@ilya-lesikov/pi-pi 0.1.0

package/extensions/orchestrator/event-handlers.ts

@@ -0,0 +1,1416 @@
+import { existsSync, readdirSync, readFileSync } from "fs";
+import { resolve, basename, join } 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 {
+  loadContextFiles,
+  getPhaseArtifacts,
+  getLatestSynthesizedPlan,
+  loadBrainstormReviewOutputs,
+  loadCodeReviewOutputs,
+  loadPlanReviewOutputs,
+} from "./context.js";
+import { WORKING_PRINCIPLES, COMMUNICATION } from "./agents/tool-routing.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 { setExtensionOnlyMode, unregisterAgentDefinitions } from "./agents/registry.js";
+import { spawnPlanners, spawnPlanReviewers } from "./phases/planning.js";
+import { spawnCodeReviewers } from "./phases/review.js";
+import { spawnBrainstormReviewers } from "./phases/brainstorm.js";
+import { openPlannotator, waitForPlannotatorResult, cancelPendingPlannotatorWait } from "./plannotator.js";
+import { Orchestrator, deepReviewConfig, type ActiveTask } from "./orchestrator.js";
+import { askUser } from "../../3p/pi-ask-user/index.js";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+export async function detectDefaultBranch(pi: ExtensionAPI, cwd: string, config?: { diffBaseBranch?: string }): Promise<string> {
+  if (config?.diffBaseBranch) return config.diffBaseBranch;
+  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/", "");
+    }
+  } 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";
+  } 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";
+  } catch {}
+  return "main";
+}
+
+export async function detectRepoCwd(pi: ExtensionAPI, modifiedFiles: Set<string>, fallbackCwd: string): Promise<string> {
+  if (modifiedFiles.size === 0) return fallbackCwd;
+  const firstFile = [...modifiedFiles][0];
+  const dir = resolve(firstFile, "..");
+  try {
+    const result = await pi.exec("git", ["rev-parse", "--show-toplevel"], { cwd: dir, timeout: 5000 });
+    if (result.code === 0 && result.stdout.trim()) return result.stdout.trim();
+  } catch {}
+  return fallbackCwd;
+}
+
+export async function selectOption(ctx: any, question: string, options: string[]): Promise<string | undefined> {
+  const result = await askUser(ctx, {
+    question,
+    options,
+    allowFreeform: false,
+    allowComment: false,
+    allowMultiple: false,
+  });
+  if (!result || result.kind !== "selection") return undefined;
+  return result.selections[0];
+}
+
+function setStep(orchestrator: Orchestrator, step: string): void {
+  if (!orchestrator.active) return;
+  orchestrator.active.state.step = step;
+  saveTask(orchestrator.active.dir, orchestrator.active.state);
+}
+
+function tryCompleteReviewCycle(orchestrator: Orchestrator): void {
+  if (
+    !orchestrator.active?.state.reviewCycle ||
+    orchestrator.active.state.reviewCycle.step !== "await_reviewers" ||
+    orchestrator.spawnedAgentIds.size > 0 ||
+    orchestrator.pendingSubagentSpawns > 0
+  ) return;
+
+  if (orchestrator.reviewTransitionToken === orchestrator.activeTaskToken) return;
+
+  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;
+  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.";
+
+  pi.sendMessage(
+    {
+      customType: "pp-review-ready",
+      content: `[PI-PI] Reviewer outputs are ready.\n\n${rendered}`,
+      display: false,
+    },
+    { deliverAs: "followUp" },
+  );
+  pi.sendUserMessage("[PI-PI] Review cycle is ready for apply_feedback. Read reviewer outputs and proceed.", { deliverAs: "followUp" });
+}
+
+export async function enterReviewCycle(orchestrator: Orchestrator, ctx: any, kind: "auto" | "auto-deep" | "plannotator") {
+  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") {
+    const phase = orchestrator.active.state.phase;
+    if (phase === "brainstorm") {
+      orchestrator.active.state.reviewCycle = null;
+      saveTask(orchestrator.active.dir, orchestrator.active.state);
+      return "Plannotator is only available for plan and implement phases. Choose another option.";
+    }
+    if (phase === "plan") {
+      const planContent = getLatestSynthesizedPlan(orchestrator.active.dir);
+      if (!planContent) {
+        orchestrator.active.state.reviewCycle = null;
+        saveTask(orchestrator.active.dir, orchestrator.active.state);
+        return "No synthesized plan found. Choose another option.";
+      }
+      const payload = { planContent, planFilePath: join(orchestrator.active.dir, "plans") };
+
+      const { opened, reviewId } = await openPlannotator(pi, "plan-review", payload);
+      if (!opened) {
+        orchestrator.active.state.reviewCycle = null;
+        saveTask(orchestrator.active.dir, orchestrator.active.state);
+        return "Plannotator is not available. Choose another option.";
+      }
+
+      let result: { approved: boolean; feedback?: string };
+      ctx.ui?.setWorkingMessage?.("Waiting for Plannotator plan review…");
+      try {
+        result = await waitForPlannotatorResult(orchestrator, reviewId);
+      } catch {
+        orchestrator.active.state.reviewCycle = null;
+        saveTask(orchestrator.active.dir, orchestrator.active.state);
+        return "Plannotator review cancelled. Choose another option.";
+      } finally {
+        ctx.ui?.setWorkingMessage?.();
+      }
+      orchestrator.active.state.reviewCycle = null;
+      if (result.approved) {
+        orchestrator.active.state.reviewPass += 1;
+        orchestrator.active.reviewPass = orchestrator.active.state.reviewPass;
+        orchestrator.active.state.step = "user_gate";
+        saveTask(orchestrator.active.dir, orchestrator.active.state);
+        return "Plannotator approved the plan. Choose next action.";
+      }
+
+      orchestrator.active.state.step = "synthesize";
+      saveTask(orchestrator.active.dir, orchestrator.active.state);
+      const feedback = result.feedback ? `\n\nFeedback:\n${result.feedback}` : "";
+      return `Plannotator requested changes.${feedback}\n\nUser wants to continue. Run /pp when ready to advance.`;
+    }
+
+    orchestrator.active.state.reviewCycle = null;
+    orchestrator.active.state.step = "llm_work";
+    saveTask(orchestrator.active.dir, orchestrator.active.state);
+    return "User wants a Plannotator code review. Call pp_specify_reviews with the list of repositories and commit ranges to review. Include all repos where you made changes.";
+  }
+
+  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;
+  if (enabledCount === 0) {
+    orchestrator.active.state.reviewCycle = null;
+    saveTask(orchestrator.active.dir, orchestrator.active.state);
+    const label = phase === "brainstorm" ? "brainstorm" : phase === "plan" ? "plan" : "code";
+    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}`);
+  });
+
+  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.`;
+}
+
+export function stopTask(orchestrator: Orchestrator): string {
+  if (!orchestrator.active) return "No active task.";
+  orchestrator.abortAllSubagents();
+  orchestrator.active.state.phase = "done";
+  saveTask(orchestrator.active.dir, orchestrator.active.state);
+  const desc = orchestrator.active.description;
+  orchestrator.cleanupActive();
+  const taskStore = (globalThis as any)[Symbol.for("pi-tasks:store")];
+  taskStore?.clearAll?.();
+  return `Task "${desc}" stopped.`;
+}
+
+export function finalizeReviewCycle(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;
+  if (!task.state.reviewPassByKind) task.state.reviewPassByKind = {};
+  task.state.reviewPassByKind[kind] = (task.state.reviewPassByKind[kind] ?? 0) + 1;
+  task.state.reviewCycle = null;
+  task.state.step = "user_gate";
+  saveTask(task.dir, task.state);
+}
+
+export async function runUserGateDialog(orchestrator: Orchestrator, ctx: any, summary: string): Promise<string> {
+  if (!orchestrator.active) return "No active task.";
+  if (orchestrator.userGatePending) return "A user-gate dialog is already in progress.";
+  orchestrator.userGatePending = true;
+
+  try {
+    return await runUserGateDialogInner(orchestrator, ctx, summary);
+  } finally {
+    orchestrator.userGatePending = false;
+  }
+}
+
+async function runUserGateDialogInner(orchestrator: Orchestrator, ctx: any, summary: string): Promise<string> {
+  if (!orchestrator.active) return "No active task.";
+  const pi = orchestrator.pi;
+  const phase = orchestrator.active.state.phase;
+  const task = orchestrator.active;
+
+  if (orchestrator.spawnedAgentIds.size > 0 || orchestrator.pendingSubagentSpawns > 0) {
+    const count = orchestrator.spawnedAgentIds.size + orchestrator.pendingSubagentSpawns;
+    return `${count} subagent(s) still running or spawning.`;
+  }
+
+    const byKind = task.state.reviewPassByKind ?? {};
+    const autoCount = byKind["auto"] ?? 0;
+    const deepCount = byKind["auto-deep"] ?? 0;
+    const autoLabel = autoCount > 0 ? `Review (pass ${autoCount + 1})` : "Review";
+    const deepLabel = deepCount > 0 ? `Deep review (pass ${deepCount + 1})` : "Deep review";
+
+  const continueMessage = "User wants to continue. Run /pp when ready to advance.";
+
+  if (phase === "brainstorm" && task.type === "implement") {
+    const choice = await selectOption(ctx, summary, ["Approve brainstorm", autoLabel, deepLabel, "Continue brainstorming", "Stop task"]);
+    finalizeReviewCycle(task);
+    if (choice === "Approve brainstorm") {
+      const result = await orchestrator.transitionToNextPhase(ctx);
+      return result.ok ? "Brainstorm approved. Transitioned to plan." : `Transition blocked: ${result.error}`;
+    }
+    if (choice === autoLabel) return enterReviewCycle(orchestrator, ctx, "auto");
+    if (choice === deepLabel) return enterReviewCycle(orchestrator, ctx, "auto-deep");
+    if (choice === "Stop task") return stopTask(orchestrator);
+    setStep(orchestrator, "llm_work");
+    return continueMessage;
+  }
+
+  if (phase === "brainstorm" && task.type === "brainstorm") {
+    const choice = await selectOption(ctx, summary, ["Approve brainstorm", autoLabel, deepLabel, "Continue brainstorming", "Finish brainstorming", "Stop task"]);
+    finalizeReviewCycle(task);
+    if (choice === "Approve brainstorm") {
+      const result = await orchestrator.transitionToNextPhase(ctx);
+      return result.ok ? "Brainstorm approved. Transitioned to plan." : `Transition blocked: ${result.error}`;
+    }
+    if (choice === autoLabel) return enterReviewCycle(orchestrator, ctx, "auto");
+    if (choice === deepLabel) return enterReviewCycle(orchestrator, ctx, "auto-deep");
+    if (choice === "Finish brainstorming" || choice === "Stop task") return stopTask(orchestrator);
+    setStep(orchestrator, "llm_work");
+    return continueMessage;
+  }
+
+  if (phase === "debug") {
+    const choice = await selectOption(ctx, summary, ["Approve debug", autoLabel, deepLabel, "Continue debugging", "Finish debugging", "Stop task"]);
+    finalizeReviewCycle(task);
+    if (choice === "Approve debug") {
+      const result = await orchestrator.transitionToNextPhase(ctx);
+      return result.ok ? "Debug approved. Transitioned to plan." : `Transition blocked: ${result.error}`;
+    }
+    if (choice === autoLabel) return enterReviewCycle(orchestrator, ctx, "auto");
+    if (choice === deepLabel) return enterReviewCycle(orchestrator, ctx, "auto-deep");
+    if (choice === "Finish debugging" || choice === "Stop task") return stopTask(orchestrator);
+    setStep(orchestrator, "llm_work");
+    return continueMessage;
+  }
+
+  if (phase === "plan") {
+    const choice = await selectOption(ctx, summary, [
+      "Approve plan",
+      autoLabel,
+      deepLabel,
+      "Review in Plannotator",
+      "Review on my own",
+      "Continue planning",
+      "Stop task",
+    ]);
+    finalizeReviewCycle(task);
+    if (choice === "Approve plan") {
+      const result = await orchestrator.transitionToNextPhase(ctx);
+      return result.ok ? "Plan approved. Transitioned to implement." : `Transition blocked: ${result.error}`;
+    }
+    if (choice === autoLabel) return enterReviewCycle(orchestrator, ctx, "auto");
+    if (choice === deepLabel) return enterReviewCycle(orchestrator, ctx, "auto-deep");
+    if (choice === "Review in Plannotator") return enterReviewCycle(orchestrator, ctx, "plannotator");
+    if (choice === "Stop task") return stopTask(orchestrator);
+    setStep(orchestrator, "synthesize");
+    return continueMessage;
+  }
+
+  if (phase === "implement") {
+    const choice = await selectOption(ctx, summary, [
+      "Approve implementation",
+      autoLabel,
+      deepLabel,
+      "Review in Plannotator",
+      "Review on my own",
+      "Continue implementation",
+      "Stop task",
+    ]);
+    finalizeReviewCycle(task);
+    if (choice === "Approve implementation") {
+      const result = await orchestrator.transitionToNextPhase(ctx);
+      return result.ok ? "Implementation approved. Task completed." : `Transition blocked: ${result.error}`;
+    }
+    if (choice === autoLabel) return enterReviewCycle(orchestrator, ctx, "auto");
+    if (choice === deepLabel) return enterReviewCycle(orchestrator, ctx, "auto-deep");
+    if (choice === "Review in Plannotator") return enterReviewCycle(orchestrator, ctx, "plannotator");
+    if (choice === "Stop task") return stopTask(orchestrator);
+    setStep(orchestrator, "llm_work");
+    return continueMessage;
+  }
+
+  return "No dialog available for this phase.";
+}
+
+function registerOrchestratorTools(orchestrator: Orchestrator): void {
+  registerPhaseCompleteTool(orchestrator);
+  registerCommitTool(orchestrator);
+  registerSpecifyReviewsTool(orchestrator);
+}
+
+function openCodeReviewDirect(
+  pi: ExtensionAPI,
+  payload: Record<string, unknown>,
+): Promise<{ approved: boolean; feedback?: string } | { error: string }> {
+  return new Promise((resolve) => {
+    pi.events.emit("plannotator:request", {
+      requestId: crypto.randomUUID(),
+      action: "code-review",
+      payload,
+      respond: (response: any) => {
+        if (response.status === "handled") {
+          resolve({ approved: !!response.result?.approved, feedback: response.result?.feedback });
+        } else {
+          resolve({ error: response.error || "Plannotator not available" });
+        }
+      },
+    });
+  });
+}
+
+function registerSpecifyReviewsTool(orchestrator: Orchestrator): void {
+  const pi = orchestrator.pi;
+
+  pi.registerTool({
+    name: "pp_specify_reviews",
+    label: "pi-pi",
+    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.",
+    parameters: Type.Object({
+      reviews: Type.Array(Type.Object({
+        cwd: Type.String({ description: "Absolute path to the git repository" }),
+        range: Type.String({ description: "Git commit range, e.g. 'origin/main..HEAD', 'abc123..def456', 'HEAD~3..HEAD'" }),
+      })),
+    }),
+    async execute(_toolCallId, params: any, _signal, _onUpdate, ctx) {
+      if (!params.reviews || params.reviews.length === 0) {
+        return { content: [{ type: "text" as const, text: "No reviews specified." }], isError: true as const, details: {} };
+      }
+
+      const results: string[] = [];
+      let hasNeedsChanges = false;
+      for (const review of params.reviews) {
+        ctx.ui?.setWorkingMessage?.(`Waiting for Plannotator review: ${review.range}…`);
+        const result = await openCodeReviewDirect(pi, {
+          cwd: review.cwd,
+          diffType: `range:${review.range}`,
+        });
+        if ("error" in result) {
+          results.push(`${review.cwd} (${review.range}): ${result.error}`);
+        } else {
+          const status = result.approved ? "APPROVED" : "NEEDS_CHANGES";
+          if (!result.approved) hasNeedsChanges = true;
+          const feedback = result.feedback ? `\nFeedback: ${result.feedback}` : "";
+          results.push(`${review.cwd} (${review.range}): ${status}${feedback}`);
+        }
+      }
+      ctx.ui?.setWorkingMessage?.();
+
+      const summary = results.join("\n\n");
+
+      if (hasNeedsChanges) {
+        if (orchestrator.active) {
+          orchestrator.active.state.step = "llm_work";
+          saveTask(orchestrator.active.dir, orchestrator.active.state);
+        }
+        return {
+          content: [{ type: "text" as const, text: `Plannotator review complete.\n\n${summary}\n\nFix the issues noted above, then call pp_phase_complete when done.` }],
+          details: {},
+        };
+      }
+
+      ctx.ui?.setWorkingMessage?.("Waiting for user input…");
+      try {
+        const gateResult = await runUserGateDialog(orchestrator, ctx, `Plannotator review complete.\n\n${summary}`);
+        return { content: [{ type: "text" as const, text: gateResult }], details: {} };
+      } finally {
+        ctx.ui?.setWorkingMessage?.();
+      }
+    },
+  });
+}
+
+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);
+  return loadCodeReviewOutputs(taskDir, pass);
+}
+
+function registerCommitTool(orchestrator: Orchestrator): void {
+  const pi = orchestrator.pi;
+
+  pi.registerTool({
+    name: "pp_commit",
+    label: "pi-pi",
+    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.",
+    parameters: Type.Object({
+      message: Type.String({ description: "Commit message describing the change (max 72 chars for first line)" }),
+    }),
+    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) {
+        return { content: [{ type: "text" as const, text: "autoCommit is disabled in config." }], details: {} };
+      }
+      if (orchestrator.active.modifiedFiles.size === 0) {
+        return { content: [{ type: "text" as const, text: "No modified files to commit." }], details: {} };
+      }
+
+      const files = [...orchestrator.active.modifiedFiles];
+      const result = autoCommit(files, params.message, orchestrator.cwd);
+      if (result.ok) {
+        orchestrator.active.modifiedFiles.clear();
+        orchestrator.active.state.modifiedFiles = [];
+        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: {} };
+      }
+      return { content: [{ type: "text" as const, text: `Commit failed: ${result.error}` }], isError: true as const, details: {} };
+    },
+  });
+}
+
+function registerPhaseCompleteTool(orchestrator: Orchestrator): void {
+  const pi = orchestrator.pi;
+
+  pi.registerTool({
+    name: "pp_phase_complete",
+    label: "pi-pi",
+    description:
+      "Call when the current phase is complete. Shows a dialog to the user for " +
+      "approval. The user's choice is returned — act on it accordingly.",
+    parameters: Type.Object({
+      summary: Type.String({ description: "Brief summary of what was accomplished in this phase" }),
+    }),
+    async execute(_toolCallId, params: any, _signal, _onUpdate, ctx) {
+      if (!orchestrator.active) {
+        return { content: [{ type: "text" as const, text: "No active task." }], isError: true as const, details: {} };
+      }
+      const step = orchestrator.active.state.step;
+      if (step === "await_planners" || step === "await_reviewers") {
+        return { content: [{ type: "text" as const, text: "Subagents are still running. Wait for them to complete before calling pp_phase_complete." }], isError: true as const, details: {} };
+      }
+      if (orchestrator.spawnedAgentIds.size > 0 || orchestrator.pendingSubagentSpawns > 0) {
+        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: {} };
+      }
+      ctx.ui.setWorkingMessage?.("Waiting for user approval…");
+      try {
+        const { showActiveTaskMenu } = await import("./pp-menu.js");
+        const text = await showActiveTaskMenu(orchestrator, ctx, params.summary, "tool");
+        if (orchestrator.phaseCompactionPending || orchestrator.taskDoneCompactionPending) {
+          return { content: [{ type: "text" as const, text: "Phase transition in progress." }], details: {} };
+        }
+        if (!text) {
+          return { content: [{ type: "text" as const, text: "No action selected." }], details: {} };
+        }
+        return { content: [{ type: "text" as const, text }], details: {} };
+      } finally {
+        ctx.ui.setWorkingMessage?.();
+      }
+    },
+  });
+}
+
+export function registerEventHandlers(orchestrator: Orchestrator): void {
+  const pi = orchestrator.pi;
+
+  function trackSubagentEvent(data: any, event: "created" | "started" | "first_tool" | "first_turn" | "completed" | "failed"): void {
+    if (!orchestrator.active || !data?.id) return;
+    const now = Date.now();
+    const lifecycle = orchestrator.agentLifecycle.get(data.id) ?? {};
+    if (data.type && lifecycle.type == null) lifecycle.type = data.type;
+    if (data.description && lifecycle.description == null) lifecycle.description = data.description;
+    lifecycle.phase = orchestrator.active.state.phase;
+    lifecycle.step = orchestrator.active.state.step ?? undefined;
+    lifecycle.lastEventAt = now;
+    if (event === "created" && lifecycle.createdAt == null) lifecycle.createdAt = now;
+    if (event === "started" && lifecycle.startedAt == null) lifecycle.startedAt = now;
+    if (event === "first_tool" && lifecycle.firstToolAt == null) lifecycle.firstToolAt = now;
+    if (event === "first_turn" && lifecycle.firstTurnAt == null) lifecycle.firstTurnAt = now;
+    orchestrator.agentLifecycle.set(data.id, lifecycle);
+
+    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;
+    const firstTurnDeltaMs = lifecycle.firstTurnAt == null || lifecycle.createdAt == null ? undefined : lifecycle.firstTurnAt - lifecycle.createdAt;
+    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(),
+      id: data.id,
+      event,
+      description: desc,
+      type: data.type ?? lifecycle.type ?? null,
+      phase: lifecycle.phase ?? null,
+      step: lifecycle.step ?? null,
+      running,
+      pending,
+      ageMs,
+      createdToStartedMs: startedDeltaMs ?? null,
+      createdToFirstToolMs: firstToolDeltaMs ?? null,
+      createdToFirstTurnMs: firstTurnDeltaMs ?? null,
+      toolName: data.toolName ?? null,
+      turnCount: data.turnCount ?? null,
+    });
+  }
+
+  function startStaleAgentWatchdog(): void {
+    if (orchestrator.staleAgentTimer) return;
+    orchestrator.staleAgentTimer = setInterval(() => {
+      if (!orchestrator.active || orchestrator.agentSpawnTimes.size === 0) {
+        clearInterval(orchestrator.staleAgentTimer!);
+        orchestrator.staleAgentTimer = null;
+        return;
+      }
+      const mgr = (globalThis as any)[Symbol.for("pi-subagents:manager")];
+      const now = Date.now();
+      const staleMs = orchestrator.config.timeouts.agentStale;
+      for (const [id, spawnTime] of orchestrator.agentSpawnTimes) {
+        const record = mgr?.getRecord?.(id);
+        if (record?.status === "running" || record?.status === "queued") continue;
+        const lastActivity = orchestrator.agentLifecycle.get(id)?.lastEventAt ?? spawnTime;
+        if (now - lastActivity > staleMs) {
+          const desc = orchestrator.agentDescriptions.get(id) || id;
+          pi.events.emit("subagents:rpc:stop", { requestId: crypto.randomUUID(), agentId: id });
+          orchestrator.spawnedAgentIds.delete(id);
+          orchestrator.agentSpawnTimes.delete(id);
+          orchestrator.agentDescriptions.delete(id);
+          orchestrator.agentLifecycle.delete(id);
+          pi.sendMessage(
+            {
+              customType: "pp-agent-stale",
+              content: `Aborted stale agent "${desc}" — no completion after ${Math.round(staleMs / 1000)}s.`,
+              display: true,
+            },
+            { deliverAs: "steer" },
+          );
+        }
+      }
+      if (orchestrator.agentSpawnTimes.size === 0) {
+        clearInterval(orchestrator.staleAgentTimer!);
+        orchestrator.staleAgentTimer = null;
+      }
+    }, 30000);
+  }
+
+  pi.events.on("subagents:created", (data: any) => {
+    if (!orchestrator.active || !data?.id) return;
+    orchestrator.spawnedAgentIds.add(data.id);
+    orchestrator.agentSpawnTimes.set(data.id, Date.now());
+    if (orchestrator.pendingSubagentSpawns > 0) orchestrator.pendingSubagentSpawns--;
+    if (data.description) {
+      orchestrator.agentDescriptions.set(data.id, data.description);
+    }
+    trackSubagentEvent(data, "created");
+    startStaleAgentWatchdog();
+    const mgr = (globalThis as any)[Symbol.for("pi-subagents:manager")];
+    mgr?.refreshWidget?.(orchestrator.lastCtx?.ui);
+  });
+
+  pi.events.on("subagents:started", (data: any) => {
+    if (!orchestrator.active || !data?.id) return;
+    trackSubagentEvent(data, "started");
+  });
+
+  pi.events.on("subagents:first_tool", (data: any) => {
+    if (!orchestrator.active || !data?.id) return;
+    trackSubagentEvent(data, "first_tool");
+  });
+
+  pi.events.on("subagents:first_turn", (data: any) => {
+    if (!orchestrator.active || !data?.id) return;
+    trackSubagentEvent(data, "first_turn");
+  });
+
+  function checkPlannerCompletion(): void {
+    if (
+      !orchestrator.active ||
+      orchestrator.active.state.phase !== "plan" ||
+      orchestrator.active.state.step !== "await_planners" ||
+      orchestrator.spawnedAgentIds.size > 0 ||
+      orchestrator.pendingSubagentSpawns > 0
+    ) return;
+
+    const plansDir = join(orchestrator.active.dir, "plans");
+    const hasPlanFiles = existsSync(plansDir) &&
+      readdirSync(plansDir).some((f) => f.endsWith(".md") && !f.includes("synthesized") && !f.includes("review_"));
+
+    const failedPlannerVariants = [...orchestrator.failedPlannerVariants];
+    if (
+      failedPlannerVariants.length > 0 &&
+      !orchestrator.plannerFailureDialogPending &&
+      orchestrator.lastCtx
+    ) {
+      orchestrator.plannerFailureDialogPending = true;
+      void (async () => {
+        try {
+          const variantsText = failedPlannerVariants.join(", ");
+          const question = hasPlanFiles
+            ? `Some planners failed: ${variantsText}. Choose how to proceed.`
+            : `All planner outputs failed: ${variantsText}. Choose how to proceed.`;
+          const options = hasPlanFiles
+            ? ["Retry failed planners", "Work with available planner outputs", "Stop task"]
+            : ["Retry failed planners", "Stop task"];
+          const choice = await selectOption(orchestrator.lastCtx, question, options);
+
+          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 retryCount = Object.keys(planners).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();
+              });
+              pi.sendUserMessage(`[PI-PI] Retrying failed planners: ${variantsText}.`, { deliverAs: "followUp" });
+              return;
+            }
+          }
+
+          if (choice === "Stop task") {
+            pi.sendUserMessage(`[PI-PI] ${stopTask(orchestrator)}`, { deliverAs: "followUp" });
+            return;
+          }
+
+          if (hasPlanFiles) {
+            orchestrator.failedPlannerVariants = [];
+          }
+        } finally {
+          orchestrator.plannerFailureDialogPending = false;
+          checkPlannerCompletion();
+        }
+      })();
+      return;
+    }
+
+    if (!hasPlanFiles) {
+      pi.sendMessage(
+        {
+          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" },
+      );
+      orchestrator.active.state.step = "synthesize";
+      saveTask(orchestrator.active.dir, orchestrator.active.state);
+      return;
+    }
+
+    orchestrator.failedPlannerVariants = [];
+    orchestrator.active.state.step = "synthesize";
+    saveTask(orchestrator.active.dir, orchestrator.active.state);
+    pi.sendUserMessage("[PI-PI] All planners completed. Read their outputs and synthesize the plan.", { deliverAs: "followUp" });
+  }
+
+  function checkReviewCycleCompletion(): void {
+    if (
+      !orchestrator.active?.state.reviewCycle ||
+      orchestrator.active.state.reviewCycle.step !== "await_reviewers" ||
+      orchestrator.spawnedAgentIds.size > 0 ||
+      orchestrator.pendingSubagentSpawns > 0
+    ) return;
+
+    const failedReviewerVariants = [...orchestrator.failedReviewerVariants];
+    if (
+      failedReviewerVariants.length > 0 &&
+      !orchestrator.reviewerFailureDialogPending &&
+      orchestrator.lastCtx
+    ) {
+      orchestrator.reviewerFailureDialogPending = true;
+      void (async () => {
+        try {
+          const variantsText = failedReviewerVariants.join(", ");
+          const choice = await selectOption(
+            orchestrator.lastCtx,
+            `Some reviewers failed: ${variantsText}. Choose how to proceed.`,
+            ["Retry failed reviewers", "Work with available reviewer outputs", "Continue without review", "Stop task"],
+          );
+
+          if (choice === "Retry failed reviewers") {
+            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 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 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)
+                  : 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);
+                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();
+                });
+                pi.sendUserMessage(`[PI-PI] Retrying failed reviewers: ${variantsText}.`, { deliverAs: "followUp" });
+                return;
+              }
+            }
+          }
+
+          if (choice === "Stop task") {
+            pi.sendUserMessage(`[PI-PI] ${stopTask(orchestrator)}`, { deliverAs: "followUp" });
+            return;
+          }
+
+          if (choice === "Continue without review") {
+            if (!orchestrator.active?.state.reviewCycle) return;
+            orchestrator.failedReviewerVariants = [];
+            orchestrator.active.state.reviewCycle = null;
+            orchestrator.active.state.step = "user_gate";
+            saveTask(orchestrator.active.dir, orchestrator.active.state);
+            pi.sendUserMessage("[PI-PI] Review cycle skipped. Use /pp to choose the next action.", { deliverAs: "followUp" });
+            return;
+          }
+
+          orchestrator.failedReviewerVariants = [];
+        } finally {
+          orchestrator.reviewerFailureDialogPending = false;
+          checkReviewCycleCompletion();
+        }
+      })();
+      return;
+    }
+
+    tryCompleteReviewCycle(orchestrator);
+  }
+
+  pi.events.on("subagents:completed", (data: any) => {
+    if (!orchestrator.active || !data?.id) return;
+    trackSubagentEvent(data, "completed");
+    orchestrator.spawnedAgentIds.delete(data.id);
+    orchestrator.agentDescriptions.delete(data.id);
+    orchestrator.agentSpawnTimes.delete(data.id);
+    orchestrator.agentLifecycle.delete(data.id);
+
+    const desc = data.description || data.type || data.id;
+    const duration = data.durationMs ? `${(data.durationMs / 1000).toFixed(1)}s` : "";
+    const tokens = data.tokens?.total ? `${data.tokens.total} tok` : "";
+    const stats = [duration, tokens].filter(Boolean).join(", ");
+
+    pi.sendMessage(
+      {
+        customType: "pp-subagent-result",
+        content: `${desc} completed${stats ? ` (${stats})` : ""}. Use get_subagent_result to read the output.`,
+        display: false,
+      },
+      { deliverAs: "steer" },
+    );
+
+    checkPlannerCompletion();
+    checkReviewCycleCompletion();
+  });
+
+  pi.events.on("subagents:failed", (data: any) => {
+    if (!orchestrator.active || !data?.id) return;
+    trackSubagentEvent(data, "failed");
+    orchestrator.spawnedAgentIds.delete(data.id);
+    orchestrator.agentSpawnTimes.delete(data.id);
+    const desc = orchestrator.agentDescriptions.get(data.id) || data.type || data.id;
+    orchestrator.agentDescriptions.delete(data.id);
+    orchestrator.agentLifecycle.delete(data.id);
+
+    if (data.status === "stopped" || data.status === "aborted") {
+      checkPlannerCompletion();
+      checkReviewCycleCompletion();
+      return;
+    }
+
+    const isApiError = data.status === "error" && (data.toolUses ?? 0) === 0;
+    if (isApiError && orchestrator.spawnedAgentIds.size > 0) {
+      orchestrator.abortAllSubagents();
+    }
+
+    pi.sendMessage(
+      {
+        customType: "pp-subagent-error",
+        content: isApiError
+          ? `**${desc}** failed (model/API error): ${data.error || "unknown error"}. All subagents aborted. Do NOT retry — the model is likely unavailable. Report the error to the user and ask how to proceed.`
+          : `**${desc}** failed: ${data.error || "unknown error"}. Do NOT retry — continue with available information.`,
+        display: true,
+      },
+      { deliverAs: "steer" },
+    );
+
+    checkPlannerCompletion();
+    checkReviewCycleCompletion();
+  });
+
+  pi.on("session_before_switch" as any, async () => {
+    if (!orchestrator.active) return;
+    cancelPendingPlannotatorWait(orchestrator);
+    orchestrator.abortAllSubagents();
+    unregisterAgentDefinitions(pi);
+    await orchestrator.cleanupActive();
+  });
+
+  pi.on("session_start", async (_event, ctx) => {
+    orchestrator.lastCtx = ctx;
+    orchestrator.cwd = ctx.cwd;
+
+    const subagentsMgr = (globalThis as any)[Symbol.for("pi-subagents:manager")];
+    subagentsMgr?.refreshWidget?.(ctx.ui);
+    const taskStore = (globalThis as any)[Symbol.for("pi-tasks:store")];
+    taskStore?.refreshWidget?.(ctx.ui);
+
+    if ((globalThis as any)[SUBAGENT_SESSION_KEY]) {
+      return;
+    }
+
+    const duplicates = orchestrator.checkForConflictingExtensions();
+    if (duplicates.length > 0) {
+      const msg = `pi-pi bundles its own versions of pi-subagents, pi-tasks, and pi-ask-user. ` +
+        `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}`);
+      return;
+    }
+
+    try {
+      const { setPI, initFlantOnStartup } = await import("./flant-infra.js");
+      setPI(pi);
+      await initFlantOnStartup(pi);
+    } catch (err: any) {
+      console.error(`[pi-pi] Flant infra init failed: ${err.message}`);
+    }
+
+    try {
+      orchestrator.config = loadConfig(orchestrator.cwd);
+    } catch (err: any) {
+      console.error(`[pi-pi] Failed to load config on session start: ${err.message}`);
+      return;
+    }
+
+    registerCbmTools(pi, orchestrator.cwd);
+    registerExaTools(pi);
+    registerAstSearchTool(pi, orchestrator.cwd);
+    registerOrchestratorTools(orchestrator);
+    setExtensionOnlyMode(pi);
+    orchestrator.registerAgents();
+
+    const found = getActiveTask(orchestrator.cwd, orchestrator.config.timeouts.lockStale);
+    if (found) {
+      ctx.ui.notify(
+          `Paused task: "${taskName(found.dir)}" (${found.type}, phase: ${found.state.phase}). Run /pp and choose Resume to continue.`,
+        "info",
+      );
+    }
+  });
+
+  pi.on("input", async (event, ctx) => {
+    if (!orchestrator.active) return;
+    if (event.source !== "interactive") return;
+
+    const step = orchestrator.active.state.step;
+    if (step === "await_planners" || step === "await_reviewers") {
+      ctx.ui.notify("Waiting for subagents to finish. Your input will be available after they complete.", "warning");
+      return { action: "handled" as const };
+    }
+  });
+
+  pi.on("before_agent_start", async (event, ctx) => {
+    orchestrator.lastCtx = ctx;
+    if (orchestrator.taskDoneCompactionPending || orchestrator.phaseCompactionPending) {
+      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;
+    }
+
+    orchestrator.nudgeHalted = false;
+    orchestrator.updateStatus(ctx);
+
+    const phasePrompt = orchestrator.getPhasePrompt(ctx);
+    const systemContextFiles = loadContextFiles(orchestrator.cwd, "main", "system");
+    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;
+
+    return {
+      systemPrompt: event.systemPrompt + "\n\n" + fullAddition,
+    };
+  });
+
+  pi.on("tool_call", async (event, _ctx) => {
+    if (event.toolName === "Agent" && orchestrator.active) {
+      const input = event.input as Record<string, unknown>;
+      const requestedType = ((input.subagent_type as string) || "").toLowerCase();
+      const isExplore = !requestedType || requestedType === "explore";
+      const isLibrarian = requestedType === "librarian";
+
+      if (isExplore) {
+        input.subagent_type = "explore";
+        input.model = orchestrator.config.agents.explore.model;
+        input.thinking = orchestrator.config.agents.explore.thinking;
+      } else if (isLibrarian) {
+        input.subagent_type = "librarian";
+        input.model = orchestrator.config.agents.librarian.model;
+        input.thinking = orchestrator.config.agents.librarian.thinking;
+      } else {
+        input.subagent_type = "task";
+        input.model = orchestrator.config.agents.task.model;
+        input.thinking = orchestrator.config.agents.task.thinking;
+      }
+    }
+
+    if (event.toolName === "write" || event.toolName === "edit") {
+      const input = event.input as { file_path?: string; filePath?: string; path?: string };
+      const rawPath = input.file_path || input.filePath || input.path || "";
+      const resolvedPath = resolve(orchestrator.cwd, rawPath);
+      const ppStateDir = resolve(orchestrator.cwd, ".pp", "state");
+      const ppDir = resolve(orchestrator.cwd, ".pp");
+
+      if (resolvedPath.startsWith(ppStateDir + "/") || resolvedPath === ppStateDir) {
+        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)) {
+        return { block: true, reason: "state.json is managed by the extension" };
+      }
+
+      if (fileName === "config.json" && (resolvedPath.startsWith(ppDir + "/") || resolvedPath === ppDir)) {
+        return { block: true, reason: "config.json is managed by the user, not the LLM" };
+      }
+    }
+    return;
+  });
+
+  pi.on("tool_result", async (event, _ctx) => {
+    if (!orchestrator.active) return;
+
+    if ((event.toolName === "edit" || event.toolName === "write") && !event.isError) {
+      const input = event.input as { file_path?: string; filePath?: string; path?: string };
+      const filePath = input.file_path || input.filePath || input.path;
+      if (!filePath) return;
+
+      const resolvedWrite = resolve(orchestrator.cwd, filePath);
+      const taskDir = orchestrator.active.dir;
+      if (resolvedWrite === join(taskDir, "USER_REQUEST.md")) {
+        const content = readFileSync(resolvedWrite, "utf-8");
+        const result = validateUserRequest(content);
+        if (!result.ok) {
+          return {
+            content: [
+              ...event.content,
+              { type: "text" as const, text: `\n\n<validation-error>\nUSER_REQUEST.md structure is invalid:\n${result.errors.map((e) => `- ${e}`).join("\n")}\n\nFix immediately. Keep exactly: # User Request, ## Problem, ## Constraints. No other sections.\n</validation-error>` },
+            ],
+          };
+        }
+      }
+      if (resolvedWrite === join(taskDir, "RESEARCH.md")) {
+        const content = readFileSync(resolvedWrite, "utf-8");
+        const result = validateResearch(content);
+        if (!result.ok) {
+          return {
+            content: [
+              ...event.content,
+              { type: "text" as const, text: `\n\n<validation-error>\nRESEARCH.md structure is invalid:\n${result.errors.map((e) => `- ${e}`).join("\n")}\n\nFix immediately. Keep exactly: ## Affected Code, ## Architecture Context, ## Constraints & Edge Cases, ## Open Questions (optional). No other sections.\n</validation-error>` },
+            ],
+          };
+        }
+      }
+      const artifactsDir = join(taskDir, "artifacts");
+      if (resolvedWrite.startsWith(artifactsDir + "/") && resolvedWrite.endsWith(".md")) {
+        const content = readFileSync(resolvedWrite, "utf-8");
+        const result = validateArtifact(content);
+        if (!result.ok) {
+          return {
+            content: [
+              ...event.content,
+              { type: "text" as const, text: `\n\n<validation-error>\nArtifact structure is invalid:\n${result.errors.map((e) => `- ${e}`).join("\n")}\n\nFix immediately. Artifact files must start with # <Title>.\n</validation-error>` },
+            ],
+          };
+        }
+      }
+
+      if (filePath.includes(".pp/")) return;
+
+      if (orchestrator.active.state.phase !== "implement") return;
+
+      orchestrator.active.modifiedFiles.add(filePath);
+      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 {}
+      }
+      try { saveTask(orchestrator.active.dir, orchestrator.active.state); } catch {}
+
+      const afterEditResults = runAfterEdit(filePath, orchestrator.config, orchestrator.cwd);
+      const failures = afterEditResults.filter((r) => !r.ok);
+
+      if (failures.length > 0) {
+        const failureText = failures
+          .map((f) => `afterEdit command failed: ${f.command}\n${f.output}`)
+          .join("\n\n");
+        return {
+          content: [
+            ...event.content,
+            { type: "text" as const, text: `\n\n<afterEdit>\n${failureText}\n</afterEdit>` },
+          ],
+        };
+      }
+
+      const lspAvailable = pi.getAllTools().some((t) => t.name === "lsp");
+      if (lspAvailable) {
+        return {
+          content: [
+            ...event.content,
+            { type: "text" as const, text: `\n\nRun lsp diagnostics on ${filePath} to check for errors.` },
+          ],
+        };
+      }
+    }
+    return;
+  });
+
+  pi.on("session_before_compact", async (event, _ctx) => {
+    if (orchestrator.taskDoneCompactionPending) {
+      const summary = orchestrator.taskDoneCompactionSummary;
+      orchestrator.taskDoneCompactionPending = false;
+      orchestrator.taskDoneCompactionSummary = "";
+      return {
+        compaction: {
+          summary,
+          firstKeptEntryId: event.preparation.firstKeptEntryId,
+          tokensBefore: event.preparation.tokensBefore,
+        },
+      };
+    }
+
+    if (!orchestrator.active || orchestrator.active.state.phase === "done") return;
+
+    if (orchestrator.phaseCompactionPending) {
+      return {
+        compaction: {
+          summary: `Previous phase (${orchestrator.active.state.phase}) completed. Transitioning to next phase.`,
+          firstKeptEntryId: event.preparation.firstKeptEntryId,
+          tokensBefore: event.preparation.tokensBefore,
+        },
+      };
+    }
+
+    const artifacts = getPhaseArtifacts(orchestrator.active.dir, orchestrator.active.state.phase);
+    if (artifacts.length === 0) return;
+
+    const artifactText = artifacts
+      .map((a) => `=== ${a.name} ===\n${a.content}`)
+      .join("\n\n");
+
+    pi.sendMessage(
+      {
+        customType: "pp-artifact-reinject",
+        content: `[PI-PI ARTIFACTS — re-injected after compaction]\n\n${artifactText}`,
+        display: false,
+      },
+      { deliverAs: "steer" },
+    );
+
+    return;
+  });
+
+  pi.on("turn_end", async (event, ctx) => {
+    if (!orchestrator.active || orchestrator.active.state.phase === "done") return;
+    orchestrator.updateStatus(ctx);
+
+    if (
+      orchestrator.active.state.phase === "implement" &&
+      orchestrator.config.autoCommit &&
+      orchestrator.active.modifiedFiles.size > 0 &&
+      !orchestrator.commitReminderSent
+    ) {
+      orchestrator.commitReminderSent = true;
+      pi.sendMessage(
+        {
+          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.`,
+          display: false,
+        },
+        { deliverAs: "steer" },
+      );
+    }
+
+    const phase = orchestrator.active.state.phase;
+
+    const msg = event.message as any;
+    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)"}`);
+      }
+      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 taskToken = orchestrator.activeTaskToken;
+        if (orchestrator.pendingRetryTimer) clearTimeout(orchestrator.pendingRetryTimer);
+        orchestrator.pendingRetryTimer = setTimeout(() => {
+          orchestrator.pendingRetryTimer = null;
+          if (orchestrator.activeTaskToken !== taskToken || !orchestrator.active) return;
+          pi.sendUserMessage(`[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");
+        orchestrator.errorRetryCount = 0;
+      }
+      return;
+    }
+    orchestrator.errorRetryCount = 0;
+
+    if ((globalThis as any)[SUBAGENT_SESSION_KEY]) {
+      return;
+    }
+
+    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;
+          }
+          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);
+                pi.sendUserMessage("[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" },
+              );
+              pi.sendUserMessage("[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;
+
+    const contentParts = Array.isArray(msg?.content) ? msg.content : [];
+    const hasText = contentParts.some((c: any) => c.type === "text" && c.text?.trim());
+    const hasToolCalls = contentParts.some((c: any) => c.type === "toolCall");
+    const hasToolResults = event.toolResults && event.toolResults.length > 0;
+    const turnWasEmpty = !hasText && !hasToolCalls && !hasToolResults;
+
+    if (!turnWasEmpty) {
+      if (hasText && !hasToolCalls) {
+        const step = orchestrator.active.state.step;
+        if (step !== "await_planners" && step !== "await_reviewers") {
+          pi.sendMessage(
+            {
+              customType: "pp-phase-complete-reminder",
+              content: `[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.`,
+              display: false,
+            },
+            { deliverAs: "followUp" },
+          );
+        }
+      }
+      return;
+    }
+    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 now = Date.now();
+
+    orchestrator.nudgeTimestamps.push(now);
+    orchestrator.nudgeTimestamps = orchestrator.nudgeTimestamps.filter((t) => now - t < 60000);
+
+    const sendNudge = () => {
+      pi.sendMessage(
+        {
+          customType: "pp-continuation",
+          content: `[PI-PI] Your previous response was interrupted. Continue working on the current phase (${phase}). Pick up where you left off.`,
+          display: false,
+        },
+        { deliverAs: "followUp" },
+      );
+    };
+
+    if (orchestrator.nudgeTimestamps.length <= 3) {
+      sendNudge();
+      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;
+      }
+
+      pi.sendMessage(
+        {
+          customType: "pp-continuation-cooldown",
+          content: "Agent interrupted repeatedly. Waiting 60 seconds before retrying.",
+          display: true,
+        },
+        { deliverAs: "steer" },
+      );
+      orchestrator.nudgeTimestamps = [];
+      const cooldownToken = orchestrator.activeTaskToken;
+      setTimeout(() => {
+        if (orchestrator.activeTaskToken !== cooldownToken || !orchestrator.active) return;
+        sendNudge();
+      }, 60000);
+      return;
+    }
+
+    sendNudge();
+  });
+
+
+}