centralu 0.1.0-beta.26 → 0.1.0-beta.28

package/bin/serve-detach.mjs

@@ -0,0 +1,277 @@
+/**
+ * `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, renameSync, writeSync } from 'node:fs'
+import { userInfo } from 'node:os'
+import { join } from 'node:path'
+import { answerLine, isAlive, say, sayTo, runCaptured, tail, sleep, waitUntil } from './serve-util.mjs'
+import { SERVE_LOG_FILE, serveDataDir, readServeState, ensureServeState, heldHere, lockHolderPid, readServePid } from './serve-files.mjs'
+import { askPowershell, detachHow, windowsArg, wmiScript, parseWmiAnswer, wmiBlockedMessage, windowsPowershell, windowsTool, wslDistro, wslUser } from './serve-windows.mjs'
+import { DEFAULT_SERVE_PORT } from './serve-port.mjs'
+import { CHILD_FLAG } from './serve-args.mjs'
+import { protocolVersionOf, connectionLine, hostProvesOf, probeHost, askHostToStop } 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']
+
+export function encodeChildSpec({ env, log }) {
+  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 }), 'utf8').toString('base64url')
+}
+
+/** `{ log, env }` 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 }
+  } 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,
+  platform = process.platform,
+  execPath = process.execPath,
+  cwd = process.cwd(),
+  start = startDetached,
+  how = detachHow(platform, env),
+  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) => {
+    const d = await describe({ env, dataDir, state: ensureServeState(dataDir, platform), entry, version })
+    if (!d?.hostRunning) return false
+    write(`${connectionLine({ ...d, detach: { ok: true, how, already } })}\n`)
+    return true
+  }
+  if (await answered(true)) return 0
+
+  const log = join(dataDir, SERVE_LOG_FILE)
+  // One start per log: the last one's is kept beside it, and its absence is how a start that never ran shows
+  try {
+    renameSync(log, `${log}.1`)
+  } catch {
+    // there was none
+  }
+  const args = [cliPath, 'serve', ...(port !== null ? ['--port', String(port)] : []), `${CHILD_FLAG}${encodeChildSpec({ env, log })}`]
+  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}` : ''}`)
+}
+
+/**
+ * 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
+  }
+  say(`started in the background (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): asks the running host to stop over
+ * its own socket and waits until it has, so its shutdown runs (its agents, terminals and app
+ * processes stopped in order, the store closed). Measured on Windows: killing the WMI-started
+ * launcher ended the host 143 ms later with no "shutting down" line, because the host sits in
+ * libuv's kill-on-close job object; so on Windows killing is the last resort, not the way.
+ *
+ * Then, only for a host that did not go: posix SIGTERM to the launcher (which passes it to the host,
+ * the same clean stop), and on Windows ending the host. A host from before `host.stop` gets that
+ * too. The launcher ends with its host; one still there afterwards is ended.
+ *
+ * Only the processes serve.pid and host.lock name, and only while they agree with each other and
+ * the host answered with this folder's token: a stale pid is never signalled.
+ *
+ * stdout: one line, `{ v: 1, stop: { ok, wasRunning, how?, message? } }`.
+ */
+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 report = (stop) => answerLine(write, 'stop', stop)
+  const state = readServeState(dataDir)
+  if (!state) return report({ ok: true, wasRunning: false, message: `no centralu serve has run for ${dataDir}` })
+  const port = state.port ?? DEFAULT_SERVE_PORT
+  const installed = protocolVersionOf(entry) ?? 0
+  const prove = hostProvesOf(entry)
+  const probe = () => probeHost({ port, token: state.token, protocolVersion: installed, prove })
+  const first = await probe()
+  if (!heldHere(first, dataDir)) return report({ ok: true, wasRunning: false, message: `centralu serve is not running for ${dataDir}` })
+
+  const hostPid = lockHolderPid(dataDir)
+  const launcher = readServePid(dataDir)
+  // serve.pid is only believed when it names the host that holds the folder now
+  const launcherPid = launcher && hostPid && launcher.hostPid === hostPid ? launcher.pid : null
+  const down = async () => !(await probe()).running && !(hostPid && isAlive(hostPid))
+
+  let asked = await askHostToStop({ port, token: state.token, protocolVersion: first.protocolVersion ?? installed, prove })
+  if (!asked.ok && asked.protocolVersion !== undefined) asked = await askHostToStop({ port, token: state.token, protocolVersion: asked.protocolVersion, prove })
+  let how = 'asked'
+  let stopped = asked.ok && (await waitUntil(down, timeoutMs))
+  let note = asked.ok ? null : `the host did not take the request to stop (${asked.message})`
+  if (!stopped) {
+    const target = platform !== 'win32' && launcherPid ? launcherPid : hostPid
+    if (target) {
+      how = platform === 'win32' ? 'ended' : 'signal'
+      try {
+        kill(target, 'SIGTERM')
+      } catch {
+        // gone in the meantime
+      }
+      stopped = await waitUntil(down, platform === 'win32' ? 5_000 : graceMs)
+      if (!stopped && hostPid && isAlive(hostPid)) {
+        how = 'ended'
+        try {
+          kill(hostPid, 'SIGKILL')
+        } catch {
+          // gone in the meantime
+        }
+        stopped = await waitUntil(down, 5_000)
+      }
+    }
+    if (how === 'ended') note = `${note ? `${note}; ` : ''}ended the host without its shutdown`
+  }
+  if (launcherPid && launcherPid !== process.pid && !(await waitUntil(() => !isAlive(launcherPid), 5_000))) {
+    try {
+      kill(launcherPid, 'SIGKILL')
+    } catch {
+      // gone in the meantime
+    }
+  }
+  if (!stopped) return report({ ok: false, wasRunning: true, how, message: `the host on 127.0.0.1:${port} is still running${note ? ` (${note})` : ''}` })
+  return report({ ok: true, wasRunning: true, how, ...(note ? { message: note } : {}) })
+}

package/bin/serve-files.mjs

@@ -0,0 +1,218 @@
+/**
+ * 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, rmSync, statSync, writeSync, closeSync } from 'node:fs'
+import { join } from 'node:path'
+import { isAlive, 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'
+
+/** 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 }`; a bare pid (an older host) has no start time */
+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)
+    return Number.isInteger(v?.pid) && v.pid > 0 ? { pid: v.pid, started: typeof v.started === 'string' ? v.started : null } : null
+  } 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, or null */
+export function lockHolderPid(dataDir) {
+  try {
+    return parseLockHolder(readFileSync(join(dataDir, 'host.lock'), 'utf8'))?.pid ?? null
+  } catch {
+    return null
+  }
+}