@foldspace_npm/harness 0.1.22 → 0.1.23

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
 
@@ -111,9 +133,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 +316,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 +346,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
@@ -356,29 +391,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 +484,9 @@ 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`. 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 +533,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

@@ -249,7 +249,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 +272,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

package/package.json

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

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

package/src/init.mjs

@@ -353,7 +353,14 @@ function copyTemplate(templateRoot, targetRoot, values) {
       const sourcePath = path.join(templateRoot, relativePath);
       // npm excludes .gitignore files from package tarballs, so the bundled
       // template uses a publish-safe name and restores it during generation.
-      const outputPath = relativePath === "gitignore" ? ".gitignore" : relativePath;
+      // The permission allowlist lives in .claude/, kept flat here for the
+      // same reason.
+      const outputPath =
+        relativePath === "gitignore"
+          ? ".gitignore"
+          : relativePath === "claude-settings.json"
+            ? path.join(".claude", "settings.json")
+            : relativePath;
       const targetPath = path.join(targetRoot, outputPath);
       assertInside(targetRoot, targetPath);
 

package/templates/agent-starter/claude-settings.json

@@ -0,0 +1,21 @@
+{
+  "$comment": "Written by foldspace init. The commands a build runs, allowed up front so the coding agent is not stopped one denial at a time mid-build. Named one by one on purpose: init, upgrade and deploy are not here and still ask. Everything else still asks.",
+  "permissions": {
+    "allow": [
+      "Bash(npx foldspace help:*)",
+      "Bash(npx foldspace build:*)",
+      "Bash(npx foldspace lint:*)",
+      "Bash(npx foldspace inject:*)",
+      "Bash(npx foldspace attach:*)",
+      "Bash(npx foldspace observe:*)",
+      "Bash(npx foldspace ask:*)",
+      "Bash(npx foldspace badge:*)",
+      "Bash(npm install:*)",
+      "Bash(npm run build:*)",
+      "Bash(npm run typecheck:*)",
+      "Bash(npm run lint:*)",
+      "Bash(npm run inject:*)",
+      "Bash(npm run attach:*)"
+    ]
+  }
+}