docs(roadmap): add inventory warning hang gap

ROADMAP.md

@@ -6611,3 +6611,33 @@ Original filing (2026-04-18): the session emitted `SessionStart hook (completed)
 527. **`config model/hooks/plugins` reject unsupported trailing flags with `kind:"unknown"` while sibling commands use `kind:"cli_parse"`, and `config env` hangs on the same flags, so config-section argument errors have three different contracts** — dogfooded 2026-05-21 from the `#clawcode-building-in-public` 05:30 UTC nudge on `/home/bellman/Workspace/claw-code-pr2967` with branch/origin `docs/roadmap-workdir-provenance@4639a58` and binary `./rust/target/debug/claw` built from source SHA `25d663d`. Clean-home probes with `.claw.json` containing `model`, `env`, `hooks`, and `plugins`: `claw config model --resume`, `config model --verbose`, `config model --continue`, and the same flags for `config hooks`/`config plugins` all return nonzero bounded errors, but the discriminator is `[error-kind: unknown] error: unexpected extra arguments after \`claw config <section>\``. In the same parser family, `status`/`version`/`doctor`/`sandbox` report `[error-kind: cli_parse] unrecognized argument ... for subcommand ...`, while `config env` still zero-byte hangs on the same flags (#526). This means automation cannot switch on one stable error kind for a simple bad argument: it sees `cli_parse`, `unknown`, or timeout depending only on which config section was requested. **Required fix shape:** (a) route every `config <section>` extra-argument failure through the same CLI-parse error constructor as other subcommands; (b) reserve `kind:"unknown"` for truly unclassified internal failures, never deterministic parser errors; (c) give `config env` the same bounded path instead of the hang in #526; (d) include `command:"config"`, `section`, `unexpected_args`, and `supported_flags` in JSON/text diagnostics; (e) add regression coverage for `config env/model/hooks/plugins --resume|--verbose|--continue` verifying exit nonzero, bounded output, and `kind:"cli_parse"` or `kind:"unsupported_flag_for_command"` consistently. **Why this matters:** config inspection is a core support surface. If identical typo/flag-placement errors produce three contracts, wrappers have to special-case config sections and users see random-looking behavior instead of a clear command-line mistake. Source: gaebal-gajae dogfood response to Clawhip message `1506891824852242513` on 2026-05-21.
 
 528. **`config` unknown sections and extra arguments fall into zero-byte hangs, including JSON-mode invocations, instead of returning bounded config-section parse errors** — dogfooded 2026-05-21 from the `#clawcode-building-in-public` 06:00 UTC nudge on `/home/bellman/Workspace/claw-code-pr2967` with branch/origin `docs/roadmap-workdir-provenance@63f4865` and binary `./rust/target/debug/claw` built from source SHA `25d663d`. Clean-home probes from a minimal temp workspace: `claw config bogus`, `claw config bogus --output-format json`, `claw config --output-format json bogus`, `claw config env extra`, `claw config env --definitely-unknown`, `claw config env --output-format json --definitely-unknown`, and `claw config env --output-format json extra` all timed out after 6s with `stdout=0`/`stderr=0`. This extends #526/#527: unsupported runtime flags on `config env` hang, known sections `model/hooks/plugins` produce bounded-but-wrong `kind:"unknown"`, and now arbitrary unknown config sections or plain extra args also hang. The config parser is not enforcing the advertised section grammar (`env|hooks|model|plugins`) before prompt/runtime fallback. **Required fix shape:** (a) parse `config` with an explicit section enum and reject unknown sections (`bogus`) before runtime startup; (b) reject any extra positional/flag arguments after a valid section unless explicitly supported; (c) in JSON mode, return a typed envelope such as `kind:"unknown_config_section"` or `kind:"unsupported_config_argument"` with `section`, `unexpected_args`, and `supported_sections`; (d) keep text mode bounded with the same information and exit nonzero; (e) add elapsed-time regressions for unknown section before/after `--output-format json`, valid section plus extra positional, valid section plus unknown flag, and bare `config` success. **Why this matters:** config inspection is a primary startup/debug surface. A typo like `config enb` or an extra copied flag should produce an immediate parse diagnostic, not an opaque no-output timeout that makes users think config loading or provider startup is dead. Source: gaebal-gajae dogfood response to Clawhip message `1506899371755569274` on 2026-05-21.
