pi-ui-extend 1.0.41 → 1.0.45

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

@@ -7,13 +7,14 @@ 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
 - `src/session-recovery` — branch- and compaction-aware `session_overview`, `session_read_section`, `session_search`, and `session_recovery_context` tools for bounded recovery from Pi's raw append-only session history
-- `src/repo-discovery` — `/idx-init`, `/idx-update`, and indexed-only `repo_architecture` / `repo_structure` / `repo_ast` / `repo_search` / `repo_explain` / `repo_deps`; tools register only when the launch project has `.indexer-cli`
-- `src/antigravity-auth` — `antigravity` custom provider with Google Antigravity OAuth login, startup account list, auth.json-only runtime account loading, `/antigravity-add-account` OAuth append into rotation, `/antigravity-account` status display, account rotation/failover, Antigravity plus Gemini CLI model registration, and streaming through the Cloud Code Assist unified gateway
+- `src/context-gateway` — off/observe/enforce result shaping; enforce keeps safe test/build compacts and bounds over-budget structured `web_search` / `web_fetch` provider content while retaining the complete producer details in raw session history for `session-recovery`; active modes also keep a privacy-safe rotated JSONL efficiency log with gross avoided context, recovery/artifact-read tax, conservative net estimates, and finalized provider usage
+- `src/repo-discovery` — `/idx-init`, `/idx-update`, and idx-backed `repo_architecture` / `repo_structure` / `repo_ast` / `repo_search` / `repo_explain` / `repo_deps` plus the unified `repo_knowledge` contract/wiki tool; repo tools and repo-aware mutation guidance register only when the launch project has `.indexer-cli` **and** an executable `idx` is available on `PATH`
+- `src/antigravity-auth` — `antigravity` custom provider with Google Antigravity OAuth login, startup account list, auth.json-only runtime account loading, `/antigravity-add-account` OAuth append into rotation, `/antigravity-account` status display, account rotation/failover, model registration with live route mapping (current Antigravity catalog: Gemini 3.5/3.6/3.7/3.8 Flash, Gemini 3.1 Pro, Claude Sonnet 4.6 Thinking, Claude Opus 4.6 Thinking, GPT-OSS 120B Medium, plus legacy Antigravity aliases and Gemini CLI mirrors), and streaming through the Cloud Code Assist unified gateway
 - `src/opencode-import` — `/opencode-import` for bounded migration of supported OpenCode OpenAI/Codex, GitHub Copilot, Z.ai, and Antigravity credentials into Pi; existing entries are preserved unless `--force` is passed
 - `src/todo` — `todo` tool, `/todos`, `/todos-persist`, `/todos-scope`, and `/todos-clear` (also `/todos clear`); supports parent/subtask hierarchy, blockers, ready-task filtering, deferred out-of-scope items, batch operations, JSON/Markdown import/export, automatic clearing when all visible todos are completed, and optional project persistence via `/todos persist on` or `/todos-persist on`; localization/i18n has been removed
 - `src/model-tools` — model-specific tool aliases such as Claude/GLM-style `Read` / `Edit` / `Write` / `Bash` / `Grep` / `Glob` / `LS`, GPT/Codex-style `shell`, and model-gated `apply_patch`
