@ebrindley/build 0.0.0-stage → 1.42.1-rc28

package/docs/reference/TELEMETRY_PRIVACY.md

@@ -0,0 +1,259 @@
+# Telemetry And Privacy Reference
+
+Build telemetry is local-first, and there is one place it is written: the shared
+telemetry directory under the Build data root, `~/.build/data/telemetry/` by
+default. The SQLite databases live in its `db/` subdirectory (`variants.db`,
+`validations.db`), `invocations.db` sits beside that directory, and JSONL logs go
+under `logs/`. An ordinary run writes no database inside the repository, and the main
+JSONL log stream follows the resolved database directory, so deleting a clone or a
+worktree never deletes that execution history, and two checkouts of one repository
+share one store (rows carry `project_id`, `builder_id`, `lab_id`). `builder_id` is
+`local-` plus the first 16 hex characters of a SHA-256 over the repository path and
+your `git config user.email`; the email itself is not stored, and without a
+configured email the value is `local-unknown`.
+
+Two things still live in the checkout. Per-run state — competition handoffs, variant
+state, and event streams — is written under `.build-project/telemetry/state/` in the checkout that ran
+them, because `build monitor`, `build find`, orphan detection, and the reliability
+commands read those files directly from the working tree. That state is reproducible
+working data, not execution history. Flywheel workflow telemetry follows the same
+resolved telemetry directory as the main stream (`logs/<month>/` under it).
+
+A lab run is the second. `--lab-id`/`--run-id` keeps everything inside a throwaway
+run tree that is never mixed into the shared store. Before a data-migration marker
+exists, that tree is
+`.build-project/labs/{labId}/runs/{runId}/` in the checkout (`telemetry/db/` and `logs/`
+under it). After a marker exists, `resolveProjectRuntimeDir` relocates `labs/` to
+`{projectDataDir}/labs/` (typically under the Build data root). Discarding the
+resolved lab tree is how a lab run is meant to end. `build doctor --verbose`
+prints the resolved telemetry directory; `build data status` names the project
+data directory.
+
+The write location resolves in this order, highest first:
+
+1. `BUILD_TELEMETRY_DB` — explicit override, used by tests and CI.
+2. A lab run (`--lab-id`/`--run-id`), which writes into its own throwaway run tree
+   under `.build-project/labs/{lab}/runs/{run}/telemetry`.
+3. `telemetry.database` in `build.config.jsonc`. DEPRECATED: set it only to
+   relocate telemetry outside the repository. A value equal to the old repo-local
+   default (`.build-project/telemetry/db/variants.db`) is ignored, and any other value is
+   honored with a one-time deprecation warning.
+4. The data root.
+
+`BUILD_DATA_DIR`, `BUILD_HOME`, and `XDG_DATA_HOME` move the data root itself.
+
+Older versions wrote databases into the repository's `.build-project/telemetry/db/`
+tree. That `db/` path is never read or written now; `build doctor --verbose`
+reports leftover checkout `db/` as an advisory, and `build data migrate execute`
+merges those databases into the data root. Checkout `state/` (per-run) is still
+live, as described above; checkout `logs/` holds only flywheel JSONL from older
+versions. Advanced-workflow
+synthesis artifacts write under the resolved telemetry directory
+(`~/.build/data/telemetry/synthesis/` by default; `build doctor --verbose`
+prints the resolved path), not under checkout `.build-project/telemetry/synthesis/`.
+
+Build does not send telemetry to a Build-hosted service. Provider CLIs still
+make their own network calls and may have their own telemetry, logging, and
+retention behavior.
+
+Portable `.ptel` bundles are local files created by `build telemetry bundle export` or the
+default-on ephemeral wrapper `build telemetry replicate`. They contain only allowlisted structured fields and omit local
+diagnostic text, prompts, commands, paths, rationales, arbitrary JSON, and provider output.
+Creating a bundle does not upload it. An external VM launcher may retrieve a bundle through its
+configured artifact channel when ephemeral replication is enabled. Import writes to a separate portability database. Imported
+execution evidence is included by cost read models through a deduplicated projection; it does not
+rewrite live execution rows or feed routing/calibration.
+
+## Usage And Cost Evidence
+
+Usage telemetry contains structured numeric evidence only. Prompt text, responses, tool arguments,
+credentials, and arbitrary provider payloads are not usage evidence.
+
+Input, output, cache-read, cache-creation/write, reasoning, and tool-token dimensions are retained
+independently when a provider emits them. Each provider declares structured usage as supported,
+best-effort, or unsupported. Kiro currently declares it unsupported. Antigravity reports
+input, output, thinking, and cache-read usage in authenticated `agy` stream-JSON runs; it does
+not currently report cache-creation tokens or monetary cost.
+
+Build stores API-equivalent list-price cost separately from cost explicitly reported by a
+provider. API-equivalent cost is not actual subscription spend. When both amounts exist, Build
+retains the comparison delta. Pricing snapshots are immutable and include cache and long-context
+rules in their content identity.
+
+Portable format v2 includes invocation attempts, usage evidence, pricing snapshots, and cost
+evaluations. Repeated import is content-addressed and idempotent.
+
+## What Build Stores Locally
+
+Build can store:
+
+- Prompts and prompt metadata: competition state JSON can include the original
+  prompt text; SQLite rows can include prompt versions, prompt hashes or
+  fingerprints, prompt lengths, prompt token counts, and prompt file paths.
+- Repository and path data: project identifiers, task IDs, competition IDs,
+  worktree paths, changed-file counts, file target paths, file touch paths,
+  directory paths, and git commit SHAs before or after execution.
+- Provider metadata: provider, requested provider, model, requested model,
+  resolved model, strategy, execution mode, workspace mode, guidance profile,
+  reasoning effort, provider readiness failover details, cloud compatibility
+  fields for older records, and provider status or error codes.
+- Execution outcomes: timestamps, duration, verdict, completeness, success or
+  failure, termination reason, PR number or URL when applicable, validation
+  command names, validation exit codes, and bounded validation output tails.
+- Output and error excerpts: telemetry state and provider-history records may
+  contain output tails, error messages, raw excerpts, judge failure excerpts,
+  and summarized provider stream events. These are for debugging and should be
+  treated as potentially sensitive.
+- Judge and synthesis metadata: judge model, rubric version, scores,
+  confidence, rationale, winner selection metadata, attribution warnings,
+  synthesis status, and calibration fields.
+- Cost and usage data: input tokens, output tokens, cached-token fields when
+  reported, request sizes, time to first token, total time, pricing snapshots,
+  computed costs, daily cost aggregates, and advisory cost forecasts.
+
+Do not put secrets in prompts. The macOS sandbox does not prevent provider
+CLIs from reading every broadly-readable file, and provider CLIs have outbound
+network access.
+
+## Retention Defaults
+
+The current compiled defaults come from `src/telemetry/retention-config.ts`:
+
+| Data | Default retention |
+| --- | --- |
+| JSONL telemetry logs | 90 days |
+| Root signal JSONL files (`signals-*.jsonl`) | 90 days |
+| Run records in `variants.db`, soft pruning | 180 days |
+| Run records in `variants.db`, warning/aggressive pruning | 90 days |
+| Invocation history (`invocations.db`) | not pruned |
+| Backup archives | 30 days |
+| Monthly backup archives beyond normal backup retention | 3 monthly archives |
+| Maximum retained telemetry backups | 1 GiB |
+| Cleanup log files | 7 days |
+| VACUUM after cleanup | enabled |
+
+The automatic SQLite pruning windows apply only to the variant execution, judge, and
+verification tables in `variants.db` (with their child rows), and only when that
+database grows past a size threshold: 1.5 GiB triggers the 180-day pass and 2 GiB
+triggers the 90-day pass (`BUILD_DB_SOFT_LIMIT` and `BUILD_DB_WARNING_LIMIT`
+change these). A smaller database is not pruned by age, and at the hard limit
+(5 GiB, `BUILD_DB_HARD_LIMIT`) startup cleanup stops with an error instead of
+pruning. Invocation history in
+`invocations.db`, which records every provider execution attempt, has no
+retention window: cleanup only compacts it (VACUUM), and it is kept until you
+delete it. The supported way is to remove the shared telemetry directory, as
+described under Delete Or Prune Local Data.
+
+Environment variables can override the JSONL and SQLite retention windows:
+
+```bash
+BUILD_TELEMETRY_RETENTION_DAYS=30 build telemetry health
+BUILD_TELEMETRY_SIGNALS_RETENTION_DAYS=30 build telemetry health
+BUILD_DB_SOFT_RETENTION_DAYS=90 build telemetry health
+BUILD_DB_WARNING_RETENTION_DAYS=30 build telemetry health
+```
+
+Project config can override backup and cleanup-log retention under
+`telemetry.retention` in `.build-project/config/build.config.jsonc`:
+
+```jsonc
+{
+  "telemetry": {
+    "retention": {
+      "backups_days": 14,
+      "backups_monthly_count": 1,
+      "backups_max_bytes": 536870912,
+      "logs_days": 7,
+      "vacuum_on_cleanup": true
+    }
+  }
+}
+```
+
+## Disable Telemetry
+
+Build recognizes `BUILD_TELEMETRY_ENABLED=0` in its configuration layer.
+Use it when you want commands to resolve telemetry as disabled:
+
+For one command:
+
+```bash
+BUILD_TELEMETRY_ENABLED=0 build run "Your task" --provider grok
+```
+
+For the current shell:
+
+```bash
+export BUILD_TELEMETRY_ENABLED=0
+```
+
+This is not a confidentiality control and does not disable telemetry owned by
+provider CLIs. Some operational state may still be written by command paths
+that need local recovery data. For runs where you do not want retained project
+telemetry, redirect Build telemetry to a temporary location and delete it when
+the run finishes:
+
+```bash
+tmpdir="$(mktemp -d)"
+BUILD_TELEMETRY_DIR="$tmpdir/.build-project" \
+  BUILD_TELEMETRY_DB="$tmpdir/telemetry.db" \
+  build run "Your task" --provider grok
+rm -rf "$tmpdir"
+```
+
+## Delete Or Prune Local Data
+
+Preview stale telemetry cleanup:
+
+```bash
+build cleanup stale --only telemetry
+```
+
+Execute stale telemetry cleanup:
+
+```bash
+build cleanup stale --only telemetry --execute
+```
+
+Preview governed TTL cleanup, including telemetry artifacts and database
+backups covered by cleanup prune policies:
+
+```bash
+build cleanup prune
+```
+
+Execute governed TTL cleanup:
+
+```bash
+build cleanup prune --execute
+```
+
+To delete telemetry, stop running Build processes first, then remove the shared
+telemetry directory under the data root:
+
+```bash
+rm -rf ~/.build/data/telemetry
+```
+
+This is shared by every project on the machine. `build doctor --verbose` prints the
+resolved directory; check it before deleting, because `BUILD_TELEMETRY_DB`,
+`telemetry.database`, `BUILD_DATA_DIR`, `BUILD_HOME`, and `XDG_DATA_HOME` all move
+it. When `BUILD_HOME` is set and no explicit data root is configured, telemetry is
+under `$BUILD_HOME/data/telemetry/`. Live synthesis artifacts live in `synthesis/`
+under that same resolved directory.
+
+A repository that was used with an older Build version may still hold
+`.build-project/telemetry/`. Do not delete that whole directory: as described above, `state/`
+holds live per-run data that is still read. Checkout `db/` is leftover SQLite only,
+and checkout `logs/` holds flywheel JSONL from older versions. Run `build data migrate execute` to
+merge those databases into the data root, then you may remove just `db/`:
+
+```bash
+rm -rf .build-project/telemetry/db
+```
+
+Do not delete checkout `.build-project/telemetry/synthesis/`. It is not a migrate source,
+and `build data migrate execute` can delete checkout JSONL shards whose destination
+already exists (including old flywheel shards that share `YYYY-MM/YYYY-MM-DD.jsonl`
+names with the data-root stream). `build doctor --verbose` reports leftover checkout `db/` and leftover
+checkout `synthesis/` and stays silent when neither is present.

