From 8a76a7f14282bf257a608326de28ac90b4791b82 Mon Sep 17 00:00:00 2001
From: Brad Harris <bmharris@gmail.com>
Date: Tue, 18 Aug 2026 22:05:27 -0600
Subject: [PATCH] Correct the Status Events docs and add a status-correction
 tip
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

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>
---
 .../components/app/docs-sections/events.tsx   | 24 ++++++++++++++-----
 apps/web/src/lib/tips/tips.ts                 |  8 +++++++
 2 files changed, 26 insertions(+), 6 deletions(-)

diff --git a/apps/web/src/components/app/docs-sections/events.tsx b/apps/web/src/components/app/docs-sections/events.tsx
index 141bbe8a..c08f0650 100644
--- a/apps/web/src/components/app/docs-sections/events.tsx
+++ b/apps/web/src/components/app/docs-sections/events.tsx
@@ -48,10 +48,18 @@ export function EventsContent() {
           them to build the activity and active-hours heatmaps, working-time
           stats, and the status breakdown chart.
         </P>
+        <P>
+          Sub agent rows and the <strong>Session details</strong> dialog show
+          the agent's current state instead of a stale event: an agent that has
+          stopped reads <strong>Stopped</strong> (or <strong>Error</strong> if
+          it failed), whatever its last reported event was, and one that hasn't
+          reported yet reads <strong>Running</strong>. The timestamp next to it
+          is still the last event's.
+        </P>
       </Section>
 
       <Section>
-        <H3>Automatic status correction</H3>
+        <H3 id="status-correction">Automatic status correction</H3>
         <P>
           Agents don't always report accurately, so Dispatch cross-checks each
           running agent's status against its terminal activity. If the terminal
@@ -69,11 +77,15 @@ export function EventsContent() {
         <H3>Configuring agent instructions</H3>
         <P>
           Dispatch already injects startup rules at launch telling the agent
-          which event types to use and when to emit them, so reporting works
-          without any setup. To reinforce or customize the behavior, add
-          instructions to your repo's <Code>CLAUDE.md</Code> (or equivalent
-          config) covering the checkpoints that matter to you: start of turn,
-          phase transitions, and a terminal event before the final response.
+          what each event type means and when to emit them, so reporting works
+          without any setup. With <strong>Use short startup rules</strong> on
+          (Settings → Agents → Launch guidance), that rule keeps the timing and
+          the <Code>blocked</Code> distinction but leaves the list of types to
+          the <Code>dispatch_event</Code> tool description. To reinforce or
+          customize the behavior, add instructions to your repo's{" "}
+          <Code>CLAUDE.md</Code> (or equivalent config) covering the checkpoints
+          that matter to you: start of turn, phase transitions, and a terminal
+          event before the final response.
         </P>
       </Section>
     </>
diff --git a/apps/web/src/lib/tips/tips.ts b/apps/web/src/lib/tips/tips.ts
index 8c962178..d7e7f570 100644
--- a/apps/web/src/lib/tips/tips.ts
+++ b/apps/web/src/lib/tips/tips.ts
@@ -308,6 +308,14 @@ export const tips: Tip[] = [
     since: "0.35.0",
     surfaces: ["ambient"],
   },
+  {
+    id: "status-correction",
+    title: "Status Correction",
+    body: 'Agent statuses are self-reported, so Dispatch cross-checks them against terminal activity. An expanded card showing "Activity detected" or "No recent activity detected" is that correction, not something the agent reported.',
+    docsSection: "events#status-correction",
+    since: "0.21.9",
+    surfaces: ["ambient"],
+  },
 ];
 
 export function getTipById(id: string): Tip | undefined {