@codeyam-editor/codeyam-editor 0.1.4 → 0.1.6

package/npm/fleet-iap-token.js

@@ -0,0 +1,165 @@
+'use strict';
+// IAP identity-token caching for the fleet dashboard's per-VM probes.
+//
+// On the GCE operator host the dashboard reaches each VM through its
+// IAP-fronted LB hostname, which requires an OIDC ID token whose audience is
+// the fleet's IAP OAuth client id.
+//
+// There are two mint paths, and they are NOT interchangeable:
+//
+//   - `buildGceIdentityTokenRequest` — the metadata server's identity endpoint
+//     with `format=full`. The only one IAP actually accepts, because IAP
+//     authorizes on the token's `email` claim and only `format=full` carries it.
+//     This is the dashboard's path on the operator host.
+//   - `gcloudMintArgs` — `gcloud auth print-identity-token`, which mirrors
+//     `scripts/operator/fleet-redeploy.sh`. Retained for the off-GCE (laptop)
+//     path, where a human account's gcloud session is the credential. It does
+//     NOT emit an email claim, so it cannot authenticate the on-GCE probe.
+//
+// The dashboard polls every VM every few seconds, so minting per probe would
+// fork a gcloud process per VM per poll. Instead we mint once and cache until
+// shortly before the token's own expiry.
+//
+// Pure logic only — the token cache, the JWT expiry read, and the gcloud argv
+// are all pure; the caller injects `mintToken` (the actual subprocess) and
+// `now`. Keeps it unit-testable in isolation like vm-urls.js.
+
+// Refresh this long before the token's stated expiry. An IAP token lives ~1h;
+// renewing a minute early means an in-flight poll can never race the boundary
+// and get a 401 that would render as "auth misconfigured" on every card.
+const EXPIRY_SKEW_MS = 60_000;
+
+// Fallback lifetime when a minted token carries no readable `exp`. Deliberately
+// short: re-minting slightly too often is cheap, serving a dead token is not.
+const FALLBACK_TTL_MS = 5 * 60_000;
+
+/** The gcloud argv that mints an IAP identity token for `clientId`.
+ *  Mirrors fleet-redeploy.sh's `gcloud_sa auth print-identity-token
+ *  --audiences=<IAP_CLIENT_ID>` so both sides request the same audience. */
+function gcloudMintArgs({ clientId } = {}) {
+  const id = clientId == null ? '' : String(clientId).trim();
+  if (id === '') throw new Error('gcloudMintArgs requires an IAP client id');
+  return ['auth', 'print-identity-token', `--audiences=${id}`];
+}
+
+// The GCE metadata server's OIDC identity endpoint. Reachable only from a GCE
+// instance, and only with the `Metadata-Flavor: Google` header.
+const GCE_IDENTITY_URL =
+  'http://metadata.google.internal/computeMetadata/v1/instance/service-accounts/default/identity';
+
+/** The metadata-server request that mints an IAP identity token for `audience`.
+ *
+ *  Two details are load-bearing and were validated live against the fleet IAP
+ *  on 2026-07-19:
+ *
+ *  - `format=full` is what makes the token carry `email` + `email_verified`.
+ *    IAP authorizes on the email, so the default (`format=standard`) token —
+ *    and equally `gcloud auth print-identity-token`, which also omits email —
+ *    is rejected with a 401 no matter how correct the audience is.
+ *  - `audience` must be the MANUAL OAuth client id the backends are configured
+ *    with. Google-managed IAP exposes no usable programmatic audience: the
+ *    client id recovered from IAP's browser 302 is rejected as `Invalid JWT
+ *    audience`. See scripts/gcp/google-ingress.sh step 8.
+ */
+function buildGceIdentityTokenRequest({ audience } = {}) {
+  const aud = audience == null ? '' : String(audience).trim();
+  if (aud === '') throw new Error('buildGceIdentityTokenRequest requires an IAP client id');
+  return {
+    url: `${GCE_IDENTITY_URL}?audience=${encodeURIComponent(aud)}&format=full`,
+    headers: { 'Metadata-Flavor': 'Google' },
+  };
+}
+
+/** Which mint path applies, given the host and the configured audience.
+ *
+ *  Three outcomes, and the distinction between the last two is the fix:
+ *    'unconfigured' — no client id. There is no audience to mint for, so the
+ *                     probe must report 'auth-misconfigured' rather than mint
+ *                     a token IAP will reject.
+ *    'metadata'     — on the GCE operator host. Only the metadata endpoint's
+ *                     format=full token carries the `email` claim IAP
+ *                     authorizes on.
+ *    'gcloud'       — off GCE (laptop), where there is no metadata server and
+ *                     a human gcloud session is the credential.
+ */
+function selectMintStrategy({ onGce, clientId } = {}) {
+  const id = clientId == null ? '' : String(clientId).trim();
+  if (id === '') return 'unconfigured';
+  return onGce ? 'metadata' : 'gcloud';
+}
+
+/** Read the `exp` claim (ms since epoch) out of a JWT without verifying it.
+ *  We are not authenticating the token — the LB does that — we only need to
+ *  know when to stop reusing it. Returns null for anything unparseable, which
+ *  sends the caller to FALLBACK_TTL_MS. */
+function decodeJwtExpiryMs(token) {
+  const raw = token == null ? '' : String(token).trim();
+  const parts = raw.split('.');
+  if (parts.length !== 3) return null;
+  try {
+    const payload = JSON.parse(Buffer.from(parts[1], 'base64url').toString('utf8'));
+    const exp = Number(payload && payload.exp);
+    if (!Number.isFinite(exp) || exp <= 0) return null;
+    return exp * 1000;
+  } catch {
+    return null;
+  }
+}
+
+/** Build a caching IAP-token provider.
+ *
+ *  `mintToken()` must resolve to a raw token string (or null/'' on failure);
+ *  `now()` returns epoch ms. Returns `{ getToken }`, where getToken() resolves
+ *  to a usable token or null. Null is a first-class outcome — the probe layer
+ *  turns it into 'auth-misconfigured' rather than a false "unreachable", so a
+ *  broken credential is legible on the card instead of looking like a dead VM.
+ *
+ *  Concurrent callers share one in-flight mint: the dashboard probes N VMs in
+ *  parallel each poll, and without this a cold cache would fork N gcloud
+ *  processes simultaneously.
+ */
+function createIapTokenProvider({ mintToken, now, skewMs = EXPIRY_SKEW_MS } = {}) {
+  if (typeof mintToken !== 'function') {
+    throw new Error('createIapTokenProvider requires a mintToken function');
+  }
+  const clock = typeof now === 'function' ? now : Date.now;
+
+  let cached = null;
+  let expiresAtMs = 0;
+  let inFlight = null;
+
+  async function mintAndCache() {
+    const token = await mintToken();
+    const value = token == null ? '' : String(token).trim();
+    if (value === '') {
+      cached = null;
+      expiresAtMs = 0;
+      return null;
+    }
+    const exp = decodeJwtExpiryMs(value);
+    cached = value;
+    expiresAtMs = exp == null ? clock() + FALLBACK_TTL_MS : exp;
+    return cached;
+  }
+
+  async function getToken() {
+    if (cached !== null && clock() + skewMs < expiresAtMs) return cached;
+    if (inFlight === null) {
+      inFlight = mintAndCache().finally(() => { inFlight = null; });
+    }
+    return inFlight;
+  }
+
+  return { getToken };
+}
+
+module.exports = {
+  EXPIRY_SKEW_MS,
+  FALLBACK_TTL_MS,
+  GCE_IDENTITY_URL,
+  gcloudMintArgs,
+  buildGceIdentityTokenRequest,
+  selectMintStrategy,
+  decodeJwtExpiryMs,
+  createIapTokenProvider,
+};

