officerdev/platform
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

step 4/4: the docs say permissions too, and capability means one thing again

Browse Source 
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:
pastilhas
2026-08-15 16:31:11 +00:00
parent f9fd002ff4
commit 027b10bd6e
45 changed files with 721 additions and 694 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/claude-sidecar-isolation.md
+26 -26
View File
@@ -43,7 +43,7 @@ that is the sidecar running your agent. **It is not.**
```ts
name: 'proxy',
capabilities: ['proxy'],
permissions: ['proxy'],
```
and its entire job is four things (`index.ts:10-23`): take a PID lock, load state, ensure an Anthropic
@@ -73,11 +73,11 @@ The credential path is in roughly the right place; the process topology is not.
### Why the process dies — two independent mechanisms
1. **Process-tree kill.** PM2 signals the whole tree on restart, so the agent gets SIGINT even though
nothing in Officer's code asks for it. *(Inferred from PM2's default `treekill: true`;
nothing in Officer's code asks for it. _(Inferred from PM2's default `treekill: true`;
`ecosystem.config.cjs` sets no `treekill` key, so the default applies. I did not test this in
isolation.)*
isolation.)_
2. **Inherited stdio.** `sidecar-registry.ts:240-241` passes `stdout: 'inherit', stderr: 'inherit'`,
so the agent writes into *officer's* PM2 log pipes. When officer restarts those pipes close, and
so the agent writes into _officer's_ PM2 log pipes. When officer restarts those pipes close, and
subsequent writes fail. Even if the signal were suppressed, the child's output path dies with the
parent.
@@ -85,7 +85,7 @@ Both must be fixed. Fixing only the signal leaves a process writing to a closed
### Also relevant: the transport direction is inverted
`user-instance.ts:19` dials *out* to officer:
`user-instance.ts:19` dials _out_ to officer:
```ts
const API_URL = process.env.API_URL ?? `ws://127.0.0.1:${process.env.PORT ?? '5000'}`;
@@ -95,8 +95,8 @@ The agent sidecar is a **client** of officer, registering over `/api/sidecar/reg
listener, reports no port. That is the exact inverse of the compliant sidecars (slskd, music, vault),
which listen on a loopback port, report it on connect, and let officer forward to them.
This matters for survivability, not just tidiness: when officer restarts, a sidecar that *listens*
just sits there with its work intact and waits to be forwarded to again. A sidecar that *dials in* has
This matters for survivability, not just tidiness: when officer restarts, a sidecar that _listens_
just sits there with its work intact and waits to be forwarded to again. A sidecar that _dials in_ has
to notice the drop, reconnect, and re-establish identity — and anything it wanted to emit in the
meantime has nowhere to go.
@@ -107,13 +107,13 @@ process now survives. Does your session?
Not yet. Five things have to hold, and only some are about process lifetime:
| # | Requirement | Status today |
|---|---|---|
| R1 | The agent process is outside officer's process tree | **broken** — child of officer |
| R2 | The agent's stdio does not belong to officer | **broken** — `'inherit'` |
| R3 | The sidecar survives its control socket dropping, and reconnects | **probably fine** — `connect.ts` has a reconnect backoff table; not tested across a real restart |
| R4 | Events emitted while officer is down are not lost | **broken** — see below |
| R5 | The browser reconnects and asks for what it missed | **already works** — verified in Pass 2, see below |
| # | Requirement | Status today |
| --- | ---------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
| R1 | The agent process is outside officer's process tree | **broken** — child of officer |
| R2 | The agent's stdio does not belong to officer | **broken** — `'inherit'` |
| R3 | The sidecar survives its control socket dropping, and reconnects | **probably fine** — `connect.ts` has a reconnect backoff table; not tested across a real restart |
| R4 | Events emitted while officer is down are not lost | **broken** — see below |
| R5 | The browser reconnects and asks for what it missed | **already works** — verified in Pass 2, see below |
**R5 is done, and that is better news than I expected.** The frontend already auto-reconnects with
backoff (`hooks/src/useChatWebSocket.ts:46-58`, `Math.min(5000, 300 * retry)`), already tracks a
@@ -130,7 +130,7 @@ The backend half exists too (`chat/websocket.ts:612-629`, `getChatEventsSince`).
"Disconnected" indicator in the UI (`ChatHistory/ChatDetailPanel.tsx:38-52`).
So **the sequence-and-replay protocol I was about to propose building already exists end to end.** The
only thing wrong with it is *who writes the events*. That collapses Stage 2 below from "design a
only thing wrong with it is _who writes the events_. That collapses Stage 2 below from "design a
durable outbox" to "move the writer" — the single biggest simplification in this plan.
One gap to close while moving it: nothing verifies sequence continuity. `resume-cursor` is only sent
@@ -175,7 +175,7 @@ With the data flow inverted to match slskd:
`server.tsx:164-228` (dev-server) and `server.tsx:323-326` → `api/vault/websocket.ts` (vault).
- The sidecar **writes its own events to Postgres** with a monotonic per-session sequence number. It
already imports `officerdb` (`user-instance.ts:10`), so this is established precedent, not a new
capability. Officer stops touching `chat_session_events` entirely.
permission. Officer stops touching `chat_session_events` entirely.
- On reconnect the browser sends `since=<seq>` and the **sidecar** answers the replay. Officer relays
the question and the answer, and interprets neither.
@@ -208,14 +208,14 @@ The minimum fix for R1 + R2. Two routes, and I'd want your view on which:
`ensureClaudeSidecar` / `spawnAndWaitForRegistration` (`sidecar-registry.ts:198-274`, ~77 lines
including the 50ms registration poll). Officer no longer spawns anything.
- *Pro:* correct, matches every other sidecar, PM2 restarts and logs it properly.
- *Con:* the per-email spawn model has to go or change — see the open question below.
- _Pro:_ correct, matches every other sidecar, PM2 restarts and logs it properly.
- _Con:_ the per-email spawn model has to go or change — see the open question below.
**1b. Detach the spawn.** Keep on-demand spawning but `detached: true`, own stdio to its own log file,
own process group.
- *Pro:* smallest diff, keeps lazy startup.
- *Con:* leaves an unmanaged process PM2 can't see or restart. I think this is the wrong end state,
- _Pro:_ smallest diff, keeps lazy startup.
- _Con:_ leaves an unmanaged process PM2 can't see or restart. I think this is the wrong end state,
but it might be a legitimate first step if you want the survivability today.
After this stage: the process survives, the socket reconnects, **but output produced during the
@@ -265,7 +265,7 @@ reads its settings from. The whole chain — unauthenticated endpoint, sidecar `
`panel-refresh` frame, `onPanelRefresh` prop — was deleted on 2026-08-04. The Chat panel already does the
same job from `onTurnComplete`, in-process, with no hook and no HTTP round trip.
### Stage 5 — the harder question: surviving a *sidecar* restart
### Stage 5 — the harder question: surviving a _sidecar_ restart
Stages 1-4 make the agent survive an **officer** restart. They do not make it survive a restart of the
agent sidecar itself — the agent process is that sidecar's child by design.
@@ -286,9 +286,9 @@ is a real design decision and I don't have a confident recommendation.
1. ~~**Is the per-email spawn model dead weight?**~~ — **answered 2026-08-07: yes, it is.** The
question was whether multi-tenancy might later need the per-email fan-out (`claude:${email}`, the
`claudeProcs` and `claudeSpawnWaiters` Maps, the per-email PID lock). The capability model settled
it in the *other* direction from what "the platform is going multi-user" would suggest: `chat` is
`kind: 'execution'` in `capabilities/registry.ts`, which is **never grantable at any level**,
`claudeProcs` and `claudeSpawnWaiters` Maps, the per-email PID lock). The permission model settled
it in the _other_ direction from what "the platform is going multi-user" would suggest: `chat` is
`kind: 'execution'` in `permissions/registry.ts`, which is **never grantable at any level**,
because the agent runs as the owner's OS user with `--dangerously-skip-permissions`. Additional
accounts exist now, and not one of them can ever open a chat.
@@ -299,7 +299,7 @@ is a real design decision and I don't have a confident recommendation.
2. **Relay or redirect?** Officer proxies the agent WebSocket (one origin, keeps your HTTPS reverse
proxy and JWT model intact, but a restart still drops the socket for a moment), or officer hands
the browser a short-lived token and the browser connects to the sidecar directly (survives an
officer restart *without even a reconnect*, but needs its own TLS/origin story and a second
officer restart _without even a reconnect_, but needs its own TLS/origin story and a second
exposed port). I lean relay — the reconnect is cheap once Stage 2 makes it lossless — but the
direct path is the only one where you genuinely never notice.
@@ -329,7 +329,7 @@ is a real design decision and I don't have a confident recommendation.
## Verified vs not
**Verified by reading the code or inspecting the running system:** my process ancestry; that
`officer-claude` runs `sidecar/claude/index.ts` and registers as `proxy` with no spawn capability;
`officer-claude` runs `sidecar/claude/index.ts` and registers as `proxy` with no spawn permission;
that `user-instance.ts` has no PM2 entry and is spawned only at `sidecar-registry.ts:238` with
inherited stdio; that it dials out rather than listening; that events leave via `connection.send`;
that officer persists and replays them; that `--resume` is in my own argv; the two port defaults; the