@botbuddy/cli 1.67.0 → 1.68.1

package/claude-plugin/bb-status/hooks/register.js

@@ -0,0 +1,992 @@
+// BOT-2644 / BOT-3152. Host code only: no model, prompt, transcript or tool-registration APIs.
+// The host side runs from the installed bb CLI (`bb status-band read|relay`).
+const PANE = "bb-status";
+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;
+let mode = "live";
+let selectedTicket;
+let snapshot = null;
+let errorCode = null;
+let loading = false;
+let generation = 0;
+let currentTime = 0;
+let activity = "Idle";
+let timer;
+// BOT-3135 relay: one `bb wait` child at a time, owned by `relayEpoch`.
+// `relayFault` is why it stopped; while `relayArmed` the band is current.
+let relayEpoch = 0;
+let relayStream = null;
+let relayArmed = false;
+let keptLive = false;
+let relayFault = null;
+let backoffMs = 0;
+const WAKE_READ_GAP_MS = 15000;
+// BOT-3152 AC-4: while no surface draws this session the relay is parked (no
+// child, no server wait); the 5 s display tick un-parks it with one read.
+let parked = false;
+// BOT-3152 AC-5: a repo with no BB binding shows no band at all (the mod is
+// installed once at user scope, so it also loads in unrelated repos).
+let unbound = false;
+const ERRORS = {
+  linear_key_missing:
+    "Export LINEAR_BB_API_KEY to Claude Desktop before using Live.",
+  session_missing: "Connect BB in this worktree before using Live.",
+  harness_session_missing:
+    "This Claude session has no supported session identifier.",
+  session_mismatch:
+    "BB identity belongs to another session. Connect BB for this Claude session.",
+  session_changed: "BB session changed during refresh. Refresh again.",
+  session_invalid: "BB session is invalid. Reconnect BB in this worktree.",
+  session_expired: "BB session expired. Reconnect BB in this worktree.",
+  session_file_unsafe: "BB session file must be private (mode 0600).",
+  tenant_mismatch: "This repo is bound to a tenant BB status does not support.",
+  agent_mismatch:
+    "BB returned a different agent. Reconnect BB for this session.",
+  worktree_mismatch: "BB identity belongs to a different worktree.",
+  ticket_missing: "Use a ticket branch (bot-… or ent-…) or /bb-status live BOT-2644.",
+  ticket_scope_mismatch: "Linear issue or workspace does not match BotBuddy.",
+  blockers_incomplete: "Blocker list is incomplete. Status is unknown.",
+  source_unauthorized:
+    "BB or Linear refused access. Check the existing connection.",
+  source_unreachable: "BB or Linear could not be reached. Refresh to retry.",
+  source_unavailable: "A status source is unavailable. Refresh to retry.",
+  cli_missing: "Install the bb CLI (npm i -g @botbuddy/cli), then run bb setup.",
+  cli_outdated: "Update the bb CLI (bb update) to use this band.",
+};
+function errorText() {
+  return (
+    ERRORS[errorCode] ||
+    "Status unavailable. Check BB and Linear connections, then refresh."
+  );
+}
+function safeLabel(value, max = 240) {
+  return (
+    typeof value === "string" &&
+    value.trim().length > 0 &&
+    value.length <= max &&
+    !/[\u0000-\u001f\u007f\u202a-\u202e\u2066-\u2069]/u.test(value)
+  );
+}
+function safeLink(value, key) {
+  try {
+    const u = new URL(value);
+    return (
+      u.protocol === "https:" &&
+      u.hostname === "linear.app" &&
+      !u.port &&
+      !u.username &&
+      !u.password &&
+      !u.search &&
+      !u.hash &&
+      new RegExp("^/botbuddy/issue/" + key + "(?:/|$)").test(u.pathname)
+    );
+  } catch {
+    return false;
+  }
+}
+// Each tenant owns one key prefix; a snapshot's keys must carry its own.
+const TENANT_PREFIX = { botbuddy: "BOT", "supply-guard": "ENT" };
+const KEY = /^[A-Z]{2,10}-[1-9]\d{0,5}$/;
+const PROJECT = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+const REPO = /^[A-Za-z0-9_.-]{1,100}\/[A-Za-z0-9_.-]{1,100}$/;
+const PR_STATES = ["open", "draft", "merged", "closed"];
+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"];
+function validSnapshot(value, harness, now) {
+  const prefix = TENANT_PREFIX[value?.tenant];
+  const ownKey = (k) => KEY.test(k) && k.startsWith(prefix + "-");
+  if (
+    !value ||
+    value.schema_version !== 2 ||
+    !prefix ||
+    value.harness_session_id !== harness ||
+    !UUID.test(value.session_id) ||
+    !UUID.test(value.agent?.id) ||
+    !safeLabel(value.agent?.name, 100) ||
+    !safeLabel(value.branch) ||
+    !Array.isArray(value.tickets) ||
+    value.tickets.length < 1 ||
+    value.tickets.length > 5 ||
+    !value.tickets.every(
+      (t) => ownKey(t?.key) && safeLabel(t.title) && safeLabel(t.status, 40),
+    ) ||
+    value.ticket?.key !== value.tickets[0].key ||
+    !safeLabel(value.ticket.title) ||
+    !safeLabel(value.ticket.status, 40) ||
+    (value.ticket.url !== null && !safeLink(value.ticket.url, value.ticket.key)) ||
+    (value.prs !== null &&
+      !(
+        Array.isArray(value.prs) &&
+        value.prs.length <= 5 &&
+        value.prs.every(
+          (p) =>
+            REPO.test(p?.repo) &&
+            Number.isSafeInteger(p.number) &&
+            p.number > 0 &&
+            safeLabel(p.title) &&
+            PR_STATES.includes(p.state) &&
+            typeof p.conflict === "boolean" &&
+            (p.reviews == null || (Number.isSafeInteger(p.reviews) && p.reviews >= 0 && p.reviews <= 999)),
+        )
+      )) ||
+    (value.epic !== null &&
+      !(
+        PROJECT.test(value.epic?.id) &&
+        /^[0-9a-f]{8,16}$/.test(value.epic.short_id) &&
+        safeLabel(value.epic.name) &&
+        PROJECT_STATES.includes(value.epic.state) &&
+        (value.epic.url === null ||
+          (LINEAR_PROJECT_URL.test(value.epic.url) &&
+            value.epic.url.startsWith("https://linear.app/" + LINEAR_WORKSPACE[value.tenant] + "/"))) &&
+        (value.epic.identifier == null || PROJECT_IDENTIFIER.test(value.epic.identifier)) &&
+        Number.isSafeInteger(value.epic.percent) &&
+        value.epic.percent >= 0 &&
+        value.epic.percent <= 100
+      )) ||
+    (value.blockers !== null &&
+      !(value.tenant === "botbuddy" && Array.isArray(value.blockers) && value.blockers.length <= 100)) ||
+    (value.epic_unreadable !== undefined && typeof value.epic_unreadable !== "boolean") ||
+    (value.staging != null &&
+      !(
+        typeof value.staging.configured === "boolean" &&
+        typeof value.staging.red === "boolean" &&
+        (value.staging.since === null || Number.isFinite(Date.parse(value.staging.since)))
+      ))
+  )
+    return false;
+  const observed = Date.parse(value.observed_at);
+  if (
+    !Number.isFinite(observed) ||
+    observed > now + 5000 ||
+    now - observed > 60000
+  )
+    return false;
+  return (value.blockers || []).every(
+    (b) =>
+      /^BOT-[1-9]\d*$/.test(b.key) &&
+      safeLabel(b.title) &&
+      safeLabel(b.status) &&
+      safeLink(b.url, b.key),
+  );
+}
+// Canonical BB drawers (?card=…, any route; BOT-2896/BOT-3100/BOT-3136). A PR
+// card id is owner/repo#n; its `#` travels as %23 so it stays in the query.
+const APP = "https://app.bot-buddy.ai";
+const LINKS = {
+  ticket: (key) => APP + "/kanban?card=ticket:" + key,
+  project: (id) => APP + "/kanban?card=project:" + id,
+  pr: (repo, n) => APP + "/kanban?card=pr:" + repo + "%23" + n,
+  // BOT-3152 AC-2: the web top bar's Staging chip link (STAGING_HREF).
+  staging: APP + "/release-readiness/staging/latest",
+};
+// The ↗ after an id goes straight to the source: Linear for tickets and the
+// epic, GitHub for PRs. Each tenant's tickets live in its own Linear workspace.
+const LINEAR_WORKSPACE = { botbuddy: "botbuddy", "supply-guard": "supply-guard" };
+const OUT = {
+  ticket: (tenant, key) => "https://linear.app/" + LINEAR_WORKSPACE[tenant] + "/issue/" + key,
+  pr: (repo, n) => "https://github.com/" + repo + "/pull/" + n,
+};
+const PR_LABEL = { open: "Open", draft: "Draft", merged: "Merged", closed: "Closed" };
+function demoSnapshot(now) {
+  return {
+    observed_at: new Date(now).toISOString(),
+    branch: "jono/bot-2644-claude-status-mod",
+    tenant: "botbuddy",
+    agent: { name: "Zara Steyn (demo)" },
+    // Illustrative only: several tickets and PRs in different states and long
+    // titles, so the demo exercises wrapping and the aligned columns.
+    ticket: {
+      key: "BOT-2644",
+      title: "Show the session's tickets, PRs and epic inside Claude so an operator can see what the agent is working on without a model turn (example)",
+      status: "In Progress",
+      url: "https://linear.app/botbuddy/issue/BOT-2644",
+    },
+    tickets: [
+      { key: "BOT-2644", title: "Show the session's tickets, PRs and epic inside Claude so an operator can see what the agent is working on without a model turn (example)", status: "In Progress" },
+      { key: "BOT-2645", title: "Status icons follow Linear (example)", status: "In Review" },
+      { key: "BOT-2646", title: "Aligned columns in the band (example)", status: "Done" },
+    ],
+    prs: [
+      { repo: "bot-buddy/botbuddy-webapp", number: 1585, title: "feat(BOT-2644): three aligned lines above the prompt, one status icon per ticket and PR, titles that wrap instead of clipping (example)", state: "open", conflict: true, reviews: 2 },
+      { repo: "bot-buddy/botbuddy-webapp", number: 1586, title: "Status icons (example)", state: "draft", conflict: false, reviews: 0 },
+      { repo: "bot-buddy/botbuddy-webapp", number: 1571, title: "Card links (example)", state: "merged", conflict: false, reviews: 1 },
+    ],
+    epic: {
+      id: "00000000-0000-4000-8000-000000000000",
+      short_id: "a1b2c3d4e5f6",
+      identifier: null,
+      url: "https://linear.app/botbuddy/project/claude-mods-a1b2c3d4e5f6",
+      name: "Claude mods: BB session status, the design gallery and live updates through the bb wait relay (example)",
+      state: "started",
+      done: 5,
+      total: 11,
+      percent: 45,
+    },
+    staging: { configured: true, red: true, since: new Date(now - 12 * 60000).toISOString() },
+    // Demonstration-only IDs; never interpreted as current dependency state.
+    blockers: [
+      {
+        key: "BOT-1200",
+        title: "Example dependency",
+        status: "In Progress",
+        url: "https://linear.app/botbuddy/issue/BOT-1200",
+      },
+    ],
+  };
+}
+// `keep` (Refresh of the same selection) and `wake` leave the drawn snapshot
+// on screen until the new one lands; a new selection or mode clears it first.
+async function refresh($, { wake = false, keep = false } = {}) {
+  const request = ++generation;
+  if (!wake) parked = false;
+  if (!wake) {
+    // A Refresh of a live band stays "Live" until its read lands (review on #1598).
+    keptLive = keep && relayArmed && !relayFault && !!snapshot;
+    stopRelay();
+    if (!keep) snapshot = null;
+  }
+  errorCode = null;
+  loading = true;
+  unbound = false;
+  $.ui.invalidate("ui.render");
+  try {
+    currentTime = await $.clock.now();
+    if (mode === "demo") {
+      snapshot = demoSnapshot(currentTime);
+      return;
+    }
+    const harness = await $.session.id();
+    if (!UUID.test(harness)) throw new Error("harness_session_missing");
+    const cwd = await $.session.cwd();
+    const argv = ["bb", "status-band", "read", "--harness-session-id", harness];
+    if (selectedTicket) argv.push("--ticket-id", selectedTicket);
+    // BOT-3135: a wake re-read skips the slow epic read and keeps the last one.
+    const previous = wake ? snapshot : null;
+    if (previous) argv.push("--skip-epic");
+    let result;
+    try {
+      result = await $.process.run(argv, { cwd, timeoutMs: 25000 });
+    } catch {
+      throw new Error("cli_missing");
+    }
+    if (request !== generation) return;
+    if (typeof result.stdout !== "string" || result.stdout.length > 100000)
+      throw new Error("invalid_response");
+    let data;
+    try {
+      data = JSON.parse(result.stdout);
+    } catch {
+      // A bb older than `status-band` prints its usage error, not JSON.
+      throw new Error(/Unknown command/.test(String(result.stderr)) ? "cli_outdated" : "invalid_response");
+    }
+    if (result.exitCode !== 0 && data?.error === "repo_binding_missing") {
+      unbound = true;
+      snapshot = null;
+      return;
+    }
+    if (result.exitCode !== 0)
+      throw new Error(
+        typeof data.error === "string" ? data.error : "source_unavailable",
+      );
+    currentTime = await $.clock.now();
+    if (request !== generation) return;
+    if (previous && data && data.epic_skipped === true) data = keepKnown(data, previous);
+    if (
+      !validSnapshot(data, harness, currentTime) ||
+      (await $.session.id()) !== harness
+    )
+      throw new Error("session_changed");
+    if (request === generation) {
+      snapshot = data;
+      relayFault = null;
+      if (!wake) startRelay($);
+    }
+  } catch (error) {
+    if (request === generation) {
+      if (wake) stopRelay();
+      snapshot = null;
+      errorCode = Object.hasOwn(ERRORS, error.message)
+        ? error.message
+        : "status_unavailable";
+    }
+  } finally {
+    if (request === generation) {
+      loading = false;
+      keptLive = false;
+      $.ui.invalidate("ui.render");
+    }
+  }
+}
+// ── BOT-3135 relay ─────────────────────────────────────────────────────
+// What the band waits on: each ticket, each PR still open or draft, and, when
+// BotBuddy blockers are listed, each ticket's last blocker clearing, and the
+// epic's Linear project (BOT-3136).
+const MAX_CONDITIONS = 18;
+function waitConditions(s) {
+  // BOT-3152 AC-2: unknown staging (null: a failed read) also wakes on it
+  // (review on #1616), so the next incident re-reads; only a tenant known to
+  // have no staging skips it.
+  const staging = s.staging?.configured === false ? [] : ["event:type=staging_incident"];
+  const conds = s.tickets.map((t) => "linear:issue=" + t.key);
+  for (const p of s.prs || [])
+    if (p.state === "open" || p.state === "draft")
+      conds.push("pr-state:repo=" + p.repo + ",pr=" + p.number);
+  // Blockers are read for the primary ticket only, and an `unblocked:` wait on
+  // a ticket that is not blocked is granted at once: never arm it for others.
+  if (s.tenant === "botbuddy" && s.blockers && s.blockers.length > 0)
+    conds.push("unblocked:" + s.ticket.key);
+  // BOT-3136 AC-1: the epic row wakes on its Linear project's progress.
+  if (s.epic && UUID.test(s.epic.id))
+    conds.push("event:type=linear_project,subject=" + s.epic.id.toLowerCase());
+  // BOT-3152 AC-3 (review on #1616): a clean review round moves only
+  // review_rounds, which no pr-state signal carries, so each open PR also wakes
+  // on its reviews. Last, so a full list drops these before anything else.
+  for (const p of s.prs || [])
+    if (p.state === "open" || p.state === "draft")
+      conds.push("pr-review:repo=" + p.repo + ",pr=" + p.number);
+  // At most 5 tickets, 5 PRs (state + review), blockers, epic and staging: 18,
+  // the relay's limit, so no wake is ever dropped (review on #1616, round 4).
+  return [...conds, ...staging].slice(0, MAX_CONDITIONS);
+}
+// Ending the loop's stream kills the child; a module unload does the same.
+function stopRelay() {
+  relayEpoch++;
+  relayArmed = false;
+  const stream = relayStream;
+  relayStream = null;
+  if (stream) stream.return?.().catch(() => {});
+}
+function delay($, ms) {
+  return new Promise((resolve) => $.clock.after(ms, resolve));
+}
+async function relayOnce($, epoch, since) {
+  const cwd = await $.session.cwd();
+  // A Refresh during that await started a new loop: this one must not spawn.
+  if (epoch !== relayEpoch) return null;
+  const argv = ["bb", "status-band", "relay"];
+  for (const c of waitConditions(snapshot)) argv.push("--cond", c);
+  if (since) argv.push("--since", since);
+  let stream;
+  try {
+    stream = $.process.spawn({ argv, cwd });
+  } catch {
+    return { exit: 4 };
+  }
+  relayStream = stream;
+  let out = "";
+  for (;;) {
+    const piece = await stream.next();
+    if (piece.done) break;
+    if (piece.value.stream === "stdout" && out.length < 20000) out += piece.value.text;
+  }
+  if (epoch !== relayEpoch) return null;
+  relayStream = null;
+  try {
+    return JSON.parse(out.trim().split("\n").pop());
+  } catch {
+    return { exit: 7 };
+  }
+}
+function startRelay($) {
+  stopRelay();
+  // Review on #1616: a read that lands after the session was hidden arms nothing.
+  if (mode !== "live" || !snapshot || parked) return;
+  const epoch = relayEpoch;
+  backoffMs = 0;
+  relayArmed = true;
+  void (async () => {
+    let since = null;
+    let expired = 0;
+    let lastWakeRead = -Infinity;
+    // Reads a relay asks for are at least 15 s apart, whatever bb returns.
+    const wakeRead = async () => {
+      const wait = lastWakeRead + WAKE_READ_GAP_MS - (await $.clock.now());
+      if (wait > 0) await delay($, wait);
+      const at = await $.clock.now();
+      // Checked after the last await: a Refresh begun meanwhile owns the relay now.
+      if (epoch !== relayEpoch) return;
+      lastWakeRead = at;
+      await refresh($, { wake: true });
+    };
+    while (epoch === relayEpoch) {
+      let res;
+      try {
+        res = await relayOnce($, epoch, since);
+      } catch {
+        res = { exit: 7 };
+      }
+      if (!res || epoch !== relayEpoch) return;
+      const cursor = typeof res.next_cursor === "string" ? res.next_cursor : null;
+      if (res.exit === 0) {
+        // A wake: one read, then arm again from the wait's cursor.
+        since = cursor;
+        expired = 0;
+        backoffMs = 0;
+        await wakeRead();
+      } else if (res.exit === 6) {
+        // An expired cursor: read and re-arm without one; a run of them backs off.
+        since = null;
+        if (++expired > 2) {
+          backoffMs = Math.min(backoffMs ? backoffMs * 2 : 30000, 300000);
+          await delay($, backoffMs);
+          if (epoch !== relayEpoch) return;
+        }
+        await wakeRead();
+      } else if (res.exit === 2) {
+        since = cursor || since;
+      } else if (res.exit === 5) {
+        backoffMs = Math.min(backoffMs ? backoffMs * 2 : 30000, 300000);
+        since = cursor || since;
+        await delay($, backoffMs);
+        if (epoch !== relayEpoch) return;
+        await wakeRead();
+      } else {
+        // 3 auth, 4 invalid, 8 superseded, anything else: stop, never loop.
+        relayFault = res.exit === 3 ? "session_expired" : "relay_stopped";
+        relayArmed = false;
+        $.ui.invalidate("ui.render");
+        return;
+      }
+      if (epoch !== relayEpoch || !snapshot || mode !== "live") return;
+    }
+  })();
+}
+// A wake read omits the epic and may not place a quiet secondary ticket
+// (BB's work list covers 3 days); keep what the last full read knew.
+function keepKnown(data, previous) {
+  const { epic_skipped, ...rest } = data;
+  const samePrimary = previous.tenant === data.tenant && previous.ticket.key === data.ticket.key;
+  const known = new Map(previous.tickets.map((t) => [t.key, t]));
+  return {
+    ...rest,
+    // Only the same primary ticket in the same tenant keeps the last epic, and
+    // with it whether that epic could not be read (review on #1616).
+    epic: samePrimary ? previous.epic : null,
+    epic_unreadable: samePrimary ? previous.epic_unreadable === true : false,
+    tickets: data.tickets.map((t) =>
+      t.status === "Unknown" && known.has(t.key) ? known.get(t.key) : t,
+    ),
+  };
+}
+// ── BOT-3152 AC-4: only a session on screen holds a live relay ─────────────
+// `$.session.surfaces()` lists the surfaces drawing this session: empty while
+// Desktop shows another session (POC 2026-11-12, Claude Code 2.1.321). A read
+// that fails counts as on screen, so a live band is never parked by mistake.
+async function onScreen($) {
+  try {
+    const surfaces = await $.session.surfaces();
+    return !Array.isArray(surfaces) || surfaces.length > 0;
+  } catch {
+    return true;
+  }
+}
+async function followVisibility($) {
+  if (mode !== "live" || unbound) return;
+  const shown = await onScreen($);
+  if (!shown && !parked) {
+    parked = true;
+    stopRelay();
+  } else if (shown && parked && !loading) {
+    // One read, then the relay re-arms (refresh starts it on success). While a
+    // read is still in flight the session stays parked, so the next tick
+    // resumes it (review on #1616).
+    parked = false;
+    await refresh($, { keep: true });
+  }
+}
+function stale() {
+  if (mode !== "live" || !snapshot || parked) return false;
+  if (relayFault) return true;
+  return !relayArmed && !keptLive && currentTime - Date.parse(snapshot.observed_at) > 60000;
+}
+function staleText() {
+  if (relayFault === "session_expired")
+    return "STALE · BB session expired. Reconnect BB in this worktree, then Refresh.";
+  if (relayFault) return "STALE · Live updates stopped. Refresh to check current status.";
+  return "STALE · Refresh to check current status";
+}
+async function openPanel($) {
+  await $.ui.open({
+    id: PANE,
+    title: "BotBuddy",
+    focus: true,
+    closeOnEscape: true,
+  });
+}
+async function selectDemo($) {
+  stopRelay();
+  mode = "demo";
+  await refresh($);
+}
+async function selectLive($) {
+  mode = "live";
+  selectedTicket = undefined;
+  await refresh($);
+}
+function controls($, Button) {
+  return [
+    Button({
+      key: "refresh",
+      label: loading ? "Refreshing…" : "Refresh",
+      hotkey: "r",
+      onPress: async () => {
+        if (!loading) await refresh($, { keep: true });
+      },
+    }),
+    Button({
+      key: "live",
+      label: "Live",
+      ...(mode !== "live" ? { plain: true } : {}),
+      onPress: async () => {
+        await selectLive($);
+      },
+    }),
+    Button({
+      key: "demo",
+      label: "Demo",
+      ...(mode !== "demo" ? { plain: true } : {}),
+      onPress: async () => {
+        await selectDemo($);
+      },
+    }),
+  ];
+}
+// --- status icons -----------------------------------------------------------
+// 12px inline SVG on Desktop, drawn from the item's state the way Linear and
+// GitHub draw theirs; the terminal keeps one-cell text glyphs. Fixed hex: a
+// mod cannot read the theme, and these read on light and dark alike.
+let surface = "desktop";
+const ICON = {
+  grey: "#95a2b3",
+  yellow: "#f2c94c",
+  green: "#4cb782",
+  violet: "#5e6ad2",
+  orange: "#f2994a",
+  pr: { open: "#1a7f37", draft: "#59636e", merged: "#8250df", closed: "#cf222e" },
+};
+function svg(body) {
+  return `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 16 16" width="12" height="12" fill="none" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round">${body}</svg>`;
+}
+// A clockwise wedge from twelve o'clock covering `pct` of a radius-3.5 disc.
+function wedge(pct, color) {
+  if (pct <= 0) return "";
+  if (pct >= 100) return `<circle cx="8" cy="8" r="3.5" fill="${color}"/>`;
+  const a = (pct / 100) * 2 * Math.PI;
+  const x = (8 + 3.5 * Math.sin(a)).toFixed(2);
+  const y = (8 - 3.5 * Math.cos(a)).toFixed(2);
+  return `<path d="M8 8 L8 4.5 A3.5 3.5 0 ${pct > 50 ? 1 : 0} 1 ${x} ${y} Z" fill="${color}"/>`;
+}
+const CHECK = `<path d="M5.2 8.2l1.9 1.9 3.7-4" stroke="#fff" stroke-width="1.6"/>`;
+// The one colour of an item's state: its icon and its status word share it.
+function ticketHex(status) {
+  if (status === "Done") return ICON.violet;
+  if (status === "In Progress") return ICON.yellow;
+  if (status === "In Review") return ICON.green;
+  return ICON.grey;
+}
+function epicHex(state) {
+  if (state === "completed") return ICON.violet;
+  if (state === "started") return ICON.yellow;
+  if (state === "backlog") return ICON.orange;
+  return ICON.grey;
+}
+function ticketIcon(status) {
+  const ring = (c, extra = "") => `<circle cx="8" cy="8" r="6" stroke="${c}"${extra}/>`;
+  if (status === "Done") return svg(`<circle cx="8" cy="8" r="6.5" fill="${ICON.violet}"/>` + CHECK);
+  if (status === "Canceled")
+    return svg(`<circle cx="8" cy="8" r="6.5" fill="${ICON.grey}"/><path d="M5.8 5.8l4.4 4.4M10.2 5.8l-4.4 4.4" stroke="#fff" stroke-width="1.6"/>`);
+  if (status === "In Progress") return svg(ring(ICON.yellow) + wedge(50, ICON.yellow));
+  if (status === "In Review") return svg(ring(ICON.green) + wedge(75, ICON.green));
+  if (status === "Todo" || status === "Triage") return svg(ring(ICON.grey));
+  return svg(ring(ICON.grey, ' stroke-dasharray="1.4 2.2"')); // Backlog, Unknown
+}
+function prIcon(state) {
+  const c = ICON.pr[state];
+  const dots = `<circle cx="4.5" cy="3.5" r="1.8" stroke="${c}"/><circle cx="4.5" cy="12.5" r="1.8" stroke="${c}"/>`;
+  if (state === "merged")
+    return svg(dots + `<circle cx="11.5" cy="8.5" r="1.8" stroke="${c}"/><path d="M4.5 5.3v5.4M4.5 5.6c0 2.4 2.4 2.9 5.2 2.9" stroke="${c}"/>`);
+  if (state === "draft")
+    return svg(dots + `<circle cx="11.5" cy="12.5" r="1.8" stroke="${c}"/><path d="M4.5 5.3v5.4M11.5 4v.6M11.5 7.2v.6" stroke="${c}"/>`);
+  if (state === "closed")
+    return svg(dots + `<circle cx="11.5" cy="12.5" r="1.8" stroke="${c}"/><path d="M4.5 5.3v5.4M10 2.5l3 3M13 2.5l-3 3M11.5 8v2.7" stroke="${c}"/>`);
+  return svg(dots + `<circle cx="11.5" cy="12.5" r="1.8" stroke="${c}"/><path d="M4.5 5.3v5.4M11.5 10.7V7a2 2 0 0 0-2-2H7.5M9 3.5 7.5 5 9 6.5" stroke="${c}"/>`);
+}
+// Linear's project hexagon, by project state (not by percent): dotted orange
+// backlog, plain outline planned, a wedge of `pct` while started or paused,
+// violet check completed, grey cross canceled.
+const HEX = "M8 1.6 13.6 4.8v6.4L8 14.4 2.4 11.2V4.8z";
+function epicIcon(state, pct) {
+  if (state === "completed") return svg(`<path d="${HEX}" fill="${ICON.violet}" stroke="${ICON.violet}"/>` + CHECK);
+  if (state === "canceled")
+    return svg(`<path d="${HEX}" fill="${ICON.grey}" stroke="${ICON.grey}"/><path d="M5.8 5.8l4.4 4.4M10.2 5.8l-4.4 4.4" stroke="#fff" stroke-width="1.6"/>`);
+  if (state === "backlog") return svg(`<path d="${HEX}" stroke="${ICON.orange}" stroke-dasharray="1.4 2"/>`);
+  if (state === "started") return svg(`<path d="${HEX}" stroke="${ICON.yellow}"/>` + wedge(pct, ICON.yellow));
+  if (state === "paused") return svg(`<path d="${HEX}" stroke="${ICON.grey}"/>` + wedge(pct, ICON.grey));
+  return svg(`<path d="${HEX}" stroke="${ICON.grey}"/>`); // planned
+}
+// The leading icon: an Svg on Desktop, else the coloured text glyph.
+function lead(el, glyph, color, alt, source) {
+  if (surface !== "terminal" && typeof el.Svg === "function")
+    return el.Box({
+      flexDirection: "row",
+      flexShrink: 0,
+      children: [el.Svg({ alt, width: 12, height: 12, source }), el.Text({ children: [" "] })],
+    });
+  return el.Text({ color, children: [glyph + " "] });
+}
+
+// --- band: three lines, each id a link to its canonical drawer ------------
+function dim(el, text) {
+  return el.Text({ dimColor: true, children: [text] });
+}
+function sep(el) {
+  return dim(el, " · ");
+}
+// Three aligned columns per line: [icon id]…, status, title. The id and
+// status columns take the widest line's width on every line and never shrink,
+// so ids never break and statuses line up; the title takes the rest and wraps.
+// One item per row: tickets, then PRs, then the single epic.
+const ID_GAP = 2;
+function idsWidth(ids) {
+  return ids.reduce((w, id, i) => w + (i ? ID_GAP : 0) + (id.label || "").length + (id.out ? 2 : 0), 0);
+}
+// Icon (2 cells) then the status parts.
+function statusWidth(spec) {
+  return (spec.icon ? 2 : 0) + spec.status.reduce((w, part, i) => w + (i ? 3 : 0) + part.text.length, 0);
+}
+function bandLine(el, spec, widths, right) {
+  const ids = [];
+  spec.ids.forEach((id, i) => {
+    if (i) ids.push(el.Text({ children: [" ".repeat(ID_GAP)] }));
+    if (id.label) ids.push(el.Link({ href: id.href, label: id.label }));
+    if (id.out) ids.push(el.Text({ children: [" "] }), el.Link({ href: id.out, label: "↗" }));
+  });
+  // The state icon sits left of the status word, in the same colour.
+  const status = spec.icon ? [spec.icon] : [];
+  spec.status.forEach((part, i) => {
+    if (i) status.push(sep(el));
+    status.push(el.Text({ color: part.color, children: [part.text] }));
+  });
+  const children = [
+    el.Box({ key: spec.key + "-ids", flexDirection: "row", width: widths.ids, flexShrink: 0, children: ids }),
+    el.Box({ key: spec.key + "-status", flexDirection: "row", width: widths.status, flexShrink: 0, children: status }),
+    el.Box({
+      key: spec.key + "-title",
+      flexGrow: 1,
+      flexShrink: 1,
+      minWidth: 0,
+      children: [el.Text({ wrap: "wrap", dimColor: spec.dim || undefined, children: [spec.title] })],
+    }),
+  ];
+  if (right && right.length)
+    children.push(el.Box({ flexDirection: "row", flexShrink: 0, columnGap: 1, children: right }));
+  // Top-aligned: with a wrapped title, the id and status sit on its first line.
+  return el.Box({ key: spec.key, flexDirection: "row", alignItems: "flex-start", columnGap: 1, children });
+}
+const UNREAD = {
+  prs: "Couldn't read this session's PRs",
+  epic: "Couldn't read this session's epic",
+  staging: "staging: couldn't read",
+};
+// The chip's own age format: minutes, then hours under two days, then days.
+function shortAge(fromIso, now) {
+  const mins = Math.max(0, Math.floor((now - Date.parse(fromIso)) / 60000));
+  if (mins < 60) return mins + "m";
+  const hours = Math.floor(mins / 60);
+  return hours < 48 ? hours + "h" : Math.floor(hours / 24) + "d";
+}
+function stagingBanner(el, key, since) {
+  return el.Box({
+    key,
+    flexDirection: "row",
+    columnGap: 1,
+    children: [
+      el.Text({ color: "error", bold: true, children: ["▲ Staging red" + (since ? " " + shortAge(since, currentTime) : "")] }),
+      el.Link({ href: LINKS.staging, label: "Open staging ↗" }),
+    ],
+  });
+}
+// `inPane`: the same rows inside the detail pane, keyed apart, no Details.
+function bandLines(el, $, inPane) {
+  const k = (key) => (inPane ? "pane-" : "") + key;
+  const details = inPane ? null : el.Button({
+    key: "details",
+    label: "Details",
+    onPress: async () => {
+      await openPanel($);
+    },
+  });
+  const tag = mode === "demo" ? [el.Text({ color: "warning", children: ["DEMO"] })] : [];
+  if (!snapshot) {
+    const text = loading ? "Loading session…" : errorText();
+    return [
+      el.Box({
+        key: k("line-ticket"),
+        flexDirection: "row",
+        columnGap: 1,
+        children: [...tag, el.Text({ color: loading ? undefined : "warning", children: ["BB · " + text] }), details].filter(Boolean),
+      }),
+    ];
+  }
+  const s = snapshot;
+  // One row per ticket and per PR, each with its own icon, status and title.
+  const specs = s.tickets.map((t) => ({
+    key: k("line-ticket-" + t.key),
+    ids: [
+      {
+        label: t.key,
+        href: LINKS.ticket(t.key),
+        out: OUT.ticket(s.tenant, t.key),
+      },
+    ],
+    icon: lead(el, "◆", ticketHex(t.status), "ticket " + t.status, ticketIcon(t.status)),
+    status: [{ text: t.status, color: ticketHex(t.status) }],
+    title: t.title,
+  }));
+  // BOT-3152 AC-1: no PR or no epic means no row; a failed read says so.
+  if (s.prs)
+    for (const p of s.prs) {
+      const status = [{ text: PR_LABEL[p.state], color: ICON.pr[p.state] }];
+      if (p.conflict && p.state !== "merged" && p.state !== "closed")
+        status.push({ text: "⚠ conflict", color: "#bc4c00" });
+      // BOT-3152 AC-3: the PR's code-review rounds, as get_pr_state counts them.
+      if (Number.isSafeInteger(p.reviews))
+        status.push({ text: p.reviews + (p.reviews === 1 ? " review" : " reviews"), color: ICON.grey });
+      specs.push({
+        key: k("line-pr-" + p.number),
+        ids: [
+          {
+            label: "#" + p.number,
+            href: LINKS.pr(p.repo, p.number),
+            out: OUT.pr(p.repo, p.number),
+          },
+        ],
+        icon: lead(el, "⎇", ICON.pr[p.state], "pr " + p.state, prIcon(p.state)),
+        status,
+        title: p.title,
+      });
+    }
+  else
+    specs.push({
+      key: k("line-pr"),
+      ids: [],
+      icon: el.Text({ color: "warning", children: ["⎇ "] }),
+      status: [],
+      title: UNREAD.prs,
+      dim: true,
+    });
+  if (s.epic)
+    specs.push({
+      key: k("line-epic"),
+      ids: [
+        {
+          // Linear's project id (P-BOT-39) when known, else the URL slug.
+          label: s.epic.identifier || s.epic.short_id,
+          href: LINKS.project(s.epic.id),
+          out: s.epic.url,
+        },
+      ],
+      icon: lead(el, "◇", epicHex(s.epic.state), "epic " + s.epic.state + " " + s.epic.percent + "%", epicIcon(s.epic.state, s.epic.percent)),
+      status: [{ text: s.epic.percent + "% done", color: epicHex(s.epic.state) }],
+      title: s.epic.name,
+    });
+  else if (s.epic_unreadable)
+    specs.push({ key: k("line-epic"), ids: [], icon: el.Text({ color: "warning", children: ["◇ "] }), status: [], title: UNREAD.epic, dim: true });
+  const widths = {
+    ids: Math.max(...specs.map((x) => idsWidth(x.ids))),
+    status: Math.max(...specs.map(statusWidth)),
+  };
+  const right = [...tag];
+  if (stale()) right.push(el.Text({ color: "warning", children: ["STALE"] }));
+  // BOT-3152 edge case: unknown staging is its own signal, never a quiet green.
+  if (s.staging == null) right.push(dim(el, UNREAD.staging));
+  if (details) right.push(details);
+  const lines = specs.map((spec, i) => bandLine(el, spec, widths, i === 0 ? right : null));
+  // BOT-3152 AC-2: the web Staging chip's red, with its link, above the rows.
+  if (s.staging?.red) lines.unshift(stagingBanner(el, k("line-staging"), s.staging.since));
+  return lines;
+}
+export function register(on) {
+  on("session.start", async ($, e, next) => {
+    // All background timing is local display freshness; there is no network poll loop.
+    if (timer) timer.cancel();
+    timer = $.clock.every(5000, async () => {
+      currentTime = await $.clock.now();
+      await followVisibility($);
+      $.ui.invalidate("ui.render");
+    });
+    await $.command.register({
+      name: "bb-status",
+      description:
+        "Open BB identity, Linear status and blockers (no model turn)",
+      argumentHint: "[live [KEY[,KEY…]]|demo]",
+      immediate: true,
+    });
+    parked = false;
+    if (await onScreen($)) await refresh($);
+    else parked = true;
+    return next(e);
+  });
+  on("command.run", { command: "bb-status" }, async ($, e) => {
+    const args = (e.args ?? "").trim();
+    if (args === "demo") await selectDemo($);
+    // Up to five keys, comma-separated; the adapter checks the tenant prefix.
+    else if (
+      args === "live" ||
+      /^live [A-Z]{2,10}-[1-9]\d{0,5}(?:,[A-Z]{2,10}-[1-9]\d{0,5}){0,4}$/.test(args)
+    ) {
+      mode = "live";
+      selectedTicket = args.split(" ")[1];
+      await refresh($);
+    } else if (args === "") {
+      if (!loading) await refresh($, { keep: true });
+    } else {
+      stopRelay();
+      errorCode = "ticket_missing";
+      snapshot = null;
+      keptLive = false;
+      generation++;
+      loading = false;
+      $.ui.invalidate("ui.render");
+    }
+    await openPanel($);
+    return {};
+  });
+  on("turn.start", async ($, e, next) => {
+    if (!e.agentId) {
+      activity = "Working";
+      $.ui.invalidate("ui.render");
+    }
+    return next(e);
+  });
+  on("turn.complete", async ($, e, next) => {
+    if (!e.agentId) {
+      activity = e.isAborted ? "Stopped" : "Idle";
+      $.ui.invalidate("ui.render");
+    }
+    return next(e);
+  });
+  on("session.end", async ($, e, next) => {
+    stopRelay();
+    generation++;
+    snapshot = null;
+    keptLive = false;
+    selectedTicket = undefined;
+    mode = "live";
+    loading = false;
+    errorCode = "session_changed";
+    parked = false;
+    unbound = false;
+    if (timer) timer.cancel();
+    return next(e);
+  });
+  on(
+    "classic.SessionStart",
+    { source: ["clear", "resume", "fork"] },
+    async ($, e, next) => {
+      selectedTicket = undefined;
+      mode = "live";
+      await refresh($);
+      return next(e);
+    },
+  );
+  on("ui.render", { component: "AbovePrompt" }, async ($, e, next) => {
+    const el = $.ui.resolve(e);
+    surface = e.surface;
+    const theirs = await next(e);
+    if (unbound && mode === "live") return theirs;
+    return el.Box({
+      flexDirection: "column",
+      children: [theirs, ...bandLines(el, $)],
+    });
+  });
+  on("ui.render", { component: "Pane" }, async ($, e, next) => {
+    if (e.requestId !== PANE) return next(e);
+    const { Box, Text, Button, Link } = $.ui.resolve(e);
+    const children = [
+      Text({ bold: true, color: "cyan", children: ["BOTBUDDY · SESSION"] }),
+      Text({
+        dimColor: true,
+        children: [
+          mode === "demo"
+            ? "DEMO · illustrative data"
+            : "LIVE",
+        ],
+      }),
+    ];
+    if (loading && !snapshot) children.push(Text({ children: ["Loading session…"] }));
+    else if (!snapshot)
+      children.push(Text({ color: "yellow", children: [errorText()] }));
+    else {
+      children.push(
+        Text({ bold: true, children: [snapshot.agent.name] }),
+        Text({
+          children: [snapshot.ticket.key + " · " + snapshot.ticket.title],
+        }),
+        Text({
+          color: "cyan",
+          // BotBuddy status is read from Linear; SupplyGuard's from BB's copy.
+          children: [
+            (snapshot.ticket.url ? "Linear · " : "BB · ") +
+              snapshot.ticket.status,
+          ],
+        }),
+        Text({ children: ["Agent · " + activity] }),
+        Text({ dimColor: true, children: [snapshot.branch] }),
+      );
+      children.push(
+        Text({
+          color: stale() ? "yellow" : undefined,
+          children: [
+            stale()
+              ? staleText()
+              : (relayArmed || keptLive ? "Live · " : "Observed · ") + snapshot.observed_at,
+          ],
+        }),
+      );
+      // The same three items the band shows, one row each in full.
+      surface = e.surface;
+      children.push(...bandLines($.ui.resolve(e), $, true));
+      if (snapshot.blockers === null)
+        children.push(
+          Text({ dimColor: true, children: ["Blockers are read from the BotBuddy Linear workspace only."] }),
+        );
+      else
+      children.push(
+        Text({
+          bold: true,
+          children: ["Blocking tickets · " + snapshot.blockers.length],
+        }),
+      );
+      for (const blocker of snapshot.blockers || []) {
+        const label =
+          blocker.key + " · " + blocker.title + " · " + blocker.status;
+        children.push(
+          mode === "demo"
+            ? Text({ children: [label + " (example)"] })
+            : Link({ label, href: blocker.url }),
+        );
+      }
+      if (snapshot.blockers && snapshot.blockers.length === 0)
+        children.push(
+          Text({ children: ["No open blockers at the last refresh."] }),
+        );
+      const links = [
+        Link({ label: "Open ticket ↗", href: LINKS.ticket(snapshot.ticket.key) }),
+      ];
+      if (snapshot.ticket.url)
+        links.push(Link({ label: "Linear ↗", href: snapshot.ticket.url }));
+      links.push(Link({ label: "Open BB ↗", href: APP }));
+      children.push(Box({ flexDirection: "row", columnGap: 2, children: links }));
+    }
+    children.push(
+      Box({
+        flexDirection: "row",
+        columnGap: 2,
+        children: controls($, Button),
+      }),
+    );
+    return Box({ flexDirection: "column", rowGap: 1, padding: 1, children });
+  });
+}