@codeyam-editor/codeyam-editor 0.1.4 → 0.1.6

package/npm/fleet-destroy-safety.js

@@ -0,0 +1,272 @@
+'use strict';
+// Pure decision + formatting helpers for the fleet dashboard's destroy/deroster
+// false-unreachable safety (2026-06-26 incident, where a reauth-triggered
+// false-unreachable cascade permanently deleted VM2/3/4). The dashboard's
+// server.js gathers the live operator-fault facts (state.operatorAuthDegraded +
+// fleetWideUnreachableNow) and runs the side effects (spawn the delete, log,
+// stop+deroster); the DECISIONS those facts drive — "is this destroy blocked,
+// and why" and "what does the attribution log line read" — live here so they
+// are unit-testable in isolation, the same pure/IO split npm/fleet-auth-health.js
+// (classifyOperatorAuth) and npm/fleet-cleanup.js (reconcileRosteredVm) follow.
+//
+// Pure logic only — no I/O, no env reads, no clock, no global state.
+
+// Concurrent-gcloud count above which a pile-up is itself evidence that the
+// operator plane is resource-throttled rather than credential-broken. Measured
+// 2026-07-29: 16 concurrent gcloud processes at load 8.49 with the cgroup near
+// MemoryHigh, against a steady state of 0-2. Set well above steady state so a
+// couple of ordinary in-flight polls never read as a pile-up.
+const GCLOUD_PILEUP_THRESHOLD = 8;
+
+// Fraction of the cgroup's memory.high at which memory counts as throttling
+// pressure. MUST stay below the 0.874 that actually occurred on 2026-07-29, or
+// the incident goes undetected and this whole change is inert — there is a
+// regression test pinning exactly that.
+//
+// Deliberately NOT fleet-memory.decideMemoryDrain, which looks superficially like
+// the same decision and is the wrong signal twice over:
+//   1. WRONG QUANTITY. It reads process.memoryUsage().rss — the node process
+//      alone. memory.current is the whole CGROUP, including the 16 gcloud
+//      subprocesses. Under a fork storm the pressure lives precisely in what RSS
+//      excludes, so RSS systematically under-reads this condition.
+//   2. WRONG THRESHOLD. Its soft cap is 1500 MB = 97.7% of the observed
+//      memory.high, but the incident sat at 87.4% — it returns false at the
+//      measured value.
+// The two coexist because they answer different questions: decideMemoryDrain
+// asks "should I admit another heavy job?", this asks "is the plane too starved
+// to trust its own probes?".
+const MEMORY_PRESSURE_RATIO = 0.85;
+
+// The recovery for a resource-throttled operator plane. Named once here so the
+// refusal message, the log line, and the tests can never drift apart.
+const THROTTLE_NEXT_ACTION = 'systemctl restart codeyam-dashboard';
+
+// Classify whether the operator plane is RESOURCE-THROTTLED (starved) rather
+// than credential-broken, from the cheap local pressure signals server.js reads.
+// Neither input spawns a subprocess — which matters, because spawning one is
+// exactly what fails when this condition holds.
+//   memoryCurrent       the cgroup's memory.current, in bytes
+//   memoryHigh          the cgroup's memory.high, in bytes ('max' when the cgroup
+//                       is unlimited, which yields no ratio and so no signal)
+//   gcloudProcessCount  concurrent gcloud processes on the host
+// Returns { throttled, signals }: `signals` names the evidence, so the refusal
+// message can cite WHY it concluded throttling instead of asserting it. An absent
+// or unreadable signal contributes nothing rather than defaulting to pressure —
+// fabricating pressure would relabel a REAL auth break as a memory problem, which
+// is the same class of misdiagnosis in the opposite direction.
+function classifyOperatorThrottle({ memoryCurrent, memoryHigh, gcloudProcessCount } = {}) {
+  const signals = [];
+  const cur = Number(memoryCurrent);
+  const high = Number(memoryHigh);
+  if (Number.isFinite(cur) && Number.isFinite(high) && high > 0) {
+    const ratio = cur / high;
+    if (ratio >= MEMORY_PRESSURE_RATIO) {
+      signals.push(`${Math.round(ratio * 100)}% of the cgroup memory throttle`);
+    }
+  }
+  const procs = Number(gcloudProcessCount);
+  if (Number.isFinite(procs) && procs >= GCLOUD_PILEUP_THRESHOLD) {
+    signals.push(`${procs} concurrent gcloud processes`);
+  }
+  return { throttled: signals.length > 0, signals };
+}
+
+// Classify whether a destructive removal (hard destroy or --shrink) must be
+// REFUSED because the operator's own side is faulted, from the facts server.js
+// computes. Returns { blocked, kind, reason, nextAction }: blocked is true when
+// the operator's plane is faulted (auth degraded) OR a fleet-wide unreachable
+// spike is in progress — the signature of a host-side fault (which makes EVERY VM
+// read unreachable), NOT N genuinely-dead VMs.
+//
+// The `kind` split exists because a throttled plane and a broken credential have
+// OPPOSITE recoveries, and reporting the wrong one is the 2026-07-29 defect: the
+// banner sent the operator to fix an SA binding that was perfectly healthy, or to
+// reach for override-safety — punching through the one guard that exists because
+// a false-unreachable cascade permanently deleted VM2/3/4 on 2026-06-26. The
+// correct action, restarting the dashboard, was named nowhere.
+//
+// A throttled verdict requires BOTH halves of the evidence: the auth probe
+// produced no answer (authProbeFailed — a failed invocation, not a failed
+// credential) AND local pressure corroborates it. Empty probe output on its own
+// stays inconclusive and keeps the auth reason, so a transient hiccup is never
+// relabeled a memory problem; a genuine auth ERROR is never reclassified at all,
+// no matter how loaded the host is.
+//
+// What this does NOT do is let anything through. Every degraded classification
+// returns blocked: true — the refusal was correct, only its diagnosis was wrong.
+//   authDegraded      state.operatorAuthDegraded — the operator plane is faulted
+//   authProbeFailed   the auth verdict's kind was 'probe-failed' (empty output,
+//                     no error message) rather than 'auth'
+//   memoryCurrent     the cgroup's memory.current in bytes (see
+//   memoryHigh        the cgroup's memory.high in bytes    classifyOperatorThrottle)
+//   gcloudProcessCount concurrent gcloud processes on the host
+//   fleetWide         fleetWideUnreachableNow() — N+ VMs unreachable at once
+function classifyDestroyBlock({ authDegraded, authProbeFailed, memoryCurrent, memoryHigh, gcloudProcessCount, fleetWide } = {}) {
+  if (authDegraded) {
+    const pressure = classifyOperatorThrottle({ memoryCurrent, memoryHigh, gcloudProcessCount });
+    if (authProbeFailed && pressure.throttled) {
+      return {
+        blocked: true,
+        kind: 'throttled',
+        reason: `operator plane resource-exhausted (${pressure.signals.join(', ')}) — the auth probe was starved, not denied`,
+        nextAction: THROTTLE_NEXT_ACTION,
+      };
+    }
+    return {
+      blocked: true,
+      kind: 'auth',
+      reason: 'operator gcloud auth degraded',
+      nextAction: 'resolve auth (SA binding) — scripts/operator/setup-service-account.sh',
+    };
+  }
+  if (fleetWide) {
+    return {
+      blocked: true,
+      kind: 'fleet-wide',
+      reason: 'fleet-wide unreachable spike in progress (operator-side fault signature)',
+      nextAction: 'wait out the spike',
+    };
+  }
+  // The NOT-blocked shape stays exactly { blocked, reason } — `kind` and
+  // `nextAction` describe a fault, and there is no fault here to describe.
+  return { blocked: false, reason: null };
+}
+
+// Classify a non-Force destroy's unpushed-commit INTENT decision from the WARM
+// ahead-count the dashboard reads off /api/session-info, mirroring the pure
+// decision shape of classifyDestroyBlock. The three outcomes:
+//   ahead number > 0        → REFUSE: unpushed work exists (Force-recoverable)
+//   ahead number === 0      → PROCEED: verified clean
+//   ahead null / undefined  → REFUSE: could NOT verify (editor unreachable /
+//                             field absent) — a DISTINCT refusal, never conflated
+//                             with "VM down", and Force-recoverable
+// Returns { refuse, forceable, outcome, msg }: `outcome` is the
+// logDestroyDecision attribution token (null when proceeding); `msg` is the
+// operator-facing refusal text (null when proceeding). Pure — the caller owns the
+// warm probe, the cached fallback, the logging, and the return; this only maps
+// ahead → decision so it is unit-testable in isolation (the way the cold-SSH
+// version never was).
+function classifyUnpushedDestroy({ n, ahead } = {}) {
+  if (typeof ahead === 'number' && ahead > 0) {
+    return {
+      refuse: true,
+      forceable: true,
+      outcome: 'REFUSED:unpushed',
+      msg: `VM-${n} has ${ahead} unpushed commit(s) — not destroying. Use Force to override.`,
+    };
+  }
+  if (ahead === 0) {
+    return { refuse: false, forceable: false, outcome: null, msg: null };
+  }
+  return {
+    refuse: true,
+    forceable: true,
+    outcome: 'REFUSED:unverifiable',
+    msg: `VM-${n} — could not verify unpushed commits (editor unreachable). Use Force to destroy anyway.`,
+  };
+}
+
+// Build the single attributable destroy-decision log line. Mirrors the
+// performAutoReset "confirmed … not fleet-wide" template so every destroy —
+// proceed OR refused, across every trigger source — is diagnosable from one
+// grep. `remote` ({ ip, ua }) is the caller attribution whose absence made the
+// 2026-06-26 delete impossible to trace back to its trigger; null/absent renders
+// as `n/a` (e.g. the shrink / reap paths have no HTTP caller). All the flag
+// fields are normalized to real booleans so a missing field never reads as
+// `undefined` in the line.
+function formatDestroyDecision(info = {}) {
+  const remote = info.remote ? `${info.remote.ip || '?'}/${info.remote.ua || '?'}` : 'n/a';
+  return (
+    `destroy-decision: VM-${info.n} source=${info.source} force=${!!info.force} ` +
+    `override=${!!info.overrideSafety} remote=${remote} hasSession=${!!info.hasSession} ` +
+    `authDegraded=${!!info.authDegraded} fleetWide=${!!info.fleetWide} → ${info.outcome}`
+  );
+}
+
+// Build the ENTRY line for a destroy request, emitted before any probe runs —
+// the third sibling of formatDestroyDecision (the up-front DECISION) and
+// formatDestroyOutcome (the terminal JOB fate). Without it a request that died
+// mid-flight left NO record at all: on 2026-07-29 two destroy POSTs both ended in
+// HTTP 000 and the log's last entry was an earlier refusal, so the operator could
+// not tell whether a delete had started against their VM — the worst possible
+// answer to "did you delete it?".
+//
+// It keeps the `destroy-decision:` prefix so ONE grep still finds a request's
+// whole life, and carries only what is known at entry. It deliberately does NOT
+// render authDegraded/fleetWide/hasSession: those are not measured yet, and
+// printing `false` for an unmeasured verdict would read as "auth was fine" —
+// exactly the false diagnosis this change exists to remove.
+function formatDestroyAttempt(info = {}) {
+  const remote = info.remote ? `${info.remote.ip || '?'}/${info.remote.ua || '?'}` : 'n/a';
+  return (
+    `destroy-decision: VM-${info.n} attempt source=${info.source} force=${!!info.force} ` +
+    `override=${!!info.overrideSafety} remote=${remote}`
+  );
+}
+
+// Render the operator-facing REFUSAL for a blocked destructive removal, pairing
+// the verdict's reason with its verdict-specific recovery. Extracted from
+// server.js so the "a throttled refusal never sends the operator at auth"
+// property is assertable at the MESSAGE level, not just on the reason field.
+//
+// The recovery renders as the greppable `Next valid action:` contract (CLAUDE.md
+// CLI error conventions) rather than as prose. override-safety is mentioned LAST
+// and never as the primary fix: it bypasses the guard that exists because a
+// false-unreachable cascade permanently deleted VM2/3/4 on 2026-06-26, and
+// putting it beside the real recovery is what made two operators reach for it
+// within one session. `detail` lets the shrink path swap the wording while
+// keeping an identical recovery contract, so the two destructive paths that share
+// operatorFaultVerdict can never give conflicting advice for one fault.
+function formatDestroyRefusal({ n, reason, nextAction, detail } = {}) {
+  const what = detail || `refusing to destroy VM-${n}`;
+  return (
+    `REFUSED: ${reason} — ${what}; a false-unreachable storm can delete healthy VMs.\n` +
+    `Next valid action: ${nextAction}\n` +
+    'If this destructive action is genuinely intended right now, pass override-safety.'
+  );
+}
+
+// Render the refusal for a destroy whose DECISION exceeded its wall-clock budget.
+// HTTP 000 is the worst possible answer to "did you delete my VM?" — it is
+// indistinguishable from a delete that started and lost its response, and it is
+// what two destroy POSTs returned on 2026-07-29 after 150s and 240s.
+//
+// The wording is deliberately "no verdict" and "no delete CONFIRMED dispatched",
+// not "nothing happened": the in-flight decision may still resolve after the
+// bound elapses, so claiming otherwise would be a second false certainty. It
+// points at the `destroy-decision:` grep instead, which the entry-time attempt
+// line guarantees is populated.
+function formatDestroyBoundExceeded({ n, budgetMs } = {}) {
+  return (
+    `REFUSED: no destroy verdict for VM-${n} within ${Math.round(budgetMs / 1000)}s — ` +
+    'the dashboard is not answering, which usually means it is resource-throttled.\n' +
+    `Next valid action: ${THROTTLE_NEXT_ACTION}\n` +
+    `No delete was confirmed dispatched; grep the log for \`destroy-decision: VM-${n}\` to see how far this request got.`
+  );
+}
+
+// Build the single TERMINAL-OUTCOME journal line for a completed destroy JOB —
+// the sibling of formatDestroyDecision, which records the up-front DECISION. The
+// decision line alone was a blind spot: diagnosing the VM-8 silent refusal
+// surfaced only `destroy-decision … → proceed:delete`, nothing about how the job
+// itself ended, so a job that refused/errored after the decision was invisible.
+// With this line a completed destroy's fate is one `grep destroy-outcome` away.
+// `outcome` is the caller-computed terminal string: `done`, `refused:<kind>`, or
+// `error code=<n>`. Pure format only — the caller owns the classification.
+function formatDestroyOutcome(info = {}) {
+  return `destroy-outcome: VM-${info.n} ${info.outcome}`;
+}
+
+module.exports = {
+  GCLOUD_PILEUP_THRESHOLD,
+  MEMORY_PRESSURE_RATIO,
+  THROTTLE_NEXT_ACTION,
+  classifyDestroyBlock,
+  classifyOperatorThrottle,
+  classifyUnpushedDestroy,
+  formatDestroyAttempt,
+  formatDestroyBoundExceeded,
+  formatDestroyDecision,
+  formatDestroyOutcome,
+  formatDestroyRefusal,
+};

