effing-use 0.2.0 → 0.2.1

package/README.md

@@ -8,14 +8,14 @@ Full Chromium automation in **3 tools, 3.9 KB**. Same pages, same clicks, same s
 
 ## Install (Bun-only)
 
-Requires [Bun](https://bun.sh) 1.4+. Installs from npm in seconds — the tarball is ~16 kB ([`effing-use` v0.1.1](https://www.npmjs.com/package/effing-use)):
+Requires [Bun](https://bun.sh) 1.4+. Installs from npm in seconds — the tarball is ~16 kB ([`effing-use` v0.2.1](https://www.npmjs.com/package/effing-use)):
 
 ```bash
 # No install needed — bunx fetches from npm on first run
-bunx effing-use               # CLI (needs running server) — effing-use observe/act/extract
-bunx effing-use-http          # HTTP MCP on :3123 (/mcp) — shared across editors
-bunx effing-use-stdio         # STDIO MCP (single editor) — legacy bin
-bunx playwright install chromium --only-shell   # one-time Chromium download (~150 MB)
+bunx --package effing-use effing-use               # CLI (needs running server)
+bunx --package effing-use effing-use-http          # HTTP MCP on :3123 (/mcp) — shared across editors
+bunx --package effing-use effing-use-stdio         # STDIO MCP (single editor)
+bunx playwright install chromium --only-shell       # one-time Chromium download (~150 MB)
 ```
 
 Optional — install globally so `effing-use` is on your PATH:
@@ -41,41 +41,74 @@ Re-run `bunx playwright install chromium --only-shell` whenever you bump the `pl
 
 **Why Chromium is separate:** Playwright supports multiple browsers and updates its pinned builds every release, so the binary can't live inside the npm tarball (ours is 16 kB). Docker users skip this — Chromium is baked into the `mcr.microsoft.com/playwright` base image.
 
+### npm vs source
+
+| Source                                | Command                                                 | When to use                                                                    |
+| ------------------------------------- | ------------------------------------------------------- | ------------------------------------------------------------------------------ |
+| **npm** (`bunx --package effing-use`) | `effing-use`, `effing-use-http`, `effing-use-stdio`     | Recommended — always matches published `package.json` version, no clone needed |
+| **source** (`bun src/*.ts`)           | `bun src/cli.ts`, `bun src/http.ts`, `bun src/index.ts` | Local dev / unreleased changes                                                 |
+
+Both expose the same 3 bins: `effing-use` = CLI (HTTP client), `effing-use-stdio` = MCP stdio, `effing-use-http` = MCP http. Don't mix them — `effing-use` alone is **not** an MCP server (it prints CLI help and exits, causing `Failed to parse message` / `MCP server has stopped`).
+
 ## Run it in 60 seconds (recommended path)
 
 **Step 1/3 — Start the server.** One server, every local editor:
 
 ```bash
+# Docker (recommended — Chromium baked in, no local install)
+docker compose up --build -d
+curl http://localhost:3123/healthz   # {"ok":true,"name":"effing-use"}
+
+# Or without Docker
 bun install
 bunx playwright install chromium --only-shell
-docker compose up --build -d
-curl http://localhost:3123/healthz
+bun src/http.ts   # or: bunx --package effing-use effing-use-http
+```
+
+The HTTP server binds `0.0.0.0:3123` inside Docker (so forwarded ports work) and sets `idleTimeout: 0` so the MCP SSE stream isn't killed after 10s of idle time. Plain HTTP on loopback is intentional — add TLS at the edge for remote use.
+
+**Step 2/3 — Connect.** Pick one transport:
+
+**HTTP (shared — recommended for multiple VS Code windows):**
+
+```json
+// ~/.config/Code/User/mcp.json  (global, all workspaces) or .vscode/mcp.json
+{
+  "servers": {
+    "effing-use": { "type": "http", "url": "http://localhost:3123/mcp" }
+  }
+}
 ```
 
-Point any VS Code instance at `http://localhost:3123/mcp` (see `.vscode/mcp.json` → `effing-use (http)`). Plain HTTP on loopback is intentional — add TLS at the edge for remote use.
+One Docker/bun process serves every window. Use same `sessionId` to share tabs, different `sessionId` to isolate.
 
-**Step 2/3 — Connect.** STDIO for one editor, HTTP for all of them:
+**STDIO (isolated — one browser per window):**
 
 ```json
 {
-  "mcpServers": {
+  "servers": {
     "effing-use": {
+      "type": "stdio",
       "command": "bunx",
-      "args": ["effing-use-stdio"]
+      "args": ["--package", "effing-use", "effing-use-stdio"],
+      "env": {
+        "BROWSER_HEADLESS": "true",
+        "OUTPUT_DIR": "${workspaceFolder}/.browser-use"
+      }
     }
   }
 }
 ```
 
-Or HTTP: `http://localhost:3123/mcp` (via `bunx effing-use-http` or Docker). From source instead: `command: "bun"`, `args: ["/path/to/effing-use/src/index.ts"]`.
+From source: `command: "bun"`, `args: ["/absolute/path/to/effing-use/src/index.ts"]`.
 
 **CLI vs MCP — when to use which:**
 
-| Surface | Command | Needs server? | Best for |
-|---------|---------|---------------|----------|
-| **MCP (stdio)** | `effing-use-stdio` / `bun src/index.ts` | No (spawns own browser) | Single VS Code / Claude Desktop |
-| **MCP (http)** | `effing-use-http` / `bun src/http.ts` | Yes (`:3123`) | Shared across editors, Docker |
-| **CLI** | `effing-use` / `bun src/cli.ts` | Yes (`:3123`, `EFFING_USE_URL`) | Terminal agents, scripts, CI |
+| Surface         | Command                                 | Needs server?                   | Best for                        |
+| --------------- | --------------------------------------- | ------------------------------- | ------------------------------- |
+| **MCP (stdio)** | `effing-use-stdio` / `bun src/index.ts` | No (spawns own browser)         | Single VS Code / Claude Desktop |
+| **MCP (http)**  | `effing-use-http` / `bun src/http.ts`   | Yes (`:3123`)                   | Shared across editors, Docker   |
+| **CLI**         | `effing-use` / `bun src/cli.ts`         | Yes (`:3123`, `EFFING_USE_URL`) | Terminal agents, scripts, CI    |
 
 The CLI is a thin HTTP client over the same engine — `effing-use observe --kind snapshot --mode delta` and `browser_observe kind=snapshot mode=delta` hit the same code. Start the server once (`bun src/http.ts` or `docker compose up`), then use either face.
 
@@ -94,6 +127,46 @@ The CLI is a thin HTTP client over the same engine — `effing-use observe --kin
 
 No Docker? `bun src/cli.ts --help` (CLI), `bun src/index.ts` (STDIO MCP), or `bun src/http.ts` (`:3123` `/mcp`) works directly.
 
+### CLI usage
+
+The CLI needs a running HTTP server (`EFFING_USE_URL` defaults to `http://localhost:3123/mcp`):
+
+```bash
+# Observe
+effing-use observe --kind snapshot --mode delta --session dev
+effing-use observe --kind title --session dev
+effing-use observe --kind screenshot --session dev
+
+# Act
+effing-use act --action open --value https://example.com --session dev
+effing-use act --action click --target e5 --expect 'url~/dashboard' --session dev
+effing-use act --action batch --file steps.json --session dev
+
+# Extract
+effing-use extract --kind text --selector main --session dev
+effing-use extract --kind state --session dev
+
+# With custom server URL
+EFFING_USE_URL=http://localhost:3123/mcp effing-use observe --kind snapshot
+```
+
+From npm without global install: `bunx --package effing-use effing-use observe --kind snapshot`.
+
+### Docker
+
+```bash
+docker compose up --build -d          # build + start (0.0.0.0:3123, idleTimeout:0)
+docker compose logs -f effing-use     # tail logs
+curl http://localhost:3123/healthz    # health check
+docker compose down                   # stop (add -v to remove volumes)
+# Rebuild after pulling new code
+docker compose up --build -d
+# Orphaned old container holding :3123? (renamed service)
+docker rm -f effing-use-computer-use-1 && docker compose up -d
+```
+
+Compose details: `restart: unless-stopped`, `init: true` + `ipc: host` (Playwright flags), `.browser-use/` bind-mounted, `EFFING_PORT` overrides host port (`EFFING_PORT=4000 docker compose up -d`).
+
 ## Why agents prefer 3 tools
 
 - 🪶 **Tiny handshake, full surface** — `browser_act` (32 actions), `browser_observe` (8 kinds + `mode`/`scope`), `browser_extract` (8 kinds incl. `state`). No schema bloat, no guessing which of 24 tools to call.
@@ -102,6 +175,36 @@ No Docker? `bun src/cli.ts --help` (CLI), `bun src/index.ts` (STDIO MCP), or `bu
 - ⚡ **One call, not five** — `batch` runs fill+press flows in one turn (max 20 steps, stops on first error). `goal` plans or returns `E_GOAL_UNCLEAR` + `suggestedSteps` instead of hallucinating.
 - 🐳 **Shared, not spawned** — one Docker server serves every local VS Code instance. No per-client `npx` spawn.
 
+## Harness — verify, delta, state, replay
+
+v2 turns the browser into a harness: AI actions are verifiable, diffable, and replayable — not just fire-and-forget clicks.
+
+**1. Verify — fingerprints + expectations + failure contract**
+
+- **Fingerprint registry** (`src/browser/identity.ts`): every `eN` ref is fingerprinted (role, accessibleName, textHash, box, pathHash). Stale refs rebind only on an UNAMBIGUOUS identity match (`rebound:true`); if several elements match equally they fail with `E_STALE` + hint — the engine never guesses a target.
+- **Expect mini-language** (`expect` on any `browser_act`): `url~/dashboard` | `text~/Saved/` | `visible=.modal` | `gone=.spinner` — evaluated server-side, returns `E_EXPECT` / `E_BAD_EXPECT` on mismatch instead of hallucinated success. ReDoS-capped and regex-validated.
+- **Failure contract**: after an uncertain mutation the engine sets `mustObserve:true` — next mutation fails with `E_MUST_OBSERVE` until you re-snapshot. No blind chains.
+- **Evidence envelope**: every `browser_act` returns `effect: { urlChanged, urlBefore/After, domChanged, consoleErrors, networkFailures }` capped at `EFFECT_MAX_CHARS` (800) so the agent sees what actually happened.
+
+**2. Delta — pay only for what changed**
+
+- `browser_observe kind=snapshot mode=delta` (default) — MutationObserver dirty flag + baseline diff. Returns only `[changed]` lines or `unchanged:true` on stable pages (~90% token saving). `mode=full` for complete dump, `scope="<css>"` for subtree.
+- `DELTA_DEFAULT=true` — flip to `false` to default to full snapshots.
+
+**3. State — per-session memory**
+
+- `browser_act action=note value="..."` appends to `notes` (capped `STATE_MAX_LINES=40`), `browser_extract kind=state` reads `notes` + `lastActions` ring (last 10). Persisted to `.browser-use/state/<session>.md` so agents survive context compaction.
+
+**4. Record → Compile → Replay — deterministic macros**
+
+- `record_start` / `record_stop` captures every step with resolved selectors + fingerprints. Secrets auto-redacted (`RECORD_REDACT=true`, `«redacted»` for password/otp/token fields).
+- `compile` generates `.browser-use/macros/<name>.{ts,md}` — a Playwright `run(page)` function + a `SKILL.md` doc. Irreversible steps (`submit`/`pay`/`delete`/etc.) are flagged `requiresApproval`.
+- `replay` replays deterministically; pauses with `E_APPROVAL_REQUIRED` until `approve:true` if any irreversible step exists.
+
+**5. CLI — same engine, no MCP client**
+
+- `effing-use observe/act/extract` over `EFFING_USE_URL` (`http://localhost:3123/mcp`) — for terminal agents, scripts, and CI. See [CLI usage](#cli-usage).
+
 ## The loop (agents: follow this order)
 
 1. `browser_observe` kind=`snapshot` → get `[eN]` refs (default `mode: delta` — only changed lines; `mode: full` for complete dump; `scope: "<css>"` for subtree). Never guess refs, re-snapshot after navigation.
@@ -130,18 +233,27 @@ Errors are always `{ ok: false, code, message, hint }` with `E_NOT_FOUND | E_TIM
 
 Need Firefox/WebKit, device emulation, or persistent profiles? Use Playwright MCP. Need context budget for Chromium work? Stay here. Full breakdown in [`docs/COMPARISON.md`](docs/COMPARISON.md).
 
-## Record → replay
+## Record → replay (harness)
 
 ```bash
-# MCP
+# MCP — capture any flow, compile to code + skill, replay deterministically
 browser_act action=record_start value=my-flow
-# ... do the flow ...
-browser_act action=record_stop
-browser_act action=compile value=my-flow   # -> .browser-use/macros/my-flow.{ts,md}
-browser_act action=replay value=my-flow    # pauses with E_APPROVAL_REQUIRED if irreversible
-browser_act action=replay value=my-flow approve=true
+# ... do the flow (clicks, fills, etc.) ...
+browser_act action=record_stop                          # -> .browser-use/recordings/my-flow.json (secrets redacted)
+browser_act action=compile value=my-flow                # -> .browser-use/macros/my-flow.{ts,md}
+browser_act action=replay value=my-flow                 # pauses with E_APPROVAL_REQUIRED if irreversible
+browser_act action=replay value=my-flow approve=true    # replay with approval
+
+# CLI — same flow over HTTP
+EFFING_USE_URL=http://localhost:3123/mcp effing-use act --action record_start --value my-flow
+# ... do the flow via CLI or MCP ...
+EFFING_USE_URL=http://localhost:3123/mcp effing-use act --action record_stop
+EFFING_USE_URL=http://localhost:3123/mcp effing-use act --action compile --value my-flow
+EFFING_USE_URL=http://localhost:3123/mcp effing-use act --action replay --value my-flow --approve true
 ```
 
+Artifacts: `recordings/*.json` (raw steps), `macros/*.ts` (Playwright `run(page)`), `macros/*.md` (skill doc). Redaction and approval gates are on by default (`RECORD_REDACT=true`).
+
 ## Config
 
 Env defaults in [`.env.example`](.env.example): `BROWSER_HEADLESS`, `BROWSER_VIEWPORT_W/H`, `BROWSER_TIMEOUT_MS`, `OUTPUT_DIR` (`.browser-use/`, gitignored), `OUTPUT_MAX_CHARS`, `ALLOW_EVAL`, `DELTA_DEFAULT`, `EFFECT_MAX_CHARS`, `STATE_MAX_LINES`, `RECORD_REDACT`, `EFFING_USE_URL`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "effing-use",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "Token-efficient browser control: 3 tools (act, observe, extract) built with tmcp + Bun + Playwright",
   "license": "MIT",
   "author": "Michael Obubelebra Amachree",

package/skills/effing-use/SKILL.md

@@ -15,14 +15,14 @@ cost than 21-tool browser servers. `tools/list` is ~3.9KB.
 
 ## The loop (always follow this order)
 
-1. `browser_observe` with `kind: "snapshot"` → get `[eN]` refs. Default is `mode: "delta"` (only changes since last observe); use `mode: "full"` for a complete dump. Use `scope: "<css>"` to observe a subtree.
+1. `browser_observe` with `kind: "snapshot"` → get `[eN]` refs. Default is `mode: "delta"` (`[changed]`/`[removed]` lines since last observe; `unchanged:true` when the page is quiet — navigation automatically forces a fresh `mode: "full"`). Use `mode: "full"` for a complete dump, `scope: "<css>"` to observe a subtree.
 2. `browser_act` to interact (`open`, `click`, `fill`, `type`, `press`, `select`, `check`, `wait`, …). Add `expect: "url~/dashboard"` or `text~/Saved/` for deterministic post-conditions.
-3. `browser_observe` with `kind: "snapshot"` again — delta returns `unchanged:true` if nothing changed, or `[changed]` lines.
+3. `browser_observe` with `kind: "snapshot"` again — delta returns `unchanged:true` if nothing changed, or `[changed]`/`[removed]` lines.
 4. `browser_extract` with `kind: "text" | "table" | "query" | "state"` → scrape or read task state.
 
 Rules:
 
-- Never guess refs. Re-snapshot after every navigation. Stale refs return `E_STALE` or auto-rebind with `rebound:true`.
+- Never guess refs. Re-snapshot after every navigation (refs are page-keyed — a cross-page stale ref returns `E_NOT_FOUND`). On a same-page re-render the engine rebinds only an UNAMBIGUOUS identity match (result carries `rebound:true`); if the fingerprint matches several elements it fails with `E_STALE` instead of guessing — re-observe.
 - Prefer `batch`: one `browser_act` with `steps[]` for fill+press flows (max 20 steps, stops on first error).
 - Large outputs are files under `.browser-use/` (gitignored). Read the path, not the preview.
 - Snapshots are capped at `OUTPUT_MAX_CHARS` (default 4000) with `…[truncated N chars, see file]`.
@@ -37,8 +37,8 @@ Rules:
 `scroll` (`up`/`down`/`top`/`bottom` or a target), `back`/`forward`/`reload`,
 `wait` (`ms:500`, `text:Saved`, or a ref), `dialog_accept`/`dialog_dismiss` (arm before the triggering step),
 `resize` (`1280x800` in `value`), `tab_new`/`tab_select`/`tab_close`, `close`,
-`goal` (deterministic add-todo/search planner, else `E_GOAL_UNCLEAR` + `suggestedSteps`),
-`batch` (needs `steps[]`), `note` (append to task state), `record_start`/`record_stop` (capture flow), `compile` (macro+SKILL.md), `replay` (deterministic replay, needs `approve:true` for irreversible steps).
+`goal` (deterministic add-todo/search planner, else `E_GOAL_UNCLEAR` + `suggestedSteps`; counts as a mutation — subject to the `mustObserve` guard, evidence, and recording),
+`batch` (needs `steps[]`), `note` (append to task state), `record_start`/`record_stop` (capture flow), `compile` (standalone `.ts` + SKILL.md; selectors resolved id → name → ARIA → data-\* → placeholder → text), `replay` (deterministic replay; runs benign steps, halts AT approval-gated steps).
 `expect` mini-language: `url~<regex>` | `text~<regex>` | `visible=<css>` | `gone=<css>` — evaluated in code, returns `E_EXPECT` or `E_BAD_EXPECT`.
 
 **browser_observe** — read-only: `snapshot` (e-refs, `mode: full|delta` default delta, `scope: <css>`), `screenshot` (file path,
@@ -70,8 +70,11 @@ browser_act action=record_start value=my-flow
 # ... do the flow ...
 browser_act action=record_stop
 browser_act action=compile value=my-flow   # -> .browser-use/macros/my-flow.{ts,md}
-browser_act action=replay value=my-flow    # pauses with E_APPROVAL_REQUIRED if irreversible
-browser_act action=replay value=my-flow approve=true
+browser_act action=replay value=my-flow    # runs benign steps, halts AT the first
+                                           # approval-gated step → E_APPROVAL_REQUIRED
+                                           # { step: N (1-indexed), completed: C }
+browser_act action=replay value=my-flow approve=true   # resumes at the gate; the
+                                           # benign prefix is NOT re-run (cursor)
 ```
 
 ## Setup

package/src/browser/delta.ts

@@ -44,6 +44,11 @@ export function getBaseline(sessionId: string): string | null {
   return ensureState(sessionId).baseline;
 }
 
+/** URL the current baseline was captured on — forces mode:full after navigation (plan §5.1). */
+export function getBaselineUrl(sessionId: string): string | null {
+  return pageStates.get(key(sessionId))?.baselineUrl ?? null;
+}
+
 export function isDirty(sessionId: string): boolean {
   return ensureState(sessionId).dirty;
 }
@@ -66,8 +71,32 @@ export async function injectDirtyObserver(
       w.__effDirty = false;
       w.__effSid = sid;
       if (w.__effObs) w.__effObs.disconnect();
-      const obs = new MutationObserver(() => {
-        w.__effDirty = true;
+      // Attribute spam that never changes the snapshot's ref lines (class,
+      // style, expand/animation state) used to mark every live SPA permanently
+      // dirty — the cheap "unchanged" fast path never fired. Ignore those;
+      // content changes still arrive via childList/characterData/input/change.
+      const NOISE_ATTRS = [
+        "class",
+        "style",
+        "aria-expanded",
+        "data-state",
+        "data-orientation",
+        "data-scroll-state",
+        "data-highlighted",
+        "data-hovered",
+        "data-dragging",
+        "data-resizing",
+        "data-index",
+      ];
+      const obs = new MutationObserver((muts) => {
+        for (const m of muts) {
+          if (m.type === "attributes") {
+            const name = m.attributeName || "";
+            if (NOISE_ATTRS.indexOf(name) !== -1) continue;
+          }
+          w.__effDirty = true;
+          return;
+        }
       });
       obs.observe(document.documentElement, {
         childList: true,
@@ -127,10 +156,18 @@ export function computeDelta(
   const baseLines = baseline.split("\n");
   const curLines = current.split("\n");
   const baseSet = new Set(baseLines);
+  const curSet = new Set(curLines);
   const changed = curLines.filter((l) => !baseSet.has(l));
+  const removed = baseLines.filter((l) => !curSet.has(l));
+  if (changed.length === 0 && removed.length === 0)
+    return { delta: "", unchanged: true };
   const unchangedCount = curLines.length - changed.length;
-  if (changed.length === 0) return { delta: "", unchanged: true };
   const header = `…${unchangedCount} unchanged lines…`;
-  const delta = [header, ...changed.map((l) => `[changed] ${l}`)].join("\n");
+  const delta = [
+    header,
+    ...changed.map((l) => `[changed] ${l}`),
+    // plan §5.1: removed nodes are reported explicitly
+    ...removed.map((l) => `[removed] ${l}`),
+  ].join("\n");
   return { delta, unchanged: false };
 }

package/src/browser/engine.ts

@@ -1,6 +1,6 @@
 import type { Page, BrowserContext } from "playwright";
 import type { Config } from "../config.js";
-import { EngineError, resolveLocator } from "./refs.js";
+import { EngineError, resolveLocator, stableSelectorFor } from "./refs.js";
 import { cap, saveText, stamp } from "./output.js";
 import {
   getConsoleLogs,
@@ -13,6 +13,7 @@ import {
 import { collectEffect, evaluateExpect, parseExpect } from "./evidence.js";
 import {
   getBaseline,
+  getBaselineUrl,
   setBaseline,
   computeDelta,
   injectDirtyObserver,
@@ -28,9 +29,17 @@ import {
   loadRecording,
   startRecording,
   stopRecording,
+  getReplayCursor,
+  setReplayCursor,
+  clearReplayCursor,
 } from "./record.js";
 import { compileMacro, isIrreversible } from "./macro.js";
-import { registerFingerprints, clearRegistry } from "./identity.js";
+import {
+  registerFingerprints,
+  clearRegistry,
+  getFingerprint,
+  extractFingerprints as collectFingerprints,
+} from "./identity.js";
 
 export type ActAction =
   | "open"
@@ -85,6 +94,19 @@ function timeoutOf(config: Config): number {
 async function liteState(page: Page): Promise<{ url: string; title: string }> {
   return { url: page.url(), title: await page.title().catch(() => "") };
 }
+
+/**
+ * SPA navigations commit after the action returns (client router awaits data),
+ * so evidence collected immediately can report urlChanged:false for a click
+ * that DOES navigate (observed: kikitai "Try paste & read" → /read).
+ * Brief settle: one tick, then a second if the URL moved.
+ */
+async function settleSpa(page: Page, action: string): Promise<void> {
+  if (!["click", "dblclick", "press", "goal"].includes(action)) return;
+  const u0 = page.url();
+  await page.waitForTimeout(60);
+  if (page.url() !== u0) await page.waitForTimeout(60);
+}
 function toEngineError(e: unknown, fallbackHint: string): EngineError {
   if (e instanceof EngineError) return e;
   const msg = e instanceof Error ? e.message : String(e);
@@ -116,6 +138,7 @@ const MUTATING = new Set<string>([
   "open",
   "goto",
   "resize",
+  "goal",
   "tab_new",
   "tab_select",
   "tab_close",
@@ -136,6 +159,10 @@ export async function doAct(
   const timeout = timeoutOf(config);
   const sid = opts?.sessionId ?? "default";
 
+  // Per-action stash must never leak from a previous (possibly failed) act
+  const pageBag = page as unknown as Record<string, unknown>;
+  delete pageBag.__rebound;
+
   // Non-page meta actions (no mustObserve guard, no evidence)
   if (action === "note") {
     if (!value && !target)
@@ -209,24 +236,28 @@ export async function doAct(
       );
     });
     const approve = opts?.approve === true;
-    // Check approval gate
-    const needsApproval = (rec.steps as any[]).filter((s: any) =>
-      isIrreversible(s),
-    );
-    if (needsApproval.length > 0 && !approve) {
-      const first = needsApproval[0];
-      return {
-        ok: false,
-        code: "E_APPROVAL_REQUIRED",
-        message: `Step ${first.seq} requires approval (${first.op}).`,
-        hint: "Re-run with approve:true.",
-        step: first.seq,
-        description: `${first.op} ${first.target ?? ""}`,
-      } as any;
-    }
-    // Deterministic replay
+    // Plan §6.3: run benign steps, pause AT each approval-gated step, and keep
+    // a cursor so approve:true resumes here instead of re-running the prefix.
+    const stepsArr = rec.steps as any[];
+    const start = getReplayCursor(sid, name) ?? 0;
     const results: any[] = [];
-    for (const s of rec.steps as any[]) {
+    for (let i = start; i < stepsArr.length; i++) {
+      const s = stepsArr[i];
+      if (isIrreversible(s) && !approve) {
+        setReplayCursor(sid, name, i);
+        const ran = i - start;
+        return {
+          ok: false,
+          code: "E_APPROVAL_REQUIRED",
+          message:
+            `Step ${i + 1} requires approval (${s.op}).` +
+            (ran > 0 ? ` Ran ${ran} prior step(s).` : ""),
+          hint: "Re-run with approve:true to resume from this step.",
+          step: i + 1,
+          completed: results.length,
+          description: `${s.op} ${s.target ?? ""}`,
+        } as any;
+      }
       try {
         const r = await doAct(
           page,
@@ -238,6 +269,7 @@ export async function doAct(
         );
         results.push({ ok: true, seq: s.seq, ...r });
       } catch (e) {
+        clearReplayCursor(sid, name);
         const err = toEngineError(e, "Replay failed.");
         results.push({
           ok: false,
@@ -248,7 +280,14 @@ export async function doAct(
         return { replayed: false, name, failSeq: s.seq, results } as any;
       }
     }
-    return { replayed: true, name, steps: results.length, results } as any;
+    clearReplayCursor(sid, name);
+    return {
+      replayed: true,
+      name,
+      steps: results.length,
+      resumedFrom: start,
+      results,
+    } as any;
   }
 
   // Failure contract guard
@@ -275,8 +314,10 @@ export async function doAct(
   const urlBefore = page.url();
   let domBefore: string | null = null;
   try {
+    // Full innerText (50k cap) — evidence diffs need the whole page, not just
+    // the first 200 chars (v0.2: below-fold changes looked like no-ops).
     domBefore = await page.evaluate(
-      () => document.body?.innerText?.slice(0, 200) ?? "",
+      () => document.body?.innerText?.slice(0, 50000) ?? "",
     );
   } catch {
     domBefore = null;
@@ -579,7 +620,12 @@ export async function doAct(
         result = { closed: true };
         break;
       case "goal":
-        return doGoal(page, config, value ?? target ?? "", opts);
+        // Route through the normal post-action pipeline (guard, evidence,
+        // dirty flag, recording) — v0.2 returned here and skipped all of it.
+        result = {
+          ...(await doGoal(page, config, value ?? target ?? "", opts)),
+        };
+        break;
       case "batch":
         throw new EngineError(
           "E_BAD_INPUT",
@@ -608,6 +654,7 @@ export async function doAct(
   // Post-action: evidence, expect, state, dirty, recording
   let effect: any = undefined;
   if (isMutating(action)) {
+    await settleSpa(page, action);
     effect = await collectEffect(
       page,
       sid,
@@ -657,8 +704,15 @@ export async function doAct(
     `${actionLine} -> ${effect ? JSON.stringify(effect).slice(0, 80) : "ok"}`,
   );
 
-  // Recording capture
+  // Recording capture — resolve a portable selector (id → name → ARIA →
+  // data-* → placeholder → text) so compiled macros don't depend on e-refs.
   if (isRecording(sid) && isMutating(action)) {
+    let resolved = target;
+    if (target) {
+      resolved =
+        (await stableSelectorFor(page, target, sid).catch(() => null)) ??
+        target;
+    }
     captureStep(
       sid,
       {
@@ -666,7 +720,8 @@ export async function doAct(
         target,
         value,
         expect: opts?.expect,
-        resolvedSelector: target,
+        resolvedSelector: resolved,
+        targetFingerprint: target ? getFingerprint(sid, target) : undefined,
       },
       config,
     );
@@ -795,9 +850,22 @@ export async function doObserve(
         | "full"
         | "delta";
       const scope = opts?.scope;
+      // Navigation forces a fresh full baseline (plan §5.1) and needs a settle
+      // beat: SPA routes hydrate after the URL changes — snapshots taken too
+      // early miss the header/nav entirely (observed on kikitai /read).
+      const prevUrl = getBaselineUrl(sessionId);
+      const urlChanged = prevUrl !== null && prevUrl !== page.url();
+      const settleHydration = async () => {
+        if (!urlChanged) return;
+        await page
+          .waitForLoadState("networkidle", { timeout: 1500 })
+          .catch(() => {});
+        await page.waitForTimeout(80);
+      };
       // Scoped snapshot: only within selector
       let yaml: string;
       if (scope) {
+        await settleHydration();
         yaml = await buildSnapshot(page, scope);
         const path = await saveText(config, stamp("snapshot", "yaml"), yaml);
         const { text, truncated } = cap(yaml, config.outputMaxChars);
@@ -815,8 +883,9 @@ export async function doObserve(
       // Delta path
       if (mode === "delta") {
         const baseline = getBaseline(sessionId);
-        // If no baseline, do full
-        if (!baseline) {
+        // No baseline, or the page navigated since the baseline → forced full
+        if (!baseline || urlChanged) {
+          await settleHydration();
           yaml = await buildSnapshot(page);
           setBaseline(sessionId, yaml, page.url());
           await injectDirtyObserver(page, sessionId);
@@ -879,6 +948,7 @@ export async function doObserve(
         };
       }
       // Full mode
+      await settleHydration();
       yaml = await buildSnapshot(page);
       setBaseline(sessionId, yaml, page.url());
       await injectDirtyObserver(page, sessionId);
@@ -960,10 +1030,28 @@ async function buildSnapshot(page: Page, scope?: string): Promise<string> {
     }
     return els.slice(0, 200).map((el) => {
       const tag = el.tagName.toLowerCase();
-      const text = (el.textContent ?? "")
+      let text = (el.textContent ?? "")
         .trim()
         .replace(/\s+/g, " ")
         .slice(0, 80);
+      // Form controls carry no text — surface placeholder/label so refs stop
+      // showing as `input ""`, and mark checked state (real state changes that
+      // delta should surface).
+      const input = el as HTMLInputElement;
+      if (!text) {
+        text = (
+          input.placeholder ||
+          (input.labels && input.labels[0]?.textContent) ||
+          ""
+        )
+          .trim()
+          .replace(/\s+/g, " ")
+          .slice(0, 80);
+      }
+      const checked =
+        (tag === "input" || tag === "select") && input.checked
+          ? " [checked]"
+          : "";
       const aria = el.getAttribute("aria-label") ?? "";
       const name = el.getAttribute("name") ?? "";
       const id = el.getAttribute("id") ?? "";
@@ -974,64 +1062,13 @@ async function buildSnapshot(page: Page, scope?: string): Promise<string> {
       ]
         .filter(Boolean)
         .join(" ");
-      return `${tag} "${text}"${extra ? " " + extra : ""}`;
+      return `${tag} "${text}"${extra ? " " + extra : ""}${checked}`;
     });
   }, scope ?? null);
   const lines = items.map((line, i) => `[e${i}] ${line}`);
   return `${header}\n${lines.join("\n") || "(no interactive elements)"}`;
 }
 
-async function collectFingerprints(
-  page: Page,
-): Promise<Array<{ ref: string; fp: import("./identity.js").Fingerprint }>> {
-  const raw = await page
-    .evaluate(() => {
-      const els = [
-        ...document.querySelectorAll(
-          "button, a, input, select, textarea, [role=button], [tabindex]",
-        ),
-      ].slice(0, 200);
-      return els.map((el) => {
-        const text = (el.textContent ?? "")
-          .trim()
-          .replace(/\s+/g, " ")
-          .slice(0, 80);
-        const aria = el.getAttribute("aria-label") ?? "";
-        const role = el.getAttribute("role") ?? el.tagName.toLowerCase();
-        let cur: Element | null = el;
-        const parts: string[] = [];
-        while (cur && parts.length < 6) {
-          parts.push(cur.tagName.toLowerCase());
-          cur = cur.parentElement;
-        }
-        const rect = el.getBoundingClientRect();
-        return {
-          role,
-          accessibleName: aria,
-          text,
-          pathHash: parts.join(">"),
-          box: { x: rect.x, y: rect.y, w: rect.width, h: rect.height },
-        };
-      });
-    })
-    .catch(() => [] as any[]);
-  return raw.map((r: any, i: number) => ({
-    ref: `e${i}`,
-    fp: {
-      role: r.role || "generic",
-      accessibleName: (r.accessibleName || "").trim().slice(0, 80),
-      textHash: (r.text || "").trim().replace(/\s+/g, " ").slice(0, 80),
-      box: {
-        x: Math.round(r.box.x),
-        y: Math.round(r.box.y),
-        w: Math.round(r.box.w),
-        h: Math.round(r.box.h),
-      },
-      pathHash: r.pathHash || "",
-    },
-  }));
-}
-
 // ---------------------------------------------------------------- extract
 
 export async function doExtract(

package/src/browser/evidence.ts

@@ -46,16 +46,35 @@ export async function collectEffect(
   const urlAfter = page.url();
   const urlChanged = urlBefore !== urlAfter;
 
-  // domChanged: try to get diff via delta module if available, else simple heuristic
+  // domChanged: line-level diff of body.innerText (50k cap). v0.2 only
+  // compared the first 200 chars, so any below-fold change looked like a no-op
+  // (and fed the failure contract wrong "no DOM change" signals).
   let domChanged: string[] = [];
   try {
     const currentDom = await page.evaluate(
-      () => document.body?.innerText?.slice(0, 200) ?? "",
+      () => document.body?.innerText?.slice(0, 50000) ?? "",
     );
     if (domBeforeHash !== null && currentDom !== domBeforeHash) {
-      domChanged = [
-        currentDom.slice(0, 120).replace(/\s+/g, " ").trim(),
-      ].filter(Boolean);
+      const before = new Set(
+        domBeforeHash
+          .split("\n")
+          .map((l) => l.trim())
+          .filter(Boolean),
+      );
+      const after = currentDom
+        .split("\n")
+        .map((l) => l.trim())
+        .filter(Boolean);
+      const afterSet = new Set(after);
+      const changed = after
+        .filter((l) => !before.has(l))
+        .slice(0, 5)
+        .map((l) => l.slice(0, 140));
+      const removed = [...before]
+        .filter((l) => !afterSet.has(l))
+        .slice(0, 3)
+        .map((l) => `- ${l.slice(0, 138)}`);
+      domChanged = [...changed, ...removed].slice(0, 5);
     }
   } catch {
     // ignore
@@ -96,9 +115,12 @@ export function parseExpect(
   const s = expect.trim();
   let parsed: { kind: string; pattern: string } | null = null;
   if (s.startsWith("url~")) parsed = { kind: "url", pattern: s.slice(4) };
-  else if (s.startsWith("text~")) parsed = { kind: "text", pattern: s.slice(5) };
-  else if (s.startsWith("visible=")) parsed = { kind: "visible", pattern: s.slice(8) };
-  else if (s.startsWith("gone=")) parsed = { kind: "gone", pattern: s.slice(5) };
+  else if (s.startsWith("text~"))
+    parsed = { kind: "text", pattern: s.slice(5) };
+  else if (s.startsWith("visible="))
+    parsed = { kind: "visible", pattern: s.slice(8) };
+  else if (s.startsWith("gone="))
+    parsed = { kind: "gone", pattern: s.slice(5) };
   else return null;
   if (parsed.pattern.length > EXPECT_MAX_PATTERN) return null;
   // Validate regex patterns early for url~/text~

package/src/browser/identity.ts

@@ -1,3 +1,5 @@
+import type { Page } from "playwright";
+
 export type Fingerprint = {
   role: string;
   accessibleName: string;
@@ -6,6 +8,114 @@ export type Fingerprint = {
   pathHash: string;
 };
 
+/** Raw per-element data as extracted inside the page (before normalization). */
+export type RawFp = {
+  role: string;
+  accessibleName: string;
+  text: string;
+  pathHash: string;
+  box: { x: number; y: number; w: number; h: number };
+};
+
+/**
+ * Browser-side fingerprint extractor — SINGLE SOURCE OF TRUTH shared by
+ * snapshot registration, stale-ref validation and rebind search. Serialized
+ * into the page as a string so it never closes over module scope.
+ *
+ * v0.2 bug fixed here: fingerprints used tag-name roles ("input"), aria-label
+ * only, and own textContent (always "" for form controls), so every bare
+ * checkbox shared one identity — rebind then clicked the wrong element
+ * (TodoMVC: stale item toggle rebound to toggle-all). Now:
+ * - role: implicit ARIA role (input[type=checkbox] → "checkbox")
+ * - accessibleName: aria-label → <label> → alt → title → placeholder → text
+ * - textHash: own text, else contextual text (nearest li/label/td/row), else
+ *   placeholder — so item toggles carry their todo text
+ */
+export const RAW_FP_SCRIPT = `(() => {
+  const SEL = "button, a, input, select, textarea, [role=button], [tabindex]";
+  const norm = (s) => (s || "").trim().replace(/\\s+/g, " ").slice(0, 80);
+  const implicitRole = (el) => {
+    const r = el.getAttribute("role");
+    if (r) return r;
+    const tag = el.tagName.toLowerCase();
+    if (tag === "a") return el.hasAttribute("href") ? "link" : "generic";
+    if (tag === "button") return "button";
+    if (tag === "textarea") return "textbox";
+    if (tag === "select") return "combobox";
+    if (tag === "summary") return "button";
+    if (tag === "input") {
+      const t = (el.getAttribute("type") || "text").toLowerCase();
+      if (t === "checkbox") return "checkbox";
+      if (t === "radio") return "radio";
+      if (t === "submit" || t === "button" || t === "reset" || t === "image") return "button";
+      if (t === "range") return "slider";
+      if (t === "hidden") return "hidden";
+      return "textbox";
+    }
+    return tag;
+  };
+  const accName = (el) => {
+    const aria = el.getAttribute("aria-label");
+    if (aria && aria.trim()) return norm(aria);
+    if (el.labels && el.labels.length > 0) {
+      const t = norm(el.labels[0].textContent);
+      if (t) return t;
+    }
+    const alt = el.getAttribute("alt");
+    if (alt && alt.trim()) return norm(alt);
+    const title = el.getAttribute("title");
+    if (title && title.trim()) return norm(title);
+    const ph = el.getAttribute("placeholder");
+    if (ph && ph.trim()) return norm(ph);
+    return norm(el.textContent);
+  };
+  const textOf = (el) => {
+    const own = norm(el.textContent);
+    if (own) return own;
+    const ctx = el.closest && el.closest("li, label, td, [role=listitem], [role=row]");
+    if (ctx) {
+      const t = norm(ctx.textContent);
+      if (t) return t;
+    }
+    return norm(el.getAttribute("placeholder"));
+  };
+  const pathOf = (el) => {
+    const parts = [];
+    let cur = el;
+    while (cur && parts.length < 6) {
+      parts.push(cur.tagName.toLowerCase());
+      cur = cur.parentElement;
+    }
+    return parts.join(">");
+  };
+  const els = Array.prototype.slice.call(document.querySelectorAll(SEL), 0, 200);
+  return els.map((el) => {
+    const rect = el.getBoundingClientRect();
+    return {
+      role: implicitRole(el),
+      accessibleName: accName(el),
+      text: textOf(el),
+      pathHash: pathOf(el),
+      box: {
+        x: Math.round(rect.x),
+        y: Math.round(rect.y),
+        w: Math.round(rect.width),
+        h: Math.round(rect.height)
+      }
+    };
+  });
+})()`;
+
+/** Extract fingerprints for every snapshot-visible element, as e-refs. */
+export async function extractFingerprints(
+  page: Page,
+): Promise<Array<{ ref: string; fp: Fingerprint }>> {
+  const raw = (await page
+    .evaluate(RAW_FP_SCRIPT)
+    .catch(() => [] as RawFp[])) as RawFp[];
+  return raw.map((r, i) => ({ ref: `e${i}`, fp: buildFingerprint(r) }));
+}
+
 function hashText(s: string): string {
   return s.trim().replace(/\s+/g, " ").slice(0, 80);
 }
@@ -41,6 +151,38 @@ export function clearRegistry(sessionId: string): void {
   registry.delete(sessionId);
 }
 
+export type RebindCandidate = { index: number; fp: Fingerprint };
+
+/**
+ * Conservative rebind ladder (P0 fix): pick an element only when the match is
+ * UNAMBIGUOUS — never guess among equals.
+ *
+ * 1. loose match (role + accessibleName + textHash) — unique → take it
+ * 2. multiple loose → narrow by identical pathHash; still >1 → give up
+ * 3. no loose → fuzzy (role + name/text contains) under the same rules
+ *
+ * Returns the chosen candidate index, or null when zero or more than one
+ * candidate survives — callers turn null into E_STALE (fail loud) instead of
+ * clicking the wrong element.
+ */
+export function chooseRebindIndex(
+  expected: Fingerprint,
+  candidates: RebindCandidate[],
+): number | null {
+  const narrow = (pool: RebindCandidate[]): number | null => {
+    if (pool.length === 1) return pool[0].index;
+    if (pool.length > 1 && expected.pathHash) {
+      const byPath = pool.filter((c) => c.fp.pathHash === expected.pathHash);
+      if (byPath.length === 1) return byPath[0].index;
+    }
+    return null;
+  };
+  const loose = candidates.filter((c) => looseMatch(expected, c.fp));
+  if (loose.length > 0) return narrow(loose);
+  const fuzzy = candidates.filter((c) => fuzzyMatch(expected, c.fp));
+  return narrow(fuzzy);
+}
+
 export function fingerprintEquals(a: Fingerprint, b: Fingerprint): boolean {
   return (
     a.role === b.role &&

package/src/browser/macro.ts

@@ -32,8 +32,11 @@ export async function compileMacro(
   const warnings: string[] = [];
   const irreversibleSteps = steps.filter(isIrreversible);
   if (irreversibleSteps.length > 0) {
+    // Steps are human-facing here — 1-indexed, matching the .md step list
     warnings.push(
-      `${irreversibleSteps.length} step(s) require approval: ${irreversibleSteps.map((s) => s.seq).join(", ")}`,
+      `${irreversibleSteps.length} step(s) require approval: steps ${irreversibleSteps
+        .map((s) => s.seq + 1)
+        .join(", ")}`,
     );
   }
 
@@ -49,12 +52,21 @@ export async function compileMacro(
     const sel = selectorFor(s);
     const val = (s.value ?? "").slice(0, 500);
     const flag = isIrreversible(s) ? " // requiresApproval" : "";
+    // Recordings made before stable-selector resolution store session-scoped
+    // e-refs — flag them so nobody runs the .ts standalone expecting it to work.
+    const staleNote = /^e\d+$/.test(sel)
+      ? " /* session-scoped e-ref — not a standalone selector */"
+      : "";
     switch (s.op) {
       case "click":
-        tsLines.push(`  await page.locator(${JSON.stringify(sel)}).click();${flag}`);
+        tsLines.push(
+          `  await page.locator(${JSON.stringify(sel)}).click();${flag}${staleNote}`,
+        );
         break;
       case "fill":
-        tsLines.push(`  await page.locator(${JSON.stringify(sel)}).fill(${JSON.stringify(val)});${flag}`);
+        tsLines.push(
+          `  await page.locator(${JSON.stringify(sel)}).fill(${JSON.stringify(val)});${flag}${staleNote}`,
+        );
         break;
       case "press":
         tsLines.push(
@@ -63,10 +75,14 @@ export async function compileMacro(
         break;
       case "goto":
       case "open":
-        tsLines.push(`  await page.goto(${JSON.stringify(val || sel)});${flag}`);
+        tsLines.push(
+          `  await page.goto(${JSON.stringify(val || sel)});${flag}`,
+        );
         break;
       default:
-        tsLines.push(`  // ${JSON.stringify(s.op)} ${JSON.stringify(sel)} ${JSON.stringify(val)}${flag}`);
+        tsLines.push(
+          `  // ${JSON.stringify(s.op)} ${JSON.stringify(sel)} ${JSON.stringify(val)}${flag}`,
+        );
         break;
     }
   }

package/src/browser/record.ts

@@ -97,7 +97,11 @@ export async function saveRecording(
   const dir = join(config.outputDir, "recordings");
   await mkdir(dir, { recursive: true });
   const path = join(dir, `${safe}.json`);
-  const rec: Recording = { name: safe, createdAt: new Date().toISOString(), steps };
+  const rec: Recording = {
+    name: safe,
+    createdAt: new Date().toISOString(),
+    steps,
+  };
   await writeFile(path, JSON.stringify(rec, null, 2), "utf-8");
   return path;
 }
@@ -115,3 +119,31 @@ export async function loadRecording(
 export function getActiveName(sessionId: string): string | null {
   return activeRecordings.get(sessionId)?.name ?? null;
 }
+
+// ---------------------------------------------------------------- replay cursor
+// Plan §6.3: pause AT an approval-gated step and resume with approve:true —
+// the cursor keeps the benign prefix from running twice (non-idempotent steps).
+const replayCursors = new Map<string, number>();
+
+function cursorKey(sessionId: string, name: string): string {
+  return `${sessionId}:${name}`;
+}
+
+export function getReplayCursor(
+  sessionId: string,
+  name: string,
+): number | undefined {
+  return replayCursors.get(cursorKey(sessionId, name));
+}
+
+export function setReplayCursor(
+  sessionId: string,
+  name: string,
+  step: number,
+): void {
+  replayCursors.set(cursorKey(sessionId, name), step);
+}
+
+export function clearReplayCursor(sessionId: string, name: string): void {
+  replayCursors.delete(cursorKey(sessionId, name));
+}

package/src/browser/refs.ts

@@ -1,9 +1,12 @@
 import type { Page, Locator } from "playwright";
 import {
   getFingerprint,
-  looseMatch,
-  fuzzyMatch,
+  buildFingerprint,
+  chooseRebindIndex,
+  RAW_FP_SCRIPT,
   type Fingerprint,
+  type RawFp,
+  type RebindCandidate,
 } from "./identity.js";
 
 export class EngineError extends Error {
@@ -52,15 +55,20 @@ export async function resolveLocator(
     if (sessionId) {
       const expected = getFingerprint(sessionId, t);
       if (expected) {
-        const actual = await fingerprintAt(page, loc).catch(() => null);
+        // Validate against the SAME extractor that registered the snapshot
+        const raws = (await page.evaluate(RAW_FP_SCRIPT).catch(() => null)) as
+          | RawFp[]
+          | null;
+        const idx = Number(t.slice(1));
+        const actual = raws && raws[idx] ? buildFingerprint(raws[idx]) : null;
         if (actual) {
           const exact =
             expected.role === actual.role &&
             expected.accessibleName === actual.accessibleName &&
             expected.textHash === actual.textHash;
           if (!exact) {
-            // Try rebind: search tree for loose/fuzzy match
-            const rebound = await findRebound(page, expected);
+            // Conservative rebind — ambiguous → E_STALE, never guess
+            const rebound = await findRebound(page, expected, raws);
             if (rebound) {
               // Return rebound locator; caller can check rebound flag via session
               (page as unknown as Record<string, unknown>).__rebound = true;
@@ -110,117 +118,143 @@ export async function resolveLocator(
   );
 }
 
-async function fingerprintAt(page: Page, loc: Locator): Promise<Fingerprint> {
-  const box = await loc.boundingBox().catch(() => null);
-  const data = await loc
-    .evaluate((el) => {
-      const text = (el.textContent ?? "").trim().slice(0, 80);
-      const aria = el.getAttribute("aria-label") ?? "";
-      const role = el.getAttribute("role") ?? el.tagName.toLowerCase();
-      // simple path hash: tag chain
-      let cur: Element | null = el;
-      const parts: string[] = [];
-      while (cur && parts.length < 6) {
-        parts.push(cur.tagName.toLowerCase());
-        cur = cur.parentElement;
-      }
-      return { role, accessibleName: aria, text, pathHash: parts.join(">") };
-    })
-    .catch(() => ({
-      role: "generic",
-      accessibleName: "",
-      text: "",
-      pathHash: "",
-    }));
-  return {
-    role: data.role || "generic",
-    accessibleName: (data.accessibleName || "").trim().slice(0, 80),
-    textHash: (data.text || "").trim().replace(/\s+/g, " ").slice(0, 80),
-    box: {
-      x: Math.round(box?.x ?? 0),
-      y: Math.round(box?.y ?? 0),
-      w: Math.round(box?.width ?? 0),
-      h: Math.round(box?.height ?? 0),
-    },
-    pathHash: data.pathHash || "",
-  };
-}
-
+/**
+ * Find where the element `expected` used to describe lives now.
+ * Uses the shared extractor + conservative chooser: only an UNAMBIGUOUS match
+ * is returned; zero or several equally-good candidates → null → E_STALE
+ * upstream (v0.2 bug: first-match rebind clicked toggle-all).
+ */
 async function findRebound(
   page: Page,
   expected: Fingerprint,
+  raws: RawFp[] | null,
 ): Promise<Locator | null> {
-  // Scan interactive elements for loose/fuzzy match
-  const els = await page
-    .evaluate(() => {
-      const nodes = [
-        ...document.querySelectorAll(
-          "button, a, input, select, textarea, [role=button], [tabindex]",
-        ),
-      ];
-      return nodes.slice(0, 200).map((el, i) => {
-        const text = (el.textContent ?? "")
+  const list =
+    raws ?? ((await page.evaluate(RAW_FP_SCRIPT).catch(() => [])) as RawFp[]);
+  const candidates: RebindCandidate[] = list.map((r, i) => ({
+    index: i,
+    fp: buildFingerprint(r),
+  }));
+  const pick = chooseRebindIndex(expected, candidates);
+  if (pick === null) return null;
+  return page.locator(INTERACTIVE_SELECTOR).nth(pick);
+}
+
+/**
+ * Resolve a portable, standalone selector for a target (plan §6.2 preference:
+ * id → name → ARIA label → stable data-* → placeholder → recorded text).
+ * Never returns nth-index or session-scoped e-refs; null when nothing unique
+ * can be found (caller falls back to the raw target).
+ */
+export async function stableSelectorFor(
+  page: Page,
+  target: string,
+  sessionId?: string,
+): Promise<string | null> {
+  try {
+    const loc = await resolveLocator(page, target, sessionId);
+    const cands = await loc
+      .first()
+      .evaluate((el) => {
+        const out: string[] = [];
+        const tag = el.tagName.toLowerCase();
+        const esc = (s: string) => {
+          const c = (
+            globalThis as unknown as {
+              CSS?: { escape?: (x: string) => string };
+            }
+          ).CSS;
+          return c && c.escape ? c.escape(s) : s;
+        };
+        const av = (s: string): string | null => {
+          const bs = String.fromCharCode(92);
+          if (s.indexOf('"') !== -1 || s.indexOf(bs) !== -1) return null;
+          return '"' + s + '"';
+        };
+        const uniq = (s: string): boolean => {
+          try {
+            return document.querySelectorAll(s).length === 1;
+          } catch {
+            return false;
+          }
+        };
+        // 1. stable id (skip framework-generated/dynamic ids)
+        const id = el.getAttribute("id");
+        if (
+          id &&
+          !/^(bits|radix|headlessui|react-aria|ember|react-|:)/.test(id) &&
+          !/[-_]\d+$/.test(id) &&
+          uniq("#" + esc(id))
+        ) {
+          out.push("#" + esc(id));
+        }
+        // 2. name attribute
+        const name = el.getAttribute("name");
+        if (name) {
+          const a = av(name);
+          if (a && uniq("[name=" + a + "]")) out.push("[name=" + a + "]");
+        }
+        // 3. ARIA label on the element itself
+        const aria = el.getAttribute("aria-label");
+        if (aria) {
+          const a = av(aria);
+          if (a && uniq(tag + "[aria-label=" + a + "]"))
+            out.push(tag + "[aria-label=" + a + "]");
+        }
+        // 4. stable data-* (test attrs preferred; state/animation attrs skipped)
+        const attrs = Array.prototype.slice.call(el.attributes) as Array<{
+          name: string;
+          value: string;
+        }>;
+        const dataAttrs = attrs.filter(
+          (a) =>
+            a.name.startsWith("data-") &&
+            !/^data-(state|orientation|index|selected|active|highlighted|value|radix|size|style|theme)/.test(
+              a.name,
+            ),
+        );
+        dataAttrs.sort((a, b) => {
+          const score = (n: string) =>
+            /^data-(test|testid|cy)/.test(n) ? 0 : 1;
+          return score(a.name) - score(b.name);
+        });
+        for (const a of dataAttrs) {
+          const v = av(a.value);
+          if (!v) continue;
+          const s = tag + "[" + a.name + "=" + v + "]";
+          if (uniq(s)) {
+            out.push(s);
+            break;
+          }
+        }
+        // 5. placeholder (form controls with no name/id)
+        const ph = el.getAttribute("placeholder");
+        if (ph) {
+          const a = av(ph);
+          if (a && uniq(tag + "[placeholder=" + a + "]"))
+            out.push(tag + "[placeholder=" + a + "]");
+        }
+        // 6. recorded text (Playwright exact text engine)
+        const text = (el.textContent || "")
           .trim()
           .replace(/\s+/g, " ")
-          .slice(0, 80);
-        const aria = el.getAttribute("aria-label") ?? "";
-        const role = el.getAttribute("role") ?? el.tagName.toLowerCase();
-        let cur: Element | null = el;
-        const parts: string[] = [];
-        while (cur && parts.length < 6) {
-          parts.push(cur.tagName.toLowerCase());
-          cur = cur.parentElement;
+          .slice(0, 60);
+        if (text && (tag === "button" || tag === "a")) {
+          const a = av(text);
+          if (a) out.push("text=" + a);
         }
-        return {
-          i,
-          role,
-          accessibleName: aria,
-          textHash: text,
-          pathHash: parts.join(">"),
-        };
-      });
-    })
-    .catch(
-      () =>
-        [] as Array<{
-          i: number;
-          role: string;
-          accessibleName: string;
-          textHash: string;
-          pathHash: string;
-        }>,
-    );
-  for (const e of els) {
-    const cand: Fingerprint = {
-      role: e.role,
-      accessibleName: e.accessibleName,
-      textHash: e.textHash,
-      box: { x: 0, y: 0, w: 0, h: 0 },
-      pathHash: e.pathHash,
-    };
-    if (looseMatch(expected, cand)) {
-      return page
-        .locator(
-          "button, a, input, select, textarea, [role=button], [tabindex]",
-        )
-        .nth(e.i);
-    }
-  }
-  for (const e of els) {
-    const cand: Fingerprint = {
-      role: e.role,
-      accessibleName: e.accessibleName,
-      textHash: e.textHash,
-      box: { x: 0, y: 0, w: 0, h: 0 },
-      pathHash: e.pathHash,
-    };
-    if (fuzzyMatch(expected, cand)) {
-      return page
-        .locator(
-          "button, a, input, select, textarea, [role=button], [tabindex]",
-        )
-        .nth(e.i);
+        return out;
+      })
+      .catch(() => [] as string[]);
+    for (const c of cands) {
+      const n = await page
+        .locator(c)
+        .count()
+        .catch(() => 0);
+      if (n === 1) return c;
     }
+    return null;
+  } catch {
+    return null;
   }
-  return null;
 }

package/src/http.ts

@@ -11,7 +11,7 @@ const transport = new HttpTransport(server, { path: "/mcp" });
 
 Bun.serve({
   port,
-  hostname: "127.0.0.1",
+  hostname: "0.0.0.0",
   // Bun closes idle connections after 10s by default (idleTimeout), and the
   // timer applies even while a response is being streamed. The MCP
   // Streamable-HTTP SSE notification stream sits idle between server->client

package/src/tools/act.ts

@@ -3,7 +3,7 @@ import { tool } from "tmcp/utils";
 import * as v from "valibot";
 import { loadConfig } from "../config.js";
 import { getPage, getContext } from "../browser/session.js";
-import { doAct, doBatch, doGoal, type ActAction } from "../browser/engine.js";
+import { doAct, doBatch, type ActAction } from "../browser/engine.js";
 import { EngineError } from "../browser/refs.js";
 
 export const ACT_ACTIONS = [
@@ -101,10 +101,6 @@ export const actTool = defineTool(
           JSON.stringify({ ok: true, action, url, title, ...result }),
         );
       }
-      if (action === "goal") {
-        const result = await doGoal(page, config, value ?? target ?? "", opts);
-        return tool.text(JSON.stringify({ ok: true, action, ...result }));
-      }
       const result = await doAct(
         page,
         config,