pi-background-tasks 0.9.0 → 1.0.3

package/docs/reference/shortcuts-and-dock.md

@@ -0,0 +1,70 @@
+---
+doc_id: reference/shortcuts-and-dock
+audience: user
+mode: mixed
+review_policy: contract
+stability: stable
+covers_surfaces: ['shortcut:ctrl+alt+c', 'shortcut:shift+down']
+covers_sources: []
+---
+# Shortcuts and dock reference
+
+<!-- pi-docs:begin name="shortcut-contracts" generator="scripts/docs/generate.mjs" -->
+| Shortcut | Description | Provenance |
+| --- | --- | --- |
+| `ctrl+alt+c` | Clear finished background task footer notices (terminal-dependent fallback for /bg-clear) | `src/extension.ts:586` |
+| `shift+down` | Open focused background task footer dock | `src/extension.ts:579` |
+<!-- pi-docs:end name="shortcut-contracts" -->
+
+## Registered shortcuts
+
+| Shortcut | Behavior |
+|---|---|
+| `Shift+Down` | Open the focused background task footer dock / task manager. |
+| `Ctrl+Alt+C` | Clear finished background task footer notices; this is an optional terminal-dependent fallback for [`/bg-clear`](../commands/bg-clear.md). |
+
+If a terminal does not deliver `Ctrl+Alt+C`, use `/bg-clear`. It is the canonical command path.
+
+## Footer states
+
+The footer appears when there are running tasks, unseen finished tasks, or an update segment. Count labels are:
+
+- `running` for active tasks;
+- `failed` for status `failed`;
+- `stopped` for status `killed`;
+- `done` for status `completed`.
+
+Examples:
+
+```text
+bg 1 running · Shift↓
+bg 1 done · Shift↓ · /bg-clear
+bg 1 running · 1 failed · 1 stopped · 1 done · Shift↓ · /bg-clear
+bg 1 running · Shift↓ · ⬆ v999.0.0 /bg-update
+bg 1 running · focused
+```
+
+The `/bg-clear` hint is hidden while the dock is open, where the entry hint becomes `focused`. A finished task's badge is marked seen when its detail view opens; `/bg-clear` or `Ctrl+Alt+C` marks all currently unseen finished tasks seen. Merely opening the list view or closing the dock does not clear badges.
+
+## Dock entry points
+
+- `Shift+Down`
+- [`/tasks`](../commands/task-manager.md)
+- [`/bg-tasks`](../commands/task-manager.md)
+
+All open the same task manager when an interactive UI is available.
+
+## Dock output detail
+
+The detail view follows a UI-only 128 KiB tail buffer, refreshes once per second while following, and shows 12 output lines. Scrolling up pauses following; reaching the bottom or pressing `r` resumes it.
+
+## Related docs
+
+- [`/bg-clear`](../commands/bg-clear.md)
+- [`/tasks` and `/bg-tasks`](../commands/task-manager.md)
+- [`/bg-update`](../commands/bg-update.md)
+- [Host UI and telemetry](../subsystems/host-ui-and-telemetry.md)
+
+## Source ownership/reference
+
+Shortcut and footer implementation is owned by [host-ui-and-telemetry](../subsystems/host-ui-and-telemetry.md).

package/docs/subsystems/attested-pi-runs.md

