d0zingcat/claude-code
1
0
Fork 0
mirror of https://github.com/instructkr/claude-code.git synced 2026-05-22 21:56:45 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs(roadmap): add diagnostics warning hang gap

Browse Source
This commit is contained in:
Yeachan-Heo
2026-05-21 15:01:16 +00:00
parent 8d0dc50cef
commit 0a2542abf7
1 changed files with 2 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
ROADMAP.md
View File

@@ -6643,3 +6643,5 @@ Original filing (2026-04-18): the session emitted `SessionStart hook (completed)
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.
544. **Local help-topic commands (`export --help`, `status --help`, `version --help`, `bootstrap-plan --help`) hang in normal env when the deprecated settings warning is present, so usage discovery is blocked by a non-fatal config migration warning** — dogfooded 2026-05-21 from the `#clawcode-building-in-public` 14:30 UTC nudge on `/home/bellman/Workspace/claw-code-pr2967` with branch/origin `docs/roadmap-workdir-provenance@785d4bd` and binary built from source SHA `25d663d`. Reproduction in the operator's normal env: bounded probes `timeout --kill-after=1s 5s ./rust/target/debug/claw export --help --output-format json`, `status --help --output-format json`, and `version --help --output-format json` each exited 124 with zero stdout and only `warning: /home/bellman/.claw/settings.json: field "enabledPlugins" is deprecated (line 2). Use "plugins.enabled" instead` on stderr; `bootstrap-plan --help --output-format json` entered the same wait before the sweep was killed. Code already has `parse_local_help_action` and `LocalHelpTopic` support for these commands, so help rendering should be a pure parser/static-output path. Instead, the presence of a config deprecation warning appears to push even `--help` into the same startup/config/plugin wedge as #543's inventory commands. **Required fix shape:** (a) route local help-topic requests before any config/plugin/runtime loading that can emit warnings or hang; (b) guarantee `claw <local-command> --help --output-format json` produces bounded static JSON independent of user config validity/deprecation state; (c) if warnings are intentionally collected, attach them only after the help payload as structured `warnings[]`, never as a blocking stderr prelude; (d) add fixture regressions with deprecated `enabledPlugins` for `export/status/version/bootstrap-plan --help --output-format json` plus text-mode controls; (e) audit all `LocalHelpTopic` variants for the same warning-induced hang. **Why this matters:** help is the recovery path when startup/config is broken. If a deprecated config warning prevents help from rendering, users cannot learn the command contract needed to fix the config or avoid the bad path. Source: gaebal-gajae dogfood response to Clawhip message `1507027716191551630` on 2026-05-21.
545. **Core local diagnostics (`doctor`, `status`, `sandbox`, `config env`, `state`) hang in normal env when the deprecated settings warning is present, so the config-warning wedge blocks both inventory/help and the primary health surfaces** — dogfooded 2026-05-21 from the `#clawcode-building-in-public` 15:00 UTC nudge on `/home/bellman/Workspace/claw-code-pr2967` with branch/origin `docs/roadmap-workdir-provenance@8d0dc50` and binary built from source SHA `25d663d`. Reproduction in the operator's normal env: bounded probes `timeout --kill-after=1s 5s ./rust/target/debug/claw doctor --output-format json`, `status --output-format json`, `sandbox --output-format json`, `config env --output-format json`, and `state --output-format json` each exited 124 with zero stdout and only `warning: /home/bellman/.claw/settings.json: field "enabledPlugins" is deprecated (line 2). Use "plugins.enabled" instead` on stderr. #543 captured inventory commands and #544 captured help topics; this entry shows the same non-fatal migration warning also disables the core health/config/state probes users need to diagnose startup. These commands are local and should be resilient to partial/deprecated config, especially `doctor`, whose purpose is to classify config problems. **Required fix shape:** (a) move deprecation collection into the diagnostic payload path instead of printing-and-wedging before command dispatch; (b) make `doctor/status/sandbox/config/state` produce bounded JSON even when config has deprecated fields, with `warnings[]` and `status:"degraded"` where appropriate; (c) guarantee `doctor` never depends on successful modern config normalization to report config migration issues; (d) add fixture regressions with `settings.json` containing `enabledPlugins` for all five probes, asserting non-timeout, nonzero/zero exit semantics as documented, and structured warning metadata; (e) unify this with #543/#544 as one startup/config-warning no-hang invariant across every local command. **Why this matters:** users run `doctor`, `status`, and `config env` precisely when startup/config looks wrong. If a deprecated config warning makes those commands hang with no JSON, the CLI loses its self-diagnostic escape hatch and every support workflow devolves into manual stderr archaeology. Source: gaebal-gajae dogfood response to Clawhip message `1507035269830934600` on 2026-05-21.