Two-way teleport with native CLI sessions

[baanish]

What this adds

T3 can now list, import, and export native Codex and Claude CLI sessions — "teleport." Start a session in either CLI and pick it up in T3, or hand a T3 thread back to the CLI, without losing the transcript and without two writers ever touching the same session file.

Three ideas hold the design together:

Native files stay native. Import copies a CLI session onto a T3 thread; export writes the thread back out in the CLI's own session format. T3 never becomes the owner of the native file.

One writer at a time. Every thread tracks a presence — t3 or native — that says which side currently owns the session. The UI swaps Import/Export based on presence, so both sides can never be writers at once.

Divergence is detected, never merged. After a successful import, a SHA-256 revision watch tracks the native file. If the CLI file changes or goes missing, further T3 turns are blocked and a conflict banner offers Fork native changes, which copies the diverged transcript into a new T3 thread. Both copies survive; nothing gets clobbered.

Scope note: TeleportProvider is codex | claudeAgent only. Grok and OpenCode remain regular T3 providers — this PR adds no native CLI teleport for them.

Fail-closed behavior

Every path that could produce a second writer refuses instead of guessing:

• File lock. Import and export refuse while the CLI holds the session file. Lock detection uses lsof; if lsof can't be spawned, Unix falls back to an exclusive-open probe and fails closed whenever the file exists. A missing file counts as unlocked, so a first export can still create it.
• Composer. Send, prompt, and stash are locked while presence is native or importing. The message-loading and attachment-upload disables stack on top of that lock — they don't replace it.
• Turn ingress. Every thread.turn.start, over WebSocket or HTTP (/api/orchestration/dispatch), requires a matching native revision. The one exception is bootstrap.createThread when the thread doesn't exist yet.
• Conflict banner. Once the watched revision diverges, send stays blocked until the user forks.

Recovery

In-place import is a single orchestration transition (thread.teleport.import). A failed or interrupted import reverts presence: importing and stays retryable — including first-time directory-bound threads, so a failed first import never looks like it succeeded. Startup recovery deletes leftover new-thread husks and clears or restores existing threads. Custom instance homes, worktree threads, and archived canonical threads are all supported.

Projection adds a teleport_json column (migration 044) and backfills only valid TeleportProvider values.

Known limitations

There is no cross-store transaction spanning orchestration, the provider directory, and the native file — this is documented, not hidden. Mobile already blocks send while a thread is teleported out; the teleport-in UI is web/desktop only for now.

Why

Work started in the Codex or Claude CLI should be able to continue in T3, and the reverse, without losing the transcript or writing from both sides at once. Presence enforces a single writer, the file lock and revision watch back it up, and forking recovers cleanly when the CLI file changes after import.

Relates to #207, #5146, #5741, and #6590. Supersedes #7136.

UI changes

Import lives on the new-thread / sessions view. Export lives in the chat header. The composer is disabled while a thread is in the native CLI.

Entry points

Tooltips

Composer disabled after teleport out

Native-revision conflict banner

Shown when the revision watch detects the CLI file diverged after import. Send is blocked until the user forks.

Recordings

Codex — full roundtrip: T3 export → native CLI (dark mode) → import back

Claude — full roundtrip: T3 export → native CLI (dark mode) → import back

Checklist

• This PR is small and focused
• I explained what changed and why
• I included before/after screenshots for any UI changes
• I included a video for animation/interaction changes

---

Note

High Risk
Touches turn admission, history replacement, attachment deletion, and native revision gating—mistakes could block sends, lose messages/attachments, or allow divergent native/T3 writers.

Overview
Adds teleport as a first-class thread concern: threads carry TeleportThreadState (native vs T3 vs importing), new orchestration commands/events (thread.teleport.set, thread.teleport.import, thread.teleport.clear, thread.history.replace), and decider rules that block turns on archived, native, or importing presence while allowing atomic import (unarchive + presence + history replace).

Server persistence and projections gain teleport_json (migration 044 with Codex/Claude backfill), hydrate teleport on shells/details (including archived threads for import/UI), and handle thread.history-replaced by wiping turns, plans, activities, and pending approvals while pruning attachment files via an owned-vs-kept plan so unrelated threads are not deleted.

