@deeeed/metamask-harness 0.50.1 → 0.50.3

package/CHANGELOG.md

@@ -2,6 +2,16 @@
 
 ## Unreleased
 
+## 0.50.3 - 2026-09-09
+
+- Recognize enabled form controls through recipe-harness 0.16.1; report Extension startup crashes without reload-based RPC probes or automatic relaunch recovery.
+- Color human recipe help while keeping JSON plain; clarify recipe composition, Extension timing capture, acceptance criteria, and team-library updates.
+- Make architecture topics expandable and correct cheatsheet platform, recording, and recipe examples.
+
+## 0.50.2 - 2026-09-08
+
+- Remove Mobile receipt actions that require unpublished app/SDK APIs; reject stale receipt-based assertion and cleanup inputs before execution.
+
 ## 0.50.1 - 2026-09-08
 
 - Hand Extension builds to a fresh background worker before readiness, including watched edits and quick reloads, while preserving wallet profiles and native sidepanels. Refuse development copies over release artifacts.

package/README.md

@@ -158,6 +158,10 @@ mm-harness run --list
 Shared libraries hold durable actions and composable recipes. Task acceptance
 criteria remain task-local. See [Recipes](docs/RECIPES.md).
 
+Teams maintain their library checkouts. Update them before starting a task;
+the harness records local revisions and recipe digests but does not fetch or
+check for upstream updates. Keep the selected library unchanged during a run.
+
 ## Recover
 
 ```bash

package/dist/adapters/extension/runtime-decision.js

@@ -441,6 +441,16 @@ async function decideExtensionReadiness(target, options = {}) {
       reasons: ["Build is fresh and the extension runtime is healthy over CDP."],
       actions: []
     },
+    {
+      when: cdp.errorCode === "EXTENSION_BACKGROUND_UNRESPONSIVE",
+      decision: "blocked",
+      reasonCode: "background-unresponsive",
+      reasons: [
+        "Extension startup failed; inspect the background error before relaunching or resetting wallet state.",
+        ...cdp.findings?.slice(0, 3) ?? []
+      ],
+      actions: []
+    },
     {
       when: cdp.errorCode === "EVM_RPC_EXECUTION_FAILED",
       decision: "blocked",
@@ -492,6 +502,13 @@ async function decideExtensionReadiness(target, options = {}) {
         reasons: [`Release artifact ${releaseArtifact.expectedVersion} is intact and healthy over CDP.`],
         actions: []
       },
+      {
+        when: cdp.errorCode === "EXTENSION_BACKGROUND_UNRESPONSIVE",
+        decision: "blocked",
+        reasonCode: "background-unresponsive",
+        reasons: ["Extension startup failed; inspect the background error before relaunching or resetting wallet state.", ...cdp.findings?.slice(0, 3) ?? []],
+        actions: []
+      },
       {
         when: cdp.errorCode === "EVM_RPC_EXECUTION_FAILED",
         decision: "blocked",

package/dist/adapters/extension/runtime.js

@@ -51,7 +51,7 @@ async function assertHealthyExtensionRuntime(options) {
       pageMode: options.pageMode
     });
     if (lastReport.status === "PASS") return lastReport;
-    if (lastReport.errorCode === "UI_COMPOSITOR_SUSPENDED") {
+    if (lastReport.errorCode === "UI_COMPOSITOR_SUSPENDED" || lastReport.errorCode === "EXTENSION_BACKGROUND_UNRESPONSIVE") {
       throw new Error(formatHealthFailure(lastReport, options.projectRoot));
     }
     await sleep(500);
@@ -151,6 +151,23 @@ async function checkExtensionRuntimeHealth(projectRoot, cdpPort, options = {}) {
       };
     }
     const runtime = await evaluateHealth(session, cdpCallTimeoutMs);
+    if (runtime.backgroundUnresponsive === true) {
+      return {
+        status: "FAIL",
+        errorCode: "EXTENSION_BACKGROUND_UNRESPONSIVE",
+        userAction: `mm-harness logs --target ${shellQuote(projectRoot)} --full  # inspect the startup error before restarting or resetting an authorized dev fixture`,
+        cdpPort,
+        targetUrl: target.url,
+        extensionId: safeExtensionId(target),
+        extensionPageTargets: extensionTargets.length,
+        findings: ["EXTENSION_BACKGROUND_UNRESPONSIVE: Extension UI reports a startup failure or unresponsive background; RPC readiness cannot be established."],
+        details: {
+          projectRoot,
+          targetUrls: targets.map((entry) => entry.url).filter(Boolean),
+          runtime
+        }
+      };
+    }
     if (runtime.hasSubmitRequest !== true) {
       const providerProbe = await probeUiEthereumProvider(session, cdpCallTimeoutMs);
       runtime.evmRpcProbeOk = providerProbe.ok;
@@ -160,9 +177,6 @@ async function checkExtensionRuntimeHealth(projectRoot, cdpPort, options = {}) {
     if (runtime.href && !String(runtime.href).startsWith("chrome-extension://")) {
       findings.push(`Extension page href is not an extension URL: ${runtime.href}`);
     }
-    if (runtime.backgroundUnresponsive === true) {
-      findings.push("Extension UI reports background connection unresponsive.");
-    }
     if (runtime.ethereumConnectionUnavailable === true) {
       findings.push('Extension UI reports "Unable to connect to Ethereum".');
     }

package/dist/commands/help.js

@@ -1,5 +1,6 @@
 import fs from "node:fs";
 import path from "node:path";
+import { color } from "../cli-color.js";
 import { detectAdapter } from "../harness.js";
 import { optionString, parseArgs, targetPath } from "./parse-args.js";
 const UNSCOPED_NEXT = "cd into a MetaMask checkout or pass --adapter <mobile|extension|core>";
@@ -48,21 +49,22 @@ function recipeHelpPayload(topic, harnessVersion, adapter, target) {
   };
 }
 function renderRecipeHelp(topic, harnessVersion, adapter) {
+  const paint = (style, text) => color(style, text, { stream: process.stdout });
   const lines = [
-    `mm-harness ${harnessVersion} recipe guide`,
-    `Context: Recipe Protocol v${topic.recipeProtocolVersion}, adapter ${adapter}`,
+    paint("bold", `mm-harness ${harnessVersion} recipe guide`),
+    paint("dim", `Context: Recipe Protocol v${topic.recipeProtocolVersion}, adapter ${adapter}`),
     topic.summary,
     topic.capabilities,
-    topic.scopeNotice,
-    "Visual tutorial: mm-harness tutorial"
+    paint("warn", topic.scopeNotice),
+    `Visual tutorial: ${paint("cmd", "mm-harness tutorial")}`
   ];
-  if (adapter === "unscoped") lines.push(`No MetaMask checkout detected. Next: ${UNSCOPED_NEXT}.`);
+  if (adapter === "unscoped") lines.push(paint("warn", `No MetaMask checkout detected. Next: ${UNSCOPED_NEXT}.`));
   for (const [index, section] of scopedSections(topic, adapter).entries()) {
-    lines.push("", `${index + 1}. ${section.title}`, `   ${section.instruction}`);
+    lines.push("", paint("label", `${index + 1}. ${section.title}`), `   ${section.instruction}`);
     for (const detail of section.details) lines.push(`   - ${detail}`);
-    for (const command of section.commands) lines.push(`   $ ${command}`);
+    for (const command of section.commands) lines.push(`   $ ${paint("cmd", command)}`);
   }
-  lines.push("", `Safety: ${topic.safety}`);
+  lines.push("", `${paint("warn", "Safety:")} ${topic.safety}`);
   return `${lines.join("\n")}
 `;
 }

package/dist/commands/launch/index.js

@@ -310,6 +310,16 @@ async function handleLaunchLocked(argv, stream) {
       exitCode: EXIT.infra
     });
   }
