pi-orchestrator-config 4.1.5 → 4.2.1

package/README.md

@@ -12,8 +12,9 @@ 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`) |
+| **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.81): `/login cli-<agent>` or `/login acpx-<agent>`, model refresh, filter when unavailable |
 | **`/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 |
@@ -212,6 +213,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):
@@ -231,9 +245,9 @@ always completes fix/explain (5a) before the cap check; the cap only blocks re-d
 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).
 
 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.
@@ -260,8 +274,8 @@ Create `.pi/pi-config-settings.json` in your project to override global defaults
   "image_model": "gemini-3-pro-image",
   "acpx_agents": ["cursor"],
   "cli_agents": ["claude", "cursor"],
-  "async_llm_provider": "anthropic",
-  "async_llm_model": "claude-sonnet-4-20250514",
+  "internal_operations_provider": "anthropic",
+  "internal_operations_model": "claude-sonnet-4-20250514",
   "agent_provider": "cli-cursor",
   "agent_model": "cursor:cursor-grok-4.5-high-fast",
   "agent_overrides": {
@@ -630,8 +644,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 +679,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
 
@@ -802,6 +819,17 @@ 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
+
+Google Vertex AI Claude provider for Pi, living under `packages/pi-vertex-claude/`.
+
+| Package | Language | Registry |
+|---------|----------|----------|
+| `@myk-org/pi-vertex-claude` | TypeScript | npm |
+
+See [`packages/pi-vertex-claude/README.md`](packages/pi-vertex-claude/README.md) for full documentation.
 
 ## License
 

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,44 @@ 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`:
+
+1. Read `.pi/data/pi-config-review-state.json` (use the `read` tool, NOT `cat`/`grep`) and check the 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 +73,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 +86,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,14 @@ 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 PR/issue comment body.
+  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*`.
+
 ## Core Operations
 
 ### Pull Requests

package/extensions/orchestrator/async-agents.ts

@@ -7,6 +7,7 @@ import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
 import { createRequire } from "node:module";
+import { fileURLToPath } from "node:url";
 
 const require = createRequire(import.meta.url);
 
@@ -16,12 +17,23 @@ import { discoverAgents } from "./agents.js";
 import { resolveAgentModelProvider } from "./resolve-agent-model.js";
 import { getPiInvocation, getProjectTmpDir, parseProcStartTime, djb2Hash } from "./utils.js";
 import { addReviewerPending, recordReviewerResult, countFindings, readReviewState, markTestsPassed, markTestsFailed } from "./pi-config-review-state.js";
-import { getMainBranch } from "./git-helpers.js";
+import {
+  getMainBranch,
+} from "./git-helpers.js";
 import { waitForResultFiles } from "./async-wait.js";
 import { openAsyncStatusOverlay } from "./async-status-ui.js";
 export { autoCompleteTask, autoMarkInProgress } from "./task-lifecycle.js";
 import { autoCompleteTask, autoMarkInProgress } from "./task-lifecycle.js";
 import { setSlot } from "./status-bar.js";
+import { getSetting } from "./project-settings.js";
+import { substituteSettingsPlaceholders } from "./rule-placeholders.js";
+
+const SETTINGS_KEYS: Record<string, unknown> = JSON.parse(
+  fs.readFileSync(
+    path.join(path.dirname(fileURLToPath(import.meta.url)), "..", "..", "settings-keys.json"),
+    "utf-8",
+  ),
+);
 
 // ── Constants ────────────────────────────────────────────────────────────
 
@@ -101,7 +113,7 @@ export function registerAsyncAgents(
   pi: ExtensionAPI,
   terminalNotify: (title: string, body: string) => void,
 ): {
-  spawnAsyncAgent: (agentName: string, task: string, cwd: string, agents: AgentConfig[], options?: { fireAndForget?: boolean; name?: string; parentModelId?: string; parentProvider?: string; groupId?: string; taskId?: string; onComplete?: () => void; persistSession?: boolean }) => { id: string; error?: string; model?: string };
+  spawnAsyncAgent: (agentName: string, task: string, cwd: string, agents: AgentConfig[], options?: { fireAndForget?: boolean; name?: string; parentModelId?: string; parentProvider?: string; groupId?: string; taskId?: string; onComplete?: () => void; persistSession?: boolean; explicit?: { model?: string; provider?: string } }) => { id: string; error?: string; model?: string };
   killAsyncAgent: (target: string) => { killed: string[]; errors: string[] };
   getAsyncJobs: () => Array<{ id: string; agent: string; name?: string; task: string; status: string; startedAt: number }>;
 } {
@@ -193,7 +205,7 @@ export function registerAsyncAgents(
                   job.updatedAt = Date.now();
                   if (job.agent.startsWith("code-reviewer-")) {
                     const findings = countFindings(typeof data.output === "string" ? data.output : "");
-                    try { recordReviewerResult(jobCwd(job), job.agent, findings < 0 ? 1 : findings); } catch {}
+                    try { recordReviewerResult(jobCwd(job), job.agent, findings < 0 ? 1 : findings); } catch (e: any) { asyncLog(`recordReviewerResult failed for ${job.agent}: ${e?.message}`); }
                   }
                   try { fs.unlinkSync(resultFilePath); } catch {}
                 } catch {
@@ -202,7 +214,7 @@ export function registerAsyncAgents(
                   job.durationMs = Date.now() - job.startedAt;
                   job.updatedAt = Date.now();
                   if (job.agent.startsWith("code-reviewer-")) {
-                    try { recordReviewerResult(jobCwd(job), job.agent, 0); } catch {}
+                    try { recordReviewerResult(jobCwd(job), job.agent, 0); } catch (e: any) { asyncLog(`recordReviewerResult failed for ${job.agent}: ${e?.message}`); }
                   }
                 }
               } else {
@@ -212,7 +224,7 @@ export function registerAsyncAgents(
                 job.updatedAt = Date.now();
                 // Record killed reviewer as having 0 findings — prevents permanent commit block
                 if (job.agent.startsWith("code-reviewer-")) {
-                  try { recordReviewerResult(jobCwd(job), job.agent, 0); } catch { /* best-effort */ }
+                  try { recordReviewerResult(jobCwd(job), job.agent, 0); } catch (e: any) { asyncLog(`recordReviewerResult failed for ${job.agent}: ${e?.message}`); }
                 }
               }
               // Check if this completes a group — deliver remaining siblings' results
@@ -260,7 +272,6 @@ export function registerAsyncAgents(
     // Ingest any unprocessed result files — zombie/kill paths may trigger delivery
     // before processResultFile() has read all group members' outputs.
     // Wait up to 2s total (not per-job) for all missing result files.
-    const lateIngestedIds = new Set<string>();
     // Wait for non-failed, non-fireAndForget jobs that haven't been ingested yet
     const waitJobs = groupJobs.filter(j => j.output === undefined && !j.fireAndForget && j.status !== "failed");
     if (waitJobs.length > 0) {
@@ -277,21 +288,33 @@ export function registerAsyncAgents(
         j.exitCode = data.exitCode;
         j.durationMs = data.durationMs;
         if (data.success !== undefined) j.status = data.success ? "complete" : "failed";
-        lateIngestedIds.add(j.id);
         asyncLog(`deliverGroupResults: late-ingested result for ${j.id}`);
       } catch (e: any) { asyncLog(`deliverGroupResults: late-ingest failed for ${j.id}: ${e?.message}`); }
     }
 
-    // Track reviewer completions for late-ingested code-reviewer jobs only
-    // (jobs already processed by processResultFile were tracked there)
+    // Track reviewer completions for ALL code-reviewer jobs in the group.
+    // processResultFile may have already called recordReviewerResult for some,
+    // but recordReviewerResult is idempotent (skips if reviewer already reported).
     for (const j of groupJobs) {
-      if (!j.agent.startsWith("code-reviewer-") || !lateIngestedIds.has(j.id)) continue;
+      if (!j.agent.startsWith("code-reviewer-")) continue;
       try {
         const output = typeof j.output === "string" ? j.output : "";
         const findings = countFindings(output);
         // -1 means invalid JSON output — treat conservatively as having findings
         recordReviewerResult(jobCwd(j), j.agent, findings < 0 ? 1 : findings);
-      } catch { /* best-effort */ }
+      } catch (e: any) { asyncLog(`recordReviewerResult failed for ${j.agent}: ${e?.message}`); }
+    }
+
+    // Track test agent completions for grouped test-automator/test-runner
+    for (const j of groupJobs) {
+      if (j.agent !== "test-automator" && j.agent !== "test-runner") continue;
+      try {
+        if (j.status === "complete") {
+          markTestsPassed(jobCwd(j));
+        } else if (j.status === "failed") {
+          markTestsFailed(jobCwd(j));
+        }
+      } catch (e: any) { asyncLog(`markTests failed for ${j.agent}: ${e?.message}`); }
     }
 
     // Skip delivery if ALL jobs in group are fire-and-forget
@@ -364,8 +387,16 @@ export function registerAsyncAgents(
       const data = JSON.parse(fs.readFileSync(resultPath, "utf-8"));
       const job = asyncState.jobs.get(data.id);
       asyncLog(`processResultFile: ${path.basename(resultPath)} job=${!!job} delivered=${job?.delivered} hasCtx=${!!asyncState.lastCtx} fireAndForget=${job?.fireAndForget} groupId=${job?.groupId}`);
-      if (!job) return;
-      if (job.delivered) return; // Already delivered to user
+      if (!job) {
+        // Orphan result file — job not in current session. Clean up to prevent re-delivery on reload.
+        try { fs.unlinkSync(resultPath); } catch (e: any) { asyncLog(`orphan cleanup failed: ${resultPath}: ${e?.message}`); }
+        return;
+      }
+      if (job.delivered) {
+        // Already delivered — clean up stale file
+        try { fs.unlinkSync(resultPath); } catch (e: any) { asyncLog(`stale cleanup failed: ${resultPath}: ${e?.message}`); }
+        return;
+      }
       // Skip if already ingested (grouped jobs stay on disk until group delivers)
       if (job.output !== undefined) return;
 
@@ -387,7 +418,7 @@ export function registerAsyncAgents(
           const findings = countFindings(output);
           // -1 means invalid JSON output — treat conservatively as having findings
           recordReviewerResult(jobCwd(job), job.agent, findings < 0 ? 1 : findings);
-        } catch { /* best-effort */ }
+        } catch (e: any) { asyncLog(`recordReviewerResult failed for ${job.agent}: ${e?.message}`); }
         // Clear reviewer session if context usage > 80% to prevent overflow on next cycle
         // Use model context window from the agent's effective model.
         // If agent uses a custom model, we pass its context window via the config.
@@ -513,7 +544,7 @@ export function registerAsyncAgents(
     task: string,
     cwd: string,
     agents: AgentConfig[],
-    options?: { fireAndForget?: boolean; name?: string; parentModelId?: string; parentProvider?: string; groupId?: string; taskId?: string; onComplete?: () => void; persistSession?: boolean },
+    options?: { fireAndForget?: boolean; name?: string; parentModelId?: string; parentProvider?: string; groupId?: string; taskId?: string; onComplete?: () => void; persistSession?: boolean; explicit?: { model?: string; provider?: string } },
   ): { id: string; error?: string; model?: string } {
     const agent = agents.find(a => a.name === agentName);
     if (!agent) return { id: "", error: `Unknown agent: "${agentName}"` };
@@ -536,6 +567,7 @@ export function registerAsyncAgents(
     if (!parentStartTime) {
       console.debug("[async-agents] WARNING: could not read /proc/self/stat starttime after 3 attempts");
     }
+    const { model: effectiveModel, provider: effectiveProvider } = resolveAgentModelProvider(agentName, agent, options?.parentModelId, options?.parentProvider, cwd, options?.explicit);
     fs.writeFileSync(path.join(workerDir, "session.json"), JSON.stringify({
       resultsDir: ASYNC_RESULTS_DIR,
       fireAndForget: options?.fireAndForget || false,
@@ -572,14 +604,18 @@ export function registerAsyncAgents(
       : agentName + ':' + task.slice(0, 100);
     const deterministicSessionId = `async-${agentName}-${djb2Hash(sessionIdSource).toString(36)}`;
     piArgs.push("--session-id", deterministicSessionId);
-    const { model: effectiveModel, provider: effectiveProvider } = resolveAgentModelProvider(agentName, agent, options?.parentModelId, options?.parentProvider, cwd);
     if (effectiveModel) piArgs.push("--model", effectiveModel);
     if (effectiveProvider) piArgs.push("--provider", effectiveProvider);
     if (agent.tools?.length) piArgs.push("--tools", agent.tools.join(","));
 
     if (agent.systemPrompt?.trim()) {
       const promptPath = path.join(workerDir, "system-prompt.md");
-      fs.writeFileSync(promptPath, agent.systemPrompt, { mode: 0o600 });
+      const resolvedPrompt = substituteSettingsPlaceholders(
+        agent.systemPrompt,
+        (key) => getSetting(cwd, key as any),
+        Object.keys(SETTINGS_KEYS),
+      );
+      fs.writeFileSync(promptPath, resolvedPrompt, { mode: 0o600 });
       piArgs.push("--append-system-prompt", promptPath);
     }
 
@@ -664,14 +700,8 @@ export function registerAsyncAgents(
       }
     }
 
-    const proc = spawn(process.execPath, spawnArgs, {
-      cwd,
-      stdio: "ignore",
-      windowsHide: true,
-      env: spawnEnv,
-    });
-
-    // Track the job
+    // Register job BEFORE spawn — child can finish and write result file before
+    // jobs.set runs; watcher/poller would then treat it as orphan and delete it.
     const job: AsyncJob = {
       id,
       agent: agentName,
@@ -692,6 +722,13 @@ export function registerAsyncAgents(
     };
     asyncState.jobs.set(id, job);
 
+    const proc = spawn(process.execPath, spawnArgs, {
+      cwd,
+      stdio: "ignore",
+      windowsHide: true,
+      env: spawnEnv,
+    });
+
     // addReviewerPending already called above (before piArgs construction)
 
     updateAsyncWidget();
@@ -891,7 +928,7 @@ export function registerAsyncAgents(
       job.updatedAt = Date.now();
       // Record killed reviewer as having 0 findings — prevents permanent commit block
       if (job.agent.startsWith("code-reviewer-")) {
-        try { recordReviewerResult(jobCwd(job), job.agent, 0); } catch { /* best-effort */ }
+        try { recordReviewerResult(jobCwd(job), job.agent, 0); } catch (e: any) { asyncLog(`recordReviewerResult failed for ${job.agent}: ${e?.message}`); }
       }
       // Check if this completes a group — deliver remaining siblings' results
       if (job.groupId) {

package/extensions/orchestrator/async-capability.ts

@@ -13,7 +13,7 @@
 
 import { asStringArray, getSetting } from "./project-settings.js";
 
-export interface AsyncLlmSidecar {
+export interface InternalOpsProvider {
   provider: string;
   model: string;
 }
@@ -61,9 +61,9 @@ export function supportsAsyncLlm(
  * Sidecar model for must-async LLM work (dream, fireAndForget) when parent is acpx.
  * Both provider and model must be set. Returns null if incomplete or sidecar is acpx-*.
  */
-export function getAsyncLlmSidecar(cwd: string): AsyncLlmSidecar | null {
-  const provider = getSetting(cwd, "async_llm_provider");
-  const model = getSetting(cwd, "async_llm_model");
+export function getInternalOpsProvider(cwd: string): InternalOpsProvider | null {
+  const provider = getSetting(cwd, "internal_operations_provider");
+  const model = getSetting(cwd, "internal_operations_model");
   if (
     typeof provider === "string" &&
     provider.trim() &&
@@ -80,7 +80,7 @@ export function getAsyncLlmSidecar(cwd: string): AsyncLlmSidecar | null {
 export type AsyncDispatchDecision =
   | { action: "keep-async" }
   | { action: "coerce-sync"; note: string }
-  | { action: "sidecar-async"; sidecar: AsyncLlmSidecar; note: string }
+  | { action: "sidecar-async"; sidecar: InternalOpsProvider; note: string }
   | { action: "skip"; note: string };
 
 /**
@@ -106,20 +106,20 @@ export function decideAsyncLlmDispatch(opts: {
   if (asyncOk) {
     return { action: "keep-async" };
   }
-  const sidecar = getAsyncLlmSidecar(opts.cwd);
+  const sidecar = getInternalOpsProvider(opts.cwd);
   if (opts.mustAsync) {
     if (!sidecar) {
       return {
         action: "skip",
         note:
           "Skipped must-async LLM work: parent is acpx and " +
-          "async_llm_provider/async_llm_model are not set (or sidecar is acpx-*).",
+          "internal_operations_provider/internal_operations_model are not set (or sidecar is acpx-*).",
       };
     }
     return {
       action: "sidecar-async",
       sidecar,
-      note: `Using async_llm sidecar ${sidecar.provider}/${sidecar.model} (parent is acpx).`,
+      note: `Using internal ops provider ${sidecar.provider}/${sidecar.model} (parent is acpx).`,
     };
   }
   return {

package/extensions/orchestrator/cron.ts

@@ -544,7 +544,7 @@ export function registerCron(
         console.debug(`[cron] ${dispatch.note} (task #${task.id})`);
         try {
           state.lastCtx?.ui?.notify?.(
-            `Cron #${task.id} skipped: set async_llm_provider/async_llm_model for acpx`,
+            `Cron #${task.id} skipped: set internal_operations_provider/internal_operations_model for acpx`,
             "warning",
           );
         } catch { /* stale UI */ }

package/extensions/orchestrator/dreaming.ts

@@ -87,7 +87,7 @@ export function registerDreaming(
       dreamingLog("warn", dreamDispatch.note || "dream skipped (no async LLM path)");
       try {
         lastCtx?.ui?.notify?.(
-          "Dream skipped: set async_llm_provider and async_llm_model for acpx sessions",
+          "Dream skipped: set internal_operations_provider and internal_operations_model for acpx sessions",
           "warning",
         );
       } catch { /* stale UI */ }

package/extensions/orchestrator/enforcement.ts

@@ -27,7 +27,7 @@ import {
   runGit,
 } from "./git-helpers.js";
 import { spawnSync } from "node:child_process";
-import { markNeedsReview, isReviewClean, readReviewState, statePath, markTestsPassed, markTestsFailed } from "./pi-config-review-state.js";
+import { markNeedsReview, isCommitAllowed, readReviewState, statePath, markTestsPassed, markTestsFailed } from "./pi-config-review-state.js";
 import {
   checkPythonPipBlock,
   checkRemoteExecBlock,
@@ -82,8 +82,7 @@ async function handleCommitTrailer(command: string, event: any, ctx: any, gitCwd
   const trailerSetting = getSetting(gitCwd, "commit_trailer");
   if (typeof trailerSetting !== "string") return undefined;
 
-  const modelId = (ctx as any).model?.id;
-  if (!modelId) return undefined;
+  const modelId = (process.env.PI_MODEL || (ctx as any).model?.id || "unknown").replace(/[^a-zA-Z0-9._:@/ -]/g, "").trim() || "unknown";
 
   const piIdentity = `PI (${modelId}) <noreply@pi.dev>`;
   let trailerName: string;
@@ -362,7 +361,7 @@ export function registerEnforcement(pi: ExtensionAPI, inContainer?: boolean): vo
     cachedTrailerSelection = null;
     // Set comment signature env var for CLI tools to read
     if (getSetting(ctx.cwd, "comment_signature")) {
-      const modelId = (ctx as any).model?.id || "unknown";
+      const modelId = (process.env.PI_MODEL || (ctx as any).model?.id || "unknown").replace(/[^a-zA-Z0-9._:@/ -]/g, "").trim() || "unknown";
       process.env.PI_COMMENT_SIGNATURE = `Assisted-by: PI (${modelId})`;
     } else {
       delete process.env.PI_COMMENT_SIGNATURE;
@@ -518,7 +517,7 @@ export function registerEnforcement(pi: ExtensionAPI, inContainer?: boolean): vo
     // Use resolveEffectiveCwd to detect the worktree from cd commands (e.g., cd .worktrees/issue-622 && git commit)
     if (process.env.PI_AGENT_NAME === "git-expert" && hasGitSub(command, "commit")) {
       const commitCwd = resolveEffectiveCwd(command, ctx.cwd);
-      if (getSetting(ctx.cwd, "review_loop_enforcement") && !isReviewClean(commitCwd)) {
+      if (getSetting(ctx.cwd, "review_loop_enforcement") && !isCommitAllowed(commitCwd)) {
         const state = readReviewState(commitCwd);
         const testInfo = state.status === "clean" && !state.tests_passed ? " Tests have not passed yet — run tests before committing." : "";
         const reviewAdvice = state.status !== "clean" ? " Fix findings and re-run all reviewers until 0 comments." : "";