pi-extended-teams 2.2.9 → 2.3.0

package/src/results/durable-json.ts

@@ -0,0 +1,29 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+
+function syncPath(file: string): void {
+  const descriptor = fs.openSync(file, "r");
+  try { fs.fsyncSync(descriptor); }
+  finally { fs.closeSync(descriptor); }
+}
+
+export function syncPathAndParents(file: string): void {
+  for (let current = file; ; current = path.dirname(current)) {
+    syncPath(current);
+    if (path.dirname(current) === current) return;
+  }
+}
+
+export function writeJsonDurably(file: string, value: unknown): void {
+  const temporary = path.join(path.dirname(file), `.${path.basename(file)}.${crypto.randomUUID()}.tmp`);
+  try {
+    fs.writeFileSync(temporary, JSON.stringify(value, null, 2), { flag: "wx", mode: 0o600 });
+    syncPath(temporary);
+    fs.renameSync(temporary, file);
+    syncPathAndParents(path.dirname(file));
+  } catch (error) {
+    try { fs.unlinkSync(temporary); } catch {}
+    throw error;
+  }
+}

package/src/results/repair-policy.ts

@@ -0,0 +1,24 @@
+import { Type, type Static } from "@sinclair/typebox";
+import { Value } from "@sinclair/typebox/value";
+
+export const RepairPolicySchema = Type.Object({
+  maxAttempts: Type.Integer({ minimum: 0, maximum: 5, description: "Maximum additional repair attempts after initial verification. Zero disables automatic repair. Only the lead or a trusted integration may authorize this policy." }),
+}, { additionalProperties: false });
+export type RepairPolicy = Static<typeof RepairPolicySchema>;
+export type RepairState = "pending" | "not-needed" | "requested" | "repaired" | "exhausted" | "cancelled" | "declined" | "blocked";
+export interface RepairResult {
+  controllerId: string;
+  journalPath?: string;
+  state: RepairState;
+  attemptsUsed?: number;
+  maxAttempts?: number;
+  requestIds?: string[];
+  outcome?: "blocked";
+  error?: string;
+}
+
+export function normalizeRepairPolicy(value: unknown): RepairPolicy | undefined {
+  if (value === undefined) return undefined;
+  if (!Value.Check(RepairPolicySchema, value)) throw new Error("Invalid repair policy.");
+  return value.maxAttempts ? structuredClone(value) : undefined;
+}

package/src/results/report-result.ts

@@ -0,0 +1,77 @@
+import { Type, type Static } from "@sinclair/typebox";
+import { Value } from "@sinclair/typebox/value";
+import type { RepairResult } from "./repair-policy";
+
+const reference = Type.String({ minLength: 1 });
+
+export const ReportedTaskDetailsSchema = Type.Object({
+  outcome: Type.Optional(Type.Union([
+    Type.Literal("succeeded"), Type.Literal("blocked"), Type.Literal("failed"), Type.Literal("cancelled"),
+  ], { description: "Reported task outcome, separate from clean exit, verification, and lead acceptance. Omit when unspecified." })),
+  changedPaths: Type.Optional(Type.Array(reference)),
+  inspectedEvidence: Type.Optional(Type.Array(Type.String({ minLength: 1, maxLength: 2048, pattern: "\\S" }), { maxItems: 128 })),
+  artifacts: Type.Optional(Type.Array(Type.Object({
+    path: reference,
+    label: Type.Optional(Type.String()),
+  }, { additionalProperties: false }))),
+  findings: Type.Optional(Type.Array(Type.Object({
+    id: reference,
+    text: reference,
+    evidence: Type.Array(reference),
+  }, { additionalProperties: false }))),
+  questions: Type.Optional(Type.Array(reference)),
+}, { additionalProperties: false });
+
+export type ReportedTaskDetails = Static<typeof ReportedTaskDetailsSchema>;
+export type TaskOutcome = NonNullable<ReportedTaskDetails["outcome"]>;
+export type VerificationState = "not-requested" | "pending" | "passed" | "failed" | "stale";
+
+export interface ReportResult extends ReportedTaskDetails {
+  version: 1;
+  taskId: string;
+  runId: string;
+  reportId: string;
+  checkpointId?: string;
+  verification: { state: VerificationState; checkIds?: string[]; error?: string };
+  acceptance: { state: "pending" | "accepted" | "rejected"; decidedAt?: number; reason?: string };
+  repair?: RepairResult;
+}
+
+export function effectiveTaskOutcome(result: ReportResult): TaskOutcome | undefined {
+  return result.repair?.outcome ?? result.outcome;
+}
+
+export function normalizeReportedTaskDetails(value: unknown): ReportedTaskDetails {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    throw new Error("Reported task details must be an object.");
+  }
+  const input = value as Record<string, unknown>;
+  const details = Object.fromEntries(Object.keys(ReportedTaskDetailsSchema.properties)
+    .filter(key => input[key] !== undefined)
+    .map(key => [key, input[key]]));
+  if (!Value.Check(ReportedTaskDetailsSchema, details)) throw new Error("Invalid reported task details.");
+  const findingIds = details.findings?.map(finding => finding.id) ?? [];
+  if (new Set(findingIds).size !== findingIds.length) throw new Error("Reported finding IDs must be unique.");
+  return structuredClone(details);
+}
+
+export function createReportResult(
+  teamName: string,
+  agentName: string,
+  runId: string,
+  reported: ReportedTaskDetails,
+): ReportResult {
+  if (![teamName, agentName, runId].every(value => typeof value === "string" && value.length > 0)) {
+    throw new Error("Report identity requires the bound team, agent and lifecycle run.");
+  }
+  const identity = [teamName, agentName, runId].map(encodeURIComponent).join(":");
+  return {
+    ...normalizeReportedTaskDetails(reported),
+    version: 1,
+    taskId: `task:${identity}`,
+    runId,
+    reportId: `report:${identity}`,
+    verification: { state: "not-requested" },
+    acceptance: { state: "pending" },
+  };
+}

