Skip to content

Correct the Status Events docs and add a status-correction tip - #980

Merged
selfcontained merged 1 commit into
mainfrom
agt_8809aa586e14/job-doc-ter-4ad99753
Aug 19, 2026
Merged

Correct the Status Events docs and add a status-correction tip#980
selfcontained merged 1 commit into
mainfrom
agt_8809aa586e14/job-doc-ter-4ad99753

Conversation

@selfcontained

Copy link
Copy Markdown
Owner

Nightly docs audit. Slice: the docs-pane Status Events section (carried over from the last two runs, run this time regardless of the diff).

Verified clean

  • The five event types match dispatch_event's enum as a set in both directions.
  • done / waiting_user / blocked are exactly what triggers browser and Slack notifications (NOTIFY_EVENT_TYPES, web-notifications.ts).
  • The activity monitor's 3-minute stale window and its exact strings — "Activity detected" / "No recent activity detected" — plus the conditional-write skip.
  • Every Activity-page claim: year heatmap, active hours, working-time stats, status breakdown chart.

Fixed

Sidebar label set. The docs described only top-level cards. #977 added describeAgentStatus, which sub agent rows and the Session details dialog use instead of the raw event label — a stopped or errored agent reads Stopped / Error there rather than a stale "Working", and one that hasn't reported yet reads Running. None of those three were in the documented set.

Startup rules claim. "Tells the agent which event types to use" only holds on the verbose branch of buildLaunchGuidance. With Settings → Agents → Launch guidance → Use short startup rules on, that rule keeps the timing and the blocked distinction but deliberately leaves the type list to the dispatch_event tool description.

Added

An ambient tip for automatic status correction. The Status Events section had no tip pointing at it, and a background loop authoring "No recent activity detected" under an agent's name is exactly what a user reads as the agent's own report. since: 0.21.9, confirmed with git merge-base --is-ancestor against both the v0.21.8 and v0.21.9 release commits. Gave the H3 an id so the tip deep-links to it.

Deferred

  • notification-settings-constants.ts describes blocked as "Agent hit an error or obstacle", and notifications.tsx mirrors it — both contradict the injected guidance. The settings UI copy is the drifted artifact, so the docs were left mirroring it and the item went to the backlog for a product decision.
  • Top-level agent cards still show the stale event label for stopped agents while sub agent rows don't; whether agent-card-status.tsx should adopt describeAgentStatus too is a code question, backlogged.
  • The dispatch_eventmetadata param stays undocumented — it is stored but never rendered anywhere user-visible. Backlog item closed.

Next run: deep-dive the Notifications section.

Deep-dive of the docs-pane Status Events section against its two
sources of truth.
Verified clean: the five event types match dispatch_event's enum as a
set in both directions, done/waiting_user/blocked are exactly what
triggers browser + Slack notifications, the activity monitor's 3-minute
window and its "Activity detected" / "No recent activity detected"
strings are exact, and every Activity-page claim (year heatmap, active
hours, working-time stats, status breakdown) still renders.
Two drifts fixed:
- The sidebar claim only described top-level cards. #977 added
describeAgentStatus, which sub agent rows and the Session details
dialog use instead of the raw event label — a stopped or errored
agent reads Stopped/Error there rather than a stale "Working", and
one that hasn't reported yet reads "Running". None of those three
labels were in the documented set.
- "Startup rules tell the agent which event types to use" is only true
on the verbose branch of buildLaunchGuidance. With Settings → Agents
→ Launch guidance → Use short startup rules on, that rule keeps the
timing and the `blocked` distinction but deliberately leaves the type
list to the dispatch_event tool description.
Also adds an ambient tip for automatic status correction (since 0.21.9,
confirmed by ancestry against the v0.21.8/v0.21.9 release commits): the
Status Events section had no tip pointing at it, and a background loop
authoring "No recent activity detected" under an agent's name is
exactly the kind of thing a user reads as the agent's own report. Gave
that H3 an id so the tip can deep-link to it.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
@selfcontained
selfcontained merged commit fea31bf into mainAug 19, 2026
1 check passed
@selfcontained
selfcontained deleted the agt_8809aa586e14/job-doc-ter-4ad99753 branch August 19, 2026 04:11
Sign up for freeto join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant

@selfcontained