@@ -21,11 +22,58 @@ 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>/task-attachments/`, `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` (with referenced `.pi/task-attachments` rebased through portable registry-only markers), `.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, and the tasks hash includes referenced attachment bytes; 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, context-gateway, truncation-metadata-normalizer, 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. Repo-aware mode requires both project `.indexer-cli` state and an executable `idx`; when enabled, `repo_*` tools stay active ahead of overlapping lower-level aliases. If `idx` is unavailable, the suite falls back to ordinary Read/Grep/LSP/sub-agent guidance and does **not** implicitly install, initialize, or create index state. `/idx-init` is the explicit setup/repair path and should be run only with user permission.
+
+## Repository knowledge and spec maintenance
+
+When repo-aware mode is available, `repo_knowledge` is the single model-facing
+surface for behavioral specs/contracts. It wraps the first-class `idx context`
+and `idx wiki` knowledge layer while ordinary file tools remain responsible for
+editing the primary spec documents themselves.
+
+Read/query actions:
+
+- `context` — primary contract + implementation ranges + tests + freshness in a
+  bounded response;
+- `search` / `show` — find or inspect authoritative project knowledge;
+- `status` / `audit` / `catalog` — freshness and project knowledge health;
+- `discover` — classify new/moved/changed document candidates, including
+  low-signal documents through the explicit all-unclassified mode;
+- `impact` — review known and uncovered contract impact for this task's changed
+  paths (preferred) or a Git base fallback.
+
+Metadata mutation actions are explicit: `record`, `relate`, `verify`, and
+`remove`. They do not edit primary documents. The wrapper requires a source
+review acknowledgement before `record`, concrete semantic evidence review before
+`relate`/`verify`, and an explicit metadata-only acknowledgement before `remove`.
+
+For a **material behavior-changing implementation** in repo-aware mode, the
+model-facing contract is:
+
+1. Find the existing primary behavioral contract before or while implementing.
+2. Keep that primary spec aligned with the intended behavior in the same task.
+   If no suitable primary contract exists, create a focused spec with the normal
+   Edit/Write/`apply_patch` tools before recording its metadata.
+3. After implementation, run task-scoped `repo_knowledge` `impact` on the files
+   changed by this task; review uncovered paths and new/moved documents.
+4. Repair only evidence-backed relations. Similarity or graph proximity alone
+   never authorizes a durable relation, and a reviewed no-impact result is valid.
+5. `record` means classified/indexed, **not verified**. Run `verify` only after
+   reading the primary source and checking relevant code/tests/evidence. Changed
+   code never automatically rewrites spec semantics.
+
+Mechanical refactors, typo/formatting edits, exact renames, and other changes
+that do not alter project behavior do not require this knowledge-maintenance
+lifecycle. When `idx` is unavailable or the project is not indexed, none of
+these requirements are injected; use the normal repository workflow instead.
+For repo-aware projects, completing a todo when only the final active todo
+remains adds one compact reminder to reconcile affected specs and repo knowledge
+before closing that final todo. File mutations themselves do not emit knowledge
+reminders.
 
 ## Session recovery
 
@@ -105,6 +153,7 @@ DCP settings are stored only under `dcp` in the user shared config file `~/.conf
         "enabled": false,
         "patience": 2,
         "summarizerModel": [],
+        "summarizerFallbackModels": [],
         "timeoutMs": 20000
       }
     },
@@ -176,11 +225,16 @@ 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.
 
-`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.
+`compress.autoCompress.enabled` is `false` by default. When explicitly enabled, its `patience` counts completed correlated main-provider opportunities, not repeated context transforms; `summarizerModel` supplies the primary summarizer list and `summarizerFallbackModels` appends explicit ordered fallbacks. Existing multi-entry `summarizerModel` configs remain supported. When both lists are empty, DCP uses the bounded extractive fallback without a model call. A configured model summarizer receives a bounded sub-deadline (75% of `timeoutMs`) so deterministic extractive fallback and durable publication retain time inside the whole operation budget. After a failed model-backed auto-compression attempt, subsequent automatic attempts in that session skip the model summarizer and use deterministic extraction. 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.
+`strategies.emergencyCurrentTurnPruning` is the default-enabled lossy safety floor for a single unfinished turn. DCP first emits emergency reminders and offers only safe old same-turn tool-result candidates. After `patience` completed ignored opportunities, at the model-independent `hardContextPercent`, or when exact auto-compression fails while input capacity is already exceeded, it replaces eligible oldest result bodies until the estimated provider context reaches `targetContextPercent` or a safe capacity margin. 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. If eligible recovery still cannot fit the request, DCP emits a user-visible blocked diagnostic with the capacity reason before abort/handoff. 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.
+DCP durable state is journaled as append-only `dcp-journal` custom entries in
+the Pi session JSONL. Resume/reload replays that journal; the current
+implementation has no legacy sidecar importer or dual-write path. 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`.
 
@@ -444,10 +498,11 @@ Explicit task/CLI model overrides bypass the pool. Setting
 `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
+The six 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).
+(run checks and diagnose logs without fixing files), `ui-qa` (real browser,
+terminal/TUI, and desktop-GUI verification), `frontier-review` (independent
+post-implementation review), 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.
@@ -473,13 +528,14 @@ contract, configuration examples, override rules and legacy compatibility.
 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.
+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"`.
+Real UI QA still requires explicit `subagentType: "ui-qa"`. Explicit legacy
+`browser-qa` requests normalize to `ui-qa` for compatibility.
 
 Unknown explicit types and failed/incomplete automatic routing reject the
 **entire spawn batch before run state or child processes are created**. The tool
