@aeondave/pi-persona 1.15.2

package/src/engine/signals.ts

@@ -0,0 +1,11 @@
+/**
+ * Shared AbortSignal plumbing for the engine backends.
+ */
+
+/** One signal that fires when any of the given signals fires (ignores undefined). */
+export function combineSignals(...signals: Array<AbortSignal | undefined>): AbortSignal | undefined {
+	const live = signals.filter((s): s is AbortSignal => s !== undefined);
+	if (live.length === 0) return undefined;
+	if (live.length === 1) return live[0];
+	return AbortSignal.any(live);
+}

package/src/engine/spec-preflight.ts

@@ -0,0 +1,33 @@
+/**
+ * Run-spec preflight failures shared by BOTH engine backends (child adapter + in-process).
+ * A spec that names an agent or an output contract that is not installed must fail before
+ * anything spawns, and the message must let the caller self-correct: it names what IS
+ * installed. One wording, one cap, so the two engines can never drift apart again.
+ */
+
+import { cappedList } from "../core/format.ts";
+import type { AgentResult, FailureKind } from "../orchestration/types.ts";
+import { emptyUsage } from "./stream.ts";
+
+/** Names shown in a self-correcting hint before the list is elided. */
+const HINT_CAP = 12;
+
+/** `" — installed agents: a, b, …"`; empty when nothing is installed (no misleading hint). */
+export function installedHint(kind: "agents" | "contracts", names: string[]): string {
+	if (names.length === 0) return "";
+	return ` — installed ${kind}: ${cappedList(names, HINT_CAP)}`;
+}
+
+/** The result skeleton both preflight rejections share; only the error text and failureKind
+ *  differ between "unknown agent" and "unknown contract". */
+function failure(agent: string, error: string, failureKind: FailureKind): AgentResult {
+	return { agent, output: "", usage: emptyUsage(), ok: false, error, failureKind };
+}
+
+export function unknownAgentFailure(agent: string, installed: string[]): AgentResult {
+	return failure(agent, `[${agent}] unknown agent (not found in registry)${installedHint("agents", installed)}`, "unknown-agent");
+}
+
+export function unknownContractFailure(agent: string, requested: string, installed: string[]): AgentResult {
+	return failure(agent, `[${agent}] output contract "${requested}" not found${installedHint("contracts", installed)}`, "contract");
+}

package/src/engine/stream.ts

