@codeyam-editor/codeyam-editor 0.1.2 → 0.1.4

package/npm/fleet-grouping.js

@@ -0,0 +1,56 @@
+// Group an already-sorted/filtered VM list by client project for the Fleet
+// Dashboard's grouped layout.
+//
+// Returns an ORDERED array of { project, vms } groups: real project groups
+// first, sorted case-insensitively by name (locale compare); the
+// unknown/starting-up bucket (project === null) pinned LAST. Within each group
+// the incoming order of `vms` is preserved untouched, so the caller's active
+// Sort mode continues to drive within-group order — grouping never re-sorts the
+// cards, it only partitions them.
+//
+// `projectKey(v)` resolves the group key for a VM and defaults to the same
+// identity `card()` renders in the dashboard:
+//   (v.cardIdentity && v.cardIdentity.project) || v.project || null
+// It is injectable so unit tests can drive grouping without constructing full
+// card payloads. A null/empty key routes the VM into the trailing unknown
+// bucket so VMs mid-provision (blank identity) never silently disappear.
+//
+// Pure; no I/O.
+
+function defaultProjectKey(v) {
+  return (v && v.cardIdentity && v.cardIdentity.project) || (v && v.project) || null;
+}
+
+function groupVmsByProject(vms, projectKey = defaultProjectKey) {
+  // First pass: stable bucketing. `Map` preserves insertion order, so the
+  // first VM of each project fixes that group's relative position before we
+  // re-order — but we re-sort named groups below regardless, so insertion
+  // order only matters for tie-stability within equal-name groups (none here).
+  const named = new Map();
+  let unknown = null;
+
+  for (const v of vms) {
+    const raw = projectKey(v);
+    const key = raw == null || raw === "" ? null : raw;
+    if (key === null) {
+      if (!unknown) unknown = { project: null, vms: [] };
+      unknown.vms.push(v);
+      continue;
+    }
+    let group = named.get(key);
+    if (!group) {
+      group = { project: key, vms: [] };
+      named.set(key, group);
+    }
+    group.vms.push(v);
+  }
+
+  const groups = Array.from(named.values());
+  groups.sort((a, b) =>
+    a.project.localeCompare(b.project, undefined, { sensitivity: "base" })
+  );
+  if (unknown) groups.push(unknown);
+  return groups;
+}
+
+module.exports = { groupVmsByProject, defaultProjectKey };

package/npm/fleet-job-badge.js

