@foldspace_npm/harness 0.1.22 → 0.1.24

package/CLAUDE.md

@@ -43,7 +43,7 @@ current CLI contract — risk, prerequisites, effects, next step.
 
 | Level | Reached when |
 |---|---|
-| **L0 · agent live** | injected, visible on the page, `identify` fired |
+| **L0 · agent live** | injected, visible on the page |
 | **L1 · read settings** | the user's own account, plan or settings in a widget, showing their real values |
 | **L2 · look up entities** | a search from the user's own words, showing rows |
 
@@ -52,7 +52,9 @@ current CLI contract — risk, prerequisites, effects, next step.
    window opened at <Product>'s login. Please log in there - I'll notice when
    you're in."* Then `npx foldspace observe wait-login`: it returns the moment
    they are in, so nobody has to type "I've logged in". Then
-   `npx foldspace attach --daemon`. An empty registry is valid. L0 is
+   `npx foldspace attach --daemon` - and if it answers that the page has no
+   Foldspace code, `npx foldspace attach --bootstrap --daemon` (an app that
+   never had Foldspace). An empty registry is valid. L0 is
    `registration_ok` with the agent visible on their page: take
    `npx foldspace observe screenshot`, send them the image, and tell them to
    look at it and say hello to it. **From here on the agent stays on their
@@ -86,7 +88,27 @@ back) and in chat you say what to try. No bar for their turn: they may type
 whatever, whenever; the pill only ever asks them to wait. `foldspace badge label` puts the small
 corner tag back; `off` removes it, for a screenshot they will share.
 
-Navigation, uploads, extraction and anything that writes are a later session.
+**After they have tried it, offer the second wave - one choice, recommended
+first, not four questions.** Once you have handed over (`badge ready`) and the
+human has asked the agent the question:
+
+1. **Starters.** The sign-up starters point at actions the agent does not have
+   (clicking one answers "that action isn't available"): replace them with the
+   question this experience answers. `set_conversation_starters` replaces the
+   whole set - send the full list. Their account, so their yes.
+2. **The bottom bar** - `recipes/bottom-bar`: the agent's resting place at the
+   foot of the page, with starters that change per screen. Ships in this
+   project's start-up code; nothing in their source changes.
+3. **Tell Foldspace who the user is** - `recipes/who-is-the-user`: from then on
+   their conversations and analytics stop being anonymous, and the agent has
+   real-time context about who it is talking to. One line in chat, no question.
+4. **A second experience** - and, once a card shows records, navigation to a
+   record's page.
+
+Not before the first experience: nothing about it needs any of these, and it
+is silent work before the human has seen anything.
+
+Uploads, extraction and anything that writes are a later session.
 
 ### Ask as a choice, and ask almost nothing
 
@@ -101,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
@@ -111,9 +158,13 @@ and asking are not the only options — **observing is, and it comes first**:
 2. **You look - once they have chosen an experience - with `foldspace
    observe`.** It reads the test window they signed in to, it is read-only by
    construction, and it works **while the agent stays attached**: do not
-   `attach --stop` to look. Write no browser-driving script of your own, and do
-   not reach for a separate DevTools server - one launched on its own opens a
-   different, signed-out Chrome and can never see the window they logged in to.
+   `attach --stop` to look. Write no browser-driving script of your own - not
+   to look at the app, and not to talk to the agent: a socket to Chrome's debug
+   port that evaluates `agent.message(...)` in a signed-in session is the shape
+   of an attack and gets refused. `foldspace observe` looks; `foldspace ask`
+   talks. Do not reach for a separate DevTools server either - one launched on
+   its own opens a different, signed-out Chrome and can never see the window
+   they logged in to.
 
    ```bash
    npx foldspace observe menu                      # the product's own screens, by label and path
@@ -290,8 +341,8 @@ Do not report success without all six:
 4. The browser reports `inspect_registration:registration_ok`, and for a named
    action the captured registry includes it.
 5. The action behaves against the real workflow: `[actions]
-   local-handler:execute` in the attach log after the human exercises the
-   visible agent. A widget also needs `local-handler:render` from a real chat
+   local-handler:execute` in the attach log after `foldspace ask` (or the
+   human) exercises the visible agent. A widget also needs `local-handler:render` from a real chat
    turn — not a hand-built `render()` call. `runAction` refuses render actions
    and driving `render()` yourself never runs `execute()`.
 6. Browser evidence came from the live target, not hand-authored examples.
