@botbuddy/cli 1.61.9 → 1.62.0

package/daemon-release/darwin-arm64.json

@@ -1,7 +1,7 @@
 {
-  "release_version": "1.61.9",
-  "source_commit": "af5fbce708449fe5cb598f4f64523fb3696dd1a0",
-  "source_sha256": "738e4a6b0da849271e515488978880eb40baab42ba708ea29bd3e0cba06ac0d8",
+  "release_version": "1.62.0",
+  "source_commit": "d239018a4df5137e9b013792274dbfe6316f46e1",
+  "source_sha256": "cd5a5bd1f0a409d0a79a3db600b218fccca101102df138d7414766a3bba1b16a",
   "target": "darwin-arm64",
-  "sha256": "a9ea783c9eb264b1ddd03f6d1fd1e5b78df479e3eab6d13f2026ea1085101923"
+  "sha256": "7b0ddb31fbbf568503a4d079badbae185cac44fe27a5ea2a0823d1ae83d52b2b"
 }

package/daemon-release/linux-x64.json

@@ -1,7 +1,7 @@
 {
-  "release_version": "1.61.9",
-  "source_commit": "af5fbce708449fe5cb598f4f64523fb3696dd1a0",
-  "source_sha256": "738e4a6b0da849271e515488978880eb40baab42ba708ea29bd3e0cba06ac0d8",
+  "release_version": "1.62.0",
+  "source_commit": "d239018a4df5137e9b013792274dbfe6316f46e1",
+  "source_sha256": "cd5a5bd1f0a409d0a79a3db600b218fccca101102df138d7414766a3bba1b16a",
   "target": "linux-x64",
-  "sha256": "09a36d5822c4c28a0ded7fe0a6bf079b58f4aa5cb80181971e8448ca3eab3804"
+  "sha256": "4c5065a8cc25ef6c01967ec96f109aa39e23799ef1043a4fd942780b0adb6c95"
 }

package/daemon-release/manifest.json

