@codeyam-editor/codeyam-editor 0.1.2 → 0.1.4

package/npm/fleet-broker-debounce.js

@@ -0,0 +1,63 @@
+'use strict';
+// Pure consecutive-failure debounce for the Fleet Dashboard's broker tri-state
+// (scripts/operator/fleet-dashboard/server.js requires this). Given the raw
+// single-poll status from npm/fleet-broker-status.js::deriveBrokerStatus and the
+// per-VM debounce state from the previous poll, decide the status the card
+// actually renders. No I/O — server.js does the polling and threads the state.
+//
+// The bug this fixes (observed live 2026-06-02, VM3): the dashboard polls each
+// VM's broker every 3s, and the editor probes the broker with a single 200ms
+// socket attempt. One transient timeout (IAP / SSH-tunnel congestion — the same
+// class of hiccup behind the known false "Editor stopped") instantly flipped a
+// healthy VM's card to 'down', which raised both the red broker-down dot and the
+// 💀 death alarm, even though the broker was fine (the build tab opened and chat
+// started immediately). The single probe is left as-is on the editor side; the
+// right seam for absorbing a one-poll blip is here at the aggregation layer.
+//
+// Asymmetric by design: ONLY the flip to 'down' is debounced (it requires
+// `threshold` consecutive 'down' polls). 'idle' / 'agent-live' / 'unknown' take
+// effect immediately — we never want to DELAY clearing a false alarm, only
+// delay raising one. And an unreachable editor ('unknown') breaks a pending
+// down-streak rather than escalating it, mirroring fleet-broker-status.js's
+// "absence of evidence is never down" rule.
+//
+// State shape carried across polls: { status, downStreak, lastConfirmed }.
+//   status        — the debounced value the card renders this poll.
+//   downStreak    — how many consecutive raw 'down' polls we've seen.
+//   lastConfirmed — the last raw 'idle'/'agent-live' we proved; held during a
+//                   pending (sub-threshold) down-streak so the card stays calm.
+
+// ~9s at the dashboard's 3s poll cadence: comfortably absorbs a transient probe
+// timeout and the brief down-window of a routine restart-server (broker down for
+// <3s between SIGTERM and respawn), while still surfacing a real outage quickly.
+// Named so retuning is a one-line edit.
+const DOWN_DEBOUNCE_THRESHOLD = 3;
+
+function debounceBrokerStatus(prev, rawStatus, opts) {
+  const threshold = (opts && opts.threshold) || DOWN_DEBOUNCE_THRESHOLD;
+  const lastConfirmed = prev ? prev.lastConfirmed : undefined;
+
+  // Confirmed up: the daemon answered now. Render immediately, reset the streak,
+  // and remember this as the last-confirmed-up value.
+  if (rawStatus === 'idle' || rawStatus === 'agent-live') {
+    return { status: rawStatus, downStreak: 0, lastConfirmed: rawStatus };
+  }
+
+  // Editor unreachable: we proved nothing. Never down — reset any pending
+  // down-streak and render 'unknown' (the card shows nothing for it).
+  if (rawStatus !== 'down') {
+    return { status: 'unknown', downStreak: 0, lastConfirmed };
+  }
+
+  // Raw 'down': only a real outage if it persists. Count the streak.
+  const downStreak = (prev ? prev.downStreak : 0) + 1;
+  if (downStreak >= threshold) {
+    // Confirmed down — surface the alarm.
+    return { status: 'down', downStreak, lastConfirmed };
+  }
+  // Pending (sub-threshold) down: hold the last confirmed up status if we have
+  // one, else 'unknown'. The card stays calm during the blip.
+  return { status: lastConfirmed || 'unknown', downStreak, lastConfirmed };
+}
+
+module.exports = { debounceBrokerStatus, DOWN_DEBOUNCE_THRESHOLD };

package/npm/fleet-broker-status.js

