@botbuddy/cli 1.32.0 → 1.32.2

package/package.json

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

package/src/pw/args.mjs

@@ -1,5 +1,26 @@
 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"]);
+// BOT-1682: the bb pw credential/session flags. They are accepted ONLY before the
+// lane (consumed in run.mjs). Once one reaches planInvocation it is after the lane
+// — the verb slot or the workload — which upstream @playwright/cli would reject
+// with an "Unknown option" + help dump; catch it here and name the fix (move it
+// before the lane) instead. `--tenant` after the lane also cannot be safely
+// honored for session/lane auth, another reason to refuse rather than forward it.
+export const PW_CREDENTIAL_FLAGS = ["--tenant", "--session-id", "--agent-session-token", "--agent-key", "--session-token"];
+const credentialFlagOf = (token) => PW_CREDENTIAL_FLAGS.find((flag) => token === flag || String(token).startsWith(`${flag}=`)) ?? null;
+function misplacedCredentialFlag(token) {
+  return new Error(`bb-pw: ${credentialFlagOf(token)} is a bb pw credential flag, not a Playwright argument — put it before the lane: bb-pw [--tenant <slug>] <lane> <verb> …`);
+}
+// BOT-1682: verbs that once existed under bb pw / an older @playwright/cli and now
+// map to a differently-named upstream command. On these, hint the rename in one
+// line instead of dumping ~110 lines of upstream usage. `console` and `status`
+// are NOT here — they are live commands.
+export const RETIRED_VERBS = { network: "use 'requests' (list) or 'request-headers <n>' / 'request <n>'" };
+// BOT-1682: everything after a bare `--` is a positional Playwright argument (the
+// upstream CLI treats `fill e1 -- --tenant` as literal text), so misplaced-flag
+// detection must not look past it. Mirrors legacyAgentAliasHint's own `--` cutoff.
+const beforeSeparator = (tokens) => { const sep = tokens.indexOf("--"); return sep === -1 ? tokens : tokens.slice(0, sep); };
 const secret = /^@ENV:(.+)$/;
 export function resolveRef(value, env = process.env) {
   const match = secret.exec(String(value));
@@ -11,17 +32,71 @@ export const normaliseLane = (token) => String(token).replace(/^agent-0*/, "").r
 function validLane(lane) { return /^[1-9]\d*$/.test(lane); }
 export function planInvocation(argv, env = process.env) {
   if (!argv.length) throw new Error("bb-pw: usage: bb-pw <lane> <verb> [args…]  (or: bb-pw <reap|list|close-all|kill-all>)");
-  if (GLOBAL_VERBS.has(argv[0])) return argv[0] === "reap" ? { scope: "global", verb: "reap", mode: "reap" } : { scope: "global", verb: argv[0], mode: "exec", execArgv: argv };
+  if (GLOBAL_VERBS.has(argv[0])) {
+    // BOT-1682: a credential flag after a global verb (`bb-pw list --tenant …`)
+    // has no lane to sit before, and would otherwise be forwarded to upstream —
+    // which rejects it with its own "Unknown option" dump. Refuse it here too.
+    // Global verbs (list/close-all/kill-all/reap) take NO positional workload, so
+    // unlike lane verbs there is no `--` exemption — a credential-shaped token in
+    // ANY position (incl. after `--`) is misplaced, never a literal value that
+    // upstream would accept (Codex: `list -- --tenant` otherwise reaches upstream,
+    // which errors "too many arguments").
+    const strayGlobal = argv.slice(1).find((value) => credentialFlagOf(value));
+    if (strayGlobal) throw misplacedCredentialFlag(strayGlobal);
+    return argv[0] === "reap" ? { scope: "global", verb: "reap", mode: "reap" } : { scope: "global", verb: argv[0], mode: "exec", execArgv: argv };
+  }
   const lane = normaliseLane(argv[0]), verb = argv[1];
   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" };
+  // BOT-1682: a credential flag in the verb slot (`<lane> --tenant …`) or a
+  // retired verb — caught before status/target handling so neither leaks upstream.
+  if (credentialFlagOf(verb)) throw misplacedCredentialFlag(verb);
+  if (Object.hasOwn(RETIRED_VERBS, verb)) throw new Error(`bb-pw: '${verb}' was retired — ${RETIRED_VERBS[verb]}`);
+  if (verb === "status") {
+    // `status` has no workload, so — like the global verbs — there is no `--`
+    // exemption: a credential flag in ANY position (incl. after `--`) is misplaced
+    // and must be refused, or `status -- --tenant` would return success while
+    // silently ignoring it and still leaving the id readable downstream (Codex).
+    const strayStatus = argv.slice(2).find((value) => credentialFlagOf(value));
+    if (strayStatus) throw misplacedCredentialFlag(strayStatus);
+    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)) {
+    // BOT-1682: run the misplaced-credential-flag guard BEFORE dispatching a
+    // translated verb (upload/route/unroute/route-list), so `route … stall --tenant …`
+    // gets the one-line "put it before the lane" refusal rather than an unrelated
+    // translate-parse error (Codex). But a translated verb's parsers consume the
+    // token AFTER an option as that option's VALUE (`upload --label --tenant`,
+    // `route … fulfill --body --session-token`), so a credential-shaped token whose
+    // predecessor is an option (`--x`) is a legitimate value and is left alone;
+    // only one in a non-value position is misplaced (Codex R17). `--` still exempts.
+    const scanT = beforeSeparator(rest);
+    const strayTranslate = scanT.find((value, i) => credentialFlagOf(value) && !(i > 0 && /^--[a-z]/.test(String(scanT[i - 1]))));
+    if (strayTranslate) throw misplacedCredentialFlag(strayTranslate);
+    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;
     target = forwarded.find((value) => !String(value).startsWith("--")) ?? null;
     if (fresh && target && isSnapshotRef(target)) throw new Error("bb-pw: --fresh cannot target a snapshot ref; use a stable locator");
   }
+  // BOT-1682: a credential flag surviving into the workload (`<lane> <verb> …
+  // --tenant …`) is misplaced — target-flag VALUES have already been consumed by
+  // parseTargetFlags, so only a genuine standalone credential-flag token remains.
+  const stray = beforeSeparator(forwarded).find((value) => credentialFlagOf(value));
+  if (stray) throw misplacedCredentialFlag(stray);
   const resolved = forwarded.map((value) => resolveRef(value, env));
   const sensitive = resolved.some((value) => value.secret);
   return { scope: "lane", lane, session: `lane-${lane}`, verb, mode: sensitive ? "socket" : "exec", execArgv: sensitive ? null : [`-s=lane-${lane}`, verb, ...forwarded], socketArgs: sensitive ? [verb, ...resolved.map((value) => value.value)] : null, telemetryUrl: ["goto", "open", "go-back", "go-forward", "reload"].includes(verb) ? (resolved[0]?.secret ? resolved[0].ref : forwarded[0] ?? null) : null, secretValues: resolved.filter((value) => value.secret).map((value) => String(value.value)), rollup: verb === "close", target, targetKind: target === null ? null : classifyTarget(target), fresh };

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

@@ -1,5 +1,5 @@
 import os from "node:os";
-import { planInvocation } from "./args.mjs";
+import { planInvocation, GLOBAL_VERBS } from "./args.mjs";
 import { actionTypeFromMethod, NAV } from "./readiness.mjs";
 import { isStaleRefError, staleRefRemediation } from "./targets.mjs";
 import { createSessionTokenCoordinator } from "./coordinator.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>    accepted before the lane but currently INERT — the tenant\n                   comes from your resolved credential, so bb pw does not act on\n                   this flag for session/lane auth yet (server-validated tenant\n                   selection is tracked in BOT-1732).\n\nCredential flags (--tenant / --session-id / --agent-session-token) go BEFORE the\nlane. Placed after the lane they are refused with guidance (they are not\nPlaywright arguments, and a --tenant after the lane cannot be safely honored).\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
@@ -103,14 +114,58 @@ export async function runPw(argv, deps = {}) {
 // while-loop in runPwInner). Everything after the first non-option (the lane) is a
 // Playwright workload argument and is never a BotBuddy credential.
 const PW_LEADING_FLAGS = ["--tenant", "--session-id", "--agent-session-token", "--agent-key", "--session-token"];
+const selfHealErrorLine = (error) => `bb-pw: ${error?.message ?? "agent session unavailable"}. ${error?.code === "client_key_required" ? "Run `bb login` then retry." : "Run `bb doctor --fix` then retry."}\n`;
+// The leading credential options, NORMALIZED to split `flag value` pairs so an
+// inline `--agent-key=<token>` is recognized by legacyAgentAliasHint (which
+// matches exact flag tokens) exactly like the split form. Credential flags are
+// only accepted BEFORE the lane (BOT-1682 P1: `--tenant` after the lane cannot be
+// safely honored for session/lane auth and is refused, see planInvocation), so
+// this leading scan is the whole surface the alias hint needs to consider.
 function leadingPwOptions(args) {
   const lead = [];
-  for (let i = 0; i < args.length && PW_LEADING_FLAGS.includes(args[i]); i += 2) {
-    lead.push(args[i]);
-    if (i + 1 < args.length) lead.push(args[i + 1]);
+  let rest = [...args];
+  let match;
+  while ((match = matchWrapperFlag(rest[0]))) {
+    lead.push(match.flag);
+    if (match.inline !== null) { lead.push(match.inline); rest = rest.slice(1); }
+    else { if (rest[1] === undefined) break; lead.push(rest[1]); rest = rest.slice(2); }
   }
   return lead;
 }
+// BOT-1682: match a leading credential flag in either `--flag value` or
+// `--flag=value` form. Returns the base flag + its inline value (null when the
+// value is the NEXT token), or null when the token is not a credential flag.
+function matchWrapperFlag(token) {
+  for (const flag of PW_LEADING_FLAGS) {
+    if (token === flag) return { flag, inline: null };
+    if (typeof token === "string" && token.startsWith(`${flag}=`)) return { flag, inline: token.slice(flag.length + 1) };
+  }
+  return null;
+}
+const applyWrapperFlag = (deps, flag, value) => flag === "--tenant"
+  ? { ...deps, tenant: value }
+  : ["--agent-session-token", "--agent-key", "--session-token"].includes(flag)
+    ? { ...deps, sessionToken: value }
+    : { ...deps, sessionId: value };
+// Consume a run of credential flags from `list` starting at `start`, folding each
+// into deps. Returns { deps, rest } on success, or { error: flag } when a flag
+// has no value. `rest` is the tokens after the consumed run.
+function consumeWrapperFlags(list, deps, start = 0) {
+  let rest = list.slice(start);
+  let match;
+  while ((match = matchWrapperFlag(rest[0]))) {
+    let value;
+    if (match.inline !== null) { value = match.inline; rest = rest.slice(1); }
+    else { if (rest[1] === undefined) return { error: match.flag }; value = rest[1]; rest = rest.slice(2); }
+    // An empty value (`--flag=` or `--flag ""`) is a usage error, not a silent
+    // no-op: an empty session token would make `!deps.sessionToken` true and fall
+    // back to another credential, executing under a different identity (Codex P2).
+    // Matches the old `if (!args[1])` guard this helper replaced.
+    if (value === "") return { error: match.flag };
+    deps = applyWrapperFlag(deps, match.flag, value);
+  }
+  return { deps, rest };
+}
 
 async function runPwInner(argv, deps = {}) {
   const env = deps.env ?? process.env, stdout = deps.stdout ?? process.stdout, stderr = deps.stderr ?? process.stderr; let args = [...argv]; if (["--help", "-h"].includes(args[0])) { help(stdout); return 0; }
@@ -126,7 +181,14 @@ async function runPwInner(argv, deps = {}) {
   // session identity alongside --session-id, so a token-armed session need not
   // pass an id. Holder matching still rides on the server's owner_is_caller and
   // the resolved agent ids (gate()).
-  while (["--tenant", "--session-id", "--agent-session-token", "--agent-key", "--session-token"].includes(args[0])) { const flag = args[0]; if (!args[1]) { stderr.write(`bb-pw: ${flag} needs a value\n`); return 2; } deps = flag === "--tenant" ? { ...deps, tenant: args[1] } : ["--agent-session-token", "--agent-key", "--session-token"].includes(flag) ? { ...deps, sessionToken: args[1] } : { ...deps, sessionId: args[1] }; args = args.slice(2); }
+  // Credential flags are accepted ONLY as LEADING options (before the lane). A
+  // `--tenant` after the lane cannot be safely honored — bb pw would authenticate
+  // with the resolved session/key regardless of the named tenant, so a tenant B
+  // request could run under tenant A's cached session (Codex P1). Anything
+  // credential-flag-shaped still present once we reach the verb is refused by
+  // planInvocation with guidance to move it before the lane; a real, server-pinned
+  // `--tenant` lane fallback is BOT-1732.
+  { const consumed = consumeWrapperFlags(args, deps, 0); if (consumed.error) { stderr.write(`bb-pw: ${consumed.error} needs a value\n`); return 2; } deps = consumed.deps; args = consumed.rest; }
   let plan; try { plan = planInvocation(args, env); } catch (error) { stderr.write(`${error.message}\n`); return 2; }
   const { spawnExec, socketRun } = deps.daemon ?? await import("./daemon.mjs");
   if (plan.scope === "global") { if (plan.mode === "reap") { await (deps.reap ?? (await import("./reap.mjs")).reap)({ env, stdout }); return 0; } if (env.BB_PW_NO_LOCK !== "1") { stderr.write("bb-pw: close-all and kill-all require BB_PW_NO_LOCK=1 because they can affect lanes you do not own.\n"); return 3; } return spawnExec(plan, env); }
@@ -135,12 +197,11 @@ async function runPwInner(argv, deps = {}) {
   let managedCredential = null;
   if (env.BB_PW_NO_LOCK !== "1" && !deps.sessionToken && !readAgentSessionTokenEnv(env) && (!deps.coordinator || deps.resolveCredential)) {
     try {
-      const credential = await (deps.resolveCredential ?? resolveAgentSessionCredential)({ argv, env, cwd: deps.cwd ?? process.cwd() });
+      const credential = await (deps.resolveCredential ?? resolveAgentSessionCredential)({ argv, env, cwd: deps.cwd ?? process.cwd(), sessionId: deps.sessionId ?? env.BOTBUDDY_SESSION_ID ?? null, flagToken: null });
       managedCredential = credential;
       deps = { ...deps, sessionToken: credential.token, sessionId: deps.sessionId ?? credential.sessionId ?? null };
     } catch (error) {
-      stderr.write(`bb-pw: ${error?.message ?? "agent session unavailable"}. ${error?.code === "client_key_required" ? "Run `bb login` then retry." : "Run `bb doctor --fix` then retry."}\n`);
-      return 3;
+      stderr.write(selfHealErrorLine(error)); return 3;
     }
   }
   const telemetry = deps.telemetry ?? (await import("./telemetry.mjs")).makeTelemetry({ env }); const host = deps.host ?? hostFor(env);
@@ -150,9 +211,17 @@ async function runPwInner(argv, deps = {}) {
   // allowed:false with NO errorCode and must never rotate the session (Codex round-5).
   if (!auth.allowed && !deps.coordinator && auth.errorCode != null && isRejectedCachedMcpSession({ auth: true, code: auth.errorCode }, managedCredential?.source, 0)) {
     await clearAgentState(deps.cwd ?? process.cwd());
-    const credential = await (deps.resolveCredential ?? resolveAgentSessionCredential)({ argv, env, cwd: deps.cwd ?? process.cwd() });
-    managedCredential = credential;
-    deps = { ...deps, sessionToken: credential.token, sessionId: credential.sessionId ?? deps.sessionId ?? null };
+    try {
+      const credential = await (deps.resolveCredential ?? resolveAgentSessionCredential)({ argv, env, cwd: deps.cwd ?? process.cwd(), sessionId: deps.sessionId ?? env.BOTBUDDY_SESSION_ID ?? null, flagToken: null });
+      managedCredential = credential;
+      // Keep an explicit --session-id holder authoritative over the freshly minted
+      // one, same precedence as the initial resolution (Codex).
+      deps = { ...deps, sessionToken: credential.token, sessionId: deps.sessionId ?? credential.sessionId ?? null };
+    } catch (error) {
+      // BOT-1682: the renewal after a revoked cache can also fail self-heal; fail
+      // closed with a clear message rather than letting the error escape to exit 1.
+      stderr.write(selfHealErrorLine(error)); return 3;
+    }
     auth = await gate({ env, host, lane: plan.lane, deps });
   }
   if (!auth.allowed) { stderr.write(`${auth.message}\n`); return 3; }
@@ -161,7 +230,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 ?? ""));