centralu 0.1.0-beta.4 → 0.1.0-beta.41

package/bin/serve-detach.mjs

@@ -0,0 +1,289 @@
+/**
+ * `centralu serve --detach` and `--stop`: starting serve outside the ssh session that asked, and
+ * stopping it in order (docs/plans/remote-hub.md §10.4).
+ */
+import { spawn } from 'node:child_process'
+import { existsSync, openSync, rmSync, writeFileSync, writeSync } from 'node:fs'
+import { userInfo } from 'node:os'
+import { join } from 'node:path'
+import { answerLine, isAlive, say, sayTo, runCaptured, tail, sleep } from './serve-util.mjs'
+import { SERVE_LOG_FILE, serveDataDir, ensureServeState, markStopped, rotateServeLog } from './serve-files.mjs'
+import { askPowershell, detachHow, windowsArg, wmiScript, parseWmiAnswer, wmiBlockedMessage, windowsPowershell, windowsTool, wslDistro, wslUser } from './serve-windows.mjs'
+import { CHILD_FLAG } from './serve-args.mjs'
+import { startInSignIn } from './serve-autostart.mjs'
+import { stopServedHost } from './serve-handover.mjs'
+import { connectionLine, serveFrom } from './serve-host.mjs'
+import { describe, runServe, serveFolder } from './serve-run.mjs'
+
+/**
+ * What a detached launcher needs from the `--detach` that started it. A process created through WMI
+ * does not inherit this environment: it gets the account's default one. Everything else it needs
+ * (the token, the port) is in the data folder. Never a secret.
+ */
+export const CARRIED_ENV = ['CC_DATA_DIR', 'CENTRALU_HOST_ENTRY', 'CENTRALU_MANAGED', 'CENTRALU_STARTED_FROM']
+
+/**
+ * `start` is how the launcher was started and why (`through WMI: <reason>`), which it writes into its first serve.log
+ * line, so a host that ended up outside the Windows sign-in says why (#1223)
+ */
+export function encodeChildSpec({ env, log, start = null }) {
+  const carried = {}
+  for (const k of CARRIED_ENV) if (typeof env[k] === 'string' && env[k]) carried[k] = env[k]
+  return Buffer.from(JSON.stringify({ log, env: carried, ...(start ? { start } : {}) }), 'utf8').toString('base64url')
+}
+
+/** `{ log, env, start? }` from `--detached-child=`, only the carried variables; null when it is not one */
+export function decodeChildSpec(raw) {
+  try {
+    const v = JSON.parse(Buffer.from(String(raw), 'base64url').toString('utf8'))
+    if (typeof v?.log !== 'string' || !v.log) return null
+    const env = {}
+    for (const k of CARRIED_ENV) if (typeof v.env?.[k] === 'string') env[k] = v.env[k]
+    return { log: v.log, env, ...(typeof v.start === 'string' && v.start ? { start: v.start } : {}) }
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Starts the launcher outside this session (`detachHow`). `{ ok: true, pid, exited?, alive? }` once
+ * something was created, `{ ok: false, blocked, message }` when nothing was: `blocked` is the WMI
+ * refusal the hub falls back from.
+ */
+export async function startDetached({ how, execPath, args, env, cwd }) {
+  if (how === 'setsid') {
+    return await new Promise((resolve) => {
+      let child
+      try {
+        child = spawn(execPath, args, { detached: true, stdio: 'ignore', cwd, env, windowsHide: true })
+      } catch (e) {
+        return resolve({ ok: false, blocked: false, message: `could not start ${execPath}: ${e.message}` })
+      }
+      child.once('error', (e) => resolve({ ok: false, blocked: false, message: `could not start ${execPath}: ${e.message}` }))
+      child.once('spawn', () => {
+        const exited = new Promise((r) => child.once('exit', (code, signal) => r(signal ?? code)))
+        child.unref()
+        resolve({ ok: true, pid: child.pid, exited })
+      })
+    })
+  }
+  const ps = windowsPowershell(how, env)
+  if (!ps) return { ok: false, blocked: true, message: wmiBlockedMessage('Windows PowerShell is not reachable from this WSL distro') }
+  let commandLine
+  try {
+    if (how === 'wmi') commandLine = [execPath, ...args].map(windowsArg).join(' ')
+    else {
+      const distro = wslDistro(env.WSL_DISTRO_NAME ?? '')
+      const user = wslUser(userInfo().username)
+      commandLine = ['wsl.exe', '-d', distro, '-u', user, '--cd', cwd, '--exec', execPath, ...args].map(windowsArg).join(' ')
+    }
+  } catch (e) {
+    return { ok: false, blocked: false, message: e.message }
+  }
+  const script = wmiScript({ commandLine, cwd: how === 'wmi' ? cwd : null })
+  const answer = await askPowershell(ps, script, env, parseWmiAnswer)
+  if (!answer.ok) return { ok: false, blocked: true, message: wmiBlockedMessage(answer.message) }
+  // A Windows pid can be watched from Windows; from inside WSL it names nothing here
+  /*
+   * Measured on a Windows 11 laptop (2026-10-08): a `wsl.exe` that WMI creates can hang without
+   * running anything in the distro (it starts a second wsl.exe and waits), while `wsl.exe --list`
+   * from the same context answers. `--detach` reports that as a start that never ran, and ends what
+   * it created rather than leave it waiting: this pid and its children, nothing else.
+   */
+  const taskkill = windowsTool(how, env, ['System32', 'taskkill.exe'])
+  const stop = taskkill ? () => runCaptured(taskkill, ['/PID', String(answer.pid), '/T', '/F'], env) : null
+  return { ok: true, pid: answer.pid, alive: how === 'wmi' ? () => isAlive(answer.pid) : null, stop }
+}
+
+/**
+ * `centralu serve --detach` (docs/plans/remote-hub.md §10.4, S9): starts `serve` outside this
+ * session (`detachHow`) and returns once its host answers a hello, so the caller, typically the
+ * hub over ssh, can connect at once.
+ *
+ * stdout carries one JSON line, read by the hub (`links/tunnel.ts`): the connection line with
+ * `hostRunning: true` and `detach: { ok: true, how, already }`, or `{ v: 1, detach: { ok: false,
+ * how, reason, message } }`. `reason` is `wmi_blocked` when WMI created nothing or created something
+ * that never ran, which the hub answers with a link-bound start; `exited` and `timeout` quote the
+ * end of serve.log. Exit codes do not survive Windows' ssh (agent-host.md §4.8), so the line is
+ * what counts; the exit code is 0 or 1 for a person at a prompt.
+ *
+ * `start` and the two waits are parameters so tests can stand in for WMI.
+ */
+export async function runDetach({
+  env,
+  home,
+  entry,
+  version,
+  cliPath,
+  port = null,
+  from = null,
+  platform = process.platform,
+  execPath = process.execPath,
+  cwd = process.cwd(),
+  start = startDetached,
+  how = detachHow(platform, env),
+  signIn = startInSignIn,
+  signInMs = 20_000,
+  timeoutMs = 30_000,
+  noStartMs = 10_000,
+  write = (line) => process.stdout.write(line),
+}) {
+  // Created here, so the token exists before the launcher reads it and `answered` reads it again
+  const { dataDir } = serveFolder({ env, home, cliPath, platform })
+  const fail = (reason, message) => answerLine(write, 'detach', { ok: false, how, reason, message })
+  const answered = async (already, as = how) => {
+    const d = await describe({ env, dataDir, state: ensureServeState(dataDir, platform), entry, version })
+    if (!d?.hostRunning) return false
+    write(`${connectionLine({ ...d, detach: { ok: true, how: as, already } })}\n`)
+    return true
+  }
+  if (await answered(true)) return 0
+
+  const log = join(dataDir, SERVE_LOG_FILE)
+  /*
+   * One start per log: the earlier ones are kept beside it, three of them (`rotateServeLog`, #1143), and its absence is
+   * how a start that never ran shows. So a log that cannot be moved aside is removed rather than left to read as a start
+   */
+  const freshLog = () => rotateServeLog(log)
+
+  /*
+   * Windows: in the person's sign-in when someone is signed in (#1224), through the scheduled task, and through WMI only
+   * when nobody is. WMI's process keeps this ssh session's network logon, where Git cannot use the credentials saved in
+   * Windows. A task-started host that does not answer in time is left to the lock: the WMI start below then either
+   * holds the folder or is refused by it, never a second host on it. Which way it went, and why, is one line of
+   * serve.log (#1223): the task's serve writes no serve.log, so that line is written here; a WMI launcher writes its own
+   */
+  let notInSignIn = null
+  if (how === 'wmi') {
+    const s = await signIn({ dataDir, env, home, platform })
+    if (s.started) {
+      const line = `started centralu serve in the Windows sign-in (the scheduled task "${s.name}"); waiting for its host`
+      say(line)
+      freshLog()
+      try {
+        writeFileSync(log, `[centralu serve] ${line}\n`)
+      } catch {
+        // the line on stderr is all there is
+      }
+      const t0 = Date.now()
+      while (Date.now() - t0 < signInMs) {
+        if (await answered(false, 'task')) return 0
+        await sleep(250)
+      }
+      notInSignIn = `the host the sign-in task "${s.name}" started did not answer within ${Math.round(signInMs / 1000)} s`
+      // The WMI launcher's first line says so; the task's line goes, so `serve.log.1` keeps the start before this one
+      rmSync(log, { force: true, maxRetries: 5 })
+    } else {
+      notInSignIn = signInMissed(s)
+    }
+    say(`${notInSignIn}: starting the host through WMI${s.reason === 'nosession' ? ', outside any sign-in, where Git cannot use the credentials saved in Windows' : ''}`)
+  }
+
+  freshLog()
+  // Where this was asked for from (#1223): the launcher runs outside this ssh session, so it is told
+  const asked = serveFrom(env, from)
+  const childEnv = asked ? { ...env, CENTRALU_STARTED_FROM: JSON.stringify(asked) } : env
+  const startedHow = `through ${how === 'wmi' ? 'WMI' : how === 'wsl' ? 'a WMI-created wsl.exe' : how}${notInSignIn ? `: ${notInSignIn}` : ''}`
+  const args = [cliPath, 'serve', ...(port !== null ? ['--port', String(port)] : []), `${CHILD_FLAG}${encodeChildSpec({ env: childEnv, log, start: startedHow })}`]
+  let started
+  try {
+    started = await start({ how, execPath, args, env, cwd })
+  } catch (e) {
+    return fail('failed', `could not start centralu serve in the background: ${e.message}`)
+  }
+  if (!started.ok) return fail(started.blocked ? 'wmi_blocked' : 'failed', started.message)
+  say(`started centralu serve in the background (${how}, pid ${started.pid ?? 'unknown'}); waiting for its host`)
+
+  let exited
+  started.exited?.then((c) => (exited = c ?? 'unknown'))
+  const t0 = Date.now()
+  while (Date.now() - t0 < timeoutMs) {
+    if (await answered(false)) return 0
+    const why = tail(log)
+    if (exited !== undefined) return fail('exited', `centralu serve exited (${exited}) before its host answered${why ? `:\n${why}` : ''}`)
+    const gone = started.alive?.() === false
+    if (how !== 'setsid' && !existsSync(log) && (gone || Date.now() - t0 > noStartMs)) {
+      // WMI said yes, and nothing ran: the process was stopped before Node started, or hangs (`startDetached`)
+      if (!gone) await started.stop?.()
+      return fail('wmi_blocked', wmiBlockedMessage(gone ? `process ${started.pid} ended before it started` : `nothing started within ${Math.round(noStartMs / 1000)} s`))
+    }
+    if (gone) return fail('exited', `centralu serve exited before its host answered${why ? `:\n${why}` : ''}`)
+    await sleep(250)
+  }
+  const why = tail(log)
+  return fail('timeout', `the host did not answer within ${Math.round(timeoutMs / 1000)} s${why ? `:\n${why}` : ''}`)
+}
+
+/** Why the host was not started in the Windows sign-in, from `startInSignIn`'s answer, for serve.log and stderr */
+export function signInMissed(s) {
+  if (s.reason === 'nosession') {
+    const n = s.desktops
+    const unread = s.unreadable ? `, ${s.unreadable} of them with an owner WMI would not tell` : ''
+    const seen =
+      typeof n !== 'number'
+        ? 'no Explorer of this account in a desktop session'
+        : n === 0
+          ? 'no Explorer in any desktop session'
+          : `none of the ${n} Explorer${n === 1 ? '' : 's'} in desktop sessions is this account's${unread}`
+    return `no Windows sign-in of this user was found (${seen})`
+  }
+  // It travels on the launcher's command line: bounded
+  if (s.reason === 'error') return `the sign-in task failed: ${String(s.message).slice(0, 300)}`
+  if (s.reason === 'off') return 'the sign-in task is turned off (CENTRALU_SIGNIN_TASK=off)'
+  if (s.reason === 'no_launcher') return 'there is no launcher in the data folder for the sign-in task to run'
+  return `the sign-in task was not used (${s.reason})`
+}
+
+/**
+ * The launcher `--detach` started: `runServe` writing to serve.log. The carried variables are
+ * already in `env` (centralu.mjs merges them before it looks for the host).
+ */
+export async function runDetachedChild({ spec, ...opts }) {
+  let fd = null
+  try {
+    fd = openSync(spec.log, 'a')
+    sayTo((text) => {
+      try {
+        writeSync(fd, text)
+      } catch {
+        // nowhere left to say it
+      }
+    })
+  } catch {
+    // no log: say() keeps stderr, which nobody reads; --detach then reports the start as never run
+  }
+  // One line saying how it was started and why (#1223), and what runs
+  say(`started in the background${spec.start ? ` ${spec.start}` : ''} (pid ${process.pid}, Node ${process.version})`)
+  try {
+    return await runServe({ ...opts, logFd: fd })
+  } catch (e) {
+    say(e?.message ?? String(e))
+    return 1
+  }
+}
+
+/**
+ * `centralu serve --stop` (docs/plans/remote-hub.md §10.4, S10): the running host stopped in order, over its own
+ * socket, and waited for (`stopServedHost` in serve-handover.mjs, which the hand-over into the sign-in shares, #1224).
+ *
+ * stdout: one line, `{ v: 1, stop: { ok, wasRunning, how?, message? } }`.
+ *
+ * A stop that went through is remembered in the data folder (`markStopped`, #1143), so a linked hub does not start the
+ * host again by itself; the next host that starts here removes the mark. Not for a hub's own stop, which starts the
+ * host again itself (an update, a rollback): the hub runs it with `CENTRALU_STOP_BY=hub` (links/tunnel.ts `stopCommand`)
+ */
+export async function runStop({
+  env,
+  home,
+  entry,
+  platform = process.platform,
+  timeoutMs = 30_000,
+  graceMs = 15_000,
+  kill = (pid, sig) => process.kill(pid, sig),
+  write = (line) => process.stdout.write(line),
+}) {
+  const dataDir = serveDataDir(env, home)
+  const stopped = await stopServedHost({ dataDir, entry, platform, timeoutMs, graceMs, kill })
+  if (stopped.ok && env.CENTRALU_STOP_BY !== 'hub') markStopped(dataDir, 'stop')
+  return answerLine(write, 'stop', stopped)
+}

package/bin/serve-files.mjs

@@ -0,0 +1,299 @@
+/**
+ * The files `centralu serve` keeps in the data folder: the token and port (serve.json, private to the
+ * user), the running launcher's pid (serve.pid), and the host's own lock (host.lock), read to tell a
+ * live host of this folder from a stale pid.
+ */
+import { execFileSync } from 'node:child_process'
+import { randomBytes } from 'node:crypto'
+import { chmodSync, existsSync, mkdirSync, openSync, readFileSync, renameSync, rmSync, statSync, writeSync, closeSync } from 'node:fs'
+import { join } from 'node:path'
+import { isAlive, renameRetrying, replaceFile, sleepSync } from './serve-util.mjs'
+
+/**
+ * The file in the data folder that holds the token and the port, mode 0600.
+ *
+ * The token is generated once, the first time either `serve` or `serve --connection` runs, and kept:
+ * the client stores it (in the OS secret store) and has to find the same one after the host
+ * restarts. The port is the one the last `serve` actually listened on, which is how
+ * `--connection`, a separate process, learns a `--port` given to `serve` in a systemd unit.
+ */
+export const SERVE_STATE_FILE = 'serve.json'
+
+/** What a detached serve writes: its own lines, and the host's until it is ready (host.log has the rest) */
+export const SERVE_LOG_FILE = 'serve.log'
+
+/** The running launcher's pid and port, so `--stop` can find it. Removed when it exits */
+export const SERVE_PID_FILE = 'serve.pid'
+
+/** How many earlier starts' serve.log are kept, as serve.log.1 (the last) to serve.log.3 */
+export const SERVE_LOGS_KEPT = 3
+
+/**
+ * Makes room for a new start's serve.log (#1143): the earlier ones move down a place, and the oldest past
+ * `SERVE_LOGS_KEPT` goes. A hub that starts a host again after it stopped makes at most three starts in ten minutes,
+ * so the log of the start that failed first is still here when it stops trying. The last one is moved aside with
+ * `renameRetrying` (a reader may hold the file on Windows, #1223); one that cannot be moved is removed rather than
+ * left to read as the new start's. Never fatal
+ */
+export function rotateServeLog(log, kept = SERVE_LOGS_KEPT, rename = renameRetrying) {
+  // No log to move aside, no room to make: a second call for the same start (the task's line removed before a WMI start)
+  if (!existsSync(log)) return
+  for (let i = kept - 1; i >= 1; i--) {
+    try {
+      renameSync(`${log}.${i}`, `${log}.${i + 1}`)
+    } catch {
+      // there was none, or a reader holds it: the older log stays where it is
+    }
+  }
+  try {
+    rename(log, `${log}.1`)
+  } catch (e) {
+    if (e?.code === 'ENOENT') return
+    try {
+      rmSync(log, { force: true, maxRetries: 5 })
+    } catch {
+      // nothing more to do
+    }
+  }
+}
+
+/**
+ * The person's stop, kept in the data folder (#1143): `centralu serve --stop` writes it (`by: 'stop'`), and so does a
+ * host that Centralu's own app stops for good when the person quits it there (`by: 'quit'`, the host's
+ * lifecycle/stopped-mark.ts, which names the same file). Every host that starts in the folder removes it.
+ * `--connection` reports it while no host runs, and a hub then starts none by itself. A hub's own stop (an update)
+ * leaves none: it says so with `CENTRALU_STOP_BY=hub`
+ */
+export const SERVE_STOPPED_FILE = 'stopped.json'
+
+/** Writes the mark; never fatal, a stop that could not note itself still stopped */
+export function markStopped(dataDir, by, now = Date.now()) {
+  try {
+    replaceFile(join(dataDir, SERVE_STOPPED_FILE), `${JSON.stringify({ v: 1, by, at: now })}\n`)
+  } catch {
+    // the folder is read-only or gone: nothing to remember it in
+  }
+}
+
+/** The mark as `{ by, at }`, or null when there is none. One that does not parse is still a stop, by `stop`, at no time */
+export function readStopped(dataDir) {
+  let text
+  try {
+    text = readFileSync(join(dataDir, SERVE_STOPPED_FILE), 'utf8')
+  } catch {
+    return null
+  }
+  let o = null
+  try {
+    o = JSON.parse(text)
+  } catch {
+    // half written, or written by hand
+  }
+  return { by: o?.by === 'quit' ? 'quit' : 'stop', at: typeof o?.at === 'number' && Number.isFinite(o.at) ? o.at : null }
+}
+
+/** The data folder: the host's own rule (`dataRoot()` in agent-host), CC_DATA_DIR or ~/.centralu */
+export function serveDataDir(env, home) {
+  return env.CC_DATA_DIR || join(home, '.centralu')
+}
+
+/**
+ * The state, or null when there is none yet or it cannot be read as one. A file that is refused (Windows, while a
+ * writer or a scanner has it) or does not parse is read again a few times before it counts as unreadable: a
+ * `--detach` waiting for the port reads it while the launcher replaces it (#1041).
+ */
+export function readServeState(dataDir, { tries = 5, sleep = sleepSync } = {}) {
+  const file = join(dataDir, SERVE_STATE_FILE)
+  for (let i = 1; ; i++) {
+    let raw
+    try {
+      raw = readFileSync(file, 'utf8')
+    } catch (e) {
+      if (e?.code === 'ENOENT' || i >= tries) return null
+      sleep(10 * i)
+      continue
+    }
+    const state = parseServeState(raw)
+    if (state || i >= tries) return state
+    sleep(10 * i)
+  }
+}
+
+function parseServeState(raw) {
+  try {
+    const v = JSON.parse(raw)
+    if (typeof v?.token !== 'string' || v.token.length < 32) return null
+    return { token: v.token, port: Number.isInteger(v.port) && v.port >= 1 && v.port <= 65535 ? v.port : null }
+  } catch {
+    return null
+  }
+}
+
+/**
+ * The state, created on first use. Never replaces a token that is already there.
+ *
+ * Created with `wx`, so two first runs at the same moment (a `serve` and a `--connection`) cannot
+ * each write a different token: the second one fails to create and reads the first one's. A file
+ * that exists but cannot be read as state is refused rather than overwritten: it may be a token
+ * the client already holds, and a silent new one would lock that client out with "bad token".
+ */
+export function ensureServeState(dataDir, platform = process.platform) {
+  mkdirSync(dataDir, { recursive: true })
+  const file = join(dataDir, SERVE_STATE_FILE)
+  if (!existsSync(file)) {
+    const token = randomBytes(32).toString('base64url')
+    try {
+      writePrivate(file, { v: 1, token, port: null }, 'wx')
+    } catch (e) {
+      if (e?.code !== 'EEXIST') throw e
+    }
+  }
+  const state = readServeState(dataDir)
+  if (!state) throw new Error(`${file} exists but is not a serve state file. Move it aside and run again.`)
+  keepPrivate(file, platform)
+  return state
+}
+
+/** Writes the port `serve` listened on, keeping the token. Atomic: a temp file renamed over it */
+export function recordServePort(dataDir, port, platform = process.platform) {
+  const file = join(dataDir, SERVE_STATE_FILE)
+  const state = readServeState(dataDir)
+  if (!state) throw new Error(`${file} is missing or unreadable`)
+  if (state.port === port) return
+  replacePrivate(file, { v: 1, token: state.token, port }, platform)
+}
+
+/**
+ * A new token, keeping the port. Only when the person asks (`--rotate-token`): every client that
+ * stored the old one has to fetch the new one with `--connection`, and a serve already running
+ * keeps answering to the old one until it restarts.
+ */
+export function rotateServeToken(dataDir, platform = process.platform) {
+  const before = ensureServeState(dataDir, platform)
+  replacePrivate(join(dataDir, SERVE_STATE_FILE), { v: 1, token: randomBytes(32).toString('base64url'), port: before.port }, platform)
+  return readServeState(dataDir)
+}
+
+/**
+ * Created 0600 from the first byte, not chmod-ed after: a file written with the default mode and
+ * narrowed afterwards is readable by everyone on the machine for the moment in between.
+ */
+function writePrivate(file, value, flag) {
+  const fd = openSync(file, flag, 0o600)
+  try {
+    writeSync(fd, `${JSON.stringify(value)}\n`)
+  } finally {
+    closeSync(fd)
+  }
+}
+
+/** Replaces a private file whole (`replaceFile`), created 0600 as `writePrivate` creates one */
+function replacePrivate(file, value, platform) {
+  replaceFile(file, `${JSON.stringify(value)}\n`, { mode: 0o600, flag: 'wx' })
+  keepPrivate(file, platform)
+}
+
+/**
+ * 0600 again on every use. A copy, a restore from backup or an editor that rewrites the file can
+ * leave it readable by the group; the token in it is the key to every RPC. Windows has no mode
+ * bits to set (the profile folder's ACL is what protects it there).
+ */
+function keepPrivate(file, platform) {
+  if (platform === 'win32') return
+  if ((statSync(file).mode & 0o777) !== 0o600) chmodSync(file, 0o600)
+}
+
+/** serve.pid: `{ pid, hostPid, port }` of the launcher that runs, or null */
+export function readServePid(dataDir) {
+  try {
+    const v = JSON.parse(readFileSync(join(dataDir, SERVE_PID_FILE), 'utf8'))
+    return Number.isInteger(v?.pid) && v.pid > 0 ? { pid: v.pid, hostPid: Number.isInteger(v.hostPid) ? v.hostPid : null, port: v.port ?? null } : null
+  } catch {
+    return null
+  }
+}
+
+export function removeServePid(dataDir, pid) {
+  if (readServePid(dataDir)?.pid !== pid) return
+  try {
+    rmSync(join(dataDir, SERVE_PID_FILE), { force: true })
+  } catch {
+    // another serve's by now, or gone
+  }
+}
+
+/**
+ * A probe that did not prove the token, while this data folder's host is alive (`host.lock`): a host from before #838
+ * still running after an update. It is running, and is not sent the token; a hub asking it for a proof is refused
+ * until it restarts. Without a live lock holder, what answered is not ours.
+ */
+export function heldHere(probe, dataDir, startOf = processStartTime) {
+  if (probe.running) return true
+  if (!probe.unproven) return false
+  return lockHolderIsAlive(dataDir, startOf)
+}
+
+/**
+ * Whether the process `host.lock` names is the one that wrote it (#838 review): alive, and started when the lock says
+ * (`ps -o lstart`, as the host writes it, `instance-lock.ts`). A lock left by a host that died, whose pid another
+ * process of the same user now has, names a stranger: counted as running, `--stop` would signal it. A lock without a
+ * start time (a host from before #184) or a system without `ps` (Windows) cannot be told apart, so it does not count.
+ */
+export function lockHolderIsAlive(dataDir, startOf = processStartTime) {
+  let holder
+  try {
+    holder = parseLockHolder(readFileSync(join(dataDir, 'host.lock'), 'utf8'))
+  } catch {
+    return false
+  }
+  if (!holder || !holder.started || !isAlive(holder.pid)) return false
+  return startOf(holder.pid) === holder.started
+}
+
+/**
+ * host.lock's `{ pid, started, by? }`; a bare pid (an older host) has no start time. `by` (#1223, additive) is who
+ * started the host: `app`, `keeper` or `serve` (`instance-lock.ts`), absent when the host did not say
+ */
+function parseLockHolder(text) {
+  const t = text.trim()
+  if (/^\d+$/.test(t)) return Number(t) > 0 ? { pid: Number(t), started: null } : null
+  try {
+    const v = JSON.parse(t)
+    if (!Number.isInteger(v?.pid) || v.pid <= 0) return null
+    const by = v.by === 'app' || v.by === 'keeper' || v.by === 'serve' ? v.by : null
+    return { pid: v.pid, started: typeof v.started === 'string' ? v.started : null, ...(by ? { by } : {}) }
+  } catch {
+    return null
+  }
+}
+
+/**
+ * A pid's start time, as `instance-lock.ts`'s `processStartTime` reads it: `ps -o lstart=` with the C locale, so the
+ * host that wrote the lock and this launcher read the same text. null without `ps` (Windows) or when it fails.
+ */
+export function processStartTime(pid) {
+  if (process.platform === 'win32') return null
+  try {
+    return execFileSync('ps', ['-o', 'lstart=', '-p', String(pid)], { encoding: 'utf8', timeout: 2000, env: { ...process.env, LC_ALL: 'C' }, stdio: ['ignore', 'pipe', 'ignore'] }).trim() || null
+  } catch {
+    return null
+  }
+}
+
+/** Who `host.lock` names as the data folder's owner, `{ pid, started, by? }`, or null */
+export function lockHolder(dataDir) {
+  try {
+    return parseLockHolder(readFileSync(join(dataDir, 'host.lock'), 'utf8'))
+  } catch {
+    return null
+  }
+}
+
+/** Who `host.lock` names as the data folder's owner, or null */
+export function lockHolderPid(dataDir) {
+  try {
+    return parseLockHolder(readFileSync(join(dataDir, 'host.lock'), 'utf8'))?.pid ?? null
+  } catch {
+    return null
+  }
+}