@codeyam-editor/codeyam-editor 0.1.3 → 0.1.4

package/npm/fleet-build-data.js

@@ -0,0 +1,81 @@
+'use strict';
+
+// Assemble the per-VM wire object the dashboard's /data response carries to the
+// browser. This is the single source of truth for a card's transport shape: the
+// card UI (scripts/operator/fleet-dashboard/public/index.html) reads `v.<field>`
+// off each entry, so every field the card renders MUST be emitted here.
+//
+// It was split out of server.js's buildData() so the shape is unit-testable.
+// The regression that motivated the split: `currentProvider` (the VM's
+// configured build agent) was merged onto the poll state AND read by the card to
+// render the 🤖 agent badge, but it was silently missing from this envelope — so
+// it lived in server memory and never reached the browser, and the badge never
+// appeared. A hand-maintained object literal inside a 197KB monolith has no
+// guard against that drift; a pure function does.
+//
+// `v` is the merged poll state (state.vms[n]). `ctx` carries the derived,
+// cross-VM, and side-effecting values buildData computes per VM (status,
+// debounced broker tri-state, reconciled job, queue position, launch cfg, …) —
+// the things this pure function can't know on its own.
+function buildVmEnvelope(v, ctx) {
+  return {
+    n: ctx.n,
+    url: v.url || null,
+    reachable: !!v.reachable,
+    hasSession: !!v.hasSession,
+    // Three-state: true = broker confirmed up, false = confirmed down, null =
+    // editor unreachable so broker state is unknown. Never conflate "down" with
+    // "unreachable" — that mismatch is what made the card show "broker down"
+    // while a direct pgrep proved the broker was up.
+    brokerLive: v.reachable ? !!v.agentBrokerLive : null,
+    // Broker tri-state: 'down' | 'idle' | 'agent-live' | 'unknown' (derived
+    // upstream, debounced). Richer than brokerLive's is-an-agent-live boolean.
+    brokerStatus: ctx.brokerStatus,
+    awaitingInput: !!v.awaitingUserInput,
+    feature: v.feature || null,
+    step: v.step != null ? v.step : null,
+    mode: v.mode || null,
+    label: v.label || null,
+    status: ctx.status,
+    orphan: ctx.orphan || null,
+    degradedReasons: ctx.degradedReasons || [],
+    isHead: !!ctx.isHead,
+    // True when this VM holds the queue head but is unreachable (operator
+    // decides manually whether to release it).
+    headHolderUnreachable: !!ctx.headHolderUnreachable,
+    queuePos: ctx.queuePos != null ? ctx.queuePos : null,
+    queueLen: ctx.queueLen,
+    job: ctx.job || null,
+    config: ctx.config || null,
+    project: ctx.project != null ? ctx.project : null,
+    variant: ctx.variant != null ? ctx.variant : null,
+    cardIdentity: ctx.cardIdentity,
+    brokerHistory: Array.isArray(v.brokerHistory) ? v.brokerHistory : [],
+    brokerDeath: ctx.brokerDeath,
+    // Auth state + reason + token expiry. Only surfaced when the editor is
+    // reachable (an unreachable VM's cached auth is stale and misleading).
+    providerAuth: v.reachable && v.providerAuth ? v.providerAuth : null,
+    effects: v.effects || null,
+    // The VM's live-configured build agent (lowercase provider), reported by
+    // /api/session-info and merged (sticky) onto the poll state. Drives the
+    // card's 🤖 agent badge. null for an older VM whose editor predates the
+    // field (the card omits the badge rather than rendering a blank chip).
+    currentProvider: v.currentProvider || null,
+  };
+}
+
+// The fields the card UI depends on being present in every /data VM entry. This
+// is the contract `buildVmEnvelope` must satisfy: the regression that prompted
+// this module was a field the card read but the envelope didn't emit, so the
+// test asserts the envelope keys are a superset of this list. Adding a field the
+// card renders means adding it here AND in buildVmEnvelope — the test fails loud
+// if you do one without the other.
+const REQUIRED_CARD_FIELDS = [
+  'n', 'url', 'reachable', 'hasSession', 'brokerLive', 'brokerStatus',
+  'awaitingInput', 'feature', 'step', 'mode', 'label', 'status', 'orphan',
+  'degradedReasons', 'isHead', 'headHolderUnreachable', 'queuePos', 'queueLen',
+  'job', 'config', 'project', 'variant', 'cardIdentity', 'brokerHistory',
+  'brokerDeath', 'providerAuth', 'effects', 'currentProvider',
+];
+
+module.exports = { buildVmEnvelope, REQUIRED_CARD_FIELDS };

