[codex] feat(sessions): add read-only diagnose command by zaidazmi · Pull Request #94192 · openclaw/openclaw

zaidazmi · 2026-06-17T15:03:22Z

Summary

Adds a typed, read-only sessions.diagnose Gateway RPC with operator.read scope.
Adds openclaw sessions diagnose for operator triage of active, queued, stalled, done, unresolved, or unknown session state.
Combines stored session state, visible Gateway runs, embedded-run state, diagnostic activity, command-lane state, bounded transcript metadata, and generic delivery metadata into stable finding codes.
Updates CLI/protocol docs, generated Swift protocol models, and focused tests.
Intentionally out of scope: recovery, aborts, lane release, config/env changes, provider/channel connectivity checks, and CHANGELOG.md edits.

Linked context

Closes #94175

Related #86159, #88870, #77542

Was this requested by a maintainer or owner?

No. This follows the feature-request issue opened before the PR, per contributor guidance.

Real behavior proof (required for external PRs)

Behavior or issue addressed: Adds a read-only session diagnosis command/RPC so operators can inspect why a session appears stuck, silent, queued, done, unresolved, or unknown before taking recovery action.
Real environment tested: macOS local source checkout, bundled Node v24.14.0, isolated temp OPENCLAW_HOME / OPENCLAW_STATE_DIR, foreground Gateway on loopback port 41234, token auth enabled.
Exact steps or command run after this patch: Started an isolated Gateway with pnpm openclaw gateway run --dev --reset --port 41234 --auth token --token <redacted> --bind loopback --allow-unconfigured --ws-log compact; ran pnpm openclaw sessions diagnose --json --tail 1 --timeout 10000; added one minimal stored session in the isolated state (sessionId=sess-proof, label=proof-triage, one transcript line containing fake private text); then ran pnpm openclaw sessions diagnose --session-key agent:main:main --json --tail 1 --timeout 10000.
Evidence after fix (screenshot, recording, terminal capture, console output, redacted runtime log, linked artifact, or copied live output): Copied live output from the isolated Gateway proof:

$ pnpm openclaw sessions diagnose --json --tail 1 --timeout 10000
{
  "ok": true,
  "outcome": "no_sessions",
  "summary": {
    "state": "unknown",
    "headline": "No stored sessions are available to diagnose."
  },
  "session": {
    "found": false
  },
  "live": {}
}

$ pnpm openclaw sessions diagnose --session-key agent:main:main --json --tail 1 --timeout 10000
{
  "ok": true,
  "outcome": "diagnosed",
  "chosenBecause": "explicit key selector",
  "summary": {
    "state": "done"
  },
  "session": {
    "key": "agent:main:main",
    "sessionId": "sess-proof",
    "label": "proof-triage"
  },
  "transcript": {
    "resolved": true,
    "recentEventCount": 1
  },
  "delivery": {
    "uncertain": false
  }
}

Observed result after fix: The CLI reached the live branch-built Gateway, returned schema-shaped JSON for both no-session and stored-session cases, and the stored-session output did not expose the local sessionFile path or the fake private transcript text.
What was not tested: A real long-running active model/channel session, Control UI rendering, provider connectivity, and channel transport health. Those are intentionally outside this read-only diagnosis slice.
Proof limitations or environment constraints: The stored-session proof used a minimal synthetic session row in an isolated temp state so no personal OpenClaw data, credentials, or channels were touched. It proves the live CLI/Gateway diagnosis surface and output safety, not real provider execution.
Before evidence (optional but encouraged): Before this patch, openclaw sessions diagnose was not a registered CLI subcommand and sessions.diagnose was not advertised by the Gateway method list.

Tests and validation

Commands run:

