specpi 0.16.0 → 0.17.1

package/SECURITY_MODEL.md

@@ -6,6 +6,33 @@ This document describes SpecPi's architecture-level security assumptions, enforc
 
 ### Experimental native delegation
 
+Snapshot creation diagnostics expose only code-owned reasons and an optional one-based
+selected-source position. Known filesystem error codes map to fixed missing/access
+messages; raw paths, messages, causes, stacks, and file contents are not returned.
+Rejected captures start no worker and spend no batch or inference allowance.
+Worker diagnostics identify the failing stage and include only allowlisted source-tool
+or report-validation reasons. Raw provider errors and malformed report text never cross
+the diagnostic boundary. The original tool reason survives SDK cancellation. Output-token
+truncation, invalid JSON and invalid evidence cannot become review sign-off. Workers can
+correct these reports and ordinary tool arguments in the same session, retaining prior
+passages and spending the original inference/context/time budgets. Source changes,
+revocation, unavailable tools and exhausted allowances still abort. The worker prompt
+discloses report constraints; raw provider errors are not automatically retried.
+Source topic words are not private-state boundaries: selected `auth.ts`,
+`credentials.ts`, `sessions/`, and similar application paths are allowed in every
+supported text format. The broker reserves known private namespaces (including
+`.pi`, `.codex`, `.ssh`, cloud credential directories, and SpecPi Chat storage),
+credential-store filenames such as `.env`, `auth.json`, and `credentials.json`,
+and private-key formats. Both lexical and canonical locations of the configured
+`PI_CODING_AGENT_DIR` are excluded; only directory metadata is resolved, never
+private contents. An inaccessible configured boundary rejects snapshot creation.
+These rules prevent accidental selection of known stores, not secrets embedded
+in otherwise ordinary source. The parent remains responsible for selecting
+appropriate material. Selected-file scope, containment, link, text, size, and
+freshness checks apply to every source. Child access limits prevent the reviewer
+from expanding its assignment; sending selected source to the same provider is
+not a new provider-disclosure boundary.
+
 Delegation is a native extension discovered through the ordinary Pi package and SpecPi lifecycle. Start `pi` normally; delegation is enabled by default at the first session start of each Pi process, including TUI, RPC, print and JSON modes, after settings, host and Guard checks. Startup launches no workers or model inference, but Pi-owned authentication/OAuth preparation may occur. The model-facing schema is present only while dispatch is enabled. It adds no launcher, separate host process, service or trust override. Parent Pi retains normal resource discovery, trust decisions and proxy policy. Delegation checks required public SDK capabilities, not exact version identifiers. Missing session/runtime/settings/thinking APIs prevent activation; session construction and every request still enforce the tool, model and resource policy. API presence is not proof of every future SDK behavior or a passing integration receipt. Normal installation's minimum Pi version and 0.84.4 bootstrap pin are separate contracts.
 
 Each worker is an SDK `createAgentSession` instance with in-memory session storage. Pi owns its model/tool loop. A fresh Pi `ModelRuntime` uses standard authentication, environment and `models.json` resolution. Child transport and thinking budgets come from configured global settings; project settings are not loaded. Parent model/thinking are explicit with Pi's supported-level clamping. SpecPi does not extract credentials, copy authentication state or inspect private runtime fields. Preflight rejects runtime-only authentication, selected extension-registered provider overrides, model-specific headers, startup proxy configuration and mismatched safe model descriptors because those routes cannot be faithfully reconstructed. These rejections leave parent configuration unchanged.
@@ -24,15 +51,17 @@ The broker reads only explicitly selected, bounded regular text files under the
 
 Snapshot tool calls check canonical paths, identity and change metadata without rereading and hashing the entire selection. Capture, publication, collect, follow-up and resolve also verify content digests. Metadata-evasive changes are detected at the next digest boundary. Stream events use cheap epoch/model/context identity checks; full root, safe model-descriptor and provider-policy validation still precede requests, tools and accepted results. An in-place change during a dispatched stream may be detected at that next protected boundary.
 
-Quotas cover SDK model invocations, logical deadlines, tool calls/bytes, snapshot bytes and observed responses. Admission occurs before each SDK dispatch. Provider/session retries and automatic compaction are disabled; one changed-input follow-up keeps original allowances and deadlines. Requested output is 8,192 tokens clamped to the model maximum. SDK streaming exposes response content for checks while the child runs, but bytes may already be buffered before an event. There are no hard raw-transport, hidden-provider-attempt, invoice or process-memory caps. Missing usage is explicit and cost is unavailable. Cancellation revokes broker grants and requests SDK abort; slots remain held through SDK-visible stream/result and prompt settlement. That does not prove physical remote execution has ended. A non-cooperative SDK/provider can require ending Pi; late results do not revive a job.
+Quotas cover SDK model invocations, logical deadlines, tool calls/bytes, snapshot bytes and observed responses. Admission occurs before each SDK dispatch. Provider/session retries and automatic compaction are disabled; one changed-input follow-up keeps original allowances and deadlines. Requested output follows Pi's normal provider/model settings without a delegation-specific token cap. Report corrections use ordinary admitted calls in the same session; they are not opaque SDK retries. SDK streaming exposes response content for checks while the child runs, but bytes may already be buffered before an event. There are no hard raw-transport, hidden-provider-attempt, invoice or process-memory caps. Missing usage is explicit and cost is unavailable. Cancellation revokes broker grants and requests SDK abort; slots remain held through SDK-visible stream/result and prompt settlement. That does not prove physical remote execution has ended. A non-cooperative SDK/provider can require ending Pi; late results do not revive a job.
 
 Incremental stream checks count recognized delta bytes and bound event structures, with exact full response checks at content/terminal boundaries. This trusts Pi's parsed event contract; it is not an exact per-event bound for arbitrary inconsistent SDK partials or a peak-memory guarantee. Usage preserves valid fields independently, reports never-supplied fields as null, and counts reporting coverage per field. Unknown SDK/setup/tool errors expose only generic diagnostics; code-owned policy failures retain specific messages. Synchronous and asynchronous teardown failures are contained without freeing unsettled slots.
 