@@ -0,0 +1,45 @@
+'use strict';
+// Pure tri-state derivation for the Fleet Dashboard's per-VM broker indicator
+// (scripts/operator/fleet-dashboard/server.js requires this). Given the raw
+// /api/session-info poll merge `v`, collapse it into the one label the card
+// renders. No I/O — server.js does the polling.
+//
+// The bug this fixes (observed live 2026-06-01): the old indicator was
+// `v.reachable ? !!v.agentBrokerLive : null`, where `agentBrokerLive` means
+// "a build-mode agent session is live in the broker" — NOT "broker daemon up".
+// So a perfectly IDLE VM (healthy broker daemon, no parked build agent) reported
+// `agentBrokerLive=false`, indistinguishable from a VM whose broker was actually
+// DOWN. An operator killed a working broker chasing that phantom. The editor now
+// also reports `brokerDaemonReachable` (the daemon answered its socket) and a
+// derived `brokerStatus`; this module layers the dashboard's own reachability on
+// top so the four states stay distinct:
+//
+//   'unknown'    — editor unreachable (can't probe the broker at all), OR an
+//                  older VM whose editor predates `brokerDaemonReachable`. Never
+//                  rendered as a problem: absence of evidence is not "down".
+//   'down'       — daemon unreachable → the real broker problem, the state that
+//                  had NO signal before. A VM here cannot start an agent session.
+//   'idle'       — daemon up, no build agent → a normal idle VM, not an error.
+//   'agent-live' — a live build-mode agent session in the broker's build slot.
+const BROKER_STATUSES = ['unknown', 'down', 'idle', 'agent-live'];
+
+function deriveBrokerStatus(v) {
+  // Editor unreachable: we polled nothing, so the broker state is unknowable.
+  // Reporting 'down' here is exactly the conflation that misled operators —
+  // an unreachable editor is not a dead broker.
+  if (!v || !v.reachable) return 'unknown';
+  // Prefer the editor's own tri-state when it reports one (newer VMs).
+  if (v.brokerStatus === 'down' || v.brokerStatus === 'idle' || v.brokerStatus === 'agent-live') {
+    return v.brokerStatus;
+  }
+  // Fallback derivation from the raw bits, for a VM reporting the bools but not
+  // the pre-derived `brokerStatus`. `agentBrokerLive` implies the daemon is up.
+  if (v.agentBrokerLive) return 'agent-live';
+  if (v.brokerDaemonReachable === true) return 'idle';
+  if (v.brokerDaemonReachable === false) return 'down';
+  // Older VM: reachable editor, but no broker-reachability field at all. Treat
+  // as 'unknown' (graceful fallback) — never falsely 'down'.
+  return 'unknown';
+}
+
+module.exports = { deriveBrokerStatus, BROKER_STATUSES };

package/npm/fleet-build-data.js

