pi-ui-extend 1.0.40 → 1.0.41

package/external/pi-tools-suite/README.md

@@ -100,7 +100,13 @@ DCP settings are stored only under `dcp` in the user shared config file `~/.conf
       "nudgeFrequency": 1,
       "iterationNudgeThreshold": 6,
       "nudgeForce": "strong",
-      "protectedTools": ["compress", "write", "edit", "subagents"]
+      "protectedTools": ["compress", "write", "edit", "subagents"],
+      "autoCompress": {
+        "enabled": false,
+        "patience": 2,
+        "summarizerModel": [],
+        "timeoutMs": 20000
+      }
     },
     "strategies": {
       "emergencyCurrentTurnPruning": {
@@ -170,7 +176,11 @@ DCP settings are stored only under `dcp` in the user shared config file `~/.conf
 
 `minContextPercent` / `maxContextPercent` accept legacy fractions (`0.25`), percent strings (`"25%"`), or absolute token counts when Pi knows the current model context window. `minContextLimit` / `maxContextLimit` and `modelMinContextLimits` / `modelMaxContextLimits` are explicit absolute-or-percent aliases. `modelOverrides` and the `modelMin*` / `modelMax*` maps support exact model keys plus `*` / `?` wildcard patterns; matching is applied from generic to specific so exact bare-model matches override bare wildcards, and exact `provider/model` matches override provider wildcards. Array fields are union-merged, so model-specific `protectedTools` extend the defaults instead of replacing them. If `compress.protectUserMessages` is enabled, range compression appends selected user messages verbatim instead of rejecting the range; individual message compression still skips protected raw user messages. Protected tool outputs are copied into summaries for tools protected by name or `protectedFilePatterns`; protected `subagents` result reads also try to include the saved `result.md` artifact when available.
 
-`strategies.emergencyCurrentTurnPruning` is the default-enabled lossy safety floor for a single unfinished turn that has no normal compression candidate. DCP first emits emergency reminders and offers only safe old same-turn tool-result candidates. After `patience` ignored reminders, or at the model-independent `hardContextPercent`, it replaces eligible oldest result bodies until the estimated provider context reaches `targetContextPercent` or a margin below the model emergency threshold. User messages, configured/protected data, the newest `keepRecentToolPairs`, and results not present in an accepted provider request are never selected. The raw session transcript is unchanged. Setting `enabled` to `false` disables same-turn candidates and lossy pruning, but keeps the non-destructive emergency reminder.
+`compress.autoCompress.enabled` is `false` by default. When explicitly enabled, its `patience` counts completed correlated main-provider opportunities, not repeated context transforms; `summarizerModel: []` uses the bounded extractive fallback without a model call, while configured models share the single `timeoutMs` summarizer deadline. If that deadline expires, DCP still has a bounded finalization grace to commit the extractive fallback. Auto commit is accepted only when the full projected replacement has positive gain and meets the current budget-recovery target.
+
+`strategies.emergencyCurrentTurnPruning` is the default-enabled lossy safety floor for a single unfinished turn that has no normal compression candidate. DCP first emits emergency reminders and offers only safe old same-turn tool-result candidates. After `patience` completed ignored opportunities, or at the model-independent `hardContextPercent`, it replaces eligible oldest result bodies until the estimated provider context reaches `targetContextPercent` or a margin below the model emergency threshold. User messages, configured/protected data, the newest `keepRecentToolPairs`, and results without **completed** provider evidence are never selected. HTTP 2xx alone is not evidence; DCP promotes eligibility only after an unambiguously correlated successful finalized assistant response, and ambiguous retries/interleaving fail closed. The raw session transcript is unchanged. Setting `enabled` to `false` disables same-turn candidates and lossy pruning, but keeps the non-destructive emergency reminder.
+
+DCP sidecars are session-private versioned generation envelopes under `<sessionDir>/dcp-state/`. Saves use private atomic files, retain a last-valid `.prev` generation, validate payload/block-graph integrity on load, quarantine corrupt primaries, and use a cross-process exclusive lock rather than silent last-writer-wins. Live paused sessions are not deleted merely for age. Protected subagent artifacts are optional bounded recovery input: reads are async, rooted at the session cwd, reject symlink escapes and oversized files, and never silently truncate a required protected artifact.
 
 Set `dcp.debug: true` to write a JSONL debug log of DCP context/prune/compress events to `~/.pi/agent/dcp-debug.jsonl` (override the path with `PI_DCP_DEBUG_LOG`, or enable without config via `PI_DCP_DEBUG=1`); off by default. The log is size-limited and rotated: once it reaches `dcp.debugLog.maxBytes` (default `5242880` = 5 MB) it is renamed to `.1`, older backups shift down (`.1`→`.2`, …) and the oldest beyond `dcp.debugLog.maxBackups` (default `3`, minimum `1`) is dropped; override either with `PI_DCP_DEBUG_MAX_BYTES` / `PI_DCP_DEBUG_MAX_BACKUPS`.
 
@@ -427,21 +437,120 @@ Notes:
 
 ## Async sub-agents
 
