@codeyam-editor/codeyam-editor 0.1.5 → 0.1.7

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

package/npm/fleet-vm-access.js

@@ -105,6 +105,132 @@ function normalizeAccessList(input) {
   return out;
 }
 
+// The env/config key holding the standing default-operator principal(s) — the
+// fleet owner / ops identity that must ALWAYS be able to reach an IAP-secured VM.
+// Comma-separated `user:`/`group:`/`domain:` principals (a bare email defaults to
+// `user:`), e.g. `VM_ACCESS_DEFAULT=user:jared@codeyam.com`. Read from config, not
+// hardcoded here, so the default operator is tenant-configurable.
+const DEFAULT_OPERATOR_ENV = 'VM_ACCESS_DEFAULT';
+
+// The default gcloud-account resolver, split out so it is the ONLY function that
+// touches child_process — the module stays side-effect-free at load, and
+// resolveDefaultOperator takes an injectable `exec` so its fallback is unit
+// testable without a real gcloud. Returns the active account email, or '' when
+// gcloud is absent / errors (never throws to the caller).
+function defaultGcloudAccountExec() {
+  const { spawnSync } = require('child_process');
+  const r = spawnSync('gcloud', ['config', 'get-value', 'account'], { encoding: 'utf8' });
+  if (!r || r.status !== 0) return '';
+  return String(r.stdout || '').trim();
+}
+
+// Read the standing default-operator principal(s) from `.codeyam/cloud.json`'s
+// `vmAccessDefault` key — the durable per-project config that resolves the default
+// operator even when a launchd/systemd env was never re-baked with
+// `VM_ACCESS_DEFAULT`. Returns the raw config value ('' when the file is missing or
+// malformed, or the key is absent / not a string) so a broken cloud.json is treated
+// as "no config" and never throws. Split out (like defaultGcloudAccountExec) so the
+// cloud.json layer of resolveDefaultOperator is injectable/unit-testable without a
+// real file. `.codeyam/cloud.json` is resolved via `rootDir` — the same repo root
+// the access sidecar and other state files use. `cloudJsonPath` is a parameter
+// (defaulting to that resolved path) so the reader is unit-testable against a temp
+// file, the same injectable-for-testability posture as defaultGcloudAccountExec.
+// The path also honors `VM_ACCESS_CLOUD_JSON` — the same env-override isolation
+// posture as `VM_ACCESS_FILE` above — so a test process (or an operator) can point
+// this read at a throwaway path and never pick up the developer's real
+// `.codeyam/cloud.json` `vmAccessDefault`.
+function defaultCloudConfigRead(
+  cloudJsonPath = process.env.VM_ACCESS_CLOUD_JSON || path.join(rootDir, '.codeyam', 'cloud.json'),
+) {
+  try {
+    const raw = fs.readFileSync(cloudJsonPath, 'utf8');
+    const data = JSON.parse(raw);
+    if (data && typeof data === 'object' && !Array.isArray(data)) {
+      return typeof data.vmAccessDefault === 'string' ? data.vmAccessDefault : '';
+    }
+  } catch { /* missing or malformed cloud.json → no config */ }
+  return '';
+}
+
+/** Resolve the standing default-operator principal(s) that must be granted IAP
+ *  access whenever a VM's IAP is enabled — the fix for "IAP enabled but nobody
+ *  granted" (the Error-51-by-default footgun). Config first, most-specific to
+ *  least:
+ *    1. `VM_ACCESS_DEFAULT` (the env knob) — normalized and returned.
+ *    2. `.codeyam/cloud.json`'s `vmAccessDefault` — the DURABLE per-project config,
+ *       consulted when the env var is unset. This closes the gap that made every
+ *       fleet Add grant nobody: the dashboard/Add runs as the automation SERVICE
+ *       ACCOUNT, and with no `VM_ACCESS_DEFAULT` in the (un-re-baked) launchd env
+ *       the resolver used to fall straight through to the gcloud fallback and skip
+ *       the SA — resolving `[]`. Reading cloud.json here means every caller
+ *       (iap-access.sh, cloud.js, the dashboard) inherits the default operator
+ *       without an env re-bake.
+ *    3. Fallback: the active gcloud account, so a HUMAN operator running these
+ *       scripts locally gets access with no extra config. A SERVICE-ACCOUNT
+ *       session (the automation SA, whose account ends in `gserviceaccount.com`)
+ *       is skipped — granting the automation SA to itself is a pointless no-op,
+ *       and the human/ops identity it should grant is unknowable from the SA
+ *       session, so config (env or cloud.json) is REQUIRED there.
+ *  Returns a normalized principal array (possibly empty — callers treat empty as
+ *  "no default operator configured" and keep their prior behavior). `exec` and
+ *  `readCloudConfig` are injectable so the gcloud and cloud.json fallbacks are
+ *  unit-testable without a real gcloud / file. */
+function resolveDefaultOperator({ env = process.env, exec, readCloudConfig } = {}) {
+  const configured = env[DEFAULT_OPERATOR_ENV];
+  if (configured != null && String(configured).trim() !== '') {
+    try { return normalizeAccessList(configured); } catch { return []; }
+  }
+  let fromCloud = '';
+  try { fromCloud = String((readCloudConfig || defaultCloudConfigRead)() || '').trim(); }
+  catch { fromCloud = ''; }
+  if (fromCloud !== '') {
+    try { return normalizeAccessList(fromCloud); } catch { return []; }
+  }
+  let account = '';
+  try { account = String((exec || defaultGcloudAccountExec)() || '').trim(); }
+  catch { account = ''; }
+  if (account === '' || /gserviceaccount\.com$/i.test(account)) return [];
+  try { return normalizeAccessList(account); } catch { return []; }
+}
+
+/** The loud degraded reason(s) to attach to a freshly-added VM whose IAP would
+ *  authorize NOBODY. Fires only for a SUCCESSFUL `add` (`ok`) in LB mode (`lbMode`
+ *  — a FLEET_DOMAIN is configured so the VM's public URL is IAP-gated) when the
+ *  default operator resolved empty (`resolvedOperatorCount === 0`): the automation-
+ *  SA identity with no `VM_ACCESS_DEFAULT` env AND no `.codeyam/cloud.json`
+ *  `vmAccessDefault` fallback (the 2026-07-09 footgun). In that case the URL comes
+ *  up authorizing nobody yet the add reads as "done" — so we surface the exact
+ *  remedy on the card instead of a silently gated URL. `resolvedOperatorCount` is
+ *  `null` when the caller skipped the (gcloud) resolve because the cheap gates
+ *  already failed; the `!== 0` test covers both null and a positive count. Returns a
+ *  single actionable reason or [] so the dashboard can spread it into
+ *  `degradedReasons` with no conditional at the call site. Pure (no I/O): the string
+ *  lives in exactly one place and the trigger is unit-testable. */
+function noDefaultOperatorDegradedReasons({ ok, action, lbMode, resolvedOperatorCount, vmNumber } = {}) {
+  if (!ok || action !== 'add' || !lbMode || resolvedOperatorCount !== 0) return [];
+  return [
+    'iap-default-operator-missing: IAP default operator not configured — set '
+      + 'VM_ACCESS_DEFAULT or cloud.json vmAccessDefault (the public URL will '
+      + `authorize nobody; run scripts/gcp/iap-access.sh ${vmNumber} grant after configuring).`,
+  ];
+}
+
+/** Union the default-operator principal(s) into an access list, deduped and
+ *  order-preserving (explicit collaborators first, the operator appended if not
+ *  already present). Both inputs are normalized. The result is what gets GRANTED;
+ *  the per-VM sidecar still records only the explicit collaborators, so the
+ *  always-present operator never pollutes the per-VM whitelist display or a
+ *  reused number's stale-revoke computation. */
+function withDefaultOperator(list, defaultOperator) {
+  const base = normalizeAccessList(list);
+  const seen = new Set(base);
+  const out = base.slice();
+  for (const p of normalizeAccessList(defaultOperator)) {
+    if (!seen.has(p)) { seen.add(p); out.push(p); }
+  }
+  return out;
+}
+
 // Read the access sidecar, returning a `{ [vmNumber]: principal[] }` object, or
 // null if the file is missing or malformed (treated as "no access lists"). Keys
 // are the string form JSON emits; callers look them up by `String(n)`.