package/src/results/source-identity.ts

@@ -0,0 +1,115 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { Type, type Static } from "@sinclair/typebox";
+
+export const SourceIdentitySchema = Type.Object({
+  version: Type.Literal(1),
+  cwd: Type.String({ minLength: 1 }),
+  repositoryRoot: Type.String({ minLength: 1 }),
+  head: Type.Union([Type.String({ minLength: 1 }), Type.Null()]),
+  fingerprint: Type.String({ pattern: "^[a-f0-9]{64}$" }),
+  inputs: Type.Array(Type.String({ minLength: 1 }), { minItems: 1 }),
+  fileCount: Type.Integer({ minimum: 0 }),
+}, { additionalProperties: false });
+export type SourceIdentity = Static<typeof SourceIdentitySchema>;
+const execute = promisify(execFile);
+
+function relativeInput(root: string, absolute: string): string {
+  const relative = path.relative(root, absolute);
+  if (relative === ".." || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) {
+    throw new Error(`Source input is outside the repository: ${absolute}`);
+  }
+  return relative.split(path.sep).join("/") || ".";
+}
+
+function fileStamp(stat: fs.BigIntStats): string {
+  return [stat.dev, stat.ino, stat.mode, stat.size, stat.mtimeNs, stat.ctimeNs].join(":");
+}
+
+export async function captureSourceIdentity(
+  cwd: string,
+  inputs?: string[],
+  signal?: AbortSignal,
+): Promise<SourceIdentity> {
+  signal?.throwIfAborted();
+  if (inputs !== undefined && (!Array.isArray(inputs) || !inputs.length
+    || inputs.some(input => typeof input !== "string" || !input.length || input.includes("\0")))) {
+    throw new Error("Source input scope must contain nonempty literal paths.");
+  }
+  const canonicalCwd = await fs.promises.realpath(cwd);
+  const git = async (args: string[], directory = canonicalCwd): Promise<string> => {
+    const { stdout } = await execute("git", ["-c", "core.fsmonitor=false", ...args], {
+      cwd: directory, encoding: "buffer", signal, timeout: 10_000, maxBuffer: 32 * 1024 * 1024,
+      env: { ...process.env, GIT_OPTIONAL_LOCKS: "0" },
+    });
+    const text = stdout.toString("utf8");
+    if (!Buffer.from(text).equals(stdout)) throw new Error("Source identity requires UTF-8 repository paths.");
+    return text;
+  };
+  const repositoryRoot = await fs.promises.realpath((await git(["rev-parse", "--show-toplevel"])).replace(/\n$/, ""));
+  const scopes = [...new Set(inputs?.map(input => relativeInput(repositoryRoot, path.resolve(canonicalCwd, input))) ?? ["."])].sort();
+  const selected = (file: string) => scopes.some(scope => scope === "." || file === scope || file.startsWith(`${scope}/`));
+  const index = await git(["ls-files", "--stage", "-z"], repositoryRoot);
+  const untracked = await git(["ls-files", "--others", "--exclude-standard", "-z"], repositoryRoot);
+  const entries = index.split("\0").filter(Boolean).map(entry => {
+    const separator = entry.indexOf("\t");
+    if (separator < 0) throw new Error("Invalid Git index listing.");
+    return { file: entry.slice(separator + 1), index: entry.slice(0, separator) };
+  });
+  const files = [...new Set([...entries.map(entry => entry.file), ...untracked.split("\0").filter(Boolean)])].filter(selected).sort();
+  for (const scope of scopes) {
+    if (inputs && !files.some(file => scope === "." || file === scope || file.startsWith(`${scope}/`))) {
+      throw new Error(`No tracked or nonignored source inputs captured for scope: ${scope}`);
+    }
+  }
+  let head: string | null;
+  try { head = (await git(["rev-parse", "--verify", "--quiet", "HEAD"], repositoryRoot)).trim(); }
+  catch (error) {
+    if (typeof error !== "object" || error === null || Reflect.get(error, "code") !== 1) throw error;
+    head = null;
+  }
+  const digest = crypto.createHash("sha256");
+  digest.update(JSON.stringify({ version: 1, head, inputs: scopes, index: entries.filter(entry => selected(entry.file)) }));
+  const captured = new Set(files);
+  for (const file of files) {
+    signal?.throwIfAborted();
+    const absolute = path.resolve(repositoryRoot, file);
+    relativeInput(repositoryRoot, absolute);
+    let before: fs.BigIntStats;
+    try { before = await fs.promises.lstat(absolute, { bigint: true }); }
+    catch (error) {
+      if (typeof error !== "object" || error === null || Reflect.get(error, "code") !== "ENOENT") throw error;
+      digest.update(JSON.stringify([file, "missing"]));
+      continue;
+    }
+    const realPath = await fs.promises.realpath(absolute);
+    const target = relativeInput(repositoryRoot, realPath);
+    if (before.isSymbolicLink()) {
+      if (!captured.has(target) || !(await fs.promises.stat(realPath)).isFile()) {
+        throw new Error(`Symlink target is not a captured regular source file: ${file}`);
+      }
+      digest.update(JSON.stringify([file, "symlink", await fs.promises.readlink(absolute)]));
+    } else {
+      if (!before.isFile() || realPath !== absolute) throw new Error(`Unsupported source input type or symlink ancestor: ${file}`);
+      const content = crypto.createHash("sha256");
+      for await (const chunk of fs.createReadStream(absolute, { signal })) content.update(chunk);
+      digest.update(JSON.stringify([file, Number(before.mode & 0o777n), content.digest("hex")]));
+    }
+    if (fileStamp(before) !== fileStamp(await fs.promises.lstat(absolute, { bigint: true }))) {
+      throw new Error(`Source input changed during capture: ${file}`);
+    }
+  }
+  if (index !== await git(["ls-files", "--stage", "-z"], repositoryRoot)
+    || untracked !== await git(["ls-files", "--others", "--exclude-standard", "-z"], repositoryRoot)) {
+    throw new Error("Source input inventory changed during capture.");
+  }
+  return { version: 1, cwd: canonicalCwd, repositoryRoot, head, fingerprint: digest.digest("hex"), inputs: scopes, fileCount: files.length };
+}
+
+export function sameTestedSource(before: SourceIdentity, after: SourceIdentity): boolean {
+  return before.version === after.version && before.cwd === after.cwd
+    && before.repositoryRoot === after.repositoryRoot && before.fingerprint === after.fingerprint;
+}

