pi-extensible-workflows 1.0.0 → 2.0.0

package/src/persistence.ts

@@ -1,5 +1,6 @@
 import { createHash, randomUUID } from "node:crypto";
 import { execFile } from "node:child_process";
+import { renameSync, rmSync, writeFileSync } from "node:fs";
 import { access, link, mkdir, open, readFile, readdir, rename, rm, stat, writeFile } from "node:fs/promises";
 import { basename, dirname, join, relative, resolve, sep } from "node:path";
 import { homedir } from "node:os";
@@ -25,6 +26,7 @@ export type PendingWorkflowDecision = BudgetApprovalRequest
 export type PersistedOwnershipNode = OwnershipRecord
 type Journal = { completed: Record<string, CompletedOperation>; awaiting?: Record<string, AwaitingCheckpoint>; decisions?: Record<string, PendingWorkflowDecision> };
 export interface WorktreeReference { owner: string; path: string; branch: string; cwd: string; base: string }
+export interface BorrowedWorktreeBinding { name: string; sourceRunId: string; owner: string }
 
 const execute = promisify(execFile);
 const gitIdentity = {
@@ -158,10 +160,28 @@ export function structuralPath(...names: string[]): string {
   return names.map((name) => encodeURIComponent(name)).join("/");
 }
 
-async function atomicJson(path: string, value: unknown): Promise<void> {
+export function atomicWriteFile(path: string, content: string): Promise<void>;
+export function atomicWriteFile(path: string, content: string, sync: true): void;
+export function atomicWriteFile(path: string, content: string, sync = false): Promise<void> | void {
   const temporary = `${path}.${String(process.pid)}.${randomUUID()}.tmp`;
-  await writeFile(temporary, `${JSON.stringify(value)}\n`, { encoding: "utf8", mode: 0o600 });
-  await rename(temporary, path);
+  if (sync) {
+    try {
+      writeFileSync(temporary, content, { encoding: "utf8", mode: 0o600 });
+      renameSync(temporary, path);
+    } catch (error) {
+      try { rmSync(temporary, { force: true }); } catch { /* Preserve the original write error. */ }
+      throw error;
+    }
+    return;
+  }
+  return writeFile(temporary, content, { encoding: "utf8", mode: 0o600 }).then(() => rename(temporary, path)).catch(async (error: unknown) => {
+    try { await rm(temporary, { force: true }); } catch { /* Preserve the original write error. */ }
+    throw error;
+  });
+}
+
+async function atomicJson(path: string, value: unknown): Promise<void> {
+  await atomicWriteFile(path, `${JSON.stringify(value)}\n`);
 }
 
 async function json<T>(path: string): Promise<T> { return JSON.parse(await readFile(path, "utf8")) as T; }
@@ -172,12 +192,13 @@ export class RunStore {
   // ponytail: serializes one RunStore instance; cross-process run sharing remains unsupported.
   private stateWrite: Promise<void> = Promise.resolve();
   private worktreeWrite: Promise<void> = Promise.resolve();
+  private borrowedWorktreeWrite: Promise<void> = Promise.resolve();
   private snapshotWrite: Promise<void> = Promise.resolve();
   private launchSnapshotWrite: Promise<void> = Promise.resolve();
   // ponytail: the session lease prevents concurrent RunStore writers for one run.
   private systemPromptWrite: Promise<void> = Promise.resolve();
   private conversationWrite: Promise<void> = Promise.resolve();
-  constructor(readonly cwd: string, readonly sessionId: string, readonly runId: string, home = homedir()) {
+  constructor(readonly cwd: string, readonly sessionId: string, readonly runId: string, readonly home = homedir()) {
     this.cwd = resolve(cwd);
     this.directory = join(runsDirectory(this.cwd, sessionId, home), safePart(runId));
   }
@@ -193,6 +214,7 @@ export class RunStore {
       await atomicJson(join(temporary, "journal.json"), { completed: {}, awaiting: {}, decisions: {} });
       await atomicJson(join(temporary, "ownership.json"), []);
       await atomicJson(join(temporary, "worktrees.json"), []);
+      await atomicJson(join(temporary, "borrowed-worktrees.json"), []);
       await atomicJson(join(temporary, "state.json"), run);
       await atomicJson(join(temporary, "system-prompts.json"), { version: 1, entries: [] });
       await atomicJson(join(temporary, "conversations.json"), { version: 1, conversations: {} });
@@ -245,7 +267,7 @@ export class RunStore {
   }
 
   async appendEvent(event: WorkflowRunEvent): Promise<void> {
-    await this.updateState((run) => ({ ...run, events: [...(run.events ?? []), ...(run.events?.some((current) => current.message === event.message) ? [] : [event])] }));
+    await this.updateState((run) => ({ ...run, events: [...(run.events ?? []), ...(run.events?.some((current) => current.type === event.type && current.message === event.message) ? [] : [event])] }));
   }
 
   async saveOwnership(nodes: readonly PersistedOwnershipNode[]): Promise<void> {
@@ -373,6 +395,24 @@ export class RunStore {
     return join(this.directory, `worktree-${key}.creating`);
   }
 
+  private namedWorktreeOwner(name: string): string {
+    if (!name.trim()) throw new WorkflowError("WORKTREE_FAILED", "Named worktree names must be non-empty");
+    return structuralPath("worktree", "named", name.trim());
+  }
+
+  private worktreeName(owner: string): string | undefined {
+    const prefix = `${structuralPath("worktree", "named")}/`;
+    if (!owner.startsWith(prefix)) return undefined;
+    const encoded = owner.slice(prefix.length);
+    if (!encoded || encoded.includes("/")) return undefined;
+    try {
+      const name = decodeURIComponent(encoded);
+      return name.trim() ? name : undefined;
+    } catch {
+      return undefined;
+    }
+  }
+
   private structuralWorktree(owner: string, record: unknown): WorktreeReference {
     if (!record || typeof record !== "object") throw new Error(`Invalid worktree record for ${owner}`);
     const candidate = record as Partial<WorktreeReference>;
@@ -383,6 +423,110 @@ export class RunStore {
     return candidate as WorktreeReference;
   }
 
+  private async borrowedWorktreeRecords(wait = true): Promise<readonly BorrowedWorktreeBinding[]> {
+    if (wait) await this.borrowedWorktreeWrite;
+    const records = await json<unknown[]>(join(this.directory, "borrowed-worktrees.json")).catch((error: unknown) => { if ((error as NodeJS.ErrnoException).code === "ENOENT") return []; throw error; });
+    if (!Array.isArray(records)) throw new WorkflowError("WORKTREE_FAILED", "Borrowed worktree bindings are invalid");
+    const seen = new Set<string>();
+    return records.map((record) => {
+      if (!record || typeof record !== "object") throw new WorkflowError("WORKTREE_FAILED", "Borrowed worktree binding is invalid");
+      const candidate = record as Partial<BorrowedWorktreeBinding>;
+      if (typeof candidate.name !== "string" || !candidate.name.trim() || candidate.name !== candidate.name.trim() || typeof candidate.sourceRunId !== "string" || !candidate.sourceRunId || typeof candidate.owner !== "string" || candidate.owner !== this.namedWorktreeOwner(candidate.name)) throw new WorkflowError("WORKTREE_FAILED", "Borrowed worktree binding is invalid");
+      if (seen.has(candidate.name)) throw new WorkflowError("WORKTREE_FAILED", `Duplicate borrowed worktree binding for ${candidate.name}`);
+      seen.add(candidate.name);
+      return { name: candidate.name, sourceRunId: candidate.sourceRunId, owner: candidate.owner };
+    });
+  }
+
+  async borrowedWorktrees(): Promise<readonly BorrowedWorktreeBinding[]> { return this.borrowedWorktreeRecords(); }
+
+  private async borrowedWorktree(name: string): Promise<BorrowedWorktreeBinding | undefined> {
+    return (await this.borrowedWorktreeRecords()).find((binding) => binding.name === name);
+  }
+
+  private async sourceRun(sourceRunId: string): Promise<RunStore> {
+    if (!sourceRunId || sourceRunId === this.runId) throw new WorkflowError("WORKTREE_FAILED", "Borrowed worktree source run is invalid");
+    const source = new RunStore(this.cwd, this.sessionId, sourceRunId, this.home);
+    try {
+      const loaded = await source.load();
+      if (!["completed", "failed", "stopped"].includes(loaded.run.state)) throw new Error(`Source run ${sourceRunId} is not terminal`);
+      return source;
+    } catch (error) {
+      if (error instanceof WorkflowError && error.code === "WORKTREE_FAILED") throw error;
+      throw new WorkflowError("WORKTREE_FAILED", error instanceof Error ? error.message : String(error));
+    }
+  }
+
+  async validateParentRun(parentRunId: string): Promise<void> { await this.sourceRun(parentRunId); }
+
+  private async ownedWorktree(owner: string, cwd?: string): Promise<WorktreeReference> {
+    const records = await json<unknown[]>(join(this.directory, "worktrees.json"));
+    const matches = records.filter((candidate) => candidate && typeof candidate === "object" && (candidate as Partial<WorktreeReference>).owner === owner);
+    if (matches.length !== 1) throw new Error(`Missing or duplicate worktree record for ${owner}`);
+    const record = this.structuralWorktree(owner, matches[0]);
+    if (cwd !== undefined && resolve(cwd) !== resolve(record.cwd)) throw new Error(`Invalid worktree record for ${owner}`);
+    await access(record.cwd);
+    return record;
+  }
+
+  private async resolveBorrowedWorktree(binding: BorrowedWorktreeBinding, seen: Set<string>): Promise<{ reference: WorktreeReference; sourceRunId: string; owner: string }> {
+    try {
+      const source = await this.sourceRun(binding.sourceRunId);
+      const resolved = await source.findNamedWorktree(binding.name, seen);
+      if (!resolved) throw new Error(`Missing named worktree ${binding.name} in source run ${binding.sourceRunId}`);
+      if (resolved.owner !== binding.owner) throw new Error(`Borrowed worktree binding does not match source owner for ${binding.name}`);
+      return resolved;
+    } catch (error) {
+      throw error instanceof WorkflowError && error.code === "WORKTREE_FAILED" ? error : new WorkflowError("WORKTREE_FAILED", error instanceof Error ? error.message : String(error));
+    }
+  }
+
+  private async findNamedWorktree(name: string, seen: Set<string> = new Set()): Promise<{ reference: WorktreeReference; sourceRunId: string; owner: string } | undefined> {
+    const owner = this.namedWorktreeOwner(name);
+    if (seen.has(this.runId)) throw new WorkflowError("WORKTREE_FAILED", "Borrowed worktree bindings contain a cycle");
+    const nextSeen = new Set(seen);
+    nextSeen.add(this.runId);
+    const binding = await this.borrowedWorktree(name);
+    if (binding) {
+      const loaded = await this.load();
+      if (loaded.run.parentRunId === undefined) throw new WorkflowError("WORKTREE_FAILED", `Borrowed worktree ${name} has no parent run`);
+      const parent = await this.sourceRun(loaded.run.parentRunId);
+      const resolved = await parent.findNamedWorktree(name, nextSeen);
+      if (!resolved || resolved.sourceRunId !== binding.sourceRunId || resolved.owner !== binding.owner) throw new WorkflowError("WORKTREE_FAILED", `Borrowed worktree binding for ${name} is not inherited from its parent run`);
+      return resolved;
+    }
+    const records = await json<unknown[]>(join(this.directory, "worktrees.json"));
+    const matches = records.filter((candidate) => candidate && typeof candidate === "object" && (candidate as Partial<WorktreeReference>).owner === owner);
+    if (matches.length === 0) return undefined;
+    try {
+      const reference = await this.ownedWorktree(owner);
+      return { reference, sourceRunId: this.runId, owner };
+    } catch (error) {
+      throw new WorkflowError("WORKTREE_FAILED", error instanceof Error ? error.message : String(error));
+    }
+  }
+
+  async resolveNamedWorktree(name: string, seen: Set<string> = new Set()): Promise<{ reference: WorktreeReference; sourceRunId: string; owner: string }> {
+    const resolved = await this.findNamedWorktree(name, seen);
+    if (!resolved) throw new WorkflowError("WORKTREE_FAILED", `Missing named worktree ${name}`);
+    return resolved;
+  }
+
+  async validateBorrowedWorktrees(): Promise<void> {
+    try {
+      const loaded = await this.load();
+      if (loaded.run.parentRunId !== undefined) await this.validateParentRun(loaded.run.parentRunId);
+      for (const binding of await this.borrowedWorktreeRecords()) await this.resolveBorrowedWorktree(binding, new Set([this.runId]));
+    } catch (error) {
+      throw error instanceof WorkflowError && error.code === "WORKTREE_FAILED" ? error : new WorkflowError("WORKTREE_FAILED", error instanceof Error ? error.message : String(error));
+    }
+  }
+
+  async ownsWorktree(owner: string): Promise<boolean> {
+    const records = await json<unknown[]>(join(this.directory, "worktrees.json"));
+    return records.filter((candidate) => candidate && typeof candidate === "object" && (candidate as Partial<WorktreeReference>).owner === owner).length === 1;
+  }
+
   private async cleanupMarker(markerPath: string): Promise<void> {
     let marker: Partial<{ owner: string; path: string; branch: string; base: string }>;
     try { marker = await json(markerPath); } catch { return; }
@@ -407,13 +551,14 @@ export class RunStore {
   async validateWorktree(owner: string, cwd?: string): Promise<WorktreeReference> {
     try {
       await this.load();
-      const records = await json<unknown[]>(join(this.directory, "worktrees.json"));
-      const matches = records.filter((candidate) => candidate && typeof candidate === "object" && (candidate as Partial<WorktreeReference>).owner === owner);
-      if (matches.length !== 1) throw new Error(`Missing or duplicate worktree record for ${owner}`);
-      const record = this.structuralWorktree(owner, matches[0]);
-      if (cwd !== undefined && resolve(cwd) !== resolve(record.cwd)) throw new Error(`Invalid worktree record for ${owner}`);
-      await access(record.cwd);
-      return record;
+      const name = this.worktreeName(owner);
+      const binding = name ? await this.borrowedWorktree(name) : undefined;
+      if (binding) {
+        const resolved = await this.resolveBorrowedWorktree(binding, new Set([this.runId]));
+        if (cwd !== undefined && resolve(cwd) !== resolve(resolved.reference.cwd)) throw new Error(`Invalid worktree record for ${owner}`);
+        return resolved.reference;
+      }
+      return await this.ownedWorktree(owner, cwd);
     } catch (error) {
       throw error instanceof WorkflowError && error.code === "WORKTREE_FAILED" ? error : new WorkflowError("WORKTREE_FAILED", error instanceof Error ? error.message : String(error));
     }
@@ -421,9 +566,19 @@ export class RunStore {
 
   async worktree(owner: string): Promise<WorktreeReference> {
     const write = this.worktreeWrite.then(async () => {
-      await this.load();
+      const loaded = await this.load();
       const recordsPath = join(this.directory, "worktrees.json");
       let records = await json<WorktreeReference[]>(recordsPath).catch((error: unknown) => { if ((error as NodeJS.ErrnoException).code === "ENOENT") return []; throw error; });
+      const name = this.worktreeName(owner);
+      const binding = name ? await this.borrowedWorktree(name) : undefined;
+      if (binding) return (await this.resolveBorrowedWorktree(binding, new Set([this.runId]))).reference;
+      if (name && loaded.run.parentRunId !== undefined) {
+        const resolved = await this.resolveNamedWorktreeFromParent(name, loaded.run.parentRunId);
+        if (resolved) {
+          await this.bindBorrowedWorktree({ name, sourceRunId: resolved.sourceRunId, owner: resolved.owner });
+          return resolved.reference;
+        }
+      }
       const existing = records.find((record) => record.owner === owner);
       if (existing) return this.validateWorktree(owner);
       const { path, branch } = this.expectedWorktree(owner);
@@ -469,6 +624,25 @@ export class RunStore {
     return write;
   }
 
+  private async resolveNamedWorktreeFromParent(name: string, parentRunId: string): Promise<{ reference: WorktreeReference; sourceRunId: string; owner: string } | undefined> {
+    const source = await this.sourceRun(parentRunId);
+    return source.findNamedWorktree(name, new Set([this.runId]));
+  }
+
+  private async bindBorrowedWorktree(binding: BorrowedWorktreeBinding): Promise<void> {
+    const write = this.borrowedWorktreeWrite.then(async () => {
+      const records = [...await this.borrowedWorktreeRecords(false)];
+      const existing = records.find((candidate) => candidate.name === binding.name);
+      if (existing) {
+        if (JSON.stringify(existing) !== JSON.stringify(binding)) throw new WorkflowError("WORKTREE_FAILED", `Borrowed worktree binding for ${binding.name} changed`);
+        return;
+      }
+      records.push(binding);
+      await atomicJson(join(this.directory, "borrowed-worktrees.json"), records);
+    });
+    this.borrowedWorktreeWrite = write.then(() => undefined, () => undefined);
+    await write;
+  }
   async snapshotWorktree(owner: string): Promise<string> {
     try {
       const write = this.snapshotWrite.then(async () => {
@@ -491,11 +665,13 @@ export class RunStore {
       throw error instanceof WorkflowError && error.code === "WORKTREE_FAILED" ? error : new WorkflowError("WORKTREE_FAILED", error instanceof Error ? error.message : String(error));
     }
   }
-
   async worktrees(): Promise<readonly WorktreeReference[]> {
     const records = await json<WorktreeReference[]>(join(this.directory, "worktrees.json")).catch((error: unknown) => { if ((error as NodeJS.ErrnoException).code === "ENOENT") return []; throw error; });
-    const validated = await Promise.all(records.map(async (record) => { try { return await this.validateWorktree(record.owner); } catch { return undefined; } }));
-    return validated.filter((record): record is WorktreeReference => record !== undefined);
+    const bindings = await this.borrowedWorktreeRecords();
+    const boundOwners = new Set(bindings.map((binding) => binding.owner));
+    const owned = await Promise.all(records.filter((record) => !boundOwners.has(record.owner)).map(async (record) => { try { return await this.validateWorktree(record.owner); } catch { return undefined; } }));
+    const borrowed = await Promise.all(bindings.map(async (binding) => (await this.resolveBorrowedWorktree(binding, new Set([this.runId]))).reference));
+    return [...owned.filter((record): record is WorktreeReference => record !== undefined), ...borrowed];
   }
 
   async changedWorktrees(): Promise<readonly WorktreeReference[]> {

package/src/session-inspector.ts

@@ -53,6 +53,10 @@ export function transcriptLines(entries: readonly SessionEntry[]): string[] {
   });
 }
 
+export function transcriptFileLines(path: string): string[] {
+  return transcriptLines(SessionManager.open(path).buildContextEntries());
+}
+
 function mergedModels(groups: readonly (readonly ModelUsage[])[]): ModelUsage[] {
   const totals = new Map<string, number>();
   for (const group of groups) for (const item of group) totals.set(item.model, (totals.get(item.model) ?? 0) + item.cost);

package/src/workflow-evals.ts

@@ -8,7 +8,7 @@ import { Value } from "typebox/value";
 import { getAgentDir, parseFrontmatter, SessionManager } from "@earendil-works/pi-coding-agent";
 import { CAPTURE_ERROR_PREFIX, CAPTURE_IDENTITY, resolveWorkflowSkillPath } from "./eval-capture-extension.js";
 export { resolveWorkflowSkillPath } from "./eval-capture-extension.js";
-import { ERROR_CODES, inspectWorkflowScript, loadAgentDefinitions, runWorkflow, WorkflowError, type AgentIdentity, type JsonSchema, type JsonValue, type StaticWorkflowCall, type StaticWorkflowExecution, type WorkflowErrorCode } from "./index.js";
+import { ERROR_CODES, inspectWorkflowScript, isObject, loadAgentDefinitions, runWorkflow, WORKFLOW_CALL_KINDS, WorkflowError, type AgentIdentity, type JsonSchema, type JsonValue, type StaticWorkflowCall, type StaticWorkflowExecution, type WorkflowErrorCode } from "./index.js";
 
 export type SignificantAction = { kind: "tool"; name: string } | { kind: "text" } | { kind: "thinking" };
 export type SequenceExpectation = readonly string[] | { equals?: readonly string[]; startsWith?: readonly string[] };
@@ -95,7 +95,6 @@ export const SAFE_PARENT_EVAL_TOOLS = Object.freeze(["read", "grep", "find", "ba
 const EVAL_MODEL_TOKEN = "$EVAL_MODEL";
 const semantic = (description: string): readonly SemanticCriterion[] => [{ id: "intent", description }];
 const JSON_RESULT_TYPES = ["null", "boolean", "number", "integer", "string", "array", "object"] as const;
-const WORKFLOW_CALL_KINDS = ["agent", "conversation", "parallel", "pipeline", "checkpoint", "phase", "withWorktree"] as const;
 const AGENT_OPTION_NAMES = ["role", "model", "thinking", "tools", "retries"] as const;
 const expectationKeys = ["firstSignificantAction", "firstTool", "firstBatchToolSequence", "parentToolSequence", "workflowCallCount", "requiredOperations", "forbiddenOperations", "requiredRoles", "minimumAgentCalls", "requireOutputSchema", "expectedResults", "agentPolicies", "requiredAgentOrder", "requiredAgentStructures", "requiredDataFlow"] as const;
 const caseKeys = ["id", "prompt", "timeoutMs", "maxCost", "expectations", "expectedWorkflowCalls", "semanticCriteria"] as const;
@@ -130,7 +129,6 @@ export function loadWorkflowEvalCases(directory = evalCasesDirectory()): readonl
 export const INITIAL_WORKFLOW_EVAL_CASES: readonly WorkflowEvalCase[] = loadWorkflowEvalCases();
 
 
-function isObject(value: unknown): value is Record<string, unknown> { return typeof value === "object" && value !== null && !Array.isArray(value); }
 function isJson(value: unknown): value is JsonValue { if (value === null || typeof value === "string" || typeof value === "boolean") return true; if (typeof value === "number") return Number.isFinite(value); if (Array.isArray(value)) return value.every(isJson); return isObject(value) && Object.values(value).every(isJson); }
 function asJsonObject(value: unknown): Readonly<Record<string, JsonValue>> | undefined { return isObject(value) && Object.values(value).every(isJson) ? value as Readonly<Record<string, JsonValue>> : undefined; }
 function jsonType(value: JsonValue): JsonResultType { if (value === null) return "null"; if (Array.isArray(value)) return "array"; if (typeof value === "number") return Number.isInteger(value) ? "integer" : "number"; if (typeof value === "object") return "object"; if (typeof value === "string") return "string"; if (typeof value === "boolean") return "boolean"; return "null"; }
@@ -487,6 +485,7 @@ export async function replayWorkflowScript(script: string, args: JsonValue = nul
         return `fake:${prompt}`;
       } finally { active -= 1; }
     },
+    worktree: async () => ({ path: "/worktrees/eval", branch: "eval-branch" }),
     phase: (name) => { phases.push(name); },
     log: (message) => { logs.push(message); },
   }, signal);
@@ -595,7 +594,7 @@ function semanticJudgePrompt(evalCase: WorkflowEvalCase, calls: readonly Capture
   const roles = loadAgentDefinitions(cwd, join(home, ".pi", "agent"));
   const usedRoles = new Set(calls.flatMap(({ script }) => { try { return script ? inspectWorkflowScript(script).flatMap((call) => call.kind === "agent" && call.role ? [call.role] : []) : []; } catch { return []; } }));
   const roleText = [...usedRoles].map((role) => `${role}: ${roles[role]?.description ?? "no description"}`).join("\n") || "none";
-  const docs = "agent(prompt, options) delegates; parallel(name, tasks) runs independent tasks concurrently; pipeline(name, items, stages) applies ordered stages; prompt(template, data) carries values into prompts. A role owns model/thinking/tools policy.";
+  const docs = "agent(prompt, options) delegates; shell(command, options) runs a deterministic host command and returns exitCode/stdout/stderr; parallel(name, tasks) runs independent tasks concurrently; pipeline(name, items, stages) applies ordered stages; prompt(template, data) carries values into prompts. A role owns model/thinking/tools policy.";
   return `Judge whether the captured workflow design satisfies each criterion. Do not execute it. Return only JSON: {"criteria":[{"id":"criterion id","pass":true,"evidence":"specific script evidence"}]}.\n\nOriginal request:\n${evalCase.prompt}\n\nCriteria:\n${JSON.stringify(evalCase.semanticCriteria ?? [])}\n\nDSL:\n${docs}\n\nRelevant roles:\n${roleText}\n\nCaptured workflow script(s):\n${calls.map((call, index) => `--- ${String(index)} ---\n${call.script ?? "<missing>"}`).join("\n")}`;
 }
 
@@ -646,21 +645,20 @@ function seedEvalProject(cwd: string, home: string, model: string): void {
     if (frontmatterEnd >= 0) writeFileSync(path, `${content.slice(0, frontmatterEnd).replace(/^model:.*$/m, `model: ${model}`)}${content.slice(frontmatterEnd)}`);
   }
 }
-
+export function findSessionFile(directory: string, sessionId: string): string | undefined {
+  if (!existsSync(directory)) return undefined;
+  for (const entry of readdirSync(directory, { withFileTypes: true })) {
+    const path = join(directory, entry.name);
+    if (entry.isDirectory()) { const found = findSessionFile(path, sessionId); if (found) return found; }
+    else if (entry.name.endsWith(".jsonl")) {
+      try { const header = JSON.parse(readFileSync(path, "utf8").split("\n")[0] ?? "{}") as unknown; if (isObject(header) && header.id === sessionId) return path; } catch { /* Ignore incomplete sessions. */ }
+    }
+  }
+  return undefined;
+}
 async function findParentSession(cwd: string, sessionDir: string, sessionId: string): Promise<string | undefined> {
   try { const sessions = await SessionManager.list(cwd, sessionDir); const found = sessions.find((session) => session.id === sessionId); if (found) return found.path; } catch { /* Fall through to the JSONL scan. */ }
-  const visit = (directory: string): string | undefined => {
-    if (!existsSync(directory)) return undefined;
-    for (const entry of readdirSync(directory, { withFileTypes: true })) {
-      const path = join(directory, entry.name);
-      if (entry.isDirectory()) { const found = visit(path); if (found) return found; }
-      else if (entry.name.endsWith(".jsonl")) {
-        try { const header = JSON.parse(readFileSync(path, "utf8").split("\n")[0] ?? "{}") as unknown; if (isObject(header) && header.id === sessionId) return path; } catch { /* Ignore incomplete files. */ }
-      }
-    }
-    return undefined;
-  };
-  return visit(sessionDir);
+  return findSessionFile(sessionDir, sessionId);
 }
 
 function emptyAccounting(cost = 0): EvalAccounting { return { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, totalTokens: 0, cost, models: [] }; }