stack/agents/darkwing/work/queue-92/build.md

Row 92, role sessions confined to their own files, build (Darkwing)

Issue #1586. Brief: docs/plans/2026-10-12_session-confinement.md (blob 21ee4458, queue rev 741, decision 118), with Sage's direction on decision 119 (Q126, b66bfe71, queue rev 754): any provider credential that ENV_ALLOW carries passes the launch check, the credential file's path appears once in the unit template and once in the README paragraph, and tests use stand-ins. Base af01465c. No commit from the base to the packet's commit touches the 13 paths.

build.patch is git diff --cached --binary af01465c of the 13 paths. Apply it with git apply --index to a detached worktree of the base, and sha256sum -c candidate-manifest.sha256 then gives 13/13 OK.

File	What changed
packages/seat/src/sandbox.mjs	new: the bind table, the bwrap command line, the probe
packages/seat/src/session.mjs	the runner spawns in the sandbox; SESSION_CREDENTIALS; sessionExit
packages/seat/tests/sandbox.test.mjs	new: real confined sessions against stand-ins, binds broken on purpose
packages/seat/tests/session.test.mjs	the session's HOME; the exit mapping; the credential sets
packages/seat/README.md	"The sandbox (#1586)" in place of the PID namespace limits
packages/cli/src/launcher.mjs	two new refusal steps; the paths a session needs; recovery matches bwrap
packages/cli/tests/launcher.test.mjs	both refusals; the real Claude Code coder; credential stand-ins
packages/cli/tests/fixtures/launch-host.mjs	passes the fake adapter as a read-only file
packages/cli/tests/host.test.mjs	the unit has one EnvironmentFile=, the README names it
packages/cli/systemd/mosaic-bus.service.in	the EnvironmentFile= line and its comment
packages/cli/README.md	the two refusals, the credential, the unit paragraph
packages/harness/src/gate.mjs	header comment only
packages/harness/README.md	"Limits" rewritten for the sandbox

The sandbox

spawnSession now runs bwrap <namespaces> <binds> --remount-ro / --setenv HOME <run>/home --setenv TMPDIR /tmp --chdir <run> -- setpriv --pdeathsig KILL -- node runner.mjs <run>. The root is an empty tmpfs; each bind lands at its host path, so the paths in session.json mean the same inside and out. The namespaces are --unshare-user --unshare-pid --unshare-ipc --as-pid-1, so the runner is still pid 1 of its own PID namespace.

Bind table

In mount order, as binds() returns them (each entry carries its why in the code too):

Source	Inside	Mode	Why
/usr	same	ro	the system's programs and libraries: sh, node, git, coreutils
/bin, /lib, /lib64, /sbin	same	symlink (or ro if a real dir)	the host's links into /usr
/etc	same	ro	name resolution, CA certificates, passwd for the user's name
(none)	/dev	private	null, zero, urandom and a pty
(none)	/proc	private	the session's own PID namespace
node's real path, if outside /usr	node's path	ro	node runs the runner and the gate
the 10 RUNNER_FILES	same	ro	the repository files the runner loads
the harness adapter	same	ro	the runner starts it each turn
<repo>/node_modules (real path), pi only	<repo>/node_modules	ro	pi and its packages, on the session's PATH
MOSAIC_CLAUDE_BIN's real path, Claude Code only, if outside /usr	MOSAIC_CLAUDE_BIN	ro	the pinned Claude Code binary
the broker socket	same	ro	the runner claims and calls through it
the launch socket, the launching role only	same	ro	the launch tool calls it
the instance's workspace	same	rw	where the harness works
the run directory	same	rw	turns/, session/, tools.sock, turn.done, home/, tmp/
<run>/bundle	same	ro	stays as the host wrote it
<run>/session.json	same	ro	stays as the host wrote it
<run>/tmp	/tmp	rw	a private /tmp on disk in the run directory

HOME is <run>/home, made empty (0700) before the spawn. Nothing else exists: no data root beyond the run directory, no other workspace or run, no ~/.config, ~/.mosaic, ~/.ssh or ~/.claude, no checkout beyond the runner's files. A bind to a socket is read-only as a mount, and connect() on a socket in a read-only mount still works; that is what the broker and launch sockets need.

Refusals

Two steps join the launcher's checks, both before family and capacity and both through refuse(), so each is an action.refused event and a launch log line:

• no-session-credential: a Claude Code launch when none of the SESSION_CREDENTIALS sets is fully set in the bus host's environment: CLAUDE_CODE_OAUTH_TOKEN, ANTHROPIC_API_KEY, or ANTHROPIC_AUTH_TOKEN with ANTHROPIC_BASE_URL. A pi launch doesn't check.
• sandbox-unavailable: sandboxProblem() runs bwrap with the namespaces and the system binds and true. A missing bwrap or a failing one refuses with the first line of bwrap's stderr. There is no unconfined path left: namespace: false and UNSHARE are gone.

Choices to review

