@codeyam-editor/codeyam-editor 0.1.0-staging.gac4ca32 → 0.1.0-staging.gc446a6f

package/npm/cloud.js

@@ -159,11 +159,17 @@ const KNOWN_FLAGS = [
   // default is loud — a tokenless VM cannot sync plan claims and must never
   // report healthy silently. Use only when push genuinely isn't wanted.
   "allow-no-git-credentials",
+  // Provision the VM in admin mode: forward CODEYAM_ADMIN=1 into the container
+  // so the Home-tab Setup door renders. Equivalent to `CODEYAM_ADMIN=1 npm run
+  // cloud:up …`; absent = strict non-admin (the safe default). Survives
+  // re-provision because it rides the compose-render substitution, unlike a
+  // manual VM compose edit.
+  "admin",
 ];
 
 // Flags that take no value (presence = true). parseFlags must not demand a
 // value for these or `--no-tunnel` would error "requires a value".
-const BOOLEAN_FLAGS = ["no-tunnel", "skip-setup", "list", "allow-no-git-credentials"];
+const BOOLEAN_FLAGS = ["no-tunnel", "skip-setup", "list", "allow-no-git-credentials", "admin"];
 
 const FIREWALL_RULE_NAME = "codeyam-editor-iap-ssh";
 const INSTANCE_TAG = "codeyam-editor";
@@ -1496,6 +1502,43 @@ function bootstrapLogTail(cfg, lines = 40) {
   return String(r.stdout || "").trim() || "(log unavailable)";
 }
 
