@ilya-lesikov/pi-pi 0.1.0

package/extensions/orchestrator/ast-search.ts

@@ -0,0 +1,85 @@
+import { execFile } from "child_process";
+import { existsSync } from "fs";
+import { resolve } from "path";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Type } from "@sinclair/typebox";
+
+const SG_AVAILABLE_KEY = Symbol.for("pi-pi:sg-available");
+
+function isSgAvailable(): boolean {
+  const cached = (globalThis as any)[SG_AVAILABLE_KEY];
+  if (cached !== undefined) return cached;
+  try {
+    const { execFileSync } = require("child_process");
+    execFileSync("sg", ["--version"], { encoding: "utf-8", stdio: "pipe" });
+    (globalThis as any)[SG_AVAILABLE_KEY] = true;
+    return true;
+  } catch {
+    (globalThis as any)[SG_AVAILABLE_KEY] = false;
+    return false;
+  }
+}
+
+function ok(text: string) {
+  return { content: [{ type: "text" as const, text }], details: {} };
+}
+
+function fail(text: string) {
+  return { content: [{ type: "text" as const, text }], isError: true as const, details: {} };
+}
+
+export function registerAstSearchTool(pi: ExtensionAPI, cwd: string): boolean {
+  if (!isSgAvailable()) return false;
+
+  pi.registerTool({
+    name: "ast_search",
+    label: "ast-grep",
+    description:
+      "Search code using AST-aware structural patterns. Uses ast-grep (sg). " +
+      "Patterns use meta-variables: $NAME matches a single node, $$$ matches multiple nodes. " +
+      "Examples: 'if err != nil { $$$ }', 'func $NAME($$$) { $$$ }', '$X.($TYPE)'",
+    parameters: Type.Object({
+      pattern: Type.String({ description: "AST pattern to search for" }),
+      lang: Type.Optional(Type.String({ description: "Language hint (e.g. 'go', 'typescript', 'python')" })),
+      path: Type.Optional(Type.String({ description: "Directory or file to search (default: project root)" })),
+    }),
+    async execute(_toolCallId: string, params: any) {
+      const searchPath = resolve(cwd, params.path ?? ".");
+      if (!existsSync(searchPath)) {
+        return fail(`Path '${params.path}' does not exist`);
+      }
+
+      const args = ["run", "--json", "-p", params.pattern];
+      if (params.lang) args.push("-l", params.lang);
+      args.push(searchPath);
+
+      try {
+        const stdout = await new Promise<string>((res, rej) => {
+          execFile("sg", args, { timeout: 30000, encoding: "utf-8", maxBuffer: 10 * 1024 * 1024 }, (err, out, stderr) => {
+            if (err && !out) return rej(new Error(stderr?.trim() || err.message));
+            res(out);
+          });
+        });
+
+        const results = JSON.parse(stdout || "[]");
+        if (!Array.isArray(results) || results.length === 0) {
+          return ok("No matches found.");
+        }
+
+        const lines: string[] = [];
+        for (const match of results) {
+          const file = match.file ?? "?";
+          const startLine = match.range?.start?.line ?? match.start?.line ?? "?";
+          const text = match.text ?? match.matchedCode ?? "";
+          lines.push(`${file}:${startLine}: ${text.trim()}`);
+        }
+
+        return ok(`${results.length} match(es):\n\n${lines.join("\n")}`);
+      } catch (e: any) {
+        return fail(`ast_search error: ${e.message}`);
+      }
+    },
+  });
+
+  return true;
+}

package/extensions/orchestrator/cbm.ts