@@ -0,0 +1,83 @@
+'use strict';
+
+// npm/fleet-job-badge.js — pure verdict for the fleet dashboard's failed-job
+// badge reconciliation (improve39). A VM's last terminal-error heavy job
+// (add/error, reset-all error, reset-editor error, …) used to stick on the
+// dashboard card indefinitely — even after the VM was recovered and is healthy
+// again — because the card renders the last job's error with no check against
+// the VM's live state, so a recovered VM keeps screaming a red error and
+// misleads the operator. This decides whether such a badge should be RECONCILED
+// (presented as "recovered" rather than a live error) because the VM is
+// demonstrably fine now. The live signals are gathered in server.js (the
+// untestable server shell); the verdict lives here so the cases are unit-tested
+// without a live VM.
+
+// Should the VM's last terminal-error job badge be reconciled against live
+// health — i.e. presented as "recovered" rather than a live red error?
+//
+//   job        the carried job record ({ state, action, ... }) or null
+//   reachable  the VM's editor answered this poll (true = healthy / responding)
+//   drifted    a project-dir-drift signal is present (reachable-but-unwired /
+//              half-provisioned add — genuinely needs-recovery, owned by the
+//              companion reconcile-inflight-jobs plan; never falsely cleared here)
+//   offBranch  the VM's live client branch differs from its target branch
+//   degraded   the job completed but a wiring sub-step is flagged degraded
+//
+// Returns true only when the job is a terminal error AND the VM is demonstrably
+// fine (reachable, not drifted, on-branch, not degraded). An unreachable /
+// drifted / off-branch VM keeps its error surfaced — a real problem must stay
+// visible.
+function shouldReconcileFailedBadge({ job, reachable, drifted, offBranch, degraded } = {}) {
+  if (!job || job.state !== 'error') return false;
+  if (!reachable) return false;
+  if (drifted) return false;
+  if (offBranch) return false;
+  if (degraded) return false;
+  return true;
+}
+
+// Given a reconcile verdict (from shouldReconcileFailedBadge) and whether the VM
+// is now idle, decide whether the recovered badge should be FULLY CLEARED — the
+// job entry dropped from state.jobs so the card goes clean — rather than merely
+// muted as a "recovered (was: …)" note (improve41).
+//
+//   badgeReconciled  the shouldReconcileFailedBadge verdict for this VM
+//   idle             the VM answered this poll, is not running a build session,
+//                    and its broker is not actively serving an agent
+//
+// A recovered VM that is also idle has demonstrably finished recovering, so the
+// stale error is dropped entirely. A recovered-but-not-yet-idle VM (mid-build,
+// or a poll hasn't confirmed idle) keeps the muted note so the prior log stays
+// visible during that transient window. Never clears a badge that wasn't first
+// judged recovered — an unreachable / drifted / off-branch error stays surfaced.
+function shouldClearReconciledBadge({ badgeReconciled, idle } = {}) {
+  return !!badgeReconciled && !!idle;
+}
+
+// Pure guard for the operator "Clear badge" action (improve41). Decides whether
+// VM-n's persisted job entry may be dropped after an out-of-band recovery,
+// independent of the server's state / fs I/O so the cases are unit-tested
+// without a live dashboard. The shell (server.js) supplies the live signals and
+// turns the verdict into the {ok,msg} response + the actual delete + snapshot.
+//
+//   rostered  the VM number is in the live roster
+//   job       the carried job record ({ state, ... }) or null/undefined
+//
+// Only a TERMINAL job (error/done) on a rostered VM may be cleared, OR a terminal
+// failed add (add/error) on a non-rostered VM (which deletes the card + add-N sidecar):
+// any other job state / non-rostered combination is not clearable.
+// Returns { ok, reason, cleanup } — reason is a stable code the shell maps to an
+// operator message, and cleanup is the cleanup action to perform ('add-failed' vs 'badge-only').
+function canClearBadge({ rostered, job } = {}) {
+  if (!rostered) {
+    if (job && job.action === 'add' && job.state === 'error') {
+      return { ok: true, reason: null, cleanup: 'add-failed' };
+    }
+    return { ok: false, reason: 'not-rostered' };
+  }
+  if (!job) return { ok: false, reason: 'no-badge' };
+  if (job.state !== 'error' && job.state !== 'done') return { ok: false, reason: 'job-active' };
+  return { ok: true, reason: null, cleanup: 'badge-only' };
+}
+
+module.exports = { shouldReconcileFailedBadge, shouldClearReconciledBadge, canClearBadge };

package/npm/fleet-memory.js

@@ -74,17 +74,30 @@ function decodeStateSnapshot(buf) {
  *  Returns null when the snapshot is missing, malformed, or older than
  *  maxAgeMs (stale snapshots are worse than no snapshot — pollVMs will
  *  repopulate from real data). Otherwise returns { jobs, vms, orphans }
- *  with two safety transforms applied to jobs:
+ *  with these safety transforms applied to jobs:
  *
- *    • `running` → `error` with a log marker, because the child process
- *      died with the dashboard; we can't possibly have a live job tracker
- *      after a process restart.
+ *    • `running` WITH a pending-job sidecar → `recovering` with a deferral
+ *      marker, NOT `error`. A heavy job that stashed a recoverable sidecar
+ *      (its cfg) must defer its final state to the startup reap, which
+ *      actually checks gcloud — the blanket `error` was the improve39 VM-7
+ *      bug: a mid-add restart stranded an instance that was really up as a
+ *      dead `add-failed`. `recovering` is an honest "the reap will resolve
+ *      this" surface; the reap then supersedes it (reconcile/half-provisioned
+ *      /cleanup) once it has the gcloud verdict.
+ *    • `running` WITHOUT a sidecar → `error` with a log marker, because the
+ *      child process died with the dashboard and there's nothing to recover
+ *      from — un-recoverable history, the old behavior.
  *    • `queued`  → dropped, because the in-memory pendingJobQueue array
  *      is gone, so promoteFromJobQueue can never start them. The operator
  *      will re-click (the queued click had done no work yet).
  *
+ *  `sidecarKeys` is the set of `${action}-${n}` strings the caller read from
+ *  the pending-jobs dir (server.js passes it; tests pass a plain array/Set).
+ *  Omitted → no job has a sidecar → every running job downgrades to `error`
+ *  exactly as before, so existing callers/tests are unaffected.
+ *
  *  Pure; no I/O. */