pnpm install
pnpm protocol:gen && pnpm protocol:gen:swift
pnpm exec oxfmt --write <touched source/docs/test files>
pnpm docs:list
PATH=<bundled-node-bin>:$PATH OPENCLAW_VITEST_MAX_WORKERS=1 pnpm test packages/gateway-protocol/src/index.test.ts src/gateway/method-scopes.test.ts src/gateway/server-methods-list.test.ts src/gateway/server-methods/session-active-runs.test.ts src/agents/embedded-agent-runner/run-state.test.ts src/gateway/server-methods/sessions.diagnose.test.ts src/commands/sessions-diagnose.test.ts src/cli/program/register.status-health-sessions.test.ts src/cli/program/routes.test.ts -- --reporter=verbose
PATH=<bundled-node-bin>:$PATH pnpm tsgo:core
PATH=<bundled-node-bin>:$PATH pnpm tsgo:core:test
PATH=<bundled-node-bin>:$PATH pnpm check:import-cycles
PATH=<bundled-node-bin>:$PATH pnpm build
git diff --check

Regression coverage added or updated:

Protocol validator coverage for SessionsDiagnoseParams and SessionsDiagnoseResult, including bounded tail, rejected stale params, closed enum values, and path-bearing field rejection.
Gateway method tests for read-only diagnosis, active-session selection beyond bounded newest scans, no-session output, and ambiguous selector rejection.
CLI tests for rendering, JSON passthrough, invalid tail handling, ambiguous selectors, unsupported older Gateway errors, and no-session exit code.
Active-run and embedded-run projection tests to ensure diagnostic output does not expose abort controllers, local paths, or stale session-key mappings.
Method-list, method-scope, route, and registration tests for the new command/RPC.

What failed before this fix, if known?

A first direct pnpm exec vitest run ... attempt was killed by local memory pressure (exit 137). The same focused set passed through the repo pnpm test wrapper with OPENCLAW_VITEST_MAX_WORKERS=1, then passed again under Node 24.

If no test was added, why not?

Not applicable.

Risk checklist

Did user-visible behavior change? (Yes/No)

Yes. Adds a new CLI subcommand and read-only Gateway RPC.

Did config, environment, or migration behavior change? (Yes/No)

No.

Did security, auth, secrets, network, or tool execution behavior change? (Yes/No)

No. The RPC is operator.read and does not execute tools, mutate state, expose transcript content, or expose local transcript paths.

What is the highest-risk area?

The new diagnostic projection could accidentally over-report sensitive/session-local detail or overstate confidence about stuck-session state.

How is that risk mitigated?

The result schema is bounded, uses stable finding codes, avoids transcript content and local path fields, rejects ambiguous selectors, keeps diagnosis read-only, and includes tests that assert local paths/private transcript text do not appear in output.

Current review state

What is the next action?

Ready for maintainer review and CI on this draft PR.

What is still waiting on author, maintainer, CI, or external proof?

CI and maintainer review. The PR already includes local targeted tests, typechecks, import-cycle check, build, docs sanity, generated protocol output, and live Gateway proof.

Which bot or reviewer comments were addressed?

None yet.

AI-assisted disclosure:

This PR is AI-assisted with Codex. I understand the intended behavior and the change is scoped to a read-only operator diagnostic surface.

Local Codex review state:

codex review --base origin/main was attempted before opening the PR, but the local review process hung after starting a deep diff read and had to be stopped. The successful validation commands and live proof above are the current review evidence.

clawsweeper · 2026-06-17T22:15:37Z

Codex review: needs maintainer review before merge. Reviewed June 17, 2026, 6:23 PM ET / 22:23 UTC.

Summary
Adds an additive read-only sessions.diagnose Gateway RPC and openclaw sessions diagnose CLI command, with protocol/Swift models, docs, and focused Gateway, CLI, and runtime projection tests.

PR surface: Source +1520, Tests +840, Docs +491, Other +96. Total +2947 across 28 files.

Reproducibility: not applicable. as a bug reproduction; current main source confirms the command/RPC is absent, and the PR body supplies live after-fix output from an isolated Gateway.

Review metrics: 1 noteworthy metric.

