@botbuddy/cli 1.32.0 → 1.32.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@botbuddy/cli",
-  "version": "1.32.0",
+  "version": "1.32.1",
   "description": "BotBuddy — Swarm coordination CLI for multi-agent workflows",
   "type": "module",
   "bin": {

package/src/pw/args.mjs

@@ -1,4 +1,5 @@
 import { TARGET_VERBS, parseTargetFlags, hasTargetFlags, buildLocatorTarget, classifyTarget, isSnapshotRef } from "./targets.mjs";
+import { TRANSLATE_VERBS, planTranslateVerb, MAX_EXEC_ARG } from "./translate.mjs";
 export const GLOBAL_VERBS = new Set(["list", "close-all", "kill-all", "reap"]);
 const secret = /^@ENV:(.+)$/;
 export function resolveRef(value, env = process.env) {
@@ -16,6 +17,20 @@ export function planInvocation(argv, env = process.env) {
   if (!validLane(lane) || !verb) throw new Error(`bb-pw: usage: lane must be a positive integer and include a verb`);
   if (verb === "status") return { scope: "lane", lane, session: `lane-${lane}`, verb, mode: "status" };
   const rest = argv.slice(2); let forwarded = rest, target = null, fresh = false;
+  // BOT-1702: bb-pw OWNS upload/route/unroute and translates them to upstream
+  // `run-code` (see translate.mjs). A resolved `@ENV:` secret in any value routes
+  // the generated code through the socket path so it never lands in argv, and is
+  // tracked for redaction — mirroring the sibling verbs' guarantee.
+  if (TRANSLATE_VERBS.has(verb)) {
+    const { code, secretValues } = planTranslateVerb(verb, rest, { env, resolveRef });
+    // Use the daemon socket (JSON, no argv limit) for a resolved secret OR a
+    // payload too large for a single child-process argument (Codex R2 P2: a big
+    // --inline/body would otherwise fail with E2BIG). Measure UTF-8 BYTES, not
+    // UTF-16 code units — the kernel's per-arg limit is on encoded bytes, so a
+    // multibyte body (e.g. emoji/CJK) could otherwise slip past (Codex R3 P2).
+    const sensitive = secretValues.length > 0 || Buffer.byteLength(code, "utf8") > MAX_EXEC_ARG;
+    return { scope: "lane", lane, session: `lane-${lane}`, verb, mode: sensitive ? "socket" : "exec", execArgv: sensitive ? null : [`-s=lane-${lane}`, "run-code", code], socketArgs: sensitive ? ["run-code", code] : null, telemetryUrl: null, secretValues, rollup: false, target: null, targetKind: null, fresh: false, translate: true };
+  }
   if (TARGET_VERBS.has(verb)) {
     const parsed = parseTargetFlags(rest); fresh = parsed.fresh;
     forwarded = hasTargetFlags(parsed.flags) ? [buildLocatorTarget(parsed.flags), ...parsed.rest] : parsed.rest;

package/src/pw/readiness.mjs

@@ -1,4 +1,7 @@
 export const NAV = "navigate";
-const interaction = new Set(["click", "fill", "type", "select", "press", "drag", "hover", "dblclick", "check", "uncheck"]);
+// `upload` mutates the page (it sets the input's files), so it counts as an
+// interaction — otherwise session telemetry would omit every upload (BOT-1702
+// Codex R27 P2).
+const interaction = new Set(["click", "fill", "type", "select", "press", "drag", "hover", "dblclick", "check", "uncheck", "upload"]);
 export function actionTypeFromMethod(method) { const value = String(method); return ["goto", "open", "go-back", "go-forward", "reload"].includes(value) ? NAV : value === "screenshot" ? "screenshot" : value === "snapshot" ? "snapshot" : interaction.has(value) ? "interaction" : "other"; }
 export function deriveSession(events, { meta = {} } = {}) { const ordered = [...events].sort((a,b) => a.ts-b.ts), type = (name) => ordered.filter((event) => actionTypeFromMethod(event.method) === name); const nav = type(NAV); return { ...meta, started_at: ordered[0]?.ts ?? null, ended_at: ordered.at(-1)?.ts ?? null, duration_ms: ordered.length ? ordered.at(-1).ts - ordered[0].ts : 0, active_ms: 0, idle_threshold_ms: 60000, navigations: nav.length, distinct_routes: [...new Set(nav.map((event) => { try { return new URL(event.url).pathname; } catch { return String(event.url).split("?")[0]; } }))], screenshots: type("screenshot").length, snapshots: type("snapshot").length, interactions: type("interaction").length, actions_total: ordered.length }; }

package/src/pw/run.mjs

@@ -13,8 +13,19 @@ import { clearAgentState, isRejectedCachedMcpSession, resolveAgentSessionCredent
 // server-side, so the lane name bb-pw builds/matches/prints is the one the lock
 // kernel actually stored ("jonos-mbp:8", not "Jonos-MBP.localdomain:8").
 const hostFor = (env) => canonicalizeHostString(env.PLAYWRIGHT_MCP_HOST || env.HOSTNAME || os.hostname());
-function help(out) { out.write("Usage: pw [--tenant <slug>] [--session-id <id>] [--agent-session-token <token>] <lane> <verb> [args…]\n\nAliases: bb-pw <lane> <verb> [args…]   ·   botbuddy pw <lane> <verb> [args…]\n         (all three drive the same lock-gated Playwright lane)\n\n--session-id <id>  accept a lane held by this arming-session agent id (from\n                   register_agent); defaults to $BOTBUDDY_SESSION_ID, then the\n                   id saved by `botbuddy register`.\n--agent-session-token <token>  session credential (env $BOTBUDDY_AGENT_SESSION_TOKEN);\n                   --agent-key / --session-token are one-release legacy aliases.\n--tenant <slug>    override the worktree .botbuddy-agent.json tenant when falling\n                   back to the .mcp.json ($BOTBUDDY_MCP_KEY) credential.\n"); }
-function redact(value, secretValues = []) { return secretValues.reduce((text, secret) => secret ? text.split(secret).join("[redacted]") : text, String(value ?? "")); }
+function help(out) { out.write("Usage: pw [--tenant <slug>] [--session-id <id>] [--agent-session-token <token>] <lane> <verb> [args…]\n\nAliases: bb-pw <lane> <verb> [args…]   ·   botbuddy pw <lane> <verb> [args…]\n         (all three drive the same lock-gated Playwright lane)\n\n--session-id <id>  accept a lane held by this arming-session agent id (from\n                   register_agent); defaults to $BOTBUDDY_SESSION_ID, then the\n                   id saved by `botbuddy register`.\n--agent-session-token <token>  session credential (env $BOTBUDDY_AGENT_SESSION_TOKEN);\n                   --agent-key / --session-token are one-release legacy aliases.\n--tenant <slug>    override the worktree .botbuddy-agent.json tenant when falling\n                   back to the .mcp.json ($BOTBUDDY_MCP_KEY) credential.\n\nFile upload (BOT-1702) — works on a hidden <input type=file>:\n  bb-pw <lane> upload <selector> <path...>\n  bb-pw <lane> upload <selector> --inline name=<n>,mime=<m>,size=<bytes>\n  bb-pw <lane> upload <selector> --inline name=<n>,mime=<m>,bytes=@base64:<b64>\n  bb-pw <lane> upload <selector> --inline name=<n>,mime=<m>,text=<str>\n     --inline repeats; builds synthetic files in memory (no workstation FS).\n     <selector> also accepts --testid/--role/--label/--text like click/fill.\n\nNetwork mocking (BOT-1702) — routes persist on the lane across invocations:\n  bb-pw <lane> route <url-glob> stall                 hold the request pending\n                                                      (screenshot the loading state)\n  bb-pw <lane> route <url-glob> abort [--error <code>] fail the request (default: failed)\n  bb-pw <lane> route <url-glob> fulfill --status <n> [--content-type <ct>]\n                                        [--body <str|@base64:..|@file:PATH>]\n  bb-pw <lane> unroute [<url-glob>]                    release one route, or all\n  bb-pw <lane> route-list                              list the routes owned on this lane\n  (offline mode already exists upstream: bb-pw <lane> network-state-set offline)\n"); }
+// Redact LONGEST secrets first: replacing a short value that is a substring of a
+// longer secret (e.g. a filename that also appears inside the payload's base64)
+// would otherwise break the longer match and leave the remainder recoverable
+// (Codex R11 P1).
+export function redact(value, secretValues = []) { return [...new Set(secretValues.filter(Boolean))].sort((a, b) => b.length - a.length).reduce((text, secret) => text.split(secret).join("[redacted]"), String(value ?? "")); }
+// bb-pw OWNS the translate verbs, so their generated run-code is an internal
+// implementation detail. When a secret is embedded in it, @playwright/cli echoes
+// the source back ("### Ran Playwright code") in forms our value-based redaction
+// cannot always match (JSON- vs single-quote-escaped, normalized, base64…). When
+// any secret is in play we therefore DROP the echoed code block entirely — the
+// robust fix for the whole class — while still redacting the rest (Codex R11).
+export const stripCodeEcho = (text) => String(text ?? "").replace(/### Ran Playwright code\n```[\s\S]*?\n```\n?/g, "");
 // BOT-1488: the register_agent identity for this machine, persisted by
 // `botbuddy register` into ~/.botbuddy/config.json. This is the SESSION agent
 // that acquire_resources binds a lane to — distinct from the tenant-bound
@@ -161,7 +172,17 @@ async function runPwInner(argv, deps = {}) {
   const effHost = auth.canonicalHost ?? host;
   if (plan.mode === "status") { const lock = auth.coordinator?.status ? await auth.coordinator.status({ host: effHost, slot: plan.lane }) : null; stdout.write(JSON.stringify({ lane: plan.lane, session: plan.session, host: effHost, lock, spooled_events: telemetry.count(plan.lane) }, null, 2) + "\n"); return 0; }
   if (actionTypeFromMethod(plan.verb) !== "other") telemetry.append(plan.lane, { ts: Date.now(), method: plan.verb, url: actionTypeFromMethod(plan.verb) === NAV ? plan.telemetryUrl : null });
-  const inspect = plan.mode === "socket" || (actionTypeFromMethod(plan.verb) === "interaction" && (plan.targetKind === "ref" || plan.fresh)); let code;
-  if (inspect) { if (plan.fresh) await socketRun({ ...plan, socketArgs: ["snapshot"] }, env).catch(() => {}); const result = await socketRun({ ...plan, socketArgs: plan.socketArgs ?? plan.execArgv.slice(1) }, env); if (result.text) stdout.write(`${redact(result.text, plan.secretValues)}\n`); if (!result.ok) stderr.write(`${redact(plan.targetKind === "ref" && isStaleRefError(result.error) ? staleRefRemediation(plan.target) : result.error, plan.secretValues)}\n`); code = result.ok ? 0 : 1; } else code = await spawnExec(plan, env);
+  // Translate verbs ALWAYS run via the socket (even a small, non-secret one), so
+  // run.mjs — not an inherited-stdio spawnExec — owns their output and can strip
+  // the internal code echo; socketRun falls back to execArgv.slice(1) as its args
+  // (Codex R26 P2).
+  const inspect = plan.mode === "socket" || plan.translate || (actionTypeFromMethod(plan.verb) === "interaction" && (plan.targetKind === "ref" || plan.fresh)); let code;
+  // bb-pw's translate verbs (upload/route/...) generate internal run-code; that
+  // echoed "### Ran Playwright code" block is never useful to the caller and can
+  // be large (a 100KB+ base64 payload) or carry a secret, so strip it for every
+  // translated command — not only secret ones (Codex R25 P2) — while still
+  // redacting any tracked secret from the rest.
+  const suppressEcho = !!plan.translate || !!plan.secretValues?.length;
+  if (inspect) { if (plan.fresh) await socketRun({ ...plan, socketArgs: ["snapshot"] }, env).catch(() => {}); const result = await socketRun({ ...plan, socketArgs: plan.socketArgs ?? plan.execArgv.slice(1) }, env); if (result.text) { const text = suppressEcho ? stripCodeEcho(result.text) : result.text; stdout.write(`${redact(text, plan.secretValues)}\n`); } if (!result.ok) { let errText = plan.targetKind === "ref" && isStaleRefError(result.error) ? staleRefRemediation(plan.target) : result.error; if (suppressEcho) errText = stripCodeEcho(errText); stderr.write(`${redact(errText, plan.secretValues)}\n`); } code = result.ok ? 0 : 1; } else code = await spawnExec(plan, env);
   if (plan.rollup && code === 0) await telemetry.rollup({ lane: plan.lane, coordinator: auth.coordinator, host: effHost }); return code;
 }

package/src/pw/targets.mjs

@@ -3,7 +3,12 @@ export const TARGET_VERBS = new Set(["click", "dblclick", "fill", "hover", "chec
 export const isSnapshotRef = (value) => REF.test(String(value ?? ""));
 export const classifyTarget = (value) => /^getBy[A-Z]/.test(String(value ?? "")) ? "locator" : isSnapshotRef(value) ? "ref" : "selector";
 const BASE = ["role", "placeholder", "text", "testid", "label", "title", "alt"];
-const quote = (value) => `'${String(value).replace(/\\/g, "\\\\").replace(/'/g, "\\'")}'`;
+// Produce a VALID single-quoted JS string literal. Besides backslash and the
+// quote, escape newline/CR — an unescaped newline in a single-quoted literal is a
+// syntax error, which would break the run-code that embeds a locator built from a
+// multiline flag value (BOT-1702 Codex R24 P2). (U+2028/U+2029 are legal in
+// string literals since ES2019, so they need no escaping.)
+const quote = (value) => "'" + String(value).replace(/\\/g, "\\\\").replace(/'/g, "\\'").replace(/\n/g, "\\n").replace(/\r/g, "\\r") + "'";
 export function parseTargetFlags(args) {
   const flags = {}, rest = []; let fresh = false;
   for (let index = 0; index < args.length; index += 1) {
@@ -15,6 +20,10 @@ export function parseTargetFlags(args) {
     if (![...BASE, "name"].includes(name)) { rest.push(args[index]); continue; }
     const value = inline ?? args[++index];
     if (value === undefined) throw new Error(`bb-pw: --${name} needs a value`);
+    // Reject a repeated locator flag rather than silently keeping the last value,
+    // so a concatenated command can't target a different element while reporting
+    // success (BOT-1702 Codex R22 P2).
+    if (name in flags) throw new Error(`bb-pw: duplicate flag --${name}`);
     flags[name] = value;
   }
   return { flags, rest, fresh };

package/src/pw/translate.mjs

@@ -0,0 +1,411 @@
+import { resolve } from "node:path";
+import { readFileSync } from "node:fs";
+import { createHash } from "node:crypto";
+import { parseTargetFlags, hasTargetFlags, buildLocatorTarget } from "./targets.mjs";
+
+// BOT-1702: bb-pw OWNS the `upload`/`route`/`unroute` verbs and translates them
+// to upstream `@playwright/cli run-code`, whose function body runs against the
+// lane daemon's persistent page. This keeps the surface in our control (no MS
+// fork) and lets route handlers persist across invocations, so
+// `route <glob> stall` → `goto` → `screenshot` → `unroute` works. Driver:
+// a Supply Guard acceptance flow (its policy-document upload UI).
+export const TRANSLATE_VERBS = new Set(["upload", "route", "unroute", "route-list"]);
+const ROUTE_ACTIONS = new Set(["stall", "abort", "fulfill"]);
+// Force the socket transport (JSON over the daemon socket, no argv limit) once
+// the generated run-code exceeds this, instead of passing it as one child-process
+// argument. Linux caps a single argv entry at ~128 KiB (MAX_ARG_STRLEN), but
+// Windows caps the WHOLE command line at 32,767 chars — so pick the limit by
+// platform, well under each cap, or a large `--inline`/fulfill body would fail in
+// spawn() (Codex R2/R23 P2).
+export const MAX_EXEC_ARG = process.platform === "win32" ? 8_000 : 100_000;
+// A JS string/number literal safe to embed in generated code. JSON.stringify
+// emits a valid double-quoted JS string (or a bare number), so it doubles as our
+// escaper for selectors, globs, bodies and base64 blobs.
+const j = (value) => JSON.stringify(value);
+
+// Node's base64 decoder is permissive: it silently drops invalid chars AND
+// normalizes non-canonical padding bits (e.g. "AB==" → "AA=="), so a malformed
+// payload would decode to different bytes than the caller supplied (Codex R4/R6
+// P2). Accept only input that round-trips to itself, i.e. canonical standard
+// base64.
+function decodeBase64(text, ctx) {
+  const s = String(text);
+  const buf = Buffer.from(s, "base64");
+  if (buf.toString("base64") !== s)
+    throw new Error(`bb-pw: ${ctx}: invalid base64 (expected canonical standard padded base64)`);
+  return buf;
+}
+
+// A fulfill body is embedded as a JS string literal, so it must be exact UTF-8.
+// Reject bytes that don't round-trip (e.g. a base64/file payload with byte 0xff),
+// rather than silently corrupting them via `toString("utf8")` → U+FFFD (Codex R19
+// P2). Binary response bodies are out of scope.
+function utf8Body(buf, ctx) {
+  const str = buf.toString("utf8");
+  if (!Buffer.from(str, "utf8").equals(buf))
+    throw new Error(`bb-pw: ${ctx}: body is not valid UTF-8 (binary fulfill bodies are not supported — provide text/JSON)`);
+  return str;
+}
+
+// The finite set Playwright's Route.abort accepts; anything else asserts in
+// Chromium at request time, so validate at plan time (Codex R6 P2).
+const ABORT_ERRORS = new Set(["aborted", "accessdenied", "addressunreachable", "blockedbyclient", "blockedbyresponse", "connectionaborted", "connectionclosed", "connectionfailed", "connectionrefused", "connectionreset", "internetdisconnected", "namenotresolved", "timedout", "failed"]);
+
+// Parse one `--inline name=<n>,mime=<m>,(size=<bytes>|bytes=@base64:<b64>|text=<str>)`
+// spec into an in-memory file descriptor. Never touches the workstation FS, so an
+// agent can craft a 0-byte or spoofed-bytes file without staging one on disk.
+export function parseInline(spec) {
+  const s = String(spec);
+  // The content source (size=/bytes=/text=) is the LAST field and its value runs
+  // to end-of-string, so a text/CSV/query-string payload may contain commas —
+  // even a literal `,name=`/`,size=` — without being mis-split (Codex R8 P2).
+  const src = /(?:^|,)(size|bytes|text)=/.exec(s);
+  if (!src) throw new Error("bb-pw: --inline needs one of size=<bytes>, bytes=@base64:<b64>, or text=<str> as its last field");
+  const srcKey = src[1];
+  const srcStart = src.index + (src[0].length - (srcKey.length + 1));
+  const srcValue = s.slice(srcStart + srcKey.length + 1);
+  // The head (everything before the source) holds name=/mime=; those values never
+  // contain commas, so a plain comma split is safe here.
+  const kv = {};
+  const head = s.slice(0, srcStart).replace(/,$/, "");
+  if (head) for (const part of head.split(",")) {
+    const eq = part.indexOf("=");
+    if (eq < 0) throw new Error(`bb-pw: --inline expects key=value pairs, got "${part}"`);
+    const key = part.slice(0, eq).trim();
+    // Only name/mime are valid before the content source; reject an unknown or
+    // misspelled field (e.g. `filename=`) or a duplicate rather than ignoring it
+    // and uploading with different metadata than the caller intended (Codex R20).
+    if (key !== "name" && key !== "mime") throw new Error(`bb-pw: --inline: unknown field "${key}" (allowed: name, mime, and one of size/bytes/text)`);
+    if (key in kv) throw new Error(`bb-pw: --inline: duplicate field "${key}"`);
+    kv[key] = part.slice(eq + 1);
+  }
+  if (!kv.name) throw new Error("bb-pw: --inline needs name=<filename> before the content source");
+  if (!kv.mime) throw new Error("bb-pw: --inline needs mime=<type> before the content source");
+  let buffer;
+  if (srcKey === "size") {
+    const n = Number(srcValue);
+    if (!/^\d+$/.test(srcValue) || !Number.isInteger(n) || n < 0) throw new Error(`bb-pw: --inline size must be a non-negative integer, got "${srcValue}"`);
+    buffer = Buffer.alloc(n);
+  } else if (srcKey === "bytes") {
+    const match = /^@base64:(.*)$/s.exec(srcValue);
+    if (!match) throw new Error("bb-pw: --inline bytes= must be @base64:<data>");
+    buffer = decodeBase64(match[1], "--inline bytes");
+  } else {
+    buffer = Buffer.from(srcValue, "utf8");
+  }
+  // Bytes are carried as base64 and decoded in the BROWSER via `atob` (see
+  // buildUploadCode): base64 is ~1.33× vs ~3-4× for a JS number array, keeping the
+  // generated arg small (Codex R2 P2), and the browser has `atob` where the
+  // run-code VM lacks Node `Buffer` and Playwright's Buffer-only FilePayload.
+  return { name: kv.name, mimeType: kv.mime, base64: buffer.toString("base64") };
+}
+
+// `selectorExpr` is a full page accessor expression, e.g. `page.locator("#x")` or
+// `page.getByTestId('x')`. `files` is either [{path}] (real disk paths) or
+// [{name,mimeType,bytes}] (synthetic in-memory). Both paths work on a hidden
+// <input type=file>:
+//   - real paths → Playwright `setInputFiles([...paths])` (native chooser path).
+//   - synthetic → built as File objects in the BROWSER via DataTransfer and
+//     assigned to `input.files`, dispatching input+change. This is fully hermetic
+//     (no workstation FS) and avoids Playwright's Buffer-only FilePayload, which
+//     is unreachable from the sandboxed run-code context (no Node Buffer there).
+export function buildUploadCode(selectorExpr, files) {
+  const synthetic = files.length > 0 && files[0].path === undefined;
+  if (!synthetic) {
+    const items = files.map((file) => j(file.path));
+    return `async page => { await ${selectorExpr}.setInputFiles([${items.join(", ")}]); }`;
+  }
+  const payload = files.map((file) => ({ name: file.name, mime: file.mimeType, b64: file.base64 }));
+  // Enforce the same constraints Playwright's setInputFiles applies, which this
+  // synthetic path would otherwise bypass — allowing browser states a real user
+  // cannot reach (Codex R13 P2): the target must be an <input type=file>, and
+  // multiple files require a `multiple` input.
+  return `async page => { await ${selectorExpr}.evaluate((el, files) => { if (el instanceof HTMLLabelElement && el.control) el = el.control; if (!(el instanceof HTMLInputElement) || el.type !== "file") throw new Error("bb-pw upload: target is not an <input type=file>"); if (el.webkitdirectory) throw new Error("bb-pw upload: cannot assign synthetic files to a directory (webkitdirectory) input"); if (files.length > 1 && !el.multiple) throw new Error("bb-pw upload: multiple files require an <input multiple>"); const dt = new DataTransfer(); for (const f of files) { const bin = atob(f.b64); const u8 = new Uint8Array(bin.length); for (let i = 0; i < bin.length; i++) u8[i] = bin.charCodeAt(i); dt.items.add(new File([u8], f.name, { type: f.mime })); } el.files = dt.files; el.dispatchEvent(new Event("input", { bubbles: true, composed: true })); el.dispatchEvent(new Event("change", { bubbles: true, composed: true })); }, ${JSON.stringify(payload)}); }`;
+}
+
+// bb-pw's routes are registered via `page.route` inside the run-code VM, which
+// bypasses upstream's route registry — so upstream `route-list` would report "No
+// active routes" and a leftover stall/fulfill mock would be invisible (Codex R2
+// P2). We therefore track owned routes on `page.__bbPwRoutes` (the daemon reuses
+// one page object across invocations) and OWN `route-list`/`unroute` so they read
+// and prune that registry.
+// Bookkeeping key = a non-reversible digest of the RESOLVED glob. It mirrors
+// Playwright's page.unroute (which matches on the resolved pattern), so two routes
+// installed under the same `@ENV:` ref but DIFFERENT resolved values get distinct
+// keys and are pruned independently (Codex R4 P2). It is a hash, so it never
+// leaks a secret glob into the registry that route-list prints (Codex R3 P1).
+const matchKey = (resolvedGlob) => createHash("sha256").update(String(resolvedGlob)).digest("hex").slice(0, 16);
+// `displayGlob` is what route-list shows — the raw arg (e.g. `@ENV:SIGNED_URL`),
+// never the resolved value.
+const trackRoute = (displayGlob, action, key) => `(page.__bbPwRoutes = page.__bbPwRoutes || []).push({ glob: ${j(displayGlob)}, action: ${j(action)}, key: ${j(key)} });`;
+
+export function buildRouteCode(glob, action, opts = {}, displayGlob = glob) {
+  const g = j(glob), key = matchKey(glob);
+  const track = trackRoute(displayGlob, action, key);
+  if (action === "stall")
+    // Capture each intercepted route (never resolving it) so the matched request
+    // hangs pending — a screenshot captures the loading state — and unroute can
+    // later release it (Codex R3 P2), instead of leaving it hung forever.
+    return `async page => { await page.route(${g}, route => { (page.__bbPwPending = page.__bbPwPending || []).push({ key: ${j(key)}, route }); }); ${track} }`;
+  if (action === "abort")
+    return `async page => { await page.route(${g}, route => route.abort(${j(opts.error || "failed")})); ${track} }`;
+  if (action === "fulfill") {
+    const fields = [];
+    if (opts.status !== undefined) fields.push(`status: ${Number(opts.status)}`);
+    if (opts.contentType !== undefined) fields.push(`contentType: ${j(opts.contentType)}`);
+    // Body is ALWAYS a plain string literal. @base64:/@file: are decoded at plan
+    // time (Node, where Buffer exists) — the generated handler runs in the
+    // @playwright/cli run-code VM, which exposes no Node Buffer, so a
+    // `Buffer.from(...)` here would throw ReferenceError on the first request.
+    if (opts.body !== undefined) fields.push(`body: ${j(opts.body)}`);
+    return `async page => { await page.route(${g}, route => route.fulfill({ ${fields.join(", ")} })); ${track} }`;
+  }
+  throw new Error(`bb-pw: route action must be stall|abort|fulfill, got "${action}"`);
+}
+
+// On unroute, also RELEASE any requests already caught by a stall handler —
+// page.unroute only stops future interceptions and would leave the pending
+// request hanging (Codex R3 P2) — and prune only the records whose resolved key
+// matches, so a colliding display ref keeps its other route (R4 P2). For a
+// SPECIFIC unroute, release via route.fallback() so any broader still-registered
+// mock in the chain still runs (route.continue() would go straight to the network
+// and bypass it); for clear-all there is no remaining chain, so continue()
+// directly (Codex R23 P2).
+export function buildUnrouteCode(glob, displayGlob = glob) {
+  // Only null/undefined means "clear all"; an (already-rejected) empty string
+  // must never reach the unrouteAll branch (Codex R5 P2).
+  if (glob != null) {
+    const g = j(glob), key = j(matchKey(glob));
+    return `async page => { await page.unroute(${g}); for (const p of (page.__bbPwPending || []).filter(p => p.key === ${key})) { try { await p.route.fallback(); } catch {} } if (page.__bbPwPending) page.__bbPwPending = page.__bbPwPending.filter(p => p.key !== ${key}); if (page.__bbPwRoutes) page.__bbPwRoutes = page.__bbPwRoutes.filter(r => r.key !== ${key}); }`;
+  }
+  return `async page => { await page.unrouteAll(); for (const p of (page.__bbPwPending || [])) { try { await p.route.continue(); } catch {} } page.__bbPwPending = []; page.__bbPwRoutes = []; }`;
+}
+
+export function buildRouteListCode() {
+  // Return the ARRAY directly (glob + action only; the internal match key stays
+  // out of the output). @playwright/cli's run-code wrapper JSON.stringifies the
+  // result once — stringifying here too would emit a JSON string, leaving
+  // automation a string after one parse (Codex R25 P2).
+  return `async page => { return (page.__bbPwRoutes || []).map(r => ({ glob: r.glob, action: r.action })); }`;
+}
+
+// Allowed flags per route action; anything else is a typo or an incompatible
+// option and must be rejected rather than silently ignored (Codex R3 P2).
+const ROUTE_FLAGS = { stall: [], abort: ["error"], fulfill: ["status", "content-type", "body"] };
+
+function parseSimpleFlags(args) {
+  const flags = {};
+  for (let index = 0; index < args.length; index += 1) {
+    const match = /^--([a-z][a-z-]*)(?:=(.*))?$/s.exec(String(args[index]));
+    if (!match) throw new Error(`bb-pw: unexpected argument "${args[index]}"`);
+    const value = match[2] !== undefined ? match[2] : args[index += 1];
+    if (value === undefined) throw new Error(`bb-pw: --${match[1]} needs a value`);
+    // Reject a repeated flag rather than silently keeping the last value, so a
+    // concatenated command can't run against a different mock than intended
+    // (Codex R21 P2).
+    if (match[1] in flags) throw new Error(`bb-pw: duplicate flag --${match[1]}`);
+    flags[match[1]] = value;
+  }
+  return flags;
+}
+
+function planUpload(rest, rr, markSecret, resolveMeta) {
+  const { flags, rest: remainder } = parseTargetFlags(rest);
+  let selectorExpr, fileArgs;
+  if (hasTargetFlags(flags)) {
+    // Resolve `@ENV:` in each locator flag value (not the boolean `exact`), so a
+    // secret/ref in a target flag behaves like any other value (Codex R1 P2).
+    const resolved = Object.fromEntries(Object.entries(flags).map(([key, value]) => [key, key === "exact" ? value : rr(value)]));
+    selectorExpr = `page.${buildLocatorTarget(resolved)}`;
+    fileArgs = remainder;
+  } else {
+    const selector = remainder[0];
+    if (selector === undefined || String(selector).startsWith("--"))
+      throw new Error("bb-pw: upload needs a <selector> (or --testid/--role/--label/--text)");
+    selectorExpr = `page.locator(${j(rr(selector))})`;
+    fileArgs = remainder.slice(1);
+  }
+  // Parse one --inline spec. If the spec itself came from a secret ref
+  // (`--inline @ENV:SPEC`), parseInline SPLITS and TRANSFORMS it, so the whole
+  // recorded secret no longer matches the substrings that reach errors, nor the
+  // base64 payload embedded in the echoed code. Mark the derived name/mime/base64
+  // sensitive, and on an invalid secret spec throw a value-free error so no
+  // fragment leaks (Codex R10 P1).
+  const parseInlineArg = (spec) => {
+    const { value: resolved, secret: specWasSecret } = resolveMeta(spec);
+    let file;
+    try { file = parseInline(resolved); }
+    catch (error) { throw specWasSecret ? new Error("bb-pw: --inline spec from a secret ref is invalid (value redacted)") : error; }
+    if (specWasSecret) { markSecret(file.name); markSecret(file.mimeType); markSecret(file.base64); }
+    return file;
+  };
+  const paths = [], inlines = [];
+  for (let index = 0; index < fileArgs.length; index += 1) {
+    const token = String(fileArgs[index]);
+    if (token === "--inline") {
+      const spec = fileArgs[index += 1];
+      if (spec === undefined) throw new Error("bb-pw: --inline needs a value");
+      inlines.push(parseInlineArg(spec));
+    } else if (token.startsWith("--inline=")) {
+      inlines.push(parseInlineArg(token.slice("--inline=".length)));
+    } else if (token.startsWith("--")) {
+      throw new Error(`bb-pw: upload: unexpected flag "${token}"`);
+    } else {
+      paths.push(fileArgs[index]);
+    }
+  }
+  if (inlines.length && paths.length)
+    throw new Error("bb-pw: upload takes either real <path...> OR --inline synthetic files, not both");
+  if (!inlines.length && !paths.length)
+    throw new Error("bb-pw: upload needs at least one <path> or --inline file");
+  const files = inlines.length ? inlines : paths.map((path) => {
+    const { value, secret } = resolveMeta(path);
+    const abs = resolve(value);
+    // If the path came from a secret ref, normalization may change its spelling;
+    // mark the resolved absolute form sensitive too (Codex R11/R14 P2).
+    if (secret) markSecret(abs);
+    return { path: abs };
+  });
+  return buildUploadCode(selectorExpr, files);
+}
+
+function planRoute(rest, rr, markSecret, resolveMeta) {
+  const rawGlob = rest[0];
+  if (rawGlob === undefined || rawGlob === "" || String(rawGlob).startsWith("--"))
+    throw new Error("bb-pw: route needs a <url-glob> pattern");
+  const action = rest[1];
+  if (action === undefined || String(action).startsWith("--"))
+    throw new Error("bb-pw: route needs an action: stall|abort|fulfill");
+  if (!ROUTE_ACTIONS.has(action))
+    throw new Error(`bb-pw: route action must be stall|abort|fulfill, got "${action}"`);
+  const flags = parseSimpleFlags(rest.slice(2));
+  const allowed = ROUTE_FLAGS[action];
+  const unknown = Object.keys(flags).filter((flag) => !allowed.includes(flag));
+  if (unknown.length)
+    throw new Error(`bb-pw: route ${action}: unsupported flag(s) ${unknown.map((f) => `--${f}`).join(", ")}. Allowed: ${allowed.length ? allowed.map((f) => `--${f}`).join(", ") : "none"}`);
+  // displayGlob is the raw arg (safe: a secret ref stays "@ENV:X"); g is resolved.
+  const g = rr(rawGlob), displayGlob = rawGlob;
+  if (action === "stall") return buildRouteCode(g, "stall", {}, displayGlob);
+  if (action === "abort") {
+    let error;
+    if (flags.error !== undefined) {
+      error = rr(flags.error);
+      if (!ABORT_ERRORS.has(error)) throw new Error(`bb-pw: route abort --error "${error}" is not a valid code. One of: ${[...ABORT_ERRORS].join(", ")}`);
+    }
+    return buildRouteCode(g, "abort", { error }, displayGlob);
+  }
+  const opts = {};
+  // --status is required for fulfill (contract: `fulfill --status <n>`); omitting
+  // it would silently default to 200 and turn a negative-path mock into a success
+  // (Codex R6 P2).
+  if (flags.status === undefined) throw new Error("bb-pw: route fulfill requires --status <n>");
+  {
+    // Resolve @ENV: like the other values, then validate — an unresolved ref
+    // would become status: NaN in the handler (Codex R2 P2). Require a valid HTTP
+    // status (100-599): Playwright evaluates `status || 200`, so 0 (and other
+    // out-of-range values) would silently return 200 (Codex R7 P2).
+    const status = rr(flags.status);
+    if (!/^\d+$/.test(String(status)) || Number(status) < 100 || Number(status) > 599)
+      throw new Error(`bb-pw: route fulfill --status must be a valid HTTP status (100-599), got "${status}"`);
+    opts.status = status;
+  }
+  if (flags["content-type"] !== undefined) opts.contentType = rr(flags["content-type"]);
+  if (flags.body !== undefined) {
+    // Resolve @ENV: FIRST, then interpret @base64:/@file: on the RESOLVED value —
+    // so `--body @ENV:BODY` where BODY is `@base64:…`/`@file:…` is decoded/loaded,
+    // not fulfilled with the literal marker (Codex R16 P2).
+    const { value: resolvedBody, secret: bodyWasSecret } = resolveMeta(flags.body);
+    const base64 = /^@base64:(.*)$/s.exec(resolvedBody);
+    const file = /^@file:(.*)$/s.exec(resolvedBody);
+    // Decode to a UTF-8 string at plan time so the generated handler embeds a
+    // plain string (no Buffer in the run-code VM). Fulfill bodies are text/JSON
+    // mock responses; binary bodies are out of scope.
+    if (base64) opts.body = utf8Body(decodeBase64(base64[1], "route fulfill --body @base64"), "route fulfill --body @base64");
+    else if (file) {
+      // When the @file: path itself came from a secret ref, mark the EXTRACTED
+      // path sensitive before reading, so a filesystem error (ENOENT etc.) that
+      // contains the bare path is redacted by the planner-error path (Codex R17
+      // P2). @file: contents are always sensitive — mark them so the body takes
+      // the socket path and is redacted, never emitted into argv/logs (R8 P2).
+      if (bodyWasSecret) markSecret(file[1]);
+      opts.body = markSecret(utf8Body(readFileSync(file[1]), "route fulfill --body @file"));
+    }
+    else opts.body = resolvedBody;
+    // If the ref itself was secret, the decoded/loaded body inherits provenance.
+    if (bodyWasSecret) markSecret(opts.body);
+  }
+  return buildRouteCode(g, "fulfill", opts, displayGlob);
+}
+
+function planUnroute(rest, rr) {
+  // Reject flag-shaped args: a typo like `unroute --glob=x` must NOT silently
+  // fall through to clearing every route (Codex R4 P2).
+  const flags = rest.filter((arg) => String(arg).startsWith("--"));
+  if (flags.length) throw new Error(`bb-pw: unroute takes no flags, got ${flags.join(", ")}`);
+  const positionals = rest.filter((arg) => !String(arg).startsWith("--"));
+  if (positionals.length > 1) throw new Error("bb-pw: unroute takes at most one <url-glob> (omit to clear all)");
+  const rawGlob = positionals[0];
+  if (rawGlob === undefined) return buildUnrouteCode(null, null);
+  // Fail closed on an explicitly empty glob (e.g. an unset "$GLOB"): it must not
+  // silently clear every route (Codex R5 P2).
+  if (rawGlob === "") throw new Error("bb-pw: unroute given an empty <url-glob>; omit the argument to clear all routes");
+  return buildUnrouteCode(rr(rawGlob), rawGlob);
+}
+
+function planRouteList(rest) {
+  // route-list takes no operands; reject a stray glob/flag rather than silently
+  // ignoring it and returning the full registry (Codex R18 P2).
+  if (rest.length) throw new Error(`bb-pw: route-list takes no arguments, got ${rest.join(" ")}`);
+  return buildRouteListCode();
+}
+
+// Build the generated run-code for a translate verb. `resolveRef` is passed in
+// from args.mjs (avoids an import cycle) so `@ENV:` refs resolve the same way as
+// for every other verb; any resolved secret is collected so the caller can route
+// through the socket path and redact it from output.
+export function planTranslateVerb(verb, rest, { env, resolveRef }) {
+  const secretValues = [];
+  // Track a secret in BOTH the raw form (as it may appear in a browser result)
+  // AND the JSON-escaped inner form (as it appears embedded via JSON.stringify in
+  // the generated code that @playwright/cli echoes back), so redaction catches a
+  // secret containing quotes/backslashes/newlines too (Codex R8 P2).
+  const pushSecret = (value) => {
+    const raw = String(value);
+    if (raw && !secretValues.includes(raw)) secretValues.push(raw);
+    const escaped = JSON.stringify(raw).slice(1, -1);
+    if (escaped !== raw && !secretValues.includes(escaped)) secretValues.push(escaped);
+  };
+  // Resolve @ENV: and report provenance. Provenance comes from resolveRef().secret
+  // directly — NOT from growth of the (deduplicated) secretValues, which would
+  // wrongly read false when the same secret was already tracked (Codex R14 P2).
+  const resolveMeta = (value) => {
+    const resolved = resolveRef(value, env);
+    if (resolved.secret) pushSecret(resolved.value);
+    return { value: String(resolved.value), secret: !!resolved.secret };
+  };
+  const rr = (value) => resolveMeta(value).value;
+  // Mark a value sensitive so it forces the socket transport and is redacted from
+  // output — used for content loaded from disk (@file:), which was never on the
+  // command line and must not be newly exposed in argv/logs (Codex R8 P2).
+  const markSecret = (value) => { pushSecret(value); return value; };
+  let code;
+  try {
+    code = verb === "upload" ? planUpload(rest, rr, markSecret, resolveMeta)
+      : verb === "route" ? planRoute(rest, rr, markSecret, resolveMeta)
+      : verb === "unroute" ? planUnroute(rest, rr)
+      : verb === "route-list" ? planRouteList(rest)
+      : (() => { throw new Error(`bb-pw: unknown translate verb ${verb}`); })();
+  } catch (error) {
+    // A planning error may interpolate a resolved @ENV: value (e.g. an invalid
+    // --status/--error). runPwInner writes the thrown message straight to stderr,
+    // before secretValues is applied — so redact it here, using the secrets rr()
+    // has already collected (Codex R9 P2).
+    throw new Error(redactSecrets(error?.message ?? String(error), secretValues));
+  }
+  return { code, secretValues };
+}
+
+// Dedupe + longest-first, matching run.mjs redact(): a short secret that is a
+// substring of a longer one must not be replaced first, or the longer match
+// breaks and leaks its remainder (Codex R12 P1).
+const redactSecrets = (text, secrets) => [...new Set(secrets.filter(Boolean))].sort((a, b) => b.length - a.length).reduce((acc, secret) => acc.split(secret).join("[redacted]"), String(text ?? ""));