@foldspace_npm/harness 0.1.26 → 0.1.28

package/recipes/swap-the-login-method/variants/utils.cookies.ts

@@ -9,13 +9,29 @@ import { AGENT_API_NAME, API_BASE } from "./constants";
 
 configure({ agentApiName: AGENT_API_NAME, apiBase: API_BASE });
 
+/**
+ * Headers the app's own requests carried besides the cookies. Add only what
+ * you OBSERVED: one build needed `x-requested-with: XMLHttpRequest`; most need
+ * none. Both `apiFetch` and `apiFetchBinary` send them.
+ */
+const EXTRA_HEADERS: Record<string, string> = {};
+
 export async function apiFetch<T = unknown>(
   path: string,
   init: RequestInit = {},
   timeoutMs = 15_000,
 ): Promise<ApiResult<T>> {
+  // Empty API_BASE is a failure on purpose: a guessed host cannot look like
+  // success. `error` is drawn on the card and read by the agent - it says what
+  // is true; the builder's hint goes in `detail`, which only the console sees.
   if (!API_BASE) {
-    return { ok: false, status: 0, reason: "config", error: "API_BASE is not set — capture the app's XHR first." };
+    return {
+      ok: false,
+      status: 0,
+      reason: "config",
+      error: "This is not set up yet.",
+      detail: "API_BASE is not set - capture the app's XHR first.",
+    };
   }
 
   const controller = new AbortController();
@@ -25,9 +41,7 @@ export async function apiFetch<T = unknown>(
       ...init,
       credentials: "include",
       signal: controller.signal,
-      // Add only what you OBSERVED the app sending. One build needed
-      // `x-requested-with: XMLHttpRequest`; most do not.
-      headers: { accept: "application/json", "Content-Type": "application/json", ...(init.headers ?? {}) },
+      headers: { accept: "application/json", "Content-Type": "application/json", ...EXTRA_HEADERS, ...(init.headers ?? {}) },
     });
     const text = await res.text();
     let parsed: unknown = text;
@@ -45,8 +59,44 @@ export async function apiFetch<T = unknown>(
   }
 }
 