+/** Assemble the extra provision-time env forwarded into the bootstrap shell,
+ *  where it feeds the compose-render substitution. Currently just the admin
+ *  toggle: CODEYAM_ADMIN gates the Home-tab Setup door and is read from the
+ *  editor-server process env (handlers.rs::admin_enabled, strict literal "1").
+ *  The operator opts in with `CODEYAM_ADMIN=1 npm run cloud:up …` or `--admin`
+ *  (which lands as cfg.admin); anything else forwards "" so a normal launch —
+ *  and a re-provision without the flag — is strict non-admin. Pure over its
+ *  inputs so cloud.test.js can pin it without touching gcloud. */
+function buildProvisionEnv(env = process.env, flags = {}) {
+  const admin = flags.admin === true || env.CODEYAM_ADMIN === "1";
+  return { CODEYAM_ADMIN: admin ? "1" : "" };
+}
+
+/** Build the one-shot SSH shell command that reconciles a running VM's admin
+ *  mode without a full re-provision: rewrite the rendered compose's
+ *  CODEYAM_ADMIN line to `value` — or insert it under `environment:` on a legacy
+ *  VM whose compose predates the placeholder — then recreate the editor service
+ *  so admin_enabled() re-reads it. `value` is always "1" or "" (the caller
+ *  normalizes), so inlining it into sed is safe. Pure/string-only so
+ *  cloud.test.js can assert its shape without SSHing. */
+function buildReconcileAdminCommand(repoName, value) {
+  const f = "docker-compose.cloud.yml";
+  const entry = `      - CODEYAM_ADMIN=${value}`;
+  // Capture only the leading indentation (\1) and re-emit the literal key, so a
+  // value that starts with a digit (e.g. "1") never lands right after the
+  // backreference — `\11` would be read by sed as group 11, not `\1` + "1".
+  return (
+    `cd ~/projects/${repoName} && ` +
+    `if grep -qE '^[[:space:]]*- CODEYAM_ADMIN=' ${f}; then ` +
+    `sed -i -E 's#^([[:space:]]*)- CODEYAM_ADMIN=.*#\\1- CODEYAM_ADMIN=${value}#' ${f}; ` +
+    `else ` +
+    `sed -i -E 's#^([[:space:]]*environment:[[:space:]]*)$#\\1\\n${entry}#' ${f}; ` +
+    `fi && ` +
+    `docker compose -f ${f} up -d editor`
+  );
+}
+
 async function ensureProjectBootstrapped(cfg) {
   const repoName = resolveProject(cfg).name;
   console.error(`Checking project bootstrap state for ${repoName}...`);
@@ -1549,12 +1592,18 @@ async function ensureProjectBootstrapped(cfg) {
   const ingressEnv = {};
   const ingressPlan = ingressWiringPlan(cfg);
   if (ingressPlan.wire) ingressEnv.FLEET_DOMAIN = ingressPlan.domain;
+  // Forward the admin-mode toggle (Home-tab Setup door) into the compose
+  // render. cfg.admin carries the `--admin` flag; process.env.CODEYAM_ADMIN
+  // carries the `CODEYAM_ADMIN=1 npm run cloud:up` form. Default "" =
+  // non-admin, so this leaves the normal launch and re-provision unchanged.
+  const provisionEnv = buildProvisionEnv(process.env, cfg);
   const command = sshScriptCommand(scriptBody, scriptArgs, {
     GITHUB_TOKEN: resolveGithubToken(),
     CY_GIT_USER_NAME: laptopGit.name,
     CY_GIT_USER_EMAIL: laptopGit.email,
     ...ingressEnv,
     ...forwardEnv,
+    ...provisionEnv,
   });
   const result = runGcloud(
     buildGcloudArgs("ssh-script", cfg, { command }),
@@ -1842,6 +1891,15 @@ function classifyGitRemoteError(stderr) {
   ) {
     return "network";
   }
+  // A greenfield project (`--new-project` scaffold) has no origin remote and an
+  // unborn `main`, so `git ls-remote origin` fails with "does not appear to be a
+  // git repository". No token would fix this — there is simply nothing to push
+  // yet — so it is neither `credential` nor `network` nor `git-spawn`. Keep the
+  // match narrow: `repository not found` is a genuine access failure against a
+  // real remote and must NOT be swallowed here.
+  if (lower.includes("does not appear to be a git repository")) {
+    return "no-remote";
+  }
   return "other";
 }
 
@@ -1879,6 +1937,14 @@ function decideCredentialHeal({ stagingEmpty, lsRemoteOk, lsRemoteStderr }) {
         reason: "git binary failed to launch — not a credential gap, not re-seeding",
       };
     }
+    if (category === "no-remote") {
+      return {
+        heal: false,
+        category,
+        reason:
+          "no git remote configured — greenfield project, nothing to push yet (not a credential gap)",
+      };
+    }
     return {
       heal: true,
       category,
@@ -3941,6 +4007,39 @@ async function cmdReconcileCredentials(args, projectDir = rootDir) {
   );
 }
 
+/** `cloud:reconcile-admin` — flip admin mode on/off for an already-running VM
+ *  WITHOUT a full re-provision. Resolves the desired value from this invocation
+ *  (`--admin` / `CODEYAM_ADMIN`, else off), rewrites the rendered compose's
+ *  CODEYAM_ADMIN line, and recreates the editor service — matching what a manual
+ *  compose edit + `docker compose up -d editor` does today, so the durable admin
+ *  setting no longer requires a full re-provision to change. */
+async function cmdReconcileAdmin(args, projectDir = rootDir) {
+  ensureGcloud();
+  const flags = parseFlags(args);
+  const cfg = loadCloudConfig(projectDir);
+  if (!cfg) {
+    throw new Error("No .codeyam/cloud.json found. Run `npm run cloud:up` first.");
+  }
+  const desired =
+    buildProvisionEnv(process.env, flags).CODEYAM_ADMIN === "1" ? "1" : "";
+  const repoName = resolveProject(cfg).name;
+  console.error(
+    `Reconciling admin mode to ${desired === "1" ? "ON" : "off"} on ${cfg.instanceName}...`,
+  );
+  const result = runGcloud(
+    buildGcloudArgs("ssh-probe", cfg, {
+      command: buildReconcileAdminCommand(repoName, desired),
+    }),
+    { stdio: "inherit" },
+  );
+  if (result.status !== 0) {
+    throw new Error(`Failed to reconcile admin mode on ${cfg.instanceName}.`);
+  }
+  console.error(
+    `  ✓ editor service recreated; /api/config now reports admin=${desired === "1" ? "true" : "false"}.`,
+  );
+}
+
 /** Provision-time guarantee that a just-provisioned VM can actually reach
  *  GitHub. Probes the staging file + in-container `git ls-remote origin` and
  *  routes the outcome through the SAME {@link decideCredentialHeal} classifier
@@ -4072,6 +4171,7 @@ const HANDLERS = {
   "reconcile-ingress": cmdReconcileIngress,
   "wire-add-tail": cmdWireAddTail,
   "reconcile-credentials": cmdReconcileCredentials,
+  "reconcile-admin": cmdReconcileAdmin,
   access: cmdAccess,
 };
 
@@ -4141,6 +4241,9 @@ module.exports = {
   loadCloudConfig,
   saveCloudConfig,
   loadOrInitCloudConfig,
+  buildProvisionEnv,
+  buildReconcileAdminCommand,
+  cmdReconcileAdmin,
   buildEditorLocalEnvPatch,
   buildEditorLocalSeedWriteCommand,
   seedPreviewOrigin,

package/npm/empty-project-dir.js

@@ -1,13 +1,14 @@
 "use strict";
 
 /**
- * Launcher-side mirror of `is_empty_project_dir` in
+ * Launcher-side mirrors of `is_empty_project_dir` and
+ * `looks_like_onboardable_project` in
  * `crates/codeyam-editor/src/commands/init.rs`. The Rust side decides
- * which `/codeyam-…` skill the init binary points at; this JS mirror
- * decides the same for the launcher's post-launch tail banner. Keep
- * both in sync — the test `empty-project-dir.test.js` and Rust's
- * `is_empty_project_dir_ignores_hidden_entries` /
- * `is_empty_project_dir_detects_visible_entry` pin the contract.
+ * which `/codeyam-…` skill the init binary points at; these JS mirrors
+ * decide the same for the launcher's post-launch tail banner. Keep both
+ * predicates in sync with Rust — the test `empty-project-dir.test.js`
+ * and Rust's `is_empty_project_dir_*` / `looks_like_onboardable_project_*`
+ * tests pin the contracts.
  *
  * A "fresh" project directory has no non-hidden entries — only things
  * like `.git/`, `.gitignore`, or other dotfiles. Hidden entries don't
@@ -19,6 +20,7 @@
  */
 
 const fs = require("node:fs");
+const path = require("node:path");
 
 function isEmptyProjectDir(projectDir) {
   let entries;
@@ -30,4 +32,87 @@ function isEmptyProjectDir(projectDir) {
   return entries.every((name) => name.startsWith("."));
 }
 
-module.exports = { isEmptyProjectDir };
+// Root files that signal a real project: dependency/build manifests,
+// lockfiles, and the static-site `index.html`. Mirror of the Rust
+// `MANIFEST_MARKERS` list.
+const MANIFEST_MARKERS = new Set([
+  "package.json",
+  "Cargo.toml",
+  "pyproject.toml",
+  "requirements.txt",
+  "setup.py",
+  "go.mod",
+  "Gemfile",
+  "pom.xml",
+  "build.gradle",
+  "build.gradle.kts",
+  "composer.json",
+  "pubspec.yaml",
+  "Package.swift",
+  "mix.exs",
+  "deno.json",
+  "CMakeLists.txt",
+  "Makefile",
+  "tsconfig.json",
+  "index.html",
+]);
+
+// Subdirectories that signal an organized source tree. Mirror of the Rust
+// `SOURCE_DIR_MARKERS` list.
+const SOURCE_DIR_MARKERS = new Set([
+  "src",
+  "app",
+  "lib",
+  "pages",
+  "components",
+  "crates",
+  "packages",
+  "source",
+  "include",
+]);
+
+/**
+ * Does this directory contain a *project* worth onboarding, as opposed to
+ * being empty or holding only a stray file or two? Mirror of Rust
+ * `looks_like_onboardable_project`. A folder "contains a project" when it
+ * holds a recognized manifest / lockfile, a `.csproj` / `.xcodeproj`, a root
+ * `index.html`, OR an organized source subdirectory. Intentionally
+ * marker-based, not file-count based: a home dir full of loose files is still
+ * not a project. A read error returns false (not a project → the
+ * auto-init/open path), matching Rust's `Err(_) => false`.
+ */
+function looksLikeOnboardableProject(projectDir) {
+  let entries;
+  try {
+    entries = fs.readdirSync(projectDir, { withFileTypes: true });
+  } catch {
+    return false;
+  }
+  for (const entry of entries) {
+    const name = entry.name;
+    if (MANIFEST_MARKERS.has(name)) {
+      return true;
+    }
+    if (name.endsWith(".csproj") || name.endsWith(".xcodeproj")) {
+      return true;
+    }
+    // Source-tree markers only count as directories, not like-named files.
+    if (SOURCE_DIR_MARKERS.has(name)) {
+      let isDir = entry.isDirectory();
+      // A symlinked source dir surfaces as a symlink Dirent; resolve it.
+      if (!isDir && entry.isSymbolicLink()) {
+        try {
+          isDir = fs.statSync(path.join(projectDir, name)).isDirectory();
+        } catch {
+          isDir = false;
+        }
+      }
+      if (isDir) {
+        return true;
+      }
+    }
+  }
+  return false;
+}
+
+module.exports = { isEmptyProjectDir, looksLikeOnboardableProject };

package/npm/fleet-add-failure.js

@@ -0,0 +1,155 @@
+'use strict';
+
+const fc = require('./fleet-cleanup');
+
+// npm/fleet-add-failure.js — pure classifier for a FAILED fleet-dashboard `add`
+// provision. Before this, every failed add rendered an identical red "add error"
+// badge whose only action was "Clear badge", and a restart mid-add collapsed the
+// message to a content-free `(re-attached after restart — detached provision
+// exited 1)`. The real cause — captured to the provision transcript on disk — was
+// thrown away. This happened live with VM9/VM10: both aborted at the streamed-
+// script drift guard because a bootstrap script had uncommitted local edits, but
+// the operator saw only "exited 1" and had to dig through /tmp/dash-add-vm-N.log.
+//
+// classifyAddFailure turns a transcript tail + exit code into a differentiated,
+// ACTIONABLE verdict: a plain-language headline, a concrete recovery instruction,
+// and — crucially — a `retryable` flag that is true ONLY for failures where the
+// classifier can PROVE nothing was provisioned, so a one-click retry can never
+// silently orphan or duplicate a half-provisioned GCP box. The decision logic
+// lives here as a pure module (like fleet-job-badge.js::canClearBadge) so the
+// whole failure matrix is unit-tested without a live VM; server.js is the thin
+// I/O shell that gathers the transcript and turns the verdict into a card + a
+// server-re-guarded retry action.
+
+// The SINGLE source of truth for which categories are safe to auto-retry: only
+// failures where nothing was provisioned. `retryable` on every returned verdict
+// is stamped from this Set, so the invariant `retryable === has(category)` holds
+// by construction and the server can re-guard a retry against the same Set.
+const ADD_FAILURE_RETRYABLE = new Set(['preflight-drift', 'instance-vanished']);
+
+// Collect the `    - <path>` bullets the drift guard prints AFTER the "following
+// files differ" header (see npm/cloud.js), stopping at the first non-bullet line
+// so an unrelated "- " elsewhere in the transcript can't leak in. Returns [] when
+// no drift block is present.
+function extractDriftFiles(logTail) {
+  const lines = String(logTail || '').split('\n');
+  const files = [];
+  let inBlock = false;
+  for (const line of lines) {
+    if (!inBlock) {
+      if (/following files differ/i.test(line)) inBlock = true;
+      continue;
+    }
+    const m = line.match(/^\s+-\s+(.+?)\s*$/);
+    if (m) { files.push(m[1]); continue; }
+    break; // first non-bullet after the header ends the block
+  }
+  return files;
+}
+
+// Pure transform: the last `maxLines` non-empty lines of a transcript, each
+// right-trimmed. Extracted from readProvisionTail (server.js) so the aggregation
+// is unit-tested and that function stays a thin filesystem-boundary call. Returns
+// '' for empty/whitespace-only input.
+function lastNonEmptyLines(text, maxLines = 50) {
+  const lines = String(text || '')
+    .split('\n')
+    .map((l) => l.replace(/\s+$/, ''))
+    .filter((l) => l.length > 0)
+    .slice(-maxLines);
+  return lines.join('\n');
+}
+
+// Build a verdict, stamping `retryable` from the single-source-of-truth Set so it
+// can never drift from the category.
+function buildFailureVerdict(category, headline, recovery, extra) {
+  const out = { category, headline, recovery, retryable: ADD_FAILURE_RETRYABLE.has(category) };
+  if (extra && extra.files) out.files = extra.files;
+  return out;
+}
+
+// Classify a failed add from its transcript tail + exit code.
+//
+//   logTail   the last lines of the provision transcript (string; '' when the
+//             log was unreadable — must never throw)
+//   exitCode  the provision's exit code (number; used for signal-kill detection)
+//
+// Returns { category, headline, recovery, retryable, files? }.
+//
+// Detection is ORDER-SENSITIVE. The provision shell echoes cloud:up's tail, so a
+// drift / instance-vanished / container-stuck transcript ALSO contains the
+// generic `cloud:up FAILED (exit N)` line. Each specific (and every retryable)
+// signature is therefore tested BEFORE the generic cloud-up-failed signature, or
+// a retryable drift would misclassify as a non-retryable cloud:up failure and the
+// operator would lose the safe one-click recovery.
+function classifyAddFailure({ logTail, exitCode } = {}) {
+  const log = String(logTail || '');
+
+  // 1. preflight-drift — the streamed-script drift guard aborted BEFORE any
+  //    gcloud call, so nothing was provisioned. Retryable once the file is fixed.
+  //    We match the unambiguous abort header / verdict label, NOT the bare
+  //    `CODEYAM_SKIP_SCRIPT_DRIFT_CHECK` token: that token ALSO appears in the
+  //    "bypass active — skipping drift check" warning, so keying on it would
+  //    misclassify a bypass-active add that later failed for a real reason as a
+  //    (retryable!) drift — inviting an unsafe retry. The header below is printed
+  //    only on a genuine drift abort.
+  if (/Streamed scripts carry unreviewed local content/i.test(log)
+      || /UNCOMMITTED LOCAL EDITS/.test(log)) {
+    const files = extractDriftFiles(log);
+    const fileList = files.length ? files.join(', ') : 'the streamed scripts';
+    const fix = files.length
+      ? `Commit & push them, or discard with \`git checkout -- ${files.join(' ')}\`, then Retry add.`
+      : 'Commit & push them, or discard the local edits, then Retry add.';
+    return buildFailureVerdict('preflight-drift', 'Blocked by local edits',
+      `Uncommitted local edits in ${fileList} tripped the streamed-script drift guard, which aborts before any cloud resource is created. ${fix}`,
+      { files });
+  }
+
+  // 2. instance-vanished — the GCP instance is confirmed gone; nothing to orphan.
+  if (/instance .* is gone/i.test(log)) {
+    return buildFailureVerdict('instance-vanished', 'Instance never came up',
+      'The GCP instance is gone — provisioning failed before the container started, so nothing was left behind. Retrying the add is safe.');
+  }
+
+  // 3. container-stuck — the instance exists but the editor container never
+  //    became healthy, so a half-provisioned box may exist. Not retryable.
+  if (/container never came up/i.test(log)) {
+    return buildFailureVerdict('container-stuck', 'Container never became healthy',
+      'The instance came up but the editor container never became healthy — it may be half-provisioned. Reconcile or destroy this VM before re-adding.');
+  }
+
+  // 4. cloud-up-failed — a generic cloud:up failure, reached ONLY when the drift /
+  //    vanished / stuck signatures above did not match. A partial instance may
+  //    exist, so not retryable.
+  if (/cloud:up FAILED \(exit/i.test(log)) {
+    return buildFailureVerdict('cloud-up-failed', 'Provisioning failed',
+      'cloud:up failed during provisioning, so a partial instance may exist. Reconcile or destroy this VM before re-adding.');
+  }
+
+  // 5. interrupted — a signal kill (OOM 137, SIGTERM 143, …) or an explicit
+  //    Killed / out-of-memory marker. The real VM state is unknown. Not retryable.
+  if (fc.isSignalKillExit(Number(exitCode)) || /\bKilled\b/.test(log) || /Out of memory/i.test(log)) {
+    return buildFailureVerdict('interrupted', 'Provisioning interrupted',
+      'The provision was interrupted (killed or out of memory), so the VM state is unknown. Reconcile or destroy this VM before re-adding.');
+  }
+
+  // 6. unknown — fallback. Never invite an unproven retry.
+  return buildFailureVerdict('unknown', 'Add failed',
+    'The add failed for an unclassified reason — inspect the transcript below, then reconcile or destroy this VM before re-adding.');
+}
+
+// Pure guard for the operator "Retry add" action: given a VM number and its
+// carried job, decide whether a one-click retry is SAFE. Retry is allowed ONLY
+// for a terminal add-error whose classifier verdict is retryable (a category
+// where nothing was provisioned). Returns { ok, reason } — reason is a stable
+// code the server shell (actionRetryAdd) maps to an operator message. Mirrors
+// fleet-job-badge.js::canClearBadge so the handler stays a thin I/O shell and the
+// safety decision is unit-tested without a live dashboard.
+function canRetryAdd({ n, job } = {}) {
+  if (!Number.isInteger(n) || n < 1) return { ok: false, reason: 'invalid-vm' };
+  if (!job || job.action !== 'add' || job.state !== 'error') return { ok: false, reason: 'no-failed-add' };
+  if (!job.retryable) return { ok: false, reason: 'not-retryable' };
+  return { ok: true, reason: null };
+}
+
+module.exports = { classifyAddFailure, extractDriftFiles, lastNonEmptyLines, canRetryAdd, ADD_FAILURE_RETRYABLE };

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-plans.js

@@ -33,6 +33,32 @@ function indexVmsBySessionId(vms) {
   return map;
 }
 
+/**
+ * Indexes the reachable VMs by their fleet machine name, so a claim that only
+ * carries `claimedBy.machine` (and no resolvable sessionId) can still attribute
+ * to a VM. A VM's machine name is `<instancePrefix><n>` (the GCE instance name
+ * the editor stamps into CODEYAM_MACHINE), so the map is derived, not probed.
+ *
+ * This is the fallback for backend/HTTP-"Run" claims: the editor stamps
+ * `claimedBy.sessionId` only for a PTY-attached `plan-select`, so a
+ * server-driven autonomous claim has an empty sessionId and never resolves via
+ * {@link indexVmsBySessionId}. Its machine name always resolves.
+ * @param {Array|Object} vms The merged VM states on the dashboard.
+ * @param {string} instancePrefix The fleet instance-name prefix (INSTANCE_PREFIX).
+ * @returns {Object} A map of machine name -> VM number (n).
+ */
+function indexVmsByMachine(vms, instancePrefix) {
+  const map = {};
+  if (!vms || !instancePrefix) return map;
+  const list = Array.isArray(vms) ? vms : Object.values(vms);
+  for (const vm of list) {
+    if (vm && vm.n !== undefined) {
+      map[`${instancePrefix}${vm.n}`] = vm.n;
+    }
+  }
+  return map;
+}
+
 /**
  * Computes which dependencies are unsatisfied (i.e. not in the completedSlugs set).
  * @param {string[]} dependsOn Prerequisite slugs.
@@ -52,9 +78,11 @@ function unsatisfiedDeps(dependsOn, completedSlugs) {
  * @param {Object[]} params.claims Array of PlanClaim objects from /api/plan-claims.
  * @param {Set|string[]} params.completedSlugs Completed plan slugs.
  * @param {Object} params.vmsBySessionId Map of sessionId -> VM number.
+ * @param {Object} [params.vmsByMachine] Map of machine name -> VM number, the
+ *   fallback for backend claims whose sessionId is empty.
  * @returns {Object[]} Annotated plan rows.
  */
-function resolvePlanRows({ plans, claims, completedSlugs, vmsBySessionId }) {
+function resolvePlanRows({ plans, claims, completedSlugs, vmsBySessionId, vmsByMachine }) {
   const list = Array.isArray(plans) ? plans : [];
   const claimsList = Array.isArray(claims) ? claims : [];
 
@@ -76,8 +104,14 @@ function resolvePlanRows({ plans, claims, completedSlugs, vmsBySessionId }) {
     if (claim) {
       const claimedBy = claim.claimedBy || claim.claimed_by || {};
       const sessionId = claimedBy.sessionId || claimedBy.session_id || null;
-      const vm = (sessionId && vmsBySessionId && vmsBySessionId[sessionId] !== undefined) ? vmsBySessionId[sessionId] : null;
-      
+      // Prefer the authoritative live sessionId match; fall back to the claim's
+      // machine name (backend claims have an empty sessionId, so this is the
+      // only key that resolves them to a VM).
+      let vm = (sessionId && vmsBySessionId && vmsBySessionId[sessionId] !== undefined) ? vmsBySessionId[sessionId] : null;
+      if (vm === null && claimedBy.machine && vmsByMachine && vmsByMachine[claimedBy.machine] !== undefined) {
+        vm = vmsByMachine[claimedBy.machine];
+      }
+
       claimInfo = {
         vm,
         machine: claimedBy.machine || null,
@@ -236,6 +270,7 @@ function parsePlansSnapshotStdout(stdout) {
 
 module.exports = {
   indexVmsBySessionId,
+  indexVmsByMachine,
   unsatisfiedDeps,
   resolvePlanRows,
   planSourceForProject,