delegation-layer 0.1.28 → 0.1.29

package/skills/agent-integration/examples/json-results.md

@@ -5,10 +5,9 @@ delegate --root "${DELEGATE_ROOT:-$HOME/delegation-state}" status "$TASK_ID" --j
 delegate --root "${DELEGATE_ROOT:-$HOME/delegation-state}" collect "$TASK_ID" --watch 5s --json
 ```
 
-Decision order:
-
-1. Save `task_id`.
-2. Check `admission` and `error`.
-3. Wait while publication is pending.
-4. Accept only a committed terminal `outcome`.
-5. If `status` is `timed_out`, follow `continuation.resumable`.
+Apply [result handling](../references/result-handling.md) to each response and
+follow [Observe and collect](../SKILL.md#5-observe-and-collect). Those sections
+own the decision order for task creation, failures, timeout continuation,
+terminal outcomes, pending interaction, and bounded collection. Read them
+before interpreting these commands; pending publication alone is not a reason
+to wait when the task needs an answer or timeout recovery.

package/skills/agent-integration/examples/managed-workspace.md

@@ -0,0 +1,68 @@
+# Managed workspace example
+
+Use this example for independent write work that should be isolated in a
+retained Git worktree. The source must be a Git checkout and the state root
+must remain outside provider-writable workspaces.
+
+```sh
+SOURCE="$PWD"
+BRIEF="$(mktemp)"
+RESPONSE="$(mktemp)"
+printf '%s\n' 'Implement the requested change and report the files changed.' >"$BRIEF"
+
+if delegate --root "${DELEGATE_ROOT:-$HOME/delegation-state}" dispatch --auto \
+  --brief "$BRIEF" --cwd "$SOURCE" \
+  --permission workspace-write --isolation git-worktree \
+  --base HEAD --workspace-budget 5m --budget 30m --json >"$RESPONSE"; then
+  dispatch_exit=0
+else
+  dispatch_exit=$?
+fi
+printf '%s\n' "$dispatch_exit" >"$RESPONSE.exit"
+cat "$RESPONSE"
+```
+
+Read the saved JSON before running another command. When
+`task_record: "created"`, use its `task_id` as `TASK_ID` below. When no task
+was created, follow the [result decisions](../references/result-handling.md#managed-workspace-results);
+do not run task status or collection against that nonexistent record.
+
+```sh
+if delegate --root "${DELEGATE_ROOT:-$HOME/delegation-state}" status TASK_ID --json >"$RESPONSE.status"; then
+  status_exit=0
+else
+  status_exit=$?
+fi
+printf '%s\n' "$status_exit" >"$RESPONSE.status.exit"
+if delegate --root "${DELEGATE_ROOT:-$HOME/delegation-state}" collect TASK_ID --watch 5s --json >"$RESPONSE.collect"; then
+  collect_exit=0
+else
+  collect_exit=$?
+fi
+printf '%s\n' "$collect_exit" >"$RESPONSE.collect.exit"
+```
+
+Continue observing that created task when collection exits `3`. Wait for the
+workspace to return to `state: retained` and inspect its final capture. Only
+after the Lead explicitly chooses release, run:
+
+```sh
+if delegate --root "${DELEGATE_ROOT:-$HOME/delegation-state}" workspace release WORKSPACE_ID \
+  --budget 5m --json >"$RESPONSE.release"; then
+  release_exit=0
+else
+  release_exit=$?
+fi
+printf '%s\n' "$release_exit" >"$RESPONSE.release.exit"
+```
+
+Read the release acknowledgement. `watch_workspace` means observe this
+accepted release; a `retry_release` acknowledgement means it was not accepted.
+Follow the same result decisions rather than assuming either response is
+completed cleanup.
+
+Save each response and exit code once. A created task is observed with
+`status` first and collected in the foreground. Exit `3` means pending, not
+success; continue observing the same task. The Lead reviews the capture and
+owns landing any changes. `workspace release` is explicit; no automatic
+apply, commit, branch merge, TTL eviction, or provider-CLI fallback occurs.

package/skills/agent-integration/references/collaboration.md

@@ -1,5 +1,13 @@
 # Parallel reviews and debates
 
+For independent parallel write work, choose `--isolation git-worktree`
+automatically unless the user explicitly chooses shared coordination. The
+model chooses fan-out and task scope; the supervisor has no fixed task-count
+cap or TTL eviction. A read-only review may attach a retained workspace with
+`--workspace ID`. The single managed-workspace policy, capture boundary, and
+release rules live in [managed workspace guidance](workspaces.md); do not
+restate them in each collaboration brief.
+
 ## Keep each request identifiable
 
 Choose the fan-out needed for the user's task. Each participant needs its own
@@ -19,18 +27,26 @@ RECEIPTS="$(mktemp -d)" || exit 1
 # Set these absolute paths and catalog IDs in this same tool invocation.
 # BRIEF_A and BRIEF_B contain the real independent assignments.
 (
-  delegate --root "${DELEGATE_ROOT:-$HOME/delegation-state}" dispatch --provider "$PROVIDER_A" \
+  if delegate --root "${DELEGATE_ROOT:-$HOME/delegation-state}" dispatch --provider "$PROVIDER_A" \
     --brief "$BRIEF_A" --cwd "$WORKSPACE_A" \
     --permission read-only --budget 30m --json \
-    >"$RECEIPTS/review-a.json" 2>"$RECEIPTS/review-a.stderr"
-  printf '%s\n' "$?" >"$RECEIPTS/review-a.exit"
+    >"$RECEIPTS/review-a.json" 2>"$RECEIPTS/review-a.stderr"; then
+    dispatch_exit=0
+  else
+    dispatch_exit=$?
+  fi
+  printf '%s\n' "$dispatch_exit" >"$RECEIPTS/review-a.exit"
 ) &
 (
-  delegate --root "${DELEGATE_ROOT:-$HOME/delegation-state}" dispatch --provider "$PROVIDER_B" \
+  if delegate --root "${DELEGATE_ROOT:-$HOME/delegation-state}" dispatch --provider "$PROVIDER_B" \
     --brief "$BRIEF_B" --cwd "$WORKSPACE_B" \
     --permission read-only --budget 30m --json \
-    >"$RECEIPTS/review-b.json" 2>"$RECEIPTS/review-b.stderr"
-  printf '%s\n' "$?" >"$RECEIPTS/review-b.exit"
+    >"$RECEIPTS/review-b.json" 2>"$RECEIPTS/review-b.stderr"; then
+    dispatch_exit=0
+  else
+    dispatch_exit=$?
+  fi
+  printf '%s\n' "$dispatch_exit" >"$RECEIPTS/review-b.exit"
 ) &
 wait
 printf 'Read each response separately in %s\n' "$RECEIPTS"

package/skills/agent-integration/references/command-reference.md

@@ -5,28 +5,30 @@ All paths passed to `--root`, `--cwd`, and `--brief` must be absolute. Add
 
 Pass the intended workspace directly. Delegate handles provider launch options;
 do not initialize Git, change trust settings, or call a provider CLI as a
-workspace workaround. Ordinary Codex tasks support non-Git directories;
-Git-targeted native review requires a suitable repository.
+workspace workaround. Ordinary tasks support non-Git directories. Git is
+required for managed worktree creation/attachment only; native review retains
+its separate explicit review-target contract. See [managed workspace guidance](workspaces.md)
+for the policy owner.
 
 | Command | Purpose | Launches provider work? |
 | --- | --- | --- |
 | `delegate --version` | Confirm the installed control CLI | No |
-| `delegate providers --json` | List compiled provider metadata | No |
-| `delegate capabilities --provider ID --json` | Read the catalog contract | No |
-| `delegate models --provider ID [--cwd ABS] --json` | Discover advisory native model and effort facts | Native inspection only; no admitted task |
-| `delegate preflight --provider ID --cwd ABS --json` | Check static provider admission | No |
-| `delegate dispatch --auto ... --json` | Select and admit one bounded turn | Yes, at most once |
-| `delegate status TASK --json` | Reconcile and observe task state | No provider launch |
-| `delegate collect TASK --watch 5s --json` | Read or wait for publication | No provider launch |
-| `delegate recheck TASK --json` | Reassess eligible rejected evidence offline | No provider launch; original outcome unchanged |
-| `delegate continue --task TASK ... --json` | Create an exact-session successor | Yes, at most once for the successor |
-| `delegate reply TASK --request ID --answers FILE --id MESSAGE_ID --json` | Answer a pending native question | No new launch |
-| `delegate steer TASK --brief FILE --id MESSAGE_ID --json` | Guide a supported active turn | No new launch |
-| `delegate events TASK --after SEQUENCE --watch 5s --json` | Read a bounded interaction event page | No |
-| `delegate logs TASK --json` | Return validated output descriptors | No |
-| `delegate cancel TASK --json` | Record one explicit stop request | Stops, does not relaunch |
-
-`delegate supervisor migrate --json` is the single command-neutral recovery
+| `delegate --root ROOT providers --json` | List compiled provider metadata | No |
+| `delegate --root ROOT capabilities --provider ID --json` | Read the catalog contract | No |
+| `delegate --root ROOT models --provider ID [--cwd ABS] --json` | Discover advisory native model and effort facts | Native inspection only; no admitted task |
+| `delegate --root ROOT preflight --provider ID --cwd ABS --json` | Check static provider admission | No |
+| `delegate --root ROOT dispatch --auto ... --json` | Select and admit one bounded turn | Yes, at most once |
+| `delegate --root ROOT status TASK --json` | Reconcile and observe task state | No provider launch |
+| `delegate --root ROOT collect TASK --watch 5s --json` | Read or wait for publication | No provider launch |
+| `delegate --root ROOT recheck TASK --json` | Reassess eligible rejected evidence offline | No provider launch; original outcome unchanged |
+| `delegate --root ROOT continue --task TASK ... --json` | Create an exact-session successor | Yes, at most once for the successor |
+| `delegate --root ROOT reply TASK --request ID --answers FILE --id MESSAGE_ID --json` | Answer a pending native question | No new launch |
+| `delegate --root ROOT steer TASK --brief FILE --id MESSAGE_ID --json` | Guide a supported active turn | No new launch |
+| `delegate --root ROOT events TASK --after SEQUENCE --watch 5s --json` | Read a bounded interaction event page | No |
+| `delegate --root ROOT logs TASK --json` | Return validated output descriptors | No |
+| `delegate --root ROOT cancel TASK --json` | Record one explicit stop request | Stops, does not relaunch |
+
+`delegate --root "${DELEGATE_ROOT:-$HOME/delegation-state}" supervisor migrate --json` is the single command-neutral recovery
 step for a `supervisor_upgrade_required` admission response. Run it once with
 the failed command's exact root. A successful response names its next action
 `retry_dispatch`, but the original command and argv remain authoritative:
@@ -55,6 +57,35 @@ Dispatch flags:
 - `--interactive`: enable advertised native clarification and steering; see [interaction](interaction.md);
 - `--native-timeout DURATION`: optional provider-native timeout where advertised.
 
+## Managed workspace commands
+
+Managed workspaces are optional. For independent parallel writes, choose
+`--isolation git-worktree` unless the user explicitly chooses shared
+coordination. The model chooses fan-out and task scope; there is no fixed task
+count cap or TTL eviction. Use the canonical [workspace reference](workspaces.md)
+for retention, capture, release, forgetting, and review-scope rules.
+
+The public forms are:
+
+```sh
+delegate --root ROOT dispatch --isolation git-worktree --cwd ABS \
+  [--base REV] [--workspace-budget DURATION] ... --json
+delegate --root ROOT dispatch --workspace WORKSPACE_ID ... --json
+delegate --root ROOT workspace list [--after ID] [--limit 1..50] --json
+delegate --root ROOT workspace status ID [--operation OP] [--watch DURATION] --json
+delegate --root ROOT workspace exec ID --budget DURATION -- ARGV...
+delegate --root ROOT workspace release ID [--discard] [--budget DURATION] --json
+delegate --root ROOT workspace forget ID [--budget DURATION] --json
+```
+
+`--workspace` cannot be combined with public `--cwd`, `--base`, or
+`--isolation`. `workspace exec` passes literal argv after `--` and initially
+returns asynchronously; exit `3` means the operation is pending. The helper
+budget defaults to 5m, is persisted/overridable, and does not renew the task
+budget. `continue --task TASK` inherits the predecessor workspace, cwd, and
+session while creating a new task ID. A read-only review may attach a retained
+workspace with `--workspace ID`.
+
 Model discovery uses the same `--provider ID` profiles and accepts an optional
 absolute `--cwd` (default: current directory). Its JSON has `status` values
 `available`, `partial`, `blocked`, `unavailable`, or `failed`; exits are `0`,
@@ -77,7 +108,8 @@ is incomplete or does not list them. To resolve a natural-language model name
 or choose an option the caller left open, use native discovery:
 
 ```sh