-The same controller and bounded idempotency journal remain in memory for the Pi process lifetime, including `/reload`, session switches and off/on. Successful spending and final-disposition receipts are retained (at most 20 under the fixed ceilings); cancellation and nonfinal assessments have a separate 128-entry oldest-first cache. Failures reserve no keys. Cache churn cannot evict spending receipts, reset quotas or disable cancellation. Limits are two active workers, four batches and 32 SDK invocations per process; two jobs and 8 invocations per batch; four invocations per logical job including follow-up. Invalidation does not reset these counters or release settling work. Completed reports retain their source bindings after the deadline, but child sessions are released at the deadline and later follow-up is rejected. These numeric limits are engineering choices, not empirical optima.
+The same controller and bounded idempotency journal remain in memory for the Pi process lifetime, including `/reload`, session switches and off/on. Successful spending and final-disposition receipts are retained (at most five per admitted batch); cancellation and nonfinal assessments have a separate 128-entry oldest-first cache. Failures reserve no keys. Cache churn cannot evict spending receipts, reset quotas or disable cancellation. Defaults are two active workers, 32 batches and 256 SDK invocations per process; two jobs and 64 invocations per batch; 32 invocations, 96 source tool calls and 512 KiB delivered source JSON per logical job including follow-up. Invalidation does not reset these counters or release settling work. Completed reports retain their source bindings after the deadline, but child sessions are released at the deadline and later follow-up is rejected. These numeric limits are engineering choices, not empirical optima.
+
+Human `/delegate budget <multiplier>` while off saves a whole multiplier from 1 to 64 (default 8). Counts for process batches and job/batch/process model calls, job source tools/output bytes, serialized child context and SDK response bytes scale together. Maximum values are 256 batches and 2,048 model invocations per process, 512 invocations per batch, 256 invocations and 768 source calls/4 MiB source output per job, and 16 MiB serialized child context. The default child-context bound is 2 MiB. SDK response acceptance defaults to 1 MiB and scales to 8 MiB at multiplier 64. Concurrency, timeouts, 256 KiB handoffs, individual tool responses and final-report bounds do not scale. Changes invalidate prior jobs without resetting spent usage; increased limits permit greater cost and memory use. Exhaustion diagnostics are code-owned, rejected source output is not counted as delivered, and exhausted jobs cannot launch a follow-up with a spent allowance.
 
 Logical jobs default to 10 minutes and batches to 20 minutes. Human `/delegate timeout <minutes>` persists a whole-minute value from 1–60 while delegation is off; the batch window is twice the job window. Queue and follow-up time count from admission. SDK request timeouts and adapter abort timers use the remaining job window, with a 60-minute ceiling. Changes revoke old policy bindings, never extend old jobs or reset quotas/settling slots, and are absent from the model-facing schema. The effective time policy is included in Guard fingerprints and packet digests. Longer windows also allow longer in-memory input/child retention; they do not add calls, retries or billing guarantees.
 
-Only the numeric timeout preference is persisted under `<agent-dir>/specpi/delegation/settings.json`; its previous content and SHA-256 are backed up in `settings.json.bak`. The human-selected agent directory is canonicalized once, including platform aliases; owned SpecPi subdirectories and preference files still reject links. Reads reject malformed/nonregular settings and are bounded to 4 KiB; the encoded backup has a separate 32 KiB bound. Saves use exclusive staging and atomic promotion. Invalid settings block activation. This store does not read Pi authentication, settings or sessions. The process loads it once; manual or other-process edits require restart, and concurrent saves are last-writer-wins. As with snapshots, this is a trusted-local-filesystem contract, not protection against hostile filesystem races. User-owned preferences survive uninstall. Requested file/directory modes are 0600/0700; Windows relies on profile ACLs.
+The numeric timeout and optional budget multiplier are persisted under `<agent-dir>/specpi/delegation/settings.json`; its previous content and SHA-256 are backed up in `settings.json.bak`. The human-selected agent directory is canonicalized once, including platform aliases; owned SpecPi subdirectories and preference files still reject links. Reads reject malformed/nonregular settings and are bounded to 4 KiB; the encoded backup has a separate 32 KiB bound. Saves use exclusive staging and atomic promotion. Invalid settings block activation. This store does not read Pi authentication, settings or sessions. The process loads it once; manual or other-process edits require restart, and concurrent saves are last-writer-wins. As with snapshots, this is a trusted-local-filesystem contract, not protection against hostile filesystem races. User-owned preferences survive uninstall. Requested file/directory modes are 0600/0700; Windows relies on profile ACLs.
 
 Shared snapshot text is destroyed once no job can continue; failed attempts retain original expiry cleanup. Packet/job-input references are dropped after owned workers settle. Metadata and digests remain for completed receipt freshness. Starting the next accepted batch retires previous reports; invalidation retires old generations after settlement. Retired batch objects are pruned, leaving only bounded state summaries and idempotency/usage counters. Replay cannot restore their reports, inputs, sessions or allowances. JavaScript strings, provider buffers and values already returned to Pi cannot be securely erased.
 

package/THIRD_PARTY.md

@@ -14,9 +14,9 @@ and produces a capability error on activation, rather than an extension-load fai
 
 When Pi is absent, SpecPi can install the reviewed `@earendil-works/pi-coding-agent@0.84.4` npm package globally after confirmation. The package provides the `pi` executable, is installed with lifecycle scripts disabled, retains its upstream license, and remains external system state after SpecPi uninstall.
 
