@botbuddy/cli 1.64.29 → 1.64.31

package/daemon-release/darwin-arm64.json

@@ -1,7 +1,7 @@
 {
-  "release_version": "1.64.29",
-  "source_commit": "03ff10bbdbf29436bb0775b0342dd6ae558ba2a0",
-  "source_sha256": "5ba023d785ba672d4e912b4c1fdb61ab0d9ccc76356d3372ac42590064516fc2",
+  "release_version": "1.64.31",
+  "source_commit": "1d612675c4e0b580098e3abe63a8bc59cd581c2c",
+  "source_sha256": "87837ab1232c23b40ebcaa4e844c9314f811d63471550b866ca66c6aff23febe",
   "target": "darwin-arm64",
-  "sha256": "3817107c1e0ad8ccd208d010482435b382db9ac16da9b5f4de7641e4d7dd8d71"
+  "sha256": "fc73087ccd6f503e12dbc011ea74520bc92fc7442009b0674621be1ef3bc7ecd"
 }

package/daemon-release/linux-x64.json

@@ -1,7 +1,7 @@
 {
-  "release_version": "1.64.29",
-  "source_commit": "03ff10bbdbf29436bb0775b0342dd6ae558ba2a0",
-  "source_sha256": "5ba023d785ba672d4e912b4c1fdb61ab0d9ccc76356d3372ac42590064516fc2",
+  "release_version": "1.64.31",
+  "source_commit": "1d612675c4e0b580098e3abe63a8bc59cd581c2c",
+  "source_sha256": "87837ab1232c23b40ebcaa4e844c9314f811d63471550b866ca66c6aff23febe",
   "target": "linux-x64",
-  "sha256": "06465a1240a4bd24033a873be038436dd059078a14009496158f6b1f32e89507"
+  "sha256": "85804a8e6e1cbff0433407337c65954b7feb7e06660a5e4722f94e5f08f57aa5"
 }

package/daemon-release/manifest.json

