rnxsim 0.1.313 → 0.1.314

package/cli/commands/daemon.ts

@@ -0,0 +1,874 @@
+// sootsim daemon — manage the persistent sootsim bridge daemon
+//
+// wraps `sootsim serve` so it starts automatically on login and restarts if
+// it crashes. the agent is tied to whichever `sootsim` binary resolves at
+// registration time, so `npm update -g sootsim` + `sootsim daemon restart`
+// picks up the upgrade without touching the plist/unit file.
+//
+// `daemonInstall` is shared by `sootsim setup` and the explicit
+// `sootsim daemon install` machine-bootstrap path.
+//
+//   macOS:  ~/Library/LaunchAgents/dev.sootsim.daemon.plist (launchd)
+//   linux:  ~/.config/systemd/user/sootsim-daemon.service (systemd --user)
+//   win:    not yet supported — use `sootsim serve` in a persistent shell.
+//
+// the macOS launchd Label is `dev.sootsim.daemon` (matching the .app
+// CFBundleIdentifier).
+
+import { execFileSync, spawnSync } from 'child_process'
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  realpathSync,
+  rmSync,
+  writeFileSync,
+} from 'fs'
+import { homedir } from 'os'
+import { basename, dirname, resolve, sep } from 'path'
+import { DEFAULT_SOOTSIM_BRIDGE_PORT } from '../../src/bridge-constants'
+import { getCliVersion } from '../../src/cli-version'
+import {
+  daemonAppBundlePath,
+  isDaemonLockfileFresh,
+  readDaemonLockfile,
+  shouldSkipPersistentDaemon,
+  sootsimHomeDir,
+} from '../../src/home-paths'
+import { rnxPublicBrand } from '../../src/public-brand'
+import { printCommandHelp } from '../help'
+import { flushCliTelemetry, trackCliEvent } from '../telemetry'
+import { ensureDaemonApp } from './daemon-mac-app'
+
+// minimum seconds between launchd / systemd respawns. without this, a daemon
+// that crashes on startup respawns in a tight loop — launchd's default is 10s,
+// systemd's previous setting was 3s. bumping to 60s caps the damage of any
+// misconfig that still slips past the bridge-host's port-fallback search.
+const RESPAWN_THROTTLE_SECONDS = 60
+
+const SERVICE_LABEL_MAC = 'dev.sootsim.daemon'
+const LEGACY_SERVICE_LABEL_MAC = 'dev.sootsim.server'
+const SERVICE_NAME_LINUX = 'sootsim-daemon'
+const LOG_DIR = resolve(homedir(), 'Library/Logs/sootsim')
+const LOG_DIR_LINUX = resolve(homedir(), '.local/state/sootsim')
+
+interface DaemonOptions {
+  port?: number
+}
+
+export async function runDaemon(args: string[], opts: DaemonOptions = {}) {
+  const [sub, ...rest] = args
+  const port = opts.port ?? DEFAULT_SOOTSIM_BRIDGE_PORT
+
+  if (!sub || sub === '--help' || sub === '-h') {
+    printHelp()
+    return
+  }
+
+  // emit a single observable event per subcommand. validate against the
+  // known set so an unknown / malformed `sub` (e.g. accidental path or
+  // shell-expanded garbage) doesn't pollute the posthog event taxonomy.
+  // tagged with subsource so daemon traffic is filterable from regular
+  // cli traffic.
+  const KNOWN_SUBCOMMANDS = new Set([
+    'install',
+    'uninstall',
+    'restart',
+    'start',
+    'stop',
+    'logs',
+  ])
+  if (KNOWN_SUBCOMMANDS.has(sub)) {
+    trackCliEvent({
+      event: `daemon_${sub}`,
+      properties: { platform: process.platform, subsource: 'daemon' },
+    })
+  }
+
+  try {
+    switch (sub) {
+      case 'install':
+        return await daemonInstall({ port, force: rest.includes('--force') })
+      case 'uninstall':
+        return await daemonUninstall()
+      case 'status':
+        return await daemonStatus()
+      case 'restart':
+        return await daemonRestart()
+      case 'start':
+        return await daemonStart()
+      case 'stop':
+        return await daemonStop()
+      case 'logs':
+        return await daemonLogs(rest)
+      default:
+        console.error(`  unknown daemon subcommand: ${sub}`)
+        printHelp()
+        process.exit(1)
+    }
+  } finally {
+    await flushCliTelemetry()
+  }
+}
+
+function printHelp() {
+  printCommandHelp('daemon')
+}
+
+// --- resolve sootsim binary ----------------------------------------------
+
+interface SootsimInvocation {
+  /** absolute path to the executable launchd / systemd should spawn directly. */
+  executable: string
+  /** args to pass before `serve --quiet --port <port>`. */
+  prefixArgs: string[]
+}
+
+function resolveSootsimInvocation(): SootsimInvocation {
+  // launchd / systemd run agents with a stripped PATH (basically just
+  // /usr/bin:/bin:/usr/sbin:/sbin), so a `#!/usr/bin/env node` shebang
+  // resolves nothing and the daemon never starts. spawn the absolute node
+  // binary directly with the sootsim entry script as an argument.
+  //
+  // process.execPath is whichever node ran the install command, which is
+  // also the node the user expects sootsim to run on.
+  const npxInvocation = resolveNpxDaemonInvocation()
+  if (npxInvocation) return npxInvocation
+  const entry = resolveSootsimEntryScript()
+  return { executable: process.execPath, prefixArgs: [entry] }
+}
+
+function resolveNpxDaemonInvocation(): SootsimInvocation | null {
+  if (!isNpxSootsimInvocation()) return null
+
+  const npmCli = resolveNpmCliPath()
+  if (!npmCli) return null
+
+  const version = getCliVersion()
+  const packageSpec =
+    version === '0.0.0'
+      ? rnxPublicBrand.packageName
+      : `${rnxPublicBrand.packageName}@${version}`
+  return {
+    executable: process.execPath,
+    prefixArgs: [
+      npmCli,
+      'exec',
+      '--yes',
+      '--package',
+      packageSpec,
+      '--',
+      rnxPublicBrand.commandName,
+    ],
+  }
+}
+
+function isNpxSootsimInvocation(): boolean {
+  const argv1 = process.argv[1]
+  if (process.env.npm_command === 'exec') return true
+  if (!argv1) return false
+  const real = realPathOrSelf(argv1)
+  return real.includes(`${sep}_npx${sep}`)
+}
+
+function resolveNpmCliPath(): string | null {
+  try {
+    const out = execFileSync('which', ['npm'], { encoding: 'utf8' }).trim()
+    if (out && existsSync(out)) return realNpmCliPath(out)
+  } catch {}
+
+  const envPath = process.env.npm_execpath
+  if (envPath && existsSync(envPath)) return realNpmCliPath(envPath)
+  return null
+}
+
+function realNpmCliPath(path: string): string {
+  const real = realPathOrSelf(path)
+  if (basename(real) === 'npx-cli.js') {
+    const npmCli = resolve(dirname(real), 'npm-cli.js')
+    if (existsSync(npmCli)) return npmCli
+  }
+  return real
+}
+
+function resolveSootsimEntryScript(): string {
+  // prefer which(1) → handles the user's $PATH (npm/bun/pnpm global bin dirs).
+  // fall back to process.argv[1] for dev checkouts. resolve any symlink so
+  // launchd / systemd spawn the real script, not a /node_modules/.bin shim
+  // that may itself depend on PATH.
+  try {
+    const out = execFileSync('which', [rnxPublicBrand.commandName], {
+      encoding: 'utf8',
+    }).trim()
+    if (out && existsSync(out)) return realPathOrSelf(out)
+  } catch {}
+  const argv1 = process.argv[1]
+  if (argv1 && existsSync(argv1)) return realPathOrSelf(argv1)
+  throw new Error(`could not locate the ${rnxPublicBrand.commandName} binary`)
+}
+
+function realPathOrSelf(p: string): string {
+  try {
+    return realpathSync(p)
+  } catch {
+    return p
+  }
+}
+
+// --- plist / unit generation ---------------------------------------------
+
+function renderPlist(invocation: SootsimInvocation, port: number): string {
+  mkdirSync(LOG_DIR, { recursive: true })
+  const stdout = resolve(LOG_DIR, 'bridge.out.log')
+  const stderr = resolve(LOG_DIR, 'bridge.err.log')
+  // launchd points at the .app launcher (which exec's the real invocation
+  // in place) rather than at bun/node directly, so Login Items reads the
+  // bundle's CFBundleDisplayName instead of bun's signer identity.
+  const { launcherPath } = ensureDaemonApp(invocation, port, { stdout, stderr })
+  const programArgs = `    <string>${escapeXml(launcherPath)}</string>`
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key><string>${SERVICE_LABEL_MAC}</string>
+  <key>ProgramArguments</key>
+  <array>
+${programArgs}
+  </array>
+  <key>RunAtLoad</key><true/>
+  <key>KeepAlive</key><true/>
+  <key>ThrottleInterval</key><integer>${RESPAWN_THROTTLE_SECONDS}</integer>
+  <key>ProcessType</key><string>Background</string>
+  <key>StandardOutPath</key><string>${stdout}</string>
+  <key>StandardErrorPath</key><string>${stderr}</string>
+</dict>
+</plist>
+`
+}
+
+function renderSystemdUnit(invocation: SootsimInvocation, port: number): string {
+  mkdirSync(LOG_DIR_LINUX, { recursive: true })
+  const exec = [invocation.executable, ...invocation.prefixArgs].map(shellQuote).join(' ')
+  return `[Unit]
+Description=rnx bridge daemon
+After=default.target
+
+[Service]
+Type=simple
+ExecStart=${exec} serve --quiet --port ${port}
+Restart=always
+RestartSec=${RESPAWN_THROTTLE_SECONDS}
+
+[Install]
+WantedBy=default.target
+`
+}
+
+function escapeXml(value: string): string {
+  return value
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&apos;')
+}
+
+function shellQuote(value: string): string {
+  return /[^\w@%+=:,./-]/.test(value) ? `'${value.replace(/'/g, `'\\''`)}'` : value
+}
+
+// --- platform paths ------------------------------------------------------
+
+function macPlistPath(): string {
+  return resolve(homedir(), 'Library/LaunchAgents', `${SERVICE_LABEL_MAC}.plist`)
+}
+
+function macLegacyPlistPath(userHome = homedir()): string {
+  return resolve(userHome, 'Library/LaunchAgents', `${LEGACY_SERVICE_LABEL_MAC}.plist`)
+}
+
+function linuxUnitPath(): string {
+  return resolve(homedir(), '.config/systemd/user', `${SERVICE_NAME_LINUX}.service`)
+}
+
+// --- subcommands ---------------------------------------------------------
+
+export interface DaemonServiceStatus {
+  supported: boolean
+  installed: boolean
+  path?: string
+}
+
+export function getDaemonServiceStatus(): DaemonServiceStatus {
+  if (shouldSkipPersistentDaemon()) return { supported: false, installed: false }
+  if (process.platform === 'darwin') {
+    const path = macPlistPath()
+    return { supported: true, installed: existsSync(path), path }
+  }
+  if (process.platform === 'linux') {
+    const path = linuxUnitPath()
+    return { supported: true, installed: existsSync(path), path }
+  }
+  return { supported: false, installed: false }
+}
+
+export async function daemonInstall({ port, force }: { port: number; force: boolean }) {
+  if (shouldSkipPersistentDaemon()) {
+    throw new Error('background daemon setup is unavailable in this environment')
+  }
+
+  const invocation = resolveSootsimInvocation()
+  console.log(`  binary: ${[invocation.executable, ...invocation.prefixArgs].join(' ')}`)
+  console.log(`  port:   ${port}`)
+
+  if (process.platform === 'darwin') {
+    const legacy = teardownLegacyMacDaemonArtifacts()
+    if (!legacy.missing) {
+      console.log(`  removed legacy ${LEGACY_SERVICE_LABEL_MAC} service`)
+    }
+    const path = macPlistPath()
+    if (existsSync(path) && !force) {
+      console.log(`  already installed at ${path}`)
+      console.log(`  pass --force to overwrite, or use 'rnxsim daemon restart' to reload`)
+      return
+    }
+    mkdirSync(dirname(path), { recursive: true })
+    writeFileSync(path, renderPlist(invocation, port))
+    console.log(`  wrote ${path}`)
+
+    // bootstrap into the gui session. launchctl is famous for returning exit
+    // 0 from `bootstrap` while leaving the service unregistered (a stale
+    // bootout reference, an in-flight unload, etc.) — kickstart then fails
+    // with a confusing "service not found" 113. so: bootstrap, immediately
+    // verify with `launchctl print`, and if the verify fails do a clean
+    // bootout-then-bootstrap retry before giving up. we surface real stderr
+    // text from any of those steps so users see what launchd actually said.
+    const target = `gui/${process.getuid!()}`
+    const serviceTarget = `${target}/${SERVICE_LABEL_MAC}`
+    const tryBootstrap = (): { ok: true } | { ok: false; reason: string } => {
+      const bs = spawnSync('launchctl', ['bootstrap', target, path], {
+        stdio: 'pipe',
+        encoding: 'utf8',
+      })
+      const bsErr = (bs.stderr || bs.stdout || '').trim()
+      if (bs.status !== 0) {
+        return {
+          ok: false,
+          reason: `bootstrap exit ${bs.status}${bsErr ? `: ${bsErr}` : ''}`,
+        }
+      }
+      const verify = spawnSync('launchctl', ['print', serviceTarget], {
+        encoding: 'utf8',
+      })
+      if (verify.status !== 0) {
+        return {
+          ok: false,
+          reason: `bootstrap returned 0 but service not registered (print exit ${verify.status})`,
+        }
+      }
+      return { ok: true }
+    }
+
+    let attempt = tryBootstrap()
+    if (!attempt.ok) {
+      const first = attempt.reason
+      // clean reload — bootout any stale reference then bootstrap again.
+      spawnSync('launchctl', ['bootout', serviceTarget], { stdio: 'ignore' })
+      attempt = tryBootstrap()
+      if (!attempt.ok) {
+        throw new Error(
+          `launchctl bootstrap failed: ${attempt.reason}` +
+            (first !== attempt.reason ? ` (initial: ${first})` : '') +
+            ` — try \`rnxsim daemon uninstall\` then retry, or reboot if launchd state is stuck.`,
+        )
+      }
+    }
+
+    // RunAtLoad=true on the plist means bootstrap already started the
+    // agent. an explicit `launchctl kickstart` is redundant here and on
+    // some machines fails with 113 ("service not found") when the agent
+    // crashes immediately and lands in launchd's throttle state — even
+    // though the service IS registered. instead, poll `launchctl print`
+    // for a few seconds until we see the service is running, then we're
+    // done; if it never reaches running, surface the err log path.
+    const deadline = Date.now() + 4000
+    let lastState: string | undefined
+    let lastPid: string | undefined
+    while (Date.now() < deadline) {
+      const p = spawnSync('launchctl', ['print', serviceTarget], { encoding: 'utf8' })
+      if (p.status === 0) {
+        lastState = p.stdout?.match(/state\s*=\s*(\w+)/)?.[1]
+        lastPid = p.stdout?.match(/pid\s*=\s*(\d+)/)?.[1]
+        if (lastState === 'running' || lastPid) break
+      }
+      await new Promise((r) => setTimeout(r, 150))
+    }
+    if (lastState !== 'running' && !lastPid) {
+      throw new Error(
+        `daemon registered but did not reach running state within 4s ` +
+          `(last state: ${lastState || 'unknown'}). check ${resolve(LOG_DIR, 'bridge.err.log')} ` +
+          `— typically a stale runtime or a port already bound by another process.`,
+      )
+    }
+    console.log(
+      `  registered (state: ${lastState || 'unknown'}${lastPid ? `, pid ${lastPid}` : ''}, log: ${resolve(LOG_DIR, 'bridge.err.log')})`,
+    )
+    return
+  }
+
+  if (process.platform === 'linux') {
+    const path = linuxUnitPath()
+    if (existsSync(path) && !force) {
+      console.log(`  already installed at ${path}`)
+      console.log(`  pass --force to overwrite, or use 'rnxsim daemon restart' to reload`)
+      return
+    }
+    mkdirSync(dirname(path), { recursive: true })
+    writeFileSync(path, renderSystemdUnit(invocation, port))
+    console.log(`  wrote ${path}`)
+
+    const reload = spawnSync('systemctl', ['--user', 'daemon-reload'], {
+      stdio: 'pipe',
+      encoding: 'utf8',
+    })
+    if (reload.status !== 0) {
+      const msg = (reload.stderr || reload.stdout || '').trim()
+      throw new Error(`systemctl daemon-reload failed${msg ? `: ${msg}` : ''}`)
+    }
+    const enable = spawnSync(
+      'systemctl',
+      ['--user', 'enable', '--now', SERVICE_NAME_LINUX],
+      { stdio: 'pipe', encoding: 'utf8' },
+    )
+    if (enable.status !== 0) {
+      const msg = (enable.stderr || enable.stdout || '').trim()
+      throw new Error(
+        `systemctl enable --now failed${msg ? `: ${msg}` : ''}` +
+          ` — try \`rnxsim daemon uninstall\` then retry.`,
+      )
+    }
+    const isActive = spawnSync('systemctl', ['--user', 'is-active', SERVICE_NAME_LINUX], {
+      encoding: 'utf8',
+    })
+    const state = (isActive.stdout || '').trim() || 'unknown'
+    console.log(
+      `  registered (state: ${state}, journalctl --user -u ${SERVICE_NAME_LINUX} to tail logs)`,
+    )
+
+    // user-scope systemd units are killed when the user's last session ends.
+    // on most distros the daemon then disappears at logout — the unit is
+    // "active" until you log off, then silently dead, and `sootsim` looks
+    // broken when you ssh back in. `loginctl enable-linger` keeps the user
+    // bus alive across sessions, which is what every other long-running
+    // user agent (gpg-agent, ssh-agent --systemd) also relies on.
+    //
+    // orb's default user is already lingered (orb seeds it); multipass and
+    // lima fresh users are not. probing `loginctl show-user --property=Linger`
+    // tells us whether to nudge the user — running enable-linger ourselves
+    // requires root (`loginctl enable-linger` invokes a polkit action that
+    // typically needs sudo from a non-root user), so we just print the
+    // one-liner instead of trying to escalate ourselves.
+    try {
+      const username = process.env.USER || process.env.LOGNAME || ''
+      if (username) {
+        const linger = spawnSync(
+          'loginctl',
+          ['show-user', username, '--property=Linger', '--value'],
+          { encoding: 'utf8' },
+        )
+        const lingerEnabled = (linger.stdout || '').trim().toLowerCase() === 'yes'
+        if (!lingerEnabled && linger.status === 0) {
+          console.log(
+            `  note: linger is not enabled for "${username}". the daemon will exit at logout.\n` +
+              `  enable persistence with: sudo loginctl enable-linger ${username}`,
+          )
+        }
+      }
+    } catch {
+      // loginctl missing or non-systemd init — silent; the daemon still works
+      // for the current session even without lingering.
+    }
+    return
+  }
+
+  console.error(`  background daemon is not supported on ${process.platform}`)
+  console.error(`  run 'rnxsim serve' in a persistent shell instead`)
+  process.exit(1)
+}
+
+// removed-path log (idempotent helpers track what they actually touched so the
+// caller can report a unified "not installed" / "removed N entries" line).
+type TeardownReport = { removed: string[]; missing: boolean }
+
+export function teardownLegacyMacDaemonArtifacts(
+  options: {
+    userHome?: string
+    launchTarget?: string
+    bootout?: (target: string) => void
+  } = {},
+): TeardownReport {
+  const userHome = options.userHome ?? homedir()
+  const plist = macLegacyPlistPath(userHome)
+  const logDir = resolve(userHome, 'Library/Logs/sootsim')
+  const removed: string[] = []
+  if (existsSync(plist)) {
+    const target = `${
+      options.launchTarget ?? `gui/${process.getuid?.() ?? 0}`
+    }/${LEGACY_SERVICE_LABEL_MAC}`
+    const bootout =
+      options.bootout ??
+      ((serviceTarget: string) => {
+        spawnSync('launchctl', ['bootout', serviceTarget], { stdio: 'ignore' })
+      })
+    bootout(target)
+    rmSync(plist, { force: true })
+    removed.push(plist)
+  }
+  for (const name of ['server.err.log', 'server.out.log']) {
+    const log = resolve(logDir, name)
+    if (!existsSync(log)) continue
+    rmSync(log, { force: true })
+    removed.push(log)
+  }
+  return { removed, missing: removed.length === 0 }
+}
+
+/** stop + disable + remove the persistent launchd / systemd registration
+ *  and its support files (mac .app bundle, log dir). does NOT touch user
+ *  data under ~/.sootsim. idempotent: each entry is checked before remove.
+ *  exported for reuse by the npm preuninstall hook (scripts/preuninstall.cjs)
+ *  via the bundled CLI so a `npm rm -g sootsim` tears down the daemon before
+ *  the bin disappears. */
+export function teardownDaemonService(): TeardownReport {
+  const removed: string[] = []
+  if (process.platform === 'darwin') {
+    const legacy = teardownLegacyMacDaemonArtifacts()
+    removed.push(...legacy.removed)
+    const plist = macPlistPath()
+    if (existsSync(plist)) {
+      spawnSync(
+        'launchctl',
+        ['bootout', `gui/${process.getuid!()}/${SERVICE_LABEL_MAC}`],
+        { stdio: 'ignore' },
+      )
+      rmSync(plist, { force: true })
+      removed.push(plist)
+    }
+    const bundle = daemonAppBundlePath()
+    if (existsSync(bundle)) {
+      rmSync(bundle, { recursive: true, force: true })
+      removed.push(bundle)
+    }
+    if (existsSync(LOG_DIR)) {
+      rmSync(LOG_DIR, { recursive: true, force: true })
+      removed.push(LOG_DIR)
+    }
+    return { removed, missing: removed.length === 0 }
+  }
+  if (process.platform === 'linux') {
+    const unit = linuxUnitPath()
+    if (existsSync(unit)) {
+      // `disable --now` stops + disables in one call. ignore exit status: a
+      // unit pointing at a now-stale ExecStart (the npm preuninstall path)
+      // can return non-zero while still successfully disabling the unit.
+      spawnSync('systemctl', ['--user', 'disable', '--now', SERVICE_NAME_LINUX], {
+        stdio: 'ignore',
+      })
+      rmSync(unit, { force: true })
+      spawnSync('systemctl', ['--user', 'daemon-reload'], { stdio: 'ignore' })
+      // reset-failed clears the "failed" state that lingers in systemd when
+      // the unit exited with a missing ExecStart, otherwise `systemctl --user
+      // status sootsim-daemon` keeps showing failed even after the unit file
+      // is gone.
+      spawnSync('systemctl', ['--user', 'reset-failed', SERVICE_NAME_LINUX], {
+        stdio: 'ignore',
+      })
+      removed.push(unit)
+    }
+    if (existsSync(LOG_DIR_LINUX)) {
+      rmSync(LOG_DIR_LINUX, { recursive: true, force: true })
+      removed.push(LOG_DIR_LINUX)
+    }
+    return { removed, missing: removed.length === 0 }
+  }
+  // win + others: no persistent daemon mechanism yet; nothing to tear down.
+  return { removed, missing: true }
+}
+
+/** remove the user-data cache under ~/.sootsim (runtimes, electron support,
+ *  profiles, lockfile, config). idempotent. honors $SOOTSIM_HOME. exported
+ *  for reuse by the npm preuninstall hook. */
+export function teardownSootsimHome(): TeardownReport {
+  const removed: string[] = []
+  const home = sootsimHomeDir()
+  if (existsSync(home)) {
+    rmSync(home, { recursive: true, force: true })
+    removed.push(home)
+  }
+  return { removed, missing: removed.length === 0 }
+}
+
+async function daemonUninstall() {
+  const service = teardownDaemonService()
+  for (const path of service.removed) console.log(`  removed ${path}`)
+  const home = teardownSootsimHome()
+  for (const path of home.removed) console.log(`  removed ${path}`)
+  if (service.missing && home.missing) console.log('  not installed')
+}
+
+// the service manager's own word is not proof the bridge works: a daemon that
+// crashes on start reads as `active` all through systemd's restart backoff,
+// which is how a fully broken daemon reported healthy on the 2026-08-19 drive.
+// the lockfile carries a pid and a heartbeat, so it answers the question the
+// caller actually asked.
+function printBridgeLiveness() {
+  const lock = readDaemonLockfile()
+  if (isDaemonLockfileFresh(lock)) {
+    console.log(`  bridge:    responding on port ${lock.bridgePort} (pid ${lock.pid})`)
+    return
+  }
+  console.log(
+    lock
+      ? '  bridge:    NOT responding — stale lockfile; check `rnxsim daemon logs`'
+      : '  bridge:    NOT responding — no lockfile; check `rnxsim daemon logs`',
+  )
+}
+
+async function daemonStatus() {
+  if (process.platform === 'darwin') {
+    const path = macPlistPath()
+    if (!existsSync(path)) {
+      console.log(`  installed: no`)
+      return
+    }
+    console.log(`  installed: yes  (${path})`)
+    const binary = readPlistBinary(path)
+    if (binary) console.log(`  binary:    ${binary}`)
+    const res = spawnSync(
+      'launchctl',
+      ['print', `gui/${process.getuid!()}/${SERVICE_LABEL_MAC}`],
+      { encoding: 'utf8' },
+    )
+    if (res.status === 0) {
+      const state = res.stdout.match(/state\s*=\s*(\w+)/)?.[1]
+      const pid = res.stdout.match(/pid\s*=\s*(\d+)/)?.[1]
+      console.log(`  state:     ${state || 'unknown'}${pid ? ` (pid ${pid})` : ''}`)
+    } else {
+      console.log('  state:     not running')
+    }
+    printBridgeLiveness()
+    return
+  }
+  if (process.platform === 'linux') {
+    const path = linuxUnitPath()
+    if (!existsSync(path)) {
+      console.log(`  installed: no`)
+      return
+    }
+    console.log(`  installed: yes  (${path})`)
+    const res = spawnSync('systemctl', ['--user', 'is-active', SERVICE_NAME_LINUX], {
+      encoding: 'utf8',
+    })
+    console.log(`  state:     ${res.stdout.trim() || 'unknown'}`)
+    printBridgeLiveness()
+    return
+  }
+  console.error(`  unsupported platform: ${process.platform}`)
+  process.exit(1)
+}
+
+async function daemonRestart() {
+  if (process.platform === 'darwin') {
+    const path = macPlistPath()
+    if (!existsSync(path)) {
+      console.error('  daemon not registered — run `rnxsim setup`')
+      process.exit(1)
+    }
+    const res = spawnSync(
+      'launchctl',
+      ['kickstart', '-k', `gui/${process.getuid!()}/${SERVICE_LABEL_MAC}`],
+      { stdio: 'pipe', encoding: 'utf8' },
+    )
+    if (res.status !== 0) {
+      console.error(`  kickstart failed: ${res.stderr?.trim()}`)
+      process.exit(1)
+    }
+    console.log('  restarted')
+    return
+  }
+  if (process.platform === 'linux') {
+    const path = linuxUnitPath()
+    if (!existsSync(path)) {
+      console.error('  daemon not registered — run `rnxsim setup`')
+      process.exit(1)
+    }
+    const res = spawnSync('systemctl', ['--user', 'restart', SERVICE_NAME_LINUX], {
+      stdio: 'pipe',
+      encoding: 'utf8',
+    })
+    if (res.status !== 0) {
+      console.error(`  restart failed: ${res.stderr?.trim()}`)
+      process.exit(1)
+    }
+    console.log('  restarted')
+    return
+  }
+  console.error(`  unsupported platform: ${process.platform}`)
+  process.exit(1)
+}
+
+async function daemonStart() {
+  if (process.platform === 'darwin') {
+    const path = macPlistPath()
+    if (!existsSync(path)) {
+      console.error('  daemon not registered — run `rnxsim setup`')
+      process.exit(1)
+    }
+    const res = spawnSync(
+      'launchctl',
+      ['kickstart', `gui/${process.getuid!()}/${SERVICE_LABEL_MAC}`],
+      { stdio: 'pipe', encoding: 'utf8' },
+    )
+    if (res.status !== 0) {
+      console.error(`  start failed: ${res.stderr?.trim()}`)
+      process.exit(1)
+    }
+    console.log('  started')
+    return
+  }
+  if (process.platform === 'linux') {
+    const path = linuxUnitPath()
+    if (!existsSync(path)) {
+      console.error('  daemon not registered — run `rnxsim setup`')
+      process.exit(1)
+    }
+    const res = spawnSync('systemctl', ['--user', 'start', SERVICE_NAME_LINUX], {
+      stdio: 'pipe',
+      encoding: 'utf8',
+    })
+    if (res.status !== 0) {
+      console.error(`  start failed: ${res.stderr?.trim()}`)
+      process.exit(1)
+    }
+    console.log('  started')
+    return
+  }
+  console.error(`  unsupported platform: ${process.platform}`)
+  process.exit(1)
+}
+
+async function daemonStop() {
+  if (process.platform === 'darwin') {
+    const path = macPlistPath()
+    if (!existsSync(path)) {
+      console.error('  daemon not registered — nothing to stop')
+      process.exit(1)
+    }
+    const res = spawnSync(
+      'launchctl',
+      ['bootout', `gui/${process.getuid!()}/${SERVICE_LABEL_MAC}`],
+      { stdio: 'pipe', encoding: 'utf8' },
+    )
+    if (res.status !== 0) {
+      console.error(`  stop failed: ${res.stderr?.trim()}`)
+      process.exit(1)
+    }
+    console.log('  stopped')
+    return
+  }
+  if (process.platform === 'linux') {
+    const path = linuxUnitPath()
+    if (!existsSync(path)) {
+      console.error('  daemon not registered — nothing to stop')
+      process.exit(1)
+    }
+    const res = spawnSync('systemctl', ['--user', 'stop', SERVICE_NAME_LINUX], {
+      stdio: 'pipe',
+      encoding: 'utf8',
+    })
+    if (res.status !== 0) {
+      console.error(`  stop failed: ${res.stderr?.trim()}`)
+      process.exit(1)
+    }
+    console.log('  stopped')
+    return
+  }
+  console.error(`  unsupported platform: ${process.platform}`)
+  process.exit(1)
+}
+
+// tail the daemon's logs. macOS reads the launchd-redirected files directly
+// (works for any user); linux reads the systemd journal. journalctl --user
+// fails for a freshly-created user not yet in the systemd-journal/adm group
+// ("No journal files were opened due to insufficient permissions"), so on that
+// error we retry the system-scoped query and, failing that, point the user at
+// the sudo form rather than printing a cryptic permission error.
+async function daemonLogs(rest: string[]) {
+  const linesArg = rest.find((a) => /^-n\d+$|^--lines=\d+$|^\d+$/.test(a))
+  const lines = linesArg ? Number(linesArg.replace(/\D/g, '')) : 200
+  const follow = rest.includes('-f') || rest.includes('--follow')
+
+  if (process.platform === 'darwin') {
+    const out = resolve(LOG_DIR, 'bridge.out.log')
+    const err = resolve(LOG_DIR, 'bridge.err.log')
+    const present = [out, err].filter((p) => existsSync(p))
+    if (present.length === 0) {
+      console.error(
+        `  no daemon logs yet at ${LOG_DIR} — run \`rnxsim setup\` to install the daemon`,
+      )
+      process.exit(1)
+    }
+    const args = follow
+      ? ['-n', String(lines), '-F', ...present]
+      : ['-n', String(lines), ...present]
+    spawnSync('tail', args, { stdio: 'inherit' })
+    return
+  }
+
+  if (process.platform === 'linux') {
+    const unit = `${SERVICE_NAME_LINUX}.service`
+    const base = ['--user', '-u', unit, '-n', String(lines), '--no-pager']
+    const res = spawnSync('journalctl', follow ? [...base, '-f'] : base, {
+      encoding: 'utf8',
+      stdio: follow ? 'inherit' : 'pipe',
+    })
+    if (follow) return
+    const combined = `${res.stdout || ''}${res.stderr || ''}`
+    const blocked = /insufficient permissions|No journal files were opened/i.test(
+      combined,
+    )
+    if (res.status === 0 && !blocked) {
+      process.stdout.write(res.stdout || '')
+      return
+    }
+    // fresh-user fallback: the system journal holds the user-unit logs even when
+    // the user can't read --user scope. try it, then fall back to guidance.
+    const sys = spawnSync(
+      'journalctl',
+      [`_SYSTEMD_USER_UNIT=${unit}`, '-n', String(lines), '--no-pager'],
+      { encoding: 'utf8' },
+    )
+    if (sys.status === 0 && (sys.stdout || '').trim()) {
+      process.stdout.write(sys.stdout)
+      return
+    }
+    console.error(
+      `  could not read --user journal for ${unit} (this user isn't in the systemd-journal group yet).\n` +
+        `  run:  sudo journalctl _SYSTEMD_USER_UNIT=${unit} -n ${lines} --no-pager`,
+    )
+    process.exit(1)
+  }
+
+  console.error(`  unsupported platform: ${process.platform}`)
+  process.exit(1)
+}
+
+function readPlistBinary(path: string): string | null {
+  try {
+    const body = readFileSync(path, 'utf8')
+    const match = body.match(/<array>\s*<string>([^<]+)<\/string>/)
+    return match?.[1] || null
+  } catch {
+    return null
+  }
+}