pi-extensible-workflows 0.3.0

package/dist/src/persistence.d.ts

@@ -0,0 +1,90 @@
+import type { JsonValue, LaunchSnapshot, RunRecord } from "./index.js";
+import type { OwnershipRecord } from "./agent-execution.js";
+export interface NativeSessionReference {
+    sessionId: string;
+    sessionFile: string;
+}
+export interface EffectiveSystemPrompt {
+    sessionId: string;
+    attempt: number;
+    turn: number;
+    sha256: string;
+    prompt: string;
+}
+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;
+}
+export type PersistedOwnershipNode = OwnershipRecord;
+export interface WorktreeReference {
+    owner: string;
+    path: string;
+    branch: string;
+    cwd: string;
+    base: string;
+}
+export declare function projectStorageKey(cwd: string): string;
+export declare function runsDirectory(cwd: string, sessionId: string, home?: string): string;
+export declare class SessionLease {
+    #private;
+    readonly path: string;
+    readonly token: string;
+    constructor(path: string, token: string);
+    get active(): boolean;
+    release(): Promise<void>;
+}
+export declare function acquireSessionLease(cwd: string, sessionId: string, home?: string): Promise<SessionLease>;
+export declare function listRunIds(cwd: string, sessionId: string, home?: string): Promise<string[]>;
+export declare function structuralPath(...names: string[]): string;
+export declare class RunStore {
+    readonly cwd: string;
+    readonly sessionId: string;
+    readonly runId: string;
+    readonly directory: string;
+    private journalWrite;
+    private stateWrite;
+    private worktreeWrite;
+    private snapshotWrite;
+    private systemPromptWrite;
+    constructor(cwd: string, sessionId: string, runId: string, home?: string);
+    create(run: PersistedRun, snapshot: Readonly<LaunchSnapshot>): Promise<void>;
+    isComplete(): Promise<boolean>;
+    load(): Promise<{
+        run: PersistedRun;
+        snapshot: Readonly<LaunchSnapshot>;
+    }>;
+    saveState(run: PersistedRun): Promise<void>;
+    updateState(update: (run: PersistedRun) => PersistedRun | Promise<PersistedRun>): Promise<PersistedRun>;
+    saveOwnership(nodes: readonly PersistedOwnershipNode[]): Promise<void>;
+    loadOwnership(): Promise<readonly PersistedOwnershipNode[]>;
+    systemPromptPath(): string;
+    recordSystemPrompt(entry: Omit<EffectiveSystemPrompt, "sha256">): Promise<void>;
+    systemPrompts(): Promise<readonly EffectiveSystemPrompt[]>;
+    private updateJournal;
+    complete(path: string, value: JsonValue): Promise<void>;
+    replay(path: string): Promise<CompletedOperation | undefined>;
+    awaitCheckpoint(checkpoint: AwaitingCheckpoint): Promise<boolean | undefined>;
+    awaitingCheckpoints(): Promise<readonly AwaitingCheckpoint[]>;
+    answerCheckpoint(name: string, approved: boolean): Promise<AwaitingCheckpoint | undefined>;
+    private expectedWorktree;
+    private markerPath;
+    private structuralWorktree;
+    private cleanupMarker;
+    private cleanupOrphanWorktrees;
+    validateWorktree(owner: string, cwd?: string): Promise<WorktreeReference>;
+    worktree(owner: string): Promise<WorktreeReference>;
+    snapshotWorktree(owner: string): Promise<string>;
+    worktrees(): Promise<readonly WorktreeReference[]>;
+    changedWorktrees(): Promise<readonly WorktreeReference[]>;
+    saveResult(value: JsonValue): Promise<string>;
+    delete(confirmed: boolean): Promise<void>;
+}

package/dist/src/persistence.js

