@bastani/atomic 0.9.5-alpha.9 → 0.9.5

package/dist/builtin/subagents/src/runs/background/completion-dedupe.ts

@@ -1,4 +1,13 @@
+export interface CompletionSeenRecord {
+	seenAt: number;
+	signature?: string;
+}
+
+export type CompletionSeenMap = Map<string, number | CompletionSeenRecord>;
+export type CompletionSeenMatch = "miss" | "match" | "conflict";
+
 interface CompletionDataLike {
+	runId?: unknown;
 	id?: unknown;
 	agent?: unknown;
 	timestamp?: unknown;
@@ -20,6 +29,8 @@ function asFiniteNumber(value: unknown): number | undefined {
 }
 
 export function buildCompletionKey(data: CompletionDataLike, fallback: string): string {
+	const runId = asNonEmptyString(data.runId);
+	if (runId) return `run:${runId}`;
 	const id = asNonEmptyString(data.id);
 	if (id) return `id:${id}`;
 	const sessionId = asNonEmptyString(data.sessionId) ?? "no-session";
@@ -40,24 +51,50 @@ export function buildCompletionKey(data: CompletionDataLike, fallback: string):
 	].join(":");
 }
 
-function pruneSeenMap(seen: Map<string, number>, now: number, ttlMs: number): void {
-	for (const [key, ts] of seen.entries()) {
-		if (now - ts > ttlMs) seen.delete(key);
+function recordTimestamp(record: number | CompletionSeenRecord): number {
+	return typeof record === "number" ? record : record.seenAt;
+}
+
+function pruneSeenMap(seen: CompletionSeenMap, now: number, ttlMs: number): void {
+	for (const [key, record] of seen.entries()) {
+		if (now - recordTimestamp(record) > ttlMs) seen.delete(key);
 	}
 }
 
-export function markSeenWithTtl(seen: Map<string, number>, key: string, now: number, ttlMs: number): boolean {
+export function lookupSeenWithTtl(
+	seen: CompletionSeenMap,
+	key: string,
+	signature: string | undefined,
+	now: number,
+	ttlMs: number,
+): CompletionSeenMatch {
+	pruneSeenMap(seen, now, ttlMs);
+	const record = seen.get(key);
+	if (record === undefined) return "miss";
+	const recordedSignature = typeof record === "number" ? undefined : record.signature;
+	return recordedSignature === undefined || signature === undefined || recordedSignature === signature ? "match" : "conflict";
+}
+
+export function hasSeenWithTtl(seen: CompletionSeenMap, key: string, now: number, ttlMs: number): boolean {
+	return lookupSeenWithTtl(seen, key, undefined, now, ttlMs) !== "miss";
+}
+
+export function recordSeen(seen: CompletionSeenMap, key: string, now: number, signature?: string): void {
+	seen.set(key, signature === undefined ? now : { seenAt: now, signature });
+}
+
+export function markSeenWithTtl(seen: CompletionSeenMap, key: string, now: number, ttlMs: number): boolean {
 	pruneSeenMap(seen, now, ttlMs);
 	if (seen.has(key)) return true;
 	seen.set(key, now);
 	return false;
 }
 
-export function getGlobalSeenMap(storeKey: string): Map<string, number> {
+export function getGlobalSeenMap(storeKey: string): CompletionSeenMap {
 	const globalStore = globalThis as Record<string, unknown>;
 	const existing = globalStore[storeKey];
-	if (existing instanceof Map) return existing as Map<string, number>;
-	const map = new Map<string, number>();
+	if (existing instanceof Map) return existing as CompletionSeenMap;
+	const map: CompletionSeenMap = new Map();
 	globalStore[storeKey] = map;
 	return map;
 }

package/dist/builtin/subagents/src/runs/background/completion-notification.ts

@@ -0,0 +1,34 @@
+import type { IntercomEventBus } from "../../shared/types.ts";
+import { SUBAGENT_ASYNC_COMPLETE_EVENT } from "../../shared/types.ts";
+
+export interface CompletionNotificationEnvelope extends Record<string, unknown> {
+	notificationId: string;
+	acknowledge: (delivered: boolean) => void;
+}
+
+export function deliverLocalCompletionNotification(
+	events: IntercomEventBus,
+	payload: Record<string, unknown>,
+	notificationId: string,
+): Promise<boolean> {
+	return new Promise((resolve) => {
+		let settled = false;
+		const finish = (delivered: boolean) => {
+			if (settled) return;
+			settled = true;
+			resolve(delivered);
+		};
+		try {
+			events.emit(SUBAGENT_ASYNC_COMPLETE_EVENT, {
+				...payload,
+				notificationId,
+				acknowledge: finish,
+			} satisfies CompletionNotificationEnvelope);
+			// The established event contract treats successful synchronous emission as
+			// delivery. Production listeners can synchronously reject via acknowledge(false).
+			finish(true);
+		} catch {
+			finish(false);
+		}
+	});
+}

package/dist/builtin/subagents/src/runs/background/notify.ts

@@ -3,7 +3,8 @@
  */
 
 import type { ExtensionAPI } from "@bastani/atomic";
-import { buildCompletionKey, getGlobalSeenMap, markSeenWithTtl } from "./completion-dedupe.ts";
+import { buildCompletionKey, hasSeenWithTtl, recordSeen } from "./completion-dedupe.ts";
+import type { CompletionNotificationEnvelope } from "./completion-notification.ts";
 import { SUBAGENT_ASYNC_COMPLETE_EVENT } from "../../shared/types.ts";
 
 interface ChainStepResult {
@@ -40,27 +41,62 @@ interface SubagentResult {
 	totalTasks?: number;
 }
 
-export default function registerSubagentNotify(pi: ExtensionAPI): void {
-	const unsubscribeStoreKey = "__pi_subagents_notify_unsubscribe__";
-	const globalStore = globalThis as Record<string, unknown>;
-	const previousUnsubscribe = globalStore[unsubscribeStoreKey];
-	if (typeof previousUnsubscribe === "function") {
+interface NotifyRegistration {
+	unsubscribe: () => void;
+}
+
+function getNotifyRegistry(): WeakMap<ExtensionAPI, NotifyRegistration> {
+	const key = "__piSubagentsNotifyRegistrations";
+	const store = globalThis as Record<string, unknown>;
+	const existing = store[key];
+	if (existing instanceof WeakMap) return existing as WeakMap<ExtensionAPI, NotifyRegistration>;
+	const registry = new WeakMap<ExtensionAPI, NotifyRegistration>();
+	store[key] = registry;
+	return registry;
+}
+
+function getNotifySeenRegistry(): WeakMap<ExtensionAPI, Map<string, number>> {
+	const key = "__piSubagentsNotifySeenByApi";
+	const store = globalThis as Record<string, unknown>;
+	const existing = store[key];
+	if (existing instanceof WeakMap) return existing as WeakMap<ExtensionAPI, Map<string, number>>;
+	const registry = new WeakMap<ExtensionAPI, Map<string, number>>();
+	store[key] = registry;
+	return registry;
+}
+
+function getNotifySeen(pi: ExtensionAPI): Map<string, number> {
+	const registry = getNotifySeenRegistry();
+	const existing = registry.get(pi);
+	if (existing) return existing;
+	const seen = new Map<string, number>();
+	registry.set(pi, seen);
+	return seen;
+}
+
+export default function registerSubagentNotify(pi: ExtensionAPI): () => void {
+	const registry = getNotifyRegistry();
+	const previous = registry.get(pi);
+	if (previous) {
 		try {
-			previousUnsubscribe();
+			previous.unsubscribe();
 		} catch {
 			// Best effort cleanup for stale handlers from an older reload.
 		}
 	}
-
-	const seen = getGlobalSeenMap("__pi_subagents_notify_seen__");
+	const seen = getNotifySeen(pi);
 	const ttlMs = 10 * 60 * 1000;
 
+	let registration: NotifyRegistration;
 	const handleComplete = (data: unknown) => {
-		const result = data as SubagentResult;
+		if (registry.get(pi) !== registration) return;
+		const result = data as SubagentResult & Partial<CompletionNotificationEnvelope>;
 		const now = Date.now();
-		const key = buildCompletionKey(result, "notify");
-		if (markSeenWithTtl(seen, key, now, ttlMs)) return;
-
+		const key = result.notificationId ? `notification:${result.notificationId}` : buildCompletionKey(result, "notify");
+		if (hasSeenWithTtl(seen, key, now, ttlMs)) {
+			result.acknowledge?.(true);
+			return;
+		}
 		const agent = result.agent ?? "unknown";
 		const summary = typeof result.summary === "string" ? result.summary : "";
 		const paused = !result.success && (
@@ -94,15 +130,29 @@ export default function registerSubagentNotify(pi: ExtensionAPI): void {
 			.filter((line) => line !== undefined)
 			.join("\n");
 
-		pi.sendMessage(
-			{
-				customType: "subagent-notify",
-				content,
-				display: true,
-			},
-			{ triggerTurn: true },
-		);
+		try {
+			pi.sendMessage(
+				{
+					customType: "subagent-notify",
+					content,
+					display: true,
+				},
+				{ triggerTurn: true },
+			);
+			recordSeen(seen, key, Date.now());
+			result.acknowledge?.(true);
+		} catch (error) {
+			result.acknowledge?.(false);
+			console.error("Failed to deliver async subagent completion notification:", error);
+		}
 	};
 
-	globalStore[unsubscribeStoreKey] = pi.events.on(SUBAGENT_ASYNC_COMPLETE_EVENT, handleComplete);
+	const unsubscribe = pi.events.on(SUBAGENT_ASYNC_COMPLETE_EVENT, handleComplete);
+	registration = { unsubscribe };
+	registry.set(pi, registration);
+	return () => {
+		if (registry.get(pi) !== registration) return;
+		registry.delete(pi);
+		unsubscribe();
+	};
 }

package/dist/builtin/subagents/src/runs/background/result-delivery-processor.ts

@@ -0,0 +1,232 @@
+import * as fs from "node:fs";
+import { createHash } from "node:crypto";
+import * as path from "node:path";
+import { buildCompletionKey, lookupSeenWithTtl, recordSeen } from "./completion-dedupe.js";
+import { deliverClaimedCompletion, type CompletionClaimSnapshot } from "./completion-claims.js";
+import { deliverLocalCompletionNotification } from "./completion-notification.js";
+import { quarantineResultFile } from "./result-quarantine.js";
+import {
+	claimIdFromScheduleKey,
+	claimPublicResult,
+	claimScheduleKey,
+	loadResultClaim,
+	readClaimData,
+	removeResultClaim,
+	updateResultClaim,
+	type FrozenCompletionEnvelope,
+	type ResultClaimFs,
+	type ResultFileClaim,
+} from "./result-file-claims.js";
+import { modernResultHasTerminalStatus, type ResultStatusFs } from "./result-status.js";
+import {
+	attachNestedChildrenToResultChildren,
+	buildSubagentResultIntercomPayload,
+	compactNestedResultChildren,
+	deliverSubagentResultIntercomEvent,
+	resolveSubagentResultStatus,
+} from "../../intercom/result-intercom.js";
+import { projectNestedRegistryForRoot } from "../shared/nested-events.js";
+import { buildCompletionSignature, sanitizeNestedResultChildren, type ResultFileData } from "./result-watcher-data.js";
+import type { IntercomEventBus, SubagentResultIntercomChild, SubagentState } from "../../shared/types.js";
+
+export interface ResultProcessOutcome {
+	status: "done" | "status-pending" | "delivery-retry" | "inactive";
+	entry?: string;
+}
+
+export interface ResultProcessorFs extends ResultClaimFs, Partial<ResultStatusFs> {
+	existsSync?: typeof fs.existsSync;
+	unlinkSync?: typeof fs.unlinkSync;
+	linkSync?: typeof fs.linkSync;
+	copyFileSync?: typeof fs.copyFileSync;
+	openSync?: typeof fs.openSync;
+	readSync?: typeof fs.readSync;
+	closeSync?: typeof fs.closeSync;
+}
+
+export interface ResultProcessorContext {
+	pi: { events: IntercomEventBus };
+	state: SubagentState;
+	resultsDir: string;
+	completionTtlMs: number;
+	fsApi?: ResultProcessorFs;
+	allowedStatusRoots?: string[];
+	maxStatusBytes?: number;
+	maxNoProgressFailures?: number;
+	intercomTimeoutMs?: number | false;
+	isActive: () => boolean;
+	ownsResult: (data: ResultFileData) => boolean;
+}
+
+function statusFs(fsApi: ResultProcessorFs): ResultStatusFs {
+	return {
+		realpathSync: fsApi.realpathSync ?? fs.realpathSync,
+		lstatSync: fsApi.lstatSync ?? fs.lstatSync,
+		openSync: fsApi.openSync ?? fs.openSync,
+		fstatSync: fsApi.fstatSync ?? fs.fstatSync,
+		readSync: fsApi.readSync ?? fs.readSync,
+		closeSync: fsApi.closeSync ?? fs.closeSync,
+	};
+}
+
+function readPublic(resultsDir: string, file: string, fsApi: ResultProcessorFs): ResultFileData {
+	return JSON.parse((fsApi.readFileSync ?? fs.readFileSync)(path.join(resultsDir, file), "utf-8")) as ResultFileData;
+}
+
+function markClaimState(claim: ResultFileClaim, value: CompletionClaimSnapshot, fsApi: ResultProcessorFs): void {
+	updateResultClaim(claim, {
+		intercomDelivered: value.intercomDelivered,
+		localDelivered: value.localDelivered,
+		noProgressFailures: value.noProgressFailures,
+		envelope: value.envelope,
+		...(value.terminalStatus === "delivered" ? { state: "delivered" as const } : {}),
+		...(value.terminalStatus === "exhausted" ? { state: "undelivered" as const } : {}),
+	}, fsApi);
+}
+
+function buildEnvelope(data: ResultFileData, resultPath: string, fsApi: ResultProcessorFs): FrozenCompletionEnvelope {
+	const runId = data.runId ?? data.id ?? path.basename(resultPath, ".json");
+	const explicitNested = data.nestedChildren !== undefined;
+	let nestedChildren = compactNestedResultChildren(sanitizeNestedResultChildren(data.nestedChildren, resultPath, "nestedChildren"));
+	if (!nestedChildren?.length && !explicitNested) nestedChildren = compactNestedResultChildren(projectNestedRegistryForRoot(runId)?.children);
+	const hasResults = Array.isArray(data.results) && data.results.length > 0;
+	const resultChildren = hasResults ? data.results! : [{ agent: data.agent, output: data.summary, success: data.success }];
+	const normalized = attachNestedChildrenToResultChildren(runId, resultChildren.map((result = {}, index): SubagentResultIntercomChild => {
+		const baseOutput = result.output ?? data.summary;
+		const hasOutput = typeof baseOutput === "string" && baseOutput.trim().length > 0;
+		const output = hasOutput ? baseOutput : "(no output)";
+		const summary = result.success === false && result.error
+			? `${result.error}${hasOutput ? `\n\nOutput:\n${baseOutput}` : ""}`
+			: output;
+		const sessionPath = result.sessionFile ?? (resultChildren.length === 1 ? data.sessionFile : undefined);
+		const children = sanitizeNestedResultChildren(result.children, resultPath, `results[${index}].children`);
+		return {
+			agent: result.agent ?? data.agent ?? `step-${index + 1}`,
+			status: resolveSubagentResultStatus({
+				success: result.success,
+				state: data.state === "paused" || typeof result.success !== "boolean" ? data.state : undefined,
+			}),
+			summary,
+			index,
+			artifactPath: result.artifactPaths?.outputPath,
+			...(typeof sessionPath === "string" && (fsApi.existsSync ?? fs.existsSync)(sessionPath) ? { sessionPath } : {}),
+			...(result.intercomTarget ? { intercomTarget: result.intercomTarget } : {}),
+			...(children ? { children } : {}),
+		};
+	}), nestedChildren);
+	const local: Record<string, unknown> = {
+		...data,
+		runId,
+		...(nestedChildren?.length ? { nestedChildren } : {}),
+		...(Array.isArray(data.results) ? {
+			results: hasResults ? normalized.map((child, index) => ({
+				...data.results![index], agent: child.agent, status: child.status, summary: child.summary,
+				index: child.index, artifactPath: child.artifactPath, sessionPath: child.sessionPath, children: child.children,
+			})) : [],
+		} : {}),
+	};
+	const target = data.intercomTarget?.trim();
+	const mode = data.mode === "single" || data.mode === "parallel" || data.mode === "chain"
+		? data.mode : resultChildren.length > 1 ? "chain" : "single";
+	return {
+		local,
+		...(target ? { intercom: { to: target, runId, mode, source: "async", children: normalized, asyncId: data.id, asyncDir: data.asyncDir } } : {}),
+	};
+}
+
+function quarantineClaim(context: ResultProcessorContext, claim: ResultFileClaim): void {
+	const fsApi = context.fsApi ?? fs;
+	updateResultClaim(claim, { state: "undelivered" }, fsApi);
+	quarantineResultFile(context.resultsDir, claim.meta.originalFile, claim.payloadPath, fsApi as typeof fs);
+	removeResultClaim(claim, fsApi);
+}
+
+export async function processResultEntry(entry: string, context: ResultProcessorContext): Promise<ResultProcessOutcome> {
+	const fsApi = context.fsApi ?? fs;
+	let claim: ResultFileClaim | undefined;
+	const existingClaimId = claimIdFromScheduleKey(entry);
+	if (existingClaimId) {
+		claim = loadResultClaim(context.resultsDir, existingClaimId, fsApi);
+		if (!claim) return { status: "done" };
+		if (claim.meta.state === "delivered") { removeResultClaim(claim, fsApi); return { status: "done" }; }
+		if (claim.meta.state === "undelivered") { quarantineClaim(context, claim); return { status: "done" }; }
+	} else {
+		const publicPath = path.join(context.resultsDir, entry);
+		if (!(fsApi.existsSync ?? fs.existsSync)(publicPath)) return { status: "done" };
+		const preliminary = readPublic(context.resultsDir, entry, fsApi);
+		if (!context.ownsResult(preliminary)) return { status: "inactive" };
+		if (!modernResultHasTerminalStatus(preliminary, statusFs(fsApi), {
+			allowedRoots: context.allowedStatusRoots,
+			maxBytes: context.maxStatusBytes,
+		})) return { status: "status-pending", entry };
+		claim = claimPublicResult(context.resultsDir, entry, fsApi);
+	}
+
+	const { data } = readClaimData(claim, fsApi);
+	if (!context.ownsResult(data)) return { status: "inactive" };
+	if (!modernResultHasTerminalStatus(data, statusFs(fsApi), {
+		allowedRoots: context.allowedStatusRoots,
+		maxBytes: context.maxStatusBytes,
+	})) return { status: "status-pending", entry: claim ? claimScheduleKey(claim.id) : entry };
+	const sourceSignature = buildCompletionSignature({ source: data });
+	if (claim.meta.sourceSignature && claim.meta.sourceSignature !== sourceSignature) {
+		quarantineClaim(context, claim);
+		return { status: "done" };
+	}
+	let envelope = claim.meta.envelope;
+	if (!envelope) {
+		envelope = buildEnvelope(data, claim.payloadPath, fsApi);
+		updateResultClaim(claim, { sourceSignature, envelope }, fsApi);
+	}
+	const completionKey = buildCompletionKey(data, `result:${claim.meta.originalFile}`);
+	const claimKey = `${path.resolve(context.resultsDir)}:${completionKey}`;
+	const stableHash = createHash("sha256").update(`${claimKey}:${sourceSignature}`).digest("hex");
+	const seen = lookupSeenWithTtl(context.state.completionSeen, completionKey, sourceSignature, Date.now(), context.completionTtlMs);
+	if (seen === "match") {
+		updateResultClaim(claim, { state: "delivered" }, fsApi);
+		removeResultClaim(claim, fsApi);
+		return { status: "done" };
+	}
+	if (seen === "conflict") {
+		quarantineClaim(context, claim);
+		return { status: "done" };
+	}
+	const claimResult = await deliverClaimedCompletion(
+		claimKey,
+		sourceSignature,
+		context.completionTtlMs,
+		{
+			isOwned: () => context.isActive() && context.ownsResult(data),
+			onState: (value) => markClaimState(claim!, value, fsApi),
+			intercom: envelope.intercom ? async (frozen) => {
+				const payload = buildSubagentResultIntercomPayload(frozen.intercom!);
+				payload.requestId = `completion-${stableHash}`;
+				return deliverSubagentResultIntercomEvent(context.pi.events, payload, context.intercomTimeoutMs ?? 500);
+			} : undefined,
+			local: async (frozen) => deliverLocalCompletionNotification(
+				context.pi.events, frozen.local, `completion-notify-${stableHash}`,
+			),
+		},
+		context.maxNoProgressFailures,
+		{
+			envelope: claim.meta.envelope,
+			intercomDelivered: claim.meta.intercomDelivered,
+			localDelivered: claim.meta.localDelivered,
+			noProgressFailures: claim.meta.noProgressFailures,
+		},
+		envelope,
+	);
+	if (claimResult.status === "retry" || claimResult.status === "released") {
+		return context.isActive() && context.ownsResult(data)
+			? { status: "delivery-retry", entry: claimScheduleKey(claim.id) }
+			: { status: "inactive" };
+	}
+	if (claimResult.status === "conflict" || claimResult.status === "exhausted") {
+		quarantineClaim(context, claim);
+		return { status: "done" };
+	}
+	recordSeen(context.state.completionSeen, completionKey, Date.now(), sourceSignature);
+	updateResultClaim(claim, { state: "delivered" }, fsApi);
+	removeResultClaim(claim, fsApi);
+	return { status: "done" };
+}

package/dist/builtin/subagents/src/runs/background/result-file-claims.ts

@@ -0,0 +1,151 @@
+import * as fs from "node:fs";
+import { randomUUID } from "node:crypto";
+import * as path from "node:path";
+import type { GroupedResultIntercomMessageInput } from "../../intercom/result-intercom.js";
+import type { ResultFileData } from "./result-watcher-data.js";
+
+const CLAIMS_DIR = ".claims";
+const CLAIM_SCHEDULE_PREFIX = "@claim/";
+
+export interface FrozenCompletionEnvelope {
+	local: Record<string, unknown>;
+	intercom?: GroupedResultIntercomMessageInput;
+}
+export interface ResultFileClaimMeta {
+	version: 1;
+	id: string;
+	originalFile: string;
+	state: "active" | "delivered" | "undelivered";
+	createdAt: number;
+	sourceSignature?: string;
+	envelope?: FrozenCompletionEnvelope;
+	intercomDelivered?: boolean;
+	localDelivered?: boolean;
+	noProgressFailures?: number;
+}
+
+export interface ResultFileClaim {
+	id: string;
+	dir: string;
+	payloadPath: string;
+	metaPath: string;
+	meta: ResultFileClaimMeta;
+}
+
+export interface ResultClaimFs {
+	mkdirSync?: typeof fs.mkdirSync;
+	renameSync?: typeof fs.renameSync;
+	readFileSync?: typeof fs.readFileSync;
+	writeFileSync?: typeof fs.writeFileSync;
+	readdirSync?: typeof fs.readdirSync;
+	rmSync?: typeof fs.rmSync;
+	rmdirSync?: typeof fs.rmdirSync;
+}
+
+function api(fsApi: ResultClaimFs) {
+	return {
+		mkdirSync: fsApi.mkdirSync ?? fs.mkdirSync,
+		renameSync: fsApi.renameSync ?? fs.renameSync,
+		readFileSync: fsApi.readFileSync ?? fs.readFileSync,
+		writeFileSync: fsApi.writeFileSync ?? fs.writeFileSync,
+		rmSync: fsApi.rmSync ?? fs.rmSync,
+		rmdirSync: fsApi.rmdirSync ?? fs.rmdirSync,
+	};
+}
+
+export function claimScheduleKey(id: string): string {
+	return `${CLAIM_SCHEDULE_PREFIX}${id}`;
+}
+
+export function claimIdFromScheduleKey(key: string): string | undefined {
+	return key.startsWith(CLAIM_SCHEDULE_PREFIX) ? key.slice(CLAIM_SCHEDULE_PREFIX.length) : undefined;
+}
+
+export function loadResultClaim(resultsDir: string, id: string, fsApi: ResultClaimFs = fs): ResultFileClaim | undefined {
+	try {
+		const dir = path.join(resultsDir, CLAIMS_DIR, id);
+		const metaPath = path.join(dir, "claim.json");
+		const payloadPath = path.join(dir, "result.json");
+		const meta = JSON.parse((fsApi.readFileSync ?? fs.readFileSync)(metaPath, "utf-8")) as ResultFileClaimMeta;
+		if (meta.version !== 1 || meta.id !== id || !path.basename(meta.originalFile)) return undefined;
+		return { id, dir, payloadPath, metaPath, meta };
+	} catch {
+		return undefined;
+	}
+}
+
+export function listResultClaims(resultsDir: string, fsApi: ResultClaimFs = fs): ResultFileClaim[] {
+	const claimsDir = path.join(resultsDir, CLAIMS_DIR);
+	try {
+		return (fsApi.readdirSync ?? fs.readdirSync)(claimsDir, { withFileTypes: true })
+			.filter((entry) => entry.isDirectory())
+			.map((entry) => loadResultClaim(resultsDir, entry.name, fsApi))
+			.filter((claim): claim is ResultFileClaim => Boolean(claim));
+	} catch {
+		return [];
+	}
+}
+
+export function claimPublicResult(
+	resultsDir: string,
+	file: string,
+	fsApi: ResultClaimFs = fs,
+	createId: () => string = randomUUID,
+): ResultFileClaim {
+	const f = api(fsApi);
+	const claimsDir = path.join(resultsDir, CLAIMS_DIR);
+	f.mkdirSync(claimsDir, { recursive: true });
+	for (let attempt = 0; attempt < 16; attempt += 1) {
+		const id = createId();
+		const dir = path.join(claimsDir, id);
+		try {
+			f.mkdirSync(dir);
+		} catch (error) {
+			if ((error as NodeJS.ErrnoException).code === "EEXIST") continue;
+			throw error;
+		}
+		const metaPath = path.join(dir, "claim.json");
+		const payloadPath = path.join(dir, "result.json");
+		const meta: ResultFileClaimMeta = {
+			version: 1, id, originalFile: path.basename(file), state: "active", createdAt: Date.now(),
+		};
+		try {
+			f.writeFileSync(metaPath, `${JSON.stringify(meta)}\n`, "utf-8");
+			f.renameSync(path.join(resultsDir, file), payloadPath);
+			return { id, dir, payloadPath, metaPath, meta };
+		} catch (error) {
+			f.rmSync(dir, { recursive: true, force: true });
+			throw error;
+		}
+	}
+	throw new Error(`Unable to allocate a result claim for '${file}'`);
+}
+
+export function readClaimData(claim: ResultFileClaim, fsApi: ResultClaimFs = fs): { raw: string; data: ResultFileData } {
+	const raw = (fsApi.readFileSync ?? fs.readFileSync)(claim.payloadPath, "utf-8");
+	return { raw, data: JSON.parse(raw) as ResultFileData };
+}
+
+export function updateResultClaim(
+	claim: ResultFileClaim,
+	patch: Partial<Omit<ResultFileClaimMeta, "version" | "id" | "originalFile" | "createdAt">>,
+	fsApi: ResultClaimFs = fs,
+): void {
+	const f = api(fsApi);
+	claim.meta = { ...claim.meta, ...patch };
+	const temporary = path.join(claim.dir, `.claim-${randomUUID()}.tmp`);
+	f.writeFileSync(temporary, `${JSON.stringify(claim.meta)}\n`, "utf-8");
+	f.renameSync(temporary, claim.metaPath);
+}
+
+export function removeResultClaim(claim: ResultFileClaim, fsApi: ResultClaimFs = fs): void {
+	const f = api(fsApi);
+	f.rmSync(claim.dir, { recursive: true, force: true });
+	try { f.rmdirSync(path.dirname(claim.dir)); } catch { /* another active claim keeps the shared directory */ }
+}
+
+export function recoverTerminalClaim(claim: ResultFileClaim, fsApi: ResultClaimFs = fs): "active" | "removed" {
+	if (claim.meta.state === "active") return "active";
+	removeResultClaim(claim, fsApi);
+	return "removed";
+}