@fitlab-ai/agent-infra 0.9.6 → 0.9.7

package/dist/lib/internal/codex-sandbox-controller.js

@@ -0,0 +1,106 @@
+import { runCodexSandboxController, verifyCodexSandboxControllerContext } from '../agent-clients/adapters/codex-lifecycle/sandbox-controller.js';
+const USAGE = 'Usage: agent-infra-internal codex-sandbox-controller <run|verify-context> [options]\n';
+function fail(code, message, exitCode = 1) {
+    process.stdout.write(`${JSON.stringify({
+        status: 'failed',
+        changed: false,
+        error: { code, message }
+    })}\n`);
+    process.exitCode = exitCode;
+}
+function parse(args) {
+    if (args[0] === '--help' || args[0] === '-h') {
+        process.stdout.write(USAGE);
+        return null;
+    }
+    const operation = args[0];
+    if (!operation || !['run', 'verify-context'].includes(operation)) {
+        process.stderr.write(USAGE);
+        fail('CODEX_SANDBOX_CONTROLLER_PAYLOAD_INVALID', 'operation must be run or verify-context', 2);
+        return null;
+    }
+    const allowed = new Set([
+        '--task-id',
+        '--task-ref',
+        '--context',
+        '--executor-model',
+        '--executor-reasoning-effort',
+        '--reviewer-model',
+        '--reviewer-reasoning-effort'
+    ]);
+    const values = {};
+    for (let index = 1; index < args.length; index += 1) {
+        const flag = args[index];
+        const value = args[++index];
+        if (!allowed.has(flag) || Object.hasOwn(values, flag) || !value || value.startsWith('--')) {
+            fail('CODEX_SANDBOX_CONTROLLER_PAYLOAD_INVALID', `invalid option '${flag}'`, 2);
+            return null;
+        }
+        values[flag] = value;
+    }
+    return { operation, values };
+}
+async function codexSandboxController(args = []) {
+    const parsed = parse(args);
+    if (!parsed || process.exitCode)
+        return;
+    const taskId = parsed.values['--task-id'];
+    if (!taskId) {
+        fail('CODEX_SANDBOX_CONTROLLER_PAYLOAD_INVALID', '--task-id is required', 2);
+        return;
+    }
+    try {
+        if (parsed.operation === 'verify-context') {
+            const contextPath = parsed.values['--context']
+                ?? process.env.AGENT_INFRA_CODEX_CONTROLLER_CONTEXT;
+            if (!contextPath)
+                throw new Error('CODEX_SANDBOX_CONTROLLER_CONTEXT_MISSING');
+            const context = verifyCodexSandboxControllerContext(contextPath, taskId);
+            process.stdout.write(`${JSON.stringify({
+                status: 'ready',
+                changed: false,
+                context: {
+                    taskId: context.taskId,
+                    controlGeneration: context.controlGeneration,
+                    controllerInstanceDigest: context.controllerInstanceDigest,
+                    expiresAt: context.expiresAt,
+                    buildIdentity: context.buildIdentity,
+                    hookDefinitionHash: context.hookDefinitionHash,
+                    lifecycleProfilesHash: context.lifecycleProfilesHash
+                },
+                error: null
+            })}\n`);
+            return;
+        }
+        const taskRef = parsed.values['--task-ref'];
+        if (!taskRef)
+            throw new Error('CODEX_SANDBOX_CONTROLLER_TASK_REF_REQUIRED');
+        const policy = [
+            '--executor-model',
+            '--executor-reasoning-effort',
+            '--reviewer-model',
+            '--reviewer-reasoning-effort'
+        ];
+        if (policy.some((flag) => parsed.values[flag] !== undefined)
+            && policy.some((flag) => parsed.values[flag] === undefined)) {
+            throw new Error('CODEX_SANDBOX_CONTROLLER_MODEL_POLICY_INVALID');
+        }
+        const exitCode = await runCodexSandboxController({
+            taskId,
+            taskRef,
+            executorModel: parsed.values['--executor-model'],
+            executorReasoningEffort: parsed.values['--executor-reasoning-effort'],
+            reviewerModel: parsed.values['--reviewer-model'],
+            reviewerReasoningEffort: parsed.values['--reviewer-reasoning-effort']
+        });
+        process.exitCode = exitCode;
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        const code = /^([A-Z][A-Z0-9_]+)/u.exec(message)?.[1]
+            ?? 'CODEX_SANDBOX_CONTROLLER_FAILED';
+        fail(code, message);
+    }
+}
+export { codexSandboxController };
+//# sourceMappingURL=codex-sandbox-controller.js.map

