@botbuddy/cli 1.67.0 → 1.68.0

package/daemon-release/darwin-arm64.json

@@ -1,7 +1,7 @@
 {
-  "release_version": "1.67.0",
-  "source_commit": "268168df0f1ca0c6e45a7650488ecc1e24e06401",
-  "source_sha256": "28a9fb83409d1d081474ef61a1a8f025837c54284d5809b4d9ebec87c0ee4e7d",
+  "release_version": "1.68.0",
+  "source_commit": "dacd86b04baacbb89711e0a72c52ee036fd17721",
+  "source_sha256": "f857817d22c1d475d9b53f86b0ea73f2e6e0af18f306b1d079b21cc844413260",
   "target": "darwin-arm64",
-  "sha256": "f75345368910de3b008e4796e6469c60e9026b9db732baadb14fa994b2982cf1"
+  "sha256": "3a9d33c8cfd04bd4844025552464c02b55399fab1c5352fdc86799a62c8bec5e"
 }

package/daemon-release/linux-x64.json

@@ -1,7 +1,7 @@
 {
-  "release_version": "1.67.0",
-  "source_commit": "268168df0f1ca0c6e45a7650488ecc1e24e06401",
-  "source_sha256": "28a9fb83409d1d081474ef61a1a8f025837c54284d5809b4d9ebec87c0ee4e7d",
+  "release_version": "1.68.0",
+  "source_commit": "dacd86b04baacbb89711e0a72c52ee036fd17721",
+  "source_sha256": "f857817d22c1d475d9b53f86b0ea73f2e6e0af18f306b1d079b21cc844413260",
   "target": "linux-x64",
-  "sha256": "9c1fb4e157e1b86f84b7efda1a3ab25f9e869a9d09a1c30093c3ef4dc67e928f"
+  "sha256": "15fde9d3dd872809e9cc0aead517e7aef9a5398af55b4543269cdd90a6ffc96b"
 }

package/daemon-release/manifest.json

