@codeyam-editor/codeyam-editor 0.1.3 → 0.1.5

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,
+};

package/npm/fleet-live-status.js

@@ -0,0 +1,123 @@
+'use strict';
+// Pure session/broker live-status derivation for the Fleet Dashboard's per-VM
+// status LABEL (scripts/operator/fleet-dashboard/server.js requires this). This
+// is the trailing decision of deriveStatus, after every heavy-job / orphan /
+// failed-badge branch has been ruled out: given the reachable VM's session and
+// broker signals, is it building, waiting, or genuinely idle?
+//
+// The bug this fixes (observed live 2026-06-20, VM-1): the label was derived
+// SOLELY from `hasSession` — the editor server's own in-process build-session
+// flag. But a Claude agent's lifetime is owned by the PTY broker, deliberately
+// DECOUPLED from the editor-server lifetime (see docs/process-model.md). After a
+// server restart, or for a broker-resumed/detached agent the server didn't spawn
+// itself, `hasSession` is false while a fully-live agent keeps working in the
+// broker. The card fell through to 'idle' even though the broker dot — driven by
+// the same `brokerStatus` — already showed 'agent-live'. The label and the dot
+// disagreed.
+//
+// The fix consults the already-debounced broker tri-state (from
+// fleet-broker-status.js, threaded in by the caller) so a broker-held live agent
+// reads as working, not idle. `awaitingUserInput` is honored independent of
+// `hasSession`, so a broker-live agent blocked on input reads 'waiting'.
+//
+// The terminal-done refinement (observed live 2026-06-21): a broker-live agent
+// whose WORKFLOW reached its terminal step is parked alive at its prompt but is
+// NOT building — the editor masks the feature and reports `needsCleanup: true`
+// (session_info_response.rs). Without this signal the card showed an active-green
+// "Building" border on a finished, idle VM. We discriminate on `needsCleanup`
+// (a positive terminal signal) rather than feature-emptiness (also briefly true
+// at session START, which would mislabel a just-starting agent as done). This
+// only ever DOWNGRADES a would-be-'building' verdict to 'session-done'; a
+// mid-feature post-restart agent is not terminal (`needsCleanup` falsy) and stays
+// 'building', preserving the 2026-06-20 decoupled-agent fix above.
+//
+// Returns 'waiting' | 'building' | 'session-done' | 'idle' for a reachable VM, or
+// `null` when the VM is unreachable — the caller maps null to its own
+// asleep/unreachable verdict (it owns the running-fleet snapshot this module
+// deliberately does not touch) and otherwise passes the verdict through verbatim
+// as the card's `status`, so 'session-done' must match the card's status class.
+// Precedence is preserved: an unreachable VM returns null regardless of a stale
+// 'agent-live', so the broker branch only ever upgrades a would-be-idle verdict.
+function liveSessionStatus(v, brokerStatus) {
+  // Unreachable: we polled nothing reliable. Defer to the caller's
+  // asleep/unreachable mapping — a stale broker signal must not mask it.
+  if (!v.reachable) return null;
+  if (v.hasSession && v.awaitingUserInput) return 'waiting';
+  if (v.hasSession) return 'building';
+  // No editor-owned session, but a live agent may still be working in the PTY
+  // broker (decoupled lifetime — see docs/process-model.md). The broker
+  // tri-state is already debounced upstream; agent-live ⇒ working, not idle.
+  if (brokerStatus === 'agent-live') {
+    if (v.awaitingUserInput) return 'waiting';
+    // The agent is parked alive in the broker's build slot, but its workflow
+    // reached the terminal step (editor reports needsCleanup) — finished and
+    // idle, not building. A mid-feature post-restart agent is NOT terminal and
+    // still reads 'building' (preserves the 2026-06-20 decoupled-agent fix).
+    if (v.needsCleanup) return 'session-done';
+    return 'building';
+  }
+  return 'idle';
+}
+
+// Distinguish a freshly-rostered VM whose editor is still STARTING UP — a normal
+// cold boot that hasn't bound :14199 yet, or (the VM-2 case) the ~10–15-min
+// self-host `rebuild-self --force-in-container` compile that recompiles the
+// editor binary from source before the server can listen — from a genuinely DEAD
+// one. deriveStatus (scripts/operator/fleet-dashboard/server.js) calls this only
+// after it has already established the VM is rostered, unreachable, and GCP still
+// lists it RUNNING — i.e. exactly the case that otherwise falls through to the
+// red 'unreachable' that made a successful Add look like a failure.
+//
+// Returns 'editor-starting' when EITHER the VM was launched within the grace
+// window (`recentlyLaunched` — the cheap common case, no SSH needed) OR an
+// in-container probe has CONFIRMED a first-run build is still running
+// (`probeBuilding === true`), which lets the long self-host compile keep reading
+// "Starting editor…" past the window with no fragile fixed timeout. Returns null
+// otherwise so deriveStatus runs its existing unreachable path unchanged — an
+// honest red card the moment the grace window lapses with no confirmed build. A
+// DISTINCT key from the wake-path 'starting' (fleet-sleep-status.js) so the two
+// in-progress states never collide. Pure; the caller owns the time + SSH I/O.
+function classifyStartingVsUnreachable({ recentlyLaunched = false, probeBuilding = null } = {}) {
+  if (recentlyLaunched || probeBuilding === true) return 'editor-starting';
+  return null;
+}
+
+// Classify the in-container startup probe (server.js's editorStartingInContainer
+// one-IAP-SSH round-trip) into the tri-state the verdict cache stores and
+// classifyStartingVsUnreachable consumes. Mirrors fleet-cleanup.js's
+// classifyProjectWiring shape: takes the raw `{ stdout, err }` and parses the
+// three `---CY---`-separated segments the probe emits — the `docker ps` status
+// line, the count of listeners on :14199, and the count of live first-run build
+// processes (`rebuild-self` / `cargo build`):
+//   true  — container up, :14199 NOT yet bound, and a build process is alive ⇒
+//           still building (keeps the card calm-blue past the grace window).
+//   false — container up but :14199 already bound (the normal reachable path
+//           will win) OR up-and-idle with no build process (let the card flip to
+//           honest 'unreachable'); also a clean response with the container down.
+//   null  — an ssh/docker blip (`err`) ⇒ inconclusive; never upgrades a
+//           past-window card (stays honest), re-probed next poll.
+function classifyStartupProbe({ stdout, err } = {}) {
+  if (err) return null;
+  const parts = String(stdout == null ? '' : stdout).split('---CY---').map((s) => s.trim());
+  const containerUp = /^Up\b/m.test(parts[0] || '');
+  const portBound = (Number((parts[1] || '0').trim()) || 0) > 0;
+  const buildProcAlive = (Number((parts[2] || '0').trim()) || 0) > 0;
+  if (!containerUp) return false; // clean response, container down → not building
+  if (portBound) return false; // already serving — the reachable path owns it
+  return buildProcAlive ? true : false;
+}
+
+// Pure gate deciding whether pollStartupProbes should fire the (costly) IAP-SSH
+// build probe for a given VM this tick. We only probe a VM that is PLAUSIBLY
+// still starting — present, unreachable, GCP still lists it RUNNING, NOT already
+// owned by an active heavy job, and either recently launched OR already confirmed
+// building on a prior tick (so a ~15-min self-host compile keeps being probed
+// past the grace window with no fixed cap). A healthy/reachable VM, an
+// asleep/vanished one, or a long-idle one that simply went unreachable is never
+// probed. Pure so pollStartupProbes stays a thin SSH loop and this decision
+// matrix is exhaustively unit-testable without booting the server.
+function shouldProbeStartup({ vmPresent = false, reachable = false, gcpRunning = false, jobActive = false, recentlyLaunched = false, wasBuilding = false } = {}) {
+  return vmPresent && !reachable && gcpRunning && !jobActive && (recentlyLaunched || wasBuilding);
+}
+
+module.exports = { liveSessionStatus, classifyStartingVsUnreachable, classifyStartupProbe, shouldProbeStartup };

