@botbuddy/cli 1.5.4 → 1.6.0

package/bin/bb-pw.mjs

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+import { runPw } from "../src/pw/run.mjs";
+
+runPw(process.argv.slice(2)).then((code) => process.exit(code)).catch((error) => {
+  console.error(`bb-pw: ${error?.message ?? error}`);
+  process.exit(1);
+});

package/bin/botbuddy.mjs

@@ -1,7 +1,9 @@
 #!/usr/bin/env node
 import { run } from "../src/commands.mjs";
 
-run(process.argv.slice(2)).catch((err) => {
+run(process.argv.slice(2)).then((code) => {
+  if (typeof code === "number") process.exitCode = code;
+}).catch((err) => {
   console.error(`\x1b[31m✗\x1b[0m ${err?.message || err}`);
   process.exit(1);
 });

package/package.json

@@ -1,10 +1,11 @@
 {
   "name": "@botbuddy/cli",
-  "version": "1.5.4",
+  "version": "1.6.0",
   "description": "BotBuddy — Swarm coordination CLI for multi-agent workflows",
   "type": "module",
   "bin": {
-    "botbuddy": "./bin/botbuddy.mjs"
+    "botbuddy": "./bin/botbuddy.mjs",
+    "bb-pw": "./bin/bb-pw.mjs"
   },
   "files": [
     "bin/",
@@ -20,9 +21,13 @@
   ],
   "license": "MIT",
   "engines": {
-    "node": ">=18.0.0"
+    "node": ">=20.0.0"
   },
   "publishConfig": {
     "access": "public"
+  },
+  "dependencies": {
+    "@playwright/cli": "0.1.17",
+    "playwright": "1.62.0-alpha-1783623505000"
   }
 }

package/src/commands.mjs

@@ -11,6 +11,7 @@ import { runWait } from "./wait.mjs";
 import { green, red, cyan, dim, bold, die } from "./utils.mjs";
 import { VERSION } from "./version.mjs";
 import { bootstrapProfile, ProfileBootstrapError, profileShellRefresh } from "./profile-bootstrap.mjs";
+import { runPw } from "./pw/run.mjs";
 
 export async function run(argv) {
   loadConfig();
@@ -32,6 +33,7 @@ export async function run(argv) {
     case "docker": return cmdDocker(args);
     case "run": return cmdRun(args);
     case "wait": return runWait(args);
+    case "pw": return runPw(args);
     case "profile": return cmdProfile(args);
     case "resources": return callTool("list_resources");
     case "agents": return callTool("list_agents");
@@ -101,6 +103,10 @@ ${bold("AGENT WAITS")}
   wait [--any] <condition>... [options]
                               Wait once for a pushed BotBuddy signal
 
+${bold("BROWSER LANES")}
+  pw <lane> <verb> [args…]    Drive a lock-gated Playwright lane
+  pw --help                   Show bb-pw-compatible lane usage
+
 ${bold("OTHER")}
   locks -m [--host name]    Reserve typed local resources, including Playwright MCP lanes
   help                       Show this help

package/src/docker-hygiene.mjs

@@ -78,6 +78,11 @@ SAFETY
   • Re-inspects every candidate immediately before deletion.
   • Never force-removes a resource, never runs a prune command, and never removes volumes.
 
+PERSISTENT ORBSTACK GHOSTS
+  If an exact ID remains listed but OrbStack cannot inspect it, inventory is
+  reported but cleanup refuses. Restart or repair OrbStack, then rerun the
+  hygiene dry run with the same explicit selector. Never use broad cleanup.
+
 EXAMPLES
   botbuddy docker hygiene --context orbstack --ticket BOT-1405 --json
   botbuddy docker hygiene --context orbstack --apply --ticket BOT-1405 \\
@@ -327,18 +332,143 @@ function nonEmptyLines(text) {
   return text.split(/\r?\n/).map((value) => value.trim()).filter(Boolean);
 }
 
-function inspectInBatches(runDocker, selector, kind, ids, extraArgs = []) {
+function boundedDockerError(value) {
+  return String(value || "Docker command failed").trim().replace(/\s+/g, " ").slice(0, 500);
+}
+
+function listInventoryRefs(runDocker, selector, kind, exactId = null) {
+  const args = [kind, "ls"];
+  if (kind === "container") args.push("--all");
+  args.push("--no-trunc");
+  if (kind === "container" && !exactId) args.push("--filter", "name=supabase_");
+  if (exactId) args.push("--filter", `id=${exactId}`);
+  args.push("--format", kind === "container" ? "{{.ID}}\t{{.Names}}" : "{{.ID}}\t{{.Name}}");
+
+  const refs = nonEmptyLines(selected(runDocker, selector, args)).map((line) => {
+    const [rawId, ...rawName] = line.split("\t");
+    const id = rawId.trim();
+    if (!id) throw new Error(`Docker ${kind} inventory returned an empty ID`);
+    return { id, name: rawName.join("\t").trim() };
+  });
+  const exact = exactId ? refs.filter((ref) => ref.id === exactId) : refs;
+  return [...new Map(exact.map((ref) => [ref.id, ref])).values()];
+}
+
+function inspectAttempt(runDocker, selector, kind, refs, extraArgs) {
+  const ids = refs.map((ref) => ref.id);
+  const args = [...selector, kind, "inspect", ...extraArgs, ...ids];
+  const result = runDocker(args);
+  if (result?.error || result?.status !== 0) {
+    return { ok: false, resources: [], error: commandFailure(args, result).message };
+  }
+
+  let inspected;
+  try {
+    inspected = JSON.parse(String(result.stdout || ""));
+  } catch {
+    return { ok: false, resources: [], error: `docker ${kind} inspect returned malformed JSON` };
+  }
+  if (!Array.isArray(inspected)) {
+    return { ok: false, resources: [], error: `Docker ${kind} inventory returned an unexpected shape` };
+  }
+  return { ok: true, resources: inspected, error: null };
+}
+
+function exactInspectedResource(attempt, id) {
+  if (!attempt.ok || attempt.resources.length !== 1) return null;
+  return String(attempt.resources[0]?.Id || "") === id ? attempt.resources[0] : null;
+}
+
+function exactInspectError(attempt, kind, id) {
+  if (!attempt.ok) return attempt.error;
+  return `docker ${kind} inspect did not return the exact requested ID ${id}`;
+}
+
+function inspectInBatches(runDocker, selector, kind, refs, extraArgs = []) {
   const resources = [];
-  for (let offset = 0; offset < ids.length; offset += INSPECT_BATCH_SIZE) {
-    const batch = ids.slice(offset, offset + INSPECT_BATCH_SIZE);
-    const inspected = parseJson(
-      selected(runDocker, selector, [kind, "inspect", ...extraArgs, ...batch]),
-      `docker ${kind} inspect`,
-    );
-    if (!Array.isArray(inspected)) throw new Error(`Docker ${kind} inventory returned an unexpected shape`);
-    resources.push(...inspected);
+  const skipped = [];
+  const errors = [];
+  for (let offset = 0; offset < refs.length; offset += INSPECT_BATCH_SIZE) {
+    const batch = refs.slice(offset, offset + INSPECT_BATCH_SIZE);
+    const attempt = inspectAttempt(runDocker, selector, kind, batch, extraArgs);
+    let isolate = batch;
+
+    if (attempt.ok) {
+      const byId = new Map();
+      let invalidIdentity = false;
+      for (const resource of attempt.resources) {
+        const id = String(resource?.Id || "");
+        if (!id || byId.has(id) || !batch.some((ref) => ref.id === id)) {
+          invalidIdentity = true;
+          break;
+        }
+        byId.set(id, resource);
+      }
+      if (!invalidIdentity) {
+        for (const ref of batch) {
+          const resource = byId.get(ref.id);
+          if (resource) resources.push(resource);
+        }
+        isolate = batch.filter((ref) => !byId.has(ref.id));
+      }
+    }
+
+    for (const ref of isolate) {
+      const isolated = inspectAttempt(runDocker, selector, kind, [ref], extraArgs);
+      const isolatedResource = exactInspectedResource(isolated, ref.id);
+      if (isolatedResource) {
+        resources.push(isolatedResource);
+        continue;
+      }
+
+      // Re-list through the same validated selector and require exact full-ID
+      // equality. A prefix match or same-name replacement is never authority.
+      const relisted = listInventoryRefs(runDocker, selector, kind, ref.id);
+      const current = relisted.find((item) => item.id === ref.id);
+      if (!current) {
+        skipped.push({
+          type: kind,
+          id: ref.id,
+          name: ref.name,
+          project: null,
+          reason: "disappeared_during_inventory",
+        });
+        continue;
+      }
+
+      const retried = inspectAttempt(runDocker, selector, kind, [current], extraArgs);
+      const retriedResource = exactInspectedResource(retried, ref.id);
+      if (retriedResource) {
+        resources.push(retriedResource);
+        continue;
+      }
+      // The row can disappear after the first exact re-list but before the
+      // retry returns. Confirm it still exists before calling the engine state
+      // persistently uninspectable; daemon/list failures still throw closed.
+      const finalRelisted = listInventoryRefs(runDocker, selector, kind, ref.id);
+      const finalCurrent = finalRelisted.find((item) => item.id === ref.id);
+      if (!finalCurrent) {
+        skipped.push({
+          type: kind,
+          id: ref.id,
+          name: current.name || ref.name,
+          project: null,
+          reason: "disappeared_during_inventory",
+        });
+        continue;
+      }
+      errors.push({
+        type: kind,
+        id: ref.id,
+        name: finalCurrent.name || current.name || ref.name,
+        project: null,
+        reason: "uninspectable_during_inventory",
+        error: boundedDockerError(exactInspectError(retried, kind, ref.id)
+          || exactInspectError(isolated, kind, ref.id)),
+      });
+    }
   }
-  return resources;
+  return { resources, skipped, errors };
 }
 
 function projectIdentity(resource) {
@@ -403,7 +533,7 @@ function skippedResource(type, resource, reason, extra = {}) {
   };
 }
 
-export function classifyInventory({ containers = [], networks = [] } = {}) {
+export function classifyInventory({ containers = [], networks = [], skipped: discoverySkipped = [], errors = [], listed = {} } = {}) {
   const activeProjects = new Set();
   for (const resource of containers) {
     const name = containerName(resource);
@@ -412,7 +542,7 @@ export function classifyInventory({ containers = [], networks = [] } = {}) {
   }
 
   const candidates = [];
-  const skipped = [];
+  const skipped = [...discoverySkipped];
   let supabaseContainers = 0;
 
   for (const resource of containers) {
@@ -490,9 +620,12 @@ export function classifyInventory({ containers = [], networks = [] } = {}) {
     active_projects: [...activeProjects].sort(),
     candidates: candidates.sort(resourceSort),
     skipped: skipped.sort(resourceSort),
+    inventory_errors: [...errors].sort(resourceSort),
     counts: {
       containers: containers.length,
       networks: networks.length,
+      listed_containers: listed.containers ?? containers.length,
+      listed_networks: listed.networks ?? networks.length,
       supabase_containers: supabaseContainers,
       supabase_networks: supabaseNetworks,
       user_bridge_networks: userBridgeNetworks,
@@ -502,15 +635,21 @@ export function classifyInventory({ containers = [], networks = [] } = {}) {
 }
 
 function readInventory(runDocker, selector) {
-  const containerIds = nonEmptyLines(selected(runDocker, selector, ["container", "ls", "--all", "--quiet", "--no-trunc", "--filter", "name=supabase_"]));
-  const containers = containerIds.length
-    ? inspectInBatches(runDocker, selector, "container", containerIds, ["--size"])
-    : [];
-  const networkIds = nonEmptyLines(selected(runDocker, selector, ["network", "ls", "--quiet", "--no-trunc"]));
-  const networks = networkIds.length
-    ? inspectInBatches(runDocker, selector, "network", networkIds)
-    : [];
-  return { containers, networks };
+  const containerRefs = listInventoryRefs(runDocker, selector, "container");
+  const containerResult = containerRefs.length
+    ? inspectInBatches(runDocker, selector, "container", containerRefs, ["--size"])
+    : { resources: [], skipped: [], errors: [] };
+  const networkRefs = listInventoryRefs(runDocker, selector, "network");
+  const networkResult = networkRefs.length
+    ? inspectInBatches(runDocker, selector, "network", networkRefs)
+    : { resources: [], skipped: [], errors: [] };
+  return {
+    containers: containerResult.resources,
+    networks: networkResult.resources,
+    skipped: [...containerResult.skipped, ...networkResult.skipped],
+    errors: [...containerResult.errors, ...networkResult.errors],
+    listed: { containers: containerRefs.length, networks: networkRefs.length },
+  };
 }
 
 function validateOrbStack(runDocker, opts) {
@@ -596,6 +735,7 @@ function baseReceipt(command, opts, now) {
     deleted: [],
     reclaimed_space_bytes: 0,
     skipped: [],
+    inventory_errors: [],
     pressure: null,
     warnings: [],
     errors: [],
@@ -698,6 +838,7 @@ export function runDockerWorkflow(argv, {
   receipt.inventory = inventory.counts;
   receipt.active_projects = inventory.active_projects;
   receipt.skipped = [...inventory.skipped];
+  receipt.inventory_errors = [...inventory.inventory_errors];
 
   const ticketCandidates = parsed.opts.ticket
     ? inventory.candidates.filter((item) => projectMatchesTicket(item.project, parsed.opts.ticket))
@@ -712,6 +853,15 @@ export function runDockerWorkflow(argv, {
   receipt.candidates = ticketCandidates;
   receipt.candidate_reclaimable_bytes = ticketCandidates.reduce((total, item) => total + item.reclaimable_bytes, 0);
 
+  if (receipt.inventory_errors.length > 0) {
+    receipt.outcome = "refused";
+    for (const item of receipt.inventory_errors) {
+      receipt.errors.push(`${item.type} ${item.id}${item.name ? ` (${item.name})` : ""} remains listed but cannot be authoritatively inspected: ${item.error}`);
+    }
+    receipt.recommendation = "Persistent OrbStack inventory blocker: restart or repair OrbStack, then rerun the hygiene dry run with the same explicit selector; never use broad cleanup.";
+    return { exitCode: EXIT.DOCKER, receipt, json: parsed.opts.json };
+  }
+
   if (parsed.command === "preflight") {
     receipt.pressure = evaluatePressure({
       bridgeNetworks: inventory.counts.user_bridge_networks,
@@ -769,6 +919,17 @@ export function runDockerWorkflow(argv, {
       addSkipOnce(receipt, { ...candidate, reason: "revalidation_failed" });
       continue;
     }
+    if (fresh.inventory_errors.length > 0) {
+      for (const item of fresh.inventory_errors) {
+        if (!receipt.inventory_errors.some((existing) => existing.type === item.type && existing.id === item.id)) {
+          receipt.inventory_errors.push(item);
+          receipt.errors.push(`revalidation blocked by ${item.type} ${item.id}${item.name ? ` (${item.name})` : ""}: ${item.error}`);
+        }
+      }
+      receipt.recommendation = "Persistent OrbStack inventory blocker: restart or repair OrbStack, then rerun the hygiene dry run with the same explicit selector; never use broad cleanup.";
+      addSkipOnce(receipt, { ...candidate, reason: "revalidation_failed" });
+      continue;
+    }
     const revalidated = fresh.candidates.find((item) => item.type === candidate.type
       && item.id === candidate.id
       && projectMatchesTicket(item.project, parsed.opts.ticket));
@@ -855,6 +1016,11 @@ export function formatHumanReceipt(receipt) {
   lines.push(`Skipped (${receipt.skipped.length}):`);
   for (const item of receipt.skipped) lines.push(`  ${item.type} ${item.id} ${item.name} — ${item.reason}`);
   if (receipt.skipped.length === 0) lines.push("  none");
+  lines.push(`Inventory errors (${receipt.inventory_errors?.length || 0}):`);
+  for (const item of receipt.inventory_errors || []) {
+    lines.push(`  ${item.type} ${item.id} ${item.name || "(name unknown)"} — ${item.reason}: ${item.error}`);
+  }
+  if (!receipt.inventory_errors?.length) lines.push("  none");
   if (receipt.pressure) {
     lines.push(`Pressure: ${receipt.pressure.projected_pressure_units} projected (${receipt.pressure.status}; warn ${receipt.pressure.warn_pressure}, fail ${receipt.pressure.fail_pressure})`);
   }

package/src/pw/args.mjs

@@ -0,0 +1,28 @@
+import { TARGET_VERBS, parseTargetFlags, hasTargetFlags, buildLocatorTarget, classifyTarget, isSnapshotRef } from "./targets.mjs";
+export const GLOBAL_VERBS = new Set(["list", "close-all", "kill-all", "reap"]);
+const secret = /^@ENV:(.+)$/;
+export function resolveRef(value, env = process.env) {
+  const match = secret.exec(String(value));
+  if (!match) return { value, secret: false };
+  if (!env[match[1]]) throw new Error(`bb-pw: env var ${match[1]} referenced by ${value} is not set`);
+  return { value: env[match[1]], ref: value, secret: true };
+}
+export const normaliseLane = (token) => String(token).replace(/^agent-0*/, "").replace(/^lane-/, "");
+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 };
+  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" };
+  const rest = argv.slice(2); let forwarded = rest, target = null, fresh = false;
+  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");
+  }
+  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/coordinator.mjs

@@ -0,0 +1,12 @@
+import { SERVER_URL } from "../config.mjs";
+export function createProfileCoordinator({ profile, identity, fetchImpl = fetch } = {}) {
+  if (!profile?.token || !identity?.agentId || identity.tenant !== profile.tenant) return { kind: "unverified" };
+  let id = 0;
+  async function call(name, args) {
+    const response = await fetchImpl(SERVER_URL, { method: "POST", headers: { "content-type": "application/json", "x-agent-api-key": profile.token }, body: JSON.stringify({ jsonrpc: "2.0", id: ++id, method: "tools/call", params: { name, arguments: args } }) });
+    if (!response.ok) throw new Error(`BotBuddy lock verification returned HTTP ${response.status}`);
+    const json = await response.json(); if (json.error) throw new Error(json.error.message || "BotBuddy lock verification failed");
+    const text = json.result?.content?.find((item) => item.type === "text")?.text; try { return text ? JSON.parse(text) : {}; } catch { throw new Error("BotBuddy lock verification returned invalid JSON"); }
+  }
+  return { kind: "profile", async status({ host, slot }) { const result = await call("list_resources", { host, subtype: "playwright_lane" }); const list = Array.isArray(result) ? result : result.resources ?? []; const resource = list.find((item) => item.name === `playwright_lane:${host}:${slot}` || String(item.slot) === String(slot)); return resource ? { held: resource.status !== "free", heldBy: resource.owner_agent_id ?? null } : { held: false, heldBy: null }; }, async emit(event) { await call("record_lane_event", event); }, agentId: identity.agentId };
+}

package/src/pw/daemon.mjs

@@ -0,0 +1,13 @@
+import { spawn } from "node:child_process";
+import net from "node:net";
+import { createRequire } from "node:module";
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { homedir } from "node:os";
+export const daemonDir = (env = process.env) => env.BB_PW_DAEMON_DIR || join(homedir(), ".botbuddy", "pw-daemon");
+export function resolveCliBin(env = process.env) { if (env.BB_PW_CLI_BIN) return { cmd: "node", args: [env.BB_PW_CLI_BIN] }; const require = createRequire(import.meta.url); const pkg = require.resolve("@playwright/cli/package.json"), meta = JSON.parse(readFileSync(pkg, "utf8")), bin = typeof meta.bin === "string" ? meta.bin : meta.bin["playwright-cli"] || Object.values(meta.bin)[0]; return { cmd: "node", args: [join(dirname(pkg), bin)] }; }
+export function spawnExec(plan, env = process.env) { const { cmd, args } = resolveCliBin(env); return new Promise((resolve) => { const child = spawn(cmd, [...args, ...plan.execArgv], { stdio: "inherit", env: { ...env, PWTEST_DAEMON_SESSION_DIR: daemonDir(env) } }); child.on("exit", (code) => resolve(code ?? 1)); child.on("error", () => resolve(127)); }); }
+export function readSession(session, env = process.env) { const root = daemonDir(env); if (!existsSync(root)) return null; for (const item of readdirSync(root)) { try { return JSON.parse(readFileSync(join(root, item, `${session}.session`), "utf8")); } catch {} } return null; }
+export function sendToDaemon(socketPath, positional, { connect = net.createConnection, cwd = process.cwd(), timeoutMs = 30000 } = {}) { return new Promise((resolve) => { let done = false, buffer = "", socket; const finish = (value) => { if (!done) { done = true; socket?.destroy(); resolve(value); } }; socket = connect(socketPath, () => socket.write(JSON.stringify({ id: 1, method: "run", params: { args: { _: positional }, cwd } }) + "\n")); socket.on("data", (data) => { buffer += String(data); const newline = buffer.indexOf("\n"); if (newline < 0) return; try { const reply = JSON.parse(buffer.slice(0, newline)), text = reply.result?.text ?? ""; finish(reply.error || /^### Error\b/m.test(text) ? { ok: false, error: reply.error?.message ?? reply.error ?? text } : { ok: true, text }); } catch { finish({ ok: false, error: "bb-pw: malformed daemon reply" }); } }); socket.on("error", (error) => finish({ ok: false, error: error.message })); setTimeout(() => finish({ ok: false, error: "bb-pw: daemon socket timeout" }), timeoutMs).unref(); }); }
+export function socketAlive(socketPath, { connect = net.createConnection, timeoutMs = 1000 } = {}) { return new Promise((resolve) => { if (!socketPath) return resolve(false); let done = false, socket; const finish = (value) => { if (!done) { done = true; socket?.destroy(); resolve(value); } }; socket = connect(socketPath, () => finish(true)); socket.on("error", () => finish(false)); setTimeout(() => finish(false), timeoutMs).unref(); }); }
+export async function socketRun(plan, env = process.env) { const session = readSession(plan.session, env); return session?.socketPath ? sendToDaemon(session.socketPath, plan.socketArgs) : { ok: false, error: `bb-pw: no open daemon for ${plan.session}; open it first` }; }

package/src/pw/readiness.mjs

@@ -0,0 +1,4 @@
+export const NAV = "navigate";
+const interaction = new Set(["click", "fill", "type", "select", "press", "drag", "hover", "dblclick", "check", "uncheck"]);
+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/reap.mjs

@@ -0,0 +1,5 @@
+import { execSync } from "node:child_process";
+import { readSession, socketAlive } from "./daemon.mjs";
+export const parsePs = (text) => String(text).split("\n").map((line) => line.trim().match(/^(\d+)\s+(\d+)\s+(.*)$/)).filter(Boolean).map(([, pid, ppid, command]) => ({ pid: Number(pid), ppid: Number(ppid), command }));
+export const selectCliDaemons = (list) => list.flatMap((row) => { const found = /cliDaemon\.js\s+(\S+)/.exec(row.command); return found ? [{ ...row, lane: found[1] }] : []; });
+export async function reap({ env = process.env, stdout = process.stdout, exec = execSync, alive = socketAlive, kill = (pid) => { try { process.kill(pid, "SIGKILL"); } catch {} } } = {}) { const processes = selectCliDaemons(parsePs(exec("ps -axw -o pid=,ppid=,command=").toString())), stale = []; for (const daemon of processes) { if (!await alive(readSession(daemon.lane, env)?.socketPath)) { stale.push(daemon.pid); kill(daemon.pid); } } stdout.write(`bb-pw reap: ${stale.length} stale daemon(s) reaped${stale.length ? ` (${stale.join(",")})` : ""}\n`); return stale; }

package/src/pw/run.mjs

@@ -0,0 +1,24 @@
+import os from "node:os";
+import { planInvocation } from "./args.mjs";
+import { actionTypeFromMethod, NAV } from "./readiness.mjs";
+import { isStaleRefError, staleRefRemediation } from "./targets.mjs";
+import { createProfileCoordinator } from "./coordinator.mjs";
+import { resolveAgentProfile } from "../wait-profile.mjs";
+import { readProfileIdentity } from "../agent-credential-store.mjs";
+const hostFor = (env) => env.PLAYWRIGHT_MCP_HOST || env.HOSTNAME || os.hostname();
+function help(out) { out.write("Usage: botbuddy pw [--profile <name>] <lane> <verb> [args…]\n\nAlias: bb-pw <lane> <verb> [args…]\n"); }
+function redact(value, secretValues = []) { return secretValues.reduce((text, secret) => secret ? text.split(secret).join("[redacted]") : text, String(value ?? "")); }
+async function gate({ env, host, lane, deps }) { if (env.BB_PW_NO_LOCK === "1") return { allowed: true }; let profile, identity; try { profile = await (deps.resolveProfile ?? resolveAgentProfile)({ cwd: deps.cwd ?? process.cwd(), env, explicitProfile: deps.profile ?? null }); identity = await (deps.readIdentity ?? readProfileIdentity)(profile.name); } catch (error) { return { allowed: false, message: `bb-pw: profile verification failed (${error.message}). Run botbuddy profile setup or set BB_PW_NO_LOCK=1 for local-only work.` }; } const coordinator = deps.coordinator ?? createProfileCoordinator({ profile, identity, fetchImpl: deps.fetch }); if (!profile.token || !identity || identity.tenant !== profile.tenant || coordinator.kind !== "profile") return { allowed: false, message: "bb-pw: profile identity is missing or tenant-mismatched. Run botbuddy profile setup or set BB_PW_NO_LOCK=1 for local-only work." }; try { const status = await coordinator.status({ host, slot: lane }); return status.held && status.heldBy === identity.agentId ? { allowed: true, coordinator } : { allowed: false, message: `bb-pw: lane lock playwright_lane:${host}:${lane} must be held by this profile. Acquire it first or set BB_PW_NO_LOCK=1 for local-only work.` }; } catch (error) { return { allowed: false, message: `bb-pw: could not verify lane lock (${error.message}). Set BB_PW_NO_LOCK=1 for local-only work.` }; } }
+export async function runPw(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; } if (args[0] === "--profile") { if (!args[1]) { stderr.write("bb-pw: --profile needs a name\n"); return 2; } deps = { ...deps, profile: args[1] }; args = args.slice(2); }
+  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); }
+  const telemetry = deps.telemetry ?? (await import("./telemetry.mjs")).makeTelemetry({ env }); const host = deps.host ?? hostFor(env);
+  const auth = await gate({ env, host, lane: plan.lane, deps }); if (!auth.allowed) { stderr.write(`${auth.message}\n`); return 3; }
+  if (plan.mode === "status") { const lock = auth.coordinator?.status ? await auth.coordinator.status({ host, slot: plan.lane }) : null; stdout.write(JSON.stringify({ lane: plan.lane, session: plan.session, host, 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);
+  if (plan.rollup && code === 0) await telemetry.rollup({ lane: plan.lane, coordinator: auth.coordinator, host }); return code;
+}

package/src/pw/targets.mjs

@@ -0,0 +1,37 @@
+const REF = /^(f\d+)?e\d+$/;
+export const TARGET_VERBS = new Set(["click", "dblclick", "fill", "hover", "check", "uncheck", "select"]);
+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, "\\'")}'`;
+export function parseTargetFlags(args) {
+  const flags = {}, rest = []; let fresh = false;
+  for (let index = 0; index < args.length; index += 1) {
+    const match = /^--([a-z]+)(?:=(.*))?$/s.exec(String(args[index]));
+    if (!match) { rest.push(args[index]); continue; }
+    const [, name, inline] = match;
+    if (name === "fresh") { fresh = true; continue; }
+    if (name === "exact") { flags.exact = true; continue; }
+    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`);
+    flags[name] = value;
+  }
+  return { flags, rest, fresh };
+}
+export const hasTargetFlags = (flags) => Object.keys(flags).some((key) => key !== "exact");
+function exact(method, value, enabled) { return enabled ? `${method}(${quote(value)}, { exact: true })` : `${method}(${quote(value)})`; }
+export function buildLocatorTarget(flags) {
+  const bases = BASE.filter((name) => flags[name] !== undefined);
+  if (flags.name !== undefined && flags.role === undefined) throw new Error("bb-pw: --name qualifies --role; pass --role too");
+  if (bases.length !== 1) throw new Error(`bb-pw: give exactly one base locator, got: ${bases.map((name) => `--${name}`).join(", ") || "none"}`);
+  const base = bases[0], isExact = flags.exact === true;
+  if (base === "role") {
+    const opts = flags.name === undefined ? "" : `, { name: ${quote(flags.name)}${isExact ? ", exact: true" : ""} }`;
+    return `getByRole(${quote(flags.role)}${opts})`;
+  }
+  if (base === "testid") return `getByTestId(${quote(flags.testid)})`;
+  return exact({ placeholder: "getByPlaceholder", text: "getByText", label: "getByLabel", title: "getByTitle", alt: "getByAltText" }[base], flags[base], isExact);
+}
+export const isStaleRefError = (text) => /not found in the current page snapshot/i.test(String(text ?? ""));
+export const staleRefRemediation = (ref) => `bb-pw: snapshot ref ${ref} is stale — capture a new snapshot or use a stable locator (--role, --text, --testid)${""}.`;

package/src/pw/telemetry.mjs

@@ -0,0 +1,14 @@
+import { appendFileSync, existsSync, mkdirSync, readFileSync, rmSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { deriveSession } from "./readiness.mjs";
+const spoolDir = (env) => env.BB_PW_SPOOL_DIR || join(homedir(), ".botbuddy", "pw-spool");
+export function makeTelemetry({ env = process.env } = {}) {
+  const path = (lane) => join(spoolDir(env), `lane-${lane}.jsonl`);
+  const readEvents = (lane) => existsSync(path(lane)) ? readFileSync(path(lane), "utf8").split("\n").filter(Boolean).flatMap((line) => { try { return [JSON.parse(line)]; } catch { return []; } }) : [];
+  return {
+    append(lane, event) { mkdirSync(spoolDir(env), { recursive: true }); appendFileSync(path(lane), JSON.stringify({ ts: event.ts, method: event.method, url: event.url ?? null }) + "\n"); },
+    count(lane) { return readEvents(lane).length; },
+    async rollup({ lane, coordinator, host }) { const events = readEvents(lane); if (!events.length) return { emitted: false, count: 0 }; const session = deriveSession(events, { meta: { host, slot: String(lane), ticket_id: env.BB_PW_TICKET_ID, ticket_url: env.BB_PW_TICKET_URL, pr_id: env.BB_PW_PR_ID, pr_url: env.BB_PW_PR_URL, branch: env.BB_PW_BRANCH, commit_sha: env.BB_PW_COMMIT, environment: env.BB_PW_ENV } }); const event = { ...session, started_at: new Date(session.started_at).toISOString(), ended_at: new Date(session.ended_at).toISOString(), ended_reason: "close" }; try { if (!coordinator?.emit) return { emitted: false, count: events.length, session: event }; await coordinator.emit(event); rmSync(path(lane), { force: true }); return { emitted: true, count: events.length, session: event }; } catch { return { emitted: false, count: events.length, session: event }; } },
+  };
+}

package/src/botbuddy-release-repair.json

@@ -1 +0,0 @@
-{"schema_version":1,"source_version":"1.5.1","source_identity":"56890dbd45a92364dc2a57ed8f09710d3e3d53c5af8999680ef1d19552e19c94"}