@@ -1,21 +1,21 @@
 {
   "schema_version": 1,
-  "release_version": "1.67.0",
-  "source_commit": "268168df0f1ca0c6e45a7650488ecc1e24e06401",
-  "source_sha256": "28a9fb83409d1d081474ef61a1a8f025837c54284d5809b4d9ebec87c0ee4e7d",
+  "release_version": "1.68.0",
+  "source_commit": "dacd86b04baacbb89711e0a72c52ee036fd17721",
+  "source_sha256": "f857817d22c1d475d9b53f86b0ea73f2e6e0af18f306b1d079b21cc844413260",
   "targets": {
     "darwin-arm64": {
       "goos": "darwin",
       "goarch": "arm64",
       "binary": "daemon/bin/darwin-arm64/botbuddy-daemon",
-      "sha256": "f75345368910de3b008e4796e6469c60e9026b9db732baadb14fa994b2982cf1",
+      "sha256": "3a9d33c8cfd04bd4844025552464c02b55399fab1c5352fdc86799a62c8bec5e",
       "mode": "0755"
     },
     "linux-x64": {
       "goos": "linux",
       "goarch": "amd64",
       "binary": "daemon/bin/linux-x64/botbuddy-daemon",
-      "sha256": "9c1fb4e157e1b86f84b7efda1a3ab25f9e869a9d09a1c30093c3ef4dc67e928f",
+      "sha256": "15fde9d3dd872809e9cc0aead517e7aef9a5398af55b4543269cdd90a6ffc96b",
       "mode": "0755"
     }
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@botbuddy/cli",
-  "version": "1.67.0",
+  "version": "1.68.0",
   "description": "BotBuddy — Swarm coordination CLI for multi-agent workflows",
   "type": "module",
   "bin": {
@@ -20,7 +20,12 @@
     "daemon/",
     "daemon-release/",
     "src/",
-    "!src/**/*.test.mjs"
+    "!src/**/*.test.mjs",
+    "claude-plugin/.claude-plugin/",
+    "claude-plugin/bb-status/.claude-plugin/",
+    "claude-plugin/bb-status/hooks/hooks.json",
+    "claude-plugin/bb-status/hooks/register.js",
+    "claude-plugin/bb-status/README.md"
   ],
   "keywords": [
     "mcp",

package/src/commands.mjs

@@ -20,6 +20,7 @@ import { cmdTest } from "./test-lane.mjs";
 import { cmdEvidence } from "./evidence.mjs";
 import { cmdFeedback } from "./feedback.mjs";
 import { cmdReleaseNotes } from "./release-notes.mjs";
+import { cmdStatusBand, installStatusBand, statusBandLine } from "./status-band.mjs";
 import { runWait } from "./wait.mjs";
 import { SETUP_BLOCK } from "./setup-block.mjs";
 import { green, red, cyan, dim, bold, die } from "./utils.mjs";
@@ -64,7 +65,7 @@ export function shouldCheckForUpdates(argv) {
 export const LOCAL_HELP_COMMANDS = Object.freeze([
   "wait", "stack", "pw", "docker", "run", "mcp", "login", "setup", "doctor", "host",
   "staging-pool", "daemon", "evidence", "feedback", "usage", "telemetry", "allocation",
-  "release-notes",
+  "release-notes", "status-band",
 ]);
 const HELP_WORDS = new Set(["help", "--help", "-h"]);
 
@@ -147,6 +148,8 @@ export async function run(argv, {
     case "feedback": return cmdFeedback(args);
     // BOT-3156: governed release notes (submit one note through submit_release_note).
     case "release-notes": return cmdReleaseNotes(args);
+    // BOT-3152: the bb-status band's host side (read/relay) and its Claude Code install.
+    case "status-band": return cmdStatusBand(args);
     case "test-ingest": return cmdTestIngest(args);
     case "wait": return runWait(args);
     case "pw": return runPw(args);
@@ -335,6 +338,8 @@ ${bold("EVIDENCE")}  (${cyan("bb help evidence")})
                               Prepare or send a BotBuddy issue report
   release-notes submit <note.json>
                               Submit one release note for your tenant (stored as draft)
+  status-band install         Install the bb-status band into Claude Code (bb setup does it)
+  status-band read|relay      The band's own reads and live wake (run by the mod)
   evidence require <file>    Record an exact-head evidence disposition → botbuddy/ready
   evidence publish <file>    Publish a local evidence statement → botbuddy/ready check-run
 
@@ -845,6 +850,8 @@ export async function cmdSetup(args, {
   selfHeal = selfHealAgentSession,
   callerResolver = resolveCaller,
   usageAgent = installUsageAgent,
+  // BOT-3152: setup also installs the bb-status band into Claude Code, once.
+  statusBand = installStatusBand,
   // BOT-2599: setup also gives this clone's SSH push transport a keepalive.
   gitTransport = async (opts) => checkGitTransport(opts),
   cwd = process.cwd(),
@@ -959,6 +966,7 @@ export async function cmdSetup(args, {
     }
     log(`bb setup: ${tenant} is ready (${session.source} worktree session). Run bb wait '<condition>'.`);
     await reportGitTransport(gitTransport, { cwd, env, log });
+    await reportStatusBand(statusBand, { log });
     await reportUsageAgent(usageAgent, { cwd, log });
     return 0;
   } catch (error) {
@@ -967,6 +975,13 @@ export async function cmdSetup(args, {
   }
 }
 
+// BOT-3152: never fails setup — the worktree session is ready either way.
+async function reportStatusBand(statusBand, { log }) {
+  let result;
+  try { result = await statusBand(); } catch (error) { result = { status: "failed", reason: error?.code ?? "install_failed" }; }
+  log(`bb setup: ${statusBandLine(result)}`);
+}
+
 // BOT-1021: setup also (re)installs the daily usage sweep. Never fails setup —
 // the worktree session is ready either way; the line says what happened.
 async function reportUsageAgent(usageAgent, { cwd, log }) {

package/src/status-band-read.mjs

@@ -0,0 +1,501 @@
+// BOT-2644 / BOT-3152. Read-only host adapter (`bb status-band read`), run from the
+// installed CLI. Credentials stay in this process, never in the mod.
+import { open, readFile, realpath } from "node:fs/promises";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { join } from "node:path";
+const execFileAsync = promisify(execFile);
+const UUID =
+  /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+const TICKET = /^BOT-[1-9]\d*$/;
+// The repo's committed binding picks the tenant; each tenant owns one key prefix.
+const TENANTS = { botbuddy: "BOT", "supply-guard": "ENT" };
+const MCP = "https://api.bot-buddy.ai/functions/v1/mcp-server/tools/";
+const UUID_LOWER = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+const LINEAR_PROJECT_URL = /^https:\/\/linear\.app\/[a-z0-9-]{1,64}\/project\/[a-z0-9-]{1,200}$/;
+const PROJECT_IDENTIFIER = /^P-[A-Z][A-Z0-9]{1,9}-[1-9]\d{0,5}$/;
+const PROJECT_STATES = ["backlog", "planned", "started", "paused", "completed", "canceled"];
+const REPO = /^[A-Za-z0-9_.-]{1,100}\/[A-Za-z0-9_.-]{1,100}$/;
+// Linear state type or BB work-item stage → the band's status word.
+const STATUS = {
+  started: "In Progress",
+  working: "In Progress",
+  review: "In Review",
+  completed: "Done",
+  complete: "Done",
+  canceled: "Canceled",
+  unstarted: "Todo",
+  backlog: "Backlog",
+  planned: "Todo",
+  triage: "Triage",
+};
+const QUERY = `query BbClaudeStatus($id: String!) {
+ organization { urlKey }
+ issue(id: $id) {
+  id identifier title url team { key } state { name type }
+  inverseRelations(first: 100) {
+   nodes { type issue { identifier title url team { key } state { name type } } }
+   pageInfo { hasNextPage endCursor }
+  }
+ }
+}`;
+// A review-round count from BB, or null when BB has none for the PR.
+function reviewCount(v) {
+  return Number.isSafeInteger(v) && v >= 0 && v <= 999 ? v : null;
+}
+// BOT-3152 AC-2: the web top bar's Staging chip (top_bar_signals): red while the
+// tenant has an open staging incident; null when BB did not say (never green).
+function stagingOf(own) {
+  const st = own?.staging;
+  if (!st || typeof st !== "object" || typeof st.configured !== "boolean") return null;
+  const since = typeof st.open_since === "string" && Number.isFinite(Date.parse(st.open_since)) ? new Date(st.open_since).toISOString() : null;
+  return { configured: st.configured, red: st.configured && since !== null, since: st.configured ? since : null };
+}
+function refuse(code) {
+  throw new Error(code);
+}
+function label(value, max = 240) {
+  if (
+    typeof value !== "string" ||
+    !value.trim() ||
+    value.length > max ||
+    /[\u0000-\u001f\u007f\u202a-\u202e\u2066-\u2069]/u.test(value)
+  )
+    refuse("invalid_response");
+  return value.trim();
+}
+function issueLink(value, key) {
+  let url;
+  try {
+    url = new URL(value);
+  } catch {
+    refuse("unsafe_link");
+  }
+  if (
+    url.protocol !== "https:" ||
+    url.hostname !== "linear.app" ||
+    url.port ||
+    url.username ||
+    url.password ||
+    !new RegExp(`^/botbuddy/issue/${key}(?:/|$)`).test(url.pathname) ||
+    url.search ||
+    url.hash
+  )
+    refuse("unsafe_link");
+  return url.href;
+}
+// A display string from BB, or null: never throws, so one odd title cannot
+// sink the snapshot the way a bad identity or link must.
+function safeText(value, max = 240) {
+  if (typeof value !== "string") return null;
+  const t = value.trim();
+  if (!t || /[\u0000-\u001f\u007f\u202a-\u202e\u2066-\u2069]/u.test(t)) return null;
+  return t.length > max ? t.slice(0, max - 1) + "…" : t;
+}
+async function jsonRequest(url, init, fetchImpl, timeoutMs = 8000) {
+  let response;
+  try {
+    response = await fetchImpl(url, {
+      ...init,
+      redirect: "error",
+      signal: AbortSignal.timeout(timeoutMs),
+    });
+  } catch {
+    refuse("source_unreachable");
+  }
+  if (!response.ok)
+    refuse(
+      response.status === 401 || response.status === 403
+        ? "source_unauthorized"
+        : "source_unavailable",
+    );
+  let body;
+  try {
+    body = await response.json();
+  } catch {
+    refuse("invalid_response");
+  }
+  if (body?.errors || body?.error || body?.isError) refuse("source_rejected");
+  return body;
+}
+async function readSession(cwd) {
+  const handle = await open(join(cwd, ".botbuddy/agent-state.json"), "r").catch(
+    () => refuse("session_missing"),
+  );
+  try {
+    const info = await handle.stat();
+    if ((info.mode & 0o077) !== 0 || info.size > 65536)
+      refuse("session_file_unsafe");
+    try {
+      return JSON.parse(await handle.readFile("utf8"));
+    } catch {
+      refuse("session_invalid");
+    }
+  } finally {
+    await handle.close();
+  }
+}
+export async function readStatus({
+  cwd,
+  harnessSessionId,
+  ticketId,
+  linearKey,
+  // BOT-3135: a relay wake skips the slow epic read; the mod keeps the last epic.
+  skipEpic = false,
+  now = () => Date.now(),
+  fetchImpl = fetch,
+  branchReader = async (path) =>
+    (
+      await execFileAsync("git", ["branch", "--show-current"], { cwd: path })
+    ).stdout.trim(),
+}) {
+  if (!UUID.test(harnessSessionId)) refuse("harness_session_missing");
+  const root = await realpath(cwd);
+  let binding;
+  try {
+    binding = JSON.parse(
+      await readFile(join(root, ".botbuddy-agent.json"), "utf8"),
+    );
+  } catch {
+    refuse("repo_binding_missing");
+  }
+  if (binding.schema_version !== 1 || !Object.hasOwn(TENANTS, binding.tenant))
+    refuse("tenant_mismatch");
+  const tenant = binding.tenant;
+  const prefix = TENANTS[tenant];
+  // Linear is read for the BotBuddy workspace only (exact state + blockers);
+  // SupplyGuard status comes from BB's own synced copy of its tickets.
+  const useLinear = tenant === "botbuddy";
+  if (useLinear && (typeof linearKey !== "string" || !linearKey.trim()))
+    refuse("linear_key_missing");
+  const state = await readSession(root);
+  if (
+    state.schema_version !== 1 ||
+    state.harness_session_id?.toLowerCase() !== harnessSessionId.toLowerCase()
+  )
+    refuse("session_mismatch");
+  if (
+    state.tenant !== tenant ||
+    !UUID.test(state.agent_id) ||
+    !UUID.test(state.session_id)
+  )
+    refuse("session_invalid");
+  if (state.worktree !== root) refuse("worktree_mismatch");
+  if (!(Date.parse(state.expires_at) > now())) refuse("session_expired");
+  if (
+    typeof state.agent_session_token !== "string" ||
+    !/^bb_(?:agent|sess)_[0-9a-f]{64}$/.test(state.agent_session_token)
+  )
+    refuse("session_invalid");
+  const branch = label(await branchReader(root));
+  const keyPattern = new RegExp(`^${prefix}-[1-9]\\d*$`);
+  const branchTicket = branch.match(
+    new RegExp(`(?:^|/)${prefix.toLowerCase()}-([1-9]\\d*)(?:-|$)`, "i"),
+  );
+  const branchKeys = branchTicket ? [`${prefix}-${branchTicket[1]}`] : [];
+  // `/bb-status live KEY…` picks the tickets explicitly.
+  const selected = ticketId === undefined ? null : [...new Set(String(ticketId).split(","))];
+  if (selected && (!selected.length || selected.length > 5 || !selected.every((k) => keyPattern.test(k))))
+    refuse("ticket_missing");
+  const identity = await jsonRequest(
+    "https://api.bot-buddy.ai/functions/v1/mcp-server/tools/whoami",
+    {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        "x-agent-api-key": state.agent_session_token,
+      },
+      body: "{}",
+    },
+    fetchImpl,
+  );
+  if (identity.tenant_id !== tenant) refuse("tenant_mismatch");
+  if (
+    identity.agent?.id !== state.agent_id ||
+    identity.credential_kind !== "agent_session"
+  )
+    refuse("agent_mismatch");
+  const bb = (name, args, timeoutMs) =>
+    jsonRequest(
+      MCP + name,
+      {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          "x-agent-api-key": state.agent_session_token,
+        },
+        body: JSON.stringify(args),
+      },
+      fetchImpl,
+      timeoutMs,
+    ).catch(() => null);
+  // BOT-3136: what this session registered with BB comes first. A reply for
+  // another session or tenant is ignored, and an empty one falls back to the
+  // branch key, which the snapshot labels as a guess.
+  // BOT-3152 (review on #1616): read even with an explicit selection, because the
+  // tenant's staging state comes from it whatever supplies the tickets.
+  const own = await bb("get_session_status", {});
+  const ownOk =
+    own?.session_id === state.session_id && own?.tenant_id === tenant && Array.isArray(own?.tickets);
+  const sessionKeys = ownOk && !selected
+    ? [...new Set(own.tickets.map((x) => String(x?.key || "").toUpperCase()).filter((k) => keyPattern.test(k)))].slice(0, 5)
+    : [];
+  const bindingKind = selected ? "selected" : sessionKeys.length ? "session" : "branch";
+  const keys = selected ?? (sessionKeys.length ? sessionKeys : branchKeys);
+  if (!keys.length) refuse("ticket_missing");
+  const key = keys[0];
+  const useSession = bindingKind === "session";
+  // The Linear ticket read and the BB reads are independent, so they run
+  // together; a refused BB read blanks only its line. The epic read is the slow
+  // one (~7 s live), so it gets a longer budget, and a relay wake skips it.
+  const linearGraph = useLinear
+    ? jsonRequest(
+        "https://api.linear.app/graphql",
+        {
+          method: "POST",
+          headers: { "Content-Type": "application/json", Authorization: linearKey },
+          body: JSON.stringify({ query: QUERY, variables: { id: key } }),
+        },
+        fetchImpl,
+      )
+    : null;
+  linearGraph?.catch(() => {});
+  // A session-bound band needs none of the broad reads (BOT-3136 AC-2).
+  const [work, prState, epicHealth] = useSession
+    ? [null, null, null]
+    : await Promise.all([
+        bb("list_work_items", { entity: "ticket", limit: 200 }),
+        bb("get_pr_state", { include_closed: true }),
+        skipEpic ? null : bb("get_epic_health", { team_key: prefix }, 15000),
+      ]);
+  let linearTicket = null;
+  const blockers = [];
+  if (useLinear) {
+  const graph = await linearGraph;
+  const issue = graph?.data?.issue;
+  if (
+    graph?.data?.organization?.urlKey !== "botbuddy" ||
+    issue?.team?.key !== "BOT" ||
+    issue?.identifier !== key
+  )
+    refuse("ticket_scope_mismatch");
+  const relations = issue.inverseRelations;
+  if (
+    relations?.pageInfo?.hasNextPage !== false ||
+    !Array.isArray(relations.nodes)
+  )
+    refuse("blockers_incomplete");
+  for (const relation of relations.nodes) {
+    if (relation.type !== "blocks") continue;
+    const blocker = relation.issue;
+    if (
+      !blocker ||
+      !TICKET.test(blocker.identifier) ||
+      blocker.team?.key !== "BOT" ||
+      !blocker.state?.type
+    )
+      refuse("blockers_incomplete");
+    if (["completed", "canceled"].includes(blocker.state.type)) continue;
+    blockers.push({
+      key: blocker.identifier,
+      title: label(blocker.title),
+      status: label(blocker.state.name),
+      url: issueLink(blocker.url, blocker.identifier),
+    });
+  }
+  linearTicket = {
+    key,
+    title: label(issue.title),
+    status: label(issue.state?.name),
+    url: issueLink(issue.url, key),
+  };
+  }
+  const epics = Array.isArray(epicHealth?.epics) ? epicHealth.epics : [];
+  const workItems = Array.isArray(work?.items) ? work.items : [];
+  const fromBb = (k) => {
+    if (useSession) {
+      const t = own.tickets.find((x) => String(x?.key || "").toUpperCase() === k);
+      return t ? { title: t.title, status: STATUS[t.state_type] || (typeof t.state === "string" ? t.state : null) } : null;
+    }
+    const item = workItems.find((w) => w?.kind === "ticket" && w.ticket === k);
+    if (item) return { title: item.title, status: STATUS[item.stage] };
+    for (const e of epics) {
+      const c = (e?.children || []).find((x) => x?.external_id === k);
+      if (c) return { title: c.title, status: STATUS[c.state_type] };
+    }
+    return null;
+  };
+  const tickets = keys.map((k) => {
+    if (linearTicket && k === key)
+      return { key: k, title: linearTicket.title, status: linearTicket.status };
+    const found = fromBb(k);
+    return {
+      key: k,
+      title: found ? safeText(found.title) || "Not in BB yet" : "Not in BB yet",
+      status: found?.status || "Unknown",
+    };
+  });
+  // PRs whose head is this worktree's branch, or whose title or branch names
+  // one of the session's tickets as a whole key (BOT-77, never BOT-770).
+  const keyRes = keys.map((k) => new RegExp(`(?:^|[^A-Za-z0-9])${k}(?![0-9])`, "i"));
+  const mentions = (p) =>
+    keyRes.some((re) => re.test(String(p?.title || "")) || re.test(String(p?.headRefName || "")));
+  // Newest first as BB returns them.
+  const prs = useSession
+    ? (Array.isArray(own.prs) ? own.prs : [])
+        .filter((p) => REPO.test(p?.repo) && Number.isSafeInteger(p?.number) && p.number > 0)
+        .slice(0, 5)
+        .map((p) => ({
+          repo: p.repo,
+          number: p.number,
+          title: safeText(p.title) || "Untitled PR",
+          state: p.state === "draft" || (p.is_draft && p.state === "open") ? "draft" : ["open", "merged", "closed"].includes(p.state) ? p.state : "open",
+          conflict: false,
+          // BOT-3152 AC-3: pr_state.review_rounds, the column get_pr_state returns as reviewRounds.
+          reviews: reviewCount(p.review_rounds),
+        }))
+    : Array.isArray(prState?.prs)
+    ? prState.prs
+        .filter((p) => (p?.headRefName === branch || mentions(p)) && REPO.test(p.slug) && Number.isSafeInteger(p.number) && p.number > 0)
+        .slice(0, 5)
+        .map((p) => ({
+          repo: p.slug,
+          number: p.number,
+          title: safeText(p.title) || "Untitled PR",
+          // BB reports a draft either as state "draft" or as an open PR flagged isDraft.
+          state: p.state === "draft" || (p.isDraft && p.state === "open") ? "draft" : ["open", "merged", "closed"].includes(p.state) ? p.state : "open",
+          conflict: p.mergeable === "CONFLICTING",
+          reviews: reviewCount(p.reviewRounds),
+        }))
+    : null;
+  // Always one epic: the project of the first ticket, in session order, that
+  // belongs to one.
+  const epicOf = (k) =>
+    epics.find(
+      (e) => UUID_LOWER.test(e?.epic_project_id) && (e.children || []).some((c) => c?.external_id === k),
+    );
+  const owner = useSession ? null : keys.map(epicOf).find(Boolean);
+  let epic = null;
+  const se = useSession ? own.epic : null;
+  if (se && UUID_LOWER.test(se.linear_project_id)) {
+    // As the branch path and v_epics.progress_pct do: canceled children don't count.
+    const total = Math.max(0, (se.children_total ?? 0) - (se.children_canceled ?? 0));
+    const done = Math.min(total, Math.max(0, se.children_completed ?? 0));
+    const slug = String(se.url || "").match(/-([0-9a-f]{8,16})$/);
+    epic = {
+      id: se.linear_project_id,
+      short_id: slug ? slug[1] : se.linear_project_id.slice(0, 8),
+      name: safeText(se.name) || "Untitled epic",
+      state: PROJECT_STATES.includes(se.state) ? se.state : "planned",
+      url: LINEAR_PROJECT_URL.test(se.url || "") ? se.url : null,
+      identifier: PROJECT_IDENTIFIER.test(se.identifier || "") ? se.identifier : null,
+      done,
+      total,
+      percent: Number.isFinite(se.progress_pct) ? Math.max(0, Math.min(100, Math.round(se.progress_pct))) : total ? Math.round((100 * done) / total) : 0,
+    };
+  }
+  if (owner) {
+    const total = Math.max(0, (owner.children_total ?? 0) - (owner.children_canceled ?? 0));
+    const done = Math.min(total, Math.max(0, owner.children_completed ?? 0));
+    const slug = String(owner.epic_url || "").match(/-([0-9a-f]{8,16})$/);
+    epic = {
+      id: owner.epic_project_id,
+      short_id: slug ? slug[1] : owner.epic_project_id.slice(0, 8),
+      name: safeText(owner.epic_name) || "Untitled epic",
+      // Linear's project state drives its icon; percent only fills the wedge.
+      state: PROJECT_STATES.includes(owner.project_state) ? owner.project_state : "planned",
+      // The project's own Linear page, for the band's direct ↗ link.
+      url: LINEAR_PROJECT_URL.test(owner.epic_url || "") ? owner.epic_url : null,
+      identifier: null,
+      done,
+      total,
+      percent: total ? Math.round((100 * done) / total) : 0,
+    };
+  }
+  // A bootstrap/session switch during either network request invalidates this snapshot.
+  const latest = await readSession(root);
+  if (
+    latest.agent_id !== state.agent_id ||
+    latest.session_id !== state.session_id ||
+    latest.harness_session_id !== state.harness_session_id ||
+    latest.session_token_generation !== state.session_token_generation ||
+    latest.agent_session_token !== state.agent_session_token ||
+    latest.tenant !== state.tenant ||
+    latest.worktree !== state.worktree ||
+    !(Date.parse(latest.expires_at) > now()) ||
+    (await branchReader(root)) !== branch
+  )
+    refuse("session_changed");
+  // Linear's project identifier (e.g. P-BOT-39): read directly for BotBuddy,
+  // whose Linear key this adapter holds; Supply Guard waits for BB to sync it.
+  if (epic && !epic.identifier && useLinear) {
+    const found = await jsonRequest(
+      "https://api.linear.app/graphql",
+      {
+        method: "POST",
+        headers: { "Content-Type": "application/json", Authorization: linearKey },
+        body: JSON.stringify({
+          query: "query BbProjectIdentifier($id: String!) { project(id: $id) { identifier } }",
+          variables: { id: epic.id },
+        }),
+      },
+      fetchImpl,
+    ).catch(() => null);
+    const id = found?.data?.project?.identifier;
+    epic.identifier = PROJECT_IDENTIFIER.test(id || "") ? id : null;
+  }
+  return {
+    schema_version: 2,
+    tenant,
+    harness_session_id: harnessSessionId.toLowerCase(),
+    session_id: state.session_id,
+    observed_at: new Date(now()).toISOString(),
+    branch,
+    agent: {
+      id: state.agent_id,
+      name: label(identity.agent.display_name, 100),
+    },
+    ticket: linearTicket || { ...tickets[0], url: null },
+    tickets,
+    prs,
+    epic,
+    ...(skipEpic && !useSession ? { epic_skipped: true } : {}),
+    // BOT-3152 AC-1: the epic source failed, so "no epic" would be a guess.
+    epic_unreadable: useSession ? false : !skipEpic && !Array.isArray(epicHealth?.epics),
+    staging: ownOk ? stagingOf(own) : null,
+    // BOT-3136: where the tickets came from — the registered session, an explicit
+    // pick, or (only when the session registered none) a guess from the branch.
+    binding: bindingKind,
+    blockers: useLinear
+      ? [...new Map(blockers.map((b) => [b.key, b])).values()].sort((a, b) =>
+          a.key.localeCompare(b.key),
+        )
+      : null,
+  };
+}
+export async function main(args, { out = process.stdout, cwd = process.cwd(), env = process.env } = {}) {
+  try {
+    args = [...args];
+    const skipEpic = args.at(-1) === "--skip-epic";
+    if (skipEpic) args.pop();
+    if (args.length !== 2 && args.length !== 4) refuse("invalid_arguments");
+    if (
+      args[0] !== "--harness-session-id" ||
+      (args.length === 4 && args[2] !== "--ticket-id")
+    )
+      refuse("invalid_arguments");
+    const snapshot = await readStatus({
+      cwd,
+      harnessSessionId: args[1],
+      ticketId: args[3],
+      linearKey: env.LINEAR_BB_API_KEY,
+      skipEpic,
+    });
+    out.write(JSON.stringify(snapshot) + "\n");
+    return 0;
+  } catch (error) {
+    const known = /^[a-z_]+$/.test(error?.message ?? "") ? error.message : "status_unavailable";
+    out.write(JSON.stringify({ error: known }) + "\n");
+    return 1;
+  }
+}