pi-extended-teams 2.2.9 → 2.3.0

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

package/src/utils/messaging.ts

@@ -2,6 +2,7 @@ import fs from "node:fs";
 import path from "node:path";
 import crypto from "node:crypto";
 import { writeJsonAtomic } from "./atomic-json";
+import { syncPathAndParents, writeJsonDurably } from "../results/durable-json";
 import { InboxMessage, TeamConfig } from "./models";
 import { withLock } from "./lock";
 import { configPath, inboxPath } from "./paths";
@@ -53,10 +54,13 @@ async function appendRunningMessage(
       const messages = readInboxRaw(p);
       if (options.operationId) {
         const existing = messages.find(item => messageOperationMatches(item, options.operationId!, options.workflowRunId));
-        if (existing) return { message: existing, delivered: false };
+        if (existing) {
+          resyncGroupedInbox(p, messages);
+          return { message: existing, delivered: false };
+        }
       }
       messages.push(message);
-      writeJsonAtomic(p, messages);
+      writeInboxRaw(p, messages);
       return { message, delivered: true };
     });
   };
@@ -132,6 +136,22 @@ function readInboxRaw(p: string): InboxMessage[] {
   return Array.isArray(parsed) ? parsed : [];
 }
 
+const hasGroupDeliveryMarker = (messages: InboxMessage[]) => messages.some(message => !!message.metadata?.completionGroup);
+function ensureInboxDurability(p: string, ...snapshots: InboxMessage[][]): boolean {
+  const marker = `${p}.durable`;
+  if (fs.existsSync(marker)) return true;
+  if (!snapshots.some(hasGroupDeliveryMarker)) return false;
+  writeJsonDurably(marker, { version: 1 });
+  return true;
+}
+function writeInboxRaw(p: string, messages: InboxMessage[], previous = messages): void {
+  if (ensureInboxDurability(p, messages, previous)) writeJsonDurably(p, messages);
+  else writeJsonAtomic(p, messages);
+}
+function resyncGroupedInbox(p: string, messages: InboxMessage[]): void {
+  if (ensureInboxDurability(p, messages)) syncPathAndParents(p);
+}
+
 export function messageOperationMatches(message: InboxMessage, operationId: string, workflowRunId?: string): boolean {
   const messageOperationId = message.operationId || message.metadata?.operationId;
   const messageWorkflowRunId = message.workflowRunId || message.metadata?.workflowRunId;
@@ -192,7 +212,7 @@ export async function appendMessage(teamName: string, agentName: string, message
   await withLock(p, async () => {
     const msgs = readInboxRaw(p);
     msgs.push(message);
-    writeJsonAtomic(p, msgs);
+    writeInboxRaw(p, msgs);
   });
 }
 
@@ -206,10 +226,13 @@ export async function appendMessageOnce(
   return await withLock(p, async () => {
     const msgs = readInboxRaw(p);
     const existing = msgs.find((item) => messageOperationMatches(item, message.operationId, message.workflowRunId));
-    if (existing) return { message: existing, delivered: false };
+    if (existing) {
+      resyncGroupedInbox(p, msgs);
+      return { message: existing, delivered: false };
+    }
 
     msgs.push(message);
-    writeJsonAtomic(p, msgs);
+    writeInboxRaw(p, msgs);
     return { message, delivered: true };
   });
 }
@@ -240,14 +263,26 @@ export async function readInbox(
     const allMsgs = readInboxRaw(p);
     const result = selectInboxMessages(allMsgs, unreadOnly);
 
-    if (markAsRead && result.length > 0 && markMessagesRead(result)) {
-      writeJsonAtomic(p, allMsgs);
+    if (markAsRead) {
+      if (markMessagesRead(result)) writeInboxRaw(p, allMsgs);
+      else resyncGroupedInbox(p, allMsgs);
     }
 
     return cloneInboxMessages(result);
   });
 }
 