@@ -1,21 +1,21 @@
 {
   "schema_version": 1,
-  "release_version": "1.64.29",
-  "source_commit": "03ff10bbdbf29436bb0775b0342dd6ae558ba2a0",
-  "source_sha256": "5ba023d785ba672d4e912b4c1fdb61ab0d9ccc76356d3372ac42590064516fc2",
+  "release_version": "1.64.31",
+  "source_commit": "1d612675c4e0b580098e3abe63a8bc59cd581c2c",
+  "source_sha256": "87837ab1232c23b40ebcaa4e844c9314f811d63471550b866ca66c6aff23febe",
   "targets": {
     "darwin-arm64": {
       "goos": "darwin",
       "goarch": "arm64",
       "binary": "daemon/bin/darwin-arm64/botbuddy-daemon",
-      "sha256": "3817107c1e0ad8ccd208d010482435b382db9ac16da9b5f4de7641e4d7dd8d71",
+      "sha256": "fc73087ccd6f503e12dbc011ea74520bc92fc7442009b0674621be1ef3bc7ecd",
       "mode": "0755"
     },
     "linux-x64": {
       "goos": "linux",
       "goarch": "amd64",
       "binary": "daemon/bin/linux-x64/botbuddy-daemon",
-      "sha256": "06465a1240a4bd24033a873be038436dd059078a14009496158f6b1f32e89507",
+      "sha256": "85804a8e6e1cbff0433407337c65954b7feb7e06660a5e4722f94e5f08f57aa5",
       "mode": "0755"
     }
   }

package/package.json

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

package/src/requester-network.mjs

@@ -0,0 +1,298 @@
+// BOT-3109 — did THIS machine lose its own network while a `bb stack run` failed?
+//
+// A requester-side drop (a cable pulled, Wi-Fi handing over, sleep) ends a remote run
+// with TUNNEL_LOST, CALLBACK_TRANSPORT_LOST or LEASE_HEARTBEAT_UNANSWERED, exactly like
+// a BotBuddy or stack-host outage. This module tells them apart from the requester's own
+// side, and only when it can prove it:
+//
+//   - a small sampler reads the primary route every SAMPLE_MS while the run lives
+//     (macOS: `route -n get default` + `ipconfig getifaddr`; Linux: `ip -4 route show default`),
+//     and when the primary moves, whether the old interface lost its address;
+//   - at a candidate failure, `classify()` reads once more and, on macOS, reads configd's own
+//     record of interface detaches in the window before the failure.
+//
+// The answer is `changed` (with evidence), `unchanged` or `undecided`. Only `changed`
+// changes what a run reports; the caller keeps today's code for the other two, so an
+// unsupported OS, a missing tool or a probe error never guesses `requester`.
+
+import { execFile } from "node:child_process";
+
+export const REQUESTER_NETWORK_LOST_CODE = "REQUESTER_NETWORK_LOST";
+/** The terminal codes a requester's own network loss can produce (BOT-3109). */
+export const REQUESTER_NETWORK_CANDIDATE_CODES = Object.freeze(["TUNNEL_LOST", "CALLBACK_TRANSPORT_LOST", "LEASE_HEARTBEAT_UNANSWERED"]);
+/** `=off` disables the probe (the CLI test suites set it; nothing else should). */
+export const REQUESTER_NETWORK_PROBE_ENV = "BOTBUDDY_REQUESTER_NETWORK_PROBE";
+export const REQUESTER_NETWORK_SAMPLE_MS = 15_000;
+/** The control-plane deadlines are 180 s, so a loss that ended a run began at most this long before. */
+export const REQUESTER_NETWORK_LOOKBACK_MS = 300_000;
+/** Evidence just after the failure still counts (the sampler may see the outage a beat late). */
+export const REQUESTER_NETWORK_FAILURE_SLACK_MS = 20_000;
+const PROBE_TIMEOUT_MS = 3000;
+const LOG_TIMEOUT_MS = 6000;
+const MAX_SAMPLES = 64;
+
+const IFACE_RE = /^[A-Za-z0-9_.:@-]{1,32}$/;
+
+// Every probe child in flight; `stop()` aborts them so a finished run never waits on a probe.
+const inFlight = new Set();
+
+/** The probe runner (exported for its abort test). */
+export function execText(file, args, timeout) {
+  return new Promise((resolve) => {
+    const ac = new AbortController();
+    inFlight.add(ac);
+    try {
+      execFile(file, args, { encoding: "utf8", timeout, maxBuffer: 1 << 20, signal: ac.signal }, (error, stdout, stderr) => {
+        inFlight.delete(ac);
+        resolve({
+          status: error ? (typeof error.code === "number" ? error.code : -1) : 0,
+          stdout: typeof stdout === "string" ? stdout : "", stderr: typeof stderr === "string" ? stderr : "", missing: error?.code === "ENOENT",
+        });
+      });
+    } catch {
+      inFlight.delete(ac);
+      resolve({ status: -1, stdout: "", missing: true });
+    }
+  });
+}
+
+/** Abort every probe child still running (an aborted read is unreadable, never a loss). */
+export function abortRequesterNetworkProbes() {
+  for (const ac of inFlight) ac.abort();
+  inFlight.clear();
+}
+
+const iface = (value) => (typeof value === "string" && IFACE_RE.test(value) ? value : null);
+
+/** `route -n get default` → the primary interface, or null when there is no default route. */
+export function parseMacosDefaultRoute(stdout) {
+  return iface(/^\s*interface:\s*(\S+)\s*$/m.exec(stdout ?? "")?.[1]);
+}
+
+/** `ip -4 route show default` → { interface, gateway } of the first default route, or null. */
+export function parseLinuxDefaultRoute(stdout) {
+  const line = String(stdout ?? "").split("\n").find((l) => /^default\b/.test(l.trim()));
+  if (!line) return null;
+  const dev = iface(/\bdev\s+(\S+)/.exec(line)?.[1]);
+  if (!dev) return null;
+  return { interface: dev, gateway: /\bvia\s+(\S+)/.exec(line)?.[1] ?? null };
+}
+
+/**
+ * One reading of this machine's primary network identity. `{ ok: false }` when it cannot be
+ * read (unsupported OS, missing tool, timeout); `{ ok: true, interface: null }` when there is
+ * provably no primary route — which is itself the loss.
+ */
+export async function readPrimaryNetwork({ platform = process.platform, run = execText } = {}) {
+  try {
+    if (platform === "darwin") {
+      const route = await run("/sbin/route", ["-n", "get", "default"], PROBE_TIMEOUT_MS);
+      if (route.missing) return { ok: false };
+      const primary = parseMacosDefaultRoute(route.stdout);
+      // route prints "not in table" (and exits non-zero) when there is no default route; anything else is unreadable.
+      if (!primary) return /not in table/i.test(`${route.stdout}\n${route.stderr ?? ""}`) ? { ok: true, interface: null, address: null } : { ok: false };
+      const addr = await run("/usr/sbin/ipconfig", ["getifaddr", primary], PROBE_TIMEOUT_MS);
+      if (addr.missing) return { ok: false };
+      const address = /^\d{1,3}(\.\d{1,3}){3}$/.test(addr.stdout.trim()) ? addr.stdout.trim() : null;
+      return { ok: true, interface: primary, address };
+    }
+    if (platform === "linux") {
+      const route = await run("ip", ["-4", "route", "show", "default"], PROBE_TIMEOUT_MS);
+      if (route.missing || route.status !== 0) return { ok: false };
+      const parsed = parseLinuxDefaultRoute(route.stdout);
+      return parsed ? { ok: true, interface: parsed.interface, address: parsed.gateway } : { ok: true, interface: null, address: null };
+    }
+  } catch { /* an unreadable probe is undecided, never a loss */ }
+  return { ok: false };
+}
+
+/**
+ * Whether `name` still has an IPv4 address right now. `{ ok: true, address: null }` is proof it
+ * lost it (macOS `ipconfig getifaddr` exits 1 with no output for an interface without one, or
+ * one that detached; Linux `ip -4 -o addr show dev` prints nothing). Anything else is unreadable.
+ */
+export async function readInterfaceAddress(name, { platform = process.platform, run = execText } = {}) {
+  if (!iface(name)) return { ok: false };
+  try {
+    if (platform === "darwin") {
+      const out = await run("/usr/sbin/ipconfig", ["getifaddr", name], PROBE_TIMEOUT_MS);
+      if (out.missing) return { ok: false };
+      const text = out.stdout.trim();
+      if (out.status === 0 && /^\d{1,3}(\.\d{1,3}){3}$/.test(text)) return { ok: true, address: text };
+      return out.status === 1 && text === "" ? { ok: true, address: null } : { ok: false };
+    }
+    if (platform === "linux") {
+      const out = await run("ip", ["-4", "-o", "addr", "show", "dev", name], PROBE_TIMEOUT_MS);
+      if (out.missing) return { ok: false };
+      // A detached device is an error ("does not exist"): it has no address either.
+      if (out.status !== 0) return /does not exist/i.test(out.stderr ?? "") ? { ok: true, address: null } : { ok: false };
+      const inet = /\binet\s+(\d{1,3}(?:\.\d{1,3}){3})/.exec(out.stdout)?.[1] ?? null;
+      return { ok: true, address: inet };
+    }
+  } catch { /* unreadable */ }
+  return { ok: false };
+}
+
+/** Parse configd's timestamp ("2026-11-09 09:19:32.634512+0200"), which carries its own offset. */
+function parseLogTimestamp(value) {
+  const m = /^(\d{4}-\d{2}-\d{2})[ T](\d{2}:\d{2}:\d{2})(\.\d{1,3})?\d*([+-]\d{2}):?(\d{2})$/.exec(String(value ?? "").trim());
+  if (!m) return NaN;
+  return Date.parse(`${m[1]}T${m[2]}${m[3] ?? ""}${m[4]}:${m[5]}`);
+}
+
+/**
+ * configd's `log show --style ndjson` lines → interface-detach events. Only a detach is evidence:
+ * a "network changed" line also fires when an interface is merely added (docking while Wi-Fi
+ * stays up), so it never counts on its own. A line without a zoned timestamp is skipped.
+ */
+export function parseConfigdLog(stdout) {
+  const events = [];
+  for (const line of String(stdout ?? "").split("\n")) {
+    if (!line.startsWith("{")) continue;
+    let entry;
+    try { entry = JSON.parse(line); } catch { continue; }
+    const atMs = parseLogTimestamp(entry?.timestamp);
+    if (!Number.isFinite(atMs)) continue;
+    const detached = /Process interface detaching:\s*(\S+)/.exec(String(entry?.eventMessage ?? ""));
+    if (detached && iface(detached[1])) events.push({ atMs, kind: "interface_detached", interface: detached[1] });
+  }
+  return events;
+}
+
+/** macOS only: configd's interface detaches in `[sinceMs, untilMs]`. `{ ok: false }` when unreadable. */
+export async function readConfigdNetworkEvents({ sinceMs, untilMs = Infinity, nowMs = Date.now(), run = execText } = {}) {
+  const secs = Math.max(1, Math.ceil((nowMs - sinceMs) / 1000) + 5);
+  try {
+    const out = await run("/usr/bin/log", ["show", "--style", "ndjson", "--last", `${secs}s`, "--predicate",
+      'process == "configd" AND eventMessage CONTAINS "interface detaching"'], LOG_TIMEOUT_MS);
+    if (out.missing || out.status !== 0) return { ok: false };
+    return { ok: true, events: parseConfigdLog(out.stdout).filter((e) => e.atMs >= sinceMs && e.atMs <= untilMs) };
+  } catch {
+    return { ok: false };
+  }
+}
+
+/**
+ * Pure decision over the samples (oldest first, each `{ atMs, ok, interface, address,
+ * previousLost }`), a fresh reading and, on macOS, configd's detaches. Evidence counts only inside
+ * `[sinceMs, untilMs]` (the lookback before the failure, and a short slack after it).
+ *
+ * Proof of a local loss is one of: the primary route disappeared after a sample had one; the
+ * primary moved to another interface AND the old one had lost its address when that was seen;
+ * the primary interface kept its name but its address changed; configd saw a primary interface
+ * detach. A primary that moved while the old one kept its address (docking, a VPN) is not proof:
+ * that run is undecided, so today's code stands.
+ */
+export function decideRequesterNetwork({ samples = [], current, log = null, sinceMs, untilMs = Infinity, platform }) {
+  const readable = samples.filter((s) => s.ok);
+  // The reference: the newest readable sample taken before the window opened, else the oldest in it.
+  const before = readable.filter((s) => s.atMs < sinceMs);
+  const reference = before.length ? before[before.length - 1] : readable.find((s) => s.atMs <= untilMs) ?? null;
+  // A machine that never had an IPv4 primary route (IPv6-only, a policy-routed Linux host) gives
+  // the probe nothing to compare: never a loss.
+  if (!reference?.interface) return { decision: "undecided" };
+  const inWindow = (s) => s.atMs >= sinceMs && s.atMs <= untilMs;
+  const chain = [...readable.filter((s) => s !== reference && inWindow(s)), ...(current?.ok && inWindow(current) ? [current] : [])];
+  const primaries = new Set([reference.interface]);
+  let previous = reference;
+  let ambiguous = false;
+  for (const sample of chain) {
+    if (sample.interface == null) {
+      if (previous.interface != null) return { decision: "changed", atMs: sample.atMs, evidence: "no_primary_interface", before: previous.interface, after: null };
+    } else if (previous.interface == null) {
+      // Back from no route: the loss was already counted above.
+    } else if (sample.interface !== previous.interface) {
+      if (sample.previousLost === true) return { decision: "changed", atMs: sample.atMs, evidence: "primary_interface_changed", before: previous.interface, after: sample.interface };
+      ambiguous = true;
+    } else if ((sample.address ?? null) !== (previous.address ?? null) && previous.address != null && sample.address != null) {
+      return { decision: "changed", atMs: sample.atMs, evidence: "primary_address_changed", before: previous.interface, after: sample.interface };
+    }
+    if (sample.interface) primaries.add(sample.interface);
+    previous = sample;
+  }
+  if (log?.ok) {
+    const detach = log.events.find((e) => e.kind === "interface_detached" && primaries.has(e.interface) && e.atMs >= sinceMs && e.atMs <= untilMs);
+    if (detach) return { decision: "changed", atMs: detach.atMs, evidence: "interface_detached", before: detach.interface, after: current?.interface ?? null };
+  }
+  // "unchanged" needs a fresh readable answer, no ambiguous move and (on macOS) a readable log.
+  const logRead = platform !== "darwin" || log?.ok === true;
+  return !ambiguous && current?.ok && logRead ? { decision: "unchanged" } : { decision: "undecided" };
+}
+
+/**
+ * A watch over one run. `start()` takes the first sample and samples every `sampleMs`;
+ * `classify({ failedAtMs })` decides over the lookback window before the failure; `stop()` ends
+ * sampling. Never throws.
+ */
+export function createRequesterNetworkWatch({
+  platform = process.platform, env = process.env, now = Date.now, read: readNetwork = readPrimaryNetwork, readAddress: readOldAddress = readInterfaceAddress,
+  readLog = readConfigdNetworkEvents, sampleMs = REQUESTER_NETWORK_SAMPLE_MS, lookbackMs = REQUESTER_NETWORK_LOOKBACK_MS,
+} = {}) {
+  const disabled = env?.[REQUESTER_NETWORK_PROBE_ENV] === "off" || (platform !== "darwin" && platform !== "linux");
+  const samples = [];
+  let timer = null;
+  let startedAtMs = null;
+  let stopped = false;
+  // After stop() no probe child starts, so nothing outlives the run.
+  const read = (opts) => (stopped ? Promise.resolve({ ok: false }) : readNetwork(opts));
+  const readAddress = (name, opts) => (stopped ? Promise.resolve({ ok: false }) : readOldAddress(name, opts));
+  const take = async () => {
+    const atMs = now();
+    let reading;
+    try { reading = await read({ platform }); } catch { reading = { ok: false }; }
+    const sample = { atMs, ok: reading?.ok === true, interface: reading?.interface ?? null, address: reading?.address ?? null, previousLost: null };
+    const last = [...samples].reverse().find((s) => s.ok);
+    // The primary moved: did the old one lose its address (a loss) or is it still up (docking, a VPN)?
+    if (sample.ok && sample.interface && last?.interface && last.interface !== sample.interface) {
+      try {
+        const old = await readAddress(last.interface, { platform });
+        sample.previousLost = old?.ok === true ? old.address == null : null;
+      } catch { sample.previousLost = null; }
+    }
+    samples.push(sample);
+    if (samples.length > MAX_SAMPLES) samples.shift();
+    return sample;
+  };
+  return {
+    disabled,
+    start() {
+      if (disabled || startedAtMs != null) return;
+      startedAtMs = now();
+      take().catch(() => {});
+      timer = setInterval(() => { take().catch(() => {}); }, sampleMs);
+      timer.unref?.();
+    },
+    stop() {
+      stopped = true;
+      if (timer) clearInterval(timer);
+      timer = null;
+      if (!disabled) abortRequesterNetworkProbes();
+    },
+    async classify({ failedAtMs } = {}) {
+      if (disabled || startedAtMs == null) return { decision: "undecided" };
+      try {
+        const nowMs = now();
+        // The failure, not this call (cleanup can take minutes): a change after it is not its cause.
+        const failAt = Number.isFinite(failedAtMs) ? Math.min(failedAtMs, nowMs) : nowMs;
+        const sinceMs = Math.max(startedAtMs, failAt - lookbackMs);
+        const untilMs = failAt + REQUESTER_NETWORK_FAILURE_SLACK_MS;
+        const history = samples.slice();
+        const current = await take();
+        const log = platform === "darwin" ? await readLog({ sinceMs, untilMs, nowMs }) : null;
+        return decideRequesterNetwork({ samples: history, current, log, sinceMs, untilMs, platform });
+      } catch {
+        return { decision: "undecided" };
+      }
+    },
+  };
+}
+
+/** The one stderr line a requester-side loss prints (BOT-3109). */
+export function requesterNetworkLostMessage(network, underlyingCode) {
+  const at = Number.isFinite(network?.atMs) ? new Date(network.atMs).toISOString() : "an unknown time";
+  const how = network?.evidence === "no_primary_interface" ? "had no network route"
+    : network?.evidence === "interface_detached" ? `lost its network interface${network.before ? ` ${network.before}` : ""}`
+      : `changed its primary network${network?.before && network?.after ? ` (${network.before} → ${network.after})` : ""}`;
+  return `stack: this machine ${how} at ${at}, so the run ended (${underlyingCode}). BotBuddy and the stack host were not at fault. ` +
+    "Check this machine's connection, then re-run the same command.";
+}

package/src/stack-run-outcome.mjs

@@ -26,7 +26,10 @@ 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", "released"]);
+export const STACK_RUN_OUTCOME_CATEGORIES = Object.freeze(["platform", "script", "interrupted", "invocation", "released", "requester"]);
+/** BOT-3109: the only code the `requester` category carries, and the codes it can replace. */
+export const REQUESTER_CATEGORY_CODE = "REQUESTER_NETWORK_LOST";
+const REQUESTER_UNDERLYING_CODES = new Set(["TUNNEL_LOST", "CALLBACK_TRANSPORT_LOST", "LEASE_HEARTBEAT_UNANSWERED"]);
 /**
  * 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
@@ -71,6 +74,7 @@ function boundedCode(value) {
  *   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
+ *   requester   — this machine's own network dropped while the run lost its transport (BOT-3109)
  */
 export function classifyStackRunOutcome(fields = {}, exitCode) {
   const code = boundedCode(fields.code);
@@ -80,6 +84,8 @@ export function classifyStackRunOutcome(fields = {}, exitCode) {
   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 };
+  // BOT-3109: set only when the requester network probe proved a local change (never a guess).
+  if (code === REQUESTER_CATEGORY_CODE) return { category: "requester", code };
   if (code && PLATFORM_CODES.has(code)) return { category: "platform", code };
   // The stdout fence also covers unresolved cleanup. The lifecycle supplies its
   // original lease-fence fact separately so coincident child exits cannot hide it.
@@ -188,6 +194,10 @@ 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;
+  // BOT-3109: the code a requester network loss replaced; sent only on such a run.
+  const underlyingCode = category === "requester" && REQUESTER_UNDERLYING_CODES.has(fields.underlying_code) ? fields.underlying_code : null;
   return {
     run_id: runId,
     lease_id: validStackLeaseId(fields.lease_id),
@@ -212,6 +222,8 @@ export function buildStackRunOutcomePayload({ fields = {}, exitCode, runId = ran
     } : {}),
     ...(callbackAuthorizationReason ? { callback_authorization_reason: callbackAuthorizationReason } : {}),
     ...(failureMechanism ? { failure_mechanism: failureMechanism } : {}),
+    ...(fenceScope ? { fence_scope: fenceScope } : {}),
+    ...(underlyingCode ? { underlying_code: underlyingCode } : {}),
   };
 }
 
@@ -244,13 +256,21 @@ 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 });
       }
