import { accessSync, constants as fsConstants, existsSync, readFileSync, realpathSync, statSync, unlinkSync, writeFileSync } from "node:fs";
import { homedir } from "node:os";
import { delimiter, dirname, 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 { isTransientServiceLauncherPath } from "../lib/transient-service-path";
export { filterTransientServicePath, isTransientServiceLauncherPath } from "../lib/transient-service-path";
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
 * for it: `ocx claude` and `ocx opencode` set that on the proxies they spawn to borrow its
 * routing-preservation meaning, so a proxy carrying it is not necessarily the managed job.
 */
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.
export const serviceSourceDir = dirname(import.meta.dir);

export type ServiceBackend = "scheduler" | "native";

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: runtime.source === "standalone" || isStandaloneBinary() ? null : join(serviceSourceDir, "cli", "index.ts"),
  };
}

export function serviceLauncherPathDiagnostic(
  state: ServiceInstallState | null = readServiceInstallState(),
  platform: NodeJS.Platform = process.platform,
  repairing = false,
): string | null {
  const launcher = state?.launcherPath;
  if (!launcher || !isTransientServiceLauncherPath(launcher, platform)) return null;
  return `STALE temporary launcher path (${launcher}) from a shell-local version manager — `
    + (repairing ? "replacing it with a durable launcher or package-local Bun runtime"
      : "run 'ocx service repair' to replace it with a durable launcher or package-local Bun runtime");
}

/**
 * The stable `ocx` launcher to bake into a systemd unit, or null to fall back to the
 * Bun + CLI pair.
 *
 * `cliEntry()` resolves both of its paths from `import.meta.dir`, so they point INSIDE
 * the installed package tree. Under a version manager that tree is a versioned directory:
 * `~/.local/share/mise/installs/npm-opencodex/2.35.0/...`. An upgrade installs 2.36.0 and
 * deletes 2.35.0, after which the unit's `exec <old-bun> <old-cli>` cannot resolve, and
 * `Restart=on-failure` turns that into a restart loop (#2898). The shim in
 * `~/.local/share/mise/shims/ocx` survives the upgrade and dispatches to whatever version
 * is current, so it is the durable thing to name.
 *
 * Deliberately LEXICAL. Resolving the symlink would write the versioned target back into
 * the unit and reintroduce the bug — the indirection is the entire point.
 *
 * Only an absolute path is accepted. A bare `ocx` would be re-resolved through `PATH` on
 * every restart, which turns a service definition into a PATH-hijacking surface; naming
 * one validated absolute file keeps the target fixed at install time.
 *
 * The RECORDED launcher wins over a fresh PATH walk. `ocx service repair` runs from
 * whatever shell the operator (or `ocx update`, or a tray helper) happened to have, and a
 * context without `ocx` on `PATH` used to resolve null here — rewriting a working
 * launcher-form plist into the version-pinned Bun + CLI pair and then booting the healthy
 * job out to load it (#4236, defect 1g). A launcher that is still an executable file is
 * the thing the installed service already runs, so repair must keep naming it; only a
 * recorded launcher that has disappeared falls through to discovery.
 *
 * That preference is NOT macOS-only: `installSystemd` resolves this same function, so a
 * Linux `ocx service repair` from a PATH-less context keeps the `ExecStart` the unit
 * already has instead of rewriting it to the version-pinned pair — the #2898 shape this
 * function exists to avoid. The failure mode it prevents is milder there (systemd
 * `daemon-reload` + `restart` does not evict-then-maybe-nothing the way launchd did), but
 * the rewrite was the same, so the behavior is deliberately shared rather than branched.
 */
export function stableLauncherEntry(deps: {
  env?: NodeJS.ProcessEnv;
  isExecutableFile?: (path: string) => boolean;
  pathDelimiter?: string;
  state?: ServiceInstallState | null;
  platform?: NodeJS.Platform;
} = {}): string | null {
  const env = deps.env ?? process.env;
  const platform = deps.platform ?? process.platform;
  const pathTools = platform === "win32" ? win32 : posix;
  const isExecutableFile = deps.isExecutableFile ?? ((path: string): boolean => {
    try {
      if (!statSync(path).isFile()) return false;
      accessSync(path, fsConstants.X_OK);
      return true;
    } catch {
      return false;
    }
  });
  const recorded = (deps.state === undefined ? readServiceInstallState() : deps.state)?.launcherPath;
  if (recorded && !isTransientServiceLauncherPath(recorded, platform)
    && pathTools.isAbsolute(recorded) && isExecutableFile(recorded)) return recorded;
  const entries = (env.PATH ?? "").split(deps.pathDelimiter ?? delimiter);
  for (const entry of entries) {
    if (!entry || isTransientServiceLauncherPath(entry, platform) || !pathTools.isAbsolute(entry)) continue;
    const candidate = pathTools.join(entry, "ocx");
    if (isExecutableFile(candidate)) return candidate;
  }
  return null;
}

export function plistPath(): string {
  return join(homedir(), "Library", "LaunchAgents", `${LABEL}.plist`);
}

