pi-extensible-workflows 1.0.1 → 3.0.0

package/src/persistence.ts

@@ -5,20 +5,13 @@ import { access, link, mkdir, open, readFile, readdir, rename, rm, stat, writeFi
 import { basename, dirname, join, relative, resolve, sep } from "node:path";
 import { homedir } from "node:os";
 import { promisify } from "node:util";
-import type { BudgetApprovalRequest, JsonValue, LaunchSnapshot, RunRecord, WorkflowRunEvent } from "./index.js";
+import type { BudgetApprovalRequest, JsonValue, LaunchSnapshot, RunRecord, WorkflowRunEvent } from "./types.js";
 import type { OwnershipRecord } from "./agent-execution.js";
-import { loadLaunchSnapshot, WorkflowError } from "./index.js";
+import { WorkflowError } from "./types.js";
+import { loadLaunchSnapshot } from "./utils.js";
 
 export interface NativeSessionReference { sessionId: string; sessionFile: string }
 export interface EffectiveSystemPrompt { sessionId: string; attempt: number; turn: number; sha256: string; prompt: string }
-export interface ConversationHead { turn: number; sessionId: string; sessionFile: string; leafId: string; systemPrompt: string; systemPromptSha256: string; toolDefinitionsSha256: string }
-export interface PersistedConversation { id: string; policy: JsonValue; head: ConversationHead }
-type ConversationArtifact = { version: 1; conversations: Record<string, PersistedConversation> };
-function isConversationArtifact(value: unknown): value is ConversationArtifact {
-  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
-  const artifact = value as { version?: unknown; conversations?: unknown };
-  return artifact.version === 1 && Boolean(artifact.conversations) && typeof artifact.conversations === "object" && !Array.isArray(artifact.conversations);
-}
 export interface PersistedRun extends RunRecord { nativeSessions: readonly NativeSessionReference[] }
 export interface CompletedOperation { path: string; value: JsonValue }
 export interface AwaitingCheckpoint { path: string; name: string; prompt: string; context: JsonValue }
@@ -26,6 +19,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 = {
@@ -191,12 +185,12 @@ 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));
   }
