pi-agent-replicate 0.0.0-stage → 1.4.1

package/pi-extension/subagents/replica-background.js

@@ -0,0 +1,32 @@
+import { fork } from "node:child_process";
+import { fileURLToPath } from "node:url";
+/** Await costly durable host work without blocking Pi's input or model loop. */
+export function runReplicaBackground(request) {
+    return new Promise((resolve, reject) => {
+        const child = fork(fileURLToPath(new URL("./replica-worker.js", import.meta.url)), [], {
+            // A pane handoff must not signal the worker through the old terminal process group.
+            detached: true, execArgv: [], stdio: ["ignore", "ignore", "pipe", "ipc"],
+        });
+        let stderr = "";
+        let reply;
+        let failure;
+        child.stderr?.on("data", (chunk) => { stderr = (stderr + String(chunk)).slice(-8192); });
+        child.on("error", reject);
+        child.on("message", (message) => {
+            if (message.error)
+                failure = new Error(message.error);
+            else
+                reply = message.result;
+        });
+        child.on("exit", (code, signal) => {
+            if (failure)
+                reject(failure);
+            else if (code === 0 && reply)
+                resolve(reply);
+            else
+                reject(new Error(`Replica host worker exited (${signal ?? code}): ${stderr}`));
+        });
+        child.send(request, (error) => { if (error)
+            reject(error); });
+    });
+}

package/pi-extension/subagents/replica-background.ts

@@ -0,0 +1,38 @@
+import { fork } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import type { ReplicaCompletion, ReplicaWork } from "./replica-work.ts";
+import type { SessionLocation } from "./session-binding.ts";
+
+/** One host operation. No model or Pi runtime is loaded in the worker. */
+export type ReplicaBackgroundRequest =
+	| { operation: "complete"; file: string; cwd: string; sessionFile: string; completion: ReplicaCompletion; parent?: SessionLocation }
+	| { operation: "cleanup"; file: string; parentCwd: string; surface: string; child?: { rootDir: string; nodeId: string } };
+export interface ReplicaBackgroundResult {
+	work?: ReplicaWork;
+	cleaned?: boolean;
+}
+
+/** Await costly durable host work without blocking Pi's input or model loop. */
+export function runReplicaBackground(request: ReplicaBackgroundRequest): Promise<ReplicaBackgroundResult> {
+	return new Promise<ReplicaBackgroundResult>((resolve, reject) => {
+		const child = fork(fileURLToPath(new URL("./replica-worker.js", import.meta.url)), [], {
+			// A pane handoff must not signal the worker through the old terminal process group.
+			detached: true, execArgv: [], stdio: ["ignore", "ignore", "pipe", "ipc"],
+		});
+		let stderr = "";
+		let reply: ReplicaBackgroundResult | undefined;
+		let failure: Error | undefined;
+		child.stderr?.on("data", (chunk) => { stderr = (stderr + String(chunk)).slice(-8192); });
+		child.on("error", reject);
+		child.on("message", (message: { result?: ReplicaBackgroundResult; error?: string }) => {
+			if (message.error) failure = new Error(message.error);
+			else reply = message.result;
+		});
+		child.on("exit", (code, signal) => {
+			if (failure) reject(failure);
+			else if (code === 0 && reply) resolve(reply);
+			else reject(new Error(`Replica host worker exited (${signal ?? code}): ${stderr}`));
+		});
+		child.send(request, (error) => { if (error) reject(error); });
+	});
+}

package/pi-extension/subagents/replica-branch.ts

