@bitkyc08/opencodex 2.60.0 → 2.61.0

package/src/service/repair.ts

@@ -5,7 +5,8 @@ import type { ServiceDiagnostic } from "./diagnostics";
 import { assertServiceEnvironmentMatchesInstall, assertServiceAuthEnvironment } from "./guards";
 import { installLaunchd, restartLaunchdJob } from "./launchd";
 import type { LaunchdInstallOutcome } from "./launchd";
-import { TASK, writeServiceInstallState, serviceSourceDir } from "./state";
+import { TASK, writeServiceInstallState, serviceSourceDir, resolveServiceOwnership } from "./state";
+import type { ServiceOwnership, ServiceOwnershipResolution } from "./state";
 import { installSystemd } from "./systemd";
 import { writeWindowsSchedulerAssets, reregisterWindowsSchedulerTask, windowsSchedulerRegistrationMatchesSnapshot, restoreWindowsSchedulerTaskIfAbsent, startWindows, stopWindows, statusWindowsXml } from "./windows-ops";
 import { probeWindowsSchedulerTask, SCHEDULER_SETTLE_DELAYS_MS, settleDelay } from "./windows-scheduler";
@@ -35,6 +36,8 @@ export interface RepairServiceDeps {
   repairSystemd?: () => void;
   /** Restarts a launchd job the install path deliberately left alone. `restart` only. */
   restartLaunchd?: () => void;
+  /** Resolves the recorded runtime owner across every state path. */
+  readOwnership?: () => ServiceOwnershipResolution;
   /**
    * Which CLI verb is being served. `repair` must leave a healthy service alone — that no-op
    * IS the #4236 fix — while `restart` promises a new process, so on darwin it kicks the job
@@ -61,6 +64,37 @@ export interface RepairServiceDeps {
   platform?: NodeJS.Platform;
 }
 
+/**
+ * Why a repair stops when something other than this CLI owns the runtime.
+ *
+ * The npm service registration is KEPT — the maintainer's decision is that a user's install
+ * is never deleted — so the recorded owner is the only thing standing between a takeover the
+ * user consented to and the next `ocx service repair`, which would re-enable and restart the
+ * npm launcher without mentioning it. Repair runs incidentally: a tray helper, `ocx update`,
+ * a doctor suggestion. `install` is the deliberate act, so `install` is the verb that takes
+ * ownership back.
+ */
+export function foreignServiceOwnerRefusal(ownership: ServiceOwnership, action = "repair"): string {
+  return `Background service ${action} stopped: the desktop app owns the runtime `
+    + `(install ${ownership.installId}, consent generation ${ownership.consentGeneration}).\n`
+    + "The service registration was left exactly as it is — not re-enabled, not rewritten and not restarted.\n"
+    + "Quit the desktop app and run 'ocx service install' to hand the runtime back to this CLI.";
+}
+
+/**
+ * Why an unreadable or contradictory record stops a repair too.
+ *
+ * Collapsing "I could not read the claim" into "there is no claim" is how a consented
+ * takeover gets reactivated by a permissions error. `ocx service install` is deliberately
+ * not gated, so this never leaves an operator without a way forward.
+ */
+export function unknownServiceOwnerRefusal(reason: string, action = "repair"): string {
+  return `Background service ${action} stopped: ${reason}, so the runtime's recorded owner could `
+    + "not be determined.\n"
+    + "The service registration was left exactly as it is — not re-enabled, not rewritten and not restarted.\n"
+    + "Repair the service-state file or its permissions, then run 'ocx service install' to take the runtime back.";
+}
+
 async function assertSchedulerSnapshotBeforeStart(
   readSchedulerXml: () => string,
   expectedXml: string,
@@ -128,6 +162,16 @@ export async function repairService(deps: RepairServiceDeps = {}): Promise<void>
     throw new Error("Background service is not installed. Run 'ocx service install' first.");
   }
 
+  // Before anything is asserted, written, stopped or started. A repair that has already
+  // rewritten the assets has changed the thing it was supposed to leave alone.
+  const ownership = (deps.readOwnership ?? resolveServiceOwnership)();
+  if (ownership.kind === "unknown") throw new Error(unknownServiceOwnerRefusal(ownership.reason));
+  // `!== "cli"` rather than `=== "desktop"`: this is the CLI's own repair path, so any owner
+  // that is not this CLI is one whose runtime it must not touch.
+  if (ownership.kind === "owned" && ownership.ownership.owner !== "cli") {
+    throw new Error(foreignServiceOwnerRefusal(ownership.ownership));
+  }
+
   (deps.assertEnv ?? assertServiceEnvironmentMatchesInstall)();
   (deps.assertAuth ?? assertServiceAuthEnvironment)();
 

package/src/service/state-lock.ts

@@ -0,0 +1,269 @@
+import { randomUUID } from "node:crypto";
+import {
+  closeSync,
+  existsSync,
+  fsyncSync,
+  lstatSync,
+  mkdirSync,
+  openSync,
+  readFileSync,
+  readdirSync,
+  realpathSync,
+  rmdirSync,
+  unlinkSync,
+  writeFileSync,
+  type Stats,
+} from "node:fs";
+import { basename, dirname, join } from "node:path";
+
+const SERVICE_STATE_LOCK_WAIT_MS = 2_000;
+const SERVICE_STATE_LOCK_POLL_MS = 20;
+const SERVICE_STATE_LOCK_STALE_MS = 30_000;
+const PROCESS_INSTANCE = randomUUID();
+
+interface ServiceStateLockRecord {
+  readonly version: 1;
+  readonly pid: number;
+  readonly processInstance: string;
+  readonly token: string;
+  readonly createdAt: number;
+}
+
+interface ServiceStateLockSnapshot {
+  readonly record: ServiceStateLockRecord;
+  readonly ownerPath: string;
+  readonly lockIdentity: Pick<Stats, "dev" | "ino">;
+  readonly ownerIdentity: Pick<Stats, "dev" | "ino" | "size">;
+  readonly mtimeMs: number;
+}
+
+export interface ServiceStateLockHooks {
+  readonly now?: () => number;
+  readonly sleep?: (ms: number) => void;
+  readonly processAlive?: (pid: number) => boolean;
+  readonly beforeStaleDelete?: (lockPath: string) => void;
+  readonly beforeRelease?: (lockPath: string) => void;
+}
+
+interface HeldServiceStateLock {
+  depth: number;
+  readonly snapshot: ServiceStateLockSnapshot;
+}
+
+const heldLocks = new Map<string, HeldServiceStateLock>();
+
+function lockPathForStatePath(statePath: string): string {
+  try { return `${realpathSync.native(statePath)}.lock`; }
+  catch {
+    try { return join(realpathSync.native(dirname(statePath)), `${basename(statePath)}.lock`); }
+    catch { return `${statePath}.lock`; }
+  }
+}
+
+function lockOwnerProcessAlive(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    // EPERM means the process exists but this account cannot signal it. Unknown failures
+    // also fail closed: only ESRCH proves the holder is gone.
+    return (error as NodeJS.ErrnoException).code !== "ESRCH";
+  }
+}
+
+function sameIdentity(
+  left: Pick<Stats, "dev" | "ino">,
+  right: Pick<Stats, "dev" | "ino">,
+): boolean {
+  return left.dev === right.dev && left.ino === right.ino;
+}
+
+function ownerFileName(record: ServiceStateLockRecord): string {
+  return `v1-${record.pid}-${record.processInstance}-${record.token}.json`;
+}
+
+function parseOwnerFileName(name: string): { pid: number; pathToken: string } | null {
+  const match = /^v1-([1-9][0-9]*)-([0-9a-f-]+)-([0-9a-f-]+)[.]json$/i.exec(name);
+  if (!match) return null;
+  const pid = Number(match[1]);
+  return Number.isSafeInteger(pid) && pid > 0 ? { pid, pathToken: `${match[2]}-${match[3]}` } : null;
+}
+
+function readLockSnapshot(lockPath: string): ServiceStateLockSnapshot | null {
+  let lockIdentity: Stats;
+  let entries: string[];
+  try {
+    lockIdentity = lstatSync(lockPath);
+    if (!lockIdentity.isDirectory()) return null;
+    entries = readdirSync(lockPath);
+  } catch {
+    return null;
+  }
+  if (entries.length !== 1 || !parseOwnerFileName(entries[0]!)) return null;
+  const ownerPath = join(lockPath, entries[0]!);
+  try {
+    const ownerIdentity = lstatSync(ownerPath);
+    if (!ownerIdentity.isFile() || ownerIdentity.size > 4096) return null;
+    const value = JSON.parse(readFileSync(ownerPath, "utf8")) as Partial<ServiceStateLockRecord>;
+    if (value.version !== 1 || !Number.isSafeInteger(value.pid) || (value.pid ?? 0) <= 0
+      || typeof value.processInstance !== "string" || value.processInstance.length === 0
+      || typeof value.token !== "string" || value.token.length === 0
+      || typeof value.createdAt !== "number" || !Number.isFinite(value.createdAt)) return null;
+    const record = value as ServiceStateLockRecord;
+    if (entries[0] !== ownerFileName(record)) return null;
+    const currentLock = lstatSync(lockPath);
+    const currentOwner = lstatSync(ownerPath);
+    if (!currentLock.isDirectory() || !sameIdentity(lockIdentity, currentLock)
+      || !currentOwner.isFile() || !sameIdentity(ownerIdentity, currentOwner)
+      || currentOwner.size !== ownerIdentity.size) return null;
+    return { record, ownerPath, lockIdentity, ownerIdentity, mtimeMs: ownerIdentity.mtimeMs };
+  } catch {
+    return null;
+  }
+}
+
+function sameLock(left: ServiceStateLockSnapshot, right: ServiceStateLockSnapshot): boolean {
+  return left.record.token === right.record.token
+    && left.record.pid === right.record.pid
+    && left.record.processInstance === right.record.processInstance
+    && sameIdentity(left.lockIdentity, right.lockIdentity)
+    && sameIdentity(left.ownerIdentity, right.ownerIdentity)
+    && left.ownerIdentity.size === right.ownerIdentity.size;
+}
+
+function parsedIncompleteOwner(lockPath: string): { ownerPath: string | null; pid: number | null; mtimeMs: number } | null {
+  try {
+    const lock = lstatSync(lockPath);
+    if (!lock.isDirectory()) return null;
+    const entries = readdirSync(lockPath);
+    if (entries.length === 0) return { ownerPath: null, pid: null, mtimeMs: lock.mtimeMs };
+    if (entries.length !== 1) return null;
+    const parsed = parseOwnerFileName(entries[0]!);
+    if (!parsed) return null;
+    const ownerPath = join(lockPath, entries[0]!);
+    const owner = lstatSync(ownerPath);
+    return owner.isFile() ? { ownerPath, pid: parsed.pid, mtimeMs: owner.mtimeMs } : null;
+  } catch {
+    return null;
+  }
+}
+
+function reclaimStaleLock(lockPath: string, hooks: ServiceStateLockHooks): boolean {
+  const now = hooks.now ?? Date.now;
+  const processAlive = hooks.processAlive ?? lockOwnerProcessAlive;
+  const snapshot = readLockSnapshot(lockPath);
+  const incomplete = snapshot ? null : parsedIncompleteOwner(lockPath);
+  if (!snapshot && !incomplete) return false;
+  const ownerPath = snapshot?.ownerPath ?? incomplete!.ownerPath;
+  const ownerPid = snapshot?.record.pid ?? incomplete!.pid;
+  const createdAt = snapshot ? Math.max(snapshot.record.createdAt, snapshot.mtimeMs) : incomplete!.mtimeMs;
+  if (now() - createdAt <= SERVICE_STATE_LOCK_STALE_MS || (ownerPid !== null && processAlive(ownerPid))) {
+    return false;
+  }
+  if (snapshot) {
+    const current = readLockSnapshot(lockPath);
+    if (!current || !sameLock(snapshot, current)) return false;
+  }
+  hooks.beforeStaleDelete?.(lockPath);
+  try {
+    // The owner filename contains the holder's PID, process-instance nonce and token. A
+    // successor has a different name, so this unlink cannot delete the successor's owner.
+    if (ownerPath) unlinkSync(ownerPath);
+    rmdirSync(lockPath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function acquireOne(lockPath: string, hooks: ServiceStateLockHooks, waitMs: number): ServiceStateLockSnapshot {
+  const held = heldLocks.get(lockPath);
+  if (held) { held.depth += 1; return held.snapshot; }
+  const now = hooks.now ?? Date.now;
+  const sleep = hooks.sleep ?? (ms => Bun.sleepSync(ms));
+  const deadline = now() + waitMs;
+  if (!existsSync(dirname(lockPath))) mkdirSync(dirname(lockPath), { recursive: true, mode: 0o700 });
+  for (;;) {
+    const record: ServiceStateLockRecord = {
+      version: 1,
+      pid: process.pid,
+      processInstance: PROCESS_INSTANCE,
+      token: randomUUID(),
+      createdAt: now(),
+    };
+    const ownerPath = join(lockPath, ownerFileName(record));
+    let createdDirectory = false;
+    let descriptor: number | null = null;
+    try {
+      mkdirSync(lockPath, { mode: 0o700 });
+      createdDirectory = true;
+      descriptor = openSync(ownerPath, "wx", 0o600);
+      writeFileSync(descriptor, `${JSON.stringify(record)}\n`, "utf8");
+      fsyncSync(descriptor);
+      closeSync(descriptor);
+      descriptor = null;
+      const snapshot = readLockSnapshot(lockPath);
+      if (!snapshot || snapshot.record.token !== record.token) throw new Error("service state lock ownership could not be verified");
+      heldLocks.set(lockPath, { depth: 1, snapshot });
+      return snapshot;
+    } catch (error) {
+      if (descriptor !== null) { try { closeSync(descriptor); } catch { /* best-effort */ } }
+      if (createdDirectory) {
+        try { unlinkSync(ownerPath); } catch { /* incomplete owner may remain for dead-PID recovery */ }
+        try { rmdirSync(lockPath); } catch { /* another entry or uncertain owner remains */ }
+      }
+      const code = (error as NodeJS.ErrnoException).code;
+      if (code !== "EEXIST") throw error;
+      if (reclaimStaleLock(lockPath, hooks)) continue;
+      if (now() >= deadline) {
+        throw new Error(`another process owns the service state lock at ${lockPath}; nothing was written`);
+      }
+      sleep(SERVICE_STATE_LOCK_POLL_MS);
+    }
+  }
+}
+
+function releaseOne(lockPath: string, hooks: ServiceStateLockHooks): void {
+  const held = heldLocks.get(lockPath);
+  if (!held) return;
+  held.depth -= 1;
+  if (held.depth > 0) return;
+  heldLocks.delete(lockPath);
+  hooks.beforeRelease?.(lockPath);
+  try {
+    const current = readLockSnapshot(lockPath);
+    if (!current || !sameLock(held.snapshot, current)) return;
+    unlinkSync(held.snapshot.ownerPath);
+    rmdirSync(lockPath);
+  } catch { /* a verified future holder or stale recovery owns cleanup */ }
+}
+
+export function assertServiceStateLocksOwned(statePaths: readonly string[]): void {
+  for (const path of statePaths) {
+    const lockPath = lockPathForStatePath(path);
+    const held = heldLocks.get(lockPath);
+    const current = readLockSnapshot(lockPath);
+    if (!held || !current || !sameLock(held.snapshot, current)) {
+      throw new Error(`service state lock ownership changed before commit: ${lockPath}`);
+    }
+  }
+}
+
+export function withServiceStateLocks<T>(
+  statePaths: readonly string[],
+  run: () => T,
+  options: { readonly waitMs?: number; readonly hooks?: ServiceStateLockHooks } = {},
+): T {
+  const hooks = options.hooks ?? {};
+  const lockPaths = [...new Set(statePaths.map(lockPathForStatePath))].sort();
+  const acquired: string[] = [];
+  try {
+    for (const lockPath of lockPaths) {
+      acquireOne(lockPath, hooks, options.waitMs ?? SERVICE_STATE_LOCK_WAIT_MS);
+      acquired.push(lockPath);
+    }
+    return run();
+  } finally {
+    for (const lockPath of acquired.reverse()) releaseOne(lockPath, hooks);
+  }
+}

package/src/service/state-record.d.mts

@@ -0,0 +1,36 @@
+export interface ServiceOwnershipRecord {
+  readonly owner: "cli" | "desktop";
+  readonly installId: string;
+  readonly consentGeneration: number;
+  readonly [key: string]: unknown;
+}
+
+export declare const SERVICE_OWNERSHIP_PROTOCOL_VERSION: 1;
+export declare const SERVICE_OWNERSHIP_MINIMUM_CLI_VERSION: "2.61.0";
+
+export interface ServiceInstallStateRecord {
+  readonly version: 1 | 2;
+  readonly codexHome: string;
+  readonly opencodexHome: string;
+  readonly revision?: number;
+  readonly ownership?: ServiceOwnershipRecord;
+  readonly [key: string]: unknown;
+}
+
+export type ServiceStateRecordEvidence =
+  | { readonly path: string; readonly kind: "absent" }
+  | { readonly path: string; readonly kind: "unreadable"; readonly reason: string }
+  | { readonly path: string; readonly kind: "invalid" }
+  | { readonly path: string; readonly kind: "valid"; readonly state: ServiceInstallStateRecord };
+
+export type AuthoritativeServiceStateRecord =
+  | { readonly kind: "none"; readonly revision: 0; readonly needsRepair: false }
+  | { readonly kind: "state"; readonly state: ServiceInstallStateRecord; readonly revision: number; readonly needsRepair: boolean }
+  | { readonly kind: "unknown"; readonly reason: string };
+
+export declare function parseServiceOwnershipRecord(value: unknown): ServiceOwnershipRecord | null;
+export declare function parseServiceInstallStateRecord(value: unknown): ServiceInstallStateRecord | null;
+export declare function serviceStatePathsForHomes(opencodexHome: string, defaultOpenCodexHome: string, platform?: NodeJS.Platform): string[];
+export declare function inspectServiceStateRecords(paths: readonly string[], read?: (path: string) => string): readonly ServiceStateRecordEvidence[];
+export declare function serviceStateFingerprint(value: unknown): string;
+export declare function selectAuthoritativeServiceState(evidence: readonly ServiceStateRecordEvidence[]): AuthoritativeServiceStateRecord;

package/src/service/state-record.mjs

@@ -0,0 +1,138 @@
+import { readFileSync, realpathSync } from "node:fs";
+import { posix, win32 } from "node:path";
+
+export const SERVICE_OWNERSHIP_PROTOCOL_VERSION = 1;
+export const SERVICE_OWNERSHIP_MINIMUM_CLI_VERSION = "2.61.0";
+
+const isObject = value => Boolean(value) && typeof value === "object" && !Array.isArray(value);
+const isNonNegativeSafeInteger = value => typeof value === "number" && Number.isSafeInteger(value) && value >= 0;
+const nonEmptyString = value => typeof value === "string" && value.length > 0;
+
+/** Parse the ownership payload shared by the Bun service code and the Node launcher. */
+export function parseServiceOwnershipRecord(value) {
+  if (!isObject(value)) return null;
+  if (value.owner !== "cli" && value.owner !== "desktop") return null;
+  if (!nonEmptyString(value.installId) || !isNonNegativeSafeInteger(value.consentGeneration)) return null;
+  return value;
+}
+
+/** Parse the COMPLETE install record; ownership alone is not enough to trust the file. */
+export function parseServiceInstallStateRecord(value) {
+  if (!isObject(value) || (value.version !== 1 && value.version !== 2)) return null;
+  if (!nonEmptyString(value.codexHome) || !nonEmptyString(value.opencodexHome)) return null;
+  for (const key of ["codexSqliteHome", "bunPath", "launcherPath", "winswVersion", "winswSha256"]) {
+    if (value[key] !== undefined && !nonEmptyString(value[key])) return null;
+  }
+  if (value.cliPath !== undefined && value.cliPath !== null && !nonEmptyString(value.cliPath)) return null;
+  if (value.revision !== undefined && !isNonNegativeSafeInteger(value.revision)) return null;
+  if (value.consentGenerationCeiling !== undefined && !isNonNegativeSafeInteger(value.consentGenerationCeiling)) return null;
+  if (value.ownershipProtocolVersion !== undefined && !isNonNegativeSafeInteger(value.ownershipProtocolVersion)) return null;
+  if (value.ownership !== undefined && parseServiceOwnershipRecord(value.ownership) === null) return null;
+  if (value.version === 1) {
+    if (value.backend !== undefined) return null;
+  } else if (value.backend !== "scheduler" && value.backend !== "native") return null;
+  return value;
+}
+
+export function serviceStatePathsForHomes(opencodexHome, defaultOpenCodexHome, platform = process.platform) {
+  const tools = platform === "win32" ? win32 : posix;
+  const primary = tools.join(opencodexHome, "service-state.json");
+  const legacy = tools.join(defaultOpenCodexHome, "service-state.json");
+  const key = path => {
+    let canonical;
+    try { canonical = realpathSync.native(path); }
+    catch {
+      try { canonical = tools.join(realpathSync.native(tools.dirname(path)), tools.basename(path)); }
+      catch { canonical = tools.resolve(path); }
+    }
+    return platform === "win32" ? canonical.toLowerCase() : canonical;
+  };
+  return key(primary) === key(legacy) ? [primary] : [primary, legacy];
+}
+
+function errorCode(error) {
+  return error && typeof error === "object" && "code" in error ? String(error.code ?? "") : "";
+}
+
+/** Read every supplied state path without collapsing absent, invalid and unreadable. */
+export function inspectServiceStateRecords(paths, read = path => readFileSync(path, "utf8")) {
+  return paths.map(path => {
+    let raw;
+    try {
+      raw = read(path);
+    } catch (error) {
+      const code = errorCode(error);
+      return code === "ENOENT"
+        ? { path, kind: "absent" }
+        : { path, kind: "unreadable", reason: code || String(error) };
+    }
+    try {
+      const state = parseServiceInstallStateRecord(JSON.parse(raw));
+      return state ? { path, kind: "valid", state } : { path, kind: "invalid" };
+    } catch {
+      return { path, kind: "invalid" };
+    }
+  });
+}
+
+function canonical(value) {
+  if (Array.isArray(value)) return `[${value.map(canonical).join(",")}]`;
+  if (!isObject(value)) return JSON.stringify(value);
+  return `{${Object.keys(value).sort().map(key => `${JSON.stringify(key)}:${canonical(value[key])}`).join(",")}}`;
+}
+
+export function serviceStateFingerprint(value) {
+  return canonical(value);
+}
+
+/**
+ * Select one authoritative generation from mirrored state.
+ *
+ * The final path is authoritative. A lower-revision mirror is repairable; a same-or-newer
+ * disagreement is unordered evidence and fails closed. Before the authority exists, one valid
+ * active-home record is imported exactly once as migration input.
+ */
+export function selectAuthoritativeServiceState(evidence) {
+  const authority = evidence.at(-1);
+  if (!authority) return { kind: "none", revision: 0, needsRepair: false };
+  if (authority.kind === "unreadable") {
+    return { kind: "unknown", reason: `the authoritative service state could not be read (${authority.reason})` };
+  }
+  if (authority.kind === "invalid") {
+    return { kind: "unknown", reason: "the authoritative service install record is present but not valid" };
+  }
+  if (authority.kind === "valid") {
+    const fingerprint = canonical(authority.state);
+    const authorityRevision = authority.state.revision ?? 0;
+    const unorderedConflict = evidence.slice(0, -1).find(entry => entry.kind === "valid"
+      && (entry.state.revision ?? 0) >= authorityRevision
+      && canonical(entry.state) !== fingerprint);
+    if (unorderedConflict) {
+      return { kind: "unknown", reason: `a service state mirror conflicts with authority revision ${authorityRevision}` };
+    }
+    return {
+      kind: "state",
+      state: authority.state,
+      revision: authorityRevision,
+      needsRepair: evidence.slice(0, -1).some(entry => entry.kind !== "valid" || canonical(entry.state) !== fingerprint),
+    };
+  }
+
+  // The authority has never been established. A single valid active-home mirror is the
+  // migration source; after the first write it can no longer vote against the authority.
+  const migration = evidence.slice(0, -1);
+  const unreadable = migration.find(entry => entry.kind === "unreadable");
+  if (unreadable) return { kind: "unknown", reason: `a legacy service state path could not be read (${unreadable.reason})` };
+  if (migration.some(entry => entry.kind === "invalid")) {
+    return { kind: "unknown", reason: "a legacy service install record is present but not valid" };
+  }
+  const valid = migration.filter(entry => entry.kind === "valid");
+  if (valid.length === 0) return { kind: "none", revision: 0, needsRepair: false };
+  const revision = Math.max(...valid.map(entry => entry.state.revision ?? 0));
+  const newest = valid.filter(entry => (entry.state.revision ?? 0) === revision);
+  const fingerprint = canonical(newest[0].state);
+  if (newest.some(entry => canonical(entry.state) !== fingerprint)) {
+    return { kind: "unknown", reason: `legacy service state mirrors disagree at revision ${revision}` };
+  }
+  return { kind: "state", state: newest[0].state, revision, needsRepair: true };
+}