pi-ui-extend 1.0.40 → 1.0.41

package/external/pi-tools-suite/docs/context-gateway-p01r-rd-evidence.md

@@ -0,0 +1,100 @@
+# Context Gateway P01-R / R-D evidence
+
+<!-- markdownlint-disable MD013 -->
+
+> Date: 7 September 2026.
+> Repository HEAD during deterministic gate: `daa1b06` with a dirty tested tree.
+> Scope: pure test/build parsing plus passive observe classification. Production tool-result delivery remains passthrough; no archive, reference, fetch, execution or LLM summary is introduced.
+
+## Supported parser scope
+
+R-D adds `src/context-gateway/test-output-parser.ts` as a pure in-memory parser for a deliberately small format set:
+
+- Bun test terminal summaries (`pass`, `fail`, `Ran ... tests across ... files`) and exact failure/warning lines;
+- TAP v13-style terminal plan/count summaries and exact `not ok` / diagnostic lines;
+- bounded TypeScript compiler diagnostics plus an explicit terminal `Found N error(s)` summary.
+
+The parser returns `recognised`, `partial`, or `unrecognised`. Host execution outcome remains authoritative; text does not turn an errored shell call into success. A failed test summary without an exact parsed diagnostic is not considered complete.
+
+The parser's ANSI and bare-CR processing creates only an internal parsing view. It does not mutate the original tool result or claim source byte coordinates.
+
+## Conservative failure rules
+
+The parser/delivery planner intentionally falls back to passthrough when any of these conditions holds:
+
+- SDK/upstream truncation is already reported;
+- timeout/abort is visible;
+- terminal summary conflicts with the host outcome (for example PASS summary followed by command exit 1);
+- multiple recognised formats appear in one output;
+- TypeScript pretty/source/caret lines remain unparsed;
+- a failed summary has no captured exact failure diagnostic;
+- the terminal summary is followed by significant unrecognised output;
+- parser input exceeds the bounded scan budget (default 1 Mi-character); head/tail resemblance is not promoted to completeness;
+- the originating shell command is compound or its scope is unknown;
+- a prospective complete compact representation would exceed the configured byte budget.
+
+Compound-command detection is transient and conservative. Observe stores only `simple / compound / unknown`, never the shell command text. False positives merely preserve passthrough; they never rewrite or block execution.
+
+## Prospective compact delivery is all-or-passthrough
+
+`planProspectiveTestOutputDelivery` is a decision helper, not a production shaper. For a complete recognised **simple** command it can build a candidate containing:
+
+1. exact host outcome;
+2. recognised format;
+3. terminal summary counts;
+4. every parsed mandatory error/warning line.
+
+The candidate is accepted only when the entire representation fits the budget. Diagnostics are never sliced merely to hit a target. `partial` and `unrecognised` inputs have no generic head/tail summary path.
+
+No runtime adapter consumes this candidate in R-D. The current Context Gateway `tool_result` handler still returns `undefined`, so delivered content stays byte-equivalent. Connecting a compact delivery requires a later explicit adapter decision with a recovery/lifetime mechanism appropriate to the omitted data. Native truncation alone is not that permission.
+
+## Observe telemetry
+
+Shell output is parsed transiently only while Context Gateway is in `observe` mode. The telemetry snapshot stores:
+
+- parser version;
+- classification and format counts;
+- scan-limited count;
+- terminal-summary / diagnostic / warning counts for the last observation;
+- safe command-scope enum;
+- prospective `compact-candidate / passthrough` decision and allowlisted reason.
+
+It does **not** store command args, diagnostic strings, filenames from diagnostics, raw body, snippets, or hidden-fact fingerprints. Tests compare the input event before/after telemetry and prove it is not mutated.
+
+## Corpus cases
+
+The deterministic corpus covers:
+
+- complete Bun success;
+- a Bun error in the middle of output plus a warning and later passing test;
+- PASS summary followed by host exit 1;
+- timeout;
+- upstream-truncated output;
+- ANSI and bare-CR overwrite;
+- TAP failure with exact diagnostics;
+- compact TypeScript diagnostics and a pretty/unparsed partial case;
+- mixed/nested recognised formats;
+- unknown custom build output;
+- compound and unknown command scope;
+- an intentionally huge output exceeding the parser scan bound;
+- prospective output that fits the byte budget and the same mandatory diagnostics under a too-small budget.
+
+These are format contracts, not claims that every Bun/TAP/TypeScript version is supported. Unknown variants remain passthrough.
+
+## Deterministic gate
+
+```text
+bun test \
+  test/context-gateway/test-output-parser.test.ts \
+  test/context-gateway/observe.test.ts \
+  test/evals/harness.test.ts
+```
+
+Result: **28 pass, 0 fail, 152 assertions**.
+
+Additional checks:
+
+- `npm run typecheck` — pass.
+- `git diff --check` — pass.
+
+No live model call, manual sync, user config change, result replacement or new full-output archive was performed for R-D.