-delegate models --provider PROVIDER_ID --cwd ABSOLUTE_WORKSPACE --json
+delegate --root "${DELEGATE_ROOT:-$HOME/delegation-state}" models \
+  --provider PROVIDER_ID --cwd ABSOLUTE_WORKSPACE --json
 ```
 
 Omit `--cwd` to use the current directory. Run discovery only when the caller
@@ -111,7 +143,8 @@ Use `preflight` when the caller asks about static readiness, rather than as a
 required step before every dispatch:
 
 ```sh
-delegate preflight --provider PROVIDER_ID --cwd ABSOLUTE_WORKSPACE \
+delegate --root "${DELEGATE_ROOT:-$HOME/delegation-state}" preflight \
+  --provider PROVIDER_ID --cwd ABSOLUTE_WORKSPACE \
   --permission REQUESTED_MODE --json
 ```
 

package/skills/agent-integration/references/continuation.md

@@ -40,6 +40,19 @@ but it does not authorize a fresh dispatch. Apply the remaining `task_record`
 error rules in [result handling](result-handling.md) before retrying or
 observing.
 
+When the predecessor is bound to a managed workspace, `continue --task` carries
+the recorded workspace, working directory, provider session, and environment
+to the new task ID. It does not mutate the predecessor's immutable request or
+reservation. A changed provider request is a new turn and must pass the normal
+workspace-use reservation. Read [managed workspace guidance](workspaces.md)
+before attaching another provider, review, or verification operation.
+
+If `continue` returns `workspace_busy` with `task_record: "not_created"` and
+`next_action: "watch_workspace"`, observe that workspace with the same root.
+Then retry the exact `continue --task PREDECESSOR_ID` after it becomes retained.
+Keep the original predecessor, brief, and budget; do not replace continuation
+with a fresh dispatch. A created successor is only observed.
+
 `mode` describes the provider contract:
 
 - `native` uses the provider’s exact persisted conversation/session ID;
@@ -53,3 +66,26 @@ terminal outcome or a durable Pueue-ended observation backed by a guardian
 lifetime-termination record with independently proven empty scope for the
 session handoff; without one of those proofs it refuses continuation. Inspect
 the predecessor again rather than bypassing that boundary.
+
+For a managed workspace timeout, capture is a new finite auxiliary operation
+after canonical closure. The normal path proves the provider scope empty and
+records the managed worker's exact `Wait`; recovery can instead use a validated
+absence disposition or previous-boot termination without inventing a native
+`Wait`. Capture never renews the expired provider deadline or reuses its scope. Closure with an
+unavailable capture can still preserve continuation evidence; it does not
+change the provider outcome.
+
+
+## Follow up after normal completion
+
+A validated terminal outcome, committed or rejected, can also support a new
+turn when the provider supports continuation, its exact session was recorded,
+and the runner/session reservation has been released. Not every rejection has
+a usable session. A normal completion without a budget stop need not expose
+`continuation.resumable` in `status` or `collect`. Use `continue` with the exact
+predecessor and a finite budget, then apply its task-creation and failure
+response as described in [result handling](result-handling.md).
+
+If the response says `stop_and_report`, stop that attempt; do not automatically
+retry it. A caller may make a later request after observing the predecessor.
+Native `codex:review` tasks cannot be continued.

package/skills/agent-integration/references/result-handling.md

@@ -13,8 +13,11 @@ the same as a successful provider result.
    `supervisor_control.next_action: "retry_dispatch"`, retry the exact original
    admission argv once. The retry is command-neutral: `dispatch` remains
    `dispatch`, and `continue` remains `continue`; never create a fresh dispatch
-   or call a provider directly to replace a failed continuation. For every
-   other `not_created` response, do not poll; correct the request only if
+   or call a provider directly to replace a failed continuation. Also handle
+   `workspace_provision_pending` or `workspace_busy` with `watch_workspace`
+   using [managed workspace recovery](#managed-workspace-results) before the
+   generic stop rule. For every other `not_created` response, do not poll;
+   correct the request only if
    `failure.next_action` is `correct_request`, otherwise report and stop. When
    `task_record` is `unknown`, stop and report without polling or retrying.
    Status and collect can report `admission: "unknown"` alongside valid terminal
@@ -68,6 +71,47 @@ Versions and help are observations, not semantic-version allowlists.
 Authentication is a separate live gate (`not_run`, `passed`, or `blocked`).
 Report a blocked prerequisite without inventing a login command or retrying.
 
+## Managed workspace results
+
+Treat `response.workspace` as a separate resource and Git-content evidence
+projection. It does not replace `outcome`, `publication`, or `continuation`.
+The provider outcome is immutable and the workspace `CaptureReceipt` is a
+separate immutable fact; a failed or unavailable capture must not be reported
+as a provider failure when native closure is already proven.
+
+Before a task record exists, a pending workspace provision returns
+`task_record: "not_created"` with
+`failure.code: "workspace_provision_pending"` and
+`failure.next_action: "watch_workspace"`. Run the returned workspace-status
+command with the same root and workspace ID. Once ready, retry the same
+admission with the returned task ID in `--id` and unchanged provider, brief,
+permission, model, effort, and source options. A proven never-launched attempt
+gets a fresh helper deadline; a created task is only observed.
+
+An occupied managed workspace can return `workspace_busy` with
+`task_record: "not_created"` and `watch_workspace` before authorizing a task.
+Observe the owning workspace, then retry the exact original admission command.
+For `continue`, keep `continue --task PREDECESSOR_ID`; never replace it with a
+dispatch. These two workspace responses are narrow exceptions to the generic
+stop rule. Do not invent another recovery code or provider retry.
+
+Read the acknowledgement before observing or repeating a workspace mutation:
+
+| Response | Required action |
+| --- | --- |
+| Exit `3`, reason `requested_action_not_authorized`, next action `retry_exec`, `retry_release`, or `retry_forget` | The requested mutation was not accepted. Observe the workspace without `--operation` until the prior use ends, then retry that exact mutation. `exec` and `release` need `state: retained`; `forget` needs `state: released`. |
+| Exit `3`, next action `watch_workspace` | The action is accepted. Observe the same workspace; add `--operation OP` only when its response supplies `operation_id`. Do not repeat the mutation or invent an operation ID. |
+| A concrete failure or `stop_and_report` | Preserve the response and report it; do not turn it into a pending watch or provider fallback. |
+
+Use `workspace status ID [--operation OP] --watch DURATION --json` for these
+observations. An accepted action may not have a helper ID yet. An `exec`
+result of `succeeded` proves the command finished; wait for `state: retained`
+before another use, because recapture must finish too. Verification evidence
+does not replace the provider outcome. Keep the checkout retained until the
+Lead has terminal task/capture evidence and explicitly releases it. Read
+[managed workspace guidance](workspaces.md) for the exact command surface and
+review/capture/forgetting boundaries.
+
 ## Offline recovery
 
 When Delegate returns `failure.next_action: "recheck"`, use the same root and

package/skills/agent-integration/references/workspaces.md

@@ -0,0 +1,197 @@
+# Optional managed Git workspaces
+
+Managed workspaces are an optional Delegate feature for tasks that need a
+retained Git worktree. Ordinary delegation, including ordinary work in a
+non-Git directory, is unchanged. Git is required only when a request creates
+or attaches to a managed workspace (`--isolation git-worktree` or
+`--workspace ID`).
+
+This reference is self-contained guidance for using managed workspaces.
+
+Provider-native permissions still apply inside an isolated checkout. A provider
+may edit files but be unable to stage or commit because linked-worktree Git
+metadata lives outside that checkout. Leave edits uncommitted for capture;
+do not bypass the provider's permissions. When a commit is needed, the Lead can
+explicitly authorize a bounded Git command through `workspace exec`.
+
+Delegate owns durable records, process lifetimes, capture, and recovery; use
+the public commands below to observe and manage them.
+
+## Choose the boundary
+
+For independent parallel write work, choose `--isolation git-worktree`
+automatically unless the user explicitly chooses shared coordination. The
+model chooses the fan-out and task scope; there is no fixed task-count cap and
+no TTL eviction. Shared coordination means the caller deliberately accepts a
+common checkout and its write conflicts. A separate managed workspace is the
+safer default for independent edits.
+
+Automatic provider-agnostic routing still goes through Delegate. A native
+subagent in the current harness remains allowed, and an explicit bypass is
+respected. This workspace feature does not force external routing or replace a
+user's explicit integration choice.
+
+The coordinator owns one workspace usage reservation at a time. A provider
+turn, continuation, read-only review, or verification operation waits for the
+canonical native closure and terminal capture of the current owner. A queue
+row ending or a provider outcome alone is not closure evidence.
+
+## Source and checkout
+
+Create a managed workspace from a committed source base:
+
+```text
+delegate --root ROOT dispatch --isolation git-worktree --cwd ABS \
+  [--base REV] [--workspace-budget DURATION] ... --json
+```
+
+`--base` resolves to a commit; the default is `HEAD`. Dirty and untracked
+source changes are observed but excluded from the managed checkout. The
+provider runs in the retained detached worktree, with the source-relative
+working subdirectory preserved. A request that attaches to an existing
+workspace uses its recorded checkout and source identity:
+
+```text
+delegate --root ROOT dispatch --workspace WORKSPACE_ID ... --json
+```
+
+Public `--workspace` cannot be combined with `--cwd`, `--base`, or
+`--isolation`. It is an attachment by durable ID, not a path alias. The Lead
+owns landing decisions; Delegate does not automatically apply changes, commit,
+create branches, or merge them.
+
+Git-content capture is not a complete filesystem backup, index partition, or
+worker commit-history backup. It does not promise ignored runtime files,
+submodule interiors, empty directories, extended attributes, or LFS payloads
+behind pointers. Read paths from `workspace.artifacts` and verify each
+descriptor’s length and SHA-256 before using its bytes. Entries marked
+`forgetting`, `forgotten`, or `omitted` have no readable path.
+
+Shared Git refs, config, and other global resources mean that
+worktree separation is cooperative checkout isolation, not a security sandbox
+or read-only enforcement. A clean Git status does not prove that a provider
+made no write outside the promised content scope.
+
+## Public commands
+
+The CLI currently exposes these managed-workspace commands:
+
+```text
+delegate --root ROOT workspace list [--after ID] [--limit 1..50] --json
+delegate --root ROOT workspace status ID [--operation OP] [--watch DURATION] --json
+delegate --root ROOT workspace exec ID --budget DURATION --json -- ARGV...
+delegate --root ROOT workspace release ID [--discard] [--budget DURATION] --json
+delegate --root ROOT workspace forget ID [--budget DURATION] --json
+```
+
+`workspace exec` passes `ARGV...` directly to the supervised helper; the
+`--` delimiter makes the arguments literal and no shell is inserted. Its
+initial response is asynchronous and uses exit code `3` while the operation
+is pending. `status` can watch one operation, while `list` returns summaries
+and a cursor for the next page. `--limit` is between 1 and 50.
+Follow the [workspace acknowledgement decisions](result-handling.md#managed-workspace-results)
+before retrying a mutation. A busy precondition and an accepted pending action
+have different next actions; an accepted action can have no helper ID yet.
+
+The workspace helper budget defaults to 5 minutes, is persisted with the
+workspace or operation, and can be overridden by the corresponding budget
+flag. This auxiliary budget is separate from and does not renew the provider
+task budget. The existing `codex:review` default remains 1 hour.
+
+`continue --task PREDECESSOR_ID` inherits the predecessor's managed workspace,
+working directory, provider session, and recorded environment, while creating
+a new task ID. A changed provider request is a new turn; it must not mutate the
+predecessor's immutable records. A retained workspace can be used by a
+read-only review by attaching its ID, for example:
+
+```text
+delegate --root ROOT dispatch --provider codex:review \
+  --workspace WORKSPACE_ID --review-target TARGET --brief ABS_BRIEF \
+  --permission read-only --budget 1h --json
+```
+
+## Capture and verification
+
+The provider outcome and Git-content `CaptureReceipt` are separate immutable
+facts. Normal capture covers the initial committed base through the captured
+tree, including worker commits and added untracked files that belong to the
+Git-content view. It uses a private temporary Git index and records an owned
+base pin plus tree/snapshot reference.
+Optional binary patch and name-status artifacts are bounded to 8 MiB each; an
+overflow is omitted, never silently truncated. Verification diagnostics retain
+an 8 MiB prefix per stream, mark truncation explicitly, and continue draining
+the stream. A verification command's exit is verification evidence, not the
+provider task outcome.
+
+A failed helper may retain an `error.txt` diagnostic with a bounded, validated
+descriptor. It is operation evidence, not captured Git content or a provider
+answer. Diagnostic write failure does not turn a known helper failure into
+success. Temporary result-read errors keep capture retryable.
+
+The normal timeout path is ordered: the provider's native scope closes, the
+managed worker's exact `Wait` is recorded, then a new finite auxiliary capture
+scope runs. Recovery may instead record a validated absence disposition; it
+proves closure without inventing a native `Wait` or provider success. The
+expired provider scope is never renewed or reused. If capture
+is unavailable after closure, the closure evidence can still preserve a valid
+continuation decision; it does not rewrite the provider outcome.
+
+## Retention and forgetting
+
+A created managed checkout is retained for every outcome, including no-op and
+provider-failure outcomes, until the Lead explicitly releases it. A failed
+admission before checkout creation has no checkout to retain. Normal release
+captures final content before exclusive durable cleanup. A failed capture or
+identity check retains the checkout and evidence for retry. `--discard` accepts
+loss of uncaptured checkout content; it does not waive native closure,
+ownership, or identity proof.
+
+Release leaves the pinned refs/blobs and capture receipts as evidence. After a
+proven release, `workspace forget ID` writes an exact inventory intent before
+removing only matching owned refs and optional artifacts by identity/CAS. It
+retains capture receipts, tombstones, all provider outcomes, raw evidence, and
+payload descriptors. Readers should label an intentionally forgotten item as
+`forgotten`, not as corruption.
+
+Release and forget keep a compact container anchor, ownership marker, and durable
+journal metadata. They remove the checkout and the exact evidence authorized by
+the forget inventory. A failed forget attempt can retain a diagnostic written
+after its inventory was committed; do not delete these internal paths manually.
+
+Unknown or busy workspace state is retained and receives no cleanup. There is
+no TTL cleanup, workspace renaming, global Git prune, or unowned goroutine
+unlink path.
+
+## Recovery and review scope
+
+When provision is pending and Delegate proves the provider task was not created,
+the response contains `task_record: "not_created"`,
+`failure.code: "workspace_provision_pending"`, and
+`failure.next_action: "watch_workspace"`. Run the returned recovery command
+with the same state root and workspace ID. Do not poll a nonexistent task or
+start the provider again. An explicit task ID can have unknown creation state;
+follow the returned failure instead of inferring absence.
+
+`state: "preparation_failed"` with `reason_code: "admission_not_launched"`
+means the admission closed without a registered checkout or provider launch.
+Report its `stop_and_report` failure; do not keep watching it as provisioning.
+A short observation window does not cancel accepted scheduling or renew the
+helper's deadline. Continue observing an accepted pending action as directed.
+
+After provision, keep the returned task ID and the same admission inputs when
+retrying a request proven not created. Delegate gives a safely closed attempt
+a new helper identity and deadline; it never reopens the earlier worker or
+renews its deadline. Changed provider input needs a new task ID. Partial setup keeps its
+durable source and ownership records. Explicit release removes only an exactly
+verified owned checkout; changed paths or unverifiable Git metadata remain
+retained with an error. Recovery never creates a checkout just to delete it.
+
+Review the whole delegated turn against its recorded initial base and captured
+tree, including worker commits. For that scope, use an ordinary read-only task
+with explicit base/snapshot refs and a `git diff BASE TREE` instruction. Native
+Codex review targets have their own scope: `uncommitted` covers current staged,
+unstaged, and untracked changes; `base:BRANCH` compares a branch; `commit:SHA`
+reviews a commit. An uncommitted review does not cover changes already committed
+by the worker. Do not pass a tree reference as a branch or assume a native
+target reviews the complete delegated turn. Preserve an explicitly requested
+native review target and state its scope.