@botbuddy/cli 1.63.42 → 1.63.43

package/daemon-release/darwin-arm64.json

@@ -1,7 +1,7 @@
 {
-  "release_version": "1.63.42",
-  "source_commit": "68cd7a93519197cc7b96a190fa0c4b4799a9c45d",
-  "source_sha256": "3a4e94f577771c564aa24d54529368c6b6d325be1e64ef0a30da1531f02be6ed",
+  "release_version": "1.63.43",
+  "source_commit": "580bdbe602c9281c639efbd317018a75011ea70c",
+  "source_sha256": "d04edc606580d8c6304eb6ed88d1fbb9b5a6c8d9b0aad2fea9f92e1cc1cedbb7",
   "target": "darwin-arm64",
-  "sha256": "3c5f90061df675f1e06408ce5e1f3c9b6350e5a237216b0dbc11d71d656a1b35"
+  "sha256": "ec91fd06a1a4da1a271c5343619f66f18ea16c2d676247fbd22e5bfaa9a9a976"
 }

package/daemon-release/linux-x64.json

@@ -1,7 +1,7 @@
 {
-  "release_version": "1.63.42",
-  "source_commit": "68cd7a93519197cc7b96a190fa0c4b4799a9c45d",
-  "source_sha256": "3a4e94f577771c564aa24d54529368c6b6d325be1e64ef0a30da1531f02be6ed",
+  "release_version": "1.63.43",
+  "source_commit": "580bdbe602c9281c639efbd317018a75011ea70c",
+  "source_sha256": "d04edc606580d8c6304eb6ed88d1fbb9b5a6c8d9b0aad2fea9f92e1cc1cedbb7",
   "target": "linux-x64",
-  "sha256": "a5a474195eca0a8b57ddf8c5d50cfddb88f083a57bc99e80dc4f1a7d10e99535"
+  "sha256": "8437df29241846a8dddfad4ce6c5a77237c0dc38bf8006512e4c22fe911fb380"
 }

package/daemon-release/manifest.json