@@ -0,0 +1,369 @@
+/**
+ * Pure parsing of the `pi --mode json -p` event stream.
+ *
+ * The CLI emits one JSON object per line (a session event). This module turns
+ * that stream into an accumulated result — final assistant text, summed usage,
+ * model, and stop reason — without any I/O, so it is fully unit-testable. The
+ * spawn wrapper (child.ts) only does process plumbing on top of these helpers.
+ *
+ * Mirrors the canonical recipe in Pi's reference subagent example.
+ */
+
+export interface ChildUsage {
+	input: number;
+	output: number;
+	cacheRead: number;
+	cacheWrite: number;
+	cost: number;
+	contextTokens: number;
+	turns: number;
+}
+
+/** Structured lifecycle transition for one runtime tool call. Deliberately excludes arguments and output. */
+export interface ToolEvent {
+	phase: "start" | "end";
+	callId: string;
+	name: string;
+	failed?: boolean;
+}
+
+export interface StreamState {
+	/** The last assistant text content seen (the agent's answer — the returned result). */
+	output: string;
+	/** The chronological live log shown in the f9 detail view: every completed message's
+	 *  reasoning AND text, plus one `⚙ tool` line per tool call — the whole progression,
+	 *  never just the latest message. Bounded (old head trimmed) so a long run can't
+	 *  grow supervisor memory without limit. */
+	transcript: string;
+	/** The current in-progress message's visible content (streamed text, or reasoning
+	 *  while there's no answer text yet). Cleared on message_end (folded into transcript).
+	 *  Bounded (old head trimmed) like the transcript: `snapshot()` copies it on every
+	 *  event, per leg, so an unbounded one is the same leak. */
+	partial: string;
+	/** The in-progress message's content parts assembled from streaming deltas, indexed by
+	 *  `contentIndex`. pi ≥0.83 makes `message_update` DELTA-ONLY on the JSON wire (no
+	 *  cumulative `message`), so live text can only be reconstructed here. */
+	deltaParts: string[];
+	/** {@link deltaParts} joined — the value `partial` takes. Kept incrementally (a delta for
+	 *  the last non-blank part appends to it) because re-joining every part on every delta is
+	 *  quadratic in message length, on the hot path of every leg. */
+	deltaLive: string;
+	/** Index of the last non-blank part in {@link deltaParts}: the only slot whose growth
+	 *  appends to {@link deltaLive} verbatim, which is what makes the append exact. -1 = none. */
+	deltaTail: number;
+	usage: ChildUsage;
+	model?: string;
+	stopReason?: string;
+	errorMessage?: string;
+	sawAssistant: boolean;
+	/** The tool the child is currently running (e.g. "grep src/…"), or undefined. */
+	activity?: string;
+	/** Calls whose start was surfaced but whose end has not arrived. This is not a retention
+	 *  cache: active ids are never evicted merely because completed calls churn. */
+	activeToolCalls?: Set<string>;
+	/** Recently completed call ids whose start/end phase was surfaced. Both caches are bounded;
+	 *  they suppress duplicate wire events without growing for the lifetime of a long run. */
+	seenToolStarts?: Set<string>;
+	seenToolEnds?: Set<string>;
+}
+
+export function emptyUsage(): ChildUsage {
+	return { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0, contextTokens: 0, turns: 0 };
+}
+
+export function createStreamState(): StreamState {
+	return {
+		output: "",
+		transcript: "",
+		partial: "",
+		deltaParts: [],
+		deltaLive: "",
+		deltaTail: -1,
+		usage: emptyUsage(),
+		sawAssistant: false,
+		activeToolCalls: new Set(),
+		seenToolStarts: new Set(),
+		seenToolEnds: new Set(),
+	};
+}
+
+const TOOL_EVENT_DEDUPE_CACHE_MAX = 1_024;
+
+function rememberRecent(cache: Set<string>, callId: string): void {
+	cache.add(callId);
+	while (cache.size > TOOL_EVENT_DEDUPE_CACHE_MAX) {
+		const oldest = cache.values().next().value as string | undefined;
+		if (oldest === undefined) break;
+		cache.delete(oldest);
+	}
+}
+
+/** Start the next message's delta assembly from an empty slate (parts AND their cache). */
+function resetDeltaParts(state: StreamState): void {
+	state.deltaParts = [];
+	state.deltaLive = "";
+	state.deltaTail = -1;
+}
+
+function isObject(x: unknown): x is Record<string, unknown> {
+	return typeof x === "object" && x !== null && !Array.isArray(x);
+}
+
+function num(x: unknown): number {
+	return typeof x === "number" && !Number.isNaN(x) ? x : 0;
+}
+
+function firstText(content: unknown): string | undefined {
+	if (!Array.isArray(content)) return undefined;
+	for (const part of content) {
+		if (isObject(part) && part.type === "text" && typeof part.text === "string") return part.text;
+	}
+	return undefined;
+}
+
+/** The visible content of an in-progress message: its reasoning AND its answer text,
+ *  in content order, so a thinking agent isn't a mute "waiting" and the answer appearing
+ *  doesn't erase the reasoning that led to it. */
+function liveContent(content: unknown): string | undefined {
+	if (!Array.isArray(content)) return undefined;
+	const parts: string[] = [];
+	for (const part of content) {
+		if (!isObject(part)) continue;
+		if (part.type === "thinking" && typeof part.thinking === "string" && part.thinking.trim()) parts.push(part.thinking);
+		else if (part.type === "text" && typeof part.text === "string" && part.text.trim()) parts.push(part.text);
+	}
+	return parts.length > 0 ? parts.join("\n\n") : undefined;
+}
+
+// A malformed line must not be able to allocate an arbitrarily sparse deltaParts array
+// (the re-join below walks its whole length) — no real message has this many content parts.
+const MAX_CONTENT_PARTS = 4096;
+
+// Bound the in-progress message exactly as the transcript is bounded: MAX_CONTENT_PARTS caps
+// how MANY parts a malformed line can allocate, but nothing on the wire caps the bytes in one
+// (a single `text_end` can carry megabytes), and `snapshot()` copies the assembly on every
+// event, per leg. Over the cap the OLD head goes — the user is watching the tail.
+const PARTIAL_MAX = 200_000;
+const PARTIAL_KEEP = 150_000;
+
+function boundLive(text: string): string {
+	if (text.length <= PARTIAL_MAX) return text;
+	return `…[earlier output trimmed]\n${text.slice(text.length - PARTIAL_KEEP)}`;
+}
+
+/** Re-join every non-blank part and record which one is last. The general case — used when a
+ *  delta can't simply extend the tail of what's already assembled. */
+function rejoinDeltaParts(state: StreamState): void {
+	let live = "";
+	let tail = -1;
+	for (let i = 0; i < state.deltaParts.length; i++) {
+		const part = state.deltaParts[i];
+		if (!part?.trim()) continue;
+		live = live ? `${live}\n\n${part}` : part;
+		tail = i;
+	}
+	state.deltaLive = boundLive(live);
+	state.deltaTail = tail;
+}
+
+/** Fold one streaming `assistantMessageEvent` delta into the live partial. This is the
+ *  pi ≥0.83 wire shape: `message_update` carries only `{contentIndex, delta}`, never the
+ *  cumulative message, so the visible content has to be reassembled part by part.
+ *  Tool-call deltas are raw argument JSON — not something to show as agent output. */
+function applyMessageDelta(state: StreamState, ev: Record<string, unknown>): void {
+	if (ev.type === "start") {
+		resetDeltaParts(state);
+		return;
+	}
+	const idx = ev.contentIndex;
+	if (typeof idx !== "number" || !Number.isInteger(idx) || idx < 0 || idx >= MAX_CONTENT_PARTS) return;
+	const prev = state.deltaParts[idx] ?? "";
+	if (ev.type === "text_delta" || ev.type === "thinking_delta") {
+		if (typeof ev.delta !== "string") return;
+		const grown = boundLive(prev + ev.delta);
+		state.deltaParts[idx] = grown;
+		if (idx === state.deltaTail) {
+			// The hot path. deltaTail is by construction the LAST non-blank part, so appending to
+			// it appends to the assembly verbatim: no re-join, and no trim() of the whole part
+			// either (that flattens the rope V8 builds from the concatenation, which is itself
+			// quadratic in message length). A part just trimmed at the cap moved its own seam.
+			if (grown === prev + ev.delta) state.deltaLive = boundLive(state.deltaLive + ev.delta);
+			else rejoinDeltaParts(state);
+		} else if (idx > state.deltaTail && ev.delta.trim()) {
+			// Every part past the tail is blank, so this one becomes the new tail and lands at the
+			// END of the assembly — an append too.
+			state.deltaLive = boundLive(state.deltaLive ? `${state.deltaLive}\n\n${grown}` : grown);
+			state.deltaTail = idx;
+		} else if (idx < state.deltaTail || grown.trim()) {
+			// A late delta for an earlier part, or a blank part promoted by whitespace-then-text:
+			// the seams moved, so re-join once.
+			rejoinDeltaParts(state);
+		}
+		// else a blank part stayed blank — excluded from the assembly either way, nothing moved.
+	} else if (ev.type === "text_end" || ev.type === "thinking_end") {
+		if (typeof ev.content !== "string") return;
+		state.deltaParts[idx] = boundLive(ev.content);
+		rejoinDeltaParts(state);
+	} else return;
+	if (state.deltaLive) {
+		state.partial = state.deltaLive;
+		delete state.activity; // generating, not running a tool
+	}
+}
+
+/** A short "toolName arg" activity label from a tool_execution_start event. */
+function toolActivity(toolName: string, args: unknown): string {
+	if (isObject(args)) {
+		const hint = args.path ?? args.pattern ?? args.command ?? args.file ?? args.query ?? args.url;
+		if (typeof hint === "string" && hint.trim()) {
+			return `${toolName} ${hint.length > 40 ? `${hint.slice(0, 40)}…` : hint}`;
+		}
+	}
+	return toolName;
+}
+
+// Bound the live transcript: a long tool-heavy run must not grow memory without limit.
+// When the cap is hit, the OLD head is trimmed (the user watches the tail live).
+const TRANSCRIPT_MAX = 200_000;
+const TRANSCRIPT_KEEP = 150_000;
+
+function appendTranscript(state: StreamState, chunk: string, sep: string): void {
+	state.transcript += (state.transcript ? sep : "") + chunk;
+	if (state.transcript.length > TRANSCRIPT_MAX) {
+		state.transcript = `…[earlier output trimmed]\n${state.transcript.slice(state.transcript.length - TRANSCRIPT_KEEP)}`;
+	}
+}
+
+/** Fold one parsed stream event into the accumulating state (in place), returning a
+ * deduplicated structured lifecycle transition when the runtime supplied a stable call id. */
+export function applyEvent(state: StreamState, event: unknown): ToolEvent | undefined {
+	if (!isObject(event)) return undefined;
+
+	// Track the current tool so the UI can show "running: grep src/…" while a
+	// tool-heavy agent reads before it has written any text. The tool line also goes
+	// into the transcript, so the live log reads chronologically (think → tools → text)
+	// instead of tool-heavy stretches leaving the view apparently frozen.
+	if (event.type === "tool_execution_start" && typeof event.toolName === "string") {
+		state.activity = toolActivity(event.toolName, event.args);
+		appendTranscript(state, `⚙ ${state.activity}`, "\n");
+		const callId = event.toolCallId;
+		if (typeof callId !== "string" || callId.length === 0) return undefined;
+		const active = state.activeToolCalls ??= new Set();
+		const seenStarts = state.seenToolStarts ??= new Set();
+		const seenEnds = state.seenToolEnds ??= new Set();
+		if (active.has(callId) || seenStarts.has(callId) || seenEnds.has(callId)) return undefined;
+		active.add(callId);
+		return { phase: "start", callId, name: event.toolName };
+	}
+	if (event.type === "tool_execution_end") {
+		delete state.activity;
+		const callId = event.toolCallId;
+		const name = event.toolName;
+		if (typeof callId !== "string" || callId.length === 0 || typeof name !== "string") return undefined;
+		const seenEnds = state.seenToolEnds ??= new Set();
+		if (seenEnds.has(callId)) return undefined;
+		const active = state.activeToolCalls ??= new Set();
+		const wasActive = active.delete(callId);
+		rememberRecent(seenEnds, callId);
+		if (wasActive) rememberRecent(state.seenToolStarts ??= new Set(), callId);
+		const toolEvent: ToolEvent = { phase: "end", callId, name };
+		if (typeof event.isError === "boolean") toolEvent.failed = event.isError;
+		return toolEvent;
+	}
+
+	// Live partial: pi streams the growing message as `message_update` events. Surface
+	// its text (or reasoning) so a long-thinking agent shows progress, not just tokens.
+	// ONLY the assistant's own message counts: pi also emits message_start/message_end for
+	// the user prompt it just delivered and for every tool result, and folding those in
+	// would make the child's own task echo look like streamed output — cancelling the
+	// startup deadline before the first provider call and salvaging the prompt as
+	// "partial output" when the leg dies without ever answering.
+	if (event.type === "message_update" || event.type === "message_start") {
+		if (isObject(event.message)) {
+			if (event.message.role !== "assistant") return;
+			if (event.type === "message_start") resetDeltaParts(state);
+			const live = liveContent(event.message.content);
+			if (live !== undefined) {
+				state.partial = boundLive(live);
+				delete state.activity; // generating, not running a tool
+			}
+			return;
+		}
+		// pi ≥0.83 strips the cumulative `message` from message_update on the JSON wire —
+		// only the deltas remain, so assemble the live text from them instead.
+		if (event.type === "message_update" && isObject(event.assistantMessageEvent)) {
+			applyMessageDelta(state, event.assistantMessageEvent);
+		}
+		return;
+	}
+
+	if (event.type !== "message_end" || !isObject(event.message)) return;
+	const msg = event.message;
+	if (msg.role !== "assistant") return;
+
+	delete state.activity; // a message means it's reasoning, not mid-tool
+	state.partial = ""; // the completed message is folded into the transcript below
+	resetDeltaParts(state); // the next message's deltas start from an empty slate
+	state.sawAssistant = true;
+	state.usage.turns++;
+
+	const text = firstText(msg.content);
+	if (text !== undefined) state.output = text;
+	// Fold the WHOLE completed message (reasoning + text) into the transcript — not just
+	// the text. Otherwise each message_end wipes the thinking the user was reading
+	// (`partial` clears) and a tool-heavy agent's view looks like it "overwrites itself".
+	const live = liveContent(msg.content);
+	if (live) appendTranscript(state, live, "\n\n");
+
+	const usage = msg.usage;
+	if (isObject(usage)) {
+		state.usage.input += num(usage.input);
+		state.usage.output += num(usage.output);
+		state.usage.cacheRead += num(usage.cacheRead);
+		state.usage.cacheWrite += num(usage.cacheWrite);
+		state.usage.cost += isObject(usage.cost) ? num(usage.cost.total) : 0;
+		// contextTokens is the *current* window size, not a sum — replace it, but
+		// only when this turn actually reported one (don't zero it out otherwise).
+		if (typeof usage.totalTokens === "number" && !Number.isNaN(usage.totalTokens)) {
+			state.usage.contextTokens = usage.totalTokens;
+		}
+	}
+
+	if (state.model === undefined && typeof msg.model === "string") state.model = msg.model;
+	if (typeof msg.stopReason === "string") state.stopReason = msg.stopReason;
+	if (typeof msg.errorMessage === "string") state.errorMessage = msg.errorMessage;
+}
+
+/** A compact live progress view of a running agent (for peek / ProgressView). */
+export interface ProgressSnapshot {
+	output: string;
+	turns: number;
+	tokens: number;
+	/** The tool currently running (e.g. "grep src/…"), if any. */
+	activity?: string;
+	/** One authoritative runtime tool lifecycle transition, when this snapshot is event-driven. */
+	toolEvent?: ToolEvent;
+}
+
+export function snapshot(state: StreamState, toolEvent?: ToolEvent): ProgressSnapshot {
+	const snap: ProgressSnapshot = {
+		// The live view shows completed messages (transcript) plus the in-progress one
+		// (partial), falling back to the last text before anything has accumulated.
+		output: [state.transcript, state.partial].filter((s) => s).join("\n\n") || state.output,
+		turns: state.usage.turns,
+		tokens: state.usage.input + state.usage.output,
+	};
+	if (state.activity !== undefined) snap.activity = state.activity;
+	if (toolEvent !== undefined) snap.toolEvent = toolEvent;
+	return snap;
+}
+
+/** Buffer a stdout chunk into complete lines, returning the partial remainder. */
+export function feedLines(buffer: string, chunk: string): { lines: string[]; rest: string } {
+	const parts = (buffer + chunk).split("\n");
+	const rest = parts.pop() ?? "";
+	// Strip a trailing CR so CRLF (Windows) output yields clean lines; the partial
+	// remainder is left untouched (it may be mid-line).
+	const lines = parts.map((l) => (l.endsWith("\r") ? l.slice(0, -1) : l));
+	return { lines, rest };
+}

