pi-extended-teams 2.2.10 → 2.3.0

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 };
+}

package/src/results/verification-controller.ts

@@ -0,0 +1,308 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { Type, type Static } from "@sinclair/typebox";
+import { Value } from "@sinclair/typebox/value";
+import * as paths from "../utils/paths";
+import { withLock } from "../utils/lock";
+import { AssignedCheckSchema, CheckJournal, assignmentBinding, checkIdentity, type AssignedCheck, type CheckRecord } from "./check-journal";
+import { normalizeCheckPolicy, readCheckEvidence, verifyAssignedChecks, type CheckDefinition, type CheckEvidence } from "./check-policy";
+import { observeCheckSource, runAssignedCheck, type CheckRunnerOptions } from "./check-runner";
+import { syncPathAndParents, writeJsonDurably } from "./durable-json";
+import { normalizeReportedTaskDetails, type ReportResult } from "./report-result";
+import { normalizeRepairPolicy, type RepairPolicy, type RepairResult, type RepairState } from "./repair-policy";
+
+const text = Type.String({ minLength: 1 });
+const stageStates = ["running", "not-needed", "requested", "repaired", "exhausted", "cancelled", "declined", "blocked"] as const;
+const StageSchema = Type.Object({
+  submissionId: text, signature: text, token: text,
+  attempt: Type.Integer({ minimum: 1, maximum: 6 }),
+  state: Type.Union(stageStates.map(state => Type.Literal(state))),
+  checkIds: Type.Array(Type.String({ pattern: "^check:[a-f0-9]{64}$" })),
+}, { additionalProperties: false });
+const LedgerSchema = Type.Object({
+  version: Type.Literal(1), assignments: Type.Array(AssignedCheckSchema, { minItems: 1 }),
+  maxAttempts: Type.Integer({ minimum: 1, maximum: 5 }), cancelled: Type.Boolean(),
+  stages: Type.Array(StageSchema, { maxItems: 6 }),
+}, { additionalProperties: false });
+type Stage = Static<typeof StageSchema>;
+type Ledger = Static<typeof LedgerSchema>;
+
+export interface VerificationControllerOptions {
+  teamName: string;
+  result: ReportResult;
+  cwd: string;
+  checks?: CheckDefinition[];
+  repair?: RepairPolicy;
+}
+export interface RepairRequest { id: string; attempt: number; checks: CheckRecord[] }
+export interface VerificationDecision { result: ReportResult; checks: CheckRecord[]; request?: RepairRequest }
+
+function identity(value: unknown): string {
+  return `repair:${crypto.createHash("sha256").update(JSON.stringify(value)).digest("hex")}`;
+}
+
+function repairJournalPath(teamName: string, reportId: string): string {
+  return path.join(paths.teamDir(teamName), "repairs", `${identity(reportId).slice(7)}.json`);
+}
+
+function readLedger(file: string): Ledger | undefined {
+  let contents: string;
+  try { contents = fs.readFileSync(file, "utf8"); }
+  catch (error) {
+    if (typeof error === "object" && error !== null && Reflect.get(error, "code") === "ENOENT") return undefined;
+    throw error;
+  }
+  let value: unknown;
+  try { value = JSON.parse(contents); } catch { throw new Error("Corrupt repair ledger JSON."); }
+  return parseLedger(value);
+}
+
+function parseLedger(value: unknown): Ledger {
+  if (!Value.Check(LedgerSchema, value)) throw new Error("Corrupt or incompatible repair ledger.");
+  const names = value.assignments.map(assignment => assignment.name);
+  if (new Set(names).size !== names.length || value.assignments.some(assignment => assignment.attempt !== 1)
+    || value.stages.length > value.maxAttempts + 1
+    || new Set(value.stages.map(stage => stage.submissionId)).size !== value.stages.length) throw new Error("Corrupt repair assignment binding.");
+  for (const [index, stage] of value.stages.entries()) {
+    if (stage.attempt !== index + 1 || (index > 0 && value.stages[index - 1].state !== "requested")
+      || stage.checkIds.length !== names.length || stage.checkIds.some((id, item) =>
+        !Array.from({ length: stage.attempt }, (_, attempt) => checkIdentity({ ...value.assignments[item], attempt: attempt + 1 })).includes(id))) {
+      throw new Error("Corrupt repair stage binding.");
+    }
+  }
+  return structuredClone(value);
+}
+
+export class VerificationController {
+  readonly journalPath: string;
+  private readonly context: VerificationControllerOptions;
+  private readonly checks: CheckDefinition[] | undefined;
+  private readonly repair: RepairPolicy | undefined;
+  private readonly assignments: AssignedCheck[];
+  private observedLedger = false;
+
+  constructor(options: VerificationControllerOptions) {
+    this.context = structuredClone(options);
+    this.checks = normalizeCheckPolicy(options.checks);
+    this.repair = normalizeRepairPolicy(options.repair);
+    if (this.repair && !this.checks?.length) throw new Error("Repair policy requires explicitly assigned checks.");
+    this.assignments = (this.checks ?? []).map(check => ({
+      ...check, inputs: check.inputs ? [...new Set(check.inputs)].sort() : undefined,
+      taskId: options.result.taskId, runId: options.result.runId, reportId: options.result.reportId,
+      cwd: options.cwd, attempt: 1,
+    }));
+    this.journalPath = repairJournalPath(options.teamName, options.result.reportId);
+  }
+
+  static async observe(teamName: string, result: ReportResult, signal?: AbortSignal): Promise<VerificationDecision> {
+    const uncertain = async (error: unknown): Promise<VerificationDecision> => {
+      const message = error instanceof Error ? error.message : String(error);
+      const evidence = await readCheckEvidence(teamName, result, signal).catch(() => ({ verification: result.verification, checks: [] }));
+      return { result: { ...structuredClone(result), verification: { ...evidence.verification, state: "pending", error: message },
+        repair: { controllerId: identity(result.reportId), journalPath: repairJournalPath(teamName, result.reportId), state: "pending", outcome: "blocked", error: message } }, checks: evidence.checks };
+    };
+    let ledger: Ledger | undefined;
+    try { ledger = readLedger(repairJournalPath(teamName, result.reportId)); }
+    catch (error) { return uncertain(error); }
+    if (!ledger && !result.repair) {
+      const evidence = await readCheckEvidence(teamName, result, signal);
+      return { result: { ...structuredClone(result), verification: evidence.verification }, checks: evidence.checks };
+    }
+    try {
+      if (!ledger) throw new Error(`Referenced repair ledger is unavailable.${result.verification.error ? ` ${result.verification.error}` : ""}`);
+      if (ledger.assignments.some(assignment => assignment.taskId !== result.taskId || assignment.runId !== result.runId || assignment.reportId !== result.reportId)) {
+        throw new Error("Repair ledger belongs to another task/run binding.");
+      }
+      const controller = new VerificationController({ teamName, result, cwd: ledger.assignments[0].cwd,
+        checks: ledger.assignments.map(({ name, command, timeoutSeconds, inputs }) => ({ name, command, timeoutSeconds, inputs })),
+        repair: { maxAttempts: ledger.maxAttempts } });
+      const current = controller.read();
+      if (!current) throw new Error("Referenced repair ledger is unavailable.");
+      if (result.verification.error && ["running", "requested"].includes(current.stages.at(-1)?.state ?? "")) {
+        return uncertain(result.verification.error);
+      }
+      return await controller.decision(current, current.stages.at(-1), undefined, signal);
+    } catch (error) { return uncertain(error); }
+  }
+
+  pendingRepair(error: unknown): RepairResult | undefined {
+    if (!this.repair) return undefined;
+    return {
+      ...this.context.result.repair,
+      controllerId: identity(this.context.result.reportId), journalPath: this.journalPath,
+      state: "pending", outcome: "blocked", maxAttempts: this.repair.maxAttempts,
+      error: error instanceof Error ? error.message : String(error),
+    };
+  }
+
+  private read(): Ledger | undefined {
+    const ledger = readLedger(this.journalPath);
+    if (!ledger) {
+      const result = this.context.result;
+      if (this.observedLedger || result.repair || (this.repair && (result.verification.checkIds?.length || result.verification.error))) {
+        throw new Error(`Referenced repair ledger is unavailable; inspect ${this.journalPath}.${result.verification.error ? ` ${result.verification.error}` : ""}`);
+      }
+      return undefined;
+    }
+    this.observedLedger = true;
+    if (ledger.maxAttempts !== this.repair?.maxAttempts
+      || JSON.stringify(ledger.assignments.map(assignmentBinding)) !== JSON.stringify(this.assignments.map(assignmentBinding))) {
+      throw new Error("Repair policy or assignment binding has changed.");
+    }
+    return ledger;
+  }
+
+  private async update<T>(change: (ledger: Ledger) => { value: T; changed: boolean }): Promise<T> {
+    fs.mkdirSync(path.dirname(this.journalPath), { recursive: true, mode: 0o700 });
+    return withLock(this.journalPath, async () => {
+      let ledger = this.read();
+      if (!ledger) {
+        const journal = new CheckJournal(this.context.teamName);
+        for (const assignment of this.assignments) {
+          if (await journal.read(checkIdentity(assignment))) throw new Error(`Referenced repair ledger is unavailable; inspect ${this.journalPath}.`);
+        }
+        ledger = { version: 1, assignments: this.assignments, maxAttempts: this.repair!.maxAttempts, cancelled: false, stages: [] };
+      }
+      const changed = change(ledger);
+      this.observedLedger = true;
+      if (changed.changed) writeJsonDurably(this.journalPath, parseLedger(ledger));
+      else syncPathAndParents(this.journalPath);
+      return structuredClone(changed.value);
+    });
+  }
+
+  async cancel(): Promise<void> {
+    if (!this.repair) {
+      this.read();
+      return;
+    }
+    await this.update(ledger => {
+      const last = ledger.stages.at(-1);
+      const terminal = last && !["running", "requested"].includes(last.state);
+      const changed = !ledger.cancelled && !terminal;
+      if (changed) ledger.cancelled = true;
+      return { value: undefined, changed };
+    });
+  }
+
+  async cancelAndRequireSettled(): Promise<void> {
+    const verificationError = this.context.result.verification.error;
+    await this.cancel();
+    const ledger = this.read();
+    const stage = ledger?.stages.at(-1);
+    if (stage?.state === "running" || (stage?.state === "requested" && verificationError)) {
+      throw new Error(`Repair verification remains unresolved; inspect ${this.journalPath}.${verificationError ? ` ${verificationError}` : ""}`);
+    }
+    const journal = new CheckJournal(this.context.teamName);
+    for (const [index, id] of (stage?.checkIds ?? []).entries()) {
+      const record = await journal.read(id);
+      if (record && assignmentBinding(record.assignment) !== assignmentBinding({ ...this.assignments[index], attempt: record.assignment.attempt })) {
+        throw new Error(`Repair evidence binding is invalid; inspect ${this.journalPath}.`);
+      }
+      if (record?.state === "claimed") throw new Error(`Repair check ownership remains unresolved; inspect ${this.journalPath}.`);
+    }
+  }
+
+  private async evidence(checkIds: string[], signal?: AbortSignal): Promise<CheckEvidence> {
+    return readCheckEvidence(this.context.teamName, {
+      ...this.context.result, verification: { state: "pending", checkIds },
+    }, signal);
+  }
+
+  private async decision(ledger: Ledger, stage: Stage | undefined, evidence?: CheckEvidence, signal?: AbortSignal): Promise<VerificationDecision> {
+    evidence ??= await this.evidence(stage?.checkIds ?? [], signal);
+    const state: RepairState = stage?.state === "running" || evidence.verification.state === "pending"
+      ? "pending" : ledger.cancelled ? "cancelled" : stage?.state ?? "pending";
+    if (state === "pending") evidence.verification.state = "pending";
+    const requested = ledger.stages.filter(item => item.state === "requested");
+    const repair: RepairResult = {
+      controllerId: identity(this.context.result.reportId), journalPath: this.journalPath, state, maxAttempts: ledger.maxAttempts,
+      attemptsUsed: requested.length, requestIds: requested.map(item => identity([this.context.result.reportId, item.attempt])),
+      ...(["pending", "exhausted", "cancelled", "declined", "blocked"].includes(state) ? { outcome: "blocked" as const } : {}),
+    };
+    return {
+      result: { ...structuredClone(this.context.result), verification: evidence.verification, repair }, checks: evidence.checks,
+      ...(state === "requested" && stage ? { request: {
+        id: identity([this.context.result.reportId, stage.attempt]), attempt: stage.attempt,
+        checks: evidence.checks.filter(check => check.state !== "passed"),
+      } } : {}),
+    };
+  }
+
+  private async runPlan(stage: Stage, previous: Stage | undefined, options: CheckRunnerOptions): Promise<CheckEvidence> {
+    const journal = new CheckJournal(this.context.teamName);
+    const prior = previous ? await Promise.all(previous.checkIds.map(id => journal.read(id))) : [];
+    for (const [index, record] of prior.entries()) {
+      if (!record || assignmentBinding(record.assignment) !== assignmentBinding({ ...this.assignments[index], attempt: record.assignment.attempt })) {
+        throw new Error("Prior repair evidence has an incompatible assignment binding.");
+      }
+    }
+    if (prior.some(record => record?.state === "claimed")) return this.evidence(previous!.checkIds, options.signal);
+    const checkIds = [...stage.checkIds];
+    for (const [index, assignment] of this.assignments.entries()) {
+      if (options.signal?.aborted) break;
+      const observed = prior[index] && await observeCheckSource(prior[index]!, options.signal);
+      if (observed?.state === "passed") { checkIds[index] = observed.checkId; continue; }
+      const record = await runAssignedCheck(journal, { ...assignment, attempt: stage.attempt }, options);
+      checkIds[index] = record.checkId;
+      if (record.state === "claimed" || options.signal?.aborted) break;
+    }
+    return this.evidence(checkIds, options.signal);
+  }
+
+  async verify(submissionId: string, options: CheckRunnerOptions): Promise<VerificationDecision> {
+    if (!this.repair) {
+      this.read();
+      const evidence = await verifyAssignedChecks(this.context.teamName, this.context.result, this.context.cwd, this.checks, options);
+      const result = { ...structuredClone(this.context.result), verification: evidence.verification };
+      delete result.repair;
+      return { result, checks: evidence.checks };
+    }
+    if (typeof submissionId !== "string" || !submissionId.trim()) throw new Error("Repair verification requires a runtime submission identity.");
+    if (options.signal?.aborted) await this.cancel();
+    const signature = identity(normalizeReportedTaskDetails(this.context.result));
+    const reservation = await this.update(ledger => {
+      const existing = ledger.stages.find(stage => stage.submissionId === submissionId);
+      if (existing && existing.signature !== signature) throw new Error("Repair submission identity binding has changed.");
+      const previous = ledger.stages.at(-1);
+      if (ledger.cancelled || existing || (previous && previous.state !== "requested")) {
+        return { value: { ledger, stage: previous ?? existing, previous: undefined as Stage | undefined, granted: false }, changed: false };
+      }
+      const attempt = (previous?.attempt ?? 0) + 1;
+      const declined = previous && ["blocked", "failed", "cancelled"].includes(this.context.result.outcome ?? "");
+      const stage: Stage = {
+        submissionId, signature, token: crypto.randomUUID(), attempt,
+        state: declined ? "declined" : "running",
+        checkIds: declined ? [...previous.checkIds] : this.assignments.map(assignment => checkIdentity({ ...assignment, attempt })),
+      };
+      ledger.stages.push(stage);
+      return { value: { ledger, stage, previous, granted: !declined }, changed: true };
+    });
+    if (!reservation.granted || !reservation.stage) {
+      const observed = await this.decision(reservation.ledger, reservation.stage, undefined, options.signal);
+      if (!options.signal?.aborted) return observed;
+      await this.cancel();
+      const cancelled = this.read();
+      if (!cancelled) throw new Error("Repair ledger disappeared during cancellation.");
+      return this.decision(cancelled, cancelled.stages.at(-1), undefined, options.signal);
+    }
+    const evidence = await this.runPlan(reservation.stage, reservation.previous, options);
+    const finished = await this.update(ledger => {
+      const stage = ledger.stages.find(item => item.token === reservation.stage!.token);
+      if (!stage || stage.state !== "running") throw new Error("Repair reservation changed before completion.");
+      stage.checkIds = evidence.verification.checkIds ?? [];
+      if (options.signal?.aborted || evidence.checks.some(check => check.state === "cancelled")) ledger.cancelled = true;
+      const repairable = evidence.checks.length === this.assignments.length
+        && evidence.checks.every(check => ["passed", "failed", "stale", "timed-out"].includes(check.state));
+      if (evidence.verification.state === "pending") stage.state = "running";
+      else if (ledger.cancelled) stage.state = "cancelled";
+      else if (evidence.verification.state === "passed") stage.state = stage.attempt === 1 ? "not-needed" : "repaired";
+      else if (["blocked", "failed", "cancelled"].includes(this.context.result.outcome ?? "")) stage.state = "declined";
+      else if (!repairable) stage.state = "blocked";
+      else stage.state = stage.attempt <= ledger.maxAttempts ? "requested" : "exhausted";
+      return { value: { ledger, stage }, changed: true };
+    });
+    return this.decision(finished.ledger, finished.stage, evidence);
+  }
+}