@os-eco/overstory-cli 0.7.0 → 0.7.2

package/src/runtimes/pi.ts

@@ -0,0 +1,244 @@
+// Pi runtime adapter for overstory's AgentRuntime interface.
+// Implements the AgentRuntime contract for the `pi` CLI (Mario Zechner's Pi coding agent).
+
+import { mkdir } from "node:fs/promises";
+import { join } from "node:path";
+import type { PiRuntimeConfig, ResolvedModel } from "../types.ts";
+import { generatePiGuardExtension } from "./pi-guards.ts";
+import type {
+	AgentRuntime,
+	HooksDef,
+	OverlayContent,
+	ReadyState,
+	SpawnOpts,
+	TranscriptSummary,
+} from "./types.ts";
+
+/** Default Pi runtime config used when no config is provided. */
+const DEFAULT_PI_CONFIG: PiRuntimeConfig = {
+	provider: "anthropic",
+	modelMap: {
+		opus: "anthropic/claude-opus-4-6",
+		sonnet: "anthropic/claude-sonnet-4-6",
+		haiku: "anthropic/claude-haiku-4-5",
+	},
+};
+
+/**
+ * Pi runtime adapter.
+ *
+ * Implements AgentRuntime for the `pi` CLI (Mario Zechner's Pi coding agent).
+ * Security is enforced via Pi guard extensions rather than permission-mode flags —
+ * Pi has no --permission-mode equivalent.
+ */
+export class PiRuntime implements AgentRuntime {
+	/** Unique identifier for this runtime. */
+	readonly id = "pi";
+
+	/** Relative path to the instruction file within a worktree. Pi reads .claude/CLAUDE.md natively. */
+	readonly instructionPath = ".claude/CLAUDE.md";
+
+	private readonly config: PiRuntimeConfig;
+
+	constructor(config?: PiRuntimeConfig) {
+		this.config = config ?? DEFAULT_PI_CONFIG;
+	}
+
+	/**
+	 * Expand a model alias to a provider-qualified model ID.
+	 *
+	 * 1. If model contains "/" → already qualified, pass through
+	 * 2. If model is in modelMap → return the mapped value
+	 * 3. Otherwise → return `${provider}/${model}`
+	 */
+	expandModel(model: string): string {
+		if (model.includes("/")) return model;
+		const mapped = this.config.modelMap[model];
+		if (mapped) return mapped;
+		return `${this.config.provider}/${model}`;
+	}
+
+	/**
+	 * Build the shell command string to spawn an interactive Pi agent.
+	 *
+	 * Maps SpawnOpts to the `pi` CLI flags:
+	 * - `model` → `--model <model>`
+	 * - `permissionMode` is accepted but NOT mapped — Pi has no permission-mode flag.
+	 *   Security is enforced via guard extensions deployed by deployConfig().
+	 * - `appendSystemPrompt` → `--append-system-prompt '<escaped>'` (POSIX single-quote escaping)
+	 *
+	 * The `cwd` and `env` fields are handled by the tmux session creator, not embedded here.
+	 *
+	 * @param opts - Spawn options (model, appendSystemPrompt; permissionMode is ignored)
+	 * @returns Shell command string suitable for tmux new-session -c
+	 */
+	buildSpawnCommand(opts: SpawnOpts): string {
+		let cmd = `pi --model ${this.expandModel(opts.model)}`;
+
+		if (opts.appendSystemPrompt) {
+			// POSIX single-quote escape: end quote, backslash-quote, start quote.
+			const escaped = opts.appendSystemPrompt.replace(/'/g, "'\\''");
+			cmd += ` --append-system-prompt '${escaped}'`;
+		}
+
+		return cmd;
+	}
+
+	/**
+	 * Build the argv array for a headless one-shot Pi invocation.
+	 *
+	 * Returns an argv array suitable for `Bun.spawn()`. The `--print` flag causes Pi
+	 * to run the prompt and exit. Unlike Claude Code, the prompt is a positional argument
+	 * (last), not passed via `-p`.
+	 *
+	 * @param prompt - The prompt to pass as a positional argument
+	 * @param model - Optional model override
+	 * @returns Argv array for Bun.spawn
+	 */
+	buildPrintCommand(prompt: string, model?: string): string[] {
+		const cmd = ["pi", "--print"];
+		if (model !== undefined) {
+			cmd.push("--model", this.expandModel(model));
+		}
+		cmd.push(prompt);
+		return cmd;
+	}
+
+	/**
+	 * Deploy per-agent instructions and guards to a worktree.
+	 *
+	 * Writes up to three files:
+	 * 1. `.claude/CLAUDE.md` — agent's task-specific overlay. Skipped when overlay is undefined.
+	 * 2. `.pi/extensions/overstory-guard.ts` — Pi guard extension (always deployed).
+	 * 3. `.pi/settings.json` — Pi settings enabling the extensions directory (always deployed).
+	 *
+	 * @param worktreePath - Absolute path to the agent's git worktree
+	 * @param overlay - Overlay content to write as CLAUDE.md, or undefined for guard-only deployment
+	 * @param hooks - Agent identity, capability, worktree path, and optional quality gates
+	 */
+	async deployConfig(
+		worktreePath: string,
+		overlay: OverlayContent | undefined,
+		hooks: HooksDef,
+	): Promise<void> {
+		if (overlay) {
+			const claudeDir = join(worktreePath, ".claude");
+			await mkdir(claudeDir, { recursive: true });
+			await Bun.write(join(claudeDir, "CLAUDE.md"), overlay.content);
+		}
+
+		// Always deploy Pi guard extension.
+		const piExtDir = join(worktreePath, ".pi", "extensions");
+		await mkdir(piExtDir, { recursive: true });
+		await Bun.write(join(piExtDir, "overstory-guard.ts"), generatePiGuardExtension(hooks));
+
+		// Always deploy Pi settings pointing at the extensions directory.
+		const piDir = join(worktreePath, ".pi");
+		const settings = { extensions: ["./extensions"] };
+		await Bun.write(join(piDir, "settings.json"), `${JSON.stringify(settings, null, "\t")}\n`);
+	}
+
+	/**
+	 * Pi does not require beacon verification/resend.
+	 *
+	 * Claude Code's TUI sometimes swallows Enter during late initialization, so the
+	 * orchestrator resends the beacon until the pane leaves the "idle" state. Pi's TUI
+	 * does not have this issue AND its idle vs. processing states are indistinguishable
+	 * via detectReady (the header "pi v..." and status bar token counter are visible in
+	 * both states). Enabling the resend loop would spam Pi with duplicate beacon messages.
+	 */
+	requiresBeaconVerification(): boolean {
+		return false;
+	}
+
+	/**
+	 * Detect Pi TUI readiness from a tmux pane content snapshot.
+	 *
+	 * Pi shows a header containing "pi" and "model:" when the TUI has fully rendered.
+	 * Pi has no trust dialog phase.
+	 *
+	 * @param paneContent - Captured tmux pane content to analyze
+	 * @returns Current readiness phase
+	 */
+	detectReady(paneContent: string): ReadyState {
+		// Pi's TUI shows "pi v<version>" in the header and a status bar with
+		// a token usage indicator like "0.0%/200k" when fully rendered.
+		// Earlier detection checked for "model:" which Pi's TUI never contains.
+		const hasHeader = paneContent.includes("pi v");
+		const hasStatusBar = /\d+\.\d+%\/\d+k/.test(paneContent);
+		if (hasHeader && hasStatusBar) {
+			return { phase: "ready" };
+		}
+		return { phase: "loading" };
+	}
+
+	/**
+	 * Parse a Pi transcript JSONL file into normalized token usage.
+	 *
+	 * Pi JSONL format differs from Claude Code:
+	 * - Token counts are in `message_end` events with TOP-LEVEL `inputTokens` / `outputTokens`
+	 *   (not nested under message.usage)
+	 * - Model identity comes from `model_change` events with a `model` field
+	 *
+	 * Returns null if the file does not exist or cannot be parsed.
+	 *
+	 * @param path - Absolute path to the Pi transcript JSONL file
+	 * @returns Aggregated token usage, or null if unavailable
+	 */
+	async parseTranscript(path: string): Promise<TranscriptSummary | null> {
+		const file = Bun.file(path);
+		if (!(await file.exists())) {
+			return null;
+		}
+
+		try {
+			const text = await file.text();
+			const lines = text.split("\n").filter((l) => l.trim().length > 0);
+
+			let inputTokens = 0;
+			let outputTokens = 0;
+			let model = "";
+
+			for (const line of lines) {
+				let entry: Record<string, unknown>;
+				try {
+					entry = JSON.parse(line) as Record<string, unknown>;
+				} catch {
+					// Skip malformed lines — Pi transcripts may have partial writes.
+					continue;
+				}
+
+				if (entry.type === "message_end") {
+					// Pi top-level token fields (not nested under message.usage).
+					if (typeof entry.inputTokens === "number") {
+						inputTokens += entry.inputTokens;
+					}
+					if (typeof entry.outputTokens === "number") {
+						outputTokens += entry.outputTokens;
+					}
+				} else if (entry.type === "model_change") {
+					if (typeof entry.model === "string") {
+						model = entry.model;
+					}
+				}
+			}
+
+			return { inputTokens, outputTokens, model };
+		} catch {
+			return null;
+		}
+	}
+
+	/**
+	 * Build runtime-specific environment variables for model/provider routing.
+	 *
+	 * Returns the provider environment variables from the resolved model, or an empty
+	 * object if none are set.
+	 *
+	 * @param model - Resolved model with optional provider env vars
+	 * @returns Environment variable map (may be empty)
+	 */
+	buildEnv(model: ResolvedModel): Record<string, string> {
+		return model.env ?? {};
+	}
+}

package/src/runtimes/registry.test.ts

@@ -1,6 +1,7 @@
 import { describe, expect, it } from "bun:test";
 import type { OverstoryConfig } from "../types.ts";
 import { ClaudeRuntime } from "./claude.ts";
+import { PiRuntime } from "./pi.ts";
 import { getRuntime } from "./registry.ts";
 
 describe("getRuntime", () => {
@@ -50,4 +51,36 @@ describe("getRuntime", () => {
 		const b = getRuntime();
 		expect(a).not.toBe(b);
 	});
+
+	it("returns PiRuntime when name is 'pi'", () => {
+		const runtime = getRuntime("pi");
+		expect(runtime).toBeInstanceOf(PiRuntime);
+		expect(runtime.id).toBe("pi");
+	});
+
+	it("passes Pi config from OverstoryConfig to PiRuntime", () => {
+		const config = {
+			runtime: {
+				default: "pi",
+				pi: {
+					provider: "amazon-bedrock",
+					modelMap: {
+						opus: "amazon-bedrock/us.anthropic.claude-opus-4-6-v1",
+					},
+				},
+			},
+		} as unknown as OverstoryConfig;
+		const runtime = getRuntime(undefined, config) as PiRuntime;
+		expect(runtime).toBeInstanceOf(PiRuntime);
+		// Verify the config was applied by testing model expansion
+		expect(runtime.expandModel("opus")).toBe("amazon-bedrock/us.anthropic.claude-opus-4-6-v1");
+	});
+
+	it("Pi runtime uses defaults when no Pi config in OverstoryConfig", () => {
+		const config = { runtime: { default: "pi" } } as OverstoryConfig;
+		const runtime = getRuntime(undefined, config) as PiRuntime;
+		expect(runtime).toBeInstanceOf(PiRuntime);
+		// Should use default anthropic mappings
+		expect(runtime.expandModel("sonnet")).toBe("anthropic/claude-sonnet-4-6");
+	});
 });

package/src/runtimes/registry.ts

@@ -3,10 +3,14 @@
 
 import type { OverstoryConfig } from "../types.ts";
 import { ClaudeRuntime } from "./claude.ts";
+import { PiRuntime } from "./pi.ts";
 import type { AgentRuntime } from "./types.ts";
 
-/** Registry of available runtime adapters (name → factory). */
-const runtimes = new Map<string, () => AgentRuntime>([["claude", () => new ClaudeRuntime()]]);
+/** Registry of config-independent runtime adapters (name → factory). */
+const runtimes = new Map<string, () => AgentRuntime>([
+	["claude", () => new ClaudeRuntime()],
+	["pi", () => new PiRuntime()],
+]);
 
 /**
  * Resolve a runtime adapter by name.
@@ -16,6 +20,9 @@ const runtimes = new Map<string, () => AgentRuntime>([["claude", () => new Claud
  * 2. `config.runtime.default` (if config is provided)
  * 3. `"claude"` (hardcoded fallback)
  *
+ * Special cases:
+ * - Pi runtime receives `config.runtime.pi` for model alias expansion.
+ *
  * @param name - Runtime name to resolve (e.g. "claude"). Omit to use config default.
  * @param config - Overstory config for reading the default runtime.
  * @throws {Error} If the resolved runtime name is not registered.
@@ -23,6 +30,12 @@ const runtimes = new Map<string, () => AgentRuntime>([["claude", () => new Claud
  */
 export function getRuntime(name?: string, config?: OverstoryConfig): AgentRuntime {
 	const runtimeName = name ?? config?.runtime?.default ?? "claude";
+
+	// Pi runtime needs config for model alias expansion.
+	if (runtimeName === "pi") {
+		return new PiRuntime(config?.runtime?.pi);
+	}
+
 	const factory = runtimes.get(runtimeName);
 	if (!factory) {
 		throw new Error(

package/src/runtimes/types.ts

@@ -66,6 +66,48 @@ export interface TranscriptSummary {
 	model: string;
 }
 
+// === RPC Connection ===
+
+/**
+ * Reported state of a connected agent process.
+ * Used by RuntimeConnection.getState() to poll agent activity without tmux.
+ */
+export type ConnectionState = {
+	status: "idle" | "working" | "error";
+	/** Tool currently executing, if status is "working". */
+	currentTool?: string;
+};
+
+/**
+ * Handle to spawned agent process I/O streams for RPC communication.
+ * Compatible with Bun.spawn output when configured with stdin/stdout pipe.
+ */
+export interface RpcProcessHandle {
+	readonly stdin: {
+		write(data: string | Uint8Array): number | Promise<number>;
+	};
+	readonly stdout: ReadableStream<Uint8Array>;
+}
+
+/**
+ * Lifecycle interface for runtimes supporting direct RPC.
+ * When AgentRuntime.connect() exists, the orchestrator bypasses tmux for
+ * mail delivery (followUp), shutdown (abort), and health checks (getState).
+ * Pi implements via JSON-RPC 2.0 over stdin/stdout.
+ */
+export interface RuntimeConnection {
+	/** Send initial prompt after spawn. */
+	sendPrompt(text: string): Promise<void>;
+	/** Send follow-up message — replaces tmux send-keys. */
+	followUp(text: string): Promise<void>;
+	/** Clean shutdown — replaces SIGTERM. */
+	abort(): Promise<void>;
+	/** Query current state — replaces tmux capture-pane. */
+	getState(): Promise<ConnectionState>;
+	/** Release connection resources. */
+	close(): void;
+}
+
 // === Runtime Interface ===
 
 /**
@@ -122,4 +164,25 @@ export interface AgentRuntime {
 	 * the provider's authTokenEnv directly.
 	 */
 	buildEnv(model: ResolvedModel): Record<string, string>;
+
+	/**
+	 * Whether this runtime requires the beacon verification/resend loop after initial send.
+	 *
+	 * Claude Code's TUI sometimes swallows Enter during late initialization, so the
+	 * orchestrator resends the beacon if the pane still appears idle (overstory-3271).
+	 * Pi's TUI does not exhibit this behavior AND its idle/processing states are
+	 * indistinguishable via detectReady (both show the header and status bar), so
+	 * the resend loop would spam Pi with duplicate startup messages.
+	 *
+	 * Runtimes that omit this method (or return true) get the resend loop.
+	 * Pi returns false to skip it.
+	 */
+	requiresBeaconVerification?(): boolean;
+
+	/**
+	 * Establish direct RPC connection to running agent process.
+	 * Runtimes without RPC (Claude, Codex) omit this method.
+	 * Orchestrator checks `if (runtime.connect)` before calling, falls back to tmux when absent.
+	 */
+	connect?(process: RpcProcessHandle): RuntimeConnection;
 }

package/src/schema-consistency.test.ts

@@ -65,6 +65,7 @@ describe("SQL schema consistency", () => {
 				"state",
 				"task_id",
 				"tmux_session",
+				"transcript_path",
 				"worktree_path",
 			].sort();
 

package/src/sessions/compat.ts

@@ -36,6 +36,7 @@ function normalizeSession(raw: Record<string, unknown>): AgentSession {
 		lastActivity: raw.lastActivity as string,
 		escalationLevel: (raw.escalationLevel as number) ?? 0,
 		stalledSince: (raw.stalledSince as string | null) ?? null,
+		transcriptPath: (raw.transcriptPath as string | null) ?? null,
 	};
 }
 

package/src/sessions/store.test.ts

@@ -46,6 +46,7 @@ function makeSession(overrides: Partial<AgentSession> = {}): AgentSession {
 		lastActivity: "2026-01-15T10:00:00.000Z",
 		escalationLevel: 0,
 		stalledSince: null,
+		transcriptPath: null,
 		...overrides,
 	};
 }
@@ -137,6 +138,36 @@ describe("upsert", () => {
 		const badSession = { ...session, state: "invalid" as AgentState };
 		expect(() => store.upsert(badSession)).toThrow();
 	});
+
+	test("handles null transcriptPath", () => {
+		const session = makeSession({ transcriptPath: null });
+		store.upsert(session);
+		const result = store.getByName("test-agent");
+		expect(result?.transcriptPath).toBeNull();
+	});
+
+	test("transcriptPath roundtrips correctly", () => {
+		const session = makeSession({ transcriptPath: "/home/user/.pi/sessions/abc.jsonl" });
+		store.upsert(session);
+		const result = store.getByName("test-agent");
+		expect(result?.transcriptPath).toBe("/home/user/.pi/sessions/abc.jsonl");
+	});
+});
+
+// === updateTranscriptPath ===
+
+describe("updateTranscriptPath", () => {
+	test("sets transcript path for an existing session", () => {
+		store.upsert(makeSession({ transcriptPath: null }));
+		store.updateTranscriptPath("test-agent", "/tmp/transcript.jsonl");
+		const result = store.getByName("test-agent");
+		expect(result?.transcriptPath).toBe("/tmp/transcript.jsonl");
+	});
+
+	test("is a no-op for nonexistent agent", () => {
+		// Should not throw
+		store.updateTranscriptPath("nonexistent", "/tmp/transcript.jsonl");
+	});
 });
 
 // === getByName ===

