@botbuddy/cli 1.63.42 → 1.63.44

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.44",
+  "source_commit": "6fb9ea556869f4b6bb5b1851941dc348009198ff",
+  "source_sha256": "175730f9512d5a1fa81e4800f0be93420e5fd91f1968bba4cd264611b8ae0f82",
   "target": "darwin-arm64",
-  "sha256": "3c5f90061df675f1e06408ce5e1f3c9b6350e5a237216b0dbc11d71d656a1b35"
+  "sha256": "1740585f4d9e5ce03d798353c1c473b6b818191f83d3a6e63b8e94f6e5d975bb"
 }

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.44",
+  "source_commit": "6fb9ea556869f4b6bb5b1851941dc348009198ff",
+  "source_sha256": "175730f9512d5a1fa81e4800f0be93420e5fd91f1968bba4cd264611b8ae0f82",
   "target": "linux-x64",
-  "sha256": "a5a474195eca0a8b57ddf8c5d50cfddb88f083a57bc99e80dc4f1a7d10e99535"
+  "sha256": "93c1837e1aad2e8cb048399e57d2d4504db08d5edda38a92369558ceb4c4e8c4"
 }

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.44",
+  "source_commit": "6fb9ea556869f4b6bb5b1851941dc348009198ff",
+  "source_sha256": "175730f9512d5a1fa81e4800f0be93420e5fd91f1968bba4cd264611b8ae0f82",
   "targets": {
     "darwin-arm64": {
       "goos": "darwin",
       "goarch": "arm64",
       "binary": "daemon/bin/darwin-arm64/botbuddy-daemon",
-      "sha256": "3c5f90061df675f1e06408ce5e1f3c9b6350e5a237216b0dbc11d71d656a1b35",
+      "sha256": "1740585f4d9e5ce03d798353c1c473b6b818191f83d3a6e63b8e94f6e5d975bb",
       "mode": "0755"
     },
     "linux-x64": {
       "goos": "linux",
       "goarch": "amd64",
       "binary": "daemon/bin/linux-x64/botbuddy-daemon",
-      "sha256": "a5a474195eca0a8b57ddf8c5d50cfddb88f083a57bc99e80dc4f1a7d10e99535",
+      "sha256": "93c1837e1aad2e8cb048399e57d2d4504db08d5edda38a92369558ceb4c4e8c4",
       "mode": "0755"
     }
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@botbuddy/cli",
-  "version": "1.63.42",
+  "version": "1.63.44",
   "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

@@ -13,7 +13,10 @@
 // path, hostname, env value, argv or command output can reach the server. The
 // server re-validates the same allowlist (supabase/functions/_shared/lib/stackRunOutcome.ts).
 
+import { spawnSync } from "node:child_process";
 import { randomUUID } from "node:crypto";
+import { lstatSync } from "node:fs";
+import { basename, isAbsolute } from "node:path";
 import { VERSION } from "./version.mjs";
 import { validStackLeaseId } from "./stack-lease-correlation.mjs";
 
@@ -23,7 +26,15 @@ export const STACK_RUN_OUTCOME_TOOL = "record_stack_run_outcome";
 export const STACK_RUN_OUTCOME_TIMEOUT_MS = 2000;
 /** `=off` disables the record (the CLI test suites set it; nothing else should). */
 export const STACK_RUN_OUTCOME_OPT_OUT_ENV = "BOTBUDDY_STACK_RUN_OUTCOME";
-export const STACK_RUN_OUTCOME_CATEGORIES = Object.freeze(["platform", "script", "interrupted", "invocation"]);
+export const STACK_RUN_OUTCOME_CATEGORIES = Object.freeze(["platform", "script", "interrupted", "invocation", "released"]);
+/**
+ * BOT-2881: a signal carries no sender, so a hold's owner says so first. The hold sets this to an
+ * absolute path when it starts `bb stack run`, and its stop command creates that file before
+ * sending SIGTERM. Without it, every signal stays `interrupted`.
+ */
+export const STACK_RELEASE_INTENT_ENV = "BOTBUDDY_STACK_RELEASE_INTENT_FILE";
+export const STACK_SIGNAL_SOURCE_OWNER_RELEASE = "owner_release";
+export const STACK_RELEASE_INTENT_MTIME_SLACK_MS = 2000;
 
 const CODE_RE = /^[A-Za-z0-9_.:-]{1,64}$/;
 const TOKEN_RE = /^[a-z0-9_-]{1,64}$/;
@@ -31,6 +42,8 @@ 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 SIGNAL_RE = /^SIG[A-Z]{1,12}$/;
+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;
@@ -56,12 +69,16 @@ function boundedCode(value) {
  *                 (`--hard-ttl` stop → code HARD_TTL)
  *   platform    — the stack, its transport, the credential or the backend failed
  *   interrupted — a signal ended the run (operator Ctrl-C / parent kill)
+ *   released    — the owner of a hold stopped it on purpose (BOT-2881), and its lease and cleanup held
  *   invocation  — exit 4: bad arguments or a refused request before any lease
  */
 export function classifyStackRunOutcome(fields = {}, exitCode) {
   const code = boundedCode(fields.code);
   const child = Number.isInteger(fields.child_exit_code) ? fields.child_exit_code : null;
   const outcome = typeof fields.outcome === "string" ? fields.outcome : null;
+  // BOT-2881: the owner's stop never hides an unproven teardown (exit 143 would otherwise read as a signal).
+  if (fields.stop_signal?.source === STACK_SIGNAL_SOURCE_OWNER_RELEASE && fields.cleanup === false) return { category: "platform", code: "CLEANUP_FAILED" };
+  if (outcome === "released") return { category: "released", code };
   if (outcome === "interrupted") return { category: "interrupted", code };
   if (code && PLATFORM_CODES.has(code)) return { category: "platform", code };
   // The stdout fence also covers unresolved cleanup. The lifecycle supplies its
@@ -91,6 +108,61 @@ export function classifyStackRunOutcome(fields = {}, exitCode) {
   }
 }
 
+/**
+ * BOT-2881: whether a lifecycle result is an owner's release that held: the signal decided the
+ * exit, not fenced, not a typed platform loss, and cleanup not refused. Anything else keeps its
+ * own outcome and category.
+ */
+export function ownerReleaseHeld(result = {}) {
+  return result.stopSignal?.source === STACK_SIGNAL_SOURCE_OWNER_RELEASE && SIGNAL_EXITS.has(result.exitCode)
+    // Any typed code (a platform loss, CALLBACK_CLEANUP_UNCERTAIN, …) keeps the run's own outcome.
+    && result.fenced !== true && result.cleanup?.ok !== false && result.code == null;
+}
+
+/** BOT-2881: the declared intent exists, is a regular file and was written after this run began. */
+export function stackReleaseIntentDeclared({ env = process.env, startedAtMs } = {}) {
+  const file = env?.[STACK_RELEASE_INTENT_ENV];
+  if (typeof file !== "string" || !isAbsolute(file) || !Number.isFinite(startedAtMs)) return false;
+  try {
+    const entry = lstatSync(file);
+    // A filesystem clock may trail Date.now() by a few ms (coarse Linux mtimes); an earlier run's
+    // file is minutes or hours old, so a small slack never admits it.
+    return entry.isFile() && entry.mtimeMs >= startedAtMs - STACK_RELEASE_INTENT_MTIME_SLACK_MS;
+  } catch {
+    return false;
+  }
+}
+
+/** BOT-2881: the parent's process name as a bounded token, or null. A name only: never its argv. */
+export function readParentProcessName(ppid, { run = spawnSync } = {}) {
+  if (!Number.isInteger(ppid) || ppid <= 1) return null;
+  try {
+    const ps = run("ps", ["-o", "comm=", "-p", String(ppid)], { encoding: "utf8", timeout: 300 });
+    if (ps?.status !== 0 || typeof ps.stdout !== "string") return null;
+    const name = basename(ps.stdout.trim()).replace(/^-/, "").toLowerCase();
+    return TOKEN_RE.test(name) ? name : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * BOT-2881: what this process can know about the signal that is ending it. Node exposes no sender,
+ * so `source` is one of: the owner's declared release, a terminal (SIGINT/SIGHUP with a TTY), a
+ * parent that had already gone, or unknown, with the parent that could have sent it named.
+ * `lossFirst`: the lease or its transport was already lost, so this stop did not end the run.
+ */
+export function observeStackRunSignal(signal, {
+  env = process.env, startedAtMs, startPpid = null, ppid = process.ppid, stdinIsTty = process.stdin?.isTTY === true,
+  lossFirst = false, intentDeclared = stackReleaseIntentDeclared, parentName = readParentProcessName,
+} = {}) {
+  if (signal === "SIGTERM" && !lossFirst && intentDeclared({ env, startedAtMs })) {
+    return { signal, source: STACK_SIGNAL_SOURCE_OWNER_RELEASE, parent: null };
+  }
+  if (startPpid != null && ppid !== startPpid) return { signal, source: "parent_exited", parent: null };
+  return { signal, source: stdinIsTty && signal !== "SIGTERM" ? "terminal" : "unknown", parent: parentName(ppid) };
+}
+
 /** The lane id from `$BOTBUDDY_LANE_SOURCE_RUN_ID` (`lefthook:<invocation>:<lane>`), or null. */
 export function laneFromSourceRunId(value) {
   if (typeof value !== "string" || !value.startsWith("lefthook:")) return null;
@@ -109,6 +181,10 @@ 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-2881: present only when a signal ended the run, so an unsignalled run's payload is unchanged.
+  const signal = pick(fields.stop_signal?.signal, SIGNAL_RE);
+  // 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 +202,12 @@ 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",
+    ...(signal ? {
+      signal,
+      signal_source: pick(fields.stop_signal.source, TOKEN_RE),
+      signal_parent: pick(fields.stop_signal.parent, TOKEN_RE),
+    } : {}),
+    ...(callbackAuthorizationReason ? { callback_authorization_reason: callbackAuthorizationReason } : {}),
   };
 }
 

package/src/stack.mjs

@@ -53,12 +53,12 @@ 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";
 import { bold, dim, yellow } from "./utils.mjs";
-import { reportStackRunOutcome } from "./stack-run-outcome.mjs";
+import { STACK_RELEASE_INTENT_ENV, observeStackRunSignal, ownerReleaseHeld, reportStackRunOutcome } from "./stack-run-outcome.mjs";
 
 export const STACK_SCHEMA_VERSION = 1;
 
@@ -253,6 +253,9 @@ ${bold("run OPTIONS")}
                          goes IDLE (no reap wait; receipt cleanup {idle, idle_since}) and the stack
                          directory + port block stay reserved (24 h, renewed on re-adoption).
                          Interrupts, --hard-ttl, a fenced heartbeat or a lost tunnel always reap.
+                         A hold that outlives its starter sets ${STACK_RELEASE_INTENT_ENV}
+                         to an absolute path and creates that file just before its stop sends SIGTERM:
+                         the run is then recorded as released, not interrupted (BOT-2881).
   --connection-file P    Optional empty file path for the mode-0600 connection JSON.
   --hard-ttl N           Bound the child runtime; timeout requests normal cleanup.
   --local-exec           Rejected: stack run never starts Docker directly.
@@ -374,7 +377,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 —
@@ -3748,7 +3755,8 @@ export async function runStackLifecycle(opts, childArgv, adapters = {}) {
   const withExecution = incidentBox.execution && !withIncident?.execution ? { ...withIncident, execution: incidentBox.execution } : withIncident;
   const withIdle = incidentBox.idleLease && !withExecution?.idleLease ? { ...withExecution, idleLease: incidentBox.idleLease } : withExecution;
   const withPortBlock = incidentBox.portBlock && !withIdle?.portBlock ? { ...withIdle, portBlock: incidentBox.portBlock } : withIdle;
-  const final = incidentBox.webUrl && withPortBlock && !withPortBlock.webUrl ? { ...withPortBlock, webUrl: incidentBox.webUrl } : withPortBlock;
+  const withWebUrl = incidentBox.webUrl && withPortBlock && !withPortBlock.webUrl ? { ...withPortBlock, webUrl: incidentBox.webUrl } : withPortBlock;
+  const final = incidentBox.stopSignal && withWebUrl ? { ...withWebUrl, stopSignal: incidentBox.stopSignal } : withWebUrl;
   // BOT-2467: non-enumerable, so the receipt fields and result comparisons never see it.
   if (final && typeof final === "object" && incidentBox.outcomeChannel) {
     Object.defineProperty(final, OUTCOME_CHANNEL, { value: incidentBox.outcomeChannel, enumerable: false });
@@ -3871,6 +3879,10 @@ async function runStackLifecycleOnce(opts, childArgv, adapters, incidentBox) {
   let execution = null;
   let leaseProvisioned = false;
   let receivedSignal = null;
+  // BOT-2881: an intent counts only when written after this run began; a parent change is an orphan.
+  const observeSignal = adapters.observeSignal ?? observeStackRunSignal;
+  const runStartedAtMs = Date.now();
+  const startPpid = process.ppid;
   let forcedStopCode = null;
   let fencing = false;
   let activeWaitAbort = null;
@@ -4076,6 +4088,11 @@ async function runStackLifecycleOnce(opts, childArgv, adapters, incidentBox) {
   const onSignal = (signal) => {
     if (receivedSignal) return;
     receivedSignal = signal;
+    try {
+      incidentBox.stopSignal = observeSignal(signal, { startedAtMs: runStartedAtMs, startPpid, lossFirst: fencing || forcedStopCode != null });
+    } catch {
+      incidentBox.stopSignal = { signal, source: "unknown", parent: null };
+    }
     activeWaitAbort?.abort("interrupted");
     stopChild(signal);
     // If capacity is still queued/provisioning there is no child to hold open;
@@ -4903,18 +4920,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 +5017,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 +5084,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 } : {}) });
@@ -5142,7 +5164,9 @@ export function runReceiptFields(result) {
   return {
     // 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,
+    command: "run", outcome: ownerReleaseHeld(result) ? "released" : result.outcome, code: result.code ?? null, lease_id: result.leaseId ?? null,
+    // BOT-2881: the signal that ended this run and what is known of its source (never on a run no signal touched).
+    ...(result.stopSignal ? { stop_signal: result.stopSignal } : {}),
     ...(result.state ? { state: result.state } : {}),
     // BOT-2468: the lease's /docker?lease= deeplink (null when the server sent none).
     web_url: result.webUrl ?? null,
@@ -5177,6 +5201,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 +5261,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,