@ilya-lesikov/pi-pi 0.5.0 → 0.7.0

package/extensions/orchestrator/state.ts

@@ -1,38 +1,63 @@
-import { appendFileSync, readFileSync, writeFileSync, existsSync, mkdirSync, readdirSync } from "fs";
-import { join, basename, resolve } from "path";
+import { readFileSync, writeFileSync, existsSync, mkdirSync, readdirSync } from "fs";
+import { join, basename, resolve, relative, isAbsolute, sep } from "path";
 import lockfile from "proper-lockfile";
+import { normalizeRepoPath, type RepoInfo } from "./repo-utils.js";
+import { getLogger } from "./log.js";
 
 function getLockfileFs(): typeof import("fs") | undefined {
   try {
     const fs = require("fs");
     fs.statSync(process.cwd());
     return fs;
-  } catch {
+  } catch (err: any) {
+    getLogger().debug({ s: "state", err: err?.message }, "getLockfileFs unavailable");
     return undefined;
   }
 }
 import type { TimeoutConfig } from "./config.js";
 
-export type TaskType = "implement" | "debug" | "brainstorm" | "review";
+export type TaskMode = "guided" | "autonomous";
+
+export interface AutonomousPhaseConfig {
+  plannerPreset?: string;
+  reviewPreset?: string;
+  maxReviewPasses: number;
+}
+
+export interface AutonomousConfig {
+  phases: Record<string, AutonomousPhaseConfig>;
+}
+
+export type TaskType = "implement" | "debug" | "brainstorm" | "review" | "quick";
 
 export type ImplementPhase = "brainstorm" | "plan" | "implement" | "done";
 export type DebugPhase = "debug" | "plan" | "implement" | "done";
 export type BrainstormPhase = "brainstorm" | "plan" | "implement" | "done";
 export type ReviewPhase = "review" | "plan" | "implement" | "done";
