@bitkyc08/opencodex 2.59.0 → 2.61.0-preview.20260922

package/src/service/health.ts

@@ -32,9 +32,10 @@ export function resolveServiceListenPort(override?: number): number {
   return 10100;
 }
 
-export function buildServiceShellCommand(bun: string, cli: string, port = resolveServiceListenPort()): string {
+export function buildServiceShellCommand(bun: string, cli: string | null, port = resolveServiceListenPort()): string {
   const tokenFile = serviceApiTokenFilePath();
-  return `if [ -f ${shellQuote(tokenFile)} ]; then OPENCODEX_API_AUTH_TOKEN="$(cat ${shellQuote(tokenFile)})"; export OPENCODEX_API_AUTH_TOKEN; fi; exec ${shellQuote(bun)} ${shellQuote(cli)} start --port ${port}`;
+  const args = cli ? `${shellQuote(cli)} start` : "start";
+  return `if [ -f ${shellQuote(tokenFile)} ]; then OPENCODEX_API_AUTH_TOKEN="$(cat ${shellQuote(tokenFile)})"; export OPENCODEX_API_AUTH_TOKEN; fi; exec ${shellQuote(bun)} ${args} --port ${port}`;
 }
 
 /**

package/src/service/install-state-contract.d.mts

@@ -0,0 +1,27 @@
+export type {
+  AuthoritativeServiceStateRecord,
+  ServiceInstallStateRecord,
+  ServiceOwnershipRecord as OwnershipClaim,
+  ServiceStateRecordEvidence as InstallStateEvidence,
+} from "./state-record.mjs";
+
+export {
+  SERVICE_OWNERSHIP_MINIMUM_CLI_VERSION,
+  SERVICE_OWNERSHIP_PROTOCOL_VERSION,
+  selectAuthoritativeServiceState,
+  serviceStateFingerprint,
+} from "./state-record.mjs";
+
+import type { ServiceStateRecordEvidence } from "./state-record.mjs";
+
+export type OwnershipResolution =
+  | { readonly kind: "none"; readonly revision: number; readonly needsRepair?: boolean }
+  | { readonly kind: "owned"; readonly ownership: { owner: string; installId: string; consentGeneration: number }; readonly revision: number }
+  | { readonly kind: "unknown"; readonly reason: string };
+
+export declare const SERVICE_STATE_FILE: "service-state.json";
+export declare function parseOwnershipClaim(value: unknown): import("./state-record.mjs").ServiceOwnershipRecord | null;
+export declare function parseInstallStateRecord(value: unknown): import("./state-record.mjs").ServiceInstallStateRecord | null;
+export declare function inspectInstallStateBytes(path: string, read: (path: string) => string): ServiceStateRecordEvidence;
+export declare function resolveOwnershipFromEvidence(evidence: readonly ServiceStateRecordEvidence[]): OwnershipResolution;
+export declare function serviceStateFilesFor(opencodexHomeDir: string, defaultHomeDir: string, platform?: NodeJS.Platform): string[];

package/src/service/install-state-contract.mjs

@@ -0,0 +1,34 @@
+/** Compatibility surface for the shared install-state contract landed before C2 hardening. */
+import {
+  inspectServiceStateRecords,
+  parseServiceInstallStateRecord,
+  parseServiceOwnershipRecord,
+  SERVICE_OWNERSHIP_MINIMUM_CLI_VERSION,
+  SERVICE_OWNERSHIP_PROTOCOL_VERSION,
+  selectAuthoritativeServiceState,
+  serviceStateFingerprint,
+  serviceStatePathsForHomes,
+} from "./state-record.mjs";
+
+export const SERVICE_STATE_FILE = "service-state.json";
+export const parseOwnershipClaim = parseServiceOwnershipRecord;
+export const parseInstallStateRecord = parseServiceInstallStateRecord;
+export const serviceStateFilesFor = serviceStatePathsForHomes;
+export {
+  SERVICE_OWNERSHIP_MINIMUM_CLI_VERSION,
+  SERVICE_OWNERSHIP_PROTOCOL_VERSION,
+  selectAuthoritativeServiceState,
+  serviceStateFingerprint,
+};
+
+export function inspectInstallStateBytes(path, read) {
+  return inspectServiceStateRecords([path], read)[0];
+}
+
+export function resolveOwnershipFromEvidence(evidence) {
+  const selected = selectAuthoritativeServiceState(evidence);
+  if (selected.kind === "unknown" || selected.kind === "none") return selected;
+  return selected.state.ownership
+    ? { kind: "owned", ownership: selected.state.ownership, revision: selected.revision }
+    : { kind: "none", revision: selected.revision };
+}

package/src/service/launchd.ts

@@ -160,7 +160,7 @@ function launchdServiceCommand(
  */
 export function expectedLaunchdCommand(
   port: number,
-  deps: { state?: ServiceInstallState | null; entry?: { bun: string; cli: string } } = {},
+  deps: { state?: ServiceInstallState | null; entry?: { bun: string; cli: string | null } } = {},
 ): string {
   const state = deps.state === undefined ? readServiceInstallState() : deps.state;
   if (state?.launcherPath) return buildServiceLauncherShellCommand(state.launcherPath, port);

package/src/service/orchestration.ts

@@ -11,7 +11,7 @@ import type { ServiceDiagnostic } from "./diagnostics";
 import { assertServiceEnvironmentMatchesInstall } from "./guards";
 import { runLaunchctl, launchdEvictionTargets, launchctlBootoutBenign, probeLaunchdLoadState, installLaunchd, startLaunchd, stopLaunchd, statusLaunchd, uninstallLaunchd } from "./launchd";
 import { assertSchedulerRegistrationBeforeStart } from "./repair";
-import { SERVICE_MANAGED_ENV, TASK, plistPath, serviceStatePaths, writeServiceInstallState } from "./state";
+import { SERVICE_MANAGED_ENV, TASK, plistPath, removeServiceInstallStateRecords, writeServiceInstallState } from "./state";
 import type { ServiceBackend } from "./state";
 import { unitPath, isSystemd, installSystemd, startSystemd, stopSystemd, statusSystemd, uninstallSystemd, systemdServiceInstallCleanupOps } from "./systemd";
 import { writeWindowsSchedulerAssets, stageWindowsSchedulerRegistrationXml, removeWindowsSchedulerRegistrationStage, registerFreshWindowsSchedulerTask, recordWindowsSchedulerOwnership, removeNativeWindowsServiceForScheduler, installWindows, installWindowsNative, startWindows, isWindowsSchedulerEndBenign, stopWindows, stopWindowsChecked, statusWindows, statusWindowsXml, killWindowsServiceWrapperProcesses, uninstallWindows, classifyWindowsServiceStop } from "./windows-ops";
@@ -527,9 +527,7 @@ export function stopServiceIfInstalledDetailed(): ServiceStopOutcome {
 
 /** Delete install-state files; stale state would make `ocx update` "reinstall" a service that no longer exists. */
 export function removeServiceInstallState(): void {
-  for (const path of serviceStatePaths()) {
-    try { if (existsSync(path)) unlinkSync(path); } catch { /* best-effort */ }
-  }
+  removeServiceInstallStateRecords();
 }
 
 type UninstallServiceHooksForTests = {

package/src/service/ownership-compatibility.ts

@@ -0,0 +1,164 @@
+import { createHash } from "node:crypto";
+import { isAbsolute } from "node:path";
+import { parseStrictSemver } from "../lib/strict-semver";
+import type {
+  ServiceInstallState,
+  ServiceOwnershipSubject,
+} from "./state";
+import {
+  SERVICE_OWNERSHIP_MINIMUM_CLI_VERSION,
+  SERVICE_OWNERSHIP_PROTOCOL_VERSION,
+} from "./install-state-contract.mjs";
+
+export type ManagingCliRole = "service-registration" | "path";
+
+export type ManagingCliObservation =
+  | { readonly status: "absent" }
+  | { readonly status: "unknown"; readonly reason: string }
+  | { readonly status: "observed"; readonly version: string; readonly identity: string };
+
+export type RegisteredManagingCliInvocation =
+  | { readonly status: "absent" }
+  | { readonly status: "unknown"; readonly reason: string }
+  | { readonly status: "resolved"; readonly executable: string; readonly args: readonly string[] };
+
+/** Resolve the exact command baked into the preserved service registration. */
+export function registeredManagingCliInvocation(
+  state: ServiceInstallState | null,
+): RegisteredManagingCliInvocation {
+  if (!state) return { status: "absent" };
+  if (state.launcherPath) {
+    return isAbsolute(state.launcherPath)
+      ? { status: "resolved", executable: state.launcherPath, args: [] }
+      : { status: "unknown", reason: "the recorded service launcher is not absolute" };
+  }
+  if (!state.bunPath || !isAbsolute(state.bunPath)) {
+    return { status: "unknown", reason: "the registered service executable is missing or not absolute" };
+  }
+  if (state.cliPath === null) return { status: "resolved", executable: state.bunPath, args: [] };
+  if (typeof state.cliPath === "string" && isAbsolute(state.cliPath)) {
+    return { status: "resolved", executable: state.bunPath, args: [state.cliPath] };
+  }
+  return { status: "unknown", reason: "the registered service CLI path is missing or not absolute" };
+}
+
+export interface ServiceTakeoverCompatibilityInput {
+  readonly state: ServiceInstallState | null;
+  readonly subject: ServiceOwnershipSubject;
+  readonly managers: Readonly<Record<ManagingCliRole, ManagingCliObservation>>;
+}
+
+export type ServiceTakeoverCompatibility =
+  | {
+      readonly kind: "supported";
+      readonly protocolVersion: typeof SERVICE_OWNERSHIP_PROTOCOL_VERSION;
+      readonly minimumCliVersion: typeof SERVICE_OWNERSHIP_MINIMUM_CLI_VERSION;
+      /** Opaque binding over the approved subject and both managing-CLI observations. */
+      readonly token: string;
+    }
+  | {
+      readonly kind: "blocked";
+      readonly reason:
+        | "managing-cli-unknown"
+        | "managing-cli-unsupported"
+        | "managing-cli-unobserved"
+        | "service-protocol-unsupported";
+      readonly detail: string;
+      readonly minimumCliVersion: typeof SERVICE_OWNERSHIP_MINIMUM_CLI_VERSION;
+    };
+
+function comparePrerelease(left: readonly (bigint | string)[], right: readonly (bigint | string)[]): number {
+  if (left.length === 0 || right.length === 0) return left.length === right.length ? 0 : left.length === 0 ? 1 : -1;
+  for (let index = 0; index < Math.max(left.length, right.length); index += 1) {
+    const a = left[index];
+    const b = right[index];
+    if (a === undefined || b === undefined) return a === b ? 0 : a === undefined ? -1 : 1;
+    if (a === b) continue;
+    if (typeof a === "bigint" && typeof b === "bigint") return a < b ? -1 : 1;
+    if (typeof a === "bigint") return -1;
+    if (typeof b === "bigint") return 1;
+    return a < b ? -1 : 1;
+  }
+  return 0;
+}
+
+function versionSupportsOwnership(value: string): boolean {
+  const actual = parseStrictSemver(value);
+  const minimum = parseStrictSemver(SERVICE_OWNERSHIP_MINIMUM_CLI_VERSION);
+  if (!actual || !minimum) return false;
+  for (let index = 0; index < actual.core.length; index += 1) {
+    if (actual.core[index] !== minimum.core[index]) return actual.core[index]! > minimum.core[index]!;
+  }
+  return comparePrerelease(actual.prerelease, minimum.prerelease) >= 0;
+}
+
+function compatibilityToken(input: ServiceTakeoverCompatibilityInput): string {
+  return createHash("sha256").update(JSON.stringify({
+    subject: input.subject,
+    protocolVersion: input.state?.ownershipProtocolVersion ?? null,
+    managers: {
+      "service-registration": input.managers["service-registration"],
+      path: input.managers.path,
+    },
+  })).digest("hex");
+}
+
+/**
+ * Decide whether permanent desktop ownership can be offered.
+ *
+ * Both managing surfaces are mandatory observations. `absent` is a trustworthy answer;
+ * `unknown` is not. An observed service registration additionally needs the protocol marker
+ * written by a CLI whose start/repair/update paths honor the ownership claim. This is what
+ * keeps the preserved registration from starting an older runtime at the next login.
+ */
+export function assessServiceTakeoverCompatibility(
+  input: ServiceTakeoverCompatibilityInput,
+): ServiceTakeoverCompatibility {
+  const observed = Object.entries(input.managers) as Array<[ManagingCliRole, ManagingCliObservation]>;
+  const unknown = observed.find(([, manager]) => manager.status === "unknown");
+  if (unknown) return {
+    kind: "blocked",
+    reason: "managing-cli-unknown",
+    detail: `${unknown[0]} compatibility could not be determined`,
+    minimumCliVersion: SERVICE_OWNERSHIP_MINIMUM_CLI_VERSION,
+  };
+  const present = observed.filter(([, manager]) => manager.status === "observed") as Array<[
+    ManagingCliRole,
+    Extract<ManagingCliObservation, { status: "observed" }>,
+  ]>;
+  if (present.length === 0) return {
+    kind: "blocked",
+    reason: "managing-cli-unobserved",
+    detail: "no managing OpenCodex CLI installation was observed",
+    minimumCliVersion: SERVICE_OWNERSHIP_MINIMUM_CLI_VERSION,
+  };
+  const unsupported = present.find(([, manager]) => !versionSupportsOwnership(manager.version));
+  if (unsupported) return {
+    kind: "blocked",
+    reason: "managing-cli-unsupported",
+    detail: `${unsupported[0]} uses OpenCodex ${unsupported[1].version}; ${SERVICE_OWNERSHIP_MINIMUM_CLI_VERSION} or later is required`,
+    minimumCliVersion: SERVICE_OWNERSHIP_MINIMUM_CLI_VERSION,
+  };
+  if (input.managers["service-registration"].status === "observed"
+    && input.state?.ownershipProtocolVersion !== SERVICE_OWNERSHIP_PROTOCOL_VERSION) {
+    return {
+      kind: "blocked",
+      reason: "service-protocol-unsupported",
+      detail: "the preserved service registration was not written by an ownership-aware CLI",
+      minimumCliVersion: SERVICE_OWNERSHIP_MINIMUM_CLI_VERSION,
+    };
+  }
+  return {
+    kind: "supported",
+    protocolVersion: SERVICE_OWNERSHIP_PROTOCOL_VERSION,
+    minimumCliVersion: SERVICE_OWNERSHIP_MINIMUM_CLI_VERSION,
+    token: compatibilityToken(input),
+  };
+}
+
+export function sameServiceTakeoverCompatibility(
+  left: ServiceTakeoverCompatibility,
+  right: ServiceTakeoverCompatibility,
+): boolean {
+  return left.kind === "supported" && right.kind === "supported" && left.token === right.token;
+}

package/src/service/ownership-mutation-lease.d.mts

@@ -0,0 +1,32 @@
+export interface OwnershipMutationLeaseOptions {
+  readonly waitMs?: number;
+  readonly now?: () => number;
+  readonly sleep?: (ms: number) => void;
+  readonly processAlive?: (pid: number) => boolean;
+  readonly beforeRelease?: (lockPath: string) => void;
+  readonly joinToken?: string;
+}
+
+export interface OwnershipMutationLease { readonly token: string; release(): void }
+
+export declare const OWNERSHIP_MUTATION_LEASE_TOKEN_ENV: "OCX_OWNERSHIP_MUTATION_LEASE_TOKEN";
+
+export declare function ownershipMutationLeaseChildEnvironment(
+  environment: NodeJS.ProcessEnv,
+  token: string,
+): NodeJS.ProcessEnv;
+
+export declare function unprivilegedOwnershipMutationEnvironment(
+  environment: NodeJS.ProcessEnv,
+): NodeJS.ProcessEnv;
+
+export declare function acquireOwnershipMutationLease(
+  statePaths: readonly string[],
+  options?: OwnershipMutationLeaseOptions,
+): OwnershipMutationLease;
+
+export declare function withOwnershipMutationLease<T>(
+  statePaths: readonly string[],
+  run: () => T,
+  options?: OwnershipMutationLeaseOptions,
+): T;

package/src/service/ownership-mutation-lease.mjs

@@ -0,0 +1,211 @@
+import { randomUUID } from "node:crypto";
+import {
+  closeSync,
+  existsSync,
+  fsyncSync,
+  lstatSync,
+  mkdirSync,
+  openSync,
+  readFileSync,
+  readdirSync,
+  realpathSync,
+  rmdirSync,
+  unlinkSync,
+  writeFileSync,
+} from "node:fs";
+import { basename, dirname, join } from "node:path";
+
+const WAIT_MS = 2_000;
+const POLL_MS = 20;
+const STALE_MS = 30_000;
+const PROCESS_INSTANCE = randomUUID();
+const held = new Map();
+const delegatedTokens = new Map();
+const sleeper = new Int32Array(new SharedArrayBuffer(4));
+export const OWNERSHIP_MUTATION_LEASE_TOKEN_ENV = "OCX_OWNERSHIP_MUTATION_LEASE_TOKEN";
+
+export function ownershipMutationLeaseChildEnvironment(environment, token) {
+  return { ...environment, [OWNERSHIP_MUTATION_LEASE_TOKEN_ENV]: token };
+}
+
+export function unprivilegedOwnershipMutationEnvironment(environment) {
+  const child = { ...environment };
+  delete child[OWNERSHIP_MUTATION_LEASE_TOKEN_ENV];
+  return child;
+}
+
+function sleep(ms) { Atomics.wait(sleeper, 0, 0, ms); }
+function processAlive(pid) {
+  try { process.kill(pid, 0); return true; }
+  catch (error) { return error?.code !== "ESRCH"; }
+}
+
+function leasePath(statePaths) {
+  const authority = statePaths.at(-1);
+  if (!authority) throw new Error("cannot acquire ownership mutation lease without a service-state path");
+  try { return `${realpathSync.native(authority)}.mutation.lock`; }
+  catch {
+    try { return join(realpathSync.native(dirname(authority)), `${basename(authority)}.mutation.lock`); }
+    catch { return `${authority}.mutation.lock`; }
+  }
+}
+
+function ownerName(record) {
+  return `v1-${record.pid}-${record.processInstance}-${record.token}.json`;
+}
+
+function parseOwnerName(name) {
+  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 : null;
+}
+
+function readOwner(path) {
+  try {
+    const lock = lstatSync(path);
+    if (!lock.isDirectory()) return null;
+    const entries = readdirSync(path);
+    if (entries.length !== 1) return null;
+    const ownerPath = join(path, entries[0]);
+    const owner = lstatSync(ownerPath);
+    if (!owner.isFile() || owner.size > 4096) return null;
+    const record = JSON.parse(readFileSync(ownerPath, "utf8"));
+    if (record?.version !== 1 || !Number.isSafeInteger(record.pid) || record.pid <= 0
+      || typeof record.processInstance !== "string" || !record.processInstance
+      || typeof record.token !== "string" || !record.token
+      || !Number.isFinite(record.createdAt) || entries[0] !== ownerName(record)) return null;
+    const currentLock = lstatSync(path);
+    const currentOwner = lstatSync(ownerPath);
+    if (currentLock.dev !== lock.dev || currentLock.ino !== lock.ino
+      || currentOwner.dev !== owner.dev || currentOwner.ino !== owner.ino
+      || currentOwner.size !== owner.size) return null;
+    return { path, ownerPath, record, lockDev: lock.dev, lockIno: lock.ino, ownerDev: owner.dev, ownerIno: owner.ino, ownerSize: owner.size, mtimeMs: owner.mtimeMs };
+  } catch { return null; }
+}
+
+function sameOwner(left, right) {
+  return left.record.token === right.record.token
+    && left.record.pid === right.record.pid
+    && left.record.processInstance === right.record.processInstance
+    && left.lockDev === right.lockDev && left.lockIno === right.lockIno
+    && left.ownerDev === right.ownerDev && left.ownerIno === right.ownerIno
+    && left.ownerSize === right.ownerSize;
+}
+
+function readIncompleteOwner(path) {
+  try {
+    const lock = lstatSync(path);
+    if (!lock.isDirectory()) return null;
+    const entries = readdirSync(path);
+    if (entries.length === 0) return { path, ownerPath: null, pid: null, mtimeMs: lock.mtimeMs };
+    if (entries.length !== 1) return null;
+    const pid = parseOwnerName(entries[0]);
+    if (!pid) return null;
+    const ownerPath = join(path, entries[0]);
+    const owner = lstatSync(ownerPath);
+    return owner.isFile() ? { path, ownerPath, pid, mtimeMs: owner.mtimeMs } : null;
+  } catch { return null; }
+}
+
+function reclaim(path, now, alive) {
+  const observed = readOwner(path);
+  const incomplete = observed ? null : readIncompleteOwner(path);
+  if (!observed && !incomplete) return false;
+  const createdAt = observed ? Math.max(observed.record.createdAt, observed.mtimeMs) : incomplete.mtimeMs;
+  const pid = observed?.record.pid ?? incomplete.pid;
+  if (now() - createdAt <= STALE_MS || (pid !== null && alive(pid))) return false;
+  if (observed) {
+    const current = readOwner(path);
+    if (!current || !sameOwner(observed, current)) return false;
+  }
+  try {
+    const ownerPath = observed?.ownerPath ?? incomplete.ownerPath;
+    if (ownerPath) unlinkSync(ownerPath);
+    rmdirSync(path);
+    return true;
+  } catch { return false; }
+}
+
+export function acquireOwnershipMutationLease(
+  statePaths,
+  options = {},
+) {
+  const path = leasePath(statePaths);
+  const nested = held.get(path);
+  if (nested) {
+    nested.depth += 1;
+    return { token: nested.snapshot.record.token, release: () => release(path, options) };
+  }
+  const now = options.now ?? Date.now;
+  const alive = options.processAlive ?? processAlive;
+  const explicitJoinToken = options.joinToken;
+  const envJoinToken = process.env[OWNERSHIP_MUTATION_LEASE_TOKEN_ENV];
+  const joinToken = explicitJoinToken ?? envJoinToken ?? delegatedTokens.get(path);
+  if (joinToken) {
+    const owner = readOwner(path);
+    if (owner?.record.token === joinToken && alive(owner.record.pid)) {
+      delegatedTokens.set(path, joinToken);
+      if (envJoinToken === joinToken) delete process.env[OWNERSHIP_MUTATION_LEASE_TOKEN_ENV];
+      held.set(path, { depth: 1, snapshot: owner, delegated: true });
+      return { token: joinToken, release: () => release(path, options) };
+    }
+    delegatedTokens.delete(path);
+    if (envJoinToken === joinToken) delete process.env[OWNERSHIP_MUTATION_LEASE_TOKEN_ENV];
+    if (explicitJoinToken) throw new Error("ownership mutation lease delegation is invalid or no longer live");
+  }
+  const wait = options.waitMs ?? WAIT_MS;
+  const deadline = now() + wait;
+  if (!existsSync(dirname(path))) mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+  for (;;) {
+    const record = { version: 1, pid: process.pid, processInstance: PROCESS_INSTANCE, token: randomUUID(), createdAt: now() };
+    const ownerPath = join(path, ownerName(record));
+    let madeDirectory = false;
+    let descriptor = null;
+    try {
+      mkdirSync(path, { mode: 0o700 });
+      madeDirectory = true;
+      descriptor = openSync(ownerPath, "wx", 0o600);
+      writeFileSync(descriptor, `${JSON.stringify(record)}\n`, "utf8");
+      fsyncSync(descriptor);
+      closeSync(descriptor);
+      descriptor = null;
+      const snapshot = readOwner(path);
+      if (!snapshot || snapshot.record.token !== record.token) throw new Error("ownership mutation lease could not be verified");
+      held.set(path, { depth: 1, snapshot, delegated: false });
+      return { token: record.token, release: () => release(path, options) };
+    } catch (error) {
+      if (descriptor !== null) { try { closeSync(descriptor); } catch { /* stale recovery owns uncertain cleanup */ } }
+      if (madeDirectory) {
+        try { unlinkSync(ownerPath); } catch { /* partial owner is recovered after dead-PID proof */ }
+        try { rmdirSync(path); } catch { /* owner entry or successor keeps the directory live */ }
+      }
+      if (error?.code !== "EEXIST") throw error;
+      if (reclaim(path, now, alive)) continue;
+      if (now() >= deadline) throw new Error(`another process owns the runtime mutation lease at ${path}`);
+      (options.sleep ?? sleep)(POLL_MS);
+    }
+  }
+}
+
+function release(path, options) {
+  const currentHeld = held.get(path);
+  if (!currentHeld) return;
+  currentHeld.depth -= 1;
+  if (currentHeld.depth > 0) return;
+  held.delete(path);
+  if (currentHeld.delegated) return;
+  options.beforeRelease?.(path);
+  try {
+    const current = readOwner(path);
+    if (!current || !sameOwner(currentHeld.snapshot, current)) return;
+    unlinkSync(currentHeld.snapshot.ownerPath);
+    rmdirSync(path);
+  } catch { /* token-specific stale recovery handles an uncertain release */ }
+}
+
+export function withOwnershipMutationLease(statePaths, run, options = {}) {
+  const lease = acquireOwnershipMutationLease(statePaths, options);
+  try { return run(); }
+  finally { lease.release(); }
+}

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)();