pi-subagents 0.65.0 → 0.66.0

package/src/intercom/native-supervisor-channel.ts

@@ -2,7 +2,7 @@ import { randomUUID } from "node:crypto";
 import * as fs from "node:fs";
 import * as path from "node:path";
 import type { AgentToolResult } from "@earendil-works/pi-agent-core";
-import type { ExtensionAPI, ExtensionContext, ToolDefinition } from "@earendil-works/pi-coding-agent";
+import type { ExtensionAPI, ToolDefinition } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
 import type { ChildSupervisorMetadata } from "../runs/shared/child-runtime-config.ts";
 import { INTERCOM_DETACH_REQUEST_EVENT, POLL_INTERVAL_MS, TEMP_ROOT_DIR, type ControlEvent, type IntercomEventBus, type SubagentState } from "../shared/types.ts";
@@ -74,7 +74,7 @@ interface ContactSupervisorParams {
 }
 
 interface IntercomParams {
-	action: "list" | "send" | "ask" | "reply" | "pending" | "status";
+	action: "list" | "pending" | "status" | "reply";
 	to?: string;
 	message?: string;
 	replyTo?: string;
@@ -83,6 +83,8 @@ interface IntercomParams {
 type SupervisorWatch = (filename: fs.PathLike, listener: fs.WatchListener<string>) => fs.FSWatcher;
 
 interface NativeSupervisorChannelDeps {
+	/** Retained scheduled states for the current runtime owner, never foreign owners. */
+	getCurrentOwnerStates?: () => Iterable<SubagentState>;
 	platform?: NodeJS.Platform;
 	watch?: SupervisorWatch;
 	timers?: Pick<typeof globalThis, "setInterval" | "clearInterval" | "setImmediate" | "clearImmediate">;
@@ -95,7 +97,7 @@ const ContactSupervisorParamsSchema = Type.Object({
 }, { additionalProperties: false });
 
 const IntercomParamsSchema = Type.Object({
-	action: Type.String({ enum: ["list", "send", "ask", "reply", "pending", "status"] }),
+	action: Type.String({ enum: ["list", "pending", "status", "reply"] }),
 	to: Type.Optional(Type.String()),
 	message: Type.Optional(Type.String()),
 	replyTo: Type.Optional(Type.String()),
@@ -128,34 +130,6 @@ function reasonHeading(reason: SupervisorReason): string {
 	return "Subagent needs a supervisor decision.";
 }
 
-function formatChildMessage(input: {
-	reason: SupervisorReason;
-	message?: string;
-	interview?: unknown;
-	runId: string;
-	agent: string;
-	childIndex: number;
-	childTarget?: string;
-}): string {
-	const lines = [
-		reasonHeading(input.reason),
-		`Run: ${input.runId}`,
-		`Agent: ${input.agent}`,
-		`Child index: ${input.childIndex}`,
-	];
-	if (input.childTarget) lines.push(`Child intercom target: ${input.childTarget}`);
-	lines.push("");
-	if (input.message?.trim()) lines.push(input.message.trim());
-	if (input.reason === "interview_request") {
-		lines.push(
-			"",
-			"Structured response requested. Reply with JSON, optionally fenced in ```json, matching the requested interview shape.",
-		);
-		if (input.interview !== undefined) lines.push(JSON.stringify(input.interview, null, "\t"));
-	}
-	return lines.join("\n").trimEnd();
-}
-
 function parseStructuredReply(message: string): { value?: unknown; error?: string } {
 	const trimmed = message.trim();
 	const fenced = trimmed.match(/^```(?:json)?\s*([\s\S]*?)\s*```$/i)?.[1]?.trim();
@@ -210,8 +184,8 @@ async function waitForReply(channelDir: string, requestId: string, deadline: num
 }
 
 async function sendSupervisorRequest(params: ContactSupervisorParams, metadata: ChildSupervisorMetadata, signal?: AbortSignal, toolCallId?: string): Promise<AgentToolResult<Record<string, unknown>>> {
-	if (params.reason !== "progress_update" && !params.message?.trim() && params.reason !== "interview_request") {
-		throw new Error("message is required for supervisor decisions.");
+	if (!params.message?.trim() && params.reason !== "interview_request") {
+		throw new Error("message is required for supervisor decisions and progress updates.");
 	}
 	ensureSupervisorChannelDir(metadata.channelDir);
 	const requestId = randomUUID();
@@ -219,7 +193,7 @@ async function sendSupervisorRequest(params: ContactSupervisorParams, metadata:
 	const createdAt = Date.now();
 	const replyDeadline = createdAt + askTimeoutMs();
 	const expiresAt = expectsReply ? replyDeadline : undefined;
-	const message = formatChildMessage({ ...metadata, reason: params.reason, message: params.message, interview: params.interview });
+	const message = params.message?.trim() ?? "";
 	const requestToolCallId = typeof toolCallId === "string" && toolCallId.length > 0 ? toolCallId : undefined;
 	const request: SupervisorRequest = {
 		type: "subagent.supervisor.request",
@@ -299,7 +273,7 @@ function parseRequestFile(file: string, channelDir: string): PendingSupervisorRe
 		if (parsed.type !== "subagent.supervisor.request") return undefined;
 		if (typeof parsed.id !== "string" || !parsed.id) return undefined;
 		if (parsed.reason !== "need_decision" && parsed.reason !== "interview_request" && parsed.reason !== "progress_update") return undefined;
-		if (typeof parsed.message !== "string" || !parsed.message) return undefined;
+		if (typeof parsed.message !== "string" || (!parsed.message.trim() && parsed.reason !== "interview_request")) return undefined;
 		if (typeof parsed.runId !== "string" || typeof parsed.agent !== "string" || typeof parsed.childIndex !== "number") return undefined;
 		return {
 			...parsed as SupervisorRequest,
@@ -409,18 +383,8 @@ function cleanupStaleEmptySupervisorChannels(nowMs = Date.now()): number {
 	return removed;
 }
 
-function currentContextSessionId(state: Pick<SubagentState, "currentSessionId">, ctx: ExtensionContext): string | undefined {
-	try {
-		const sessionId = ctx.sessionManager.getSessionId();
-		if (sessionId) return sessionId;
-	} catch {
-		// Fall through to the last known identity.
-	}
-	return state.currentSessionId ?? undefined;
-}
-
-function requestMatchesContext(request: SupervisorRequest, state: Pick<SubagentState, "currentSessionId">, ctx: ExtensionContext): boolean {
-	const currentSessionId = currentContextSessionId(state, ctx);
+function requestMatchesOwner(request: SupervisorRequest, state: Pick<SubagentState, "supervisorOwnerSessionId">): boolean {
+	const currentSessionId = state.supervisorOwnerSessionId;
 	return Boolean(currentSessionId && request.orchestratorSessionId === currentSessionId);
 }
 
@@ -490,12 +454,12 @@ function requestRunInactive(request: SupervisorRequest, state: SubagentState): b
 	return stepStatus === "complete" || stepStatus === "completed" || stepStatus === "failed" || stepStatus === "paused";
 }
 
-function requestLifecycle(request: PendingSupervisorRequest, state: SubagentState, ctx: ExtensionContext | undefined, now: number): SupervisorRequestLifecycle {
-	if (ctx && !requestMatchesContext(request, state, ctx)) return "wrong-session";
+function requestLifecycle(request: PendingSupervisorRequest, state: SubagentState, now: number, runState: SubagentState): SupervisorRequestLifecycle {
+	if (!requestMatchesOwner(request, state)) return "wrong-session";
 	if (!fs.existsSync(request.requestFile)) return "missing";
 	if (request.expectsReply && fs.existsSync(replyPath(request.channelDir, request.id))) return "resolved";
 	if (request.expectsReply && now > requestExpiresAt(request, now)) return "expired";
-	if (request.expectsReply && requestRunInactive(request, state)) return "inactive";
+	if (request.expectsReply && requestRunInactive(request, runState)) return "inactive";
 	return "pending";
 }
 
@@ -503,10 +467,10 @@ function cleanupRequestLifecycle(request: PendingSupervisorRequest, lifecycle: S
 	if (lifecycle === "resolved" || lifecycle === "expired" || lifecycle === "inactive") removeRequestFile(request.requestFile);
 }
 
-function refreshPendingRequests(pending: Map<string, PendingSupervisorRequest>, state: SubagentState, ctx: ExtensionContext | undefined, onLifecycle: SupervisorRequestLifecycleObserver): void {
+function refreshPendingRequests(pending: Map<string, PendingSupervisorRequest>, state: SubagentState, onLifecycle: SupervisorRequestLifecycleObserver, runState: (request: SupervisorRequest) => SubagentState): void {
 	const now = Date.now();
 	for (const request of pending.values()) {
-		const lifecycle = requestLifecycle(request, state, ctx, now);
+		const lifecycle = requestLifecycle(request, state, now, runState(request));
 		if (lifecycle === "pending") continue;
 		pending.delete(request.id);
 		onLifecycle(request, lifecycle);
@@ -520,11 +484,24 @@ function formatPendingLine(request: PendingSupervisorRequest): string {
 }
 
 function requestVisibleText(request: PendingSupervisorRequest): string {
-	const lines = [request.message];
-	if (request.expectsReply) {
-		lines.push("", `Reply with: ${supervisorReplyHint(request.id)}`);
+	const lines = [
+		reasonHeading(request.reason),
+		`Run: ${request.runId}`,
+		`Agent: ${request.agent}`,
+		`Child index: ${request.childIndex}`,
+	];
+	lines.push("");
+	if (request.message) lines.push(request.message);
+	if (request.reason === "interview_request") {
+		lines.push(
+			"",
+			"Structured response requested. Reply with JSON, optionally fenced in ```json, matching the requested interview shape.",
+		);
+		if (request.interview !== undefined) lines.push(JSON.stringify(request.interview, null, "\t"));
 	}
-	return lines.join("\n");
+	if (request.expectsReply) lines.push("", `Reply with: ${supervisorReplyHint(request.id)}`);
+	lines.push("", `Live guidance: subagent({ action: "steer", id: ${JSON.stringify(request.runId)}, index: ${request.childIndex}, message: "..." })${request.expectsReply ? " (Reply to the pending request first.)" : ""}`);
+	return lines.join("\n").trimEnd();
 }
 
 function writeReply(request: PendingSupervisorRequest, message: string): SupervisorReply {
@@ -578,6 +555,7 @@ function resolvePendingRequest(pending: Map<string, PendingSupervisorRequest>, p
 		);
 		if (matches.length === 1) return matches[0]!;
 		if (matches.length > 1) throw new Error(`Multiple pending supervisor requests match '${params.to}'. Use replyTo.`);
+		throw new Error(`No pending supervisor request matches '${params.to}'. Use replyTo.`);
 	}
 	if (requests.length === 1) return requests[0]!;
 	if (requests.length === 0) throw new Error("No pending supervisor requests need a reply.");
@@ -595,14 +573,16 @@ function publicPendingRequests(pending: Map<string, PendingSupervisorRequest>):
 	}));
 }
 
-function buildParentSupervisorTool(pi: ExtensionAPI, pending: Map<string, PendingSupervisorRequest>, state: SubagentState, onLifecycle: SupervisorRequestLifecycleObserver): ToolDefinition<typeof IntercomParamsSchema, Record<string, unknown>> {
+function buildParentSupervisorTool(pi: ExtensionAPI, pending: Map<string, PendingSupervisorRequest>, state: SubagentState, onLifecycle: SupervisorRequestLifecycleObserver, discover: () => void, runState: (request: SupervisorRequest) => SubagentState): ToolDefinition<typeof IntercomParamsSchema, Record<string, unknown>> {
 	return {
 		name: NATIVE_SUPERVISOR_TOOL_NAME,
 		label: "Subagent Supervisor",
 		description: "Native pi-subagents supervisor channel. Use reply/pending/status to answer child subagent requests without overriding pi-intercom.",
 		parameters: IntercomParamsSchema,
 		async execute(_id, params) {
-			refreshPendingRequests(pending, state, state.lastUiContext ?? undefined, onLifecycle);
+			// Discover new request files even when demand-gated polling is idle.
+			discover();
+			refreshPendingRequests(pending, state, onLifecycle, runState);
 			const input = params as IntercomParams;
 			if (input.action === "status") {
 				return { content: [{ type: "text", text: `Native supervisor channel active. Pending replies: ${pending.size}.` }], details: { active: true, pending: pending.size, root: SUPERVISOR_CHANNEL_ROOT } };
@@ -620,9 +600,6 @@ function buildParentSupervisorTool(pi: ExtensionAPI, pending: Map<string, Pendin
 				clearForegroundSupervisorAttention(request, pending, state);
 				return { content: [{ type: "text", text: `Replied to supervisor request ${request.id}.` }], details: { replyTo: request.id, runId: request.runId, agent: request.agent } };
 			}
-			if (input.action === "send" || input.action === "ask") {
-				throw new Error("The native subagent supervisor handles replies only. Child agents initiate asks with contact_supervisor.");
-			}
 			throw new Error(`Unsupported supervisor action: ${input.action}`);
 		},
 	};
@@ -631,12 +608,19 @@ function buildParentSupervisorTool(pi: ExtensionAPI, pending: Map<string, Pendin
 export function createNativeSupervisorChannel(pi: ExtensionAPI, state: SubagentState, deps: NativeSupervisorChannelDeps = {}): {
 	start: () => void;
 	activateTransport: () => void;
+	findPendingAsks: (target: { runId: string; agent: string; childIndex: number }) => string[];
 	dispose: () => void;
 	pending: Map<string, PendingSupervisorRequest>;
 	getSupervisorRequestState: (event: ControlEvent) => SupervisorRequestState;
 } {
 	const watch = deps.watch ?? fs.watch;
 	const timers = deps.timers ?? globalThis;
+	const runState = (request: SupervisorRequest): SubagentState => {
+		for (const ownerState of deps.getCurrentOwnerStates?.() ?? []) {
+			if (ownerState.asyncJobs.has(request.runId)) return ownerState;
+		}
+		return state;
+	};
 	const pending = new Map<string, PendingSupervisorRequest>();
 	const requestCorrelations = new Map<string, SupervisorRequestCorrelation>();
 	const correlationKey = (request: { runId: string; agent: string; childIndex: number; toolCallId?: string }): string | undefined => {
@@ -682,7 +666,7 @@ export function createNativeSupervisorChannel(pi: ExtensionAPI, state: SubagentS
 		if (!fs.existsSync(correlation.request.requestFile)
 			|| fs.existsSync(replyPath(correlation.request.channelDir, correlation.request.id))
 			|| now > requestExpiresAt(correlation.request, now)
-			|| requestRunInactive(correlation.request, state)) {
+			|| requestRunInactive(correlation.request, runState(correlation.request))) {
 			rememberResolvedRequest(correlation.request);
 			return "resolved";
 		}
@@ -701,11 +685,17 @@ export function createNativeSupervisorChannel(pi: ExtensionAPI, state: SubagentS
 	const hasTransportDemand = () => {
 		if (pending.size > 0) return true;
 		if (state.foregroundControls.size > 0) return true;
-		return [...state.asyncJobs.values()].some((job) => job.status === "queued" || job.status === "running");
+		if ([...state.asyncJobs.values()].some((job) => job.status === "queued" || job.status === "running")) return true;
+		for (const ownerState of deps.getCurrentOwnerStates?.() ?? []) {
+			for (const job of ownerState.asyncJobs.values()) {
+				if (job.status === "queued" || job.status === "running") return true;
+			}
+		}
+		return false;
 	};
 
 	const registerParentTools = (): void => {
-		if (!hasTool(pi, NATIVE_SUPERVISOR_TOOL_NAME)) pi.registerTool(buildParentSupervisorTool(pi, pending, state, observeRequestLifecycle));
+		if (!hasTool(pi, NATIVE_SUPERVISOR_TOOL_NAME)) pi.registerTool(buildParentSupervisorTool(pi, pending, state, observeRequestLifecycle, () => poll(), runState));
 	};
 
 	const cleanupStaleChannelsIfDue = (): void => {
@@ -721,15 +711,14 @@ export function createNativeSupervisorChannel(pi: ExtensionAPI, state: SubagentS
 
 	const poll = (): void => {
 		cleanupStaleChannelsIfDue();
-		const ctx = state.lastUiContext;
-		if (!ctx) return;
-		refreshPendingRequests(pending, state, ctx, observeRequestLifecycle);
+		// Only display notifications require a live UI context, not request registration.
+		refreshPendingRequests(pending, state, observeRequestLifecycle, runState);
 		const now = Date.now();
 		for (const { channelDir, file } of listRequestFiles()) {
 			if (seenFiles.has(file)) continue;
 			const request = parseRequestFile(file, channelDir);
-			if (!request || !requestMatchesContext(request, state, ctx)) continue;
-			const lifecycle = requestLifecycle(request, state, undefined, now);
+			if (!request || !requestMatchesOwner(request, state)) continue;
+			const lifecycle = requestLifecycle(request, state, now, runState(request));
 			if (lifecycle !== "pending") {
 				seenFiles.add(file);
 				observeRequestLifecycle(request, lifecycle);
@@ -742,26 +731,34 @@ export function createNativeSupervisorChannel(pi: ExtensionAPI, state: SubagentS
 				pending.set(request.id, request);
 				markForegroundSupervisorAttention(request, state);
 			}
-			else {
-				removeRequestFile(request.requestFile);
+			// The ask is already queued above. A sendMessage failure (no UI, stale context) must not
+			// lose it, and must not abort the loop before the remaining asks register.
+			try {
+				pi.sendMessage({
+					customType: SUPERVISOR_REQUEST_MESSAGE_TYPE,
+					content: requestVisibleText(request),
+					display: true,
+					details: {
+						id: request.id,
+						requestId: request.id,
+						reason: request.reason,
+						expectsReply: request.expectsReply,
+						runId: request.runId,
+						agent: request.agent,
+						childIndex: request.childIndex,
+						...(request.childTarget ? { childTarget: request.childTarget } : {}),
+						...(request.interview !== undefined ? { interview: request.interview } : {}),
+						requestBody: request.message,
+						...(request.expectsReply ? { replyHint: supervisorReplyHint(request.id) } : {}),
+					},
+				}, { triggerTurn: true });
+				// sendMessage accepts synchronously; one-way updates stay on disk until it returns.
+				if (!request.expectsReply) removeRequestFile(request.requestFile);
+			} catch (error) {
+				// Allow an existing later scan to retry an unaccepted one-way update.
+				if (!request.expectsReply) seenFiles.delete(file);
+				console.error(`Failed to surface supervisor request ${request.id} as a user turn:`, error);
 			}
-			pi.sendMessage({
-				customType: SUPERVISOR_REQUEST_MESSAGE_TYPE,
-				content: requestVisibleText(request),
-				display: true,
-				details: {
-					id: request.id,
-					requestId: request.id,
-					reason: request.reason,
-					expectsReply: request.expectsReply,
-					runId: request.runId,
-					agent: request.agent,
-					childIndex: request.childIndex,
-					...(request.childTarget ? { childTarget: request.childTarget } : {}),
-					...(request.interview !== undefined ? { interview: request.interview } : {}),
-					...(request.expectsReply ? { replyHint: supervisorReplyHint(request.id) } : {}),
-				},
-			}, { triggerTurn: true });
 			if (request.expectsReply) {
 				(pi as { events?: IntercomEventBus }).events?.emit(INTERCOM_DETACH_REQUEST_EVENT, {
 					requestId: request.id,
@@ -838,6 +835,23 @@ export function createNativeSupervisorChannel(pi: ExtensionAPI, state: SubagentS
 			poll();
 			if (!useNativeWatcher() && hasTransportDemand()) startPolling();
 		},
+		findPendingAsks: (target) => {
+			// Receipt-only discovery: no registration, notification, cleanup or reply writes.
+			const channelDir = resolveSupervisorChannelDir(target.runId, target.agent, target.childIndex);
+			let files: string[];
+			try { files = fs.readdirSync(path.join(channelDir, REQUESTS_DIR)); }
+			catch (error) {
+				if ((error as NodeJS.ErrnoException).code === "ENOENT") return [];
+				throw error;
+			}
+			const now = Date.now();
+			return files.filter(file => file.endsWith(".json")).flatMap(file => {
+				const request = parseRequestFile(path.join(channelDir, REQUESTS_DIR, file), channelDir);
+				return request?.expectsReply && request.runId === target.runId
+					&& request.agent === target.agent && request.childIndex === target.childIndex
+					&& requestLifecycle(request, state, now, runState(request)) === "pending" ? [request.id] : [];
+			}).sort();
+		},
 		start: () => {
 			if (started) return;
 			started = true;

package/src/intercom/supervisor-ui.ts

@@ -17,6 +17,7 @@ export interface SupervisorRequestMessageDetails {
 	childIndex?: number;
 	childTarget?: string;
 	interview?: unknown;
+	requestBody?: string;
 	replyHint?: string;
 }
 
@@ -107,7 +108,7 @@ function optionalString(value: unknown): boolean {
 
 function requestDetails(value: unknown): SupervisorRequestMessageDetails | undefined {
 	if (!isRecord(value)) return undefined;
-	if (!optionalString(value.id) || !optionalString(value.requestId) || !optionalString(value.replyHint) || !optionalString(value.runId) || !optionalString(value.agent) || !optionalString(value.childTarget)) return undefined;
+	if (!optionalString(value.id) || !optionalString(value.requestId) || !optionalString(value.replyHint) || !optionalString(value.requestBody) || !optionalString(value.runId) || !optionalString(value.agent) || !optionalString(value.childTarget)) return undefined;
 	if (value.reason !== undefined && !isSupervisorReason(value.reason)) return undefined;
 	if (value.expectsReply !== undefined && typeof value.expectsReply !== "boolean") return undefined;
 	if (value.childIndex !== undefined && (typeof value.childIndex !== "number" || !Number.isFinite(value.childIndex))) return undefined;
@@ -153,7 +154,7 @@ function requestLines(message: SupervisorMessageLike, details: SupervisorRequest
 	if (details.childTarget) lines.push(`Child target: ${boundedField(details.childTarget)}`);
 	lines.push(`Request ID: ${requestId}`);
 	if (details.expectsReply) lines.push(`Reply with: ${displayText(details.replyHint ?? supervisorReplyHint(requestId), MAX_BODY_CHARS, expanded)}`);
-	lines.push("", "Request:", displayText(contentText(message.content) || "(no request body)", MAX_BODY_CHARS, expanded));
+	lines.push("", "Request:", displayText((details.requestBody ?? contentText(message.content)) || "(no request body)", MAX_BODY_CHARS, expanded));
 	if (details.interview !== undefined) lines.push("", "Interview shape:", interviewText(details.interview, expanded));
 	return lines;
 }

package/src/missions/workflow-state.ts

@@ -18,6 +18,12 @@ export interface MissionWorkflowState {
 	set(key: string, value: unknown): void;
 }
 
+export interface MissionWorkflowStateOptions {
+	isProcessAlive?: (pid: number) => boolean;
+	getProcessStartKey?: (pid: number) => string | undefined;
+	retryDelaysMs?: readonly number[];
+}
+
 export function missionStatePath(location: MissionStoreLocation, missionId: string): string {
 	return path.join(location.missionDir, validateMissionId(missionId), "state.json");
 }
@@ -66,13 +72,22 @@ function windowsProcessStartKey(pid: number): string | undefined {
 	}
 }
 
+let currentProcessKey: string | undefined | null = null;
+
 function processStartKey(pid: number): string | undefined {
+	// Foreign PIDs can be reused while this process lives, so resolve them afresh.
+	if (pid !== process.pid) return computeProcessStartKey(pid);
+	if (currentProcessKey === null) currentProcessKey = computeProcessStartKey(pid);
+	return currentProcessKey;
+}
+
+function computeProcessStartKey(pid: number): string | undefined {
 	if (process.platform === "linux") return linuxProcessStartKey(pid) ?? psProcessStartKey(pid);
 	if (process.platform === "win32") return windowsProcessStartKey(pid);
 	return undefined;
 }
 
-const CURRENT_PROCESS_KEY = processStartKey(process.pid);
+type StateLockOptions = Required<MissionWorkflowStateOptions>;
 
 function readStateLockOwner(lockPath: string): StateLockOwner | undefined {
 	try {
@@ -91,13 +106,13 @@ function readStateLockOwner(lockPath: string): StateLockOwner | undefined {
 	return undefined;
 }
 
-function stateLockIsStale(lockPath: string, now = Date.now()): boolean {
+function stateLockIsStale(lockPath: string, options: StateLockOptions, now = Date.now()): boolean {
 	const owner = readStateLockOwner(lockPath);
 	if (owner) {
-		if (!isProcessAlive(owner.pid)) return true;
+		if (!options.isProcessAlive(owner.pid)) return true;
 		if (owner.processKey) {
-			const currentProcessKey = owner.pid === process.pid ? CURRENT_PROCESS_KEY : processStartKey(owner.pid);
-			if (currentProcessKey) return owner.processKey !== currentProcessKey;
+			const observedProcessKey = options.getProcessStartKey(owner.pid);
+			if (observedProcessKey) return owner.processKey !== observedProcessKey;
 			if (owner.pid === process.pid) return true;
 		}
 		return false;
@@ -140,11 +155,11 @@ function waitForStateLock(delayMs: number | undefined, lockPath: string): void {
 	waitForFileSystemRetry(delayMs);
 }
 
-function reclaimStaleStateLock(lockPath: string, reclaimPath: string): boolean {
-	if (!stateLockIsStale(lockPath)) return false;
+function reclaimStaleStateLock(lockPath: string, reclaimPath: string, options: StateLockOptions): boolean {
+	if (!stateLockIsStale(lockPath, options)) return false;
 	if (!tryMakeDirectory(reclaimPath, 0o700)) return false;
 	try {
-		if (!stateLockIsStale(lockPath)) return false;
+		if (!stateLockIsStale(lockPath, options)) return false;
 		fs.rmSync(lockPath, { recursive: true, force: true });
 		return true;
 	} finally {
@@ -152,7 +167,7 @@ function reclaimStaleStateLock(lockPath: string, reclaimPath: string): boolean {
 	}
 }
 
-function withStateFileLock<T>(filePath: string, operation: () => T): T {
+function withStateFileLock<T>(filePath: string, operation: () => T, options: StateLockOptions): T {
 	fs.mkdirSync(path.dirname(filePath), { recursive: true });
 	const lockPath = `${filePath}.lock`;
 	const reclaimPath = `${lockPath}.reclaim`;
@@ -163,7 +178,7 @@ function withStateFileLock<T>(filePath: string, operation: () => T): T {
 				fs.rmSync(reclaimPath, { recursive: true, force: true });
 				continue;
 			}
-			waitForStateLock(DEFAULT_FILE_SYSTEM_RETRY_DELAYS_MS[attempt], lockPath);
+			waitForStateLock(options.retryDelaysMs[attempt], lockPath);
 			continue;
 		}
 		let acquired = false;
@@ -171,17 +186,18 @@ function withStateFileLock<T>(filePath: string, operation: () => T): T {
 			acquired = tryMakeDirectory(lockPath, 0o700);
 		} catch (error) {
 			if (isRetryableFileSystemError(error)) {
-				waitForStateLock(DEFAULT_FILE_SYSTEM_RETRY_DELAYS_MS[attempt], lockPath);
+				waitForStateLock(options.retryDelaysMs[attempt], lockPath);
 				continue;
 			}
 			throw new Error(`Failed to acquire mission state lock '${lockPath}': ${error instanceof Error ? error.message : String(error)}`);
 		}
 		if (!acquired) {
-			if (reclaimStaleStateLock(lockPath, reclaimPath)) continue;
-			waitForStateLock(DEFAULT_FILE_SYSTEM_RETRY_DELAYS_MS[attempt], lockPath);
+			if (reclaimStaleStateLock(lockPath, reclaimPath, options)) continue;
+			waitForStateLock(options.retryDelaysMs[attempt], lockPath);
 			continue;
 		}
-		owner = { pid: process.pid, token: randomUUID(), createdAt: Date.now(), ...(CURRENT_PROCESS_KEY ? { processKey: CURRENT_PROCESS_KEY } : {}) };
+		const key = options.getProcessStartKey(process.pid);
+		owner = { pid: process.pid, token: randomUUID(), createdAt: Date.now(), ...(key ? { processKey: key } : {}) };
 		try {
 			fs.writeFileSync(path.join(lockPath, "owner.json"), JSON.stringify(owner), { encoding: "utf-8", mode: 0o600 });
 		} catch (error) {
@@ -205,8 +221,13 @@ function validateStateKey(value: unknown): string {
 	return value;
 }
 
-export function createMissionWorkflowState(location: MissionStoreLocation, missionId: string): MissionWorkflowState {
+export function createMissionWorkflowState(location: MissionStoreLocation, missionId: string, options: MissionWorkflowStateOptions = {}): MissionWorkflowState {
 	const filePath = missionStatePath(location, missionId);
+	const lockOptions: StateLockOptions = {
+		isProcessAlive: options.isProcessAlive ?? isProcessAlive,
+		getProcessStartKey: options.getProcessStartKey ?? processStartKey,
+		retryDelaysMs: options.retryDelaysMs ?? DEFAULT_FILE_SYSTEM_RETRY_DELAYS_MS,
+	};
 	let loaded = false;
 	let values: Record<string, unknown> = Object.create(null) as Record<string, unknown>;
 
@@ -254,7 +275,7 @@ export function createMissionWorkflowState(location: MissionStoreLocation, missi
 				writePrivateAtomicJson(filePath, next);
 				values = next;
 				loaded = true;
-			});
+			}, lockOptions);
 		},
 	};
 }