@ilya-lesikov/pi-pi 0.5.0 → 0.7.0

package/extensions/orchestrator/event-handlers.ts

@@ -1,53 +1,91 @@
-import { existsSync, readdirSync, readFileSync } from "fs";
-import { resolve, basename, join } from "path";
+import { existsSync, mkdtempSync, readdirSync, readFileSync, rmSync, statSync } from "fs";
+import { tmpdir } from "os";
+import { resolve, basename, join, relative, dirname, isAbsolute, sep } from "path";
 import { validateUserRequest, validateResearch, validateArtifact } from "./validate-artifacts.js";
 import { Type } from "@sinclair/typebox";
-import { loadConfig } from "./config.js";
-import { runAfterEdit, autoCommit } from "./commands.js";
-import { taskName, getActiveTask, saveTask, appendTaskLog } from "./state.js";
+import { loadConfig, resolvePreset } from "./config.js";
+import { runAfterEdit, autoCommit, loadRepoAfterEditCommands } from "./commands.js";
+import { taskName, getActiveTask, getEffectiveMode, getEffectivePhaseMode, saveTask, type Phase, type TaskMode } from "./state.js";
+import { getLogger, initSessionLogger, addTaskDestination, setLogLevel, flushLogs } from "./log.js";
+import { initTracer, finalizeTracer, getTracer } from "./tracer.js";
+import { handleSpawnResult } from "./spawn-cleanup.js";
 import {
-  loadContextFiles,
+  getContextDirs,
+  loadAllContextFiles,
   getPhaseArtifacts,
   getLatestSynthesizedPlan,
   loadBrainstormReviewOutputs,
   loadCodeReviewOutputs,
   loadPlanReviewOutputs,
 } from "./context.js";
-import { WORKING_PRINCIPLES, COMMUNICATION } from "./agents/tool-routing.js";
+import { PRINCIPLES_BLOCK, TOOLS_BLOCK } from "./agents/tool-routing.js";
+import { constraintsBlock, phaseConstraint } from "./agents/constraints.js";
 import { registerCbmTools } from "./cbm.js";
 import { registerExaTools } from "./exa.js";
 import { registerAstSearchTool } from "./ast-search.js";
 import { SUBAGENT_SESSION_KEY } from "./index.js";
+import { registerCommandHandlers } from "./command-handlers.js";
 import { setExtensionOnlyMode, unregisterAgentDefinitions } from "./agents/registry.js";
+import { resolveModel, getModelInfo, updateRegistryFromAvailableModels } from "./model-registry.js";
 import { spawnPlanners, spawnPlanReviewers } from "./phases/planning.js";
 import { spawnCodeReviewers } from "./phases/review.js";
 import { spawnBrainstormReviewers } from "./phases/brainstorm.js";
+import { reviewPassUnanimousApprove } from "./phases/verdict.js";
+import { validateExitCriteria } from "./phases/machine.js";
 import { openPlannotator, waitForPlannotatorResult, cancelPendingPlannotatorWait } from "./plannotator.js";
-import { Orchestrator, deepReviewConfig, type ActiveTask } from "./orchestrator.js";
+import { Orchestrator, type ActiveTask } from "./orchestrator.js";
 import { createCustomFooter, setFooterContext, setFooterTracker } from "./custom-footer.js";
 import { createUsageTracker, dumpUsageSummary, loadUsageSummary, type UsageTracker } from "./usage-tracker.js";
-import { askUser } from "../../3p/pi-ask-user/index.js";
+import { askUser, isCancel } from "../../3p/pi-ask-user/index.js";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { findRootRepo, normalizeRepoPath, resolveRepoForFile, type RepoInfo } from "./repo-utils.js";
 
 const USAGE_TRACKER_KEY = Symbol.for("pi-pi:usage-tracker");
 
