Running t3 pair against a server on another orchestration protocol prints a token that the server cannot use. For example, stable 0.0.45 writes state.sqlite while a V2 server reads statev2.sqlite; the reverse direction also creates an unnecessary V2 database before returning an unusable token.
Check the discovered server's orchestration protocol before Tailscale setup or database/auth initialization. Refuse mismatches with both protocol versions and the exact server-version pairing command. Missing protocol metadata uses the existing V1 compatibility default; matching protocols retain the existing pairing path.
Fixes https://github.com/pingdotgg/t3code/issues/15492
Triaged bug via the automated issue flow: #15492. Limited to the pairing CLI compatibility check and its regression test.
server-runtime.json; actual also contained environment-id, secrets, and statev2.sqlite.vp test run apps/server/src/cli/pair.test.ts: 14/14 passed on c502579298.| Real server/CLI check | Result |
|---|---|
| Published stable CLI → current V2 server | Before: token printed, fresh exchange HTTP 401 |
| Current CLI → published stable V1 server | Before: token printed, fresh exchange HTTP 401; after: exit 1, actionable mismatch, no token, SQLite/sidecar hashes unchanged |
| Fixed current CLI → current V2 server | Token issued, fresh exchange HTTP 200 |
Independent sanitized evidence audit
Server/CLI-only change; render matrix empty. Runtime verified on Linux x64, Node 26.12.1, isolated real V1/V2 servers. macOS desktop and Tailscale wrapping were not run. The already-published immutable 0.0.45 package remains affected; the source fix protects future CLI releases.
Models: Claude Opus 5.5 (Claude Agent harness), GPT-6.1-Sol (Codex harness).
Review + omitted-protocol evidence at c502579298, against merge-base 044f07257c. No source changes or fixes applied; these are delegated review results, not posted forge reviews.
gpt-6.1-sol: MERGE. Full diff and discovery/config/auth paths traced: guard precedes database/migrations, secrets, environment-id and Tailscale writes; failed/unreachable discovery cannot reach token minting. No pairing acceptance, scope or grant changes. Static review; diff check passed.claude-opus-5-5: MERGE. Full diff and descriptor history traced: omitted metadata uses the established V1 default; production V2 producers always include the field. Focused pairing suite passed 14/14. Nonblocking caveats: retain original CLI flags with the suggested command; unpublished server versions may not have a matching npm release. No auth acceptance/grant change beyond refusing unusable token issuance, so neither reviewer triggered NEEDS_JULIUS.| Additional evidence row | Before (merge-base) | After (head) |
|---|---|---|
Controlled HTTP descriptor server omits orchestrationProtocolVersion; real source CLI, isolated fresh and existing homes | Exit 0, token printed. Fresh: creates environment-id, secrets/server-signing-key.bin, statev2.sqlite, one pairing row. Existing: database hash changes, pairing rows 1→2. | Exit 1, no token; reports server protocol 1 / CLI protocol 2 and npx t3@0.0.45 pair. Fresh: no files created or changed. Existing: all file hashes unchanged, pairing rows remain 1. |
Sanitized transcripts, file inventories, and exact driver. Driver SHA-256: 4c008957f981f4a2cb7812cd5067f23fa2ccf8b34861975e6e26a5ceb96e1226.
This row uses a descriptor fixture advertising 0.0.45, not a full production server; no exchange result is claimed. All runtime homes were under /tmp/ev-23789; no real T3 database was accessed. No Tailscale command was run. Server port-owner PIDs were recorded and their cwd checked before stopping. An initial Vite+ shim bootstrap was discarded and the row rerun using the installed Node binary directly. Missing metadata on a hypothetical modified V2 server would also be treated as V1; shipped V2 descriptor constructors emit the field. No correction to the existing PR-body evidence claims was found.
Added 2 commits
Verdict: Needs Human Approval
Macroscope's review found this PR requires human approval — This narrowly scoped fix rejects protocol-incompatible servers before pairing setup can initialize authentication storage or mint an unusable credential, while preserving matching and legacy paths. Because it changes authentication-related runtime behavior, human review is warranted.
You can add or adjust custom eligibility rules. Learn more.
✅ Thread transfer remains within every enforced ceiling.
ℹ️ The exact PR base did not have a successful artifact. Baseline uses the latest successful
mainmeasurement shown below.
| Provider | Metric | Main baseline | This PR | Impact | PR ceiling | |
|---|---|---|---|---|---|---|
| Codex | Total thread wire | 5.0 KiB | 5.0 KiB | −7 B (−0.1%) | 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 | −7 B (−0.6%) | 2.0 KiB | ✅ |
| Codex | Live turn WebSocket decoded | 20.9 KiB | 20.9 KiB | 0 B (0.0%) | 29.3 KiB | ✅ |
| Codex | Live turn messages | 2 | 2 | 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.2 KiB | 21.2 KiB | 0 B (0.0%) | 29.3 KiB | ✅ |
| Claude | Live turn messages | 2 | 2 | 0 (0.0%) | 8 | ✅ |
Baseline: 4eae8ae · PR result: c502579 · Source CI: success
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.
Updated in place by a trusted workflow. PR artifacts are strictly validated and never executed.
No actionable comments were generated in the recent review. 🎉
24f5929e-3370-41c5-b036-9e232d528827Reviewing files that changed from the base of the PR and between 044f07257c9684ae4543bd1e1ebf9c394e9e3830 and c502579298f719c4346f48ff75f3b7d896ba17c4.
apps/server/src/cli/pair.test.tsapps/server/src/cli/pair.tsIncluded review availability: This review used your included allowance. Your plan provides up to 10 included reviews per hour; 8 remain after this review.
The pairing CLI now checks the discovered server’s orchestration protocol version before continuing with pairing setup. It returns an incompatibility error for a mismatch. A regression test verifies that this failure does not create additional userdata files.
Changes: Pairing protocol compatibility
| Layer / File(s) | Summary |
|---|---|
Protocol compatibility guard apps/server/src/cli/pair.ts | pairCommand compares the discovered server’s protocol version with the CLI’s version. If they differ, it returns IncompatibleServerProtocolError with the server version and protocol version. A missing server protocol version defaults to 1. |
Mismatch regression test apps/server/src/cli/pair.test.ts | The test descriptor helper accepts a supplied descriptor. The regression test checks that a protocol mismatch fails and leaves only the existing server-runtime.json file in the userdata directory. |
Priority: ➖ Normal
Estimated code review effort: 2 (Simple) | ~10 minutes
Change: Bug fix · Severity of issue fixed: Medium
Possibly related issues
Suggested reviewers: t3dotgg
c5025The compatibility check rejects mismatched servers before pairing changes local state. No merge-blocking issue was found.
| Check name | Status | Explanation |
|---|---|---|
| Title check | Passed | The title clearly and concisely states the main change: rejecting pairing when the server protocol is incompatible. |
| Linked Issues check | Passed | Issue #15492 requires the CLI to reject a protocol mismatch before database access and provide an actionable matching-version command. The reviewed source adds IncompatibleServerProtocolError, which… |
| Out of Scope Changes check | Passed | The changes are limited to the pairing protocol check and its regression test, as requested by issue #15492. The descriptor helper updates and protocol fields support that test. No unrelated changes a… |
| Description check | Passed | The description follows the required template. It explains the problem, change, scope and approval, focused verification results, limitations, and agent attribution. It also documents the linked issue… |
Explanation
Issue #15492 requires the CLI to reject a protocol mismatch before database access and provide an actionable matching-version command. The reviewed source adds IncompatibleServerProtocolError, which reports both protocol versions and npx t3@<serverVersion> pair. The supplied change summary places the check before server configuration and token creation. The regression test uses a protocol 1 server descriptor and checks failure, the versioned command hint, and that no userdata files beyond server-runtime.json are created. Missing protocol metadata retains the V1 default, and matching protocols retain the existing path.
Explanation
The changes are limited to the pairing protocol check and its regression test, as requested by issue #15492. The descriptor helper updates and protocol fields support that test. No unrelated changes are evident in the reviewed summary or test diff.
Explanation
The description follows the required template. It explains the problem, change, scope and approval, focused verification results, limitations, and agent attribution. It also documents the linked issue and relevant test evidence.
Comment @coderabbitai help to get the list of available commands.