@@ -0,0 +1,141 @@
+---
+doc_id: subsystems/attested-pi-runs
+audience: maintainer
+mode: authored
+review_policy: behavioral
+stability: evolving
+covers_surfaces: []
+covers_sources: [src/core/attested-pi-run.ts]
+---
+# Attested Pi runs subsystem
+
+This document is the primary behavioral owner for `src/core/attested-pi-run.ts`.
+
+It does **not** claim ownership of shared registry, Pi-launch, common task, or durable-fs modules. Those modules spawn the prepared request, store task metadata, publish terminal state, and provide atomic write primitives used by this subsystem.
+
+## Purpose
+
+Attested Pi runs are opt-in local-evidence tasks for a structured child Pi invocation. They are intended for cases where an operator wants local hashes and observed route/auth/session facts, not just a background output file.
+
+They do not replace ordinary `bg_run`, and they do not provide remote cryptographic proof.
+
+## Structured request and argv
+
+The request shape is:
+
+- `name`
+- `provider`
+- `model`
+- `prompt`
+- `reportPath`
+- optional `extraPiArgs`
+- optional `thinking`
+- optional `timeoutSeconds`
+
+Validation rejects blank `name`, `provider`, `model`, `reportPath`, and empty `prompt`. `reportPath` must resolve inside task cwd and may not target `.git` or `.pi/tasks`.
+
+The logical argv always begins:
+
+```text
+pi --mode json --provider <provider> --model <model>
+```
+
+Then optional `--thinking <thinking>`, then literal `extraPiArgs`, then the prompt as the final user prompt argument. Forbidden extra args are direct auth (`--api-key`, `--auth-file`), mode/print (`-p`, `--print`, `--mode`), and duplicate structured fields (`--provider`, `--model`, `--thinking`).
+
+The registry launches exactly one child through the resolved Pi executable with `shell:false`. The attestation records the stable logical argv (`['pi', ...]`), not platform-specific Windows Node/CLI shims. Attested tasks are created with generic background completion notification/wake disabled; terminal snapshots are still published through the task system.
+
+## Auth and environment boundary
+
+The child environment removes direct/metered API configuration:
+
+- `OPENROUTER_API_KEY`, `OPENROUTER_BASE_URL`
+- `OPENAI_API_KEY`, `OPENAI_BASE_URL`
+- `ANTHROPIC_API_KEY`, `ANTHROPIC_BASE_URL`
+- `PI_API_KEY`, `PI_API_BASE_URL`, `PI_AUTH_FILE`
+
+The producer observes auth through the model registry before spawn. The selected model must exist and `ModelRegistry.isUsingOAuth(selected)` must be available and true. Current accepted provider classes are:
+
+- `openai-codex` → `pi-codex-oauth`, `subscription-codex`;
+- `anthropic` → `pi-anthropic-oauth`, `subscription-anthropic`.
+
+Any unsupported provider or non-OAuth route fails before attestation.
+
+## Event parsing and observed route
+
+Raw child stdout is captured as Pi JSON events. A successful stream must be newline-terminated and contain:
+
+- exactly one `session` with id/cwd;
+- exactly one `agent_start`;
+- at least one assistant `message_end`;
+- exactly one `agent_end`;
+- the last assistant `stopReason` value reported in the stream is `stop`; messages that omit `stopReason` do not replace an earlier reported value;
+- stable assistant provider/model across assistant messages;
+- no assistant error.
+
+The parsed provider/model must match the model selected from the registry. Token usage, cost total when present, tool usage, and a human transcript are derived from these events.
+
+## Git authority
+
+Before spawn, the subsystem records:
+
+- git `HEAD` commit;
+- git `HEAD^{tree}`;
+- `git status --porcelain=v1 --untracked-files=all` cleanliness;
+- repository root realpath;
+- cwd realpath.
+
+The worktree must be clean at start. On successful child completion, finish commit/tree/cleanliness are checked again. Changed commit/tree or dirty worktree prevents attestation.
+
+## Files and hashes
+
+Runtime paths are allocated by the background registry under `.pi/tasks/<session-id>-<pid>/`:
+
+- `<task-id>.output`
+- `<task-id>.json`
+- `<task-id>.pi-events.jsonl`
+- `<task-id>.stderr`
+- `<task-id>.pi-telemetry-wrapper.cjs`
+- `<task-id>.attestation.json`
+
+The wrapper file is a note that the task is direct-spawned and no shell telemetry wrapper is used. The sidecar hashes metadata, output, events, stderr, wrapper, prompt bytes, and the required report file.
+
+The sidecar schema is `phase2.pi_task_attestation.v1`. It includes locator, source hashes, lifecycle, invocation/auth facts, git authority, artifact hashes, and a self hash (`attestation_sha256`) over canonical sidecar content excluding that self field.
+
+## Durability and visibility
+
+Initial output/events/stderr/wrapper files and metadata are created before spawn. On close, stdout/stderr buffers are fsynced to the events/stderr files. Successful event parsing rewrites task output from the parsed transcript; failures write diagnostics/stderr output.
+
+For a completed child with parsed events, the registry asks this subsystem to build the attestation, then writes `<task-id>.attestation.json` using durable atomic replacement. Only after that write returns does the registry set in-memory `task.status` to `completed` and publish terminal state. The metadata file may receive a completed snapshot earlier in this path; terminal in-memory/UI visibility is held until after sidecar durability.
+
+## Failure and no-partial-sidecar behavior
+
+No successful sidecar is emitted when:
+
+- request validation fails;
+- route/auth observation fails;
+- worktree is dirty at start;
+- child spawn fails;
+- child exits non-zero, times out, or is killed;
+- stdout events are malformed, incomplete, not newline-terminated, route-drifted, or the last reported assistant stop reason is not `stop`;
+- the expected report file is missing/unreadable;
+- git authority changes or finish worktree is dirty;
+- attestation construction or durable sidecar write fails.
+
+Raw evidence files remain for diagnosis. Sidecar final-name writes use atomic replacement, so ordinary write failures do not create a truncated final sidecar that looks complete. If sidecar construction/write fails after earlier metadata work, the task is marked failed.
+
+## Trust boundary
+
+The sidecar is unsigned local evidence in a same-user-writable working tree/task store. It states what this extension observed and hashed locally. It is not a signature, not tamper-proof, not a remote cryptographic proof, and not evidence against an attacker who can modify the repository or `.pi/tasks` artifacts.
+
+## Maintainer checklist
+
+When changing this subsystem, re-check:
+
+- forbidden auth/mode/provider/model/thinking args;
+- OAuth-only observation and provider class mapping;
+- stripped metered environment keys;
+- JSON event strictness and route consistency;
+- git clean/commit/tree checks at start and finish;
+- prompt/report/events/stderr/output/wrapper/metadata hash coverage;
+- sidecar write ordering relative to terminal visibility;
+- no sidecar on failure paths.

