@farmslot/adapter-web 0.6.0 → 0.6.1

package/CHANGELOG.md

@@ -6,6 +6,11 @@ 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.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/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.1",
   "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/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;
+  }
+}