package/external/pi-tools-suite/docs/context-gateway-p01r-re-evidence.md

@@ -0,0 +1,74 @@
+# Context Gateway P01-R / R-E evidence
+
+<!-- markdownlint-disable MD013 -->
+
+> Date: 7 September 2026.
+> Repository HEAD during deterministic gate: `daa1b06` with a dirty tested tree.
+> Scope: mutation/LSP outcome integrity and storeless capability inventory for web/docs, structured JSON, subagents and visual results. No archival adapter, fetcher, grant or lifetime extension was added.
+
+## Mutation and LSP
+
+R-E keeps mutations as native passthrough. An actual `applyPatch` run in a temporary fixture proves that its returned `changedFiles`/summary contain only the file changed by that invocation while an unrelated dirty file remains untouched and absent from the result. `getEventPaths` prefers `details.changedFiles` over broader input/patch-shaped paths, so downstream LSP refresh does not derive a whole-workspace diff.
+
+The pre-approved patch string is not rewritten by Context Gateway. Errored/cancelled mutation results are no-ops for LSP enrichment and storeless metadata cleanup, preserving their original result object/outcome. Existing LSP integration tests continue to cover successful post-edit diagnostics, changed-file deduplication, deleted-file behavior and aliases. R-B SDK-chain tests separately prove that enrichment/protocol fields survive later storeless cleanup/security stages.
+
+No new “partial mutation” inference is introduced. If a producer reports partial/error/cancelled state, Gateway preserves that producer outcome rather than constructing a synthetic success or retry.
+
+## Capability matrix
+
+`src/context-gateway/storeless-capabilities.ts` records the current non-archival decisions. It is metadata only; importing it registers no tools/readers/adapters.
+
+| Surface | Status | Storeless strategy | Lifetime claim |
+| --- | --- | --- | --- |
+| test/build | limited | pure-parser candidate in observe only | current result |
+| mutation/LSP | supported | native passthrough | current result |
+| web/document | limited | native passthrough | current result |
+| structured JSON | limited | native passthrough | current result |
+| subagent result | limited | native passthrough | producer-managed |
+| visual/image | supported | native passthrough | visual message |
+| direct browser | unsupported | none | none |
+| direct MCP | unsupported | none | none |
+
+The matrix is a claim boundary, not feature discovery by name. Unsupported paths do not become supported merely because an output resembles JSON/HTML or contains a filesystem path.
+
+## Web/document path
+
+Existing web tool tests cover actual producer-owned HTTP behavior: request metadata, content/link metadata, Ollama→Tavily fallback, auth/API errors, invalid JSON, cancellation and timeout. Storeless Gateway adds no fetch callback and does not reinterpret headings/code or producer pagination/truncation metadata. A bounded R-E fixture confirms that `web_fetch` content remains byte-equivalent through observation.
+
+There is no storeless historical page reader. Producer truncation/pagination remains producer-owned, which is why web/document is `limited` rather than an archive-capable adapter.
+
+## Structured JSON
+
+No generic JSON parser/field selector is registered. A fixture containing the exact literal `9007199254740993123456789` remains opaque text and is not parsed into a JavaScript number, rounded, ranked or field-selected. Upstream pagination metadata is left on the producer result. A dedicated typed adapter requires a future concrete use case and precision contract.
+
+## Subagents
+
+The existing async-subagent result tool already emits a bounded summary plus paths to producer artifacts and explicitly avoids inlining raw logs. Its tests cover missing/running/completed states, structured result generation, artifact paths, cleanup and session lifecycle.
+
+P01-R does not read internal subagent history, does not turn an artifact path into an authorization grant and does not extend artifact lifetime. A completed path therefore remains `producer-managed`; it is not promised to survive producer cleanup/resume/export.
+
+## Visual and unsupported direct paths
+
+Image parts remain image parts and are accounted separately from text. No textual placeholder replaces them as a context optimization.
+
+P00 did not prove a direct parent Context Gateway boundary for browser DOM/network/console or a current direct MCP execution adapter. Both remain explicitly `unsupported`; R-E does not add placeholder adapters to make the matrix look complete.
+
+## Deterministic gate
+
+```text
+bun test \
+  test/context-gateway/storeless-format-contracts.test.ts \
+  test/lsp.test.ts \
+  test/web-search.test.ts \
+  test/async-subagents/tools.test.ts \
+  test/context-gateway/sdk-pipeline.test.ts
+```
+
+Result: **107 pass, 0 fail, 689 assertions**.
+
+Additional checks:
+
+- `npm run typecheck` — pass.
+- `git diff --check` — pass.
+
+No live model call, manual sync, user-config change or result-shaping adapter was added for R-E.

