@botbuddy/cli 1.8.5 → 1.8.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@botbuddy/cli",
-  "version": "1.8.5",
+  "version": "1.8.7",
   "description": "BotBuddy — Swarm coordination CLI for multi-agent workflows",
   "type": "module",
   "bin": {
@@ -8,6 +8,10 @@
     "pw": "./bin/pw.mjs",
     "bb-pw": "./bin/bb-pw.mjs"
   },
+  "exports": {
+    "./playwright-reporter": "./src/test/playwright-reporter.mjs",
+    "./package.json": "./package.json"
+  },
   "files": [
     "bin/",
     "src/",

package/src/commands.mjs

@@ -7,6 +7,7 @@ import { CallUsageError, discoveryUrlFor, formatDiscovery, parseCallArgs } from
 import { cmdStack } from "./stack.mjs";
 import { cmdDocker } from "./docker-hygiene.mjs";
 import { cmdRun } from "./run.mjs";
+import { cmdTest } from "./test-lane.mjs";
 import { runWait } from "./wait.mjs";
 import { green, red, cyan, dim, bold, die } from "./utils.mjs";
 import { VERSION } from "./version.mjs";
@@ -32,6 +33,7 @@ export async function run(argv) {
     case "stack": return cmdStack(args);
     case "docker": return cmdDocker(args);
     case "run": return cmdRun(args);
+    case "test": return cmdTest(args);
     case "wait": return runWait(args);
     case "pw": return runPw(args);
     case "profile": return cmdProfile(args);

package/src/pw/daemon.mjs

@@ -1,13 +1,62 @@
 import { spawn } from "node:child_process";
 import net from "node:net";
 import { createRequire } from "node:module";
-import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { existsSync, readdirSync, readFileSync, statSync, unlinkSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { homedir } from "node:os";
+import { normaliseLane } from "./args.mjs";
 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(); }); }