-Sub-agent model routing normally follows task overrides, subagent type config, then `ASYNC_SUBAGENTS_MODEL` / `PI_SUBAGENTS_MODEL` fallbacks. Set `ASYNC_SUBAGENTS_FORCE_CURRENT_MODEL=1` (or `PI_SUBAGENTS_FORCE_CURRENT_MODEL=1`) to ignore task/config/env model choices and launch every sub-agent with the current parent session model. When this flag is enabled, any `--model` entries in sub-agent extra args are stripped so they cannot override the current model.
+Model selection uses the ordered candidates from each agent's Markdown file,
+filtered by the selected preset's available models and runtime capabilities.
+Explicit task/CLI model overrides bypass the pool. Setting
+`ASYNC_SUBAGENTS_FORCE_CURRENT_MODEL=1` (or
+`PI_SUBAGENTS_FORCE_CURRENT_MODEL=1`) deliberately selects the parent model and
+strips conflicting model arguments; this is not the economical default.
+
+The five built-in modes are `research` (read-only evidence and independent
+review), `implement` (bounded code, docs, tests, or UI changes), `verify`
+(run checks and diagnose logs without fixing files), `browser-qa` (trusted
+browser workflow), and `oracle` (deliberate strong second opinion).
+Ordinary workers use economical model candidates; no built-in parent-tier
+rule promotes them to a flagship. Oracle is the exception, not an automatic
+retry for difficult work. Task-specific discipline belongs in the brief.
+
+Delegate when a suitable lower-cost worker can handle bounded work or noisy
+intermediate evidence should stay outside the parent context. One sequential
+task can qualify. Keep decisions and integration in the parent; read compact
+results and verify selectively rather than repeating the worker's investigation.
+Do trivial reads/edits directly. Redirect a noisy command to a log without an
+extra LLM when no interpretation is needed. `verify`'s no-edit instruction is
+a behavioral contract, not a read-only filesystem sandbox for its shell.
+
+Run `/ultrawork` or `/ulw` for orchestration, `/hyperplan` to pressure-test a
+plan, or set `ULTRAWORK=1` to apply the orchestration prompt to normal inputs.
+`ULTRAWORK_AUTO=1` classifies only the first normal input on non-GPT parents;
+GPT-like parents skip that automatic transform, not ordinary delegation.
+
+See [Model pools and migration](docs/subagent-model-pools.md) for the selection
+contract, configuration examples, override rules and legacy compatibility.
+
+### Parent-first role selection
+
+The parent normally selects an explicit `subagentType` from the effective
+system-prompt catalog, preferring a matching project-local specialist. Valid
+explicit types bypass the LLM router entirely; presets, model selection, tools,
+skills, and role instructions are still applied by the normal config resolver.
+Model/thinking overrides are not substitutes for selecting a role.
+
+The router remains enabled as a fallback for omitted types: use it when the role
+is unclear or the user explicitly requests automatic routing. Only omitted
+tasks are classified, in one batch; the parent's explicit choices are preserved.
+Real-browser QA still requires explicit `subagentType: "browser-qa"`.
+
+Unknown explicit types and failed/incomplete automatic routing reject the
+**entire spawn batch before run state or child processes are created**. The tool
+returns an error with affected task IDs and available types; the parent should
+correct the roles and resubmit the whole batch. Provider error responses are
+failures too, not successful routes. Configured fallback router models may be
+tried, but missing routes are never silently replaced with `quick`/`defaultType`.
+
+With `routing.enabled: false`, every spawn task must supply a valid explicit
+type. `defaultType` remains a preference for genuinely ambiguous LLM choices
+and a legacy config-resolver default, not a spawn error fallback. Existing
+callers relying on an implicit default must now choose a type explicitly.
+
+### Project-local agents (`.pi/agents/*.md`)
+
+A project can ship sub-agent roles as individual Markdown files in
+`<project>/.pi/agents/`. The first such directory found walking up from the
+session cwd is used; each top-level `*.md` file becomes a `subagentType` named
+after the file. Parent and router see the short `description`; only the child
+receives the Markdown body. A project's ordered `models` are filtered through
+the same active preset pool as built-in agents.
+
+```markdown
+---
+description: Use for reviewing this repo's diff — knows the house rules.
+icon: eye
+models:
+  - zai/glm-5-turbo
+  - openai-codex/gpt-5.6-luna
+thinking: low
+tools: read, grep
+retry:
+  maxRetries: 1
+  backoffMs: 2000
+---
+
+You are this project's staff reviewer. Apply the repo rules from
+AGENTS.md before approving anything; cite file paths first.
+```
 