package/npm/fleet-early-roster.js

@@ -0,0 +1,87 @@
+'use strict';
+
+// npm/fleet-early-roster.js — decides WHEN an in-flight `add` earns its roster
+// entry.
+//
+// Background (vm--batch-add-must-roster-and-wire-each-vm): rostering used to
+// happen in exactly one place on the live add path — `startJob`'s onSuccess
+// callback — which only fires when the whole ~28-minute add script exits 0. A
+// VM whose container came up but whose add later failed (wiring, reachability,
+// a dashboard SIGKILL) was therefore never rostered, and an unrostered VM is
+// invisible to `reconcile-ingress`, which skips it. That produced a deadlock:
+//
+//   not rostered → reconcile skips → no backend service → LB 503 →
+//   not reachable → bootstrap recovery retries → exhausted → still not rostered
+//
+// Observed live 2026-07-20 provisioning VM-4..VM-11: the roster stayed `[1,2,3]`
+// for a `count=8` add even though every container was `Up` and serving 200
+// locally. The only recovery was to destroy and re-add one at a time.
+//
+// The fix is to roster EARLY — as soon as the instance exists and the container
+// gate has passed — so a later-stage failure leaves a *rostered, reconcilable*
+// VM that the periodic sweep can finish wiring, rather than an invisible one.
+// The add script announces that moment by printing a marker line; `startJob`
+// taps the child's stdout and hands the accumulated text here.
+//
+// This module is PURE (no fs, no network, no roster writes) so the "has this VM
+// earned its roster entry yet" rule is unit-testable without a live VM. The
+// actual `addToRoster` write stays in server.js.
+
+// The marker the add script prints once its container gate passes. Chosen to
+// match the existing `CY_DEGRADED` marker convention that `startJob` already
+// scans for, so both live in the same namespace and are equally greppable in a
+// job log.
+const ROSTER_MARKER = 'CY_ROSTER';
+
+// Build the marker line the add script emits. Kept here (rather than inlined in
+// server.js) so the emitter and the parser can never drift apart — a test that
+// round-trips `parseRosterMarkers(rosterMarkerLine(n))` pins them together.
+function rosterMarkerLine(n) {
+  return `${ROSTER_MARKER} ${n}`;
+}
+
+// Extract every VM number announced by a roster marker in `text`.
+//
+// Scans the FULL accumulated buffer rather than a single chunk: child stdout
+// arrives in arbitrary chunks that can split a line mid-marker, so a
+// chunk-local parse would miss (or double-count) a marker straddling a
+// boundary. Re-parsing the whole buffer is idempotent and cheap relative to the
+// ~28-minute job it rides along with.
+//
+// Returns unique numbers in ascending order. Junk (`CY_ROSTER abc`,
+// `CY_ROSTER 1.5`, a bare `CY_ROSTER`) is dropped — the roster is a set of
+// VM-number integers, so a malformed marker must never poison it.
+function parseRosterMarkers(text) {
+  if (typeof text !== 'string' || text === '') return [];
+  const out = new Set();
+  for (const line of text.split('\n')) {
+    const t = line.trim();
+    if (!t.startsWith(`${ROSTER_MARKER} `)) continue;
+    const rest = t.slice(ROSTER_MARKER.length + 1).trim();
+    // Reject anything that is not a plain positive integer. `Number()` alone
+    // would accept '1.5', '0x2', and ' 3 '; the regex gate keeps it strict.
+    if (!/^\d+$/.test(rest)) continue;
+    const n = Number(rest);
+    if (Number.isInteger(n) && n > 0) out.add(n);
+  }
+  return [...out].sort((a, b) => a - b);
+}
+
+// Should VM `n` be rostered right now, given the job output so far?
+//
+// `alreadyRostered` is the caller's own latch — server.js flips it after the
+// first successful write so a marker sitting in the buffer for the rest of the
+// job doesn't re-trigger a write on every subsequent chunk. (The roster write
+// is itself idempotent, so this is an efficiency guard, not a correctness one.)
+function shouldEarlyRoster({ text, vmNumber, alreadyRostered } = {}) {
+  if (alreadyRostered) return false;
+  if (!Number.isInteger(vmNumber) || vmNumber <= 0) return false;
+  return parseRosterMarkers(text).includes(vmNumber);
+}
+
+module.exports = {
+  ROSTER_MARKER,
+  rosterMarkerLine,
+  parseRosterMarkers,
+  shouldEarlyRoster,
+};