package/npm/fleet-cleanup.js

@@ -206,6 +206,32 @@ function reattachVerdict({ markerPresent, exitCode, childAlive } = {}) {
   return 'reconcile';
 }
 
+// improve45 — map a reattachVerdict tag to the dashboard's NEXT action, now that
+// a clean exit marker is NECESSARY BUT NOT SUFFICIENT to roster. A detached
+// `cloud:up` can exit 0 AFTER the image build but BEFORE `docker compose up`
+// ever runs — an ssh broken-pipe or dashboard SIGKILL landing in that window,
+// with the wrapping EXIT trap still recording 0 (the live VM2 signature: built
+// image, repo cloned, ZERO editor containers). So 'done' no longer means "roster
+// it"; it means "confirm the container is actually up first." Both the clean-exit
+// ('done') and the no-usable-marker ('reconcile') cases therefore route through
+// the SAME gcloud container + wiring probe (reconcileViaGcloud → fc.reapVerdict),
+// which rosters only a genuinely-up + wired add and routes a half-provisioned one
+// to recover-bootstrap. 'error' (real non-zero exit) and 'running' (child still
+// alive) are unchanged. reattachVerdict stays the honest classifier of the
+// child's exit SIGNAL; this helper expresses how that signal is CONSUMED now that
+// exit-0 no longer implies rostering. Pure: server.js maps the returned action to
+// its side-effecting step, so the matrix is exhaustively testable without a VM.
+//   verdict       next step         meaning
+//   'done'        'probe'           confirm the container before rostering
+//   'reconcile'   'probe'           no usable marker — let the gcloud probe decide
+//   'error'       'surface-error'   real failure — show add-failed with the code
+//   'running'     'watch'           child still alive — keep polling for the marker
+function reattachNextStep(verdict) {
+  if (verdict === 'error') return 'surface-error';
+  if (verdict === 'running') return 'watch';
+  return 'probe'; // 'done' and 'reconcile' both confirm via the gcloud probe
+}
+
 // Anti-loop budget for the `recover-bootstrap` path. Pure: given the count of
 // recoveries ALREADY persisted on the sidecar, return the next attempt number,
 // whether the reap should proceed (re-run cloud:up) or treat the VM as
@@ -294,4 +320,5 @@ module.exports = {
   readExitMarker,
   clearExitMarker,
   reattachVerdict,
+  reattachNextStep,
 };

package/npm/fleet-job-badge.js

