@foldspace_npm/harness 0.1.4 → 0.1.5

package/README.md

@@ -142,9 +142,10 @@ Use `foldspace help attach` for mode requirements, effects, and safety options.
 ### Verify actions through the agent
 
 `foldspace attach` does not invoke action handlers directly. It loads the local
-artifact, verifies that its action names exactly match the configured SDK agent,
-and then observes action callbacks while you exercise the normal agent
-experience.
+artifact, verifies that the captured local registry matches the configured SDK
+agent — including an empty registry — and then observes action callbacks while
+you exercise the normal agent experience. Named actions are not required to
+attach.
 
 Action output identifies SDK callbacks and local `execute`/`render` phases:
 

package/bin/attach.mjs

@@ -30,6 +30,7 @@ import {
   hostMatches,
   hostPatternsFromTarget,
   parseAgentId,
+  registrationVerified,
 } from "../src/attach-helpers.mjs";
 import {
   buildReplacePrelude,
@@ -294,8 +295,10 @@ const sessionCollector = createSessionCollector();
 // sessionId -> preparation state used for deterministic detach cleanup.
 const prepared = new Map();
 const preparing = new Set();
-// Rejections are scoped to the observed URL so a later navigation can retry.
-const rejected = new Map();
+// Rejections are scoped to the CDP session. SPA URL changes must not retry
+// prepare() on the same tab. Off-host navigation still clears rejected in
+// targetInfoChanged so a later return to the app can retry.
+const rejected = new Set();
 // targetId -> sessionId, so a target that navigates INTO a matching host can be
 // prepared later. Without this, opening Chrome on a new tab and then browsing
 // to the app never arms the swap.
@@ -451,13 +454,7 @@ async function verifyPreparedPage(ws, sessionId) {
           },
         );
         latest.registration = registration;
