@botbuddy/cli 1.59.3 → 1.59.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@botbuddy/cli",
-  "version": "1.59.3",
+  "version": "1.59.5",
   "description": "BotBuddy \u2014 Swarm coordination CLI for multi-agent workflows",
   "type": "module",
   "bin": {

package/src/commands.mjs

@@ -212,6 +212,8 @@ ${bold("MCP CONFIG KEY")}
 ${bold("TOOLS")}
   help --tools               List every BotBuddy tool
   help <tool>                Show one tool's arguments
+  help test                  Safe test-lane launch and recovery guidance
+  help symptom <name>        Diagnose a known block without source-diving
   call <tool> [--key value]  Invoke any tool
   call <tool> --json '{...}' Invoke with a JSON arguments object
   call <tool> --pin <slug>   Pin the connection tenant (a user token needs one;
@@ -362,6 +364,11 @@ async function cmdCall(args) {
 }
 
 async function cmdToolHelp(args) {
+  const local = recoveryHelp(args);
+  if (local) {
+    console.log(local);
+    return;
+  }
   // `help --tools` (or `help --all`) lists the catalog; `help <tool>` details one.
   const tool = args[0].startsWith("-") ? null : args[0];
   const res = await fetch(discoveryUrlFor(SERVER_URL, tool));
@@ -373,6 +380,80 @@ async function cmdToolHelp(args) {
   console.log(formatDiscovery(await res.json(), { tool }));
 }
 
+// Keep the most common lifecycle recoveries local: an agent must be able to
+// discover the safe next action even when the MCP discovery endpoint is down.
+// This deliberately names only stable, already-shipped commands. New lifecycle
+// commands belong in their owning feature ticket before they are documented here.
+export function recoveryHelp(args) {
+  const topic = args.map((arg) => String(arg).trim().toLowerCase()).filter(Boolean).join(" ");
+  if (topic === "test") return `${bold("bb help test")} — launch tests without losing their evidence
+
+${bold("SAFE DEFAULT")}
+  1. Run ${cyan("bb doctor --json")} from the target worktree.
+  2. Run the repository's configured test command without manually copying a
+     session ID or session token unless the harness explicitly requires it.
+  3. Keep the command's original result and receipt path. Do not start a second
+     full suite merely because telemetry is missing.
+
+${bold("WHEN TEST TELEMETRY IS UNAVAILABLE")}
+  Run ${cyan("bb help symptom telemetry-unavailable")}. A null test-run ID means
+  there is no semantic test-run wait to arm; it is not a passing result.
+
+${bold("WAITING")}
+  Use ${cyan("bb wait 'test-run:id=<id>' --heartbeat")} only when the launch output
+  contains a real test-run ID. Do not replace a missing lifecycle signal with a
+  timer or status-polling loop.`;
+
+  if (topic === "symptom" || topic === "symptoms") return `${bold("bb help symptom <name>")} — supported recovery topics
+
+  ${cyan("telemetry-unavailable")}  A test launch has no test-run ID or wait command.
+  ${cyan("command-run-stuck")}     A local command receipt and remote lifecycle disagree.
+
+Choose the symptom printed by the command. If neither applies, preserve the
+original command result and receipt, then report the exact error and command ID.`;
+
+  if (topic === "symptom telemetry-unavailable") return `${bold("Symptom: telemetry unavailable")}
+
+${bold("Meaning")}
+The workload may have started, but BotBuddy did not create a test-run record.
+There is no ${cyan("test-run:id")} wait to arm and silence is never a green result.
+
+${bold("Safe recovery")}
+  1. Do not launch another full suite yet.
+  2. Preserve the original ${cyan("command_run_id")} and receipt path from its output.
+  3. Read the terminal receipt when the original runner returns. A receipt with a
+     terminal status is evidence of that workload's result.
+  4. If the receipt is not terminal, keep the original runner result pending;
+     do not poll it or use a timer as a completion signal.
+  5. After a terminal receipt, fix the launch/authentication cause and rerun the
+     smallest affected scope once, with an explicit rerun reason when supported.
+
+${bold("Escalation payload")}
+Include CLI version, exact command (with secrets removed), command-run ID,
+receipt status/exit code, and whether a test-run ID was created.`;
+
+  if (topic === "symptom command-run-stuck") return `${bold("Symptom: command run appears stuck")}
+
+${bold("Meaning")}
+A remote lifecycle record can lag or fail to receive a terminal callback. It
+does not prove that the workload is still running.
+
+${bold("Safe recovery")}
+  1. Preserve the command-run ID and the original result.
+  2. Prefer the owning runner's local terminal receipt for the workload verdict.
+  3. If the receipt is terminal, do not cancel or duplicate the command solely
+     because remote state remains ${cyan("registered")} or ${cyan("running")}.
+  4. If the receipt is absent/non-terminal, retain the original runner result;
+     do not poll or infer completion from elapsed time.
+  5. Report the receipt and remote discrepancy as telemetry evidence.
+
+${bold("Boundary")}
+Command-run status is agent-owned. A different agent may be denied access; that
+denial is not evidence that the run is missing or terminal.`;
+
+  return null;
+}
+
 // BOT-1566 C1: a tenant slug as the server accepts it on `?tenant=` — lowercase
 // alphanumerics and hyphens, 2–63 chars, not starting with a hyphen.
 export const TENANT_SLUG_RE = /^[a-z0-9][a-z0-9-]{1,62}$/;

package/src/run.mjs

@@ -215,6 +215,66 @@ export function commandHash(command) { return createHash("sha256").update(JSON.s
 export function environmentHash(cwd, environment) { return createHash("sha256").update(`${cwd}\0${environment}`).digest("hex"); }
 export function receiptPath(runId) { return join(homedir(), ".botbuddy", "command-runs", `${runId}.receipt.json`); }
 export function contextPath(runId) { return join(homedir(), ".botbuddy", "command-runs", `${runId}.context.json`); }
+function cancellationPath(contextFile) { return `${contextFile}.cancelled`; }
+
+async function markCancellation(contextFile, runId) {
+  try {
+    await writeFile(cancellationPath(contextFile), JSON.stringify({ run_id: runId, reason: "cancelled_before_workload_start", requested_at: new Date().toISOString() }), { mode: 0o600, flag: "wx" });
+    return true;
+  } catch (error) {
+    if (error?.code === "EEXIST") return false;
+    throw error;
+  }
+}
+
+async function hasCancellationMarker(contextFile) {
+  try { await readFile(cancellationPath(contextFile), "utf8"); return true; } catch (error) {
+    if (error?.code === "ENOENT") return false;
+    throw error;
+  }
+}
+
+async function preWorkloadCancellationReceipt(context) {
+  const now = new Date().toISOString();
+  const receipt = {
+    schema_version: RUN_SCHEMA_VERSION,
+    run_id: context.run_id,
+    status: "cancelled",
+    started_at: now,
+    ended_at: now,
+    exit_code: null,
+    signal: "SIGTERM",
+    recovery_command: null,
+    bounded_log: "",
+    output_characters: 0,
+    reason: "cancelled_before_workload_start",
+  };
+  await writeJson(context.receipt_path, receipt);
+  return receipt;
+}
+
+async function retryCancellationHandoff(context, call, { sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)) } = {}) {
+  let attempts = 0;
+  let delay = 1_000;
+  for (;;) {
+    let result;
+    try {
+      result = await call("cancel_command_run", {
+        run_id: context.run_id,
+        run_credential: context.run_credential,
+        reason: "cancelled_before_workload_start",
+      });
+    } catch (error) { result = { ok: false, error: error instanceof Error ? error.message : String(error) }; }
+    if (result?.ok && !result.isError && result.data?.status === "cancelled") return result;
+    attempts += 1;
+    await writeJson(context.context_path, {
+      ...context,
+      cancellation_handoff: { attempts, last_error: result?.error ?? result?.data?.error ?? "cancellation_handoff_rejected", next_retry_at: new Date(Date.now() + delay).toISOString() },
+    });
+    await sleep(delay);
+    delay = Math.min(delay * 2, 60_000);
+  }
+}
 
 async function writeJson(path, value) {
   await mkdir(dirname(path), { recursive: true });
@@ -222,7 +282,7 @@ async function writeJson(path, value) {
   // file, or a poller) never observes a torn/empty file mid-write. rename(2)
   // is atomic within a directory, so readers see either the old or the new
   // complete JSON, never a partial one.
-  const tmp = `${path}.${process.pid}.tmp`;
+  const tmp = `${path}.${process.pid}.${randomUUID()}.tmp`;
   await writeFile(tmp, JSON.stringify(value), { mode: 0o600 });
   await chmod(tmp, 0o600);
   await rename(tmp, path);
@@ -340,7 +400,12 @@ export async function launchRun(argv, {
   }
   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(), ...(childEnv && Object.keys(childEnv).length ? { child_env: childEnv } : {}), ...(testRun ? { test_run: testRun } : {}) });
+  // The detached worker has no ambient credential after its launcher exits.
+  // Seal the already-resolved owning session in the private (0600) context so
+  // every callback is attributable to the same agent. It deliberately stays
+  // outside child_env, receipts, and the workload's process environment.
+  const knownSession = opts.sessionId ?? managedCredential?.identity?.sessionId ?? managedCredential?.sessionId;
+  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(), ...(opts.sessionToken ? { callback_session_token: opts.sessionToken } : {}), ...(knownSession ? { callback_session_id: knownSession } : {}), ...(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 });
@@ -351,25 +416,85 @@ export async function launchRun(argv, {
     await effectiveCall("update_command_run", { run_id: runId, run_credential: registration.data.run_credential, status: "owner_lost", invalidated_reason: `launcher_failed:${error instanceof Error ? error.message : String(error)}` });
     return { exitCode: EXIT.INTERNAL, receipt: { schema_version: RUN_SCHEMA_VERSION, outcome: "owner_lost", run_id: runId, exit_code: EXIT.INTERNAL } };
   }
-  const knownSession = opts.sessionId ?? managedCredential?.identity?.sessionId ?? managedCredential?.sessionId;
   return { exitCode: EXIT.OK, receipt: { schema_version: RUN_SCHEMA_VERSION, outcome: "launched", run_id: runId,
     ...(knownSession ? { session_id: knownSession } : { session_binding: "server_derived" }),
     durable_owner: "detached_worker", receipt_path: receipt, reentry: "update_command_run publishes the terminal callback for this run_id", exit_code: EXIT.OK } };
 }
 
-export async function runWorker(contextFile, { spawnImpl = spawn, call = callToolJson } = {}) {
+export async function runWorker(contextFile, {
+  spawnImpl = spawn,
+  call = callToolJson,
+  signalEmitter = process,
+  terminate = terminateProcessGroup,
+} = {}) {
   const context = JSON.parse(await readFile(contextFile, "utf8"));
+  const callbackCall = callWithContextIdentity(context, call);
+  const ownerHeartbeat = startOwnerHeartbeat(context, callbackCall);
   const startedAt = new Date().toISOString();
   let timedOut = false;
   let child;
+  let cancellationStateWrite = Promise.resolve();
+  let contextWrite = Promise.resolve();
+  const persistWorkerContext = (state) => {
+    const next = contextWrite.then(() => writeJson(context.context_path, {
+      ...context,
+      worker_pid: process.pid,
+      ...state,
+    }));
+    contextWrite = next;
+    return next;
+  };
+  // `cancelRun` creates a durable marker before it acknowledges an unstarted
+  // cancellation. The worker owns its own process group, so SIGTERM is also
+  // the fence for the tiny interval after the final marker check: if spawn won
+  // that interval, the handler terminates the just-created workload instead.
+  const cancellationHandler = () => {
+    void hasCancellationMarker(context.context_path).then(async (marked) => {
+      if (!marked) {
+        // Preserve the old default SIGTERM behaviour for a signal that was not
+        // issued by `cancelRun` for this durable context.
+        signalEmitter.removeListener("SIGTERM", cancellationHandler);
+        process.kill(process.pid, "SIGTERM");
+        return;
+      }
+      if (child) {
+        terminate(child, "SIGTERM");
+        cancellationStateWrite = persistWorkerContext({ workload_pid: child.pid, worker_state: "cancelling_workload" });
+      } else {
+        cancellationStateWrite = persistWorkerContext({ worker_state: "cancelled_before_workload_start" });
+      }
+      await cancellationStateWrite;
+    }).catch(() => { /* the durable marker remains the source of truth for recovery */ });
+  };
+  signalEmitter.once("SIGTERM", cancellationHandler);
   try {
-    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) {
-    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;
-  }
+    if (await hasCancellationMarker(context.context_path)) {
+      if (!context.cancellation_handoff?.accepted) await retryCancellationHandoff(context, callbackCall);
+      if (context.test_run) {
+        const endedAt = new Date().toISOString();
+        await completeTestRun(context, { status: "cancelled", exitCode: null, signal: "SIGTERM", startedAt: context.launched_at ?? endedAt, endedAt, call: callbackCall });
+      }
+      return await preWorkloadCancellationReceipt(context);
+    }
+    // Publish worker ownership before the first workload spawn. Cancellation
+    // can now signal this private process group instead of terminalizing the
+    // server run while a local worker still has authority to start work.
+    await persistWorkerContext({ worker_state: "starting" });
+    if (await hasCancellationMarker(context.context_path)) {
+      if (!context.cancellation_handoff?.accepted) await retryCancellationHandoff(context, callbackCall);
+      if (context.test_run) {
+        const endedAt = new Date().toISOString();
+        await completeTestRun(context, { status: "cancelled", exitCode: null, signal: "SIGTERM", startedAt: context.launched_at ?? endedAt, endedAt, call: callbackCall });
+      }
+      return await preWorkloadCancellationReceipt(context);
+    }
+    try {
+      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) {
+      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)}` }, callbackCall);
+      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
   // fast failure) cannot lose the sole terminal event.
@@ -381,32 +506,57 @@ export async function runWorker(contextFile, { spawnImpl = spawn, call = callToo
   const capture = boundedCapture();
   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 });
+    await persistWorkerContext({ workload_pid: child.pid, worker_state: "running" });
   // 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;
+  const lane = context.test_run ? startLaneFlusher(context, callbackCall) : null;
   let killTimer;
   const timer = setTimeout(() => {
     timedOut = true;
-    terminateProcessGroup(child, "SIGTERM");
-    killTimer = setTimeout(() => terminateProcessGroup(child, "SIGKILL"), context.timeout_grace_ms ?? TIMEOUT_GRACE_MS);
+    terminate(child, "SIGTERM");
+    killTimer = setTimeout(() => terminate(child, "SIGKILL"), context.timeout_grace_ms ?? TIMEOUT_GRACE_MS);
   }, context.timeout_seconds * 1000);
-  const result = await completion;
-  clearTimeout(timer);
-  clearTimeout(killTimer);
-  if (lane) await lane.stop();
-  const endedAt = new Date().toISOString();
-  if (result.error) {
-    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 });
+    const result = await completion;
+    clearTimeout(timer);
+    clearTimeout(killTimer);
+    await cancellationStateWrite;
+    if (lane) await lane.stop();
+    const endedAt = new Date().toISOString();
+    if (result.error) {
+      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 }, callbackCall);
+      return receipt;
+    }
+    const status = terminalStatus({ ...result, timedOut });
+    const receipt = await finalize(context, { status, startedAt, endedAt, exitCode: result.exitCode, signal: result.signal, output: capture.output, outputCharacters: capture.characters }, callbackCall);
     return receipt;
+  } finally {
+    if (ownerHeartbeat) await ownerHeartbeat.stop();
+    signalEmitter.removeListener("SIGTERM", cancellationHandler);
   }
-  const status = terminalStatus({ ...result, timedOut });
-  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;
+}
+
+function startOwnerHeartbeat(context, call, { intervalMs = 5 * 60_000, setIntervalFn = setInterval } = {}) {
+  // A detached worker must never acquire liveness through its ambient default
+  // identity. It can only refresh the bearer sealed for its owner.
+  if (typeof context.callback_session_token !== "string" || !context.callback_session_token) return null;
+  // A token-only launch intentionally omits its public session id. The server
+  // derives the exact active session from the sealed bearer, so it must still
+  // heartbeat rather than waiting for the eight-hour token window to lapse.
+  // Supplying an id when one was sealed retains the same explicit scope fence.
+  const heartbeatArgs = typeof context.callback_session_id === "string" && context.callback_session_id
+    ? { session_id: context.callback_session_id } : {};
+  let stopped = false;
+  let chain = Promise.resolve();
+  const tick = () => {
+    chain = chain.then(async () => {
+      if (stopped) return;
+      try { await call("heartbeat", heartbeatArgs); } catch { /* terminal delivery retains its own retry path */ }
+    });
+  };
+  tick();
+  const timer = setIntervalFn(tick, intervalMs);
+  timer.unref?.();
+  return { async stop() { stopped = true; clearInterval(timer); await chain; } };
 }
 
 // Periodic lane flusher: reduce the NDJSON events file to the current case state
@@ -496,6 +646,30 @@ function terminateProcessGroup(child, signal) {
   try { child.kill?.(signal); } catch { /* already exited */ }
 }
 
+function workerProcessGroupAlive(pid) {
+  if (!Number.isInteger(pid) || pid <= 0 || process.platform === "win32") return false;
+  try { process.kill(-pid, 0); return true; } catch (error) { return error?.code !== "ESRCH"; }
+}
+
+async function waitForWorkerCancellation(contextFile, { sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)), attempts = 25 } = {}) {
+  let latest = null;
+  for (let attempt = 0; attempt < attempts; attempt++) {
+    try { latest = JSON.parse(await readFile(contextFile, "utf8")); } catch { /* the context is atomically replaced */ }
+    if (Number.isInteger(latest?.workload_pid) || latest?.worker_state === "cancelled_before_workload_start") return latest;
+    await sleep(20);
+  }
+  return latest;
+}
+
+async function sealedTerminalStatus(context) {
+  if (typeof context.terminal_update?.status === "string") return context.terminal_update.status;
+  if (!context.receipt_path) return null;
+  try {
+    const receipt = JSON.parse(await readFile(context.receipt_path, "utf8"));
+    return receipt?.run_id === context.run_id && typeof receipt.status === "string" ? receipt.status : null;
+  } catch { return null; }
+}
+
 function forwardTerminationSignals(child, signalEmitter) {
   let signal = null;
   let escalation = null;
@@ -525,15 +699,87 @@ function waitForChild(child) {
   });
 }
 
-export async function cancelRun(runId, { call = callToolJson } = {}) {
+export async function cancelRun(runId, {
+  call = callToolJson,
+  waitForCancellation = waitForWorkerCancellation,
+  killWorker = (pid) => process.kill(-pid, "SIGTERM"),
+  workerAlive = workerProcessGroupAlive,
+} = {}) {
   const context = JSON.parse(await readFile(contextPath(runId), "utf8"));
+  const callbackCall = callWithContextIdentity(context, call);
+  const sealedStatus = await sealedTerminalStatus(context);
+  if (sealedStatus) {
+    return { exitCode: EXIT.OK, receipt: {
+      schema_version: RUN_SCHEMA_VERSION,
+      outcome: "terminal_delivery_pending",
+      run_id: runId,
+      terminal_status: sealedStatus,
+      exit_code: EXIT.OK,
+    } };
+  }
+  const requestCancellation = async () => {
+    // No worker remains to publish the linked test-run terminal event. Complete
+    // it before revoking the one-run credential so an armed `test-run:` wait
+    // cannot be stranded active after the command cancellation is accepted.
+    if (context.test_run) {
+      const endedAt = new Date().toISOString();
+      await completeTestRun(context, {
+        status: "cancelled",
+        exitCode: null,
+        signal: "SIGTERM",
+        startedAt: context.launched_at ?? endedAt,
+        endedAt,
+        call: callbackCall,
+      });
+    }
+    let cancellation;
+    try {
+      cancellation = await callbackCall("cancel_command_run", {
+        run_id: context.run_id,
+        run_credential: context.run_credential,
+        reason: "cancelled_before_workload_start",
+      });
+    } catch (error) {
+      cancellation = { ok: false, error: error instanceof Error ? error.message : String(error) };
+    }
+    if (cancellation?.ok && !cancellation.isError && cancellation.data?.status === "cancelled") {
+      await writeJson(context.context_path ?? contextPath(runId), { ...context, cancellation_handoff: { accepted: true, accepted_at: new Date().toISOString() } });
+      return { exitCode: EXIT.OK, receipt: { schema_version: RUN_SCHEMA_VERSION, outcome: "cancellation_requested", run_id: runId, exit_code: EXIT.OK } };
+    }
+    return { exitCode: EXIT.BACKEND, receipt: { schema_version: RUN_SCHEMA_VERSION, outcome: "rejected", run_id: runId, error: cancellation?.error ?? cancellation?.data?.error ?? "cancellation_handoff_failed", exit_code: EXIT.BACKEND } };
+  };
   if (!Number.isInteger(context.workload_pid) || context.workload_pid <= 0) {
-    return { exitCode: EXIT.INVALID, receipt: { schema_version: RUN_SCHEMA_VERSION, outcome: "rejected", run_id: runId, error: "durable owner has not started a workload", exit_code: EXIT.INVALID } };
+    // The marker is durable and checked twice by the worker. It must exist
+    // before the terminal API transition so a launcher-returned worker cannot
+    // begin executing after cancellation has been acknowledged.
+    const contextFile = context.context_path ?? contextPath(runId);
+    try {
+      await markCancellation(contextFile, context.run_id);
+    } catch (error) {
+      return { exitCode: EXIT.INTERNAL, receipt: { schema_version: RUN_SCHEMA_VERSION, outcome: "rejected", run_id: runId, error: `cancellation_fence_failed:${error instanceof Error ? error.message : String(error)}`, exit_code: EXIT.INTERNAL } };
+    }
+    if (Number.isInteger(context.worker_pid) && context.worker_pid > 0) {
+      // A live worker may have claimed the interval after launcher handoff.
+      // Fence it first; its SIGTERM handler either records a no-workload
+      // acknowledgement (safe for cancel_command_run) or terminates the
+      // workload and keeps ownership of the final update_command_run callback.
+      try { killWorker(context.worker_pid); } catch (error) {
+        if (error?.code !== "ESRCH") return { exitCode: EXIT.INTERNAL, receipt: { schema_version: RUN_SCHEMA_VERSION, outcome: "rejected", run_id: runId, error: `cancellation_worker_fence_failed:${error instanceof Error ? error.message : String(error)}`, exit_code: EXIT.INTERNAL } };
+      }
+      const fenced = await waitForCancellation(contextFile);
+      if (Number.isInteger(fenced?.workload_pid) && fenced.workload_pid > 0) {
+        terminateProcessGroup({ pid: fenced.workload_pid }, "SIGTERM");
+        return { exitCode: EXIT.OK, receipt: { schema_version: RUN_SCHEMA_VERSION, outcome: "cancellation_requested", run_id: runId, exit_code: EXIT.OK } };
+      }
+      if (fenced?.worker_state === "cancelled_before_workload_start" || !workerAlive(context.worker_pid)) return requestCancellation();
+      return { exitCode: EXIT.BACKEND, receipt: { schema_version: RUN_SCHEMA_VERSION, outcome: "rejected", run_id: runId, error: "cancellation_worker_fence_unconfirmed", exit_code: EXIT.BACKEND } };
+    }
+    return requestCancellation();
   }
   try {
     process.kill(-context.workload_pid, "SIGTERM");
   } catch (error) {
-    await call("update_command_run", { run_id: context.run_id, run_credential: context.run_credential, status: "owner_lost", invalidated_reason: `cancel_owner_unreachable:${error instanceof Error ? error.message : String(error)}` });
+    await callbackCall("update_command_run", { run_id: context.run_id, run_credential: context.run_credential, status: "owner_lost", invalidated_reason: `cancel_owner_unreachable:${error instanceof Error ? error.message : String(error)}` });
     return { exitCode: EXIT.INTERNAL, receipt: { schema_version: RUN_SCHEMA_VERSION, outcome: "owner_lost", run_id: runId, exit_code: EXIT.INTERNAL } };
   }
   return { exitCode: EXIT.OK, receipt: { schema_version: RUN_SCHEMA_VERSION, outcome: "cancellation_requested", run_id: runId, exit_code: EXIT.OK } };
@@ -548,11 +794,28 @@ async function finalize(context, state, call) {
   const sha256 = createHash("sha256").update(await readFile(context.receipt_path)).digest("hex");
   const apiStatus = ({ success: "succeeded", failure: "failed", cancelled: "cancelled", timed_out: "timed_out", owner_lost: "owner_lost" })[state.status];
   const update = { run_id: context.run_id, run_credential: context.run_credential, status: apiStatus, exit_code: state.exitCode ?? undefined, invalidated_reason: state.reason ?? (state.status === "timed_out" ? "timeout" : state.status === "owner_lost" ? "owner_lost" : undefined), receipt_path: context.receipt_upload, receipt_content_type: "application/json", receipt_byte_size: bytes.size, receipt_sha256: sha256, output_characters: outputCharacters, truncated: outputCharacters > MAX_CAPTURE_BYTES };
+  // A locally durable receipt is enough to publish the linked test run. Do it
+  // before the command callback's intentionally unbounded retry: otherwise an
+  // auth outage (for example agent_identity_required) strands a 0-case run in
+  // active state forever even though its command has already failed locally.
+  if (context.test_run) await completeTestRun(context, { status: state.status, exitCode: state.exitCode, signal: state.signal, startedAt: state.startedAt, endedAt: state.endedAt, call });
   await retryTerminalUpdate(context, update, call);
   try { await unlink(context.context_path); } catch { /* receipt is authoritative; context cleanup is best effort */ }
   return receipt;
 }
 
+function callWithContextIdentity(context, call) {
+  const token = typeof context.callback_session_token === "string" && SESSION_TOKEN_RE.test(context.callback_session_token)
+    ? context.callback_session_token
+    : null;
+  // Old contexts cannot safely fall back to the machine-level owner key. Ask
+  // the API layer to require a session instead; the retained receipt/context
+  // makes recovery possible without attributing a callback to the wrong agent.
+  return (name, args) => call(name, args, token
+    ? { auth: { "x-agent-api-key": token } }
+    : { requireSessionToken: true });
+}
+
 export async function retryTerminalUpdate(context, update, call, { sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)) } = {}) {
   let attempts = 0;
   let delay = 1_000;

package/src/test-lane.mjs

@@ -176,18 +176,29 @@ export async function launchTestLane(argv, {
     return { exitCode: EXIT_TEST.INVALID, line: JSON.stringify({ outcome: "rejected", errors }) };
   }
   let managedCredential = null;
-  if (!opts.sessionId && !opts.sessionToken) {
-    // Test doubles intentionally do not self-mint. The shipped command does,
-    // using exactly the same cache/re-adoption resolver as `bb wait` and `run`.
+  // A session id names a session but is not an API credential. Resolve the
+  // worktree's token even when the caller supplied --session-id, so the
+  // create/update calls are authenticated and the launched lane has a durable
+  // test-run to wait on. Without this, an otherwise valid explicit id could
+  // launch a real test with test_run_id:null and no supported wait condition.
+  //
+  // Test doubles that provide only a synthetic session id retain the old
+  // no-network seam. Production, and every caller that supplies a resolver,
+  // must resolve the token or fail before launching an untrackable run.
+  const mustResolveCredential = !opts.sessionToken
+    && (!opts.sessionId || !!resolveCredential || call === callToolJson);
+  if (mustResolveCredential) {
     if (!resolveCredential && call !== callToolJson) {
       process.stderr.write("botbuddy test: --session-id is required (or set BOTBUDDY_AGENT_SESSION_TOKEN)\n");
       return { exitCode: EXIT_TEST.INVALID, line: JSON.stringify({ outcome: "rejected", errors: ["--session-id is required"] }) };
     }
     try {
-      const credential = await (resolveCredential ?? resolveAgentSessionCredential)({ argv, env, cwd });
+      const credential = await (resolveCredential ?? resolveAgentSessionCredential)({ argv, env, cwd, sessionId: opts.sessionId });
       managedCredential = credential;
       opts.sessionToken = credential.token;
-      opts.sessionId = credential.sessionId ?? null;
+      // --session-id is a deliberate caller choice. The resolved token proves
+      // authority; it must not silently replace the session the caller named.
+      opts.sessionId ??= credential.sessionId ?? null;
     } catch (error) {
       const code = error?.code ?? "agent_session_unavailable";
       process.stderr.write(`botbuddy test: ${error?.message ?? code}\n`);