pi-extensible-workflows 1.0.1 → 2.0.0

package/dist/src/persistence.d.ts

@@ -47,6 +47,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,10 +71,12 @@ 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;
@@ -104,11 +111,30 @@ 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>;
+    private ownedWorktree;
+    private resolveBorrowedWorktree;
+    private findNamedWorktree;
+    resolveNamedWorktree(name: string, seen?: Set<string>): Promise<{
+        reference: WorktreeReference;
+        sourceRunId: string;
+        owner: string;
+    }>;
+    validateBorrowedWorktrees(): 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[]>;
     changedWorktrees(): Promise<readonly WorktreeReference[]>;

package/dist/src/persistence.js

@@ -215,11 +215,13 @@ 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.
@@ -229,6 +231,7 @@ export class RunStore {
         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,6 +247,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: {} });
@@ -447,6 +451,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 +482,123 @@ 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 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)
+            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, 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 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 +631,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 +647,21 @@ 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;
+                }
+            }
             const existing = records.find((record) => record.owner === owner);
             if (existing)
                 return this.validateWorktree(owner);
@@ -564,6 +716,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 +764,16 @@ 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 changedWorktrees() {
         const changed = [];

package/dist/src/session-inspector.d.ts

@@ -63,6 +63,7 @@ export interface InspectorViewState {
     scroll: number;
 }
 export declare function transcriptLines(entries: readonly SessionEntry[]): string[];
+export declare function transcriptFileLines(path: string): string[];
 export declare function matchSession(query: string, sessions: readonly SessionInfo[]): SessionInfo;
 export declare function loadSessionReport(path: string, home?: string): Promise<SessionReport>;
 export declare function renderInspector(report: SessionReport, state: InspectorViewState, width?: number, height?: number, highlighter?: (script: string) => string[]): string[];

package/dist/src/session-inspector.js

@@ -45,6 +45,9 @@ export function transcriptLines(entries) {
         return index ? ["", ...lines] : lines;
     });
 }
+export function transcriptFileLines(path) {
+    return transcriptLines(SessionManager.open(path).buildContextEntries());
+}
 function mergedModels(groups) {
     const totals = new Map();
     for (const group of groups)

package/dist/src/workflow-evals.js

@@ -707,6 +707,7 @@ export async function replayWorkflowScript(script, args = null, signal) {
                 active -= 1;
             }
         },
+        worktree: async () => ({ path: "/worktrees/eval", branch: "eval-branch" }),
         phase: (name) => { phases.push(name); },
         log: (message) => { logs.push(message); },
     }, signal);
@@ -860,7 +861,7 @@ function semanticJudgePrompt(evalCase, calls, cwd, home) {
         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")}`;
 }
 async function runSemanticJudge(input, calls, cwd, home, sessionDir, maxCost) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-extensible-workflows",