package/npm/fleet-effect-poll.js

@@ -0,0 +1,110 @@
+'use strict';
+// Self-healing cycle guard for the Fleet Dashboard's slow effect poll
+// (scripts/operator/fleet-dashboard/server.js requires this). No gcloud/SSH
+// I/O — this module owns the control-flow guarantee ONLY; the server keeps its
+// gather edges and worker pools.
+//
+// The bug this fixes: `pollEffects` guards against overlap with a
+// `effectPollRunning` flag (two concurrent full cycles would double the gcloud
+// load), releasing it in a `finally` that runs only AFTER
+// `await Promise.all(...)` of the reachable + launcher-strand sweeps. On
+// 2026-07-09 a single probe's callback never fired (an SSH/docker-exec against
+// VM-8, whose GCP instance had been deleted mid-session), so that awaited
+// promise never resolved, the `finally` never ran, and `effectPollRunning`
+// stayed `true` forever — every subsequent 45s tick early-returned and fleet
+// readiness (iapAccess, backendHealth, readiness, launcher-strand self-heal)
+// froze fleet-wide until the dashboard was restarted.
+//
+// Two guarantees make that freeze impossible:
+//   makeGuardedCycle — the no-overlap guard is kept (it's correct), but its
+//     release is made unconditional: the returned promise ALWAYS settles, either
+//     when the tasks finish or when a whole-cycle watchdog fires, and the guard
+//     flag is cleared in a `finally` either way. A hung task can no longer strand
+//     the next tick.
+//   withTimeout — wraps a single probe promise so a never-firing callback
+//     resolves to a safe fallback verdict instead of hanging the sweep.
+
+// Wrap a promise so it can never hang the caller: resolve to `fallback` if
+// `promise` has not settled within `ms`, and also on rejection (a probe that
+// throws must degrade gracefully, never reject the whole sweep). `ms <= 0`
+// disables the timeout and just awaits the promise (rejections still fold to
+// `fallback`), so a caller can opt a leg out without branching. Whichever of
+// (settle, timeout) happens first wins; the other is a no-op.
+function withTimeout(promise, ms, fallback) {
+  const settled = Promise.resolve(promise).catch(() => fallback);
+  if (!(ms > 0)) return settled;
+  return new Promise((resolve) => {
+    let done = false;
+    const finish = (val) => { if (!done) { done = true; resolve(val); } };
+    // NOT unref'd: this timer is load-bearing — it resolves the promise the
+    // caller awaits, so letting the event loop exit before it fires would leave
+    // the await hung. It is cleared the instant the real promise settles, so it
+    // holds the loop open only for the (short) timeout window.
+    const timer = setTimeout(() => finish(fallback), ms);
+    settled.then((val) => { clearTimeout(timer); finish(val); });
+  });
+}
+
+// Build a guarded cycle runner. `run(tasks)` executes an array of zero-arg async
+// task factories (or bare promises) under a no-overlap guard:
+//   - while a cycle is in flight, a second `run(...)` returns `{ skipped: true }`
+//     immediately without launching the tasks — the no-overlap contract.
+//   - the returned promise ALWAYS settles: when the tasks finish, or — if
+//     `watchdogMs > 0` — when the whole-cycle watchdog fires first (returning
+//     `{ wedged: true }`). Either way the guard flag is cleared in a `finally`,
+//     so the NEXT tick can always run. A never-resolving task therefore cannot
+//     permanently wedge the loop (the 2026-07-09 freeze).
+// `onWedge(elapsedMs)` (optional) is called when the watchdog fires, so the
+// caller can log a wedge warning. A task that rejects is swallowed (one bad probe
+// must not fail the whole cycle); the caller composes concurrency/ordering.
+function makeGuardedCycle(opts) {
+  const o = opts || {};
+  const watchdogMs = o.watchdogMs > 0 ? o.watchdogMs : 0;
+  const onWedge = typeof o.onWedge === 'function' ? o.onWedge : null;
+  let running = false;
+  const run = async (tasks) => {
+    if (running) return { skipped: true };
+    running = true;
+    try {
+      const work = Promise.all((tasks || []).map((t) => (typeof t === 'function' ? t() : t)))
+        .then(() => false, () => false); // settle to `wedged=false`; swallow a rejecting probe
+      let wedged = false;
+      if (watchdogMs > 0) {
+        wedged = await new Promise((resolve) => {
+          // NOT unref'd: this watchdog resolves the promise the caller awaits, so
+          // it must keep the loop alive until it fires (or the work settles first
+          // and clears it). Unref'ing it would let a standalone await hang.
+          const timer = setTimeout(() => resolve(true), watchdogMs);
+          work.then((w) => { clearTimeout(timer); resolve(w); });
+        });
+      } else {
+        await work;
+      }
+      if (wedged && onWedge) { try { onWedge(watchdogMs); } catch (e) { /* logging must never re-wedge */ } }
+      return { skipped: false, wedged };
+    } finally {
+      // Unconditional release — the whole point. Whether the tasks finished or
+      // the watchdog fired, the guard is cleared so the next tick proceeds. Any
+      // still-pending task keeps running detached, but holds no guard.
+      running = false;
+    }
+  };
+  return { run };
+}
+
+// A roster entry whose Add errored out is an `add-failed` ghost: its GCP instance
+// may be half-created or already reconciled away, so an SSH/docker-exec strand
+// probe against it is the exact call that hung the 2026-07-09 sweep (VM-8). The
+// strand selection skips it — a failed Add is owned by the reachable / vanish
+// reconcilers, not the launcher-strand self-heal. `withTimeout` (above) is the
+// general backstop for any hung probe; this removes the doomed probe at the
+// source for the named trigger.
+function isAddFailedGhost(job) {
+  return !!(job && job.state === 'error' && job.action === 'add');
+}
+
+module.exports = {
+  withTimeout,
+  makeGuardedCycle,
+  isAddFailedGhost,
+};

