pi-ui-extend 1.0.42 → 1.0.45

package/docs/desktop-mvp.md

@@ -44,8 +44,10 @@ current product non-goals.
 
 ## Behavior
 
-1. Tauri starts one isolated `pix-acp` child and exposes only start, line-send,
-   and stop commands to the webview. Arbitrary shell execution is not exposed.
+1. Tauri starts one isolated `pix-acp` child for the ACP protocol. The host's
+   command surface has since grown beyond start/line-send/stop (e.g. package and
+   shell terminals via portable-pty); those additions are governed by the later
+   `specs/desktop-*.md` family, not by this historical baseline.
 2. The client initializes ACP with form-elicitation support before creating or
    loading a session.
 3. Selecting a workspace lists its persisted sessions. The user can create a
@@ -75,10 +77,13 @@ current product non-goals.
     object and the generation must still own the child
   - `acp_stop(generation)`; stale generations cannot stop a replacement child
 - Rust → webview events:
-  - `acp://stdout` with `{ generation, line }` for one complete stdout line
-  - `acp://stderr` with `{ generation, line }` for one diagnostic line
+  - `acp://stdout` with `{ windowLabel, generation, lines: string[] }` batches
+    of complete stdout lines (stdout stays protocol-only)
+  - `acp://stderr` with `{ windowLabel, generation, lines: string[] }` batches
+    of diagnostic lines
   - `acp://exit` with the generation and child exit status
-- Rust starts `node ../../acp/dist/main.js` by default. `PIX_ACP_NODE_BINARY`
+- Rust starts Node with the generated `<repo>/acp/dist/main.js` entry by
+  default. `PIX_ACP_NODE_BINARY`
   and `PIX_ACP_ENTRY` may override executable and entry path for development.
 - Webview ↔ adapter payloads follow `@agentclientprotocol/sdk` 1.4.0 types.
 

package/docs/desktop-task-manager.md

@@ -16,15 +16,18 @@ agent's session-local todo list.
 
 ## Scope
 
-- A collapsible, resizable left sidebar with `Tasks` and `Project` tabs.
+- A collapsible, resizable left activity sidebar whose project-scoped views
+  include `Tasks` and `Project` alongside other workspace views.
 - Create, edit, delete, manual status changes, drag reordering, and moving tasks
   between type groups.
+- Create an untitled task directly from the normal message composer through its
+  overflow menu, carrying the current draft text and attachments without
+  sending a prompt.
 - Task type (`bug`, `feature`, `improvement`) and status (`backlog`, `todo`,
   `in-progress`, `done`).
 - Persisted priority (`low`, `medium`, `high`, `urgent`). New tasks currently
   receive `medium`; priority is not exposed by the current task editor or rows.
 - Project-local persistence in `.pi/tasks.jsonc` with a versioned schema.
-- One-time migration from the legacy strict-JSON `.pi/tasks.json` file.
 - Starting an unlinked task in a new ACP session and reopening an already-linked
   session instead of creating a duplicate.
 - Task descriptions can contain attachment markers; those attachments are
@@ -42,38 +45,65 @@ agent's session-local todo list.
 
 ## Behavior
 
-1. The sidebar starts on `Tasks`, remembers its width/collapsed state locally,
-   and keeps a compact tab rail available while collapsed.
+1. On first use the sidebar starts on `Tasks`; afterward it restores the last
+   active sidebar view. It remembers its width/collapsed state locally and keeps
+   a compact activity rail available while collapsed.
 2. Tasks are grouped by type. Dragging a task reorders it; dropping it into a
    different group also changes its type and updates `updatedAt`.