Public diagnostic surfaces added: 1 Gateway RPC, 1 CLI subcommand. The new operator-facing protocol and CLI contract should be explicitly accepted before merge even though the implementation is additive and read-only.

Stored data model
Persistent data-model change detected: serialized state: packages/gateway-protocol/src/schema/sessions.ts, serialized state: src/commands/sessions-diagnose.test.ts, serialized state: src/commands/sessions-diagnose.ts, serialized state: src/config/sessions/session-accessor.ts, serialized state: src/gateway/server-methods/session-active-runs.test.ts, serialized state: src/gateway/server-methods/session-active-runs.ts, and 10 more. Confirm migration or upgrade compatibility proof before merge.

Root-cause cluster
Relationship: fixed_by_candidate
Canonical: #94175
Summary: this PR is the candidate implementation for the focused read-only session diagnosis request in #94175, while the broader stuck-session recovery and stall-diagnostics items remain adjacent work.

Members:

canonical: [Feature]: Add read-only sessions diagnose command for stuck-session triage #94175 - The issue asks for the same sessions.diagnose Gateway/CLI diagnostic surface added by this PR.
partial_overlap: Stuck-session recovery aborts long-but-active agent runs at warnMs×3 (~6min) with misleading "Reply operation aborted by user" reason #88870 - The issue motivates session-state visibility for false stuck-session aborts, but it still needs direct recovery/liveness behavior fixes beyond this read-only diagnosis surface.
partial_overlap: Feature: diagnostics stuck-session recovery ladder (steer → nudge → abort) #86159 - The recovery-ladder request could use diagnosis evidence but asks for new recovery actions and configuration not implemented by this PR.
adjacent_distinct: [codex] add gateway stall diagnostics #77542 - The open stall-diagnostics PR adds broader liveness/logging improvements and does not supersede this focused CLI/RPC diagnosis command.

Proposal only: this assessment does not dispatch repair, suppress jobs, mutate sibling items, close, or merge anything.

Merge readiness
Overall: 🐚 platinum hermit
Proof: 🐚 platinum hermit
Patch quality: 🐚 platinum hermit
Result: ready for maintainer review.

Overall follows the weaker of proof and patch quality, so missing proof can cap an otherwise strong patch.

Rank-up moves:

[P2] Have a maintainer explicitly confirm the sessions.diagnose command/RPC vocabulary and support commitment before merge.

Risk before merge

[P1] The main unresolved risk is product/API acceptance: the PR adds a new public Gateway method, protocol result vocabulary, Swift model, and CLI command that maintainers must be willing to support.

Maintainer options:

Decide the mitigation before merge
Land the additive read-only diagnose surface if maintainers accept the command/RPC contract; otherwise narrow or defer it to the existing stuck-session diagnostics and recovery work.
Pause or close
Do not merge this PR until maintainers decide whether the risk is worth taking.

Next step before merge

[P2] This adds a new public operator RPC/CLI diagnostic surface, so the next action is maintainer product/API review rather than an automated repair.

Security
Cleared: The diff adds a read-only operator.read diagnostic RPC/CLI path with no dependency, workflow, lockfile, secret-handling, or state-mutation changes, and reviewed tests cover transcript/path redaction.

Review details

Best possible solution:

Land the additive read-only diagnose surface if maintainers accept the command/RPC contract; otherwise narrow or defer it to the existing stuck-session diagnostics and recovery work.

Do we have a high-confidence way to reproduce the issue?

Not applicable as a bug reproduction; current main source confirms the command/RPC is absent, and the PR body supplies live after-fix output from an isolated Gateway.

Is this the best way to solve the issue?

Yes, subject to maintainer API acceptance; using the Gateway method as the canonical source and the CLI as a renderer is better than duplicating local store/runtime inspection in the CLI.

AGENTS.md: found and applied where relevant.

Codex review notes: model internal, reasoning high; reviewed against 591313e80a5e.

Label changes

