fix(server): prevent worktree pairing from falling back to the live install

[Gigioxx]

Problem

Running t3 pair from a linked worktree with no live local server silently selected the shared install and opened its database with the checkout's migrations. That can migrate the live desktop database from a dev checkout.

Change

Discovery now checks only the worktree's .t3 when run inside a linked worktree, matching dev-runner precedence (worktreeHome ?? shared home). A missing or stale local server returns NoRunningServerError. An explicit --base-dir and discovery outside linked worktrees still work.

This does not repair already affected databases. Minting still uses EnvironmentAuth.runtimeLayer, so preventing checkout migrations when a database is explicitly targeted (including auth pairing create) remains a follow-up.

Scope and approval

Fixes #10516. Maintainer triage confirmed the bug and identified the inclusive discovery fallback as the cause: #10516 (comment)

Verification

• Reproduced before the fix through the actual CLI handler with disposable homes and a local HTTP descriptor server: both missing and stale worktree state created state.sqlite in the shared home.
• New parameterized test in apps/server/src/cli/pair.test.ts covers missing, stale, local, explicit --base-dir, and ordinary-checkout discovery, and asserts no shared database is created for the worktree cases. The missing and stale cases fail without the fix.
• After rebasing on current main (only conflict: Config.string renamed to Config.String): vp test run src/cli/pair.test.ts in apps/server, 15 of 15 passed. vp lint and vp fmt --check on both changed files: clean. tsc --noEmit for apps/server: no errors.
• Not checked: no live install was touched; already affected databases are not covered.

Original change by GPT-6 via Codex. Rebase and description update by Claude Opus 5.5 via Claude Code.

Note

Fix worktree pairing fallback to live T3CODE_HOME install

Adds a parameterized discovery test in pair.test.ts covering missing, stale, local, explicit-base, and regular-checkout worktree scenarios. The test creates temporary worktree and shared-home layouts, mocks the working directory, and verifies which state database and pairing output are used. Confirms that linked worktrees no longer fall back to the shared T3CODE_HOME installation, while local worktree state, explicit base directories, and regular checkouts still produce pairing URLs.

^{Macroscope summarized 9c32b39.}

Summary by CodeRabbit

• Bug Fixes
  • Improved t3 pair discovery in linked Git worktrees.
  • Pairing now consistently uses the worktree’s local .t3 directory and no longer falls back to the shared T3 home directory when operating there.

[coderabbitai]

Navigate logical layers of code changes, visualize relationships, and explore their blast radius.

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository: pingdotgg/t3code/.coderabbit.yaml

Review profile: CHILL

Plan: Advanced

Run ID: 73fc14cb-3aac-4873-bffd-ea0cba64463a

📥 Commits

Reviewing files that changed from the base of the PR and between 9c32b39 and 3711cf5.

📒 Files selected for processing (1)

• 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; 3 remain after this review.

---

📝 Walkthrough

Walkthrough

t3 pair now checks only a linked worktree’s .t3 directory when discovering runtime state. Integration tests cover missing, stale, local, explicit-base-directory, and checkout scenarios.

Changes

Pairing discovery

Layer / File(s)	Summary
Exclusive worktree discovery and integration coverage apps/server/src/cli/pair.ts, apps/server/src/cli/pair.test.ts	When no explicit base directory is supplied, linked worktrees use only their own .t3 directory. Other checkouts retain shared-home discovery. Parameterized tests cover discovery scenarios and fallback diagnostics.

Priority: ⬇️ Low

Estimated code review effort: 2 (Simple) | ~15 minutes

Change: Bug fix

Suggested reviewers: juliusmarminge

Merge Risk: ⚪ Minimal · up to 3711c

Linked-worktree pairing now reports missing or stale local server state instead of using a shared server; explicit-base and ordinary-checkout discovery remain supported. No actionable merge risk is apparent.

Architecture Summary

Architecture risk: 🔵 Low · up to 3711c

The change affects 1 system.

Changed systems: apps/server

Architecture concerns
No architecture-level concerns identified.

Review details

Systems and components

• observed — apps/server (service) was modified; 2 changed files map to changed impact.

Before / after behavior

• observed — Modified behavior in apps/server/src/cli/pair.test.ts: Added imports for ConfigProvider and vi, used by the new CLI integration test.
• observed — Modified behavior in apps/server/src/cli/pair.test.ts: Added a parameterized t3 pair integration test that isolates runtime-state discovery across missing, stale, local, explicit-base-directory, and Git checkout scenarios. It creates temporary worktree and shared-home layouts, mocks process.cwd, persists valid or stale server state, configures T3CODE_HOME, executes the CLI, and verifies whether pairing succeeds or reports the expected state-file fallback paths.
• observed — Modified behavior in apps/server/src/cli/pair.ts: The comment now states that a linked worktree’s .t3 is checked exclusively rather than first, matching the changed discovery behavior.
• observed — Modified behavior in apps/server/src/cli/pair.ts: When no explicit base directory is supplied, discovery now uses the worktree home alone if one exists. Previously it also added the configured or default shared home, allowing fallback to that server; outside worktrees, the shared-home lookup is unchanged.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff. Analyzed 0 functions across 2…
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Title check	✅ Passed	The title clearly and concisely describes the primary fix: preventing linked worktrees from pairing through the live installation.
Description check	✅ Passed	The description includes the required Problem, Change, Scope and approval, and Verification sections. It explains the bug, the fix, the linked issue and maintainer approval, focused test coverage, obs…

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create a new PR

---

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

[macroscopeapp]

Approvability

Verdict: Not approved

Macroscope's review found this PR not approvable — This focused fix correctly prevents linked worktrees from falling back to the shared installation and adds regression coverage for the discovery cases. Because the selected installation is also where pairing credentials are minted and persisted, the runtime change has authentication-sensitive impact that warrants human review.

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