@botbuddy/cli 1.33.5 → 1.33.7

package/package.json

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

package/src/stack.mjs

@@ -76,10 +76,12 @@ ${bold("up OPTIONS")}
   --host <host_key>      Pin to a canonical host. Omit to auto-select a beacon-fresh host.
   --repo <repo>          Repository the batch is for (e.g. botbuddy-web).
   --ticket <BOT-123>     Ticket the batch is for (also used to derive the slot).
-  --stack-path <relative> Stack directory inside the registered worktree (default: .).
-                         REQUIRED with --local-exec: point it at a slot-derived stack whose
-                         supabase/config.toml declares a DISTINCT project_id + remapped ports
-                         (never the worktree root's shared canonical project).
+  --stack-path <relative> ISOLATED stack directory inside the registered worktree. Required:
+                         the control plane refuses the worktree root (stack_path_root_refused,
+                         BOT-1797) because its supabase/config.toml is the repo's SHARED
+                         canonical project. Point it at a slot-derived stack whose
+                         supabase/config.toml declares a DISTINCT project_id + remapped ports,
+                         or use 'stack run', which materializes one for you.
   --purpose <text>       Free-text purpose recorded on the lease.
   --idle-ttl <seconds>   Idle seconds before the reaper STOPS an unused stack (default 1800).
   --timeout <seconds>    Max seconds to park for capacity before giving up (default ${DEFAULT_TIMEOUT_SEC}).
@@ -669,6 +671,39 @@ export function worktreeRegistrationHint(code, auth) {
     + `Run \`bb doctor --fix\` here to register its host + machine id, then retry.`;
 }
 
+// BOT-1797: the control plane refuses a Helper-backed lease whose stack_path is the
+// worktree root — its supabase/config.toml is the repo's SHARED canonical project, so
+// the Helper would start (and on reap destroy) the shared dev stack. This CLI always
+// materializes an isolated stack (BOT-1798), so seeing this code means a stale binary,
+// an explicit root --stack-path, or a wrapper that hand-rolls the lease call.
+export const STACK_PATH_ROOT_REFUSED_CODE = "stack_path_root_refused";
+
+// Only used when an older/leaner server sends the code with no message; the server's
+// own message is always preferred so the two can never drift.
+const STACK_PATH_ROOT_REFUSED_FALLBACK =
+  "the control plane refused a stack lease at the worktree root (the repo's shared stack). " +
+  "Upgrade with `npm i -g @botbuddy/cli@latest`, or pass --stack-path <isolated dir>.";
+
+/** The server's root refusal, verbatim, as one operator-facing line (or null). */
+export function stackPathRootRefusalNotice(code, message) {
+  if (code !== STACK_PATH_ROOT_REFUSED_CODE) return null;
+  return `${yellow("⚠")} stack: ${message || STACK_PATH_ROOT_REFUSED_FALLBACK}`;
+}
+
+/**
+ * Exit code for a lease the server REFUSED (`success: false`). A refused root path is a
+ * bad argument the caller must fix — INVALID (4) — not a backend fault, which automation
+ * reads as "the control plane is unhealthy, retry". Every other refusal keeps BACKEND (5).
+ */
+export function leaseRefusalExit(code) {
+  return code === STACK_PATH_ROOT_REFUSED_CODE ? EXIT.INVALID : EXIT.BACKEND;
+}
+
+/** The refusal text for a receipt: the server's message, else its code. */
+export function leaseRefusalError(data) {
+  return data?.message || data?.code || "lease request refused";
+}
+
 // The MCP lease endpoint accepts a session token in x-agent-api-key, whereas
 // the event-stream relay requires that same token in its bearer form too. Keep
 // the lease RPC shape unchanged and derive the relay-compatible form only at
@@ -1340,9 +1375,9 @@ export async function cmdUp(opts, {
   }
   const d = req.data;
   if (!d.success) {
-    const hint = worktreeRegistrationHint(d.code, auth);
+    const hint = worktreeRegistrationHint(d.code, auth) ?? stackPathRootRefusalNotice(d.code, d.message);
     if (hint) process.stderr.write(`${hint}\n`);
-    return emitResult(buildReceipt({ command: "up", outcome: "error", code: d.code, error: d.message || d.code || "request refused", slot }), opts, EXIT.BACKEND);
+    return emitResult(buildReceipt({ command: "up", outcome: "error", code: d.code, error: leaseRefusalError(d), slot }), opts, leaseRefusalExit(d.code));
   }
   let leaseId = d.lease_id;
   let state = d.state;
@@ -2007,9 +2042,10 @@ export async function runStackLifecycle(opts, childArgv, adapters = {}) {
       return { exitCode: request?.auth ? EXIT.AUTH : EXIT.BACKEND, outcome: "error", error: request?.error || "lease request failed" };
     }
     if (!request.data?.success) {
-      const hint = worktreeRegistrationHint(request.data?.code, rpc.auth);
+      const hint = worktreeRegistrationHint(request.data?.code, rpc.auth)
+        ?? stackPathRootRefusalNotice(request.data?.code, request.data?.message);
       if (hint) process.stderr.write(`${hint}\n`);
-      return { exitCode: EXIT.BACKEND, outcome: "error", error: request.data?.message || request.data?.code || "lease request refused" };
+      return { exitCode: leaseRefusalExit(request.data?.code), outcome: "error", code: request.data?.code, error: leaseRefusalError(request.data) };
     }
     leaseId = request.data.lease_id;
     if (request.data.reused) {
@@ -2154,7 +2190,9 @@ export async function runStackLifecycle(opts, childArgv, adapters = {}) {
 async function cmdRun(opts, childArgv) {
   const result = await runStackLifecycle(opts, childArgv);
   return emit(buildReceipt({
-    command: "run", outcome: result.outcome, lease_id: result.leaseId ?? null,
+    // BOT-1797: carry the server's typed refusal code (e.g. stack_path_root_refused)
+    // so automation can branch on it instead of matching the message text.
+    command: "run", outcome: result.outcome, code: result.code ?? null, lease_id: result.leaseId ?? null,
     child_exit_code: result.childExitCode ?? null, cleanup: result.cleanup?.ok ?? null,
     fenced: result.fenced ?? false, error: result.error ?? result.cleanup?.error ?? null,
   }), opts, result.exitCode);

package/src/wait-core.mjs

@@ -692,6 +692,49 @@ export function formatPrReviewSnapshotWarnings(snapshot, now = Date.now()) {
   return lines;
 }
 
+/**
+ * BOT-1837 — the one-line arm-time notice for a `scope=next` ci wait, built from
+ * the relay's `arm_context.latest_run`. Report-only: it says what CI has ALREADY
+ * done on the branch, so an agent that armed after the run it meant can see that
+ * immediately instead of discovering it at the deadline. Returns null when there
+ * is nothing to report. A missing field is reported as unknown, never guessed.
+ *
+ * @param {{run_id?:string|number|null,workflow_name?:string|null,status?:string|null,conclusion?:string|null,created_at?:string|null}|null|undefined} latestRun
+ * @param {{branch?:string|null, now?:number}} [opts]
+ * @returns {string|null}
+ */
+export function formatCiLatestRunNotice(latestRun, { branch = null, now = Date.now() } = {}) {
+  if (!latestRun || typeof latestRun !== "object") return null;
+  const runId = latestRun.run_id ?? "?";
+  const workflow = latestRun.workflow_name || "unknown workflow";
+  const status = latestRun.status || "unknown";
+  const conclusion = latestRun.conclusion || "none";
+  const createdMs = Date.parse(latestRun.created_at ?? "");
+  const age = Number.isFinite(createdMs)
+    ? `${Math.max(0, Math.round((now - createdMs) / 60000))} min ago`
+    : "age unknown";
+  return `latest run on ${branch || "?"}: ${workflow} #${runId} ${status}/${conclusion} ` +
+    `(${age}) — scope=next wakes only on a NEWER run`;
+}
+
+/**
+ * BOT-1837 — the stderr block for a relay `unknown_workflow` refusal: the
+ * server's detail, then one COPY-PASTEABLE `workflow=<name>` line per candidate
+ * so the fix is a paste, not a guess.
+ *
+ * @param {string} detail
+ * @param {string[]|null|undefined} candidates
+ * @returns {string[]}
+ */
+export function formatUnknownWorkflowGuidance(detail, candidates) {
+  const lines = [String(detail)];
+  const named = Array.isArray(candidates) ? candidates.filter((c) => typeof c === "string" && c.trim() !== "") : [];
+  if (named.length === 0) return lines;
+  lines.push("closest workflow names this repo has actually reported:");
+  for (const name of named) lines.push(`  workflow=${name}`);
+  return lines;
+}
+
 // ---------------------------------------------------------------------------
 // Matching — does a spine signal frame satisfy a condition?
 // ---------------------------------------------------------------------------
@@ -1073,6 +1116,10 @@ export async function runWaitLoop({
   // wait capacity_source_stale even though the host recovered seconds after the stale
   // frame. 90s = 60s cron + margin.
   beaconConfirmMs = 90_000,
+  // BOT-1837: the arm-time notice (if any) to carry into a TIMEOUT receipt's
+  // `error`, so the receipt itself says what CI was already doing when this wait
+  // armed. Purely descriptive — it never changes the outcome or the exit code.
+  timeoutError = null,
 }) {
   const startedAt = typeof originalStartedAt === "string" && Number.isFinite(Date.parse(originalStartedAt))
     ? originalStartedAt : nowIso();
@@ -1206,7 +1253,7 @@ export async function runWaitLoop({
     // The terminal feed-freshness reprobe now lives in finalize() (the single
     // finalization path), so every terminal receipt gets it — not just the alarm path.
     if (!alarm) return null;
-    if (alarm.kind === "timeout") return finalize("timeout", { exitCode: EXIT.TIMEOUT });
+    if (alarm.kind === "timeout") return finalize("timeout", { exitCode: EXIT.TIMEOUT, error: timeoutError ?? null });
     if (alarm.kind === "stale") {
       // Capacity source didn't deliver within the grace: degrade truthfully and
       // exit with an error receipt (not a silent hang, not a plain timeout).

package/src/wait.mjs

@@ -13,7 +13,7 @@
 // Usage:  botbuddy wait [--any] <condition>... [options]
 // Run     botbuddy wait --help for the condition grammar.
 
-import { EXIT, parseConditions, parseSseFrames, runWaitLoop, normalizeSince, truncateReceipt, formatPrReviewSnapshotWarnings } from "./wait-core.mjs";
+import { EXIT, parseConditions, parseSseFrames, runWaitLoop, normalizeSince, truncateReceipt, formatPrReviewSnapshotWarnings, formatCiLatestRunNotice, formatUnknownWorkflowGuidance } from "./wait-core.mjs";
 import { readAgentBinding, withPrincipalReceipt } from "./wait-profile.mjs";
 import { VERSION } from "./version.mjs";
 import { fileURLToPath } from "node:url";
@@ -352,11 +352,16 @@ async function registerWait(opts, conditions, deadlineIso) {
       "session_id_required",
       "wait_resume_identity_invalid",
       "wait_resume_identity_mismatch",
+      // BOT-1837: `workflow=` names a workflow this repo has never reported a
+      // wake-capable run for. The wait could only ever expire, and no amount of
+      // waiting repairs a typo — a hard stop, with the server's candidates.
+      "unknown_workflow",
     ]);
     if (INVALID_CONDITION_CODES.has(body.error)) {
       const err = new Error(body.detail || body.error);
       err.invalidCondition = true;
       err.errorCode = body.error;
+      if (Array.isArray(body.candidates)) err.candidates = body.candidates;
       throw err;
     }
   }
@@ -454,6 +459,13 @@ async function registerWait(opts, conditions, deadlineIso) {
     // pr-review/pr-state target. Report-only — surfaced on stderr so a silent
     // edge-triggered park isn't mistaken for "no review yet".
     prReviewSnapshot: Array.isArray(body.pr_review_snapshot) ? body.pr_review_snapshot : null,
+    // BOT-1837: what CI had already done on the branch at arm time. An ABSENT
+    // arm_context (a pre-BOT-1837 relay, or a condition that isn't scope=next
+    // with a branch) and an explicit `latest_run: null` both collapse to null —
+    // there is simply nothing to report either way.
+    armLatestRun: body.arm_context && typeof body.arm_context === "object"
+      ? (body.arm_context.latest_run ?? null)
+      : null,
     status: typeof body.status === "string" ? body.status : "active",
     // A canonicalized alias wait was deliberately abandoned and already has a
     // sequenced wait_superseded signal. Preserve that terminal state and replay
@@ -1615,6 +1627,10 @@ export async function runWait(argv, { recoveryLocalWaitId = null } = {}) {
   // BOT-1467: the session agent the relay attributed the wait to (when overridden).
   let registeredSessionAgentId = null;
   let registeredSessionId = null;
+  // BOT-1837: the arm-time "latest run on <branch>" notice, printed once on
+  // register and reused as the timeout receipt's error. Null when there is
+  // nothing to report (no ci scope=next+branch condition, or no run yet).
+  let ciArmNotice = null;
   let replayMatchedClaim = false;
   let replayExpiredRecovery = false;
   if (needsRelay) {
@@ -1719,6 +1735,13 @@ export async function runWait(argv, { recoveryLocalWaitId = null } = {}) {
       for (const line of formatPrReviewSnapshotWarnings(reg.prReviewSnapshot)) {
         process.stderr.write(`bb-wait: ${line}\n`);
       }
+      // BOT-1837: one line naming the branch's latest run at arm time. Report-only
+      // (arming before dispatch is the correct flow), and carried into a timeout
+      // receipt below so the receipt explains the silence too.
+      ciArmNotice = formatCiLatestRunNotice(reg.armLatestRun, {
+        branch: conditions.find((c) => c.type === "ci" && c.params?.branch)?.params?.branch ?? null,
+      });
+      if (ciArmNotice) process.stderr.write(`bb-wait: ${ciArmNotice}\n`);
       // BOT-1184: adopt the server's canonical host for each lock condition so the
       // local matcher builds the same subject_key the availability/claim-grant
       // signals carry (armed under an alias like 'jono-mac', the signal uses the
@@ -1893,8 +1916,21 @@ export async function runWait(argv, { recoveryLocalWaitId = null } = {}) {
         // A rejected condition set is a configuration error, not a wait — fail closed
         // rather than arming an untracked wait that skips the server's initial
         // evaluation (BOT-1066 no_signal_source, BOT-1247 unblocked_cross_tenant, …).
+        if (err.errorCode === "unknown_workflow") {
+          // BOT-1837: print the workflow names this repo HAS reported, one
+          // copy-pasteable `workflow=<name>` per line, so the retry is a paste.
+          for (const line of formatUnknownWorkflowGuidance(err.message, err.candidates)) {
+            process.stderr.write(`bb-wait: ${line}\n`);
+          }
+        }
         process.stderr.write(`bb-wait: invalid condition (${err.errorCode}) — ${err.message}\n`);
-        emitReceipt({ schema_version: 1, outcome: "error", error: err.errorCode, detail: String(err.message) });
+        emitReceipt({
+          schema_version: 1,
+          outcome: "error",
+          error: err.errorCode,
+          detail: String(err.message),
+          ...(Array.isArray(err.candidates) && err.candidates.length > 0 ? { candidates: err.candidates } : {}),
+        });
         process.exit(EXIT.INVALID);
       }
       if (err && err.initialEval) {
@@ -1959,6 +1995,9 @@ export async function runWait(argv, { recoveryLocalWaitId = null } = {}) {
       feedLagProbe,
       receiptMaxBytes: opts.receiptMaxBytes,
       startedAt: checkpoint.created_at,
+      // BOT-1837: a timeout receipt carries the arm-time CI notice, so a caller
+      // reading only the receipt learns the run it meant had already finished.
+      timeoutError: ciArmNotice,
       // BOT-1259: fail-closed tenant scope for the central guard, plus a debug sink
       // (opt-in via BB_WAIT_DEBUG) that surfaces each fail-closed drop without turning
       // it into an error.