Document model help JSON hang

Constraint: ROADMAP-only dogfood follow-up for 03:30 nudge on rebuilt claw git_sha d95b230c

Rejected: implementation change to model help; request was one concrete follow-up if no backlog item
Confidence: high after repeated bounded samples plus version JSON responsiveness sanity check
Scope-risk: narrow
Directive: Continue preflight help hang coverage with distinct model-selection surface pinpoint
Tested: repeated timeout --kill-after=1s 8s ./rust/target/debug/claw model --help --output-format json; timeout --kill-after=1s 8s ./rust/target/debug/claw version --output-format json; git diff --check; scripts/fmt.sh --check
Not-tested: runtime behavior change, because this commit only documents the gap

ROADMAP.md

@@ -6300,5 +6300,4 @@ Original filing (2026-04-18): the session emitted `SessionStart hook (completed)
 358. **Top-level `cost --help --output-format json` hangs with zero stdout/stderr instead of returning bounded command help JSON** — dogfooded 2026-04-30 for the 02:00 nudge on current `origin/main` / rebuilt `./rust/target/debug/claw` with embedded `git_sha` `d95b230c`. After rebuilding and verifying the binary provenance, repeated bounded runs of `timeout 8 ./rust/target/debug/claw cost --help --output-format json` exited `124` with `stdout=0` and `stderr=0`. In the same rebuilt binary, `version --output-format json` returned promptly with version/build metadata, proving the binary itself and the JSON output path are reachable; the hang is specific to the cost help path, though other help surfaces have separate known JSON contract issues (#356/#357). **Required fix shape:** (a) make `cost --help --output-format json` return static/bounded stdout JSON with `kind:"help"` or `kind:"cost"`, `action:"help"`, usage, options, examples, supported output formats, and related slash/direct commands; (b) ensure help rendering does not initialize slow cost/session/accounting providers; (c) if any dynamic provider is accidentally consulted, return a typed JSON timeout/unavailable error instead of hanging; (d) add regression coverage proving cost help in JSON mode returns within a deterministic budget. **Why this matters:** cost/tokens surfaces are commonly consumed by automation for budgeting. If even cost help can hang silently, claws cannot discover cost command semantics or present safe budget diagnostics before running potentially slow accounting paths. Source: gaebal-gajae dogfood follow-up for the 02:00 nudge on rebuilt `./rust/target/debug/claw` `d95b230c`.
 380. **Top-level `tokens --help --output-format json` hangs with zero stdout/stderr instead of returning bounded command help JSON** — dogfooded 2026-04-30 for the 02:30 nudge on current `origin/main` / rebuilt `./rust/target/debug/claw` with embedded `git_sha` `d95b230c`. After verifying #358 covered `cost --help`, a fresh adjacent probe on the token-budget surface showed the same silent failure class: repeated bounded runs of `timeout 8 ./rust/target/debug/claw tokens --help --output-format json` exited `124` with `stdout=0` and `stderr=0`. In the same rebuilt binary, `version --output-format json` returned promptly with version/build metadata, proving the binary itself and JSON output path are reachable. This is distinct from #358's cost help hang: the affected surface is the sibling `tokens` command help, which agents use before estimating prompt/session token budgets. **Required fix shape:** (a) make `tokens --help --output-format json` return static/bounded stdout JSON with `kind:"help"` or `kind:"tokens"`, `action:"help"`, usage, options, examples, supported output formats, and related slash/direct commands; (b) ensure help rendering does not initialize slow token accounting, session, or provider state; (c) if any dynamic provider is consulted, return a typed JSON timeout/unavailable error instead of hanging; (d) add regression coverage proving tokens help in JSON mode returns within a deterministic budget. **Why this matters:** token budgeting is a preflight clawability surface. If help hangs silently, automation cannot safely discover how to inspect or constrain token usage before running expensive prompts, and budget-aware wrappers stall at the discovery step. Source: gaebal-gajae dogfood follow-up for the 02:30 nudge on rebuilt `./rust/target/debug/claw` `d95b230c`.
 381. **Top-level `cache --help --output-format json` hangs with zero stdout/stderr instead of returning bounded command help JSON** — dogfooded 2026-04-30 for the 03:00 nudge on current `origin/main` / rebuilt `./rust/target/debug/claw` with embedded `git_sha` `d95b230c`. After #358 and #380 landed for the cost/tokens preflight help hangs, a fresh adjacent probe on the cache-control surface showed the same silent failure class: repeated bounded runs of `timeout --kill-after=1s 8s ./rust/target/debug/claw cache --help --output-format json` exited `124` with `stdout=0` and `stderr=0`. In the same rebuilt binary, `version --output-format json` returned promptly with version/build metadata, proving the binary itself and JSON output path are reachable. This is distinct from the separate `/cache` slash-command envelope mismatch class: the affected surface here is top-level `cache` command help, where agents need bounded local discovery before deciding whether to inspect, clear, or summarize cache state. **Required fix shape:** (a) make `cache --help --output-format json` return static/bounded stdout JSON with `kind:"help"` or `kind:"cache"`, `action:"help"`, usage, options, examples, supported output formats, and related slash/direct commands; (b) ensure help rendering does not initialize slow cache/session/provider state; (c) if any dynamic provider is consulted, return a typed JSON timeout/unavailable error instead of hanging; (d) add regression coverage proving cache help in JSON mode returns within a deterministic budget. **Why this matters:** cache inspection and cleanup are recovery/control-plane operations. If cache help hangs silently, claws cannot safely discover cache semantics before attempting cleanup, and automation stalls before it can choose a non-destructive cache action. Source: gaebal-gajae dogfood follow-up for the 03:00 nudge on rebuilt `./rust/target/debug/claw` `d95b230c`.
-
-417. **`mcp show <nonexistent> --output-format json` returns `found:false` + `status:"ok"` with exit 0 — a "not found" result with a success status is contradictory and causes automation to false-positive** — dogfooded 2026-04-30 by Jobdori on `e939777f`. Running `claw mcp show nonexistent --output-format json` when the server is not configured returns `{"action":"show","config_load_error":null,"found":false,"kind":"mcp","message":"server \`nonexistent\` is not configured","server_name":"nonexistent","status":"ok","working_directory":"..."}` with exit code 0. `found:false` means the server does not exist in config; `status:"ok"` means the show operation completed without internal error — but these two fields give conflicting signals: a claw checking `if status == "ok" then server_is_present` will false-positive on every nonexistent server query. The only unambiguous signal is `found:false`, but `status:"ok"` directly contradicts it. `exit 0` compounds this: standard CLI convention is exit 1 for "not found" lookups. **This is distinct from ROADMAP #102** which covers the deeper liveness-probe gap (server configured but command unreachable); #417 targets the simpler semantic contradiction in the `show` response when the server is not configured at all. **Required fix shape:** (a) use `status:"not_found"` (or `"missing"`) instead of `status:"ok"` when `found:false`; (b) exit with a non-zero code (exit 1 or exit 2) when the queried server is not found, consistent with standard lookup-command semantics; (c) if `status:"ok"` is intentionally reserved for "the show command itself ran without error" (not "the server exists"), rename it to `query_status:"ok"` and add a separate `found_status:"not_found"|"found"` field to prevent ambiguity; (d) add regression coverage proving `mcp show <nonexistent> --output-format json` returns a non-ok or semantically distinct status and a non-zero exit code. **Why this matters:** automation that orchestrates MCP server checks before starting a session will loop over a server list with `mcp show` and check `status`. If `status:"ok"` means "command ran OK" not "server exists", every missing server looks healthy to a standard status-check loop. Source: Jobdori live dogfood, `e939777f`, 2026-04-30.
+382. **Top-level `model --help --output-format json` hangs with zero stdout/stderr instead of returning bounded command help JSON** — dogfooded 2026-04-30 for the 03:30 nudge on current `origin/main` / rebuilt `./rust/target/debug/claw` with embedded `git_sha` `d95b230c`. After #358/#380/#381 landed for cost/tokens/cache preflight help hangs, a fresh adjacent probe on the model-selection surface showed the same silent failure class: repeated bounded runs of `timeout --kill-after=1s 8s ./rust/target/debug/claw model --help --output-format json` exited `124` with `stdout=0` and `stderr=0`. In the same rebuilt binary, `version --output-format json` returned promptly with version/build metadata, proving the binary itself and JSON output path are reachable. This is distinct from runtime model switching behavior: the affected surface is help/discovery for the top-level `model` command, where agents need bounded local usage/options before changing or reporting model state. **Required fix shape:** (a) make `model --help --output-format json` return static/bounded stdout JSON with `kind:"help"` or `kind:"model"`, `action:"help"`, usage, options, examples, supported output formats, and related slash/direct commands; (b) ensure help rendering does not initialize slow provider/model registry/auth/session state; (c) if any dynamic provider is consulted, return a typed JSON timeout/unavailable error instead of hanging; (d) add regression coverage proving model help in JSON mode returns within a deterministic budget. **Why this matters:** model selection is a high-impact control-plane operation. If model help hangs silently, claws cannot safely discover how to inspect or change models before execution, and automation stalls before it can choose a compatible provider/model path. Source: gaebal-gajae dogfood follow-up for the 03:30 nudge on rebuilt `./rust/target/debug/claw` `d95b230c`.