-3. Task rows show title, status, session/run action, edit, and delete controls.
-   Status uses icon, text, and color rather than color alone.
-4. Creating a task requires a non-empty title, starts with status `todo` and
-   priority `medium`, and may include description text and attachments.
+3. Task rows show the title when present. Untitled tasks use the first line of
+   description as their display label, or `Untitled task` when they contain only
+   attachments. Rows also show status, session/run action, edit, and delete
+   controls. Status uses icon, text, and color rather than color alone.
+4. Manual creation through the task editor still requires a non-empty title.
+   Tasks start with status `todo` and priority `medium`, and may include
+   description text and attachments. Newly selected/pasted task attachments are
+   persisted into `.pi/task-attachments` so the task owns its files. Existing
+   untitled composer-captured tasks may be edited without inventing a title as
+   long as description content or attachments remain.
 5. Editing changes title, description, and type. Status is changed separately.
    Existing persisted priority is preserved.
 6. `.pi/tasks.jsonc` is authoritative. Missing `.pi`/task storage produces an
    empty version-1 document. JSONC comments and trailing commas are accepted.
-7. If `.pi/tasks.jsonc` is absent and legacy `.pi/tasks.json` exists, Pix reads
-   and validates the legacy document, adds the schema reference when absent,
-   writes `.pi/tasks.jsonc`, deletes the legacy file, and returns the migrated
-   document. If JSONC already exists, it wins and the legacy file is ignored.
+7. Only `.pi/tasks.jsonc` is recognized as task storage. Other sibling task
+   files are ignored; Pix does not import, migrate, delete, or interpret them.
 8. Starting an unlinked task creates/selects a new ACP session, persists its
    session id, changes any non-`done` task to `in-progress`, preserves `done`,
    appends the generated task prompt, and sends it immediately.
 9. Starting a linked task opens that session. A stale/missing linked session is
    a recoverable error and does not silently create another session.
 10. Task completion remains manual.
+11. The normal message composer's vertical-ellipsis menu exposes `Create task`
+    whenever the current draft has text, attachments, or active voice input.
+    Voice input is finalized first. The resulting task has an empty persisted
+    title, type `feature`, status `todo`, priority `medium`, and stores the
+    composer text plus attachment markers in its description. The prompt is not
+    sent to the agent. Composer attachments are persisted into
+    `.pi/task-attachments` before those markers are written; path-backed files
+    are copied there and pathless images are materialized from their bytes.
+12. After composer task persistence succeeds, Pix expands/selects the Tasks
+    sidebar view, scrolls the newly created task into view, highlights it, and
+    clears the composer only if the draft is still the exact draft that was
+    captured for task creation. A failed save or edits made while the save is in
+    flight preserve the composer.
+13. After a task-document write succeeds, Pix prunes regular files from
+    `.pi/task-attachments` that are no longer referenced by any remaining task.
+    Shared attachments stay on disk until the last task reference is removed.
+14. Every successful task-document write also marks the Registry `tasks` project
+    artifact dirty for background synchronization. Rapid task mutations are
+    debounced/coalesced; a failed local write never enters the remote sync queue.
+    If the Registry session is busy, the dirty task state remains pending until
+    an idle sync window is available.
 
 ## Contracts
 
 - Project file: `.pi/tasks.jsonc`.
 - Document shape: optional `$schema`, `version: 1`, and `tasks`.
-- Each task has a unique id, title, type, status, priority, `createdAt`, and
-  `updatedAt`; description and `sessionId` are optional.
-- Unknown fields, duplicate ids, unsupported enum values, empty titles,
-  malformed timestamps, unsupported versions, and oversized documents are
-  rejected.
+- Each task has a unique id, string title, type, status, priority, `createdAt`,
+  and `updatedAt`; description and `sessionId` are optional. The title may be an
+  empty string only when description content is present.
+- Unknown fields, duplicate ids, unsupported enum values, completely empty task
+  content, malformed timestamps, unsupported versions, and oversized documents
+  are rejected.
 - The Tauri backend confines task paths to the active workspace, rejects escape
   through `.pi` symlinks, and caps the document at 1 MB.
 - Writes validate the complete document, write a same-directory temporary file,
@@ -83,6 +113,18 @@ agent's session-local todo list.
 
 - Failed validation never replaces the task file.
 - Failed persistence restores the previous in-memory task document.
