docs(exec): document suppression diagnostics

Peter Steinberger · Peter Steinberger · commit 937e08c698f7 · 2026-06-30T21:06:42.000-07:00
diff --git a/docs/cli/gateway.md b/docs/cli/gateway.md
@@ -229,7 +229,7 @@ openclaw gateway stability --json
 
 <AccordionGroup>
   <Accordion title="Privacy and bundle behavior">
-    - Records keep operational metadata: event names, counts, byte sizes, memory readings, queue/session state, channel/plugin names, and redacted session summaries. They do not keep chat text, webhook bodies, tool outputs, raw request or response bodies, tokens, cookies, secret values, hostnames, or raw session ids. Set `diagnostics.enabled: false` to disable the recorder entirely.
+    - Records keep operational metadata: event names, counts, byte sizes, memory readings, queue/session state, approval ids, channel/plugin names, and redacted session summaries. They do not keep chat text, webhook bodies, tool outputs, raw request or response bodies, tokens, cookies, secret values, hostnames, or raw session ids. Set `diagnostics.enabled: false` to disable the recorder entirely.
     - On fatal Gateway exits, shutdown timeouts, and restart startup failures, OpenClaw writes the same diagnostic snapshot to `~/.openclaw/logs/stability/openclaw-stability-*.json` when the recorder has events. Inspect the newest bundle with `openclaw gateway stability --bundle latest`; `--limit`, `--type`, and `--since-seq` also apply to bundle output.
 
   </Accordion>
diff --git a/docs/gateway/opentelemetry.md b/docs/gateway/opentelemetry.md
@@ -412,6 +412,10 @@ to them directly without OTLP export.
 - `exec.process.completed` - terminal outcome, duration, target, mode, exit
   code, and failure kind. Command text and working directories are not
   included.
+- `exec.approval.followup_suppressed` - stale approval follow-up dropped after
+  a session rebound. Includes `approvalId`, `reason` (`session_rebound`),
+  `phase` (`direct_delivery` or `gateway_preflight`), and the dispatcher
+  timestamp. Session keys, routes, and command text are not included.
 
 ## Without an exporter
 
diff --git a/src/agents/bash-tools.exec-approval-followup.test.ts b/src/agents/bash-tools.exec-approval-followup.test.ts
@@ -232,6 +232,10 @@ describe("exec approval followup", () => {
     const sessionStore = writeTempSessionStore({
       "agent:main:main": { sessionId: "session-after-reset" },
     });
+    const diagnostics: DiagnosticEventPayload[] = [];
+    onDiagnosticEvent((event) => {
+      diagnostics.push(event);
+    });
 
     const result = await sendExecApprovalFollowup({
       approvalId: "req-finished-rebound",
@@ -245,6 +249,15 @@ describe("exec approval followup", () => {
     });
 
     expect(result).toBe(false);
+    await waitForDiagnosticEventsDrained();
+    expect(diagnostics).toContainEqual(
+      expect.objectContaining({
+        type: "exec.approval.followup_suppressed",
+        approvalId: "req-finished-rebound",
+        reason: "session_rebound",
+        phase: "direct_delivery",
+      }),
+    );
     expect(sendMessage).not.toHaveBeenCalled();
     expect(callGatewayTool).not.toHaveBeenCalled();
   });
diff --git a/src/infra/diagnostic-events.test.ts b/src/infra/diagnostic-events.test.ts
@@ -822,6 +822,7 @@ describe("diagnostic-events", () => {
         approvalId: "approval-123",
         reason: "session_rebound",
         phase: "gateway_preflight",
+        ts: expect.any(Number),
       }),
     );
   });
