Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions changelog.d/fixed-18916-stale-handoff-reason-label.md
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
- Workflow dispatch: a reason replayed from the hand-off ledger now carries its age and the hand-off session that decided it (`reason_at`, `reason_age`, `reason_session`) in the "item not handed off" log line and the Settings "not started" display, and is marked stale once a newer hand-off of the same item exists, so an old decline is no longer read as a new refusal (#18916).
2 changes: 1 addition & 1 deletion dashboard/openapi.json
Original file line number Diff line number Diff line change
Expand Up @@ -40617,7 +40617,7 @@
},
"dispatch": {
"type": "array",
"description": "Every bound repository's profiles: repo, profile, agent, source, mode, needs, pinned, disabled, problem (why nothing fills it), states, candidates (each pinnable agent with its mode and whether it may do what the profile needs), not_started (hand-offs an agent declined or did not act on)",
"description": "Every bound repository's profiles: repo, profile, agent, source, mode, needs, pinned, disabled, problem (why nothing fills it), states, candidates (each pinnable agent with its mode and whether it may do what the profile needs), not_started (hand-offs an agent declined or did not act on, each with reason_at, reason_age, reason_session and stale: true once a newer hand-off of the item exists, so the reason is history and not the current state)",
"items": {
"type": "object"
}
Expand Down
5 changes: 3 additions & 2 deletions src/cmd/hive/workflow_dispatch.go
Original file line number Diff line number Diff line change
Expand Up @@ -323,8 +323,9 @@ func buildWorkflowDispatchKicks(cfg *config.Config, rt *workflowDispatchRuntime,
})
for _, s := range skips {
if logger != nil && s.Reason != scheduler.WorkflowSkipDone && s.Reason != scheduler.WorkflowSkipNoReply {
logger.Info("workflow dispatch: item not handed off", "item", s.Ref, "profile", s.Profile, "reason", s.Reason,
"problem", problems[s.Ref], "fix", workflowDispatchFix(s.Profile))
reason, prov := workflowSkipReasonLog(s, dlog, now)
logger.Info("workflow dispatch: item not handed off", append([]any{"item", s.Ref, "profile", s.Profile, "reason", reason,
"problem", problems[s.Ref], "fix", workflowDispatchFix(s.Profile)}, prov...)...)
}
}
var out []workflowDispatchKick
Expand Down
8 changes: 6 additions & 2 deletions src/cmd/hive/workflow_dispatch_handoff.go
Original file line number Diff line number Diff line change
Expand Up @@ -228,15 +228,19 @@ func (rt *workflowDispatchRuntime) notStarted(cfg *config.Config, logger *slog.L
rt.mu.Lock()
seen := rt.seen
rt.mu.Unlock()
dlog := rt.dispatchLog(cfg, logger)
now := time.Now()
for _, e := range entries {
if !seen[workflowHandoffSeenKey(e.Ref, e.Profile, e.State)] {
continue
}
repo, number := splitWorkflowRef(e.Ref)
out = append(out, dashboard.WorkflowDispatchHandoff{
h := dashboard.WorkflowDispatchHandoff{
Ref: e.Ref, Repo: qualifyClaimRepo(cfg.Project.Org, repo), Number: number, Profile: e.Profile, State: e.State,
Agent: e.Agent, Reason: e.Reason, At: e.At, Attempts: e.Attempts, Retrying: e.Retryable(), Next: scheduler.WorkflowHandoffNext(e),
})
}
workflowHandoffReasonOrigin(&h, e, dlog, now)
out = append(out, h)
}
return out
}
Expand Down
45 changes: 45 additions & 0 deletions src/cmd/hive/workflow_dispatch_reason.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,45 @@
package main

import (
"time"

"github.com/hivecommons/hive/pkg/dashboard"
"github.com/hivecommons/hive/pkg/scheduler"
)

// workflowSkipReasonLog is the reason and provenance attributes of a skipped
// item's log line. A reason replayed from the ledger carries its age, the
// session that decided it and whether a newer hand-off has made it stale,
// so a decline from a session that is over is never read as a new refusal
// (hivecommons/hive#18916). Every other skip is returned unchanged.
func workflowSkipReasonLog(s scheduler.WorkflowDispatchSkip, dlog *scheduler.WorkflowDispatchLog, now time.Time) (reason string, attrs []any) {
reason = s.Reason
if s.Replayed == nil {
return reason, nil
}
o := scheduler.ReplayedReasonOrigin(*s.Replayed, now, dlog.Superseded(*s.Replayed))
if o.Stale {
reason = "stale (not current): " + reason
}
attrs = []any{"reason_replayed", true, "reason_age", o.Age, "reason_session", o.Session, "reason_stale", o.Stale}
if !o.At.IsZero() {
attrs = append(attrs, "reason_at", o.At.UTC().Format(time.RFC3339))
}
return reason, attrs
}

