pi-ui-extend 1.0.40 → 1.0.42

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

@@ -7,7 +7,7 @@ This package keeps shared Pi tools as ordinary source folders under `src/` and r
 - `src/coding-discipline` — injects a deduplicated silent-mode and quality-discipline block at the very top of the main-session per-turn system prompt for GLM main-session models only (`isGlmModel`) immediately before the LLM request; text-only GLM models get the `lookup` bridge while vision-capable `zai/glm-5.3-flash` inspects images directly; non-GLM models are left untouched; disabled for async sub-agents
 - `src/credential-firewall` — opt-in secret firewall for high-confidence outbound/session credential redaction; disabled by default
 - `src/ast-grep` — `ast_grep` / `ast_apply`
-- `src/async-subagents` — `subagents` tool and sub-agent slash commands, including oh-my-openagent-style `/ultrawork` (`/ulw`) and `/hyperplan` orchestration prompts, plus config-defined sub-agent model/thinking/args presets selected via `/subagent-preset` from `asyncSubagents` in `~/.config/pi/pi-tools-suite.jsonc`; includes the `frontend` profile for Gemini-friendly UI/UX and visual frontend work and the `oracle` profile for cross-provider second opinions; enforces a 30-minute per-agent execution timeout, project-wide `maxConcurrent` queueing, optional retry/backoff, and `result.json` structured metadata/chaining fields next to raw `result.md`; stores project-local run files and a registry under `.pi/subagents/` so result/status collection can recover after compaction or reload while the main session remains alive
+- `src/async-subagents` — `subagents` tool and sub-agent slash commands, including oh-my-openagent-style `/ultrawork` (`/ulw`) and `/hyperplan` orchestration prompts; agent roles are Markdown files under `src/async-subagents/agents/*.md` plus project `.pi/agents/*.md`, while `/subagent-preset` selects model-pool presets from the bundled/project `agents/presets.jsonc`; includes the `oracle` profile for strong second opinions; enforces a 30-minute per-agent execution timeout, project-wide concurrency queueing, optional per-agent retry/backoff, and `result.json` structured metadata/chaining fields next to raw `result.md`; stores project-local run files and a registry under `.pi/subagents/` so result/status collection can recover after compaction or reload while the main session remains alive
 - `src/lsp` — shared LSP diagnostics hook/library that enriches mutating tool results with diagnostics and shuts down language servers on session shutdown
 - `src/comment-checker` — AI-slop comment guard that listens to the `tool_result` event for `write` / `edit` / `apply_patch` mutations, extracts net-new code comment lines, classifies them (filler phrasing, restating code, decorative separators, generic paraphrasing, or — under aggressive strictness — any non-valuable comment), and appends a short nudge to the tool result so the agent removes unnecessary comments on its next turn; TODO/FIXME, license headers, docstrings, pragmas, linter directives, shebangs, and decorators are never flagged; language-agnostic across `//` / `/* */` / `#` / `--` / `<!-- -->` / triple-quote comment styles; per-session deduplication (at most one nudge per 30 s) prevents fix/remark loops; configured via the `commentChecker` section (`enabled`, `strictness`: `conservative` | `balanced` | `aggressive`, default `balanced`) or `PI_COMMENT_CHECKER_ENABLED` / `PI_COMMENT_CHECKER_STRICTNESS`
 - `src/session-name` — `session_name` tool for reading or setting the current session title directly from tool calls, without relying on slash-command parsing
