From 00e2bfb75936aff28107d8c08de8f5b79e7f59d6 Mon Sep 17 00:00:00 2001 From: Andy Anderson Date: Wed, 18 Nov 2026 00:21:39 -0500 Subject: [PATCH 1/2] =?UTF-8?q?=F0=9F=90=9B=20Label=20the=20age,=20session?= =?UTF-8?q?=20and=20staleness=20of=20a=20replayed=20hand-off=20decline=20(?= =?UTF-8?q?#18916)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Andy Anderson --- .../fixed-18916-stale-handoff-reason-label.md | 1 + dashboard/openapi.json | 2 +- src/cmd/hive/workflow_dispatch.go | 5 +- src/cmd/hive/workflow_dispatch_handoff.go | 8 +- src/cmd/hive/workflow_dispatch_reason.go | 45 ++++++ src/cmd/hive/workflow_dispatch_reason_test.go | 47 +++++++ src/docs/api-reference/configuration.md | 2 +- src/docs/design/workflow-models.md | 12 ++ .../api_workflows_dispatch_handoffs.go | 16 ++- .../static-src/js/config-workflows-handoff.js | 18 +++ .../static-src/js/config-workflows.js | 2 +- src/pkg/dashboard/static-src/manifest.txt | 1 + src/pkg/dashboard/static/index.html | 20 ++- .../workflow_handoff_stale_reason.test.js | 31 ++++ src/pkg/scheduler/workflow_dispatch.go | 10 +- .../scheduler/workflow_dispatch_handoff.go | 4 + src/pkg/scheduler/workflow_dispatch_reason.go | 132 ++++++++++++++++++ .../workflow_dispatch_reason_test.go | 73 ++++++++++ 18 files changed, 419 insertions(+), 10 deletions(-) create mode 100644 changelog.d/fixed-18916-stale-handoff-reason-label.md create mode 100644 src/cmd/hive/workflow_dispatch_reason.go create mode 100644 src/cmd/hive/workflow_dispatch_reason_test.go create mode 100644 src/pkg/dashboard/static-src/js/config-workflows-handoff.js create mode 100644 src/pkg/dashboard/workflow_handoff_stale_reason.test.js create mode 100644 src/pkg/scheduler/workflow_dispatch_reason.go create mode 100644 src/pkg/scheduler/workflow_dispatch_reason_test.go diff --git a/changelog.d/fixed-18916-stale-handoff-reason-label.md b/changelog.d/fixed-18916-stale-handoff-reason-label.md new file mode 100644 index 0000000000..c30ded37c1 --- /dev/null +++ b/changelog.d/fixed-18916-stale-handoff-reason-label.md @@ -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). diff --git a/dashboard/openapi.json b/dashboard/openapi.json index 4a685adee4..be61f8658c 100644 --- a/dashboard/openapi.json +++ b/dashboard/openapi.json @@ -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" } diff --git a/src/cmd/hive/workflow_dispatch.go b/src/cmd/hive/workflow_dispatch.go index 5bd9047914..2bff699b4a 100644 --- a/src/cmd/hive/workflow_dispatch.go +++ b/src/cmd/hive/workflow_dispatch.go @@ -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 diff --git a/src/cmd/hive/workflow_dispatch_handoff.go b/src/cmd/hive/workflow_dispatch_handoff.go index 97dfe6eb03..76bd12ef19 100644 --- a/src/cmd/hive/workflow_dispatch_handoff.go +++ b/src/cmd/hive/workflow_dispatch_handoff.go @@ -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 } diff --git a/src/cmd/hive/workflow_dispatch_reason.go b/src/cmd/hive/workflow_dispatch_reason.go new file mode 100644 index 0000000000..f4124dcebc --- /dev/null +++ b/src/cmd/hive/workflow_dispatch_reason.go @@ -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" + } +} diff --git a/src/cmd/hive/workflow_dispatch_reason_test.go b/src/cmd/hive/workflow_dispatch_reason_test.go new file mode 100644 index 0000000000..4311b376a4 --- /dev/null +++ b/src/cmd/hive/workflow_dispatch_reason_test.go @@ -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 +} diff --git a/src/docs/api-reference/configuration.md b/src/docs/api-reference/configuration.md index c6547fe8d5..2b2d1c6f04 100644 --- a/src/docs/api-reference/configuration.md +++ b/src/docs/api-reference/configuration.md @@ -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..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..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..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` | diff --git a/src/docs/design/workflow-models.md b/src/docs/design/workflow-models.md index c291cabb01..bf76a8a24a 100644 --- a/src/docs/design/workflow-models.md +++ b/src/docs/design/workflow-models.md @@ -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: ` 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, diff --git a/src/pkg/dashboard/api_workflows_dispatch_handoffs.go b/src/pkg/dashboard/api_workflows_dispatch_handoffs.go index afc62db093..297fe35c91 100644 --- a/src/pkg/dashboard/api_workflows_dispatch_handoffs.go +++ b/src/pkg/dashboard/api_workflows_dispatch_handoffs.go @@ -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. @@ -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. @@ -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 } } diff --git a/src/pkg/dashboard/static-src/js/config-workflows-handoff.js b/src/pkg/dashboard/static-src/js/config-workflows-handoff.js new file mode 100644 index 0000000000..670d8044f2 --- /dev/null +++ b/src/pkg/dashboard/static-src/js/config-workflows-handoff.js @@ -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, ' + origin + '): ' + reason + '. 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.'); + } diff --git a/src/pkg/dashboard/static-src/js/config-workflows.js b/src/pkg/dashboard/static-src/js/config-workflows.js index e9ad4612d8..e52ae9bb9a 100644 --- a/src/pkg/dashboard/static-src/js/config-workflows.js +++ b/src/pkg/dashboard/static-src/js/config-workflows.js @@ -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 }; } diff --git a/src/pkg/dashboard/static-src/manifest.txt b/src/pkg/dashboard/static-src/manifest.txt index 476481f5c6..cd95845675 100644 --- a/src/pkg/dashboard/static-src/manifest.txt +++ b/src/pkg/dashboard/static-src/manifest.txt @@ -174,6 +174,7 @@ js/config-hub.js js/config-agent.js js/config-governor.js js/config-workflows.js +js/config-workflows-handoff.js js/config-workflows-library.js js/config-workflows-editor.js js/config-workflows-ingest-sources.js diff --git a/src/pkg/dashboard/static/index.html b/src/pkg/dashboard/static/index.html index 662f272a3b..6caa02a87a 100644 --- a/src/pkg/dashboard/static/index.html +++ b/src/pkg/dashboard/static/index.html @@ -72851,7 +72851,7 @@

Agent Watchdog

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 }; } @@ -72922,6 +72922,24 @@

