@bitkyc08/opencodex 2.60.0 → 2.61.0-preview.20260922

package/src/service/state.ts

@@ -1,14 +1,33 @@
-import { accessSync, chmodSync, constants as fsConstants, existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { accessSync, constants as fsConstants, existsSync, readFileSync, statSync, unlinkSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { delimiter, dirname, isAbsolute, join, posix, resolve, win32 } from "node:path";
 import { expandUserPath, getConfigDir } from "../config";
+import { atomicWriteFileStreamed } from "../config/atomic-write";
 import { resolveCodexHomeDir, type CodexHomeDeps } from "../codex/home";
 import { resolveCodexSqliteHome } from "../codex/paths";
 import { durableBunRuntime, type BunRuntimeSource, type DurableBunRuntime } from "../lib/bun-runtime";
 import { WINSW_SHA256, WINSW_VERSION } from "../lib/winsw";
-import { hardenSecretPath } from "../lib/windows-secret-acl";
-import { recordOwnedConfigPath } from "../lib/config-ownership";
 import { isProtectedHomeUnderTest, isTestHomeGuardArmed } from "../lib/test-home-guard";
+import { isStandaloneBinary } from "../lib/standalone";
+import {
+  inspectInstallStateBytes,
+  parseInstallStateRecord,
+  parseOwnershipClaim,
+  SERVICE_OWNERSHIP_MINIMUM_CLI_VERSION,
+  SERVICE_OWNERSHIP_PROTOCOL_VERSION,
+  selectAuthoritativeServiceState,
+  serviceStateFingerprint,
+  serviceStateFilesFor,
+} from "./install-state-contract.mjs";
+import type { ServiceStateRecordEvidence } from "./state-record.mjs";
+import { assertServiceStateLocksOwned, withServiceStateLocks, type ServiceStateLockHooks } from "./state-lock";
+import { withOwnershipMutationLease, type OwnershipMutationLeaseOptions } from "./ownership-mutation-lease.mjs";
+import {
+  assessServiceTakeoverCompatibility,
+  sameServiceTakeoverCompatibility,
+  type ManagingCliObservation,
+  type ServiceTakeoverCompatibility,
+} from "./ownership-compatibility";
 
 /**
  * Written only by the launchd plist and the systemd unit. `OCX_SERVICE=1` cannot stand in
@@ -19,6 +38,7 @@ export const SERVICE_MANAGED_ENV = "OCX_SERVICE_MANAGED";
 
 export const LABEL = "com.opencodex.proxy";
 export const TASK = "opencodex-proxy";
+export { SERVICE_OWNERSHIP_MINIMUM_CLI_VERSION, SERVICE_OWNERSHIP_PROTOCOL_VERSION };
 
 // This module lives one level below the original src/service.ts, so path-relative
 // lookups anchored at that file's directory go through this constant instead.
@@ -26,14 +46,18 @@ export const serviceSourceDir = dirname(import.meta.dir);
 
 export type ServiceBackend = "scheduler" | "native";
 
-export function cliEntry(runtime: DurableBunRuntime = durableBunRuntime()): { bun: string; bunRuntimeSource: BunRuntimeSource; cli: string } {
+export function cliEntry(runtime: DurableBunRuntime = durableBunRuntime()): { bun: string; bunRuntimeSource: BunRuntimeSource; cli: string | null } {
   // Bake the bundled Bun (manager-owned global package directory, survives `ocx update`) rather than
   // a transient system Bun, so launchd/systemd/schtasks keep resolving even if a
   // standalone Bun is later removed. The CLI entry lives at src/cli/index.ts.
   //
   // Path and provenance come from ONE resolution so the marker can never describe a
   // different binary than the one actually baked.
-  return { bun: runtime.path, bunRuntimeSource: runtime.source, cli: join(serviceSourceDir, "cli", "index.ts") };
+  return {
+    bun: runtime.path,
+    bunRuntimeSource: runtime.source,
+    cli: runtime.source === "standalone" || isStandaloneBinary() ? null : join(serviceSourceDir, "cli", "index.ts"),
+  };
 }
 
 /**
@@ -130,10 +154,7 @@ function defaultOpenCodexHome(): string {
 }
 
 export function serviceStatePathsForOpenCodexHome(opencodexHome: string): string[] {
-  const paths = [join(opencodexHome, "service-state.json")];
-  const defaultPath = join(defaultOpenCodexHome(), "service-state.json");
-  if (normalizePathForCompare(defaultPath) !== normalizePathForCompare(paths[0])) paths.push(defaultPath);
-  return paths;
+  return serviceStateFilesFor(opencodexHome, defaultOpenCodexHome());
 }
 
 export function serviceStatePaths(): string[] {
@@ -223,7 +244,7 @@ export interface ServiceInstallState {
   codexSqliteHome?: string;
   /** Baked at install; lets status flag paths gone stale after npm prefix/nvm moves. */
   bunPath?: string;
-  cliPath?: string;
+  cliPath?: string | null;
   /**
    * launchd and systemd. The stable `ocx` launcher the service definition actually invokes,
    * when one was found. Present means `bunPath`/`cliPath` are provenance for the install,
@@ -236,59 +257,573 @@ export interface ServiceInstallState {
   backend?: ServiceBackend;
   winswVersion?: string;
   winswSha256?: string;
+  /**
+   * Bumped by every write through {@link swapServiceInstallState}; the compare-and-swap
+   * token. Absent means a record written before this field existed, which compares equal
+   * to 0 so the first swap over it still lands.
+   */
+  revision?: number;
+  /** Who owns the running proxy. Absent means the CLI install that registered the service. */
+  ownership?: ServiceOwnership;
+  /**
+   * The highest consent generation this record has ever carried, kept across a release.
+   *
+   * Without it the counter is an ABA token: granting, releasing and granting again produces
+   * generation 1 twice, and an app-local record holding the first 1 would read the second
+   * one as its own prior consent.
+   */
+  consentGenerationCeiling?: number;
+  /** Written only by CLIs whose start/repair/update paths honor a desktop claim. */
+  ownershipProtocolVersion?: number;
+}
+
+/**
+ * The two kinds of installation that can own the proxy.
+ *
+ * `cli` is the npm (or standalone) `ocx` install that registered the background service.
+ * `desktop` is the packaged app, which brings its own bundled runtime.
+ */
+export type ServiceOwner = "cli" | "desktop";
+
+/**
+ * Durable ownership, recorded in the shared service install state.
+ *
+ * Ownership used to be a boolean the desktop shell recomputed at every launch from whether
+ * it happened to spawn a child, so a restart silently demoted the app back to guest and
+ * "ask once, then own permanently" could not be expressed at all. This record is the thing
+ * that survives the restart.
+ *
+ * ABSENT IS NOT UNOWNED. Every installation that predates this field has no record, and the
+ * npm service registration is what owns the runtime there, so absence has to keep meaning
+ * exactly that.
+ */
+export interface ServiceOwnership {
+  readonly owner: ServiceOwner;
+  /**
+   * Opaque identity of the owning INSTALLATION — not of the user, the machine or the
+   * account. The desktop app keeps the same value in its own app-local store, and comparing
+   * the two through {@link ownershipGrantedTo} is how a reinstalled app tells its own prior
+   * consent from another installation's.
+   */
+  readonly installId: string;
+  /**
+   * Increments once per ownership grant. Re-recording the same owner and install id leaves
+   * it alone, so a relaunch cannot inflate it and "exactly one increment per takeover" is
+   * an assertion a test can make.
+   */
+  readonly consentGeneration: number;
+}
+
+/**
+ * Validate an ownership claim read off disk.
+ *
+ * Returns the ORIGINAL object rather than a rebuilt one: a newer writer may carry fields
+ * this version does not know about, and rebuilding would drop them on the next preserve —
+ * which is the same lost-field failure this whole record exists to stop.
+ */
+export function parseServiceOwnership(value: unknown): ServiceOwnership | null {
+  return parseOwnershipClaim(value) as ServiceOwnership | null;
 }
 
+/**
+ * The record contract lives in `install-state-contract.mjs` so the Node launcher validates
+ * exactly what this reader validates. It used to keep a weaker copy, and a record that fails
+ * this contract while merely lacking an `ownership` field read there as "nobody owns the
+ * runtime" — which is permission to stop a foreign runtime and reactivate the npm service.
+ */
 export function parseServiceInstallState(value: unknown): ServiceInstallState | null {
-  if (!value || typeof value !== "object" || Array.isArray(value)) return null;
-  const state = value as Record<string, unknown>;
-  if (state.version !== 1 && state.version !== 2) return null;
-  if (typeof state.codexHome !== "string" || state.codexHome.length === 0) return null;
-  if (typeof state.opencodexHome !== "string" || state.opencodexHome.length === 0) return null;
-  for (const key of ["codexSqliteHome", "bunPath", "cliPath", "launcherPath", "winswVersion", "winswSha256"] as const) {
-    if (state[key] !== undefined && (typeof state[key] !== "string" || state[key].length === 0)) return null;
-  }
-  if (state.version === 1) {
-    if (state.backend !== undefined) return null;
-  } else if (state.backend !== "scheduler" && state.backend !== "native") {
-    return null;
-  }
-  return state as unknown as ServiceInstallState;
+  return parseInstallStateRecord(value) as ServiceInstallState | null;
 }
 
-export function writeServiceInstallState(backend: ServiceBackend = "scheduler", launcherPath?: string | null): void {
+/**
+ * What an install bakes into the record: the homes, the provenance paths and the backend.
+ *
+ * Everything here is rebuilt from the CURRENT process on every write, which is the point —
+ * it describes the install that just ran. {@link ServiceInstallState.ownership} deliberately
+ * is not part of it.
+ */
+function installProvenanceRecord(backend: ServiceBackend, launcherPath?: string | null): ServiceInstallState {
   const { bun, cli } = cliEntry();
   const codexHome = currentCodexHome();
-  const state: ServiceInstallState = {
+  return {
     version: 2,
     codexHome,
     opencodexHome: currentOpenCodexHome(),
     codexSqliteHome: resolveCodexSqliteHome({ codexHome }),
     bunPath: bun,
     cliPath: cli,
+    ownershipProtocolVersion: SERVICE_OWNERSHIP_PROTOCOL_VERSION,
     ...(launcherPath ? { launcherPath } : {}),
     backend,
     ...(backend === "native" ? { winswVersion: WINSW_VERSION, winswSha256: WINSW_SHA256 } : {}),
   };
-  for (const path of serviceStateWritePaths()) {
-    const dir = dirname(path);
-    recordOwnedConfigPath(getConfigDir(), path);
-    if (!existsSync(dir)) mkdirSync(dir, { recursive: true, mode: 0o700 });
-    writeFileSync(path, JSON.stringify(state, null, 2) + "\n", { encoding: "utf8", mode: 0o600 });
-    try { chmodSync(path, 0o600); } catch { /* best-effort */ }
-    if (process.platform === "win32") hardenSecretPath(path, { required: true });
-  }
+}
+
+/**
+ * Record an install, PRESERVING whatever owns the runtime.
+ *
+ * Every install, repair, update and stop path ends here, and each one used to hand this
+ * function a freshly rebuilt record that simply replaced the file. That is why ownership
+ * cannot be an ordinary field written by whoever ran last: a repair kicked off by a tray
+ * helper, or by `ocx update`, would erase a takeover the user had consented to and hand the
+ * runtime back to the npm launcher without saying anything. Preserving it here is what makes
+ * the consent durable.
+ */
+export function writeServiceInstallState(
+  backend: ServiceBackend = "scheduler",
+  launcherPath?: string | null,
+  deps: ServiceStateSwapDeps = {},
+): void {
+  swapServiceInstallState(current => ({
+    ...installProvenanceRecord(backend, launcherPath),
+    ...preservedConsent(current),
+  }), deps);
+}
+
+/** The ownership half of a record: the claim itself plus the generation high-water mark. */
+function preservedConsent(
+  current: ServiceInstallState | null,
+): Pick<ServiceInstallState, "ownership" | "consentGenerationCeiling"> {
+  const ownership = current?.ownership;
+  const ceiling = Math.max(current?.consentGenerationCeiling ?? 0, ownership?.consentGeneration ?? 0);
+  return {
+    ...(ownership ? { ownership } : {}),
+    ...(ceiling > 0 ? { consentGenerationCeiling: ceiling } : {}),
+  };
 }
 
 export function readServiceInstallState(): ServiceInstallState | null {
-  for (const path of serviceStatePaths()) {
-    try {
-      const parsed = parseServiceInstallState(JSON.parse(readFileSync(path, "utf8")));
-      if (parsed) return parsed;
-    } catch {
-      /* try the next known state path */
+  const resolved = resolveServiceState();
+  return resolved.kind === "state" ? resolved.state : null;
+}
+
+/** Raised when a non-cooperating writer prevents a stable authoritative commit. */
+export class ServiceStateConflictError extends Error {
+  constructor(readonly path: string, readonly attempts: number) {
+    super(
+      `service install state at ${path} was rewritten by another process during all ${attempts} `
+      + "compare-and-swap attempts; a stable commit could not be verified. Re-run the command.",
+    );
+    this.name = "ServiceStateConflictError";
+  }
+}
+
+export interface ServiceStateSwapDeps {
+  /** Test seam: which state paths to write. Defaults to every writable state path. */
+  paths?: readonly string[];
+  /** How many times to re-read and recompute before giving up. */
+  attempts?: number;
+  /**
+   * Test seam: runs immediately before each commit. It is the only place a competing writer
+   * can be interleaved deterministically, which is what makes the revision check testable
+   * rather than a claim in a comment.
+   */
+  beforeCommit?: (attempt: number) => void;
+  /** How long to wait for another process to release the anchor lock. */
+  lockWaitMs?: number;
+  /** Deterministic lock seams for failure-order tests. */
+  lockHooks?: ServiceStateLockHooks;
+  /** Atomic publisher seam. The callback must run immediately before its commit point. */
+  commitStateFile?: (path: string, serialized: string, validate: () => void) => void;
+  /** A mirror failure occurs after the authority committed and is therefore diagnostic. */
+  onMirrorError?: (path: string, error: unknown) => void;
+  /** Allows consented mutations to preserve a machine-readable unknown-subject error. */
+  unknownStateError?: (reason: string) => Error;
+  /** Shared with update/install/start so replacement and ownership mutation cannot overlap. */
+  mutationLease?: OwnershipMutationLeaseOptions;
+}
+
+export interface ServiceStateMutationContext {
+  readonly revision: number;
+}
+
+const SERVICE_STATE_SWAP_ATTEMPTS = 5;
+
+function authoritativeState(
+  paths: readonly string[],
+  unknownStateError?: (reason: string) => Error,
+): { current: ServiceInstallState | null; revision: number; fingerprint: string } {
+  const selected = selectAuthoritativeServiceState(
+    inspectServiceStateEvidence(paths) as readonly ServiceStateRecordEvidence[],
+  );
+  if (selected.kind === "unknown") {
+    throw unknownStateError?.(selected.reason) ?? new Error(`${selected.reason}; nothing was written`);
+  }
+  if (selected.kind === "none") return { current: null, revision: 0, fingerprint: "none" };
+  const current = selected.state as ServiceInstallState;
+  return { current, revision: selected.revision, fingerprint: serviceStateFingerprint(current) };
+}
+
+function commitServiceStateFile(path: string, serialized: string, validate: () => void): void {
+  atomicWriteFileStreamed(path, descriptor => {
+    writeFileSync(descriptor, serialized, { encoding: "utf8" });
+  }, { validateBeforeRename: validate });
+}
+
+/**
+ * Read the recorded state, compute the next one from it, and commit it only if nothing else
+ * moved the record in between.
+ *
+ * `mutate` may return null to mean "nothing to change", which writes nothing and leaves the
+ * file — including its absence — exactly as it was.
+ *
+ * WHAT THE REVISION CHECK IS. The anchor is re-read immediately before the commit and the
+ * committed bytes are read back immediately after, so a writer that landed on either side of
+ * the window is DETECTED and the whole read-modify-write runs again against the new base.
+ * The comparison is over the serialized record rather than the revision number alone,
+ * because two writers racing from one base both compute the same next revision — identical
+ * bytes mean nothing was lost, and differing bytes mean something was.
+ *
+ * The final path is the authority. With a custom home that is the legacy default-home path —
+ * the only path every writer can derive — and the active-home path is a compatibility mirror.
+ * The authority's atomic rename is the commit point. A mirror failure is reported but cannot
+ * roll back or reclassify the already committed mutation; the next writer repairs the mirror.
+ */
+export function swapServiceInstallState(
+  mutate: (current: ServiceInstallState | null, context: ServiceStateMutationContext) => ServiceInstallState | null,
+  deps: ServiceStateSwapDeps = {},
+): ServiceInstallState | null {
+  const paths = deps.paths ?? serviceStateWritePaths();
+  const authority = paths.at(-1);
+  if (authority === undefined) throw new Error("refusing to swap service install state with no state path");
+  const mirrors = paths.filter(path => path !== authority);
+  const attempts = deps.attempts ?? SERVICE_STATE_SWAP_ATTEMPTS;
+  const publish = deps.commitStateFile ?? commitServiceStateFile;
+  return withOwnershipMutationLease(paths, () => withServiceStateLocks(paths, () => {
+    for (let attempt = 0; attempt < attempts; attempt += 1) {
+      const base = authoritativeState(paths, deps.unknownStateError);
+      const candidate = mutate(base.current, { revision: base.revision });
+      if (candidate === null) return base.current;
+      if (base.revision >= Number.MAX_SAFE_INTEGER) {
+        throw new Error("service state revision is exhausted; refusing to publish an unversioned mutation");
+      }
+      const next: ServiceInstallState = { ...candidate, revision: base.revision + 1 };
+      const serialized = JSON.stringify(next, null, 2) + "\n";
+      deps.beforeCommit?.(attempt);
+      assertServiceStateLocksOwned(paths);
+      const fresh = authoritativeState(paths, deps.unknownStateError);
+      if (fresh.revision !== base.revision || fresh.fingerprint !== base.fingerprint) continue;
+      const validate = () => assertServiceStateLocksOwned(paths);
+      publish(authority, serialized, validate);
+      const committed = authoritativeState([authority]);
+      if (committed.revision !== next.revision || committed.fingerprint !== serviceStateFingerprint(next)) continue;
+      for (const mirror of mirrors) {
+        try { publish(mirror, serialized, validate); }
+        catch (error) {
+          (deps.onMirrorError ?? ((path, cause) => console.warn(
+            `service state committed, but compatibility mirror ${path} could not be refreshed: ${cause instanceof Error ? cause.message : String(cause)}`,
+          )))(mirror, error);
+        }
+      }
+      return next;
     }
+    throw new ServiceStateConflictError(authority, attempts);
+  }, { waitMs: deps.lockWaitMs, hooks: deps.lockHooks }), deps.mutationLease);
+}
+
+export interface RemoveServiceStateDeps {
+  readonly paths?: readonly string[];
+  readonly unlink?: (path: string) => void;
+  readonly lockWaitMs?: number;
+  readonly lockHooks?: ServiceStateLockHooks;
+}
+
+/**
+ * Delete mirrors first and the authority last under the same ownership locks.
+ *
+ * A crash or mirror error before the final unlink leaves the authority in place, so a stale
+ * mirror can never become a migration source and resurrect a released desktop claim.
+ */
+export function removeServiceInstallStateRecords(deps: RemoveServiceStateDeps = {}): void {
+  const paths = deps.paths ?? serviceStateWritePaths();
+  const authority = paths.at(-1);
+  if (!authority) return;
+  const unlink = deps.unlink ?? unlinkSync;
+  withOwnershipMutationLease(paths, () => withServiceStateLocks(paths, () => {
+    for (const mirror of paths.slice(0, -1)) {
+      assertServiceStateLocksOwned(paths);
+      if (existsSync(mirror)) unlink(mirror);
+    }
+    assertServiceStateLocksOwned(paths);
+    if (existsSync(authority)) unlink(authority);
+  }, { waitMs: deps.lockWaitMs, hooks: deps.lockHooks }), { waitMs: deps.lockWaitMs });
+}
+
+/** The recorded owner of ONE already-read record, or null. Prefer {@link resolveServiceOwnership}. */
+export function serviceOwnership(state: ServiceInstallState | null = readServiceInstallState()): ServiceOwnership | null {
+  return state?.ownership ?? null;
+}
+
+/**
+ * What every state path, together, says about who owns the runtime.
+ *
+ * An unknown resolution is the answer that matters. \`readServiceInstallState\` collapses
+ * unreadable, malformed and absent into one null, and a caller that reads that null as "the
+ * CLI owns it" will re-enable the npm launcher over a claim it merely failed to read — the
+ * exact demotion the record exists to prevent. Absence is the only thing that may mean no
+ * claim.
+ */
+export type ServiceStateResolution =
+  | { readonly kind: "none"; readonly revision: 0; readonly needsRepair: false }
+  | { readonly kind: "state"; readonly state: ServiceInstallState; readonly revision: number; readonly needsRepair: boolean }
+  | { readonly kind: "unknown"; readonly reason: string };
+
+export type ServiceOwnershipSubject =
+  | { readonly kind: "none"; readonly revision: number }
+  | { readonly kind: "owned"; readonly ownership: ServiceOwnership; readonly revision: number };
+
+export type ServiceOwnershipResolution = ServiceOwnershipSubject
+  | { readonly kind: "unknown"; readonly reason: string };
+
+export function resolveServiceState(
+  evidence: readonly ServiceStateEvidence[] = inspectServiceStateEvidence(),
+): ServiceStateResolution {
+  const selected = selectAuthoritativeServiceState(evidence as readonly ServiceStateRecordEvidence[]);
+  if (selected.kind === "unknown") return selected;
+  if (selected.kind === "none") return selected;
+  return {
+    kind: "state",
+    state: selected.state as ServiceInstallState,
+    revision: selected.revision,
+    needsRepair: selected.needsRepair,
+  };
+}
+
+export function resolveServiceOwnership(
+  evidence: readonly ServiceStateEvidence[] = inspectServiceStateEvidence(),
+): ServiceOwnershipResolution {
+  const state = resolveServiceState(evidence);
+  if (state.kind === "unknown") return state;
+  if (state.kind === "none" || !state.state.ownership) return { kind: "none", revision: state.revision };
+  return { kind: "owned", ownership: state.state.ownership, revision: state.revision };
+}
+
+export function sameServiceOwnershipSubject(
+  left: ServiceOwnershipSubject,
+  right: ServiceOwnershipSubject,
+): boolean {
+  if (left.kind !== right.kind || left.revision !== right.revision) return false;
+  if (left.kind === "none" || right.kind === "none") return true;
+  return left.ownership.owner === right.ownership.owner
+    && left.ownership.installId === right.ownership.installId
+    && left.ownership.consentGeneration === right.ownership.consentGeneration;
+}
+
+function sameServiceOwnershipIdentity(left: ServiceOwnershipSubject, right: ServiceOwnershipSubject): boolean {
+  if (left.kind !== right.kind) return false;
+  if (left.kind === "none" || right.kind === "none") return true;
+  return left.ownership.owner === right.ownership.owner
+    && left.ownership.installId === right.ownership.installId
+    && left.ownership.consentGeneration === right.ownership.consentGeneration;
+}
+
+function serviceOwnershipSubject(
+  state: ServiceInstallState | null,
+  revision: number,
+): ServiceOwnershipSubject {
+  return state?.ownership
+    ? { kind: "owned", ownership: state.ownership, revision }
+    : { kind: "none", revision };
+}
+
+export class ServiceOwnershipSubjectMismatchError extends Error {
+  readonly code = "service-ownership-subject-mismatch" as const;
+  constructor(readonly expected: ServiceOwnershipSubject, readonly actual: ServiceOwnershipSubject) {
+    super("service ownership changed after consent; resolve again and ask for fresh approval");
+    this.name = "ServiceOwnershipSubjectMismatchError";
   }
-  return null;
+}
+
+export class ServiceOwnershipSubjectUnknownError extends Error {
+  readonly code = "service-ownership-subject-unknown" as const;
+  constructor(readonly expected: ServiceOwnershipSubject, readonly reason: string) {
+    super(`service ownership could not be revalidated after consent (${reason}); nothing was written`);
+    this.name = "ServiceOwnershipSubjectUnknownError";
+  }
+}
+
+export class ServiceTakeoverCompatibilityChangedError extends Error {
+  readonly code = "service-takeover-compatibility-changed" as const;
+  constructor(readonly actual: ServiceTakeoverCompatibility) {
+    super("the managing CLI compatibility changed after consent; resolve again and ask for fresh approval");
+    this.name = "ServiceTakeoverCompatibilityChangedError";
+  }
+}
+
+/**
+ * Whether the packaged desktop app owns the runtime.
+ *
+ * This is the predicate `ocx service repair` and `ocx update` consult before they would
+ * re-enable, rewrite or restart the npm service registration. The registration itself is
+ * kept either way — the maintainer's decision is that the user's install is never deleted,
+ * so this marker is the only thing that makes the takeover durable.
+ */
+export function desktopOwnsService(state: ServiceInstallState | null = readServiceInstallState()): boolean {
+  return serviceOwnership(state)?.owner === "desktop";
+}
+
+/**
+ * THE COMPARISON RULE. An installation holds the recorded grant only when both the kind of
+ * owner and the install id match its own.
+ *
+ * The desktop app calls this at launch with the install id from its app-local store. True
+ * means this very installation already has consent and must not ask again. False with a
+ * non-null `ownership` means a DIFFERENT installation owns the runtime — a reinstalled app,
+ * or a second copy — and consent has to be asked before taking over. Null means nothing is
+ * recorded and the npm install still owns it.
+ */
+export function ownershipGrantedTo(
+  ownership: ServiceOwnership | null,
+  owner: ServiceOwner,
+  installId: string,
+): boolean {
+  return ownership !== null && ownership.owner === owner && ownership.installId === installId;
+}
+
+/**
+ * The record an ownership write lands on when no install state exists yet.
+ *
+ * Deliberately carries no `bunPath`, `cliPath` or `launcherPath`: those are baked BY AN
+ * INSTALL, and a takeover is not one. Recording the claiming process's own paths as install
+ * provenance would make `ocx service status` describe a registration nobody created.
+ */
+function ownershipBaseRecord(current: ServiceInstallState | null): ServiceInstallState {
+  if (current) return current;
+  const codexHome = currentCodexHome();
+  return {
+    version: 2,
+    codexHome,
+    opencodexHome: currentOpenCodexHome(),
+    codexSqliteHome: resolveCodexSqliteHome({ codexHome }),
+    backend: "scheduler",
+  };
+}
+
+/**
+ * Record `claim` as the runtime's owner and return what was written.
+ *
+ * Idempotent by design: re-recording the same owner and install id leaves the consent
+ * generation alone, so every relaunch of an app that already has consent is a no-op on the
+ * number. A different owner or a different install id is a new grant and increments it once.
+ */
+export interface RecordServiceOwnerRequest {
+  readonly owner: ServiceOwner;
+  readonly installId: string;
+  readonly expectedSubject: ServiceOwnershipSubject;
+  readonly expectedCompatibility: Extract<ServiceTakeoverCompatibility, { kind: "supported" }>;
+}
+
+export interface RecordServiceOwnerDeps extends ServiceStateSwapDeps {
+  /** Re-observes BOTH the registered manager and the current PATH manager inside the lock. */
+  readonly observeManagers: () => Readonly<Record<"service-registration" | "path", ManagingCliObservation>>;
+}
+
+export function recordServiceOwner(
+  request: RecordServiceOwnerRequest,
+  deps: RecordServiceOwnerDeps,
+): Extract<ServiceOwnershipSubject, { kind: "owned" }> {
+  if (!request.installId) throw new Error("refusing to record service ownership without an install id");
+  if (!request.expectedSubject || request.expectedCompatibility?.kind !== "supported") {
+    throw new Error("refusing to record service ownership without the exact approved subject and compatibility token");
+  }
+  if (!deps || typeof deps.observeManagers !== "function") {
+    throw new Error("refusing to record service ownership without a managing-CLI revalidation callback");
+  }
+  const { observeManagers, ...swapDeps } = deps;
+  let recorded: ServiceOwnership | null = null;
+  const committed = swapServiceInstallState((current, context) => {
+    const actualSubject = serviceOwnershipSubject(current, context.revision);
+    if (!sameServiceOwnershipSubject(request.expectedSubject, actualSubject)) {
+      throw new ServiceOwnershipSubjectMismatchError(request.expectedSubject, actualSubject);
+    }
+    let managers: Readonly<Record<"service-registration" | "path", ManagingCliObservation>>;
+    try { managers = observeManagers(); }
+    catch (error) {
+      throw new ServiceTakeoverCompatibilityChangedError({
+        kind: "blocked",
+        reason: "managing-cli-unknown",
+        detail: error instanceof Error ? error.message : String(error),
+        minimumCliVersion: SERVICE_OWNERSHIP_MINIMUM_CLI_VERSION,
+      });
+    }
+    const compatibility = assessServiceTakeoverCompatibility({
+      state: current,
+      subject: actualSubject,
+      managers,
+    });
+    if (!sameServiceTakeoverCompatibility(request.expectedCompatibility, compatibility)) {
+      throw new ServiceTakeoverCompatibilityChangedError(compatibility);
+    }
+    const previous = current?.ownership ?? null;
+    // The ceiling, not just the live claim: a grant that was released left its number
+    // behind on purpose, so a later grant cannot reuse it.
+    const floor = Math.max(previous?.consentGeneration ?? 0, current?.consentGenerationCeiling ?? 0);
+    if (floor >= Number.MAX_SAFE_INTEGER) {
+      throw new Error("service ownership consent generation is exhausted; nothing was written");
+    }
+    recorded = {
+      owner: request.owner,
+      installId: request.installId,
+      consentGeneration: previous && ownershipGrantedTo(previous, request.owner, request.installId)
+        ? previous.consentGeneration
+        : floor + 1,
+    };
+    return {
+      ...ownershipBaseRecord(current),
+      ownership: recorded,
+      consentGenerationCeiling: Math.max(floor, recorded.consentGeneration),
+    };
+  }, {
+    ...swapDeps,
+    unknownStateError: reason => new ServiceOwnershipSubjectUnknownError(request.expectedSubject, reason),
+  });
+  if (recorded === null || !committed?.ownership || committed.revision === undefined) {
+    throw new Error("service ownership was not recorded");
+  }
+  return { kind: "owned", ownership: committed.ownership, revision: committed.revision };
+}
+
+/**
+ * Drop a recorded owner and return what was dropped, or null when nothing was recorded.
+ *
+ * Writes nothing when there is no claim to release, so asking about an unowned runtime never
+ * creates an install record describing a service nobody registered.
+ */
+export interface ReleaseServiceOwnerDeps extends ServiceStateSwapDeps {
+  /** Service install refreshes provenance first; that known write may advance only revision. */
+  readonly allowRevisionAdvance?: boolean;
+}
+
+export function releaseServiceOwner(
+  expectedSubject: ServiceOwnershipSubject,
+  deps: ReleaseServiceOwnerDeps = {},
+): ServiceOwnership | null {
+  const { allowRevisionAdvance = false, ...swapDeps } = deps;
+  let released: ServiceOwnership | null = null;
+  swapServiceInstallState((current, context) => {
+    const actualSubject = serviceOwnershipSubject(current, context.revision);
+    const matches = allowRevisionAdvance
+      ? sameServiceOwnershipIdentity(expectedSubject, actualSubject) && actualSubject.revision >= expectedSubject.revision
+      : sameServiceOwnershipSubject(expectedSubject, actualSubject);
+    if (!matches) throw new ServiceOwnershipSubjectMismatchError(expectedSubject, actualSubject);
+    released = current?.ownership ?? null;
+    if (!current?.ownership) return null;
+    const { ownership: _released, ...withoutOwnership } = current;
+    // Keep the number. Dropping it makes the generation an ABA token: grant, release, grant
+    // again would produce 1 twice, and an app-local record still holding the first 1 would
+    // read the second grant as its own prior consent.
+    return {
+      ...withoutOwnership,
+      consentGenerationCeiling: Math.max(
+        current.consentGenerationCeiling ?? 0,
+        current.ownership.consentGeneration,
+      ),
+    };
+  }, {
+    ...swapDeps,
+    unknownStateError: reason => new ServiceOwnershipSubjectUnknownError(expectedSubject, reason),
+  });
+  return released;
 }
 
 /** What ONE state path said. Absent, unreadable and invalid are different answers. */
@@ -301,37 +836,16 @@ export type ServiceStateEvidence =
 /**
  * Every state path, with what each one said.
  *
- * `readServiceInstallState` returns the FIRST path that parsed and discards the
- * rest, so a valid mirror beside a corrupt one reads as clean. That is the right
- * behavior for callers that just need the install state; it is the wrong input
- * for deciding ownership, where a disagreement between mirrors is exactly the
- * evidence that matters.
+ * The final path is authoritative; earlier paths are compatibility mirrors and the
+ * migration source only while the authority is absent. Keeping the raw evidence separate
+ * lets the selector distinguish migration, degraded mirrors and unordered conflicts.
  */
 export function inspectServiceStateEvidence(
   paths: readonly string[] = serviceStatePaths(),
 ): readonly ServiceStateEvidence[] {
-  return paths.map((path): ServiceStateEvidence => {
-    let raw: string;
-    try {
-      raw = readFileSync(path, "utf8");
-    } catch (error) {
-      const code = error && typeof error === "object" && "code" in error
-        ? String((error as { code?: unknown }).code)
-        : "";
-      // ENOENT is an answer. EACCES, ENOTDIR and the rest are a failure to ask,
-      // and collapsing them into absence is how a locked-down state file would
-      // become permission to write.
-      if (code === "ENOENT") return { path, kind: "absent" };
-      return { path, kind: "unreadable", reason: code || String(error) };
-    }
-    let parsed: ServiceInstallState | null;
-    try {
-      parsed = parseServiceInstallState(JSON.parse(raw));
-    } catch {
-      return { path, kind: "invalid" };
-    }
-    return parsed ? { path, kind: "valid", state: parsed } : { path, kind: "invalid" };
-  });
+  return paths.map(path => (
+    inspectInstallStateBytes(path, at => readFileSync(at, "utf8")) as ServiceStateEvidence
+  ));
 }
 
 /** The homes this process is actually using, for comparison against a claim. */