@foldspace_npm/harness 0.1.26 → 0.1.28

package/src/observe-core.mjs

@@ -44,7 +44,7 @@ export function isSameSite(url, pageUrl, hosts = []) {
 }
 
 /**
- * One product often lives on several hosts (www., analyze., admin. ...), and a
+ * One product often lives on several hosts (www., reports., admin. ...), and a
  * project only works on the hosts it names. Given addresses seen from a page,
  * say which hosts look like the same product but are NOT covered, and the one
  * pattern that would cover them. The site is an approximation (see siteOf), so
@@ -81,7 +81,7 @@ export function uncoveredSiblings(urls, pageUrl, hosts = []) {
     hint:
       `This product also lives on ${found.slice(0, 4).map((entry) => entry.host).join(", ")}` +
       `${found.length > 4 ? ` and ${found.length - 4} more` : ""}, which this project does not cover. ` +
-      `To work there, add "${pattern}" to "hosts" in foldspace.dev.json - with the human's yes - then run inject and attach again.`,
+      `To work there, add "${pattern}" to "hosts" in foldspace.dev.json - with the human's yes - then \`npx foldspace attach --stop\`, \`npm run inject\` and \`npx foldspace attach --daemon\` with the flags it ran with.`,
   };
 }
 
@@ -132,7 +132,7 @@ export function gotoDestination(input, pageUrl, hosts = []) {
     throw new Error(
       `--goto: ${target.hostname} is not one of this project's hosts (${hosts.join(", ") || "none named"}). ` +
         (coverage.pattern
-          ? `If it is part of the product, add "${coverage.pattern}" to "hosts" in foldspace.dev.json - with the human's yes - then run inject and attach again.`
+          ? `If it is part of the product, add "${coverage.pattern}" to "hosts" in foldspace.dev.json - with the human's yes - then \`npx foldspace attach --stop\`, \`npm run inject\` and \`npx foldspace attach --daemon\` with the flags it ran with. If it is not, --goto a screen on this project's hosts.`
           : "observe only opens screens of the product this project is for."),
     );
   }
@@ -398,6 +398,11 @@ export function rankCandidates(candidates, words = [], max = 8) {
 
 const WRITE_FLAGS = ["method", "data", "body", "header", "headers", "json", "post", "put", "delete"];
 
+/** True for an option that would make `observe read` write (`--method`, `--body`, ...). */
+export function isWriteFlag(option) {
+  return WRITE_FLAGS.includes(String(option || "").replace(/^--/, ""));
+}
+
 /**
  * `observe read` is GET only. There is deliberately no way to pick a method,
  * add a header or send a body: anything else belongs in an action handler the
@@ -407,7 +412,7 @@ export function refuseWriteFlags(flags = {}) {
   const asked = WRITE_FLAGS.filter((name) => name in flags);
   if (asked.length) {
     throw new Error(
-      `observe read is GET only and never sends a body (refused: ${asked
+      `observe read is GET only - it never sets a method, a header or a body (refused: ${asked
         .map((name) => `--${name}`)
         .join(", ")}).`,
     );
@@ -706,8 +711,9 @@ export function looksLoggedIn({ url, hasPasswordField = false, hosts = [] }) {
 
 /** Computed colours come back as rgb()/rgba(); anything else passes through. */
 // oklch / oklab, as modern apps write their palettes and as Chrome reports