-  "version": "1.0.1",
+  "version": "2.0.0",
   "description": "Deterministic multi-agent workflow orchestration for Pi",
   "homepage": "https://vekexasia.github.io/pi-extensible-workflows/",
   "repository": {
@@ -31,8 +31,9 @@
     "build": "rm -rf dist && tsc -p tsconfig.json && chmod +x dist/src/cli.js",
     "inspect": "node dist/src/cli.js inspect",
     "lint": "eslint .",
-    "test": "npm run build && node --test 'dist/test/*.test.js'",
-    "acceptance": "npm run build && node --test dist/test/runtime-acceptance.test.js",
+    "test": "npm run build && TEST_FILES='dist/test/*.test.js' npm run test:run",
+    "test:run": "tmp=$(mktemp -d); trap 'rm -rf \"$tmp\"' EXIT; TMPDIR=\"$tmp\" node --test $TEST_FILES",
+    "acceptance": "npm run build && TEST_FILES='dist/test/runtime-acceptance.test.js' npm run test:run",
     "docs:check": "node scripts/check-docs.mjs",
     "check": "npm run lint && npm test && npm run docs:check",
     "evals": "npm run build && node dist/src/workflow-evals.js",

package/skills/pi-extensible-workflows/SKILL.md

@@ -4,87 +4,80 @@ description: Use when the task is complex enough to require multiple subagents o
 ---
 
 # pi-extensible-workflows
-
-Use `workflow` exclusively for genuinely multi-agent orchestration. For one agent, use ordinary tools or `Agent` directly. Do not wrap a single agent in a workflow; define distinct responsibilities and keep the result flow explicit.
+Use `workflow` only for genuinely multi-agent orchestration; one agent uses ordinary tools or `Agent` directly. Give phases distinct responsibilities and keep result flow explicit.
 
 ## Pattern
-
 ```js
-const reportSchema = {
-  type: "object",
-  properties: {
-    summary: { type: "string" },
-    findings: { type: "array", items: { type: "string" } },
-  },
-  required: ["summary", "findings"],
-  additionalProperties: false,
-};
+const reportSchema = { type: "object", properties: { summary: { type: "string" }, findings: { type: "array", items: { type: "string" } } }, required: ["summary", "findings"], additionalProperties: false };
 
 const reports = await parallel("research", {
   first: () => agent("Research the first target.", { role: "scout", outputSchema: reportSchema }),
   second: () => agent("Research the second target.", { role: "scout", outputSchema: reportSchema }),
 });
 
-// Add a downstream agent only when synthesis or independent review is a real phase.
 return agent(
   prompt("Review these reports:\n\n{reports}", { reports }),
   { role: "reviewer", outputSchema: reportSchema },
 );
 ```
 
-To pass structured input from the main agent, include `args`:
+Pass structured input from the main agent with `args`:
 ```json
 { "workflow": "workflowName", "args": { "issue": 42 } }
 ```
-Inside the workflow, read `args.issue`; omitted `args` is `null`.
-Use `workflow_stop` with the exact run ID to stop an active background run from the current Pi session.
-If `workflow_catalog` is available, call it once before creating the first workflow for a task. Use the returned global functions, variables, registered workflows, and configured model aliases as needed for the rest of that task. Alias targets are catalog metadata, not an availability probe. Do not try to reinvent already exposed functions.
+Inside the workflow, read `args.issue` (`args` is `null` when omitted). `workflow_stop` requires the exact run ID; foreground results retain their value and completed `runId`, while background launches return `runId` immediately. A terminal `parentRunId` reuses matching named `withWorktree` scopes; unnamed or missing names create new worktrees.
+If `workflow_catalog` is available, call it once before creating the first workflow for a task. The name-less result is a compact index with launch-ready input schemas, descriptions, variables, and configured model aliases. Use those inputs to launch registered functions directly with `{ "workflow": "name", "args": { ... } }`; their input and output schemas are enforced. Request full detail with `{ "name": "name" }` only when composing a function programmatically or inspecting its output contract and extension metadata; do not load full definitions unconditionally. Alias targets are catalog metadata, not an availability probe. Do not try to reinvent already exposed functions.
 
-Pass downstream only needed results. Workflow JavaScript has no imports, filesystem, network, process, or timers; delegate such work to agents with the required tools.
+Workflow JavaScript has no imports, filesystem, network, process, or timers. Delegate that work to agents. `shell(command, options)` is the trusted host RPC for deterministic gates: it inherits the workflow or active-worktree cwd, merges string `env` overrides, and returns `{ exitCode, stdout, stderr }`; nonzero exits are results, but launch failures and timeouts fail with `SHELL_FAILED`.
 
-## `agent()` options
+Use a bounded verification loop when command output controls the gate:
+```js
+return withWorktree("fix-tests", async ({ path, branch }) => {
+  for (let attempt = 1; attempt <= 5; attempt += 1) {
+    const tests = await shell("yarn test", { env: { CI: "1" } });
+    if (tests.exitCode === 0) return { path, branch, tests };
+    await agent(prompt("Fix these failures:\n\n{output}", { output: tests.stderr || tests.stdout }));
+  }
+  return { path, branch, tests: await shell("yarn test", { env: { CI: "1" } }) };
+});
+```
+Shell results are journaled only after process exit and RPC validation. A host crash after side effects but before journaling can rerun the command on resume; use `shell()` mainly for verification and bounded gates, not exactly-once mutations.
 
+## `agent()` options
 ```typescript
 interface AgentOptions {
-  label?: string; // optional non-empty display name
-  model?: string; // configured alias or provider/model[:thinking]
-  thinking?: "off" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
-  role?: string; // one of the available workflow roles
-  tools?: string[]; // [] = no tools; omitted uses role or launch tools
-  outputSchema?: JsonSchema;
-  retries?: number; // non-negative; use for safe, repeatable work
-  timeoutMs?: number | null; // positive milliseconds; null means unlimited
+  label?: string; model?: string; role?: string; tools?: string[];
+  thinking?: "off" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max"; outputSchema?: JsonSchema; retries?: number; timeoutMs?: number | null;
 }
 ```
 
-Extensions may define additional JSON-compatible agent option keys such as `advisor: true`. Core-owned keys still use the validation and role constraints above; extension options are passed to setup hooks and native setup but are not inherited by child agents.
-
-Agent calls are unnamed. Direct `agent(...)` calls receive hidden source call-site identity; JavaScript aliases for workflow calls are unsupported. Calls from one source call site must not race outside `parallel` or `pipeline`, whose structural keys keep replay deterministic.
+Extensions may add JSON-compatible agent options such as `advisor: true`; core keys retain validation and role constraints. Extension options go to setup hooks/native setup and are not inherited by child agents.
 
-## Shared worktree scope
+Agent calls are unnamed. Direct calls receive hidden source call-site identity; aliases are unsupported, and calls from one source site must not race outside `parallel` or `pipeline`, whose structural keys make replay deterministic.
 
-Use `withWorktree(callback)` or `withWorktree(name, callback)` when top-level agents should collaborate in one worktree:
+## Persistent conversations
+Use `conversation(name, options)` when several agent turns should share a persisted transcript and build on one another. Unlike independent `agent(prompt, options)` calls, the returned handle continues from the last successful turn:
 
 ```js
-const results = await withWorktree("implementation", async () => parallel("implementation", {
-  api: () => agent("Implement the API"),
-  tests: () => agent("Add integration tests"),
-}));
+const handle = conversation("developer", { role: "developer" });
+const findings = await handle.run("Inspect the implementation.");
+const fix = await handle.run("Now propose the smallest fix.");
+return { findings, fix };
 ```
 
-The callback result is returned unchanged and the worktree is created only when the first enclosed agent launches. Concurrent agents share mutable files, so give them non-conflicting work or coordinate explicitly.
-
-`parallel()` tasks may call any workflow function, not only `agent()`:
+Await each `handle.run(prompt, turnOptions)` call before starting the next one; conversation turns must be sequential and cannot overlap. Conversation creation accepts the same execution-policy options as `agent()`. `timeoutMs` and `retries` passed to `run()` are turn-local, so a failed turn does not advance the persisted conversation head.
 
+## Worktrees
+Use `withWorktree(callback)` or `withWorktree(name, callback)` for top-level agents that collaborate in one worktree:
 ```js
-const results = await parallel("checks", {
-  security: () => reviewRepository({ focus: "security" }),
-  release: () => reviewRepository({ focus: "release readiness" }),
+const result = await withWorktree("issue", async ({ path, branch }) => {
+  const report = await agent("Implement the issue");
+  return { path, branch, report };
 });
 ```
+Entering the scope materializes its worktree before the callback. The callback receives a frozen reference containing only the real string `path` and `branch`; callbacks may ignore the argument, and their bare return value is preserved. Concurrent agents share mutable files, so assign non-conflicting work or coordinate explicitly.
 
-Use separate named scopes when each parallel branch needs its own worktree:
-
+Branches may call any workflow function, not only `agent()`. Use separate named scopes when parallel branches need isolated worktrees:
 ```js
 const results = await parallel("implementation", {
   api: () => withWorktree("api", () => agent("Implement the API")),
@@ -92,26 +85,17 @@ const results = await parallel("implementation", {
 });
 ```
 
-Registered extension functions receive `withWorktree` in their context, so they may create a shared scope internally. They can compose other registered functions without importing their source:
-```ts
-const report = await context.invoke("reviewRepository", { focus: "security" });
-```
-Their public inputs and outputs must remain JSON; callbacks cannot cross the extension-function boundary.
+Registered extension functions receive `withWorktree` in context and can compose other registered functions with `context.invoke("reviewRepository", { focus: "security" })`. Their public inputs and outputs remain JSON; callbacks cannot cross the extension boundary.
 
 ## Rules
-
-- Do not create a workflow for one agent. Phases must have distinct work.
-- Use `log(messageString)` in the script to surface brief status messages to the operator.
-- A role owns its execution policy. When `role` is present, do not also set `model`, `thinking`, or `tools`; only task-specific options such as `outputSchema`, retries, timeout, or a `withWorktree` scope may accompany it.
-- Use `parallel()` for independent tasks with different flows. Use `pipeline()` when each keyed item passes through the same ordered stages; do not duplicate identical stage chains inside `parallel()` branches.
-- Call shapes are `parallel(operationName, tasksRecord)` and `pipeline(operationName, itemsRecord, stagesRecord)`; object keys are stable task, item, and stage names.
-- Preserve item metadata in workflow code between pipeline stages instead of requiring agents to echo it through `outputSchema`.
-- Repeated work uses a JavaScript loop; each direct `agent(...)` call receives deterministic call-site and occurrence identity.
+- Use `log(messageString)` for brief operator status.
+- A role owns execution policy: with `role`, do not set `model`, `thinking`, or `tools`; only task options such as `outputSchema`, retries, timeout, or a `withWorktree` scope may accompany it.
+- Use `parallel()` for independent tasks with different flows and `pipeline()` when every keyed item follows the same ordered stages; do not duplicate identical chains in `parallel()`. Signatures are `parallel(operationName, tasksRecord)` and `pipeline(operationName, itemsRecord, stagesRecord)`; keys are stable task, item, and stage names.
+- Preserve item metadata in workflow code between pipeline stages instead of making agents echo it through `outputSchema`.
+- Use a JavaScript loop for repeated work; each direct `agent(...)` call gets deterministic call-site and occurrence identity.
 - Runs default to background; set tool-call `foreground: true` when asked to wait.
-- Add `budget` only when the run needs aggregate limits. The only valid dimension names are exactly `tokens`, `costUsd`, `durationMs`, and `agentLaunches` (never `cost`, `duration`, `launches`, or other shorthand). Each dimension is `{ soft?: number, hard?: number }`; `soft` must be less than `hard`.
-- A `budget_exhausted` run is resumable through `workflow_resume`. Omitted patch values stay unchanged, explicit `null` removes a limit, and any relaxation requires an exact human-approved proposal through `workflow_respond`.
-- `parallel()` and `pipeline()` return keyed bare values. Await results before use.
-- Interpolate results with `prompt("...{value}", { value })`; placeholders in plain strings stay literal.
-- Use `outputSchema` only when another phase must compare, aggregate, or validate the result. Never add it to a final agent whose prose is returned directly. Keep only fields the consumer needs, and avoid repeating the same evidence in multiple schemas.
-- With `outputSchema`, agents must call `workflow_result`; one repair prompt is built in. Omit `retries` unless an additional retry is justified and the work is idempotent.
-- Do not add "persona" specs to the prompt for agents. Just define the task.
+- Add `budget` only for aggregate limits. Valid dimensions are exactly `tokens`, `costUsd`, `durationMs`, and `agentLaunches`; each is `{ soft?: number, hard?: number }` with `soft < hard`.
+- `budget_exhausted` runs resume through `workflow_resume`: omitted patch values stay unchanged, `null` removes a limit, and tightening resumes directly. Relaxation stores the exact proposal and returns `{ state: "awaiting_approval", proposalId }`; `workflow_respond` must answer that ID. Rejection leaves the run exhausted; approval applies the budget and cold-resumes it.
+- `parallel()` and `pipeline()` return keyed bare values; await them before use. Interpolate results with `prompt("...{value}", { value })`; placeholders in plain strings remain literal.
+- Use `outputSchema` only when another phase compares, aggregates, or validates a result, never for final prose. Keep only consumer-needed fields and avoid repeated evidence. Agents with it must call `workflow_result`; one repair prompt is built in. Omit `retries` unless an extra retry is justified and work is idempotent.
+- Do not add persona specifications to agent prompts; define the task directly.