@@ -21,11 +21,11 @@ This package keeps shared Pi tools as ordinary source folders under `src/` and r
 - `src/web-search` — `web_search` and `web_fetch` tools migrated from `@ollama/pi-web-search`; uses local Ollama by default or the official Ollama cloud API when an API key is configured, supports Tavily Search/Extract fallback, provides `/web-credentials` for secure user-level key storage, honors `OLLAMA_HOST`, supports request timeouts via `timeout_ms` / `PI_WEB_SEARCH_TIMEOUT_MS`, and reports provider-specific errors
 - `src/dcp` — headless Dynamic Context Pruning ported from `opencode-dynamic-context-pruning` for the Pi SDK: explicit `compress` tool with range and message modes, `/dcp` commands (context, stats, sweep, manual, decompress, recompress, compress), same-call overlap validation, recoverable compressed-block rollups, grouped message-mode skip diagnostics, stable raw-message anchors when available, protected user/tool preservation, deduplication, error purging, and context nudges; visualization is left to `compress` tool responses and the renderer-owned context-percent click dialog
 - `src/prompt-commands` — user slash-command builder: `/prompt-commands` opens a CRUD menu for saved prompt-backed slash commands, stores them under `promptCommands` in `~/.config/pi/pi-tools-suite.jsonc`, reloads after edits, and runs each saved prompt as a normal user message
-- `src/skill-installer` — `/install-skill [name]` installs a personal skill folder from `~/.agents/local_skills` into the current project's `.pi/skills/` so it activates as a project-local skill, then automatically runs `/reload` so the new skill is picked up without a manual step; `/export-skill [name]` does the reverse, copying a project-local skill back to `~/.agents/local_skills/` for reuse in other projects (no reload, since the library lives outside the project); with no argument either command shows an interactive menu of available skills (folders containing `SKILL.md`), and the `<name>` form installs/exports it directly (headless-safe); existing destinations prompt to overwrite in the UI and are refused in headless mode; `.DS_Store` files are skipped
+- `src/resource-registry` — `/registry` manages one private Git registry with global reusable `skills/` and `agents/` plus project-scoped `projects/<project-key>/tasks.jsonc`, `projects/<project-key>/plans/`, and `projects/<project-key>/TODO.md`; skills install into `.pi/skills/<name>/`, agents into `.pi/agents/<name>.md`, while `push tasks|plans|todo|project` and `pull tasks|plans|todo|project` synchronize `.pi/tasks.jsonc`, `.pi/plans/`, and `.pi/TODO.md` only for the current project; the project key is normally derived from Git `origin` (SSH and HTTPS forms normalize to the same key) and can be overridden per project with `/registry project-key <key>` in `.pi/pi-tools-suite.jsonc`; `status` fetches and groups skills, agents, tasks, plans, and TODO by state (up to date, updates, conflicts, local-only, remote-only, and so on) using `.pi/registry.json` provenance; reusable `install`, `update`, `push`, remote-only `remove`, and local-only `uninstall` support TUI flows and bulk `all` forms, `delete`/`rm` alias remote `remove`, `remove-local`/`local-remove` alias `uninstall`, destructive bulk operations require interactive confirmation, and every successful skill/agent mutation reloads resources once; `/registry configure <git-url> [branch]` stores the registry remote in the user config; Git authentication is delegated to the user's normal Git/SSH credential setup and the local clone is only a disposable cache
 
 `index.ts` is intentionally only a thin auto-discovery shim that re-exports `src/index.ts`. There is no `pi.extensions` manifest here, so local Pi auto-discovery loads the suite once via `~/.pi/agent/extensions/pi-tools-suite/index.ts` and does not double-register tools.
 
-Registration order is preserved in `src/index.ts`: coding-discipline, ast-grep, async-subagents, lsp, comment-checker, session-name, session-recovery, repo-discovery command/tool gate, antigravity-auth provider, OpenCode import, todo, model-tools, usage, web-search, dcp, prompt-commands, skill-installer, credential-firewall, then codex-reasoning-fix. Tool metadata and active model-specific tool sets have two modes: standard and repo-aware. When `.indexer-cli` enables `repo_*`, those tools stay active ahead of overlapping lower-level aliases so the indexed discovery surface has priority.
+Registration order is preserved in `src/index.ts`: coding-discipline, ast-grep, async-subagents, lsp, comment-checker, session-name, session-recovery, repo-discovery command/tool gate, antigravity-auth provider, OpenCode import, todo, model-tools, usage, web-search, dcp, prompt-commands, resource-registry, credential-firewall, then codex-reasoning-fix. Tool metadata and active model-specific tool sets have two modes: standard and repo-aware. When `.indexer-cli` enables `repo_*`, those tools stay active ahead of overlapping lower-level aliases so the indexed discovery surface has priority.
 
 ## Session recovery
 