+  if (adapter === "extension" && attempt.output.includes("EXTENSION_BACKGROUND_UNRESPONSIVE:")) {
+    return launchFail(jsonOutput, stream, adapter, mobileTarget, tier, state, target, {
+      code: "EXTENSION_BACKGROUND_UNRESPONSIVE",
+      message: "Extension startup failed; inspect the background error before restarting or resetting wallet state.",
+      recoverable: false,
+      userAction: `mm-harness logs --target ${shellQuote(target)} --full`,
+      exitCode: EXIT.runtime,
+      originalError: attempt.output.trim() || void 0
+    });
+  }
   if (adapter === "extension" && attempt.output.includes("EVM_RPC_EXECUTION_FAILED:")) {
     return launchFail(jsonOutput, stream, adapter, mobileTarget, tier, state, target, {
       code: "EVM_RPC_EXECUTION_FAILED",

package/docs/QA.md

@@ -56,8 +56,8 @@ mm-harness verify
 - [ ] Bad input fails before runtime work with a stable code and one exact next
   action.
 - [ ] `doctor --fix` is idempotent and does not choose a fixture or launch.
-- [ ] With `capture-helper` absent, Extension reports CDP screenshots and Mobile
-  reports `simctl`/ADB screenshots; video is honestly unavailable.
+- [ ] With `capture-helper` absent, Extension reports CDP screenshots and no
+  Extension video; Mobile reports its independent simctl/ADB capture readiness.
 
 Run the bounded multi-platform preflight when all three checkouts are available:
 
@@ -177,8 +177,8 @@ Before release:
   Core scenarios.
 - [ ] Independent review approves the exact final diff.
 - [ ] Known limits are explicit: Extension requires product Infura setup;
-  Mobile requires its normal dev-client/device setup; video requires optional
-  `capture-helper`; the harness never invents funded fixtures.
+  Mobile requires its normal dev-client/device setup; Extension video requires
+  `capture-helper`, while Mobile uses platform recorders; the harness never invents funded fixtures.
 - [ ] Existing [Farmslot](https://farmslot.io) slots remain compatible.
 
 When a slot manager is available, repeat `runner.smoke` in one existing managed

package/docs/RECIPES.md

@@ -96,6 +96,23 @@ detached-DOM check, and idle-control comparison. A one-screen slope does not
 prove those broader claims. Check the suite's reference markers against the
 tested build before running it.
 
+### Extension timing observation
+
+First inspect `app.performance_capture` and `app.network_capture`. When the
+`recipe-performance` skill is installed, its
+`scripts/capture-extension-window.mjs --help` describes capture around a single
+command. Run that wrapper outside the recipe; a command node cannot start a
+second `mm-harness run/call` while its parent owns the checkout sandbox.
+
+For a custom observer blocked by LavaMoat, register a pre-boot script with
+`Page.addScriptToEvaluateOnNewDocument` to retain only the required native API
+reference, such as a bound `requestAnimationFrame`. Initialize it during explicit
+setup, remove the preload after use, and clean up the observer afterward. Do not
+disable scuttling, pause the debugger, or reload inside the measured window.
+Record lifecycle identity and use the application's clock for UI timing; CLI
+duration is a different measurement. Keep endpoint and readiness predicates in
+the team recipe, not a new harness action.
+
 ### Extension Perps release recipes
 
 Discover these identifiers with `run --list --adapter extension --json` and
@@ -189,6 +206,10 @@ export RECIPE_LIBRARY_PATH="perps=/path/to/experimental-metamask-recipe-perps"
 
 `perps.pro-order-setup` preserves existing orders, positions, and strategies by
 default. Its Scale, Chase, and TWAP placement callers inherit that policy.
+All three placement helpers require explicit `account` and `notional` inputs.
+Scale also requires `start_price` and `end_price`; Chase requires `max_distance`.
+Choose values for the current market and approved budget. Preserve JSON quotes
+for string parameters, for example `'notional="15"'`; inspect `--describe` first.
 When a proof requires a clean testnet market, reserve the account/market and
 compose explicit setup with `trading_state=clean_selected_testnet_market`.
 This parameter never authorizes cleanup of another task's trades.

package/library/actions/mobile/perps/assert_orders.mjs

@@ -1,7 +1,6 @@
 // Assert that selected Perps orders are open or absent using the Mobile controller.
 import { runAdapter } from '../platform/bridge.mjs';
 import { assertOrders } from './perps.mjs';
-import { useOrderReceipt } from './order-receipt.mjs';
 
 function expectedOpen(input) {
   if (input.node?.state == null) throw new Error('metamask.perps.assert_orders requires state=open or state=none.');
@@ -11,6 +10,7 @@ function expectedOpen(input) {
   throw new Error(`metamask.perps.assert_orders received unsupported state: ${state}`);
 }
 
-runAdapter((input) => Object.hasOwn(input.node ?? {}, 'confirmation')
-  ? useOrderReceipt(input, 'orders')
-  : assertOrders(input, expectedOpen(input)));
+runAdapter((input) => {
+  if (Object.hasOwn(input.node ?? {}, 'confirmation')) throw new Error('Receipt-based Mobile assertions are unsupported. Next: mm-harness help');
+  return assertOrders(input, expectedOpen(input));
+});

package/library/actions/mobile/perps/assert_positions.mjs

@@ -1,7 +1,6 @@
 // Assert that selected Perps positions are open or absent using the Mobile controller.
 import { runAdapter } from '../platform/bridge.mjs';
 import { assertPositions } from './perps.mjs';
-import { useOrderReceipt } from './order-receipt.mjs';
 
 function expectedOpen(input) {
   if (input.node?.state == null) throw new Error('metamask.perps.assert_positions requires state=open or state=none.');
@@ -11,6 +10,7 @@ function expectedOpen(input) {
   throw new Error(`metamask.perps.assert_positions received unsupported state: ${state}`);
 }
 
-runAdapter((input) => Object.hasOwn(input.node ?? {}, 'confirmation')
-  ? useOrderReceipt(input, 'positions')
-  : assertPositions(input, expectedOpen(input)));
+runAdapter((input) => {
+  if (Object.hasOwn(input.node ?? {}, 'confirmation')) throw new Error('Receipt-based Mobile assertions are unsupported. Next: mm-harness help');
+  return assertPositions(input, expectedOpen(input));
+});

package/library/actions/mobile/perps/close_orders.mjs

@@ -1,10 +1,9 @@
 // Cancel selected Perps orders through the Mobile controller and assert their absence.
 import { runAdapter } from '../platform/bridge.mjs';
 import { assertOrders, closeOrders } from './perps.mjs';
-import { useOrderReceipt } from './order-receipt.mjs';
 
 runAdapter(async (input) => {
-  if (Object.hasOwn(input.node ?? {}, 'confirmation')) return useOrderReceipt(input, 'cancel');
+  if (Object.hasOwn(input.node ?? {}, 'confirmation')) throw new Error('Receipt-based Mobile cleanup is unsupported; no orders were cancelled. Next: mm-harness help');
   const close = await closeOrders(input);
   const assertion = await assertOrders(input, false);
   return { ...assertion, close };

package/library/actions/mobile/perps/close_positions.mjs

@@ -1,10 +1,9 @@
 // Close selected Perps positions through the Mobile controller and assert their absence.
 import { runAdapter } from '../platform/bridge.mjs';
 import { assertPositions, closePositions } from './perps.mjs';
-import { useOrderReceipt } from './order-receipt.mjs';
 
 runAdapter(async (input) => {
-  if (Object.hasOwn(input.node ?? {}, 'confirmation')) return useOrderReceipt(input, 'close');
+  if (Object.hasOwn(input.node ?? {}, 'confirmation')) throw new Error('Receipt-based Mobile cleanup is unsupported; no positions were closed. Next: mm-harness help');
   const close = await closePositions(input);
   const assertion = await assertPositions(input, false);
   return { ...assertion, close };

package/library/manifests/mobile.action-manifest.json

@@ -2399,7 +2399,6 @@
       "schema": {
         "type": "object",
         "properties": {
-          "confirmation": { "type": "object", "description": "Frozen read_order_input output; requires exact live UI receipt identity." },
           "market": {
             "type": "string",
             "description": "Single market symbol, e.g. BTC or ETH. Alias: symbol."
@@ -2491,7 +2490,6 @@
       "schema": {
         "type": "object",
         "properties": {
-          "confirmation": { "type": "object", "description": "Frozen read_order_input output; requires exact live UI receipt identity." },
           "market": {
             "type": "string",
             "description": "Single market symbol, e.g. BTC or ETH. Alias: symbol."
@@ -2578,32 +2576,6 @@
       ],
       "execution_capabilities": ["app-mutation", "external-mutation"]
     },
-    "metamask.perps.read_order_input": {
-      "description": "Freeze committed unsigned Mobile inputs and require a receipt observer before UI submission.",
-      "examples": [{ "action": "metamask.perps.read_order_input", "amount": "10", "leverage": 1, "protection": "none", "intent": "Freeze the exact unsigned order before its UI submission", "next": "submit-order" }],
-      "schema": {
-        "type": "object", "required": ["amount", "leverage"], "additionalProperties": false,
-        "properties": {
-          "amount": { "type": ["string", "number"] },
-          "leverage": { "type": "number" },
-          "identity": { "type": "object" },
-          "protection": { "type": "string", "enum": ["none", "take_profit", "stop_loss", "both"], "default": "none" }
-        }
-      },
-      "execution_capabilities": []
-    },
-    "metamask.perps.read_order_receipt": {
-      "description": "Observe the actual Mobile UI submission result including failure and accepted IDs; never dispatch.",
-      "examples": [{ "action": "metamask.perps.read_order_receipt", "confirmation": "{{outputs.capture-input.confirmation}}", "intent": "Observe the result of the frozen UI submission", "next": "done" }],
-      "schema": {
-        "type": "object", "required": ["confirmation"], "additionalProperties": false,
-        "properties": {
-          "confirmation": { "type": "object" },
-          "timeout_ms": { "type": "number", "minimum": 1, "default": 30000 }
-        }
-      },
-      "execution_capabilities": []
-    },
     "metamask.perps.configure_order": {
       "description": "Set USD notional and visible leverage on an already-open instrumented Mobile confirmation; verify exact mounted values and native readback against its unchanged unsigned request, without submitting.",
       "schema": {
@@ -2734,7 +2706,6 @@
       "schema": {
         "type": "object",
         "properties": {
-          "confirmation": { "type": "object", "description": "Frozen read_order_input output; requires exact live UI receipt identity." },
           "market": {
             "type": "string",
             "description": "Single market symbol, e.g. BTC or ETH. Alias: symbol."
@@ -2827,7 +2798,6 @@
       "schema": {
         "type": "object",
         "properties": {
-          "confirmation": { "type": "object", "description": "Frozen read_order_input output; requires exact live UI receipt identity." },
           "market": {
             "type": "string",
             "description": "Single market symbol, e.g. BTC or ETH. Alias: symbol."

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deeeed/metamask-harness",
-  "version": "0.50.1",
+  "version": "0.50.3",
   "type": "module",
   "bin": {
     "mm-harness": "bin/mm-harness"
@@ -24,7 +24,7 @@
     "@farmslot/expo-recipe": "0.9.0",
     "@farmslot/handoff": "^0.3.1",
     "@farmslot/protocol": "0.21.0",
-    "@farmslot/recipe-harness": "0.16.0",
+    "@farmslot/recipe-harness": "0.16.1",
     "agent-device": "0.19.3",
     "commander": "^12.0.0",
     "es-module-lexer": "2.3.1",

package/site/assets/help-recipes.json

@@ -94,6 +94,7 @@
       "instruction": "Use static call references for unchanged sub-journeys. Separate preparation, action, assertions, and evidence; add workflow.teardown when cleanup must run after success or failure.",
       "details": [
         "Starting conditions are ordinary nodes at the beginning of workflow, not a preconditions field. Use idempotent ensure actions and independently assert their postconditions.",
+        "Do not invoke mm-harness run/call from a command node on the same checkout: the outer run owns its sandbox. Compose actions or call child recipes instead. External measurement wrappers may invoke one root run, with preparation outside it; never bypass the lock.",
         "Inspect existing state before creating or cleaning fixtures. Establish only prerequisites required by the claim; a history or display check may already have usable records and need no trade or cleanup. Record the selected records and verify they still satisfy the proof boundary.",
         "Match history-query ranges to the dates of existing visible records before declaring fixtures missing. Sample only sections needed for change detection; fetch one-time corroborating history once, and count background calls as well as graph nodes.",
         "Actions translate UI, CDP, or controller operations. Recipes compose them. Product code owns business rules. Teams own specialized journeys in their libraries; the harness retains shared capabilities and a small set of composable examples.",
@@ -188,6 +189,10 @@
           ]
         },
         "Performance: define a measured window, exclude setup, and compare equivalent builds, devices, and lifecycle conditions; action duration alone is not app latency.",
+        {
+          "text": "For Extension timing, inspect app.performance_capture/app.network_capture and the installed recipe-performance capture-extension-window.mjs helper before writing a collector. If LavaMoat blocks an observation API, capture its reference before initialization via Page.addScriptToEvaluateOnNewDocument during explicit setup, not inside the measured window. Keep domain predicates in the team recipe; see docs/RECIPES.md#extension-timing-observation.",
+          "adapters": ["extension"]
+        },
         "Retain samples and declared limits when a measurement fails. For memory growth, compare an equal-duration idle control before attributing it to navigation; do not raise the budget to make the run pass.",
         "Analytics: verify the collection destination and existing consent before capture. Changing participation or marketing consent requires operator approval and restoration of the prior settings; a recipe's hardcoded opt-in is not permission. Missing collection prerequisites are not missing product events.",
         "Flake risk: wait on observable state instead of sleeping, keep device and runtime identity explicit, and never overwrite a prior run's artifacts.",

package/library/actions/mobile/perps/order-receipt.mjs

@@ -1,241 +0,0 @@
-// Bind live order results and cleanup to the exact UI approval, request and accepted fills.
-import { bridgeCommand } from '../platform/bridge.mjs';
-
-function confirmationFor(input) {
-  const confirmation = input.node?.confirmation;
-  const identity = confirmation?.identity;
-  if (!identity || ['approvalId', 'account', 'provider', 'chainId', 'routeKey', 'asset', 'direction']
-    .some((field) => typeof identity[field] !== 'string' || !identity[field])
-    || !Number.isSafeInteger(identity.transactionTime) || identity.isTestnet !== true
-    || identity.provider !== 'hyperliquid' || confirmation.form?.leverage !== 1
-    || !(Number(confirmation.form?.amount) > 0 && Number(confirmation.form.amount) <= 20)) {
-    throw new Error('Mobile receipt requires a frozen Hyperliquid testnet confirmation at 1x and at most $20.');
-  }
-  return confirmation;
-}
-
-function receiptExpression(confirmation, allowMissing = false) {
-  return `
-    const expected = ${JSON.stringify(confirmation)};
-    const controller = Engine.context.PerpsController;
-    function assertIdentity() {
-      const state = controller.state;
-      const account = Engine.context.AccountsController.getSelectedAccount();
-      if (account.address.toLowerCase() !== expected.identity.account.toLowerCase()
-        || state.activeProvider !== expected.identity.provider || state.isTestnet !== true) {
-        throw new Error('Mobile receipt account, provider or network changed.');
-      }
-    }
-    assertIdentity();
-    if (typeof __AGENTIC__.readPerpsOrderReceipts !== 'function') throw new Error('Mobile UI receipt observer is unavailable.');
-    const receipts = __AGENTIC__.readPerpsOrderReceipts(expected.identity.approvalId);
-    if (${allowMissing} && Array.isArray(receipts) && receipts.length === 0) return null;
-    if (!Array.isArray(receipts) || receipts.length !== 1) throw new Error('Exactly one UI submission receipt is required.');
-    const receipt = receipts[0];
-    for (const key of ['approvalId', 'transactionTime', 'account', 'provider', 'isTestnet', 'chainId', 'routeKey']) {
-      if (receipt.identity[key] !== expected.identity[key]) throw new Error('UI receipt identity differs from the frozen confirmation.');
-    }
-    for (const key of ['asset', 'direction']) if (receipt.request[key] !== expected.identity[key]) throw new Error('UI receipt market or direction differs.');
-    for (const key of ['amount', 'leverage', 'orderType', 'limitPrice', 'takeProfitPrice', 'stopLossPrice']) {
-      if ((receipt.request[key] ?? null) !== (expected.form[key] ?? null)) throw new Error('UI receipt request differs from committed ' + key + '.');
-    }
-    const ids = [...new Set([receipt.result?.orderId, ...(receipt.result?.childOrderIds ?? [])].filter(id => typeof id === 'string' && id))];
-  `;
-}
-
-export async function readOrderReceipt(input) {
-  const confirmation = confirmationFor(input);
-  const deadline = Date.now() + Number(input.node.timeout_ms ?? 30000);
-  input = { ...input, node: { ...input.node, _action_deadline_epoch_ms: deadline } };
-  for (;;) {
-    const receipt = await bridgeCommand(input, ['eval', `(() => { ${receiptExpression(confirmation, true)} return receipt; })()`]);
-    if (receipt?.status === 'settled') {
-      const protectionCount = ['takeProfitPrice', 'stopLossPrice'].filter((key) => receipt.request[key] != null).length;
-      if (receipt.result?.success === true && protectionCount) {
-        if (receipt.request.orderType !== 'market') throw new Error('Protected limit receipts remain unsupported.');
-        if (!receipt.protectionResult) {
-          if (Date.now() >= deadline) throw new Error('Mobile protection result is unknown; do not submit again.');
-          await new Promise((resolve) => setTimeout(resolve, 250));
-          continue;
-        }
-        const protectionIds = receipt.protectionResult.childOrderIds;
-        if (receipt.protectionResult.success !== true || !Array.isArray(protectionIds)
-          || protectionIds.length !== protectionCount || new Set(protectionIds).size !== protectionCount
-          || protectionIds.some((id) => typeof id !== 'string' || !/^[1-9][0-9]*$/u.test(id)
-            || id === receipt.result.orderId || receipt.result.childOrderIds?.includes(id))) {
-          throw new Error(`Mobile protection result lacks complete accepted IDs: ${JSON.stringify(receipt.protectionResult)}.`);
-        }
-      }
-      return { action: input.action, receipt };
-    }
-    if (Date.now() >= deadline) throw new Error('Mobile UI submission result is unknown; do not submit again.');
-    await new Promise((resolve) => setTimeout(resolve, 250));
-  }
-}
-
-export async function useOrderReceipt(input, operation) {
-  const confirmation = confirmationFor(input);
-  const deadline = Date.now() + Number(input.node.timeout_ms ?? 30000);
-  input = { ...input, node: { ...input.node, _action_deadline_epoch_ms: deadline } };
-  if ((input.node.market && input.node.market !== confirmation.identity.asset)
-    || (input.node.side && input.node.side !== confirmation.identity.direction)
-    || (['positions', 'orders'].includes(operation) && input.node.state !== 'open')) {
-    throw new Error('Receipt assertion requires the same market/direction and state=open.');
-  }
-  const mutation = operation === 'cancel' || operation === 'close';
-  const result = await bridgeCommand(input, ['eval-async', `(() => {
-    ${receiptExpression(confirmation)}
-    if (receipt.status !== 'settled' || receipt.result?.success !== true || !ids.length) throw new Error('Accepted UI receipt IDs are required before state assertion or cleanup.');
-    if (receipt.result.providerId && receipt.result.providerId !== expected.identity.provider) throw new Error('Accepted provider differs from UI receipt identity.');
-    if (!['market', 'limit'].includes(receipt.request.orderType)) throw new Error('Receipt cleanup supports ordinary market and limit orders only.');
-    const market = receipt.request.asset;
-    const protectionKeys = ['takeProfitPrice', 'stopLossPrice'].filter(key => receipt.request[key] != null);
-    const protectionIds = protectionKeys.length ? receipt.protectionResult?.childOrderIds : [];
-    if (protectionKeys.length && (receipt.request.orderType !== 'market' || receipt.protectionResult?.success !== true
-      || !Array.isArray(protectionIds) || protectionIds.length !== protectionKeys.length
-      || new Set(protectionIds).size !== protectionKeys.length
-      || protectionIds.some(id => typeof id !== 'string' || !/^[1-9][0-9]*$/.test(id) || ids.includes(id)))) {
-      throw new Error('Protected cleanup requires complete distinct accepted market protection IDs.');
-    }
-    const ownedIds = ids.concat(protectionIds);
-    const sign = receipt.request.direction === 'long' ? 1n : -1n;
-    function decimal(value) {
-      const match = /^(-?)(0|[1-9][0-9]{0,19})(?:\\.([0-9]{1,8}))?$/.exec(String(value));
-      if (!match) throw new Error('Receipt fill decimal is invalid.');
-      return BigInt(match[1] + match[2] + (match[3] ?? '').padEnd(8, '0'));
-    }
-    function readSnapshot() {
-      assertIdentity();
-      if (typeof controller.getUserDataSnapshot !== 'function') throw new Error('Complete user-data snapshots are unavailable.');
-      return controller.getUserDataSnapshot().then(snapshot => {
-        assertIdentity();
-        const identity = snapshot?.identity;
-        if (!Array.isArray(snapshot?.positions) || !Array.isArray(snapshot?.orders)
-          || typeof identity?.address !== 'string' || identity.address.toLowerCase() !== expected.identity.account.toLowerCase()
-          || identity.provider !== expected.identity.provider || identity.network !== 'testnet') {
-          throw new Error('Receipt snapshot is incomplete or belongs to another identity.');
-        }
-        const orders = snapshot.orders.filter(order => order.symbol === market);
-        if (orders.some(order => !ownedIds.includes(String(order.orderId)))
-          || new Set(orders.map(order => String(order.orderId))).size !== orders.length) {
-          throw new Error('Extra or unowned market orders prevent receipt assertion or cleanup.');
-        }
-        return {orders, positions: snapshot.positions.filter(position => position.symbol === market)};
-      });
-    }
-    function verifyProtection(position, orders, present) {
-      const matchedIds = [];
-      for (const [priceKey, ordersKey] of [['takeProfitPrice','takeProfitOrders'],['stopLossPrice','stopLossOrders']]) {
-        const wanted = present ? receipt.request[priceKey] : null;
-        const triggers = position[ordersKey];
-        const count = position[priceKey === 'takeProfitPrice' ? 'takeProfitCount' : 'stopLossCount'];
-        if (!Array.isArray(triggers)) throw new Error('Exact position protection arrays are unavailable.');
-        if (wanted == null) {
-          if (triggers.length || count !== 0 || position[priceKey] != null) throw new Error('Unexpected position protection remains.');
-          continue;
-        }
-        const direction = priceKey === 'takeProfitPrice' ? 'take_profit' : 'stop';
-        const type = direction === 'take_profit' ? 'take_profit_limit' : 'stop_market';
-        if (triggers.length !== 1 || count !== 1) throw new Error('Position protection count differs from the frozen UI request.');
-        const trigger = triggers[0];
-        const order = orders.find(candidate => String(candidate.orderId) === trigger.orderId);
-        if (!protectionIds.includes(trigger.orderId) || matchedIds.includes(trigger.orderId)
-          || trigger.direction !== direction || trigger.orderType !== type || decimal(trigger.triggerPrice) !== decimal(wanted)
-          || decimal(trigger.size) !== sign * decimal(position.size) || trigger.reduceOnly !== true || trigger.isPartial !== false
-          || !order || order.side !== (sign === 1n ? 'sell' : 'buy') || order.reduceOnly !== true
-          || order.isTrigger !== true || order.isPositionTpsl !== true || order.triggerOrderType !== type
-          || decimal(order.triggerPrice) !== decimal(wanted) || decimal(order.size) !== decimal(trigger.size)) {
-          throw new Error('Exact protection ID, price, size, side or type differs from the UI receipt.');
-        }
-        matchedIds.push(trigger.orderId);
-      }
-      if (present && matchedIds.length !== protectionIds.length) throw new Error('Accepted protection IDs are not all represented in the position.');
-    }
-    function verifyLineage(position) {
-      return controller.getOrderFills({aggregateByTime: false, startTime: receipt.identity.transactionTime, endTime: Date.now()}).then(fills => {
-        assertIdentity();
-        if (!Array.isArray(fills) || fills.length >= 2000) throw new Error('Receipt fill history is incomplete.');
-        const marketFills = fills.filter(fill => fill.symbol === market);
-        if (!marketFills.length || marketFills.some(fill => !ids.includes(String(fill.orderId)))) throw new Error('Another order changed the market or parent accepted fills are unavailable.');
-        marketFills.sort((a,b) => { const difference = sign * (decimal(a.startPosition) - decimal(b.startPosition)); return difference < 0n ? -1 : difference > 0n ? 1 : 0; });
-        let size = 0n;
-        for (const fill of marketFills) {
-          if (fill.side !== (sign === 1n ? 'buy' : 'sell') || decimal(fill.size) <= 0n || decimal(fill.startPosition) !== size) throw new Error('Parent accepted fills do not prove a position starting from zero.');
-          size += sign * decimal(fill.size);
-        }
-        if (size !== decimal(position.size) || position.leverage?.value !== receipt.request.leverage) throw new Error('Current position differs from exact parent fills or leverage.');
-        return marketFills;
-      });
-    }
-    function cancelOwned(orders, baseline) {
-      const results = [];
-      function waitForCancellation() {
-        return readSnapshot().then(after => {
-          if (baseline && (after.positions.length !== 1 || after.positions[0].size !== baseline.size
-            || after.positions[0].entryPrice !== baseline.entryPrice || after.positions[0].leverage?.value !== baseline.leverage.value)) {
-            throw new Error('Owned position changed during protective cancellation.');
-          }
-          if (!after.orders.length) {
-            if (baseline) verifyProtection(after.positions[0], after.orders, false);
-            return {after, results};
-          }
-          if (Date.now() >= ${deadline}) throw new Error('Accepted order cancellation is not independently confirmed.');
-          return new Promise(resolve => setTimeout(resolve, 250)).then(waitForCancellation);
-        });
-      }
-      return orders.reduce((previous, order) => previous.then(() => {
-        if (Date.now() >= ${deadline}) throw new Error('Receipt cleanup deadline elapsed before cancellation.');
-        assertIdentity();
-        return controller.cancelOrder({symbol: market, orderId: String(order.orderId)}).then(result => {
-          results.push({orderId: order.orderId, result});
-          if (result?.success !== true) throw new Error('Exact receipt cancellation failed: ' + JSON.stringify(results));
-        });
-      }), Promise.resolve()).then(waitForCancellation);
-    }
-    return readSnapshot().then(snapshot => {
-      const orders = snapshot.orders;
-      if (${JSON.stringify(operation)} === 'orders') {
-        if (!orders.length || orders.some(order => !ids.includes(String(order.orderId))
-          || order.side !== (sign === 1n ? 'buy' : 'sell'))) throw new Error('No matching exact accepted UI order remains open.');
-        return {receipt, orders};
-      }
-      if (${JSON.stringify(operation)} === 'cancel' && !protectionKeys.length) {
-        return cancelOwned(orders).then(({results}) => ({receipt, results, remainingOwnedOrders: 0}));
-      }
-      if (!snapshot.positions.length && ${JSON.stringify(operation)} === 'close' && !orders.length) return {receipt, closed: false, alreadyAbsent: true};
-      if (snapshot.positions.length !== 1) throw new Error('Receipt position is absent or ambiguous.');
-      const position = snapshot.positions[0];
-      if (protectionKeys.length && orders.some(order => !protectionIds.includes(String(order.orderId)))) throw new Error('Extra parent orders prevent protected position assertion or cleanup.');
-      return verifyLineage(position).then(fills => {
-        const protectionPresent = protectionIds.some(id => orders.some(order => String(order.orderId) === id));
-        verifyProtection(position, orders, ${JSON.stringify(operation)} === 'positions' || protectionPresent);
-        if (${JSON.stringify(operation)} === 'positions') return {receipt, position, fills};
-        if (orders.some(order => !protectionIds.includes(String(order.orderId)))) throw new Error('Parent order remainder prevents owned position cleanup.');
-        return cancelOwned(orders, position).then(({after, results}) => {
-          if (${JSON.stringify(operation)} === 'cancel') return {receipt, results, remainingOwnedOrders: 0};
-          const unchanged = after.positions[0];
-          return verifyLineage(unchanged).then(readSnapshot).then(beforeClose => {
-            if (beforeClose.positions.length !== 1 || beforeClose.orders.length
-              || beforeClose.positions[0].size !== unchanged.size || beforeClose.positions[0].entryPrice !== unchanged.entryPrice
-              || beforeClose.positions[0].leverage?.value !== unchanged.leverage.value) throw new Error('Owned position changed before close.');
-            verifyProtection(beforeClose.positions[0], beforeClose.orders, false);
-            if (Date.now() >= ${deadline}) throw new Error('Receipt cleanup deadline elapsed before close.');
-            assertIdentity();
-            return controller.closePosition({symbol: market, size: String(sign === 1n ? unchanged.size : String(unchanged.size).slice(1)), orderType: 'market', providerId: 'hyperliquid', position: unchanged}).then(closeResult => {
-              if (closeResult?.success !== true || !closeResult.orderId) throw new Error('Receipt-owned close has no accepted result: ' + JSON.stringify(closeResult));
-              function waitForClose() {
-                return readSnapshot().then(final => {
-                  if (!final.positions.length && !final.orders.length) return {receipt, results, closeResult, closed: true};
-                  if (Date.now() >= ${deadline}) throw new Error('Receipt-owned close is not independently confirmed.');
-                  return new Promise(resolve => setTimeout(resolve, 250)).then(waitForClose);
-                });
-              }
-              return waitForClose();
-            });
-          });
-        });
-      });
-    });
-  })()`]);
-  return { action: input.action, ...result, mutation };
-}

package/library/actions/mobile/perps/read_order_input.mjs

@@ -1,33 +0,0 @@
-// Freeze the visible unsigned order inputs and refuse a repeated or unobservable submission.
-import { bridgeCommand, runAdapter } from '../platform/bridge.mjs';
-import { readOrderInputState } from './order-input-state.mjs';
-import { observeNativeUi } from '../platform/observe-ui.mjs';
-
-runAdapter(async (input) => {
-  const confirmation = await readOrderInputState(input, input.node?.identity);
-  const { identity, form } = confirmation;
-  const observation = await observeNativeUi({ refs: ['ui.visible'], node: input.node }, input.context);
-  const visible = observation.observations?.['ui.visible'];
-  const payRows = visible?.items?.filter((item) => item.test_id === 'pay-with') ?? [];
-  if (!visible || visible.truncated || payRows.length !== 1 || payRows[0].label !== 'Pay with, Perps balance') {
-    throw new Error('Receipt proof requires the visible Perps balance payment source; funding is not permitted.');
-  }
-  if (identity.provider !== 'hyperliquid' || identity.isTestnet !== true
-    || form.leverage !== 1 || !(Number(form.amount) > 0 && Number(form.amount) <= 20)
-    || !['market', 'limit'].includes(form.orderType)) {
-    throw new Error('Mobile receipt proof requires Hyperliquid testnet, 1x and at most $20 on a market or limit order.');
-  }
-  if (Number(form.amount) !== Number(input.node.amount) || form.leverage !== Number(input.node.leverage)) {
-    throw new Error('Committed Mobile order inputs differ from the requested amount or leverage.');
-  }
-  const protection = input.node.protection ?? 'none';
-  for (const [field, required] of [['takeProfitPrice', ['take_profit', 'both'].includes(protection)], ['stopLossPrice', ['stop_loss', 'both'].includes(protection)]]) {
-    if (required ? !(Number(form[field]) > 0) : form[field] !== null) throw new Error(`Committed Mobile ${field} does not match requested protection.`);
-  }
-  const prior = await bridgeCommand(input, ['eval', `(() => {
-    if (typeof __AGENTIC__.readPerpsOrderReceipts !== 'function') throw new Error('Mobile UI receipt observer is unavailable.');
-    return __AGENTIC__.readPerpsOrderReceipts(${JSON.stringify(identity.approvalId)});
-  })()`]);
-  if (!Array.isArray(prior) || prior.length) throw new Error('This unsigned confirmation already has a submission attempt; do not submit it again.');
-  return { action: input.action, confirmation, submitted: false };
-});

package/library/actions/mobile/perps/read_order_receipt.mjs

@@ -1,5 +0,0 @@
-// Observe the actual result of one UI submission without dispatching an order.
-import { runAdapter } from '../platform/bridge.mjs';
-import { readOrderReceipt } from './order-receipt.mjs';
-
-runAdapter(readOrderReceipt);