package/src/sessions/store.ts

@@ -28,6 +28,8 @@ export interface SessionStore {
 	updateLastActivity(agentName: string): void;
 	/** Update escalation level and stalled timestamp. */
 	updateEscalation(agentName: string, level: number, stalledSince: string | null): void;
+	/** Update the transcript path for a session. */
+	updateTranscriptPath(agentName: string, path: string): void;
 	/** Remove a session by agent name. */
 	remove(agentName: string): void;
 	/** Purge sessions matching criteria. Returns count of deleted rows. */
@@ -54,6 +56,7 @@ interface SessionRow {
 	last_activity: string;
 	escalation_level: number;
 	stalled_since: string | null;
+	transcript_path: string | null;
 }
 
 /** Row shape for runs table as stored in SQLite (snake_case columns). */
@@ -84,7 +87,8 @@ CREATE TABLE IF NOT EXISTS sessions (
   started_at TEXT NOT NULL,
   last_activity TEXT NOT NULL,
   escalation_level INTEGER NOT NULL DEFAULT 0,
-  stalled_since TEXT
+  stalled_since TEXT,
+  transcript_path TEXT
 )`;
 
 const CREATE_INDEXES = `
@@ -124,6 +128,7 @@ function rowToSession(row: SessionRow): AgentSession {
 		lastActivity: row.last_activity,
 		escalationLevel: row.escalation_level,
 		stalledSince: row.stalled_since,
+		transcriptPath: row.transcript_path,
 	};
 }
 