-For an oh-my-openagent-style workflow, run `/ultrawork` or `/ulw` to ask the parent agent to split broad work into configured async-subagents roles (`quick`, `scan`, `research`, `docs`, `frontend`, `browser-qa`, `implement`, `tests`, `review`, `deep`, `oracle`). Set `ULTRAWORK=1` before launching Pi to apply that compact routing prompt to normal non-slash user inputs automatically. Set `ULTRAWORK_AUTO=1` to ask the lightweight router model to classify only the first normal user input on non-GPT parent models: clear broad/parallel work is transformed into ultrawork, vague potentially-complex work gets a soft delegation hint, and narrow work is left unchanged. GPT-like parent models skip only this automatic transform; they can still use `/ultrawork` and `subagents` normally. `frontend` is for UI/UX, styling, layout, responsive behavior, and visual component polish; `browser-qa` reproduces browser bugs and proves fixes with deterministic assertions plus screenshot/video/trace evidence; `review` covers security/performance/audit tracks; `implement` covers refactors; `deep` covers debugging/root-cause; `oracle` is for sparse cross-provider second opinions on high-stakes uncertainty. Run `/hyperplan` to pressure-test a plan before implementation.
+- Frontmatter keys: `name` (must match the filename), `description`, `icon`, `models`, `thinking`, `tools`, `isolatedSkills`, `extraArgs`, `promptAppend`, `promptOverride`, `retry`, `maxResultBytes`, `timeoutMs`. Legacy `model`, `fallbackModels`, and `modelByParent` still load. Unknown keys are rejected with an error naming the file.
+- Array fields accept block lists (`- item`), inline arrays (`[a, b]`), or comma-separated strings (`tools: read, grep, bash`). The frontmatter YAML subset is intentionally small: scalars, quoted strings, numbers, comments, lists, and nested maps for `modelByParent`/`retry`. Tabs, block scalars (`|`/`>`), anchors/aliases, and flow maps are hard errors naming file and line.
+- The markdown body becomes `promptAppend`: it is appended after the standard generated prompt (parent objective + task + output format), so the agent still receives its task in the usual structure. Use frontmatter `promptOverride` for full prompt replacement.
+- Precedence: project agent fields override same-named types from user/project JSONC config (field-level; other fields are kept), which in turn override built-ins. Setting `ASYNC_SUBAGENTS_CONFIG` / `PI_SUBAGENTS_CONFIG` disables the directory (explicit config = full control).
+- Files without frontmatter are skipped (a `README.md` there is fine). Definition loading is uncached: edits apply on the next config read/spawn without a restart, and the effective system-prompt catalog is rebuilt at parent-agent start.
+- Bundled roles use the same format internally under `src/async-subagents/agents/*.md`; built-in and project-local profiles therefore share one parser and normalization path instead of maintaining a second role-description schema in TypeScript.
+- `icon` names an agent glyph for UIs that render sub-agent widgets (pix TUI panel, Pix Desktop subagents panel): `agent` (neutral default), `search`, `code`, `flask`, `globe`, `sparkles`, `brain`, `wrench`, `terminal`, `bug`, `book`, `eye`, `zap`, `rocket`. The value is passed through opaquely; unknown names render as the neutral agent icon, and status stays color-coded next to it.
 
 ### Private browser QA and project auth
 
 The built-in `browser-qa` role runs on `zai/glm-5.3-flash`, with
-`openai-codex/gpt-5.6-luna` as its fallback. Its browser
-workflow is an explicit private skill under `src/async-subagents/private-skills/`,
-outside normal Pi skill discovery. The role's first-class `isolatedSkills` setting launches the child with
-`--no-skills` plus one self-contained private workflow. It bundles the relevant
-scenario-design, locator, waiting, assertion, evidence, and cleanup guidance next
-to its trusted runner, so browser QA does not depend on a separately installed
-skill or CLI. The private workflow remains mandatory when configuration appends
-other isolated skills; parent and ordinary sub-agent sessions do not discover it.
+`openai-codex/gpt-5.6-luna` as its fallback. Its complete workflow and detailed
+scenario-design guidance live in the Markdown body of
+`src/async-subagents/agents/browser-qa.md`. The normal profile loader appends
+that body to the QA child's task prompt; the parent and LLM router receive only
+the short `description`. There is no additional QA skill to discover or read.
+
+Executable resources live under `src/async-subagents/agents/browser-qa/`.
+The launcher supplies the installed runner's absolute path in
+`PI_BROWSER_QA_RUNNER`; the child invokes `node "$PI_BROWSER_QA_RUNNER"` from
+the delegated project's cwd. This non-secret path is set only for QA children.
+QA always launches with `--no-skills`, even when `isolatedSkills` is empty,
+and skill flags in `extraArgs` cannot bypass that isolation. Explicitly
+configured `isolatedSkills` remain supported as optional additions; no built-in
+QA `--skill` is injected. Other roles retain their normal discovery behavior.
+
+Model/thinking/tool-only profile overrides inherit the Markdown workflow.
+An explicit profile `promptAppend` replaces the inherited body under the usual
+field-level merge rules; custom QA instructions must preserve the runner-only,
+credential, target, and evidence contracts. Runner-enforced isolation and
+credential handling remain in code, not in the prompt.
 
 Public browser QA does not require an auth profile or `.pi/qa_auth.jsonc`: run it
 with an explicit base URL, whose exact origin becomes the fail-closed allowlist.
@@ -498,8 +607,8 @@ creating a template. Only an explicit authenticated request may create the
 private template. Missing, rejected, or expired selected auth returns
 `QA_AUTH_UPDATE_REQUIRED`, naming only the profile/file/reason needed for the
 parent to ask the user for an update and rerun. See