@@ -320,12 +371,21 @@ Do not report success without all six:
    MCP (`search_docs`, `fetch_page`) before asserting how the platform behaves;
    cite the page, or say plainly that the docs do not cover it and write down
    what you learned.
-4. **Test through the agent, then let them.** In a first session, talk to the
-   agent yourself to prove an experience - type the real question into its
-   panel in the test window and read the reply - and only then invite the
-   customer to try it. Those conversations appear in their Foldspace dashboard,
-   and that is wanted: seeing their own conversations recorded is part of what
-   they came to see. Never pass `--test-mode` in a first session.
+4. **Test through the agent, then let them.** In a first session, prove an
+   experience yourself before the customer sees it: once the action is
+   published and registered, `npx foldspace ask "<the question>" --retry 2`
+   types it into the agent's panel in the test window the way a person would,
+   and reports the reply, the card's text, whether `execute` and `render` ran
+   (from the attach log) and a screenshot. A reply with no action fired is
+   publish lag or a wrong key - `--retry` covers the lag. Look at the
+   screenshot. Only then the ready pill and the invitation to try it; never
+   hand the first test to the customer. **Ask only what reads.** A question
+   that makes the agent create, send, change or delete something is you
+   writing in their product: ask it only in an environment the human has
+   named as a test one, or let them type it. Those conversations appear in their
+   Foldspace dashboard, and that is wanted: seeing their own conversations
+   recorded is part of what they came to see. Never pass `--test-mode` in a
+   first session.
 5. **Test mode is for an agent that already has real users.** Then `attach
    --test-mode` keeps your conversations out of their data. It is not a safety
    net: publishing still changes the live agent. Working on an agent in
@@ -341,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
 
@@ -356,29 +431,24 @@ Lint catches some of these in handler code; Agent Studio copy is on you.
 Three layers: built-in defaults, then Agent Studio, then code - **and code
 wins**. <https://docs.foldspace.ai/customize/configuration/>
 