@@ -520,35 +576,86 @@ You are this project's staff reviewer. Apply the repo rules from
 AGENTS.md before approving anything; cite file paths first.
 ```
 
-- 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.
+- Frontmatter keys: `name` (must match the filename), `description`, `icon`, `models`, `thinking`, `tools`, `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).
+- 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 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,
+### Real UI QA (browser, TUI, and desktop GUI)
+
+The built-in `ui-qa` role runs on `zai/glm-5.3-flash`, with
+`openai-codex/gpt-5.6-luna` as its fallback. Its Markdown body
+(`src/async-subagents/agents/ui-qa.md`) is a deliberately thin common contract:
+test the real user-facing target, classify only the top-level backend, route
+through on-demand guides, run through the unified runner, and keep deterministic
+assertions as the oracle with bounded execution, owned cleanup, and private
+evidence. Provider/presentation/platform details are intentionally absent from
+the initial role body. 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.
+
+Backend specifics use progressive disclosure through bundled guides under
+`src/async-subagents/agents/ui-qa/guides/`. `browser.md`, `tui.md`, and
+`desktop.md` are compact routers; backend-scoped detail topics cover the actual
+browser provider, TUI presentation, desktop platform driver, and explicit
+browser-auth workflow. The child loads the matching base guide, then only the
+routed detail topic read-only via the runner:
+
+```sh
+node "$PI_UI_QA_RUNNER" guide --backend browser   # or: tui | desktop
+node "$PI_UI_QA_RUNNER" guide --backend browser --topic playwright
+# other examples: chrome-devtools, tui/native-terminal, desktop/windows-uia
+```
+
+The command resolves the guide from a backend-scoped fixed allowlist bundled
+with the suite (never a model-composed path), rejects unknown/cross-backend
+topics/options and extra arguments, bounds guide size, and prints only the
+requested document. `probe` returns authoritative
+`selection.guide = {backend, topic}`; the child reconciles that route before
+`run`.
+
+`ui-qa` authors one private declarative flow and invokes the capability-first
+runner supplied in `PI_UI_QA_RUNNER`. The runner selects exactly one backend
+from the target descriptor and reports candidate capabilities plus its selection
+rationale. Browser routing selects the trusted Playwright backend or the
+capability-probed Chrome DevTools provider. TUI routing selects PTY semantics or
+the native-terminal mirror. Desktop routing selects the capability-probed macOS
+Accessibility, Windows UI Automation, or Linux AT-SPI implementation. Evidence
+capabilities remain platform-specific and never replace deterministic
+assertions. Unsupported platforms or missing required control permissions
+return `BLOCKED`. QA does not
+install GUI automation dependencies, change OS privacy/accessibility settings,
+disable sandboxing, or operate unrelated user windows. Static or mock checks do
+not substitute for the requested UI.
+
+Unified flows and native/TUI evidence—including automatic recordings—stay in the owning agent's private
+`.pi/subagents/<run>/<agent-id>/ui-qa/` workspace. Pass/fail requires a
+product-visible deterministic oracle such as terminal content/state,
+accessibility/app-driver state, window/dialog state, or visible control values;
+screenshots are supporting evidence, not the sole oracle. Cleanup is scoped to
+the PTY/session/app process created by the QA run.
+
+#### Browser backend and project auth
+
+The capability-first runner and all backend resources live under
+`src/async-subagents/agents/ui-qa/`; the trusted browser runner, vendor code,
+license, and examples are grouped under its `browser/` directory. The launcher
+supplies absolute paths in `PI_UI_QA_RUNNER` and `PI_BROWSER_QA_RUNNER`. Normal
+probe/run uses the former;
+the latter is invoked directly only for browser auth profile discovery and
+form-auth scaffolding. These non-secret paths are set only for QA children.
+Every async sub-agent launches with `--no-skills`, and skill flags in
+`extraArgs` are stripped rather than forwarded. Agent roles are self-contained;
+there is no profile field for injecting skills and no built-in QA `--skill`.
+
+Model/thinking/tool-only overrides should use a project `ui-qa.md` and inherit
+the bundled Markdown workflow. A legacy project `browser-qa.md` is migrated to
+the canonical `ui-qa` profile when no `ui-qa.md` override exists. 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.
 
@@ -594,9 +701,10 @@ video recording begins on the login page and captures the field-filling and subm
 sequence; password inputs remain browser-masked, but the private video may show
 other visible login identifiers and must be treated as sensitive evidence. Tracing
 starts only after login succeeds and is sanitized before retention. The launcher