@@ -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: bundled Markdown defines the built-ins, then the nearest project `.pi/agents/*.md` file overrides the same-named built-in field-by-field. Markdown is the only source of agent role/profile definitions. The removed `asyncSubagents` section and old standalone config-path variables are not read.
+- 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 overrides in a project `browser-qa.md` inherit the
+bundled Markdown workflow. A project Markdown body replaces the inherited
+`promptAppend` 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
@@ -512,70 +621,81 @@ so screenshots and assertions remain state-focused.
 
 Async-subagents also injects a lightweight oh-my-openagent-style system-prompt strategy by model: non-GPT parents get `parallel-first`, an orchestration-first hint that favors ultrawork/subagents for broad work, while GPT-like parents get `deep-work`, a direct deep-worker hint that uses subagents only when clearly useful. Explicit custom system prompts (`--system-prompt`, `SYSTEM.md`, custom templates) are respected and skip this injection by default. Disable it with `PI_AGENT_STRATEGY=off`; force a strategy with `PI_AGENT_STRATEGY=parallel-first` or `PI_AGENT_STRATEGY=deep-work`; set `PI_AGENT_STRATEGY_WITH_CUSTOM_PROMPT=1` to append it even when a custom prompt is present.
 
-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`.
-
-Example shared async-subagents config section:
+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. Provider image metadata is supplemented by an internal compatibility list for known blind models so the parent does not falsely claim visual access; this is runtime capability policy, not agent configuration.
+
+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.
+
+Bundled pools live in `src/async-subagents/agents/presets.jsonc`. Add or override
+project pools in the nearest `.pi/agents/presets.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 path` shows the
+bundled and project preset paths. The shipped pools are `cheap` (GLM), `gpt`,
+and `deep` (the retained legacy name for the mixed pool, not worker escalation).
+Agent descriptions, instructions, model order, thinking, tools, retry, and
+timeouts remain in agent Markdown; selecting a pool never changes them.
+
+Example project `.pi/agents/presets.jsonc`:
 
 ```jsonc
 {
-  "asyncSubagents": {
-    "defaultType": "quick",
-    "routing": {
-      "enabled": true,
-      "model": "zai/glm-4.5-air",
-      "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" }
-        }
-      }
-    },
-    "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"
-      }
-    }
+  "cheap": {
+    "description": "GLM workers with a strong oracle candidate.",
+    "models": ["zai/glm-5-turbo", "zai/glm-5.3-flash", "zai/glm-5.3"]
+  },
+  "project-gpt": {
+    "description": "GPT models approved for this project.",
+    "models": ["openai-codex/gpt-5.6-luna", "openai-codex/gpt-5.6-terra"]
   }
 }
 ```
 
-### Parent-model-aware model selection (`modelByParent`)
+### Legacy configuration compatibility
 
-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.
+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 project `.pi/agents/<name>.md` files.
 
-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"] }
-  }
-}
-```
+Within an agent Markdown file, legacy `model` plus `fallbackModels` and
+`modelByParent` remain readable. `models` is a complete replacement list: it
+clears inherited legacy model/fallback/parent routing. New built-ins use ordered
+`models` lists and contain no parent-tier escalation maps.
 
-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.
+The removed `asyncSubagents` section is not part of the public schema or generated
+user config and is no longer read at runtime. Existing files can remain on disk
+without being rewritten, but they have no effect: migrate role definitions to
+`.pi/agents/*.md` and custom model pools to `.pi/agents/presets.jsonc`. 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.
 
