specpi 0.11.2 → 0.12.0

package/docs/delegation/evaluation.md

@@ -0,0 +1,307 @@
+# Delegation evaluation and implementation gates
+
+This is an experiment specification, not a report of comparative outcomes. The
+[experimental implementation](README.md) uses Pi AgentSession workers under the
+[bounded session protocol](protocol.md). Runtime, broker, lifecycle and synthetic-provider
+fixtures require a fresh run against this SDK integration before they support a passing
+contract claim. Tests do not establish better task quality, cost or latency, or parity
+with every live provider. No comparative outcome experiment is reported here. The numeric criteria
+below remain proposed hypotheses, not research-derived constants or achieved results.
+
+The [archived architecture](design.md) and [target protocol](design-protocol.md) retain
+stronger proof obligations. In particular, full parent request-pipeline parity,
+midstream/raw-transport bounds, admission of every underlying provider attempt and
+monetary admission remain unmet by the native `bounded-pi-sessions-v1` contract.
+
+## 1. Decide what improvement means before a run
+
+Choose one primary objective for each cohort: quality, cost, or time. Set the quality
+floor, resource envelope, allowed model routes, acceptance rubric and stop rules before
+looking at outcomes. A route must not claim success by changing its objective afterward.
+
+Acceptance is task-specific and independently adjudicated. For code, use hidden or
+held-out behavior checks, appropriate regression tests, and human review of the diff.
+For research, use verified factual coverage, source quality, citations, and material
+omissions. For review, use confirmed defects, false positives and reviewer-induced
+regressions. A worker's `complete` declaration or a host receipt is never the target metric.
+
+Use versioned public or sanitized fixtures. Keep evaluation data separate from private
+Pi sessions and user repositories unless a human explicitly provides those materials
+for this purpose. No automatic collection from ordinary conversations.
+
+## 2. Baselines and comparisons
+
+| Arm                                                     | Purpose                                                                         |
+| ------------------------------------------------------- | ------------------------------------------------------------------------------- |
+| A: capable single agent with current workflow           | Establish the useful baseline                                                   |
+| B: the same agent with the same total additional budget | Distinguish delegation from simply buying more reasoning or another review pass |
+| C: structured serial workflow, same execution context   | Test workflow structure without separate identities                             |
+| D: selective one- or two-worker delegation              | Test the experimental implementation                                            |
+| E: always-delegate policy                               | Measure routing value and unnecessary overhead; evaluation only                 |
+| F: approved sequential model routing                    | Separate model-selection benefit from child-context benefit                     |
+
+Do not run all six arms on every case before establishing which question matters.
+For stage 1, A/B/D on frozen reviews is sufficient. Add C/E for investigation and F
+only when alternative models are authorized. Use the same exact provider/model version
+and tools where the comparison calls for it. A mixed-model arm must disclose composition.
+
+Start with the implemented `review` and `scout` purposes, not all archived profiles.
+Compare frozen review against both normal parent review and an additional parent pass
+under the same total envelope. Include clean changes so false positives carry a cost.
+For scouts, compare parent-only and structured serial analysis before attributing gains
+to fresh context or parallelism. Evaluate one versus two workers only when independent
+source partitions justify that question.
+
+Record the parent's and child's effective thinking settings and model clamping. The
+child uses a fresh standard Pi ModelRuntime; parent hooks and ephemeral settings are
+not inherited. Control these differences when isolating architecture, or disclose them
+as part of an end-to-end workflow comparison. Same model IDs alone do not establish
+equal inference configuration.
+
+Use total task spending, not only worker spending. Include preparation, parent reasoning,
+worker requests, tools, retries, synthesis and validation. When actual dollar cost is
+unavailable, label the cohort as call/token/latency constrained and do not describe it
+as dollar-matched. Give the parent sufficient remaining budget to consume and check a
+result; a worker that spends the whole allowance before integration has not succeeded.
+
+Match maximum resource envelopes and report actual use in both arms. Equal ceilings
+do not imply equal spending. Run latency comparisons separately from quality/cost
+comparisons because provider load and concurrency can change latency.
+
+## 3. Task strata
+
+Use at least these separately reported classes:
+
+- Small understood edits and short lookups, where delegation should usually be rejected.
+- Coupled changes with unsettled interfaces, where one writer should retain ownership.
+- Independent repository investigations, including contradictory hypotheses.
+- Large source collections with verifiable coverage requirements and repeated evidence.
+- Frozen reviews with naturally occurring defects, seeded defects, and clean changes.
+- Difficult decisions with sufficient context, plus missing-context cases that require abstention.
+- Cancellation, stale source, prompt injection, bad decomposition and provider failure cases.
+
+A pilot of 30–50 cases is for debugging the protocol and estimating variance, not
+declaring a universal routing winner. Freeze policy after the pilot. Size a separate
+holdout using the minimum useful effect, expected paired disagreement and cluster
+variation. A target of 200 or more holdout cases can be a planning starting point;
+it is not a power guarantee. Use repeated runs where stochastic variation is material.
+
+Partition by repository or source family when possible so close variants do not leak
+between tuning and evaluation. Randomize arm order, record service conditions, define
+cold/warm cache handling, and use repeated time blocks to reduce infrastructure bias.
+Cluster uncertainty by task/repository as appropriate. Include all admitted trials,
+timeouts and failed attempts; do not condition the headline metric on successful jobs.
+
+## 4. Required measurements
+
+| Measure                | Definition or interpretation                                                                |
+| ---------------------- | ------------------------------------------------------------------------------------------- |
+| Accepted-task rate     | Accepted tasks / all attempted tasks, under the frozen rubric                               |
+| Cost per accepted task | Sum of all task costs / accepted tasks; undefined if none pass                              |
+| Resource use           | Input/output/cache/tool categories, calls, retries, unknown accounting and model identities |
+| Elapsed time           | End-to-end p50/p95 plus uncertainty; separate provider wait, work and integration           |
+| Review precision       | Confirmed material findings / all material findings presented                               |
+| Review recall          | Confirmed detected defects / adjudicated defects in the evaluated fixtures                  |
+| Human correction       | Time and actions needed to resolve findings and repair final output                         |
+| Coverage               | Required questions or requirements supported by applicable evidence                         |
+| Context failures       | Missing or distorted information that changed a conclusion or prevented acceptance          |
+| Coordination overhead  | Preparation, repeated source work, messages, synthesis, invalidated jobs and integration    |
+| Recovery               | Verified recoveries by fault class, including abandoned work and additional cost            |
+| Routing errors         | Unnecessary delegation, missed useful delegation and unsupported model/capability requests  |
+| Policy violations      | Denied capabilities attempted, actual escaped capabilities and stale result publication     |
+
+Do not count a speculative finding as a caught bug. Separate naturally occurring and
+seeded defects. Do not reward verbose output, agreement among agents, smaller packets,
+clean merges, model confidence, or absence of exceptions as substitutes for acceptance.
+
+## 5. Promotion rules
+
+The user should choose the minimum useful change before a confirmatory run. Suggested
+initial rules for discussion and pre-registration are:
+
+| Objective | Candidate rule                                                                                                                                                |
+| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Cost      | At least 20% lower total cost per accepted task, with the lower one-sided 95% bound for the quality difference above a predeclared −2 percentage-point margin |
+| Time      | At least 25% lower median end-to-end latency under the same resource ceiling and quality margin, without unacceptable p95 regression                          |
+| Quality   | Positive paired improvement whose confidence interval excludes zero, under the fixed budget; no unacceptable increase in false positives or correction time   |
+
+Report confidence intervals on the primary effect, not only on each arm's mean.
+Use paired task-level analyses and clustered resampling where the sampling design
+requires it. A low-powered non-significant difference is not evidence of equivalence.
+If the holdout cannot resolve the chosen margin, keep the route experimental rather
+than moving the threshold after the result. Correct for multiple confirmatory route
+comparisons or specify one primary comparison and treat the rest as exploratory.
+
+Any actual capability escape, credential exposure, invalid acceptance across a task
+revision, or concealed cost accounting blocks promotion regardless of mean quality.
+Zero observed escapes in fixtures does not prove universal containment; record the
+enforced interface and residual trust assumptions.
+
+Promote one task class and model route at a time. Pin the accepted policy version and
+retain a parent-only fallback. A later model/provider/harness change invalidates an
+assumption and requires appropriate reevaluation, not automatic inheritance of gains.
+
+## 6. Targeted ablations
+
+Run only the ablations needed to resolve a material decision:
+
+1. Same-context self-review versus fresh-context review with identical requirements.
+2. Same-model worker versus an authorized alternative, keeping context and tools fixed.
+3. One versus two workers on genuinely independent source partitions.
+4. Selected original context versus compressed context with original-source retrieval.
+5. Explicit incomplete results versus forced answers under missing evidence.
+6. One diagnosed retry versus blind replay on transient and semantic failures.
+7. Parent verification versus unchecked worker summaries, inside test fixtures only.
+8. Warm versus cold cache and single-provider versus allowed model switching.
+
+This separates the value of context isolation, model capability, concurrency,
+compression and validation. A gain from one must not be attributed to another.
+Alternative models, compression, automatic retries and live-web research are not
+implemented routes. Ablations requiring them need separate authorized fixtures or a
+reviewed implementation; they are not options in the shipped model-facing tool.
+
+## 7. Runtime compatibility and security fixtures
+
+The implementation includes deterministic fake-provider and broker fixtures. Run the
+relevant suites and record their actual results before live inference; this checklist
+is not itself a passing receipt. The supported calls/time contract requires coverage for:
+
+- Native Pi package discovery and actual SDK AgentSession creation on recorded test
+  versions, including current Pi releases, with in-memory sessions and rejection of
+  missing capabilities and unsupported routes. New version identifiers alone must not
+  block activation. API presence or a CLI version check is not suite completion.
+- Explicit parent model/thinking with Pi clamping; fresh standard ModelRuntime
+  configuration; configured global transport/thinking budgets without project settings;
+  rejection of runtime-only authentication, selected extension-provider overrides,
+  model-specific headers, startup proxy configuration and safe descriptor mismatches.
+  Parent hooks, ephemeral runtime settings
+  and session affinity are not implicitly inherited.
+- No ambient child extensions, skills, AGENTS files or parent session history; the SDK
+  owns the agent/tool loop, with only selected-source tools exposed.
+- Review/scout mode and benefit compatibility, required evidence, assigned requirement
+  subsets, duplicate-question rejection and parentWork required only for parallel claims.
+- Normal Pi ownership of resource discovery, trust, proxy policy and authentication,
+  without a separate SDK host or bootstrap override.
+- Native and legacy provider composition using synthetic credentials only; no secrets
+  returned to the extension, logged, or copied into packets.
+- Errors represented as resolved terminal messages, setup failure and missing usage.
+- Abort before admission, during provider setup, during inference and immediately before
+  a broker operation; non-cooperative provider settlement and late output rejection.
+- Concurrent call-slot accounting, duplicate submissions, aggregate counters and
+  non-resetting follow-up limits; cancelled requests keep slots until settlement.
+- Admission before every SDK model invocation, including tool continuations; provider
+  and session retries and automatic compaction disabled; requested output clamped to
+  the model maximum. Follow-up does not reset allowances.
+- Pi-owned authentication preflight before model-invocation accounting, without
+  claiming that the inference counter bounds authentication/OAuth preparation.
+- Oversized SDK-visible streaming responses, bounded reports/tool output and correct
+  settlement state. Hold slots through stream/result and prompt settlement; do not infer
+  physical remote termination or a raw-response/allocation guarantee from SDK events.
+- Lost collection responses, cursor replay, idempotent follow-up and resolution,
+  stale result revisions, conflicting idempotency payloads and cancelled-job revival.
+- Asynchronous job leases surviving normal `run` return without retaining stale
+  extension contexts, and revocation at the intended task/policy boundaries.
+- Complete versus partial tool calls, repeated IDs, unknown tools and schema tampering.
+- Path traversal, encoded paths, symlinks/reparse points, private files, source changes,
+  invalid line ranges and oversized input/output.
+- Actual branch navigation versus ordinary leaf advancement; model, task, scope and
+  policy changes during queued and active work; controller and aggregate quotas
+  retained across reloads, session switches and off/on within the Pi process.
+- Fixed canonical working root, with a Pi restart required for a new root or runtime
+  version rather than loading changed implementation code through `/reload`.
+- Completed reports remain source-bound after the deadline; child sessions release at
+  the deadline and subsequent follow-up fails.
+- Reused Guard instances restore exactly one state responder; invalid, declined and
+  stale-confirmation commands cannot revoke or downgrade policy.
+- SDK errors with synthetic secret canaries never enter status, notices or tool output.
+  Throwing/rejecting teardown is contained across cancellation and deadline callbacks.
+- Shared snapshot text survives an eligible sibling follow-up, then is destroyed;
+  failed jobs still expire inputs, and retired batches preserve quotas and replay keys.
+- Partial usage retains known fields and per-field reporting coverage; missing fields
+  are distinct from reported zero, including unsuccessful calls.
+- Operation-count probes cover per-event root/model checks, snapshot tool reads and
+  linear serialized-byte work. Overflow and source/model drift remain rejected at
+  protected boundaries. These probes measure implementation work, not user-visible
+  latency, production model quality, or dollar savings.
+- Recursive source syntax checks discover new nested modules and TypeScript syntax,
+  including negative fixtures; they do not rely on a maintained filename list.
+- No worker writes, recursion, arbitrary process execution or copied parent-tool bypass.
+- Normal parent-tool-result retention through Pi versus in-memory worker state, accurate
+  privacy disclosure, bounded retained data, cleanup and no automatic resume.
+
+### Local regression measurements: September 5, 2026
+
+The review-fix probe used identical source bytes from
+`d49fe9bc227cac480fea825932795e6db57e2127:extensions/delegation/worker.mjs`
+as a selected fixture, comparing the old snapshot broker with the corrected broker.
+Read used `read("s1", 1, 200)`; search used `search("a", 20)`. Returned objects were equal.
+
+| Operation                  | Before: bytes serialized | After: bytes serialized | Returned JSON bytes |
+| -------------------------- | -----------------------: | ----------------------: | ------------------: |
+| Read 183 lines             |                  809,549 |                   8,220 |               8,220 |
+| Literal search, 20 matches |                   25,485 |                   2,741 |               2,762 |
+
+This counts work inside `JSON.stringify`, including intermediate prefixes, not network
+traffic. The read path now encodes each line once; search encodes each match once and
+adds array punctuation arithmetically. Per-tool binding checks performed zero file
+reads; full freshness checks still reread and hash the source. A synthetic 1,000-delta
+provider regression requires fewer than 40 full lease checks and less than 100 KB of
+serialization, while every delta still receives cheap lease and bounded-data checks.
+The actual Pi fixture also exercises fragmented localhost SSE and transient root lookup
+recovery. These are reproducible workload checks in the snapshot/provider/native test
+suites, not measured UI-latency improvements or production-provider benchmarks.
+
+### Stronger target gates: not met by the calls/time experiment
+
+The following remain requirements before claiming the corresponding guarantees in
+the [target protocol](design-protocol.md):
+
+- Full parent inference-pipeline parity, including request hooks, ephemeral runtime
+  settings and session affinity. Explicit model/thinking and standard child configuration
+  do not supply that broader contract.
+- Every underlying inference attempt, including transport fallback or an internal SDK
+  retry, receives pre-dispatch admission; opaque attempts are rejected and initial
+  dispatch is not double-debited.
+- Raw text, reasoning, framing, compressed transport and tool arguments are bounded
+  before parsing or allocation, including decompression and transport buffering.
+- Monetary reservations account conservatively for provider pricing, uncertain dispatch,
+  retries and settlement, with honest unknown-cost behavior.
+
+The current runtime disables configurable retries, counts model invocations, enforces
+logical deadlines, validates inputs before dispatch, counts observed stream deltas and
+validates complete parsed responses at protected boundaries. It reports cost as unavailable. These controls do
+not pass the stronger gates: adapters may buffer the whole response or make transport
+attempts before SpecPi observes completion. The narrower experiment must reject policies requiring unsupported
+guarantees. Its fixture tests cannot be presented as transport, invoice or process-memory
+proof. The unimplemented recovery/retry policy also needs separate fault-class tests.
+
+For the later web adapter, add connection-time public-address checks, redirects,
+rebinding defenses, credential/header stripping, oversized responses, malformed text,
+page instruction injection and blocked private-network destinations. Test the actual
+transport boundary; a validator unit test alone does not prove connection behavior.
+
+All installer, package and Pi integration tests use fresh temporary state and skip
+unnecessary external installation. A live provider smoke test is a separate explicit
+authorization with a harmless prompt and a bounded cost envelope. Fake tests cannot
+prove production provider parity or network behavior.
+
+## 8. Shipping gate and rollback
+
+Before release, inspect the complete diff, run focused tests and the full repository
+check, exercise the packaged artifact, and obtain fresh independent review of provider,
+permission, cancellation, retention and dependency changes. Update third-party and
+security documentation to describe the contracts actually implemented. A host bridge
+that does not exist cannot be replaced with a private-field workaround just to pass
+the release gate.
+
+Disabling the extension must stop new calls and revoke broker grants immediately while
+reporting requests still settling. Uninstall must not require restoring provider
+configuration or authentication files because the package never owns them. Explicit
+user-exported evidence remains user data. Policy rollback returns routing to the last
+validated version or parent-only operation; it never discards user changes or retries
+abandoned work automatically.
+
+An experimental implementation with passing fixtures establishes only its tested
+contract. Promotion beyond experimental status requires repeatable value on a defined
+task class and understandable operating boundaries. Unimplemented capabilities remain
+absent, not represented as partially functioning options.