Label changes:

add P2: This is a normal-priority operator diagnostics improvement with incident-triage value and limited direct runtime blast radius.
add proof: sufficient: Contributor real behavior proof is sufficient. The PR body includes after-fix live CLI/Gateway output for no-session and synthetic stored-session cases, including redacted auth context and no transcript/path leak; active provider/channel proof remains outside this slice.
add rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🐚 platinum hermit and patch quality is 🐚 platinum hermit.
add feature: ✨ showcase: ClawSweeper spotlight: unusually compelling feature idea for maintainer attention. The idea gives operators a safer read-only triage step before using recovery actions that can abort or disturb active sessions.
add status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Sufficient (live_output): The PR body includes after-fix live CLI/Gateway output for no-session and synthetic stored-session cases, including redacted auth context and no transcript/path leak; active provider/channel proof remains outside this slice.

Label justifications:

P2: This is a normal-priority operator diagnostics improvement with incident-triage value and limited direct runtime blast radius.
rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🐚 platinum hermit and patch quality is 🐚 platinum hermit.
feature: ✨ showcase: ClawSweeper spotlight: unusually compelling feature idea for maintainer attention. The idea gives operators a safer read-only triage step before using recovery actions that can abort or disturb active sessions.
status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Sufficient (live_output): The PR body includes after-fix live CLI/Gateway output for no-session and synthetic stored-session cases, including redacted auth context and no transcript/path leak; active provider/channel proof remains outside this slice.
proof: sufficient: Contributor real behavior proof is sufficient. The PR body includes after-fix live CLI/Gateway output for no-session and synthetic stored-session cases, including redacted auth context and no transcript/path leak; active provider/channel proof remains outside this slice.

Evidence reviewed

PR surface:

Source +1520, Tests +840, Docs +491, Other +96. Total +2947 across 28 files.

View PR surface stats

Area	Files	Added	Removed	Net
Source	13	1523	3	+1520
Tests	10	840	0	+840
Docs	4	491	0	+491
Config	0	0	0	0
Generated	0	0	0	0
Other	1	96	0	+96
Total	28	2950	3	+2947

Acceptance criteria:

[P1] Review the sessions.diagnose protocol schema and stable finding/outcome vocabulary for long-term supportability.
[P1] Confirm CLI text and JSON output are acceptable public operator contracts.
[P1] Use the existing focused Gateway/CLI tests as merge validation; run broader Gateway/protocol checks if maintainers accept the feature.

What I checked:

Repository policy read: The full root AGENTS.md and scoped docs, agents, gateway, and gateway/server-methods AGENTS.md files were read and applied; the applicable guidance treats Gateway protocol/CLI additions as public, compatibility-sensitive surfaces that need source, tests, current behavior, and owner-boundary review. (AGENTS.md:1, f7e5132b3b3d)
Current main lacks the requested command/RPC: sessions.diagnose is absent from the current main reference inspected for this review, so the central behavior is not already implemented on main. (591313e80a5e)
Gateway RPC implementation: The PR adds validated sessions.diagnose handling that resolves selectors, gathers stored session, active-run, embedded-run, diagnostic, lane, transcript, and delivery metadata, and returns diagnosis outcomes without mutating session state. (src/gateway/server-methods/sessions.ts:1843, c6a0b57ee374)
Protocol contract: The protocol schema defines strict params/results for sessions.diagnose, including bounded transcript tail input, stable finding/outcome enums, and result objects that do not expose raw transcript content or local transcript paths. (packages/gateway-protocol/src/schema/sessions.ts:225, c6a0b57ee374)
CLI command: The CLI command validates mutually exclusive selectors and tail bounds, calls Gateway with requiredMethods: ["sessions.diagnose"], validates the typed result, and renders text or JSON without inspecting session files locally. (src/commands/sessions-diagnose.ts:159, c6a0b57ee374)
Leak and ambiguity tests: Gateway tests cover no raw transcript text/path exposure, active-session visibility beyond the bounded newest-session scan, and rejection of ambiguous selectors; CLI tests cover rendering, JSON, tail validation, unsupported Gateway method, and no-session cases. (src/gateway/server-methods/sessions.diagnose.test.ts:25, c6a0b57ee374)