-export type Phase = ImplementPhase | DebugPhase | BrainstormPhase | ReviewPhase;
+export type QuickPhase = "quick";
+export type Phase = ImplementPhase | DebugPhase | BrainstormPhase | ReviewPhase | QuickPhase;
 
 export interface TaskState {
   phase: Phase;
+  initialPhase?: string;
   step: string | null;
   reviewCycle: { kind: string; step: string; pass: number } | null;
   reviewPass: number;
-  reviewPassByKind?: Record<string, number>;
+  reviewPassByKind?: Record<string, Record<string, number>>;
+  reviewApprovedClean?: boolean;
   modifiedFiles?: string[];
-  repoCwd?: string;
+  committedFiles?: string[];
+  repos?: RepoInfo[];
   from: string | null;
   description: string;
   startedAt: string;
-
+  activePlannerPreset?: string;
+  activeReviewPreset?: string;
+  mode?: TaskMode;
+  effectiveMode?: TaskMode;
+  autonomousConfig?: AutonomousConfig;
+  plannerFailureAutoRetried?: boolean;
+  reviewerFailureAutoRetried?: boolean;
 }
 
 export interface TaskInfo {
@@ -49,7 +74,27 @@ function taskStatePath(taskDir: string): string {
   return join(taskDir, "state.json");
 }
 
-export function createTask(cwd: string, type: TaskType, description: string): string {
+export function getFirstPhase(type: TaskType): Exclude<Phase, "done"> {
+  if (type === "implement" || type === "brainstorm") return "brainstorm";
+  if (type === "debug") return "debug";
+  if (type === "review") return "review";
+  return "quick";
+}
+
+export function getEffectiveMode(state: TaskState): TaskMode | undefined {
+  return state.effectiveMode ?? state.mode;
+}
+
+// The research first phases (brainstorm/debug/review) are always interactive: the user
+// drives them, so they never inherit the task's autonomous mode even when one is set.
+// plan/implement are autonomous-capable regardless of whether they are the task's initial phase.
+export function getEffectivePhaseMode(state: TaskState): TaskMode {
+  if (state.phase === "brainstorm" || state.phase === "debug" || state.phase === "review") return "guided";
+  return getEffectiveMode(state) ?? "guided";
+}
+
+export function createTask(cwd: string, type: TaskType, description: string, mode?: TaskMode): string {
+  const log = getLogger();
   const id = crypto.randomUUID().slice(0, 12);
   const safeName = description
     .toLowerCase()
@@ -62,16 +107,22 @@ export function createTask(cwd: string, type: TaskType, description: string): st
   mkdirSync(taskDir, { recursive: true });
 
   const state: TaskState = {
-    phase: type === "implement" ? "brainstorm" : type === "debug" ? "debug" : type === "review" ? "review" : "brainstorm",
+    phase: getFirstPhase(type),
+    initialPhase: getFirstPhase(type),
     step: "llm_work",
     reviewCycle: null,
     reviewPass: 0,
+    repos: [{ path: normalizeRepoPath(cwd), isRoot: true }],
     from: null,
     description,
     startedAt: new Date().toISOString(),
+    mode,
+    plannerFailureAutoRetried: false,
+    reviewerFailureAutoRetried: false,
   };
 
   writeFileSync(taskStatePath(taskDir), JSON.stringify(state, null, 2) + "\n", "utf-8");
+  log.info({ s: "task", taskDir, type, description, phase: state.phase }, "task created");
   return taskDir;
 }
 
@@ -80,6 +131,23 @@ export function loadTask(taskDir: string): TaskState {
   const raw = readFileSync(sp, "utf-8");
   try {
     const state = JSON.parse(raw) as TaskState;
+    if ((state as any).phase === "planning") {
+      state.phase = "plan";
+    }
+    if (!state.initialPhase) {
+      state.initialPhase = state.phase;
+    }
+    if (state.plannerFailureAutoRetried === undefined) {
+      state.plannerFailureAutoRetried = false;
+    }
+    if (state.reviewerFailureAutoRetried === undefined) {
+      state.reviewerFailureAutoRetried = false;
+    }
+    if ((state as any).repoCwd && (!state.repos || state.repos.length === 0)) {
+      state.repos = [{ path: (state as any).repoCwd, isRoot: false }];
+    }
+    if (!state.repos) state.repos = [];
+    delete (state as any).repoCwd;
     return state;
   } catch (err: any) {
     throw new Error(`Failed to parse ${sp}: ${err.message}`);
@@ -87,6 +155,7 @@ export function loadTask(taskDir: string): TaskState {
 }
 
 export function saveTask(taskDir: string, state: TaskState): void {
+  getLogger().debug({ s: "task", taskDir, phase: state.phase, step: state.step }, "saving task state");
   writeFileSync(taskStatePath(taskDir), JSON.stringify(state, null, 2) + "\n", "utf-8");
 }
 
@@ -94,7 +163,7 @@ export function listTasks(cwd: string, type?: TaskType): TaskInfo[] {
   const base = stateDir(cwd);
   if (!existsSync(base)) return [];
 
-  const types: TaskType[] = type ? [type] : ["implement", "debug", "brainstorm", "review"];
+  const types: TaskType[] = type ? [type] : ["implement", "debug", "brainstorm", "review", "quick"];
   const results: TaskInfo[] = [];
 
   for (const t of types) {
@@ -113,7 +182,7 @@ export function listTasks(cwd: string, type?: TaskType): TaskInfo[] {
           results.push({ dir, state, type: t });
         }
       } catch {
-        console.error(`[pi-pi] Skipping corrupt task at ${dir}`);
+        getLogger().warn({ s: "state", dir }, "skipping corrupt task");
       }
     }
   }
@@ -135,11 +204,11 @@ export async function lockTask(taskDir: string, timeouts: TimeoutConfig): Promis
   const lockFs = getLockfileFs();
   const release = await lockfile.lock(sp, {
     ...(lockFs && { fs: lockFs }),
-    stale: timeouts.lockStale,
-    update: timeouts.lockUpdate,
+    stale: timeouts.taskLockStale,
+    update: timeouts.taskLockRefresh,
     retries: { retries: 3, minTimeout: 200, maxTimeout: 1000 },
     onCompromised: (err: Error) => {
-      console.error(`[pi-pi] Lock compromised for ${sp}: ${err.message}`);
+      getLogger().error({ s: "state", path: sp, err: err.message }, "lock compromised");
     },
   });
   return release;
@@ -158,7 +227,7 @@ export function getActiveTask(cwd: string, lockStale?: number): TaskInfo | null
         unlocked.push(task);
       }
     } catch {
-      console.error(`[pi-pi] Failed to check lock for ${task.dir}`);
+      getLogger().warn({ s: "state", dir: task.dir }, "failed to check lock");
     }
   }
 
