Document supervised worker controls and recovery - #5495

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 · REQ753 for documentation.

Summary

The guide shows how to change write grants between turns on a supported local Linux or macOS executor, how to restore a grant, and when an active command prevents a change. It explains the macOS host prerequisites and the fixed opening grants on remote macOS executors.

The Sessions guide explains how to restore an idle WSS checkpoint saved with writable_roots=None and network=None. Restore with those same settings on a WSS Environment, or omit the Environment. Open a new Session to use a local executor or explicit writable roots. The guide also explains when NativeAgents requires a new Session to change write grants.

Execution observations report the item kind, IDs, and status by default. The guide shows how trusted readers opt in to command, patch, and MCP details with include_execution_details=True and find the full retained record through session.items().

The guide explains explicit read roots, platform runtime reads, trusted MCP grants, and placement of the installed helpers outside writable roots. It also describes which local recovery outcomes the SDK can reconcile.

This pull request updates the docs for the worker controls in #5499, #5500, #5501 and #5502. It explains local execution, per-turn write roots, Turn.steer_exact(), UncertainCall.reconcile(), applied instruction receipts, execution history and sparse API-key limits.

The guidance distinguishes live executor details from portable receipts and explains which policy checks apply during restore. Implicit remote workspaces can move; strict policies and configured network rules still must match. It links the supervised-worker example and keeps journal ownership and publication with the application.

This docs PR is stacked on #5503. The current guidance reflects the separate exact-steering method, call-owned reconciliation helper and filtered public executor receipt fields.

Requirements

The guides explain the public APIs and their limits for local execution and write policy (REQ732), steering and recovery (REQ733), execution and instruction receipts (REQ734), and API-key limits and attention waits (REQ735).

The supervised-worker recipe also addresses the documentation side of three new acceptance records:

• REQ779 explains how to request revisions in the same conversation.
• REQ780 separates checking an artifact from publishing its accepted result.
• REQ781 describes two isolated workers, reconnect, crash reconciliation and separate timing measurements.

The runnable example and its integration tests are in #5503. #5494 preserves the verified combined source.

Test plan

MkDocs built the guides and rendered the updated WSS restore rule. An earlier strict build also checked the Sessions and tools guidance for WSS and NativeAgents.

A native WSS probe restored an idle checkpoint in a different working directory and without an Environment. It rejected a local executor, explicit writable roots, and a changed network policy before sending any executor requests.

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