pi-orchestrator-config 4.2.0 → 4.2.1

package/extensions/orchestrator/index.ts

@@ -14,6 +14,7 @@
  */
 
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
 import { registerAskUser } from "./ask-user.js";
 import { registerAsyncAgents } from "./async-agents.js";
 import { registerBtw } from "./btw.js";
@@ -97,4 +98,58 @@ export default function (pi: ExtensionAPI) {
   registerPreferenceExtractor(pi);
   registerMemoryTools(pi);
   registerSessionSearch(pi);
+
+  // ── list_models tool — LLM-callable model discovery ──
+  pi.registerTool({
+    name: "list_models",
+    label: "List Models",
+    description: "List available models and providers. Use when the user asks to run an agent with a specific model, or when you need to discover available models for the subagent model parameter. Returns provider/model pairs that can be passed to subagent(model=\"provider/model-id\").",
+    parameters: Type.Object({
+      provider: Type.Optional(Type.String({ description: "Filter by provider name (e.g., 'litellm', 'cli-cursor', 'google')" })),
+    }),
+    async execute(_callId, params, _signal, _onUpdate, ctx) {
+      let models: any[];
+      try {
+        const registry = ctx.modelRegistry;
+        if (!registry) {
+          return {
+            content: [{ type: "text" as const, text: "Model registry not available." }],
+          };
+        }
+        models = registry.getAvailable?.() || registry.getAll?.() || [];
+      } catch (e: any) {
+        return {
+          content: [{ type: "text" as const, text: `Failed to list models: ${e?.message || e}` }],
+        };
+      }
+      // Filter out acpx-* providers — they cannot work in subagent children
+      // (PI_SUBAGENT_CHILD=1 skips acpx registration)
+      const filtered = (params.provider
+        ? models.filter((m: any) => m.provider === params.provider)
+        : models
+      ).filter((m: any) => !(m.provider || "").startsWith("acpx-"));
+      if (filtered.length === 0) {
+        return {
+          content: [{ type: "text" as const, text: params.provider ? `No models found for provider "${params.provider}".` : "No models available." }],
+        };
+      }
+      // Group by provider for readability
+      const byProvider = new Map<string, string[]>();
+      for (const m of filtered) {
+        const list = byProvider.get(m.provider) || [];
+        list.push(m.id);
+        byProvider.set(m.provider, list);
+      }
+      const lines: string[] = [];
+      for (const [prov, ids] of byProvider) {
+        lines.push(`## ${prov}`);
+        for (const id of ids) {
+          lines.push(`- ${prov}/${id}`);
+        }
+      }
+      return {
+        content: [{ type: "text" as const, text: lines.join("\n") }],
+      };
+    },
+  });
 }

package/extensions/orchestrator/parse-model-override.ts

@@ -0,0 +1,29 @@
+/** Parse 'provider/model-id' into separate provider and model. Plain 'model-id' returns undefined provider. */
+export function parseModelOverride(modelStr: string | undefined): { model?: string; provider?: string } | undefined {
+  if (!modelStr) return undefined;
+  const trimmed = modelStr.trim();
+  if (!trimmed) return undefined;
+  const slashIdx = trimmed.indexOf("/");
+  if (slashIdx > 0) {
+    const provider = trimmed.slice(0, slashIdx).trim();
+    const model = trimmed.slice(slashIdx + 1).trim();
+    if (!provider || !model) return undefined;
+    return { provider, model };
+  }
+  return { model: trimmed };
+}
+
+/** Merge task-level model override with top-level explicit fallback. Task fields win. */
+export function mergeModelOverride(
+  taskModel: string | undefined,
+  explicit: { model?: string; provider?: string } | undefined,
+): { model?: string; provider?: string } | undefined {
+  const taskParsed = parseModelOverride(taskModel);
+  if (taskParsed) {
+    return {
+      model: taskParsed.model || explicit?.model,
+      provider: taskParsed.provider || explicit?.provider,
+    };
+  }
+  return explicit;
+}

package/extensions/orchestrator/pi-config-review-state.ts

@@ -7,6 +7,7 @@
 
 import { existsSync, readFileSync, writeFileSync, unlinkSync, renameSync } from "node:fs";
 import { join } from "node:path";
+import { getSetting } from "./project-settings.js";
 import { resolveWorktreeRoot, getProjectDataDir } from "./utils.js";
 
 type StateTransitionCallback = (state: ReviewState) => void;