package/external/pi-tools-suite/docs/context-gateway-p01r-rf-evidence.md

@@ -0,0 +1,153 @@
+# Context Gateway P01-R / R-F evidence
+
+<!-- markdownlint-disable MD013 -->
+
+> Date: 7 September 2026.
+> Repository HEAD during deterministic gate: `daa1b06` with a dirty tested tree.
+> Scope: storeless lifecycle and current-result UI/replay only. No new persistent artifact service, native-temp reader endpoint, fork grant, export bundle, DCP lifecycle implementation or manual sync was added.
+
+## Runtime / transient lifecycle
+
+Context Gateway observe state is runtime-local. The current implementation tracks
+in-flight tool call IDs separately from aggregate telemetry and refuses an
+`off ↔ observe` mode change while any tool call is still in flight. At a safe
+boundary the mode change clears transient call bindings. `session_start`,
+`session_tree` and `session_shutdown` reset transient and aggregate observation
+state.
+
+Deterministic contracts additionally prove:
+
+- a mode change requested during an observed call is rejected until that result
+  completes; the result is attributed to the old effective observe epoch once;
+- lifecycle reset removes pending bindings and counters rather than carrying them
+  into a resumed/switched branch;
+- two Read/shell calls may complete in reverse order without crossing tool class,
+  parser command-scope or call identity;
+- an unbound result increments the explicit `unboundResults` counter but its
+  bytes/class/parser facts are not aggregated as current-session evidence;
+- extension reload during an in-flight SDK tool remains a separate P00 limitation
+  and is not hidden by telemetry; root tab/session generation guards keep a late
+  result owned by its origin tab.
+
+No suppression ledger is introduced, and no persisted JSONL message is rewritten
+when mode or session lifecycle changes.
+
+## TUI / current result rendering
+
+R-B already proves collapsed/expanded renderer equivalence for the exact
+Read/Bash/ast_grep metadata-normalization surfaces, including image preservation.
+The root renderer/session gate additionally covers:
+
+- shell running/nonzero/signal rendering;
+- LSP diagnostic severity rendering and mutation tool blocks;
+- truncated collapsed previews and expanded full current-result bodies;
+- persisted history tail/replay, unresolved/completed historical tool calls and
+  cancellation while older history is being prepended;
+- stale runtime/session event rejection and late tool-result binding to the
+  original inactive tab.
+
+These are current/persisted tool-result views; they are not a new route to the
+producer's full native temp output.
+
+## ACP / Desktop lazy current-result hydration
+
+Pix already has `pix/session/history`, `pix/session/tool_result` and deferred image
+hydration for Desktop. The lazy tool-result route is explicitly scoped by the ACP
+`sessionId` and the deferred result map created for that session. For a persisted
+result, the backend stores a trusted `sessionPath + byte offset + byte length`
+reference and materializes exactly that persisted JSONL message line on demand.
+
+The ACP contract now proves that requesting a deferred result:
+
+- does not replay or append a `session/update`;
+- returns the persisted current tool-result content/details only on explicit
+  hydration;
+- cannot be performed with another session's ID even when the tool call ID is
+  known;
+- frees the duplicate backend deferred copy after successful hydration.
+
+Desktop transcript logic keeps deferred results lightweight until expansion,
+hydrates them into the local transcript, and separately hydrates deferred image
+bodies. This is a human/UI operation; it does not create a new model tool result
+or provider input.
+
+## Native temp output: deliberate limitation
+
+There is **no existing authenticated host route that reads the contents of a
+`Read`/Bash/ast_grep native temp/full-output handle for TUI/ACP/Desktop**.
+`pix/session/tool_result` is not such a route: it reads a persisted JSONL result,
+not the producer's `fullOutputPath` contents.
+
+Therefore R-F adds no “open full native source” button or ACP endpoint. The UI may
+show the current result/status/diagnostics already available through the normal
+message path, but P01-R does not widen filesystem access merely because a result
+contains a temp path. R-C's lifetime limitations remain in force: temp paths can
+be absent, mutable, expired, or unavailable on error/timeout/abort and have no
+resume/fork/export guarantee.
+
+## Deterministic gates
+
+Context Gateway lifecycle/result gate:
+
+```text
+bun test \
+  test/context-gateway/observe.test.ts \
+  test/context-gateway/sdk-pipeline.test.ts \
+  test/context-gateway/metadata-normalization.test.ts
+```
+
+Result: **49 pass, 0 fail, 337 assertions**. Suite typecheck and `git diff --check`
+also pass for this gate.
+
+Root TUI/session gate:
+
+```text
+node --import tsx --test \
+  tests/conversation-tool-renderer.test.ts \
+  tests/tool-block-renderer.test.ts \
+  tests/conversation-shell-renderer.test.ts \
+  tests/session-history.test.ts \
+  tests/session-lifecycle-controller.test.ts \
+  tests/tabs-controller.test.ts
+```
+
+Result: **98 pass, 0 fail**.
+
+ACP lazy current-result gate:
+
+```text
+node --import tsx --test \
+  --test-name-pattern='desktop lazy session/load omits tool bodies and retrieves them on demand|desktop lazy session/load reuses an already-live tab runtime|deferred' \
+  test/agent.test.ts test/session-replay.test.ts
+npm run typecheck
+```
+
+Result: **4 pass, 0 fail**; ACP typecheck passes. The targeted lazy-result test
+also asserts no hydration `session/update` and denial for another session ID.
+
+An additional ACP boundary suite covers persisted lazy materialization and replay:
+
+```text
+node --import tsx --test \
+  test/session-replay.test.ts \
+  test/session-history-file.test.ts \
+  test/desktop-commands.test.ts
+```
+
+Result: **6 pass, 0 fail**. It additionally proves that the Desktop tool-result
+request surface is `sessionId + toolCallId` scoped, ignores arbitrary path-like
+extras, legacy persisted metadata is not retroactively normalized during replay,
+and deferred image/tool bodies are hydrated only from their existing persisted
+session references.
+
+Desktop gate:
+
+```text
+npm run check
+npm test -- src/lib/transcript.test.ts src/lib/acp-client.test.ts
+```
+
+Result: Desktop check has **0 errors** and two pre-existing Svelte accessibility
+warnings in `WorkspaceSidebar.svelte`; targeted tests are **28 pass, 0 fail**.
+
+No live model call or manual suite sync was used for R-F.