-provides each browser QA process with its own
-`.pi/subagents/<run>/<agent-id>/browser-qa/` workspace. Declarative flows,
-screenshots, video, sanitized traces, and result manifests stay there, so normal
+provides each UI QA process with its general `ui-qa/` workspace plus the browser
+backend's `.pi/subagents/<run>/<agent-id>/browser-qa/` workspace. Unified flows
+stay under `ui-qa/flows/`; browser adapter flows, screenshots, video, sanitized
+traces, and result manifests stay under the backend workspace, so normal
 session shutdown or `subagents cleanup` removes them with the run directory.
 The runner validates the owning agent metadata and refuses flows outside that
 workspace; reusing an agent id clears stale browser QA files first. Trace archives
@@ -607,7 +715,7 @@ 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/agents/browser-qa/examples/qa-auth.example.jsonc`
+`src/async-subagents/agents/ui-qa/browser/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.
 
@@ -621,7 +729,7 @@ 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.
+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`. `lookupFallbackModels` is the ordered fallback array for `lookupModel` and defaults to `[]`; lookup tries the configured chain in order. 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
@@ -638,7 +746,7 @@ 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
+Image-bearing tasks and `ui-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
@@ -653,39 +761,28 @@ 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
+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 init` inserts the
-sample only when config is missing. The shipped pools are `cheap` (GLM), `gpt`,
+`~/.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).
-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.
+Agent descriptions, instructions, model order, thinking, tools, retry, and
+timeouts remain in agent Markdown; selecting a pool never changes them.
 
-Example shared async-subagents config section:
+Example project `.pi/agents/presets.jsonc`:
 
 ```jsonc
 {
-  "asyncSubagents": {
-    "defaultType": "research",
-    "routing": {
-      "enabled": true,
-      "model": "zai/glm-5-turbo",
-      "timeoutMs": 12000
-    },
-    "presets": {
-      "cheap": {
-        "description": "GLM workers with a strong oracle candidate.",
-        "models": ["zai/glm-5-turbo", "zai/glm-5.3-flash", "zai/glm-5.3"]
-      }
-    },
-    "types": {
-      "research": {
-        "models": ["zai/glm-5-turbo", "openai-codex/gpt-5.6-luna"],
-        "thinking": "low"
-      }
-    }
+  "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"]
   }
 }
 ```
@@ -694,21 +791,19 @@ Example shared async-subagents config section:
 
 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.
+defined as ordinary project `.pi/agents/<name>.md` files.
+
+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.
+
+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.
 
@@ -716,7 +811,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
 
@@ -736,6 +831,14 @@ Without an Ollama API key, both tools default to `http://localhost:11434/api/exp
 
 Configure a Tavily key to enable automatic fallback for both tools. Ollama remains the primary provider; if any Ollama request or response fails, `web_search` retries through `https://api.tavily.com/search` and `web_fetch` retries through `https://api.tavily.com/extract`. The Tavily key is sent only in Tavily's bearer authorization header and is never accepted as a tool parameter or included in result details. Fallback results set `details.provider` to `tavily` and include the primary Ollama error under `details.fallbackFrom`; ordinary results set `details.provider` to `ollama`.
 