package/npm/fleet-plans.js

@@ -0,0 +1,231 @@
+'use strict';
+
+/**
+ * Indexes the currently-reachable VMs by their live sessionId.
+ * @param {Array|Object} vms The merged VM states on the dashboard.
+ * @returns {Object} A map of sessionId -> VM number (n).
+ */
+function indexVmsBySessionId(vms) {
+  const map = {};
+  if (!vms) return map;
+  const list = Array.isArray(vms) ? vms : Object.values(vms);
+  for (const vm of list) {
+    if (vm && vm.sessionId && vm.n !== undefined) {
+      map[vm.sessionId] = vm.n;
+    }
+  }
+  return map;
+}
+
+/**
+ * Computes which dependencies are unsatisfied (i.e. not in the completedSlugs set).
+ * @param {string[]} dependsOn Prerequisite slugs.
+ * @param {Set|string[]} completedSlugs Set or array of completed plan slugs.
+ * @returns {string[]} The unsatisfied dependency slugs.
+ */
+function unsatisfiedDeps(dependsOn, completedSlugs) {
+  const deps = Array.isArray(dependsOn) ? dependsOn : [];
+  const completedSet = completedSlugs instanceof Set ? completedSlugs : new Set(completedSlugs || []);
+  return deps.filter(dep => !completedSet.has(dep));
+}
+
+/**
+ * Resolves claims and dependency states for each queued plan.
+ * @param {Object} params
+ * @param {Object[]} params.plans Array of PlanSummary objects from /api/plans.
+ * @param {Object[]} params.claims Array of PlanClaim objects from /api/plan-claims.
+ * @param {Set|string[]} params.completedSlugs Completed plan slugs.
+ * @param {Object} params.vmsBySessionId Map of sessionId -> VM number.
+ * @returns {Object[]} Annotated plan rows.
+ */
+function resolvePlanRows({ plans, claims, completedSlugs, vmsBySessionId }) {
+  const list = Array.isArray(plans) ? plans : [];
+  const claimsList = Array.isArray(claims) ? claims : [];
+
+  return list.map(plan => {
+    // 1. Extract plan fields
+    const slug = plan.slug;
+    const title = plan.title;
+    const mode = plan.mode || null;
+    const order = plan.order != null ? plan.order : null;
+    const prefix = plan.prefix || null;
+
+    // 2. Resolve dependency-blocked state
+    const dependsOn = Array.isArray(plan.depends_on) ? plan.depends_on : (plan.dependsOn ? plan.dependsOn : []);
+    const blockedBy = unsatisfiedDeps(dependsOn, completedSlugs);
+
+    // 3. Resolve claim state
+    const claim = claimsList.find(c => c.slug === slug);
+    let claimInfo = null;
+    if (claim) {
+      const claimedBy = claim.claimedBy || claim.claimed_by || {};
+      const sessionId = claimedBy.sessionId || claimedBy.session_id || null;
+      const vm = (sessionId && vmsBySessionId && vmsBySessionId[sessionId] !== undefined) ? vmsBySessionId[sessionId] : null;
+      
+      claimInfo = {
+        vm,
+        machine: claimedBy.machine || null,
+        agent: claimedBy.agentProvider || claimedBy.agent_provider || null,
+        sessionAlive: claim.sessionAlive !== undefined ? claim.sessionAlive : (claim.session_alive !== undefined ? claim.session_alive : null),
+        source: claim.source || null,
+        currentStep: claimedBy.currentStep || claimedBy.current_step || null,
+      };
+    }
+
+    return {
+      slug,
+      title,
+      mode,
+      order,
+      prefix,
+      blockedBy,
+      claim: claimInfo
+    };
+  });
+}
+
+const REQUIRED_PLAN_ROW_FIELDS = [
+  'slug', 'title', 'mode', 'order', 'prefix', 'blockedBy', 'claim'
+];
+
+/**
+ * Decides which data source a project's Queued Plans panel should read from.
+ * The dashboard's own project (codeyam-editor) reads plans fresh from origin
+ * via the laptop checkout; every other project keeps the VM probe.
+ * @param {Object} params
+ * @param {string} params.project The project name for the panel.
+ * @param {?string} params.selfHostProject The dashboard's own project name.
+ * @returns {'origin'|'vm'} The source to use.
+ */
+function planSourceForProject({ project, selfHostProject }) {
+  return selfHostProject && project === selfHostProject ? 'origin' : 'vm';
+}
+
+/**
+ * Builds the static (non-ticking) part of a Queued Plans panel header label so
+ * the data source and its staleness risk are always visible. Origin-sourced
+ * panels name the branch + short sha; VM-sourced panels carry the "may lag
+ * origin" caveat. The relative age ("· 8s ago") is appended by the frontend's
+ * own ago ticker, so this returns the static prefix only.
+ * @param {Object} params
+ * @param {'origin'|'vm'} params.source Where the panel's data came from.
+ * @param {?string} params.ref The git ref (e.g. "origin/<branch>") for origin.
+ * @param {?string} params.sha The full commit sha for origin.
+ * @param {?number} params.fromVm The representative VM number for vm source.
+ * @param {?('stale-binary'|'fetch-failed'|'parse-error'|'unknown')} params.originError
+ *   When the self-host origin path was *attempted* and failed, the classified
+ *   reason it fell back to the VM probe. Absent/null for ordinary VM-sourced
+ *   projects (which were never meant to read origin).
+ * @returns {string} The static header annotation.
+ */
+function planPanelSourceLabel({ source, ref, sha, fromVm, originError }) {
+  if (source === 'origin') {
+    const shortSha = sha ? String(sha).slice(0, 7) : '?';
+    const where = ref || 'origin';
+    return `${where} @ ${shortSha}`;
+  }
+  // VM-sourced: surface the residual lag risk the origin path eliminates.
+  const vm = (fromVm !== null && fromVm !== undefined) ? `VM-${fromVm}` : 'VM';
+  if (originError) {
+    // The origin path was attempted and failed: this is a *degraded* panel, not
+    // a normal VM-sourced one. Name the failure class so it is self-diagnosing.
+    return `via ${vm} · origin unavailable: ${originErrorPhrase(originError)}`;
+  }
+  return `via ${vm} · may lag origin`;
+}
+
+/**
+ * Maps a classified origin-failure bucket to a short operator-facing phrase for
+ * the panel header. Mirrors the bucket set of classifyOriginError; an unknown
+ * bucket degrades to the generic "origin read failed" phrase.
+ * @param {string} originError The classified bucket.
+ * @returns {string} A short human-readable phrase.
+ */
+function originErrorPhrase(originError) {
+  switch (originError) {
+    case 'stale-binary':
+      return 'stale editor binary';
+    case 'fetch-failed':
+      return 'git fetch failed';
+    case 'parse-error':
+      return 'bad snapshot output';
+    default:
+      return 'origin read failed';
+  }
+}
+
+/**
+ * Classifies a caught origin-path error message into a small, stable set of
+ * buckets the operator can act on, rather than surfacing a noisy raw error
+ * (which can carry paths/branch names) in the panel header. Pure so it is
+ * unit-testable.
+ *   - `unrecognized subcommand`        → 'stale-binary'  (CLI predates the command)
+ *   - leading `git fetch origin`       → 'fetch-failed'  (couldn't reach origin)
+ *   - no-JSON / malformed snapshot     → 'parse-error'   (plans-snapshot output)
+ *   - anything else                    → 'unknown'
+ * @param {?string} message The caught error's message text.
+ * @returns {'stale-binary'|'fetch-failed'|'parse-error'|'unknown'}
+ */
+function classifyOriginError(message) {
+  const msg = typeof message === 'string' ? message : '';
+  if (msg.includes('unrecognized subcommand')) return 'stale-binary';
+  if (/^git fetch origin\b/.test(msg)) return 'fetch-failed';
+  if (msg.includes('plans-snapshot produced no JSON') ||
+      msg.includes('plans-snapshot JSON parse')) return 'parse-error';
+  return 'unknown';
+}
+
+/**
+ * True when an origin-fetch error means the branch no longer exists on the
+ * remote — it was merged and deleted, so `git fetch origin <branch>` fails with
+ * git's `couldn't find remote ref <branch>`. This is NOT a transient fetch
+ * failure (network / auth): the branch is *gone*, so re-fetching it every poll
+ * cycle is pure noise. The dashboard uses this to record the branch as gone,
+ * fall back to the VM probe quietly, and stop logging an error every cycle —
+ * the difference between a healthy fleet that *reads* broken in the log and one
+ * that reads calm. Pure so it is unit-testable.
+ * @param {?string} message The caught fetch-error message text.
+ * @returns {boolean}
+ */
+function isRemoteRefGone(message) {
+  const msg = typeof message === 'string' ? message : '';
+  return /couldn't find remote ref/i.test(msg);
+}
+
+/**
+ * Parses the stdout of `editor plans-snapshot --format json` into the snapshot
+ * envelope the dashboard consumes. The pure half of snapshotPlansFromOrigin:
+ * extracts the JSON object (the CLI may prefix a dev-build banner), parses it,
+ * and normalizes missing arrays to []. Throws a descriptive error on no-JSON
+ * or malformed-JSON so the caller can fall back to the VM probe.
+ * @param {string} stdout The plans-snapshot CLI stdout.
+ * @returns {{ref: string, sha: string, plans: Object[], completedSlugs: string[]}}
+ */
+function parsePlansSnapshotStdout(stdout) {
+  const m = stdout && stdout.match(/\{[\s\S]*\}/);
+  if (!m) throw new Error('plans-snapshot produced no JSON');
+  let data;
+  try {
+    data = JSON.parse(m[0]);
+  } catch (e) {
+    throw new Error(`plans-snapshot JSON parse: ${e.message}`);
+  }
+  return {
+    ref: data.ref,
+    sha: data.sha,
+    plans: data.plans || [],
+    completedSlugs: data.completedSlugs || [],
+  };
+}
+
+module.exports = {
+  indexVmsBySessionId,
+  unsatisfiedDeps,
+  resolvePlanRows,
+  planSourceForProject,
+  planPanelSourceLabel,
+  classifyOriginError,
+  isRemoteRefGone,
+  parsePlansSnapshotStdout,
+  REQUIRED_PLAN_ROW_FIELDS
+};