fix(statusline): guard the shim for Docker, drop the ancestor walk, remove on chip-off (#405)

Follow-ups to the delegating statusline shim from discussion #405, answering
the four design questions and the Docker one raised there.

Docker cases: the injected command is now a self-selecting shell guard,
`if [ -x <node> ] && [ -f <shim> ]; then exec <node> <shim>; fi;` followed by
the inline curl exporter. A Docker case bind-mounts the workspace, and with it
settings.local.json, at the same absolute path inside the container, but
neither the host's node nor ~/.codeman exists there, so a bare shim command
would have rendered a broken statusline in every container session. The same
string now runs the shim on the host and the curl inside the container. The
settings-save injection loop needs no docker guard for that reason; it does
skip remote attaches now, whose workingDir is a user@host pseudo-path.

Settings precedence: the shim reads exactly the three files Claude Code
documents, .claude/settings.local.json and .claude/settings.json under
workspace.project_dir (the launch directory), then ~/.claude/settings.json.
No ancestor walk and no user-level settings.local.json: delegating to a
command Claude Code would have ignored is the original failure in a new coat.

The bare word: all three paths that produced `codeman` are gone. The route
answers an unknown session with an empty body, formatSessionStatusText()
returns '' with nothing to show, and the inline fallback ends in `|| true`
(plus `curl -f`, so an HTTP error body never renders as the statusline). The
shim also treats a literal `codeman` from an older server as no telemetry and
prints nothing rather than a brand word when it has neither a delegate nor a
footer, which is what Claude Code shows a user with no statusline of their own.

Removal: turning the plan-usage chip OFF now takes the exporter out of the
workspaces of the caller's live Claude sessions. statusLineTelemetry:false is
sent only by the save that flips the chip off on that device
(statusLineTelemetryAction() in settings-ui.js), so a phone whose chip was
never on cannot strip the exporter a desktop's chip depends on; a second
device with the chip still on re-injects on its next save or session create.
Nothing in src/ called applyStatusLineConfig(dir, false) before.

Tests run the generated shim AND the injected command as real subprocesses
(the fallback half with the shim path pointed at nothing, the container's
view), plus both directions of the action field through PUT /api/settings.
Measured against the live server: a render costs ~85 ms through the shim
versus ~26 ms for the old inline curl (node start ~33 ms, the rest TLS to
the loopback HTTPS server plus the delegate spawn), off the input path.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
This commit is contained in:
Codeman maintainer committed 2026-09-14 13:45:32 +02:00
1 parent c375268879
commit d1cd7884d4
17 files changed
+623 -218

No files matched your search

+1 -1
View File
@@ -92,7 +92,7 @@ Tests: `test/docker-hosts.test.ts`, `test/docker-exec-options.test.ts`, `test/do
### Plan-usage chip (statusLine telemetry)
**Plan-usage chip** (`showPlanUsageLimits`, per-device: desktop default **ON** since 1.9.3, handhelds OFF) renders compact Claude and Codex provider rows. Claude Code (v2.1.80+) pipes a JSON blob to a configured `statusLine.command` on each render; on Pro/Max it carries a `rate_limits` object (`five_hour`/`seven_day` windows only — no Opus weekly field — each `{used_percentage 0-100, resets_at epoch-SECONDS}`). Codeman injects its OWN statusLine exporter (`generateStatusLineCommand()` in `hooks-config.ts` — it only ever adds/updates/removes a statusLine that is _ours_, never a user's hand-authored one) that POSTs the blob to `POST /api/status-telemetry`. ⚠️ **Taking that slot SHADOWS the user's own statusline**: a repo's `.claude/settings.local.json` outranks `~/.claude/settings.json`, so the inline exporter replaced whatever the user had configured globally, and a hand-run `claude` in a managed repo rendered the bare word `codeman` (what the route returns for an unknown session id). The exporter is therefore a GENERATED shim — `statusline-shim.ts` writes `dataPath('codeman-statusline-shim.mjs')`, same pattern as `deepseek-status-shim.ts`: versioned marker, refreshed when it changes, temp-and-rename because a live render can be executing the path mid-refresh. It forwards the blob and, concurrently, resolves the statusline it shadows and prints THAT; the route's footer is the fallback for when there is nothing to shadow. ⚠️ The delegate resolves at RENDER time, not injection time (walk the settings files Claude Code consults from the render dir upward, then the home ones, first non-ours wins), so editing a global statusline needs no reinjection. ⚠️ **Ownership keys on the version-free `codeman-statusline-shim` token**, and `isCodemanStatusLine()` ALSO accepts the pre-shim `/api/status-telemetry` command: drop that second form and every repo an older Codeman managed reads as hand-authored, so the upgrade refuses to touch it and the user keeps the shadowing exporter forever. The shim skips both forms when hunting a delegate, which is the same predicate serving as its loop guard. That route (auth-exempt like `/api/hook-event` — localhost-only, hook-secret-gated whenever auth is active, COD-91) parses via `usage-telemetry.ts` (pure, unit-tested), broadcasts SSE `session:statusTelemetry` (de-duped per session by `telemetrySignature` since the statusline fires on every assistant message), and returns a compact plain-text footer for the exporter to **print-through**. Main Codex subscription usage comes from the signed-in host CLI's read-only app-server `account/rateLimits/read` request at startup and every 5 minutes; `usage-telemetry.ts` selects only the main `codex` bucket (never model-specific buckets such as Spark), maps whatever 5-hour/7-day windows it supplies, and omits the provider row when unavailable. Credentials stay inside the CLI and no auth material is sent to the browser. `plan-usage-latest.ts` merges both process-wide sources and replays them in the SSE init snapshot (`getLightState`) so `#planUsageChip` renders immediately on page load/reconnect. `planUsageChipEnabled()` remains the single resolver behind the checkbox, chip visibility, and Claude create-time exporter flag. **Distinct from auto-resume** (which reacts to the Claude limit _message_; this proactively shows live percentages). Design: `docs/usage-limits-display-plan.md`. Tests: `test/usage-telemetry.test.ts`, `test/codex-plan-usage.test.ts`, `test/plan-usage-chip.test.ts`, `test/plan-usage-latest.test.ts`, `test/statusline-shim.test.ts` (runs the generated shim as a real subprocess, since tsc never sees it).
**Plan-usage chip** (`showPlanUsageLimits`, per-device: desktop default **ON** since 1.9.3, handhelds OFF) renders compact Claude and Codex provider rows. Claude Code (v2.1.80+) pipes a JSON blob to a configured `statusLine.command` on each render; on Pro/Max it carries a `rate_limits` object (`five_hour`/`seven_day` windows only, no Opus weekly field, each `{used_percentage 0-100, resets_at epoch-SECONDS}`). Codeman injects its OWN statusLine exporter (`generateStatusLineCommand()` in `hooks-config.ts`, ownership via `isCodemanStatusLine()`: it only ever adds/updates/removes a statusLine that is _ours_, never a user's hand-authored one) that POSTs the blob to `POST /api/status-telemetry`. ⚠️ **Taking that slot SHADOWS the user's own statusline** (discussion #405): a repo's `.claude/settings.local.json` outranks `~/.claude/settings.json`, so the original inline exporter replaced whatever the user had configured globally, and a hand-run `claude` in a managed repo rendered the bare word `codeman`, which three paths produced: the route's answer for an unknown session id, the exporter's own `|| echo codeman` (the one that fired outside a managed session, where `CODEMAN_API_URL` is unset and curl fails), and `formatSessionStatusText(null)`. All three now yield an EMPTY string, and the shim treats a bare `codeman` from an older server as no telemetry too. The exporter is a GENERATED shim: `statusline-shim.ts` writes `dataPath('codeman-statusline-shim.mjs')`, same pattern as `deepseek-status-shim.ts` (versioned marker, refreshed when it changes, temp-and-rename because a live render can be executing the path mid-refresh). It forwards the blob and, concurrently, resolves the statusline it shadows, runs it with the same blob on stdin and prints THAT; the route's footer is the fallback for when there is nothing to shadow or the delegate printed nothing, and with neither the shim prints nothing, which is what Claude Code shows a user with no statusline of their own. ⚠️ The delegate resolves at RENDER time, not injection time, from exactly the three files Claude Code documents: `.claude/settings.local.json` and `.claude/settings.json` under `workspace.project_dir` (the directory Claude Code was launched in; `cwd` can drift from it mid-session) and then `~/.claude/settings.json`, first non-ours wins. Two candidates are deliberately NOT consulted, because delegating to a command Claude Code itself would have ignored is the original failure in a new coat: a user-level `~/.claude/settings.local.json` (not in the documented set) and the project files of any ANCESTOR of the launch directory (Claude Code reads project settings from the launch directory alone). Late resolution means editing a global statusline needs no reinjection. ⚠️ **The injected command is a self-selecting shell guard, not a bare shim invocation**: `if [ -x <node> ] && [ -f <shim> ]; then exec <node> <shim>; fi;` followed by the inline curl exporter (`curl -sfk … || true`). A Docker case bind-mounts the workspace, and with it `settings.local.json`, at the SAME absolute path inside the container, but neither `~/.codeman` nor the host's node exists there, so the shim half cannot run and a bare shim command would have rendered a broken statusline in every container session (the settings-save injection loop has no docker guard, and needs none now). The guard makes the same string render the shim on the host and the curl inside the container; it is also what a wiped data dir or a moved node degrades to. ⚠️ **Ownership keys on EITHER marker**: the version-free `codeman-statusline-shim` token (the shim's filename, so present for every shim version) OR the `/api/status-telemetry` path (present in the pre-shim inline command and in the current command's fallback half). Drop the second and every repo an older Codeman managed reads as hand-authored, so the upgrade refuses to touch it and the user keeps the shadowing exporter forever. The shim skips both forms when hunting a delegate, which is the same predicate serving as its loop guard. ⚠️ **`statusLineTelemetry` on `PUT /api/settings` is an ACTION field in both directions.** `true` rides every save while the chip is on and (re)injects into every live Claude session's workspace (remote attaches skipped: their `workingDir` is a `user@host:session` pseudo-path the enable path would mkdir as a junk local dir); `false` rides ONLY the save that turned the chip OFF on that device (`statusLineTelemetryAction()` in settings-ui.js, pure and pinned by `test/plan-usage-telemetry-action.test.ts`) and removes our entry from those workspaces, scoped to the caller's own sessions in multi-user mode. Before 1.28 nothing in `src/` called `applyStatusLineConfig(dir, false)` at all: the call sites passed `true` deliberately, because a repo's `settings.local.json` is shared by sibling sessions and every device and one device's off must not yank the exporter another device's chip depends on, and the effect was thatLine truncated
### Cron jobs
+1 -1
View File
@@ -1,6 +1,6 @@
# Plan Usage Limits Display — Design & As-Built
> **Status: SHIPPED — deployed to prod + pushed to master, not yet released (2026-06-14).** App Settings → Display → **Plan Usage Limits** (`showPlanUsageLimits`). **Default changed in 1.9.3: desktop now defaults ON, handhelds stay OFF, resolved via `planUsageChipEnabled()`.** The per-device notes further down describing it as opt-in/synced record the original 2026-06-14 shape, not current behavior. **The exporter changed shape on 2026-09-11**: it is now a generated shim (`src/statusline-shim.ts`) that prints the statusline it shadows and falls back to the footer below only when there is nothing to shadow, so the passages describing the footer as the exporter's own output record the original shape too. See `docs/architecture-invariants.md#plan-usage-chip-statusline-telemetry`. Commits `c82f6c8` (feature) → `4d9d93d` (end-to-end fixes) → `eae225b` (per-user reconcile) → `95fb5fc` (init-snapshot replay). Full suite green (2869), CI green. No changeset/version bump yet.
> **Status: SHIPPED. Deployed to prod + pushed to master, not yet released (2026-06-14).** App Settings → Display → **Plan Usage Limits** (`showPlanUsageLimits`). **Default changed in 1.9.3: desktop now defaults ON, handhelds stay OFF, resolved via `planUsageChipEnabled()`.** The per-device notes further down describing it as opt-in/synced record the original 2026-06-14 shape, not current behavior. **The exporter changed shape in 1.28 (discussion #405)**: it is now a self-selecting shell guard that runs a generated, delegating shim (`src/statusline-shim.ts`) where the shim exists and the inline curl below where it does not (inside a Docker case's container). The shim prints the statusline it shadows and falls back to the footer below only when there is nothing to shadow; with neither it prints nothing, and the route now answers an unknown session with an empty body, so the bare word `codeman` never renders. Turning the chip OFF now also removes the exporter from live workspaces (`statusLineTelemetry:false`, sent only on the save that flips the chip off on a device), so the "removal only via the toggle" sentences below are current again and the "never remove" ones record the 1.9-1.27 shape. See `docs/architecture-invariants.md#plan-usage-chip-statusline-telemetry`. Commits `c82f6c8` (feature) → `4d9d93d` (end-to-end fixes) → `eae225b` (per-user reconcile) → `95fb5fc` (init-snapshot replay). Full suite green (2869), CI green. No changeset/version bump yet.
>
> Two surfaces from one `statusLine` callback:
> - **Header chip** (top-right) — account-wide **plan limits**: `5h 35% · 7d 38%`, per-window green/yellow/red.
+8 -4
View File
@@ -101,10 +101,14 @@ subscription plan.
**Claude only.** A header chip showing live subscription usage, on by default on desktop and
off on phones.
It works by installing a status line exporter into Claude Code, which posts Claude's own
rate limit data back to Codeman. The exporter is marker-identified, so it only ever touches
a status line Codeman installed, never one you wrote yourself, and it prints your footer
through so the in-terminal status line still works.
It works by installing a status line exporter into each managed repo's
`.claude/settings.local.json`, which posts Claude's own rate limit data back to Codeman. The
exporter is marker-identified, so it only ever touches a status line Codeman installed, never
one you wrote yourself. A repo's status line outranks the one in `~/.claude/settings.json`,
so the exporter also runs the status line it shadows and prints that instead of its own
footer: your global status line keeps rendering in managed repos, and in a repo with no
status line of your own you get Codeman's compact session footer. Turning the chip off takes
the exporter back out of the repos of your live sessions.
The chip and the exporter are the same setting. Turning the chip on without the exporter
would leave it showing a dash forever, so resolve it in one place: **App Settings**.