1. setpriv's parent-death signal, not bwrap's --die-with-parent. --die-with-parent sets the death signal on bwrap itself as well as on the child. bwrap's parent is the bus host, so a host that dies hard would take every session with it, and the launcher's recover() (the next host finds the sessions and ends their runs) would have nothing to recover. That breaks the two "host that died hard" tests. So the runner gets setpriv --pdeathsig KILL: it dies when the outer bwrap does, as it did with unshare's --kill-child, and bwrap outlives the host. The race: if the outer bwrap dies between the fork and setpriv's prctl, the runner keeps running. The host ends the launch when the outer bwrap exits, and endLaunch voids every capability of the run, so the runner's next poll gets unauthenticated and it exits (runner.mjs, SESSION_GONE). A turn already running finishes first, up to the turn timeout. The window to hit is the few instructions between the fork and the prctl.
2. The refusal names the variables, not the file. The brief said a Claude Code launch with no credential refuses "naming the missing file". Sage's one-path rule puts the path only in the unit template and the README paragraph, so the message names the variables and "the bus unit's EnvironmentFile". The README paragraph names the file.
3. Any provider credential passes, per decision 119. The check accepts the OAuth token, an API key, or a proxy's token with its base URL, so the proxy-issued key (Vikunja #237) swaps in by editing the file. A proxy token without its URL doesn't count.
4. Pi sessions see the credential variables too. ENV_ALLOW passes them to every session, so a pi session's bash can print them. That was so before this row for whatever the shell had; it is now so for the file's credential. The cli README says so. Narrowing ENV_ALLOW per harness would be a change to sessionEnv, outside this brief.
5. claude from PATH finds only /usr. With MOSAIC_CLAUDE_BIN unset, the adapter runs claude from PATH, and inside the sandbox that is only a claude under /usr; a ~/.local/bin/claude isn't there. The installed unit pins MOSAIC_CLAUDE_BIN (decision 91), so only a hand-started bus meets this. The cli README says so.
6. Edits past the brief's file list. host.test.mjs gains the unit's one-EnvironmentFile= check, and launch-host.mjs passes the fake adapter as a read-only bind (the sandbox otherwise hides it). The cli README's refusal table gains its two rows, beyond the unit paragraph the brief names.
7. The test fixture strips the shell's credentials. The cli fixture's env started from process.env, so a credential in the shell running the tests reached test sessions. prepare() now deletes every SESSION_CREDENTIALS variable and sets a stand-in.
8. NoNewPrivileges. The unit sets NoNewPrivileges=yes. bwrap here is not setuid and uses user namespaces, which work under no-new-privs: setpriv --no-new-privs around sandboxProblem() returns null.

Probes

Scratch probes, not part of the candidate:

• bwrap under setpriv --no-new-privs: works (choice 8).
• The host's claude inside the Claude Code binds with an empty environment: claude --version gives 2.1.296; DNS resolves api.anthropic.com and a request reaches it (405); HOME is <run>/home; claude -p with no credential prints "Not logged in", exit
  1. The founder's login in ~/.claude is out of reach. Afterwards HOME holds the .claude and .claude.json claude made itself.

Tests

packages/seat/tests/sandbox.test.mjs (new):