-`src/async-subagents/private-skills/browser-qa/references/qa-auth.example.jsonc`
-for complete profile shapes and `references/qa-flow.example.jsonc` beside it for
+`src/async-subagents/agents/browser-qa/examples/qa-auth.example.jsonc`
+for complete profile shapes and `examples/qa-flow.example.jsonc` beside it for
 the declarative, non-executable QA action/assertion format.
 
 Browser QA videos automatically visualize pointer interactions. Clicks and
@@ -514,68 +623,92 @@ Async-subagents also injects a lightweight oh-my-openagent-style system-prompt s
 
 For blind-model screenshot/image inspection, use the main-session `coding-discipline` lookup tool; the bundled default uses vision-capable `zai/glm-5.3-flash`. Async-subagents still supports `imagePaths` on tasks when a broader delegated track genuinely needs images, but it no longer ships a dedicated `vision` role. Dynamic provider capabilities can be missing or stale after switching models, so blind parent models can still be configured explicitly with case-insensitive `*` masks under `asyncSubagents.vision.blindModelPatterns` in `~/.config/pi/pi-tools-suite.jsonc`; do not include `zai/glm-5.3-flash` because it accepts image input. This keeps guidance honest, not a sub-agent role.
 
-When a task omits `subagentType`, async-subagents asks a lightweight router model to choose one configured type for each task from the task text/scope and the `types.<name>.description` metadata. Explicit task `subagentType` still wins. Keep type descriptions short, literal, and distinct because they are inserted into the router prompt for a small model. Router settings live under `asyncSubagents.routing` (`enabled`, `model`, `maxTaskChars`, `maxTokens`, `maxRetries`, `timeoutMs`, `debug`); the default router model is `zai/glm-4.5-air`. If the router is disabled, unavailable, aborted, or returns invalid JSON, omitted types fall back to `defaultType`.
-
-Define optional `presets` under `asyncSubagents` in `~/.config/pi/pi-tools-suite.jsonc`, `$PI_CONFIG_DIR/pi-tools-suite.jsonc`, or project `.pi/pi-tools-suite.jsonc`, then use `/subagent-preset` or `/subagent-preset-config` to pick one persistent active preset for future spawns across all sessions. Set `AGENTS_PRESET=<name>` before launching Pi to override the saved preset for only the current process/session without changing the saved selection. If Pi is already running, use `/subagent-preset session <name>` for the same process-only override, and `/subagent-preset session-clear` to remove that runtime override. The TUI only selects presets already present in config; it does not edit JSON. If no `asyncSubagents` section exists, run `/subagent-preset init` to insert the bundled sample from `src/async-subagents/async-subagents.sample.jsonc` into the shared config (or to copy a standalone override file when `ASYNC_SUBAGENTS_CONFIG` / `PI_SUBAGENTS_CONFIG` is set). Existing config sections/files are never overwritten. Presets select an agent/model configuration: they can provide global fallback `model`/`thinking`/`extraArgs` and per-role overrides under `asyncSubagents.presets.<name>.types.<subagentType>`. They can also provide ordered `fallbackModels` globally or per-role; when a sub-agent fails with quota/rate-limit errors such as 429, async-subagents immediately tries the next fallback model and remembers the exhausted provider for the current Pi process/session, so later spawns skip that provider until Pi exits. This is intended for provider-level fallback chains such as `antigravity/* → openai-codex/* → zai/*` or `openai-codex/* → zai/*`; omit fallbacks for effectively unlimited providers. Antigravity account rotation has priority over preset fallback: async-subagents only falls back after Antigravity reports that all configured accounts are exhausted for that model. Explicit task model overrides and force-current-model disable preset fallback for that task. The active preset name is stored separately in `~/.pi/agent/subagent-preset-selection.json`.
+When `subagentType` is omitted, the lightweight role router classifies the task
+using the descriptions. Explicit types bypass it. Unknown types or failed
+routing reject the batch, never substitute `defaultType`. Choosing a worker
+model from its candidate list does not involve an LLM call.
+
+### Presets are available-model pools
+
+Each agent declares an ordered `models` list in Markdown. A preset declares
+which model references may be used, not another role/model/thinking matrix.
+Selection preserves agent order, intersects it with `preset.models`, checks
+runtime registration/auth availability, and takes the first usable candidate.
+Pool order does not change preference and pool-only models are never appended.
+Without a preset, the full agent list is eligible. Candidate order expresses
+the configured budget preference; runtime does not infer current API prices.
+
+Image-bearing tasks and `browser-qa` require confirmed image support; configured
+blind-model masks override runtime image metadata. Remaining eligible models
+form the quota fallback chain, so neither quota history nor image fallback can
+escape the pool. Antigravity account rotation still happens before provider
+fallback. No match, no usable model, or an explicitly empty list rejects the
+whole batch before run directories or child processes are created. A new custom
+agent must supply candidates instead of silently inheriting the parent model.
+
+Oracle uses its separate strong-model list and prefers another provider when
+available, but also respects the pool. A same-provider choice is allowed when
+the pool offers no alternative; cross-provider independence is not guaranteed.
+Explicit task/CLI model overrides and `FORCE_CURRENT_MODEL` remain deliberate
+escape hatches and disable automatic model fallback for that task. They do not
+bypass the image-capability check.
+
+Define pools in the shared or project `pi-tools-suite.jsonc`. Select a saved
+pool with `/subagent-preset`; use `AGENTS_PRESET=<name>` or
+`/subagent-preset session <name>` for a process-only override and
+`/subagent-preset session-clear` to remove it. The saved selection lives in
+`~/.pi/agent/subagent-preset-selection.json`. `/subagent-preset init` inserts the
+sample only when config is missing. The shipped pools are `cheap` (GLM), `gpt`,
+and `deep` (the retained legacy name for the mixed pool, not worker escalation).
+Initial user config and the sample share one source; descriptions and worker
+model order exist only in the agent files. Existing user files are not rewritten.
 
 Example shared async-subagents config section:
 
 ```jsonc
 {
   "asyncSubagents": {
-    "defaultType": "quick",
+    "defaultType": "research",
     "routing": {
       "enabled": true,
-      "model": "zai/glm-4.5-air",
+      "model": "zai/glm-5-turbo",
       "timeoutMs": 12000
     },
     "presets": {
       "cheap": {
-        "description": "Use GLM by role, including GLM-5.3 Flash for multimodal work.",
-        "types": {
-          "quick": { "model": "zai/glm-5.3", "thinking": "off" },
-          "frontend": { "model": "zai/glm-5.3-flash", "thinking": "medium" },
-          "browser-qa": { "model": "zai/glm-5.3-flash", "fallbackModels": ["openai-codex/gpt-5.6-luna"], "thinking": "low" },
-          "review": { "model": "zai/glm-5.3", "thinking": "high" }
-        }
+        "description": "GLM workers with a strong oracle candidate.",
+        "models": ["zai/glm-5-turbo", "zai/glm-5.3-flash", "zai/glm-5.3"]
       }
     },
     "types": {
-      "frontend": {
-        "description": "Use for frontend UI/UX visual work: styling, layout, typography, animation, responsive states, component polish, accessibility. Avoid backend/business logic unless needed for UI behavior.",
-        "thinking": "medium"
-      },
-      "review": {
-        "description": "Use for review/audit of existing code or changes: correctness, security, performance, maintainability, API risks, quality. Do not implement new code.",
-        "thinking": "high"
+      "research": {
+        "models": ["zai/glm-5-turbo", "openai-codex/gpt-5.6-luna"],
+        "thinking": "low"
       }
     }
   }
 }
 ```
 
