@botbuddy/cli 1.33.6 → 1.33.8

package/package.json

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

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,24 @@ 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",
+      // BOT-1612: a `chat:channel=<id>` wait whose bound agent is not one of the
+      // channel's participants could only ever park to timeout (the emitter never
+      // scopes a message to a non-participant). The relay refuses it at arm time;
+      // `chat_participant_ambiguous` means two of the caller's own live-session
+      // agents are participants and --session-id must pick one. Both are
+      // caller-actionable hard stops, not the untracked live-only fallback.
+      "chat_not_participant",
+      "chat_participant_ambiguous",
     ]);
     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 +467,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 +1635,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 +1743,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 +1924,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 +2003,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.