@codeyam-editor/codeyam-editor 0.1.4 → 0.1.5

package/npm/fleet-reconcile.js

@@ -33,6 +33,32 @@ function computeUnrostered(running, shown) {
     .sort((a, b) => a - b);
 }
 
+// Streak bookkeeping for the adopt-direction stranded-instance reconcile — the
+// mirror of pollVanishedInstances' `unreachableStreak` gate, in the opposite
+// (adopt) direction. Given the currently-stranded VM numbers (running in GCP
+// but absent from roster / provisioning / orphan), the prior streak map, and
+// the threshold, return the NEXT streak map (incremented for each still-stranded
+// number; entries for no-longer-stranded numbers dropped so a transient blip
+// never leaves a stale count) plus `ready` — the numbers whose streak has
+// reached the threshold and may now be auto-finished. A single stale
+// `runningFleetVms` snapshot therefore can't trigger a recovery: the instance
+// must read stranded for `threshold` consecutive polls first. Pure, so the gate
+// is unit-tested without gcloud or a running server.
+function strandedAdoptDecision({ stranded, streaks, threshold } = {}) {
+  const prev = streaks || {};
+  const t = Number(threshold) > 0 ? Number(threshold) : 1;
+  const present = [...new Set((stranded || []).filter((n) => Number.isInteger(n) && n > 0))];
+  const next = {};
+  const ready = [];
+  for (const n of present) {
+    const count = (Number(prev[n]) || 0) + 1;
+    next[n] = count;
+    if (count >= t) ready.push(n);
+  }
+  ready.sort((a, b) => a - b);
+  return { streaks: next, ready };
+}
+
 // Map a single degraded reason to the live health signal that resolves it.
 // Returns true only when that signal now passes; a reason with no mapped signal
 // returns false (retained — a genuine config problem, never a false-green).
@@ -90,4 +116,20 @@ function reconcileTerminalAddBadge({ job, health } = {}) {
   return null;
 }
 
-module.exports = { parseRunningFleetVms, computeUnrostered, reconcileTerminalAddBadge };
+// Self-heal for the slug sidecar: given the slug map (`{ "<N>": "<slug>" }`) and
+// the roster (the live VM numbers), return the sorted, de-duped VM numbers whose
+// slug entry should be released because the VM is no longer rostered. A
+// destroyed VM is removed from the roster, so any slug still keyed to a
+// non-rostered number is stranded (e.g. a destroy path that failed to call
+// `removeSlug`) and would otherwise block re-using that name forever. Pure: the
+// caller reads the sidecar + roster (I/O at the edge) and applies `removeSlug`
+// to each returned number. Tolerates a null/absent slug map and an empty roster.
+function pruneOrphanSlugs({ slugs, roster } = {}) {
+  const rostered = new Set((roster || []).filter(Number.isInteger));
+  const orphans = Object.keys(slugs || {})
+    .map((k) => Number(k))
+    .filter((n) => Number.isInteger(n) && n > 0 && !rostered.has(n));
+  return [...new Set(orphans)].sort((a, b) => a - b);
+}
+
+module.exports = { parseRunningFleetVms, computeUnrostered, strandedAdoptDecision, reconcileTerminalAddBadge, pruneOrphanSlugs };

package/npm/fleet-reset.js

@@ -123,11 +123,15 @@ function codeyamBrokerEnsureStep(E) {
 }
 
 // Build the in-container bash for "Reset client" — hard-clean the CLIENT
-// project (/workspace) on ANY VM shape. The decisions encoded here:
-//   - Reset to HEAD, NOT origin: `git reset --hard` (bare) discards uncommitted
-//     churn but PRESERVES committed work. Advancing to origin tip is the
-//     separate "Update client" action — this must never `git fetch`/reset to
-//     `origin/<branch>`.
+// project (/workspace) on ANY VM shape, advancing to origin tip. The decisions
+// encoded here:
+//   - Advance to ORIGIN tip: fetch + `reset --hard origin/<branch>` (the same
+//     shape resetEditorStateScript uses), so the working tree ends clean AT the
+//     origin tip. This discards uncommitted churn AND unpushed commits — more
+//     destructive than the old reset-to-HEAD; the card's confirm dialog warns
+//     about the unpushed-commit loss. A greenfield local-only repo (no origin)
+//     falls back to a bare `git reset --hard` to HEAD. The non-destructive
+//     ff-to-tip-that-keeps-the-session path is the separate "Update client".
 //   - `git reset --hard` leaves untracked files, so node_modules + a per-VM
 //     .env survive (no forced re-install / lost secrets).
 //   - Stop the broker FIRST so abandoned agent WIP can't be re-written to disk
