@botbuddy/cli 1.59.10 → 1.60.1

package/daemon-release/darwin-arm64.json

@@ -1,7 +1,7 @@
 {
-  "release_version": "1.59.10",
-  "source_commit": "0a69b9e8cf14b345f8cc9e23e8ed68a8f240147c",
-  "source_sha256": "126242299e994c1e88bf377dbc0046672b5cdfe3c1454657f06abb64275b0301",
+  "release_version": "1.60.1",
+  "source_commit": "ac9d46a93d57bb9d5af94cba238532767c1f19cc",
+  "source_sha256": "667acf404a591bd0e09357645192040cba7a0b2085f33d89be6a4bbc84a6dd53",
   "target": "darwin-arm64",
-  "sha256": "8c41e97c983e235c710b8624849998f0e231cdab27d7147499e5ba6e4e7e5abb"
+  "sha256": "9dd4af84ad4131cf69c94bbed69f3c51087ca8ac4d742df6e9367faadbeddb97"
 }

package/daemon-release/linux-x64.json

@@ -1,7 +1,7 @@
 {
-  "release_version": "1.59.10",
-  "source_commit": "0a69b9e8cf14b345f8cc9e23e8ed68a8f240147c",
-  "source_sha256": "126242299e994c1e88bf377dbc0046672b5cdfe3c1454657f06abb64275b0301",
+  "release_version": "1.60.1",
+  "source_commit": "ac9d46a93d57bb9d5af94cba238532767c1f19cc",
+  "source_sha256": "667acf404a591bd0e09357645192040cba7a0b2085f33d89be6a4bbc84a6dd53",
   "target": "linux-x64",
-  "sha256": "92a173432e8a40e2ed5d91cd2a93a5fd0cfcd23c63b56ecec42d53127e272b7a"
+  "sha256": "61db8eb2108fcf9407460e96f487316728e262927241b5ee672ffca3443a11d3"
 }

package/daemon-release/manifest.json

