Merge pull request ultraworkers#2915 from ultraworkers/docs/roadmap-358-cost-help-json-hangs

docs(roadmap): add ultraworkers#358 — cost help json hangs

Author: Yeachan-Heo

ROADMAP.md

@@ -6297,3 +6297,4 @@ Original filing (2026-04-18): the session emitted `SessionStart hook (completed)
 355. **Top-level `session list` and `session help` with `--output-format json` hang with zero stdout/stderr instead of returning bounded session inventory/help or a typed unavailable response** — dogfooded 2026-04-30 for the 00:30 nudge on current `origin/main` / rebuilt `./rust/target/debug/claw` with embedded `git_sha` `8e24f304`. After rebuilding and verifying the binary provenance, repeated bounded runs of `timeout 8 ./rust/target/debug/claw session list --output-format json` exited `124` with `stdout=0` and `stderr=0`. A follow-up bounded `session help --output-format json` probe also produced no stdout/stderr before it had to be killed, so the issue is broader than inventory: even the session help path can silently hang in JSON mode. This is distinct from #354's memory help/list hang: the affected surface is session command introspection, where claws need a safe local way to enumerate resumable sessions or at least read usage before deciding whether to resume, inspect, or clean them up. **Required fix shape:** (a) make `session help` and `session list --output-format json` return bounded local JSON without waiting indefinitely on remote API/auth/session-store availability; (b) return stdout JSON with `kind:"session"`, `action:"help"|"list"`, `status`, usage or `sessions[]`, source/provenance, counts, and truncation metadata, or typed `status:"unavailable"`/`code` when backing state cannot be reached; (c) add explicit timeout diagnostics if a remote/authenticated session source is consulted; (d) add regression coverage proving both `session help --output-format json` and `session list --output-format json` return machine-readable outcomes within a deterministic budget. **Why this matters:** session inventory/help is a core recovery/control-plane path. If even help/list can hang silently with no bytes, claws cannot distinguish no sessions, missing credentials, remote API stall, corrupted local store, or dispatch deadlock, and resume/cleanup automation blocks before it can choose a safe next action. Source: gaebal-gajae dogfood follow-up for the 00:30 nudge on rebuilt `./rust/target/debug/claw` `8e24f304`.
 356. **Top-level `status --help --output-format json` exits successfully but emits plain text help instead of JSON** — dogfooded 2026-04-30 for the 01:00 nudge on current `origin/main` / rebuilt `./rust/target/debug/claw` with embedded `git_sha` `74338dc6`. After rebuilding and verifying the binary provenance, repeated bounded runs of `./rust/target/debug/claw status --help --output-format json` exited `0` with `stdout=326` and `stderr=0`, but stdout was plain text (`Status`, `Usage`, `Purpose`, `Output`, `Formats`, `Related`) rather than a JSON object. In the same rebuilt binary, `version --output-format json` returned proper stdout JSON with version/build metadata, proving the JSON output path itself is reachable. This is distinct from #354/#355 memory/session JSON help/list hangs: the status help path returns promptly, but ignores the requested JSON format. **Required fix shape:** (a) make `status --help --output-format json` emit valid stdout JSON with `kind:"help"` or `kind:"status"`, `action:"help"`, usage, options, examples, supported output formats, and related slash/direct commands; (b) preserve text help for default/text mode only; (c) add a `format:"json"` or equivalent field so callers can assert the contract without parsing prose; (d) add regression coverage proving status help with JSON format parses as JSON and does not silently fall back to plain text. **Why this matters:** help is the discovery surface automation uses before invoking status. If `--output-format json` is accepted but help remains plain text, claws must scrape formatting-sensitive prose or special-case help output, defeating the point of machine-readable CLI contracts. Source: gaebal-gajae dogfood follow-up for the 01:00 nudge on rebuilt `./rust/target/debug/claw` `74338dc6`; invalid hang PR #2907 was closed after repeated bounded repros returned promptly.
 357. **Top-level `doctor --help --output-format json` exits successfully but emits plain text help instead of JSON** — dogfooded 2026-04-30 for the 01:30 nudge on current `origin/main` / rebuilt `./rust/target/debug/claw` with embedded `git_sha` `52a909ce`. After rebuilding and verifying the binary provenance, repeated bounded runs of `./rust/target/debug/claw doctor --help --output-format json` exited `0` with `stdout=343` and `stderr=0`, but stdout was plain text (`Doctor`, `Usage`, `Purpose`, `Output`, `Formats`, `Related`) rather than a JSON object. In the same rebuilt binary, `status --help --output-format json` also returned promptly as plain text (#356), confirming a broader help-format fallback class while keeping this pinpoint on the doctor surface. This is distinct from #354/#355 memory/session JSON help/list hangs: doctor help returns promptly, but ignores the requested JSON format. **Required fix shape:** (a) make `doctor --help --output-format json` emit valid stdout JSON with `kind:"help"` or `kind:"doctor"`, `action:"help"`, usage, checks, options, examples, supported output formats, and related slash/direct commands; (b) preserve text help for default/text mode only; (c) add a `format:"json"` or equivalent field so callers can assert the contract without parsing prose; (d) add regression coverage proving doctor help with JSON format parses as JSON and does not silently fall back to plain text. **Why this matters:** doctor is the diagnostic entrypoint users reach for when things are broken. If JSON help falls back to prose, claws cannot discover diagnostic semantics or present structured recovery instructions without scraping formatting-sensitive text. Source: gaebal-gajae dogfood follow-up for the 01:30 nudge on rebuilt `./rust/target/debug/claw` `52a909ce`; invalid hang PR #2911 was closed after repeated bounded repros returned promptly.
+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`.