@deeeed/metamask-harness 0.14.7 → 0.15.0

package/dist/runtime-context.js

@@ -0,0 +1,228 @@
+import { createHash } from "node:crypto";
+import { execFileSync } from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { recipeRuntimeDir } from "./paths.js";
+function ensureRuntimeContext(target, adapter) {
+  const repoRoot = fs.realpathSync(target);
+  const runtimeDir = recipeRuntimeDir();
+  const contextPath = path.join(repoRoot, runtimeDir, "agentic-runtime.json");
+  const existingState = readExistingContext(contextPath, repoRoot, runtimeDir, adapter);
+  const existing = existingState.context;
+  const defaults = localDefaults(repoRoot, adapter, existing);
+  const context = {
+    schemaVersion: 1,
+    ...existing,
+    repoRoot,
+    slotId: process.env.RECIPE_SLOT_ID || existing.slotId || defaults.slotId,
+    runtimeOwner: existing.runtimeOwner && existing.runtimeOwner !== "unknown" ? existing.runtimeOwner : "mm-harness",
+    strict: existing.strict ?? true,
+    platform: existing.platform || adapter,
+    runtimeDir,
+    ...runtimeResources(adapter, existing, defaults),
+    ...gitIdentity(repoRoot)
+  };
+  if (!existing.createdAt) context.createdAt = (/* @__PURE__ */ new Date()).toISOString();
+  removeEmptyValues(context);
+  fs.mkdirSync(path.dirname(contextPath), { recursive: true });
+  writeJsonAtomic(contextPath, context);
+  hydrateRuntimeEnv(contextPath, context);
+  return {
+    path: contextPath,
+    created: !existingState.existed || Object.keys(existing).length === 0 || existingState.quarantinedPath !== void 0,
+    quarantinedPath: existingState.quarantinedPath,
+    context
+  };
+}
+function readExistingContext(contextPath, repoRoot, runtimeDir, adapter) {
+  if (!fs.existsSync(contextPath)) return { context: {}, existed: false };
+  let parsed;
+  try {
+    parsed = JSON.parse(fs.readFileSync(contextPath, "utf8"));
+  } catch {
+    return quarantineInvalidContext(contextPath);
+  }
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+    return quarantineInvalidContext(contextPath);
+  }
+  const context = parsed;
+  if (!validExistingContext(context, repoRoot, runtimeDir, adapter)) {
+    return quarantineInvalidContext(contextPath);
+  }
+  return { context, existed: true };
+}
+function validExistingContext(context, repoRoot, runtimeDir, adapter) {
+  if (context.schemaVersion !== void 0 && context.schemaVersion !== 1) return false;
+  if (context.repoRoot !== void 0 && (typeof context.repoRoot !== "string" || path.resolve(context.repoRoot) !== repoRoot)) return false;
+  if (context.platform !== void 0 && context.platform !== adapter) return false;
+  if (context.runtimeDir !== void 0 && context.runtimeDir !== runtimeDir) return false;
+  if (context.strict !== void 0 && typeof context.strict !== "boolean") return false;
+  if (context.gitDirty !== void 0 && typeof context.gitDirty !== "boolean") return false;
+  const stringFields = [
+    "project",
+    "slotId",
+    "machine",
+    "runtimeOwner",
+    "simulator",
+    "adbSerial",
+    "distDir",
+    "extensionId",
+    "gitHead",
+    "gitBranch",
+    "gitCommit",
+    "createdAt",
+    "session"
+  ];
+  for (const field of stringFields) {
+    if (context[field] !== void 0 && (typeof context[field] !== "string" || context[field].length === 0)) return false;
+  }
+  if (context.runtimeOwner !== void 0 && !["farmslot", "mm-harness", "unknown"].includes(String(context.runtimeOwner))) return false;
+  for (const field of ["cdpPort", "watcherPort", "metroPort", "devServerPort"]) {
+    const value = context[field];
+    if (value !== void 0 && (!Number.isInteger(value) || Number(value) < 1 || Number(value) > 65535)) return false;
+  }
+  if (context.runtimeStart !== void 0) {
+    if (!context.runtimeStart || typeof context.runtimeStart !== "object" || Array.isArray(context.runtimeStart)) return false;
+    const runtimeStart = context.runtimeStart;
+    if (runtimeStart.approved !== void 0 && typeof runtimeStart.approved !== "boolean") return false;
+    for (const field of ["command", "readyUrl"]) {
+      if (runtimeStart[field] !== void 0 && (typeof runtimeStart[field] !== "string" || runtimeStart[field].length === 0)) return false;
+    }
+  }
+  const forbiddenResources = adapter === "core" ? ["cdpPort", "watcherPort", "metroPort", "devServerPort", "simulator", "adbSerial", "extensionId"] : adapter === "extension" ? ["metroPort", "simulator", "adbSerial"] : ["cdpPort", "extensionId"];
+  if (forbiddenResources.some((field) => context[field] !== void 0)) return false;
+  return true;
+}
+function quarantineInvalidContext(contextPath) {
+  const quarantinedPath = `${contextPath}.invalid-${Date.now()}-${process.pid}`;
+  fs.renameSync(contextPath, quarantinedPath);
+  return { context: {}, existed: true, quarantinedPath };
+}
+function localDefaults(repoRoot, adapter, existing) {
+  const digest = createHash("sha256").update(repoRoot).digest("hex");
+  const offset = Number.parseInt(digest.slice(0, 8), 16) % 1e4;
+  const defaults = { slotId: `local-${adapter}-${digest.slice(0, 8)}` };
+  if (adapter === "extension" && !numericEnv("RECIPE_CDP_PORT", "CDP_PORT") && !existing.cdpPort) {
+    defaults.cdpPort = claimLocalPort(repoRoot, "cdp", 2e4 + offset);
+  }
+  if (adapter !== "core" && !numericEnv("WATCHER_PORT", "METRO_PORT", "RECIPE_WATCHER_PORT") && !existing.watcherPort && !existing.metroPort && !existing.devServerPort) {
+    defaults.watcherPort = claimLocalPort(repoRoot, "watcher", (adapter === "extension" ? 3e4 : 4e4) + offset);
+  }
+  return defaults;
+}
+function claimLocalPort(repoRoot, kind, preferred) {
+  const registry = process.env.MM_HARNESS_PORT_REGISTRY ? path.resolve(process.env.MM_HARNESS_PORT_REGISTRY) : path.join(os.homedir(), ".cache", "mm-harness", "ports");
+  fs.mkdirSync(registry, { recursive: true });
+  const rangeStart = Math.floor(preferred / 1e4) * 1e4;
+  for (let step = 0; step < 1e4; step += 1) {
+    const port = rangeStart + (preferred - rangeStart + step) % 1e4;
+    const claimPath = path.join(registry, `${port}.json`);
+    const claim = { schemaVersion: 1, port, kind, repoRoot, createdAt: (/* @__PURE__ */ new Date()).toISOString() };
+    try {
+      const fd = fs.openSync(claimPath, "wx", 384);
+      fs.writeFileSync(fd, `${JSON.stringify(claim, null, 2)}
+`);
+      fs.closeSync(fd);
+      return port;
+    } catch (error) {
+      if (error.code !== "EEXIST") throw error;
+      const owner = readPortClaim(claimPath);
+      if (owner?.repoRoot === repoRoot) return port;
+      if (!owner || !portClaimIsLive(owner, port)) {
+        fs.rmSync(claimPath, { force: true });
+        step -= 1;
+      }
+    }
+  }
+  throw new Error(`no local ${kind} port is available in ${rangeStart}-${rangeStart + 9999}`);
+}
+function readPortClaim(claimPath) {
+  try {
+    const value = JSON.parse(fs.readFileSync(claimPath, "utf8"));
+    return value && typeof value === "object" && !Array.isArray(value) ? value : null;
+  } catch {
+    return null;
+  }
+}
+function portClaimIsLive(claim, port) {
+  if (typeof claim.repoRoot !== "string" || !fs.existsSync(claim.repoRoot)) return false;
+  const contextPath = path.join(claim.repoRoot, recipeRuntimeDir(), "agentic-runtime.json");
+  try {
+    const context = JSON.parse(fs.readFileSync(contextPath, "utf8"));
+    return context.cdpPort === port || context.watcherPort === port || context.metroPort === port || context.devServerPort === port;
+  } catch {
+    const created = typeof claim.createdAt === "string" ? Date.parse(claim.createdAt) : Number.NaN;
+    return Number.isFinite(created) && Date.now() - created < 6e4;
+  }
+}
+function runtimeResources(adapter, existing, defaults) {
+  if (adapter === "core") return {};
+  const watcherPort = numericEnv("WATCHER_PORT", "METRO_PORT", "RECIPE_WATCHER_PORT") ?? existing.watcherPort ?? existing.metroPort ?? existing.devServerPort ?? defaults.watcherPort;
+  const shared = {
+    watcherPort,
+    devServerPort: watcherPort
+  };
+  if (adapter === "extension") {
+    shared.cdpPort = numericEnv("RECIPE_CDP_PORT", "CDP_PORT") ?? existing.cdpPort ?? defaults.cdpPort;
+  } else {
+    shared.metroPort = watcherPort;
+    shared.simulator = process.env.IOS_SIMULATOR || existing.simulator;
+    shared.adbSerial = process.env.ADB_SERIAL || process.env.ANDROID_SERIAL || existing.adbSerial;
+  }
+  return shared;
+}
+function numericEnv(...names) {
+  for (const name of names) {
+    const raw = process.env[name];
+    if (!raw || !/^\d+$/u.test(raw)) continue;
+    return Number(raw);
+  }
+  return void 0;
+}
+function gitIdentity(repoRoot) {
+  return {
+    gitHead: git(repoRoot, ["rev-parse", "HEAD"]),
+    gitBranch: git(repoRoot, ["branch", "--show-current"]),
+    gitDirty: Boolean(git(repoRoot, ["status", "--short"]))
+  };
+}
+function git(repoRoot, args) {
+  try {
+    return execFileSync("git", ["-C", repoRoot, ...args], {
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"]
+    }).trim() || void 0;
+  } catch {
+    return void 0;
+  }
+}
+function removeEmptyValues(context) {
+  for (const [key, value] of Object.entries(context)) {
+    if (value === void 0 || value === null || value === "") delete context[key];
+  }
+}
+function writeJsonAtomic(file, value) {
+  const temporary = `${file}.${process.pid}.tmp`;
+  fs.writeFileSync(temporary, `${JSON.stringify(value, null, 2)}
+`, { mode: 384 });
+  fs.renameSync(temporary, file);
+}
+function hydrateRuntimeEnv(contextPath, context) {
+  process.env.RECIPE_RUNTIME_CONTEXT = contextPath;
+  setEnv("RECIPE_SLOT_ID", context.slotId);
+  setEnv("CDP_PORT", context.cdpPort);
+  setEnv("RECIPE_CDP_PORT", context.cdpPort);
+  setEnv("WATCHER_PORT", context.watcherPort);
+  setEnv("RECIPE_WATCHER_PORT", context.watcherPort);
+  setEnv("METRO_PORT", context.metroPort ?? context.watcherPort);
+  setEnv("IOS_SIMULATOR", context.simulator);
+  setEnv("ADB_SERIAL", context.adbSerial);
+  setEnv("ANDROID_SERIAL", context.adbSerial);
+}
+function setEnv(name, value) {
+  if (value !== void 0 && value !== null && value !== "") process.env[name] = String(value);
+}
+export {
+  ensureRuntimeContext
+};