@@ -0,0 +1,530 @@
+import { createHash, randomUUID } from "node:crypto";
+import { execFile } from "node:child_process";
+import { access, link, mkdir, open, readFile, readdir, rename, rm, stat, writeFile } from "node:fs/promises";
+import { basename, dirname, join, relative, resolve, sep } from "node:path";
+import { homedir } from "node:os";
+import { promisify } from "node:util";
+import { loadLaunchSnapshot, WorkflowError } from "./index.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",
+    GIT_AUTHOR_DATE: "2000-01-01T00:00:00Z", GIT_COMMITTER_DATE: "2000-01-01T00:00:00Z",
+};
+function safePart(value) { return value.replace(/[^a-zA-Z0-9._-]/g, "_"); }
+export function projectStorageKey(cwd) {
+    const exact = resolve(cwd);
+    const slug = safePart(basename(exact)) || "root";
+    return `${slug}-${createHash("sha256").update(exact).digest("hex").slice(0, 12)}`;
+}
+export function runsDirectory(cwd, sessionId, home = homedir()) {
+    return join(home, ".pi", "workflows", "projects", projectStorageKey(cwd), "sessions", safePart(sessionId), "runs");
+}
+const SESSION_OWNER_FILE = "owner.json";
+const SESSION_OWNER_WRITE_GRACE_MS = 30_000;
+const RUN_CREATE_TEMP = /^\.([a-zA-Z0-9._-]+)\.(\d+)\.[0-9a-f-]+\.tmp$/;
+async function processAlive(pid, startedAt) {
+    try {
+        process.kill(pid, 0);
+    }
+    catch (error) {
+        return error.code !== "ESRCH";
+    }
+    if (startedAt !== undefined && process.platform === "linux") {
+        try {
+            if ((await stat(`/proc/${String(pid)}`)).ctimeMs > startedAt)
+                return false;
+        }
+        catch (error) {
+            if (error.code === "ENOENT")
+                return false;
+        }
+    }
+    return true;
+}
+function sameOwner(left, right) {
+    if (!left || typeof left !== "object" || !right || typeof right !== "object")
+        return false;
+    const first = left;
+    const second = right;
+    return first.pid === second.pid && first.token === second.token;
+}
+async function restoreLease(path, stale) {
+    try {
+        await link(stale, path);
+    }
+    catch (error) {
+        const code = error.code;
+        if (code !== "EEXIST" && code !== "ENOENT")
+            throw error;
+    }
+    await rm(stale, { force: true });
+}
+async function cleanupRunTemps(directory, entries) {
+    await Promise.all(entries.map(async (entry) => {
+        const match = entry.isDirectory() ? RUN_CREATE_TEMP.exec(entry.name) : undefined;
+        const pid = match?.[2] ? Number(match[2]) : undefined;
+        if (pid && !await processAlive(pid))
+            await rm(join(directory, entry.name), { recursive: true, force: true });
+    }));
+}
+export class SessionLease {
+    path;
+    token;
+    #released = false;
+    constructor(path, token) {
+        this.path = path;
+        this.token = token;
+    }
+    get active() { return !this.#released; }
+    async release() {
+        if (this.#released)
+            return;
+        this.#released = true;
+        try {
+            const owner = JSON.parse(await readFile(this.path, "utf8"));
+            if (owner.token === this.token)
+                await rm(this.path, { force: true });
+        }
+        catch (error) {
+            if (error.code !== "ENOENT")
+                throw error;
+        }
+    }
+}
+export async function acquireSessionLease(cwd, sessionId, home = homedir()) {
+    const directory = runsDirectory(cwd, sessionId, home);
+    await mkdir(directory, { recursive: true, mode: 0o700 });
+    const path = join(directory, SESSION_OWNER_FILE);
+    for (;;) {
+        const token = randomUUID();
+        const owner = { pid: process.pid, token, startedAt: Date.now() };
+        try {
+            const handle = await open(path, "wx", 0o600);
+            try {
+                await handle.writeFile(`${JSON.stringify(owner)}\n`, "utf8");
+            }
+            finally {
+                await handle.close();
+            }
+            return new SessionLease(path, token);
+        }
+        catch (error) {
+            if (error.code !== "EEXIST")
+                throw error;
+            let existing;
+            let existingText = "";
+            try {
+                existingText = await readFile(path, "utf8");
+                existing = JSON.parse(existingText);
+                if (typeof existing.pid === "number" && existing.pid > 0 && await processAlive(existing.pid, existing.startedAt))
+                    throw new WorkflowError("RUN_OWNED", `Pi session ${sessionId} is already owned by process ${String(existing.pid)}`);
+            }
+            catch (readError) {
+                if (readError instanceof WorkflowError)
+                    throw readError;
+                if (readError.code === "ENOENT")
+                    continue;
+                const age = await stat(path).then((value) => Date.now() - value.mtimeMs).catch(() => 0);
+                if (age < SESSION_OWNER_WRITE_GRACE_MS)
+                    throw new WorkflowError("RUN_OWNED", `Pi session ${sessionId} has an active ownership lease`);
+                existing = {};
+            }
+            const stale = `${path}.${randomUUID()}.stale`;
+            try {
+                await rename(path, stale);
+                const movedText = await readFile(stale, "utf8");
+                let moved;
+                try {
+                    moved = JSON.parse(movedText);
+                }
+                catch {
+                    if (movedText === existingText)
+                        await rm(stale, { force: true });
+                    else
+                        await restoreLease(path, stale);
+                    continue;
+                }
+                if (!sameOwner(existing, moved)) {
+                    await restoreLease(path, stale);
+                    continue;
+                }
+                await rm(stale, { force: true });
+            }
+            catch (reclaimError) {
+                if (reclaimError.code === "ENOENT")
+                    continue;
+                throw reclaimError;
+            }
+        }
+    }
+}
+export async function listRunIds(cwd, sessionId, home = homedir()) {
+    const directory = runsDirectory(cwd, sessionId, home);
+    try {
+        const entries = await readdir(directory, { withFileTypes: true });
+        await cleanupRunTemps(directory, entries);
+        return entries.filter((entry) => entry.isDirectory() && !entry.name.startsWith(".")).map(({ name }) => name);
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return [];
+        throw error;
+    }
+}
+export function structuralPath(...names) {
+    if (names.length === 0 || names.some((name) => name.trim() === ""))
+        throw new WorkflowError("INVALID_METADATA", "Structural paths require non-empty explicit names");
+    return names.map((name) => encodeURIComponent(name)).join("/");
+}
+async function atomicJson(path, value) {
+    const temporary = `${path}.${String(process.pid)}.${randomUUID()}.tmp`;
+    await writeFile(temporary, `${JSON.stringify(value)}\n`, { encoding: "utf8", mode: 0o600 });
+    await rename(temporary, path);
+}
+async function json(path) { return JSON.parse(await readFile(path, "utf8")); }
+export class RunStore {
+    cwd;
+    sessionId;
+    runId;
+    directory;
+    journalWrite = Promise.resolve();
+    // ponytail: serializes one RunStore instance; cross-process run sharing remains unsupported.
+    stateWrite = Promise.resolve();
+    worktreeWrite = Promise.resolve();
+    snapshotWrite = Promise.resolve();
+    // ponytail: the session lease prevents concurrent RunStore writers for one run.
+    systemPromptWrite = Promise.resolve();
+    constructor(cwd, sessionId, runId, home = homedir()) {
+        this.cwd = cwd;
+        this.sessionId = sessionId;
+        this.runId = runId;
+        this.cwd = resolve(cwd);
+        this.directory = join(runsDirectory(this.cwd, sessionId, home), safePart(runId));
+    }
+    async create(run, snapshot) {
+        if (resolve(run.cwd) !== this.cwd || run.sessionId !== this.sessionId || run.id !== this.runId)
+            throw new WorkflowError("INTERNAL_ERROR", "Run identity does not match its session-scoped store");
+        const temporary = join(dirname(this.directory), `.${safePart(this.runId)}.${String(process.pid)}.${randomUUID()}.tmp`);
+        await mkdir(dirname(this.directory), { recursive: true, mode: 0o700 });
+        await mkdir(temporary, { mode: 0o700 });
+        try {
+            await atomicJson(join(temporary, "snapshot.json"), snapshot);
+            await atomicJson(join(temporary, "journal.json"), { completed: {}, awaiting: {} });
+            await atomicJson(join(temporary, "ownership.json"), []);
+            await atomicJson(join(temporary, "worktrees.json"), []);
+            await atomicJson(join(temporary, "state.json"), run);
+            await atomicJson(join(temporary, "system-prompts.json"), { version: 1, entries: [] });
+            await rename(temporary, this.directory);
+        }
+        catch (error) {
+            await rm(temporary, { recursive: true, force: true });
+            throw error;
+        }
+    }
+    async isComplete() {
+        try {
+            await Promise.all([access(join(this.directory, "snapshot.json")), access(join(this.directory, "journal.json")), access(join(this.directory, "ownership.json")), access(join(this.directory, "state.json"))]);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    async load() {
+        await this.stateWrite;
+        const run = await json(join(this.directory, "state.json"));
+        if (resolve(run.cwd) !== this.cwd || run.sessionId !== this.sessionId || run.id !== this.runId)
+            throw new WorkflowError("RESUME_INCOMPATIBLE", "Persisted run belongs to another cwd or Pi session");
+        return { run, snapshot: loadLaunchSnapshot(await json(join(this.directory, "snapshot.json"))) };
+    }
+    async saveState(run) {
+        const write = this.stateWrite.then(async () => {
+            if (resolve(run.cwd) !== this.cwd || run.sessionId !== this.sessionId || run.id !== this.runId)
+                throw new WorkflowError("INTERNAL_ERROR", "Run identity does not match its session-scoped store");
+            await atomicJson(join(this.directory, "state.json"), run);
+        });
+        this.stateWrite = write.catch(() => undefined);
+        await write;
+    }
+    async updateState(update) {
+        let result;
+        const write = this.stateWrite.then(async () => {
+            const current = await json(join(this.directory, "state.json"));
+            if (resolve(current.cwd) !== this.cwd || current.sessionId !== this.sessionId || current.id !== this.runId)
+                throw new WorkflowError("RESUME_INCOMPATIBLE", "Persisted run belongs to another cwd or Pi session");
+            result = await update(current);
+            if (resolve(result.cwd) !== this.cwd || result.sessionId !== this.sessionId || result.id !== this.runId)
+                throw new WorkflowError("INTERNAL_ERROR", "Run identity does not match its session-scoped store");
+            await atomicJson(join(this.directory, "state.json"), result);
+        });
+        this.stateWrite = write.catch(() => undefined);
+        await write;
+        return result;
+    }
+    async saveOwnership(nodes) {
+        await atomicJson(join(this.directory, "ownership.json"), nodes);
+    }
+    async loadOwnership() {
+        return json(join(this.directory, "ownership.json"));
+    }
+    systemPromptPath() { return join(this.directory, "system-prompts.json"); }
+    async recordSystemPrompt(entry) {
+        const write = this.systemPromptWrite.then(async () => {
+            const path = this.systemPromptPath();
+            const artifact = await json(path).catch((error) => { if (error.code === "ENOENT")
+                return { version: 1, entries: [] }; throw error; });
+            artifact.entries.push({ ...entry, sha256: createHash("sha256").update(entry.prompt).digest("hex") });
+            await atomicJson(path, artifact);
+        });
+        this.systemPromptWrite = write.catch(() => undefined);
+        await write;
+    }
+    async systemPrompts() {
+        await this.systemPromptWrite;
+        return (await json(this.systemPromptPath()).catch((error) => { if (error.code === "ENOENT")
+            return { version: 1, entries: [] }; throw error; })).entries;
+    }
+    async updateJournal(update) {
+        let result;
+        const write = this.journalWrite.then(async () => {
+            const journalPath = join(this.directory, "journal.json");
+            const journal = await json(journalPath);
+            journal.awaiting ??= {};
+            result = await update(journal);
+            await atomicJson(journalPath, journal);
+        });
+        this.journalWrite = write.catch(() => undefined);
+        await write;
+        return result;
+    }
+    async complete(path, value) {
+        await this.updateJournal((journal) => {
+            if (journal.completed[path])
+                throw new WorkflowError("DUPLICATE_NAME", `Completed structural path already exists: ${path}`);
+            journal.completed[path] = { path, value };
+        });
+    }
+    async replay(path) {
+        await this.journalWrite;
+        return (await json(join(this.directory, "journal.json"))).completed[path];
+    }
+    async awaitCheckpoint(checkpoint) {
+        return this.updateJournal((journal) => {
+            const completed = journal.completed[checkpoint.path];
+            if (completed)
+                return completed.value;
+            journal.awaiting[checkpoint.path] = checkpoint;
+            return undefined;
+        });
+    }
+    async awaitingCheckpoints() {
+        await this.journalWrite;
+        const journal = await json(join(this.directory, "journal.json"));
+        return Object.values(journal.awaiting ?? {});
+    }
+    async answerCheckpoint(name, approved) {
+        return this.updateJournal((journal) => {
+            const checkpoint = Object.values(journal.awaiting).find((item) => item.name === name);
+            if (!checkpoint || journal.completed[checkpoint.path])
+                return undefined;
+            journal.completed[checkpoint.path] = { path: checkpoint.path, value: approved };
+            journal.awaiting = Object.fromEntries(Object.entries(journal.awaiting).filter(([path]) => path !== checkpoint.path));
+            return checkpoint;
+        });
+    }
+    expectedWorktree(owner) {
+        const key = createHash("sha256").update(`${this.sessionId}\0${this.runId}\0${owner}`).digest("hex").slice(0, 16);
+        return { path: join(this.directory, "worktrees", key), branch: `pi-extensible-workflows/${safePart(this.runId)}/${key}` };
+    }
+    markerPath(owner) {
+        const key = createHash("sha256").update(`${this.sessionId}\0${this.runId}\0${owner}`).digest("hex").slice(0, 16);
+        return join(this.directory, `worktree-${key}.creating`);
+    }
+    structuralWorktree(owner, record) {
+        if (!record || typeof record !== "object")
+            throw new Error(`Invalid worktree record for ${owner}`);
+        const candidate = record;
+        const expected = this.expectedWorktree(owner);
+        const relativePath = typeof candidate.path === "string" ? relative(this.directory, candidate.path) : "..";
+        const relativeCwd = typeof candidate.path === "string" && typeof candidate.cwd === "string" ? relative(candidate.path, candidate.cwd) : "..";
+        if (candidate.owner !== owner || typeof candidate.path !== "string" || typeof candidate.branch !== "string" || typeof candidate.cwd !== "string" || typeof candidate.base !== "string" || resolve(candidate.path) !== expected.path || candidate.branch !== expected.branch || relativePath === ".." || relativePath.startsWith(`..${sep}`) || relativeCwd === ".." || relativeCwd.startsWith(`..${sep}`))
+            throw new Error(`Invalid worktree record for ${owner}`);
+        return candidate;
+    }
+    async cleanupMarker(markerPath) {
+        let marker;
+        try {
+            marker = await json(markerPath);
+        }
+        catch {
+            return;
+        }
+        if (typeof marker.owner !== "string" || typeof marker.base !== "string")
+            return;
+        const expected = this.expectedWorktree(marker.owner);
+        if (marker.path !== expected.path || marker.branch !== expected.branch)
+            return;
+        const root = await git(this.cwd, ["rev-parse", "--show-toplevel"]).then((value) => value.trim()).catch(() => "");
+        if (!root)
+            return;
+        const branchBase = await git(root, ["rev-parse", "--verify", `${expected.branch}^{commit}`]).then((value) => value.trim()).catch(() => "");
+        if (branchBase !== marker.base)
+            return;
+        await git(root, ["worktree", "remove", "--force", expected.path]).catch(() => undefined);
+        await git(root, ["branch", "-D", expected.branch]).catch(() => undefined);
+        await rm(expected.path, { recursive: true, force: true });
+        await rm(markerPath, { force: true });
+    }
+    async cleanupOrphanWorktrees() {
+        const entries = await readdir(this.directory).catch(() => []);
+        for (const entry of entries.filter((name) => name.endsWith(".creating")))
+            await this.cleanupMarker(join(this.directory, entry));
+    }
+    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;
+        }
+        catch (error) {
+            throw error instanceof WorkflowError && error.code === "WORKTREE_FAILED" ? error : new WorkflowError("WORKTREE_FAILED", error instanceof Error ? error.message : String(error));
+        }
+    }
+    async worktree(owner) {
+        const write = this.worktreeWrite.then(async () => {
+            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 existing = records.find((record) => record.owner === owner);
+            if (existing)
+                return this.validateWorktree(owner);
+            const { path, branch } = this.expectedWorktree(owner);
+            const index = join(this.directory, `index-${basename(path)}`);
+            const markerPath = this.markerPath(owner);
+            let branchCreated = false;
+            let worktreeCreated = false;
+            try {
+                const root = (await git(this.cwd, ["rev-parse", "--show-toplevel"])).trim();
+                const launchRelative = relative(root, this.cwd);
+                if (launchRelative.startsWith(".."))
+                    throw new Error("launch cwd is outside the repository");
+                await this.cleanupMarker(markerPath);
+                await mkdir(dirname(path), { recursive: true, mode: 0o700 });
+                await git(root, ["read-tree", "HEAD"], { GIT_INDEX_FILE: index });
+                await git(root, ["add", "-A"], { GIT_INDEX_FILE: index });
+                const tree = (await git(root, ["write-tree"], { GIT_INDEX_FILE: index })).trim();
+                const commit = (await git(root, ["commit-tree", tree, "-p", "HEAD", "-m", "pi-extensible-workflows runtime snapshot"], { GIT_INDEX_FILE: index, ...gitIdentity })).trim();
+                const record = { owner, path, branch, cwd: join(path, launchRelative), base: commit };
+                await atomicJson(markerPath, { owner, path, branch, base: commit });
+                await git(root, ["branch", branch, commit]);
+                branchCreated = true;
+                await git(root, ["worktree", "add", "--no-checkout", path, branch]);
+                worktreeCreated = true;
+                await git(path, ["checkout", "--force", branch]);
+                await rm(index, { force: true });
+                await atomicJson(recordsPath, [...records, record]);
+                await rm(markerPath, { force: true });
+                return record;
+            }
+            catch (error) {
+                await rm(index, { force: true });
+                if (worktreeCreated)
+                    await git(this.cwd, ["worktree", "remove", "--force", path]).catch(() => undefined);
+                if (branchCreated)
+                    await git(this.cwd, ["branch", "-D", branch]).catch(() => undefined);
+                await rm(markerPath, { force: true });
+                try {
+                    const persisted = await json(recordsPath);
+                    const matches = persisted.filter((candidate) => candidate && typeof candidate === "object" && candidate.owner === owner);
+                    if (matches.length === 1) {
+                        this.structuralWorktree(owner, matches[0]);
+                        records = persisted.filter((candidate) => candidate !== matches[0]);
+                        await atomicJson(recordsPath, records);
+                    }
+                }
+                catch { /* Ownership changed or disappeared: do not delete anything. */ }
+                throw new WorkflowError("WORKTREE_FAILED", error instanceof Error ? error.message : String(error));
+            }
+        });
+        this.worktreeWrite = write.then(() => undefined, () => undefined);
+        return write;
+    }
+    async snapshotWorktree(owner) {
+        try {
+            const write = this.snapshotWrite.then(async () => {
+                const record = await this.worktree(owner);
+                await git(record.path, ["add", "-A"]);
+                if ((await git(record.path, ["status", "--porcelain"])).trim())
+                    await git(record.path, ["commit", "-m", "pi-extensible-workflows runtime snapshot"], gitIdentity);
+                return (await git(record.path, ["rev-parse", "HEAD"])).trim();
+            });
+            this.snapshotWrite = write.then(() => undefined, () => undefined);
+            return await write;
+        }
+        catch (error) {
+            throw error instanceof WorkflowError && error.code === "WORKTREE_FAILED" ? error : new WorkflowError("WORKTREE_FAILED", error instanceof Error ? error.message : String(error));
+        }
+    }
+    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 {
+            return await this.validateWorktree(record.owner);
+        }
+        catch {
+            return undefined;
+        } }));
+        return validated.filter((record) => record !== undefined);
+    }
+    async changedWorktrees() {
+        const changed = [];
+        for (const valid of await this.worktrees()) {
+            try {
+                await git(valid.path, ["diff", "--quiet", valid.base, "HEAD"]);
+            }
+            catch {
+                changed.push(valid);
+            }
+        }
+        return changed;
+    }
+    async saveResult(value) {
+        const path = join(this.directory, "result.json");
+        await atomicJson(path, value);
+        return path;
+    }
+    async delete(confirmed) {
+        if (!confirmed)
+            throw new WorkflowError("CANCELLED", "Run deletion requires confirmation");
+        const records = await json(join(this.directory, "worktrees.json")).catch((error) => { if (error.code === "ENOENT")
+            return []; throw error; });
+        const validated = records.map((record) => {
+            try {
+                if (!record || typeof record !== "object" || typeof record.owner !== "string")
+                    throw new Error("Invalid worktree record");
+                return this.structuralWorktree(record.owner, record);
+            }
+            catch (error) {
+                throw new WorkflowError("WORKTREE_FAILED", error instanceof Error ? error.message : String(error));
+            }
+        });
+        await this.cleanupOrphanWorktrees();
+        for (const record of validated) {
+            await git(this.cwd, ["worktree", "remove", "--force", record.path]).catch(() => undefined);
+            await git(this.cwd, ["branch", "-D", record.branch]).catch(() => undefined);
+        }
+        await rm(this.directory, { recursive: true, force: true });
+    }
+}
+async function git(cwd, args, extraEnv = {}) {
+    const { stdout } = await execute("git", ["-c", "core.hooksPath=/dev/null", "-c", "commit.gpgSign=false", ...args], { cwd, env: { ...process.env, ...extraEnv }, encoding: "utf8" });
+    return stdout;
+}

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

