centralu 0.1.0-beta.13 → 0.1.0-beta.15

package/bin/centralu.mjs

@@ -29,7 +29,7 @@ import {
   busyMessage,
   earlyExitMessage,
   executableIn,
-  hostDirIn,
+  findHostEntry,
   installedPaths,
   isBusyError,
   launchPlan,
@@ -47,12 +47,14 @@ import {
   parseServeArgs,
   printConnection,
   rotateToken,
+  runAutostart,
   runDetach,
   runDetachedChild,
   runServe,
   runStop,
   SERVE_HELP,
 } from './serve.mjs'
+import { swapInto } from './swap.mjs'
 import { chmodSync, cpSync, existsSync, mkdirSync, readdirSync, readFileSync, realpathSync, renameSync, rmSync, writeFileSync } from 'node:fs'
 import { createRequire } from 'node:module'
 import { homedir } from 'node:os'
@@ -118,7 +120,8 @@ function explainMissing() {
 }
 
 /**
- * The bundled host's entry (`resources/host/main.mjs`) for `centralu serve`, or exit with why not.
+ * The bundled host's entry (`resources/host/main.mjs`) for `centralu serve`, or exit with why not:
+ * from the platform package, or from the host-only package where a hub installed this (`findHostEntry`).
  *
  * `CENTRALU_HOST_ENTRY` points it at another host instead: a source checkout's
  * `packages/agent-host/src/main.ts` while developing, or a freshly bundled `resources/host/main.mjs`.
@@ -130,22 +133,27 @@ function requireHostEntry() {
     console.error(explainMissing())
     process.exit(1)
   }
-  let root
-  try {
-    root = dirname(require.resolve(`${TARGET.pkg}/package.json`))
-  } catch {
-    console.error(explainMissing())
-    process.exit(1)
-  }
-  const entry = join(hostDirIn(PLATFORM, join(root, TARGET.artifact)), 'main.mjs')
-  if (!existsSync(entry)) {
+  // The platform package of an npm install, else the host-only package a hub installed (platform.mjs)
+  const found = findHostEntry(PLATFORM, process.arch, {
+    resolveRoot: (name) => {
+      try {
+        return dirname(require.resolve(`${name}/package.json`))
+      } catch {
+        return null
+      }
+    },
+    exists: existsSync,
+  })
+  if (found.entry) return found.entry
+  if (found.missingHost) {
     console.error(
-      `The host is missing from ${TARGET.pkg} (looked for ${entry}).\n` +
+      `The host is missing from ${found.missingHost.pkg} (looked for ${found.missingHost.entry}).\n` +
         'Linux packages published before `centralu serve` existed do not carry it. Update with `npm i -g centralu`.',
     )
     process.exit(1)
   }
-  return entry
+  console.error(explainMissing())
+  process.exit(1)
 }
 
 function requireApp() {
@@ -272,13 +280,14 @@ function install() {
   const app = requireApp()
   if (PLATFORM === 'win32') return installWindows(app)
   if (PLATFORM !== 'darwin') return installDesktopEntry(app)
-  if (existsSync(INSTALLED)) {
-    console.log(`Replacing the existing ${INSTALLED} with the new version.`)
-    rmSync(INSTALLED, { recursive: true, force: true })
-  }
-  // ditto, not cp — carries over the bundle's permissions and extended attributes unchanged
-  // (so the signature does not break).
-  execFileSync('/usr/bin/ditto', [app, INSTALLED], { stdio: 'inherit' })
+  if (existsSync(INSTALLED)) console.log(`Replacing the existing ${INSTALLED} with the new version.`)
+  // Copied beside the old one and swapped in by rename (swap.mjs): a copy that fails leaves the
+  // old app in place rather than none. ditto, not cp — carries over the bundle's permissions and
+  // extended attributes unchanged (so the signature does not break).
+  const { leftAt } = swapInto(INSTALLED, (staging) => {
+    execFileSync('/usr/bin/ditto', [app, staging], { stdio: 'inherit' })
+  })
+  if (leftAt) console.log(`The previous copy could not be removed and was left at ${leftAt}. Delete it yourself.`)
   console.log(`Installed: ${INSTALLED}`)
   console.log('It can now be found in Launchpad and Spotlight too.')
 }
@@ -602,6 +611,7 @@ switch (cmd) {
       if (args.mode === 'connection') process.exitCode = await printConnection(opts)
       else if (args.mode === 'detach') process.exitCode = await runDetach({ ...opts, port: args.port })
       else if (args.mode === 'stop') process.exitCode = await runStop(opts)
+      else if (args.mode === 'autostart') process.exitCode = await runAutostart({ ...opts, action: args.autostart })
       else if (spec) process.exitCode = await runDetachedChild({ ...opts, spec, port: args.port })
       else process.exitCode = await runServe({ ...opts, port: args.port })
     } catch (e) {

package/bin/platform.mjs

@@ -70,6 +70,46 @@ export function hostDirIn(platform, app) {
   return posix.join(posix.dirname(app), 'host')
 }
 
+/**
+ * The host alone, without the window, for the machines a hub installs on (docs/plans/remote-hub.md
+ * §10.2, owner decision 2 of §10.9): `host/` at the top of the package on every platform. The shim
+ * never pins these (an npm install gets the host inside its platform package already); a hub's
+ * installer fetches one beside this package instead of the platform package, so a Linux remote does
+ * not download an 81 MB AppImage to throw away. Published from the same release jobs as the platform
+ * packages (`scripts/host-package.mts`); `tooling/host-package.test.ts` holds this table to them.
+ */
+export const HOST_PACKAGES = {
+  'linux-arm64': '@centralu/host-linux-arm64',
+  'linux-x64': '@centralu/host-linux-x64',
+  'win32-x64': '@centralu/host-win32-x64',
+}
+
+/**
+ * Where `centralu serve` finds the host's `main.mjs`: in the platform package (an npm install), else
+ * in the host-only package (what a hub installed, `<data>/remote/versions/<v>/node_modules/`).
+ *
+ * `resolveRoot(name)` is the package's folder or null when it is not installed; `exists(file)` says
+ * whether a file is there. Answers `{ entry }`, or `{ missingHost: { pkg, entry } }` when a package
+ * is installed without its host, or `{ missingPackage: true }` when neither is installed.
+ */
+export function findHostEntry(platform, arch, { resolveRoot, exists }) {
+  const join = platform === 'win32' ? win32.join : posix.join
+  const target = targetFor(platform, arch)
+  const hostOnly = HOST_PACKAGES[`${platform}-${arch}`]
+  const places = []
+  if (target) places.push({ pkg: target.pkg, dir: (root) => hostDirIn(platform, join(root, target.artifact)) })
+  if (hostOnly) places.push({ pkg: hostOnly, dir: (root) => join(root, 'host') })
+  let missingHost = null
+  for (const place of places) {
+    const root = resolveRoot(place.pkg)
+    if (!root) continue
+    const entry = join(place.dir(root), 'main.mjs')
+    if (exists(entry)) return { entry }
+    missingHost ??= { pkg: place.pkg, entry }
+  }
+  return missingHost ? { missingHost } : { missingPackage: true }
+}
+
 /**
  * How to start the app: the command, its arguments, the spawn options, and whether the
  * launcher stays attached until it exits.

package/bin/semver.mjs

@@ -68,7 +68,15 @@ export function copyDiffers(pkgVersion, copyVersion) {
   return typeof copyVersion === 'string' && copyVersion !== '' && copyVersion !== pkgVersion
 }
 
-function split(v) {
+/*
+ * Build metadata (`+sha`) is dropped first: semver ignores it for precedence, and left in, it turned `3+build5`
+ * into NaN (and the `-` in `+build-5` into a prerelease). A leading `v` (`v1.2.3`, as a tag is written) is dropped
+ * too, or the first slot is NaN. Either NaN ends the comparison as "not newer", the #42 failure again.
+ */
+function split(raw) {
+  let v = raw.trim().replace(/^v/i, '')
+  const plus = v.indexOf('+')
+  if (plus !== -1) v = v.slice(0, plus)
   const dash = v.indexOf('-')
   const core = (dash === -1 ? v : v.slice(0, dash)).split('.').map(Number)
   const pre = dash === -1 ? null : v.slice(dash + 1)

package/bin/serve.mjs

@@ -16,11 +16,11 @@
  * directory, so this ships automatically.
  */
 import { spawn } from 'node:child_process'
-import { randomBytes } from 'node:crypto'
+import { createHash, randomBytes } from 'node:crypto'
 import { chmodSync, existsSync, mkdirSync, openSync, readFileSync, renameSync, rmSync, statSync, writeFileSync, writeSync, closeSync } from 'node:fs'
-import { connect } from 'node:net'
+import { connect, createServer } from 'node:net'
 import { userInfo } from 'node:os'
-import { dirname, join } from 'node:path'
+import { dirname, join, posix } from 'node:path'
 import { createInterface } from 'node:readline'
 
 /**
@@ -34,6 +34,70 @@ import { createInterface } from 'node:readline'
  */
 export const DEFAULT_SERVE_PORT = 17175
 
+/** How many ports from the recorded one `serve` tries when it is taken (#482); none at or above 20000 */
+export const SERVE_PORT_TRIES = 20
+
+/**
+ * The port `serve` starts the host on (#482): `{ port, from }`, `from` being the port it moved away
+ * from (null when it did not), or null when every candidate is taken.
+ *
+ * A port the person gave (`--port`) is used as given: they asked for that one. Otherwise the recorded
+ * port (else the default) when it is free, and when another program listens there, the next free
+ * one above it, below 20000 (the ranges `DEFAULT_SERVE_PORT` keeps out of). The host's ready line
+ * then records the port it got, so `--connection` reports it and the hub forwards to it.
+ *
+ * The usual other program is the other half of one Windows laptop: WSL2 relays a distro's
+ * 127.0.0.1 ports to Windows (`wslrelay.exe`), so a Windows install and a WSL install linked as two
+ * machines both wanted 17175, and whichever started second could not start at all.
+ * `taken(port)` answers whether something listens there.
+ */
+export async function chooseServePort({ asked, recorded, taken }) {
+  if (asked !== null && asked !== undefined) return { port: asked, from: null }
+  const first = recorded ?? DEFAULT_SERVE_PORT
+  for (let p = first; p < first + SERVE_PORT_TRIES && p <= 65535; p++) {
+    if (p !== first && p >= 20000) break
+    if (!(await taken(p))) return { port: p, from: p === first ? null : first }
+  }
+  return null
+}
+
+/** Whether something listens on 127.0.0.1:`port` here: a listen that fails with EADDRINUSE (or EACCES) */
+export function listensHere(port) {
+  return new Promise((resolve) => {
+    const srv = createServer()
+    srv.once('error', (e) => resolve(e?.code === 'EADDRINUSE' || e?.code === 'EACCES'))
+    srv.listen({ host: '127.0.0.1', port, exclusive: true }, () => srv.close(() => resolve(false)))
+  })
+}
+
+/**
+ * The TCP ports Windows listens on, from `netstat.exe -an -p TCP` output: a listening socket is the
+ * row whose foreign address is `0.0.0.0:0` (or `[::]:0`). Read that way rather than by the state
+ * column, which Windows translates (a Korean Windows does not print LISTENING everywhere).
+ */
+export function parseNetstatListening(text) {
+  const ports = new Set()
+  for (const line of String(text).split(/\r?\n/)) {
+    const m = /^\s*TCP\s+(?:127\.0\.0\.1|0\.0\.0\.0|\[::1?\]):(\d+)\s+(?:0\.0\.0\.0:0|\[::\]:0)\s/i.exec(line)
+    if (m) ports.add(Number(m[1]))
+  }
+  return ports
+}
+
+/**
+ * The ports the Windows side listens on, seen from inside a WSL distro (empty elsewhere, or when
+ * Windows cannot be asked). Inside the distro a port Windows holds looks free, yet a host there
+ * would be unreachable from the hub: the hub's forward ends on Windows' 127.0.0.1, where the
+ * Windows program answers instead (#482).
+ */
+async function windowsListening(env, platform) {
+  if (detachHow(platform, env) !== 'wsl') return new Set()
+  const netstat = windowsTool('wsl', env, ['System32', 'netstat.exe'])
+  if (!netstat) return new Set()
+  const r = await runCaptured(netstat, ['-an', '-p', 'TCP'], env)
+  return r.code === 0 ? parseNetstatListening(r.stdout) : new Set()
+}
+
 /**
  * The file in the data folder that holds the token and the port, mode 0600.
  *
@@ -58,6 +122,11 @@ export const SERVE_HELP = `centralu serve: run the Centralu host on this machine
   centralu serve --stop           Ask the running host to stop, and wait until it has
   centralu serve --connection     Print how to reach it as one JSON line, then exit
   centralu serve --rotate-token   Replace the token (a running serve keeps the old one until restarted)
+  centralu serve --autostart on|off|status
+                                  Start it when this machine starts (Linux: a systemd user unit;
+                                  Windows and WSL: a scheduled task at sign-in), stop doing that,
+                                  or say whether it does. Turning it on or off leaves a host that
+                                  runs now as it is
 
 The data folder is ~/.centralu (CC_DATA_DIR overrides it). The app on another computer reaches
 this host through an SSH local forward, and starts it with --detach when it is not running.
@@ -70,7 +139,10 @@ from an install the app made over SSH, which has a launcher of its own.`
 
 /** The flags that each make serve a different command */
 const MODE_FLAGS = { '--connection': 'connection', '--rotate-token': 'rotate', '--detach': 'detach', '--stop': 'stop' }
-const FLAG_OF = Object.fromEntries(Object.entries(MODE_FLAGS).map(([f, m]) => [m, f]))
+const FLAG_OF = { ...Object.fromEntries(Object.entries(MODE_FLAGS).map(([f, m]) => [m, f])), autostart: '--autostart' }
+
+/** What `--autostart` takes */
+export const AUTOSTART_ACTIONS = ['on', 'off', 'status']
 
 /**
  * The argument a detached launcher is started with: what it needs from the `--detach` that started
@@ -80,21 +152,29 @@ const FLAG_OF = Object.fromEntries(Object.entries(MODE_FLAGS).map(([f, m]) => [m
 const CHILD_FLAG = '--detached-child='
 
 /**
- * What the arguments after `serve` ask for: `{ mode, port }` (plus `child` for a detached launcher)
- * or `{ error }`.
+ * What the arguments after `serve` ask for: `{ mode, port }` (plus `child` for a detached launcher,
+ * `autostart` for `--autostart`) or `{ error }`.
  *
- * `mode` is `serve`, `detach`, `stop`, `connection`, `rotate` or `help`; `port` is null when not
- * given. `--port` goes with `serve` and `--detach` only: `--connection` has to report the port
- * `serve` uses, not one the caller names, and `--stop` stops the one that runs.
+ * `mode` is `serve`, `detach`, `stop`, `connection`, `rotate`, `autostart` or `help`; `port` is null
+ * when not given. `--port` goes with `serve` and `--detach` only: `--connection` has to report the
+ * port `serve` uses, not one the caller names, `--stop` stops the one that runs, and the entry
+ * `--autostart` writes starts serve on the port it recorded.
  */
 export function parseServeArgs(argv) {
   let mode = 'serve'
   let port = null
   let help = false
   let child = null
+  let autostart = null
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i]
-    if (Object.hasOwn(MODE_FLAGS, a)) {
+    if (a === '--autostart' || a.startsWith('--autostart=')) {
+      const raw = a === '--autostart' ? argv[++i] : a.slice('--autostart='.length)
+      if (!AUTOSTART_ACTIONS.includes(raw)) return { error: `--autostart needs on, off or status (got ${raw === undefined ? 'nothing' : JSON.stringify(raw)})` }
+      if (mode !== 'serve' && mode !== 'autostart') return { error: `${FLAG_OF[mode]} and --autostart are separate commands; pass one` }
+      mode = 'autostart'
+      autostart = raw
+    } else if (Object.hasOwn(MODE_FLAGS, a)) {
       const m = MODE_FLAGS[a]
       if (mode !== 'serve' && mode !== m) return { error: `${FLAG_OF[mode]} and ${a} are separate commands; pass one` }
       mode = m
@@ -116,6 +196,10 @@ export function parseServeArgs(argv) {
     return { error: '--port goes with `centralu serve`; `--connection` reports the port serve listens on' }
   }
   if (mode === 'stop' && port !== null) return { error: '--stop stops the serve that is running, on the port it recorded; it takes no --port' }
+  if (mode === 'autostart') {
+    if (port !== null) return { error: '--autostart takes no --port: the entry it writes starts serve on the port serve recorded' }
+    return { mode, port, autostart }
+  }
   return { mode, port }
 }
 
@@ -314,7 +398,7 @@ export function protocolVersionOf(entry) {
  * `install` (additive, the line stays `v: 1`) says what runs this command (`installInfo`); `detach`
  * is added by `--detach` only.
  */
-export function connectionLine({ port, token, version, protocolVersion, dataDir, hostRunning, install, detach }) {
+export function connectionLine({ port, token, version, protocolVersion, dataDir, hostRunning, install, autostart, detach }) {
   return JSON.stringify({
     v: 1,
     port,
@@ -324,6 +408,7 @@ export function connectionLine({ port, token, version, protocolVersion, dataDir,
     dataDir,
     hostRunning,
     ...(install ? { install } : {}),
+    ...(autostart ? { autostart } : {}),
     ...(detach ? { detach } : {}),
   })
 }
@@ -614,6 +699,7 @@ async function describe({ env, dataDir, state, entry, version }) {
     dataDir,
     hostRunning: probe.running,
     install: installInfo(dataDir, env),
+    autostart: autostartInfo(dataDir, process.platform, env),
   }
 }
 
@@ -669,7 +755,6 @@ export async function runServe({ env, home, entry, version, cliPath, port: asked
   const dataDir = serveDataDir(env, home)
   const state = ensureServeState(dataDir, platform)
   keepLauncher(dataDir, cliPath, env)
-  const port = askedPort ?? state.port ?? DEFAULT_SERVE_PORT
   const protocolVersion = protocolVersionOf(entry)
 
   // A serve that is already up answers on the port it recorded; say so before starting a host that
@@ -682,6 +767,18 @@ export async function runServe({ env, home, entry, version, cliPath, port: asked
     return 1
   }
 
+  const onWindows = await windowsListening(env, platform)
+  const chosen = await chooseServePort({ asked: askedPort, recorded: state.port, taken: async (p) => onWindows.has(p) || (await listensHere(p)) })
+  if (chosen === null) {
+    say(`another program listens on 127.0.0.1:${recorded} and on the ${SERVE_PORT_TRIES - 1} ports above it. Give a free one with --port <n>.`)
+    return 1
+  }
+  const port = chosen.port
+  if (chosen.from !== null) {
+    const who = onWindows.has(chosen.from) ? 'Windows' : 'another program'
+    say(`127.0.0.1:${chosen.from} is in use by ${who}; starting on ${port} instead (kept for the next start)`)
+  }
+
   const plan = hostCommand(execPath, entry, { port, dataDir, platform })
   const child = spawn(plan.command, plan.args, {
     stdio: ['pipe', 'pipe', logFd === null ? 'inherit' : 'pipe'],
@@ -1243,3 +1340,370 @@ export async function runStop({
   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 } : {}) })
 }
+
+// ── --autostart ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * What `--autostart on` records in the data folder: the entry it wrote, so `--connection` can say
+ * whether this machine starts its host at boot without asking systemd or Task Scheduler at every
+ * link start. `--autostart status` asks them, and corrects this file when it disagrees.
+ */
+export const AUTOSTART_FILE = 'autostart.json'
+
+/** The variables the entry carries to the serve it starts: the data folder, and a host entry (development) */
+export const AUTOSTART_ENV = ['CC_DATA_DIR', 'CENTRALU_HOST_ENTRY']
+
+/**
+ * How this machine would start `serve` at boot (docs/plans/remote-hub.md §10.4, owner decision 4),
+ * or null where it offers none:
+ *
+ *   systemd  Linux: a `systemd --user` unit, enabled for `default.target`, plus lingering so the
+ *            user's manager starts at boot rather than at the first login
+ *   task     Windows: a per-user scheduled task at sign-in (no administrator needed). Also inside
+ *            WSL: nothing in a stopped distro runs, so the Windows side has to start it, through
+ *            `wsl.exe`, which then holds the distro for as long as the host runs
+ *
+ * WSL with interop off has no way to the Windows side, and a Linux without systemd (or macOS) has
+ * no user unit; those say so instead.
+ */
+export function autostartHow(platform, env, { interop = wslInterop, systemd = () => existsSync('/run/systemd/system') } = {}) {
+  if (platform === 'win32') return 'task'
+  if (platform !== 'linux') return null
+  if (env.WSL_DISTRO_NAME) return interop() ? 'task' : null
+  return systemd() ? 'systemd' : null
+}
+
+/** Why `autostartHow` found nothing, in one sentence */
+export function autostartUnsupported(platform, env) {
+  if (platform === 'linux' && env.WSL_DISTRO_NAME) {
+    return 'Starting Centralu with WSL needs a Windows scheduled task, and this distro cannot run Windows programs (WSL interop is off)'
+  }
+  if (platform === 'linux') return 'This Linux does not run systemd, so there is no user unit to start Centralu at boot; start `centralu serve` from your own init system'
+  return `Starting Centralu at boot is offered on Linux and Windows; on ${platform === 'darwin' ? 'macOS' : platform}, run \`centralu serve --detach\` from a login item or launchd agent of your own`
+}
+
+/**
+ * A folder path as a comparable key on `platform`: either separator as `/`, `.` and `..` folded, no
+ * trailing separator, and lower case on Windows, whose paths do not differ by case
+ */
+export function pathKey(p, platform) {
+  let s = posix.normalize(String(p).replaceAll('\\', '/'))
+  if (s.length > 1) s = s.replace(/\/+$/, '')
+  return platform === 'win32' ? s.toLowerCase() : s
+}
+
+/**
+ * The entry's name. One per data folder: the default one gets the plain name, any other (a second
+ * install, a test's temporary folder) a suffix from its path, so they never replace each other. A
+ * Windows laptop linked twice, as Windows and as a WSL distro, gets two tasks.
+ *
+ * Whether `dataDir` is the default is read the same way whatever OS runs this (`pathKey`), not with
+ * this Node's `join`: the folder may be written with either separator (`CC_DATA_DIR=C:/x` on Windows),
+ * and Windows paths do not differ by case, so `C:\Users\Me\.centralu` is the default folder too.
+ */
+export function autostartName(how, { dataDir, home, env, platform = process.platform }) {
+  const key = pathKey(dataDir, platform)
+  const own = key === pathKey(`${home}/.centralu`, platform) ? '' : createHash('sha256').update(key).digest('hex').slice(0, 8)
+  if (how === 'systemd') return `centralu-serve${own ? `-${own}` : ''}.service`
+  const distro = env.WSL_DISTRO_NAME
+  if (distro && !/^[A-Za-z0-9._-]{1,64}$/.test(distro)) throw new Error(`not a WSL distro name: ${distro}`)
+  return `Centralu host${distro ? ` (WSL ${distro})` : ''}${own ? ` ${own}` : ''}`
+}
+
+/**
+ * What the entry runs: the managed launcher when the app installed Centralu here over ssh (its text
+ * never changes and it reads `current`, so an update needs no new entry), else the launcher `serve`
+ * keeps for an npm install. The order is the hub's lookup (`connectionCommand` in links/tunnel.ts).
+ */
+export function autostartLauncher(dataDir, platform, exists = existsSync) {
+  const file = platform === 'win32' ? 'centralu.cmd' : 'centralu'
+  for (const p of [join(remoteLayout(dataDir).bin, file), join(dataDir, 'bin', file)]) if (exists(p)) return p
+  return null
+}
+
+/** One value for a unit file, double-quoted; `$` doubled where systemd would expand it (ExecStart) */
+function systemdQuote(value, { dollars = false } = {}) {
+  const s = String(value)
+  if (/[\r\n\0]/.test(s)) throw new Error(`cannot put ${JSON.stringify(s)} in a systemd unit`)
+  let q = s.replaceAll('\\', '\\\\').replaceAll('"', '\\"').replaceAll('%', '%%')
+  if (dollars) q = q.replaceAll('$', '$$$$')
+  return `"${q}"`
+}
+
+/**
+ * The `systemd --user` unit (docs/agent-host.md §4.7 has the hand-written one this follows).
+ *
+ * - `serve` in the foreground: systemd is what keeps it outside any session.
+ * - `KillMode=mixed`: a stop sends SIGTERM to the launcher only, which passes one to the host, which
+ *   stops its agents in order; the rest of the group is killed only after `TimeoutStopSec`.
+ * - `Restart=on-failure`, but bounded: a host that fails at every start (a port another program
+ *   holds, a store from a newer build) is left failed after five tries in five minutes rather than
+ *   started forever. A clean stop (`serve --stop`, as an update does) exits 0 and stays stopped.
+ */
+export function systemdUnit({ launcher, env }) {
+  return [
+    '# Written by `centralu serve --autostart on`; `centralu serve --autostart off` removes it.',
+    '[Unit]',
+    'Description=Centralu host (centralu serve)',
+    'StartLimitIntervalSec=300',
+    'StartLimitBurst=5',
+    '',
+    '[Service]',
+    'Type=simple',
+    ...AUTOSTART_ENV.filter((k) => env[k]).map((k) => `Environment=${systemdQuote(`${k}=${env[k]}`)}`),
+    `ExecStart=${systemdQuote(launcher, { dollars: true })} serve`,
+    'KillMode=mixed',
+    'TimeoutStopSec=30',
+    'Restart=on-failure',
+    'RestartSec=10',
+    '',
+    '[Install]',
+    'WantedBy=default.target',
+    '',
+  ].join('\n')
+}
+
+/** A PowerShell expression for `s`: base64 decoded there, so no quote reaches PowerShell's parser */
+function psText(s) {
+  return `([Text.Encoding]::UTF8.GetString([Convert]::FromBase64String('${Buffer.from(String(s), 'utf8').toString('base64')}')))`
+}
+
+/**
+ * The PowerShell the scheduled task runs at sign-in, in a hidden window: `serve` in the foreground,
+ * for as long as it runs. Not `--detach`: a task is not an ssh session, so nothing ends it with one,
+ * and it needs no WMI, which some machines block (decision 3).
+ *
+ *   Windows  the launcher itself
+ *   WSL      `wsl.exe -d <distro> -u <user> --exec <launcher> serve`: that `wsl.exe` is a client of
+ *            the distro for as long as the host runs, so WSL does not stop it (§10.4)
+ *
+ * The variables of `AUTOSTART_ENV` are set in the task (Windows) or passed through `env` (WSL, where
+ * the Windows side's environment does not reach the distro).
+ */
+export function taskActionScript({ how, launcher, env, distro = null, user = null }) {
+  const carried = AUTOSTART_ENV.filter((k) => env[k])
+  if (how === 'wmi') return [...carried.map((k) => `$env:${k} = ${psText(env[k])}`), `& ${psText(launcher)} serve`].join('\n')
+  if (!/^[A-Za-z0-9._-]{1,64}$/.test(distro ?? '')) throw new Error(`not a WSL distro name: ${distro}`)
+  if (!/^[A-Za-z_][A-Za-z0-9_.-]{0,31}$/.test(user ?? '')) throw new Error(`cannot name the user ${user} to wsl.exe`)
+  const args = ['-d', distro, '-u', user, '--cd', '~', '--exec', ...(carried.length ? ['/usr/bin/env', ...carried.map((k) => `${k}=${env[k]}`)] : []), launcher, 'serve']
+  for (const a of args) if (/["\r\n\0]/.test(a)) throw new Error(`cannot pass ${JSON.stringify(a)} on a Windows command line`)
+  return [`$a = @(${args.map(psText).join(', ')})`, "& (Join-Path $env:SystemRoot 'System32\\wsl.exe') @a"].join('\n')
+}
+
+const TASK_WORD = 'CENTRALU-AUTOSTART'
+
+/**
+ * The PowerShell that registers, removes or reads the scheduled task, printing one `CENTRALU-AUTOSTART`
+ * line. Registered for this user only, at this user's sign-in, run only while they are signed in
+ * (`Interactive`): the kind of task a user may create without an administrator. On a laptop, it runs
+ * on battery too, and with no time limit (the default ends a task after 72 hours).
+ */
+export function taskScript(action, { name, run = '' }) {
+  const head = ["$ErrorActionPreference = 'Stop'", '[Console]::OutputEncoding = [Text.Encoding]::UTF8', `$name = ${psText(name)}`]
+  const fail = `} catch { "${TASK_WORD}-ERROR $($_.Exception.Message -replace '\\s+', ' ')" }`
+  const find = "$t = Get-ScheduledTask -TaskName $name -TaskPath '\\' -ErrorAction SilentlyContinue"
+  if (action === 'status') return [...head, 'try {', `  ${find}`, `  if ($t) { "${TASK_WORD} state $($t.State)" } else { '${TASK_WORD} state none' }`, fail].join('\n')
+  if (action === 'off') {
+    return [...head, 'try {', `  ${find}`, "  if ($t) { Unregister-ScheduledTask -TaskName $name -TaskPath '\\' -Confirm:$false }", `  '${TASK_WORD} off'`, fail].join('\n')
+  }
+  const encoded = Buffer.from(run, 'utf16le').toString('base64')
+  return [
+    ...head,
+    'try {',
+    "  $exe = Join-Path $env:SystemRoot 'System32\\WindowsPowerShell\\v1.0\\powershell.exe'",
+    `  $arg = '-NoProfile -NonInteractive -WindowStyle Hidden -EncodedCommand ${encoded}'`,
+    '  $user = if ($env:USERDOMAIN) { "$env:USERDOMAIN\\$env:USERNAME" } else { $env:USERNAME }',
+    '  $a = New-ScheduledTaskAction -Execute $exe -Argument $arg',
+    '  $tr = New-ScheduledTaskTrigger -AtLogOn -User $user',
+    '  $p = New-ScheduledTaskPrincipal -UserId $user -LogonType Interactive -RunLevel Limited',
+    '  $s = New-ScheduledTaskSettingsSet -AllowStartIfOnBatteries -DontStopIfGoingOnBatteries -ExecutionTimeLimit ([TimeSpan]::Zero) -MultipleInstances IgnoreNew',
+    `  Register-ScheduledTask -TaskName $name -TaskPath '\\' -Action $a -Trigger $tr -Principal $p -Settings $s -Description ${psText('Starts the Centralu host (centralu serve) when you sign in. Written by centralu serve --autostart on.')} -Force | Out-Null`,
+    `  '${TASK_WORD} on'`,
+    fail,
+  ].join('\n')
+}
+
+/** What a task script printed: `{ ok: true, word }` (`on`, `off`, or the state after `state`) or `{ ok: false, message }` */
+export function parseTaskAnswer(stdout) {
+  const text = String(stdout ?? '')
+  const e = new RegExp(`${TASK_WORD}-ERROR (.*)`).exec(text)
+  if (e) return { ok: false, message: e[1].trim() }
+  const m = new RegExp(`${TASK_WORD} (?:state )?(\\S+)`).exec(text)
+  if (m) return { ok: true, word: m[1] }
+  return { ok: false, message: 'PowerShell did not answer' }
+}
+
+/** `{ how, name, linger }` from `AUTOSTART_FILE`, or null */
+export function readAutostartMark(dataDir) {
+  try {
+    const v = JSON.parse(readFileSync(join(dataDir, AUTOSTART_FILE), 'utf8'))
+    if ((v?.how !== 'systemd' && v?.how !== 'task') || typeof v.name !== 'string') return null
+    return { how: v.how, name: v.name, linger: typeof v.linger === 'boolean' ? v.linger : null }
+  } catch {
+    return null
+  }
+}
+
+function writeAutostartMark(dataDir, mark) {
+  mkdirSync(dataDir, { recursive: true })
+  const file = join(dataDir, AUTOSTART_FILE)
+  const tmp = `${file}.${process.pid}.tmp`
+  writeFileSync(tmp, `${JSON.stringify({ v: 1, ...mark, at: Date.now() })}\n`)
+  renameSync(tmp, file)
+}
+
+function clearAutostartMark(dataDir) {
+  rmSync(join(dataDir, AUTOSTART_FILE), { force: true })
+}
+
+/**
+ * The connection line's `autostart` field (additive): `{ on, how, linger }`. `how` is what this
+ * machine would use (null where it offers nothing), `on` whether `--autostart on` wrote an entry of
+ * that kind, `linger` (systemd only) whether the user's manager starts at boot. From the mark only:
+ * this runs at every link start.
+ */
+export function autostartInfo(dataDir, platform, env, how = autostartHow(platform, env)) {
+  const mark = readAutostartMark(dataDir)
+  const on = how !== null && mark?.how === how
+  return { on, how, linger: on && how === 'systemd' ? mark.linger : null }
+}
+
+/** The sentence for a user manager that starts only at login (`loginctl enable-linger` refused) */
+export function lingerMessage(user) {
+  return `systemd starts it when ${user} logs in, not at boot, until an administrator runs \`sudo loginctl enable-linger ${user}\` there`
+}
+
+/** systemctl --user over ssh needs the user's runtime folder; a session without pam_systemd may not name it */
+function userManagerEnv(env) {
+  if (env.XDG_RUNTIME_DIR || typeof process.getuid !== 'function') return env
+  const dir = `/run/user/${process.getuid()}`
+  return existsSync(dir) ? { ...env, XDG_RUNTIME_DIR: dir } : env
+}
+
+async function systemdAutostart(action, { dataDir, env, home, name, run, user }) {
+  const dir = join(env.XDG_CONFIG_HOME || join(home, '.config'), 'systemd', 'user')
+  const file = join(dir, name)
+  const ctlEnv = userManagerEnv(env)
+  const ctl = (...args) => run('systemctl', ['--user', ...args], ctlEnv)
+  const lingers = async () => {
+    const r = await run('loginctl', ['show-user', user, '--property=Linger', '--value'], ctlEnv)
+    return r.code === 0 ? r.stdout.trim() === 'yes' : null
+  }
+  const base = { ok: true, how: 'systemd' }
+  if (action === 'status') {
+    const on = existsSync(file) && (await ctl('is-enabled', name)).stdout.trim() === 'enabled'
+    const linger = on ? await lingers() : null
+    if (on) writeAutostartMark(dataDir, { how: 'systemd', name, linger })
+    else clearAutostartMark(dataDir)
+    return { ...base, on, linger }
+  }
+  if (action === 'off') {
+    if (existsSync(file)) {
+      await ctl('disable', name)
+      rmSync(file, { force: true })
+      // Left by an `enable` whose `disable` did not reach the manager; harmless, but not ours to leave
+      rmSync(join(dir, 'default.target.wants', name), { force: true })
+      await ctl('daemon-reload')
+    }
+    clearAutostartMark(dataDir)
+    return { ...base, on: false, linger: null }
+  }
+  const launcher = autostartLauncher(dataDir, 'linux')
+  if (!launcher) return { ...base, ok: false, on: false, linger: null, message: `there is no Centralu launcher in ${dataDir} to start at boot` }
+  mkdirSync(dir, { recursive: true })
+  const tmp = `${file}.${process.pid}.tmp`
+  writeFileSync(tmp, systemdUnit({ launcher, env }))
+  renameSync(tmp, file)
+  let r = await ctl('daemon-reload')
+  if (r.code === 0) r = await ctl('enable', name)
+  if (r.code !== 0) {
+    rmSync(file, { force: true })
+    await ctl('daemon-reload')
+    clearAutostartMark(dataDir)
+    const why = String(r.stderr).trim().split(/\r?\n/).at(-1) || `exit ${r.code}`
+    return { ...base, ok: false, on: false, linger: null, message: `systemd did not take the unit: ${why}` }
+  }
+  let linger = await lingers()
+  if (linger === false) {
+    await run('loginctl', ['--no-ask-password', 'enable-linger', user], ctlEnv)
+    linger = await lingers()
+  }
+  writeAutostartMark(dataDir, { how: 'systemd', name, linger })
+  return { ...base, on: true, linger, ...(linger === true ? {} : { message: lingerMessage(user) }) }
+}
+
+async function taskAutostart(action, { dataDir, env, name, run, user, platform, interop }) {
+  const detach = detachHow(platform, env, interop)
+  const ps = windowsPowershell(detach, env)
+  const base = { ok: true, how: 'task', linger: null }
+  if (!ps) return { ...base, ok: false, on: false, message: 'Windows PowerShell is not reachable from this WSL distro' }
+  const ask = async (script) => {
+    const r = await run(ps, ['-NoProfile', '-NonInteractive', '-EncodedCommand', Buffer.from(script, 'utf16le').toString('base64')], env)
+    const a = parseTaskAnswer(r.stdout)
+    return a.ok || r.stdout.trim() || !r.stderr.trim() ? a : { ok: false, message: r.stderr.trim().split(/\r?\n/).at(-1) }
+  }
+  if (action === 'status') {
+    const a = await ask(taskScript('status', { name }))
+    if (!a.ok) return { ...base, ok: false, on: readAutostartMark(dataDir)?.how === 'task', message: `Task Scheduler did not answer: ${a.message}` }
+    const on = a.word !== 'none' && a.word !== 'Disabled'
+    if (on) writeAutostartMark(dataDir, { how: 'task', name, linger: null })
+    else clearAutostartMark(dataDir)
+    return { ...base, on }
+  }
+  if (action === 'off') {
+    const a = await ask(taskScript('off', { name }))
+    if (!a.ok) return { ...base, ok: false, on: true, message: `Task Scheduler did not remove the task "${name}": ${a.message}` }
+    clearAutostartMark(dataDir)
+    return { ...base, on: false }
+  }
+  const launcher = autostartLauncher(dataDir, platform)
+  if (!launcher) return { ...base, ok: false, on: false, message: `there is no Centralu launcher in ${dataDir} to start at sign-in` }
+  const runScript = taskActionScript({ how: detach, launcher, env, distro: env.WSL_DISTRO_NAME ?? null, user })
+  const a = await ask(taskScript('on', { name, run: runScript }))
+  if (!a.ok) return { ...base, ok: false, on: false, message: `Task Scheduler did not take the task: ${a.message}` }
+  writeAutostartMark(dataDir, { how: 'task', name, linger: null })
+  return { ...base, on: true }
+}
+
+/**
+ * `centralu serve --autostart on|off|status` (docs/plans/remote-hub.md §10.4, owner decision 4: per
+ * machine, off by default). The hub runs it over ssh for the Settings → Machines toggle, and its
+ * uninstall runs `off`. Turning it on or off never starts or stops a host: one runs already when the
+ * hub asks (the link started it), and the entry is for the next boot.
+ *
+ * stdout: one line, `{ v: 1, autostart: { ok, on, how, linger, message? } }`; `how` null where this
+ * machine offers nothing (`autostartHow`). `run` (a command runner) and `how` are parameters so
+ * tests never reach the real systemd or Task Scheduler.
+ */
+export async function runAutostart({
+  env,
+  home,
+  action,
+  cliPath,
+  platform = process.platform,
+  interop = wslInterop,
+  how = autostartHow(platform, env, { interop }),
+  run = runCaptured,
+  user = userInfo().username,
+  write = (line) => process.stdout.write(line),
+}) {
+  const dataDir = serveDataDir(env, home)
+  // The entry of an npm install runs the launcher serve keeps; make sure it is there and current
+  keepLauncher(dataDir, cliPath, env)
+  const report = (a) => {
+    if (a.message) say(a.message)
+    write(`${JSON.stringify({ v: 1, autostart: a })}\n`)
+    return a.ok ? 0 : 1
+  }
+  if (how === null) {
+    clearAutostartMark(dataDir)
+    return report({ ok: action !== 'on', on: false, how: null, linger: null, ...(action === 'off' ? {} : { message: autostartUnsupported(platform, env) }) })
+  }
+  try {
+    const name = autostartName(how, { dataDir, home, env, platform })
+    const opts = { dataDir, env, home, name, run, user, platform, interop }
+    return report(how === 'systemd' ? await systemdAutostart(action, opts) : await taskAutostart(action, opts))
+  } catch (e) {
+    return report({ ok: false, on: readAutostartMark(dataDir)?.how === how, how, linger: null, message: e?.message ?? String(e) })
+  }
+}

package/bin/swap.mjs

@@ -0,0 +1,48 @@
+/**
+ * Replacing an installed copy of the app without a moment where there is none.
+ *
+ * Lives apart from `centralu.mjs` for the same reason `platform.mjs` does: the launcher runs a
+ * command at import time, so a test cannot import it. The paths come in as arguments, so
+ * `tooling/launcher-swap.test.ts` runs this against temporary folders instead of `/Applications`.
+ */
+import { existsSync, renameSync, rmSync } from 'node:fs'
+
+/**
+ * Puts a new copy at `target`: `fill(staging)` writes it beside the old one, the old one is
+ * renamed aside, the new one is renamed in, and only then is the old one deleted.
+ *
+ * The old copy is never deleted before the new one is complete. Deleting first and copying
+ * after left a person whose copy failed (a full disk, a permission, an interrupted `ditto`)
+ * with no app at all, from a command they ran to update it. A copy that fails here leaves the
+ * old install untouched, and a rename that fails puts the old one back.
+ *
+ * Returns whether something was replaced, and where the old copy was left if it could not be
+ * deleted (null when it was).
+ */
+export function swapInto(target, fill, now = Date.now()) {
+  const staging = `${target}.new`
+  const aside = `${target}.old-${now}`
+  rmSync(staging, { recursive: true, force: true })
+  try {
+    fill(staging)
+  } catch (e) {
+    rmSync(staging, { recursive: true, force: true })
+    throw e
+  }
+  const replaced = existsSync(target)
+  if (replaced) renameSync(target, aside)
+  try {
+    renameSync(staging, target)
+  } catch (e) {
+    if (replaced) renameSync(aside, target)
+    rmSync(staging, { recursive: true, force: true })
+    throw e
+  }
+  if (!replaced) return { replaced, leftAt: null }
+  try {
+    rmSync(aside, { recursive: true, force: true })
+    return { replaced, leftAt: null }
+  } catch {
+    return { replaced, leftAt: aside }
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "centralu",
-  "version": "0.1.0-beta.13",
+  "version": "0.1.0-beta.15",
   "description": "Run, watch and steer several Claude Code and Codex CLI sessions from one window",
   "license": "MIT",
   "author": "ijun17",
@@ -37,9 +37,9 @@
     "win32"
   ],
   "optionalDependencies": {
-    "@centralu/darwin-arm64": "0.1.0-beta.13",
-    "@centralu/linux-arm64": "0.1.0-beta.13",
-    "@centralu/linux-x64": "0.1.0-beta.13",
-    "@centralu/win32-x64": "0.1.0-beta.13"
+    "@centralu/darwin-arm64": "0.1.0-beta.15",
+    "@centralu/linux-arm64": "0.1.0-beta.15",
+    "@centralu/linux-x64": "0.1.0-beta.15",
+    "@centralu/win32-x64": "0.1.0-beta.15"
   }
 }