@curia-sh/cli 0.4.1

package/src/stage.mjs

@@ -0,0 +1,141 @@
+import { chmodSync, cpSync, existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, statSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { pathToFileURL } from 'node:url'
+
+import { Refusal } from './exit.mjs'
+import { readArchive } from './archive.mjs'
+import { operatorConfigPath } from './config.mjs'
+import { verifyStagedRelease } from './manifest.mjs'
+import { versionPaths } from './root.mjs'
+
+// How one release lands under versions/<version>/ (#873, lifted for #883).
+//
+// A stage is a directory that holds the seven files a complete version is
+// made of: the unpacked runtime, the unpacked package, and the three retained
+// artifacts the doctor re-verifies. The bootstrap builds one in a temporary
+// directory for `curia install`; `curia update` builds one itself from the
+// network. Either way `placeVersion` is the one door from a stage to an
+// installed version: the artifacts are verified against the release
+// manifest, copied into a sibling of the version directory, made read-only,
+// and renamed into place, so `versions/<version>/` is either absent, the
+// previous complete one, or the new complete one, never half of one.
+
+export const STAGE_FILES = Object.freeze(['node/bin/node', 'cli/bin/curia.mjs', 'cli/package.json', 'cli/manifest.json', 'cli.tgz', 'bundle.tar.gz', 'bundle.tar.gz.sha256'])
+
+// Whether `dir` holds every file of a complete version.
+export function isCompleteStage(dir) {
+  return STAGE_FILES.every((f) => existsSync(join(dir, f)))
+}
+
+// The version the staged package names.
+export function stagedVersion(stage) {
+  return JSON.parse(readFileSync(join(stage, 'cli', 'package.json'), 'utf8')).version
+}
+
+// Verifies the stage and lands it as versions/<version>/, replacing that
+// directory if it was there. Returns the version's paths.
+export async function placeVersion({ root, version, stage, stdout }, release) {
+  for (const f of STAGE_FILES) {
+    if (!existsSync(join(stage, f))) throw new Refusal(`the stage ${stage} lacks ${f}. Run the command again; it downloads a complete stage.`)
+  }
+  const staged = stagedVersion(stage)
+  if (staged !== version) {
+    throw new Refusal(`the stage holds @curia-sh/cli ${staged}, but ${version} was selected. Run the command again so it stages one version end to end.`)
+  }
+  stdout.write(`verifying the staged release ${version}\n`)
+  await verifyRetained({ version, dir: stage, stdout }, release)
+
+  const paths = versionPaths(root, version)
+  const compose = composeFrom(readFileSync(join(stage, 'bundle.tar.gz')), version)
+  const staging = join(root, 'versions', `.${version}.${process.pid}.staging`)
+  rmSync(staging, { recursive: true, force: true })
+  mkdirSync(staging, { mode: 0o700 })
+  try {
+    for (const name of ['node', 'cli']) cpSync(join(stage, name), join(staging, name), { recursive: true, verbatimSymlinks: true })
+    for (const name of ['cli.tgz', 'bundle.tar.gz', 'bundle.tar.gz.sha256']) cpSync(join(stage, name), join(staging, name))
+    mkdirSync(join(staging, 'bundle'), { mode: 0o700 })
+    writeFileSync(join(staging, 'bundle', 'compose.yaml'), compose)
+    makeReadOnly(staging)
+    if (existsSync(paths.dir)) {
+      stdout.write(`replacing ${paths.dir}\n`)
+      rmSync(paths.dir, { recursive: true, force: true })
+    }
+    renameSync(staging, paths.dir)
+  } catch (e) {
+    rmSync(staging, { recursive: true, force: true })
+    throw e
+  }
+  stdout.write(`installed ${version} under ${paths.dir}\n`)
+  return paths
+}
+
+// The retained artifacts of one directory (a stage or an installed version)
+// through the release door. Throws the refusal when a check fails.
+export async function verifyRetained({ version, dir, stdout }, release) {
+  const report = await verifyStagedRelease({
+    version,
+    tarball: readFileSync(join(dir, 'cli.tgz')),
+    archive: readFileSync(join(dir, 'bundle.tar.gz')),
+    checksum: readFileSync(join(dir, 'bundle.tar.gz.sha256'), 'utf8'),
+  }, { stdout }, release)
+  if (!report.ok) throw report.refusal
+}
+
+// A release validates the current operator configuration with its own
+// reader (#883, lifted for #885): the package's `src/config.mjs` under
+// versions/<version>/, imported from there, and its `readOperatorConfig` on
+// `config/config.yaml`. That is how `curia update` learns that the target
+// accepts the configuration before anything switches, and how `curia
+// rollback` learns that the rollback release still reads it. Nothing is
+// written. A release that refuses the file throws an `IncompatibleRelease`
+// whose `reason` is `configuration`, with the contract's own sentence; a
+// release that carries no reader cannot validate and throws one whose
+// `reason` is `reader`. The caller adds the action that fits its command.
+export class IncompatibleRelease extends Error {
+  constructor(message, reason) {
+    super(message)
+    this.name = 'IncompatibleRelease'
+    this.reason = reason
+  }
+}
+
+export async function validateWithRelease({ root, version, dir = versionPaths(root, version).dir }) {
+  const reader = join(dir, 'cli', 'src', 'config.mjs')
+  if (!existsSync(reader)) {
+    throw new IncompatibleRelease(`${version} carries no operator configuration reader (cli/src/config.mjs), so it cannot validate the current configuration.`, 'reader')
+  }
+  const release = await import(pathToFileURL(reader).href)
+  if (typeof release.readOperatorConfig !== 'function') {
+    throw new IncompatibleRelease(`${version}'s configuration reader has no readOperatorConfig, so it cannot validate the current configuration.`, 'reader')
+  }
+  try {
+    release.readOperatorConfig(operatorConfigPath(root))
+  } catch (e) {
+    if (e?.name !== 'ConfigError') throw e
+    throw new IncompatibleRelease(`${version} refuses the current operator configuration: ${e.message}.`, 'configuration')
+  }
+}
+
+// The one file the verified bundle archive holds.
+function composeFrom(archive, version) {
+  const files = readArchive(archive)
+  const compose = files.get(`curia-bundle-${version}/compose.yaml`)
+  if (!compose) throw new Error(`the bundle archive holds no curia-bundle-${version}/compose.yaml`)
+  return compose.toString('utf8')
+}
+
+// Verified artifacts become read-only: every file loses its write bits and
+// keeps its execute bits, so the runtime still runs. Directories stay 0700,
+// which is what lets a reinstall or an update replace the version as a whole.
+function makeReadOnly(dir) {
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    const path = join(dir, entry.name)
+    if (entry.isSymbolicLink()) continue
+    if (entry.isDirectory()) {
+      makeReadOnly(path)
+      chmodSync(path, 0o700)
+    } else {
+      chmodSync(path, (statSync(path).mode & 0o555) | 0o400)
+    }
+  }
+}

