@codeyam-editor/codeyam-editor 0.1.4 → 0.1.5

package/npm/fleet-cleanup.js

@@ -175,13 +175,28 @@ function clearExitMarker(dir, n) {
   catch (_) { /* missing is fine */ }
 }
 
+// True when an integer exit code is the shell's "killed by signal N" encoding,
+// i.e. 128 + N for N in 1..37 — the realistic kills being 143 (SIGTERM, the
+// `launchctl bootout` graceful teardown), 137 (SIGKILL), 130 (SIGINT) and 129
+// (SIGHUP). Pure boundary check: 128 itself is NOT a signal kill (it's `exit
+// 128`, an ordinary failure code), so the range is the OPEN interval
+// (128, 165]. Anything outside it — a small `exit 1` from the addVm script's own
+// failure branches, 0, NaN, null — is not a signal kill. The split that matters:
+// "did a signal kill the provision shell" (interrupted → reconcile) vs "did the
+// provision logic itself decide it failed" (real error). Exported so the matrix
+// is unit-testable directly.
+function isSignalKillExit(code) {
+  return Number.isInteger(code) && code > 128 && code <= 165;
+}
+
 // Decide how a snapshot-restored `add` should be re-attached after a dashboard
 // restart, BEFORE any gcloud probe. Pure: takes the durable signals the boot
 // path gathers — whether the exit marker exists, its recorded code, and whether
 // the detached provision child is still alive (recorded pid, `kill -0`).
 //   verdict       when                                          dispatch
 //   'done'        marker present, exit code 0                   roster + recordLaunch, clear sidecar/marker
-//   'error'       marker present, non-zero exit code            surface the real failure, clear sidecar/marker
+//   'reconcile'   marker present, SIGNAL-kill code (128<c≤165)  interrupted, not failed — gcloud probe decides
+//   'error'       marker present, other non-zero exit code      surface the real failure, clear sidecar/marker
 //   'running'     no marker yet, child still alive              RE-ATTACH: keep polling, do NOT mark error
 //   'reconcile'   child gone, no usable marker                  fall through to fc.reapVerdict (gcloud probe)
 // This is the durable fix's brain: a provision that survived the kill (still
