// canonical filesystem layout under ~/.rnx/. shared by the CLI and the
// electron main process so every surface agrees where runtimes, the daemon
// lockfile, and caches live.
//
//   ~/.rnx/
//   ├── runtimes/
//   │   ├── <version>/     unpacked dist/ of sootsim-engine
//   │   └── active         text file with the active version string (win-safe
//   │                      alternative to a symlink)
//   ├── electron/
//   │   └── <version>/     pinned electron binary (future: playwright-style)
//   ├── profiles/
//   │   └── profiles.json  storage profile metadata
//   ├── cache/
//   │   └── rnx-runtime-<version>.tar.gz
//   ├── daemon.json        lockfile: pid, ports, active runtime, heartbeat
//   ├── dev-bridges/       live Vite dev bridge records, keyed by bound port
//   ├── runtime-upgraded.json  one-shot notice written by the daemon's
//   │                      background updater, consumed (printed + deleted)
//   │                      by the next interactive CLI run
//   ├── cli-update.json    cached standalone CLI release check + notice state
//   ├── automatic-cleanup-v1.json  completion marker for the one-time safe
//   │                      cleanup introduced for legacy unbounded data
//   └── config.json        user prefs: update channel, cdn origin override,
//                          telemetry, engine settings, default box

import { randomUUID } from 'node:crypto'
import fs from 'node:fs'
import { homedir } from 'node:os'
import path from 'node:path'

export const RNX_HOME_ENV = 'RNX_HOME'
export const ACTIVE_RUNTIME_FILE = 'active'
export const DAEMON_LOCKFILE = 'daemon.json'
export const DEV_BRIDGES_DIR = 'dev-bridges'
export const CONFIG_FILE = 'config.json'
export const CLI_UPDATE_FILE = 'cli-update.json'
export const DAEMON_HEARTBEAT_STALE_MS = 30_000

export function rnxHomeDir(): string {
  const override = process.env[RNX_HOME_ENV]
  if (override && override.length > 0) return path.resolve(override)
  return path.join(homedir(), '.rnx')
}

// detect when sootsim is running from a source checkout (the Contrast monorepo)
// rather than a published npm install. used to skip auto-install of the
// persistent launchd / systemd agent: dev shells shouldn't register an agent
// whose Program path points at workspace artifacts that change between
// sessions, and whose served engine assets are the stale prod build instead
// of the live `bun dev:sootsim` output.
//
// overrides:
//   SOOTSIM_DEV=1 / SOOTSIM_DEV=0           force the answer
//   SOOTSIM_FORCE_DAEMON_INSTALL=1          pretend prod even from a dev
//                                           checkout, for exercising the
//                                           install path from this repo
//
// signal: realpath of process.argv[1] lands inside a `packages/sootsim/`
// directory. workspace bin symlinks (`node_modules/.bin/sootsim` →
// `packages/sootsim/dist-cli/bin.js`) and bun-direct invocations
// (`bun packages/sootsim/cli/bin.ts ...`) both match; published installs
// resolve under `node_modules/sootsim/` instead.
export function isSootsimDevCheckout(): boolean {
  if (process.env.SOOTSIM_FORCE_DAEMON_INSTALL === '1') return false
  const env = process.env.SOOTSIM_DEV
  if (env === '1' || env === 'true') return true
  if (env === '0' || env === 'false') return false
  const argv1 = process.argv[1]
  if (!argv1) return false
  try {
    const real = fs.realpathSync(argv1)
    return real.includes(`${path.sep}packages${path.sep}sootsim${path.sep}`)
  } catch {
    return false
  }
}

// detect the human's dev workstation by the env markers the developer sets in
// their shell profile (`IS_TAMAGUI_DEV=1` in ~/.zshrc). distinct from
// isSootsimDevCheckout, which keys on the *binary path*: a globally-installed
// `sootsim` binary on the dev machine would NOT match the checkout path, yet a
// persistent daemon registered there is just as dangerous. it runs in the
// background carrying the workstation's dev env (dev auth tokens, prod-pointing
// vars), and when the live `bun dev` stack already owns the bridge port it
// silently lands on a fallback port and shadows the real one with stale assets
// — the "I was on the daemon on port 7-something" footgun.
//
// override: SOOTSIM_FORCE_DAEMON_INSTALL=1 to run the daemon here anyway.
export function isDevWorkstation(): boolean {
  if (process.env.SOOTSIM_FORCE_DAEMON_INSTALL === '1') return false
  return process.env.IS_TAMAGUI_DEV === '1'
}