-- **Agent-wide conversation starters you can set yourself**, through the
-  Foldspace tools, and they carry over to the customer's real site. Once the
-  first action works, offer one starter that asks its question, so they can
-  click instead of type. `set_conversation_starters` **replaces the whole set
-  and clears whatever you leave out**: call `list_conversation_starters` first
-  and send back the full list with your one addition. It changes their
-  Foldspace account, so it needs their yes.
-- **Page-specific starters and the bottom bar are only possible from code
-  today** - `setConversationStarters` (`null` restores Agent Studio's), and
+- **Conversation starters** are agent-wide and yours to set through the
+  Foldspace tools; they carry over to the customer's real site.
+  `set_conversation_starters` **replaces the whole set and clears whatever you
+  leave out**: call `list_conversation_starters` first and send back the full
+  list. It changes their Foldspace account, so it needs their yes. Offer it in
+  the second wave, replacing the sign-up starters that point at actions the
+  agent does not have.
+- **Page-specific starters and the bottom bar are code** -
+  `setConversationStarters` (`null` restores Agent Studio's) and
   `setConfiguration({ bottomBarSettings })` then `openBottomBar()`. Send one
-  whole settings group per call, as the docs do.
-- **That code belongs where the product mounts the agent - in the customer's
-  own source.** In this project you do not have their source: you see their
-  product only through the test window. So this is their engineers' change, not
-  yours. Shipping it from this project's start-up code instead is a fallback for
-  a customer who cannot make the change, decided with Foldspace - not something
-  to reach for, and never in a first session.
+  whole settings group per call, as the docs do. That code lives in this
+  project's start-up (`recipes/bottom-bar`, kind `page-setup`) and ships with
+  the actions bundle, so nothing in the customer's source changes; their own
+  mount code is the other place it can live, their engineers' call. Offer it in
+  the second wave.
 - **An action's `execute` never calls `setConfiguration`**: a partial call from
   one once collapsed the agent's panel to nothing.
 
-If they ask for page-specific starters or the bottom bar, say what it takes in
-one sentence and note it in `docs/app-profile.md` as a next step.
-
 ## Agentic UI components: what bites
 
 An Agentic UI component is the card an action draws in the chat (`render`).
@@ -454,8 +524,10 @@ out: the API helper, the handler or card, and a recorded response per state. Cop
 placeholder path and fields with what you observed. They match the harness
 version you have installed, and every one is built and run on each release.
 
-L0 → `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
+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`. 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`.
@@ -502,7 +574,12 @@ export { apiFetch } from "./api";
 - **A refusal is an answer.** When a command or tool call is declined - by the
   human or by the session's own safety checks - stop. Say in one plain sentence
   what you wanted it for, or take a narrower read-only route. Never retry it,
-  and never try a different command hoping it gets through.
+  and never try a different command hoping it gets through - not re-quoted, not
+  in pieces, not through a helper script or a subagent: a denial covers the
+  outcome, not the string. If a `foldspace` command itself was denied, name it,
+  give the one-line allow rule (`Bash(npx foldspace:*)` in
+  `.claude/settings.local.json`), and hand that step to the human - for a chat
+  turn, that is them typing the question into the panel.
 - **Never create an account or a key** - not in Foldspace, not in the
   customer's product, not anywhere. If one is missing, say which and where it
   goes. **Never widen your own access**: if something is refused for a site or

package/bin/ask.mjs

@@ -0,0 +1,345 @@
+#!/usr/bin/env node
+// foldspace ask — put a question to the visible assistant through its panel,
+// exactly as a person would, and report what came back: the reply, any card,
+// what the handlers did, and a picture.
+//
+// It exists so the coding agent stops asking a non-technical customer to
+// "reload, try these two sentences and tell me what you saw".
+//
+//   node bin/ask.mjs "<question>" [--retry <n>] [--every <s>] [--timeout <s>] [--out <dir>]
+//
+// Nothing here reaches into the SDK, patches fetch or injects into the panel:
+// it opens the panel, types into the composer, presses Enter and reads the
+// screen. --retry re-asks when no action fired, which covers the platform
+// taking up to a minute to pick up a newly published action; lagMs is that cost.
+
+import fs from "node:fs";
+import path from "node:path";
+
+import {
+  createSettleTracker,
+  numberFlag,
+  replyAfter,
+  shouldRetry,
+  squash,
+  summarizeHandlerLog,
+} from "../src/ask-core.mjs";
+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 { resolveProjectDir } from "../src/upgrade.mjs";
+
+const PANEL_ID = "eucera-agent-iframe";
+const COMPOSER_WAIT_S = 30;
+const POLL_MS = 1500;
+
+const { flags, rest } = parseArgs(process.argv.slice(2), ["retry", "every", "timeout", "out"]);
+const question = squash(rest.join(" "));
+const retries = Math.floor(numberFlag(flags.retry, 0));
+const everyS = numberFlag(flags.every, 20);
+const timeoutS = numberFlag(flags.timeout, 90);
+const projectDir = resolveProjectDir();
+const outDir = flags.out
+  ? path.resolve(projectDir, String(flags.out))
+  : path.join(projectDir, ".foldspace-dev", "ask");
+const logFile = path.join(projectDir, ".foldspace-dev", ATTACH_DAEMON_LOG_FILE);
+
+let page = null;
+
+function finish(result, code) {
+  recordEvent(projectDir, "ask", { ok: result.ok, hasCard: Boolean(result.hasCard) });
+  printJson(result);
+  page?.close();
+  process.exit(code);
+}
+
+function logSize() {
+  try {
+    return fs.statSync(logFile).size;
+  } catch {
+    return null;
+  }
+}
+
+// Only what attach appended after the ask began; a missing log reads as "".
+function logSince(offset) {
+  if (offset === null) return "";
+  try {
+    const buffer = fs.readFileSync(logFile);
+    return buffer.subarray(Math.min(offset, buffer.length)).toString("utf8");
+  } catch {
+    return "";
+  }
+}
+
+// Shared by every page snippet: the panel document, or null while it loads.
+const PANEL_DOC = `
+  const frame = document.getElementById(${JSON.stringify(PANEL_ID)});
+  let doc = null;
+  try { doc = frame && frame.contentDocument; } catch {}
+`;
+
+async function panelState() {
+  return page.evaluate(`${PANEL_DOC}
+    if (!doc) return { frame: !!frame, composer: false };
+    const box = doc.querySelector("textarea");
+    const rect = frame.getBoundingClientRect();
+    return { frame: true, composer: !!box, visible: rect.width > 50 && rect.height > 50 };`);
+}
+
+// open() is the SDK's public "show the panel" call, the same thing the
+// launcher button does. The handle comes from the bootstrap when attach made
+// one, else from the page's own SDK.
+async function openPanel(agentApiName) {
+  return page.evaluate(`
+    const wanted = ${JSON.stringify(agentApiName || "")};
+    const namespace = typeof window.__FOLD_SPACE__ === "string" && window.__FOLD_SPACE__
+      ? window.__FOLD_SPACE__ : "foldspace";
+    const sdk = window[namespace];
+    let agent = window.__FOLDSPACE_AGENT__ || null;
+    if (!agent && typeof sdk?.agentIds === "function") {
+      const ids = sdk.agentIds().filter((id) => typeof id === "string" && id.indexOf("-") > 0);
+      const id = ids.find((item) => item.slice(item.indexOf("-") + 1) === wanted) || ids[0];
+      if (id) {
+        const cut = id.indexOf("-");
+        agent = sdk.agent({ apiName: id.slice(cut + 1), mode: id.slice(0, cut).toUpperCase() });
+      }
+    }
+    if (typeof agent?.open !== "function") return { sdk: !!sdk, opened: false };
+    try { agent.open(); return { sdk: true, opened: true }; }
+    catch (error) { return { sdk: true, opened: false, error: String(error?.message || error) }; }`);
+}
+
+async function readPanel(cardsBefore) {
+  return page.evaluate(`${PANEL_DOC}
+    if (!doc || !doc.body) return { panel: "", cards: [], cardFrames: 0, newCardFrames: 0 };
+    const squash = (text) => (text || "").replace(/\\s+/g, " ").trim();
+    const frames = Array.from(doc.querySelectorAll("iframe"));
+    const cards = [];
+    let painted = 0;
+    // Cards from earlier turns are still in the panel; only the new ones count.
+    for (const card of frames.slice(${Number(cardsBefore) || 0})) {
+      const rect = card.getBoundingClientRect();
+      if (rect.width > 20 && rect.height > 20) painted += 1;
+      try {
+        const body = card.contentDocument && card.contentDocument.body;
+        if (body) cards.push(squash(body.innerText || body.textContent));
+      } catch {}
+    }
+    return {
+      panel: squash(doc.body.innerText || doc.body.textContent),
+      cards: cards.filter(Boolean),
+      cardFrames: frames.length,
+      newCardFrames: painted,
+    };`);
+}
+
+// Real key events through the browser's input pipeline, like a person at the
+// keyboard. Frameworks that ignore synthetic DOM events still hear these.
+async function typeLikeAPerson(text) {
+  const focused = await page.evaluate(`${PANEL_DOC}
+    const box = doc && doc.querySelector("textarea");
+    if (!box) return false;
+    window.focus(); frame.contentWindow.focus(); box.focus();
+    return doc.activeElement === box;`);
+  if (!focused) return false;
+  await page.send("Input.insertText", { text });
+  const typed = await page.evaluate(`${PANEL_DOC}
+    const box = doc && doc.querySelector("textarea");
+    return box ? box.value : null;`);
+  if (squash(typed) !== text) return false;
+  const enter = {
+    key: "Enter",
+    code: "Enter",
+    windowsVirtualKeyCode: 13,
+    nativeVirtualKeyCode: 13,
+  };
+  await page.send("Input.dispatchKeyEvent", { type: "rawKeyDown", ...enter });
+  await page.send("Input.dispatchKeyEvent", { type: "char", ...enter, text: "\r" });
+  await page.send("Input.dispatchKeyEvent", { type: "keyUp", ...enter });
+  return true;
+}
+
+// A background or unfocused tab can swallow CDP input. Same gesture, delivered
+// as DOM events on the composer; still only typing, still nothing injected.
+async function typeWithDomEvents(text) {
+  return page.evaluate(`${PANEL_DOC}
+    const box = doc && doc.querySelector("textarea");
+    if (!box) return false;
+    const view = frame.contentWindow;
+    const setValue = Object.getOwnPropertyDescriptor(view.HTMLTextAreaElement.prototype, "value").set;
+    box.focus();
+    setValue.call(box, ${JSON.stringify(text)});
+    box.dispatchEvent(new view.Event("input", { bubbles: true }));
+    for (const type of ["keydown", "keypress", "keyup"]) {
+      box.dispatchEvent(new view.KeyboardEvent(type, {
+        key: "Enter", code: "Enter", keyCode: 13, which: 13, bubbles: true, cancelable: true,
+      }));
+    }
+    return true;`);
+}
+
+async function composerValue() {
+  return page
+    .evaluate(`${PANEL_DOC}
+      const box = doc && doc.querySelector("textarea");
+      return box ? box.value : "";`)
+    .catch(() => "");
+}
+
+async function askOnce() {
+  const before = await readPanel(0);
+  const cardsBefore = before.cardFrames;
+  const logOffset = logSize();
+
+  let typedBy = "keyboard";
+  let sent = await typeLikeAPerson(question).catch(() => false);
+  await sleep(700);
+  // Still sitting in the composer means Enter never landed.
+  if (!sent || squash(await composerValue()) === question) {
+    typedBy = "dom-events";
+    sent = await typeWithDomEvents(question).catch(() => false);
+  }
+  if (!sent) return { sent: false };
+
+  const tracker = createSettleTracker();
+  const deadline = Date.now() + timeoutS * 1000;
+  let seen = { panel: "", cards: [], newCardFrames: 0 };
+  let reply = "";
+  let settled = false;
+  while (Date.now() < deadline && !settled) {
+    await sleep(POLL_MS);
+    seen = await readPanel(cardsBefore).catch(() => seen);
+    reply = replyAfter(seen.panel, question);
+    settled = tracker.observe({ reply, cards: seen.cards }).settled;
+  }
+  // The render line trails the card by a beat; let attach flush it.
+  await sleep(400);
+  return {
+    sent: true,
+    typedBy,
+    settled,
+    reply: reply.slice(0, 2000),
+    cards: seen.cards.map((card) => card.slice(0, 2000)),
+    hasCard: seen.cards.length > 0 || seen.newCardFrames > 0,
+    handler: summarizeHandlerLog(logSince(logOffset)),
+  };
+}
+
+async function takeScreenshots() {
+  const stamp = new Date().toISOString().replace(/[:.]/g, "-");
+  const fullPath = path.join(outDir, `${stamp}-full.png`);
+  const panelPath = path.join(outDir, `${stamp}-panel.png`);
+  let screenshotFull = null;
+  let screenshot = null;
+  try {
+    screenshotFull = await page.screenshot(fullPath);
+  } catch {
+    // A picture is evidence, not the answer; never fail the ask over it.
+  }
+  // Clip is in page coordinates, so a scrolled page needs its offset added.
+  const clip = await page
+    .evaluate(`${PANEL_DOC}
+      if (!frame) return null;
+      const rect = frame.getBoundingClientRect();
+      const x = Math.max(0, rect.left), y = Math.max(0, rect.top);
+      const width = Math.min(window.innerWidth, rect.right) - x;
+      const height = Math.min(window.innerHeight, rect.bottom) - y;
+      return { x: x + window.scrollX, y: y + window.scrollY, width, height };`)
+    .catch(() => null);
+  if (clip && clip.width > 50 && clip.height > 50) {
+    try {
+      screenshot = await page.screenshot(panelPath, clip);
+    } catch {
+      // fall through to the full-window picture
+    }
+  }
+  return { screenshot: screenshot || screenshotFull, screenshotFull };
+}
+
+async function main() {
+  if (!question) {
+    finish(
+      {
+        ok: false,
+        reason:
+          'No question. Usage: foldspace ask "<question>" [--retry <n>] [--every <s>] [--timeout <s>] [--out <dir>]',
+      },
+      1,
+    );
+  }
+
+  const startedAt = Date.now();
+  page = await CdpPage.open({ projectDir });
+  const url = page.info.url;
+
+  // The composer does not exist until the panel has opened, and one open() is
+  // not always enough, so it is retried inside the poll.
+  let state = await panelState();
+  let opened = { sdk: false, opened: false };
+  for (let tick = 0; tick < COMPOSER_WAIT_S && !(state.composer && state.visible); tick++) {
+    opened = await openPanel(page.info.target?.agentApiName).catch(() => opened);
+    await sleep(1000);
+    state = await panelState().catch(() => state);
+    if (tick === 5 && !state.frame && !opened.sdk) break;
+  }
+  if (!state.composer) {
+    finish(
+      {
+        ok: false,
+        question,
+        reason: state.frame
+          ? "The assistant panel is on the page but never showed a composer."
+          : "No assistant panel on this page. Run `foldspace attach --daemon` (add --bootstrap when the page has no Foldspace SDK), then ask again.",
+        url,
+      },
+      1,
+    );
+  }
+  await sleep(600);
+
+  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 }));
+
+  if (!turn.sent) {
+    finish({ ok: false, question, reason: "Could not type into the composer.", attempts, url }, 1);
+  }
+
+  await sleep(500);
+  const shots = await takeScreenshots();
+  const ok = turn.reply.length > 0;
+  finish(
+    {
+      ok,
+      question,
+      reply: turn.reply,
+      cards: turn.cards,
+      hasCard: turn.hasCard,
+      handler: {
+        execute: turn.handler.execute,
+        render: turn.handler.render,
+        lines: turn.handler.lines,
+      },
+      ...(ok ? {} : { reason: `No reply within ${timeoutS}s.` }),
+      ...(turn.settled ? {} : { settled: false }),
+      screenshot: shots.screenshot,
+      screenshotFull: shots.screenshotFull,
+      typedBy: turn.typedBy,
+      attempts,
+      // Only a re-ask has lag to report: the time the platform took to catch up.
+      lagMs: attempts > 1 ? Date.now() - startedAt : 0,
+      ms: Date.now() - startedAt,
+      url,
+    },
+    ok ? 0 : 1,
+  );
+}
+
+main().catch((error) => {
+  finish({ ok: false, question, error: String(error?.message || error) }, 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,
@@ -249,7 +250,7 @@ const badgeSrc = `(() => {
     const want = s.state + "|" + (s.text || "");
     if (b.dataset.fsState === want) return;
     b.dataset.fsState = want;
-    const base = "position:fixed;top:0;left:0;z-index:2147483647;color:#fff;font:700 10px/1 ui-monospace,Menlo,monospace;letter-spacing:.12em;pointer-events:none;box-shadow:0 1px 6px rgba(0,0,0,.35);";
+    const base = "position:fixed;top:0;left:0;z-index:2147483647;color:#fff;font:700 10px/1 ui-monospace,Menlo,monospace;letter-spacing:.12em;pointer-events:none;transition:opacity .15s;box-shadow:0 1px 6px rgba(0,0,0,.35);";
     if (s.state === "working") {
       // Attention, not decoration: a pulsing marker, the ask in bold, and an
       // animated line underneath so it reads as "in progress" at a glance.
@@ -272,6 +273,18 @@ const badgeSrc = `(() => {
   draw();
   document.addEventListener("DOMContentLoaded", draw);
   setInterval(draw, 1000);
+  // The corner tag sits over the app's top-left corner - often a logo or the
+  // first menu item. Clicks already pass through it (pointer-events:none); it
+  // also fades out while the pointer is near, so what is under it can be seen.
+  // The working pill never fades: it is the one thing that must be read.
+  document.addEventListener("mousemove", (e) => {
+    const b = document.getElementById("foldspace-dev-badge");
+    if (!b) return;
+    if ((b.dataset.fsState || "").indexOf("working") === 0) { b.style.opacity = "1"; return; }
+    const r = b.getBoundingClientRect();
+    const near = e.clientX >= r.left - 12 && e.clientX <= r.right + 12 && e.clientY >= r.top - 12 && e.clientY <= r.bottom + 12;
+    b.style.opacity = near ? "0" : "1";
+  }, { passive: true });
 })();`;
 
 // Flag every local session as test traffic so it is excluded from analytics and
@@ -797,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;
 
@@ -807,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.
@@ -831,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 });