@foldspace_npm/harness 0.1.4 → 0.1.6

package/README.md

@@ -138,13 +138,19 @@ The generated npm scripts intentionally remain the normal project interface;
   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
+returns after `[lifecycle] inspect_registration:…`. Foreground attach remains
+the default for humans watching the terminal. `attach --status` and
+`attach --stop` inspect and tear down a daemon. Observe customer-app network
+traffic after `inject` and before attach; attach owns the debug port.
 
 ### 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:
 
@@ -171,6 +177,7 @@ npm i -D @foldspace_npm/harness
     "build":  "foldspace build",
     "inject": "foldspace inject",
     "attach": "foldspace attach",
+    "attach:daemon": "foldspace attach --daemon",
     "deploy": "foldspace deploy"
 } }
 ```

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;
@@ -1010,7 +1012,7 @@ async function cleanup() {
   return result;
 }
 
-process.on("SIGINT", () => {
+function requestDetach() {
   if (shuttingDown) return;
   shuttingDown = true;
   void cleanup().finally(() => {
@@ -1018,7 +1020,10 @@ process.on("SIGINT", () => {
     console.log(`\nDetached. Served the local bundle ${served} time(s).`);
     process.exit(0);
   });
-});
+}
+
+process.on("SIGINT", requestDetach);
+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

package/bin/cli.mjs

@@ -5,6 +5,10 @@ import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { runInit } from "../src/init.mjs";
+import {
+  classifyAttachControl,
+  runAttachControl,
+} from "../src/attach-daemon.mjs";
 import {
   CLI_COMMANDS,
   createCliRegistry,
@@ -151,10 +155,32 @@ if (!command || command === "--help" || command === "-h") {
   } else {
     try {
       const definition = commandByName(command);
-      runScript(
-        definition.entry,
-        normalizeCommandArgs(definition, args),
-      );
+      const normalized = normalizeCommandArgs(definition, args);
+      if (command === "attach") {
+        const control = classifyAttachControl(normalized);
+        if (control) {
+          Promise.resolve()
+            .then(() =>
+              runAttachControl(control, normalized, {
+                attachScript: path.join(here, definition.entry),
+                spawnFn: spawn,
+              }),
+            )
+            .then((report) => {
+              console.log(JSON.stringify(report, null, 2));
+              if (control === "daemon" && report.ok === false) {
+                process.exitCode = 1;
+              }
+            })
+            .catch((error) => {
+              fail(error instanceof Error ? error.message : String(error));
+            });
+        } else {
+          runScript(definition.entry, normalized);
+        }
+      } else {
+        runScript(definition.entry, normalized);
+      }
     } catch (error) {
       fail(error instanceof Error ? error.message : String(error));
     }

package/package.json

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

package/src/attach-daemon.mjs

@@ -0,0 +1,268 @@
+import fs from "node:fs";
+import path from "node:path";
+
+export const ATTACH_DAEMON_ENV = "FOLDSPACE_ATTACH_DAEMON";
+export const ATTACH_DAEMON_STATE_FILE = "attach-daemon.json";
+export const ATTACH_DAEMON_LOG_FILE = "attach-daemon.log";
+
+const CONTROL_FLAGS = ["--daemon", "--status", "--stop"];
+const LIFECYCLE_PATTERN =
+  /\[lifecycle\] inspect_registration:(registration_ok|registration_mismatch)/g;
+
+export function projectRoot(env = process.env, cwd = process.cwd()) {
+  return env.FOLDSPACE_PROJECT_DIR || cwd;
+}
+
+export function daemonPaths(root) {
+  const dir = path.join(root, ".foldspace-dev");
+  return {
+    dir,
+    stateFile: path.join(dir, ATTACH_DAEMON_STATE_FILE),
+    logFile: path.join(dir, ATTACH_DAEMON_LOG_FILE),
+  };
+}
+
+export function isProcessAlive(pid, killFn = process.kill) {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try {
+    killFn(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export function classifyAttachControl(args) {
+  const selected = CONTROL_FLAGS.filter((flag) => args.includes(flag));
+  if (selected.length > 1) {
+    throw new Error("--daemon, --status, and --stop cannot be used together");
+  }
+  if (selected[0] === "--daemon") return "daemon";
+  if (selected[0] === "--status") return "status";
+  if (selected[0] === "--stop") return "stop";
+  return null;
+}
+
+export function childAttachArgs(args) {
+  return args.filter((token) => !CONTROL_FLAGS.includes(token));
+}
+
+export function parseRegistrationLifecycle(logText) {
+  let last = null;
+  const matches = String(logText ?? "").matchAll(LIFECYCLE_PATTERN);
+  for (const match of matches) {
+    last = {
+      state: match[1],
+      ok: match[1] === "registration_ok",
+    };
+  }
+  return last;
+}
+
+export function readDaemonState(root) {
+  const { stateFile } = daemonPaths(root);
+  try {
+    const parsed = JSON.parse(fs.readFileSync(stateFile, "utf8"));
+    if (!parsed || typeof parsed !== "object") return null;
+    return parsed;
+  } catch {
+    return null;
+  }
+}
+
+export function writeDaemonState(root, state) {
+  const { dir, stateFile } = daemonPaths(root);
+  fs.mkdirSync(dir, { recursive: true });
+  fs.writeFileSync(stateFile, `${JSON.stringify(state, null, 2)}\n`);
+}
+
+export function clearDaemonState(root) {
+  const { stateFile } = daemonPaths(root);
+  try {
+    fs.unlinkSync(stateFile);
+  } catch (error) {
+    if (error?.code !== "ENOENT") throw error;
+  }
+}
+
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+export async function waitForRegistration({
+  logFile,
+  pid,
+  attempts = 60,
+  intervalMs = 250,
+  readFile = fs.readFileSync,
+  isAlive = isProcessAlive,
+  delay = sleep,
+} = {}) {
+  for (let attempt = 0; attempt < attempts; attempt++) {
+    let text = "";
+    try {
+      text = readFile(logFile, "utf8");
+    } catch (error) {
+      if (error?.code !== "ENOENT") throw error;
+    }
+    const registration = parseRegistrationLifecycle(text);
+    if (registration) return registration;
+    if (!isAlive(pid)) {
+      throw new Error(
+        `Attach daemon exited before inspect_registration. Check ${logFile}`,
+      );
+    }
+    await delay(intervalMs);
+  }
+  throw new Error(
+    `Attach daemon did not report inspect_registration. Check ${logFile}`,
+  );
+}
+
+export function liveDaemon(root, isAlive = isProcessAlive) {
+  const state = readDaemonState(root);
+  if (!state?.pid || !isAlive(state.pid)) return null;
+  return state;
+}
+
+function daemonReport(state, extra = {}) {
+  let logText = "";
+  if (state?.logPath) {
+    try {
+      logText = fs.readFileSync(state.logPath, "utf8");
+    } catch {
+      logText = "";
+    }
+  }
+  const registration = parseRegistrationLifecycle(logText);
+  return {
+    daemon: true,
+    pid: state?.pid ?? null,
+    logPath: state?.logPath ?? null,
+    ...(registration
+      ? { ok: registration.ok, registration: registration.state }
+      : {}),
+    ...extra,
+  };
+}
+
+export async function stopAttachDaemon({
+  root,
+  killFn = process.kill,
+  isAlive = isProcessAlive,
+  delay = sleep,
+  attempts = 20,
+  intervalMs = 100,
+} = {}) {
+  const state = readDaemonState(root);
+  if (!state?.pid || !isAlive(state.pid)) {
+    clearDaemonState(root);
+    return { daemon: true, stopped: true, pid: state?.pid ?? null, reused: false };
+  }
+
+  try {
+    killFn(state.pid, "SIGTERM");
+  } catch (error) {
+    if (error?.code !== "ESRCH") throw error;
+  }
+
+  for (let attempt = 0; attempt < attempts; attempt++) {
+    if (!isAlive(state.pid)) break;
+    await delay(intervalMs);
+  }
+  if (isAlive(state.pid)) {
+    try {
+      killFn(state.pid, "SIGKILL");
+    } catch (error) {
+      if (error?.code !== "ESRCH") throw error;
+    }
+  }
+
+  clearDaemonState(root);
+  return { daemon: true, stopped: true, pid: state.pid };
+}
+
+export async function startAttachDaemon({
+  root,
+  attachScript,
+  args,
+  spawnFn,
+  env = process.env,
+  wait = waitForRegistration,
+  isAlive = isProcessAlive,
+  killFn = process.kill,
+} = {}) {
+  const existing = liveDaemon(root, isAlive);
+  if (existing) {
+    return daemonReport(existing, { reused: true, alive: true });
+  }
+
+  const stale = readDaemonState(root);
+  if (stale) clearDaemonState(root);
+
+  const paths = daemonPaths(root);
+  fs.mkdirSync(paths.dir, { recursive: true });
+  fs.writeFileSync(paths.logFile, "");
+  const logFd = fs.openSync(paths.logFile, "a");
+  let child;
+  try {
+    child = spawnFn(process.execPath, [attachScript, ...childAttachArgs(args)], {
+      detached: true,
+      env: { ...env, [ATTACH_DAEMON_ENV]: "1" },
+      stdio: ["ignore", logFd, logFd],
+    });
+  } finally {
+    fs.closeSync(logFd);
+  }
+  if (typeof child.unref === "function") child.unref();
+
+  const state = {
+    pid: child.pid,
+    startedAt: new Date().toISOString(),
+    logPath: paths.logFile,
+  };
+  writeDaemonState(root, state);
+
+  try {
+    const registration = await wait({
+      logFile: paths.logFile,
+      pid: child.pid,
+      isAlive,
+    });
+    return daemonReport(state, {
+      reused: false,
+      ready: true,
+      ok: registration.ok,
+      registration: registration.state,
+    });
+  } catch (error) {
+    if (isAlive(child.pid)) {
+      try {
+        killFn(child.pid, "SIGTERM");
+      } catch {
+        // Best-effort: the wait error is what the caller should see.
+      }
+    }
+    clearDaemonState(root);
+    throw error;
+  }
+}
+
+export async function runAttachControl(control, args, options = {}) {
+  const root = options.root ?? projectRoot(options.env);
+  const isAlive = options.isAlive ?? isProcessAlive;
+  if (control === "status") {
+    const state = readDaemonState(root);
+    if (!state) {
+      return { daemon: false, alive: false, pid: null, logPath: null };
+    }
+    return daemonReport(state, {
+      reused: true,
+      alive: Boolean(state.pid && isAlive(state.pid)),
+    });
+  }
+  if (control === "stop") {
+    return stopAttachDaemon({ root, isAlive, killFn: options.killFn });
+  }
+  return startAttachDaemon({ root, args, isAlive, ...options });
+}

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

@@ -118,7 +118,7 @@ export const CLI_COMMANDS = Object.freeze([
       "Otherwise creates an isolated profile and writes .foldspace-dev/state.json",
       "Does not load the SDK or action artifact",
     ],
-    next: ["Sign in to the target application", "Run foldspace attach"],
+    next: ["Sign in to the target application", "Observe the real workflow, or run foldspace attach"],
   }),
   Object.freeze({
     name: "attach",
@@ -127,7 +127,7 @@ export const CLI_COMMANDS = Object.freeze([
     summary:
       "Load local actions over CDP and observe the normal agent experience",
     usage:
-      "foldspace attach [--bootstrap | --replace] [--target <name>] [--port <number>] [--agent <api-name>] [--no-test-mode] [--no-badge]",
+      "foldspace attach [--bootstrap | --replace] [--daemon | --status | --stop] [--target <name>] [--port <number>] [--agent <api-name>] [--no-test-mode] [--no-badge]",
     risk: "browser-session",
     environment: "local-chrome",
     environmentVariables: [
@@ -178,6 +178,12 @@ export const CLI_COMMANDS = Object.freeze([
         "Do not mark conversations as test traffic; use deliberately",
       ),
       flag("--no-badge", "Hide the visible Foldspace development badge"),
+      flag(
+        "--daemon",
+        "Start attach in the background and return after inspect_registration",
+      ),
+      flag("--status", "Print whether the attach daemon is running"),
+      flag("--stop", "Stop the attach daemon and restore prepared pages"),
     ],
     prerequisites: [
       "foldspace.dev.json",
@@ -189,13 +195,17 @@ 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",
+      "--daemon returns after inspect_registration and keeps CDP in a child process",
     ],
     next: [
+      "Coding agents should use foldspace attach --daemon so the invoking tool returns",
       "Exercise the visible agent normally",
-      "Confirm [lifecycle] inspect_registration:registration_ok",
-      "Confirm execute/render observations",
-      "Detach with Ctrl-C",
+      "Confirm [lifecycle] inspect_registration:registration_ok in the terminal or daemon log",
+      "On mismatch, read foldspace help attach --json diagnostics and the lifecycle details",
+      "After a named action, read [actions] execute/render lines from the attach log",
+      "Detach with Ctrl-C, or foldspace attach --stop for a daemon",
     ],
   }),
   Object.freeze({
@@ -305,6 +315,8 @@ 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.",
+      "Coding agents should run attach --daemon; foreground attach is for humans watching the terminal.",
     ],
   };
 }

package/templates/agent-starter/CLAUDE.md

@@ -15,22 +15,31 @@ changes there.
 3. Inspect the selected agent with `get_agent_settings`, `list_actions`, and
    `list_task_agents`.
 4. Use `discover_actions` to identify candidate experiences, then let the user
-   choose what to build.
+   choose what to build. Treat those ideas as candidates, not an inventory.
 
 ## Build workflow
 
 An experience can require several reusable actions. Separate lookup actions
 from actions that read or mutate a selected resource.
 
-1. Agree on the experience and how its actions compose.
-2. Create the action metadata as a draft.
-3. Ask before publishing when the agent has real users; publishing is a live
-   product change.
-4. Observe the real target workflow and capture its browser requests.
-5. Generate the typed handler skeleton from the published action schema.
-6. Implement the handler using the observed request and response shapes.
-7. Register the handler in `agent/actions/index.ts`.
-8. Complete the verification gates below.
+1. Agree on the candidate experience and how its actions would compose. This is
+   not a publish and not a commitment.
+2. Run `npm run inject`. Ask the user to sign in and perform the real target
+   workflow in that Chrome window.
+3. Capture at least one real HTTP 200 for the data the action needs. Use
+   chrome-devtools MCP against the inject Chrome, or a page-context `fetch`,
+   **before** `attach` owns the debug port. If there is no 200,
+   pivot; do not create Foldspace resources.
+4. Create action metadata as a draft. `generate_action_handler` works from the
+   draft schema; do not publish yet.
+5. Implement the handler using the observed request and response shapes.
+6. Register the handler in `agent/actions/index.ts` and build.
+7. Run `npx foldspace attach --daemon` (add `--bootstrap` or `--replace` when
+   the page requires it). An empty local registry is valid if you only want to
+   see how the agent works.
+8. Ask before publishing. Publishing is required only so the copilot can call
+   the action, and it is a live product change when the agent has real users.
+9. Complete the verification gates below.
 
 ## API rules
 
@@ -38,8 +47,8 @@ Actions execute in the user's signed-in browser session.
 
 - Use the same internal APIs as the product page, with
   `credentials: "include"`.
-- Never guess endpoints or schemas. Capture at least one real request and
-  response before implementing a parser.
+- Never guess endpoints or schemas. Capture at least one real 200 before
+  implementing a parser. Do not implement a path that was not observed.
 - Verify that the user is signed in before observing a workflow.
 - Do not substitute a public developer API when the browser session is missing;
   ask the user to sign in.
@@ -50,12 +59,17 @@ Actions execute in the user's signed-in browser session.
 ```bash
 npm run dev
 npm run inject