@@ -36,4 +36,48 @@ function shouldReconcileFailedBadge({ job, reachable, drifted, offBranch, degrad
   return true;
 }
 
-module.exports = { shouldReconcileFailedBadge };
+// Given a reconcile verdict (from shouldReconcileFailedBadge) and whether the VM
+// is now idle, decide whether the recovered badge should be FULLY CLEARED — the
+// job entry dropped from state.jobs so the card goes clean — rather than merely
+// muted as a "recovered (was: …)" note (improve41).
+//
+//   badgeReconciled  the shouldReconcileFailedBadge verdict for this VM
+//   idle             the VM answered this poll, is not running a build session,
+//                    and its broker is not actively serving an agent
+//
+// A recovered VM that is also idle has demonstrably finished recovering, so the
+// stale error is dropped entirely. A recovered-but-not-yet-idle VM (mid-build,
+// or a poll hasn't confirmed idle) keeps the muted note so the prior log stays
+// visible during that transient window. Never clears a badge that wasn't first
+// judged recovered — an unreachable / drifted / off-branch error stays surfaced.
+function shouldClearReconciledBadge({ badgeReconciled, idle } = {}) {
+  return !!badgeReconciled && !!idle;
+}
+
+// Pure guard for the operator "Clear badge" action (improve41). Decides whether
+// VM-n's persisted job entry may be dropped after an out-of-band recovery,
+// independent of the server's state / fs I/O so the cases are unit-tested
+// without a live dashboard. The shell (server.js) supplies the live signals and
+// turns the verdict into the {ok,msg} response + the actual delete + snapshot.
+//
+//   rostered  the VM number is in the live roster
+//   job       the carried job record ({ state, ... }) or null/undefined
+//
+// Only a TERMINAL job (error/done) on a rostered VM may be cleared, OR a terminal
+// failed add (add/error) on a non-rostered VM (which deletes the card + add-N sidecar):
+// any other job state / non-rostered combination is not clearable.
+// Returns { ok, reason, cleanup } — reason is a stable code the shell maps to an
+// operator message, and cleanup is the cleanup action to perform ('add-failed' vs 'badge-only').
+function canClearBadge({ rostered, job } = {}) {
+  if (!rostered) {
+    if (job && job.action === 'add' && job.state === 'error') {
+      return { ok: true, reason: null, cleanup: 'add-failed' };
+    }
+    return { ok: false, reason: 'not-rostered' };
+  }
+  if (!job) return { ok: false, reason: 'no-badge' };
+  if (job.state !== 'error' && job.state !== 'done') return { ok: false, reason: 'job-active' };
+  return { ok: true, reason: null, cleanup: 'badge-only' };
+}
+
+module.exports = { shouldReconcileFailedBadge, shouldClearReconciledBadge, canClearBadge };

package/npm/fleet-plans.js

@@ -0,0 +1,96 @@
+'use strict';
+
+/**
+ * Indexes the currently-reachable VMs by their live sessionId.
+ * @param {Array|Object} vms The merged VM states on the dashboard.
+ * @returns {Object} A map of sessionId -> VM number (n).
+ */
+function indexVmsBySessionId(vms) {
+  const map = {};
+  if (!vms) return map;
+  const list = Array.isArray(vms) ? vms : Object.values(vms);
+  for (const vm of list) {
+    if (vm && vm.sessionId && vm.n !== undefined) {
+      map[vm.sessionId] = vm.n;
+    }
+  }
+  return map;
+}
+
+/**
+ * Computes which dependencies are unsatisfied (i.e. not in the completedSlugs set).
+ * @param {string[]} dependsOn Prerequisite slugs.
+ * @param {Set|string[]} completedSlugs Set or array of completed plan slugs.
+ * @returns {string[]} The unsatisfied dependency slugs.
+ */
+function unsatisfiedDeps(dependsOn, completedSlugs) {
+  const deps = Array.isArray(dependsOn) ? dependsOn : [];
+  const completedSet = completedSlugs instanceof Set ? completedSlugs : new Set(completedSlugs || []);
+  return deps.filter(dep => !completedSet.has(dep));
+}
+
+/**
+ * Resolves claims and dependency states for each queued plan.
+ * @param {Object} params
+ * @param {Object[]} params.plans Array of PlanSummary objects from /api/plans.
+ * @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.
+ * @returns {Object[]} Annotated plan rows.
+ */
+function resolvePlanRows({ plans, claims, completedSlugs, vmsBySessionId }) {
+  const list = Array.isArray(plans) ? plans : [];
+  const claimsList = Array.isArray(claims) ? claims : [];
+
+  return list.map(plan => {
+    // 1. Extract plan fields
+    const slug = plan.slug;
+    const title = plan.title;
+    const mode = plan.mode || null;
+    const order = plan.order != null ? plan.order : null;
+    const prefix = plan.prefix || null;
+
+    // 2. Resolve dependency-blocked state
+    const dependsOn = Array.isArray(plan.depends_on) ? plan.depends_on : (plan.dependsOn ? plan.dependsOn : []);
+    const blockedBy = unsatisfiedDeps(dependsOn, completedSlugs);
+
+    // 3. Resolve claim state
+    const claim = claimsList.find(c => c.slug === slug);
+    let claimInfo = null;
+    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;
+      
+      claimInfo = {
+        vm,
+        machine: claimedBy.machine || null,
+        agent: claimedBy.agentProvider || claimedBy.agent_provider || null,
+        sessionAlive: claim.sessionAlive !== undefined ? claim.sessionAlive : (claim.session_alive !== undefined ? claim.session_alive : null),
+        source: claim.source || null,
+        currentStep: claimedBy.currentStep || claimedBy.current_step || null,
+      };
+    }
+
+    return {
+      slug,
+      title,
+      mode,
+      order,
+      prefix,
+      blockedBy,
+      claim: claimInfo
+    };
+  });
+}
+
+const REQUIRED_PLAN_ROW_FIELDS = [
+  'slug', 'title', 'mode', 'order', 'prefix', 'blockedBy', 'claim'
+];
+
+module.exports = {
+  indexVmsBySessionId,
+  unsatisfiedDeps,
+  resolvePlanRows,
+  REQUIRED_PLAN_ROW_FIELDS
+};