package/external/pi-tools-suite/docs/context-gateway-p01r-rg-evidence.md

@@ -0,0 +1,235 @@
+# Context Gateway P01-R / R-G storeless release evidence
+
+<!-- markdownlint-disable MD013 -->
+
+> Scope frozen before the R-G measurement gate on 7 September 2026.
+> Repository HEAD: `daa1b06`; tested source tree is dirty and earlier live run identities must not be inferred from HEAD alone.
+> This document does not authorise Context Gateway enforce mode or P02 durable storage.
+
+## Scope fixed before measurement
+
+The candidate storeless release is deliberately small:
+
+| Surface | Decision for R-G | Runtime effect |
+| --- | --- | --- |
+| Context Gateway observe | Keep available, `off` by default | Aggregate measurement/classification only; no result replacement or archive. |
+| `repo_*` Native Compact | Accept as explicit opt-in profile | Existing bounded native flags/cursors/validation; no store. |
+| `truncation-metadata-normalizer` | Accept as separate explicit opt-in module | Removes only proven duplicate truncation metadata for measured Read/shell/ast_grep shapes. |
+| test/build parser | Keep observe-only | Safe classification/metrics only; no result replacement. |
+| mutation/LSP | Native passthrough | Existing outcome/diagnostics behavior only. |
+| web/document | Native passthrough / limited | No second fetch, no archive. |
+| structured JSON | Native passthrough / limited | No generic parse/rewrite. |
+| subagent result | Native passthrough / producer-managed lifetime | No parent grant or lifetime extension. |
+| images | Native passthrough | No text replacement. |
+| direct browser / MCP | Unsupported | Not in the claimed denominator. |
+
+Provider-specific equality claims are limited to the installed OpenAI-completions
+serialization path already exercised by the deterministic harness. UI claims are
+limited to the current TUI result renderers and the existing ACP/Desktop lazy
+persisted-result flow. Native temp-output contents do not get a new UI/ACP reader.
+
+## Metrics and release criteria fixed before measurement
+
+R-G evaluates the following dimensions independently:
+
+- task/fact correctness and execution outcome;
+- initial delivered result bytes and all continuation/recovery calls;
+- JSONL/details bytes for metadata-only cleanup;
+- actual checked provider payload equality/usage rather than converting metadata
+  bytes into token estimates;
+- tool-call/refusal/retry counts and elapsed time for model-driven evidence that
+  already exists;
+- parser/capability CPU work through explicit scan/output bounds rather than a
+  claim based on one timing sample;
+- native temp/current-file/index lifetime limitations and unavailable recovery;
+- unsupported paths and failures remain in the report rather than being removed
+  from the denominator.
+
+There is no aggregate batch-budget claim. P00 proved stable per-call identity and
+source-order delivery, but not a host API that supplies a durable whole-batch
+budget before execution. Batch cost is therefore the sum of actual per-result
+traffic/calls in measurements.
+
+## Measurement results
+
+The measurements below were run after the scope and criteria above were written.
+
+### Native Compact deterministic paired corpus
+
+`PI_CONTEXT_GATEWAY_BENCHMARK_REPORT=1 bun test test/context-gateway/benchmark.test.ts`
+compares the historical baseline behavior with the current Native Compact profile
+over search, structure, AST, explain and dependency scenarios. All eight critical
+facts are recovered in both arms.
+
+| Metric | Baseline | Native Compact | Delta |
+| --- | ---: | ---: | ---: |
+| Delivered repo bytes including continuations | 71,025 | 27,519 | **-61.25%** |
+| Tool calls | 6 | 8 | +2 |
+| Continuation calls | 1 | 3 | +2 |
+| Refusals | 0 | 0 | 0 |
+| Full overrides | 0 | 0 | 0 |
+| Critical facts | 8/8 | 8/8 | equal |
+
+This is the expected trade-off for narrow native paging: substantially fewer
+delivered bytes, but potentially more calls. It is not evidence of lower total
+model cost by itself.
+
+### Historical model-driven paired evidence
+
+The retained `zai/glm-5.3` paired report
+`test/evals/artifacts/p01n-2026-09-07T17-30-21-479Z/p01n-paired-report.json`
+contains three Prompt Compact / Native Compact pairs; all **6 arm-runs passed**.
+It predates R-A v2 source/corpus identity, so R-G uses it only as historical
+model-behavior/cost evidence rather than pretending it certifies the current dirty
+tree byte-for-byte.
+
+| Aggregate metric | Prompt Compact | Native Compact | Delta |
+| --- | ---: | ---: | ---: |
+| Repo-result bytes | 1,286 | 983 | **-23.6%** |
+| All tool-result bytes | 9,737 | 9,149 | **-6.0%** |
+| Tool calls | 14 | 12 | **-14.3%** |
+| Parent tokens | 179,855 | 207,611 | **+15.4%** |
+| Parent cost | $0.0682 | $0.0923 | **+35.4%** |
+| Elapsed | 88.682s | 96.219s | **+8.5%** |
+| Native refusals / full overrides / refusal retries | 0 / 0 / 0 | 0 / 0 / 0 | equal |
+
+The live evidence therefore argues **against** making Native Compact the default:
+repo traffic improved, but total token/cost/latency did not consistently improve.
+It remains a useful explicit opt-in for workloads where repo-result volume is the
+binding constraint.
+
+### Metadata normalizer
+
+The normalizer changes only `details.truncation.content` on proven Read/shell/
+`ast_grep` SDK shapes. A deterministic 24,007-byte duplicate fixture measured:
+
+| Metric | Raw | Normalized | Delta |
+| --- | ---: | ---: | ---: |
+| Serialized tool-result JSON | 48,396 B | 24,376 B | **-24,020 B (-49.6%)** |
+| Ten identical persisted results | — | — | **240,200 B avoided** |
+
+The actual SDK fixtures in R-B also remove more than 40 KiB of duplicated metadata
+from large Read/Bash results while preserving visible content and structural
+truncation fields.
+
+This is deliberately reported as JSONL/metadata savings only. The installed
+OpenAI-completions serialization contract is byte-equivalent before/after cleanup
+because tool-result `details` are not serialized to that provider payload. R-G
+therefore claims **no token, cache or model-quality saving** from the normalizer.
+
+An additional 52,000-byte duplicate sample, matching the approximate size of the
+live observe residual details, measured `104,408 → 52,395 B` for the serialized
+tool-result object and `52,279 → 266 B` for `details`: **52,013 B** removed while
+visible content remained `52,035 B`. Seven reference-machine rounds of 10,000
+normalizer calls on that sample measured approximately `3.5–4.3 µs/call`. These
+timings are diagnostics, not a portable release threshold.
+
+### Residual and negative corpus
+
+The live observe-only residual run shows the measured large classes remain real:
+Read/Bash/ast_grep each delivered roughly 52 KiB of result content and roughly
+another 52 KiB of details at the checked boundary. The Bash task assertion failed
+because the model made an extra call; the large Bash observation itself remained
+valid. That failure stays visible rather than being removed from the denominator.
+
+R-A–R-F deterministic contracts cover the rest of the offline release corpus:
+
+- small/exact/control results and current-file Read continuation;
+- Unicode/CRLF/long-line and changed file/index behavior;
+- successful Bash/ast_grep native recovery plus missing/replaced temp output;
+- timeout/abort/nonzero and unavailable structured recovery handles;
+- parser middle failures, PASS→exit-1 conflict, ANSI/CR, mixed/compound commands,
+  unknown formats and a bounded 1 Mi-character parser scan;
+- mutation/LSP outcomes, web errors/cancellation, opaque large-integer JSON,
+  subagent producer-managed artifacts, image passthrough and unsupported browser/MCP;
+- late/reloaded/session-switched results, parallel calls and UI/history replay.
+
+The test/build parser is bounded but remains observe-only. Its prospective compact
+candidate is all-or-passthrough and must fit the configured result budget; no
+runtime result delivery, provider traffic, calls or token usage are changed by it.
+On a 4,550,063-character synthetic input the 1 Mi-character scan bound produced
+`scan-limited / partial`; seven rounds of 100 parses measured about
+`16.2–16.9 ms/call` on the reference machine. This is CPU/telemetry evidence only,
+not a shaping or provider-saving claim.
+
+## Live-run decision
+
+R-G does **not** request another live model run for the selected release scope:
+
+- the metadata normalizer is provider-invisible on the checked serializer and has
+  deterministic JSONL/provider equality contracts;
+- the test/build parser does not replace results;
+- mutation/LSP, web/JSON/subagent/image surfaces remain native passthrough;
+- Native Compact already has retained paired model-driven evidence, while all
+  post-run changes relevant to this scope are deterministic policy/validation
+  hardening rather than a new model-visible adapter.
+
+The R-A v2 recovery runner remains available for a future claim that specifically
+depends on exact model-driven native-handle recovery. Such a run still requires
+separate authorization and must create a new v2-identity report. R-G does not
+reinterpret the old v1 recovery reports as v2 passes.
+
+## Release decision
+
+Accept the verified storeless scope with conservative defaults:
+
+1. **Context Gateway stays `off` by default.** Observe remains an explicit passive
+   measurement mode; `enforce` remains unavailable.
+2. **Native Compact is accepted only as explicit opt-in.** Default
+   `repoDiscovery.profile` remains `baseline` because live total-cost evidence is
+   mixed despite lower repo-result traffic.
+3. **`truncation-metadata-normalizer` is accepted as a separate explicit opt-in.**
+   It remains disabled by default and claims JSONL/metadata reduction, not token
+   savings.
+4. **Test/build parsing stays observe-only.** No production compact-result adapter
+   is enabled without a proven recovery/lifetime contract for omitted data.
+5. **Mutation/LSP, web/document, JSON, subagent and visual paths remain their R-E
+   passthrough/limited decisions.** Browser/MCP direct adapters remain unsupported.
+6. **P02 durable store remains deferred.** R-G found no task requiring new durable
+   snapshot identity strongly enough to justify store/readers/quotas now.
+
+Rollback is configuration-only for future calls: disable the normalizer module,
+return `repoDiscovery.profile` to `baseline`, and/or set Context Gateway mode to
+`off`. Rollback does not delete session history, native temp files, user data or
+DCP state and does not require a manual sync operation.
+
+## Deterministic R-G gate
+
+The final gate reuses the independently proven R-A–R-F contracts rather than one
+monolithic test process where unrelated LSP/AgentSession suites can interfere with
+shared process/temp state. The required groups are:
+
+- Context Gateway/storeless contracts, Native Compact, recovery validator/corpus,
+  eval harness and coverage registry;
+- ACP lazy history/replay and typecheck;
+- root tab ownership/session UI contracts;
+- suite/root `git diff --check` and source typechecks.
+
+No new live model call, manual suite sync, durable store, reader tool or DCP change
+is part of the R-G release gate.
+
+The final external-suite P01-R gate is:
+
+```text
+bun test \
+  test/context-gateway \
+  test/repo-native-compact.test.ts \
+  test/repo-discovery.test.ts \
+  test/config.test.ts \
+  test/evals/extension-contracts.test.ts \
+  test/evals/harness.test.ts \
+  test/evals/recovery-corpus.test.ts \
+  test/evals/recovery-run-identity.test.ts \
+  test/evals/recovery-report.test.ts \
+  test/evals/recovery-validation.test.ts
+```
+
+Result: **144 pass, 0 fail, 1011 assertions**; suite typecheck and
+`git diff --check` pass. Root SDK pin remains `0.85.1`; generated schemas are
+unchanged when checked through `node --import tsx` (the sandbox blocks the normal
+`tsx` CLI IPC socket), and root `tsc --noEmit` passes.
+
+R-F's separate host/UI gates remain green: root TUI/session **98/98**, ACP lazy
+current-result **4/4** plus an additional **6/6** persisted-history/request-boundary
+suite and typecheck, and Desktop transcript/client **28/28** with Desktop check at
+zero errors (two pre-existing accessibility warnings).