-### Parent-model-aware model selection (`modelByParent`)
-
-Any type profile can carry `modelByParent`: a map from glob model refs (matched against the **current parent model**, e.g. `"zai/*"`) to a model for that role. The first matching key wins. Values may be a model string or `{ "model": "...", "fallbackModels": [...] }`. It is resolved after an explicit task `model` / `forcedModel`, but **before** the preset/static profile `model`, so a role can always pick a model based on who the parent is — independent of the active preset.
-
-The canonical use case is an **`oracle`** role that consults a flagship model from a *different* provider than the parent for a second opinion:
-
-```jsonc
-"oracle": {
-  "description": "Cross-provider second opinion: consult a flagship from a different provider than the parent to pressure-test a hard decision. Read-only; advise, do not edit.",
-  "model": "openai-codex/gpt-5.6-sol",
-  "fallbackModels": ["zai/glm-5.3"],
-  "thinking": "max",
-  "modelByParent": {
-    "zai/*":         { "model": "openai-codex/gpt-5.6-sol", "fallbackModels": ["zai/glm-5.3"] },
-    "openai-codex/*": "zai/glm-5.3",
-    "antigravity/*": { "model": "zai/glm-5.3", "fallbackModels": ["openai-codex/gpt-5.6-sol"] },
-    "anthropic/*":   { "model": "openai-codex/gpt-5.6-sol", "fallbackModels": ["zai/glm-5.3"] }
-  }
-}
-```
-
-With this config a GLM parent (`zai/*`) spawns the oracle on `gpt-5.6-sol`, a GPT parent (`openai-codex/*`) spawns it on `glm-5.3`, and so on — automatically, at spawn time, with no `task.model` needed. The parent model ref is read from the spawn context (`ctx.model`) and passed into resolution. Pattern matching is case-insensitive `*` glob (same engine as `vision.blindModelPatterns`). When no key matches (or no parent model is known), the role falls back to its static `model` + `fallbackModels`. An explicit `task.model` or `ASYNC_SUBAGENTS_FORCE_CURRENT_MODEL=1` still overrides the match.
+### Legacy configuration compatibility
+
+Old built-in role names are no longer implicit aliases. `quick`, `scan`,
+`review`, `deep`, `docs`, `frontend`, and `tests` are valid only when explicitly
+defined as ordinary custom/project types. Old preset per-role keys likewise
+apply only when a type with that exact name exists.
+
+Legacy `model` plus `fallbackModels` remains readable. `models` is a complete
+replacement list: it clears inherited legacy model/fallback/parent routing.
+A later old-format model override still replaces the primary candidate, and a
+later `fallbackModels` replaces the remaining candidates; `[]` disables them.
+Old `modelByParent` configs remain supported, but ordinary roles give legacy
+preset models precedence. New built-ins contain no parent-tier escalation maps.
+
+When a preset specifies `models`, it is exclusively a pool; inherited legacy
+`model`, `types`, thinking, arguments and timeout overrides do not run. A later
+explicit old-format preset selector can still replace a pool for compatibility.
+Runtime retry structures and the separate role router continue to use the
+term `fallbackModels` for actual fallback-only lists, not agent candidates.
 
 Sub-agents run with `--no-session` by default to avoid writing duplicate Pi session JSONL files for fire-and-forget background work. Set `ASYNC_SUBAGENTS_ENABLE_SESSIONS=1` to restore persisted per-agent sessions under each agent's `sessions/` directory; this also registers the session-navigation slash commands (`/sub-open`, `/sub-back`, `/sub-where`) needed for switching and deeper post-mortem navigation.
 

