#18179: CLI: add sessions --json-debug diagnostics

## Summary Describe the problem and fix in 2–5 bullets: - Problem: `openclaw sessions --json` did not expose per-entry `sessionFile` diagnostics, while recurring support reports center on `Session file path must be within sessions directory`. - Why it matters: users can still hit that error on `2026.2.16` due to local store/config mismatches; when that happens, built-in CLI output does not show which session entry is problematic. - Context: session-file resolution fixes were already merged previously (for example #15154 and #15323), so this PR is intentionally a diagnostics extension, not a path-resolution logic change. - What changed: added `openclaw sessions --json-debug` (implies JSON output) and included per-session debug path fields under `sessions[].debug`. - What did NOT change (scope boundary): default `openclaw sessions` and `openclaw sessions --json` output remains unchanged. ## Change Type (select all) - [x] Bug fix - [x] Feature - [ ] Refactor - [x] Docs - [ ] Security hardening - [ ] Chore/infra ## Scope (select all touched areas) - [ ] Gateway / orchestration - [ ] Skills / tool execution - [ ] Auth / tokens - [ ] Memory / storage - [ ] Integrations - [x] API / contracts - [x] UI / DX - [ ] CI/CD / infra ## Linked Issue/PR - Closes # - Related #15154 - Related #15323 ## User-visible / Behavior Changes - New flag: `openclaw sessions --json-debug`. - `--json-debug` implies JSON mode and adds `sessions[].debug` with: - `sessionFileRaw` - `sessionFileResolved` - `sessionFileStatus` (`missing`, `empty`, `ok`, `outside_sessions_dir`) - `transcriptExists` - Existing `--json` shape is unchanged unless `--json-debug` is provided. ## Security Impact (required) - New permissions/capabilities? (`No`) - Secrets/tokens handling changed? (`No`) - New/changed network calls? (`No`) - Command/tool execution surface changed? (`No`) - Data access scope changed? (`No`) - If any `Yes`, explain risk + mitigation: ## Repro + Verification ### Environment - OS: macOS - Runtime/container: Node 22 / pnpm - Model/provider: N/A - Integration/channel (if any): N/A - Relevant config (redacted): session store at `~/.openclaw/agents/main/sessions/sessions.json` with legacy absolute transcript pointers under `~/.clawdbot/...`. ### Steps 1. Install/use a legacy CLI version (pre-fix era): ```bash npm i -g clawdbot@2026.2.12 ``` 2. Run normal setup and create at least one session entry: ```bash clawdbot onboard clawdbot agent --message "hello" ``` 3. Upgrade via the standard user path and restart gateway: ```bash clawdbot update openclaw gateway restart ``` 4. Reproduce and inspect diagnostics: ```bash openclaw doctor --non-interactive openclaw sessions --json-debug ``` ### Expected - Legacy/mismatched `sessionFile` entries can still trigger `Session file path must be within sessions directory`. - `openclaw sessions --json-debug` should expose the problematic row(s) with `sessionFileStatus: outside_sessions_dir`. ### Actual - Matches expected. - Validation: `pnpm vitest run --config vitest.e2e.config.ts src/commands/sessions.e2e.test.ts` (pass). ## Compatibility / Migration - Backward compatible? (`Yes`) - Config/env changes? (`No`) - Migration needed? (`No`) - If yes, exact upgrade steps: ## Failure Recovery (if this breaks) - How to disable/revert this change quickly: - Use existing `openclaw sessions --json` (without `--json-debug`) or revert this commit. - Files/config to restore: - `src/commands/sessions.ts`, `src/cli/program/register.status-health-sessions.ts`, `src/cli/program/routes.ts`, docs/test updates in this PR. - Known bad symptoms reviewers should watch for: - `--json` unexpectedly including `debug` fields without `--json-debug`. ## Risks and Mitigations List only real risks for this PR. Add/remove entries as needed. If none, write `None`. - Risk: absolute/local file paths in debug output may be pasted externally. - Mitigation: debug details are opt-in behind `--json-debug`; default `--json` remains unchanged. ## Alternative Considered - Open question for reviewers (@onutc, @gumadeiras): should we keep diagnostics opt-in, or promote at least `sessionFile` into default `--json` rows? - Additional approach to evaluate: migrate stale `sessionFile` pointers proactively in `openclaw update` and/or `openclaw doctor` state-migration flows so older alias paths are auto-normalized. <!-- greptile_comment --> <h3>Greptile Summary</h3> Added `--json-debug` flag to `openclaw sessions` command to expose per-session path diagnostics. This helps users troubleshoot legacy session store path mismatches (specifically the "Session file path must be within sessions directory" error) by providing visibility into `sessionFileStatus`, resolved paths, and transcript existence for each session entry. The implementation correctly reuses the existing `resolveSessionFilePath` validation logic and maintains backward compatibility by keeping default `--json` output unchanged. <h3>Confidence Score: 5/5</h3> - This PR is safe to merge with minimal risk - The implementation is a straightforward diagnostic feature addition with excellent test coverage, clear backward compatibility (existing `--json` output unchanged), proper flag composition logic, and good separation of concerns. The refactor commit properly reuses the existing path resolution logic instead of duplicating validation code. - No files require special attention _{Last reviewed commit: d106bda} <!-- greptile_other_comments_section --> _{(5/5) You can turn off certain types of comments like style [here](https://app.greptile.com/review/github)!} <!-- /greptile_comment -->