Ingress and runtime: HTTP/WS dispatch runs TeleportService.requireNativeRevisionForTurn before thread.turn.start (skipped for bootstrap create on a missing thread); teleport RPCs get auth scopes; environment advertises capabilities.teleport. Provider changes treat turn.aborted like completion for session state and stop recovering stale sessions on interruptTurn.

Mobile mirrors web fail-closed behavior: the thread composer disables send and shows teleportSendDisabledReason when the thread is teleported out.

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

Note

Add two-way teleport with native CLI sessions (Codex/Claude)

• Introduces a TeleportService that lists, imports, and exports native CLI sessions (Codex JSONL, Claude JSONL) with format-specific adapters, file locking, bounded reads, atomic writes, and symlink-safe directory traversal.
• Adds orchestration commands thread.history.replace, thread.teleport.set, thread.teleport.import, and thread.teleport.clear, plus corresponding events thread.history-replaced and thread.teleported; the decider blocks turn starts on native/importing presence and can unarchive threads on import.
• Persists teleport state via a new teleport_json column on projection_threads (migration 44) and hydrates it through projection handlers, snapshot queries, and client-side thread reducers.
• Web UI adds a command-palette import flow, a TeleportOutButton in the chat header, native-conflict banners with fork actions, and composer locking (text, attachments, annotations, review comments) when a thread is teleported out or importing. Mobile disables sending for teleported-out threads.
• interruptTurn in makeProviderService now passes allowRecovery: false, preventing stale-session recovery before an interrupt.
• Behavioral Change: thread.turn.start may now fail early with a native-revision check via turnStartRequiresNativeRevisionCheck and TeleportService.requireNativeRevisionForTurn before dispatch in both HTTP and WS paths; archived threads are returned by by-id snapshot queries (list queries still exclude them).

^{Macroscope summarized a6b7b47.}

[macroscopeapp]

One finding: a composer insertion guard was widened to every sendDisabledReason, which blocks ordinary draft input (file-tree mentions, terminal links, type-to-focus) while an image upload is in flight or the thread is still loading. Details inline.

^{Posted via Macroscope — UI Consistency}

[macroscopeapp]

Reviewed the new apps/server/src/teleport/** service code against the Effect service conventions. Two findings on startup reconciliation error handling. The Effect.catchTag usages in formats/codex.ts and formats/claude.ts flagged in a previous run are still present and unchanged; not re-posting those.

^{Posted via Macroscope — Effect Service Conventions}

[macroscopeapp]

UI Consistency

One new finding on the teleport composer lock. The previously reported insertComposerTextAtEnd gate (apps/web/src/components/chat/ChatComposer.tsx L2803 — isSendDisabled also covers "Image still uploading" / "Sending feedback" / "Messages loading", so file-tree "Add to chat" and mention drops are rejected outside the teleport lock) is still present; not re-commented here.

^{Posted via Macroscope — UI Consistency}

[macroscopeapp]

One convention finding in the new teleport format registry. Note that the two previously flagged Effect.catchTag usages in apps/server/src/teleport/formats/codex.ts and apps/server/src/teleport/formats/claude.ts are still present; those comments are not repeated here.

^{Posted via Macroscope — Effect Service Conventions}

[macroscopeapp]

One finding: apps/server/src/teleport/sessionFile.ts computes the native-session digest with a suppressed node:crypto import instead of acquiring the Effect Crypto service the sibling module already uses. Everything else (new TeleportService tag/make/layer shape, namespace imports, catchTags usage, startup-recovery retry/interrupt handling, and the tagged-error definitions in packages/contracts/src/teleport.ts) matches the conventions.

^{Posted via Macroscope — Effect Service Conventions}

[t3dotgg]

Note

🤖 GPT-5.6 Sol responding on behalf of Theo

We're closing this PR as we clean up the T3 Code backlog. Thank you for taking the time to put this together.

Two-way teleport with native CLI sessions combines several separable runtime and lifecycle systems. It needs a smaller product decision and staged implementation before code review will be useful.

If you believe we closed this in error, please reopen the PR and leave a comment explaining what we missed.