@@ -1,21 +1,21 @@
 {
   "schema_version": 1,
-  "release_version": "1.61.9",
-  "source_commit": "af5fbce708449fe5cb598f4f64523fb3696dd1a0",
-  "source_sha256": "738e4a6b0da849271e515488978880eb40baab42ba708ea29bd3e0cba06ac0d8",
+  "release_version": "1.62.0",
+  "source_commit": "d239018a4df5137e9b013792274dbfe6316f46e1",
+  "source_sha256": "cd5a5bd1f0a409d0a79a3db600b218fccca101102df138d7414766a3bba1b16a",
   "targets": {
     "darwin-arm64": {
       "goos": "darwin",
       "goarch": "arm64",
       "binary": "daemon/bin/darwin-arm64/botbuddy-daemon",
-      "sha256": "a9ea783c9eb264b1ddd03f6d1fd1e5b78df479e3eab6d13f2026ea1085101923",
+      "sha256": "7b0ddb31fbbf568503a4d079badbae185cac44fe27a5ea2a0823d1ae83d52b2b",
       "mode": "0755"
     },
     "linux-x64": {
       "goos": "linux",
       "goarch": "amd64",
       "binary": "daemon/bin/linux-x64/botbuddy-daemon",
-      "sha256": "09a36d5822c4c28a0ded7fe0a6bf079b58f4aa5cb80181971e8448ca3eab3804",
+      "sha256": "4c5065a8cc25ef6c01967ec96f109aa39e23799ef1043a4fd942780b0adb6c95",
       "mode": "0755"
     }
   }

package/package.json

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

package/src/commands.mjs

@@ -56,6 +56,23 @@ export function shouldCheckForUpdates(argv) {
   return true;
 }
 
+// BOT-2715: local commands with their own --help. `bb help <command>` (and
+// `bb <command> help`) print that help instead of asking MCP discovery for a tool
+// of the same name. MCP tools are snake_case, so no name here can shadow one.
+export const LOCAL_HELP_COMMANDS = Object.freeze([
+  "wait", "stack", "pw", "docker", "run", "mcp", "login", "setup", "doctor", "host",
+  "staging-pool", "daemon", "evidence", "usage", "telemetry", "allocation",
+]);
+const HELP_WORDS = new Set(["help", "--help", "-h"]);
+
+export function routeHelpArgv(argv) {
+  const [command, ...args] = argv;
+  if (HELP_WORDS.has(command) && args.length === 1 && LOCAL_HELP_COMMANDS.includes(args[0])) return [args[0], "--help"];
+  // pw parses its own argv (`bb pw help` is its lane grammar's business).
+  if (args.length === 1 && args[0] === "help" && command !== "pw" && LOCAL_HELP_COMMANDS.includes(command)) return [command, "--help"];
+  return argv;
+}
+
 const TICKET_KEY_RE = /^[A-Za-z][A-Za-z0-9]{1,9}-\d{1,6}$/;
 
 export function validateBootstrapLinkage(ticketId, noTicketReason) {
@@ -73,7 +90,7 @@ export async function run(argv, {
   bootstrap = cmdBootstrap,
   managedAllocation = cmdManagedAllocation,
 } = {}) {
-  const [command, ...args] = argv;
+  const [command, ...args] = routeHelpArgv(argv);
   // BOT-2069: `bootstrap close` can retire a live server session. Parse its
   // own arguments before loading config, checking npm, reading the runtime
   // cache, or resolving any credential. Help and malformed invocations return
@@ -84,7 +101,7 @@ export async function run(argv, {
   }
 
   await load();
-  if (shouldCheckForUpdates(argv)) await warnStale({ version: VERSION });
+  if (shouldCheckForUpdates([command, ...args])) await warnStale({ version: VERSION });
 
   switch (command) {
     case "start": return cmdStart(args);
@@ -184,19 +201,28 @@ export function cmdHelp(log = console.log) {
   log(`${bold("bb")} ${dim(`v${VERSION}`)} — Swarm coordination CLI
 
 ${dim(`Run everything as ${cyan("bb <command>")} — the short, preferred alias. ${cyan("botbuddy <command>")} is the identical long form.`)}
-
-${bold("USAGE")}
-  bb start                   Start BotBuddy (login + codex server + bridge)
-  bb bootstrap --session-id <uuid> (--ticket-id <BOT-n> | --no-ticket-reason <reason>)
-                             Internal launcher contract: persist a wait-capable
-                             harness session without printing its secret
-
-${bold("OPTIONS")}
-  start [options]
-    -p, --port <port>        WebSocket port (default: 4500)
-    -r, --repo <path>        Repository path (default: cwd)
-    -m, --model <model>      Default model (default: gpt-5.4)
-    --no-server              Don't auto-start codex app-server
+${dim(`Detailed help: ${cyan("bb help <command>")} or ${cyan("bb <command> --help")} for ${LOCAL_HELP_COMMANDS.join(", ")}; ${cyan("bb test --help")} for test.`)}
+
+${bold("COMMON TASKS")}
+  bb setup                                  sign in and cache this worktree's agent session (once)
+  bb doctor --fix                           repair a stale or rejected agent session
+  bb wait 'timer:duration=1800'             wait 30 min (the only allowed way to wait for time)
+  bb wait 'ci:repo=<owner/repo>,scope=latest,pr=<n>' --heartbeat
+                                            wait for CI on a PR's current head to finish
+  bb wait 'pr-review:repo=<owner/repo>,pr=<n>,sha=<head>' --heartbeat
+                                            wait for review activity on the head you just pushed
+  bb wait 'unblocked:BOT-123'               wait for a ticket's last blocker to clear
+  bb wait result --from-file "$wait_artifact" --exit-code "$wait_exit"
+                                            read a redirected wait's receipt once it exits
+                                            (the full wrapper is in bb help wait → EXAMPLES)
+  bb stack run --repo botbuddy-web --ticket BOT-123 -- pnpm test:integration
+                                            run a batch on a leased, isolated local Supabase stack
+  bb test unit                              run a configured test lane as a tracked test run
+  bb pw --environment local 3 open http://localhost:5173
+                                            drive Playwright lane 3 (lock it first)
+  bb call get_staging_gate --repo bot-buddy/botbuddy-webapp
+                                            call any BotBuddy MCP tool (${cyan("bb help <tool>")} for its args)
+  More wait recipes: ${cyan("bb help wait")} → EXAMPLES.
 
 ${bold("AUTH")}
   login [--no-browser] [--tenant <slug>] [--device | --loopback] [--caller <name>] [--caller-harness <h>] [--caller-ticket <ref>]
@@ -221,6 +247,7 @@ ${bold("MCP CONFIG KEY")}
 ${bold("TOOLS")}
   help --tools               List every BotBuddy tool
   help <tool>                Show one tool's arguments
+  help <command>             Detailed help for a command named at the top (same as <command> --help)
   help test                  Safe test-lane launch and recovery guidance
   help symptom <name>        Diagnose a known block without source-diving
   call <tool> [--key value]  Invoke any tool
@@ -228,49 +255,37 @@ ${bold("TOOLS")}
   call <tool> --pin <slug>   Pin the connection tenant (a user token needs one;
                              default: BOTBUDDY_TENANT → repo profile → sole tenant)
 
-${bold("STACK LEASES")}
+${bold("AGENT WAITS")}  (${cyan("bb help wait")} — every condition, with examples)
+  wait [--any] <condition>... [options]
+                             Wait once for a pushed BotBuddy signal; one JSON receipt on exit
+  wait                       List this worktree's saved waits (after a restart)
+  wait result [<local_wait_id>] [--from-file <path> --exit-code <n>]
+                             Read a terminal receipt without re-arming
+  wait resume|cancel|acknowledge <local_wait_id>
+                             Recover, stop, or mark read one saved wait
+
+${bold("STACK LEASES")}  (${cyan("bb help stack")})
+  stack run [options] -- <command>   Own one Helper-backed test/fix batch end-to-end (preferred)
   stack up [options]         Request a batch-scoped local stack lease; park if full; hold it active
   stack status <lease_id>    Show a lease's state + connection
   stack touch  <lease_id>    Bump the lease idle clock
-  stack done   <lease_id>    Release (done) a lease — reap the stack
-  stack help                 Full stack usage + exit codes
+  stack done   <lease_id>    Release (done) a lease — idle it for re-adoption (--reap tears it down)
+  stack cancel <lease_id>    Give a queued lease's place up
   allocation status <id> <generation> <target_revision>  Verify managed placement before Compose
 
-${bold("DOCKER HYGIENE")}
-  docker hygiene [options]   Dry-run/apply safe stale Supabase cleanup on OrbStack
-  docker preflight [options] Refuse a managed-stack start before network pressure exhausts the host
-  docker help                Full explicit-context safety contract
-
-${bold("GO DAEMON")}
-  daemon <render|install|status|enroll|bootstrap> …
-                             Verify and manage the native Go daemon service
-
-${bold("DURABLE WORKLOADS")}
-  run --session-id <id> --environment <env> -- <command>
-                              Launch a receipt-bearing command under a detached owner
-  run --foreground --kind <kind> --environment <env> -- <command>
-                              Run locally with a durable lifecycle outbox
-  telemetry <status|replay|doctor>
-                              Inspect, replay, or gate durable lifecycle delivery
+${bold("TEST LANES")}
+  test <lane> [--ticket <KEY>] [--pr <n>] [--wait] [-- <extra args>]
+                             Run a lane from .botbuddy/lanes.json as a tracked test run
+  test list                  List the configured lanes (${cyan("bb test --help")})
   test-ingest --file <payload.json|-> [--tenant <slug>]
-                              Upload a test-run report with this worktree's agent session
-
-${bold("USAGE INGEST")}
-  usage sync [--since 2d] [--provider claude|codex|all] [--file <transcript>] [--dry-run] [--quiet]
-                              Send local Claude/Codex token usage (counters only, no prompts)
-  usage status                Last sync runs and tracked transcripts
+                             Upload a test-run report with this worktree's agent session
 
-${bold("AGENT WAITS")}
-  wait [--any] <condition>... [options]
-                              Wait once for a pushed BotBuddy signal
-
-${bold("BROWSER LANES")}
+${bold("BROWSER LANES")}  (${cyan("bb pw --help")})
   pw <lane> <verb> [args…]    Drive a lock-gated Playwright lane
                               (also the short ${cyan("pw")} binary, or ${cyan("bb-pw")} alias)
   pw <lane> verdict pass|fail Record the session's acceptance verdict
                               (sessions report live timing/results; start one
                               with --environment <env> or BB_PW_ENV)
-  pw --help                   Show lane usage
 
 ${bold("STAGING SIGN-IN")} (BOT-2084)
   pw --environment staging <lane> auth --persona <alias>
@@ -284,10 +299,56 @@ ${bold("STAGING SIGN-IN")} (BOT-2084)
                               Human only, any directory (${cyan("bb staging-pool --help")})
   help symptom staging-pool   Every refusal code with its cause and next command
 
-${bold("OTHER")}
-  locks -m [--host name]    Reserve typed local resources, including Playwright MCP lanes
+${bold("LOCKS")}
+  locks -m [--host name]     Reserve typed local resources, including Playwright MCP lanes
+  lock <resource_name> <type>  Acquire one named lock (acquire_lock)
+  unlock <resource_name>     Release one named lock (release_lock)
+
+${bold("DURABLE WORKLOADS")}  (${cyan("bb help run")})
+  run --session-id <id> --environment <env> -- <command>
+                              Launch a receipt-bearing command under a detached owner
+  run --foreground --kind <kind> --environment <env> -- <command>
+                              Run locally with a durable lifecycle outbox
+  run inspect|cancel <run_id> Read or stop one command run
+  telemetry <status|replay|doctor>
+                              Inspect, replay, or gate durable lifecycle delivery
+
+${bold("EVIDENCE")}  (${cyan("bb help evidence")})
   evidence require <file>    Record an exact-head evidence disposition → botbuddy/ready
   evidence publish <file>    Publish a local evidence statement → botbuddy/ready check-run
+
+${bold("HOST + DOCKER")}
+  docker hygiene [options]   Dry-run/apply safe stale Supabase cleanup on OrbStack
+  docker preflight [options] Refuse a managed-stack start before network pressure exhausts the host
+  docker help                Full explicit-context safety contract
+  daemon <render|install|status|config-render|enroll|bootstrap> …
+                             Verify and manage the native Go daemon service (${cyan("bb help daemon")})
+
+${bold("USAGE INGEST")}
+  usage sync [--since 2d] [--provider claude|codex|all] [--file <transcript>] [--dry-run] [--quiet]
+                              Send local Claude/Codex token usage (counters only, no prompts)
+  usage status                Last sync runs and tracked transcripts
+
+${bold("SHORTCUTS")}  (thin wrappers over ${cyan("bb call <tool>")})
+  heartbeat [<current task>] Refresh this session's heartbeat (heartbeat)
+  agents                     List agents (list_agents)
+  resources                  List resources and locks (list_resources)
+  tasks                      Read the task board (botbuddy://tasks)
+  task create <title> [-d <desc>] [-p <priority>] | task claim|done <task_id>
+                             Create, claim or complete a task
+  hours [derive | set '<json>']  Read, derive or set working hours
+  browse <agents|tasks|resources|activity|settings>  Read a botbuddy:// resource
+
+${bold("CODEX BRIDGE")}
+  start [-p <port>] [-r <repo>] [-m <model>] [--no-server]
+                             Start BotBuddy (login + codex app-server + bridge); defaults:
+                             port 4500, repo = cwd, model gpt-5.4
+  codex bridge               Legacy alias of start
+  bootstrap --session-id <uuid> (--ticket-id <BOT-n> | --no-ticket-reason <reason>)
+                             Internal launcher contract: persist a wait-capable
+                             harness session without printing its secret
+
+${bold("OTHER")}
   update                     Install the latest @botbuddy/cli in the background via npm
   help                       Show this help
   version                    Show version
@@ -433,7 +494,7 @@ async function cmdToolHelp(args) {
   const res = await fetch(discoveryUrlFor(SERVER_URL, tool));
   if (!res.ok) {
     die(res.status === 404
-      ? `Unknown tool: ${tool}. Run ${cyan("bb help --tools")} to list them.`
+      ? `Unknown tool: ${tool}. Run ${cyan("bb help --tools")} to list tools, or ${cyan("bb help")} for CLI commands.`
       : `Discovery failed: ${res.status} ${res.statusText}`);
   }
   console.log(formatDiscovery(await res.json(), { tool }));
@@ -468,7 +529,10 @@ ${bold("WHEN TEST TELEMETRY IS UNAVAILABLE")}
 ${bold("WAITING")}
   Use ${cyan("bb wait 'test-run:id=<id>' --heartbeat")} only when the launch output
   contains a real test-run ID. Do not replace a missing lifecycle signal with a
-  timer or status-polling loop.`;
+  timer or status-polling loop.
+
+${bold("LANE COMMAND")}
+  ${cyan("bb test --help")} lists the flags; ${cyan("bb test list")} shows this repo's lanes.`;
 
   if (topic === "symptom" || topic === "symptoms") return `${bold("bb help symptom <name>")} — supported recovery topics
 

package/src/wait-core.mjs

@@ -459,6 +459,9 @@ const VALIDATORS = {
   },
 };
 
+// BOT-2715: the condition types `bb wait --help` must document (pinned by a test).
+export const CONDITION_TYPES = Object.freeze(Object.keys(VALIDATORS));
+
 // pr-state / pr-review share a target grammar. The spine subject_key is
 // `owner/repo#number` (github-webhook / pr_state read model convention), so a
 // condition names an owner/repo and, optionally, a PR number. Accept three forms:

package/src/wait.mjs

@@ -49,14 +49,32 @@ export function shouldRenewCachedSession(error, credentialSource, attempts) {
   return isRejectedCachedSession(error, credentialSource, attempts);
 }
 
-export const HELP = `botbuddy wait — one wait command instead of a polling loop (BOT-989)
+export const HELP = `bb wait — one wait command instead of a polling loop (BOT-989)
+
+Park until a condition holds, then exit ONCE with one JSON receipt on stdout. Zero polling
+and zero tokens while parked. Every wait — time included — is a bb wait: never sleep loops,
+until/while polling, watch, or gh run watch. Full guide: docs/agent-wait.md.
 
 USAGE
-  botbuddy wait [--any] <condition>... [options]
+  bb wait [--any] <condition>... [options]       arm a wait (also: bb help wait)
+  bb wait <subcommand> …                         inspect or recover a saved wait (SUBCOMMANDS)
+  (botbuddy wait … is the identical long form.)
+
+  Pick the condition that proves the state your NEXT action needs, not a correlated proxy:
+    CI finished on the current PR head ......... ci:…,scope=latest,pr=<n>  (or exact sha=)
+    review activity (Codex, a human) ........... pr-review:…  (arm BEFORE requesting it)
+    PR merged/closed/conflict/ready flip ........ pr-state:…
+    your merged PR reached staging ............. staging-release:…
+    staging recovered after an incident ........ staging-green:…
+    a ticket's last blocker cleared ............ unblocked:<KEY>
+    a named bb stack run finished .............. stack-run:id=<UUID>
+    Docker capacity freed after a refusal ...... capacity:…  (copy the refusal's own condition)
+    a fixed time passed ........................ timer:…
 
 CONDITIONS  (TYPE:key=val,key=val — repeat for several; --any wakes on the first)
-  timer:duration=<seconds>            wake after N seconds (DB-clocked server-side)
-  timer:deadline=<ISO-8601>           wake at an absolute time
+  timer:duration=<seconds> | timer:deadline=<ISO-8601>
+                                      wake after N seconds (DB-clocked server-side) or at an
+                                      absolute time. Exempt from the 2 h --timeout minimum.
   chat:channel=<id>|*                 new Direct Chat message (or * = any channel you are in;
                                       you are never woken by your own messages). Level-
                                       triggered at arm: an unread reply from another
@@ -65,6 +83,7 @@ CONDITIONS  (TYPE:key=val,key=val — repeat for several; --any wakes on the fir
                                       so send-then-arm never misses a fast reply. Respects
                                       your read marker (mark_direct_chat_read) and your own
                                       last message; a sibling session's reply still wakes.
+                                      include_self= is reserved (accepted, no effect yet).
   lock:subtype=<t>,host=<h>[,slot=<s>][,claim=true]
                                       a resource lock becomes available
                                       subtype ∈ playwright_lane|vite_port|backend_port|supabase_local
@@ -82,9 +101,10 @@ CONDITIONS  (TYPE:key=val,key=val — repeat for several; --any wakes on the fir
                                       in the repo; or pass pr=<owner/repo#n> in one value. A
                                       conflict/clean flip sets payload.mergeable_changed. The
                                       payload carries head_ref_oid; sha=<head> (7-40 hex; either
-                                      side may be an abbreviated prefix) wakes only on signals for that head, so a
-                                      previous head's check result can't wake you. A push alone
-                                      emits nothing — the head rides on the next transition.
+                                      side may be an abbreviated prefix) wakes only on signals for
+                                      that head, so a previous head's check result can't wake you.
+                                      A push alone emits nothing — the head rides on the next
+                                      transition.
   pr-review:repo=<owner/repo>[,pr=<n>][,reviewer=<login>][,sha=<commit>]
                                       a submitted review, a new review comment, a thread
                                       resolved/re-opened (payload carries the unresolved-thread
@@ -96,27 +116,62 @@ CONDITIONS  (TYPE:key=val,key=val — repeat for several; --any wakes on the fir
                                       has an outstanding review at arm, bb-wait prints a one-line
                                       stderr notice (unresolved count, review_decision, age) so a
                                       silent park isn't mistaken for "no review yet" — the
-                                      existing review will not re-wake it.
+                                      existing review will not re-wake it. Your own thread reply or
+                                      resolve also wakes it: check reviewer_login + commit_sha.
                                       reviewer=<login> wakes only on that reviewer (case-
                                       insensitive; a trailing [bot] is ignored). sha=<commit>
-                                      wakes only on verdicts for that commit (either side may be an abbreviated prefix; submitted reviews
-                                      and clean passes carry commit_sha; thread comments do not,
-                                      so they never match sha=); the usage-limit decline always
-                                      passes sha=. Any other key is refused (exit 4).
-  test-run:id=<run_id>                a test run reaching a terminal status (owner-scoped)
-  lease:id=<lease_id>                 a batch stack lease (BOT-1218) leaving the queue /
-                                      becoming active — the zero-poll wake for a parked
-                                      \`botbuddy stack up\` (recipient-scoped to the owner).
+                                      wakes only on verdicts for that commit (either side may be an
+                                      abbreviated prefix; submitted reviews and clean passes carry
+                                      commit_sha; thread comments do not, so they never match sha=);
+                                      the usage-limit decline always passes sha=. Any other key is
+                                      refused (exit 4).
+  ci:repo=<owner/repo>,{scope=latest,pr=<n> | run_id=<id> | sha=<sha>[,workflow=<name>]
+                        | scope=next[,sha=<sha>][,branch=<name>][,workflow=<name>]
+                                    [,workflow_id=<id>][,workflow_path=<path>]}
+                                      a run's terminal conclusion (owner-scoped) — not a
+                                      PR state or review change (use pr-state / pr-review);
+                                      GitHub Actions or an external check_suite provider.
+                                      A repo with no CI feed is rejected (no_signal_source).
+                                      scope=latest,pr=<n> follows the PR's current head.
+                                      scope=next is LIVE-ONLY: it wakes on the first terminal
+                                      run delivered AFTER arm (post-merge / cron / scheduled),
+                                      never replays a finished run, and needs no run_id/pr.
+                                      Optional sha= pins it to a commit (BOT-1685: arm before
+                                      re-dispatching a run for a known SHA so it wakes on the
+                                      NEW run, not an earlier terminal run for the same SHA);
+                                      branch= (exact) / workflow= (GitHub workflow DISPLAY
+                                      name, case-insensitive) / workflow_id= (GitHub's numeric
+                                      id) / workflow_path= (e.g. .github/workflows/staging.yml,
+                                      exact) narrow that first run too. A filter matching no
+                                      known workflow exits 4 unknown_workflow and prints the
+                                      valid workflow=/workflow_id=/workflow_path= lines.
+  test-run:id=<run_id>                a test run reaching a terminal status (owner-scoped);
+                                      bb test <lane> prints the exact line to arm.
+  stack-run:id=<run UUID>             one named bb stack run reaching its terminal outcome
+                                      (BOT-2629). Choose the UUID BEFORE dispatch and pass it as
+                                      bb stack run --run-id <UUID>; the receipt carries exit_code,
+                                      child_exit_code, category, outcome and code. Live-only and
+                                      recipient-scoped to the run's agent. Never substitute a
+                                      lease: transition, a log tail or a polling loop.
+  lease:id=<lease_id>[,state=<s>]     a batch stack lease (BOT-1218). Without state=: the lease
+                                      leaving the queue / becoming active — the zero-poll wake
+                                      for a parked bb stack up (recipient-scoped to the owner).
                                       Level-triggered: an already-granted lease wakes at once.
-  lease:id=<lease_id>,state=<s>       BOT-2400: wait for that exact state (provisioning, active,
-                                      reaped). provisioning/active end on lease loss (exit 9,
-                                      with the provisioning failure's reason and class).
-  lease:id=<lease_id>,state=reaped    proven cleanup of that owned lease (BOT-1948). Requires an
-                                      accepted successful reap receipt or a verified
-                                      never-provisioned no-op; preserves stop/destroy
+                                      state=provisioning|active (BOT-2400): that exact state;
+                                      both end on lease loss (exit 9, with the provisioning
+                                      failure's reason and class).
+                                      state=reaped (BOT-1948): proven cleanup of that owned
+                                      lease. Requires an accepted successful reap receipt or a
+                                      verified never-provisioned no-op; preserves stop/destroy
                                       disposition. An already-cleaned lease matches at once;
-                                      reaping keeps waiting. A verified failed reap exits 12;
-                                      an unverified gave-up reap exits 9 (lease_lost).
+                                      reaping keeps waiting. A verified failed reap exits 12; an
+                                      unverified gave-up reap exits 9 (lease_lost).
+  managed-allocation:id=<allocation UUID>,generation=<n>,target_revision=<n>
+                                      one exact managed allocation reaching an accepted cleanup
+                                      outcome (BOT-2330), fenced to that generation/revision. A
+                                      released match needs a zero permit count and the exact
+                                      accepted Helper cleanup receipt; an accepted cleanup_failed
+                                      receipt exits 10. A lifecycle wait, not host capacity.
   guidance:request=<post_id>          a command-post guidance request being answered
                                       (scoped to the asking agent; fetch the body with
                                       get_guidance_response)
@@ -132,6 +187,8 @@ CONDITIONS  (TYPE:key=val,key=val — repeat for several; --any wakes on the fir
                                       Tenant-scoped. Also accepts unblocked:ticket=<KEY>.
   capacity:policy=<p>,slots>=<N>[,host=<h>][,stale_grace=<sec>]
                                       a managed-container host reaching >= N free slots.
+                                      Copy the condition a capacity refusal prints (e.g.
+                                      policy=default or host_docker_pressure_v1).
                                       Host-shared; a silently-dead host is detected server-side
                                       (capacity_source_stale) via a host beacon. BOT-2400: a stale
                                       source is DEGRADED, never terminal — the wait stays armed and
@@ -141,25 +198,21 @@ CONDITIONS  (TYPE:key=val,key=val — repeat for several; --any wakes on the fir
                                       one and its receipt carries grant:{position,tier,score};
                                       the others keep parking. Older servers broadcast without
                                       the ranking (first-come). Needs cli >= 1.20.0.
-  ci:repo=<owner/repo>,{scope=latest,pr=<n> | run_id=<id> | sha=<sha>
-                        | scope=next[,sha=<sha>][,branch=<name>][,workflow=<name>]}
-                                      a run's terminal conclusion (owner-scoped) — not a
-                                      PR state or review change (use pr-state / pr-review);
-                                      GitHub Actions or an external check_suite provider.
-                                      A repo with no CI feed is rejected (no_signal_source).
-                                      scope=next is LIVE-ONLY: it wakes on the first terminal
-                                      run delivered AFTER arm (post-merge / cron / scheduled),
-                                      never replays a finished run, and needs no run_id/pr.
-                                      Optional sha= pins it to a commit (BOT-1685: arm before
-                                      re-dispatching a run for a known SHA so it wakes on the
-                                      NEW run, not an earlier terminal run for the same SHA);
-                                      branch= (exact) / workflow= (GitHub workflow DISPLAY
-                                      name, case-insensitive) narrow that first run too.
   staging-green:repo=<owner/repo>    verified automatic recovery of an enabled staging gate.
                                       Wakes only after a complete non-vacuous workflow success;
                                       manual resolutions, overrides, skipped, and neutral runs do not match.
+  staging-release:repo=<owner/repo>,pr=<n>[,after_run=<run_id>[:<attempt>]]
+                                      the first staging release train whose head CONTAINS your
+                                      merged PR (git ancestry, never timestamps) reaching a
+                                      terminal conclusion — success OR failure (payload.conclusion
+                                      + verified; on verified:false check staging yourself).
+                                      Level-triggered: a train that already shipped your merge
+                                      grants at once (payload.reason=already_released).
+                                      after_run= skips a run you already saw, so a wait re-armed
+                                      from a failure receipt parks for the NEXT train.
   event:type=<signal_type>[,subject=<key>]
-                                      raw signal-spine match (escape hatch). Host setup uses
+                                      raw signal-spine match (escape hatch only when that raw
+                                      signal IS the outcome). Host setup uses
                                       event:type=host_approval,subject=bbh-<24 lowercase hex>;
                                       it wakes only for the authenticated owner's one bound
                                       tenant after current server-side approval revalidation.
@@ -181,25 +234,32 @@ OPTIONS
                         (--agent-key and --session-token are one-release aliases.)
   --session-id <uuid>   advanced attribution override; normal worktrees derive it automatically.
   --help                show this help
-  resume <local_wait_id>       recover one explicitly named saved wait
-  result [<local_wait_id>]     read its terminal receipt without rearming or acknowledging
-    [--from-file <path> --exit-code <n>]
-                              validate redirected output AFTER the original command exits
-  cancel <local_wait_id>       explicitly stop one saved wait
-  acknowledge <local_wait_id>  mark one saved terminal receipt read
+
+SUBCOMMANDS  (saved waits live in this worktree's .botbuddy/waits/)
+  bb wait                      List this worktree's saved waits (after a restart or crash);
+                               [--offset <n>] pages. Non-interactive callers get JSON.
+  bb wait result [<local_wait_id>] [--from-file <path> --exit-code <n>]
+                               read a terminal receipt without re-arming or acknowledging;
+                               --from-file validates redirected output AFTER the original
+                               command exits (see EXAMPLES)
+  bb wait resume <local_wait_id>       recover one explicitly named saved wait
+  bb wait cancel <local_wait_id>       explicitly stop one saved wait
+  bb wait acknowledge <local_wait_id>  mark one saved terminal receipt read (after acting on it)
 
 AUTH
   In a configured project worktree, bb wait restores or renews its session automatically.
-  For first-time setup or repair, run bb setup once, then retry the same wait. No environment
-  variables, copied identifiers, or credential flags are needed for normal waits.
+  For first-time setup or repair, run bb setup once (bb doctor --fix for a stale session),
+  then retry the same wait. No environment variables, copied identifiers, or credential
+  flags are needed for normal waits.
   --token and --profile are RETIRED (BOT-1574); the session override above is for managed
   runners only. The per-machine client key is a setup credential, never a wait credential.
 
 OUTPUT
   Exactly one JSON receipt line on stdout at exit, with client semver and
   protocol identity. Diagnostics go to stderr — including the arm-time notices
-  (outstanding review, latest CI run). Do not pipe bb wait through tail: the
-  notice is on stderr and you will not see it until the wait exits.
+  (outstanding review, latest CI run) and the 🔗 /waits link to show the user.
+  Do not pipe bb wait through tail: the notice is on stderr and you will not
+  see it until the wait exits.
   Exit codes: 0 matched · 2 timeout · 3 auth · 4 invalid conditions ·
               5 backend unavailable · 6 cursor expired · 7 internal ·
               8 superseded (wait replaced server-side) · 9 lease lost (a
@@ -216,24 +276,78 @@ OUTPUT
                 only on a queued/busy result (granted = you hold it — just resume);
                 otherwise re-run from the receipt's next_cursor. docs/agent-wait.md.
 
-EXAMPLES
-  # wait for a Playwright lane to free up, then acquire it yourself
-  botbuddy wait 'lock:subtype=playwright_lane,host=Jonos-MBP'
+EXAMPLES  (concrete values shown — substitute your repo, PR, SHA, ticket and ids)
+  # Wait for time. The ONLY sanctioned way to wait N seconds or until a clock time.
+  bb wait 'timer:duration=1800'
+  bb wait 'timer:deadline=2026-11-02T09:05:00Z'
+
+  # After a push: CI on the PR's current head finished (any conclusion).
+  bb wait 'ci:repo=bot-buddy/botbuddy-webapp,scope=latest,pr=1234' --heartbeat
+
+  # After a merge or a re-dispatch: the NEXT run for that exact commit (arm first, then dispatch).
+  bb wait 'ci:repo=bot-buddy/botbuddy-webapp,scope=next,sha=9f3c2a1b4d5e6f708192a3b4c5d6e7f809a1b2c3' --heartbeat
+  bb wait 'ci:repo=bot-buddy/botbuddy-webapp,scope=next,branch=main,workflow_path=.github/workflows/staging.yml' --heartbeat
+
+  # Codex review of the head you just pushed (arm BEFORE posting @codex review).
+  bb wait 'pr-review:repo=bot-buddy/botbuddy-webapp,pr=1234,reviewer=chatgpt-codex-connector[bot],sha=9f3c2a1' --heartbeat
+
+  # The next review comment OR a PR state change (merge, conflict, checks), whichever first.
+  bb wait --any 'pr-review:repo=bot-buddy/botbuddy-webapp,pr=1234' \\
+                'pr-state:repo=bot-buddy/botbuddy-webapp,pr=1234,sha=9f3c2a1' --heartbeat
+
+  # A ticket changes (state, comment, assignee) / its last blocker clears.
+  bb wait 'linear:issue=BOT-1234' --heartbeat
+  bb wait 'unblocked:BOT-1234' --heartbeat
+
+  # Your merged PR reached staging (success or failure) / staging recovered.
+  bb wait 'staging-release:repo=bot-buddy/botbuddy-webapp,pr=1234' --timeout 28800 --heartbeat
+  bb wait 'staging-green:repo=bot-buddy/botbuddy-webapp' --heartbeat
+
+  # A named stack run finished: choose the UUID, arm, then bb stack run --run-id <same UUID> -- ...
+  bb wait 'stack-run:id=2f9d6a3c-0b1e-4c5d-8e7f-1a2b3c4d5e6f' --heartbeat
 
-  # queue for a specific lane and be HANDED it when it frees (no acquire race):
-  #   acquire_lock (gets queued) → bb-wait claim=true → wake already holding lane 3
-  botbuddy wait 'lock:subtype=playwright_lane,host=Jonos-MBP,slot=3,claim=true' --heartbeat
+  # A parked lease was granted / a lease's cleanup was proven.
+  bb wait 'lease:id=7c1e2d3f-4a5b-4c6d-8e9f-0a1b2c3d4e5f' --heartbeat
+  bb wait 'lease:id=7c1e2d3f-4a5b-4c6d-8e9f-0a1b2c3d4e5f,state=reaped'
 
-  # wait for a chat reply on any channel, or 20 minutes, whichever first
-  botbuddy wait --any 'chat:channel=*' 'timer:duration=1200' --heartbeat
+  # Docker capacity after HOST_CAPACITY_SOURCE_STALE (phase transient) or a pressure refusal:
+  # copy the refusal's own condition, then re-run the refused command once.
+  bb wait 'capacity:policy=host_docker_pressure_v1,slots>=1' --heartbeat
 
-  # after pushing review fixes, wait for the next review comment or a state change
-  botbuddy wait --any 'pr-review:repo=bot-buddy/botbuddy-webapp,pr=425' \\
-                'pr-state:repo=bot-buddy/botbuddy-webapp,pr=425'
+  # A tracked test run finished (bb test <lane> prints this line with the real id).
+  bb wait 'test-run:id=5b0c7e2a-9d41-4f3e-8a6b-1c2d3e4f5a6b' --heartbeat
+
+  # Wait for a Playwright lane to free up, then acquire it yourself.
+  bb wait 'lock:subtype=playwright_lane,host=Jonos-MBP'
+
+  # Queue for a specific lane and be HANDED it when it frees (no acquire race):
+  #   acquire_lock (gets queued) → bb wait claim=true → wake already holding lane 3
+  bb wait 'lock:subtype=playwright_lane,host=Jonos-MBP,slot=3,claim=true' --heartbeat
+
+  # A Direct Chat reply on any channel you are in (arm before sending).
+  bb wait 'chat:channel=*' --heartbeat
+
+  # Redirect a wait's output and still return its receipt: run these three lines as ONE
+  # pending (background) command, and keep that command's result pending until it exits.
+  wait_artifact=$(mktemp /tmp/bb-wait-result.XXXXXX); wait_exit=0
+  bb wait 'pr-review:repo=bot-buddy/botbuddy-webapp,pr=1234,sha=9f3c2a1' --heartbeat > "$wait_artifact" 2>&1 || wait_exit=$?
+  bb wait result --from-file "$wait_artifact" --exit-code "$wait_exit"
+
+  # After a restart: list saved waits, then recover exactly one by id.
+  bb wait
+  bb wait resume <local_wait_id>
 
 ${SETUP_BLOCK}
 `;
 
+// BOT-2715: exit only once stdout has taken the whole text. On a macOS pipe the
+// write is async, so a process.exit() straight after it can drop everything past
+// the first 8 KiB (CI cut the ~22 KiB help at exactly 8192 bytes). Never resolves:
+// the process ends in the write callback.
+export function writeThenExit(text, { stream = process.stdout, exit = (code) => process.exit(code) } = {}) {
+  return new Promise(() => { stream.write(text, () => exit(EXIT.MATCHED)); });
+}
+
 // BOT-2400: a wait's timeout is a SAFETY CAP measured in hours or days, never a polling
 // interval. Each re-arm wakes the agent and re-reads its whole context (ENT-4850 §18: 15
 // wakes ≈ 50M tokens), so the default is a day, the cap three days, and a cap under two hours
@@ -1121,10 +1235,7 @@ async function inspectSavedWaits(argv = []) {
     });
     process.exit(EXIT.MATCHED);
   }
-  if (inventory.items.length === 0) {
-    process.stdout.write(HELP);
-    process.exit(EXIT.MATCHED);
-  }
+  if (inventory.items.length === 0) return writeThenExit(HELP);
   // A TTY gets discovery guidance without an implicit selection. This is a
   // deliberately conservative menu: a restart must name an ID before mutation.
   process.stdout.write("Saved bb waits:\n");
@@ -1608,10 +1719,7 @@ export async function runWait(argv, { recoveryLocalWaitId = null } = {}) {
     writeLeaseLostNotice(receipt);
     return emit(receipt, { ...options, maxBytes: opts.receiptMaxBytes });
   };
-  if (opts.help) {
-    process.stdout.write(HELP);
-    process.exit(0);
-  }
+  if (opts.help) return writeThenExit(HELP);
   // BOT-1574 (AC3): --token / --profile are retired. Emit the migration hint and
   // a typed `unknown_option` receipt, then exit 4 — before any relay call.
   if (opts.retiredFlag) {