@codeyam-editor/codeyam-editor 0.1.4 → 0.1.6

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

@@ -0,0 +1,112 @@
+'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 };
+}
+
+// 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')) {
+      // 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: 'Wiring the public URL — this happens automatically.',
+        auto: true,
+      });
+    } 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;
+}
+
+// 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-sleep-status.js

@@ -0,0 +1,33 @@
+'use strict';
+// Pure status helpers for the Sleep / Wake feature on the Fleet Dashboard
+// (scripts/operator/fleet-dashboard/server.js requires this). Mirrors the
+// pure-module-plus-colocated-vitest-test shape of npm/fleet-effect-status.js:
+// server.js does the impure fact-gathering (the gcloud running-VM list, the
+// per-VM reachability probe); these predicates turn those facts into the two
+// new card statuses without any I/O, so the whole decision is unit-testable.
+
+// Map a RUNNING stop/start job to its in-flight status badge. A Sleep click
+// runs `gcloud compute instances stop` as a 'stop' job → 'stopping'; a Wake
+// click runs `...start` as a 'start' job → 'starting'. Returns null for every
+// other action so deriveStatus's existing per-action chain keeps owning it.
+function sleepJobStatus(action) {
+  if (action === 'stop') return 'stopping';
+  if (action === 'start') return 'starting';
+  return null;
+}
+
+// Classify an UNREACHABLE rostered VM. The dashboard already polls GCP for the
+// set of RUNNING fleet instances (runningFleetVms) on its slow 60s cycle, so we
+// reuse it at zero extra API cost: a VM GCP still lists as running but whose
+// control API we can't reach is genuinely 'unreachable' (booting, wedged, or
+// the cloudflared tunnel is down); one absent from the running list has been
+// stopped to pause billing — 'asleep'. A null/absent list is treated as "not
+// running" so a cold dashboard with no poll yet defaults to the safe 'asleep'
+// rather than masking a stopped VM as a red unreachable.
+function unreachableStatus(n, runningFleetVms) {
+  return Array.isArray(runningFleetVms) && runningFleetVms.includes(n)
+    ? 'unreachable'
+    : 'asleep';
+}
+
+module.exports = { sleepJobStatus, unreachableStatus };

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

