44 files of prose — CLAUDE.md, AGENTS.md, TODO.md, 20 docs, both plugin design
documents, and the comment surface the earlier steps could not reach.
Applied against an explicit keep-list, not swept, because the word turned out to
have SIX meanings in this repository rather than the three the offscale doc
recorded:
permissions renamed (steps 1–2)
$OFFICER_ROOT/capabilities/ KEPT — the item store, and now the only thing
the word means that is ours
sidecar routing keys renamed to `handles` (step 3)
Lightning wallet KEPT — a domain term, and on the wire to the mobile apps
terminfo queries KEPT — XTGETTCAP, in the pty sidecar
InvoiceShelf KEPT — per-resource { write, bulkDelete } flags
The sweep still falsified two things, both caught by checking rather than by
review, and both in prose that discusses more than one meaning at once:
CLAUDE.md began claiming the item store lives at `$OFFICER_ROOT/permissions`.
It does not; that directory is on disk and full of skills and tools.
And the offscale doc's own note about the collision became
"Named `permissions`, NOT `permissions`" — a sentence that had eaten the thing
it existed to warn about.
Both restored, and the note rewritten to say what is now true: capability means
one thing of ours, and three that belong to somebody else's vocabulary.
Verified live after restart: self and admin permission endpoints 200, gated
route 200, agent-status 200, 9 grants intact with 6 permissions offered.
tsgo clean, 797 tests, 787 pass, same 7.
The rename is done. Four steps, no data lost, no client break that survived
the step it was introduced in.
Investigation notes, written as they were gathered rather than after the fact. No code changes.
Covers how a sidecar comes into existence: PM2 peer, dials in to /api/sidecar/register, reports an
ephemeral port, officer proxies to it. Officer spawns nothing — the only startup problem left is
ordering, handled by waiting on a capability rather than failing the first request.
The finding worth having: `sidecar/claude/` is TWO processes, and they register as different sidecars.
`claude/index.ts` is officer-anthropic-proxy and registers capability `proxy`; `claude/user-instance.ts`
is officer-agent and registers capability `claude`. So `isConnected()` — defined as "a sidecar with
capability proxy exists" — means the Anthropic proxy is up, not the agent, which is not what the name
suggests. It has no callers today, so nothing is misreading it yet.
Marks what is unverified and what is still open rather than presenting the lot as settled: the
bind-read-release race in getFreePort, whether the `PORT ?? 5000` fallback is reachable, what a partial
boot looks like, and whether the sidecar-side boilerplate is worth factoring the way create-proxy.ts
factored officer's side.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
pastilhas