// workflowHandoffReasonOrigin fills the provenance of a not-started
// hand-off's reason on its dashboard record. A stale reason is no longer the
// item's state, so it never retries and its next step says so.
func workflowHandoffReasonOrigin(h *dashboard.WorkflowDispatchHandoff, e scheduler.WorkflowDispatchEntry, dlog *scheduler.WorkflowDispatchLog, now time.Time) {
o := scheduler.ReplayedReasonOrigin(e, now, dlog.Superseded(e))
h.ReasonAge, h.ReasonSession, h.Stale = o.Age, o.Session, o.Stale
if !o.At.IsZero() {
at := o.At
h.ReasonAt = &at
}
if o.Stale {
h.Retrying = false
h.Next = "a newer hand-off of this item exists; this decline is history, not its state now"
}
}
47 changes: 47 additions & 0 deletions src/cmd/hive/workflow_dispatch_reason_test.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,47 @@
package main

import (
"strings"
"testing"
"time"

"github.com/hivecommons/hive/pkg/scheduler"
)

func TestSkipReasonLogLabelsAReplayedDecline(t *testing.T) {
at := time.Date(2026, 11, 17, 1, 0, 0, 0, time.UTC)
now := at.Add(5 * time.Hour)
dlog, _ := scheduler.OpenWorkflowDispatchLog("")
decided := at.Add(time.Minute)
old := scheduler.WorkflowDispatchEntry{Key: "a", Ref: "o/r#7", Agent: "quality", At: at, Status: scheduler.WorkflowHandoffNotStarted,
Reason: "quality declined the hand-off: old text", ReasonAt: &decided, ReasonSession: "quality@2026-11-17T01:00:00Z"}
_ = dlog.Record(old)
skip := scheduler.WorkflowDispatchSkip{Ref: "o/r#7", Reason: scheduler.WorkflowSkipNotStarted + ": " + old.Reason, Replayed: &old}

reason, attrs := workflowSkipReasonLog(skip, dlog, now)
if strings.HasPrefix(reason, "stale") || !hasAttr(attrs, "reason_stale", false) || !hasAttr(attrs, "reason_session", "quality@2026-11-17T01:00:00Z") || !hasAttr(attrs, "reason_age", "4h 59m") {
t.Fatalf("current decline mislabelled: %q %v", reason, attrs)
}

_ = dlog.Record(scheduler.WorkflowDispatchEntry{Key: "b", Ref: "o/r#7", Agent: "writer", At: at.Add(2 * time.Hour), Status: scheduler.WorkflowHandoffPending})
reason, attrs = workflowSkipReasonLog(skip, dlog, now)
if !strings.HasPrefix(reason, "stale (not current): ") || !hasAttr(attrs, "reason_stale", true) {
t.Fatalf("a stale decline shown as current: %q %v", reason, attrs)
}
}

func TestSkipReasonLogLeavesOtherSkipsAlone(t *testing.T) {
reason, attrs := workflowSkipReasonLog(scheduler.WorkflowDispatchSkip{Ref: "o/r#1", Reason: scheduler.WorkflowSkipNoAgent}, nil, time.Now())
if reason != scheduler.WorkflowSkipNoAgent || attrs != nil {
t.Fatalf("%q %v", reason, attrs)
}
}

