platform/COMMS/sidecar-app-store/2026-08-11-per-user-claude-handoff.md

# Handoff — per-user Claude, 2026-08-11

Branch `sidecar-app-store`, based on `48ed171`. **Three files, uncommitted at the time of writing.** This is
the start of item 4 in `2026-08-11-per-user-accounts-handoff.md` §6 ("Per-user Claude"), and it revises two
claims that handoff and `docs/per-user-linux-accounts.md` both make.

Written for the agent on the production host, to read **before** running any of it. Nothing here has been
executed against a real member account. Items 1–3 of the earlier handoff (bind mount, terminal replay,
`deprovisionOsAccount`) were deliberately skipped on the owner's instruction and are still open.

---

## 1. The claim that changed, and why it matters

`docs/per-user-linux-accounts.md:226-229` says `query()` from `@anthropic-ai/claude-agent-sdk` "spawns
`claude` itself and takes `env`/`cwd` but has nowhere to put a uid", concluding that dropping privileges must
happen *outside* the SDK, which makes a member's turn "its own process — a change of shape rather than a
flag."

**That is stale.** The installed SDK exposes exactly that hook:

```
node_modules/@anthropic-ai/claude-agent-sdk/sdk.d.ts:951
  spawnClaudeCodeProcess?: (options: SpawnOptions) => SpawnedProcess;
sdk.d.ts:936  "Custom function to spawn the Claude Code process.
               Use this to run Claude Code in VMs, containers, or remote environments."
```

`SpawnOptions` (`sdk.d.ts:2006`) supplies `{command, args, cwd, env, signal}`; `SpawnedProcess`
(`sdk.d.ts:1965`) wants `{stdin: Writable, stdout: Readable, killed, exitCode, kill(sig), on('exit'|'error')}`
— which is what `node:child_process.spawn` returns natively. So the existing sidecar can wrap the CLI spawn in
`sudo setpriv` per turn. No second sidecar, no new PM2 entry, no inverted transport.

**VERIFIED:** the type declarations above, and that `bunx tsgo` passes with an implementation written against
them. Installed SDK is **0.2.59**; `package.json:31` pins `^0.2.41`.

**NOT VERIFIED:** that the hook behaves as documented at runtime. It has never been called. If it turns out
the SDK also needs to reach the spawned process in a way `setpriv` breaks, this whole approach is wrong and
the fallback is the earlier plan (member turn as its own process).

