Summary

• Adds a public exec.approval.timeout-suppressed diagnostic event for stale exec approval timeout follow-ups that are intentionally dropped after a session rebound.
• Emits the event from both suppression paths: direct follow-up delivery and gateway preflight.
• Carries only bounded operator metadata: approvalId, source, and reason; no session key, route id, command text, or channel target is added.
• Projects the event into diagnostic stability snapshots and preserves safe approval ids when persisted stability bundles are read back.
• Updates the plugin SDK surface budget for the new public diagnostic event type.

What Problem This Solves

When an exec approval timeout follow-up is stale because the target session was rebound by reset/new-session flow, OpenClaw intentionally suppresses the follow-up. Before this patch, that suppression was only visible through a free-form log line, so operator tooling could not reliably distinguish an intentional stale suppression from lost delivery or a stuck approval path.

Closes #98279

Why This Change Was Made

The existing stale-session guards already know when the approval-time session no longer matches the current session. The fix emits a structured diagnostic event at those existing guards without changing delivery, dedupe, session mutation, or approval resolution behavior.

The event name follows the issue wording: exec.approval.timeout-suppressed. The payload uses source: "agent-direct" | "gateway-preflight" to identify which suppression point fired and reason: "session-rebound" for a stable low-cardinality reason code.

User Impact

Operators and diagnostics consumers can subscribe to the public diagnostic stream or inspect stability/support bundles to see when an approval timeout follow-up was intentionally suppressed. Existing end-user behavior is unchanged.

Change Type

• Bug fix
• Feature
• Refactor
• Docs
• Security
• Chore

Scope

• Gateway
• Skills
• Auth
• Memory
• Integrations
• API
• UI/UX
• CI

Evidence

• node scripts/run-vitest.mjs src/agents/bash-tools.exec-approval-followup.test.ts passed.
• node scripts/run-vitest.mjs src/infra/diagnostic-events.test.ts src/logging/diagnostic-stability.test.ts src/logging/diagnostic-stability-bundle.test.ts passed.
• OPENCLAW_VITEST_MAX_WORKERS=1 node scripts/run-vitest.mjs run --config test/vitest/vitest.gateway.config.ts src/gateway/server-methods/agent.test.ts -t "drops a stale exec approval followup at preflight" exited 0.
• node scripts/plugin-sdk-surface-report.mjs --check passed.
• OPENCLAW_OXLINT_SKIP_PREPARE=1 node scripts/run-oxlint.mjs --tsconfig config/tsconfig/oxlint.core.json <changed files> passed.
• timeout 360s node scripts/run-tsgo.mjs -p test/tsconfig/tsconfig.core.test.json --incremental --tsBuildInfoFile .artifacts/tsgo-cache/core-test.tsbuildinfo passed.
• timeout 180s node scripts/run-tsgo.mjs -p extensions/diagnostics-otel/tsconfig.json --incremental --tsBuildInfoFile .artifacts/tsgo-cache/diagnostics-otel.tsbuildinfo passed.
• timeout 180s node scripts/run-tsgo.mjs -p extensions/diagnostics-prometheus/tsconfig.json --incremental --tsBuildInfoFile .artifacts/tsgo-cache/diagnostics-prometheus.tsbuildinfo passed.
• git diff --check passed.

Real behavior proof

Behavior addressed: A stale approval-timeout follow-up is suppressed and emits a structured exec.approval.timeout-suppressed event with the approval id, suppression source, reason, and dispatcher timestamp.

Environment tested: Linux workspace, Node 22.22.0, current main plus this patch.

Steps run after the patch: Ran node --import tsx --no-warnings -e ... and imported the real sendExecApprovalFollowup, onDiagnosticEvent, and waitForDiagnosticEventsDrained functions. The script seeded a temp session store where agent:main:main had already rebound from session-original to session-after-reset, then sent an approval-timeout follow-up for the original session.

Evidence after fix:

[agents/exec-approval-followup] Dropping stale denied exec approval followup req-proof-rebound: session agent:main:main was rebound before the approval resolved
{
  "result": false,
  "events": [
    {
      "type": "exec.approval.timeout-suppressed",
      "approvalId": "req-proof-rebound",
      "source": "agent-direct",
      "reason": "session-rebound",
      "seq": 2,
      "ts": 1782863776172
    }
  ]
}

Observed result after the fix: The follow-up returned false, no delivery was attempted, and the public diagnostic subscriber received exactly the new suppression event with approvalId, source, reason, and ts.

What was not tested: A live external channel timeout with real user interaction was not exercised; the proof calls the production follow-up function directly with a real session-store rebound scenario.

Root Cause

• Root cause: stale approval-timeout follow-ups were intentionally dropped after session rebound, but the drop paths only wrote free-form log messages.
• Missing guardrail: the existing diagnostic event stream and stability recorder had no event type for this suppression.

Regression Test Plan

• Direct follow-up test asserts the public diagnostic stream receives exec.approval.timeout-suppressed when a denied timeout follow-up is stale.
• Gateway preflight test asserts the event is emitted before the rebound session is touched.
• Diagnostic events test confirms public subscribers receive the event.
• Stability recorder test confirms snapshots include approval id, source, reason, and timestamp.
• Stability bundle test confirms safe approval ids survive imported bundle sanitization and unsafe ids are dropped.

Impact Assessment

• Scope: additive diagnostic event emitted from two existing stale-session guards.
• Downstream: public diagnostic stream and stability/support-bundle readers gain a new event type; delivery behavior and session mutation are unchanged.
• Edge cases: empty or malformed imported approval ids are not preserved by the bundle reader because it only keeps safe diagnostic code strings.
• Hard-coded values: no runtime configuration defaults were added; event values are derived from the suppression path and approval id already present at the call site.
• Existing fixes: open PRs fix(exec): emit structured event when stale approval followups are suppressed (fixes #98279) #98292 and fix(gateway): emit stale exec approval followup diagnostics #98293 were checked. This patch keeps the event payload narrow, covers direct and gateway suppression paths, preserves persisted stability correlation, and includes production-function proof.

Security Impact

• New permissions: No
• Secrets handling changed: No
• New network calls: No
• Payload text, command text, session keys, chat ids, and route ids are not added to the event.