package/src/engine/worktree.ts

@@ -0,0 +1,144 @@
+/**
+ * Git worktree isolation — run a sub-agent in a throwaway `git worktree` so its file
+ * edits / test runs never touch the main working tree (spec §6 `isolation: worktree`).
+ * The worktree is detached at HEAD, used, then force-removed (the agent's experiments are
+ * discarded — isolation, not persistence; the agent returns its findings as its result).
+ *
+ * Pure over an injected async `GitExec` (so the lifecycle is unit-tested without a real repo);
+ * the default exec shells out to `git` via `child_process.execFile` — asynchronous, so the
+ * extension host keeps rendering, ticking timers and serving broker sockets while a large
+ * checkout is created or removed. Only the child-process engine uses this (a worktree needs
+ * its own cwd, i.e. a separate process).
+ */
+
+import { execFile } from "node:child_process";
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+export interface GitResult {
+	code: number;
+	stdout: string;
+	stderr: string;
+}
+
+export type GitExec = (args: string[]) => Promise<GitResult>;
+
+export type WorktreeArtifact =
+	| { ok: true; diff: string }
+	| { ok: false; error: string };
+
+/** Bound the data copied from an isolated checkout into the supervisor context. */
+export const MAX_WORKTREE_ARTIFACT_CHARS = 1_000_000;
+
+/** Output buffer for one git invocation — comfortably above MAX_WORKTREE_ARTIFACT_CHARS so the
+ *  size check below, not the OS pipe, is what rejects an oversized diff. */
+const GIT_MAX_BUFFER = 64 * 1024 * 1024;
+
+/** Default git runner — `git <args>`, never throwing (returns the exit code). */
+export const defaultGitExec: GitExec = (args) =>
+	new Promise((resolveResult) => {
+		execFile("git", args, { encoding: "utf8", maxBuffer: GIT_MAX_BUFFER, windowsHide: true, timeout: 120_000 }, (err, stdout, stderr) => {
+			if (!err) {
+				resolveResult({ code: 0, stdout, stderr });
+				return;
+			}
+			const e = err as NodeJS.ErrnoException & { code?: number | string };
+			const code = typeof e.code === "number" ? e.code : 1;
+			resolveResult({ code, stdout: stdout ?? "", stderr: stderr || e.message });
+		});
+	});
+
+/** The preflight gate for an isolated coding leg. Isolation is a safety boundary: a missing
+ * repository or a dirty checkout is not permission to run against the real cwd. */
+export async function worktreePreflight(root: string, exec: GitExec = defaultGitExec): Promise<{ ok: true } | { ok: false; error: string }> {
+	const repo = await exec(["-C", root, "rev-parse", "--is-inside-work-tree"]);
+	if (repo.code !== 0 || repo.stdout.trim().toLowerCase() === "false") {
+		return {
+			ok: false,
+			error: `worktree isolation requires a Git repository at ${root}; use a Git checkout or remove isolation: "worktree"`,
+		};
+	}
+	const status = await exec(["-C", root, "status", "--porcelain=v1", "--untracked-files=all"]);
+	if (status.code !== 0) {
+		return {
+			ok: false,
+			error: `worktree isolation could not inspect Git status at ${root}; commit/stash the checkout or remove isolation: "worktree" (${status.stderr.trim() || `git exited ${status.code}`})`,
+		};
+	}
+	if (status.stdout.trim().length > 0) {
+		const summary = status.stdout.trim().replace(/\s+/g, " ").slice(0, 240);
+		return {
+			ok: false,
+			error: `worktree isolation requires a clean Git checkout; commit/stash current changes (including untracked files) or remove isolation: "worktree" (status: ${summary})`,
+		};
+	}
+	return { ok: true };
+}
+
+/** Capture the complete post-run worktree state as a portable unified diff. Tracked edits use
+ * `git diff HEAD`; files newly created by a coding leg are added with `git diff --no-index`.
+ * Exit code 1 is the normal "files differ" result for --no-index. */
+export async function captureWorktreeArtifact(root: string, exec: GitExec = defaultGitExec): Promise<WorktreeArtifact> {
+	const tracked = await exec(["-C", root, "diff", "--no-ext-diff", "--binary", "HEAD", "--"]);
+	if (tracked.code !== 0) {
+		return { ok: false, error: `could not export the isolated worktree diff: ${tracked.stderr.trim() || `git exited ${tracked.code}`}` };
+	}
+	if (tracked.stdout.length > MAX_WORKTREE_ARTIFACT_CHARS) {
+		return { ok: false, error: `isolated worktree artifact is too large to return safely (limit ${MAX_WORKTREE_ARTIFACT_CHARS} characters)` };
+	}
+	const listed = await exec(["-C", root, "ls-files", "--others", "--exclude-standard", "-z"]);
+	if (listed.code !== 0) {
+		return { ok: false, error: `could not enumerate new files in the isolated worktree: ${listed.stderr.trim() || `git exited ${listed.code}`}` };
+	}
+	const parts = tracked.stdout.trim().length > 0 ? [tracked.stdout] : [];
+	let totalChars = tracked.stdout.length;
+	for (const name of listed.stdout.split("\0").filter((entry) => entry.length > 0)) {
+		const result = await exec(["-C", root, "diff", "--no-ext-diff", "--binary", "--no-index", "--", "/dev/null", name]);
+		if (result.code !== 0 && result.code !== 1) {
+			return { ok: false, error: `could not export new file ${name}: ${result.stderr.trim() || `git exited ${result.code}`}` };
+		}
+		totalChars += result.stdout.length;
+		if (totalChars > MAX_WORKTREE_ARTIFACT_CHARS) {
+			return { ok: false, error: `isolated worktree artifact is too large to return safely (limit ${MAX_WORKTREE_ARTIFACT_CHARS} characters)` };
+		}
+		if (result.stdout.trim().length > 0) parts.push(result.stdout);
+	}
+	return { ok: true, diff: parts.join("\n") };
+}
+
+/** Create a detached worktree off `root`'s HEAD, run `body(worktreeDir)`, then force-remove it. */
+export async function withWorktree<T>(root: string, exec: GitExec, body: (dir: string) => Promise<T>): Promise<T> {
+	const preflight = await worktreePreflight(root, exec);
+	if (!preflight.ok) throw new Error(preflight.error);
+	const dir = await mkdtemp(join(tmpdir(), "pi-persona-wt-"));
+	const add = await exec(["-C", root, "worktree", "add", "--detach", dir, "HEAD"]);
+	if (add.code !== 0) {
+		await rm(dir, { recursive: true, force: true }).catch(() => {
+			/* best effort */
+		});
+		throw new Error(`could not create git worktree: ${add.stderr.trim() || `git exited ${add.code}`}`);
+	}
+	try {
+		return await body(dir);
+	} finally {
+		// Remove the worktree registration, then the dir (force: it may carry the agent's edits).
+		// Never throw: cleanup must not replace the body's result (or its error) — `defaultGitExec`
+		// never rejects, but an injected `GitExec` could, and a rejection here must not either.
+		const rejected = (): GitResult => ({ code: 1, stdout: "", stderr: "git exec rejected" });
+		const remove = await exec(["-C", root, "worktree", "remove", "--force", dir]).catch(rejected);
+		await rm(dir, { recursive: true, force: true }).catch(() => {
+			/* the worktree remove usually handles it; ignore races */
+		});
+		// A failed remove (on Windows a grandchild tool process can still hold a file inside the
+		// worktree) leaves the .git/worktrees entry registered while the dir is gone — prune it,
+		// or stale ghosts accumulate across delegations until a manual `git worktree prune`.
+		// Never throw: cleanup must not replace the body's result (or its error).
+		if (remove.code !== 0) {
+			await exec(["-C", root, "worktree", "prune"]).catch(rejected);
+			if (process.env.PI_PERSONA_DEBUG) {
+				process.stderr.write(`[pi-persona] git worktree remove failed for ${dir} (pruned): ${remove.stderr.trim() || `git exited ${remove.code}`}\n`);
+			}
+		}
+	}
+}