@@ -0,0 +1,330 @@
+import { spawn, execFileSync, type ChildProcess } from "child_process";
+import { createInterface, type Interface as ReadlineInterface } from "readline";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Type } from "@sinclair/typebox";
+
+function findCbmBin(): string | null {
+  try {
+    return execFileSync("which", ["codebase-memory-mcp"], { encoding: "utf-8", stdio: "pipe" }).trim() || null;
+  } catch {
+    return null;
+  }
+}
+
+const CBM_BIN_KEY = Symbol.for("pi-pi:cbm-bin");
+
+function getCbmBin(): string | null {
+  if ((globalThis as any)[CBM_BIN_KEY] !== undefined) return (globalThis as any)[CBM_BIN_KEY];
+  const bin = findCbmBin();
+  (globalThis as any)[CBM_BIN_KEY] = bin;
+  return bin;
+}
+
+function isCbmAvailable(): boolean {
+  return getCbmBin() !== null;
+}
+
+const CBM_DAEMON_KEY = Symbol.for("pi-pi:cbm-daemon");
+
+function getGlobalDaemon(): CbmDaemon | null {
+  return (globalThis as any)[CBM_DAEMON_KEY] ?? null;
+}
+
+function setGlobalDaemon(daemon: CbmDaemon): void {
+  (globalThis as any)[CBM_DAEMON_KEY] = daemon;
+}
+
+class CbmDaemon {
+  private proc: ChildProcess | null = null;
+  private rl: ReadlineInterface | null = null;
+  private nextId = 1;
+  private pending = new Map<number, { resolve: (v: any) => void; reject: (e: Error) => void; timer: ReturnType<typeof setTimeout> }>();
+  private initialized = false;
+  private initPromise: Promise<void> | null = null;
+  private indexedProjects = new Set<string>();
+
+  start(): void {
+    if (this.proc) return;
+
+    this.proc = spawn(getCbmBin()!, [], { stdio: ["pipe", "pipe", "ignore"] });
+    this.proc.unref();
+    (this.proc.stdout as any)?.unref?.();
+    (this.proc.stdin as any)?.unref?.();
+
+    this.rl = createInterface({ input: this.proc.stdout! });
+    this.rl.on("line", (line) => this.handleLine(line));
+
+    this.proc.on("exit", () => this.cleanup());
+    this.proc.on("error", (err) => {
+      console.error(`[pi-pi] CBM daemon error: ${err.message}`);
+      this.cleanup();
+    });
+
+    this.initPromise = this.initialize();
+  }
+
+  private cleanup(): void {
+    for (const [, entry] of this.pending) {
+      clearTimeout(entry.timer);
+      entry.reject(new Error("CBM daemon exited"));
+    }
+    this.pending.clear();
+    this.rl?.close();
+    this.rl = null;
+    this.proc = null;
+    this.initialized = false;
+    this.initPromise = null;
+  }
+
+  stop(): void {
+    if (!this.proc) return;
+    try { this.proc.kill(); } catch {}
+    this.cleanup();
+  }
+
+  private async initialize(): Promise<void> {
+    await this.rpc("initialize", {
+      protocolVersion: "2024-11-05",
+      capabilities: {},
+      clientInfo: { name: "pi-pi", version: "1.0" },
+    });
+    this.initialized = true;
+  }
+
+  private handleLine(line: string): void {
+    if (!line.trim()) return;
+    try {
+      const msg = JSON.parse(line);
+      if (msg.id != null && this.pending.has(msg.id)) {
+        const entry = this.pending.get(msg.id)!;
+        this.pending.delete(msg.id);
+        clearTimeout(entry.timer);
+        if (msg.error) {
+          entry.reject(new Error(msg.error.message ?? JSON.stringify(msg.error)));
+        } else {
+          entry.resolve(msg.result);
+        }
+      }
+    } catch {
+      // ignore unparseable lines (e.g. log output on stderr)
+    }
+  }
+
+  private rpc(method: string, params: Record<string, unknown>, timeoutMs = 60000): Promise<any> {
+    return new Promise((resolve, reject) => {
+      if (!this.proc?.stdin?.writable) {
+        return reject(new Error("CBM daemon not running"));
+      }
+
+      const id = this.nextId++;
+      const timer = setTimeout(() => {
+        this.pending.delete(id);
+        reject(new Error(`CBM call timed out: ${method}`));
+      }, timeoutMs);
+
+      this.pending.set(id, { resolve, reject, timer });
+      this.proc.stdin.write(JSON.stringify({ jsonrpc: "2.0", id, method, params }) + "\n");
+    });
+  }
+
+  private async ensureReady(): Promise<void> {
+    if (!this.proc) this.start();
+    if (this.initPromise) await this.initPromise;
+  }
+
+  async callTool(name: string, args: Record<string, unknown>, timeoutMs = 60000): Promise<unknown> {
+    await this.ensureReady();
+    const result = await this.rpc("tools/call", { name, arguments: args }, timeoutMs);
+    if (result?.isError) {
+      throw new Error(result.content?.[0]?.text ?? "unknown CBM error");
+    }
+    const text = result?.content?.[0]?.text;
+    if (!text) return result;
+    try {
+      return JSON.parse(text);
+    } catch {
+      return text;
+    }
+  }
+
+  async ensureIndexed(cwd: string): Promise<string> {
+    const name = projectName(cwd);
+    if (this.indexedProjects.has(name)) return name;
+
+    try {
+      const projects = (await this.callTool("list_projects", {})) as { projects: Array<{ name: string }> };
+      if (projects.projects.some((p) => p.name === name)) {
+        this.indexedProjects.add(name);
+        return name;
+      }
+    } catch { /* fall through to index */ }
+
+    await this.callTool("index_repository", { repo_path: cwd }, 300000);
+    this.indexedProjects.add(name);
+    return name;
+  }
+}
+
+function projectName(cwd: string): string {
+  return cwd.replace(/^\//, "").replace(/\//g, "-");
+}
+
+function ok(text: string) {
+  return { content: [{ type: "text" as const, text }], details: {} };
+}
+
+function fail(text: string) {
+  return { content: [{ type: "text" as const, text }], isError: true as const, details: {} };
+}
+
+export function registerCbmTools(pi: ExtensionAPI, cwd: string): boolean {
+  if (!isCbmAvailable()) return false;
+
+  let daemon = getGlobalDaemon();
+  if (!daemon) {
+    daemon = new CbmDaemon();
+    daemon.start();
+    setGlobalDaemon(daemon);
+  }
+
+  pi.registerTool({
+    name: "cbm_search",
+    label: "CBM",
+    description:
+      "Search the codebase knowledge graph. Use `query` for natural-language BM25 search, " +
+      "`name_pattern` for regex on symbol names, or `semantic_query` (array of keywords) for " +
+      "vector similarity. Returns symbols with name, file_path, label, in_degree, out_degree.",
+    parameters: Type.Object({
+      query: Type.Optional(Type.String({ description: "Natural-language BM25 search (e.g. 'deploy release chart')" })),
+      name_pattern: Type.Optional(Type.String({ description: "Regex pattern on symbol names" })),
+      semantic_query: Type.Optional(Type.Array(Type.String(), { description: "Array of keywords for vector similarity search" })),
+      label: Type.Optional(Type.String({ description: "Filter by node type: Function, Method, Interface, Class, Type, Route" })),
+      limit: Type.Optional(Type.Number({ description: "Max results (default: 20)" })),
+    }),
+    async execute(_toolCallId, params: any) {
+      try {
+        const project = await daemon.ensureIndexed(cwd);
+        const p: Record<string, unknown> = { project, limit: params.limit ?? 20 };
+        if (params.query) p.query = params.query;
+        if (params.name_pattern) p.name_pattern = params.name_pattern;
+        if (params.semantic_query) p.semantic_query = params.semantic_query;
+        if (params.label) p.label = params.label;
+        return ok(JSON.stringify(await daemon.callTool("search_graph", p), null, 2));
+      } catch (e: any) {
+        return fail(`cbm_search error: ${e.message}`);
+      }
+    },
+  });
+
+  pi.registerTool({
+    name: "cbm_search_code",
+    label: "CBM",
+    description:
+      "Graph-augmented grep: searches code text then deduplicates matches into containing " +
+      "functions with structural metadata (in_degree, out_degree, label). Better than raw grep " +
+      "for understanding which functions contain a pattern.",
+    parameters: Type.Object({
+      pattern: Type.String({ description: "Text pattern to search for" }),
+      file_pattern: Type.Optional(Type.String({ description: "Glob filter (e.g. '*.go', '*.ts')" })),
+      path_filter: Type.Optional(Type.String({ description: "Regex filter on file paths (e.g. '^pkg/')" })),
+      limit: Type.Optional(Type.Number({ description: "Max results (default: 20)" })),
+    }),
+    async execute(_toolCallId, params: any) {
+      try {
+        const project = await daemon.ensureIndexed(cwd);
+        const p: Record<string, unknown> = { project, pattern: params.pattern, limit: params.limit ?? 20 };
+        if (params.file_pattern) p.file_pattern = params.file_pattern;
+        if (params.path_filter) p.path_filter = params.path_filter;
+        return ok(JSON.stringify(await daemon.callTool("search_code", p), null, 2));
+      } catch (e: any) {
+        return fail(`cbm_search_code error: ${e.message}`);
+      }
+    },
+  });
+
+  pi.registerTool({
+    name: "cbm_trace",
+    label: "CBM",
+    description:
+      "Trace call chains through the code graph. Find who calls a function (inbound) or " +
+      "what a function calls (outbound). Useful for understanding dependencies and impact.",
+    parameters: Type.Object({
+      function_name: Type.String({ description: "Function name to trace" }),
+      direction: Type.Optional(Type.String({ description: "inbound, outbound, or both (default: both)" })),
+      depth: Type.Optional(Type.Number({ description: "Max traversal depth (default: 3)" })),
+    }),
+    async execute(_toolCallId, params: any) {
+      try {
+        const project = await daemon.ensureIndexed(cwd);
+        const p: Record<string, unknown> = {
+          project,
+          function_name: params.function_name,
+          direction: params.direction ?? "both",
+          depth: params.depth ?? 3,
+        };
+        return ok(JSON.stringify(await daemon.callTool("trace_path", p), null, 2));
+      } catch (e: any) {
+        return fail(`cbm_trace error: ${e.message}`);
+      }
+    },
+  });
+
+  pi.registerTool({
+    name: "cbm_changes",
+    label: "CBM",
+    description:
+      "Detect code changes from git diff and map to affected symbols with blast radius. " +
+      "Shows which functions/types are impacted by uncommitted or branch changes.",
+    parameters: Type.Object({
+      base_branch: Type.Optional(Type.String({ description: "Compare against this branch (default: main)" })),
+      since: Type.Optional(Type.String({ description: "Git ref or date (e.g. HEAD~5, v0.5.0)" })),
+    }),
+    async execute(_toolCallId, params: any) {
+      try {
+        const project = await daemon.ensureIndexed(cwd);
+        const p: Record<string, unknown> = { project };
+        if (params.base_branch) p.base_branch = params.base_branch;
+        if (params.since) p.since = params.since;
+        return ok(JSON.stringify(await daemon.callTool("detect_changes", p), null, 2));
+      } catch (e: any) {
+        return fail(`cbm_changes error: ${e.message}`);
+      }
+    },
+  });
+
+  pi.registerTool({
+    name: "cbm_query",
+    label: "CBM",
+    description:
+      "Execute a Cypher-like graph query for complex multi-hop patterns. " +
+      "Example: MATCH (f:Function)-[:CALLS]->(g:Function) WHERE f.name = 'main' RETURN g.name, g.file_path LIMIT 10",
+    parameters: Type.Object({
+      query: Type.String({ description: "Cypher query string" }),
+    }),
+    async execute(_toolCallId, params: any) {
+      try {
+        const project = await daemon.ensureIndexed(cwd);
+        return ok(JSON.stringify(await daemon.callTool("query_graph", { project, query: params.query }), null, 2));
+      } catch (e: any) {
+        return fail(`cbm_query error: ${e.message}`);
+      }
+    },
+  });
+
+  pi.registerTool({
+    name: "cbm_architecture",
+    label: "CBM",
+    description: "Get high-level architecture overview of the indexed codebase — node/edge counts, schema, structure.",
+    parameters: Type.Object({}),
+    async execute() {
+      try {
+        const project = await daemon.ensureIndexed(cwd);
+        return ok(JSON.stringify(await daemon.callTool("get_architecture", { project }), null, 2));
+      } catch (e: any) {
+        return fail(`cbm_architecture error: ${e.message}`);
+      }
+    },
+  });
+
+  return true;
+}

package/extensions/orchestrator/command-handlers.test.ts

@@ -0,0 +1,163 @@
+import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from "fs";
+import { tmpdir } from "os";
+import { join } from "path";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { registerCommandHandlers } from "./command-handlers.js";
+import { Orchestrator, type ActiveTask } from "./orchestrator.js";
+
+vi.mock("./event-handlers.js", () => ({
+  runUserGateDialog: vi.fn().mockResolvedValue("User wants to continue. Run /pp:next when ready to advance."),
+}));
+
+import { runUserGateDialog } from "./event-handlers.js";
+
+type Handler = (args: string | undefined, ctx: any) => any;
+
+const tempDirs: string[] = [];
+
+function makeTempDir(): string {
+  const dir = mkdtempSync(join(tmpdir(), "pi-pi-cmd-"));
+  tempDirs.push(dir);
+  return dir;
+}
+
+afterEach(() => {
+  vi.mocked(runUserGateDialog).mockClear();
+  while (tempDirs.length > 0) {
+    const dir = tempDirs.pop();
+    if (dir) rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+function makePi() {
+  const commands = new Map<string, { handler: Handler }>();
+  return {
+    registerCommand: vi.fn((name: string, cmd: { handler: Handler }) => {
+      commands.set(name, cmd);
+    }),
+    on: vi.fn(),
+    events: { on: vi.fn(), emit: vi.fn() },
+    getAllTools: vi.fn().mockReturnValue([]),
+    sendMessage: vi.fn(),
+    sendUserMessage: vi.fn(),
+    setModel: vi.fn(),
+    setThinkingLevel: vi.fn(),
+    setSessionName: vi.fn(),
+    _commands: commands,
+  };
+}
+
+function makeConfig() {
+  return {
+    mainModel: {
+      implement: { model: "a/b", thinking: "high" },
+      debug: { model: "a/b", thinking: "high" },
+      brainstorm: { model: "a/b", thinking: "high" },
+    },
+    planners: {},
+    planReviewers: {},
+    codeReviewers: { variant1: { enabled: true, model: "x/1", thinking: "low" } },
+    brainstormReviewers: { variant1: { enabled: true, model: "x/1", thinking: "low" } },
+    agents: {
+      explore: { model: "x/e", thinking: "low" },
+      librarian: { model: "x/l", thinking: "medium" },
+      task: { model: "x/t", thinking: "medium" },
+    },
+    commands: { afterEdit: [], afterImplement: [] },
+    timeouts: { afterEdit: 1, afterImplement: 1, agentSpawn: 1, agentReadyPing: 1, lockStale: 1, lockUpdate: 1 },
+    autoCommit: false,
+  };
+}
+
+function makeActiveTask(taskDir: string): ActiveTask {
+  const stateDir = join(taskDir, "plans");
+  mkdirSync(stateDir, { recursive: true });
+  writeFileSync(join(stateDir, "1_synthesized.md"), "- [x] done\n", "utf-8");
+  writeFileSync(join(taskDir, "USER_REQUEST.md"), "request", "utf-8");
+  writeFileSync(join(taskDir, "RESEARCH.md"), "research", "utf-8");
+  return {
+    dir: taskDir,
+    type: "implement",
+    state: {
+      phase: "implement",
+      step: "user_gate",
+      reviewCycle: null,
+      reviewPass: 1,
+      from: null,
+      description: "Test",
+      startedAt: new Date().toISOString(),
+    },
+    release: null,
+    taskId: "123",
+    modifiedFiles: new Set(),
+    reviewPass: 1,
+    description: "Test",
+  };
+}
+
+function makeCtx() {
+  return {
+    ui: {
+      confirm: vi.fn(),
+      select: vi.fn(),
+      notify: vi.fn(),
+      setStatus: vi.fn(),
+    },
+    abort: vi.fn(),
+    waitForIdle: vi.fn().mockResolvedValue(undefined),
+    compact: vi.fn(),
+  };
+}
+
+describe("pp:next user gate", () => {
+  it("routes pp:next to shared user gate dialog", async () => {
+    const pi = makePi();
+    const orchestrator = new Orchestrator(pi as any);
+    const taskDir = makeTempDir();
+    orchestrator.cwd = taskDir;
+    orchestrator.config = makeConfig() as any;
+    orchestrator.active = makeActiveTask(taskDir);
+    registerCommandHandlers(orchestrator);
+
+    const ctx = makeCtx();
+
+    const ppNext = pi._commands.get("pp:next");
+    await ppNext!.handler(undefined, ctx);
+
+    expect(runUserGateDialog).toHaveBeenCalledOnce();
+    expect(pi.sendUserMessage).toHaveBeenCalledWith("[PI-PI] User wants to continue. Run /pp:next when ready to advance.");
+  });
+
+  it("returns error when no active task", async () => {
+    const pi = makePi();
+    const orchestrator = new Orchestrator(pi as any);
+    orchestrator.cwd = makeTempDir();
+    orchestrator.config = makeConfig() as any;
+    registerCommandHandlers(orchestrator);
+
+    const ctx = makeCtx();
+
+    const ppNext = pi._commands.get("pp:next");
+    await ppNext!.handler(undefined, ctx);
+
+    expect(ctx.ui.notify).toHaveBeenCalledWith("No active task.", "error");
+    expect(runUserGateDialog).not.toHaveBeenCalled();
+  });
+
+  it("passes standard summary text to user gate dialog", async () => {
+    const pi = makePi();
+    const orchestrator = new Orchestrator(pi as any);
+    const taskDir = makeTempDir();
+    orchestrator.cwd = taskDir;
+    orchestrator.config = makeConfig() as any;
+    orchestrator.active = makeActiveTask(taskDir);
+    registerCommandHandlers(orchestrator);
+
+    const ctx = makeCtx();
+
+    const ppNext = pi._commands.get("pp:next");
+    await ppNext!.handler(undefined, ctx);
+
+    expect(runUserGateDialog).toHaveBeenCalledWith(orchestrator, ctx, "Choose next action");
+  });
+});

package/extensions/orchestrator/command-handlers.ts

@@ -0,0 +1,116 @@
+import { unregisterAgentDefinitions } from "./agents/registry.js";
+import { runAfterImplement } from "./commands.js";
+import { nextPhase, validateExitCriteria } from "./phases/machine.js";
+import { spawnPlanners } from "./phases/planning.js";
+import { Orchestrator } from "./orchestrator.js";
+import { saveTask } from "./state.js";
+
+export async function transitionToNextPhase(
+  orchestrator: Orchestrator,
+  ctx: any,
+): Promise<{ ok: boolean; error?: string }> {
+  if (!orchestrator.active) return { ok: false, error: "No active task." };
+
+  const currentPhase = orchestrator.active.state.phase;
+  if (currentPhase === "done") return { ok: false, error: "Task is already done." };
+
+  const exitCheck = validateExitCriteria(orchestrator.active.dir, orchestrator.active.type, currentPhase);
+  if (!exitCheck.ok) {
+    return { ok: false, error: exitCheck.reason };
+  }
+
+  if (orchestrator.phaseStartTime > 0) {
+    const elapsed = Math.round((Date.now() - orchestrator.phaseStartTime) / 1000);
+    const min = Math.floor(elapsed / 60);
+    const sec = elapsed % 60;
+    ctx.ui.notify(`Phase "${currentPhase}" completed in ${min > 0 ? `${min}m ${sec}s` : `${sec}s`}`, "info");
+  }
+
+  const next = nextPhase(orchestrator.active.type, currentPhase);
+  if (!next) return { ok: false, error: "No next phase available." };
+
+  if (currentPhase === "implement") {
+    const afterResults = runAfterImplement(orchestrator.config, orchestrator.cwd);
+    const failures = afterResults.filter((r) => !r.ok);
+    if (failures.length > 0) {
+      const failureText = failures.map((f) => `${f.command}: ${f.output}`).join("\n");
+      return { ok: false, error: `afterImplement commands failed:\n${failureText}\n\nFix these issues before advancing.` };
+    }
+  }
+
+  orchestrator.active.state.phase = next;
+  if (next !== "done") {
+    orchestrator.active.state.reviewCycle = null;
+    orchestrator.active.state.reviewPass = 0;
+    orchestrator.active.state.reviewPassByKind = {};
+    orchestrator.active.reviewPass = 0;
+  }
+  if (next === "plan") {
+    orchestrator.active.state.step = "spawn_planners";
+  } else if (next === "implement") {
+    orchestrator.active.state.step = "llm_work";
+  } else if (next === "brainstorm" || next === "debug") {
+    orchestrator.active.state.step = "llm_work";
+  } else if (next === "done") {
+    orchestrator.active.state.step = null;
+  }
+  saveTask(orchestrator.active.dir, orchestrator.active.state);
+
+  if (next === "done") {
+    const name = orchestrator.active.description;
+    const type = orchestrator.active.type;
+    orchestrator.taskDoneCompactionPending = true;
+    orchestrator.taskDoneCompactionSummary = `Task "${name}" (${type}) completed.`;
+
+    orchestrator.abortAllSubagents();
+    unregisterAgentDefinitions(orchestrator.pi);
+    await orchestrator.cleanupActive();
+    orchestrator.updateStatus(ctx);
+    ctx.compact();
+    ctx.ui.notify("Task completed!", "info");
+    return { ok: true };
+  }
+
+  orchestrator.updateStatus(ctx);
+
+  if (next === "plan") {
+    orchestrator.active.state.step = "await_planners";
+    saveTask(orchestrator.active.dir, orchestrator.active.state);
+  }
+
+  orchestrator.compactAndTransition(ctx, orchestrator.active.dir, orchestrator.active.state.phase);
+
+  if (next === "plan") {
+    orchestrator.pendingSubagentSpawns = Object.values(orchestrator.config.planners).filter((v) => v.enabled).length;
+    orchestrator.failedPlannerVariants = [];
+    spawnPlanners(orchestrator.pi, orchestrator.cwd, orchestrator.active.dir, orchestrator.active.taskId, orchestrator.config).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;
+    }).catch((err) => {
+      orchestrator.pendingSubagentSpawns = 0;
+      console.error(`[pi-pi] spawnPlanners failed: ${err.message}`);
+    });
+  }
+
+  return { ok: true };
+}
+
+export function registerCommandHandlers(orchestrator: Orchestrator): void {
+  const pi = orchestrator.pi;
+  orchestrator.transitionToNextPhase = (ctx: any) => transitionToNextPhase(orchestrator, ctx);
+
+  pi.registerCommand("pp", {
+    description: "Open pi-pi task menu",
+    handler: async (_args, ctx) => {
+      const { showPpMenu } = await import("./pp-menu.js");
+      const text = await showPpMenu(orchestrator, ctx, "command");
+      if (text) {
+        pi.sendUserMessage(`[PI-PI] ${text}`);
+      }
+    },
+  });
+}