1. RUNNER_FILES is exactly the runner's import graph plus the three files the harness starts: the test walks the imports, so a new import that isn't bound fails here, not in a live session.
2. sandboxProblem names a missing bwrap and one that fails.
3. Every bind has a why; bundle/ and session.json are mounted read-only after the read-write run directory; /tmp is last; no launch socket for a role that may not launch; no node_modules for Claude Code.
4. A real confined session (the real runner, a real broker, an adapter that runs each message's body in sh) answers a table of 20 checks against stand-ins under a scratch root: the stand-in ~/.config/mosaic-dev/secrets/stand-in.env and ~/.mosaic, another workspace, another run directory, the data root's bus store, the checkout (AGENTS.md, the seat's own source), writes to /, beside the workspace, in the data root, to a runner file, the bundle and the session file: all refused. Positive: HOME is the run's empty home/, TMPDIR is /tmp, the data root shows only this run, the workspace, the run directory and /tmp take a write and a read, node runs.
5. Breaking it on purpose: the same session with the two stand-ins bound in fails exactly their two checks; a sandbox from binds() passes all 20; without the workspace bind, exactly the workspace check fails.

packages/seat/tests/session.test.mjs: the existing real-session test now runs in the sandbox and checks the runner's HOME is <run>/home. A new test covers sessionExit (0, 23 and 128 stay codes; 137 and 143 become SIGKILL and SIGTERM, ending killed) and hasSessionCredential (each of the three sets alone passes; a proxy token or URL alone, empty strings and nothing fail; every name is in ENV_ALLOW).

packages/cli/tests/launcher.test.mjs:

• A Claude Code PM with only a proxy token refuses no-session-credential with the exact message, one log line, no session, no run directory.
• A bwrap that fails, then a missing one, refuse sandbox-unavailable with bwrap's line and "is missing"; a session's launch request gets the same code through refuse(); no session, no run.
• The real Claude Code launch. The PM (fake adapter) launches a coder whose harness is Claude Code, with the real adapters/claude and the host's claude pinned by MOSAIC_CLAUDE_BIN. Its credential is a stand-in proxy key, ANTHROPIC_AUTH_TOKEN with ANTHROPIC_BASE_URL pointing at the scripted Messages API from the harness tests, so no real credential or model is involved. The script makes one Bash call that tries nine things; the coder's reply carries the tool result. Refused: the stand-in secret (FAKE_TOKEN=stand-in-value), the stand-in ~/.mosaic, the PM's run directory, the data root's sessions.json, the checkout, a write outside. Allowed: a write and read in its workspace and in /tmp, a writable HOME ending /home. The reply never contains the secret's value. The test passes in about 3 seconds; a rerun that printed the reply body gave ANSWER [[false,"0 no\n1 no\n2 no\n3 no\n4 no\n5 no\n6 yes\n7 yes\n8 yes"]]. With the stand-in secret added as a read-only bind, the test fails on exactly 'read the stand-in secret': true (real-exposed.txt).
• The test where the PM launches a coder now also reads both sessions' bwrap command lines: the PM's binds the launch socket, the coder's doesn't. This was the one mutant survivor (below).
• prepare() strips the shell's credential variables (choice 7).

packages/cli/tests/host.test.mjs: the rendered unit has exactly one EnvironmentFile=, of the form -%h/..., and the cli README contains that line.

The unit renders, and systemd-analyze --user verify on it prints nothing.

Mutants

mutants.sh with agents/darkwing/work/queue-59-review/r1/mut.mjs. Each mutant edits one site (exactly one match), runs the test files it names and restores the file. The run went 2026-10-12 20:43:33Z to 20:47:09Z, after Dewey's row 89 run had ended (mutants.txt).

26 mutants. 23 were killed on the first run. Three needed a second look:

• bind-checkout and probe-always-ok were killed by a SyntaxError, not by a test. Their replacement text was single-quoted, so it carried a literal \n. I fixed the quoting and reran both. Each is now killed by an assertion (the confined-shell table and the bwrap refusal test).
• launch-socket-always survived: a coder session given the launch socket passed every test. The coder's sandbox couldn't reach the socket in any test, because no test asked. The launcher test above now reads the command lines, and the rerun kills it.

The table after the fixes, all 26 killed:

Mutant	What it undoes	Killed by
no-workspace-bind	the workspace bind	confined shell table
runDir-read-only	the run directory is read-write	bind order test
bind-all-runs	the run bind is the run directory, not its parent	bind order test
bundle-writable	bundle/ read-only over the run directory	bind order test
session-json-writable	session.json read-only	bind order test
no-private-tmp	the private /tmp	bind order test
bind-checkout	the checkout stays out	confined shell table
node-modules-always	node_modules only for pi	bind order test
runner-file-missing	a runner import left out of RUNNER_FILES	import walk
no-remount-ro	the read-only root	confined shell table
host-home	HOME in the run directory	confined shell table
no-pid-namespace	the PID namespace	the PM launch test
die-with-parent	bwrap's own --die-with-parent added	the host-died-hard test
no-pdeathsig	setpriv --pdeathsig KILL removed	the host-died-hard test: the runner outlives bwrap
exit-code-not-mapped	128+n back to the signal	sessionExit test
recover-matches-unshare	recover() matching bwrap's command line	the host-died-hard test
no-sandbox-check	the sandbox-unavailable refusal	the bwrap refusal test
probe-always-ok	the probe	the bwrap refusal test
no-credential-check	the no-session-credential refusal	the credential refusal test
proxy-key-alone	the proxy set needs its URL	credential tests
proxy-key-ignored	the proxy set counts	credential tests
any-variable-will-do	every variable of a set	credential tests
claude-bin-not-bound	the pinned claude bind	the real Claude Code launch
launch-socket-always	the launch socket only for the launching role	the PM launches a coder test
unit-no-envfile	the unit's EnvironmentFile=	host.test.mjs
unit-envfile-required	its leading -	host.test.mjs

My three-mutant rerun overlapped Filbert's row 95 run for about a minute: I chained the busy check and the run in one command, so the run didn't stop when the check found Filbert's processes.

Gate

My run on the candidate, in a worktree of af01465c holding the 13 paths, TMPDIR in my scratch (gate.sh, gate-summary.txt). Sequential, each package's own test command from its directory, then every scripts/test-*.sh, with test-task.sh under DOCKER_HOST=unix:///nonexistent. Nothing of another seat's was running: Filbert called the machine clear at 21:30:30Z and my check found no process. 2026-10-12T21:30:49Z to 21:34:10Z, all rc=0.

Suite	Result
seat	33 pass
cli	118 pass
harness	59 pass
bus	102 pass
webui	84 pass
test-auth	15 passed
test-conductor	17 passed
test-config	24 passed
test-discord	66 passed
test-extension-package	18 passed
test-foundation	44 passed
test-queue	27 passed
test-release	14 passed
test-task	26 passed; four Docker groups skip (adapter seam, workspace/capability, live task, live recall pair)

No node suite skipped a test. The cli count includes the launch socket check that the third mutant rerun needed; this is its first unmutated run. One test made a compose network, wt_default, at 21:33:58Z; it was empty afterwards and I removed it. The worktree still checks 13/13 against the manifest after the run.