@@ -0,0 +1,81 @@
+'use strict';
+
+// Assemble the per-VM wire object the dashboard's /data response carries to the
+// browser. This is the single source of truth for a card's transport shape: the
+// card UI (scripts/operator/fleet-dashboard/public/index.html) reads `v.<field>`
+// off each entry, so every field the card renders MUST be emitted here.
+//
+// It was split out of server.js's buildData() so the shape is unit-testable.
+// The regression that motivated the split: `currentProvider` (the VM's
+// configured build agent) was merged onto the poll state AND read by the card to
+// render the 🤖 agent badge, but it was silently missing from this envelope — so
+// it lived in server memory and never reached the browser, and the badge never
+// appeared. A hand-maintained object literal inside a 197KB monolith has no
+// guard against that drift; a pure function does.
+//
+// `v` is the merged poll state (state.vms[n]). `ctx` carries the derived,
+// cross-VM, and side-effecting values buildData computes per VM (status,
+// debounced broker tri-state, reconciled job, queue position, launch cfg, …) —
+// the things this pure function can't know on its own.
+function buildVmEnvelope(v, ctx) {
+  return {
+    n: ctx.n,
+    url: v.url || null,
+    reachable: !!v.reachable,
+    hasSession: !!v.hasSession,
+    // Three-state: true = broker confirmed up, false = confirmed down, null =
+    // editor unreachable so broker state is unknown. Never conflate "down" with
+    // "unreachable" — that mismatch is what made the card show "broker down"
+    // while a direct pgrep proved the broker was up.
+    brokerLive: v.reachable ? !!v.agentBrokerLive : null,
+    // Broker tri-state: 'down' | 'idle' | 'agent-live' | 'unknown' (derived
+    // upstream, debounced). Richer than brokerLive's is-an-agent-live boolean.
+    brokerStatus: ctx.brokerStatus,
+    awaitingInput: !!v.awaitingUserInput,
+    feature: v.feature || null,
+    step: v.step != null ? v.step : null,
+    mode: v.mode || null,
+    label: v.label || null,
+    status: ctx.status,
+    orphan: ctx.orphan || null,
+    degradedReasons: ctx.degradedReasons || [],
+    isHead: !!ctx.isHead,
+    // True when this VM holds the queue head but is unreachable (operator
+    // decides manually whether to release it).
+    headHolderUnreachable: !!ctx.headHolderUnreachable,
+    queuePos: ctx.queuePos != null ? ctx.queuePos : null,
+    queueLen: ctx.queueLen,
+    job: ctx.job || null,
+    config: ctx.config || null,
+    project: ctx.project != null ? ctx.project : null,
+    variant: ctx.variant != null ? ctx.variant : null,
+    cardIdentity: ctx.cardIdentity,
+    brokerHistory: Array.isArray(v.brokerHistory) ? v.brokerHistory : [],
+    brokerDeath: ctx.brokerDeath,
+    // Auth state + reason + token expiry. Only surfaced when the editor is
+    // reachable (an unreachable VM's cached auth is stale and misleading).
+    providerAuth: v.reachable && v.providerAuth ? v.providerAuth : null,
+    effects: v.effects || null,
+    // The VM's live-configured build agent (lowercase provider), reported by
+    // /api/session-info and merged (sticky) onto the poll state. Drives the
+    // card's 🤖 agent badge. null for an older VM whose editor predates the
+    // field (the card omits the badge rather than rendering a blank chip).
+    currentProvider: v.currentProvider || null,
+  };
+}
+
+// The fields the card UI depends on being present in every /data VM entry. This
+// is the contract `buildVmEnvelope` must satisfy: the regression that prompted
+// this module was a field the card read but the envelope didn't emit, so the
+// test asserts the envelope keys are a superset of this list. Adding a field the
+// card renders means adding it here AND in buildVmEnvelope — the test fails loud
+// if you do one without the other.
+const REQUIRED_CARD_FIELDS = [
+  'n', 'url', 'reachable', 'hasSession', 'brokerLive', 'brokerStatus',
+  'awaitingInput', 'feature', 'step', 'mode', 'label', 'status', 'orphan',
+  'degradedReasons', 'isHead', 'headHolderUnreachable', 'queuePos', 'queueLen',
+  'job', 'config', 'project', 'variant', 'cardIdentity', 'brokerHistory',
+  'brokerDeath', 'providerAuth', 'effects', 'currentProvider',
+];
+
+module.exports = { buildVmEnvelope, REQUIRED_CARD_FIELDS };

package/npm/fleet-cleanup.js

@@ -76,31 +76,162 @@ function classifyDescribeError(err, stderr) {
 }
 
 // Decide what the startup reap should do for one sidecar. Pure: takes the
-// decoded sidecar + GCP-existence verdict + (for adds) container-up verdict,
-// returns a tag the caller dispatches on.
-//   verdict             when                                          dispatch
-//   'cleanup'           destroy gone, OR add gone                     runDestroyCleanup / runAddCleanup
-//   'reconcile-add'     add up AND container up                       ensure roster + recordLaunch, then clear
-//   'recover-bootstrap' add instance up but container missing/down    re-run cloud:up to finish the half-done bootstrap
-//   'clear-only'        destroy sidecar but instance still exists     just clear the sidecar
-//   'leave'             gcloud uncertain (exists === null)             leave for the next boot
-// The (exists, containerUp) split is what distinguishes a finished add from a
-// half-provisioned one: a dashboard SIGKILL'd mid-`cloud:up` leaves a GCP
+// decoded sidecar + GCP-existence verdict + (for adds) container-up verdict +
+// (for up adds) project-wiring verdict, returns a tag the caller dispatches on.
+//   verdict             when                                              dispatch
+//   'cleanup'           destroy gone, OR add gone                         runDestroyCleanup / runAddCleanup
+//   'reconcile-add'     add up, container up, project wired (or unknown)  ensure roster + recordLaunch, then clear
+//   'half-provisioned'  add up, container up, but project NOT wired       surface needs-recovery card (finish-wire from cfg)
+//   'recover-bootstrap' add instance up but container missing/down        re-run cloud:up to finish the half-done bootstrap
+//   'clear-only'        destroy sidecar but instance still exists         just clear the sidecar
+//   'leave'             gcloud uncertain (exists === null)                 leave for the next boot
+// The (exists, containerUp) split distinguishes a finished add from a container-
+// down half-provisioned one: a dashboard SIGKILL'd mid-`cloud:up` leaves a GCP
 // instance with no docker/container, which the old (exists-only) matrix wrongly