export function logPath(): string {
  return join(getConfigDir(), "service.log");
}

export function serviceLogPath(): string {
  return logPath();
}

export function windowsServiceScriptPath(): string {
  return join(getConfigDir(), "opencodex-service.cmd");
}

export function windowsLauncherVbsPath(): string {
  return join(getConfigDir(), "opencodex-service-launcher.vbs");
}

export function windowsTaskXmlPath(): string {
  return join(getConfigDir(), "opencodex-service-task.xml");
}

export function serviceStatePath(): string {
  return join(getConfigDir(), "service-state.json");
}

function defaultOpenCodexHome(): string {
  return resolve(join(homedir(), ".opencodex"));
}

export function serviceStatePathsForOpenCodexHome(opencodexHome: string): string[] {
  // Bun caches the startup home: parallel workers inherit the wrapper's HOME even
  // after the preload gives each one a sandbox. Tests must not share that mirror,
  // including serial cases that select different OPENCODEX_HOME fixtures.
  return serviceStateFilesFor(opencodexHome, isTestHomeGuardArmed() ? opencodexHome : defaultOpenCodexHome());
}

export function serviceStatePaths(): string[] {
  const paths = serviceStatePathsForOpenCodexHome(currentOpenCodexHome());
  if (!isTestHomeGuardArmed()) return paths;
  /*
   * The test resolver omits the legacy mirror; still reject an explicit or fallback
   * OPENCODEX_HOME that names the developer's real home. A missing fixture pin must
   * never allow a test to read or replace their live service installation.
   *
   * The predicate is the guard's own, not a local `resolve()` compare: the guard
   * canonicalizes through `realpath`, and on macOS a sandbox under `/var/folders/...`
   * resolves to `/private/var/folders/...`, so two spellings of one directory must not
   * decide this.
   */
  return paths.filter(path => !isProtectedHomeUnderTest(dirname(path)));
}

/**
 * The state paths a WRITE may use. Same list, but an empty one is an error instead of a
 * silent no-op.
 *
 * With OPENCODEX_HOME unset under an armed test process, `currentOpenCodexHome()` falls
 * back to the real `~/.opencodex` (`os.homedir()` ignores `$HOME`), the filter above then
 * removes every candidate, and `writeServiceInstallState` wrote NOTHING while reporting
 * success — a test asserting on install state would read the previous run's record, or
 * none. Fail the way `assertNotRealHomeUnderTest` does, naming the fix.
 */
function serviceStateWritePaths(): string[] {
  const paths = serviceStatePaths();
  if (paths.length > 0) return paths;
  throw new Error(
    "refusing to write service install state with no writable state path: every candidate "
    + "resolved to the real OpenCodex home and was filtered out. Point OPENCODEX_HOME at a "
    + "temp directory for this test (the preload does it for every invocation; something "
    + "deleted the variable without restoring it).",
  );
}

export function currentCodexHome(deps: CodexHomeDeps = {}): string {
  // Service ownership must identify the same home as the runtime. In WSL an
  // unset CODEX_HOME can resolve to the single Windows Desktop home rather than
  // Linux ~/.codex; recording the fallback here creates a false foreign owner.
  return resolveCodexHomeDir(deps);
}

/** Resolve an explicit CODEX_HOME using Windows path rules for generated service artifacts. */
export function currentWindowsServiceCodexHome(): string {
  const raw = process.env.CODEX_HOME?.trim();
  if (!raw) return currentCodexHome();
  const expanded = expandUserPath(raw);
  return win32.isAbsolute(expanded) ? win32.normalize(expanded) : resolve(expanded);
}

export function currentCodexSqliteHomeAbsolute(target: "native" | "windows" = "native"): string | undefined {
  const raw = process.env.CODEX_SQLITE_HOME?.trim();
  if (!raw) return undefined;
  const expanded = expandUserPath(raw);
  // Service artifacts can be rendered by cross-platform tests and repair tooling, so an
  // already-absolute path for the TARGET platform is preserved rather than re-anchored
  // against the writing host. `resolve()` is host-relative in both directions: on a POSIX
  // host it turns `C:\data` into `<cwd>/C:\data`, and on a Windows host it turns `/tmp/x`
  // into `D:\tmp\x` — neither is a path the target can use. A relative value still resolves,
  // because a service unit has no meaningful working directory.
  //
  // CODEX_HOME and OPENCODEX_HOME are carried through literally, so without this the same
  // generated file disagreed with itself about two variables holding the same kind of value.
  if (target === "windows") {
    return win32.isAbsolute(expanded) ? win32.normalize(expanded) : resolve(expanded);
  }
  return posix.isAbsolute(expanded) ? posix.normalize(expanded) : resolve(expanded);
}

export function currentOpenCodexHome(): string {
  // getConfigDir() already resolves OPENCODEX_HOME with ~ expansion; keep the
  // install-state comparison on the same normalization or `~/...` values falsely
  // fail the environment-match check depending on cwd.
  return getConfigDir();
}