-npm run attach
+npx foldspace attach --daemon
 ```
 
 `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.
+It does not generate or load an application extension. Observe the customer's
+workflow after inject and **before** attach, while chrome-devtools MCP can use
+the same Chrome. `attach` prepares the page and loads the local `dist/index.js`
+bundle through CDP. Coding agents must use `--daemon` so the invoking tool
+returns after `[lifecycle] inspect_registration:…`; foreground `npm run attach`
+is for humans watching the terminal. An empty local registry is valid. `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 +77,21 @@ 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`).
+
+While attach is running it owns the debug port. Detach (`attach --stop`, or
+Ctrl-C in the foreground) before using chrome-devtools MCP against the same
+Chrome.
+
+Prove a named action through the visible agent. After the user talks to the
+copilot, read the daemon log for `[actions]` SDK callback and local
+execute/render lines; do not invoke the handler directly. Those lines record
+names, statuses, durations, and parameter keys only — not results or error
+bodies.
 
 ## Verification gates
 
@@ -73,8 +99,11 @@ 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.
-4. The action behaves correctly against the real target workflow.
+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. Confirm
+   `[actions] local-handler:execute` in the attach log after the user exercises
+   the visible agent.
 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

@@ -50,11 +50,17 @@ npm run build    # create dist/index.js
 npm run dev      # rebuild dist/index.js on changes
 npm run inject   # launch the dedicated Chrome profile
 npm run attach   # load local actions and observe the agent over CDP
