@foldspace_npm/harness 0.1.9 → 0.1.11

package/CLAUDE.md

@@ -0,0 +1,235 @@
+# Foldspace Agent
+
+## Harness version
+
+At the start of a session, run `npx foldspace help --json` (or, from an older
+install, `npx --yes @foldspace_npm/harness@latest upgrade --check`).
+
+If `update.outdated` is true, tell the user the pinned and latest versions and
+**ask before upgrading**. After they agree, run `foldspace upgrade --yes`, then
+`npm run build`. Do not upgrade as a side effect of build, attach, or
+implementing an action. A harness bump is not a deploy.
+
+If the tenant `CLAUDE.md` does not contain
+`@node_modules/@foldspace_npm/harness/CLAUDE.md`, ask before
+`foldspace upgrade --refresh-instructions`. That replaces the snapshot with an
+import of this file.
+
+## Before building
+
+1. Run `npx foldspace help --json` before an unfamiliar harness operation.
+   Treat its risk, prerequisites, effects, next-step, and `update` fields as
+   the current CLI contract.
+2. Connect Product MCP and verify that `list_agents` works.
+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. 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 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. Write what you establish into
+   `docs/app-profile.md` with **how you know it**. Do not promote an assumption
+   by quoting that file.
+4. Create action metadata as a draft. `generate_action_handler` works from a
+   draft schema; do not publish yet.
+5. Implement the handler using the observed request and response shapes.
+   Import helpers from `agent/utils.ts` — inspect that file before writing
+   another `fetch` or rank helper.
+6. Register the handler in `agent/actions/index.ts` and build (`foldspace build` lints first).
+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
+
+Actions execute in the user's signed-in browser session.
+
+- Import HTTP, ranking, and widget helpers from `../utils`, not a new
+  `agent/api.ts` copy of `fetch`.
+- Do not guess `API_BASE` or `AUTH_SOURCE`. Capture at least one real 200
+  (and the auth header the page actually sends) before filling them in.
+  `credentials: "include"` is correct only when you have observed the app
+  using cookies that way. Many apps use `Authorization: Bearer` from
+  `localStorage` instead; some use a custom header.
+- 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.
+- Validate parameters and return sanitized errors. Return **data only** — never
+  `directive`, `instructions`, or a paragraph telling the copilot what to say.
+  Action and agent instructions live in Agent Studio / MCP. Never return
+  `ApiResult.detail` from `execute` — it is for the console.
+- Actions that return data the user will inspect should include a `render`
+  function for in-chat UI (a chatterblock). If it makes more sense to output the data
+  in a UI component instead of text then consider using render to show a component.
+   - `render` receives **`execute`'s return value**, not the action's input params.
+     Returning anything that lacks the ids the card needs is why widgets pass in
+     isolation and fail in the real chat.
+   - `runAction` refuses render actions (`cannot be executed silently`). Driving
+     `render()` yourself never runs `execute()`, so it does not test that contract.
+   - Check https://docs.foldspace.ai/guides/in-chat-ui/ for more information
+
+## Task agents
+
+Use a Task Agent when the handler needs a one-time LLM subtask that
+deterministic code cannot do well: extraction, summarization,
+classification, normalization, enrichment, or generation.
+
+Do not use a Task Agent for API calls, CRUD, routing, or parsing a
+known response shape. Those stay in `execute`.
+
+Task agents are created in Agent Studio, not in this repo. Ask before
+creating or publishing one. Call a published task agent from the
+handler with `runTask({ taskKey, data })` (if not published the runTask won't work).
+`data` carries extracted facts only — not `prompt` / `instructions` strings.
+Prefer JSON output when the handler must consume the result.
+
+See https://docs.foldspace.ai/user-guides/task-agents/ and
+https://docs.foldspace.ai/reference/task-agent-api/
+
+## Local harness loop
+
+```bash
+npm run dev
+npm run inject
+npx foldspace attach --daemon
+```
+
+`inject` launches an isolated Chrome profile and records its debug port.
+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
+`--replace` when it embeds a different product or agent, or when an SDK is
+present without the configured agent.
+
+The attach log must report `inspect_registration:registration_ok` before
+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.
+
+## Product defaults
+
+These are not product-specific. Lint can catch some of them in handler code;
+Agent Studio copy is on you.
+
+- **No emoji** in copilot replies, cards, or handler strings. Put that in the
+  agent's Behavior instructions (MCP cannot write that field, so each new
+  action's Studio `instructions` must carry the line too).
+- **Never send the user out of the host app.** No "open in <product>"
+  button and no pasted URLs — navigate with a navigation route, same tab.
+- **Check row counts before choosing the experience.** On an empty account the
+  useful first action is one that creates data.
+
+## Verification gates
+
+Do not report success without all six:
+
+1. TypeScript compiles with `npm run typecheck` (`tsc --noEmit -p tsconfig.json`).
+   Do not run `npx tsc` — that can install the wrong package.
+2. `foldspace lint` reports no errors (`foldspace build` runs this first).
+3. The expected handler appears in `dist/index.js`.
+4. The browser reports `inspect_registration:registration_ok`. For a named
+   action, the captured registry includes that handler.
+5. 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. For a widget, that log must include `local-handler:render`
+   from a real chat turn — not a hand-built `render()` call.
+6. Browser evidence came from the live target, not from hand-authored examples.
+   Neighbour fixtures still pass when they exist.
+
+## Layout
+
+- `agent/actions/` — one handler per action (`execute`, optional `render`),
+  registered in `index.ts`
+- `agent/api/` — one HTTP helper per endpoint
+- `agent/constants.ts` — agent, product, domain, plus empty `API_BASE` /
+  `AUTH_SOURCE` and `LOAD_MODE`
+- `agent/utils.ts` — configure the harness runtime and re-export it. **This is
+  the only import surface for actions.**
+- `foldspace.dev.json` — local harness target configuration
+- `docs/app-profile.md` — what is known about this app, and how it was established
+- `CLAUDE.md` — this file, imported — plus what is specific to this product
+
+Do not introduce another bundler or bundle format.
+
+## What you already have
+
+Import from `../utils`. Inspect that file before implementing another
+general-purpose helper. MCP `generate_action_handler` may still emit a
+skeleton that does not import it — fix the import when you implement.
+
+| Helper | Use when | Do not use when |
+|---|---|---|
+| `apiFetch` / `apiFetchBinary` | The app's own JSON/file API, after a real 200 | Public marketing hosts (`publicFetch`); custom auth headers |
+| `publicFetch` | Unauthenticated / marketing origin | Signed-in product APIs |
+| `getAuthToken` / `parseJwt` | `AUTH_SOURCE` is `localStorage` or `cookie` | Custom header schemes — override `apiFetch` in `utils.ts` |
+| `rankBy` | User typed a name; API search is exact or ignored | Domain ranking (invoices, coverage, MasterFormat) |
+| `renderLoading` / `Empty` / `Error` / `Fatal` | Chatterblock empty/error paths | Branded cards — those stay in `agent/views/` |
+| `getAgent` | Talking to Foldspace | You need a specific instance — then `agentIds()` |
+| `armAllInstances` | Attach/bootstrap setup | Inside `execute` (can ship into `dist`; attach already arms test mode) |
+| `redact` / `mapWithConcurrency` | Logging tokens; batching fetches | — |
+
+If the observed auth is not Bearer + `localStorage`/`cookie`, stop re-exporting
+that one function and keep the rest:
+
+```ts
+export { getAgent, rankBy, renderEmpty } from "@foldspace_npm/harness/runtime";
+export { apiFetch } from "./api";
+```
+
+## Agent learnings
+
+`docs/app-profile.md` is the durable record of this app. Fill it as you probe,
+not afterwards. Other notes in `docs/` are fine for session-specific lessons.
+
+- Before similar work, read `docs/app-profile.md` and any other notes in `docs/`.
+- After non-obvious discoveries, add them to the profile (or a short extra
+  note) covering verified gotchas, failed approaches, and how they were
+  established.
+- Keep notes concise and evidence-based.
+- Do not store secrets, cookies, HAR files, browser storage, or other transient
+  session data in `docs/`.
+
+## Safety
+
+- Do not commit secrets, cookies, HAR files, browser storage, or
+  `.foldspace-dev/`.
+- Local handler changes are not cloud publication.
+- Creating or publishing Foldspace resources requires explicit approval.
+- Action keys and parameter names must match the published schema.
+- Search Foldspace documentation before asserting unfamiliar platform
+  behaviour.

package/README.md

@@ -97,7 +97,7 @@ Non-interactive / CI form:
 npx --yes @foldspace_npm/harness init foldspace-agent \
   --product-id FR8JUQZAQRZB \
   --agent-key my-agent \
-  --domain app.example.com \
+  --app-domain app.example.com \
   --name "My Agent"
 ```
 
@@ -107,14 +107,15 @@ When running directly from a harness checkout during development:
 node bin/cli.mjs init ../foldspace-agent \
   --product-id FR8JUQZAQRZB \
   --agent-key my-agent \
-  --domain app.example.com
+  --app-domain app.example.com
 ```
 
 The Agent Key is the value shown in Agent Studio, such as `my-agent`. It is
 not the sidecar directory name. `--agent-api-name` remains a deprecated alias
-for `--agent-key`. `--name` is optional and defaults to the target directory
+for `--agent-key`. `--domain` remains a deprecated alias for `--app-domain`.
+`--name` is optional and defaults to the target directory
 name (`foldspace-agent` unless you pass a directory). The product ID must be
-the bare ID, not the `EU-…-1-1` SDK loader key. The domain may be a hostname
+the bare ID, not the `EU-…-1-1` SDK loader key. The app domain may be a hostname
 or an HTTP(S) URL without a port or path.
 
 For safety, `init` requires a target path that does not exist. It does not
@@ -132,6 +133,24 @@ npm run attach
 The generated npm scripts intentionally remain the normal project interface;
 `foldspace init` is the one-time project creation command.
 
+Generated `CLAUDE.md` imports platform instructions from
+`@foldspace_npm/harness` instead of copying them. Existing projects can switch
+to that import with `foldspace upgrade --refresh-instructions`.
+
+### Keep the harness current
+
+Tenant projects pin an exact `@foldspace_npm/harness` version. Publishing a
+newer package does not move them. Check, ask the user, then bump:
+
+```bash
+npx --yes @foldspace_npm/harness@latest upgrade --check
+foldspace upgrade --yes   # only after the user agrees
+```
+
+`--check` (and a non-interactive `upgrade` with no `--yes`) never installs.
+`--yes` rewrites the exact pin and runs `npm install --ignore-scripts`. Rebuild
+afterward; that is still not a deploy.
+
 ### Lint handlers before they ship
 
 `foldspace build` runs `foldspace lint` first. Errors skip bundling; warnings

package/bin/attach.mjs

@@ -31,6 +31,7 @@ import {
   hostPatternsFromTarget,
   parseAgentId,
   registrationVerified,
+  resolveAttachLaunch,
 } from "../src/attach-helpers.mjs";
 import {
   buildReplacePrelude,
@@ -47,6 +48,12 @@ import {
   createLifecycleResult,
 } from "../src/protocol.mjs";
 import { createCdpRequestManager } from "../src/cdp-request-manager.mjs";
+import {
+  assertOwnedCdp,
+  chromeProfileDir,
+  ownershipErrorMessage,
+  verifyLaunchSentinel,
+} from "../src/cdp-ownership.mjs";
 import { buildActionObserverScript } from "../src/action-observer.mjs";
 import { buildBootstrapScript } from "../src/bootstrap-script.mjs";
 import {
@@ -61,8 +68,8 @@ const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const root = process.env.FOLDSPACE_PROJECT_DIR || process.cwd();
 const bundlePath = path.join(root, "dist", "index.js");
 
-// Prefer what inject actually launched, then an explicit override, then the
-// legacy default. Guessing here means attaching to the wrong browser.
+// Prefer an explicit override, then the port inject recorded. Do not guess
+// 9222 — that is how we attach to a different browser than the one we launched.
 function readDevState() {
   try {
     return JSON.parse(
@@ -82,18 +89,42 @@ const explicitPort =
   portArgIndex > -1 ? process.argv[portArgIndex + 1] : null;
 const explicitTarget =
   targetArgIndex > -1 ? process.argv[targetArgIndex + 1] : null;
-const savedLaunchMatches =
-  !explicitTarget || explicitTarget === devState.target;
-const useSavedLaunch =
-  !explicitPort &&
-  !process.env.CDP_PORT &&
-  savedLaunchMatches;
-const port = String(
-  explicitPort ||
-    process.env.CDP_PORT ||
-    (useSavedLaunch ? devState.debugPort : null) ||
-    "9222",
-);
+const { useSavedLaunch, port } = resolveAttachLaunch({
+  explicitPort,
+  envPort: process.env.CDP_PORT,
+  explicitTarget,
+  savedTarget: devState.target,
+  savedDebugPort: devState.debugPort,
+});
+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.`,
+  );
+  process.exit(1);
+}
+const profileDir = chromeProfileDir(root);
+const claimed = verifyLaunchSentinel({
+  profileDir,
+  token: devState.sentinel,
+});
+if (!claimed.ok) {
+  console.error(
+    `attach: ${ownershipErrorMessage(claimed.reason, { port, profileDir, root })}`,
+  );
+  process.exit(1);
+}
+const owned = await assertOwnedCdp({
+  profileDir,
+  port,
+  token: devState.sentinel,
+});
+if (!owned.ok) {
+  console.error(
+    `attach: ${ownershipErrorMessage(owned.reason, { port, profileDir, root })}`,
+  );
+  process.exit(1);
+}
 let attachMode;
 try {
   attachMode = attachModeFromArgs(process.argv.slice(2));
@@ -883,8 +914,8 @@ let ws;
 // temporal dead zone, throwing instead of reconnecting.
 const keepAlive = setInterval(() => {}, 1 << 30);
 
-async function connect() {
-  const ver = await (await fetch(`http://localhost:${port}/json/version`)).json();
+async function connect(version) {
+  const ver = version;
   const socket = new WebSocket(ver.webSocketDebuggerUrl);
   await new Promise((resolve, reject) => {
     socket.onopen = resolve;
@@ -912,7 +943,7 @@ async function connect() {
   return ver;
 }
 
-const ver = await connect();
+const ver = await connect(owned.version);
 
 console.log(`Attached to ${ver.Browser} on :${port}`);
 console.log(`Mode:  ${attachMode}`);

package/bin/cli.mjs

@@ -5,6 +5,12 @@ import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { runInit } from "../src/init.mjs";
+import {
+  checkForUpdate,
+  nagIfOutdated,
+  resolveProjectDir,
+  runUpgrade,
+} from "../src/upgrade.mjs";
 import {
   classifyAttachControl,
   runAttachControl,
@@ -56,10 +62,13 @@ function printHelp(topic, json) {
     );
     return;
   }
+  const update = checkForUpdate(resolveProjectDir());
   if (json) {
-    console.log(JSON.stringify(document, null, 2));
+    const payload = topic ? document : { ...document, update };
+    console.log(JSON.stringify(payload, null, 2));
     return;
   }
+  nagIfOutdated(update);
   console.log(
     topic ? renderCommandHelp(registry, topic) : renderGeneralHelp(registry),
   );
@@ -118,6 +127,7 @@ const [command, ...args] = process.argv.slice(2);
 if (!command || command === "--help" || command === "-h") {
   printHelp(null, args.includes("--json"));
 } else if (command === "--version" || command === "-v") {
+  nagIfOutdated(checkForUpdate(resolveProjectDir()));
   console.log(
     `${registry.package.name} ${registry.package.version} ` +
       `(protocol ${registry.protocolVersion}, CLI schema ${registry.schemaVersion})`,
@@ -149,6 +159,24 @@ if (!command || command === "--help" || command === "-h") {
       fail(error instanceof Error ? error.message : String(error));
     }
   }
+} else if (command === "upgrade") {
+  if (args.includes("--help") || args.includes("-h")) {
+    printHelp("upgrade", args.includes("--json"));
+  } else {
+    try {
+      const normalized = normalizeCommandArgs(commandByName("upgrade"), args);
+      Promise.resolve()
+        .then(() => runUpgrade(normalized))
+        .then((report) => {
+          console.log(JSON.stringify(report, null, 2));
+        })
+        .catch((error) => {
+          fail(error instanceof Error ? error.message : String(error));
+        });
+    } catch (error) {
+      fail(error instanceof Error ? error.message : String(error));
+    }
+  }
 } else if (commandByName(command)) {
   if (args.includes("--help") || args.includes("-h")) {
     printHelp(command, args.includes("--json"));

package/bin/inject.mjs

@@ -15,6 +15,11 @@ import fs from "fs";
 import path from "path";
 import os from "os";
 import { spawn } from "child_process";
+import {
+  ownershipErrorMessage,
+  waitForOwnedCdp,
+  writeLaunchSentinel,
+} from "../src/cdp-ownership.mjs";
 
 // Resolve the CONSUMING repo, not this package. FOLDSPACE_PROJECT_DIR lets a
 // hosted builder point the harness at a workspace it controls.
@@ -180,26 +185,7 @@ if (!chrome) {
 fs.mkdirSync(profileDir, { recursive: true });
 
 const debugPort = args.port || "9222";
-
-// Record it so attach does not have to be told again. inject and attach
-// disagreeing about the port is how you end up attached to a different
-// browser than the one you launched.
-fs.mkdirSync(workDir, { recursive: true });
-fs.writeFileSync(
-  path.join(workDir, "state.json"),
-  JSON.stringify(
-    {
-      debugPort,
-      target: targetName,
-      resolvedTarget: {
-        ...target,
-        sdkUrl: cfg.sdkUrl,
-      },
-    },
-    null,
-    2,
-  ),
-);
+const sentinel = writeLaunchSentinel(profileDir);
 
 // Name the profile so this window is identifiable among other Chrome windows.
 function nameProfile() {
@@ -244,6 +230,7 @@ const chromeArgs = [
   "--no-first-run",
   "--no-default-browser-check",
   "--test-type",
+  "--remote-allow-origins=*",
   startUrl,
 ];
 
@@ -253,6 +240,45 @@ console.log("Log in to the app once — the profile persists between runs.\n");
 const child = spawn(chrome, chromeArgs, { detached: true, stdio: "ignore" });
 child.unref();
 
+const owned = await waitForOwnedCdp({
+  profileDir,
+  port: debugPort,
+  token: sentinel,
+});
+if (!owned.ok) {
+  try {
+    if (child.pid) process.kill(child.pid, "SIGTERM");
+  } catch {
+    // The isolated window may still be open without a debug port.
+  }
+  console.error(`inject: ${ownershipErrorMessage(owned.reason, {
+    port: debugPort,
+    profileDir,
+    root,
+  })}`);
+  process.exit(1);
+}
+
+// Record only after the listener is provably this profile. Writing the port
+// first is how attach adopted someone else's Chrome on :9222.
+fs.mkdirSync(workDir, { recursive: true });
+fs.writeFileSync(
+  path.join(workDir, "state.json"),
+  JSON.stringify(
+    {
+      debugPort,
+      sentinel,
+      target: targetName,
+      resolvedTarget: {
+        ...target,
+        sdkUrl: cfg.sdkUrl,
+      },
+    },
+    null,
+    2,
+  ),
+);
+
 // --- theme -------------------------------------------------------------
 //
 // Chrome 151 ignores --load-extension, so load the optional cosmetic theme
@@ -260,34 +286,24 @@ child.unref();
 //
 // The CDP Extensions domain still works (that is what
 // --enable-unsafe-extension-debugging is for), so load the theme that way.
-// Only the theme: the SDK and actions arrive over CDP from attach.mjs, and the
-// dev extension is not required for them.
-async function loadTheme() {
-  const endpoint = `http://127.0.0.1:${debugPort}/json/version`;
-  for (let i = 0; i < 40; i++) {
-    try {
-      const version = await (await fetch(endpoint)).json();
-      const ws = new WebSocket(version.webSocketDebuggerUrl);
-      await new Promise((resolve, reject) => {
-        ws.addEventListener("open", resolve);
-        ws.addEventListener("error", reject);
-      });
-      const done = new Promise((resolve) => {
-        ws.addEventListener("message", (event) => {
-          const message = JSON.parse(event.data);
-          if (message.id === 1) resolve(message);
-        });
-      });
-      ws.send(JSON.stringify({ id: 1, method: "Extensions.loadUnpacked", params: { path: themeDir } }));
-      const result = await done;
-      ws.close();
-      if (result.error) console.log(`  theme not applied: ${result.error.message}`);
-      return;
-    } catch {
-      await new Promise((resolve) => setTimeout(resolve, 500));
-    }
-  }
-  console.log("  theme not applied: Chrome did not expose CDP in time");
+// Only the theme: the SDK and actions arrive over CDP from attach.mjs, and
+// the dev extension is not required for them.
+async function loadTheme(version) {
+  const ws = new WebSocket(version.webSocketDebuggerUrl);
+  await new Promise((resolve, reject) => {
+    ws.addEventListener("open", resolve);
+    ws.addEventListener("error", reject);
+  });
+  const done = new Promise((resolve) => {
+    ws.addEventListener("message", (event) => {
+      const message = JSON.parse(event.data);
+      if (message.id === 1) resolve(message);
+    });
+  });
+  ws.send(JSON.stringify({ id: 1, method: "Extensions.loadUnpacked", params: { path: themeDir } }));
+  const result = await done;
+  ws.close();
+  if (result.error) console.log(`  theme not applied: ${result.error.message}`);
 }
 
-await loadTheme();
+await loadTheme(owned.version);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@foldspace_npm/harness",
-  "version": "0.1.9",
+  "version": "0.1.11",
   "description": "Build and verify portable Foldspace action artifacts against a live app.",
   "type": "module",
   "bin": {
@@ -21,7 +21,8 @@
     "bin",
     "src",
     "templates",
-    "README.md"
+    "README.md",
+    "CLAUDE.md"
   ],
   "dependencies": {
     "esbuild": "^0.20.0",

package/src/attach-helpers.mjs

@@ -15,6 +15,38 @@ export function attachModeFromArgs(argv) {
   return ATTACH_MODES.SWAP;
 }
 
+function present(value) {
+  if (value == null) return null;
+  const text = String(value);
+  return text ? text : null;
+}
+
+/**
+ * Resolve the Chrome debug port attach should connect to.
+ *
+ * An explicit --port or CDP_PORT always wins. Otherwise the port inject
+ * recorded is used only when the recorded target still matches. There is no
+ * fallback to 9222: that is Chrome's conventional debugging port, and guessing
+ * it attaches to whoever is listening — often not the profile we launched.
+ */
+export function resolveAttachLaunch({
+  explicitPort = null,
+  envPort = null,
+  explicitTarget = null,
+  savedTarget = null,
+  savedDebugPort = null,
+} = {}) {
+  const portOverride = present(explicitPort);
+  const envOverride = present(envPort);
+  const savedPort = present(savedDebugPort);
+  const useSavedLaunch =
+    !portOverride &&
+    !envOverride &&
+    (!explicitTarget || explicitTarget === savedTarget);
+  const port = portOverride || envOverride || (useSavedLaunch ? savedPort : null);
+  return { useSavedLaunch, port };
+}
+
 export function hostPatternsFromMatches(matches) {
   return matches.map((match) =>
     match.replace("*://", "").replace("/*", ""),