+- Composer task creation never clears a newer draft that changed while task
+  persistence was in flight.
+- Task attachments are persisted through the same task-description marker
+  format used by the task editor, and newly attached files are owned by the
+  project's `.pi/task-attachments` storage so running the task restores them
+  without depending on the expiring chat cache or original source path.
+- Attachment cleanup runs only after the replacement `tasks.jsonc` has been
+  committed successfully. Cleanup is reference-based across the complete task
+  document and never deletes paths outside `.pi/task-attachments`.
+- Create/edit/delete/status/reorder/session-link task mutations all flow through
+  the same save method, so they share the same background Registry scheduling
+  semantics.
 - A task is linked to at most one session.
 - Running/reordering/editing is disabled while conflicting task/session work is
   active.
@@ -92,16 +134,23 @@ agent's session-local todo list.
 
 - Switching workspaces discards the previous in-memory task view and loads the
   new project's task document.
-- Missing storage means no tasks; malformed or empty JSON/JSONC is an error.
-- A legacy task file is migrated at most once because successful migration
-  removes `.pi/tasks.json`.
+- Missing storage means no tasks; malformed or empty `.pi/tasks.jsonc` is an error.
+- Unsupported sibling task files do not participate in task loading.
 - Save, session creation, attachment preparation, and prompt failures remain
   visible and retryable.
 
 ## Related files
 
-- `desktop/src/App.svelte`
+- `desktop/src/app/project-actions.svelte.ts`
+- `desktop/src/app/desktop-project-action-services.ts`
+- `desktop/src/components/PromptComposerActionsMenu.svelte`
 - `desktop/src/components/WorkspaceSidebar.svelte`
+- `desktop/src/components/workspace-sidebar-layout-controller.svelte.ts`
+- `desktop/src/components/workspace-sidebar-task-drag-controller.svelte.ts`
+- `desktop/src/components/WorkspaceSidebarTasksPanel.svelte`
+- `desktop/src/components/WorkspaceSidebarTaskEditor.svelte`
+- `desktop/src/lib/attachments.ts`
+- `desktop/src/lib/attachments.test.ts`
 - `desktop/src/lib/project-tasks.ts`
 - `desktop/src/lib/project-tasks.test.ts`
 - `desktop/src-tauri/src/lib.rs`
@@ -109,10 +158,12 @@ agent's session-local todo list.
 
 ## Verification
 
-- `desktop/src/lib/project-tasks.test.ts` covers parsing, prompt generation, and
-  drag/reorder semantics.
+- `desktop/src/lib/project-tasks.test.ts` covers untitled composer task creation,
+  parsing, prompt generation, and drag/reorder semantics.
+- `desktop/src/lib/attachments.test.ts` covers data-URL decoding used when a
+  pathless composer image is persisted into project task storage.
 - Rust tests in `desktop/src-tauri/src/lib.rs` cover missing/read/write/malformed
-  JSONC, validation, workspace confinement, and legacy JSON migration.
+  JSONC, validation, workspace confinement, and ignoring unsupported task files.
 - Run `npm --prefix desktop test`, `npm --prefix desktop run check`, and
   `cargo test --manifest-path desktop/src-tauri/Cargo.toml`.
 
@@ -127,9 +178,11 @@ agent's session-local todo list.
 
 ## Evidence
 
-- Confirmed by code: `desktop/src/App.svelte`,
-  `desktop/src/components/WorkspaceSidebar.svelte`, and
-  `desktop/src/lib/project-tasks.ts` implement the current task lifecycle.
+- Confirmed by code: `desktop/src/app/project-actions.svelte.ts`,
+  `desktop/src/app/desktop-project-action-services.ts`, the extracted composer/
+  sidebar task surfaces, and `desktop/src/lib/project-tasks.ts` implement the
+  current task lifecycle and composer capture action.
 - Confirmed by code: `desktop/src-tauri/src/lib.rs` owns JSONC persistence,
-  validation, confinement, atomic replacement, and legacy migration.
+  validation, confinement, atomic replacement, and ignores unsupported sibling
+  task-storage formats.
 - Confirmed by tests: project-task unit tests and Tauri task persistence tests.

package/docs/release.md