@@ -145,18 +149,34 @@ function resetClientScript({ E, gitReseedBody }) {
     'echo ">> [1/5] stopping agent session"',
     `(${E} editor pty-broker stop || true)`,
     '(git config --local --unset-all credential.helper || true)',
-    'echo ">> [2/5] discarding uncommitted changes (git reset --hard to HEAD; keeps committed work + untracked files)"',
-    'git reset --hard',
+    'if git remote | grep -qx origin; then ' +
+      'BR=$(git branch --show-current); ' +
+      'echo ">> [2/5] advancing client to origin tip (git fetch + reset --hard origin/$BR; discards uncommitted AND unpushed; keeps untracked files)"; ' +
+      'git reset --hard && git fetch origin "$BR" && git reset --hard "origin/$BR"; ' +
+    'else echo ">> [2/5] no origin remote (greenfield) — git reset --hard to HEAD"; git reset --hard; fi',
     'echo ">> [3/5] deep-cleaning .codeyam (clears ignored runtime state; keeps editor.local.json + server-state.json)"',
     ...codeyamDeepCleanSteps(E),
     `${E} editor session-reset`,
-    'echo ">> [4/5] restarting server to respawn the broker (no rebuild)"',
+    // Self-host: client === editor, so a client reset advances /workspace (the
+    // editor source) and MUST rebuild before restart or the binary↔source
+    // mismatch loops. No-op off self-host (the client /workspace is the client
+    // app, not the editor source). See selfHostRebuildStep.
+    selfHostRebuildStep(E),
+    'echo ">> [4/5] restarting server to respawn the broker"',
     `(${E} editor restart-server --force-in-container || true)`,
     // Belt-and-suspenders: ensure a broker is live even on an older binary
     // whose restart-server doesn't yet respawn it. Idempotent / status-gated.
     codeyamBrokerEnsureStep(E),
     'echo ">> [5/5] re-seeding git credential cache"',
     `( ( ${gitReseedBody} ) || echo "WARN git cache re-seed failed" )`,
+    // Terminal contract guard: the reset PROMISES idle, so verify it and end any
+    // agent that slipped back after the restart/broker-ensure. No-op when the
+    // reset already reached idle. See verifyIdleOrEndSessionStep.
+    verifyIdleOrEndSessionStep({ E }),
+    // Verify the editor came back SERVING THE PROJECT on :14199 (not stranded in
+    // launcher mode); on a self-host strand emit CY_NEEDS_RECONFIGURE so the
+    // dashboard auto-falls-back to reconfigure.
+    verifyServingProjectOrFlagReconfigureStep(),
   ].join(' && ');
 }
 