+When Context Gateway is in `enforce` mode, an over-budget `web_search` or
+`web_fetch` result with complete structured producer details is delivered to the
+next model as a bounded `web-recoverable-compact` view. The original structured
+details stay in the raw session tool result (they are not serialized into the
+provider request) and can be found by `toolCallId` with `session_search`, then
+read or paged with `session_read_section`. Unsupported web result shapes remain
+passthrough instead of being irreversibly sliced.
+
 The recommended interactive setup is:
 
 ```text
@@ -780,17 +883,27 @@ pi-tools-suite/
   package.json
   src/
     index.ts
+    coding-discipline/
     ast-grep/
     async-subagents/
     lsp/
+    comment-checker/
+    session-name/
+    session-recovery/
     repo-discovery/
     antigravity-auth/
+    opencode-import/
     todo/
     model-tools/
     usage/
     web-search/
+    context-gateway/
+    truncation-metadata-normalizer/
     dcp/
     prompt-commands/
+    resource-registry/
+    credential-firewall/
+    codex-reasoning-fix/
   docs/
   licenses/
   scripts/

package/external/pi-tools-suite/docs/evals.md

@@ -137,7 +137,7 @@ The current extension registry covers all 19 modules:
 | `web-search` | web-search tests | deterministic only |
 | `dcp` | DCP prompt/pruning/state tests | existing prompt evals |
 | `prompt-commands` | eval extension contracts | deterministic only |
-| `skill-installer` | eval extension contracts | deterministic only |
+| `resource-registry` | resource-registry integration + eval extension contracts | deterministic only |
 | `credential-firewall` | firewall tests | deterministic only |
 | `codex-reasoning-fix` | reasoning-fix tests | deterministic only |
 

package/external/pi-tools-suite/docs/session-recovery.md

@@ -2,6 +2,14 @@
 
 Status: implemented MVP contract (semantic search is intentionally deferred).
 
+## Type
+
+As-is
+
+## Lifecycle
+
+Active implemented contract.
+
 ## Goal
 
 Let an agent recover the task, recent instructions, file activity, and useful raw
@@ -28,19 +36,36 @@ active model context by compaction remains discoverable.
 
 A section starts at the first selected entry, a user message, a compaction, or a
 branch summary. Its stable ID is derived from the start entry ID. The overview
-reports bounded head and tail sections with entry ranges, counts, and compact
-role/tool/error/file statistics. Labels are previews, not inferred decisions.
+reports bounded section pages with entry ranges, counts, and compact
+role/tool/error/file statistics. When more sections exist it returns an opaque
+`nextCursor`; continuing with that cursor resumes after the last delivered
+section. Labels are previews, not inferred decisions.
 
 ### Reading and search
 
-`session_read_section` requires a section ID produced for the same scope. It
-renders message roles and text, tool calls and arguments, tool results,
+`session_read_section` accepts either a section ID produced for the same scope or
+one exact raw `entry_id`. Direct entry reads avoid scanning from the start of a
+section and are useful when overview/search already identified the exact entry.
+Without a continuation cursor, callers must pass exactly one of `section_id` or
+`entry_id`.
+
+The reader renders message roles/text, tool calls/arguments, tool results,
 compaction summaries, and branch summaries with per-entry and total output
-limits.
+limits. Long entry bodies and multi-entry pages return an opaque `nextCursor`;
+passing that cursor continues at the exact entry/body offset and must use the
+same scope.
+
+When Context Gateway has delivered a `web-recoverable-compact` result,
+`session_search` can locate its raw tool-result entry by `toolCallId`, and
+`session_read_section` exposes the retained structured `toolResult.details`
+under `recoverable_raw_details`. The compact provider view is therefore not the
+only copy of the web result: recovery reads the original structured data from
+the append-only session and never refetches the URL.
 
 `session_search` is case-insensitive by default and searches message text, tool
 arguments/results, custom-message content, and compaction or branch summaries.
-It returns entry and section IDs plus bounded snippets. Regex and semantic
+It returns entry and section IDs plus bounded snippets. Search pages use an
+opaque cursor bound to scope, query, and case-sensitivity. Regex and semantic
 search are out of scope for the MVP.
 
 ### Recovery context
@@ -60,6 +85,8 @@ tools are not guessed to be mutations.
 
 - Results use small defaults and hard caps for result count, entry body size,
   and total text size.
+- Overview, read, and search pagination use opaque validated cursors; a cursor
+  from another scope/query or a stale section is rejected rather than guessed.
 - Empty or in-memory sessions return a normal explanatory result.
 - Unknown or partially shaped entries are ignored or rendered conservatively.
 - Concurrent sibling tool results might not yet be visible when recovery runs.
@@ -68,17 +95,23 @@ tools are not guessed to be mutations.
 - Parent-session metadata is reported when Pi exposes it; parent files are not
   traversed.
 
+## Related files
+
+- `external/pi-tools-suite/src/session-recovery/index.ts`
+- `external/pi-tools-suite/src/tool-descriptions.ts`
+- `external/pi-tools-suite/test/session-recovery.test.ts`
+
 ## Verification
 
 Deterministic tests cover active versus all branches, raw pre-compaction search,
-stable section IDs, Unicode case-insensitive search, bounded output, empty
-sessions, current-call exclusion, recent errors, file carry-forward details,
-and conservative handling of unknown entries. Release verification runs the
-suite typecheck/tests/smoke gate, host `npm run check`, and then syncs the suite
-with `npm run sync:pi-tools-suite`.
+stable section IDs, overview/search pagination, direct late-entry reads,
+continued long bodies, Unicode case-insensitive search, bounded output, empty
+sessions, DCP-control filtering, current-call exclusion, recent errors, file
+carry-forward details, and conservative handling of unknown entries. Release
+verification runs the suite typecheck/tests/smoke gate and host checks.
 
 ## Evidence
 
-Evidence is recorded by the implementation tests in
-`test/session-recovery.test.ts` and the verification commands reported with the
-change.
+Evidence is recorded by
+`external/pi-tools-suite/test/session-recovery.test.ts` and the implementation
+in `external/pi-tools-suite/src/session-recovery/index.ts`.