@@ -13,15 +13,39 @@ npm run smoke-test
 `release:check` runs type checking, the test suite, a production build, and `npm pack --dry-run`.
 `smoke-test` packs the real tarball, installs it into an isolated temp directory, checks the bundled files, and runs non-interactive `pix` commands from the installed package.
 
-## Publish a new npm version
+## CI regression guardrails
 
-Pix uses the same release style as `indexer-cli`: a local command bumps the version, smoke-tests the tarball, then pushes the release commit and tag. GitHub Actions publishes the tag to npm using the `NPM_TOKEN` repository secret.
+The normative CI invariants are recorded in [`specs/ci-release.md`](../specs/ci-release.md). This section is the operational checklist for release work.
 
-One-time setup:
+The GitHub Actions release workflow has two different responsibilities and they should stay separate:
 
-```bash
-gh secret set NPM_TOKEN
-```
+- `build-and-test` runs on Ubuntu, macOS, and Windows. This is the cross-platform correctness gate: type checks, unit/integration tests, platform-specific host checks, and the Pix build belong here.
+- Package smoke tests validate the artifact a user actually installs. Run the full payload/tarball smoke test on Ubuntu, and a smaller pack/install/CLI sanity check on Windows. A separate macOS package smoke job is unnecessary unless packaging gains macOS-specific behavior.
+
+Keep CI tests deterministic across runner speed and operating systems:
+
+- Assert explicit byte/count/state thresholds instead of assuming a background producer will do enough work within a short wall-clock interval. For example, a truncation test should write a fixed amount greater than the limit rather than write repeatedly for 300 ms and assume the runner will exceed the limit.
+- Use timers only when timeout behavior itself is the contract. Do not use elapsed time as a proxy for produced output, process progress, or cleanup completion.
+- When a test needs asynchronous process teardown, wait for an observable owned-process condition rather than relying on a short sleep.
+- Run configuration-sensitive suite checks with an isolated `HOME` when reproducing CI locally. User-level Pix/pi-tools-suite config can intentionally change DCP and other opt-in behavior and must not be mistaken for a CI regression.
+
+Windows process tests have additional invariants:
+
+- `@lydell/node-pty` on Windows does not support POSIX signal arguments to `kill`; terminate an owned Windows PTY with signal-less `kill()` and release its ConPTY resources.
+- Browser/process cleanup must stay ownership-scoped. When a PowerShell helper discovers descendants, it must not select or terminate itself; kill owned child roots recursively and verify cleanup before returning.
+- Treat CRLF/LF differences as presentation differences unless line endings are the behavior under test.
+
+Package smoke assertions should check stable package contracts. If a bundled guide title, required payload path, CLI entry point, or other intentionally asserted artifact changes, update the corresponding smoke assertion in the same change. Do not remove the smoke test merely because ordinary source tests are green: source tests do not prove that `npm pack` contains an installable, runnable artifact.
+
+Current implementation:
+
+- `.github/workflows/publish.yml` owns the CI matrix and release gates.
+- `scripts/smoke-test-package.sh` is the full packed-artifact/payload smoke test.
+- `scripts/smoke-test-package-cli.mjs` is the cross-platform pack/install/CLI sanity check used on Windows.
+
+## Publish a new npm version
+
+Pix uses the same release style as `indexer-cli`: a local command bumps the version, smoke-tests the tarball, then pushes the release commit and tag. GitHub Actions publishes the tag to npm using npm trusted publishing (GitHub OIDC), so the publish job does not require a long-lived `NPM_TOKEN` secret.
 
 Release commands:
 

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

@@ -12,8 +12,9 @@ This package keeps shared Pi tools as ordinary source folders under `src/` and r
 - `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/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
+- `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, 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.
+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,7 +576,7 @@ 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: 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.
@@ -528,26 +584,77 @@ AGENTS.md before approving anything; cite file paths first.
 - 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 overrides in a project `browser-qa.md` inherit the
-bundled Markdown workflow. A project Markdown body replaces the inherited
+### 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. 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.
+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
@@ -723,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
@@ -767,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/