@codeyam-editor/codeyam-editor 0.1.5 → 0.1.6

package/npm/fleet-reachability.js

@@ -0,0 +1,80 @@
+'use strict';
+
+// The three-state reachability contract for the Fleet Dashboard.
+//
+// A VM's reachability has THREE states, not two:
+//   true  — a probe reached the VM's editor
+//   false — a probe RAN and FAILED (a confirmed outage)
+//   null  — no verdict at all (never polled, or held inconclusive)
+//
+// `npm/fleet-auth-health.js::classifyReachability` has always modelled this
+// correctly, deliberately returning `{ reachable: null }` for the inconclusive
+// case. Every consumer between it and the browser then coerced that care away
+// with `!!v.reachable` and `{ n, reachable: false }` placeholders, so the null
+// never survived to anyone who could act on it.
+//
+// On 2026-07-30 that collapse served all 13 rostered VMs as `reachable: false`
+// with NO `reachableSource`, while each card's own `backendHealth` read
+// `healthy` and operator auth read clean — a self-contradicting fleet-wide
+// "outage" that had never been probed. It blocked both sanctioned refresh paths
+// (`refresh-client-vm-editor.sh` exits 1, `fleet-advance-to.sh` classifies
+// SKIP-unreachable) and, in a storm, is the signal that has driven reconcile
+// into hard-rebooting healthy VMs.
+//
+// This module is the single home for that vocabulary so the distinction is
+// stated once and grepped, rather than re-derived inline at each consumer. Pure:
+// no I/O, no clock, no state.
+
+// The `reachableSource` value for a record carrying no reachability verdict.
+// `reachableSource` otherwise names the signal that DECIDED a verdict ('lb' |
+// 'backend' | 'local' | 'iap', from classifyReachability), which is what makes a
+// card self-diagnosing — a `reachable: false` with a missing source is exactly
+// the fingerprint that identified the 2026-07-30 incident as manufactured by the
+// serializer rather than reported by a probe. 'unpolled' extends that same
+// self-diagnosis to the no-verdict case instead of leaving a silent gap.
+const REACHABILITY_UNPOLLED = 'unpolled';
+
+// Does this VM have a DEFINITE reachability verdict — did anyone actually ask?
+// Only a real boolean counts; null/undefined (and any malformed value) read as
+// "no verdict". Consumers use this to tell "never asked" from "asked and got an
+// answer", which is the distinction the whole three-state contract exists for.
+function hasReachabilityVerdict(reachable) {
+  return reachable === true || reachable === false;
+}
+
+// Is this VM CONFIRMED unreachable — probed, and the probe failed?
+//
+// Safety-critical. Reboot, reconcile, and destroy paths must gate on THIS, never
+// on a falsy check: `!reachable` is also true for an unknown, so a `!reachable`
+// guard lets a VM nobody has polled walk into a path that ends in a hard reset.
+// An unknown is not evidence, and evidence is the bar for a destructive action.
+function isConfirmedUnreachable(reachable) {
+  return reachable === false;
+}
+
+// Normalize a raw poll record's reachability into the pair the wire envelope
+// carries: `{ reachable, reachableSource }`.
+//
+// This is the seam where the bug lived. `reachable` is preserved as a genuine
+// tri-state — an ABSENT verdict stays absent rather than being coerced to a
+// definite false — and `reachableSource` falls back to 'unpolled' so a card with
+// no verdict says so out loud instead of looking like an unexplained outage.
+//
+// `v` is the merged poll state (`state.vms[n]`), or a placeholder standing in
+// for a VM with no poll state at all.
+function normalizeReachability(v) {
+  const raw = v ? v.reachable : null;
+  const reachable = hasReachabilityVerdict(raw) ? raw : null;
+  return {
+    reachable,
+    reachableSource: (v && v.reachableSource)
+      || (reachable === null ? REACHABILITY_UNPOLLED : null),
+  };
+}
+
+module.exports = {
+  REACHABILITY_UNPOLLED,
+  hasReachabilityVerdict,
+  isConfirmedUnreachable,
+  normalizeReachability,
+};

package/npm/fleet-reset.js

@@ -494,6 +494,36 @@ 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,
@@ -504,4 +534,6 @@ module.exports = {
   resetEditorStateScript,
   endSessionScript,
   verifyIdleOrEndSessionStep,
+  resetJobTimeoutMs,
+  REBUILDS_ON_SELF_HOST,
 };

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