@@ -0,0 +1,181 @@
+'use strict';
+// Pure classification + self-heal predicates for the fleet dashboard's
+// launcher-strand detection (vm: Fleet converges onto the launcher-strand fix
+// and self-heals the strand regardless of trigger).
+//
+// A cloud VM can strand off its control port `:14199` in bare Project Launcher
+// mode: the editor re-execs into the launcher on an EPHEMERAL port instead of
+// serving its one /workspace project on the contract port, so the dashboard's
+// local-forward probe gets connection-refused and reports a generic
+// "unreachable" — indistinguishable from a real outage. Diagnosed on VM-4
+// (2026-06-25): an add-time binary that predated the `serve_cwd_directly`
+// launcher-strand guard fell through `decide_launch` to the launcher because a
+// stale `/tmp` test-fixture project padded `registry_count` to 2.
+//
+// The completed predecessor plan fixed the editor CODE PATH (serve the cwd
+// project on :14199); this module is the dashboard-side SAFETY NET that detects
+// the strand CONTINUOUSLY — by its trigger-independent SIGNAL SHAPE, not by what
+// caused it — so a running fleet can't silently sit on the landmine. This is the
+// PURE half (classification + decision), mirroring npm/fleet-public-url.js: the
+// docker-exec / curl I/O lives in scripts/operator/fleet-dashboard/server.js's
+// gatherLauncherStrand, the same gather-edge / pure-half split
+// classifyPublicUrlHealth follows. Unit-tested in npm/fleet-strand.test.js.
+//
+// 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 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
+ *  caused the strand (a stale add-time binary, a wiped open-project pointer, any
+ *  future cause):
+ *
+ *    'serving'        — `editorHealthOk`: the control port answers /api/health,
+ *                       so the editor is serving its project. Nothing to heal.
+ *    'launcher-strand'— container up, control port has NO listener, AND a
+ *                       codeyam-editor process is serving the Project Launcher on
+ *                       an ephemeral port. THIS is the strand: :14199 is dark but
+ *                       the editor is alive on the wrong port.
+ *    'down'           — container up, control port dark, and NO launcher process
+ *                       either: a genuine outage (crashed editor / dead tunnel).
+ *                       Left to the existing unreachable handling — must NOT
+ *                       auto-rebuild, a rebuild is the wrong hammer for a crash.
+ *    'unknown'        — anything else (container not up, probe failed): absence
+ *                       of evidence, never auto-acts (mirrors
+ *                       classifyPublicUrlHealth's 'unknown' contract).
+ *
+ *  `editorHealthOk` wins first: once the control port answers, the VM is serving
+ *  no matter what else a slow/racy probe reported. */
+function classifyLauncherStrand({
+  controlPortListening,
+  containerUp,
+  launcherServing,
+  editorHealthOk,
+} = {}) {
+  if (editorHealthOk) return 'serving';
+  if (containerUp && !controlPortListening && launcherServing) return 'launcher-strand';
+  if (containerUp && !controlPortListening && !launcherServing) return 'down';
+  return 'unknown';
+}
+
+/** Decide whether a just-landed strand verdict warrants an auto-recovery, the
+ *  PURE gate the standing self-heal fires through — debounced exactly like
+ *  shouldAutoRewireIngress so a recovery that doesn't immediately clear can't
+ *  loop and a single transient poll during a legitimate restart can't act:
+ *    - `verdict` is 'launcher-strand' (only the strand self-heals; 'down' is a
+ *      genuine outage the unreachable path owns, 'serving'/'unknown' need nothing),
+ *    - `strandStreak` has reached `minStreak` consecutive strand polls (a single
+ *      transient dark-port poll during a restart must not trigger a heavy rebuild),
+ *    - no recovery is `alreadyRecovering` (one heavy job per VM), AND
+ *    - the `cooldownMs` window has elapsed since `lastRecoverAt` so a recovery
+ *      still settling can't re-fire every slow cycle.
+ *  `hasSession` deliberately does NOT gate: a stranded editor has no live project
+ *  session to protect (same rationale as the post-reset force=true fallback). A
+ *  missing/0 `lastRecoverAt` means "never recovered" → the cooldown is satisfied. */
+function shouldAutoRecoverStrand({
+  verdict,
+  strandStreak,
+  alreadyRecovering,
+  lastRecoverAt,
+  now,
+  cooldownMs,
+  minStreak = 2,
+} = {}) {
+  if (verdict !== 'launcher-strand') return false;
+  if (alreadyRecovering) return false;
+  if (Number(strandStreak) < Number(minStreak)) return false;
+  return (Number(now) - (Number(lastRecoverAt) || 0)) >= Number(cooldownMs);
+}
+
+/** Choose the recovery SHAPE for a launcher-strand by binary currency. A plain
+ *  reconfigure KEEPS the editor image, so recreating the container with the SAME
+ *  pre-guard binary would immediately re-strand — the wrong hammer when a stale
+ *  binary caused the strand. Returns:
+ *    'rebuild'     — advance source to origin tip → rebuild-self → restart (the
+ *                    update-reset-everything shape) when the binary is stale OR
+ *                    its currency is UNKNOWN. The dark-control-port strand can't
+ *                    advertise its capability live, and re-stranding on a kept
+ *                    image is the worse failure, so unknown defaults to rebuild.
+ *    'reconfigure' — image-kept container recreate, correct ONLY when the running
+ *                    binary is already CURRENT (e.g. a wiped-pointer strand on a
+ *                    fresh binary), where a rebuild would be a needless ~8-min build.
+ *  `binaryCurrent === true` is the only input that yields 'reconfigure'; null /
+ *  undefined / false all yield 'rebuild'. */
+function strandRecoveryAction({ binaryCurrent } = {}) {
+  return binaryCurrent === true ? 'reconfigure' : 'rebuild';
+}
+
+/** Classify whether a STILL-SERVING VM's running binary is at risk of the
+ *  launcher-strand on its next re-exec — the PROACTIVE convergence signal (step
+ *  5), distinct from the strand verdict above (which fires only once a VM is
+ *  ALREADY dark). Whether a binary is guard-capable is answered most robustly by
+ *  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 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.
+ *  `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)) {
+    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 '${missing}'${because}; rebuild to converge`,
+    };
+  }
+  const behind = Number(editorBehind);
+  if (Number.isFinite(behind) && behind > 0) {
+    return {
+      stale: true,
+      reason: `running binary predates the boot-guard capability and editor source is ${behind} commit(s) behind origin; rebuild to converge`,
+    };
+  }
+  return { stale: false, reason: null };
+}
+
+module.exports = {
+  SERVE_CWD_GUARD,
+  CAPTURE_AUTH_GUARD,
+  classifyLauncherStrand,
+  shouldAutoRecoverStrand,
+  strandRecoveryAction,
+  classifyBinaryGuard,
+};