package/src/exocom/activation.ts

@@ -0,0 +1,31 @@
+/**
+ * Recover the optional value form Pi's extension-flag API cannot currently expose.
+ *
+ * Pi registers `exocom` as a boolean so the established bare `--exocom` keeps working.
+ * Its CLI parser accepts `--exocom=<value>`, but boolean flag validation intentionally
+ * collapses that value to `true`. Read only the exact equals form, before the ordinary
+ * `--` option terminator; all enablement still flows through Pi's registered flag/config.
+ */
+
+export interface ExocomArgSelection {
+	joinCode?: string;
+	error?: string;
+}
+
+const CODE = /^[0-9A-Za-z]{4}$/;
+
+export function parseExocomArgv(argv: readonly string[]): ExocomArgSelection {
+	const explicit: string[] = [];
+	for (const arg of argv) {
+		if (arg === "--") break;
+		if (!arg.startsWith("--exocom=")) continue;
+		const value = arg.slice("--exocom=".length);
+		if (!CODE.test(value)) {
+			return { error: "--exocom join code must be exactly 4 Base62 characters (0-9, A-Z, a-z)" };
+		}
+		explicit.push(value);
+	}
+	const unique = [...new Set(explicit)];
+	if (unique.length > 1) return { error: "conflicting --exocom join codes" };
+	return unique[0] === undefined ? {} : { joinCode: unique[0] };
+}