package/docs/subsystems/background-task-runtime.md

@@ -0,0 +1,85 @@
+---
+doc_id: subsystems/background-task-runtime
+audience: maintainer
+mode: authored
+review_policy: behavioral
+stability: stable
+covers_surfaces: []
+covers_sources: [src/core/common.ts, src/core/registry.ts, src/core/windows-taskkill.ts]
+---
+# Background task runtime
+
+The runtime owns task identity, shell invocation, process lifecycle, bounded logs, metadata, telemetry ingestion, completion publication, and platform termination.
+
+## Core contracts
+
+- Task statuses are exactly `running`, `completed`, `failed`, and `killed`.
+- Terminal statuses are exactly `completed`, `failed`, and `killed`.
+- Runtime directory: `.pi/tasks/<session-id>-<pid>/` under the project cwd.
+- Per task: `<task-id>.output` and `<task-id>.json`; some agent modes may add wrapper or attestation files.
+- In-memory recent retention prunes oldest finished tasks over the limit while preserving running tasks.
+- `resolveTask` accepts exact ids or unambiguous prefixes and fails loudly for empty, unknown, or ambiguous ids.
+
+## Starting ordinary tasks
+
+`startTask` trims surrounding command whitespace and rejects an empty command. It derives task name from explicit `name`, then `description`, then command. Names are compacted and truncated; callers should still provide concise names.
+
+Shell commands are spawned in the task cwd using `stdio: ['ignore','pipe','pipe']`, `windowsHide:true`, the extension environment, and detached process groups on non-Windows. Shell commands are **not sandboxed**.
+
+Default delivery at registry level is `notifyOnCompletion:true` and `triggerOnCompletion:false`; surface tools may override that. [`bg_run`](../tools/bg_run.md) explicitly defaults both to true.
+
+## Shell policy
+
+POSIX uses `$SHELL` when set, otherwise `/bin/sh`, with `-c <command>`.
+
+Windows defaults to `cmd.exe` or `ComSpec`, with args `['/d','/s','/c','"<command>"']` and `windowsVerbatimArguments:true`. `PI_BG_SHELL=cmd|bash` can select a shell; `PI_BG_SHELL_PATH` is accepted only with `PI_BG_SHELL` and must be an absolute `.exe`/`.com` path. `PI_BG_SHELL=bash` without a path searches PATH for `bash.exe` or `bash.com`; unresolved or invalid shell settings fail before creating a task.
+
+## Logs and output caps
+
+All child stdout/stderr is written to the output file unless it is recognized control telemetry from a wrapped Pi agent. The runtime enforces `PI_BG_MAX_OUTPUT_BYTES` or the default 20 MiB output cap; exceeding it appends an error notice, kills the task, and finalizes as `failed`.
+
+Model-visible log reads use bounded file reads capped by `MAX_LOG_BYTES` (currently up to 50 KiB). Truncated reads preserve the full output path in the notice.
+
+## Telemetry
+
+Telemetry is task-owned. It is parsed from task output/control lines when the task reports it; it is never copied from the parent session. Optional telemetry includes context usage, token usage, tool usage, and model. Malformed optional telemetry is ignored without clearing prior task state; unknown wrapped-agent JSON is written to the transcript rather than silently dropped.
+
+`isAgent` explicitly controls telemetry wrapping. If `isAgent:false`, a `pi -p` command is treated as an ordinary command. If `isAgent:true` and the POSIX command contains an interceptable `pi -p`, `pi --print`, or `pi --mode json` invocation, the runtime writes a wrapper and converts Pi JSON events into task-owned metrics and human transcript lines. Path-qualified `pi` commands are not intercepted. On Windows cmd, telemetry wrapping is unavailable and the task records `win32-cmd-cannot-safely-intercept-pi-argv`.
+
+## Finalization and completion
+
+A child closing with code `0` becomes `completed` unless killed/timeout/cap state overrides it. Nonzero exit becomes `failed` with `Exited with code ...`. User or shutdown kills become `killed`; timeout and output cap become `failed`.
+
+During finalization, the runtime flushes wrapped-agent output, ends and waits for the output stream to finish/close, writes terminal metadata through the durable metadata path, updates waiters, initiates terminal EventBus publication, sends the completion notification when enabled and not shutting down, persists notification state, then prunes old finished tasks. Actual EventBus emission may wait behind the run-response publication gate and therefore may occur after the completion notification; it still occurs only after stream close and terminal metadata. The registry calls a historically named `closeAndFsyncOutputStream()` helper, but its current implementation ends and observes the stream rather than issuing `fsync` for ordinary `.output`; durable terminal truth refers to the metadata-backed status, not a stronger crash-durability guarantee for every output byte.
+
+## Stopping tasks
+
+Only `running` tasks can be stopped.
+
+POSIX stop path:
+
+1. send `SIGTERM` to the detached process group (`-pid`),
+2. if that fails, call the child handle's `kill`,
+3. after the grace window, send one `SIGKILL` escalation.
+
+Windows stop path:
+
+1. run `%SystemRoot%\System32\taskkill.exe /PID <pid> /T`, or `%WINDIR%` fallback,
+2. after the grace window, abort the soft helper and run `/F`,
+3. treat taskkill exit 128 as an already-exited race,
+4. surface force failures loudly with `Descendant processes may have leaked`.
+
+Windows never falls back to root-only `child.kill` for tree termination. The taskkill helper uses structured argv, `shell:false`, bounded stdout/stderr capture, external abort, and a helper timeout.
+
+## Related docs
+
+- [`bg_run`](../tools/bg_run.md)
+- [`bg_status`](../tools/bg_status.md)
+- [`bg_logs`](../tools/bg_logs.md)
+- [`bg_kill`](../tools/bg_kill.md)
+- [Completion delivery](../concepts/completion-delivery.md)
+- [Host UI and telemetry](host-ui-and-telemetry.md)
+
+## Source ownership/reference
+
+Primary source ownership for this document is `src/core/common.ts`, `src/core/registry.ts`, and `src/core/windows-taskkill.ts`.