@@ -192,14 +207,33 @@ function clearExitMarker(dir, n) {
 // `reconcile` hands that exact (exists, containerUp, projectWired) decision to
 // fc.reapVerdict. A marker whose first line isn't an integer is treated as
 // absent (parseExitMarker → null) so a corrupt marker reconciles rather than
-// asserting a bogus code. The matrix is exhaustively tested without a live VM.
+// asserting a bogus code.
+//
+// SIGNAL-kill codes (improve46): `setsid` shields the detached provision from a
+// dashboard-process-GROUP SIGKILL (the 2GB launchd hard cap), but NOT from a
+// `launchctl bootout`, which tears down the whole launchd job tree regardless of
+// session/process-group. A graceful SIGTERM then reaches the "detached" child and
+// its EXIT trap records 143 (128+SIGTERM) into the marker. That is an INTERRUPTED
+// add, not a failed one — the manual re-add succeeds in seconds off the image the
+// interrupted build already left on the VM. So a signal-kill code routes to
+// 'reconcile' (let the gcloud probe read ground truth and roster / recover) rather
+// than 'error' (a false add-failed that throws away a resumable build). A genuine
+// provision failure exits with a small non-zero code (e.g. `exit 1`), which STILL
+// classifies 'error'. The matrix is exhaustively tested without a live VM.
 function reattachVerdict({ markerPresent, exitCode, childAlive } = {}) {
   if (markerPresent) {
     // Guard the null/undefined coercion BEFORE Number() — `Number(null)` is 0,
     // which would masquerade as a clean exit. A marker with no parseable code
     // (half-written / corrupt) must reconcile, not assert success.
     const code = exitCode == null ? NaN : Number(exitCode);
-    if (Number.isInteger(code)) return code === 0 ? 'done' : 'error';
+    if (Number.isInteger(code)) {
+      if (code === 0) return 'done';
+      // A signal killed the provision shell (e.g. bootout SIGTERM → 143): the add
+      // was interrupted, not failed — reconcile against real VM state instead of
+      // surfacing a false add-failed and discarding a resumable build.
+      if (isSignalKillExit(code)) return 'reconcile';
+      return 'error';
+    }
     return 'reconcile'; // marker present but no parseable code — let gcloud decide
   }
   if (childAlive) return 'running';
@@ -297,11 +331,87 @@ function orphanedAddsToReconcile({ jobs, sidecarKeys } = {}) {
 // posture). "Busy" (a live session or an in-flight add to this number) also
 // holds the entry for an operator rather than auto-removing — the shouldn't-
 // happen-but-fail-safe case where a vanished instance still reports a session.
-function reconcileRosteredVm({ exists, hasSession, hasPendingAdd } = {}) {
+//   verdict     when                                        dispatch
+//   'cleanup'   instance gone AND the VM is idle            runDestroyCleanup
+//   'leave'     exists uncertain (null), OR the VM is busy  do nothing this pass
+//   'keep'      instance still exists                       do nothing (healthy)
+//   'reset'     existing idle instance unreachable too long trigger auto-reset
+// Fail-safe by construction: cleanup fires ONLY on a DEFINITIVE absence
+// (exists === false) — a flaky/transient describe (null) is always 'leave', so a
+// gcloud blip can never evict a healthy VM (mirroring reapVerdict's `leave`
+// posture). "Busy" (a live session or an in-flight add to this number) also
+// holds the entry for an operator rather than auto-removing — the shouldn't-
+// happen-but-fail-safe case where a vanished instance still reports a session.
+// auto-reset escalation (vm: OOM Wedge Prevention):
+// When the VM has been unreachable for at least RESET_UNREACHABLE_THRESHOLD
+// (e.g. 200, which is roughly 10 minutes at a 3s poll rate), we issue a 'reset'
+// verdict. This auto-reset is guarded and bounded by a cooldown window (in ms)
+// and a max attempts limit to prevent infinite reboot loops.
+//
+// false-unreachable reboot safety (2026-06-25): "unreachable" as the dashboard
+// sees it means the LOCALLY-FORWARDED port is dark — which is ALSO the signature
+// of an operator-side fault (the laptop's gcloud auth expired, the ssh -L tunnel
+// zombied, a laptop network blip) where the VM itself is perfectly healthy.
+// Rebooting a healthy production VM off that signal interrupts a live session.
+// So three operator-fault guards are layered BEFORE the cooldown/attempts budget
+// (a reset is a last resort, never the response to a dark local port). Each is
+// OPT-IN: it only changes the verdict when the caller supplies the fact, so
+// legacy callers (and the OOM-wedge tests) that pass none keep the old behavior.
+//   operatorAuthDegraded  our own gcloud auth is broken → EVERY VM reads
+//                         unreachable; rebooting them all is exactly wrong → keep
+//   fleetWideUnreachable  a simultaneous N-VM "outage" is the operator (auth/
+//                         tunnel/network), not N dead VMs → keep
+//   gcpReachable          GCP-side confirmation: true  ⇒ the VM answers from
+//                         GCP's vantage, so the dark local port is a laptop
+//                         tunnel fault → 'respawn' (never reset); null ⇒ the
+//                         GCP-side probe was inconclusive → keep (don't escalate
+//                         a destructive reset on absence of evidence); false ⇒
+//                         genuinely unreachable from GCP too → fall through to
+//                         the cooldown/attempts budget and reset as before.
+function reconcileRosteredVm({ exists, hasSession, hasPendingAdd, streak, resetHistory, threshold, cooldownMs, maxAttempts, operatorAuthDegraded, fleetWideUnreachable, gcpReachable } = {}) {
   if (exists === null || exists === undefined) return "leave";
-  if (exists) return "keep";
-  if (hasSession || hasPendingAdd) return "leave";
-  return "cleanup";
+  if (!exists) {
+    if (hasSession || hasPendingAdd) return "leave";
+    return "cleanup";
+  }
+
+  // If the VM exists, check if it's dead-unreachable and eligible for auto-reset.
+  if (streak !== undefined && threshold !== undefined) {
+    if (streak >= threshold) {
+      if (hasSession || hasPendingAdd) {
+        // Do NOT auto-reset a VM that is busy (holding a live session or an in-flight add)
+        return "keep";
+      }
+
+      // Operator-fault guards — layered before the cooldown/attempts budget so a
+      // laptop-side fault never even consumes a reset attempt.
+      if (operatorAuthDegraded) return "keep";
+      if (fleetWideUnreachable) return "keep";
+      if (gcpReachable === true) return "respawn";
+      if (gcpReachable === null) return "keep";
+
+      const history = resetHistory || { count: 0, lastResetAt: 0 };
+      const attempts = history.count || 0;
+      const limit = maxAttempts !== undefined ? maxAttempts : 3;
+      
+      if (attempts >= limit) {
+        // Budget exhausted (VM wedges repeatedly) -> park (needs-manual-recovery status)
+        return "keep";
+      }
+      
+      const lastReset = history.lastResetAt || 0;
+      const cooldown = cooldownMs !== undefined ? cooldownMs : 600000; // default 10 minutes
+      const now = Date.now();
+      if (now - lastReset < cooldown) {
+        // Within cooldown window -> do not reset again yet
+        return "keep";
+      }
+
+      return "reset";
+    }
+  }
+
+  return "keep";
 }
 
 module.exports = {
@@ -319,6 +429,7 @@ module.exports = {
   parseExitMarker,
   readExitMarker,
   clearExitMarker,
+  isSignalKillExit,
   reattachVerdict,
   reattachNextStep,
 };

package/npm/fleet-destroy-safety.js

@@ -0,0 +1,55 @@
+'use strict';
+// Pure decision + formatting helpers for the fleet dashboard's destroy/deroster
+// false-unreachable safety (2026-06-26 incident, where a reauth-triggered
+// false-unreachable cascade permanently deleted VM2/3/4). The dashboard's
+// server.js gathers the live operator-fault facts (state.operatorAuthDegraded +
+// fleetWideUnreachableNow) and runs the side effects (spawn the delete, log,
+// stop+deroster); the DECISIONS those facts drive — "is this destroy blocked,
+// and why" and "what does the attribution log line read" — live here so they
+// are unit-testable in isolation, the same pure/IO split npm/fleet-auth-health.js
+// (classifyOperatorAuth) and npm/fleet-cleanup.js (reconcileRosteredVm) follow.
+//
+// Pure logic only — no I/O, no env reads, no clock, no global state.
+
+// Classify whether a destructive removal (hard destroy or --shrink) must be
+// REFUSED because the operator's own side is faulted, from the two booleans
+// server.js computes. Returns { blocked, reason }: blocked is true when the
+// operator's gcloud auth is degraded OR a fleet-wide unreachable spike is in
+// progress — the signature of a laptop-side fault (which makes EVERY VM read
+// unreachable), NOT N genuinely-dead VMs. authDegraded takes precedence in the
+// reason because it is the upstream cause (a broken operator auth is what
+// produces the fleet-wide false-unreachable spike in the first place), so the
+// message points at the thing to fix.
+//   authDegraded  state.operatorAuthDegraded — operator gcloud auth is broken
+//   fleetWide     fleetWideUnreachableNow() — N+ VMs unreachable at once
+function classifyDestroyBlock({ authDegraded, fleetWide } = {}) {
+  if (authDegraded) {
+    return { blocked: true, reason: 'operator gcloud auth degraded' };
+  }
+  if (fleetWide) {
+    return { blocked: true, reason: 'fleet-wide unreachable spike in progress (operator-side fault signature)' };
+  }
+  return { blocked: false, reason: null };
+}
+
+// Build the single attributable destroy-decision log line. Mirrors the
+// performAutoReset "confirmed … not fleet-wide" template so every destroy —
+// proceed OR refused, across every trigger source — is diagnosable from one
+// grep. `remote` ({ ip, ua }) is the caller attribution whose absence made the
+// 2026-06-26 delete impossible to trace back to its trigger; null/absent renders
+// as `n/a` (e.g. the shrink / reap paths have no HTTP caller). All the flag
+// fields are normalized to real booleans so a missing field never reads as
+// `undefined` in the line.
+function formatDestroyDecision(info = {}) {
+  const remote = info.remote ? `${info.remote.ip || '?'}/${info.remote.ua || '?'}` : 'n/a';
+  return (
+    `destroy-decision: VM-${info.n} source=${info.source} force=${!!info.force} ` +
+    `override=${!!info.overrideSafety} remote=${remote} hasSession=${!!info.hasSession} ` +
+    `authDegraded=${!!info.authDegraded} fleetWide=${!!info.fleetWide} → ${info.outcome}`
+  );
+}
+
+module.exports = {
+  classifyDestroyBlock,
+  formatDestroyDecision,
+};

package/npm/fleet-effect-status.js

@@ -58,12 +58,10 @@ function resetReason({ agent, session, dirty, behind, codeyam }) {
 // meaningless for them).
 const ACTION_IDS = [
   'update-client-source',
-  'update-editor-source',
-  'reset-editor-source',
   'reset-client',
+  'end-session',
   'rebuild-binary',
   'update-reset-everything',
-  'run-setup',
 ];
 
 // facts (a plain object gathered by server.js — no I/O):
@@ -105,13 +103,6 @@ function computeButtonEffects(facts) {
       ? { effect: 'changes', reason: behindReason(client.behind, f.clientBranch) }
       : { effect: 'noop', reason: 'up to date with ' + originRef(f.clientBranch) };
 
-  // (2) Update editor — advance the editor source the binary builds from.
-  const updateEditor = editor == null
-    ? { effect: 'unknown', reason: 'editor state not checked' }
-    : editor.behind > 0
-      ? { effect: 'changes', reason: behindReason(editor.behind, f.editorBranch) }
-      : { effect: 'noop', reason: 'up to date with ' + originRef(f.editorBranch) };
-
   // (5) Rebuild binary — advances source then compiles. Changes iff the running
   // binary's build commit differs from the editor origin tip. Unknown when we
   // don't have both commits to compare.
@@ -121,25 +112,38 @@ function computeButtonEffects(facts) {
       ? { effect: 'changes', reason: `binary at ${short(editor.buildCommit)}, ${originRef(f.editorBranch)} at ${short(editor.originSha)}` }
       : { effect: 'noop', reason: 'binary built from ' + originRef(f.editorBranch) + ' tip' };
 
-  // (3) Reset editor — discards uncommitted + session, advances source, wipes
-  // .codeyam. No-op ONLY when clean at origin tip with no session.
+  // Reset editor (editor-state reset) — discards uncommitted + session, advances
+  // source, wipes .codeyam. No-op ONLY when clean at origin tip with no session.
+  // INTERNAL-ONLY: the standalone "Reset editor" button was removed; this
+  // predicate survives purely as an input to the "Reset all + rebuild" composite
+  // below (which still runs resetEditorStateScript), so it is NOT returned/keyed.
   const resetEditor = editor == null
     ? { effect: 'unknown', reason: 'editor state not checked' }
     : (brokerLive || hasSession || editor.dirty || editor.behind > 0 || codeyamDirty)
       ? { effect: 'changes', reason: resetReason({ agent: brokerLive, session: hasSession, dirty: editor.dirty, behind: editor.behind > 0, codeyam: codeyamDirty }) }
       : { effect: 'noop', reason: 'already clean at origin tip, no session' };
 
-  // (3b) Reset client — hard-clean /workspace + .codeyam, drop the session.
-  // No source-advance, so `behind` is NOT part of this predicate.
+  // (2) Reset client — hard-clean /workspace + .codeyam, drop the session, now
+  // ADVANCING to origin tip. Since the reset advances source, a VM behind origin
+  // would be changed by a re-run, so `behind` IS part of this predicate.
   const resetClient = client == null
     ? { effect: 'unknown', reason: 'client state not checked' }
-    : (brokerLive || client.dirty || codeyamDirty || hasSession)
-      ? { effect: 'changes', reason: resetReason({ agent: brokerLive, session: hasSession, dirty: client.dirty, behind: false, codeyam: codeyamDirty }) }
-      : { effect: 'noop', reason: 'already clean, no session' };
+    : (brokerLive || client.dirty || client.behind > 0 || codeyamDirty || hasSession)
+      ? { effect: 'changes', reason: resetReason({ agent: brokerLive, session: hasSession, dirty: client.dirty, behind: client.behind > 0, codeyam: codeyamDirty }) }
+      : { effect: 'noop', reason: 'already clean at origin tip, no session' };
 
-  // (4b) Update & Reset Everything — composite. Changes iff ANY component would
-  // change: rebuild-binary, reset-editor-source, or the client being
-  // behind/dirty. Reason summarizes which parts.
+  // (2b) End session — kills the live agent + clears session state. The ONLY
+  // thing it touches is the running session, so it changes the VM iff a live
+  // agent or a registered session exists; otherwise it's a clean no-op. Unlike
+  // the resets it ignores dirty/behind/.codeyam — it neither advances source nor
+  // wipes state.
+  const endSession = (brokerLive || hasSession)
+    ? { effect: 'changes', reason: resetReason({ agent: brokerLive, session: hasSession }) }
+    : { effect: 'noop', reason: 'no active session' };
+
+  // (4) Reset all + rebuild — composite. Changes iff ANY component would
+  // change: rebuild-binary, the editor-state reset (internal resetEditor
+  // predicate above), or the client being behind/dirty. Reason summarizes parts.
   const everything = (() => {
     if (editor == null || client == null) {
       return { effect: 'unknown', reason: 'state not checked' };
@@ -157,23 +161,20 @@ function computeButtonEffects(facts) {
     return { effect: 'noop', reason: 'everything already at origin tip, no session' };
   })();
 
-  // (run-setup) Honest soft signal — there is no cheap upstream proof that
-  // `npm run setup` would change nothing (DB/migration state isn't
-  // introspected). `recommended` when a reset/update landed after the last
-  // successful setup; otherwise `unknown`. Never a confident green no-op.
-  const runSetup = f.setupRanSince
-    ? { effect: 'unknown', reason: 'no setup-affecting change since last setup' }
-    : { effect: 'recommended', reason: 'a reset/update landed since the last setup' };
-
   return {
     'update-client-source': updateClient,
-    'update-editor-source': updateEditor,
-    'reset-editor-source': resetEditor,
     'reset-client': resetClient,
+    'end-session': endSession,
     'rebuild-binary': rebuild,
     'update-reset-everything': everything,
-    'run-setup': runSetup,
   };
 }
 
-module.exports = { computeButtonEffects, ACTION_IDS };
+// Decide whether a Live Preview SSH forward needs to be re-wired (improve41)
+function needsRewire(forwardAppPort, polledAppPort) {
+  if (typeof polledAppPort !== 'number' || isNaN(polledAppPort)) return false;
+  if (!forwardAppPort) return false;
+  return forwardAppPort !== polledAppPort;
+}
+
+module.exports = { computeButtonEffects, ACTION_IDS, needsRewire };

package/npm/fleet-host.js

@@ -0,0 +1,74 @@
+'use strict';
+// Pure operator-host placement resolution for the fleet dashboard
+// (vm-dashboard-on-gce).
+//
+// The dashboard runs in two homes: the operator's laptop (legacy fallback) and a
+// dedicated GCE "operator host" (the primary path). Three things differ by home —
+// how gcloud authenticates, what address the dashboard binds, and how a branch
+// pin is read from the env — and each used to be an inline ternary at the top of
+// server.js's 200KB monolith, untestable. This module is the single home for
+// those decisions, so server.js delegates the RULE and keeps only the I/O, the
+// same split npm/fleet-branch.js (resolveFleetBranch) follows.
+//
+// Pure logic only — no I/O, no env reads beyond the explicit `env` argument a
+// caller passes in — so it stays unit-testable in isolation (npm/fleet-host.test.js).
+
+// Env var the systemd unit sets on the GCE operator host. Its presence (truthy)
+// is what flips the dashboard from the laptop defaults to the on-GCE defaults.
+const FLEET_ON_GCE_ENV = 'FLEET_ON_GCE';
+
+/** True when the dashboard is running on the GCE operator host, read from the
+ *  `FLEET_ON_GCE` env. Accepts the conventional truthy spellings `1` / `true` /
+ *  `yes` (case-insensitive, trimmed); everything else — unset, empty, `0`,
+ *  `false`, garbage — is false, so a laptop run (which never sets it) stays on
+ *  the loopback + named-configuration defaults. */
+function onGce(env = {}) {
+  return /^(1|true|yes)$/i.test(String(env[FLEET_ON_GCE_ENV] || '').trim());
+}
+
+/** Resolve the gcloud invocation prefix the dashboard's `${GCLOUD}` chokepoint
+ *  uses. On the GCE operator host the attached SA authenticates from instance
+ *  metadata, so a plain `gcloud` is correct (no key file, no named config). Off
+ *  GCE (laptop) it pins the non-expiring SA configuration with
+ *  `--configuration=<config>` so background loops survive OAuth-token expiry.
+ *  Returns `'gcloud'` on GCE; throws if a non-GCE call omits the config name,
+ *  since silently emitting a bare `gcloud` there would run on the operator's
+ *  personal account — the exact regression the chokepoint exists to prevent. */
+function gcloudCommand({ onGce: gce, config } = {}) {
+  if (gce) return 'gcloud';
+  const c = typeof config === 'string' ? config.trim() : '';
+  if (!c) {
+    throw new Error('gcloudCommand requires a config name when not on GCE');
+  }
+  return `gcloud --configuration=${c}`;
+}
+
+/** Resolve the address the dashboard binds. An explicit `bind` (the DASH_BIND
+ *  override) always wins. Otherwise the host serves the LB's zonal NEG so it must
+ *  bind the instance's internal NIC (`0.0.0.0`, firewalled to the LB + IAP
+ *  ranges); a laptop run binds loopback only (`127.0.0.1`). A blank/whitespace
+ *  override counts as absent so a set-but-empty env doesn't bind to an empty
+ *  string. */
+function dashboardBind({ onGce: gce, bind } = {}) {
+  const explicit = typeof bind === 'string' ? bind.trim() : '';
+  if (explicit) return explicit;
+  return gce ? '0.0.0.0' : '127.0.0.1';
+}
+
+/** Resolve the explicit branch pin from the env, or null when unpinned. The
+ *  operator-host name is `FLEET_BRANCH`; `BRANCH` is the legacy laptop alias and
+ *  is honored as a fallback. A blank/whitespace value is "no pin" (so the
+ *  dashboard tracks live git HEAD via resolveFleetBranch). Returns the trimmed
+ *  pin or null. */
+function branchPin(env = {}) {
+  const pin = String(env.FLEET_BRANCH || env.BRANCH || '').trim();
+  return pin === '' ? null : pin;
+}
+
+module.exports = {
+  FLEET_ON_GCE_ENV,
+  onGce,
+  gcloudCommand,
+  dashboardBind,
+  branchPin,
+};

package/npm/fleet-job-badge.js

@@ -2,7 +2,7 @@
 
 // npm/fleet-job-badge.js — pure verdict for the fleet dashboard's failed-job
 // badge reconciliation (improve39). A VM's last terminal-error heavy job
-// (add/error, reset-all error, reset-editor error, …) used to stick on the
+// (add/error, reset-all error, reset-client error, …) used to stick on the
 // dashboard card indefinitely — even after the VM was recovered and is healthy
 // again — because the card renders the last job's error with no check against
 // the VM's live state, so a recovered VM keeps screaming a red error and

package/npm/fleet-launchd.js

@@ -0,0 +1,171 @@
+'use strict';
+// Pure helpers for running a VM `add` provision as its OWN transient launchd
+// job (`com.codeyam.fleet-add-vm-<n>`) — improve46 Phase 3. The provision job
+// is a SIBLING of `com.codeyam.fleet-dashboard` rather than a `setsid` child of
+// it, so a `launchctl bootout` of the dashboard label (which tears down the
+// whole dashboard launchd job tree regardless of session/process-group) has no
+// authority over the provision. Phases 1 (signal-kill reclassification) and 2
+// (the reinstall in-flight-add guard) still compose with this — Phase 3 reduces
+// how often a bootout reaches the provision at all.
+//
+// All the string-building and parsing lives here so server.js can stay thin and
+// these pieces are unit-testable WITHOUT launchctl (npm/fleet-launchd.test.js) —
+// the same decomposition `npm/fleet-cleanup.js` uses for the reap brain.
+//
+// Stack assumption: launchd is macOS-only. server.js gates the whole own-job
+// path on platform + a `launchctl` probe and falls back to the existing `setsid`
+// detached spawn on cloud containers / CI / Linux, where these helpers are never
+// reached. They are pure either way.
+
+// The launchd label for VM-n's transient add-provision job. ONE label per VM
+// number so the re-add collision guard and the completion teardown each address
+// exactly one job. Mirrors the `com.codeyam.fleet-*` label family used by the
+// dashboard's other launchd agents (see scripts/operator/launchd-reinstall.sh).
+function addVmLabel(n) {
+  return `com.codeyam.fleet-add-vm-${n}`;
+}
+
+// The file the transient job's stdout/stderr are redirected to (the plist's
+// Standard{Out,Error}Path). The dashboard tails this for the in-progress card's
+// live log when the launchd path is taken — the equivalent of the `setsid`
+// path's stdout pipe, which a separate launchd job can't share. Kept DISTINCT
+// from `/tmp/dash-add-vm-<n>.log` (the addVm script's own `cloud:up` redirect)
+// so the provision shell's progress echoes ("provisioning…", "VM-n provisioned")
+// aren't interleaved with the cloud:up build output.
+function addVmJobLogPath(n) {
+  return `/tmp/dash-add-vm-${n}.provision.log`;
+}
+
+// XML-escape a string for safe inclusion in a plist `<string>` body. Plists are
+// XML, so the five predefined entities must be escaped or a path/env value with
+// `&`/`<`/`>`/quotes would corrupt the plist. Pure.
+function xmlEscape(s) {
+  return String(s == null ? '' : s)
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&apos;');
+}
+
+// Build a transient launchd plist (XML text) that runs `programArguments` ONCE
+// under `label`. RunAtLoad=true so `launchctl bootstrap` fires it immediately;
+// KeepAlive=false so launchd NEVER relaunches the provision after it exits (a
+// one-shot job, not a daemon). stdout/stderr go to `logPath` so the dashboard
+// can tail the live card. `environment` (the bootstrap form env) and
+// `workingDirectory` are optional. Pure — caller writes the returned text to a
+// temp file and bootstraps it.
+function buildAddVmPlist({ label, programArguments, logPath, workingDirectory, environment } = {}) {
+  const args = (Array.isArray(programArguments) ? programArguments : [])
+    .map((a) => `    <string>${xmlEscape(a)}</string>`)
+    .join('\n');
+  const lines = [
+    '<?xml version="1.0" encoding="UTF-8"?>',
+    '<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">',
+    '<plist version="1.0">',
+    '<dict>',
+    '  <key>Label</key>',
+    `  <string>${xmlEscape(label)}</string>`,
+    '  <key>ProgramArguments</key>',
+    '  <array>',
+    args,
+    '  </array>',
+    '  <key>RunAtLoad</key>',
+    '  <true/>',
+    '  <key>KeepAlive</key>',
+    '  <false/>',
+  ];
+  if (logPath) {
+    lines.push('  <key>StandardOutPath</key>', `  <string>${xmlEscape(logPath)}</string>`);
+    lines.push('  <key>StandardErrorPath</key>', `  <string>${xmlEscape(logPath)}</string>`);
+  }
+  if (workingDirectory) {
+    lines.push('  <key>WorkingDirectory</key>', `  <string>${xmlEscape(workingDirectory)}</string>`);
+  }
+  const env = environment && typeof environment === 'object' ? environment : null;
+  if (env && Object.keys(env).length > 0) {
+    lines.push('  <key>EnvironmentVariables</key>', '  <dict>');
+    for (const [k, v] of Object.entries(env)) {
+      lines.push(`    <key>${xmlEscape(k)}</key>`, `    <string>${xmlEscape(v)}</string>`);
+    }
+    lines.push('  </dict>');
+  }
+  lines.push('</dict>', '</plist>', '');
+  return lines.join('\n');
+}
+
+// Parse the integer pid from `launchctl print gui/$UID/<label>` output. While
+// the job's process is alive the block contains a `pid = N` line; this resolves
+// it so the dashboard records the REAL provision pid into the sidecar `meta.pid`
+// (the field `reattachVerdict`'s `kill -0` re-attach reads) rather than the
+// launchctl invocation's own pid. Returns the integer pid, or null when there's
+// no live process line (job not started yet, already exited, or junk). `pid = 0`
+// is treated as no-pid. Pure: takes the text so it's testable without launchctl.
+function parseLaunchdPrintPid(text) {
+  const m = String(text == null ? '' : text).match(/^\s*pid\s*=\s*(\d+)\b/m);
+  if (!m) return null;
+  const pid = Number(m[1]);
+  return Number.isInteger(pid) && pid > 0 ? pid : null;
+}
+
+// Filter a captured transcript down to the live-card tail: drop the noisy
+// gcloud/IAP/NumPy lines and keep the last `maxLines`. Pure — the same shaping
+// startJob's `tailLog` applies to the setsid stdout pipe, extracted so the
+// launchd path's logfile tail and the setsid path share ONE tested filter
+// instead of duplicating the regex + slice.
+function filterTailLog(text, maxLines = 14) {
+  return String(text == null ? '' : text).split('\n')
+    .filter((l) => !/WARNING|NumPy|google\.com\/iap/.test(l))
+    .join('\n').trim().split('\n').slice(-maxLines).join('\n');
+}
+
+// True when a `spawnSync` result represents a successful launchctl invocation:
+// a defined result with a zero exit status and no spawn error (ENOENT etc.).
+// Pure — lets the bootstrap/`load -w` success checks be one tested predicate.
+function launchctlSpawnSucceeded(result) {
+  return !!result && result.status === 0 && !result.error;
+}
+
+// Decide what the launchd add-completion watcher should do on one tick, from the
+// durable signals it gathers: the exit marker's code (or null when absent),
+// whether the launchd process is still alive, and how many consecutive ticks it
+// has been gone. Pure state machine — the I/O (reading the marker, `kill -0`,
+// tailing the log) stays in the server.js watcher; this owns the decision so it
+// is exhaustively testable without launchd.
+//   - marker present                 → done, that exit code (the normal path)
+//   - process gone for `graceTicks`  → done, exit 1 (EXIT trap never wrote a
+//                                       marker — resolve the card as a failure
+//                                       rather than tailing forever)
+//   - process gone, under grace      → keep waiting, bump goneTicks
+//   - process alive                  → keep waiting, reset goneTicks
+function launchdWatchVerdict({ markerExitCode, pidAlive, goneTicks = 0, graceTicks = 3 } = {}) {
+  if (markerExitCode != null) return { done: true, exitCode: markerExitCode, goneTicks: 0 };
+  if (!pidAlive) {
+    const next = goneTicks + 1;
+    if (next >= graceTicks) return { done: true, exitCode: 1, goneTicks: next };
+    return { done: false, goneTicks: next };
+  }
+  return { done: false, goneTicks: 0 };
+}
+
+// Decide whether the own-launchd-job path should be taken for a spawn. Pure
+// gate: it's taken only for a `detached` add (the sole caller that passes
+// `detached`) AND on a host where `launchctl` is actually present. Everything
+// else — a non-detached job, or a host with no launchctl (cloud container / CI /
+// Linux) — falls back to the existing `setsid` detached spawn. Centralised here
+// so the gate is one tested predicate, not an inline `&&` at the spawn site.
+function shouldUseLaunchd({ detached, hasLaunchctl } = {}) {
+  return !!detached && !!hasLaunchctl;
+}
+
+module.exports = {
+  addVmLabel,
+  addVmJobLogPath,
+  xmlEscape,
+  buildAddVmPlist,
+  parseLaunchdPrintPid,
+  filterTailLog,
+  launchctlSpawnSucceeded,
+  launchdWatchVerdict,
+  shouldUseLaunchd,
+};