docs(roadmap): add top-level session command gap

ROADMAP.md

@@ -6637,3 +6637,5 @@ Original filing (2026-04-18): the session emitted `SessionStart hook (completed)
 540. **`--resume latest /<slash> --output-format json` fails before slash dispatch with `session_load_failed` when no session exists, so resume-safe slash commands cannot expose static usage/JSON-format errors in cold workspaces** — dogfooded 2026-05-21 from the `#clawcode-building-in-public` 12:00/12:30 UTC nudges on `/home/bellman/Workspace/claw-code-pr2967` with branch/origin `docs/roadmap-workdir-provenance@3b9332b` and binary `./rust/target/debug/claw` built from source SHA `25d663d`. Clean-home probes from a minimal temp workspace with no sessions: `claw --resume latest /status --output-format json`, `/diff --output-format json`, `/help --output-format json`, `/config env --output-format json`, and `/agents list --output-format json` all returned the same stderr JSON error: `kind:"session_load_failed"`, `failed to restore session: no managed sessions found in .claw/sessions/<fingerprint>/`, with `stdout=0`. The parser never reaches slash-command usage/argument validation, so callers cannot learn whether `--output-format json` is supported for that slash command, whether the command is resume-safe, or what static usage applies unless a session already exists. This compounds #538/#539 (direct slash errors are `unknown`/prose) with a resume-path ordering issue: cold workspaces collapse every slash probe into a generic session-load error. **Required fix shape:** (a) parse resume slash commands and static help/usage/format flags before attempting to load `latest`; (b) for slash commands that can answer without session state (`/help`, `/agents list`, maybe `/config env`), return the bounded result even when no session exists; (c) for stateful slash commands (`/status`, `/diff`) return a typed `kind:"no_managed_sessions"` / `reason:"session_required"` envelope that preserves `slash`, `usage`, and `resume_supported`; (d) route JSON-mode error envelopes according to the global JSON stream contract; (e) add cold-workspace regressions for the five probes above plus a warm-session control proving real dispatch still works. **Why this matters:** resume-safe slash commands are the documented way to inspect sessions without entering the REPL. In a cold or wrong-cwd workspace, automation needs to distinguish “no session exists” from “slash command/JSON args unsupported” and still retrieve usage; a generic pre-dispatch session-load failure hides the real command contract. Source: gaebal-gajae dogfood response to Clawhip messages `1506989972564086886` and `1506997517198430249` on 2026-05-21.
 
 541. **`SessionStore::from_cwd` and `from_data_dir` eagerly `create_dir_all` the sessions namespace, so read-only session discovery and failed resume attempts mutate the workspace before proving a session will be read or written** — dogfooded 2026-05-21 from the `#clawcode-building-in-public` 13:00 UTC nudge on `/home/bellman/Workspace/claw-code-pr2967` with branch/origin `docs/roadmap-workdir-provenance@8a92f0e` and binary built from source SHA `25d663d`. Code inspection: `runtime/src/session_control.rs:32-43` builds `<cwd>/.claw/sessions/<workspace_hash>/` and immediately calls `fs::create_dir_all(&sessions_root)?`; `from_data_dir` does the same at lines 54-67. These constructors are used by read/discovery paths (`session_control.rs` list/exists/resolve helpers, `main.rs` session store setup, tests, and resume command routing), so merely asking to list sessions, check existence, or resume `latest` in a fresh workspace can create `.claw/sessions/<fingerprint>/` even when no session exists and the command ultimately fails. This is the root cause behind the repeated failed-resume droppings noted in #435/#444/#540, but the actual product gap is broader: the constructor for a session *store handle* performs durable filesystem mutation instead of deferring directory creation to the first successful save/create operation. **Required fix shape:** (a) split `SessionStore::from_cwd` into non-mutating construction and an explicit `ensure_exists_for_write()` path; (b) make list/exists/resolve/latest handle missing session directories as empty/not-found without creating them; (c) call `create_dir_all` only when creating a new session file or writing a session snapshot; (d) expose a `store_exists` / `created:false` diagnostic if needed, but do not mutate during read-only probes; (e) add regressions proving `--resume latest`, session list/exists, and cold-workspace slash probes leave no `.claw/` tree behind on failure, while a real successful save creates the namespace. **Why this matters:** session discovery is supposed to be a read-only observability surface. Eagerly creating workspace metadata during failed reads pollutes repos, confuses `git status`, and makes cold-workspace probes look like they partially initialized state even though no usable session exists. Source: gaebal-gajae dogfood response to Clawhip message `1507005067016929364` on 2026-05-21.
+
+542. **`claw session --help --output-format json` and other top-level `session` invocations fall through to prompt/runtime startup, then hang behind config/plugin initialization instead of returning bounded local help or typed unsupported-subcommand JSON** — dogfooded 2026-05-21 from the `#clawcode-building-in-public` 13:30 UTC nudge on `/home/bellman/Workspace/claw-code-pr2967` with branch/origin `docs/roadmap-workdir-provenance@adaf8c3` and binary built from source SHA `25d663d`. Reproduction in normal env: `timeout --kill-after=1s 5s ./rust/target/debug/claw session --help --output-format json` exits 124 with zero stdout and only the settings deprecation warning on stderr (`enabledPlugins` deprecated). `session list --output-format json` and `session exists latest --output-format json` show the same zero-stdout timeout pattern. Code inspection explains it: `parse_local_help_action` only recognizes `status|sandbox|doctor|acp|init|state|export|version|system-prompt|dump-manifests|bootstrap-plan`; `LocalHelpTopic` has no `Session` variant; and the top-level parser has no `session` branch even though slash/resume `/session list|exists|switch|fork|delete` has structured helpers (`render_session_list`, `session_exists_json`). As a result, a user asking for the session command contract is routed into the generic prompt path and waits on runtime startup instead of getting a small control-plane response. **Required fix shape:** (a) add a top-level `session` command parser with `help|list|exists <id>|show <id>|delete?` or explicitly documented unsupported actions; (b) add `LocalHelpTopic::Session` and bounded JSON help showing supported top-level vs slash/resume session operations; (c) make `session list` and `session exists` use non-mutating session-store read paths from #541 and return typed empty/not-found results; (d) reject unsupported `session` actions with `kind:"unsupported_session_action"` including `action`, `supported_actions`, and whether slash/resume alternatives exist; (e) add elapsed-time regressions for `session --help --output-format json`, `session list --output-format json`, `session exists latest --output-format json`, and `session bogus --output-format json`. **Why this matters:** session management is the backbone of resume/export automation. If the natural top-level `session` spelling hangs, operators cannot safely discover or preflight sessions without already knowing the slash-only internal contract, and a control-plane typo looks like runtime/plugin deadlock. Source: gaebal-gajae dogfood response to Clawhip message `1507012621079937165` on 2026-05-21.