From dbd04ad33401ab55e8e28fb61ed32d9cb38449b2 Mon Sep 17 00:00:00 2001 From: Yeachan-Heo Date: Wed, 20 May 2026 06:31:24 +0000 Subject: [PATCH] docs(roadmap): add interactive alias help hang --- ROADMAP.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/ROADMAP.md b/ROADMAP.md index 8678c8e3..77d482bc 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -6519,3 +6519,5 @@ Original filing (2026-04-18): the session emitted `SessionStart hook (completed) 481. **Slash-only top-level aliases (`files`, `hooks`, `memory`) emit a useful bare resume-only error, but `--help` hangs with zero output, so users cannot discover the documented resume-safe command shape from the command they just tried** — dogfooded 2026-05-20 from the `#clawcode-building-in-public` 05:30 UTC nudge on `/home/bellman/Workspace/claw-code-pr2967` with branch/origin `docs/roadmap-workdir-provenance@51e6040` and binary `./rust/target/debug/claw` built from source SHA `25d663d`. Clean-home probes show the bare aliases are bounded: `claw files`, `claw hooks`, and `claw memory` each exit 1 with `[error-kind: unknown]` and a helpful message: `Use \`claw --resume SESSION.jsonl /\` or start \`claw\` and run \`/\`.` Their JSON forms are also bounded (`files --output-format json`, `hooks --output-format json`, `memory --output-format json`) with the same message in a JSON error envelope. But adding the most natural discovery flag hangs: `claw files --help`, `claw hooks --help`, and `claw memory --help` each timed out after 6s with `stdout=0`/`stderr=0`. In the same clean-home sweep, real top-level local verbs (`config`, `config --help`, `config env --output-format json`) returned immediately, proving this is specific to slash-only alias help fallback. **Required fix shape:** (a) centralize slash-only alias handling so `--help`/`help` never enter prompt/runtime dispatch; (b) return a bounded help page for every slash-only alias, including direct CLI usage (`claw --resume SESSION.jsonl /files`) and whether the command is resume-safe; (c) make JSON help/error envelopes include `kind:"slash_command_alias"`, `slash:"/files"`, `resume_required:true`, and supported resume forms; (d) add clean-home regressions for bare, `--help`, `help`, and JSON forms for `files`, `hooks`, `memory`, plus the already-found `session` sibling (#480). **Why this matters:** these are exactly the diagnostic surfaces users reach for during prompt misdelivery and stale-session debugging. A helpful bare error followed by a zero-byte hang on `--help` is a recovery dead-end. Source: gaebal-gajae dogfood response to Clawhip message `1506529436466675713` on 2026-05-20. 482. **Session-inspection slash aliases (`cost`, `stats`, `history`, `tokens`) have bounded bare/JSON resume-only errors, but `--help` hangs with zero output, extending the slash-alias help dead-end to the telemetry/recovery commands users need during stale-session debugging** — dogfooded 2026-05-20 from the `#clawcode-building-in-public` 06:00 UTC nudge on `/home/bellman/Workspace/claw-code-pr2967` with branch/origin `docs/roadmap-workdir-provenance@111e7e8` and binary `./rust/target/debug/claw` built from source SHA `25d663d`. Clean-home sweep showed local direct verbs behave differently: `diff` returns bounded no-git text/JSON and rejects `diff --help` with a bounded `unexpected extra arguments`; interactive-only write verbs (`commit`, `pr`, `issue`) return bounded bare/JSON errors and `--help` prints the global help. The broken cluster is the resume-safe telemetry alias family: `claw cost`, `claw stats`, `claw history`, and `claw tokens` each exit 1 with a useful resume-only message (`Use \`claw --resume SESSION.jsonl /\` or start \`claw\` and run \`/\`.`), and their `--output-format json` forms return bounded JSON error envelopes, but `claw cost --help`, `claw stats --help`, `claw history --help`, and `claw tokens --help` time out after 6s with `stdout=0`/`stderr=0`; the sweep had to be killed while stuck at `tokens --help`. **Required fix shape:** (a) fold the resume-safe telemetry slash aliases into the centralized slash-only alias help handler proposed in #481; (b) for each alias, return bounded text/JSON help listing the `--resume SESSION.jsonl /` form, accepted optional args (`history [count]`), and JSON support status; (c) do not fall through to prompt/runtime dispatch when `--help` follows any known slash alias; (d) add clean-home regressions for bare, `--help`, `help`, and JSON forms for `cost`, `stats`, `history`, `tokens`, `cache`, and `providers`. **Why this matters:** these commands are the observability surface for event/log opacity and stale-session confusion. If the first attempt to ask for help on `/tokens` or `/history` silently hangs, operators cannot tell whether the session store, runtime, or help parser is broken. Source: gaebal-gajae dogfood response to Clawhip message `1506536984976425070` on 2026-05-20. + +483. **Interactive-only slash aliases (`approve`, `deny`, `model`) hang on `--help`, while `permissions --help` already returns bounded inline usage, proving the alias-help behavior is inconsistent within the same command family** — dogfooded 2026-05-20 from the `#clawcode-building-in-public` 06:30 UTC nudge on `/home/bellman/Workspace/claw-code-pr2967` with branch/origin `docs/roadmap-workdir-provenance@625b8b0` and binary `./rust/target/debug/claw` built from source SHA `25d663d`. Clean-home sweep: `claw approve`, `claw deny`, and `claw model` each exit 1 with a bounded interactive-only message (`Start \`claw\` and run \`/\` inside the REPL.`), and their `--output-format json` forms return bounded JSON error envelopes. But `claw approve --help`, `claw deny --help`, and `claw model --help` time out after 6s with `stdout=0`/`stderr=0`. Same sweep shows a nearby positive control: `claw permissions --help` exits 1 with the interactive-only message plus an inline usage block (`Usage /permissions [read-only|workspace-write|danger-full-access]`). Resume-safe siblings `cache`, `providers`, and `clear` also still hang on `--help`, matching #481/#482. **Required fix shape:** (a) extend the centralized slash-alias help handler to interactive-only aliases, not just resume-safe aliases; (b) model it after the existing bounded `permissions --help` behavior, returning the interactive-only reason plus per-command usage; (c) include aliases (`/approve` = `/yes`/`/y`, `/deny` = `/no`/`/n`) in help text/JSON; (d) add clean-home regressions for `approve --help`, `deny --help`, `model --help`, `debug-tool-call --help`, and assert `permissions --help` remains bounded. **Why this matters:** permission prompts and model switching are high-friction startup/operator surfaces. If users naturally type `claw approve --help` or `claw model --help`, the CLI must explain that these are REPL-only instead of silently hanging and looking like a dead runtime. Source: gaebal-gajae dogfood response to Clawhip message `1506544532026687562` on 2026-05-20.