Add local execution with per-turn write policies - #5501

Review stack: #5504 (CI) > #5499 (turn controls) > #5500 (receipts) > #5501 (executor) > #5502 (recovery) > #5503 (example) > #5495 (docs) > #5509 (automatic compaction during cancellation). Combined reference: #5494.

Requirements · REQ732 for executor configuration and startup, REQ733 for owned cancellation, REQ734 for execution evidence, and REQ736 for isolation.

Summary

A coding worker needs to run commands under a bounded write policy and know when its processes have stopped. This layer adds local execution on supported Linux and macOS hosts. The first commit enforces the policy in Core. The second exposes it through the SDK and tests the public interface.

• Set write roots at session open or after prior work settles. The executor rejects path overlap with its runtime home, persistent storage and native helpers. Linux checks both directions of existing bind mounts. Linux and macOS reject grants that contain an existing hard link to an installed helper executable. A disjoint workspace still works when the package manager hard-links the helper elsewhere. The executor also checks existing files in private session storage and its runtime home. It rejects writable aliases while allowing a disjoint workspace when a file has another hard link outside the write grant.
• Register local commands before they can run. On macOS each command has a dedicated launchd job. Shutdown waits for detached descendants. A terminal network denial waits for the job to drain before a later turn replaces the write roots. The sandbox also prevents commands from starting a separate user-owned service.
• Shutdown waits for published Linux commands, including previously accepted background commands during fallback cleanup. If the executor cannot confirm that a command exited, the session reports the cleanup failure and preserves any earlier acknowledgment error. An earlier, handled child cancellation can finish without making a later session close fail.
• Keep accepted background handles usable. Cancellation cleans up foreground commands and background processes whose handles never reached the caller.
• Verify the saved policy on reopen. Implicit remote workspaces can relocate. Local or explicit write grants require a matching policy digest. Remote macOS executors retain their opening grants.

When a result callback finishes during cancellation, the stopped turn cannot send an ordinary HTTP or WebSocket follow-up to the model.

The worker example uses these guarantees for artifact acceptance (REQ780) and workspace isolation (REQ781). Managed login and billing (REQ731) are excluded.

The native build applies the Core patches in the order listed in packages/codex/patches/series.json. The Linux shutdown regression exercises the resulting branch that joins all managed local commands.

On macOS, shutdown waits for the starting wrapper to report its kernel process identity or for its control channel to finish. It can then resume a paused wrapper. Success requires both the drain acknowledgment and the wrapper's exit within the shutdown deadline.

A session saved before its first model request can reopen without a sampling receipt. After sampling, an explicit network policy or strict write grant needs recorded evidence. The SDK checks the owner of surviving modern receipt fields before allowing a legacy reopen. Older implicit remote sessions can reopen when every retained Core context matches the original default read-only or single-workspace policy. If all modern receipt fields were erased, a strict session that recorded the same Core context as an older implicit session can be indistinguishable from it. The caller can reopen that history only under a compatible implicit policy.

A writable root can expose private session history in either direction. It can contain a relocated sessions directory, or it can sit inside one and receive the next rollout. On Linux and macOS, Core compares directory identities and their ancestors so alternate spellings reach the same check. Disjoint storage relocations remain supported. On open, resume, and policy replacement, the SDK also checks the selected rollout file and the files directly inside its private checklist and budget directories. The SDK refuses symbolic links inside its temporary runtime home.

Test plan

In an unprivileged Linux guest, the installed Python wheel passed 12 storage checks, including direct and relocated SQLite aliases, writable-root replacement and reopen. Sixteen installed Linux durable receipt cases passed, including corrupted identities, strict policies, and compatible legacy reopening. All 165 Rust binding tests passed. Five shared control-channel tests passed after the queued-identity regression failed on the previous source. They exercised the socket protocol with a simulated failed signal on Linux.

The installed Linux wheel passed 16 cancellation and lifecycle cases. Five unprivileged Linux guest scenarios passed, including pre-launch cancellation, policy restore and two-worker recovery. The wrapper passed service-delegation, terminal, filesystem and network tests on macOS 15 and 26. macOS 15 run · macOS 26 run · Installed Python package run

An installed Linux wheel passed all 12 session-storage tests, including refusing a compressed rollout before writing to it and reopening a disjoint relocated rollout. The Rust compressed-rollout test also passed.

A hosted child-approval test read the command output file while the command was still running. The fixture now polls the approved process until it exits successfully. A forced delay reproduced the failure before the change. Both delayed policy cases and all three ordinary controls passed with the installed wheel.

A sandbox command corrupted a saved checklist through a hard link before the fix. The checklist and budget correction passed seven installed Linux cases. Separately, the old native wheel created a real rollout inside a writable subdirectory on a case-insensitive volume. The final wheel passed all four overlap cases on case-insensitive ext4 and five controls on case-sensitive ext4, including resuming a disjoint rollout.

Issue number

None linked. Owning requirements database IDs are listed above.

Checks

• I've added new tests, if relevant
• I've run the applicable checks in AGENTS.md, including .agents/skills/code-change-verification/scripts/run.sh when required
• I've confirmed all required checks pass
• I've completed the review required by AGENTS.md