Enforce worker write roots and verify policy on reopen - #2122

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

Review order. #2120 (controls) → #2121 (receipts) → #2122 (executor) → #2123 (recovery) → #2124 (worker example) → #2125 (docs) → #2137 (automatic compaction during cancellation).

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.

Closing a session prevents a delayed executor result from sending an ordinary HTTP or WebSocket follow-up to the model. New sessions can still issue requests.

The native build applies the Core patches in the order listed in packages/agents/native/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 directory. The SDK refuses symbolic links inside its temporary runtime home.

The stacked package workflow now covers native code and patches, SDK runtime code, native tests and the package workflows themselves. The release note describes local write-root changes on both supported platforms and the opening-only grant on remote macOS.

Test plan

In an unprivileged Linux guest, the installed JavaScript package passed four SQLite checks covering direct and relocated database aliases at open and during write-root replacement. A separate installed Linux test passed with a disjoint workspace and durable reopen. On macOS, the installed package rejected the existing helper alias and still ran Code Mode from a disjoint workspace. macOS installed helper test

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.

Focused SDK checks cover session close, delayed callbacks, model-step limits and successor turns. The package workflow has a separate installed-consumer check. The wrapper passed service-delegation, terminal, filesystem and network tests on macOS 15 and 26. macOS 15 run · macOS 26 run · Installed JS package run

On the old package a sandbox command changed a real rollout through a writable subdirectory with an alternate spelling. The corrected Linux package passed 13 selected cases on case-sensitive ext4 and three on case-insensitive ext4, including rejecting that subdirectory on open and policy replacement. The case-sensitive results combine 12 original passes with a rerun after fixing one test assertion about a permitted session open. The full executor-receipt suite passed all 19 cases with the corrected legacy fixture and a previously built package.

Issue number

The owning requirement IDs appear above.