+export async function markInboxMessagesRead(teamName: string, agentName: string, ids: string[]): Promise<void> {
+  const p = inboxPath(teamName, agentName);
+  if (!fs.existsSync(p)) throw new Error("Referenced inbox is unavailable.");
+  await withLock(p, async () => {
+    const messages = readInboxRaw(p);
+    const selected = messages.filter(message => message.id && ids.includes(message.id));
+    if (markMessagesRead(selected)) writeInboxRaw(p, messages);
+    else resyncGroupedInbox(p, messages);
+  });
+}
+
 export async function readInboxTail(
   teamName: string,
   agentName: string,
@@ -262,8 +297,9 @@ export async function readInboxTail(
     const allMsgs = readInboxRaw(p);
     const result = selectInboxMessages(allMsgs, options.unreadOnly === true, normalizedLimit);
 
-    if (options.markAsRead === true && result.length > 0 && markMessagesRead(result)) {
-      writeJsonAtomic(p, allMsgs);
+    if (options.markAsRead === true) {
+      if (markMessagesRead(result)) writeInboxRaw(p, allMsgs);
+      else resyncGroupedInbox(p, allMsgs);
     }
 
     return cloneInboxMessages(result);
@@ -284,7 +320,8 @@ export async function removeInboxMessagesByOperationUnderLifecycleLock(
     const messages = readInboxRaw(p);
     const remaining = messages.filter((message) => !messageOperationMatches(message, operationId, workflowRunId));
     const removed = messages.length - remaining.length;
-    if (removed > 0) writeJsonAtomic(p, remaining);
+    if (removed > 0) writeInboxRaw(p, remaining, messages);
+    else resyncGroupedInbox(p, messages);
     return removed;
   });
 }

package/src/utils/models.ts

@@ -1,4 +1,10 @@
 import { THINKING_LEVEL_NAMES, type ThinkingLevelName } from "./thinking-levels";
+import type { ReportResult } from "../results/report-result";
+import type { CheckDefinition } from "../results/check-policy";
+import type { RepairPolicy } from "../results/repair-policy";
+import type { CompletionGroupBinding } from "../results/completion-group";
+import type { CheckpointAssignment } from "../results/checkpoint-assignment";
+import type { SpecialistCheckpoint } from "../results/specialist-checkpoint";
 
 export const THINKING_LEVELS = THINKING_LEVEL_NAMES;
 export type ThinkingLevel = ThinkingLevelName;
@@ -18,6 +24,10 @@ export interface Member {
   color?: string;
   thinking?: ThinkingLevel;
   planModeRequired?: boolean;
+  assignedChecks?: CheckDefinition[];
+  repairPolicy?: RepairPolicy;
+  checkpointAssignment?: CheckpointAssignment;
+  completionGroup?: CompletionGroupBinding;
   backendType?: string;
   isActive?: boolean;
   /** Optional programmatic orchestration/idempotency metadata. */
@@ -96,6 +106,9 @@ export interface TeamReportEvent {
   agentName: string;
   role?: string;
   status: "completed" | "failed";
+  checkpoint?: { id: string; draft?: SpecialistCheckpoint };
+  completionGroup?: CompletionGroupBinding;
+  result?: ReportResult;
   report: string;
   summary?: string;
   reportPath?: string;

package/src/utils/paths.ts

@@ -76,6 +76,10 @@ export function reportFilesDir() {
   return path.join(PI_DIR, "agent", "reports");
 }
 
+export function checkpointFilesDir() {
+  return path.join(PI_DIR, "agent", "checkpoints");
+}
+
 export function leadSessionPath(teamName: string) {
   return path.join(teamDir(teamName), "lead-session.json");
 }

package/src/utils/report-events.ts

@@ -4,6 +4,13 @@ import crypto from "node:crypto";
 import { TeamReportEvent } from "./models";
 import * as paths from "./paths";
 import { withLock } from "./lock";
+import { writeJsonAtomic } from "./atomic-json";
+import { syncPathAndParents, writeJsonDurably } from "../results/durable-json";
+import { VerificationController } from "../results/verification-controller";
+import type { CheckRecord } from "../results/check-journal";
+import { isSpecialistCheckpoint, type SpecialistCheckpoint } from "../results/specialist-checkpoint";
+
+export type ObservedTeamReportEvent = TeamReportEvent & { checks?: CheckRecord[] };
 
 export type NewTeamReportEvent = Omit<TeamReportEvent, "id" | "teamName" | "createdAt"> & Partial<Pick<TeamReportEvent, "id" | "teamName" | "createdAt">>;
 
@@ -67,9 +74,7 @@ function compareCreatedAt(a: TeamReportEvent, b: TeamReportEvent): number {
 }
 
 function cloneTeamReportEvent(event: TeamReportEvent): TeamReportEvent {
-  const cloned = { ...event };
-  if (event.metadata !== undefined) cloned.metadata = structuredClone(event.metadata);
-  return cloned;
+  return structuredClone(event);
 }
 
 function cloneTeamReportEvents(events: readonly TeamReportEvent[]): TeamReportEvent[] {
@@ -115,7 +120,8 @@ function readEventsCache(p: string): ReportEventsCache {
 }
 
 function writeEventsRaw(p: string, events: TeamReportEvent[], options: { sorted?: boolean } = {}): void {
-  fs.writeFileSync(p, JSON.stringify(events, null, 2));
+  if (events.some(event => event.completionGroup || event.checkpoint)) writeJsonDurably(p, events);
+  else writeJsonAtomic(p, events);
   buildCache(p, events, reportEventsStatKey(p), options);
 }
 
@@ -196,27 +202,106 @@ export async function appendTeamReportEvent(teamName: string, event: NewTeamRepo
     const cache = readEventsCache(p);
     const normalized: TeamReportEvent = cloneTeamReportEvent({
       ...event,
-      id: event.id || defaultEventId(teamName, event),
+      id: event.id || event.result?.reportId || defaultEventId(teamName, event),
       teamName,
       createdAt: event.createdAt || Date.now(),
     });
 
+    if (normalized.result && normalized.result.reportId !== normalized.id) {
+      throw new Error("Structured report identity does not match its event ID.");
+    }
+    if (normalized.checkpoint && normalized.result) normalized.result.checkpointId = normalized.checkpoint.id;
     const existing = cache.byId.get(normalized.id);
-    if (existing) return cloneTeamReportEvent(existing);
+    if (existing) return existing.completionGroup || existing.checkpoint ? resyncEvent(p, existing) : cloneTeamReportEvent(existing);
 
     normalized.reportPath = writeStandaloneReport(teamName, normalized.agentName, normalized.report);
+    if (normalized.completionGroup || normalized.checkpoint) syncPathAndParents(normalized.reportPath);
     writeEventsRaw(p, insertEvent(cache.events, normalized), { sorted: true });
     return cloneTeamReportEvent(normalized);
   });
 }
 
-export async function listTeamReportEvents(
+function resyncEvent(p: string, event: TeamReportEvent | undefined): TeamReportEvent {
+  if (!event?.reportPath) throw new Error(`Full report is unavailable in ${p}.`);
+  syncPathAndParents(event.reportPath);
+  syncPathAndParents(p);
+  return cloneTeamReportEvent(event);
+}
+
+export async function resyncStoredTeamReportEvent(teamName: string, reportId: string): Promise<TeamReportEvent> {
+  const p = ensureReportEventsFile(teamName);
+  return withLock(p, async () => resyncEvent(p, readEventsCache(p).byId.get(reportId)));
+}
+
+export async function recordReportCheckpoint(teamName: string, reportId: string, draft: SpecialistCheckpoint): Promise<TeamReportEvent> {
+  if (!isSpecialistCheckpoint(draft)) throw new Error("Invalid specialist checkpoint.");
+  const p = ensureReportEventsFile(teamName);
+  return withLock(p, async () => {
+    const cache = readEventsCache(p);
+    const existing = cache.byId.get(reportId);
+    if (!existing?.checkpoint || existing.checkpoint.id !== draft.id || draft.reportId !== reportId
+      || draft.author.teamName !== teamName || draft.author.agentName !== existing.agentName || draft.author.runId !== existing.result?.runId
+      || draft.reports.find(report => report.id === reportId)?.path !== existing.reportPath) throw new Error("Checkpoint report binding changed.");
+    resyncEvent(p, existing);
+    if (existing.checkpoint.draft) return cloneTeamReportEvent(existing);
+    const updated = cloneTeamReportEvent({ ...existing, checkpoint: { id: draft.id, draft } });
+    writeEventsRaw(p, cache.events.map(event => event.id === reportId ? updated : event), { sorted: true });
+    return cloneTeamReportEvent(updated);
+  });
+}
+
+export async function recordReportAcceptance(
+  teamName: string,
+  reportId: string,
+  state: "accepted" | "rejected",
+  reason?: string,
+): Promise<TeamReportEvent> {
+  if (state !== "accepted" && state !== "rejected") throw new Error("Report acceptance must be accepted or rejected.");
+  const p = ensureReportEventsFile(teamName);
+  return withLock(p, async () => {
+    const cache = readEventsCache(p);
+    const existing = cache.byId.get(reportId);
+    if (!existing?.result || existing.result.version !== 1) throw new Error(`Structured report ${reportId} is unavailable.`);
+    const updated = cloneTeamReportEvent({
+      ...existing,
+      result: { ...existing.result, acceptance: { state, reason, decidedAt: Date.now() } },
+    });
+    writeEventsRaw(p, cache.events.map(event => event.id === reportId ? updated : event), { sorted: true });
+    return cloneTeamReportEvent(updated);
+  });
+}
+
+export async function readStoredTeamReportEvent(teamName: string, reportId: string): Promise<TeamReportEvent | undefined> {
+  const p = ensureReportEventsFile(teamName);
+  return withLock(p, async () => {
+    const event = readEventsCache(p).byId.get(reportId);
+    return event ? cloneTeamReportEvent(event) : undefined;
+  });
+}
+
+export async function listStoredTeamReportEvents(
   teamName: string,
   options: ListTeamReportEventsOptions = {}
 ): Promise<TeamReportEvent[]> {
   const p = ensureReportEventsFile(teamName);
+  return withLock(p, async () => selectEvents(readEventsCache(p), options));
+}
 
-  return await withLock(p, async () => {
-    return selectEvents(readEventsCache(p), options);
-  });
+export async function listTeamReportEvents(
+  teamName: string,
+  options: ListTeamReportEventsOptions = {}
+): Promise<ObservedTeamReportEvent[]> {
+  const events = await listStoredTeamReportEvents(teamName, options);
+  return Promise.all(events.map(async event => {
+    if (!event.result) return event;
+    try {
+      const observed = await VerificationController.observe(teamName, event.result);
+      return { ...event, result: observed.result,
+        ...(observed.result.verification.state !== "not-requested" ? { checks: observed.checks } : {}) };
+    } catch (error) {
+      return { ...event, result: { ...event.result, verification: {
+        state: "failed" as const, error: error instanceof Error ? error.message : String(error),
+      } }, checks: [] };
+    }
+  }));
 }

package/src/utils/teams.ts

@@ -3,6 +3,7 @@ import path from "node:path";
 import { TeamConfig, Member } from "./models";
 import { configPath, teamDir, taskDir } from "./paths";
 import { withLock } from "./lock";
+import { assertUnusedContinuationRecipient } from "../results/continuation-recipient";
 import {
   assertLifecycleTombstoneAbsent,
   generateLifecycleRunId,
@@ -157,9 +158,10 @@ export async function addMember(teamName: string, member: Member) {
   member.lifecycleRunId = generateLifecycleRunId();
   await withLifecycleTombstoneLock(teamName, member.name, async lifecycleLock => {
     assertLifecycleTombstoneAbsent(teamName, member.name, lifecycleLock.read());
+    if (member.checkpointAssignment?.parent) assertUnusedContinuationRecipient(teamName, member.name);
     await withLock(p, async () => {
       const config = readConfigRaw(p);
-      if (config.members.some(existing => existing.name === member.name)) {
+      if (config.members.some(existing => existing.name === member.name || (member.checkpointAssignment?.parent && existing.name.toLowerCase() === member.name.toLowerCase()))) {
         throw new Error(`Teammate ${member.name} already exists in team ${teamName}.`);
       }
       config.members.push(member);

package/src/utils/write-queue.ts

@@ -87,6 +87,9 @@ export async function enqueueWriteSpawn(
   teamName: string,
   request: Omit<QueuedWriteSpawn, "id" | "requestedAt"> & Partial<Pick<QueuedWriteSpawn, "id" | "requestedAt">>
 ): Promise<QueuedWriteSpawn> {
+  if (["checkpoint", "checkpointAssignment", "continueFrom", "continue_from"].some(field => Reflect.get(request, field) !== undefined)) {
+    throw new Error("Checkpoint-enabled agents require in-process lead admission; the legacy terminal queue is unsupported.");
+  }
   const queuePath = ensureQueueDir(teamName);
   return await withLock(queuePath, async () => {
     const queue = readQueueRaw(queuePath);