-The experimental delegation extension uses native discovery and public Pi SDK `createAgentSession`, in-memory sessions and a fresh `ModelRuntime`, with **public SDK capability checks instead of an exact-version allowlist**. Compatible Pi updates can activate without a SpecPi release. Missing APIs are named in the activation error; actual SDK/provider behavior remains subject to runtime checks and regression testing. The installer floor and pinned 0.84.4 bootstrap package are unchanged. Pi supplies the conversation/tool loop, standard configuration, authentication and OAuth. The child receives the parent model and thinking level with Pi clamping; unsupported runtime-only authentication, selected extension-provider overrides and safe descriptor mismatches fail preflight. Children load no ambient extensions, skills, AGENTS files or parent history. Parent hooks, ephemeral settings and session affinity are not inherited. Each SDK invocation is admitted before dispatch, retries and compaction are disabled, and SDK-visible streams are checked without claiming hard raw-transport, hidden-attempt, memory or invoice bounds. SpecPi does not install or vendor another runtime, add a launcher/service, or introduce a direct `pi-agent-core` dependency or additional runtime library. Parent Pi startup, resources and trust remain unchanged.
+The experimental delegation extension uses native discovery and public Pi SDK `createAgentSession`, in-memory sessions and a fresh `ModelRuntime`, with **public SDK capability checks instead of an exact-version allowlist**. Compatible Pi updates can activate without a SpecPi release. Missing APIs are named in the activation error; actual SDK/provider behavior remains subject to runtime checks and regression testing. The installer floor and pinned 0.84.4 bootstrap package are unchanged. Pi supplies the conversation/tool loop, standard configuration, authentication and OAuth. The child receives the parent model and thinking level with Pi clamping; unsupported runtime-only authentication, selected extension-provider overrides and safe descriptor mismatches fail preflight. Children load no ambient extensions, skills, AGENTS files or parent history. Parent hooks, ephemeral settings and session affinity are not inherited. Each SDK invocation is admitted before dispatch. SDK provider retries and compaction are disabled; ordinary tool-argument and report corrections use admitted calls in the same child session. Output length follows Pi's normal provider/model settings without a delegation-specific token cap, and SDK-visible streams are checked without claiming hard raw-transport, hidden-attempt, memory or invoice bounds. SpecPi does not install or vendor another runtime, add a launcher/service, or introduce a direct `pi-agent-core` dependency or additional runtime library. Parent Pi startup, resources and trust remain unchanged.
 