Second stale claim, already retracted once by the previous handoff §5:
`docs/per-user-linux-accounts.md:230` said a member's `claude` "needs only `ANTHROPIC_BASE_URL` pointed at the
proxy and no key of its own." That is backwards — the proxy holds the **owner's** credential
(`sidecar/claude/proxy.ts:7` reads the owner's own `~/.claude/.credentials.json`), so pointing a member at it
spends the owner's account on their turns.

**Both passages have now been corrected in `docs/per-user-linux-accounts.md`** (same commit range as the code).
The superseded text is in that file's git history. If you are reading this handoff against an older checkout,
the doc is the one that moved.

---

## 2. Architecture: the platform never runs as a member

The owner's constraint, and the design follows it: **there is never a platform process running under a
member's uid.** The platform runs once as the service user and spawns everything.

This also rules out the tempting reading of "each member runs their own Claude" — a second `officer-agent`
under their uid. It does not work, for a reason worth stating because it looks like plumbing and is actually a
boundary. That sidecar needs `POSTGRES_URL` (it imports `officerdb` at `user-instance.ts:19`) and the JWT
signing secret (it mints a 30-day owner token for the MCP tools at `user-instance.ts:72`). A member-uid
process holding those could read every account's data and sign a token as the owner — strictly more than
their shell can do. `docs/per-user-linux-accounts.md:60-82` already forbids this shape: `.env` is 600 and
`assertSecretsClosed` refuses to boot with `OFFICER_OS_USERS` on while it is group- or world-readable.

So the split is:

| | runs as | holds |
|---|---|---|
| `officer-agent` (the harness) | service user | DB, JWT, MCP config, session log |
| `claude` (the member's turn) | **the member** | their binary, their `~/.claude` credential, their home |

This is the pty sidecar's established shape — one process, per-request identity, privileges dropped at the
point the member's code starts (`sidecar/pty/sessions.mjs:85-93`, `:113-125`). It is not a new pattern.

**It also avoids the registry rework.** A second sidecar would have needed one: registration is name-keyed and
a same-named sidecar evicts the incumbent (`sidecar-registry.ts:52-57`), `RegisteredSidecar` has no identity
field, and all nine claude verbs resolve by capability with no selector (`sidecar-registry.ts:275-402`).
Under the one-sidecar shape none of that has to change.

---

## 3. What is in the tree

### `src/servers/os-user-claude.ts` (new)

- `provisionClaudeCli({email, osUser})` — runs `curl -fsSL https://claude.ai/install.sh | sh` **as the
  member**, via `runAs`. Same installer the owner's own install uses (`scripts/setup.sh:853`), chosen there
  for auto-update support. Per-member binary rather than a shared one is the owner's explicit decision:
  everything Claude-related is user-specific, and a root-owned binary is one a member cannot update.
- Idempotent by **skipping when the binary is present**, not by re-running the installer. The retry button
  reprovisions on every press; re-downloading would cost a network round trip per press and would quietly move
  a member off a version they had updated to.
- `claudeLoginState({email, osUser})` — `{installed, loggedIn}`. Login marker is
  `~/.claude/.credentials.json`, **not** `~/.claude.json` (which holds settings/history and appears on first
  run regardless).
- Both checks run **as the member**, not as root. A `true` then means the member's own process can reach those
  files, which is what the answer gets used to promise. This deviates from the earlier handoff §6.4, which
  said "detect login by reading `~/.claude` as root" — deliberately.
- Never throws; returns a result. Same posture as SSH/shell/Docker in `provisionOsAccount`.

### `src/servers/sidecar/claude/spawn-as-member.ts` (new)

The `spawnClaudeCodeProcess` implementation, built on the existing `runAsArgv` (`os-user.ts:95`) — i.e.
`sudo -n setpriv --reuid --regid --init-groups --reset-env --`.

- **Env is an allowlist, not a filter** (`ALLOWED_ENV`). At the moment of the call, the calling process's
  environment contains `POSTGRES_URL`, the JWT secret and the owner's `ANTHROPIC_API_KEY`. A denylist would
  have to be right about every variable that exists now and every one added later. `--reset-env` means
  nothing crosses unless written into the argv (`os-user.ts:120-124`), so the allowlist is the complete
  answer to "what can this turn see".
- `NEVER_ENV` throws rather than leaks if someone later widens the allowlist or the SDK starts merging its own
  environment into `SpawnOptions.env`.
- Sets `HOME` and `CLAUDE_CONFIG_DIR` to the member's home explicitly. `--reset-env` already sets `HOME` from
  their passwd entry, so `CLAUDE_CONFIG_DIR` is belt — but "which account's credential did this turn use"
  should be answerable by reading one line.
- Uses `node:child_process`, not `Bun.spawn`: its return value satisfies `SpawnedProcess` (Bun gives web
  streams and no emitter), and `Bun.spawn` silently ignores `uid`/`gid` anyway (`os-user.test.ts:23`).

### `src/servers/api/users/provision-os.ts` (modified)

`provisionClaudeCli` called after `seedShellConfig`, before `provisionRootlessDocker`. Non-fatal. Error
precedence is now ssh → claude → shell → docker.

---

## 4. What is NOT wired — read this before testing

**`spawn-as-member.ts` is never called.** `claude-manager.ts:350-352` still passes the owner's `CLAUDE_BIN`
(`:31`), `HOST_HOME` (`:35`) and `cleanEnv` (`:315`) into `query()`. The remaining work is threading a
`MemberRun` through `ClaudeSpawnStreamingParams` and the sidecar protocol so a turn carries whose it is.

**Therefore both owner gates must stay up:**

- `src/servers/api/chat/chat.ts:49-53` — HTTP refusal of non-owners
- `src/server.tsx:214-217` — chat socket refusal

Pinned by `capabilities/registry.test.ts:157-170` and `:180-185` so one cannot move without the other.
Lifting either now would run a member's turn **as the owner, with the owner's credential** — the exact
failure they exist to prevent. Do not lift them to "see if it works".

Note `chat` is already granted at `write` for every role by default (`f0af723`, seeded at bootstrap), so the
permission is live and the route refusal is the only thing standing in the way.

**Still owner-bound, untouched:**

- `api/chat/claude-sessions.ts:25` — `claudeHome` is a private copy of the owner-home logic; discards its
  `email` whenever `HOME_DIR` is set. This is the transcript-history half.
- `api/chat/websocket.ts:51-60` — `resolveCwd`/`resolveBaseCwd` expand `~` against `getOwnerHomeDir`.
- `workspaces/officerdev/src/apps/ChatHistory/PwdSelector.tsx:12` — shortens with `/^\/home\/[^/]+/`, which
  will not match a member's `DATA_PATH/<email>/home`. Cosmetic. The pwd picker itself is already per-caller
  correct via `DirPickerModal.tsx:16` → `useFilesAPI('home')` → `rootDir`.

The pattern for all of these is `resolveHomeDir` in `src/servers/user-home.ts:34`, which already exists from
the file-browser move.

---

## 5. Verified vs assumed

**VERIFIED on the dev machine:**

- `bunx tsgo` clean across the project with all three files in place.
- `bunx prettier --write` on those three files only (not `bun format` — the tree has other uncommitted work).
- The SDK type declarations quoted in §1.
- `~/.claude/.credentials.json` exists mode 600 on a logged-in account; `~/.claude.json` exists separately.
- `CLAUDE_CONFIG_DIR` is honoured by the bundled CLI (4 occurrences in `cli.js`) and by `sdk.mjs`
  (`CLAUDE_CONFIG_DIR ?? join(homedir(),'.claude')`). Zero occurrences anywhere in this repo before this
  change.

**ASSUMED, NOT TESTED — the whole list:**

- That `provisionClaudeCli` succeeds for a real member. It needs network egress as the member and a writable
  home. `--reset-env` means `PATH` comes from their passwd entry; if `curl` is not on that `PATH` the install
  fails and the account still provisions, reporting the error.
- That the installer writes to `~/.local/bin/claude` when run under `setpriv` with a passwd-derived `HOME`.
  `claudeBinPath` assumes it does. If it picks a different target the install "succeeds" and the `test -x`
  gate reports failure, which is the safe direction.
- That `claudeLoginState` returns `{installed: true, loggedIn: false}` for a freshly provisioned member and
  flips after they run `claude` once themselves.
- That the spawn hook works at all (§1).
- Everything about how this behaves with `DATA_PATH` at 711 with ACLs
  (`docs/per-user-linux-accounts.md:392-415`). Untested for the agent's paths specifically.

---

## 6. Open questions and known risks

**Network isolation is not solved and is not in scope of this change.** A member's `claude` has general
outbound reach — it must, to authenticate — which includes loopback, where the platform's own services
listen. `docs/per-user-linux-accounts.md:221-225` already says this plainly: not a sandbox; members are
isolated from each other and from accidents, not from the host. The terminal and rootless Docker have the same
property today. If "a member cannot reach the others or the outside" is a requirement rather than an
aspiration, it is a separate stage (per-uid firewalling or a network namespace) covering all three surfaces,
and it wants looking at **on the host that actually runs members** — not on the dev box. I probed the dev box
for this and the results say nothing about the deployment; disregard any such finding from me.

**`curl … | sh` per member sits against this repo's supply-chain stance.** `bunfig.toml` sets
`frozenLockfile` precisely so nothing resolves that nobody chose, with the 2026-08-04 npm compromise as the
reasoning. This adds an unreviewed network fetch executed once per account creation. It is how the tool ships
and what the owner's own install does, and the owner accepted the trade — but it should be a conscious one,
not a thing discovered later in a diff.

**`spawn-as-member.ts` has no test.** It is the one file standing between a member's turn and the owner's
credential, and the guarantee is currently a code-read. The test to write is in the shape of
`os-user.test.ts`: assert no `NEVER_ENV` name survives into the argv `runAsArgv` produces, and that `HOME` and
`CLAUDE_CONFIG_DIR` point inside the member's home.

**Untested interaction with `claude-manager.ts`'s module-level state.** `CLAUDE_BIN` (`:31`) and `HOST_HOME`
(`:35`) are resolved once at import, from the *sidecar process's* environment. Both are wrong for a member and
both are what the wiring in §4 has to override per turn, not globally.

---

## 7. Running it

Provisioning lives in the main server, so the change takes effect with:

```
pm2 restart officer
```

`spawn-as-member.ts` is not imported by anything yet, so `officer-agent` does **not** need restarting and
restarting it proves nothing about this change.

To exercise the provisioning half on the server: press the terminal/retry icon on a member's row in
Settings → User management (`provisionOsAccount` is idempotent and will run the new step), then as root:

```bash
sudo ls -l ~<member>/.local/bin/claude          # expect: present, owned by the member
sudo ls -l ~<member>/.claude/.credentials.json  # expect: ABSENT until they log in themselves
```

Then have the member open a terminal and run `claude` once to log in with **their own** account. Confirm the
credential appears and that `claudeLoginState` flips. Do not log in on their behalf with the owner's account
— that is the thing this whole design exists to avoid.

Expect **no change to chat behaviour for anyone**, member or owner: the gates in §4 are still up and the
spawn hook is not called. If a member's chat starts working after this change, something is wrong.