@foldspace_npm/harness 0.1.27 → 0.1.28

package/README.md

@@ -12,12 +12,12 @@ else about how a builder runs differs between them; this does not.
 
 | | **A — local** *(today)* | **B — remote** *(designed, unbuilt)* |
 |---|---|---|
-| Who runs the agent | Claude Code on the builder's desktop | Claude Agent SDK in GCP |
-| Whose browser | an isolated Chrome the harness launches | the user's **own** Chrome |
+| Where the build runs | Claude Code on the human's computer | Claude Agent SDK in GCP |
+| Whose browser | an isolated Chrome the harness launches | the human's **own** Chrome |
 | How code reaches the page | harness CDP preparation | builder extension loads the cloud artifact |
 | Prerequisites | Claude Code, a client repo, Node, an isolated Chrome profile | the extension installed |
-| Session and cookies | in a profile the harness creates | the user's own, untouched |
-| Code and history | a git repo on the builder's machine | a workspace in the hosted environment |
+| Session and cookies | in a profile the harness creates | the human's own, untouched |
+| Code and history | a git repo on the human's computer | a workspace in the hosted environment |
 
 "Export to repo" moves a build from B to A — **and it is only a copy, not a
 rewrite, while `agent/` is identical in both.** Keeping it identical is the
@@ -29,7 +29,7 @@ constraint this package exists to protect.
   nothing more. Actions built in one track run unmodified in the other.
 - `agent/utils.ts` — configures and re-exports `@foldspace_npm/harness/runtime`
 - `foldspace build` — esbuild → `dist/index.js`
-- `foldspace deploy` — publish to `agent/actions/<env>/<productId>/<agentApiName>`
+- `foldspace deploy` (Foldspace-internal) - uploads `dist/index.js` to `agent/actions/<env>/<productId>/<agentApiName>`
 - fixtures and tests
 - **the verb interface** below
 
@@ -95,7 +95,7 @@ Non-interactive / CI form:
 
 ```bash
 npx --yes @foldspace_npm/harness init foldspace-agent \
-  --product-id FR8JUQZAQRZB \
+  --product-id <product-id> \
   --agent-key my-agent \
   --app-domain app.example.com \
   --name "My Agent"
@@ -105,7 +105,7 @@ When running directly from a harness checkout during development:
 
 ```bash
 node bin/cli.mjs init ../foldspace-agent \
-  --product-id FR8JUQZAQRZB \
+  --product-id <product-id> \
   --agent-key my-agent \
   --app-domain app.example.com
 ```
@@ -115,8 +115,9 @@ not the sidecar directory name. `--agent-api-name` remains a deprecated alias
 for `--agent-key`. `--domain` remains a deprecated alias for `--app-domain`.
 `--name` is optional and defaults to the target directory
 name (`foldspace-agent` unless you pass a directory). The product ID must be
-the bare ID, not the `EU-…-1-1` SDK loader key. The app domain may be a hostname
-or an HTTP(S) URL without a port or path.
+the bare ID, not the SDK key (the one that starts with `EU-`, in every
+region). The app domain may be a hostname or an HTTP(S) URL without a port or
+path.
 
 `--region us|eu` (default `us`) is the Foldspace region the account lives in.
 It is written to `foldspace.dev.json` as `region`, and picks the SDK the
@@ -131,9 +132,11 @@ initialize Git or overwrite files. On a TTY it can offer
 ```bash
 cd foldspace-agent
 npm install --ignore-scripts   # if you skipped the install prompt
+# before the first build, CLAUDE.md step 5: a code project's agent/ replaces the scaffold's
 npm run build
-npm run inject
-npm run attach
+npm run inject   # the human signs in in that window
+npx foldspace observe wait-login
+npx foldspace attach --daemon
 ```
 
 The generated npm scripts intentionally remain the normal project interface;
@@ -146,21 +149,21 @@ to that import with `foldspace upgrade --refresh-instructions`.
 ### Keep the harness current
 
 Tenant projects pin an exact `@foldspace_npm/harness` version. Publishing a
-newer package does not move them. Check, ask the user, then bump:
+newer package does not move them. Check, ask the human, then bump:
 
 ```bash
 npx --yes @foldspace_npm/harness@latest upgrade --check