package/external/pi-tools-suite/docs/browser-qa-subagent.md

@@ -4,25 +4,32 @@
 
 Provide a cheap, fast `browser-qa` async-subagent that reproduces browser bugs
 and proves fixes with deterministic assertions plus screenshot, video, and trace
-evidence. The role uses `zai/glm-5.3-flash`, falling back to
-`openai-codex/gpt-5.6-luna`.
-
-## Private skill isolation
-
-- The browser QA skill lives under `src/async-subagents/private-skills/`, outside
-  Pi's normal skill discovery roots.
+evidence. Its ranked `models` list prefers `zai/glm-5.3-flash`, then
+`openai-codex/gpt-5.6-luna`, filtered by the active preset's model pool and
+confirmed runtime image support.
+
+## Inline agent workflow and skill isolation
+
+- All operating instructions, flow contracts, scenario-design guidance, and
+  auth-scaffolding rules live in `src/async-subagents/agents/browser-qa.md`.
+  Its body becomes the QA child's `promptAppend` through the shared agent
+  loader. Parent and router catalogs include only its short `description`.
+- Runner code, vendor dependencies/licenses, and optional JSONC examples live
+  under `src/async-subagents/agents/browser-qa/`; none is a discoverable skill.
 - Sub-agent processes disable normal extension discovery, then always load the
-  suite's model-tools and Antigravity provider extensions explicitly, regardless
-  of the selected model. This keeps the process isolated without making any
-  Antigravity-backed role unavailable.
+  suite's model-tools extension. They load the Antigravity provider extension
+  only when an Antigravity model is explicitly selected.
 - A type profile may declare `isolatedSkills`. Spawning that profile adds
   `--no-skills` followed by one explicit `--skill` per configured path.
-- The `browser-qa` profile always loads one self-contained private workflow.
-  Relevant browser-test design guidance is bundled beside its trusted runner;
-  no separately discovered skill or browser CLI is required. Configuration may
-  append isolated skills but cannot remove the mandatory private workflow.
-- Other sub-agent profiles and the parent session must not discover the private
-  skill automatically.
+- `browser-qa` always disables normal skill discovery and filters skill flags
+  out of `extraArgs`, even without configured skills. It no longer injects a
+  mandatory QA skill. Explicitly configured skills are optional additions.
+- The launcher sets `PI_BROWSER_QA_RUNNER` to the absolute installed runner path,
+  replacing inherited values, and strips it from ordinary child environments.
+  QA invokes `node "$PI_BROWSER_QA_RUNNER"` without guessing paths from cwd.
+- Model-only profile overrides inherit the workflow. An explicit profile
+  `promptAppend` replaces the body like any other agent profile; it is not an
+  immutable security boundary. Runtime protections remain in the runner.
 
 ## Authentication contract
 
@@ -98,7 +105,7 @@ evidence. The role uses `zai/glm-5.3-flash`, falling back to
 
 ## Reliability and shutdown contract
 
-- The built-in `browser-qa` profile has a 120-second wall-clock budget unless
+- The built-in `browser-qa` profile has a 300-second wall-clock budget unless
   the caller explicitly supplies a task or spawn timeout. This bounds model
   stalls as well as browser work.
 - The trusted runner has its own bounded lifecycle. Browser launch, context
@@ -124,11 +131,14 @@ evidence. The role uses `zai/glm-5.3-flash`, falling back to
 
 ## Acceptance criteria
 
-1. `browser-qa` resolves to the intended model/fallback and its self-contained
-   private workflow, and its isolated child process can register the configured
+1. `browser-qa` resolves to the intended model/fallback and its inline Markdown
+   workflow, and its isolated child process can register the configured
    model provider.
-2. Spawn args contain `--no-skills` and the mandatory private skill for this
-   profile; ordinary profiles retain existing skill discovery behavior.
+2. Default QA spawn args contain `--no-skills` but no `--skill`. The child
+   receives the full workflow in its initial prompt and can invoke the bundled
+   runner through `PI_BROWSER_QA_RUNNER` from an unrelated project directory.
+   Optional configured skills still load; ordinary profiles retain existing
+   skill discovery behavior and do not receive QA-only environment paths.
 3. Auth profile listing and all error output are redacted; model-authored input
    cannot execute code in the credential-bearing process.
 4. Runner tests cover public execution without an auth file, explicit profile

