@foldspace_npm/harness 0.1.22 → 0.1.24

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.22",
+  "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/recipes/who-is-the-user/README.md

@@ -1,8 +1,9 @@
 # Who is the user — L0
 
-L0 is not "the agent appears". It is the agent appearing **and** Foldspace
-knowing who it is talking to. Without `identify`, every conversation, every
-analytics row and every segment is anonymous.
+L0 is the agent appearing. This recipe comes right after the human has tried
+the first experience: Foldspace learns who it is talking to, so conversations,
+analytics rows and segments stop being anonymous, and the agent has real-time
+context about the user.
 
 **Proven by 4 production builds**, which found the identity in three different
 places — so look before you assume:

package/src/ask-core.mjs

@@ -0,0 +1,195 @@
+// Pure helpers behind `foldspace ask`: deciding when the assistant has finished
+// replying, reading what attach logged about the handlers, and deciding whether
+// to ask again. No I/O here, so every judgement call is unit-tested.
+
+/** Collapse whitespace the way the panel text is collapsed before comparing. */
+export function squash(text) {
+  return String(text ?? "")
+    .replace(/\s+/g, " ")
+    .trim();
+}
+
+// The reply is "whatever follows the question in the panel". A short prefix
+// survives truncation and the panel re-wrapping a long question bubble.
+export function anchorFor(question) {
+  return squash(question).slice(0, 24);
+}
+
+/** Text after the LAST occurrence of the question: earlier turns are ignored. */
+export function replyAfter(panelText, question) {
+  const panel = squash(panelText);
+  const anchor = anchorFor(question);
+  if (!anchor) return "";
+  const at = panel.lastIndexOf(anchor);
+  if (at < 0) return "";
+  const rest = panel.slice(at);
+  // Drop the whole echoed question when it is there, else just the anchor.
+  const full = squash(question);
+  const tail = rest.startsWith(full) ? rest.slice(full.length) : rest.slice(anchor.length);
+  return stripPanelChrome(tail);
+}
+
+// The panel's footer sits after the last message in document order, so it
+// would otherwise be read as the end of every reply.
+export function stripPanelChrome(text) {
+  return squash(String(text ?? "").replace(/[\u200b-\u200d\ufeff]/g, ""))
+    .replace(/\s*Powered by Foldspace(?:\.ai)?\s*$/i, "")
+    .trim();
+}
+
+const PENDING_PATTERN =
+  /thinking|working on it|one moment|generating|ready to go|\.\.\.\s*$|…\s*$/i;
+
+/** A reply whose tail is a progress phrase is still being written. */
+export function looksPending(reply) {
+  return PENDING_PATTERN.test(squash(reply).slice(-60));
+}
+
+/**
+ * Feed one observation per poll. Settled means a real reply that stopped
+ * changing: the same text and the same cards on `stableNeeded` consecutive
+ * polls after the first sighting, and not a progress phrase. A streaming reply
+ * and a card that paints late both reset the count.
+ */
+export function createSettleTracker({ stableNeeded = 2, minChars = 2 } = {}) {
+  let last = null;
+  let stable = 0;
+  return {
+    observe({ reply = "", cards = [] } = {}) {
+      const snapshot = `${reply}|${cards.join("|")}`;
+      const answered = (reply.length >= minChars || cards.some(Boolean)) && !looksPending(reply);
+      if (answered && snapshot === last) stable += 1;
+      else stable = 0;
+      last = snapshot;
+      return { settled: stable >= stableNeeded, stable };
+    },
+  };
+}
+
+const ACTION_LINE = /\[actions\]\s+([\w-]+):(execute|render)(?:\s+(\S+))?\s+(started|succeeded|failed)\b/;
+
+/** One `[actions] local-handler:execute my_action succeeded 12ms` line. */
+export function parseActionLine(line) {
+  const match = ACTION_LINE.exec(String(line ?? ""));
+  if (!match) return null;
+  return {
+    source: match[1],
+    phase: match[2],
+    actionName: match[3] || null,
+    status: match[4],
+  };
+}
+
+function phaseOutcome(events, phase) {
+  const mine = events.filter((event) => event.phase === phase);
+  // A failure anywhere in the turn is the headline, even if a later call passed.
+  if (mine.some((event) => event.status === "failed")) return "failed";
+  if (mine.some((event) => event.status === "succeeded")) return "succeeded";
+  // "started" with no end yet: the handler fired but has not reported.
+  return mine.length ? "started" : "absent";
+}
+
+/**
+ * Summarise the attach log text written since the ask began.
+ * `logText` of null/"" (no daemon log) reads as all "absent".
+ */
+export function summarizeHandlerLog(logText) {
+  // The daemon log indents these and may prefix them; keep from the tag onward.
+  const lines = String(logText ?? "")
+    .split("\n")
+    .filter((line) => parseActionLine(line))
+    .map((line) => line.slice(line.indexOf("[actions]")).trim());
+  const events = lines.map(parseActionLine);
+  const actions = [...new Set(events.map((event) => event.actionName).filter(Boolean))];
+  return {
+    execute: phaseOutcome(events, "execute"),
+    render: phaseOutcome(events, "render"),
+    actions,
+    lines: lines.slice(-20),
+  };
+}
+
+export function actionFired(handler, hasCard) {
+  return Boolean(hasCard) || handler?.execute !== "absent" || handler?.render !== "absent";
+}
+
+/**
+ * Re-ask only for publish lag: the assistant answered from knowledge because
+ * the platform has not picked the new action up yet. A handler that ran and
+ * FAILED is a bug to read, not something another ask will fix.
+ */
+export function shouldRetry({ handler, hasCard, attempts, retries }) {
+  if (!(retries > 0) || attempts > retries) return false;
+  return !actionFired(handler, hasCard);
+}
+
+/** Positive number from a flag, else the default; never NaN into a sleep. */
+export function numberFlag(value, fallback) {
+  const parsed = Number(value);
+  return Number.isFinite(parsed) && parsed >= 0 && value !== true && value !== undefined
+    ? parsed
+    : fallback;
+}
+
+// ---- `foldspace run`: describe what a handler returned without printing it ----
+
+function typeOf(value) {
+  if (value === null) return "null";
+  if (Array.isArray(value)) return "array";
+  return typeof value;
+}
+
+// Breadth-first so `items` wins over `meta.pages[0].items`; the first array of
+// records is what a card will draw.
+function findRows(value, maxDepth = 3) {
+  const queue = [{ node: value, path: "$", depth: 0 }];
+  while (queue.length) {
+    const { node, path, depth } = queue.shift();
+    if (Array.isArray(node)) return { path, count: node.length, first: node[0] };
+    if (!node || typeof node !== "object" || depth >= maxDepth) continue;
+    for (const [key, child] of Object.entries(node)) {
+      queue.push({ node: child, path: path === "$" ? key : `${path}.${key}`, depth: depth + 1 });
+    }
+  }
+  return null;
+}
+
+const short = (value) => (typeof value === "string" ? value.slice(0, 200) : null);
+
+/**
+ * The SHAPE of a handler's return value: enough to tell "it answered with 12
+ * rows of {id,name}" from "it returned a clean failure", and no customer data.
+ */
+export function describeReturn(value) {
+  const type = typeOf(value);
+  const isObject = type === "object";
+  const rows = findRows(value);
+  const firstRow = rows?.first;
+  return {
+    type,
+    keys: isObject ? Object.keys(value).slice(0, 50) : [],
+    okFlag: isObject && typeof value.ok === "boolean" ? value.ok : null,
+    reason: isObject ? short(value.reason) : null,
+    error: isObject ? short(value.error) : null,
+    rows: rows ? { path: rows.path, count: rows.count } : null,
+    fieldNames:
+      firstRow && typeof firstRow === "object" && !Array.isArray(firstRow)
+        ? Object.keys(firstRow).slice(0, 50)
+        : [],
+  };
+}
+
+/**
+ * runAction only executes data handlers. For an action with `render` the SDK
+ * rejects with `Action "x" is a render action and cannot be executed silently`
+ * (it needs a conversation to draw into); recognise that so the caller is
+ * pointed at `foldspace ask` instead of a stack trace.
+ */
+export function refusedAsNotSilent(message) {
+  return typeof message === "string" && /render action|executed silently/i.test(message);
+}
+
+/** `Action "x" not found`: the key is not in the bundle the page loaded. */
+export function refusedAsUnknown(message) {
+  return typeof message === "string" && /\bnot found\b/i.test(message);
+}