package/npm/fleet-reconcile.js

@@ -33,4 +33,61 @@ function computeUnrostered(running, shown) {
     .sort((a, b) => a - b);
 }
 
-module.exports = { parseRunningFleetVms, computeUnrostered };
+// Map a single degraded reason to the live health signal that resolves it.
+// Returns true only when that signal now passes; a reason with no mapped signal
+// returns false (retained — a genuine config problem, never a false-green).
+// Start with the two observed classes (improve41); extend the table as new
+// degraded reasons gain a corresponding live signal.
+function reasonClearedByHealth(reason, { reachableServing, authed }) {
+  const r = String(reason || '');
+  if (/claude auth|claude\.json|login/i.test(r)) return authed;
+  if (/container|never came up|provisioning failed/i.test(r)) return reachableServing;
+  return false;
+}
+
+// Given a terminal add-job badge and the VM's live health, return the corrected
+// badge — or null when nothing changes. Conservative by construction: clears a
+// degraded reason only when its live health signal now passes; flips a bare
+// `error` add to `done` when the VM is reachable + serving; leaves any reason
+// with no health signal intact (no false-green). The poll loop supplies the live
+// facts (I/O at the edge) and applies the result; the verdict itself is pure.
+//   job:    { state: 'done'|'error', degraded, degradedReasons }
+//   health: { reachable, editorHttpOk, providerAuthState }
+//   → null | { state, degraded, degradedReasons, transition }
+function reconcileTerminalAddBadge({ job, health } = {}) {
+  if (!job || !health) return null;
+  const reachableServing = !!(health.reachable && health.editorHttpOk);
+  const authed = health.providerAuthState === 'authenticated';
+
+  // Bare `error` add (no degraded reasons): flip to `done` once the VM is
+  // reachable + serving — the VM3 case (a manual `cloud:up` recovered the editor
+  // outside the dashboard's view).
+  if (job.state === 'error') {
+    const reasons = job.degradedReasons || [];
+    if (reasons.length === 0 && reachableServing) {
+      return { state: 'done', degraded: false, degradedReasons: [], transition: 'error→done (editor 200)' };
+    }
+    return null;
+  }
+
+  // Terminal `done` that is degraded: clear each reason whose live signal now
+  // passes; retain the rest. Drop `degraded` only when no reasons remain.
+  if (job.state === 'done' && job.degraded) {
+    const reasons = job.degradedReasons || [];
+    const remaining = reasons.filter((reason) => !reasonClearedByHealth(reason, { reachableServing, authed }));
+    if (remaining.length === reasons.length) return null; // nothing cleared → no-op
+    const cleared = reasons.length - remaining.length;
+    return {
+      state: 'done',
+      degraded: remaining.length > 0,
+      degradedReasons: remaining,
+      transition: remaining.length > 0
+        ? `degraded: cleared ${cleared} reason(s), ${remaining.length} remain`
+        : 'degraded→clear (health restored)',
+    };
+  }
+
+  return null;
+}
+
+module.exports = { parseRunningFleetVms, computeUnrostered, reconcileTerminalAddBadge };

package/npm/launch-config.js

@@ -8,7 +8,14 @@
 // runs on a VM; the history is the cache that makes the last choice the default
 // and past launches one click to re-run.
 