package/npm/fleet-job-badge.js

@@ -2,7 +2,7 @@
 
 // npm/fleet-job-badge.js — pure verdict for the fleet dashboard's failed-job
 // badge reconciliation (improve39). A VM's last terminal-error heavy job
-// (add/error, reset-all error, reset-editor error, …) used to stick on the
+// (add/error, reset-all error, reset-client error, …) used to stick on the
 // dashboard card indefinitely — even after the VM was recovered and is healthy
 // again — because the card renders the last job's error with no check against
 // the VM's live state, so a recovered VM keeps screaming a red error and

package/npm/fleet-launchd.js

@@ -0,0 +1,171 @@
+'use strict';
+// Pure helpers for running a VM `add` provision as its OWN transient launchd
+// job (`com.codeyam.fleet-add-vm-<n>`) — improve46 Phase 3. The provision job
+// is a SIBLING of `com.codeyam.fleet-dashboard` rather than a `setsid` child of
+// it, so a `launchctl bootout` of the dashboard label (which tears down the
+// whole dashboard launchd job tree regardless of session/process-group) has no
+// authority over the provision. Phases 1 (signal-kill reclassification) and 2
+// (the reinstall in-flight-add guard) still compose with this — Phase 3 reduces
+// how often a bootout reaches the provision at all.
+//
+// All the string-building and parsing lives here so server.js can stay thin and
+// these pieces are unit-testable WITHOUT launchctl (npm/fleet-launchd.test.js) —
+// the same decomposition `npm/fleet-cleanup.js` uses for the reap brain.
+//
+// Stack assumption: launchd is macOS-only. server.js gates the whole own-job
+// path on platform + a `launchctl` probe and falls back to the existing `setsid`
+// detached spawn on cloud containers / CI / Linux, where these helpers are never
+// reached. They are pure either way.
+
+// The launchd label for VM-n's transient add-provision job. ONE label per VM
+// number so the re-add collision guard and the completion teardown each address
+// exactly one job. Mirrors the `com.codeyam.fleet-*` label family used by the
+// dashboard's other launchd agents (see scripts/operator/launchd-reinstall.sh).
+function addVmLabel(n) {
+  return `com.codeyam.fleet-add-vm-${n}`;
+}
+
+// The file the transient job's stdout/stderr are redirected to (the plist's
+// Standard{Out,Error}Path). The dashboard tails this for the in-progress card's
+// live log when the launchd path is taken — the equivalent of the `setsid`
+// path's stdout pipe, which a separate launchd job can't share. Kept DISTINCT
+// from `/tmp/dash-add-vm-<n>.log` (the addVm script's own `cloud:up` redirect)
+// so the provision shell's progress echoes ("provisioning…", "VM-n provisioned")
+// aren't interleaved with the cloud:up build output.
+function addVmJobLogPath(n) {
+  return `/tmp/dash-add-vm-${n}.provision.log`;
+}
+
+// XML-escape a string for safe inclusion in a plist `<string>` body. Plists are
+// XML, so the five predefined entities must be escaped or a path/env value with
+// `&`/`<`/`>`/quotes would corrupt the plist. Pure.
+function xmlEscape(s) {
+  return String(s == null ? '' : s)
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&apos;');
+}
+
+// Build a transient launchd plist (XML text) that runs `programArguments` ONCE
+// under `label`. RunAtLoad=true so `launchctl bootstrap` fires it immediately;
+// KeepAlive=false so launchd NEVER relaunches the provision after it exits (a
+// one-shot job, not a daemon). stdout/stderr go to `logPath` so the dashboard
+// can tail the live card. `environment` (the bootstrap form env) and
+// `workingDirectory` are optional. Pure — caller writes the returned text to a
+// temp file and bootstraps it.
+function buildAddVmPlist({ label, programArguments, logPath, workingDirectory, environment } = {}) {
+  const args = (Array.isArray(programArguments) ? programArguments : [])
+    .map((a) => `    <string>${xmlEscape(a)}</string>`)
+    .join('\n');
+  const lines = [
+    '<?xml version="1.0" encoding="UTF-8"?>',
+    '<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">',
+    '<plist version="1.0">',
+    '<dict>',
+    '  <key>Label</key>',
+    `  <string>${xmlEscape(label)}</string>`,
+    '  <key>ProgramArguments</key>',
+    '  <array>',
+    args,
+    '  </array>',
+    '  <key>RunAtLoad</key>',
+    '  <true/>',
+    '  <key>KeepAlive</key>',
+    '  <false/>',
+  ];
+  if (logPath) {
+    lines.push('  <key>StandardOutPath</key>', `  <string>${xmlEscape(logPath)}</string>`);
+    lines.push('  <key>StandardErrorPath</key>', `  <string>${xmlEscape(logPath)}</string>`);
+  }
+  if (workingDirectory) {
+    lines.push('  <key>WorkingDirectory</key>', `  <string>${xmlEscape(workingDirectory)}</string>`);
+  }
+  const env = environment && typeof environment === 'object' ? environment : null;
+  if (env && Object.keys(env).length > 0) {
+    lines.push('  <key>EnvironmentVariables</key>', '  <dict>');
+    for (const [k, v] of Object.entries(env)) {
+      lines.push(`    <key>${xmlEscape(k)}</key>`, `    <string>${xmlEscape(v)}</string>`);
+    }
+    lines.push('  </dict>');
+  }
+  lines.push('</dict>', '</plist>', '');
+  return lines.join('\n');
+}
+
+// Parse the integer pid from `launchctl print gui/$UID/<label>` output. While
+// the job's process is alive the block contains a `pid = N` line; this resolves
+// it so the dashboard records the REAL provision pid into the sidecar `meta.pid`
+// (the field `reattachVerdict`'s `kill -0` re-attach reads) rather than the
+// launchctl invocation's own pid. Returns the integer pid, or null when there's
+// no live process line (job not started yet, already exited, or junk). `pid = 0`
+// is treated as no-pid. Pure: takes the text so it's testable without launchctl.
+function parseLaunchdPrintPid(text) {
+  const m = String(text == null ? '' : text).match(/^\s*pid\s*=\s*(\d+)\b/m);
+  if (!m) return null;
+  const pid = Number(m[1]);
+  return Number.isInteger(pid) && pid > 0 ? pid : null;
+}
+
+// Filter a captured transcript down to the live-card tail: drop the noisy
+// gcloud/IAP/NumPy lines and keep the last `maxLines`. Pure — the same shaping
+// startJob's `tailLog` applies to the setsid stdout pipe, extracted so the
+// launchd path's logfile tail and the setsid path share ONE tested filter
+// instead of duplicating the regex + slice.
+function filterTailLog(text, maxLines = 14) {
+  return String(text == null ? '' : text).split('\n')
+    .filter((l) => !/WARNING|NumPy|google\.com\/iap/.test(l))
+    .join('\n').trim().split('\n').slice(-maxLines).join('\n');
+}
+
+// True when a `spawnSync` result represents a successful launchctl invocation:
+// a defined result with a zero exit status and no spawn error (ENOENT etc.).
+// Pure — lets the bootstrap/`load -w` success checks be one tested predicate.
+function launchctlSpawnSucceeded(result) {
+  return !!result && result.status === 0 && !result.error;
+}
+
+// Decide what the launchd add-completion watcher should do on one tick, from the
+// durable signals it gathers: the exit marker's code (or null when absent),
+// whether the launchd process is still alive, and how many consecutive ticks it
+// has been gone. Pure state machine — the I/O (reading the marker, `kill -0`,
+// tailing the log) stays in the server.js watcher; this owns the decision so it
+// is exhaustively testable without launchd.
+//   - marker present                 → done, that exit code (the normal path)
+//   - process gone for `graceTicks`  → done, exit 1 (EXIT trap never wrote a
+//                                       marker — resolve the card as a failure
+//                                       rather than tailing forever)
+//   - process gone, under grace      → keep waiting, bump goneTicks
+//   - process alive                  → keep waiting, reset goneTicks
+function launchdWatchVerdict({ markerExitCode, pidAlive, goneTicks = 0, graceTicks = 3 } = {}) {
+  if (markerExitCode != null) return { done: true, exitCode: markerExitCode, goneTicks: 0 };
+  if (!pidAlive) {
+    const next = goneTicks + 1;
+    if (next >= graceTicks) return { done: true, exitCode: 1, goneTicks: next };
+    return { done: false, goneTicks: next };
+  }
+  return { done: false, goneTicks: 0 };
+}
+
+// Decide whether the own-launchd-job path should be taken for a spawn. Pure
+// gate: it's taken only for a `detached` add (the sole caller that passes
+// `detached`) AND on a host where `launchctl` is actually present. Everything
+// else — a non-detached job, or a host with no launchctl (cloud container / CI /
+// Linux) — falls back to the existing `setsid` detached spawn. Centralised here
+// so the gate is one tested predicate, not an inline `&&` at the spawn site.
+function shouldUseLaunchd({ detached, hasLaunchctl } = {}) {
+  return !!detached && !!hasLaunchctl;
+}
+
+module.exports = {
+  addVmLabel,
+  addVmJobLogPath,
+  xmlEscape,
+  buildAddVmPlist,
+  parseLaunchdPrintPid,
+  filterTailLog,
+  launchctlSpawnSucceeded,
+  launchdWatchVerdict,
+  shouldUseLaunchd,
+};