export function normalizePathForCompare(path: string): string {
  const resolved = resolve(path);
  return process.platform === "win32" ? resolved.toLowerCase() : resolved;
}

export interface ServiceInstallState {
  version: 1 | 2;
  codexHome: string;
  opencodexHome: string;
  /** Effective Codex SQLite home used by this service's history integration. */
  codexSqliteHome?: string;
  /** Baked at install; lets status flag paths gone stale after npm prefix/nvm moves. */
  bunPath?: 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,
   * NOT what the service runs — so staleness must be judged against THIS path instead. A version-manager
   * upgrade replaces the directory those two point into while the launcher survives, and
   * checking the old pair would report a stale service that is in fact healthy.
   */
  launcherPath?: string;
  /** v2: which Windows backend was chosen at install; absent (v1/legacy) means scheduler. */
  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 {
  return parseInstallStateRecord(value) as ServiceInstallState | null;
}

/**
 * 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 | undefined, runtime: DurableBunRuntime): ServiceInstallState {
  const { bun, cli } = cliEntry(runtime);
  const codexHome = currentCodexHome();
  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 } : {}),
  };
}

/**
 * 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 = {},
  runtime: DurableBunRuntime = durableBunRuntime(),
): void {
  swapServiceInstallState(current => ({
    ...installProvenanceRecord(backend, launcherPath, runtime),
    ...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 {
  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";
  }
}

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. */
export type ServiceStateEvidence =
  | { 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: ServiceInstallState };

/**
 * Every state path, with what each one said.
 *
 * 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 => (
    inspectInstallStateBytes(path, at => readFileSync(at, "utf8")) as ServiceStateEvidence
  ));
}

/** The homes this process is actually using, for comparison against a claim. */
export function currentServiceHomes(deps: CodexHomeDeps = {}): { codexHome: string; opencodexHome: string } {
  return { codexHome: currentCodexHome(deps), opencodexHome: currentOpenCodexHome() };
}

export function serviceHomeMatches(a: string, b: string): boolean {
  return normalizePathForCompare(a) === normalizePathForCompare(b);
}

export type ServicePathComparison = "same" | "different" | "unknown";

/**
 * Tri-state physical-home compare. A realpath failure (EACCES, EPERM, a
 * vanished directory, transient I/O) is "unknown", not "different": callers
 * deciding whether a home is foreign must not turn an unreadable resolution
 * into a definitive mismatch. Lifecycle guards may still fail closed on
 * "unknown".
 */
export function compareServicePathToInstall(recorded: string, current: string, deps: CodexHomeDeps = {}): ServicePathComparison {
  if (serviceHomeMatches(recorded, current)) return "same";
  const realpath = deps.realpathSync ?? realpathSync;
  let currentPhysical: string;
  try {
    currentPhysical = realpath(current);
  } catch {
    return "unknown";
  }
  try {
    return serviceHomeMatches(realpath(recorded), currentPhysical) ? "same" : "different";
  } catch (error) {
    // The spellings already differ. A recorded path that no longer exists cannot be an alias of
    // the current home, so it stays a mismatch (a stale mount keeps the foreign-owner refusal);
    // only an error that leaves existence unproven, such as EACCES, is indeterminate.
    const code = (error as NodeJS.ErrnoException | null)?.code;
    return code === "ENOENT" || code === "ENOTDIR" ? "different" : "unknown";
  }
}

/** Lexical compare first; when spellings differ, compare the directories both resolve to so a
 * junction or symlink spelling recorded by an older install still names the same home.
 * Fails closed on an indeterminate resolution — ownership classification needs the
 * tri-state {@link compareServicePathToInstall} instead. */
export function servicePathMatchesInstall(recorded: string, current: string, deps: CodexHomeDeps = {}): boolean {
  return compareServicePathToInstall(recorded, current, deps) === "same";
}

export function serviceCodexHomeMatchesInstall(recordedHome: string, deps: CodexHomeDeps = {}): boolean {
  return servicePathMatchesInstall(recordedHome, currentCodexHome(deps), deps);
}

/** Single accessor for backend-sensitive service code — v1/legacy state maps to scheduler. */
export function readServiceBackend(): ServiceBackend {
  return readServiceInstallState()?.backend === "native" ? "native" : "scheduler";
}

/**
 * The `ocx` argv that refreshes an already-installed service after an update.
 *
 * `repair` discovers the installed backend itself. A healthy Windows scheduler task only
 * gets refreshed assets plus a restart; a stale live definition is re-registered and may
 * require elevation. `install` always reaches `/create`, so using repair here avoids an
 * unnecessary admin prompt for the common healthy update path.
 *
 * The historical export name is kept for callers outside this module.
 */
export function serviceReinstallArgs(): string[] {
  return ["service", "repair"];
}

/** The `ocx` argv that registers a service from scratch, preserving the chosen backend. */
export function serviceInstallArgs(): string[] {
  return readServiceBackend() === "native" ? ["service", "install", "--native"] : ["service", "install"];
}
