@foldspace_npm/harness 0.1.23 → 0.1.24

package/CLAUDE.md

@@ -123,6 +123,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 +401,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
 
@@ -486,7 +526,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/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
@@ -41,7 +41,9 @@ import {
   rankCandidates,
   readHint,
   refuseWriteFlags,
-  sameOriginPath,
+  gotoDestination,
+  pageCoverage,
+  uncoveredSiblings,
   summarizeJson,
   toHex,
 } from "../src/observe-core.mjs";
@@ -294,10 +296,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 +336,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 +358,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 +366,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) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@foldspace_npm/harness",
-  "version": "0.1.23",
+  "version": "0.1.24",
   "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/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/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("\\")) {

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/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 |