@@ -0,0 +1,45 @@
+import { execFileSync, spawnSync } from "node:child_process";
+import { join } from "node:path";
+import { withLineageMutationGate } from "./lineage.ts";
+
+/** Reserve a readable, unique branch and checkout name without moving parent HEAD or staging. */
+export async function reserveReplicaBranch(cwd: string, title: string, base: string): Promise<string> {
+	const [task, ...origins] = title.split(" ← ");
+	const cyrillic: Record<string, string> = {
+		а: "a", б: "b", в: "v", г: "g", д: "d", е: "e", ё: "yo", ж: "zh", з: "z", и: "i", й: "i",
+		к: "k", л: "l", м: "m", н: "n", о: "o", п: "p", р: "r", с: "s", т: "t", у: "u", ф: "f",
+		х: "kh", ц: "ts", ч: "ch", ш: "sh", щ: "shch", ъ: "", ы: "y", ь: "", э: "e", ю: "yu", я: "ya",
+	};
+	// Herdr drops non-ASCII characters from its default checkout directory.
+	const origin = origins.join("-").normalize("NFKC").toLowerCase()
+		.replace(/[а-яё]/g, character => cyrillic[character])
+		.normalize("NFKD").replace(/\p{M}/gu, "")
+		.replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "") || "session";
+	const stem = `replica/${origin}/${task}`;
+	const git = (args: string[]) => execFileSync("git", args, { cwd, encoding: "utf8", timeout: 10_000 });
+	const gate = join(git(["rev-parse", "--path-format=absolute", "--git-common-dir"]).trim(), "replica-branches");
+	const deadline = Date.now() + 5_000;
+	for (;;) {
+		try {
+			return withLineageMutationGate(gate, () => {
+				// Different origin/task pairs can flatten to the same Herdr directory.
+				// Serialize both checks across all linked checkouts of this repository.
+				const directory = (branch: string) => branch.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+				const occupied = new Set(git(["for-each-ref", "--format=%(refname:strip=2)", "refs/heads"]).trim().split("\n").map(directory));
+				for (let number = 1; ; number++) {
+					const branch = number === 1 ? stem : `${stem}-${number}`;
+					if (occupied.has(directory(branch))) continue;
+					const ref = `refs/heads/${branch}`;
+					// Empty expected old value also guards against external Git writers.
+					const created = spawnSync("git", ["update-ref", ref, base, ""], { cwd, encoding: "utf8", timeout: 10_000 });
+					if (created.error) throw created.error;
+					if (created.status === 0) return branch;
+					if (!git(["for-each-ref", "--format=%(refname)", ref]).split("\n").includes(ref)) throw new Error(`Cannot reserve replica branch ${branch}: ${created.stderr.trim() || created.signal || "Git failed"}`);
+				}
+			});
+		} catch (error) {
+			if (!(error instanceof Error) || error.message !== "Durable state has an active mutation." || Date.now() >= deadline) throw error;
+			await new Promise(resolve => setTimeout(resolve, 25));
+		}
+	}
+}

package/pi-extension/subagents/replica-directory-settings.ts

