-
-
Notifications
You must be signed in to change notification settings - Fork 80.7k
[Feature]: Add read-only sessions diagnose command for stuck-session triage #94175
Copy link
Copy link
Open
Labels
P2Normal backlog priority with limited blast radius.Normal backlog priority with limited blast radius.clawsweeper:linked-pr-openClawSweeper found an open linked pull request for this issue.ClawSweeper found an open linked pull request for this issue.clawsweeper:needs-product-decisionClawSweeper marked this issue as needing a product or behavior decision.ClawSweeper marked this issue as needing a product or behavior decision.clawsweeper:no-new-fix-prClawSweeper does not recommend queueing a new automated fix PR for this issue.ClawSweeper does not recommend queueing a new automated fix PR for this issue.enhancementNew feature or requestNew feature or requestimpact:session-stateSession, memory, transcript, context, or agent state can drift or corrupt.Session, memory, transcript, context, or agent state can drift or corrupt.issue-rating: 🌊 off-meta tidepoolIssue quality rating does not apply to this item.Issue quality rating does not apply to this item.
Description
Metadata
Metadata
Assignees
Labels
P2Normal backlog priority with limited blast radius.Normal backlog priority with limited blast radius.clawsweeper:linked-pr-openClawSweeper found an open linked pull request for this issue.ClawSweeper found an open linked pull request for this issue.clawsweeper:needs-product-decisionClawSweeper marked this issue as needing a product or behavior decision.ClawSweeper marked this issue as needing a product or behavior decision.clawsweeper:no-new-fix-prClawSweeper does not recommend queueing a new automated fix PR for this issue.ClawSweeper does not recommend queueing a new automated fix PR for this issue.enhancementNew feature or requestNew feature or requestimpact:session-stateSession, memory, transcript, context, or agent state can drift or corrupt.Session, memory, transcript, context, or agent state can drift or corrupt.issue-rating: 🌊 off-meta tidepoolIssue quality rating does not apply to this item.Issue quality rating does not apply to this item.
Type
Fields
Priority
None yet
Summary
Add a read-only Gateway/CLI diagnostic surface,
openclaw sessions diagnose, that explains why a session appears active, queued, stalled, done, unresolved, or unknown before any recovery action is attempted.Problem to solve
OpenClaw has several session-state and recovery issues where operators cannot tell whether a session is truly active, stale, queued, terminal with stale diagnostic state, or missing transcript evidence.
Related: #86159, #88870, #84903, #90516.
Current tools expose pieces of this state, but there is no single conservative diagnosis command.
Proposed solution
Add a typed
sessions.diagnoseGateway method withoperator.readscope and a CLI command:openclaw sessions diagnoseopenclaw sessions diagnose --session-key <key>openclaw sessions diagnose --session-id <id> --jsonopenclaw sessions diagnose --label <label>The command should combine stored session state, visible active Gateway runs, embedded-run state, diagnostic activity, command-lane counts, bounded transcript metadata, and delivery metadata into stable finding codes.
It should reject ambiguous selectors and avoid raw transcript content, secrets, and local transcript paths.
Alternatives considered
sessions,sessions tail,health, and logs manually: too slow and inconsistent during incidents.Impact
Affected: users and operators debugging stuck, silent, or queued sessions.
Severity: high during incidents because the wrong recovery action can lose work or keep agents silent.
Consequence: safer triage, better bug reports, fewer blind restarts/resets, and a foundation for future recovery-ladder work.
Evidence/examples
This is related to the stuck-session recovery ladder in #86159 and stale/active-session issues like #88870.
A PR will include live behavior proof from a real OpenClaw setup, plus focused protocol/Gateway/CLI/docs validation.
Additional information
This is diagnosis-only. It does not add config/env knobs, change recovery thresholds, abort active runs, release lanes, or edit
CHANGELOG.md.Additional information
No response