-foldspace upgrade --yes   # only after the user agrees
+foldspace upgrade --yes   # only after the human agrees
 ```
 
 `--check` (and a non-interactive `upgrade` with no `--yes`) never installs.
-`--yes` rewrites the exact pin and runs `npm install --ignore-scripts`. Rebuild
-afterward; that is still not a deploy.
+`--yes` writes the new exact version and runs `npm install --ignore-scripts`.
+Rebuild afterward; that publishes nothing.
 
 `foldspace build` and `foldspace attach` run the same check before they start
 (`attach --status` and `--stop` do not). A project that is behind gets one line
 on stderr and carries on. A project on a **withdrawn** version (below) refuses
-to run and prints the reason. To build on it anyway, once the user has declined
+to run and prints the reason. To build on it anyway, once the human has declined
 the upgrade:
 
 ```bash
@@ -200,13 +203,14 @@ To undo a withdrawal, deprecate with an empty message:
 npm deprecate @foldspace_npm/harness@0.1.14 ""
 ```
 
-**It is not instant.** Each project caches the registry's answer for 12 hours
-in `.foldspace-dev/harness-update.json`. A project that checked recently keeps
-its "fine" answer until that expires, so a withdrawal reaches every project
-within 12 hours. It only reaches projects on a harness version that has this
-check.
+**It is not instant for `build` and `attach`.** They use the registry's answer
+cached for 12 hours in `.foldspace-dev/harness-update.json`. `foldspace help
+--json` (which the manual reads first) and `foldspace upgrade` ask the registry
+each time and refresh that cache, so a withdrawal reaches a project at its next
+session start, and within 12 hours otherwise. It only reaches projects on a
+harness version that has this check.
 
-### Lint handlers before they ship
+### Lint agent code before it ships
 
 `foldspace build` runs `foldspace lint` first. Errors skip bundling; warnings
 print and still produce `dist/index.js`.
@@ -218,12 +222,16 @@ foldspace lint --json
 
 v1 flags:
 
-- **error** `no-static-agent-prompt` — `execute` / chatterblock `callback` returning copilot instructions (`directive`, “tell the user”, …)
+- **error** `no-static-agent-prompt` - `execute`, a card's `callback` or its `readyState` handing the agent instructions (`directive`, “tell the user”, …)
 - **error** `no-runtask-prompt` — `runTask({ data: { prompt } })` and the same keys; a customer API field named `prompt` is allowed
+- **error** `card-contract` - `awaitUserInput: true` on a view card (its `render` uses no `callback`, `cancel` or `readyState`): the chat panel ignores it, but in headless mode the agent waits for a callback that never comes
+- **error** `no-test-mode-in-bundle` - `armAllInstances(...)`, or `setTestMode(...)` with anything but a literal `false`, anywhere in `agent/`
+- **warning** `card-contract` - any other `awaitUserInput` on a view card, `awaitUserInput` on an input card (not needed), or a `render` that declares `callback`, `cancel` or `readyState` and uses none of them (the SDK treats it as a view card)
 - **warning** `no-emoji` — emoji in handler or `agent/views` string literals
 - **warning** `registry-integrity` — duplicate keys, `{ execute }` not registered, registry value missing `execute`
 
-Put action instructions in Agent Studio or MCP. `foldspace lint` cannot see that copy.
+Put action instructions in Agent Studio or with the Foldspace tools. `foldspace
+lint` cannot see that copy.
 
 ### Runtime helpers
 
@@ -232,7 +240,10 @@ Tenant actions import from `agent/utils.ts`, which configures and re-exports
 runs in the customer's page — it is not a CLI command.
 
 `API_BASE` and `AUTH_SOURCE` stamp empty. Fill them from a captured XHR, not a
-guess. Custom auth headers stay a tenant override of one function in `utils.ts`.
+guess. For auth that is not Bearer, follow
+`recipes/swap-the-login-method/README.md`: for a custom header, copy its
+`agent/utils.ts` over `agent/utils.ts`; for cookies with no token, its
+`variants/utils.cookies.ts`.
 
 ### Choose an attach mode
 
@@ -242,21 +253,25 @@ guess. Custom auth headers stay a tenant override of one function in `utils.ts`.
   has an SDK without the configured agent.
 
 Use `foldspace help attach` for mode requirements, effects, and safety options.
-Coding agents should run `foldspace attach --daemon` so the invoking tool
+Coding agents run `foldspace attach --daemon` so the invoking tool
 returns after `[lifecycle] inspect_registration:…`. Foreground attach remains
-the default for humans watching the terminal. `attach --status` and
+the default for someone watching the terminal. `attach --status` and
 `attach --stop` inspect and tear down a daemon. Look at the customer's app with
-`foldspace observe`: it reads the same window, read-only, while attach runs.
+`foldspace observe`: it reads the test window, read-only, while attach runs.
 
 ### Verify actions through the agent
 
 `foldspace attach` does not invoke action handlers directly. It loads the local
 artifact, verifies that the captured local registry matches the configured SDK
-agent — including an empty registry — and then observes action callbacks while
+agent - including an empty registry - and then observes action calls while
 you exercise the normal agent experience. Named actions are not required to
 attach.
 
-Action output identifies SDK callbacks and local `execute`/`render` phases:
+`npx foldspace ask "<question>" --retry 2` types the question into the agent's
+panel and reports the reply, the card text and a screenshot, and - while attach
+runs - whether execute and render ran.
+
+Action output shows the SDK's action calls and local `execute`/`render` phases:
 
 ```text
 [actions] sdk:action show_account_360 executed
