beadboard/NEXT_SESSION_PROMPT.md

Next Session: Dolt Direct SQL Integration (beadboard-550)

What This Session Accomplished

This session completed Phase 0 and Phase 1 of the UX redesign PRD, then pivoted to a more important infrastructure fix: replacing the stale issues.jsonl read path with direct Dolt SQL queries.

Phase 0 + 1 (done, committed as 7d37d02 and a2e523b)

• unified-shell.tsx: wired blockedOnly to SocialPage, TopBar with live counts
• thread-drawer.tsx: dynamic status instead of hardcoded "In Progress"
• social-page.tsx: fixed onJumpToActivity dead URL
• contextual-right-panel.tsx: added taskId branch (ThreadDrawer embedded) and swarmId branch (MissionInspector via SwarmIdBranch inner component)
• AGENTS.md: documented WSL2 mirrored networking workaround for mixed environments

Why we pivoted to beadboard-550

The frontend reads issues.jsonl as its data source, but bd in dolt-native mode writes to a Dolt SQL server (127.0.0.1:3307). In mixed WSL2+Windows environments (and whenever Windows bd fails with a CGO error), the JSONL gets stale and the frontend shows outdated data.

The right fix: BeadBoard connects to Dolt directly via mysql2 — same MySQL wire protocol, no CGO needed, no sync step, and it unlocks Dolt's time-travel version history for future history/audit views.

---

Active Epic: beadboard-550

bd show beadboard-550

4 sequential child tasks:

Bead	Status	What
beadboard-550.1	in_progress (mysql2 installed, bead claimed)	Install mysql2, create src/lib/dolt-client.ts
beadboard-550.2	blocked on 550.1	readIssuesViaDolt() — JOIN issues+deps+labels
beadboard-550.3	blocked on 550.2	Wire Dolt as primary path in readIssuesFromDisk()
beadboard-550.4	blocked on 550.3	Verify SSE/watcher still fires, remove manual export from AGENTS.md

---

Session Start Protocol

cd /mnt/c/Users/Zenchant/codex/beadboard
bd show beadboard-550.1   # read the full spec
bd ready                  # confirm 550.1 is the only unblocked task
npm run typecheck         # baseline should pass (pre-existing status-badge error is expected)

---

Key Technical Context

Dolt schema (confirmed this session)

The Dolt server runs at 127.0.0.1:3307, database beadboard. Key tables:

• issues — main table, all fields including metadata (JSON column), status, issue_type, priority, close_reason, etc.
• dependencies — (issue_id, depends_on_id, type, created_at, created_by) — maps to BeadDependency[]
• labels — (issue_id, label) — maps to string[]

Connection config lives in .beads/metadata.json:

{
  "database": "dolt",
  "dolt_server_port": 3307,
  "dolt_database": "beadboard",
  "backend": "dolt"
}

Host defaults to 127.0.0.1 (not in metadata.json).

Current read path (what to replace)

src/app/page.tsx calls readIssuesForScope({ preferBd: true }):

1. preferBd: true → readIssuesViaBd() → runs bd list --all --json via CLI → works in WSL2, fails in Windows (CGO error)
2. Falls back to readIssuesFromDisk() → reads issues.jsonl → stale

Target: replace step 1 with readIssuesViaDolt() → mysql2 → always works regardless of platform.

BeadIssue shape (what mysql2 rows must normalize to)

See src/lib/types.ts for the full BeadIssue interface. Key fields:

• id, title, description, status, priority, issue_type
• labels: string[] — from labels table
• dependencies: BeadDependency[] — from dependencies table
• created_at, updated_at, closed_at — ISO strings (Dolt returns Date objects from mysql2)
• metadata: Record<string, unknown> — Dolt stores as JSON column, mysql2 auto-parses to object

normalizeBdIssue() already exists

src/lib/read-issues.ts has normalizeBdIssue() which handles the JSON→BeadIssue mapping from bd list --json output. The Dolt SQL rows will have the same field names, so reuse this function (or factor it out) for 550.2.

SSE / watcher (concern for 550.4)

src/lib/watcher.ts watches .beads/issues.jsonl + .beads/last_touched for changes and fires SSE events. Need to check whether bd still updates last_touched when writing to Dolt — if yes, watcher fires correctly and no change needed. If no, need a lightweight poll.

---

Skills to Use

This is an implementation task — use the standard hyperpowers workflow:

hyperpowers:executing-plans  — execute one task at a time, STOP after each
hyperpowers:test-driven-development — write test before implementation
hyperpowers:verification-before-completion — run typecheck+lint+test before closing any bead

Per hyperpowers:executing-plans: execute ONE bead, verify, close it, STOP for user review, then run /hyperpowers:execute-plan again to continue.

---

Files to Read Before Starting

src/lib/read-issues.ts          — current read path, normalizeBdIssue(), readIssuesViaBd()
src/lib/types.ts                — BeadIssue, BeadDependency interfaces
src/lib/bridge.ts               — runBdCommand (the CLI path being replaced)
src/app/page.tsx                — how preferBd: true is called
.beads/metadata.json            — Dolt connection config

---

Verification Gates (every bead before closing)

npm run typecheck && npm run lint && npm run test

Pre-existing known failure: status-badge.tsx TS2307: Cannot find module '@/lib/types' — ignore, it predates this work.

---

What Comes After beadboard-550

The UX phases (Phase 2–5) are still waiting:

• Phase 2 (beadboard-0fi) — operator identity (now unblocked since Phase 1 closed)
• Phase 3 (beadboard-8ij) — coordination layer
• Phase 4 (beadboard-x3l) — agent presence
• Phase 5 (beadboard-d2x) — blocked triage modal

But those have lower urgency than 550 (data infrastructure correctness > UI features).

---

Platform Note (WSL2 + Windows)

The Dolt server runs in WSL2 at 127.0.0.1:3307. If the frontend runs in Windows PowerShell, enable WSL2 mirrored networking first (one-time):

C:\Users\<you>\.wslconfig:
[wsl2]
networkingMode=mirrored

Then wsl --shutdown. Not required for single-platform setups. See AGENTS.md Data Backend section for full details.