package/dist/lib/internal/task-orchestration.js

@@ -1,8 +1,8 @@
 import { normalizeAgentToken, AGENT_USAGE_HINT } from '../agent-clients/tokens.js';
-import { abortCommitIntent, activateMatchingOrchestrationDelegation, activateOrchestrationDelegation, advanceOrchestration, beginCommitIntent, beginOrResumeOrchestration, checkpointCommitIntent, completeCommitIntent, pauseOrchestration, recoverCommitIntent, routeOrchestration, sealMatchingOrchestrationDelegation, sealOrchestrationDelegation, startCommitAttempt, statusCommitIntent, statusOrchestration, terminateCommitAttempt } from '../task/orchestration.js';
+import { abortCommitIntent, activateMatchingOrchestrationDelegation, activateOrchestrationDelegation, advanceOrchestration, awaitOrchestrationDelegationActivation, beginCommitIntent, beginOrResumeOrchestration, checkpointCommitIntent, completeCommitIntent, dispatchOrchestrationDelegation, pauseOrchestration, recoverCommitIntent, recoverPreparedOrchestrationDelegation, routeOrchestration, sealMatchingOrchestrationDelegation, sealOrchestrationDelegation, startCommitAttempt, statusCommitIntent, statusOrchestration, terminateCommitAttempt } from '../task/orchestration.js';
 import { prepareCodexOrchestrationDelegation } from '../task/codex-orchestration.js';
 import { isAgentClientId } from '../agent-clients/types.js';