package/docs/delegation/protocol.md

@@ -0,0 +1,271 @@
+# 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.
+
+The extension loads through normal `pi` package discovery and remains disabled until
+the human runs `/delegate on`. Compatibility is checked through required public SDK
+capabilities; there is no exact-version allowlist. Missing APIs prevent activation and
+are named in the error. The runtime also verifies the created session's thinking,
+tools and streaming interface. Tested versions are evidence, not an activation gate.
+Workers are SDK `createAgentSession` instances using in-memory session storage and a
+fresh Pi `ModelRuntime`. The parent model and thinking level are passed explicitly,
+subject to Pi's clamping. Standard Pi authentication, environment and `models.json`
+resolution apply. Child transport/thinking budgets come from configured global settings;
+project settings are not loaded. Runtime-only authentication, selected extension-provider
+overrides, model-specific headers, startup proxy configuration and safe model-descriptor
+mismatches fail preflight. Parent request hooks,
+ephemeral runtime settings, session affinity and ambient resources are not inherited.
+
+Command Guard is optional. Absent and Off states permit human activation; an installed
+Guard's Strict approvals and explicit locks remain enforced. Unready or duplicate
+Guard responders prevent activation with a specific error. Guard state changes revoke
+the current delegation generation. Snapshot tools and resource limits are enforced
+by delegation itself in every mode. Status includes the observed `guard` state.
+
+The SDK runs the conversation and selected-source tool loop. SpecPi admits each SDK
+invocation before dispatch and observes the SDK stream; provider/session retries and
+automatic compaction are disabled. This does not establish hard raw-transport,
+hidden-provider-attempt, invoice or process-memory limits.
+Pi authentication preflight precedes the model-invocation counter; its preparation
+is not a model invocation or an operation bounded by that counter.
+
+Every object is closed: unknown fields, duplicate IDs, malformed values and oversized
+data are rejected. The host creates identities and receipts; workers cannot supply them.
+The protocol identifier `bounded-pi-sessions-v1` and inference contract
+`pi-agent-session-v1` describe the host implementation, not model-selected options.
+
+## Submit a batch
+
+After the human runs `/delegate on`, the parent calls the `delegate` tool:
+
+```json
+{
+    "operation": "run",
+    "requestId": "scout-routing-1",
+    "packet": {
+        "objective": "Explain how model selection reaches the request pipeline",
+        "requirements": [{ "id": "R1", "text": "Identify the route binding and its invalidation behavior" }],
+        "decisions": ["The parent remains the sole writer"],
+        "nonGoals": ["Do not implement or change providers"],
+        "reason": {
+            "benefit": "parallel_analysis",
+            "why": "Source analysis can proceed independently of the parent's lifecycle-test inspection",
+            "parentWork": "Inspect the lifecycle tests while the worker reads"
+        },
+        "jobs": [
+            {
+                "id": "route",
+                "mode": "scout",
+                "requirements": ["R1"],
+                "question": "Where is the model captured, and when is that capability revoked?",
+                "context": "Return evidence for R1, including missing or contrary evidence.",
+                "sources": ["extensions/delegation/provider.mjs"]
+            }
+        ]
+    }
+}
+```
+
+`run` returns immediately with `batchId`, `packetDigest`, `generation`, a collection
+cursor and job states. It does not return invented findings while work is pending.
+The digest binds the packet, source descriptors, host identity, selected model/provider
+IDs and resource policy. It does not freeze the registry's endpoint, headers or
+authentication configuration. Those can change behind the same public identities;
+the extension cannot observe every such change or certify an unchanged provider route.
+IDs are short alphanumeric/hyphen/underscore strings. The host batch and attempt IDs
+are UUIDs. Source paths are exact relative filenames, not directories, globs or commands.
+Modes are `review` and `scout`. Either can use the selected-source list/read/literal-search
+tools when files are supplied. A scout requires at least one selected file. A review
+requires nonempty inline context or selected files; with an empty `sources` array it
+uses inline context without tools. Source selection never grants ambient filesystem
+or web access. Questions that are identical after trimming and case normalization are
+rejected; distinct text does not establish distinct reasoning work.
+
+`reason` contains exactly `benefit`, `why` and `parentWork`. `why` is nonempty.
+`independent_review` requires review jobs; `parallel_analysis` and `context_isolation`
+require scout jobs. `parentWork` must describe useful concurrent work for
+`parallel_analysis` and may be empty otherwise. These are structural admission checks,
+not proof that delegation improves the task.
+
+Each job's nonempty `requirements` list names unique IDs from the packet's global
+requirements. The child receives only its assigned requirements, plus the global
+decisions and non-goals. A batch contains at most two jobs. All modes require the same
+explicit packet fields, even when an allowed array or string is empty.
+
+## Inspect and collect
+
+Worker `list_sources` accepts an optional zero-based `offset` and returns
+`{ "sources": [...], "nextOffset": number | null }`. Each page is at most 16 KiB,
+including JSON metadata, and fits the remaining tool-byte allowance. A non-null
+`nextOffset` identifies the next page; null marks the end. Pages consume the same
+per-job tool-call and byte budgets as reads and searches.
+
+```json
+{ "operation": "status" }
+```
+
+```json
+{ "operation": "collect", "batchId": "HOST_BATCH_ID", "afterCursor": 0, "waitMs": 30000 }
+```
+
+`status` is compact and available while disabled. `collect` returns reports whose
+completion cursor is newer than `afterCursor`; omitting it replays retained reports.
+An accepted next batch retires the previous batch's reports. Old generations retire
+after their workers settle. `status` retains bounded summaries marked `retired: true`,
+but retired batches reject collect and follow-up. Quotas and request fingerprints survive
+retirement, so replay cannot reopen a batch or replenish the process allowance.
+`waitMs` defaults to zero and cannot exceed 30 seconds. There is no destructive dequeue
+and no automatic parent turn. A cursor ahead of the batch is invalid.
+
+Collection rechecks host/task/policy generation and every selected source binding.
+A changed file is stale even when its pathname is unchanged. Source or lifecycle changes
+cannot be repaired by presenting an old receipt or idempotency key.
+
+Each returned item has `receipt`, `result`, `error`, and `disposition`. A host receipt
+contains `batchId`, `jobId`, `attemptId`, `packetDigest`, `generation`, `resultRevision`,
+`model`, `state`, `settling`, call/tool counters, token usage, `usageReportedCalls`, `usageComplete`, and
+`cost: null`. Copy the six binding fields when following up or resolving. The
+`collectionCursor` belongs to delivery ordering, not result identity.
+Each usage field sums its valid reported values independently; never-reported fields
+are `null`. `usageReportedCalls` counts reports for each field. A positive subtotal may
+still be incomplete; `usageComplete` requires all four fields for every admitted call.
+
+## Worker report
+
+Workers return this exact shape, without Markdown fences:
+
+```json
+{
+    "status": "partial",
+    "answer": "The selected context is insufficient to establish runtime behavior.",
+    "requirements": [{ "id": "R1", "status": "unaddressed", "evidence": [] }],
+    "findings": [],
+    "missing": ["A provider implementation or runtime fixture"],
+    "nextStep": "The parent should inspect the provider fixture before making a claim."
+}
+```
+
+Statuses are `complete`, `partial`, or `needs_context`. Every assigned requirement appears
+exactly once as `addressed` or `unaddressed`. Each finding has `id`, `claim`, `confidence`
+(`observed`, `inferred`, `unverified`), `evidence` and `contraryEvidence`. Evidence entries
+contain exactly `sourceId`, `lineStart`, `lineEnd`. References must resolve within the
+job selection and valid line ranges. `p1` denotes the submitted inline context; it
+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.
+
+## Follow up and resolve
+
+```json
+{
+    "operation": "follow_up",
+    "requestId": "route-correction-1",
+    "batchId": "HOST_BATCH_ID",
+    "jobId": "route",
+    "attemptId": "HOST_ATTEMPT_ID",
+    "packetDigest": "HOST_64_CHARACTER_SHA256",
+    "generation": 2,
+    "resultRevision": 1,
+    "prompt": "Reconsider the claim using the already-selected source; identify the missing condition."
+}
+```
+
+The uppercase placeholders above must be replaced with the current host receipt.
+One follow-up creates a new attempt under the original job deadline, context,
+selected sources, model-call counters and tool counters. It cannot add files, change
+models, extend time or reset quotas. If it needs a new grant or source set, discard
+the report and submit a fresh batch. A settling, cancelled, expired, stale or finally
+disposed result cannot receive a follow-up.
+
+```json
+{
+    "operation": "resolve",
+    "requestId": "route-assessment-1",
+    "batchId": "HOST_BATCH_ID",
+    "jobId": "route",
+    "attemptId": "HOST_ATTEMPT_ID",
+    "packetDigest": "HOST_64_CHARACTER_SHA256",
+    "generation": 2,
+    "resultRevision": 1,
+    "decision": "needs_check",
+    "findings": []
+}
+```
+
+Overall decisions are `accept`, `discard`, `needs_check`. Each returned finding must
+appear exactly once in `findings` with `{ "id": "F1", "decision": "confirmed" }`,
+`rejected`, or `needs_check`. Acceptance requires a result and no unchecked findings.
+Accept/discard finalize the parent disposition; needs_check leaves it open for a later
+assessment or allowed follow-up. These are parent assertions, never human permission,
+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
+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
+cache. After eviction, those operations are revalidated against current state; they
+cannot start inference or restore cancelled jobs. Generation and source checks still
+apply. Neither cache eviction nor failed attempts reset quotas or block cancellation.
+
+## Cancellation and lifecycle
+
+```json
+{ "operation": "cancel", "requestId": "cancel-route-1", "batchId": "HOST_BATCH_ID", "jobId": "route" }
+```
+
+Omit `jobId` to cancel the batch. Cancellation remains available after invalidation.
+Job states are `queued`, `running`, the three report statuses, `failed`, `cancelled`,
+`expired`, and `stale`. Terminal job state and `settling` are separate. Cancellation
+revokes tool access and requests SDK abort. A worker keeps its global slot through
+SDK-visible stream/result and prompt settlement. Old payloads are discarded. Neither
+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.
+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.
+Model and thinking selections retain the human's activation choice. The extension
+preflights the latest selected host and resumes dispatch automatically, without
+replaying old jobs. Unsupported selections pause dispatch and report `pauseReason`;
+a compatible selection resumes it. Status exposes `requested`, `updating` and
+`pauseReason` alongside the controller's `enabled` flag. Concurrent notifications
+for the same host share setup, and a late setup cannot overwrite a newer selection,
+explicit off command, Guard revocation or session change. A turn-start refresh also
+catches a changed host before the next parent turn.
+The canonical working root remains fixed for that process. Restart Pi to change the
+root or load a new delegation runtime version. There is no retry on process restart
+and no durable worker queue. Completed reports retain their original source bindings
+after the deadline; child sessions are released at the deadline and subsequent
+follow-up is rejected. Snapshot text is destroyed when every job loses continuation
+eligibility. Failed first attempts retain the original expiry timer. After settlement,
+packet and job-input references are dropped; only source metadata/digests remain to
+validate completed reports until retirement.
+
+Per-event lease checks use model/context identities and generation. Full canonical-root,
+safe model-descriptor and provider-policy checks run at request, tool and publication
+boundaries. Snapshot tools check canonical/stat bindings; full digest checks run at
+capture, publication, collect, follow-up and resolve. These cheaper checks assume a
+trusted local filesystem and Pi's parsed stream contract. Streaming uses incremental
+recognized-delta accounting and bounded structure checks, with exact response checks
+at content/terminal boundaries. It does not promise an exact per-event size bound for
+inconsistent SDK partial objects. Bytes may already be allocated before an event.
+Per invocation the parser permits 64 content blocks, 512 structural nodes per partial,
+65,536 events and 130 non-delta boundaries. These fixed engineering ceilings also bound
+repeated whole-message validation for malformed event sequences.
+Unexpected SDK errors are redacted before status/tool/UI output; teardown failures
+cannot escape timer callbacks or reset settling ownership.
+
+The enforced [resource envelope and limitations](README.md#enforced-resource-envelope)
+define `bounded-pi-sessions-v1`. Unsupported hard billing, raw transport, provider
+attempt and process-memory policies are not accepted through this API.