-        if (
-          observation?.captureCount > 0 &&
-          expectedActionNames.length > 0 &&
-          registration?.agentFound &&
-          registration.missingActionNames?.length === 0 &&
-          registration.unexpectedActionNames?.length === 0
-        ) {
+        if (registrationVerified(observation, registration)) {
           return {
             ok: true,
             state,
@@ -493,9 +490,6 @@ async function verifyPreparedPage(ws, sessionId) {
 }
 
 async function prepare(ws, sessionId, url) {
-  if (rejected.has(sessionId) && rejected.get(sessionId) !== url) {
-    rejected.delete(sessionId);
-  }
   if (
     prepared.has(sessionId) ||
     preparing.has(sessionId) ||
@@ -527,7 +521,7 @@ async function prepare(ws, sessionId, url) {
       pageProductIds,
     });
     if (!guard.ok) {
-      rejected.set(sessionId, url);
+      rejected.add(sessionId);
       logLifecycle(
         createLifecycleResult({
           operation: "prepare_page",
@@ -697,6 +691,11 @@ async function prepare(ws, sessionId, url) {
               verification.registration?.actionNames || [],
             expectedActionNames:
               verification.observation?.expectedActionNames || [],
+            expectedActionCount: Array.isArray(
+              verification.observation?.expectedActionNames,
+            )
+              ? verification.observation.expectedActionNames.length
+              : 0,
             missingActionNames:
               verification.registration?.missingActionNames || [],
             unexpectedActionNames:
@@ -715,7 +714,7 @@ async function prepare(ws, sessionId, url) {
           await cleanupPreparedSession(ws, sessionId, state);
           prepared.delete(sessionId);
         }
-        rejected.set(sessionId, url);
+        rejected.add(sessionId);
       }
     }
   } finally {
@@ -920,7 +919,10 @@ console.log(`Mode:  ${attachMode}`);
 console.log(`Agent: ${agentApiName} (product ${productId}, ${agentMode})`);
 console.log(`Test:  ${noTestMode ? "OFF — conversations WILL appear in the dashboard" : "on"}`);
 console.log(`Hosts: ${hostPatterns.join(", ")}`);
-console.log(`Serving: ${path.relative(root, bundlePath)}\n`);
+console.log(`Serving: ${path.relative(root, bundlePath)}`);
+console.log(
+  `CDP: this process owns the debug port. Detach before using chrome-devtools MCP against the same Chrome.\n`,
+);
 
 function printSessionSummary() {
   if (summaryPrinted) return;

package/package.json

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

package/src/attach-helpers.mjs

@@ -140,6 +140,21 @@ export function actionRequestMatchesTarget(request, target) {
   );
 }
 
+export function registrationVerified(observation, registration) {
+  return Boolean(
+    observation?.installed === true &&
+      observation?.ownerMatches === true &&
+      observation?.actionNameLimitExceeded !== true &&
+      observation?.captureCount > 0 &&
+      Array.isArray(observation.expectedActionNames) &&
+      registration?.agentFound === true &&
+      Array.isArray(registration.missingActionNames) &&
+      registration.missingActionNames.length === 0 &&
+      Array.isArray(registration.unexpectedActionNames) &&
+      registration.unexpectedActionNames.length === 0,
+  );
+}
+
 export function summarizeConsoleMessages(messages, limit = 50) {
   const summaries = new Map();
   for (const message of messages) {

package/src/cli-registry.mjs

@@ -189,12 +189,14 @@ export const CLI_COMMANDS = Object.freeze([
       "May reload and instrument matching target pages",
       "Test mode is enabled unless --no-test-mode is passed",
       "Never directly invokes an action handler",
+      "An empty local action registry is valid; named actions are not required",
       "Restores prepared pages when detached cleanly",
     ],
     next: [
       "Exercise the visible agent normally",
       "Confirm [lifecycle] inspect_registration:registration_ok",
-      "Confirm execute/render observations",
+      "On mismatch, read foldspace help attach --json diagnostics and the lifecycle details",
+      "Confirm execute/render observations when verifying a named action",
       "Detach with Ctrl-C",
     ],
   }),
@@ -305,6 +307,7 @@ export function createCliRegistry({ packageName, packageVersion }) {
       "Capability metadata describes current behavior; it is not hosted-environment enforcement.",
       "Action verification is passive and agent-driven.",
       "The harness bin alias is equivalent to foldspace.",
+      "attach diagnostics are attach-internal; interpret them from the lifecycle log, not as CLI commands.",
     ],
   };
 }

package/templates/agent-starter/CLAUDE.md

@@ -55,7 +55,9 @@ npm run attach
 
 `inject` launches an isolated Chrome profile and records its debug port.
 It does not generate or load an application extension. `attach` prepares the
-page and loads the local `dist/index.js` bundle through CDP.
+page and loads the local `dist/index.js` bundle through CDP. An empty local
+registry is valid: attach before implementing handlers to see how the agent
+works. `npm run build` is still required so `dist/index.js` exists.
 
 Use the default swap only when the page already has the configured product and
 agent. Use `--bootstrap` only when the page has no Foldspace SDK, and
@@ -63,9 +65,14 @@ agent. Use `--bootstrap` only when the page has no Foldspace SDK, and
 present without the configured agent.
 
 The attach log must report `inspect_registration:registration_ok` before
-treating the page as registered. Prove the experience through the visible agent
-and require both an SDK action callback and local execute/render evidence; do
-not invoke the handler directly.
+treating the page as registered. Zero captured actions is success when the
+local registry is empty. On `registration_mismatch`, read
+`npx foldspace help attach --json` diagnostics and map those names onto the
+lifecycle details (`missingActionNames`, `unexpectedActionNames`,
+`diagnosticError`).
+
+Prove a named action through the visible agent and require both an SDK action
+callback and local execute/render evidence; do not invoke the handler directly.
 
 ## Verification gates
 
@@ -73,7 +80,8 @@ Do not report success without all six:
 
 1. TypeScript compiles with `npx tsc --noEmit -p tsconfig.json`.
 2. The expected handler appears in `dist/index.js`.
-3. The browser reports the expected number of attached actions.
+3. The browser reports `inspect_registration:registration_ok`. For a named
+   action, the captured registry includes that handler.
 4. The action behaves correctly against the real target workflow.
 5. Existing neighbouring action fixtures still pass when fixtures exist.
 6. Browser evidence came from the live target, not from hand-authored examples.

package/templates/agent-starter/README.md

@@ -54,7 +54,8 @@ npm run attach   # load local actions and observe the agent over CDP
 
 Run `inject` before `attach`. Sign in to the product in the Chrome window that
 `inject` opens. `inject` does not generate an application extension; `attach`
-loads `dist/index.js` directly through CDP.
+loads `dist/index.js` directly through CDP. An empty local registry is valid,
+so you can attach before implementing handlers.
 
 Choose the attach mode from the state of the target page: