@vimhead.dev/norn-cli 0.1.0-tip.0

package/assets/packages/cli/src/internal/metrics.ts

@@ -0,0 +1,356 @@
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import type { NornAgentMetrics, NornAgentUsage, NornCommandMetrics, NornRunMetrics, NornRunStatus, NornWorkflowMetrics } from "@vimhead.dev/norn";
+import { runCurrentRoot } from "./run-store.ts";
+import { RUN_STATE_FILE_NAME } from "./run-state.ts";
+import { isNodeError } from "@vimhead.dev/norn-core/errors";
+import { addAgentUsage, agentUsageFromValue, emptyAgentUsage } from "./usage.ts";
+
+const LEGACY_RUN_STATE_FILE_NAME = "runtime-state.json";
+
+type NornRunManifestEvent = Record<string, unknown> & {
+	readonly at?: string;
+	readonly type?: string;
+};
+
+type NornRunManifest = {
+	readonly events?: readonly NornRunManifestEvent[];
+};
+
+type NornRunStateSnapshot = {
+	readonly status?: NornRunStatus;
+	readonly startedAt?: string;
+	readonly updatedAt?: string;
+	readonly outcome?: { readonly completedAt?: string } | null;
+	readonly failed?: { readonly failedAt?: string } | null;
+};
+
+type OpenWorkflowMetrics = {
+	readonly workflowId: string;
+	readonly startedAt: string;
+	readonly startedAtMs: number;
+	readonly agents: readonly NornAgentMetrics[];
+	readonly commands: readonly NornCommandMetrics[];
+	readonly openAgents: readonly OpenAgentMetrics[];
+	readonly openCommands: readonly OpenCommandMetrics[];
+};
+
+type OpenAgentMetrics = {
+	readonly label: string;
+	readonly startedAt: string;
+	readonly startedAtMs: number;
+};
+
+type OpenCommandMetrics = {
+	readonly label: string;
+	readonly startedAt: string;
+	readonly startedAtMs: number;
+};
+
+export async function readRunMetrics(runRoot: string): Promise<NornRunMetrics> {
+	const currentRoot = runCurrentRoot(runRoot);
+	const [state, events] = await Promise.all([
+		readRunStateSnapshot(currentRoot),
+		readManifestEvents(join(currentRoot, "manifest.json")),
+	]);
+	return calculateRunMetrics(events, state, new Date());
+}
+
+export function calculateRunMetrics(
+	events: readonly NornRunManifestEvent[],
+	state: NornRunStateSnapshot,
+	now: Date,
+): NornRunMetrics {
+	const startedAt = state.startedAt ?? firstEventTime(events) ?? now.toISOString();
+	const endedAt = runEndedAt(state);
+	const startedAtMs = timestampMs(startedAt) ?? now.getTime();
+	const endedAtMs = timestampMs(endedAt) ?? now.getTime();
+	const workflows: NornWorkflowMetrics[] = [];
+	let openWorkflow: OpenWorkflowMetrics | undefined;
+	let gateStartedAtMs: number | undefined;
+	let gateWaitMs = 0;
+	let agentUsage = emptyAgentUsage();
+
+	for (const event of events) {
+		const eventAtMs = timestampMs(event.at);
+		if (event.type === "run.interrupted" && eventAtMs !== undefined) gateStartedAtMs = eventAtMs;
+		else if (event.type === "run.resumed" && eventAtMs !== undefined && gateStartedAtMs !== undefined) {
+			gateWaitMs += Math.max(0, eventAtMs - gateStartedAtMs);
+			gateStartedAtMs = undefined;
+		}
+
+		if (event.type === "workflow.started") {
+			openWorkflow = {
+				workflowId: stringField(event.workflowId, "unknown"),
+				startedAt: isoTime(event.at, now),
+				startedAtMs: eventAtMs ?? now.getTime(),
+				agents: [],
+				commands: [],
+				openAgents: [],
+				openCommands: [],
+			};
+			continue;
+		}
+
+		if (event.type === "agent.started") {
+			if (openWorkflow) openWorkflow = startAgentMetrics(openWorkflow, event, now);
+			continue;
+		}
+
+		if (event.type === "agent.completed" || event.type === "agent.failed") {
+			const usage = agentUsageFromEvent(event);
+			agentUsage = addAgentUsage(agentUsage, usage);
+			if (openWorkflow) openWorkflow = finishAgentMetrics(openWorkflow, event, usage, now);
+			continue;
+		}
+
+		if (event.type === "command.started") {
+			if (openWorkflow) openWorkflow = startCommandMetrics(openWorkflow, event, now);
+			continue;
+		}
+
+		if (event.type === "command.completed" || event.type === "command.failed") {
+			if (openWorkflow) openWorkflow = finishCommandMetrics(openWorkflow, event, now);
+			continue;
+		}
+
+		const status = workflowTerminalStatus(event.type);
+		if (status) {
+			const durationMs = numberField(event.durationMs) || (openWorkflow && eventAtMs !== undefined ? Math.max(0, eventAtMs - openWorkflow.startedAtMs) : 0);
+			const workflowId = status === "transitioned" ? stringField(event.fromWorkflowId, openWorkflow?.workflowId ?? "unknown") : stringField(event.workflowId, openWorkflow?.workflowId ?? "unknown");
+			const workflow = openWorkflow ?? createSyntheticWorkflowMetrics(workflowId, startedAtMs, endedAtMs, eventAtMs, durationMs);
+			const childStatus = status === "failed" ? "failed" : "completed";
+			workflows.push(closeWorkflowMetrics(closeOpenChildMetrics(workflow, eventAtMs ?? now.getTime(), event.at, childStatus), workflows.length + 1, status, durationMs, event.at));
+			openWorkflow = undefined;
+		}
+	}
+
+	if (gateStartedAtMs !== undefined) gateWaitMs += Math.max(0, endedAtMs - gateStartedAtMs);
+	if (openWorkflow) {
+		workflows.push(closeWorkflowMetrics(closeOpenChildMetrics(openWorkflow, endedAtMs, endedAt, "running"), workflows.length + 1, "running", Math.max(0, endedAtMs - openWorkflow.startedAtMs), endedAt));
+	}
+	const workflowsMs = workflows.reduce((sum, workflow) => sum + workflow.wallMs, 0);
+	const agentsMs = workflows.reduce((sum, workflow) => sum + workflow.agentsMs, 0);
+	const commandsMs = workflows.reduce((sum, workflow) => sum + workflow.commandsMs, 0);
+	const wallMs = Math.max(0, endedAtMs - startedAtMs);
+	return {
+		status: state.status ?? "running",
+		startedAt,
+		...(endedAt === undefined ? {} : { endedAt }),
+		wallMs,
+		activeMs: Math.max(0, wallMs - gateWaitMs),
+		gateWaitMs,
+		workflowsMs,
+		workflowOwnMs: Math.max(0, workflowsMs - agentsMs - commandsMs),
+		agentsMs,
+		commandsMs,
+		agentUsage,
+		workflows,
+	};
+}
+
+async function readRunStateSnapshot(currentRoot: string): Promise<NornRunStateSnapshot> {
+	try {
+		return JSON.parse(await readFile(join(currentRoot, RUN_STATE_FILE_NAME), "utf8")) as NornRunStateSnapshot;
+	} catch (error) {
+		if (!isNodeError(error) || error.code !== "ENOENT") throw error;
+		return JSON.parse(await readFile(join(currentRoot, LEGACY_RUN_STATE_FILE_NAME), "utf8")) as NornRunStateSnapshot;
+	}
+}
+
+async function readManifestEvents(path: string): Promise<readonly NornRunManifestEvent[]> {
+	const manifest = JSON.parse(await readFile(path, "utf8")) as NornRunManifest;
+	return manifest.events ?? [];
+}
+
+function createSyntheticWorkflowMetrics(workflowId: string, runStartedAtMs: number, runEndedAtMs: number, eventAtMs: number | undefined, durationMs: number): OpenWorkflowMetrics {
+	const startedAtMs = eventAtMs === undefined ? runEndedAtMs : Math.max(runStartedAtMs, eventAtMs - durationMs);
+	return {
+		workflowId,
+		startedAt: isoTimeFromMs(startedAtMs),
+		startedAtMs,
+		agents: [],
+		commands: [],
+		openAgents: [],
+		openCommands: [],
+	};
+}
+
+function startAgentMetrics(workflow: OpenWorkflowMetrics, event: NornRunManifestEvent, now: Date): OpenWorkflowMetrics {
+	return {
+		...workflow,
+		openAgents: [...workflow.openAgents, {
+			label: stringField(event.label, "unknown"),
+			startedAt: isoTime(event.at, now),
+			startedAtMs: timestampMs(event.at) ?? now.getTime(),
+		}],
+	};
+}
+
+function finishAgentMetrics(workflow: OpenWorkflowMetrics, event: NornRunManifestEvent, usage: NornAgentUsage, now: Date): OpenWorkflowMetrics {
+	const [agent, openAgents] = takeOpenChild(workflow.openAgents, stringField(event.label, "unknown"));
+	const closedAgent = closeAgentMetrics(event, workflow.agents.length + 1, usage, now, agent);
+	return { ...workflow, agents: [...workflow.agents, closedAgent], openAgents };
+}
+
+function startCommandMetrics(workflow: OpenWorkflowMetrics, event: NornRunManifestEvent, now: Date): OpenWorkflowMetrics {
+	return {
+		...workflow,
+		openCommands: [...workflow.openCommands, {
+			label: stringField(event.label, "unknown"),
+			startedAt: isoTime(event.at, now),
+			startedAtMs: timestampMs(event.at) ?? now.getTime(),
+		}],
+	};
+}
+
+function finishCommandMetrics(workflow: OpenWorkflowMetrics, event: NornRunManifestEvent, now: Date): OpenWorkflowMetrics {
+	const [command, openCommands] = takeOpenChild(workflow.openCommands, stringField(event.label, "unknown"));
+	const closedCommand = closeCommandMetrics(event, workflow.commands.length + 1, now, command);
+	return { ...workflow, commands: [...workflow.commands, closedCommand], openCommands };
+}
+
+function closeOpenChildMetrics(workflow: OpenWorkflowMetrics, endedAtMs: number, endedAt: string | undefined, status: NornAgentMetrics["status"]): OpenWorkflowMetrics {
+	return {
+		...workflow,
+		agents: [
+			...workflow.agents,
+			...workflow.openAgents.map((agent, offset): NornAgentMetrics => ({
+				index: workflow.agents.length + offset + 1,
+				label: agent.label,
+				status,
+				startedAt: agent.startedAt,
+				...(endedAt === undefined ? {} : { endedAt }),
+				wallMs: Math.max(0, endedAtMs - agent.startedAtMs),
+				usage: emptyAgentUsage(),
+			})),
+		],
+		commands: [
+			...workflow.commands,
+			...workflow.openCommands.map((command, offset): NornCommandMetrics => ({
+				index: workflow.commands.length + offset + 1,
+				label: command.label,
+				status,
+				startedAt: command.startedAt,
+				...(endedAt === undefined ? {} : { endedAt }),
+				wallMs: Math.max(0, endedAtMs - command.startedAtMs),
+			})),
+		],
+		openAgents: [],
+		openCommands: [],
+	};
+}
+
+function closeWorkflowMetrics(
+	workflow: OpenWorkflowMetrics,
+	index: number,
+	status: NornWorkflowMetrics["status"],
+	wallMs: number,
+	endedAt: string | undefined,
+): NornWorkflowMetrics {
+	const agentsMs = workflow.agents.reduce((sum, agent) => sum + agent.wallMs, 0);
+	const commandsMs = workflow.commands.reduce((sum, command) => sum + command.wallMs, 0);
+	return {
+		index,
+		workflowId: workflow.workflowId,
+		status,
+		startedAt: workflow.startedAt,
+		...(endedAt === undefined ? {} : { endedAt }),
+		wallMs,
+		ownMs: Math.max(0, wallMs - agentsMs - commandsMs),
+		agentsMs,
+		commandsMs,
+		agentUsage: workflow.agents.reduce((sum, agent) => addAgentUsage(sum, agent.usage), emptyAgentUsage()),
+		agents: workflow.agents,
+		commands: workflow.commands,
+	};
+}
+
+function closeAgentMetrics(event: NornRunManifestEvent, index: number, usage: NornAgentUsage, now: Date, openAgent: OpenAgentMetrics | undefined): NornAgentMetrics {
+	const endedAtMs = timestampMs(event.at) ?? now.getTime();
+	const wallMs = numberField(event.durationMs) || (openAgent ? Math.max(0, endedAtMs - openAgent.startedAtMs) : 0);
+	return {
+		index,
+		label: stringField(event.label, openAgent?.label ?? "unknown"),
+		status: event.type === "agent.failed" ? "failed" : "completed",
+		startedAt: openAgent?.startedAt ?? isoTimeFromMs(Math.max(0, endedAtMs - wallMs)),
+		endedAt: isoTime(event.at, now),
+		wallMs,
+		attempts: optionalNumberField(event.attempts),
+		usage,
+	};
+}
+
+function closeCommandMetrics(event: NornRunManifestEvent, index: number, now: Date, openCommand: OpenCommandMetrics | undefined): NornCommandMetrics {
+	const endedAtMs = timestampMs(event.at) ?? now.getTime();
+	const wallMs = numberField(event.durationMs) || (openCommand ? Math.max(0, endedAtMs - openCommand.startedAtMs) : 0);
+	return {
+		index,
+		label: stringField(event.label, openCommand?.label ?? "unknown"),
+		status: event.type === "command.failed" ? "failed" : "completed",
+		startedAt: openCommand?.startedAt ?? isoTimeFromMs(Math.max(0, endedAtMs - wallMs)),
+		endedAt: isoTime(event.at, now),
+		wallMs,
+		...(event.type === "command.completed" ? { exitCode: nullableNumberField(event.exitCode), killed: booleanField(event.killed) } : {}),
+	};
+}
+
+function takeOpenChild<T extends { readonly label: string }>(children: readonly T[], label: string): readonly [T | undefined, readonly T[]] {
+	const index = children.findIndex((child) => child.label === label);
+	if (index === -1) return [undefined, children];
+	return [children[index], [...children.slice(0, index), ...children.slice(index + 1)]];
+}
+
+function workflowTerminalStatus(type: unknown): NornWorkflowMetrics["status"] | undefined {
+	if (type === "workflow.completed") return "completed";
+	if (type === "workflow.failed") return "failed";
+	if (type === "workflow.transitioned") return "transitioned";
+	return undefined;
+}
+
+function runEndedAt(state: NornRunStateSnapshot): string | undefined {
+	if (state.status === "completed") return state.outcome?.completedAt ?? state.updatedAt;
+	if (state.status === "failed") return state.failed?.failedAt ?? state.outcome?.completedAt ?? state.updatedAt;
+	return undefined;
+}
+
+function agentUsageFromEvent(event: NornRunManifestEvent): NornAgentUsage {
+	return agentUsageFromValue(event.usage) ?? emptyAgentUsage();
+}
+
+function firstEventTime(events: readonly NornRunManifestEvent[]): string | undefined {
+	return events.find((event) => timestampMs(event.at) !== undefined)?.at;
+}
+
+function timestampMs(value: string | undefined): number | undefined {
+	const parsed = value ? Date.parse(value) : NaN;
+	return Number.isFinite(parsed) ? parsed : undefined;
+}
+
+function isoTime(value: string | undefined, now: Date): string {
+	return value && timestampMs(value) !== undefined ? value : now.toISOString();
+}
+
+function isoTimeFromMs(value: number): string {
+	return new Date(value).toISOString();
+}
+
+function numberField(value: unknown): number {
+	return typeof value === "number" && Number.isFinite(value) ? value : 0;
+}
+
+function optionalNumberField(value: unknown): number | undefined {
+	return typeof value === "number" && Number.isFinite(value) ? value : undefined;
+}
+
+function nullableNumberField(value: unknown): number | null {
+	return typeof value === "number" && Number.isFinite(value) ? value : null;
+}
+
+function booleanField(value: unknown): boolean {
+	return typeof value === "boolean" ? value : false;
+}
+
+function stringField(value: unknown, fallback: string): string {
+	return typeof value === "string" && value.length > 0 ? value : fallback;
+}

package/assets/packages/cli/src/internal/pi-assets.ts

@@ -0,0 +1,95 @@
+import { createHash } from "node:crypto";
+import { lstat, mkdir, mkdtemp, readFile, readdir, rename, rm, writeFile } from "node:fs/promises";
+import { join, resolve } from "node:path";
+import { gunzipSync } from "node:zlib";
+import { isNodeError } from "@vimhead.dev/norn-core/errors";
+
+export type PiAssetFile = { readonly path: string; readonly content: string };
+
+export function resolvePiAssetsCacheRoot(input: {
+	readonly platform: string;
+	readonly home: string;
+	readonly environment: Readonly<Record<string, string | undefined>>;
+}): string {
+	if (input.environment.NORN_PI_CACHE_DIR) return resolve(input.environment.NORN_PI_CACHE_DIR);
+	if (input.platform === "darwin") return join(input.home, "Library", "Caches", "norn", "pi");
+	if (input.platform === "win32") return join(input.environment.LOCALAPPDATA || join(input.home, "AppData", "Local"), "norn", "pi");
+	const xdgCache = input.environment.XDG_CACHE_HOME;
+	return join(xdgCache?.startsWith("/") ? xdgCache : join(input.home, ".cache"), "norn", "pi");
+}
+
+export async function materializePiAssets(input: { readonly archive: string; readonly cacheRoot: string }): Promise<string> {
+	const digest = createHash("sha256").update(input.archive).digest("hex");
+	const files: PiAssetFile[] = JSON.parse(gunzipSync(Buffer.from(input.archive, "base64")).toString("utf8"));
+	const expectedFiles = new Map<string, Buffer>();
+	for (const file of files) {
+		if (!file.path || file.path.includes("\\") || file.path.includes(":") || file.path.split("/").some(part => !part || part === "." || part === "..") || expectedFiles.has(file.path)) {
+			throw new Error("Invalid bundled Pi asset path");
+		}
+		expectedFiles.set(file.path, Buffer.from(file.content, "base64"));
+	}
+	return new PiAssetCache({ cacheRoot: input.cacheRoot, digest, expectedFiles }).materialize();
+}
+
+class PiAssetCache {
+	private readonly root: string;
+
+	constructor(private readonly input: { readonly cacheRoot: string; readonly digest: string; readonly expectedFiles: ReadonlyMap<string, Buffer> }) {
+		this.root = join(input.cacheRoot, `v1-${input.digest}`);
+	}
+
+	async materialize(): Promise<string> {
+		await mkdir(this.input.cacheRoot, { recursive: true, mode: 0o700 });
+		if (!(await lstat(this.input.cacheRoot)).isDirectory()) throw new Error("Pi asset cache root must be a real directory");
+		if (await this.validateExistingCache()) return this.root;
+		const staging = await mkdtemp(join(this.input.cacheRoot, ".extract-"));
+		try {
+			for (const [path, content] of this.input.expectedFiles) {
+				const parts = path.split("/");
+				await mkdir(join(staging, ...parts.slice(0, -1)), { recursive: true, mode: 0o700 });
+				await writeFile(join(staging, ...parts), content, { flag: "wx", mode: 0o600 });
+			}
+			try {
+				await rename(staging, this.root);
+			} catch (error) {
+				if (!isNodeError(error) || !["EEXIST", "ENOTEMPTY", "EPERM", "EACCES"].includes(error.code ?? "") || !await this.validateExistingCache()) throw error;
+			}
+			if (!await this.validateExistingCache()) throw new Error("Pi assets disappeared after extraction");
+			return this.root;
+		} finally {
+			await rm(staging, { recursive: true, force: true });
+		}
+	}
+
+	private async validateExistingCache(): Promise<boolean> {
+		try {
+			if (!(await lstat(this.root)).isDirectory()) throw this.invalidCacheError();
+		} catch (error) {
+			if (isNodeError(error) && error.code === "ENOENT") return false;
+			throw error;
+		}
+		const seen = new Set<string>();
+		await this.validateDirectory({ directory: this.root, prefix: "", seen });
+		if (seen.size !== this.input.expectedFiles.size) throw this.invalidCacheError();
+		return true;
+	}
+
+	private async validateDirectory(input: { readonly directory: string; readonly prefix: string; readonly seen: Set<string> }): Promise<void> {
+		for (const entry of await readdir(input.directory, { withFileTypes: true })) {
+			const path = input.prefix ? `${input.prefix}/${entry.name}` : entry.name;
+			const absolutePath = join(input.directory, entry.name);
+			if (entry.isDirectory()) {
+				if (![...this.input.expectedFiles.keys()].some(file => file.startsWith(`${path}/`))) throw this.invalidCacheError();
+				await this.validateDirectory({ directory: absolutePath, prefix: path, seen: input.seen });
+			} else {
+				const expected = this.input.expectedFiles.get(path);
+				if (!entry.isFile() || !expected || !(await readFile(absolutePath)).equals(expected)) throw this.invalidCacheError();
+				input.seen.add(path);
+			}
+		}
+	}
+
+	private invalidCacheError(): Error {
+		return new Error(`Bundled Pi assets are incomplete or modified: ${this.root}. Remove this cache entry and retry.`);
+	}
+}

package/assets/packages/cli/src/internal/resource-bindings.ts

@@ -0,0 +1,35 @@
+import type { ToolDefinition } from "@earendil-works/pi-coding-agent";
+import type { NornAgentResourceBinding, NornAgentResourceAdapter } from "@vimhead.dev/norn";
+
+export class NornSessionResourceBindings {
+	readonly tools: ToolDefinition[] = [];
+	private readonly bindings: NornAgentResourceBinding[] = [];
+
+	async bind(input: { readonly adapters: readonly NornAgentResourceAdapter[]; readonly runId: string; readonly label: string; readonly reservedTools: readonly string[] }): Promise<void> {
+		const adapterNames = new Set<string>();
+		const tools = new Set(input.reservedTools);
+		for (const adapter of input.adapters) {
+			if (adapterNames.has(adapter.name)) throw new Error(`Duplicate resource adapter: ${adapter.name}`);
+			adapterNames.add(adapter.name);
+			const binding = await adapter.bind({ runId: input.runId, label: input.label });
+			this.bindings.push(binding);
+			for (const tool of binding.tools) {
+				if (tools.has(tool.name)) throw new Error(`Resource tool name collision: ${tool.name}`);
+				tools.add(tool.name);
+				this.tools.push(tool);
+			}
+		}
+	}
+
+	async dispose(): Promise<void> {
+		const errors: unknown[] = [];
+		for (const binding of this.bindings.splice(0).reverse()) {
+			try {
+				await binding.dispose();
+			} catch (error) {
+				errors.push(error);
+			}
+		}
+		if (errors.length) throw new AggregateError(errors, "Resource binding cleanup failed");
+	}
+}