@@ -0,0 +1,51 @@
+import { mkdirSync, readFileSync, writeFileSync, renameSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { randomUUID } from "node:crypto";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+export type ReplicaDirectoryMode = "worktree" | "shared";
+const fileFor = (cwd: string) => join(cwd, ".pi", "replicate.json");
+
+export function readReplicaDirectoryMode(cwd: string): ReplicaDirectoryMode {
+	let raw: string;
+	try { raw = readFileSync(fileFor(cwd), "utf8"); }
+	catch (error) {
+		if ((error as NodeJS.ErrnoException).code === "ENOENT") return "worktree";
+		throw error;
+	}
+	const value = JSON.parse(raw);
+	if (!value || (value.directoryMode !== "worktree" && value.directoryMode !== "shared")) {
+		throw new Error("Invalid replica directory mode in " + fileFor(cwd));
+	}
+	return value.directoryMode;
+}
+
+function saveMode(cwd: string, mode: ReplicaDirectoryMode): void {
+	const dir = join(cwd, ".pi");
+	mkdirSync(dir, { recursive: true });
+	const file = fileFor(cwd), temp = file + "." + randomUUID() + ".tmp";
+	try {
+		writeFileSync(temp, JSON.stringify({ directoryMode: mode }, null, 2) + "\n", { flag: "wx" });
+		renameSync(temp, file);
+	} finally { rmSync(temp, { force: true }); }
+}
+
+export function registerReplicaDirectoryCommand(pi: ExtensionAPI): void {
+	pi.registerCommand("replica-directory", {
+		description: "Choose where new replicas work for this project",
+		handler: async (args, ctx) => {
+			let mode = args.trim();
+			if (!mode && ctx.hasUI) {
+				const current = readReplicaDirectoryMode(ctx.cwd);
+				mode = await ctx.ui.select(`Replica directory (current: ${current})`, ["worktree", "shared"]) ?? "";
+			}
+			if (!mode) return;
+			if (mode !== "shared" && mode !== "worktree") {
+				ctx.ui.notify("Use /replica-directory shared or /replica-directory worktree.", "error");
+				return;
+			}
+			saveMode(ctx.cwd, mode);
+			ctx.ui.notify(`New replicas will use ${mode === "shared" ? "the shared directory" : "a separate worktree"}.`, "info");
+		},
+	});
+}

package/pi-extension/subagents/replica-history.js

@@ -0,0 +1,22 @@
+import { readFileSync } from "node:fs";
+import { dirname } from "node:path";
+import { materializeResultFile } from "./delivery-files.js";
+import { readSessionBinding } from "./session-binding.js";
+/** Save post-fork answer text without inherited answers, tools or hidden reasoning. */
+export function materializeReplicationHistory(sessionFile, childId, name) {
+    const baseline = readSessionBinding(sessionFile)?.child?.environment.PI_SUBAGENT_REPLICATION_ASSISTANTS;
+    if (!baseline)
+        throw new Error("Replica answer history has no inherited-answer boundary.");
+    const inherited = new Set(JSON.parse(baseline));
+    const answers = readFileSync(sessionFile, "utf8").split("\n").filter(Boolean).flatMap((line) => {
+        const entry = JSON.parse(line);
+        if (entry.type !== "message" || entry.message?.role !== "assistant" || inherited.has(entry.id))
+            return [];
+        const text = entry.message.content.filter((part) => part.type === "text" && typeof part.text === "string").map((part) => part.text).join("\n");
+        return text ? [`## Answer ${entry.id}\n\n${text}`] : [];
+    });
+    return materializeResultFile({
+        sessionsDir: dirname(sessionFile), childSessionId: childId, deliveryId: `history:${childId}`,
+        status: "error", agentName: name, answer: answers.join("\n\n") || "No textual answers were produced after replication.", now: Date.now(),
+    }).path;
+}

package/pi-extension/subagents/replica-history.ts

@@ -0,0 +1,21 @@
+import { readFileSync } from "node:fs";
+import { dirname } from "node:path";
+import { materializeResultFile } from "./delivery-files.ts";
+import { readSessionBinding } from "./session-binding.ts";
+
+/** Save post-fork answer text without inherited answers, tools or hidden reasoning. */
+export function materializeReplicationHistory(sessionFile: string, childId: string, name: string): string {
+	const baseline = readSessionBinding(sessionFile)?.child?.environment.PI_SUBAGENT_REPLICATION_ASSISTANTS;
+	if (!baseline) throw new Error("Replica answer history has no inherited-answer boundary.");
+	const inherited = new Set<string>(JSON.parse(baseline));
+	const answers = readFileSync(sessionFile, "utf8").split("\n").filter(Boolean).flatMap((line) => {
+		const entry = JSON.parse(line);
+		if (entry.type !== "message" || entry.message?.role !== "assistant" || inherited.has(entry.id)) return [];
+		const text = entry.message.content.filter((part: any) => part.type === "text" && typeof part.text === "string").map((part: any) => part.text).join("\n");
+		return text ? [`## Answer ${entry.id}\n\n${text}`] : [];
+	});
+	return materializeResultFile({
+		sessionsDir: dirname(sessionFile), childSessionId: childId, deliveryId: `history:${childId}`,
+		status: "error", agentName: name, answer: answers.join("\n\n") || "No textual answers were produced after replication.", now: Date.now(),
+	}).path;
+}

package/pi-extension/subagents/replica-work.js

@@ -0,0 +1,326 @@
+import { closeSync, existsSync, fsyncSync, mkdirSync, openSync, readFileSync, readlinkSync, readdirSync, realpathSync, writeFileSync } from "node:fs";
+import { execFileSync } from "node:child_process";
+import { dirname, join } from "node:path";
+import { writeBindingFile, readSessionBinding, childSessionLocation, sessionLocationAlive, sessionOwnsPane, launchOwnsPane } from "./session-binding.js";
+import { closeHerdrSurface, getHerdrPaneProcessInfo, listHerdrWorktrees } from "./herdr.js";
+import { applySourceJoin, planSourceJoin, snapshotSource } from "./source-state.js";
+import { processIncarnationAlive, withLineageMutationGate } from "./lineage.js";
+/** Resolve an attempt only inside the session's durable binding store. */
+export function replicaWorkFile(storeDir, id) {
+    if (!/^[a-zA-Z0-9-]+$/.test(id))
+        throw new Error("Invalid replica continuation ID.");
+    return join(storeDir, "replicas", `${id}.json`);
+}
+/** Load known ownership; missing or malformed records are never guessed recoverable. */
+export function readReplicaWork(file) {
+    const value = JSON.parse(readFileSync(file, "utf8"));
+    if (value.version !== 1 || !value.id || !value.parentSessionId || !value.integration || (value.mode === "shared" ? !value.sharedCwd : ((value.mode != null && value.mode !== "worktree") || !value.fork?.commit || !value.joinBase)) ||
+        (value.continuationOwner && (!Number.isInteger(value.continuationOwner.pid) || value.continuationOwner.pid <= 0 || (value.continuationOwner.startTime != null && typeof value.continuationOwner.startTime !== "string"))))
+        throw new Error("Invalid replica work record.");
+    return value;
+}
+/** Record the source basis before Herdr allocates any resources. */
+export function createReplicaWork(file, id, parentSessionId, fork, joinBase = fork.commit) {
+    if (existsSync(file))
+        throw new Error("Replica work identity already exists.");
+    writeBindingFile(file, { version: 1, id, parentSessionId, fork, joinBase, integration: { status: "pending" } });
+}
+/** Record a shared attempt without creating a Git snapshot or branch. */
+export function createSharedReplicaWork(file, id, parentSessionId, cwd) {
+    if (existsSync(file)) throw new Error("Replica work identity already exists.");
+    writeBindingFile(file, { version: 1, id, parentSessionId, mode: "shared", sharedCwd: cwd, integration: { status: "pending" } });
+}
+/** Persist the allocated shared pane before dispatch. */
+export function attachSharedReplicaPane(file, pane, sessionFile) {
+    const record = readReplicaWork(file);
+    if (record.mode !== "shared" || (record.sharedPane && record.sharedPane !== pane)) throw new Error("Invalid shared replica pane.");
+    writeBindingFile(file, { ...record, sharedPane: pane, ...(sessionFile ? { sessionFile } : {}) });
+}
+/** Reserve the latest settled attempt for its exact immediate parent. */
+export function reserveReplicaContinuation(file, parentSessionId, attemptId) {
+    let current = file;
+    const seen = new Set();
+    for (;;) {
+        const result = withLineageMutationGate(current + ".artifacts", (owner) => {
+            const record = readReplicaWork(current);
+            if (record.parentSessionId !== parentSessionId)
+                throw new Error("Continuation is not owned by this session.");
+            if (seen.has(record.id))
+                throw new Error("Invalid continuation cycle.");
+            seen.add(record.id);
+            if (!record.completion && !record.launchError)
+                throw new Error("Continuation is still active.");
+            if (record.integration.status === "pending")
+                throw new Error("Continuation has an active integration.");
+            const binding = record.sessionFile && existsSync(record.sessionFile) ? readSessionBinding(record.sessionFile) : undefined;
+            const location = binding?.child ? childSessionLocation(binding.child.lineage.rootDir, binding.child.lineage.nodeId) : record.worktreeLocation;
+            if (location && sessionLocationAlive(location))
+                throw new Error("Continuation session is still active.");
+            if (record.continuationAttempt) {
+                const next = join(dirname(current), record.continuationAttempt + ".json");
+                if (!existsSync(next)) {
+                    if (!record.continuationOwner || processIncarnationAlive(record.continuationOwner, owner))
+                        throw new Error("Continuation has an active launch reservation.");
+                }
+                else {
+                    const child = readReplicaWork(next);
+                    if (!child.completion && !child.launchError)
+                        throw new Error("Continuation is still active.");
+                    if (!child.launchError)
+                        return { next };
+                }
+            }
+            if (!record.checkpoint || !record.sessionCheckpoint)
+                throw new Error("Continuation has no usable saved source/session checkpoint.");
+            writeBindingFile(current, { ...record, continuationAttempt: attemptId, continuationOwner: owner });
+            return { record };
+        });
+        if ("record" in result)
+            return result.record;
+        current = result.next;
+    }
+}
+/** Release only this unpublished launch; never clear another attempt's reservation. */
+export function releaseReplicaContinuation(file, attemptId) {
+    withLineageMutationGate(file + ".artifacts", () => {
+        const record = readReplicaWork(file);
+        if (record.continuationAttempt !== attemptId)
+            return;
+        const { continuationAttempt: _attempt, continuationOwner: _owner, ...rest } = record;
+        writeBindingFile(file, rest);
+    });
+}
+/** Persist runtime before launch, so recovery never silently adopts another configuration. */
+export function saveReplicaRuntime(file, runtime) {
+    writeBindingFile(file, { ...readReplicaWork(file), runtime });
+}
+/** Preserve failed allocation facts and release a reservation without discarding evidence. */
+export function failReplicaLaunch(file, error, toolCallId) {
+    const record = readReplicaWork(file);
+    writeBindingFile(file, { ...record, launchError: String(error), ...(toolCallId ? { launchErrorToolCallId: toolCallId } : {}), integration: { status: "not-attempted", details: record.mode === "shared" ? "Launch failed; changes may already be present in the shared directory." : "Launch failed; saved work was not applied." } });
+}
+/** A persisted native tool error already delivered this pre-acknowledgement failure. */
+export function replicaLaunchFailureReported(record, entries, owner) {
+    if (!record.launchError)
+        return false;
+    const ids = new Set([record.launchErrorToolCallId, owner?.toolCallId].filter(Boolean));
+    const diagnostic = record.launchError.replace(/^(?:Error:\s*)+/, "");
+    return entries.some(entry => {
+        const row = entry;
+        const message = row?.message;
+        if (row?.type !== "message" || message?.role !== "toolResult" || message.isError !== true)
+            return false;
+        if (ids.has(message.toolCallId))
+            return true;
+        // An outer script may fail for another call. Require this launch's actual facts.
+        return !!owner?.parentToolCallId && message.toolCallId === owner.parentToolCallId && !!diagnostic && Array.isArray(message.content) &&
+            message.content.some(block => typeof block.text === "string" &&
+                (block.text.includes(diagnostic) || block.text.includes(JSON.stringify(diagnostic).slice(1, -1))));
+    });
+}
+/** Bind allocated worktree and session before the child process can start. */
+export function attachReplicaWork(file, worktree, sessionFile) {
+    const record = readReplicaWork(file);
+    writeBindingFile(file, { ...record, worktree, ...(sessionFile ? { sessionFile } : {}) });
+}
+/** Save launch ownership before the child can fail during extension loading. */
+export function captureReplicaLaunchPane(file, owner) {
+    const record = readReplicaWork(file);
+    if ((record.mode === "shared" ? record.sharedPane : record.worktree?.paneId) !== owner.paneId)
+        throw new Error("Launch ownership does not match the replica pane.");
+    if (record.launchPane) {
+        if (!launchOwnsPane(record.launchPane, owner.paneId, owner.shellPid))
+            throw new Error("Replica launch shell incarnation changed.");
+        return;
+    }
+    writeBindingFile(file, { ...record, launchPane: owner });
+}
+/** Preserve the launch workspace's process incarnation even if the session later teleports. */
+export function captureReplicaWorkLocation(file, location) {
+    const record = readReplicaWork(file);
+    const pane = record.mode === "shared" ? record.sharedPane : record.worktree?.paneId;
+    const cwd = record.mode === "shared" ? record.sharedCwd : record.worktree?.path;
+    if (record.worktreeLocation || !pane || !cwd || location.paneId !== pane) return;
+    if (realpathSync(location.cwd) !== realpathSync(cwd))
+        return;
+    writeBindingFile(file, { ...record, worktreeLocation: location });
+}
+/** Save task result and latest files before join or pane/worktree cleanup. */
+export function checkpointReplicaCompletion(file, cwd, sessionFile, completion) {
+    let record = readReplicaWork(file);
+    if (record.completion)
+        return record;
+    const sessionDir = file + ".artifacts";
+    mkdirSync(sessionDir, { recursive: true });
+    const sessionCheckpoint = join(sessionDir, "session.jsonl");
+    try {
+        writeFileSync(sessionCheckpoint, readFileSync(sessionFile), { mode: 0o600 });
+        for (const path of [sessionCheckpoint, sessionDir]) {
+            const fd = openSync(path, "r");
+            try {
+                fsyncSync(fd);
+            }
+            finally {
+                closeSync(fd);
+            }
+        }
+        record = { ...record, sessionCheckpoint };
+    }
+    catch (error) {
+        record = { ...record, sessionCheckpointError: String(error) };
+    }
+    if (record.mode === "shared") {
+        const failed = completion.exitCode !== 0 || !!completion.error || !!completion.errorMessage || !completion.summary.trim();
+        record = { ...record, sessionFile, completion, integration: failed
+            ? { status: "not-attempted", details: "The task failed; changes may already be present in the shared directory." }
+            : { status: "shared" } };
+        writeBindingFile(file, record);
+        return record;
+    }
+    try {
+        const checkpoint = snapshotSource(cwd, join(file + ".artifacts", "source"));
+        if (checkpoint.commonDir !== record.fork.commonDir)
+            throw new Error("Replica moved outside its source repository.");
+        record = { ...record, checkpoint };
+    }
+    catch (error) {
+        record = { ...record, checkpointError: String(error) };
+    }
+    const failed = completion.exitCode !== 0 || !!completion.error || !!completion.errorMessage || !completion.summary.trim();
+    record = { ...record, sessionFile, completion, integration: failed
+            ? { status: "not-attempted", details: "The task failed; partial work was not applied." }
+            : record.sessionCheckpointError
+                ? { status: "blocked", details: `The session could not be saved: ${record.sessionCheckpointError}` }
+                : record.integration };
+    writeBindingFile(file, record);
+    return record;
+}
+/** Attempt successful work; the optional receiver check can refuse application after a session move. */
+export function joinReplicaWork(file, parentCwd, parentActive = () => true) {
+    let record = readReplicaWork(file);
+    if (!record.completion)
+        throw new Error("Replica has no saved task result.");
+    if (record.integration.status !== "pending")
+        return record;
+    if (!record.checkpoint) {
+        record = { ...record, integration: { status: "blocked", details: record.checkpointError ?? "No saved source checkpoint." } };
+        writeBindingFile(file, record);
+        return record;
+    }
+    try {
+        const parent = snapshotSource(parentCwd, join(file + ".artifacts", "parent"));
+        if (parent.commonDir !== record.fork.commonDir)
+            throw new Error("The parent is now in a different repository; saved work was not applied there.");
+        if (record.joinPlan && record.joinPlan.before.repoDir !== parent.repoDir)
+            throw new Error("An interrupted join belongs to another parent checkout; its saved plan is retained.");
+        if (!record.joinPlan) {
+            const plan = planSourceJoin(parent.repoDir, record.joinBase, record.checkpoint.commit, join(file + ".artifacts", "join"));
+            if (plan.status === "conflict") {
+                record = { ...record, integration: { status: "conflict", details: plan.details } };
+                writeBindingFile(file, record);
+                return record;
+            }
+            record = { ...record, joinPlan: plan };
+            writeBindingFile(file, record);
+        }
+        applySourceJoin(record.joinPlan, () => {
+            if (!parentActive())
+                throw new Error("The parent session moved or closed during integration; saved work was retained.");
+        });
+        record = { ...record, integration: { status: "applied" } };
+    }
+    catch (error) {
+        record = { ...record, integration: { status: "blocked", details: String(error) } };
+    }
+    writeBindingFile(file, record);
+    return record;
+}
+/** Close an owned settled pane; remove its checkout only after safe integration. */
+export function cleanupReplicaWork(file, parentCwd) {
+    const record = readReplicaWork(file), worktree = record.worktree;
+    if (record.cleaned) return true;
+    if (record.mode === "shared") {
+        if (!record.sharedPane) return true;
+        if (record.worktreeLocation && sessionLocationAlive(record.worktreeLocation)) return false;
+        let info;
+        try { info = getHerdrPaneProcessInfo(record.sharedPane); }
+        catch (error) {
+            if (/pane_not_found|pane.*not found/i.test(String(error))) { writeBindingFile(file, { ...record, cleaned: true }); return true; }
+            throw error;
+        }
+        const owned = record.worktreeLocation
+            ? sessionOwnsPane(record.worktreeLocation, record.sharedPane, info.shellPid)
+            : !!record.launchPane && launchOwnsPane(record.launchPane, record.sharedPane, info.shellPid);
+        if (!owned || info.pids.some(pid => pid !== info.shellPid)) return false;
+        closeHerdrSurface(record.sharedPane);
+        writeBindingFile(file, { ...record, cleaned: true });
+        return true;
+    }
+    if (!worktree) return true;
+    const removeWorktree = record.integration.status === "applied";
+    const matches = listHerdrWorktrees(parentCwd).filter((entry) => entry.path === worktree.path && entry.branch === worktree.branch && entry.isLinkedWorktree);
+    if (matches.length > 1)
+        throw new Error("Ambiguous replica worktree ownership.");
+    if (!matches.length) {
+        if (!removeWorktree)
+            return true;
+        if (existsSync(worktree.path))
+            return false;
+        writeBindingFile(file, { ...record, cleaned: true });
+        return true;
+    }
+    const observed = matches[0];
+    if (record.worktreeLocation && sessionLocationAlive(record.worktreeLocation))
+        return false;
+    if (removeWorktree) {
+        if (!record.checkpoint || !record.sessionCheckpoint || !existsSync(record.sessionCheckpoint))
+            return false;
+        const checkpoint = snapshotSource(worktree.path, join(file + ".artifacts", "cleanup"));
+        if (checkpoint.tree !== record.checkpoint.tree || checkpoint.head !== record.checkpoint.head || checkpoint.indexHash !== record.checkpoint.indexHash)
+            return false; // Never discard edits made after settlement.
+    }
+    if (observed.workspaceId) {
+        if (observed.workspaceId !== worktree.workspaceId)
+            return false;
+        const failedLaunch = !record.worktreeLocation && !!record.launchPane &&
+            (!!record.launchError || (record.completion != null && record.completion.exitCode !== 0));
+        if (!record.worktreeLocation && !failedLaunch)
+            return false;
+        const response = JSON.parse(execFileSync("herdr", ["pane", "list", "--workspace", observed.workspaceId], { encoding: "utf8" }));
+        const panes = response?.result?.panes;
+        if (!Array.isArray(panes) || panes.length !== 1 || panes[0].pane_id !== worktree.paneId)
+            return false;
+        const info = getHerdrPaneProcessInfo(worktree.paneId);
+        const owned = record.worktreeLocation
+            ? sessionOwnsPane(record.worktreeLocation, worktree.paneId, info.shellPid)
+            : launchOwnsPane(record.launchPane, worktree.paneId, info.shellPid);
+        if (!owned || info.pids.some((pid) => pid !== info.shellPid))
+            return false;
+        if (!removeWorktree) {
+            closeHerdrSurface(worktree.paneId);
+            return true;
+        }
+        execFileSync("herdr", ["worktree", "remove", "--workspace", observed.workspaceId, "--force", "--trust-repository"], { encoding: "utf8" });
+    }
+    else {
+        if (!removeWorktree)
+            return true;
+        // A restarted Herdr may no longer have its workspace. Keep any surviving cwd users.
+        for (const pid of readdirSync("/proc").filter((entry) => /^\d+$/.test(entry))) {
+            let cwd;
+            try {
+                cwd = readlinkSync(`/proc/${pid}/cwd`);
+            }
+            catch {
+                continue;
+            }
+            if (cwd === worktree.path || cwd === `${worktree.path} (deleted)` || cwd.startsWith(worktree.path + "/"))
+                return false;
+        }
+        execFileSync("git", ["worktree", "remove", "--force", worktree.path], { cwd: parentCwd, encoding: "utf8" });
+    }
+    if (existsSync(worktree.path))
+        throw new Error("Replica worktree cleanup could not be verified.");
+    writeBindingFile(file, { ...record, cleaned: true });
+    return true;
+}