// the persistent launchd / systemd daemon must never auto-install or run on a
// dev checkout or a dev workstation. either makes the background agent point at
// moving workspace artifacts / dev env and serve stale assets that shadow the
// live dev stack. setup and the launchd-spawned `rnx serve` boot consult
// this; a foreground `rnx serve` the dev starts
// by hand is intentional and stays allowed.
export function shouldSkipPersistentDaemon(): boolean {
  return isSootsimDevCheckout() || isDevWorkstation()
}

export function runtimesDir(): string {
  return path.join(rnxHomeDir(), 'runtimes')
}

export function runtimeDir(version: string): string {
  return path.join(runtimesDir(), version)
}

export function activeRuntimeFile(): string {
  return path.join(runtimesDir(), ACTIVE_RUNTIME_FILE)
}

export function electronDir(): string {
  return path.join(rnxHomeDir(), 'electron')
}

export function electronUserDataDir(): string {
  return path.join(electronDir(), 'userData')
}

export function electronVersionDir(version: string): string {
  return path.join(electronDir(), version)
}

export function profilesDir(): string {
  return path.join(rnxHomeDir(), 'profiles')
}

// video fixtures staged for `rnx camera play`. the CLI copies the user's
// file in here and the daemon serves it by basename from this one directory,
// so the route can never be talked into reading anywhere else on disk.
export function cameraFixturesDir(): string {
  return path.join(rnxHomeDir(), 'camera-fixtures')
}

// the launchd-managed daemon spawns ProgramArguments[0] directly, and macOS
// Background Task Management attributes the entry to whoever code-signed
// that binary. pointing launchd at bun directly makes Login Items say
// "software from Jarred Sumner" (bun's signer); wrapping the invocation in
// an ad-hoc-signed .app bundle here gives BTM a CFBundleDisplayName to
// read instead.
export function daemonAppDir(): string {
  return path.join(rnxHomeDir(), 'daemon-app')
}

export function daemonAppBundlePath(): string {
  return path.join(daemonAppDir(), 'RNX Daemon.app')
}

export function daemonAppLauncherPath(): string {
  return path.join(daemonAppBundlePath(), 'Contents', 'MacOS', 'rnx-daemon')
}

export function cacheDir(): string {
  return path.join(rnxHomeDir(), 'cache')
}

export function daemonLockfilePath(): string {
  return path.join(rnxHomeDir(), DAEMON_LOCKFILE)
}

export function devBridgesDir(): string {
  return path.join(rnxHomeDir(), DEV_BRIDGES_DIR)
}

export function devBridgeLockfilePath(bridgePort: number): string {
  if (!Number.isInteger(bridgePort) || bridgePort <= 0) {
    throw new Error(`invalid development bridge port: ${bridgePort}`)
  }
  return path.join(devBridgesDir(), `${bridgePort}.json`)
}

export function configFilePath(): string {
  return path.join(rnxHomeDir(), CONFIG_FILE)
}

export function cliUpdateFilePath(): string {
  return path.join(rnxHomeDir(), CLI_UPDATE_FILE)
}

// --- shared rnx config ---------------------------------------------------
//
// ~/.rnx/config.json is the single user-level config file every rnx
// surface (cli, electron renderer, dev browser via electron ipc) agrees on.
//
// privacy preferences live in the nested settings object so the cli, desktop
// main process, renderer, daemon-served browser, and settings UI all read and
// write one persisted value per choice.

export interface SharedConfig {
  telemetry?: boolean
  onboardingVersion?: number
  simulatorDriver?: 'electron' | 'playwright'
  settings?: Record<string, unknown>
  [key: string]: unknown
}

export function readSharedConfig(): SharedConfig {
  try {
    const raw = fs.readFileSync(configFilePath(), 'utf8')
    const parsed = JSON.parse(raw) as SharedConfig
    return parsed && typeof parsed === 'object' ? parsed : {}
  } catch {
    return {}
  }
}

/** merge `patch` into the shared config and atomically write to disk. nested
 *  objects (currently just `settings`) are shallow-merged so partial writes
 *  don't clobber unrelated fields. returns the new full snapshot. */