@@ -208,6 +334,44 @@ function parseProjectMembers(stdout) {
   return out;
 }
 
+/** Reconcile a VM's LOCAL access sidecar against LIVE IAM. PURE — the caller
+ *  does the two reads (the sidecar file, the gcloud IAP probe) and hands both in,
+ *  so this decision logic is unit-testable without the fleet dashboard's
+ *  untestable server shell around it.
+ *
+ *  `sidecar` is the recorded principal list (what someone asked to grant);
+ *  `iapMembers` is the aggregated live-IAM result from
+ *  fleet-public-url.js::aggregateIapMembers, or null/undefined when that read has
+ *  not landed or a surface errored. Returns:
+ *
+ *    live    — the principals IAM actually authorizes. The display truth.
+ *    drift   — sidecar principals live IAM does NOT confirm. These are failed
+ *              grants; a caller renders them flagged, never as access.
+ *    pending — the live read is unavailable, so NEITHER list is verified.
+ *    partial — a principal holds the role on some ingress surfaces but not all.
+ *
+ *  The pending distinction is the whole point. Treating an unavailable read as an
+ *  empty policy would render a genuinely-granted collaborator as missing — the
+ *  same false report as the bug this replaces, merely inverted. So when
+ *  `iapMembers` is absent, `live` is empty, every sidecar principal lands in
+ *  `drift`, and `pending` is true to tell the caller not to assert either way.
+ *
+ *  Comparison is case-insensitive: parseProjectMembers lowercases for
+ *  dedup-stability while the sidecar holds whatever normalizePrincipal produced. */
+function reconcileVmAccess(sidecar, iapMembers) {
+  const recorded = Array.isArray(sidecar) ? sidecar : [];
+  if (!iapMembers || !Array.isArray(iapMembers.all)) {
+    return { live: [], drift: recorded, pending: true, partial: false };
+  }
+  const live = new Set(iapMembers.all.map((m) => String(m).toLowerCase()));
+  return {
+    live: iapMembers.all,
+    drift: recorded.filter((p) => !live.has(String(p).toLowerCase())),
+    pending: false,
+    partial: iapMembers.partial === true,
+  };
+}
+
 /** Drop VM `n`'s entire access list, returning the new map. Clearing an absent
  *  entry is a no-op. Called on Destroy so a number freed and later re-used
  *  doesn't inherit a stale whitelist. */
@@ -221,9 +385,15 @@ function clearAccess(n) {
 module.exports = {
   VM_ACCESS_FILE,
   PRINCIPAL_TYPES,
+  DEFAULT_OPERATOR_ENV,
   normalizePrincipal,
   normalizeAccessList,
+  resolveDefaultOperator,
+  defaultCloudConfigRead,
+  noDefaultOperatorDegradedReasons,
+  withDefaultOperator,
   parseProjectMembers,
+  reconcileVmAccess,
   readAccess,
   writeAccess,
   accessFor,