step 4/4: the docs say permissions too, and capability means one thing again
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.
This commit is contained in:
@@ -17,7 +17,7 @@ A sidecar is a **PM2 peer of `officer`** — never a child. It dials _in_; offic
|
||||
```
|
||||
PM2 starts it → it binds its own ephemeral port (if it serves HTTP)
|
||||
→ it opens a WS to officer at /api/sidecar/register
|
||||
→ it sends { type:'register', name, capabilities[] }
|
||||
→ it sends { type:'register', name, permissions[] }
|
||||
→ officer replies { type:'registered', id }
|
||||
→ it sends { type:'<name>:server', port } (HTTP sidecars only)
|
||||
→ officer remembers the port and proxies <prefix>/* to it
|
||||
@@ -26,10 +26,10 @@ PM2 starts it → it binds its own ephemeral port (if it serves HTTP)
|
||||
Officer's side of that is `src/servers/sidecar-registry.ts`; the sidecar's side is
|
||||
`src/servers/sidecar/connect.ts`.
|
||||
|
||||
**Nothing in this path is officer starting a process.** `waitForCapability` in the registry says so
|
||||
**Nothing in this path is officer starting a process.** `waitForPermission` in the registry says so
|
||||
explicitly — it replaced ~77 lines of spawn-and-poll (`ensureClaudeSidecar`,
|
||||
`spawnAndWaitForRegistration`, and per-email process maps). The only startup problem left is _ordering_,
|
||||
handled by waiting up to 15s for a capability to appear rather than failing the first request after boot.
|
||||
handled by waiting up to 15s for a permission to appear rather than failing the first request after boot.
|
||||
|
||||
---
|
||||
|
||||
@@ -56,11 +56,11 @@ the reconnect loop. The ecosystem file says so in a comment, which is the right
|
||||
Four things, and three of them fail loudly if missed.
|
||||
|
||||
1. **A PM2 entry** in `ecosystem.config.cjs` (`script: 'bun'`, `args: 'run src/servers/sidecar/<n>/index.ts'`).
|
||||
2. **A registration** with a `name` and `capabilities[]`. Officer indexes by capability, not by name —
|
||||
`findSidecarByCapability` is how every caller reaches one.
|
||||
2. **A registration** with a `name` and `permissions[]`. Officer indexes by permission, not by name —
|
||||
`findSidecarByPermission` is how every caller reaches one.
|
||||
3. **A `'<name>:server'` event in `protocol.ts`**, if it serves HTTP. Without it the type does not exist
|
||||
and `createSidecarProxy`'s listener never matches.
|
||||
4. **A capability-registry entry**, if it mounts a router. `assertCapabilityTotality` runs in
|
||||
4. **A permission-registry entry**, if it mounts a router. `assertPermissionTotality` runs in
|
||||
`server.tsx` _before_ `serve()` and **throws**, so a missing entry means the server refuses to boot,
|
||||
naming what is missing. Alternatively an `EXEMPT_API_PREFIXES` entry _with a stated reason_.
|
||||
|
||||
@@ -102,19 +102,19 @@ contains two entrypoints that register as _different sidecars_:
|
||||
|
||||
| File | PM2 entry | Registers as | What it is |
|
||||
| ------------------------- | ------------------------- | ------------------------------------ | ---------------------------------------------------- |
|
||||
| `claude/index.ts` | `officer-anthropic-proxy` | name `proxy`, capability `['proxy']` | Holds the Anthropic credential, forwards API traffic |
|
||||
| `claude/user-instance.ts` | `officer-agent` | capability `['claude']` | The process that actually spawns `claude` |
|
||||
| `claude/index.ts` | `officer-anthropic-proxy` | name `proxy`, permission `['proxy']` | Holds the Anthropic credential, forwards API traffic |
|
||||
| `claude/user-instance.ts` | `officer-agent` | permission `['claude']` | The process that actually spawns `claude` |
|
||||
|
||||
So **capability `proxy` is the Anthropic proxy, and capability `claude` is the agent.** Nothing named
|
||||
"claude" registers the `claude` capability from `claude/index.ts`, which is exactly the sort of thing
|
||||
So **permission `proxy` is the Anthropic proxy, and permission `claude` is the agent.** Nothing named
|
||||
"claude" registers the `claude` permission from `claude/index.ts`, which is exactly the sort of thing
|
||||
that reads as a bug in a grep and is not one.
|
||||
|
||||
That resolves the special-casing: `isConnected()` returns "a sidecar with capability `proxy` exists" —
|
||||
That resolves the special-casing: `isConnected()` returns "a sidecar with permission `proxy` exists" —
|
||||
i.e. **the Anthropic proxy is up**, which is _not_ the same as "the agent is up", though the name reads
|
||||
that way. `[verified]` It currently has **no callers** outside the registry itself, so nothing is
|
||||
misreading it today. Worth either renaming or deleting before something starts trusting the name.
|
||||
|
||||
`registerSidecar` also fires a notification when a registration includes capability `claude`
|
||||
`registerSidecar` also fires a notification when a registration includes permission `claude`
|
||||
(`sidecar-registry.ts:75`) — "a new agent process has come up". That one is correctly aimed at the agent.
|
||||
|
||||
---
|
||||
@@ -135,11 +135,11 @@ lines?
|
||||
|
||||
## Open questions, in the order I would answer them
|
||||
|
||||
1. ~~What provides the `proxy` capability~~ — **answered above**: the Anthropic proxy, not the agent.
|
||||
1. ~~What provides the `proxy` permission~~ — **answered above**: the Anthropic proxy, not the agent.
|
||||
`isConnected()` has no callers; rename or delete it before its name misleads someone.
|
||||
2. **Is the sidecar-side boilerplate worth factoring**, given `create-proxy.ts` already proved the
|
||||
officer side was?
|
||||
3. **What happens on a partial boot** — officer up, a sidecar permanently down. `waitForCapability`
|
||||
3. **What happens on a partial boot** — officer up, a sidecar permanently down. `waitForPermission`
|
||||
throws after 15s; who catches it, and what does the user see?
|
||||
4. **Is the `PORT ?? '5000'` fallback reachable**, and should it fail loudly instead?
|
||||
5. **`sweepStaleServes` is `/proc`-based and a no-op on macOS** (already noted in the OpenCode parity
|
||||
@@ -149,13 +149,13 @@ lines?
|
||||
|
||||
## Verified facts this document rests on
|
||||
|
||||
| Claim | How |
|
||||
| -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
|
||||
| 20 PM2 entries, 18 sidecar dirs | `ecosystem.config.cjs`, `ls src/servers/sidecar/` |
|
||||
| 16 sidecars report a port, 2 do not | `grep` for `':server'` in each `index.ts`, cross-checked against 16 declarations in `protocol.ts` |
|
||||
| `pty` is node + `.mjs` + its own reconnect loop | `ecosystem.config.cjs` comment and `ls sidecar/pty/` |
|
||||
| Officer spawns nothing | `waitForCapability` comment; no spawn call in the registry |
|
||||
| Ports change across restarts and officer follows | observed live tonight across five photos restarts |
|
||||
| Boot fails on a missing capability entry | `assertCapabilityTotality` throws before `serve()` |
|
||||
| `sidecar/claude/` is two processes with different capabilities | `ecosystem.config.cjs` args + the two `createSidecarConnector` calls |
|
||||
| `isConnected()` has no callers outside the registry | grep across `src/servers` |
|
||||
| Claim | How |
|
||||
| ------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
|
||||
| 20 PM2 entries, 18 sidecar dirs | `ecosystem.config.cjs`, `ls src/servers/sidecar/` |
|
||||
| 16 sidecars report a port, 2 do not | `grep` for `':server'` in each `index.ts`, cross-checked against 16 declarations in `protocol.ts` |
|
||||
| `pty` is node + `.mjs` + its own reconnect loop | `ecosystem.config.cjs` comment and `ls sidecar/pty/` |
|
||||
| Officer spawns nothing | `waitForPermission` comment; no spawn call in the registry |
|
||||
| Ports change across restarts and officer follows | observed live tonight across five photos restarts |
|
||||
| Boot fails on a missing permission entry | `assertPermissionTotality` throws before `serve()` |
|
||||
| `sidecar/claude/` is two processes with different permissions | `ecosystem.config.cjs` args + the two `createSidecarConnector` calls |
|
||||
| `isConnected()` has no callers outside the registry | grep across `src/servers` |
|
||||
|
||||
Reference in New Issue
Block a user