package/external/pi-tools-suite/docs/context-gateway-p00-adr.md

@@ -0,0 +1,216 @@
+# Context Gateway P00 ADR: tool-result stage ordering
+
+<!-- markdownlint-disable MD013 -->
+
+> Status: accepted implementation decision for future Context Gateway work.
+> This ADR does not enable Gateway, change user configuration, or certify rollout.
+> Evidence baseline: repository `daa1b06`, installed Pi SDK `0.85.1`, 7 September 2026.
+
+## Context
+
+The installed extension runner chains `tool_result` handlers in registration
+order. The suite currently has four independent `tool_result` registrations:
+LSP, comment-checker, DCP, and the opt-in credential firewall. Their module load
+order is LSP → comment-checker → DCP → credential firewall.
+
+That order is unsuitable for Gateway enforce mode:
+
+- mutation diagnostics must be present before Gateway renders a bounded result;
+- session-hygiene redaction, when enabled, must happen before durable capture;
+- Gateway must shape before DCP records the delivered result;
+- changing the global `MODULES` order would also change unrelated lifecycle and
+  provider hooks, including the intentionally late provider firewall.
+
+P00 tests also prove that throwing from a result handler is fail-open, and that
+an in-flight extension tool can cross an extension reload: the old wrapper then
+fails on its stale runner while the new runner handles the resulting error.
+Therefore current active-runner state is not an origin binding.
+
+## Decision
+
+For the current **P01-R storeless scope**, keep the existing independent
+`tool_result` chain. A suite-local coordinator is **not** introduced merely to
+make the architecture look uniform. It becomes conditional future work only if
+a store-backed/enforce stage is authorised and a concrete conflict between
+enabled suite-owned result handlers cannot be expressed safely through the
+verified event-specific order.
+
+The verified storeless order is:
+
+1. LSP and comment-checker result enrichers.
+2. Context Gateway `observe` (passive; no result patch).
+3. Optional `truncation-metadata-normalizer` (details-only duplicate cleanup).
+4. Other downstream result observers/modifiers; the current legacy DCP happens
+   to be in this position but P01-R does not depend on DCP state or persistence.
+5. Opt-in credential-firewall session-hygiene redaction.
+
+For provider hooks, credential-firewall redaction runs before
+`codex-reasoning-fix`, and `codex-reasoning-fix` remains the final
+`before_provider_request` sanitizer.
+
+This order is covered both by the `MODULES` contract and by an executable
+`ExtensionRunner` chain with a DCP-free fake downstream observer. The optional
+normalizer removes only redundant metadata; the later firewall still owns secret
+redaction. With firewall session hygiene disabled, the normalizer does not redact
+or otherwise alter visible content.
+
+If a future enforce/store stage is authorised, the previously proposed
+coordinator remains the candidate design: modules participating in it must not
+also register an independent `tool_result` handler, while their non-result hooks
+remain registered normally. That future decision must be revalidated against the
+then-current DCP/session-recovery implementation rather than copied mechanically
+from the legacy chain.
+
+The **future enforce coordinator candidate** order is:
+
+1. **Enrich** — LSP mutation diagnostics, then comment-checker output.
+2. **Session-hygiene sanitize** — the credential-firewall tool-result transform
+   when that existing opt-in policy is enabled.
+3. **Gateway sanitize/capture/render** — apply Gateway's archive-specific
+   permitted-snapshot sanitizer, consume any trusted pre-truncation capture
+   handle, publish if policy requires it, and return passthrough/exact/compact/
+   degraded delivery.
+4. **DCP observe** — record only the result that will be delivered after the
+   preceding stages.
+
+The credential firewall's `before_provider_request` hook stays in its existing
+late provider position. `codex-reasoning-fix` remains the last provider-payload
+sanitizer. The coordinator is event-specific; it is not a replacement for
+global module ordering.
+
+### P01-R storeless ordering before any coordinator exists
+
+The accepted coordinator above is conditional future **store-backed enforce**
+work. P01-R does not add it merely to clean redundant SDK metadata. The checked
+storeless path keeps independent handlers and the current suite registration
+order:
+
+1. suite-owned result enrichers such as LSP/comment-checker;
+2. Context Gateway `observe`, which records the original result boundary and
+   does not transform it;
+3. optional `truncation-metadata-normalizer`, which may remove only a proven
+   duplicate `details.truncation.content` while preserving the delivered body,
+   outcome and every other details field;
+4. downstream result observers. The R-B contract uses a fake observer with no
+   DCP imports so this boundary is not coupled to the current or future DCP
+   implementation;
+5. optional credential-firewall `tool_result` hygiene, which remains the
+   security transform for delivered result content/details when that module is
+   enabled;
+6. provider hooks later run in their normal order: credential firewall before
+   the final `codex-reasoning-fix` payload sanitizer.
+
+This ordering intentionally lets `observe` measure the pre-cleanup metadata
+boundary. The normalizer is not a security boundary and does not restore or
+create source bytes. If firewall hygiene is enabled after it, secrets still
+present in delivered content/remaining details are redacted before JSONL/next
+provider context. When hygiene is disabled, the normalizer must not silently
+pretend those bytes were redacted.
+
+The normalizer's tool-name/SDK-shape allowlist is a compatibility guard, not
+trusted provenance. `tool_result` carries no authenticated extension owner, so
+a replacement tool can reuse `Read`/shell/`ast_grep` names. Exact duplicate
+cleanup can remain semantics-preserving while all stronger capability/lifetime
+claims for such a replacement stay **limited**. A future capture/store path
+cannot use this name/shape test as permission to open a path or publish a
+snapshot.
+
+R-B does **not** introduce a coordinator because no conflict requiring one is
+present in the storeless path. Existing tests prove independent handler
+composition, exception fail-open behavior and the fact that a later extension
+can reinsert raw content. Therefore hard enforce remains unsupported; if a
+future store-backed stage needs different security ordering, it must implement
+the event-specific coordinator without leaving duplicate independent result
+registrations active.
+
+## P01-R same-name replacement limitation
+
+The metadata normalizer can conservatively reject unknown tool names and
+malformed/non-matching truncation metadata, but the generic `tool_result` event
+does not carry a cryptographic or host-owned identity proving which tool
+definition produced a result. A separately loaded replacement that deliberately
+uses a measured name such as `read` plus the exact SDK truncation shape is
+therefore **not independently provenance-certified** by name+shape alone. P01-R
+support claims are limited to the verified suite/SDK tool combinations. Strict
+enforce must not generalise this heuristic to arbitrary replacements without a
+host-owned tool-definition identity seam.
+
+## Failure contract
+
+Gateway stage failure must not rely on `throw`. A Gateway failure returns an
+explicit bounded degraded result that preserves the real execution outcome and
+states that archival/retrieval is unavailable. A successful mutation must never
+be reported as "not executed" merely because publication failed.
+
+Enrichment or optional session-hygiene failures keep their existing semantics
+until their coordinator adapters are implemented and tested. DCP observation
+must never be allowed to restore a raw source after Gateway shaping.
+
+## Origin binding and reload
+
+`toolCallId` is necessary but not sufficient. Gateway execution identity must
+also bind the originating session/workspace and attempt/runtime epoch before an
+await boundary. The active tab or current extension runner after execution is
+not authoritative.
+
+The installed SDK currently makes extension reload during an in-flight custom
+tool a limited path: `wrapRegisteredTool()` touches the old runner after the
+tool returns and can turn the original completion into a stale-runner error.
+Gateway strict-enforce support for such cross-reload executions is therefore
+**not claimed**. Wrapper-level capture may preserve permitted bytes as an
+orphaned source, but it must not fabricate a successful delivered result.
+
+At the app layer, tab ownership already uses runtime/session/generation guards.
+Gateway bindings should use equivalent host-owned identity rather than the
+currently active tab.
+
+## Capture implications
+
+- Built-in `read`: generic `tool_result` is after truncation and there is no
+  full-output handle. Treat as limited unless a supported execution wrapper is
+  introduced; exact native paging remains the primary path.
+- Built-in `bash`: generic result is bounded, but a trusted `fullOutputPath`
+  exists on successful truncated output. Timeout/abort throw paths preserve a
+  text prefix/status but lose structured details.
+- `repo_*`: add any future capture seam inside the suite wrapper before
+  `truncateOutput`; the generic result hook cannot recover omitted bytes.
+- `ast_grep`: the suite wrapper can capture before truncation and already
+  exposes a full-output temp path when truncated.
+- Unknown/custom tools remain limited unless their concrete execution path is
+  separately proven.
+
+## Unsupported integrations in the current evidence
+
+The current Pix ACP `session/new` implementation consumes `cwd` and `_meta` and
+does not plumb the protocol `mcpServers` field into a local MCP execution path.
+MCP result capture is therefore unsupported, not implicitly covered by the
+generic hook.
+
+Browser QA runs in a child Pi process launched with `--no-extensions` plus a
+restricted extension set. The parent Gateway cannot observe Playwright DOM,
+network, or console bytes as parent `tool_result` events. Future integration may
+reuse completed subagent artifacts; it is not a direct browser adapter.
+
+## Storage/platform boundary
+
+P00 chooses no durable publication primitive. Current tests run on macOS and do
+not certify directory rename/fsync/no-clobber or cross-process quota behavior on
+Linux or Windows. Until P02 fault/platform tests exist, Gateway must not describe
+its storage as crash-durable across the supported platform matrix.
+
+## Third-party extensions
+
+The suite coordinator controls only suite-owned stages. A separately loaded
+third-party extension may register a later `tool_result` modifier and reinsert
+large/raw data. Strict enforce is unsupported for an unverified extension
+combination until a final session/provider-boundary test proves that the raw
+sentinel cannot reappear.
+
+## Evidence
+
+- `test/context-gateway/sdk-pipeline.test.ts`
+- `test/context-gateway/capture-contracts.test.ts`
+- `test/context-gateway/lifecycle-contracts.test.ts`
+- `test/context-gateway/provider-serialization.test.ts`
+- `test/context-gateway/p00-capabilities.md`
+- root `tests/tabs-controller.test.ts`, late origin-tab result contract