-// them back, converted to sRGB. Cards must be plain hex: the panel saves them
-// to history as an image drawn by a library that cannot read these.
+// them back, converted to sRGB hex like rgb() and rgba(): brandFile checks
+// contrast and works out its other keys from hex. lab(), lch() and color()
+// pass through; brandFile writes a default in their place.
 function okToHex(text) {
   const match = /^(oklch|oklab)\(\s*([\d.]+%?)\s+(-?[\d.]+%?)\s+(-?[\d.]+)(?:deg)?\s*(?:\/\s*([\d.]+%?))?\s*\)$/i.exec(text);
   if (!match) return null;
@@ -770,57 +776,180 @@ function luminance(hex) {
 
 const isHex = (value) => /^#[0-9a-f]{6}([0-9a-f]{2})?$/i.test(String(value || ""));
 
+/** `share` of the way from one #RRGGBB to another, channel by channel. */
+function mixHex(from, to, share) {
+  const channels = (hex) => [1, 3, 5].map((start) => parseInt(hex.slice(start, start + 2), 16));
+  const target = channels(to);
+  return `#${channels(from)
+    .map((value, i) => Math.round(value + (target[i] - value) * share).toString(16).padStart(2, "0"))
+    .join("")
+    .toUpperCase()}`;
+}
+
 /**
  * `agent/views/brand.ts` from what `observe styles` sampled: the app's own
- * accent, text, border, font and radius, on the panel's white surface. A dark
- * app keeps its accent, font and radius; its light-on-dark text and borders
+ * accent, text, muted text, border, font, radius and text size, on white (the
+ * panel's default background), plus every other key a recipe card reads - a
+ * fixed colour (surface2 and the status colours), one worked out from the
+ * sampled ones, or another name for one of them. A see-through text, muted or
+ * border colour is flattened onto the white; a see-through accent keeps its
+ * colour at full strength, so a tinted button still gives the app's own accent.
+ * A text, muted, border or accent colour still too light to read on white falls
+ * back to its default and says so. A dark app keeps its font, radius, text size
+ * and (unless it is too light) its accent; its light-on-dark text and borders
  * would vanish on white, so those fall back to neutral greys and say so.
  */
-export function brandFile(styles, { url, date, agentPrimary } = {}) {
+export function brandFile(styles, { url, date } = {}) {
   const notes = [];
   const pick = (value, fallback, name) => {
     const hex = value ? toHex(value) : null; // rgb / oklch / oklab -> hex; anything else stays as it was
     if (isHex(hex)) return hex.slice(0, 7).toUpperCase();
-    if (value) notes.push(`${name}: sampled "${value}" is not a plain colour - using ${fallback}`);
+    if (value) notes.push(`${name}: sampled "${value}" could not be converted to hex - using ${fallback}`);
     return fallback;
   };
+  // A see-through colour (rgba, or hex with alpha) is drawn on the panel's
+  // white, so flatten it onto white: dropping the alpha would turn an
+  // rgba(0, 0, 0, 0.12) border, and every key worked out from it, black.
+  const onPanel = (value, fallback, name) => {
+    const hex = value ? toHex(value) : null;
+    const alpha = isHex(hex) && hex.length === 9 ? parseInt(hex.slice(7), 16) / 255 : 1;
+    return mixHex("#FFFFFF", pick(value, fallback, name), alpha);
+  };
   const background = pick(styles.background, "#FFFFFF", "background");
   const darkApp = (luminance(background) ?? 1) < 0.4;
-  if (darkApp) notes.push(`the app is dark (${background}); cards sit in the white panel, so text, muted and border are neutral greys`);
-  const text = darkApp ? "#111827" : pick(styles.text, "#111827", "text");
-  const muted = darkApp ? "#6B7280" : pick(styles.textMuted, "#6B7280", "textMuted");
-  const border = darkApp ? "#E5E7EB" : pick(styles.border, "#E5E7EB", "border");
+  if (darkApp) notes.push(`the app is dark (${background}); cards sit in the panel, white by default, so text, muted and border are neutral greys`);
+  // A colour too light to read on white - white nav text on a light app, a
+  // white button on a dark one - falls back to its default, and says so.
+  const readable = (resolve, value, fallback, name, limit) => {
+    const hex = resolve(value, fallback, name);
+    if ((luminance(hex) ?? 0) <= limit) return hex;
+    notes.push(`${name}: sampled "${value}" would not read on white - using ${fallback}`);
+    return fallback;
+  };
+  const text = darkApp ? "#111827" : readable(onPanel, styles.text, "#111827", "text", 0.6);
+  const muted = darkApp ? "#6B7280" : readable(onPanel, styles.textMuted, "#6B7280", "textMuted", 0.75);
+  const border = darkApp ? "#E5E7EB" : readable(onPanel, styles.border, "#E5E7EB", "border", 0.97);
   const buttonBackground = styles.primaryButton?.background;
-  const accent = isHex(agentPrimary)
-    ? agentPrimary.slice(0, 7).toUpperCase()
-    : pick(buttonBackground || styles.link, "#3248F2", "accent");
-  const accentSource = isHex(agentPrimary) ? "the agent's own primary colour" : buttonBackground ? "the app's primary button" : styles.link ? "the app's links" : "Foldspace blue (nothing sampled)";
-  const accentText = pick(styles.primaryButton?.color, (luminance(accent) ?? 0) > 0.6 ? "#111827" : "#FFFFFF", "accentText");
+  const accentSample = buttonBackground || styles.link;
+  // The accent keeps its colour at full strength: a tinted button such as
+  // rgba(50, 72, 242, 0.08) still gives the app's own blue, which the cards
+  // draw white text on.
+  const accent = readable(pick, accentSample, "#3248F2", "accent", 0.85);
+  // The accent is the app's only when the sample could be converted to hex
+  // and reads on white; otherwise a NOTE says why it is the default.
+  const accentFromApp = Boolean(accentSample) && !notes.some((note) => note.startsWith("accent:"));
+  const accentSource = !accentSample
+    ? "a default blue (nothing sampled)"
+    : !accentFromApp
+      ? "a default blue (see the NOTE on accent)"
+      : buttonBackground
+        ? "the app's primary button"
+        : "the app's links";
+  // Only a solid button's text is kept, and only when the accent is that
+  // button's: a see-through button's text was chosen for its tint.
+  const buttonHex = toHex(buttonBackground);
+  const buttonText = accentFromApp && isHex(buttonHex) && buttonHex.length === 7 ? styles.primaryButton?.color : null;
+  const accentText = pick(buttonText, (luminance(accent) ?? 0) > 0.6 ? "#111827" : "#FFFFFF", "accentText");
   const font = String(styles.fontFamily || "").replace(/["'\\]/g, "").trim() || "Roboto, sans-serif";
   const radius = /^\d+(\.\d+)?px$/.test(String(styles.boxRadius || "")) ? styles.boxRadius : "8px";
+  // The app's most used text size, kept to 12-16px so a card fits the panel.
+  const sampledSize = /^(\d+(?:\.\d+)?)px$/.exec(String(styles.fontSize || ""));
+  const base = sampledSize ? Math.min(16, Math.max(12, Math.round(Number(sampledSize[1])))) : 14;
+  const white = "#FFFFFF";
+  const black = "#000000";
+  const good = "#047857";
+  const warn = "#B45309";
+  const derived = {
+    textStrong: mixHex(text, black, 0.5),
+    faint: mixHex(muted, white, 0.35),
+    row: mixHex(border, white, 0.75),
+    tableHead: mixHex(border, white, 0.5),
+    accentDeep: mixHex(accent, black, 0.15),
+    accentSoft: mixHex(accent, white, 0.9),
+    headerStart: mixHex(accent, white, 0.92),
+  };
+  // One shape for every card: each recipe's brand.ts is a placeholder with
+  // these keys, in this order.
+  const values = {
+    surface: white,
+    surface2: "#F5F6FA",
+    text,
+    muted,
+    border,
+    accent,
+    accentText,
+    font,
+    radius,
+    size: { base: `${base}px`, small: `${base - 2}px` },
+    ...derived,
+    good,
+    warn,
+    warnInk: "#FEF3C7",
+    bad: "#B91C1C",
+    primary: accent,
+    tint: derived.tableHead,
+    disabled: derived.faint,
+    money: good,
+    ok: good,
+    deals: accent,
+    contacts: derived.accentDeep,
+    cases: warn,
+  };
+  const groups = {
+    textStrong: "Worked out from the values above.",
+    good: "Status colours: fixed, so green, amber and red mean the same in every app.",
+    primary: "Other names some cards use for the colours above; a new card uses the original key.",
+  };
+  const comments = {
+    surface2: "a second background: a fixed light grey",
+    accentText: isHex(toHex(buttonText))
+      ? "text on accent: the app's button text"
+      : "text on accent: white, or near-black when accent is light",
+    size: sampledSize
+      ? "base: the app's most used text size, kept to 12-16px; small: 2px less"
+      : "base: 14px (no text size was sampled); small: 2px less",
+    textStrong: "names and headings: text, halfway to black",
+    faint: "hints and empty states: muted, 35% toward white",
+    row: "row backgrounds and alternate rows: border, 75% toward white",
+    tableHead: "table heads and summary boxes: border, halfway to white",
+    accentDeep: "gradients and hover: accent, 15% toward black",
+    accentSoft: "chips, selected rows and focus rings: accent, 90% toward white",
+    headerStart: "card headers and stage tags: accent, 92% toward white",
+    good: "done, valid, amounts",
+    warn: "late, at risk, needs a look",
+    warnInk: "the light amber behind a warning tag",
+    bad: "failed, not valid, critical",
+    primary: "same as accent",
+    tint: "pick-from-a-list's head and selected row: same as tableHead",
+    disabled: "a button that cannot be pressed: same as faint",
+    money: "amounts: same as good",
+    ok: "same as good",
+    deals: "the open-deals count: same as accent",
+    contacts: "the contacts count: same as accentDeep",
+    cases: "the open-cases count: same as warn",
+  };
+  const literal = (key, value) =>
+    key === "size" ? `{ base: "${value.base}", small: "${value.small}" }` : key === "font" ? `'${value}'` : `"${value}"`;
   const stamp = `${url || "the app"}${date ? ` on ${date}` : ""}`;
   const lines = [
     `// Brand reference for this product's cards. Sampled from ${stamp} with`,
-    "// `foldspace observe styles --write`. Cards live in the agent's panel, which is",
-    "// white, so the surface is the panel's; accent, text, border, font and radius",
-    "// are the app's own. Re-run the command to re-sample; do not edit by eye.",
-    "// Plain hex only: the panel saves cards to history as an image drawn by a",
-    "// library that cannot read oklch()/lab().",
+    "// `npx foldspace observe styles --write`. Cards live in the agent's panel,",
+    "// which is white by default, so surface is white. text, muted, border, accent,",
+    "// font, radius and size are the app's own, or a default where they were not",
+    "// sampled or would not read on white; every other key's comment, or the",
+    "// heading above it, says where it comes from. Keep every key, so any recipe",
+    "// card can use this file.",
+    "// Re-run the command to re-sample; do not edit by eye.",
     `// accent: ${accentSource}.`,
     ...notes.map((note) => `// NOTE ${note}.`),
     "",
     "export const brand = {",
-    `  surface: "#FFFFFF",`,
-    `  surface2: "#F5F6FA",`,
-    `  text: "${text}",`,
-    `  muted: "${muted}",`,
-    `  border: "${border}",`,
-    `  accent: "${accent}",`,
-    `  accentText: "${accentText}",`,
-    `  font: '${font}',`,
-    `  radius: "${radius}",`,
+    ...Object.entries(values).flatMap(([key, value]) => [
+      ...(groups[key] ? [`  // ${groups[key]}`] : []),
+      `  ${key}: ${literal(key, value)},${comments[key] ? ` // ${comments[key]}` : ""}`,
+    ]),
     "} as const;",
     "",
   ];
-  return { content: lines.join("\n"), notes, values: { text, muted, border, accent, accentText, font, radius } };
+  return { content: lines.join("\n"), notes, values };
 }

package/src/published-core.mjs

@@ -0,0 +1,392 @@
+// Pure logic behind `foldspace published <dev|prod>`, unit-tested.
+//
+// The command points the test window's agent at the code published to dev or
+// prod, so `foldspace ask` checks that code instead of the local build. Each
+// refusal here keeps that check honest: while attach runs the page serves the
+// local build, and a page whose agent is not this project's would load another
+// agent's code.
+
+import { ACTION_OBSERVER_GLOBAL } from "./action-observer.mjs";
+import { ATTACH_MODES, characterizePageAgents, parseAgentId } from "./attach-helpers.mjs";
+import { detectedProductIds, guardAttachMode } from "./attach-preflight.mjs";
+import { serializeDiagnostic } from "./diagnostics.mjs";
+
+export const PUBLISHED_USAGE = "usage: foldspace published <dev|prod>";
+
+// The public SDK's values for remoteActionsSettings.environment: "DEV" loads
+// /agent/actions/dev/<product>/<agent>/index.js, anything else - "PROD" is
+// the default - /agent/actions/prod/... (checked against script.eucerahive.io
+// /web/sdk/foldspace.js, built 2026-10-04).
+export const ENVIRONMENTS = Object.freeze({ dev: "DEV", prod: "PROD" });
+
+export const ATTACH_RUNNING =
+  "Stop attach first: `npx foldspace attach --stop` - while it runs the page serves your local build.";
+
+// No daemon runs, yet the page carries the local build again after a reload:
+// an attach started without --daemon is connected, and `attach --stop` (which
+// stops only the daemon) does not reach it.
+export const FOREGROUND_ATTACH =
+  "This page still runs a local build after a reload, but no attach daemon runs for this project: an attach started without --daemon is still connected to the test window.";
+
+export function foregroundAttachNext(env) {
+  return `Stop the attach that was started without --daemon - \`attach --stop\` stops only the daemon - then run \`npx foldspace published ${env}\` again.`;
+}
+
+export const RELOAD_NOTE = "A reload puts the page back on what the agent loads normally.";
+
+// Every published bundle assigns its handlers here; the SDK reads and deletes it.
+export const REMOTE_ACTIONS_GLOBAL = "__FOLDSPACE_REMOTE_ACTIONS__";
+
+// Every refusal below comes after `attach --stop`, so each next step starts by
+// putting the local build back. A platform gap never stops the session.
+const word = (env) => (env === "prod" ? "production" : "dev");
+const lower = (text) => `${text.charAt(0).toLowerCase()}${text.slice(1)}`;
+
+/** The page is this project's agent, but this window cannot show the published code. */
+export function notHere(env) {
+  return `Run \`npx foldspace attach --daemon\` to put your local build back in the test window, and tell the human in one sentence that the test window cannot show ${word(env)} yet - do not invite them to try ${word(env)} there.`;
+}
+
+/** Worth one more run; then the window cannot show it. */
+function again(env) {
+  return `Run \`npx foldspace published ${env}\` once more. If it fails again: ${lower(notHere(env))}`;
+}
+
+/**
+ * The page needs --bootstrap or --replace to attach, which is not a site that
+ * loads this agent by itself: the manual sends the rest to the Foldspace team.
+ */
+function attachAgain(flag) {
+  return `Run \`npx foldspace attach --daemon ${flag}\` to put your local build back in the test window. A page that needs \`${flag}\` cannot show the published code, and production waits until their site loads this agent by itself: for the rest, give the human the Foldspace team answer (CLAUDE.md, "Done, and what you say at the end").`;
+}
+
+// How long the agent gets to load the published code. The SDK gives up on the
+// script itself after 10s.
+export const LOAD_TIMEOUT_MS = 20_000;
+
+/** "dev" | "prod" (any case) -> { name, sdkValue }, or throws the usage line. */
+export function publishedEnvironment(value) {
+  const name = String(value ?? "").trim().toLowerCase();
+  if (!Object.hasOwn(ENVIRONMENTS, name)) throw new Error(PUBLISHED_USAGE);
+  return { name, sdkValue: ENVIRONMENTS[name] };
+}
+
+/** The agent foldspace.dev.json names, as inject recorded it. */
+export function projectAgent(launchTarget = {}, configTarget = {}) {
+  const target = { ...configTarget, ...launchTarget };
+  if (!target.productId || !target.agentApiName) {
+    throw new Error("foldspace.dev.json must define productId and agentApiName.");
+  }
+  return {
+    productId: String(target.productId),
+    apiName: String(target.agentApiName),
+    mode: String(target.mode || "OVERLAY").toUpperCase(),
+  };
+}
+
+/**
+ * Page body: what attach's own preflight reads (inspectSdkState), whether
+ * attach prepared this document, and how long ago the document loaded.
+ */
+export function buildPageReadScript(agent) {
+  return `const state = await ${serializeDiagnostic("inspectSdkState", {
+    expectedApiName: agent.apiName,
+  })};
+    return {
+      state,
+      attachPrepared: Boolean(window[${JSON.stringify(ACTION_OBSERVER_GLOBAL)}] || window.__FOLDSPACE_DEV_REPLACE__),
+      ageMs: Math.round(performance.now()),
+    };`;
+}
+
+/**
+ * Enough of the page has loaded to judge it: its agent is there, and no load
+ * of remote actions is in flight (the SDK removes that script once it lands).
+ */
+export function pageSettled(read) {
+  const state = read?.state;
+  if (!state) return false;
+  if (read.attachPrepared) return true;
+  const ready = state.documentReadyState === "interactive" || state.documentReadyState === "complete";
+  const loading = (state.scripts || []).some((source) => String(source).includes("/agent/actions/"));
+  return ready && state.sdkReady === true && (state.agentIds || []).length > 0 && !loading;
+}
+
+/** The mode the page created this agent in, when it has exactly one instance of it. */
+export function modeOnPage(agentIds = [], apiName) {
+  const mine = agentIds.map(parseAgentId).filter((agent) => agent && agent.apiName === apiName);
+  return mine.length === 1 ? mine[0].mode : null;
+}
+
+/**
+ * Is the page's own Foldspace agent this project's agent - same Agent Key, same
+ * product? Attach's swap-mode preflight answers exactly that, so it is reused.
+ */
+export function checkPublishedPage({ state, agent }) {
+  const mode = modeOnPage(state?.agentIds, agent.apiName) || agent.mode;
+  const characterization = characterizePageAgents({
+    sdkPresent: state?.sdkPresent === true,
+    agentIds: state?.agentIds || [],
+    expectedApiName: agent.apiName,
+    expectedMode: mode,
+  });
+  const pageProductIds = detectedProductIds(state);
+  const guard = guardAttachMode({
+    mode: ATTACH_MODES.SWAP,
+    characterization,
+    expectedProductId: agent.productId,
+    pageProductIds,
+  });
+  if (guard.ok) return { ok: true, mode };
+
+  const status = characterization.status;
+  const next = attachAgain(status === "no-sdk" ? "--bootstrap" : "--replace");
+  let reason;
+  if (status === "no-sdk") {
+    reason = "This page has no Foldspace agent of its own, so there is nothing to load the published code into.";
+  } else if (status === "sdk-without-agent") {
+    reason = "This page loads Foldspace but has no agent on it.";
+  } else if (status === "different-agent") {
+    reason = `This page's Foldspace agent is not ${agent.apiName}, the Agent Key in foldspace.dev.json, so foldspace ask would talk to another agent and the check would prove nothing.`;
+  } else if (status === "multiple-agents") {
+    reason = "This page has more than one Foldspace agent, so it is not clear which one foldspace ask would talk to.";
+  } else if (!pageProductIds.length) {
+    reason = `The page's agent is ${agent.apiName}, but its product cannot be read from the page, so it is not proven to be this project's agent.`;
+  } else {
+    reason = `The page's agent is ${agent.apiName} of another product (${pageProductIds.join(", ")}), not ${agent.productId} in foldspace.dev.json: it would load that product's code, and the check would prove nothing.`;
+  }
+  return {
+    ok: false,
+    reason,
+    next,
+    page: { agents: state?.agentIds || [], products: pageProductIds },
+  };
+}
+
+/**
+ * Page body that points the agent instance at its published code and reports
+ * what loaded. It calls only the instance's public methods, and watches the
+ * one global every published bundle assigns itself to.
+ *
+ * What in the SDK shapes it:
+ * - A published bundle assigns its handlers to window.__FOLDSPACE_REMOTE_ACTIONS__;
+ *   the SDK reads that global when the script loads, deletes it, and then
+ *   reports remoteActions.loaded. Watching the global is how this knows the
+ *   exact handlers the published code brought.
+ * - When remote actions load, a handler the instance already has wins over a
+ *   loaded one of the same name - the page's own, or what its normal load
+ *   brought, even when that load lands late. So once the published code has
+ *   loaded, its handlers are set over every one of the same name, and the
+ *   check counts only the names that answer from the published code.
+ * - An agent created late queues these calls until it is ready, and its
+ *   getAvailableActions() reads {} until then. Nothing is taken from the page
+ *   before the load: what it had is read only after the load reported.
+ * - setConfiguration loads nothing when the settings equal the current ones
+ *   (the page may already load prod, or ran this before). Turning remote
+ *   actions off first makes the second call a change.
+ * The page remembers what an earlier run brought and what it covered, so dev's
+ * handlers do not linger into a prod check.
+ */
+export function buildPublishedScript({ apiName, mode, environment, timeoutMs = LOAD_TIMEOUT_MS }) {
+  return `
+    const NS = typeof window.__FOLD_SPACE__ === "string" && window.__FOLD_SPACE__ ? window.__FOLD_SPACE__ : "foldspace";
+    const sdk = window[NS];
+    if (typeof sdk?.agent !== "function") return { switched: false, reason: "no-sdk" };
+    const agent = sdk.agent({ apiName: ${JSON.stringify(apiName)}, mode: ${JSON.stringify(mode)} });
+    const needed = ["getAvailableActions", "removeAiActions", "setAiActions", "setConfiguration", "on", "off"];
+    const missing = needed.filter((name) => typeof agent?.[name] !== "function");
+    if (missing.length) return { switched: false, reason: "sdk-too-old", missing };
+
+    const ENV = ${JSON.stringify(environment.name)};
+    const store = window.__FOLDSPACE_PUBLISHED__ || (window.__FOLDSPACE_PUBLISHED__ = {});
+    const ID = ${JSON.stringify(`${mode.toLowerCase()}-${apiName}`)};
+    // own: the page's handler for a name the published code covered, before
+    // any run covered it. brought: what the last run set.
+    const memo = store[ID]?.brought ? store[ID] : (store[ID] = { own: {}, brought: {} });
+
+    const GLOBAL = ${JSON.stringify(REMOTE_ACTIONS_GLOBAL)};
+    let held = window[GLOBAL];
+    let lastRead;
+    let watching = true;
+    const watch = {
+      configurable: true,
+      enumerable: true,
+      get() {
+        lastRead = held;
+        queueMicrotask(rearm);
+        return held;
+      },
+      set(value) { held = value; },
+    };
+    const armed = () => Object.getOwnPropertyDescriptor(window, GLOBAL)?.get === watch.get;
+    // The SDK deletes the global right after reading it; watch for the next load.
+    function rearm() {
+      if (!watching || armed()) return;
+      held = undefined;
+      try { Object.defineProperty(window, GLOBAL, watch); } catch {}
+    }
+    try { Object.defineProperty(window, GLOBAL, watch); } catch {}
+
+    let settle;
+    const outcome = new Promise((resolve) => { settle = resolve; });
+    const onLoaded = (event) => {
+      // The read that just happened belongs to this load, whichever load it is.
+      const bundle = lastRead;
+      lastRead = undefined;
+      if (event?.environment === ENV) {
+        settle({ loaded: true, actionCount: Number(event.actionCount) || 0, source: event.source || null, bundle });
+      }
+    };
+    const onFailed = (event) => {
+      if (event?.environment === ENV) settle({ loaded: false, source: event.source || null });
+    };
+    agent.on("remoteActions.loaded", onLoaded);
+    agent.on("remoteActions.failed", onFailed);
+    let result;
+    let timer;
+    try {
+      agent.setConfiguration({ remoteActionsSettings: { enabled: false } });
+      agent.setConfiguration({
+        enableDebugLogs: true,
+        remoteActionsSettings: { enabled: true, environment: ${JSON.stringify(environment.sdkValue)} },
+      });
+      result = await Promise.race([
+        outcome,
+        new Promise((resolve) => { timer = setTimeout(() => resolve({ loaded: null }), ${Number(timeoutMs)}); }),
+      ]);
+    } catch (error) {
+      result = { loaded: false, error: String(error?.message || error).slice(0, 300) };
+    } finally {
+      clearTimeout(timer);
+      agent.off("remoteActions.loaded", onLoaded);
+      agent.off("remoteActions.failed", onFailed);
+      watching = false;
+      if (armed()) {
+        delete window[GLOBAL];
+        if (held !== undefined) window[GLOBAL] = held;
+      }
+    }
+
+    const { bundle, ...report } = result;
+    if (result.loaded !== true) return { switched: true, ...report };
+    if (!bundle || typeof bundle !== "object") {
+      return { switched: true, ...report, published: report.actionCount ? null : [], kept: [] };
+    }
+
+    // The SDK takes only entries with an execute function.
+    const names = Object.keys(bundle).filter((name) => typeof bundle[name]?.execute === "function");
+    const now = agent.getAvailableActions() || {};
+    for (const name of names) {
+      const current = now[name];
+      if (current && current !== bundle[name] && current !== memo.brought[name] && !(name in memo.own)) {
+        memo.own[name] = current;
+      }
+    }
+    // What an earlier run brought that this code does not define goes; the
+    // page's own handler for that name comes back.
+    for (const name of Object.keys(memo.brought)) {
+      if (names.includes(name) || now[name] !== memo.brought[name]) continue;
+      if (name in memo.own) agent.setAiActions({ [name]: memo.own[name] });
+      else agent.removeAiActions([name]);
+    }
+    const over = {};
+    for (const name of names) if (now[name] !== bundle[name]) over[name] = bundle[name];
+    if (Object.keys(over).length) agent.setAiActions(over);
+    memo.brought = Object.fromEntries(names.map((name) => [name, bundle[name]]));
+
+    const after = agent.getAvailableActions() || {};
+    const published = names.filter((name) => after[name] === bundle[name]).sort();
+    const kept = names.filter((name) => after[name] !== bundle[name]).sort();
+    return { switched: true, ...report, published, kept };`;
+}
+
+/**
+ * The published code of an environment is /agent/actions/<env>/<product>/<agent>/index.js.
+ * Anything else the agent loaded is not what was published last: an agent
+ * pinned to one version loads index.<version>.js (the SDK reports that name
+ * even when it falls back to index.js), and a host override loads from
+ * elsewhere entirely.
+ */
+export function publishedSourceProblem({ source, env, agent }) {
+  if (!source) return null;
+  const path = `/agent/actions/${env}/${agent.productId}/${agent.apiName}/`;
+  if (source.endsWith(`${path}index.js`)) return null;
+  if (!source.includes(`/agent/actions/${env}/`)) {
+    return `The agent loaded ${source}, not the published ${word(env)} code: its configuration names its own address for actions.`;
+  }
+  if (source.includes(path) && /\/index\.[^/]+\.js$/.test(source)) {
+    return `The agent loaded ${source}: it is pinned to one version of its code, so this window keeps loading that version, not what was published last.`;
+  }
+  return `The agent loaded ${source}, not the published ${word(env)} code of ${agent.apiName}.`;
+}
+
+/** The JSON the command prints, from what the page reported. */
+export function publishedReport({ outcome, environment, agent, timeoutMs = LOAD_TIMEOUT_MS }) {
+  const env = environment.name;
+  const base = { environment: env, agent: agent.apiName };
+  if (!outcome?.switched) {
+    return {
+      ok: false,
+      ...base,
+      reason:
+        outcome?.reason === "sdk-too-old"
+          ? `This page's Foldspace SDK cannot load published code on request: its agent has no ${outcome.missing.join(", ")}.`
+          : "This page has no Foldspace agent to point at the published code.",
+      next: notHere(env),
+    };
+  }
+  if (outcome.loaded === null) {
+    return {
+      ok: false,
+      ...base,
+      reason: `The agent did not report loading the published ${word(env)} code within ${Math.round(timeoutMs / 1000)}s. Its own handlers are untouched; ${lower(RELOAD_NOTE)}`,
+      next: again(env),
+    };
+  }
+  if (outcome.error) {
+    return {
+      ok: false,
+      ...base,
+      reason: `This page's agent failed while switching to the published ${word(env)} code: ${outcome.error}. Its own handlers are untouched; ${lower(RELOAD_NOTE)}`,
+      next: notHere(env),
+    };
+  }
+  if (outcome.loaded === false) {
+    return {
+      ok: false,
+      ...base,
+      reason: `The page could not load the published ${word(env)} code${outcome.source ? ` (${outcome.source})` : ""}. Its own handlers are untouched; ${lower(RELOAD_NOTE)}`,
+      next:
+        env === "dev"
+          ? `If you have not published to dev with the \`deploy\` tool yet, do that, then run \`npx foldspace published dev\` again. If you have, run it again in a minute; if it fails again: ${lower(notHere(env))}`
+          : `If you have published to production with the \`deploy\` tool, run \`npx foldspace published prod\` again in a minute. If you have not (production gets code only with the human's yes), or it fails again: ${lower(notHere(env))}`,
+    };
+  }
+  const sourceProblem = publishedSourceProblem({ source: outcome.source, env, agent });
+  if (sourceProblem) return { ok: false, ...base, reason: sourceProblem, next: notHere(env) };
+  if (!Array.isArray(outcome.published)) {
+    return {
+      ok: false,
+      ...base,
+      reason: `The agent loaded the published ${word(env)} code, but the page did not show which handlers it brought, so it is not proven that foldspace ask would test that code.`,
+      next: notHere(env),
+    };
+  }
+  const kept = outcome.kept || [];
+  if (kept.length) {
+    const count = outcome.published.length + kept.length;
+    return {
+      ok: false,
+      ...base,
+      reason: `The published ${word(env)} code has ${count} ${count === 1 ? "action" : "actions"}, but the page kept its own handler for ${kept.length} of them (${kept.join(", ")}), so foldspace ask would not test that code.`,
+      next: again(env),
+    };
+  }
+  return {
+    ok: true,
+    ...base,
+    actions: outcome.published,
+    ...(outcome.source ? { source: outcome.source } : {}),
+    note: RELOAD_NOTE,
+  };
+}