@botbuddy/cli 1.64.28 → 1.64.30

package/daemon-release/darwin-arm64.json

@@ -1,7 +1,7 @@
 {
-  "release_version": "1.64.28",
-  "source_commit": "68e4229ab423ab6cb69a029a794cd6f9bbdab501",
-  "source_sha256": "e456c16060302ab7b6d5642d057985316384a24e806ba400dcdba74836a5c886",
+  "release_version": "1.64.30",
+  "source_commit": "cea90b48937b714dae31540ddf0559943b9d87a2",
+  "source_sha256": "0ed4fcd3314212258923964ddc437034105fc914901e9bc055668ef650878cd2",
   "target": "darwin-arm64",
-  "sha256": "0234fb211982fc176db2da07f2c8be94d5c33f93e11ad2fc07e22c32ed62a8bd"
+  "sha256": "5b8dff2916c1bd2210c91631d93bbe376a15c4f1c3d1720d5b908cd6e2745385"
 }

package/daemon-release/linux-x64.json

@@ -1,7 +1,7 @@
 {
-  "release_version": "1.64.28",
-  "source_commit": "68e4229ab423ab6cb69a029a794cd6f9bbdab501",
-  "source_sha256": "e456c16060302ab7b6d5642d057985316384a24e806ba400dcdba74836a5c886",
+  "release_version": "1.64.30",
+  "source_commit": "cea90b48937b714dae31540ddf0559943b9d87a2",
+  "source_sha256": "0ed4fcd3314212258923964ddc437034105fc914901e9bc055668ef650878cd2",
   "target": "linux-x64",
-  "sha256": "402e8e84890e6095422c1e0ffa85639e9842fa3ffd3f5abd6d28a80f664b34b2"
+  "sha256": "711103b10bce9107321a8d9ad0e1e6d5cc86158d91234dcebfa952b7f0819f71"
 }

package/daemon-release/manifest.json