+      // BOT-3109: a server from before the requester category refuses it (or its underlying_code).
+      // Record exactly what that server would have got from an older CLI: the platform code.
+      const refusedRequester = payload.category === "requester" && payload.underlying_code && typeof first?.data?.message === "string" &&
+        (first.data.message.startsWith("unknown key 'underlying_code'") || first.data.message.startsWith("category must be"));
+      if (!ac.signal.aborted && refusedRequester && first?.ok && first?.isError && first?.data?.code === "INVALID_STACK_RUN_OUTCOME") {
+        const { underlying_code: underlying, ...rest } = payload;
+        return await channel.callTool(STACK_RUN_OUTCOME_TOOL, { ...rest, category: "platform", code: underlying }, { auth: channel.auth, signal: ac.signal });
+      }
       return first;
     });
     const result = await Promise.race([call.catch(() => null), timeout]);

package/src/stack.mjs

@@ -60,6 +60,7 @@ 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 { STACK_RELEASE_INTENT_ENV, classifyStackRunOutcome, observeStackRunSignal, ownerReleaseHeld, reportStackRunOutcome } from "./stack-run-outcome.mjs";
+import { REQUESTER_NETWORK_CANDIDATE_CODES, REQUESTER_NETWORK_LOST_CODE, createRequesterNetworkWatch, requesterNetworkLostMessage } from "./requester-network.mjs";
 
 export const STACK_SCHEMA_VERSION = 1;
 
