@hecer/yoke 1.3.0 → 1.5.0

package/dist/loop/candidate-selection.js

@@ -0,0 +1,84 @@
+import { randomUUID } from 'node:crypto';
+import { reduceCandidatePairComparisons } from '../quality/verdict.js';
+import { parseCandidateEvidence } from './candidate-boundaries.js';
+export async function selectCandidate(input) {
+    const first = input.candidates[0];
+    if (!first)
+        return { kind: 'inconsistent', reason: 'selection requires one candidate' };
+    let selected = first;
+    let selectedEvidence = await prepareEvidence(input, first);
+    input.ensureActive();
+    if (input.pause?.())
+        return { kind: 'paused' };
+    const comparisons = [];
+    for (let index = 1; index < input.candidates.length; index += 1) {
+        const challenger = input.candidates[index];
+        if (!challenger)
+            continue;
+        const challengerEvidence = await prepareEvidence(input, challenger);
+        input.ensureActive();
+        if (input.pause?.())
+            return { kind: 'paused' };
+        const normal = issueComparison({ left: { candidate: selected, evidence: selectedEvidence }, right: { candidate: challenger, evidence: challengerEvidence }, provenance: input.judgeProvenance });
+        const swapped = issueComparison({ left: { candidate: challenger, evidence: challengerEvidence }, right: { candidate: selected, evidence: selectedEvidence }, provenance: input.judgeProvenance });
+        const normalVerdict = await input.judge(structuredClone(normal.expected.request));
+        input.ensureActive();
+        if (input.pause?.())
+            return { kind: 'paused' };
+        const swappedVerdict = await input.judge(structuredClone(swapped.expected.request));
+        input.ensureActive();
+        if (input.pause?.())
+            return { kind: 'paused' };
+        const reduction = reduceCandidatePairComparisons({ expected: { normal: normal.expected, swapped: swapped.expected }, normal: normalVerdict, swapped: swappedVerdict });
+        if (reduction.kind === 'inconsistent')
+            return reduction;
+        const winner = reduction.winnerCandidateId === selected.candidateId ? selected : challenger;
+        const loser = winner.candidateId === selected.candidateId ? challenger : selected;
+        comparisons.push({
+            normal: { request: structuredClone(normal.expected.request), verdict: structuredClone(reduction.normal) },
+            swapped: { request: structuredClone(swapped.expected.request), verdict: structuredClone(reduction.swapped) },
+            selectedCandidateId: reduction.winnerCandidateId,
+            selectedDigest: reduction.winnerDigest,
+        });
+        await input.discard(loser);
+        input.ensureActive();
+        if (input.pause?.())
+            return { kind: 'paused' };
+        if (winner.candidateId === challenger.candidateId) {
+            selected = challenger;
+            selectedEvidence = challengerEvidence;
+        }
+    }
+    input.ensureActive();
+    return input.pause?.() ? { kind: 'paused' } : { kind: 'selected', candidate: selected, evidence: selectedEvidence.trusted, comparisons };
+}
+async function prepareEvidence(input, candidate) {
+    const trusted = parseCandidateEvidence(input.evidence(candidate));
+    const handle = { digest: `evidence-${randomUUID()}`, artifacts: trusted.artifacts.map(() => `artifact-${randomUUID()}`) };
+    await input.stageEvidence({
+        handle: { digest: handle.digest, artifacts: [...handle.artifacts] },
+        trusted: { digest: trusted.digest, artifacts: [...trusted.artifacts] },
+    });
+    return { trusted, handle };
+}
+function issueComparison(input) {
+    const request = {
+        permissions: 'read-only',
+        attemptId: randomUUID(),
+        left: { digest: input.left.evidence.handle.digest, artifacts: [...input.left.evidence.handle.artifacts], label: 'A' },
+        right: { digest: input.right.evidence.handle.digest, artifacts: [...input.right.evidence.handle.artifacts], label: 'B' },
+    };
+    return {
+        request,
+        expected: {
+            request: {
+                permissions: request.permissions,
+                attemptId: request.attemptId,
+                left: { ...request.left, artifacts: [...request.left.artifacts] },
+                right: { ...request.right, artifacts: [...request.right.artifacts] },
+            },
+            candidateIds: { left: input.left.candidate.candidateId, right: input.right.candidate.candidateId },
+            provenance: { ...input.provenance },
+        },
+    };
+}