package/npm/fleet-session-token-cache.js

@@ -0,0 +1,65 @@
+'use strict';
+// Per-VM editor session-token cache for the fleet dashboard's gated probes.
+//
+// The post-501766261 editor runs FAIL-CLOSED: every control-API request must
+// carry that VM's own editor session token in `Authorization`, or the editor
+// answers 401. The dashboard reads each token once over the existing SSH/
+// docker-exec path (server.js supplies the impure `fetchToken`) and caches it
+// per VM — the token is stable for the container's lifetime, so re-reading it
+// on every poll would be a wasted gcloud-ssh fork per VM per cycle.
+//
+// Pure logic only — no I/O, no env reads, no clock — so it stays unit-testable
+// in isolation (npm/fleet-session-token-cache.test.js), exactly like the
+// createIapTokenProvider it mirrors. The caller injects `fetchToken(n)`.
+
+/** Build a per-VM session-token cache.
+ *
+ *  `fetchToken(n)` resolves to the VM's session token string (or null/'' when
+ *  it cannot be read). Returns `{ getToken, invalidate }`:
+ *
+ *    getToken(n)   — resolves the cached token, fetching once on a cold entry.
+ *                    Concurrent cold calls for the same VM share ONE in-flight
+ *                    fetch (the poll cycle probes several endpoints per VM at
+ *                    once). A null/empty/failed fetch resolves to null and is
+ *                    NOT cached, so the next poll retries rather than sticking a
+ *                    VM on a missing token.
+ *    invalidate(n) — drop a VM's cached token so the next getToken re-fetches.
+ *                    Called on a fail-closed 401, which is how a container
+ *                    recreate / token rotation self-heals.
+ */
+function createSessionTokenCache({ fetchToken } = {}) {
+  if (typeof fetchToken !== 'function') {
+    throw new Error('createSessionTokenCache requires a fetchToken(n) function');
+  }
+
+  const cache = new Map();     // n -> non-empty token string
+  const inFlight = new Map();  // n -> Promise<string|null>
+
+  async function getToken(n) {
+    if (cache.has(n)) return cache.get(n);
+    if (inFlight.has(n)) return inFlight.get(n);
+
+    const p = Promise.resolve()
+      .then(() => fetchToken(n))
+      .then((tok) => {
+        const value = tok == null ? '' : String(tok).trim();
+        // Only a real token is cached; a null/empty/errored read degrades to
+        // today's behavior (probe with no session token) and retries next poll.
+        if (value !== '') cache.set(n, value);
+        return value === '' ? null : value;
+      })
+      .catch(() => null)
+      .finally(() => { inFlight.delete(n); });
+
+    inFlight.set(n, p);
+    return p;
+  }
+
+  function invalidate(n) {
+    cache.delete(n);
+  }
+
+  return { getToken, invalidate };
+}
+
+module.exports = { createSessionTokenCache };

package/npm/fleet-setup-steps.js