@@ -212,9 +206,9 @@ 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: {} });
       await rename(temporary, this.directory);
     } catch (error) {
       await rm(temporary, { recursive: true, force: true });
@@ -293,27 +287,6 @@ export class RunStore {
     return (await json<{ version: 1; entries: EffectiveSystemPrompt[] }>(this.systemPromptPath()).catch((error: unknown) => { if ((error as NodeJS.ErrnoException).code === "ENOENT") return { version: 1 as const, entries: [] }; throw error; })).entries;
   }
 
-  conversationPath(): string { return join(this.directory, "conversations.json"); }
-  async conversation(id: string): Promise<PersistedConversation | undefined> {
-    await this.conversationWrite;
-    let artifact: ConversationArtifact;
-    try { const raw = await json<unknown>(this.conversationPath()); if (!isConversationArtifact(raw)) throw new WorkflowError("RESUME_INCOMPATIBLE", "Conversation state is corrupt"); artifact = raw; } catch (error) { if ((error as NodeJS.ErrnoException).code === "ENOENT") return undefined; if (error instanceof WorkflowError) throw error; throw new WorkflowError("RESUME_INCOMPATIBLE", `Cannot load conversation state: ${error instanceof Error ? error.message : String(error)}`); }
-    return artifact.conversations[id];
-  }
-  async saveConversation(conversation: PersistedConversation): Promise<void> {
-    const write = this.conversationWrite.then(async () => {
-      const path = this.conversationPath();
-      let artifact: ConversationArtifact;
-      try { const raw = await json<unknown>(path); if (!isConversationArtifact(raw)) throw new WorkflowError("RESUME_INCOMPATIBLE", "Conversation state is corrupt"); artifact = raw; } catch (error) { if ((error as NodeJS.ErrnoException).code === "ENOENT") artifact = { version: 1, conversations: {} }; else if (error instanceof WorkflowError) throw error; else throw new WorkflowError("RESUME_INCOMPATIBLE", `Cannot load conversation state: ${error instanceof Error ? error.message : String(error)}`); }
-      const previous = artifact.conversations[conversation.id];
-      if (previous && previous.head.turn + 1 !== conversation.head.turn) throw new WorkflowError("RESUME_INCOMPATIBLE", `Conversation head is not the previous turn: ${conversation.id}`);
-      if (!previous && conversation.head.turn !== 1) throw new WorkflowError("RESUME_INCOMPATIBLE", `Conversation must start at turn one: ${conversation.id}`);
-      artifact.conversations[conversation.id] = structuredClone(conversation);
-      await atomicJson(path, artifact);
-    });
-    this.conversationWrite = write.catch(() => undefined);
-    await write;
-  }
   private async updateJournal<T>(update: (journal: Journal) => T | Promise<T>): Promise<T> {
     let result!: T;
     const write = this.journalWrite.then(async () => {
@@ -336,11 +309,33 @@ export class RunStore {
   }
 
   async replay(path: string): Promise<CompletedOperation | undefined> {
+    const operations = await this.replayableOperations();
+    return operations.find((operation) => operation.path === path);
+  }
+
+  async replayableOperations(): Promise<readonly CompletedOperation[]> {
+    return this.replayableOperationsFrom(new Set());
+  }
+
+  private async replayableOperationsFrom(seen: Set<string>): Promise<readonly CompletedOperation[]> {
+    if (seen.has(this.runId)) throw new WorkflowError("RESUME_INCOMPATIBLE", "Retry provenance contains a cycle");
+    const nextSeen = new Set(seen);
+    nextSeen.add(this.runId);
     await this.journalWrite;
-    return (await json<Journal>(join(this.directory, "journal.json"))).completed[path];
+    const loaded = await this.load();
+    const operations = new Map<string, CompletedOperation>();
+    if (loaded.run.retry?.sourceRunId) {
+      const source = await this.sourceRun(loaded.run.retry.sourceRunId);
+      for (const operation of await source.replayableOperationsFrom(nextSeen)) operations.set(operation.path, operation);
+    }
+    const journal = await json<Journal>(join(this.directory, "journal.json"));
+    for (const operation of Object.values(journal.completed)) operations.set(operation.path, operation);
+    return [...operations.values()].map((operation) => structuredClone(operation));
   }
 
   async awaitCheckpoint(checkpoint: AwaitingCheckpoint): Promise<boolean | undefined> {
+    const replayed = await this.replay(checkpoint.path);
+    if (replayed) return replayed.value as boolean;
     return this.updateJournal((journal) => {
       const completed = journal.completed[checkpoint.path];
       if (completed) return completed.value as boolean;
@@ -392,6 +387,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>;
@@ -402,6 +415,146 @@ 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); }
+  async validateRetrySource(): Promise<void> {
+    const validate = async (current: RunStore, seen: Set<string>): Promise<void> => {
+      if (seen.has(current.runId)) throw new WorkflowError("RESUME_INCOMPATIBLE", "Retry provenance contains a cycle");
+      const nextSeen = new Set(seen);
+      nextSeen.add(current.runId);
+      const loaded = await current.load();
+      const retry = loaded.run.retry;
+      if (!retry) return;
+      if (typeof retry.sourceRunId !== "string" || !retry.sourceRunId || retry.sourceRunId === current.runId || typeof retry.lineageRootRunId !== "string" || !retry.lineageRootRunId || !Array.isArray(retry.completedPaths) || retry.completedPaths.some((path) => typeof path !== "string") || !Array.isArray(retry.incompletePaths) || retry.incompletePaths.some((path) => typeof path !== "string") || !Array.isArray(retry.namedWorktrees) || retry.namedWorktrees.some((name) => typeof name !== "string")) throw new WorkflowError("RESUME_INCOMPATIBLE", "Retry provenance is incomplete");
+      const source = await current.sourceRun(retry.sourceRunId);
+      const sourceRun = (await source.load()).run;
+      if (loaded.run.parentRunId !== retry.sourceRunId) throw new WorkflowError("RESUME_INCOMPATIBLE", "Retry parent run does not match its source run");
+      if (sourceRun.state !== "failed") throw new WorkflowError("RESUME_INCOMPATIBLE", `Retry source run ${retry.sourceRunId} is not failed`);
+      const expectedLineageRoot = sourceRun.retry?.lineageRootRunId ?? sourceRun.id;
+      if (retry.lineageRootRunId !== expectedLineageRoot) throw new WorkflowError("RESUME_INCOMPATIBLE", "Retry lineage root does not match its source run");
+      await validate(source, nextSeen);
+    };
+    try { await validate(this, new Set()); }
+    catch (error) { throw error instanceof WorkflowError && error.code === "RESUME_INCOMPATIBLE" ? error : new WorkflowError("RESUME_INCOMPATIBLE", error instanceof Error ? error.message : String(error)); }
+  }
+
+  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) {
+      const loaded = await this.load();
+      if (loaded.run.parentRunId === undefined) return undefined;
+      const parent = await this.sourceRun(loaded.run.parentRunId);
+      return parent.findNamedWorktree(name, nextSeen);
+    }
+    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 validateNamedWorktrees(): Promise<void> {
+    try {
+      const records = await json<unknown[]>(join(this.directory, "worktrees.json"));
+      for (const record of records) {
+        const owner = record && typeof record === "object" && typeof (record as Partial<WorktreeReference>).owner === "string" ? (record as Partial<WorktreeReference>).owner : undefined;
+        if (owner && this.worktreeName(owner)) await this.validateWorktree(owner);
+      }
+    } 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; }
@@ -426,13 +579,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));
     }
@@ -440,9 +594,20 @@ 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;
+        }
+      }
+      if (name && Array.isArray(loaded.run.retry?.namedWorktrees) && loaded.run.retry.namedWorktrees.includes(name)) throw new WorkflowError("WORKTREE_FAILED", `Missing inherited named worktree ${name}`);
       const existing = records.find((record) => record.owner === owner);
       if (existing) return this.validateWorktree(owner);
       const { path, branch } = this.expectedWorktree(owner);
