@selesai/code 0.8.3 → 0.8.5

package/dist/extensions/pi-subagents/src/missions/store.ts

@@ -2,6 +2,7 @@ import { createHash, randomUUID } from "node:crypto";
 import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
+import { getProjectSubagentsDir } from "../shared/artifacts.ts";
 import { writePrivateAtomicJson } from "../shared/atomic-json.ts";
 import { getAgentDir } from "../shared/utils.ts";
 import {
@@ -12,6 +13,7 @@ import {
 	type MissionArtifactKind,
 	type MissionCreateInput,
 	type MissionDecision,
+	type MissionGoal,
 	type MissionIndexEntry,
 	type MissionListResult,
 	type MissionReceipt,
@@ -23,7 +25,10 @@ import {
 	type MissionStatus,
 	type MissionStoreConfig,
 	type MissionStoreLocation,
+	type MissionTokenBudget,
+	type MissionTokenUsage,
 	type MissionUpdateInput,
+	type MissionWorkflowChild,
 } from "./types.ts";
 
 const MISSION_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
@@ -63,6 +68,37 @@ function missionStatus(value: unknown, label: string): MissionStatus {
 	return value as MissionStatus;
 }
 
+function positiveTokenCount(value: unknown, label: string): number {
+	if (!Number.isSafeInteger(value) || (value as number) < 1) throw new Error(`${label} must be a positive integer`);
+	return value as number;
+}
+
+function nonNegativeTokenCount(value: unknown, label: string): number {
+	if (!Number.isSafeInteger(value) || (value as number) < 0) throw new Error(`${label} must be a non-negative integer`);
+	return value as number;
+}
+
+function parseStoredGoal(value: unknown, label: string): { goal?: MissionGoal; legacyObjective?: string } {
+	if (typeof value === "string") return { legacyObjective: requiredString(value, label).trim() };
+	return { goal: parseGoal(value, label) };
+}
+
+function parseGoal(value: unknown, label: string): MissionGoal {
+	const input = asObject(value, label);
+	if (input.status !== "active" && input.status !== "paused" && input.status !== "budget-exhausted") throw new Error(`${label}.status is invalid`);
+	return { status: input.status };
+}
+
+function parseBudget(value: unknown, label: string): MissionTokenBudget {
+	const input = asObject(value, label);
+	return { tokens: positiveTokenCount(input.tokens, `${label}.tokens`) };
+}
+
+function parseUsage(value: unknown, label: string): MissionTokenUsage {
+	const input = asObject(value, label);
+	return { tokens: nonNegativeTokenCount(input.tokens, `${label}.tokens`) };
+}
+
 function stringArray(value: unknown, label: string): string[] {
 	if (!Array.isArray(value)) throw new Error(`${label} must be an array of non-empty strings`);
 	const result = value.map((item, index) => requiredString(item, `${label}[${index}]`).trim());
@@ -94,6 +130,7 @@ function parseRunLink(value: unknown, label: string): MissionRunLink {
 		...(optionalString(input.status, `${label}.status`) ? { status: input.status as string } : {}),
 		...(input.startedAt !== undefined ? { startedAt: timestamp(input.startedAt, `${label}.startedAt`) } : {}),
 		...(input.completedAt !== undefined ? { completedAt: timestamp(input.completedAt, `${label}.completedAt`) } : {}),
+		...(input.usage !== undefined ? { usage: parseUsage(input.usage, `${label}.usage`) } : {}),
 	};
 }
 
@@ -114,6 +151,33 @@ function parseDecision(value: unknown, label: string): MissionDecision {
 	};
 }
 
+function parseWorkflowChild(value: unknown, label: string): MissionWorkflowChild {
+	const input = asObject(value, label);
+	const artifactPaths = input.artifactPaths === undefined ? [] : stringArray(input.artifactPaths, `${label}.artifactPaths`);
+	const heartbeat = input.heartbeat === undefined ? undefined : asObject(input.heartbeat, `${label}.heartbeat`);
+	return {
+		workflowRunId: requiredString(input.workflowRunId, `${label}.workflowRunId`),
+		key: validateMissionId(input.key, `${label}.key`),
+		status: requiredString(input.status, `${label}.status`),
+		startedAt: timestamp(input.startedAt, `${label}.startedAt`),
+		updatedAt: timestamp(input.updatedAt, `${label}.updatedAt`),
+		artifactPaths,
+		...(optionalString(input.runId, `${label}.runId`) ? { runId: input.runId as string } : {}),
+		...(optionalString(input.agent, `${label}.agent`) ? { agent: input.agent as string } : {}),
+		...(optionalString(input.task, `${label}.task`) ? { task: input.task as string } : {}),
+		...(optionalString(input.label, `${label}.label`) ? { label: input.label as string } : {}),
+		...(optionalString(input.phase, `${label}.phase`) ? { phase: input.phase as string } : {}),
+		...(input.completedAt !== undefined ? { completedAt: timestamp(input.completedAt, `${label}.completedAt`) } : {}),
+		...(optionalString(input.sessionPath, `${label}.sessionPath`) ? { sessionPath: input.sessionPath as string } : {}),
+		...(heartbeat ? { heartbeat: {
+			updatedAt: timestamp(heartbeat.updatedAt, `${label}.heartbeat.updatedAt`),
+			...(optionalString(heartbeat.status, `${label}.heartbeat.status`) ? { status: heartbeat.status as string } : {}),
+			...(optionalString(heartbeat.phase, `${label}.heartbeat.phase`) ? { phase: heartbeat.phase as string } : {}),
+			...(optionalString(heartbeat.message, `${label}.heartbeat.message`) ? { message: heartbeat.message as string } : {}),
+		} } : {}),
+	};
+}
+
 function parseArtifact(value: unknown, label: string): MissionArtifact {
 	const input = asObject(value, label);
 	const kind = requiredString(input.kind, `${label}.kind`) as MissionArtifactKind;
@@ -151,22 +215,34 @@ export function parseMissionRecord(value: unknown, source = "mission record"): M
 	const input = asObject(value, source);
 	if (input.schemaVersion !== 1) throw new Error(`${source}.schemaVersion must be 1`);
 	if (!Array.isArray(input.runs)) throw new Error(`${source}.runs must be an array`);
+	if (input.workflowChildren !== undefined && !Array.isArray(input.workflowChildren)) throw new Error(`${source}.workflowChildren must be an array`);
 	if (!Array.isArray(input.decisions)) throw new Error(`${source}.decisions must be an array`);
 	if (!Array.isArray(input.artifacts)) throw new Error(`${source}.artifacts must be an array`);
 	if (input.receipts !== undefined && !Array.isArray(input.receipts)) throw new Error(`${source}.receipts must be an array`);
 	const runs = input.runs as unknown[];
+	const workflowChildren = (input.workflowChildren ?? []) as unknown[];
 	const decisions = input.decisions as unknown[];
 	const artifacts = input.artifacts as unknown[];
 	const receipts = (input.receipts ?? []) as unknown[];
+	const parsedGoal = input.goal !== undefined ? parseStoredGoal(input.goal, `${source}.goal`) : {};
+	const budget = input.budget !== undefined ? parseBudget(input.budget, `${source}.budget`) : undefined;
+	const usage = input.usage !== undefined ? parseUsage(input.usage, `${source}.usage`) : undefined;
+	const objective = optionalString(input.objective, `${source}.objective`)?.trim() ?? parsedGoal.legacyObjective;
+	if (!objective) throw new Error(`${source}.objective must be a non-empty string`);
+	if (parsedGoal.goal && !budget) throw new Error(`${source}.budget is required for a goal mission`);
 	return {
 		schemaVersion: 1,
 		id: validateMissionId(input.id, `${source}.id`),
 		title: requiredString(input.title, `${source}.title`),
-		goal: requiredString(input.goal, `${source}.goal`),
+		objective,
+		...(parsedGoal.goal ? { goal: parsedGoal.goal } : {}),
+		...(budget ? { budget } : {}),
+		...(usage ? { usage } : {}),
 		status: missionStatus(input.status, `${source}.status`),
 		createdAt: timestamp(input.createdAt, `${source}.createdAt`),
 		updatedAt: timestamp(input.updatedAt, `${source}.updatedAt`),
 		runs: runs.map((item, index) => parseRunLink(item, `${source}.runs[${index}]`)),
+		workflowChildren: workflowChildren.map((item, index) => parseWorkflowChild(item, `${source}.workflowChildren[${index}]`)),
 		decisions: decisions.map((item, index) => parseDecision(item, `${source}.decisions[${index}]`)),
 		artifacts: artifacts.map((item, index) => parseArtifact(item, `${source}.artifacts[${index}]`)),
 		receipts: receipts.map((item, index) => parseReceipt(item, `${source}.receipts[${index}]`)),
@@ -215,7 +291,7 @@ export function resolveMissionStoreLocation(input: {
 	const projectRoot = path.resolve(input.projectRoot);
 	const missionDir = input.config?.directory
 		? expandConfiguredPath(input.config.directory, projectRoot)
-		: path.join(projectRoot, ".pi-subagents", "missions");
+		: path.join(getProjectSubagentsDir(projectRoot), "missions");
 	const globalIndexDir = input.config?.globalIndexDir
 		? expandConfiguredPath(input.config.globalIndexDir, projectRoot)
 		: path.join(input.agentDir ?? getAgentDir(), "missions", "index");
@@ -279,6 +355,7 @@ function pruneTerminalMissions(location: MissionStoreLocation, maxTerminal: numb
 	for (const record of terminal.slice(maxTerminal)) {
 		try {
 			fs.rmSync(missionRecordPath(location, record.id), { force: true });
+			fs.rmSync(path.join(location.missionDir, record.id), { recursive: true, force: true });
 			if (location.writeGlobalIndex) fs.rmSync(indexPath(location, record), { force: true });
 		} catch {
 			// Retention is best-effort and must never block a launch.
@@ -292,18 +369,23 @@ export function createMission(location: MissionStoreLocation, input: MissionCrea
 		schemaVersion: 1,
 		id: randomUUID(),
 		title: requiredString(input.title, "mission.title").trim(),
-		goal: requiredString(input.goal, "mission.goal").trim(),
+		objective: requiredString(input.objective, "mission.objective").trim(),
+		...(input.goal === true ? { goal: { status: "active" as const } } : {}),
+		...(input.budget ? { budget: parseBudget(input.budget, "mission.budget") } : {}),
+		...(input.goal === true ? { usage: { tokens: 0 } } : {}),
 		status: input.status ?? "planned",
 		createdAt,
 		updatedAt: createdAt,
 		cwd: location.projectRoot,
 		runs: [],
+		workflowChildren: [],
 		decisions: [],
 		artifacts: [],
 		receipts: [],
 		...(input.ownerSessionId ? { ownerSessionId: requiredString(input.ownerSessionId, "mission.ownerSessionId") } : {}),
 		...(input.labels ? { labels: stringArray(input.labels, "mission.labels") } : {}),
 	};
+	if (input.goal === true && !input.budget) throw new Error("mission.budget is required when mission.goal is true");
 	const created = writeMission(location, record);
 	pruneTerminalMissions(location, retainTerminal);
 	return created;
@@ -314,11 +396,11 @@ export class MissionNotFoundError extends Error {
 	readonly missionId: string;
 	readonly missionDir: string;
 
-	constructor(missionId: string, missionDir: string) {
-		super(`Mission '${missionId}' was not found in ${missionDir}`);
+	constructor(missionId: string, location: MissionStoreLocation) {
+		super(`Mission '${missionId}' was not found in mission directory '${location.missionDir}' for project root '${location.projectRoot}'. If it was created in another worktree, run the request from that worktree.`);
 		this.name = "MissionNotFoundError";
 		this.missionId = missionId;
-		this.missionDir = missionDir;
+		this.missionDir = location.missionDir;
 	}
 }
 
@@ -328,7 +410,7 @@ export function readMission(location: MissionStoreLocation, missionId: string):
 	try {
 		raw = fs.readFileSync(filePath, "utf-8");
 	} catch (error) {
-		if ((error as NodeJS.ErrnoException).code === "ENOENT") throw new MissionNotFoundError(missionId, location.missionDir);
+		if ((error as NodeJS.ErrnoException).code === "ENOENT") throw new MissionNotFoundError(missionId, location);
 		throw error;
 	}
 	try {
@@ -363,6 +445,28 @@ export function updateMission(location: MissionStoreLocation, missionId: string,
 		if (existingIndex === -1) runs.push(run);
 		else runs[existingIndex] = { ...runs[existingIndex]!, ...run };
 	}
+	const workflowChildren = [...current.workflowChildren];
+	for (const candidate of update.upsertWorkflowChildren ?? []) {
+		const nowIso = now.toISOString();
+		const parsed = parseWorkflowChild({
+			...candidate,
+			startedAt: candidate.startedAt ?? nowIso,
+			updatedAt: nowIso,
+			artifactPaths: candidate.artifactPaths ?? [],
+			...(candidate.heartbeat ? { heartbeat: { ...candidate.heartbeat, updatedAt: nowIso } } : {}),
+		}, "mission.update.upsertWorkflowChildren[]");
+		const existingIndex = workflowChildren.findIndex((child) => child.workflowRunId === parsed.workflowRunId && child.key === parsed.key);
+		if (existingIndex === -1) workflowChildren.push(parsed);
+		else {
+			const existing = workflowChildren[existingIndex]!;
+			workflowChildren[existingIndex] = parseWorkflowChild({
+				...existing,
+				...parsed,
+				startedAt: existing.startedAt,
+				artifactPaths: [...new Set([...existing.artifactPaths, ...parsed.artifactPaths])],
+			}, "mission.update.upsertWorkflowChildren[]");
+		}
+	}
 	const artifacts = [...current.artifacts];
 	for (const candidate of update.addArtifacts ?? []) {
 		const artifact = parseArtifact(candidate, "mission.update.addArtifacts[]");
@@ -390,20 +494,58 @@ export function updateMission(location: MissionStoreLocation, missionId: string,
 			...(decision.recommendation ? { recommendation: requiredString(decision.recommendation, "mission.update.addDecisions[].recommendation") } : {}),
 		})),
 	];
+	if (update.resolveDecision) {
+		const decisionId = validateMissionId(update.resolveDecision.id, "mission.update.resolveDecision.id");
+		const decisionIndex = decisions.findIndex((decision) => decision.id === decisionId);
+		if (decisionIndex === -1) throw new Error(`Decision '${decisionId}' was not found in mission '${missionId}'`);
+		if (decisions[decisionIndex]!.status === "resolved") throw new Error(`Decision '${decisionId}' is already resolved`);
+		decisions[decisionIndex] = {
+			...decisions[decisionIndex]!,
+			status: "resolved",
+			resolvedAt: createdAt,
+			resolution: requiredString(update.resolveDecision.resolution, "mission.update.resolveDecision.resolution").trim(),
+		};
+	}
+	const budget = update.budget !== undefined ? parseBudget(update.budget, "mission.update.budget") : current.budget;
+	const usage = update.usage !== undefined
+		? parseUsage(update.usage, "mission.update.usage")
+		: { tokens: runs.reduce((total, run) => total + (run.usage?.tokens ?? 0), 0) };
+	let goal = update.goal === false ? undefined : update.goal !== undefined ? parseGoal(update.goal, "mission.update.goal") : current.goal;
+	if (goal && !budget) throw new Error("mission.update.budget is required when enabling a goal mission");
+	if (goal && budget) {
+		goal = usage.tokens >= budget.tokens
+			? { status: "budget-exhausted" }
+			: goal.status === "budget-exhausted"
+				? { status: "active" }
+				: goal;
+	}
+	const hasOpenDecisions = decisions.some((decision) => decision.status === "open");
+	const requestedStatus = update.status !== undefined ? missionStatus(update.status, "mission.update.status") : undefined;
+	const candidateStatus = requestedStatus
+		?? (update.addDecisions?.length && current.status === "active"
+			? "needs_decision"
+			: update.resolveDecision && current.status === "needs_decision" && !hasOpenDecisions
+				? "active"
+				: current.status);
+	const decisionStatus = hasOpenDecisions && (candidateStatus === "active" || candidateStatus === "completed") ? "needs_decision" : candidateStatus;
 	const next: MissionRecord = {
 		...current,
 		updatedAt: createdAt,
 		runs,
+		workflowChildren,
 		artifacts,
 		receipts,
 		decisions,
 		...(update.title !== undefined ? { title: requiredString(update.title, "mission.update.title").trim() } : {}),
-		...(update.goal !== undefined ? { goal: requiredString(update.goal, "mission.update.goal").trim() } : {}),
-		...(update.status !== undefined ? { status: missionStatus(update.status, "mission.update.status") } : {}),
+		...(update.objective !== undefined ? { objective: requiredString(update.objective, "mission.update.objective").trim() } : {}),
+		...(budget ? { budget } : {}),
+		...(goal ? { goal, usage } : {}),
+		status: decisionStatus,
 		...(update.summary !== undefined ? { summary: requiredString(update.summary, "mission.update.summary") } : {}),
 		...(update.labels !== undefined ? { labels: stringArray(update.labels, "mission.update.labels") } : {}),
 		...(update.acceptance !== undefined ? { acceptance: update.acceptance } : {}),
 	};
+	if (!goal) delete next.goal;
 	const updated = writeMission(location, next);
 	if (TERMINAL_MISSION_STATUSES.has(updated.status)) pruneTerminalMissions(location, retainTerminal);
 	return updated;

package/dist/extensions/pi-subagents/src/missions/types.ts

@@ -13,6 +13,19 @@ export type MissionRunMode = "single" | "parallel" | "chain" | "workflow" | "sch
 export type MissionArtifactKind = "status" | "output" | "patch" | "manifest" | "review" | "note" | "other";
 export type MissionReceiptKind = "pull_request" | "ci" | "deployment" | "release";
 export type MissionReceiptStatus = "pending" | "ready" | "succeeded" | "failed";
+export type MissionGoalStatus = "active" | "paused" | "budget-exhausted";
+
+export interface MissionGoal {
+	status: MissionGoalStatus;
+}
+
+export interface MissionTokenBudget {
+	tokens: number;
+}
+
+export interface MissionTokenUsage {
+	tokens: number;
+}
 
 export interface MissionRunLink {
 	runId: string;
@@ -23,6 +36,7 @@ export interface MissionRunLink {
 	status?: string;
 	startedAt?: string;
 	completedAt?: string;
+	usage?: MissionTokenUsage;
 }
 
 export interface MissionDecision {
@@ -37,6 +51,36 @@ export interface MissionDecision {
 	resolution?: string;
 }
 
+export interface MissionChildHeartbeat {
+	updatedAt: string;
+	status?: string;
+	phase?: string;
+	message?: string;
+}
+
+export interface MissionWorkflowChild {
+	workflowRunId: string;
+	key: string;
+	status: string;
+	startedAt: string;
+	updatedAt: string;
+	runId?: string;
+	agent?: string;
+	task?: string;
+	label?: string;
+	phase?: string;
+	completedAt?: string;
+	sessionPath?: string;
+	artifactPaths: string[];
+	heartbeat?: MissionChildHeartbeat;
+}
+
+export type MissionWorkflowChildUpdate = Pick<MissionWorkflowChild, "workflowRunId" | "key" | "status"> & Partial<Omit<MissionWorkflowChild, "workflowRunId" | "key" | "status" | "startedAt" | "updatedAt" | "artifactPaths" | "heartbeat">> & {
+	startedAt?: string;
+	artifactPaths?: string[];
+	heartbeat?: Omit<MissionChildHeartbeat, "updatedAt"> & { updatedAt?: string };
+};
+
 export interface MissionArtifact {
 	kind: MissionArtifactKind;
 	path: string;
@@ -56,13 +100,17 @@ export interface MissionRecord {
 	schemaVersion: 1;
 	id: string;
 	title: string;
-	goal: string;
+	objective: string;
+	goal?: MissionGoal;
+	budget?: MissionTokenBudget;
+	usage?: MissionTokenUsage;
 	status: MissionStatus;
 	createdAt: string;
 	updatedAt: string;
 	cwd?: string;
 	ownerSessionId?: string;
 	runs: MissionRunLink[];
+	workflowChildren: MissionWorkflowChild[];
 	decisions: MissionDecision[];
 	artifacts: MissionArtifact[];
 	receipts: MissionReceipt[];
@@ -115,7 +163,9 @@ export interface GlobalMissionListResult {
 
 export interface MissionCreateInput {
 	title: string;
-	goal: string;
+	objective: string;
+	goal?: boolean;
+	budget?: MissionTokenBudget;
 	status?: MissionStatus;
 	labels?: string[];
 	ownerSessionId?: string;
@@ -123,13 +173,18 @@ export interface MissionCreateInput {
 
 export interface MissionUpdateInput {
 	title?: string;
-	goal?: string;
+	objective?: string;
+	goal?: MissionGoal | false;
+	budget?: MissionTokenBudget;
+	usage?: MissionTokenUsage;
 	status?: MissionStatus;
 	summary?: string;
 	labels?: string[];
 	acceptance?: unknown;
 	addRuns?: MissionRunLink[];
+	upsertWorkflowChildren?: MissionWorkflowChildUpdate[];
 	addArtifacts?: MissionArtifact[];
 	addDecisions?: Array<Omit<MissionDecision, "id" | "status" | "createdAt">>;
+	resolveDecision?: { id: string; resolution: string };
 	addReceipts?: Array<Omit<MissionReceipt, "createdAt">>;
 }

package/dist/extensions/pi-subagents/src/missions/workflow-state.ts

@@ -0,0 +1,260 @@
+import { execFileSync } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { writePrivateAtomicJson } from "../shared/atomic-json.ts";
+import { DEFAULT_FILE_SYSTEM_RETRY_DELAYS_MS, isRetryableFileSystemError, waitForFileSystemRetry } from "../shared/file-system-retry.ts";
+import { assertWorkflowJsonValue } from "../workflows/scripted-workflow.ts";
+import type { MissionStoreLocation } from "./types.ts";
+import { validateMissionId } from "./store.ts";
+
+const STATE_KEY_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
+const STATE_LOCK_STALE_MS = 60_000;
+export const MISSION_STATE_MAX_BYTES = 256 * 1024;
+
+export interface MissionWorkflowState {
+	path: string;
+	get(key: string): unknown;
+	set(key: string, value: unknown): void;
+}
+
+export function missionStatePath(location: MissionStoreLocation, missionId: string): string {
+	return path.join(location.missionDir, validateMissionId(missionId), "state.json");
+}
+
+function isProcessAlive(pid: number): boolean {
+	try {
+		process.kill(pid, 0);
+		return true;
+	} catch (error) {
+		return (error as NodeJS.ErrnoException).code === "EPERM";
+	}
+}
+
+interface StateLockOwner {
+	pid: number;
+	token: string;
+	createdAt: number;
+	processKey?: string;
+}
+
+function linuxProcessStartKey(pid: number): string | undefined {
+	try {
+		const raw = fs.readFileSync(`/proc/${pid}/stat`, "utf-8");
+		const tail = raw.slice(raw.lastIndexOf(")") + 2).trim().split(/\s+/);
+		return tail[19] ? `linux:${tail[19]}` : undefined;
+	} catch {
+		return undefined;
+	}
+}
+
+function psProcessStartKey(pid: number): string | undefined {
+	try {
+		const raw = execFileSync("ps", ["-p", String(pid), "-o", "lstart="], { encoding: "utf-8", stdio: ["ignore", "pipe", "ignore"], timeout: 1000 }).trim();
+		return raw ? `ps:${raw}` : undefined;
+	} catch {
+		return undefined;
+	}
+}
+
+function windowsProcessStartKey(pid: number): string | undefined {
+	try {
+		const raw = execFileSync("powershell.exe", ["-NoProfile", "-Command", `(Get-CimInstance Win32_Process -Filter \"ProcessId=${pid}\").CreationDate`], { encoding: "utf-8", stdio: ["ignore", "pipe", "ignore"], timeout: 1000 }).trim();
+		return raw ? `win:${raw}` : undefined;
+	} catch {
+		return undefined;
+	}
+}
+
+function processStartKey(pid: number): string | undefined {
+	if (process.platform === "linux") return linuxProcessStartKey(pid) ?? psProcessStartKey(pid);
+	if (process.platform === "win32") return windowsProcessStartKey(pid);
+	return psProcessStartKey(pid);
+}
+
+const CURRENT_PROCESS_KEY = processStartKey(process.pid);
+
+function readStateLockOwner(lockPath: string): StateLockOwner | undefined {
+	try {
+		const owner = JSON.parse(fs.readFileSync(path.join(lockPath, "owner.json"), "utf-8")) as { pid?: unknown; token?: unknown; createdAt?: unknown; processKey?: unknown };
+		if (Number.isSafeInteger(owner.pid) && (owner.pid as number) > 0 && typeof owner.token === "string" && owner.token && Number.isSafeInteger(owner.createdAt)) {
+			return {
+				pid: owner.pid as number,
+				token: owner.token,
+				createdAt: owner.createdAt as number,
+				...(typeof owner.processKey === "string" && owner.processKey ? { processKey: owner.processKey } : {}),
+			};
+		}
+	} catch {
+		return undefined;
+	}
+	return undefined;
+}
+
+function stateLockIsStale(lockPath: string, now = Date.now()): boolean {
+	const owner = readStateLockOwner(lockPath);
+	if (owner) {
+		if (!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;
+			if (owner.pid === process.pid) return true;
+		}
+		return false;
+	}
+	try {
+		return now - fs.statSync(lockPath).mtimeMs > STATE_LOCK_STALE_MS;
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code === "ENOENT") return false;
+		throw error;
+	}
+}
+
+function removeOwnedStateLock(lockPath: string, owner: StateLockOwner): void {
+	const current = readStateLockOwner(lockPath);
+	if (current?.token !== owner.token) return;
+	fs.rmSync(lockPath, { recursive: true, force: true });
+}
+
+function staleDirectoryExists(dirPath: string, now = Date.now()): boolean {
+	try {
+		return now - fs.statSync(dirPath).mtimeMs > STATE_LOCK_STALE_MS;
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code === "ENOENT") return false;
+		throw error;
+	}
+}
+
+function tryMakeDirectory(dirPath: string, mode: number): boolean {
+	try {
+		fs.mkdirSync(dirPath, { mode });
+		return true;
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code === "EEXIST") return false;
+		throw error;
+	}
+}
+
+function waitForStateLock(delayMs: number | undefined, lockPath: string): void {
+	if (delayMs === undefined) throw new Error(`Timed out acquiring mission state lock '${lockPath}'.`);
+	waitForFileSystemRetry(delayMs);
+}
+
+function reclaimStaleStateLock(lockPath: string, reclaimPath: string): boolean {
+	if (!stateLockIsStale(lockPath)) return false;
+	if (!tryMakeDirectory(reclaimPath, 0o700)) return false;
+	try {
+		if (!stateLockIsStale(lockPath)) return false;
+		fs.rmSync(lockPath, { recursive: true, force: true });
+		return true;
+	} finally {
+		fs.rmSync(reclaimPath, { recursive: true, force: true });
+	}
+}
+
+function withStateFileLock<T>(filePath: string, operation: () => T): T {
+	fs.mkdirSync(path.dirname(filePath), { recursive: true });
+	const lockPath = `${filePath}.lock`;
+	const reclaimPath = `${lockPath}.reclaim`;
+	let owner: StateLockOwner | undefined;
+	for (let attempt = 0; ; attempt++) {
+		if (fs.existsSync(reclaimPath)) {
+			if (staleDirectoryExists(reclaimPath)) {
+				fs.rmSync(reclaimPath, { recursive: true, force: true });
+				continue;
+			}
+			waitForStateLock(DEFAULT_FILE_SYSTEM_RETRY_DELAYS_MS[attempt], lockPath);
+			continue;
+		}
+		let acquired = false;
+		try {
+			acquired = tryMakeDirectory(lockPath, 0o700);
+		} catch (error) {
+			if (isRetryableFileSystemError(error)) {
+				waitForStateLock(DEFAULT_FILE_SYSTEM_RETRY_DELAYS_MS[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);
+			continue;
+		}
+		owner = { pid: process.pid, token: randomUUID(), createdAt: Date.now(), ...(CURRENT_PROCESS_KEY ? { processKey: CURRENT_PROCESS_KEY } : {}) };
+		try {
+			fs.writeFileSync(path.join(lockPath, "owner.json"), JSON.stringify(owner), { encoding: "utf-8", mode: 0o600 });
+		} catch (error) {
+			fs.rmSync(lockPath, { recursive: true, force: true });
+			owner = undefined;
+			throw error;
+		}
+		break;
+	}
+	try {
+		return operation();
+	} finally {
+		if (owner) removeOwnedStateLock(lockPath, owner);
+	}
+}
+
+function validateStateKey(value: unknown): string {
+	if (typeof value !== "string" || !STATE_KEY_PATTERN.test(value)) {
+		throw new Error("state key must be 1-128 characters using letters, numbers, '.', '_' or '-', and start with a letter or number.");
+	}
+	return value;
+}
+
+export function createMissionWorkflowState(location: MissionStoreLocation, missionId: string): MissionWorkflowState {
+	const filePath = missionStatePath(location, missionId);
+	let loaded = false;
+	let values: Record<string, unknown> = Object.create(null) as Record<string, unknown>;
+
+	const readStateFile = (): Record<string, unknown> => {
+		let raw: string;
+		try {
+			raw = fs.readFileSync(filePath, "utf-8");
+		} catch (error) {
+			if ((error as NodeJS.ErrnoException).code === "ENOENT") return Object.create(null) as Record<string, unknown>;
+			throw new Error(`Failed to read mission state '${filePath}': ${error instanceof Error ? error.message : String(error)}`);
+		}
+		const bytes = Buffer.byteLength(raw);
+		if (bytes > MISSION_STATE_MAX_BYTES) throw new Error(`Mission state file '${filePath}' exceeds the 256 KiB limit (${bytes} bytes).`);
+		try {
+			const parsed: unknown = JSON.parse(raw);
+			if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) throw new Error("root must be a JSON object");
+			assertWorkflowJsonValue(parsed, "mission state");
+			return Object.assign(Object.create(null) as Record<string, unknown>, parsed);
+		} catch (error) {
+			throw new Error(`Invalid mission state file '${filePath}': ${error instanceof Error ? error.message : String(error)}`);
+		}
+	};
+
+	const load = (): Record<string, unknown> => {
+		if (loaded) return values;
+		values = readStateFile();
+		loaded = true;
+		return values;
+	};
+
+	return {
+		path: filePath,
+		get(key) {
+			const validKey = validateStateKey(key);
+			const current = load();
+			return Object.hasOwn(current, validKey) ? current[validKey] : undefined;
+		},
+		set(key, value) {
+			const validKey = validateStateKey(key);
+			assertWorkflowJsonValue(value, `state.set('${validKey}') value`);
+			withStateFileLock(filePath, () => {
+				const next = Object.assign(Object.create(null) as Record<string, unknown>, readStateFile(), { [validKey]: value });
+				const bytes = Buffer.byteLength(JSON.stringify(next, null, 2));
+				if (bytes > MISSION_STATE_MAX_BYTES) throw new Error(`Mission state exceeds the 256 KiB limit (${bytes} bytes; maximum ${MISSION_STATE_MAX_BYTES} bytes).`);
+				writePrivateAtomicJson(filePath, next);
+				values = next;
+				loaded = true;
+			});
+		},
+	};
+}