@@ -311,8 +326,7 @@ npm i -D @foldspace_npm/harness
     "build":  "foldspace build",
     "inject": "foldspace inject",
     "attach": "foldspace attach",
-    "attach:daemon": "foldspace attach --daemon",
-    "deploy": "foldspace deploy"
+    "attach:daemon": "foldspace attach --daemon"
 } }
 ```
 
@@ -320,9 +334,13 @@ Every command resolves the **consuming** repo — `process.cwd()`, or
 `FOLDSPACE_PROJECT_DIR` so a hosted builder can point it at a workspace it
 controls. Config comes from the consumer's `foldspace.dev.json`.
 
-`foldspace deploy` is an explicit remote publication step that reads product
-and agent identity from the selected target in `foldspace.dev.json`. It requires
-local cloud credentials and is separate from local verification.
+`foldspace deploy` is Foldspace-internal: it writes to Foldspace's own storage,
+which no customer can write to. A coding agent never runs or offers it. With a
+code project, a build session publishes the agent's code with the Foldspace
+tools instead: `repo_write` saves it, and the `deploy` tool publishes it - to
+dev after saying so, to production only on the human's yes - as the manual's
+"Done, and what you say at the end" says. Without a code project, the
+Foldspace team does it with the human.
 
 ---
 
@@ -336,7 +354,7 @@ and **neither had all five**:
 |---|---|
 | SDK load guard + retry | On an app with no `document.body` at document-start the append throws; the old guard tested for the stub, so nothing retried and the agent silently never loaded |
 | Worker release on auto-attach | Auto-attach pauses every worker until the attaching client releases it — the harness froze the app's own workers for the whole session |
-| `agentIds` enumeration | `agent({apiName})` returns the OVERLAY handle; arming it on an embedded copilot leaves real conversations untagged |
+| `agentIds` enumeration | `agent({apiName})` returns the OVERLAY handle; arming it on an embedded agent leaves real conversations untagged |
 | `--test-mode` (off by default) | Test mode was armed unconditionally, hiding exactly what initial setup needs to see; now it is opt-in |
 | Honest badge | It asserted `TEST MODE` whether or not test mode was on |
 

package/bin/ask.mjs

@@ -1,12 +1,12 @@
 #!/usr/bin/env node
-// foldspace ask — put a question to the visible assistant through its panel,
+// foldspace ask - put a question to the visible agent 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".
+// It exists so the coding agent stops asking the human 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>]
+//   npx foldspace ask "<question>" [--retry <n>] [--every <s>] [--timeout <s>]
 //
 // 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
@@ -272,7 +272,7 @@ async function main() {
       {
         ok: false,
         reason:
-          'No question. Usage: foldspace ask "<question>" [--retry <n>] [--every <s>] [--timeout <s>] [--out <dir>]',
+          'No question. Usage: foldspace ask "<question>" [--retry <n>] [--every <s>] [--timeout <s>]',
       },
       1,
     );
@@ -298,8 +298,10 @@ async function main() {
         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.",
+          ? "The agent panel is on the page but never showed a composer. Run `npx foldspace observe screenshot` and look at the page."
+          : tracked
+            ? "No agent panel on this page while attach runs. Read the lines under the last [lifecycle] line in .foldspace-dev/attach-daemon.log, then ask again."
+            : "No agent panel on this page. Run `npx foldspace attach --daemon`, follow what it says about the page, then ask again.",
         url,
       },
       1,

package/bin/attach.mjs

@@ -15,7 +15,7 @@
  *
  *  --replace       The app embeds a different Foldspace product or agent.
  *                  Rebind the page bootstrap to the configured product and
- *                  make the configured agent the sole visible widget owner.
+ *                  make the configured agent the only visible one.
  *
  * Chrome 136+ removed --load-extension and does not run content scripts for
  * CDP-loaded extensions, so neither path uses the extension at runtime.
@@ -25,11 +25,13 @@ import path from "path";
 import { fileURLToPath } from "url";
 import {
   ATTACH_MODES,
+  attachAgainFlags,
   attachModeFromArgs,
   characterizePageAgents,
   hostMatches,
   hostPatternsFromTarget,
   parseAgentId,
+  registrationMismatchReport,
   registrationVerified,
   resolveAttachLaunch,
 } from "../src/attach-helpers.mjs";
@@ -101,8 +103,8 @@ const { useSavedLaunch, port } = resolveAttachLaunch({
 });
 if (!port) {
   console.error(
-    `attach: no CDP port. Run "foldspace inject" first, or pass --port / CDP_PORT.\n` +
-      `        Refusing to guess 9222 — that port is often someone else's Chrome.`,
+    `attach: no CDP port recorded here. Run \`npm run inject\` first; it opens the test window and records its port.\n` +
+      `        Refusing to guess 9222 - that port is often someone else's Chrome.`,
   );
   process.exit(1);
 }