@@ -1,21 +1,21 @@
 {
   "schema_version": 1,
-  "release_version": "1.64.28",
-  "source_commit": "68e4229ab423ab6cb69a029a794cd6f9bbdab501",
-  "source_sha256": "e456c16060302ab7b6d5642d057985316384a24e806ba400dcdba74836a5c886",
+  "release_version": "1.64.30",
+  "source_commit": "cea90b48937b714dae31540ddf0559943b9d87a2",
+  "source_sha256": "0ed4fcd3314212258923964ddc437034105fc914901e9bc055668ef650878cd2",
   "targets": {
     "darwin-arm64": {
       "goos": "darwin",
       "goarch": "arm64",
       "binary": "daemon/bin/darwin-arm64/botbuddy-daemon",
-      "sha256": "0234fb211982fc176db2da07f2c8be94d5c33f93e11ad2fc07e22c32ed62a8bd",
+      "sha256": "5b8dff2916c1bd2210c91631d93bbe376a15c4f1c3d1720d5b908cd6e2745385",
       "mode": "0755"
     },
     "linux-x64": {
       "goos": "linux",
       "goarch": "amd64",
       "binary": "daemon/bin/linux-x64/botbuddy-daemon",
-      "sha256": "402e8e84890e6095422c1e0ffa85639e9842fa3ffd3f5abd6d28a80f664b34b2",
+      "sha256": "711103b10bce9107321a8d9ad0e1e6d5cc86158d91234dcebfa952b7f0819f71",
       "mode": "0755"
     }
   }

package/package.json

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

package/src/stack-run-outcome.mjs

@@ -188,6 +188,8 @@ export function buildStackRunOutcomePayload({ fields = {}, exitCode, runId = ran
   const failureMechanism = code === "REQUESTER_ORIGIN_DIGEST_UNAVAILABLE" &&
       ["origin_config_missing", "origin_digest_missing"].includes(fields.failure_mechanism)
     ? fields.failure_mechanism : null;
+  // BOT-2977: sent only on a stale-context refusal, so every other payload keeps its shape.
+  const fenceScope = code === "STALE_AGENT_CONTEXT" && ["session", "agent"].includes(fields.fence_scope) ? fields.fence_scope : null;
   return {
     run_id: runId,
     lease_id: validStackLeaseId(fields.lease_id),
@@ -212,6 +214,7 @@ export function buildStackRunOutcomePayload({ fields = {}, exitCode, runId = ran
     } : {}),
     ...(callbackAuthorizationReason ? { callback_authorization_reason: callbackAuthorizationReason } : {}),
     ...(failureMechanism ? { failure_mechanism: failureMechanism } : {}),
+    ...(fenceScope ? { fence_scope: fenceScope } : {}),
   };
 }
 
@@ -244,11 +247,11 @@ export async function reportStackRunOutcome({ fields, exitCode, runId, opts, env
       const first = await channel.callTool(STACK_RUN_OUTCOME_TOOL, payload, { auth: channel.auth, signal: ac.signal });
       // Older servers reject unknown keys before writing. Retry only that exact,
       // explicit rejection with the same run id; never retry an uncertain send.
-      if (!ac.signal.aborted && payload.failure_mechanism && first?.ok && first?.isError &&
-          first?.data?.code === "INVALID_STACK_RUN_OUTCOME" &&
-          typeof first?.data?.message === "string" &&
-          first.data.message.startsWith("unknown key 'failure_mechanism'")) {
-        const { failure_mechanism: _omitted, ...legacyPayload } = payload;
+      const refusedKey = ["failure_mechanism", "fence_scope"].find((key) => payload[key] &&
+        typeof first?.data?.message === "string" && first.data.message.startsWith(`unknown key '${key}'`));
+      if (!ac.signal.aborted && refusedKey && first?.ok && first?.isError &&
+          first?.data?.code === "INVALID_STACK_RUN_OUTCOME") {
+        const { [refusedKey]: _omitted, ...legacyPayload } = payload;
         return await channel.callTool(STACK_RUN_OUTCOME_TOOL, legacyPayload, { auth: channel.auth, signal: ac.signal });
       }
       return first;

package/src/stack.mjs

@@ -1488,13 +1488,52 @@ export const REMOTE_REFUSAL_GUIDANCE = Object.freeze({
 
 const AGENT_DEEPLINK_REQUIRED_GUIDANCE = "the control plane refused this stack because its owning agent has no canonical profile or native session link. Reconnect with `bb register`, then retry. No lease was created.";
 
+const STALE_CONTEXT_TICKET_RE = /^[A-Z][A-Z0-9]{1,15}-[0-9]{1,12}$/;
+
+/**
+ * BOT-2977: the one command that re-registers this worktree for the requested
+ * ticket. `bb doctor --fix` registers the ticket its BRANCH names, so it is only
+ * offered when that is the requested ticket. `branchTicket` undefined means the
+ * branch is unknown: say nothing rather than guess. Never retried automatically.
+ */
+function staleContextRecovery(requested, branchTicket) {
+  if (branchTicket === undefined || requested === "unknown") return "";
+  const branch = typeof branchTicket === "string" && STALE_CONTEXT_TICKET_RE.test(branchTicket) ? branchTicket : null;
+  if (branch === requested) return `Run \`bb doctor --fix\` in this worktree to re-register it for ${requested}, then retry. `;
+  return `${branch ? `This worktree's branch is for ${branch}` : "This worktree's branch names no ticket"}, so \`bb doctor --fix\` here would not register ${requested}: `
+    + `run \`bb doctor --fix\` in ${requested}'s worktree, or call register_agent with ticket_id ${requested} in this session, then retry. `;
+}
+
+/** BOT-2977: the fence the server applied (`session` for a tier-3 session, else `agent`). */
+export function staleContextFenceScope(data) {
+  return data?.code === "STALE_AGENT_CONTEXT" && (data.fence_scope === "session" || data.fence_scope === "agent") ? data.fence_scope : null;
+}
+
+/** BOT-2977: the ticket this checkout's branch names (null when none), read only for a stale-context refusal. */
+export async function currentBranchTicket(cwd = process.cwd()) {
+  try {
+    const git = spawnSync("git", ["rev-parse", "--abbrev-ref", "HEAD"], { cwd, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"], timeout: 5000 });
+    if (git.status !== 0 || typeof git.stdout !== "string") return undefined;
+    const branch = git.stdout.trim();
+    // A detached HEAD names no branch, so the branch's ticket is unknown, not absent.
+    if (!branch || branch === "HEAD") return undefined;
+    const match = branch.match(/(?:^|\/)\s*(bot|ent)-(\d+)(?:-|$)/i);
+    return match ? `${match[1].toUpperCase()}-${match[2]}` : null;
+  } catch {
+    return undefined;
+  }
+}
+
 /** The refusal text for a receipt: the server's message, else the CLI's guidance, else the code. */
-export function leaseRefusalError(data) {
+export function leaseRefusalError(data, { branchTicket } = {}) {
   if (data?.code === "STALE_AGENT_CONTEXT") {
     // These identifiers are shown only in the local receipt; never copy an
     // arbitrary server string into it or into the separate telemetry envelope.
-    const ticket = (value) => typeof value === "string" && /^[A-Z][A-Z0-9]{1,15}-[0-9]{1,12}$/.test(value) ? value : "unknown";
-    return `STALE_AGENT_CONTEXT: registered ticket ${ticket(data.registered_ticket_id)}; requested ticket ${ticket(data.requested_ticket_id)}. No lease was created. Run \`bb help register_agent\` to inspect the supported session registration options before retrying.`;
+    const ticket = (value) => typeof value === "string" && STALE_CONTEXT_TICKET_RE.test(value) ? value : "unknown";
+    const requested = ticket(data.requested_ticket_id);
+    return `STALE_AGENT_CONTEXT: registered ticket ${ticket(data.registered_ticket_id)}; requested ticket ${requested}. No lease was created. `
+      + staleContextRecovery(requested, branchTicket)
+      + "Run `bb help register_agent` to inspect the supported session registration options before retrying.";
   }
   if (data?.lease_id && ["STACK_CONTEXT_BIND_FAILED", "STACK_CONTEXT_ALREADY_BOUND"].includes(data?.code)) {
     return `${data.message || data.code}; lease ${data.lease_id} is ${data.state ?? "unknown"}. ` +
@@ -2651,6 +2690,8 @@ async function cmdUpOnce(opts, {
   machineUuidFn = machineUuid,
   assertIsolated = validateLocalExecTarget,
   refreshAuth = refreshRejectedCacheAuth,
+  // BOT-2977: the ticket this checkout's branch names, read only for a stale-context refusal.
+  branchTicket = currentBranchTicket,
   reportLaneStatus = writeLaneStatus,
   waitCapacity = defaultWaitCapacity,
   reauth = (current, kind) => reauthenticateParkedLease(current, kind),
@@ -2791,8 +2832,11 @@ async function cmdUpOnce(opts, {
   if (!d.success) {
     const hint = worktreeRegistrationHint(d.code, auth) ?? stackPathRootRefusalNotice(d.code, d.message);
     if (hint) process.stderr.write(`${hint}\n`);
+    const fenceScope = staleContextFenceScope(d);
+    const staleBranchTicket = d.code === "STALE_AGENT_CONTEXT" ? await branchTicket() : undefined;
     return emitResult(buildReceipt({
-      command: "up", outcome: "error", code: d.code, ...capacityStaleReceiptFields(d), error: leaseRefusalError(d), slot,
+      command: "up", outcome: "error", code: d.code, ...capacityStaleReceiptFields(d), error: leaseRefusalError(d, { branchTicket: staleBranchTicket }), slot,
+      ...(fenceScope ? { fence_scope: fenceScope } : {}),
     }), opts, leaseRefusalExit(d.code));
   }
   let leaseId = d.lease_id;
@@ -4762,9 +4806,13 @@ async function runStackLifecycleOnce(opts, childArgv, adapters, incidentBox) {
       // an idle mode mismatch) is not proof that its ports are free. Keep the
       // claim until owner-safe cleanup is verified; never reap a possibly live batch.
       if (request.data?.lease_id) retainBlock = true;
+      // BOT-2977: name the re-registration command; the refusal itself is never retried here.
+      const fenceScope = staleContextFenceScope(request.data);
+      const branchTicket = request.data?.code === "STALE_AGENT_CONTEXT" ? await (adapters.branchTicket ?? currentBranchTicket)() : undefined;
       return {
         exitCode: leaseRefusalExit(request.data?.code), outcome: "error", code: request.data?.code,
-        ...capacityStaleReceiptFields(request.data), error: leaseRefusalError(request.data),
+        ...(fenceScope ? { fenceScope } : {}),
+        ...capacityStaleReceiptFields(request.data), error: leaseRefusalError(request.data, { branchTicket }),
         ...(request.data?.sqlstate ? { sqlstate: request.data.sqlstate } : {}),
         ...(request.data.lease_id ? { leaseId: request.data.lease_id, state: request.data.state ?? null } : {}),
       };
@@ -5455,6 +5503,9 @@ export function runReceiptFields(result) {
     ...(result.callbackAuthorizationReason ? { callback_authorization_reason: result.callbackAuthorizationReason } : {}),
     ...(result.code === "REQUESTER_ORIGIN_DIGEST_UNAVAILABLE" && ["origin_config_missing", "origin_digest_missing"].includes(result.failureMechanism)
       ? { failure_mechanism: result.failureMechanism } : {}),
+    // BOT-2977: which fence refused a STALE_AGENT_CONTEXT run (session | agent).
+    ...(result.code === "STALE_AGENT_CONTEXT" && (result.fenceScope === "session" || result.fenceScope === "agent")
+      ? { fence_scope: result.fenceScope } : {}),
     // BOT-2957: the control-plane gaps this run's callback route rode through (never on a run that had none).
     ...(result.callbackOutage ? { callback_outage: result.callbackOutage } : {}),
     // BOT-2780: the reserved requester origin generated auth links name (never a credential).