-// classified 'reconcile-add' — adding an unreachable VM to the roster.
-// `containerUp` is only consulted for an add whose instance exists; destroy and
-// the instance-gone add path ignore it. Splitting the matrix out lets the table
-// be exhaustively tested without any of the side-effects in server.js.
-function reapVerdict({ action, exists, containerUp }) {
+// classified 'reconcile-add' — adding an unreachable VM to the roster. The
+// `projectWired` axis closes the remaining gap (improve39 VM-7): an instance +
+// container that ARE up but whose `/workspace` is unwired (no git remote, empty
+// manifest) is NOT a finished add — it's half-provisioned and must surface a
+// recoverable card, not be silently reconciled "done". Only a POSITIVE unwired
+// signal (`projectWired === false`) downgrades to 'half-provisioned'; an
+// unknown/unprobed wiring (`null`/`undefined`) stays 'reconcile-add' so a flaky
+// probe can't strand a healthy VM. `containerUp`/`projectWired` are only consulted
+// for an add whose instance exists; destroy and the instance-gone add path ignore
+// them. Splitting the matrix out lets the table be exhaustively tested without any
+// of the side-effects in server.js.
+function reapVerdict({ action, exists, containerUp, projectWired }) {
   if (exists === null) return 'leave';
   if (action === 'destroy') return exists ? 'clear-only' : 'cleanup';
   if (action === 'add') {
     if (!exists) return 'cleanup';
-    return containerUp ? 'reconcile-add' : 'recover-bootstrap';
+    if (!containerUp) return 'recover-bootstrap';
+    return projectWired === false ? 'half-provisioned' : 'reconcile-add';
   }
   return 'leave';
 }
 
+// Classify whether a VM's editor `/workspace` is actually wired to a client
+// project, from a best-effort probe of two signals: the git remote URL and
+// whether `package.json` carries a real `name`. Pure: server.js runs the SSH +
+// `docker exec` probe and hands the raw stdout/err here so the decision is
+// unit-testable without a live VM.
+//   - err present (ssh/docker blip, timeout)        → null  (unknown — do NOT
+//     strand a healthy VM on a flaky probe; reapVerdict treats null as wired)
+//   - a git remote OR a non-empty package.json name → true  (wired)
+//   - neither (empty / no-git workspace)            → false (half-provisioned —
+//     the VM-7 signature: `/workspace` with no remote and an empty manifest)
+// The probe emits the two signals separated by the `---CY---` sentinel so this
+// parser is independent of locale/line-ending noise in the ssh transport.
+function classifyProjectWiring({ stdout, err } = {}) {
+  if (err) return null;
+  const parts = String(stdout == null ? '' : stdout).split('---CY---').map((s) => s.trim());
+  const remote = parts[0] || '';
+  const nameCount = Number((parts[1] || '0').trim()) || 0;
+  if (remote || nameCount > 0) return true;
+  return false;
+}
+
+// Durable exit marker for a detached `add` provision (improve40). The add's
+// `cloud:up` shell is spawned in its OWN session (detached) so a dashboard
+// SIGKILL — the 2GB launchd hard cap, exactly the kill that aborted the VM-7
+// add mid-flight — no longer reaches it; the provision keeps running. When that
+// detached shell finally exits it writes `add-<n>.exit` (its trailing exit code
+// + an ISO timestamp) into PENDING_JOBS_DIR, alongside the `add-<n>.json`
+// sidecar. The marker is the GROUND-TRUTH completion signal the next boot reads
+// instead of inferring `in-flight → error` from the lost child: a marker means
+// "the provision finished while the dashboard was away," its code says whether
+// it finished OK. The name is derived here so the shell `trap` (server.js) and
+// the JS reader build the exact same path.
+function exitMarkerName(n) {
+  return `add-${n}.exit`;
+}
+
+// Parse an exit-marker file body into { exitCode, finishedAt }, or null when the
+// body is missing/blank/malformed. Format is two lines — the numeric exit code
+// then an ISO timestamp — written by the shell trap. A non-integer first line is
+// treated as no-marker (null) so a half-written / corrupt marker falls back to
+// the gcloud reconcile path rather than being read as a bogus exit code. Pure:
+// takes the text so it's unit-testable without touching disk.
+function parseExitMarker(text) {
+  if (text == null) return null;
+  const lines = String(text).split('\n').map((s) => s.trim()).filter(Boolean);
+  if (!lines.length) return null;
+  const code = Number(lines[0]);
+  if (!Number.isInteger(code)) return null;
+  return { exitCode: code, finishedAt: lines[1] || null };
+}
+
+// Read VM-n's exit marker from `dir`, or null when it's absent/unreadable/
+// malformed (the still-running and never-written cases both surface as null).
+function readExitMarker(dir, n) {
+  try { return parseExitMarker(fs.readFileSync(path.join(dir, exitMarkerName(n)), 'utf8')); }
+  catch { return null; }
+}
+
+// Remove a consumed exit marker; a missing file is the already-cleared path, not
+// an error (mirrors clearPendingJob).
+function clearExitMarker(dir, n) {
+  try { fs.unlinkSync(path.join(dir, exitMarkerName(n))); }
+  catch (_) { /* missing is fine */ }
+}
+
+// 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
+//   '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
+// running, or finished while we were away) is classified from GROUND TRUTH, so
+// it is never blanket-converted `in-flight → error` the way the snapshot-only
+// path did (the improve39 VM-7 false `add-failed`). Only when the child is gone
+// AND left no parseable marker do we fall back to inferring state from gcloud —
+// `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.
+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';
+    return 'reconcile'; // marker present but no parseable code — let gcloud decide
+  }
+  if (childAlive) return 'running';
+  return 'reconcile';
+}
+
+// improve45 — map a reattachVerdict tag to the dashboard's NEXT action, now that
+// a clean exit marker is NECESSARY BUT NOT SUFFICIENT to roster. A detached
+// `cloud:up` can exit 0 AFTER the image build but BEFORE `docker compose up`
+// ever runs — an ssh broken-pipe or dashboard SIGKILL landing in that window,
+// with the wrapping EXIT trap still recording 0 (the live VM2 signature: built
+// image, repo cloned, ZERO editor containers). So 'done' no longer means "roster
+// it"; it means "confirm the container is actually up first." Both the clean-exit
+// ('done') and the no-usable-marker ('reconcile') cases therefore route through
+// the SAME gcloud container + wiring probe (reconcileViaGcloud → fc.reapVerdict),
+// which rosters only a genuinely-up + wired add and routes a half-provisioned one
+// to recover-bootstrap. 'error' (real non-zero exit) and 'running' (child still
+// alive) are unchanged. reattachVerdict stays the honest classifier of the
+// child's exit SIGNAL; this helper expresses how that signal is CONSUMED now that
+// exit-0 no longer implies rostering. Pure: server.js maps the returned action to
+// its side-effecting step, so the matrix is exhaustively testable without a VM.
+//   verdict       next step         meaning
+//   'done'        'probe'           confirm the container before rostering
+//   'reconcile'   'probe'           no usable marker — let the gcloud probe decide
+//   'error'       'surface-error'   real failure — show add-failed with the code
+//   'running'     'watch'           child still alive — keep polling for the marker
+function reattachNextStep(verdict) {
+  if (verdict === 'error') return 'surface-error';
+  if (verdict === 'running') return 'watch';
+  return 'probe'; // 'done' and 'reconcile' both confirm via the gcloud probe
+}
+
 // Anti-loop budget for the `recover-bootstrap` path. Pure: given the count of
 // recoveries ALREADY persisted on the sidecar, return the next attempt number,
 // whether the reap should proceed (re-run cloud:up) or treat the VM as