@@ -173,8 +242,9 @@ export function validateFromPath(cwd: string, fromPath: string): { ok: true; dir
 
   const stateRoot = resolve(stateDir(cwd));
   const resolved = resolve(stateRoot, fromPath);
+  const rel = relative(stateRoot, resolved);
 
-  if (resolved !== stateRoot && !resolved.startsWith(stateRoot + "/")) {
+  if (rel === ".." || rel.startsWith(`..${sep}`) || isAbsolute(rel)) {
     return { ok: false, reason: "Path escapes .pp/state/ directory" };
   }
 
@@ -192,30 +262,51 @@ export function validateFromPath(cwd: string, fromPath: string): { ok: true; dir
 
 export function taskName(taskDir: string): string {
   try {
-    const state = loadTask(taskDir);
-    let desc = state.description ?? "";
-
-    if (["implement", "debug", "brainstorm", "review"].includes(desc)) {
-      const urPath = join(taskDir, "USER_REQUEST.md");
-      if (existsSync(urPath)) {
-        const content = readFileSync(urPath, "utf-8");
-        const lines = content.split("\n").map((l) => l.trim()).filter((l) => l.length > 0);
-        const firstContent = lines.find((l) => !l.startsWith("#"));
-        if (firstContent) desc = firstContent;
-      }
-    }
+    return taskNameFromState(taskDir, loadTask(taskDir));
+  } catch {
+    getLogger().warn({ s: "state", taskDir }, "failed to read task name");
+    return dirSlugName(taskDir);
+  }
+}
 
-    if (desc) {
-      desc = desc.replace(/\s+/g, " ").trim();
-      if (desc.length > 60) desc = desc.slice(0, 57) + "...";
-      return desc;
+// Same as taskName but reuses an already-loaded TaskState (avoids re-reading
+// state.json per resume-menu entry). The only per-entry disk read is the
+// USER_REQUEST.md fallback, which is unavoidable for generic descriptions.
+export function taskNameFromState(taskDir: string, state: TaskState): string {
+  let desc = state.description ?? "";
+
+  if (["implement", "debug", "brainstorm", "review", "quick"].includes(desc)) {
+    const urPath = join(taskDir, "USER_REQUEST.md");
+    if (existsSync(urPath)) {
+      const content = readFileSync(urPath, "utf-8");
+      const lines = content.split("\n").map((l) => l.trim()).filter((l) => l.length > 0);
+      const firstContent = lines.find((l) => !l.startsWith("#"));
+      if (firstContent) desc = firstContent;
     }
-  } catch {
-    console.error(`[pi-pi] Failed to read task name from ${taskDir}`);
   }
+
+  if (desc) {
+    desc = desc.replace(/\s+/g, " ").trim();
+    if (desc.length > 60) desc = desc.slice(0, 57) + "...";
+    return desc;
+  }
+  return dirSlugName(taskDir);
+}
+
+function dirSlugName(taskDir: string): string {
+  const dir = basename(taskDir);
+  const idx = dir.indexOf("_");
+  const slug = idx >= 0 ? dir.slice(idx + 1) : dir;
+  return slug.replace(/-/g, " ");
+}
+
+// The task's short id is the leading segment of its dir name (`${id}_${slug}`),
+// where id is a 12-char uuid slice from createTask. Used to disambiguate
+// otherwise-identical resume-menu titles.
+export function taskShortId(taskDir: string): string {
   const dir = basename(taskDir);
-  const match = dir.match(/^\d+_(.+)$/);
-  return match ? match[1].replace(/-/g, " ") : dir;
+  const idPart = dir.split("_", 1)[0] ?? dir;
+  return idPart.slice(0, 6);
 }
 
 export function taskAge(state: TaskState): string {
@@ -227,10 +318,3 @@ export function taskAge(state: TaskState): string {
   if (hours < 24) return `${hours}h`;
   return `${Math.floor(hours / 24)}d`;
 }
-
-export function appendTaskLog(taskDir: string, fileName: string, entry: Record<string, unknown>): string {
-  mkdirSync(taskDir, { recursive: true });
-  const filePath = join(taskDir, fileName);
-  appendFileSync(filePath, JSON.stringify(entry) + "\n", "utf-8");
-  return filePath;
-}

package/extensions/orchestrator/subagent-session-marker.test.ts

@@ -0,0 +1,36 @@
+import { describe, it, expect } from "vitest";
+
+// Documents the shared contract for Symbol.for("pi-pi:subagent-session") between
+// extensions/orchestrator/index.ts (writer) and 3p/pi-subagents/src/agent-runner.ts
+// (depth tracker). The canonical shape is { depth: number }; a legacy boolean true
+// must still be tolerated as depth 1. This mirrors agent-runner's read so a future
+// shape change on either side is caught.
+function readDepth(marker: unknown): number {
+  return typeof marker === "object" && marker !== null
+    ? ((marker as { depth?: number }).depth ?? 0)
+    : marker
+      ? 1
+      : 0;
+}
+
+describe("subagent-session marker contract", () => {
+  it("treats the orchestrator's { depth: 1 } write as depth 1 (truthy, not reset to 0)", () => {
+    const marker = { depth: 1 };
+    expect(readDepth(marker)).toBe(1);
+    expect(Boolean(marker)).toBe(true);
+  });
+
+  it("still tolerates a legacy boolean marker as depth 1", () => {
+    expect(readDepth(true)).toBe(1);
+  });
+
+  it("reports depth 0 when no marker is set", () => {
+    expect(readDepth(undefined)).toBe(0);
+  });
+
+  it("increments nesting from an existing object marker", () => {
+    const previous = { depth: 2 };
+    const next = { depth: readDepth(previous) + 1 };
+    expect(next.depth).toBe(3);
+  });
+});

package/extensions/orchestrator/test-helpers.ts

@@ -0,0 +1,229 @@
+import { expect } from "vitest";
+
+export type TextMatch = string | RegExp | ((value: string) => boolean);
+
+export interface MenuExpectation {
+  question?: TextMatch;
+  options?: {
+    exact?: TextMatch[];
+    include?: TextMatch[];
+    exclude?: TextMatch[];
+  };
+  // When set, the harness returns a cancel (as askUser/isCancel would on ESC)
+  // instead of choosing an option. `choose` is ignored in that case.
+  cancel?: "user" | "timeout" | "signal";
+  choose?: TextMatch | ((options: string[]) => string);
+}
+
+export interface MenuTranscriptEntry {
+  question: string;
+  options: Array<{ title: string; description?: string }>;
+  chosen: string;
+}
+
+export interface AskUserHarness {
+  transcript: MenuTranscriptEntry[];
+  expect(step: MenuExpectation): AskUserHarness;
+  handle(opts: any): Promise<{ kind: "selection"; selections: [string] } | { __cancel: true; reason: "user" | "timeout" | "signal" }>;
+  assertDone(): void;
+}
+
+interface MenuOption {
+  title: string;
+  description?: string;
+}
+
+function escapeRegExp(value: string): string {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+function stringifyMatcher(matcher: TextMatch | undefined): string {
+  if (matcher === undefined) return "<none>";
+  if (typeof matcher === "string") return JSON.stringify(matcher);
+  if (matcher instanceof RegExp) return matcher.toString();
+  return "<function>";
+}
+
+function matchText(matcher: TextMatch, value: string): boolean {
+  if (typeof matcher === "string") return value === matcher;
+  if (matcher instanceof RegExp) return matcher.test(value);
+  return matcher(value);
+}
+
+function renderMenu(question: string, options: MenuOption[]): string {
+  const lines = options.map((option) => {
+    if (!option.description) return `- ${option.title}`;
+    return `- ${option.title} — ${option.description}`;
+  });
+  return `question=${JSON.stringify(question)}\noptions:\n${lines.join("\n")}`;
+}
+
+export function createAskUserHarness(): AskUserHarness {
+  const queue: MenuExpectation[] = [];
+  const transcript: MenuTranscriptEntry[] = [];
+
+  return {
+    transcript,
+    expect(step: MenuExpectation) {
+      queue.push(step);
+      return this;
+    },
+    async handle(opts: any) {
+      const question = String(opts?.question ?? "");
+      const options: MenuOption[] = (Array.isArray(opts?.options) ? opts.options : []).map((option: any): MenuOption => {
+        if (typeof option === "string") return { title: option };
+        return {
+          title: String(option?.title ?? ""),
+          description: option?.description === undefined ? undefined : String(option.description),
+        };
+      });
+      const titles: string[] = options.map((option: MenuOption) => option.title);
+
+      if (queue.length === 0) {
+        throw new Error(`Unexpected menu: ${renderMenu(question, options)}`);
+      }
+
+      const expected = queue.shift()!;
+
+      if (expected.question && !matchText(expected.question, question)) {
+        throw new Error(
+          `Question mismatch: expected ${stringifyMatcher(expected.question)}, actual ${JSON.stringify(question)}\n${renderMenu(question, options)}`,
+        );
+      }
+
+      if (expected.options?.include) {
+        for (const include of expected.options.include) {
+          const found = titles.some((title: string) => matchText(include, title));
+          if (!found) {
+            throw new Error(
+              `Missing expected option ${stringifyMatcher(include)}\n${renderMenu(question, options)}`,
+            );
+          }
+        }
+      }
+
+      if (expected.options?.exclude) {
+        for (const exclude of expected.options.exclude) {
+          const found = titles.some((title: string) => matchText(exclude, title));
+          if (found) {
+            throw new Error(
+              `Found excluded option ${stringifyMatcher(exclude)}\n${renderMenu(question, options)}`,
+            );
+          }
+        }
+      }
+
+      if (expected.options?.exact) {
+        expect(titles.length).toBe(expected.options.exact.length);
+        for (let i = 0; i < expected.options.exact.length; i += 1) {
+          const matcher = expected.options.exact[i]!;
+          const actual = titles[i] ?? "";
+          if (!matchText(matcher, actual)) {
+            throw new Error(
+              `Exact options mismatch at index ${i}: expected ${stringifyMatcher(matcher)}, actual ${JSON.stringify(actual)}\n${renderMenu(question, options)}`,
+            );
+          }
+        }
+      }
+
+      if (expected.cancel) {
+        transcript.push({ question, options, chosen: `<cancel:${expected.cancel}>` });
+        return { __cancel: true, reason: expected.cancel };
+      }
+
+      if (expected.choose === undefined) {
+        throw new Error(`Menu expectation is missing a chooser\n${renderMenu(question, options)}`);
+      }
+
+      let chosen: string;
+      if (typeof expected.choose === "function") {
+        const maybeChoice = (expected.choose as (options: string[]) => unknown)(titles);
+        if (typeof maybeChoice === "string") {
+          chosen = maybeChoice;
+        } else {
+          const matcher = expected.choose as (value: string) => boolean;
+          const picked = titles.find((title: string) => matcher(title));
+          if (!picked) {
+            throw new Error(`No option matched chooser function\n${renderMenu(question, options)}`);
+          }
+          chosen = picked;
+        }
+      } else {
+        const picked = titles.find((title: string) => matchText(expected.choose as TextMatch, title));
+        if (!picked) {
+          throw new Error(
+            `No option matched chooser ${stringifyMatcher(expected.choose as TextMatch)}\n${renderMenu(question, options)}`,
+          );
+        }
+        chosen = picked;
+      }
+
+      if (!titles.includes(chosen)) {
+        throw new Error(`Chosen option not found: ${JSON.stringify(chosen)}\n${renderMenu(question, options)}`);
+      }
+
+      transcript.push({ question, options, chosen });
+
+      return { kind: "selection", selections: [chosen] };
+    },
+    assertDone() {
+      if (queue.length > 0) {
+        const next = queue[0]!;
+        throw new Error(
+          `Unconsumed menu expectations: ${queue.length}. Next expected question=${stringifyMatcher(next.question)} choose=${stringifyMatcher(
+            typeof next.choose === "function" ? undefined : next.choose,
+          )}`,
+        );
+      }
+    },
+  };
+}
+
+export const m = {
+  taskMenu: (type: string, phase: string) =>
+    (q: string) => q.includes(`Task: ${type}`) && q.includes(`Phase: ${phase}`),
+  anyTaskMenu: (q: string) => q.startsWith("/pp"),
+  preset: (name: string) => new RegExp(`^${escapeRegExp(name)}(?: \\[default\\])?$`),
+  autoReview: /^Auto review(?: \(pass \d+\))?$/,
+};
+
+export function expectActiveTaskNext(menu: AskUserHarness, choose: string): void {
+  menu.expect({ question: m.anyTaskMenu, options: { include: ["Next"] }, choose: "Next" });
+  menu.expect({ question: "Next", options: { include: [choose] }, choose });
+}
+
+export function expectBrainstormToPlan(menu: AskUserHarness): void {
+  expectActiveTaskNext(menu, "Continue to plan & implement");
+  menu.expect({ question: "Planner preset", options: { include: [m.preset("regular"), "Back"] }, choose: m.preset("regular") });
+}
+
+export function expectPlanToImplement(menu: AskUserHarness): void {
+  expectActiveTaskNext(menu, "Continue to implement");
+}
+
+export function expectImplementToDone(menu: AskUserHarness): void {
+  expectActiveTaskNext(menu, "Complete");
+}
+
+export function expectQuickMenu(menu: AskUserHarness, choose: string): void {
+  menu.expect({ question: m.anyTaskMenu, options: { include: [choose] }, choose });
+}
+
+export function expectReviewAuto(menu: AskUserHarness, preset = "regular"): void {
+  menu.expect({ question: m.anyTaskMenu, options: { include: ["Review"] }, choose: "Review" });
+  menu.expect({ question: "Review", options: { include: [m.autoReview] }, choose: m.autoReview });
+  menu.expect({ question: "Review preset", options: { include: [m.preset(preset), "Back"] }, choose: m.preset(preset) });
+}
+
+export function expectReviewOnMyOwn(menu: AskUserHarness): void {
+  menu.expect({ question: m.anyTaskMenu, options: { include: ["Review"] }, choose: "Review" });
+  menu.expect({ question: "Review", options: { include: ["Review on my own"] }, choose: "Review on my own" });
+}
+
+export function expectPpStartImplementAutonomous(menu: AskUserHarness): void {
+  menu.expect({ question: "/pp", options: { include: ["Task"] }, choose: "Task" });
+  menu.expect({ question: "Task", options: { include: ["Implement"] }, choose: "Implement" });
+  menu.expect({ question: "Implement", options: { include: ["New"] }, choose: "New" });
+  menu.expect({ question: "Mode", options: { include: ["Guided", "Autonomous", "Back"] }, choose: "Autonomous" });
+  menu.expect({ question: "Autonomous", options: { include: ["Start", "Back"] }, choose: "Start" });
+}

package/extensions/orchestrator/tracer.test.ts

@@ -0,0 +1,132 @@
+import { existsSync, mkdtempSync, readFileSync, rmSync, utimesSync } from "fs";
+import { tmpdir } from "os";
+import { join } from "path";
+import { afterEach, describe, expect, it } from "vitest";
+import { initTracer, finalizeTracer, getTracer } from "./tracer.js";
+
+const tempDirs: string[] = [];
+
+function makeTempDir(): string {
+  const dir = mkdtempSync(join(tmpdir(), "pi-pi-tracer-test-"));
+  tempDirs.push(dir);
+  return dir;
+}
+
+function readLines(file: string): Record<string, any>[] {
+  if (!existsSync(file)) return [];
+  return readFileSync(file, "utf-8")
+    .split("\n")
+    .filter((l) => l.trim().length > 0)
+    .map((l) => JSON.parse(l));
+}
+
+afterEach(() => {
+  finalizeTracer();
+  for (const dir of tempDirs.splice(0)) {
+    try {
+      rmSync(dir, { recursive: true, force: true });
+    } catch {}
+  }
+});
+
+describe("tracer", () => {
+  it("is a no-op when not initialized", () => {
+    expect(getTracer()).toBeUndefined();
+  });
+
+  it("creates per-session dir with main.jsonl and writes main events", () => {
+    const ppDir = join(makeTempDir(), ".pp");
+    initTracer(ppDir, "sess-abc");
+    const tracer = getTracer();
+    expect(tracer).toBeDefined();
+
+    tracer!.traceMain("before_agent_start", { prompt: "hello", systemPrompt: "sys" });
+    tracer!.traceMain("tool_execution_end", { toolCallId: "t1", result: { ok: true }, isError: false });
+
+    const dir = join(ppDir, "logs", "traces", "sess-abc");
+    expect(existsSync(join(dir, "main.jsonl"))).toBe(true);
+
+    const lines = readLines(join(dir, "main.jsonl"));
+    expect(lines[0].kind).toBe("before_agent_start");
+    expect(lines[0].prompt).toBe("hello");
+    expect(lines[0].systemPrompt).toBe("sys");
+    expect(lines[1].kind).toBe("tool_execution_end");
+    expect(lines[1].result).toEqual({ ok: true });
+  });
+
+  it("writes one file per subagent keyed by id, with prompts and full payloads", () => {
+    const ppDir = join(makeTempDir(), ".pp");
+    initTracer(ppDir, "sess-1");
+    const tracer = getTracer()!;
+
+    tracer.openSubagent({
+      subagentId: "agent-1",
+      type: "Explore",
+      description: "find stuff",
+      parentToolCallId: "call-9",
+      parentSubagentId: "root-agent",
+      depth: 2,
+      systemPrompt: "sub-sys",
+      effectivePrompt: "do the thing",
+    });
+    tracer.traceSubagent("agent-1", "tool_execution_start", { toolCallId: "x", toolName: "grep", args: { pattern: "foo" } });
+
+    const dir = join(ppDir, "logs", "traces", "sess-1");
+    const subLines = readLines(join(dir, "agent-1.jsonl"));
+    expect(subLines[0].kind).toBe("subagent_open");
+    expect(subLines[0].systemPrompt).toBe("sub-sys");
+    expect(subLines[0].effectivePrompt).toBe("do the thing");
+    expect(subLines[0].parentToolCallId).toBe("call-9");
+    expect(subLines[0].parentSubagentId).toBe("root-agent");
+    expect(subLines[0].depth).toBe(2);
+    expect(subLines[1].kind).toBe("tool_execution_start");
+    expect(subLines[1].args).toEqual({ pattern: "foo" });
+
+    const mainLines = readLines(join(dir, "main.jsonl"));
+    const spawned = mainLines.find((l) => l.kind === "subagent_spawned" && l.subagentId === "agent-1");
+    expect(spawned).toBeDefined();
+    expect(spawned!.parentToolCallId).toBe("call-9");
+    expect(spawned!.parentSubagentId).toBe("root-agent");
+  });
+
+  it("keeps concurrent subagents in separate files", () => {
+    const ppDir = join(makeTempDir(), ".pp");
+    initTracer(ppDir, "sess-2");
+    const tracer = getTracer()!;
+
+    tracer.openSubagent({ subagentId: "a", depth: 1 });
+    tracer.openSubagent({ subagentId: "b", depth: 1 });
+    tracer.traceSubagent("a", "turn_end", { turnIndex: 0 });
+    tracer.traceSubagent("b", "turn_end", { turnIndex: 0 });
+
+    const dir = join(ppDir, "logs", "traces", "sess-2");
+    expect(readLines(join(dir, "a.jsonl")).some((l) => l.kind === "turn_end")).toBe(true);
+    expect(readLines(join(dir, "b.jsonl")).some((l) => l.kind === "turn_end")).toBe(true);
+    expect(readLines(join(dir, "a.jsonl")).some((l) => l.subagentId === "b")).toBe(false);
+  });
+
+  it("finalize writes session_finalized and clears the tracer", () => {
+    const ppDir = join(makeTempDir(), ".pp");
+    initTracer(ppDir, "sess-3");
+    const dir = join(ppDir, "logs", "traces", "sess-3");
+    finalizeTracer();
+    expect(getTracer()).toBeUndefined();
+    expect(readLines(join(dir, "main.jsonl")).some((l) => l.kind === "session_finalized")).toBe(true);
+  });
+
+  it("cleans up trace dirs older than 7 days", () => {
+    const ppDir = join(makeTempDir(), ".pp");
+    initTracer(ppDir, "old-session");
+    finalizeTracer();
+    const tracesRoot = join(ppDir, "logs", "traces");
+    const oldDir = join(tracesRoot, "old-session");
+    expect(existsSync(oldDir)).toBe(true);
+
+    const past = (Date.now() - 8 * 24 * 60 * 60 * 1000) / 1000;
+    utimesSync(oldDir, past, past);
+
+    initTracer(ppDir, "new-session");
+    expect(existsSync(oldDir)).toBe(false);
+    expect(existsSync(join(tracesRoot, "new-session"))).toBe(true);
+  });
+});