export function writeSharedConfig(patch: Partial<SharedConfig>): SharedConfig {
  ensureRnxHome()
  const current = readSharedConfig()
  const next: SharedConfig = { ...current, ...patch }
  if (patch.settings && typeof patch.settings === 'object') {
    next.settings = {
      ...(current.settings && typeof current.settings === 'object'
        ? current.settings
        : {}),
      ...patch.settings,
    }
  }
  const tmp = `${configFilePath()}.tmp`
  fs.writeFileSync(tmp, `${JSON.stringify(next, null, 2)}\n`, 'utf8')
  fs.renameSync(tmp, configFilePath())
  return next
}

const CURRENT_ONBOARDING_VERSION = 1

export type SimulatorDriverPreference = 'electron' | 'playwright'

export function isOnboardingComplete(): boolean {
  return readSharedConfig().onboardingVersion === CURRENT_ONBOARDING_VERSION
}

export function readSimulatorDriverPreference(): SimulatorDriverPreference | null {
  const driver = readSharedConfig().simulatorDriver
  return driver === 'electron' || driver === 'playwright' ? driver : null
}

export function writeOnboardingPreferences(driver: SimulatorDriverPreference): void {
  writeSharedConfig({
    onboardingVersion: CURRENT_ONBOARDING_VERSION,
    simulatorDriver: driver,
  })
}

export interface PrivacyPreferences {
  productAnalytics: boolean
  crashReports: boolean
  configured: boolean
}

export function readPrivacyPreferences(): PrivacyPreferences {
  const settings = readSharedConfig().settings
  const productAnalytics = settings?.productAnalytics
  const crashReports = settings?.crashReports
  return {
    productAnalytics: typeof productAnalytics === 'boolean' ? productAnalytics : false,
    crashReports: typeof crashReports === 'boolean' ? crashReports : false,
    configured:
      typeof productAnalytics === 'boolean' && typeof crashReports === 'boolean',
  }
}

export function writePrivacyPreferences(
  preferences: Pick<PrivacyPreferences, 'productAnalytics' | 'crashReports'>,
): void {
  writeSharedConfig({
    settings: {
      productAnalytics: preferences.productAnalytics,
      crashReports: preferences.crashReports,
    },
  })
}

// stable per-machine anonymous telemetry id. every signed-out cli used to
// report as the single literal distinct_id 'anonymous-cli', which merged all
// first-run users into one posthog person and made "a new user's login hung"
// impossible to see. created lazily on first use, persisted in config.json.
export function readOrCreateAnonymousId(): string {
  const existing = readSharedConfig().anonymousId
  if (typeof existing === 'string' && existing.trim()) return existing
  const created = `anon-cli-${randomUUID()}`
  writeSharedConfig({ anonymousId: created })
  return created
}

// --- default box ----------------------------------------------------------
//
// the box every box verb acts on when the command line names none. `rnx box
// use` writes it and `rnx box stop` clears it when it stops that box.
//
// the id and the display name, and nothing else. a Box is reached with a
// bearer token the account service hands out per attach, so writing one here
// would make this file a credential store; every verb resolves the token
// again from the id it reads back.

export interface DefaultBox {
  boxId: string
  name: string | null
}

export function readDefaultBox(): DefaultBox | null {
  const stored = readSharedConfig().defaultBox
  if (typeof stored !== 'object' || stored === null) return null
  if (!('boxId' in stored) || typeof stored.boxId !== 'string' || !stored.boxId) {
    return null
  }
  const name = 'name' in stored && typeof stored.name === 'string' ? stored.name : null
  return { boxId: stored.boxId, name }
}

/** set the default box, or clear it with null. */
export function writeDefaultBox(box: DefaultBox | null): void {
  writeSharedConfig({ defaultBox: box })
}

// --- background-upgrade notice --------------------------------------------
//
// the daemon auto-updates the engine runtime in the background (hourly), so
// the only place its "updated to vX" line lands is the daemon's own stderr,
// which nobody reads. it also drops a one-shot notice file here; the next
// interactive CLI invocation prints it once and deletes it, so users learn
// their engine moved without having to run `rnx version`.

export interface RuntimeUpgradeNotice {
  from: string | null
  to: string
  at: number
}

export function runtimeUpgradeNoticePath(): string {
  return path.join(rnxHomeDir(), 'runtime-upgraded.json')
}

