pi-extensible-workflows 1.0.1 → 3.0.0

package/dist/src/persistence.d.ts

@@ -1,4 +1,4 @@
-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";
 export interface NativeSessionReference {
     sessionId: string;
@@ -11,20 +11,6 @@ export interface EffectiveSystemPrompt {
     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;
-}
 export interface PersistedRun extends RunRecord {
     nativeSessions: readonly NativeSessionReference[];
 }
@@ -47,6 +33,11 @@ export interface WorktreeReference {
     cwd: string;
     base: string;
 }
+export interface BorrowedWorktreeBinding {
+    name: string;
+    sourceRunId: string;
+    owner: string;
+}
 export declare function projectStorageKey(cwd: string): string;
 export declare function runsDirectory(cwd: string, sessionId: string, home?: string): string;
 export declare class SessionLease {
@@ -66,14 +57,15 @@ export declare class RunStore {
     readonly cwd: string;
     readonly sessionId: string;
     readonly runId: string;
+    readonly home: string;
     readonly directory: string;
     private journalWrite;
     private stateWrite;
     private worktreeWrite;
+    private borrowedWorktreeWrite;
     private snapshotWrite;
     private launchSnapshotWrite;
     private systemPromptWrite;
-    private conversationWrite;
     constructor(cwd: string, sessionId: string, runId: string, home?: string);
     create(run: PersistedRun, snapshot: Readonly<LaunchSnapshot>): Promise<void>;
     isComplete(): Promise<boolean>;
@@ -90,12 +82,11 @@ export declare class RunStore {
     systemPromptPath(): string;
     recordSystemPrompt(entry: Omit<EffectiveSystemPrompt, "sha256">): Promise<void>;
     systemPrompts(): Promise<readonly EffectiveSystemPrompt[]>;
-    conversationPath(): string;
-    conversation(id: string): Promise<PersistedConversation | undefined>;
-    saveConversation(conversation: PersistedConversation): Promise<void>;
     private updateJournal;
     complete(path: string, value: JsonValue): Promise<void>;
     replay(path: string): Promise<CompletedOperation | undefined>;
+    replayableOperations(): Promise<readonly CompletedOperation[]>;
+    private replayableOperationsFrom;
     awaitCheckpoint(checkpoint: AwaitingCheckpoint): Promise<boolean | undefined>;
     awaitingCheckpoints(): Promise<readonly AwaitingCheckpoint[]>;
     requestWorkflowDecision(request: PendingWorkflowDecision): Promise<void>;
@@ -104,13 +95,35 @@ export declare class RunStore {
     answerCheckpoint(name: string, approved: boolean): Promise<AwaitingCheckpoint | undefined>;
     private expectedWorktree;
     private markerPath;
+    private namedWorktreeOwner;
+    private worktreeName;
     private structuralWorktree;
+    private borrowedWorktreeRecords;
+    borrowedWorktrees(): Promise<readonly BorrowedWorktreeBinding[]>;
+    private borrowedWorktree;
+    private sourceRun;
+    validateParentRun(parentRunId: string): Promise<void>;
+    validateRetrySource(): Promise<void>;
+    private ownedWorktree;
+    private resolveBorrowedWorktree;
+    private findNamedWorktree;
+    resolveNamedWorktree(name: string, seen?: Set<string>): Promise<{
+        reference: WorktreeReference;
+        sourceRunId: string;
+        owner: string;
+    }>;
+    validateBorrowedWorktrees(): Promise<void>;
+    validateNamedWorktrees(): Promise<void>;
+    ownsWorktree(owner: string): Promise<boolean>;
     private cleanupMarker;
     private cleanupOrphanWorktrees;
     validateWorktree(owner: string, cwd?: string): Promise<WorktreeReference>;
     worktree(owner: string): Promise<WorktreeReference>;
+    private resolveNamedWorktreeFromParent;
+    private bindBorrowedWorktree;
     snapshotWorktree(owner: string): Promise<string>;
     worktrees(): Promise<readonly WorktreeReference[]>;
+    validNamedWorktrees(): Promise<readonly string[]>;
     changedWorktrees(): Promise<readonly WorktreeReference[]>;
     saveResult(value: JsonValue): Promise<string>;
     delete(confirmed: boolean): Promise<void>;

package/dist/src/persistence.js

@@ -5,13 +5,8 @@ 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 { loadLaunchSnapshot, WorkflowError } from "./index.js";
-function isConversationArtifact(value) {
-    if (!value || typeof value !== "object" || Array.isArray(value))
-        return false;
-    const artifact = value;
-    return artifact.version === 1 && Boolean(artifact.conversations) && typeof artifact.conversations === "object" && !Array.isArray(artifact.conversations);
-}
+import { WorkflowError } from "./types.js";
+import { loadLaunchSnapshot } from "./utils.js";
 const execute = promisify(execFile);
 const gitIdentity = {
     GIT_AUTHOR_NAME: "pi-extensible-workflows", GIT_AUTHOR_EMAIL: "pi-extensible-workflows@localhost", GIT_COMMITTER_NAME: "pi-extensible-workflows", GIT_COMMITTER_EMAIL: "pi-extensible-workflows@localhost",
@@ -215,20 +210,22 @@ export class RunStore {
     cwd;
     sessionId;
     runId;
+    home;
     directory;
     journalWrite = Promise.resolve();
     // ponytail: serializes one RunStore instance; cross-process run sharing remains unsupported.
     stateWrite = Promise.resolve();
     worktreeWrite = Promise.resolve();
+    borrowedWorktreeWrite = Promise.resolve();
     snapshotWrite = Promise.resolve();
     launchSnapshotWrite = Promise.resolve();
     // ponytail: the session lease prevents concurrent RunStore writers for one run.
     systemPromptWrite = Promise.resolve();
-    conversationWrite = Promise.resolve();
     constructor(cwd, sessionId, runId, home = homedir()) {
         this.cwd = cwd;
         this.sessionId = sessionId;
         this.runId = runId;
+        this.home = home;
         this.cwd = resolve(cwd);
         this.directory = join(runsDirectory(this.cwd, sessionId, home), safePart(runId));
     }
@@ -244,9 +241,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) {
@@ -325,54 +322,6 @@ export class RunStore {
         return (await json(this.systemPromptPath()).catch((error) => { if (error.code === "ENOENT")
             return { version: 1, entries: [] }; throw error; })).entries;
     }
-    conversationPath() { return join(this.directory, "conversations.json"); }
-    async conversation(id) {
-        await this.conversationWrite;
-        let artifact;
-        try {
-            const raw = await json(this.conversationPath());
-            if (!isConversationArtifact(raw))
-                throw new WorkflowError("RESUME_INCOMPATIBLE", "Conversation state is corrupt");
-            artifact = raw;
-        }
-        catch (error) {
-            if (error.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) {
-        const write = this.conversationWrite.then(async () => {
-            const path = this.conversationPath();
-            let artifact;
-            try {
-                const raw = await json(path);
-                if (!isConversationArtifact(raw))
-                    throw new WorkflowError("RESUME_INCOMPATIBLE", "Conversation state is corrupt");
-                artifact = raw;
-            }
-            catch (error) {
-                if (error.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;
-    }
     async updateJournal(update) {
         let result;
         const write = this.journalWrite.then(async () => {
@@ -394,10 +343,34 @@ export class RunStore {
         });
     }
     async replay(path) {
+        const operations = await this.replayableOperations();
+        return operations.find((operation) => operation.path === path);
+    }
+    async replayableOperations() {
+        return this.replayableOperationsFrom(new Set());
+    }
+    async replayableOperationsFrom(seen) {
+        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(join(this.directory, "journal.json"))).completed[path];
+        const loaded = await this.load();
+        const operations = new Map();
+        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(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) {
+        const replayed = await this.replay(checkpoint.path);
+        if (replayed)
+            return replayed.value;
         return this.updateJournal((journal) => {
             const completed = journal.completed[checkpoint.path];
             if (completed)
@@ -447,6 +420,26 @@ export class RunStore {
         const key = createHash("sha256").update(`${this.sessionId}\0${this.runId}\0${owner}`).digest("hex").slice(0, 16);
         return join(this.directory, `worktree-${key}.creating`);
     }
+    namedWorktreeOwner(name) {
+        if (!name.trim())
+            throw new WorkflowError("WORKTREE_FAILED", "Named worktree names must be non-empty");
+        return structuralPath("worktree", "named", name.trim());
+    }
+    worktreeName(owner) {
+        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;
+        }
+    }
     structuralWorktree(owner, record) {
         if (!record || typeof record !== "object")
             throw new Error(`Invalid worktree record for ${owner}`);
@@ -458,6 +451,171 @@ export class RunStore {
             throw new Error(`Invalid worktree record for ${owner}`);
         return candidate;
     }
+    async borrowedWorktreeRecords(wait = true) {
+        if (wait)
+            await this.borrowedWorktreeWrite;
+        const records = await json(join(this.directory, "borrowed-worktrees.json")).catch((error) => { if (error.code === "ENOENT")
+            return []; throw error; });
+        if (!Array.isArray(records))
+            throw new WorkflowError("WORKTREE_FAILED", "Borrowed worktree bindings are invalid");
+        const seen = new Set();
+        return records.map((record) => {
+            if (!record || typeof record !== "object")
+                throw new WorkflowError("WORKTREE_FAILED", "Borrowed worktree binding is invalid");
+            const candidate = record;
+            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() { return this.borrowedWorktreeRecords(); }
+    async borrowedWorktree(name) {
+        return (await this.borrowedWorktreeRecords()).find((binding) => binding.name === name);
+    }
+    async sourceRun(sourceRunId) {
+        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) { await this.sourceRun(parentRunId); }
+    async validateRetrySource() {
+        const validate = async (current, seen) => {
+            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));
+        }
+    }
+    async ownedWorktree(owner, cwd) {
+        const records = await json(join(this.directory, "worktrees.json"));
+        const matches = records.filter((candidate) => candidate && typeof candidate === "object" && candidate.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;
+    }
+    async resolveBorrowedWorktree(binding, seen) {
+        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));
+        }
+    }
+    async findNamedWorktree(name, seen = new Set()) {
+        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(join(this.directory, "worktrees.json"));
+        const matches = records.filter((candidate) => candidate && typeof candidate === "object" && candidate.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, seen = new Set()) {
+        const resolved = await this.findNamedWorktree(name, seen);
+        if (!resolved)
+            throw new WorkflowError("WORKTREE_FAILED", `Missing named worktree ${name}`);
+        return resolved;
+    }
+    async validateBorrowedWorktrees() {
+        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() {
+        try {
+            const records = await json(join(this.directory, "worktrees.json"));
+            for (const record of records) {
+                const owner = record && typeof record === "object" && typeof record.owner === "string" ? record.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) {
+        const records = await json(join(this.directory, "worktrees.json"));
+        return records.filter((candidate) => candidate && typeof candidate === "object" && candidate.owner === owner).length === 1;
+    }
     async cleanupMarker(markerPath) {
         let marker;
         try {
@@ -490,15 +648,15 @@ export class RunStore {
     async validateWorktree(owner, cwd) {
         try {
             await this.load();
-            const records = await json(join(this.directory, "worktrees.json"));
-            const matches = records.filter((candidate) => candidate && typeof candidate === "object" && candidate.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));
@@ -506,10 +664,23 @@ export class RunStore {
     }
     async worktree(owner) {
         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(recordsPath).catch((error) => { if (error.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);
@@ -564,6 +735,25 @@ export class RunStore {
         this.worktreeWrite = write.then(() => undefined, () => undefined);
         return write;
     }
+    async resolveNamedWorktreeFromParent(name, parentRunId) {
+        const source = await this.sourceRun(parentRunId);
+        return source.findNamedWorktree(name, new Set([this.runId]));
+    }
+    async bindBorrowedWorktree(binding) {
+        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) {
         try {
             const write = this.snapshotWrite.then(async () => {
@@ -593,13 +783,63 @@ export class RunStore {
     async worktrees() {
         const records = await json(join(this.directory, "worktrees.json")).catch((error) => { if (error.code === "ENOENT")
             return []; throw error; });
-        const validated = await Promise.all(records.map(async (record) => { try {
+        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;
         } }));
-        return validated.filter((record) => record !== undefined);
+        const borrowed = await Promise.all(bindings.map(async (binding) => (await this.resolveBorrowedWorktree(binding, new Set([this.runId]))).reference));
+        return [...owned.filter((record) => record !== undefined), ...borrowed];
+    }
+    async validNamedWorktrees() {
+        const load = async (path) => {
+            try {
+                return await json(path);
+            }
+            catch (error) {
+                if (error.code === "ENOENT")
+                    return [];
+                throw error;
+            }
+        };
+        const names = new Set();
+        const rawRecords = await load(join(this.directory, "worktrees.json"));
+        let bindings;
+        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.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() {
         const changed = [];

package/dist/src/registry.d.ts

@@ -0,0 +1,31 @@
+import type { JsonValue, RegisteredAgentSetupHook, WorkflowCatalog, WorkflowCatalogError, WorkflowCatalogFunction, WorkflowCatalogIndex, WorkflowCatalogVariable, WorkflowExtension, WorkflowFunction, WorkflowFunctionContext, WorkflowJournal, WorkflowVariable } from "./types.js";
+export declare class WorkflowRegistry {
+    #private;
+    get frozen(): boolean;
+    freeze(): void;
+    register(extension: WorkflowExtension): void;
+    function(name: string): WorkflowFunction;
+    functions(): Readonly<Record<string, WorkflowFunction>>;
+    catalog(): WorkflowCatalog;
+    catalogIndex(): WorkflowCatalogIndex;
+    catalogDetail(name: string): WorkflowCatalogFunction | WorkflowCatalogVariable | WorkflowCatalogError;
+    globals(): Readonly<Record<string, {
+        name: string;
+    }>>;
+    invokeFunction(name: string, input: unknown, context: Readonly<WorkflowFunctionContext>, path: string, journal: WorkflowJournal): Promise<JsonValue>;
+    variables(): readonly {
+        name: string;
+        variable: WorkflowVariable;
+    }[];
+    agentSetupHooks(): readonly RegisteredAgentSetupHook[];
+}
+export type WorkflowRegistryApi = Pick<WorkflowRegistry, "frozen" | "freeze" | "register" | "function" | "functions" | "catalog" | "catalogIndex" | "catalogDetail" | "globals" | "invokeFunction" | "variables" | "agentSetupHooks">;
+export declare function resetWorkflowRegistry(): void;
+export declare function beginWorkflowExtensionLoading(): void;
+export declare function loadingRegistry(): WorkflowRegistryApi;
+export declare function registerWorkflowExtension(extension: WorkflowExtension): void;
+export declare function workflowCatalog(): WorkflowCatalog;
+export declare function workflowCatalogIndex(): WorkflowCatalogIndex;
+export declare function workflowCatalogDetail(name: string): WorkflowCatalogFunction | WorkflowCatalogVariable | WorkflowCatalogError;
+export declare function registeredWorkflowFunctions(): Readonly<Record<string, WorkflowFunction>>;
+export type { WorkflowCatalog, WorkflowCatalogError, WorkflowCatalogFunction, WorkflowCatalogIndex, WorkflowCatalogIndexFunction, WorkflowCatalogIndexVariable, WorkflowCatalogVariable } from "./types.js";