delegation-layer 0.1.30 → 0.1.37

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

@@ -3,7 +3,11 @@
 Use the response fields independently. A successful control command is not
 the same as a successful provider result.
 
-1. Save `task_id` immediately after dispatch or continue.
+1. Save `task_id` immediately after dispatch or continue. It is the durable
+   Delegate identity. `supervisor.numeric_task_id` and a stop's
+   `numeric_task_id` are private, ephemeral queue addresses. The queue can
+   reuse a number for a later task, so a repeated number is not a binding
+   error; never use it as a task handle.
 2. For a dispatch or continue error, inspect `task_record` first. When it is
    `created`, observe the returned ID with `status`. Before applying the generic
    `not_created` stop rule, handle the sole migration exception: when
@@ -24,7 +28,13 @@ the same as a successful provider result.
    evidence for an existing task.
 3. If `status` is `timed_out`, follow the continuation procedure before treating
    pending publication as a reason to wait. `continuation.resumable: true`
-   permits a linked successor even when no outcome has been published.
+   permits a linked successor even when no outcome has been published. An
+   `interrupted` task (`failure.code: "task_interrupted"`) follows the table in
+   [interrupted turn](continuation.md#interrupted-turn): continue only when
+   `failure.next_action` is `continue_task` and `continuation.resumable` is
+   `true`, otherwise report it. A `timed_out` task whose `failure.code` is
+   `task_cancelled` is `stop_and_report`: report it and stop, even though
+   `collect` exits `3`; that exit is not success.
 4. If `publication` is committed and `outcome.verdict` is committed, return
    the result and its payload/evidence descriptors.
 5. If `outcome.verdict` is rejected and `failure.next_action` is `recheck`,
@@ -51,7 +61,13 @@ from an inspection-worker or supervisor-observation failure.
 For `delegate models`, validate the complete JSON envelope before using any
 fact. Treat `available` and `partial` with exit `0` as observations, preserve
 `blocked` and `unavailable` with exit `2` as unresolved prerequisites, and
-preserve `failed` with exit `1` as a discovery failure. `complete` refers to
+preserve `failed` as a discovery failure. Exit `1` with `failed` is an
+operational failure; exit `2` with `failed` is an invalid or unsupported
+request, not an authentication block. Status and exit are separate
+observations. When the response
+includes the optional `failure` object and `error` message, keep both in the
+report and follow `failure.next_action`; report and stop on
+`stop_and_report`. `complete` refers to
 model enumeration. Keep `efforts: null` distinct from `efforts: []`, and do not
 apply harness-wide effort choices to every model. Discovery is advisory and
 never an admission allowlist; a provider default remains valid and a listed
@@ -79,6 +95,18 @@ 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.
 
+In task `status` or `collect`, a workspace with `state: "undetermined"`,
+`evidence_state: "unknown"`, and `next_action: "watch_workspace"` means that
+observer's bounded view expired before it read the workspace. It is an
+unobserved view only. It does not imply corruption, change the task fields, or
+revoke an eligible continuation, and it does not turn a committed task into a
+failure. Follow the task fields above: return a committed result, handle a
+rejection using its reported guidance, and keep observing only while the task
+fields are pending. When useful, watch the same workspace with the same root.
+Do not dispatch again, retry the provider, fall back to another integration,
+or repair the environment because of it. A workspace view with `stop_and_report` remains a
+concrete failure to report.
+
 Before a task record exists, a pending workspace provision returns
 `task_record: "not_created"` with
 `failure.code: "workspace_provision_pending"` and
@@ -112,6 +140,42 @@ 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.
 
+## Checkpoint results
+
+A `checkpoint` response has `command: "checkpoint"` and no `task_id` or
+`outcome`. A checkpoint receipt is Git-content evidence; it never replaces a
+provider outcome, and a provider outcome never proves a checkpoint. Read
+`checkpoint.id`, `checkpoint.operation_id`, `checkpoint.current`,
+`checkpoint.operation`, `checkpoint.reason_code`, `checkpoint.next_action`, and
+`error` separately, together with the exit code. Exit `0` alone is not enough.
+
+| Command and response | Meaning and next action |
+| --- | --- |
+| `create`: exit `3`, `id` C, `next_action: "watch_checkpoint"` | Accepted, not yet captured. Watch `status C`; never repeat `create`. |
+| `create`: exit `3`, `requested_action_not_authorized`, `retry_create`, no `id` | Busy refusal; nothing was accepted. Apply the [busy rule](workspaces.md#checkpoint-before-fork). Never wait for your own turn or switch to `--cwd`. |
+| `remove C`: exit `3`, `id` C, `operation_id` R, `watch_checkpoint` | Removal attempt R is accepted. Watch `status C --operation R`; never repeat `remove` to observe it. |
+| `remove C`: exit `3`, `requested_action_not_authorized`, `retry_remove`, no `operation_id` | Not accepted, usually because creation is still pending. The `id` in your command is not a removal ID. Watch `status C` until it settles, then retry `remove C` once. |
+| `remove C`: exit `0` with `operation_id` R | R already succeeded. No new attempt was registered. |
+| `status C`: exit `0` | Successful observation. Fork only when `current.state` is `checkpointed` and `current.usable` is `true`. With `next_action: "stop_and_report"`, report the unavailable creation or latest removal; do not fork. |
+| `status C`: exit `3`, `watch_checkpoint` | Creation or latest removal is still pending. Keep watching the same C. |
+| `status C --operation R`: exit `0`, `1`, or `3` | R's own result: `removed` or `nothing_to_remove` is `0`; `unavailable` is `1` with `stop_and_report`; pending is `3`. A newer attempt in `current.removal` never replaces R's outcome. Keep watching R, not the newer head. |
+| `list`: exit `0` | One metadata page. Entries may be pending, unavailable, or removed. Run `status C` for a reconciled verdict. |
+| Exit `1` with `stop_and_report` | Concrete failure. Report `error` and every ID already returned; do not repeat the mutation. |
+| Exit `2` | Invalid request. Parse errors print usage on stderr without guaranteed JSON; correct the request. |
+
+Take `C` only from `checkpoint.id` and `R` only from `checkpoint.operation_id`
+of a response that returned them. Never invent an operation ID or reuse a
+creation ID as `--operation`. Returned IDs stay valid after a later read
+fault; an unreadable `current` or `operation` is omitted rather than shown as
+empty availability.
+
+`status --watch` repeats the same observation of the same IDs until a settled
+or failed result or the bound ends. It never begins another action, renews a
+helper deadline, or cancels accepted work. The latest observation chooses the
+exit. A watch that ends at exit `3` means keep observing; it is not a failure.
+If writing the response itself fails (exit `1`), accepted work stays accepted;
+observe it with `status` instead of repeating the mutation.
+
 ## Offline recovery
 
 When Delegate returns `failure.next_action: "recheck"`, use the same root and

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

@@ -4,7 +4,7 @@ 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`).
+`--workspace ID`), or creates or removes a [Git checkpoint](#git-checkpoints).
 
 This reference is self-contained guidance for using managed workspaces.
 
@@ -48,7 +48,10 @@ delegate --root ROOT dispatch --isolation git-worktree --cwd ABS \
 `--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
+working subdirectory preserved. The source may itself be a managed checkout,
+such as a sibling in the same workspace container. After provisioning, the new
+workspace depends on the shared repository, not on the source checkout, so
+removing that source does not block capture, release, or forget. A request that attaches to an existing
 workspace uses its recorded checkout and source identity:
 
 ```text
@@ -117,6 +120,36 @@ 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.
+
+Each provider turn also records its actual starting tree, `HEAD`, and index
+identity just before launch, so Lead edits made between turns belong to the
+next turn's start. The index identity covers every entry's mode, object, stage
+(including conflicts), path, assume-unchanged or skip-worktree flag, and
+intent-to-add (`git add -N`) state, but not stat caches or `HEAD`. A task capture's `candidate.turn` compares that start with the
+final capture: `content`, `head`, and `index` are `changed` or `unchanged`, and
+`baseline_ref` keeps the start tree. This is observed evidence, not
+enforcement: a read-only turn that commits or edits is reported, not rejected,
+and writes reverted before capture or ignored files are not observed.
+`status: "unavailable"` with `reason_code: "baseline_unavailable"` means no
+baseline exists, for example for a turn started before this evidence existed;
+treat it as unknown, never as unchanged. A capture without `candidate.turn`,
+such as one recorded before per-turn evidence existed or a release or exec
+recapture, is also unknown, never unchanged. A failed baseline refuses the
+provider launch for that task.
+
+An observed turn adds `turn-diff.patch` and `turn-name-status.z`, which diff
+that turn's start tree to the final tree with the same bounds as the
+cumulative artifacts. Use them to see which files the current turn touched;
+they exclude earlier turns and Lead edits made before its launch. Use the
+cumulative `diff.patch` and `name-status.z`, from the workspace base, to land
+or review the whole delegated result. Report a read-only turn whose `content`,
+`head`, or `index` is `changed` as a mutation, even when its turn file list is
+empty, and report an unavailable turn as unknown.
+
+`status` and `collect` for a task report that task's own capture, even after a
+later turn has used the workspace. The workspace `state` still reflects the
+resource now, so a sealed earlier capture does not make a busy, released, or
+forgotten workspace usable. `workspace status` reports the latest use.
 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
@@ -136,6 +169,98 @@ 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.
 
+## Git checkpoints
+
+A checkpoint records the current Git content of one checkout as a synthetic
+commit pinned by the owned ref `refs/delegate/ROOT_ID/checkpoints/CHECKPOINT_ID`.
+It does not move `HEAD`, create or switch a branch, or change the real index.
+The commit's tree is the full current Git-content view, built through a private
+index with the capture algorithm above, so the same exclusions apply. Its single
+parent is the `HEAD` the helper observed. Author, committer, and timestamp are
+fixed Delegate values; trailers carry the checkpoint ID and request digest.
+This is unrelated to a provider continuation `mode: "checkpoint"`.
+
+```text
+delegate --root ROOT checkpoint create --cwd ABS [--budget DURATION] --json
+delegate --root ROOT checkpoint create --workspace ID [--budget DURATION] --json
+delegate --root ROOT checkpoint status CHECKPOINT_ID [--operation OP] [--watch DURATION] --json
+delegate --root ROOT checkpoint list [--after CHECKPOINT_ID] [--limit 1..50] --json
+delegate --root ROOT checkpoint remove CHECKPOINT_ID [--budget DURATION] --json
+```
+
+- `create` names exactly one target: `--cwd` for an absolute ordinary Git
+  checkout directory, or `--workspace` for a managed workspace ID. Nothing is
+  inferred from the current directory. Select a managed checkout only by
+  `--workspace ID`; never pass its path as `--cwd`.
+- `status` and `remove` take the checkpoint ID `C` from the create response.
+  `list` takes no target and runs no Git command.
+- Only `create --cwd` may initialize a new state root. Every other checkpoint
+  command needs the existing root and fails with exit `1` without creating it.
+  Use one state root for every command about the same checkpoint.
+- `--budget` is the finite helper budget (default 5m). It is persisted with the
+  operation and does not renew any provider task budget. `--watch` exists only
+  on `status`.
+
+A managed checkpoint is a workspace use. It needs the workspace's use owner and
+holds that workspace's usage reservation while its helper runs, so a concurrent
+turn or `workspace exec` on that workspace gets the normal busy response. It
+closes without content capture. Create it while the workspace is retained.
+
+Delegate does not restore, apply, merge, or land a checkpoint into any checkout.
+It does not control nested delegation budgets or lifetimes either. A fork from
+a checkpoint is an ordinary new managed dispatch with its own task budget.
+
+### Checkpoint before fork
+
+Use this sequence to start an isolated worker from current uncommitted work.
+Save every response and exit code once; follow
+[checkpoint results](result-handling.md#checkpoint-results) for each one.
+
+1. Run `checkpoint create` with one target. Exit `3` with `checkpoint.id` and
+   `next_action: "watch_checkpoint"` means the request was accepted. It does
+   not mean the content was captured. Save that exact ID as `C`.
+2. Run `checkpoint status C --watch 30s --json` until the exit is not `3`.
+   Never repeat `create` to observe it.
+3. Fork only when `status` exits `0` and `checkpoint.current.state` is
+   `checkpointed` and `checkpoint.current.usable` is `true`. A `commit_oid` or
+   `snapshot_ref` alone is not proof: an unavailable creation can still name a
+   retained candidate.
+4. Dispatch the worker with the qualified `checkpoint.current.commit_oid` as
+   the existing `--base` of a new managed workspace. Use an ordinary checkout of
+   the same repository as `--cwd`, normally the source the Lead already uses:
+
+   ```text
+   delegate --root ROOT dispatch --auto --brief ABS_BRIEF --cwd ABS_SOURCE \
+     --isolation git-worktree --base COMMIT_OID \
+     --permission workspace-write --budget 30m --json
+   ```
+
+5. Remove the checkpoint explicitly when the Lead no longer needs it.
+
+`status` exit `0` means a successful metadata observation, not an available
+checkpoint. `usable` is `true` only for a `checkpointed` creation with no
+registered removal attempt, including a failed one. It is derived from
+Delegate's records; it is not proof that an external Git command left the ref
+in place.
+
+If `checkpoint create --workspace ID` returns exit `3` with
+`reason_code: "requested_action_not_authorized"` and `retry_create`, no
+checkpoint was accepted and no ID was assigned. When that workspace is in use
+by the turn you are running in, do not wait for yourself, retry in a loop, or
+retry through `--cwd`. Finish and report; the Lead creates the checkpoint after
+your turn closes. When another use holds it, the Lead observes that workspace
+until it is retained again, then retries the same create once.
+
+Checkpoint refs outlive `workspace release` and `workspace forget`: the forget
+inventory covers only the workspace's own base, capture, and baseline refs.
+`checkpoint remove C` is the only command that removes a checkpoint ref.
+Removal needs only the shared Git common directory, so it works after the
+source checkout or managed checkout is gone. A missing or replaced common
+directory makes that removal attempt `unavailable`, never `removed`. Creation
+history stays observable after removal: `current.state` keeps the creation
+disposition, while `current.usable` becomes `false` and `current.removal`
+shows the latest attempt.
+
 ## Retention and forgetting
 
 A created managed checkout is retained for every outcome, including no-op and
@@ -146,9 +271,10 @@ 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
+Release leaves the pinned refs/blobs, turn-baseline refs, 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.