-const USAGE = 'Usage: agent-infra-internal task-orchestration <task-ref|auto> <begin-or-resume|route|prepare|hook-start|hook-stop|advance|pause|status|commit-start|commit-begin|commit-checkpoint|commit-complete|commit-recover|commit-abort|commit-terminate|commit-status> [options]\n';
+const USAGE = 'Usage: agent-infra-internal task-orchestration <task-ref|auto> <begin-or-resume|route|prepare|dispatch|await-activation|recover-prepared|hook-start|hook-stop|advance|pause|status|commit-start|commit-begin|commit-checkpoint|commit-complete|commit-recover|commit-abort|commit-terminate|commit-status> [options]\n';
 function usageFailure(message) {
     process.stdout.write(`${JSON.stringify({
         status: 'failed', changed: false,
@@ -22,7 +22,8 @@ async function taskOrchestration(args = []) {
     }
     const [taskRef, intent] = args;
     if (![
-        'begin-or-resume', 'route', 'prepare', 'hook-start', 'hook-stop', 'advance', 'pause', 'status',
+        'begin-or-resume', 'route', 'prepare', 'dispatch', 'await-activation', 'recover-prepared',
+        'hook-start', 'hook-stop', 'advance', 'pause', 'status',
         'commit-start', 'commit-begin', 'commit-checkpoint', 'commit-complete', 'commit-recover', 'commit-abort', 'commit-terminate', 'commit-status'
     ].includes(intent)) {
         usageFailure(`unknown intent '${intent}'`);
@@ -45,7 +46,9 @@ async function taskOrchestration(args = []) {
         if (![
             '--max-steps', '--executor-model', '--executor-reasoning-effort',
             '--reviewer-model', '--reviewer-reasoning-effort',
-            '--client', '--requested-model', '--requested-reasoning-effort', '--parent-id', '--before-fingerprint',
+            '--client', '--requested-model', '--requested-reasoning-effort', '--capability-token',
+            '--parent-id', '--before-fingerprint',
+            '--stage', '--round', '--artifact', '--role',
             '--native-agent', '--child-id', '--spawn-mode', '--actual-model', '--actual-reasoning-effort',
             '--model-fallback-reason', '--reasoning-effort-fallback-reason',
             '--exit-code', '--after-fingerprint', '--changed-paths', '--code', '--message', '--recoverable', '--agent',
@@ -264,9 +267,38 @@ async function taskOrchestration(args = []) {
         result = await prepareCodexOrchestrationDelegation(taskRef, {
             client: values['--client'],
             requestedModel: values['--requested-model'],
-            requestedReasoningEffort: values['--requested-reasoning-effort']
+            requestedReasoningEffort: values['--requested-reasoning-effort'],
+            capabilityToken: values['--capability-token']
         }, { orchestrationOptions: coreOptions });
     }
+    else if (intent === 'dispatch') {
+        result = dispatchOrchestrationDelegation(taskRef, coreOptions);
+    }
+    else if (intent === 'await-activation') {
+        const missing = requireValues(['--stage', '--round', '--artifact', '--role']);
+        if (missing) {
+            usageFailure(`intent 'await-activation' requires '${missing}'`);
+            return;
+        }
+        const round = Number(values['--round']);
+        if (!Number.isSafeInteger(round) || round < 1) {
+            usageFailure('--round must be a positive integer');
+            return;
+        }
+        if (!['executor', 'reviewer'].includes(values['--role'])) {
+            usageFailure('--role must be executor or reviewer');
+            return;
+        }
+        result = await awaitOrchestrationDelegationActivation(taskRef, {
+            stage: values['--stage'],
+            round,
+            artifact: values['--artifact'],
+            role: values['--role']
+        }, coreOptions);
+    }
+    else if (intent === 'recover-prepared') {
+        result = recoverPreparedOrchestrationDelegation(taskRef, coreOptions);
+    }
     else if (intent === 'hook-start') {
         const missing = requireValues([
             ...(taskRef === 'auto' ? ['--client'] : []),

package/dist/lib/platform/context.js

@@ -5,6 +5,7 @@ import semver from 'semver';
 import { getPlatformAdapter, registerPlatformAdapter } from './adapters.js';
 import { createGitHubClient, MINIMUM_GITHUB_CLI_VERSION } from './github-client.js';
 import { platformResult } from './types.js';
+const CURRENT_USER_QUERY = 'query { viewer { login } }';
 function findRepoRoot(cwd) {
     try {
         return execFileSync('git', ['rev-parse', '--show-toplevel'], {
@@ -89,18 +90,19 @@ function resolveGitHubContext(options) {
             error: { code: 'UPSTREAM_UNRESOLVED', message: 'Unable to resolve the upstream repository', retryable: false }
         });
     }
-    const user = client.json(['api', 'user'], { cwd });
+    const user = client.json(['api', 'graphql', '-f', `query=${CURRENT_USER_QUERY}`], { cwd });
     if (!user.ok)
         return failure(user.error, upstream);
     const userValue = user.value;
+    const currentUser = userValue?.data?.viewer?.login || null;
     const permissions = client.json(['api', `repos/${upstream}`], { cwd });
     if (!permissions.ok)
         return failure(permissions.error, upstream);
     const permissionValue = permissions.value;
     const values = permissionValue?.permissions || {};
     const capabilities = {
-        authenticated: Boolean(userValue?.login),
-        comment: Boolean(userValue?.login),
+        authenticated: Boolean(currentUser),
+        comment: Boolean(currentUser),
         triage: Boolean(values.triage || values.push || values.admin),
         push: Boolean(values.push || values.admin),
         admin: Boolean(values.admin)
@@ -108,7 +110,7 @@ function resolveGitHubContext(options) {
     const status = Object.values(capabilities).every(Boolean) ? 'no-op' : 'degraded';
     return platformResult(status, {
         changed: false,
-        platform: { type: platform, repository: upstream, currentUser: userValue?.login || null },
+        platform: { type: platform, repository: upstream, currentUser },
         resource: { kind: 'repository', number: null },
         capabilities,
         operations: [{ name: 'resolve', status: 'no-op', reasonCode: null }]

package/dist/lib/platform/github-client.js

@@ -1,7 +1,9 @@
 import process from 'node:process';
 import spawn from 'cross-spawn';
 import semver from 'semver';
-const MINIMUM_GITHUB_CLI_VERSION = '2.16.0';
+// closingIssuesReferences (introduced in gh 2.72.0) is the highest-versioned gh feature
+// the platform layer depends on; see github-release-notes.ts:102.
+const MINIMUM_GITHUB_CLI_VERSION = '2.72.0';
 const GITHUB_CLI_MAX_BUFFER = 64 * 1024 * 1024;
 const ERROR_DETAIL_LIMIT = 4096;
 function boundedFailureDetail(result) {
@@ -76,6 +78,41 @@ function classifyGitHubFailure(result) {
     }
     return { code: 'PLATFORM_REQUEST_FAILED', message: detail || 'GitHub request failed', retryable: false };
 }
+function responseUrl(args) {
+    const endpoint = args.find((arg, index) => index > 0 && !arg.startsWith('-')) || '';
+    return endpoint.startsWith('http') ? endpoint : `https://api.github.com/${endpoint.replace(/^\//, '')}`;
+}
+function parseIncludedResponse(stdout, args) {
+    const statusBlocks = [...stdout.matchAll(/^HTTP\/[^\r\n]+/gim)];
+    const headerStart = statusBlocks.at(-1)?.index;
+    if (headerStart === undefined)
+        return null;
+    const response = stdout.slice(headerStart);
+    const separator = response.match(/\r?\n\r?\n/);
+    if (!separator || separator.index === undefined)
+        return null;
+    const header = response.slice(0, separator.index);
+    const body = response.slice(separator.index + separator[0].length);
+    const status = header.match(/^HTTP\/[^ ]+\s+(\d{3})/mi)?.[1];
+    if (!status)
+        return null;
+    const date = header.match(/^Date:\s*(.+)$/mi)?.[1]?.trim();
+    const links = [...header.matchAll(/^Link:\s*(.+)$/gim)].flatMap((match) => match[1].split(',').map((value) => value.trim()));
+    try {
+        return {
+            value: JSON.parse(body || 'null'),
+            metadata: {
+                status: Number(status),
+                requestUrl: responseUrl(args),
+                ...(date ? { date } : {}),
+                links
+            }
+        };
+    }
+    catch {
+        return null;
+    }
+}
 function createGitHubClient(options = {}) {
     const runner = options.runner || defaultRunner;
     const delays = options.retryDelaysMs || retryDelaysFromEnvironment();
@@ -134,8 +171,24 @@ function createGitHubClient(options = {}) {
                     error: { code: 'INVALID_PLATFORM_RESPONSE', message: 'GitHub returned invalid JSON', retryable: true }
                 };
             }
+        },
+        jsonWithMetadata(args, request = {}) {
+            const includeArgs = args[0] === 'api' && args[1] !== '--include'
+                ? [args[0], '--include', ...args.slice(1)]
+                : args;
+            const result = run(includeArgs, request);
+            if (!result.ok)
+                return result;
+            const parsed = parseIncludedResponse(result.value, args);
+            if (!parsed) {
+                return {
+                    ok: false,
+                    error: { code: 'INVALID_PLATFORM_RESPONSE', message: 'GitHub response metadata or JSON is invalid', retryable: true }
+                };
+            }
+            return { ok: true, value: parsed };
         }
     };
 }