@@ -113,7 +115,7 @@ const claimed = verifyLaunchSentinel({
 });
 if (!claimed.ok) {
   console.error(
-    `attach: ${ownershipErrorMessage(claimed.reason, { port, profileDir, root })}`,
+    `attach: ${ownershipErrorMessage(claimed.reason, { port, command: "attach" })}`,
   );
   process.exit(1);
 }
@@ -124,7 +126,7 @@ const owned = await assertOwnedCdp({
 });
 if (!owned.ok) {
   console.error(
-    `attach: ${ownershipErrorMessage(owned.reason, { port, profileDir, root })}`,
+    `attach: ${ownershipErrorMessage(owned.reason, { port, command: "attach" })}`,
   );
   process.exit(1);
 }
@@ -148,6 +150,8 @@ const noTestMode = !process.argv.includes("--test-mode");
 // string that asserts you are safe while you are not. It now states what is
 // actually true. --no-badge drops it entirely, for recording a demo.
 const noBadge = process.argv.includes("--no-badge");
+// What a restart step names, so it keeps this attach's mode, test mode and tag.
+const againFlags = attachAgainFlags({ mode: attachMode, testMode: !noTestMode, noBadge });
 // Agent api name for setTestMode — from the same config inject.mjs used.
 const cfg = JSON.parse(fs.readFileSync(path.join(root, "foldspace.dev.json"), "utf8"));
 const targetName =
