specpi 0.16.0 → 0.17.0

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## 0.17.0 - 2026-09-06
+
+- Let delegation workers correct ordinary source-tool arguments and malformed/truncated reports in the same child session, preserving previously read passages and spending the original budgets. Keep source changes, revocations, unavailable tools, and exhausted budgets terminal. Remove the delegation-specific 8,192-token cap in favor of Pi's provider/model settings; scale SDK response acceptance with `/delegate budget` (1 MiB by default).
+- Replace generic delegation worker failures with safe diagnostics for source tools, provider requests, stream/context/response limits, output-token truncation, and final JSON/schema/evidence validation. Preserve the original tool failure through SDK cancellation, disclose report constraints in the worker prompt, and cover low-usage failures with controller and native Pi regressions.
+- Raise default delegation budgets to 96 source calls/512 KiB and 32 model turns per job, with 32 batches/256 model turns per Pi process. Add human-only, persisted `/delegate budget <multiplier>` (1–64, default 8), scaling counts and context together while preserving spent usage, deadlines, and concurrency. Keep handoff and response sizes independently bounded.
+- Count only delivered source JSON, report the specific exhausted allowance, and reject spent-budget follow-ups before starting a child. Tell workers their remaining allowance and verify substantial reading plus passage-preserving follow-up with offline regressions.
+- Preserve safe delegation snapshot rejection reasons and identify the selected-source position so failed reviews are diagnosable in SpecPi Chat and terminal Pi. Redact raw filesystem errors and verify that rejected snapshots start no worker or inference.
+- Replace delegation's private-topic keyword filter with known private namespaces and credential-store formats. Allow ordinary authentication, credential, session, and history source files/directories in all supported text formats, including `src/lib/security/credential-url.ts` and `credentials.ts`. Protect configured Pi storage and its canonical aliases; retain selected-file scope, containment, link, text, size, and freshness checks.
+
 ## 0.16.0 - 2026-09-05
 
 - Enable experimental read-only delegation by default at the first session start of each Pi process, including TUI, RPC, print and JSON modes. Startup preflights the host without launching workers or model inference; selective review/scout admission, Guard checks, source restrictions and resource ceilings remain unchanged.

package/README.md

@@ -5,237 +5,65 @@
 <h1 align="center">SpecPi</h1>
 
 <p align="center">
-  A local, human-directed improvement harness for the
-  <a href="https://pi.dev/">Pi coding agent</a>.
+  A small toolkit for the <a href="https://pi.dev/">Pi coding agent</a>.
 </p>
 
 <p align="center">
-  <a href="#install"><strong>Install</strong></a>
-  · <a href="#included-capabilities">Capabilities</a>
-  · <a href="#improvement-loop">Improvement loop</a>
+  <a href="#install">Install</a>
   · <a href="https://tannermidd.github.io/SpecPi/">Website</a>
-  · <a href="https://tannermidd.github.io/SpecPi/wiki/">Wiki</a>
-  · <a href="SECURITY.md">Security</a>
+  · <a href="https://tannermidd.github.io/SpecPi/wiki/">Documentation</a>
 </p>
 
-## Purpose
+SpecPi extends Pi with chat, review tools, and focused delegation. Its principles are simple: you choose the improvements, changes stay small and reversible, improvement records stay local, and checks matter more than an agent's claims.
 
-SpecPi adds task contracts, workflow controls, and a local improvement loop to Pi. It records recurring capability gaps and presents qualified items for human review. Selecting one exact item with `/harness-improvement` authorizes a bounded change; repository checks and capability-specific validators must pass before it can retire.
-
-Collection is disabled until explicitly enabled. Reports are sanitized, bounded, deduplicated by task, and never uploaded. Later evidence can reopen an item for review, but never restarts implementation automatically.
-
-Version `0.16.0` enables bounded read-only delegation by default at Pi startup. One agent still owns edits and verification; worker use remains selective. SpecPi Chat, browser checks, and the human-selected improvement workflow remain available. See the [release notes](CHANGELOG.md) for the change list.
-
-## SpecPi Chat for VS Code
-
-The `vscode/` source contains **SpecPi Chat 0.3.2**, a separately packaged native sidebar with streamed replies, tool results, file and image attachments, model/thinking controls, Pi approvals, and searchable workspace conversation history. Rename or archive chats, switch between independent live conversations, branch or edit an earlier prompt, search and export visible messages, inspect usage, and review changes through VS Code's native diff tools. Switching chats preserves background work, approvals, drafts, and attachments. Connected conversations share workspace files; use separate worktrees for isolated writers. Opening the sidebar does not start Pi.
+<details>
+<summary>Watch the showcase · 51 seconds</summary>
 
-From a repository checkout, build a local VSIX with `npm --prefix vscode run package`, then install `.specpi-test/vscode/specpi-chat-0.3.2.vsix` through **Extensions: Install from VSIX…**. See the [extension guide](https://github.com/TannerMidd/SpecPi/blob/main/vscode/README.md) for prerequisites, image/provider limits, commands, privacy, and testing. Pi owns provider authentication and tool execution. Stop and Disconnect affect the selected conversation only; branching does not undo code changes. The extension is separate from the SpecPi npm package and has not been published to a marketplace.
+<p>
+  <a href="https://tannermidd.github.io/SpecPi/#showcase">
+    <img src="https://tannermidd.github.io/SpecPi/media/showcase-poster.jpg" width="560" alt="Play the SpecPi showcase">
+  </a>
+</p>
 
-## Selective delegation
+</details>
 
-One agent owns edits and verifies results. Experimental delegation adds up to two read-only Pi workers: `review` checks a frozen artifact; `scout` answers a focused question using selected sources. Workers cannot write, run shell commands, browse the web, or delegate further.
+## What it adds
 
-Delegation is **on by default at Pi startup**, subject to compatibility, settings, and Guard checks. Startup does not launch workers or model inference. Use `/delegate status` to inspect work and limits, `/delegate off` to revoke it, and `/delegate on` to re-enable it. Off and safety revocations survive reloads and session switches; restarting Pi reapplies the on default. Research informed the design; SpecPi quality, speed, and cost gains remain unmeasured.
+- **Focused delegation.** One agent makes changes. Up to two read-only subagents help investigate and review. [Research and design](https://tannermidd.github.io/SpecPi/single-agent/)
+- **Review as you work.** Track changed files, inspect diffs, check pages in a browser, and review risky commands.
+- **Improvements you choose.** Record recurring problems, select one with `/harness-improvement`, and test the change before calling it done.
 
-See [setup and limits](docs/delegation/README.md) or [how the research shaped the architecture](https://tannermidd.github.io/SpecPi/single-agent/).
+Problem collection is off by default. Its records stay on your machine. Pi connects to your chosen model provider.
 
 ## Install
 
-Requires **Node.js 22.19+**, **npm**, **Git**, and **Pi 0.84.4+**. If Pi is absent, the confirmed install adds the reviewed pinned package.
+Requires **Node.js 22.19+**, **npm**, and **Git**. SpecPi needs **Pi 0.84.4+**; the installer can add it if missing.
 
-Install the CLI, inspect its non-mutating plan, and confirm the managed installation:
-
-```bash
+```sh
 npm install --global specpi@latest
 specpi plan
 specpi install
 specpi doctor
 ```
 
-`plan` does not mutate the system. Install, update, and uninstall require confirmation unless `--yes` is supplied. Restart Pi after installation or updating SpecPi to load the delegation runtime.
-
-<details>
-<summary><strong>Pin a release or install from audited source</strong></summary>
-
-Pin the reusable CLI when installing a reviewed release, or inspect its plan without retaining a global CLI installation:
-
-```bash
-npm install --global specpi@0.16.0
-npx --package specpi@0.16.0 specpi plan
-```
-
-For a source-audited installation, clone the exact release:
-
-```bash
-git clone --branch v0.16.0 --depth 1 https://github.com/TannerMidd/SpecPi.git
-cd SpecPi
-./specpi plan
-./specpi install
-./specpi doctor
-```
-
-On Windows source checkouts, use `.\specpi.cmd` in place of `./specpi`. The npm installation provides the `specpi` command on every supported platform.
-
-</details>
-
-<details>
-<summary><strong>Update or uninstall</strong></summary>
-
-Update the npm CLI and its managed installation as two explicit steps:
-
-```bash
-npm install --global specpi@latest
-specpi update
-specpi doctor
-```
-
-Uninstall managed SpecPi resources before removing the CLI. Private wishlist, journal, experiment, and patch state remains local unless explicitly removed:
-
-```bash
-specpi uninstall
-npm uninstall --global specpi
-```
-
-</details>
-
-Direct `pi install npm:specpi` loads extensions, skills, and themes only. It does not run the full installer or provide managed instructions, browser runtime dependencies, supporting Pi packages, optional tools, shell integration, backups, or ownership records.
-
-## Included capabilities
-
-### Define and review work
-
-| Interface     | Purpose                                                                                                                                         |
-| ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
-| `/task`       | Record the objective, fixed requirements, acceptance checks, expected paths, hypothesis, rollback, and non-goals on the current session branch. |
-| `/scope`      | Declare expected paths and report unacknowledged drift.                                                                                         |
-| `/files`      | Browse source, rendered Markdown, Git diffs, and bounded review comments.                                                                       |
-| `/experiment` | Create detached worktrees with keep, binary patch export, and confirmed discard outcomes.                                                       |
-| `/challenge`  | Review readiness through structured evidence, gaps, contradictions, and residual risk.                                                          |
-
-### Improve from evidence
-
-| Interface              | Purpose                                                                              |
-| ---------------------- | ------------------------------------------------------------------------------------ |
-| `/wishlist`            | Store and curate privacy-minimized local capability-gap reports.                     |
-| `/harness-improvement` | Select one qualified or review-needed item and authorize its bounded implementation. |
-
-### Work inside Pi
+Preview the changes, confirm the install, then check the setup. Restart Pi when finished.
 
-| Interface           | Purpose                                                                                                                               |
-| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
-| `/spec`             | Replace normal chrome with a technical run panel, seal live reasoning, hold streaming prose until complete, and keep tools collapsed. |
-| `/guard`            | Deny confirmed host-wide destructive calls and request approval for bounded risk classes.                                             |
-| Browser tools       | Inspect isolated Chromium, diagnose errors, exercise keyboard/select/wait flows, and capture screenshots.                              |
-| `specpi-spec` theme | Bring blueprint blue, technical greys, layered surfaces, and restrained semantic states into Pi.                                      |
-| `specpi` CLI        | Plan, install, update, verify, and uninstall managed state with backups and rollback.                                                 |
+To pin this release, use `npm install --global specpi@0.17.0`.
 
-`specpi-spec` is the default Pi theme, carrying the site's specification design through message surfaces, tools, Markdown, diffs, syntax highlighting, search, and the full thinking-level scale. **Existing valid theme preferences survive installation and updates.** The original `tea-house` theme remains bundled and selectable from `/settings`.
+Delegation is enabled at startup. Use `/delegate off` to turn it off.
 
-Capability registry entries include closed offline validators. Completion, `npm run check`, and `specpi doctor` run those validators.
+[Setup, updates & removal](https://tannermidd.github.io/SpecPi/wiki/#getting-started) · [Delegation settings](docs/delegation/README.md)
 
-## How SpecPi fits
-
-SpecPi runs inside Pi through extensions, skills, settings, and themes. Pi supplies the agent runtime, tools, sessions, and model connections; SpecPi adds the working agreement, workflow controls, and local improvement loop.
-
-```mermaid
-flowchart TB
-    human["You · goals, selections, review"]
-    subgraph session["Pi session"]
-        specpi["SpecPi · contracts, guard, review, improvement"]
-        pi["Pi · agent loop, tools, sessions"]
-        specpi <-->|extension hooks| pi
-    end
-    human --> specpi
-    human --> pi
-    pi -->|model requests| provider["Selected model provider"]
-    pi -->|tools| project["Project files and commands"]
-    specpi -->|local records| evidence["Task cards, wishlist, verification receipts"]
-```
-
-## Work ownership
-
-### Task contracts and handoff
-
-Use `/task set` when a shared contract would improve continuity. Its card supplies fixed requirement IDs to `/challenge` and can seed an experiment's hypothesis and acceptance checks. `/spec` shows the active task. `/scope task` explicitly imports the card's expected paths; recording a card alone never widens scope. Human edits create a new card revision and invalidate a review of the earlier card.
-
-Use `/task clear` before recording an unrelated task. Within a session, repeated reports for the same capability share the card's task ID across agent runs and card revisions. Without a card, report grouping remains per run.
-
-`/task handoff` displays a review packet containing the original card, observed change information, the latest completion review, and unresolved facts. Inspect the packet before sharing it or opening a separate review session. It does not launch another agent or write an export.
-
-### Scope and completion
-
-`/scope set` declares expected paths. `/scope accept <path>` acknowledges one finding without widening the contract. `/scope add <path>` widens it. `/scope recheck` replaces an uncertain baseline.
-
-`/challenge` requires structured requirement evidence and checks for contradictions, false-positive validation, scope drift, missing runtime or visual checks, and residual risk. Its result supports human review and does not replace direct proof.
-
-### Isolated experiments
-
-Use `/experiment start` when an independent review or trial justifies a separate worktree. Open the reported path in another Pi session. SpecPi does not launch an agent, copy dirty base changes, commit, merge, or touch remotes.
-
-SpecPi's default workflow uses one writer per working directory. Its experimental delegation adds bounded read-only Pi sessions. SpecPi Chat also supports independent conversations that you start explicitly; connected chats can continue concurrently in the same workspace. They share workspace files rather than receiving separate worktrees. A parent determines what context a delegated child receives and verifies what returns, so either handoff can omit a material constraint. Parallel writers also introduce conflicting assumptions and increase review work.
-
-## Improvement loop
-
-1. **Record:** A reusable capability gap is stored as a sanitized local report.
-2. **Qualify:** Recurrence, project reach, impact, and recency determine whether the item enters the review menu.
-3. **Select:** `/harness-improvement` authorizes one exact item.
-4. **Implement:** The `specpi-improve` skill makes the narrowest sufficient change and adds direct checks.
-5. **Verify:** The completion gate checks the selected task contract and registry integration, runs `npm run check` and the item's closed validators, and rejects evidence if the checked source changes.
-6. **Retire:** A passing item leaves the queue. Its model-reported evidence and executable verification receipt remain separately identified in the local journal.
-7. **Review again:** Later evidence returns the item as `review-needed`. Implementation does not restart automatically.
-
-<details>
-<summary><strong>View the improvement loop</strong></summary>
-
-<p align="center">
-  <img src="site/self-improvement-loop-v2.svg" width="760" alt="SpecPi improvement loop: local friction becomes qualified evidence; a person chooses one change; verification failure keeps it selected; later evidence returns it to human review.">
-</p>
-
-</details>
-
-### Inspect the record
-
-Use `/wishlist status` for queue and loop-health totals. Use `/wishlist history [gap-id]` for retirement evidence, validators, changed files, reopen signals, and rollback context. `/wishlist` also supports duplicate cleanup, local issue drafts, archive, and reset operations.
-
-With collection enabled, `/wishlist outcome <gap-id>` records an explicit human assessment of the latest local retirement: helped, failed, not exercised, or reverted. Later assessments replace the earlier assessment in totals while history retains both. Failure is a reason to review; it never authorizes another implementation. Unused capabilities remain unassessed.
-
-## Command guard
-
-Every supported model-initiated Pi tool call is classified before execution. Select one mode at session start:
-
-| Mode       | Behavior                                                                                                                |
-| ---------- | ----------------------------------------------------------------------------------------------------------------------- |
-| **Guard**  | Denies confirmed host-wide catastrophe and guard tampering, asks before Git destroys work, and otherwise remains quiet. |
-| **Strict** | Adds approval requests for mutation, execution, sensitive reads, and network activity.                                  |
-| **Off**    | Requires confirmation and applies only to the current session.                                                          |
-
-Approvals apply to one exact call and one session. Only a structurally proven critical mutation locks the session. Parser uncertainty and invalid cleanup syntax are denied without locking later work.
-
-The guard covers the documented `bash`, `powershell`, `read`, `write`, and `edit` seams. Direct shell escapes, malicious extensions, unclassified custom tools, approved scripts, TOCTOU changes, and external processes remain outside its scope.
-
-## Data and security boundaries
-
-**Local state.** SpecPi does not persist command text or read Pi credentials, unrelated sessions, or history. Scope and challenge records are bounded entries in the current Pi session; task cards are bounded to the active session branch. Wishlist reports, improvement journals, experiment metadata, and exported patches remain in private local SpecPi state and can survive uninstall. Review local artifacts before sharing.
-
-**Verification receipts.** Improvement verification fingerprints supported source and validation inputs, records actual gate results, and detects changes between verification snapshots. Receipts retain hashes and runtime metadata, not source contents or raw command output. They describe what was checked; they are not cryptographic attestations or proof that a model's acceptance explanation is correct. Older journals remain readable and are identified as lacking a receipt.
-
-**Provider and network access.** Local SpecPi evidence does not make the whole agent offline. Pi sends model requests to the selected provider, browser pages and installed packages may contact the network, and Pi has separate telemetry and update-check settings. The installer explains these boundaries without changing those upstream preferences.
-
-**Host permissions.** Pi extensions run with the current user's permissions. Use OS permissions, a least-privilege account, a container, or a VM for hostile code or data. See [SECURITY_MODEL.md](SECURITY_MODEL.md) for the complete trust model and [SECURITY.md](SECURITY.md) for vulnerability reporting.
+## SpecPi Chat for VS Code
 
-## Development
+Chat beside your code, attach files, and switch conversations.
 
-```bash
-npm install --ignore-scripts --omit=peer --no-package-lock
-npm run format
-npm run check
-```
+[**Install from Marketplace**](https://marketplace.visualstudio.com/items?itemName=tannermidd.specpi-chat) · Requires the setup above and VS Code 1.96+.
 
-JavaScript and TypeScript use four-space indentation, explicit braced control flow, and one statement per line. The repository check enforces formatting, validates syntax, strictly type-checks the browser extension, runs the Node test suite, executes registry-linked validators, and installs the exact npm tarball through an isolated lifecycle. Maintainers should follow [NPM_RELEASE.md](NPM_RELEASE.md) for release preparation and protected publication.
+In VS Code, find **SpecPi Chat** by **tannermidd** in Extensions and install it. Open **SpecPi** in the Activity Bar, then **Connect Pi**.
 
-For application testing, use `browser_diagnostics` alongside rendered inspection, and `browser_press`, `browser_select_option`, and `browser_wait_for` for keyboard, native dropdown, and asynchronous flows. Diagnostics are bounded and best-effort sanitized, not guaranteed secret-free or proof of application health.
+## Go further
 
-Provision repository-local Chromium with `npm run setup:browser`, then run `npm run test:browser` and `npm run test:site:browser`. The required CI browser commands reject skipped coverage; Pages deployment waits for the same rendered check. See [browser testing](docs/browser-testing.md) for tool contracts, privacy limits, type-check scope, and the semantic-navigation assessment.
+[Commands](https://tannermidd.github.io/SpecPi/wiki/#reference) · [Chat help](https://github.com/TannerMidd/SpecPi/blob/main/vscode/README.md) · [Development](https://tannermidd.github.io/SpecPi/wiki/#development) · [Security](SECURITY_MODEL.md) · [Release notes](CHANGELOG.md)
 
-MIT licensed.
+[MIT License](LICENSE)

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,7 +14,7 @@ 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.
 
@@ -64,6 +64,8 @@ Browser type checking and registered-tool tests additionally use exact project-l
 
 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/delegation/README.md

@@ -1,6 +1,6 @@
 # Bounded delegation
 
-Status: experimental in SpecPi 0.16.0. Enabled by default at Pi startup.
+Status: experimental in SpecPi 0.17.0. Enabled by default at Pi startup.
 The package remains `specpi`; no separate npm package or background service is required.
 
 SpecPi keeps one agent responsible for changes and acceptance. This extension adds
@@ -188,7 +188,7 @@ edits, coupled mutable work, generic second opinions or repeated role-based answ
 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,
+The parent obtains and selects source material. Model routing, automatic provider retries,
 live-web access, monetary admission and automatic policy tuning remain unimplemented.
 
 `/task` remains optional. Changes to an active task contract invalidate delegation,
@@ -205,21 +205,42 @@ and counters. [Protocol and executable examples](protocol.md) define the exact f
 | 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        |
+| Batches / jobs            | 32 batches per Pi process; one unresolved batch; 2 jobs per batch            |
+| SDK model invocations     | 256 per Pi process, 64 per batch; 32 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                                             |
+| Packet / child context    | 256 KiB handoff; 2 MiB serialized child context, checked before dispatch      |
 | Selected sources          | 200 files and 8 MiB per batch                                                |
-| Tools                     | 12 calls and 64 KiB total returned JSON per logical job                      |
+| Tools                     | 96 calls and 512 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                        |
+| Requested provider output | Pi's normal provider/model output and thinking settings                     |
+| SDK-visible response      | 1 MiB acceptance limit on observed response content; scales with budget       |
 
-These are conservative experiment limits, not empirically optimal values. Each SDK
+These use the default budget multiplier of 8, 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.
+Ordinary source-argument mistakes return corrective feedback. Invalid or truncated
+reports trigger a correction in the same child session with its passages preserved.
+These corrections consume the existing model-call, context and deadline budgets;
+they do not create a fresh job or reset usage. Only a validated report can complete.
+
+Use `/delegate off`, `/delegate budget 16`, then `/delegate on` for a larger review:
+192 source tool calls, 1 MiB source output, and 64 model turns per job. The human-only
+budget command saves a multiplier from 1 to 64; `budget reset` restores 8. It scales
+tool calls/output, model turns per job/batch/process, process batches, and serialized
+child context and SDK response bytes together. It leaves concurrency, tool-response/packet/result limits,
+and timeouts unchanged. Existing settings files use 8 when no budget is saved.
+Budget changes invalidate old jobs and preserve spent process counters. Use a fresh
+batch afterward. Increasing budgets can increase model usage, cost, and retained
+context; provider context-window limits still apply.
+
+Tool-byte receipts count only delivered JSON; a rejected response cannot inflate the
+total beyond the allowance. Budget exhaustion reports the specific allowance and
+blocks a follow-up before launching a child. Successful follow-ups retain their
+existing passages and share the original budget/deadline. A failed child is released;
+when another attempt is eligible it starts with the original handoff, not the failed
+child's transcript.
 Pi authentication preflight occurs before the model-invocation counter; these quotas
 do not count or bound Pi's authentication/OAuth preparation.
 
@@ -257,6 +278,27 @@ all selected bytes. Publication, collection, follow-up and disposition also rech
 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.
 
+Snapshot creation failures report a safe reason and, when applicable, the one-based
+position in the batch's selected-source list (job order, with repeated paths removed).
+Paths must be exact repository-relative filenames. A relative path can still be
+rejected for known private storage or credential-store filenames,
+unsupported file types, missing or inaccessible files, links, quotas, or changed or
+non-text content. The diagnostic never includes raw filesystem errors or file contents.
+Rejection starts no worker and consumes no batch or inference allowance. It provides
+no independent review. Check the reported cause before submitting corrected inputs;
+do not rename or copy restricted files to bypass the source policy.
+
+Ordinary application names such as `auth.ts`, `credentials.ts`, `secrets.py`,
+`credential-url.json`, and `sessions/` are allowed across supported text formats.
+The parent chooses the review material. Private namespaces such as `.pi`, `.ssh`,
+and SpecPi Chat storage, the configured Pi agent directory (including its canonical
+alias target), `.env` files, credential stores such as `auth.json` and
+`credentials.json`, and private keys remain blocked. An inaccessible configured
+Pi storage boundary must be repaired before capture. All selected-file scope,
+containment, link, text, size, and freshness checks still apply. Source naming is
+not proof that a file contains no secrets. Workers have no ambient source access;
+using the parent's provider does not grant them the parent's tools or transcript.
+
 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
@@ -282,6 +324,17 @@ Only bounded state summaries, quota counters and the idempotency journal remain
 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.
+Worker failures identify the failing stage: source tools, provider requests, stream or
+context/response limits, missing/truncated output, or final JSON/schema/evidence validation.
+Known source and report-validation reasons are included; raw provider errors, rejected
+report text, and filesystem paths are not. A tool failure keeps its original diagnostic
+even when Pi aborts the session. A low tool-call count therefore does not imply a reading
+budget failure. Delegation does not impose its own output-token cap. Ordinary argument
+errors and invalid reports can be corrected within the same session; source changes,
+revocation, unavailable tools and exhausted allowances still terminate it. No failure
+is a completed review or independent sign-off. Provider failures do not trigger automatic
+retries; a changed-input follow-up still shares the original job allowances
+and deadline, and a released failed child starts from its original handoff.
 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

package/docs/delegation/protocol.md

@@ -172,9 +172,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 +232,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 +255,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.