@@ -1,21 +1,21 @@
 {
   "schema_version": 1,
-  "release_version": "1.63.42",
-  "source_commit": "68cd7a93519197cc7b96a190fa0c4b4799a9c45d",
-  "source_sha256": "3a4e94f577771c564aa24d54529368c6b6d325be1e64ef0a30da1531f02be6ed",
+  "release_version": "1.63.43",
+  "source_commit": "580bdbe602c9281c639efbd317018a75011ea70c",
+  "source_sha256": "d04edc606580d8c6304eb6ed88d1fbb9b5a6c8d9b0aad2fea9f92e1cc1cedbb7",
   "targets": {
     "darwin-arm64": {
       "goos": "darwin",
       "goarch": "arm64",
       "binary": "daemon/bin/darwin-arm64/botbuddy-daemon",
-      "sha256": "3c5f90061df675f1e06408ce5e1f3c9b6350e5a237216b0dbc11d71d656a1b35",
+      "sha256": "ec91fd06a1a4da1a271c5343619f66f18ea16c2d676247fbd22e5bfaa9a9a976",
       "mode": "0755"
     },
     "linux-x64": {
       "goos": "linux",
       "goarch": "amd64",
       "binary": "daemon/bin/linux-x64/botbuddy-daemon",
-      "sha256": "a5a474195eca0a8b57ddf8c5d50cfddb88f083a57bc99e80dc4f1a7d10e99535",
+      "sha256": "8437df29241846a8dddfad4ce6c5a77237c0dc38bf8006512e4c22fe911fb380",
       "mode": "0755"
     }
   }

package/package.json

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

package/src/stack-native-callback.mjs

@@ -21,6 +21,19 @@ const fail=(code,message)=>{throw Object.assign(Error(message),{code});};
 const quote=value=>"'"+String(value).replaceAll("'","'\\''")+"'";
 // BOT-2828: a relay-reported cause is one fixed upper-case code, never free text.
 const typedCause=value=>typeof value==='string'&&/^CALLBACK_[A-Z_]{1,64}$/.test(value)?value:null;
+// BOT-2880: which check refused. A bounded token naming the check or changed field, never its value.
+const AUTHORIZATION_REASON=/^[a-z0-9_.:-]{1,64}$/;
+export const boundedAuthorizationReason=value=>typeof value==='string'&&AUTHORIZATION_REASON.test(value)?value:null;
+const refuse=(reason,message)=>{throw Object.assign(Error(message),{code:'CALLBACK_AUTHORIZATION_LOST',authorizationReason:reason});};
+const tokenReason=(name,value)=>boundedAuthorizationReason(name+':'+value)??name;
+function changedBindingField(previous,next,path=''){
+ for(const key of new Set([...Object.keys(previous),...Object.keys(next)])){
+  const a=previous[key],b=next[key],field=path+key;
+  if(a&&b&&typeof a==='object'&&typeof b==='object'){const nested=changedBindingField(a,b,field+'.');if(nested)return nested;}
+  else if(a!==b)return field;
+ }
+ return null;
+}
 const canonicalMachine=value=>typeof value==='string'&&/^(?:[0-9a-f]{32}|[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})$/i.test(value)?value.replaceAll('-','').toLowerCase():null;
 
 export function validatedCallbackDescriptor(value){
@@ -31,10 +44,21 @@ export function validatedCallbackDescriptor(value){
 }
 
 export function currentCallbackBinding(current,{leaseId,hostKey,callbackPort,requesterMachineId,routeGeneration}){
- if(current?.callback_transport!==NATIVE_CALLBACK_TRANSPORT)fail('HOST_CALLBACK_TRANSPORT_UNSUPPORTED','backend did not acknowledge required callback transport');
- if(current.callback_current_authorization!==true||current.state!=='active'||current.execution_mode!=='remote')fail('CALLBACK_AUTHORIZATION_LOST','current callback authorization unavailable');
- const context=current.callback_context,d=validatedCallbackDescriptor(context?.descriptor);
- if(current.lease_id!==leaseId||current.host_key!==hostKey||d.lease_id!==leaseId||d.host_key!==hostKey||d.callback_port!==callbackPort||current.callback_port!==callbackPort||d.project_id!==current.connection?.project_id||!context||context.tenant_id!==d.tenant_id||!text(context.owner)||!uuid.test(context.requester_machine_id)||canonicalMachine(requesterMachineId)!==canonicalMachine(context.requester_machine_id)||!uuid.test(routeGeneration))fail('CALLBACK_AUTHORIZATION_LOST','current callback context changed');
+ if(current?.callback_transport!==NATIVE_CALLBACK_TRANSPORT)throw Object.assign(Error('backend did not acknowledge required callback transport'),{code:'HOST_CALLBACK_TRANSPORT_UNSUPPORTED',authorizationReason:'binding_callback_transport'});
+ if(current.state!=='active')refuse(tokenReason('lease_state',current.state),'current callback authorization unavailable');
+ if(current.execution_mode!=='remote')refuse(tokenReason('lease_execution_mode',current.execution_mode),'current callback authorization unavailable');
+ if(current.callback_current_authorization!==true)refuse(boundedAuthorizationReason(current.callback_authorization_reason)??'server_not_authorized','current callback authorization unavailable');
+ const context=current.callback_context;let d;
+ try{d=validatedCallbackDescriptor(context?.descriptor)}catch(error){throw Object.assign(error,{authorizationReason:'descriptor_refused'});}
+ for(const [changed,reason] of [
+  [current.lease_id!==leaseId,'binding_lease_id'],[current.host_key!==hostKey,'binding_host_key'],
+  [d.lease_id!==leaseId,'binding_descriptor_lease_id'],[d.host_key!==hostKey,'binding_descriptor_host_key'],
+  [d.callback_port!==callbackPort,'binding_descriptor_callback_port'],[current.callback_port!==callbackPort,'binding_callback_port'],
+  [d.project_id!==current.connection?.project_id,'binding_project_id'],[context.tenant_id!==d.tenant_id,'binding_tenant_id'],
+  [!text(context.owner),'binding_owner'],
+  [!uuid.test(context.requester_machine_id)||canonicalMachine(requesterMachineId)!==canonicalMachine(context.requester_machine_id),'binding_requester_machine_id'],
+  [!uuid.test(routeGeneration),'binding_route_generation'],
+ ])if(changed)refuse(reason,'current callback context changed');
  return Object.freeze({owner:context.owner,tenant_id:context.tenant_id,requester_machine_id:context.requester_machine_id,route_generation:routeGeneration,origin:'requester_http',descriptor:d});
 }
 
@@ -107,29 +131,35 @@ export async function openNativeCallbackTransport({current,leaseId,hostKey,callb
   });
   const callbackUrl=callbackReadiness(ready,callbackPort);
   gateway.onClose(()=>{if(!closed){reportExit({reason:'callback_gateway_closed',code:'CALLBACK_GATEWAY_EXPIRED'});void close().catch(()=>{})}});
-  let renewedAt=null;
+  let renewedAt=null,refusalPending=false;
   const refresh=async(first=false)=>{
    if(closed||refreshing)return;refreshing=true;
    try{
-    statusAbort=new AbortController();let statusTimeout,status;
-    try{status=await new Promise((resolve,reject)=>{statusTimeout=setTimeout(()=>{statusAbort.abort();reject(Object.assign(Error('callback status deadline'),{transient:true}));},statusDeadlineMs);statusTimeout.unref();Promise.resolve().then(()=>readCurrent(statusAbort.signal)).then(resolve,reject).finally(()=>clearTimeout(statusTimeout));});}
-    catch(error){
+    statusAbort=new AbortController();let statusTimeout,renewed;
+    try{
+     const status=await new Promise((resolve,reject)=>{statusTimeout=setTimeout(()=>{statusAbort.abort();reject(Object.assign(Error('callback status deadline'),{transient:true}));},statusDeadlineMs);statusTimeout.unref();Promise.resolve().then(()=>readCurrent(statusAbort.signal)).then(resolve,reject).finally(()=>clearTimeout(statusTimeout));});
+     if(closed)return;renewed=currentCallbackBinding(status,options);
+     if(JSON.stringify(renewed)!==snapshot)refuse(tokenReason('binding_changed',changedBindingField(binding,renewed)),'callback context changed');
+     refusalPending=false;
+    }catch(error){
      // A failed status READ is not an authorization answer: keep the live generation (relay and
      // gateway still expire it at 30 s) and retry on the next tick while inside the grace window.
      if(!first&&error?.transient===true&&renewedAt!==null&&performance.now()-renewedAt<transientGraceMs){const retry=setTimeout(()=>{void refresh()},transientRetryMs);retry.unref();return;}
      if(error?.transient===true&&!error.code&&!first)error.code='CALLBACK_STATUS_UNREADABLE';
+     // BOT-2880: a definitive answer stops the child only if one re-read repeats it, while the live
+     // generation can still carry that re-read. The opening renewal and an expired grace fail closed.
+     if(!first&&error?.transient!==true&&!refusalPending&&renewedAt!==null&&performance.now()-renewedAt<transientGraceMs){refusalPending=true;const retry=setTimeout(()=>{void refresh()},transientRetryMs);retry.unref();return;}
      throw error;
     }
-    if(closed)return;const renewed=currentCallbackBinding(status,options);if(JSON.stringify(renewed)!==snapshot)fail('CALLBACK_AUTHORIZATION_LOST','callback context changed');
     const sentAt=performance.now();
     await new Promise((resolve,reject)=>{const timeout=setTimeout(()=>reject(Object.assign(Error('callback renewal acknowledgement deadline'),first?{}:{code:'CALLBACK_RENEWAL_ACK_TIMEOUT',transport:true})),first?firstAckMs:renewAckMs);timeout.unref();pendingAck={resolve:value=>{clearTimeout(timeout);resolve(value)},reject:error=>{clearTimeout(timeout);reject(error)}};child.stdin.write(JSON.stringify({binding:renewed,renew:true})+'\n');});
     if(closed)return;renewedAt=sentAt;gateway.refresh(Object.freeze({snapshot}),30_000-(performance.now()-sentAt));
    }
    // The first renewal carries the consuming-namespace probe: its uncoded failure is readiness.
-   catch(error){if(!closed){reportExit({reason:error?.transport===true?'callback_renewal_unacknowledged':'callback_authorization_lost',code:error?.code??(first?'CALLBACK_NOT_READY':'CALLBACK_AUTHORIZATION_LOST')});void close().catch(()=>{});}}
+   catch(error){if(!closed){const authorizationReason=boundedAuthorizationReason(error?.authorizationReason);reportExit({reason:error?.transport===true?'callback_renewal_unacknowledged':'callback_authorization_lost',code:error?.code??(first?'CALLBACK_NOT_READY':'CALLBACK_AUTHORIZATION_LOST'),...(authorizationReason?{authorization_reason:authorizationReason}:{})});void close().catch(()=>{});}}
    finally{refreshing=false}
   };
-  await refresh(true);if(closed||!gateway.isLive())fail(exitResult?.code??'CALLBACK_NOT_READY','callback route not ready after readiness');
+  await refresh(true);if(closed||!gateway.isLive())throw Object.assign(Error('callback route not ready after readiness'),{code:exitResult?.code??'CALLBACK_NOT_READY',...(exitResult?.authorization_reason?{authorizationReason:exitResult.authorization_reason}:{})});
   refreshTimer=setInterval(refresh,renewIntervalMs);refreshTimer.unref();
   return{callbackUrl,close,isLive:()=>!closed&&gateway.isLive(),onExit(listener){exits.add(listener);if(exitResult)listener(exitResult)}};
  }catch(error){try{await close()}catch{fail('CALLBACK_CLEANUP_UNCERTAIN','owned callback cleanup could not be verified');}throw error;}

package/src/stack-run-outcome.mjs

@@ -31,6 +31,7 @@ const LANE_RE = /^[A-Za-z0-9:_.-]{1,128}$/;
 const TICKET_RE = /^[A-Za-z][A-Za-z0-9]*-\d{1,9}$/;
 const REPO_RE = /^[A-Za-z0-9._/-]{1,128}$/;
 const VERSION_RE = /^[0-9A-Za-z.+-]{1,32}$/;
+const AUTHORIZATION_REASON_RE = /^[a-z0-9_.:-]{1,64}$/;
 
 // Mirrors stack.mjs EXIT (kept local so this module stays dependency-free for tests).
 const EXIT_TIMEOUT = 2;
@@ -109,6 +110,8 @@ const exitInt = (value) => (Number.isInteger(value) && value >= 0 && value <= 25
  */
 export function buildStackRunOutcomePayload({ fields = {}, exitCode, runId = randomUUID(), opts = {}, env = process.env, durationMs = null }) {
   const { category, code } = classifyStackRunOutcome(fields, exitCode);
+  // BOT-2880: sent only when present, because an older server refuses an unknown key.
+  const callbackAuthorizationReason = pick(fields.callback_authorization_reason, AUTHORIZATION_REASON_RE);
   return {
     run_id: runId,
     lease_id: validStackLeaseId(fields.lease_id),
@@ -126,6 +129,7 @@ export function buildStackRunOutcomePayload({ fields = {}, exitCode, runId = ran
     repo: pick(opts.repo, REPO_RE),
     duration_ms: Number.isFinite(durationMs) && durationMs >= 0 ? Math.round(durationMs) : null,
     cli_version: pick(VERSION, VERSION_RE) ?? "unknown",
+    ...(callbackAuthorizationReason ? { callback_authorization_reason: callbackAuthorizationReason } : {}),
   };
 }
 

package/src/stack.mjs

@@ -53,7 +53,7 @@ import { checkReadoptedStackMounts } from "./stack-mount-health.mjs";
 import { machineUuid } from "./machine-id.mjs";
 import { DEFAULT_BUNDLE_MAX_BYTES, buildStackBundle, uploadStackBundle, validateBundleIncludePath } from "./stack-bundle.mjs";
 import { assertSshTarget, establishSshTunnel } from "./stack-tunnel.mjs";
-import { NATIVE_CALLBACK_TRANSPORT, openNativeCallbackTransport } from "./stack-native-callback.mjs";
+import { NATIVE_CALLBACK_TRANSPORT, boundedAuthorizationReason, openNativeCallbackTransport } from "./stack-native-callback.mjs";
 import { FORWARD_ATTESTATION_ENV, startForwardAttestation, readForwardAttestation } from "./stack-forward-attestation.mjs";
 import { stackServicesForForwards } from "./stack-service-discovery.mjs";
 import { ENGINE_PUBLISHES_BEYOND_LOOPBACK, engineSocketIsLocal, formatPublishIp, isLoopbackIp, publishIpFix, resolvePublishIp } from "./docker-publish-ip.mjs";
@@ -374,7 +374,11 @@ ${bold("REMOTE LEASES")} (BOT-2142, stack run)
                           CALLBACK_VALIDATION_UNAVAILABLE (Docker unanswered 20 s), CALLBACK_PRODUCER_ENDED,
                           CALLBACK_GENERATION_EXPIRED, CALLBACK_RENEWAL_REFUSED; requester CALLBACK_SSH_LOST,
                           CALLBACK_RELAY_EXITED, CALLBACK_GATEWAY_EXPIRED, CALLBACK_RENEWAL_ACK_TIMEOUT,
-                          CALLBACK_STATUS_UNREADABLE, CALLBACK_PROTOCOL_ERROR, CALLBACK_AUTHORIZATION_LOST
+                          CALLBACK_STATUS_UNREADABLE, CALLBACK_PROTOCOL_ERROR, CALLBACK_AUTHORIZATION_LOST.
+                          A refusal must repeat on one re-read before it stops the child (BOT-2880), and
+                          callback_authorization_reason names the refused check, e.g. requester_host_disabled
+                          (the requester machine's own Docker host was set to disabled: use maintenance),
+                          lease_state:reaping, binding_changed:descriptor.producer_pid
   5 CALLBACK_PORT_BUSY    --callback-port is already listening on the serving host (another run or
                           service), the host refused this run's -R because another run took the
                           port first, or another listener shares the port; this run holds no -R —
@@ -4903,18 +4907,19 @@ async function runStackLifecycleOnce(opts, childArgv, adapters, incidentBox) {
               // that survived the auth refresh or a typed JSON-RPC refusal is a definitive answer.
               // BOT-2847: the shared classification (stack-release-retry.mjs) the cleanup release retries on.
               const transient = observed == null || isTransientStackRpcResult(observed);
-              throw Object.assign(new Error(transient ? "current callback status unreadable" : "current callback authorization refused"), transient ? { transient: true } : { code: "CALLBACK_AUTHORIZATION_LOST" });
+              throw Object.assign(new Error(transient ? "current callback status unreadable" : "current callback authorization refused"), transient ? { transient: true } : { code: "CALLBACK_AUTHORIZATION_LOST", authorizationReason: refusedRpcReason(observed) });
             }
             // BOT-2790 AC-6 (BOT-2828): a backend RPC_ERROR (e.g. a statement timeout) is an unanswered read.
             if (isTransientStackRpcResult(observed)) throw Object.assign(new Error("current callback status unreadable (RPC_ERROR)"), { transient: true });
-            if (observed.data?.success !== true) throw Object.assign(new Error("current callback authorization unavailable"), { code: "CALLBACK_AUTHORIZATION_LOST" });
+            if (observed.data?.success !== true) throw Object.assign(new Error("current callback authorization unavailable"), { code: "CALLBACK_AUTHORIZATION_LOST", authorizationReason: refusedRpcReason(observed) });
             return observed.data; },
           });
           nativeCallback.onExit((exit) => { if (childResult) return; callbackLost = exit; fencing = true; stopChild("SIGTERM", EXIT.LEASE_FAILED); });
           placement.callbackTransport = NATIVE_CALLBACK_TRANSPORT;
         } catch (error) {
           await closeTunnel(); const cleanup = await requestCleanup();
-          return { exitCode: cleanup.ok && !callbackCleanupError && error?.code !== "CALLBACK_CLEANUP_UNCERTAIN" ? EXIT.BACKEND : EXIT.CLEANUP_FAILED, outcome: "error", code: error?.code ?? "CALLBACK_NOT_READY", leaseId, error: String(error?.message ?? "callback transport unavailable"), cleanup };
+          const openReason = boundedAuthorizationReason(error?.authorizationReason);
+          return { exitCode: cleanup.ok && !callbackCleanupError && error?.code !== "CALLBACK_CLEANUP_UNCERTAIN" ? EXIT.BACKEND : EXIT.CLEANUP_FAILED, outcome: "error", code: error?.code ?? "CALLBACK_NOT_READY", leaseId, error: String(error?.message ?? "callback transport unavailable"), cleanup, ...(openReason ? { callbackAuthorizationReason: openReason } : {}) };
         }
       }
       placement.transport = "ssh-forward";
@@ -4999,7 +5004,8 @@ async function runStackLifecycleOnce(opts, childArgv, adapters, incidentBox) {
     if (callbackLost || nativeCallback && !nativeCallback.isLive()) {
       await closeTunnel(); const cleanup = await requestCleanup();
       const callbackCause = callbackLost?.code ?? "CALLBACK_RELAY_EXITED";
-      return { exitCode: cleanup.ok && !callbackCleanupError ? EXIT.LEASE_FAILED : EXIT.CLEANUP_FAILED, outcome: "error", code: "CALLBACK_TRANSPORT_LOST", callbackCause, leaseId, error: `callback transport closed before child start (${callbackCause})`, cleanup };
+      const lostReason = boundedAuthorizationReason(callbackLost?.authorization_reason);
+      return { exitCode: cleanup.ok && !callbackCleanupError ? EXIT.LEASE_FAILED : EXIT.CLEANUP_FAILED, outcome: "error", code: "CALLBACK_TRANSPORT_LOST", callbackCause, ...(lostReason ? { callbackAuthorizationReason: lostReason } : {}), leaseId, error: `callback transport closed before child start (${callbackCause})`, cleanup };
     }
     if (tunnelLost) {
       // The forwards died between being verified and the child starting.
@@ -5065,7 +5071,10 @@ async function runStackLifecycleOnce(opts, childArgv, adapters, incidentBox) {
     if (callbackLost && !receivedSignal) {
       // BOT-2828: the receipt names the hop and cause that closed the route, not only the class.
       const callbackCause = callbackLost.code ?? (callbackLost.reason === "callback_authorization_lost" ? "CALLBACK_AUTHORIZATION_LOST" : "CALLBACK_RELAY_EXITED");
-      return { exitCode: cleanup.ok && !callbackCleanupError ? EXIT.LEASE_FAILED : EXIT.CLEANUP_FAILED, outcome: "failed", code: callbackLost.reason === "callback_authorization_lost" ? "CALLBACK_AUTHORIZATION_LOST" : "CALLBACK_TRANSPORT_LOST", callbackCause, leaseId, childExitCode: childResult.code, cleanup, fenced: true, error: `callback transport authorization or runtime context was lost (${callbackCause}); child stopped` };
+      const authorizationLost = callbackLost.reason === "callback_authorization_lost";
+      // BOT-2880: an authorization loss always names the refused check, even as "unclassified".
+      const callbackAuthorizationReason = authorizationLost ? boundedAuthorizationReason(callbackLost.authorization_reason) ?? "unclassified" : null;
+      return { exitCode: cleanup.ok && !callbackCleanupError ? EXIT.LEASE_FAILED : EXIT.CLEANUP_FAILED, outcome: "failed", code: authorizationLost ? "CALLBACK_AUTHORIZATION_LOST" : "CALLBACK_TRANSPORT_LOST", callbackCause, ...(callbackAuthorizationReason ? { callbackAuthorizationReason } : {}), leaseId, childExitCode: childResult.code, cleanup, fenced: true, error: `callback transport authorization or runtime context was lost (${callbackCause}${callbackAuthorizationReason ? `: ${callbackAuthorizationReason}` : ""}); child stopped` };
     }
     if (tunnelLost && !receivedSignal) {
       return tunnelLostResult(tunnelLost, { leaseId, cleanup, childExitCode: childResult.code, fenced: fencing, ...(parkIncident ? { incident: parkIncident } : {}) });
@@ -5177,6 +5186,8 @@ export function runReceiptFields(result) {
     ...(result.execution?.callbackTransport ? { callback_transport: result.execution.callbackTransport } : {}),
     // BOT-2828: the typed cause of a native callback route close (e.g. CALLBACK_RUNTIME_DRIFT).
     ...(result.callbackCause ? { callback_cause: result.callbackCause } : {}),
+    // BOT-2880: which check refused a CALLBACK_AUTHORIZATION_LOST (a bounded token, never a value).
+    ...(result.callbackAuthorizationReason ? { callback_authorization_reason: result.callbackAuthorizationReason } : {}),
     // BOT-2780: the reserved requester origin generated auth links name (never a credential).
     ...(result.execution?.requesterOrigin ? { requester_origin: result.execution.requesterOrigin } : {}),
     // BOT-2788: "previous" (an idle stack's origin re-reserved), "previous_port_busy" or "new".
@@ -5235,6 +5246,14 @@ export async function cmdRun(opts, childArgv, {
  * receipt deliberately does not carry (which wait a timeout ended and the original
  * lease fence). Never emitted.
  */
+// BOT-2880: a definitive RPC refusal of the callback status read names itself by the backend's
+// typed code or its HTTP status. The shared bound drops anything that is not a plain token.
+function refusedRpcReason(observed) {
+  const code = observed?.data?.code ?? observed?.code;
+  const named = typeof code === "string" && code ? code.toLowerCase() : Number.isInteger(observed?.status) ? `http_${observed.status}` : null;
+  return (named && boundedAuthorizationReason(`refused:${named}`)) ?? "refused";
+}
+
 export function stackRunOutcomeFields(result) {
   return {
     ...runReceiptFields(result), lease_fenced: result?.fenced === true,