Likely related people:

Peter Steinberger: History search shows prior merged work adding the adjacent sessions.preview RPC and splitting diagnostic session-state code, both close to the new diagnose surface. (role: feature-history contributor; confidence: medium; commits: cadaf2c835f, 0dec234505; files: src/gateway/server-methods/sessions.ts, packages/gateway-protocol/src/schema/sessions.ts, src/logging/diagnostic-session-state.ts)
Josh Lehman: Recent main history shows session lifecycle seam work in src/gateway/server-methods/sessions.ts, the central file extended by this PR. (role: recent area contributor; confidence: medium; commits: e442b575; files: src/gateway/server-methods/sessions.ts)
Vincent Koc: Current-main blame and recent history point to broad session-method and gateway source work in the affected module, although the commit appears broad so ownership confidence is lower. (role: current-source provenance contributor; confidence: low; commits: 014c4ae; files: src/gateway/server-methods/sessions.ts, src/gateway/server-methods/session-active-runs.ts)

What the crustacean ranks mean

🦀 challenger crab: rare, exceptional readiness with strong proof, clean implementation, and convincing validation.
🦞 diamond lobster: very strong readiness with only minor maintainer review expected.
🐚 platinum hermit: good normal PR, likely mergeable with ordinary maintainer review.
🦐 gold shrimp: useful signal, but proof or patch confidence is still limited.
🦪 silver shellfish: thin signal; proof, validation, or implementation needs work.
🧂 unranked krab: not merge-ready because proof is missing/unusable or there are serious correctness or safety concerns.
🌊 off-meta tidepool: rating does not apply to this item.

Shiny media proof means a screenshot, video, or linked artifact directly shows the changed behavior. Runtime, network, CSP, and security claims still need visible diagnostics.

How this review workflow works

ClawSweeper keeps one durable marker-backed review comment per issue or PR.
Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
Maintainers can also comment @clawsweeper review to request a fresh review only.
Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.

zaidazmi marked this pull request as ready for review June 17, 2026 15:48

zaidazmi added 2 commits June 17, 2026 23:46

feat(sessions): add diagnose command

7cd7105

fix(sessions): remove redundant boolean conversion

a5687a8

zaidazmi force-pushed the codex/sessions-diagnose branch from 232c2f7 to a5687a8 Compare June 17, 2026 21:47

zaidazmi added 2 commits June 17, 2026 23:54

fix(sessions): restore diagnose transcript reader import

935c461

fix(sessions): route diagnose transcript tail through accessor

c6a0b57

zaidazmi closed this by deleting the head repository Jun 22, 2026

zaidazmi mentioned this pull request Jun 23, 2026

feat(sessions): add read-only diagnose command #96113

Open

clawsweeper Bot mentioned this pull request Jul 6, 2026

[Feature]: Enhance with failure summary and fix suggestions #89339

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!

[codex] feat(sessions): add read-only diagnose command#94192

[codex] feat(sessions): add read-only diagnose command#94192
zaidazmi wants to merge 4 commits into
openclaw:mainfrom
zaidazmi:codex/sessions-diagnose

zaidazmi commented Jun 17, 2026 •

edited

Loading

Uh oh!

clawsweeper Bot commented Jun 17, 2026 •

edited

Loading

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Uh oh!

Uh oh!

Conversation

zaidazmi commented Jun 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Linked context

Real behavior proof (required for external PRs)

Tests and validation

Risk checklist

Current review state

Uh oh!

clawsweeper Bot commented Jun 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

zaidazmi commented Jun 17, 2026 •

edited

Loading

clawsweeper Bot commented Jun 17, 2026 •

edited

Loading