@@ -189,7 +193,7 @@ const unresolved = PLACEHOLDERS.filter((ph) =>
 if (unresolved.length) {
   console.error(
     `attach: foldspace.dev.json still contains placeholders: ${unresolved.join(", ")}\n` +
-    `        Run "foldspace init" first, or pass --agent <apiName>.\n` +
+    `        Run "foldspace init" first, or pass --agent <agent-key>.\n` +
     `        Refusing to run — injecting a placeholder breaks the app's agent.`
   );
   process.exit(1);
@@ -203,7 +207,7 @@ if (bootstrap && (!sdkUrl || typeof sdkUrl !== "string")) {
   process.exit(1);
 }
 if (!fs.existsSync(bundlePath)) {
-  console.error(`attach: ${path.relative(root, bundlePath)} is missing — run "npm run build" first.`);
+  console.error(`attach: ${path.relative(root, bundlePath)} is missing - run \`npm run build\` first.`);
   process.exit(1);
 }
 const hostPatterns = hostPatternsFromTarget(cfgTarget);
@@ -224,10 +228,10 @@ const SDK_PATTERNS = [
 
 // The badge has three states, set from outside with \`foldspace badge\`:
 //   label   - the small corner tag (default): who is attached, which mode
-//   working - a pill at the foot of the window: the agent is building in this
-//             window, please leave it alone
+//   working - a pill at the foot of the window: the build session is working
+//             in this window, please leave it alone
 //   ready   - the pill goes away and the small tag comes back: their turn.
-//             No bar for that - they may type whatever, whenever
+//             No pill for that - they may type whatever, whenever
 // The pill sits bottom-left, never across the top: a bar there covered the
 // app's own header and menu (seen on a CRM, 2026-09-22). The agent's panel
 // is on the right, so bottom-left is the corner nothing else uses.
@@ -260,11 +264,11 @@ const badgeSrc = `(() => {
         '#foldspace-dev-badge .fs-dot{display:inline-block;width:10px;height:10px;border-radius:50%;background:#FFD314;margin-right:10px;vertical-align:middle;animation:fsPulse 1s ease-in-out infinite}' +
         '#foldspace-dev-badge .fs-line{position:absolute;left:0;right:0;bottom:0;height:3px;background:rgba(255,255,255,.15);overflow:hidden}' +
         '#foldspace-dev-badge .fs-line::after{content:"";position:absolute;top:0;width:30%;height:100%;background:#FFD314;animation:fsSweep 1.4s linear infinite}</style>' +
-        '<span class="fs-dot"></span>Foldspace is building your agent on this page. <b style="color:#FFD314">Please leave this window alone</b> until the agent says it is ready.' +
+        '<span class="fs-dot"></span>Foldspace is building your agent on this page. <b style="color:#FFD314">Please leave this window alone</b> until you are told in the chat that it is ready.' +
         (s.text ? " " + s.text.replace(/[<>&]/g, (c) => ({ "<": "&lt;", ">": "&gt;", "&": "&amp;" })[c]) : "") +
         '<span class="fs-line"></span>';
     } else {
-      // "ready" and "label" both draw the small tag: their turn needs no bar -
+      // "ready" and "label" both draw the small tag: their turn needs no pill -
       // they may type whatever, whenever. Only the wait ever gets a pill.
       b.style.cssText = base + "background:#3247F2;padding:5px 10px;border-bottom-right-radius:4px;";
       b.textContent = LABEL;
@@ -292,7 +296,7 @@ const badgeSrc = `(() => {
 // https://docs.foldspace.ai/reference/test-mode.md
 //
 // A handle is scoped by mode: window.foldspace.agent({apiName}) alone returns
-// the OVERLAY instance. On an app that embeds the copilot that is NOT the
+// the OVERLAY instance. On an app that embeds the agent in-page that is NOT the
 // instance serving the chat, so arming it succeeds, logs success, and leaves
 // the real conversations untagged — the failure that actually leaks. Enumerate
 // foldspace.agentIds() — each id is shaped "<mode>-<apiName>" — and arm every
@@ -349,7 +353,7 @@ const testModeScript = (enable) => `(() => {
     try { window.foldspace("when", "ready", armAll); } catch (e) {}
     armAll();
 
-    // The instance serving the chat is built when the copilot panel opens, long
+    // The instance serving the chat is built when the agent panel opens, long
     // after "ready" — arming once is too early. Keep arming.
     setInterval(armAll, 1000);
 
@@ -406,6 +410,9 @@ function logLifecycle(result) {
   if (!result.ok && result.error?.message) {
     console.log(`    ${result.error.message}`);
   }
+  if (!result.ok && Array.isArray(result.details?.findings)) {
+    for (const line of result.details.findings) console.log(`    ${line}`);
+  }
   if (!result.ok && result.details?.suggestion) {
     console.log(`    Next: ${result.details.suggestion}`);
   }
@@ -703,6 +710,7 @@ async function prepare(ws, sessionId, url) {
               mode: agentMode,
               namespace: pageState?.namespace || "foldspace",
               aliases,
+              testMode: !noTestMode,
             }),
             hostPatterns,
           ),
@@ -718,7 +726,8 @@ async function prepare(ws, sessionId, url) {
     // Test mode is armed when --test-mode is set, and actively CLEARED otherwise:
     // it is page-session state that only a reload or setTestMode(false) undoes,
     // so a page left in test mode by an earlier attach would keep the striped
-    // banner under a LIVE badge until reload (seen on RoofSnap, 2026-09-30).
+    // test-mode banner under a LIVE corner tag until reload (a customer build,
+    // 2026-09-30).
     scripts.push(testModeScript(!noTestMode));
     if (bootstrap) {
       scripts.push(
@@ -762,6 +771,45 @@ async function prepare(ws, sessionId, url) {
       const verification = await verifyPreparedPage(ws, sessionId);
       // For scoring a session: the moment the customer could first see their agent.
       if (verification.ok) recordEvent(root, "agent_visible", { mode: attachMode });
+      const registrationDetails = {
+        mode: attachMode,
+        testMode: !noTestMode,
+        noBadge,
+        expectedAgentId: verification.characterization.expectedAgentId,
+        detectedAgentIds: verification.state?.agentIds || [],
+        expectedProductId: productId,
+        detectedProductIds: verification.products,
+        widget: verification.widget,
+        registeredActionNames:
+          verification.registration?.actionNames || [],
+        expectedActionNames:
+          verification.observation?.expectedActionNames || [],
+        expectedActionCount: Array.isArray(
+          verification.observation?.expectedActionNames,
+        )
+          ? verification.observation.expectedActionNames.length
+          : 0,
+        missingActionNames:
+          verification.registration?.missingActionNames || [],
+        unexpectedActionNames:
+          verification.registration?.unexpectedActionNames || [],
+        actionObserverSubscribed:
+          verification.observation?.subscribed === true,
+        // null when attach never got as far as the action checks.
+        actionObserverInstalled: verification.observation
+          ? verification.observation.installed === true
+          : null,
+        actionCaptureCount: verification.observation
+          ? Number(verification.observation.captureCount) || 0
+          : null,
+        agentFound: verification.registration
+          ? verification.registration.agentFound === true
+          : null,
+        actionNameLimitExceeded:
+          verification.observation?.actionNameLimitExceeded === true,
+        diagnosticError: verification.diagnosticError,
+      };
+      const mismatch = verification.ok ? null : registrationMismatchReport(registrationDetails);
       logLifecycle(
         createLifecycleResult({
           operation: "inspect_registration",
@@ -774,32 +822,9 @@ async function prepare(ws, sessionId, url) {
                 message:
                   "The local action registry did not match the configured page agent.",
               },
-          details: {
-            mode: attachMode,
-            expectedAgentId: verification.characterization.expectedAgentId,
-            detectedAgentIds: verification.state?.agentIds || [],
-            expectedProductId: productId,
-            detectedProductIds: verification.products,
-            widget: verification.widget,
-            registeredActionNames:
-              verification.registration?.actionNames || [],
-            expectedActionNames:
-              verification.observation?.expectedActionNames || [],
-            expectedActionCount: Array.isArray(
-              verification.observation?.expectedActionNames,
-            )
-              ? verification.observation.expectedActionNames.length
-              : 0,
-            missingActionNames:
-              verification.registration?.missingActionNames || [],
-            unexpectedActionNames:
-              verification.registration?.unexpectedActionNames || [],
-            actionObserverSubscribed:
-              verification.observation?.subscribed === true,
-            actionNameLimitExceeded:
-              verification.observation?.actionNameLimitExceeded === true,
-            diagnosticError: verification.diagnosticError,
-          },
+          details: mismatch
+            ? { ...registrationDetails, findings: mismatch.lines, suggestion: mismatch.next }
+            : registrationDetails,
         }),
       );
       if (!verification.ok) {
@@ -825,7 +850,7 @@ function noteUncoveredHost(url) {
   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.`);
+  console.log(`    Next: if it is part of the product, add "${coverage.pattern}" to "hosts" in foldspace.dev.json (with the human's yes), then \`npx foldspace attach --stop\`, \`npm run inject\` and \`npx foldspace attach${againFlags} --daemon\`. If it is not, ask the human to go back to the product in the test window.`);
 }
 
 async function onEvent(ws, msg) {
@@ -1026,11 +1051,11 @@ const ver = await connect(owned.version);
 console.log(`Attached to ${ver.Browser} on :${port}`);
 console.log(`Mode:  ${attachMode}`);
 console.log(`Agent: ${agentApiName} (product ${productId}, ${agentMode})`);
-console.log(`Test:  ${noTestMode ? "off — conversations appear in the dashboard (pass --test-mode to hide them)" : "on"}`);
+console.log(`Test:  ${noTestMode ? "off - conversations appear in their Foldspace dashboard (--test-mode is only for an agent that already has real users)" : "on"}`);
 console.log(`Hosts: ${hostPatterns.join(", ")}`);
 console.log(`Serving: ${path.relative(root, bundlePath)}`);
 console.log(
-  `CDP: attached. \`foldspace observe\` reads this same window while attach runs; stop attach only to load rebuilt actions.\n`,
+  `CDP: attached. \`npx foldspace observe\` and \`npx foldspace ask\` use this same window while attach runs; stop attach only to load rebuilt actions or changed hosts, or to check published code on dev.\n`,
 );
 
 function printSessionSummary() {
@@ -1136,9 +1161,9 @@ process.on("SIGTERM", requestDetach);
 
 // A closed socket does not mean the browser closed. Chrome drops the CDP
 // connection on target churn and transient errors too, and exiting on those
-// silently ends the swap while the user keeps browsing — the page then loads
-// the deployed bundle with no signal that anything changed. Reconnect, and
-// only give up once the debugging port is genuinely gone.
+// silently ends the swap while the human keeps browsing - the page then runs
+// only what the site loads by itself, with no signal that anything changed.
+// Reconnect, and only give up once the debugging port is genuinely gone.
 async function browserIsUp() {
   try {
     const r = await fetch(`http://localhost:${port}/json/version`);
@@ -1162,12 +1187,16 @@ async function onDisconnect(closedSocket) {
       if (!(await browserIsUp())) {
         clearInterval(keepAlive);
       printSessionSummary();
-        console.log("\nBrowser closed. Detaching.");
+        console.log("\nThe test window was closed. Detaching.");
         process.exit(0);
       }
       try {
         console.log(`  connection lost — reconnecting (${attempt}/10)…`);
-        await connect();
+        // connect() needs the browser's version endpoint; re-check ownership
+        // so attach never adopts another Chrome that took the port meanwhile.
+        const again = await assertOwnedCdp({ profileDir, port, token: devState.sentinel });
+        if (!again.ok) throw new Error(again.reason);
+        await connect(again.version);
         console.log(`  reconnected. ${attachMode} mode is live again.`);
         return;
       } catch {
@@ -1176,8 +1205,8 @@ async function onDisconnect(closedSocket) {
     }
     clearInterval(keepAlive);
     printSessionSummary();
-    console.error("\nCould not reconnect after 10 attempts. Detaching — "
-      + "the page is now loading the DEPLOYED bundle, not your local build.");
+    console.error("\nCould not reconnect after 10 attempts. Detaching - after a reload the page runs only what "
+      + `the site loads by itself, not this build. Run \`npx foldspace attach${againFlags} --daemon\` again.`);
     process.exit(1);
   } finally {
     reconnecting = false;

package/bin/badge.mjs

@@ -2,15 +2,16 @@
 /**
  * foldspace badge <working|ready|label|off> [--text "<what to show>"]
  *
- * Sets the pill the attach badge draws at the foot of the test window.
- * The agent and the human share that one Chrome window, so the pill says
- * when to wait:
+ * Sets what attach draws in the test window: the pill or the corner tag.
+ * You and the human share that one Chrome window, so the pill says when to
+ * wait:
  *   working - "Foldspace is building your agent on this page. Please leave
- *             this window alone until the agent says it is ready."
+ *             this window alone until you are told in the chat that it is
+ *             ready."
  *   ready   - the pill goes away, the small corner tag comes back: their
- *             turn. No bar for that - they may type whatever, whenever.
+ *             turn. No pill for that - they may type whatever, whenever.
  *   label   - the small corner tag
- *   off     - remove it
+ *   off     - draw nothing: no pill, no corner tag
  * The state is kept in the page's sessionStorage, so it survives navigation;
  * attach's badge script redraws within a second. Nothing else on the page is
  * touched.
@@ -36,12 +37,31 @@ try {
 let page;
 try {
   page = await CdpPage.open({ projectDir });
+  // attach's badge script redraws within a second (after `badge off`, or
+  // before the body exists, there is no element yet): give it that second.
   const shown = await page.evaluate(
     `sessionStorage.setItem("__foldspace_badge__", ${JSON.stringify(JSON.stringify(payload))});
-     const b = document.getElementById("foldspace-dev-badge");
+     let b = document.getElementById("foldspace-dev-badge");
+     for (let i = 0; !b && ${payload.state !== "off"} && i < 8; i++) {
+       await new Promise((resolve) => setTimeout(resolve, 250));
+       b = document.getElementById("foldspace-dev-badge");
+     }
      return { url: location.href.split(/[?#]/)[0], hadBadge: Boolean(b) };`,
   );
-  printJson({ ok: true, state: payload.state, ...(payload.text ? { text: payload.text } : {}), ...shown });
+  // Still no element: the state was stored but nothing will show it.
+  const note =
+    !shown.hadBadge && payload.state !== "off"
+      ? {
+          note:
+            "Nothing is drawn on this page. After `npx foldspace published` that is expected - attach is " +
+            "stopped - so say in chat whose turn it is instead. Otherwise run `npx foldspace attach --status`. " +
+            "With no live daemon, run `npx foldspace attach --daemon` with the flags it ran with. With one, " +
+            "read its log (`logPath`): a `registration_mismatch` there names what differs and the next step; " +
+            "without one, attach runs with --no-badge - `npx foldspace attach --stop`, then " +
+            "`npx foldspace attach --daemon` with the flags it ran with, minus --no-badge.",
+        }
+      : {};
+  printJson({ ok: true, state: payload.state, ...(payload.text ? { text: payload.text } : {}), ...shown, ...note });
 } catch (error) {
   printJson({ ok: false, error: error instanceof Error ? error.message : String(error) });
   process.exit(1);