@@ -254,6 +255,18 @@ export function isReviewClean(cwd: string): boolean {
   return true;
 }
 
+/** Check if commit is allowed — clean review, no tracking, or max cycles exhausted. */
+export function isCommitAllowed(cwd: string): boolean {
+  if (isReviewClean(cwd)) return true;
+  const state = readReviewState(cwd);
+  // Allow commit when max review cycles exhausted — cap reached, no reviewers running
+  if ((state.status === "has_findings" || state.status === "clean" || state.status === "needs_review") && state.reviewers_pending.length === 0) {
+    const maxCycles = getSetting(cwd, "review_loop_max_cycles");
+    if (state.cycle >= maxCycles) return true;
+  }
+  return false;
+}
+
 /** Mark that tests have passed. Only meaningful when review status is being tracked. */
 export function markTestsPassed(cwd: string): void {
   withStateLock(cwd, (state) => {

package/extensions/orchestrator/project-settings.ts

@@ -6,7 +6,7 @@
  * 2. Global ~/.pi/pi-config-settings.json (fallback for all projects)
  * 3. Env var (PI_COMMIT_TRAILER, PI_USE_WORKTREES, PI_DREAM_INTERVAL_HOURS, PI_DCO,
  *    ACPX_AGENTS, CLI_AGENTS, PI_PIDASH_ENABLE, PI_PIDIFF_ENABLE, PI_PIDASH_PORT, PI_IMAGE_MODEL,
- *    PI_ASYNC_LLM_PROVIDER, PI_ASYNC_LLM_MODEL, PI_REVIEW_LOOP_MAX_CYCLES)
+ *    PI_INTERNAL_OPERATIONS_PROVIDER, PI_INTERNAL_OPERATIONS_MODEL, PI_REVIEW_LOOP_MAX_CYCLES)
  * 4. Default (dream_interval_hours defaults to 3; acpx_agents/cli_agents to []; pidash_enable/pidiff_enable to true; pidash_port to 19190;
  *    review_loop_max_cycles to 3)
  *
@@ -17,7 +17,8 @@
  */
 
 import { existsSync, statSync, readFileSync } from "node:fs";
-import { join } from "node:path";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
 import { homedir } from "node:os";
 import { resolveRepoRoot } from "./utils.js";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
@@ -40,9 +41,9 @@ interface ProjectSettings {
   pidash_port?: number;
   image_model?: string;
   /** Provider for detached LLM async children when parent is acpx (must-async / dream). */
-  async_llm_provider?: string;
+  internal_operations_provider?: string;
   /** Model id for detached LLM async children when parent is acpx. */
-  async_llm_model?: string;
+  internal_operations_model?: string;
   /** Max review-loop cycles injected into the rules prompt. Integer 1-10 only. */
   review_loop_max_cycles?: number;
   /** Default provider for all subagents. */
@@ -53,8 +54,52 @@ interface ProjectSettings {
   agent_overrides?: Record<string, { provider?: string | null; model?: string | null }>;
 }
 
+/** Key definition from settings-keys.json — single source of truth for env names + defaults. */
+interface SettingsKeyDef {
+  type: string;
+  env?: string;
+  default: unknown;
+  min?: number;
+  max?: number;
+  strict_digits?: boolean;
+  per_key_resolution?: boolean;
+}
+
 const SETTINGS_FILENAME = "pi-config-settings.json";
 
+const SETTINGS_KEYS: Record<string, SettingsKeyDef> = JSON.parse(
+  readFileSync(join(dirname(fileURLToPath(import.meta.url)), "..", "..", "settings-keys.json"), "utf-8"),
+);
+
+/** Dev-time check: every ProjectSettings field must have a JSON definition. */
+const PROJECT_SETTINGS_KEYS: (keyof ProjectSettings)[] = [
+  "commit_trailer",
+  "allow_push_to_protected_branches",
+  "use_worktrees",
+  "dream_interval_hours",
+  "dco",
+  "comment_signature",
+  "review_loop_enforcement",
+  "orchestrator_edit_write_block",
+  "acpx_agents",
+  "cli_agents",
+  "pidash_enable",
+  "pidiff_enable",
+  "pidash_port",
+  "image_model",
+  "internal_operations_provider",
+  "internal_operations_model",
+  "review_loop_max_cycles",
+  "agent_provider",
+  "agent_model",
+  "agent_overrides",
+];
+for (const key of PROJECT_SETTINGS_KEYS) {
+  if (!(key in SETTINGS_KEYS)) {
+    throw new Error(`[project-settings] settings-keys.json missing key: ${key}`);
+  }
+}
+
 function getSettingsPath(cwd: string): string {
   return join(resolveRepoRoot(cwd), ".pi", SETTINGS_FILENAME);
 }
@@ -83,11 +128,11 @@ function parseSettingsFile(filePath: string): ProjectSettings {
     if (typeof raw.image_model === "string" && raw.image_model.trim()) {
       result.image_model = raw.image_model.trim();
     }
-    if (typeof raw.async_llm_provider === "string" && raw.async_llm_provider.trim()) {
-      result.async_llm_provider = raw.async_llm_provider.trim();
+    if (typeof raw.internal_operations_provider === "string" && raw.internal_operations_provider.trim()) {
+      result.internal_operations_provider = raw.internal_operations_provider.trim();
     }
-    if (typeof raw.async_llm_model === "string" && raw.async_llm_model.trim()) {
-      result.async_llm_model = raw.async_llm_model.trim();
+    if (typeof raw.internal_operations_model === "string" && raw.internal_operations_model.trim()) {
+      result.internal_operations_model = raw.internal_operations_model.trim();
     }
     const parsedMaxCycles = parseReviewLoopMaxCycles(raw.review_loop_max_cycles);
     if (parsedMaxCycles !== undefined) {
@@ -302,67 +347,34 @@ export function getSetting(cwd: string, key: "pidash_enable"): boolean;
 export function getSetting(cwd: string, key: "pidiff_enable"): boolean;
 export function getSetting(cwd: string, key: "pidash_port"): number;
 export function getSetting(cwd: string, key: "image_model"): string;
-export function getSetting(cwd: string, key: "async_llm_provider"): string;
-export function getSetting(cwd: string, key: "async_llm_model"): string;
+export function getSetting(cwd: string, key: "internal_operations_provider"): string;
+export function getSetting(cwd: string, key: "internal_operations_model"): string;
 export function getSetting(cwd: string, key: "review_loop_max_cycles"): number;
 export function getSetting(cwd: string, key: "agent_provider"): string;
 export function getSetting(cwd: string, key: "agent_model"): string;
 export function getSetting(cwd: string, key: "agent_overrides"): Record<string, { provider?: string | null; model?: string | null }>;
 export function getSetting(cwd: string, key: string): boolean | string | number | string[] | Record<string, { provider?: string | null; model?: string | null }> {
   const settings = getSettings(cwd);
+  const def = SETTINGS_KEYS[key];
+  if (!def) return false;
 
+  // Special cases — unique parsing beyond simple settings → env → default
   switch (key) {
     case "commit_trailer": {
       if (settings.commit_trailer !== undefined) return settings.commit_trailer;
-      const envStr = process.env.PI_COMMIT_TRAILER;
+      const envStr = def.env ? process.env[def.env] : undefined;
       if (envStr !== undefined && envStr !== "") {
         if (["true", "1", "yes", "on"].includes(envStr.toLowerCase())) return true;
         if (["false", "0", "no", "off"].includes(envStr.toLowerCase())) return false;
         return envStr; // treat as custom trailer string
       }
-      return false; // default: disabled
-    }
-    case "allow_push_to_protected_branches": {
-      if (settings.allow_push_to_protected_branches !== undefined) return settings.allow_push_to_protected_branches;
-      const env = parseBoolEnv("PI_ALLOW_PUSH_TO_PROTECTED_BRANCHES");
-      if (env !== undefined) return env;
-      return false; // default: block pushes to protected branches
-    }
-    case "use_worktrees": {
-      if (settings.use_worktrees !== undefined) return settings.use_worktrees;
-      const env = parseBoolEnv("PI_USE_WORKTREES");
-      if (env !== undefined) return env;
-      return false; // default: disabled
-    }
-    case "dream_interval_hours": {
-      if (settings.dream_interval_hours !== undefined) return settings.dream_interval_hours;
-      const env = parseNumEnv("PI_DREAM_INTERVAL_HOURS");
-      if (env !== undefined) return env;
-      return 3; // default: 3 hours
-    }
-    case "dco": {
-      if (settings.dco !== undefined) return settings.dco;
-      const env = parseBoolEnv("PI_DCO");
-      if (env !== undefined) return env;
-      return false; // default: disabled
+      return def.default as boolean;
     }
-    case "comment_signature": {
-      if (settings.comment_signature !== undefined) return settings.comment_signature;
-      return false; // default: disabled
-    }
-    case "review_loop_enforcement": {
-      if (settings.review_loop_enforcement !== undefined) return settings.review_loop_enforcement;
-      const env = parseBoolEnv("PI_REVIEW_LOOP_ENFORCEMENT");
-      if (env !== undefined) return env;
-      return false; // default: disabled (opt-in)
-    }
-    case "orchestrator_edit_write_block": {
-      if (settings.orchestrator_edit_write_block !== undefined) return settings.orchestrator_edit_write_block;
-      return false; // default: disabled
-    }
-    case "acpx_agents": {
-      if (projectSettingsFileHasKey(cwd, "acpx_agents")) {
-        const projectValue = loadProjectSettings(cwd).acpx_agents;
+    case "acpx_agents":
+    case "cli_agents": {
+      const agentKey = key as "acpx_agents" | "cli_agents";
+      if (projectSettingsFileHasKey(cwd, agentKey)) {
+        const projectValue = loadProjectSettings(cwd)[agentKey];
         // Only override when the raw value parsed as a valid type (string or array).
         // Invalid types (number, object, etc.) are skipped by parseSettingsFile,
         // leaving projectValue undefined — fall through to global/env.
@@ -370,44 +382,27 @@ export function getSetting(cwd: string, key: string): boolean | string | number
           return parseAgentNameList(projectValue);
         }
       }
-      const globalAgents = loadGlobalSettings().acpx_agents;
+      const globalAgents = loadGlobalSettings()[agentKey];
       if (globalAgents !== undefined) {
         return parseAgentNameList(globalAgents);
       }
-      const env = process.env.ACPX_AGENTS;
-      if (env !== undefined && env !== "") {
-        return parseAgentNameList(env);
-      }
-      return [];
-    }
-    case "cli_agents": {
-      if (projectSettingsFileHasKey(cwd, "cli_agents")) {
-        const projectValue = loadProjectSettings(cwd).cli_agents;
-        if (projectValue !== undefined) {
-          return parseAgentNameList(projectValue);
+      if (def.env) {
+        const env = process.env[def.env];
+        if (env !== undefined && env !== "") {
+          return parseAgentNameList(env);
         }
       }
-      const globalAgents = loadGlobalSettings().cli_agents;
-      if (globalAgents !== undefined) {
-        return parseAgentNameList(globalAgents);
-      }
-      const env = process.env.CLI_AGENTS;
-      if (env !== undefined && env !== "") {
-        return parseAgentNameList(env);
-      }
-      return [];
-    }
-    case "pidash_enable": {
-      if (settings.pidash_enable !== undefined) return settings.pidash_enable;
-      const disabled = parseDisabledEnv("PI_PIDASH_ENABLE");
-      if (disabled !== undefined) return !disabled;
-      return true;
+      return parseAgentNameList(def.default as string | string[] | undefined);
     }
+    case "pidash_enable":
     case "pidiff_enable": {
-      if (settings.pidiff_enable !== undefined) return settings.pidiff_enable;
-      const disabled = parseDisabledEnv("PI_PIDIFF_ENABLE");
-      if (disabled !== undefined) return !disabled;
-      return true;
+      const enableKey = key as "pidash_enable" | "pidiff_enable";
+      if (settings[enableKey] !== undefined) return settings[enableKey]!;
+      if (def.env) {
+        const disabled = parseDisabledEnv(def.env);
+        if (disabled !== undefined) return !disabled;
+      }
+      return def.default as boolean;
     }
     case "pidash_port": {
       if (settings.pidash_port !== undefined) {
@@ -417,39 +412,51 @@ export function getSetting(cwd: string, key: string): boolean | string | number
         }
         // Invalid value in merged settings — fall through to env/default
       }
-      const envPort = parsePortEnv("PI_PIDASH_PORT");
-      if (envPort !== undefined) return envPort;
-      return 19190;
-    }
-    case "image_model": {
-      if (settings.image_model !== undefined) return settings.image_model;
-      const env = process.env.PI_IMAGE_MODEL;
-      return env !== undefined && env !== "" ? env : "";
-    }
-    case "async_llm_provider": {
-      if (settings.async_llm_provider !== undefined) return settings.async_llm_provider;
-      const env = process.env.PI_ASYNC_LLM_PROVIDER;
-      return env !== undefined && env !== "" ? env.trim() : "";
-    }
-    case "async_llm_model": {
-      if (settings.async_llm_model !== undefined) return settings.async_llm_model;
-      const env = process.env.PI_ASYNC_LLM_MODEL;
-      return env !== undefined && env !== "" ? env.trim() : "";
+      if (def.env) {
+        const envPort = parsePortEnv(def.env);
+        if (envPort !== undefined) return envPort;
+      }
+      return def.default as number;
     }
     case "review_loop_max_cycles": {
       if (settings.review_loop_max_cycles !== undefined) return settings.review_loop_max_cycles;
-      const env = parseReviewLoopMaxCyclesEnv("PI_REVIEW_LOOP_MAX_CYCLES");
-      if (env !== undefined) return env;
-      return 3; // default: 3 cycles
+      if (def.env) {
+        const env = parseReviewLoopMaxCyclesEnv(def.env);
+        if (env !== undefined) return env;
+      }
+      return def.default as number;
     }
-    case "agent_provider": {
-      return settings.agent_provider || "";
+    case "agent_overrides": {
+      return settings.agent_overrides || (def.default as Record<string, { provider?: string | null; model?: string | null }>);
     }
-    case "agent_model": {
-      return settings.agent_model || "";
+  }
+
+  // Generic handler — simple bool / number / string keys driven by settings-keys.json
+  const merged = settings[key as keyof ProjectSettings];
+  switch (def.type) {
+    case "bool": {
+      if (merged !== undefined) return merged as boolean;
+      if (def.env) {
+        const env = parseBoolEnv(def.env);
+        if (env !== undefined) return env;
+      }
+      return def.default as boolean;
     }
-    case "agent_overrides": {
-      return settings.agent_overrides || {};
+    case "number": {
+      if (merged !== undefined) return merged as number;
+      if (def.env) {
+        const env = parseNumEnv(def.env);
+        if (env !== undefined) return env;
+      }
+      return def.default as number;
+    }
+    case "string": {
+      if (merged !== undefined) return (merged as string) || (def.default as string);
+      if (def.env) {
+        const env = process.env[def.env];
+        if (env !== undefined && env !== "") return env.trim();
+      }
+      return def.default as string;
     }
     default:
       return false;

package/extensions/orchestrator/resolve-agent-model.ts

@@ -1,6 +1,7 @@
 /**
  * Resolve effective model/provider for an agent.
- * Priority: agent_overrides[name] > agent frontmatter > agent_provider/agent_model setting > parent
+ * Each field resolved independently through priority chain:
+ * explicit > agent_overrides[name] > agent frontmatter > agent_provider/agent_model setting > parent
  * null in overrides = skip settings, use parent directly.
  */
 
@@ -11,22 +12,32 @@ export function resolveAgentModelProvider(
   agent: { model?: string; provider?: string },
   parentModelId: string | undefined,
   parentProvider: string | undefined,
-  cwd: string
+  cwd: string,
+  explicit?: { model?: string; provider?: string },
 ): { model: string | undefined; provider: string | undefined } {
   const overrides = getSetting(cwd, "agent_overrides");
   const override = overrides[agentName];
 
-  if (override) {
-    // null = explicitly use parent (skip agent frontmatter AND global settings)
-    // Model and provider resolve independently on purpose: a partial override
-    // (e.g. only model) still lets provider fall through frontmatter → settings → parent.
-    const model = override.model === null ? parentModelId : (override.model || agent.model || getSetting(cwd, "agent_model") || parentModelId);
-    const provider = override.provider === null ? parentProvider : (override.provider || agent.provider || getSetting(cwd, "agent_provider") || parentProvider);
-    return { model: model || undefined, provider: provider || undefined };
+  // Resolve each field independently through the priority chain:
+  // explicit > agent_overrides[name] > agent frontmatter > agent_provider/agent_model setting > parent
+  // null in overrides = skip settings, use parent directly.
+  function resolveModel(): string | undefined {
+    if (explicit?.model) return explicit.model;
+    if (override) {
+      if (override.model === null) return parentModelId;
+      if (override.model) return override.model;
+    }
+    return agent.model || getSetting(cwd, "agent_model") || parentModelId || undefined;
   }
 
-  // No override: agent frontmatter > global setting > parent
-  const model = agent.model || getSetting(cwd, "agent_model") || parentModelId;
-  const provider = agent.provider || getSetting(cwd, "agent_provider") || parentProvider;
-  return { model: model || undefined, provider: provider || undefined };
+  function resolveProvider(): string | undefined {
+    if (explicit?.provider) return explicit.provider;
+    if (override) {
+      if (override.provider === null) return parentProvider;
+      if (override.provider) return override.provider;
+    }
+    return agent.provider || getSetting(cwd, "agent_provider") || parentProvider || undefined;
+  }
+
+  return { model: resolveModel(), provider: resolveProvider() };
 }

package/extensions/orchestrator/review-ui.ts

@@ -8,10 +8,11 @@
 
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { Box, Text } from "@earendil-works/pi-tui";
-import { onStateTransition, readReviewState, type ReviewState } from "./pi-config-review-state.js";
+import { onStateTransition, readReviewState, markNeedsReview, resetReviewState, type ReviewState } from "./pi-config-review-state.js";
 import { ICON_REVIEW_CLEAN, ICON_REVIEW_NEEDED, ICON_REVIEW_PROGRESS, ICON_REVIEW_FINDINGS } from "./icons.js";
 import { getSetting } from "./project-settings.js";
 import { setSlot, clearSlot } from "./status-bar.js";
+import { runGit } from "./git-helpers.js";
 
 interface ReviewStatusData {
   status: ReviewState["status"];
@@ -23,11 +24,13 @@ interface ReviewStatusData {
   timestamp: number;
 }
 
-// Deduplication — skip append if status+cycle hasn't changed
+// Deduplication — skip append if status hasn't changed
 let lastAppendedKey = "";
 
 /** Dedup key shared by status bar and transcript cards. */
 function stateKey(s: { status: string; cycle: number; findings_count: number; tests_passed: boolean; reviewers_pending: { length: number } }): string {
+  // For needs_review, only status+cycle matter — tests_passed flips shouldn't re-trigger the card
+  if (s.status === "needs_review") return `${s.status}:${s.cycle}`;
   return `${s.status}:${s.cycle}:${s.findings_count}:${s.tests_passed}:${s.reviewers_pending.length}`;
 }
 
@@ -95,6 +98,7 @@ export function registerReviewUI(pi: ExtensionAPI): void {
 
   let lastCtx: ExtensionContext | null = null;
   let lastBarKey = "";
+  let lastGitSnapshot = "";
 
   function updateStatusBar(state: ReviewState): void {
     if (!lastCtx?.hasUI) return;
@@ -142,6 +146,15 @@ export function registerReviewUI(pi: ExtensionAPI): void {
   // Capture ctx and show current state on load
   pi.on("session_start", (_event, ctx) => {
     lastCtx = ctx;
+    // Initialize git snapshot for dirty detection
+    lastGitSnapshot = runGit(["status", "--porcelain"], ctx.cwd).stdout;
+    // If tree is already dirty on session start, ensure review state reflects it
+    if (lastGitSnapshot && getSetting(ctx.cwd, "review_loop_enforcement")) {
+      const state = readReviewState(ctx.cwd);
+      if (state.status === "none" || state.status === "clean") {
+        try { markNeedsReview(ctx.cwd); } catch (e: any) { console.debug("[review-ui] markNeedsReview failed:", e?.message); }
+      }
+    }
     if (getSetting(ctx.cwd, "review_loop_enforcement")) {
       updateStatusBar(readReviewState(ctx.cwd));
     } else if (ctx.hasUI) {
@@ -169,22 +182,58 @@ export function registerReviewUI(pi: ExtensionAPI): void {
   }, 5000);
   if (reviewPoller.unref) reviewPoller.unref();
 
+  // Poll git status to detect file changes from CLI/ACPX agents
+  const gitDirtyPoller = setInterval(() => {
+    if (!lastCtx) return;
+    try { void lastCtx.ui.theme; } catch { lastCtx = null; return; }
+    try {
+      if (!getSetting(lastCtx.cwd, "review_loop_enforcement")) return;
+      const result = runGit(["status", "--porcelain"], lastCtx.cwd);
+      const snapshot = result.stdout;
+      if (snapshot === lastGitSnapshot) return;
+      lastGitSnapshot = snapshot;
+      if (snapshot) {
+        // Dirty tree — markNeedsReview handles all states:
+        // none/clean/has_findings → sets needs_review
+        // in_progress → sets edited_during_cycle + clears tests_passed
+        // needs_review → no-op (deduped internally)
+        try { markNeedsReview(lastCtx.cwd); } catch (e: any) { console.debug("[review-ui] markNeedsReview failed:", e?.message); }
+      } else if (result.code === 0) {
+        // Tree clean AND git succeeded — reset when status is clean (committed-away),
+        // needs_review (edits reverted, nothing left to review), or has_findings
+        // (committed+pushed — fresh start). Skip in_progress (reviewers still running).
+        const state = readReviewState(lastCtx.cwd);
+        if (state.status === "clean" || state.status === "needs_review" || state.status === "has_findings") {
+          try { resetReviewState(lastCtx.cwd); } catch (e: any) { console.debug("[review-ui] resetReviewState failed:", e?.message); }
+        }
+      }
+    } catch (e: any) { console.debug("[review-ui] gitDirtyPoller error:", e?.message); }
+  }, 3000);
+  if (gitDirtyPoller.unref) gitDirtyPoller.unref();
+
   pi.on("session_shutdown", () => {
     clearInterval(reviewPoller);
+    clearInterval(gitDirtyPoller);
   });
 
   // ── Hook into review state transitions ───────────────────────────────
 
   onStateTransition((state: ReviewState) => {
-    // Always update status bar (even for "none" — clears it)
-    // Only show if enforcement is enabled
+    // Always update status bar
     if (lastCtx && getSetting(lastCtx.cwd, "review_loop_enforcement")) {
       updateStatusBar(state);
     }
 
-    if (state.status === "none") return;
+    if (state.status === "none") {
+      lastAppendedKey = "";
+      return;
+    }
+
+    // Card only shows on status change — not on tests_passed/findings/pending changes
+    if (state.status === lastAppendedKey) return;
+    lastAppendedKey = state.status;
 
-    const data: ReviewStatusData = {
+    pi.appendEntry<ReviewStatusData>("review-status", {
       status: state.status,
       cycle: state.cycle,
       findings_count: state.findings_count,
@@ -192,13 +241,6 @@ export function registerReviewUI(pi: ExtensionAPI): void {
       reviewers_pending: [...state.reviewers_pending],
       reviewers_total: state.reviewers_total,
       timestamp: Date.now(),
-    };
-
-    // Deduplicate transcript cards — skip if nothing meaningful changed
-    const key = stateKey(data);
-    if (key === lastAppendedKey) return;
-    lastAppendedKey = key;
-
-    pi.appendEntry<ReviewStatusData>("review-status", data);
+    });
   });
 }

package/extensions/orchestrator/rule-placeholders.ts

@@ -1,12 +1,38 @@
 /**
- * Pure placeholder substitution for rules/*.md prompt text.
+ * Pure placeholder substitution for rules/*.md and agent system-prompt text.
  *
  * Kept in its own module (no heavy imports) so it can be unit tested without
  * pulling in the full orchestrator dependency chain (e.g. rules.ts → async-agents.ts
  * → @earendil-works/pi-tui, which is a runtime-only dependency not present in
- * the test install).
+ * the test install). Callers pass a resolve function for settings lookups.
  */
 
 export function substituteRulePlaceholders(text: string, values: { reviewLoopMaxCycles: number }): string {
   return text.replaceAll("{{REVIEW_LOOP_MAX_CYCLES}}", String(values.reviewLoopMaxCycles));
 }
+
+const SETTINGS_PATTERN = /\{\{SETTINGS(?::([^}]+))?\}\}/g;
+
+/**
+ * Replace `{{SETTINGS:key1,key2,...}}` with JSON of resolved setting values.
+ * `{{SETTINGS}}` (no colon) resolves every key in `allKeys`.
+ */
+export function substituteSettingsPlaceholders(
+  text: string,
+  resolve: (key: string) => unknown,
+  allKeys: string[],
+): string {
+  return text.replace(new RegExp(SETTINGS_PATTERN.source, "g"), (_match, keysGroup: string | undefined) => {
+    const keys = keysGroup !== undefined
+      ? keysGroup.split(",").map((k) => k.trim()).filter((k) => k.length > 0)
+      : allKeys;
+    const result: Record<string, unknown> = {};
+    for (const key of keys) {
+      if (!allKeys.includes(key)) {
+        continue;
+      }
+      result[key] = resolve(key);
+    }
+    return JSON.stringify(result);
+  });
+}