package/docs/CLI-SPEC.md

@@ -286,19 +286,23 @@ Recovery is silent in human mode. With `--json`: `"recovered": ["metro.restarted
 > `runOneNode` in `runner/src/cli.ts`). `set` always prints the fixture edit path;
 > the password is read FROM the fixture, never typed. On-device seed is Tier B.
 
-**One canonical wallet fixture per checkout** — same SSOT model as the farm installer. There is no fixture selection, listing, or bare status verb. **Fixture status is reported by `doctor` automatically** (grounded: `doctor.ts` `fixtureSummary()` already returns `{ status: 'missing'|'ready'|'incomplete'|'invalid', path, accountCount, hasPassword }` and is included in `createDoctorReport()` at line 125). The human edits `wallet-fixture.json` directly; `fixtures set` always teaches where.
+**One canonical wallet fixture per checkout** — same SSOT model as the farm installer. `init --from` copies an existing secure team/test fixture; explicit `init --dev` creates a disposable public test wallet that must never hold real funds. **Fixture status is reported by `doctor` automatically.**
 
-**Synopsis:** `mm-harness fixtures <sync|set|generate|finalize> [flags]` — subcommand required.
+**Synopsis:** `mm-harness fixtures <init|sync|set|generate|finalize> [flags]` — subcommand required.
 
 | Subcommand | Behavior |
 |---|---|
+| `init` | Create the canonical fixture from `--from <path>` or explicit `--dev`; refuse replacement unless `--force` is supplied |
 | `sync` | Refresh **wallet fixture files** on the target (wallet DATA only — overlay refresh is `--heal` / `doctor --fix` territory, NOT `fixtures`; they are separate concerns) |
-| `set` | Apply THE canonical fixture (SRP/password/accounts) to the running slot — password read FROM the fixture, never typed; always prints "Want different accounts? Edit: <absolute-path>/wallet-fixture.json" |
+| `set` | Apply THE canonical fixture (SRP/password/accounts) to Mobile/Extension; Core validates and reads the same fixture directly for signing |
 | `generate` | Render the extension `fixture-state.json` from a wallet fixture for pre-launch profile prefill (fronts `adapters/extension/wallet-fixture-state.cjs generate`). **Extension-only** (mobile/core teach). Requires `--fixture <wallet-fixture.json>` and `--out <fixture-state.json>`. This is the public surface for farm packs that need the pre-launch fixture-state file, replacing direct reach-in to the internal leaf. |
 | `finalize` | Seed account labels/selection into the **live** extension over CDP and validate import parity (fronts `adapters/extension/wallet-fixture-state.cjs seed-cdp`). **Extension-only, post-launch** (mobile/core teach). Requires `--fixture`, `--state`, `--cdp-port`, `--extension-dir`. This is the public surface for farm packs that finalize account labels after launch, replacing the last direct reach-in to the internal leaf. |
 
 | Flag | Type | Default | ENV (agent) | Audience | Description |
 |---|---|---|---|---|---|
+| `--from <json>` | path | — | — | both | `init`: copy an existing fixture without exposing its values in arguments |
+| `--dev` | bool | false | — | both | `init`: create a disposable public test wallet; never real funds |
+| `--force` | bool | false | — | both | `init`: intentionally replace the canonical fixture |
 | `--fixture <json>` | path | slot's `wallet-fixture.json` (`set`/`sync`); **required** for `generate`/`finalize` (input wallet fixture) | `RECIPE_WALLET_FIXTURE` | **agent** (`set`/`sync`); both (`generate`/`finalize`) | `set`/`sync`: override fixture path (human form = edit the canonical file directly). `generate`/`finalize`: the input wallet fixture. |
 | `--out <json>` | path | `generate`: **required**; `finalize`: leaf default report path | — | both | `generate`: output `fixture-state.json`. `finalize`: optional validation report path. |
 | `--state <json>` | path | — (**required** for `finalize`) | — | both | `finalize` only: the pre-launch `fixture-state.json` to seed into the live wallet |
@@ -393,9 +397,9 @@ Readiness check for a checkout without launching the app. Doctor is the single p
 
 | Field | Env var set by harness | Flag override | How to customize |
 |---|---|---|---|
-| `slotId` | `RECIPE_SLOT_ID` | `--slot` | farmslot dispatch writes it |
-| `extensionId` | `RECIPE_HARNESS_EXTENSION_ID` | — | auto-resolved; edit file to pin |
-| `cdpPort` | `RECIPE_CDP_PORT` / `CDP_PORT` | `--cdp-port` | edit file or pass flag |
+| `slotId` | `RECIPE_SLOT_ID` | `--slot` | `doctor --fix` creates local identity; Farmslot may override |
+| `extensionId` | `RECIPE_HARNESS_EXTENSION_ID` | — | resolved from the built extension |
+| `cdpPort` | `RECIPE_CDP_PORT` / `CDP_PORT` | `--cdp-port` | `doctor --fix` claims one; flag overrides |
 | `runtimeStart.approved` | `RECIPE_RUNTIME_START_APPROVED` | — | edit file (`true`/`false`) |
 | `runtimeStart.command` | — | — | edit file |
 | `runtimeStart.readyUrl` | `RECIPE_RUNTIME_READY_URL` | — | edit file |
@@ -412,9 +416,9 @@ Readiness check for a checkout without launching the app. Doctor is the single p
     "fileExists": true,
     "envOverride": null,
     "fields": {
-      "slotId":   { "value": "slot-1", "source": "file", "envVar": "RECIPE_SLOT_ID", "customize": "farmslot dispatch writes this" },
-      "extensionId": { "value": "abc123", "source": "file", "envVar": "RECIPE_HARNESS_EXTENSION_ID", "customize": "auto-resolved; edit file to pin" },
-      "cdpPort":  { "value": "6663", "source": "file", "envVar": "CDP_PORT", "customize": "edit file or pass --cdp-port" },
+      "slotId":   { "value": "slot-1", "source": "file", "envVar": "RECIPE_SLOT_ID", "customize": "doctor --fix creates local identity; Farmslot may override" },
+      "extensionId": { "value": "abc123", "source": "file", "envVar": "RECIPE_HARNESS_EXTENSION_ID", "customize": "resolved from the built extension" },
+      "cdpPort":  { "value": "6663", "source": "file", "envVar": "CDP_PORT", "customize": "doctor --fix claims one; --cdp-port overrides" },
       "runtimeStart.approved": { "value": "true", "source": "file", "envVar": "RECIPE_RUNTIME_START_APPROVED", "customize": "edit file (true/false)" },
       "runtimeStart.command": { "value": null, "source": "default", "envVar": null, "customize": "edit file" },
       "runtimeStart.readyUrl": { "value": null, "source": "default", "envVar": "RECIPE_RUNTIME_READY_URL", "customize": "edit file" }
@@ -428,7 +432,7 @@ Readiness check for a checkout without launching the app. Doctor is the single p
 | `--adapter <p>` | mobile\|extension\|core | auto-detect | `RECIPE_HARNESS_PLATFORM` | both | Target · [DEFAULT-GAP] required today |
 | `--target <repo>` | path | `$PWD` | — | both | Checkout to probe |
 | `--action-manifest <path>` | path | bundled | — | agent | Override manifest (the file; `manifest` verb is retired) |
-| `--fix` | bool | false | — | both | Run healing steps WITHOUT launching — repair overlay, runtime context, and validate manifest; no app started. Exit 0 = all healed; 1 = partial/failed. `--json` adds `"fixed": [...]` and `"failed": [...]` arrays. |
+| `--fix` | bool | false | — | both | Repair overlay/runtime context and require a usable canonical fixture without launching. Exit 0 = sandbox prerequisites ready; 1 = partial/failed. JSON adds `fixed`, `failed`, and numbered `nextActions`. |
 | `--json` | bool | false | — | agent | Machine-readable (includes fixture + runtimeContext sections; with `--fix`: adds fixed/failed arrays) |
 
 **`--fix` framing:** `doctor --fix` runs the same healing checks as `launch`/`verify`'s self-healing path but stops short of starting the app. Use it when the agent detects a broken state and wants to repair before the next `run` — or when CI needs to repair without a launch side-effect. `doctor` without `--fix` is always pure read-only.
@@ -618,7 +622,7 @@ pretty-printed fallback. `manifest` is **RETIRED**: raw protocol dump rehomes to
 | Flag | Type | Default | ENV | Audience | Description |
 |---|---|---|---|---|---|
 | `<action>` positional | string | required | — | both | Full action name or unambiguous short name (fuzzy resolved from adapter vocabulary) |
-| `--arg <k=v>` | string (repeatable) | — | — | both | Action field value; repeatable: `--arg symbol=BTC --arg side=long` |
+| `--arg <k=v>` | string (repeatable) | — | — | both | Action field value; parses JSON scalars/arrays/objects. Wrap a numeric-looking string as a JSON string, e.g. `--arg 'test_id="12345"'`. |
 | `--adapter <p>` | mobile\|extension\|core | auto-detect | `RECIPE_HARNESS_PLATFORM` | both | Target adapter |
 | `--json` | bool | false | — | **agent PRIMARY** | `{ action, resolvedAction, args, trace, evidence, recovered, mutations, exitCode, schemaVersion }` — same shape as `run --json` (one-node subset) |
 

package/docs/MENTAL-MODEL.md

@@ -58,7 +58,8 @@ good defaults for easy typing. Enforced rules, visible in every table below:
   auto-install it inline with a one-line notice on first run on that checkout.
   `install` is the explicit form for CI, agents, and deterministic setup
   (`--heal=off` on daily verbs disables the inline check and all healing).
-- **Your slot's settings live in `agentic-runtime.json` — `doctor` explains them;
+- **Your checkout's settings live in `agentic-runtime.json` — `doctor --fix` creates
+  local identity/resources when absent and `doctor` explains them;
   you never hunt for the file.** `doctor` prints every field (slotId, extensionId,
   cdpPort, runtimeStart.*), its current value, its source (file / env var /
   default), and exactly how to change it. Arthur's rule made concrete: no
@@ -157,15 +158,15 @@ Auto-ensures runtime overlay before launching (installs inline with a one-line n
 | `mm-recipe debug` | `debug` | ABSORB-LATER |
 | `mm-recipe dev-menu` · `devmenu` | `debug --dev-menu` (flag) | ABSORB-LATER · [DEFAULT-GAP] separate verb for one console concept |
 
-#### `fixtures` — sync fixture files + set up the wallet  ·  REAL (wave 3)
+#### `fixtures` — initialize/sync fixture files + set up the wallet  ·  REAL (wave 3)
 
-One canonical wallet fixture per checkout (SSOT). Fixture status is reported by `doctor` automatically (grounded: `fixtureSummary()` in `runner/src/doctor.ts`). `fixtures` group = `sync` and `set` only — no bare status verb.
+One canonical wallet fixture per checkout (SSOT). Fixture status is reported by `doctor` automatically. Initialize from an existing secure team/test fixture or explicitly choose a disposable public dev wallet; secrets are never typed into chat or command arguments.
 
-Subcommands: `fixtures sync`, `fixtures set`.
+Subcommands: `fixtures init`, `fixtures sync`, `fixtures set`, plus Extension generate/finalize helpers.
 
 | | |
 |---|---|
-| **Human form** | `mm-harness fixtures sync` · `mm-harness fixtures set` (applies THE canonical fixture — password read FROM the fixture, never typed; always prints "Want different accounts? Edit: <path>/wallet-fixture.json") |
+| **Human form** | `mm-harness fixtures init --from <path>` or explicit `--dev` · `fixtures sync` · `fixtures set` (password read FROM the fixture, never typed) |
 | **Agent / advanced** | `mm-harness fixtures set --fixture <json> --platform mobile` (`--fixture` is agent-only; humans edit the canonical file directly) |
 
 | Today (real) | → mm-harness | Status |
@@ -292,4 +293,3 @@ The surface below is settled — the design passed a three-round external review
 ## How farmslot calls mm-harness (preflight & the fleet binding)
 
 "Preflight" survives as a capability, not an exposed concept: it is what `launch` does before returning (readiness: Metro/bundle → app → health/bridge poll), with `launch --verify` as the prove-it tier and `doctor` as the read-only view. The fleet is just another agent-grade caller — farmslot prepare profiles keep their git / fixtures / deps phases, and the preflight/health hooks collapse to one call: `mm-harness launch <target> --verify --heal=auto --json`. Same-capability by construction: the machine contract (`--json` schemas, `--heal`, exit-code taxonomy, `recovered[]` / `mutations[]` / `recoverable:false`) is the one agents already use. Three bindings, one verb: the engineer types `mm-harness launch ios`; the slot's prepare hook calls the same verb with slot context; dispatch scales it across the fleet. (Full contract: CLI-SPEC.md Part 6.)
-

package/library/actions/extension/perps/perps.mjs

@@ -38,11 +38,15 @@ function selectedItems(input, items) {
   });
 }
 
+export function positionSelectionState(input, positions) {
+  return { hasMatching: selectedItems(input, positions).length > 0 };
+}
+
 async function navigatePerps(input) {
   const selected = String(input.node?.target ?? input.node?.destination ?? (input.node?.market || input.node?.symbol ? 'market' : 'home')).toLowerCase();
   return withExtensionPage(input, async (page) => {
     if (selected === 'home' || selected === 'perps' || selected === 'perps_home') {
-      const navigation = await page.navigateHash('#/?tab=perps');
+      const navigation = await page.navigateHash('#/perps-home');
       await page.waitForExpression('document.body && document.body.innerText.includes("Perps")', { timeoutMs: 15000 });
       return { action: input.action, target: selected, navigation, proofPath: 'ui-navigation' };
     }
@@ -186,6 +190,16 @@ async function requestBackground(page, method, args, timeoutMs = 20000) {
   return result;
 }
 
+async function triggerBackground(page, method, args) {
+  return page.evaluate(`(() => {
+    const request = globalThis.stateHooks?.submitRequestToBackground;
+    if (typeof request !== 'function') throw new Error('stateHooks.submitRequestToBackground is unavailable; cannot call ${method}.');
+    const pending = request(${JSON.stringify(method)}, ${JSON.stringify(args)});
+    Promise.resolve(pending).catch(() => {});
+    return { requested: true };
+  })()`);
+}
+
 function isTransientClosePriceError(result) {
   const message = String(result?.error ?? result?.message ?? '');
   // Retry local pricing/slippage races only. Provider-level oracle rejections
@@ -422,9 +436,9 @@ export async function ensurePositions(input) {
     const current = await withExtensionPage(input, async (page) => {
       const stateResult = await page.readPositions();
       if (!stateResult.available) throw new Error('stateHooks.submitRequestToBackground is unavailable; cannot ensure live Perps positions.');
-      return stateResult.positions;
+      return positionSelectionState(input, stateResult.positions);
     });
-    if (selectedItems(input, current).length === 0) await placeOrder(input);
+    if (!current.hasMatching) await placeOrder(input);
     return assertPositions(input, true);
   }
   throw new Error(`metamask.perps.ensure_positions received unsupported state: ${state}`);
@@ -573,14 +587,16 @@ async function readPerpsRuntimeState(page) {
     const hooks = globalThis.stateHooks || {};
     const request = hooks.submitRequestToBackground;
     const reduxState = hooks.store?.getState?.() || {};
-    const cleanState = hooks.getCleanAppState?.() || hooks.getState?.() || {};
+    const cleanState = (await hooks.getCleanAppState?.()) || hooks.getState?.() || {};
+    const persisted = await globalThis.chrome?.storage?.local?.get?.('data');
     // Extension flattens PerpsController state into state.metamask via ComposableObservableStore.getFlatState().
     const metamask = reduxState.metamask || cleanState.metamask || {};
-    const nestedPerps = metamask.PerpsController || cleanState.PerpsController || cleanState.perps || {};
+    const nestedPerps = persisted?.data?.PerpsController || metamask.PerpsController || cleanState.PerpsController || cleanState.perps || {};
     return {
       available: typeof request === 'function',
       activeProvider: metamask.activeProvider || nestedPerps.activeProvider || 'hyperliquid',
-      isTestnet: Boolean(metamask.isTestnet ?? nestedPerps.isTestnet),
+      networkKnown: typeof nestedPerps.isTestnet === 'boolean',
+      isTestnet: Boolean(nestedPerps.isTestnet),
       initializationState: metamask.initializationState || nestedPerps.initializationState || null,
       isEligible: Boolean(metamask.isEligible ?? nestedPerps.isEligible),
     };
@@ -607,8 +623,11 @@ async function ensureNetwork(input, config) {
   return withExtensionPage(input, async (page) => {
     const before = await readPerpsRuntimeState(page);
     if (!before.available) throw new Error('stateHooks.submitRequestToBackground is unavailable; cannot enforce Perps network.');
+    if (!before.networkKnown) throw new Error('Unable to read the current Perps network from persisted controller state.');
     if (Boolean(before.isTestnet) === expectedTestnet) return { requested: config.network, isTestnet: before.isTestnet, changed: false };
-    const result = await requestBackground(page, 'perpsToggleTestnet', []);
+    // The toggle request can remain pending after the controller state changes.
+    // Convergence is proved by the bounded state poll below, not request completion.
+    const result = await triggerBackground(page, 'perpsToggleTestnet', []);
     const after = await waitForNetworkState(page, expectedTestnet, Number(input.node?.timeout_ms ?? 30000));
     if (Boolean(after.isTestnet) !== expectedTestnet) {
       throw new Error(`Expected Perps network ${config.network}, got isTestnet=${after.isTestnet}.`);
@@ -660,13 +679,15 @@ async function assertBalance(input, config) {
 export async function startState(input) {
   const params = paramsForState(input);
   const config = mergeStateConfig(profileDefaults(params.profile), params);
+  // Enter the Perps surface first so its stream bridge/controller API exists
+  // before provider, network, order, or position convergence begins.
+  const navigation = await applyStateNavigation(input, config);
   const provider = await ensureProvider(input, config);
   const network = await ensureNetwork(input, config);
   const readyToTrade = await assertReadyToTrade(input, config);
   const balance = await assertBalance(input, config);
   const orders = await applyOrdersState(input, config.orders);
   const positions = await applyPositionsState(input, config.positions);
-  const navigation = await applyStateNavigation(input, config);
   return {
     action: input.action,
     profile: config.profile ?? params.profile ?? 'clean_market_testnet',

package/library/actions/extension/platform/cdp.mjs

@@ -120,18 +120,23 @@ async function captureHelperBrowserPid(context, port) {
   );
 }
 
-async function captureHelperSnapshot(page, context, relPath, metadata) {
-  if (process.platform !== 'darwin') {
-    throw new Error('Extension ui.screenshot uses capture-helper snapshot and is currently supported only on macOS.');
-  }
+async function captureCdpViewportSnapshot(page, context, relPath, metadata, captureHelperError = null) {
   const { relative, absolute } = resolveRelativeArtifactPath(context.artifactsDir, relPath);
   await mkdir(path.dirname(absolute), { recursive: true });
-
-  await page.session.call('Page.bringToFront');
-  const pid = await captureHelperBrowserPid(context, page.port);
-  const timeoutMs = Number(metadata?.timeoutMs ?? 30000);
-  const sessionSnapshot = await captureActiveRecipeRecordingSnapshot(pid, absolute, timeoutMs);
-  if (sessionSnapshot) {
+  try {
+    const timeoutMs = Number(metadata?.cdpTimeoutMs ?? 5000);
+    const result = await Promise.race([
+      page.session.call('Page.captureScreenshot', {
+        format: 'png',
+        fromSurface: true,
+        captureBeyondViewport: false,
+      }),
+      new Promise((_, reject) => setTimeout(() => reject(new Error(`Chrome Page.captureScreenshot timed out after ${timeoutMs}ms.`)), timeoutMs)),
+    ]);
+    if (typeof result?.data !== 'string' || result.data.length === 0) {
+      throw new Error('Chrome Page.captureScreenshot returned no image data.');
+    }
+    await writeFile(absolute, Buffer.from(result.data, 'base64'));
     return {
       path: relative,
       type: 'screenshot',
@@ -140,25 +145,62 @@ async function captureHelperSnapshot(page, context, relPath, metadata) {
       category: metadata?.category ?? 'evidence',
       mimeType: 'image/png',
       metadata: {
-        provider: 'capture-helper',
-        mode: 'record_session_snapshot',
-        pid,
-        captureHelper: sessionSnapshot,
+        provider: 'cdp',
+        mode: 'Page.captureScreenshot',
+        ...(captureHelperError ? { fallbackFrom: 'capture-helper', captureHelperError } : {}),
       },
     };
+  } catch (error) {
+    const cdpError = error instanceof Error ? error.message : String(error);
+    return captureDomRasterSnapshot(page, context, relPath, metadata, captureHelperError, cdpError);
   }
+}
 
-  const result = await runProcess(captureHelperPath(), ['snapshot', '--pid', String(pid), '--output', absolute], {
-    cwd: context.projectRoot,
-    env: process.env,
-    timeoutMs,
-  });
-  if (result.exitCode !== 0) {
-    throw new Error(
-      `capture-helper snapshot failed for Extension ui.screenshot (pid ${pid}): ${result.stderr || result.stdout}`,
-    );
+async function captureDomRasterSnapshot(page, context, relPath, metadata, captureHelperError, cdpError) {
+  const { relative, absolute } = resolveRelativeArtifactPath(context.artifactsDir, relPath);
+  const dataUrl = await page.evaluate(`(async () => {
+    const width = Math.max(1, window.innerWidth);
+    const height = Math.max(1, window.innerHeight);
+    const source = document.documentElement;
+    const clone = source.cloneNode(true);
+    const sourceNodes = [source, ...source.querySelectorAll('*')];
+    const cloneNodes = [clone, ...clone.querySelectorAll('*')];
+    for (let index = 0; index < sourceNodes.length; index += 1) {
+      const sourceNode = sourceNodes[index];
+      const cloneNode = cloneNodes[index];
+      if (!(sourceNode instanceof Element) || !(cloneNode instanceof Element)) continue;
+      const computed = getComputedStyle(sourceNode);
+      cloneNode.setAttribute('style', Array.from(computed).map((name) => name + ':' + computed.getPropertyValue(name) + ';').join(''));
+      if ('value' in sourceNode && typeof sourceNode.value === 'string') cloneNode.setAttribute('value', sourceNode.value);
+      if (sourceNode instanceof HTMLCanvasElement) {
+        const image = document.createElement('img');
+        try { image.src = sourceNode.toDataURL('image/png'); } catch { image.alt = 'canvas'; }
+        image.setAttribute('style', cloneNode.getAttribute('style') || '');
+        cloneNode.replaceWith(image);
+      }
+    }
+    clone.querySelectorAll('script').forEach((node) => node.remove());
+    clone.setAttribute('xmlns', 'http://www.w3.org/1999/xhtml');
+    clone.style.width = width + 'px';
+    clone.style.height = height + 'px';
+    clone.style.overflow = 'hidden';
+    const serialized = new XMLSerializer().serializeToString(clone);
+    const svg = '<svg xmlns="http://www.w3.org/2000/svg" width="' + width + '" height="' + height + '"><foreignObject width="100%" height="100%">' + serialized + '</foreignObject></svg>';
+    const image = new Image();
+    const loaded = new Promise((resolve, reject) => { image.onload = resolve; image.onerror = () => reject(new Error('DOM raster image load failed.')); });
+    image.src = 'data:image/svg+xml;base64,' + btoa(unescape(encodeURIComponent(svg)));
+    await loaded;
+    const canvas = document.createElement('canvas');
+    canvas.width = width;
+    canvas.height = height;
+    const context = canvas.getContext('2d');
+    context.drawImage(image, 0, 0, width, height);
+    return canvas.toDataURL('image/png');
+  })()`);
+  if (typeof dataUrl !== 'string' || !dataUrl.startsWith('data:image/png;base64,')) {
+    throw new Error(`Extension screenshot fallbacks failed: capture-helper=${captureHelperError ?? 'not attempted'}; cdp=${cdpError}; DOM raster returned no PNG.`);
   }
-  const details = parseJsonObject(result.stdout);
+  await writeFile(absolute, Buffer.from(dataUrl.slice('data:image/png;base64,'.length), 'base64'));
   return {
     path: relative,
     type: 'screenshot',
@@ -167,14 +209,72 @@ async function captureHelperSnapshot(page, context, relPath, metadata) {
     category: metadata?.category ?? 'evidence',
     mimeType: 'image/png',
     metadata: {
-      provider: 'capture-helper',
-      mode: 'snapshot',
-      pid,
-      ...(details ? { captureHelper: details } : {}),
+      provider: 'dom-raster',
+      mode: 'computed-style-viewport',
+      fallbackFrom: captureHelperError ? 'capture-helper+cdp' : 'cdp',
+      ...(captureHelperError ? { captureHelperError } : {}),
+      cdpError,
     },
   };
 }
 
+export async function captureHelperSnapshot(page, context, relPath, metadata) {
+  if (process.platform !== 'darwin') {
+    return captureCdpViewportSnapshot(page, context, relPath, metadata);
+  }
+  const { relative, absolute } = resolveRelativeArtifactPath(context.artifactsDir, relPath);
+  await mkdir(path.dirname(absolute), { recursive: true });
+
+  try {
+    const pid = await captureHelperBrowserPid(context, page.port);
+    const timeoutMs = Number(metadata?.timeoutMs ?? 30000);
+    const sessionSnapshot = await captureActiveRecipeRecordingSnapshot(pid, absolute, timeoutMs);
+    if (sessionSnapshot) {
+      return {
+        path: relative,
+        type: 'screenshot',
+        nodeId: context.nodeId,
+        label: metadata?.label ?? `${context.nodeId} screenshot`,
+        category: metadata?.category ?? 'evidence',
+        mimeType: 'image/png',
+        metadata: {
+          provider: 'capture-helper',
+          mode: 'record_session_snapshot',
+          pid,
+          captureHelper: sessionSnapshot,
+        },
+      };
+    }
+
+    const result = await runProcess(captureHelperPath(), ['snapshot', '--pid', String(pid), '--output', absolute], {
+      cwd: context.projectRoot,
+      env: process.env,
+      timeoutMs,
+    });
+    if (result.exitCode !== 0) {
+      throw new Error(`capture-helper snapshot failed for pid ${pid}: ${result.stderr || result.stdout}`);
+    }
+    const details = parseJsonObject(result.stdout);
+    return {
+      path: relative,
+      type: 'screenshot',
+      nodeId: context.nodeId,
+      label: metadata?.label ?? `${context.nodeId} screenshot`,
+      category: metadata?.category ?? 'evidence',
+      mimeType: 'image/png',
+      metadata: {
+        provider: 'capture-helper',
+        mode: 'snapshot',
+        pid,
+        ...(details ? { captureHelper: details } : {}),
+      },
+    };
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return captureCdpViewportSnapshot(page, context, relPath, metadata, message);
+  }
+}
+
 function autolaunchEnabled(input) {
   return input.node?.launch_existing_dist === true ||
     input.node?.autolaunch === true ||

package/library/actions/extension/ui/navigate.mjs

@@ -2,7 +2,7 @@ import { runAdapter, withExtensionPage } from '../platform/cdp.mjs';
 
 const PAGE_HASHES = {
   home: '#/',
-  perps: '#/?tab=perps',
+  perps: '#/perps-home',
 };
 
 function text(value) {