-// Everything else still comes from the harness. Named, NOT `export *` — that
-// would put the default apiFetch back next to this one.
+/** The same sign-in as `apiFetch`, for a file: the answer comes back as bytes. */
+export async function apiFetchBinary(
+  path: string,
+  init: RequestInit = {},
+  timeoutMs = 15_000,
+): Promise<ApiResult<Uint8Array>> {
+  if (!API_BASE) {
+    return {
+      ok: false,
+      status: 0,
+      reason: "config",
+      error: "This is not set up yet.",
+      detail: "API_BASE is not set - capture the app's XHR first.",
+    };
+  }
+
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    const res = await fetch(`${API_BASE}${path}`, {
+      ...init,
+      credentials: "include",
+      signal: controller.signal,
+      headers: { ...EXTRA_HEADERS, ...(init.headers ?? {}) },
+    });
+    if (!res.ok) return httpFailure(res, "That file could not be returned.");
+    return { ok: true, status: res.status, data: new Uint8Array(await res.arrayBuffer()) };
+  } catch (error) {
+    return networkFailure(error, "Download timed out.", "Could not reach the server.");
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+// Everything else comes from the harness, by name. Give a helper that calls
+// the app's API its own version above, as apiFetch and apiFetchBinary have:
+// the harness's returns a config failure here, because this file sets no
+// `authSource`. For the same reason getAuthToken returns null (see the README).
 export {
   getAgent,
   armAllInstances,
@@ -60,5 +110,8 @@ export {
   renderError,
   renderFatal,
   renderFailure,
+  httpFailure,
+  networkFailure,
+  getAuthToken,
 } from "@foldspace_npm/harness/runtime";
 export type { ApiResult, ApiFailure, FailureReason, ViewHost } from "@foldspace_npm/harness/runtime";

package/recipes/update-meeting-notes/README.md

@@ -4,9 +4,15 @@
 
 **Proven by 1 production build.**
 
-A missing `meetingId` or empty notes fails and names the field that was absent. A missing meeting comes back as `not_found`. The saved result is the note id and the meeting id.
+A missing `meetingId` or empty notes fails and says, in plain words, which one is missing. A missing meeting comes back as `not_found`. The saved result is the note id and the meeting id. A 2xx from the app with no note id comes back as `success: false`, `status: "unconfirmed"`, `reason: "server"`: it is not known whether the note was saved.
 
-In Agent Studio: an action with key `update_meeting_notes` and string parameters `meetingId`, `notes`, and optional `author`.
+In Agent Studio: an action with key `update_meeting_notes` and three string parameters, described as:
+
+- `meetingId`: "The meeting's id. Never taken from the user's words: get it from `<meetings action key>`."
+- `notes`: "The text to save on the meeting."
+- `author` (optional): "The name to put on the note, only when the user gives one - never the agent's own name; leave it out otherwise."
+
+Replace `<meetings action key>` with the key of this agent's action that returns meeting ids; if the agent has none, build that action first - `find-by-name` has the shape. Instructions to set: "No emoji."
 
 ## Adapt it
 
@@ -18,5 +24,5 @@ In Agent Studio: an action with key `update_meeting_notes` and string parameters
 ## What that build learned the hard way
 
 - **Return the id the server created.** "Saved" without an id is not something the next action can use.
-- **Name the missing field.** An empty notes string and a missing meeting are different failures.
-- **This is a live write.** Ask before publishing an edit to an action that already has users.
+- **Say which one is missing.** An empty note and a missing meeting are different failures.
+- **This is a live write.** Running it - with `foldspace ask` or any other way - saves a real note in the signed-in account. Run it yourself only in an account the human named as a test environment; anywhere else, let the human type the question. Publishing it, and every later edit to it, needs the human's yes.

package/recipes/update-meeting-notes/agent/actions/update_meeting_notes.ts

@@ -1,5 +1,6 @@
 // A write, with no card. The result is what was saved: the note id and the
-// meeting id. A missing field is named. A missing meeting is not_found.
+// meeting id. A missing meeting id or note text is said in plain words. A
+// missing meeting is not_found.
 
 import { saveMeetingNote } from "../api/meetings";
 
@@ -10,10 +11,10 @@ export const update_meeting_notes = {
     const author = typeof params?.author === "string" ? params.author.trim() : "";
 
     if (!meetingId) {
-      return { success: false, error: "meetingId was not provided.", reason: "config" };
+      return { success: false, error: "No meeting was given.", reason: "config" };
     }
     if (!notes) {
-      return { success: false, error: "notes were not provided.", reason: "config" };
+      return { success: false, error: "No note text was given.", reason: "config" };
     }
 
     const res = await saveMeetingNote(meetingId, notes, author || undefined);
@@ -22,9 +23,19 @@ export const update_meeting_notes = {
       return { success: false, error: res.error, reason: res.reason };
     }
 
-    const noteId = res.data.note?.id?.trim() || "";
+    // A 2xx without an id is not a failure the app reported: the note may
+    // well be saved. Say exactly that, so it is neither retried as lost nor
+    // reported as saved. The body may be anything - `null`, or a numeric id.
+    const rawId = res.data?.note?.id as unknown;
+    const noteId = typeof rawId === "number" ? String(rawId) : typeof rawId === "string" ? rawId.trim() : "";
     if (!noteId) {
-      return { success: false, error: "The note was not saved.", reason: "server" };
+      return {
+        success: false,
+        status: "unconfirmed",
+        error: "The app answered without a note id, so it is not known whether the note was saved.",
+        reason: "server",
+        data: { meetingId },
+      };
     }
 
     return {

package/recipes/upload-contacts/README.md

@@ -1,12 +1,12 @@
 # Upload contacts — L4
 
-**The user says** "upload these contacts". **The user sees** the import card: a drop zone, a review table, then the result. Nothing is written until they choose Import. Done finishes the card.
+**The user says** "upload these contacts". **The user sees** the import card: a drop zone, a review table, then the result. Nothing is written until they choose Import.
 
 **Proven by 1 production build.**
 
-`awaitUserInput` is set, so the agent is paused until `callback` runs. Cancel, an empty file, a failed import, and a finished import each call `callback`. The callback states what happened: created, skipped, and a reason on each skipped row.
+An input card: `render` uses `callback`, so the agent waits until the card calls it. Cancel, an empty file, a failed import and a finished import each call `callback` once - a finished import as soon as it returns, with `false` so Done and View Contacts still work; those two buttons do not call back. Each callback states what happened; a finished import carries created, skipped, and a reason on each skipped row.
 
-In Agent Studio: an action with key `upload_contacts` and no parameters. The file comes from the card, not from the model.
+In Agent Studio: an action with key `upload_contacts` and no parameters. The file comes from the card, not from the model. Instructions to set: "No emoji. Quote totals and counts exactly as returned; never work them out."
 
 ## Adapt it
 
@@ -14,12 +14,12 @@ In Agent Studio: an action with key `upload_contacts` and no parameters. The fil
 |---|---|
 | `agent/api/contacts.ts` | Mock import path. Find a real API that accepts a list of contacts and returns created and skipped rows |
 | `agent/contacts.ts` | The columns the file actually has |
-| `agent/views/uploader.ts` | The card. `brand.ts` matches the agent's white panel; put the agent's primary colour in `accent` |
+| `agent/views/uploader.ts` | The card. `brand.ts` here is a placeholder: keep the `agent/views/brand.ts` that `npx foldspace observe styles --write` wrote - it has every key the recipe cards read. If the project has none yet, run that command first; do not copy this one |
 
 ## What that build learned the hard way
 
 - **Preview before the write.** Choosing a file is not a request to create records. The write runs when they choose Import.
 - **Invalid rows stay out of the request.** They are reported as skipped, with the reason, and the valid rows are what get posted.
-- **Every path calls `callback`.** Cancel and an empty file included. Leaving the card up without calling it holds the conversation.
+- **Every path calls `callback`.** Cancel and an empty file included. A path that never calls it leaves the agent waiting until the user presses stop.
 - **A failed import is not "Created 0".** Draw the failure and return its `reason`.
 - **"View Contacts" only works where the app listens.** The build's single-page app routed on a message the card posts; other apps do not. ⚠️ Keep the button only if you wire that message, or open the list with a navigation route.

package/recipes/upload-contacts/agent/actions/upload_contacts.ts

@@ -1,6 +1,8 @@
-// The agent waits while the user picks a file, reviews the rows, and imports.
-// Calling callback is mandatory on every finished path. The write happens only
-// after Import. Done is what finishes the card.
+// An input card: the user picks a file, reviews the rows, and imports.
+// render uses callback, so the agent waits until it is called - exactly once
+// on every path: Cancel, an empty file, a failed import, or as soon as the
+// import returns (that one with `false`, so Done and View Contacts still
+// work). The write happens only after Import.
 
 import type { ImportOutcome } from "../contacts";
 import { renderFailure, type ApiFailure, type FailureReason } from "../utils";
@@ -27,8 +29,6 @@ export const upload_contacts = {
     return { success: true, message: "A contact upload is on screen.", data: { cancelled: false } };
   },
 
-  awaitUserInput: true,
-
   render: (
     result: UploadResult | undefined,
     host: HTMLElement,
@@ -63,8 +63,8 @@ export const upload_contacts = {
           true,
         );
       },
-      onDone: (outcome) => {
-        callback(done(outcome), true);
+      onImported: (outcome) => {
+        callback(done(outcome), false);
       },
       onFailed: (failure: ApiFailure) => {
         callback(

package/recipes/upload-contacts/agent/views/brand.ts

@@ -1,25 +1,35 @@
-// The card lives in the agent's panel, which is white by default (the agent's
-// theme: backgroundColor #FFFFFF, primaryColor for accents) - so the palette
-// matches the panel, not the page. Plain hex/rgba only: the panel saves every
-// card to history as an image drawn with html2canvas, which cannot read
-// oklch()/lab()/color-mix(). Take `accent` from the agent's own primaryColor
-// (get_agent_settings); re-sample font and radius from the page if you want
-// them to match; swap for a dark set only when the panel itself is dark.
+// Placeholder with the keys of the agent/views/brand.ts that
+// `npx foldspace observe styles --write` writes. When you copy this recipe,
+// keep the project's own brand.ts; if it has none yet, run that command.
 
 export const brand = {
   surface: "#FFFFFF",
-  border: "#E5E7EB",
+  surface2: "#F5F6FA",
   text: "#374151",
-  textStrong: "#111827",
   muted: "#6B7280",
-  faint: "#9CA3AF",
+  border: "#E5E7EB",
   accent: "#3248F2",
+  accentText: "#FFFFFF",
+  font: 'Roboto, -apple-system, BlinkMacSystemFont, "Segoe UI", Helvetica, Arial, sans-serif',
+  radius: "8px",
+  size: { base: "14px", small: "12px" },
+  textStrong: "#111827",
+  faint: "#9CA3AF",
+  row: "#F9FAFB",
+  tableHead: "#F3F4F6",
   accentDeep: "#2538D6",
-  ok: "#047857",
+  accentSoft: "#EEF0FE",
+  headerStart: "#F0F1FE",
+  good: "#047857",
   warn: "#B45309",
+  warnInk: "#FEF3C7",
   bad: "#B91C1C",
-  tableHead: "#F3F4F6",
+  primary: "#3248F2",
+  tint: "#F3F4F6",
   disabled: "#9CA3AF",
-  font: 'Roboto, -apple-system, BlinkMacSystemFont, "Segoe UI", Helvetica, Arial, sans-serif',
-  radius: "8px",
+  money: "#047857",
+  ok: "#047857",
+  deals: "#3248F2",
+  contacts: "#2538D6",
+  cases: "#B45309",
 } as const;

package/recipes/upload-contacts/agent/views/uploader.ts

@@ -1,6 +1,7 @@
 // The import card from the production build. textContent only — never innerHTML
-// with file data. Styles go in `header`. The write runs only after Import.
-// Done is what finishes the card.
+// with file data. Styles go in `header`. The write runs only after Import. The
+// result goes back as soon as the import returns; Done and View Contacts do not
+// call back.
 
 import { importContacts } from "../api/contacts";
 import { contactName, outcomeFrom, parseContactsCsv, toDraft, type ImportOutcome, type ParsedContact } from "../contacts";
@@ -67,12 +68,12 @@ const UPLOAD_PATH = "M7 16a4 4 0 01-.88-7.903A5 5 0 1115.9 6L16 6a5 5 0 011 9.9M
 const FILE_PATH = "M9 13h6m-3-3v6m5 5H7a2 2 0 01-2-2V5a2 2 0 012-2h5.586a1 1 0 01.707.293l5.414 5.414a1 1 0 01.293.707V19a2 2 0 01-2 2z";
 const REVIEW_PATH = "M9 5H7a2 2 0 00-2 2v12a2 2 0 002 2h10a2 2 0 002-2V7a2 2 0 00-2-2h-2M9 5a2 2 0 002 2h2a2 2 0 002-2M9 5a2 2 0 012-2h2a2 2 0 012 2m-6 9l2 2 4-4";
 const DONE_PATH = "M9 12l2 2 4-4m6 2a9 9 0 11-18 0 9 9 0 0118 0z";
-const UPLOAD_COPY = "Upload a CSV file with your contacts. The file should include columns for firstName, lastName, and email (required). Optional columns: phone, title, accountName.";
+const UPLOAD_COPY = "Upload a CSV file of contacts. It needs first name, last name and email columns; phone, title and account (company) are optional.";
 
 export type UploadHandlers = {
   onCancel: () => void;
   onEmpty: () => void;
-  onDone: (outcome: ImportOutcome) => void;
+  onImported: (outcome: ImportOutcome) => void;
   onFailed: (failure: ApiFailure) => void;
 };
 
@@ -229,7 +230,14 @@ export function mountContactUpload(host: HTMLElement, header: HTMLElement, handl
 
     const cancel = button("fs-up-btn fs-up-secondary", "Cancel");
     cancel.addEventListener("click", () => {
-      report(() => mount(el("div", "fs-up")), () => handlers.onCancel());
+      report(
+        () => {
+          const closed = el("div", "fs-up");
+          closed.append(el("div", "fs-up-sub", "Upload cancelled. No contacts were imported."));
+          mount(closed);
+        },
+        () => handlers.onCancel(),
+      );
     });
 
     card.append(zone, actions(cancel));
@@ -291,7 +299,7 @@ export function mountContactUpload(host: HTMLElement, header: HTMLElement, handl
       parsed = [];
       showUpload();
     });
-    const confirm = button("fs-up-btn fs-up-primary", `Import ${ready.length} Contacts`);
+    const confirm = button("fs-up-btn fs-up-primary", `Import ${ready.length} ${ready.length === 1 ? "Contact" : "Contacts"}`);
     confirm.disabled = ready.length === 0;
     confirm.addEventListener("click", async () => {
       if (settled || busy || ready.length === 0) return;
@@ -300,12 +308,16 @@ export function mountContactUpload(host: HTMLElement, header: HTMLElement, handl
       const res = await importContacts(ready.map(toDraft));
       if (!res.ok) {
         report(
-          () => renderFailure(host, res, { notFound: "No import endpoint answered." }),
+          () => renderFailure(host, res, { notFound: "Contacts cannot be imported here." }),
           () => handlers.onFailed(res),
         );
         return;
       }
-      showResults(outcomeFrom(parsed, res.data));
+      const outcome = outcomeFrom(parsed, res.data);
+      report(
+        () => showResults(outcome),
+        () => handlers.onImported(outcome),
+      );
     });
     card.append(actions(back, confirm));
     mount(card);
@@ -318,7 +330,7 @@ export function mountContactUpload(host: HTMLElement, header: HTMLElement, handl
     const head = el("div", "fs-up-head");
     head.append(row, el("div", "fs-up-sub", "Please wait while we import your contacts. This may take a moment for large files."));
     const wait = el("div", "fs-up-wait");
-    wait.append(el("div", "fs-up-spin is-lg"), el("div", "fs-up-wait-text", `Processing ${count} contacts...`));
+    wait.append(el("div", "fs-up-spin is-lg"), el("div", "fs-up-wait-text", `Processing ${count} ${count === 1 ? "contact" : "contacts"}...`));
     card.append(head, wait);
     mount(card);
   };
@@ -377,16 +389,15 @@ export function mountContactUpload(host: HTMLElement, header: HTMLElement, handl
       card.append(section);
     }
 
-    const finish = () => report(() => {}, () => handlers.onDone(outcome));
+    // The agent already has the result. These buttons only act on the card.
     const view = button("fs-up-btn fs-up-secondary", "View Contacts");
-    view.addEventListener("click", () => {
-      // callback first: a navigation that unloads the page must not lose it.
-      finish();
-      go("/__observe_me/contacts");
-    });
+    view.addEventListener("click", () => go("/__observe_me/contacts"));
     const done = button("fs-up-btn fs-up-primary", "Done");
-    done.addEventListener("click", finish);
-    card.append(actions(view, done));
+    const buttons = actions(view, done);
+    done.addEventListener("click", () => {
+      buttons.textContent = "";
+    });
+    card.append(buttons);
     mount(card);
   };
 

package/recipes/who-is-the-user/README.md

@@ -30,8 +30,10 @@ import { identifyUser } from "../identify";
 identifyUser();
 ```
 
-Custom attributes (a plan name, a sign-up date) only land if they were created
-first in **Settings → Attribute Settings**; send them under their API Name.
+Built-in user attributes need no setup: `id`, `email`, `name`, `role`,
+`image`, `phone`, `timezone`, `signUpDate`. A custom one (a plan name, say)
+lands only if it was created first in **Settings → Attribute Settings**; send
+it under its API Name. <https://docs.foldspace.ai/user-guides/settings/attributes/>
 
 ## What those builds learned the hard way
 
@@ -49,7 +51,9 @@ first in **Settings → Attribute Settings**; send them under their API Name.
 - **A failed identify must not break the agent.** Every failure is silent to the
   user, and releases the flag so a later load can try again.
 - **Hide the agent until identify resolves, with a timeout** — and on a page
-  with no signed-in user (the login page), do not show it at all.
+  with no signed-in user (the login page), do not show it at all. This recipe
+  does not do it; to add it, call `getAgent()?.hide()` /
+  `getAgent()?.show()` (<https://docs.foldspace.ai/reference/visibility-api/>).
 - **This is unsigned.** Anyone can call `foldspace.identify` from a console.
   Signing has to come from the customer's backend
   (<https://docs.foldspace.ai/security/overview/>); until then treat the

package/src/ask-core.mjs

@@ -1,4 +1,4 @@
-// Pure helpers behind `foldspace ask`: deciding when the assistant has finished
+// Pure helpers behind `foldspace ask`: deciding when the agent 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.
 
@@ -109,12 +109,24 @@ export function summarizeHandlerLog(logText) {
   };
 }
 
+// execute/render come from the log the attach daemon writes. With no daemon
+// running - the page runs published code, see `foldspace published` - there is
+// no log to read, so they are reported as not tracked rather than as absent.
+export const NOT_TRACKED = "not tracked here (published code)";
+
+export function untrackedHandler() {
+  return { execute: NOT_TRACKED, render: NOT_TRACKED, actions: [], lines: [] };
+}
+
+// Without the log only a card counts: an action that answers with data and
+// draws no card reads as not fired, and --retry asks again.
 export function actionFired(handler, hasCard) {
-  return Boolean(hasCard) || handler?.execute !== "absent" || handler?.render !== "absent";
+  const ran = (status) => status !== "absent" && status !== NOT_TRACKED;
+  return Boolean(hasCard) || ran(handler?.execute) || ran(handler?.render);
 }
 
 /**
- * Re-ask only for publish lag: the assistant answered from knowledge because
+ * Re-ask only for publish lag: the agent 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.
  */
@@ -131,7 +143,7 @@ export function numberFlag(value, fallback) {
     : fallback;
 }
 
-// ---- `foldspace run`: describe what a handler returned without printing it ----
+// ---- Describe what a handler returned without printing it ----
 
 function typeOf(value) {
   if (value === null) return "null";

package/src/attach-daemon.mjs

@@ -76,11 +76,16 @@ export function rejectionAdvice(code) {
     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 "The page's Foldspace agent is not the one this project is set up for (another agent or product, or one that could not be confirmed). Run: npx foldspace attach --replace --daemon";
   }
   return null;
 }
 
+/** Where to read why registration did not match: attach prints it under the lifecycle line. */
+export function mismatchNext(logPath) {
+  return `Read the lines under "[lifecycle] inspect_registration:registration_mismatch" in ${logPath}: they name what differs and the next step.`;
+}
+
 export function readDaemonState(root) {
   const { stateFile } = daemonPaths(root);
   try {
@@ -162,7 +167,7 @@ function daemonReport(state, extra = {}) {
     }
   }
   const registration = parseRegistrationLifecycle(logText);
-  return {
+  const report = {
     daemon: true,
     pid: state?.pid ?? null,
     logPath: state?.logPath ?? null,
@@ -171,6 +176,8 @@ function daemonReport(state, extra = {}) {
       : {}),
     ...extra,
   };
+  if (report.registration === "registration_mismatch") report.next = mismatchNext(report.logPath);
+  return report;
 }
 
 export async function stopAttachDaemon({

package/src/attach-helpers.mjs

@@ -15,6 +15,19 @@ export function attachModeFromArgs(argv) {
   return ATTACH_MODES.SWAP;
 }
 
+/**
+ * The flags to start attach again with, so a restart keeps what this one ran
+ * with: its mode, test mode (a restart without --test-mode turns it off) and
+ * --no-badge. Leading space; empty for a plain swap attach.
+ */
+export function attachAgainFlags({ mode, testMode = false, noBadge = false } = {}) {
+  return (
+    (mode === ATTACH_MODES.REPLACE ? " --replace" : mode === ATTACH_MODES.BOOTSTRAP ? " --bootstrap" : "") +
+    (testMode === true ? " --test-mode" : "") +
+    (noBadge === true ? " --no-badge" : "")
+  );
+}
+
 function present(value) {
   if (value == null) return null;
   const text = String(value);
@@ -172,6 +185,98 @@ export function actionRequestMatchesTarget(request, target) {
   );
 }
 
+/**
+ * What the log says under `inspect_registration:registration_mismatch`, so
+ * the model reads the difference instead of hunting for it: whether the page's
+ * agent, product or panel is not this project's, which action names differ,
+ * the diagnostic error, and one next step. `details` is the lifecycle result's
+ * details; the log prints only `lines` and `next`, never the fields.
+ */
+export function registrationMismatchReport(details = {}) {
+  const list = (value) => (Array.isArray(value) ? value.filter((item) => typeof item === "string") : []);
+  const missing = list(details.missingActionNames);
+  const unexpected = list(details.unexpectedActionNames);
+  const agents = list(details.detectedAgentIds);
+  const products = list(details.detectedProductIds);
+  const expectedAgent = details.expectedAgentId;
+  const expectedProduct = details.expectedProductId;
+  const lines = [];
+  const noAgent = agents.length === 0;
+  const otherAgent = Boolean(expectedAgent) && !noAgent && !agents.includes(expectedAgent);
+  const moreAgents = Boolean(expectedAgent) && agents.length > 1 && agents.includes(expectedAgent);
+  const otherProduct = Boolean(expectedProduct) && products.length > 0 && !products.includes(expectedProduct);
+  const unknownProduct = Boolean(expectedProduct) && !noAgent && products.length === 0;
+  // Only --replace requires this project's panel to be the one visible.
+  const widget = details.mode === ATTACH_MODES.REPLACE && details.widget ? details.widget : null;
+  const visibleCount = widget ? Number(widget.visibleCount) || 0 : 0;
+
+  if (noAgent) lines.push(`Agent: no Foldspace agent started on the page; this project is set up for ${expectedAgent}.`);
+  if (otherAgent) lines.push(`Agent: this project is set up for ${expectedAgent}; the page has ${agents.join(", ")}.`);
+  if (moreAgents) lines.push(`Agent: the page has ${agents.join(", ")} - more than this project's ${expectedAgent}.`);
+  if (otherProduct) lines.push(`Product: this project is set up for ${expectedProduct}; the page has ${products.join(", ")}.`);
+  if (unknownProduct) {
+    lines.push(`Product: the page's agent does not say which product it is; this project is set up for ${expectedProduct}.`);
+  }
+  if (widget && visibleCount === 0) {
+    lines.push("Panel: no agent panel is visible on the page.");
+  } else if (widget && visibleCount > 1) {
+    lines.push(`Panel: ${visibleCount} agent panels are visible; --replace needs this project's to be the only one.`);
+  } else if (widget && widget.ownerMatches !== true) {
+    lines.push("Panel: the visible panel is not this project's agent panel.");
+  }
+  // The action checks run only once the agent, product and panel match.
+  if (!lines.length) {
+    if (details.actionObserverInstalled === false || details.actionCaptureCount === 0) {
+      lines.push("Actions: the page's agent never took this build's actions.");
+    }
+    if (details.actionNameLimitExceeded === true) {
+      lines.push("Actions: this build has more than 200 action names; attach checks at most 200, so it cannot confirm them.");
+    }
+  }
+  if (missing.length) {
+    lines.push(`Missing - in this build, not registered on the page's agent: ${missing.join(", ")}`);
+  }
+  if (unexpected.length) {
+    lines.push(`Unexpected - registered on the page's agent, not in this build: ${unexpected.join(", ")}`);
+  }
+  if (details.diagnosticError) lines.push(`Diagnostic error: ${details.diagnosticError}`);
+
+  const sameMode = attachAgainFlags(details);
+  // Switching to --replace keeps the rest of what this attach ran with.
+  const asReplace = attachAgainFlags({ ...details, mode: ATTACH_MODES.REPLACE });
+  const once =
+    `run \`npx foldspace attach --stop\`, then \`npx foldspace attach${sameMode} --daemon\` once; if the same lines come back, ` +
+    "tell the human in one sentence that the test window could not load the latest changes to their agent.";
+  let next;
+  if (noAgent && details.mode !== ATTACH_MODES.SWAP) {
+    // bootstrap and replace start the agent from foldspace.dev.json.
+    next =
+      "check `productId`, `agentApiName` (the Agent Key) and `region` in foldspace.dev.json against the agent in " +
+      "Agent Studio, and correct any that differ with the human's yes. Then run `npx foldspace attach --stop`, " +
+      `then \`npx foldspace attach${sameMode} --daemon\` once; if the same lines come back, tell the human in one ` +
+      "sentence that their agent could not be started in the test window.";
+  } else if ((otherAgent || moreAgents || otherProduct || unknownProduct) && details.mode !== ATTACH_MODES.REPLACE) {
+    next = `run \`npx foldspace attach --stop\`, then \`npx foldspace attach${asReplace} --daemon\`: the page's Foldspace agent is not this project's.`;
+  } else if (missing.length || unexpected.length) {
+    next =
+      "compare these names with agent/actions/index.ts. If the code changed since the last build: `npm run build`, " +
+      `\`npx foldspace attach --stop\`, then \`npx foldspace attach${sameMode} --daemon\`. If it did not, ${once}`;
+  } else {
+    if (!lines.length) {
+      lines.push(
+        `Details: ${JSON.stringify({
+          mode: details.mode ?? null,
+          actionObserverInstalled: details.actionObserverInstalled ?? null,
+          actionCaptureCount: details.actionCaptureCount ?? null,
+          agentFound: details.agentFound ?? null,
+        })}`,
+      );
+    }
+    next = once;
+  }
+  return { lines, next };
+}
+
 export function registrationVerified(observation, registration) {
   return Boolean(
     observation?.installed === true &&