feat(security): run a thread unattended inside a hardened container

[jonathanKingston]

Summary

Run a Copse thread unattended inside a disposable, hardened local Docker container with no user prompts, per the plan docs/plans/thread-in-container.md (the loop runs in the guest, not on the desktop), startable from the app, able to run key-capable ACP agents (Claude, Codex, Gemini) in the guest under a vendor API key — or, for Codex and Gemini, on the user's desktop sign-in when they opt in per run — and, since the later commits, a turn on the thread that launched it, with follow-ups that continue the run.

Experimental and off by default. Settings › Experimental › Unattended container runs (containerRunsEnabled) turns it on. The run service refuses to start anything while it is off, whatever the renderer asks, and the composer's menu entry and target picker exist only once it is on. Needs Docker.

The runtime and the gate

• Contained-effect gate branch. ensureShellCommandPermitted takes one new branch when the run is an armed unattended run and the runtime declared container: the harm gate still runs (hard denies stay hard), then decideContainedShellEffect (@copse/shell-guard/container-effects.ts) refuses host escapes, defers outward effects (git push, GitHub writes, publishes, HTTP writes, cloud CLIs) under the new prompt cause shell-outward-effect, and allows everything else.
• Runtime containment declaration (security/runtime-containment.ts): the host writes an attestation of the hardening it applied; the guest declares from it and refuses anything short of the bar (unprivileged uid, read-only rootfs, cap-drop ALL, no-new-privileges, no unmediated network, no host mount outside /run/copse).
• Unattended-run ledger (security/unattended-run.ts): session-only, per-thread, beside Guarded YOLO and mutually exclusive with it; arming begins deferral mode and requires budgets.
• Container worker: the product's runHeadlessAgent in the guest with a fail-closed approval handler that counts prompts (must be zero); workspace carried in as a git bundle and carried out as commits under refs/copse/runs/<id>. The container is the sandbox (no nested bubblewrap).
• Host runner: hardened docker run argv (the same source as the attestation), --network none plus one broker socket and a token-gated HTTP CONNECT proxy in the guest with a pattern allowlist (host:port, *.suffix:port), a connection log, a secret canary check, idempotent teardown, a managed-container sweep, and a JSON review record per run. A pnpm store volume is shared across installing runs.
• Follow-up refactors merged into this branch (refactor(container): share validated run and attestation contracts #2598, refactor(container): report lifecycle phases as structured events #2599, refactor(agent): share transcript content and tool updates #2602, refactor(container): track external runs with the task supervisor #2603): the run request and attestation cross the host/guest boundary as shared validated schemas; the worker reports its lifecycle phases as structured events; transcript content and tool updates share one reducer with the desktop agent; runs are tracked by the task supervisor.

From the app

• resolveContainerProvider adapts the desktop's own provider resolution for the guest: describeProvider → ProviderDescription (protocol, endpoint, tuned parameters, OpenRouter privacy and OpenAI transport settings; keys apart) travels in run.json with the desktop's context window, and the guest builds the same client from it. A loopback endpoint is renamed to a broker alias; LM Studio's WebSocket transport becomes its OpenAI-compatible endpoint.
• ContainerRunService owns one run per thread, refuses SSH projects before touching Docker, records the arming as a decision, and pushes ContainerRunProgress snapshots over container:* channels; preload and the demo API expose api.container.
• A run is a turn on its thread: the prompt is the thread's user message and the run is one container_run tool call whose subagent session holds the guest's transcript (folded with the desktop's own text planner) and the review record; the dialog closes on start and a banner shows the phase. The composer gets a target picker: to container continues the run (carrying in its commits, or a fresh snapshot when it made none, with what it was asked and reported prefixed to the prompt); to thread talks to the desktop model, which is told the run's outcome through the thread's model history. Apply N commits to this checkout cherry-picks the run's commits onto HEAD.
• ACP agents in the guest: pinned agents baked into the image, the run's one key handed to the agent under its own variable, contained permission policy (outward effects refused and recorded, never deferred), the resolver's verdict per picker row, and the per-run sign-in opt-in for Codex and Gemini.

Changes to shared paths (the merge risk)

• The desktop's buildProvider now goes through describeProvider + buildProviderFromDescription: the same branches split in two, covered by provider-selection.test.ts.
• The worktree backup, the container carry-in and the remote e2e push share one working-tree snapshot (git-snapshot.ts). A clean tree's backup ref now points at HEAD rather than an identical fresh commit.
• runHeadlessAgent returns the turn's turnOutcome.
• Security pins moved past today's advisories: @xmldom/xmldom 0.8.15, sharp 0.35.4, js-yaml 4.3.2 (main carries the same).
• Two e2e specs that assert the footer overflow menu (developer-mode, footer-overflow-bounds) seed the experimental setting on, since the container entry is hidden by default.

Validation

• pnpm run check green (typecheck, lint, format, dead code, 8970 unit tests); CI green on every head since the review rounds.
• Unit: the gate matrix, attestation shortfalls, Docker argv, carry-in/out and the carry-out branch rule, the image fingerprint, judgeRun, the provider description and plan, the run service (key hidden and blanked, stop before the container exists, continuation from memory, disk and the card), the egress grammar/broker/proxy over real sockets (including close during a dial), the guest transcript fold, the turn's failure and token tally, the thread history record, the composer target and the experimental gate.
• Docker integration (COPSE_THREAD_CONTAINER_E2E=1 pnpm test -- thread-container.integration, acp-container.integration): a scripted model and a scripted ACP agent behind the broker; not run in CI.
• Real runs: Codex on the author's sign-in, several times; each run's findings are fixed in the later commits (beachball on start, no live progress, run-on report text, follow-ups to thread and container, a volume that went away under the container).

Not in this PR (recorded in the plan)

Attaching from the desktop (ACP role + lease), approving a deferral from the dialog, the macOS broker variant.

🤖 Generated with Claude Code

https://claude.ai/code/session_01NzkY3kYdcQvYk8EH3EW8uv

[github-actions]

🖥️ PR preview

• Marketing site
• Browser demo
  Interactive, with a mocked backend — jump to a scenario:
• Builds a cupcake site
• Agent-proposed edits open the Changes panel
• Markdown list indentation
• Unattended container run
• Responsive composer footer
• Subagent display visual reference
• Subagent stays ungrouped beside reading tools
• Semantic search subagent markdown
• Light-theme approval with a bright accent
• Light-theme syntax, fills, and selection
• Grouped outside-sandbox command approval
• Remote desktop discovered-port list with one selected
• Settings scroll + sticky footer geometry
• Per-model reasoning / temperature / top-p
• Thread switch hydration notice
• Thread switch hydration failure
• Chat layout styling
  _{Static demo of the renderer against a mock API — the browser pane, terminal, and all main-process IPC are stubbed, so it never proves main-process behaviour. Rebuilt whenever a push changes the demo bundle; these links go live once the queued deploy lands, shortly after this comment. Removed when the PR closes.}

[jonathanKingston]

Readiness review: retaining this as a prototype draft. Its own product gate still lists unproven real-provider execution, no deferred-action approval/replay surface, and no startup orphan reconciliation/TTL. The scripted container test and UI shots establish useful plumbing, but do not discharge those security/lifecycle requirements; I am not merging unattended execution on that evidence alone.

[jonathanKingston]

Additional review findings against current head 5e2abcd, beyond the previously noted readiness gaps:

1. Snapshot the thread checkout, not the project root. ContainerRunService.start resolves only getProjectRoot(request.projectId) (container-run-service.ts:92). A thread running in an isolated worktree therefore snapshots the project checkout instead, potentially using the wrong branch and omitting its edits. Resolve and validate the thread-specific checkout before carry-in; cover a project and thread worktree with different commits and uncommitted edits.

2. Do not report successful completion when result retrieval or teardown fails. The service chooses finished solely from the presence of a result and its stopReason (container-run-service.ts:185-189). Carry-out fetch failures are only logged (thread-container.ts:748-754), while teardown failure and container exit are not considered. The UI can consequently say commits are back when no result ref was fetched, or report completion without surfacing failed cleanup as a failure/warning. Track these outcomes explicitly and test failed fetch and failed teardown records.

3. Invalidate the worker image when the shipped worker changes. ensureImage only checks whether the fixed copse-worker:local tag exists (container-run-service.ts:40-44). Once built, an image survives app upgrades and can keep running old worker code, including old security behavior. Key image reuse to a worker/runtime build fingerprint or version and rebuild when it differs.

4. Make the wall-clock deadline independently bounded. waitForContainer starts docker stop at the deadline but swallows its failure and resolves only when docker wait closes (thread-container.ts:518-540). If stop fails or hangs while wait remains open, the run can wait indefinitely and never reach the cleanup finally block. Bound the Docker subprocesses and deadline settlement independently, attempt cleanup, and explicitly report cleanup failures; cover a failed/hung stop with a still-pending wait.

These are source-review findings, not newly executed reproductions. No code changes were made during this follow-up review.

[jonathanKingston]

All four findings are fixed in 4bfd03c, each with the coverage the review asked for.

1. Snapshot the thread checkout. The service now resolves the checkout through resolveThreadExecutionContext — the cold resolver long-task-wake.ts and ci-watch-service.ts already inject — rather than getProjectRoot. A broken worktree fails the arming instead of falling back to the project root, and a root git cannot snapshot is refused up front with a readable reason rather than a raw git rev-parse failure after the image build. start became async, so it claims the thread's slot before its first await (two clicks cannot start two containers) and releases it when resolution fails. The record and the dialog now name which checkout ran. Test: a real project checkout plus a real linked worktree at a different commit with its own uncommitted edits, asserting the worktree is what gets carried in; plus a broken-resolver case and a non-git case.

2. No successful completion when retrieval or teardown fails. carryOutRef became carryOut { expected, ref, error }, and the record gained cleanupError; judgeRun decides the phase from the whole record. Commits produced but not fetched, a container that would not stop or reap, and a leaked secret canary all keep a run out of finished — as the failure reason, with cleanup problems also listed as warnings in the dialog. The banner now reads "made but NOT fetched" rather than "back" when there is no ref. Tests cover the failed-fetch and failed-teardown records.

3. Image invalidation. Reuse is keyed to a fingerprint of the guest bundle, the Dockerfile, the entrypoint, the worker uid and the sandbox-runtime version, written as a dev.copse.worker-fingerprint image label and compared before reuse, so an app upgrade rebuilds instead of running the previous worker. Verified on a real build; test covers the fingerprint changing with the bundle and with the base image.

4. Independently bounded deadline. docker stop now has its own timeout, and a bounded grace period settles the wait either way, so a failed or hung stop with a still-pending wait can no longer leave the run pending and skip its cleanup block. The abandoned wait is killed, the failure is reported as cleanupError instead of swallowed, and docker rm --force in teardown remains the next line of defence. Both Docker calls are injectable; tests cover a rejecting stop with a hung wait, a successful stop with a hung wait, and a wait that cannot spawn.

Validation: pnpm run check green (8305 unit tests), the Docker integration test re-run green against a real daemon with a rebuilt image, and the browser-tier screenshots refreshed (the result view now shows the checkout row).

These are fixes to the findings only — the readiness gaps you listed earlier (real-provider execution, deferred-action approval/replay, orphan reconciliation/TTL) are unchanged and still recorded as not-in-this-PR in docs/plans/thread-in-container.md.

---

Generated by Claude Code

[jonathanKingston]

Followed up on 5ddeb89 (the stricter judgeRun). Two things.

What I verified. The new containerExit !== 0 rule depends on a clean guest actually exiting 0, which no unit test can establish and which CI never exercises — the Docker integration test is opt-in. I ran waitForContainer against real containers on a live daemon:

guest	waitForContainer
finishes normally (main() resolves, as worker-entry.ts does)	{ exit: 0, timedOut: false }
fails (main().catch sets exitCode = 1)	{ exit: 1, timedOut: false }
outlives its budget, stopped by the host	{ exit: 137, timedOut: true }

So the happy path still judges clean, and the two failure shapes are now caught. The entrypoint is exec node /app/worker.cjs, so the container's status is the worker's own — nothing in between can launder a non-zero exit into a zero.

One ordering problem, fixed in d0e9813. The canary is pushed onto warnings before the cleanup branch is tested, so a run that both leaked the canary and failed to reap its container reported

The container could not be removed; remove it by hand before the next run.

as the failure, with the leak demoted to a warning underneath. A container left behind is a chore; a credential that escaped is an incident. The canary verdict now sits above the cleanup branch (still in warnings too, so the dialog's warning strip is unchanged), with a test for the combined case. pnpm run check green.

What I could not check. The full Docker integration test cannot run in this session: the network policy blocks deb.debian.org, so the worker image's apt-get layer (bubblewrap, git, ripgrep, socat) will not build here, through the proxy or the gcr mirror. The last real end-to-end run was against 4bfd03c; the judgeRun changes since then are covered by unit tests and the container-level check above, not by a full run.

---

Generated by Claude Code

[jonathanKingston]

Current-head validation is green and current with main: full CI passes, the diff is whitespace-clean, and the four concrete source-review findings recorded above are addressed. This still should remain a prototype draft. The remaining gates are product/security evidence, not obvious code nits: a real-provider end-to-end run, deferred-action approval/replay, and startup orphan reconciliation/runtime TTL. The existing plan and this PR already track those gaps; a new issue would only be useful if this prototype is split into independently owned implementation slices.