+npm run attach:daemon  # same, but return after inspect_registration
 ```
 
 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.
+`inject` opens. Observe the real product workflow in that window **before**
+attach if you need customer API evidence; `attach` owns the debug port.
+`inject` does not generate an application extension; `attach` loads
+`dist/index.js` directly through CDP. An empty local registry is valid,
+so you can attach before implementing handlers. Coding agents should use
+`attach --daemon` (or `npm run attach:daemon`) so the command returns after
+registration instead of occupying the terminal.
 
 Choose the attach mode from the state of the target page:
 
@@ -68,10 +74,13 @@ agents can read the versioned contract with `npx foldspace help --json`.
 
 ## Add an action
 
-1. Define and publish the action in Agent Studio or through Product MCP.
-2. Copy `agent/actions/_example.ts` to `agent/actions/<action_key>.ts`.
-3. Implement the handler from observed browser API evidence.
-4. Import and register the handler in `agent/actions/index.ts`.
-5. Type-check, rebuild, attach, and verify it in the target product.
+1. Observe the real product workflow in the inject Chrome and capture a real
+   200 for the API the action will call.
+2. Create the action as a draft in Agent Studio or through Product MCP.
+3. Copy `agent/actions/_example.ts` to `agent/actions/<action_key>.ts`.
+4. Implement the handler from that observed request and response.
+5. Import and register the handler in `agent/actions/index.ts`.
+6. Type-check, rebuild, `attach --daemon`, and verify it through the visible
+   agent. Publish only when the copilot must call the action.
 
-Action keys and parameter names must exactly match the published action schema.
+Action keys and parameter names must exactly match the action schema.

package/templates/agent-starter/package.json

@@ -8,7 +8,8 @@
     "dev": "foldspace build --watch",
     "build": "foldspace build",
     "inject": "foldspace inject",
-    "attach": "foldspace attach"
+    "attach": "foldspace attach",
+    "attach:daemon": "foldspace attach --daemon"
   },
   "devDependencies": {
     "@foldspace_npm/harness": "{{HARNESS_VERSION}}",