-export async function detectDefaultBranch(pi: ExtensionAPI, cwd: string, config?: { diffBaseBranch?: string }): Promise<string> {
-  if (config?.diffBaseBranch) return config.diffBaseBranch;
+function isEnabled(value: { enabled?: boolean } | undefined): boolean {
+  return value?.enabled !== false;
+}
+
+function isPathInside(basePath: string, targetPath: string): boolean {
+  const rel = relative(basePath, targetPath);
+  return rel === "" || (!rel.startsWith(`..${sep}`) && rel !== ".." && !isAbsolute(rel));
+}
+
+export async function detectDefaultBranch(orchestrator: Orchestrator, repos: RepoInfo[], repoPath: string): Promise<string> {
+  const normalizedPath = normalizeRepoPath(repoPath);
+  const repo = repos.find((r) => r.path === normalizedPath);
+  if (repo?.baseBranch) return repo.baseBranch;
+
   try {
-    const result = await pi.exec("git", ["symbolic-ref", "refs/remotes/origin/HEAD"], { cwd, timeout: 5000 });
-    if (result.code === 0 && result.stdout.trim()) {
-      return "origin/" + result.stdout.trim().replace("refs/remotes/origin/", "");
+    const headRef = await orchestrator.pi.exec("git", ["symbolic-ref", "refs/remotes/origin/HEAD"], {
+      cwd: normalizedPath,
+      timeout: 5000,
+    });
+    if (headRef.code === 0) {
+      const value = headRef.stdout.trim();
+      if (value.startsWith("refs/remotes/")) {
+        return value.slice("refs/remotes/".length);
+      }
     }
   } catch {}
+
   try {
-    const result = await pi.exec("git", ["show-ref", "--verify", "refs/remotes/origin/main"], { cwd, timeout: 5000 });
-    if (result.code === 0) return "origin/main";
+    const mainRef = await orchestrator.pi.exec("git", ["show-ref", "--verify", "--quiet", "refs/remotes/origin/main"], {
+      cwd: normalizedPath,
+      timeout: 5000,
+    });
+    if (mainRef.code === 0) return "origin/main";
   } catch {}
+
   try {
-    const result = await pi.exec("git", ["show-ref", "--verify", "refs/remotes/origin/master"], { cwd, timeout: 5000 });
-    if (result.code === 0) return "origin/master";
+    const masterRef = await orchestrator.pi.exec("git", ["show-ref", "--verify", "--quiet", "refs/remotes/origin/master"], {
+      cwd: normalizedPath,
+      timeout: 5000,
+    });
+    if (masterRef.code === 0) return "origin/master";
   } catch {}
-  return "main";
+
+  return "origin/main";
 }
 
 export async function selectOption(ctx: any, question: string, options: string[]): Promise<string | undefined> {
@@ -58,11 +96,77 @@ export async function selectOption(ctx: any, question: string, options: string[]
     allowComment: false,
     allowMultiple: false,
   });
-  if (!result || result.kind !== "selection") return undefined;
+  if (!result || isCancel(result) || result.kind !== "selection") return undefined;
   return result.selections[0];
 }
 
-function tryCompleteReviewCycle(orchestrator: Orchestrator): void {
+function resolveReviewers(
+  orchestrator: Orchestrator,
+  phase: string,
+  presetName?: string,
+): Record<string, any> {
+  const group = phase === "brainstorm"
+    ? "brainstormReviewers"
+    : phase === "plan"
+    ? "planReviewers"
+    : "codeReviewers";
+  return resolvePreset(orchestrator.config, group, presetName);
+}
+
+function getDefaultReviewPresetName(orchestrator: Orchestrator, phase: string): string {
+  if (phase === "brainstorm") return orchestrator.config.agents.subagents.presetGroups.brainstormReviewers.default;
+  if (phase === "plan") return orchestrator.config.agents.subagents.presetGroups.planReviewers.default;
+  return orchestrator.config.agents.subagents.presetGroups.codeReviewers.default;
+}
+
+function normalizeStoredPlannerPresetName(orchestrator: Orchestrator): string {
+  const requestedName = orchestrator.active?.state.activePlannerPreset ?? orchestrator.config.agents.subagents.presetGroups.planners.default;
+  const plannerPresets = orchestrator.config.agents.subagents.presetGroups.planners.presets ?? {};
+  const exists = Object.prototype.hasOwnProperty.call(plannerPresets, requestedName);
+  const resolvedName = exists ? requestedName : (Object.keys(plannerPresets)[0] ?? requestedName);
+
+  if (orchestrator.active && orchestrator.active.state.activePlannerPreset !== resolvedName) {
+    orchestrator.active.state.activePlannerPreset = resolvedName;
+    saveTask(orchestrator.active.dir, orchestrator.active.state);
+  }
+
+  if (!exists && resolvedName !== requestedName) {
+    orchestrator.lastCtx?.ui?.notify(
+      `Planner preset "${requestedName}" not found. Falling back to "${resolvedName}".`,
+      "warning",
+    );
+  }
+
+  return resolvedName;
+}
+
+function normalizeStoredReviewPresetName(orchestrator: Orchestrator, phase: string): string {
+  const group = phase === "brainstorm"
+    ? "brainstormReviewers"
+    : phase === "plan"
+    ? "planReviewers"
+    : "codeReviewers";
+  const requestedName = orchestrator.active?.state.activeReviewPreset ?? getDefaultReviewPresetName(orchestrator, phase);
+  const reviewPresets = orchestrator.config.agents.subagents.presetGroups[group].presets ?? {};
+  const exists = Object.prototype.hasOwnProperty.call(reviewPresets, requestedName);
+  const resolvedName = exists ? requestedName : (Object.keys(reviewPresets)[0] ?? requestedName);
+
+  if (orchestrator.active && orchestrator.active.state.activeReviewPreset !== resolvedName) {
+    orchestrator.active.state.activeReviewPreset = resolvedName;
+    saveTask(orchestrator.active.dir, orchestrator.active.state);
+  }
+
+  if (!exists && resolvedName !== requestedName) {
+    orchestrator.lastCtx?.ui?.notify(
+      `Review preset "${requestedName}" not found. Falling back to "${resolvedName}".`,
+      "warning",
+    );
+  }
+
+  return resolvedName;
+}
+
+function tryCompleteReviewCycle(orchestrator: Orchestrator, spawnedReviewers?: number): void {
   if (
     !orchestrator.active?.state.reviewCycle ||
     orchestrator.active.state.reviewCycle.step !== "await_reviewers" ||
@@ -70,41 +174,67 @@ function tryCompleteReviewCycle(orchestrator: Orchestrator): void {
     orchestrator.pendingSubagentSpawns > 0
   ) return;
 
-  if (orchestrator.reviewTransitionToken === orchestrator.activeTaskToken) return;
-
+  // Idempotent by state: the first call mutates reviewCycle.step away from
+  // "await_reviewers" (or nulls reviewCycle), so the guard above no-ops any
+  // subsequent caller. No separate dedup token needed.
   const cycle = orchestrator.active.state.reviewCycle;
   const phase = orchestrator.active.state.phase;
   const outputs = loadPhaseReviewOutputs(orchestrator.active.dir, phase, cycle.pass);
   const pi = orchestrator.pi;
 
-  orchestrator.reviewTransitionToken = orchestrator.activeTaskToken;
+  if (spawnedReviewers === 0 && outputs.length === 0) {
+    orchestrator.active.state.reviewCycle = null;
+    orchestrator.active.state.step = "llm_work";
+    saveTask(orchestrator.active.dir, orchestrator.active.state);
+    orchestrator.safeSendUserMessage("[PI-PI] No reviewer outputs were produced — nothing to review. Continue working.");
+    return;
+  }
+
   cycle.step = "apply_feedback";
   orchestrator.active.state.step = "apply_feedback";
   saveTask(orchestrator.active.dir, orchestrator.active.state);
 
   const rendered = outputs.length
     ? outputs.map((o) => `=== ${o.name} ===\n${o.content}`).join("\n\n")
-    : "No reviewer outputs found. Review the implementation yourself and decide whether to approve or request changes.";
+    : "All reviewers failed to produce output. Review the work yourself and decide whether to approve or request changes.";
 
-  pi.sendMessage(
+  orchestrator.transitionController.sendCustom(
     {
       customType: "pp-review-ready",
       content: `[PI-PI] Reviewer outputs are ready.\n\n${rendered}`,
       display: false,
     },
-    { deliverAs: "followUp" },
+    "instruction",
   );
-  orchestrator.safeSendUserMessage("[PI-PI] Review cycle is ready for apply_feedback. Read reviewer outputs and proceed.");
+  orchestrator.safeSendUserMessage(reviewReadyMessage(phase, getEffectivePhaseMode(orchestrator.active.state)));
+}
+
+function reviewReadyMessage(phase: string, mode: TaskMode): string {
+  if (phase === "brainstorm") {
+    return "[PI-PI] Review cycle is ready for apply_feedback. The reviewers assessed your artifacts (USER_REQUEST.md, RESEARCH.md, and artifacts/), not a code diff. Read their outputs and update those artifacts as needed.";
+  }
+  // Only autonomous plan/implement auto-advance: those must re-call
+  // pp_phase_complete to finalize the pass and transition. Guided phases
+  // (including debug and the interactive review phase) stay user-driven, so
+  // they get neutral wording with no re-call/auto-advance directive.
+  if (mode === "autonomous") {
+    return "[PI-PI] Review cycle is ready for apply_feedback. Read the reviewer outputs, apply any required changes, then call pp_phase_complete again to finalize this review pass and advance the phase. Do NOT stop or wait for the user — the phase is NOT complete until you re-call pp_phase_complete.";
+  }
+  return "[PI-PI] Review cycle is ready for apply_feedback. Read the reviewer outputs and apply any required changes.";
 }
 
-export async function enterReviewCycle(orchestrator: Orchestrator, ctx: any, kind: "auto" | "auto-deep" | "plannotator") {
+export async function enterReviewCycle(
+  orchestrator: Orchestrator,
+  ctx: any,
+  kind: "plannotator" | string,
+): Promise<string> {
   if (!orchestrator.active) return "No active task.";
   const pi = orchestrator.pi;
   const pass = orchestrator.active.state.reviewPass + 1;
-  orchestrator.active.state.reviewCycle = { kind, step: "spawn_reviewers", pass };
-  saveTask(orchestrator.active.dir, orchestrator.active.state);
 
   if (kind === "plannotator") {
+    orchestrator.active.state.reviewCycle = { kind: "plannotator", step: "spawn_reviewers", pass };
+    saveTask(orchestrator.active.dir, orchestrator.active.state);
     const phase = orchestrator.active.state.phase;
     if (phase === "brainstorm") {
       orchestrator.active.state.reviewCycle = null;
@@ -160,13 +290,14 @@ export async function enterReviewCycle(orchestrator: Orchestrator, ctx: any, kin
   }
 
   const phase = orchestrator.active.state.phase;
-  const config = kind === "auto-deep" ? deepReviewConfig(orchestrator.config) : orchestrator.config;
-  const reviewers = phase === "brainstorm"
-    ? config.brainstormReviewers
-    : phase === "plan"
-    ? config.planReviewers
-    : config.codeReviewers;
-  const enabledCount = Object.values(reviewers).filter((v) => v.enabled).length;
+  const presetName = kind || getDefaultReviewPresetName(orchestrator, phase);
+  orchestrator.active.state.reviewCycle = { kind: "auto", step: "spawn_reviewers", pass };
+  orchestrator.active.state.reviewerFailureAutoRetried = false;
+  orchestrator.active.state.activeReviewPreset = presetName;
+  saveTask(orchestrator.active.dir, orchestrator.active.state);
+
+  const reviewers = resolveReviewers(orchestrator, phase, presetName);
+  const enabledCount = Object.values(reviewers).filter((v) => isEnabled(v)).length;
   if (enabledCount === 0) {
     orchestrator.active.state.reviewCycle = null;
     saveTask(orchestrator.active.dir, orchestrator.active.state);
@@ -174,41 +305,77 @@ export async function enterReviewCycle(orchestrator: Orchestrator, ctx: any, kin
     return `No ${label} reviewers enabled. Choose another option.`;
   }
 
-  orchestrator.reviewTransitionToken = -1;
   orchestrator.pendingSubagentSpawns = enabledCount;
-  const spawnFn = phase === "brainstorm"
-    ? () => spawnBrainstormReviewers(pi, orchestrator.cwd, orchestrator.active!.dir, orchestrator.active!.taskId, config, pass)
-    : phase === "plan"
-    ? () => spawnPlanReviewers(pi, orchestrator.cwd, orchestrator.active!.dir, orchestrator.active!.taskId, config)
-    : () => spawnCodeReviewers(pi, orchestrator.cwd, orchestrator.active!.dir, orchestrator.active!.taskId, config, pass);
-  spawnFn().then((result) => {
-    orchestrator.failedReviewerVariants = result.failedVariants;
-    if (result.spawned === 0) orchestrator.pendingSubagentSpawns = 0;
-    for (const id of result.agentIds ?? []) {
-      orchestrator.spawnedAgentIds.delete(id);
-    }
-    orchestrator.pendingSubagentSpawns = 0;
-    tryCompleteReviewCycle(orchestrator);
-  }).catch((err) => {
-    orchestrator.pendingSubagentSpawns = 0;
-    tryCompleteReviewCycle(orchestrator);
-    console.error(`[pi-pi] spawn reviewers failed (${phase}): ${err.message}`);
+    const spawnFn = phase === "brainstorm"
+      ? () => spawnBrainstormReviewers(
+        pi,
+        orchestrator.cwd,
+        orchestrator.active!.dir,
+        orchestrator.active!.taskId,
+        orchestrator.config,
+        pass,
+        orchestrator.transitionController.phaseSend,
+        reviewers,
+        orchestrator.active?.state.repos ?? [],
+      )
+      : phase === "plan"
+      ? () => spawnPlanReviewers(
+        pi,
+        orchestrator.cwd,
+        orchestrator.active!.dir,
+        orchestrator.active!.taskId,
+        orchestrator.config,
+        pass,
+        orchestrator.transitionController.phaseSend,
+        reviewers,
+        orchestrator.active?.state.repos ?? [],
+      )
+      : () => spawnCodeReviewers(
+        pi,
+        orchestrator.cwd,
+        orchestrator.active!.dir,
+        orchestrator.active!.taskId,
+        orchestrator.config,
+        pass,
+        phase,
+        orchestrator.transitionController.phaseSend,
+        reviewers,
+        orchestrator.active?.state.repos ?? [],
+      );
+  handleSpawnResult(orchestrator, spawnFn(), {
+    kind: "reviewer",
+    logScope: "review",
+    logMessage: "spawn reviewers failed",
+    logExtra: { phase },
+    onSettled: (result) => tryCompleteReviewCycle(orchestrator, result?.spawned),
   });
 
   orchestrator.active.state.reviewCycle.step = "await_reviewers";
   orchestrator.active.state.step = "await_reviewers";
   saveTask(orchestrator.active.dir, orchestrator.active.state);
-  return `Started review cycle pass ${pass} (${kind}). Awaiting reviewers.`;
+  return `Started review cycle pass ${pass} (auto, preset: ${presetName}). Awaiting reviewers.`;
 }
 
 export async function stopTask(orchestrator: Orchestrator): Promise<string> {
   if (!orchestrator.active) return "No active task.";
   orchestrator.abortAllSubagents();
+  orchestrator.active.state.reviewCycle = null;
   saveTask(orchestrator.active.dir, orchestrator.active.state);
   const desc = orchestrator.active.description;
+  const type = orchestrator.active.type;
   await orchestrator.cleanupActive();
   const taskStore = (globalThis as any)[Symbol.for("pi-tasks:store")];
   taskStore?.clearAll?.();
+
+  // Route the stop/pause compaction through the controller as a "done" target.
+  // The controller supplies the summary to session_before_compact and its
+  // awaitable resolves at every terminus (session_compact, no-op skip,
+  // already-idle), so this await never hangs and never resolves early.
+  await orchestrator.transitionController.requestTransition({
+    kind: "done",
+    summary: `Task "${desc}" (${type}) stopped/paused.`,
+  });
+
   return `Task "${desc}" stopped. Use /pp → Resume to continue.`;
 }
 
@@ -217,19 +384,184 @@ export function finalizeReviewCycle(task: ActiveTask): void {
   const kind = task.state.reviewCycle.kind;
   task.state.reviewPass = task.state.reviewCycle.pass;
   task.reviewPass = task.state.reviewPass;
-  if (!task.state.reviewPassByKind) task.state.reviewPassByKind = {};
-  task.state.reviewPassByKind[kind] = (task.state.reviewPassByKind[kind] ?? 0) + 1;
+  incrementReviewPass(task, kind);
   task.state.reviewCycle = null;
   task.state.step = "user_gate";
   saveTask(task.dir, task.state);
 }
 
+function incrementReviewPass(task: ActiveTask, kind: string): void {
+  if (!task.state.reviewPassByKind) task.state.reviewPassByKind = {};
+  const phase = task.state.phase;
+  if (!task.state.reviewPassByKind[phase]) task.state.reviewPassByKind[phase] = {};
+  task.state.reviewPassByKind[phase][kind] = (task.state.reviewPassByKind[phase][kind] ?? 0) + 1;
+}
+
+function completedReviewPasses(task: ActiveTask, kind: string): number {
+  return task.state.reviewPassByKind?.[task.state.phase]?.[kind] ?? 0;
+}
+
+export function finalizeReviewCycleAutonomous(task: ActiveTask): void {
+  if (!task.state.reviewCycle) return;
+  const kind = task.state.reviewCycle.kind;
+  task.state.reviewPass = task.state.reviewCycle.pass;
+  task.reviewPass = task.state.reviewPass;
+  incrementReviewPass(task, kind);
+  task.state.reviewCycle = null;
+  if (task.state.phase === "plan") {
+    task.state.step = "synthesize";
+  } else {
+    task.state.step = "llm_work";
+  }
+  saveTask(task.dir, task.state);
+}
+
 function registerOrchestratorTools(orchestrator: Orchestrator): void {
+  registerRepoTool(orchestrator);
   registerPhaseCompleteTool(orchestrator);
   registerCommitTool(orchestrator);
   registerSpecifyReviewsTool(orchestrator);
 }
 
+function registerRepoTool(orchestrator: Orchestrator): void {
+  const pi = orchestrator.pi;
+
+  pi.registerTool({
+    name: "pp_register_repo",
+    label: "pi-pi",
+    description:
+      "Register a git repository you're working in. Call this for every repo " +
+      "including the root directory at the start of each task. Pass the base " +
+      "branch — the branch this work will be merged into (e.g. origin/main, origin/develop).",
+    parameters: Type.Object({
+      path: Type.String({ description: "Absolute path to the git repository (or any path inside it)" }),
+      baseBranch: Type.Optional(Type.String({ description: "Base branch for this repo (e.g. origin/main)" })),
+    }),
+    async execute(_toolCallId, params: any) {
+      if (!orchestrator.active) {
+        return { content: [{ type: "text" as const, text: "No active task." }], isError: true as const, details: {} };
+      }
+      getLogger().debug({ s: "tool", tool: "pp_register_repo", path: params.path, baseBranch: params.baseBranch }, "register repo called");
+
+      const pathInput = typeof params.path === "string" ? params.path.trim() : "";
+      if (!pathInput) {
+        return { content: [{ type: "text" as const, text: "Missing path." }], isError: true as const, details: {} };
+      }
+
+      const normalizedInputPath = normalizeRepoPath(pathInput);
+      let gitCwd = normalizedInputPath;
+      try {
+        gitCwd = statSync(normalizedInputPath).isDirectory() ? normalizedInputPath : dirname(normalizedInputPath);
+      } catch {
+        gitCwd = dirname(normalizedInputPath);
+      }
+
+      let gitRoot = "";
+      try {
+        const result = await pi.exec("git", ["rev-parse", "--show-toplevel"], { cwd: gitCwd, timeout: 5000 });
+        if (result.code !== 0) {
+          return { content: [{ type: "text" as const, text: "Not a git repository." }], isError: true as const, details: {} };
+        }
+        gitRoot = result.stdout.trim();
+      } catch {
+        return { content: [{ type: "text" as const, text: "Not a git repository." }], isError: true as const, details: {} };
+      }
+
+      if (!gitRoot) {
+        return { content: [{ type: "text" as const, text: "Not a git repository." }], isError: true as const, details: {} };
+      }
+
+      const normalizedRepo = normalizeRepoPath(gitRoot);
+      const normalizedRoot = normalizeRepoPath(orchestrator.cwd);
+      const hadRepos = Array.isArray(orchestrator.active.state.repos);
+      const repos = orchestrator.active.state.repos ?? [{ path: normalizedRoot, isRoot: true }];
+      const baseBranch = typeof params.baseBranch === "string" && params.baseBranch.trim().length > 0
+        ? params.baseBranch.trim()
+        : undefined;
+      const isRoot = normalizedRepo === normalizedRoot;
+
+      let added = false;
+      let changed = !hadRepos;
+
+      if (isRoot) {
+        const existingRootIdx = repos.findIndex((repo) => repo.isRoot);
+        const existingByPathIdx = repos.findIndex((repo) => repo.path === normalizedRepo);
+
+        if (existingRootIdx >= 0) {
+          const existingRoot = repos[existingRootIdx];
+          if (existingRoot.path !== normalizedRepo) {
+            existingRoot.path = normalizedRepo;
+            changed = true;
+          }
+          if (!existingRoot.isRoot) {
+            existingRoot.isRoot = true;
+            changed = true;
+          }
+          if (baseBranch && existingRoot.baseBranch !== baseBranch) {
+            existingRoot.baseBranch = baseBranch;
+            changed = true;
+          }
+          if (existingByPathIdx >= 0 && existingByPathIdx !== existingRootIdx) {
+            repos.splice(existingByPathIdx, 1);
+            changed = true;
+          }
+        } else if (existingByPathIdx >= 0) {
+          const existing = repos[existingByPathIdx];
+          if (!existing.isRoot) {
+            existing.isRoot = true;
+            changed = true;
+          }
+          if (baseBranch && existing.baseBranch !== baseBranch) {
+            existing.baseBranch = baseBranch;
+            changed = true;
+          }
+        } else {
+          repos.push({ path: normalizedRepo, isRoot: true, ...(baseBranch ? { baseBranch } : {}) });
+          added = true;
+          changed = true;
+        }
+      } else {
+        const existingByPathIdx = repos.findIndex((repo) => repo.path === normalizedRepo);
+        if (existingByPathIdx >= 0) {
+          const existing = repos[existingByPathIdx];
+          if (baseBranch && existing.baseBranch !== baseBranch) {
+            existing.baseBranch = baseBranch;
+            changed = true;
+          }
+        } else {
+          repos.push({ path: normalizedRepo, isRoot: false, ...(baseBranch ? { baseBranch } : {}) });
+          added = true;
+          changed = true;
+        }
+      }
+
+      orchestrator.active.state.repos = repos;
+      if (changed) {
+        saveTask(orchestrator.active.dir, orchestrator.active.state);
+      }
+
+      if (added) {
+        unregisterAgentDefinitions(orchestrator.pi);
+        orchestrator.registerAgents();
+      }
+
+      const registered = repos.find((repo) => repo.path === normalizedRepo) ?? {
+        path: normalizedRepo,
+        isRoot,
+        ...(baseBranch ? { baseBranch } : {}),
+      };
+      const rootLabel = registered.isRoot ? " (root)" : "";
+      const baseLabel = registered.baseBranch ? `, base: ${registered.baseBranch}` : "";
+      const action = added ? "Registered" : changed ? "Updated" : "Already registered";
+
+      return {
+        content: [{ type: "text" as const, text: `${action} repository: ${registered.path}${rootLabel}${baseLabel}` }],
+        details: {},
+      };
+    },
+  });
+}
+
 function openCodeReviewDirect(
   pi: ExtensionAPI,
   payload: Record<string, unknown>,
@@ -259,7 +591,8 @@ function registerSpecifyReviewsTool(orchestrator: Orchestrator): void {
     description:
       "Specify which repositories and commit ranges to open in Plannotator for code review. " +
       "Called when the user requests a Plannotator code review. " +
-      "Plannotator will open sequentially for each entry. Results are returned after all reviews complete.",
+      "Plannotator will open sequentially for each entry. Results are returned after all reviews complete. " +
+      "Range supports both 'base..HEAD' and 'base..target' (non-HEAD target is reviewed via temporary worktree checkout).",
     parameters: Type.Object({
       reviews: Type.Array(Type.Object({
         cwd: Type.String({ description: "Absolute path to the git repository" }),
@@ -267,6 +600,9 @@ function registerSpecifyReviewsTool(orchestrator: Orchestrator): void {
       })),
     }),
     async execute(_toolCallId, params: any, _signal, _onUpdate, ctx) {
+      if (orchestrator.active && getEffectiveMode(orchestrator.active.state) === "autonomous") {
+        return { content: [{ type: "text" as const, text: "Plannotator review is not available in autonomous mode. Continue with automated reviews via pp_phase_complete." }], isError: true as const, details: {} };
+      }
       if (!params.reviews || params.reviews.length === 0) {
         return { content: [{ type: "text" as const, text: "No reviews specified." }], isError: true as const, details: {} };
       }
@@ -275,12 +611,89 @@ function registerSpecifyReviewsTool(orchestrator: Orchestrator): void {
       let hasNeedsChanges = false;
       for (const review of params.reviews) {
         ctx.ui?.setWorkingMessage?.(`Waiting for Plannotator review: ${review.range}…`);
-        const rangeBase = review.range.includes("..") ? review.range.split("..")[0] : review.range;
+        const range = String(review.range ?? "").trim();
+        let compareBase = range;
+        let compareTarget = "HEAD";
+        const rangeSeparatorIdx = range.indexOf("..");
+        if (rangeSeparatorIdx >= 0) {
+          compareBase = range.slice(0, rangeSeparatorIdx).trim();
+          compareTarget = range.slice(rangeSeparatorIdx + 2).trim() || "HEAD";
+        }
+
+        if (!compareBase) {
+          results.push(`${review.cwd} (${review.range}): Invalid range (missing base).`);
+          continue;
+        }
+
+        let reviewCwd = review.cwd;
+        let tempWorktreePath: string | null = null;
+        let tempWorktreeParent: string | null = null;
+        let setupError: string | null = null;
+
+        if (compareTarget !== "HEAD") {
+          tempWorktreeParent = mkdtempSync(join(tmpdir(), "pi-pi-review-worktree-"));
+          tempWorktreePath = join(tempWorktreeParent, "checkout");
+          try {
+            const addResult = await pi.exec("git", ["worktree", "add", "--detach", tempWorktreePath, compareTarget], {
+              cwd: review.cwd,
+              timeout: 20000,
+            });
+            if (addResult.code !== 0) {
+              setupError = addResult.stderr?.trim() || addResult.stdout?.trim() || "Failed to prepare temporary worktree";
+            } else {
+              reviewCwd = tempWorktreePath;
+            }
+          } catch (error: any) {
+            setupError = error?.message ?? String(error);
+          }
+        }
+
+        if (setupError) {
+          results.push(`${review.cwd} (${review.range}): ${setupError}`);
+          if (tempWorktreePath) {
+            try {
+              await pi.exec("git", ["worktree", "remove", "--force", tempWorktreePath], {
+                cwd: review.cwd,
+                timeout: 20000,
+              });
+            } catch {}
+          }
+          if (tempWorktreePath) {
+            try {
+              rmSync(tempWorktreePath, { recursive: true, force: true });
+            } catch {}
+          }
+          if (tempWorktreeParent) {
+            try {
+              rmSync(tempWorktreeParent, { recursive: true, force: true });
+            } catch {}
+          }
+          continue;
+        }
+
         const result = await openCodeReviewDirect(pi, {
-          cwd: review.cwd,
+          cwd: reviewCwd,
           diffType: "branch",
-          defaultBranch: rangeBase,
+          defaultBranch: compareBase,
         });
+
+        if (tempWorktreePath) {
+          try {
+            await pi.exec("git", ["worktree", "remove", "--force", tempWorktreePath], {
+              cwd: review.cwd,
+              timeout: 20000,
+            });
+          } catch {}
+          try {
+            rmSync(tempWorktreePath, { recursive: true, force: true });
+          } catch {}
+          if (tempWorktreeParent) {
+            try {
+              rmSync(tempWorktreeParent, { recursive: true, force: true });
+            } catch {}
+          }
+        }
+
         if ("error" in result) {
           results.push(`${review.cwd} (${review.range}): ${result.error}`);
         } else {
@@ -307,9 +720,18 @@ function registerSpecifyReviewsTool(orchestrator: Orchestrator): void {
 
       ctx.ui?.setWorkingMessage?.("Waiting for user input…");
       try {
-        const { showActiveTaskMenu } = await import("./pp-menu.js");
+        const { showActiveTaskMenu, USER_CANCELLED } = await import("./pp-menu.js");
         const text = await showActiveTaskMenu(orchestrator, ctx, `Plannotator review complete.\n\n${summary}`, "tool");
-        if (orchestrator.phaseCompactionPending || orchestrator.taskDoneCompactionPending) {
+        // Deliberate user ESC: stop the turn cleanly (mirror ask_user), no
+        // reminder text that would start a new LLM turn.
+        if (text === USER_CANCELLED) {
+          ctx.abort?.();
+          return { content: [{ type: "text" as const, text: "" }], details: {} };
+        }
+        // A transition may have started while the menu was open. The controller
+        // is the source of truth; abort the agent's pending turn so it doesn't
+        // race the transition. (Interactive-UX abort — stays local, not routed.)
+        if (!orchestrator.transitionController.isRunning()) {
           ctx.abort?.();
           return { content: [{ type: "text" as const, text: "" }], details: {} };
         }
@@ -326,7 +748,7 @@ function registerSpecifyReviewsTool(orchestrator: Orchestrator): void {
 
 function loadPhaseReviewOutputs(taskDir: string, phase: string, pass: number): { name: string; content: string }[] {
   if (phase === "brainstorm") return loadBrainstormReviewOutputs(taskDir, pass);
-  if (phase === "plan") return loadPlanReviewOutputs(taskDir);
+  if (phase === "plan") return loadPlanReviewOutputs(taskDir, pass);
   return loadCodeReviewOutputs(taskDir, pass);
 }
 
@@ -339,37 +761,65 @@ function registerCommitTool(orchestrator: Orchestrator): void {
     description:
       "Commit modified files with a descriptive message. Call after completing a logical " +
       "unit of work (e.g. implementing one plan item, fixing a bug, adding a test). " +
-      "The message should describe WHAT changed and WHY, not list files.",
+      "The message should describe WHAT changed and WHY, not list files. " +
+      "Prefix the message with a conventional-commit type (fix:, feat:, or chore:) " +
+      "unless the user asked for a different commit style.",
     parameters: Type.Object({
       message: Type.String({ description: "Commit message describing the change (max 72 chars for first line)" }),
+      repo: Type.Optional(Type.String({ description: "Absolute path to the repo to commit in. Defaults to root." })),
     }),
     async execute(_toolCallId, params: any) {
       if (!orchestrator.active) {
         return { content: [{ type: "text" as const, text: "No active task." }], isError: true as const, details: {} };
       }
-      if (!orchestrator.config.autoCommit) {
+      if (!orchestrator.config.general.autoCommit) {
         return { content: [{ type: "text" as const, text: "autoCommit is disabled in config." }], details: {} };
       }
+
+      const repos = orchestrator.active.state.repos ?? [];
+      const rootRepo = findRootRepo(repos);
+      const defaultRepoPath = rootRepo?.path ?? orchestrator.cwd;
+      let commitRepoPath = defaultRepoPath;
+      if (typeof params.repo === "string" && params.repo.trim().length > 0) {
+        const normalized = normalizeRepoPath(params.repo);
+        const registered = repos.find((repo) => repo.path === normalized);
+        if (!registered) {
+          return { content: [{ type: "text" as const, text: `Repository is not registered: ${params.repo}` }], isError: true as const, details: {} };
+        }
+        commitRepoPath = registered.path;
+      }
+
       const files: string[] = [];
       try {
-        const gitResult = await pi.exec("git", ["diff", "--name-only"], { cwd: orchestrator.cwd, timeout: 5000 });
-        if (gitResult.code === 0 && gitResult.stdout.trim()) {
-          files.push(...gitResult.stdout.trim().split("\n").filter(Boolean));
-        }
-        const stagedResult = await pi.exec("git", ["diff", "--name-only", "--cached"], { cwd: orchestrator.cwd, timeout: 5000 });
-        if (stagedResult.code === 0 && stagedResult.stdout.trim()) {
-          for (const f of stagedResult.stdout.trim().split("\n").filter(Boolean)) {
-            if (!files.includes(f)) files.push(f);
+        const statusResult = await pi.exec("git", ["status", "--porcelain"], { cwd: commitRepoPath, timeout: 5000 });
+        if (statusResult.code === 0 && statusResult.stdout.trim()) {
+          for (const rawLine of statusResult.stdout.split("\n")) {
+            const line = rawLine.trimEnd();
+            if (!line) continue;
+            const pathPart = line.slice(3);
+            if (!pathPart) continue;
+            const finalPath = pathPart.includes(" -> ") ? pathPart.split(" -> ").at(-1)! : pathPart;
+            if (!files.includes(finalPath)) {
+              files.push(finalPath);
+            }
           }
         }
       } catch {}
       if (files.length === 0) {
         return { content: [{ type: "text" as const, text: "No modified files to commit." }], details: {} };
       }
-      const result = autoCommit(files, params.message, orchestrator.cwd);
+      const result = autoCommit(files, params.message, commitRepoPath);
       if (result.ok) {
-        orchestrator.active.modifiedFiles.clear();
-        orchestrator.active.state.modifiedFiles = [];
+        const remaining = [...orchestrator.active.modifiedFiles].filter((file) => {
+          const absoluteFile = resolve(orchestrator.cwd, file);
+          const repo = resolveRepoForFile(repos, absoluteFile);
+          return repo?.path !== commitRepoPath;
+        });
+        orchestrator.active.modifiedFiles = new Set(remaining);
+        orchestrator.active.state.modifiedFiles = [...orchestrator.active.modifiedFiles];
+        const committed = new Set(orchestrator.active.state.committedFiles ?? []);
+        for (const file of files) committed.add(file);
+        orchestrator.active.state.committedFiles = [...committed];
         saveTask(orchestrator.active.dir, orchestrator.active.state);
         orchestrator.commitReminderSent = false;
         return { content: [{ type: "text" as const, text: `Committed ${files.length} file(s): ${result.commitHash ?? "ok"}` }], details: {} };
@@ -403,15 +853,102 @@ function registerPhaseCompleteTool(orchestrator: Orchestrator): void {
         const count = orchestrator.spawnedAgentIds.size + orchestrator.pendingSubagentSpawns;
         return { content: [{ type: "text" as const, text: `${count} subagent(s) still running. Wait for them to complete before calling pp_phase_complete.` }], isError: true as const, details: {} };
       }
+      // Gate on the effective PHASE mode, not the task mode: brainstorm/debug/
+      // review are always user-driven even for an autonomous task, so they must
+      // fall through to the guided menu path below rather than auto-advancing.
+      const effectiveMode = getEffectivePhaseMode(orchestrator.active.state);
+      if (effectiveMode === "autonomous") {
+        const phase = orchestrator.active.state.phase;
+        let justFinalizedReviewCycle = false;
+        if (orchestrator.active.state.reviewCycle?.step === "apply_feedback") {
+          const completedRound = orchestrator.active.state.reviewCycle.pass;
+          const completedPreset = normalizeStoredReviewPresetName(orchestrator, phase);
+          const enabledReviewerCount = Object.values(resolveReviewers(orchestrator, phase, completedPreset)).filter((v) => isEnabled(v)).length;
+          finalizeReviewCycleAutonomous(orchestrator.active);
+          justFinalizedReviewCycle = true;
+          if (reviewPassUnanimousApprove(orchestrator.active.dir, phase, completedRound, enabledReviewerCount)) {
+            orchestrator.active.state.reviewApprovedClean = true;
+            saveTask(orchestrator.active.dir, orchestrator.active.state);
+          }
+        }
+        const phaseConfig = orchestrator.active.state.autonomousConfig?.phases?.[phase];
+        const reviewPreset = phaseConfig?.reviewPreset;
+        const maxReviewPasses = phaseConfig?.maxReviewPasses ?? 0;
+        const completedAutoPasses = orchestrator.active.state.reviewPassByKind?.[phase]?.auto ?? 0;
+
+        if (
+          justFinalizedReviewCycle &&
+          !orchestrator.active.state.reviewApprovedClean &&
+          reviewPreset &&
+          maxReviewPasses > 0 &&
+          completedAutoPasses < maxReviewPasses
+        ) {
+          return {
+            content: [{ type: "text" as const, text: `The review pass found changes to make. Apply the reviewers' required changes, then call pp_phase_complete again to re-review (pass ${completedAutoPasses + 1}/${maxReviewPasses >= 999 ? "∞" : maxReviewPasses}). Do NOT wait for the user and do NOT advance the phase.` }],
+            details: {},
+          };
+        }
+
+        if (
+          !justFinalizedReviewCycle &&
+          !orchestrator.active.state.reviewApprovedClean &&
+          reviewPreset &&
+          maxReviewPasses > 0 &&
+          completedAutoPasses < maxReviewPasses
+        ) {
+          const exitCheck = validateExitCriteria(orchestrator.active.dir, orchestrator.active.type, phase);
+          if (!exitCheck.ok) {
+            return {
+              content: [{ type: "text" as const, text: `Cannot start review yet: ${exitCheck.reason}\n\nFix this and call pp_phase_complete again. Do NOT wait for the user.` }],
+              details: {},
+            };
+          }
+          const reviewText = await enterReviewCycle(orchestrator, ctx, reviewPreset);
+          if (orchestrator.active?.state.step === "await_reviewers") {
+            return {
+              content: [{ type: "text" as const, text: `Reviews are running (${reviewPreset}, pass ${completedAutoPasses + 1}/${maxReviewPasses >= 999 ? "∞" : maxReviewPasses}). You will be notified automatically when the reviewer outputs are ready — then read them and proceed. Do NOT wait for the user and do NOT stop.` }],
+              details: {},
+            };
+          }
+          if (!reviewText.includes("No") || !reviewText.includes("reviewers enabled")) {
+            return { content: [{ type: "text" as const, text: reviewText }], details: {} };
+          }
+        }
+
+        const plannerPreset = orchestrator.active.state.autonomousConfig?.phases?.plan?.plannerPreset;
+        const result = await orchestrator.transitionToNextPhase(ctx, plannerPreset);
+        if (!result.ok) {
+          return { content: [{ type: "text" as const, text: `Transition blocked: ${result.error}` }], details: {} };
+        }
+        return { content: [{ type: "text" as const, text: "" }], details: {} };
+      }
       ctx.ui.setWorkingMessage?.("Waiting for user approval…");
       try {
-        const { showActiveTaskMenu } = await import("./pp-menu.js");
+        const { showActiveTaskMenu, USER_CANCELLED } = await import("./pp-menu.js");
         const text = await showActiveTaskMenu(orchestrator, ctx, params.summary, "tool");
-        if (orchestrator.phaseCompactionPending || orchestrator.taskDoneCompactionPending) {
+        // A deliberate user ESC on the menu means "stop cleanly, let me type" —
+        // mirror ask_user: abort the turn and return nothing so no new LLM turn
+        // starts. This takes precedence over the reminder path below, in ALL
+        // interactive cases (including while a transition is mid-flight).
+        if (text === USER_CANCELLED) {
+          ctx.abort?.();
+          return { content: [{ type: "text" as const, text: "" }], details: {} };
+        }
+        // A transition or await may have started while the menu was open. The
+        // controller is the source of truth; abort the pending turn so it can't
+        // race. (Interactive-UX abort — stays local, not routed.)
+        const curStep = orchestrator.active?.state.step;
+        if (curStep === "await_planners" || curStep === "await_reviewers") {
+          ctx.abort?.();
+          return { content: [{ type: "text" as const, text: `Waiting for ${curStep === "await_planners" ? "planners" : "reviewers"} to complete. Do NOT proceed until notified.` }], details: {} };
+        }
+        if (!orchestrator.transitionController.isRunning()) {
           ctx.abort?.();
           return { content: [{ type: "text" as const, text: "" }], details: {} };
         }
         if (!text) {
+          // Non-ESC dismissal (explicit "Back") while a transition is running:
+          // keep the intentional artifact-update reminder (commit 10e7021).
           return { content: [{ type: "text" as const, text: "User dismissed the menu. Wait for the user's next message. When you resume work, update USER_REQUEST.md and RESEARCH.md with any new findings before calling pp_phase_complete." }], details: {} };
         }
         return { content: [{ type: "text" as const, text }], details: {} };
@@ -422,9 +959,104 @@ function registerPhaseCompleteTool(orchestrator: Orchestrator): void {
   });
 }
 
+function registerMainTraceHooks(orchestrator: Orchestrator): void {
+  const pi = orchestrator.pi;
+  // These hooks are registered only on the root orchestrator session
+  // (registerEventHandlers is never called from the subagent branch in index.ts),
+  // so they only ever receive root-session events — no SUBAGENT_SESSION_KEY gate needed.
+
+  pi.on("before_agent_start", async (event) => {
+    getTracer()?.traceMain("before_agent_start", {
+      prompt: event.prompt,
+      images: event.images,
+      systemPrompt: event.systemPrompt,
+    });
+  });
+  pi.on("agent_start", async () => {
+    getTracer()?.traceMain("agent_start", {});
+  });
+  pi.on("agent_end", async (event) => {
+    getTracer()?.traceMain("agent_end", { messages: event.messages });
+  });
+  pi.on("turn_start", async (event) => {
+    const tracer = getTracer();
+    if (tracer) tracer.turnIndex = event.turnIndex;
+    tracer?.traceMain("turn_start", { turnIndex: event.turnIndex, timestamp: event.timestamp });
+  });
+  pi.on("turn_end", async (event) => {
+    const tracer = getTracer();
+    if (tracer) tracer.turnIndex = event.turnIndex;
+    tracer?.traceMain("turn_end", { turnIndex: event.turnIndex, message: event.message, toolResults: event.toolResults });
+  });
+  pi.on("message_start", async (event) => {
+    const tracer = getTracer();
+    tracer?.traceMain("message_start", { turnIndex: tracer.turnIndex, message: event.message });
+  });
+  pi.on("message_update", async (event) => {
+    const tracer = getTracer();
+    tracer?.traceMain("message_update", { turnIndex: tracer.turnIndex, assistantMessageEvent: event.assistantMessageEvent });
+  });
+  pi.on("message_end", async (event) => {
+    const tracer = getTracer();
+    tracer?.traceMain("message_end", { turnIndex: tracer.turnIndex, message: event.message });
+  });
+  pi.on("tool_execution_start", async (event) => {
+    const tracer = getTracer();
+    tracer?.traceMain("tool_execution_start", { turnIndex: tracer.turnIndex, toolCallId: event.toolCallId, toolName: event.toolName, args: event.args });
+  });
+  pi.on("tool_execution_update", async (event) => {
+    const tracer = getTracer();
+    tracer?.traceMain("tool_execution_update", { turnIndex: tracer.turnIndex, toolCallId: event.toolCallId, toolName: event.toolName, args: event.args, partialResult: event.partialResult });
+  });
+  pi.on("tool_execution_end", async (event) => {
+    const tracer = getTracer();
+    tracer?.traceMain("tool_execution_end", { turnIndex: tracer.turnIndex, toolCallId: event.toolCallId, toolName: event.toolName, result: event.result, isError: event.isError });
+  });
+}
+
 export function registerEventHandlers(orchestrator: Orchestrator): void {
   const pi = orchestrator.pi;
 
+  registerMainTraceHooks(orchestrator);
+
+  // Personal-subscription Claude routing registers the sub provider with a
+  // literal OAuth token (a static snapshot). That token expires within a few
+  // hours, so a long-lived session would keep sending a stale token and the
+  // gateway would return 401. Refresh (and re-register on change) before each
+  // turn's LLM call. Cheap no-op when subscription routing is inactive or the
+  // token is unchanged. registerEventHandlers runs only on the root session.
+  pi.on("turn_start", async () => {
+    try {
+      const { refreshSubProvider } = await import("./flant-infra.js");
+      await refreshSubProvider(pi);
+    } catch (err: any) {
+      getLogger().debug({ s: "flant", err: err?.message }, "sub provider refresh failed");
+    }
+  });
+
+  // TransitionController drivers. These are the reliable idle/completion signals:
+  //   - agent_end: the main loop went idle. If a transition is pending, this is
+  //     when the controller fires compaction.
+  //   - session_compact: compaction finished. The controller resumes (injects
+  //     context/artifacts + sends the next instruction).
+  // The SDK supports multiple handlers per event, so these coexist with the
+  // trace-only hooks registered above. registerEventHandlers is never called on
+  // the subagent branch, so these only ever see root-session events.
+  pi.on("agent_end", async (_event, ctx) => {
+    if (ctx) orchestrator.lastCtx = ctx;
+    orchestrator.transitionController.onAgentEnd();
+  });
+  pi.on("session_compact", async (_event, ctx) => {
+    if (ctx) orchestrator.lastCtx = ctx;
+    orchestrator.transitionController.onSessionCompact();
+  });
+
+  // Expose the event-driven planner-completion check so initial plan-entry
+  // spawns (in command-handlers / orchestrator) can wire it as their onSettled
+  // safety net (the deleted poller's former role). checkPlannerCompletion is a
+  // hoisted function declaration below.
+  orchestrator.checkPlannerCompletion = () => checkPlannerCompletion();
+
   function getUsageTracker(): UsageTracker | undefined {
     return (globalThis as any)[USAGE_TRACKER_KEY] as UsageTracker | undefined;
   }
@@ -444,6 +1076,25 @@ export function registerEventHandlers(orchestrator: Orchestrator): void {
     if (event === "first_turn" && lifecycle.firstTurnAt == null) lifecycle.firstTurnAt = now;
     orchestrator.agentLifecycle.set(data.id, lifecycle);
 
+    getTracer()?.traceMain("subagent_lifecycle", {
+      event,
+      subagentId: data.id,
+      type: data.type ?? lifecycle.type,
+      description: data.description ?? lifecycle.description,
+      parentToolCallId: data.toolCallId,
+      phase: lifecycle.phase,
+      step: lifecycle.step,
+      toolName: data.toolName,
+      turnCount: data.turnCount,
+      tokens: data.tokens,
+      durationMs: data.durationMs,
+      toolUses: data.toolUses,
+      modelId: data.modelId,
+      status: data.status,
+      error: data.error,
+      result: data.result,
+    });
+
     const ageMs = lifecycle.createdAt == null ? 0 : now - lifecycle.createdAt;
     const startedDeltaMs = lifecycle.startedAt == null || lifecycle.createdAt == null ? undefined : lifecycle.startedAt - lifecycle.createdAt;
     const firstToolDeltaMs = lifecycle.firstToolAt == null || lifecycle.createdAt == null ? undefined : lifecycle.firstToolAt - lifecycle.createdAt;
@@ -451,8 +1102,8 @@ export function registerEventHandlers(orchestrator: Orchestrator): void {
     const pending = orchestrator.pendingSubagentSpawns;
     const running = orchestrator.spawnedAgentIds.size;
     const desc = data.description || lifecycle.description || data.type || lifecycle.type || data.id;
-    appendTaskLog(orchestrator.active.dir, "subagent-lifecycle.jsonl", {
-      timestamp: new Date(now).toISOString(),
+    getLogger().debug({
+      s: "subagent",
       id: data.id,
       event,
       description: desc,
@@ -467,7 +1118,7 @@ export function registerEventHandlers(orchestrator: Orchestrator): void {
       createdToFirstTurnMs: firstTurnDeltaMs ?? null,
       toolName: data.toolName ?? null,
       turnCount: data.turnCount ?? null,
-    });
+    }, "subagent lifecycle event");
   }
 
   function startStaleAgentWatchdog(): void {
@@ -480,7 +1131,7 @@ export function registerEventHandlers(orchestrator: Orchestrator): void {
       }
       const mgr = (globalThis as any)[Symbol.for("pi-subagents:manager")];
       const now = Date.now();
-      const staleMs = orchestrator.config.timeouts.agentStale;
+      const staleMs = orchestrator.config.performance.internals.subagentStale;
       for (const [id, spawnTime] of orchestrator.agentSpawnTimes) {
         const record = mgr?.getRecord?.(id);
         if (record?.status === "running" || record?.status === "queued") continue;
@@ -492,13 +1143,13 @@ export function registerEventHandlers(orchestrator: Orchestrator): void {
           orchestrator.agentSpawnTimes.delete(id);
           orchestrator.agentDescriptions.delete(id);
           orchestrator.agentLifecycle.delete(id);
-          pi.sendMessage(
+          orchestrator.transitionController.sendCustom(
             {
               customType: "pp-agent-stale",
               content: `Aborted stale agent "${desc}" — no completion after ${Math.round(staleMs / 1000)}s.`,
               display: true,
             },
-            { deliverAs: "steer" },
+            "context",
           );
         }
       }
@@ -538,6 +1189,15 @@ export function registerEventHandlers(orchestrator: Orchestrator): void {
     trackSubagentEvent(data, "first_turn");
   });
 
+  function markAllAgentsConsumed(): void {
+    const mgr = (globalThis as any)[Symbol.for("pi-subagents:manager")];
+    if (!mgr?.getRecord) return;
+    for (const id of orchestrator.agentDescriptions.keys()) {
+      const record = mgr.getRecord(id);
+      if (record) record.resultConsumed = true;
+    }
+  }
+
   function checkPlannerCompletion(): void {
     if (
       !orchestrator.active ||
@@ -545,7 +1205,7 @@ export function registerEventHandlers(orchestrator: Orchestrator): void {
       orchestrator.active.state.step !== "await_planners" ||
       orchestrator.spawnedAgentIds.size > 0 ||
       orchestrator.pendingSubagentSpawns > 0 ||
-      orchestrator.phaseCompactionPending
+      orchestrator.transitionController.isTransitioning()
     ) return;
 
     const plansDir = join(orchestrator.active.dir, "plans");
@@ -553,8 +1213,75 @@ export function registerEventHandlers(orchestrator: Orchestrator): void {
       readdirSync(plansDir).some((f) => f.endsWith(".md") && !f.includes("synthesized") && !f.includes("review_"));
 
     const failedPlannerVariants = [...orchestrator.failedPlannerVariants];
+    const effectiveMode = getEffectiveMode(orchestrator.active.state);
+    if (effectiveMode === "autonomous" && failedPlannerVariants.length > 0) {
+      const alreadyRetried = orchestrator.active.state.plannerFailureAutoRetried === true;
+      if (!alreadyRetried) {
+        const failedSet = new Set(failedPlannerVariants);
+        const presetName = normalizeStoredPlannerPresetName(orchestrator);
+        const planners = resolvePreset(orchestrator.config, "planners", presetName);
+        const scopedPlanners: typeof planners = {};
+        for (const [name, cfg] of Object.entries(planners)) {
+          if (failedSet.has(name)) scopedPlanners[name] = cfg;
+        }
+        const retryCount = Object.keys(scopedPlanners).length;
+        if (retryCount > 0) {
+          orchestrator.active.state.plannerFailureAutoRetried = true;
+          saveTask(orchestrator.active.dir, orchestrator.active.state);
+          orchestrator.failedPlannerVariants = [];
+          orchestrator.pendingSubagentSpawns = retryCount;
+          handleSpawnResult(
+            orchestrator,
+            spawnPlanners(
+              pi,
+              orchestrator.cwd,
+              orchestrator.active!.dir,
+              orchestrator.active!.taskId,
+              orchestrator.config,
+              orchestrator.transitionController.phaseSend,
+              scopedPlanners,
+              orchestrator.active?.state.repos ?? [],
+            ),
+            {
+              kind: "planner",
+              logScope: "planner",
+              logMessage: "retry spawnPlanners failed",
+              onSettled: checkPlannerCompletion,
+            },
+          );
+          orchestrator.safeSendUserMessage(`[PI-PI] Retrying failed planners once: ${failedPlannerVariants.join(", ")}.`);
+          return;
+        }
+      }
+
+      orchestrator.failedPlannerVariants = [];
+      orchestrator.active.state.plannerFailureAutoRetried = false;
+      saveTask(orchestrator.active.dir, orchestrator.active.state);
+      if (!hasPlanFiles) {
+        // Custom (sendMessage) followUp does NOT start a turn when the agent is
+        // idle (SDK agent-session.js) — emit the payload as display context and
+        // start the synthesizer turn via safeSendUserMessage (sendUserMessage
+        // always triggers a turn).
+        orchestrator.transitionController.sendCustom(
+          {
+            customType: "pp-planners-error",
+            content: "All planner subagents failed. Continue without planner outputs and synthesize the plan yourself.",
+            display: true,
+          },
+          "context",
+        );
+        orchestrator.safeSendUserMessage("[PI-PI] All planners failed. Synthesize the plan yourself based on USER_REQUEST.md and RESEARCH.md.");
+      } else {
+        orchestrator.safeSendUserMessage("[PI-PI] Some planners failed. Continue with available planner outputs.");
+      }
+      orchestrator.active.state.step = "synthesize";
+      saveTask(orchestrator.active.dir, orchestrator.active.state);
+      return;
+    }
+
     if (
       failedPlannerVariants.length > 0 &&
+      effectiveMode !== "autonomous" &&
       !orchestrator.plannerFailureDialogPending &&
       orchestrator.lastCtx
     ) {
@@ -572,28 +1299,35 @@ export function registerEventHandlers(orchestrator: Orchestrator): void {
 
           if (choice === "Retry failed planners") {
             const failedSet = new Set(failedPlannerVariants);
-            const planners: typeof orchestrator.config.planners = {};
-            for (const [name, cfg] of Object.entries(orchestrator.config.planners)) {
-              if (failedSet.has(name)) planners[name] = cfg;
+            const presetName = normalizeStoredPlannerPresetName(orchestrator);
+            const planners = resolvePreset(orchestrator.config, "planners", presetName);
+            const scopedPlanners: typeof planners = {};
+            for (const [name, cfg] of Object.entries(planners)) {
+              if (failedSet.has(name)) scopedPlanners[name] = cfg;
             }
-            const retryCount = Object.keys(planners).length;
+            const retryCount = Object.keys(scopedPlanners).length;
             if (retryCount > 0) {
-              const retryConfig = { ...orchestrator.config, planners };
               orchestrator.failedPlannerVariants = [];
               orchestrator.pendingSubagentSpawns = retryCount;
-              spawnPlanners(pi, orchestrator.cwd, orchestrator.active!.dir, orchestrator.active!.taskId, retryConfig).then((result) => {
-                orchestrator.failedPlannerVariants = result.failedVariants;
-                if (result.spawned === 0) orchestrator.pendingSubagentSpawns = 0;
-                for (const id of result.agentIds ?? []) {
-                  orchestrator.spawnedAgentIds.delete(id);
-                }
-                orchestrator.pendingSubagentSpawns = 0;
-                checkPlannerCompletion();
-              }).catch((err) => {
-                orchestrator.pendingSubagentSpawns = 0;
-                console.error(`[pi-pi] retry spawnPlanners failed: ${err.message}`);
-                checkPlannerCompletion();
-              });
+              handleSpawnResult(
+                orchestrator,
+                spawnPlanners(
+                  pi,
+                  orchestrator.cwd,
+                  orchestrator.active!.dir,
+                  orchestrator.active!.taskId,
+                  orchestrator.config,
+                  orchestrator.transitionController.phaseSend,
+                  scopedPlanners,
+                  orchestrator.active?.state.repos ?? [],
+                ),
+                {
+                  kind: "planner",
+                  logScope: "planner",
+                  logMessage: "retry spawnPlanners failed",
+                  onSettled: checkPlannerCompletion,
+                },
+              );
               orchestrator.safeSendUserMessage(`[PI-PI] Retrying failed planners: ${variantsText}.`);
               return;
             }
@@ -616,20 +1350,26 @@ export function registerEventHandlers(orchestrator: Orchestrator): void {
     }
 
     if (!hasPlanFiles) {
-      pi.sendMessage(
+      // Display payload as context; start the synthesizer turn via safeSendUserMessage
+      // (a custom followUp message does not start an idle turn).
+      orchestrator.transitionController.sendCustom(
         {
           customType: "pp-planners-error",
           content: "All planner subagents finished but no plan files were produced. You must create the plan yourself based on USER_REQUEST.md and RESEARCH.md.",
           display: true,
         },
-        { deliverAs: "followUp" },
+        "context",
       );
       orchestrator.active.state.step = "synthesize";
       saveTask(orchestrator.active.dir, orchestrator.active.state);
+      orchestrator.safeSendUserMessage("[PI-PI] No plan files were produced. Create the plan yourself based on USER_REQUEST.md and RESEARCH.md.");
       return;
     }
 
     orchestrator.failedPlannerVariants = [];
+    orchestrator.active.state.plannerFailureAutoRetried = false;
+    saveTask(orchestrator.active.dir, orchestrator.active.state);
+    markAllAgentsConsumed();
     orchestrator.active.state.step = "synthesize";
     saveTask(orchestrator.active.dir, orchestrator.active.state);
     orchestrator.safeSendUserMessage("[PI-PI] All planners completed. Read their outputs and synthesize the plan.");
@@ -641,12 +1381,95 @@ export function registerEventHandlers(orchestrator: Orchestrator): void {
       orchestrator.active.state.reviewCycle.step !== "await_reviewers" ||
       orchestrator.spawnedAgentIds.size > 0 ||
       orchestrator.pendingSubagentSpawns > 0 ||
-      orchestrator.phaseCompactionPending
+      orchestrator.transitionController.isTransitioning()
     ) return;
 
     const failedReviewerVariants = [...orchestrator.failedReviewerVariants];
+    const effectiveMode = getEffectiveMode(orchestrator.active.state);
+    if (effectiveMode === "autonomous" && failedReviewerVariants.length > 0) {
+      const cycle = orchestrator.active.state.reviewCycle;
+      const phase = orchestrator.active.state.phase;
+      const outputs = loadPhaseReviewOutputs(orchestrator.active.dir, phase, cycle.pass);
+      const alreadyRetried = orchestrator.active.state.reviewerFailureAutoRetried === true;
+      if (!alreadyRetried) {
+        const presetName = normalizeStoredReviewPresetName(orchestrator, phase);
+        const sourceReviewers = resolveReviewers(orchestrator, phase, presetName);
+        const failedSet = new Set(failedReviewerVariants);
+        const scopedReviewers: typeof sourceReviewers = {};
+        for (const [name, cfg] of Object.entries(sourceReviewers)) {
+          if (failedSet.has(name)) scopedReviewers[name] = cfg;
+        }
+        const retryCount = Object.keys(scopedReviewers).length;
+        if (retryCount > 0) {
+          const spawnFn = phase === "brainstorm"
+            ? () => spawnBrainstormReviewers(
+              pi,
+              orchestrator.cwd,
+              orchestrator.active!.dir,
+              orchestrator.active!.taskId,
+              orchestrator.config,
+              cycle.pass,
+              orchestrator.transitionController.phaseSend,
+              scopedReviewers,
+              orchestrator.active?.state.repos ?? [],
+            )
+            : phase === "plan"
+            ? () => spawnPlanReviewers(
+              pi,
+              orchestrator.cwd,
+              orchestrator.active!.dir,
+              orchestrator.active!.taskId,
+              orchestrator.config,
+              cycle.pass,
+              orchestrator.transitionController.phaseSend,
+              scopedReviewers,
+              orchestrator.active?.state.repos ?? [],
+            )
+            : () => spawnCodeReviewers(
+              pi,
+              orchestrator.cwd,
+              orchestrator.active!.dir,
+              orchestrator.active!.taskId,
+              orchestrator.config,
+              cycle.pass,
+              phase,
+              orchestrator.transitionController.phaseSend,
+              scopedReviewers,
+              orchestrator.active?.state.repos ?? [],
+            );
+          orchestrator.active.state.reviewerFailureAutoRetried = true;
+          saveTask(orchestrator.active.dir, orchestrator.active.state);
+          orchestrator.failedReviewerVariants = [];
+          orchestrator.pendingSubagentSpawns = retryCount;
+          cycle.step = "await_reviewers";
+          orchestrator.active.state.step = "await_reviewers";
+          saveTask(orchestrator.active.dir, orchestrator.active.state);
+          handleSpawnResult(orchestrator, spawnFn(), {
+            kind: "reviewer",
+            logScope: "review",
+            logMessage: "retry spawn reviewers failed",
+            logExtra: { phase },
+            onSettled: checkReviewCycleCompletion,
+          });
+          orchestrator.safeSendUserMessage(`[PI-PI] Retrying failed reviewers once: ${failedReviewerVariants.join(", ")}.`);
+          return;
+        }
+      }
+
+      orchestrator.failedReviewerVariants = [];
+      orchestrator.active.state.reviewerFailureAutoRetried = false;
+      saveTask(orchestrator.active.dir, orchestrator.active.state);
+      if (outputs.length === 0) {
+        finalizeReviewCycleAutonomous(orchestrator.active);
+        orchestrator.safeSendUserMessage("[PI-PI] All reviewers failed twice. Continue without reviewer outputs and proceed with best judgment.");
+        return;
+      }
+      orchestrator.safeSendUserMessage("[PI-PI] Some reviewers failed. Continue with available reviewer outputs.");
+    }
+
     if (
       failedReviewerVariants.length > 0 &&
+      effectiveMode !== "autonomous" &&
       !orchestrator.reviewerFailureDialogPending &&
       orchestrator.lastCtx
     ) {
@@ -664,13 +1487,9 @@ export function registerEventHandlers(orchestrator: Orchestrator): void {
             const cycle = orchestrator.active?.state.reviewCycle;
             if (cycle) {
               const pass = cycle.pass;
-              const reviewConfig = cycle.kind === "auto-deep" ? deepReviewConfig(orchestrator.config) : orchestrator.config;
               const phase = orchestrator.active!.state.phase;
-              const sourceReviewers = phase === "brainstorm"
-                ? reviewConfig.brainstormReviewers
-                : phase === "plan"
-                ? reviewConfig.planReviewers
-                : reviewConfig.codeReviewers;
+              const presetName = normalizeStoredReviewPresetName(orchestrator, phase);
+              const sourceReviewers = resolveReviewers(orchestrator, phase, presetName);
               const failedSet = new Set(failedReviewerVariants);
               const scopedReviewers: typeof sourceReviewers = {};
               for (const [name, cfg] of Object.entries(sourceReviewers)) {
@@ -678,33 +1497,53 @@ export function registerEventHandlers(orchestrator: Orchestrator): void {
               }
               const retryCount = Object.keys(scopedReviewers).length;
               if (retryCount > 0) {
-                const retryConfig = phase === "brainstorm"
-                  ? { ...reviewConfig, brainstormReviewers: scopedReviewers }
-                  : phase === "plan"
-                  ? { ...reviewConfig, planReviewers: scopedReviewers }
-                  : { ...reviewConfig, codeReviewers: scopedReviewers };
                 const spawnFn = phase === "brainstorm"
-                  ? () => spawnBrainstormReviewers(pi, orchestrator.cwd, orchestrator.active!.dir, orchestrator.active!.taskId, retryConfig, pass)
+                  ? () => spawnBrainstormReviewers(
+                    pi,
+                    orchestrator.cwd,
+                    orchestrator.active!.dir,
+                    orchestrator.active!.taskId,
+                    orchestrator.config,
+                    pass,
+                    orchestrator.transitionController.phaseSend,
+                    scopedReviewers,
+                    orchestrator.active?.state.repos ?? [],
+                  )
                   : phase === "plan"
-                  ? () => spawnPlanReviewers(pi, orchestrator.cwd, orchestrator.active!.dir, orchestrator.active!.taskId, retryConfig)
-                  : () => spawnCodeReviewers(pi, orchestrator.cwd, orchestrator.active!.dir, orchestrator.active!.taskId, retryConfig, pass);
+                  ? () => spawnPlanReviewers(
+                    pi,
+                    orchestrator.cwd,
+                    orchestrator.active!.dir,
+                    orchestrator.active!.taskId,
+                    orchestrator.config,
+                    pass,
+                    orchestrator.transitionController.phaseSend,
+                    scopedReviewers,
+                    orchestrator.active?.state.repos ?? [],
+                  )
+                  : () => spawnCodeReviewers(
+                    pi,
+                    orchestrator.cwd,
+                    orchestrator.active!.dir,
+                    orchestrator.active!.taskId,
+                    orchestrator.config,
+                    pass,
+                    phase,
+                    orchestrator.transitionController.phaseSend,
+                    scopedReviewers,
+                    orchestrator.active?.state.repos ?? [],
+                  );
                 orchestrator.failedReviewerVariants = [];
                 orchestrator.pendingSubagentSpawns = retryCount;
                 cycle.step = "await_reviewers";
                 orchestrator.active!.state.step = "await_reviewers";
                 saveTask(orchestrator.active!.dir, orchestrator.active!.state);
-                spawnFn().then((result) => {
-                  orchestrator.failedReviewerVariants = result.failedVariants;
-                  if (result.spawned === 0) orchestrator.pendingSubagentSpawns = 0;
-                  for (const id of result.agentIds ?? []) {
-                    orchestrator.spawnedAgentIds.delete(id);
-                  }
-                  orchestrator.pendingSubagentSpawns = 0;
-                  checkReviewCycleCompletion();
-                }).catch((err) => {
-                  orchestrator.pendingSubagentSpawns = 0;
-                  console.error(`[pi-pi] retry spawn reviewers failed (${phase}): ${err.message}`);
-                  checkReviewCycleCompletion();
+                handleSpawnResult(orchestrator, spawnFn(), {
+                  kind: "reviewer",
+                  logScope: "review",
+                  logMessage: "retry spawn reviewers failed",
+                  logExtra: { phase },
+                  onSettled: checkReviewCycleCompletion,
                 });
                 orchestrator.safeSendUserMessage(`[PI-PI] Retrying failed reviewers: ${variantsText}.`);
                 return;
@@ -736,6 +1575,11 @@ export function registerEventHandlers(orchestrator: Orchestrator): void {
       return;
     }
 
+    if (orchestrator.active.state.reviewerFailureAutoRetried) {
+      orchestrator.active.state.reviewerFailureAutoRetried = false;
+      saveTask(orchestrator.active.dir, orchestrator.active.state);
+    }
+    markAllAgentsConsumed();
     tryCompleteReviewCycle(orchestrator);
   }
 
@@ -764,13 +1608,13 @@ export function registerEventHandlers(orchestrator: Orchestrator): void {
     const tokens = data.tokens?.total ? `${data.tokens.total} tok` : "";
     const stats = [duration, tokens].filter(Boolean).join(", ");
 
-    pi.sendMessage(
+    orchestrator.transitionController.sendCustom(
       {
         customType: "pp-subagent-result",
         content: `${desc} completed${stats ? ` (${stats})` : ""}. Use get_subagent_result to read the output.`,
         display: false,
       },
-      { deliverAs: "steer" },
+      "context",
     );
 
     checkPlannerCompletion();
@@ -797,7 +1641,7 @@ export function registerEventHandlers(orchestrator: Orchestrator): void {
       orchestrator.abortAllSubagents();
     }
 
-    pi.sendMessage(
+    orchestrator.transitionController.sendCustom(
       {
         customType: "pp-subagent-error",
         content: isApiError
@@ -805,7 +1649,7 @@ export function registerEventHandlers(orchestrator: Orchestrator): void {
           : `**${desc}** failed: ${data.error || "unknown error"}. Do NOT retry — continue with available information.`,
         display: true,
       },
-      { deliverAs: "steer" },
+      "context",
     );
 
     checkPlannerCompletion();
@@ -813,6 +1657,7 @@ export function registerEventHandlers(orchestrator: Orchestrator): void {
   });
 
   pi.on("session_before_switch" as any, async () => {
+    finalizeTracer();
     if (!orchestrator.active) return;
     cancelPendingPlannotatorWait(orchestrator);
     orchestrator.abortAllSubagents();
@@ -828,14 +1673,47 @@ export function registerEventHandlers(orchestrator: Orchestrator): void {
     try {
       dumpUsageSummary(tracker, sessionId);
     } catch (err: any) {
-      console.error(`[pi-pi] Failed to dump usage summary: ${err.message}`);
+      getLogger().error({ s: "usage", err: err.message }, "failed to dump usage summary");
     }
+    flushLogs();
+    finalizeTracer();
     delete (globalThis as any)[USAGE_TRACKER_KEY];
   });
 
   pi.on("session_start", async (_event, ctx) => {
     orchestrator.lastCtx = ctx;
     orchestrator.cwd = ctx.cwd;
+    (globalThis as any)[Symbol.for("pi-pi:orchestrator-cwd")] = ctx.cwd;
+
+    const ppDir = join(ctx.cwd, ".pp");
+    const { ensureGitignore } = await import("./orchestrator.js");
+    ensureGitignore(ctx.cwd);
+
+    let earlyLogLevel: "debug" | "info" | "warn" | "error" = "info";
+    try {
+      const { readRawConfig, GLOBAL_CONFIG_PATH } = await import("./config.js");
+      const { isValidLogLevel: checkLevel } = await import("./log.js");
+      const globalRaw = readRawConfig(GLOBAL_CONFIG_PATH);
+      const projectRaw = readRawConfig(join(ppDir, "config.json"));
+      const rawLevel = projectRaw?.general?.logLevel ?? globalRaw?.general?.logLevel;
+      if (checkLevel(rawLevel)) earlyLogLevel = rawLevel;
+    } catch {}
+
+    initSessionLogger(ppDir, earlyLogLevel);
+    const log = getLogger();
+    log.info({ s: "session", cwd: ctx.cwd, logLevel: earlyLogLevel }, "session started");
+
+    const available = (ctx as any).modelRegistry?.getAvailable?.();
+    if (Array.isArray(available)) {
+      const modelIds = available
+        .map((m: any) => {
+          const provider = typeof m?.provider === "string" ? m.provider.trim() : "";
+          const id = typeof m?.id === "string" ? m.id.trim() : "";
+          return provider && id ? `${provider}/${id}` : "";
+        })
+        .filter((id: string) => id.length > 0);
+      updateRegistryFromAvailableModels(modelIds);
+    }
 
     if (!(globalThis as any)[SUBAGENT_SESSION_KEY]) {
       const tracker = createUsageTracker();
@@ -865,7 +1743,7 @@ export function registerEventHandlers(orchestrator: Orchestrator): void {
         `Duplicate tools detected: ${duplicates.join(", ")}. ` +
         `Remove the conflicting packages: pi remove npm:@tintinweb/pi-subagents npm:@tintinweb/pi-tasks npm:pi-ask-user`;
       ctx.ui.notify(msg, "error");
-      console.error(`[pi-pi] FATAL: ${msg}`);
+      getLogger().error({ s: "init", duplicates }, "conflicting extensions detected");
       return;
     }
 
@@ -874,16 +1752,28 @@ export function registerEventHandlers(orchestrator: Orchestrator): void {
       setPI(pi);
       await initFlantOnStartup(pi);
     } catch (err: any) {
-      console.error(`[pi-pi] Flant infra init failed: ${err.message}`);
+      getLogger().error({ s: "flant", err: err.message }, "flant infra init failed");
     }
 
     try {
       orchestrator.config = loadConfig(orchestrator.cwd);
     } catch (err: any) {
-      console.error(`[pi-pi] Failed to load config on session start: ${err.message}`);
+      getLogger().error({ s: "config", err: err.message }, "failed to load config on session start");
       return;
     }
 
+    setLogLevel(orchestrator.config.general.logLevel);
+    log.info({ s: "config", logLevel: orchestrator.config.general.logLevel }, "config loaded");
+
+    if (orchestrator.config.general.tracing) {
+      const sessionId = ctx.sessionManager?.getSessionId?.() || `session-${Date.now()}`;
+      initTracer(ppDir, sessionId);
+      log.info({ s: "tracing", sessionId }, "session tracing enabled");
+    } else {
+      finalizeTracer();
+    }
+
+    registerCommandHandlers(orchestrator);
     registerCbmTools(pi, orchestrator.cwd);
     registerExaTools(pi);
     registerAstSearchTool(pi, orchestrator.cwd);
@@ -891,7 +1781,7 @@ export function registerEventHandlers(orchestrator: Orchestrator): void {
     setExtensionOnlyMode(pi);
     orchestrator.registerAgents();
 
-    const found = getActiveTask(orchestrator.cwd, orchestrator.config.timeouts.lockStale);
+    const found = getActiveTask(orchestrator.cwd, orchestrator.config.performance.internals.taskLockStale);
     if (found) {
       ctx.ui.notify(
           `Paused task: "${taskName(found.dir)}" (${found.type}, phase: ${found.state.phase}). Run /pp and choose Resume to continue.`,
@@ -913,34 +1803,77 @@ export function registerEventHandlers(orchestrator: Orchestrator): void {
 
   pi.on("before_agent_start", async (event, ctx) => {
     orchestrator.lastCtx = ctx;
-    if (orchestrator.taskDoneCompactionPending || orchestrator.phaseCompactionPending) {
-      ctx.abort();
+    // The controller owns the transition/await abort gate: it decides whether the
+    // agent loop may start (not running during a pending/compacting/resuming
+    // transition, subsuming the old compaction-pending checks, or while awaiting
+    // subagents) AND issues the abort itself.
+    if (orchestrator.transitionController.gateAgentStart(() => ctx.abort())) {
       return;
     }
     if (!orchestrator.active || orchestrator.active.state.phase === "done") return;
 
-    const step = orchestrator.active.state.step;
-    if (step === "await_planners" || step === "await_reviewers") {
-      ctx.abort();
-      return;
+    // Clear the nudge guard ONLY on a genuine user re-engagement. Controller-
+    // injected prompts (nudges, "Begin working" handoffs, planner-error prompts)
+    // are all "[PI-PI]"-prefixed and themselves restart the loop via followUp;
+    // resetting on those would make consecutiveNudges oscillate 0->1->0 and the
+    // halt could never fire. A nudge-induced restart must NOT clear the guard.
+    const isControllerInjected = (event.prompt ?? "").startsWith("[PI-PI]");
+    if (!isControllerInjected) {
+      orchestrator.nudgeHalted = false;
+      orchestrator.consecutiveNudges = 0;
     }
-
-    orchestrator.nudgeHalted = false;
     orchestrator.updateStatus(ctx);
 
     const phasePrompt = orchestrator.getPhasePrompt(ctx);
-    const systemContextFiles = loadContextFiles(orchestrator.cwd, "main", "system");
+    const phase = orchestrator.active?.state.phase;
+    const modelSpec = ctx.model ? `${ctx.model.provider}/${ctx.model.id}` : "";
+    const modelInfo = getModelInfo(modelSpec);
+    const repos = orchestrator.active?.state.repos ?? [];
+    const contextDirs = getContextDirs(orchestrator.cwd, repos, orchestrator.config.general.loadExtraRepoConfigs);
+    const systemContextFiles = loadAllContextFiles(contextDirs, "main", "system", phase, modelInfo);
     const systemSnippets = systemContextFiles.map((f) => f.content).join("\n\n");
-
-    const fullAddition = [WORKING_PRINCIPLES, COMMUNICATION, systemSnippets, phasePrompt].filter(Boolean).join("\n\n");
-    if (!fullAddition) return;
+    const effectiveMode: TaskMode = getEffectivePhaseMode(orchestrator.active.state);
+    const now = new Date();
+    const monthYear = `${now.getFullYear()}-${String(now.getMonth() + 1).padStart(2, "0")}`;
+
+    const projectContext = systemSnippets
+      ? ["<project_context>", systemSnippets, "</project_context>"].join("\n")
+      : "";
+    const checklistLine =
+      phase === "implement" ? "Keep the plan checklist current: mark each item done (- [ ] → - [x]) as you complete it." : "";
+    const taskBlock = [
+      "<task>",
+      phasePrompt,
+      checklistLine,
+      `Current month: ${monthYear}. Working directory: ${orchestrator.cwd}.`,
+      "</task>",
+    ]
+      .filter(Boolean)
+      .join("\n");
+
+    const fullPrompt = [
+      constraintsBlock(phase as Phase, effectiveMode),
+      PRINCIPLES_BLOCK,
+      TOOLS_BLOCK,
+      projectContext,
+      taskBlock,
+    ]
+      .filter(Boolean)
+      .join("\n\n");
 
     return {
-      systemPrompt: event.systemPrompt + "\n\n" + fullAddition,
+      systemPrompt: fullPrompt,
     };
   });
 
   pi.on("tool_call", async (event, _ctx) => {
+    getLogger().debug({ s: "hook", hook: "tool_call", tool: event.toolName }, "tool call");
+    if (event.toolName === "ask_user" && orchestrator.active) {
+      if (getEffectivePhaseMode(orchestrator.active.state) === "autonomous") {
+        return { block: true, reason: "Autonomous mode — make your best judgment based on available context." };
+      }
+    }
+
     if (event.toolName === "Agent" && orchestrator.active) {
       const input = event.input as Record<string, unknown>;
       const requestedType = ((input.subagent_type as string) || "").toLowerCase();
@@ -952,16 +1885,16 @@ export function registerEventHandlers(orchestrator: Orchestrator): void {
 
       if (isExplore) {
         input.subagent_type = "explore";
-        input.model = orchestrator.config.agents.explore.model;
-        input.thinking = orchestrator.config.agents.explore.thinking;
+        input.model = resolveModel(orchestrator.config.agents.subagents.simple.explore.model);
+        input.thinking = orchestrator.config.agents.subagents.simple.explore.thinking;
       } else if (isLibrarian) {
         input.subagent_type = "librarian";
-        input.model = orchestrator.config.agents.librarian.model;
-        input.thinking = orchestrator.config.agents.librarian.thinking;
+        input.model = resolveModel(orchestrator.config.agents.subagents.simple.librarian.model);
+        input.thinking = orchestrator.config.agents.subagents.simple.librarian.thinking;
       } else {
         input.subagent_type = "task";
-        input.model = orchestrator.config.agents.task.model;
-        input.thinking = orchestrator.config.agents.task.thinking;
+        input.model = resolveModel(orchestrator.config.agents.subagents.simple.task.model);
+        input.thinking = orchestrator.config.agents.subagents.simple.task.thinking;
       }
     }
 
@@ -972,25 +1905,38 @@ export function registerEventHandlers(orchestrator: Orchestrator): void {
       const ppStateDir = resolve(orchestrator.cwd, ".pp", "state");
       const ppDir = resolve(orchestrator.cwd, ".pp");
 
-      if (resolvedPath.startsWith(ppStateDir + "/") || resolvedPath === ppStateDir) {
+      if (isPathInside(ppStateDir, resolvedPath)) {
         if (!resolvedPath.endsWith(".md")) {
           return { block: true, reason: "Cannot write non-.md files in .pp/state/" };
         }
       }
 
       const fileName = basename(resolvedPath);
-      if (fileName === "state.json" && (resolvedPath.startsWith(ppDir + "/") || resolvedPath === ppDir)) {
+      if (fileName === "state.json" && isPathInside(ppDir, resolvedPath)) {
         return { block: true, reason: "state.json is managed by the extension" };
       }
 
-      if (fileName === "config.json" && (resolvedPath.startsWith(ppDir + "/") || resolvedPath === ppDir)) {
+      if (fileName === "config.json" && isPathInside(ppDir, resolvedPath)) {
         return { block: true, reason: "config.json is managed by the user, not the LLM" };
       }
     }
     return;
   });
 
-  pi.on("tool_result", async (event, _ctx) => {
+  pi.on("tool_result", async (event, ctx) => {
+    // ESC in an ask_user dialogue must stop the LLM's turn (treat ESC as
+    // "stop, I want to type"). Only a deliberate user cancel aborts — timeout
+    // and programmatic signal-aborts carry a non-"user" reason and must not.
+    // The benign tool result has already been produced, so abort() yields a
+    // clean stop rather than an error in the agent loop.
+    if (event.toolName === "ask_user") {
+      const cancelReason = (event.details as { cancelReason?: string } | undefined)?.cancelReason;
+      if (cancelReason === "user") {
+        getLogger().debug({ s: "hook", hook: "tool_result", tool: "ask_user" }, "user cancelled ask_user — aborting turn");
+        ctx.abort?.();
+      }
+    }
+
     if (!orchestrator.active) return;
 
     if ((event.toolName === "edit" || event.toolName === "write") && !event.isError) {
@@ -1025,7 +1971,7 @@ export function registerEventHandlers(orchestrator: Orchestrator): void {
         }
       }
       const artifactsDir = join(taskDir, "artifacts");
-      if (resolvedWrite.startsWith(artifactsDir + "/") && resolvedWrite.endsWith(".md")) {
+      if (isPathInside(artifactsDir, resolvedWrite) && resolvedWrite.endsWith(".md")) {
         const content = readFileSync(resolvedWrite, "utf-8");
         const result = validateArtifact(content);
         if (!result.ok) {
@@ -1038,24 +1984,39 @@ export function registerEventHandlers(orchestrator: Orchestrator): void {
         }
       }
 
-      if (filePath.includes(".pp/")) return;
+      const ppDir = resolve(orchestrator.cwd, ".pp");
+      if (isPathInside(ppDir, resolvedWrite)) return;
 
       if (orchestrator.active.state.phase !== "implement") return;
 
-      orchestrator.active.modifiedFiles.add(filePath);
+      orchestrator.active.modifiedFiles.add(resolvedWrite);
       orchestrator.active.state.modifiedFiles = [...orchestrator.active.modifiedFiles];
-      if (!orchestrator.active.state.repoCwd) {
-        const dir = resolve(filePath, "..");
-        try {
-          const result = await pi.exec("git", ["rev-parse", "--show-toplevel"], { cwd: dir, timeout: 5000 });
-          if (result.code === 0 && result.stdout.trim()) {
-            orchestrator.active.state.repoCwd = result.stdout.trim();
-          }
-        } catch {}
-      }
+      orchestrator.active.state.reviewApprovedClean = false;
       try { saveTask(orchestrator.active.dir, orchestrator.active.state); } catch {}
 
-      const afterEditResults = runAfterEdit(filePath, orchestrator.config, orchestrator.cwd);
+      const repos = orchestrator.active.state.repos ?? [];
+      const repo = resolveRepoForFile(repos, resolvedWrite);
+      getLogger().debug({ s: "afterEdit", file: resolvedWrite, repo: repo?.path ?? null, isRoot: repo?.isRoot ?? null }, "resolving afterEdit commands");
+      const afterEditResults: Array<{ ok: boolean; command: string; output: string }> = [];
+      if (repo) {
+        if (repo.isRoot) {
+          const fileInRepo = relative(orchestrator.cwd, resolvedWrite);
+          afterEditResults.push(
+            ...runAfterEdit(
+              fileInRepo,
+              orchestrator.config.commands.afterEdit,
+              orchestrator.config.performance.commands.afterEdit,
+              orchestrator.cwd,
+            ),
+          );
+        } else if (orchestrator.config.general.loadExtraRepoConfigs) {
+          const repoCommands = loadRepoAfterEditCommands(repo.path);
+          if (repoCommands && Object.keys(repoCommands).length > 0) {
+            const fileInRepo = relative(repo.path, resolvedWrite);
+            afterEditResults.push(...runAfterEdit(fileInRepo, repoCommands, orchestrator.config.performance.commands.afterEdit, repo.path));
+          }
+        }
+      }
       const failures = afterEditResults.filter((r) => !r.ok);
 
       if (failures.length > 0) {
@@ -1084,10 +2045,13 @@ export function registerEventHandlers(orchestrator: Orchestrator): void {
   });
 
   pi.on("session_before_compact", async (event, _ctx) => {
-    if (orchestrator.taskDoneCompactionPending) {
-      const summary = orchestrator.taskDoneCompactionSummary;
-      orchestrator.taskDoneCompactionPending = false;
-      orchestrator.taskDoneCompactionSummary = "";
+    const transitioning = orchestrator.transitionController.isTransitioning();
+    getLogger().debug({ s: "hook", hook: "session_before_compact", transitioning, state: orchestrator.transitionController.getState() }, "before compact");
+    // Controller-initiated compaction (phase transition or task done/stop/new-task):
+    // supply the transition summary. The controller is the single source of truth,
+    // so this works whether or not `active` is still set (done cleanup nulls it).
+    if (transitioning) {
+      const summary = orchestrator.transitionController.currentSummary() || "Phase transition in progress.";
       return {
         compaction: {
           summary,
@@ -1097,20 +2061,10 @@ export function registerEventHandlers(orchestrator: Orchestrator): void {
       };
     }
 
+    // Natural (user-triggered) compaction: re-inject phase artifacts so context
+    // survives.
     if (!orchestrator.active || orchestrator.active.state.phase === "done") return;
 
-    if (orchestrator.phaseCompactionPending) {
-      const summary = orchestrator.phaseCompactionSummary || "Phase transition in progress.";
-      orchestrator.phaseCompactionSummary = "";
-      return {
-        compaction: {
-          summary,
-          firstKeptEntryId: event.preparation.firstKeptEntryId,
-          tokensBefore: event.preparation.tokensBefore,
-        },
-      };
-    }
-
     const artifacts = getPhaseArtifacts(orchestrator.active.dir, orchestrator.active.state.phase);
     if (artifacts.length === 0) return;
 
@@ -1118,13 +2072,13 @@ export function registerEventHandlers(orchestrator: Orchestrator): void {
       .map((a) => `=== ${a.name} ===\n${a.content}`)
       .join("\n\n");
 
-    pi.sendMessage(
+    orchestrator.transitionController.sendCustom(
       {
         customType: "pp-artifact-reinject",
         content: `[PI-PI ARTIFACTS — re-injected after compaction]\n\n${artifactText}`,
         display: false,
       },
-      { deliverAs: "steer" },
+      "context",
     );
 
     return;
@@ -1136,33 +2090,36 @@ export function registerEventHandlers(orchestrator: Orchestrator): void {
     if (usageTracker && msg?.usage) {
       const input = typeof msg.usage.input === "number" ? msg.usage.input : 0;
       const output = typeof msg.usage.output === "number" ? msg.usage.output : 0;
+      const cacheSupported = typeof msg.usage.cacheRead === "number" || typeof msg.usage.cacheWrite === "number";
       const cacheRead = typeof msg.usage.cacheRead === "number" ? msg.usage.cacheRead : 0;
       const cacheWrite = typeof msg.usage.cacheWrite === "number" ? msg.usage.cacheWrite : 0;
       const cost = typeof msg.usage.cost?.total === "number" ? msg.usage.cost.total : 0;
       const modelId = (typeof msg.model === "string" && msg.model) || ctx.model?.id || "unknown-model";
       const provider = (typeof msg.provider === "string" && msg.provider) || ctx.model?.provider || "unknown";
-      usageTracker.recordTurn(modelId, provider, input, output, cacheRead, cacheWrite, cost);
+      usageTracker.recordTurn(modelId, provider, input, output, cacheRead, cacheWrite, cost, cacheSupported);
       (ctx.ui as any)?.requestRender?.();
     }
 
     if (!orchestrator.active || orchestrator.active.state.phase === "done") return;
-    if (orchestrator.phaseCompactionPending || orchestrator.taskDoneCompactionPending) return;
+    // A transition is in flight (controller owns the loop) — skip orthogonal
+    // turn_end work (commit reminder / nudges) until it resumes.
+    if (orchestrator.transitionController.isTransitioning()) return;
     orchestrator.updateStatus(ctx);
 
     if (
       orchestrator.active.state.phase === "implement" &&
-      orchestrator.config.autoCommit &&
+      orchestrator.config.general.autoCommit &&
       orchestrator.active.modifiedFiles.size > 0 &&
       !orchestrator.commitReminderSent
     ) {
       orchestrator.commitReminderSent = true;
-      pi.sendMessage(
+      orchestrator.transitionController.sendCustom(
         {
           customType: "pp-commit-reminder",
-          content: `You have ${orchestrator.active.modifiedFiles.size} uncommitted file(s). If you've completed a logical unit of work, call pp_commit with a descriptive message.`,
+          content: `You have ${orchestrator.active.modifiedFiles.size} uncommitted file(s). If you've completed a logical unit of work, call pp_commit with a descriptive message. Prefix it with a conventional-commit type (fix:, feat:, or chore:) unless the user asked for a different commit style.`,
           display: false,
         },
-        { deliverAs: "steer" },
+        "context",
       );
     }
 
@@ -1171,20 +2128,29 @@ export function registerEventHandlers(orchestrator: Orchestrator): void {
     if (msg?.stopReason === "aborted") return;
     if (msg?.stopReason === "error") {
       const errorMsg = msg.errorMessage || "unknown error";
-      console.error(`[pi-pi] Turn ended with error: ${errorMsg}`);
-      console.error(`[pi-pi]   model=${msg.model} provider=${msg.provider} api=${msg.api}`);
-      console.error(`[pi-pi]   usage: input=${msg.usage?.input} output=${msg.usage?.output} cache_read=${msg.usage?.cacheRead}`);
-      console.error(`[pi-pi]   content blocks: ${msg.content?.length ?? 0}`);
-      for (const c of msg.content || []) {
-        if (c.type === "toolCall") console.error(`[pi-pi]   toolCall: ${c.name}`);
-        if (c.type === "text" && c.text) console.error(`[pi-pi]   text: ${c.text.slice(0, 100)}`);
-        if (c.type === "thinking") console.error(`[pi-pi]   thinking: ${c.thinking?.slice(0, 100) || "(redacted)"}`);
-      }
+      const contentSummary = (msg.content || []).map((c: any) => {
+        if (c.type === "toolCall") return `toolCall:${c.name}`;
+        if (c.type === "text" && c.text) return `text:${c.text.slice(0, 100)}`;
+        if (c.type === "thinking") return `thinking:${c.thinking?.slice(0, 100) || "(redacted)"}`;
+        return c.type;
+      });
+      getLogger().error({
+        s: "turn",
+        err: errorMsg,
+        model: msg.model,
+        provider: msg.provider,
+        api: msg.api,
+        input: msg.usage?.input,
+        output: msg.usage?.output,
+        cacheRead: msg.usage?.cacheRead,
+        contentBlocks: msg.content?.length ?? 0,
+        contentSummary,
+      }, "turn ended with error");
       orchestrator.errorRetryCount = (orchestrator.errorRetryCount ?? 0) + 1;
-      const retryDelays = [2000, 6000, 24000];
-      if (orchestrator.errorRetryCount <= retryDelays.length) {
-        const delay = retryDelays[orchestrator.errorRetryCount - 1];
-        ctx.ui.notify(`API error (attempt ${orchestrator.errorRetryCount}/${retryDelays.length}): ${errorMsg}. Retrying in ${delay / 1000}s...`, "warning");
+      const maxRetries = 5;
+      if (orchestrator.errorRetryCount <= maxRetries) {
+        const delay = 2000 * Math.pow(2, orchestrator.errorRetryCount - 1);
+        ctx.ui.notify(`API error (attempt ${orchestrator.errorRetryCount}/${maxRetries}): ${errorMsg}. Retrying in ${delay / 1000}s...`, "warning");
         const taskToken = orchestrator.activeTaskToken;
         if (orchestrator.pendingRetryTimer) clearTimeout(orchestrator.pendingRetryTimer);
         orchestrator.pendingRetryTimer = setTimeout(() => {
@@ -1193,7 +2159,7 @@ export function registerEventHandlers(orchestrator: Orchestrator): void {
           orchestrator.safeSendUserMessage(`[PI-PI] Previous request failed due to an API error. Continue working on the current phase (${phase}).`);
         }, delay);
       } else {
-        ctx.ui.notify(`API error persisted after 3 retries: ${errorMsg}. Stopping auto-retry.`, "error");
+        ctx.ui.notify(`API error persisted after ${maxRetries} retries: ${errorMsg}. Stopping auto-retry.`, "error");
         orchestrator.errorRetryCount = 0;
       }
       return;
@@ -1204,76 +2170,14 @@ export function registerEventHandlers(orchestrator: Orchestrator): void {
       return;
     }
 
+    // While awaiting subagents, completion is driven entirely by the event-driven
+    // owners (checkPlannerCompletion / checkReviewCycleCompletion / tryCompleteReviewCycle,
+    // wired to subagents:completed/failed and the blocking spawn promise's onSettled).
+    // The old 5s setInterval poller was a redundant fallback and has been removed;
+    // turn_end simply returns here (no nudge, no poll) while in an await_* step.
     if (orchestrator.active.state.step === "await_planners" || orchestrator.active.state.step === "await_reviewers") {
-      if (!orchestrator.awaitPollTimer) {
-        orchestrator.awaitPollTimer = setInterval(() => {
-          if (!orchestrator.active) {
-            clearInterval(orchestrator.awaitPollTimer!);
-            orchestrator.awaitPollTimer = null;
-            return;
-          }
-          if (orchestrator.phaseCompactionPending) return;
-          const taskDir = orchestrator.active.dir;
-          if (orchestrator.active.state.step === "await_planners") {
-            const plansDir = join(taskDir, "plans");
-            const plannerCount = Object.values(orchestrator.config.planners).filter((v) => v.enabled).length;
-            if (existsSync(plansDir)) {
-              const planFiles = readdirSync(plansDir).filter((f) => f.endsWith(".md") && !f.includes("synthesized") && !f.includes("review_"));
-              if (planFiles.length >= plannerCount) {
-                clearInterval(orchestrator.awaitPollTimer!);
-                orchestrator.awaitPollTimer = null;
-                orchestrator.spawnedAgentIds.clear();
-                orchestrator.pendingSubagentSpawns = 0;
-                orchestrator.active.state.step = "synthesize";
-                saveTask(orchestrator.active.dir, orchestrator.active.state);
-                orchestrator.safeSendUserMessage("[PI-PI] All planners completed. Read their outputs and synthesize the plan.");
-              }
-            }
-          } else if (orchestrator.active.state.step === "await_reviewers" && orchestrator.active.state.reviewCycle) {
-            const cycle = orchestrator.active.state.reviewCycle;
-            const reviewConfig = cycle.kind === "auto-deep" ? deepReviewConfig(orchestrator.config) : orchestrator.config;
-            const phase = orchestrator.active.state.phase;
-            const reviewers = phase === "brainstorm"
-              ? reviewConfig.brainstormReviewers
-              : phase === "plan"
-              ? reviewConfig.planReviewers
-              : reviewConfig.codeReviewers;
-            const reviewerCount = Object.values(reviewers).filter((v) => v.enabled).length;
-            const outputs = loadPhaseReviewOutputs(taskDir, phase, cycle.pass);
-            if (outputs.length >= reviewerCount) {
-              clearInterval(orchestrator.awaitPollTimer!);
-              orchestrator.awaitPollTimer = null;
-              orchestrator.spawnedAgentIds.clear();
-              orchestrator.pendingSubagentSpawns = 0;
-
-              if (orchestrator.reviewTransitionToken === orchestrator.activeTaskToken) return;
-              orchestrator.reviewTransitionToken = orchestrator.activeTaskToken;
-
-              cycle.step = "apply_feedback";
-              orchestrator.active.state.step = "apply_feedback";
-              saveTask(orchestrator.active.dir, orchestrator.active.state);
-              const rendered = outputs.map((o) => `=== ${o.name} ===\n${o.content}`).join("\n\n");
-              pi.sendMessage(
-                { customType: "pp-review-ready", content: `[PI-PI] Reviewer outputs are ready.\n\n${rendered}`, display: false },
-                { deliverAs: "followUp" },
-              );
-              orchestrator.safeSendUserMessage("[PI-PI] Review cycle is ready for apply_feedback. Read reviewer outputs and proceed.");
-            }
-          } else {
-            clearInterval(orchestrator.awaitPollTimer!);
-            orchestrator.awaitPollTimer = null;
-          }
-        }, 5000);
-      }
       return;
     }
-    if (orchestrator.awaitPollTimer) {
-      clearInterval(orchestrator.awaitPollTimer);
-      orchestrator.awaitPollTimer = null;
-    }
-
-    if (orchestrator.active.type === "brainstorm" && phase === "brainstorm") return;
-    if (orchestrator.active.type === "review" && phase === "review") return;
 
     const contentParts = Array.isArray(msg?.content) ? msg.content : [];
     const hasText = contentParts.some((c: any) => c.type === "text" && c.text?.trim());
@@ -1281,78 +2185,51 @@ export function registerEventHandlers(orchestrator: Orchestrator): void {
     const hasToolResults = event.toolResults && event.toolResults.length > 0;
     const turnWasEmpty = !hasText && !hasToolCalls && !hasToolResults;
 
-    if (!turnWasEmpty) {
-      const lastPart = contentParts.length > 0 ? contentParts[contentParts.length - 1] : null;
-      const endsWithText = lastPart?.type === "text" && lastPart?.text?.trim();
-      if (hasText && (!hasToolCalls || endsWithText)) {
-        const step = orchestrator.active.state.step;
-        if (step !== "await_planners" && step !== "await_reviewers" && !orchestrator.textStopReminderSent) {
-          orchestrator.textStopReminderSent = true;
-          orchestrator.safeSendUserMessage(`[PI-PI] You stopped without calling pp_phase_complete. If you are done with the ${phase} phase, call pp_phase_complete now. If not, continue working.`);
-        }
-      } else {
-        orchestrator.textStopReminderSent = false;
-      }
-      return;
-    }
-    orchestrator.textStopReminderSent = false;
-    if (orchestrator.nudgeHalted) return;
-    if (orchestrator.spawnedAgentIds.size > 0 || orchestrator.pendingSubagentSpawns > 0) return;
-
-    const step = orchestrator.active.state.step;
-    if (step === "await_planners" || step === "await_reviewers") return;
+    const isAutonomous = getEffectivePhaseMode(orchestrator.active.state) === "autonomous";
 
-    const now = Date.now();
+    // Nudges fire ONLY for plan/implement. brainstorm/debug/review (and quick) are
+    // interactive by nature — stopping there is normal, not a stall. They are also
+    // suppressed whenever the controller is not running (a transition handoff or
+    // await is in progress — that pause is plumbing, not a genuine model stop).
+    const nudgesEnabled = (phase === "plan" || phase === "implement") && orchestrator.transitionController.isRunning();
 
-    orchestrator.nudgeTimestamps.push(now);
-    orchestrator.nudgeTimestamps = orchestrator.nudgeTimestamps.filter((t) => now - t < 60000);
+    // A genuine model stop is a turn that produced no forward progress: either a
+    // text-only reply (no tool call, or one that trails into text) or a fully
+    // empty turn. A turn that ended on a tool call IS progress and resets the guard.
+    const lastPart = contentParts.length > 0 ? contentParts[contentParts.length - 1] : null;
+    const endsWithText = lastPart?.type === "text" && !!lastPart?.text?.trim();
+    const isGenuineStop = turnWasEmpty || (hasText && (!hasToolCalls || endsWithText));
 
-    const sendNudge = () => {
-      orchestrator.safeSendUserMessage(`[PI-PI] Your previous response was interrupted. Continue working on the current phase (${phase}). Pick up where you left off.`);
-    };
-
-    if (orchestrator.nudgeTimestamps.length <= 3) {
-      sendNudge();
+    if (!isGenuineStop) {
+      // Forward progress — clear the consecutive-nudge guard.
+      orchestrator.consecutiveNudges = 0;
       return;
     }
 
-    if (orchestrator.nudgeTimestamps.length >= 5) {
-      orchestrator.cooldownHits.push(now);
-      orchestrator.cooldownHits = orchestrator.cooldownHits.filter((t) => now - t < 20 * 60 * 1000);
-
-      if (orchestrator.cooldownHits.length >= 5) {
-        orchestrator.nudgeHalted = true;
-        orchestrator.nudgeTimestamps = [];
-        orchestrator.cooldownHits = [];
-        pi.sendMessage(
-          {
-            customType: "pp-continuation-halted",
-            content: "Agent has been repeatedly interrupted. Auto-continuation paused. Send any message to resume nudging.",
-            display: true,
-          },
-          { deliverAs: "steer" },
-        );
-        return;
-      }
+    if (!nudgesEnabled || orchestrator.nudgeHalted) return;
 
-      pi.sendMessage(
+    // Single consecutive-nudge guard: nudge up to MAX_CONSECUTIVE_NUDGES times in
+    // a row, then halt with one notification until the user re-engages (a fresh
+    // before_agent_start resets the counter).
+    const MAX_CONSECUTIVE_NUDGES = 6;
+    if (orchestrator.consecutiveNudges >= MAX_CONSECUTIVE_NUDGES) {
+      orchestrator.nudgeHalted = true;
+      orchestrator.transitionController.sendCustom(
         {
-          customType: "pp-continuation-cooldown",
-          content: "Agent interrupted repeatedly. Waiting 60 seconds before retrying.",
+          customType: "pp-continuation-halted",
+          content: "Agent has been repeatedly interrupted without making progress. Auto-continuation paused. Send any message to resume.",
           display: true,
         },
-        { deliverAs: "steer" },
+        "context",
       );
-      orchestrator.nudgeTimestamps = [];
-      const cooldownToken = orchestrator.activeTaskToken;
-      setTimeout(() => {
-        if (orchestrator.activeTaskToken !== cooldownToken || !orchestrator.active) return;
-        sendNudge();
-      }, 60000);
       return;
     }
 
-    sendNudge();
+    orchestrator.consecutiveNudges++;
+    const nudge = isAutonomous
+      ? `[PI-PI] Continue the ${phase} phase. ${phaseConstraint(phase as Phase)} If the phase's objectives are met, call pp_phase_complete now; otherwise call the next tool. Do NOT apologize or reply with text only — respond with a tool call.`
+      : `[PI-PI] Continue the ${phase} phase where you left off.`;
+    orchestrator.safeSendUserMessage(nudge);
   });