@botbuddy/cli 1.67.0 → 1.68.1

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## 1.68.1
+
+- The bb-status band now binds a Claude Code session whose repo has no BotBuddy SessionStart hook, such as Supply Guard worktrees, instead of showing "BB identity belongs to another session". When the worktree has no session cache, an unbound one or an expired one, `bb status-band read` bootstraps this session once (ticketless, the same bootstrap `bb bootstrap` runs) and reads again. A cache another live session holds is never taken over.
+
+## 1.68.0
+
+- The bb-status band for Claude Code now ships in this package. `bb setup` and `bb update` install it once, at user scope, through `bb status-band install`. They point the `botbuddy-labs` marketplace at the plugin inside the installed CLI, so every worktree shows the band with no plugin command, and no repo checkout is needed. The band's reads and live wake run from the installed CLI (`bb status-band read` and `bb status-band relay`).
+- The band hides the PR and epic rows when the session has none, and says when it couldn't read them. Each PR row shows its code-review count. A red staging banner links to the latest staging readiness page. The band holds a live wait only while the session is on screen.
+- `bb wait 'event:type=staging_incident'` wakes when one of your tenant's staging incidents opens or closes.
+
 ## 1.67.0
 
 - New `bb release-notes submit <note.json>` submits one governed release note for your tenant through the MCP tool `submit_release_note`. It sends the file unchanged, prints the stored source key, state and revision, and exits 1 with the named refusal (`schema_invalid`, `type_unknown`, `markup_refused`, `link_refused`, `entitlement_missing`) when nothing was stored.

package/claude-plugin/.claude-plugin/marketplace.json

@@ -0,0 +1,17 @@
+{
+  "name": "botbuddy-labs",
+  "owner": {
+    "name": "BotBuddy"
+  },
+  "metadata": {
+    "description": "BotBuddy's Claude Code mods, shipped inside the bb CLI package. bb setup and bb update install them (BOT-3152)."
+  },
+  "plugins": [
+    {
+      "name": "bb-status",
+      "source": "./bb-status",
+      "description": "BB session status above the prompt: tickets, PRs with review counts, epic and staging, for BotBuddy and Supply Guard sessions",
+      "version": "1.0.0"
+    }
+  ]
+}

package/claude-plugin/bb-status/.claude-plugin/plugin.json

@@ -0,0 +1,9 @@
+{
+  "name": "bb-status",
+  "version": "1.0.0",
+  "description": "BB session status above the prompt: tickets, PRs with review counts, epic and staging, live only while the session is on screen.",
+  "author": {
+    "name": "BotBuddy"
+  },
+  "license": "MIT"
+}

package/claude-plugin/bb-status/README.md