package/dist/loop/candidates.js

@@ -0,0 +1,228 @@
+import { candidateConfigProblem, canonicalWorktreePath } from './candidate-boundaries.js';
+import { CandidateCleanup } from './candidate-cleanup.js';
+import { selectCandidate } from './candidate-selection.js';
+import { runStoryWorker } from './worker.js';
+class CandidateCancellationError extends Error {
+    name = 'CandidateCancellationError';
+}
+export async function coordinateCandidates(input) {
+    const configProblem = candidateConfigProblem(input);
+    if (configProblem)
+        return { kind: 'blocked', reason: 'invalid-config', summary: configProblem };
+    if (input.signal?.aborted)
+        return { kind: 'cancelled', summary: cancellationSummary(input.signal) };
+    const definitions = input.candidates.slice(0, input.maxCandidates);
+    const pathPlatform = input.pathPlatform ?? (process.platform === 'win32' ? 'win32' : 'posix');
+    const owned = [];
+    const outcomes = new Map();
+    const cleanup = new CandidateCleanup(input.lifecycle, input.onLifecycle);
+    const terminalize = async (candidate, reason) => {
+        const result = outcomes.get(candidate.candidateId) ?? {
+            kind: 'cancelled', storyId: candidate.storyId, worktree: candidate.worktree.path,
+            baseCommit: candidate.worktree.baseCommit, provider: candidate.provider, summary: reason,
+            evidence: { criteria: [] },
+        };
+        await input.recordResult?.({ ...candidate, result });
+        await input.recordElimination?.({ ...candidate, result });
+    };
+    const terminalizeAll = async (reason) => {
+        for (const candidate of owned)
+            await terminalize(candidate, reason);
+    };
+    const ensureActive = () => {
+        if (input.signal?.aborted)
+            throw new CandidateCancellationError(cancellationSummary(input.signal));
+    };
+    const cancelActive = () => cleanup.cancelNow(input.signal ? cancellationSummary(input.signal) : 'candidate coordinator cancelled');
+    input.signal?.addEventListener('abort', cancelActive, { once: true });
+    const finishPaused = async () => {
+        await terminalizeAll('candidate coordination paused');
+        await cleanup.cleanupAll('candidate coordination paused');
+        ensureActive();
+        return cleanup.hasFailures()
+            ? blocked(cleanup, 'cleanup-error', 'candidate pause cleanup failed')
+            : { kind: 'paused', summary: 'candidate coordination paused' };
+    };
+    try {
+        const paths = new Set();
+        for (const definition of definitions) {
+            const controller = new AbortController();
+            const provenance = provenanceFor(input, definition);
+            const worktree = input.lifecycle.reserve({ ...provenance, baseCommit: input.baseCommit });
+            const candidate = { ...provenance, worktree, signal: controller.signal, controller, definition };
+            owned.push(candidate);
+            cleanup.register(candidate);
+            input.onLifecycle?.(candidate, 'reserved');
+            const canonicalPath = canonicalWorktreePath(worktree.path, pathPlatform);
+            if (worktree.baseCommit !== input.baseCommit || canonicalPath === null || paths.has(canonicalPath)) {
+                await cleanup.cleanupAll('candidate worktree invariant failed');
+                ensureActive();
+                return blocked(cleanup, 'worktree-invariant', 'candidate worktrees must be unique absolute paths and share the configured base');
+            }
+            paths.add(canonicalPath);
+        }
+        for (const candidate of owned) {
+            await input.lifecycle.materialize(candidate);
+            cleanup.markMaterialized(candidate.candidateId);
+            input.onLifecycle?.(candidate, 'materialized');
+            ensureActive();
+            if (input.pause?.())
+                return await finishPaused();
+        }
+        for (const candidate of owned)
+            input.onLifecycle?.(candidate, 'running');
+        const runs = await runCandidates(input, owned);
+        for (const run of runs)
+            outcomes.set(run.owned.candidateId, run.result);
+        ensureActive();
+        if (input.pause?.() || runs.some(run => run.result.kind === 'paused')) {
+            return await finishPaused();
+        }
+        const green = [];
+        for (const run of runs) {
+            await input.recordResult?.({ ...run.owned, result: run.result });
+            switch (run.result.kind) {
+                case 'candidate':
+                    green.push({ ...run.owned, result: run.result });
+                    break;
+                case 'cancelled':
+                case 'mechanical-failure':
+                case 'quality-failure':
+                case 'review-failure':
+                    input.onLifecycle?.(run.owned, 'cleaning', run.result.summary);
+                    await input.recordElimination?.({ ...run.owned, result: run.result });
+                    await cleanup.cleanup(run.owned, run.result.summary);
+                    ensureActive();
+                    break;
+                case 'paused':
+                    throw new Error('paused candidates must be handled before mechanical filtering');
+            }
+        }
+        ensureActive();
+        if (input.pause?.())
+            return await finishPaused();
+        if (green.length === 0)
+            return blocked(cleanup, 'zero-green', 'no candidate passed every mechanical gate');
+        for (const candidate of green)
+            input.onLifecycle?.(candidate, 'selecting');
+        input.onSelecting?.();
+        const selection = await selectCandidate({
+            candidates: green,
+            evidence: input.evidence,
+            stageEvidence: input.stageEvidence,
+            judgeProvenance: input.judgeProvenance,
+            judge: input.judge,
+            ...(input.pause ? { pause: input.pause } : {}),
+            ensureActive,
+            discard: async (candidate) => {
+                await input.recordElimination?.(candidate);
+                await cleanup.cleanup(candidate, 'candidate was not selected');
+            },
+        });
+        ensureActive();
+        if (selection.kind === 'paused')
+            return await finishPaused();
+        if (selection.kind === 'inconsistent') {
+            for (const candidate of green)
+                await input.recordElimination?.({ ...candidate, result: candidate.result }, `selection-inconsistent: ${selection.reason}`);
+            await cleanup.cleanupAll(`candidate selection was inconsistent: ${selection.reason}`);
+            ensureActive();
+            if (input.pause?.())
+                return await finishPaused();
+            return blocked(cleanup, 'selection-inconsistent', selection.reason);
+        }
+        const { controller: _controller, definition: _definition, ...winner } = selection.candidate;
+        const selectedWinner = {
+            ...winner,
+            digest: selection.evidence.digest,
+            artifacts: [...selection.evidence.artifacts],
+            comparisons: [...selection.comparisons],
+        };
+        await input.recordSelection?.(selectedWinner);
+        await cleanup.cleanupAll('candidate was not selected', selection.candidate.candidateId);
+        ensureActive();
+        if (input.pause?.())
+            return await finishPaused();
+        if (cleanup.hasFailures()) {
+            await cleanup.cleanup(selection.candidate, 'candidate cleanup failed');
+            ensureActive();
+            if (input.pause?.())
+                return await finishPaused();
+            return blocked(cleanup, 'cleanup-error', 'candidate loser cleanup failed');
+        }
+        return {
+            kind: 'winner',
+            winner: selectedWinner,
+        };
+    }
+    catch (error) {
+        let proofFailure;
+        try {
+            await terminalizeAll(`candidate coordinator failed: ${message(error)}`);
+        }
+        catch (proofError) {
+            proofFailure = message(proofError);
+        }
+        await cleanup.cleanupAll('candidate coordinator failed');
+        if (proofFailure)
+            return blocked(cleanup, 'cleanup-error', `candidate terminal proof failed: ${proofFailure}`);
+        if (input.signal?.aborted) {
+            return cleanup.hasFailures()
+                ? blocked(cleanup, 'cleanup-error', 'candidate cancellation cleanup failed')
+                : { kind: 'cancelled', summary: cancellationSummary(input.signal) };
+        }
+        if (input.pause?.()) {
+            try {
+                return await finishPaused();
+            }
+            catch (pauseError) {
+                if (input.signal?.aborted) {
+                    return cleanup.hasFailures()
+                        ? blocked(cleanup, 'cleanup-error', 'candidate cancellation cleanup failed')
+                        : { kind: 'cancelled', summary: cancellationSummary(input.signal) };
+                }
+                return blocked(cleanup, 'coordinator-error', message(pauseError));
+            }
+        }
+        return blocked(cleanup, 'coordinator-error', message(error));
+    }
+    finally {
+        input.signal?.removeEventListener('abort', cancelActive);
+    }
+}
+async function runCandidates(input, owned) {
+    const settled = await Promise.allSettled(owned.map(async (candidate) => ({
+        owned: candidate,
+        result: await runStoryWorker({
+            ...candidate.definition.worker,
+            ...(candidate.definition.runnerFor ? { runner: candidate.definition.runnerFor({ signal: candidate.signal }) } : {}),
+            ...(candidate.definition.reporterFor ? { reporter: candidate.definition.reporterFor(candidate) } : {}),
+            story: structuredClone(input.story),
+            worktree: candidate.worktree.path,
+            baseCommit: candidate.worktree.baseCommit,
+            cancellation: { signal: candidate.signal },
+        }),
+    })));
+    const runs = [];
+    for (const outcome of settled) {
+        if (outcome.status === 'rejected')
+            throw new Error(`candidate worker failed: ${message(outcome.reason)}`);
+        runs.push(outcome.value);
+    }
+    return runs;
+}
+function provenanceFor(input, definition) {
+    return { candidateId: definition.id, coordinatorId: input.coordinatorId, ownerToken: input.ownerToken(definition.id), storyId: input.story.id, provider: definition.worker.provider };
+}
+function cancellationSummary(signal) {
+    return typeof signal.reason === 'string' && signal.reason.length > 0 ? signal.reason : 'candidate coordinator cancelled';
+}
+function message(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function blocked(cleanup, reason, summary) {
+    const recovery = cleanup.recovery();
+    return cleanup.hasFailures()
+        ? { kind: 'blocked', reason: 'cleanup-error', summary: cleanup.failureSummary(), recovery }
+        : { kind: 'blocked', reason, summary };
+}

package/dist/loop/claim-lease.js

@@ -0,0 +1,131 @@
+import { existsSync, linkSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { randomUUID } from 'node:crypto';
+import { dirname } from 'node:path';
+import { z } from 'zod';
+const ClaimOperationLeaseSchema = z.object({
+    schemaVersion: z.literal(1),
+    token: z.string().uuid(),
+    pid: z.number().int().positive(),
+    createdAt: z.string().min(1),
+});
+function operationPath(file) {
+    return `${file}.operation`;
+}
+function recoveryPath(file) {
+    return `${operationPath(file)}.recovery`;
+}
+function errorCode(error) {
+    if (typeof error !== 'object' || error === null || !('code' in error))
+        return undefined;
+    return typeof error.code === 'string' ? error.code : undefined;
+}
+function publish(file, value, token = randomUUID()) {
+    mkdirSync(dirname(file), { recursive: true });
+    const temporary = `${file}.${token}.tmp`;
+    writeFileSync(temporary, JSON.stringify(value), { flag: 'wx' });
+    try {
+        linkSync(temporary, file);
+        return true;
+    }
+    catch (error) {
+        if (errorCode(error) === 'EEXIST')
+            return false;
+        throw error;
+    }
+    finally {
+        rmSync(temporary, { force: true });
+    }
+}
+function readLease(file) {
+    if (!existsSync(file))
+        return null;
+    try {
+        return ClaimOperationLeaseSchema.parse(JSON.parse(readFileSync(file, 'utf8')));
+    }
+    catch {
+        return null;
+    }
+}
+function expired(lease, options) {
+    const createdAt = Date.parse(lease.createdAt);
+    return !options.isAlive(lease.pid) && (!Number.isFinite(createdAt) || options.now.getTime() - createdAt > options.staleMs);
+}
+function lease(token, options) {
+    return { schemaVersion: 1, token, pid: process.pid, createdAt: options.now.toISOString() };
+}
+function acquireRecovery(file, options) {
+    const token = randomUUID();
+    if (publish(file, lease(token, options), token))
+        return token;
+    const observed = readLease(file);
+    if (!observed || !expired(observed, options))
+        return null;
+    options.filesystem?.beforeRecoveryRemove?.(file);
+    const current = readLease(file);
+    if (!current || current.token !== observed.token || !expired(current, options))
+        return null;
+    rmSync(file, { force: true });
+    return publish(file, lease(token, options), token) ? token : null;
+}
+export function publishClaimFile(file, value) {
+    return publish(file, value);
+}
+export function replaceClaimFile(file, value) {
+    const temporary = `${file}.${randomUUID()}.tmp`;
+    writeFileSync(temporary, JSON.stringify(value), { flag: 'wx' });
+    renameSync(temporary, file);
+}
+export function acquireClaimOperation(file, options) {
+    const token = randomUUID();
+    const candidate = lease(token, options);
+    const operation = operationPath(file);
+    if (publish(operation, candidate, token))
+        return token;
+    const observed = readLease(operation);
+    if (!observed || !expired(observed, options))
+        return null;
+    const recovery = recoveryPath(file);
+    const recoveryToken = acquireRecovery(recovery, options);
+    if (!recoveryToken)
+        return null;
+    try {
+        const current = readLease(operation);
+        if (!current || !expired(current, options))
+            return null;
+        rmSync(operation, { force: true });
+        return publish(operation, candidate, token) ? token : null;
+    }
+    finally {
+        releaseClaimOperation(recovery, recoveryToken, true);
+    }
+}
+export function releaseClaimOperation(file, token, rawPath = false) {
+    const operation = rawPath ? file : operationPath(file);
+    const current = readLease(operation);
+    if (current?.token === token)
+        rmSync(operation, { force: true });
+}
+export function withClaimOperation(file, context, readRecords, task) {
+    return withClaimOperations(file, context, readRecords, () => [], task);
+}
+export function withClaimOperations(file, context, readRecords, claimFiles, task) {
+    const token = acquireClaimOperation(file, context);
+    if (!token)
+        return null;
+    const acquired = [];
+    const orderedFiles = [...new Set(claimFiles(readRecords()).filter(candidate => candidate !== file))].sort((left, right) => left.localeCompare(right));
+    try {
+        for (const nextFile of orderedFiles) {
+            const nextToken = acquireClaimOperation(nextFile, context);
+            if (!nextToken)
+                return null;
+            acquired.push({ file: nextFile, token: nextToken });
+        }
+        return task(readRecords());
+    }
+    finally {
+        for (const lease of acquired.reverse())
+            releaseClaimOperation(lease.file, lease.token);
+        releaseClaimOperation(file, token);
+    }
+}

package/dist/loop/claims.js

@@ -1,57 +1,194 @@
-import { closeSync, mkdirSync, openSync, readFileSync, readdirSync, rmSync, writeFileSync } from 'node:fs';
+import { existsSync, readFileSync, readdirSync, rmSync } from 'node:fs';
 import { join } from 'node:path';
-const pathFor = (dir, id) => join(dir, '.yoke', 'claims', `${id}.json`);
-export function acquireClaim(dir, storyId, owner, opts = {}) {
-    const path = pathFor(dir, storyId);
-    mkdirSync(join(dir, '.yoke', 'claims'), { recursive: true });
-    const now = opts.now ?? new Date();
-    try {
-        const old = JSON.parse(readFileSync(path, 'utf8'));
-        if (now.getTime() - Date.parse(old.claimedAt) <= (opts.staleMs ?? 30 * 60_000))
-            return null;
-        rmSync(path, { force: true });
-    }
-    catch { /* absent or malformed */ }
-    const claim = { storyId, owner, pid: opts.pid ?? process.pid, claimedAt: now.toISOString() };
+import { z } from 'zod';
+import { isPidAlive } from './lock.js';
+import { publishClaimFile, replaceClaimFile, withClaimOperations } from './claim-lease.js';
+import { storyPathSegment } from './prd.js';
+export const CLAIM_SCHEMA_VERSION = 2;
+const LegacyClaimSchema = z.object({
+    storyId: z.string().min(1),
+    owner: z.string().min(1),
+    pid: z.number().int().positive(),
+    claimedAt: z.string().min(1),
+});
+const RichClaimSchema = LegacyClaimSchema.extend({
+    schemaVersion: z.literal(CLAIM_SCHEMA_VERSION),
+    dispatcherId: z.string().min(1),
+    ownerToken: z.string().min(1),
+    heartbeatAt: z.string().min(1),
+    baseCommit: z.string().min(1).optional(),
+    worktree: z.string().min(1).optional(),
+    provider: z.enum(['claude', 'codex', 'gemini']).optional(),
+    model: z.string().min(1).optional(),
+    role: z.enum(['implementation', 'quality', 'repair', 'review']).optional(),
+    cancellation: z.object({
+        requestedAt: z.string().min(1),
+        reason: z.string().min(1),
+    }).optional(),
+});
+const StoredClaimSchema = z.union([RichClaimSchema, LegacyClaimSchema]);
+function claimsDir(dir) {
+    return join(dir, '.yoke', 'claims');
+}
+function pathFor(dir, id) {
+    return join(claimsDir(dir), `${storyPathSegment(id)}.json`);
+}
+function claimOwner(claim) {
+    return 'ownerToken' in claim ? claim.ownerToken : claim.owner;
+}
+function readClaimFile(file) {
+    if (!existsSync(file))
+        return null;
     try {
-        const fd = openSync(path, 'wx');
-        writeFileSync(fd, JSON.stringify(claim));
-        closeSync(fd);
-        return claim;
+        return StoredClaimSchema.parse(JSON.parse(readFileSync(file, 'utf8')));
     }
     catch {
         return null;
     }
 }
-export function releaseClaim(dir, storyId, owner) {
-    const path = pathFor(dir, storyId);
-    try {
-        const claim = JSON.parse(readFileSync(path, 'utf8'));
-        if (claim.owner !== owner)
+function claimRecords(dir, storyId) {
+    const canonicalPath = pathFor(dir, storyId);
+    const records = [];
+    const canonicalClaim = readClaimFile(canonicalPath);
+    if (canonicalClaim?.storyId === storyId)
+        records.push({ path: canonicalPath, claim: canonicalClaim });
+    if (!existsSync(claimsDir(dir)))
+        return records;
+    for (const file of readdirSync(claimsDir(dir))) {
+        const path = join(claimsDir(dir), file);
+        if (path === canonicalPath)
+            continue;
+        const claim = readClaimFile(path);
+        if (claim?.storyId === storyId)
+            records.push({ path, claim });
+    }
+    return records;
+}
+function resolveClaimRecord(dir, storyId) {
+    return claimRecords(dir, storyId)[0] ?? null;
+}
+function matchingClaimRecords(records, ownerToken) {
+    return records.filter(record => claimOwner(record.claim) === ownerToken);
+}
+export function readClaim(dir, storyId) {
+    return resolveClaimRecord(dir, storyId)?.claim ?? null;
+}
+function isExpired(claim, now, staleMs, isAlive) {
+    const heartbeatAt = 'heartbeatAt' in claim ? claim.heartbeatAt : claim.claimedAt;
+    const heartbeatMs = Date.parse(heartbeatAt);
+    return !isAlive(claim.pid) && (!Number.isFinite(heartbeatMs) || now.getTime() - heartbeatMs > staleMs);
+}
+function richClaim(storyId, owner, options) {
+    const now = options.now ?? new Date();
+    const ownerToken = options.ownerToken ?? owner;
+    return {
+        schemaVersion: CLAIM_SCHEMA_VERSION,
+        storyId,
+        owner: ownerToken,
+        ownerToken,
+        dispatcherId: options.dispatcherId ?? owner,
+        pid: options.pid ?? process.pid,
+        claimedAt: now.toISOString(),
+        heartbeatAt: now.toISOString(),
+        ...(options.baseCommit ? { baseCommit: options.baseCommit } : {}),
+        ...(options.worktree ? { worktree: options.worktree } : {}),
+        ...(options.provider ? { provider: options.provider } : {}),
+        ...(options.model ? { model: options.model } : {}),
+        ...(options.role ? { role: options.role } : {}),
+    };
+}
+function promoteClaim(claim, now) {
+    if ('schemaVersion' in claim)
+        return claim;
+    return {
+        schemaVersion: CLAIM_SCHEMA_VERSION,
+        storyId: claim.storyId,
+        owner: claim.owner,
+        ownerToken: claim.owner,
+        dispatcherId: claim.owner,
+        pid: claim.pid,
+        claimedAt: claim.claimedAt,
+        heartbeatAt: now.toISOString(),
+    };
+}
+export function acquireClaim(dir, storyId, owner, options = {}) {
+    const candidate = richClaim(storyId, owner, options);
+    const now = options.now ?? new Date();
+    const staleMs = options.staleMs ?? 30 * 60_000;
+    const isAlive = options.isAlive ?? isPidAlive;
+    const file = resolveClaimRecord(dir, storyId)?.path ?? pathFor(dir, storyId);
+    return withClaimOperations(file, { now, staleMs, isAlive }, () => claimRecords(dir, storyId), records => records.map(record => record.path), records => {
+        if (records.some(record => !isExpired(record.claim, now, staleMs, isAlive)))
+            return null;
+        for (const record of records)
+            rmSync(record.path, { force: true });
+        return publishClaimFile(pathFor(dir, storyId), candidate) ? candidate : null;
+    });
+}
+export function heartbeatClaim(dir, storyId, ownerToken, options = {}) {
+    const now = options.now ?? new Date();
+    const staleMs = options.staleMs ?? 30 * 60_000;
+    const isAlive = options.isAlive ?? isPidAlive;
+    const file = resolveClaimRecord(dir, storyId)?.path ?? pathFor(dir, storyId);
+    return withClaimOperations(file, { now, staleMs, isAlive }, () => claimRecords(dir, storyId), records => records.map(record => record.path), records => {
+        const record = records.find(candidate => claimOwner(candidate.claim) === ownerToken);
+        if (!record)
+            return null;
+        const updated = { ...promoteClaim(record.claim, now), heartbeatAt: now.toISOString() };
+        for (const matchingRecord of matchingClaimRecords(records, ownerToken))
+            replaceClaimFile(matchingRecord.path, updated);
+        return updated;
+    });
+}
+export function requestClaimCancellation(dir, storyId, ownerToken, reason, options = {}) {
+    const now = options.now ?? new Date();
+    const staleMs = options.staleMs ?? 30 * 60_000;
+    const isAlive = options.isAlive ?? isPidAlive;
+    const file = resolveClaimRecord(dir, storyId)?.path ?? pathFor(dir, storyId);
+    return withClaimOperations(file, { now, staleMs, isAlive }, () => claimRecords(dir, storyId), records => records.map(record => record.path), records => {
+        const record = records.find(candidate => claimOwner(candidate.claim) === ownerToken);
+        if (!record)
+            return null;
+        const updated = {
+            ...promoteClaim(record.claim, now),
+            cancellation: { reason, requestedAt: now.toISOString() },
+        };
+        for (const matchingRecord of matchingClaimRecords(records, ownerToken))
+            replaceClaimFile(matchingRecord.path, updated);
+        return updated;
+    });
+}
+export function releaseClaim(dir, storyId, ownerToken, options = {}) {
+    const now = options.now ?? new Date();
+    const staleMs = options.staleMs ?? 30 * 60_000;
+    const isAlive = options.isAlive ?? isPidAlive;
+    const file = resolveClaimRecord(dir, storyId)?.path ?? pathFor(dir, storyId);
+    return withClaimOperations(file, { now, staleMs, isAlive }, () => claimRecords(dir, storyId), records => records.map(record => record.path), records => {
+        const matchingRecords = matchingClaimRecords(records, ownerToken);
+        if (!matchingRecords.length)
             return false;
-        rmSync(path, { force: true });
+        for (const record of matchingRecords)
+            rmSync(record.path, { force: true });
         return true;
-    }
-    catch {
-        return false;
-    }
+    }) ?? false;
 }
-export function cleanupClaims(dir, owner) {
-    const claimsDir = join(dir, '.yoke', 'claims');
+export function cleanupClaims(dir, ownerToken) {
+    const dirPath = claimsDir(dir);
     let removed = 0;
     try {
-        for (const file of readdirSync(claimsDir)) {
-            const path = join(claimsDir, file);
-            try {
-                const claim = JSON.parse(readFileSync(path, 'utf8'));
-                if (!owner || claim.owner === owner) {
-                    rmSync(path, { force: true });
-                    removed++;
-                }
+        for (const file of readdirSync(dirPath)) {
+            const path = join(dirPath, file);
+            const claim = readClaimFile(path);
+            if (!claim)
+                continue;
+            if (!ownerToken || claimOwner(claim) === ownerToken) {
+                rmSync(path, { force: true });
+                removed += 1;
             }
-            catch { /* scoped cleanup never guesses ownership */ }
         }
     }
-    catch { /* no claims */ }
+    catch {
+        return removed;
+    }
     return removed;
 }