package/src/steps.mjs

@@ -0,0 +1,25 @@
+import { Refusal } from './exit.mjs'
+
+// The named steps of one lifecycle command (#873's shape, lifted for #885):
+// each step is printed as `[n/N] <name>` when it begins, and an error that
+// escapes a step is turned into one that names the step. A `Refusal` keeps
+// its class and exit code and gains the step's name; any other error becomes
+// `<step> failed: <cause>` followed by the line that says how to run the
+// step again. Every command that has steps says the same things the same
+// way, so an operator reads one shape.
+export function namedSteps({ steps, stdout, rerun }) {
+  let current = null
+  return {
+    begin(name) {
+      current = name
+      stdout.write(`[${steps.indexOf(name) + 1}/${steps.length}] ${name}\n`)
+    },
+    wrap(e) {
+      if (current === null) return e
+      if (e instanceof Refusal) return new Refusal(`${current}: ${e.message}`)
+      const wrapped = new Error(`${current} failed: ${e.message}\n${rerun(current)}`)
+      wrapped.cause = e
+      return wrapped
+    },
+  }
+}

package/src/switch.mjs

@@ -0,0 +1,199 @@
+import { readdirSync, rmSync } from 'node:fs'
+import { join } from 'node:path'
+
+import { HEALTH_POLL_MS, compose, composeProject, dockerRunner, waitForHealth, writeComposeEnvironment } from './compose.mjs'
+import { APP_PORT, SERVICE_PORT } from './doctor.mjs'
+import { writeInstallationRecord } from './root.mjs'
+
+// The switch of a live installation from one installed release to another
+// (#884, implementing #854), the one door `curia update` and `curia
+// rollback` (#885) share.
+//
+// Both releases are complete under versions/<version>/, the target is
+// validated, and the caller holds the lifecycle lock. What happens here:
+//
+//   1. The live sessions are read from the running service (`GET /overview`
+//      on loopback): every agent whose tmux pane is live. That is the list
+//      the recreated service must adopt back.
+//   2. `run/compose.env` is rewritten with the same values, the target's
+//      images are pulled by digest, and the core services (the service, the
+//      app, and the overseer) are recreated from the target's bundle with
+//      `up --detach --no-deps`. The tmux runtime, the attach surface, and
+//      every agent container keep running: they are not named, `--no-deps`
+//      keeps Compose off the runtime the service depends on, and nothing
+//      removes orphans. An agent keeps the image it started on; the
+//      recreated service builds the target's agent image for the next
+//      spawn. The overseer comes back beside the service, which is the
+//      shape its replay of an interrupted turn was built for (ADR-0015).
+//   3. Acceptance: every declared service reports healthy, the service and
+//      the app report the target version on their `/ping` routes, and every
+//      live session from step 1 is adopted by the recreated service's
+//      reconcile, read from `/overview` until it settles or the deadline
+//      passes. A session that vanished from tmux meanwhile ended on its
+//      own and is reported, not failed.
+//   4. Activation: the installation record names the target, through one
+//      atomic write, and every directory under versions/ other than the
+//      target and the release that was active is removed. The release that
+//      was active is the one rollback release.
+//
+// A failure anywhere after the recreate switches the core services back to
+// the release that was active, once, and proves that release the same way:
+// its health, its version on both `/ping` routes, and the same live
+// sessions adopted back. Then it reports both outcomes. Nothing runs the
+// target a second time, and nothing runs the switch back a second time: a
+// switch back that fails its own proof is reported as failed too, with the
+// reinstall as the way out. The record is untouched by a failure: it names
+// the target only after acceptance, so the launcher and the service's own
+// reads follow the switch and never a half of one. The staged target stays
+// under versions/ for the rerun.
+//
+// Docker is reached through `compose.mjs` and its injectable runner; the
+// service and the app through an injectable `fetch`. Nothing here prints or
+// reads a secret.
+
+export const CORE_SERVICES = Object.freeze(['daemon', 'dashboard', 'overseer'])
+
+
+// How long the recreated service may take to report the target version and
+// adopt every live session, counted after its health check passed. The boot
+// reconcile reads GitHub once per live ticket, so a fleet of a dozen agents
+// on a slow origin needs a minute; two is the bound.
+export const READOPTION_TIMEOUT_MS = 120_000
+const READ_TIMEOUT_MS = 10_000
+
+export class SwitchError extends Error {
+  constructor(message) {
+    super(message)
+    this.name = 'SwitchError'
+  }
+}
+
+// Switches the core services from `from` to `to` and records `to` active.
+// `record` is the installation record as it stands; `environment` is what
+// `run/compose.env` carries (`uid`, `gid`, `dockerGid`, `installationId`).
+// Returns what was re-adopted. Throws a `SwitchError` that says what failed
+// and where the installation stands.
+export async function switchRelease(
+  { root, from, to, record, environment, stdout },
+  { docker = dockerRunner, fetch: fetchImpl = globalThis.fetch, sleep = (ms) => new Promise((r) => setTimeout(r, ms)), now = Date.now } = {},
+) {
+  const say = (text) => stdout.write(`${text}\n`)
+  const read = reader(fetchImpl)
+  const target = composeProject({ root, version: to })
+  const previous = composeProject({ root, version: from })
+
+  // 1. What is live now, from the service that is about to be recreated.
+  const live = await liveSessions(read)
+  if (live === null) say('the service did not answer before the switch, so no live session is expected back')
+  else if (live.length === 0) say('no live session to re-adopt')
+  else say(`${live.length} live ${live.length === 1 ? 'session' : 'sessions'} to re-adopt after the switch: ${live.join(', ')}`)
+
+  // 2. The recreate.
+  writeComposeEnvironment(target, environment)
+  say(`pulling the images of ${to} by digest`)
+  await compose(target, ['pull', ...CORE_SERVICES], { docker })
+  say(`recreating ${CORE_SERVICES.join(', ')} from ${to}; tmux, ttyd, and the agent containers keep running`)
+  say('an agent keeps the image it started on; the next agent uses the image of the target release')
+  say('the overseer replays a turn the switch interrupted, as it does after any restart')
+  await compose(target, ['up', '--detach', '--no-deps', ...CORE_SERVICES], { docker })
+
+  // 3. Acceptance, then 4. activation. A failure past the recreate goes back.
+  let adopted
+  try {
+    await waitForHealth(target, { docker, sleep, now, stdout })
+    adopted = await acceptRecreated({ to, live, read, sleep, now, say })
+    writeInstallationRecord(root, { ...record, activeVersion: to })
+  } catch (e) {
+    throw await switchBack({ previous, from, live, read, docker, sleep, now, stdout, cause: e })
+  }
+  say(`${to} is the active version; ${from} is kept for 'curia rollback'`)
+  for (const other of readdirSync(join(root, 'versions'))) {
+    if (other === to || other === from) continue
+    rmSync(join(root, 'versions', other), { recursive: true, force: true })
+    if (!other.startsWith('.')) say(`removed ${other}, which is no longer a rollback release`)
+  }
+  return adopted
+}
+
+// The sessions whose tmux pane is live, as the running service reports
+// them, or null when the service does not answer.
+export async function liveSessions(read) {
+  const overview = await read.json(`http://127.0.0.1:${SERVICE_PORT}/overview`)
+  if (!overview.ok || !Array.isArray(overview.body?.agents)) return null
+  return overview.body.agents.filter((a) => a?.tmux_live === true).map((a) => String(a.session)).sort()
+}
+
+// The recreated service must say the target version, the app must say it
+// too, and every live session must be adopted. The version reads settle at
+// once (a healthy service answers its version on the first read); the
+// adoption settles when the boot reconcile has run, which the listener
+// answers before. So the loop polls until the fleet is determinate and
+// every session is either adopted or gone, and fails at the deadline on the
+// first one still unadopted.
+async function acceptRecreated({ to, live, read, sleep, now, say }) {
+  const service = await read.json(`http://127.0.0.1:${SERVICE_PORT}/ping`)
+  const app = await read.json(`http://127.0.0.1:${APP_PORT}/ping`)
+  const reported = (answer) => (answer.ok ? String(answer.body?.version ?? 'no version') : `no answer (${answer.error})`)
+  if (!service.ok || service.body?.version !== to || !app.ok || app.body?.version !== to) {
+    throw new SwitchError(`the service reports ${reported(service)} and the Curia app reports ${reported(app)}, not ${to}.`)
+  }
+  say(`the service reports ${to} and the Curia app reports ${to}`)
+
+  if (live === null || live.length === 0) return { adopted: [], ended: [] }
+  const started = now()
+  for (;;) {
+    const overview = await read.json(`http://127.0.0.1:${SERVICE_PORT}/overview`)
+    const agents = overview.ok && Array.isArray(overview.body?.agents) ? overview.body.agents : null
+    if (agents !== null) {
+      const untracked = new Set(Array.isArray(overview.body.untracked) ? overview.body.untracked.map(String) : [])
+      const adopted = live.filter((s) => agents.some((a) => String(a?.session) === s && a.tmux_live === true))
+      const ended = live.filter((s) => !adopted.includes(s) && !untracked.has(s))
+      const pending = live.filter((s) => !adopted.includes(s) && !ended.includes(s))
+      if (pending.length === 0) {
+        if (adopted.length > 0) say(`re-adopted ${adopted.length} live ${adopted.length === 1 ? 'session' : 'sessions'}: ${adopted.join(', ')}`)
+        for (const s of ended) say(`${s} ended during the switch; nothing to re-adopt`)
+        return { adopted, ended }
+      }
+      if (now() - started >= READOPTION_TIMEOUT_MS) {
+        throw new SwitchError(`${to} did not re-adopt ${pending[0]} within ${Math.round(READOPTION_TIMEOUT_MS / 1000)} seconds: its pane is live and the service does not track it.`)
+      }
+    } else if (now() - started >= READOPTION_TIMEOUT_MS) {
+      throw new SwitchError(`${to} did not report its agents within ${Math.round(READOPTION_TIMEOUT_MS / 1000)} seconds, so the ${live.length} live ${live.length === 1 ? 'session was' : 'sessions were'} not proven re-adopted.`)
+    }
+    await sleep(HEALTH_POLL_MS)
+  }
+}
+
+// One switch back to the release that was active, proven the way the target
+// was (health, version, re-adoption of the same live sessions), then the
+// failure that names both outcomes. The record was never changed.
+async function switchBack({ previous, from, live, read, docker, sleep, now, stdout, cause }) {
+  const say = (text) => stdout.write(`${text}\n`)
+  say(`switching back to ${from}`)
+  let adopted
+  try {
+    await compose(previous, ['up', '--detach', '--no-deps', ...CORE_SERVICES], { docker })
+    await waitForHealth(previous, { docker, sleep, now, stdout })
+    adopted = await acceptRecreated({ to: from, live, read, sleep, now, say })
+  } catch (e) {
+    return new SwitchError(`${cause.message} The switch back to ${from} failed too: ${e.message} The record still names ${from}; run 'curia reinstall' to start it again, or read the logs first.`)
+  }
+  const n = adopted.adopted.length
+  const readopted = n === 0 ? '' : ` and re-adopted ${n} live ${n === 1 ? 'session' : 'sessions'}`
+  return new SwitchError(`${cause.message} Switched back to ${from}, which is healthy${readopted}. The record still names ${from}.`)
+}
+
+// A JSON read that answers instead of throwing.
+function reader(fetchImpl) {
+  return {
+    async json(url) {
+      try {
+        const response = await fetchImpl(url, { redirect: 'manual', signal: AbortSignal.timeout(READ_TIMEOUT_MS) })
+        if (!response.ok) return { ok: false, error: `HTTP ${response.status}` }
+        return { ok: true, body: await response.json() }
+      } catch (e) {
+        return { ok: false, error: String(e.cause?.message ?? e.message).split('\n')[0] }
+      }
+    },
+  }
+}