package/external/pi-tools-suite/docs/subagent-model-pools.md

@@ -0,0 +1,109 @@
+# Sub-agent model pools
+
+Sub-agents primarily reduce the cost of bounded work and keep intermediate
+source, searches and logs out of the parent context. The parent owns planning,
+integration, decisions and the final answer. Actual savings depend on worker
+quality, retries and how much work the parent repeats; the configuration is
+not a price oracle.
+
+## Five execution modes
+
+- `research`: read-only evidence gathering, searches and independent diff review.
+- `implement`: bounded code, documentation, test and frontend changes.
+- `verify`: run checks and interpret logs, without fixing source or tests.
+- `browser-qa`: isolated browser workflow with assertions and visual artifacts.
+- `oracle`: a deliberate strong second opinion, not automatic worker escalation.
+
+Task-specific discipline belongs in the brief or `promptAppend`. A new project
+agent is warranted when it adds a durable contract, capabilities or resources,
+not merely a professional title. `verify` has a behavioral no-edit contract;
+shell access is not a read-only filesystem sandbox.
+
+## Agent priority, preset availability
+
+Each Markdown profile owns its ordered `models` list. This is one candidate
+chain for initial selection and subsequent quota fallbacks:
+
+```yaml
+---
+description: Make bounded implementation changes.
+models:
+  - zai/glm-5.3-flash
+  - openai-codex/gpt-5.6-terra
+  - openai-codex/gpt-5.6-luna
+thinking: medium
+---
+```
+
+A preset contains a set of available models, not a per-agent matrix:
+
+```jsonc
+{
+  "asyncSubagents": {
+    "presets": {
+      "gpt": {
+        "description": "Models available for this session",
+        "models": [
+          "openai-codex/gpt-5.6-luna",
+          "openai-codex/gpt-5.6-terra",
+          "openai-codex/gpt-5.6-sol"
+        ]
+      }
+    }
+  }
+}
+```
+
+The example agent selects Terra, not Luna: the agent's order wins. Sol is
+available in the pool but absent from this worker's chain, so it cannot become
+an automatic implementation fallback. The oracle can declare Sol in its own
+chain. Model references must be exact `provider/model` values, not wildcards.
+
+The resolver intersects the agent chain with the selected pool. Runtime
+selection then skips unregistered, unauthenticated or session-exhausted models.
+Tasks with images and browser QA require confirmed image support. The first
+eligible candidate runs; only the remaining eligible candidates are passed to
+quota fallback. An empty intersection or unavailable chain rejects the batch
+before any children or run state are created. Model selection makes no LLM
+completion request; the optional role router is a separate operation.
+
+Oracle prefers another provider when possible, but still respects the pool.
+It never substitutes an ordinary cheap candidate merely to avoid a selection
+error. A single-provider pool cannot promise cross-provider independence.
+
+Explicit task `model`, CLI `--model`, and `FORCE_CURRENT_MODEL` remain deliberate
+overrides: they bypass the pool and do not add automatic fallback candidates.
+The parent should not use these to evade the configured budget. The pool is
+a selection policy, not a security boundary against explicit overrides.
+
+## Selection and compatibility
+
+Use `/subagent-preset <name>`, `AGENTS_PRESET=<name>` or
+`/subagent-preset session <name>`. Clearing the preset uses agent priorities
+without a pool filter. The shipped names remain compatible with saved choices:
+`cheap` is the GLM pool, `gpt` the GPT pool, and `deep` the mixed pool. The last
+name no longer means that ordinary workers should escalate to flagship models.
+
+Old role names are not implicit aliases. `quick`, `scan`, `review`, `deep`,
+`docs`, `frontend`, and `tests` work only when explicitly defined as ordinary
+custom/project types. This keeps the effective catalog and accepted names exact.
+
+Legacy `model` plus `fallbackModels` and `modelByParent` still load. New profile
+`models` replaces inherited legacy selection fields; an explicit legacy model
+override can still replace an inherited new list. Empty `models` means no
+candidates, not permission to inherit the parent model. Model-less project
+specialists must declare candidates or receive an explicit model override.
+
+Legacy preset role matrices remain readable. A preset with `models` uses only
+the pool contract, dropping stale legacy model/thinking/type overrides. Switching
+a higher-priority config layer back to a legacy preset removes the inherited
+pool. Configuration loading never rewrites user files; review old overrides
+when migrating, since explicitly saved profiles can retain expensive models.
+
+## Compact handoff
+
+Give workers a scope, acceptance criteria and the evidence needed to start.
+Read compact results first and inspect raw artifacts selectively. One noisy
+sequential investigation can justify a worker; a command whose exit status is
+sufficient usually only needs a saved log, not another LLM. Independent review
+uses a fresh `research` invocation, not a separate built-in persona.