@deeeed/metamask-harness 0.80.0 → 0.81.0

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

@@ -3,6 +3,8 @@
 
 import { pathToFileURL } from 'node:url';
 import { createHash } from 'node:crypto';
+import { readFile, writeFile } from 'node:fs/promises';
+import path from 'node:path';
 import { dataTestId, marketSymbol, normalizeMarketSymbol, runAdapter, withExtensionPage } from '../platform/cdp.mjs';
 import {
   assertTrustedExternalMutationTarget,
@@ -14,11 +16,19 @@ import {
   trustedExternalMutationBudget,
   trustedExternalMutationFundingRequirement,
   trustedExternalMutationIdentity,
+  inFixturePolicyLane,
+  withFixturePolicyContext,
   withExternalMutationRecovery,
 } from './mutation-receipt.mjs';
 import { readSnapshot } from './read_snapshot.mjs';
 import { readPerpsRuntimeStateExpression } from './state.mjs';
 import { readWalletStateExpression } from '../wallet/state.mjs';
+import {
+  assertFlatBeforeRoundTrip,
+  assertHouseLimitPosition,
+  closeImmediatelyRequested,
+  requireHouseNotional,
+} from '../../shared/perps/order-policy.mjs';
 import {
   orderIdentityMatches,
   parseOrderCard,
@@ -44,6 +54,10 @@ function sideForItem(item) {
   const side = String(item?.side ?? item?.direction ?? '').toLowerCase();
   if (side === 'buy' || side === 'b') return 'long';
   if (side === 'sell' || side === 'a' || side === 's') return 'short';
+  if (side) return side;
+  // Positions carry no side, only a signed size (long > 0, short < 0).
+  const size = Number(item?.size ?? item?.szi);
+  if (Number.isFinite(size) && size !== 0) return size > 0 ? 'long' : 'short';
   return side;
 }
 
@@ -222,6 +236,9 @@ export async function closePositions(input) {
 }
 
 async function closeOrderThroughBackground(input, page, timeoutMs) {
+  ({ input } = await withFixturePolicyContext(input, page, {
+    operations: [{ operation: 'perps-cancel-order', amount: String(input.node?.amount ?? '') }],
+  }));
   await requirePerpsTradingContext(input, page);
   const symbol = marketSymbol(input);
   const side = String(input.node?.side ?? '').toLowerCase();
@@ -414,6 +431,9 @@ export async function closeOrders(input) {
         partialCloseAmount: null,
         roundingToleranceBaseUnits,
       };
+      ({ input } = await withFixturePolicyContext(input, page, {
+        operations: [{ operation: 'perps-cancel-order', amount }],
+      }));
       const priorLookupIdentity = trustedExternalMutationIdentity(input, page, operation);
       const priorPlace = await readPriorMutationReceipt(
         input,
@@ -791,8 +811,24 @@ async function observeBackgroundPlace(page, expected, baselineIds, timeoutMs) {
   throw new Error('Exact background Perps placement postcondition was not proven.');
 }
 
+// Page source that returns { changed: true } unless the selected account and the
+// Perps network are still the ones the order rule allowed. It runs in the same
+// evaluation as the request it guards, with no await between the comparison and
+// the request. The state reads themselves are awaited, so a switch inside that
+// millisecond window can't be ruled out from the page; anything earlier is.
+function boundContextGuard(bound) {
+  if (!bound) return '';
+  return `
+    const __wallet = await (${readWalletStateExpression()});
+    const __perps = await (${readPerpsRuntimeStateExpression()});
+    const __address = String(__wallet?.selectedAccount?.address ?? '').toLowerCase();
+    const __network = __perps?.networkKnown ? (__perps.isTestnet ? 'testnet' : 'mainnet') : null;
+    if (__address !== ${JSON.stringify(bound.address)} || __network !== ${JSON.stringify(bound.network)}) return { changed: true };`;
+}
+
 async function dispatchBackgroundPlace(page, {
   amount,
+  bound = null,
   isBuy,
   leverage,
   limitPrice,
@@ -804,6 +840,7 @@ async function dispatchBackgroundPlace(page, {
   return page.evaluate(`(async () => {
     const request = globalThis.stateHooks?.submitRequestToBackground;
     if (typeof request !== 'function') throw new Error('stateHooks.submitRequestToBackground is unavailable; cannot place live Perps order.');
+    ${boundContextGuard(bound)}
     const currentPrice = Number(${JSON.stringify(resolvedPrice)});
     const usdAmount = ${JSON.stringify(amount)};
     const leverage = ${JSON.stringify(leverage)};
@@ -1167,6 +1204,8 @@ async function observeExactVisibleOrderResult(page, expected, receipt, timeoutMs
 
 async function placeOrderThroughBackground(input, page, {
   amount,
+  bound = null,
+  onDispatch = () => {},
   expected,
   identity,
   isBuy,
@@ -1224,8 +1263,10 @@ async function placeOrderThroughBackground(input, page, {
       } catch (error) {
         throw externalMutationNotDispatched(error instanceof Error ? error.message : String(error));
       }
-      return dispatchBackgroundPlace(page, {
+      onDispatch();
+      const accepted = await dispatchBackgroundPlace(page, {
         amount,
+        bound,
         isBuy,
         leverage,
         limitPrice,
@@ -1234,6 +1275,10 @@ async function placeOrderThroughBackground(input, page, {
         resolvedPrice,
         symbol,
       });
+      if (accepted?.changed) {
+        throw externalMutationNotDispatched('the selected account or Perps network changed after the order rule allowed it');
+      }
+      return accepted;
     },
     observe: async () => observeBackgroundPlace(
       page,
@@ -1285,6 +1330,16 @@ export async function requirePerpsTradingContext(input, page) {
       throw new Error('Source-dev funded mutation selected account changed after its visible identity proof.');
     }
   }
+  if (trusted?.proofLane === 'fixture-policy') {
+    // The order rule allowed the account selected when the context was completed;
+    // dispatch only from that same account.
+    const wallet = await page.evaluate(readWalletStateExpression());
+    const address = String(wallet?.selectedAccount?.address ?? '').toLowerCase();
+    if (!/^0x[0-9a-f]{40}$/u.test(address)
+      || createHash('sha256').update(address).digest('hex') !== trusted.selectedIdentitySha256) {
+      throw new Error('Perps mutation selected account changed after the order rule allowed it.');
+    }
+  }
   if (actualProvider !== provider || actualNetwork !== network) {
     throw new Error(
       `Perps mutation expected ${provider}/${network}, got ${actualProvider || 'unknown'}/${actualNetwork}.`,
@@ -1565,7 +1620,7 @@ export async function placeOrder(input) {
   if (fromCurrentForm && (positionMode !== 'new' || submitAttempts !== 1)) {
     throw new Error('Prepared-form placement requires position_mode=new and submit_attempts=1.');
   }
-  const roundingToleranceBaseUnits = String(input.node?.identity_rounding_tolerance_base_units ?? '10000');
+  let roundingToleranceBaseUnits = String(input.node?.identity_rounding_tolerance_base_units ?? '10000');
   if (!/^(?:0|[1-9][0-9]{0,6})$/u.test(roundingToleranceBaseUnits)
     || BigInt(roundingToleranceBaseUnits) > 1_000_000n) {
     throw new Error(`${input.action} identity_rounding_tolerance_base_units must be 0..1000000.`);
@@ -1581,7 +1636,55 @@ export async function placeOrder(input) {
   if (!Number.isInteger(submitAttempts) || submitAttempts < 1 || submitAttempts > 2) {
     throw new Error(`${input.action} submit_attempts must be 1 or 2.`);
   }
-  return withExtensionPage(input, async (page) => {
+  const closeImmediately = closeImmediatelyRequested(input.node);
+  if (closeImmediately && !inFixturePolicyLane(input)) {
+    throw new Error('close_immediately runs without funding files; a funded run closes through its own authorized close node.');
+  }
+  if (closeImmediately && (positionMode !== 'new' || fromCurrentForm)) {
+    throw new Error('close_immediately needs position_mode=new and a background placement.');
+  }
+  // Set once the market is proven flat in this action: only then is a position
+  // in it after a failed placement this order's own.
+  // Set at the actual dispatch (or by a prior receipt that may have dispatched):
+  // only then can a failure have left a position, so only then may cleanup run.
+  let dispatchMayHaveHappened = false;
+  let houseNotional = null;
+  // The account and network the order rule allowed, rechecked before any close.
+  let bound = null;
+  const place = () => withExtensionPage(input, async (page) => {
+    const lane = await withFixturePolicyContext(input, page, {
+      operations: [
+        { operation: orderType === 'limit' ? 'perps-limit-order' : 'perps-market-order', amount, order: true },
+      ],
+      order: { amount, leverage, orderType, closeImmediately },
+    });
+    input = lane.input;
+    if (lane.network) {
+      const wallet = await page.evaluate(readWalletStateExpression());
+      const address = String(wallet?.selectedAccount?.address ?? '').toLowerCase();
+      if (createHash('sha256').update(address).digest('hex') !== input.context?.trustedMutation?.selectedIdentitySha256) {
+        throw new Error('Perps mutation selected account changed after the order rule allowed it.');
+      }
+      bound = { address, network: lane.network };
+    }
+    if (closeImmediately) {
+      if (input.node?.identity_rounding_tolerance_base_units == null) {
+        // The fill's margin differs from the request by up to one size step plus
+        // slippage, more than the default cent: check it fits the $1 cap.
+        const price = await readCurrentMarketPrice(page, symbol, input.node?.current_price ?? input.node?.currentPrice);
+        const szDecimals = await readSizeDecimals(page, symbol);
+        const slippage = Number(input.node?.max_slippage_bps ?? input.node?.maxSlippageBps ?? 300) / 10_000;
+        const margin = Number(amount);
+        if (szDecimals == null) throw new Error(`close_immediately cannot read the ${symbol} size decimals; not dispatched.`);
+        const tolerance = Math.ceil(((10 ** -Number(szDecimals)) * Number(price) / leverage + margin * slippage) * 1_000_000) + 10_000;
+        if (!Number.isInteger(Number(szDecimals)) || !Number.isFinite(tolerance) || tolerance > 1_000_000) {
+          throw new Error(`close_immediately cannot prove a ${symbol} fill within $1 (size step or slippage too coarse); pass identity_rounding_tolerance_base_units or choose another market.`);
+        }
+        // The receipt identity must not move with the price, so a resume finds it:
+        // use the fixed $1 cap the estimate fits in.
+        roundingToleranceBaseUnits = '1000000';
+      }
+    }
     const identity = trustedExternalMutationIdentity(input, page, {
       operation: orderType === 'limit' ? 'perps-limit-order' : 'perps-market-order',
       provider: input.node?.provider,
@@ -1621,6 +1724,18 @@ export async function placeOrder(input) {
     const hasBackgroundRequest = await page.evaluate(
       `typeof globalThis.stateHooks?.submitRequestToBackground === 'function'`,
     );
+    if (closeImmediately) {
+      // The close goes through the background request, so the order must too.
+      if (!hasBackgroundRequest) throw new Error('close_immediately needs the background Perps request; it is unavailable.');
+      const receipt = await readExternalMutationReceipt(input, identity);
+      // Only a receipt that may have dispatched owns what is open in the market now.
+      const owned = ['succeeded', 'outcome-unknown'].includes(receipt?.record?.state);
+      if (owned) dispatchMayHaveHappened = true;
+      if (!owned) {
+        const book = await readBoundBook(page, bound);
+        assertFlatBeforeRoundTrip(book.positions, symbol, symbolForItem, book.orders);
+      }
+    }
     if (hasBackgroundRequest && !fromCurrentForm) {
       await requirePerpsTradingContext(input, page);
       const resolvedPrice = await readCurrentMarketPrice(
@@ -1628,11 +1743,24 @@ export async function placeOrder(input) {
         symbol,
         input.node?.current_price ?? input.node?.currentPrice,
       );
+      houseNotional = requireHouseNotional({
+        network: lane.network,
+        symbol,
+        amount,
+        leverage,
+        price: resolvedPrice,
+        szDecimals: lane.network === 'mainnet' ? await readSizeDecimals(page, symbol) : null,
+        maxSlippageBps: Number(input.node?.max_slippage_bps ?? input.node?.maxSlippageBps ?? 300),
+      });
       const backgroundLimitPrice = orderType === 'limit'
         ? resolveLimitPrice(input, isBuy, resolvedPrice)
         : null;
       return placeOrderThroughBackground(input, page, {
         amount,
+        bound,
+        onDispatch: () => {
+          dispatchMayHaveHappened = true;
+        },
         expected: {
           ...expectedVisibleIdentity,
           limitPriceBaseUnits: backgroundLimitPrice == null ? null : parseUsdBaseUnits(backgroundLimitPrice),
@@ -1952,6 +2080,195 @@ export async function placeOrder(input) {
     }
     throw new Error('Visible Perps placement did not return a terminal result.');
   });
+  if (!closeImmediately) return place();
+  // A resumed order checks its close record before anything else: it never
+  // re-observes, cleans up or closes after its round trip has run.
+  const marker = closeMarkerPath(input);
+  const recorded = await readCloseMarker(marker);
+  if (recorded?.state === 'closed') {
+    if (recorded.error) throw new Error(recorded.error);
+    return { ...recorded.placed, roundTrip: { ...recorded.roundTrip, resumed: true } };
+  }
+  if (recorded) {
+    throw new Error(`close_immediately: an earlier close of ${symbol} may have run (record ${recorded.state}); check ${symbol} and rerun with a fresh artifacts dir.`);
+  }
+  let placed;
+  try {
+    placed = await place();
+  } catch (error) {
+    if (!dispatchMayHaveHappened || error?.knownNotDispatched) throw error;
+    throw await closeAfterFailedPlacement(input, symbol, error, bound, marker);
+  }
+  placed = { ...placed, ...(houseNotional ? { houseNotional } : {}) };
+  return { ...placed, roundTrip: await closeOpenedPosition(input, { symbol, bound, marker, placed }) };
+}
+
+// The flat-market baseline: the bound account's positions and resting orders,
+// read in one evaluation with the context guard before, between and after the
+// reads, so a switch to another account's book and back can't pass as flat.
+async function readBoundBook(page, bound) {
+  const book = await page.evaluate(`(async () => {
+    const request = globalThis.stateHooks?.submitRequestToBackground;
+    if (typeof request !== 'function') return { unavailable: true };
+    const guard = async () => { ${boundContextGuard(bound)} return null; };
+    if (await guard()) return { changed: true };
+    const positions = await request('perpsGetPositions', []);
+    if (await guard()) return { changed: true };
+    const orders = await request('perpsGetOpenOrders', []);
+    if (await guard()) return { changed: true };
+    return { positions, orders };
+  })()`);
+  if (book?.changed) {
+    throw Object.assign(
+      new Error('Perps order not dispatched: the selected account or network changed while the market was checked flat.'),
+      { knownNotDispatched: true },
+    );
+  }
+  if (!Array.isArray(book?.positions) || !Array.isArray(book?.orders)) {
+    throw new Error('Background Perps API unavailable; cannot check the market is flat.');
+  }
+  return book;
+}
+
+async function readSizeDecimals(page, symbol) {
+  const markets = await page.evaluate(
+    `globalThis.stateHooks.submitRequestToBackground('perpsGetMarkets', [{ symbols: [${JSON.stringify(symbol)}] }])`,
+  );
+  const market = (Array.isArray(markets) ? markets : []).find((item) => normalizeMarketSymbol(item?.name ?? '') === symbol);
+  return market?.szDecimals ?? null;
+}
+
+// close_immediately started from a flat market (proven in the same action), so a
+// position in that market afterwards is this order's own. It is closed with the
+// product's own background close request and the market is proven flat again.
+// Every read and the close itself run guarded: if the selected account or the
+// Perps network is no longer the bound one, nothing is read as ours or closed.
+export async function closeOwnPosition(page, symbol, { houseLimits = false, bound = null } = {}) {
+  const read = () => page.evaluate(`(async () => {
+    ${boundContextGuard(bound)}
+    const positions = await globalThis.stateHooks.submitRequestToBackground('perpsGetPositions', []);
+    return { positions: Array.isArray(positions) ? positions : null };
+  })()`);
+  const own = async () => {
+    const state = await read();
+    if (state?.changed) return { changed: true };
+    if (!state?.positions) throw new Error('Background Perps API unavailable.');
+    return { position: state.positions.find((position) => symbolForItem(position) === symbol) ?? null };
+  };
+  const before = await own();
+  if (before.changed) return { changed: true, closed: false };
+  if (!before.position) return { wasOpen: false, closed: true };
+  let limitError = null;
+  if (houseLimits) {
+    try {
+      assertHouseLimitPosition(before.position, symbol);
+    } catch (error) {
+      limitError = error;
+    }
+  }
+  const result = await page.evaluate(`(async () => {
+    ${boundContextGuard(bound)}
+    return globalThis.stateHooks.submitRequestToBackground('perpsClosePosition', [{ symbol: ${JSON.stringify(symbol)}, orderType: 'market' }]);
+  })()`);
+  if (result?.changed) return { changed: true, closed: false };
+  const deadline = Date.now() + 30_000;
+  let closed = false;
+  while (Date.now() < deadline) {
+    const after = await own();
+    if (after.changed) return { changed: true, closed: false, closeSent: true };
+    if (!after.position) {
+      closed = true;
+      break;
+    }
+    await sleep(1_000);
+  }
+  return {
+    wasOpen: true,
+    closed,
+    limitError,
+    opened: { symbol, size: before.position.size ?? null, leverage: before.position.leverage ?? null },
+    result,
+  };
+}
+
+// The run's close record, next to its execution ledger: `closing` before the
+// close is sent, `closed` after. A resume reads it first, so it never closes a
+// position opened in that market later, and a crash between the two leaves a
+// record that refuses to guess.
+function closeMarkerPath(input) {
+  const trusted = input.context?.trustedMutation;
+  const root = trusted?.executionLedgerRoot;
+  const nodeId = String(input.context?.nodeId ?? '');
+  if (typeof root !== 'string' || !path.isAbsolute(root) || !/^[a-f0-9]{64}$/u.test(String(trusted?.runId ?? '')) || !nodeId) {
+    throw new Error('close_immediately needs the run-owned execution ledger.');
+  }
+  // Same id as the receipt identity's executionId.
+  const executionId = createHash('sha256').update(`${trusted.runId}\0${nodeId}`).digest('hex');
+  return path.join(root, `${executionId}.close.json`);
+}
+
+async function readCloseMarker(marker) {
+  return readFile(marker, 'utf8').then(JSON.parse, (error) => {
+    if (error?.code === 'ENOENT') return null;
+    throw error;
+  });
+}
+
+async function writeCloseMarker(marker, record, { exclusive = false } = {}) {
+  await writeFile(marker, `${JSON.stringify({ schemaVersion: 1, kind: 'perps-immediate-close', ...record })}\n`, {
+    mode: 0o600,
+    flag: exclusive ? 'wx' : 'w',
+  });
+}
+
+async function closeAfterFailedPlacement(input, symbol, error, bound, marker) {
+  const message = error instanceof Error ? error.message : String(error);
+  let outcome;
+  try {
+    await writeCloseMarker(marker, { state: 'closing', market: symbol }, { exclusive: true });
+    // withExtensionPage merges the callback's result into its runtime fields.
+    const { wasOpen, closed, changed } = await withExtensionPage(input, (page) => closeOwnPosition(page, symbol, { bound }));
+    outcome = changed
+      ? `the selected account or network changed, so nothing was closed; check ${symbol} on the original account now`
+      : !wasOpen
+        ? `no ${symbol} position is open`
+        : closed
+          ? `the ${symbol} position it opened was closed`
+          : `the ${symbol} position is STILL OPEN after a close request; close it now`;
+    // Nothing open, or closed now: the run is settled and a resume rethrows the failure.
+    if (!changed && (closed || !wasOpen)) {
+      await writeCloseMarker(marker, { state: 'closed', market: symbol, error: `${message} close_immediately: ${outcome}.` });
+    }
+  } catch (closeError) {
+    outcome = `the ${symbol} position could not be checked or closed (${closeError instanceof Error ? closeError.message : String(closeError)}); check it now`;
+  }
+  return new Error(`${message} close_immediately: ${outcome}.`);
+}
+
+async function closeOpenedPosition(input, { symbol, bound, marker, placed }) {
+  await writeCloseMarker(marker, { state: 'closing', market: symbol }, { exclusive: true });
+  const mainnet = bound?.network === 'mainnet';
+  const { wasOpen, closed, changed, limitError, opened, result } = await withExtensionPage(
+    input,
+    (page) => closeOwnPosition(page, symbol, { houseLimits: mainnet, bound }),
+  );
+  if (changed) {
+    throw new Error(`close_immediately did not finish closing ${symbol}: the selected account or network changed after the order. Check ${symbol} on the original account now and close it if it is open.`);
+  }
+  if (!wasOpen) throw new Error(`close_immediately could not find the ${symbol} position the order opened; check ${symbol} now.`);
+  if (!closed) {
+    throw new Error(`close_immediately could not close the ${symbol} position this order opened; it is still open. Close it now.`);
+  }
+  const roundTrip = { opened, closed: true, result, proofPath: 'background-close-request' };
+  await writeCloseMarker(marker, {
+    state: 'closed',
+    market: symbol,
+    placed,
+    roundTrip,
+    ...(limitError ? { error: limitError.message } : {}),
+  });
+  if (limitError) throw limitError;
+  return roundTrip;
 }
 
 export async function ensurePositions(input) {

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

@@ -1,11 +1,13 @@
 // Place a Perps order and return visible-control evidence or assert the resulting order or position state.
+// With close_immediately the order's position is already closed again, so the market must be flat.
 import { runAdapter } from '../platform/cdp.mjs';
+import { closeImmediatelyRequested } from '../../shared/perps/order-policy.mjs';
 import { assertOrders, assertPositions, placeOrder } from './perps.mjs';
 runAdapter(async (input) => {
   const order = await placeOrder(input);
   if (order.proofPath === 'visible-product-controls') return order;
   const assertion = order.orderType === 'limit'
     ? await assertOrders(input, true)
-    : await assertPositions(input, true);
+    : await assertPositions(input, !closeImmediatelyRequested(input.node));
   return { ...assertion, submitted: order.submitted === true, order };
 });

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

@@ -7,6 +7,7 @@ import {
   readExternalMutationReceipt,
   runGuardedExternalMutation,
   trustedExternalMutationIdentity,
+  withFixturePolicyContext,
   withExternalMutationRecovery,
 } from './mutation-receipt.mjs';
 import { requireCurrentVisibleFundingBalance, requirePerpsTradingContext } from './perps.mjs';
@@ -165,6 +166,9 @@ export async function updatePositionTpsl(input) {
   if (input.node?.confirm_live !== true) {
     throw new Error('metamask.perps.update_position_tpsl requires confirm_live=true for live submission.');
   }
+  ({ input } = await withFixturePolicyContext(input, page, {
+    operations: [{ operation: 'perps-tpsl-update', amount: fundingAmount }],
+  }));
   const identity = trustedExternalMutationIdentity(input, page, {
     operation: 'perps-tpsl-update',
     provider: input.node?.provider,

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

@@ -195,6 +195,55 @@ function captureHelperPath() {
   return process.env.CAPTURE_HELPER_PATH || 'capture-helper';
 }
 
+// A snapshot helper that outlived its harness process (a crashed run, or a
+// timeout from before timed-out helpers were killed) is reparented to launchd
+// and makes later snapshots hang. Kill those, and what they started (the npm
+// wrapper `node …/capture-helper snapshot` runs the native binary as its
+// child), before starting a new one. Only this user's processes are touched.
+async function reapOrphanedCaptureHelpers(context) {
+  const ps = await runProcess('ps', ['-axo', 'pid=,ppid=,uid=,command='], {
+    cwd: context.projectRoot,
+    env: process.env,
+    timeoutMs: 5000,
+  });
+  if (ps.exitCode !== 0) throw new Error(`ps failed while reaping capture-helper: ${ps.stderr}`);
+  const escape = (value) => value.replace(/[.*+?^${}()|[\]\\]/gu, '\\$&');
+  const configured = captureHelperPath();
+  // The executable (or the script node runs) and its subcommand, never an
+  // argument. The configured path may contain spaces; other install paths may not.
+  const dir = configured.includes('/') ? `${escape(path.dirname(configured))}/|` : '';
+  const snapshotHelper = new RegExp(
+    `^(?:(?:\\S*/)?node\\s+)?(?:${dir}\\S*/)?${escape(path.basename(configured))} snapshot(?:\\s|$)`,
+    'u',
+  );
+  const processes = ps.stdout.split('\n').flatMap((line) => {
+    const match = /^\s*(\d+)\s+(\d+)\s+(\d+)\s+(.*)$/u.exec(line);
+    return match && Number(match[3]) === process.getuid()
+      ? [{ pid: Number(match[1]), ppid: Number(match[2]), command: match[4] }]
+      : [];
+  });
+  const doomed = new Set(
+    processes.filter((entry) => entry.ppid === 1 && snapshotHelper.test(entry.command)).map((entry) => entry.pid),
+  );
+  for (let grew = true; grew;) {
+    grew = false;
+    for (const entry of processes) {
+      if (doomed.has(entry.ppid) && !doomed.has(entry.pid)) {
+        doomed.add(entry.pid);
+        grew = true;
+      }
+    }
+  }
+  for (const pid of doomed) {
+    try {
+      process.kill(pid, 'SIGKILL');
+    } catch (error) {
+      // It exited between ps and kill: already reaped.
+      if (error?.code !== 'ESRCH') throw error;
+    }
+  }
+}
+
 function parsePositivePid(value) {
   const pid = Number(String(value ?? '').trim());
   return Number.isInteger(pid) && pid > 0 ? pid : null;
@@ -280,7 +329,7 @@ async function captureCdpSnapshot(page, context, relPath, metadata, captureHelpe
       provider: 'cdp',
       mode: 'Page.captureScreenshot',
       fullPage: metadata?.fullPage === true,
-      ...(captureHelperError ? { fallbackFrom: 'capture-helper', captureHelperError } : {}),
+      ...(captureHelperError ? { fallbackFrom: 'capture-helper', fallbackReason: captureHelperError, captureHelperError } : {}),
     },
   };
 }
@@ -318,6 +367,7 @@ export async function captureHelperSnapshot(page, context, relPath, metadata) {
         'native snapshot skipped while full-run recording owns the browser window',
       );
     } else {
+      await reapOrphanedCaptureHelpers(context);
       const result = await runProcess(
         captureHelperPath(),
         ['snapshot', '--pid', String(pid), '--output', destination.stagedPath],
@@ -413,17 +463,31 @@ async function execNodeScript(script, args, options) {
 
 function runProcess(command, args, options) {
   return new Promise((resolve, reject) => {
+    // A bounded command runs in its own process group so a timeout kills
+    // everything it started: the npm capture-helper wrapper runs the native
+    // binary as a child, which would otherwise keep our pipes open.
     const child = spawn(command, args, {
       cwd: options.cwd,
       env: options.env || process.env,
       stdio: ['ignore', 'pipe', 'pipe'],
+      detached: Boolean(options.timeoutMs),
     });
     let timer = null;
     let stdout = '';
     let stderr = '';
     if (options.timeoutMs) {
       timer = setTimeout(() => {
-        child.kill('SIGTERM');
+        timer = null;
+        // SIGKILL: capture-helper can ignore SIGTERM while it holds a window capture.
+        try {
+          process.kill(-child.pid, 'SIGKILL');
+        } catch (error) {
+          // ESRCH: the whole group already exited; only the pipe close is pending.
+          if (error?.code !== 'ESRCH') {
+            reject(error);
+            return;
+          }
+        }
         reject(new Error(`Command timed out after ${options.timeoutMs}ms: ${command} ${args.join(' ')}`));
       }, options.timeoutMs);
     }
@@ -650,7 +714,11 @@ export async function openExtensionHomePage(port, extensionId) {
 
 async function ensureExtensionTarget(input, port) {
   let launch = null;
-  const trustedTargetId = input.context?.trustedMutation?.cdpTargetId ?? null;
+  // A fixture-policy run (F21) has no target until its first mutation pins the
+  // live one; every later page in that action uses it.
+  const trusted = input.context?.trustedMutation;
+  const unpinnedPolicyLane = trusted?.proofLane === 'fixture-policy' && trusted.cdpTargetId === '';
+  const trustedTargetId = unpinnedPolicyLane ? null : trusted?.cdpTargetId ?? null;
   if (trustedTargetId !== null && !/^[A-Za-z0-9._:-]{1,128}$/u.test(String(trustedTargetId))) {
     throw new Error('Funded Extension action has no valid trusted CDP target id.');
   }