@@ -0,0 +1,59 @@
+import { type SessionEntry, type SessionInfo } from "@earendil-works/pi-coding-agent";
+import { type ModelSpec, type StaticWorkflowCall } from "./index.js";
+export interface ModelUsage {
+    model: string;
+    cost: number;
+}
+export interface AttemptReport {
+    attempt: number;
+    prompt: string;
+    model: string;
+    thinking?: ModelSpec["thinking"];
+    cost: number;
+    models: readonly ModelUsage[];
+    error?: string;
+}
+export interface AgentReport {
+    name: string;
+    label?: string;
+    state: string;
+    role?: string;
+    model: string;
+    thinking?: ModelSpec["thinking"];
+    cost: number;
+    attempts: readonly AttemptReport[];
+}
+export interface WorkflowReport {
+    name: string;
+    description?: string;
+    status: string;
+    runId?: string;
+    script?: string;
+    calls: readonly StaticWorkflowCall[];
+    parseError?: string;
+    cost: number;
+    models: readonly ModelUsage[];
+    agents: readonly AgentReport[];
+}
+export interface SessionReport {
+    id: string;
+    cwd: string;
+    path: string;
+    cost: number;
+    models: readonly ModelUsage[];
+    workflows: readonly WorkflowReport[];
+    totalCost: number;
+    totalModels: readonly ModelUsage[];
+}
+export interface InspectorViewState {
+    view: "list" | "detail" | "script";
+    selected: number;
+    scroll: number;
+}
+export declare function transcriptLines(entries: readonly SessionEntry[]): 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[];
+export declare function showSessionInspector(report: SessionReport): Promise<void>;
+export declare function resolveSession(query: string, sessionDir?: string | undefined): Promise<SessionInfo>;
+export declare function runSessionInspector(sessionId?: string): Promise<void>;