func hasAttr(attrs []any, key string, want any) bool {
for i := 0; i+1 < len(attrs); i += 2 {
if attrs[i] == key && attrs[i+1] == want {
return true
}
}
return false
}
2 changes: 1 addition & 1 deletion src/docs/api-reference/configuration.md
Original file line number Diff line number Diff line change
Expand Up @@ -129,4 +129,4 @@ Part of the [Dashboard REST API reference](../api-reference.md); see that page f
| `PUT` | `/api/config/governor/inference-auth` | Owner only | Governor Inference Auth Set | `pkg/dashboard/api.go:279` |
| `PUT` | `/api/workflows/enabled` | Owner only | Turn model-based stage derivation (`workflow.enabled`, [#17620](https://github.com/hivecommons/hive/issues/17620)) on or off from the dashboard, for hosted hives with no `hive.yaml` access. Body `{enabled: bool}`; persists `hive.yaml`; the stage engine and tracker read the live flag so it applies on the next derivation pass without a restart. Turning on also provisions every bound repository's model labels now (`warnings[]` lists repositories that could not be provisioned; the next sweep retries). Returns `{enabled, changed, bindings[], warnings?[]}`. Audited `workflow_enabled` / `workflow_disabled`; `400` on a non-boolean body | `pkg/dashboard/api_workflows.go:29` |
| `POST` | `/api/workflows/dispatch` | Owner only | Send a model-owned item to its agent profile: the stage tracker's **Send to *profile*** on a row whose bound model hands its current state to a profile ([cncf/techdocs#395](https://github.com/cncf/techdocs/issues/395): Accepted → `techdocs-drafter`, Drafting → `techdocs-verifier`). Body `{repo, number}`. Reads the item fresh, resolves the agent (`workflow.dispatch.profiles.<profile>.agent`, then the default order ending at the hive's issue worker or reviewer, at every step only an agent whose mode lets it do what the profile needs, [#18749](https://github.com/hivecommons/hive/issues/18749); a profile disabled for automatic dispatch still resolves), takes the agent claim on an issue first, kicks the agent, and records the hand-off as pending once the kick lands so the automatic pass does not repeat it; a later pass marks it not started if the agent declines or ends its turn without the deliverable. Returns `{status: "sent", ref, model, state, profile, agent, result}`. Audited `workflow_dispatch`; `404` when the model does not hand the state to a profile, `409` when no agent fills it (the message gives the reason, for example that no agent on the hive may open pull requests in the repository, and names the Settings → Repos picker), someone else holds the claim, or the agent is busy | `pkg/dashboard/api_workflows.go:30` |
| `PUT` | `/api/workflows/dispatch/profiles` | Owner only | Pick the hive agent a bound model's profile is handed to ([#18690](https://github.com/hivecommons/hive/issues/18690)): the agent picker on a repository's workflow row in Settings → Repos. Body `{profile, agent}`; an empty `agent` clears the pin so the profile resolves by default again. Persists `workflow.dispatch.profiles.<profile>.agent` in `hive.yaml` (the profile's `prompt_template` and `disabled` are kept); the next scheduler pass reads the live config, so no restart is needed. `agent` must be an enabled agent that is not a replica (`400` otherwise). Returns `{changed, profile, agent, dispatch, agents}`, where `dispatch` lists every bound repository's profiles as `{repo, profile, agent, source, mode, needs, pinned, disabled, problem, states, candidates, not_started}` (`problem` is why nothing fills the profile, including a pin to an agent whose mode does not let it do the profile's work; `candidates` lists each pinnable agent as `{agent, mode, qualifies, reason}`; `not_started` lists the hand-offs an agent declined or did not act on while their item still waits, as `{ref, repo, number, profile, state, agent, reason, at, attempts, retrying, next}`, [#18749](https://github.com/hivecommons/hive/issues/18749)) and `agents` the agents that can be picked; `GET /api/workflows` and `PUT /api/workflows/bindings` carry the same two fields. Audited `workflow_dispatch_agent` | `pkg/dashboard/api_workflows.go:31` |
| `PUT` | `/api/workflows/dispatch/profiles` | Owner only | Pick the hive agent a bound model's profile is handed to ([#18690](https://github.com/hivecommons/hive/issues/18690)): the agent picker on a repository's workflow row in Settings → Repos. Body `{profile, agent}`; an empty `agent` clears the pin so the profile resolves by default again. Persists `workflow.dispatch.profiles.<profile>.agent` in `hive.yaml` (the profile's `prompt_template` and `disabled` are kept); the next scheduler pass reads the live config, so no restart is needed. `agent` must be an enabled agent that is not a replica (`400` otherwise). Returns `{changed, profile, agent, dispatch, agents}`, where `dispatch` lists every bound repository's profiles as `{repo, profile, agent, source, mode, needs, pinned, disabled, problem, states, candidates, not_started}` (`problem` is why nothing fills the profile, including a pin to an agent whose mode does not let it do the profile's work; `candidates` lists each pinnable agent as `{agent, mode, qualifies, reason}`; `not_started` lists the hand-offs an agent declined or did not act on while their item still waits, as `{ref, repo, number, profile, state, agent, reason, at, attempts, retrying, next, reason_at, reason_age, reason_session, stale}` (`reason_at`, `reason_age` and `reason_session` say when and in which hand-off session the reason was decided, and `stale` is true once a newer hand-off of the item exists, so the reason is history and not the item's state now, [#18916](https://github.com/hivecommons/hive/issues/18916)), [#18749](https://github.com/hivecommons/hive/issues/18749)) and `agents` the agents that can be picked; `GET /api/workflows` and `PUT /api/workflows/bindings` carry the same two fields. Audited `workflow_dispatch_agent` | `pkg/dashboard/api_workflows.go:31` |
12 changes: 12 additions & 0 deletions src/docs/design/workflow-models.md
Original file line number Diff line number Diff line change
Expand Up @@ -804,6 +804,18 @@ profile (`dispatch[].not_started`), and the tracker payload carries them per rep
and the item's Activity Monitor row (`not started: <profile>` badge) both show them
(`Dependencies.WorkflowDispatchHandoffs`).

**A replayed reason is labelled with where it came from** (hivecommons/hive#18916). The ledger
keeps the last reason an agent gave, and the planner prints it on every pass while the item
waits, so the text can outlive the session that wrote it. Each record therefore stores
`reason_at` (when the reason was decided) and `reason_session` (the hand-off that decided it:
the agent and the delivery time, ids only). The `workflow dispatch: item not handed off` line
and the `not_started` entries carry `reason_at`, `reason_age` and `reason_session`, and a reason
is marked **stale** (`reason_stale` in the log, `stale` in the API) once a newer hand-off of the
same item exists under any key. A stale decline is history: the dashboard shows it as an earlier
hand-off's decline, the log line says `stale (not current)`, and it never counts as the item's
state now. A record written before provenance was kept shows its session as `unknown (before
provenance was recorded)` and takes its age from the time it was last reviewed.

**Which agent fills a profile.** `Config.ResolveWorkflowDispatch(profile, need, manual)` is the
one resolver (hivecommons/hive#18690). Every step accepts only an enabled agent that may do
what the profile needs in the item's repository (hivecommons/hive#18749,
Expand Down
16 changes: 15 additions & 1 deletion src/pkg/dashboard/api_workflows_dispatch_handoffs.go
Original file line number Diff line number Diff line change
Expand Up @@ -38,6 +38,14 @@ type WorkflowDispatchHandoff struct {
Retrying bool `json:"retrying"`
// Next says, in a few words, what happens now.
Next string `json:"next"`
// ReasonAt, ReasonAge and ReasonSession say when and in which hand-off
// session Reason was decided (session is ids only); Stale is true once a
// newer hand-off of the item exists, so Reason is history rather than
// the item's state now (hivecommons/hive#18916).
ReasonAt *time.Time `json:"reason_at,omitempty"`
ReasonAge string `json:"reason_age,omitempty"`
ReasonSession string `json:"reason_session,omitempty"`
Stale bool `json:"stale"`
}

// StageTrackerWorkflowHandoff is a not-started hand-off on a tracker row.
Expand All @@ -48,6 +56,11 @@ type StageTrackerWorkflowHandoff struct {
Reason string `json:"reason"`
Retrying bool `json:"retrying"`
Next string `json:"next,omitempty"`
// ReasonAt, ReasonAge, ReasonSession and Stale: see WorkflowDispatchHandoff.
ReasonAt *time.Time `json:"reason_at,omitempty"`
ReasonAge string `json:"reason_age,omitempty"`
ReasonSession string `json:"reason_session,omitempty"`
Stale bool `json:"stale"`
}

// workflowDispatchHandoffs is the live not-started list, never nil.
Expand Down Expand Up @@ -99,7 +112,8 @@ func attachWorkflowHandoffsToTracker(w *StageTrackerWorkflows, handoffs []Workfl
if block.Handoffs == nil {
block.Handoffs = map[string]StageTrackerWorkflowHandoff{}
}
block.Handoffs[strconv.Itoa(h.Number)] = StageTrackerWorkflowHandoff{Profile: h.Profile, State: h.State, Agent: h.Agent, Reason: h.Reason, Retrying: h.Retrying, Next: h.Next}
block.Handoffs[strconv.Itoa(h.Number)] = StageTrackerWorkflowHandoff{Profile: h.Profile, State: h.State, Agent: h.Agent, Reason: h.Reason, Retrying: h.Retrying, Next: h.Next,
ReasonAt: h.ReasonAt, ReasonAge: h.ReasonAge, ReasonSession: h.ReasonSession, Stale: h.Stale}
w.Repos[repo] = block
}
}
Expand Down
4 changes: 2 additions & 2 deletions src/pkg/dashboard/api_workflows_dispatch_handoffs_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -102,7 +102,7 @@ func TestWorkflowDispatchHandoffUI(t *testing.T) {
script := `const assert = require('assert');
const esc = s => String(s).replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/"/g, '&quot;');
` + jsConstLine(t, html, "WORKFLOW_DISPATCH_SOURCE_WORD") + "\n" +
jsFunc(t, html, "workflowDispatchProfileView") + jsFunc(t, html, "renderRepoWorkflowProfileRows") +
jsFunc(t, html, "workflowHandoffNote") + jsFunc(t, html, "workflowDispatchProfileView") + jsFunc(t, html, "renderRepoWorkflowProfileRows") +
jsFunc(t, html, "stageTrackerWorkflowOf") + jsFunc(t, html, "stageTrackerWorkflowDispatchOf") +
jsFunc(t, html, "stageTrackerWorkflowGapOf") + jsFunc(t, html, "stageTrackerWorkflowGapHtml") + `
const agents = ['quality', 'scanner'];
Expand All @@ -122,7 +122,7 @@ assert.strictEqual(v.options[2].label, 'scanner (ADVISORY, cannot do this)');
assert.strictEqual(v.options[2].disabled, true);
assert.ok(v.options[2].title.indexOf('scanner may not open pull requests in cncf/techdocs') === 0, v.options[2].title);
assert.strictEqual(v.warning, '');
assert.deepStrictEqual(v.stalled, ['Hand-off of cncf/techdocs#395 not started: scanner declined the hand-off: my session is advisory. The hive hands it to another agent that may do the work, if there is one.']);
assert.deepStrictEqual(v.stalled, ['Hand-off of cncf/techdocs#395 not started: scanner declined the hand-off: my session is advisory. Decided at an unknown time in session unknown (before provenance was recorded). The hive hands it to another agent that may do the work, if there is one.']);

// A pin to an agent that may not do the work stays selectable (it is the
// current value) and the row warns.
Expand Down
18 changes: 18 additions & 0 deletions src/pkg/dashboard/static-src/js/config-workflows-handoff.js
Original file line number Diff line number Diff line change
@@ -0,0 +1,18 @@
// The Settings → Repos line for a hand-off an agent did not start
// (hivecommons/hive#18749), with where its reason came from
// (hivecommons/hive#18916). The reason is text an agent wrote in a session
// that may be over: it carries its age and session, and once a newer
// hand-off of the item exists (`stale`) it is shown as an earlier
// decline, never as the item's current state. Pure: the caller escapes
// the result when it puts it in markup.
function workflowHandoffNote(h, profile) {
const ref = String(h && h.ref || '');
const reason = String(h && h.reason || 'the agent did not act');
const age = h && h.reason_age ? String(h.reason_age) + ' ago' : 'at an unknown time';
const session = h && h.reason_session ? String(h.reason_session) : 'unknown (before provenance was recorded)';
const origin = 'Decided ' + age + ' in session ' + session + '.';
if (h && h.stale) {
return 'Earlier hand-off of ' + ref + ' (stale): ' + reason + '. ' + origin + ' A newer hand-off of this item exists, so this is history, not its state now.';
}
return 'Hand-off of ' + ref + ' not started: ' + reason + '. ' + origin + ' ' + (h && h.retrying ? 'The hive hands it to another agent that may do the work, if there is one.' : 'It waits for an owner: use Send to ' + String(profile) + ' on the item\'s row in the Activity Monitor.');
}
2 changes: 1 addition & 1 deletion src/pkg/dashboard/static-src/js/config-workflows.js
Original file line number Diff line number Diff line change
Expand Up @@ -112,7 +112,7 @@
const warning = d.problem ? 'Not handed off: ' + d.problem + '. Items in this profile\'s states wait until an agent that may do the work is picked.' : '';
const how = pinned ? 'pinned' : (WORKFLOW_DISPATCH_SOURCE_WORD[String(d.source || '')] || '');
const note = warning ? '' : (agent ? 'handed to ' + agent + (how ? ' (' + how + ')' : '') : '') + (d.disabled ? ' · automatic hand-off off, manual send only' : '');
const stalled = (Array.isArray(d.not_started) ? d.not_started : []).map(h => 'Hand-off of ' + String(h.ref || '') + ' not started: ' + String(h.reason || 'the agent did not act') + '. ' + (h.retrying ? 'The hive hands it to another agent that may do the work, if there is one.' : 'It waits for an owner: use Send to ' + String(d.profile) + ' on the item\'s row in the Activity Monitor.'));
const stalled = (Array.isArray(d.not_started) ? d.not_started : []).map(h => workflowHandoffNote(h, d.profile));
return { profile: String(d.profile), options, warning, note, stalled };
}

Expand Down
Loading
Loading