@fitlab-ai/agent-infra 0.9.5 → 0.9.7

package/lib/internal/task-create.ts

@@ -1,15 +1,15 @@
 import fs from 'node:fs';
 import path from 'node:path';
 
-import { requestSandboxTaskCreate } from '../sandbox/control/client.ts';
+import { requestSandboxTaskCreate, SandboxControlClientError } from '../sandbox/control/client.ts';
 import { SANDBOX_CONTROL_MAX_BYTES } from '../sandbox/control/protocol.ts';
 import { validateTaskCreateCandidate } from '../task/create.ts';
 import { createTask, type TaskCreateResult } from '../task/create-service.ts';
 
-function failed(code: string, message: string): TaskCreateResult {
+function failed(code: string, message: string, retryable = false): TaskCreateResult {
   return {
-    status: 'failed', changed: false, task: { id: null, shortId: null }, issue: null,
-    operations: [], warnings: [], error: { code, message, retryable: false }
+    status: retryable ? 'blocked' : 'failed', changed: false, task: { id: null, shortId: null }, issue: null,
+    operations: [], warnings: [], error: { code, message, retryable }
   };
 }
 
@@ -33,6 +33,14 @@ function taskCreate(args: string[]): void {
     const candidate = validateTaskCreateCandidate(JSON.parse(fs.readFileSync(inputPath, 'utf8')));
     if (process.env.AGENT_INFRA_CONTROL_TOKEN) {
       const response = requestSandboxTaskCreate({ candidate });
+      if (response.phase === 'rejected') {
+        output(failed(
+          response.error?.code ?? 'SANDBOX_CONTROL_REJECTED',
+          response.error?.message ?? response.stderr,
+          response.error?.retryable ?? false
+        ));
+        return;
+      }
       process.stdout.write(response.stdout);
       process.stderr.write(response.stderr);
       process.exitCode = response.exitCode;
@@ -40,6 +48,10 @@ function taskCreate(args: string[]): void {
     }
     output(createTask(candidate, { repoRoot: process.cwd() }));
   } catch (error) {
+    if (error instanceof SandboxControlClientError) {
+      output(failed(error.detail.code, error.detail.message, error.detail.retryable));
+      return;
+    }
     const message = error instanceof Error ? error.message : String(error);
     const code = /^([A-Z][A-Z0-9_]+)/.exec(message)?.[1] ?? 'TASK_CREATE_INPUT_INVALID';
     output(failed(code, message));

package/lib/internal/task-orchestration.ts

@@ -4,13 +4,15 @@ import {
   activateMatchingOrchestrationDelegation,
   activateOrchestrationDelegation,
   advanceOrchestration,
+  awaitOrchestrationDelegationActivation,
   beginCommitIntent,
   beginOrResumeOrchestration,
   checkpointCommitIntent,
   completeCommitIntent,
+  dispatchOrchestrationDelegation,
   pauseOrchestration,
-  prepareOrchestrationDelegation,
   recoverCommitIntent,
+  recoverPreparedOrchestrationDelegation,
   routeOrchestration,
   sealMatchingOrchestrationDelegation,
   sealOrchestrationDelegation,
@@ -19,10 +21,11 @@ import {
   statusOrchestration,
   terminateCommitAttempt
 } from '../task/orchestration.ts';
+import { prepareCodexOrchestrationDelegation } from '../task/codex-orchestration.ts';
 import { isAgentClientId } from '../agent-clients/types.ts';
 import type { AgentClientId } from '../agent-clients/types.ts';
 
-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: string): void {
   process.stdout.write(`${JSON.stringify({
@@ -33,7 +36,7 @@ function usageFailure(message: string): void {
   process.exitCode = 2;
 }
 
-function taskOrchestration(args: string[] = []): void {
+async function taskOrchestration(args: string[] = []): Promise<void> {
   if (args[0] === '--help' || args[0] === '-h') {
     process.stdout.write(USAGE);
     return;
@@ -44,7 +47,8 @@ function taskOrchestration(args: string[] = []): void {
   }
   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}'`);
@@ -64,7 +68,9 @@ function taskOrchestration(args: string[] = []): void {
     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',
@@ -212,11 +218,32 @@ function taskOrchestration(args: string[] = []): void {
   } else if (intent === 'prepare') {
     const missing = requireValues(['--client']);
     if (missing) { usageFailure(`intent 'prepare' requires '${missing}'`); return; }
-    result = prepareOrchestrationDelegation(taskRef!, {
+    result = await prepareCodexOrchestrationDelegation(taskRef!, {
       client: values['--client'] as AgentClientId,
       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'] as Parameters<typeof awaitOrchestrationDelegationActivation>[1]['stage'],
+      round,
+      artifact: values['--artifact']!,
+      role: values['--role'] as 'executor' | 'reviewer'
     }, coreOptions);
+  } else if (intent === 'recover-prepared') {
+    result = recoverPreparedOrchestrationDelegation(taskRef!, coreOptions);
   } else if (intent === 'hook-start') {
     const missing = requireValues([
       ...(taskRef === 'auto' ? ['--client'] : []),

package/lib/platform/context.ts

@@ -20,6 +20,8 @@ type ContextOptions = {
   platformType?: string;
 };
 
+const CURRENT_USER_QUERY = 'query { viewer { login } }';
+
 function findRepoRoot(cwd: string): string {
   try {
     return execFileSync('git', ['rev-parse', '--show-toplevel'], {
@@ -105,16 +107,17 @@ function resolveGitHubContext(options: ContextOptions & { cwd: string }): Platfo
       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 as { login?: string } | null;
+  const userValue = user.value as { data?: { viewer?: { login?: string } } } | null;
+  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 as { permissions?: Record<string, boolean> } | null;
   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)
@@ -122,7 +125,7 @@ function resolveGitHubContext(options: ContextOptions & { cwd: string }): Platfo
   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/lib/platform/github-client.ts

@@ -10,10 +10,18 @@ type RunOptions = { cwd?: string; input?: string };
 type Runner = (args: string[], options: RunOptions) => RunResult;
 type RequestOptions = RunOptions & { method?: 'GET' | 'PATCH' | 'POST' | 'DELETE' };
 type ClientResult<T> = { ok: true; value: T } | { ok: false; error: PlatformError };
+type ResponseMetadata = {
+  status: number;
+  requestUrl: string;
+  date?: string;
+  links: string[];
+};
+type JsonResponse<T> = { value: T; metadata: ResponseMetadata };
 
 type GitHubClient = {
   version(options?: RunOptions): ClientResult<string>;
   json<T = unknown>(args: string[], options?: RequestOptions): ClientResult<T>;
+  jsonWithMetadata?<T = unknown>(args: string[], options?: RequestOptions): ClientResult<JsonResponse<T>>;
   text(args: string[], options?: RequestOptions): ClientResult<string>;
 };
 
@@ -23,7 +31,9 @@ type ClientOptions = {
   sleep?: (delayMs: number) => void;
 };
 
-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;
 
@@ -101,6 +111,39 @@ function classifyGitHubFailure(result: RunResult): PlatformError {
   return { code: 'PLATFORM_REQUEST_FAILED', message: detail || 'GitHub request failed', retryable: false };
 }
 
+function responseUrl(args: string[]): string {
+  const endpoint = args.find((arg, index) => index > 0 && !arg.startsWith('-')) || '';
+  return endpoint.startsWith('http') ? endpoint : `https://api.github.com/${endpoint.replace(/^\//, '')}`;
+}
+
+function parseIncludedResponse<T>(stdout: string, args: string[]): JsonResponse<T> | null {
+  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') as T,
+      metadata: {
+        status: Number(status),
+        requestUrl: responseUrl(args),
+        ...(date ? { date } : {}),
+        links
+      }
+    };
+  } catch {
+    return null;
+  }
+}
+
 function createGitHubClient(options: ClientOptions = {}): GitHubClient {
   const runner = options.runner || defaultRunner;
   const delays = options.retryDelaysMs || retryDelaysFromEnvironment();
@@ -156,9 +199,24 @@ function createGitHubClient(options: ClientOptions = {}): GitHubClient {
           error: { code: 'INVALID_PLATFORM_RESPONSE', message: 'GitHub returned invalid JSON', retryable: true }
         };
       }
+    },
+    jsonWithMetadata<T>(args: string[], request: RequestOptions = {}): ClientResult<JsonResponse<T>> {
+      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<T>(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 type { ClientResult, GitHubClient, RequestOptions, RunOptions, RunResult, Runner };
+export { classifyGitHubFailure, createGitHubClient, MINIMUM_GITHUB_CLI_VERSION, parseIncludedResponse };
+export type { ClientResult, GitHubClient, JsonResponse, RequestOptions, ResponseMetadata, RunOptions, RunResult, Runner };

package/lib/platform/issue-comments.ts

@@ -39,6 +39,7 @@ const ARTIFACT_TITLES: Record<string, string> = {
   code: '实现报告',
   'review-code': '代码审查',
   'manual-validation': '人工验证报告',
+  'validation-run': '验证运行证据',
   'pr-review': 'PR 审查报告'
 };
 
@@ -75,7 +76,7 @@ function renderTaskComment(content: string, taskId: string, agent: string): stri
 
 function artifactIdentity(artifact: string): { stem: string; title: string } {
   const stem = path.basename(artifact, '.md');
-  const match = stem.match(/^(analysis|review-analysis|plan|review-plan|code|review-code|manual-validation|pr-review)(?:-r(\d+))?$/);
+  const match = stem.match(/^(analysis|review-analysis|plan|review-plan|code|review-code|manual-validation|validation-run|pr-review)(?:-r(\d+))?$/);
   if (!match) throw new Error(`unsupported artifact '${artifact}'`);
   const base = ARTIFACT_TITLES[match[1]!]!;
   const round = match[2] ? Number(match[2]) : 1;

package/lib/process-data/checkpoint.ts

@@ -0,0 +1,335 @@
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+import { verifySnapshot } from './store.ts';
+import type { GitHubCheckpoint, CheckpointOwner, ProcessResult, RecoveryReport } from './types.ts';
+
+type CheckpointPaths = { directory: string; checkpoint: string; lock: string };
+type CheckpointCandidate = {
+  schema: 'github-checkpoint/v1';
+  candidateSchema: 'github-checkpoint-candidate/v1';
+  ownerId: string;
+  expectedOld: { snapshotId: string | null; manifestSha256: string | null };
+  repository: string;
+  snapshotId: string;
+  watermark: string;
+  manifestSha256: string;
+  committedAt: string;
+};
+type CheckpointLease = {
+  paths: CheckpointPaths;
+  repository: string;
+  owner: CheckpointOwner;
+  recovery: RecoveryReport;
+  expectedOld: GitHubCheckpoint | null;
+};
+
+function repositoryKey(repository: string): string {
+  return crypto.createHash('sha256').update(repository).digest('hex').slice(0, 32);
+}
+
+function checkpointPaths(root: string, repository: string): CheckpointPaths {
+  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: number): string | null {
+  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: string): void {
+  if (process.platform === 'win32') return;
+  const fd = fs.openSync(directory, 'r');
+  try { fs.fsyncSync(fd); } finally { fs.closeSync(fd); }
+}
+
+function ensurePrivateDirectory(directory: string): void {
+  const missing: string[] = [];
+  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: string, value: unknown): string {
+  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: unknown, repository: string): value is GitHubCheckpoint {
+  if (!value || typeof value !== 'object') return false;
+  const checkpoint = value as GitHubCheckpoint;
+  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: string, value: GitHubCheckpoint): boolean {
+  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: GitHubCheckpoint | null): { snapshotId: string | null; manifestSha256: string | null } {
+  return { snapshotId: value?.snapshotId ?? null, manifestSha256: value?.manifestSha256 ?? null };
+}
+
+function readGitHubCheckpoint(root: string, repository: string): ProcessResult<GitHubCheckpoint | null> {
+  const target = checkpointPaths(root, repository).checkpoint;
+  if (!fs.existsSync(target)) return { ok: true, value: null };
+  try {
+    const parsed = JSON.parse(fs.readFileSync(target, 'utf8')) as GitHubCheckpoint;
+    const value: GitHubCheckpoint = {
+      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: string): string {
+  const target = `${lockPath}.orphaned-${Date.now()}-${crypto.randomBytes(4).toString('hex')}`;
+  fs.renameSync(lockPath, target);
+  return target;
+}
+
+function acquireGitHubCheckpoint(root: string, repository: string): ProcessResult<CheckpointLease> {
+  const paths = checkpointPaths(root, repository);
+  ensurePrivateDirectory(paths.directory);
+  const recovery: RecoveryReport = { recovered: false, quarantined: [] };
+  const owner: CheckpointOwner = {
+    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: string | null = null;
+  if (fs.existsSync(paths.lock)) {
+    let previous: CheckpointOwner;
+    try {
+      previous = JSON.parse(fs.readFileSync(paths.lock, 'utf8')) as CheckpointOwner;
+    } 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 as NodeJS.ErrnoException).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')) as CheckpointCandidate | GitHubCheckpoint;
+      const isCandidate = parsed && typeof parsed === 'object' && 'candidateSchema' in parsed
+        && parsed.candidateSchema === 'github-checkpoint-candidate/v1';
+      if (isCandidate) {
+        const candidateValue = parsed as CheckpointCandidate;
+        const value: GitHubCheckpoint = 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: CheckpointLease, value: GitHubCheckpoint): ProcessResult<void> {
+  try {
+    const current = JSON.parse(fs.readFileSync(lease.paths.lock, 'utf8')) as CheckpointOwner;
+    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: CheckpointCandidate = {
+      ...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: CheckpointLease): void {
+  try {
+    const current = JSON.parse(fs.readFileSync(lease.paths.lock, 'utf8')) as CheckpointOwner;
+    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
+};
+export type { CheckpointLease, CheckpointPaths };