package/src/results/specialist-checkpoint.ts

@@ -0,0 +1,227 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { isDeepStrictEqual } from "node:util";
+import { Type, type Static } from "@sinclair/typebox";
+import { Value } from "@sinclair/typebox/value";
+import { checkpointFilesDir } from "../utils/paths";
+import { FAVORITE_MODEL_SLOTS } from "../utils/settings";
+import { withLock } from "../utils/lock";
+import { normalizeCheckpointPolicy, StoredCheckpointPolicySchema } from "./checkpoint-policy";
+import { SourceIdentitySchema } from "./source-identity";
+import { createReportResult, type ReportResult } from "./report-result";
+import { syncPathAndParents, writeJsonDurably } from "./durable-json";
+
+export const MAX_CHECKPOINT_BYTES = 65_536;
+export const MAX_CHECKPOINT_REPORT_PATH_LENGTH = 2048;
+const day = 86_400_000;
+const text = (maxLength = 4096) => Type.String({ minLength: 1, maxLength });
+const identity = Type.String({ pattern: "^checkpoint:[a-f0-9]{64}$", maxLength: 75 });
+const reportIdentity = Type.String({ pattern: "^report:[^:]+:[^:]+:[^:]+$", maxLength: 2048 });
+const time = Type.Integer({ minimum: 0, maximum: Number.MAX_SAFE_INTEGER });
+const authorSchema = Type.Object({
+  teamName: text(256), agentName: text(256), runId: text(256),
+  modelSlot: Type.Union(FAVORITE_MODEL_SLOTS.map(slot => Type.Literal(slot))),
+}, { additionalProperties: false });
+export type CheckpointAuthor = Static<typeof authorSchema>;
+const recordSchema = Type.Object({
+  version: Type.Literal(1), state: Type.Literal("ready"), id: identity,
+  author: authorSchema, createdAt: time, expiresAt: time, parentId: Type.Optional(identity),
+  assignment: Type.Object({ original: text(16_384), current: text(16_384) }, { additionalProperties: false }),
+  policy: StoredCheckpointPolicySchema, reportId: reportIdentity,
+  reports: Type.Array(Type.Object({
+    id: reportIdentity, path: text(MAX_CHECKPOINT_REPORT_PATH_LENGTH),
+    source: Type.Object({ before: SourceIdentitySchema, after: SourceIdentitySchema }, { additionalProperties: false }),
+    verification: Type.Union((["not-requested", "pending", "passed", "failed", "stale"] as const).map(state => Type.Literal(state))),
+    acceptance: Type.Union((["pending", "accepted", "rejected"] as const).map(state => Type.Literal(state))),
+    leadDecisions: Type.Optional(Type.Array(text(), { maxItems: 32 })),
+  }, { additionalProperties: false }), { minItems: 1, maxItems: 16 }),
+  findings: Type.Array(Type.Object({
+    id: text(256), text: text(), evidence: Type.Array(text(2048), { maxItems: 32 }), reportId: reportIdentity,
+  }, { additionalProperties: false }), { maxItems: 100 }),
+  inspectedEvidence: Type.Array(Type.Object({ reference: text(2048), reportId: reportIdentity }, { additionalProperties: false }), { maxItems: 128 }),
+  questions: Type.Array(text(), { maxItems: 32 }),
+}, { additionalProperties: false });
+const retirementSchema = Type.Object({
+  version: Type.Literal(1), id: identity, retiredAt: time,
+  state: Type.Union([Type.Literal("deleted"), Type.Literal("expired")]),
+}, { additionalProperties: false });
+export type SpecialistCheckpoint = Static<typeof recordSchema>;
+export type RetiredCheckpoint = Static<typeof retirementSchema>;
+export type CheckpointRecord = SpecialistCheckpoint | RetiredCheckpoint;
+
+const currentReportSchema = Type.Pick(recordSchema, ["findings", "inspectedEvidence", "questions"]);
+
+export function checkpointReportPayload(result: ReportResult): Static<typeof currentReportSchema> {
+  const payload = {
+    findings: (result.findings ?? []).map(finding => ({ ...finding, reportId: result.reportId })),
+    inspectedEvidence: [...new Set(result.inspectedEvidence ?? [])].map(reference => ({ reference, reportId: result.reportId })),
+    questions: [...new Set(result.questions ?? [])],
+  };
+  const error = Value.Errors(currentReportSchema, payload).First();
+  if (error) throw new Error(`Checkpoint report ${error.path}: ${error.message}. Correct the report fields and resubmit report_and_exit.`);
+  return payload;
+}
+
+export function checkpointId(author: CheckpointAuthor): string {
+  if (!Value.Check(authorSchema, author)) throw new Error("Invalid checkpoint author.");
+  return `checkpoint:${crypto.createHash("sha256").update(JSON.stringify([author.teamName, author.agentName, author.runId])).digest("hex")}`;
+}
+
+export function checkpointPath(id: string): string {
+  if (!Value.Check(identity, id)) throw new Error("Invalid checkpoint ID.");
+  return path.join(checkpointFilesDir(), `${id.slice("checkpoint:".length)}.json`);
+}
+
+export function isSpecialistCheckpoint(value: unknown): value is SpecialistCheckpoint {
+  if (!Value.Check(recordSchema, value)) return false;
+  const { author, reports, policy } = value;
+  const reportIds = new Set(reports.map(report => report.id));
+  const current = reports.find(report => report.id === value.reportId);
+  const source = current?.source.before;
+  const inputs = source ? [...new Set(policy.inputs.map(input =>
+    path.relative(source.repositoryRoot, path.resolve(source.cwd, input)).split(path.sep).join("/") || "."))].sort() : [];
+  return value.id === checkpointId(author) && value.parentId !== value.id
+    && value.reportId === createReportResult(author.teamName, author.agentName, author.runId, {}).reportId
+    && value.expiresAt === value.createdAt + policy.retentionDays * day
+    && isDeepStrictEqual(policy, normalizeCheckpointPolicy(policy))
+    && reportIds.size === reports.length && !!source && isDeepStrictEqual(inputs, source.inputs)
+    && new Set(value.findings.map(finding => finding.id)).size === value.findings.length
+    && [...value.findings, ...value.inspectedEvidence].every(item => reportIds.has(item.reportId))
+    && reports.every(report => {
+      const { before, after } = report.source;
+      const relative = path.relative(before.repositoryRoot, before.cwd);
+      return path.isAbsolute(report.path) && path.isAbsolute(before.cwd) && path.isAbsolute(before.repositoryRoot)
+        && !path.isAbsolute(relative) && !relative.split(path.sep).includes("..")
+        && before.cwd === after.cwd && before.repositoryRoot === after.repositoryRoot
+        && isDeepStrictEqual(before.inputs, after.inputs);
+    })
+    && Buffer.byteLength(JSON.stringify(value, null, 2)) <= MAX_CHECKPOINT_BYTES;
+}
+
+function rootAvailable(create = false): boolean {
+  const root = checkpointFilesDir();
+  for (let current = root; ; current = path.dirname(current)) {
+    const stat = fs.lstatSync(current, { throwIfNoEntry: false });
+    if (stat && (!stat.isDirectory() || stat.isSymbolicLink())) throw new Error(`Unsafe checkpoint directory: ${current}`);
+    if (path.dirname(current) === current) break;
+  }
+  if (!fs.existsSync(root)) {
+    if (!create) return false;
+    fs.mkdirSync(root, { recursive: true, mode: 0o700 });
+  }
+  const stat = fs.lstatSync(root);
+  if (!stat.isDirectory() || stat.isSymbolicLink() || (stat.mode & 0o077)
+    || (process.getuid && stat.uid !== process.getuid())) throw new Error(`Unsafe checkpoint directory: ${root}`);
+  return true;
+}
+
+function requireRegularFile(file: string): fs.Stats {
+  const stat = fs.lstatSync(file, { throwIfNoEntry: false });
+  if (!stat) throw new Error(`Checkpoint unavailable: ${file}. Request a new checkpoint.`);
+  if (!stat.isFile() || stat.isSymbolicLink() || stat.nlink !== 1
+    || (process.getuid && stat.uid !== process.getuid())) throw new Error(`Unsafe checkpoint file: ${file}`);
+  return stat;
+}
+
+function readRecord(id: string): CheckpointRecord {
+  const file = checkpointPath(id);
+  requireRegularFile(file);
+  const fd = fs.openSync(file, fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW | fs.constants.O_NONBLOCK);
+  let raw: string;
+  try {
+    const stat = fs.fstatSync(fd);
+    if (!stat.isFile() || stat.nlink !== 1 || (process.getuid && stat.uid !== process.getuid())) throw new Error(`Unsafe checkpoint file: ${file}`);
+    if (stat.size > MAX_CHECKPOINT_BYTES) throw new Error(`Checkpoint is too large: ${file}. Delete it or create a smaller checkpoint.`);
+    const buffer = Buffer.alloc(MAX_CHECKPOINT_BYTES + 1);
+    let length = 0;
+    while (length < buffer.length) {
+      const bytes = fs.readSync(fd, buffer, length, buffer.length - length, length);
+      if (!bytes) break;
+      length += bytes;
+    }
+    if (length > MAX_CHECKPOINT_BYTES) throw new Error(`Checkpoint is too large: ${file}. Delete it or create a smaller checkpoint.`);
+    raw = buffer.subarray(0, length).toString("utf8");
+  } finally { fs.closeSync(fd); }
+  try {
+    const value: unknown = JSON.parse(raw);
+    if ((Value.Check(retirementSchema, value) || isSpecialistCheckpoint(value)) && value.id === id) return value;
+  } catch {}
+  throw new Error(`Checkpoint ${id} is corrupt or incompatible; inspect ${file} or delete it.`);
+}
+
+export function readCheckpoint(id: string, now = Date.now()): SpecialistCheckpoint {
+  if (!Value.Check(time, now)) throw new Error("Invalid checkpoint observation time.");
+  const file = checkpointPath(id);
+  if (!rootAvailable()) throw new Error(`Checkpoint unavailable: ${file}. Request a new checkpoint.`);
+  const record = readRecord(id);
+  if (record.state !== "ready") throw new Error(`Checkpoint ${id} was ${record.state}. Request a new checkpoint.`);
+  if (record.expiresAt <= now) throw new Error(`Checkpoint ${id} has expired. Request a new checkpoint.`);
+  return structuredClone(record);
+}
+
+export async function saveCheckpoint(value: unknown): Promise<CheckpointRecord | undefined> {
+  if (value === undefined) return undefined;
+  if (!isSpecialistCheckpoint(value)) throw new Error("Invalid specialist checkpoint.");
+  const record = structuredClone(value);
+  if (record.parentId === undefined) delete record.parentId;
+  for (const report of record.reports) if (report.leadDecisions === undefined) delete report.leadDecisions;
+  const file = checkpointPath(record.id);
+  rootAvailable(true);
+  return withLock(file, async () => {
+    rootAvailable();
+    if (fs.lstatSync(file, { throwIfNoEntry: false })) {
+      const existing = readRecord(record.id);
+      if (existing.state === "ready" && !isDeepStrictEqual(existing, record)) throw new Error(`Checkpoint ${record.id} is immutable.`);
+      syncPathAndParents(file);
+      return structuredClone(existing);
+    }
+    writeJsonDurably(file, record);
+    return structuredClone(record);
+  });
+}
+
+export async function resyncCheckpoint(id: string): Promise<CheckpointRecord> {
+  const file = checkpointPath(id);
+  if (!rootAvailable()) throw new Error(`Checkpoint unavailable: ${file}. Request a new checkpoint.`);
+  return withLock(file, async () => {
+    rootAvailable();
+    const record = readRecord(id);
+    syncPathAndParents(file);
+    return structuredClone(record);
+  });
+}
+
+export async function retireCheckpoint(id: string, state: RetiredCheckpoint["state"], now = Date.now()): Promise<RetiredCheckpoint> {
+  const record: RetiredCheckpoint = { version: 1, id, state, retiredAt: now };
+  if (!Value.Check(retirementSchema, record)) throw new Error("Invalid checkpoint retirement.");
+  const file = checkpointPath(id);
+  if (!rootAvailable()) throw new Error(`Checkpoint unavailable: ${file}. Request a new checkpoint.`);
+  return withLock(file, async () => {
+    rootAvailable();
+    requireRegularFile(file);
+    let existing: CheckpointRecord | undefined;
+    try { existing = readRecord(id); }
+    catch (error) { if (state !== "deleted") throw error; }
+    if (existing && existing.state !== "ready") {
+      syncPathAndParents(file);
+      return existing;
+    }
+    if (state === "expired" && (!existing || existing.expiresAt > now)) throw new Error(`Checkpoint ${id} is not expired.`);
+    writeJsonDurably(file, record);
+    return structuredClone(record);
+  });
+}
+
+export function listCheckpointRecords(): { records: CheckpointRecord[]; errors: { id: string; message: string }[] } {
+  const records: CheckpointRecord[] = [];
+  const errors: { id: string; message: string }[] = [];
+  if (!rootAvailable()) return { records, errors };
+  for (const name of fs.readdirSync(checkpointFilesDir()).sort()) {
+    if (!/^[a-f0-9]{64}\.json$/.test(name)) continue;
+    const id = `checkpoint:${name.slice(0, -5)}`;
+    try { records.push(readRecord(id)); }
+    catch (error) { errors.push({ id, message: error instanceof Error ? error.message : String(error) }); }
+  }
+  return { records, errors };
+}