@@ -583,7 +703,7 @@ Sub-agent runs are stored in the current project's `.pi/subagents/` directory wh
 
 Runtime logs are minimized by default: successful agents do not keep `events.jsonl`, and `stderr.log` is discarded unless the agent fails. Set `ASYNC_SUBAGENTS_DEBUG_LOGS=1` / `PI_SUBAGENTS_DEBUG_LOGS=1` to keep diagnostic logs for successful agents too; debug event logs store a compact RPC event summary instead of the full streaming transcript. Defaults are 0 bytes for `events.jsonl` without debug, 32 MiB for debug `events.jsonl`, 8 MiB for retained `stderr.log`, and 8 MiB for a single RPC JSON line; override with `ASYNC_SUBAGENTS_MAX_EVENTS_BYTES` / `PI_SUBAGENTS_MAX_EVENTS_BYTES`, `ASYNC_SUBAGENTS_MAX_STDERR_BYTES` / `PI_SUBAGENTS_MAX_STDERR_BYTES`, and `ASYNC_SUBAGENTS_MAX_RPC_LINE_CHARS` / `PI_SUBAGENTS_MAX_RPC_LINE_CHARS`.
 
-`asyncSubagents` config also supports `maxConcurrent` (default 5, project-wide; `0` means unlimited), global/per-type `retry` with exponential backoff, global/per-type `maxResultBytes` for bounding `result.json.resultText` while keeping raw `result.md` intact, and global/per-type/preset `timeoutMs` for wall-clock agent watchdogs. Spawn calls and individual task objects can pass `timeoutSeconds` to shorten the watchdog for synthetic tests or bounded probes. Stop requests mark running, queued planned, and retry-pending agents as `stopped` so queued work is not launched later. Completed agents write `result.json` with status/duration/model/retry metadata plus best-effort `summary`, `findings`, `files`, `risks`, `nextActions`, and `confidence` fields for parent-agent chaining.
+Runtime concurrency defaults to 5 agents per project and the global result summary bound defaults to 100000 bytes. These are internal engine defaults rather than normal user configuration. Per-agent `retry`, `maxResultBytes`, and `timeoutMs` belong in agent Markdown; spawn calls and individual task objects can pass `timeoutSeconds` to shorten the watchdog for synthetic tests or bounded probes. Stop requests mark running, queued planned, and retry-pending agents as `stopped` so queued work is not launched later. Completed agents write `result.json` with status/duration/model/retry metadata plus best-effort `summary`, `findings`, `files`, `risks`, `nextActions`, and `confidence` fields for parent-agent chaining.
 
 ## OpenCode credential import
 

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

@@ -1,28 +1,43 @@
 # Browser QA sub-agent specification
 
+## Type
+
+As-is
+
+## Lifecycle
+
+Active implemented contract.
+
 ## Goal
 
 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 +113,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
@@ -122,13 +137,27 @@ evidence. The role uses `zai/glm-5.3-flash`, falling back to
   failure the runner snapshots and kills only its own descendants before it
   exits, covering that detached browser tree without touching a user's browser.
 
+## Related files
+
+- `external/pi-tools-suite/src/async-subagents/agents/browser-qa.md`
+- `external/pi-tools-suite/src/async-subagents/core/browser-qa.ts`
+- `external/pi-tools-suite/src/async-subagents/core/spawn.ts`
+- `external/pi-tools-suite/src/async-subagents/agents/browser-qa/scripts/browser-qa-runner.mjs`
+- `external/pi-tools-suite/test/async-subagents/core.test.ts`
+- `external/pi-tools-suite/test/async-subagents/browser-qa-runner.test.ts`
+- `external/pi-tools-suite/test/async-subagents/browser-qa-runner.e2e.test.ts`
+- `external/pi-tools-suite/test/async-subagents/selection-e2e.test.ts`
+
 ## 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