@@ -113,6 +244,66 @@ function recoverBootstrapDecision({ recoverAttempts, max = 3 }) {
   return { attempt, proceed: attempt <= max, max };
 }
 
+// improve40 — select the orphaned `add` jobs that must be reconciled from the
+// VM's REAL provision state even though their per-job sidecar is GONE. The
+// durable re-attach path (sidecar + exit marker + recorded pid) cannot fire for
+// these — a restart left only the snapshot record — so the snapshot job's
+// stashed `config` is the sole cfg source and a live gcloud probe is the only
+// ground truth. Pure: takes the restored jobs map + the set of `<action>-<n>`
+// sidecar keys the sidecar reap already owns; returns the [{ n, cfg }] the boot
+// path hands to reconcileViaGcloud. A job is selected when ALL hold:
+//   - it is an `add`,
+//   - it is flagged `restartOrphaned` (restoreFromSnapshot downgraded a
+//     running add → error because the dashboard restarted before it finished —
+//     this is the ONLY error state we re-probe; an add that failed IN-PROCESS
+//     carries a plain terminal `error` with no flag and stays surfaced), AND
+//   - NO `add-<n>` sidecar exists (a sidecar means the sidecar reap already
+//     owns it — never double-reconcile).
+// `cfg` rides from the job's `config`; null when the snapshot never carried one
+// (older snapshot) — the caller still probes, but a roster reconcile then can't
+// recordLaunch, exactly mirroring the sidecar path's `meta.cfg`-absent case.
+function orphanedAddsToReconcile({ jobs, sidecarKeys } = {}) {
+  const sidecars = sidecarKeys instanceof Set ? sidecarKeys : new Set(sidecarKeys || []);
+  const src = (jobs && typeof jobs === 'object') ? jobs : {};
+  const out = [];
+  for (const [k, j] of Object.entries(src)) {
+    if (!j || typeof j !== 'object') continue;
+    if (j.action !== 'add') continue;
+    if (!j.restartOrphaned) continue;
+    if (sidecars.has(`add-${k}`)) continue;
+    out.push({ n: Number(k), cfg: j.config || null });
+  }
+  return out;
+}
+
+// improve41 — the destroy-direction mirror of orphanedAddsToReconcile: decide
+// what to do with a VM that is STILL in the roster but whose GCP instance state
+// we have just re-probed. The bug this closes: a Destroy that races a dashboard
+// restart can leave the instance deleted while the startup reap took the
+// `clear-only` path (instance still present at reap time) and dropped the only
+// sidecar — so nothing ever runs roster cleanup and the VM polls forever
+// "unreachable." A sidecar-independent reconcile, keyed on REAL GCP existence
+// rather than on a pending-job sidecar, catches it. Pure: server.js runs the
+// gcloud describe (→ exists, via classifyDescribeError) and reads session /
+// pending-add state, and hands the three facts here so the matrix is testable
+// without a live VM.
+//   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)
+// 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.
+function reconcileRosteredVm({ exists, hasSession, hasPendingAdd } = {}) {
+  if (exists === null || exists === undefined) return "leave";
+  if (exists) return "keep";
+  if (hasSession || hasPendingAdd) return "leave";
+  return "cleanup";
+}
+
 module.exports = {
   parsePendingJobFilename,
   persistPendingJob,
@@ -120,5 +311,14 @@ module.exports = {
   listPendingJobs,
   classifyDescribeError,
   reapVerdict,
+  reconcileRosteredVm,
+  orphanedAddsToReconcile,
+  classifyProjectWiring,
   recoverBootstrapDecision,
+  exitMarkerName,
+  parseExitMarker,
+  readExitMarker,
+  clearExitMarker,
+  reattachVerdict,
+  reattachNextStep,
 };

package/npm/fleet-effect-status.js

@@ -0,0 +1,179 @@
+'use strict';
+// Pure predicate module for the Fleet Dashboard's per-button "will clicking
+// this change the VM, or is it already in that state?" indicators
+// (scripts/operator/fleet-dashboard/server.js requires this). Given an
+// already-gathered FACTS object — no I/O, no git/docker exec; server.js does
+// the impure fact-gathering — computeButtonEffects returns a per-button verdict
+// map. Mirrors the pure-module-plus-colocated-vitest-test shape of
+// npm/fleet-reset.js so the whole decision table is unit-testable without
+// spawning a process.
+//
+// Each verdict is { effect, reason }:
+//   - 'changes'     — clicking does something; `reason` says what.
+//   - 'noop'        — already in that state; clicking changes nothing.
+//   - 'recommended' — soft signal (run-setup only): a reset/update landed after
+//                     the last successful setup. NEVER a confident green no-op.
+//   - 'unknown'     — not yet checked, VM unreachable, or a needed fact is
+//                     missing. We never CLAIM a safe no-op we couldn't verify —
+//                     silent failure here would be worse than no indicator.
+//
+// The predicate for each button is derived from what that button actually
+// touches (its tooltip in public/index.html is the source of truth): the sync
+// buttons key off a git commit comparison, the reset buttons off
+// working-tree/session/`.codeyam` state, and rebuild off a build-commit
+// comparison.
+
+// Short sha for compact reason strings. Tolerates null / short input.
+function short(sha) {
+  return sha ? String(sha).slice(0, 7) : '?';
+}
+
+// "origin/<branch>" — or a bare "origin" when the branch is unknown.
+function originRef(branch) {
+  return branch ? `origin/${branch}` : 'origin';
+}
+
+// "N commit(s) behind origin/<branch>" with correct singular/plural.
+function behindReason(behind, branch) {
+  return `${behind} commit${behind === 1 ? '' : 's'} behind ${originRef(branch)}`;
+}
+
+// Compose a short reason listing which signals make a reset non-trivial, so the
+// operator sees WHAT a Reset would discard rather than a bare "changes". The
+// `agent` (a live build agent in the broker) leads the list — it's the most
+// consequential thing a reset's `pty-broker stop` would silently discard.
+function resetReason({ agent, session, dirty, behind, codeyam }) {
+  const parts = [];
+  if (agent) parts.push('running build agent');
+  if (dirty) parts.push('uncommitted changes');
+  if (behind) parts.push('source behind origin');
+  if (session) parts.push('active session');
+  if (codeyam) parts.push('.codeyam state');
+  return parts.length ? `will discard: ${parts.join(', ')}` : 'will reset state';
+}
+
+// The action ids governed by an effect indicator — the same ids server.js /
+// index.html use for the buttons. Reconfigure / Env / Destroy are deliberately
+// absent (one-shots, not converge-to-a-state actions, so a no-op predicate is
+// meaningless for them).
+const ACTION_IDS = [
+  'update-client-source',
+  'update-editor-source',
+  'reset-editor-source',
+  'reset-client',
+  'rebuild-binary',
+  'update-reset-everything',
+  'run-setup',
+];
+
+// facts (a plain object gathered by server.js — no I/O):
+//   {
+//     reachable: boolean,
+//     hasSession: boolean,
+//     client:  { headSha, originSha, behind, dirty } | null,     // /workspace
+//     editor:  { headSha, originSha, behind, dirty, buildCommit } | null,
+//     codeyamDirty: boolean,
+//     setupRanSince: boolean,        // a setup completed after the last reset/update
+//     clientBranch: string | null,   // for reason text only
+//     editorBranch: string | null,   // for reason text only
+//   }
+function computeButtonEffects(facts) {
+  const f = facts || {};
+
+  // Unreachable VM (or no facts at all): every governed button is unknown. We
+  // could not reach the editor to gather facts, so never render a green no-op.
+  if (!f.reachable) {
+    const out = {};
+    for (const id of ACTION_IDS) out[id] = { effect: 'unknown', reason: 'VM unreachable' };
+    return out;
+  }
+
+  const client = f.client || null;
+  const editor = f.editor || null;
+  const hasSession = !!f.hasSession;
+  const codeyamDirty = !!f.codeyamDirty;
+  // A live build agent in the broker. A reset's first step is `pty-broker stop`,
+  // which kills it regardless of whether a workflow session is registered — so
+  // this is discardable work even when hasSession is false. Explicit-true only:
+  // a null/absent value (older or unreachable VM) must NOT flip a genuine noop.
+  const brokerLive = f.brokerLive === true;
+
+  // (1) Update client — ff-advance /workspace to origin tip. Changes iff behind.
+  const updateClient = client == null
+    ? { effect: 'unknown', reason: 'client state not checked' }
+    : client.behind > 0
+      ? { 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.
+  const rebuild = (editor == null || !editor.buildCommit || !editor.originSha)
+    ? { effect: 'unknown', reason: 'binary/source commit not checked' }
+    : editor.buildCommit !== editor.originSha
+      ? { 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.
+  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.
+  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' };
+
+  // (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.
+  const everything = (() => {
+    if (editor == null || client == null) {
+      return { effect: 'unknown', reason: 'state not checked' };
+    }
+    const parts = [];
+    if (rebuild.effect === 'changes') parts.push('rebuild');
+    if (resetEditor.effect === 'changes') parts.push('reset editor');
+    if (client.behind > 0 || client.dirty) parts.push('reset client');
+    if (parts.length > 0) return { effect: 'changes', reason: parts.join(' + ') };
+    // No part would change. But if a component was itself unverifiable, don't
+    // claim a confident no-op — fall back to unknown.
+    if (rebuild.effect === 'unknown' || resetEditor.effect === 'unknown') {
+      return { effect: 'unknown', reason: 'state not checked' };
+    }
+    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,
+    'rebuild-binary': rebuild,
+    'update-reset-everything': everything,
+    'run-setup': runSetup,
+  };
+}
+
+module.exports = { computeButtonEffects, ACTION_IDS };