package/npm/fleet-effect-status.js

@@ -58,12 +58,10 @@ function resetReason({ agent, session, dirty, behind, codeyam }) {
 // meaningless for them).
 const ACTION_IDS = [
   'update-client-source',
-  'update-editor-source',
-  'reset-editor-source',
   'reset-client',
+  'end-session',
   'rebuild-binary',
   'update-reset-everything',
-  'run-setup',
 ];
 
 // facts (a plain object gathered by server.js — no I/O):
@@ -105,13 +103,6 @@ function computeButtonEffects(facts) {
       ? { effect: 'changes', reason: behindReason(client.behind, f.clientBranch) }
       : { effect: 'noop', reason: 'up to date with ' + originRef(f.clientBranch) };
 
-  // (2) Update editor — advance the editor source the binary builds from.
-  const updateEditor = editor == null
-    ? { effect: 'unknown', reason: 'editor state not checked' }
-    : editor.behind > 0
-      ? { effect: 'changes', reason: behindReason(editor.behind, f.editorBranch) }
-      : { effect: 'noop', reason: 'up to date with ' + originRef(f.editorBranch) };
-
   // (5) Rebuild binary — advances source then compiles. Changes iff the running
   // binary's build commit differs from the editor origin tip. Unknown when we
   // don't have both commits to compare.
@@ -121,25 +112,38 @@ function computeButtonEffects(facts) {
       ? { effect: 'changes', reason: `binary at ${short(editor.buildCommit)}, ${originRef(f.editorBranch)} at ${short(editor.originSha)}` }
       : { effect: 'noop', reason: 'binary built from ' + originRef(f.editorBranch) + ' tip' };
 
-  // (3) Reset editor — discards uncommitted + session, advances source, wipes
-  // .codeyam. No-op ONLY when clean at origin tip with no session.
+  // Reset editor (editor-state reset) — discards uncommitted + session, advances
+  // source, wipes .codeyam. No-op ONLY when clean at origin tip with no session.
+  // INTERNAL-ONLY: the standalone "Reset editor" button was removed; this
+  // predicate survives purely as an input to the "Reset all + rebuild" composite
+  // below (which still runs resetEditorStateScript), so it is NOT returned/keyed.
   const resetEditor = editor == null
     ? { effect: 'unknown', reason: 'editor state not checked' }
     : (brokerLive || hasSession || editor.dirty || editor.behind > 0 || codeyamDirty)
       ? { effect: 'changes', reason: resetReason({ agent: brokerLive, session: hasSession, dirty: editor.dirty, behind: editor.behind > 0, codeyam: codeyamDirty }) }
       : { effect: 'noop', reason: 'already clean at origin tip, no session' };
 
-  // (3b) Reset client — hard-clean /workspace + .codeyam, drop the session.
-  // No source-advance, so `behind` is NOT part of this predicate.
+  // (2) Reset client — hard-clean /workspace + .codeyam, drop the session, now
+  // ADVANCING to origin tip. Since the reset advances source, a VM behind origin
+  // would be changed by a re-run, so `behind` IS part of this predicate.
   const resetClient = client == null
     ? { effect: 'unknown', reason: 'client state not checked' }
-    : (brokerLive || client.dirty || codeyamDirty || hasSession)
-      ? { effect: 'changes', reason: resetReason({ agent: brokerLive, session: hasSession, dirty: client.dirty, behind: false, codeyam: codeyamDirty }) }
-      : { effect: 'noop', reason: 'already clean, no session' };
+    : (brokerLive || client.dirty || client.behind > 0 || codeyamDirty || hasSession)
+      ? { effect: 'changes', reason: resetReason({ agent: brokerLive, session: hasSession, dirty: client.dirty, behind: client.behind > 0, codeyam: codeyamDirty }) }
+      : { effect: 'noop', reason: 'already clean at origin tip, no session' };
 
-  // (4b) Update & Reset Everything — composite. Changes iff ANY component would
-  // change: rebuild-binary, reset-editor-source, or the client being
-  // behind/dirty. Reason summarizes which parts.
+  // (2b) End session — kills the live agent + clears session state. The ONLY
+  // thing it touches is the running session, so it changes the VM iff a live
+  // agent or a registered session exists; otherwise it's a clean no-op. Unlike
+  // the resets it ignores dirty/behind/.codeyam — it neither advances source nor
+  // wipes state.
+  const endSession = (brokerLive || hasSession)
+    ? { effect: 'changes', reason: resetReason({ agent: brokerLive, session: hasSession }) }
+    : { effect: 'noop', reason: 'no active session' };
+
+  // (4) Reset all + rebuild — composite. Changes iff ANY component would
+  // change: rebuild-binary, the editor-state reset (internal resetEditor
+  // predicate above), or the client being behind/dirty. Reason summarizes parts.
   const everything = (() => {
     if (editor == null || client == null) {
       return { effect: 'unknown', reason: 'state not checked' };
@@ -157,23 +161,20 @@ function computeButtonEffects(facts) {
     return { effect: 'noop', reason: 'everything already at origin tip, no session' };
   })();
 
-  // (run-setup) Honest soft signal — there is no cheap upstream proof that
-  // `npm run setup` would change nothing (DB/migration state isn't
-  // introspected). `recommended` when a reset/update landed after the last
-  // successful setup; otherwise `unknown`. Never a confident green no-op.
-  const runSetup = f.setupRanSince
-    ? { effect: 'unknown', reason: 'no setup-affecting change since last setup' }
-    : { effect: 'recommended', reason: 'a reset/update landed since the last setup' };
-
   return {
     'update-client-source': updateClient,
-    'update-editor-source': updateEditor,
-    'reset-editor-source': resetEditor,
     'reset-client': resetClient,
+    'end-session': endSession,
     'rebuild-binary': rebuild,
     'update-reset-everything': everything,
-    'run-setup': runSetup,
   };
 }
 
-module.exports = { computeButtonEffects, ACTION_IDS };
+// Decide whether a Live Preview SSH forward needs to be re-wired (improve41)
+function needsRewire(forwardAppPort, polledAppPort) {
+  if (typeof polledAppPort !== 'number' || isNaN(polledAppPort)) return false;
+  if (!forwardAppPort) return false;
+  return forwardAppPort !== polledAppPort;
+}
+
+module.exports = { computeButtonEffects, ACTION_IDS, needsRewire };