@@ -0,0 +1,156 @@
+# BB status — Claude Code mod
+
+Shows the session's work in Claude Code as a three-line band above the prompt:
+
+```
+◆ BOT-3110 · In Progress · Go daemon crash-loops when it reaps …     Details
+⎇ #1585 · Open · fix(BOT-3110): a never-provisioned remote lease …
+◇ cbce84018a75 · 0% done · A third party adds a Linux Docker host …
+```
+
+Every id is a link. A ticket opens BB's ticket drawer and an epic opens BB's
+project drawer (`?card=ticket:KEY`, `?card=project:<uuid>`, BOT-2896/BOT-3100).
+BB has no PR drawer yet, so a PR id opens its Testing pipeline row as the
+placeholder. BB has no must-have field either, so the epic line shows BB's own
+progress (done over non-canceled members) as the placeholder. `/bb-status` opens
+the detail pane: agent, the same three rows, blockers and links. Opening it, pressing buttons, and refreshing
+run host code without model calls, extra tools, or status text in Claude's context.
+
+It reads **BotBuddy** (BOT-*) and **SupplyGuard** (ENT-*) sessions; the repo's
+committed `.botbuddy-agent.json` tenant picks which. A repo with no binding shows
+no band at all. Normal Chat and Cowork do not load this UI.
+
+**BOT-3152 band rules.** A session with no PR or no epic shows no row for it. A
+failed read shows "Couldn't read …" instead, never the empty state. Each PR row
+shows its code-review rounds (`pr_state.review_rounds`, which `get_pr_state`
+returns as `reviewRounds`). While the tenant's staging is red, a `▲ Staging red`
+banner links to `/release-readiness/staging/latest`, the web Staging chip's
+status and link. Unreadable staging says `staging: couldn't read`, never green.
+The relay is parked, with no child and no server wait, while
+`$.session.surfaces()` is empty, which is the case while Desktop shows another
+session. Once a surface draws the session again, the 5 s display tick does one
+read and re-arms the relay.
+
+## Install
+
+The bb CLI ships this mod and installs it (BOT-3152). `bb setup` and `bb update`
+run `bb status-band install`. That command points Claude Code's `botbuddy-labs`
+marketplace at `claude-plugin/` inside the installed `@botbuddy/cli` package, and
+installs `bb-status` at **user scope**, so every worktree gets the band at session
+start. A marketplace still pointing at a repo checkout is re-pointed. The band's
+reads and live wake run from the installed CLI (`bb status-band read` and
+`bb status-band relay`), so deleting a checkout never breaks a running relay.
+Open sessions pick up a new version with `/reload-plugins`.
+
+Requirements: Claude Code >=2.1.287 and Node >=20, with `bb` on Claude's PATH.
+
+For development, run against this checkout without installing:
+
+```sh
+claude --plugin-dir "$PWD/cli/claude-plugin/bb-status"
+```
+
+Then run `/bb-status demo` to inspect the UI without credentials, or `/bb-status`
+to read the current session. `/bb-status live BOT-2644` explicitly selects a ticket;
+Refresh keeps that selection. `/bb-status live` returns to the current branch's
+BOT ticket. Demo is always labelled and never makes network requests.
+
+## Live mode
+
+Use the existing BB SessionStart connection in the **same worktree and Claude
+session**. The adapter requires its private `.botbuddy/agent-state.json`, including
+the canonical work-graph session, agent, tenant, worktree, expiry, and harness id.
+It refuses another session's cache. Do not copy an agent-state file between sessions.
+The committed `.botbuddy-agent.json` must declare `tenant: "botbuddy"` or
+`"supply-guard"`, and the branch or `/bb-status live KEY[,KEY…]` names tickets
+with that tenant's prefix.
+
+For BotBuddy, `LINEAR_BB_API_KEY` must reach Claude's child processes; use the existing Keychain /
+launch-environment setup in the repository README. Never put a credential in the
+plugin, its options, a prompt, or a snapshot. A missing or expired connection is
+shown as Unknown with a recovery instruction; the mod does not mint identities,
+refresh credentials, approve tools, or change Linear tickets.
+
+Reads are limited to BB's authenticated REST aliases (`whoami`,
+`list_work_items`, `get_pr_state`, `get_epic_health`) and, for BotBuddy only,
+Linear's `organization` plus the exact issue and incoming `blocks` relations.
+PRs are this worktree's branch's. SupplyGuard status comes from BB's synced
+tickets and shows no blockers. A refused BB read blanks only its own line.
+It validates the returned BB agent against the cache and the Linear workspace /
+team / issue against BotBuddy, and re-checks the cache after both requests.
+Credentials stay inside the Node adapter; only allowlisted display fields reach
+the mod. Requests refuse redirects and time out after 8 seconds each. Raw errors,
+headers, stderr, and API responses never enter the UI.
+
+Data refreshes **when BB reports a change** (BOT-3135). After each live read the
+mod starts one relay child, `bb status-band relay`. The relay runs the installed CLI's own `bb wait`
+on the band's subjects:
+- each ticket (`linear:issue=`);
+- each open or draft PR (`pr-state:`);
+- for BotBuddy blockers, each ticket's last blocker clearing (`unblocked:`).
+- the epic's Linear project (`event:type=linear_project,subject=<uuid>`, BOT-3136);
+- when the tenant has staging configured, its staging incidents opening or closing
+  (`event:type=staging_incident`, BOT-3152).
+
+**What the band shows comes from the registered session** (BOT-3136). The adapter reads
+`get_session_status`, which returns the tickets, PRs and epic this BB session registered
+(`register_agent`, or a ticket declared by `heartbeat`), in one read of at most 4 KB. Only
+when the session registered no ticket does it fall back to the key in the branch name.
+The snapshot's `binding` field says which happened: `session`, `branch`, or `selected`
+(from `/bb-status live KEY`).
+
+It uses the `bb` beside the `node` that runs it and the worktree's cached BB session.
+
+| The wait ends with | The mod |
+|---|---|
+| A wake (exit 0) | Re-reads once, redraws, and re-arms from the wait's cursor. |
+| A quiet 570 s timeout (exit 2) | Re-arms from the cursor with no read. |
+| Backend unavailable (exit 5) | Backs off 30 s, doubling to 5 min, then reads once. |
+| Expired cursor (exit 6) | Reads, then re-arms without one. |
+| Expired session (exit 3) or any other exit | Stops and marks the band **STALE** with what to do. It never retries in a loop. |
+
+Reads the relay triggers are at least 15 s apart. Refresh, demo, the end of the
+session and a mod reload each end the child, so a session has at most one.
+
+The band's waits run under the agent's own BB session. They show in `/waits` and in
+`register_agent`'s `existing_waits` with the short-timeout reason
+"bb-status band relay…". An agent recovering from a crash must not `bb wait resume`
+them, because the band re-arms its own. Epic progress has no wait condition yet (BOT-3136); it
+refreshes with each wake.
+
+Without a live relay, a local display clock marks snapshots older than 60 seconds as
+**STALE**. That clock makes no network requests. Agent Working/Idle/Stopped comes from
+Claude turn events and is separate from Linear state.
+The POC rejects incomplete blocker pages (>100 relations) rather than showing a
+false unblocked state. Demo dependencies are illustrative, not current Linear facts.
+
+## Verification
+
+See [EVIDENCE.md](EVIDENCE.md) for the recorded receipts and limits.
+
+```sh
+node --test cli/src/status-band*.test.mjs cli/claude-plugin/bb-status/hooks/*.test.mjs
+claude plugin validate cli/claude-plugin/bb-status --strict
+claude plugin test cli/claude-plugin/bb-status
+```
+
+The native test suite requires Claude Code >=2.1.293 for its mock session helper.
+
+Native tests use Claude's own `claude-code/testing` kit and validate element trees
+and interactions for both `terminal` and `desktop`. They require no sign-in or
+model. The live fixture was captured on 2026-10-21 by the real adapter with BB and
+Linear, using this implementation's Codex session; it contains no credential.
+Synthetic test variants cover failure cases and dependency changes. That live read
+proves the adapter boundary, not an interactive Claude Desktop paint or login.
+
+The browser preview renders the **actual mod hooks and returned element tree**,
+using a lightweight host adapter. It is explicitly a preview, not a screenshot of
+Claude Desktop. It can exercise live reads when its server is started in this
+worktree with `BB_STATUS_PREVIEW_HARNESS_SESSION_ID` set to this session's id:
+
+```sh
+BB_STATUS_PREVIEW_HARNESS_SESSION_ID=<current-harness-uuid> \
+  node cli/claude-plugin/bb-status/preview/server.mjs --port <claimed-local-port>
+```
+
+Live receipts for each BOT-3152 criterion are on the ticket.

package/claude-plugin/bb-status/hooks/hooks.json

@@ -0,0 +1 @@
+{ "modules": ["./register.js"] }