export function writeRuntimeUpgradeNotice(notice: RuntimeUpgradeNotice): void {
  ensureRnxHome()
  const tmp = `${runtimeUpgradeNoticePath()}.tmp`
  fs.writeFileSync(tmp, `${JSON.stringify(notice)}\n`, 'utf8')
  fs.renameSync(tmp, runtimeUpgradeNoticePath())
}

/** read + delete the pending upgrade notice, or null when none is pending.
 *  deleting first-read keeps the banner one-shot even across racing CLIs. */
export function consumeRuntimeUpgradeNotice(): RuntimeUpgradeNotice | null {
  try {
    const raw = fs.readFileSync(runtimeUpgradeNoticePath(), 'utf8')
    fs.unlinkSync(runtimeUpgradeNoticePath())
    const parsed = JSON.parse(raw) as Partial<RuntimeUpgradeNotice>
    if (typeof parsed?.to !== 'string' || !parsed.to) return null
    return {
      from: typeof parsed.from === 'string' ? parsed.from : null,
      to: parsed.to,
      at: typeof parsed.at === 'number' ? parsed.at : 0,
    }
  } catch {
    return null
  }
}

export function ensureRnxHome(): void {
  fs.mkdirSync(rnxHomeDir(), { recursive: true })
  fs.mkdirSync(runtimesDir(), { recursive: true })
  fs.mkdirSync(electronDir(), { recursive: true })
  fs.mkdirSync(profilesDir(), { recursive: true })
  fs.mkdirSync(cacheDir(), { recursive: true })
}

/** read the active runtime version string, or null if none is selected. */
export function readActiveRuntime(): string | null {
  try {
    const value = fs.readFileSync(activeRuntimeFile(), 'utf8').trim()
    return value.length > 0 ? value : null
  } catch {
    return null
  }
}

/** set the active runtime version. caller is responsible for verifying the
 *  version actually exists on disk before calling. */
export function writeActiveRuntime(version: string): void {
  fs.mkdirSync(runtimesDir(), { recursive: true })
  fs.writeFileSync(activeRuntimeFile(), `${version}\n`, 'utf8')
}

// listInstalledRuntimes + compareSemver live in @contrast/runtime-delivery:
// they are delivery machinery (sorting the hosted catalog, deciding whether
// channel latest is newer than active), shared with contrast, and this module
// stays free of that dependency so every published `sootsim/*` export that
// resolves through it keeps working with no bundling requirement.

/** absolute path to the active runtime's directory, or null if none active
 *  or the active version is no longer installed. */
export function activeRuntimeDir(): string | null {
  const version = readActiveRuntime()
  if (!version) return null
  const dir = runtimeDir(version)
  try {
    if (fs.statSync(dir).isDirectory()) return dir
  } catch {}
  return null
}

// --- daemon lockfile ----------------------------------------------------

export interface DaemonLockfile {
  /** sootsim cli/daemon version that wrote the lockfile. bumped whenever
   *  the lockfile shape changes so readers can gate on it. */
  schema: 1
  pid: number
  /** platform — useful when one home dir is shared across platforms via NFS. */
  platform: NodeJS.Platform
  /** ws bridge port (where cli + electron open control connections). */
  bridgePort: number
  /** http runtime server port (where electron loads the renderer from). */
  runtimePort: number
  /** active runtime version at boot, or null if the daemon booted with no
   *  runtime installed. updated live when the user runs `sootsim runtime use`. */
  activeRuntime: string | null
  /** absolute path to the active runtime's dist directory, or null. */
  activeRuntimeDir: string | null
  /** repo-selected runtime versions currently served to connected sims. */
  servedRuntimes?: string[]
  /** epoch-ms of daemon start. */
  startedAt: number
  /** epoch-ms of last heartbeat. daemons update this every ~5s; readers
   *  treat the lockfile as stale if now - heartbeatAt > DAEMON_HEARTBEAT_STALE_MS. */
  heartbeatAt: number
  /** true while the daemon is still fetching/activating its runtime on first
   *  boot. clients (electron splash, cli) should wait for this to become
   *  false before treating the daemon as ready to serve. */
  bootstrapping?: boolean
}

export interface DevBridgeLockfile {
  schema: 1
  pid: number
  platform: NodeJS.Platform
  bridgePort: number
  runtimePort: number
  /** http port of the vite shell dev server that owns this bridge (e.g. 5173).
   *  optional: lockfiles written before this field existed still parse, and
   *  readers fall back to the default shell URL. this is what lets the CLI
   *  resolve the shell base URL and the bridge port from the SAME world
   *  instead of mixing dev bridge + daemon runtime (the split-brain bug). */
  shellPort?: number
  cwd: string
  startedAt: number
  heartbeatAt: number
  source: 'vite-dev'
  /** repo-selected runtime versions currently served to connected sims. */
  servedRuntimes?: string[]
}

