@botbuddy/cli 1.34.4 → 1.35.0

package/package.json

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

package/src/commands.mjs

@@ -223,6 +223,9 @@ ${bold("AGENT WAITS")}
 ${bold("BROWSER LANES")}
   pw <lane> <verb> [args…]    Drive a lock-gated Playwright lane
                               (also the short ${cyan("pw")} binary, or ${cyan("bb-pw")} alias)
+  pw <lane> verdict pass|fail Record the session's acceptance verdict
+                              (sessions report live timing/results; start one
+                              with --environment <env> or BB_PW_ENV)
   pw --help                   Show lane usage
 
 ${bold("OTHER")}

package/src/pw/args.mjs

@@ -7,10 +7,14 @@ export const GLOBAL_VERBS = new Set(["list", "close-all", "kill-all", "reap"]);
 // with an "Unknown option" + help dump; catch it here and name the fix (move it
 // before the lane) instead. `--tenant` after the lane also cannot be safely
 // honored for session/lane auth, another reason to refuse rather than forward it.
-export const PW_CREDENTIAL_FLAGS = ["--tenant", "--session-id", "--agent-session-token", "--agent-key", "--session-token"];
+export const PW_CREDENTIAL_FLAGS = ["--tenant", "--session-id", "--agent-session-token", "--agent-key", "--session-token", "--environment"];
+// BOT-1318: the one lane bound, shared with the server validator
+// (supabase/functions/_shared/executionLifecycle.ts MAX_BROWSER_LANE; a contract
+// test pins them equal). An out-of-range lane is refused before anything runs.
+export const MAX_PW_LANE = 9999;
 const credentialFlagOf = (token) => PW_CREDENTIAL_FLAGS.find((flag) => token === flag || String(token).startsWith(`${flag}=`)) ?? null;
 function misplacedCredentialFlag(token) {
-  return new Error(`bb-pw: ${credentialFlagOf(token)} is a bb pw credential flag, not a Playwright argument — put it before the lane: bb-pw [--tenant <slug>] <lane> <verb> …`);
+  return new Error(`bb-pw: ${credentialFlagOf(token)} is a bb pw ${credentialFlagOf(token) === "--environment" ? "wrapper" : "credential"} flag, not a Playwright argument — put it before the lane: bb-pw [--tenant <slug>] [--environment <env>] <lane> <verb> …`);
 }
 // BOT-1682: verbs that once existed under bb pw / an older @playwright/cli and now
 // map to a differently-named upstream command. On these, hint the rename in one
@@ -29,7 +33,7 @@ export function resolveRef(value, env = process.env) {
   return { value: env[match[1]], ref: value, secret: true };
 }
 export const normaliseLane = (token) => String(token).replace(/^agent-0*/, "").replace(/^lane-/, "");