package/src/attach-daemon.mjs

@@ -8,6 +8,8 @@ export const ATTACH_DAEMON_LOG_FILE = "attach-daemon.log";
 const CONTROL_FLAGS = ["--daemon", "--status", "--stop"];
 const LIFECYCLE_PATTERN =
   /\[lifecycle\] inspect_registration:(registration_ok|registration_mismatch)/g;
+// The page was refused before registration: no SDK on it, or someone else's.
+const REJECTED_PATTERN = /\[lifecycle\] prepare_page:rejected (SDK_NOT_FOUND|REGISTRATION_MISMATCH)/g;
 
 export function projectRoot(env = process.env, cwd = process.cwd()) {
   return env.FOLDSPACE_PROJECT_DIR || cwd;
@@ -59,6 +61,26 @@ export function parseRegistrationLifecycle(logText) {
   return last;
 }
 
+/** The last page rejection in the log, or null. */
+export function parseRejection(logText) {
+  let last = null;
+  for (const match of String(logText ?? "").matchAll(REJECTED_PATTERN)) {
+    last = { code: match[1] };
+  }
+  return last;
+}
+
+/** What to run next, in one line, when attach refused the page. */
+export function rejectionAdvice(code) {
+  if (code === "SDK_NOT_FOUND") {
+    return "The page has no Foldspace code. Run: npx foldspace attach --bootstrap --daemon";
+  }
+  if (code === "REGISTRATION_MISMATCH") {
+    return "The page carries a different Foldspace agent. Run: npx foldspace attach --replace --daemon";
+  }
+  return null;
+}
+
 export function readDaemonState(root) {
   const { stateFile } = daemonPaths(root);
   try {
@@ -107,6 +129,11 @@ export async function waitForRegistration({
     }
     const registration = parseRegistrationLifecycle(text);
     if (registration) return registration;
+    const rejection = parseRejection(text);
+    if (rejection) {
+      const advice = rejectionAdvice(rejection.code);
+      throw new Error(advice ? `${advice} (${rejection.code}; log: ${logFile})` : `Attach refused the page: ${rejection.code}. Check ${logFile}`);
+    }
     if (!isAlive(pid)) {
       throw new Error(
         `Attach daemon exited before inspect_registration. Check ${logFile}`,

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

@@ -320,6 +320,35 @@ export const CLI_COMMANDS = Object.freeze([
     ],
     next: ["Record what you established in docs/app-profile.md", "Write the handler"],
   }),
+  Object.freeze({
+    name: "ask",
+    entry: "ask.mjs",
+    group: "verify",
+    summary: "Ask the visible agent a question through its panel; get the reply, card text, what the handlers did, and a screenshot",
+    usage: "foldspace ask \"<question>\" [--retry <n>] [--every <s>] [--timeout <s>]",
+    risk: "browser-session",
+    environment: "local-chrome",
+    environmentVariables: ["FOLDSPACE_PROJECT_DIR", "CDP_PORT"],
+    capabilities: ["browser.cdp", "page.evaluate"],
+    positionals: [
+      Object.freeze({ name: "question", required: true, description: "What an end user would type" }),
+    ],
+    options: [
+      value("--retry", "n", "Ask again when no action fired (a newly published action can take a minute to be picked up)", { default: "0" }),
+      value("--every", "seconds", "Pause between retries", { default: "20" }),
+      value("--timeout", "seconds", "Wait this long for a reply", { default: "90" }),
+    ],
+    prerequisites: ["foldspace attach is running, so the handlers on the page are this project's build"],
+    effects: [
+      "Types into the panel the way a person does; touches nothing inside the SDK",
+      "Creates a real conversation: it appears in the customer's Foldspace dashboard (test traffic only under attach --test-mode)",
+      "Saves panel and full-page screenshots under .foldspace-dev/ask/",
+    ],
+    next: [
+      "Read reply, cards and handler.execute / handler.render; look at the screenshot",
+      "Only then: foldspace badge ready, and invite the customer to try it",
+    ],
+  }),
   Object.freeze({
     name: "badge",
     entry: "badge.mjs",
@@ -447,7 +476,7 @@ export function createCliRegistry({ packageName, packageVersion, env = process.e
     },
     protocolVersion: HARNESS_PROTOCOL_VERSION,
     workflow: ["init", "build", "inject", "attach"],
-    verifyWorkflow: ["observe"],
+    verifyWorkflow: ["observe", "ask"],
     publishWorkflow: showInternal ? ["deploy"] : [],
     capabilities: CAPABILITY_CATALOGUE.map(([id, description]) => ({
       id,