@codeyam-editor/codeyam-editor 0.1.16-staging.ge120017 → 0.1.17-staging.gdcd54cf

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 CodeYam
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,72 @@
+# CodeYam Editor
+
+A step-driven AI build editor with an isolated Live Preview, scenario capture, verification commands, and a Rust control API.
+
+CodeYam Editor runs beside your project and drives an AI build agent through a planned, step-by-step workflow. Every feature is built together with the *scenarios* (the data states) that demonstrate it, shown in a live preview as you go and captured so they can be re-verified later. It works with any stack: web apps, backend services, CLIs, libraries.
+
+## Install
+
+**Recommended: the one-line installer.** It installs through npm and puts `codeyam-editor` on your `PATH`:
+
+```bash
+curl -fsSL https://codeyam.com/install.sh | sh
+```
+
+It checks the prerequisites (Node 20 or newer, and on Linux a recent enough glibc), runs the global npm install, and adds npm's global `bin` directory to your shell profile, so a new shell finds `codeyam-editor`. It prints exactly what it changed.
+
+**Plain npm** (you manage `PATH` yourself):
+
+```bash
+npm install -g @codeyam-editor/codeyam-editor
+```
+
+> If you use a custom npm prefix (for example `npm config set prefix ~/.npm-global` to avoid `sudo`), add its `bin` directory to `PATH` yourself. Otherwise the install succeeds but the shell reports `codeyam-editor: command not found`. The one-line installer does this for you.
+
+**No install: a one-off run** through npx:
+
+```bash
+npx @codeyam-editor/codeyam-editor
+```
+
+## Requirements
+
+- Node.js 20 or newer.
+- One of the supported platforms. npm installs the matching native binary automatically:
+  - macOS on Apple silicon (arm64) or Intel (x64)
+  - Linux x64 with glibc 2.28 or newer: Ubuntu 20.04+, Debian 10+, RHEL/Rocky/Alma 8+, Fedora 29+, Amazon Linux 2023. Older distros such as CentOS 7 and Amazon Linux 2 are not supported.
+  - Windows x64
+- Playwright's Chromium, for scenario screenshots: `npx playwright install chromium`.
+
+## Quick start
+
+In your project directory:
+
+```bash
+codeyam-editor init     # write .codeyam/editor.json
+codeyam-editor start    # start the editor and open it in your browser
+```
+
+`start` prints the editor's local URL and opens it. Pass `--no-open` to skip the browser, or `--port <PORT>` to pick the port. `init --provider <claude|codex|gemini|opencode>` chooses the build agent (Claude by default).
+
+## Commands
+
+| Command | What it does |
+|---|---|
+| `codeyam-editor start` | Start the editor (control API and your app's process). |
+| `codeyam-editor init` | Initialize a new `.codeyam/editor.json` config. |
+| `codeyam-editor mcp` | Run an MCP (Model Context Protocol) server over stdio, for Claude Desktop and other MCP clients. |
+| `codeyam-editor editor` | The workflow subcommands the build agent uses: scenarios, glossary, audit, and more. |
+
+Run `codeyam-editor <command> --help` for a command's options, and `codeyam-editor editor --help` for the full list of workflow subcommands.
+
+## Use with Claude
+
+The editor works with Claude Code out of the box: `codeyam-editor init` sets up the project for it. For Claude Desktop or any other MCP client, register `codeyam-editor mcp` as a stdio MCP server. See [codeyam.com](https://codeyam.com/) for the other ways to install it in Claude.
+
+## Links
+
+- Homepage: <https://codeyam.com/>
+
+## License
+
+MIT. See `LICENSE`.

package/npm/disk-pressure.js

@@ -55,10 +55,11 @@ const PRUNABLE_CACHE_DIRS = [
 // keyed on this known mount path, NOT folded into the generic allowlist, so a
 // client project's own Rust target/ is never touched.
 //
-// Stack assumption: only self-host VMs that run cargo write to this volume;
-// guest/client VMs (Next.js, Vite, Tauri, Python, …) carry an empty or absent
-// volume, so cargoTargetReclaimPlan returns an empty plan there (a guaranteed
-// no-op — honoring the stack-agnosticism rule in CLAUDE.md).
+// Stack assumption: every cargo build in the container writes to this volume —
+// the editor's own on a self-host VM, and a Rust client project's on a client
+// VM (60+ GB on the rapid-cad VMs, 2026-10-23). A VM whose project never runs
+// cargo (Next.js, Vite, Python, …) carries an empty or absent volume, so
+// cargoTargetReclaimPlan prunes nothing inside it there.
 const CARGO_TARGET_DIR = '/codeyam-build-target';
 
 // Sub-dirs of CARGO_TARGET_DIR that are ALWAYS safe to delete: pure coverage
@@ -73,33 +74,59 @@ const CARGO_TARGET_ALWAYS_PRUNE = ['llvm-cov-target'];
 // in-flight compile to free space — the failure mode this tiering avoids).
 const CARGO_TARGET_CRITICAL_CLEAN = ['debug'];
 
+// Targeted tiers, in the order the guard runs them, at WARN and CRITICAL alike
+// and regardless of buildInFlight: each removes only state no build will read
+// again (scripts/cloud-disk-guard.sh::reclaim_targeted_tiers). Before them WARN
+// freed nothing and CRITICAL could only wipe debug/ whole, so long-running Rust
+// client VMs drifted to 100% and every reclaim cost a cold rebuild.
+//   - stale-incremental: superseded `incremental/<crate>-<hash>/s-*` state under
+//     every profile and target triple of CARGO_TARGET_DIR (needs the volume)
+//   - orphan-workspace-target: a project-local target/ while CARGO_TARGET_DIR
+//     points elsewhere
+//   - idle-base-run-targets: test-on-base scratch caches no live run holds
+//   - idle-scratch-targets: cargo targets left in agent scratch space
+// The last three live outside the volume, so they apply on any VM.
+const CARGO_TARGETED_TIERS = [
+  'stale-incremental',
+  'orphan-workspace-target',
+  'idle-base-run-targets',
+  'idle-scratch-targets',
+];
+const TIERS_NEEDING_CARGO_TARGET = ['stale-incremental'];
+
 // Pure decision function for tiered cargo-target reclamation. Given the current
 // pressure `level`, whether a build is in flight, and whether this VM actually
-// has the cargo-target volume, return which sub-dirs to prune and whether the
-// heavy `debug` clean was deferred (so the caller can log it — no silent cap).
+// has the cargo-target volume, return the targeted tiers to run, which sub-dirs
+// to prune, and whether the heavy `debug` clean was deferred (so the caller can
+// log it — no silent cap).
 //
 // Tiers (mirrored by the bash guard + watchdog):
-//   - no cargo-target (guest/client VM)      → prune nothing (total no-op)
+//   - warn / critical                        → targeted tiers first, always
+//   - no cargo-target (guest/client VM)      → prune nothing in the volume
 //   - warn                                   → ALWAYS_PRUNE only (llvm-cov)
 //   - critical & idle                        → ALWAYS_PRUNE + CRITICAL_CLEAN
 //   - critical & build in flight             → ALWAYS_PRUNE only, defer heavy
-//   - ok / unknown level                     → fail-safe: prune nothing
+//   - ok / unknown level                     → fail-safe: run nothing
 function cargoTargetReclaimPlan({ level, buildInFlight, hasCargoTarget } = {}) {
-  if (!hasCargoTarget) return { prune: [], deferredHeavyClean: false };
+  if (level !== 'warn' && level !== 'critical') {
+    // 'ok', undefined, or any unknown level → do nothing (fail safe).
+    return { targeted: [], prune: [], deferredHeavyClean: false };
+  }
+  const targeted = CARGO_TARGETED_TIERS.filter(
+    (tier) => hasCargoTarget || !TIERS_NEEDING_CARGO_TARGET.includes(tier)
+  );
+  if (!hasCargoTarget) return { targeted, prune: [], deferredHeavyClean: false };
   if (level === 'warn') {
-    return { prune: [...CARGO_TARGET_ALWAYS_PRUNE], deferredHeavyClean: false };
+    return { targeted, prune: [...CARGO_TARGET_ALWAYS_PRUNE], deferredHeavyClean: false };
   }
-  if (level === 'critical') {
-    if (buildInFlight) {
-      return { prune: [...CARGO_TARGET_ALWAYS_PRUNE], deferredHeavyClean: true };
-    }
-    return {
-      prune: [...CARGO_TARGET_ALWAYS_PRUNE, ...CARGO_TARGET_CRITICAL_CLEAN],
-      deferredHeavyClean: false,
-    };
+  if (buildInFlight) {
+    return { targeted, prune: [...CARGO_TARGET_ALWAYS_PRUNE], deferredHeavyClean: true };
   }
-  // 'ok', undefined, or any unknown level → do nothing (fail safe).
-  return { prune: [], deferredHeavyClean: false };
+  return {
+    targeted,
+    prune: [...CARGO_TARGET_ALWAYS_PRUNE, ...CARGO_TARGET_CRITICAL_CLEAN],
+    deferredHeavyClean: false,
+  };
 }
 
 // Classify an integer disk-usage percent into a pressure level. A non-numeric,
@@ -159,6 +186,7 @@ module.exports = {
   CARGO_TARGET_DIR,
   CARGO_TARGET_ALWAYS_PRUNE,
   CARGO_TARGET_CRITICAL_CLEAN,
+  CARGO_TARGETED_TIERS,
   cargoTargetReclaimPlan,
   classifyDiskPressure,
   parseDfUsedPct,

package/npm/fleet-add-vm-steps.js

@@ -0,0 +1,210 @@
+'use strict';
+
+const lc = require('./launch-config');
+const fa = require('./fleet-auth');
+const fer = require('./fleet-early-roster');
+
+// npm/fleet-add-vm-steps.js — what an Add (fleet-dashboard server.js `addVm`)
+// runs, and in what order, decided before anything is spawned.
+//
+// addVm keeps every side effect: the pending-job sidecar, the exit-marker
+// clear, startJob and the roster writes. These two steps only DECIDE:
+//
+//   resolveAddCreds   — which reachable VM donates claude/git credentials (or
+//                       which donor-less fallback applies) and the seeding
+//                       shell steps that follow from it;
+//   buildAddVmScript  — the provision script itself: cloud:up, the container
+//                       gate, the early-roster marker, creds, tunnels and the
+//                       awaited ingress wiring, as one newline-joined string.
+//
+// The server's constants arrive under their server names, and `shq` is the
+// server's single-quote shell escaper, so both read as they did inline.
+
+// `vms` is the server's state.vms; `requestedAccount` is the account the add
+// should seed (a per-add override, else the fleet's chosen one), already
+// resolved by the server because choosing it reads the dashboard's settings.
+function resolveAddCreds({
+  n, VMS, vms, requestedAccount, inst, INSTANCE_PREFIX, CLAUDE_CREDS_SRC, GITHUB_TOKEN,
+  CONTAINER, GCLOUD, ZONE, shq,
+}) {
+  // Creds source: prefer a *reachable* donor (a VM that actually answered the
+  // last poll — VMS[0] may be a destroyed-but-still-rostered orphan, #24), else
+  // fall back to the operator-configured CLAUDE_CREDS_SRC / GITHUB_TOKEN. A full
+  // teardown empties VMS, so there's no donor at all — the fallback is what lets
+  // "destroy all → Add count=N" produce a working fleet numbered 1-N (improve34).
+  // A reachable donor whose credential failed the integrity probe is dropped
+  // HERE, before resolveCredsSource's first-donor fallback could pick it: the
+  // copy sink would refuse its credential only after the add had committed to
+  // it (VM-11 → VM-2, 2026-09-17). Each dropped donor is named in the add log.
+  const donorSplit = fa.partitionDonorsByIntegrity(
+    VMS.filter((x) => x !== n && vms[x] && vms[x].reachable),
+    vms,
+  );
+  const reachableDonors = donorSplit.usable;
+  // The donor is the reachable VM holding the requested account, so the account
+  // the Add dialog showed is the account actually seeded. When no reachable VM
+  // holds it, fall back to the usual donor and raise a CY_DEGRADED reason naming
+  // both (credsSteps below).
+  const preferredDonor = fa.selectDonorForAccount(reachableDonors, vms, requestedAccount);
+  const creds = lc.resolveCredsSource({
+    reachableDonors,
+    preferredDonor,
+    requestedAccount,
+    claudeCredsSrc: CLAUDE_CREDS_SRC,
+    githubToken: GITHUB_TOKEN,
+  });
+  const refInst = creds.donor != null ? INSTANCE_PREFIX + creds.donor : null;   // claude/git source when present
+  const donorAuth = creds.donor != null && vms[creds.donor] && vms[creds.donor].providerAuth;
+  const seededAccount = (donorAuth && donorAuth.account && donorAuth.account.email) || '';
+  // Build the creds-seeding steps for the resolved mode. The "donor" path is the
+  // unchanged default (container→container claude + host-file git from a live
+  // VM); host-stash / token / none are the donor-less fallback. `add-degraded`
+  // (modes token/none — no claude auth source) is flagged after startJob below.
+  // The shell-string builder lives in npm/launch-config.js so it's unit-testable
+  // (see launch-config.test.js::buildCredsSteps).
+  const credsSteps = lc.buildCredsSteps({
+    mode: creds.mode,
+    refInst,
+    inst,
+    container: CONTAINER,
+    gcloud: GCLOUD,
+    zone: ZONE,
+    n,
+    claudeCredsSrc: CLAUDE_CREDS_SRC,
+    account: seededAccount,
+  });
+  // Fall back loudly, never silently: the operator asked for an account no
+  // reachable VM holds, so say which account was requested and what was seeded.
+  if (creds.requestedAccountUnavailable) {
+    const reason = lc.accountFallbackMessage({
+      requested: requestedAccount,
+      seeded: seededAccount,
+      mode: creds.mode,
+      donor: creds.donor,
+      inst,
+    });
+    credsSteps.unshift(`echo ${shq(reason)}`);
+  }
+  credsSteps.unshift(...donorSplit.skipped.map((d) => lc.donorSkippedLine(d)));
+  return { creds, credsSteps };
+}
+
+// The provision script startJob runs for an add. `exitMarker` / `exitMarkerTmp`
+// are the durable add-<n>.exit paths, which the server clears before calling.
+function buildAddVmScript(opts) {
+  const {
+    n, cfg, inst, port, previewPort, appPort, upArgs, proj, tunnelCmd, credsSteps,
+    exitMarker, exitMarkerTmp, resolveProjectName, REPO_ROOT, GCLOUD, ZONE, CONTAINER,
+    WIRING_AWAIT_SEC, GIT_RESEED_BODY, shq,
+  } = opts;
+  // Make git creds live in the running container. Both the donor host-file copy
+  // and cloud:up's token write land on the read-only STAGING mount but DON'T
+  // touch the in-memory `cache` daemon (seeded from the empty placeholder at
+  // container boot) — so git auth stays inert until re-seeded. Mirror the
+  // entrypoint seed (scripts/cloud-editor-entrypoint.sh) live; base64-framed so
+  // the multi-line snippet survives the gcloud-ssh + docker-exec quoting layers.
+  // `-s` self-skips when STAGING is still the empty placeholder (mode none).
+  const gitReseedB64 = Buffer.from(GIT_RESEED_BODY, 'utf8').toString('base64');
+  const gitReseedStep = `echo ${gitReseedB64} | ${GCLOUD} compute ssh ${inst} --tunnel-through-iap --zone=${ZONE} --command='docker exec -i ${CONTAINER} bash -c "base64 -d | bash"' 2>/dev/null || echo "WARN git cache re-seed exec failed"`;
+  const script = [
+    `CY_ADD_EXIT_MARKER=${shq(exitMarker)}`,
+    `CY_ADD_EXIT_MARKER_TMP=${shq(exitMarkerTmp)}`,
+    `trap 'cy_code=$?; printf "%s\\n%s\\n" "$cy_code" "$(date -u +%Y-%m-%dT%H:%M:%SZ)" > "$CY_ADD_EXIT_MARKER_TMP" 2>/dev/null && mv -f "$CY_ADD_EXIT_MARKER_TMP" "$CY_ADD_EXIT_MARKER" 2>/dev/null; exit $cy_code' EXIT`,
+    `cd ${shq(REPO_ROOT)}`,
+    `echo "provisioning ${inst} — GCP project ${resolveProjectName()} — project ${proj}, editor ${cfg.editorVariant}${cfg.editorBranch ? '@' + cfg.editorBranch : ''} (cloud:up — image build can take ~15-25 min under fleet load)..."`,
+    // Background cloud:up so we can poll the container on our own cadence while
+    // the image build runs (~15-25 min). Under --no-tunnel it exits cleanly the
+    // instant the container is up — the wait below treats that exit as normal.
+    `npm run cloud:up -- ${upArgs} > /tmp/dash-add-vm-${n}.log 2>&1 &`,
+    `UP_PID=$!`,
+    // Wait up to ~28 min of real time for the editor container — the cold image
+    // build is the long pole and gets slower as the fleet grows. The gate (pure,
+    // tested: lc.containerGateCmd) treats ANY single `Up` as terminal success
+    // (mirrors lc.classifyContainerWait); a clean cloud:up exit is the NORMAL
+    // --no-tunnel success path (fragility #33) while a NON-ZERO exit fails fast
+    // after one re-check; a transient gcloud-ssh blip is retried; and failure
+    // past the deadline tells a vanished instance from a stuck build, then reaps
+    // the `node cloud.js up` grandchild $UP_PID doesn't cover (anchored at
+    // `node`, so it can't match THIS script's own `sh -c` wrapper).
+    //
+    // It probes on a WIDENING cadence (10s → 30s → 60s), not every 10s: each
+    // probe is a `gcloud compute ssh`, i.e. an oslogin read against the
+    // fleet-wide 60/min per-user quota, and the flat 10s loop spent 6/min per
+    // in-flight add on that question alone — invisible to hostOpLimiter, which
+    // only sees the dashboard's own calls. A quota refusal on a probe prints a
+    // CY_API_QUOTA line startJob's output tap journals.
+    lc.containerGateCmd({ gcloud: GCLOUD, inst, zone: ZONE, probeCmd: tunnelCmd, logPath: `/tmp/dash-add-vm-${n}.log` }),
+    // Container gate passed: the instance exists and the editor container is Up.
+    // Announce it so the dashboard rosters this VM NOW rather than waiting for
+    // the whole script to exit 0. Rostering here is what breaks the deadlock
+    // that stranded VM-4..7 on 2026-07-20: everything below (creds, tunnels, the
+    // awaited LB wiring) can still fail, but a rostered VM stays VISIBLE to
+    // `reconcile-ingress`, which skips unrostered numbers — so the periodic
+    // sweep can finish the wiring instead of the VM becoming invisible and
+    // burning its bootstrap-recovery budget on a probe that can never pass
+    // without ingress. See npm/fleet-early-roster.js.
+    `echo ${shq(fer.rosterMarkerLine(n))}`,
+    // Container is up — but cloud:up is NOT done. wireVmIngressOnAdd runs as a
+    // TAIL step of cloud:up (the slow EXTERNAL_MANAGED backend-services create +
+    // NEG attach + url-map host-rule), AFTER the container gate. The old code
+    // reaped cloud:up here (`kill $UP_PID`) 15s after the container was Up, on the
+    // false premise that `--no-tunnel` had "already exited" — that SIGTERM'd
+    // `backend-services create` mid-flight and stranded the VM backendless at 503
+    // until the self-heal sweep recovered it. So DON'T kill cloud:up here: just
+    // settle for in-flight seeds + sweep any stray :14199 tunnel before we open
+    // ours. The wiring is AWAITED (lc.awaitWiringCmd) at the end of the script,
+    // after the creds/tunnel steps — which don't depend on it — have run.
+    // The sweep is anchored at the ssh executable (lc.editorForwardSweepCmd).
+    // Bare, `pkill -f "14199:127.0.0.1:14199"` matched this script's OWN
+    // `sh -c '<add script>'` wrapper — the script text contains this line — and
+    // every concurrent sibling add wrapper, SIGTERMing them 15s after the
+    // container gate passed. That killed the EXIT trap that writes
+    // add-<n>.exit, orphaned the detached cloud:up, and painted a red
+    // "Add failed" on healthy VMs (2026-07-31, VM-3..8).
+    `sleep 15; ${lc.editorForwardSweepCmd({ localPort: 14199 })}`,
+    // Seed claude + git auth: donor copy (default) or the donor-less fallback.
+    ...credsSteps,
+    // Activate git creds in the running container (host-file/STAGING write alone
+    // is inert against the booted cache daemon).
+    gitReseedStep,
+    // open the localhost tunnels (nohup; watchdog maintains them) as TWO
+    // INDEPENDENT ssh processes: the editor reachability forward (14299+N ->
+    // VM:14199) and a sibling Live Preview forward (15172+N -> VM:<appPort>)
+    // that the cloudflared-monitor fronts with a public "<N>-preview" tunnel.
+    // Splitting them is load-bearing — a preview-port re-wire then restarts ONLY
+    // the preview process, so the editor :14199 forward (the dashboard's
+    // reachability signal) stays up and the probe can't blip a false
+    // "unreachable". Separate log files keep each tunnel independently inspectable.
+    lc.editorTunnelCmd({ gcloud: GCLOUD, inst, zone: ZONE, editorPort: port, n }),
+    lc.previewTunnelCmd({ gcloud: GCLOUD, inst, zone: ZONE, previewPort, appPort, n }),
+    // Tell the editor's process-global provider-auth cache to forget the
+    // cold-boot probe's NeedsLogin verdict now that credsSteps has dropped a
+    // fresh .credentials.json onto the VM's /root/.claude/. Without this hop,
+    // /api/config keeps serving needs-login (UI shows ProviderAuthGate, Build
+    // tab locked) until the editor server is restarted — even though the
+    // creds are valid. Fail-soft: a few retries cover the nohup tunnel still
+    // settling; the manual restart-server workaround remains the fallback.
+    `echo "invalidating providerAuth cache on VM-${n}..."`,
+    `for i in 1 2 3 4 5; do if curl -sS -m 3 -X POST http://localhost:${port}/api/auth/refresh-cache >/dev/null 2>&1; then echo "providerAuth cache invalidated on VM-${n}"; break; fi; sleep 2; if [ "$i" = "5" ]; then echo "WARN providerAuth cache refresh failed on VM-${n} — restart editor if Build tab shows Connect"; fi; done`,
+    // Await cloud:up's slow wiring tail (started AFTER the container gate) rather
+    // than reaping it the instant the container was Up — the mid-`backend-services
+    // create` SIGTERM is the add-time 503 strand this closes. Waits for cloud:up to
+    // exit on its own (wiring done, success OR loud-fail) up to WIRING_AWAIT_SEC,
+    // force-reaping only past the deadline (the dashboard self-heal is the backstop).
+    // Placed here, after the creds/tunnel steps that don't depend on wiring, so the
+    // CY_DEGRADED grep below reads the FINAL wiring outcome — not a mid-flight log.
+    lc.awaitWiringCmd({ inst, deadlineSec: WIRING_AWAIT_SEC }),
+    // Republish any CY_DEGRADED marker cloud:up emitted (LB ingress wiring failed
+    // — the VM7-10 case) from its private log onto THIS job's stdout, where the
+    // completion scanner (finish()) reads markers from `buf`. Without this hop the
+    // marker stays buried in /tmp/dash-add-vm-N.log and the card never goes amber.
+    `grep -h '^CY_DEGRADED ' /tmp/dash-add-vm-${n}.log 2>/dev/null || true`,
+    // "+ wired" must be EARNED, not asserted: the unwired-but-green VM7-10 log
+    // came from claiming "+ wired" unconditionally here. State the provisioned
+    // fact only; the ingress-not-wired marker above carries the wiring state.
+    `echo "VM-${n} provisioned on localhost:${port} (preview localhost:${previewPort})"`,
+  ].join('\n');
+  return script;
+}
+
+module.exports = { resolveAddCreds, buildAddVmScript };

package/npm/fleet-build-data.js

@@ -158,7 +158,15 @@ function buildVmEnvelope(v, ctx) {
     // decides manually whether to release it).
     headHolderUnreachable: !!ctx.headHolderUnreachable,
     queuePos: ctx.queuePos != null ? ctx.queuePos : null,
-    queueLen: ctx.queueLen,
+    // The fleet queue's length when this VM is in it, else its own branch
+    // queue's length, else null (npm/fleet-stuck-position.js::resolveQueueLen).
+    queueLen: ctx.queueLen != null ? ctx.queueLen : null,
+    // This VM's OWN branch commit queue, read from its /api/branch-queue/status:
+    // { branch, position, length, inQueue, holdsHead, blocked, headMachine,
+    // headSuspect }, or null when the VM did not answer. Distinct from
+    // queuePos/isHead, which describe the fleet's pinned-branch queue only, so a
+    // VM on a client branch can say "position 4 of 5 on rapid-cad-7".
+    branchQueue: v.branchQueue || null,
     job: ctx.job || null,
     config: ctx.config || null,
     project: ctx.project != null ? ctx.project : null,
@@ -193,7 +201,7 @@ function buildVmEnvelope(v, ctx) {
     startedAt: v.startedAt || null,
     featureStartedAt: v.featureStartedAt || null,
     // The server-computed stuck / needs-you verdict (npm/fleet-stuck-status.js):
-    // { stepElapsedMs, level: 'ok'|'slow'|'stuck', needsYou, needsYouElapsedMs }.
+    // { stepElapsedMs, level: 'ok'|'slow'|'stuck'|'queued', needsYou, needsYouElapsedMs }.
     // The authoritative level only changes on poll; the card colors the step
     // tenure badge by it. null when buildData couldn't compute one.
     attention: ctx.attention || null,
@@ -240,7 +248,7 @@ const REQUIRED_CARD_FIELDS = [
   'sessionIdleSeconds', 'sessionActivity', 'sessionWedged', 'brokerLive', 'brokerStatus',
   'awaitingInput', 'needsCleanup', 'feature', 'selectedPlan', 'step', 'mode', 'label', 'cycleClosed', 'status', 'orphan',
   'degradedReasons', 'setupSteps', 'attentionReasons',
-  'isHead', 'headHolderUnreachable', 'queuePos', 'queueLen',
+  'isHead', 'headHolderUnreachable', 'queuePos', 'queueLen', 'branchQueue',
   'job', 'config', 'project', 'variant', 'cardIdentity', 'brokerHistory',
   'brokerDeath', 'providerAuth', 'previewMisconfigured', 'previewEndpoint', 'datastore', 'effects', 'currentProvider',
   'readiness', 'backendHealth', 'vmAccess',