@@ -39,15 +39,6 @@ function parseDriftReason(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
@@ -66,11 +57,14 @@ function classifyReasons(degradedReasons = []) {
     if (reason.startsWith('claude-auth-not-seeded')) {
       setupSteps.push({ code: 'auth', label: 'Claude login', detail: reason });
     } else if (reason.startsWith('ingress-unwired')) {
+      // System-handled: the dashboard reconcile wires the public URL
+      // automatically (incl. down+up self-heal for reused-slug orphans). NO
+      // operator `action`/command — render as in-progress, never a to-do.
       setupSteps.push({
         code: 'ingress',
         label: 'Public URL wiring',
-        detail: reason,
-        action: parseIngressAction(reason),
+        detail: 'Wiring the public URL — this happens automatically.',
+        auto: true,
       });
     } else if (reason.startsWith('project-dir-drift')) {
       const { expected, running } = parseDriftReason(reason);
@@ -102,4 +96,17 @@ function hasOnlySetup(degradedReasons = []) {
   return setupSteps.length > 0 && attentionReasons.length === 0;
 }
 
-module.exports = { classifyReasons, hasOnlySetup, SETUP_CODES, SCAFFOLD_PROJECT_DIR };
+// True when a VM's reasons are ALL expected setup steps AND every one of them is
+// the SAME given code — e.g. `onlySetupCode(reasons, 'auth')` is the gate for the
+// calm, first-class `needs-login` status: the ONLY outstanding item is Claude
+// login, nothing else. A MIXED set (auth + ingress) is not `onlySetupCode('auth')`
+// — it reads the generic `finishing-setup` instead. Builds on the same classifier
+// as hasOnlySetup, so an empty list or any attention reason is false.
+function onlySetupCode(degradedReasons = [], code) {
+  const { setupSteps, attentionReasons } = classifyReasons(degradedReasons);
+  return setupSteps.length > 0
+    && attentionReasons.length === 0
+    && setupSteps.every((s) => s.code === code);
+}
+
+module.exports = { classifyReasons, hasOnlySetup, onlySetupCode, SETUP_CODES, SCAFFOLD_PROJECT_DIR };

package/npm/fleet-status-refs.js

@@ -0,0 +1,96 @@
+'use strict';
+// Push-based fleet-status read for the operator dashboard
+// (scripts/operator/fleet-dashboard/server.js requires this).
+//
+// Each VM's editor publishes its own status to a git ref
+// `refs/codeyam/fleet-status/<machine>` on its plan-claim heartbeat (see the
+// Rust `control-api::fleet_status_refs` writer + the `plan_claims_sync`
+// pusher). This module is the READ half: the dashboard fetches that WHOLE
+// namespace in ONE `git fetch` and reads every VM's status from the local
+// mirror — O(1) in fleet size, and crucially spawning ZERO `gcloud ssh`.
+//
+// That is the entire point of the push model: the old gather fanned out one
+// heavyweight `gcloud compute ssh … docker exec` per VM per poll (Python +
+// IAP tunnel, ~100 MB apiece), so monitoring cost O(N) SSH round-trips and
+// the operator host had to be over-provisioned just to stay responsive. One
+// fetch replaces all of it.
+//
+// Pure orchestration with injected I/O (`spawn` for the fetch, `readRefs` for
+// the mirror read) so it stays unit-testable with no network and no git —
+// exactly like the other fleet-* modules. Any real gcloud/SSH I/O is
+// DELIBERATELY absent here; a test asserts no spawn command matches /gcloud/.
+
+// Force refspec mirroring the whole fleet-status namespace into the local
+// mirror. The leading `+` prunes a machine that stopped publishing (its ref
+// deleted upstream), so a decommissioned VM's status can't linger. Kept
+// byte-identical to the Rust `FLEET_STATUS_FETCH_REFSPEC` constant.
+const FLEET_STATUS_FETCH_REFSPEC =
+  '+refs/codeyam/fleet-status/*:refs/codeyam/fleet-status/*';
+
+// Parse `git for-each-ref --format='%(refname)%00%(contents)'` output over the
+// fleet-status namespace into an array of payload objects. A ref whose body is
+// not valid JSON is skipped (never throws) so one corrupt ref can't blind the
+// dashboard to the rest of the fleet. NUL separates the ref name from its
+// single-line JSON body; records are newline-separated.
+function parseForEachRef(stdout) {
+  const out = [];
+  for (const line of String(stdout || '').split('\n')) {
+    if (!line.trim()) continue;
+    const sep = line.indexOf('\u0000');
+    const json = sep >= 0 ? line.slice(sep + 1) : line;
+    try {
+      const payload = JSON.parse(json);
+      if (payload && typeof payload === 'object') out.push(payload);
+    } catch (e) {
+      // Skip an unparseable ref body; the rest of the fleet still reads.
+    }
+  }
+  return out;
+}
+
+// Index an array of status payloads by their `machine`, keeping the LAST
+// occurrence for a machine (there should only be one ref per machine, but be
+// deterministic if a duplicate slips in). Payloads with no `machine` are
+// dropped — they can't be attributed to a VM.
+function indexByMachine(payloads) {
+  const vms = {};
+  for (const p of payloads || []) {
+    if (p && p.machine) vms[p.machine] = p;
+  }
+  return vms;
+}
+
+// Read the whole fleet's pushed status in ONE fetch, then index it by machine.
+//
+//   spawn(command, args)  — run a process (the single git fetch). May return a
+//                           promise; awaited. NEVER used for gcloud/SSH.
+//   readRefs()            — return (or resolve to) the parsed status payloads
+//                           from the local mirror. Injected so tests need no
+//                           git; production passes a reader that runs
+//                           `git for-each-ref` + parseForEachRef.
+//   remote                — remote to fetch from (default 'origin').
+//   projectDir            — cwd for the fetch, threaded to spawn's options.
+//
+// Returns `{ vms: { <machine>: payload }, count }`. A fetch failure is
+// swallowed (best-effort, same posture as the Rust sync): the read falls back
+// to whatever is already in the local mirror, so a transient network blip
+// degrades to slightly-stale status rather than a blank dashboard.
+async function gatherFleetStatus({ spawn, readRefs, remote = 'origin', projectDir } = {}) {
+  if (typeof spawn !== 'function') throw new Error('gatherFleetStatus requires a spawn function');
+  if (typeof readRefs !== 'function') throw new Error('gatherFleetStatus requires a readRefs function');
+  try {
+    await spawn('git', ['fetch', '--no-write-fetch-head', remote, FLEET_STATUS_FETCH_REFSPEC], { cwd: projectDir });
+  } catch (e) {
+    // Fall through to reading the (possibly stale) local mirror.
+  }
+  const payloads = await readRefs();
+  const vms = indexByMachine(payloads);
+  return { vms, count: Object.keys(vms).length };
+}
+
+module.exports = {
+  FLEET_STATUS_FETCH_REFSPEC,
+  parseForEachRef,
+  indexByMachine,
+  gatherFleetStatus,
+};

package/npm/fleet-strand.js

@@ -24,10 +24,25 @@
 // Stack note: this is fleet-operator infrastructure (the GCE fleet that runs
 // codeyam-editor itself). A project that never joins the fleet never reaches it.
 
-// The boot guard whose presence makes a binary safe from the launcher-mode
-// strand. Single source so the classifier, the capability field the editor
-// advertises, and any log line agree on the string.
+// The boot guards whose presence makes a binary safe. Single source so the
+// classifier, the capability field the editor advertises, and any log line
+// agree on the strings.
+//   SERVE_CWD_GUARD    — safe from the launcher-mode strand (serves its cwd
+//                        project on the contract port instead of re-execing
+//                        into the Project Launcher on an ephemeral port).
+//   CAPTURE_AUTH_GUARD — enforces the capture-session auth guard, so component
+//                        captures don't 401 when the editor binds a
+//                        non-loopback address.
 const SERVE_CWD_GUARD = 'serve_cwd_directly';
+const CAPTURE_AUTH_GUARD = 'capture_session_auth';
+
+// Per-guard impact clause folded into the stale reason, so a flagged VM's badge
+// names WHY the missing guard matters (not a generic "stale") and the operator
+// knows the concrete failure to expect.
+const GUARD_IMPACT = {
+  [SERVE_CWD_GUARD]: 'will strand in Project Launcher mode on its next re-exec',
+  [CAPTURE_AUTH_GUARD]: 'component captures will 401 on a non-loopback bind',
+};
 
 /** Classify a VM's in-container probe into the launcher-strand vocabulary. The
  *  DECISIVE, trigger-independent signal is observable in-VM regardless of what
@@ -116,19 +131,34 @@ function strandRecoveryAction({ binaryCurrent } = {}) {
  *  the editor advertising the capability (the `bootGuards` array on the
  *  health/session-info payload it already serves) rather than the dashboard
  *  guessing from commit ancestry:
- *    - `bootGuards` IS an array → authoritative: stale iff it lacks the guard.
+ *    - `bootGuards` IS an array → authoritative: stale iff it is missing ANY
+ *      required guard. A binary that has `serve_cwd_directly` yet predates
+ *      `capture_session_auth` (VM-13) must still be flagged, so a single
+ *      required guard is not enough — the check is over the whole required set,
+ *      naming the FIRST missing guard (with its impact clause) in the reason.
  *    - `bootGuards` ABSENT (an older binary that predates the field — which are
  *      exactly the at-risk ones) → fall back to the build-commit comparison the
  *      dashboard already computes: flag stale only when the editor source is
  *      `editorBehind > 0` commits behind origin, so a current binary that merely
  *      predates the FIELD isn't falsely flagged while a genuinely-behind one is.
- *  Returns `{ stale, reason }`; `reason` is null when not stale. */
-function classifyBinaryGuard({ bootGuards, editorBehind, requiredGuard = SERVE_CWD_GUARD } = {}) {
+ *  `requiredGuard` accepts an array (the new multi-guard shape, default
+ *  `[SERVE_CWD_GUARD, CAPTURE_AUTH_GUARD]`) or a single string (legacy /
+ *  future-guard reuse). Returns `{ stale, reason }`; `reason` is null when not
+ *  stale. */
+function classifyBinaryGuard({
+  bootGuards,
+  editorBehind,
+  requiredGuard = [SERVE_CWD_GUARD, CAPTURE_AUTH_GUARD],
+} = {}) {
+  const required = Array.isArray(requiredGuard) ? requiredGuard : [requiredGuard];
   if (Array.isArray(bootGuards)) {
-    if (bootGuards.includes(requiredGuard)) return { stale: false, reason: null };
+    const missing = required.find((guard) => !bootGuards.includes(guard));
+    if (!missing) return { stale: false, reason: null };
+    const impact = GUARD_IMPACT[missing];
+    const because = impact ? ` — ${impact}` : '';
     return {
       stale: true,
-      reason: `running binary advertises bootGuards [${bootGuards.join(', ')}] without '${requiredGuard}'; rebuild to converge`,
+      reason: `running binary advertises bootGuards [${bootGuards.join(', ')}] without '${missing}'${because}; rebuild to converge`,
     };
   }
   const behind = Number(editorBehind);
@@ -143,6 +173,7 @@ function classifyBinaryGuard({ bootGuards, editorBehind, requiredGuard = SERVE_C
 
 module.exports = {
   SERVE_CWD_GUARD,
+  CAPTURE_AUTH_GUARD,
   classifyLauncherStrand,
   shouldAutoRecoverStrand,
   strandRecoveryAction,

package/npm/fleet-stuck-status.js

@@ -62,16 +62,22 @@ function elapsedMs(iso, nowMs) {
 
 // Derive the attention verdict for one VM.
 //
-//   deriveAttention({ status, stepStartedAt, awaitingInput, nowMs, thresholds })
+//   deriveAttention({ status, stepStartedAt, nowMs, thresholds })
 //     -> { stepElapsedMs, level, needsYou, needsYouElapsedMs }
 //
 // Rules:
 //   - `level` ('ok' | 'slow' | 'stuck') is computed ONLY for an actively-
 //     building VM (status === 'building'). Thresholds are inclusive:
 //     >= stuckMs -> 'stuck', else >= slowMs -> 'slow', else 'ok'.
-//   - A VM awaiting input (status === 'waiting' or awaitingInput true) never
-//     reads 'slow'/'stuck' — it is legitimately blocked on a human. Instead
-//     `needsYou` flips true once its elapsed >= needsYouMs.
+//   - "Needs you" flips true ONLY for the genuinely-blocked `waiting` state (a
+//     running task awaiting a human), once its elapsed >= needsYouMs. An 'idle'
+//     VM (parked at its prompt, no task running) is deliberately NOT flagged no
+//     matter how long it sits — idle means "ready for you to start something",
+//     not "a task is blocked on you" (observed live 2026-06-30, VM-1, which
+//     false-flagged "Needs You" while merely idle). `awaitingInput` alone no
+//     longer drives this: liveSessionStatus already collapses an idle awaiting
+//     agent to 'idle' and a blocked one to 'waiting', so the status IS the
+//     discriminator.
 //   - Missing/unparseable stepStartedAt degrades to stepElapsedMs:null,
 //     level:'ok', needsYou:false (older editor, no crash).
 function deriveAttention(opts) {
@@ -79,14 +85,14 @@ function deriveAttention(opts) {
   const thresholds = o.thresholds || resolveThresholds({});
   const nowMs = o.nowMs;
   const stepElapsed = elapsedMs(o.stepStartedAt, nowMs);
-  const awaiting = o.status === 'waiting' || !!o.awaitingInput;
 
   let level = 'ok';
   let needsYou = false;
   let needsYouElapsedMs = null;
 
-  if (awaiting) {
-    // Waiting on a human — never "stuck"; flag "needs you" past its threshold.
+  if (o.status === 'waiting') {
+    // A task genuinely blocked on a human — never "stuck"; flag "needs you" past
+    // its threshold. An 'idle' VM never reaches this branch.
     needsYouElapsedMs = stepElapsed;
     needsYou = stepElapsed != null && stepElapsed >= thresholds.needsYouMs;
   } else if (o.status === 'building' && stepElapsed != null) {