-export { classifyGitHubFailure, createGitHubClient, MINIMUM_GITHUB_CLI_VERSION };
+export { classifyGitHubFailure, createGitHubClient, MINIMUM_GITHUB_CLI_VERSION, parseIncludedResponse };
 //# sourceMappingURL=github-client.js.map

package/dist/lib/process-data/checkpoint.js

@@ -0,0 +1,319 @@
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { verifySnapshot } from './store.js';
+function repositoryKey(repository) {
+    return crypto.createHash('sha256').update(repository).digest('hex').slice(0, 32);
+}
+function checkpointPaths(root, repository) {
+    const directory = path.join(root, 'checkpoints', 'github');
+    const base = path.join(directory, repositoryKey(repository));
+    return { directory, checkpoint: `${base}.json`, lock: `${base}.lock` };
+}
+function processStartToken(pid) {
+    if (process.platform === 'linux') {
+        try {
+            const stat = fs.readFileSync(`/proc/${pid}/stat`, 'utf8');
+            const closing = stat.lastIndexOf(')');
+            const fields = stat.slice(closing + 2).split(' ');
+            return fields[19] ?? null;
+        }
+        catch {
+            return null;
+        }
+    }
+    return pid === process.pid ? `self:${process.pid}` : null;
+}
+function fsyncDirectory(directory) {
+    if (process.platform === 'win32')
+        return;
+    const fd = fs.openSync(directory, 'r');
+    try {
+        fs.fsyncSync(fd);
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+}
+function ensurePrivateDirectory(directory) {
+    const missing = [];
+    let current = path.resolve(directory);
+    while (!fs.existsSync(current)) {
+        missing.push(current);
+        const parent = path.dirname(current);
+        if (parent === current)
+            throw new Error(`cannot create directory tree: ${directory}`);
+        current = parent;
+    }
+    for (const target of missing.reverse()) {
+        fs.mkdirSync(target, { mode: 0o700 });
+        if (process.platform !== 'win32')
+            fs.chmodSync(target, 0o700);
+        fsyncDirectory(path.dirname(target));
+    }
+}
+function writeTemporary(filePath, value) {
+    fs.mkdirSync(path.dirname(filePath), { recursive: true, mode: 0o700 });
+    const temporary = `${filePath}.${process.pid}.${crypto.randomBytes(6).toString('hex')}.tmp`;
+    const fd = fs.openSync(temporary, 'wx', 0o600);
+    try {
+        fs.writeFileSync(fd, `${JSON.stringify(value)}\n`);
+        fs.fsyncSync(fd);
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+    return temporary;
+}
+function validCheckpoint(value, repository) {
+    if (!value || typeof value !== 'object')
+        return false;
+    const checkpoint = value;
+    return checkpoint.schema === 'github-checkpoint/v1'
+        && checkpoint.repository === repository
+        && Boolean(checkpoint.snapshotId)
+        && Boolean(checkpoint.watermark)
+        && Boolean(checkpoint.committedAt)
+        && /^[a-f0-9]{64}$/.test(checkpoint.manifestSha256);
+}
+function checkpointMatchesSnapshot(root, value) {
+    const verified = verifySnapshot(root, value.snapshotId);
+    return verified.ok
+        && verified.manifest?.schema === 'raw-manifest/v2'
+        && verified.manifest.snapshotId === value.snapshotId
+        && verified.manifest.repository === value.repository
+        && verified.manifest.manifestSha256 === value.manifestSha256
+        && verified.manifest.watermark === value.watermark;
+}
+function checkpointState(value) {
+    return { snapshotId: value?.snapshotId ?? null, manifestSha256: value?.manifestSha256 ?? null };
+}
+function readGitHubCheckpoint(root, repository) {
+    const target = checkpointPaths(root, repository).checkpoint;
+    if (!fs.existsSync(target))
+        return { ok: true, value: null };
+    try {
+        const parsed = JSON.parse(fs.readFileSync(target, 'utf8'));
+        const value = {
+            schema: parsed.schema,
+            repository: parsed.repository,
+            snapshotId: parsed.snapshotId,
+            watermark: parsed.watermark,
+            manifestSha256: parsed.manifestSha256,
+            committedAt: parsed.committedAt
+        };
+        if (!validCheckpoint(value, repository)) {
+            return { ok: false, error: { code: 'CHECKPOINT_INVALID', message: 'GitHub checkpoint schema or identity is invalid' } };
+        }
+        return { ok: true, value };
+    }
+    catch {
+        return { ok: false, error: { code: 'CHECKPOINT_INVALID', message: 'GitHub checkpoint is not valid JSON' } };
+    }
+}
+function quarantine(lockPath) {
+    const target = `${lockPath}.orphaned-${Date.now()}-${crypto.randomBytes(4).toString('hex')}`;
+    fs.renameSync(lockPath, target);
+    return target;
+}
+function acquireGitHubCheckpoint(root, repository) {
+    const paths = checkpointPaths(root, repository);
+    ensurePrivateDirectory(paths.directory);
+    const recovery = { recovered: false, quarantined: [] };
+    const owner = {
+        schema: 'checkpoint-owner/v1',
+        ownerId: crypto.randomUUID(),
+        pid: process.pid,
+        host: os.hostname(),
+        processStartToken: processStartToken(process.pid) ?? '',
+        createdAt: new Date().toISOString()
+    };
+    if (!owner.processStartToken) {
+        return { ok: false, error: { code: 'CHECKPOINT_TOPOLOGY_UNSUPPORTED', message: 'Process liveness cannot be verified on this host' } };
+    }
+    let recoveredOwnerId = null;
+    if (fs.existsSync(paths.lock)) {
+        let previous;
+        try {
+            previous = JSON.parse(fs.readFileSync(paths.lock, 'utf8'));
+        }
+        catch {
+            return { ok: false, error: { code: 'CHECKPOINT_RECOVERY_REQUIRED', message: 'Checkpoint lock is unreadable' } };
+        }
+        if (previous.host !== owner.host || !previous.ownerId || !previous.processStartToken) {
+            return { ok: false, error: { code: 'CHECKPOINT_RECOVERY_REQUIRED', message: 'Checkpoint lock owner topology is unknown' } };
+        }
+        const currentToken = processStartToken(previous.pid);
+        if (currentToken && currentToken === previous.processStartToken) {
+            return { ok: false, error: { code: 'CHECKPOINT_BUSY', message: 'Checkpoint is held by a live process' } };
+        }
+        if (process.platform !== 'linux') {
+            return { ok: false, error: { code: 'CHECKPOINT_RECOVERY_REQUIRED', message: 'Checkpoint owner liveness cannot be proven on this host' } };
+        }
+        try {
+            recoveredOwnerId = previous.ownerId;
+            recovery.quarantined.push(quarantine(paths.lock));
+            recovery.recovered = true;
+        }
+        catch {
+            return { ok: false, error: { code: 'CHECKPOINT_RECOVERY_REQUIRED', message: 'Unable to quarantine an orphaned checkpoint lock' } };
+        }
+    }
+    try {
+        const fd = fs.openSync(paths.lock, 'wx', 0o600);
+        try {
+            fs.writeFileSync(fd, `${JSON.stringify(owner)}\n`);
+            fs.fsyncSync(fd);
+        }
+        finally {
+            fs.closeSync(fd);
+        }
+        fsyncDirectory(paths.directory);
+    }
+    catch (error) {
+        if (error.code === 'EEXIST') {
+            return { ok: false, error: { code: 'CHECKPOINT_BUSY', message: 'Checkpoint lock was acquired by another process' } };
+        }
+        return { ok: false, error: { code: 'CHECKPOINT_LOCK_FAILED', message: String(error) } };
+    }
+    const releaseOwnedLock = () => {
+        try {
+            fs.unlinkSync(paths.lock);
+            fsyncDirectory(paths.directory);
+        }
+        catch {
+            // Preserve the original recovery error; a remaining lock will fail closed next time.
+        }
+    };
+    const beforeResult = readGitHubCheckpoint(root, repository);
+    if (!beforeResult.ok) {
+        releaseOwnedLock();
+        return beforeResult;
+    }
+    let checkpointBefore = beforeResult.value;
+    const temporaryCandidates = fs.readdirSync(paths.directory)
+        .filter((entry) => entry.startsWith(path.basename(paths.checkpoint) + '.') && entry.endsWith('.tmp'))
+        .map((entry) => path.join(paths.directory, entry));
+    if (temporaryCandidates.length > 1) {
+        releaseOwnedLock();
+        return { ok: false, error: { code: 'CHECKPOINT_RECOVERY_REQUIRED', message: 'Multiple checkpoint recovery candidates exist' } };
+    }
+    if (temporaryCandidates.length === 1) {
+        const candidate = temporaryCandidates[0];
+        try {
+            const parsed = JSON.parse(fs.readFileSync(candidate, 'utf8'));
+            const isCandidate = parsed && typeof parsed === 'object' && 'candidateSchema' in parsed
+                && parsed.candidateSchema === 'github-checkpoint-candidate/v1';
+            if (isCandidate) {
+                const candidateValue = parsed;
+                const value = candidateValue;
+                const expected = checkpointState(checkpointBefore);
+                const candidateExpected = candidateValue.expectedOld;
+                if (!recoveredOwnerId || candidateValue.ownerId !== recoveredOwnerId) {
+                    recovery.quarantined.push(quarantine(candidate));
+                    releaseOwnedLock();
+                    return { ok: false, error: { code: 'CHECKPOINT_RECOVERY_REQUIRED', message: 'Checkpoint candidate owner proof does not match the recovered lock owner' } };
+                }
+                if (!validCheckpoint(value, repository)
+                    || candidateExpected?.snapshotId !== expected.snapshotId
+                    || candidateExpected?.manifestSha256 !== expected.manifestSha256) {
+                    releaseOwnedLock();
+                    return { ok: false, error: { code: 'CHECKPOINT_RECOVERY_REQUIRED', message: 'Checkpoint candidate does not match the current head' } };
+                }
+                if (!checkpointMatchesSnapshot(root, value)) {
+                    recovery.quarantined.push(quarantine(candidate));
+                    releaseOwnedLock();
+                    return { ok: false, error: { code: 'CHECKPOINT_RECOVERY_REQUIRED', message: 'Checkpoint candidate snapshot failed full verification' } };
+                }
+                if (process.platform === 'win32' && checkpointBefore) {
+                    releaseOwnedLock();
+                    return { ok: false, error: { code: 'CHECKPOINT_TOPOLOGY_UNSUPPORTED', message: 'Checkpoint replacement durability cannot be proven on this host' } };
+                }
+                fs.renameSync(candidate, paths.checkpoint);
+                recovery.recovered = true;
+                fsyncDirectory(paths.directory);
+                const recovered = readGitHubCheckpoint(root, repository);
+                if (!recovered.ok) {
+                    releaseOwnedLock();
+                    return recovered;
+                }
+                checkpointBefore = recovered.value;
+            }
+            else {
+                recovery.quarantined.push(quarantine(candidate));
+                releaseOwnedLock();
+                return { ok: false, error: { code: 'CHECKPOINT_RECOVERY_REQUIRED', message: 'Checkpoint candidate lacks owner proof' } };
+            }
+        }
+        catch {
+            recovery.quarantined.push(quarantine(candidate));
+        }
+    }
+    return { ok: true, value: { paths, repository, owner, recovery, expectedOld: checkpointBefore } };
+}
+function commitGitHubCheckpoint(lease, value) {
+    try {
+        const current = JSON.parse(fs.readFileSync(lease.paths.lock, 'utf8'));
+        if (current.ownerId !== lease.owner.ownerId) {
+            return { ok: false, error: { code: 'CHECKPOINT_OWNER_MISMATCH', message: 'Checkpoint lock ownership changed' } };
+        }
+        if (value.repository !== lease.repository || !validCheckpoint(value, lease.repository)) {
+            return { ok: false, error: { code: 'CHECKPOINT_INVALID', message: 'Checkpoint value is invalid' } };
+        }
+        const root = path.dirname(path.dirname(lease.paths.directory));
+        if (!checkpointMatchesSnapshot(root, value)) {
+            return { ok: false, error: { code: 'CHECKPOINT_INVALID', message: 'Checkpoint snapshot does not match a verified v2 manifest' } };
+        }
+        const currentCheckpoint = readGitHubCheckpoint(root, lease.repository);
+        if (!currentCheckpoint.ok)
+            return currentCheckpoint;
+        if (checkpointState(currentCheckpoint.value).snapshotId !== checkpointState(lease.expectedOld).snapshotId
+            || checkpointState(currentCheckpoint.value).manifestSha256 !== checkpointState(lease.expectedOld).manifestSha256) {
+            return { ok: false, error: { code: 'CHECKPOINT_CONFLICT', message: 'Checkpoint head changed before commit' } };
+        }
+        const candidate = {
+            ...value,
+            candidateSchema: 'github-checkpoint-candidate/v1',
+            ownerId: lease.owner.ownerId,
+            expectedOld: checkpointState(lease.expectedOld)
+        };
+        const temporary = writeTemporary(lease.paths.checkpoint, candidate);
+        const rechecked = readGitHubCheckpoint(root, lease.repository);
+        if (!rechecked.ok) {
+            fs.unlinkSync(temporary);
+            return rechecked;
+        }
+        if (checkpointState(rechecked.value).snapshotId !== checkpointState(lease.expectedOld).snapshotId
+            || checkpointState(rechecked.value).manifestSha256 !== checkpointState(lease.expectedOld).manifestSha256) {
+            fs.unlinkSync(temporary);
+            return { ok: false, error: { code: 'CHECKPOINT_CONFLICT', message: 'Checkpoint head changed during commit' } };
+        }
+        if (process.platform === 'win32' && fs.existsSync(lease.paths.checkpoint)) {
+            fs.unlinkSync(temporary);
+            return { ok: false, error: { code: 'CHECKPOINT_TOPOLOGY_UNSUPPORTED', message: 'Checkpoint replacement durability cannot be proven on this host' } };
+        }
+        fs.renameSync(temporary, lease.paths.checkpoint);
+        if (process.platform !== 'win32')
+            fs.chmodSync(lease.paths.checkpoint, 0o600);
+        fsyncDirectory(lease.paths.directory);
+        return { ok: true, value: undefined };
+    }
+    catch (error) {
+        return { ok: false, error: { code: 'CHECKPOINT_COMMIT_FAILED', message: String(error) } };
+    }
+}
+function releaseGitHubCheckpoint(lease) {
+    try {
+        const current = JSON.parse(fs.readFileSync(lease.paths.lock, 'utf8'));
+        if (current.ownerId === lease.owner.ownerId) {
+            fs.unlinkSync(lease.paths.lock);
+            fsyncDirectory(lease.paths.directory);
+        }
+    }
+    catch {
+        // The next invocation will fail closed and report recovery if the lock remains.
+    }
+}
+export { acquireGitHubCheckpoint, checkpointPaths, commitGitHubCheckpoint, processStartToken, readGitHubCheckpoint, releaseGitHubCheckpoint };
+//# sourceMappingURL=checkpoint.js.map