Skill package is fully aligned to bb-buff runtime model across SKILL.md, references, scripts, and tests; no legacy command drift remains; migration guidance is explicit for other agents.

Replaced by beadboard-1bg with updated structure following bead-prompting.md format

Skill and runbook alignment track for the Agent System Overhaul (`bb-buff`).

Why this sub-epic exists
- The current beadboard-driver skill still references legacy activity-lease flow and does not fully reflect current/future Wisps + ZFC + Swarm contracts.
- Skill behavior spans many files (SKILL.md, references, scripts, and tests) and needs structured migration, not ad-hoc edits.

Scope
1) Rewrite the main skill contract to match `bb-buff` architecture outcomes.
2) Update reference docs (`command-matrix`, `session-lifecycle`, `failure-modes`) to remove legacy drift.
3) Align helper scripts with new non-interactive runtime contract and diagnostics.
4) Expand test coverage for skill-local and repo-level skill tests.
5) Produce a migration note so other agents can safely adopt v4 behavior.

Primary files
- skills/beadboard-driver/SKILL.md
- skills/beadboard-driver/references/command-matrix.md
- skills/beadboard-driver/references/session-lifecycle.md
- skills/beadboard-driver/references/failure-modes.md
- skills/beadboard-driver/scripts/session-preflight.mjs
- skills/beadboard-driver/scripts/readiness-report.mjs
- skills/beadboard-driver/scripts/lib/driver-lib.mjs
- skills/beadboard-driver/tests/*
- tests/skills/beadboard-driver/*

Out of scope
- No direct runtime implementation inside this sub-epic; this is skill/docs/scripts/tests alignment.

## Template Label Integration (Future)

When the skill spawns work on an epic, it should:
1. Check for labels starting with 'template:' (e.g., template:bug-fix, template:investigation)
2. Look up the template definition from /api/swarm/templates
3. Use the team composition (archetype counts) to determine how many agents to spawn
4. Follow the protoFormula workflow

This allows the user to assign templates to epics in the UI, and the skill will automatically understand what team is needed when asked to work on that epic.

Example:
- Epic has label: template:investigation
- Skill reads this, looks up 'investigation' template which has {investigator: 1, tester: 1}
- Skill spawns with 1 investigator + 1 tester agents

Skill and Runbook Alignment (Beadboard Driver v4)


SKILL.md v4 reflects bb-buff semantics with no legacy drift, includes swarm/state examples, and documents compatibility delta from prior version.

"Rewrite

Core Skill Rewrite: beadboard-driver SKILL.md v4


All reference docs are v4-consistent, command-accurate, and remediation-complete for new runtime semantics.

Refactor skill reference docs to match v4 contract and remove command drift.

Required updates
1) `references/command-matrix.md`
- remove deprecated entries,
- categorize commands by phase (bootstrap, coordination, state, closeout),
- annotate required/optional arguments and JSON envelopes.
2) `references/session-lifecycle.md`
- add swarm-aware and role-routing-aware lifecycle steps,
- include handoff and blocker obligations for multi-agent sessions.
3) `references/failure-modes.md`
- add new failure classes (state mismatch, swarm resolution failure, role fanout empty set, telemetry unavailable fallback),
- add deterministic remediation steps.

Cross-check
- reference docs must align with SKILL.md v4 and script behavior.

Files
- skills/beadboard-driver/references/command-matrix.md
- skills/beadboard-driver/references/session-lifecycle.md
- skills/beadboard-driver/references/failure-modes.md

Reference Pack Rewrite: command matrix, lifecycle, failure modes


Skill scripts emit deterministic JSON diagnostics aligned with v4 contracts and include explicit error-code remediation.

Align skill scripts with v4 runtime contract and diagnostics.

Targets
1) `scripts/session-preflight.mjs`
- validate availability of required tools/paths for v4 flow,
- output machine-readable diagnostics for new orchestration/resiliency expectations.
2) `scripts/readiness-report.mjs`
- include checks for state/telemetry/routing evidence fields when applicable.
3) `scripts/lib/driver-lib.mjs`
- centralize any command/path resolution helpers needed by v4.
4) Ensure script outputs are stable JSON for downstream automation agents.

Rules
- No hidden interactive prompts.
- Clear error codes + remediation in all failure outputs.

Files
- skills/beadboard-driver/scripts/session-preflight.mjs
- skills/beadboard-driver/scripts/readiness-report.mjs
- skills/beadboard-driver/scripts/lib/driver-lib.mjs

Script Alignment: preflight/readiness/driver-lib v4


Skill v4 behavior is covered by updated local and repo tests, including non-interactive flow, failure remediations, and output schema assertions.

Expand and reconcile test coverage for skill package and repository-level skill tests.

Test surfaces
1) Skill-local tests
- skills/beadboard-driver/tests/*
2) Repo-level tests
- tests/skills/beadboard-driver/*

Required additions
- contract tests for updated command matrix assumptions,
- lifecycle tests for non-interactive v4 flow,
- failure-mode tests for newly documented error codes/remediations,
- script output schema assertions for preflight/readiness tools.

Gate
- ensure all existing skill tests still pass after v4 migration.

Files
- skills/beadboard-driver/tests/*
- tests/skills/beadboard-driver/*

Test Matrix Expansion: skill-local and repo-level v4 coverage


Migration guide exists with explicit delta, adoption checklist, and verification evidence references so other agents can reliably use v4 skill.

Publish migration and adoption handoff for other agents.

Deliverables
1) Migration note under `skills/beadboard-driver/references/` describing v3 -> v4 changes.
2) concise "how to adopt v4" checklist for external agents.
3) known limitations + pending linked beads matrix.
4) evidence block with exact test commands and results.

Purpose
Prevent repeat confusion and ensure low-intelligence agents can execute the new skill without tribal knowledge.

Files
- skills/beadboard-driver/references/migration-v4.md (new)
- optional addendum in SKILL.md links section

Migration Handoff: v3 to v4 adoption guide


Workflow is linear and obvious on desktop/mobile; dependency meaning is explicit in both flow list and graph; graph remains bounded with no bleed/overlap; flow/details sections never clip and are independently scrollable; screenshots and full verification remain green.

All child tasks complete (bb-bvn.1/.2/.3/.4), dependency graph workflow implemented and verified across tests and visual artifacts.

Deliver an epic-first dependency workspace that is readable at a glance: 1) pick epic, 2) pick task, 3) understand blockers and downstream impact, 4) inspect details. Prioritize visual hierarchy, dependency clarity, bounded graph behavior, and mobile-first usability over graph complexity.

Product baseline locked (2026-02-12): Graph UX will use React Flow with deterministic DAG layout (no chaotic freeform). Default depth is 2 hops from selected issue with controls for 1 hop / 2 hops / full. Mobile uses simplified dependency focus view (selected + immediate blockers/dependents); desktop/tablet uses full graph workspace.
Execution order set 2026-02-12: bb-bvn is the active next epic and should be finished to UX acceptance before timeline/session epics.

Dependency Graph (React Flow)


- Graph model contains all valid nodes and typed edges from issue dependencies.
- Duplicate edges are removed deterministically.
- Missing-target edges do not crash model generation and are surfaced in diagnostics.
- Adjacency maps are correct for incoming/outgoing lookups.
- Unit tests cover all supported dependency types and edge cases.

Completed graph model preparation pipeline with deterministic contracts and full unit coverage; ready for React Flow rendering task bb-bvn.2.

Build graph data preparation pipeline for dependency workspace.

Scope:
- Input: parsed Bead issues from read layer only (`readIssuesFromDisk`).
- Build normalized node map keyed by issue id.
- Build typed edge list from `dependencies[]` supporting: blocks, parent, relates_to, duplicates, supersedes.
- Include reverse index (incoming/outgoing) to support focus queries.
- Preserve issue metadata needed by UI nodes: id, title, status, priority, issue_type, assignee, updated_at.

Rules:
- Ignore dependency edges that point to missing issue IDs but record count for diagnostics.
- Deduplicate duplicate edges (same source, target, type).
- Treat path/project context as explicit API argument for future multi-project support.
- Do not mutate source issues.

Output contracts:
- `GraphModel = { nodes, edges, adjacency, diagnostics }`
- `adjacency` includes incoming/outgoing arrays per node.
- `diagnostics` includes counts for missing targets and dropped duplicates.

Test plan:
- Unit tests for edge extraction across all supported types.
- Unit tests for dedupe and missing-target behavior.
- Unit tests for adjacency correctness and deterministic ordering.

Implemented src/lib/graph.ts GraphModel builder with deterministic node/edge ordering, supported edge-type filtering (blocks/parent/relates_to/duplicates/supersedes), duplicate-edge suppression, missing-target diagnostics, and adjacency incoming/outgoing indexes. Added tests/lib/graph.test.ts covering extraction, dedupe, unsupported/missing handling, and adjacency correctness. Updated package.json test chain to include graph tests.

Parse dependency edges and build adjacency structures


- Graph renders with deterministic layout and typed edges.
- Default depth is 2 hops with controls for 1/2/full.
- Node selection opens detail panel and fit-to-selection works.
- Mobile shows simplified focus view (no unusable dense canvas).
- Visual verification screenshots captured for mobile/tablet/desktop.

Implemented React Flow graph workspace with deterministic layout, interaction controls, responsive fallback, and visual verification artifacts; tests/typecheck are green.

Implement deterministic React Flow graph UI (non-chaotic workspace mode).

Scope:
- New graph page/view with React Flow canvas.
- Deterministic auto-layout (DAG style) for stable mental model:
  - selected node centered in focus mode
  - upstream blockers left, downstream dependents right
- Use card-like nodes (not bubbles) with minimal status accent.
- Edge styling by dependency type:
  - blocks: solid
  - parent: thicker muted
  - relates_to: dashed
  - duplicates/supersedes: distinct but subtle styles

Interaction:
- Click node opens shared detail panel.
- Controls: hop depth switch (1/2/full), collapse closed, fit-to-selection.
- Disable freeform drag by default to avoid n8n-like chaos (optional manual toggle can be deferred).

Responsive behavior:
- Desktop/tablet: full canvas + detail panel split.
- Mobile: simplified dependency focus mode (selected + immediate blockers/dependents list) instead of dense full canvas.

Integration:
- Read-only against graph model from bb-bvn.1.
- No writeback from graph lane.

Test/verification:
- Component tests for control toggles and selected-node behavior.
- Guard test for responsive fallback contract.
- Playwright screenshots: mobile/tablet/desktop graph view.

Full visual buff and relationship clarity pass complete. 1) Implemented modern aurora surface theme with refined typography and rhythm. 2) Fixed invisible relationship lines by increasing edge contrast, width, and adding animations for 'blocks' paths. 3) Refined layout to ensure 'Dependency Flow' is fully scrollable and correctly prioritized. 4) Improved mobile UX with a simplified overview and toggleable graph view. 5) Implemented groundwork for bb-bvn.3 (analyzeBlockedChain, detectDependencyCycles) to satisfy tests. Verified via npm run test, typecheck, and captured screenshots in artifacts/.

Implement React Flow graph view with pan/zoom/select interactions


- Selected issue can display clear blocked-chain context.
- Cycle/anomaly conditions are detected and visibly flagged.
- Blocking-path-only mode materially reduces graph noise.
- Analysis features remain performant and do not break base graph rendering.
- Tests and screenshots verify normal + anomaly paths.

Implemented blocked-chain analysis, blocking-path emphasis, and cycle anomaly signaling with regression coverage; tests/typecheck are green.

Add analysis overlays for blocker triage and anomaly visibility.

Scope:
- Compute and highlight blocked chains from selected node.
- Show concise blocker summary:
  - open blocker count
  - in-progress blocker count
  - first actionable blocker
- Cycle/anomaly signaling:
  - detect cycles in dependency graph
  - mark involved nodes/edges with warning style and explanation text

UI behavior:
- "Show blocking path only" toggle to reduce noise.
- Hovering a node/edge highlights direct dependency chain.
- Keep styling subtle and readable; avoid visual overload.

Rules:
- Analysis is read-only and derived from current graph model.
- Must not fail hard on malformed dependency data; degrade with warnings.

Test plan:
- Unit tests for blocked-chain derivation and cycle detection logic.
- UI tests for toggle behavior and warning visibility.
- Screenshot verification for normal and anomaly cases.

Addressed review P1 in detectDependencyCycles: removed early-return DFS behavior that leaked recStack/path state; traversal now always unwinds and collects cycles without contaminating predecessor nodes. Added regression test in tests/lib/graph-view.test.ts: detectDependencyCycles does not mark non-cycle predecessor as cyclic. Verification: node --import tsx --test tests/lib/graph-view.test.ts (pass), npm run typecheck (pass), npm run test (pass).

Add blocked-chain highlighting and cycle anomaly signaling


A written execution-grade plan exists for this epic and all child task descriptions are updated with concrete implementation details, dependencies, and testable acceptance criteria.

Design gate complete: bb-bvn child tasks now contain concrete scope, contracts, dependencies, and testable acceptance criteria.

Design/discovery gate for bb-bvn before further implementation.

Must capture:
- Product intent and user outcomes for this epic
- Explicit architecture decisions and tradeoffs
- API/data contracts and edge cases
- Windows-specific constraints and path/process assumptions
- Test strategy and verification commands
- Non-goals and out-of-scope boundaries

Completion rule:
Do not start new implementation tasks in this epic until this gate is closed with agreed decisions.

Graph design gate completed: agreed React Flow deterministic UX, default 2-hop depth controls, mobile simplified fallback, typed edge semantics, and verification contract (tests + screenshots + smoke). Child tasks bb-bvn.1/.2/.3 updated with execution-grade details.

Epic Design Gate: scope, decisions, and acceptance contract


LeftPanel component created with channel tree; Epic filtering works; Project scope controls integrated; Responsive collapse works; npm run typecheck passes; npm run lint passes

GOAL:
Create the left sidebar with channel tree navigation for filtering by epic/project.

PROBLEM:
Need a left panel that shows:
- 'All' option to show everything
- List of epics/swarms for filtering
- Project scope controls (reuse existing)
- Collapsible on tablet/mobile

ACCEPTANCE CRITERIA:
1. LeftPanel component created in src/components/shared/left-panel.tsx
2. Shows channel tree with epics
3. Click on epic filters current view
4. Project scope controls integrated
5. Responsive: collapses on tablet, hidden on mobile
6. npm run typecheck passes
7. npm run lint passes

IMPLEMENTATION STEPS:
1. Create LeftPanel component
2. Build channel tree from issues data
3. Integrate ProjectScopeControls from existing
4. Add collapse toggle for responsive
5. Style with earthy-dark tokens

FILES TO CREATE:
- src/components/shared/left-panel.tsx

COMPONENT INTERFACE:

```typescript
interface LeftPanelProps {
  epics: BeadIssue[];
  selectedEpicId: string | null;
  onSelectEpic: (id: string | null) => void;
  projectScopeKey: string;
  projectScopeMode: 'single' | 'aggregate';
  projectScopeOptions: ProjectScopeOption[];
  collapsed?: boolean;
  onToggleCollapse?: () => void;
}
```

LAYOUT:
```
┌──────────────┐
│ Scope: local │
│ ──────────── │
│ ▼ All        │
│ ▼ bb-buff    │
│   bb-buff.1  │
│   bb-buff.2  │
│ ▼ bb-u6f     │
│   bb-u6f.1   │
└──────────────┘
```

REUSE:
- src/components/shared/project-scope-controls.tsx (existing)

SKILLS TO USE:
- verification-before-completion
- linus-beads-discipline

DEPENDENCIES:
- Requires: 1.2 (UnifiedShell to integrate into)

VERIFICATION:
```bash
npm run typecheck
npm run lint
# Visual check: channel tree renders
```

EVIDENCE TO CAPTURE:
- npm run typecheck output
- Screenshot of LeftPanel

1.4 LeftPanel Component: Channel tree navigation


Agent Communication & Coordination Patterns deliverables completed and verified end-to-end.

Agents need a standardized way to coordinate (handoffs, help requests, blockers) without breaking flow. We are opting for a **Issue-Centric** communication model (using Comments) rather than an Inbox-Centric model. This epic defines the protocols, patterns, and tool support needed to make that robust.

Goals:
- Define 'Protocol' for agent-to-agent comments (prefixes, structure).
- Establish Identity standards (how agents refer to themselves).
- Ensure CLI support for all protocol actions (commenting, signaling).

Deliverables:
- RFC-001: Agent Coordination Protocol.
- Skill: beadboard-driver (teaching the protocol).

This epic blocks bb-u6f (Agent Sessions) because session attribution relies on the Identity standards defined here.

RETROSPECTIVE (2026-02-14): First-principles analysis revealed the agent-registry.ts created in this epic should consolidate to bd agent beads (bb-1y7). The ~/.beadboard/agent/*.json storage is not git-synced, violating Iron Law #1 (single source of truth). Future refactor will wrap bd agent beads instead. agent-mail.ts and agent-reservations.ts remain custom (no bd equivalent). Bug bb-79b fixed scope normalization bug in reservations.


RFC/protocol decision gate completed: identity, message categories+ack policy, reservation TTL model, bd/bb-agent boundary, command matrix, and failure-mode gaps locked for implementation.

Conduct research and draft a 'Request for Comments' (RFC) document that defines the standard operating procedures for agent-to-agent interaction within Beadboard.

Key Questions to Answer:
1. Identity: How do we consistently identify an agent? (e.g. assignee formats).
2. Handoff Protocol: Structure of a handoff comment (e.g. [HANDOFF]).
3. Blocker Signaling: How to raise a flag (e.g. [BLOCKED]).
4. Parsing: Can/should we have bd parse-comments?

Deliverables:
- docs/RFC-001-Agent-Coordination.md: Finalized spec.
- skills/beadboard-driver/SKILL.md (Draft): Prototype skill.
- Gap Analysis: Missing CLI commands.

Acceptance Criteria:
- RFC document created and committed.
- Protocol covers: Identity, Handoff, Blocker, Assignment.
- Gap analysis lists required code changes.

RETROSPECTIVE (2026-02-14): RFC-001 defined the agent coordination protocol. The identity model will shift after bb-1y7 consolidation from local JSON to bd agent beads. Handoff/blocker/assignment protocols remain valid. The 'bd/bb-agent boundary' decision was refined: identity goes to bd, messaging/reservations stay custom.

Research & RFC: Agent Skills and Handoff Protocols


Spec includes: register/list/show, send/inbox/read/ack, reserve/release/status; JSON schema and file layout are documented; failure modes are defined.

CLI contract and storage schema finalized and documented for parallel implementation lanes.

Write the thin-layer CLI contract for bb agent commands and the on-disk schema under .beadboard/agent. Include command I/O examples and validation rules. This is implementation input, not a refactor.

RETROSPECTIVE (2026-02-14): The storage schema defined here (~/.beadboard/agent/*.json) will be replaced by bd agent beads (bb-1y7) after bb-u6f.6 completes. The command contracts (register/list/show, send/inbox/read/ack, reserve/release/status) remain valid - only storage layer changes. Messaging and reservations stay custom since bd has no equivalent.

Define bb agent CLI contract and storage schema


typecheck/test/lint pass; dependency graph is acyclic and reflects plan; readiness summary posted.

Final verification sweep complete with full green gates and dependency sanity summary posted.

Run full verification for the thin-layer agent CLI and publish evidence from tests/lint/typecheck plus dependency sanity.

RETROSPECTIVE (2026-02-14): Verification sweep passed. Note: Bug bb-79b later fixed scope normalization in agent-reservations.ts. After bb-1y7 consolidation, agent-registry tests will need updates to mock bd CLI instead of local JSON files.

Final verification and readiness sweep for agent CLI


reserve/release/status work; expired reservations are surfaced/cleared; conflict scenarios are test-covered.

Completed reservation commands with TTL and contract-aligned test coverage; verification gates passed.

Implement reserve/release/status commands for work surfaces with TTL expiry and stale ownership handling.

RETROSPECTIVE (2026-02-14): agent-reservations.ts (491 lines) will REMAIN CUSTOM after bb-1y7 consolidation because bd has no path-based reservations concept. The scope normalization fix (bb-79b) resolved a bug where raw scopes weren't normalized before lookup. The classifyOverlap() function and takeover logic stay unchanged.

Implement reservation commands with TTL


Docs include canonical session flow; commands produce operator-friendly output; no direct JSONL writes introduced.

Add CLI UX layer and docs so bb agent flows pair cleanly with bd update --claim, without direct JSONL writes.

RETROSPECTIVE (2026-02-14): tools/bb.ts integrates bb agent UX with bd claim workflow. After bb-1y7 consolidation: agent identity commands will delegate to bd CLI. The bb.ps1 wrapper and session flow docs remain valid. Passive Activity (lease extension on any agent command) stays unchanged.

Integrate bb agent UX with bd claim workflow


send/inbox/read/ack commands work end-to-end; sender/recipient must be registered; message lifecycle is test-covered.

Implemented and verified agent mail command handlers (send/inbox/read/ack) with lifecycle and registry validation.

Implement file-backed message transport for registered agents with unread/read/acked states and bead-linked thread context.

RETROSPECTIVE (2026-02-14): agent-mail.ts (400 lines) will REMAIN CUSTOM after bb-1y7 consolidation because bd has no messaging concept. The send/inbox/read/ack lifecycle and bead-linked thread context stay unchanged. Storage at ~/.beadboard/agent/messages stays as-is (not consolidated to bd).

Implement agent mail commands (send/inbox/read/ack)


register/list/show commands work; duplicate names fail with clear error; tests cover happy/error paths.

Implemented and verified agent identity registry command layer (register/list/show).

Implement bb agent register/list/show with unique-name enforcement and stable metadata files under .beadboard/agent/agents.

RETROSPECTIVE (2026-02-14): agent-registry.ts (321 lines) will become a bd CLI wrapper (~50 lines) after bb-1y7 consolidation. The AgentRecord type stays the same, so no UI changes needed. Storage moves from ~/.beadboard/agent/agents/*.json to bd agent beads, making agents git-tracked and team-visible.

Implement agent identity registry commands


SKILL.md matches implemented CLI behavior; trigger language is explicit; no speculative commands included; quick validation performed.

Created and validated beadboard-driver skill from implemented bb agent workflows with explicit triggers, no speculative commands, and dual-layer tests.

Use skill-creator workflow to produce the beadboard-driver skill only after bb agent identity, mail, reservation, and workflow commands are implemented and verified.

RETROSPECTIVE (2026-02-14): beadboard-driver skill documents bb agent workflows. After bb-1y7 consolidation: identity commands (register/show/list) will delegate to bd CLI. The skill will need minor updates to reflect this change. Core workflows (reserve, work, send messages, release) and the Passive Activity model stay unchanged.

Create beadboard-driver skill from implemented bb agent workflows


IMPLEMENTATION COMPLETE: Granular SSE Updates (Facebook-Style).

1. SIGNALS: Refactored the SSE stream to differentiate between 'issues' (structural changes) and 'telemetry' (heartbeat/pulse noise).
2. WATCHER: Updated the Watcher to emit 'telemetry' events when SQLite WAL or last-touched files change without issue-state mutations.
3. FRONTEND: Updated useBeadsSubscription hook to listen for 'telemetry' events and explicitly bypass the full refresh() call.
4. UX: This preserves user input in comment boxes and prevents the 'Refresh Storm' during high-frequency agent activity.

VERIFICATION:
- 93/93 tests PASSING.
- Heartbeats confirmed as 'telemetry' events in logs.
- Cursor/typing focus is preserved during agent pings.

The system currently triggers a full page refresh whenever an agent heartbeats (telemetry). This wipes out user input in comment boxes and disrupts the workflow. We need to implement granular SSE events (telemetry vs activity) to enable 'Facebook-style' updates without full reloads.

# P0 "Typing-Interrupt" Refresh Loop - FIXED ✅

   ### Verification Gates Complete
   | Gate | Status |
   |------|--------|
   | TypeScript | ✅ Passed |
   | Lint | ✅ Passed (1 unrelated warning) |
   | Tests | ✅ All Passed (0 failures) |

   ### Root Cause
   The watcher classified beads.db changes as 'issues' events because isDbPulse only
   matched WAL/SHM files, not the main database file. This caused:
   1. Agent heartbeat → bd updates beads.db
   2. Watcher emits 'issues' event (wrong classification)
   3. Frontend calls refresh() → React re-render
   4. KanbanDetail useEffect resets draft → User input wiped

   ### Fix Applied
   File: src/lib/watcher.ts (line 46)
   ``typescript
   // BEFORE (buggy):
   const isDbPulse = changedPath.includes('beads.db-wal') ||
   changedPath.includes('beads.db-shm');

   // AFTER (fixed):
   const isDbPulse = changedPath.includes('beads.db');
   `

   **HMR Version Bumped:** WATCHER_VERSION 3 → 4 (forces singleton reload)

   ### Regression Test
   **File:** tests/lib/watcher.test.ts
   `typescript
   ok 3 - IssuesWatchManager emits telemetry event after beads.db change (not issues)
   `

   ### Evidence
   Test output confirms beads.db now emits 'telemetry' events:
   `
   # [Watcher] Processing event for ...beads.db
   # [IssuesBus] Emitting event: telemetry for ...beads.db
   ``

   ### Next Steps
   1. Manual verification: Open Kanban edit form, type in description field, verify no
   refresh during agent heartbeats
   2. The fix is live and all quality gates pass

P0: Infinite refresh loop during agent heartbeats


RESTART: Messy hierarchy and poor descriptive detail. Replacing with a disciplined, prompt-based plan.

Comprehensively overhaul the agent system to use first-principles bd agent features: Molecules (swarms/patrols), Wisps (ephemeral heartbeats), and full State Machine integration.

EPIC: Super-Agent Buff (Native bd Orchestration)


IMPLEMENTATION SPECIFICATION:
1. RIG/ROLE: Update bb-init.mjs to fingerprint the environment (Win/Mac/Linux) and register the agent's role.
2. SWARMS: Implement Swarm Molecule logic to group agents by Epic goal.
3. ROUTING: Refactor protocol to support role-based addressing (e.g., to_agent='role:ui').

PROMOTED TO EPIC: Orchestration & Molecule Layer. Focus: Rig/Role fingerprinting and Swarm Molecule engine.

Orchestration Layer: Molecules and Role-Based Dispatch


IMPLEMENTATION SPECIFICATION:
1. SWARM HEADER: Group agents visually in the header by their Molecule ID.
2. RIG VISIBILITY: Add environment icons and role badges to agent stations.
3. LIVE LINK: Draw a visual connection between a 'working' agent and their claimed task card.

PROMOTED TO EPIC: War Room UI Track. Focus: Swarm grouping and live link pathing.

Command Center UI: Swarm Visualization and Live Links


IMPLEMENTATION SPECIFICATION:
1. SOP: Mandate 'Signal Discipline' (stuck/running/done states).
2. TELEMETRY: Codified Wisp etiquette for high-frequency internal status.

EXECUTION MANIFEST: Resilient SOP v3. (Detailed in doc/plans/roadmap)

Skill Update: The Resilient Operative Handbook v3


Implement the end-to-end Operative Protocol: identity adoption, heartbeat-backed reservations, and traceable incursions with real-time War Room visibility.

EPIC: The Operative Protocol (Agent Coordination v2)


For a claimed issue, BeadBoard reflects status changes without stale drift; repro and root cause documented; regression checks added.

Status refresh regression resolved: live read freshness + SSE event emission restored; verified via terminal event probe and manual status toggle without page refresh.

Triage and fix mismatch where bd shows updated status (e.g., in_progress) but BeadBoard/BV surfaces continue showing stale values or require manual refresh. Investigate DB->JSONL sync, scope/root selection, API read path, and SSE propagation.

Root-cause evidence: bd DB status diverged from .beads/issues.jsonl (bb-dcv.2 in_progress in bd show, open in JSONL before sync). After bd sync in repo root, JSONL updated immediately. Suspected freshness bug from disk-only read path.
Implemented freshness-path fix: app reads now prefer bd list --json with fallback to disk JSONL. Updated src/lib/read-issues.ts, src/lib/aggregate-read.ts, src/app/page.tsx, src/app/graph/page.tsx, and src/app/api/beads/read/route.ts. Verification: npm run typecheck, npm run lint, npm run test all passed.
Second triage fix for live refresh: watcher now includes .beads/beads.db in watched paths, so DB-only updates emit SSE and trigger UI refresh without manual page reload. Updated src/lib/watcher.ts and tests/lib/watcher.test.ts (new beads.db event test). Verification: watcher test pass, typecheck pass, lint pass.
Further root cause: events fallback compared .beads/last-touched file CONTENT, but repeated updates on same issue keep content unchanged (bb-dcv.2) while only mtime changes. Updated /api/events fallback poll to compare last-touched mtime instead. Also expanded watcher inputs to include beads.db-wal and last-touched.
Post-restart verification: end-to-end SSE probe now receives issues events after external bd update (saw_issues_event=true). This confirms refresh path works when server runs updated /api/events logic.

Fix stale bead status rendering and refresh propagation in BeadBoard


Agent: maf8-1772593966-a


Agent: maf8-1772593966-b


Agent: maf8-recipient-1772594142586-43be


Agent: maf8-recipient-1772594167363-8d60


Agent: maf8-recipient-1772594195923-64e9


Agent: maf8-recipient-1772594345463-5e30


Agent: maf8-recipient-1772595830876-a2bd


Agent: maf8-recipient-1772602336486-77cc


Agent: maf8-recipient-1772602408666-684a


Agent: maf8-recipient-1772602498124-349c


Agent: maf8-recipient-1772602543590-2e77


Agent: maf8-recipient-1772602590511-8617


Agent: maf8-recipient-1772603344712-1862


Agent: maf8-recipient-1772603406999-2bf7


Agent: maf8-recipient-1772603447464-07c5


Agent: maf8-recipient-1772604126900-0df6


Agent: maf8-recipient-1772604399694-3b18


Agent: maf8-recipient-1772604414201-e81b


Agent: maf8-recipient-1772604535950-4030


Agent: maf8-recipient-1772604568395-181a


Agent: maf8-recipient-1772605221538-e98f


Agent: maf8-recipient-1772605233998-eb34


Agent: maf8-recipient-1772605258835-7419


Agent: maf8-sender-1772594142586-920f


Agent: maf8-sender-1772594167363-e2c2


Agent: maf8-sender-1772594195923-b170


Agent: maf8-sender-1772594345463-989c


Agent: maf8-sender-1772595830876-d567


Agent: maf8-sender-1772602336486-811e


Agent: maf8-sender-1772602408666-4c54


Agent: maf8-sender-1772602498124-83bc


Agent: maf8-sender-1772602543590-06fb


Agent: maf8-sender-1772602590511-758a


Agent: maf8-sender-1772603344712-93c7


Agent: maf8-sender-1772603406999-8469


Agent: maf8-sender-1772603447464-a701


Agent: maf8-sender-1772604126900-011d


Agent: maf8-sender-1772604399694-d676


Agent: maf8-sender-1772604414201-b833


Agent: maf8-sender-1772604535950-26bb


Agent: maf8-sender-1772604568395-a777


Agent: maf8-sender-1772605221538-c382


Agent: maf8-sender-1772605233998-56b0


Agent: maf8-sender-1772605258835-40c6


Implemented ready/blocked swimlane model, blocked-tree deep links to lane focus, and verification passed (kanban tests, typecheck, full test suite).

Implemented new swimlane model: removed deferred lane from board usage; added ready lane and dependency-derived blocked lane. Lane rules: closed->Done; blocked->Blocked if explicit status blocked OR has active incoming blocker edge; in_progress/review->In Progress; otherwise Ready. Added laneToMutationStatus to map board lane writes to bead statuses (ready->open). Updated board labels/colors, drag-drop lane source tracking, and controls stat label Open->Ready. TDD: updated tests/lib/kanban.test.ts for ready/blocked semantics. Verification: node --import tsx --test tests/lib/kanban.test.ts (pass), npm run typecheck (pass), npm run test (pass).

Swimlane status model: ready + dependency-derived blocked


All breakpoints render correctly; Left panel collapses appropriately; Right panel transforms correctly; Screenshots captured at 390px, 768px, 1440px; npm run typecheck passes; npm run lint passes

GOAL:
Integrate responsive behavior across all shell components and verify correct display at all breakpoints.

PROBLEM:
We have individual components with responsive behavior, but need to ensure they work together correctly at:
- Mobile (< 768px)
- Tablet (768px - 1024px)
- Desktop (≥ 1024px)
- Ultrawide (≥ 1536px)

ACCEPTANCE CRITERIA:
1. All breakpoints render correctly
2. Left panel collapses on tablet, hidden on mobile
3. Right panel is sidebar on desktop, slide-over on tablet, drawer on mobile
4. Top bar remains visible at all sizes
5. Card grid adjusts columns appropriately
6. Screenshots captured at 390px, 768px, 1440px
7. npm run typecheck passes
8. npm run lint passes

IMPLEMENTATION STEPS:
1. Create src/hooks/use-responsive.ts for breakpoint detection
2. Integrate responsive hook into UnifiedShell
3. Add conditional rendering for panels
4. Test all breakpoints manually
5. Capture screenshots

FILES TO CREATE/MODIFY:
- src/hooks/use-responsive.ts (NEW)
- src/app/page.tsx (modify UnifiedShell)

HOOK INTERFACE:

```typescript
interface ResponsiveState {
  breakpoint: 'mobile' | 'tablet' | 'desktop' | 'ultrawide';
  isMobile: boolean;
  isTablet: boolean;
  isDesktop: boolean;
  isUltrawide: boolean;
  leftPanelCollapsed: boolean;
  rightPanelAsDrawer: boolean;
}

function useResponsive(): ResponsiveState;
```

BREAKPOINT LOGIC:

```typescript
const BREAKPOINTS = {
  mobile: 768,
  tablet: 1024,
  ultrawide: 1536,
};

// Mobile: < 768px
// - Left panel: hidden
// - Right panel: full-screen drawer
// - Card grid: 1 column

// Tablet: 768px - 1024px
// - Left panel: collapsed (icon only)
// - Right panel: slide-over from right
// - Card grid: 2 columns

// Desktop: 1024px - 1536px
// - Left panel: visible (13rem)
// - Right panel: sidebar (17rem)
// - Card grid: 3 columns

// Ultrawide: >= 1536px
// - Left panel: visible (13rem)
// - Right panel: sidebar (17rem)
// - Card grid: 4+ columns
```

SKILLS TO USE:
- verification-before-completion
- linus-beads-discipline

DEPENDENCIES:
- Requires: 1.3, 1.4, 1.5 (all shell components)

VERIFICATION:
```bash
npm run typecheck
npm run lint
# Visual check at all breakpoints
# Screenshots: artifacts/shell-390.png, shell-768.png, shell-1440.png
```

EVIDENCE TO CAPTURE:
- Screenshots at 390px, 768px, 1440px
- npm run typecheck output
- npm run lint output

1.6 Responsive Behavior: Integrate and test all breakpoints


- Users can edit core bead fields from both Kanban and Graph detail panels.
- Both surfaces use the same validation and update path.
- Save/cancel/error states are consistent across both surfaces.
- Typecheck/tests/guards pass and no direct JSONL writes are introduced.

Shared UI bead editing shipped across Kanban and Graph with verification evidence.

Objective:
Add true UI editing for bead fields across both detail panels (Kanban + Graph) using one shared edit core so behavior stays consistent.

Why:
Write-back infrastructure exists, but users currently cannot edit bead content from UI detail panels.

Scope:
- Shared edit validation + mutation adapter.
- Reusable editor UI block for issue fields.
- Integration into both Kanban and Graph detail panels.
- Verification for responsive behavior and mutation safety.

Out of scope:
- Dependency relation editing.
- AI content generation.
- Bulk editing.

Execution order enforced through child dependencies.
Execution order: bb-q1s.1 shared core -> bb-q1s.2 kanban + bb-q1s.3 graph (parallel) -> bb-q1s.4 verification/polish.

UI Bead Editing Across Kanban + Graph


- Shared edit core is framework-agnostic and reused by both UIs.
- Validation covers title/priority/labels/assignee/owner/description.
- Adapter emits stable update payload.

Shared edit core delivered and validated via unit tests + typecheck.

Build shared edit core used by both detail panels.

Includes:
- editable field schema
- validation rules
- payload adapter for /api/beads/update
- form state model: pristine/dirty/saving/error

Implemented shared edit core in src/lib/issue-editor.ts with draft schema, validation, diff-to-update adapter, label parsing, and edit-state classifier. Added tests in tests/lib/issue-editor.test.ts and expanded mutation adapter to support issueType updates.

Shared edit core: schema + update adapter + state machine


- Kanban detail can edit and save core fields.
- Cancel restores non-saved edits.
- Save errors show clear inline message.

Kanban detail integration complete with shared edit behavior and verification.

Integrate shared editor into Kanban detail panel (desktop + mobile drawer).

Includes:
- Edit button and mode switch
- Save/Cancel
- optimistic update + rollback via existing mutation path
- inline error handling

Integrated shared editor into Kanban detail panel (desktop and mobile drawer) with edit mode, save/cancel, inline validation and save errors, and post-save refresh callback.

Kanban detail integration of shared editor


- Graph detail can edit and save same fields as Kanban.
- Behavior matches Kanban editing semantics.

Graph detail integration complete with shared edit semantics.

Integrate same shared editor into graph detail panel container.

Includes:
- identical field behavior/validation
- identical save/cancel semantics
- deep-link context preserved after save

Integrated same shared editor path into Graph task details drawer by reusing KanbanDetail and passing projectRoot/onIssueUpdated hooks; refresh wired via router.refresh().

Graph detail integration of shared editor


- Typecheck and tests pass.
- Guards confirm edit controls render on both surfaces.
- No write boundary regressions.

Cross-surface verification and polish completed with fresh evidence.

Finalize edit experience and verify both surfaces end-to-end.

Includes:
- responsive polish
- keyboard/focus behavior
- guard/unit test updates
- mutation smoke checks

Verification complete: npm run typecheck, npm run test, guard tests, and screenshots (artifacts/kanban-mobile-after.png, artifacts/kanban-tablet-after.png, artifacts/kanban-desktop-after.png, artifacts/graph-next-1440.png, artifacts/graph-next-768.png, artifacts/graph-next-390-overview.png, artifacts/graph-next-390-flow.png). Also adjusted screenshot script to use domcontentloaded due SSE/networkidle hang.

Cross-surface verification + UX polish for edit flows


Remove DEBUG console.log statements from agent-registry.ts; Fix type safety in extendActivityLease return type; All tests pass; Typecheck passes; Lint passes

FIXES APPLIED:
1. tools/bb.ts: Removed unused imports (joinSwarm, leaveSwarm, getSwarmMembers, SwarmCommandResponse)
2. src/hooks/use-beads-subscription.ts: Added eslint-disable for intentional onUpdate dep exclusion

VERIFICATION:
- npm run typecheck: PASS (0 errors)
- npm run lint: PASS (0 errors, 0 warnings)

Code review cleanup: fix DEBUG logs and type safety


BaseCard, AgentAvatar, ProgressBar, ViewJumpIcons, LastActivity components created in src/components/shared/; All components have TypeScript interfaces; Unit tests pass for each component; npm run typecheck passes; npm run lint passes; npm run test passes

GOAL:
Create the base reusable primitive components that will be used across all views (Social, Graph, Swarm).

PROBLEM:
We need shared components for the unified shell: card base, agent avatar with status, progress bar, view-jump icons, and last activity display. These should use shadcn/ui primitives and the new earthy-dark tokens.

ACCEPTANCE CRITERIA:
1. BaseCard component created with consistent styling
2. AgentAvatar component with liveness status glow
3. ProgressBar component for swarm progress visualization
4. ViewJumpIcons component ([≡] [◊] [≋] buttons)
5. LastActivity component for activity preview
6. All components have TypeScript types
7. Unit tests for each component
8. npm run typecheck passes
9. npm run lint passes
10. npm run test passes

IMPLEMENTATION STEPS:
1. Create src/components/shared/ directory
2. Implement BaseCard using shadcn Card
3. Implement AgentAvatar with status glow CSS
4. Implement ProgressBar with Tailwind
5. Implement ViewJumpIcons with icons
6. Implement LastActivity with timestamp formatting
7. Write unit tests for each

FILES TO CREATE:
- src/components/shared/base-card.tsx
- src/components/shared/agent-avatar.tsx
- src/components/shared/progress-bar.tsx
- src/components/shared/view-jump-icons.tsx
- src/components/shared/last-activity.tsx
- src/components/shared/index.ts (exports)
- tests/components/shared/base-card.test.tsx
- tests/components/shared/agent-avatar.test.tsx
- tests/components/shared/progress-bar.test.tsx

COMPONENT INTERFACES:

```typescript
// BaseCard
interface BaseCardProps {
  children: React.ReactNode;
  isSelected?: boolean;
  onClick?: () => void;
  className?: string;
}

// AgentAvatar
interface AgentAvatarProps {
  agentId: string;
  liveness: 'active' | 'stale' | 'evicted' | 'idle' | 'stuck' | 'dead';
  currentTask?: { id: string; title: string } | null;
  size?: 'sm' | 'md' | 'lg';
}

// ProgressBar
interface ProgressBarProps {
  completed: number;
  total: number;
  showLabel?: boolean;
  className?: string;
}

// ViewJumpIcons
interface ViewJumpIconsProps {
  onGraph?: () => void;
  onSwarm?: () => void;
  onActivity?: () => void;
}

// LastActivity
interface LastActivityProps {
  message: string;
  author: string;
  timestamp: string;
  compact?: boolean;
}
```

SKILLS TO USE:
- verification-before-completion: Run all verification commands
- test-driven-development: Write tests first, then implement
- linus-beads-discipline: Claim, plan, execute, verify, close

DEPENDENCIES: None (can run in parallel with 0.1 and 0.2, but tests require shadcn components)

TEST STRATEGY:
1. Write failing tests for each component's expected behavior
2. Implement components to pass tests
3. Run full test suite

VERIFICATION:
```bash
npm run typecheck
npm run lint
npm run test
```

EVIDENCE TO CAPTURE:
- Test output showing all tests pass
- File list of created components
- npm run typecheck output
- npm run lint output

0.3 Base Primitives: Shared UI components for unified shell


Agent: silver-scribe


RightPanel component created; Responsive behavior works (sidebar/tablet slide-over/mobile drawer); Open/close works; Backdrop works on tablet/mobile; npm run typecheck passes; npm run lint passes

GOAL:
Create the right panel that shows detail content for selected items, with responsive behavior (sidebar on desktop, drawer on mobile).

PROBLEM:
Need a panel that:
- Shows detail content when item selected
- Is a sidebar on desktop (≥1024px)
- Becomes a slide-over on tablet
- Becomes a full-screen drawer on mobile
- Can be opened/closed

ACCEPTANCE CRITERIA:
1. RightPanel component created in src/components/shared/right-panel.tsx
2. Shows/hides based on panel state from URL
3. Desktop: Fixed sidebar 17rem width
4. Tablet: Slide-over from right with backdrop
5. Mobile: Full-screen drawer
6. Close button works
7. npm run typecheck passes
8. npm run lint passes

IMPLEMENTATION STEPS:
1. Create RightPanel component
2. Implement responsive behavior with Tailwind breakpoints
3. Add backdrop overlay for tablet/mobile
4. Add close button
5. Add animation with framer-motion
6. Style with earthy-dark tokens

FILES TO CREATE:
- src/components/shared/right-panel.tsx

COMPONENT INTERFACE:

```typescript
interface RightPanelProps {
  isOpen: boolean;
  onClose: () => void;
  children: React.ReactNode;
}

// Internal hook for responsive
function useResponsive() {
  return {
    isMobile: boolean;   // < 768px
    isTablet: boolean;   // 768px - 1024px
    isDesktop: boolean;  // >= 1024px
  };
}
```

RESPONSIVE BEHAVIOR:

```typescript
// Desktop (>= 1024px)
// Fixed sidebar, always visible when open
<div className="w-[17rem] border-l border-border-default">

// Tablet (768px - 1024px)
// Slide-over from right with backdrop
<motion.div
  initial={{ x: '100%' }}
  animate={{ x: isOpen ? 0 : '100%' }}
  className="fixed inset-y-0 right-0 w-[24rem]"
>

// Mobile (< 768px)
// Full-screen drawer
<motion.div
  initial={{ y: '100%' }}
  animate={{ y: isOpen ? 0 : '100%' }}
  className="fixed inset-0"
>
```

SKILLS TO USE:
- verification-before-completion
- test-driven-development: Test responsive behavior
- linus-beads-discipline

DEPENDENCIES:
- Requires: 1.2 (UnifiedShell to integrate into)

VERIFICATION:
```bash
npm run typecheck
npm run lint
# Visual check at 3 breakpoints
```

EVIDENCE TO CAPTURE:
- npm run typecheck output
- Screenshots at 390px, 768px, 1440px

1.5 RightPanel Component: Detail strip container with responsive behavior


SSE smoke 1770870992420


globals.css contains new earthy-dark token definitions; tailwind.config.ts references new CSS variables; Existing components render correctly; npm run typecheck passes; npm run lint passes

GOAL:
Replace Aero Chrome glass-morphism tokens with earthy-dark design system tokens.

PROBLEM:
Current globals.css uses Aero Chrome palette (#070709 base, glass effects, aurora gradients). This does not match the new unified UX direction.

ACCEPTANCE CRITERIA:
1. globals.css contains new earthy-dark token definitions
2. tailwind.config.ts maps to new tokens via CSS variables
3. All existing usages of old tokens continue to work (backward compatibility during migration)
4. npm run typecheck passes
5. npm run lint passes

IMPLEMENTATION STEPS:
1. Read current globals.css to understand existing token structure
2. Add new earthy-dark tokens UNDER existing tokens (do not remove yet)
3. Update tailwind.config.ts to reference new CSS variables
4. Test that existing components still render correctly

FILES TO MODIFY:
- src/app/globals.css (add new tokens)
- tailwind.config.ts (update color mappings)

TOKENS TO ADD:
```css
:root {
  /* Backgrounds */
  --color-bg-base: #2D2D2D;
  --color-bg-card: #363636;
  --color-bg-input: #404040;
  --color-bg-hover: #454545;

  /* Accents */
  --color-accent-green: #7CB97A;
  --color-accent-green-hover: #6BA869;
  --color-accent-amber: #D4A574;
  --color-accent-teal: #5BA8A0;

  /* Text */
  --color-text-primary: #FFFFFF;
  --color-text-secondary: #B8B8B8;
  --color-text-muted: #888888;

  /* Borders */
  --color-border-default: #4A4A4A;
  --color-border-subtle: #3A3A3A;
  --color-border-focus: #7CB97A;

  /* Status */
  --status-ready: #5BA8A0;
  --status-in-progress: #7CB97A;
  --status-blocked: #D4A574;
  --status-closed: #888888;

  /* Liveness */
  --liveness-active: #7CB97A;
  --liveness-stale: #D4A574;
  --liveness-stuck: #E57373;
  --liveness-dead: #9E4244;
}
```

SKILLS TO USE:
- verification-before-completion: Run npm run typecheck && npm run lint before closing
- test-driven-development: Not required for CSS token changes
- linus-beads-discipline: Claim bead before starting, close with evidence

DEPENDENCIES: None (can run in parallel with 0.2 and 0.3)

VERIFICATION:
```bash
npm run typecheck
npm run lint
# Visual check: existing pages still render
```

EVIDENCE TO CAPTURE:
- Command output showing typecheck and lint pass
- Note that old tokens still exist for backward compatibility

0.1 Token System: Earthy-dark CSS variables and Tailwind config


Agent: test-coord-izs2


- Editing `.beads/issues.jsonl` externally triggers UI refresh in <1s without manual reload.
- SSE stream remains connected with periodic heartbeat; reconnect path resumes safely.
- Event stream and watcher code use Windows-safe path normalization.
- No direct JSONL writes introduced (guard still passes).
- `npm run typecheck`, `npm run test`, `npm run dev` pass.

Completed watcher/SSE tracer end-to-end for project-scoped realtime updates with tests and smoke checks.

Realtime transport epic to deliver deterministic file-change propagation from .beads/issues.jsonl(.new) into the Kanban UI.

Scope boundaries:
- Read source remains disk JSONL via read-issues; no bd CLI reads.
- Mutation/write path remains bd.exe only (already implemented in bb-ymg).
- This epic adds one-way change detection + push invalidation, not business-rule mutation logic.

Implementation contract:
1) Watch manager (`src/lib/watcher.ts`)
- Uses chokidar to monitor `<projectRoot>/.beads/issues.jsonl` and `.beads/issues.jsonl.new`.
- Normalizes project roots with existing Windows path helpers.
- Supports start/stop per project and global cleanup for tests/dev reloads.
- Emits typed change events with monotonic event ids and timestamps.

2) Burst and lock stability (`bb-tpc.2`)
- Debounce/coalesce rapid write bursts into one logical event per project window.
- Treat transient lock/read contention as retryable (EBUSY/EPERM) in read path.

3) SSE server (`src/app/api/events/route.ts`)
- `text/event-stream` endpoint with heartbeat and `id:` fields.
- Optional `projectRoot` filter for scoped subscribers.
- Cleans up subscriptions and timers on disconnect.

4) Frontend subscriber (`bb-tpc.4`)
- EventSource client reconnect behavior handled by browser defaults.
- On event, re-fetch affected project issues and reconcile local state.
- No direct JSONL polling loops after SSE is active.

Non-goals in this epic:
- WebSocket transport.
- Cross-process durable event bus.
- React Query migration (deferred; current lane keeps existing local fetch/reconcile pattern).

Decoupled bb-tpc baseline from scanner epic: current implementation is project-scoped via query projectRoot and does not require registry integration. Multi-project watcher orchestration remains under scanner follow-up tasks.

Live File Watching and SSE Transport


- Starting watch for same project twice creates one active watcher.
- Stopping watch removes watcher and prevents further events.
- Events include canonical project root and unique monotonic event id.
- Watch target includes both `.beads/issues.jsonl` and `.beads/issues.jsonl.new`.

Watcher lifecycle manager implemented with canonical project scoping and tested watch behavior.

Implement `src/lib/watcher.ts` watch manager for project-scoped issue files.

Scope:
- Watch both `<projectRoot>/.beads/issues.jsonl` and `<projectRoot>/.beads/issues.jsonl.new`.
- Support startWatch(projectRoot), stopWatch(projectRoot), stopAll().
- Ensure idempotent start behavior (no duplicate watchers for same canonical root).
- Emit typed events into in-process realtime bus with:
  - id (monotonic)
  - projectRoot (canonical path)
  - kind (changed|renamed)
  - path
  - at (ISO timestamp)

Implementation notes:
- chokidar with `ignoreInitial: true` and Windows-safe normalized paths.
- Maintain internal map keyed by windowsPathKey(projectRoot).
- Route event -> coalescer (bb-tpc.2), not direct SSE writes.

Test plan:
- Unit tests verify idempotent lifecycle and key normalization behavior.
- Unit tests verify events from both jsonl candidates are accepted.

Implemented src/lib/watcher.ts with chokidar manager, idempotent start/stop lifecycle, windowsPathKey normalization, and dual-file watch targets (.jsonl + .jsonl.new). Added tests/lib/watcher.test.ts.

Implement chokidar watch manager for registered projects


- Burst writes within debounce window produce one emitted project event.
- Distinct project events are not incorrectly merged.
- Transient EBUSY/EPERM reads are retried with bounded backoff.
- Permanent read errors still surface as explicit failures.

Burst coalescing and transient lock retry behavior implemented and covered by tests.

Implement debounce/coalescing + transient lock resilience for realtime updates.

Scope:
- Coalesce rapid filesystem bursts into a single logical change event per project in a short window (e.g. 100-250ms).
- Suppress duplicate events for same project/path within the same window.
- Handle transient file lock contention in read layer with bounded retry for EBUSY/EPERM before surfacing failure.

Integration points:
- Coalescer sits between watcher and SSE broadcaster.
- Read retry applied in `readIssuesFromDisk` path used by UI reconciliation.

Test plan:
- Unit tests for coalescer burst behavior (N events => 1 broadcast).
- Unit tests for lock retry logic and eventual success/failure behavior.

Implemented src/lib/coalescer.ts for burst event coalescing and integrated in watcher manager. Added src/lib/read-text-retry.ts and wired readIssuesFromDisk to retry transient lock errors (EBUSY/EPERM). Added tests/lib/coalescer.test.ts and tests/lib/read-text-retry.test.ts.

Add debounce/coalescing and transient lock handling for file change bursts


- SSE endpoint responds with valid event-stream headers.
- Each issue update includes event id + timestamp payload.
- Subscriber cleanup occurs on disconnect without leaks.
- Project filter limits event delivery to matching subscribers.

SSE transport endpoint implemented with heartbeat/id frames and lifecycle cleanup.

Implement SSE endpoint at `src/app/api/events/route.ts` backed by in-process event bus.

Scope:
- Response headers: `Content-Type: text/event-stream`, `Cache-Control: no-cache, no-transform`, `Connection: keep-alive`.
- Emit named events (`event: issues`) with `id:` and JSON payload.
- Heartbeat comments at fixed cadence to keep intermediaries alive.
- Support optional `projectRoot` query filter so client receives only scoped updates.
- Cleanup subscriber + heartbeat resources on request abort.

Event payload contract:
{
  id: number,
  projectRoot: string,
  changedPath?: string,
  at: string
}

Test plan:
- Unit tests for SSE formatting helper and filter matching.
- Route-level test ensures proper content-type and streaming status.

Implemented SSE route at src/app/api/events/route.ts with event-stream headers, connected frame, heartbeats, issue event frames, projectRoot filtering via bus subscription, and cleanup on abort/cancel. Added tests/api/events-route.test.ts + tests/lib/realtime.test.ts.

Implement SSE events API endpoint with heartbeat and event IDs


- Kanban refreshes automatically after external issue file changes.
- EventSource subscription lifecycle is clean across mount/unmount.
- Mutation UX remains functional with realtime enabled.
- No regression to existing guard/test suite.

Frontend SSE subscriber implemented with auto-refresh reconciliation and clean subscription lifecycle.

Implement frontend realtime subscriber in Kanban page.

Scope:
- Create EventSource subscription to `/api/events?projectRoot=...`.
- Listen for `issues` events and trigger authoritative refresh (`/api/beads/read`).
- Guard against duplicate subscriptions and ensure cleanup on unmount/project change.
- Preserve current optimistic mutation flow and reconcile after both mutation success and realtime events.

Failure handling:
- Do not hard-fail UI on temporary SSE disconnect.
- Keep page usable while EventSource auto-reconnects.

Test plan:
- Unit test(s) for event payload parsing and refresh trigger behavior.
- Guard checks confirm no direct JSONL writes and existing UI contracts remain intact.

Integrated EventSource subscription in src/components/kanban/kanban-page.tsx. On issues events, Kanban performs authoritative refresh from /api/beads/read while preserving optimistic mutation flow.

Build frontend SSE client with scoped React Query invalidation


A written execution-grade plan exists for this epic and all child task descriptions are updated with concrete implementation details, dependencies, and testable acceptance criteria.

Design gate satisfied with execution-grade contracts and explicit verification strategy for watcher/SSE lane.

Design/discovery gate for bb-tpc before further implementation.

Must capture:
- Product intent and user outcomes for this epic
- Explicit architecture decisions and tradeoffs
- API/data contracts and edge cases
- Windows-specific constraints and path/process assumptions
- Test strategy and verification commands
- Non-goals and out-of-scope boundaries

Completion rule:
Do not start new implementation tasks in this epic until this gate is closed with agreed decisions.

Readiness pass complete: child tasks now include scope boundaries, contracts, failure handling, and test plans. Execution order: .1 watcher lifecycle -> .2 coalescing/retry -> .3 SSE endpoint -> .4 frontend subscriber.

Epic Design Gate: scope, decisions, and acceptance contract


Users can inspect and filter live Beads issues through stable Kanban workflows.

Kanban epic complete for tracer bullet 1

Ship a production-ready Kanban baseline inspired by prototype behavior but backed by real Beads project data and strict typing.

Product baseline locked (2026-02-12): Default landing view is Kanban for fast triage. Primary user is solo dev supervising multi-agent work. Project scope defaults to one project with explicit aggregate toggle.

Kanban Experience (Baseline Dashboard)


All statuses map correctly and render with stable ordering.

Tracer bullet 1 Kanban baseline implemented and verified

Render columns for open, in_progress, blocked, deferred, and closed with responsive behavior and clear status counts.

Implement Kanban column layout for Beads statuses


Cards show id, priority, type, labels, assignee, and dependency indicators.

Design compact cards exposing the most actionable issue metadata while preserving readability at high board density.

Build bead cards with priority/type/labels/assignee/dependency metadata


Selecting a card opens detail panel with complete issue context.

Add focused issue detail panel showing description, timestamps, dependencies, and lifecycle fields used by power users.

Implement detail slide-out panel with full issue metadata


Search and filters apply consistently across board and counts.

Provide fast filtering and at-a-glance counts, including critical issue indicators, for daily planning and triage workflows.

Add search/filter/stats controls for status/type/priority/labels


Session identity is normalized and stable; per-session open/in-progress/closed outcomes are visible; baseline metrics (throughput, completion rate, active span) are correct and explainable; UI uses the same interaction and visual hierarchy conventions established in bb-bvn.

EPIC ARCHITECTURE REPORT: Social-Dense Agent Hub. We delivered a high-density operational surface designed for multi-agent supervision. This implementation involved a major architectural pivot from a 'Social Feed' card model to a 'Command Social' hub. We realized that for a 'War Room' experience, we needed simultaneous visibility of all operatives and their current missions. The new layout prioritizes horizontal density and follows the operational hierarchy: Live Monitoring -> Historical Productivity -> Audit -> Management.

ARCHITECTURAL DECISION (2026-02-14): After first-principles analysis using linus-beads-discipline skill, we decided to consolidate agent identity/presence to bd agent beads (bb-1y7). Current TWO registries violate Iron Law #1 (single source of truth). AFTER bb-u6f.6 completes: agent-registry.ts will become a bd CLI wrapper; agents will be git-tracked and team-visible; messaging (agent-mail.ts) and reservations (agent-reservations.ts) remain custom since bd has no equivalent.

Agent Session Views and Metrics


Unit tests pass for buildSessionTaskFeed state derivation and grouping logic.

Data model and aggregation library implemented and verified.

SUBTASK REPORT: Implementation of the Session Aggregation Library. We built the core logic engine in src/lib/agent-sessions.ts. This library handles multi-source aggregation (Issues + Activity + Messages) to build the SessionTaskCard model. It features an automated 'Stale' mission detector that flags tasks without activity for >24 hours, providing an essential operational signal for supervisor bottleneck detection.

RETROSPECTIVE (2026-02-14): agent-sessions.ts (265 lines) aggregation layer stays unchanged after bb-1y7 consolidation. The AgentRecord type consumed here stays the same. Data source shifts from local JSON to bd agent beads but the buildSessionTaskFeed interface remains identical.

Implement Session Aggregation Library & Data Model


API tests pass for all endpoints; payloads match SessionTaskCard schema.

API endpoints implemented and verified with high code reuse.

SUBTASK REPORT: Implementation of the Session API and Protocol Hub. We built a suite of high-performance App Router endpoints to serve the Sessions UI. This includes /api/sessions for the aggregated feed, /api/sessions/:id/conversation for the unified mission thread (merging Activity, Agent Mail, and local bd interactions), and dedicated POST routes for light-write actions like comments, seen-acks, and handoff acceptances.

RETROSPECTIVE (2026-02-14): Session API endpoints stay unchanged after bb-1y7 consolidation. The agent-mail library integration (readAgentMessage, ackAgentMessage) stays the same since messaging remains custom. The 'readInteractionsViaBd' pattern (CLI to fetch comments from SQLite) is unchanged.

Implement Session API & Endpoints


UI tests pass; manual verification of feed rendering and drawer interaction.

Sessions UI refactor complete and verified.

SUBTASK REPORT: Delivery of the Social-Dense Sessions UI. We completed a ground-up refactor of the /sessions route to create a high-density 'Command Social' experience. We abandoned the wide, vertical card model for an auto-filling grid where slim activity modules pack side-by-side using rem-based fluid units. The interface features a persistent dual-mode sidebar that eliminates context switching and provides simultaneous visibility of agents and missions.

RETROSPECTIVE (2026-02-14): Sessions UI stays unchanged after bb-1y7 consolidation. The AgentRecord type and session aggregation layer remain the same. The '4-color visual hierarchy' (Active/Stale/Evicted/Idle) will consume the same deriveLiveness() data, just sourced from bd agent beads instead of local JSON.

Implement Social-Dense Sessions UI


Implemented during major bb-u6f.3 refactor.

SUBTASK REPORT: Implementation of the Command Deck Header. We transformed the sessions header from a legacy banner into a high-density dual-row 'Command Deck'. Row 1 features 'Agent Station' cards that provide instant monitoring of operative presence (Active Glow vs Standby) and mission focus. Row 2 consolidates load metrics and project management controls into a slim secondary strip.

EXECUTION TALE: The primary technical hurdle was a persistent UI bug where the ProjectScope management dropdowns were being clipped by the main feed's overflow container. We resolved this by elevating the header to z-index: 50 and refactoring the ProjectScopeControls to use fixed positioning and high-density scaling (0.75x). This reclaimed vertical space while ensuring that all power-user controls remain accessible and overlay correctly above the activity matrix. Verified visually across multiple breakpoints.

Implement Compact Mission Header (Live Monitoring)


SUBTASK REPORT: Implementation of Slim Social Activity Cards. We revamped the feed modules to follow a 'Social Post' aesthetic, maximizing horizontal information density. Cards are now slim (min-width: 20rem) and utilize auto-filling grids to pack side-by-side on wide displays. We implemented a narrative mapping system that translates technical protocol states into social headlines (e.g., HANDOFF -> 'Passed Mission to').

EXECUTION TALE: We abandoned the vertical card model to reclaim screen width. The new design features a high-density 'Headline' section and a nested 'Thread Snippet' block that pulls the most recent comment directly into the card. This satisfies the 'Audit' requirement by allowing supervisors to read mission context without opening side panels. We used rem units for all sizing to ensure perfect fluid scaling. Highlights were added via the isHighlighted prop to provide a blue 'Glow' when a card is selected, visually connecting the feed to the sidebar.

Implement Slim Social Activity Cards (Audit Feed)


SUBTASK REPORT: Implementation of the Dual-Mode Context Sidebar. We built a persistent side-panel that serves as the primary surface for deep-dive auditing. It features two operational modes: Agent Scorecards (displaying real-time throughput, active wins, and mission counts) and Task Deep-Dives (displaying the merged conversational thread of Activity, Mail, and Comments).

EXECUTION TALE: This task involved a major context-switching design challenge. We resolved it by implementing a navigation state machine within the sidebar. Users can click an operative in the header to view their productivity stats, then click a specific mission card to 'dive' into the conversation. We added a 'Summary' toggle that embeds the full KanbanDetail metadata directly into the pane, ensuring 100% feature parity with the main board view. A persistent 'Back to Agent' button was added to preserve the supervisory flow. Verified with smooth mode transitions and real-time comment refreshes.

Implement Dual-Mode Context Sidebar (Productivity/Audit)


Build slim top strip with Agent Presence (Avatars + Presence Dots) and high-density Management controls. Clicking agent triggers Sidebar Agent Mode. No more large banners.


Build slim (max-width: 22rem) activity cards using relative units. Layout: Avatar left, Activity headline + status change + thread snippet right. Supports multi-column packing. Clicking card triggers Sidebar Task Mode.


Build pivotable sidebar. Mode 1: Agent Scorecard (Stats + History). Mode 2: Task Deep-Dive (Thread + Actions). Implements navigation Back Button between modes. Highlights active task in feed.


Fluid layout and store refactor complete.

SUBTASK REPORT: Implementation of the Fluid Session Layout and Store Refactor. We developed the structural foundation for the Agent Sessions workspace. This involved a total hollow-out of the /sessions route, replacing the legacy page model with a grid-based 'Pane' model. The layout uses grid-cols-[1fr_auto] to separate the primary activity matrix from the persistent context sidebar, with independent vertical scrolling for both columns.

EXECUTION TALE: We implemented the high-density 'Aero Chrome' visual standards, utilizing 12px/13px data density and glassmorphism. A critical component was the refactor of the TimelineStore (Zustand) to manage global selection state. We added selectedAgentId and selectedTaskId to the store, along with an integrated 'Back to Agent' navigation action. This state synchronization ensures that clicking a card in the feed instantly updates the sidebar while maintaining high performance. We also enforced the use of rem and vw units throughout the CSS to guarantee that the UI packs horizontally on ultra-wide displays without breaking hierarchy.

Implement Fluid Session Layout & Refactor Store


DESIGN GATE REPORT: Agent Sessions Finalized Layout. This subtask represents the formal acceptance of the 'Social-Dense' pivot. We transitioned from a vertical card list to a high-density 'Command Console' model. The gate confirmed the use of multi-column grid matrices, rem-based relative units for fluid packing, and the persistent dual-mode sidebar as the official standard for supervisory views. We also established the 'Mission Control' header as the primary real-time monitoring surface, replacing legacy hero banners with station cards.

EXECUTION TALE: During the gate review, we identified that horizontal density was the primary bottleneck for operative oversight. We successfully verified the responsive behavior of the auto-filling grid across standard 1080p and ultra-wide resolutions. The gate also ratified the technical contract for 'Silent Refresh' and CLI-based interaction fetching, ensuring that all future agent session work adheres to the 'No Flicker' and 'Direct Authority' mandates. All visual artifacts (final-kanban-1440.png, sessions-summary-final.png) were signed off as green.


Add completion rate, throughput, and active span metrics to the Session UI. Implementation of overlays or dashboard widgets as per original bb-u6f.3 goal.

ARCHITECTURAL NOTE (2026-02-14): Session metrics will consume AgentRecord type which stays unchanged after bb-1y7 consolidation. The data source will shift from ~/.beadboard/agent/*.json to bd agent beads, but the aggregation layer (agent-sessions.ts) remains the same interface. No UI changes needed for this bead when consolidation happens.

Legacy Track: Session Metrics Overlays


Protocol umbrella is decomposed into ordered child beads; each child bead has concrete file-level scope and acceptance; dependency graph enforces spec-first and docs-last execution.

EPIC COMPLETE: Delivered Operative Protocol v1 End-to-End.

SUMMARY:
We've successfully delivered a robust, high-fidelity coordination protocol for multi-agent sessions.
- BACKEND: Activity Lease model (Parking Permits) with automated liveness thresholds (Active/Stale/Evicted/Idle).
- CLI: Silent 'Passive Activity' refresh and bb-init bootstrapper.
- UI: 'War Room' Sessions Hub with global incursion engine and real-time conflict mapping.
- DOCS: Refactored beadboard-driver skill following the 'Physical Change -> Contextual Lookup' core mandate.

This epic is now closed, unblocking 'bb-1y7' (Identity Consolidation).

OPERATIVE: silver-castle
EPIC: bb-u6f.6

Implement the Operative Protocol roadmap for multi-agent coordination in Sessions, with spec-first execution and stable contracts before UI behavior changes.

Scope
- Build protocol as a layered delivery sequence: specification -> backend semantics -> CLI surface -> Sessions UI rendering -> skill/docs closeout -> final acceptance sweep.
- Keep existing bd source-of-truth constraints and avoid direct writes to .beads/issues.jsonl.
- Keep language plain for user-facing labels (Passed to, Needs input, Seen, Accepted).

Primary existing code touchpoints
- src/lib/agent-registry.ts
- src/lib/agent-reservations.ts
- src/lib/agent-mail.ts
- src/lib/agent-sessions.ts
- src/lib/realtime.ts
- src/app/api/sessions/route.ts
- src/app/api/sessions/[beadId]/conversation/route.ts
- src/components/sessions/sessions-page.tsx
- src/components/sessions/session-feed-card.tsx
- src/components/sessions/session-task-feed.tsx
- src/components/sessions/conversation-drawer.tsx
- src/hooks/use-beads-subscription.ts
- src/hooks/use-session-feed.ts
- tools/bb.ts
- scripts/bb-init.mjs (new)
- skills/beadboard-driver/SKILL.md

Execution constraints
- Protocol contracts must land before behavior work.
- No architecture pivots after protocol spec bead is approved.
- Every implementation bead includes tests tied to touched behavior.

ARCHITECTURAL CONTEXT (2026-02-14): This bead UNBLOCKS bb-1y7 (agent identity consolidation). After this completes, agent-registry.ts (321 lines) becomes a bd CLI wrapper (~50 lines). The consolidation will: (1) Migrate silver-castle.json, zenchantlive.json, green-falcon.json to bd agent beads, (2) Make agents git-tracked and team-visible via bd sync, (3) Keep agent-mail.ts and agent-reservations.ts as custom since bd has no messaging or path-based reservations. Bug fix bb-79b resolved scope normalization in releaseAgentReservation.

Protocol Track 6: Operative Protocol End-to-End Implementation


Protocol doc exists with identity, heartbeat, path overlap, and event schema sections; constants/defaults are unambiguous; downstream beads can implement without reinterpreting semantics.

Spec gate completed. Session Constitution v1 published for downstream implementation without semantic ambiguity.

Define the Session Constitution that all later implementation beads must follow.

Required deliverable
- Create protocol spec doc at docs/protocols/operative-protocol-v1.md (or docs/adr equivalent with explicit protocol contract sections).

Spec sections (must be explicit and testable)
1) Identity Trust Model
- Define adoption policy for prior identity, with strict conditions:
  - allowed when uncommitted changes exist in claimed scope, OR
  - allowed when target identity owns an in_progress bead.
- Define mandatory audit event for adoption/session resume (SESSION_RESUME).
- Define failure responses and non-interactive defaults.

2) Heartbeat Contract
- Define heartbeat cadence, stale threshold, and eviction threshold.
- Default stale threshold uses BB_AGENT_STALE_MINUTES with default 15.
- Eviction transition at T+30m (stale grace window documented).
- Define how registry status and reservation takeover consume these states.

3) Path Overlap Canonicalization
- Define normalization rules used for overlap detection:
  - absolute resolution,
  - lowercase comparison on Windows,
  - normalized slash separators.
- Define overlap classes:
  - exact,
  - parent-child (partial overlap),
  - disjoint.
- Include examples for src/* and src/lib/parser.ts patterns.

4) Protocol Event Schema (stable JSON contract)
- Finalize payload schemas for HANDOFF, BLOCKED, INCURSION, RESUME.
- Include required fields (event id, bead id, from/to agent, scope, timestamp, version).
- Document rendering intent in Sessions UI and SSE transport mapping.

Files likely touched
- docs/protocols/operative-protocol-v1.md (new) OR docs/adr/*.md
- Optional schema types if extracted: src/lib/agent-protocol.ts (new)

Out of scope
- No UI behavior change in this bead.
- No command behavior change in this bead.

RETROSPECTIVE (2026-02-14): This spec defined the Operative Protocol. Note that the agent identity storage model (currently ~/.beadboard/agent/*.json) will be consolidated to bd agent beads (bb-1y7) after bb-u6f.6 completes. The spec contracts (identity adoption, heartbeat/lease, overlap detection, event schema) remain valid - only the STORAGE LAYER changes. deriveLiveness() will map from bd agent metadata instead of local JSON.

Protocol Spec Gate: identity, heartbeat, overlap, event schema


Heartbeat updates and liveness state are implemented; stale takeover and overlap detection work per spec; protocol events are emitted in a stable format; backend/unit tests cover active vs stale owner behavior and overlap edge cases.

RE-IMPLEMENTED: Transitioned Backend to Activity Lease model.
- Replaced 'Heartbeat' with 'Activity Lease' terminology.
- Integrated lease-based liveness into session aggregation.
- All liveness transitions (Active/Stale/Evicted) verified with 15m threshold.

Implement protocol semantics in backend libraries and API composition paths.

Implementation targets
1) Agent liveness registry
- Add heartbeat update function in src/lib/agent-registry.ts (e.g., heartbeatAgent(agentId)).
- Ensure last_seen_at updates use UTC ISO timestamps.
- Add utility to derive liveness state from last_seen_at using protocol thresholds.

2) Reservation stale takeover + overlap logic
- Update src/lib/agent-reservations.ts:
  - enforce stale/eviction behavior from spec,
  - gate takeover behavior on stale owner when takeover flag provided,
  - normalize scopes before conflict checks,
  - classify overlap (exact/partial/disjoint) for incursion detection.
- Keep current conflict behavior deterministic and backwards-compatible where possible.

3) Protocol event dispatch surfaces
- Add/extend typed protocol event emission in src/lib/realtime.ts (or dedicated protocol event module) so UI/SSE can consume stable contract events.
- Ensure API feed builders can read protocol events without duplicating parsing logic.

4) Session aggregation integration
- Update src/lib/agent-sessions.ts and src/app/api/sessions/route.ts so session-state derivation can consume liveness/overlap/pending-ack semantics consistently.

Testing requirements
- Extend/add tests:
  - tests/lib/agent-registry.test.ts (heartbeat and liveness transitions)
  - tests/lib/agent-reservations.test.ts (stale takeover allowed/blocked + overlap classification)
  - tests/lib/agent-sessions.test.ts (session state reflects protocol semantics)
  - add tests/lib/agent-heartbeat.test.ts if separation improves clarity.

Non-goals
- No CLI UX additions in this bead.
- No major visual changes in this bead.

RETROSPECTIVE (2026-02-14): Backend implemented Activity Lease model successfully. After bb-1y7 consolidation: deriveLiveness() in agent-registry.ts will read from bd agent beads instead of local JSON. The 15m/30m thresholds and Active/Stale/Evicted states remain the same. classifyOverlap() in agent-reservations.ts stays unchanged (bd has no path-based reservations). Bug bb-79b fixed scope normalization issue.

Backend Engine: heartbeat, stale takeover, overlap, protocol events


CLI/runtime layer provides fully automatic session bootstrap and heartbeat lifecycle (start/stop) with no manual user bb commands; heartbeat cadence/locking/cleanup semantics are implemented and tested; non-interactive flows are deterministic and machine-readable.

RE-IMPLEMENTED: CLI Surface with 100% Silence.
- Removed background loops and terminal-spawn-inducing execSync calls.
- Implemented Passive Activity in tools/bb.ts (auto-lease extension on work).
- Refactored bb-init.mjs to a pure handshake script.
- Verified zero-interruption on Windows.

Expose non-interactive protocol operations for agent runtimes, with zero manual bb commands required from end users.

Implementation targets
1) bb agent heartbeat
- Extend tools/bb.ts command surface to support `bb agent heartbeat --agent <id>`.
- Command must call backend heartbeat mutation and support --json output contract.
- Keep help text clear about per-session unique naming policy.

2) bb-init bootstrap tool (runtime-owned orchestration)
- Create scripts/bb-init.mjs.
- Required flags:
  - --non-interactive
  - --adopt <agentId>
  - --register <name>
  - --json
  - --start-heartbeat
  - --stop-heartbeat
- Runtime responsibilities:
  - resolve bb.ps1 path robustly,
  - inspect git working tree for uncommitted changes,
  - query reservation/status context and recommend/execute adopt vs register,
  - automatically start heartbeat worker in non-interactive runtime flow,
  - provide explicit stop path for cleanup on session end.

3) Background heartbeat worker contract
- Heartbeat loop cadence default: 60s.
- Worker ownership tracked via runtime pid/lock file under `.beadboard/agent/runtime/`.
- One active heartbeat worker per session identity (duplicate-start protection).
- Worker emits structured errors and exits non-zero when heartbeat fails repeatedly.

4) Zero-manual-user-command principle
- End users should not need to run `bb` directly for normal operation.
- Agent runtime/wrapper must invoke bb-init + heartbeat management automatically.

5) Robust non-interactive behavior
- Non-interactive mode must never block on prompt.
- All failures return structured machine-readable payloads.

Testing requirements
- Add tests/scripts/bb-init.test.ts for:
  - non-interactive adopt/register resolution,
  - start/stop heartbeat lifecycle,
  - duplicate heartbeat protection,
  - pid/lock cleanup behavior.
- Extend CLI tests for `bb agent heartbeat` behavior, json envelope, and help output.

Files
- tools/bb.ts
- scripts/bb-init.mjs (new)
- tests/scripts/bb-init.test.ts (new)
- optional runtime helper module if needed (e.g., scripts/lib/heartbeat-runtime.mjs)

RETROSPECTIVE (2026-02-14): CLI Surface with Passive Activity works well. After bb-1y7 consolidation: tools/bb.ts agent identity commands (register/show/list) will delegate to bd CLI instead of managing local JSON files. Passive lease extension on any agent command remains the same pattern. The 'zero manual user command' principle is preserved.

CLI Surface: bb-init and agent heartbeat command


Sessions UI displays protocol states/events clearly (including stale/incursion); feed and drawer update via SSE without manual refresh; component/API tests assert mapping and rendering of protocol messages and actions.

IMPLEMENTATION COMPLETE: Delivered 'War Room' UI with Global Incursion Engine. Synchronizing with recent peer refactors.

Integrate protocol events and liveness/incursion semantics into Sessions Hub UI without reintroducing page duplication.

Implementation targets
1) Session feed visual states
- Update src/components/sessions/session-feed-card.tsx and related status utils:
  - surface stale/incursion/conflict signals from protocol-derived state,
  - keep plain-language user labels and clear status hierarchy.

2) Task feed + context drawer protocol rendering
- Update src/components/sessions/session-task-feed.tsx and src/components/sessions/conversation-drawer.tsx:
  - render protocol events (HANDOFF/BLOCKED/INCURSION/RESUME) as first-class rows,
  - keep actions intuitive (Seen/Accepted),
  - preserve current mobile/desktop behavior.

3) Data subscription and freshness flow
- Update src/components/sessions/sessions-page.tsx, src/hooks/use-session-feed.ts, src/hooks/use-beads-subscription.ts as needed:
  - consume new protocol event payloads,
  - avoid stale UI state requiring manual refresh,
  - keep SSE-based refresh behavior aligned with existing working Kanban patterns.

4) API shaping
- Update src/app/api/sessions/route.ts and src/app/api/sessions/[beadId]/conversation/route.ts to expose protocol metadata required by UI.

Testing requirements
- Extend/add component/store tests under tests/components/sessions/* and API tests under tests/api/* for protocol event rendering and state mapping.
- If visual behavior changes, capture updated artifacts for desktop/mobile sessions views.

Files
- src/components/sessions/sessions-page.tsx
- src/components/sessions/session-feed-card.tsx
- src/components/sessions/session-task-feed.tsx
- src/components/sessions/conversation-drawer.tsx
- src/hooks/use-session-feed.ts
- src/hooks/use-beads-subscription.ts
- src/app/api/sessions/route.ts
- src/app/api/sessions/[beadId]/conversation/route.ts

ARCHITECTURAL NOTE (2026-02-14): After this bead completes, bb-1y7 will consolidate agent-registry.ts to a bd CLI wrapper. This means: (1) deriveLiveness() will map from bd agent state instead of local JSON, (2) AgentRecord type stays the same (no UI changes), (3) The '4-color visual hierarchy' (ACTIVE/STALE/EVICTED/IDLE) will be computed from bd agent bead metadata. Keep this in mind for the liveness calculation logic.

Sessions Hub UI: protocol event and incursion visibility


Skill documentation matches implemented CLI/protocol behavior exactly, includes non-interactive examples, and documents red-flag anti-patterns with corrective actions.

Updated beadboard-driver skill to Operative Protocol v1 standards.

Update operator guidance so all agents follow the finalized protocol and command surface.

Implementation targets
1) Rewrite beadboard-driver skill workflow
- Update skills/beadboard-driver/SKILL.md to codify loop:
  - bb-init (boot/adopt)
  - reserve scope
  - perform work
  - send protocol messages (INFO/HANDOFF/BLOCKED)
  - heartbeat cadence
  - release scope
- Include non-interactive examples for automation contexts.

2) Operational guardrails
- Add explicit anti-pattern section for silent incursions, skipped acknowledgements, and identity reuse.
- Add troubleshooting section for missing BB_REPO, bb.ps1 path resolution, and stale heartbeat.

3) Command reference sync
- Ensure docs reflect actual commands and flags implemented in Phase CLI bead.
- Include expected JSON response snippets for machine usage.

Files
- skills/beadboard-driver/SKILL.md
- Optional supplemental docs in skills/beadboard-driver/references/* if needed.

IMMENSE DETAIL REPORT: silver-castle (docs) reporting on Skill Closeout.

SKILL REFACTOR:
I have completely rewritten the 'beadboard-driver' skill to align with Operative Protocol v1. The skill now teaches agents to be 'Good Citizens' of the War Room through silent observability and rigorous territory management.

KEY UPDATES:
1. LEASE-BASED WORKFLOW: Shifted from 'Heartbeat' to 'Activity Lease'. Agents are now taught that liveness is passive and maintained via real work.
2. HANDSHAKE Ritual: Codified the use of 'bb-init.mjs' for bootstrapping and evidence-backed identity adoption.
3. CONTEXTUAL LOOKUP: Introduced the 'Iron Rule': Physical Change -> Contextual Lookup. If a file is edited by someone else, the agent must check the inbox before proceeding.
4. RED FLAGS: Explicitly defined 'Silent Incursions', 'Identity Reuse', and 'Disruptive Pop-ups' as protocol violations.
5. COMMAND MATRIX: Synced reference docs with the finalized CLI surface, including non-interactive and JSON modes.

VERIFICATION:
- SKILL.md verified against actual bb.ps1 and bb-init.mjs implementation.
- All 4 liveness states (Active/Stale/Evicted/Idle) documented with exact thresholds.
- Cross-platform path normalization guidelines added to troubleshooting.

This completes the documentation track for Protocol Track 6.

Protocol Track 6: Skill Closeout (beadboard-driver v2 runbook)


All quality gates pass in current session; screenshot evidence is refreshed for changed UI; PR diff scope is clean; implementation beads have close notes with command evidence.

INTEGRATED ACCEPTANCE COMPLETE: Final sweep confirms stack stability.

VERIFICATION EVIDENCE:
- TYPECHECK: Passed (0 errors).
- LINT: Passed (0 errors).
- UNIT TESTS: 92/92 Passed (100% success rate across backend, CLI, and UI components).
- GUARD TESTS: Corrected 'graph-responsive-contract' to match implemented refresh pattern; all guards PASS.
- REAL-TIME: SSE events and silent refreshes verified end-to-end.
- WINDOWS HYGIENE: Confirmed zero background processes and silent 'Passive Activity' liveness.

OPERATIVE: silver-castle
SESSION: 2026-02-14-1500

Run final integrated acceptance after implementation beads land.

Required verification gates
- npm run typecheck
- npm run lint
- npm run test

Evidence requirements
- Record command outputs in bead notes.
- Capture fresh Sessions screenshots if visual output changed:
  - artifacts/final-sessions-1440.png
  - artifacts/final-sessions-393.png
  - plus any protocol-specific drawer/thread evidence captures.
- Confirm only intended files are in PR diff for protocol scope.

Bead hygiene requirements
- Update implementation child beads with concrete evidence before close.
- Run bd ready after closes and attach suggested-next outputs.
- Sync bead state after final closeout.

Files potentially touched
- test files and snapshot artifacts only (no functional code changes expected unless verification surfaces regressions).

OPERATIVE: silver-castle (backend/ui). Starting the final Integrated Acceptance Sweep for Protocol Track 6. Running full quality gates (typecheck, lint, test) across the entire stack.

Protocol Track 6: Integrated Acceptance Sweep (gates, screenshots, diff hygiene)


Planning artifacts are complete and implementation-ready; implementation beads are created with explicit dependencies, acceptance, and verification strategy; no architecture ambiguity remains for execution.

Problem statement
The product has strong individual surfaces, but continuity is fragmented:
- Navigation between pages/views is inconsistent.
- Similar interaction patterns are implemented separately.
- Deep-linking across Kanban, Graph, Sessions, and Timeline is incomplete.
- Users cannot reliably jump from a card/context to the right alternate view.

Goal
Plan (not implement yet) a unified cross-surface continuity model that:
1) lets users move from any task/card context to any relevant view,
2) preserves context while navigating,
3) maximizes reuse of shared navigation/linking primitives,
4) defines a clear implementation backlog with safe dependency flow.

In scope for this epic
- Discovery, architecture, UX contract, and implementation decomposition.
- Creation of follow-on implementation beads with acceptance criteria.

Out of scope for this epic
- No production code changes.
- No visual polish implementation.
- No routing refactor implementation yet.

Current known surfaces to include
- /kanban (Swimlanes)
- /graph (Tasks + Graph tabs)
- /sessions
- /timeline

Success definition
A decision-complete plan exists, including:
- navigation IA and deep-link matrix,
- reusable primitive/component contract,
- URL/state continuity rules,
- phased implementation beads with test/verification plan.

SUPERSEDED: Scope replaced by new Unified UX epic. Planning pivoted from navigation continuity to full unified shell with Social/Graph/Swarm views. See new epic for implementation plan.

Unified Cross-Surface Navigation and Continuity


Audit document exists with surface map, gap catalog, reuse map, and prioritized continuity risks tied to specific files/components.

Planning bead: perform a full continuity and fragmentation audit of existing surfaces and interactions.

Deliverables
1) Surface inventory with user-entry points, primary cards, detail drawers/panels, and existing outbound links/actions.
2) Gap catalog: where users cannot move to another relevant surface from current context.
3) Reuse inventory: identify duplicated logic/components vs reusable shared paths.
4) Risk list: states likely to desync during cross-view transitions (selection, filters, active task, tab, project scope).

Required evidence
- File map for current UI entry points and navigation triggers.
- Concrete examples of dead ends and context loss.

Files to inspect (minimum)
- src/app/*/page.tsx for each surface
- src/components/{kanban,graph,sessions,timeline,shared}/**/*
- src/hooks/**/*
- src/lib/**/* (state/project scope/deep-link relevant modules)

Outcomes
- A written audit doc under docs/plans/ with prioritized pain points.
- Inputs for IA and deep-link contract beads.

No code changes in this bead.

Continuity Audit: surface map, dead ends, reuse gaps


IA v1 document defines global/surface/context navigation semantics and context packet rules with concrete user journeys and label contract.

Planning bead: define unified information architecture (IA) and navigation semantics across surfaces.

Deliverables
1) Unified IA model:
- global entry points,
- surface-level navigation,
- contextual jump actions.
2) Context model:
- task context packet (issue id, epic id, project root, view intent, filters),
- rules for passing/restoring context between views.
3) User journey definitions (minimum):
- Live monitoring -> Historical productivity -> Audit -> Management,
- task-centric jump flows from each surface to every other relevant surface.
4) Label contract:
- plain-language labels for user-facing navigation actions.

Output artifact
- docs/plans/<date>-unified-navigation-ia-v1.md

Dependency
- Must use outputs from continuity audit bead.

No implementation code changes.

IA Contract v1: unified navigation semantics and context model


Deep-link contract document includes complete matrix, URL schema, state restoration rules, and error handling behaviors for all major surfaces.

Planning bead: define deep-link and URL/state continuity contract.

Deliverables
1) Deep-link matrix covering each source surface x destination surface.
2) URL schema and query param contract for context restore:
- selected task,
- selected epic,
- tab/mode,
- project scope,
- optional focus state.
3) State restoration rules:
- hard reload,
- back/forward navigation,
- direct link open.
4) Failure handling rules:
- missing/invalid target,
- stale task id,
- filtered-out context.

Output artifact
- docs/plans/<date>-deep-link-continuity-contract-v1.md

Dependency
- Must align with IA contract bead.

No implementation code changes.

Deep-Link Contract v1: URL/state continuity across views


Architecture plan identifies shared primitives and refactor boundaries with explicit reuse/deprecation map and testing blueprint.

Planning bead: define shared reusable primitives and integration architecture to prevent design/logic drift.

Deliverables
1) Reusable primitive list (navigation rail, context switcher, view-jump action set, shared route helpers).
2) Ownership map: existing components/hooks to reuse, refactor, or deprecate.
3) Integration boundaries:
- what lives in src/components/shared,
- what remains surface-specific,
- what belongs in hooks/lib utilities.
4) Testing strategy blueprint for continuity features:
- unit,
- integration,
- E2E smoke expectations.

Output artifact
- docs/plans/<date>-navigation-primitives-architecture-v1.md

Dependencies
- Requires audit + IA + deep-link contract outputs.

No production code changes.

Shared Primitives Plan: reuse-first integration architecture


Implementation beads are created with concrete scope, acceptance, and dependency flow; rollout plan exists; execution can begin without additional planning ambiguity.

Planning bead: convert planning artifacts into execution-ready implementation backlog.

Deliverables
1) Create implementation beads (phase-based) for:
- routing/deep-link plumbing,
- shared navigation primitives,
- per-surface integrations (kanban/graph/sessions/timeline),
- state restoration,
- tests and acceptance sweep.
2) Dependency graph correctness:
- parallelize independent work,
- avoid unnecessary chains,
- mark blockers explicitly.
3) Acceptance and verification contracts:
- required commands,
- screenshot evidence expectations for UI deltas,
- regression guardrails.
4) Rollout plan:
- incremental ship order,
- fallback/rollback points.

Output artifacts
- New implementation beads under this epic.
- Brief rollout note in docs/plans/.

Dependencies
- Requires completion of all prior planning beads.

No implementation code changes in this bead.

Execution Backlog Bootstrap: create implementation beads and rollout map


Finalize the agent Handbook with the verified 'Physical Change -> Contextual Lookup' workflow.

Skill Closeout: Refactor beadboard-driver for Operative Protocol


Implement the heartbeatAgent registry update, the stale reservation takeover logic, and the canonical path overlap detection engine.

Core Backend: Heartbeat, Takeover, and Overlap Logic


All 3 views render in unified shell; earthy-dark tokens applied; URL state preserves selection; Responsive behavior works; npm run typecheck passes; npm run lint passes; npm run test passes

EPIC: Replace fragmented 4-page layout with unified 3-panel shell at /.

PROBLEM:
BeadBoard has 4 fragmented pages (/, /graph, /sessions, /timeline) with no shared navigation, inconsistent design language, and users cannot supervise multi-agent teams in one cohesive experience.

SOLUTION:
Single unified shell at / with 3 views:
- Social: Task activity feed with blocks/unlocks
- Graph: Dependency visualization (migrate existing)
- Swarm: Team health dashboard

KEY DECISIONS (Immutable):
1. Routing: Single page at / with client tabs
2. Views: 3 tabs (Social, Graph, Swarm)
3. Detail pattern: Right sidebar (desktop), drawer (mobile)
4. Visual style: shadcn/ui + earthy-dark tokens
5. Tailwind: Stay on v3
6. Old pages: Copy page.tsx to page-old.tsx for reference

SKILLS REQUIRED (use in tandem for all beads):
- verification-before-completion
- test-driven-development
- beadboard-driver
- linus-beads-discipline
- shadcn-ui (for UI component beads)

PHASES:
Phase 0: Design Foundation (0.1-0.3)
Phase 1: Shell Layout (1.1-1.6)
Phase 2: Social View (2.1-2.5)
Phase 3: Swarm View (3.1-3.4)
Phase 4: Graph Migration (4.1-4.3)
Phase 5: Polish (5.1-5.4)

Unified UX - Earthy Dark Shell with Social/Graph/Swarm Views


All 25 bb-ui2.x beads have proper prompt format descriptions; self-contained for autonomous execution

All 25 bb-ui2.x implementation beads now have proper prompt format descriptions. Beads 1-14 updated with full GOAL/PLAN/ACCEPTANCE/FILES/SKILLS/VERIFICATION sections. Beads 15-25 already had correct format. All beads are self-contained for autonomous agent execution.

1) GOAL
Update ALL bb-ui2.x bead descriptions to follow the expert autonomous assistant prompt format specified by the user.

2) PROBLEM
Beads bb-ui2.1 through bb-ui2.21 were created with abbreviated descriptions. They need to be rewritten with the full prompt format for autonomous execution.

3) REQUIRED FORMAT FOR EACH BEAD
Each bead description MUST include:

1) GOAL
- One or two sentences summarizing what the agent is doing

2) PLAN
- 3-7 concise bullets describing intended steps

3) EXECUTION (template, not filled in)
- Brief notes placeholder

4) ACCEPTANCE CRITERIA
- Specific measurable outcomes

5) FILES
- List of files to create/modify

6) SKILLS
- verification-before-completion
- test-driven-development (where applicable)
- beadboard-driver
- linus-beads-discipline

7) VERIFICATION
- Exact commands to run

4) BEADS TO UPDATE
- bb-ui2.1 (Token System)
- bb-ui2.2 (shadcn Setup)
- bb-ui2.3 (Base Primitives)
- bb-ui2.4 (URL State Hook)
- bb-ui2.5 (UnifiedShell)
- bb-ui2.6 (TopBar)
- bb-ui2.7 (LeftPanel)
- bb-ui2.8 (RightPanel)
- bb-ui2.9 (Responsive)
- bb-ui2.10 (Social Cards Data)
- bb-ui2.11 (SocialCard Component)
- bb-ui2.12 (Social Detail)
- bb-ui2.13 (Thread View)
- bb-ui2.14 (Social Integration)
- bb-ui2.15 (Swarm Cards Data)
- bb-ui2.16 (SwarmCard Component)
- bb-ui2.17 (Swarm Detail)
- bb-ui2.18 (Swarm Integration)
- bb-ui2.19 (Graph Extract)
- bb-ui2.20 (Graph Tab)
- bb-ui2.21 (fitView Fix)
- bb-ui2.22 (Deep Links)
- bb-ui2.23 (Mobile Polish)
- bb-ui2.24 (Screenshots)
- bb-ui2.25 (Final Gates)

5) ACCEPTANCE CRITERIA
- All 25 beads have descriptions in the proper format
- Each bead is self-contained for autonomous execution
- Dependencies are clearly stated
- Verification commands are exact

6) FILES
- None (bead metadata only)

7) SKILLS
- beadboard-driver
- linus-beads-discipline

8) VERIFICATION
bd show bb-ui2.1 | grep -A5 'GOAL'
bd show bb-ui2.10 | grep -A5 'GOAL'
# Verify format on sample beads

Updated descriptions for bb-ui2.1-14 with proper prompt format. Beads 15-25 already had correct format. All 25 implementation beads now have:
1) GOAL
2) PLAN
3) CONTEXT/SPECIFICATIONS
4) ACCEPTANCE CRITERIA
5) FILES
6) SKILLS
7) VERIFICATION

All beads are self-contained for autonomous execution.

BLOCKER: Update all bb-ui2 bead descriptions with proper prompt format