const DAEMON_LOCKFILE_MAX_BYTES = 16 * 1024
const DAEMON_CLAIM_STALE_MS = 30_000

interface DaemonClaim {
  pid: number
  startedAt: number
  createdAt: number
}

export function readDaemonLockfile(): DaemonLockfile | null {
  try {
    // cap the read so a junk/large file on the lockfile path can't OOM
    // the CLI when someone has been messing with ~/.rnx/.
    const fd = fs.openSync(daemonLockfilePath(), 'r')
    try {
      const buf = Buffer.alloc(DAEMON_LOCKFILE_MAX_BYTES)
      const bytesRead = fs.readSync(fd, buf, 0, DAEMON_LOCKFILE_MAX_BYTES, 0)
      const raw = buf.subarray(0, bytesRead).toString('utf8')
      const parsed = JSON.parse(raw) as Partial<DaemonLockfile>
      if (
        parsed &&
        parsed.schema === 1 &&
        typeof parsed.pid === 'number' &&
        typeof parsed.bridgePort === 'number' &&
        typeof parsed.runtimePort === 'number' &&
        typeof parsed.startedAt === 'number' &&
        typeof parsed.heartbeatAt === 'number' &&
        (parsed.servedRuntimes === undefined ||
          (Array.isArray(parsed.servedRuntimes) &&
            parsed.servedRuntimes.every((version) => typeof version === 'string')))
      ) {
        return parsed as DaemonLockfile
      }
      return null
    } finally {
      fs.closeSync(fd)
    }
  } catch {
    return null
  }
}

function parseDevBridgeLockfile(raw: string): DevBridgeLockfile | null {
  try {
    const parsed = JSON.parse(raw)
    if (
      parsed &&
      parsed.schema === 1 &&
      parsed.source === 'vite-dev' &&
      typeof parsed.pid === 'number' &&
      typeof parsed.bridgePort === 'number' &&
      typeof parsed.runtimePort === 'number' &&
      typeof parsed.cwd === 'string' &&
      typeof parsed.startedAt === 'number' &&
      typeof parsed.heartbeatAt === 'number' &&
      (parsed.shellPort === undefined || typeof parsed.shellPort === 'number') &&
      (parsed.servedRuntimes === undefined ||
        (Array.isArray(parsed.servedRuntimes) &&
          parsed.servedRuntimes.every((version: unknown) => typeof version === 'string')))
    ) {
      return parsed
    }
    return null
  } catch {
    return null
  }
}

export function readDevBridgeLockfiles(): DevBridgeLockfile[] {
  let entries: fs.Dirent[]
  try {
    entries = fs.readdirSync(devBridgesDir(), { withFileTypes: true })
  } catch {
    return []
  }

  const lockfiles: DevBridgeLockfile[] = []
  for (const entry of entries) {
    if (!entry.isFile() || !/^\d+\.json$/.test(entry.name)) continue
    try {
      const filePath = path.join(devBridgesDir(), entry.name)
      const fd = fs.openSync(filePath, 'r')
      try {
        const buf = Buffer.alloc(DAEMON_LOCKFILE_MAX_BYTES)
        const bytesRead = fs.readSync(fd, buf, 0, DAEMON_LOCKFILE_MAX_BYTES, 0)
        const lockfile = parseDevBridgeLockfile(
          buf.subarray(0, bytesRead).toString('utf8'),
        )
        if (lockfile && entry.name === `${lockfile.bridgePort}.json`) {
          lockfiles.push(lockfile)
        }
      } finally {
        fs.closeSync(fd)
      }
    } catch {}
  }
  return lockfiles.sort((left, right) => left.bridgePort - right.bridgePort)
}

/** true when the lockfile exists, the named pid is alive, and the heartbeat
 *  is recent. callers should reach for this before trusting any of the
 *  ports inside.
 *
 *  pid-reuse note: `process.kill(pid, 0)` only checks that *some* process
 *  with that pid exists. after a reboot or heavy fork churn the OS can
 *  recycle the pid onto an unrelated process owned by the same user. the
 *  heartbeat freshness check catches most of that (30s stale ⇒ reject),
 *  but a stale lockfile where pid happens to be reused < 30s ago could
 *  still slip through. the consumer paths that actually connect (electron
 *  + ws-bridge client) time out quickly, so a stale lockfile degrades to
 *  "connect attempt fails" rather than corrupt state. */
