[juliusmarminge]

Problem

CLI commands that open the T3 home's database (t3 auth …, t3 pair, t3 thread …, t3 connect …, t3 project …, t3 environment …) ran their own build's pending migrations even while a running server owned that home. A newer CLI next to an older server moved the server's schema under it. A later server build that ships a different migration with the same id then refused to start ("would skip required schema migrations").

Reproduced on main 5b89a53:

1. Start a server on a scratch home.
2. Add a stand-in migration 073_CliOnlyProbe to the checkout.
3. Run t3 auth session issue, t3 pair --ttl 5m or t3 environment list with --base-dir set to that home.

Each command exited 0 and the ledger moved from 72 to 73 CliOnlyProbe. The server was still running and still held server-owner.sqlite.

Change

• CLI commands open the database through a new SqlitePersistence.layerCliConfig. The server and the offline t3 project path, which already hold ownership, keep layerConfig.
• Before migrating, the CLI layer checks whether this build has migrations the database has not recorded (hasPendingMigrations, the same rule the Migrator and the V2-preview reconciliation follow).
  • Nothing pending: it runs the usual read-only path. It takes no lock, and history checks still run.
  • Pending: it holds the T3 home's ownership lock only while migrating. If another process, usually a running server, holds that lock, the command fails with ServerOwnsDatabaseError. The error says to use the t3 that matches the running server or stop it, and the database is left unchanged.
• serverOwnership.ts gains holdServerOwnershipLock, the lock alone, without the runtime-state claim. acquireServerOwnership now shares the same lock code.
• isWildcardHost and formatHostForUrl move from startupAccess.ts to @t3tools/shared/hostClassification. Without the move, Sqlite.ts importing serverOwnership.ts creates an import cycle back through EnvironmentAuth.ts. Only imports change.

Scope and approval

Fixes #26696

Verification

• EnvironmentAuth.layer > does not migrate a T3 home behind the server that owns it, in apps/server/src/auth/EnvironmentAuth.test.ts. It holds the ownership lock, seeds a database one migration behind, and builds the CLI storage layer. It fails on main with expected 72 to be 71, and passes here.
• opens a current T3 home while the server that owns it runs, in the same file. With nothing pending, the CLI still opens the database beside an owner.
• apps/server: EnvironmentAuth, Sqlite, Migrations, pair and project tests pass, 51 of 51. tsc --noEmit is clean. vp run check:changed passes.
• Runtime transcript, from a scratch home and a server started from the checkout. A newer CLI now exits 1 with ServerOwnsDatabaseError and the ledger stays at 72. The unmodified server and a build with a different 073 both start afterwards; on main the latter refused. Control: with nothing pending, auth session issue and pair exit 0 beside the running server. transcript-26696.md, driver: repro.sh
• Server-only change with no visible surface, so there are no captures.
• Not checked:
  • Published binaries (a stable server with a nightly npx t3). The stand-in migration exercises the same path.
  • Servers older than 0.1.0, which have no ownership lock. The lock-only check does not detect them.

Claude Opus 5.5 (Claude Code), with step agents on Claude Opus 5.5 and GPT 6.1 Sol (Codex), through T3 Code.

🤖 Generated with Claude Code

[macroscopeapp]

Approvability

Verdict: Approved at 111f112

Macroscope's review found this PR approvable — CLI commands now require database ownership before applying pending migrations, preventing schema changes behind a running server while preserving current-schema access. Existing server migration behavior remains unchanged, and the reported runtime checks cover both refusal and normal-access paths.

^{You can add or adjust custom eligibility rules. Learn more.}