Agent Watchdog

} renderConfigTab('Repos'); } + // 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, ' + origin + '): ' + reason + '. 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.'); + } // Settings → Workflows (hivecommons/hive#17620, RFC phase 3). // // The spoke's home for workflow models: a Library of every stored model diff --git a/src/pkg/dashboard/workflow_handoff_stale_reason.test.js b/src/pkg/dashboard/workflow_handoff_stale_reason.test.js new file mode 100644 index 0000000000..d5db86be83 --- /dev/null +++ b/src/pkg/dashboard/workflow_handoff_stale_reason.test.js @@ -0,0 +1,31 @@ +// hivecommons/hive#18916: a replayed hand-off decline carries its age and +// session, and a stale one never reads as the item's current state. +const test = require('node:test'); +const assert = require('node:assert'); +const fs = require('node:fs'); +const path = require('node:path'); + +const src = fs.readFileSync(path.join(__dirname, 'static-src', 'js', 'config-workflows-handoff.js'), 'utf8'); +// The file is one pure function with no dependency on the page: no stubs. +const workflowHandoffNote = new Function(src + '\nreturn workflowHandoffNote;')(); + +test('a current decline names its age and session and what happens next', () => { + const n = workflowHandoffNote({ ref: 'o/r#7', reason: 'q declined the hand-off: no', reason_age: '3h 5m', reason_session: 'q@2026-11-17T01:00:00Z', retrying: true, stale: false }, 'writer'); + assert.match(n, /not started: q declined the hand-off: no/); + assert.match(n, /decided 3h 5m ago in session q@2026-11-17T01:00:00Z/); + assert.match(n, /another agent/); + assert.doesNotMatch(n, /stale/); +}); + +test('a stale decline is history and never shown as not started', () => { + const n = workflowHandoffNote({ ref: 'o/r#7', reason: 'old text', reason_age: '9h 0m', reason_session: 's1', stale: true, retrying: true }, 'writer'); + assert.match(n, /^Earlier hand-off of o\/r#7 \(stale/); + assert.doesNotMatch(n, /not started/); + assert.doesNotMatch(n, /Send to/); + assert.match(n, /not its state now/); +}); + +test('a record from before provenance was kept says so', () => { + const n = workflowHandoffNote({ ref: 'o/r#1', reason: 'x' }, 'p'); + assert.match(n, /at an unknown time in session unknown \(before provenance was recorded\)/); +}); diff --git a/src/pkg/scheduler/workflow_dispatch.go b/src/pkg/scheduler/workflow_dispatch.go index 2d6b96bbdb..47e9a596a5 100644 --- a/src/pkg/scheduler/workflow_dispatch.go +++ b/src/pkg/scheduler/workflow_dispatch.go @@ -125,6 +125,9 @@ type WorkflowDispatchSkip struct { // Profile is the model profile the item is handed to. Profile string Reason string + // Replayed is the not-started hand-off whose stored reason Reason + // repeats (WorkflowSkipNotStarted); nil for any other skip. + Replayed *WorkflowDispatchEntry } // Skip reasons. @@ -225,7 +228,7 @@ func PlanWorkflowDispatch(items []github.WorkflowDispatch, deps WorkflowDispatch agent, ok = deps.RetryAgent(d, prior.Tried) } if !ok { - skips = append(skips, WorkflowDispatchSkip{Ref: ref, Profile: d.Target.Profile, Reason: WorkflowSkipNotStarted + ": " + prior.Reason}) + skips = append(skips, WorkflowDispatchSkip{Ref: ref, Profile: d.Target.Profile, Reason: WorkflowSkipNotStarted + ": " + prior.Reason, Replayed: prior}) continue } if deps.Eligible != nil && !deps.Eligible(agent) { @@ -499,6 +502,11 @@ type WorkflowDispatchEntry struct { Status string `json:"status,omitempty"` // Reason says why a hand-off was not started. Reason string `json:"reason,omitempty"` + // ReasonAt is when Reason was decided and ReasonSession the hand-off + // session that decided it (WorkflowHandoffSession); both empty on a + // record written before provenance was kept. + ReasonAt *time.Time `json:"reason_at,omitempty"` + ReasonSession string `json:"reason_session,omitempty"` // Attempts counts the hand-offs of this key to an agent that could do // the work; Tried names those agents. A hand-off to an agent that may // not do what the profile needs counts for neither. diff --git a/src/pkg/scheduler/workflow_dispatch_handoff.go b/src/pkg/scheduler/workflow_dispatch_handoff.go index d6cc4c4a11..411aa266c1 100644 --- a/src/pkg/scheduler/workflow_dispatch_handoff.go +++ b/src/pkg/scheduler/workflow_dispatch_handoff.go @@ -103,6 +103,7 @@ func ReviewWorkflowHandoff(e WorkflowDispatchEntry, ev WorkflowHandoffEvidence) } notStarted := func(reason string, counts bool) (WorkflowDispatchEntry, bool) { e.Status, e.Reason = WorkflowHandoffNotStarted, reason + e = stampReason(e, ev.Now) if counts { if e.Attempts < 1 { e.Attempts = 1 @@ -122,6 +123,7 @@ func ReviewWorkflowHandoff(e WorkflowDispatchEntry, ev WorkflowHandoffEvidence) } started := func() (WorkflowDispatchEntry, bool) { e.Status, e.Reason = WorkflowHandoffStarted, "" + e = clearReason(e) at := ev.Now e.CheckedAt = &at return e, true @@ -157,6 +159,7 @@ func ReviewWorkflowHandoff(e WorkflowDispatchEntry, ev WorkflowHandoffEvidence) // person's choice. func WorkflowHandoffLeftState(e WorkflowDispatchEntry, now time.Time) WorkflowDispatchEntry { e.Status, e.Reason = WorkflowHandoffStarted, "" + e = clearReason(e) e.CheckedAt = &now return e } @@ -166,6 +169,7 @@ func WorkflowHandoffLeftState(e WorkflowDispatchEntry, now time.Time) WorkflowDi // hand-offs before it carried over. func NextWorkflowDispatchEntry(e WorkflowDispatchEntry, prior *WorkflowDispatchEntry) WorkflowDispatchEntry { e.Status, e.Reason, e.CheckedAt = WorkflowHandoffPending, "", nil + e = clearReason(e) e.Attempts, e.Tried = 1, []string{e.Agent} if prior != nil { e.Attempts = prior.Attempts + 1 diff --git a/src/pkg/scheduler/workflow_dispatch_reason.go b/src/pkg/scheduler/workflow_dispatch_reason.go new file mode 100644 index 0000000000..86455bcdfb --- /dev/null +++ b/src/pkg/scheduler/workflow_dispatch_reason.go @@ -0,0 +1,132 @@ +package scheduler + +import ( + "fmt" + "time" +) + +// Where a replayed reason came from. +// +// The hand-off ledger keeps the last reason an agent gave for not starting an +// item, and the planner prints it on every pass while the item waits. The +// text outlives the session that wrote it, so a line printed hours later reads +// as a new refusal. Each reason therefore carries when it was decided +// (reason_at), which hand-off session decided it (reason_session), and, at +// print time, its age and whether a newer hand-off of the same item has since +// replaced the state it described (stale). + +// ReasonSessionUnknown labels a reason written before provenance was +// recorded. +const ReasonSessionUnknown = "unknown (before provenance was recorded)" + +// WorkflowHandoffSession names the hand-off a record belongs to: the agent +// and the delivery time. It holds ids only, never agent text. +func WorkflowHandoffSession(e WorkflowDispatchEntry) string { + if e.Agent == "" || e.At.IsZero() { + return "" + } + return e.Agent + "@" + e.At.UTC().Format(time.RFC3339) +} + +// stampReason records when and in which hand-off e's reason was decided. +func stampReason(e WorkflowDispatchEntry, at time.Time) WorkflowDispatchEntry { + e.ReasonAt = &at + e.ReasonSession = WorkflowHandoffSession(e) + return e +} + +// clearReason drops the provenance of a reason that no longer applies. +func clearReason(e WorkflowDispatchEntry) WorkflowDispatchEntry { + e.ReasonAt, e.ReasonSession = nil, "" + return e +} + +// ReasonOrigin says where a replayed reason came from. +type ReasonOrigin struct { + // At is when the reason was decided; zero when unknown. + At time.Time + // Age is how long ago, in a few words ("3h 5m"); empty when At is + // unknown. + Age string + // Session is the hand-off that decided it, or ReasonSessionUnknown. + Session string + // Stale is true once a newer hand-off of the same item exists: the + // reason describes a session that is over, not the item's state now. + Stale bool +} + +// ReasonDecidedAt is when e's reason was decided: the recorded reason time, +// else when the hand-off was last reviewed, else when it was delivered (a +// record written before provenance was kept). +func (e WorkflowDispatchEntry) ReasonDecidedAt() time.Time { + switch { + case e.ReasonAt != nil: + return *e.ReasonAt + case e.CheckedAt != nil: + return *e.CheckedAt + } + return e.At +} + +// ReplayedReasonOrigin is the origin of e's reason as of now. superseded is +// whether a newer hand-off of the item exists (WorkflowDispatchLog.Superseded). +func ReplayedReasonOrigin(e WorkflowDispatchEntry, now time.Time, superseded bool) ReasonOrigin { + o := ReasonOrigin{Session: e.ReasonSession, Stale: superseded, At: e.ReasonDecidedAt()} + if o.Session == "" { + o.Session = ReasonSessionUnknown + } + if !o.At.IsZero() { + o.Age = HandoffAge(now.Sub(o.At)) + } + return o +} + +// Label renders the origin for a log line or a tooltip: no agent text. +func (o ReasonOrigin) Label() string { + s := "decided" + if o.Age != "" { + s += " " + o.Age + " ago" + } else { + s += " at an unknown time" + } + s += " in session " + o.Session + if o.Stale { + s += "; stale, a newer hand-off of this item exists" + } + return s +} + +// HandoffAge renders d as its two largest units ("2d 3h", "3h 5m", "40s"). +func HandoffAge(d time.Duration) string { + if d < 0 { + d = 0 + } + d = d.Round(time.Second) + days, hours := int(d/(24*time.Hour)), int(d/time.Hour)%24 + mins, secs := int(d/time.Minute)%60, int(d/time.Second)%60 + switch { + case days > 0: + return fmt.Sprintf("%dd %dh", days, hours) + case hours > 0: + return fmt.Sprintf("%dh %dm", hours, mins) + case mins > 0: + return fmt.Sprintf("%dm %ds", mins, secs) + } + return fmt.Sprintf("%ds", secs) +} + +// Superseded reports whether a hand-off of the same item was delivered after +// e's reason was decided, under any key: the reason is then history, not the +// item's current state. +func (l *WorkflowDispatchLog) Superseded(e WorkflowDispatchEntry) bool { + if l == nil { + return false + } + decided := e.ReasonDecidedAt() + for _, o := range l.Entries() { + if o.Ref == e.Ref && o.Key != e.Key && o.At.After(decided) { + return true + } + } + return false +} diff --git a/src/pkg/scheduler/workflow_dispatch_reason_test.go b/src/pkg/scheduler/workflow_dispatch_reason_test.go new file mode 100644 index 0000000000..2ec462e666 --- /dev/null +++ b/src/pkg/scheduler/workflow_dispatch_reason_test.go @@ -0,0 +1,73 @@ +package scheduler + +import ( + "strings" + "testing" + "time" +) + +func TestDeclineIsStampedWithItsSession(t *testing.T) { + at := time.Date(2026, 11, 17, 1, 0, 0, 0, time.UTC) + now := at.Add(10 * time.Minute) + e := WorkflowDispatchEntry{Key: "k", Ref: "o/r#7", Agent: "quality", At: at, Status: WorkflowHandoffPending} + got, changed := ReviewWorkflowHandoff(e, WorkflowHandoffEvidence{Now: now, Declined: "stand down: no push rights"}) + if !changed || got.Status != WorkflowHandoffNotStarted { + t.Fatalf("not decided: %+v", got) + } + if got.ReasonAt == nil || !got.ReasonAt.Equal(now) || got.ReasonSession != "quality@2026-11-17T01:00:00Z" { + t.Fatalf("reason provenance not recorded: %+v", got) + } + again := NextWorkflowDispatchEntry(got, &got) + if again.ReasonAt != nil || again.ReasonSession != "" || again.Reason != "" { + t.Fatalf("a new hand-off kept the old reason's provenance: %+v", again) + } +} + +func TestReasonOriginAgeAndUnknownSession(t *testing.T) { + at := time.Date(2026, 11, 17, 1, 0, 0, 0, time.UTC) + legacy := WorkflowDispatchEntry{Key: "k", Ref: "o/r#7", At: at, Status: WorkflowHandoffNotStarted, Reason: "x"} + o := ReplayedReasonOrigin(legacy, at.Add(3*time.Hour+5*time.Minute), false) + if o.Session != ReasonSessionUnknown || o.Age != "3h 5m" || o.Stale { + t.Fatalf("legacy origin: %+v", o) + } + if strings.Contains(o.Label(), "x") && strings.Contains(o.Label(), legacy.Reason+" ") { + t.Fatalf("label repeated the reason: %q", o.Label()) + } +} + +// A stale decline is never the current state: once a newer hand-off of the +// same item exists, the older record is marked stale; a hand-off of another +// item, or an older one, does not. +func TestStaleOnlyWhenANewerHandoffOfTheSameItemExists(t *testing.T) { + at := time.Date(2026, 11, 17, 1, 0, 0, 0, time.UTC) + log, _ := OpenWorkflowDispatchLog("") + decided := at.Add(time.Hour) + old := WorkflowDispatchEntry{Key: "a", Ref: "o/r#7", Agent: "q", At: at, Status: WorkflowHandoffNotStarted, Reason: "no", ReasonAt: &decided} + other := WorkflowDispatchEntry{Key: "b", Ref: "o/r#8", Agent: "q", At: at.Add(2 * time.Hour), Status: WorkflowHandoffPending} + _ = log.RecordAll([]WorkflowDispatchEntry{old, other}) + if log.Superseded(old) { + t.Fatal("another item's hand-off made the decline stale") + } + earlier := WorkflowDispatchEntry{Key: "c", Ref: "o/r#7", Agent: "q", At: at.Add(-time.Hour), Status: WorkflowHandoffStarted} + _ = log.Record(earlier) + if log.Superseded(old) { + t.Fatal("an older hand-off made the decline stale") + } + newer := WorkflowDispatchEntry{Key: "d", Ref: "o/r#7", Agent: "w", At: at.Add(3 * time.Hour), Status: WorkflowHandoffPending} + _ = log.Record(newer) + if !log.Superseded(old) { + t.Fatal("a newer hand-off of the same item did not make the decline stale") + } + var nilLog *WorkflowDispatchLog + if nilLog.Superseded(old) { + t.Fatal("nil log reported stale") + } +} + +func TestHandoffAge(t *testing.T) { + for d, want := range map[time.Duration]string{-time.Second: "0s", 40 * time.Second: "40s", 5*time.Minute + 2*time.Second: "5m 2s", 26 * time.Hour: "1d 2h"} { + if got := HandoffAge(d); got != want { + t.Errorf("%v: %q want %q", d, got, want) + } + } +} From 96cf91b64e6ae71a33953f26ec08a48e76dd24f7 Mon Sep 17 00:00:00 2001 From: Andy Anderson Date: Wed, 18 Nov 2026 00:33:47 -0500 Subject: [PATCH 2/2] =?UTF-8?q?=F0=9F=90=9B=20Fix=20the=20hand-off=20UI=20?= =?UTF-8?q?harness=20for=20the=20stale-reason=20label=20(#18916)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Andy Anderson --- src/pkg/dashboard/api_workflows_dispatch_handoffs_test.go | 4 ++-- .../dashboard/static-src/js/config-workflows-handoff.js | 6 +++--- src/pkg/dashboard/static/index.html | 6 +++--- src/pkg/dashboard/workflow_handoff_stale_reason.test.js | 8 ++++---- 4 files changed, 12 insertions(+), 12 deletions(-) diff --git a/src/pkg/dashboard/api_workflows_dispatch_handoffs_test.go b/src/pkg/dashboard/api_workflows_dispatch_handoffs_test.go index 3eadce1fc7..7353b0b931 100644 --- a/src/pkg/dashboard/api_workflows_dispatch_handoffs_test.go +++ b/src/pkg/dashboard/api_workflows_dispatch_handoffs_test.go @@ -102,7 +102,7 @@ func TestWorkflowDispatchHandoffUI(t *testing.T) { script := `const assert = require('assert'); const esc = s => String(s).replace(/&/g, '&').replace(/Agent Watchdog 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; + const origin = 'Decided ' + age + ' in session ' + session + '.'; if (h && h.stale) { - return 'Earlier hand-off of ' + ref + ' (stale, ' + origin + '): ' + reason + '. A newer hand-off of this item exists, so this is history, not its state now.'; + 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.'); + 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.'); } // Settings → Workflows (hivecommons/hive#17620, RFC phase 3). // diff --git a/src/pkg/dashboard/workflow_handoff_stale_reason.test.js b/src/pkg/dashboard/workflow_handoff_stale_reason.test.js index d5db86be83..913fb69f84 100644 --- a/src/pkg/dashboard/workflow_handoff_stale_reason.test.js +++ b/src/pkg/dashboard/workflow_handoff_stale_reason.test.js @@ -11,15 +11,15 @@ const workflowHandoffNote = new Function(src + '\nreturn workflowHandoffNote;')( test('a current decline names its age and session and what happens next', () => { const n = workflowHandoffNote({ ref: 'o/r#7', reason: 'q declined the hand-off: no', reason_age: '3h 5m', reason_session: 'q@2026-11-17T01:00:00Z', retrying: true, stale: false }, 'writer'); - assert.match(n, /not started: q declined the hand-off: no/); - assert.match(n, /decided 3h 5m ago in session q@2026-11-17T01:00:00Z/); + assert.match(n, /not started: q declined the hand-off: no\./); + assert.match(n, /Decided 3h 5m ago in session q@2026-11-17T01:00:00Z\./); assert.match(n, /another agent/); assert.doesNotMatch(n, /stale/); }); test('a stale decline is history and never shown as not started', () => { const n = workflowHandoffNote({ ref: 'o/r#7', reason: 'old text', reason_age: '9h 0m', reason_session: 's1', stale: true, retrying: true }, 'writer'); - assert.match(n, /^Earlier hand-off of o\/r#7 \(stale/); + assert.match(n, /^Earlier hand-off of o\/r#7 \(stale\): old text\./); assert.doesNotMatch(n, /not started/); assert.doesNotMatch(n, /Send to/); assert.match(n, /not its state now/); @@ -27,5 +27,5 @@ test('a stale decline is history and never shown as not started', () => { test('a record from before provenance was kept says so', () => { const n = workflowHandoffNote({ ref: 'o/r#1', reason: 'x' }, 'p'); - assert.match(n, /at an unknown time in session unknown \(before provenance was recorded\)/); + assert.match(n, /Decided at an unknown time in session unknown \(before provenance was recorded\)\./); });