@foldspace_npm/harness 0.1.15 → 0.1.16

package/CLAUDE.md

@@ -44,16 +44,23 @@ current CLI contract — risk, prerequisites, effects, next step.
 | **L2 · look up entities** | a search from the user's own words, showing rows |
 
 1. **Get the agent live first (L0) - with no actions.** Straight after
-   orienting: `npm run build`, `npm run inject`, the human signs in to their
-   app, then `npx foldspace attach --daemon`. An empty registry is valid. L0
-   is `registration_ok` with the agent visible on their page - tell them to
-   look at it and say hello to it. **Do not explore the app first**: no
+   orienting: `npm run build`, `npm run inject`, and one ask - *"A Chrome
+   window opened at <Product>'s login. Please log in there - I'll notice when
+   you're in."* Then `npx foldspace observe wait-login`: it returns the moment
+   they are in, so nobody has to type "I've logged in". Then
+   `npx foldspace attach --daemon`. An empty registry is valid. L0 is
+   `registration_ok` with the agent visible on their page: take
+   `npx foldspace observe screenshot`, send them the image, and tell them to
+   look at it and say hello to it. **From here on the agent stays on their
+   page** - you never detach to look at the app.
+   **Do not explore the app first**: no
    reading its bundle, no watching its traffic, no browsing its screens.
    Nothing about L0 needs any of it, and minutes of silent investigation
    before the human has seen anything is the wrong first impression.
 2. **Then offer experiences - from what you already have.** With the agent on
    their screen, offer three or four read-only experiences as a choice,
-   recommended first. Sources: the conversation starters seeded at sign-up,
+   recommended first. Sources: the product's own menu (`npx foldspace observe
+   menu` takes a second and moves nothing), the conversation starters seeded at sign-up,
    `discover_actions`, and `docs/app-profile.md`. `discover_actions` gives
    candidates, not an inventory. Do not investigate the app to build this
    list. Order them cheapest first: the user's own data with no parameter
@@ -92,15 +99,35 @@ and asking are not the only options — **observing is, and it comes first**:
 
 1. **Already known** — `docs/app-profile.md`. A verified endpoint needs no
    browsing.
-2. **You drive - once they have chosen an experience.** The agent is already
-   attached from L0, and `attach` owns the debug port: `npx foldspace attach
-   --stop` first. Then *you* go to the one screen that experience needs: read
-   the app's bundle for API paths and watch the requests it makes
-   (chrome-devtools MCP against the inject Chrome, or a page-context
-   `fetch`). Attach again when you have the call. Read the auth method off a request
-   the page already sent — bearer from `localStorage`, cookie, custom header.
-   Delegate the watching to a read-only subagent so the traffic does not flood
-   your context.
+2. **You look - once they have chosen an experience - with `foldspace
+   observe`.** It reads the test window they signed in to, it is read-only by
+   construction, and it works **while the agent stays attached**: do not
+   `attach --stop` to look. Write no browser-driving script of your own, and do
+   not reach for a separate DevTools server - one launched on its own opens a
+   different, signed-out Chrome and can never see the window they logged in to.
+
+   ```bash
+   npx foldspace observe menu                      # the product's own screens, by label and path
+   npx foldspace observe screen --click "<a label from menu>" --match "<three to five words for the data>"
+   npx foldspace observe read "<the GET path screen returned>"   # GET only: status, field names and types, row count
+   npx foldspace observe auth                      # only if a read came back 401 or 403
+   npx foldspace observe styles                    # their font and colours, for the card
+   ```
+
+   `screen` reaches a screen the way a person does and returns at most eight
+   requests, ranked by your words - field names, value types and row counts,
+   **never values**. `read` confirms the one you picked. `auth` reports *where*
+   each header value comes from, never the value: do not go hunting through
+   storage, cookies or bundles yourself. One experience needs one screen; two
+   `screen` calls is normal, five means the experience is wrong for this
+   product - offer the next one.
+
+   **`observe` refuses what is not provably looking**, and a refusal is an
+   answer (**Safety**): it follows links, tabs and menu openers only - a plain
+   button can do anything, so use `--goto <path>` from `menu` instead; it will
+   not open a path that does something (`/logout`, `/…/delete`); and `read`
+   only goes to the app's own origin, a host configured for this project, or
+   an origin `screen` saw the page call.
 3. **Ask the human to perform the workflow** — only for what you cannot reach:
    an MFA step, a paywall, a screen that needs a record the account does not
    have, or anything that would write.
@@ -198,9 +225,8 @@ npx foldspace attach --daemon
 ```
 
 `inject` launches an isolated Chrome profile and records its debug port; it
