Add local execution and supervised worker controls - #5494

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 covers local execution, startup diagnostics, command cleanup, per-turn write roots on local Linux and macOS, and policy checks on restore.
• REQ733 adds exact-turn steering and explicit crash reconciliation. The worker example exercises interruption and reconnect.
• REQ734 adds execution history and receipts for commands, patches, MCP calls and applied instructions.
• REQ735 adds attention waits and sparse API-key rate-limit reporting.
• REQ736, REQ737 and REQ738 exercise existing configuration isolation, approval denial and deadline handling. REQ753 covers the public worker APIs documented in Document supervised worker controls and recovery #5495.

The worker example and integration tests address three new acceptance records:

• REQ779 exercises structured results and evidence-driven revisions in the same conversation.
• REQ780 checks artifact bytes and execution evidence before a separate publication step.
• REQ781 runs two workers through steering, reconnect and crash recovery and records separate timing measurements.

These tests qualify the reference workflow. Deployment-specific acceptance and comparative latency measurements remain open. REQ731 is excluded. Model access uses API keys, and managed login and billing verification are outside this PR.

Summary

The combined diff matches the worker example layer in #5503. The adoption docs are in #5495, and #5509 adds the automatic-compaction checks. This reference includes child receipts, local write-root isolation, remote policy restoration and worker effect-journal validation. Local isolation covers the runtime home, durable storage and native helpers, including bind mounts in either direction on Linux. Linux and macOS also check whether a write grant contains an existing hard link to an installed helper executable.

This pull request adds controls for supervising API-key coding workers. Applications can steer a specific turn, inspect execution records, and resume a local session after recording an interrupted tool call's outcome.

• Run local tools on supported Linux and macOS hosts without a WebSocket relay. Report startup failures before the model runs, wait for local command descendants to exit, and apply new write roots between settled turns. Preserve network rules and check the recorded policy on restore. Remote macOS executors keep their opening grants.
• Target steering to a native turn ID. Persist explicit reconciliation outcomes so recorded calls are not dispatched again.
• Retain completed command, patch and MCP records with native thread, turn and call IDs. A command denied during early sandbox startup now records its failed result after Core finishes its approval and retry checks. Record the applied instruction hashes, settings and runtime details. Portable receipts withhold executor policy details.
• Expose sparse API-key limits and attention waits. Add a two-process worker example with an effect journal, revision loop, artifact checks and a separate publication step.

Implicit remote workspaces can move during portable restore; explicit write policies and configured network rules still must match. The existing Environment.url: str and Turn.steer(input) contracts remain supported; exact targeting uses the separate Turn.steer_exact() method. Reconciliation requires a supported idle local session; cold descendant recovery remains unsupported. UncertainCall.reconcile() builds a confirmation from the reported call's IDs. Public executor receipt projection omits the raw permission profile. The application owns duplicate prevention across new call IDs and publication. Model authentication remains API-key-only.

Native changes extend the patch series without changing the pinned upstream Core revision. The isolated CI prerequisite is #5504. Behavioral docs are in #5495. This PR remains the combined reference; the five feature layers carry the review.

The supervised worker records acceptance after both owned resources close and checks exact verification output, including its final newline.

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.

After restore, new turns record the instruction files or inline instructions the caller actually supplied. Earlier receipts retain their original source. Detached commands that finish after the turn iterator ends remain observable through the session and its history.

At session opening and when changing write roots, the local executor checks whether a writable path is a hard link to a private SDK storage file. A writable alias can otherwise change saved state through a different filename.

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

The combined PR's Windows 3.10 and 3.14 jobs both failed two artifact tests on the missing Unix flag O_NOFOLLOW. Those tests now run on the same Linux and macOS platforms supported by the local worker. The platform-independent worker tests still run on Windows.

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 combined reference has the same tree as the split worker source. The integrated follow-up passed 141 focused tests with five platform skips. A separate 27-test recovery run and five raw-input cases passed. The split PRs own the corresponding reviews and qualification.

The installed Linux wheel passed all 12 session-storage tests, including the compressed-rollout case and the disjoint relocation control.

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.

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