@botbuddy/cli 1.8.4 → 1.8.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@botbuddy/cli",
-  "version": "1.8.4",
+  "version": "1.8.6",
   "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/botbuddy-release-repair.json

@@ -1 +1 @@
-{"schema_version":1,"source_version":"1.8.3","source_identity":"8a450fe651f42fc96f9fd713da5fe707ff48a914c174496337495adf0c425588"}
+{"schema_version":1,"source_version":"1.8.3","source_identity":"8304ea6fbec329d54d6361cb6cbf5a6789331b0851d09caf151f0663ade18ec2"}

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/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/wait-core.mjs

@@ -196,20 +196,44 @@ const VALIDATORS = {
   // BOT-1066 — ci: wake when a PR's CI reaches a terminal conclusion. Exactly one
   // selector: scope=latest (follows the PR's latest run — needs pr=), run_id=<id>
   // (pinned to one run), or sha=<sha> (pinned to a commit). repo= is always required.
+  // BOT-1507 — scope=next adds a fourth, LIVE-ONLY selector: it names no run, sha,
+  // or PR (they must all already exist at arm time) and wakes on the first terminal
+  // CI run for the repo delivered AFTER the wait was armed — the post-merge / cron
+  // train case. Optional branch=/workflow= filter that first run; both are valid
+  // ONLY with scope=next (a run_id/sha/latest wait already names its run).
   ci(p) {
     const repo = p.repo != null ? String(p.repo).trim() : null;
     if (!repo || !repo.includes("/")) throw new Error("ci needs repo=<owner/repo>");
     const selectors = ["scope", "run_id", "sha"].filter((k) => p[k] !== undefined);
     if (selectors.length !== 1) {
-      throw new Error("ci needs exactly one of scope=latest | run_id=<id> | sha=<sha>");
+      throw new Error("ci needs exactly one of scope=latest|next | run_id=<id> | sha=<sha>");
     }
+    const hasFilter = p.branch !== undefined || p.workflow !== undefined;
     if (p.scope !== undefined) {
-      if (p.scope !== "latest") throw new Error("ci scope must be 'latest' (or use run_id=/sha=)");
-      if (p.pr === undefined || !/^\d+$/.test(String(p.pr).trim())) {
-        throw new Error("ci scope=latest needs pr=<number>");
+      if (p.scope === "latest") {
+        if (hasFilter) throw new Error("ci branch=/workflow= are only valid with scope=next");
+        if (p.pr === undefined || !/^\d+$/.test(String(p.pr).trim())) {
+          throw new Error("ci scope=latest needs pr=<number>");
+        }
+        return { repo, scope: "latest", pr: String(p.pr).trim() };
+      }
+      if (p.scope === "next") {
+        // A future run has no PR head to follow — pr= is meaningless (and run_id/sha
+        // are already excluded by the single-selector check above).
+        if (p.pr !== undefined) {
+          throw new Error("ci scope=next takes no pr= (it targets a future run, not a PR head)");
+        }
+        const filter = (key) => {
+          if (p[key] === undefined) return null;
+          const v = String(p[key]).trim();
+          if (v === "") throw new Error(`ci ${key}= must be non-empty`);
+          return v;
+        };
+        return { repo, scope: "next", branch: filter("branch"), workflow: filter("workflow"), pr: null };
       }
-      return { repo, scope: "latest", pr: String(p.pr).trim() };
+      throw new Error("ci scope must be 'latest' or 'next' (or use run_id=/sha=)");
     }
+    if (hasFilter) throw new Error("ci branch=/workflow= are only valid with scope=next");
     if (p.run_id !== undefined) {
       if (!String(p.run_id).trim()) throw new Error("ci run_id must be non-empty");
       return { repo, scope: "run_id", runId: String(p.run_id).trim(), pr: p.pr != null ? String(p.pr).trim() : null };
@@ -679,6 +703,23 @@ function conditionMatchesSignal(condition, signal, waitSessionId) {
       if (String(signal.payload?.repo ?? "").toLowerCase() !== params.repo.toLowerCase()) return false;
       if (params.scope === "run_id") return String(signal.payload?.run_id) === params.runId;
       if (params.scope === "sha") return signal.payload?.head_sha === params.sha;
+      if (params.scope === "next") {
+        // BOT-1507 — live-only: the first TERMINAL run for the repo. Never keys on
+        // subject_key (it is run:<id> for post-merge runs and owner/repo#n for PR
+        // runs — both are legitimate wakes); a null/empty conclusion is an
+        // in-progress signal and never terminal. Optional branch/workflow filters:
+        // branch is exact, workflow is the GitHub display name (case/space-insensitive).
+        const conclusion = signal.payload?.conclusion;
+        if (typeof conclusion !== "string" || conclusion.trim() === "") return false;
+        if (params.branch != null && signal.payload?.head_branch !== params.branch) return false;
+        if (params.workflow != null) {
+          const wf = signal.payload?.workflow_name;
+          if (typeof wf !== "string" || wf.trim().toLowerCase() !== params.workflow.trim().toLowerCase()) {
+            return false;
+          }
+        }
+        return true;
+      }
       // scope=latest: the PR's run (by subject owner/repo#pr or payload pr_number).
       return signal.subject_key === `${params.repo}#${params.pr}` ||
         (signal.payload?.pr_number != null && String(signal.payload.pr_number) === params.pr);

package/src/wait.mjs

@@ -75,10 +75,16 @@ CONDITIONS  (TYPE:key=val,key=val — repeat for several; --any wakes on the fir
                                       Host-shared; a silently-dead host is detected server-side
                                       (capacity_source_stale) via a host beacon — the client
                                       grace (default 900s) is a backstop, no longer the only guard.
-  ci:repo=<owner/repo>,{scope=latest,pr=<n> | run_id=<id> | sha=<sha>}
+  ci:repo=<owner/repo>,{scope=latest,pr=<n> | run_id=<id> | sha=<sha>
+                        | scope=next[,branch=<name>][,workflow=<name>]}
                                       a PR's CI reaching a terminal conclusion (owner-scoped);
                                       GitHub Actions or an external check_suite provider.
                                       A repo with no CI feed is rejected (no_signal_source).
+                                      scope=next is LIVE-ONLY: it wakes on the first terminal
+                                      run delivered AFTER arm (post-merge / cron / scheduled),
+                                      never replays a finished run, and needs no run_id/sha/pr.
+                                      Optional branch= (exact) / workflow= (GitHub workflow
+                                      DISPLAY name, case-insensitive) narrow that first run.
   staging-green:repo=<owner/repo>    verified automatic recovery of an enabled staging gate.
                                       Wakes only after a complete non-vacuous workflow success;
                                       manual resolutions, overrides, skipped, and neutral runs do not match.