@@ -416,6 +417,11 @@ ${bold("REMOTE LEASES")} (BOT-2142, stack run)
                           (BUNDLE_UNSAFE_LINK: it resolves outside the stack); no lease is created
   6 TUNNEL_LOST           the forward exited mid-child: the child is stopped, the lease released,
                           park_reason tunnel_lost (its failures were transport, not product)
+  6 REQUESTER_NETWORK_LOST  one of TUNNEL_LOST, CALLBACK_TRANSPORT_LOST or LEASE_HEARTBEAT_UNANSWERED,
+                          while THIS machine's own network changed (macOS: primary interface or IPv4,
+                          or configd saw it detach; Linux: default route). underlying_code keeps the
+                          original code, requester_network {lost_at, evidence} says when; recorded as
+                          category requester, not platform (BOT-3109). Undecided → the original code.
   Every remote failure after the lease exists still runs \`stack done\` and closes the forwards.
 
 ${bold("HOST_CAPACITY_SOURCE_STALE")} (BOT-2024)
@@ -1488,13 +1494,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 +2696,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 +2838,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;
@@ -3907,8 +3957,23 @@ export async function runStackLifecycle(opts, childArgv, adapters = {}) {
   // no claim exists, which is a safe, explicit disposition rather than omission.
   // BOT-1803: whether this run re-adopted / re-provisioned an idle lease, and its stack digest.
   const freshBox = () => ({ incident: null, execution: null, idleLease: null, webUrl: null, portBlock: { released: false, reason: "no port-block claim was created before stack allocation" } });
-  let incidentBox = freshBox();
+  const incidentBox = freshBox();
   const startedAtMs = (adapters.now ?? Date.now)();
+  // BOT-3109: watch this machine's own primary network for the run's life (null disables).
+  let networkWatch = null;
+  try {
+    networkWatch = adapters.requesterNetwork === undefined ? createRequesterNetworkWatch() : adapters.requesterNetwork;
+    networkWatch?.start?.();
+  } catch { networkWatch = null; }
+  try {
+    return await runStackLifecycleWatched(opts, childArgv, adapters, incidentBox, freshBox, startedAtMs, networkWatch);
+  } finally {
+    try { networkWatch?.stop?.(); } catch { /* a probe never changes the run */ }
+  }
+}
+
+async function runStackLifecycleWatched(opts, childArgv, adapters, firstBox, freshBox, startedAtMs, networkWatch) {
+  let incidentBox = firstBox;
   const once = async (attemptOpts = opts) => {
     try {
       return await runStackLifecycleOnce(attemptOpts, childArgv, adapters, incidentBox);
@@ -3940,7 +4005,8 @@ export async function runStackLifecycle(opts, childArgv, adapters = {}) {
   const withPortBlock = incidentBox.portBlock && !withIdle?.portBlock ? { ...withIdle, portBlock: incidentBox.portBlock } : withIdle;
   const withWebUrl = incidentBox.webUrl && withPortBlock && !withPortBlock.webUrl ? { ...withPortBlock, webUrl: incidentBox.webUrl } : withPortBlock;
   const withStopSignal = incidentBox.stopSignal && withWebUrl ? { ...withWebUrl, stopSignal: incidentBox.stopSignal } : withWebUrl;
-  const final = incidentBox.callbackOutage && withStopSignal ? { ...withStopSignal, callbackOutage: incidentBox.callbackOutage } : withStopSignal;
+  const withOutage = incidentBox.callbackOutage && withStopSignal ? { ...withStopSignal, callbackOutage: incidentBox.callbackOutage } : withStopSignal;
+  const final = await applyRequesterNetworkLoss(withOutage, networkWatch, { failedAtMs: incidentBox.lossAtMs });
   // 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 });
@@ -3948,6 +4014,36 @@ export async function runStackLifecycle(opts, childArgv, adapters = {}) {
   return final;
 }
 
+/**
+ * BOT-3109: a run that ended on a transport or control-plane loss while THIS machine's own
+ * network changed is the requester's loss, not BotBuddy's: code REQUESTER_NETWORK_LOST (category
+ * `requester`), the original code kept as `underlyingCode`, and one plain stderr line. Anything
+ * short of a proven change (no change, an undecided or throwing probe, no probe) returns the
+ * result object untouched, so its receipt is byte-identical to before.
+ */
+export async function applyRequesterNetworkLoss(result, watch, { failedAtMs = null, stderrLine = (line) => process.stderr.write(`${line}\n`) } = {}) {
+  if (!result || typeof result !== "object" || !REQUESTER_NETWORK_CANDIDATE_CODES.includes(result.code) || typeof watch?.classify !== "function") return result;
+  // An unproven teardown (a lease that may be leaked) is never relabelled: it stays the platform failure it is today.
+  // CALLBACK_CLEANUP_UNCERTAIN exits CLEANUP_FAILED with cleanup.ok true, so the exit code is checked too.
+  // A TUNNEL_LOST whose callback close threw keeps exit 6 today, so it says so on the result instead.
+  if (result.cleanup?.ok === false || result.exitCode === EXIT.CLEANUP_FAILED || result.callbackCleanupUncertain === true) return result;
+  let network;
+  try {
+    network = await watch.classify({ failedAtMs });
+  } catch {
+    return result;
+  }
+  if (network?.decision !== "changed" || !Number.isFinite(network.atMs)) return result;
+  const message = requesterNetworkLostMessage(network, result.code);
+  try { stderrLine(message); } catch { /* the receipt still carries it */ }
+  return {
+    ...result, code: REQUESTER_NETWORK_LOST_CODE, underlyingCode: result.code,
+    requesterNetwork: { lost_at: new Date(network.atMs).toISOString(), evidence: network.evidence },
+    // The original diagnostic stays on the receipt, so a wrong attribution can still be seen.
+    error: message, underlyingError: result.error ?? null,
+  };
+}
+
 /** BOT-2467: where a lifecycle result carries its outcome-record channel. */
 export const OUTCOME_CHANNEL = Symbol.for("botbuddy.stackRunOutcomeChannel");
 
@@ -4272,6 +4368,8 @@ async function runStackLifecycleOnce(opts, childArgv, adapters, incidentBox) {
   const stopChild = (signal = "SIGTERM", forcedCode = null) => {
     void closeOrigin();
     if (!child || childResult) return;
+    // BOT-3109: when a loss stopped the child, so the requester probe weighs the network then, not after cleanup.
+    if (forcedCode != null && forcedStopCode == null) incidentBox.lossAtMs ??= Date.now();
     forcedStopCode ??= forcedCode;
     childGroupSignal(child, signal);
     const kill = clock.setTimeout(() => childGroupSignal(child, "SIGKILL"), 10_000);
@@ -4762,9 +4860,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 } : {}),
       };
@@ -5125,7 +5227,7 @@ async function runStackLifecycleOnce(opts, childArgv, adapters, incidentBox) {
               if (outage.recovered > (previous?.recovered ?? 0)) stderrLine("stack: the control plane answered again; the callback route stayed up");
             },
           });
-          nativeCallback.onExit((exit) => { if (childResult) return; callbackLost = exit; fencing = true; stopChild("SIGTERM", EXIT.LEASE_FAILED); });
+          nativeCallback.onExit((exit) => { if (childResult) return; incidentBox.lossAtMs ??= Date.now(); callbackLost = exit; fencing = true; stopChild("SIGTERM", EXIT.LEASE_FAILED); });
           placement.callbackTransport = NATIVE_CALLBACK_TRANSPORT;
         } catch (error) {
           await closeTunnel(); const cleanup = await requestCleanup();
@@ -5140,6 +5242,8 @@ async function runStackLifecycleOnce(opts, childArgv, adapters, incidentBox) {
       const forwardTarget = sshTarget;
       tunnel.onExit((exit) => {
         if (childResult) return;
+        // BOT-3109: when the loss was seen, even before a child exists (stopChild stamps only a running one).
+        incidentBox.lossAtMs ??= Date.now();
         tunnelLost = { ...exit, target: forwardTarget };
         stopChild("SIGTERM", EXIT.LEASE_FAILED);
       });
@@ -5222,7 +5326,7 @@ async function runStackLifecycleOnce(opts, childArgv, adapters, incidentBox) {
       // The forwards died between being verified and the child starting.
       await closeTunnel();
       const cleanup = await requestCleanup();
-      return tunnelLostResult(tunnelLost, { leaseId, cleanup, childExitCode: null });
+      return tunnelLostResult(tunnelLost, { leaseId, cleanup, childExitCode: null, ...(callbackCleanupError ? { callbackCleanupUncertain: true } : {}) });
     }
     child = startChild(childArgv, childEnv, childCwd);
     leaseIdleTtlSecs = current.data.idle_ttl_secs ?? opts.idleTtl ?? 1800;
@@ -5337,7 +5441,9 @@ async function runStackLifecycleOnce(opts, childArgv, adapters, incidentBox) {
       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 } : {}) });
+      return tunnelLostResult(tunnelLost, { leaseId, cleanup, childExitCode: childResult.code, fenced: fencing, ...(parkIncident ? { incident: parkIncident } : {}),
+        // BOT-3109: not a receipt field; it keeps an unproven callback close out of the requester relabel.
+        ...(callbackCleanupError ? { callbackCleanupUncertain: true } : {}) });
     }
     if (preempted && !receivedSignal) {
       return {
@@ -5412,6 +5518,10 @@ export function runReceiptFields(result) {
     // 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: ownerReleaseHeld(result) ? "released" : result.outcome, code: result.code ?? null, lease_id: result.leaseId ?? null,
+    // BOT-3109: a requester-side network loss names the code it replaced and when this machine lost its network.
+    ...(result.code === REQUESTER_NETWORK_LOST_CODE && REQUESTER_NETWORK_CANDIDATE_CODES.includes(result.underlyingCode)
+      ? { underlying_code: result.underlyingCode, underlying_error: result.underlyingError ?? null,
+        ...(result.requesterNetwork ? { requester_network: result.requesterNetwork } : {}) } : {}),
     // 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 } : {}),
@@ -5455,6 +5565,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).