@agent-native/core 0.111.4 → 0.113.0

package/corpus/core/src/cli/multi-frontier-runs.ts

@@ -0,0 +1,1952 @@
+import fs from "node:fs";
+import path from "node:path";
+
+import {
+  appendUniqueJsonLineAtomically,
+  withFileLockSync,
+  writeJsonFileAtomically,
+  writeTextFileAtomically,
+} from "./atomic-json-file.js";
+import { codeAgentStoreRoot } from "./code-agent-runs.js";
+
+export type MultiFrontierPhase =
+  | "proposing"
+  | "cross_review"
+  | "converging"
+  | "awaiting_go"
+  | "implementing"
+  | "checkpoint_review"
+  | "paused"
+  | "completed"
+  | "failed"
+  | "canceled";
+
+export type MultiFrontierParticipantRole = "driver" | "watchdog";
+export type MultiFrontierParticipantPermission =
+  | "read_only"
+  | "workspace_write";
+export type MultiFrontierParticipantStatus =
+  | "idle"
+  | "running"
+  | "waiting"
+  | "failed"
+  | "completed";
+export type MultiFrontierApprovalState =
+  | "not_required"
+  | "pending"
+  | "approved"
+  | "rejected";
+export type MultiFrontierRecoveryReason =
+  | "main_process_restarted"
+  | "driver_crashed"
+  | "watchdog_crashed"
+  | "app_quit"
+  | "canceled";
+
+export interface MultiFrontierParticipantState {
+  participantId: string;
+  provider: string;
+  runtime: string;
+  model?: string;
+  capabilities?: string[];
+  sessionRef?: string;
+  role: MultiFrontierParticipantRole;
+  permission: MultiFrontierParticipantPermission;
+  status: MultiFrontierParticipantStatus;
+}
+
+export interface MultiFrontierDriverLease {
+  participantId: string;
+  generation: number;
+  leaseState: "inactive" | "active" | "revoked";
+}
+
+export interface MultiFrontierApproval {
+  state: MultiFrontierApprovalState;
+  proposalId?: string;
+  reviewPacketId?: string;
+}
+
+export interface MultiFrontierRecovery {
+  reason: MultiFrontierRecoveryReason;
+  recoveredAt: string;
+  resumablePhase: MultiFrontierPhase;
+  checkpointId?: string;
+}
+
+/**
+ * The durable state contract shared by the main process and every participant.
+ * Only the main-process coordinator writes it through this module.
+ */
+export interface MultiFrontierRunState {
+  schemaVersion: 1;
+  collaborationId: string;
+  /** Opaque local workspace handle; never a filesystem path. */
+  workspaceId?: string;
+  phase: MultiFrontierPhase;
+  participants: MultiFrontierParticipantState[];
+  driver: MultiFrontierDriverLease | null;
+  approval: MultiFrontierApproval;
+  checkpointIds: string[];
+  round: number;
+  proposalIds: string[];
+  reviewIds: string[];
+  /** Opt-in policy; explicit GO remains the durable default. */
+  autoContinueAfterAgreement: boolean;
+  recovery?: MultiFrontierRecovery;
+}
+
+export interface CreateMultiFrontierRunInput {
+  collaborationId: string;
+  workspaceId?: string;
+  phase?: MultiFrontierPhase;
+  participants: MultiFrontierParticipantState[];
+  approval?: MultiFrontierApproval;
+  checkpointIds?: string[];
+  autoContinueAfterAgreement?: boolean;
+}
+
+export interface RecoverMultiFrontierRunInput {
+  now: string;
+  reason: MultiFrontierRecoveryReason;
+}
+
+export interface MultiFrontierParticipantEvent {
+  participantId: string;
+  generation?: number;
+  permission: MultiFrontierParticipantPermission;
+}
+
+export interface PersistedMultiFrontierParticipantEvent extends MultiFrontierParticipantEvent {
+  schemaVersion: 1;
+  id: string;
+  collaborationId: string;
+  createdAt: string;
+  status?: MultiFrontierParticipantStatus;
+}
+
+export type MultiFrontierArtifactKind = "proposal" | "review" | "checkpoint";
+
+export interface MultiFrontierArtifactTestSummary {
+  name: string;
+  status: "passed" | "failed" | "skipped";
+  summary?: string;
+}
+
+/** A bounded, redacted projection used only for Desktop orchestrator recovery. */
+export interface MultiFrontierOrchestrationArtifact {
+  id: string;
+  kind:
+    | "proposal"
+    | "cross_review"
+    | "revision"
+    | "synthesis"
+    | "checkpoint"
+    | "watchdog_review"
+    | "finding_disposition"
+    | "completion";
+  round: number;
+  participantId?: string;
+  text: string;
+  attribution: { participantIds: string[]; sourceArtifactIds: string[] };
+  supersedesArtifactId?: string;
+  metadata?: Record<string, unknown>;
+}
+
+/**
+ * A deliberately narrow coordination record. Full diffs, transcripts, and
+ * provider payloads stay in their owning runtime rather than this durable
+ * cross-provider index.
+ */
+export interface PersistedMultiFrontierArtifact {
+  schemaVersion: 1;
+  id: string;
+  collaborationId: string;
+  kind: MultiFrontierArtifactKind;
+  createdAt: string;
+  participantId?: string;
+  title: string;
+  summary: string;
+  supersedesArtifactId?: string;
+  contentHash?: string;
+  fileRefs?: string[];
+  testSummary?: MultiFrontierArtifactTestSummary[];
+  orchestration?: MultiFrontierOrchestrationArtifact;
+}
+
+export interface AppendMultiFrontierArtifactInput {
+  id: string;
+  collaborationId: string;
+  kind: MultiFrontierArtifactKind;
+  createdAt?: string;
+  participantId?: string;
+  title: string;
+  summary: string;
+  supersedesArtifactId?: string;
+  contentHash?: string;
+  fileRefs?: string[];
+  testSummary?: MultiFrontierArtifactTestSummary[];
+  orchestration?: MultiFrontierOrchestrationArtifact;
+}
+
+export interface MultiFrontierParticipantEventRetention {
+  schemaVersion: 1;
+  retainedEventCount: number;
+  retainedByteCount: number;
+  droppedEventCount: number;
+  droppedByteCount: number;
+  truncated: boolean;
+  replay: {
+    requiresSnapshot: boolean;
+    firstRetainedEventId?: string;
+  };
+}
+
+export interface MultiFrontierParticipantEventRetentionLimits {
+  maxEventCount: number;
+  maxBytes: number;
+}
+
+export interface AppendMultiFrontierParticipantEventInput extends MultiFrontierParticipantEvent {
+  id: string;
+  collaborationId: string;
+  createdAt?: string;
+  status?: MultiFrontierParticipantStatus;
+}
+
+export interface MultiFrontierStoredRun extends MultiFrontierRunState {
+  createdAt: string;
+  updatedAt: string;
+}
+
+/**
+ * The desktop main-process coordinator is the sole caller of this transition
+ * boundary. Its callback receives a detached snapshot, never renderer input.
+ */
+export type MultiFrontierCoordinatorTransition = (
+  current: MultiFrontierStoredRun,
+) => MultiFrontierRunState | MultiFrontierStoredRun | null;
+
+export type AppendMultiFrontierParticipantEventResult =
+  | {
+      accepted: true;
+      deduplicated: boolean;
+      event: PersistedMultiFrontierParticipantEvent;
+      run: MultiFrontierStoredRun;
+    }
+  | {
+      accepted: false;
+      reason:
+        | "missing-run"
+        | "stale-driver"
+        | "missing-participant"
+        | "event-conflict"
+        | "terminal-participant";
+      run: MultiFrontierStoredRun | null;
+    };
+
+export type AppendMultiFrontierArtifactResult =
+  | {
+      accepted: true;
+      deduplicated: boolean;
+      artifact: PersistedMultiFrontierArtifact;
+      run: MultiFrontierStoredRun;
+    }
+  | {
+      accepted: false;
+      reason:
+        | "missing-run"
+        | "artifact-conflict"
+        | "missing-participant"
+        | "missing-superseded-artifact"
+        | "artifact-limit-reached";
+      run: MultiFrontierStoredRun | null;
+    };
+
+const TERMINAL_PHASES = new Set<MultiFrontierPhase>([
+  "completed",
+  "failed",
+  "canceled",
+]);
+const SAFE_ID = /^[A-Za-z0-9][A-Za-z0-9._-]{0,191}$/;
+const SAFE_CONTENT_HASH = /^[a-f0-9]{64}$/;
+const SAFE_FILE_REF = /^(?!\/)(?!.*(?:^|\/)\.\.(?:\/|$))[A-Za-z0-9._/@+-]+$/;
+const MAX_ARTIFACT_TITLE_BYTES = 280;
+const MAX_ARTIFACT_SUMMARY_BYTES = 8 * 1024;
+const MAX_ARTIFACT_FILE_REFS = 40;
+const MAX_ARTIFACT_TEST_SUMMARIES = 40;
+const MAX_ARTIFACT_TEST_NAME_BYTES = 280;
+const MAX_ARTIFACT_TEST_SUMMARY_BYTES = 2 * 1024;
+export const MAX_MULTI_FRONTIER_ARTIFACTS_PER_RUN = 200;
+export const DEFAULT_MULTI_FRONTIER_PARTICIPANT_EVENT_RETENTION: MultiFrontierParticipantEventRetentionLimits =
+  {
+    maxEventCount: 2_000,
+    maxBytes: 1_000_000,
+  };
+
+/** All multi-frontier state stays alongside the existing local Code store. */
+export function multiFrontierRunsStoreRoot(): string {
+  return path.join(codeAgentStoreRoot(), "multi-frontier");
+}
+
+export function multiFrontierRunsDir(): string {
+  return path.join(multiFrontierRunsStoreRoot(), "runs");
+}
+
+export function multiFrontierParticipantEventsDir(): string {
+  return path.join(multiFrontierRunsStoreRoot(), "events");
+}
+
+export function multiFrontierArtifactsDir(): string {
+  return path.join(multiFrontierRunsStoreRoot(), "artifacts");
+}
+
+export function createMultiFrontierRun(
+  input: CreateMultiFrontierRunInput,
+): MultiFrontierStoredRun {
+  assertSafeId(input.collaborationId, "collaboration id");
+  if (input.workspaceId !== undefined) {
+    assertSafeId(input.workspaceId, "workspace id");
+  }
+  assertParticipants(input.participants);
+  if (getMultiFrontierRun(input.collaborationId)) {
+    throw new Error(
+      `Multi-frontier run already exists: ${input.collaborationId}`,
+    );
+  }
+  const now = new Date().toISOString();
+  const state: MultiFrontierStoredRun = {
+    schemaVersion: 1,
+    collaborationId: input.collaborationId,
+    ...(input.workspaceId ? { workspaceId: input.workspaceId } : {}),
+    phase: input.phase ?? "proposing",
+    participants: input.participants.map((participant) => ({
+      ...participant,
+      capabilities: [...(participant.capabilities ?? [])],
+      role: "watchdog",
+      permission: "read_only",
+    })),
+    driver: null,
+    approval: { ...(input.approval ?? { state: "not_required" }) },
+    checkpointIds: [...(input.checkpointIds ?? [])],
+    round: 1,
+    proposalIds: [],
+    reviewIds: [],
+    autoContinueAfterAgreement: input.autoContinueAfterAgreement ?? false,
+    createdAt: now,
+    updatedAt: now,
+  };
+  writeNewMultiFrontierRun(state);
+  return state;
+}
+
+export function getMultiFrontierRun(
+  collaborationId: string,
+): MultiFrontierStoredRun | null {
+  if (!SAFE_ID.test(collaborationId)) return null;
+  return readStoredRun(multiFrontierRunPath(collaborationId));
+}
+
+export function listMultiFrontierRuns(): MultiFrontierStoredRun[] {
+  const directory = multiFrontierRunsDir();
+  if (!fs.existsSync(directory)) return [];
+  return fs
+    .readdirSync(directory)
+    .filter((file) => file.endsWith(".json"))
+    .map((file) => readStoredRun(path.join(directory, file)))
+    .filter((run): run is MultiFrontierStoredRun => run !== null)
+    .sort((left, right) => right.updatedAt.localeCompare(left.updatedAt));
+}
+
+/**
+ * Recovery never resumes a native participant automatically. Any in-flight
+ * driver lease is revoked and requires an explicit, newly fenced activation.
+ */
+export function recoverMultiFrontierRun(
+  state: MultiFrontierRunState,
+  input: RecoverMultiFrontierRunInput,
+): MultiFrontierRunState {
+  assertTimestamp(input.now, "recovery time");
+  if (TERMINAL_PHASES.has(state.phase) || state.phase === "paused") {
+    return state;
+  }
+
+  const checkpointId = state.checkpointIds.at(-1);
+  return {
+    ...state,
+    phase: "paused",
+    participants: state.participants.map((participant) => ({
+      ...participant,
+      role: "watchdog",
+      permission: "read_only",
+      status: participant.status === "running" ? "waiting" : participant.status,
+    })),
+    driver: state.driver ? { ...state.driver, leaseState: "revoked" } : null,
+    recovery: {
+      reason: input.reason,
+      recoveredAt: input.now,
+      resumablePhase: state.phase,
+      ...(checkpointId ? { checkpointId } : {}),
+    },
+  };
+}
+
+/** Persist the recovery decision made by the main-process coordinator. */
+export function recoverStoredMultiFrontierRun(
+  collaborationId: string,
+  input: RecoverMultiFrontierRunInput,
+): MultiFrontierStoredRun | null {
+  return mutateStoredMultiFrontierRun(collaborationId, input.now, (current) => {
+    const recovered = recoverMultiFrontierRun(current, input);
+    return recovered === current ? current : recovered;
+  });
+}
+
+/**
+ * Applies one durable coordinator-owned state transition under the run lock.
+ * A state-shaped result retains proposal and review references by default;
+ * returning a full stored record is the explicit escape hatch for a
+ * coordinator operation that intentionally changes those references.
+ */
+export function transitionStoredMultiFrontierRun(
+  collaborationId: string,
+  updatedAt: string,
+  transition: MultiFrontierCoordinatorTransition,
+): MultiFrontierStoredRun | null {
+  assertSafeId(collaborationId, "collaboration id");
+  assertTimestamp(updatedAt, "transition time");
+  if (typeof transition !== "function") {
+    throw new Error("Invalid multi-frontier coordinator transition.");
+  }
+
+  return mutateStoredMultiFrontierRun(collaborationId, updatedAt, (current) => {
+    const candidate = transition(cloneStoredMultiFrontierRun(current));
+    if (candidate === null) return null;
+    if (isThenable(candidate)) {
+      throw new Error(
+        "Multi-frontier coordinator transitions must be synchronous.",
+      );
+    }
+    if (
+      !candidate ||
+      typeof candidate !== "object" ||
+      Array.isArray(candidate)
+    ) {
+      throw new Error("Invalid multi-frontier coordinator transition state.");
+    }
+
+    const isFullStoredRun = hasStoredRunTimestamps(candidate);
+    if (
+      !isFullStoredRun &&
+      (Object.hasOwn(candidate, "createdAt") ||
+        Object.hasOwn(candidate, "updatedAt"))
+    ) {
+      throw new Error("Invalid multi-frontier coordinator transition state.");
+    }
+    if (
+      candidate.schemaVersion !== current.schemaVersion ||
+      candidate.collaborationId !== current.collaborationId
+    ) {
+      throw new Error(
+        "Multi-frontier coordinator transitions cannot change run identity.",
+      );
+    }
+    if (isFullStoredRun) {
+      if (!isCompleteMultiFrontierStoredRun(candidate)) {
+        throw new Error("Invalid multi-frontier coordinator transition state.");
+      }
+      if (candidate.createdAt !== current.createdAt) {
+        throw new Error(
+          "Multi-frontier coordinator transitions cannot change creation time.",
+        );
+      }
+    }
+
+    const nextState: MultiFrontierRunState = {
+      ...candidate,
+      ...(isFullStoredRun
+        ? {}
+        : {
+            proposalIds: [...current.proposalIds],
+            reviewIds: [...current.reviewIds],
+          }),
+    };
+    if (!isCompleteMultiFrontierRunState(nextState)) {
+      throw new Error("Invalid multi-frontier coordinator transition state.");
+    }
+    return nextState;
+  });
+}
+
+/**
+ * Coordinators must call this before applying a participant event. Write
+ * events are accepted only from the active driver generation.
+ */
+export function canApplyMultiFrontierParticipantEvent(
+  state: MultiFrontierRunState,
+  event: MultiFrontierParticipantEvent,
+): boolean {
+  if (TERMINAL_PHASES.has(state.phase) || state.phase === "paused") {
+    return false;
+  }
+  if (
+    !state.participants.some(
+      (candidate) => candidate.participantId === event.participantId,
+    )
+  ) {
+    return false;
+  }
+  if (event.permission === "read_only") return true;
+  const driver = state.driver;
+  return Boolean(
+    state.phase === "implementing" &&
+    driver?.leaseState === "active" &&
+    driver.participantId === event.participantId &&
+    driver.generation === event.generation,
+  );
+}
+
+/**
+ * Explicitly restores a write lease after recovery. The generation increments
+ * so an event from the interrupted process can never regain write authority.
+ */
+export function reactivateMultiFrontierDriver(
+  state: MultiFrontierRunState,
+  participantId: string,
+): MultiFrontierRunState | null {
+  if (
+    state.phase !== "paused" ||
+    !state.recovery ||
+    state.recovery.resumablePhase !== "implementing" ||
+    state.approval.state === "pending"
+  ) {
+    return null;
+  }
+  const participant = state.participants.find(
+    (candidate) => candidate.participantId === participantId,
+  );
+  if (!participant || participant.status === "failed") return null;
+
+  const nextGeneration = (state.driver?.generation ?? 0) + 1;
+  return {
+    ...state,
+    phase: state.recovery.resumablePhase,
+    participants: state.participants.map((candidate) => ({
+      ...candidate,
+      role: candidate.participantId === participantId ? "driver" : "watchdog",
+      permission:
+        candidate.participantId === participantId
+          ? "workspace_write"
+          : "read_only",
+      status:
+        candidate.participantId === participantId
+          ? "waiting"
+          : candidate.status,
+    })),
+    driver: {
+      participantId,
+      generation: nextGeneration,
+      leaseState: "active",
+    },
+    recovery: undefined,
+  };
+}
+
+/** Assign the first explicit write lease for an implementing run. */
+export function activateMultiFrontierDriver(
+  state: MultiFrontierRunState,
+  participantId: string,
+): MultiFrontierRunState | null {
+  if (
+    state.phase !== "implementing" ||
+    state.approval.state === "pending" ||
+    state.driver?.leaseState === "active"
+  ) {
+    return null;
+  }
+  const participant = state.participants.find(
+    (candidate) => candidate.participantId === participantId,
+  );
+  if (!participant || participant.status === "failed") return null;
+
+  return {
+    ...state,
+    participants: state.participants.map((candidate) => ({
+      ...candidate,
+      role: candidate.participantId === participantId ? "driver" : "watchdog",
+      permission:
+        candidate.participantId === participantId
+          ? "workspace_write"
+          : "read_only",
+    })),
+    driver: {
+      participantId,
+      generation: (state.driver?.generation ?? 0) + 1,
+      leaseState: "active",
+    },
+  };
+}
+
+/** Persist the first explicit driver activation from the main-process coordinator. */
+export function activateStoredMultiFrontierDriver(
+  collaborationId: string,
+  participantId: string,
+  now = new Date().toISOString(),
+): MultiFrontierStoredRun | null {
+  assertTimestamp(now, "activation time");
+  return mutateStoredMultiFrontierRun(collaborationId, now, (current) =>
+    activateMultiFrontierDriver(current, participantId),
+  );
+}
+
+/** Persist an explicit driver reactivation after the human-approved resume. */
+export function reactivateStoredMultiFrontierDriver(
+  collaborationId: string,
+  participantId: string,
+  now = new Date().toISOString(),
+): MultiFrontierStoredRun | null {
+  assertTimestamp(now, "reactivation time");
+  return mutateStoredMultiFrontierRun(collaborationId, now, (current) =>
+    reactivateMultiFrontierDriver(current, participantId),
+  );
+}
+
+/**
+ * Appends an idempotent participant event after the coordinator has fenced it.
+ * The event journal is diagnostic; state is mutated only through this guarded
+ * coordinator entry point.
+ */
+export function appendMultiFrontierParticipantEvent(
+  input: AppendMultiFrontierParticipantEventInput,
+): AppendMultiFrontierParticipantEventResult {
+  assertSafeId(input.id, "event id");
+  assertSafeId(input.collaborationId, "collaboration id");
+  assertSafeId(input.participantId, "participant id");
+  const createdAt = input.createdAt ?? new Date().toISOString();
+  assertTimestamp(createdAt, "event time");
+
+  const runPath = multiFrontierRunPath(input.collaborationId);
+  return withFileLockSync(runPath, () => {
+    const current = readStoredRun(runPath);
+    if (!current) return { accepted: false, reason: "missing-run", run: null };
+    const existing = listMultiFrontierParticipantEvents(
+      input.collaborationId,
+    ).find((event) => event.id === input.id);
+    if (existing) {
+      if (!isMatchingParticipantEvent(existing, input)) {
+        return { accepted: false, reason: "event-conflict", run: current };
+      }
+      return {
+        accepted: true,
+        deduplicated: true,
+        event: existing,
+        run: current,
+      };
+    }
+    if (
+      !current.participants.some(
+        (candidate) => candidate.participantId === input.participantId,
+      )
+    ) {
+      return { accepted: false, reason: "missing-participant", run: current };
+    }
+    if (!canApplyMultiFrontierParticipantEvent(current, input)) {
+      return { accepted: false, reason: "stale-driver", run: current };
+    }
+    const participant = current.participants.find(
+      (candidate) => candidate.participantId === input.participantId,
+    );
+    if (
+      input.status !== undefined &&
+      (participant?.status === "completed" ||
+        participant?.status === "failed") &&
+      input.status !== participant.status
+    ) {
+      return { accepted: false, reason: "terminal-participant", run: current };
+    }
+
+    const event: PersistedMultiFrontierParticipantEvent = {
+      schemaVersion: 1,
+      id: input.id,
+      collaborationId: input.collaborationId,
+      participantId: input.participantId,
+      permission: input.permission,
+      createdAt,
+      ...(input.generation === undefined
+        ? {}
+        : { generation: input.generation }),
+      ...(input.status === undefined ? {} : { status: input.status }),
+    };
+    appendParticipantEvent(event);
+    compactParticipantEventJournal(input.collaborationId);
+    const status = input.status;
+    const participants = status
+      ? current.participants.map((candidate) =>
+          candidate.participantId === input.participantId
+            ? { ...candidate, status }
+            : candidate,
+        )
+      : current.participants;
+    const run = writeNextStoredRun(
+      current,
+      { ...current, participants },
+      createdAt,
+    );
+    return { accepted: true, deduplicated: false, event, run };
+  });
+}
+
+/**
+ * Appends a bounded proposal, review, or checkpoint index record. The
+ * coordinator owns both the artifact and its run-state reference under one
+ * run lock, so a reader never observes a durable reference without its record.
+ */
+export function appendMultiFrontierArtifact(
+  input: AppendMultiFrontierArtifactInput,
+): AppendMultiFrontierArtifactResult {
+  assertArtifactInput(input);
+  const createdAt = input.createdAt ?? new Date().toISOString();
+  assertTimestamp(createdAt, "artifact time");
+  const artifact = toPersistedArtifact(input, createdAt);
+  const runPath = multiFrontierRunPath(input.collaborationId);
+  return withFileLockSync(runPath, () => {
+    const current = readStoredRun(runPath);
+    if (!current) return { accepted: false, reason: "missing-run", run: null };
+    if (
+      input.participantId !== undefined &&
+      !current.participants.some(
+        (participant) => participant.participantId === input.participantId,
+      )
+    ) {
+      return { accepted: false, reason: "missing-participant", run: current };
+    }
+    if (
+      input.supersedesArtifactId !== undefined &&
+      !readStoredArtifact(
+        multiFrontierArtifactPath(
+          input.collaborationId,
+          input.supersedesArtifactId,
+        ),
+      )
+    ) {
+      return {
+        accepted: false,
+        reason: "missing-superseded-artifact",
+        run: current,
+      };
+    }
+
+    const artifactPath = multiFrontierArtifactPath(
+      input.collaborationId,
+      input.id,
+    );
+    const existing = readStoredArtifact(artifactPath);
+    if (existing) {
+      if (!isMatchingArtifact(existing, artifact)) {
+        return { accepted: false, reason: "artifact-conflict", run: current };
+      }
+      const ids = artifactIdsForKind(current, existing.kind);
+      const run = ids.includes(existing.id)
+        ? current
+        : writeNextStoredRun(
+            current,
+            withArtifactId(current, existing.kind, existing.id),
+            new Date().toISOString(),
+          );
+      return {
+        accepted: true,
+        deduplicated: true,
+        artifact: existing,
+        run,
+      };
+    }
+    if (fs.existsSync(artifactPath)) {
+      return { accepted: false, reason: "artifact-conflict", run: current };
+    }
+    if (
+      listMultiFrontierArtifacts(input.collaborationId).length >=
+      MAX_MULTI_FRONTIER_ARTIFACTS_PER_RUN
+    ) {
+      return {
+        accepted: false,
+        reason: "artifact-limit-reached",
+        run: current,
+      };
+    }
+
+    writeJsonFileAtomically(artifactPath, artifact, { mode: 0o600 });
+    const ids = artifactIdsForKind(current, artifact.kind);
+    const next = ids.includes(artifact.id)
+      ? current
+      : withArtifactId(current, artifact.kind, artifact.id);
+    const run = writeNextStoredRun(current, next, createdAt);
+    return { accepted: true, deduplicated: false, artifact, run };
+  });
+}
+
+export function getMultiFrontierArtifact(
+  collaborationId: string,
+  artifactId: string,
+): PersistedMultiFrontierArtifact | null {
+  if (!SAFE_ID.test(collaborationId) || !SAFE_ID.test(artifactId)) return null;
+  return readStoredArtifact(
+    multiFrontierArtifactPath(collaborationId, artifactId),
+  );
+}
+
+export function listMultiFrontierArtifacts(
+  collaborationId: string,
+): PersistedMultiFrontierArtifact[] {
+  if (!SAFE_ID.test(collaborationId)) return [];
+  const directory = multiFrontierArtifactsRunDir(collaborationId);
+  if (!fs.existsSync(directory)) return [];
+  return fs
+    .readdirSync(directory)
+    .filter((file) => file.endsWith(".json"))
+    .map((file) => readStoredArtifact(path.join(directory, file)))
+    .filter(
+      (artifact): artifact is PersistedMultiFrontierArtifact =>
+        artifact !== null,
+    )
+    .sort((left, right) => left.createdAt.localeCompare(right.createdAt));
+}
+
+export function listMultiFrontierParticipantEvents(
+  collaborationId: string,
+): PersistedMultiFrontierParticipantEvent[] {
+  if (!SAFE_ID.test(collaborationId)) return [];
+  const eventPath = multiFrontierParticipantEventsPath(collaborationId);
+  if (!fs.existsSync(eventPath)) return [];
+  return fs
+    .readFileSync(eventPath, "utf-8")
+    .split(/\r?\n/)
+    .filter(Boolean)
+    .map(readParticipantEvent)
+    .filter(
+      (event): event is PersistedMultiFrontierParticipantEvent =>
+        event !== null,
+    );
+}
+
+export function getMultiFrontierParticipantEventRetention(
+  collaborationId: string,
+): MultiFrontierParticipantEventRetention | null {
+  if (!SAFE_ID.test(collaborationId)) return null;
+  return readParticipantEventRetention(
+    multiFrontierParticipantEventRetentionPath(collaborationId),
+  );
+}
+
+/**
+ * Coordinator maintenance for a bounded event journal. It deliberately keeps
+ * the newest contiguous tail and a replay marker instead of deleting run state.
+ */
+export function compactMultiFrontierParticipantEvents(
+  collaborationId: string,
+  limits = DEFAULT_MULTI_FRONTIER_PARTICIPANT_EVENT_RETENTION,
+): MultiFrontierParticipantEventRetention | null {
+  assertSafeId(collaborationId, "collaboration id");
+  assertRetentionLimits(limits);
+  const runPath = multiFrontierRunPath(collaborationId);
+  return withFileLockSync(runPath, () => {
+    if (!readStoredRun(runPath)) return null;
+    return compactParticipantEventJournal(collaborationId, limits);
+  });
+}
+
+function writeMultiFrontierRun(run: MultiFrontierStoredRun): void {
+  writeJsonFileAtomically(multiFrontierRunPath(run.collaborationId), run);
+}
+
+function writeNewMultiFrontierRun(run: MultiFrontierStoredRun): void {
+  const filePath = multiFrontierRunPath(run.collaborationId);
+  withFileLockSync(filePath, () => {
+    if (fs.existsSync(filePath)) {
+      throw new Error(
+        `Multi-frontier run already exists: ${run.collaborationId}`,
+      );
+    }
+    writeJsonFileAtomically(filePath, run);
+  });
+}
+
+function writeNextStoredRun(
+  current: MultiFrontierStoredRun,
+  nextState: MultiFrontierRunState,
+  updatedAt: string,
+): MultiFrontierStoredRun {
+  const next: MultiFrontierStoredRun = {
+    ...nextState,
+    createdAt: current.createdAt,
+    updatedAt,
+  };
+  writeMultiFrontierRun(next);
+  return next;
+}
+
+function appendParticipantEvent(
+  event: PersistedMultiFrontierParticipantEvent,
+): void {
+  appendUniqueJsonLineAtomically(
+    multiFrontierParticipantEventsPath(event.collaborationId),
+    event,
+    readParticipantEventValue,
+    { mode: 0o600 },
+  );
+}
+
+function compactParticipantEventJournal(
+  collaborationId: string,
+  limits = DEFAULT_MULTI_FRONTIER_PARTICIPANT_EVENT_RETENTION,
+): MultiFrontierParticipantEventRetention {
+  const eventPath = multiFrontierParticipantEventsPath(collaborationId);
+  return withFileLockSync(eventPath, () => {
+    const previous = readParticipantEventRetention(
+      multiFrontierParticipantEventRetentionPath(collaborationId),
+    );
+    const events = listMultiFrontierParticipantEvents(collaborationId);
+    const retained: PersistedMultiFrontierParticipantEvent[] = [];
+    let retainedByteCount = 0;
+    for (const event of [...events].reverse()) {
+      const bytes = eventLineByteLength(event);
+      if (
+        retained.length >= limits.maxEventCount ||
+        retainedByteCount + bytes > limits.maxBytes
+      ) {
+        break;
+      }
+      retained.push(event);
+      retainedByteCount += bytes;
+    }
+    retained.reverse();
+    const retainedIds = new Set(retained.map((event) => event.id));
+    const dropped = events.filter((event) => !retainedIds.has(event.id));
+    if (dropped.length > 0) {
+      writeTextFileAtomically(
+        eventPath,
+        retained.map((event) => `${JSON.stringify(event)}\n`).join(""),
+      );
+    }
+    const retention: MultiFrontierParticipantEventRetention = {
+      schemaVersion: 1,
+      retainedEventCount: retained.length,
+      retainedByteCount,
+      droppedEventCount: (previous?.droppedEventCount ?? 0) + dropped.length,
+      droppedByteCount:
+        (previous?.droppedByteCount ?? 0) +
+        dropped.reduce((total, event) => total + eventLineByteLength(event), 0),
+      truncated: (previous?.truncated ?? false) || dropped.length > 0,
+      replay: {
+        requiresSnapshot: (previous?.truncated ?? false) || dropped.length > 0,
+        ...(retained[0] ? { firstRetainedEventId: retained[0].id } : {}),
+      },
+    };
+    writeJsonFileAtomically(
+      multiFrontierParticipantEventRetentionPath(collaborationId),
+      retention,
+      { mode: 0o600 },
+    );
+    return retention;
+  });
+}
+
+function mutateStoredMultiFrontierRun(
+  collaborationId: string,
+  updatedAt: string,
+  mutate: (current: MultiFrontierStoredRun) => MultiFrontierRunState | null,
+): MultiFrontierStoredRun | null {
+  const filePath = multiFrontierRunPath(collaborationId);
+  return withFileLockSync(filePath, () => {
+    const current = readStoredRun(filePath);
+    if (!current) return null;
+    const nextState = mutate(current);
+    if (!nextState) return null;
+    const next: MultiFrontierStoredRun = {
+      ...nextState,
+      createdAt: current.createdAt,
+      updatedAt,
+    };
+    writeMultiFrontierRun(next);
+    return next;
+  });
+}
+
+function multiFrontierRunPath(collaborationId: string): string {
+  return path.join(multiFrontierRunsDir(), `${collaborationId}.json`);
+}
+
+function multiFrontierParticipantEventsPath(collaborationId: string): string {
+  return path.join(
+    multiFrontierParticipantEventsDir(),
+    `${collaborationId}.jsonl`,
+  );
+}
+
+function multiFrontierParticipantEventRetentionPath(
+  collaborationId: string,
+): string {
+  return path.join(
+    multiFrontierParticipantEventsDir(),
+    `${collaborationId}.retention.json`,
+  );
+}
+
+function multiFrontierArtifactsRunDir(collaborationId: string): string {
+  return path.join(multiFrontierArtifactsDir(), collaborationId);
+}
+
+function multiFrontierArtifactPath(
+  collaborationId: string,
+  artifactId: string,
+): string {
+  return path.join(
+    multiFrontierArtifactsRunDir(collaborationId),
+    `${artifactId}.json`,
+  );
+}
+
+function readStoredRun(filePath: string): MultiFrontierStoredRun | null {
+  try {
+    const raw = JSON.parse(fs.readFileSync(filePath, "utf-8")) as unknown;
+    const normalized = normalizeStoredRunDefaults(raw);
+    return isCompleteMultiFrontierStoredRun(normalized) ? normalized : null;
+  } catch {
+    return null;
+  }
+}
+
+function isCompleteMultiFrontierStoredRun(
+  value: unknown,
+): value is MultiFrontierStoredRun {
+  if (!hasStoredRunTimestamps(value)) return false;
+  return (
+    isCompleteMultiFrontierRunState(value) &&
+    !Number.isNaN(Date.parse(value.createdAt)) &&
+    !Number.isNaN(Date.parse(value.updatedAt))
+  );
+}
+
+function isCompleteMultiFrontierRunState(
+  value: unknown,
+): value is MultiFrontierRunState {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+  const run = value as Partial<MultiFrontierRunState>;
+  return (
+    run.schemaVersion === 1 &&
+    typeof run.collaborationId === "string" &&
+    SAFE_ID.test(run.collaborationId) &&
+    (run.workspaceId === undefined ||
+      (typeof run.workspaceId === "string" && SAFE_ID.test(run.workspaceId))) &&
+    isPhase(run.phase) &&
+    isStoredRunParticipantsAndDriverValid(run.participants, run.driver) &&
+    isApproval(run.approval) &&
+    Array.isArray(run.checkpointIds) &&
+    run.checkpointIds.every(
+      (checkpointId) => typeof checkpointId === "string",
+    ) &&
+    typeof run.round === "number" &&
+    Number.isInteger(run.round) &&
+    run.round >= 1 &&
+    isStringArray(run.proposalIds) &&
+    isStringArray(run.reviewIds) &&
+    typeof run.autoContinueAfterAgreement === "boolean" &&
+    (run.recovery === undefined || isRecovery(run.recovery))
+  );
+}
+
+function normalizeStoredRunDefaults(value: unknown): unknown {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return value;
+  if (!Object.hasOwn(value, "autoContinueAfterAgreement")) {
+    return { ...value, autoContinueAfterAgreement: false };
+  }
+  return value;
+}
+
+function hasStoredRunTimestamps(
+  value: unknown,
+): value is MultiFrontierStoredRun {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+  const run = value as Partial<MultiFrontierStoredRun>;
+  return typeof run.createdAt === "string" && typeof run.updatedAt === "string";
+}
+
+function cloneStoredMultiFrontierRun(
+  run: MultiFrontierStoredRun,
+): MultiFrontierStoredRun {
+  return JSON.parse(JSON.stringify(run)) as MultiFrontierStoredRun;
+}
+
+function isThenable(value: unknown): value is PromiseLike<unknown> {
+  return (
+    Boolean(value) &&
+    (typeof value === "object" || typeof value === "function") &&
+    typeof (value as { then?: unknown }).then === "function"
+  );
+}
+
+function readParticipantEvent(
+  line: string,
+): PersistedMultiFrontierParticipantEvent | null {
+  try {
+    return readParticipantEventValue(JSON.parse(line) as unknown);
+  } catch {
+    return null;
+  }
+}
+
+function readParticipantEventValue(
+  raw: unknown,
+): PersistedMultiFrontierParticipantEvent | null {
+  try {
+    if (!raw || typeof raw !== "object") return null;
+    const event = raw as Partial<PersistedMultiFrontierParticipantEvent>;
+    if (
+      event.schemaVersion !== 1 ||
+      typeof event.id !== "string" ||
+      typeof event.collaborationId !== "string" ||
+      typeof event.participantId !== "string" ||
+      !isPermission(event.permission) ||
+      (event.generation !== undefined &&
+        typeof event.generation !== "number") ||
+      (event.status !== undefined && !isParticipantStatus(event.status)) ||
+      typeof event.createdAt !== "string" ||
+      Number.isNaN(Date.parse(event.createdAt))
+    ) {
+      return null;
+    }
+    return event as PersistedMultiFrontierParticipantEvent;
+  } catch {
+    return null;
+  }
+}
+
+function readStoredArtifact(
+  filePath: string,
+): PersistedMultiFrontierArtifact | null {
+  try {
+    return readArtifactValue(
+      JSON.parse(fs.readFileSync(filePath, "utf-8")) as unknown,
+    );
+  } catch {
+    return null;
+  }
+}
+
+function readArtifactValue(
+  raw: unknown,
+): PersistedMultiFrontierArtifact | null {
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) return null;
+  const artifact = raw as Partial<PersistedMultiFrontierArtifact>;
+  if (
+    artifact.schemaVersion !== 1 ||
+    !isSafeId(artifact.id) ||
+    !isSafeId(artifact.collaborationId) ||
+    !isArtifactKind(artifact.kind) ||
+    typeof artifact.createdAt !== "string" ||
+    Number.isNaN(Date.parse(artifact.createdAt)) ||
+    (artifact.participantId !== undefined &&
+      !isSafeId(artifact.participantId)) ||
+    !isBoundedText(artifact.title, MAX_ARTIFACT_TITLE_BYTES) ||
+    !isArtifactSummary(artifact.summary) ||
+    (artifact.supersedesArtifactId !== undefined &&
+      !isSafeId(artifact.supersedesArtifactId)) ||
+    (artifact.contentHash !== undefined &&
+      !SAFE_CONTENT_HASH.test(artifact.contentHash)) ||
+    !isArtifactFileRefs(artifact.fileRefs) ||
+    !isArtifactTestSummaries(artifact.testSummary) ||
+    !isOrchestrationArtifact(artifact.orchestration)
+  ) {
+    return null;
+  }
+  return artifact as PersistedMultiFrontierArtifact;
+}
+
+function readParticipantEventRetention(
+  filePath: string,
+): MultiFrontierParticipantEventRetention | null {
+  try {
+    const raw = JSON.parse(fs.readFileSync(filePath, "utf-8")) as unknown;
+    if (!raw || typeof raw !== "object" || Array.isArray(raw)) return null;
+    const retention = raw as Partial<MultiFrontierParticipantEventRetention>;
+    if (
+      retention.schemaVersion !== 1 ||
+      !isNonNegativeInteger(retention.retainedEventCount) ||
+      !isNonNegativeInteger(retention.retainedByteCount) ||
+      !isNonNegativeInteger(retention.droppedEventCount) ||
+      !isNonNegativeInteger(retention.droppedByteCount) ||
+      typeof retention.truncated !== "boolean" ||
+      !retention.replay ||
+      typeof retention.replay !== "object" ||
+      typeof retention.replay.requiresSnapshot !== "boolean" ||
+      (retention.replay.firstRetainedEventId !== undefined &&
+        !isSafeId(retention.replay.firstRetainedEventId))
+    ) {
+      return null;
+    }
+    return retention as MultiFrontierParticipantEventRetention;
+  } catch {
+    return null;
+  }
+}
+
+function assertArtifactInput(input: AppendMultiFrontierArtifactInput): void {
+  assertAllowlistedArtifactInput(input);
+  assertSafeId(input.id, "artifact id");
+  assertSafeId(input.collaborationId, "collaboration id");
+  if (!isArtifactKind(input.kind))
+    throw new Error("Invalid multi-frontier artifact kind.");
+  if (input.participantId !== undefined) {
+    assertSafeId(input.participantId, "participant id");
+  }
+  assertBoundedText(input.title, MAX_ARTIFACT_TITLE_BYTES, "artifact title");
+  if (!isArtifactSummary(input.summary)) {
+    throw new Error("Invalid multi-frontier artifact summary.");
+  }
+  if (input.supersedesArtifactId !== undefined) {
+    assertSafeId(input.supersedesArtifactId, "superseded artifact id");
+  }
+  if (
+    input.contentHash !== undefined &&
+    !SAFE_CONTENT_HASH.test(input.contentHash)
+  ) {
+    throw new Error("Invalid multi-frontier artifact content hash.");
+  }
+  if (!isArtifactFileRefs(input.fileRefs)) {
+    throw new Error("Invalid multi-frontier artifact file references.");
+  }
+  if (!isArtifactTestSummaries(input.testSummary)) {
+    throw new Error("Invalid multi-frontier artifact test summary.");
+  }
+  if (!isOrchestrationArtifact(input.orchestration)) {
+    throw new Error("Invalid multi-frontier orchestration artifact.");
+  }
+}
+
+function assertAllowlistedArtifactInput(
+  input: AppendMultiFrontierArtifactInput,
+): void {
+  const allowed = new Set([
+    "id",
+    "collaborationId",
+    "kind",
+    "createdAt",
+    "participantId",
+    "title",
+    "summary",
+    "supersedesArtifactId",
+    "contentHash",
+    "fileRefs",
+    "testSummary",
+    "orchestration",
+  ]);
+  if (
+    !input ||
+    typeof input !== "object" ||
+    Array.isArray(input) ||
+    Object.keys(input).some((key) => !allowed.has(key))
+  ) {
+    throw new Error(
+      "Multi-frontier artifacts only accept allowlisted summary fields.",
+    );
+  }
+}
+
+function toPersistedArtifact(
+  input: AppendMultiFrontierArtifactInput,
+  createdAt: string,
+): PersistedMultiFrontierArtifact {
+  return {
+    schemaVersion: 1,
+    id: input.id,
+    collaborationId: input.collaborationId,
+    kind: input.kind,
+    createdAt,
+    title: input.title,
+    summary: input.summary,
+    ...(input.participantId === undefined
+      ? {}
+      : { participantId: input.participantId }),
+    ...(input.supersedesArtifactId === undefined
+      ? {}
+      : { supersedesArtifactId: input.supersedesArtifactId }),
+    ...(input.contentHash === undefined
+      ? {}
+      : { contentHash: input.contentHash }),
+    ...(input.fileRefs === undefined ? {} : { fileRefs: [...input.fileRefs] }),
+    ...(input.testSummary === undefined
+      ? {}
+      : {
+          testSummary: input.testSummary.map((summary) => ({ ...summary })),
+        }),
+    ...(input.orchestration === undefined
+      ? {}
+      : { orchestration: cloneOrchestrationArtifact(input.orchestration) }),
+  };
+}
+
+function artifactIdsForKind(
+  run: MultiFrontierStoredRun,
+  kind: MultiFrontierArtifactKind,
+): string[] {
+  if (kind === "proposal") return run.proposalIds;
+  if (kind === "review") return run.reviewIds;
+  return run.checkpointIds;
+}
+
+function withArtifactId(
+  run: MultiFrontierStoredRun,
+  kind: MultiFrontierArtifactKind,
+  artifactId: string,
+): MultiFrontierStoredRun {
+  if (kind === "proposal") {
+    return { ...run, proposalIds: [...run.proposalIds, artifactId] };
+  }
+  if (kind === "review") {
+    return { ...run, reviewIds: [...run.reviewIds, artifactId] };
+  }
+  return { ...run, checkpointIds: [...run.checkpointIds, artifactId] };
+}
+
+function isMatchingArtifact(
+  existing: PersistedMultiFrontierArtifact,
+  candidate: PersistedMultiFrontierArtifact,
+): boolean {
+  return JSON.stringify(existing) === JSON.stringify(candidate);
+}
+
+function isArtifactKind(value: unknown): value is MultiFrontierArtifactKind {
+  return value === "proposal" || value === "review" || value === "checkpoint";
+}
+
+function isArtifactSummary(value: unknown): value is string {
+  return (
+    isBoundedText(value, MAX_ARTIFACT_SUMMARY_BYTES) &&
+    !/(?:^|\n)diff --git\s|(?:^|\n)@@\s+-\d+/m.test(value)
+  );
+}
+
+function isArtifactFileRefs(value: unknown): value is string[] | undefined {
+  return (
+    value === undefined ||
+    (Array.isArray(value) &&
+      value.length <= MAX_ARTIFACT_FILE_REFS &&
+      value.every(
+        (fileRef) =>
+          typeof fileRef === "string" &&
+          Buffer.byteLength(fileRef, "utf-8") <= 512 &&
+          SAFE_FILE_REF.test(fileRef),
+      ))
+  );
+}
+
+function isArtifactTestSummaries(
+  value: unknown,
+): value is MultiFrontierArtifactTestSummary[] | undefined {
+  return (
+    value === undefined ||
+    (Array.isArray(value) &&
+      value.length <= MAX_ARTIFACT_TEST_SUMMARIES &&
+      value.every(
+        (summary) =>
+          Boolean(summary) &&
+          typeof summary === "object" &&
+          isBoundedText(
+            (summary as MultiFrontierArtifactTestSummary).name,
+            MAX_ARTIFACT_TEST_NAME_BYTES,
+          ) &&
+          ["passed", "failed", "skipped"].includes(
+            (summary as MultiFrontierArtifactTestSummary).status,
+          ) &&
+          ((summary as MultiFrontierArtifactTestSummary).summary ===
+            undefined ||
+            isBoundedText(
+              (summary as MultiFrontierArtifactTestSummary).summary,
+              MAX_ARTIFACT_TEST_SUMMARY_BYTES,
+            )),
+      ))
+  );
+}
+
+function isOrchestrationArtifact(
+  value: unknown,
+): value is MultiFrontierOrchestrationArtifact | undefined {
+  if (value === undefined) return true;
+  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+  const artifact = value as Partial<MultiFrontierOrchestrationArtifact>;
+  return (
+    hasExactKeys(artifact, [
+      "id",
+      "kind",
+      "round",
+      "participantId",
+      "text",
+      "attribution",
+      "supersedesArtifactId",
+      "metadata",
+    ]) &&
+    isSafeId(artifact.id) &&
+    [
+      "proposal",
+      "cross_review",
+      "revision",
+      "synthesis",
+      "checkpoint",
+      "watchdog_review",
+      "finding_disposition",
+      "completion",
+    ].includes(artifact.kind ?? "") &&
+    Number.isSafeInteger(artifact.round) &&
+    artifact.round! >= 1 &&
+    artifact.round! <= 3 &&
+    (artifact.participantId === undefined ||
+      isSafeId(artifact.participantId)) &&
+    isSafeOrchestrationText(artifact.text) &&
+    isOrchestrationAttribution(artifact.attribution) &&
+    (artifact.supersedesArtifactId === undefined ||
+      isSafeId(artifact.supersedesArtifactId)) &&
+    isSafeOrchestrationMetadata(artifact.kind!, artifact.metadata)
+  );
+}
+
+function hasExactKeys(value: object, allowed: readonly string[]): boolean {
+  return Object.keys(value).every((key) => allowed.includes(key));
+}
+
+function isOrchestrationAttribution(
+  value: unknown,
+): value is MultiFrontierOrchestrationArtifact["attribution"] {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+  const attribution = value as Partial<
+    MultiFrontierOrchestrationArtifact["attribution"]
+  >;
+  return (
+    hasExactKeys(attribution as Record<string, unknown>, [
+      "participantIds",
+      "sourceArtifactIds",
+    ]) &&
+    isSafeIdArray(attribution.participantIds, 2) &&
+    isSafeIdArray(
+      attribution.sourceArtifactIds,
+      MAX_MULTI_FRONTIER_ARTIFACTS_PER_RUN,
+    )
+  );
+}
+
+function isSafeIdArray(value: unknown, max: number): value is string[] {
+  return (
+    Array.isArray(value) &&
+    value.length <= max &&
+    value.every((item) => isSafeId(item))
+  );
+}
+
+function isSafeOrchestrationText(value: unknown): value is string {
+  return (
+    isArtifactSummary(value) &&
+    !/(?:bearer\s+|api[_-]?key\s*[:=]|authorization\s*[:=]|(?:sk|rk|pk)[_-][A-Za-z0-9_-]{12,}|(?:access|refresh)[_-]?token\s*[:=])/i.test(
+      value,
+    )
+  );
+}
+
+function isSafeOrchestrationMetadata(
+  kind: NonNullable<MultiFrontierOrchestrationArtifact["kind"]>,
+  value: unknown,
+): value is Record<string, unknown> | undefined {
+  const allowedKeys = metadataKeysForOrchestrationKind(kind);
+  if (allowedKeys.length === 0) return value === undefined;
+  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+  const entries = Object.entries(value);
+  if (
+    entries.length === 0 ||
+    entries.some(([key]) => !allowedKeys.includes(key)) ||
+    entries.some(([key]) =>
+      /(token|secret|authorization|credential|password|email|organization|account)/i.test(
+        key,
+      ),
+    )
+  ) {
+    return false;
+  }
+  try {
+    return (
+      isArtifactSummary(JSON.stringify(value)) &&
+      isValidOrchestrationMetadata(kind, value as Record<string, unknown>)
+    );
+  } catch {
+    return false;
+  }
+}
+
+function isValidOrchestrationMetadata(
+  kind: NonNullable<MultiFrontierOrchestrationArtifact["kind"]>,
+  metadata: Record<string, unknown>,
+): boolean {
+  if (kind === "synthesis") {
+    return (
+      typeof metadata.agreed === "boolean" &&
+      typeof metadata.deterministicallyResolved === "boolean" &&
+      (metadata.reversibleResolution === undefined ||
+        isReversibleResolution(metadata.reversibleResolution))
+    );
+  }
+  if (kind === "checkpoint") return isCheckpointBundle(metadata.bundle);
+  if (kind === "cross_review" || kind === "watchdog_review") {
+    return isFindingList(metadata.findings);
+  }
+  if (kind === "finding_disposition") {
+    return isFindingDispositionList(metadata.dispositions);
+  }
+  if (kind === "completion") {
+    return (
+      isCompletionTests(metadata.tests) &&
+      isSafeTextList(metadata.proofRefs, 40) &&
+      isSafeTextList(metadata.remainingRisks, 40)
+    );
+  }
+  return false;
+}
+
+function isFindingList(value: unknown): boolean {
+  return (
+    Array.isArray(value) &&
+    value.length <= 40 &&
+    value.every((finding) => {
+      if (!finding || typeof finding !== "object" || Array.isArray(finding))
+        return false;
+      const item = finding as Record<string, unknown>;
+      return (
+        hasExactKeys(item, [
+          "id",
+          "category",
+          "summary",
+          "rawFindingId",
+          "reviewerParticipantId",
+        ]) &&
+        isSafeId(item.id) &&
+        isSafeOrchestrationText(item.summary) &&
+        isSafeId(item.rawFindingId) &&
+        isSafeId(item.reviewerParticipantId) &&
+        [
+          "reversible_technical",
+          "intent_or_scope",
+          "destructive_action",
+          "security_or_privacy",
+          "outward_effect",
+          "meaningful_cost_expansion",
+          "irreversible_architecture",
+        ].includes(item.category as string)
+      );
+    })
+  );
+}
+
+function isFindingDispositionList(value: unknown): boolean {
+  return (
+    Array.isArray(value) &&
+    value.length <= 40 &&
+    value.every((disposition) => {
+      if (
+        !disposition ||
+        typeof disposition !== "object" ||
+        Array.isArray(disposition)
+      )
+        return false;
+      const item = disposition as Record<string, unknown>;
+      return (
+        hasExactKeys(item, ["findingId", "disposition", "reason"]) &&
+        isSafeId(item.findingId) &&
+        ["addressed", "rejected", "deferred"].includes(
+          item.disposition as string,
+        ) &&
+        isSafeOrchestrationText(item.reason)
+      );
+    })
+  );
+}
+
+function isReversibleResolution(value: unknown): boolean {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+  const item = value as Record<string, unknown>;
+  return (
+    hasExactKeys(item, [
+      "alternatives",
+      "comparator",
+      "selected",
+      "reversibility",
+    ]) &&
+    isSafeTextList(item.alternatives, 8) &&
+    isSafeOrchestrationText(item.comparator) &&
+    isSafeOrchestrationText(item.selected) &&
+    isSafeOrchestrationText(item.reversibility)
+  );
+}
+
+function isCheckpointBundle(value: unknown): boolean {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+  const item = value as Record<string, unknown>;
+  return (
+    hasExactKeys(item, [
+      "requestSummary",
+      "requestRef",
+      "acceptedPlanArtifactId",
+      "contentRef",
+      "contentHash",
+      "testOutput",
+      "driverSummary",
+      "openRisks",
+      "unresolvedFindingIds",
+    ]) &&
+    isSafeOrchestrationText(item.requestSummary) &&
+    (item.requestRef === undefined || isSafeId(item.requestRef)) &&
+    isSafeId(item.acceptedPlanArtifactId) &&
+    typeof item.contentRef === "string" &&
+    /^(?!\/)(?!.*\.\.)[A-Za-z0-9._/@:-]{1,512}$/.test(item.contentRef) &&
+    typeof item.contentHash === "string" &&
+    SAFE_CONTENT_HASH.test(item.contentHash) &&
+    isSafeOrchestrationText(item.testOutput) &&
+    isSafeOrchestrationText(item.driverSummary) &&
+    isSafeTextList(item.openRisks, 40) &&
+    isSafeIdArray(item.unresolvedFindingIds, 40)
+  );
+}
+
+function isCompletionTests(value: unknown): boolean {
+  return (
+    Array.isArray(value) &&
+    value.length <= 40 &&
+    value.every((test) => {
+      if (!test || typeof test !== "object" || Array.isArray(test))
+        return false;
+      const item = test as Record<string, unknown>;
+      return (
+        hasExactKeys(item, ["name", "status", "evidence"]) &&
+        isSafeOrchestrationText(item.name) &&
+        ["passed", "failed", "skipped"].includes(item.status as string) &&
+        isSafeOrchestrationText(item.evidence)
+      );
+    })
+  );
+}
+
+function isSafeTextList(value: unknown, max: number): boolean {
+  return (
+    Array.isArray(value) &&
+    value.length <= max &&
+    value.every((item) => isSafeOrchestrationText(item))
+  );
+}
+
+function metadataKeysForOrchestrationKind(
+  kind: NonNullable<MultiFrontierOrchestrationArtifact["kind"]>,
+): string[] {
+  if (kind === "synthesis") {
+    return ["agreed", "deterministicallyResolved", "reversibleResolution"];
+  }
+  if (kind === "checkpoint") return ["bundle"];
+  if (kind === "cross_review" || kind === "watchdog_review") {
+    return ["findings"];
+  }
+  if (kind === "finding_disposition") return ["dispositions"];
+  if (kind === "completion") return ["tests", "proofRefs", "remainingRisks"];
+  return [];
+}
+
+function containsUnsafeOrchestrationValue(
+  value: unknown,
+  depth: number,
+): boolean {
+  if (depth > 8) return true;
+  if (typeof value === "string") return !isSafeOrchestrationText(value);
+  if (
+    value === null ||
+    typeof value === "boolean" ||
+    (typeof value === "number" && Number.isFinite(value))
+  ) {
+    return false;
+  }
+  if (Array.isArray(value)) {
+    return (
+      value.length > 40 ||
+      value.some((item) => containsUnsafeOrchestrationValue(item, depth + 1))
+    );
+  }
+  if (!value || typeof value !== "object") return true;
+  const entries = Object.entries(value);
+  return (
+    entries.length > 40 ||
+    entries.some(
+      ([key, item]) =>
+        !isBoundedText(key, 160) ||
+        /(token|secret|authorization|credential|password|email|organization|account)/i.test(
+          key,
+        ) ||
+        containsUnsafeOrchestrationValue(item, depth + 1),
+    )
+  );
+}
+
+function cloneOrchestrationArtifact(
+  artifact: MultiFrontierOrchestrationArtifact,
+): MultiFrontierOrchestrationArtifact {
+  return JSON.parse(
+    JSON.stringify(artifact),
+  ) as MultiFrontierOrchestrationArtifact;
+}
+
+function isBoundedText(value: unknown, maxBytes: number): value is string {
+  return (
+    typeof value === "string" &&
+    value.trim().length > 0 &&
+    Buffer.byteLength(value, "utf-8") <= maxBytes
+  );
+}
+
+function assertBoundedText(
+  value: unknown,
+  maxBytes: number,
+  label: string,
+): void {
+  if (!isBoundedText(value, maxBytes)) {
+    throw new Error(`Invalid multi-frontier ${label}.`);
+  }
+}
+
+function assertRetentionLimits(
+  limits: MultiFrontierParticipantEventRetentionLimits,
+): void {
+  if (
+    !isNonNegativeInteger(limits.maxEventCount) ||
+    limits.maxEventCount < 1 ||
+    !isNonNegativeInteger(limits.maxBytes) ||
+    limits.maxBytes < 512
+  ) {
+    throw new Error(
+      "Invalid multi-frontier participant event retention limits.",
+    );
+  }
+}
+
+function eventLineByteLength(
+  event: PersistedMultiFrontierParticipantEvent,
+): number {
+  return Buffer.byteLength(`${JSON.stringify(event)}\n`, "utf-8");
+}
+
+function isSafeId(value: unknown): value is string {
+  return typeof value === "string" && SAFE_ID.test(value);
+}
+
+function isNonNegativeInteger(value: unknown): value is number {
+  return typeof value === "number" && Number.isInteger(value) && value >= 0;
+}
+
+function assertParticipants(
+  participants: MultiFrontierParticipantState[],
+): void {
+  if (participants.length === 0) {
+    throw new Error("A multi-frontier run needs at least one participant.");
+  }
+  const participantIds = new Set<string>();
+  for (const participant of participants) {
+    if (!isParticipant(participant))
+      throw new Error("Invalid multi-frontier participant.");
+    assertSafeId(participant.participantId, "participant id");
+    if (participantIds.has(participant.participantId)) {
+      throw new Error(
+        `Duplicate multi-frontier participant id: ${participant.participantId}`,
+      );
+    }
+    participantIds.add(participant.participantId);
+  }
+}
+
+function isParticipant(value: unknown): value is MultiFrontierParticipantState {
+  if (!value || typeof value !== "object") return false;
+  const participant = value as Partial<MultiFrontierParticipantState>;
+  return (
+    typeof participant.participantId === "string" &&
+    SAFE_ID.test(participant.participantId) &&
+    typeof participant.provider === "string" &&
+    participant.provider.length > 0 &&
+    typeof participant.runtime === "string" &&
+    participant.runtime.length > 0 &&
+    (participant.model === undefined ||
+      typeof participant.model === "string") &&
+    (participant.capabilities === undefined ||
+      isStringArray(participant.capabilities)) &&
+    (participant.sessionRef === undefined ||
+      typeof participant.sessionRef === "string") &&
+    (participant.role === "driver" || participant.role === "watchdog") &&
+    isPermission(participant.permission) &&
+    isParticipantStatus(participant.status)
+  );
+}
+
+function areStoredParticipantsValid(
+  value: unknown,
+): value is MultiFrontierParticipantState[] {
+  if (
+    !Array.isArray(value) ||
+    value.length === 0 ||
+    !value.every(isParticipant)
+  ) {
+    return false;
+  }
+  return (
+    new Set(value.map((participant) => participant.participantId)).size ===
+    value.length
+  );
+}
+
+function isStoredRunParticipantsAndDriverValid(
+  participants: unknown,
+  driver: unknown,
+): participants is MultiFrontierParticipantState[] {
+  if (!areStoredParticipantsValid(participants) || !isDriver(driver)) {
+    return false;
+  }
+  if (driver?.leaseState !== "active") {
+    return participants.every(
+      (participant) => participant.permission === "read_only",
+    );
+  }
+  if (
+    !participants.some(
+      (participant) => participant.participantId === driver.participantId,
+    )
+  ) {
+    return false;
+  }
+  return participants.every((participant) => {
+    if (participant.participantId !== driver.participantId) {
+      return (
+        participant.role === "watchdog" &&
+        participant.permission === "read_only"
+      );
+    }
+    return (
+      participant.role === "driver" &&
+      participant.permission === "workspace_write"
+    );
+  });
+}
+
+function isDriver(value: unknown): value is MultiFrontierDriverLease | null {
+  if (value === null) return true;
+  if (!value || typeof value !== "object") return false;
+  const driver = value as Partial<MultiFrontierDriverLease>;
+  return (
+    typeof driver.participantId === "string" &&
+    typeof driver.generation === "number" &&
+    (driver.leaseState === "inactive" ||
+      driver.leaseState === "active" ||
+      driver.leaseState === "revoked")
+  );
+}
+
+function isApproval(value: unknown): value is MultiFrontierApproval {
+  if (!value || typeof value !== "object") return false;
+  const approval = value as Partial<MultiFrontierApproval>;
+  return (
+    (approval.state === "not_required" ||
+      approval.state === "pending" ||
+      approval.state === "approved" ||
+      approval.state === "rejected") &&
+    (approval.proposalId === undefined ||
+      typeof approval.proposalId === "string") &&
+    (approval.reviewPacketId === undefined ||
+      typeof approval.reviewPacketId === "string")
+  );
+}
+
+function isRecovery(value: unknown): value is MultiFrontierRecovery {
+  if (!value || typeof value !== "object") return false;
+  const recovery = value as Partial<MultiFrontierRecovery>;
+  return (
+    isRecoveryReason(recovery.reason) &&
+    typeof recovery.recoveredAt === "string" &&
+    !Number.isNaN(Date.parse(recovery.recoveredAt)) &&
+    isPhase(recovery.resumablePhase) &&
+    (recovery.checkpointId === undefined ||
+      typeof recovery.checkpointId === "string")
+  );
+}
+
+function isPhase(value: unknown): value is MultiFrontierPhase {
+  return (
+    typeof value === "string" &&
+    [
+      "proposing",
+      "cross_review",
+      "converging",
+      "awaiting_go",
+      "implementing",
+      "checkpoint_review",
+      "paused",
+      "completed",
+      "failed",
+      "canceled",
+    ].includes(value)
+  );
+}
+
+function isParticipantStatus(
+  value: unknown,
+): value is MultiFrontierParticipantStatus {
+  return (
+    value === "idle" ||
+    value === "running" ||
+    value === "waiting" ||
+    value === "failed" ||
+    value === "completed"
+  );
+}
+
+function isPermission(
+  value: unknown,
+): value is MultiFrontierParticipantPermission {
+  return value === "read_only" || value === "workspace_write";
+}
+
+function isMatchingParticipantEvent(
+  existing: PersistedMultiFrontierParticipantEvent,
+  input: AppendMultiFrontierParticipantEventInput,
+): boolean {
+  return (
+    existing.collaborationId === input.collaborationId &&
+    existing.participantId === input.participantId &&
+    existing.permission === input.permission &&
+    existing.generation === input.generation &&
+    existing.status === input.status &&
+    (input.createdAt === undefined || existing.createdAt === input.createdAt)
+  );
+}
+
+function isStringArray(value: unknown): value is string[] {
+  return (
+    Array.isArray(value) && value.every((item) => typeof item === "string")
+  );
+}
+
+function isRecoveryReason(
+  value: unknown,
+): value is MultiFrontierRecoveryReason {
+  return (
+    value === "main_process_restarted" ||
+    value === "driver_crashed" ||
+    value === "watchdog_crashed" ||
+    value === "app_quit" ||
+    value === "canceled"
+  );
+}
+
+function assertSafeId(value: string, label: string): void {
+  if (!SAFE_ID.test(value)) throw new Error(`Invalid multi-frontier ${label}.`);
+}
+
+function assertTimestamp(value: string, label: string): void {
+  if (Number.isNaN(Date.parse(value))) {
+    throw new Error(`Invalid multi-frontier ${label}.`);
+  }
+}