package/npm/fleet-live-status.js

@@ -0,0 +1,155 @@
+'use strict';
+// Pure session/broker live-status derivation for the Fleet Dashboard's per-VM
+// status LABEL (scripts/operator/fleet-dashboard/server.js requires this). This
+// is the trailing decision of deriveStatus, after every heavy-job / orphan /
+// failed-badge branch has been ruled out: given the reachable VM's session and
+// broker signals, is it building, waiting, or genuinely idle?
+//
+// The bug this fixes (observed live 2026-06-20, VM-1): the label was derived
+// SOLELY from `hasSession` — the editor server's own in-process build-session
+// flag. But a Claude agent's lifetime is owned by the PTY broker, deliberately
+// DECOUPLED from the editor-server lifetime (see docs/process-model.md). After a
+// server restart, or for a broker-resumed/detached agent the server didn't spawn
+// itself, `hasSession` is false while a fully-live agent keeps working in the
+// broker. The card fell through to 'idle' even though the broker dot — driven by
+// the same `brokerStatus` — already showed 'agent-live'. The label and the dot
+// disagreed.
+//
+// The fix consults the already-debounced broker tri-state (from
+// fleet-broker-status.js, threaded in by the caller) so a broker-held live agent
+// reads as working, not idle. `awaitingUserInput` is honored independent of
+// `hasSession`, so a broker-live agent blocked on input reads 'waiting'.
+//
+// The terminal-done refinement (observed live 2026-06-21): a broker-live agent
+// whose WORKFLOW reached its terminal step is parked alive at its prompt but is
+// NOT building — the editor masks the feature and reports `needsCleanup: true`
+// (session_info_response.rs). Without this signal the card showed an active-green
+// "Building" border on a finished, idle VM. We discriminate on `needsCleanup`
+// (a positive terminal signal) rather than feature-emptiness (also briefly true
+// at session START, which would mislabel a just-starting agent as done). This
+// only ever DOWNGRADES a would-be-'building' verdict to 'session-done'; a
+// mid-feature post-restart agent is not terminal (`needsCleanup` falsy) and stays
+// 'building', preserving the 2026-06-20 decoupled-agent fix above.
+//
+// Returns 'waiting' | 'building' | 'session-done' | 'idle' for a reachable VM, or
+// `null` when the VM is unreachable — the caller maps null to its own
+// asleep/unreachable verdict (it owns the running-fleet snapshot this module
+// deliberately does not touch) and otherwise passes the verdict through verbatim
+// as the card's `status`, so 'session-done' must match the card's status class.
+// Precedence is preserved: an unreachable VM returns null regardless of a stale
+// 'agent-live', so the broker branch only ever upgrades a would-be-idle verdict.
+function liveSessionStatus(v, brokerStatus) {
+  // Unreachable: we polled nothing reliable. Defer to the caller's
+  // asleep/unreachable mapping — a stale broker signal must not mask it.
+  if (!v.reachable) return null;
+  if (v.hasSession && v.awaitingUserInput) return awaitingVerdict(v);
+  if (v.hasSession) return 'building';
+  // No editor-owned session, but a live agent may still be working in the PTY
+  // broker (decoupled lifetime — see docs/process-model.md). The broker
+  // tri-state is already debounced upstream; agent-live ⇒ working, not idle.
+  if (brokerStatus === 'agent-live') {
+    if (v.awaitingUserInput) return awaitingVerdict(v);
+    // The agent is parked alive in the broker's build slot, but its workflow
+    // reached the terminal step (editor reports needsCleanup) — finished and
+    // idle, not building. A mid-feature post-restart agent is NOT terminal and
+    // still reads 'building' (preserves the 2026-06-20 decoupled-agent fix).
+    if (v.needsCleanup) return 'session-done';
+    return 'building';
+  }
+  return 'idle';
+}
+
+// Does the VM have a task/feature genuinely running? `feature`/`featureStartedAt`
+// (from /api/session-info) are both None at a fresh prompt and Some once a build
+// feature is selected, so either being present means a task is in flight.
+function hasActiveFeature(v) {
+  return !!(v.feature || v.featureStartedAt);
+}
+
+// Discriminate an `awaitingUserInput` agent between two very different shapes
+// (observed live 2026-06-30, VM-1): an agent parked at its prompt with NO task
+// running is IDLE — ready and waiting for YOU to start something — not the same
+// as a running task BLOCKED on a human answer. Only the latter is 'waiting'
+// (which the needs-you overlay later escalates). A no-feature, non-terminal
+// awaiting agent reads 'idle' so a freshly-launched healthy VM never false-flags
+// "Waiting"/"Needs You". `needsCleanup` (the terminal-done signal the module
+// already trusts) keeps a finished session out of the idle bucket.
+function awaitingVerdict(v) {
+  if (!v.needsCleanup && !hasActiveFeature(v)) return 'idle';
+  return 'waiting';
+}
+
+// Distinguish a freshly-rostered VM whose editor is still STARTING UP — a normal
+// cold boot that hasn't bound :14199 yet, or (the VM-2 case) the ~10–15-min
+// self-host `rebuild-self --force-in-container` compile that recompiles the
+// editor binary from source before the server can listen — from a genuinely DEAD
+// one. deriveStatus (scripts/operator/fleet-dashboard/server.js) calls this only
+// after it has already established the VM is rostered, unreachable, and GCP still
+// lists it RUNNING — i.e. exactly the case that otherwise falls through to the
+// red 'unreachable' that made a successful Add look like a failure.
+//
+// Returns 'editor-starting' when EITHER the VM was launched within the grace
+// window (`recentlyLaunched` — the cheap common case, no SSH needed) OR an
+// in-container probe has CONFIRMED a first-run build is still running
+// (`probeBuilding === true`), which lets the long self-host compile keep reading
+// "Starting editor…" past the window with no fragile fixed timeout. Returns null
+// otherwise so deriveStatus runs its existing unreachable path unchanged — an
+// honest red card the moment the grace window lapses with no confirmed build. A
+// DISTINCT key from the wake-path 'starting' (fleet-sleep-status.js) so the two
+// in-progress states never collide. Pure; the caller owns the time + SSH I/O.
+function classifyStartingVsUnreachable({ recentlyLaunched = false, probeBuilding = null } = {}) {
+  if (recentlyLaunched || probeBuilding === true) return 'editor-starting';
+  return null;
+}
+
+// Classify the in-container startup probe (server.js's editorStartingInContainer
+// one-IAP-SSH round-trip) into the tri-state the verdict cache stores and
+// classifyStartingVsUnreachable consumes. Mirrors fleet-cleanup.js's
+// classifyProjectWiring shape: takes the raw `{ stdout, err }` and parses the
+// three `---CY---`-separated segments the probe emits — the `docker ps` status
+// line, the count of listeners on :14199, and the count of live first-run build
+// processes (`rebuild-self` / `cargo build`):
+//   true  — container up, :14199 NOT yet bound, and a build process is alive ⇒
+//           still building (keeps the card calm-blue past the grace window).
+//   false — container up but :14199 already bound (the normal reachable path
+//           will win) OR up-and-idle with no build process (let the card flip to
+//           honest 'unreachable'); also a clean response with the container down.
+//   null  — an ssh/docker blip (`err`) ⇒ inconclusive; never upgrades a
+//           past-window card (stays honest), re-probed next poll.
+function classifyStartupProbe({ stdout, err } = {}) {
+  if (err) return null;
+  const parts = String(stdout == null ? '' : stdout).split('---CY---').map((s) => s.trim());
+  const containerUp = /^Up\b/m.test(parts[0] || '');
+  const portBound = (Number((parts[1] || '0').trim()) || 0) > 0;
+  const buildProcAlive = (Number((parts[2] || '0').trim()) || 0) > 0;
+  if (!containerUp) return false; // clean response, container down → not building
+  if (portBound) return false; // already serving — the reachable path owns it
+  return buildProcAlive ? true : false;
+}
+
+// Pure gate deciding whether pollStartupProbes should fire the (costly) IAP-SSH
+// build probe for a given VM this tick. We only probe a VM that is PLAUSIBLY
+// still starting — present, unreachable, GCP still lists it RUNNING, not blocked
+// by an active heavy job, and either recently launched OR already confirmed
+// building on a prior tick (so a ~15-min self-host compile keeps being probed
+// past the grace window with no fixed cap). A healthy/reachable VM, an
+// asleep/vanished one, or a long-idle one that simply went unreachable is never
+// probed.
+//
+// The add-job exception (observed live 2026-06-30, VM-1): an active ADD job does
+// NOT block the probe. The long self-host container build runs *under* the add,
+// so we must probe DURING it to prime `wasBuilding` early — otherwise, by the
+// time the add completes the recentlyLaunched grace has already lapsed, no prior
+// probe ever ran (the old `!jobActive` guard suppressed them all), and the
+// still-booting editor falls straight to red 'unreachable' instead of calm
+// 'editor-starting'. Priming `wasBuilding` during the add lets the probe chain
+// carry the card calm past the grace with no fixed cap. Any OTHER active heavy
+// job (rebuild/destroy/reconfigure/…) still gates the probe out — its own status
+// already owns the card. Pure so pollStartupProbes stays a thin SSH loop and this
+// decision matrix is exhaustively unit-testable without booting the server.
+function shouldProbeStartup({ vmPresent = false, reachable = false, gcpRunning = false, jobActive = false, jobIsAdd = false, recentlyLaunched = false, wasBuilding = false } = {}) {
+  const blockedByJob = jobActive && !jobIsAdd;
+  return vmPresent && !reachable && gcpRunning && !blockedByJob && (recentlyLaunched || wasBuilding);
+}
+
+module.exports = { liveSessionStatus, classifyStartingVsUnreachable, classifyStartupProbe, shouldProbeStartup };