pi-orchestrator-config 4.2.0 → 4.3.2

package/README.md

@@ -12,9 +12,10 @@ Single extension that provides:
 
 | Feature | Description |
 |---------|-------------|
-| **Subagent tool** | Delegate tasks to specialist agents (single, parallel, chain, async modes) |
-| **Async background agents** | Spawn agents in background with `async: true` — results surface automatically when complete. Fullscreen overlay dashboard with live output, keyboard nav, and kill support (`/async-status`, `/async-kill`). On **acpx** parents, optional async is coerced to sync; dream/cron need `async_llm_provider` + `async_llm_model`. `cli-*` providers support async natively (see `dev-docs/cli-provider.md`) |
-| **CLI / ACPX providers** | Optional `cli_agents` / `acpx_agents` register `cli-*` / `acpx-*` via native `createProvider` (pi ≥ 0.81): `/login cli-<agent>` or `/login acpx-<agent>`, model refresh, filter when unavailable |
+| **Subagent tool** | Delegate tasks to specialist agents (single, parallel, chain, async modes); optional `model` param for model override |
+| **`list_models`** | List available models and providers for subagent model override |
+| **Async background agents** | Spawn agents in background with `async: true` — results surface automatically when complete. Fullscreen overlay dashboard with live output, keyboard nav, and kill support (`/async-status`, `/async-kill`). On **acpx** parents, optional async is coerced to sync; dream/cron need `internal_operations_provider` + `internal_operations_model`. `cli-*` providers support async natively (see `dev-docs/cli-provider.md`) |
+| **CLI / ACPX providers** | Optional `cli_agents` / `acpx_agents` register `cli-*` / `acpx-*` via native `createProvider` (pi ≥ 0.84): `/login cli-<agent>` or `/login acpx-<agent>`, model refresh, filter when unavailable. Missing context window / maxTokens / cost filled from models.dev (`~/.pi/pi-config/models.dev.json`, 1-day refresh). Cold-start default restore (#753): gates `startup`\|`new`, empty `enabledModels`, trusted project merge — see `dev-docs/cli-provider.md` |
 | **`/btw` command** | Quick side questions without polluting conversation history — ephemeral overlay |
 | **`/async-status` command** | Show status of background agents — select one for live output streaming |
 | **`/async-kill` command** | Kill async agents (overlay picker or by name/id) |
@@ -32,10 +33,10 @@ Single extension that provides:
 | **Dreaming** | Background memory consolidation — extracts memories from sessions, deduplicates, maintains topic-based memory |
 | **Memory enforcement** | Code-enforced memory entries — triggers on bash/tool/file events, actions: block, run_after, warn. LLM cannot ignore enforced rules. Dreaming-safe via *(enforced)* marker |
 | **Upgrade changelog** | Shows release notes on session start after pi-config version upgrade |
-| **Task tracking** | Structured task lists for multi-step workflows — live widget, progress tracking, reminder nudges ([@tintinweb/pi-tasks](https://github.com/tintinweb/pi-tasks)) |
+| **Task tracking** | Structured task lists for multi-step workflows — live widget, progress tracking, reminder nudges (owned, based on [@tintinweb/pi-tasks](https://github.com/tintinweb/pi-tasks) MIT) |
 | **Neovim integration** | Send changed files and review findings to nvim's quickfix list — only active when running inside nvim |
-| **Inter-agent communication** | P2P (`/coms`) and networked (`/coms-net`) agent communication — on-demand activation via slash commands |
-| **Slash commands** | `/pr-review`, `/issue-review`, `/release`, `/review-local`, `/review-status`, `/query-db`, `/btw`, `/async-status`, `/async-kill`, `/status`, `/dream`, `/remember`, `/coms`, `/coms-net` — with autocomplete argument hints |
+| **Inter-agent communication** | P2P (`/coms`) agent communication — on-demand activation via slash command |
+| **Slash commands** | `/pr-review`, `/issue-review`, `/release`, `/review-local`, `/review-status`, `/query-db`, `/btw`, `/async-status`, `/async-kill`, `/status`, `/dream`, `/remember`, `/coms`, `/pi-config-settings` — with autocomplete argument hints |
 | **GitHub autocomplete** | Type `#` in the editor to get issue/PR suggestions from the current repo — lazy-loaded, 5min cache |
 | **Command arg completions** | Tab-complete arguments for slash commands — providers and models for `/external-ai`, branches for `/review-local`, PR numbers for `/pr-review`, and more |
 | **Discord bot** | Control pi sessions from your phone via Discord DMs — send prompts, answer ask_user dialogs, switch sessions |
@@ -76,13 +77,13 @@ Single extension that provides:
 | `/dream-auto` | Toggle automatic memory dreaming (every 3h + session end) |
 | `/cron add\|list\|list-all\|remove` | Schedule recurring tasks within the pi session (e.g., `/cron add every 2h check for new issues`, `/cron add at 12:00 /review-handler`). `/cron list` and `/cron list-all` open overlay UI (view / remove; list-all = all sessions). Tasks run while pi is active, survive `/reload`, and stop on exit |
 | `/async-kill [name\|id\|all]` | Kill async agents (overlay picker or by name/id) |
+| `/pi-config-settings [project\|global]` | Interactive TUI settings editor — browse all pi-config settings with scope indicators, smart pickers for providers/models, and immediate save |
 | `/status` | Unified session snapshot — async agents, cron tasks, git branch, context usage |
 | `/nvim-changed-files` | Send git changed files to nvim's quickfix list (only inside nvim) |
 | `/pidiff start\|stop\|restart\|status` | Manage the pidiff diff viewer server (per-project) |
 | `/coms start\|stop\|status` | P2P local agent communication (Unix socket) |
-| `/coms-net start\|connect\|disconnect\|stop\|status` | Networked agent communication (HTTP/SSE hub) |
 
-### Inter-Agent Communication (coms & coms-net)
+### Inter-Agent Communication (coms)
 
 Two systems for Pi agents to communicate with each other, activated on-demand via slash commands:
 
@@ -94,18 +95,6 @@ Two systems for Pi agents to communicate with each other, activated on-demand vi
 /coms status
 ```
 
-**Networked (`/coms-net`)** — HTTP/SSE hub for communication across machines. Server auto-starts on localhost.
-
-```text
-/coms-net start --name dev --purpose "Development agent"
-/coms-net connect
-/coms-net disconnect
-/coms-net stop
-/coms-net status
-```
-
-For LAN/remote access, set `PI_COMS_NET_AUTH_TOKEN` and `PI_COMS_NET_HOST=0.0.0.0` in your environment.
-
 **Tools available once activated:**
 
 | Tool | Description |
@@ -212,6 +201,19 @@ Use python-expert to fix the type errors in src/models.py
 Run scout and planner in a chain to analyze the auth module
 ```
 
+**Run agent with specific model:**
+
+```bash
+# Discover available models
+list_models(provider="litellm")
+
+# Run agent with explicit model
+subagent(agent="worker", task="...", model="litellm/claude-opus-4-6-1m")
+
+# Parallel tasks with per-task models
+subagent(tasks=[{agent: "worker", task: "...", model: "litellm/claude-opus-4-6-1m", cwd: "..."}])
+```
+
 ## Code Review Loop
 
 After any code change, the orchestrator runs 6 agents **in parallel** (5 reviewers + test-automator):
@@ -224,16 +226,17 @@ After any code change, the orchestrator runs 6 agents **in parallel** (5 reviewe
 6. **test-automator** — Runs project tests (pytest, node tests, pre-commit)
 
 When `review_loop_enforcement` is enabled, the loop stops once all reviewers approve with 0 findings and tests pass
-(`tests_passed: true` in `pi-config-review-state.json`), OR after `review_loop_max_cycles` total cycles (default `3`,
+(`tests_passed: true` in `pi-config-review-state.jsonl`), OR after `review_loop_max_cycles` total cycles (default `3`,
 valid integers `1`-`10`; env: digit string `"1"`-`"10"` only (after trim)) — whichever comes first. Each cycle
 always completes fix/explain (5a) before the cap check; the cap only blocks re-dispatch
 (step 2 / all 6 agents, including test-automator), not responding to findings.
 At cap, report **Not fixed** (explained why not → outstanding) vs **Fixed**
 (verification blocked by the cap — cannot re-dispatch to confirm clean). Invalid values (including non-digit
 forms like `"10.0"` / `"1e1"`) fall through to the next resolution layer / default `3`. Disable the review loop via
-`review_loop_enforcement: false`, not via max_cycles. The max-cycles stop is via injected orchestrator rules
-(LLM compliance only); commit blocking remains code-enforced — blocked unless both `status: clean` and
-`tests_passed: true`; hitting the cycle cap does NOT bypass it.
+`review_loop_enforcement: false`, not via max_cycles. Commit blocking is code-enforced via `isCommitAllowed`:
+allows commit when `isReviewClean` (`status: clean` + `tests_passed: true`, or `status: none`), or when max cycles are exhausted
+(`status` is `has_findings` or `clean`, no pending reviewers, `cycle >= review_loop_max_cycles` — no `tests_passed` requirement).
+Review enforcement and dirty tracking are automatically skipped on `chore/bump-version-<version>` branches (e.g. `chore/bump-version-4.2.1-1234567890`, used by the release workflow).
 
 Staged mode (`--autorabbit`/`--autoqodo` in `/review-handler`) shares one total `review_loop_max_cycles` budget
 across both its Spec Compliance and Code Quality stages — not a separate cap per stage.
@@ -244,35 +247,18 @@ Use `/review-status` to inspect the current review loop state. Pass a worktree p
 
 ### Project Settings
 
-Create `.pi/pi-config-settings.json` in your project to override global defaults:
-
-```json
-{
-  "commit_trailer": "Assisted-by",
-  "allow_push_to_protected_branches": false,
-  "use_worktrees": true,
-  "dream_interval_hours": 6,
-  "review_loop_enforcement": false,
-  "review_loop_max_cycles": 3,
-  "pidash_enable": true,
-  "pidiff_enable": true,
-  "pidash_port": 19190,
-  "image_model": "gemini-3-pro-image",
-  "acpx_agents": ["cursor"],
-  "cli_agents": ["claude", "cursor"],
-  "async_llm_provider": "anthropic",
-  "async_llm_model": "claude-sonnet-4-20250514",
-  "agent_provider": "cli-cursor",
-  "agent_model": "cursor:cursor-grok-4.5-high-fast",
-  "agent_overrides": {
-    "git-expert": { "provider": null, "model": null }
-  }
-}
+Copy the example file to your project and customize:
+
+```bash
+cp pi-config-settings.example.jsonc .pi/pi-config-settings.json
 ```
 
+Settings files support JSONC (JSON with `//` comments).
+See [`pi-config-settings.example.jsonc`](pi-config-settings.example.jsonc) for all available settings with descriptions.
+
 Resolution order: project file → global `~/.pi/pi-config-settings.json` → env var → default.
 
-See `dev-docs/project-settings.md` for the full settings table and env vars.
+See `dev-docs/project-settings.md` for the full settings table.
 
 #### Reviewer Environment Variables
 
@@ -331,6 +317,17 @@ EOF
 
 Rules auto-load alphabetically. Same-filename entries are overridden (project > user > package). Missing directories are silently skipped.
 
+#### Conditional assembly
+
+Rules support settings/feature conditionals at prompt assembly (`assembleRuleText` in
+`rule-placeholders.ts`). Full syntax, truthiness, and assembly order:
+**[dev-docs/project-settings.md](dev-docs/project-settings.md)** (Rules assembly).
+
+Markers: `{{IF:key}}…{{/IF}}`, `{{IFNOT:key}}…{{/IFNOT}}`, comparisons
+`{{IF:key==value}}` / `{{IF:key!=value}}`. Whole-file frontmatter: `requires_setting` /
+`requires`. Conditionals run **per file** (no cross-file matching), then bodies are
+joined, then placeholders like `{{REVIEW_LOOP_MAX_CYCLES}}` are substituted.
+
 ### Add project agents
 
 Create `.pi/agents/my-agent.md` in your project with frontmatter:
@@ -357,7 +354,7 @@ Set `image_model` in `pi-config-settings.json` or use `PI_IMAGE_MODEL` env var.
 
 | Setting / Variable | Description |
 |----------|-------------|
-| `image_model` / `PI_IMAGE_MODEL` | Gemini model name (e.g., `gemini-3-pro-image`). No default. |
+| `image_model` / `PI_IMAGE_MODEL` | Google/Gemini image model for `generate_image` (Settings TUI filters to google; empty = disabled). |
 | `GEMINI_API_KEY` or `GOOGLE_API_KEY` | Gemini API key (env only) |
 
 **Usage:** Ask naturally — "generate an image of a sunset" — or use structured params: `subject`, `action`, `scene`, `composition`, `lighting`, `style`, `text`, `aspect_ratio`.
@@ -390,8 +387,15 @@ Run pi inside a disposable container for **filesystem isolation** — the agent
 `agent` (Cursor Agent CLI). Enable with `cli_agents` in settings (e.g.
 `["claude","cursor","gemini"]`). Binary missing at load → `cli-*` not registered.
 After register, `filterModels` hides models when unavailable: PATH cleared while
-agent state remains → restore PATH; after `session_shutdown` (AgentState cleared)
-→ `/reload` or restart (PATH alone is not enough). See `dev-docs/cli-provider.md`.
+agent state remains, restore PATH; after `session_shutdown` (AgentState cleared
+and `initialized` reset) the next factory re-registers on `/new`|`/resume`|`/fork`
+(PATH alone is not enough). See `dev-docs/cli-provider.md`.
+
+**ACPX provider agents (optional `acpx_agents`):** ACPX wraps CLI agents via the
+ACP runtime. Supported agents: `cursor`, `claude`, `gemini`. Enable with
+`acpx_agents` in settings (e.g. `["cursor","claude","gemini"]`). Each ACPX agent
+requires the underlying CLI binary on PATH (`agent` for cursor, `claude` for claude,
+`gemini` for gemini) — missing binary → `acpx-*` not registered.
 
 **CLI specialist agents (Cursor / Claude / Gemini):** On container start, `entrypoint.sh`
 symlinks package `agents/*.md` into the mounted project:
@@ -443,7 +447,9 @@ docker run --rm -it \
 
 ### Environment file
 
-Create a `.env` file with container-specific variables:
+Create a `.env` file with external service credentials and container-specific
+variables. Pi-config settings (image_model, acpx_agents, vertex_claude_1m, etc.)
+go in `.pi/pi-config-settings.json` — not here:
 
 ```env
 # Timezone (host timezone for correct timestamps)
@@ -456,9 +462,6 @@ PI_HOST_USER=myakove
 GOOGLE_CLOUD_PROJECT=your-project-id
 GOOGLE_CLOUD_LOCATION=us-east5
 GOOGLE_APPLICATION_CREDENTIALS=/home/myakove/.config/gcloud/application_default_credentials.json
-VERTEX_PROJECT_ID=your-project-id
-VERTEX_REGION=us-east5
-VERTEX_CLAUDE_1M=true
 
 # GitHub
 GITHUB_TOKEN=ghp_xxx
@@ -468,12 +471,6 @@ GH_CONFIG_DIR=/home/myakove/.config/gh
 # Gemini (optional — required for image generation)
 GEMINI_API_KEY=xxx
 
-# Image generation model (required for generate_image tool)
-PI_IMAGE_MODEL=gemini-3-pro-image
-
-# acpx agents (optional)
-# ACPX_AGENTS=cursor
-
 # mcpl (MCP Launchpad) config path inside the container (must match mount target)
 # Use your actual home path — it resolves inside the container via the PI_HOST_USER symlink
 MCPL_CONFIG_FILES=/home/myakove/.config/mcpl/mcp.json
@@ -512,7 +509,8 @@ Pidash is a web-based dashboard that runs alongside the TUI, accessible from any
 **How it works:**
 
 - A daemon (`pidash-server.ts`) runs on port `19190` and aggregates all pi sessions
-- Each pi session's extension (`pidash.ts`) connects to the daemon and forwards events
+- Each interactive pi session's extension (`pidash.ts`) connects to the daemon and forwards events
+- Oneshot (`pi -p` / `--print` / `--mode json`) skips pidash register, so no session connects
 - The React web UI shows live conversations, tool calls, and session status
 
 **Features:**
@@ -550,6 +548,10 @@ PI_PIDASH_PORT=9999 pi
 PI_PIDASH_ENABLE=false pi
 ```
 
+Oneshot (`pi -p` / `--print` / `--mode json`) skips register of pidash, pidiff,
+pitasks, and coms so those daemons/watchers do not start. CLI and ACPX providers
+still load. `--mode rpc` is long-lived and is not skipped.
+
 **Management:**
 
 ```bash
@@ -574,7 +576,8 @@ Pidiff is a per-project diff viewer that opens in your browser, providing rich b
 
 **How it works:**
 
-- Each pi session spawns its own server (`pidiff-server.ts`) on a random free port
+- Each interactive pi session spawns its own server (`pidiff-server.ts`) on a random free port
+- Oneshot (`pi -p` / `--print` / `--mode json`) skips pidiff register, so no per-session server starts
 - Container and native sessions get separate servers automatically
 - Lockfiles in `.pi/tmp/` track port and PID for each server
 - The extension (`pidiff.ts`) connects to its session's server and registers its repo
@@ -615,7 +618,8 @@ PI_PIDIFF_ENABLE=false pi
 | `-v "<PATH_TO_MCPL_CONFIG>":"$HOME/.config/mcpl/mcp.json":ro` | MCP server config for `mcpl` |
 | `-v "$HOME/.agents":"$HOME/.agents":rw` | User-level skills (install/uninstall from container) |
 | `-v "$HOME/.config/gcloud/application_default_credentials.json":"$HOME/.config/gcloud/application_default_credentials.json":ro` | Google Cloud ADC (for Claude via Vertex AI) |
-| `-v "$HOME/.config/cursor/auth.json":"$HOME/.config/cursor/auth.json":ro` | Cursor CLI auth (for acpx cursor models) |
+| `-v "$HOME/.config/cursor/auth.json":"$HOME/.config/cursor/auth.json":ro` | Cursor CLI auth (for acpx-cursor / cli-cursor models) |
+| `-v "$HOME/.claude/credentials.json":"$HOME/.claude/credentials.json":ro` | Claude CLI auth (for acpx-claude / cli-claude models) |
 | `-v "$HOME/.config/glab-cli":"$HOME/.config/glab-cli":ro` | GitLab CLI config (auth tokens, host settings) |
 | `-v "$HOME/.coderabbit":"$HOME/.coderabbit":rw` | CodeRabbit CLI auth and review data |
 | `-v "$HOME/screenshots":"$HOME/screenshots"` | Share screenshots/images with the agent |
@@ -630,8 +634,10 @@ PI_PIDIFF_ENABLE=false pi
 | `git` | Version control |
 | `gh` | GitHub CLI (PRs, issues) |
 | `glab` | GitLab CLI (MRs, issues, pipelines) — install [gitlab-cli-skills](https://github.com/vince-winkintel/gitlab-cli-skills) for full agent support |
+| `gcc` | C compiler — needed for building Python C extensions (e.g. ovirt-engine-sdk-python) |
 | `uv` / `uvx` | Python execution (enforced by orchestrator) |
 | `go` | Go development and code review |
+| `libxml2-dev` | libxml2 headers — needed for building Python C extensions (e.g. ovirt-engine-sdk-python) |
 | `mcpl` | MCP server access (search, Jenkins, etc.) |
 | `myk-pi-tools` | PR review, release, and other CLI utilities |
 | `prek` | Pre-commit hook runner |
@@ -663,7 +669,8 @@ PI_PIDIFF_ENABLE=false pi
 | `myk-pi-tools reviews` | Review handling commands |
 | `myk-pi-tools memory` | Project memory commands — persistent per-repo learning |
 | `myk-pi-tools ai-cli` | AI CLI commands (cursor, claude, gemini) |
-| `myk-pi-tools coderabbit` | CodeRabbit commands |
+| `myk-pi-tools coderabbit` | CodeRabbit commands (check, trigger, retry) |
+| `myk-pi-tools settings get [key ...]` | Resolve settings (project → global → env → default). No args = all keys |
 
 ### What's protected
 
@@ -704,6 +711,7 @@ alias pi-docker='docker pull ghcr.io/myk-org/pi-config:latest && \
   -v "$HOME/.agents":"$HOME/.agents":rw \
   -v "$HOME/.config/gcloud/application_default_credentials.json":"$HOME/.config/gcloud/application_default_credentials.json":ro \
   -v "$HOME/.config/cursor/auth.json":"$HOME/.config/cursor/auth.json":ro \
+  -v "$HOME/.claude/credentials.json":"$HOME/.claude/credentials.json":ro \
   -v "$HOME/.config/glab-cli":"$HOME/.config/glab-cli":ro \
   -v "$HOME/screenshots":"$HOME/screenshots":ro \
   -v /var/run/docker.sock:/var/run/docker.sock:ro \
@@ -783,7 +791,7 @@ See [DEVELOPMENT.md](DEVELOPMENT.md) for tips on testing extensions locally, run
 
 ## Prerequisites
 
-- [pi](https://github.com/badlogic/pi-mono) (minimum version: **0.81.0**)
+- [pi](https://github.com/badlogic/pi-mono) (minimum version: **0.84.0**)
 - `gh` CLI (for GitHub operations)
 - `uv` (for Python execution)
 - `myk-pi-tools` (optional, for `/pr-review` and `/release`)
@@ -802,6 +810,7 @@ A standalone HTTP sidecar wrapping the Pi SDK, living under `packages/pi-sidecar
 CLI commands: `npx pi-sidecar` (start server), `npx pi-sidecar-start` (background start/stop).
 
 See [`packages/pi-sidecar/README.md`](packages/pi-sidecar/README.md) for full documentation.
+See [`packages/pi-sidecar/CONSUMER-GUIDE.md`](packages/pi-sidecar/CONSUMER-GUIDE.md) for integration best practices.
 
 ### pi-vertex-claude
 

package/agents/code-reviewer-docs.md

@@ -11,7 +11,7 @@ You are a code review specialist focused on **documentation quality, completenes
 - Execute first, explain after
 - Do NOT modify files — only review and report findings
 - If a task falls outside your domain, report it and hand off
-- Get the diff with `git diff origin/$PI_REVIEW_BASE_BRANCH...HEAD`
+- Get the diff with `git diff origin/$PI_REVIEW_BASE_BRANCH` (includes uncommitted changes)
 
 ## Project Guidelines (MANDATORY — read before reviewing)
 
@@ -143,3 +143,13 @@ If no issues: `{"findings": []}`
 Severity values: `CRITICAL`, `WARNING`, `SUGGESTION`
 
 After writing your response, validate it is parseable JSON.
+
+## Prior Review Cycle
+
+If your prompt includes a `<prior-review-cycle>` block with previous findings and responses:
+
+- **Fixed findings** → verify the fix is correct. Do NOT re-raise if the fix addresses the issue.
+- **Explained findings** → accept valid technical explanations. Only re-raise if the explanation is factually wrong (state why in the finding description field).
+- **Focus on NEW issues** not covered in prior cycles.
+
+Do NOT repeat findings that were adequately addressed. All output MUST remain JSON-only — no prose outside the JSON object.

package/agents/code-reviewer-guidelines.md

@@ -11,7 +11,7 @@ You are a code review specialist focused on **project guidelines and style adher
 - Execute first, explain after
 - Do NOT modify files — only review and report findings
 - If a task falls outside your domain, report it and hand off
-- Get the diff with `git diff origin/$PI_REVIEW_BASE_BRANCH...HEAD`
+- Get the diff with `git diff origin/$PI_REVIEW_BASE_BRANCH` (includes uncommitted changes)
 
 ## Review Focus
 
@@ -95,3 +95,13 @@ If no issues: `{"findings": []}`
 Severity values: `CRITICAL`, `WARNING`, `SUGGESTION`
 
 After writing your response, validate it is parseable JSON.
+
+## Prior Review Cycle
+
+If your prompt includes a `<prior-review-cycle>` block with previous findings and responses:
+
+- **Fixed findings** → verify the fix is correct. Do NOT re-raise if the fix addresses the issue.
+- **Explained findings** → accept valid technical explanations. Only re-raise if the explanation is factually wrong (state why in the finding description field).
+- **Focus on NEW issues** not covered in prior cycles.
+
+Do NOT repeat findings that were adequately addressed. All output MUST remain JSON-only — no prose outside the JSON object.

package/agents/code-reviewer-quality.md

@@ -11,7 +11,7 @@ You are a code review specialist focused on **general code quality and maintaina
 - Execute first, explain after
 - Do NOT modify files — only review and report findings
 - If a task falls outside your domain, report it and hand off
-- Get the diff with `git diff origin/$PI_REVIEW_BASE_BRANCH...HEAD`
+- Get the diff with `git diff origin/$PI_REVIEW_BASE_BRANCH` (includes uncommitted changes)
 
 ## Project Guidelines (MANDATORY — read before reviewing)
 
@@ -140,3 +140,13 @@ If no issues: `{"findings": []}`
 Severity values: `CRITICAL`, `WARNING`, `SUGGESTION`
 
 After writing your response, validate it is parseable JSON.
+
+## Prior Review Cycle
+
+If your prompt includes a `<prior-review-cycle>` block with previous findings and responses:
+
+- **Fixed findings** → verify the fix is correct. Do NOT re-raise if the fix addresses the issue.
+- **Explained findings** → accept valid technical explanations. Only re-raise if the explanation is factually wrong (state why in the finding description field).
+- **Focus on NEW issues** not covered in prior cycles.
+
+Do NOT repeat findings that were adequately addressed. All output MUST remain JSON-only — no prose outside the JSON object.

package/agents/code-reviewer-security.md

@@ -11,7 +11,7 @@ You are a code review specialist focused on **bugs, logic errors, and security v
 - Execute first, explain after
 - Do NOT modify files — only review and report findings
 - If a task falls outside your domain, report it and hand off
-- Get the diff with `git diff origin/$PI_REVIEW_BASE_BRANCH...HEAD`
+- Get the diff with `git diff origin/$PI_REVIEW_BASE_BRANCH` (includes uncommitted changes)
 
 ## Review Focus
 
@@ -105,3 +105,13 @@ If no issues: `{"findings": []}`
 Severity values: `CRITICAL`, `WARNING`, `SUGGESTION`
 
 After writing your response, validate it is parseable JSON.
+
+## Prior Review Cycle
+
+If your prompt includes a `<prior-review-cycle>` block with previous findings and responses:
+
+- **Fixed findings** → verify the fix is correct. Do NOT re-raise if the fix addresses the issue.
+- **Explained findings** → accept valid technical explanations. Only re-raise if the explanation is factually wrong (state why in the finding description field).
+- **Focus on NEW issues** not covered in prior cycles.
+
+Do NOT repeat findings that were adequately addressed. All output MUST remain JSON-only — no prose outside the JSON object.

package/agents/code-reviewer-spec.md

@@ -11,7 +11,7 @@ You are a code review specialist focused on **spec compliance — alignment betw
 - Execute first, explain after
 - Do NOT modify files — only review and report findings
 - If a task falls outside your domain, report it and hand off
-- Get the diff with `git diff origin/$PI_REVIEW_BASE_BRANCH...HEAD`
+- Get the diff with `git diff origin/$PI_REVIEW_BASE_BRANCH` (includes uncommitted changes)
 - You MUST run `gh pr view` and `gh issue view` commands every time — even if you think you already have the data from a prior turn. Prior turn data is STALE.
 - If `$PI_HAS_PR` is `false`, this is a pre-push review — no PR exists yet. Follow the reduced flow in Step 1.
 
@@ -162,3 +162,13 @@ If no issues: `{"findings": []}`
 Severity values: `SUGGESTION`
 
 After writing your response, validate it is parseable JSON.
+
+## Prior Review Cycle
+
+If your prompt includes a `<prior-review-cycle>` block with previous findings and responses:
+
+- **Fixed findings** → verify the fix is correct. Do NOT re-raise if the fix addresses the issue.
+- **Explained findings** → accept valid technical explanations. Only re-raise if the explanation is factually wrong (state why in the finding description field).
+- **Focus on NEW issues** not covered in prior cycles.
+
+Do NOT repeat findings that were adequately addressed. All output MUST remain JSON-only — no prose outside the JSON object.

package/agents/git-expert.md

@@ -13,9 +13,48 @@ You are a Git Expert responsible for all local git operations and version contro
 - Do NOT ask for confirmation — execute directly
 - If a task falls outside your domain, report it and hand off
 
+## Review Loop Enforcement
+
+{{SETTINGS:review_loop_enforcement,review_loop_max_cycles}}
+
+Before ANY `git commit`, if `review_loop_enforcement` is `true`:
+
+**Skip this check entirely if the current branch starts with `chore/bump-version`** (release version bump only).
+
+1. Read `.pi/data/pi-config-review-state.jsonl` (use the `read` tool, NOT `cat`/`grep`).
+   This is a JSONL file (one JSON object per line); parse the **last valid JSON object line**
+   (skip any truncated or corrupt trailing lines) to get current state.
+
+2. **BLOCK the commit unless one of the allow cases in step 4 holds.**
+   Common block reasons: `status` is `"needs_review"` / `"in_progress"`,
+   `status` is `"clean"` with `tests_passed: false` (does **not** block the max-cycle path),
+   `reviewers_pending` is not empty,
+   or `has_findings` but `cycle` still below `review_loop_max_cycles`.
+
+3. When blocking, report: "⛔ Review loop incomplete (status: X, tests_passed: Y). Run the review loop before committing." and STOP — do NOT proceed with the commit.
+
+4. **Only commit when:**
+   - Status is `"clean"` with `tests_passed: true`, OR
+   - Status is `"none"` (no review tracking), OR
+   - Max cycles exhausted: status is `"has_findings"`, `"clean"`, or `"needs_review"`,
+     `reviewers_pending` is empty, and `cycle` >= `review_loop_max_cycles`. No `tests_passed` requirement.
+
+## Project Settings
+
+{{SETTINGS:dco,commit_trailer,use_worktrees,allow_push_to_protected_branches}}
+
+- If `dco` is `true`: add `--signoff` to `git commit`. Skip if already present.
+- If `commit_trailer` is a string (e.g. `"Assisted-by"`): append trailer to the commit message.
+  Format: `TRAILER: PI (MODEL) <noreply@pi.dev>` using `$PI_MODEL` for model. Skip if already present.
+  If the value contains commas, use the first name.
+- If `use_worktrees` is `true`: BLOCK `git checkout` (except `git checkout -- <file>`) and `git switch`.
+  Use `git worktree add .worktrees/NAME -b BRANCH DEFAULT_BRANCH` instead
+  (detect default branch via `git symbolic-ref refs/remotes/origin/HEAD`, fallback to `main`).
+- If `allow_push_to_protected_branches` is `true`: commits and pushes to main/master are allowed.
+
 ## Protection Rules
 
-- NEVER commit or push to main/master branch
+- NEVER commit or push to main/master branch (unless `allow_push_to_protected_branches` is `true` — see Project Settings)
 - NEVER commit to already-merged branches
 - NEVER use `--no-verify` flag
 - Branch prefixes: `feature/`, `fix/`, `hotfix/`, `refactor/`
@@ -38,7 +77,7 @@ Format rules:
 - First line: Clear, concise title (50 chars or less)
 - Blank line separator
 - Body: Detailed explanation if needed
-- NO attribution — no Claude/AI signatures whatsoever
+- NO ad-hoc AI signatures. When `commit_trailer` is configured, append that trailer only (see Project Settings)
 
 ## Standard Workflows
 
@@ -51,7 +90,7 @@ Format rules:
 
 **Create branch and push:**
 
-1. `git checkout -b branch-name`
+1. `git checkout -b branch-name` (if `use_worktrees` is enabled: `git worktree add .worktrees/NAME -b BRANCH DEFAULT_BRANCH`)
 2. Verify changes committed
 3. `git push -u origin branch-name`
 

package/agents/github-expert.md

@@ -27,6 +27,17 @@ This agent does NOT run tests. When tests are required (e.g., before creating a
 1. Ask orchestrator: "Have all tests passed?"
 2. If NO/UNKNOWN: "Please delegate to test-runner, then call me again"
 
+## Project Settings
+
+{{SETTINGS:comment_signature}}
+
+- If `comment_signature` is `true`: append a signature to every GitHub body you write —
+  PR/issue **create**, **edit --body**, and **comment**.
+  Format: `\n\n---\n*Assisted-by: PI (<model>)*` using `$PI_MODEL` for model.
+  If `$PI_COMMENT_SIGNATURE` is set, use: `\n\n---\n*$PI_COMMENT_SIGNATURE*`.
+  Skip if the body already contains `Assisted-by`.
+  Runtime enforcement also injects this on `gh pr|issue create|comment|edit` `--body` / heredoc.
+
 ## Core Operations
 
 ### Pull Requests

package/extensions/acpx-provider/runtime-models.ts

@@ -4,6 +4,10 @@
  */
 
 import { buildRuntimeModel } from "../shared/create-runtime-provider.js";
+import {
+	fillRuntimeModelFromCatalog,
+	type ModelsDevCatalog,
+} from "../shared/models-dev.js";
 
 export function modelIdToDisplayName(modelId: string): string {
 	// Strip bracket suffixes for display: gpt-5.4[context=272k,...] -> Gpt 5.4
@@ -17,6 +21,7 @@ export function modelIdToDisplayName(modelId: string): string {
 export function mapAcpxDiscoveredModels(
 	agent: string,
 	modelIds: readonly string[],
+	catalog?: ModelsDevCatalog | null,
 ): ReturnType<typeof buildRuntimeModel>[] {
 	const provider = `acpx-${agent}`;
 	if (modelIds.length === 0) {
@@ -30,11 +35,18 @@ export function mapAcpxDiscoveredModels(
 		];
 	}
 	return modelIds.map((m) =>
-		buildRuntimeModel({
-			id: `${agent}:${m}`,
-			name: `${modelIdToDisplayName(m)} (${agent})`,
-			api: "acpx",
-			provider,
-		}),
+		buildRuntimeModel(
+			fillRuntimeModelFromCatalog(
+				{
+					id: `${agent}:${m}`,
+					name: `${modelIdToDisplayName(m)} (${agent})`,
+					api: "acpx",
+					provider,
+				},
+				catalog,
+				agent,
+				m,
+			),
+		),
 	);
 }

package/extensions/cli-provider/agents/claude.ts

@@ -3,7 +3,8 @@
  */
 
 import { closeSync, openSync, readSync, statSync } from "node:fs";
-import { cliProviderLog } from "../../shared/file-logger.js";
+import { createLogger } from "../../shared/logger.js";
+const log = createLogger("cli_provider");
 import type { CliProviderDef, DiscoveredCliModel } from "../types.js";
 import {
   cacheKeyForFile,
@@ -97,7 +98,7 @@ function discoverClaudeModels(): DiscoveredCliModel[] {
     if (models.length > 0) writeModelCache(key, models);
     return models;
   } catch (err) {
-    cliProviderLog("error", "claude: binary catalog failed", err);
+    log.error("claude: binary catalog failed", err);
     return [];
   }
 }

package/extensions/cli-provider/agents/cursor.ts

@@ -5,7 +5,8 @@
  */
 
 import { spawnSync } from "node:child_process";
-import { cliProviderLog } from "../../shared/file-logger.js";
+import { createLogger } from "../../shared/logger.js";
+const log = createLogger("cli_provider");
 import type { CliProviderDef, DiscoveredCliModel } from "../types.js";
 import { resolveBinary } from "../shared/discover-cache.js";
 
@@ -48,10 +49,7 @@ function discoverCursorModels(): DiscoveredCliModel[] {
   const out = `${r.stdout || ""}\n${r.stderr || ""}`;
   const models = parseAgentListModels(out);
   if (models.length === 0) {
-    cliProviderLog(
-      "warn",
-      `cursor: --list-models failed (status=${r.status}): ${out.slice(0, 200)}`,
-    );
+    log.warn(`cursor: --list-models failed (status=${r.status}): ${out.slice(0, 200)}`);
   }
   return models;
 }

package/extensions/cli-provider/agents/gemini.ts

@@ -9,7 +9,8 @@ import {
   statSync,
 } from "node:fs";
 import { dirname, join } from "node:path";
-import { cliProviderLog } from "../../shared/file-logger.js";
+import { createLogger } from "../../shared/logger.js";
+const log = createLogger("cli_provider");
 import type { CliProviderDef, DiscoveredCliModel } from "../types.js";
 import {
   cacheKeyForFile,
@@ -71,7 +72,7 @@ function discoverGeminiModels(): DiscoveredCliModel[] {
     if (models.length > 0) writeModelCache(key, models);
     return models;
   } catch (err) {
-    cliProviderLog("error", "gemini: CLI bundle parse failed", err);
+    log.error("gemini: CLI bundle parse failed", err);
     return [];
   }
 }