package/src/tailscale.mjs

@@ -0,0 +1,156 @@
+import { execFile } from 'node:child_process'
+import { lstatSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+import { writeAtomically } from './atomic.mjs'
+
+// The Tailscale record of an installation and Curia's own Serve routes
+// (#877 wrote the record; #886 withdraws the routes).
+//
+// `state/tailscale.json` holds the allowed operator, the machine name the
+// operator expects, and the Serve routes Curia created. Nothing in it is a
+// secret. The service (`daemon/src/tailscalesetup.mjs`) writes it during
+// integration setup and reads it at boot; the lifecycle interface reads it
+// at uninstall and purge to withdraw exactly the routes Curia created and no
+// other. One reader and one writer live here, dependency-free, and the
+// service imports them by relative path the way it imports `config.mjs`.
+//
+// CURIA DETECTS TAILSCALE AND NEVER CHANGES IT, except for its own routes.
+// `withdrawServeRoutes` reads what the node serves, turns off only a recorded
+// route that is standing, and leaves every other route alone. A route that
+// is no longer standing is nothing to do, so a rerun is quiet.
+
+export const TAILSCALE_FILE = 'tailscale.json'
+export const tailscalePath = (stateDir) => join(stateDir, TAILSCALE_FILE)
+
+// A Tailscale login as Serve stamps it: an email-shaped identity, or a
+// GitHub-style `name@github` handle. Bounded, and never whitespace.
+export const LOGIN_RE = /^[A-Za-z0-9][A-Za-z0-9._+-]{0,127}@[A-Za-z0-9][A-Za-z0-9.-]{0,127}$/
+// The machine name the operator types, the same shape `state/setup.json` keeps.
+export const MACHINE_NAME_RE = /^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?(\.[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?)*$/i
+
+const EMPTY = () => ({ operator: null, machine_name: null, serve: [] })
+
+function checked(data, source) {
+  if (!data || typeof data !== 'object' || Array.isArray(data)) throw new Error(`${source}: not a mapping`)
+  for (const key of Object.keys(data)) {
+    if (!['format', 'operator', 'machine_name', 'serve'].includes(key)) throw new Error(`${source}: unknown key ${key}`)
+  }
+  let operator = null
+  if (data.operator !== null && data.operator !== undefined) {
+    const op = data.operator
+    if (!op || typeof op !== 'object' || typeof op.login !== 'string' || !LOGIN_RE.test(op.login)) {
+      throw new Error(`${source}: operator.login must be a Tailscale login`)
+    }
+    operator = { login: op.login.toLowerCase(), confirmed_at: typeof op.confirmed_at === 'string' ? op.confirmed_at : null }
+  }
+  const machine = data.machine_name ?? null
+  if (machine !== null && (typeof machine !== 'string' || !MACHINE_NAME_RE.test(machine))) {
+    throw new Error(`${source}: machine_name must be a machine name or absent`)
+  }
+  const serve = data.serve ?? []
+  if (!Array.isArray(serve) || serve.some((r) => !r || !Number.isInteger(r.https) || typeof r.target !== 'string')) {
+    throw new Error(`${source}: serve must be a list of { https, target } routes`)
+  }
+  return { operator, machine_name: machine, serve: serve.map((r) => ({ https: r.https, target: r.target })) }
+}
+
+// The record, or the empty answer when there is no file: no operator is
+// recorded, which is what a fresh installation runs until setup writes it.
+export function readTailscaleRecord(stateDir) {
+  const file = tailscalePath(stateDir)
+  let text
+  try {
+    if (lstatSync(file).isSymbolicLink()) throw new Error(`${file} is a symbolic link. Replace the link with the real file.`)
+    text = readFileSync(file, 'utf8')
+  } catch (e) {
+    if (e.code === 'ENOENT') return EMPTY()
+    throw e
+  }
+  let data
+  try {
+    data = JSON.parse(text)
+  } catch {
+    throw new Error(`${file}: not JSON`)
+  }
+  return checked(data, file)
+}
+
+export function writeTailscaleRecord(stateDir, data) {
+  const record = checked(data, tailscalePath(stateDir))
+  writeAtomically(tailscalePath(stateDir), `${JSON.stringify({ format: 1, ...record }, null, 2)}\n`, { mode: 0o600 })
+  return record
+}
+
+// The routes in a `tailscale serve status --json` answer, which is the
+// node's whole serve config: `{ Web: { "<host>:<port>": { Handlers: { "/":
+// { Proxy } } } } }`.
+export function serveRoutes(config) {
+  const out = []
+  for (const [hostPort, site] of Object.entries(config?.Web ?? {})) {
+    const port = Number(hostPort.split(':').pop())
+    for (const [mount, handler] of Object.entries(site?.Handlers ?? {})) {
+      if (handler?.Proxy) out.push({ https: port, mount, target: String(handler.Proxy) })
+    }
+  }
+  return out
+}
+
+// The real `tailscale` CLI, the same shape as `dockerRunner` in compose.mjs:
+// one invocation, output captured, never a throw.
+export const tailscaleRunner = (args, { timeoutMs = 60_000 } = {}) => new Promise((resolve) => {
+  execFile('tailscale', args, { timeout: timeoutMs, maxBuffer: 8 * 1024 * 1024 }, (error, stdout, stderr) => {
+    if (!error) return resolve({ ok: true, stdout, stderr, code: 0 })
+    resolve({ ok: false, stdout, stderr: stderr || error.message, code: error.code, missing: error.code === 'ENOENT', timedOut: Boolean(error.killed) })
+  })
+})
+
+export class TailscaleError extends Error {
+  constructor(message) {
+    super(message)
+    this.name = 'TailscaleError'
+  }
+}
+
+// Withdraws the Serve routes the record under `stateDir` names, and no
+// other. Returns `{ recorded, withdrawn, absent, unreachable }`: the
+// recorded routes, the ones turned off on this call, the ones that were not
+// standing, and whether the node could be asked at all. The `tailscale`
+// command missing from the path counts every route as absent and the node
+// as unreachable: with no CLI there is no node this operator can reach, and
+// the record is kept for the next run that can. A node that answers with an
+// error fails, because a route may still stand.
+export async function withdrawServeRoutes({ stateDir, stdout }, { tailscale = tailscaleRunner } = {}) {
+  const recorded = readTailscaleRecord(stateDir).serve
+  if (recorded.length === 0) return { recorded, withdrawn: [], absent: [], unreachable: false }
+
+  const status = await tailscale(['serve', 'status', '--json'])
+  if (!status.ok && status.missing) {
+    stdout?.write(`the tailscale command is not on the path, so no Serve route is withdrawn; the record keeps ${recorded.length === 1 ? 'the route' : 'the routes'} for a host that runs Tailscale\n`)
+    return { recorded, withdrawn: [], absent: recorded, unreachable: true }
+  }
+  if (!status.ok) throw new TailscaleError(`tailscale serve status failed: ${firstLine(status.stderr || status.stdout) || `exit ${status.code}`}`)
+  let standing
+  try {
+    standing = serveRoutes(JSON.parse(status.stdout.trim() || '{}'))
+  } catch {
+    throw new TailscaleError('tailscale serve status --json did not answer JSON')
+  }
+
+  const withdrawn = []
+  const absent = []
+  for (const route of recorded) {
+    const stands = standing.some((s) => s.https === route.https && s.target === route.target)
+    if (!stands) {
+      absent.push(route)
+      continue
+    }
+    const off = await tailscale(['serve', `--https=${route.https}`, 'off'])
+    if (!off.ok) throw new TailscaleError(`tailscale serve --https=${route.https} off failed: ${firstLine(off.stderr || off.stdout) || `exit ${off.code}`}`)
+    stdout?.write(`withdrew the Serve route https://:${route.https} -> ${route.target}\n`)
+    withdrawn.push(route)
+  }
+  return { recorded, withdrawn, absent, unreachable: false }
+}
+
+const firstLine = (text) => String(text ?? '').trim().split('\n')[0]