@foldspace_npm/harness 0.1.23 → 0.1.25

package/CLAUDE.md

@@ -78,9 +78,11 @@ current CLI contract — risk, prerequisites, effects, next step.
    one that creates data - say so instead.
 
 **Say when the test window is yours, and when it is theirs - on the page and
-in chat.** You and the human share one Chrome window. Before you start looking
-at the app or testing in it, run `npx foldspace badge working` (a bar across
-the top of the window says Foldspace is building here, leave it alone) and say
+in chat.** You and the human share one Chrome window. `observe` and `ask`
+raise the working pill by themselves for as long as they run, and drop it
+after. For the longer stretch - from the moment you start working on their
+window until it is their turn - run `npx foldspace badge working` (the pill at
+the foot of the window says Foldspace is building here, leave it alone) and say
 so in chat: *"I'm going to work in that Chrome window for a few minutes -
 please leave it alone until I tell you it's ready."* When it is their turn,
 `npx foldspace badge ready` takes the pill away (the small corner tag comes
@@ -123,6 +125,31 @@ Then agree the experience in the customer's words, before creating anything:
 *"Show my plan and credits needs one new action on your agent and one card to
 show it in. Sound right?"*
 
+## One product, several hosts
+
+Many products live on more than one host - `www.`, `analyze.`, `admin.` under
+one domain. `init` covers only the host it was given, so on the others the
+agent does not appear and every command refuses the window.
+
+- **Find out at the start.** Straight after the agent is live, `npx foldspace
+  observe menu` lists the hosts the page links to that belong to the same
+  product and that this project does not cover (`otherHosts`). `observe pages`
+  and the attach log say the same when the window lands on one.
+- **Widening is the human's yes.** Name the hosts you found and ask once:
+  *"Your product also lives on analyze.… and communicate.…. Add them so the
+  agent works there too?"* Then add the one pattern (`"*.example.com"`) to
+  `hosts` in `foldspace.dev.json`, `npm run inject`, and attach again.
+- **Then go there yourself.** `npx foldspace observe screen --goto
+  https://analyze.example.com/reports` opens a screen on any host the project
+  names. Do not ask the human to click a tile you can open.
+- **An action reads only the host it runs on** - that is the browser. Build
+  each experience on the host its data lives on, and use
+  `recipes/several-hosts`: an action asked from the wrong host answers
+  `wrong_page` instead of failing.
+- **The user and their conversations carry across hosts; the agent carrying
+  on after it navigated does not** (PLG-5962). `recipes/several-hosts` has the
+  workaround. It is a workaround: register it (**Rules**, 9).
+
 ## Find the call yourself
 
 Never guess `API_BASE`, `AUTH_SOURCE`, an endpoint or a schema. But guessing
@@ -376,6 +403,21 @@ Do not report success without all six:
 8. **Subagents investigate; they do not build.** A read-only investigation
    that returns a summary belongs in a subagent because it floods context.
    Never delegate a handler or a gate — a summary of a gate is not a gate.
+9. **A platform gap never stops the session - work round it, and register
+   it.** When something the experience needs looks missing or broken on
+   Foldspace's side - the SDK, the harness, the panel:
+   - **Check before you conclude.** `search_docs`, `npx foldspace help --json`
+     and the recipes first: it may be supported in a way you have not found.
+     Say "I did not find it", never "Foldspace does not support it".
+   - **Build the narrowest workaround that gives them a working experience.**
+     A prospect is never left stuck on a Foldspace limitation.
+   - **Register it, in two places.** A comment in the code where it lives -
+     what it works around, how you established that, and that it goes when the
+     fix ships - and a row under **Workarounds** in `docs/app-profile.md`:
+     what, why, where in the code, verified or assumed. An unregistered
+     workaround is copied as house style by whoever comes next, and hides the
+     gap from the people who can close it.
+   - **Tell the human in one sentence**, and carry on.
 
 ## Product defaults
 
@@ -447,10 +489,15 @@ Each of these cost a real build.
 - **A card matches the panel, not the page.** The card sits in the agent's
   panel - white by default (the agent's theme: `backgroundColor #FFFFFF`,
   `primaryColor` for accents; a `darkTheme` when the panel is dark, and the
-  panel follows the OS colour scheme, not the app's own toggle). `observe
-  styles` samples the page: a dark app gives a dark card in a white panel
-  (seen 2026-09-22). Start from the recipe palettes, put the agent's
-  `primaryColor` in `accent`, and take only font and radius from the page.
+  panel follows the OS colour scheme, not the app's own toggle). **Before the
+  first card, make the brand reference:** `npx foldspace observe styles
+  --write` samples the app's own accent, text, border, font and radius and
+  writes `agent/views/brand.ts` for the panel's white surface - every card
+  imports it, and the recipes' `brand.ts` files are placeholders for it. A
+  dark app keeps its accent and font; its light-on-dark text would vanish on
+  white, so that falls back to greys and the file says so. Record where the
+  values came from in the profile's Brand section. Never copy colours by eye
+  (seen 2026-09-22: a dark card in a white panel).
 - **Plain hex or rgba only.** The panel saves every card to the conversation
   history as an image drawn with html2canvas, which cannot read `oklch()`,
   `lab()` or `color-mix()`: one such value and the saved card is blank
@@ -486,7 +533,8 @@ version you have installed, and every one is built and run on each release.
 
 After the first experience → `who-is-the-user`. L2 → `find-by-name`, and
 `pick-from-a-list` when the user has to choose. The user's records on one
-card → `records-list`. Show one account on a card → `account-overview`. Upload a
+card → `records-list`. The product lives on several hosts → `several-hosts`.
+Show one account on a card → `account-overview`. Upload a
 CSV of contacts → `upload-contacts`. Save a note on a meeting →
 `update-meeting-notes`. Prepare for a meeting → `prepare-for-a-meeting`. The records that need
 attention, with reasons → `opportunities-at-risk`.

package/bin/ask.mjs

@@ -27,6 +27,7 @@ import {
 import { ATTACH_DAEMON_LOG_FILE } from "../src/attach-daemon.mjs";
 import { CdpPage, parseArgs, printJson, sleep } from "../src/cdp-client.mjs";
 import { recordEvent } from "../src/session-events.mjs";
+import { withWorkingBadge } from "../src/badge-auto.mjs";
 import { resolveProjectDir } from "../src/upgrade.mjs";
 
 const PANEL_ID = "eucera-agent-iframe";
@@ -300,11 +301,15 @@ async function main() {
 
   let attempts = 0;
   let turn;
-  do {
-    if (attempts > 0) await sleep(everyS * 1000);
-    turn = await askOnce();
-    attempts += 1;
-  } while (turn.sent && shouldRetry({ ...turn, attempts, retries }));
+  // The working pill is up while the question is typed and answered - the
+  // human must not type into the same composer - and down before the pictures.
+  await withWorkingBadge(page, async () => {
+    do {
+      if (attempts > 0) await sleep(everyS * 1000);
+      turn = await askOnce();
+      attempts += 1;
+    } while (turn.sent && shouldRetry({ ...turn, attempts, retries }));
+  });
 
   if (!turn.sent) {
     finish({ ok: false, question, reason: "Could not type into the composer.", attempts, url }, 1);

package/bin/attach.mjs

@@ -45,6 +45,7 @@ import {
 import { serializeDiagnostic } from "../src/diagnostics.mjs";
 import { recordEvent } from "../src/session-events.mjs";
 import { withoutStealingFocus } from "../src/keep-focus.mjs";
+import { pageCoverage } from "../src/observe-core.mjs";
 import {
   ERROR_CODES,
   createLifecycleResult,
@@ -809,6 +810,18 @@ async function prepare(ws, sessionId, url) {
   }
 }
 
+// A tab on a host of the same product that this project does not name: the
+// agent is not injected there, silently. Say so once per host, with the fix.
+const uncoveredHostsSeen = new Set();
+function noteUncoveredHost(url) {
+  if (!/^https?:/.test(String(url || ""))) return;
+  const coverage = pageCoverage(url, hostPatterns);
+  if (coverage.covered || !coverage.pattern || uncoveredHostsSeen.has(coverage.host)) return;
+  uncoveredHostsSeen.add(coverage.host);
+  console.log(`  [hosts] the window is on ${coverage.host}, which this project does not cover - the agent is not there.`);
+  console.log(`    Next: add "${coverage.pattern}" to "hosts" in foldspace.dev.json (with the human's yes), then inject and attach again.`);
+}
+
 async function onEvent(ws, msg) {
   const { method, params, sessionId } = msg;
 
@@ -819,6 +832,8 @@ async function onEvent(ws, msg) {
       sessionUrls.set(params.sessionId, t.url);
       if (hostMatches(t.url, hostPatterns)) {
         await prepare(ws, params.sessionId, t.url);
+      } else {
+        noteUncoveredHost(t.url);
       }
     } else {
       // Auto-attach pauses workers on start until the attaching client says go.
@@ -843,6 +858,7 @@ async function onEvent(ws, msg) {
       if (hostMatches(t.url, hostPatterns)) {
         await prepare(ws, sid, t.url);
       } else {
+        noteUncoveredHost(t.url);
         const state = prepared.get(sid);
         if (state) {
           await cleanupPreparedSession(ws, sid, state, { reload: false });

package/bin/observe.mjs

@@ -6,7 +6,7 @@
  *
  *   foldspace observe pages
  *   foldspace observe menu
- *   foldspace observe screen [--click "<label>"] [--goto /path] [--match "deal stage"] [--wait 4000]
+ *   foldspace observe screen [--click "<label>"] [--goto /path | https://<one of this project's hosts>/path] [--match "deal stage"] [--wait 4000]
  *   foldspace observe read <path-or-url>
  *   foldspace observe auth [--wait 5000]
  *   foldspace observe styles
@@ -23,6 +23,7 @@ import path from "node:path";
 
 import { CdpPage, parseArgs, printJson, readLaunchState, sleep } from "../src/cdp-client.mjs";
 import { withoutStealingFocus } from "../src/keep-focus.mjs";
+import { withWorkingBadge } from "../src/badge-auto.mjs";
 import {
   NAV_ITEM_SELECTOR,
   NAV_SCOPE_SELECTOR,
@@ -41,7 +42,10 @@ import {
   rankCandidates,
   readHint,
   refuseWriteFlags,
-  sameOriginPath,
+  brandFile,
+  gotoDestination,
+  pageCoverage,
+  uncoveredSiblings,
   summarizeJson,
   toHex,
 } from "../src/observe-core.mjs";
@@ -54,7 +58,7 @@ const SUBCOMMANDS = {
   screen: { values: ["click", "goto", "match", "wait"], flags: [] },
   read: { values: [], flags: [] },
   auth: { values: ["wait"], flags: [] },
-  styles: { values: [], flags: [] },
+  styles: { values: [], flags: ["write"] },
   screenshot: { values: ["out"], flags: [] },
   "wait-login": { values: ["timeout"], flags: [] },
 };
@@ -294,10 +298,33 @@ async function runPages() {
       `The inject Chrome is not answering on :${state.port}. It was closed; run \`npm run inject\` again.`,
     );
   }
-  const pages = targets
-    .filter((target) => target.type === "page" && !String(target.url).startsWith("devtools://"))
-    .map((target) => ({ url: printableUrl(target.url), title: target.title }));
-  return { ok: true, pages };
+  const real = targets.filter(
+    (target) => target.type === "page" && !String(target.url).startsWith("devtools://"),
+  );
+  const pages = real.map((target) => {
+    const coverage = /^https?:/.test(String(target.url)) ? pageCoverage(target.url, state.hosts) : { covered: true };
+    return {
+      url: printableUrl(target.url),
+      title: target.title,
+      ...(coverage.covered ? {} : { covered: false }),
+    };
+  });
+  // A tab on a host of the same product that this project does not name: every
+  // command would refuse it, and the agent would not appear there.
+  const off = real
+    .map((target) => pageCoverage(target.url, state.hosts))
+    .find((coverage) => !coverage.covered && coverage.pattern);
+  return {
+    ok: true,
+    pages,
+    ...(off
+      ? {
+          hostsHint:
+            `The window is on ${off.host}, which this project does not cover (hosts: ${state.hosts.join(", ")}). ` +
+            `If it is part of the product, add "${off.pattern}" to "hosts" in foldspace.dev.json - with the human's yes - then run inject and attach again.`,
+        }
+      : {}),
+  };
 }
 
 async function runMenu(page) {
@@ -311,11 +338,20 @@ async function runMenu(page) {
     items.push(publicItem(entry));
   }
   const url = await page.evaluate("return location.href;");
+  // Links that leave this host but stay in the product (analyze., admin. ...).
+  // Looked for across the whole page: product tiles are often not navigation.
+  const leaving = await page
+    .evaluate(
+      `return [...document.querySelectorAll("a[href]")].map((a) => a.href).filter((href) => /^https?:/.test(href)).slice(0, 400);`,
+    )
+    .catch(() => []);
+  const siblings = uncoveredSiblings(Array.isArray(leaving) ? leaving : [], url, page.info.hosts);
   return {
     ok: true,
     url: printableUrl(url),
     count: items.length,
     items,
+    ...(siblings ? { otherHosts: siblings.hosts, hostsHint: siblings.hint } : {}),
     ...(items.length ? {} : { note: "No visible navigation found. The app may still be loading, or showing a login page." }),
   };
 }
@@ -324,7 +360,7 @@ async function runScreen(page, flags) {
   const waitMs = numberFlag(flags.wait, 4000, "wait");
   const words = parseMatchWords(flags.match);
   const before = await page.evaluate("return location.href;");
-  const destination = flags.goto !== undefined ? sameOriginPath(flags.goto, before) : null;
+  const destination = flags.goto !== undefined ? gotoDestination(flags.goto, before, page.info.hosts) : null;
 
   await page.send("Network.enable");
   const network = recordNetwork(page);
@@ -332,7 +368,7 @@ async function runScreen(page, flags) {
 
   if (destination) {
     await withoutStealingFocus(() => page.send("Page.navigate", { url: destination.url }));
-    reached = { how: "goto", path: destination.path };
+    reached = { how: "goto", path: destination.path, ...(destination.host ? { host: destination.host } : {}) };
     if (flags.click !== undefined) await network.settle(Math.min(waitMs, 3000));
   }
   if (flags.click !== undefined) {
@@ -557,7 +593,7 @@ function lowerKeys(wire = {}, pageSet = {}) {
   return Object.fromEntries(Object.entries(wire).filter(([name]) => !known.has(name.toLowerCase())));
 }
 
-async function runStyles(page) {
+async function runStyles(page, flags = {}) {
   const raw = await page.evaluate(`
     ${VISIBLE_JS}
     const clear = (color) =>
@@ -653,7 +689,7 @@ async function runStyles(page) {
       radius: top(radii)[0] || null,
     };`);
   const { button } = raw;
-  return {
+  const report = {
     ok: true,
     url: printableUrl(raw.url),
     sampledFrom: "computed styles of visible elements",
@@ -675,6 +711,15 @@ async function runStyles(page) {
     boxRadius: raw.radius,
     body: { ...raw.body, color: toHex(raw.body.color) },
   };
+  if (!flags.write) return report;
+  // The brand reference every card imports. Written, not printed: values
+  // copied by hand drift, and re-sampling must be one command.
+  const target = path.join(projectDir, "agent", "views", "brand.ts");
+  const existed = fs.existsSync(target);
+  const { content, notes } = brandFile(report, { url: report.url, date: new Date().toISOString().slice(0, 10) });
+  fs.mkdirSync(path.dirname(target), { recursive: true });
+  fs.writeFileSync(target, content, "utf8");
+  return { ...report, wrote: path.relative(projectDir, target), replaced: existed, notes };
 }
 
 async function runScreenshot(page, flags) {
@@ -762,11 +807,14 @@ async function main() {
 
   const page = await CdpPage.open({ projectDir });
   try {
-    if (sub === "menu") return await runMenu(page);
-    if (sub === "screen") return await runScreen(page, flags);
-    if (sub === "read") return await runRead(page, flags, rest);
-    if (sub === "auth") return await runAuth(page, flags);
-    if (sub === "styles") return await runStyles(page);
+    // The working pill goes up while the harness drives the human's window,
+    // and comes down after - nobody has to remember it. Not for screenshot:
+    // the picture is for the human, and the pill would be in it.
+    if (sub === "menu") return await withWorkingBadge(page, () => runMenu(page));
+    if (sub === "screen") return await withWorkingBadge(page, () => runScreen(page, flags));
+    if (sub === "read") return await withWorkingBadge(page, () => runRead(page, flags, rest));
+    if (sub === "auth") return await withWorkingBadge(page, () => runAuth(page, flags));
+    if (sub === "styles") return await withWorkingBadge(page, () => runStyles(page, flags));
     return await runScreenshot(page, flags);
   } finally {
     page.close();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@foldspace_npm/harness",
-  "version": "0.1.23",
+  "version": "0.1.25",
   "description": "Build and verify portable Foldspace action artifacts against a live app.",
   "type": "module",
   "bin": {

package/recipes/INDEX.md

@@ -13,6 +13,7 @@ Read this whole table, then open the recipe closest to the outcome.
 | [`upload-contacts`](upload-contacts/) | **L4** | A CSV is previewed, then written only after the user chooses Import | An action with a card that waits for the user | 1 production build |
 | [`update-meeting-notes`](update-meeting-notes/) | **L4** | A note is saved on a meeting and the new note id comes back | A write. **No card** | 1 production build |
 | [`prepare-for-a-meeting`](prepare-for-a-meeting/) | **L2** | Meeting facts are gathered in code, then a task agent writes the summary | A data action plus a task agent. **No card** | 1 production build |
+| [`several-hosts`](several-hosts/) | any | The product lives on several hosts (`www.`, `analyze.`, `admin.` ...): an action asked from the wrong host says which page it needs, and the conversation carries on after the agent moves the user there. **The resume is a registered workaround** (PLG-5962) | Page set-up, plus a guard each action calls | 1 production build |
 | [`records-list`](records-list/) | **L2** | The user's records on one card: a row each with name, two facts and a number, matched to the agent's white panel. The model does not see the card | A view-only card. **No** `awaitUserInput` | 1 production build |
 | [`opportunities-at-risk`](opportunities-at-risk/) | **L2** | Every open opportunity the app flags as at risk, on one card: count, total, and why each one is at risk. The model does not see the card | A view-only card. **No** `awaitUserInput` | 1 production build |
 

package/recipes/bottom-bar/recipe.json

@@ -5,5 +5,9 @@
   "kind": "page-setup",
   "entry": "agent/bottomBar.ts",
   "outcome": "The agent's resting entry point is a bar at the bottom of the page whose starters change with the page the user is on",
-  "provenBy": 2
+  "provenBy": 2,
+  "setup": {
+    "import": "installBottomBar",
+    "from": "../bottomBar"
+  }
 }

package/recipes/several-hosts/README.md

@@ -0,0 +1,35 @@
+# One product, several hosts
+
+**The product lives on more than one host** — `www.`, `analyze.`, `communicate.`, `admin.` under one domain — **and the agent should work on all of them.**
+
+**Proven by 1 production build**, which met each part of this the hard way, one at a time.
+
+## Find out at the start
+
+`npx foldspace observe menu` names the hosts a page links to that belong to the same product and that this project does not cover (`otherHosts`, `hostsHint`). `init` covers only the host you gave it. Tell the human which hosts you found and ask for a yes before adding the pattern (`"*.example.com"`) to `hosts` in `foldspace.dev.json`; then `npm run inject` and attach again. After that you open screens on the other hosts yourself: `npx foldspace observe screen --goto https://analyze.example.com/reports`.
+
+## What this recipe gives
+
+| Piece | What it does |
+|---|---|
+| `wrongHost(tool)` | First line of an action. On the right host: `null`. On another: `{ status: "wrong_page", required_page, current_page }`, and no request is made |
+| `installResumeAcrossHosts()` | **A registered workaround.** After the agent moves the user to the right host, the conversation carries on there by itself |
+
+In Agent Studio, each action's instructions say: *on `wrong_page`, navigate to that tool's route, then call the action again.* Give each tool a navigation route with a full address.
+
+## Adapt it
+
+| File | Change |
+|---|---|
+| `agent/hosts.ts` → `TOOLS` | The product's tools and how to recognise each one's host (and path, if two tools share a host) |
+| `agent/actions/index.ts` | `installResumeAcrossHosts()` once, next to the registry |
+| each action | `const wrong = wrongHost("reports"); if (wrong) return { success: true, ...wrong };` before any request |
+| `docs/app-profile.md` → Workarounds | One row for the resume workaround: what, why, `agent/hosts.ts`, verified or assumed, "goes when PLG-5962 ships" |
+
+## What that build learned the hard way
+
+- **An action can only read the host it runs on.** Asked from Analyze, a Communicate action failed its first read in 150 ms. That is the browser, not the app.
+- **Who the user is, and their conversations, do carry across hosts** — Foldspace keeps the identity on the shared domain. What does not carry is the agent *continuing its turn* after it navigated: the note it leaves itself is kept per host, and the page that is leaving reports the navigation as finished.
+- **Reopening the conversation is not enough.** The first attempt restored the note on the new host; the right chat opened and nothing happened. It took a message to start the next turn — it shows as a user bubble, "Continue on this page."
+- **Ask the browser for the shared domain.** Counting dots gets `.co.uk` wrong.
+- **Remove it when the SDK carries on by itself.** This is Foldspace's to fix, not the customer's code to keep.

package/recipes/several-hosts/agent/hosts.ts

@@ -0,0 +1,146 @@
+// One product, several hosts (www. / analyze. / communicate. / admin. ...).
+//
+// Two facts decide everything here:
+//   1. An action runs inside the page, and a page may only read its own host.
+//      Asked from the wrong host, the request cannot succeed - so say which
+//      page is needed instead of failing (`wrongHost`).
+//   2. WORKAROUND - registered in docs/app-profile.md, goes when PLG-5962 ships.
+//      When the agent moves the user to another host, the SDK does not carry
+//      on with the turn: its resume note is kept per host, and the page that
+//      is leaving reports the navigation as done. The user and the
+//      conversation do carry over; only the "carry on" is lost. So the
+//      conversation id is handed across in a 60-second cookie on the domain
+//      the hosts share, and the new page reopens it and starts the next turn
+//      (`installResumeAcrossHosts`). Established on a live build, 2026-09-25.
+
+import { getAgent } from "./utils";
+
+/** ADAPT: the tools of this product and the host each one lives on. */
+export const TOOLS: Record<string, { label: string; onThisHost: (hostname: string, path: string) => boolean }> = {
+  reports: { label: "Reports", onThisHost: (hostname) => hostname.startsWith("analyze.") },
+  messages: { label: "Messages", onThisHost: (hostname) => hostname.startsWith("communicate.") },
+};
+
+export type WrongPage = { status: "wrong_page"; required_page: string; current_page: string };
+
+let resumeExpected = false;
+
+/**
+ * First line of every action that reads or writes one tool: null on the right
+ * host, otherwise the state to hand back - no request is made. The action's
+ * Studio instructions say: on `wrong_page`, navigate to that tool's route,
+ * then call the action again.
+ */
+export function wrongHost(tool: keyof typeof TOOLS): WrongPage | null {
+  const wanted = TOOLS[tool];
+  if (!wanted || wanted.onThisHost(window.location.hostname, window.location.pathname)) return null;
+  resumeExpected = true;
+  return { status: "wrong_page", required_page: wanted.label, current_page: window.location.hostname };
+}
+
+// ---------------------------------------------------------------- the workaround
+
+const SDK_NAV_KEY = "_eucera_nav"; // the SDK's own resume note (per host)
+const COOKIE = "fs_resume";
+const TTL_SECONDS = 60;
+export const RESUME_MESSAGE = "Continue on this page.";
+
+type Carried = { conversationId: string; origin: string; expiry: number };
+
+function readCookie(name: string): string | null {
+  const hit = document.cookie.split("; ").find((entry) => entry.startsWith(`${name}=`));
+  return hit ? hit.slice(name.length + 1) : null;
+}
+
+/**
+ * The widest domain the browser lets this page set a cookie on - the domain
+ * the product's hosts share. Asked of the browser, the way the SDK does it:
+ * guessing from the number of dots gets `.co.uk` wrong.
+ */
+export function sharedCookieDomain(): string | null {
+  const labels = window.location.hostname.split(".");
+  if (labels.length < 2) return null;
+  const probe = "fs_domain_probe";
+  for (let from = labels.length - 1; from >= 0; from -= 1) {
+    const domain = labels.slice(from).join(".");
+    document.cookie = `${probe}=1; domain=${domain}; path=/; max-age=30`;
+    if (readCookie(probe) === "1") {
+      document.cookie = `${probe}=; domain=${domain}; path=/; max-age=0`;
+      return domain;
+    }
+  }
+  return null;
+}
+
+/** The page that is leaving: hand the conversation id to the next host. */
+function carryOut(): void {
+  if (!resumeExpected) return;
+  try {
+    const raw = window.localStorage.getItem(SDK_NAV_KEY);
+    if (!raw) return;
+    const record = JSON.parse(raw) as { payload?: { conversationId?: string }; normalizedUrl?: string };
+    const conversationId = record.payload?.conversationId;
+    if (!conversationId || !record.normalizedUrl || !/^https?:\/\//.test(record.normalizedUrl)) return;
+    const target = new URL(record.normalizedUrl);
+    const domain = sharedCookieDomain();
+    // Only to another host of the same product - never off the shared domain.
+    if (!domain || target.origin === window.location.origin) return;
+    if (target.hostname !== domain && !target.hostname.endsWith(`.${domain}`)) return;
+    const carried: Carried = { conversationId, origin: target.origin, expiry: Date.now() + TTL_SECONDS * 1000 };
+    const secure = window.location.protocol === "https:" ? "; secure" : "";
+    document.cookie = `${COOKIE}=${encodeURIComponent(JSON.stringify(carried))}; domain=${domain}; path=/; max-age=${TTL_SECONDS}; samesite=lax${secure}`;
+  } catch (error) {
+    console.warn("[several-hosts] could not hand the conversation over", error);
+  }
+}
+
+function waitForAgent(timeoutMs: number): Promise<any | null> {
+  const started = Date.now();
+  return new Promise((resolve) => {
+    const tick = () => {
+      const agent = getAgent();
+      if (agent && typeof agent.message === "function") return resolve(agent);
+      if (Date.now() - started > timeoutMs) return resolve(null);
+      setTimeout(tick, 250);
+    };
+    tick();
+  });
+}
+
+/** The page that arrives: reopen the conversation and start its next turn. */
+async function bringIn(waitMs: number, settleMs: number): Promise<"resumed" | "nothing" | "no_agent"> {
+  try {
+    const value = readCookie(COOKIE);
+    if (!value) return "nothing";
+    const domain = sharedCookieDomain();
+    // Used once: whatever happens next, the note is gone.
+    if (domain) document.cookie = `${COOKIE}=; domain=${domain}; path=/; max-age=0`;
+    const carried = JSON.parse(decodeURIComponent(value)) as Carried;
+    if (carried.origin !== window.location.origin || carried.expiry < Date.now()) return "nothing";
+    const agent = await waitForAgent(waitMs);
+    if (!agent) {
+      console.warn("[several-hosts] the agent did not appear; the conversation was not resumed");
+      return "no_agent";
+    }
+    // The chat frame has to load before it can switch conversation and send.
+    await new Promise((resolve) => setTimeout(resolve, settleMs));
+    agent.selectConversation(carried.conversationId);
+    agent.message(RESUME_MESSAGE);
+    return "resumed";
+  } catch (error) {
+    console.warn("[several-hosts] could not resume the conversation", error);
+    return "nothing";
+  }
+}
+
+let installed: Promise<"resumed" | "nothing" | "no_agent"> | null = null;
+
+/** Call once from agent/actions/index.ts, next to the registry. Safe to call twice. */
+export function installResumeAcrossHosts({ waitMs = 20_000, settleMs = 2_500 } = {}): Promise<
+  "resumed" | "nothing" | "no_agent"
+> {
+  if (installed) return installed;
+  installed = bringIn(waitMs, settleMs);
+  window.addEventListener("pagehide", carryOut);
+  return installed;
+}

package/recipes/several-hosts/fixtures/nav-record.json

@@ -0,0 +1,5 @@
+{
+  "payload": { "conversationId": "conv_123", "actionName": "navigate" },
+  "normalizedUrl": "https://communicate.example-campus.net/applications/acme/test",
+  "expiry": 9999999999999
+}

package/recipes/several-hosts/recipe.json

@@ -0,0 +1,10 @@
+{
+  "title": "One product, several hosts",
+  "level": "any",
+  "family": "several-hosts",
+  "kind": "page-setup",
+  "entry": "agent/hosts.ts",
+  "setup": { "import": "installResumeAcrossHosts", "from": "../hosts" },
+  "outcome": "An action asked from the wrong host says so instead of failing, and the conversation carries on after the agent moves the user to the right host",
+  "provenBy": 1
+}

package/src/badge-auto.mjs

@@ -0,0 +1,42 @@
+// The working pill, raised by the harness itself while it drives the shared
+// window. `foldspace badge working` exists so the human knows when to leave the
+// window alone - and across a long session of observe and ask it was never
+// set, so both drove the same window (raised by the human, 2026-09-29). The
+// commands know when they are about to drive it, so they raise the pill for
+// as long as they run and put back whatever was there. A pill the agent set
+// on purpose is left alone.
+
+export const BADGE_KEY = "__foldspace_badge__";
+
+export async function readBadge(page) {
+  try {
+    const raw = await page.evaluate(`return sessionStorage.getItem(${JSON.stringify(BADGE_KEY)});`);
+    return raw ? JSON.parse(raw) : null;
+  } catch {
+    return null;
+  }
+}
+
+export async function writeBadge(page, payload) {
+  await page.evaluate(
+    `sessionStorage.setItem(${JSON.stringify(BADGE_KEY)}, ${JSON.stringify(JSON.stringify(payload))}); return true;`,
+  );
+}
+
+/** Run `action` with the working pill up, then restore what was there before. */
+export async function withWorkingBadge(page, action) {
+  const before = await readBadge(page);
+  if (before?.state === "working") return action(); // set on purpose: theirs to drop
+  let raised = false;
+  try {
+    await writeBadge(page, { state: "working", auto: true });
+    raised = true;
+  } catch {
+    // no badge script on this page (attach not running): nothing to raise
+  }
+  try {
+    return await action();
+  } finally {
+    if (raised) await writeBadge(page, before ?? { state: "label" }).catch(() => {});
+  }
+}

package/src/cdp-client.mjs

@@ -14,6 +14,7 @@ import path from "node:path";
 import { assertOwnedCdp, chromeProfileDir, ownershipErrorMessage } from "./cdp-ownership.mjs";
 import { resolveProjectDir } from "./upgrade.mjs";
 
+import { pageCoverage } from "./observe-core.mjs";
 export const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
 
 /** Where inject recorded the Chrome it launched. Never guess a port. */
@@ -76,8 +77,12 @@ export function choosePage(pages, hosts = []) {
   const match = real.find((page) => hostMatches(page.url, hosts));
   if (match) return match;
   if (hosts.length) {
+    const off = real.map((page) => pageCoverage(page.url, hosts)).find((coverage) => coverage.pattern);
     throw new Error(
-      `The test window has no tab on ${hosts.join(", ")}. Open the product there (or finish signing in), then try again.`,
+      off
+        ? `The test window is on ${off.host}, which this project does not cover (hosts: ${hosts.join(", ")}). ` +
+            `If it is part of the product, add "${off.pattern}" to "hosts" in foldspace.dev.json - with the human's yes - then run inject and attach again.`
+        : `The test window has no tab on ${hosts.join(", ")}. Open the product there (or finish signing in), then try again.`,
     );
   }
   return real[0];

package/src/cli-registry.mjs

@@ -306,10 +306,11 @@ export const CLI_COMMANDS = Object.freeze([
     ],
     options: [
       value("--click", "label", "screen: reach the screen by a navigation label, as a person would"),
-      value("--goto", "path", "screen: a same-origin path"),
+      value("--goto", "path", "screen: a path on this host, or a full https address on a host this project names"),
       value("--match", "words", "screen: rank the requests seen by these words"),
       value("--wait", "ms", "screen/auth: how long to keep listening"),
       value("--out", "file", "screenshot: where to save the PNG"),
+      flag("--write", "styles: write agent/views/brand.ts - the brand reference every card imports"),
       value("--timeout", "seconds", "wait-login: give up after this long", { default: "600" }),
     ],
     prerequisites: ["foldspace inject has opened the test window"],
@@ -317,6 +318,7 @@ export const CLI_COMMANDS = Object.freeze([
       "GET only. Never submits a form; clicks navigation elements only",
       "Prints names, shapes and counts - never values, tokens or cookies",
       "Works while foldspace attach is running",
+      "Raises the working pill on the window while it runs (not for screenshot), and drops it after",
     ],
     next: ["Record what you established in docs/app-profile.md", "Write the handler"],
   }),

package/src/observe-core.mjs

@@ -43,6 +43,63 @@ export function isSameSite(url, pageUrl, hosts = []) {
   }
 }
 
+/**
+ * One product often lives on several hosts (www., analyze., 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
+ * this only ever SUGGESTS: widening `hosts` is the human's decision.
+ */
+export function uncoveredSiblings(urls, pageUrl, hosts = []) {
+  let pageHost;
+  try {
+    pageHost = new URL(pageUrl).hostname.toLowerCase();
+  } catch {
+    return null;
+  }
+  const site = siteOf(pageHost);
+  if (!site.includes(".") || /^[\d.]+$/.test(site)) return null;
+  const counts = new Map();
+  for (const url of urls) {
+    let host;
+    try {
+      const parsed = new URL(url);
+      if (!/^https?:$/.test(parsed.protocol)) continue;
+      host = parsed.hostname.toLowerCase();
+    } catch {
+      continue;
+    }
+    if (host === pageHost || siteOf(host) !== site || hostMatchesAny(host, hosts)) continue;
+    counts.set(host, (counts.get(host) || 0) + 1);
+  }
+  if (!counts.size) return null;
+  const found = [...counts].map(([host, seen]) => ({ host, seen })).sort((a, b) => b.seen - a.seen || a.host.localeCompare(b.host));
+  const pattern = `*.${site}`;
+  return {
+    hosts: found.slice(0, 12),
+    pattern,
+    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.`,
+  };
+}
+
+/** Whether the page the window is on is one this project works on; if not, what would make it one. */
+export function pageCoverage(pageUrl, hosts = []) {
+  let host;
+  try {
+    host = new URL(pageUrl).hostname.toLowerCase();
+  } catch {
+    return { covered: false, host: null, pattern: null };
+  }
+  if (!hosts.length || hostMatchesAny(host, hosts)) return { covered: true, host, pattern: null };
+  const shared = hosts
+    .map((pattern) => String(pattern).toLowerCase().replace(/^\*\./, ""))
+    .some((bare) => siteOf(bare) === siteOf(host));
+  return { covered: false, host, pattern: shared ? `*.${siteOf(host)}` : null };
+}
+
 // ------------------------------------------------------------ navigation
 
 export const NAV_SCOPE_SELECTOR =
@@ -50,7 +107,45 @@ export const NAV_SCOPE_SELECTOR =
 export const NAV_ITEM_SELECTOR =
   "a[href], button, [role=menuitem], [role=tab], [role=link]";
 
-/** `--goto` accepts a path on the page's own origin and nothing else. */
+/**
+ * Where `--goto` may go: a path on the page's own origin, or a full https
+ * address on a host this project names. Nowhere else - the window carries the
+ * human's session. The path is screened either way.
+ */
+export function gotoDestination(input, pageUrl, hosts = []) {
+  const raw = String(input ?? "").trim();
+  if (!/^https?:\/\//i.test(raw)) return { ...sameOriginPath(raw, pageUrl), host: null };
+  let target;
+  try {
+    target = new URL(raw);
+  } catch {
+    throw new Error(`--goto: "${raw}" is not an address.`);
+  }
+  if (target.protocol !== "https:" && new URL(pageUrl).protocol === "https:") {
+    throw new Error("--goto must use https.");
+  }
+  if (target.username || target.password) throw new Error("--goto takes no credentials in the address.");
+  const page = new URL(pageUrl);
+  const sameOrigin = target.origin === page.origin;
+  if (!sameOrigin && !hostMatchesAny(target.hostname, hosts)) {
+    const coverage = pageCoverage(target.href, 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.`
+          : "observe only opens screens of the product this project is for."),
+    );
+  }
+  const refused = pathRefusal(target.pathname);
+  if (refused) throw new Error(`--goto: ${refused}`);
+  return {
+    url: target.href,
+    path: target.pathname + target.search + target.hash,
+    host: sameOrigin ? null : target.hostname,
+  };
+}
+
+/** `--goto` with a path: the page's own origin and nothing else. */
 export function sameOriginPath(input, pageUrl) {
   const raw = String(input ?? "").trim();
   if (!raw.startsWith("/") || raw.startsWith("//") || raw.includes("\\")) {
@@ -610,8 +705,46 @@ export function looksLoggedIn({ url, hasPasswordField = false, hosts = [] }) {
 // ---------------------------------------------------------------- styles
 
 /** 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.
+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;
+  const number = (value, scale = 1) => (value.endsWith("%") ? (Number(value.slice(0, -1)) / 100) * scale : Number(value));
+  const L = number(match[2]);
+  let a;
+  let b;
+  if (match[1].toLowerCase() === "oklch") {
+    const C = number(match[3], 0.4);
+    const H = (Number(match[4]) * Math.PI) / 180;
+    a = C * Math.cos(H);
+    b = C * Math.sin(H);
+  } else {
+    a = number(match[3], 0.4);
+    b = number(match[4], 0.4);
+  }
+  const l = (L + 0.3963377774 * a + 0.2158037573 * b) ** 3;
+  const m = (L - 0.1055613458 * a - 0.0638541728 * b) ** 3;
+  const s = (L - 0.0894841775 * a - 1.291485548 * b) ** 3;
+  const linear = [
+    4.0767416621 * l - 3.3077115913 * m + 0.2309699292 * s,
+    -1.2684380046 * l + 2.6097574011 * m - 0.3413193965 * s,
+    -0.0041960863 * l - 0.7034186147 * m + 1.707614701 * s,
+  ];
+  const channel = (c) => {
+    const v = c <= 0.0031308 ? 12.92 * c : 1.055 * Math.max(c, 0) ** (1 / 2.4) - 0.055;
+    return Math.max(0, Math.min(255, Math.round(v * 255))).toString(16).padStart(2, "0");
+  };
+  const hex = `#${linear.map(channel).join("")}`;
+  const alpha = match[5] === undefined ? 1 : number(match[5]);
+  return alpha >= 1 ? hex : `${hex}${Math.round(alpha * 255).toString(16).padStart(2, "0")}`;
+}
+
 export function toHex(cssColor) {
   const text = String(cssColor || "").trim();
+  const ok = okToHex(text);
+  if (ok) return ok;
   const match = /^rgba?\(\s*([\d.]+)[\s,]+([\d.]+)[\s,]+([\d.]+)(?:\s*[,/]\s*([\d.]+%?))?\s*\)$/i.exec(text);
   if (!match) return text || null;
   const channel = (value) =>
@@ -625,3 +758,69 @@ export function toHex(cssColor) {
   const hex = `#${channel(match[1])}${channel(match[2])}${channel(match[3])}`;
   return alpha >= 1 ? hex : `${hex}${channel(alpha * 255)}`;
 }
+
+// ------------------------------------------------------------ brand file
+
+function luminance(hex) {
+  const m = /^#([0-9a-f]{2})([0-9a-f]{2})([0-9a-f]{2})/i.exec(String(hex || ""));
+  if (!m) return null;
+  const [r, g, b] = [m[1], m[2], m[3]].map((part) => parseInt(part, 16) / 255);
+  return 0.2126 * r + 0.7152 * g + 0.0722 * b;
+}
+
+const isHex = (value) => /^#[0-9a-f]{6}([0-9a-f]{2})?$/i.test(String(value || ""));
+
+/**
+ * `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
+ * would vanish on white, so those fall back to neutral greys and say so.
+ */
+export function brandFile(styles, { url, date, agentPrimary } = {}) {
+  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}`);
+    return fallback;
+  };
+  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");
+  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 font = String(styles.fontFamily || "").replace(/["'\\]/g, "").trim() || "Roboto, sans-serif";
+  const radius = /^\d+(\.\d+)?px$/.test(String(styles.boxRadius || "")) ? styles.boxRadius : "8px";
+  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().",
+    `// 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}",`,
+    "} as const;",
+    "",
+  ];
+  return { content: lines.join("\n"), notes, values: { text, muted, border, accent, accentText, font, radius } };
+}

package/src/runtime/render.ts

@@ -14,7 +14,14 @@ import type { ApiFailure } from "./http";
 export type ViewHost = HTMLElement | { container: HTMLElement };
 
 function containerOf(host: ViewHost): HTMLElement {
-  return host instanceof HTMLElement ? host : host.container;
+  // Not `instanceof HTMLElement`: the host Foldspace passes belongs to the
+  // agent panel's frame, and an element from another frame is not an instance
+  // of THIS frame's HTMLElement. The check was false for every real host, so
+  // `host.container` (undefined) was used and every failure card crashed
+  // instead of drawing (seen on a live build, 2026-09-24).
+  const wrapped = (host as { container?: HTMLElement }).container;
+  if (wrapped && typeof wrapped.appendChild === "function") return wrapped;
+  return host as HTMLElement;
 }
 
 function el(tag: string, className: string, text?: string): HTMLElement {

package/src/upgrade.mjs

@@ -307,7 +307,12 @@ export function checkForUpdate(projectDir, options = {}) {
   } else if (skipped) {
     status = "check_skipped";
   } else {
-    const cached = options.cache === false ? null : readCache(projectDir, now);
+    // `fresh` asks the registry whatever was remembered, and still writes the
+    // new answer down. `foldspace upgrade` is always fresh: someone asking to
+    // upgrade minutes after a release was told the previous version was the
+    // latest, for up to 12 hours (seen 2026-09-28).
+    const cached =
+      options.cache === false || options.fresh === true ? null : readCache(projectDir, now);
     const cachedDeprecation =
       cached?.deprecation?.version === running ? cached.deprecation : null;
     if (cached?.latest && cachedDeprecation) {
@@ -445,7 +450,7 @@ export async function runUpgrade(argv, options = {}) {
     );
   }
 
-  const report = checkForUpdate(projectDir, options);
+  const report = checkForUpdate(projectDir, { ...options, fresh: options.fresh ?? true });
 
   if (parsed.checkOnly || (!parsed.yes && !isInteractive(options) && !parsed.refreshInstructions)) {
     return report;

package/templates/agent-starter/docs/app-profile.md

@@ -101,6 +101,16 @@ across.
 
 Listed so the next person knows they exist **and knows they are unverified**.
 
+## Workarounds
+
+Anything built here because Foldspace - the SDK, the harness, the panel - did
+not do it, or did not seem to. One row each, and the same note as a comment in
+the code. "Assumed" means you did not find support for it; it may exist.
+
+| What it does | What it works around | Where in the code | Verified or assumed | Goes when |
+|---|---|---|---|---|
+| | | | | |
+
 ## Failures observed
 
 | Call | Result | What it means |