@@ -1,21 +1,21 @@
 {
   "schema_version": 1,
-  "release_version": "1.59.10",
-  "source_commit": "0a69b9e8cf14b345f8cc9e23e8ed68a8f240147c",
-  "source_sha256": "126242299e994c1e88bf377dbc0046672b5cdfe3c1454657f06abb64275b0301",
+  "release_version": "1.60.1",
+  "source_commit": "ac9d46a93d57bb9d5af94cba238532767c1f19cc",
+  "source_sha256": "667acf404a591bd0e09357645192040cba7a0b2085f33d89be6a4bbc84a6dd53",
   "targets": {
     "darwin-arm64": {
       "goos": "darwin",
       "goarch": "arm64",
       "binary": "daemon/bin/darwin-arm64/botbuddy-daemon",
-      "sha256": "8c41e97c983e235c710b8624849998f0e231cdab27d7147499e5ba6e4e7e5abb",
+      "sha256": "9dd4af84ad4131cf69c94bbed69f3c51087ca8ac4d742df6e9367faadbeddb97",
       "mode": "0755"
     },
     "linux-x64": {
       "goos": "linux",
       "goarch": "amd64",
       "binary": "daemon/bin/linux-x64/botbuddy-daemon",
-      "sha256": "92a173432e8a40e2ed5d91cd2a93a5fd0cfcd23c63b56ecec42d53127e272b7a",
+      "sha256": "61db8eb2108fcf9407460e96f487316728e262927241b5ee672ffca3443a11d3",
       "mode": "0755"
     }
   }

package/package.json

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

package/src/agent-doctor.mjs

@@ -10,15 +10,35 @@ import { selfHealAgentSession } from "./agent-session.mjs";
 import { machineUuid } from "./machine-id.mjs";
 import { machineHost } from "./machine-host.mjs";
 
+// BOT-2599: checks `--only` can run on their own. Each is local-only (no auth,
+// no network), so it is fast enough for a git hook.
+export const DOCTOR_ONLY_CHECKS = Object.freeze(["git_transport"]);
+
 export function parseDoctorArgs(argv = []) {
   const parsed = { fix: false, printExports: false, json: false, errors: [] };
-  for (const arg of argv) {
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
     if (arg === "--fix") parsed.fix = true;
     else if (arg === "--print-exports") parsed.printExports = true;
     else if (arg === "--json") parsed.json = true;
     else if (arg === "--help" || arg === "-h") parsed.help = true;
-    else parsed.errors.push(`unknown option: ${arg}`);
+    else if (arg === "--only" || arg.startsWith("--only=")) {
+      const value = arg === "--only" ? argv[++i] : arg.slice("--only=".length);
+      if (!value || value.startsWith("--")) parsed.errors.push("--only needs a check name (git_transport)");
+      else if (!DOCTOR_ONLY_CHECKS.includes(value)) parsed.errors.push(`unknown check: ${value} (--only accepts ${DOCTOR_ONLY_CHECKS.join(", ")})`);
+      else parsed.only = value;
+    } else if (arg === "--remote" || arg.startsWith("--remote=")) {
+      const value = arg === "--remote" ? argv[++i] : arg.slice("--remote=".length);
+      if (!value) parsed.errors.push("--remote needs a remote name or URL");
+      else parsed.remote = value;
+    } else if (arg === "--url" || arg.startsWith("--url=")) {
+      // A pre-push hook's $2: the URL this push actually goes to.
+      const value = arg === "--url" ? argv[++i] : arg.slice("--url=".length);
+      if (!value) parsed.errors.push("--url needs the push URL");
+      else parsed.url = value;
+    } else parsed.errors.push(`unknown option: ${arg}`);
   }
+  if (parsed.only && parsed.printExports) parsed.errors.push("--print-exports cannot be combined with --only");
   return parsed;
 }
 
@@ -251,5 +271,5 @@ export async function doctorAgentAuth({
 }
 
 export function doctorHelp() {
-  return "bb doctor [--fix] [--print-exports] [--json]\n\nChecks the client key, repo binding, cached agent session, and this worktree's stack-lease capability (registered host + attested machine). --fix mints a replacement session and (re)establishes the stack-lease capability; --print-exports prints its canonical shell exports. When the client key is unreachable (a Background LaunchAgent cannot read the login Keychain), --fix mints from the tier-2 MCP key exported under the binding's mcp_env name (env only, never Keychain).";
+  return "bb doctor [--fix] [--print-exports] [--json]\nbb doctor --only git_transport [--remote <name>] [--url <push url>] [--fix] [--json]\n\nChecks the client key, repo binding, cached agent session, this worktree's stack-lease capability (registered host + attested machine), and whether git's SSH push connection carries a keepalive (git_transport). --fix mints a replacement session and (re)establishes the stack-lease capability; --print-exports prints its canonical shell exports. When the client key is unreachable (a Background LaunchAgent cannot read the login Keychain), --fix mints from the tier-2 MCP key exported under the binding's mcp_env name (env only, never Keychain).\n\ngit_transport: git opens the SSH connection BEFORE the pre-push hook runs, so a long hook lets it idle until it is dropped and the push dies (exit 141) after every gate passed. ok = ServerAliveInterval > 0 on the push's ssh; n/a = not an ssh remote; needs_fix / unknown = not provable. --fix sets git config --local core.sshCommand \"ssh -o ServerAliveInterval=20 -o ServerAliveCountMax=60\" only when nothing is configured; an existing GIT_SSH_COMMAND, core.sshCommand or GIT_SSH is never overwritten (the exact edit is printed instead).\n\n--only git_transport runs just that check — no sign-in, no network, well under a second — for a pre-push hook: exit 0 ok/n/a, 3 needs_fix/unknown (remedy on stderr), 4 usage. A hook passes its $1 as --remote and its $2 (the URL this push goes to) as --url; without --url every push URL of the remote (default: the branch's push remote, else origin) is checked.";
 }

package/src/commands.mjs

@@ -30,6 +30,7 @@ import { createTelemetryOutbox } from "./telemetry-outbox.mjs";
 import { attestTelemetryCredential, loadTelemetryIdentity, loadTelemetryLocation } from "./telemetry-config.mjs";
 import { deliverExecutionEvent } from "./telemetry-delivery.mjs";
 import { doctorAgentAuth, doctorHelp, parseDoctorArgs, readClientKeyStrict, repairFailureRecovery } from "./agent-doctor.mjs";
+import { GIT_TRANSPORT_PASSING, checkGitTransport, formatGitTransportLine } from "./git-transport.mjs";
 import { formatPublishIp, isLoopbackIp, probeEnginePublishIp, publishIpFix } from "./docker-publish-ip.mjs";
 import { cmdHost, fixHelperWorkers, formatHelperWorkersLines, inspectHelperWorkers } from "./helper-host.mjs";
 import { clearAgentState, resolveAgentSessionCredential, selfHealAgentSession } from "./agent-session.mjs";
@@ -48,6 +49,9 @@ export function shouldCheckForUpdates(argv) {
   // BOT-1982: nor `test-ingest`, which runs at the tail of every test harness.
   if (command === "wait" || command === "telemetry" || command === "usage" || command === "test-ingest") return false;
   if (argv.includes("--json")) return false;
+  // BOT-2599: `bb doctor --only <check>` runs inside a git pre-push hook; it must
+  // stay local and sub-second, so it never consults the npm registry.
+  if (command === "doctor" && argv.some((arg) => arg === "--only" || arg.startsWith("--only="))) return false;
   return true;
 }
 
@@ -284,10 +288,13 @@ export async function cmdDoctor(args, {
   // BOT-1982: which credential test-run uploads would use — the ONE place a
   // missing upload credential is reported (the harnesses skip silently).
   testIngestReport = () => doctorTestIngest(),
+  // BOT-2599: will this clone's SSH push connection survive a long pre-push hook?
+  gitTransportReport = async ({ fix, remote, url }) => checkGitTransport({ fix, remote, url }),
 } = {}) {
   const parsed = parseDoctorArgs(args);
   if (parsed.help) { log(doctorHelp()); return 0; }
   if (parsed.errors.length) { errorLog(`bb doctor: ${parsed.errors.join("; ")}`); return 4; }
+  if (parsed.only === "git_transport") return doctorGitTransportOnly(parsed, { log, errorLog, gitTransportReport });
   const result = await doctor({ fix: parsed.fix, printExports: parsed.printExports });
   // BOT-2146: where would this host's engine publish a leased stack's ports?
   // Informational (read-only, never changes the exit code); reported only when
@@ -310,8 +317,13 @@ export async function cmdDoctor(args, {
   }
   // BOT-1982: informational, like usage sync — never changes the exit code.
   const testIngest = await Promise.resolve().then(testIngestReport).catch(() => null);
+  // BOT-2599: informational in the full report (its exit code stays the auth
+  // verdict existing callers key on); `--only git_transport` is the gating form.
+  const gitTransport = await Promise.resolve()
+    .then(() => gitTransportReport({ fix: parsed.fix, remote: parsed.remote ?? null, url: parsed.url ?? null }))
+    .catch(() => ({ check: "git_transport", status: "unknown", reason: "check_failed" }));
   if (parsed.json) {
-    log(JSON.stringify({ ...result.report, ...(usage ? { usage_sync: usage } : {}), ...(bootstrap ? { bootstrap } : {}), ...(helperWorkers ? { helper_workers: helperWorkers } : {}), ...(testIngest ? { test_ingest: testIngest } : {}) }));
+    log(JSON.stringify({ ...result.report, ...(usage ? { usage_sync: usage } : {}), ...(bootstrap ? { bootstrap } : {}), ...(helperWorkers ? { helper_workers: helperWorkers } : {}), ...(testIngest ? { test_ingest: testIngest } : {}), ...(gitTransport ? { git_transport: gitTransport } : {}) }));
   } else {
     log(`binding: ${result.report.binding.status}${result.report.binding.tenant ? ` (${result.report.binding.tenant})` : ""}`);
     log(`client key: ${result.report.client_key.status}`);
@@ -329,11 +341,36 @@ export async function cmdDoctor(args, {
     if (usage) log(formatUsageSyncLine(usage));
     for (const line of formatHelperWorkersLines(helperWorkers, helperFix)) log(line);
     if (testIngest) log(formatTestIngestLine(testIngest));
+    if (gitTransport) {
+      log(formatGitTransportLine(gitTransport));
+      if (gitTransport.recovery) log(`git transport recovery: ${gitTransport.recovery}`);
+    }
   }
   if (result.exports) log(result.exports);
   return result.exitCode;
 }
 
+/**
+ * BOT-2599: `bb doctor --only git_transport` — the one check, nothing else (no
+ * sign-in, no network), for a pre-push hook. Exit 0 = ok / n/a; 3 = needs_fix
+ * or unknown (a check that cannot prove a keepalive never passes); the remedy
+ * goes to stderr so a hook shows it.
+ */
+async function doctorGitTransportOnly(parsed, { log, errorLog, gitTransportReport }) {
+  let report;
+  try {
+    report = await gitTransportReport({ fix: parsed.fix, remote: parsed.remote ?? null, url: parsed.url ?? null });
+  } catch {
+    report = null;
+  }
+  if (!report) report = { check: "git_transport", status: "unknown", reason: "check_failed", recovery: "the git_transport check failed to run; run `bb doctor --only git_transport` by hand" };
+  if (parsed.json) log(JSON.stringify({ git_transport: report }));
+  else log(formatGitTransportLine(report));
+  const passing = GIT_TRANSPORT_PASSING.has(report.status);
+  if (!passing && report.recovery && !parsed.json) errorLog(`recovery: ${report.recovery}`);
+  return passing ? 0 : 3;
+}
+
 /** BOT-1021: is the daily sweep installed, and how did the last sync runs go? */
 export async function doctorUsageSync({ agentStatus = usageAgentStatus, status = usageStatus } = {}) {
   const agent = await agentStatus();
@@ -446,12 +483,24 @@ does not prove that the workload is still running.
 
 ${bold("Safe recovery")}
   1. Preserve the command-run ID and the original result.
-  2. Prefer the owning runner's local terminal receipt for the workload verdict.
-  3. If the receipt is terminal, do not cancel or duplicate the command solely
+  2. Run ${cyan("bb run inspect <command-run-id>")} from the owning checkout.
+  3. Prefer the owning runner's local terminal receipt for the workload verdict.
+  4. If the receipt is terminal, do not cancel or duplicate the command solely
      because remote state remains ${cyan("registered")} or ${cyan("running")}.
-  4. If the receipt is absent/non-terminal, retain the original runner result;
+  5. If the receipt is absent/non-terminal, retain the original runner result;
      do not poll or infer completion from elapsed time.
-  5. Report the receipt and remote discrepancy as telemetry evidence.
+  6. Report the receipt and remote discrepancy as telemetry evidence. A stale
+     test-run or command-run is never validation evidence.
+
+${bold("One controlled push retry")}
+Only after inspection leaves the original push unresolved, arm an exact-SHA CI
+wait before one new push, then verify the resulting CI run reports that SHA:
+
+  ${cyan("bb wait 'ci:repo=SupplySpark/supplyspark-ent,scope=next,sha=<full-sha>' --heartbeat")}
+
+Do not substitute ${cyan("pr-state")}, a timer, or a status-polling loop for a bare
+push. If the prior push has no terminal receipt, keep it unresolved rather than
+counting it as validation evidence.
 
 ${bold("Boundary")}
 Command-run status is agent-owned. A different agent may be denied access; that
@@ -675,6 +724,8 @@ export async function cmdSetup(args, {
   selfHeal = selfHealAgentSession,
   callerResolver = resolveCaller,
   usageAgent = installUsageAgent,
+  // BOT-2599: setup also gives this clone's SSH push transport a keepalive.
+  gitTransport = async (opts) => checkGitTransport(opts),
   cwd = process.cwd(),
   env = process.env,
   platform = process.platform,
@@ -786,6 +837,7 @@ export async function cmdSetup(args, {
       errorLog(`bb setup: warning: ${warning} — held by ${who}. Confirm the active work before editing shared resources; typed locks remain required.`);
     }
     log(`bb setup: ${tenant} is ready (${session.source} worktree session). Run bb wait '<condition>'.`);
+    await reportGitTransport(gitTransport, { cwd, env, log });
     await reportUsageAgent(usageAgent, { cwd, log });
     return 0;
   } catch (error) {
@@ -805,6 +857,16 @@ async function reportUsageAgent(usageAgent, { cwd, log }) {
   else log(`bb setup: daily usage sync could not be installed (${result?.error ?? "unknown"}); run bb setup again to retry.`);
 }
 
+// BOT-2599: never fails setup — the session is ready either way; the line says
+// whether pushes from this clone keep their SSH connection through a long hook.
+async function reportGitTransport(gitTransport, { cwd, env, log }) {
+  let report;
+  try { report = await gitTransport({ cwd, env, fix: true }); } catch { report = null; }
+  if (!report) report = { check: "git_transport", status: "unknown", reason: "check_failed" };
+  log(`bb setup: ${formatGitTransportLine(report)}`);
+  if (report.recovery) log(`bb setup: git transport recovery: ${report.recovery}`);
+}
+
 export function loginHelp(log = console.log) {
   log(`${bold("botbuddy login")} — authenticate via OAuth (browser + loopback callback)
 

package/src/git-transport.mjs

@@ -0,0 +1,476 @@
+// BOT-2599 — keep git's SSH connection alive through a long pre-push hook.
+//
+// git opens the SSH transport and reads the remote's ref advertisement BEFORE it
+// runs the pre-push hook (githooks(5)). A hook that runs for minutes leaves that
+// connection idle until something on the path drops it, and the pack send then
+// dies on a closed pipe (exit 141) after every gate passed. An SSH-level
+// keepalive (`ServerAliveInterval` > 0) keeps it open.
+//
+// This module answers "will THIS clone's push connection carry a keepalive?" the
+// way git itself picks the ssh command — GIT_SSH_COMMAND, then core.sshCommand,
+// then GIT_SSH, then plain `ssh` — and, for ssh, the way ssh resolves options:
+// an explicit `-o ServerAliveInterval=…` on the command line wins over every
+// config file; otherwise `ssh -G` prints the effective value. `ssh -G` reads
+// config only (no network), but a config can `Match exec`, so it is bounded and
+// a timeout is a typed `unknown`, never a false `ok`.
+//
+// `--fix` writes `git config --local core.sshCommand` only when NOTHING is
+// configured; an existing GIT_SSH_COMMAND, core.sshCommand or GIT_SSH is never
+// overwritten — the report carries the exact edit instead. The remote URL is
+// never reported (an HTTPS URL can embed a credential); only its host.
+//
+// Dependency-free (Node stdlib only); every git/ssh call goes through `run`
+// (spawnSync-compatible) so the unit tests need no network and no real config.
+
+import { spawnSync } from "node:child_process";
+import { homedir } from "node:os";
+import { basename } from "node:path";
+
+export const GIT_TRANSPORT_CHECK = "git_transport";
+export const KEEPALIVE_OPTIONS = "-o ServerAliveInterval=20 -o ServerAliveCountMax=60";
+export const KEEPALIVE_SSH_COMMAND = `ssh ${KEEPALIVE_OPTIONS}`;
+export const SSH_CONFIG_TIMEOUT_MS = 5_000;
+const GIT_TIMEOUT_MS = 5_000;
+
+/** Statuses that let a push proceed. `unknown` never does: it cannot prove a keepalive. */
+export const GIT_TRANSPORT_PASSING = Object.freeze(new Set(["ok", "n/a"]));
+
+function shellQuote(value) {
+  return `'${String(value).replaceAll("'", "'\\''")}'`;
+}
+
+/**
+ * Classify a remote URL by transport. Only ssh remotes carry host/user/port;
+ * nothing else of the URL is kept (it may embed a credential).
+ */
+export function classifyRemoteUrl(url) {
+  const value = String(url ?? "").trim();
+  if (!value) return { transport: "none" };
+  const scheme = value.match(/^([a-z][a-z0-9+.-]*):\/\//i);
+  if (scheme) {
+    const name = scheme[1].toLowerCase();
+    if (name === "ssh" || name === "git+ssh" || name === "ssh+git") {
+      let parsed;
+      try {
+        parsed = new URL(`ssh://${value.slice(scheme[0].length)}`);
+      } catch {
+        return { transport: "ssh", host: null, user: null, port: null };
+      }
+      return {
+        transport: "ssh",
+        host: parsed.hostname.replace(/^\[|\]$/g, "") || null,
+        user: parsed.username ? decodeURIComponent(parsed.username) : null,
+        port: parsed.port || null,
+      };
+    }
+    return { transport: name === "https" || name === "http" ? "https" : name };
+  }
+  // git's scp-like syntax, `[user@]host:path`, applies only when no slash comes
+  // before the first colon; anything else is a local path.
+  const scp = value.match(/^(?:([^@/:]+)@)?(\[[^\]/]+\]|[^:/]+):/);
+  if (scp) return { transport: "ssh", host: scp[2].replace(/^\[|\]$/g, ""), user: scp[1] ?? null, port: null };
+  return { transport: "local" };
+}
+
+/**
+ * Split a git ssh command the way `sh -c` evaluates it (git runs
+ * core.sshCommand / GIT_SSH_COMMAND through the shell): words, quotes,
+ * backslash escapes, a leading `~` / `~/` (the home directory) and plain
+ * `$NAME` / `${NAME}` expansions from `env`. Returns null for anything a real
+ * shell would do that this cannot reproduce faithfully — command substitution,
+ * other parameter forms, `~user`, pipes, redirects, a leading comment, an
+ * unbalanced quote, or an unquoted expansion that word splitting or globbing
+ * would change — so the caller reports `unknown` instead of guessing.
+ */
+export function splitShellWords(text, env = {}) {
+  const words = [];
+  let current = "";
+  let inWord = false;
+  let quote = null;
+  const home = () => env.HOME || homedir() || null;
+  // `$NAME` / `${NAME}` at text[i] ("$"); returns { value, next } or null.
+  const expand = (i) => {
+    const braced = text[i + 1] === "{";
+    const m = text.slice(braced ? i + 2 : i + 1).match(/^[A-Za-z_][A-Za-z0-9_]*/);
+    if (!m) return null;
+    let next = i + 1 + (braced ? 1 : 0) + m[0].length;
+    if (braced) {
+      if (text[next] !== "}") return null;
+      next += 1;
+    }
+    return { value: env[m[0]] ?? "", next: next - 1 };
+  };
+  for (let i = 0; i < text.length; i += 1) {
+    const ch = text[i];
+    if (quote === "'") {
+      if (ch === "'") quote = null;
+      else current += ch;
+      continue;
+    }
+    if (quote === '"') {
+      if (ch === '"') quote = null;
+      else if (ch === "\\" && i + 1 < text.length && '"\\$`'.includes(text[i + 1])) current += text[++i];
+      else if (ch === "`") return null;
+      else if (ch === "$") {
+        const ex = expand(i);
+        if (!ex) return null;
+        current += ex.value;
+        i = ex.next;
+      } else current += ch;
+      continue;
+    }
+    if (ch === "'" || ch === '"') {
+      quote = ch;
+      inWord = true;
+      continue;
+    }
+    if (ch === "\\") {
+      if (i + 1 >= text.length) return null;
+      current += text[++i];
+      inWord = true;
+      continue;
+    }
+    if (/\s/.test(ch)) {
+      if (inWord) words.push(current);
+      current = "";
+      inWord = false;
+      continue;
+    }
+    if (ch === "~" && !inWord) {
+      // Tilde-prefix: only a bare `~` ending at `/`, whitespace or the end.
+      const after = text[i + 1];
+      if (after !== undefined && after !== "/" && !/\s/.test(after)) return null;
+      const dir = home();
+      if (!dir) return null;
+      current += dir;
+      inWord = true;
+      continue;
+    }
+    if (ch === "$") {
+      const ex = expand(i);
+      if (!ex || /[\s*?[]/.test(ex.value)) return null;
+      current += ex.value;
+      if (ex.value) inWord = true;
+      i = ex.next;
+      continue;
+    }
+    if ("|&;<>()`".includes(ch) || (ch === "#" && !inWord)) return null;
+    current += ch;
+    inWord = true;
+  }
+  if (quote) return null;
+  if (inWord) words.push(current);
+  return words;
+}
+
+/** ssh's time format (`20`, `30s`, `1m`, `1h30m`) in seconds, or null. */
+export function parseSshTime(value) {
+  const text = String(value ?? "").trim().toLowerCase();
+  if (/^\d+$/.test(text)) return Number(text);
+  const units = { s: 1, m: 60, h: 3600, d: 86400, w: 604800 };
+  let total = 0;
+  let rest = text;
+  if (!rest) return null;
+  while (rest) {
+    const m = rest.match(/^(\d+)([smhdw])/);
+    if (!m) return null;
+    total += Number(m[1]) * units[m[2]];
+    rest = rest.slice(m[0].length);
+  }
+  return total;
+}
+
+// ssh(1) options that take an argument (`ssh -h` usage line).
+const SSH_ARG_FLAGS = new Set("BbcDEeFIiJLlmOoPpQRSWw");
+
+/**
+ * Parse ssh's own argument list (everything after the program) the way ssh's
+ * getopt does: `-o` values, and any positional word. A positional word in a
+ * configured ssh command is an embedded destination (`ssh bastion ssh …`): git
+ * appends its host and remote command AFTER it, so a probe that appended `-G`
+ * would become a remote command and connect. Returns null when an option is
+ * missing its argument.
+ */
+export function parseSshArgs(args) {
+  const options = [];
+  const positional = [];
+  // The arguments up to (not including) a `--` terminator: a probe must put its
+  // own options before the terminator, or ssh reads `-G` as the destination.
+  let optionArgs = args;
+  for (let i = 0; i < args.length; i += 1) {
+    const arg = args[i];
+    if (arg === "--") {
+      optionArgs = args.slice(0, i);
+      positional.push(...args.slice(i + 1));
+      break;
+    }
+    if (!arg.startsWith("-") || arg === "-") {
+      positional.push(arg);
+      continue;
+    }
+    for (let j = 1; j < arg.length; j += 1) {
+      const flag = arg[j];
+      if (!SSH_ARG_FLAGS.has(flag)) continue;
+      let value = arg.slice(j + 1);
+      if (!value) {
+        if (i + 1 >= args.length) return null;
+        value = args[++i];
+      }
+      if (flag === "o") options.push(value);
+      break;
+    }
+  }
+  return { options, positional, optionArgs };
+}
+
+/**
+ * The ServerAliveInterval an ssh argument list sets explicitly, or null. ssh
+ * keeps the FIRST value it obtains and the command line beats every config
+ * file, so the first explicit `-o ServerAliveInterval` is authoritative.
+ */
+export function explicitServerAliveInterval(args) {
+  const parsed = parseSshArgs(args);
+  for (const option of parsed?.options ?? []) {
+    const m = option.match(/^\s*serveraliveinterval\s*(?:=\s*|\s+)(\S+)\s*$/i);
+    if (m) return parseSshTime(m[1]);
+  }
+  return null;
+}
+
+/** Insert the keepalive options right after the program, so they win over any later `-o`. */
+export function withKeepalive(command) {
+  const m = String(command).match(/^(\s*)(\S+)/);
+  if (!m) return KEEPALIVE_SSH_COMMAND;
+  return `${m[1]}${m[2]} ${KEEPALIVE_OPTIONS}${command.slice(m[0].length)}`;
+}
+
+function runQuiet(run, cmd, args, { cwd, env, timeout }) {
+  let res;
+  try {
+    res = run(cmd, args, { cwd, env, encoding: "utf8", timeout, stdio: ["ignore", "pipe", "pipe"] });
+  } catch (error) {
+    return { status: null, stdout: "", stderr: "", error };
+  }
+  return {
+    status: typeof res?.status === "number" ? res.status : null,
+    stdout: String(res?.stdout ?? ""),
+    stderr: String(res?.stderr ?? ""),
+    error: res?.error ?? null,
+    signal: res?.signal ?? null,
+  };
+}
+
+function git(run, args, { cwd, env }) {
+  return runQuiet(run, "git", args, { cwd, env, timeout: GIT_TIMEOUT_MS });
+}
+
+function gitConfigValue(run, key, ctx) {
+  const res = git(run, ["config", "--get", key], ctx);
+  return res.status === 0 ? res.stdout.replace(/\n$/, "") : null;
+}
+
+/** Which remote this push would use: branch pushRemote → remote.pushDefault → branch remote → origin. */
+function defaultPushRemote(run, ctx) {
+  const head = git(run, ["symbolic-ref", "--quiet", "--short", "HEAD"], ctx);
+  const branch = head.status === 0 ? head.stdout.trim() : null;
+  return (branch && gitConfigValue(run, `branch.${branch}.pushRemote`, ctx))
+    || gitConfigValue(run, "remote.pushDefault", ctx)
+    || (branch && gitConfigValue(run, `branch.${branch}.remote`, ctx))
+    || "origin";
+}
+
+/**
+ * Every URL this push may go to. A hook passes the actual destination (`$2`) as
+ * `url`; otherwise all of the remote's push URLs (`--all`: a remote can push to
+ * several) so the verdict covers each, not just the first.
+ */
+function resolveDestinations(run, { remote, url }, ctx) {
+  // A remote given as a URL (a push to a URL) is never echoed: it can embed a credential.
+  if (url) return { name: remote && classifyRemoteUrl(remote).transport === "local" ? remote : null, urls: [url] };
+  const name = remote || defaultPushRemote(run, ctx);
+  const res = git(run, ["remote", "get-url", "--push", "--all", name], ctx);
+  const urls = res.status === 0 ? res.stdout.split("\n").map((line) => line.trim()).filter(Boolean) : [];
+  if (urls.length) return { name, urls };
+  // A pre-push hook's $1 is the URL itself when the push named a URL, not a remote.
+  if (remote && classifyRemoteUrl(remote).transport !== "local") return { name: null, urls: [remote] };
+  return { name, urls: [], error: res.error ? "git_unavailable" : "no_push_remote" };
+}
+
+/** git's own order: GIT_SSH_COMMAND, core.sshCommand, GIT_SSH, then plain `ssh`. */
+function resolveSshCommand(run, env, ctx) {
+  if (env.GIT_SSH_COMMAND) return { source: "GIT_SSH_COMMAND", command: env.GIT_SSH_COMMAND, words: splitShellWords(env.GIT_SSH_COMMAND, env) };
+  let res = git(run, ["config", "--show-scope", "--get", "core.sshCommand"], ctx);
+  if (res.status === 129) res = git(run, ["config", "--get", "core.sshCommand"], ctx); // git < 2.26
+  if (res.status === 0) {
+    const line = res.stdout.replace(/\n$/, "");
+    const tab = line.indexOf("\t");
+    const scoped = tab > 0 && /^(local|global|system|worktree|command)$/.test(line.slice(0, tab));
+    const command = scoped ? line.slice(tab + 1) : line;
+    return { source: "core.sshCommand", scope: scoped ? line.slice(0, tab) : null, command, words: splitShellWords(command, env) };
+  }
+  if (env.GIT_SSH) return { source: "GIT_SSH", command: env.GIT_SSH, words: [env.GIT_SSH] };
+  return { source: "ssh_config", command: "ssh", words: ["ssh"] };
+}
+
+function sshEffectiveInterval(run, optionArgs, program, remote, { env, timeout }) {
+  // The configured options, then the probe's, then `--` and the host: a host can
+  // never be read as an option, and a configured trailing `--` cannot swallow -G.
+  const args = [...optionArgs, "-G"];
+  if (remote.port) args.push("-p", remote.port);
+  if (remote.user) args.push("-l", remote.user);
+  args.push("--", remote.host);
+  const res = runQuiet(run, program, args, { env, timeout });
+  if (res.error?.code === "ETIMEDOUT" || (res.signal && res.status === null)) return { reason: "ssh_config_timeout" };
+  if (res.error?.code === "ENOENT") return { reason: "ssh_not_found" };
+  if (res.error || res.status !== 0) return { reason: "ssh_config_unreadable" };
+  const m = res.stdout.match(/^serveraliveinterval\s+(\S+)\s*$/im);
+  const interval = m ? parseSshTime(m[1]) : null;
+  return interval == null ? { reason: "ssh_config_unparseable" } : { interval };
+}
+
+function recoveryFor(report, resolved) {
+  if (report.status === "ok" || report.status === "n/a") return null;
+  if (resolved.source === "ssh_config") {
+    if (report.status === "needs_fix") {
+      return `nothing gives this push a keepalive (ssh config for ${report.host}: ServerAliveInterval ${report.server_alive_interval}); run \`bb doctor --fix\` — it sets git config --local core.sshCommand "${KEEPALIVE_SSH_COMMAND}" for this clone and its worktrees`;
+    }
+    return `\`ssh -G ${report.host}\` gave no answer (${report.reason}), so a keepalive cannot be proven; run \`bb doctor --fix\` to set an explicit one in core.sshCommand`;
+  }
+  if (report.reason === "ssh_command_has_destination") {
+    return `the ssh command embeds a destination (a nested connection such as \`ssh bastion ssh\`), so its keepalive cannot be proven without connecting and \`bb doctor --fix\` never edits it; use ProxyJump instead: ssh -J <bastion> ${KEEPALIVE_OPTIONS}`;
+  }
+  // Echo the configured command back only when it is plain ssh: another program
+  // (sshpass, a wrapper) can carry a secret on its command line.
+  const plainSsh = Boolean(resolved.words?.length) && basename(resolved.words[0]) === "ssh";
+  const suggested = plainSsh ? withKeepalive(resolved.command) : null;
+  const edit = suggested
+    ? `add ${KEEPALIVE_OPTIONS} right after the program`
+    : `make its keepalive explicit with ${KEEPALIVE_OPTIONS}`;
+  if (resolved.source === "GIT_SSH_COMMAND") {
+    return `GIT_SSH_COMMAND overrides git config and \`bb doctor --fix\` never edits it; ${edit}${suggested ? `: export GIT_SSH_COMMAND=${shellQuote(suggested)}` : ""} (or unset it and run \`bb doctor --fix\`)`;
+  }
+  if (resolved.source === "GIT_SSH") {
+    return `GIT_SSH is set and \`bb doctor --fix\` never overrides it; export GIT_SSH_COMMAND=${shellQuote(`${resolved.command} ${KEEPALIVE_OPTIONS}`)} or unset GIT_SSH and run \`bb doctor --fix\``;
+  }
+  const where = resolved.scope && resolved.scope !== "command" ? ` --${resolved.scope}` : "";
+  const how = resolved.scope === "command" ? "it is passed with `git -c`; change it there" : null;
+  return `core.sshCommand${resolved.scope ? ` (${resolved.scope} config)` : ""} has no keepalive and \`bb doctor --fix\` never overwrites it; ${edit}${how ? ` — ${how}` : suggested ? `: git config${where} core.sshCommand ${shellQuote(suggested)}` : ""}`;
+}
+
+/** The verdict for one push URL. `sshCommand()` resolves the ssh command once, on first need. */
+function evaluateDestination(rawUrl, { run, env, sshTimeoutMs, sshCommand }) {
+  const url = classifyRemoteUrl(rawUrl);
+  if (url.transport !== "ssh") return { status: "n/a", transport: url.transport, reason: `${url.transport}_remote` };
+  if (!url.host) return { status: "unknown", transport: "ssh", host: null, reason: "unparseable_remote_url" };
+  // git refuses a host or user that starts with "-" (it would be read as an ssh
+  // option, CVE-2017-1000117); so does this probe, without running ssh.
+  if (url.host.startsWith("-") || url.user?.startsWith("-")) return { status: "unknown", transport: "ssh", host: null, reason: "unsafe_remote_url" };
+  const resolved = sshCommand();
+  const report = {
+    transport: "ssh", host: url.host, source: resolved.source,
+    ...(resolved.scope ? { scope: resolved.scope } : {}),
+    server_alive_interval: null,
+  };
+  if (!resolved.words || resolved.words.length === 0) {
+    report.reason = "unparseable_ssh_command";
+  } else {
+    const isSsh = basename(resolved.words[0]) === "ssh";
+    const sshArgs = isSsh ? parseSshArgs(resolved.words.slice(1)) : null;
+    const explicit = explicitServerAliveInterval(resolved.words.slice(1));
+    if (isSsh && (!sshArgs || sshArgs.positional.length > 0)) {
+      // `ssh bastion ssh`: a nested connection. Never probe it (the probe would
+      // connect); its inner keepalive cannot be proven from here either.
+      report.reason = sshArgs ? "ssh_command_has_destination" : "unparseable_ssh_command";
+    } else if (explicit != null) {
+      report.server_alive_interval = explicit;
+      report.interval_origin = "command_line";
+    } else if (isSsh) {
+      const effective = sshEffectiveInterval(run, sshArgs.optionArgs, resolved.words[0], url, { env, timeout: sshTimeoutMs });
+      if (effective.reason) report.reason = effective.reason;
+      else {
+        report.server_alive_interval = effective.interval;
+        report.interval_origin = "ssh_config";
+      }
+    } else {
+      report.reason = "custom_ssh_program";
+    }
+  }
+  if (report.server_alive_interval == null) report.status = "unknown";
+  else report.status = report.server_alive_interval > 0 ? "ok" : "needs_fix";
+  return report;
+}
+
+function evaluate({ cwd, env, remote, url, run, sshTimeoutMs }) {
+  const ctx = { cwd, env };
+  const target = resolveDestinations(run, { remote, url }, ctx);
+  const base = { check: GIT_TRANSPORT_CHECK, remote: target.name ?? null };
+  if (target.urls.length === 0) {
+    if (target.error === "git_unavailable") return { report: { ...base, status: "unknown", transport: null, reason: "git_unavailable", recovery: "git could not run here (not on PATH, or the directory is missing); run the check from the clone you push from" } };
+    return { report: { ...base, status: "n/a", transport: "none", reason: "no_push_remote" } };
+  }
+  let resolved = null;
+  const sshCommand = () => (resolved ??= resolveSshCommand(run, env, ctx));
+  const results = target.urls.map((u) => evaluateDestination(u, { run, env, sshTimeoutMs, sshCommand }));
+  // The push passes only if every destination does: report the first that does not.
+  const primary = results.find((r) => !GIT_TRANSPORT_PASSING.has(r.status))
+    ?? results.find((r) => r.transport === "ssh") ?? results[0];
+  const report = { ...base, ...primary };
+  if (results.length > 1) {
+    report.destinations = results.map((r) => ({
+      transport: r.transport, ...(r.host ? { host: r.host } : {}), status: r.status,
+      ...(r.server_alive_interval != null ? { server_alive_interval: r.server_alive_interval } : {}),
+      ...(r.reason ? { reason: r.reason } : {}),
+    }));
+  }
+  if (report.reason === "unparseable_remote_url" || report.reason === "unsafe_remote_url") report.recovery = "a push URL's host cannot be parsed safely; check `git remote get-url --push --all`";
+  else if (resolved) {
+    const recovery = recoveryFor(report, resolved);
+    if (recovery) report.recovery = recovery;
+  }
+  return { report, resolved };
+}
+
+/**
+ * Check (and with `fix`, repair) the keepalive on this clone's push transport.
+ * `url` is the push's actual destination (a pre-push hook's `$2`); without it
+ * every push URL of `remote` (default: the branch's push remote) is checked.
+ * Returns the report: { check, status: ok|needs_fix|n/a|unknown, remote,
+ * transport, host?, source?, scope?, server_alive_interval?, interval_origin?,
+ * reason?, recovery?, destinations? (when several URLs), fix? }.
+ */
+export function checkGitTransport({
+  cwd = process.cwd(), env = process.env, remote = null, url = null, fix = false,
+  run = spawnSync, sshTimeoutMs = SSH_CONFIG_TIMEOUT_MS,
+} = {}) {
+  const first = evaluate({ cwd, env, remote, url, run, sshTimeoutMs });
+  if (!fix || GIT_TRANSPORT_PASSING.has(first.report.status) || !first.resolved) return first.report;
+  if (first.resolved.source !== "ssh_config") {
+    return { ...first.report, fix: { applied: false, reason: `existing_${first.resolved.source}_left_untouched` } };
+  }
+  const set = git(run, ["config", "--local", "core.sshCommand", KEEPALIVE_SSH_COMMAND], { cwd, env });
+  if (set.status !== 0) {
+    return { ...first.report, fix: { applied: false, reason: "git_config_failed" } };
+  }
+  // Report fixed only on proof: re-resolve exactly as a push would.
+  const after = evaluate({ cwd, env, remote, url, run, sshTimeoutMs }).report;
+  return { ...after, fix: { applied: true, set: `git config --local core.sshCommand "${KEEPALIVE_SSH_COMMAND}"`, verified: after.status === "ok" } };
+}
+
+/** One human line for `bb doctor` / `bb setup`. */
+export function formatGitTransportLine(report) {
+  if (!report) return "git transport: unknown (check failed)";
+  const parts = [];
+  if (report.host) parts.push(`ssh ${report.host}`);
+  else if (report.transport && report.transport !== "none" && report.transport !== "ssh") parts.push(`${report.transport} remote`);
+  if (report.server_alive_interval != null) {
+    const via = report.interval_origin === "command_line" ? report.source
+      : report.source === "ssh_config" ? "ssh config" : `${report.source} → ssh config`;
+    parts.push(`ServerAliveInterval ${report.server_alive_interval} via ${via}`);
+  } else if (report.reason && !(report.transport && report.reason === `${report.transport}_remote`)) {
+    parts.push(report.reason);
+  }
+  const fixed = report.fix?.applied
+    ? (report.fix.verified ? " — fixed: set core.sshCommand (local)" : " — fix applied but NOT verified")
+    : "";
+  return `git transport: ${report.status}${parts.length ? ` (${parts.join(", ")})` : ""}${fixed}`;
+}

package/src/run.mjs

@@ -11,7 +11,7 @@ import { stackLeaseIdFromEnv, withStackLeaseCorrelation } from "./stack-lease-co
 import { mkdir, readFile, writeFile, chmod, unlink, stat, rename } from "node:fs/promises";
 import { dirname, join } from "node:path";
 import { homedir } from "node:os";
-import { spawn } from "node:child_process";
+import { execFileSync, spawn } from "node:child_process";
 import { fileURLToPath } from "node:url";
 import { performance } from "node:perf_hooks";
 import { callToolJson } from "./api.mjs";
@@ -26,7 +26,7 @@ import { deliverExecutionEvent } from "./telemetry-delivery.mjs";
 import { attestTelemetryCredential, loadTelemetryIdentity } from "./telemetry-config.mjs";
 import { VERSION } from "./version.mjs";
 import {
-  TERMINAL_RETRY_BUDGET_MS, DELIVERY_CALL_TIMEOUT_MS, callWithContextIdentity, classifyTerminalUpdateFailure,
+  TERMINAL_RETRY_BUDGET_MS, DELIVERY_CALL_TIMEOUT_MS, callWithContextIdentity, classifyTerminalUpdateFailure, contextServerUrl,
   ensureRunDelivery, parkedRecord, runDelivery, terminalUpdateAccepted,
 } from "./run-delivery.mjs";
 
@@ -221,6 +221,154 @@ export function commandHash(command) { return createHash("sha256").update(JSON.s
 export function environmentHash(cwd, environment) { return createHash("sha256").update(`${cwd}\0${environment}`).digest("hex"); }
 export function receiptPath(runId) { return join(homedir(), ".botbuddy", "command-runs", `${runId}.receipt.json`); }
 export function contextPath(runId) { return join(homedir(), ".botbuddy", "command-runs", `${runId}.context.json`); }
+
+// A command receipt is evidence about one checkout revision, not a claim that
+// its working tree was clean.  Resolving this once at launch lets recovery
+// distinguish a stale callback from an unrelated later command without ever
+// returning the command line itself.
+export function sourceSha(cwd, { exec = execFileSync } = {}) {
+  try {
+    const sha = String(exec("git", ["rev-parse", "HEAD"], { cwd, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] })).trim();
+    return /^[0-9a-f]{40,64}$/i.test(sha) ? sha.toLowerCase() : null;
+  } catch { return null; }
+}
+
+const TERMINAL_COMMAND_STATUSES = new Set(["success", "failure", "cancelled", "timed_out", "owner_lost"]);
+const TERMINAL_REMOTE_STATUSES = new Set(["succeeded", "failed", "cancelled", "timed_out", "owner_lost", "invalidated"]);
+const REMOTE_STATUS_FOR_COMMAND_STATUS = Object.freeze({
+  success: "succeeded",
+  failure: "failed",
+  cancelled: "cancelled",
+  timed_out: "timed_out",
+  owner_lost: "owner_lost",
+});
+
+function parseOwnedRunFile(raw, runId) {
+  try {
+    const value = JSON.parse(raw);
+    return value && value.run_id === runId ? value : null;
+  } catch { return null; }
+}
+
+function freshContext(context, now) {
+  const launchedAt = Date.parse(context?.launched_at ?? "");
+  const timeoutMs = Number(context?.timeout_seconds) * 1_000;
+  return Number.isFinite(launchedAt) && Number.isFinite(timeoutMs) && timeoutMs > 0
+    && now <= launchedAt + timeoutMs + TIMEOUT_GRACE_MS + 60_000;
+}
+
+function publicRemoteSummary(result) {
+  if (!result?.ok || result.isError || !result.data || typeof result.data !== "object") return { state: "unavailable" };
+  const status = typeof result.data.status === "string" ? result.data.status : null;
+  return {
+    state: status ? "available" : "unavailable",
+    ...(status ? { status } : {}),
+    ...(typeof result.data.exit_code === "number" ? { exit_code: result.data.exit_code } : {}),
+    ...(typeof result.data.ended_at === "string" ? { ended_at: result.data.ended_at } : {}),
+  };
+}
+
+function terminalOutcomesAgree(receipt, remote) {
+  if (!receipt || remote.state !== "available") return false;
+  if (REMOTE_STATUS_FOR_COMMAND_STATUS[receipt.status] !== remote.status) return false;
+  // A missing exit code is meaningful for cancellation, timeout, and
+  // owner-loss. When both sides do have one, a disagreement is never hidden.
+  return typeof receipt.exit_code !== "number" || typeof remote.exit_code !== "number"
+    || receipt.exit_code === remote.exit_code;
+}
+
+// Reconcile only evidence the current OS user and owning BotBuddy agent can
+// read.  This is intentionally advisory: an inspector must never terminate a
+// worker, replay a callback, or make a retry safe merely by observing a file.
+export async function inspectRun(runId, {
+  call = callToolJson,
+  read = readFile,
+  now = Date.now(),
+  processAlive = workerProcessGroupAlive,
+  receiptFile = receiptPath,
+  contextFile = contextPath,
+} = {}) {
+  if (typeof runId !== "string" || !runId.trim()) {
+    return { schema_version: RUN_SCHEMA_VERSION, classification: "rejected", rerun_safe: false, cancellation_safe: false, error: "run_id_required" };
+  }
+  const id = runId.trim();
+  const [receiptRaw, contextRaw] = await Promise.all([
+    read(receiptFile(id), "utf8").catch(() => null),
+    read(contextFile(id), "utf8").catch(() => null),
+  ]);
+  const receipt = typeof receiptRaw === "string" ? parseOwnedRunFile(receiptRaw, id) : null;
+  const context = typeof contextRaw === "string" ? parseOwnedRunFile(contextRaw, id) : null;
+  // A durable run belongs to the agent that launched it. Prefer its sealed
+  // session identity; older contexts must use a current worktree session and
+  // never silently fall back to an unrelated durable machine credential.
+  const remoteResult = await callWithContextIdentity(context, call)("get_command_run", { run_id: id }, {
+    ...(context ? { serverUrl: contextServerUrl(context) } : {}),
+  }).catch(() => null);
+  const remote = publicRemoteSummary(remoteResult);
+  const receiptTerminal = Boolean(receipt && TERMINAL_COMMAND_STATUSES.has(receipt.status));
+  const receiptFingerprint = receipt && typeof receipt.command_hash === "string" && /^[a-f0-9]{64}$/i.test(receipt.command_hash)
+    && typeof receipt.source_sha === "string" && /^[a-f0-9]{40,64}$/i.test(receipt.source_sha);
+  const fingerprintMismatch = Boolean(context && (
+    (context.command_hash && context.command_hash !== receipt?.command_hash)
+    || (context.source_sha && context.source_sha !== receipt?.source_sha)
+  ));
+  const contextMatchesReceipt = !fingerprintMismatch;
+  const sourceBound = Boolean(receiptTerminal && receiptFingerprint && contextMatchesReceipt);
+
+  if (receiptTerminal) {
+    // A context that identifies a different command/revision must never be
+    // promoted to completed evidence, even if its receipt is terminal.
+    if (fingerprintMismatch) {
+      return {
+        schema_version: RUN_SCHEMA_VERSION,
+        run_id: id,
+        classification: "unknown",
+        rerun_safe: false,
+        cancellation_safe: false,
+        source_bound: false,
+        local: { status: null, exit_code: null },
+        remote,
+      };
+    }
+    const remoteTerminal = remote.state === "available" && TERMINAL_REMOTE_STATUSES.has(remote.status);
+    const outcomesAgree = remoteTerminal && terminalOutcomesAgree(receipt, remote);
+    return {
+      schema_version: RUN_SCHEMA_VERSION,
+      run_id: id,
+      classification: outcomesAgree ? "completed" : remoteTerminal ? "completed_locally_remote_conflict" : remote.status === "registered" || remote.status === "running" || remote.status === "approval_required" ? "completed_locally_remote_stale" : "completed_locally_remote_unknown",
+      rerun_safe: false,
+      cancellation_safe: false,
+      source_bound: sourceBound,
+      local: { status: receipt.status, exit_code: receipt.exit_code ?? null },
+      remote,
+    };
+  }
+
+  const pids = [context?.worker_pid, context?.workload_pid].filter((pid) => Number.isInteger(pid) && pid > 0);
+  if (context && freshContext(context, now) && pids.some((pid) => processAlive(pid))) {
+    return {
+      schema_version: RUN_SCHEMA_VERSION,
+      run_id: id,
+      classification: "running",
+      rerun_safe: false,
+      cancellation_safe: false,
+      source_bound: false,
+      local: { status: null, exit_code: null },
+      remote,
+    };
+  }
+
+  return {
+    schema_version: RUN_SCHEMA_VERSION,
+    run_id: id,
+    classification: "unknown",
+    rerun_safe: false,
+    cancellation_safe: false,
+    source_bound: false,
+    local: { status: null, exit_code: null },
+    remote,
+  };
+}
 function cancellationPath(contextFile) { return `${contextFile}.cancelled`; }
 
 async function markCancellation(contextFile, runId) {
@@ -250,6 +398,8 @@ async function preWorkloadCancellationReceipt(context) {
     ended_at: now,
     exit_code: null,
     signal: "SIGTERM",
+    command_hash: context.command_hash ?? commandHash(context.command ?? []),
+    source_sha: context.source_sha ?? null,
     recovery_command: null,
     bounded_log: "",
     output_characters: 0,
@@ -347,7 +497,7 @@ function rejectedSessionReceipt(error, runId) {
 
 export async function launchRun(argv, {
   cwd = process.cwd(), spawnImpl = spawn, call = null, childEnv = null, testRun = null,
-  resolveCredential = null, renewCredential = selfHealAgentSession, env = process.env,
+  resolveCredential = null, renewCredential = selfHealAgentSession, env = process.env, getSourceSha = sourceSha,
 } = {}) {
   const parsed = parseRunArgs(argv, env);
   let managedCredential = null;
@@ -376,12 +526,14 @@ export async function launchRun(argv, {
   const effectiveCall = (t, a) => (call ?? callToolJson)(t, a,
     opts.sessionToken ? { auth: { "x-agent-api-key": opts.sessionToken } } : {});
   const runId = randomUUID();
+  const commandFingerprint = commandHash(command);
+  const launchSourceSha = getSourceSha(cwd);
   const registerArgs = () => ({
     // Omit session_id entirely when only a token is present — the backend derives
     // it. A plain id is still sent (and honoured) when supplied.
     ...(opts.sessionId ? { session_id: opts.sessionId } : {}),
     run_id: runId, tool_category: opts.category,
-    command_hash: commandHash(command), environment_hash: environmentHash(cwd, opts.environment),
+    command_hash: commandFingerprint, ...(launchSourceSha ? { source_sha: launchSourceSha } : {}), environment_hash: environmentHash(cwd, opts.environment),
     environment: opts.environment, command_kind: opts.kind, expected_duration_seconds: opts.expectedDuration,
     rerun_reason: opts.rerunReason,
   });
@@ -411,7 +563,7 @@ export async function launchRun(argv, {
   // every callback is attributable to the same agent. It deliberately stays
   // outside child_env, receipts, and the workload's process environment.
   const knownSession = opts.sessionId ?? managedCredential?.identity?.sessionId ?? managedCredential?.sessionId;
-  await writeJson(context, { schema_version: RUN_SCHEMA_VERSION, context_path: context, run_id: runId, run_credential: registration.data.run_credential, receipt_upload: registration.data.receipt_upload, command, cwd, timeout_seconds: opts.timeout, receipt_path: receipt, launched_at: new Date().toISOString(), server_url: SERVER_URL,...(opts.sessionToken ? { callback_session_token: opts.sessionToken } : {}), ...(knownSession ? { callback_session_id: knownSession } : {}), ...(childEnv && Object.keys(childEnv).length ? { child_env: childEnv } : {}), ...(testRun ? { test_run: testRun } : {}) });
+  await writeJson(context, { schema_version: RUN_SCHEMA_VERSION, context_path: context, run_id: runId, run_credential: registration.data.run_credential, receipt_upload: registration.data.receipt_upload, command, command_hash: commandFingerprint, source_sha: launchSourceSha, cwd, timeout_seconds: opts.timeout, receipt_path: receipt, launched_at: new Date().toISOString(), server_url: SERVER_URL, ...(opts.sessionToken ? { callback_session_token: opts.sessionToken } : {}), ...(knownSession ? { callback_session_id: knownSession } : {}), ...(childEnv && Object.keys(childEnv).length ? { child_env: childEnv } : {}), ...(testRun ? { test_run: testRun } : {}) });
   const [file, args] = workerInvocation(context);
   try {
     const worker = spawnImpl(file, args, { detached: true, stdio: "ignore", windowsHide: true });
@@ -804,7 +956,7 @@ export async function cancelRun(runId, {
 async function finalize(context, state, call, retry = {}) {
   const boundedLog = String(state.output ?? "").slice(-8192);
   const outputCharacters = state.outputCharacters ?? String(state.output ?? "").length;
-  const receipt = { schema_version: RUN_SCHEMA_VERSION, run_id: context.run_id, status: state.status, started_at: state.startedAt, ended_at: state.endedAt, exit_code: state.exitCode, signal: state.signal, recovery_command: state.status === "failure" ? `botbuddy run --session-id <new-session-id> --environment local -- ${context.command.map((x) => JSON.stringify(x)).join(" ")}` : null, bounded_log: boundedLog, output_characters: outputCharacters, reason: state.reason ?? null };
+  const receipt = { schema_version: RUN_SCHEMA_VERSION, run_id: context.run_id, status: state.status, started_at: state.startedAt, ended_at: state.endedAt, exit_code: state.exitCode, signal: state.signal, command_hash: context.command_hash ?? commandHash(context.command ?? []), source_sha: context.source_sha ?? null, recovery_command: state.status === "failure" ? `botbuddy run --session-id <new-session-id> --environment local -- ${context.command.map((x) => JSON.stringify(x)).join(" ")}` : null, bounded_log: boundedLog, output_characters: outputCharacters, reason: state.reason ?? null };
   await writeJson(context.receipt_path, receipt);
   const bytes = await stat(context.receipt_path);
   const sha256 = createHash("sha256").update(await readFile(context.receipt_path)).digest("hex");
@@ -882,6 +1034,12 @@ export async function cmdRun(args) {
     if (args.includes("--json")) oneLine({ schema_version: RUN_SCHEMA_VERSION, ...result }, false);
     return;
   }
+  if (args[0] === "inspect") {
+    const result = await inspectRun(args[1] ?? "");
+    oneLine(result, false);
+    process.exitCode = result.classification === "rejected" ? EXIT.INVALID : EXIT.OK;
+    return;
+  }
   if (args[0] === "cancel") {
     const result = await cancelRun(args[1] ?? "");
     oneLine(result.receipt, false);
@@ -889,7 +1047,7 @@ export async function cmdRun(args) {
     return;
   }
   if (args[0] === "help" || args[0] === "--help") {
-    console.log("botbuddy run --session-id <id> --environment <local|preview|staging|production|none> [--timeout <sec>] [--rerun-reason <json>] -- <command> [args...]\nbotbuddy run --foreground --kind <test|wait|browser|ci|hook|stack> --environment <local|preview|staging|production|none> -- <command> [args...]\nbotbuddy run cancel <run_id>\n  --agent-session-token <token>  session credential (env $BOTBUDDY_AGENT_SESSION_TOKEN); --agent-key / --session-token are one-release legacy aliases");
+    console.log("botbuddy run --session-id <id> --environment <local|preview|staging|production|none> [--timeout <sec>] [--rerun-reason <json>] -- <command> [args...]\nbotbuddy run --foreground --kind <test|wait|browser|ci|hook|stack> --environment <local|preview|staging|production|none> -- <command> [args...]\nbotbuddy run inspect <run_id>\nbotbuddy run cancel <run_id>\n  --agent-session-token <token>  session credential (env $BOTBUDDY_AGENT_SESSION_TOKEN); --agent-key / --session-token are one-release legacy aliases");
     return;
   }
   // BOT-1701 (AC-6): one stderr nudge when a tier-3 legacy flag/env alias is used