export function isDaemonLockfileFresh(
  lock: DaemonLockfile | null,
  now = Date.now(),
): lock is DaemonLockfile {
  if (!lock) return false
  if (now - lock.heartbeatAt > DAEMON_HEARTBEAT_STALE_MS) return false
  try {
    // signal 0 just tests whether the pid exists + we have perm to signal.
    process.kill(lock.pid, 0)
    return true
  } catch {
    return false
  }
}

export function isDevBridgeLockfileFresh(
  lock: DevBridgeLockfile | null,
  now = Date.now(),
): lock is DevBridgeLockfile {
  if (!lock) return false
  if (now - lock.heartbeatAt > DAEMON_HEARTBEAT_STALE_MS) return false
  try {
    process.kill(lock.pid, 0)
    return true
  } catch {
    return false
  }
}

export function readLiveRuntimeVersions(): string[] {
  const versions = new Set<string>()
  const daemon = readDaemonLockfile()
  if (isDaemonLockfileFresh(daemon)) {
    if (daemon.activeRuntime) versions.add(daemon.activeRuntime)
    for (const version of daemon.servedRuntimes ?? []) versions.add(version)
  }
  for (const devBridge of readDevBridgeLockfiles()) {
    if (!isDevBridgeLockfileFresh(devBridge)) continue
    for (const version of devBridge.servedRuntimes ?? []) versions.add(version)
  }
  return [...versions].sort()
}

export function writeDaemonLockfile(data: DaemonLockfile): void {
  ensureRnxHome()
  const lockfilePath = daemonLockfilePath()
  const existing = readDaemonLockfile()
  if (!existing) {
    if (createDaemonLockfileExclusive(data)) return
    throw new Error('another rnx daemon claimed the lockfile before this write')
  }
  if (!sameDaemonOwner(existing, data)) {
    throw new Error('refusing to overwrite another rnx daemon lockfile')
  }
  const tmp = `${lockfilePath}.${data.pid}.${randomUUID()}.tmp`
  fs.writeFileSync(tmp, `${JSON.stringify(data, null, 2)}\n`, 'utf8')
  try {
    const current = readDaemonLockfile()
    if (!current || !sameDaemonOwner(current, data)) {
      throw new Error('rnx daemon lock ownership changed during heartbeat')
    }
    fs.renameSync(tmp, lockfilePath)
  } finally {
    try {
      fs.unlinkSync(tmp)
    } catch {}
  }
}

export function writeDevBridgeLockfile(data: DevBridgeLockfile): void {
  fs.mkdirSync(devBridgesDir(), { recursive: true })
  const lockfilePath = devBridgeLockfilePath(data.bridgePort)
  const tmp = `${lockfilePath}.${data.pid}.tmp`
  fs.writeFileSync(tmp, `${JSON.stringify(data, null, 2)}\n`, 'utf8')
  fs.renameSync(tmp, lockfilePath)
}

function sameDaemonOwner(
  left: Pick<DaemonLockfile, 'pid' | 'startedAt'>,
  right: Pick<DaemonLockfile, 'pid' | 'startedAt'>,
): boolean {
  return left.pid === right.pid && left.startedAt === right.startedAt
}

function isAlreadyExists(error: unknown): boolean {
  return (
    error instanceof Error && 'code' in error && Reflect.get(error, 'code') === 'EEXIST'
  )
}

function createDaemonLockfileExclusive(data: DaemonLockfile): boolean {
  const lockfilePath = daemonLockfilePath()
  const tmp = `${lockfilePath}.${data.pid}.${randomUUID()}.claim`
  fs.writeFileSync(tmp, `${JSON.stringify(data, null, 2)}\n`, 'utf8')
  try {
    fs.linkSync(tmp, lockfilePath)
    return true
  } catch (error) {
    if (isAlreadyExists(error)) return false
    throw error
  } finally {
    try {
      fs.unlinkSync(tmp)
    } catch {}
  }
}

function daemonClaimPath(): string {
  return `${daemonLockfilePath()}.claim`
}