+
+529. **Unknown `agents`/`mcp` subcommands and malformed JSON placements zero-byte hang instead of returning bounded unsupported-action errors, so lifecycle inventory surfaces share the config parser fallthrough class** — dogfooded 2026-05-21 from the `#clawcode-building-in-public` 06:30 UTC nudge on `/home/bellman/Workspace/claw-code-pr2967` with branch/origin `docs/roadmap-workdir-provenance@66e3c8c` and binary `./rust/target/debug/claw` built from source SHA `25d663d`. Clean-home probes from a minimal temp workspace: `claw agents bogus`, `claw agents bogus --output-format json`, `claw agents --output-format json bogus`, `claw mcp bogus`, and `claw mcp bogus --output-format json` each timed out after 6s with `stdout=0`/`stderr=0`; the broader sweep was killed after `skills bogus` also entered the same no-output wait. These commands are advertised lifecycle/introspection surfaces (`agents`, `mcp`, `skills`) and should have small, closed subcommand grammars (`list|show|help`, etc.). Instead, unknown subcommands and misplaced JSON selectors fall through into the same silent runtime path recently found for `config` (#526-#528). **Required fix shape:** (a) define explicit subcommand enums for `agents`, `mcp`, and `skills` before prompt/runtime fallback; (b) reject unknown actions with typed bounded errors (`kind:"unsupported_action"` / `kind:"unknown_subcommand"`) including `command`, `action`, and supported actions; (c) support or deterministically reject `--output-format json` in both prefix and suffix positions without hanging; (d) add elapsed-time regressions for `agents bogus`, `agents bogus --output-format json`, `agents --output-format json bogus`, `mcp bogus`, `mcp bogus --output-format json`, and equivalent `skills` forms; (e) audit every top-level introspection command for the same fallthrough. **Why this matters:** MCP/plugin/agent lifecycle debugging depends on these inventory commands being safe escape hatches. If a typo in an introspection command looks like a dead runtime, operators cannot tell whether the lifecycle subsystem is broken or the CLI parser silently routed to prompt startup. Source: gaebal-gajae dogfood response to Clawhip message `1506906920089550859` on 2026-05-21.
+
+530. **`skills` and `dump-manifests` unknown actions/extra args zero-byte hang, so the skill/manifest discovery surfaces are not safe typed inventories when users typo a subcommand** — dogfooded 2026-05-21 from the `#clawcode-building-in-public` 07:00 UTC nudge on `/home/bellman/Workspace/claw-code-pr2967` with branch/origin `docs/roadmap-workdir-provenance@4fc57a3` and binary `./rust/target/debug/claw` built from source SHA `25d663d`. Clean-home probes from a minimal temp workspace: `claw skills bogus`, `claw skills bogus --output-format json`, `claw skills --output-format json bogus`, `claw dump-manifests bogus`, and `claw dump-manifests bogus --output-format json` each timed out after 6s with `stdout=0`/`stderr=0`; the sweep was stopped before probing later diagnostics. #529 captured `agents`/`mcp` and noticed `skills` starting to hang; this entry isolates the skill/manifest inventory surfaces. `skills` should have a closed grammar (`list|install|help|<skill> [args]`) and `dump-manifests` should either accept only documented `--manifests-dir`/format flags or return a typed unsupported-arg error. Instead, malformed inventory calls fall through into silent runtime/prompt wait. **Required fix shape:** (a) implement explicit parser branches for `skills` and `dump-manifests` before any prompt fallback; (b) for `skills <unknown>`, decide whether unknown means “try invoke skill” or “unknown skill”, but return a bounded `kind:"unknown_skill"` / `kind:"unsupported_action"` when no such skill exists; (c) reject extra positionals for `dump-manifests` with `kind:"unsupported_argument"` and list supported flags; (d) honor JSON mode with machine-readable errors and elapsed-time guards; (e) add regressions for the five probes above plus valid `skills list`/`dump-manifests --manifests-dir <missing>` controls. **Why this matters:** skills and manifests are the self-description layer for downstream claws. A typo while inspecting capabilities should never look like MCP/plugin lifecycle deadlock or prompt startup; it should be a small typed inventory error. Source: gaebal-gajae dogfood response to Clawhip message `1506914474010087594` on 2026-05-21.
+
+531. **`sandbox` and `doctor` unknown positional arguments zero-byte hang, so health/safety diagnostics lose their escape-hatch value when a user adds a typo or copied JSON placement** — dogfooded 2026-05-21 from the `#clawcode-building-in-public` 07:30 UTC nudge on `/home/bellman/Workspace/claw-code-pr2967` with branch/origin `docs/roadmap-workdir-provenance@297a9c4` and binary `./rust/target/debug/claw` built from source SHA `25d663d`. Clean-home probes from a minimal temp workspace: `claw sandbox bogus`, `claw sandbox bogus --output-format json`, `claw sandbox --output-format json bogus`, `claw doctor bogus`, and `claw doctor bogus --output-format json` each timed out after 6s with `stdout=0`/`stderr=0`; the sweep was killed before reaching `status/version` controls. These are supposed to be bounded local health/safety commands. A stray positional arg should be a deterministic `cli_parse` / `unexpected_argument` error, not a silent wait that is indistinguishable from the diagnostic itself hanging. **Required fix shape:** (a) define strict no-extra-positional grammars for `sandbox` and `doctor` before any prompt/runtime fallback; (b) reject unknown positionals/flags in text and JSON modes with bounded errors carrying `command`, `unexpected_args`, and supported flags; (c) support `--help`/`--output-format json` placements consistently, or reject unsupported placement explicitly; (d) add elapsed-time regressions for `sandbox bogus`, `sandbox bogus --output-format json`, `sandbox --output-format json bogus`, `doctor bogus`, and `doctor bogus --output-format json`; (e) audit `status`/`version` for the same positional fallthrough after this fix. **Why this matters:** `doctor` and `sandbox` are the commands operators run when startup, permissions, or isolation look broken. If a typo makes the diagnostic command itself hang with zero output, the user loses the very surface meant to explain the system state. Source: gaebal-gajae dogfood response to Clawhip message `1506922019906916403` on 2026-05-21.
+
+532. **`status` and `version` unknown positional arguments zero-byte hang, so the two most basic local introspection commands are not parse-safe when a stray token is present** — dogfooded 2026-05-21 from the `#clawcode-building-in-public` 08:00 UTC nudge on `/home/bellman/Workspace/claw-code-pr2967` with branch/origin `docs/roadmap-workdir-provenance@fc591b6` and binary `./rust/target/debug/claw` built from source SHA `25d663d`. Clean-home probes from a minimal temp workspace: `claw status bogus`, `claw status bogus --output-format json`, and `claw status --output-format json bogus` each timed out after 6s with `stdout=0`/`stderr=0`; the sweep then reached `claw version bogus`, which also entered the same zero-output wait before the run was killed. This extends #531's `doctor`/`sandbox` positional hang to the most commonly scripted diagnostics. `status` and `version` should reject unexpected positionals before any runtime/prompt fallback and should never need model/config startup to explain a syntax typo. **Required fix shape:** (a) make `status` and `version` strict no-extra-positional subcommands; (b) reject malformed text and JSON placements with bounded `kind:"cli_parse"` / `kind:"unexpected_argument"`, echoing `unexpected_args` and supported flags; (c) keep valid `status --output-format json` and `version --output-format json` behavior unchanged; (d) add elapsed-time regressions for the four probes above plus `version bogus --output-format json` and `version --output-format json bogus`; (e) consolidate this with #531 into a shared parser rule for all no-positional diagnostic commands. **Why this matters:** `status` and `version` are the first commands wrappers call to decide whether claw is alive and which binary is running. A stray token from command composition should produce a tiny parse error, not a silent timeout that marks the binary as dead. Source: gaebal-gajae dogfood response to Clawhip message `1506929574771163176` on 2026-05-21.
+
+533. **`export` and `init` unknown/extra arguments zero-byte hang, so artifact/setup commands are not parse-safe and can masquerade as session-store or project-initialization deadlocks** — dogfooded 2026-05-21 from the `#clawcode-building-in-public` 08:30 UTC nudge on `/home/bellman/Workspace/claw-code-pr2967` with branch/origin `docs/roadmap-workdir-provenance@7e35ed0` and binary `./rust/target/debug/claw` built from source SHA `25d663d`. Clean-home probes from a minimal temp workspace: `claw export bogus`, `claw export bogus --output-format json`, and `claw export --output-format json bogus` each timed out after 6s with `stdout=0`/`stderr=0`; the sweep then reached `claw init bogus`, which also entered the same zero-output wait before the run was killed. `export` is documented as `claw export [PATH] [--session SESSION] [--output PATH]`, and `init` should have either no positionals or a documented target path. Unknown/ambiguous argument forms must be validated before the command can fall into prompt/runtime/session paths. **Required fix shape:** (a) give `export` a strict positional contract: a single optional output path, with extra positionals rejected and JSON/output flags parsed deterministically; (b) make `init` reject unexpected positionals/flags with bounded `kind:"unexpected_argument"` unless a target path is intentionally supported; (c) when `export <PATH>` is valid but no sessions exist, return the existing `no_managed_sessions` error only after path validation, not a hang; (d) add elapsed-time regressions for `export bogus`, `export bogus --output-format json`, `export --output-format json bogus`, `init bogus`, and valid `init`/`export --session missing` controls; (e) fold these artifact/setup commands into the shared no-fallthrough parser rule from #531/#532. **Why this matters:** `export` and `init` are file/artifact setup surfaces. If a typo or copied flag yields a silent timeout, users cannot tell whether session discovery, markdown export, or project initialization is stuck; the CLI should fail before touching runtime state. Source: gaebal-gajae dogfood response to Clawhip message `1506937123373187183` on 2026-05-21.
+
+534. **`bootstrap-plan` and `acp` unknown/extra arguments zero-byte hang, so setup/editor-integration diagnostics still fall through to runtime instead of enforcing their tiny command grammars** — dogfooded 2026-05-21 from the `#clawcode-building-in-public` 09:00 UTC nudge on `/home/bellman/Workspace/claw-code-pr2967` with branch/origin `docs/roadmap-workdir-provenance@d2a4b7b` and binary `./rust/target/debug/claw` built from source SHA `25d663d`. Clean-home probes from a minimal temp workspace: `claw bootstrap-plan bogus`, `claw bootstrap-plan bogus --output-format json`, and `claw bootstrap-plan --output-format json bogus` each timed out after 6s with `stdout=0`/`stderr=0`; the sweep then reached `claw acp bogus`, which also entered the same zero-output wait before the run was killed. `bootstrap-plan` should be a bounded setup/planning helper, and `acp [serve]` is documented as an editor-integration status/server surface with a closed action set. Unknown positionals or misplaced JSON selectors should never start prompt/runtime machinery. **Required fix shape:** (a) make `bootstrap-plan` strict about accepted args/flags and reject extras with `kind:"unexpected_argument"`; (b) make `acp` accept only the documented empty/status form and `serve`, with typed `kind:"unsupported_action"` for anything else; (c) support or explicitly reject `--output-format json` placements without hanging; (d) add elapsed-time regressions for the four probes above plus `acp serve`/bare `bootstrap-plan` controls; (e) include these in the shared no-fallthrough parser audit covering #529-#533. **Why this matters:** setup and editor integration commands are often called by installers, editors, and wrappers. A typo in those integration paths should return a clear command error, not look like editor server startup, prompt delivery, or bootstrap planning has deadlocked. Source: gaebal-gajae dogfood response to Clawhip message `1506944672889831516` on 2026-05-21.
+
+535. **`help` unknown/extra arguments zero-byte hang, so the command meant to explain CLI usage is itself not parse-safe when users ask for a bad topic or misplace JSON flags** — dogfooded 2026-05-21 from the `#clawcode-building-in-public` 09:30 UTC nudge on `/home/bellman/Workspace/claw-code-pr2967` with branch/origin `docs/roadmap-workdir-provenance@c8e2ae4` and binary `./rust/target/debug/claw` built from source SHA `25d663d`. Clean-home probes from a minimal temp workspace: `claw help bogus`, `claw help bogus --output-format json`, and `claw help --output-format json bogus` each timed out after 6s with `stdout=0`/`stderr=0`; the sweep then reached `claw acp bogus --output-format json`, which also entered the same wait before the run was killed. #534 already captured bare `acp bogus`; this entry isolates the help surface. `help` should either print top-level usage, show a known topic, or return a bounded `unknown_help_topic` / `unexpected_argument` diagnostic. It must never fall through to prompt/runtime startup because a user asked for an invalid help topic. **Required fix shape:** (a) give `help` a strict topic parser with known topics/aliases and a bounded unknown-topic error; (b) if JSON help output is unsupported, reject `--output-format json` with `kind:"unsupported_flag_for_command"` rather than hanging; (c) include `topic`, `supported_topics`, and examples in the diagnostic; (d) add elapsed-time regressions for `help bogus`, `help bogus --output-format json`, `help --output-format json bogus`, valid `help`, and valid `--help`; (e) fold `help` into the global no-fallthrough audit so usage-discovery paths remain safe even when malformed. **Why this matters:** help is the recovery path after a parse error. If malformed help requests hang silently, users lose the most basic self-service diagnostic and wrappers cannot safely probe supported command topics. Source: gaebal-gajae dogfood response to Clawhip message `1506952218346127553` on 2026-05-21.
+
+536. **`diff` and `commit` malformed arguments zero-byte hang, so core git/tooling surfaces fall through to runtime instead of rejecting stray tokens before touching workspace state** — dogfooded 2026-05-21 from the `#clawcode-building-in-public` 10:00 UTC nudge on `/home/bellman/Workspace/claw-code-pr2967` with branch/origin `docs/roadmap-workdir-provenance@03fefd2` and binary `./rust/target/debug/claw` built from source SHA `25d663d`. Clean-home probes from a minimal temp workspace: `claw diff bogus`, `claw diff bogus --output-format json`, and `claw diff --output-format json bogus` each timed out after 6s with `stdout=0`/`stderr=0`; the sweep then reached `claw commit bogus`, which also entered the same zero-output wait before the run was killed. `diff` should be a bounded local git inspection command and `commit` should have a documented commit-message/context grammar or reject unexpected args. Neither should silently route malformed invocations into prompt/runtime wait. **Required fix shape:** (a) make `diff` strict about accepted flags/positionals and reject extras with `kind:"unexpected_argument"`; (b) make `commit` either document/parse a single optional context/message argument or reject stray positionals before runtime startup; (c) support `--output-format json` consistently in valid positions and reject malformed placements with a bounded JSON/text parse error; (d) add elapsed-time regressions for the four probes above plus `commit bogus --output-format json`, `pr bogus`, and `issue bogus` if those share the same tool-command parser; (e) fold these git/tool commands into the global no-fallthrough parser audit. **Why this matters:** diff/commit are the coding loop's safety rails. A malformed diff command should not look like a stuck git process, and a malformed commit command should not start opaque model/session work before proving the CLI syntax is valid. Source: gaebal-gajae dogfood response to Clawhip message `1506959769838026895` on 2026-05-21.
+
+537. **`pr` and `issue` malformed arguments zero-byte hang, so GitHub artifact helpers fall through to runtime instead of validating their context/output grammar** — dogfooded 2026-05-21 from the `#clawcode-building-in-public` 10:30 UTC nudge on `/home/bellman/Workspace/claw-code-pr2967` with branch/origin `docs/roadmap-workdir-provenance@87fa106` and binary `./rust/target/debug/claw` built from source SHA `25d663d`. Clean-home probes from a minimal temp workspace: `claw pr bogus`, `claw pr bogus --output-format json`, `claw pr --output-format json bogus`, and `claw issue bogus` each timed out after 6s with `stdout=0`/`stderr=0`; `claw issue bogus --output-format json` then entered the same zero-output wait before the run was killed. `pr [context]` and `issue [context]` may intentionally accept freeform context, but then they must either treat trailing text as context and fail with a bounded missing-auth/no-session/model-preflight diagnostic, or document that direct non-REPL invocation is unsupported and reject it. They should not silently wait before any event/log signal. **Required fix shape:** (a) define the direct CLI contract for `pr`/`issue`: supported one-shot artifact generation vs REPL-only helper; (b) if REPL-only, return `kind:"slash_command_repl_only"` with usage for bare/context/JSON forms; (c) if one-shot is supported, parse context and JSON/output flags strictly, then preflight auth/session requirements with bounded typed errors; (d) add elapsed-time regressions for `pr bogus`, `pr bogus --output-format json`, `pr --output-format json bogus`, `issue bogus`, and `issue bogus --output-format json`; (e) align with #536's `commit` handling so all GitHub/artifact helpers share one no-fallthrough parser. **Why this matters:** PR/issue generation is a high-value automation surface. A malformed or unsupported direct invocation should not look like prompt delivery, GitHub auth, or artifact generation has deadlocked; users need an immediate contract/error before trusting the helper in scripts. Source: gaebal-gajae dogfood response to Clawhip message `1506967318054436914` on 2026-05-21.
+
+538. **Direct slash-command invocations return bounded interactive-only errors but use `kind:"unknown"`, so automation cannot distinguish expected REPL-only usage from unclassified failures** — dogfooded 2026-05-21 from the `#clawcode-building-in-public` 11:00 UTC nudge on `/home/bellman/Workspace/claw-code-pr2967` with branch/origin `docs/roadmap-workdir-provenance@236d345` and binary `./rust/target/debug/claw` built from source SHA `25d663d`. Clean-home probes from a minimal temp workspace: `claw /status`, `claw /diff`, `claw /version`, and `claw /session list` all returned bounded nonzero errors explaining the slash command is interactive-only and suggesting `claw --resume ... /<command>` where applicable, but every envelope used `[error-kind: unknown]`. `claw /status --output-format json` also returned a bounded usage error for unexpected args, again with `kind:"unknown"`. Positive control `claw /help` exited 0 with usage. This is better than the zero-byte fallthrough family, but still a machine-contract gap: direct slash command misuse is a deterministic, expected CLI condition, not an unknown internal failure. **Required fix shape:** (a) add typed error kinds for direct slash command routing: `slash_command_repl_only`, `slash_command_unexpected_args`, and/or `slash_command_resume_required`; (b) include fields such as `slash`, `resume_supported`, `usage`, `suggested_invocations`, and `unexpected_args`; (c) make JSON mode return the same typed envelope without prose scraping; (d) add regressions for `/status`, `/diff`, `/version`, `/session list`, `/status --output-format json`, and `/help`; (e) reserve `kind:"unknown"` for genuine unclassified failures only. **Why this matters:** slash commands are a major entrypoint for users migrating from REPL to scripts. Wrappers need to distinguish “this command is REPL-only; use --resume or top-level equivalent” from actual CLI/runtime failure without parsing English help text. Source: gaebal-gajae dogfood response to Clawhip message `1506974870372745368` on 2026-05-21.
+
+539. **Direct slash commands reject `--output-format json` as unexpected args and still print prose `kind:"unknown"` errors to stderr, so JSON-mode callers cannot get machine-readable slash diagnostics** — dogfooded 2026-05-21 from the `#clawcode-building-in-public` 11:30 UTC nudge on `/home/bellman/Workspace/claw-code-pr2967` with branch/origin `docs/roadmap-workdir-provenance@ad6b573` and binary `./rust/target/debug/claw` built from source SHA `25d663d`. Clean-home probes from a minimal temp workspace: `claw /diff --output-format json`, `claw /version --output-format json`, `claw /session list --output-format json`, `claw /config env --output-format json`, and `claw /agents list --output-format json` all exited nonzero with `stdout=0` and stderr-only prose usage/error output. Every case used `[error-kind: unknown]`; none emitted a JSON error envelope despite an explicit `--output-format json` token. This is distinct from #538's generic slash `unknown` kind drift: JSON-mode slash invocations are both rejected as unexpected args and denied machine-readable error output. **Required fix shape:** (a) decide whether direct slash commands support `--output-format json`; if yes, parse it before slash-arg validation and return structured errors; if no, reject with a typed JSON-capable `unsupported_flag_for_slash_command` envelope; (b) include `slash`, `unexpected_args`, `usage`, `resume_supported`, and `suggested_top_level_command` fields; (c) return JSON on stdout or stderr consistently with other JSON error contracts; (d) add regressions for the five probes above plus valid `/help --output-format json` behavior (support or typed reject); (e) replace `kind:"unknown"` with slash-specific kinds from #538. **Why this matters:** wrappers often add `--output-format json` globally to every probe. Slash-command errors currently force prose scraping and make expected REPL-only or unsupported-format cases indistinguishable from unknown failures. Source: gaebal-gajae dogfood response to Clawhip message `1506982418014277683` on 2026-05-21.
+
+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.
+
+543. **Top-level local inventory commands (`plugins list`, `mcp list`, `agents list`, `skills list`) hang in normal env when deprecated config warnings are present, so a non-fatal settings migration warning blocks JSON inventory output entirely** — dogfooded 2026-05-21 from the `#clawcode-building-in-public` 14:00 UTC nudge on `/home/bellman/Workspace/claw-code-pr2967` with branch/origin `docs/roadmap-workdir-provenance@dbc7125` and binary built from source SHA `25d663d`. Reproduction in the operator's normal env: bounded probes `timeout --kill-after=1s 6s ./rust/target/debug/claw plugins list --output-format json`, `mcp list --output-format json`, `agents list --output-format json`, and `skills list --output-format json` each exited 124 with zero stdout and only one stderr line: `warning: /home/bellman/.claw/settings.json: field "enabledPlugins" is deprecated (line 2). Use "plugins.enabled" instead`. These are supposed to be local discovery surfaces and the code has direct top-level branches (`CliAction::Plugins`, `CliAction::Mcp`, `CliAction::Agents`, `CliAction::Skills`) plus JSON renderers, but a non-fatal config deprecation warning appears before output and the command never completes. This is distinct from unknown-subcommand parser fallthrough (#529/#530) and missing top-level `session` (#542): here the requested actions are valid, parsed, and should be bounded, yet the normal-env warning path wedges them. **Required fix shape:** (a) make config deprecation warnings non-blocking for read-only inventory commands and never require interaction/cleanup before emitting JSON; (b) include warnings in a structured `warnings[]` field for JSON mode instead of stderr-only prelude that can precede a hang; (c) ensure inventory handlers can load partial/deprecated config and return `status:"degraded"` with `config_warnings` rather than timing out; (d) add normal-env/fixture regressions with deprecated `enabledPlugins` proving `plugins list`, `mcp list`, `agents list`, and `skills list` all produce bounded JSON within a small budget; (e) audit `dump-manifests` and `system-prompt` for the same warning-induced wedge. **Why this matters:** inventory commands are the emergency observability path for MCP/plugin/agent lifecycle issues. A migration warning must not make those commands look dead, especially in the exact long-lived user configs where deprecated fields are most likely to exist. Source: gaebal-gajae dogfood response to Clawhip message `1507020170671947888` on 2026-05-21.