-loads nothing. In a first session `attach` comes straight after sign-in (L0);
-to observe afterwards, `attach --stop`, use chrome-devtools MCP against the
-same Chrome, then attach again. `attach` prepares the page and loads the local
+loads nothing. In a first session `attach` comes straight after sign-in (L0),
+and `foldspace observe` reads the same window while it runs. `attach` prepares the page and loads the local
 `dist/index.js` over CDP. Coding agents use `--daemon` so the tool returns after
 `[lifecycle] inspect_registration:…`. An empty local registry is valid; `npm run
 build` is still required so `dist/index.js` exists.
@@ -212,8 +238,9 @@ SDK without the configured agent.
 
 `inspect_registration:registration_ok` is the signal. On `registration_mismatch`
 read `npx foldspace help attach --json` and map `missingActionNames`,
-`unexpectedActionNames`, `diagnosticError`. While attach runs it owns the debug
-port — `attach --stop` before using chrome-devtools MCP again.
+`unexpectedActionNames`, `diagnosticError`. A running attach keeps the actions
+it loaded: after a rebuild, `attach --stop` and attach again to load the new
+ones. That is the only reason to stop it.
 
 Prove a named action through the visible agent: after the human talks to the
 copilot, read the daemon log for `[actions]` SDK callback and local

package/README.md

@@ -190,8 +190,8 @@ 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.
+`attach --stop` inspect and tear down a daemon. Look at the customer's app with
+`foldspace observe`: it reads the same window, read-only, while attach runs.
 
 ### Verify actions through the agent
 

package/bin/attach.mjs

@@ -43,6 +43,7 @@ import {
   shouldFulfillActionRequest,
 } from "../src/attach-preflight.mjs";
 import { serializeDiagnostic } from "../src/diagnostics.mjs";
+import { recordEvent } from "../src/session-events.mjs";
 import {
   ERROR_CODES,
   createLifecycleResult,
@@ -699,6 +700,8 @@ async function prepare(ws, sessionId, url) {
 
     {
       const verification = await verifyPreparedPage(ws, sessionId);
+      // For scoring a session: the moment the customer could first see their agent.
+      if (verification.ok) recordEvent(root, "agent_visible", { mode: attachMode });
       logLifecycle(
         createLifecycleResult({
           operation: "inspect_registration",
@@ -952,7 +955,7 @@ console.log(`Test:  ${noTestMode ? "OFF — conversations WILL appear in the das
 console.log(`Hosts: ${hostPatterns.join(", ")}`);
 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`,
+  `CDP: attached. \`foldspace observe\` reads this same window while attach runs; stop attach only to load rebuilt actions.\n`,
 );
 
 function printSessionSummary() {

package/bin/inject.mjs

@@ -11,6 +11,7 @@
  *   npm run inject -- --url https://app.other.com --product ABC123 --agent other-agent
  *   npm run inject -- --print                       # resolve target only, don't launch
  */
+import { recordEvent } from "../src/session-events.mjs";
 import fs from "fs";
 import path from "path";
 import os from "os";
@@ -279,6 +280,8 @@ fs.writeFileSync(
   ),
 );
 
+recordEvent(root, "chrome_opened", { url: startUrl });
+
 // --- theme -------------------------------------------------------------
 //
 // Chrome 151 ignores --load-extension, so load the optional cosmetic theme