@@ -139,6 +144,18 @@ function rowToRun(row: RunRow): Run {
 	};
 }
 
+/**
+ * Migrate an existing sessions table to add the transcript_path column.
+ * Safe to call multiple times — only adds the column if it does not exist.
+ */
+function migrateAddTranscriptPath(db: Database): void {
+	const rows = db.prepare("PRAGMA table_info(sessions)").all() as Array<{ name: string }>;
+	const existingColumns = new Set(rows.map((r) => r.name));
+	if (!existingColumns.has("transcript_path")) {
+		db.exec("ALTER TABLE sessions ADD COLUMN transcript_path TEXT");
+	}
+}
+
 /**
  * Migrate an existing sessions table from bead_id to task_id column.
  * Safe to call multiple times — only renames if bead_id exists and task_id does not.
@@ -173,6 +190,8 @@ export function createSessionStore(dbPath: string): SessionStore {
 
 	// Migrate: rename bead_id → task_id on existing tables
 	migrateBeadIdToTaskId(db);
+	// Migrate: add transcript_path column to existing tables
+	migrateAddTranscriptPath(db);
 
 	// Prepare statements for frequent operations
 	const upsertStmt = db.prepare<
@@ -194,16 +213,17 @@ export function createSessionStore(dbPath: string): SessionStore {
 			$last_activity: string;
 			$escalation_level: number;
 			$stalled_since: string | null;
+			$transcript_path: string | null;
 		}
 	>(`
 		INSERT INTO sessions
 			(id, agent_name, capability, worktree_path, branch_name, task_id,
 			 tmux_session, state, pid, parent_agent, depth, run_id,
-			 started_at, last_activity, escalation_level, stalled_since)
+			 started_at, last_activity, escalation_level, stalled_since, transcript_path)
 		VALUES
 			($id, $agent_name, $capability, $worktree_path, $branch_name, $task_id,
 			 $tmux_session, $state, $pid, $parent_agent, $depth, $run_id,
-			 $started_at, $last_activity, $escalation_level, $stalled_since)
+			 $started_at, $last_activity, $escalation_level, $stalled_since, $transcript_path)
 		ON CONFLICT(agent_name) DO UPDATE SET
 			id = excluded.id,
 			capability = excluded.capability,
@@ -219,7 +239,8 @@ export function createSessionStore(dbPath: string): SessionStore {
 			started_at = excluded.started_at,
 			last_activity = excluded.last_activity,
 			escalation_level = excluded.escalation_level,
-			stalled_since = excluded.stalled_since
+			stalled_since = excluded.stalled_since,
+			transcript_path = excluded.transcript_path
 	`);
 
 	const getByNameStmt = db.prepare<SessionRow, { $agent_name: string }>(`
@@ -268,6 +289,13 @@ export function createSessionStore(dbPath: string): SessionStore {
 		DELETE FROM sessions WHERE agent_name = $agent_name
 	`);
 
+	const updateTranscriptPathStmt = db.prepare<
+		void,
+		{ $agent_name: string; $transcript_path: string }
+	>(`
+		UPDATE sessions SET transcript_path = $transcript_path WHERE agent_name = $agent_name
+	`);
+
 	return {
 		upsert(session: AgentSession): void {
 			upsertStmt.run({
@@ -287,6 +315,7 @@ export function createSessionStore(dbPath: string): SessionStore {
 				$last_activity: session.lastActivity,
 				$escalation_level: session.escalationLevel,
 				$stalled_since: session.stalledSince,
+				$transcript_path: session.transcriptPath,
 			});
 		},
 
@@ -334,6 +363,10 @@ export function createSessionStore(dbPath: string): SessionStore {
 			});
 		},
 
+		updateTranscriptPath(agentName: string, path: string): void {
+			updateTranscriptPathStmt.run({ $agent_name: agentName, $transcript_path: path });
+		},
+
 		remove(agentName: string): void {
 			removeStmt.run({ $agent_name: agentName });
 		},

package/src/types.ts

@@ -22,6 +22,14 @@ export interface ResolvedModel {
 	env?: Record<string, string>;
 }
 
+/** Configuration for the Pi runtime's model alias expansion. */
+export interface PiRuntimeConfig {
+	/** Provider prefix for unqualified model aliases (e.g., "anthropic", "amazon-bedrock"). */
+	provider: string;
+	/** Maps short aliases (e.g., "opus") to provider-qualified model IDs. */
+	modelMap: Record<string, string>;
+}
+
 // === Task Tracker ===
 
 /** Backend for the task tracker. Defined here for use in OverstoryConfig. */
