@farmslot/adapter-web 0.6.0 → 0.6.2

package/CHANGELOG.md

@@ -6,6 +6,16 @@ All notable changes to `@farmslot/adapter-web` are tracked here.
 
 - Active-development baseline; add user-facing changes here before release or package publication.
 
+## 0.6.2 - 2026-10-08
+
+- Fix: `launch-browser` no longer builds its `node -e` CDP request from the port, path or target id. They reach the child as argv, `cdpHttp` takes only an integer port from 1 to 65535 and the paths it uses (`/json/list`, `/json/version`, `/json/close/<id>`), and closing duplicate home tabs skips, with a warning, a target id from `/json/list` that is not a CDP id (letters, digits, `-`). Before, a hostile or substituted local CDP endpoint could run code in that child through a crafted target id. `cdpHttp` and `pruneExtraHomeTabs` are exported for tests. ([#859](https://github.com/deeeed/farmslot/pull/859))
+- Publish with adapter-sdk 0.7.1 and recipe-runner 0.27.0 so consumers share one adapter-sdk and one recipe-runner copy.
+
+## 0.6.1 - 2026-10-08
+
+- `web-dapp` refuses a headful launch while the macOS login session is locked (`SESSION_LOCKED`, with the unlock step), before starting, reusing or stopping a browser, as mm-harness does since its #363 (0.6.0 shipped `web-dapp` without it). `macosSessionLocked()`, `parseSessionLocked()`, `SESSION_LOCKED_MESSAGE` and `SESSION_LOCKED_USER_ACTION` are exported.
+- Publish with adapter-sdk 0.7.1 and recipe-runner 0.27.0 so consumers share one adapter-sdk and one recipe-runner copy.
+
 ## 0.6.0 - 2026-10-08
 
 - Add `web-dapp` (`@farmslot/adapter-web/web-dapp`, an ESM subpath): `createWebDappAdapter({ id, signerModule, cli, hooks })` returns an `@farmslot/adapter-sdk` `PlatformAdapter` for a web app under test whose dev server the slot owns, moved from mm-harness's Web Terminal adapter. It runs a slot browser and wallet host with the injected strict wallet or a host-supplied extension signer, held to the testnet venue of the adapter that extends it. See the adapter-web reference for the signer module, venue policy and hooks.

package/README.md

@@ -114,6 +114,7 @@ const binding = createWalletRequestBinding({
 
 - **Venue policy.** The app's venue (the hosts a testnet run blocks and serves, the typed data to refuse, the start page) comes from the adapter that `extends: 'web-dapp'`: its policy module goes to `RECIPE_WEB_DAPP_POLICY` through `bindWebDappPolicy(adapter)`. Bare web-dapp has no policy and refuses to launch. `fencePolicy` and `assertPolicyDigest` hold the module and what it imports to the files the plugin digest covers.
 - **Served network.** A policy that declares served hosts (`venueHosts().served`) has the wallet host wait for the app to request one of them, which proves the dev server serves testnet. A policy for an app whose page makes no venue request of its own (such as test-dapp-multichain, whose wallet traffic goes through the extension) opts out explicitly: `venueHosts()` returns `served: []` with `servedCheck: 'not-applicable'`. The check is then skipped, and `networkEnforcement.served` in `browser.json` and the `network-enforcement` entry of the wallet request log say `not-applicable`. An empty `served` without that opt-out keeps the check, which fails closed, so a policy that computes its served hosts can't lose the check by finding none. Listing served hosts and opting out together is refused. Mainnet blocking is enforced either way.
+- **Locked session.** A headful launch refuses while the macOS login session is locked (`SESSION_LOCKED`), before starting, reusing or stopping a browser: macOS stops painting visible windows, so screenshots, video and UI actions would stall. `macosSessionLocked()` reads `ioreg` (3 s bound; `null` off macOS or when unknown). A headless launch never probes.
 - **Signers.** `signer=injected` needs nothing. `signer=extension` belongs to the host: a signer module exports `signers.extension` with `prepareProfile` (load the extension, seed the profile; returns `{ browserArgs, secrets, state }` and may carry an `afterBrowserStart` step; both steps get `trackSecret` for key-material files), `confirm` (required with `prepareProfile`: without it the wallet host would close the wallet's own windows) and `readinessChecks`. `signers.injected.identity` sets the EIP-6963 identity the injected strict wallet presents. The module path (`signerModule`, `--signer-module` or `RECIPE_WEB_DAPP_SIGNER_MODULE`) is the one source: readiness, launch, verify and the wallet host all load it, and `createWebDappAdapter` throws if given an in-process `signers` object. With no signer requested, the signer is `extension` when a module is configured and `injected` otherwise, so a host whose module exports only `injected` sets the signer explicitly (`--signer injected` or `TERMINAL_SIGNER=injected`).
 - **Hooks.** The action set, console capture, and network and performance observation are the host's; pass them as `hooks`. `diagnostics`, `readiness` and `harness` merge over the generic members.
 - **Leaves.** `webDappLeafPath('launch' | 'wallet-host' | 'inject' | 'verify' | 'stop' | 'cleanup')` names the CLI scripts.

package/dist/launch-browser.d.cts

@@ -116,3 +116,22 @@ export function homeTabsToClose(targets: unknown[], { extensionId, homePage, def
     id: string;
     url: string;
 }[];
+/**
+ * GET a CDP HTTP path on 127.0.0.1. Returns the body, or null when the port or
+ * path is not one the launcher uses, or the request fails.
+ * @param {number} port
+ * @param {string} pathname `/json/list`, `/json/version` or `/json/close/<target id>`
+ * @returns {string | null}
+ */
+export function cdpHttp(port: number, pathname: string): string | null;
+/**
+ * Close the extra `homePage` tabs and stray blank tabs the browser on `port` has.
+ * @param {number} port CDP port on 127.0.0.1.
+ * @param {string} extensionDir The unpacked extension, for its id.
+ * @param {{ homePage?: string, defaultTitle?: string }} options
+ * @returns {string[]} What could not be done, one line each; empty when all went well.
+ */
+export function pruneExtraHomeTabs(port: number, extensionDir: string, { homePage, defaultTitle }: {
+    homePage?: string;
+    defaultTitle?: string;
+}): string[];

package/dist/web-dapp/index.d.mts

@@ -121,3 +121,4 @@ export { assertPolicyDigest, fencePolicy, POLICY_DIGEST_ENV, PolicyFenceError }
 export { cdpListenerPids, ownedBrowserPids, OWNER_FLAG, OWNER_KINDS, ownerMarker, ownsProcess, pidAlive, portFree, stopConsoleCollector, stopWebDappBrowser, terminate } from "./lib/processes.mjs";
 export { assertLaunchNetwork, DEV_SERVER_PID_FILE, devServerTestnetDiagnostic, pythonFor, webDappReadiness } from "./lib/readiness.mjs";
 export { accountName, appOrigin, appPort, canonicalPath, cdpPort, DEFAULT_ACCOUNT, fixtureAccount, fixtureEntry, fixturePath, loadWalletFixture, readBrowserState, readJsonFile, resolveAccountAddress, resolveSigner, SIGNER_MODES, viemAccountFromEntry, webDappRuntimeDir, webDappRuntimePath, writePrivateJson } from "./lib/runtime.mjs";
+export { macosSessionLocked, parseSessionLocked, SESSION_LOCKED_MESSAGE, SESSION_LOCKED_USER_ACTION } from "./lib/session-lock.mjs";

package/dist/web-dapp/launch.d.mts

@@ -40,13 +40,14 @@ export function writePrivateFile(file: any, text: any): void;
 /**
  * @param {Record<string, any>} args the parsed launch flags (see `parseLaunchArgs`)
  * @param {NodeJS.ProcessEnv} [env]
- * @param {{ timeouts?: { browserStartMs: number, hostReadyMs: number } }} [options]
+ * @param {{ timeouts?: { browserStartMs: number, hostReadyMs: number }, sessionLocked?: () => boolean | null }} [options]
  */
-export function launchWebDappBrowser(args: Record<string, any>, env?: NodeJS.ProcessEnv, { timeouts }?: {
+export function launchWebDappBrowser(args: Record<string, any>, env?: NodeJS.ProcessEnv, { timeouts, sessionLocked }?: {
     timeouts?: {
         browserStartMs: number;
         hostReadyMs: number;
     };
+    sessionLocked?: () => boolean | null;
 }): Promise<any>;
 export const SPAWN: "spawn";
 export const LAUNCH_SERVICES: "launch-services";

package/dist/web-dapp/lib/session-lock.d.mts

@@ -0,0 +1,21 @@
+/**
+ * `ioreg -n Root -d1 -a` output: the lock flag of the on-console session in
+ * IOConsoleUsers (any session's when none is on console); false for a plist
+ * without it, null for anything else.
+ * @param {string} output
+ * @returns {boolean | null}
+ */
+export function parseSessionLocked(output: string): boolean | null;
+/**
+ * true or false on macOS; null when unknown (another platform, or ioreg failed
+ * or took longer than 3 s). Never throws.
+ * @param {{ platform?: string, spawnSync?: typeof nodeSpawnSync }} [deps]
+ * @returns {boolean | null}
+ */
+export function macosSessionLocked({ platform, spawnSync, }?: {
+    platform?: string;
+    spawnSync?: typeof nodeSpawnSync;
+}): boolean | null;
+export const SESSION_LOCKED_MESSAGE: "The macOS login session is locked, so the headful browser can't paint (screenshots, video and UI actions stall).";
+export const SESSION_LOCKED_USER_ACTION: string;
+import { spawnSync as nodeSpawnSync } from 'node:child_process';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@farmslot/adapter-web",
-  "version": "0.6.0",
+  "version": "0.6.2",
   "description": "Web platform adapter for Farmslot recipes: resolve and launch an isolated Chromium, own its CDP port, load unpacked extensions, and keep macOS focus.",
   "type": "commonjs",
   "exports": {

package/src/launch-browser.cjs

@@ -643,25 +643,39 @@ function extensionPageUrl(extensionDir, page) {
   return id ? `chrome-extension://${id}/${page}` : '';
 }
 
+// The CDP HTTP paths the launcher reads: the target list, the version, or one
+// target to close. CDP target ids are hex or UUIDs.
+const CDP_HTTP_PATH = /^\/json\/(?:list|version|close\/[A-Za-z0-9-]+)$/u;
+const CDP_TARGET_ID = /^[A-Za-z0-9-]+$/u;
+// A child node keeps cdpHttp synchronous. The port and path reach it as argv,
+// never as script source, so a path cannot change what it runs.
+const CDP_HTTP_SCRIPT = `
+const http = require('http');
+const [port, pathname] = process.argv.slice(1);
+http.get({ host: '127.0.0.1', port: Number(port), path: pathname }, (res) => {
+  let body = '';
+  res.on('data', (chunk) => { body += chunk; });
+  res.on('end', () => {
+    process.stdout.write(body);
+    process.exitCode = res.statusCode === 200 ? 0 : 1;
+  });
+}).on('error', () => process.exit(1));
+`;
+
+/**
+ * GET a CDP HTTP path on 127.0.0.1. Returns the body, or null when the port or
+ * path is not one the launcher uses, or the request fails.
+ * @param {number} port
+ * @param {string} pathname `/json/list`, `/json/version` or `/json/close/<target id>`
+ * @returns {string | null}
+ */
 function cdpHttp(port, pathname) {
-  const result = spawnSync(
-    process.execPath,
-    [
-      '-e',
-      `
-    const http = require('http');
-    http.get('http://127.0.0.1:${Number(port)}${pathname}', (res) => {
-      let body = '';
-      res.on('data', (chunk) => { body += chunk; });
-      res.on('end', () => {
-        process.stdout.write(body);
-        process.exitCode = res.statusCode === 200 ? 0 : 1;
-      });
-    }).on('error', () => process.exit(1));
-  `,
-    ],
-    { encoding: 'utf8', timeout: 4000 },
-  );
+  if (!Number.isInteger(port) || port < 1 || port > 65535) return null;
+  if (typeof pathname !== 'string' || !CDP_HTTP_PATH.test(pathname)) return null;
+  const result = spawnSync(process.execPath, ['-e', CDP_HTTP_SCRIPT, String(port), pathname], {
+    encoding: 'utf8',
+    timeout: 4000,
+  });
   if (result.status !== 0) return null;
   return result.stdout;
 }
@@ -710,6 +724,13 @@ function homeTabsToClose(targets, { extensionId, homePage, defaultTitle }) {
 // readiness converges home tabs again, so a pruning failure must not fail the
 // launch. Every failure is returned so the launch log says why a duplicate tab
 // survived instead of hiding it.
+/**
+ * Close the extra `homePage` tabs and stray blank tabs the browser on `port` has.
+ * @param {number} port CDP port on 127.0.0.1.
+ * @param {string} extensionDir The unpacked extension, for its id.
+ * @param {{ homePage?: string, defaultTitle?: string }} options
+ * @returns {string[]} What could not be done, one line each; empty when all went well.
+ */
 function pruneExtraHomeTabs(port, extensionDir, { homePage, defaultTitle }) {
   if (!homePage) return [];
   const extensionId = extensionIdFromExtensionDir(extensionDir);
@@ -725,10 +746,17 @@ function pruneExtraHomeTabs(port, extensionDir, { homePage, defaultTitle }) {
   if (!Array.isArray(targets)) return ['/json/list did not return a target list'];
   const problems = [];
   for (const target of homeTabsToClose(targets, { extensionId, homePage, defaultTitle })) {
-    if (cdpHttp(port, `/json/close/${target.id}`) === null)
+    // The id comes from the endpoint's own response: close only a CDP-shaped one.
+    if (!CDP_TARGET_ID.test(target.id)) {
+      problems.push(
+        `skipped target with an invalid id: ${JSON.stringify(target.id)} (${target.url})`,
+      );
+      continue;
+    }
+    if (cdpHttp(port, `/json/close/${encodeURIComponent(target.id)}`) === null)
       problems.push(`could not close ${target.url} (${target.id})`);
   }
   return problems;
 }
 
-module.exports = { launchBrowser, homeTabsToClose };
+module.exports = { launchBrowser, homeTabsToClose, cdpHttp, pruneExtraHomeTabs };

package/src/web-dapp/index.mjs

@@ -101,6 +101,12 @@ export {
   webDappRuntimePath,
   writePrivateJson,
 } from './lib/runtime.mjs';
+export {
+  macosSessionLocked,
+  parseSessionLocked,
+  SESSION_LOCKED_MESSAGE,
+  SESSION_LOCKED_USER_ACTION,
+} from './lib/session-lock.mjs';
 
 const LEAVES = Object.freeze(['launch', 'wallet-host', 'inject', 'verify', 'stop', 'cleanup']);
 

package/src/web-dapp/launch.mjs

@@ -73,6 +73,11 @@ import {
   webDappPolicy,
   webDappRuntimeDir,
 } from './lib/runtime.mjs';
+import {
+  macosSessionLocked,
+  SESSION_LOCKED_MESSAGE,
+  SESSION_LOCKED_USER_ACTION,
+} from './lib/session-lock.mjs';
 import { defaultSigner, loadSigners, SIGNER_MODULE_ENV } from './lib/signers.mjs';
 
 const SCRIPT_DIR = path.dirname(fileURLToPath(import.meta.url));
@@ -393,12 +398,12 @@ export const LAUNCH_TIMEOUTS = Object.freeze({ browserStartMs: 90000, hostReadyM
 /**
  * @param {Record<string, any>} args the parsed launch flags (see `parseLaunchArgs`)
  * @param {NodeJS.ProcessEnv} [env]
- * @param {{ timeouts?: { browserStartMs: number, hostReadyMs: number } }} [options]
+ * @param {{ timeouts?: { browserStartMs: number, hostReadyMs: number }, sessionLocked?: () => boolean | null }} [options]
  */
 export async function launchWebDappBrowser(
   args,
   env = process.env,
-  { timeouts = LAUNCH_TIMEOUTS } = {},
+  { timeouts = LAUNCH_TIMEOUTS, sessionLocked = macosSessionLocked } = {},
 ) {
   const policy = webDappPolicy(env);
   const signerModule = args['signer-module'] ?? env[SIGNER_MODULE_ENV];
@@ -474,6 +479,13 @@ export async function launchWebDappBrowser(
   const appOrigin = `http://localhost:${appPort}`;
   const headless = resolveHeadless({ headless: args.headless, headful: args.headful, env });
   const slowMoMs = resolveSlowMo({ flag: args['slow-mo'], env });
+  // A headful browser can't paint while the macOS session is locked: refuse
+  // before starting, reusing or stopping one.
+  if (!headless && sessionLocked() === true) {
+    throw new Error(
+      `SESSION_LOCKED: ${SESSION_LOCKED_MESSAGE}\nNext: ${SESSION_LOCKED_USER_ACTION}`,
+    );
+  }
 
   const { fixture } = await loadWalletFixture(target, env);
   const accountAddress = viemAccountFromEntry(fixtureEntry(fixture, args.account), target).address;

package/src/web-dapp/lib/session-lock.mjs

@@ -0,0 +1,56 @@
+// Whether the macOS login session is locked. macOS stops painting visible
+// windows while it is, so a headful browser's screenshots, video and UI actions
+// stall until their own timeouts. The launcher refuses a headful launch up front
+// instead (SESSION_LOCKED).
+
+import { spawnSync as nodeSpawnSync } from 'node:child_process';
+
+export const SESSION_LOCKED_MESSAGE =
+  "The macOS login session is locked, so the headful browser can't paint (screenshots, video and UI actions stall).";
+export const SESSION_LOCKED_USER_ACTION =
+  'Unlock the Mac and keep its login session unlocked while the run drives the browser, then rerun. ' +
+  'caffeinate keeps the Mac awake but does not unlock it.';
+
+const LOCKED = /<key>CGSSessionScreenIsLocked<\/key>\s*<true\/>/u;
+const ON_CONSOLE = /<key>kCGSSessionOnConsoleKey<\/key>\s*<true\/>/u;
+
+/**
+ * `ioreg -n Root -d1 -a` output: the lock flag of the on-console session in
+ * IOConsoleUsers (any session's when none is on console); false for a plist
+ * without it, null for anything else.
+ * @param {string} output
+ * @returns {boolean | null}
+ */
+export function parseSessionLocked(output) {
+  if (!/<plist[\s>]/u.test(output)) return null;
+  const users = /<key>IOConsoleUsers<\/key>\s*<array>([\s\S]*?)<\/array>/u.exec(output)?.[1] ?? '';
+  const onConsole = users
+    .match(/<dict>[\s\S]*?<\/dict>/gu)
+    ?.find((session) => ON_CONSOLE.test(session));
+  return LOCKED.test(onConsole ?? output);
+}
+
+/**
+ * true or false on macOS; null when unknown (another platform, or ioreg failed
+ * or took longer than 3 s). Never throws.
+ * @param {{ platform?: string, spawnSync?: typeof nodeSpawnSync }} [deps]
+ * @returns {boolean | null}
+ */
+export function macosSessionLocked({
+  platform = process.platform,
+  spawnSync = nodeSpawnSync,
+} = {}) {
+  if (platform !== 'darwin') return null;
+  try {
+    const result = spawnSync('ioreg', ['-n', 'Root', '-d1', '-a'], {
+      encoding: 'utf8',
+      timeout: 3_000,
+      maxBuffer: 8 * 1024 * 1024,
+      stdio: ['ignore', 'pipe', 'ignore'],
+    });
+    if (result.error || result.status !== 0) return null;
+    return parseSessionLocked(String(result.stdout));
+  } catch {
+    return null;
+  }
+}