@botbuddy/cli 1.59.4 → 1.59.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@botbuddy/cli",
-  "version": "1.59.4",
+  "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/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`);