@botbuddy/cli 1.34.3 → 1.35.0

package/src/pw/session.mjs

@@ -0,0 +1,997 @@
+// BOT-1318 — bb pw as a live, durable browser-acceptance lifecycle producer.
+//
+// One real lane browser session = one canonical BOT-1317 execution with
+// producer_kind=browser_acceptance, attempt=1 and an opaque source_run_id minted
+// before the first browser operation. Every lifecycle event (start, per-action
+// progress, verdict, heartbeat, terminal) is allocated a producer_event_id and
+// a monotonically increasing producer_sequence under an exclusive per-lane state
+// lock, appended durably to the BOT-1316 outbox BEFORE delivery, and delivered
+// through execution-ingest. Retries resend the SAME event, so the server's
+// per-execution idempotency collapses every replay/transport duplicate.
+//
+// Privacy: only verb, category, timing, result class and an origin+path route are
+// recorded. Typed/filled values, @ENV secrets, query strings, fragments, raw
+// Playwright output and error text never reach state, outbox or the server.
+import { createHash, randomUUID } from "node:crypto";
+import { chmod, link, mkdir, open, readFile, rename, stat, unlink, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { containsSensitive, createTelemetryOutbox } from "../telemetry-outbox.mjs";
+
+export const PRODUCER_KIND = "browser_acceptance";
+// BOT-1317's reaper abandons an execution 90 s after its last accepted event; a
+// live idle browser is kept fresh by a session-owned heartbeat at most every 20 s.
+export const HEARTBEAT_INTERVAL_MS = 15_000;
+// active_ms caps every idle gap between consecutive commands at 60 s.
+export const IDLE_GAP_CAP_MS = 60_000;
+export const ENVIRONMENTS = Object.freeze(["local", "preview", "staging", "production"]);
+export const VERDICTS = Object.freeze(["pass", "fail"]);
+const MAX_EVIDENCE_REFS = 32;
+const MAX_ROUTES = 32;
+const MAX_ROUTE_LENGTH = 256;
+// Bounded, synchronous delivery windows. Pre-action delivery runs CONCURRENTLY
+// with the browser command (no added latency); the post-action window is awaited
+// before the command returns so each result is live while the session runs.
+const PRE_ACTION_DELIVERY_MS = 2_000;
+const POST_ACTION_DELIVERY_MS = 2_500;
+const STATE_LOCK_ATTEMPTS = 400; // ≈10 s at 25 ms
+const EXEC_LOCK_ATTEMPTS = 4_800; // ≈120 s: commands on one lane run serially
+
+// A live closer holds the closing marker at most this long — under the 90 s reaper,
+// so a stalled close can never silence the heartbeat into a false abandonment.
+const CLOSING_GRACE_MS = 60_000;
+// After the heartbeat ends a session it keeps delivering the queued terminal for up to
+// this many ticks (~10 min at 15 s), since no lane command may ever run again.
+const TERMINAL_DRAIN_TICKS = 40;
+
+// A lock-reclaim guard is held for one read + unlink; older than this, its reclaimer died.
+const RECLAIM_GUARD_STALE_MS = 5_000;
+
+const CLEAN_CLOSE = Symbol("clean-close");
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+const hash = (value) => createHash("sha256").update(value).digest("hex");
+const safeSegment = (value) => String(value).toLowerCase().replace(/[^a-z0-9._-]/g, "_").slice(0, 128) || "_";
+
+// ── Pure helpers ─────────────────────────────────────────────────────────────
+
+/**
+ * command_ms = Σ measured (monotonic) durations of unique finished commands.
+ * active_ms  = union of command intervals + each idle gap between consecutive
+ *              commands capped at 60 s; time before the first / after the last
+ *              command is excluded. An effort proxy, NOT CPU time or attention.
+ * Commands [0,1000] and [121000,122000] → command 2000, active 62000, span 122000.
+ */
+export function computeTiming(actions = []) {
+  const intervals = [];
+  let commandMs = 0;
+  for (const action of actions) {
+    const start = Date.parse(action?.started_at ?? "");
+    const finish = Date.parse(action?.finished_at ?? "");
+    if (!Number.isFinite(start) || !Number.isFinite(finish)) continue;
+    intervals.push([start, Math.max(start, finish)]);
+    commandMs += Math.max(0, Math.round(Number(action.command_ms) || 0));
+  }
+  if (!intervals.length) return { command_ms: 0, active_ms: 0, action_span_ms: 0, first_action_at: null, last_action_at: null };
+  intervals.sort((a, b) => a[0] - b[0] || a[1] - b[1]);
+  let [currentStart, currentEnd] = intervals[0];
+  let active = 0;
+  let lastEnd = currentEnd;
+  for (const [start, end] of intervals.slice(1)) {
+    if (start <= currentEnd) { currentEnd = Math.max(currentEnd, end); }
+    else {
+      active += currentEnd - currentStart;
+      active += Math.min(start - currentEnd, IDLE_GAP_CAP_MS);
+      currentStart = start; currentEnd = end;
+    }
+    lastEnd = Math.max(lastEnd, end);
+  }
+  active += currentEnd - currentStart;
+  lastEnd = Math.max(lastEnd, currentEnd);
+  const first = intervals[0][0];
+  return {
+    command_ms: commandMs,
+    active_ms: active,
+    action_span_ms: Math.max(0, lastEnd - first),
+    first_action_at: new Date(first).toISOString(),
+    last_action_at: new Date(lastEnd).toISOString(),
+  };
+}
+
+// Route segments are an ALLOWLIST (Codex R38): a path segment may itself be the credential —
+// a JWT, UUID, reset/OTP code or invitation token, however short — so a segment survives only
+// as a plain lowercase word slug. Anything carrying a digit, an uppercase letter or other
+// characters, a long unbroken run, and the segment right after a credential keyword are
+// templated to `:id`. The server applies the same rule (executionLifecycle.ts isOpaqueSegment)
+// and refuses a route that still carries one. Over-redacting a route is preferred to
+// retaining a credential.
+const OPAQUE_SEGMENT_MIN = 16;
+const WORD_SLUG = /^[a-z]+(?:[-_.][a-z]+)*$/;
+export const CREDENTIAL_KEYWORDS = new Set([
+  "reset", "reset-password", "password-reset", "forgot-password", "recover", "recovery",
+  "verify", "verify-email", "verification", "confirm", "confirm-email", "confirmation",
+  "invite", "invites", "invitation", "invitations", "accept-invite",
+  "magic", "magic-link", "login-link", "passwordless", "token", "tokens", "otp", "code", "codes",
+  "activate", "activation", "unlock", "unsubscribe", "share",
+]);
+function isOpaqueSegment(segment, previous = "") {
+  if (segment === "") return false;
+  if (CREDENTIAL_KEYWORDS.has(previous.toLowerCase())) return true;
+  if (!WORD_SLUG.test(segment)) return true;
+  return segment.split(/[^a-z]+/).some((run) => run.length >= OPAQUE_SEGMENT_MIN);
+}
+
+// A decoded path the server accepts: every segment is `:id` or an allowed slug.
+function segmentsAllowed(path) {
+  const segments = path.split("/");
+  return segments.every((segment, index) => segment === ":id" || !isOpaqueSegment(segment, index ? segments[index - 1] : ""));
+}
+
+function decodeStable(value) {
+  let decoded = value;
+  for (;;) {
+    let next;
+    try { next = decodeURIComponent(decoded); } catch { return null; }
+    if (next === decoded) return decoded;
+    decoded = next;
+  }
+}
+
+/**
+ * Origin + path only. @ENV references, non-http(s) URLs and unparsable input are dropped,
+ * and so is a path carrying a credential (reset links, signed or provider-token paths) or a
+ * character the server's route contract refuses — never persisted, never quarantined. An
+ * opaque segment that may be a credential is templated to `:id`.
+ */
+export function sanitizeRoute(value) {
+  if (typeof value !== "string" || !value || value.startsWith("@ENV:")) return null;
+  let url;
+  try { url = new URL(value); } catch { return null; }
+  if (url.protocol !== "http:" && url.protocol !== "https:") return null;
+  if (containsSensitive(`${url.origin}${url.pathname}`)) return null;
+  // Percent-encoding must not hide a credential: screen the path decoded until stable.
+  // Every changing decode shortens the string, so the loop ends within its length;
+  // an undecodable path is dropped, not trusted.
+  let decoded = url.pathname;
+  for (;;) {
+    let next;
+    try { next = decodeURIComponent(decoded); } catch { return null; }
+    if (containsSensitive(next)) return null;
+    if (next === decoded) break;
+    decoded = next;
+  }
+  const raw = url.pathname.split("/");
+  const plain = raw.map((segment) => decodeStable(segment) ?? "\u0000");
+  const path = raw.map((segment, index) => (isOpaqueSegment(plain[index], index ? plain[index - 1] : "") ? ":id" : segment)).join("/");
+  const route = `${url.origin}${path}`;
+  if (route.length > MAX_ROUTE_LENGTH || /[?#@\s]/.test(route)) return null;
+  // An encoded `/` can split a segment once decoded; the server screens the decoded path,
+  // so a route it would still refuse is dropped rather than quarantined.
+  const decodedPath = decodeStable(path);
+  if (decodedPath === null || !segmentsAllowed(decodedPath)) return null;
+  return route;
+}
+
+/** A bounded error class; the raw text is inspected, never stored. */
+export function errorClassOf(text) {
+  const value = String(text ?? "").toLowerCase();
+  if (/timeout|timed out/.test(value)) return "timeout";
+  if (/daemon is not running|not running|socket is gone|connection (?:dropped|failed|refused)/.test(value)) return "browser_not_running";
+  if (/stale|ref .*not found|no element .*ref|unknown ref/.test(value)) return "stale_ref";
+  if (/net::err_|navigation|err_name_not_resolved|err_connection/.test(value)) return "navigation_error";
+  if (/strict mode violation/.test(value)) return "strict_mode_violation";
+  if (/not visible|not enabled|intercepts pointer|not attached|detached/.test(value)) return "element_not_actionable";
+  const exit = /^exit (\d{1,3})$/.exec(value.trim());
+  if (exit) return `exit_${exit[1]}`;
+  return "action_failed";
+}
+
+export function resolveEnvironment({ flag = null, env = {} } = {}) {
+  const raw = flag ?? (env.BB_PW_ENV ? env.BB_PW_ENV : null);
+  if (raw === null || raw === undefined || raw === "") return { environment: null };
+  if (!ENVIRONMENTS.includes(raw)) return { error: `bb-pw: environment must be one of ${ENVIRONMENTS.join("|")} (got "${raw}").` };
+  return { environment: raw };
+}
+
+export function sessionStatePath({ root, tenant, repository, host, lane }) {
+  return join(root, "pw-sessions", safeSegment(tenant), hash(String(repository).toLowerCase()).slice(0, 32), safeSegment(host), `lane-${lane}.json`);
+}
+
+function hasLiveInflight(state) {
+  return state.actions.some((action) => !action.result && pidAlive(action.owner_pid));
+}
+
+function pidAlive(pid) {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try { process.kill(pid, 0); return true; } catch (error) { return error?.code === "EPERM"; }
+}
+
+// An exclusive lock file holding the owner PID plus a per-acquisition nonce. A lock whose
+// same-host owner is provably gone is reclaimed; an incomplete record is never age-reclaimed.
+export async function withLock(lockPath, fn, { attempts = STATE_LOCK_ATTEMPTS, waitMs = 25 } = {}) {
+  await mkdir(dirname(lockPath), { recursive: true, mode: 0o700 });
+  const token = JSON.stringify({ pid: process.pid, nonce: randomUUID() });
+  // The complete record is written to a private temp file first and then hard-linked into
+  // place (link fails with EEXIST if a lock exists), so the lock path is never visible
+  // empty or partial — a crash mid-publish can never strand an unprovable lock.
+  const staged = `${lockPath}.${process.pid}.${randomUUID()}.tmp`;
+  await writeFile(staged, token, { mode: 0o600 });
+  try {
+  for (let attempt = 0; ; attempt++) {
+    try {
+      await link(staged, lockPath);
+      break;
+    } catch (error) {
+      if (error?.code !== "EEXIST") throw error;
+      let raw = null;
+      let owner = null;
+      try { raw = await readFile(lockPath, "utf8"); owner = JSON.parse(raw); } catch { /* being written */ }
+      if (Number.isInteger(owner?.pid) && !pidAlive(owner.pid)) { await reclaimStaleLock(lockPath, raw); continue; }
+      if (attempt >= attempts) throw Object.assign(new Error("bb-pw: the lane's browser-session state is busy"), { code: "pw_session_lock_busy" });
+      await sleep(waitMs);
+    }
+  }
+  } finally { await unlink(staged).catch(() => {}); }
+  try { return await fn(); } finally { await releaseLock(lockPath, token); }
+}
+
+// Remove a dead owner's lock only if the file still holds THAT exact record, checked and
+// removed under a short reclaim guard — so two reclaimers can never delete a new owner's lock.
+async function reclaimStaleLock(lockPath, observed) {
+  const guard = `${lockPath}.reclaim`;
+  let handle;
+  try { handle = await open(guard, "wx", 0o600); } catch (error) {
+    if (error?.code !== "EEXIST") throw error;
+    // The guard is held only for one read + unlink; an old one belongs to a killed reclaimer.
+    try { const info = await stat(guard); if (Date.now() - info.mtimeMs > RECLAIM_GUARD_STALE_MS) await unlink(guard).catch(() => {}); } catch { /* gone */ }
+    await sleep(5);
+    return;
+  }
+  try {
+    let current = null;
+    try { current = await readFile(lockPath, "utf8"); } catch { /* already gone */ }
+    if (current !== null && current === observed) await unlink(lockPath).catch(() => {});
+  } finally {
+    await handle.close().catch(() => {});
+    await unlink(guard).catch(() => {});
+  }
+}
+
+async function releaseLock(lockPath, token) {
+  let current = null;
+  try { current = await readFile(lockPath, "utf8"); } catch { return; }
+  if (current === token) await unlink(lockPath).catch(() => {});
+}
+
+async function syncDirectoryEntry(directory) {
+  let handle;
+  try { handle = await open(directory, "r"); await handle.sync(); } finally { await handle?.close(); }
+}
+
+// The rename publishes the new state; syncing the directory makes that entry itself durable
+// across a power loss, as the outbox's atomicJson does (Codex R34), so recovery can never load
+// a previous state and reuse an already-appended event id or sequence.
+export async function writeJsonAtomic(path, value, { syncDirectory = syncDirectoryEntry } = {}) {
+  await mkdir(dirname(path), { recursive: true, mode: 0o700 });
+  const temp = `${path}.${process.pid}.${randomUUID()}.tmp`;
+  const handle = await open(temp, "w", 0o600);
+  try { await handle.writeFile(`${JSON.stringify(value)}\n`); await handle.sync(); } finally { await handle.close(); }
+  await chmod(temp, 0o600);
+  await rename(temp, path);
+  await syncDirectory(dirname(path));
+}
+
+// ── Summary / outcome derivations (replacements, never additive rollups) ─────
+
+function summarize(state) {
+  const finished = state.actions.filter((action) => action.result);
+  const measured = finished.filter((action) => action.result !== "interrupted");
+  const timing = computeTiming(measured);
+  const count = (predicate) => finished.filter(predicate).length;
+  // Only a navigation that SUCCEEDED exercised its route: readiness treats every listed
+  // path as verified, so a failed or interrupted open/goto must never appear here.
+  const routes = [...new Set(finished.filter((action) => action.result === "succeeded").map((action) => action.route).filter(Boolean))].slice(0, MAX_ROUTES);
+  return {
+    actions_total: finished.length,
+    actions_succeeded: count((action) => action.result === "succeeded"),
+    actions_failed: count((action) => action.result === "failed"),
+    actions_interrupted: count((action) => action.result === "interrupted"),
+    command_ms: timing.command_ms,
+    active_ms: timing.active_ms,
+    action_span_ms: timing.action_span_ms,
+    first_action_at: timing.first_action_at,
+    last_action_at: timing.last_action_at,
+    navigations: count((action) => action.category === "navigate" && action.result === "succeeded"),
+    screenshots: count((action) => action.category === "screenshot" && action.result === "succeeded"),
+    snapshots: count((action) => action.category === "snapshot" && action.result === "succeeded"),
+    interactions: count((action) => action.category === "interaction" && action.result === "succeeded"),
+    distinct_routes: routes,
+    acceptance_verdict: state.verdict ?? "not_asserted",
+  };
+}
+
+// Clean close: passed when no action failed/was interrupted and the verdict is
+// not fail; otherwise failed. An explicit pass never erases a recorded failure.
+function closeOutcome(state) {
+  // A session closed before any browser command ran (e.g. orphaned right after its start
+  // was appended) exercised nothing: it is abandoned, never a successful execution.
+  if (state.actions.length === 0) return "abandoned";
+  const failed = state.actions.some((action) => action.result === "failed" || action.result === "interrupted");
+  return failed || state.verdict === "fail" ? "failed" : "passed";
+}
+
+function actionView(action) {
+  return Object.fromEntries(Object.entries({
+    action_id: action.action_id, verb: action.verb, category: action.category,
+    phase: action.result ? "finished" : "started", started_at: action.started_at,
+    finished_at: action.finished_at ?? undefined, command_ms: action.command_ms ?? undefined,
+    result: action.result ?? undefined, error_class: action.error_class ?? undefined, route: action.route ?? undefined,
+  }).filter(([, value]) => value !== undefined && value !== null));
+}
+
+// ── Lane tracker ─────────────────────────────────────────────────────────────
+
+function createLaneTracker({ root, tenant, repository, host, lane, getOutbox, deliver, now, monotonic, gitInfo, spawnHeartbeat, onAppended = null, onStateWrite = null }) {
+  const statePath = sessionStatePath({ root, tenant, repository, host, lane });
+  const stateLock = `${statePath}.lock`;
+  const execLock = `${statePath}.exec.lock`;
+  const iso = () => now().toISOString();
+
+  // Every write of this lane's state goes through here; `onStateWrite` is a test seam
+  // that can inject a storage failure portably (unlike chmod, which root ignores).
+  async function persistState(state) {
+    onStateWrite?.(state);
+    await writeJsonAtomic(statePath, state);
+  }
+
+  async function readState() {
+    try { return JSON.parse(await readFile(statePath, "utf8")); } catch (error) { if (error?.code === "ENOENT") return null; throw error; }
+  }
+
+  const contextFor = (state, phase) => ({ ...state.context, phase });
+
+  // Allocate + durably append under the state lock. The state is only
+  // persisted by the caller after every append in the step succeeded, so a
+  // failed append (e.g. full disk) never advances the sequence or the action.
+  async function emit(state, suffix, action, { phase = "testing", browser = {}, occurredAt = iso(), ...extra } = {}) {
+    const sequence = state.next_sequence;
+    const event = {
+      schema_version: 1, action, producer_kind: PRODUCER_KIND, source_run_id: state.source_run_id, attempt: 1,
+      producer_event_id: `${state.source_run_id}:${suffix}`, producer_sequence: sequence, occurred_at: occurredAt,
+      context: contextFor(state, phase), browser: { lane: String(lane), host, ...browser }, ...extra,
+    };
+    // Write-ahead: the event and its sequence are durable in state BEFORE the outbox
+    // append, so a crash between the append and the caller's state write can never
+    // let a later event reuse this id or sequence; recovery re-appends it unchanged.
+    state.pending_events = [...(state.pending_events ?? []), event];
+    state.next_sequence = sequence + 1;
+    await persistState(state);
+    await appendDurably(event);
+    onAppended?.(event);
+    state.pending_events = state.pending_events.filter((item) => item.producer_event_id !== event.producer_event_id);
+    return event;
+  }
+
+  async function appendDurably(event) {
+    const outbox = await getOutbox();
+    // The shared outbox lock is held while a bounded replay delivers; a busy
+    // lock is retried (bounded) rather than refusing the browser command.
+    for (let attempt = 0; ; attempt++) {
+      try { await outbox.append(event); return; } catch (error) {
+        if (error?.code !== "telemetry_outbox_lock_busy" || attempt >= 4) throw error;
+      }
+    }
+  }
+
+  // Read state for a locked step, first re-appending any write-ahead events a previous
+  // process made durable in state but may not have appended (idempotent by event id).
+  async function readLockedState() {
+    const state = await readState();
+    if (!state?.pending_events?.length) return state;
+    for (const event of state.pending_events) await appendDurably(event);
+    state.pending_events = [];
+    await persistState(state);
+    return state;
+  }
+
+  function evidenceRefs(state) { return state.evidence_refs.slice(0, MAX_EVIDENCE_REFS); }
+
+  async function emitActionFinish(state, action) {
+    return emit(state, `${action.action_id}:finish`, "progress", {
+      occurredAt: action.finished_at ?? iso(),
+      progress: { completed: state.actions.filter((item) => item.result).length, phase: "testing", current_item: action.verb },
+      browser: { action: actionView(action), summary: summarize(state) },
+      evidence_refs: evidenceRefs(state),
+    });
+  }
+
+  async function interruptUnfinished(state) {
+    for (const action of state.actions) {
+      if (action.result) continue;
+      action.result = "interrupted";
+      action.finished_at = null;
+      action.command_ms = null;
+      await emitActionFinish(state, action);
+    }
+  }
+
+  // `outcome` may be CLEAN_CLOSE: the clean-close outcome is then derived only
+  // AFTER unfinished actions are marked interrupted, so an interrupted action can
+  // never yield `passed` (Codex R2). No explicit outcome may be `passed` either
+  // once an action was interrupted or failed.
+  async function terminalize(state, requested, diagnostic = null) {
+    await interruptUnfinished(state);
+    let outcome = requested === CLEAN_CLOSE ? closeOutcome(state) : requested;
+    if (outcome === "passed" && closeOutcome(state) !== "passed") outcome = "failed";
+    const terminalAt = iso();
+    const fields = {
+      phase: outcome === "passed" ? "complete" : "failed", occurredAt: terminalAt, outcome,
+      browser: { summary: summarize(state) }, evidence_refs: evidenceRefs(state),
+      ...(diagnostic ? { diagnostic } : {}),
+    };
+    // The terminal state is durable in the SAME write-ahead step as the terminal event,
+    // so a crash after the outbox append can never leave the lane active (Codex R19):
+    // recovery re-appends the unchanged terminal and the closed execution is never
+    // extended or re-terminalized with a different outcome.
+    state.status = "terminal";
+    state.outcome = outcome;
+    state.terminal_at = terminalAt;
+    state.closing = false;
+    await emit(state, "terminal", "terminal", fields);
+  }
+
+  async function newSession(environment, { startedAt = iso() } = {}) {
+    const git = (await gitInfo?.()) ?? {};
+    const context = { repo: repository, environment, runner: "bb-pw", health: "verified" };
+    if (git.ticket) context.ticket = String(git.ticket);
+    if (git.branch && git.branch !== "HEAD") context.branch = String(git.branch);
+    if (git.prNumber !== null && git.prNumber !== undefined && git.prNumber !== "") context.pr = String(git.prNumber);
+    if (git.sha) context.sha = String(git.sha);
+    const state = {
+      schema_version: 1, tenant, repository, host, lane: String(lane), producer_kind: PRODUCER_KIND, attempt: 1,
+      source_run_id: randomUUID(), status: "active", environment, context, started_at: startedAt, next_sequence: 0,
+      actions: [], evidence_refs: [], verdict: null, daemon_generation: null, heartbeat_pid: null,
+      execution_id: null, delivery: { state: "pending", queued_count: null, last_error_class: null }, closing: false,
+      outcome: null, terminal_at: null, reconciliation: null,
+    };
+    await emit(state, "start", "start", { occurredAt: state.started_at, browser: {} });
+    return state;
+  }
+
+  /** Apply accepted receipts for this state's execution; true when anything changed. */
+  function applyReceipts(state, receipts) {
+    let changed = false;
+    for (const { event, result } of receipts) {
+      if (event.source_run_id !== state.source_run_id) continue;
+      if (typeof result.execution_id === "string" && result.execution_id && state.execution_id !== result.execution_id) { state.execution_id = result.execution_id; changed = true; }
+      if (result.receipt === "terminal_conflict_retired") {
+        // The server's terminal is canonical: adopt its outcome, keeping the locally derived
+        // one for diagnosis, so `bb pw status` never disagrees with the execution (Codex R27).
+        const canonical = typeof result.outcome === "string" && result.outcome ? result.outcome : null;
+        state.reconciliation = {
+          receipt: "terminal_conflict", producer_event_id: event.producer_event_id, observed_at: iso(),
+          ...(canonical ? { outcome: canonical, local_outcome: state.outcome ?? null } : {}),
+        };
+        if (canonical && state.status === "terminal") state.outcome = canonical;
+        changed = true;
+      }
+      // The server already ended this run (e.g. reaped it as abandoned after the machine
+      // slept past the grace): stop claiming it is live, so the next command starts fresh.
+      if (state.status === "active" && typeof result.outcome === "string" && result.outcome) {
+        state.status = "terminal";
+        state.outcome = result.outcome;
+        state.terminal_at = iso();
+        state.closing = false;
+        state.reconciliation = { receipt: "server_terminal", outcome: result.outcome, producer_event_id: event.producer_event_id, producer_sequence: event.producer_sequence, observed_at: iso() };
+        changed = true;
+      }
+    }
+    return changed;
+  }
+
+  /** The lane's delivery view after a replay; quarantine counts are sticky. */
+  function refreshDelivery(state, { queued, quarantined, status }) {
+    const priorQuarantined = Number(state.delivery?.quarantined_count ?? 0);
+    state.delivery = { state: queued || quarantined || priorQuarantined ? "degraded" : "delivered", queued_count: queued, quarantined_count: priorQuarantined + quarantined, last_error_class: quarantined ? "rejected_quarantined" : status?.last_error_class ?? null, last_attempt_at: iso() };
+  }
+
+  async function deliverPending(windowMs) {
+    const outbox = await getOutbox();
+    const receipts = [];
+    const rejected = [];
+    let quarantinedTotal = 0;
+    try {
+      const replayed = await outbox.replay(async (event) => {
+        const result = await deliver(event);
+        if (result?.accepted) receipts.push({ event, result });
+        else if (result?.permanent) rejected.push(event);
+        return result;
+      }, { maxEvents: 64, deadline: Date.now() + windowMs });
+      quarantinedTotal = replayed?.quarantined ?? 0;
+    } catch { /* a busy/unavailable outbox is degradation, never an action failure */ }
+    // Queued state is per owning lane: the outbox is shared, so its total is not any lane's backlog.
+    const ownerKey = (event) => (event?.browser?.lane === undefined || event?.browser?.lane === null ? null : `${event.browser.host ?? host}\u0000${event.browser.lane}`);
+    const status = await outbox.status({ ownerOf: ownerKey }).catch(() => null);
+    const queuedFor = (laneHost, laneId) => (status ? status.queued_by_owner?.[`${laneHost}\u0000${laneId}`] ?? 0 : null);
+    const queued = queuedFor(host, String(lane));
+    // The outbox is shared by every lane of this repository: a receipt or a permanent
+    // rejection for another lane's event is applied to THAT lane's state, never
+    // discarded or charged to the lane that happened to replay it.
+    const laneKey = (event) => {
+      const eventHost = event.browser?.host ?? host;
+      const eventLane = String(event.browser?.lane ?? lane);
+      return eventHost === host && eventLane === String(lane) ? null : sessionStatePath({ root, tenant, repository, host: eventHost, lane: eventLane });
+    };
+    const otherQueued = new Map();
+    const own = { receipts: [], rejected: [] };
+    const others = new Map();
+    const bucket = (event) => {
+      const otherPath = laneKey(event);
+      if (!otherPath) return own;
+      if (!others.has(otherPath)) {
+        others.set(otherPath, { receipts: [], rejected: [] });
+        otherQueued.set(otherPath, queuedFor(event.browser?.host ?? host, String(event.browser?.lane)));
+      }
+      return others.get(otherPath);
+    };
+    for (const receipt of receipts) bucket(receipt.event).receipts.push(receipt);
+    for (const event of rejected) bucket(event).rejected.push(event);
+    // A record the outbox could not even parse has no known owner; it stays with this lane.
+    const unowned = Math.max(0, quarantinedTotal - rejected.length);
+    // A rejection is charged only to the session (source_run_id) it belongs to — never to a
+    // later session on the same lane.
+    const quarantinedFor = (laneState, laneRejected) => laneRejected.filter((event) => event.source_run_id === laneState.source_run_id).length;
+    for (const [otherPath, other] of others) {
+      await withLock(`${otherPath}.lock`, async () => {
+        let otherState;
+        try { otherState = JSON.parse(await readFile(otherPath, "utf8")); } catch { return; }
+        applyReceipts(otherState, other.receipts);
+        // The owning lane may be terminal with no heartbeat left: its delivery view is refreshed here.
+        refreshDelivery(otherState, { queued: otherQueued.get(otherPath) ?? 0, quarantined: quarantinedFor(otherState, other.rejected), status });
+        await writeJsonAtomic(otherPath, otherState);
+      }).catch(() => { /* that lane's next delivery or status reconciles it */ });
+    }
+    let quarantined = unowned + own.rejected.length;
+    let serverEnded = null;
+    await withLock(stateLock, async () => {
+      const state = await readLockedState();
+      if (!state) return;
+      const wasActive = state.status === "active";
+      applyReceipts(state, own.receipts);
+      quarantined = unowned + quarantinedFor(state, own.rejected);
+      if (wasActive && state.reconciliation?.receipt === "server_terminal" && state.status === "terminal") serverEnded = state.outcome;
+      refreshDelivery(state, { queued, quarantined, status });
+      await persistState(state);
+    }).catch(() => {});
+    return { queued: queued ?? 0, quarantined, degraded: Boolean(queued) || quarantined > 0, server_ended: serverEnded };
+  }
+
+  // Actions the server never accepted because it had already ended this run (e.g. reaped it
+  // as abandoned after the machine slept past the grace): every finished action whose start
+  // was at or after the event that discovered the server's terminal (Codex R37).
+  function lostToServerEnd(state) {
+    const found = state?.reconciliation;
+    if (state?.status !== "terminal" || found?.receipt !== "server_terminal" || !Number.isInteger(found.producer_sequence)) return [];
+    return state.actions.filter((action) => action.result && action.result !== "interrupted"
+      && Number.isInteger(action.start_sequence) && action.start_sequence >= found.producer_sequence);
+  }
+
+  // Re-record lost actions, in order and with their measured intervals, in ONE fresh session
+  // for the same environment, so each real browser action reaches canonical telemetry once.
+  async function rehome(state, lost, probe) {
+    const fresh = await newSession(state.environment, { startedAt: lost[0].started_at });
+    const live = await probe();
+    if (live.alive) fresh.daemon_generation = live.generation;
+    fresh.reconciliation = { receipt: "rehomed", from_source_run_id: state.source_run_id, actions: lost.length, observed_at: iso() };
+    for (const original of lost) {
+      const action = {
+        action_id: `a${fresh.actions.length + 1}`, verb: original.verb, category: original.category, started_at: original.started_at,
+        finished_at: null, command_ms: null, result: null, error_class: null, route: original.route ?? null, owner_pid: process.pid,
+      };
+      fresh.actions.push(action);
+      const startEvent = await emit(fresh, `${action.action_id}:start`, "progress", {
+        occurredAt: action.started_at,
+        progress: { completed: fresh.actions.filter((item) => item.result).length, phase: "testing", current_item: action.verb },
+        browser: { action: actionView(action) },
+      });
+      action.start_sequence = startEvent.producer_sequence;
+      Object.assign(action, { finished_at: original.finished_at, command_ms: original.command_ms, result: original.result, error_class: original.error_class });
+      for (const ref of state.evidence_refs) {
+        const [kind, target] = ref.split(":");
+        if (target === `${state.source_run_id}/${original.action_id}` && fresh.evidence_refs.length < MAX_EVIDENCE_REFS) fresh.evidence_refs.push(`${kind}:${fresh.source_run_id}/${action.action_id}`);
+      }
+      await emitActionFinish(fresh, action);
+    }
+    // No live browser left: the recovered session can never close, so it ends as observed.
+    if (!live.alive) await terminalize(fresh, "crashed", { code: "browser_daemon_exited", category: "crash" });
+    await persistState(fresh);
+    return fresh;
+  }
+
+  function environmentGuard(state, environment) {
+    if (environment && state?.status === "active" && state.environment !== environment) {
+      return `bb-pw: lane ${lane}'s open browser session is tracked as environment "${state.environment}", not "${environment}". Close it before starting a ${environment} session.`;
+    }
+    return null;
+  }
+
+  // Returns { failed: true } when the session needs a heartbeat but none could be started
+  // (Codex R36): the caller reports it, since an idle session would otherwise be reaped
+  // as abandoned within the server's grace window. The next action retries the spawn.
+  async function ensureHeartbeat() {
+    let failed = false;
+    // A resolver without heartbeat machinery (no spawnHeartbeat) has nothing to start.
+    if (typeof spawnHeartbeat !== "function") return { failed };
+    await withLock(stateLock, async () => {
+      const state = await readLockedState();
+      // A live browser generation, or an in-flight first command (e.g. a long initial open,
+      // before any generation is known) whose owner is still alive, needs a heartbeat.
+      if (!state || state.status !== "active" || (!state.daemon_generation && !hasLiveInflight(state))) return;
+      if (state.heartbeat_pid && pidAlive(state.heartbeat_pid)) return;
+      let pid = null;
+      try { pid = await spawnHeartbeat({ root, tenant, repository, host, lane: String(lane), source_run_id: state.source_run_id }); } catch { pid = null; }
+      state.heartbeat_pid = Number.isInteger(pid) ? pid : null;
+      failed = state.heartbeat_pid === null;
+      await persistState(state);
+    }).catch(() => { failed = true; });
+    return { failed };
+  }
+
+  return {
+    statePath,
+
+    async status() {
+      const state = await readState().catch(() => null);
+      if (!state) return { tracked: true, active: false };
+      const summary = summarize(state);
+      const wallEnd = state.terminal_at ? Date.parse(state.terminal_at) : now().getTime();
+      return {
+        tracked: true, active: state.status === "active", status: state.status,
+        source_run_id: state.source_run_id, producer_kind: state.producer_kind, attempt: state.attempt,
+        execution_id: state.execution_id ?? null, environment: state.environment,
+        acceptance_verdict: summary.acceptance_verdict, outcome: state.outcome ?? null,
+        started_at: state.started_at, terminal_at: state.terminal_at ?? null,
+        wall_ms: Math.max(0, wallEnd - Date.parse(state.started_at)),
+        command_ms: summary.command_ms, active_ms: summary.active_ms,
+        actions_total: summary.actions_total, actions_succeeded: summary.actions_succeeded,
+        actions_failed: summary.actions_failed, actions_interrupted: summary.actions_interrupted,
+        delivery: state.delivery ?? null, reconciliation: state.reconciliation ?? null,
+      };
+    },
+
+    /**
+     * Begin one lane command. Holds the lane's exec lock until finish/release so
+     * commands on a lane (and their measured intervals) are strictly serial.
+     */
+    async begin({ verb, category, route, environment, probe }) {
+      let releaseExec;
+      const held = new Promise((resolve) => { releaseExec = resolve; });
+      let acquired;
+      const lockReady = new Promise((resolve, reject) => {
+        withLock(execLock, () => { resolve(); return held; }, { attempts: EXEC_LOCK_ATTEMPTS }).catch(reject);
+      });
+      try { await lockReady; acquired = true; } catch (error) { return { error: error.message, exitCode: 1 }; }
+      const release = () => { if (acquired) { acquired = false; releaseExec(); } };
+      let started;
+      let reconciled = false;
+      try {
+        started = await withLock(stateLock, async () => {
+          let state = await readLockedState();
+          if (state?.status === "active") {
+            const live = await probe();
+            if (!live.alive || (state.daemon_generation && live.generation !== state.daemon_generation)) {
+              // Observed daemon/owner death (or an open that never produced a browser).
+              await terminalize(state, state.daemon_generation ? "crashed" : CLEAN_CLOSE, state.daemon_generation ? { code: "browser_daemon_exited", category: "crash" } : null);
+              await persistState(state);
+              reconciled = true;
+            } else {
+              let changed = false;
+              if (state.actions.some((action) => !action.result)) {
+                await interruptUnfinished(state);
+                reconciled = true;
+                changed = true;
+              }
+              // An open that died after starting the browser never recorded it: adopt the live
+              // generation now so the recovered session owns a heartbeat.
+              if (!state.daemon_generation && live.generation) {
+                state.daemon_generation = live.generation;
+                changed = true;
+              }
+              if (changed) await persistState(state);
+            }
+          }
+          const mismatch = environmentGuard(state, environment);
+          if (mismatch) return { error: mismatch };
+          // An open always starts a new session, so its required environment is checked
+          // BEFORE the active session is closed: a refused open never ends it (Codex R25).
+          if (verb === "open" && !environment) return { error: `bb-pw: a tracked browser session needs an environment — pass --environment <${ENVIRONMENTS.join("|")}> before the lane, or set BB_PW_ENV.` };
+          if (verb === "open" && state?.status === "active") {
+            // A new explicit open ends the previous session with clean-close semantics.
+            await terminalize(state, CLEAN_CLOSE);
+            await persistState(state);
+          }
+          if (state?.status !== "active") {
+            let adopted = null;
+            if (verb !== "open") {
+              const live = await probe();
+              if (!live.alive) return { tracked: false };
+              adopted = live.generation ?? null;
+            }
+            if (!environment) return { error: `bb-pw: a tracked browser session needs an environment — pass --environment <${ENVIRONMENTS.join("|")}> before the lane, or set BB_PW_ENV.` };
+            state = await newSession(environment);
+            // Adopting an already-running browser: record it so the session owns a heartbeat.
+            if (adopted) state.daemon_generation = adopted;
+          }
+          const action = {
+            action_id: `a${state.actions.length + 1}`, verb, category, started_at: iso(), finished_at: null,
+            command_ms: null, result: null, error_class: null, route: sanitizeRoute(route),
+            owner_pid: process.pid,
+          };
+          state.actions.push(action);
+          const startEvent = await emit(state, `${action.action_id}:start`, "progress", {
+            progress: { completed: state.actions.filter((item) => item.result).length, phase: "testing", current_item: verb },
+            browser: { action: actionView(action) },
+          });
+          action.start_sequence = startEvent.producer_sequence;
+          await persistState(state);
+          return { tracked: true, sourceRunId: state.source_run_id, actionId: action.action_id };
+        });
+      } catch (error) {
+        release();
+        return { error: `bb-pw: browser telemetry could not durably record the action (${error?.code ?? error?.message ?? "error"}); nothing was run.`, exitCode: 1 };
+      }
+      if (!started.tracked) {
+        // A reconciliation (observed crash / interrupted action) is still reported.
+        if (reconciled) await deliverPending(POST_ACTION_DELIVERY_MS);
+        release();
+        return started.error ? { ...started, exitCode: 2 } : started;
+      }
+      // An adopted or recovered live browser owns its heartbeat BEFORE the command runs,
+      // so a long first command can never outlive the server's reaper window (idempotent).
+      await ensureHeartbeat();
+      const startMono = monotonic();
+      const pre = deliverPending(PRE_ACTION_DELIVERY_MS);
+      const { sourceRunId, actionId } = started;
+      return {
+        tracked: true, sourceRunId, actionId,
+        async finish({ ok, errorText = null, exitCode = null, evidenceKind = null }) {
+          const commandMs = Math.max(0, Math.round(monotonic() - startMono));
+          let persistFailed = null;
+          let rehomed = 0;
+          // Settle the concurrent pre-action delivery first: a server terminal it discovered
+          // must be known before this action's result is recorded (Codex R37).
+          const preDelivery = await pre;
+          try {
+            await withLock(stateLock, async () => {
+              const state = await readLockedState();
+              if (!state || state.source_run_id !== sourceRunId) return;
+              const serverEnded = state.status === "terminal" && state.reconciliation?.receipt === "server_terminal";
+              if (state.status !== "active" && !serverEnded) return;
+              const action = state.actions.find((item) => item.action_id === actionId);
+              if (!action || action.result) return;
+              action.finished_at = iso();
+              action.command_ms = commandMs;
+              action.result = ok ? "succeeded" : "failed";
+              action.error_class = ok ? null : errorClassOf(errorText ?? `exit ${exitCode}`);
+              if (ok && evidenceKind && state.evidence_refs.length < MAX_EVIDENCE_REFS) state.evidence_refs.push(`${evidenceKind}:${sourceRunId}/${actionId}`);
+              if (serverEnded) {
+                // The run ended server-side before this action was accepted: record it (and any
+                // other action the server never accepted) in a fresh session instead of dropping it.
+                const lost = lostToServerEnd(state);
+                if (lost.length) { await rehome(state, lost, probe); rehomed = lost.length; }
+                return;
+              }
+              if (action.verb === "open") {
+                const live = await probe();
+                // A failed open that still left a usable browser is recoverable: it keeps a heartbeat.
+                if (live.alive) state.daemon_generation = live.generation;
+                // An open that left no live browser can never recover or close: end it with what
+                // was observed now — failed if the open failed, crashed if it succeeded but the
+                // daemon is already gone — instead of letting the reaper call it abandoned.
+                if (!live.alive && !state.daemon_generation) {
+                  await emitActionFinish(state, action);
+                  await terminalize(state, ok ? "crashed" : "failed", ok ? { code: "browser_daemon_exited", category: "crash" } : { code: action.error_class, category: "open" });
+                  await persistState(state);
+                  return;
+                }
+              }
+              await emitActionFinish(state, action);
+              await persistState(state);
+            });
+          } catch (error) {
+            // The action already ran and keeps its exit code; the lost result must still be visible.
+            persistFailed = errorClassOf(error?.code ?? error?.message ?? "error");
+          }
+          let post = await deliverPending(POST_ACTION_DELIVERY_MS);
+          if (post.server_ended && !rehomed) {
+            // The server's terminal surfaced only now (e.g. this action's start was still queued
+            // when the pre-action delivery ran): re-record what it never accepted.
+            await withLock(stateLock, async () => {
+              const state = await readLockedState();
+              if (!state || state.source_run_id !== sourceRunId) return;
+              const lost = lostToServerEnd(state);
+              if (lost.length) { await rehome(state, lost, probe); rehomed = lost.length; }
+            }).catch(() => {});
+            if (rehomed) post = { ...(await deliverPending(POST_ACTION_DELIVERY_MS)), server_ended: post.server_ended };
+          }
+          // A rejection during the concurrent pre-action delivery is reported too.
+          const quarantined = post.quarantined + (preDelivery?.quarantined ?? 0);
+          const heartbeat = await ensureHeartbeat();
+          const delivery = {
+            ...post, quarantined, persist_failed: persistFailed, heartbeat_failed: heartbeat.failed, rehomed,
+            server_ended: post.server_ended ?? preDelivery?.server_ended ?? null,
+            degraded: post.degraded || quarantined > 0 || Boolean(persistFailed) || heartbeat.failed,
+          };
+          release();
+          return delivery;
+        },
+        async cancel(signal) {
+          try {
+            await withLock(stateLock, async () => {
+              const state = await readLockedState();
+              if (!state || state.source_run_id !== sourceRunId || state.status !== "active") return;
+              await terminalize(state, "canceled", { code: "signal", category: "signal", signal: String(signal) });
+              await persistState(state);
+            });
+          } catch { /* best effort on the way out */ }
+          await deliverPending(POST_ACTION_DELIVERY_MS);
+        },
+        release,
+      };
+    },
+
+    /** close: terminalize the active session once; repeated close is a no-op. */
+    /**
+     * close: terminalize the active session once; repeated close is a no-op.
+     * A clean close is passed/failed by closeOutcome. A browser daemon that was
+     * already gone (or replaced) before close is `crashed`; a close that exits
+     * non-zero with the browser still owned is `failed` with a bounded error
+     * class. A failed close never terminalizes as passed (Codex R1 P1).
+     * `run` returns `{ code, errorText }` (errorText is classified, never stored).
+     */
+    async close({ environment, run, probe }) {
+      return withLock(execLock, async () => {
+        const marked = await withLock(stateLock, async () => {
+          const state = await readLockedState();
+          if (!state || state.status !== "active") return { active: false };
+          const mismatch = environmentGuard(state, environment);
+          if (mismatch) return { error: mismatch };
+          state.closing = true;
+          state.closing_pid = process.pid;
+          state.closing_since = iso();
+          await persistState(state);
+          return { active: true, sourceRunId: state.source_run_id, generation: state.daemon_generation };
+        });
+        if (marked.error) return { error: marked.error };
+        const live = marked.active && probe ? await probe() : { alive: true, generation: marked.generation ?? null };
+        const ranAt = await run();
+        const code = typeof ranAt === "number" ? ranAt : ranAt?.code ?? 1;
+        const errorText = typeof ranAt === "number" ? null : ranAt?.errorText ?? null;
+        // No active session: a retried close still drains a terminal queued while offline.
+        if (!marked.active) return { code, delivery: await deliverPending(POST_ACTION_DELIVERY_MS) };
+        const daemonGone = !live.alive || Boolean(marked.generation && live.generation && live.generation !== marked.generation);
+        await withLock(stateLock, async () => {
+          const state = await readLockedState();
+          if (!state || state.source_run_id !== marked.sourceRunId || state.status !== "active") return;
+          if (daemonGone && state.daemon_generation) {
+            await terminalize(state, "crashed", { code: "browser_daemon_exited", category: "crash" });
+          } else if (code !== 0) {
+            await terminalize(state, "failed", { code: errorClassOf(errorText ?? `exit ${code}`), category: "close" });
+          } else {
+            await terminalize(state, CLEAN_CLOSE);
+          }
+          await persistState(state);
+        });
+        const delivery = await deliverPending(POST_ACTION_DELIVERY_MS);
+        return { code, delivery };
+      }, { attempts: EXEC_LOCK_ATTEMPTS });
+    },
+
+    async setVerdict(verdict, { environment } = {}) {
+      if (!VERDICTS.includes(verdict)) return { error: "bb-pw: usage: bb-pw <lane> verdict pass|fail" };
+      const result = await withLock(execLock, () => withLock(stateLock, async () => {
+        const state = await readLockedState();
+        if (!state || state.status !== "active") return { error: `bb-pw: lane ${lane} has no open tracked browser session to record a verdict on.` };
+        const mismatch = environmentGuard(state, environment);
+        if (mismatch) return { error: mismatch };
+        // A recorded fail is final for the session (the server refuses to overturn it too,
+        // Codex R29): re-test in a new session instead.
+        if (state.verdict === "fail" && verdict !== "fail") return { error: `bb-pw: lane ${lane}'s recorded fail verdict is final for this session — close it and open a new session to re-test.` };
+        state.verdict = verdict;
+        await emit(state, `verdict:${state.next_sequence}`, "progress", {
+          progress: { completed: state.actions.filter((item) => item.result).length, phase: "testing" },
+          browser: { summary: summarize(state) }, evidence_refs: evidenceRefs(state),
+        });
+        await persistState(state);
+        return { ok: true };
+      }), { attempts: EXEC_LOCK_ATTEMPTS });
+      if (result.error) return result;
+      return { ok: true, delivery: await deliverPending(POST_ACTION_DELIVERY_MS) };
+    },
+
+    /** One heartbeat tick for the session-owned heartbeat process. */
+    async heartbeatTick({ sourceRunId, daemonAlive }) {
+      const result = await withLock(stateLock, async () => {
+        const state = await readLockedState();
+        if (!state || state.source_run_id !== sourceRunId || state.status !== "active") return { stop: true, reason: "terminal" };
+        if (state.closing) {
+          const since = Date.parse(state.closing_since ?? "");
+          const closerLive = pidAlive(state.closing_pid) && Number.isFinite(since) && now().getTime() - since < CLOSING_GRACE_MS;
+          if (closerLive) return { stop: false, reason: "closing" };
+          // The closer died or stalled before terminalizing: clear the marker and resume liveness.
+          state.closing = false;
+          state.closing_pid = null;
+          state.closing_since = null;
+          if (!(await daemonAlive(state))) {
+            await terminalize(state, "failed", { code: "close_interrupted", category: "close" });
+            await persistState(state);
+            return { stop: true, reason: "close_interrupted" };
+          }
+        }
+        // Before any browser generation exists (a long first open), the in-flight command's
+        // live owner is the liveness proof — the daemon may not be up yet.
+        if (!state.daemon_generation && hasLiveInflight(state)) {
+          await emit(state, `hb:${state.next_sequence}`, "heartbeat", { browser: {} });
+          await persistState(state);
+          return { stop: false, reason: "heartbeat" };
+        }
+        if (!(await daemonAlive(state))) {
+          await terminalize(state, "crashed", { code: "browser_daemon_exited", category: "crash" });
+          await persistState(state);
+          return { stop: true, reason: "crashed" };
+        }
+        await emit(state, `hb:${state.next_sequence}`, "heartbeat", { browser: {} });
+        await persistState(state);
+        return { stop: false, reason: "heartbeat" };
+      });
+      if (result.reason === "closing") return result;
+      // Also on "terminal": a close may have terminalized while delivery was down, and
+      // this heartbeat may be the only process left to deliver that queued terminal.
+      const delivery = await deliverPending(POST_ACTION_DELIVERY_MS);
+      return { ...result, pending: delivery?.queued ?? 0 };
+    },
+
+    /** One bounded delivery attempt of this lane's queue; used to drain a terminal after the heartbeat stops. */
+    async drainPending() {
+      return deliverPending(POST_ACTION_DELIVERY_MS);
+    },
+  };
+}
+
+/**
+ * The injectable core: a resolver bound to one verified tenant/repository
+ * identity. `deliver(event)` is the BOT-1316 direct ingest delivery.
+ */
+export function createBrowserTelemetryResolver({
+  root = join(homedir(), ".botbuddy"), tenant, repository, producerVersion, deliver,
+  now = () => new Date(), monotonic = () => performance.now(), gitInfo = () => ({}), spawnHeartbeat = null,
+  onAppended = null, // test seam: observe each durable append (e.g. to simulate a crash right after it)
+  onStateWrite = null, // test seam: inject a state-write failure
+} = {}) {
+  let outboxPromise = null;
+  const getOutbox = () => (outboxPromise ??= createTelemetryOutbox({ root: join(root, "telemetry"), tenant, repository, producerVersion, now }));
+  const trackerFor = ({ host, lane }) => createLaneTracker({ root, tenant, repository, host, lane, getOutbox, deliver, now, monotonic, gitInfo, spawnHeartbeat, onAppended, onStateWrite });
+  return {
+    async resolve({ host, lane }) { return { tracked: true, tracker: trackerFor({ host, lane }) }; },
+    async forHeartbeat(info) { return trackerFor({ host: info.host, lane: info.lane }); },
+  };
+}
+
+/** Heartbeat loop: ≤20 s ticks until the session terminalizes or its browser dies. */
+export async function runHeartbeatLoop({ tracker, sourceRunId, daemonAlive, sleep: wait = sleep, intervalMs = HEARTBEAT_INTERVAL_MS, maxTicks = Infinity, maxDrainTicks = TERMINAL_DRAIN_TICKS }) {
+  for (let tick = 0; tick < maxTicks; tick++) {
+    await wait(Math.min(intervalMs, 20_000));
+    let result;
+    try { result = await tracker.heartbeatTick({ sourceRunId, daemonAlive }); } catch { continue; }
+    if (!result.stop) continue;
+    if (!result.pending) return { reason: result.reason, drained: true };
+    // The heartbeat observed the end (e.g. a crash) while delivery was down: it is the
+    // only process left to deliver that terminal, so it keeps retrying (bounded).
+    for (let drain = 0; drain < maxDrainTicks; drain++) {
+      await wait(Math.min(intervalMs, 20_000));
+      const delivery = await tracker.drainPending().catch(() => null);
+      if (delivery && !delivery.queued) return { reason: result.reason, drained: true };
+    }
+    return { reason: result.reason, drained: false };
+  }
+  return { reason: "max_ticks" };
+}