@getspur/spur-graph 1.1.17

package/.gitignore

@@ -0,0 +1,2 @@
+/node_modules
+

package/CHANGELOG.md

@@ -0,0 +1,260 @@
+## Unreleased
+
+### Added
+- **`spur-graph` content-hash invalidation substrate (bd-jvers, v2.1).**
+  Replaces mtime/size per-file invalidation with a filtered-content hash
+  over `(path, content_oid)` pairs, where `content_oid` is the git blob OID
+  (from `git ls-files -s` for clean files; locally computed via
+  `sha1("blob " || decimal(size) || "\0" || bytes)` for dirty / untracked /
+  fs-mode files; `gitlink:<oid>` for submodules). Cache key derivation
+  reads only the git index + dirty file bytes — does not depend on `HEAD`.
+  - **Canonical artifact** at `<git_common_dir>/spur-graph/artifacts/<manifest_version>/<graph_content_hash>.json`
+    (immutable per key, content-addressed).
+  - **Per-worktree** `.spur/graph-index.json` retained as a full artifact,
+    hardlinked to the canonical (with `fs::copy` fallback across filesystems).
+    Existing direct consumers (`crates/spur-tui/src/mentions/code_graph/source.rs`)
+    are source-compatible — no API changes.
+  - **Optional pointer sidecar** at `.spur/graph-index.pointer.json` carries
+    provenance (`indexed_commit_oid`, `source_kind`, `manifest_version`).
+  - **Bucket reuse.** Within a worktree, unchanged paths (same `content_oid`
+    as the previous artifact) are cloned wholesale — no tree-sitter parsing
+    or symbol extraction. This is the per-build extraction-saving mechanism.
+  - **Cross-worktree dedup.** Two worktrees with identical filtered content
+    derive the same canonical key regardless of commit history, so the
+    second writer skips the canonical JSON write and hardlinks the existing
+    artifact. (Each worktree still computes its own discovery + hash;
+    pre-extraction shortcircuit is tracked as a followup, bd-5yful.)
+  - **Dirty == committed (I2).** A worktree's dirty `content_oid` equals
+    the blob OID git would assign if the file were committed, so
+    `graph_content_hash` before and after committing identical bytes
+    matches and every bucket is reused on the next build.
+  - `fs2` exclusive lock with 5s timeout + worktree-only fallback on
+    contention; atomic write via tmp + rename + best-effort `fsync_dir`.
+  - Schema bumped to `spur-graph-schema-v4`: `GraphFileManifestEntry` swaps
+    `mtime_nanos`/`size_bytes` for `content_oid`; `GraphIndexArtifact` gains
+    `graph_content_hash` and value-level `tombstones` (no commit OID).
+  - Design spec: `docs/architecture/spur-graph-git-invalidation.md`.
+- **`spur-graph` benchmark gate.** Criterion bench at
+  `crates/spur-graph/benches/incremental.rs` covers four scenarios:
+  clean cold (cache miss), clean warm (cache hit via hardlink), 1k-file
+  change set over baseline, and dirty unstaged mods overlay. Env-knob
+  scaling via `BENCH_FILE_COUNT` / `BENCH_CHANGE_SET` / `BENCH_DIRTY_MODS`.
+
+### Fixed
+- **`spur-graph` cache lock-timeout no longer leaves a ghost pointer**
+  (bd-jvers followup). On `fs2` lock contention, `write_with_dedup`
+  previously wrote the worktree artifact and ALSO wrote a pointer sidecar
+  whose `canonical_artifact_path` referenced a canonical file that was
+  never created — any pointer-following reader hit a deterministic
+  missing-file failure. Fix: on lock-timeout, write the worktree artifact
+  (still authoritative) and remove any pre-existing pointer so it cannot
+  be stale. Convergent finding from claude-code and kimi reviews. Test
+  `lock_timeout_writes_worktree_only` extended to stage a stale pointer
+  before the lock-contended write and assert no pointer exists after.
+
+- **Experimental TUI Insights view (`--features analytics`, default OFF).**
+  `Alt+a` from any view opens a 4-tab Insights surface (Overview / Timeline /
+  Breakdown / Live) backed by `spur-context::AnalyticsEngine`'s DuckDB store.
+  - Overview: KPI cards (Today / 7d / 30d / Cache hit), 7d cost sparkline,
+    cost-provenance gauge (native / priced / unpriced), top-3 agent / model /
+    project lists.
+  - Timeline: BarChart with `D`/`W`/`M` granularity toggle (no re-query).
+  - Breakdown: Pivot table over Agent / Model / Project (`A` / `M` / `P`).
+  - Live: per-session burn rate, hourly projection, refresh interval drops to
+    5s while this tab is active (60s otherwise).
+  Refresh is driven by an async `tokio::spawn` task with a signal channel and
+  30s timeout; the view never blocks the UI thread.
+- **Five well-known agents are first-class in analytics**: Claude Code,
+  Codex, Gemini, OpenCode, Kimi. Kiro remains a Phase-2 stub
+  (no token data via filesystem; ACP `UsageUpdate` capture pending).
+- **`spur-context` Gemini extractor (R4).** Parses `~/.gemini/tmp/<uuid>/chats/session-*.json`
+  with `tokens.{input,output,cached,thoughts,tool}` folding. Wires into
+  `AnalyticsEngine` alongside existing Claude / Codex / OpenCode / Kimi paths.
+- **OpenCode model-prefix strip (R1).** `anthropic/claude-opus-4-5` is now
+  stored as `claude-opus-4-5` so the pricing registry's `LIKE` matcher works.
+  Eliminates spurious `cost_source='unpriced'` rows for OpenCode users.
+- **Kimi `kimi-for-coding` pricing (R2).** Registered at $0.60 input /
+  $2.50 output / $0.15 cache-read per million tokens. Kimi events now surface
+  with correct `cost_source='priced'` instead of `'unpriced'`.
+- **OpenCode SQLite mtime in cache staleness (R3).** `newest_agent_mtime`
+  now includes `~/.local/share/opencode/opencode.db`, fixing permanently-stale
+  cache for OpenCode-only users.
+- **Dashboard cost-source switch (when feature on).** Dashboard's total cost
+  reads from a periodically-refreshed `LiveCostCache` populated via
+  `AnalyticsEngine::live_session_snapshot` instead of `ExecutorLineage`. The
+  status bar shows a `via analytics` pill while the cache has data for the
+  active session. Single source of truth for cost when feature is enabled.
+- **CI matrix for `spur-tui`.** New workflow runs
+  `cargo check + cargo test --lib` for `--no-default-features`, default, and
+  `--features analytics` configurations on every PR and `main` push.
+- **P0 cost-correctness fixes harvested onto this branch.**
+  - P0.1: Claude event dedup on `(sessionId, requestId, message.id)`.
+  - P0.2/3/4: `cost_source` column + Codex cache double-count fix.
+  - P0.6: `include_str!` per-report SQL with synced cache columns.
+  - P0.8: `SessionRow::models` aggregates across mid-session model switches.
+
+### Changed
+- **Read-only future metadata saves now fail visibly.** When
+  `.spur/session_metadata.json` was written by a future SPUR version,
+  `SessionMetadataStore::save()` now returns `Err(ReadOnlyFutureSchema)`
+  instead of silently accepting and discarding in-session edits. App
+  save paths route through `App::persist_metadata`, which surfaces the
+  refusal as a dismissible warning banner.
+- **Peer mailbox reconciler now emits `WorkerPeerMessageAuditFailed`** on
+  non-terminal transition errors during startup reconciliation. The
+  `WorkerPeerMailboxReconciled.audit_failed_emitted` counter, which was
+  always `0` prior to this release, may now report non-zero values when
+  the persistent ledger introduces transition failures. Dashboards and
+  alerts that filter `audit_failed_emitted == 0` as a "no anomalies"
+  signal should switch to alerting on the
+  `WorkerPeerMessageAuditFailed { transition_kind: "reconcile_to_delivered" }`
+  event directly. (bd-cpf.5b)
+
+### Added
+- **Tolerant input-history deserialize.** A malformed `ProtectedRange` or
+  `InputHistoryEntry` in `.spur/session_metadata.json` no longer aborts
+  the entire load: bad rows are skipped with `tracing::warn!`, while
+  remaining valid history is preserved.
+- **`schema_version` field on `SessionMetadata`.** Persisted as the
+  on-disk JSON key `"version"` for backward compatibility. Files written
+  by a future SPUR version are loaded read-only; in-memory mutations are
+  not persisted until SPUR understands that schema.
+- **Read-only mode banner.** Future-version metadata now shows a top-row
+  warning at first paint and after every refused save attempt. `Esc`
+  dismisses the current banner without clearing read-only mode.
+- **`SessionMetadataStore::is_read_only()` getter.** Callers can poll
+  whether metadata is in read-only mode before enabling write-oriented UI.
+- **Worker heartbeat watchdog configuration.** New `[worktree]` config keys:
+  `worker_heartbeat_watchdog_enabled` (bool, default `false`),
+  `worker_heartbeat_timeout_secs` (u64, default `90`),
+  `worker_heartbeat_initial_grace_secs` (u64, default `60`). See
+  `docs/architecture.md` Risk #23 for operational guidance and the
+  no-runtime-toggle rollback constraint. (bd-arch.23)
+- **`DelegationAbortReason` enum** distinguishing `BrainRequested` from
+  `WorkerHeartbeatTimeout`. Stage-2 will extend with `ResourceLimitExceeded`
+  / `SandboxTerminated` for cgroup-based termination. (bd-arch.23)
+- **Peer mailbox production wire-up (Stage-1).** The peer mailbox subsystem
+  (hardened in bd-cpf.1–7) is now constructed and attached when
+  `peer_mailbox_enabled = true` is set in config. A long-lived reconciler
+  task drains stranded peer messages and emits audit events. Startup
+  reconcile runs at brain session boundaries. Default is `false`; no
+  behavioral change for existing deployments. Operators who opt in should
+  monitor for `WorkerPeerMessageUndeliverable` events and be aware that
+  the in-memory ledger does not prune entries (Risk #22). To disable,
+  set `peer_mailbox_enabled = false` and restart SPUR — runtime toggle
+  is not supported. (bd-arch.21)
+- **Peer mailbox drain lifecycle events.** `WorkerPeerMessageDrainStarted`
+  and `WorkerPeerMessageDrainTimedOut` add symmetric observability to the
+  post-prompt ack drain. `DrainStarted` carries the candidate-set size
+  and the cap/quiet-window limits in effect; `DrainTimedOut` carries the
+  same payload shape as `WorkerPeerMessageDrainCappedOut` plus
+  `quiet_window_ms`, so dashboards can reuse panel queries across both
+  exit events. `DrainTimedOut` is emitted only when the quiet-window
+  exit leaves remaining non-terminal messages; clean-exit drains
+  (`remaining_messages == 0`) emit no exit event. Diagnostic-only —
+  message loss continues to be tracked per-message via
+  `WorkerPeerMessageIgnored`. (bd-cpf.7)
+- **`WorkerPeerMailboxReconciled.inflight_already_delivered` counter.**
+  Tracks benign idempotent races during startup reconciliation where an
+  entry was already in `Delivered` state when the reconciler attempted
+  to advance it. Always 0 in Stage-1; becomes non-zero under Stage-2
+  crash-loop or concurrent-reconcile scenarios. (bd-cpf.5c)
+- **Spur Way skill bundle.** Six bundled skills harden brain-worker-beads
+  collaboration: `spur-way` (beads-first invariant), `beads-lifecycle`
+  (status state machine), `worker-signals` (`[[spur-signal v1]]` protocol),
+  `brain-review-gate` (beads-aware approval checklist), `plan-task-discipline`
+  (DAG integrity rules), and `worker-mention-routing` (user `@`-mention
+  overrides algorithmic selection). All compile into `spur-core` via
+  `include_str!` and render across the seven agent adapters. See
+  `docs/superpowers/specs/2026-04-22-superpower-skill-hardening-spur-way.md`.
+- **Role-gated skill rendering + Kimi adapter.** Skills now carry a `role`
+  field (`brain | worker | both`). Brain-only skills (`brain-review-gate`,
+  `brain-delegation`) no longer leak into worker agent directories. Worker
+  skills (`test-driven-development`, `systematic-debugging`) are tagged
+  explicitly. New `Adapter::Kimi` renders to `.kimi/skills/`, closing the
+  gap where Kimi workers accidentally relied on `.claude/skills/` fallback.
+  See `docs/superpowers/specs/2026-04-22-multi-agent-skill-embedding-research.md`.
+
+### Fixed
+- **Risk #4 (worktree orphaning under unclean shutdown).** New
+  `WorktreeAuthority` actor sweeps dead-session worktrees safely under
+  multi-process operation. Branch namespace migrated to
+  `spur/worker/v2/{agent}/{brain_session_id}/{worker_session_id}` so
+  sweep enumeration can be precisely scoped to v2 worktrees. Pre-v2
+  branches are NOT auto-cleaned; operators reclaim legacy debt via the
+  separate `spur-worktree-gc-legacy.sh` script (deferred). The actor
+  uses a `SessionLivenessProbe` over advisory `flock(2)` and a
+  `SelfHeldSet` to skip self-owned sessions. See
+  `docs/superpowers/specs/2026-04-26-worktree-authority-design.md` for
+  the full invariants I-1..I-7.
+- **Worker child processes now die with their orchestrator** via
+  `kill_on_drop(true)` on the `tokio::process::Command` spawn paths in
+  `crates/spur-acp/src/connection/{native,stdio_adapter,cli_wrap_adapter,stream_json_adapter}.rs`.
+  Closes Risk #4's hard prerequisite.
+- **`spur-bot/tests/runtime_flow.rs` compile errors absorbed.** 12
+  inline `AgentSessionReady` event initializers were missing the
+  `fs_unsafe: bool` field added in the single-attach invariant work
+  (commit `84e91895`). Fixed inline so the workspace smoke test gate
+  passes. This is cross-stream cleanup — not part of the
+  WorktreeAuthority design but required for plan closure.
+- **Architecture Risk #23 (semaphore indefinite wait).** Permit acquire is now
+  cancellable: `cancel_delegation` arriving while a task is queued for a
+  permit short-circuits immediately without acquiring. A heartbeat-based
+  watchdog (default-off) detects silent worker hangs and releases the held
+  permit after `worker_heartbeat_timeout_secs` (default 90s, configurable).
+  Watchdog is gated behind `worker_heartbeat_watchdog_enabled` (default
+  `false`) until a v1 `_spur/heartbeat` emitter lands; operators may opt
+  in early if their workers emit heartbeats. Watchdog firings map to
+  `DelegationStatus::Timeout`, preserving the `Timeout` (worker-hang)
+  vs `TimedOut` (review-gate) semantic split. Brain-initiated cancellations
+  continue to map to `DelegationStatus::Cancelled`. (bd-arch.23)
+- **Architecture Risk #21.** The peer mailbox reconciler is now spawned
+  at orchestrator boot and aborted on shutdown via `Orchestrator::drop`.
+  Previously the receiver was dropped immediately after construction,
+  causing stranded messages to be silently lost — but the surrounding
+  wire-up was also missing in production, so the entire subsystem (62
+  tests, bd-cpf.1–7 hardening) was inert. (bd-arch.21)
+
+## v1.1.8 — 2026-05-13
+
+Spur 1.1.8 ships fresh defaults for the agents you actually run and makes two long-standing rough edges disappear: `/model` now feels instant on every agent, and long GitHub fetches stop looking like a hang.
+
+- **Fresh out-of-the-box agent versions.** `spur init` now seeds new repos with `claude-agent-acp 0.33.1` (up from 0.26.0) and `codex-acp 0.14.0` (up from 0.11.1). New users get the latest ACP features and fixes on first run — no manual version-pinning, no stale prompts about deprecated flags. Existing `.spur/config.toml` files are preserved as-is; bump the pinned versions there when you're ready.
+- **`/model` feels instant on every agent.** Some agents (including older Claude Code and Kimi builds) don't emit a `config_option_update` after a model switch, so the status bar used to keep showing the previous model until you reconnected. Spur now applies an optimistic override the moment you pick a model — the label flips immediately and reconciles with the agent's confirmation when it arrives.
+- **GitHub ingest shows live progress.** `spur pm` ingesting a large GitHub repo's issues used to look frozen for minutes on the first run. The PM layer now surfaces per-page progress as fetches stream in, so you can see it working and estimate how much longer it'll take instead of wondering whether to kill it.
+
+## v1.1.7 — 2026-05-13
+
+Spur 1.1.7 makes everyday agent-switching and navigation feel right. Changing models works everywhere, the picker puts what you actually want at the top, and the code graph is there when you need it without any setup.
+
+- **`/model` now works on every supported agent.** Switching models in Gemini CLI and Kimi CLI was broken before — both now behave like Codex, Claude Code, and OpenCode. Pick a model, get that model.
+- **Status bar reflects the model you're actually on.** After a `/model` switch, the label updates live instead of showing the old name until you restart the session.
+- **Smarter `@mention` picker.** Files no longer get buried under issues and workers. Results are grouped under clear section headers and ordered so the thing you're most likely reaching for is at the top.
+- **Code graph just works.** Spur now auto-discovers the project's code graph at the worktree root — no environment variable to set, no "run `spur graph build`" hint when the graph is already there. Rebuilds are also faster and symbol names stay stable across runs, so jumping between files is more reliable.
+
+## v0.4.5 — 2026-04-19
+
+Spur 0.4.5 focuses on getting around faster and trusting what you see. A new universal palette (Ctrl+K) jumps you between sessions, workers, traces, and commands from anywhere. The `@mention` and `/slash` pickers now share one consistent interface. Agent output renders markdown and mermaid diagrams inline, and streaming stays smooth under bursty traffic.
+
+### Added
+- **Universal palette (Ctrl+K).** Fuzzy-search and jump to any session, worker, trace entry, or command from anywhere in the TUI. A `[Ctrl+K: go]` badge in the status bar reminds you it's there.
+- **Unified completion for `@mention` and `/slash`.** Both now flow through the same picker — same keys, same preview, same ranking. One interface to learn.
+- **Rerun recent prompts with Ctrl+R.** Session picker surfaces your recent prompts; pick one to rerun against the current session.
+- **Auto-resume landing.** Launching spur drops you straight back on the last session you were working in.
+- **Markdown and mermaid in agent output.** Rich content renders inline in the trace view — no more raw source for formatted replies or diagrams.
+- **Dashboard view.** New top-level view for at-a-glance status across sessions and workers.
+- **Skills installer across adapters.** `.spur/skills/` installs to Cursor, Codex, Kiro, Gemini, and OpenCode in one step, with edits you own preserved on upgrade.
+- **Delegation visibility in the timeline.** Delegation plans now appear in the TUI timeline as they happen; `list_available_workers` returns richer descriptors (tier, cost, suitability hints).
+
+### Improved
+- **Smoother streaming.** A new scroll anchor and per-frame drain cap keep long, bursty outputs readable instead of jittery.
+- **Faster palette and pickers.** Single-pass reranking and cached search patterns.
+- **Session metadata persists across restarts.**
+
+### Preview features (opt-in)
+- **Brain delegation framework.** A new orchestration model for deciding which worker handles a task. Opt in via your config:
+  ```toml
+  [brain.delegation]
+  framework = "v1"
+  ```
+  Release builds default to `legacy` for 0.4.5; the v1 framework will become default once it stabilizes.

package/README.md

@@ -0,0 +1,222 @@
+# SPUR
+
+**The control tower for your CLI coding agents.**
+
+> Issue in, PR out — across every agent, in parallel, with one review surface.
+
+SPUR is a Rust-native terminal layer that sits above the AI coding agents you already run — Claude Code, Codex, Gemini, Kimi, OpenCode, or any [ACP](https://github.com/anthropics/agent-client-protocol)-speaking agent. A "brain" reasons about your task and delegates to one or more "workers." Each worker runs in its own isolated git worktree. SPUR coordinates dispatch, human review, cherry-pick, retries, cross-vendor cost, and project-management state in one place.
+
+> ⚠️ **Early stage** — APIs and config format may change.
+
+## The Problem
+
+Running 2+ AI coding agents today means living with four frustrations:
+
+- **Rate-limit ambush.** Claude Code Max users blow through 5-hour windows in under 90 minutes. *"Paying $200 a month, I hit my weekly in 3 days last week"* (esperent, HN 47626833). When the lockout hits, the in-flight context is gone.
+- **Cost opacity.** Tokens accrue across five vendors with no single ledger. *"I'm paying for Max, and when I use the tooling to calculate the spend returned by the API, I can see it's almost $1k!"* (buremba, HN 44598254). Devs only discover the gap by reverse-engineering their own bill.
+- **Multi-agent chaos.** *"I run 5–10 Claude Code agents at a time across different repos. Keeping track of which one is waiting for input, which one is working, and which one broke something was chaos. I needed a control tower"* (Beefin, HN 47104424).
+- **Worktree merge tax.** DIY tmux + worktrees is the workaround. *"I expected this to become less necessary over time as models got faster, but the opposite has happened"* (nojs, HN 47573483).
+
+SPUR addresses all four: cross-vendor brain-swap when one vendor rate-limits you, a unified live cost ledger across every CLI you pay for, one review surface for parallel workers, and DAG-ordered cherry-pick of approved diffs onto a staging branch.
+
+## How It Works
+
+```
+┌─────────────────────┐     ┌──────────────────────────────────┐     ┌─────────────────────┐
+│  Project Management │     │           SPUR TUI               │     │   Worker Agents     │
+│                     │     │                                  │     │                     │
+│  beads (native)     │◄───►│  ┌────────────────────────────┐  │     │  Claude Code        │
+│  GitHub Issues      │     │  │  Brain Agent (orchestrator) │──┼────►│  Codex              │
+│                     │     │  └────────────────────────────┘  │     │  Gemini             │
+│                     │     │  ┌─────────┬────────┬─────────┐  │     │  Kimi               │
+│                     │     │  │Dashboard│Insights│Plan View│  │     │  OpenCode           │
+│                     │     │  └─────────┴────────┴─────────┘  │     │  Kiro (partial)     │
+└─────────────────────┘     └──────────────────────────────────┘     │  Generic ACP        │
+                                         ▲                            └─────────────────────┘
+                                         │ ACP (JSON-RPC 2.0 / stdio)
+                                         ▼
+                          ┌──────────────────────────────────┐
+                          │  Git Worktrees per Worker        │
+                          │  DuckDB Analytics Engine         │
+                          │  Beads Plan Store + Reconciler   │
+                          │  MCP Server (delegation tools)   │
+                          └──────────────────────────────────┘
+```
+
+## Capabilities
+
+*Ordered by uniqueness — what no single-vendor or cloud peer can match by design.*
+
+- **Unified cost ledger across every vendor.** Five live extractors (Claude, Codex, Gemini, OpenCode, Kimi) feeding a DuckDB analytics engine that reads vendor JSONL/SQLite in place — no ETL. The Insights view (`Alt+a`) shows 7-day cost sparklines, per-session burn rate, and a `cost_source` provenance gauge. Devin, Cosine, Cursor, Aider, and Claude Code each only see their own bill; SPUR sees all of them in one number.
+- **Brain-swap across vendors mid-flow.** Hit a Claude rate limit → keep working on Codex → come back to Claude when the window resets. Per-agent capability negotiation; `/model` and `/effort` synthesized from each agent's `InitializeResponse`. Impossible inside any single-vendor tool.
+- **Session resume via event replay.** Close the laptop, restart SPUR, the brain picks up exactly where it left off. Not a soft-reconnect — a full replay from an event-sourced log.
+- **Local-first durability.** Plans persist as beads epics in SQLite, events as NDJSON, outcomes as content-addressed git blobs. Survives crashes, OS updates, and network outages — resilience cloud-only competitors cannot match without offline sync.
+- **Review loop with Reflexion retry.** Every worker completion produces a review card — Approve / Reject / Modify / Retry. Retries feed prior attempts back as context (max 3, auto-reject on exhaustion). A first-class state machine, not a UI convenience.
+- **Parallel delegation, isolated.** `delegate_to_worker`, `delegate_parallel`, and DAG-ordered `submit_plan` dispatch workers concurrently. Each gets its own git worktree on `spur/worker/v2/{agent}/...`, protected by advisory `flock` liveness probes and an orphan-collector.
+- **Cherry-pick in DAG order.** Approved subtask commits are cherry-picked in topological order onto a staging branch. Collapses the post-worktree merge tax that DIY tmux+worktree users hit every day.
+- **Telegram bot on the same state machine.** `spur-bot` mirrors review cards and session streams into Telegram forum topics. Same review lane, same event bus, same approval semantics as the TUI — review on the train, not just at the desk.
+- **Native ACP + MCP dual channel.** Structured JSON-RPC, not PTY scraping or prompt injection. Any ACP-speaking agent works out of the box.
+- **Durable plan mutations.** `submit_plan_mutation` supports split / replace / amend in-flight; the reconciler ticks adaptively, validates ownership, and previews overlay conflicts.
+- **Multi-brain safety.** Plans are locked to a single active brain via a `spur:plan-owner:<id>` label. Tier-1 mutating tools fail on session mismatch. `force_reclaim_plan` breaks deadlocks when a brain wedges.
+- **Structured delegation reasoning.** Brains pass a `DelegationPlan` (candidates, rationale, decomposition) with every dispatch. SPUR verifies the chosen agent matches the actual payload — preventing the LLM from lying to its own reviewer.
+- **Stable-identity code graph.** Tree-sitter parses Rust / Python / TS / TSX / Markdown into a graph with SHA256 stable symbol IDs and incremental per-file rebuilds. Auto-discovered at the worktree root — no env var setup.
+- **Built for orchestration, not chat.** Dashboard with lineage tree, full-screen ReAct trace with inline markdown + mermaid, grouped `@mention` picker (Workers / Files / Issues / Code Graph), `Ctrl+K` universal palette, Plan Inspector (`Alt+P`), live status bar (running count, pending reviews, total cost, model labels).
+
+## What SPUR is NOT
+
+SPUR is built to sit *above* the agents and tools you already use. We don't try to replace them — and several excellent products own jobs SPUR explicitly does not compete on:
+
+- **Not a Devin replacement.** Devin owns "autonomous engineer I can assign tickets to in Slack." SPUR keeps the human in the loop on purpose — review is a state machine, not a slogan. If you want a fully autonomous agent, hire Devin.
+- **Not a Cursor competitor.** Cursor owns the AI IDE. SPUR sits *next to* your editor, not inside it. Most SPUR users keep Cursor open in another window.
+- **Not an Aider replacement.** Aider owns the simplest free BYO-key single-agent CLI. SPUR's value materializes at fleet size ≥ 2 — "add SPUR above Aider," not "switch from Aider." Aider-as-a-SPUR-worker is on the roadmap.
+- **Not a Claude Code replacement.** SPUR uses Claude Code as a worker. We don't try to beat the in-session UX; we add what Claude Code doesn't attempt — cross-session durability, cross-vendor failover, and a cost ledger that spans every CLI.
+- **Not autonomous.** Review gate is required by design. If you want a "set and forget" system, this is the wrong tool.
+
+And on the boring scope side:
+
+- Not a chat UI. Every interaction is task-structured.
+- Not an IDE. No editor, no LSP, no inline diff gutter.
+- Not CI/CD. Plans run locally with local worktrees, not on remote runners.
+- Not a universal PM sync. Only beads (native) and GitHub (via `gh`) are implemented today.
+
+## Crate Structure
+
+| Crate | Purpose |
+|---|---|
+| `spur-cli` | Binary entry point and CLI commands |
+| `spur-tui` | `ratatui` terminal interface — views, components, input handling |
+| `spur-core` | Orchestration engine, review loop, lineage, event pipeline |
+| `spur-acp` | ACP client, transports (stdio / native / cli-wrap), capability negotiation |
+| `spur-mcp` | MCP server exposing delegation tools to the brain (delegate, plan, signals) |
+| `spur-context` | DuckDB analytics engine + per-agent log extractors |
+| `spur-cost` | Pricing registry + SQLite session ledger |
+| `spur-graph` | Tree-sitter code graph, stable IDs, incremental rebuild |
+| `spur-pm` | Project management adapters (beads, GitHub) |
+| `spur-worktree` | Git worktree creation, isolation, flock liveness, cleanup |
+| `spur-interactive` | Frontend bridge for non-TUI clients |
+| `spur-bot` | Telegram bot frontend |
+| `spur-blob-store` | Content-addressed delegation outcome artifacts |
+| `spur-license` / `spur-license-admin` | Tier / feature-key registry |
+
+## Quickstart
+
+### Install
+
+```sh
+curl -sSL https://getspur.dev/install.sh | sh
+```
+
+Installs the signed `spur` binary. Free Community tier — no key required. Pro / Team / Enterprise unlock via a signed license file from your account dashboard.
+
+> Note: install domain is provisional; final URL will be confirmed at launch.
+
+### Initialize a project
+
+```sh
+cd your-project
+spur init
+```
+
+Creates a `.spur/config.toml` with detected agents and sensible defaults.
+
+### Run
+
+```sh
+spur
+```
+
+The TUI launches with your configured brain and worker agents. Type a task or pick an issue from your PM integration.
+
+### Check config
+
+```sh
+spur config check
+```
+
+Validates your configuration and reports warnings.
+
+## Configuration
+
+SPUR is configured via `.spur/config.toml` at your project root:
+
+```toml
+[brain]
+agent = "claude-code-acp"
+
+[agents.entries.claude-code-acp]
+role = "brain"
+transport = "native"
+
+[agents.entries.codex]
+role = "worker"
+transport = "stdio"
+good_for = ["rust", "tests"]
+tier = 1
+
+[agents.entries.kimi]
+role = "worker"
+transport = "stdio"
+good_for = ["long-context-exploration", "research"]
+
+[pm.github]
+repo = "owner/repo"
+
+[worktree]
+enabled = true
+
+[cost]
+db_path = "~/.spur/cost.db"
+```
+
+Each agent entry supports delegation descriptors (`good_for`, `avoid_for`, `tier`, `cost_tier`) used by the brain for routing. Run `spur config check` to lint your configuration.
+
+## Telemetry and Privacy
+
+SPUR ships anonymous-identifier-based telemetry: Tier 1 crash diagnostics and performance are default ON, Tier 2 usage is default OFF (opt-in).
+Disable all telemetry in one line: `SPUR_TELEMETRY=0 spur`.
+For persistent disable, run `spur telemetry disable all`.
+Collected fields, retention (90 days), deletion-by-ID steps, and pseudonymity details: [docs/PRIVACY.md](docs/PRIVACY.md).
+
+## A Day in the Life
+
+**Parallel refactor.** "Refactor error handling across the codebase." Brain submits a 5-task plan → 5 worktrees, 5 workers run in parallel → review cards appear → approve 4, reject 1 with feedback → rejected worker retries with your note → approved branches cherry-picked to staging. Status bar: total cost $2.40.
+
+**Cost burn check.** Hit `Alt+a` for Insights. Live tab shows 3 active sessions — Codex is on the wrong model. Switch to that session, type `/model gpt-4o`, status bar updates instantly. Breakdown tab shows yesterday $18 (60% Claude, 40% Codex).
+
+**Stuck plan recovery.** Overnight 12-task plan; one task stuck in `Dispatched` (worker died). `Alt+P` Plan Inspector → `force_reclaim_plan` promotes it to `AwaitingReview` → inspect partial diff → reject and split via `submit_plan_mutation` → plan resumes, 11 completed tasks intact.
+
+## Development
+
+```sh
+# Build all crates
+cargo build --workspace
+
+# Run the full test suite
+cargo test --workspace
+
+# Run tests for a single crate
+cargo test -p spur-tui
+
+# Lint
+cargo clippy --workspace -- -D warnings
+
+# Format
+cargo fmt --all
+
+# Run locally
+cargo run -p spur-cli -- --help
+```
+
+### Commit format
+
+```
+<type>(<scope>): <short imperative>
+```
+
+Types: `feat`, `fix`, `test`, `docs`, `refactor`, `chore`. Keep subjects under 72 characters.
+
+## License
+
+SPUR is a proprietary product. The free Community tier is available without a license key under the terms of the EULA at [https://getspur.dev/eula](https://getspur.dev/eula). Pro / Team / Enterprise tiers require a signed license file. See [LICENSE](LICENSE) for terms.
+
+> The source in this repository is not open source. Issues, feedback, and feature requests are welcome via [https://getspur.dev/feedback](https://getspur.dev/feedback) or your team's support channel.