-The [Pi 0.85.0 release](https://github.com/earendil-works/pi/releases/tag/v0.85.0), published 4 September 2026, prompted the additional compatibility review. It does not change the installer pin or imply that every provider/setup has passed. The [compatibility record](docs/delegation/research.md#pi-compatibility-evidence) records completed validation independently of activation. Pi 0.85.1 also passes the isolated native/provider fixtures; its SDK session, agent-session and model-runtime modules match 0.85.0.
+The [Pi 0.85.0 release](https://github.com/earendil-works/pi/releases/tag/v0.85.0), published 4 September 2026, prompted the additional compatibility review. It does not change the installer pin or imply that every provider/setup has passed. Pi 0.85.1 also passes the isolated native/provider fixtures; its SDK session, agent-session and model-runtime modules match 0.85.0. Compatibility evidence is not an activation allowlist or proof of full parent inference parity.
 
 The child uses configured global transport/thinking budgets without loading project settings. Startup proxy configuration and model-specific headers are unsupported and fail preflight; parent configuration stays unchanged. These limits are part of the experimental SDK integration, not claims about what Pi itself supports.
 
@@ -58,12 +58,14 @@ Repository development uses these exact, project-local formatting and linting pa
 - `@typescript-eslint/parser@8.68.0` — MIT
 - `typescript@6.0.3` — Apache-2.0
 
-They are development-only dependencies, are not shipped by the SpecPi installer, and enforce the repository's JavaScript and TypeScript readability rules. TypeScript also runs strict no-emit checking for the browser extension and a bounded semantic-navigation fixture.
+They are development-only dependencies, are not shipped by the SpecPi installer, and enforce the repository's JavaScript and TypeScript readability rules. TypeScript also runs strict no-emit checking for the browser extension.
 
 Browser type checking and registered-tool tests additionally use exact project-local development dependencies: `@earendil-works/pi-coding-agent@0.84.4`, `@earendil-works/pi-ai@0.84.4`, `@earendil-works/pi-tui@0.84.4` (MIT), `typebox@1.3.7` (MIT), `@types/node@22.20.1` (MIT), and `playwright@1.62.1` (Apache-2.0). These reuse the reviewed Pi/runtime versions, do not alter the optional production-peer contract, and are not bundled or installed by SpecPi. Direct development dependencies are pinned; this is not a claim that the development transitive graph is locked. The browser executable test runtime still uses the separately reviewed lockfile. `setup:browser` provisions only `.specpi-test/browser-runtime/`; its explicit `--with-deps` option invokes Playwright OS dependency setup on disposable Linux CI runners. No language-server executable or additional automation framework was added.
 
 The GitHub Pages site vendors the Latin subsets of IBM Plex Sans and IBM Plex Mono. Copyright © 2017 IBM Corp. with Reserved Font Name "Plex". The font files are distributed under the SIL Open Font License 1.1; the required license text is included at `site/fonts/LICENSE.txt`.
 
+The site showcase at `site/media/specpi-showcase.mp4` incorporates “Machina” by Scott Buckley, released under Creative Commons Attribution 4.0 (CC BY 4.0), https://creativecommons.org/licenses/by/4.0/. Source and composer credit: https://www.scottbuckley.com.au/library/machina/ and https://www.scottbuckley.com.au/. The music excerpt is edited, level-adjusted, and faded; its license is separate from SpecPi's MIT license. Credit appears in the film and the player's transcript/credits disclosure. Preserve that attribution with redistribution; YouTube uploads require it in the video description. See `site/media/README.md`.
+
 The npm release workflow installs `npm@11.19.1` as its pinned publishing client. npm is distributed under the Artistic License 2.0 and runs only on the ephemeral GitHub-hosted release runner.
 
 Repository automation uses these official GitHub Actions. General CI and Pages workflows track the listed major versions; the npm publishing workflow pins exact reviewed commit SHAs so the OIDC job does not execute mutable action tags:

package/docs/browser-testing.md

@@ -61,16 +61,8 @@ The shared browser workflow runs for CI and is a prerequisite of Pages deploymen
 
 The existing `local-browser-automation` registry entry and `browser-runtime-smoke` prove their historical rendering/image-comparison contract only. They are not expanded into claims that diagnostics or keyboard behavior have passed that closed validator. Browser diagnostics and interactions in SpecPi 0.13.0 are evidenced by dedicated registered-tool/Chromium tests and CI; no wishlist item is automatically selected or retired and no invented shipped version is entered in the registry.
 
-## Semantic navigation assessment (R6)
+## Semantic navigation decision
 
-**Decision: no new agent-facing semantic tool in this delivery.** Keep project-native compiler/tooling as the default and reassess after concrete larger-refactor friction.
+No agent-facing semantic-navigation tool is implemented. The original feasibility assessment found the existing TypeScript language service adequate for a small alias/reference/diagnostics example; that does not establish product coverage or a productivity improvement. Use project-native compiler/tooling and reassess only after concrete refactor friction.
 
-Run `node --test tests/semantic-navigation.test.mjs`. The existing pinned TypeScript language service resolves an aliased cross-file definition, finds four related symbol references while excluding a shadowed name, and reports diagnostic 2345 after an on-disk argument-type mutation. The fixture creates temporary source files, supplies an explicit language-service host, and disposes it afterward. No language server, plugin, project configuration script, or new executable dependency is loaded. Windows path normalization was necessary when comparing compiler-returned reference paths; the test retains that check.
-
-| Approach | Assessment |
-| --- | --- |
-| Project-native compiler and shell tools | Adequate baseline for this TypeScript fixture and the browser refactor. Text search is easy but cannot distinguish aliases/shadowing; compiler APIs can, at the cost of writing a small explicit host. No measured productivity improvement is claimed. |
-| Narrow TypeScript adapter | Could expose bounded path/line/column results and reuse this compiler if repeated refactor work justifies a maintained tool contract. Not justified by this small fixture alone. |
-| Broad LSP integration | Adds server acquisition/trust, process cleanup, language-specific configuration, and protocol complexity without evidence of a current need. Deferred, not implemented. |
-
-Any later adapter proposal must define supported languages/projects, on-disk versus unsaved buffers, canonical project-root and symlink boundaries, out-of-root declaration references, generated/vendor exclusions, result/time limits, cancellation/subprocess cleanup, and a no-auto-edit/no-auto-install policy. Definitions in dependencies may need an explicit read-only opt-in. Repository plugins/config scripts are executable trust boundaries, not automatically safe navigation inputs.
+A later adapter would need explicit language/project support, on-disk versus unsaved-buffer semantics, path/link and dependency boundaries, bounded results and cancellation, and no automatic edits or server installation. Repository plugins and configuration scripts remain executable trust boundaries.

package/docs/delegation/README.md

@@ -1,307 +1,79 @@
 # Bounded delegation
 
-Status: experimental in SpecPi 0.16.0. Enabled by default at Pi startup.
-The package remains `specpi`; no separate npm package or background service is required.
+Experimental; enabled by default at normal `pi` startup. No measured quality, speed or cost benefit is claimed.
 
-SpecPi keeps one agent responsible for changes and acceptance. This extension adds
-bounded, read-only workers for independent questions. It does not add a second writer,
-an automatic planner, or a permanent team. The [research](research.md) supports testing
-selective delegation; it does not establish that this implementation improves outcomes.
+The parent remains the sole writer and verifies workers' evidence. Use delegation for a substantial independent question or frozen review, not routine lookups, small edits, coupled work or generic second opinions. Workers are real Pi SDK sessions with in-memory storage, selected-source read/search tools, no shell, writes, live web, ambient extensions or parent history.
 
-## Use normal Pi startup
-
-```sh
-pi
-```
-
-The native extension is discovered through the ordinary Pi package and SpecPi
-install/update lifecycle. Existing Pi startup, UI, resources, trust decisions and
-proxy configuration remain Pi-owned. Delegation needs no alternate launcher, extra
-SDK host, separate runtime process or new setup path.
-
-Delegation checks **SDK capabilities, not an exact Pi version list**. New Pi versions
-can activate when the required public session, runtime, settings and thinking APIs are
-available. Missing APIs produce an error naming the unavailable capability; session
-construction and each request still enforce the tool, model and resource policy.
-The [compatibility record](research.md#pi-compatibility-evidence) records tested versions
-separately; API presence does not prove every future SDK behavior. Normal SpecPi installation
-keeps its separately documented host floor and 0.84.4 bootstrap pin.
-Restart Pi after updating SpecPi to load a changed delegation
-runtime version or change its working root. The broker uses the canonical working
-directory captured for this Pi process.
-
-Workers are actual SDK `createAgentSession` instances with in-memory session storage.
-Pi runs their model/tool loop. SpecPi supplies admission, selected-source tools and
-result checks; it does not implement a second conversation loop. Children load no
-ambient extensions, skills, AGENTS files or parent session history.
-
-```mermaid
-flowchart LR
-    parent["Parent Pi agent · sole writer"] -->|bounded question| controller["SpecPi admission and receipts"]
-    controller --> child["Pi AgentSession · memory only"]
-    child -->|admitted SDK invocation| runtime["Pi ModelRuntime"]
-    child -->|selected list/read/search| broker["Snapshot broker"]
-    child -->|claims and evidence| parent
-    parent --> checks["Verification and final decision"]
-```
-
-The child uses a fresh Pi `ModelRuntime` with standard authentication, environment
-and `models.json` resolution. Its settings take transport and thinking budgets from
-Pi's configured global settings; project settings are not loaded. The parent model and
-thinking level are explicit. Pi's public thinking-level clamp determines the effective
-child level, which the adapter verifies. Pi handles authentication
-and OAuth; SpecPi does not copy credentials or inspect private runtime fields.
-Preflight rejects runtime-only authentication, selected extension-registered provider
-overrides, model-specific headers, startup proxy configuration and mismatched safe
-model descriptors because the fresh runtime cannot faithfully reproduce those parent
-routes. Parent configuration is left unchanged; an unsupported route disables delegation.
-
-This is **not full parent inference parity**. Parent request hooks, ephemeral runtime
-settings and session affinity are not automatically transferred. A workflow requiring
-those inherited controls for every request must keep delegation disabled. Receipts
-bind supported model and source descriptors; they cannot certify an unchanged remote
-service or every configuration change behind a stable provider identity.
-
-## Control delegation
-
-The first session start of each Pi process enables delegation after settings, host and
-Guard checks, in TUI, RPC, print and JSON modes. Startup does not launch workers or
-model inference. Preflight may perform Pi-owned authentication/OAuth preparation.
-Use one agent for small or sequential work; delegate only a justified independent question.
-
-In an interactive session:
+## Controls
 
 ```text
 /delegate status
 /delegate limits
 /delegate cancel <batchId>
 /delegate off
+/delegate on
 ```
 
-In Pi's terminal UI, a small panel above the editor shows each worker's ID, role,
-state, elapsed time, model calls and source-tool calls. `1/2 workers` means one of
-two slots is occupied; it is not a completion percentage. Model calls are SDK
-invocations, not tokens. Completed jobs remain visible as **ready for review** until
-the parent resolves them. A cancelled worker shows **stopping** while its SDK request
-still occupies a slot. The panel disappears when no work needs attention.
+Startup enables dispatch only after host, settings and Guard checks; it launches no workers. Preflight may perform Pi-owned authentication/OAuth preparation. Off and safety revocations survive reload/session switches; restarting Pi restores the on default. While off, the tool is absent from model requests.
 
-Tool output uses compact summaries. Expand it with Pi's normal tool-output shortcut
-to read answers, findings, evidence references and missing context. These remain
-advisory worker reports. `/delegate status` shows the selected model, process budgets
-and batch IDs; use an ID with `/delegate cancel <batchId>` to cancel that batch.
+The TUI panel shows worker state, elapsed time and call counts. **Ready for review** requires a parent disposition; **stopping** still occupies a slot. RPC/print modes return structured results without widgets. Expand tool output for findings and evidence.
 
-The panel follows Pi's theme and adapts to terminal width. It refreshes at most once
-per second between lifecycle changes, stops its timer when workers settle and is
-removed on shutdown or reload. It reads counters without checking files or providers;
-it does not retain or display live child reasoning. RPC and print mode keep the same
-structured tool responses and do not mount terminal widgets. The UI uses Pi's public
-[widget and tool-rendering APIs](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/extensions.md).
+Model/thinking changes revoke old results and preflight the new route. Unsupported routes pause dispatch; compatible selections resume it unless explicitly off. Guard, session, branch and task/scope changes revoke the current generation. Ordinary conversation advancement does not. Reload/off/on never reset spent process quotas or release unsettled requests. Restart Pi to load changed runtime code or a different working root.
 
-The startup default enables the documented experimental calls/time envelope. Use
-`/delegate off` to revoke it and `/delegate on` to explicitly re-enable it. Off and
-safety revocations survive `/reload` and session switches; restarting Pi reapplies the
-on default. No on/off preference is written to disk. There is no model-call
-permission toggle in the model-facing tool. `limits` is read-only; prompts cannot
-change timeouts or raise other ceilings. Turning delegation off, changing guard policy, switching
-sessions or models, navigating branches, and changing task/scope bindings revoke the
-current generation. Off/on, `/reload` and session switches do not reset the Pi process's
-counters or free requests that are still settling. The same in-memory controller remains
-in use; restart Pi to load changed runtime code. Normal conversation leaf advancement
-does not invalidate workers.
+Command Guard is optional. Active Strict Guard binds approval to the exact call and effective policy; locked, unready or ambiguous installed Guard blocks activation. Workers remain restricted independently of Guard. Neither worker output nor parent acceptance grants human approval.
 
-Once enabled, delegation follows changes to the parent's provider, model and thinking
-level without another `/delegate on`. Each change revokes old worker results, retains
-unsettled slots and consumed quotas, and checks the new host before resuming dispatch.
-Old jobs are not retried. An unsupported selection pauses delegation with a reason;
-selecting a compatible model resumes it automatically. `/delegate off` remains off
-through later model changes. Guard, task/scope and session lifecycle changes still
-revoke activation. Status separates the default or human `requested` choice from `enabled`
-dispatch, with `updating` and `pauseReason` for model setup.
+## Persistent limits
 
-While delegation is off, its tool is removed from the parent's active tool list.
-The command remains available, but the delegation tool schema is included in model
-requests only after activation. Other active tools are preserved.
-
-Command Guard is optional: delegation can run when Guard is absent or Off. When
-active, Command Guard continues to intercept the parent `delegate` tool. Strict mode presents
-the effective capability envelope and binds approval to its policy fingerprint and
-the exact call. A locked, unready or ambiguous installed Guard still blocks activation;
-the error identifies that state. `/delegate status` reports the observed Guard state.
-Worker tool restrictions and resource limits are enforced independently of Guard. A worker result
-cannot authorize a write, a commit, a deployment, or an improvement.
-
-## Configure the timeout
-
-The default is **10 minutes per logical job** (previously 2 minutes). In Pi:
+Change settings only while delegation is off:
 
 ```text
 /delegate off
 /delegate timeout 15
+/delegate budget 16
 /delegate on
 ```
 
-`/delegate timeout` shows the current value; `/delegate timeout reset` saves the
-10-minute default. Tab completion suggests common values. Use whole minutes from
-**1 to 60**; there is no unlimited setting. The batch deadline is twice the job
-timeout (20 minutes by default), so it does not truncate the configured job window.
-Both deadlines start at batch admission and include queue and follow-up time; a
-follow-up never gets a fresh timeout. Provider requests use the remaining job window,
-not a separate two-minute cap. Provider-side limits may still end requests sooner.
-
-Changes require delegation to be off, including when model setup is pending or paused.
-They apply to this process and future Pi starts; they cannot extend old jobs, reset
-call quotas or free requests still settling. `/delegate on`, `status`, `limits` and
-Strict Guard policy summaries display the effective timeout. Only the human command
-can configure it; the model-facing tool has no timeout-setting operation.
-
-The preference is stored in `<agent-dir>/specpi/delegation/settings.json`, where
-`<agent-dir>` is `PI_CODING_AGENT_DIR` or `~/.pi/agent`. It contains only
-`{"schema":1,"timeoutMinutes":15}`. Saves atomically replace this file and keep the
-previous contents plus their SHA-256 in `settings.json.bak`. No Pi settings,
-authentication, sessions or history are read or changed by this preference store.
-The human-selected agent directory is resolved once, supporting platform path aliases.
-Preference files and SpecPi subdirectories must not be links. Malformed, oversized or
-unreadable settings block activation rather than silently using another timeout. Repair them manually
-and restart Pi. Manual edits and changes from another Pi process take effect on
-restart; `/reload` preserves the current process policy and counters. The preference
-survives uninstall as user-owned configuration.
-
-## Admit a specific purpose
-
-| Mode     | Required structure                                                                                                                    | Context and tools                                                                         |
-| -------- | ------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
-| `review` | A frozen artifact, original requirements, relevant constraints and actual validation facts. The parent checks findings before acting. | Nonempty inline context or selected files; selected-source tools when files are supplied. |
-| `scout`  | A bounded evidence question with an independently checkable answer and a reason to separate the analysis.                             | At least one selected file; list/read/literal-search only, with no live web access.       |
-
-The packet declares one benefit: `independent_review` for review jobs, or
-`parallel_analysis` / `context_isolation` for scout jobs. It includes a nonempty `why`.
-`parallel_analysis` also requires useful `parentWork`; this may be empty for the other
-benefits. A final review can be useful even when the parent waits. The controller checks
-this structure, not whether the claimed benefit will materialize. Duplicate questions
-after trimming and case normalization are rejected; distinct text is not proof of
-independent work.
-
-Each job names its assigned global requirement IDs and receives only those requirements,
-plus the fixed decisions and non-goals. Transfer original constraints and evidence,
-not the parent's reasoning or verdict. Do not delegate routine lookups, small understood
-edits, coupled mutable work, generic second opinions or repeated role-based answers.
-Use parallel parent tool calls when retrieval alone answers the question.
-
-Workers have no shell, writes, arbitrary plugin tools or recursive delegation.
-The parent obtains and selects source material. Model routing, automatic retries,
-live-web access, monetary admission and automatic policy tuning remain unimplemented.
-
-`/task` remains optional. Changes to an active task contract invalidate delegation,
-but the parent is still responsible for faithfully transferring the task into the packet.
-
-Use `delegate run`, continue useful parent work, then `collect`. Collection can wait
-up to 30 seconds without another model request. Do not poll on a fixed schedule.
-Check the referenced evidence and `resolve` each report, including per-finding
-dispositions. One changed-input `follow_up` is available under the original deadline
-and counters. [Protocol and executable examples](protocol.md) define the exact fields.
+- `timeout`: whole minutes 1–60, default 10; `timeout reset` restores it. Batch deadline is twice the job timeout. Both begin at admission, including queue/follow-up time.
+- `budget`: multiplier 1–64, default 8; `budget reset` restores it. Scales call/byte/context allowances, not concurrency, deadlines or per-response limits. Higher budgets can increase cost.
+- Commands without values show current settings. Models cannot change them. Changes preserve consumed process counters and cannot extend existing jobs.
 
-## Enforced resource envelope
+Preferences live in `<agent-dir>/specpi/delegation/settings.json`, with an atomic backup and checksum; `<agent-dir>` is `PI_CODING_AGENT_DIR` or `~/.pi/agent`. They survive uninstall. Linked, malformed, oversized or unreadable preferences block activation. Repair manually and restart; external edits are loaded on restart, not reload. Pi credentials/settings/history are not modified.
 
-| Resource                  | Ceiling                                                                      |
-| ------------------------- | ---------------------------------------------------------------------------- |
-| Active worker requests    | 2 per Pi process, including cancelled requests still settling                |
-| Batches / jobs            | 4 batches per Pi process; one unresolved batch; 2 jobs per batch             |
-| SDK model invocations     | 32 per Pi process, 8 per batch; 4 per logical job including follow-up        |
-| Follow-ups / retries      | 1 changed-input follow-up per job; provider and session retries disabled     |
-| Time                      | 10 minutes per job by default (human configurable 1–60); batch twice that; queue/follow-up included |
-| Packet / child context    | 256 KiB, checked before dispatch                                             |
-| Selected sources          | 200 files and 8 MiB per batch                                                |
-| Tools                     | 12 calls and 64 KiB total returned JSON per logical job                      |
-| Tool response             | Bounded reads/search; 16 KiB per snapshot read/search response               |
-| Final report              | 16 KiB; 8 findings; coverage for each assigned requirement                   |
-| Requested provider output | 8,192 tokens, clamped to the model maximum                                   |
-| SDK-visible response      | 256 KiB acceptance limit on observed response content                        |
+Default envelope (`/delegate limits` reports the effective policy):
 
-These are conservative experiment limits, not empirically optimal values. Each SDK
-invocation is admitted before dispatch. Automatic provider/session retries and
-compaction are disabled, so they cannot silently create another SDK request.
-Pi authentication preflight occurs before the model-invocation counter; these quotas
-do not count or bound Pi's authentication/OAuth preparation.
+| Resource | Ceiling |
+| --- | --- |
+| Concurrent requests | 2, including cancelled requests still settling |
+| Batches | 32/process; one unresolved batch; 2 jobs/batch |
+| SDK model calls | 256/process, 64/batch, 32/job including follow-up |
+| Follow-up | One changed-input attempt, original budgets/deadline |
+| Handoff / child context | 256 KiB / 2 MiB |
+| Selected sources | 200 files, 8 MiB/batch |
+| Source tools | 96 calls, 512 KiB returned JSON/job; 16 KiB/read or search |
+| Final report | 16 KiB, 8 findings, coverage of every assigned requirement |
+| SDK-visible response | 1 MiB acceptance limit |
 
-The native SDK stream is observed while the child runs. Its response checks are not
-hard bounds on raw transport, hidden provider attempts, billing or process memory.
-Bytes may already be buffered before an SDK event becomes visible. Stream checks count
-recognized deltas incrementally; full response validation occurs at content/terminal
-boundaries, before tool execution and before publication. This relies on Pi's parsed
-stream contract, not arbitrary inconsistent partial objects. Cheap lease checks run
-per event; full root, model and provider-policy checks run at protected boundaries.
-The parsed stream allows at most 64 content blocks, 512 structural nodes per partial,
-65,536 events and 130 non-delta boundaries per invocation. These are implementation
-ceilings, not empirically optimal values.
-Cost is unavailable; available token fields are retained even when others are missing.
-Never-reported fields are `null`, and per-field `usageReportedCalls` distinguishes
-partial totals from complete accounting. This version cannot satisfy a policy
-requiring those unsupported guarantees.
+Provider/session retries and compaction are disabled. Correctable source arguments and malformed reports can consume further calls within the same job. A failed attempt is not a review. Exhaustion, revocation and source changes terminate it. These are SDK-visible limits, not guarantees about raw transport, memory, remote attempts or billing. Cost is unavailable; missing token fields are `null` and receipts identify partial usage.
 
-Cancellation revokes broker access and requests SDK abort. Slots remain held through
-SDK-visible stream/result and prompt settlement; that does not prove physical remote
-execution has ended. Late content is discarded. A non-cooperative SDK/provider can
-require ending Pi; a timeout does not launch a replacement behind its back. Completed
-reports keep their original source bindings after the deadline, but child sessions are
-released at the deadline and later follow-up is rejected.
+## Workflow and evidence
 
-## Evidence and retention
+1. `run`: supply requirements, decisions, non-goals and distinct jobs. `review` needs frozen inline context or files; `scout` needs selected files. Explain the independent-review, parallel-analysis or context-isolation benefit; parallel work also names useful parent work.
+2. `collect`: wait up to 30 seconds for advisory reports; avoid fixed polling.
+3. Verify source citations and findings against the original requirements.
+4. `resolve`: record acceptance/discard/check-needed and each finding's disposition. One changed-input `follow_up` shares the original budget and deadline.
 
-Snapshots contain only exact selected regular text files under the fixed canonical
-working root of the Pi process. The broker rejects traversal, symlinks/junctions,
-hardlinks, binary content, private path
-names, unknown source IDs, and oversized reads. Each worker can search only its own
-selection. Capture verifies content digests. Each tool call checks canonical paths,
-file identity and change metadata against the immutable capture, without rereading
-all selected bytes. Publication, collection, follow-up and disposition also recheck
-content digests. Changed source bindings require a fresh batch. A content change that
-evades filesystem metadata is detected at the next digest check, not by each tool call.
+See [protocol.md](protocol.md) for exact request and receipt fields.
 
-This is a trusted-local-filesystem contract, not an operating-system sandbox or an
-atomic filesystem snapshot. Filename restrictions cannot detect secrets embedded in
-an ordinary source file. The parent must select appropriate material for the configured
-model provider. Trusted Pi extensions remain privileged in the shared process despite
-being absent from the child's resource loader. Only the submitted packet is inherited
-automatically, not the parent transcript.
+Only exact regular text files under the startup working root are selectable. Traversal, links/hardlinks, binary/oversized files, private runtime storage and credential stores are rejected. Ordinary authentication/session *source code* names are allowed. Filenames cannot prove absence of secrets: the parent must select material appropriate for the provider. Workers see only their own selected snapshot. Paths/identity/change metadata are checked during tools; content digests are rechecked at publication, collection, follow-up and resolution. Changed bindings require a fresh batch.
 
-Each report separates worker claims from a host receipt: job/attempt identity, packet
-digest, generation, result revision, route, state, counters and usage completeness.
-Source references are validated for identity and line range; their truth is still a
-verification question for the parent. `accept` records a parent assessment, not human
-approval or verified task completion.
+Selection errors identify a safe reason and source position, without raw paths/errors; no worker starts or inference allowance is spent. Fix the cause, never rename or copy restricted material to evade policy. Source references are checked for identity/range, not truth. Parent acceptance is not independent proof or task completion.
 
-Child conversations use in-memory sessions. A final disposition, cancellation, exhausted
-follow-up or original deadline releases the child; active SDK work retains its slot until
-settlement. Teardown failures do not escape into Pi's event loop. Shared snapshot text
-is destroyed once no job can continue, including failed jobs at their original deadline.
-Packet and job-input references are dropped when owned workers settle. Source metadata
-and digests still validate completed reports after text is destroyed. Starting the next
-accepted batch retires the previous batch's reports; invalidation retires old generations
-after their workers settle. Retired batches cannot be collected or followed up.
-Only bounded state summaries, quota counters and the idempotency journal remain for
-the Pi process lifetime, including `/reload` and session switches. They cannot recreate
-retired work. SDK setup errors are replaced with generic diagnostics before reaching
-status, command notices or model-facing errors; code-owned policy errors stay specific.
-There is no child session database, raw metrics log,
-credential copy, automatic resume, or secure memory-erasure claim. Normal Pi parent
-tool results may be retained in its ordinary session. Turning delegation off does not
-remove results already retained by Pi; review the session before sharing it.
+Cancellation revokes access and requests SDK abort. Slots remain held until SDK-visible settlement; this cannot prove remote execution ended. Late content is discarded. Non-cooperative providers may require ending Pi. Sessions are released on final disposition, cancellation, exhausted follow-up or deadline; settled text/packets are dropped when no job can continue. Completed reports retain source bindings; a new accepted batch retires previous reports. Only bounded summaries, counters and idempotency records remain for the process lifetime. No child database, raw metrics log, automatic resume or secure-erasure guarantee exists. Parent tool results may remain in Pi history even after delegation is off.
 
-## Implementation and evaluation
+## Host limitations
 
-The modules under `extensions/delegation/` integrate Pi AgentSession with admission,
-snapshot tools and closed result validation. There are no additional runtime dependencies
-or separate host process. Compatibility requires verification against the supported
-Pi SDK and ordinary package discovery, not merely a passing mock provider.
+Activation checks required public SDK capabilities, not an exact version allowlist. The installer retains its separate Pi 0.84.4 bootstrap pin. Restart after updating the runtime.
 
-The evaluation plan separates deterministic runtime/security fixtures from comparative
-task outcomes. Use isolated state and synthetic providers for contract tests; live
-inference needs separate authorization. Such fixtures do not establish parity with
-the parent's full inference pipeline or every production provider.
+Children use fresh Pi `ModelRuntime` instances with standard authentication/environment/models resolution and global transport/thinking settings. Project settings are not loaded. Parent model/thinking are explicit and checked through Pi's public APIs. Runtime-only authentication, selected extension-provider overrides, model headers, startup proxy configuration and mismatched model descriptors are rejected rather than silently approximated.
 
-The [evaluation plan](evaluation.md) compares selective delegation with strong single
-agents, serial workflows and always-delegate baselines using matched resource budgets.
-No production quality, speed or cost improvement is claimed until those experiments run.
-The [original design](design.md) and [target protocol](design-protocol.md) preserve the
-broader proposal and its currently unimplemented proof obligations. The implemented
-[calls/time protocol](protocol.md) is the source of truth for this release's behavior.
+Parent hooks, ephemeral settings and session affinity are **not inherited**. Keep delegation off if they are required on every request. Stable provider identity cannot certify an unchanged remote service. Trusted extensions still share Pi's privileged process; this is a trusted-local-filesystem contract, not an OS sandbox. See [SECURITY_MODEL.md](../../SECURITY_MODEL.md) for the authoritative boundaries and [THIRD_PARTY.md](../../THIRD_PARTY.md) for dependency compatibility.

package/docs/delegation/protocol.md

@@ -1,8 +1,7 @@
 # Delegation protocol: bounded-pi-sessions-v1
 
 This is the implemented in-process API. It has no HTTP listener, daemon, child process,
-or child session store. The broader [target protocol](design-protocol.md) remains a
-proposal; its stronger transport/attempt/cost gates are not supplied by this version.
+or child session store.
 
 The extension loads through normal `pi` package discovery and enables delegation at
 the first session start of each Pi process, including noninteractive modes. Startup
@@ -172,9 +171,18 @@ job selection and valid line ranges. `p1` denotes the submitted inline context;
 does not denote the parent transcript or prove repository behavior. `observed` requires
 at least one reference. At most eight findings and 16 KiB are retained.
 
-Malformed reports fail the attempt. There is no automatic retry. Provider exceptions
-are reduced to a generic failure message because raw errors may contain sensitive URLs
-or content. Missing usage is explicit; failed calls still consume invocation allowance.
+Malformed reports receive a correction prompt in the same child session. Previously
+read passages remain available; each correction must pass the normal inference admission
+and context/deadline checks. Ordinary selected-source argument errors return feedback
+and count their delivered JSON toward the tool-byte allowance. SDK argument-validation
+errors can also be corrected; source changes, revocation and quota exhaustion still abort.
+Provider requests are not automatically retried. Diagnostics distinguish
+source-tool failures, provider requests, stream/context/response bounds, output-token
+truncation, empty reports, JSON parsing, and schema/evidence validation. Only fixed stage
+messages and allowlisted validation reasons are returned; raw provider errors and rejected
+report text may contain sensitive URLs or content and are withheld. The original tool
+diagnostic survives SDK cancellation. Missing usage is explicit; failed calls still
+consume invocation allowance.
 
 ## Follow up and resolve
 
@@ -223,7 +231,8 @@ automatic tool execution, verified completion, or wishlist authorization.
 
 All mutations require `requestId`. Successful runs, follow-ups and final dispositions
 retain their replay receipts for the process lifetime; the fixed batch/job ceilings
-bound these to at most 20 entries. Replaying a retained request returns its stored
+bound these to at most five entries per admitted batch (160 at the default budget;
+1,280 at the maximum). Replaying a retained request returns its stored
 response without another request or transition. Reusing a retained ID with a different
 payload fails. Failed requests do not reserve IDs and may be corrected or retried.
 Successful cancellation and `needs_check` responses use a separate 128-entry oldest-first
@@ -245,10 +254,16 @@ SDK-visible stream/result and prompt settlement. Old payloads are discarded. Nei
 terminal receipt delivery nor SDK settlement proves physical remote execution has ended.
 
 The same in-memory controller survives `/reload` and session switches within the Pi
-process. Its ceilings are two active workers, four batches and 32 SDK model invocations
-per process, with two jobs and 8 invocations per batch and four invocations per logical
-job including one follow-up. Requested output is 8,192 tokens clamped to the model
-maximum. These are experiment limits, not research-derived optimal values.
+process. Defaults are two active workers, 32 batches and 256 SDK model invocations
+per process, with two jobs and 64 invocations per batch and 32 invocations per logical
+job including one follow-up. Source reading allows 96 calls and 512 KiB delivered
+JSON per job. Human `/delegate budget <multiplier>` (1–64, default 8) while off scales
+batch/model/tool counts, source-output bytes, serialized child context and SDK response bytes; it is
+saved across restarts and never resets spent counters or extends old jobs. Exhausted
+jobs reject follow-up admission rather than opening a child with no usable allowance.
+Requested output uses Pi's normal provider/model settings (`outputTokens: null`).
+SDK response acceptance defaults to 1 MiB and scales to 8 MiB at multiplier 64.
+These are experiment limits, not research-derived optimal values.
 Human off/on, task changes,
 branch navigation, model selection, guard changes and reloads revoke old generations;
 they do not create a new resource allowance. Normal parent turns do not revoke a job.