create-walle 0.10.2 → 0.10.3

package/template/coding-task-manager/lib/fleet-update.js

@@ -0,0 +1,798 @@
+'use strict';
+
+// WP-0 (docs/fleet-auto-update-pooled-machines-2026-10-26.html §5.1, §6, §8 WP-0, §9 S-1..S-4):
+// the version truth both sides of the fleet need.
+//
+//   * HUB side — `readHubTarget()`: the sha of the hub repo's local `refs/heads/main`, which is the
+//     fleet's target (D-1: the user works on local main and never auto-pushes). Memoized for 15 s so
+//     a sweep over N boxes runs `git` once, and a git failure reads `''` (never a throw into an HTTP
+//     handler).
+//   * BOX side — `readFleetStatus()`: what this checkout IS, so a hub can decide eligibility
+//     (channel / branch / clean) and so the box's own Machines card can say "current" or "N behind".
+//
+// Eligibility is deliberately NOT a stored setting (lead decision 2026-10-26, dropping doc S-5):
+// a box is eligible iff its checkout is the git channel, on `main`, with a clean tree. There is no
+// `autoUpdate` machine-self flag anywhere in this module or the routes it feeds.
+//
+// Every git call goes through `execFile` (never a shell string, never a `-C` interpolated into a
+// command line) with a 5 s timeout, and `runGit` is injectable so tests drive a real temp repo — or
+// a counter — without a shell. The module owns no timer: the memo is a plain timestamp compare.
+
+const { isSystemdService } = require('./systemd-scope');
+const { execFile, spawn } = require('node:child_process');
+// The real launchers again, under a second name: `_spawnFleetApplyDetached`'s parameters are bound to
+// the literal call names (`execFile(...)`/`spawn(...)`) so bin/main-thread-lint.js keeps SEEING both
+// launch sites — a call written through an `*Impl` alias would be invisible to it, and an invisible
+// process launch is exactly what that ledger exists to prevent.
+const defaultExecFile = execFile;
+const defaultSpawn = spawn;
+const fsp = require('node:fs/promises');
+const fs = require('node:fs');
+const http = require('node:http');
+const path = require('node:path');
+// WP-3 (§6.2): the origin half of the status read reuses the landing machine's own readers — the
+// target-tree policy loader and the local tracking-ref status — so the box's card and `land status`
+// can never disagree about ahead/behind or the last sync verdict.
+
+/** Planner verdicts (WP-2). Frozen so a completeness test can iterate it. */
+const FLEET_REASONS = Object.freeze([
+  'current',
+  'not_git',
+  'not_main',
+  'dirty',
+  'diverged',
+  'unreachable',
+  'another_box_updating',
+  'already_attempted',
+  'cooldown',
+  'busy',
+  'behind',
+]);
+
+/** The box state machine's states (doc §5.3). A state file naming anything else reads as 'idle'. */
+const FLEET_STATES = Object.freeze(['idle', 'applying', 'waiting_idle', 'restarting', 'rolling_back']);
+
+/** The three lockfiles whose change forces a frozen install (D-6); `git diff --name-only` paths. */
+const FLEET_LOCKFILES = Object.freeze([
+  'package-lock.json',
+  'coding-task-manager/package-lock.json',
+  'wall-e/package-lock.json',
+]);
+
+/** 28× the measured worst live gap (2,324,240 B) — the bundle body cap (§9 S-6). */
+const FLEET_BUNDLE_MAX_BYTES = 64 * 1024 * 1024;
+
+const GIT_TIMEOUT_MS = 5000;
+/** `git bundle verify` / `git fetch <bundle>` are O(gap size), not O(1); 60 s is the §6 budget. */
+const GIT_BUNDLE_TIMEOUT_MS = 60000;
+const HUB_TARGET_MEMO_MS = 15000;
+
+/** The repo root holding `.git` — `lib/` is one level below it. */
+const DEFAULT_REPO_ROOT = path.resolve(__dirname, '..', '..');
+
+/**
+ * The production `git` runner: `execFile` with the args as an ARRAY (no shell), a 5 s timeout, and
+ * stdout trimmed. A non-zero exit rejects, which every caller below catches and reads as "unknown".
+ */
+function _execFileGit(args, { cwd, timeout = GIT_TIMEOUT_MS } = {}) {
+  return new Promise((resolve, reject) => {
+    execFile('git', args, { cwd, timeout }, (error, stdout) => {
+      if (error) { reject(error); return; }
+      resolve(String(stdout == null ? '' : stdout).trim());
+    });
+  });
+}
+
+/**
+ * One git call reduced to `{ code, stdout, stderr }` — never a throw. `runGit` has two legitimate
+ * shapes: the production runner above (rejects on a non-zero exit, with `error.stderr` attached by
+ * `execFile`) and a test double that returns stdout. Both are read here, so a caller that must look
+ * at an EXIT CODE (`git bundle verify`, `git merge-base --is-ancestor`) does not care which it got.
+ */
+async function _runGitResult(runGit, args, cwd, timeout) {
+  try {
+    const out = await runGit(args, { cwd, timeout });
+    if (out && typeof out === 'object' && Number.isInteger(out.code)) {
+      return { code: out.code, stdout: String(out.stdout == null ? '' : out.stdout), stderr: String(out.stderr == null ? '' : out.stderr) };
+    }
+    return { code: 0, stdout: String(out == null ? '' : out), stderr: '' };
+  } catch (error) {
+    const code = error && Number.isInteger(error.code) ? error.code : 1;
+    const stderr = error && (error.stderr != null ? String(error.stderr) : String(error.message || ''));
+    return { code, stdout: String((error && error.stdout) || ''), stderr };
+  }
+}
+
+// Module state by design (same contract as the registry's caches): repoRoot -> { sha, at }. The memo
+// dies with the process, and a stale sha is worthless — it is re-read every 15 s.
+const _hubTarget = new Map();
+
+/**
+ * D-1: the hub's fleet target — the full sha of its LOCAL `refs/heads/main`.
+ *
+ * Memoized for 15 s. Any git failure returns `''` and leaves the memo UNset (a zeroed stamp), so the
+ * very next call retries instead of serving a failure for the rest of the window. `now` is injectable
+ * so a test can move the clock without waiting.
+ */
+async function readHubTarget({ repoRoot = DEFAULT_REPO_ROOT, runGit = _execFileGit, now = Date.now } = {}) {
+  const at = Number(now()) || 0;
+  const memo = _hubTarget.get(repoRoot);
+  if (memo && at - memo.at < HUB_TARGET_MEMO_MS) return memo.sha;
+  let sha = '';
+  try {
+    sha = String((await runGit(['rev-parse', '--verify', 'refs/heads/main'], { cwd: repoRoot })) || '').trim();
+  } catch {
+    // HANDLE: no git, no repo, or no local main — this hub has no target to offer. Report '' rather
+    // than a half-truth, and drop the memo so the next read tries again.
+    sha = '';
+  }
+  if (!sha) { _hubTarget.delete(repoRoot); return ''; }
+  _hubTarget.set(repoRoot, { sha, at });
+  return sha;
+}
+
+/**
+ * One git read for the status below; a failure degrades THAT field, never the whole response.
+ * `runGit` may be the production string runner or a `{ code, stdout, stderr }` one (see
+ * `_runGitResult`); both spellings are unwrapped here so a caller can inject either.
+ */
+async function _git(runGit, repoRoot, args, fallback) {
+  try {
+    const out = await runGit(args, { cwd: repoRoot });
+    if (out && typeof out === 'object') return String(out.stdout == null ? fallback : out.stdout).trim();
+    return out == null ? fallback : String(out).trim();
+  } catch {
+    return fallback; // HANDLE: a missing/unreadable repo reads as unknown, not as a 500
+  }
+}
+
+/**
+ * S-4: this checkout's fleet-facing truth.
+ *
+ *   channel  'git' iff `git rev-parse --is-inside-work-tree` prints `true`, else 'unknown'. This is
+ *            the ONLY eligibility fact the lead's decision needs besides branch/clean.
+ *   head     the full sha on disk — differs from `runningSha` until the process restarts onto it.
+ *   clean    `git status --porcelain --untracked-files=no` is empty (untracked files never make a
+ *            box ineligible: they are not local work the update could overwrite).
+ *   guard    the restart guard's blocking count. Production passes `guardSnapshot` = server.js's
+ *            `_restartGuardSnapshot` — the exact verdict /api/instance/update-gate and
+ *            /api/restart/ctm use (hosted sessions + revive preflight included), so the hub and the
+ *            box can never disagree about idle. The bare summarizer is the unit-test fallback.
+ *
+ * `state`/`last` are the box state machine's (doc §5.3); WP-0 has no apply path yet, so they read
+ * the honest idle/never default.
+ *
+ * `originSync` (WP-3, docs/fleet-origin-main-sync-skill-2026-10-31.html §5 R-1, §6.2): the origin
+ * half of the same truth — `{ configured, follow, ahead, behind, fetchedAt, lastSync }`, read
+ * LOCAL-ONLY (a status read never fetches; `land sync` is what moves the tracking ref). A repository
+ * whose target tree carries no `landing.publish` block reads exactly `{ configured: false }`: the hub
+ * planner turns that fact into the `origin_sync` reason, so a self-syncing box is never bundled to.
+ */
+async function readFleetStatus({
+  repoRoot = DEFAULT_REPO_ROOT,
+  dataDir = '',
+  runningSha = '',
+  sessions = [],
+  runGit = _execFileGit,
+  summarizeGuard = require('./restart-guard').summarizeRestartGuard,
+  guardSnapshot = null,
+} = {}) {
+  const insideWorkTree = await _git(runGit, repoRoot, ['rev-parse', '--is-inside-work-tree'], '');
+  const channel = insideWorkTree === 'true' ? 'git' : 'unknown';
+  const head = String(await _git(runGit, repoRoot, ['rev-parse', 'HEAD'], '') || '');
+  const branch = String(await _git(runGit, repoRoot, ['rev-parse', '--abbrev-ref', 'HEAD'], '') || '');
+  const porcelain = await _git(runGit, repoRoot, ['status', '--porcelain', '--untracked-files=no'], null);
+  // null = the status read itself failed. Fail CLOSED (not clean): a box we cannot inspect is never
+  // a box we may write over (D-9).
+  const clean = porcelain === null ? false : porcelain === '';
+  const verdict = (typeof guardSnapshot === 'function' ? guardSnapshot() : summarizeGuard(sessions)) || {};
+  const state = await readFleetState(dataDir);
+  return {
+    channel,
+    head,
+    runningSha: String(runningSha == null ? '' : runningSha).trim(),
+    branch,
+    clean,
+    guard: { blockingCount: Number(verdict.blockingCount) || 0 },
+    state: state.state,
+    last: state.last,
+    originSync: await readOriginSync(repoRoot, runGit),
+  };
+}
+
+/**
+ * WP-3 (§5 R-1, §6.2): the origin half of `readFleetStatus`. The policy is the `.ctm.json` committed at the
+ * checkout's HEAD (a box that reports here is on main); ahead/behind come from the LOCAL tracking ref —
+ * this function performs no fetch and writes nothing, and uses only async git/fs (it runs on the request
+ * path of GET /api/fleet/status).
+ *
+ * Every failure collapses to `{ configured: false }`: a directory that is not a repository, a missing
+ * target branch, an unreadable/invalid `.ctm.json`, or no `landing.publish` block all mean "this box
+ * has no origin contract", which is the honest answer and never a 500 on the status route.
+ */
+async function readOriginSync(repoRoot, runGit = _execFileGit) {
+  // Async git + fsp only: this runs inside GET /api/fleet/status on CTM's main thread, so it must never
+  // block the event loop (the landing CLI's synchronous runner is fine in `land`, not here). Local refs
+  // only — never a fetch inside a status read.
+  const NOT = { configured: false };
+  const raw = await _git(runGit, repoRoot, ['show', 'HEAD:.ctm.json'], '');
+  if (!raw) return NOT;
+  let landing = null;
+  try {
+    const parsed = JSON.parse(raw);
+    landing = parsed && typeof parsed === 'object' ? parsed.landing : null;
+  } catch {
+    return NOT; // HANDLE: an unparsable .ctm.json is "not configured", never a 500
+  }
+  const publish = landing && typeof landing === 'object' ? landing.publish : null;
+  if (!publish || typeof publish !== 'object') return NOT;
+  const target = typeof landing.target === 'string' && landing.target ? landing.target : 'main';
+  const remote = typeof publish.remote === 'string' && publish.remote ? publish.remote : 'origin';
+  const branch = typeof publish.branch === 'string' && publish.branch ? publish.branch : 'main';
+  const common = await _git(runGit, repoRoot, ['rev-parse', '--path-format=absolute', '--git-common-dir'], '');
+  let state = {};
+  if (common) {
+    try {
+      const parsed = JSON.parse(await fsp.readFile(path.join(common, 'landing', 'sync-state.json'), 'utf8'));
+      if (parsed && typeof parsed === 'object') state = parsed;
+    } catch {
+      state = {}; // HANDLE: no sync has run yet (or the file is mid-rename) — no fetchedAt/lastSync
+    }
+  }
+  const counts = await _git(runGit, repoRoot,
+    ['rev-list', '--left-right', '--count', `refs/heads/${target}...refs/remotes/${remote}/${branch}`], '');
+  const [ahead, behind] = String(counts || '').split(/\s+/).map((value) => (value === '' ? NaN : Number(value)));
+  return {
+    configured: true,
+    follow: publish.follow !== false,
+    ahead: Number.isFinite(ahead) ? ahead : null,
+    behind: Number.isFinite(behind) ? behind : null,
+    fetchedAt: state.fetchedAt || null,
+    lastSync: state.lastSync || null,
+  };
+}
+
+// ── WP-1: the box state machine + the apply lock (doc §5.3, §9 S-6/S-7) ─────────────────────────
+//
+// Two files under <dataDir>/fleet carry the box's apply truth, and both are read by readFleetStatus:
+//   state.json  the state machine the Machines card renders (idle/applying/waiting_idle/restarting/
+//               rolling_back) plus the last terminal verdict. Missing or corrupt ⇒ the honest
+//               idle/never default — never a throw into an HTTP handler.
+//   apply.lock  a plain pid lock file (lead decision 2026-10-26, replacing the doc's
+//               acquireUpdateLease, which is bound to the npm release layout). `open(…, 'wx')` is
+//               the atomic claim; a lock whose pid is dead is stale and is reclaimed.
+//
+// The ROUTE holds the lock across the transfer and releases it just before it spawns the detached
+// helper, which takes the same lock for the apply itself — so "transferring" and "applying" are the
+// same serialization point (D-7), and D-6's one-box-at-a-time is enforced by the kernel, not by a
+// flag.
+
+/** `<dataDir>/fleet` — the apply state's one directory. */
+function fleetDir(dataDir) { return path.join(String(dataDir || ''), 'fleet'); }
+
+/** `<dataDir>/fleet/state.json` (mode 0600, written atomically). */
+function fleetStatePath(dataDir) { return path.join(fleetDir(dataDir), 'state.json'); }
+
+/** `<dataDir>/fleet/apply.lock` — the pid lock file (§3 step 1). */
+function fleetApplyLockPath(dataDir) { return path.join(fleetDir(dataDir), 'apply.lock'); }
+
+/**
+ * The box state machine as persisted. No `dataDir` (a unit test, or a box that never applied) reads
+ * the honest idle/never default; so does a file that is missing, unreadable, not JSON, or names a
+ * state this module does not know.
+ */
+async function readFleetState(dataDir) {
+  if (!dataDir) return { state: 'idle', last: null };
+  let parsed = null;
+  try {
+    parsed = JSON.parse(await fsp.readFile(fleetStatePath(dataDir), 'utf8'));
+  } catch {
+    // HANDLE: no state file yet, or a torn/unreadable one. "Never applied" is the truthful answer and
+    // is what the box reports before its first bundle; a 500 here would break a read-only card.
+    return { state: 'idle', last: null };
+  }
+  if (!parsed || typeof parsed !== 'object') return { state: 'idle', last: null };
+  return {
+    state: FLEET_STATES.includes(parsed.state) ? parsed.state : 'idle',
+    last: parsed.last && typeof parsed.last === 'object' ? parsed.last : null,
+  };
+}
+
+/** Atomic 0600 write: temp file in the same directory, then `rename` (§3 step 2). */
+async function writeFleetState(dataDir, value) {
+  const dir = fleetDir(dataDir);
+  await fsp.mkdir(dir, { recursive: true, mode: 0o700 });
+  const target = fleetStatePath(dataDir);
+  const tmp = path.join(dir, `.state.${process.pid}.${Date.now()}.tmp`);
+  await fsp.writeFile(tmp, JSON.stringify(value), { mode: 0o600 });
+  await fsp.rename(tmp, target);
+}
+
+/** The pid a lock file names, or 0 when it is absent/unreadable/garbage. */
+async function _readLockPid(lockPath) {
+  try {
+    const pid = Number.parseInt(String(await fsp.readFile(lockPath, 'utf8')).trim(), 10);
+    return Number.isInteger(pid) && pid > 0 ? pid : 0;
+  } catch {
+    return 0; // HANDLE: unreadable lock ⇒ unknown holder; the caller treats pid 0 as dead and reclaims
+  }
+}
+
+/** Signal 0 probe: EPERM means the pid exists but is not ours — that is still a LIVE holder. */
+function isPidAlive(pid) {
+  if (!pid) return false;
+  try { process.kill(pid, 0); return true; }
+  catch (error) { return !!error && error.code === 'EPERM'; }
+}
+
+/**
+ * Claim `<dataDir>/fleet/apply.lock`. `open(…, 'wx')` is atomic at the OS level, so two concurrent
+ * callers cannot both win; the loser reads the holder's pid and reports `live: true` (a real apply or
+ * transfer is in flight). A lock whose holder is DEAD is stale (§3 step 1) and is reclaimed once.
+ */
+async function acquireFleetApplyLock(dataDir) {
+  const dir = fleetDir(dataDir);
+  await fsp.mkdir(dir, { recursive: true, mode: 0o700 });
+  const lockPath = fleetApplyLockPath(dataDir);
+  for (let attempt = 0; attempt < 2; attempt += 1) {
+    try {
+      const handle = await fsp.open(lockPath, 'wx', 0o600);
+      try { await handle.writeFile(String(process.pid)); } finally { await handle.close(); }
+      return { ok: true, path: lockPath, pid: process.pid };
+    } catch (error) {
+      if (!error || error.code !== 'EEXIST') throw error;
+      const pid = await _readLockPid(lockPath);
+      if (isPidAlive(pid)) return { ok: false, live: true, pid, path: lockPath };
+      // The holder is gone (crash, kill -9, or a torn file): reclaim and retry ONCE.
+      try { await fsp.unlink(lockPath); } catch { /* expected: another reclaimer won the race; the retry below reports the truth */ }
+    }
+  }
+  const pid = await _readLockPid(lockPath);
+  return { ok: false, live: isPidAlive(pid), pid, path: lockPath };
+}
+
+/** Release a claim made by `acquireFleetApplyLock`. Missing is success (idempotent). */
+async function releaseFleetApplyLock(lock) {
+  if (!lock || !lock.path) return;
+  try { await fsp.unlink(lock.path); }
+  catch { /* expected: already released — the stale-reclaim path, or a double release */ }
+}
+
+/** An identity-preserving regex test for the `?to=` parameter (a full 40-hex sha). */
+function isFullSha(value) { return typeof value === 'string' && /^[0-9a-f]{40}$/.test(value); }
+
+/**
+ * Stream a binary request body to `filePath` with a hard byte cap (§9 S-6 — deliberately NOT
+ * `_readRawBody` from lib/remote-machine-proxy.js, which decodes the body into a string and is for
+ * proxied JSON). Resolves `{ ok: true, bytes }` or `{ ok: false, tooLarge | error }`; on any failure
+ * the partial file is unlinked, so a refused bundle never leaves anything behind.
+ */
+function _streamBodyToFile(req, filePath, maxBytes) {
+  return new Promise((resolve) => {
+    const out = fs.createWriteStream(filePath, { mode: 0o600 });
+    let bytes = 0;
+    let settled = false;
+    const settle = (result) => {
+      if (settled) return;
+      settled = true;
+      if (!result.ok) {
+        try { out.destroy(); } catch { /* expected: the write already failed and closed the stream */ }
+        if (typeof req.destroy === 'function') { try { req.destroy(); } catch { /* expected: the request already ended */ } }
+        void fsp.unlink(filePath).catch(() => { /* expected: nothing to unlink — the file was never created */ });
+      }
+      resolve(result);
+    };
+    out.on('error', (error) => settle({ ok: false, error, bytes }));
+    if (typeof req.on === 'function') {
+      req.on('error', (error) => settle({ ok: false, error, bytes }));
+      req.on('data', (chunk) => {
+        if (settled) return;
+        bytes += chunk.length;
+        if (bytes > maxBytes) { settle({ ok: false, tooLarge: true, bytes }); return; }
+        if (!out.write(chunk)) req.pause();
+      });
+      out.on('drain', () => { if (!settled && typeof req.resume === 'function') req.resume(); });
+      req.on('end', () => { if (!settled) out.end(() => settle({ ok: true, bytes })); });
+    }
+  });
+}
+
+/** The detached helper's log file: one per target, so a failed apply is diagnosable after the fact. */
+function fleetApplyLogPath(dataDir, to) { return path.join(fleetDir(dataDir), `apply-${String(to).slice(0, 12)}.log`); }
+
+/** `systemd-run` is a launcher, not the work: if it does not answer quickly, fall back (below). */
+const SYSTEMD_RUN_TIMEOUT_MS = 10000;
+
+/**
+ * The transient user unit the helper runs under on a systemd host (`ctm-fleet-apply-<to12>`), built as
+ * one argv array so the whole command is auditable and nothing goes through a shell (S-6).
+ *
+ * `local: true` is §8 WP-2b (`land sync` moved THIS box's own main): the flag goes BEFORE the sha, in
+ * the helper's own positional contract (`fleet-apply.js [--local] <to-sha>`).
+ */
+function systemdRunArgv(to, { repoRoot, dataDir, port, logPath, local = false }) {
+  return [
+    '--user',
+    '--collect',
+    '--quiet',
+    `--unit=ctm-fleet-apply-${String(to).slice(0, 12)}`,
+    `--working-directory=${repoRoot}`,
+    `--setenv=CTM_PORT=${port == null ? '' : port}`,
+    `--setenv=CTM_DATA_DIR=${dataDir}`,
+    '-p', `StandardOutput=append:${logPath}`,
+    '-p', `StandardError=append:${logPath}`,
+    process.execPath,
+    path.join(repoRoot, 'bin', 'fleet-apply.js'),
+    ...(local ? ['--local'] : []),
+    to,
+  ];
+}
+
+/**
+ * Default `spawnHelper`: start `bin/fleet-apply.js <to>` so it outlives the CTM restart it triggers
+ * (D-4), with stdout/stderr on the per-target log file (the pattern lib/api/worktrees.js:193-215 uses
+ * for the npx updater). `CTM_PORT`/`CTM_DATA_DIR` are handed to the child so it polls the box it was
+ * spawned by.
+ *
+ * TWO LAUNCH SHAPES, because "detached" means different things to the two supervisors:
+ *   * systemd (Linux service — measured on the DGX Spark 2026-10-27): `ctm.service` is
+ *     `KillMode=control-group` / `Restart=on-failure` and EVERY descendant — session hosts, Wall-E,
+ *     agents — lives in that unit's cgroup. CTM's restart is exit 42, so systemd stops the unit and
+ *     reaps the WHOLE cgroup: a `detached: true` child is killed mid-apply, before step 7 can confirm
+ *     or roll back, and the box is left saying `restarting` forever. A transient `systemd-run --user`
+ *     unit is not in `ctm.service`'s cgroup, so it survives the restart and `--collect` cleans it up.
+ *   * launchd / anything else: `detached: true` already puts the child in its own process group, which
+ *     nothing here reaps. Unchanged.
+ *
+ * A `systemd-run` that cannot start (non-zero exit, ENOENT) is not fatal: we say so in the log and
+ * fall back to the detached child, which is still strictly better than not applying at all.
+ * `platform`/`env`/`execFileImpl`/`spawnImpl` are injectable so tests pin the exact argv.
+ */
+async function _spawnFleetApplyDetached(to, {
+  repoRoot,
+  dataDir,
+  port,
+  platform = process.platform,
+  env = process.env,
+  execFileImpl: execFile = defaultExecFile,
+  spawnImpl: spawn = defaultSpawn,
+  local = false,
+} = {}) {
+  await fsp.mkdir(fleetDir(dataDir), { recursive: true, mode: 0o700 });
+  const logPath = fleetApplyLogPath(dataDir, to);
+
+  // §8 WP-2b — the LOCAL variant (`land sync` moved this box's own main; `--local` before the sha).
+  // A SEPARATE BRANCH, deliberately: the two launch shapes below keep their exact text, because
+  // bin/main-thread-lint.js keys its process-launch exemptions on the whole source line. Both shapes
+  // exist here for the same reason they exist below (see the block comment on this function): on a
+  // systemd host a `detached: true` child dies with `ctm.service`'s cgroup mid-apply.
+  if (local) {
+    if (platform === 'linux' && env && env.INVOCATION_ID) {
+      const outcome = await new Promise((resolve) => {
+        execFile('systemd-run', systemdRunArgv(to, { repoRoot, dataDir, port, logPath, local: true }),
+          { timeout: SYSTEMD_RUN_TIMEOUT_MS },
+          (error) => resolve(error || null));
+      });
+      if (!outcome) return;
+      const why = Number.isInteger(outcome.code) ? `exit ${outcome.code}` : String(outcome.message || outcome);
+      await fsp.appendFile(logPath,
+        `[fleet-update] systemd-run could not start the local apply unit (${why}); falling back to a detached child\n`,
+        { mode: 0o600 }).catch(() => { /* expected: an unwritable log must not swallow the apply */ });
+    }
+    const localHandle = await fsp.open(logPath, 'a', 0o600);
+    try {
+      const child = spawn(process.execPath, [path.join(repoRoot, 'bin', 'fleet-apply.js'), '--local', to], {
+        cwd: repoRoot,
+        detached: true,
+        stdio: ['ignore', localHandle.fd, localHandle.fd],
+        env: { ...env, CTM_PORT: String(port == null ? '' : port), CTM_DATA_DIR: String(dataDir) },
+      });
+      child.unref();
+    } finally {
+      await localHandle.close();
+    }
+    return;
+  }
+
+  // INVOCATION_ID is set by systemd for the unit's own processes: its presence is what proves we are
+  // a service rather than a human's shell on a Linux box.
+  if (isSystemdService({ platform, env })) {
+    const outcome = await new Promise((resolve) => {
+      execFile('systemd-run', systemdRunArgv(to, { repoRoot, dataDir, port, logPath }),
+        { timeout: SYSTEMD_RUN_TIMEOUT_MS },
+        (error) => resolve(error || null));
+    });
+    if (!outcome) return;
+    const why = Number.isInteger(outcome.code) ? `exit ${outcome.code}` : String(outcome.message || outcome);
+    await fsp.appendFile(logPath,
+      `[fleet-update] systemd-run could not start the apply unit (${why}); falling back to a detached child\n`,
+      { mode: 0o600 }).catch(() => { /* expected: an unwritable log must not swallow the apply */ });
+  }
+
+  const handle = await fsp.open(logPath, 'a', 0o600);
+  try {
+    const child = spawn(process.execPath, [path.join(repoRoot, 'bin', 'fleet-apply.js'), to], {
+      cwd: repoRoot,
+      detached: true,
+      stdio: ['ignore', handle.fd, handle.fd],
+      env: { ...env, CTM_PORT: String(port == null ? '' : port), CTM_DATA_DIR: String(dataDir) },
+    });
+    child.unref();
+  } finally {
+    await handle.close();
+  }
+}
+
+/**
+ * §5 R-7 / §8 WP-2b: the outcomes `scheduleLocalApply` can report, frozen so a test can iterate the
+ * whole set and a reader can tell "refused on purpose" from "silently did nothing".
+ */
+const FLEET_LOCAL_RESTART_REASONS = Object.freeze([
+  'no_move',        // the sync did not move main (pushed, in_sync, …) — nothing to converge onto
+  'no_env',         // CTM_DATA_DIR / CTM_PORT unset: not a CTM-managed box (a human's shell, a test)
+  'dev_instance',   // CTM_INSTANCE_TAG starts with `dev-`: a dev instance never restarts itself
+  'foreign_repo',   // the synced repository is not the one this launcher ships in (see below)
+  'already_current',// /readyz already reports a build that is this sha
+  'self_restart_off',// this clone's `git config ctm.fleetSelfRestart false`: the box restarts by hand only
+  'spawned',        // the helper was launched; it owns the idle verdict, the restart and readyz
+  'spawn_failed',   // the launch itself threw — reported, never retried here
+]);
+
+// User ruling 2026-10-31: "for fleet apply, don't restart hub ctm, you can restart the ctm in other
+// boxes". Which box is the hub is a per-machine fact, not repository policy (`.ctm.json` is the same
+// on every box), so it lives in the clone's own git config — the same place the ledger merge drivers
+// live: `git config ctm.fleetSelfRestart false` in the hub's main checkout. Unset (every other box)
+// or any value git does not read as false keeps today's behaviour: the box restarts itself when idle.
+const SELF_RESTART_CONFIG_KEY = 'ctm.fleetSelfRestart';
+
+/** True unless `repoRoot`'s git config sets `ctm.fleetSelfRestart` to a false boolean. */
+async function selfRestartAllowed(repoRoot, { runGit = _execFileGit } = {}) {
+  const out = await _runGitResult(runGit, ['config', '--type=bool', '--get', SELF_RESTART_CONFIG_KEY], repoRoot);
+  // exit 1 = unset; any other failure (a value git cannot parse as a bool) also keeps the default.
+  if (out.code !== 0) return true;
+  return out.stdout.trim() !== 'false';
+}
+
+/** `/readyz` is a local HTTP call inside a sync: 5 s is generous, and a miss means "spawn". */
+const READYZ_TIMEOUT_MS = 5000;
+
+/**
+ * `GET 127.0.0.1:<port>/readyz` — the identity of the build this box is RUNNING (`build.sha`).
+ * Anything unreadable (refused, timed out, not JSON, non-200) resolves `{ ok: false }`, which the
+ * caller reads as "spawn": the helper re-reads the box's own state and is the only place that can
+ * decide to give up, so a failed probe must never be the reason a box stays stale.
+ */
+function defaultReadyzProbe(port) {
+  return new Promise((resolve) => {
+    const request = http.get({ host: '127.0.0.1', port: Number(port), path: '/readyz', timeout: READYZ_TIMEOUT_MS }, (response) => {
+      let body = '';
+      response.setEncoding('utf8');
+      response.on('data', (chunk) => { body += chunk; });
+      response.on('end', () => resolve({ ok: response.statusCode === 200, body }));
+    });
+    request.on('timeout', () => { request.destroy(); resolve({ ok: false, body: '' }); });
+    request.on('error', () => resolve({ ok: false, body: '' }));
+  });
+}
+
+/** The running build's sha, or `''` for a readyz this code cannot read. */
+function runningShaFrom(response) {
+  if (!response || !response.ok || !response.body) return '';
+  try {
+    const parsed = JSON.parse(response.body);
+    const sha = parsed && parsed.build && parsed.build.sha;
+    return typeof sha === 'string' ? sha.trim() : '';
+  } catch (error) {
+    /* expected: a non-JSON /readyz body proves nothing about the running build — the caller then
+       spawns, and the helper's own readyz check is the authority */
+    return '';
+  }
+}
+
+/**
+ * `realpath` or `null`: a path that does not exist cannot be the repository that ships
+ * fleet-apply.js. Async on purpose — `land sync` must not block its own event loop on the filesystem.
+ */
+async function realRepoPath(value) {
+  if (!value) return null;
+  try {
+    return await fsp.realpath(value);
+  } catch (error) {
+    /* expected: a missing/unreadable path is "not my repository", never a throw into a sync */
+    return null;
+  }
+}
+
+/**
+ * The MAIN worktree of the repository `dir` belongs to (realpath), or null. A linked worktree's `.git` is
+ * a file `gitdir: <common>/worktrees/<name>`, so its main worktree is three levels above that path; a main
+ * checkout's `.git` is a directory. `land sync` usually runs from an agent's linked worktree, so guard (c)
+ * must compare main worktree to main worktree, never a worktree path to the main checkout.
+ */
+async function mainWorktreeOf(dir) {
+  const real = await realRepoPath(dir);
+  if (!real) return null;
+  let stat;
+  try {
+    stat = await fsp.stat(path.join(real, '.git'));
+  } catch (error) {
+    /* expected: no .git here means "not a repository root", which guard (c) reports as foreign_repo */
+    return null;
+  }
+  if (stat.isDirectory()) return real;
+  let text;
+  try {
+    text = await fsp.readFile(path.join(real, '.git'), 'utf8');
+  } catch (error) {
+    /* expected: an unreadable .git file is "not my repository" */
+    return null;
+  }
+  const match = /^gitdir:\s*(.+)$/m.exec(text);
+  if (!match) return null;
+  const gitdir = path.resolve(real, match[1].trim());
+  return realRepoPath(path.resolve(gitdir, '..', '..', '..'));
+}
+
+/**
+ * §5 R-7 / §8 WP-2b: after `land sync` moved THIS box's own main (pulled or published), schedule ONE
+ * idle restart onto the new sha — `bin/fleet-apply.js --local <to>` detached through the launcher
+ * above, so the box converges onto its own build without waiting for a hub bundle.
+ *
+ * SPAWN ONLY when all four guards hold, else `{ spawned: false, reason }` (the reasons above):
+ *   (a) `CTM_DATA_DIR` and `CTM_PORT` are set — a CTM-managed box, not a human's shell or a test;
+ *   (b) `CTM_INSTANCE_TAG` does not start with `dev-` — a dev instance never restarts itself;
+ *   (c) the synced repo's MAIN worktree (the git common dir's parent, resolved) IS the repository
+ *       this launcher ships in. This is the safety rule that keeps a scratch repo in a test — or
+ *       another checkout of the same code — from ever restarting a real CTM;
+ *   (d) `/readyz` does not already report a build that is `to` (an unreadable readyz ⇒ spawn: the
+ *       helper handles a box that is mid-restart, and refusing there would strand it).
+ *
+ * `probe` and `spawner` are injectable so the guards are testable without a server or a process.
+ */
+async function scheduleLocalApply({
+  to,
+  syncedRepoRoot = null,
+  env = process.env,
+  probe = defaultReadyzProbe,
+  spawner = null,
+  repoRoot = DEFAULT_REPO_ROOT,
+  local = true,
+  readSelfRestart = selfRestartAllowed,
+} = {}) {
+  const refuse = (reason) => ({ spawned: false, reason });
+  const dataDir = env ? env.CTM_DATA_DIR : null;
+  const port = env ? env.CTM_PORT : null;
+  if (!dataDir || !port) return refuse('no_env');
+  if (String(env.CTM_INSTANCE_TAG || '').startsWith('dev-')) return refuse('dev_instance');
+  const mine = await mainWorktreeOf(repoRoot);
+  const synced = await realRepoPath(syncedRepoRoot);
+  if (!mine || synced !== mine) return refuse('foreign_repo');
+  if (!(await readSelfRestart(mine))) return refuse('self_restart_off');
+
+  let ready = null;
+  try {
+    ready = await probe(String(port));
+  } catch (error) {
+    /* expected: a throwing probe is an unreadable readyz — spawn, and let the helper be the judge */
+    ready = null;
+  }
+  const running = runningShaFrom(ready);
+  if (running && String(to).startsWith(running)) return refuse('already_current');
+
+  try {
+    const spawnFn = typeof spawner === 'function'
+      ? spawner
+      // The helper must be the MAIN checkout's copy: it restarts the CTM that checkout runs, and its own
+      // HEAD-is-main check is against the checkout it lives in (a worktree copy would refuse not_main).
+      : (sha) => _spawnFleetApplyDetached(sha, { repoRoot: mine, dataDir, port, local });
+    await spawnFn(to);
+    return { spawned: true, reason: 'spawned' };
+  } catch (error) {
+    return { spawned: false, reason: `spawn_failed: ${error.message}` };
+  }
+}
+
+/**
+ * POST /api/fleet/bundle (§6, §9 S-6): accept ONE fast-forward bundle, verify it, park it in
+ * `refs/fleet/incoming`, and hand the apply to the detached helper. Never merges anything itself —
+ * D-4's "the box applies" is the helper's job, so this route's worst case is a refused ref.
+ *
+ * Returns `{ status, body }`; the caller writes it. Every refusal unlinks the received file, so a
+ * rejected bundle leaves no trace beyond the ref it never moved.
+ */
+async function acceptFleetBundle(req, {
+  to,
+  repoRoot = DEFAULT_REPO_ROOT,
+  dataDir = '',
+  port = null,
+  runGit = _execFileGit,
+  spawnHelper = null,
+  maxBytes = FLEET_BUNDLE_MAX_BYTES,
+} = {}) {
+  if (!isFullSha(to)) return { status: 400, body: { error: 'fleet_bad_target' } };
+  if (!dataDir) return { status: 500, body: { error: 'fleet_no_data_dir' } };
+
+  // The transfer holds the SAME lock the helper takes, so a second bundle cannot start while one is
+  // in flight (D-7) — and a lock whose holder is dead is reclaimed here, not by a human.
+  const lock = await acquireFleetApplyLock(dataDir);
+  if (!lock.ok) return { status: 409, body: { error: 'fleet_refused', reason: 'in_progress' } };
+
+  const bundlePath = path.join(fleetDir(dataDir), 'incoming', `${to}.bundle`);
+  let handedOff = false;
+  try {
+    const status = await readFleetStatus({ repoRoot, runGit });
+    if (status.channel !== 'git') return { status: 409, body: { error: 'fleet_refused', reason: 'not_git' } };
+    if (status.branch !== 'main') return { status: 409, body: { error: 'fleet_refused', reason: 'not_main' } };
+    if (!status.clean) return { status: 409, body: { error: 'fleet_refused', reason: 'dirty' } };
+
+    await fsp.mkdir(path.dirname(bundlePath), { recursive: true, mode: 0o700 });
+    const streamed = await _streamBodyToFile(req, bundlePath, maxBytes);
+    if (!streamed.ok) {
+      if (streamed.tooLarge) return { status: 413, body: { error: 'fleet_bundle_too_large' } };
+      return { status: 400, body: { error: 'fleet_bundle_invalid' } };
+    }
+
+    // A bundle that needs a prerequisite this box does not hold is the DIVERGED case the hub must
+    // show as such; anything else is simply not a bundle we can use.
+    const verify = await _runGitResult(runGit, ['bundle', 'verify', bundlePath], repoRoot, GIT_BUNDLE_TIMEOUT_MS);
+    if (verify.code !== 0) {
+      if (/prerequisite/i.test(verify.stderr || '')) return { status: 409, body: { error: 'fleet_refused', reason: 'diverged' } };
+      return { status: 400, body: { error: 'fleet_bundle_invalid' } };
+    }
+
+    const fetched = await _runGitResult(runGit, ['fetch', bundlePath, '+refs/heads/main:refs/fleet/incoming'], repoRoot, GIT_BUNDLE_TIMEOUT_MS);
+    if (fetched.code !== 0) return { status: 400, body: { error: 'fleet_bundle_invalid' } };
+    const incoming = String(await _git(runGit, repoRoot, ['rev-parse', 'refs/fleet/incoming'], '') || '').trim();
+    if (incoming !== to) return { status: 400, body: { error: 'fleet_bundle_target_mismatch' } };
+
+    // D-9: fast-forward only. A `to` this box's HEAD is not an ancestor of is never applied.
+    const ancestor = await _runGitResult(runGit, ['merge-base', '--is-ancestor', 'HEAD', to], repoRoot, GIT_TIMEOUT_MS);
+    if (ancestor.code !== 0) return { status: 409, body: { error: 'fleet_refused', reason: 'diverged' } };
+
+    // Hand the lock to the helper (it re-claims it as its own pid) before the detached spawn, so the
+    // child never races the route for its own lock file.
+    await releaseFleetApplyLock(lock);
+    handedOff = true;
+    const spawnFn = typeof spawnHelper === 'function'
+      ? spawnHelper
+      : (sha) => _spawnFleetApplyDetached(sha, { repoRoot, dataDir, port });
+    await spawnFn(to);
+    return { status: 202, body: { accepted: true, to } };
+  } finally {
+    if (!handedOff) {
+      await releaseFleetApplyLock(lock);
+      await fsp.unlink(bundlePath).catch(() => { /* expected: a 400/409 refused before the body was written */ });
+    }
+  }
+}
+
+function _resetFleetUpdateStateForTests() { _hubTarget.clear(); }
+
+module.exports = {
+  _resetFleetUpdateStateForTests,
+  _spawnFleetApplyDetached,
+  defaultReadyzProbe,
+  runningShaFrom,
+  scheduleLocalApply,
+  mainWorktreeOf,
+  systemdRunArgv,
+  FLEET_BUNDLE_MAX_BYTES,
+  FLEET_LOCKFILES,
+  FLEET_LOCAL_RESTART_REASONS,
+  SELF_RESTART_CONFIG_KEY,
+  selfRestartAllowed,
+  FLEET_REASONS,
+  FLEET_STATES,
+  acceptFleetBundle,
+  acquireFleetApplyLock,
+  fleetApplyLockPath,
+  fleetDir,
+  fleetStatePath,
+  isFullSha,
+  isPidAlive,
+  readFleetState,
+  readFleetStatus,
+  readHubTarget,
+  releaseFleetApplyLock,
+  writeFleetState,
+};