+// BOT-1522: playwright-cli keeps one sub-dir per invocation context under the
+// daemon dir, and only ever cleans up its OWN sub-dir's `<session>.session`. A
+// lane opened from another worktree whose daemon has since exited leaves a file
+// pointing at a socket that no longer exists — and it can sort before today's
+// live one. Selection is therefore by liveness, never by readdir order, and the
+// caller gets a remediation naming the lane and the command, never a raw syscall.
+export const laneOf = (session) => normaliseLane(session ?? "");
+// Any connect-phase failure means the daemon is not there to answer; name the
+// shape in prose so the syscall code never reaches the operator (AC-3/AC-6).
+const CONNECT_FAILURE = { ENOENT: "its socket is gone", ECONNREFUSED: "its socket refused the connection", ENOTSOCK: "its socket refused the connection", ECONNRESET: "the connection dropped", EPIPE: "the connection dropped" };
+const connectFailure = (error) => (error?.code ? CONNECT_FAILURE[error.code] ?? "the connection failed" : null);
+export function notRunningMessage(session, ignored = [], detail = null) {
+  const why = ignored.length ? `ignored stale session file(s): ${ignored.map((entry) => `${entry.file} [${entry.reason}]`).join(", ")}` : detail ?? "no session file found";
+  return `bb-pw: ${session} daemon is not running (${why}). Run \`bb-pw ${laneOf(session) || "<lane>"} open <url>\` first, then retry.`;
+}
+// Every `<root>/<sub>/<session>.session`, newest first. A file whose socket path
+// is ABSENT on disk is provably dead (the daemon's tmp dir is gone) and is
+// pruned; one whose socket EXISTS is kept — the daemon may be starting — and
+// liveness is decided by connecting (resolveSession), not by the file. Corrupt
+// JSON is left alone: it is not provably dead. Only this session's file is read,
+// so another lane's live daemon in the same sub-dir is never touched.
+export function scanSessions(session, env = process.env, { prune = true } = {}) {
+  const root = daemonDir(env), candidates = [], ignored = [];
+  if (!existsSync(root)) return { candidates, ignored };
+  for (const item of readdirSync(root)) {
+    const file = join(root, item, `${session}.session`);
+    let data; try { data = JSON.parse(readFileSync(file, "utf8")); } catch { continue; }
+    if (!data?.socketPath) { ignored.push({ file, reason: "no socket path" }); continue; }
+    if (!existsSync(data.socketPath)) { ignored.push({ file, reason: "socket missing" }); if (prune) { try { unlinkSync(file); } catch {} } continue; }
+    let mtimeMs = 0; try { mtimeMs = statSync(file).mtimeMs; } catch {}
+    candidates.push({ file, data, mtimeMs });
+  }
+  // Newest first; a deterministic path tiebreak so an mtime tie never falls back to readdir order.
+  candidates.sort((a, b) => b.mtimeMs - a.mtimeMs || b.file.localeCompare(a.file));
+  return { candidates, ignored };
+}
+// Synchronous, back-compatible, READ-ONLY reader (reap.mjs): the newest session
+// whose socket path exists on disk. Pruning belongs to the socket path (socketRun).
+export function readSession(session, env = process.env) { return scanSessions(session, env, { prune: false }).candidates[0]?.data ?? null; }
+export function sendToDaemon(socketPath, positional, { connect = net.createConnection, cwd = process.cwd(), timeoutMs = 30000, session = null } = {}) { 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) => { const why = session ? connectFailure(error) : null; finish({ ok: false, error: why ? notRunningMessage(session, [], why) : 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` }; }
+// Authoritative, async: the newest candidate whose socket actually ANSWERS.
+export async function resolveSession(session, env = process.env, { alive = socketAlive } = {}) {
+  const { candidates, ignored } = scanSessions(session, env);
+  for (const candidate of candidates) { if (await alive(candidate.data.socketPath)) return { session: candidate.data, ignored }; ignored.push({ file: candidate.file, reason: "did not answer" }); }
+  return { session: null, ignored };
+}
+export async function socketRun(plan, env = process.env, { alive, send = sendToDaemon } = {}) {
+  const { session, ignored } = await resolveSession(plan.session, env, { alive });
+  if (!session) return { ok: false, error: notRunningMessage(plan.session, ignored) };
+  return send(session.socketPath, plan.socketArgs, { session: plan.session });
+}

package/src/pw/run.mjs

@@ -7,6 +7,7 @@ import { canonicalizeHostString } from "./host.mjs";
 import { resolveAgentProfile } from "../wait-profile.mjs";
 import { readProfileIdentity } from "../agent-credential-store.mjs";
 import { loadConfig, getConfig } from "../config.mjs";
+import { VERSION } from "../version.mjs";
 // BOT-1488: canonicalize the raw hostname the SAME way acquire_resources does
 // 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").
@@ -68,8 +69,22 @@ async function gate({ env, host, lane, deps }) {
     return { allowed: false, message: `bb-pw: could not verify lane lock ${laneName} (${error.message}). Set BB_PW_NO_LOCK=1 for local-only work.` };
   }
 }
+// BOT-1522: a stale global install (1.6.1 on the reporting host) replayed the
+// pre-BOT-1488 refusal and was indistinguishable from a code regression. Every
+// non-zero exit now names the bundled version, and --version exists at all, so
+// an agent can tell "old binary" from "real bug" without reading the source.
+const versionLine = () => `bb-pw (@botbuddy/cli v${VERSION})`;
 export async function runPw(argv, deps = {}) {
+  const stderr = deps.stderr ?? process.stderr;
+  const code = await runPwInner(argv, deps);
+  // Neutral: a refusal may be correct policy, not staleness — the line only lets
+  // the reader compare this binary against cli/package.json in their checkout.
+  if (code !== 0) stderr.write(`${versionLine()} — if your checkout's cli/package.json is newer, this global is stale: npm i -g @botbuddy/cli@latest, or run node cli/bin/bb-pw.mjs from the repo.\n`);
+  return code;
+}
+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; }
+  if (["--version", "-v"].includes(args[0])) { stdout.write(`${versionLine()}\n`); return 0; }
   while (args[0] === "--profile" || args[0] === "--session-id") { const flag = args[0]; if (!args[1]) { stderr.write(`bb-pw: ${flag} needs a value\n`); return 2; } deps = flag === "--profile" ? { ...deps, profile: args[1] } : { ...deps, sessionId: 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");

package/src/run.mjs

@@ -13,12 +13,16 @@ import { homedir } from "os";
 import { spawn } from "child_process";
 import { fileURLToPath } from "url";
 import { callToolJson } from "./api.mjs";
+import { parseLaneEvents, laneCaseCounts, flushLaneCases, buildLaneSummary, laneSummaryFilename } from "./test-lane-events.mjs";
 
 export const RUN_SCHEMA_VERSION = 1;
 export const EXIT = Object.freeze({ OK: 0, INVALID: 4, BACKEND: 5, INTERNAL: 7 });
 export const DEFAULT_TIMEOUT_SECONDS = 8 * 60 * 60;
 export const TIMEOUT_GRACE_MS = 5_000;
 const MAX_CAPTURE_BYTES = 8_192;
+// BOT-1510: how often the worker flushes lane case verdicts to the backend.
+// Well under AC-3's 5 s so a begin/verdict is visible within the window.
+const LANE_FLUSH_INTERVAL_MS = 2_500;
 
 export function parseRunArgs(argv) {
   const opts = { sessionId: null, environment: null, category: "validation", kind: "other", expectedDuration: 0, timeout: DEFAULT_TIMEOUT_SECONDS, rerunReason: null, json: false };
@@ -91,7 +95,7 @@ function workerInvocation(context) {
   return [process.execPath, [bin, "run", "--worker", context]];
 }
 
-export async function launchRun(argv, { cwd = process.cwd(), spawnImpl = spawn, call = callToolJson } = {}) {
+export async function launchRun(argv, { cwd = process.cwd(), spawnImpl = spawn, call = callToolJson, childEnv = null, testRun = null } = {}) {
   const { opts, command, errors } = parseRunArgs(argv);
   if (errors.length) return { exitCode: EXIT.INVALID, receipt: { schema_version: RUN_SCHEMA_VERSION, outcome: "rejected", errors, exit_code: EXIT.INVALID } };
   const runId = randomUUID();
@@ -106,7 +110,7 @@ export async function launchRun(argv, { cwd = process.cwd(), spawnImpl = spawn,
   }
   const context = contextPath(runId);
   const receipt = receiptPath(runId);
-  await writeJson(context, { schema_version: RUN_SCHEMA_VERSION, context_path: context, run_id: runId, run_credential: registration.data.run_credential, receipt_upload: registration.data.receipt_upload, command, cwd, timeout_seconds: opts.timeout, receipt_path: receipt, launched_at: new Date().toISOString() });
+  await writeJson(context, { schema_version: RUN_SCHEMA_VERSION, context_path: context, run_id: runId, run_credential: registration.data.run_credential, receipt_upload: registration.data.receipt_upload, command, cwd, timeout_seconds: opts.timeout, receipt_path: receipt, launched_at: new Date().toISOString(), ...(childEnv && Object.keys(childEnv).length ? { child_env: childEnv } : {}), ...(testRun ? { test_run: testRun } : {}) });
   const [file, args] = workerInvocation(context);
   try {
     const worker = spawnImpl(file, args, { detached: true, stdio: "ignore", windowsHide: true });
@@ -124,9 +128,12 @@ export async function runWorker(contextFile, { spawnImpl = spawn, call = callToo
   let timedOut = false;
   let child;
   try {
-    child = spawnImpl(context.command[0], context.command.slice(1), { cwd: context.cwd, detached: true, stdio: ["ignore", "pipe", "pipe"], windowsHide: true });
+    child = spawnImpl(context.command[0], context.command.slice(1), { cwd: context.cwd, detached: true, stdio: ["ignore", "pipe", "pipe"], windowsHide: true, ...(context.child_env ? { env: { ...process.env, ...context.child_env } } : {}) });
   } catch (error) {
-    return finalize(context, { status: "owner_lost", startedAt, endedAt: new Date().toISOString(), exitCode: null, signal: null, reason: `workload_spawn_failed:${error instanceof Error ? error.message : String(error)}` }, call);
+    const endedAt = new Date().toISOString();
+    const receipt = await finalize(context, { status: "owner_lost", startedAt, endedAt, exitCode: null, signal: null, reason: `workload_spawn_failed:${error instanceof Error ? error.message : String(error)}` }, call);
+    if (context.test_run) await completeTestRun(context, { status: "owner_lost", exitCode: null, signal: null, startedAt, endedAt, call });
+    return receipt;
   }
   // A failed spawn can report through the child `error` event on the next turn.
   // Subscribe before any filesystem I/O so a busy parallel test run (or a real
@@ -140,6 +147,9 @@ export async function runWorker(contextFile, { spawnImpl = spawn, call = callToo
   child.stdout?.on("data", (chunk) => capture.append(chunk));
   child.stderr?.on("data", (chunk) => capture.append(chunk));
   await writeJson(context.context_path, { ...context, worker_pid: process.pid, workload_pid: child.pid });
+  // BOT-1510: for a test lane, tail the reporter's NDJSON and flush per-case
+  // verdicts while the child runs. The test process never touches the network.
+  const lane = context.test_run ? startLaneFlusher(context, call) : null;
   let killTimer;
   const timer = setTimeout(() => {
     timedOut = true;
@@ -149,11 +159,85 @@ export async function runWorker(contextFile, { spawnImpl = spawn, call = callToo
   const result = await completion;
   clearTimeout(timer);
   clearTimeout(killTimer);
+  if (lane) await lane.stop();
+  const endedAt = new Date().toISOString();
   if (result.error) {
-    return finalize(context, { status: "owner_lost", startedAt, endedAt: new Date().toISOString(), exitCode: null, signal: null, reason: `workload_spawn_failed:${result.error.message}`, output: capture.output, outputCharacters: capture.characters }, call);
+    const receipt = await finalize(context, { status: "owner_lost", startedAt, endedAt, exitCode: null, signal: null, reason: `workload_spawn_failed:${result.error.message}`, output: capture.output, outputCharacters: capture.characters }, call);
+    if (context.test_run) await completeTestRun(context, { status: "owner_lost", exitCode: null, signal: null, startedAt, endedAt, call });
+    return receipt;
   }
   const status = terminalStatus({ ...result, timedOut });
-  return finalize(context, { status, startedAt, endedAt: new Date().toISOString(), exitCode: result.exitCode, signal: result.signal, output: capture.output, outputCharacters: capture.characters }, call);
+  const receipt = await finalize(context, { status, startedAt, endedAt, exitCode: result.exitCode, signal: result.signal, output: capture.output, outputCharacters: capture.characters }, call);
+  // AC-4/AC-5: complete the run (final flush → update_test_run status:completed →
+  // emit_test_run_signal fires → the armed `test-run:` wait wakes).
+  if (context.test_run) await completeTestRun(context, { status, exitCode: result.exitCode, signal: result.signal, startedAt, endedAt, call });
+  return receipt;
+}
+
+// Periodic lane flusher: reduce the NDJSON events file to the current case state
+// and upsert it via sync_test_run_cases. Idempotent (keyed by case_key), so a
+// re-flush of an unchanged list is a no-op server-side. Never throws.
+function startLaneFlusher(context, call) {
+  const tr = context.test_run;
+  let stopped = false;
+  let chain = Promise.resolve();
+  const tick = () => {
+    chain = chain.then(async () => {
+      if (stopped) return;
+      let text = "";
+      try { text = await readFile(tr.events_path, "utf8"); } catch { return; }
+      const { cases } = parseLaneEvents(text, { warn: () => {} });
+      if (cases.size) await flushLaneCases({ call, testRunId: tr.test_run_id, cases });
+    }).catch(() => { /* a flush failure retries on the next tick; never blocks the child */ });
+  };
+  const timer = setInterval(tick, LANE_FLUSH_INTERVAL_MS);
+  timer.unref?.();
+  return { async stop() { stopped = true; clearInterval(timer); await chain; } };
+}
+
+// Terminal: one last flush, write the .botbuddy/test-runs summary, then retry
+// update_test_run{completed} until accepted (like update_command_run).
+async function completeTestRun(context, { status, exitCode, signal, startedAt, endedAt, call }) {
+  const tr = context.test_run;
+  let text = "";
+  try { text = await readFile(tr.events_path, "utf8"); } catch { /* no events (0-test lane, or offline reporter) */ }
+  const { cases } = parseLaneEvents(text, { warn: () => {} });
+  if (cases.size) { try { await flushLaneCases({ call, testRunId: tr.test_run_id, cases }); } catch { /* update below still records terminal state */ } }
+  const counts = laneCaseCounts(cases);
+  const cancelled = status !== "success" && status !== "failure";
+  const durationMs = Math.max(0, Date.parse(endedAt) - Date.parse(startedAt));
+  const summary = buildLaneSummary({
+    lane: tr.lane, runner: tr.runner, testRunId: tr.test_run_id,
+    startedAt, finishedAt: endedAt, durationMs, exitCode, signal,
+    command: context.command, cwd: context.cwd, gitSha: tr.git_sha ?? null, branch: tr.branch ?? null,
+    counts, cancelled, lefthookEnv: laneLefthookEnv(),
+  });
+  try {
+    const summaryPath = join(context.cwd, ".botbuddy", "test-runs", laneSummaryFilename(endedAt, tr.lane));
+    await mkdir(dirname(summaryPath), { recursive: true });
+    await writeFile(summaryPath, JSON.stringify(summary, null, 2) + "\n");
+  } catch { /* the summary is best-effort; the test_runs row is authoritative */ }
+  await retryUpdateTestRun({
+    test_run_id: tr.test_run_id, status: "completed",
+    metadata: { lane: tr.lane, runner: tr.runner, exit_code: exitCode ?? null, duration_ms: durationMs, cwd: context.cwd, command: context.command, command_run_id: context.run_id, cancelled, ...counts },
+  }, call);
+  return summary;
+}
+
+export async function retryUpdateTestRun(update, call, { sleep = (ms) => new Promise((r) => setTimeout(r, ms)), maxAttempts = 6 } = {}) {
+  let delay = 1_000;
+  for (let attempt = 1; ; attempt++) {
+    let res;
+    try { res = await call("update_test_run", update); } catch (error) { res = { ok: false, error: error instanceof Error ? error.message : String(error) }; }
+    if (res?.ok && !res.isError) return res;
+    if (attempt >= maxAttempts) return res; // detached worker gives up rather than hanging forever
+    await sleep(delay);
+    delay = Math.min(delay * 2, 30_000);
+  }
+}
+
+function laneLefthookEnv(env = process.env) {
+  return { LEFTHOOK: env.LEFTHOOK ?? null, LEFTHOOK_EXCLUDE: env.LEFTHOOK_EXCLUDE ?? null, LEFTHOOK_INCLUDE: env.LEFTHOOK_INCLUDE ?? null };
 }
 
 function boundedCapture() {

package/src/test/playwright-reporter.mjs

@@ -0,0 +1,99 @@
+// BOT-1510 — Playwright reporter for `botbuddy test <lane>` (runner=playwright).
+//
+// Wired via `@botbuddy/cli/playwright-reporter` behind an env-conditional line in
+// the host's playwright.config.ts:
+//   reporter: process.env.BOTBUDDY_TEST_RUN_ID
+//     ? [["list"], ["@botbuddy/cli/playwright-reporter"]]
+//     : [["list"], ["html", { open: "never" }]]
+//
+// It does ONE thing: append NDJSON begin/verdict events to the file named by
+// $BOTBUDDY_TEST_RUN_EVENTS. It NEVER opens a socket — the detached `botbuddy
+// run` worker tails this file and is the only process that talks to the backend.
+// No env → a silent no-op, so a normal `pnpm test:e2e` is unaffected.
+
+import { appendFileSync, mkdirSync } from "node:fs";
+import { dirname } from "node:path";
+
+const MAX_FAIL_REASON_BYTES = 2048;
+
+export function verdictFor(status) {
+  switch (status) {
+    case "passed": return "pass";
+    case "skipped": return "skip";
+    case "failed":
+    case "timedOut":
+    case "interrupted": return "fail";
+    default: return "fail";
+  }
+}
+
+function projectName(test) {
+  try {
+    const p = test?.parent?.project?.();
+    if (p?.name) return p.name;
+  } catch { /* older Playwright shapes — fall through */ }
+  return "";
+}
+
+// Stable per-case identity: "<file>::<titlePath joined ' › '>::<project>".
+export function caseKey(test) {
+  const file = test?.location?.file ?? "";
+  const path = (typeof test?.titlePath === "function" ? test.titlePath() : []).filter(Boolean).join(" › ");
+  return `${file}::${path}::${projectName(test)}`;
+}
+
+function truncateUtf8(input, maxBytes) {
+  const bytes = new TextEncoder().encode(input);
+  if (bytes.length <= maxBytes) return input;
+  return new TextDecoder("utf-8", { fatal: false }).decode(bytes.slice(0, maxBytes)).replace(/�+$/, "");
+}
+
+export default class BotBuddyPlaywrightReporter {
+  constructor(_options = {}, { env = process.env } = {}) {
+    this._path = env.BOTBUDDY_TEST_RUN_EVENTS || null;
+    this._order = new Map();
+    this._dirEnsured = false;
+  }
+
+  _append(event) {
+    if (!this._path) return; // no telemetry target — a normal local run
+    try {
+      if (!this._dirEnsured) { mkdirSync(dirname(this._path), { recursive: true }); this._dirEnsured = true; }
+      appendFileSync(this._path, JSON.stringify(event) + "\n");
+    } catch (err) {
+      // Telemetry must never fail the test run.
+      process.stderr.write(`[botbuddy-reporter] could not append event: ${err?.message ?? err}\n`);
+    }
+  }
+
+  onBegin(_config, suite) {
+    if (!this._path) return;
+    const tests = typeof suite?.allTests === "function" ? suite.allTests() : [];
+    tests.forEach((t, i) => {
+      const key = caseKey(t);
+      this._order.set(key, i);
+      const title = (typeof t?.titlePath === "function" ? t.titlePath() : []).filter(Boolean).join(" › ") || key;
+      this._append({ type: "begin", key, title, sort_order: i });
+    });
+  }
+
+  onTestEnd(test, result) {
+    if (!this._path) return;
+    const key = caseKey(test);
+    const sort_order = this._order.get(key) ?? this._order.size;
+    const firstError = Array.isArray(result?.errors) ? result.errors.find((e) => e?.message)?.message : result?.error?.message;
+    this._append({
+      type: "verdict",
+      key,
+      sort_order,
+      verdict: verdictFor(result?.status),
+      fail_reason: firstError ? truncateUtf8(String(firstError), MAX_FAIL_REASON_BYTES) : null,
+      duration_ms: Number.isFinite(result?.duration) ? Math.round(result.duration) : null,
+      retry: Number.isInteger(result?.retry) ? result.retry : 0,
+    });
+  }
+
+  // Playwright requires this hook to exist; nothing to flush — the worker owns
+  // the terminal update.
+  onEnd() {}
+}

package/src/test-lane-events.mjs

@@ -0,0 +1,104 @@
+// BOT-1510 — the detached worker's view of a lane's NDJSON telemetry.
+//
+// The Playwright reporter (or the generic runner) appends begin/verdict events
+// to an NDJSON file; the worker tails it and flushes the reduced per-case state
+// to `sync_test_run_cases`. These functions are the pure, unit-tested core:
+// parse (corrupt lines skipped, never a crash), reduce to a case map (last
+// verdict wins), chunk to the 500-case cap, count, and build the terminal
+// `.botbuddy/test-runs/<iso>-<lane>.json` summary.
+
+export const SYNC_BATCH = 500;
+
+// Parse NDJSON lane events into an ordered case map. Corrupt/partial lines are
+// skipped with a stderr warning (AC-11) and counted in `malformed`.
+export function parseLaneEvents(text, { warn = (m) => process.stderr.write(m) } = {}) {
+  const cases = new Map();
+  let malformed = 0;
+  for (const raw of String(text ?? "").split("\n")) {
+    const line = raw.trim();
+    if (!line) continue;
+    let ev;
+    try { ev = JSON.parse(line); } catch { malformed += 1; warn("[botbuddy] skipping corrupt lane event line\n"); continue; }
+    if (!ev || typeof ev.key !== "string" || (ev.type !== "begin" && ev.type !== "verdict")) { malformed += 1; continue; }
+    const c = cases.get(ev.key) ?? { key: ev.key, title: ev.key, sort_order: cases.size, verdict: "pending", fail_reason: null, duration_ms: null };
+    if (typeof ev.title === "string" && ev.title) c.title = ev.title;
+    if (Number.isInteger(ev.sort_order)) c.sort_order = ev.sort_order;
+    if (ev.type === "verdict") {
+      if (ev.verdict) c.verdict = ev.verdict; // last write wins (retries)
+      c.fail_reason = typeof ev.fail_reason === "string" ? ev.fail_reason : null;
+      if (Number.isFinite(ev.duration_ms)) c.duration_ms = ev.duration_ms;
+    }
+    cases.set(ev.key, c);
+  }
+  return { cases, malformed };
+}
+
+// Case map → the sync_test_run_cases payload, ordered by sort_order.
+export function laneCasesToSync(cases) {
+  return [...cases.values()]
+    .sort((a, b) => a.sort_order - b.sort_order)
+    .map((c) => ({
+      key: c.key, title: c.title, sort_order: c.sort_order, verdict: c.verdict,
+      ...(c.fail_reason != null ? { fail_reason: c.fail_reason } : {}),
+      ...(c.duration_ms != null ? { duration_ms: c.duration_ms } : {}),
+    }));
+}
+
+export function chunkCases(arr, size = SYNC_BATCH) {
+  const out = [];
+  for (let i = 0; i < arr.length; i += size) out.push(arr.slice(i, i + size));
+  return out;
+}
+
+export function laneCaseCounts(cases) {
+  let passed = 0, failed = 0, skipped = 0, pending = 0;
+  for (const c of cases.values()) {
+    if (c.verdict === "pass") passed += 1;
+    else if (c.verdict === "fail") failed += 1;
+    else if (c.verdict === "skip") skipped += 1;
+    else pending += 1;
+  }
+  return { case_count: cases.size, passed, failed, skipped, pending };
+}
+
+// Flush the current case state in ≤500-case batches. Never throws — a failed
+// batch is reported so the caller can retry on the next tick without ever
+// blocking or killing the child.
+export async function flushLaneCases({ call, testRunId, cases }) {
+  const chunks = chunkCases(laneCasesToSync(cases));
+  let sent = 0;
+  let ok = true;
+  for (const chunk of chunks) {
+    let res;
+    try { res = await call("sync_test_run_cases", { test_run_id: testRunId, cases: chunk }); }
+    catch (err) { res = { ok: false, error: err instanceof Error ? err.message : String(err) }; }
+    if (res?.ok && !res.isError) sent += chunk.length; else ok = false;
+  }
+  return { chunks: chunks.length, sent, ok };
+}
+
+// The `.botbuddy/test-runs/<iso>-<lane>.json` summary: the log-test-run.mjs
+// shape (BOT-461) plus test_run_id, so BOT-1387/BOT-608 consumers stay
+// compatible while gaining the run linkage.
+export function buildLaneSummary({
+  lane, runner, testRunId, startedAt, finishedAt, durationMs, exitCode, signal,
+  command, cwd, gitSha = null, branch = null, counts = null, cancelled = false, lefthookEnv = null,
+}) {
+  return {
+    runner, source: "cli-lane",
+    command: Array.isArray(command) ? command.join(" ") : String(command ?? ""),
+    started_at: startedAt, finished_at: finishedAt, duration_ms: durationMs,
+    exit_code: exitCode ?? null, signal: signal ?? null,
+    verdict: exitCode === 0 ? "pass" : "fail",
+    git_sha: gitSha, branch, spawn_error: null,
+    meta: { lane, cwd, cancelled, ...(counts ?? {}) },
+    lefthook_env: lefthookEnv,
+    test_run_id: testRunId,
+  };
+}
+
+// `.botbuddy/test-runs/<iso>-<lane>.json` — the same ISO-safe basename shape as
+// scripts/log-test-run.mjs, but keyed by lane (not runner) per AC-4.
+export function laneSummaryFilename(finishedAtIso, lane) {
+  return `${finishedAtIso.replace(/[:.]/g, "-")}-${lane}.json`;
+}

package/src/test-lane.mjs

@@ -0,0 +1,275 @@
+// BOT-1510 — `botbuddy test <lane>`: run a repo-configured local test lane AS a
+// BotBuddy test run.
+//
+// The launcher creates a `test_runs` row for the lane, promotes it to `active`
+// (attaching the ticket in a SECOND call so a human's ticket+env draft run is
+// never hijacked by create_test_run's upsert), then hands the lane to the
+// existing durable `botbuddy run` worker with the test-run id in the child's
+// env. It prints exactly one JSON line and exits 0 — like `botbuddy run` — while
+// the lane keeps executing detached. A worker (later phase) tails the reporter's
+// NDJSON and flushes per-case verdicts through `sync_test_run_cases`.
+//
+// Backend down? The lane still runs; the JSON line says telemetry:"unavailable",
+// wait:null, and the child exit code is preserved.
+
+import { randomUUID } from "node:crypto";
+import { existsSync, readFileSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { homedir } from "node:os";
+import { execFileSync } from "node:child_process";
+
+import { EXIT, launchRun, receiptPath, DEFAULT_TIMEOUT_SECONDS } from "./run.mjs";
+import { callToolJson } from "./api.mjs";
+
+// EXIT.{OK,INVALID,BACKEND,INTERNAL} plus a --wait timeout code (AC-9).
+export const EXIT_TEST = Object.freeze({ ...EXIT, TIMEOUT: 2 });
+export const WAITS_URL = "https://app.bot-buddy.ai/waits";
+const KNOWN_RUNNERS = new Set(["playwright", "generic"]);
+
+export function parseTestArgs(argv, { env = process.env } = {}) {
+  const opts = {
+    sessionId: env.BOTBUDDY_SESSION_ID ?? null,
+    environment: "local",
+    ticket: null, pr: null, repo: null,
+    wait: false, json: false,
+  };
+  const errors = [];
+  const separator = argv.indexOf("--");
+  const flags = separator === -1 ? argv : argv.slice(0, separator);
+  const extra = separator === -1 ? [] : argv.slice(separator + 1);
+  let subcommand = null;
+  let lane = null;
+  const value = (name, i) => { if (flags[i + 1] == null) { errors.push(`${name} needs a value`); return null; } return flags[i + 1]; };
+  for (let i = 0; i < flags.length; i++) {
+    const flag = flags[i];
+    switch (flag) {
+      case "--session-id": opts.sessionId = value(flag, i); i++; break;
+      case "--environment": opts.environment = value(flag, i); i++; break;
+      case "--ticket": opts.ticket = value(flag, i); i++; break;
+      case "--pr": { const raw = value(flag, i); i++; opts.pr = raw == null ? null : Number(raw); if (raw != null && !Number.isInteger(opts.pr)) errors.push("--pr must be an integer"); break; }
+      case "--repo": opts.repo = value(flag, i); i++; break;
+      case "--wait": opts.wait = true; break;
+      case "--json": opts.json = true; break;
+      default:
+        if (flag.startsWith("-")) { errors.push(`unknown option: ${flag}`); break; }
+        if (lane === null && subcommand === null) {
+          if (flag === "list" || flag === "help") subcommand = flag;
+          else lane = flag;
+        } else errors.push(`unexpected argument: ${flag}`);
+    }
+  }
+  if (!subcommand && !lane) errors.push("a lane is required (e.g. `botbuddy test e2e`); run `botbuddy test list`");
+  return { subcommand, lane, opts, extra, errors };
+}
+
+export function findGitRoot(cwd) {
+  let dir = cwd;
+  for (;;) {
+    if (existsSync(join(dir, ".git"))) return dir;
+    const parent = dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+
+// `.botbuddy/lanes.json` at the git root — no defaults (gate 9): a missing file
+// or an unknown lane is a hard, named failure, never a guessed command.
+export function resolveLane(laneName, { cwd = process.cwd(), readFileImpl = readFileSync } = {}) {
+  const root = findGitRoot(cwd) ?? cwd;
+  const path = join(root, ".botbuddy", "lanes.json");
+  if (!existsSync(path)) return { ok: false, error: "missing", path, root };
+  let config;
+  try { config = JSON.parse(readFileImpl(path, "utf8")); }
+  catch (e) { return { ok: false, error: "invalid", path, root, detail: e instanceof Error ? e.message : String(e) }; }
+  const lanes = config?.lanes && typeof config.lanes === "object" ? config.lanes : {};
+  const available = Object.keys(lanes);
+  if (!laneName || !lanes[laneName]) return { ok: false, error: "unknown", path, root, available };
+  const lane = lanes[laneName];
+  if (!Array.isArray(lane.command) || lane.command.length === 0) return { ok: false, error: "invalid", path, root, detail: `lane "${laneName}" has no command` };
+  if (!KNOWN_RUNNERS.has(lane.runner)) return { ok: false, error: "invalid", path, root, detail: `lane "${laneName}" runner must be playwright|generic` };
+  return { ok: true, appSlug: config.app_slug ?? null, lane, path, root };
+}
+
+// Best-effort git/gh context. Every field falls back to null — never fabricated
+// (gate 9). CLI overrides (--ticket/--pr/--repo) win over the derived values.
+export function defaultGitInfo({ cwd = process.cwd(), ticket = null, pr = null, repo = null } = {}) {
+  const git = (args) => { try { return execFileSync("git", args, { cwd, encoding: "utf8" }).trim() || null; } catch { return null; } };
+  const branch = git(["rev-parse", "--abbrev-ref", "HEAD"]);
+  const sha = git(["rev-parse", "HEAD"]);
+  let ticketId = ticket;
+  if (!ticketId && branch) {
+    const m = branch.match(/(?:^|\/)((?:bot|ent)-\d+)/i);
+    if (m) ticketId = m[1].toUpperCase();
+  }
+  const ticketUrl = ticketId?.startsWith("BOT-") ? `https://linear.app/botbuddy/issue/${ticketId}` : null;
+  let prNumber = pr;
+  let prUrl = null;
+  if (prNumber == null) {
+    try {
+      const raw = execFileSync("gh", ["pr", "view", "--json", "number,url"], { cwd, encoding: "utf8" });
+      const parsed = JSON.parse(raw);
+      prNumber = Number.isInteger(parsed.number) ? parsed.number : null;
+      prUrl = parsed.url ?? null;
+    } catch { /* no PR / gh unavailable — null, never fabricated */ }
+  }
+  return { branch, sha, prNumber, prUrl, repo, ticket: ticketId, ticketUrl };
+}
+
+// The production lane launcher: run the lane through the durable `botbuddy run`
+// worker, carrying the telemetry env into its detached child.
+async function defaultLaunchLane({ command, sessionId, environment, expectedDurationSeconds, childEnv, testRun, cwd, call }) {
+  const argv = ["--session-id", sessionId, "--environment", environment, "--category", "validation", "--kind", "full_suite", "--expected-duration", String(expectedDurationSeconds ?? 0), "--", ...command];
+  const result = await launchRun(argv, { cwd, call, childEnv, testRun });
+  return { exitCode: result.exitCode, runId: result.receipt?.run_id ?? null };
+}
+
+function waitCommand(testRunId, sessionId) {
+  return `botbuddy wait 'test-run:id=${testRunId}' --session-id ${sessionId} --heartbeat`;
+}
+
+export async function launchTestLane(argv, {
+  cwd = process.cwd(),
+  env = process.env,
+  call = callToolJson,
+  launchLane = defaultLaunchLane,
+  gitInfo = defaultGitInfo,
+  eventsDir = join(homedir(), ".botbuddy", "test-lanes"),
+} = {}) {
+  const { lane: laneName, opts, extra, errors } = parseTestArgs(argv, { env });
+  if (errors.length) {
+    for (const e of errors) process.stderr.write(`botbuddy test: ${e}\n`);
+    return { exitCode: EXIT_TEST.INVALID, line: JSON.stringify({ outcome: "rejected", errors }) };
+  }
+  if (!opts.sessionId) {
+    process.stderr.write("botbuddy test: --session-id is required (or set $BOTBUDDY_SESSION_ID)\n");
+    return { exitCode: EXIT_TEST.INVALID, line: JSON.stringify({ outcome: "rejected", errors: ["--session-id is required"] }) };
+  }
+
+  const resolved = resolveLane(laneName, { cwd });
+  if (!resolved.ok) {
+    if (resolved.error === "missing") process.stderr.write(`botbuddy test: no lane config — create ${resolved.path}\n`);
+    else if (resolved.error === "unknown") process.stderr.write(`botbuddy test: unknown lane "${laneName}". Available: ${resolved.available.join(", ") || "(none)"}\n`);
+    else process.stderr.write(`botbuddy test: invalid lane config (${resolved.detail}) at ${resolved.path}\n`);
+    return { exitCode: EXIT_TEST.INVALID, line: JSON.stringify({ outcome: "rejected", error: resolved.error, path: resolved.path }) };
+  }
+
+  const git = gitInfo({ cwd, ticket: opts.ticket, pr: opts.pr, repo: opts.repo });
+  const sha7 = (git.sha ?? "").slice(0, 7) || "nosha";
+  const laneRunId = randomUUID();
+  const eventsPath = join(eventsDir, `${laneRunId}.ndjson`);
+  const title = `${laneName} · ${git.branch ?? "detached"} · ${sha7}`;
+
+  // Step 1: create WITHOUT ticket_id (create_test_run upserts on ticket_id+env —
+  // passing it would hijack a human's draft/active run for the same ticket).
+  const createArgs = {
+    app_slug: resolved.appSlug, environment: opts.environment, title,
+    commit_sha: git.sha ?? undefined, branch_name: git.branch ?? undefined,
+    pr_number: git.prNumber ?? undefined, pr_url: git.prUrl ?? undefined,
+    source_kind: "cli-lane", source_id: laneRunId,
+  };
+  const created = await call("create_test_run", createArgs);
+  const testRunId = created?.ok && !created.isError ? created.data?.id ?? null : null;
+
+  if (testRunId) {
+    // Step 2: attach the ticket + promote to active in one update.
+    await call("update_test_run", {
+      test_run_id: testRunId,
+      ticket_id: git.ticket ?? undefined,
+      ticket_url: git.ticketUrl ?? undefined,
+      status: "active",
+    });
+  }
+
+  // Step 3: launch the lane under the durable worker, telemetry env in the child.
+  const childEnv = { BOTBUDDY_LANE: laneName };
+  if (testRunId) { childEnv.BOTBUDDY_TEST_RUN_ID = testRunId; childEnv.BOTBUDDY_TEST_RUN_EVENTS = eventsPath; }
+  const testRun = testRunId
+    ? { test_run_id: testRunId, events_path: eventsPath, lane: laneName, runner: resolved.lane.runner, git_sha: git.sha ?? null, branch: git.branch ?? null }
+    : null;
+  const launch = await launchLane({
+    command: [...resolved.lane.command, ...extra],
+    sessionId: opts.sessionId, environment: opts.environment,
+    expectedDurationSeconds: resolved.lane.expected_duration_seconds ?? 0,
+    childEnv, testRun, cwd, call, testRunId, lane: laneName, runner: resolved.lane.runner,
+  });
+
+  const commandRunId = launch.runId;
+  const line = testRunId
+    ? {
+        outcome: "launched", test_run_id: testRunId, command_run_id: commandRunId, lane: laneName,
+        wait: waitCommand(testRunId, opts.sessionId),
+        receipt_path: commandRunId ? receiptPath(commandRunId) : null, waits_url: WAITS_URL,
+      }
+    : {
+        outcome: "launched", test_run_id: null, command_run_id: commandRunId, lane: laneName,
+        telemetry: "unavailable", wait: null,
+        receipt_path: commandRunId ? receiptPath(commandRunId) : null, waits_url: WAITS_URL,
+      };
+
+  return { exitCode: launch.exitCode, line: JSON.stringify(line), testRunId, commandRunId, opts };
+}
+
+// AC-9 (--wait foreground convenience): block until the run reaches a terminal
+// status, then surface the LANE's exit code (from the command-run receipt the
+// worker wrote, falling back to the run's metadata). A timeout returns exit 2
+// and never touches the still-running lane. We poll get_test_run rather than the
+// SSE wait engine because runWait() hard-exits and cannot yield the lane code.
+const TERMINAL_RUN_STATUSES = new Set(["completed", "archived", "superseded"]);
+export async function waitForLane({
+  testRunId, commandRunId, timeoutSec = DEFAULT_TIMEOUT_SECONDS,
+  call = callToolJson, readReceipt = (p) => readFile(p, "utf8").then(JSON.parse),
+  sleep = (ms) => new Promise((r) => setTimeout(r, ms)), now = Date.now, pollMs = 3_000,
+} = {}) {
+  const deadline = now() + timeoutSec * 1_000;
+  for (;;) {
+    let status = null;
+    let metaExit;
+    try {
+      const res = await call("get_test_run", { test_run_id: testRunId });
+      if (res?.ok && !res.isError) { status = res.data?.status ?? null; metaExit = res.data?.metadata?.exit_code; }
+    } catch { /* transient — retry until the deadline */ }
+    if (status && TERMINAL_RUN_STATUSES.has(status)) {
+      let exitCode = Number.isInteger(metaExit) ? metaExit : 0;
+      if (commandRunId) { try { const r = await readReceipt(receiptPath(commandRunId)); if (Number.isInteger(r?.exit_code)) exitCode = r.exit_code; } catch { /* metadata fallback */ } }
+      return { outcome: "completed", exitCode };
+    }
+    if (now() >= deadline) return { outcome: "timeout", exitCode: EXIT_TEST.TIMEOUT };
+    await sleep(pollMs);
+  }
+}
+
+function laneList(cwd) {
+  const resolved = resolveLane(null, { cwd });
+  if (resolved.error === "missing") { process.stderr.write(`botbuddy test: no lane config — create ${resolved.path}\n`); return EXIT_TEST.INVALID; }
+  const lanes = resolved.available ?? [];
+  process.stdout.write(JSON.stringify({ app_slug: resolved.appSlug ?? null, lanes }) + "\n");
+  return EXIT_TEST.OK;
+}
+
+function testHelp() {
+  console.log(`botbuddy test <lane> [--session-id <uuid>] [--environment local] [--ticket <KEY>] [--pr <n>] [--repo <owner/repo>] [--wait] [--json] [-- <extra args>]
+botbuddy test list      List the lanes configured in .botbuddy/lanes.json
+botbuddy test help      Show this help
+
+Runs a repo-configured local test lane as a BotBuddy test run, prints a
+ready-to-paste \`botbuddy wait 'test-run:id=…'\` line, and shows the run on
+${WAITS_URL} while it executes detached.`);
+}
+
+export async function cmdTest(args, { cwd = process.cwd() } = {}) {
+  const { subcommand } = parseTestArgs(args);
+  if (subcommand === "help" || args[0] === "--help" || args[0] === "-h") { testHelp(); return; }
+  if (subcommand === "list") { process.exitCode = laneList(cwd); return; }
+  const result = await launchTestLane(args, { cwd });
+  process.stdout.write(result.line + "\n");
+  // --wait (AC-9): after launch, block until the run completes and exit with the
+  // lane's exit code; a timeout exits 2 without killing the lane. Only meaningful
+  // when telemetry is live (there is a run to wait on).
+  if (result.testRunId && result.opts?.wait) {
+    const wait = await waitForLane({ testRunId: result.testRunId, commandRunId: result.commandRunId });
+    process.exitCode = wait.exitCode;
+    return;
+  }
+  process.exitCode = result.exitCode;
+}

package/src/botbuddy-release-repair.json

@@ -1 +0,0 @@
-{"schema_version":1,"source_version":"1.8.3","source_identity":"a3c85408868d913b2ab265f910ab062916c1c394895cec71cae0f79fc99f5a6c"}