@@ -174,7 +194,12 @@ function resetClientScript({ E, gitReseedBody }) {
 // `git reset --hard` / `rm -rf .codeyam`. The composite action relies on this
 // same gate as its safety contract — a failed rebuild that leaves no binary
 // will short-circuit the trailing recipe before any wipe happens.
-function resetEditorStateScript({ E }) {
+// `rebuildOnSelfHost` (default true): rebuild the binary before the final
+// restart when this is a self-host VM (see selfHostRebuildStep). The composite
+// update-reset-everything passes `false` because its leading
+// rebuildBinaryHostScript already rebuilt — a second cargo build would be a
+// ~5-8 min no-op.
+function resetEditorStateScript({ E, rebuildOnSelfHost = true } = {}) {
   return [
     'cd /workspace',
     `command -v ${E} >/dev/null`,
@@ -203,20 +228,280 @@ function resetEditorStateScript({ E }) {
     'echo ">> [3/4] deep-cleaning .codeyam (clears ignored state; keeps editor.local.json + server-state.json)"',
     ...codeyamDeepCleanSteps(E),
     `${E} editor session-reset`,
-    // No rebuild here (that's Rebuild binary). Restart the server in place to
-    // respawn the broker we stopped: restart-server SIGUSR1s pid 1 and the
-    // docker-exec returns cleanly, so `|| true` keeps a broker-down VM green.
-    'echo ">> [4/4] restarting server to respawn the broker (no rebuild)"',
+    // Self-host VMs build the binary from /workspace, so a reset that advanced
+    // source MUST rebuild before restarting or the binary↔source mismatch sends
+    // the editor into a stale-binary reexec loop. No-op off self-host (the
+    // binary is shipped). Skipped when the composite already rebuilt.
+    ...(rebuildOnSelfHost ? [selfHostRebuildStep(E)] : []),
+    // Restart the server in place to respawn the broker we stopped (now on a
+    // binary that matches the advanced source on self-host): restart-server
+    // SIGUSR1s pid 1 and the docker-exec returns cleanly, so `|| true` keeps a
+    // broker-down VM green.
+    'echo ">> [4/4] restarting server to respawn the broker"',
     `(${E} editor restart-server --force-in-container || true)`,
     // Belt-and-suspenders: ensure a broker is live even on an older binary
     // whose restart-server doesn't yet respawn it. Idempotent / status-gated.
     codeyamBrokerEnsureStep(E),
+    // Terminal contract guard: the reset PROMISES idle, so verify it and end any
+    // agent that slipped back after the restart/broker-ensure. No-op when the
+    // reset already reached idle. See verifyIdleOrEndSessionStep.
+    verifyIdleOrEndSessionStep({ E }),
+    // Verify the editor came back SERVING THE PROJECT on :14199 (not stranded in
+    // launcher mode on an ephemeral port); on a self-host strand emit
+    // CY_NEEDS_RECONFIGURE so the dashboard auto-falls-back to reconfigure.
+    verifyServingProjectOrFlagReconfigureStep(),
   ].join(' && ');
 }
 
+// Build the in-container bash for "End session" — the MINIMAL "stop the agent"
+// primitive. Unlike the reset family this does NOT advance source, deep-clean
+// .codeyam, or rebuild: it kills the live agent process and clears the
+// session-specific state files, taking the VM from a live `waiting`/`building`
+// session back to a true `idle` in seconds.
+//
+// The recipe takes the VM to idle (`hasSession:false`) while leaving a BARE
+// broker daemon ready for the next run:
+//   - `pty-broker stop` SIGTERMs the broker daemon, which kills the live agent.
+//     Fail-soft (`|| true`): a VM with no broker running legitimately exits
+//     non-zero (crates/codeyam-editor/src/commands/editor/pty_broker.rs), and a
+//     no-op end must not abort the chain.
+//   - `session-reset` deletes the session-specific state files (no resume
+//     target) so the still-running editor server's view drops to no-session.
+//   - codeyamBrokerEnsureStep respawns a BARE daemon (no agent attached) — only
+//     if none is reachable. Order matters: stop → reset → ensure, so the
+//     ensure can never re-bind stale session state.
+//
+// Why ensure a bare daemon instead of leaving the broker down: End session
+// means "no agent session," NOT "no broker at all." The Build-tab terminal
+// WebSocket handler does NOT respawn the broker on connect — if the daemon is
+// down, `attach_or_spawn` fails with "PTY broker unreachable"
+// (crates/control-api/src/terminal.rs). So leaving the broker down means the
+// next Run / Build-tab open errors until the watchdog catches up. A bare daemon
+// (broker alive, zero sessions) still reports `hasSession:false` → status
+// `idle`, and lets the next `attach_or_spawn` attach instantly and spawn a
+// fresh agent. The builder unit test asserts the chain ends with the daemon
+// ensure and contains NO `restart-server`.
+//
+// CRITICAL: there is NO `restart-server` here. `restart-server` deliberately
+// reattaches the surviving/respawned broker session and brings the agent back
+// (crates/codeyam-editor/src/commands/editor/restart_server.rs), which would
+// undo the end. codeyamBrokerEnsureStep, by contrast, never attaches an agent —
+// it only spawns a bare daemon.
+function endSessionScript({ E }) {
+  return [
+    'cd /workspace',
+    // Binary-existence gate FIRST, mirroring the reset builders.
+    `command -v ${E} >/dev/null`,
+    `(${E} editor pty-broker stop || true)`,
+    `${E} editor session-reset`,
+    // Respawn a BARE daemon (no agent) so the next Run / Build-tab open attaches
+    // instantly. Status-gated + idempotent, and NOT restart-server (no resume).
+    codeyamBrokerEnsureStep(E),
+  ].join(' && ');
+}
+
+// Build the TERMINAL "verify idle, end the agent if one slipped back" step,
+// appended as the LAST step of every reset recipe. This is the contract fix for
+// `vm: Resets Must Land at Idle`: the reset actions ("Reset client", "Reset
+// editor", "Reset all + rebuild") all promise to drop the agent and return the
+// VM to a fresh-provision state, but in practice a live Claude agent came back
+// resumed at the Plan step after the reset's trailing restart-server +
+// codeyamBrokerEnsureStep — so the dashboard card read `waiting` instead of
+// `idle` (observed live on VM-4).
+//
+// Diagnosis note (the fix is MECHANISM-AGNOSTIC on purpose): the reset already
+// STOPS the broker before the wipe (codeyamDeepCleanSteps) and runs
+// session-reset, so the agent is killed mid-reset; it reappears only because of
+// the trailing restart-server + broker-ensure — the same two steps
+// endSessionScript deliberately OMITS to land at idle (see its idle-end
+// invariant test). The EXACT re-attach path — restart-server's in-place SIGUSR1
+// reexec resuming a session, the broker-ensure respawn the server then attaches
+// an agent to, or the editor server auto-resuming a workflow on startup — was
+// NOT reproduced on a scratch cloud VM in the authoring environment, so rather
+// than guess at one we make the reset TERMINALLY VERIFY idle regardless of which
+// path fires: read /api/session-info from the now-running server and, if it
+// still reports an active session (`hasSession: true`) OR a live build-slot
+// broker agent (`agentBrokerLive: true`), end the session with the proven
+// endSessionScript primitive (`pty-broker stop` + `session-reset`, with NO
+// further restart). The EITHER condition exactly mirrors the editor UI's
+// Build-dot clear condition in useBuildSessionLive (the dot clears only when
+// `!hasSession && !agentBrokerLive`): a reset that left a live build-slot agent
+// in the broker — the `fresh_branch_surfaces_agent_broker_live_true` server
+// shape, `hasSession:false` + `agentBrokerLive:true` — previously slipped past a
+// `hasSession`-only check, reading "idle" on the dashboard while the editor UI
+// Build dot stayed lit. Gating on either signal closes that gap (and
+// `pty-broker stop` is what drops `agentBrokerLive` to false). Robust even if a
+// future change reintroduces a resume path, and a no-op on the happy path where
+// the reset already reached idle (the bare broker daemon from
+// codeyamBrokerEnsureStep stays up — which reads idle, both signals false).
+//
+// Stack assumption: in-container the editor server's control port is the
+// preserved server-state.json `controlPort` (rewritten by restart-server),
+// falling back to the standard 14199 — the same port the rebuild verify curls
+// (scripts/operator/fleet-dashboard/server.js). server-state.json survives the
+// deep-clean wipe (codeyamDeepCleanSteps cp's it aside and restores it).
+//
+// SETTLE-WINDOW POLL (vm: Resets Stay at Idle After restart-server Reattach):
+// a single point-in-time probe loses a race. The reset family ends with
+// `restart-server --force-in-container`, which is DESIGNED to reattach the
+// surviving broker session and bring the agent back asynchronously
+// (crates/codeyam-editor/src/commands/editor/restart_server.rs:29-33) — a beat
+// AFTER this terminal guard's first curl already saw `hasSession:false` and
+// declared idle. Observed live on VM-3/VM-6 (2026-06-22): the reset-client job
+// logged `>> reset reached idle` then ~90s later `/data` reported
+// `status=building, hasSession=true`. The one-shot check won the probe but lost
+// the race. endSessionScript lands at idle reliably ONLY because it omits
+// restart-server; the reset NEEDS restart-server to respawn the broker / advance
+// the binary, so it must DEFEAT the reattach rather than avoid it.
+//
+// The fix keeps every property of the single-probe guard above (mechanism-
+// agnostic `hasSession || agentBrokerLive` grep, the reused endSessionScript
+// primitive with NO restart-server, the `( …; true )` non-fatal wrapper, the
+// server-state.json controlPort resolution) and turns "checked once, too early"
+// into "checked until stable": a bounded loop probes /api/session-info
+// PROBE_COUNT times (~1s apart), and on ANY probe where a session or live broker
+// agent reappears it ends it with endSessionScript (`pty-broker stop` +
+// `session-reset`, NEVER another restart) and keeps probing — so a late reattach,
+// or even a second one within the window, is each caught. The window outlasts
+// restart-server's async reattach (a few seconds) without stretching the reset.
+// On the happy path (already idle and stays idle) every probe reads idle, zero
+// endSession calls fire, and it ends with the same `reset reached idle` line as
+// before — a no-op, same as the old single probe.
+//
+// Wrapped in `( …; true )` so a curl/parse hiccup mid-window can never abort the
+// reset's &&-chain, exactly like codeyamBrokerEnsureStep.
+function verifyIdleOrEndSessionStep({ E, controlPort = 14199 }) {
+  const end = endSessionScript({ E });
+  // Settle-window budget. Kept as named locals so the builder test can assert the
+  // loop is bounded and a tuning change is a one-line edit. PROBE_COUNT probes
+  // PROBE_SLEEP_SECS apart ⇒ ~7s window — long enough to outlast restart-server's
+  // async reattach, short enough not to stretch the reset job.
+  const PROBE_COUNT = 8;
+  const PROBE_SLEEP_SECS = 1;
+  const probe = `si=$(curl -sf "http://127.0.0.1:$PORT/api/session-info" 2>/dev/null || true)`;
+  const sessionLiveGate = `printf '%s' "$si" | grep -qE '"(hasSession|agentBrokerLive)"[[:space:]]*:[[:space:]]*true'`;
+  const reattachMsg =
+    '">> reset left a session or live broker agent attached — ending the session to land at idle"';
+  return (
+    `( PORT=$(grep -oE '"controlPort"[^0-9]*[0-9]+' .codeyam/server-state.json 2>/dev/null | grep -oE '[0-9]+$' | head -1); ` +
+    `PORT=\${PORT:-${controlPort}}; ` +
+    // Settle window: probe up to PROBE_COUNT times; end any session/agent that
+    // reattaches on each probe and keep polling, so a late (or double) reattach
+    // after restart-server is caught instead of slipping past a single probe.
+    `i=0; while [ "$i" -lt ${PROBE_COUNT} ]; do ` +
+    `${probe}; ` +
+    `if ${sessionLiveGate}; then echo ${reattachMsg}; ${end}; fi; ` +
+    `i=$((i+1)); [ "$i" -lt ${PROBE_COUNT} ] && sleep ${PROBE_SLEEP_SECS}; ` +
+    `done; ` +
+    // Confirming trailing probe — the window has now outlasted the async
+    // reattach, so this read is the authoritative idle verdict. End once more if
+    // a session somehow survived the final loop iteration; otherwise declare idle.
+    `${probe}; ` +
+    `if ${sessionLiveGate}; then echo ${reattachMsg}; ${end}; ` +
+    `else echo ">> reset reached idle (no session, no live broker agent)"; fi; true )`
+  );
+}
+
+// REBUILD-BEFORE-RESTART on a self-host VM. The reset family advances source to
+// origin tip; on a self-host VM (the client project IS codeyam-editor, so
+// /workspace/Cargo.toml exists) the binary is BUILT from /workspace, so a reset
+// that advances source without rebuilding deterministically produces a
+// binary↔source mismatch — and the editor, deciding it's stale, enters a
+// reexec/rebuild loop. So before the final restart we rebuild the binary in
+// place (`rebuild-self`, the same mechanism rebuildBinaryHostScript uses). The
+// self-host axis is detected at RUNTIME with the same `/workspace/Cargo.toml`
+// probe rebuildBinaryHostScript uses, so the NON-self-host path — where the
+// editor binary is shipped, not built from the client repo — keeps its fast
+// "(no rebuild)" restart untouched.
+//
+// Stack assumption: only a self-host VM has /workspace/Cargo.toml AND builds its
+// own binary; a normal client project's /workspace is the client's app, never
+// the editor source, so the probe is false and this is a silent no-op there.
+//
+// Fail-soft: a `rebuild-self` failure `|| echo WARN`s rather than aborting the
+// reset's &&-chain — restarting on the prior (un-advanced-binary) build is
+// recoverable (the restart-server full-restart fallback makes the stale-binary
+// loop non-fatal), and the trailing serving-probe still flags reconfigure if the
+// editor doesn't come back. The whole step is wrapped so it can never break the
+// chain.
+function selfHostRebuildStep(E) {
+  return (
+    '( if test -f /workspace/Cargo.toml; then ' +
+    'echo ">> self-host VM — rebuilding binary before restart so it matches the advanced source (cargo ~5-8 min)"; ' +
+    `${E} editor rebuild-self --force-in-container || echo "WARN self-host rebuild-self failed — restart may hit the stale-binary reexec path"; ` +
+    'fi; true )'
+  );
+}
+
+// POST-RESET SERVING PROBE — verify the editor came back SERVING THE PROJECT on
+// :14199, and on a self-host VM flag an auto-reconfigure if it didn't. The
+// Project Launcher binds an EPHEMERAL port (never :14199 — see
+// crates/codeyam-editor/src/commands/launcher/server.rs `TcpListener::bind(…, 0)`),
+// so a launcher-mode strand — or a server that never came back — shows up
+// identically: :14199 stops answering /api/health. (The serve-on-:14199 fix in
+// start.rs::decide_launch prevents the strand at the source; this is the
+// belt-and-suspenders that turns a residual strand into an automatic recovery
+// instead of a hand-run reconfigure.)
+//
+// On a self-host VM that isn't serving :14199, emit the `CY_NEEDS_RECONFIGURE`
+// marker the dashboard's job-completion handler reacts to by auto-running
+// reconfigure (the proven container-recreate recovery). Off self-host we only
+// WARN: reconfigure's container recreate is the wrong hammer for a shipped-binary
+// client VM, so the operator decides.
+//
+// Reuses the server-state.json controlPort resolution (falling back to 14199)
+// exactly like verifyIdleOrEndSessionStep, and is wrapped in `( …; true )` so a
+// curl hiccup can never abort the reset's &&-chain.
+function verifyServingProjectOrFlagReconfigureStep({ controlPort = 14199 } = {}) {
+  // ~30s window — long enough for restart-server's async respawn to bind the
+  // port, short enough not to stretch the reset job.
+  const PROBE_COUNT = 15;
+  const PROBE_SLEEP_SECS = 2;
+  // VERIFY-AFTER-REBUILD (VM-4 2026-06-25): a rebuild that produces a binary and
+  // answers /api/health on :14199 is NOT proof the fix took — the launcher, when
+  // it lands from the boot decision, binds the CONTROL port (so `npm run editor`
+  // finds it) and ALSO serves /api/health, so /api/health alone can't tell a
+  // serving editor from a launcher strand sitting ON :14199. /api/projects is
+  // launcher-ONLY (the editor serves /api/session-info, never /api/projects) and
+  // returns JSON, so a launcher signature ON the control port means the strand
+  // SURVIVED the rebuild — treat it as a FAILURE (emit the reconfigure marker),
+  // never as success. This makes "serves the PROJECT on :14199" the hard
+  // post-condition, not merely "something answers /api/health".
+  const launcherOnPort =
+    'body=$(curl -sf --max-time 2 "http://127.0.0.1:$PORT/api/projects" 2>/dev/null); ' +
+    'case "$body" in "["*|"{"*) true;; *) false;; esac';
+  return (
+    `( PORT=$(grep -oE '"controlPort"[^0-9]*[0-9]+' .codeyam/server-state.json 2>/dev/null | grep -oE '[0-9]+$' | head -1); ` +
+    `PORT=\${PORT:-${controlPort}}; ` +
+    `serving=0; launchered=0; i=0; while [ "$i" -lt ${PROBE_COUNT} ]; do ` +
+    'if curl -sf "http://127.0.0.1:$PORT/api/health" >/dev/null 2>&1; then ' +
+    `if ${launcherOnPort}; then launchered=1; else serving=1; break; fi; fi; ` +
+    `i=$((i+1)); sleep ${PROBE_SLEEP_SECS}; done; ` +
+    'if [ "$serving" = "1" ]; then echo ">> editor serving project on :$PORT"; ' +
+    'elif test -f /workspace/Cargo.toml; then ' +
+    'echo "CY_NEEDS_RECONFIGURE self-host editor not serving project on :$PORT after reset ($([ "$launchered" = "1" ] && echo "launcher-mode strand ON the control port — rebuild did not adopt the guard" || echo "launcher-mode strand or server down") ) — falling back to reconfigure"; ' +
+    'else echo "WARN editor not serving project on :$PORT after reset — check the VM"; fi; true )'
+  );
+}
+
+// Pure predicate the dashboard's job-completion handler uses to decide whether a
+// finished reset must auto-fall-back to reconfigure: true iff the job log
+// carries the `CY_NEEDS_RECONFIGURE` marker emitted by
+// verifyServingProjectOrFlagReconfigureStep (self-host, didn't come back serving
+// :14199). Kept here as a pure function of the log string so the decision is
+// unit-tested without the gcloud/docker dispatch.
+function needsReconfigureFallback(log) {
+  return typeof log === 'string' && log.includes('CY_NEEDS_RECONFIGURE');
+}
+
 module.exports = {
   codeyamDeepCleanSteps,
   codeyamBrokerEnsureStep,
+  selfHostRebuildStep,
+  verifyServingProjectOrFlagReconfigureStep,
+  needsReconfigureFallback,
   resetClientScript,
   resetEditorStateScript,
+  endSessionScript,
+  verifyIdleOrEndSessionStep,
 };

package/npm/fleet-roster.js

@@ -31,16 +31,14 @@ function normalizeRoster(arr) {
   return [...new Set((arr || []).filter(Number.isInteger))].sort((a, b) => a - b);
 }
 
-// Read the roster, returning a normalized integer array. A missing or malformed
-// file is treated as the empty roster `[]` (the documented contract the previous
-// `readRoster`/`loadVmsState` duplicates shared) so a truncated write or an
-// absent file never throws into a consumer's poll loop.
+// Read the roster, returning a normalized integer array, or null if the file is
+// missing or malformed.
 function readRoster() {
   try {
     const data = JSON.parse(fs.readFileSync(VMS_STATE_FILE, 'utf8'));
     if (Array.isArray(data)) return normalizeRoster(data);
-  } catch { /* missing or malformed — treated as empty */ }
-  return [];
+  } catch { /* missing or malformed */ }
+  return null;
 }
 
 // Persist `arr` as the roster, atomically: write a temp file then `rename` it
@@ -62,13 +60,13 @@ function writeRoster(arr) {
 // onSuccess rosters again — is a harmless no-op, which is exactly what closes
 // the race where one writer's roster write could fail.
 function addToRoster(n) {
-  return writeRoster([...readRoster(), n]);
+  return writeRoster([...(readRoster() || []), n]);
 }
 
 // Remove `n` from the roster, returning the new roster. Removing an absent
 // entry is a no-op.
 function removeFromRoster(n) {
-  return writeRoster(readRoster().filter((x) => x !== n));
+  return writeRoster((readRoster() || []).filter((x) => x !== n));
 }
 
 module.exports = {

package/npm/fleet-self-update.js

@@ -0,0 +1,142 @@
+'use strict';
+// Pure decision + bash-script composition for the dashboard's SELF-update action
+// (scripts/operator/fleet-dashboard/server.js requires this). Mirrors the
+// fleet-branch.js / fleet-reset.js pattern: string + decision logic only, no I/O
+// (no git exec, no env detection, no `exec`), so the self-update *recipe* — what
+// the detached bash actually does to pull the dashboard's own checkout to tip and
+// which supervisor it restarts through — stays unit-testable in isolation
+// (npm/fleet-self-update.test.js). server.js owns the I/O: current-branch read,
+// `id -u`, FLEET_ON_GCE detection, and the detached `exec`.
+//
+// The dashboard's Node half is plain source (it `require`s server.js +
+// npm/fleet-*.js from REPO_ROOT at boot, no compile step), so refreshing *it* is
+// just "pull new source + restart the node process". Both supervisors auto-respawn
+// on exit (systemd Restart=always, launchd KeepAlive), so the restart is a clean
+// hand-off. But the dashboard also depends on the Rust `codeyam-editor` binary at
+// runtime — `pollPlans` shells out to `codeyam-editor editor plans-snapshot` for the
+// Queued-Plans origin view — so a self-update that advances editor source past a
+// changed/new subcommand must rebuild the binary too, or the JS moves while a stale
+// binary keeps erroring. buildSelfUpdateScript therefore rebuilds the binary, but
+// only when editor source actually changed across the update and fail-soft so a
+// build problem never blocks the restart.
+
+const { cleanBranch } = require('./fleet-branch');
+
+// Single-quote a value for safe bash interpolation — identical to server.js's
+// `shq`, duplicated here so this module stays a pure, dependency-light leaf (it
+// must not require the untestable server shell).
+function shq(s) {
+  return `'${String(s).replace(/'/g, `'\\''`)}'`;
+}
+
+// A branch name we're willing to hand to `git checkout` / `git reset --hard`.
+// git's own ref rules are broader, but the dashboard only ever targets ordinary
+// fleet branches, so we accept a conservative charset (letters, digits, and the
+// `._/-` that real branch names use) and reject everything else. This is the
+// belt to shq's suspenders: even though every interpolated value is quoted, an
+// up-front reject turns an injection attempt / typo into a clear `{ok:false}`
+// instead of a script that runs and fails deep in the detached child.
+function isSafeBranch(b) {
+  return /^[A-Za-z0-9._/-]+$/.test(b) && !b.includes('..');
+}
+
+// Decide whether a self-update request is actionable and on which branch.
+//   - `alreadyRunning` (a self-update already in flight) is refused first, so the
+//     in-flight guard is part of the tested decision rather than action branching.
+//   - A blank requested branch falls back to the dashboard's current branch
+//     (the modal prefills the current branch, but an operator can clear it).
+//   - An unsafe / empty resulting branch is rejected with a clear `msg`.
+// Pure; no I/O. Returns `{ ok, branch, msg }`. Keeping the guard + resolution +
+// validation here lets server.js's actionUpdateDashboard stay a thin I/O shell.
+function decideSelfUpdate({ requestedBranch, currentBranch, alreadyRunning } = {}) {
+  if (alreadyRunning) {
+    return { ok: false, msg: 'dashboard update already running' };
+  }
+  const branch = cleanBranch(requestedBranch) || cleanBranch(currentBranch);
+  if (!branch) {
+    return { ok: false, msg: 'self-update: no branch given and current branch is unknown' };
+  }
+  if (!isSafeBranch(branch)) {
+    return { ok: false, msg: `self-update: invalid branch name '${branch}'` };
+  }
+  return { ok: true, branch, msg: `updating dashboard to ${branch}` };
+}
+
+// The supervisor-appropriate restart command. The dashboard restarting itself
+// kills the very process serving the request, so this runs inside the detached
+// child (see buildSelfUpdateScript). Selection:
+//   - GCE operator host (systemd) → `sudo systemctl restart codeyam-dashboard`
+//     (needs a passwordless sudoers drop-in; see the plan's provisioning note).
+//   - laptop (launchd)            → `launchctl kickstart -k gui/<uid>/<label>`
+//   - bare-nohup fallback         → `<repoRoot>/scripts/operator/fleet-dashboard/start.sh`
+// The non-GCE path tries launchd first and falls back to start.sh in one `||`
+// chain, so a laptop with no launchd agent (a bare `nohup node server.js`) still
+// restarts. start.sh is idempotent (kills the port, re-execs node).
+function restartCommand({ onGce, launchdUid, label, repoRoot }) {
+  if (onGce) return 'sudo systemctl restart codeyam-dashboard';
+  const target = shq(`gui/${launchdUid}/${label}`);
+  const startSh = shq(`${repoRoot}/scripts/operator/fleet-dashboard/start.sh`);
+  return `launchctl kickstart -k ${target} || ${startSh}`;
+}
+
+// Compose the bash the detached child runs: pull the dashboard's own checkout to
+// the tip of `branch`, conditionally rebuild the editor binary, then restart
+// through the environment-appropriate supervisor. Hard-reset semantics
+// (operator's choice): always land exactly on `origin/<branch>`, discarding any
+// uncommitted/divergent state on the dashboard checkout. Bails loudly if the
+// branch doesn't exist on origin (nothing is reset/restarted).
+//
+// Rebuild gating (between the reset and the restart): record the pre-reset HEAD,
+// compare it to the post-reset HEAD restricted to the editor source paths, and
+// rebuild only when something under `crates`/`Cargo.toml`/`Cargo.lock` actually
+// moved — a JS-only update must not pay a multi-minute Rust compile. The rebuild
+// is additionally gated on `codeyam-editor` being on PATH so a host without the
+// toolchain skips cleanly, and is fail-soft (`|| echo …`) so a build failure can't
+// abort the `set -e` script before the restart: a degraded-but-running dashboard
+// beats a wedged one. The restart stays last and unconditional.
+//
+// Every interpolated value is shq-quoted. Pure; no I/O.
+function buildSelfUpdateScript({ repoRoot, branch, onGce, launchdUid, label } = {}) {
+  const R = shq(repoRoot);
+  const B = shq(branch);
+  const originRef = shq(`origin/${branch}`);
+  const restart = restartCommand({ onGce, launchdUid, label, repoRoot });
+  return [
+    'set -e',
+    `echo ">> self-update: fetching origin in ${repoRoot}"`,
+    `git -C ${R} fetch origin`,
+    // Verify origin/<branch> exists BEFORE touching the working tree, so a typo'd
+    // / unknown branch bails with nothing reset or restarted.
+    `git -C ${R} rev-parse --verify ${originRef} >/dev/null 2>&1 || ` +
+      `{ echo "self-update: origin/${branch} not found" >&2; exit 1; }`,
+    // Record the editor-source revision BEFORE the reset, so we can tell after
+    // whether the editor binary needs rebuilding. Read-only; touches nothing.
+    `OLD=$(git -C ${R} rev-parse HEAD)`,
+    `echo ">> self-update: checking out ${branch}"`,
+    // DWIM creates a local tracking branch when one doesn't exist yet; a no-op
+    // when already on it.
+    `git -C ${R} checkout ${B}`,
+    `echo ">> self-update: hard-reset to origin/${branch} (discards local changes)"`,
+    `git -C ${R} reset --hard ${originRef}`,
+    `NEW=$(git -C ${R} rev-parse HEAD)`,
+    // Rebuild the editor binary, but only when (a) editor source actually moved
+    // and (b) the binary is on PATH. The `git diff --quiet … -- crates …` exits 0
+    // when nothing under the editor source paths changed → skip (the fast JS-only
+    // path). `command -v` skips a toolchain-less host. The rebuild itself is
+    // fail-soft so a build failure still falls through to the restart. Each guard
+    // sits in an `if`/`elif` condition, where a non-zero exit is allowed under
+    // `set -e`.
+    `if git -C ${R} diff --quiet "$OLD" "$NEW" -- crates Cargo.toml Cargo.lock; then ` +
+      `echo ">> self-update: skipping rebuild (no editor source change)"; ` +
+      `elif ! command -v codeyam-editor >/dev/null 2>&1; then ` +
+      `echo ">> self-update: skipping rebuild (codeyam-editor not on PATH)"; ` +
+      `else echo ">> self-update: editor source changed — rebuilding binary"; ` +
+      `codeyam-editor editor rebuild-self || ` +
+      `echo ">> self-update: rebuild-self FAILED — continuing to restart with the existing binary" >&2; ` +
+      `fi`,
+    `echo ">> self-update: restarting dashboard"`,
+    restart,
+  ].join('\n');
+}
+
+module.exports = { shq, isSafeBranch, decideSelfUpdate, restartCommand, buildSelfUpdateScript };