-function validLane(lane) { return /^[1-9]\d*$/.test(lane); }
+function validLane(lane) { return /^[1-9]\d*$/.test(lane) && Number(lane) <= MAX_PW_LANE; }
 export function planInvocation(argv, env = process.env) {
   if (!argv.length) throw new Error("bb-pw: usage: bb-pw <lane> <verb> [args…]  (or: bb-pw <reap|list|close-all|kill-all>)");
   if (GLOBAL_VERBS.has(argv[0])) {
@@ -46,11 +50,17 @@ export function planInvocation(argv, env = process.env) {
     return argv[0] === "reap" ? { scope: "global", verb: "reap", mode: "reap" } : { scope: "global", verb: argv[0], mode: "exec", execArgv: argv };
   }
   const lane = normaliseLane(argv[0]), verb = argv[1];
-  if (!validLane(lane) || !verb) throw new Error(`bb-pw: usage: lane must be a positive integer and include a verb`);
+  if (!validLane(lane) || !verb) throw new Error(`bb-pw: usage: lane must be an integer from 1 to ${MAX_PW_LANE} and include a verb`);
   // BOT-1682: a credential flag in the verb slot (`<lane> --tenant …`) or a
   // retired verb — caught before status/target handling so neither leaks upstream.
   if (credentialFlagOf(verb)) throw misplacedCredentialFlag(verb);
   if (Object.hasOwn(RETIRED_VERBS, verb)) throw new Error(`bb-pw: '${verb}' was retired — ${RETIRED_VERBS[verb]}`);
+  // BOT-1318: `verdict pass|fail` is a LOCAL wrapper verb — it records the
+  // session's acceptance verdict and is never forwarded to Playwright.
+  if (verb === "verdict") {
+    if (argv.length !== 3 || !["pass", "fail"].includes(argv[2])) throw new Error("bb-pw: usage: bb-pw <lane> verdict pass|fail");
+    return { scope: "lane", lane, session: `lane-${lane}`, verb, mode: "verdict", verdict: argv[2] };
+  }
   if (verb === "status") {
     // `status` has no workload, so — like the global verbs — there is no `--`
     // exemption: a credential flag in ANY position (incl. after `--`) is misplaced

package/src/pw/coordinator.mjs

@@ -18,12 +18,12 @@ function mcpCaller(authHeader, fetchImpl) {
 }
 
 function laneCoordinator(kind, call, agentId) {
-  return { kind, async status({ host, slot }) { const result = await call("list_resources", { host, subtype: "playwright_lane" }); const list = Array.isArray(result) ? result : result.resources ?? []; const resource = list.find((item) => item.name === `playwright_lane:${host}:${slot}` || String(item.slot) === String(slot)); /* BOT-1490: canonical_host is a TOP-LEVEL field the server echoes even on an empty page (not-held lane); owner_is_caller is per-row. Older servers send neither → null. */ const canonicalHost = (result && !Array.isArray(result) ? result.canonical_host : null) ?? null; return resource ? { held: resource.status !== "free", heldBy: resource.owner_agent_id ?? null, heldByName: resource.agents?.name ?? null, host: resource.host ?? null, name: resource.name ?? null, slot: resource.slot ?? null, canonicalHost, ownerIsCaller: resource.owner_is_caller ?? null } : { held: false, heldBy: null, heldByName: null, host: null, name: null, slot: null, canonicalHost, ownerIsCaller: null }; }, async emit(event) { await call("record_lane_event", event); }, agentId };
+  return { kind, async status({ host, slot }) { const result = await call("list_resources", { host, subtype: "playwright_lane" }); const list = Array.isArray(result) ? result : result.resources ?? []; const resource = list.find((item) => item.name === `playwright_lane:${host}:${slot}` || String(item.slot) === String(slot)); /* BOT-1490: canonical_host is a TOP-LEVEL field the server echoes even on an empty page (not-held lane); owner_is_caller is per-row. Older servers send neither → null. */ const canonicalHost = (result && !Array.isArray(result) ? result.canonical_host : null) ?? null; return resource ? { held: resource.status !== "free", heldBy: resource.owner_agent_id ?? null, heldByName: resource.agents?.name ?? null, host: resource.host ?? null, name: resource.name ?? null, slot: resource.slot ?? null, canonicalHost, ownerIsCaller: resource.owner_is_caller ?? null } : { held: false, heldBy: null, heldByName: null, host: null, name: null, slot: null, canonicalHost, ownerIsCaller: null }; }, agentId };
 }
 
 // BOT-1572/1582: authenticate lock verification with a per-session `bb_agent_` token —
 // the server resolves it to the session agent (mcp-server authenticateAgent), so
-// `list_resources`/`record_lane_event` run AS the session, and holder matching
+// `list_resources` runs AS the session, and holder matching
 // rides on the server's `owner_is_caller`. No machine profile is required.
 export function createSessionTokenCoordinator({ token, fetchImpl = fetch } = {}) {
   if (!token) return { kind: "unverified" };

package/src/pw/heartbeat.mjs

@@ -0,0 +1,31 @@
+#!/usr/bin/env node
+// BOT-1318 — the browser-session-owned heartbeat. Spawned detached by bb pw once
+// a tracked lane browser is open; it keeps the execution fresh (≤20 s ticks)
+// against BOT-1317's 90 s reaper while the browser idles, terminalizes
+// `crashed` when it observes the lane's Playwright daemon die, and exits once
+// the session closes. It carries no secret: the credential is re-resolved from
+// the worktree binding (else its cached session, never a fresh mint), exactly as
+// the foreground command resolves it.
+import { pathToFileURL } from "node:url";
+import { resolveSession } from "./daemon.mjs";
+import { resolveBrowserTelemetry } from "./telemetry.mjs";
+import { runHeartbeatLoop } from "./session.mjs";
+
+export async function main(argv = process.argv.slice(2), env = process.env) {
+  let info;
+  try { info = JSON.parse(argv[0] ?? ""); } catch { return 2; }
+  if (!info?.source_run_id || !info?.lane || !info?.host || !info?.cwd) return 2;
+  const resolved = await resolveBrowserTelemetry({ env, cwd: info.cwd });
+  if (!resolved.tracked) return 0;
+  const tracker = await resolved.resolver.forHeartbeat(info);
+  const daemonAlive = async (state) => {
+    const { session } = await resolveSession(`lane-${info.lane}`, env);
+    return Boolean(session) && (!state?.daemon_generation || session.socketPath === state.daemon_generation);
+  };
+  await runHeartbeatLoop({ tracker, sourceRunId: info.source_run_id, daemonAlive });
+  return 0;
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  main().then((code) => { process.exitCode = code; }, () => { process.exitCode = 1; });
+}

package/src/pw/run.mjs

@@ -4,6 +4,7 @@ import { actionTypeFromMethod, NAV } from "./readiness.mjs";
 import { isStaleRefError, staleRefRemediation } from "./targets.mjs";
 import { createSessionTokenCoordinator } from "./coordinator.mjs";
 import { canonicalizeHostString } from "./host.mjs";
+import { resolveEnvironment } from "./session.mjs";
 import { resolveAgentBinding } from "../wait-profile.mjs";
 import { loadConfig, getConfig } from "../config.mjs";
 import { VERSION } from "../version.mjs";
@@ -13,7 +14,7 @@ import { clearAgentState, isRejectedCachedMcpSession, resolveAgentSessionCredent
 // server-side, so the lane name bb-pw builds/matches/prints is the one the lock
 // kernel actually stored ("jonos-mbp:8", not "Jonos-MBP.localdomain:8").
 const hostFor = (env) => canonicalizeHostString(env.PLAYWRIGHT_MCP_HOST || env.HOSTNAME || os.hostname());
-function help(out) { out.write("Usage: pw [--tenant <slug>] [--session-id <id>] [--agent-session-token <token>] <lane> <verb> [args…]\n\nAliases: bb-pw <lane> <verb> [args…]   ·   botbuddy pw <lane> <verb> [args…]\n         (all three drive the same lock-gated Playwright lane)\n\n--session-id <id>  accept a lane held by this arming-session agent id (from\n                   register_agent); defaults to $BOTBUDDY_SESSION_ID, then the\n                   id saved by `botbuddy register`.\n--agent-session-token <token>  session credential (env $BOTBUDDY_AGENT_SESSION_TOKEN);\n                   --agent-key / --session-token are one-release legacy aliases.\n--tenant <slug>    accepted before the lane but currently INERT — the tenant\n                   comes from your resolved credential, so bb pw does not act on\n                   this flag for session/lane auth yet (server-validated tenant\n                   selection is tracked in BOT-1732).\n\nCredential flags (--tenant / --session-id / --agent-session-token) go BEFORE the\nlane. Placed after the lane they are refused with guidance (they are not\nPlaywright arguments, and a --tenant after the lane cannot be safely honored).\n\nFile upload (BOT-1702) — works on a hidden <input type=file>:\n  bb-pw <lane> upload <selector> <path...>\n  bb-pw <lane> upload <selector> --inline name=<n>,mime=<m>,size=<bytes>\n  bb-pw <lane> upload <selector> --inline name=<n>,mime=<m>,bytes=@base64:<b64>\n  bb-pw <lane> upload <selector> --inline name=<n>,mime=<m>,text=<str>\n     --inline repeats; builds synthetic files in memory (no workstation FS).\n     <selector> also accepts --testid/--role/--label/--text like click/fill.\n\nNetwork mocking (BOT-1702) — routes persist on the lane across invocations:\n  bb-pw <lane> route <url-glob> stall                 hold the request pending\n                                                      (screenshot the loading state)\n  bb-pw <lane> route <url-glob> abort [--error <code>] fail the request (default: failed)\n  bb-pw <lane> route <url-glob> fulfill --status <n> [--content-type <ct>]\n                                        [--body <str|@base64:..|@file:PATH>]\n  bb-pw <lane> unroute [<url-glob>]                    release one route, or all\n  bb-pw <lane> route-list                              list the routes owned on this lane\n  (offline mode already exists upstream: bb-pw <lane> network-state-set offline)\n"); }
+function help(out) { out.write("Usage: pw [--tenant <slug>] [--session-id <id>] [--agent-session-token <token>] [--environment <env>] <lane> <verb> [args…]\n\nAliases: bb-pw <lane> <verb> [args…]   ·   botbuddy pw <lane> <verb> [args…]\n         (all three drive the same lock-gated Playwright lane)\n\n--session-id <id>  accept a lane held by this arming-session agent id (from\n                   register_agent); defaults to $BOTBUDDY_SESSION_ID, then the\n                   id saved by `botbuddy register`.\n--agent-session-token <token>  session credential (env $BOTBUDDY_AGENT_SESSION_TOKEN);\n                   --agent-key / --session-token are one-release legacy aliases.\n--tenant <slug>    accepted before the lane but currently INERT — the tenant\n                   comes from your resolved credential, so bb pw does not act on\n                   this flag for session/lane auth yet (server-validated tenant\n                   selection is tracked in BOT-1732).\n\n--environment <local|preview|staging|production>  the environment a TRACKED\n                   browser session is exercising (env $BB_PW_ENV when absent; the\n                   flag wins). Required when a session starts in a repository\n                   with .botbuddy/config.json; persisted for the session, and a\n                   later disagreeing value is refused.\n\nBrowser-acceptance telemetry (BOT-1318): each lane browser session (open →\nclose) is reported once as a browser_acceptance execution with wall/active/\ncommand time, per-action results and a verdict. Every action's result is\nuploaded before the command returns; offline, events queue locally and drain\nlater. Values you type/fill, secrets, query strings and raw output are never\nrecorded. BB_PW_NO_LOCK=1 stays local and untracked.\n  bb-pw <lane> verdict pass|fail   record the acceptance verdict (local; never\n                                   sent to Playwright). Without it a session\n                                   closes as not_asserted.\n  bb-pw <lane> status              shows browser_session: source_run_id,\n                                   execution_id, delivery, environment, verdict.\n\nCredential flags (--tenant / --session-id / --agent-session-token) and\n--environment go BEFORE the lane. Placed after the lane they are refused with guidance (they are not\nPlaywright arguments, and a --tenant after the lane cannot be safely honored).\n\nFile upload (BOT-1702) — works on a hidden <input type=file>:\n  bb-pw <lane> upload <selector> <path...>\n  bb-pw <lane> upload <selector> --inline name=<n>,mime=<m>,size=<bytes>\n  bb-pw <lane> upload <selector> --inline name=<n>,mime=<m>,bytes=@base64:<b64>\n  bb-pw <lane> upload <selector> --inline name=<n>,mime=<m>,text=<str>\n     --inline repeats; builds synthetic files in memory (no workstation FS).\n     <selector> also accepts --testid/--role/--label/--text like click/fill.\n\nNetwork mocking (BOT-1702) — routes persist on the lane across invocations:\n  bb-pw <lane> route <url-glob> stall                 hold the request pending\n                                                      (screenshot the loading state)\n  bb-pw <lane> route <url-glob> abort [--error <code>] fail the request (default: failed)\n  bb-pw <lane> route <url-glob> fulfill --status <n> [--content-type <ct>]\n                                        [--body <str|@base64:..|@file:PATH>]\n  bb-pw <lane> unroute [<url-glob>]                    release one route, or all\n  bb-pw <lane> route-list                              list the routes owned on this lane\n  (offline mode already exists upstream: bb-pw <lane> network-state-set offline)\n"); }
 // Redact LONGEST secrets first: replacing a short value that is a substring of a
 // longer secret (e.g. a filename that also appears inside the payload's base64)
 // would otherwise break the longer match and leave the remainder recoverable
@@ -101,6 +102,19 @@ async function gate({ env, host, lane, deps }) {
 // pre-BOT-1488 refusal and was indistinguishable from a code regression. Every
 // non-zero exit now names the bundled version, and --version exists at all, so
 // an agent can tell "old binary" from "real bug" without reading the source.
+// BOT-1318: a queued (undelivered) lifecycle event is degradation, never a
+// change to the browser command's exit code or output.
+function reportDegradation(stderr, delivery) {
+  if (delivery?.server_ended) {
+    const next = delivery.rehomed ? `this command's result${delivery.rehomed > 1 ? ` and ${delivery.rehomed - 1} earlier undelivered action(s) were` : " was"} recorded in a new tracked session` : "the next command starts a new tracked session";
+    stderr.write(`bb-pw: BotBuddy already ended this session as ${delivery.server_ended} (no heartbeat reached it within its grace window, e.g. while this machine slept); ${next}.\n`);
+  }
+  if (delivery?.heartbeat_failed) stderr.write(`bb-pw: telemetry degraded — the session heartbeat could not start; if this browser idles longer than BotBuddy's grace window it is recorded as abandoned. The next bb pw command on this lane retries it.\n`);
+  if (delivery?.persist_failed) stderr.write(`bb-pw: telemetry degraded — the browser command ran, but its result could not be durably recorded (${delivery.persist_failed}); this session's report is missing that action. Check disk space and permissions under the bb pw telemetry directory.\n`);
+  if (delivery?.queued) stderr.write(`bb-pw: telemetry degraded — ${delivery.queued} lifecycle event(s) queued locally; they are delivered on the next action, heartbeat or close.\n`);
+  // A permanent (contract) rejection is quarantined, never retried — say so.
+  if (delivery?.quarantined) stderr.write(`bb-pw: telemetry degraded — ${delivery.quarantined} lifecycle event(s) were rejected by BotBuddy and quarantined locally (not retried); this session's report is incomplete. Upgrade @botbuddy/cli, or inspect the outbox quarantine file.\n`);
+}
 const versionLine = () => `bb-pw (@botbuddy/cli v${VERSION})`;
 export async function runPw(argv, deps = {}) {
   const stderr = deps.stderr ?? process.stderr;
@@ -113,7 +127,7 @@ export async function runPw(argv, deps = {}) {
 // The leading option/value pairs bb pw consumes before the lane/verb (mirrors the
 // while-loop in runPwInner). Everything after the first non-option (the lane) is a
 // Playwright workload argument and is never a BotBuddy credential.
-const PW_LEADING_FLAGS = ["--tenant", "--session-id", "--agent-session-token", "--agent-key", "--session-token"];
+const PW_LEADING_FLAGS = ["--tenant", "--session-id", "--agent-session-token", "--agent-key", "--session-token", "--environment"];
 const selfHealErrorLine = (error) => `bb-pw: ${error?.message ?? "agent session unavailable"}. ${error?.code === "client_key_required" ? "Run `bb login` then retry." : "Run `bb doctor --fix` then retry."}\n`;
 // The leading credential options, NORMALIZED to split `flag value` pairs so an
 // inline `--agent-key=<token>` is recognized by legacyAgentAliasHint (which
@@ -144,6 +158,8 @@ function matchWrapperFlag(token) {
 }
 const applyWrapperFlag = (deps, flag, value) => flag === "--tenant"
   ? { ...deps, tenant: value }
+  : flag === "--environment"
+    ? { ...deps, environment: value }
   : ["--agent-session-token", "--agent-key", "--session-token"].includes(flag)
     ? { ...deps, sessionToken: value }
     : { ...deps, sessionId: value };
@@ -204,7 +220,7 @@ async function runPwInner(argv, deps = {}) {
       stderr.write(selfHealErrorLine(error)); return 3;
     }
   }
-  const telemetry = deps.telemetry ?? (await import("./telemetry.mjs")).makeTelemetry({ env }); const host = deps.host ?? hostFor(env);
+  const host = deps.host ?? hostFor(env);
   let auth = await gate({ env, host, lane: plan.lane, deps });
   // Only an ACTUAL auth rejection carries an errorCode (the coordinator surfaces
   // the MCP auth code). A plain lock denial (lane held by another agent) returns
@@ -228,19 +244,74 @@ async function runPwInner(argv, deps = {}) {
   // Report the host the lock service actually stored (alias-collapsed), so the
   // status view and lane telemetry match the server, not the local string (AC-4).
   const effHost = auth.canonicalHost ?? host;
-  if (plan.mode === "status") { const lock = auth.coordinator?.status ? await auth.coordinator.status({ host: effHost, slot: plan.lane }) : null; stdout.write(JSON.stringify({ lane: plan.lane, session: plan.session, host: effHost, lock, spooled_events: telemetry.count(plan.lane) }, null, 2) + "\n"); return 0; }
-  if (actionTypeFromMethod(plan.verb) !== "other") telemetry.append(plan.lane, { ts: Date.now(), method: plan.verb, url: actionTypeFromMethod(plan.verb) === NAV ? plan.telemetryUrl : null });
+  // BOT-1318: resolve the lane's browser-acceptance tracker AFTER the gate (a
+  // refused/unverified lane writes no lifecycle) and never for unlocked local mode.
+  let tracker = null;
+  if (env.BB_PW_NO_LOCK !== "1") {
+    const telemetry = deps.telemetry ?? (await import("./telemetry.mjs")).makeTelemetry({ env, cwd: deps.cwd ?? process.cwd(), sessionCredential: deps.sessionToken ?? readAgentSessionTokenEnv(env) ?? null });
+    const resolved = await telemetry.resolve({ host: effHost, lane: plan.lane });
+    if (resolved?.error) { stderr.write(`${resolved.error}\n`); return 2; }
+    tracker = resolved?.tracked ? resolved.tracker : null;
+  }
+  // BOT-1318: a tracked session's environment comes from --environment, then
+  // BB_PW_ENV; an invalid value is refused before any tracked action or write —
+  // and before status too, so wrapper configuration is never silently accepted.
+  const envResolution = resolveEnvironment({ flag: deps.environment ?? null, env });
+  if (tracker && envResolution.error) { stderr.write(`${envResolution.error}\n`); return 2; }
+  const environment = envResolution.environment ?? null;
+  if (plan.mode === "status") {
+    const lock = auth.coordinator?.status ? await auth.coordinator.status({ host: effHost, slot: plan.lane }) : null;
+    const browserSession = tracker ? await tracker.status() : { tracked: false, active: false };
+    if (tracker && environment && browserSession.active && browserSession.environment && browserSession.environment !== environment) {
+      stderr.write(`bb-pw: lane ${plan.lane}'s open browser session is tracked as environment "${browserSession.environment}", not "${environment}".\n`);
+      return 2;
+    }
+    stdout.write(JSON.stringify({ lane: plan.lane, session: plan.session, host: effHost, lock, browser_session: browserSession }, null, 2) + "\n");
+    return 0;
+  }
+  if (plan.mode === "verdict") {
+    if (!tracker) { stderr.write("bb-pw: verdict needs a tracked browser session (a repository with .botbuddy/config.json and a lock-gated lane).\n"); return 2; }
+    const result = await tracker.setVerdict(plan.verdict, { environment });
+    if (result.error) { stderr.write(`${result.error}\n`); return 2; }
+    reportDegradation(stderr, result.delivery); return 0;
+  }
   // Translate verbs ALWAYS run via the socket (even a small, non-secret one), so
   // run.mjs — not an inherited-stdio spawnExec — owns their output and can strip
   // the internal code echo; socketRun falls back to execArgv.slice(1) as its args
   // (Codex R26 P2).
-  const inspect = plan.mode === "socket" || plan.translate || (actionTypeFromMethod(plan.verb) === "interaction" && (plan.targetKind === "ref" || plan.fresh)); let code;
+  const inspect = plan.mode === "socket" || plan.translate || (actionTypeFromMethod(plan.verb) === "interaction" && (plan.targetKind === "ref" || plan.fresh));
   // bb-pw's translate verbs (upload/route/...) generate internal run-code; that
   // echoed "### Ran Playwright code" block is never useful to the caller and can
   // be large (a 100KB+ base64 payload) or carry a secret, so strip it for every
   // translated command — not only secret ones (Codex R25 P2) — while still
   // redacting any tracked secret from the rest.
   const suppressEcho = !!plan.translate || !!plan.secretValues?.length;
-  if (inspect) { if (plan.fresh) await socketRun({ ...plan, socketArgs: ["snapshot"] }, env).catch(() => {}); const result = await socketRun({ ...plan, socketArgs: plan.socketArgs ?? plan.execArgv.slice(1) }, env); if (result.text) { const text = suppressEcho ? stripCodeEcho(result.text) : result.text; stdout.write(`${redact(text, plan.secretValues)}\n`); } if (!result.ok) { let errText = plan.targetKind === "ref" && isStaleRefError(result.error) ? staleRefRemediation(plan.target) : result.error; if (suppressEcho) errText = stripCodeEcho(errText); stderr.write(`${redact(errText, plan.secretValues)}\n`); } code = result.ok ? 0 : 1; } else code = await spawnExec(plan, env);
-  if (plan.rollup && code === 0) await telemetry.rollup({ lane: plan.lane, coordinator: auth.coordinator, host: effHost }); return code;
+  // `errorText` is inspected only to classify a failure; it is never persisted.
+  const execute = async () => {
+    if (inspect) { if (plan.fresh) await socketRun({ ...plan, socketArgs: ["snapshot"] }, env).catch(() => {}); const result = await socketRun({ ...plan, socketArgs: plan.socketArgs ?? plan.execArgv.slice(1) }, env); if (result.text) { const text = suppressEcho ? stripCodeEcho(result.text) : result.text; stdout.write(`${redact(text, plan.secretValues)}\n`); } if (!result.ok) { let errText = plan.targetKind === "ref" && isStaleRefError(result.error) ? staleRefRemediation(plan.target) : result.error; if (suppressEcho) errText = stripCodeEcho(errText); stderr.write(`${redact(errText, plan.secretValues)}\n`); } return { code: result.ok ? 0 : 1, errorText: result.ok ? null : String(result.error ?? "") }; }
+    const code = await spawnExec(plan, env); return { code, errorText: code === 0 ? null : `exit ${code}` };
+  };
+  if (!tracker) return (await execute()).code;
+  const probe = async () => { const resolver = deps.daemon?.resolveSession ?? (await import("./daemon.mjs")).resolveSession; const { session } = await resolver(plan.session, env); return { alive: Boolean(session), generation: session?.socketPath ?? null }; };
+  if (plan.verb === "close") {
+    const closed = await tracker.close({ environment, probe, run: execute });
+    if (closed.error) { stderr.write(`${closed.error}\n`); return 2; }
+    reportDegradation(stderr, closed.delivery); return closed.code;
+  }
+  const handle = await tracker.begin({ verb: plan.verb, category: actionTypeFromMethod(plan.verb), route: plan.telemetryUrl ?? null, environment, probe });
+  if (handle.error) { stderr.write(`${handle.error}\n`); return handle.exitCode ?? 2; }
+  if (!handle.tracked) return (await execute()).code;
+  // A signal during a tracked action terminalizes the session `canceled` (once)
+  // before the process exits with the conventional signal code.
+  const signals = deps.signalEmitter ?? process;
+  const exit = deps.exit ?? ((code) => process.exit(code));
+  const onSignal = (signal) => { handle.cancel(signal).finally(() => exit(signal === "SIGINT" ? 130 : 143)); };
+  signals.once("SIGINT", onSignal); signals.once("SIGTERM", onSignal);
+  let result;
+  try { result = await execute(); }
+  finally { signals.removeListener("SIGINT", onSignal); signals.removeListener("SIGTERM", onSignal); }
+  const evidenceKind = plan.verb === "screenshot" ? "screenshot" : plan.verb === "tracing-stop" ? "trace" : null;
+  const delivery = await handle.finish({ ok: result.code === 0, errorText: result.errorText, exitCode: result.code, evidenceKind });
+  reportDegradation(stderr, delivery);
+  return result.code;
 }