@codeyam-editor/codeyam-editor 0.1.4 → 0.1.6

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,312 @@ 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');
+}
+
+// The reset-family actions whose in-container recipe REBUILDS the codeyam-editor
+// binary before restart when the target is a self-host VM. Both resetClientScript
+// and resetEditorStateScript (default rebuildOnSelfHost=true) run selfHostRebuildStep,
+// so on a self-host VM either one triggers a full cargo compile (~10-14 min). The
+// composite reset-all budgets that rebuild separately; update-client (a non-destructive
+// ff-merge with NO rebuild/restart) is deliberately absent.
+const REBUILDS_ON_SELF_HOST = new Set(['reset-client', 'reset-editor']);
+
+// Default per-action SHORT budgets (ms) — the historical non-self-host timeout for
+// each reset action, kept so a genuine client-VM hang still surfaces promptly.
+const RESET_SHORT_TIMEOUT_MS = { 'reset-client': 300000, 'reset-editor': 600000 };
+// Default self-host REBUILD budget (ms): the same 27.5-min allowance reset-all
+// already uses for a self-host binary rebuild. Overridable via the rebuildMs arg
+// (server.js resolves it from RESET_REBUILD_TIMEOUT_MS).
+const RESET_REBUILD_TIMEOUT_MS = 1650000;
+
+// Select the startJob timeout (ms) for a reset-family action, accounting for the
+// self-host rebuild. On a self-host VM a rebuild-bearing reset (see
+// REBUILDS_ON_SELF_HOST) advances the editor's OWN source and MUST rebuild the
+// binary before restart, a ~10-14 min cargo compile the old flat 5-min budget
+// killed mid-compile — surfacing a false `error` badge on a reset that actually
+// succeeded. A non-self-host client reset genuinely does not rebuild and keeps its
+// short budget. Pure: budgets default to the constants above but are injectable for
+// env-tunability + tests. Unknown/non-rebuild action or non-self-host → short budget.
+function resetJobTimeoutMs({ action, selfHost, shortMs, rebuildMs } = {}) {
+  const short = Number.isFinite(shortMs) ? shortMs : RESET_SHORT_TIMEOUT_MS[action];
+  const rebuild = Number.isFinite(rebuildMs) ? rebuildMs : RESET_REBUILD_TIMEOUT_MS;
+  return selfHost && REBUILDS_ON_SELF_HOST.has(action) ? rebuild : short;
+}
+
 module.exports = {
   codeyamDeepCleanSteps,
   codeyamBrokerEnsureStep,
+  selfHostRebuildStep,
+  verifyServingProjectOrFlagReconfigureStep,
+  needsReconfigureFallback,
   resetClientScript,
   resetEditorStateScript,
+  endSessionScript,
+  verifyIdleOrEndSessionStep,
+  resetJobTimeoutMs,
+  REBUILDS_ON_SELF_HOST,
 };

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-running-plan.js

@@ -0,0 +1,85 @@
+'use strict';
+
+// Resolve the running-plan fields a fleet card shows — feature, step, mode,
+// selectedPlan, holderSessionId — from the two independent per-VM probes plus
+// the last-known-good state.
+//
+// Why this exists: the card used to hang these fields off `/api/session-info`
+// alone (spread as `...info` in server.js). But a VM whose editor server
+// restarted while the PTY broker kept the agent alive reports
+// `hasSession:false` / `sessionId:null` and session-info then OMITS
+// feature/step/mode/selectedPlan — so an actively-building VM showed a BLANK
+// card. `GET /api/step` reads `editor-step.json` directly, independent of
+// session registration, so it stays populated across that restart. This helper
+// makes `/api/step` the preferred source and falls back to session-info.
+//
+// Stickiness — the subtle part. The last-known `prev` is carried ONLY to bridge
+// a genuine probe failure (the editor answered NOTHING this poll), so a single
+// timed-out cycle can't blank a plan the card is already showing. It is NOT a
+// blanket fallback: when the editor DID answer, the fresh read is authoritative
+// for the plan the VM is executing NOW. Carrying prev unconditionally pinned a
+// COMPLETED plan's feature onto the next one — feature-complete deletes
+// editor-step.json (reset_step_state), and a plan's `feature` is null until
+// step 4, so a stale prev would win over the correct null and the card kept
+// showing plan A while the VM built plan B. So prev is carried only within the
+// SAME plan (matching selectedPlan); a plan change (or going idle) drops it.
+//
+// Precedence per field, when the editor answered: `/api/step` (session-
+// independent) > `/api/session-info` > same-plan `prev`. On a full probe
+// failure: `prev` verbatim. Pure; no I/O — unit-tested in
+// fleet-running-plan.test.js.
+//
+// @param {Object} params
+// @param {?Object} params.step  Parsed `/api/step` body (EditorStepState) or
+//   null when the VM has no `editor-step.json` (idle) / the probe failed.
+// @param {?Object} params.info  Parsed `/api/session-info` body (carries
+//   `reachable`), or null on a failed/timed-out probe.
+// @param {?Object} params.prev  The previous `state.vms[n]` (carries the
+//   last-known feature/step/mode/selectedPlan/holderSessionId). null/undefined
+//   on the first poll.
+// @returns {{feature: ?string, step: ?number, mode: ?string,
+//   selectedPlan: ?string, holderSessionId: ?string}}
+function resolveRunningPlan({ step, info, prev } = {}) {
+  const s = step || {};
+  const i = info || {};
+  const p = prev || {};
+
+  // Did the editor answer at all this poll? `/api/step` returning a body proves
+  // it; so does a reachable `/api/session-info`. If NEITHER answered, this is a
+  // transient outage — hold the last-known-good plan verbatim rather than blank
+  // the card for one cycle.
+  const editorAnswered = step != null || !!i.reachable;
+  if (!editorAnswered) {
+    return {
+      feature: p.feature || null,
+      step: p.step != null ? p.step : null,
+      mode: p.mode || null,
+      selectedPlan: p.selectedPlan || null,
+      holderSessionId: p.holderSessionId || null,
+    };
+  }
+
+  // Editor answered: the fresh read is authoritative for the current plan.
+  const freshSelectedPlan = s.selectedPlan || i.selectedPlan || null;
+  // Carry prev ONLY within the same plan — a blip-fallback for a momentarily
+  // missing field (e.g. /api/step timed out but session-info answered). Across
+  // a plan change or an idle poll, prev is stale and MUST be dropped.
+  const samePlan = freshSelectedPlan != null && freshSelectedPlan === (p.selectedPlan || null);
+  const carry = samePlan ? p : {};
+
+  const stepNum =
+    s.step != null ? s.step : i.step != null ? i.step : carry.step != null ? carry.step : null;
+
+  return {
+    feature: s.feature || i.feature || carry.feature || null,
+    step: stepNum,
+    mode: s.mode || i.mode || carry.mode || null,
+    selectedPlan: freshSelectedPlan || carry.selectedPlan || null,
+    // session-info never carries holderSessionId — it comes from /api/step
+    // (editor-step.json) or the same-plan carry. This is what lets a claim map
+    // to the executing VM after an editor restart drops the live sessionId.
+    holderSessionId: s.holderSessionId || carry.holderSessionId || null,
+  };
+}
+
+module.exports = { resolveRunningPlan };