package/docs/subsystems/child-launch-durability-and-safety.md

@@ -0,0 +1,57 @@
+---
+doc_id: subsystems/child-launch-durability-and-safety
+audience: maintainer
+mode: authored
+review_policy: behavioral
+stability: evolving
+covers_surfaces: []
+covers_sources: [src/core/durable-fs.ts, src/core/pi-launch.ts]
+---
+# Child launch, durability, and safety
+
+Primary sources: `src/core/pi-launch.ts` and `src/core/durable-fs.ts`.
+
+## Pi launch resolution
+
+On non-Windows platforms, `resolvePiLaunch()` returns `{ executable: 'pi', argvPrefix: [], kind: 'path' }`.
+
+On Windows, the package does not trust shell PATH shims. It resolves `@earendil-works/pi-coding-agent/package.json`, reads `bin.pi`, realpaths the package root and bin target, verifies the target stays inside the package root, and accepts only a regular file with one of these forms:
+
+- `.js`, `.cjs`, `.mjs`: launch with `process.execPath` and the target as `argvPrefix[0]`;
+- `.exe`, `.com`: launch the target directly.
+
+Resolution failures throw `PiLaunchResolutionError` with code `pi_executable_resolution_failed`; no substitute route or shell fallback is selected.
+
+## Windows argv and command-line length
+
+`assertWindowsCommandLineWithinLimit()` renders the exact Windows command line with Windows quoting rules, measures UTF-16 length plus the terminating NUL, and throws `PiCommandLineLimitError` (`pi_command_line_too_long`) if it exceeds 32,767 characters. The check is used before child launches that construct `pi` argv.
+
+Delegate seed bytes are delivered over stdin, not argv, so large seeds do not rely on command-line quoting or shell length limits.
+
+## Durable write invariant
+
+`durable-fs.ts` provides two public operations:
+
+- `writeFileDurable(path, data)`: open the target once with `w`, write, `sync()`, close.
+- `replaceFileDurable(path, data)`: create a task-owned temp file with exclusive `wx` at `0o600`, write, `sync()`, close, rename over the target, then directory-sync on non-Windows.
+
+Invariant: a pathname is never reopened merely to fsync it. Sync failures are fatal and surfaced as `DurableFileError`; cleanup failures are retained in the error object instead of hiding the primary failure.
+
+Temp ownership matters: if exclusive temp creation collides, the caller does not delete the other writer's file. A successful rename is the commit point; if a post-rename directory sync fails, the error marks `renameCompleted: true` because the replacement may already be visible.
+
+## POSIX directory sync limitation
+
+After atomic replace, POSIX-like platforms open and sync the parent directory to durably record the rename. Windows skips directory sync because Node/Windows directory fsync is not portable in the same way. This is an explicit platform limitation, not a silent success claim; file contents are still written and synced before rename.
+
+## Process trust boundaries
+
+- Background shell tasks run the operator-provided shell command in the project cwd and are not sandboxed.
+- Delegate children are direct `pi` spawns, not shell commands. They use a task-owned session id and session dir, stripped parent session environment, disabled discovery, and an explicit child guard extension.
+- Fusion children are direct `pi --mode text` spawns with private metadata/tool-call audit extensions and workflow-specific tool policy.
+- Attested Pi tasks are direct `pi --mode json` spawns and produce evidence sidecars after successful parsing and durability.
+
+Never blur parent and child authority: parent tools can start/inspect/kill tasks, but child tools must stay within their explicit argv tool set.
+
+## Terminal integrity
+
+Task terminal status is not published until output streams are ended and observed finished/closed and terminal metadata is written. Ordinary task `.output` streams are not explicitly fsynced; attested event/stderr buffers and atomic metadata/artifact paths use the durable helpers described above. If stream close or terminal metadata fails, the task is marked failed; terminal truth is not guessed from the process exit alone.