package/assets/packages/cli/src/internal/run-lease.ts

@@ -0,0 +1,158 @@
+import { randomUUID } from "node:crypto";
+import { mkdir, readFile, rm, stat } from "node:fs/promises";
+import { join } from "node:path";
+import type { NornRunHealth } from "@vimhead.dev/norn";
+import { isNodeError } from "@vimhead.dev/norn-core/errors";
+import { writeJsonAtomically } from "@vimhead.dev/norn-core/atomic-files";
+
+const LOCK_DIR_NAME = "active.lock";
+const OWNER_FILE_NAME = "owner.json";
+const HEARTBEAT_INTERVAL_MS = 15_000;
+const HEARTBEAT_TTL_MS = 60_000;
+const ACQUIRE_ATTEMPTS = 5;
+
+export type NornRunLeaseOwner = {
+	readonly token: string;
+	readonly acquiredAt: string;
+	readonly heartbeatAt: string;
+	readonly pid: number;
+	readonly processGroupId: number;
+	readonly command: readonly string[];
+};
+
+export class NornRunLease {
+	private heartbeat: ReturnType<typeof setInterval> | undefined;
+	private heartbeatChain: Promise<void> = Promise.resolve();
+	private isReleased = false;
+
+	private constructor(
+		private readonly lockRoot: string,
+		private readonly token: string,
+		private readonly processOwner: NornRunProcessOwner,
+	) {}
+
+	static async acquire(runRoot: string, processOwner: NornRunProcessOwner = currentRunProcessOwner()): Promise<NornRunLease> {
+		const lockRoot = join(runRoot, LOCK_DIR_NAME);
+		for (let attempt = 1; attempt <= ACQUIRE_ATTEMPTS; attempt++) {
+			try {
+				await mkdir(lockRoot);
+				const lease = new NornRunLease(lockRoot, randomUUID(), processOwner);
+				try {
+					await lease.writeOwner({ acquiredAt: new Date().toISOString() });
+				} catch (error) {
+					await rm(lockRoot, { recursive: true, force: true });
+					throw error;
+				}
+				lease.startHeartbeat();
+				return lease;
+			} catch (error) {
+				if (!isNodeError(error) || error.code !== "EEXIST") throw error;
+				const owner = await readRunLeaseOwner(join(lockRoot, OWNER_FILE_NAME));
+				const isStale = owner ? isRunLeaseStale(owner) : await isRunLeaseDirectoryStale(lockRoot);
+				if (!isStale) throw new Error(`Run is already active: ${runRoot}`);
+				await rm(lockRoot, { recursive: true, force: true });
+			}
+		}
+		throw new Error(`Could not acquire run lease: ${runRoot}`);
+	}
+
+	async assertOwned(): Promise<void> {
+		if (this.isReleased) throw new Error("Run lease has been released");
+		const owner = await readRunLeaseOwner(this.ownerPath);
+		if (!owner || owner.token !== this.token) throw new Error("Run lease was lost");
+	}
+
+	async release(): Promise<void> {
+		if (this.isReleased) return;
+		this.isReleased = true;
+		if (this.heartbeat) clearInterval(this.heartbeat);
+		await this.heartbeatChain.catch(() => undefined);
+		const owner = await readRunLeaseOwner(this.ownerPath);
+		if (owner?.token === this.token) await rm(this.lockRoot, { recursive: true, force: true });
+	}
+
+	private get ownerPath(): string {
+		return join(this.lockRoot, OWNER_FILE_NAME);
+	}
+
+	private startHeartbeat(): void {
+		this.heartbeat = setInterval(() => {
+			this.heartbeatChain = this.heartbeatChain.then(() => this.refreshHeartbeat()).catch(() => {
+				this.isReleased = true;
+				if (this.heartbeat) clearInterval(this.heartbeat);
+			});
+		}, HEARTBEAT_INTERVAL_MS);
+		this.heartbeat.unref?.();
+	}
+
+	private async refreshHeartbeat(): Promise<void> {
+		if (this.isReleased) return;
+		const owner = await readRunLeaseOwner(this.ownerPath);
+		if (!owner || owner.token !== this.token) throw new Error("Run lease was lost");
+		await this.writeOwner({ acquiredAt: owner.acquiredAt });
+	}
+
+	private async writeOwner(input: { readonly acquiredAt: string }): Promise<void> {
+		const now = new Date().toISOString();
+		await writeJsonAtomically(this.ownerPath, { token: this.token, acquiredAt: input.acquiredAt, heartbeatAt: now, ...this.processOwner });
+	}
+}
+
+export type NornRunProcessOwner = {
+	readonly pid: number;
+	readonly processGroupId: number;
+	readonly command: readonly string[];
+};
+
+export async function getRunLeaseHealth(runRoot: string): Promise<NornRunHealth> {
+	const lockRoot = join(runRoot, LOCK_DIR_NAME);
+	const owner = await readRunLeaseOwner(join(lockRoot, OWNER_FILE_NAME));
+	if (owner) return isRunLeaseStale(owner) ? "unhealthy" : "healthy";
+	return await isRunLeaseDirectoryStale(lockRoot) ? "unhealthy" : "healthy";
+}
+
+export async function getRunLeaseOwner(runRoot: string): Promise<NornRunLeaseOwner | undefined> {
+	return readRunLeaseOwner(join(runRoot, LOCK_DIR_NAME, OWNER_FILE_NAME));
+}
+
+function currentRunProcessOwner(): NornRunProcessOwner {
+	return {
+		pid: process.pid,
+		processGroupId: process.pid,
+		command: process.argv,
+	};
+}
+
+async function readRunLeaseOwner(path: string): Promise<NornRunLeaseOwner | undefined> {
+	try {
+		return parseRunLeaseOwner(JSON.parse(await readFile(path, "utf8")));
+	} catch (error) {
+		if (isNodeError(error) && error.code === "ENOENT") return undefined;
+		return undefined;
+	}
+}
+
+function parseRunLeaseOwner(value: unknown): NornRunLeaseOwner | undefined {
+	if (!value || typeof value !== "object") return undefined;
+	const owner = value as Partial<NornRunLeaseOwner>;
+	if (typeof owner.token !== "string" || owner.token.length === 0) return undefined;
+	if (typeof owner.acquiredAt !== "string" || Number.isNaN(Date.parse(owner.acquiredAt))) return undefined;
+	if (typeof owner.heartbeatAt !== "string" || Number.isNaN(Date.parse(owner.heartbeatAt))) return undefined;
+	const pid = typeof owner.pid === "number" && Number.isInteger(owner.pid) ? owner.pid : 0;
+	const processGroupId = typeof owner.processGroupId === "number" && Number.isInteger(owner.processGroupId) ? owner.processGroupId : pid;
+	const command = Array.isArray(owner.command) ? owner.command.filter((value): value is string => typeof value === "string") : [];
+	return { token: owner.token, acquiredAt: owner.acquiredAt, heartbeatAt: owner.heartbeatAt, pid, processGroupId, command };
+}
+
+function isRunLeaseStale(owner: NornRunLeaseOwner): boolean {
+	return Date.now() - Date.parse(owner.heartbeatAt) > HEARTBEAT_TTL_MS;
+}
+
+async function isRunLeaseDirectoryStale(lockRoot: string): Promise<boolean> {
+	try {
+		return Date.now() - (await stat(lockRoot)).mtimeMs > HEARTBEAT_TTL_MS;
+	} catch (error) {
+		if (isNodeError(error) && error.code === "ENOENT") return true;
+		throw error;
+	}
+}