package/integrations/bb-plugin-build/README.md

@@ -0,0 +1,391 @@
+# Build for BB (local development)
+
+This optional, full-trust BB plugin presents Build planning state, searchable task, sprint, and
+backlog work, task/sprint execution, local Fusion and judged competition runs, and tracked backlog
+execution. Build remains the planning,
+orchestration, provider, judge, and result authority. The plugin keeps no backlog database, provider credentials, run
+ledger, daemon, or independent provider execution path.
+
+## Installation and enablement
+
+Prerequisites: a running BB server with plugin SDK `0.4.x`, Build `1.x` or a calendar release (`YYYY.M.D`), and one BB project
+whose local source is the root of an initialized Build Git repository.
+
+Build alone is the default. The optional visual path reuses the existing
+provider setup surface (no new Build command family) and BB's native plugin
+installer:
+
+```bash
+build provider setup --bb
+```
+
+That command prints the Build plugin version, detected BB version, plugin SDK
+range, and full-trust permission implications before enablement. Missing BB, an
+incompatible BB version, a missing plugin package, or install failure leaves
+standalone Build unchanged and prints a recovery path. Provider credentials
+and auth files are never read or copied.
+
+An older local-path registration is not replaced implicitly. After reviewing
+the disclosure, rerun with `--bb --reinstall` to replace it. Reinstalling the
+same path is idempotent. To move the plugin, Build asks BB to install the new
+path directly so BB can preserve the plugin's settings, secrets, and schedules.
+A failed explicit replacement reports BB's observed installed state and leaves
+the existing registration in place. A failed first-time registration is removed
+automatically when Build can prove it created it.
+
+When the panel sees exactly one local BB project source it selects it
+automatically; zero or multiple sources require an explicit user choice.
+
+## SDK compatibility and host-test contract
+
+The committed declaration files are development inputs for editors, TypeScript,
+and CI. They are excluded from Build's published npm package and are not read
+or regenerated during end-user setup. `types/PROVENANCE.json` records their BB
+source commit, SDK version, generation method, digests, and byte lengths.
+
+Regenerate declarations for development from a BB checkout with the recorded
+`generation.command`, then update `upstream.sourceCommit`, `sha256`, and
+`byteLength` in `types/PROVENANCE.json`.
+
+The focused backend/RPC test loads the real `server.ts` factory directly into
+BB's official `@bb/plugin-sdk/testing` `createFakePluginHost`. Point
+`BB_SOURCE_ROOT` at a checkout of the recorded source commit and run:
+
+```bash
+BB_SOURCE_ROOT=/path/to/bb npx vitest run \
+  --config integrations/bb-plugin-build/vitest.host.config.ts
+```
+
+This exercises BB's actual contract registration and strict runtime validation
+without copying its test-host implementation into Build. The test-only runtime
+is resolved from the supplied checkout; standalone Build and its ordinary test
+suite do not import BB or require BB to be installed.
+
+### Local development
+
+```bash
+cd /absolute/path/to/build/integrations/bb-plugin-build
+npm install
+bb plugin install /absolute/path/to/build/integrations/bb-plugin-build
+bb plugin dev /absolute/path/to/build/integrations/bb-plugin-build
+```
+
+Open the `Build` navigation panel and select the BB project source when
+auto-association does not apply. The workbench nav is Overview, Plan, Run, and
+Settings. Backlog list and detail live under Plan (`plan/backlog`); run list and
+detail live under Run (`run`); Settings remounts the former setup workspace
+(`settings`, with `setup` as an alias). Older `backlog` and `runs` paths parse
+to the same kinds. If the BB server does not inherit the shell
+path that contains `build`, set the plugin's `Build executable` setting to an
+absolute path and reload the plugin.
+
+Run contains one client-side work browser with Tasks, Sprints, and Backlog tabs. Tasks and sprints
+include active and archived Build records and can be searched, filtered, and sorted without
+adding server-side query state or a BB planning mirror. A task opens its existing Plan detail or
+runs through its owning sprint; a sprint can be inspected or run. Backlog items retain the
+existing Run, Compete, and Fusion actions.
+
+## Trust and effects
+
+BB plugins execute with full host trust. Every launch confirmation discloses
+that this backend starts the installed `build` executable as the current host
+user with the selected canonical repository as `cwd`. It passes an argv array
+with `shell: false`; the RPC contract exposes no arbitrary executable, argv,
+environment, cwd, or file-read method.
+
+Fusion launches `build run fusion --backlog-item <id> --json`. Build resolves the
+canonical backlog body; BB does not copy task content into process arguments. That action
+may use the user's native provider authentication and create local worktrees,
+logs, or artifacts. It does not mutate/synchronize Build's managed planning
+files and does not push Git changes. The plugin never adds `--allow-main` or
+changes Build's consent policy. Protected branches are disclosed; detached
+HEAD, a non-root/wrong repository, an uninitialized Build repository, and
+incompatible Build or snapshot major versions are blocked explicitly.
+
+Competition launch has its own consent and starts only
+`build run competition --backlog-item <id> --judge ai --configured-defaults --json`.
+Build resolves the configured variants and models, owns judging, and publishes
+the versioned start envelope before BB begins its existing competition-results
+polling. BB adds no provider picker, judge implementation, retry loop, or run
+store. Competition cards take lifecycle, phase, candidate status, and compatibility
+from Build's canonical `operationalReadbackV1`, without combining it with legacy
+result fields. After BB loses its exact child-process handle, the run remains observable
+from Build but is not cancellable or automatically restarted.
+
+Tracked execution has a separate RPC and consent schema. It launches only
+`build plan backlog execute <id>` with no bypass flags. Build owns repository-readiness checks.
+The disclosure states that canonical Build may create or switch branches,
+synchronize managed planning state, invoke native provider authentication,
+create commits, push changes, and open a PR. BB does not implement any of those
+steps. Finalization wraps the exact
+`build plan backlog finalize <id> --pr <n> --commit <sha>` argv under high
+consent; Build still owns the lifecycle. BB never invents the PR number or
+commit SHA and never implements `--auto` finalize.
+
+Task and sprint execution use the same typed surface over `build run sprint`. BB first displays
+Build's canonical preflight task, stage, warning, and error projection. BB separately discloses the
+fixed repository effects of the selected launch. Review
+offers **Use default**, **Off**, **Block**, and **Repair**, with full Critical, High, Medium, and Low
+levels for Block and Repair. Use default omits `--review`; BB displays the effective policy and a
+friendly source such as `Set by user environment`, `Set by project configuration`, or `Set by
+Build default`. An explicit choice applies only to that run. Launch re-runs preflight immediately
+and invokes only the fixed `--apply --detach --json` command, without a retry after an ambiguous
+result.
+
+## Planning authoring and sprint composition
+
+BB provides bounded forms over Build's existing planning authority. Backlog
+authoring can capture and edit items, mark them reviewed, and set priority;
+custom-task authoring can create or edit an operator-authored task, add or remove
+task dependencies, and link a task to a backlog item. Sprint composition can
+create or rename a sprint, add backlog work as a new task, detach a task without
+deleting it, and migrate a task between sprints while preserving its id and
+resetting its status to `todo`.
+
+Each confirmed action runs once against the selected repository and branch.
+Build mints identities, applies mutations, and remains authoritative for
+status, membership, capacity, integrity, and sync evidence; BB displays changed
+facts only after authoritative rereads. The confirmation discloses that
+Build's built-in managed sync may commit and push planning changes, and BB does
+not suppress or replace that sync. Backlog bodies are sent over stdin and are not
+placed in reported process arguments. BB verifies that the selected branch did
+not move, but Build decides whether each planning command is valid on that branch.
+
+This surface wraps one-item finalize and single-sprint close under high consent.
+It still does not defer or archive-backlog, `--force` close, refine
+items, or select providers or models. Those remaining concerns stay in their
+existing Build-owned workflows.
+
+## Read and polling contract
+
+- The planning workspace reads the versioned projection carried by
+  `build plan sprint status --json` when the panel selects a repository. It
+  presents Build's sprint, task, dependency, blocker, ownership, active-work,
+  and advisory sync evidence without keeping a planning mirror. Older Build
+  versions and malformed or unavailable evidence render as unavailable rather
+  than as an empty or healthy workspace.
+- Planning state is not attached to run polling, the background service, or the
+  30-second watchdog. Selecting or reopening a repository performs one fresh
+  planning read; when a tracked execute card first becomes terminal the panel
+  issues one additional `planningWorkspace` refetch. The adapter does not.
+  No planning poller, cache, heartbeat, or daemon is added.
+- Backlog list/detail comes from `build plan backlog list/show --json` on each
+  request. No BB task store is used.
+- The work browser's complete task catalog comes from fixed argv `build plan task list --all
+  --json`; sprint rows come from `build plan sprint list --json`. Search, filters, and sorting are
+  transient panel state and never change either command.
+- Detached task/sprint cards poll fixed argv `build run flywheel status <workflow-id> --json` and
+  consume only Build's versioned `operationalReadbackV1`. The card shows canonical task/stage,
+  execution, apply, branch, and commit state. When it first becomes terminal, BB refreshes the
+  planning workspace and work-browser lists once.
+- Tracked-execution cards also come from that item-specific, kind-tagged
+  operational readback. Branch, workflow, commit, verification, PR, blocker,
+  and finalization evidence is rendered only when Build publishes it.
+- Fusion's versioned `build.run.started` line supplies the run ID. The plugin
+  never guesses it from directories or prose.
+- BB's background service owns the authoritative cadence: it polls
+  `build run fusion results <run-id> --json` server-side every 2.5 seconds while any
+  run is non-terminal, and every 30 seconds otherwise. The response carries
+  `RunSnapshotV1` and Build's deterministic `runProgressV1` projection. A
+  repository is polled only while a panel has asked about it in the last five
+  minutes; the service's own reads do not extend that window.
+- The frontend keeps connection/watchdog behavior only. It refetches on an
+  ephemeral realtime signal, after the shared connection returns from
+  `reconnecting`, and on a 30-second watchdog floor.
+- Realtime is ephemeral invalidation, not Build run-event authority. The signal
+  names the repository to refetch plus advisory counts; it carries no status,
+  phase, progress, verdict, or evidence, and it is published only after the
+  server's authoritative read completes. A dropped signal costs a refresh, never
+  correctness.
+- The same response optionally carries Build's read-only `judgeOperationsV1`
+  projection, which the card renders as the judge operations cockpit (see below).
+- Operation handles are bounded, plugin-process-local startup supervision. Kind-specific run state
+  remains inspectable from Build; a detached sprint card intentionally has no standalone command
+  because its complete supported status is already presented in BB.
+- Evidence entries retain the run ID and canonical repository so commits,
+  branches, changed files, verification, synthesis, and artifacts cannot cross
+  between concurrent cards.
+
+## Judge operations cockpit
+
+Build decides every judge outcome; the cockpit only presents what Build already
+recorded. A competition launched from a reviewed backlog item or adopted by entering
+a known run ID reuses the existing run-card polling path. BB persists no run state,
+and the standalone authority remains `build run competition results <run-id> --json`. It adds
+no polling mechanism, persistence, command, or gate, and it never
+recomputes a score, selects or overrides a winner, reruns a judge, adjudicates on
+the host, or approves anything.
+
+- The field is optional. A record that carries no `judgeOperationsV1` — including
+  every record written before the projection existed — renders an unavailable
+  cockpit, and the run card stays valid. A payload with an incompatible major
+  version or another run's id is rejected: unusable evidence is never presented.
+- Evidence Build did not publish renders as an explicit `unavailable`. A published
+  empty list renders as `none`; the two are never conflated, and no field is
+  defaulted, clamped, or back-filled.
+- The immutable judge winner has its own row, separate from the synthesized and
+  delivered artifact rows, even when all three agree. When a synthesized or
+  delivered artifact diverges from the winner, that divergence is disclosed and the
+  judge winner is left unchanged.
+- Matrix escalation is presented as an escalated judge verdict with Build's own
+  escalation reasons, recorded per-profile disagreements, and human checks labelled
+  `blocking` or `advisory` as Build recorded them. It does not change which winner
+  the cockpit shows.
+- Fusion reports `No judge by design` — a complete state, not a pending, degraded,
+  broken, or empty one. Fusion's synthesized and delivered artifacts are still
+  shown, because they are not judge concepts.
+- Tracked backlog execution renders no cockpit: its kind-tagged readback carries no
+  judge, variant, or verdict fields at all. An unreadable observation also renders
+  none rather than replaying stale judge evidence.
+
+## Results explorer, patch preview, defaults, and setup
+
+Build remains the execution and result authority. BB only presents and navigates
+what Build already published. Competition, Fusion, and tracked backlog execution
+stay kind-specific; sections, references, and standalone commands do not cross kinds.
+Fusion has no Judge winner by design.
+
+- **Results explorer** — one read-only view per run via `readResult`. It reuses
+  Build's canonical result readback and adds no winner, score, or verification
+  recomputation. Canonical standalone commands: `build run competition results <run-id>
+  --json`, `build run fusion results <run-id> --json`, and
+  `build plan backlog show <id> --json` for tracked execution.
+- **Patch preview** — bounded and patch-only. Only a freshly rebound canonical
+  repository-relative `patch` reference may open content, and only up to a fixed byte ceiling; truncated
+  previews are labelled partial. Non-patch kinds, cross-run or cross-repository
+  identity, unsafe paths, symlinks, binaries, compressed, and missing files are
+  explicit refusals. There is no apply, write, or merge control.
+- **Competition configured-defaults disclosure** — read-only presentation of
+  `build config resolved --compete --json` with source attribution. The existing
+  PBB-20 launch remains
+  `build run competition --backlog-item <id> --judge ai --configured-defaults --json`;
+  disclosure does not change that argv.
+- **Setup and configuration workspace** — read-only status for install readiness,
+  resolved defaults, providers, and copyable guidance. Setup, auth, and config
+  commands are guidance only and are never executed by BB. BB displays Build's
+  normalized provider-readiness state and label; authentication needed and installed
+  but unverified remain distinct, while deferred or unobserved authentication is
+  `unknown` / normal, not a fault or launch gate.
+  Canonical guidance includes `build --version`,
+  `build config resolved --summary --json`,
+  `build config resolved --compete --json`,
+  `build config validate --json`, `build provider list --json`,
+  `build init`, and `build provider setup --first-run` (all run outside BB).
+
+## Optional narrated progress
+
+Narration is advisory and requires an active UI subscriber: `pollRuns` schedules a
+model call only when a visible panel sets `narrate`. The background service polls
+with narration off, so the authoritative cadence never issues a model call on its
+own. An already-cached fresh narration still renders, because it costs nothing.
+
+Narration is disabled by default. Enable it in user or project
+`build.config.jsonc` with an explicit provider; omit `model` to use that
+provider CLI's configured default:
+
+```jsonc
+{
+  "progressNarration": {
+    "enabled": true,
+    "provider": "codex",
+    "minIntervalMs": 15000,
+    "maxAgeMs": 60000,
+  },
+}
+```
+
+Build publishes only a bounded structured-facts envelope alongside
+`runProgressV1`. The plugin invokes the existing `build ask --json` surface,
+so it reuses Build's provider resolution and the installed CLI's native
+authentication. One request covers all active variants for a run. The plugin
+coalesces overlapping polls, rate-limits requests, keeps its cache in memory,
+and immediately falls back to the deterministic progress line when narration
+is disabled, stale, invalid, terminal, or unavailable. Narration and its
+advisory latency never change run state, cancellation, judging, verification,
+or result evidence.
+
+## Cancel and reconnect
+
+The launch and cancel controls are plugin RPC actions over Build's existing behavior. They add
+no public Build command, scheduler, retry path, or persistence mechanism.
+
+- `cancelRun` names exactly one operation. It sends the same interrupt a
+  standalone operator would to the exact process this plugin launched. For
+  Fusion it also runs `build processes --kill <run-id> --force` for anything
+  Build spawned for that run. Sibling runs are untouched.
+- A cancelled card reports `cancelRequested`, but its status and terminal flag
+  stay whatever Build reports. The plugin never asserts a terminal state Build
+  has not confirmed. Runs that already reached a final state, unknown
+  operations, and operations from another repository are refused explicitly.
+- What could not be cancelled is reported verbatim on the card: an unsignalable
+  process, a Build cancel command that failed, Build reporting no live
+  processes for the run, or cancellation requested before a run ID existed.
+- Detached task/sprint runs are never cancellable from BB. Build owns the detached worker and does
+  not publish an exact workflow-scoped cancellation control, so BB hides Cancel rather than risk
+  terminating unrelated or newer work.
+- `pollRuns` with no `operationIds` is the reconnect path. It combines bounded
+  plugin-local history with task IDs from `build processes --json`, accepting a
+  discovered ID only when its Fusion snapshot belongs to the selected repository. BB-launched
+  sprint references reconnect by workflow ID and are accepted only when the typed readback matches
+  the repository, sprint, and selected task identity.
+  Cards are merged without duplication. `Refresh runs` triggers the same poll.
+- Fusion registers its top-level CLI process under the authoritative run ID before
+  publishing the run-start envelope and refreshes that entry for the active
+  lifecycle. A fresh adapter therefore re-adopts active queued, provider, and
+  synthesis work without importing Build internals or keeping a second ledger.
+
+### Duplicate-launch refusal
+
+`plan backlog show --json` carries Build's kind-tagged tracked-execution
+readback. BB admits at most one tracked launch per repository checkout; the
+reservation is repository-scoped, while Fusion and other repositories remain
+independent. A launch is also refused while readback proves an active execution:
+a non-terminal, non-stale record whose status is `running` or `queued` **and**
+whose recorded process Build observed `alive`. Everything weaker
+allows the launch — `gone`, `unobserved`, `stale`, `unknown`, and a missing record
+are not evidence of activity, and `.build-project/provenance` is local-only, so absence
+never proves nothing is running. The evidence is read fresh on every request and
+is never stored in BB, so BB state can neither manufacture a block nor grant
+permission.
+
+### Bounded reference index (BB-launched history only)
+
+Runs this plugin launched get one bounded BB KV row holding **discovery identity
+only**: repository, kind, run id, typed task/sprint subject when applicable, backlog item id,
+operation id, and launch time.
+There is deliberately no status, progress, phase, terminal verdict, provider
+output, evidence, or Git result, so a stale reference cannot override Build's
+readback — every card is rehydrated from Build. The index caps at 50 references
+(oldest launches evicted) and expires entries after 7 days; unparsable,
+foreign-schema, and expired rows are deleted on read. It is BB-launched history,
+not a run ledger or a second store.
+
+### Loss of the local process handle (safe, not seamless)
+
+Fusion is launched as a plain child of the BB server process with
+`stdio: ['ignore', 'pipe', 'pipe']` — not detached, and not `unref`ed. This slice
+does not promise restart recovery; it promises safe behavior when the handle is
+gone.
+
+- Reloading the BB **panel** keeps runs alive and reconnects to them; operation
+  handles live in the plugin's server-side adapter, not in the web view.
+- Restarting the BB **server** or reloading the plugin ends the plugin's direct
+  child supervision. Cards then report `processHandle: 'lost'` and disclose it in
+  plain text. A fresh adapter re-reads Build — from its process registry and from
+  the bounded reference index — and reports a supported terminal or live state, or
+  an honest, non-cancellable `unknown`. The identity remains visible so a later
+  Build read can recover it without restarting or reconstructing the run.
+- Nothing is automatically restarted, resumed, replayed, or reconstructed. There
+  is no daemon, event journal, general crash-recovery subsystem, or
+  machine-reboot guarantee.
+- Cancellation requires `controlEvidence`: either a `local-process` handle this
+  plugin still owns, or a `build-live-process` — a healthy top-level Fusion
+  process Build reports for that run in that repository. With neither, the
+  control is disabled and the RPC refuses, rather than claiming control the
+  plugin does not have. Live-process evidence is recomputed on every reconnect, so
+  a run that leaves the registry loses cancellability.
+
+A public Build API family, remote repositories, retry/relaunch, seamless process
+reattachment, live-output restoration, live provider-session steering, and
+imperative artifact opening are not part of this slice. Optional enablement is
+available via `build provider setup --bb`.