package/docs/subsystems/delegation.md

@@ -0,0 +1,190 @@
+---
+doc_id: subsystems/delegation
+audience: maintainer
+mode: authored
+review_policy: behavioral
+stability: evolving
+covers_surfaces: []
+covers_sources: [extensions/delegate-child.ts, src/core/delegate/artifacts.ts, src/core/delegate/budget.ts, src/core/delegate/hook-contract-evidence.json, src/core/delegate/hook-contract.ts, src/core/delegate/launch.ts, src/core/delegate/result-package.ts, src/core/delegate/runner.ts, src/core/delegate/seed.ts, src/core/delegate/types.ts, src/delegate-child-extension.ts, src/delegate-extension.ts]
+---
+# Delegation subsystem
+
+This document is the primary behavioral owner for delegation runtime code:
+
+- `src/delegate-extension.ts`
+- `src/delegate-child-extension.ts`
+- `extensions/delegate-child.ts`
+- every current file under `src/core/delegate/**`, including `hook-contract-evidence.json`
+
+It does **not** claim ownership of shared `common`, `registry`, `pi-launch`, or `durable-fs`; delegation consumes those integration points.
+
+## Behavioral contract
+
+Delegation provides one background child Pi agent, one directive, one pinned route, and read-only inspection tools. The parent gets a launch receipt immediately and later retrieves a verified answer through `bg_result`.
+
+The design deliberately separates:
+
+- launch admission (no side effects on refusal),
+- child isolation and runtime guards,
+- child answer commit (`result.json`),
+- parent adjudication (`outcome.json`),
+- user retrieval (`bg_result`).
+
+## Seed and context policy
+
+The seed schema is `pi-background-tasks.delegate-seed.v1`. It wraps the frozen `visible-conversation-ledger-v2` projection under delegate policy id `delegate-inspect-v1`; it never emits Fusion input schemas or claims Fusion provenance.
+
+Projection behavior:
+
+| Source content | Delegate seed behavior |
+|---|---|
+| user text | included verbatim |
+| assistant text | included verbatim |
+| user images | marker text only |
+| assistant thinking | omitted; ledger row with bytes/hash/count |
+| tool-call arguments | omitted; ledger row with bytes/hash/tool name/call id |
+| tool-result text | omitted; ledger row with bytes/hash/tool name/call id |
+| tool-result images | ledger-only omission with bytes/hash/mime |
+| unknown blocks | projection failure; no child |
+
+The assistant message containing the active `bg_delegate` call is excluded as a whole. Therefore sibling tool calls in the same assistant message are not visible to any child launched by that batch.
+
+`directive.text` is stored exactly, hashed, and marked `authority: "explicit_text"`. The child prompt and system prompt state that the directive is authoritative and projected history is untrusted supporting context. Omitted parent tool output cannot be recovered by the child; the child is instructed to say so rather than guess.
+
+## Launch and isolation
+
+Public admission first loads hook evidence and resolves the requested/current route; launch preparation then resolves the package-owned child guard extension. Inside `preflightDelegateLaunch()`, the hook-contract gate runs before capability/tool policy, limit checks, seed construction, and launch budget admission. All of these checks complete before child process, child session directory, or artifact root creation. Route, guard-extension, hook-contract, or later admission refusal therefore leaves zero child processes and zero delegate artifacts; do not rely on one absolute error-precedence order across those pre-preflight resolutions.
+
+The child launch:
+
+- direct Pi spawn through the registry, not a shell;
+- prompt bytes over stdin, not a positional/shell argument;
+- separate random `--session-id`;
+- task-owned `--session-dir` under the artifact directory;
+- parent session/provider/model/reasoning env keys stripped;
+- only package-owned child guard extension explicitly loaded;
+- ambient extension/skill/template/theme/context discovery disabled.
+
+The only v1 capability is `inspect`. Allowed tools are exactly `read`, `grep`, `find`, `ls`, and `delegate_read_artifact`; forbidden tools deny shell, writes, background task controls, recursive delegation, attested Pi launch, and Fusion. The boundary is argv/tool-registry enforced.
+
+## Route and budget
+
+Routes are pinned once:
+
+- omitted route → parent current model;
+- explicit route → exact registry entry;
+- unavailable/unknown-capacity routes fail;
+- no substitution, fallback, or retry on a different route.
+
+Budgets use a delegate-specific conservative estimator. Constants currently documented by source/tests:
+
+- reserved output: `16,384` tokens;
+- framing reserve: `8,192` tokens;
+- safety reserve: `4,096` tokens;
+- minimum usable input: `8,192` tokens;
+- default turns/tools/timeout: `24` / `120` / `1200s`;
+- per-result transcript cap: `64 KiB`;
+- aggregate tool-output cap: `64 MiB`;
+- answer capture cap value carried in the seed: `4 MiB`; current child code does not separately enforce this before packaging;
+- inline answer cap: `48 KiB`.
+
+Launch admission measures the child system prompt plus the actual child prompt carrying the seed. Runtime guard measures retained input before every model call. An over-budget runtime call latches `provider_context_budget_exhausted`, aborts the run, and suppresses outgoing content.
+
+## Child guard and commit discipline
+
+The child verifies seed hash, task id, and launch nonce at extension load before the first model call. It then enforces:
+
+- context budget before every provider call;
+- per-result spill receipts before tool output enters the transcript;
+- aggregate tool-output cap;
+- turn and tool-call limits;
+- route attestation for assistant messages;
+- complete usage records only (missing/partial usage is `unavailable`, never zero);
+- accepted final stop reason `stop` only, so provider `length` stops become `child_model_output_limit` rather than partial success;
+- non-empty, non-whitespace answer text;
+- well-formed UTF-8 answer blocks.
+
+A terminal latch prevents later success commit after any degraded/refused condition. This avoids a hash-valid result built on silently modified context.
+
+`result.json` is the single answer data plane. It is child-written by temp file, file fsync, and rename; POSIX then fsyncs the parent directory, while Windows skips directory fsync because Node does not provide the same portable guarantee there. Final-name presence is the child commit point. No final `result.json` means no accepted answer, regardless of process exit code. `child-terminal.json` records child-side terminal failures when no success package is committed.
+
+After adjudication, the parent makes a best-effort durable write of `outcome.json`. This is separate from `result.json` so child and parent cannot race over one state field. An `outcome.json` write failure is currently ignored and does not change the returned adjudication, so the artifact may be absent even though evaluation completed. Child stdout/stderr are currently captured in the background task output file; although delegate artifact constants name `child.stdout.txt` and `child.stderr.txt`, current registry finalization does not populate those files in the delegate artifact directory.
+
+## Spill artifacts and `delegate_read_artifact`
+
+Oversized tool results are durably written in full under `spill/` and replaced with receipts. A failed spill withholds the original payload and latches a terminal failure; no uncommitted artifact is claimed by receipt.
+
+`delegate_read_artifact` requires:
+
+- `artifact: string` relative to the delegate artifact root;
+- `offset: non-negative safe integer`;
+- `length: positive safe integer`.
+
+It reads the whole artifact file, verifies the requested range is in bounds, and returns exactly that UTF-8-decoded range. Path escape and short reads fail loudly.
+
+## Retrieval contract
+
+`bg_result` verifies committed packages before returning bytes. It checks identity, seed hash, route and route attestations, schema, usage shape, strict base64, per-block hashes, aggregate hash, byte lengths, and UTF-8 round trip. Running tasks return a not-ready view (`state:"running"`, `delivery:"none"`) without blocking.
+
+Default delivery inlines answers up to `48 KiB`; larger answers return artifact metadata. Explicit oversized inline requests fail with `result_too_large_for_inline`. Answers are never truncated.
+
+Current `autoDeliver` status: `bg_delegate` accepts and records `never | when_small | always` and includes it in launch facts/details. The registry's generic terminal notification currently does not evaluate delegate results or include answer text, so `bg_result` remains the retrieval path.
+
+## User-oriented failure taxonomy
+
+Admission / no child:
+
+- `delegate_hook_contract_unsupported`
+- `delegate_isolation_unsupported`
+- `route_unresolved`
+- `route_capacity_unknown`
+- `seed_projection_failed`
+- `seed_budget_exceeded`
+- `seed_persist_failed`
+- `invalid_arguments`
+
+Launch / execution:
+
+- `child_spawn_failed`
+- `child_startup_failed`
+- `child_timeout`
+- `child_cancelled`
+- `child_turn_limit`
+- `child_tool_call_limit`
+- `child_exited_without_commit`
+
+Budget / limits:
+
+- `provider_context_budget_exhausted`
+- `aggregate_tool_output_cap`
+- `child_model_output_limit`
+- `child_capture_limit`
+
+Integrity / artifacts:
+
+- `child_result_invalid`
+- `child_result_encoding_invalid`
+- `route_attestation_missing`
+- `route_mismatch`
+- `seed_hash_mismatch`
+- `answer_hash_mismatch`
+- `artifact_spill_failed`
+- `artifact_read_failed`
+- `artifact_error`
+
+Retrieval:
+
+- `result_not_ready`
+- `result_unavailable`
+- `result_too_large_for_inline`
+- `task_unknown`
+
+Each `DelegateError` renders code, message, child-created flag, artifact location when known, preserved evidence, and remediation.
+
+## Hook-contract compatibility gate
+
+The child guard relies on Pi hook behavior proven by `tests/scripted-provider/pi-hook-contract.test.ts`; shipped evidence is byte-identical to `src/core/delegate/hook-contract-evidence.json`.
+
+Required guarantees include context hook ordering, returned context messages reaching the provider, abort blocking the provider request by handing an aborted signal, abort terminating the run, context throw isolation, tool-result replacement before transcript entry, replacement identity preservation, and extension load order.
+
+Pi 0.83 evidence explicitly shows two guarantees are false and therefore not required: context throws do not block provider calls, and abort does not skip the provider call site. The guard is built fail-closed anyway: it aborts and returns a suppressed message set, so the original oversized content is not dispatched even if a provider ignored the aborted signal. Missing/malformed/unsupported evidence fails with `delegate_hook_contract_unsupported`; the guard is not weakened at runtime.

package/docs/subsystems/docs-freshness-gate.md

@@ -0,0 +1,26 @@
+---
+doc_id: subsystems/docs-freshness-gate
+audience: maintainer
+mode: mixed
+review_policy: contract
+stability: stable
+covers_surfaces: []
+covers_sources: []
+---
+# Docs freshness gate
+
+This authored section defines the boundary: documentation facts are extracted from package metadata and TypeScript ASTs, then generated into docs and the manifest. Unsupported syntax fails the gate rather than falling back to regex or stale hand-maintained inventories.
+
+<!-- pi-docs:begin name="docs-freshness-gate" generator="scripts/docs/generate.mjs" -->
+- Canonical package version: `1.0.3`
+- Governed markdown docs: 40
+- Public surfaces extracted: 30
+- Governed production sources: 44
+- Tool contracts extracted: 11
+- Schema IDs extracted: 37
+- Environment variable references extracted: 46
+- Behavioral attestation receipts not passing: 0
+- Receipt store: `docs/attestations.json`
+
+`npm run docs:verify` is read-only: it renders generated files twice in memory and compares them with committed bytes. `npm run docs:generate` is the only docs writer.
+<!-- pi-docs:end name="docs-freshness-gate" -->