function parseDaemonClaim(raw: string): DaemonClaim | null {
  try {
    const value: unknown = JSON.parse(raw)
    if (
      value !== null &&
      typeof value === 'object' &&
      typeof Reflect.get(value, 'pid') === 'number' &&
      typeof Reflect.get(value, 'startedAt') === 'number' &&
      typeof Reflect.get(value, 'createdAt') === 'number'
    ) {
      return {
        pid: Reflect.get(value, 'pid'),
        startedAt: Reflect.get(value, 'startedAt'),
        createdAt: Reflect.get(value, 'createdAt'),
      }
    }
  } catch {}
  return null
}

function readDaemonClaim(): DaemonClaim | null {
  try {
    return parseDaemonClaim(fs.readFileSync(daemonClaimPath(), 'utf8'))
  } catch {
    return null
  }
}

function isDaemonClaimFresh(claim: DaemonClaim, now = Date.now()): boolean {
  if (now - claim.createdAt > DAEMON_CLAIM_STALE_MS) return false
  try {
    process.kill(claim.pid, 0)
    return true
  } catch {
    return false
  }
}

function acquireDaemonClaim(data: DaemonLockfile): boolean {
  const claim: DaemonClaim = {
    pid: data.pid,
    startedAt: data.startedAt,
    createdAt: Date.now(),
  }
  const serialized = `${JSON.stringify(claim)}\n`
  for (let attempt = 0; attempt < 8; attempt++) {
    try {
      fs.writeFileSync(daemonClaimPath(), serialized, { encoding: 'utf8', flag: 'wx' })
      return true
    } catch (error) {
      if (!isAlreadyExists(error)) throw error
    }
    const existing = readDaemonClaim()
    if (existing && sameDaemonOwner(existing, claim)) return true
    if (existing && isDaemonClaimFresh(existing)) return false
    let before: string
    try {
      before = fs.readFileSync(daemonClaimPath(), 'utf8')
      const latest = parseDaemonClaim(before)
      if (latest && isDaemonClaimFresh(latest)) return false
      if (fs.readFileSync(daemonClaimPath(), 'utf8') !== before) continue
      fs.unlinkSync(daemonClaimPath())
    } catch {}
  }
  return false
}

function releaseDaemonClaim(owner: Pick<DaemonLockfile, 'pid' | 'startedAt'>): void {
  try {
    const claim = readDaemonClaim()
    if (!claim || !sameDaemonOwner(claim, owner)) return
    fs.unlinkSync(daemonClaimPath())
  } catch {}
}

/** try to claim the lockfile atomically on daemon boot. a short-lived,
 *  process-owned election file serializes concurrent fallback-port binds;
 *  the complete lock snapshot is then installed with an exclusive hard link. */
export function claimDaemonLockfile(data: DaemonLockfile): boolean {
  ensureRnxHome()
  if (!acquireDaemonClaim(data)) return false
  try {
    const existing = readDaemonLockfile()
    if (existing && sameDaemonOwner(existing, data)) {
      writeDaemonLockfile(data)
      return true
    }
    if (existing && isDaemonLockfileFresh(existing)) return false
    if (existing) {
      const latest = readDaemonLockfile()
      if (!latest || !sameDaemonOwner(latest, existing)) return false
      if (isDaemonLockfileFresh(latest)) return false
      try {
        fs.unlinkSync(daemonLockfilePath())
      } catch {
        return false
      }
    }
    return createDaemonLockfileExclusive(data)
  } finally {
    releaseDaemonClaim(data)
  }
}

export function removeDaemonLockfile(
  owner: Pick<DaemonLockfile, 'pid' | 'startedAt'>,
): void {
  try {
    const lockfile = readDaemonLockfile()
    if (!lockfile || !sameDaemonOwner(lockfile, owner)) return
    fs.unlinkSync(daemonLockfilePath())
  } catch {}
}

export function removeDevBridgeLockfile(
  owner: Pick<DevBridgeLockfile, 'bridgePort' | 'pid' | 'startedAt'>,
): void {
  try {
    const lockfilePath = devBridgeLockfilePath(owner.bridgePort)
    const lockfile = parseDevBridgeLockfile(fs.readFileSync(lockfilePath, 'utf8'))
    if (lockfile?.pid !== owner.pid || lockfile.startedAt !== owner.startedAt) return
    fs.unlinkSync(lockfilePath)
  } catch {}
}