@@ -488,6 +653,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 () => {
@@ -510,13 +694,37 @@ 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 validNamedWorktrees(): Promise<readonly string[]> {
+    const load = async (path: string): Promise<unknown> => {
+      try { return await json<unknown>(path); } catch (error) { if ((error as NodeJS.ErrnoException).code === "ENOENT") return []; throw error; }
+    };
+    const names = new Set<string>();
+    const rawRecords = await load(join(this.directory, "worktrees.json"));
+    let bindings: readonly BorrowedWorktreeBinding[];
+    try { bindings = await this.borrowedWorktreeRecords(); }
+    catch (error) { if (error instanceof WorkflowError && error.code === "WORKTREE_FAILED") return []; throw error; }
+    const boundOwners = new Set(bindings.map((binding) => binding.owner));
+    for (const record of Array.isArray(rawRecords) ? rawRecords : []) {
+      if (!record || typeof record !== "object") continue;
+      const owner = (record as Partial<WorktreeReference>).owner;
+      if (typeof owner !== "string") continue;
+      const name = this.worktreeName(owner);
+      if (!name || owner !== this.namedWorktreeOwner(name) || boundOwners.has(owner)) continue;
+      try { await this.ownedWorktree(owner); names.add(name); } catch { /* Do not advertise stale or invalid records. */ }
+    }
+    for (const binding of bindings) {
+      try { await this.resolveBorrowedWorktree(binding, new Set([this.runId])); names.add(binding.name); } catch { /* Do not advertise stale inherited records. */ }
+    }
+    return [...names];
   }
-
   async changedWorktrees(): Promise<readonly WorktreeReference[]> {
     const changed: WorktreeReference[] = [];
     for (const valid of await this.worktrees()) {

package/src/registry.ts

@@ -0,0 +1,157 @@
+import { Value } from "typebox/value";
+import type { JsonValue, RegisteredAgentSetupHook, WorkflowCatalog, WorkflowCatalogError, WorkflowCatalogFunction, WorkflowCatalogIndex, WorkflowCatalogVariable, WorkflowExtension, WorkflowFunction, WorkflowFunctionContext, WorkflowJournal, WorkflowVariable } from "./types.js";
+import { deepFreeze, fail, jsonValue, object } from "./utils.js";
+import { loadSettings, validateSchema } from "./validation.js";
+
+const RESERVED_GLOBALS = new Set(["agent", "shell", "prompt", "checkpoint", "parallel", "pipeline", "phase", "withWorktree", "log", "args", "Promise", "JSON", "Math", "Date", "eval", "Function", "WebAssembly", "process", "require", "module", "exports", "console", "fetch", "XMLHttpRequest", "WebSocket", "performance", "crypto", "setTimeout", "setInterval", "setImmediate", "queueMicrotask", "Intl", "SharedArrayBuffer", "Atomics", "globalThis", "global", "undefined", "NaN", "Infinity", "extensions", "workflow_catalog"]);
+const IDENTIFIER = /^[A-Za-z_$][\w$]*$/;
+const SEMVER = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/;
+
+export class WorkflowRegistry {
+  readonly #extensions = new Set<Readonly<WorkflowExtension>>();
+  readonly #globals = new Map<string, string>();
+  readonly #hooks = new Map<string, RegisteredAgentSetupHook>();
+  #frozen = false;
+
+  get frozen(): boolean { return this.#frozen; }
+  freeze(): void { this.#frozen = true; }
+
+  register(extension: WorkflowExtension): void {
+    if (this.#frozen) fail("REGISTRY_FROZEN", "Workflow extension registration is closed after session_start");
+    if (object(extension) && Object.prototype.hasOwnProperty.call(extension, "workflows")) fail("INVALID_METADATA", "Separate registered workflow definitions were removed; register a function with input and output schemas instead");
+    if (!object(extension) || Object.keys(extension).some((key) => !["version", "headline", "description", "functions", "variables", "agentSetupHooks"].includes(key)) || typeof extension.version !== "string" || !SEMVER.test(extension.version) || typeof extension.headline !== "string" || !extension.headline.trim() || typeof extension.description !== "string" || !extension.description.trim()) fail("INVALID_METADATA", "Workflow extensions require a semantic version, headline, and description");
+    const functions = extension.functions ?? {};
+    const variables = extension.variables ?? {};
+    const agentSetupHooks = extension.agentSetupHooks ?? {};
+    if (!object(functions) || !object(variables) || !object(agentSetupHooks) || (Object.keys(functions).length === 0 && Object.keys(variables).length === 0 && Object.keys(agentSetupHooks).length === 0)) fail("INVALID_METADATA", "Workflow extensions require functions, variables, or agent setup hooks");
+    const names = [...Object.keys(functions), ...Object.keys(variables)];
+    if (new Set(names).size !== names.length) fail("GLOBAL_COLLISION", "Global name collision inside extension");
+    for (const name of names) {
+      if (!IDENTIFIER.test(name) || name.startsWith("__pi_extensible_workflows_")) fail("INVALID_METADATA", `Invalid global name: ${name}`);
+      if (RESERVED_GLOBALS.has(name)) fail("GLOBAL_COLLISION", `Global name is reserved: ${name}`);
+      if (this.#globals.has(name)) fail("GLOBAL_COLLISION", `Global name is already registered: ${name}`);
+    }
+    for (const [name, fn] of Object.entries(functions)) {
+      if (!object(fn) || Object.keys(fn).some((key) => !["description", "input", "output", "run"].includes(key)) || typeof fn.description !== "string" || !fn.description.trim() || typeof fn.run !== "function") fail("INVALID_METADATA", `Invalid workflow function: ${name}`);
+      validateSchema(fn.input, `${name} input`);
+      validateSchema(fn.output, `${name} output`);
+      if (fn.input.type !== "object") fail("INVALID_SCHEMA", `${name} input must describe one object`);
+    }
+    for (const [name, variable] of Object.entries(variables)) {
+      if (!object(variable) || Object.keys(variable).some((key) => !["description", "schema", "resolve"].includes(key)) || typeof variable.description !== "string" || !variable.description.trim() || typeof variable.resolve !== "function") fail("INVALID_METADATA", `Invalid workflow variable: ${name}`);
+      validateSchema(variable.schema, `${name} schema`);
+    }
+    for (const [name, hook] of Object.entries(agentSetupHooks)) {
+      if (!IDENTIFIER.test(name) || !object(hook) || Object.keys(hook).some((key) => !["priority", "setup"].includes(key)) || typeof hook.setup !== "function" || hook.priority !== undefined && (typeof hook.priority !== "number" || !Number.isFinite(hook.priority))) fail("INVALID_METADATA", `Invalid agent setup hook: ${name}`);
+      if (this.#hooks.has(name)) fail("DUPLICATE_NAME", `Agent setup hook already registered: ${name}`);
+    }
+    const stored = deepFreeze({ ...extension, functions, variables, agentSetupHooks });
+    this.#extensions.add(stored);
+    for (const name of names) this.#globals.set(name, name);
+    for (const [name, hook] of Object.entries(agentSetupHooks)) this.#hooks.set(name, { name, priority: hook.priority ?? 10, setup: hook.setup });
+  }
+
+  function(name: string): WorkflowFunction {
+    if (!IDENTIFIER.test(name)) fail("MISSING_WORKFLOW", `Registered functions require an unqualified name: ${name}`);
+    const fn = [...this.#extensions].find((extension) => extension.functions?.[name])?.functions?.[name];
+    if (!fn) fail("MISSING_WORKFLOW", `Registered function is unavailable: ${name}; the separate registered-workflow format was removed`);
+    return fn;
+  }
+
+  functions(): Readonly<Record<string, WorkflowFunction>> {
+    return Object.freeze(Object.fromEntries([...this.#extensions].flatMap((extension) => Object.entries(extension.functions ?? {}))));
+  }
+
+  catalog(): WorkflowCatalog {
+    const functions: WorkflowCatalogFunction[] = [];
+    const variables: WorkflowCatalogVariable[] = [];
+    for (const extension of this.#extensions) {
+      for (const [name, fn] of Object.entries(extension.functions ?? {})) functions.push({ name, version: extension.version, headline: extension.headline, extensionDescription: extension.description, description: fn.description, input: structuredClone(fn.input), output: structuredClone(fn.output) });
+      for (const [name, variable] of Object.entries(extension.variables ?? {})) variables.push({ name, version: extension.version, headline: extension.headline, extensionDescription: extension.description, description: variable.description, schema: structuredClone(variable.schema) });
+    }
+    let aliases: Readonly<Record<string, string>> | undefined;
+    try { aliases = loadSettings().modelAliases; } catch { aliases = undefined; }
+    const sort = (left: { name: string }, right: { name: string }) => left.name.localeCompare(right.name);
+    return deepFreeze({ functions: functions.sort(sort), variables: variables.sort(sort), ...(aliases ? { modelAliases: structuredClone(aliases) } : {}) });
+  }
+
+  catalogIndex(): WorkflowCatalogIndex {
+    const catalog = this.catalog();
+    return deepFreeze({
+      functions: catalog.functions.map(({ name, description, input }) => ({ name, description, input: structuredClone(input) })),
+      variables: catalog.variables.map(({ name, description, schema }) => ({ name, description, schema: structuredClone(schema) })),
+      ...(catalog.modelAliases ? { modelAliases: structuredClone(catalog.modelAliases) } : {}),
+    });
+  }
+
+  catalogDetail(name: string): WorkflowCatalogFunction | WorkflowCatalogVariable | WorkflowCatalogError {
+    const catalog = this.catalog();
+    const entry = catalog.functions.find((candidate) => candidate.name === name) ?? catalog.variables.find((candidate) => candidate.name === name);
+    if (entry) return entry;
+    return deepFreeze({ error: { code: "NOT_FOUND", name, message: `No registered workflow function or variable is available: ${name}` } });
+  }
+
+  globals(): Readonly<Record<string, { name: string }>> {
+    return Object.freeze(Object.fromEntries([...this.#extensions].flatMap((extension) => Object.keys(extension.functions ?? {}).map((name) => [name, { name }]))));
+  }
+
+  async invokeFunction(name: string, input: unknown, context: Readonly<WorkflowFunctionContext>, path: string, journal: WorkflowJournal): Promise<JsonValue> {
+    const fn = this.function(name);
+    if (!object(input) || !jsonValue(input) || !Value.Check(fn.input, input)) fail("RESULT_INVALID", `Invalid input for ${name}`);
+    const replayed = journal.get(path);
+    if (replayed !== undefined) {
+      if (!jsonValue(replayed) || !Value.Check(fn.output, replayed)) fail("RESULT_INVALID", `Invalid replay for ${name}`);
+      return structuredClone(replayed);
+    }
+    const result: unknown = await fn.run(deepFreeze(structuredClone(input)), Object.freeze({ run: context.run, invoke: context.invoke, agent: context.agent, shell: context.shell, prompt: context.prompt, parallel: context.parallel, pipeline: context.pipeline, withWorktree: context.withWorktree, checkpoint: context.checkpoint, phase: context.phase, log: context.log }));
+    if (!jsonValue(result) || !Value.Check(fn.output, result)) fail("RESULT_INVALID", `Invalid output from ${name}`);
+    const stored = structuredClone(result);
+    journal.put(path, stored);
+    return structuredClone(stored);
+  }
+
+  variables(): readonly { name: string; variable: WorkflowVariable }[] {
+    return [...this.#extensions].flatMap((extension) => Object.entries(extension.variables ?? {}).map(([name, variable]) => ({ name, variable })));
+  }
+  agentSetupHooks(): readonly RegisteredAgentSetupHook[] {
+    return [...this.#hooks.values()].sort((left, right) => left.priority - right.priority || (left.name < right.name ? -1 : left.name > right.name ? 1 : 0));
+  }
+}
+export type WorkflowRegistryApi = Pick<WorkflowRegistry, "frozen" | "freeze" | "register" | "function" | "functions" | "catalog" | "catalogIndex" | "catalogDetail" | "globals" | "invokeFunction" | "variables" | "agentSetupHooks">;
+interface WorkflowRegistryHost { api: WorkflowRegistryApi }
+const WORKFLOW_REGISTRY_KEY = Symbol.for("pi-extensible-workflows.workflow-registry");
+const globalRegistry = globalThis as typeof globalThis & Record<symbol, WorkflowRegistryHost | undefined>;
+function createWorkflowRegistryApi(registry: WorkflowRegistry): WorkflowRegistryApi {
+  return {
+    get frozen() { return registry.frozen; },
+    freeze: () => { registry.freeze(); },
+    register: (extension) => { registry.register(extension); },
+    function: (name) => registry.function(name),
+    functions: () => registry.functions(),
+    catalog: () => registry.catalog(),
+    catalogIndex: () => registry.catalogIndex(),
+    catalogDetail: (name) => registry.catalogDetail(name),
+    globals: () => registry.globals(),
+    invokeFunction: (...args) => registry.invokeFunction(...args),
+    variables: () => registry.variables(),
+    agentSetupHooks: () => registry.agentSetupHooks(),
+  };
+}
+function workflowRegistryHost(): WorkflowRegistryHost {
+  return globalRegistry[WORKFLOW_REGISTRY_KEY] ??= { api: createWorkflowRegistryApi(new WorkflowRegistry()) };
+}
+export function resetWorkflowRegistry(): void {
+  workflowRegistryHost().api = createWorkflowRegistryApi(new WorkflowRegistry());
+}
+export function beginWorkflowExtensionLoading(): void {
+  if (workflowRegistryHost().api.frozen) resetWorkflowRegistry();
+}
+export function loadingRegistry(): WorkflowRegistryApi { return workflowRegistryHost().api; }
+beginWorkflowExtensionLoading();
+export function registerWorkflowExtension(extension: WorkflowExtension): void { loadingRegistry().register(extension); }
+export function workflowCatalog(): WorkflowCatalog { return loadingRegistry().catalog(); }
+export function workflowCatalogIndex(): WorkflowCatalogIndex { return loadingRegistry().catalogIndex(); }
+export function workflowCatalogDetail(name: string): WorkflowCatalogFunction | WorkflowCatalogVariable | WorkflowCatalogError { return loadingRegistry().catalogDetail(name); }
+export function registeredWorkflowFunctions(): Readonly<Record<string, WorkflowFunction>> { return loadingRegistry().functions(); }
+
+export type { WorkflowCatalog, WorkflowCatalogError, WorkflowCatalogFunction, WorkflowCatalogIndex, WorkflowCatalogIndexFunction, WorkflowCatalogIndexVariable, WorkflowCatalogVariable } from "./types.js";

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);
@@ -211,7 +215,7 @@ export async function loadSessionReport(path: string, home = homedir()): Promise
     const args = call.arguments;
     const agents = loaded ? await Promise.all(loaded.run.agents.map(agentReport)) : [];
     const models = mergedModels(agents.flatMap(({ attempts }) => attempts.map(({ models: attemptModels }) => attemptModels)));
-    const name = typeof args.name === "string" ? args.name : typeof args.workflow === "string" ? args.workflow : loaded?.run.workflowName ?? "workflow";
+    const name = loaded?.run.workflowName ?? (typeof args.workflow === "string" ? args.workflow : typeof args.name === "string" ? args.name : "workflow");
     const description = typeof args.description === "string" ? args.description : loaded?.snapshot.metadata.description;
     const script = typeof args.script === "string" && args.script.trim() ? args.script : loaded?.snapshot.script;
     let staticCalls: StaticWorkflowCall[] = [];