@@ -89,6 +97,14 @@ export interface OverstoryConfig {
 	runtime?: {
 		/** Default runtime adapter name (default: "claude"). */
 		default: string;
+		/**
+		 * Runtime adapter for headless one-shot AI calls (--print mode).
+		 * Used by merge/resolver.ts and watchdog/triage.ts.
+		 * Falls back to runtime.default when omitted.
+		 */
+		printCommand?: string;
+		/** Pi runtime configuration for model alias expansion. */
+		pi?: PiRuntimeConfig;
 	};
 }
 
@@ -145,6 +161,7 @@ export interface AgentSession {
 	lastActivity: string;
 	escalationLevel: number; // Progressive nudge stage: 0=warn, 1=nudge, 2=escalate, 3=terminate
 	stalledSince: string | null; // ISO timestamp when agent first entered stalled state
+	transcriptPath: string | null; // Runtime-provided transcript JSONL path (decoupled from ~/.claude/)
 }
 
 // === Agent Identity ===

package/src/watchdog/daemon.test.ts

@@ -75,6 +75,7 @@ function makeSession(overrides: Partial<AgentSession> = {}): AgentSession {
 		runId: null,
 		escalationLevel: 0,
 		stalledSince: null,
+		transcriptPath: null,
 		startedAt: new Date().toISOString(),
 		lastActivity: new Date().toISOString(),
 		...overrides,
@@ -804,6 +805,7 @@ describe("daemon tick", () => {
 			pid: process.pid,
 			escalationLevel: 0,
 			stalledSince: null,
+			transcriptPath: null,
 		});
 
 		writeSessionsToStore(tempRoot, [session]);
@@ -1389,7 +1391,7 @@ describe("run completion detection", () => {
 		expect(coordinatorNudges).toHaveLength(1);
 		// The test creates builders, so the message should be builder-specific
 		expect(coordinatorNudges[0]?.message).toContain("builder");
-		expect(coordinatorNudges[0]?.message).toContain("merge/cleanup");
+		expect(coordinatorNudges[0]?.message).toContain("Awaiting lead verification");
 	});
 
 	test("does not nudge when some workers still active", async () => {
@@ -1581,7 +1583,7 @@ describe("run completion detection", () => {
 		expect(coordinatorNudges).toHaveLength(1);
 		// The test creates builders, so the message should be builder-specific
 		expect(coordinatorNudges[0]?.message).toContain("builder");
-		expect(coordinatorNudges[0]?.message).toContain("merge/cleanup");
+		expect(coordinatorNudges[0]?.message).toContain("Awaiting lead verification");
 	});
 
 	test("does not nudge when no worker sessions in run", async () => {
@@ -1916,14 +1918,15 @@ describe("buildCompletionMessage", () => {
 		expect(msg).not.toContain("merge/cleanup");
 	});
 
-	test("all builders → contains 'builder' and 'Ready for merge/cleanup'", () => {
+	test("all builders → contains 'builder' and 'Awaiting lead verification' (not merge authorization)", () => {
 		const sessions = [
 			makeSession({ capability: "builder", agentName: "builder-1" }),
 			makeSession({ capability: "builder", agentName: "builder-2" }),
 		];
 		const msg = buildCompletionMessage(sessions, testRunId);
 		expect(msg).toContain("builder");
-		expect(msg).toContain("Ready for merge/cleanup");
+		expect(msg).toContain("Awaiting lead verification");
+		expect(msg).not.toContain("merge/cleanup");
 	});
 
 	test("all reviewers → contains 'reviewer' and 'Reviews done'", () => {

package/src/watchdog/daemon.ts

@@ -148,7 +148,7 @@ export function buildCompletionMessage(
 			return `[WATCHDOG] All ${count} scout(s) in run ${runId} have completed. Ready for next phase.`;
 		}
 		if (capabilities.has("builder")) {
-			return `[WATCHDOG] All ${count} builder(s) in run ${runId} have completed. Ready for merge/cleanup.`;
+			return `[WATCHDOG] All ${count} builder(s) in run ${runId} have completed. Awaiting lead verification.`;
 		}
 		if (capabilities.has("reviewer")) {
 			return `[WATCHDOG] All ${count} reviewer(s) in run ${runId} have completed. Reviews done.`;