@codeyam-editor/codeyam-editor 0.1.3 → 0.1.5

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

package/npm/fleet-setup-steps.js

@@ -0,0 +1,105 @@
+'use strict';
+
+// npm/fleet-setup-steps.js — partition a VM's degradedReasons into expected
+// first-run SETUP steps vs genuine ATTENTION problems for the fleet dashboard
+// (vm: Dashboard 'Finishing setup' state for expected add steps).
+//
+// A clean greenfield Add lands with a wall of amber `⚠ Add degraded` badges
+// because every unfinished post-provision wiring step is funneled into one flat
+// `degradedReasons` string array and rendered identically. There is no
+// distinction between *expected first-run setup that just hasn't finished yet*
+// (Claude login not seeded, ingress host-rule not wired, project dir still the
+// scaffold `workspace`, no start command on a brand-new project) and *something
+// that actually broke* (broker death, half-provisioned orphan, off-branch
+// drift). This module draws that line: it parses the existing reason-code
+// prefixes and classifies each reason as a calm `setup` step or an `attention`
+// problem, keeping the rules in a tested pure function the way fleet-job-badge.js
+// / fleet-public-url.js do — server.js stays thin and the card colors finally
+// tell the truth (blue = still wiring up, amber = look at this).
+//
+// Stack note: this is fleet-operator infrastructure (the GCE fleet that runs
+// codeyam-editor itself), GCP-specific by design — the same posture as the
+// scripts it backstops. The classification is pure string parsing, no network,
+// so it unit-tests with no fixtures.
+
+// The setup-step codes this module emits. A single source so server.js and the
+// card UI agree on the vocabulary.
+const SETUP_CODES = ['auth', 'ingress', 'project-dir', 'start-command'];
+
+// The scaffold default project directory a brand-new (not-yet-created) VM runs
+// under. project-dir-drift AWAY from this is a real problem (two real project
+// names disagree); drift while still ON it is just "the greenfield project
+// hasn't been created yet" — an expected setup step.
+const SCAFFOLD_PROJECT_DIR = 'workspace';
+
+// Parse `project-dir-drift (expected: X, running: Y)` into its two names.
+// Returns { expected, running } with null fields when the shape doesn't match.
+function parseDriftReason(reason) {
+  const m = /expected:\s*([^,]+?)\s*,\s*running:\s*([^)]+?)\s*\)/.exec(reason);
+  return m ? { expected: m[1].trim(), running: m[2].trim() } : { expected: null, running: null };
+}
+
+// The re-wire command the ingress-unwired reason embeds after "Re-wire: " (see
+// fleet-public-url.js::ingressUnwiredReason). Surfaced as the setup step's
+// inline action so the calm checklist row carries the exact command, not just a
+// label. null when the reason carries no command tail.
+function parseIngressAction(reason) {
+  const m = /Re-wire:\s*(.+)$/.exec(reason);
+  return m ? m[1].trim() : null;
+}
+
+// Partition degradedReasons into { setupSteps, attentionReasons }.
+//
+//   setupSteps        ordered [{ code, label, detail, action? }] — expected
+//                     first-run wiring the card renders as a calm checklist.
+//   attentionReasons  the original reason strings that signal a genuine
+//                     problem — rendered amber with the existing ⚠ treatment.
+//
+// Unknown reason codes default to attentionReasons: an unrecognized signal is
+// surfaced loudly, never silently hidden in the calm checklist.
+function classifyReasons(degradedReasons = []) {
+  const setupSteps = [];
+  const attentionReasons = [];
+  const list = Array.isArray(degradedReasons) ? degradedReasons : [];
+  for (const raw of list) {
+    const reason = String(raw);
+    if (reason.startsWith('claude-auth-not-seeded')) {
+      setupSteps.push({ code: 'auth', label: 'Claude login', detail: reason });
+    } else if (reason.startsWith('ingress-unwired')) {
+      setupSteps.push({
+        code: 'ingress',
+        label: 'Public URL wiring',
+        detail: reason,
+        action: parseIngressAction(reason),
+      });
+    } else if (reason.startsWith('project-dir-drift')) {
+      const { expected, running } = parseDriftReason(reason);
+      if (running === SCAFFOLD_PROJECT_DIR) {
+        setupSteps.push({
+          code: 'project-dir',
+          label: expected ? `Create project ${expected}` : 'Create project',
+          detail: reason,
+        });
+      } else {
+        // Drift between two REAL project names is a genuine problem, not setup.
+        attentionReasons.push(reason);
+      }
+    } else if (reason.startsWith('start-command')) {
+      setupSteps.push({ code: 'start-command', label: 'Start command', detail: reason });
+    } else {
+      attentionReasons.push(reason);
+    }
+  }
+  return { setupSteps, attentionReasons };
+}
+
+// True when a VM's reasons are ALL expected setup steps with zero genuine
+// problems — the gate for the calm `finishing-setup` status. Requires at least
+// one setup step (an empty reason list is not "finishing setup", it's just a
+// healthy VM with nothing left to do) and zero attention reasons.
+function hasOnlySetup(degradedReasons = []) {
+  const { setupSteps, attentionReasons } = classifyReasons(degradedReasons);
+  return setupSteps.length > 0 && attentionReasons.length === 0;
+}
+
+module.exports = { classifyReasons, hasOnlySetup, SETUP_CODES, SCAFFOLD_PROJECT_DIR };