feat(server): vp run migrate-dev-db seeds worktree dev dbs with real data

[t3dotgg]

Worktree dev servers start with an empty database, so testing anything real means clicking around to fabricate projects and threads. And nothing checks that a new migration applies cleanly on top of the real database's applied-migration state — fresh CI databases always pass.

vp run migrate-dev-db fixes both. It snapshots the real ~/.t3 database read-only (VACUUM INTO), prunes it to a handful of recent projects and their fully-stopped threads, and drops it into the worktree's isolated .t3. Then it runs this checkout's migrations against the result, which is real applied state, and fails loudly if a migration slot id was already taken under a different name (the silent-skip collision that has bitten parallel PRs before).

Details:

• Keeps threads only when their session is stopped and they are not settled, monitored, archived, or deleted. Working/monitoring liveness is in-memory only, so the persisted filter is exact.
• Event-sourcing stays consistent: kept threads keep their full orchestration_events streams, and sqlite_sequence plus projection_state cursors carry over, so nothing rewinds.
• Auth sessions, pairing links, command receipts, and provider runtime rows are dropped. Pair a fresh browser.
• Refuses to touch the shared ~/.t3 and refuses while a dev server holds the destination db.
• Flags: --projects (5), --threads-per-project (10), --base-dir, --source.
• Tolerates the monitor_json column that exists in the live db without a matching migration.

Tested end to end on the real database (2.5 GB in, ~145 MB out, 17 threads across 5 projects) plus three colocated tests covering the lifecycle filter, slot-collision detection, and the shared-home guard.

Built by Claude Fable 5 running in Claude Code.

🤖 Generated with Claude Code

---

Note

Medium Risk
Touches real user database copies and rewrites worktree dev SQLite, but refuses the shared home and active servers; main risk is mistaken --base-dir/--source paths or incomplete prune semantics for edge thread states.

Overview
Adds migrate-dev-db (pnpm migrate-dev-db / vp run migrate-dev-db) so a git worktree can get a pruned copy of the real ~/.t3 SQLite state instead of an empty dev database.

The command read-only snapshots the source (VACUUM INTO), runs this checkout’s migrations on that clone (so new migrations are exercised against real effect_sql_migrations history), verifies migration slot names and fails with MigrateDevDbSlotCollisionError when a slot was applied under a different name, then prunes to recent live projects and fully stopped threads (skips running, settled, monitored, deleted/archived), drops auth/pairing/command receipts/provider runtime, trims orchestration_events per kept stream while leaving projection cursors/sequences intact, and compacts into the worktree’s isolated .t3/userdata/state.sqlite with 0600 and WAL.

Guards block rebuilding shared ~/.t3, using a source that resolves to the destination or temp snapshot path, and overwriting the DB while server-runtime.json indicates a live server or SQLite reports write/WAL contention.

Vitest coverage exercises the prune filter, slot collision, server-running refusal, source/destination overlap, and shared-home refusal.

^{Reviewed by Cursor Bugbot for commit 451a1ad. Bugbot is set up for automated code reviews on this repo. Configure here.}

Note

Add migrate-dev-db script to seed worktree dev databases with real data

• Adds migrate-dev-db.ts — a new CLI script and programmatic API (runMigrateDevDb) that snapshots a source SQLite database, runs pending migrations, prunes it to recent stopped threads and their projects, strips auth/runtime state, and compacts the result into a destination dev database.
• Pruning keeps the N most recently updated projects (default 5) and, per project, the M most recent stopped threads (default 10), dropping all auth sessions, pairing links, and provider runtime state.
• Adds multiple guard checks before touching the destination: detects a live dev server via server-runtime.json, checks for write-locks and WAL holds on the destination file, refuses to target the shared ~/.t3 home, and rejects a source path that resolves to the destination.
• Introduces typed errors (MigrateDevDbSlotCollisionError, MigrateDevDbServerRunningError, etc.) and phase-wrapped errors for snapshot, prune, compact, migrate, and verify stages.
• Adds npm run migrate-dev-db in package.json as the CLI entrypoint.

^{Macroscope summarized 451a1ad.}

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 68658d86-d457-47ef-9246-80e03a8efa7d

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[github-actions]

Thread transfer impact

✅ Thread transfer remains within every enforced ceiling.

Provider	Metric	Main baseline	This PR	Impact	PR ceiling
Codex	Total thread wire	11.3 KiB	11.3 KiB	−11 B (−0.1%)	15.1 KiB	✅
Codex	Thread snapshot wire	5.5 KiB	5.5 KiB	+2 B (+0.0%)	7.3 KiB	✅
Codex	Live turn WebSocket wire	5.9 KiB	5.9 KiB	−13 B (−0.2%)	7.8 KiB	✅
Codex	Live turn WebSocket decoded	49.7 KiB	49.7 KiB	0 B (0.0%)	66.4 KiB	✅
Codex	Live turn messages	16	16	0 (0.0%)	21	✅
Claude	Total thread wire	11.3 KiB	11.4 KiB	+43 B (+0.4%)	15.1 KiB	✅
Claude	Thread snapshot wire	5.5 KiB	5.5 KiB	−3 B (−0.1%)	7.3 KiB	✅
Claude	Live turn WebSocket wire	5.8 KiB	5.9 KiB	+46 B (+0.8%)	7.8 KiB	✅
Claude	Live turn WebSocket decoded	50.6 KiB	50.6 KiB	0 B (0.0%)	66.4 KiB	✅
Claude	Live turn messages	16	16	0 (0.0%)	21	✅

Baseline: 886195e · PR result: 451a1ad · Source CI: success

Scenario and decoded snapshot size

10 historical turns, 5 command tools per turn, 878.9 KiB retained MCP result per historical turn, and a 1.05 MiB retained result in the measured turn.

• Codex decoded thread snapshot: 94.6 KiB
• Claude decoded thread snapshot: 95.4 KiB

Updated in place by a trusted workflow. PR artifacts are strictly validated and never executed.

[macroscopeapp]

Reviewed the new apps/server/scripts/migrate-dev-db.ts (and its test) against the Effect service/error conventions. Imports, Schema.TaggedErrorClass usage, the phase discriminator, and dependency acquisition (yield* SqlClient.SqlClient, layers provided per-database) all look right. Three error-modeling findings inline: the busy error stores a prose fragment as its only variable data and carries no cause, the wrap at the probe discards the underlying SqlError, and the verify boundary hand-rolls a _tag comparison instead of Effect.catchTags.

^{Posted via Macroscope — Effect Service Conventions}

[macroscopeapp]

One convention finding on the new script: a wrapped failure drops its underlying cause. Everything else (namespace imports, Schema.TaggedErrorClass errors with structural attributes and messages derived from them, SqlClient acquired from the environment, NodeRuntime.runMain only at the CLI boundary) matches the conventions.

^{Posted via Macroscope — Effect Service Conventions}

[cursor]

Cursor Bugbot has reviewed your changes using high effort and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 81f3692. Configure here.}

[macroscopeapp]

Approvability

Verdict: Needs human review

This PR adds 755 lines of new developer tooling for rebuilding isolated dev databases. While it doesn't affect production runtime and has comprehensive tests, the substantial amount of new logic (database operations, CLI commands, error handling) represents a new feature that benefits from human review.

^{You can customize Macroscope's approvability policy. Learn more.}

[macroscopeapp]

One finding: the destination-busy error uses its reason discriminator to select the user-facing message and carries a variant-only pid. Earlier feedback on cause, the structured reason, and Effect.catchTags is addressed.

^{Posted via Macroscope — Effect Service Conventions}