-const { CANONICAL_EDITOR_REPO, EDITOR_VARIANTS, repoBasename } = require("./cloud");
+const { CANONICAL_EDITOR_REPO, EDITOR_VARIANTS, repoBasename, AGENT_ENV_VARS } = require("./cloud");
+
+/** The build agents a VM's editor terminal can run, as the keys of cloud.js's
+ *  AGENT_ENV_VARS. Deriving the selectable set from that map keeps it a single
+ *  source of truth with the agent→API-key-env-var mapping (cloud.js) and the
+ *  gcp-bootstrap CLI installer, so adding an agent is still a one-line change in
+ *  AGENT_ENV_VARS rather than a list to keep in sync here. */
+const AGENTS = Object.freeze(Object.keys(AGENT_ENV_VARS));
 
 const EMPTY_CONFIG = Object.freeze({
   clientRepo: "",
@@ -18,6 +25,9 @@ const EMPTY_CONFIG = Object.freeze({
   newProjectName: "",
   editorVariant: "dev",
   editorBranch: "",
+  // Build agent provider the VM's editor terminal runs (claude | codex | gemini).
+  // Defaults to claude; cloudUpArgs forwards it as cloud:up's --agent flag.
+  agent: "claude",
 });
 
 /** Coerce a raw form/query object into the canonical launch-config shape: trim
@@ -26,12 +36,17 @@ const EMPTY_CONFIG = Object.freeze({
 function normalizeLaunchConfig(input = {}) {
   const str = (v) => (typeof v === "string" ? v.trim() : "");
   const editorVariant = EDITOR_VARIANTS.includes(input.editorVariant) ? input.editorVariant : "dev";
+  // Coerce an unknown/absent agent to the default rather than rejecting — the
+  // form's agent selector only ever submits a known value, so an out-of-set
+  // agent is a stale query param, not an error.
+  const agent = AGENTS.includes(input.agent) ? input.agent : "claude";
   return {
     clientRepo: str(input.clientRepo),
     clientBranch: str(input.clientBranch),
     newProjectName: str(input.newProjectName),
     editorVariant,
     editorBranch: str(input.editorBranch),
+    agent,
   };
 }
 
@@ -111,13 +126,25 @@ function variantImageTag(variant) {
 /** Build the `cloud:up` flag array for a launch config + instance name. The
  *  editor source is the canonical codeyam-editor repo (dev variant builds the
  *  image from editorBranch); the client repo/branch is what lands in
- *  /workspace. Decoupled exactly as cloud.js consumes them. */
-function cloudUpArgs(cfg, instanceName, agent = "claude") {
+ *  /workspace. The build agent rides on `cfg.agent` (normalizeLaunchConfig
+ *  guarantees a known value, defaulting to claude), so a single config object
+ *  carries every launch choice. Decoupled exactly as cloud.js consumes them. */
+function cloudUpArgs(cfg, instanceName, project) {
   const args = ["--instance-name", instanceName];
+  // Pass the authoritative GCP project (the dashboard's resolved PROJECT)
+  // explicitly so cloud:up never relies on the spawning shell's ambient
+  // `gcloud config get-value project`. Critically, a `--project` flag OVERRIDES
+  // a persisted .codeyam/cloud.json `project` (cloud.js merges
+  // `{ ...existing, ...flags }`), which a bare cloud:up reuses verbatim with no
+  // gcloud fallback — the sticky-wrong-project failure mode where a stale
+  // "gcp-proj" in cloud.json wedges every re-provision with a firewall-create
+  // PERMISSION_DENIED. Omitted when unset to preserve the pre-existing arg shape
+  // (cloud.js then falls back to the gcloud default, as before).
+  if (project) args.push("--project", project);
   // Greenfield (new folder) vs clone an existing repo.
   if (cfg.newProjectName) args.push("--new-project", cfg.newProjectName);
   else args.push("--repo", cfg.clientRepo);
-  args.push("--agent", agent, "--editor-repo", CANONICAL_EDITOR_REPO, "--editor-variant", cfg.editorVariant);
+  args.push("--agent", cfg.agent || "claude", "--editor-repo", CANONICAL_EDITOR_REPO, "--editor-variant", cfg.editorVariant);
   if (!cfg.newProjectName && cfg.clientBranch) args.push("--branch", cfg.clientBranch);
   if (cfg.editorBranch) args.push("--editor-branch", cfg.editorBranch);
   // The dashboard opens its own per-VM tunnel, so cloud:up must NOT open one:
@@ -237,6 +264,40 @@ function distinctConfigs(history, limit = 12) {
   return out;
 }
 
+/** Display-side companion to `distinctConfigs`: derive the two label strings the
+ *  "recent launches" picker renders for one config, so two configs that differ
+ *  only by build agent (or greenfield project name) look different instead of
+ *  collapsing to identical rows. `distinctConfigs` de-dups on the FULL config, so
+ *  the rows are genuinely distinct launches — the old inline label just never
+ *  surfaced the distinguishing fields (agent, greenfield name).
+ *
+ *  Returns { primary, secondary }:
+ *   - primary:   greenfield (`!clientRepo && newProjectName`) → `new: <name>` so
+ *                two different greenfield projects no longer both read `(none)`;
+ *                else `repoBasename(clientRepo)` + (`@<branch>` when set); else
+ *                `(none)` when there's neither a repo nor a project name.
+ *   - secondary: `editor <variant>` + (`@<editorBranch>` when set) + ` · <agent>`.
+ *
+ *  Normalizes through EMPTY_CONFIG so a pre-`agent` history entry still renders
+ *  `· claude`. Reuses `repoBasename` (cloud.js) so server/browser basename
+ *  semantics stay single-sourced. Pure; no I/O. */
+function recentLaunchDisplay(config) {
+  const cfg = { ...EMPTY_CONFIG, ...(config || {}) };
+  let primary;
+  if (!cfg.clientRepo && cfg.newProjectName) {
+    primary = `new: ${cfg.newProjectName}`;
+  } else if (cfg.clientRepo) {
+    primary = repoBasename(cfg.clientRepo) + (cfg.clientBranch ? `@${cfg.clientBranch}` : "");
+  } else {
+    primary = "(none)";
+  }
+  const secondary =
+    `editor ${cfg.editorVariant || "dev"}` +
+    (cfg.editorBranch ? `@${cfg.editorBranch}` : "") +
+    ` · ${cfg.agent || "claude"}`;
+  return { primary, secondary };
+}
+
 /** The default config to pre-fill the launch form: the most recent launch's
  *  config, or an empty config when there's no history. */
 function defaultConfig(history) {
@@ -591,7 +652,48 @@ function buildEnvApplyCommand({ gcloud, instance, zone, envFile, container, edit
   return `base64 < ${_shq(envFile)} | ${gcloud} compute ssh ${instance} --tunnel-through-iap --zone=${zone} --command=${_shq(sink)}`;
 }
 
+/** Get authenticated Git URL for checking client branch. */
+function getAuthRepoUrl(repo, token) {
+  if (!repo) return "";
+  if (!token) return repo;
+  const sshRegex = /^git@github\.com:([^/]+)\/(.+?)(?:\.git)?$/;
+  const sshMatch = repo.match(sshRegex);
+  if (sshMatch) {
+    return `https://x-access-token:${token}@github.com/${sshMatch[1]}/${sshMatch[2]}`;
+  }
+  if (repo.startsWith("https://github.com/")) {
+    return repo.replace(/^https:\/\/github\.com\//, `https://x-access-token:${token}@github.com/`);
+  }
+  return repo;
+}
+
+/** Interpret the output of git ls-remote to see if a branch exists. */
+function interpretLsRemote({ stdout = "", code = 0, err = null, repo = "", branch = "" } = {}) {
+  const b = (branch || "").trim();
+  if (!b) {
+    return { ok: true, msg: "using repo default branch" };
+  }
+  if (err || code !== 0) {
+    const errMsg = (err && (err.message || String(err))) || "command failed";
+    return {
+      ok: false,
+      soft: true,
+      msg: `couldn't verify branch: ${errMsg.trim()}`
+    };
+  }
+  const trimmed = (stdout || "").trim();
+  if (trimmed) {
+    return { ok: true };
+  } else {
+    return {
+      ok: false,
+      msg: `branch '${b}' not found in ${repo || "repository"}`
+    };
+  }
+}
+
 module.exports = {
+  AGENTS,
   EMPTY_CONFIG,
   normalizeLaunchConfig,
   validateLaunchConfig,
@@ -606,6 +708,7 @@ module.exports = {
   queuedStatusForAction,
   pushHistory,
   distinctConfigs,
+  recentLaunchDisplay,
   defaultConfig,
   configForVm,
   resolveCardIdentity,
@@ -619,4 +722,6 @@ module.exports = {
   editorSourceShellResolve,
   rebuildStrategy,
   decideStartJob,
+  getAuthRepoUrl,
+  interpretLsRemote,
 };

package/npm/scenario-check.js

@@ -275,6 +275,76 @@ function pushRedirectMismatchIssue(issues, requestedUrl, frame, response, config
   );
 }
 
+// Read-only page-state snapshot for `capture-state`: the full localStorage
+// map, a bounded sample of visible text nodes (document order), and — when a
+// selector is given — that element's text. Evaluated in-page against the
+// settled frame so it reflects exactly what a real capture saw (the proxy
+// already injected the scenario's seed into the served HTML). Every read is
+// individually guarded so a sandboxed/cross-origin localStorage never throws
+// the whole capture; the worst case is an empty section, not a failure.
+async function dumpPageState(frame, selector) {
+  return frame.evaluate((sel) => {
+    const localStorage = {};
+    try {
+      for (let i = 0; i < window.localStorage.length; i++) {
+        const key = window.localStorage.key(i);
+        if (key != null) localStorage[key] = window.localStorage.getItem(key);
+      }
+    } catch (_) {
+      /* localStorage may be unavailable (sandboxed/opaque origin) */
+    }
+
+    const visibleText = [];
+    try {
+      // Reject text inside non-rendered tags (SCRIPT/STYLE/etc.) so an
+      // injected proxy script or inline CSS never masquerades as on-screen
+      // text — that noise is exactly what makes a state dump misleading.
+      const SKIP_TAGS = new Set([
+        "SCRIPT",
+        "STYLE",
+        "NOSCRIPT",
+        "TEMPLATE",
+        "HEAD",
+        "TITLE",
+      ]);
+      const walker = document.createTreeWalker(
+        document.body,
+        NodeFilter.SHOW_TEXT,
+        {
+          acceptNode(node) {
+            const parent = node.parentElement;
+            if (parent && SKIP_TAGS.has(parent.tagName)) {
+              return NodeFilter.FILTER_REJECT;
+            }
+            return (node.textContent || "").trim()
+              ? NodeFilter.FILTER_ACCEPT
+              : NodeFilter.FILTER_REJECT;
+          },
+        },
+      );
+      let node;
+      while ((node = walker.nextNode()) && visibleText.length < 40) {
+        const text = (node.textContent || "").replace(/\s+/g, " ").trim();
+        if (text) visibleText.push(text);
+      }
+    } catch (_) {
+      /* no body / detached document */
+    }
+
+    let selectorText = null;
+    if (sel) {
+      try {
+        const el = document.querySelector(sel);
+        if (el) selectorText = (el.textContent || "").replace(/\s+/g, " ").trim();
+      } catch (_) {
+        /* invalid selector — leave selectorText null */
+      }
+    }
+
+    return { localStorage, visibleText, selectorText };
+  }, selector || null);
+}
+
 // `preflight` is injectable (defaulting to the real app-port reachability
 // check) so unit tests that mock the browser can stay network-free.
 async function runScenarioCheck(config, { preflight = assertAppPortReachable } = {}) {
@@ -460,13 +530,22 @@ async function runScenarioCheck(config, { preflight = assertAppPortReachable } =
       await page.screenshot({ path: outputPath, fullPage: false });
     }
 
-    return buildResult({
+    const result = buildResult({
       loaded,
       hasContent,
       issues,
       outputPath,
       url: frame.url() || url,
     });
+
+    // `capture-state` mode: attach the read-only page-state snapshot so the
+    // backend can report localStorage + rendered text. Off by default, so a
+    // normal error-check capture is byte-for-byte unchanged.
+    if (config.captureState) {
+      result.state = await dumpPageState(frame, config.stateSelector);
+    }
+
+    return result;
   } catch (error) {
     pushIssue(
       issues,
@@ -506,6 +585,7 @@ async function main() {
 
 module.exports = {
   runScenarioCheck,
+  dumpPageState,
   readStackLoadingMarkers,
   applyBrowserState,
   isCrossOriginRequest,

package/npm/scenario-handlers.js

@@ -48,6 +48,22 @@ function handleConsoleMessage(message) {
     return null;
   }
 
+  // Ignore the browser's blocked-script warning for sandboxed mockup-preview
+  // frames. Mockup previews render untrusted AI-generated HTML inside a
+  // `sandbox=""` iframe; the HTML-injection proxy injects an error-capture
+  // <script> tag, which the browser then refuses to run, emitting
+  // "Blocked script execution ... because the frame is sandboxed". That block
+  // is the capture's own injected script being denied — benign for capture
+  // purposes. Match narrowly on BOTH the block phrase and the "sandboxed"
+  // signature so a genuine non-sandbox CSP block ("Blocked script execution"
+  // without "sandboxed") still surfaces as a real issue.
+  if (
+    text.includes("Blocked script execution") &&
+    text.includes("sandboxed")
+  ) {
+    return null;
+  }
+
   return createIssue("console", text);
 }