[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	5.0 KiB	5.0 KiB	0 B (0.0%)	6.8 KiB	✅
Codex	Thread snapshot wire	3.8 KiB	3.8 KiB	0 B (0.0%)	4.9 KiB	✅
Codex	Live turn WebSocket wire	1.2 KiB	1.2 KiB	0 B (0.0%)	2.0 KiB	✅
Codex	Live turn WebSocket decoded	21.5 KiB	21.5 KiB	0 B (0.0%)	24.4 KiB	✅
Codex	Live turn messages	1	1	0 (0.0%)	8	✅
Claude	Total thread wire	5.0 KiB	5.0 KiB	0 B (0.0%)	6.8 KiB	✅
Claude	Thread snapshot wire	3.8 KiB	3.8 KiB	0 B (0.0%)	4.9 KiB	✅
Claude	Live turn WebSocket wire	1.2 KiB	1.2 KiB	0 B (0.0%)	2.0 KiB	✅
Claude	Live turn WebSocket decoded	21.9 KiB	21.9 KiB	0 B (0.0%)	24.4 KiB	✅
Claude	Live turn messages	1	1	0 (0.0%)	8	✅

Baseline: f7b81e1 · PR result: 111f112 · 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: 108.5 KiB
• Claude decoded thread snapshot: 108.8 KiB

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

[coderabbitai]

No actionable comments were generated in the recent review.

Walkthrough

CLI persistence now checks migration history and uses a server ownership lock before applying pending migrations. Host-formatting and wildcard-detection helpers now come from the shared host-classification module.

Changes: CLI migration ownership guard

Layer / File(s)	Summary
Acquire and release the ownership lock apps/server/src/serverOwnership.ts	A shared helper acquires the ownership lock and maps SQLite busy errors to ServerAlreadyRunningError. holdServerOwnershipLock holds the lock for a scope. acquireServerOwnership uses the helper and retains owner-matched runtime-state cleanup.
Select migration behavior for persistence layers apps/server/src/persistence/Migrations.ts, apps/server/src/persistence/Sqlite.ts	hasPendingMigrations checks for a missing history table, a recorded ID below the latest migration, or an OrchestrationV2 row at ID 53 or 54. SQLite setup now accepts a migration effect. The CLI configuration acquires the ownership lock before applying pending migrations and reports ServerOwnsDatabaseError if another server holds it.
Wire CLI persistence and verify ownership behavior apps/server/src/auth/EnvironmentAuth.ts, apps/server/src/cli/environment.ts, apps/server/src/cli/project.ts, apps/server/src/cli/deferredImports.test.ts, apps/server/src/persistence/Sqlite.test.ts	Auth storage and CLI environment layers use layerCliConfig. A comment records that the project runtime layer is built after ownership is acquired. SQLite tests cover an owned database with pending migrations and one with current migrations. The deferred-import test no longer asserts that the ownership file is absent.

Shared host classification helpers

Layer / File(s)	Summary
Define and use shared host helpers packages/shared/src/hostClassification.ts, apps/server/src/startupAccess.ts, apps/server/src/serverRuntimeState.ts, apps/server/src/serverRuntimeStartup.ts, apps/server/src/cli/pair.ts, apps/server/src/environment/DirectEndpoints.ts	The shared module exports wildcard-host detection and URL host formatting. Server consumers import these helpers from the shared module, and startupAccess.ts removes its local implementations.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Change: Bug fix · Severity of issue fixed: Low

Possibly related issues

• [Bug]: t3 thread creates and migrates a new empty database when statev2.sqlite is missing #27120 — The issue describes CLI creation and migration of a missing database while a server is registered. This change adds ownership checks before applying pending migrations, but the issue notes that database initialization still occurs before the ownership check.

Suggested reviewers: maria-rcks, t3dotgg

Merge Risk: Minimal · up to 111f1

CLI commands now refuse to migrate a database owned by a running server when migrations are pending. No concrete merge-blocking risk was found in this change.

Pre-merge checks: 4

Check name	Status	Explanation
Title check		The title is concise, specific, and accurately describes the primary change: CLI commands no longer migrate a database owned by a running server.
Description check		The description includes the required Problem, Change, Scope and approval, and Verification sections. It explains the reproduction, implementation, linked issue, test results, runtime validation, and …
Linked Issues check		Issue #26696 requires CLI persistence commands to avoid applying pending migrations to a T3 home owned by a running server. SqlitePersistence.layerCliConfig uses hasPendingMigrations and acquires …
Out of Scope Changes check		The changes stay within issue #26696. serverOwnership.ts extracts shared lock acquisition so the CLI can hold the existing ownership lock without claiming runtime state. Migrations.ts adds the pen…

Full details: Description check

Explanation

The description includes the required Problem, Change, Scope and approval, and Verification sections. It explains the reproduction, implementation, linked issue, test results, runtime validation, and unverified cases.

Full details: Linked Issues check

Explanation

Issue #26696 requires CLI persistence commands to avoid applying pending migrations to a T3 home owned by a running server. SqlitePersistence.layerCliConfig uses hasPendingMigrations and acquires holdServerOwnershipLock before migration. A busy lock produces ServerOwnsDatabaseError; the error states that the database was not changed. The no-pending path validates history without taking the lock. CLI consumers use this layer, while the offline t3 project path retains layerConfig because it already owns the home. The added SQLite tests cover both the blocked pending-migration case and the current-database case. The shared host-helper move supports the import-cycle fix and does not alter the issue behavior.

Full details: Out of Scope Changes check

Explanation

The changes stay within issue #26696. serverOwnership.ts extracts shared lock acquisition so the CLI can hold the existing ownership lock without claiming runtime state. Migrations.ts adds the pending-migration check required by the new CLI path. Host-helper relocation removes an import cycle caused by the ownership dependency, and the related import-only updates preserve existing behavior. The added tests verify the requested migration and ownership behavior.

Finishing Touches

Generate docstrings

• Commit to this branch
• Create a new PR

Generate unit tests (beta)

• Commit to this branch
• Create a new PR

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Recent review info

Run configuration

• Source mode: Auto
• Repository: pingdotgg/t3code
• Branch: fix/issue-26696
• File: .coderabbit.config.ts
• Commit: 111f112
• Layers: Repository TS config
• Review profile: CHILL
• Plan: Team
• Run ID: fd579e37-49d0-41e2-886b-12b139fdf525

Commits

Reviewing files that changed from the base of the PR and between 866a3d9 and 111f112.

Files selected for processing: 11

• apps/server/src/auth/EnvironmentAuth.ts
• apps/server/src/cli/deferredImports.test.ts
• apps/server/src/cli/environment.ts
• apps/server/src/cli/pair.ts
• apps/server/src/cli/project.ts
• apps/server/src/environment/DirectEndpoints.ts
• apps/server/src/persistence/Migrations.ts
• apps/server/src/persistence/Sqlite.test.ts
• apps/server/src/persistence/Sqlite.ts
• apps/server/src/serverOwnership.ts
• apps/server/src/serverRuntimeStartup.ts

Files with no reviewable changes: 2

• apps/server/src/cli/deferredImports.test.ts
• apps/server/src/cli/pair.ts

Included review availability: This review used your included allowance. Your plan provides up to 10 included reviews per hour; 0 remain after this review.

[juliusmarminge]

The automated pipeline stopped on this pull request and will not merge it:

someone else pushed to fix/issue-26696 (head is now 866a3d9); the pipeline does not build on commits it did not review

It stays open for a person to finish or close.

Dismissing prior approval to re-evaluate 111f112

[juliusmarminge]

Evidence

Started a real server on a fresh disposable home on each commit. Matching-manifest session issuance and pairing succeeded on both. Appended harmless CLI-only migration 81, then ran session issuance, pairing, and environment listing against the running server. Finally stopped the server and attempted startup with a conflicting migration 81.

Before	After
f7b81e1d11	111f11209c
Session issuance records migration 81 and creates the probe table. Conflicting server startup fails.	All three commands return ServerOwnsDatabaseError; schema and ledger remain unchanged. Subsequent server startup succeeds.
Full transcript · Transcript playback · Schema/ledger snapshots	Full transcript · Transcript playback · Schema/ledger snapshots

Environment: Linux, real source CLI and HTTP server, fresh synthetic homes. Images and videos render captured transcripts; they are not screen recordings. Credential output was withheld.

Reproduction driver. Evidence uploaded using the ghdrop skill.

AI-assisted; verified with the tests and tools listed above.

Not shown:

• Pairing and environment listing were not independently tested as the first pending-migration command on base: session issuance had already applied migration 81. On head, migration 81 remained pending for all three commands.
• No live terminal screen recording was captured; supplied videos are readable presentations of captured real command output.