@foldspace_npm/harness 0.1.26 → 0.1.28

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,14 +296,16 @@ 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
 // one. See the playbook's test-mode rule.
-const testModeSrc = `(() => {
+const testModeScript = (enable) => `(() => {
   if (window.top !== window.self) return;
   const AGENT = ${JSON.stringify(agentApiName)};
+  const WANT = ${enable};
+  const WORD = ${JSON.stringify(enable ? "ON" : "OFF")};
   // Log once per instance; setTestMode itself is re-applied on every pass so an
   // instance that is torn down and rebuilt gets re-armed.
   const logged = new Set();
@@ -316,10 +322,10 @@ const testModeSrc = `(() => {
     // Older SDK with no agentIds(): the unscoped handle is all there is.
     if (!ids) {
       try {
-        fs.agent({ apiName: AGENT }).setTestMode(true);
+        fs.agent({ apiName: AGENT }).setTestMode(WANT);
         if (!logged.has(AGENT)) {
           logged.add(AGENT);
-          console.log("[foldspace-dev] test mode ON (" + AGENT + " — SDK has no agentIds(), overlay handle only)");
+          console.log("[foldspace-dev] test mode " + WORD + " (" + AGENT + " — SDK has no agentIds(), overlay handle only)");
         }
       } catch (e) {
         console.warn("[foldspace-dev] setTestMode failed:", e && e.message);
@@ -332,10 +338,10 @@ const testModeSrc = `(() => {
       if (cut < 1) continue;
       try {
         fs.agent({ apiName: id.slice(cut + 1), mode: id.slice(0, cut).toUpperCase() })
-          .setTestMode(true);
+          .setTestMode(WANT);
         if (!logged.has(id)) {
           logged.add(id);
-          console.log("[foldspace-dev] test mode ON (" + id + ")");
+          console.log("[foldspace-dev] test mode " + WORD + " (" + id + ")");
         }
       } catch (e) {
         console.warn("[foldspace-dev] setTestMode failed for " + id + ":", e && e.message);
@@ -347,7 +353,7 @@ const testModeSrc = `(() => {
     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);
 
@@ -404,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}`);
   }
@@ -701,6 +710,7 @@ async function prepare(ws, sessionId, url) {
               mode: agentMode,
               namespace: pageState?.namespace || "foldspace",
               aliases,
+              testMode: !noTestMode,
             }),
             hostPatterns,
           ),
@@ -713,7 +723,12 @@ async function prepare(ws, sessionId, url) {
     const scripts = [];
     scripts.push(fs.readFileSync(bundlePath, "utf8"));
     if (!noBadge) scripts.push(badgeSrc);
-    if (!noTestMode) scripts.push(testModeSrc);
+    // 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
+    // test-mode banner under a LIVE corner tag until reload (a customer build,
+    // 2026-09-30).
+    scripts.push(testModeScript(!noTestMode));
     if (bootstrap) {
       scripts.push(
         buildBootstrapScript({
@@ -756,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",
@@ -768,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) {
@@ -819,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) {
@@ -1020,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() {
@@ -1130,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`);
@@ -1156,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 {
@@ -1170,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);

package/bin/cli.mjs

@@ -5,6 +5,7 @@ import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { runInit } from "../src/init.mjs";
+import { isWriteFlag } from "../src/observe-core.mjs";
 import {
   checkForUpdate,
   gateForCommand,
@@ -17,7 +18,6 @@ import {
   runAttachControl,
 } from "../src/attach-daemon.mjs";
 import {
-  CLI_COMMANDS,
   createCliRegistry,
   commandByName,
 } from "../src/cli-registry.mjs";
@@ -75,13 +75,17 @@ function printHelp(topic, json) {
     );
     return;
   }
-  const update = checkForUpdate(resolveProjectDir());
   if (json) {
-    const payload = topic ? document : { ...document, update };
+    // help --json is the first thing the manual reads, so it asks the registry
+    // now (as upgrade does) rather than trusting a 12-hour-old answer; offline,
+    // it falls back to that answer. One command's contract carries no update.
+    const payload = topic
+      ? document
+      : { ...document, update: checkForUpdate(resolveProjectDir(), { preferFresh: true }) };
     console.log(JSON.stringify(payload, null, 2));
     return;
   }
-  nagIfOutdated(update);
+  nagIfOutdated(checkForUpdate(resolveProjectDir()));
   console.log(
     topic ? renderCommandHelp(registry, topic) : renderGeneralHelp(registry),
   );
@@ -112,7 +116,18 @@ function normalizeCommandArgs(command, args) {
     const separator = token.indexOf("=");
     const name = separator > -1 ? token.slice(0, separator) : token;
     const match = options.get(name);
-    if (!match) throw new Error(`unknown option '${name}'`);
+    if (!match) {
+      // The reason matters more than the refusal: observe never writes, and
+      // always prints JSON. The write reason fits only `observe read`.
+      const verb = args.find((item) => !item.startsWith("--"));
+      throw new Error(
+        command.name === "observe" && name === "--json"
+          ? "unknown option '--json': observe always prints JSON."
+          : command.name === "observe" && verb === "read" && isWriteFlag(name)
+            ? `unknown option '${name}': observe read is GET only - it never sets a method, a header or a body.`
+            : `unknown option '${name}'`,
+      );
+    }
     const { option, canonicalName } = match;
     if (seen.has(canonicalName)) {
       throw new Error(`option '${canonicalName}' was provided twice`);
@@ -233,7 +248,9 @@ if (!command || command === "--help" || command === "-h") {
     }
   }
 } else {
-  const names = CLI_COMMANDS.map((entry) => entry.name).join(", ");
+  // The visible commands only: listing deploy here would offer a coding agent
+  // the Foldspace-internal command help hides.
+  const names = registry.commands.map((entry) => entry.name).join(", ");
   fail(
     `unknown command '${command}'. Available commands: ${names}. ` +
       `Run 'foldspace help'.`,

package/bin/inject.mjs

@@ -235,8 +235,8 @@ const chromeArgs = [
   startUrl,
 ];
 
-console.log(`\nLaunching Chrome \u2014 profile ${path.relative(root, profileDir)}, devtools on :${debugPort}.`);
-console.log("Log in to the app once — the profile persists between runs.\n");
+console.log(`\nOpening the test window - profile ${path.relative(root, profileDir)}, debugging port :${debugPort}.`);
+console.log("The human signs in there; the profile keeps what the site remembers between runs.\n");
 
 const child = spawn(chrome, chromeArgs, { detached: true, stdio: "ignore" });
 child.unref();
@@ -254,8 +254,7 @@ if (!owned.ok) {
   }
   console.error(`inject: ${ownershipErrorMessage(owned.reason, {
     port: debugPort,
-    profileDir,
-    root,
+    command: "inject",
   })}`);
   process.exit(1);
 }

package/bin/observe.mjs

@@ -22,6 +22,7 @@ import fs from "node:fs";
 import path from "node:path";
 
 import { CdpPage, parseArgs, printJson, readLaunchState, sleep } from "../src/cdp-client.mjs";
+import { ownershipErrorMessage } from "../src/cdp-ownership.mjs";
 import { withoutStealingFocus } from "../src/keep-focus.mjs";
 import { withWorkingBadge } from "../src/badge-auto.mjs";
 import {
@@ -294,9 +295,7 @@ async function runPages() {
   try {
     targets = await (await fetch(`http://127.0.0.1:${state.port}/json/list`)).json();
   } catch {
-    throw new Error(
-      `The inject Chrome is not answering on :${state.port}. It was closed; run \`npm run inject\` again.`,
-    );
+    throw new Error(ownershipErrorMessage("cdp_not_ready", { port: state.port }));
   }
   const real = targets.filter(
     (target) => target.type === "page" && !String(target.url).startsWith("devtools://"),
@@ -321,7 +320,7 @@ async function runPages() {
       ? {
           hostsHint:
             `The window is on ${off.host}, which this project does not cover (hosts: ${state.hosts.join(", ")}). ` +
-            `If it is part of the product, add "${off.pattern}" to "hosts" in foldspace.dev.json - with the human's yes - then run inject and attach again.`,
+            `If it is part of the product, add "${off.pattern}" to "hosts" in foldspace.dev.json - with the human's yes - then \`npx foldspace attach --stop\`, \`npm run inject\` and \`npx foldspace attach --daemon\` with the flags it ran with. If it is not, ask the human to go back to the product in the test window.`,
         }
       : {}),
   };
@@ -338,7 +337,7 @@ async function runMenu(page) {
     items.push(publicItem(entry));
   }
   const url = await page.evaluate("return location.href;");
-  // Links that leave this host but stay in the product (analyze., admin. ...).
+  // Links that leave this host but stay in the product (reports., admin. ...).
   // Looked for across the whole page: product tiles are often not navigation.
   const leaving = await page
     .evaluate(
@@ -768,7 +767,24 @@ async function runWaitLogin(flags) {
     }
     await sleep(1500);
   }
-  throw new ObserveExit({ ok: false, loggedIn: false, url, ...(lastError ? { lastError } : {}) }, 2);
+  // A last check that failed (window closed, or on a host this project does
+  // not cover) says what to do itself; asking the human would only loop.
+  const secs = Math.round(timeoutMs / 1000);
+  throw new ObserveExit(
+    {
+      ok: false,
+      loggedIn: false,
+      error: lastError
+        ? `No sign-in seen in ${secs} seconds. The last check said: ${lastError}`
+        : `No sign-in seen in ${secs} seconds: the test window still shows a sign-in page (${url}). ` +
+          "Ask the human whether they managed to sign in there. If they have not, run " +
+          "`npx foldspace observe wait-login` again while they do; if they say they are in, run " +
+          "`npx foldspace observe screenshot` and look at the page.",
+      url,
+      ...(lastError ? { lastError } : {}),
+    },
+    2,
+  );
 }
 
 // -------------------------------------------------------------------- main