-function restoreFromSnapshot({ snapshot, maxAgeMs, nowIso } = {}) {
+function restoreFromSnapshot({ snapshot, maxAgeMs, nowIso, sidecarKeys } = {}) {
   if (!snapshot || typeof snapshot !== 'object') return null;
   if (typeof snapshot.timestamp !== 'string') return null;
   const ts = Date.parse(snapshot.timestamp);
@@ -95,16 +108,33 @@ function restoreFromSnapshot({ snapshot, maxAgeMs, nowIso } = {}) {
   if (!Number.isFinite(cap) || cap <= 0) return null;
   if (ageMs > cap) return null;
 
+  const sidecars = sidecarKeys instanceof Set ? sidecarKeys : new Set(sidecarKeys || []);
   const srcJobs = (snapshot.jobs && typeof snapshot.jobs === 'object') ? snapshot.jobs : {};
   const jobs = {};
   for (const [k, j] of Object.entries(srcJobs)) {
     if (!j || typeof j !== 'object') continue;
     if (j.state === 'queued') continue;
     if (j.state === 'running') {
+      if (sidecars.has(`${j.action}-${k}`)) {
+        jobs[k] = {
+          ...j,
+          state: 'recovering',
+          log: `${j.log ? j.log + '\n' : ''}(snapshot-restored — deferring to startup reap)`,
+        };
+        continue;
+      }
       jobs[k] = {
         ...j,
         state: 'error',
         finishedAt: nowIso,
+        // improve40: mark this as a restart-orphan, NOT a genuine in-process
+        // failure. The job was `running` when the restart downgraded it and has
+        // NO sidecar to reconcile from — so the boot path must probe the VM's
+        // REAL provision state (orphanedAddsToReconcile → gcloud reap) rather
+        // than leave a dead `add-failed` badge on a VM that may have actually
+        // provisioned (the VM-7 hole). An add that failed IN-PROCESS keeps its
+        // own terminal `error` with no flag, so it is never re-probed/cleared.
+        restartOrphaned: true,
         log: `${j.log ? j.log + '\n' : ''}(snapshot-restored — dashboard restarted before this finished)`,
       };
       continue;

package/npm/fleet-plans.js

@@ -0,0 +1,96 @@
+'use strict';
+
+/**
+ * Indexes the currently-reachable VMs by their live sessionId.
+ * @param {Array|Object} vms The merged VM states on the dashboard.
+ * @returns {Object} A map of sessionId -> VM number (n).
+ */
+function indexVmsBySessionId(vms) {
+  const map = {};
+  if (!vms) return map;
+  const list = Array.isArray(vms) ? vms : Object.values(vms);
+  for (const vm of list) {
+    if (vm && vm.sessionId && vm.n !== undefined) {
+      map[vm.sessionId] = vm.n;
+    }
+  }
+  return map;
+}
+
+/**
+ * Computes which dependencies are unsatisfied (i.e. not in the completedSlugs set).
+ * @param {string[]} dependsOn Prerequisite slugs.
+ * @param {Set|string[]} completedSlugs Set or array of completed plan slugs.
+ * @returns {string[]} The unsatisfied dependency slugs.
+ */
+function unsatisfiedDeps(dependsOn, completedSlugs) {
+  const deps = Array.isArray(dependsOn) ? dependsOn : [];
+  const completedSet = completedSlugs instanceof Set ? completedSlugs : new Set(completedSlugs || []);
+  return deps.filter(dep => !completedSet.has(dep));
+}
+
+/**
+ * Resolves claims and dependency states for each queued plan.
+ * @param {Object} params
+ * @param {Object[]} params.plans Array of PlanSummary objects from /api/plans.
+ * @param {Object[]} params.claims Array of PlanClaim objects from /api/plan-claims.
+ * @param {Set|string[]} params.completedSlugs Completed plan slugs.
+ * @param {Object} params.vmsBySessionId Map of sessionId -> VM number.
+ * @returns {Object[]} Annotated plan rows.
+ */
+function resolvePlanRows({ plans, claims, completedSlugs, vmsBySessionId }) {
+  const list = Array.isArray(plans) ? plans : [];
+  const claimsList = Array.isArray(claims) ? claims : [];
+
+  return list.map(plan => {
+    // 1. Extract plan fields
+    const slug = plan.slug;
+    const title = plan.title;
+    const mode = plan.mode || null;
+    const order = plan.order != null ? plan.order : null;
+    const prefix = plan.prefix || null;
+
+    // 2. Resolve dependency-blocked state
+    const dependsOn = Array.isArray(plan.depends_on) ? plan.depends_on : (plan.dependsOn ? plan.dependsOn : []);
+    const blockedBy = unsatisfiedDeps(dependsOn, completedSlugs);
+
+    // 3. Resolve claim state
+    const claim = claimsList.find(c => c.slug === slug);
+    let claimInfo = null;
+    if (claim) {
+      const claimedBy = claim.claimedBy || claim.claimed_by || {};
+      const sessionId = claimedBy.sessionId || claimedBy.session_id || null;
+      const vm = (sessionId && vmsBySessionId && vmsBySessionId[sessionId] !== undefined) ? vmsBySessionId[sessionId] : null;
+      
+      claimInfo = {
+        vm,
+        machine: claimedBy.machine || null,
+        agent: claimedBy.agentProvider || claimedBy.agent_provider || null,
+        sessionAlive: claim.sessionAlive !== undefined ? claim.sessionAlive : (claim.session_alive !== undefined ? claim.session_alive : null),
+        source: claim.source || null,
+        currentStep: claimedBy.currentStep || claimedBy.current_step || null,
+      };
+    }
+
+    return {
+      slug,
+      title,
+      mode,
+      order,
+      prefix,
+      blockedBy,
+      claim: claimInfo
+    };
+  });
+}
+
+const REQUIRED_PLAN_ROW_FIELDS = [
+  'slug', 'title', 'mode', 'order', 'prefix', 'blockedBy', 'claim'
+];
+
+module.exports = {
+  indexVmsBySessionId,
+  unsatisfiedDeps,
+  resolvePlanRows,
+  REQUIRED_PLAN_ROW_FIELDS
+};

package/npm/fleet-reconcile.js

@@ -33,4 +33,61 @@ function computeUnrostered(running, shown) {
     .sort((a, b) => a - b);
 }
 
-module.exports = { parseRunningFleetVms, computeUnrostered };
+// 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).
+// Start with the two observed classes (improve41); extend the table as new
+// degraded reasons gain a corresponding live signal.
+function reasonClearedByHealth(reason, { reachableServing, authed }) {
+  const r = String(reason || '');
+  if (/claude auth|claude\.json|login/i.test(r)) return authed;
+  if (/container|never came up|provisioning failed/i.test(r)) return reachableServing;
+  return false;
+}
+
+// Given a terminal add-job badge and the VM's live health, return the corrected
+// badge — or null when nothing changes. Conservative by construction: clears a
+// degraded reason only when its live health signal now passes; flips a bare
+// `error` add to `done` when the VM is reachable + serving; leaves any reason
+// with no health signal intact (no false-green). The poll loop supplies the live
+// facts (I/O at the edge) and applies the result; the verdict itself is pure.
+//   job:    { state: 'done'|'error', degraded, degradedReasons }
+//   health: { reachable, editorHttpOk, providerAuthState }
+//   → null | { state, degraded, degradedReasons, transition }
+function reconcileTerminalAddBadge({ job, health } = {}) {
+  if (!job || !health) return null;
+  const reachableServing = !!(health.reachable && health.editorHttpOk);
+  const authed = health.providerAuthState === 'authenticated';
+
+  // Bare `error` add (no degraded reasons): flip to `done` once the VM is
+  // reachable + serving — the VM3 case (a manual `cloud:up` recovered the editor
+  // outside the dashboard's view).
+  if (job.state === 'error') {
+    const reasons = job.degradedReasons || [];
+    if (reasons.length === 0 && reachableServing) {
+      return { state: 'done', degraded: false, degradedReasons: [], transition: 'error→done (editor 200)' };
+    }
+    return null;
+  }
+
+  // Terminal `done` that is degraded: clear each reason whose live signal now
+  // passes; retain the rest. Drop `degraded` only when no reasons remain.
+  if (job.state === 'done' && job.degraded) {
+    const reasons = job.degradedReasons || [];
+    const remaining = reasons.filter((reason) => !reasonClearedByHealth(reason, { reachableServing, authed }));
+    if (remaining.length === reasons.length) return null; // nothing cleared → no-op
+    const cleared = reasons.length - remaining.length;
+    return {
+      state: 'done',
+      degraded: remaining.length > 0,
+      degradedReasons: remaining,
+      transition: remaining.length > 0
+        ? `degraded: cleared ${cleared} reason(s), ${remaining.length} remain`
+        : 'degraded→clear (health restored)',
+    };
+  }
+
+  return null;
+}
+
+module.exports = { parseRunningFleetVms, computeUnrostered, reconcileTerminalAddBadge };

package/npm/fleet-reset.js

@@ -31,30 +31,97 @@
 // Best-effort: a no-remote / queue-disabled project legitimately exits
 // non-zero, and we should not block the reset.
 //
-// Between the cp-asides and the `rm -rf` we cooperatively pause the editor
-// server (`stop-server --hold-for-restart`). Without that, the server keeps
-// writing to `.codeyam/logs/editor-server.log` and `.codeyam/run/` between
-// when `rm -rf` enumerates the dir and when it tries to `rmdir` the empty
-// directory — it surfaces as `rm: cannot remove '.codeyam': Directory not
-// empty`, which the dashboard reports as `error`. SIGUSR2 closes listeners +
-// stops the dev-server and parks the PID; the parent script's trailing
-// `restart-server --force-in-container` then resurrects via the existing
-// SIGUSR1 in-place reexec. Fail-soft `|| true` so a server that's already
-// dead (e.g. the reset is rerun after a partial failure) doesn't block the
-// chain.
+// Before the wipe we QUIESCE ALL WRITERS: park the editor server
+// (`stop-server --hold-for-restart`) AND stop the PTY broker
+// (`pty-broker stop`). Parking only the editor server is insufficient — the
+// broker is a SEPARATE process (and hooks / agent subprocesses can fire), so
+// it keeps re-creating `.codeyam/logs/` and `.codeyam/run/` between when the
+// wipe enumerates the dir and when it removes it. That race surfaced live
+// (VM-1, 2026-06-01) as `rm: cannot remove '.codeyam': Directory not empty`,
+// aborting the whole reset. Both quiesce calls are fail-soft `|| true` so a
+// server/broker that's already dead (e.g. the reset is rerun after a partial
+// failure) doesn't block the chain.
+//
+// The wipe itself is RETRY-RESILIENT instead of a single `rm -rf .codeyam`
+// that aborts the &&-chain on one transient re-creation: a bounded loop of
+// `find .codeyam -mindepth 1 -delete` empties the contents and tolerates a
+// brief re-create, then proceeds even if `.codeyam` is still non-empty after
+// best-effort (a soft retry, never a hard failure — `git checkout`/`init`
+// repopulates over whatever remains). Emptying contents (not removing the dir)
+// also sidesteps the `rmdir` race entirely.
+//
+// The destructive region (park → broker-stop → wipe → restore) is made
+// FAILURE-SAFE with an EXIT trap installed before the park and disarmed after
+// a successful restore. If ANY step in that region aborts the chain, the trap
+// still restores tracked `.codeyam` (or re-inits), copies the two preserved
+// infra files back, and runs `restart-server --force-in-container` before
+// exiting non-zero — so a failed deep-clean self-recovers to a working
+// (un-reset, but UP) VM instead of leaving it parked-and-down with a
+// half-wiped `.codeyam`, and still reports the failure. The happy path is
+// unchanged: the restore steps run, the trap is disarmed, and the caller's
+// own trailing `restart-server` resurrects the parked server.
 function codeyamDeepCleanSteps(E) {
+  // Restore primitives shared by the happy path and the trap recovery body.
+  const restoreCodeyam = `git checkout HEAD -- .codeyam 2>/dev/null || ${E} init`;
+  const restoreElj =
+    'test -f /tmp/cy-elj.bak && mkdir -p .codeyam && cp /tmp/cy-elj.bak .codeyam/editor.local.json';
+  const restoreSs =
+    'test -f /tmp/cy-ss.bak && mkdir -p .codeyam && cp /tmp/cy-ss.bak .codeyam/server-state.json';
+  // Recovery body: restore .codeyam + the two infra backups, then resurrect the
+  // parked server. Runs ONLY on the failure path (the happy path's own restore
+  // steps remove the backups; recovery here intentionally leaves them in place
+  // because on a mid-region abort those steps never ran).
+  const recover =
+    `${restoreCodeyam}; ( ${restoreElj}; true ); ( ${restoreSs}; true ); ` +
+    `${E} editor restart-server --force-in-container || true`;
   return [
     `( ${E} editor branch-queue release-mine --yes 2>/dev/null; true )`,
     '( cp .codeyam/editor.local.json /tmp/cy-elj.bak 2>/dev/null; true )',
     '( cp .codeyam/server-state.json /tmp/cy-ss.bak 2>/dev/null; true )',
+    // A brace group (NOT a subshell) so the function + trap persist into the
+    // current shell where the rest of the &&-chain runs.
+    `{ __cy_recover() { ${recover}; }; trap '__cy_recover; exit 1' EXIT; }`,
     `(${E} editor stop-server --hold-for-restart --force-in-container || true)`,
-    'rm -rf .codeyam',
-    `( git checkout HEAD -- .codeyam 2>/dev/null || ${E} init )`,
-    '( test -f /tmp/cy-elj.bak && mkdir -p .codeyam && cp /tmp/cy-elj.bak .codeyam/editor.local.json && rm -f /tmp/cy-elj.bak; true )',
-    '( test -f /tmp/cy-ss.bak && mkdir -p .codeyam && cp /tmp/cy-ss.bak .codeyam/server-state.json && rm -f /tmp/cy-ss.bak; true )',
+    `(${E} editor pty-broker stop || true)`,
+    '( for i in 1 2 3 4 5; do find .codeyam -mindepth 1 -delete 2>/dev/null; [ -z "$(ls -A .codeyam 2>/dev/null)" ] && break; sleep 0.2; done; true )',
+    `( ${restoreCodeyam} )`,
+    `( ${restoreElj} && rm -f /tmp/cy-elj.bak; true )`,
+    `( ${restoreSs} && rm -f /tmp/cy-ss.bak; true )`,
+    // Restore succeeded — disarm the failure-safe trap so normal completion
+    // (and the caller's trailing session-reset + restart) doesn't re-trigger it.
+    'trap - EXIT',
   ];
 }
 
+// Belt-and-suspenders broker-ensure, appended after the trailing
+// `restart-server` in every reset recipe. The PRIMARY fix lives in the
+// editor server's `ensure_broker_running`: it now `rm -f`s the stale
+// socket and retries the spawn, so the reexec'd `start` (which
+// restart-server triggers) reliably respawns the broker with no
+// down-window. This step is the safety net for an OLDER in-container
+// binary whose `restart-server` predates that fix — it mirrors the
+// vm-watchdog's recovery so a reset still ends broker-up regardless of
+// which binary is installed.
+//
+// Shape: status-gated and idempotent. `pty-broker status` exits non-zero
+// only when no broker is reachable; ONLY then does the `||` branch fire
+// (`rm -f` the stale socket — mirroring the watchdog — then `nohup` a
+// detached daemon). When a broker is already alive the status succeeds
+// and the respawn branch never runs, so a healthy broker is NEVER killed.
+// Wrapped in `( …; true )` so it can never break the reset's &&-chain
+// (a down broker that fails to respawn must not abort the rest of the
+// reset). The socket glob + `pty-broker daemon` invocation match the
+// watchdog (`scripts/operator/vm-watchdog.sh`) and the per-project
+// `$TMPDIR`/`/tmp` socket layout (`socket_path_for`).
+function codeyamBrokerEnsureStep(E) {
+  return (
+    `( ${E} editor pty-broker status >/dev/null 2>&1 || ` +
+    `( rm -f /tmp/codeyam-pty-broker-*.sock; ` +
+    `nohup ${E} editor pty-broker daemon </dev/null >/tmp/broker-spawn.log 2>&1 & disown ); ` +
+    'true )'
+  );
+}
+
 // 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
@@ -85,6 +152,9 @@ function resetClientScript({ E, gitReseedBody }) {
     `${E} editor session-reset`,
     'echo ">> [4/5] restarting server to respawn the broker (no rebuild)"',
     `(${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" )`,
   ].join(' && ');
@@ -138,7 +208,15 @@ function resetEditorStateScript({ E }) {
     // docker-exec returns cleanly, so `|| true` keeps a broker-down VM green.
     'echo ">> [4/4] restarting server to respawn the broker (no rebuild)"',
     `(${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),
   ].join(' && ');
 }
 
-module.exports = { codeyamDeepCleanSteps, resetClientScript, resetEditorStateScript };
+module.exports = {
+  codeyamDeepCleanSteps,
+  codeyamBrokerEnsureStep,
+  resetClientScript,
+  resetEditorStateScript,
+};