feat(orchestrator): move a running thread between devices

[Bil0000]

Closes #5363.

Stacked on #2829 (t3code/codex-turn-mapping). main and the orchestrator branch share no common ancestor; every primitive this builds on exists only there.

What this does

Run on picks the machine a thread starts on and locks once it has a message — a thread is born on one device and dies there. This makes that reversible: pick another connected environment from the same control, and the conversation, the provider continuation, and the git working state move there. Pull it back later from the same control, which shows where the thread originally ran.

Verified live: real threads moved repeatedly between a MacBook (desktop app) and a Linux server and continued on each side, through the actual relay-free client-brokered transfer — including round trips, pull-backs, and the failure modes listed under Verification.

The safety model

• A branch tip only ever moves to a descendant of itself, on either machine. Diverged or unrelated history parks the sender's commits at refs/handoff/<environment>/<handoff>/<branch> and stops with both machines untouched.
• Exactly one side is live. thread.handoff.depart locks the giving side before any bundle is applied anywhere; mutations on an away thread are refused in the orchestrator (a small allowlist of local-copy lifecycle verbs excepted). An interrupted transfer releases the lock; a stranded one has a Continue here escape hatch, offered only while the transfer never landed. A completed handoff can no longer be aborted or repointed.
• Old tip tagged and dirty worktrees stashed (root and destination worktree independently) before any pointer moves; patches dry-run first; a failed apply rolls the repository back and cleans up everything it extracted. Rollback metadata (pre-tag, stashes, apply directory) is persisted before the patch lands, so startup recovery can restore the tree from any crash point — including a first arrival that died before its thread projection existed.
• A busy thread is interrupted first and the transfer starts when it goes idle; the depart command re-checks for active runs under the dispatch lock, so a racing message cannot slip a live run past the snapshot.
• Payload ceilings (200 MB warn / 1 GB refuse) enforced during prepare and again per chunk on the receiving side. First hops cut the bundle against the repo's remote-tracking refs; a fully pushed branch ships no bundle at all.
• Untracked files that would overwrite tracked files on the receiver refuse the hop (checked on real extracted paths in a staging directory, immune to path tricks). ThreadHandoffId is schema-restricted to a URL- and git-ref-safe alphabet.

What travels

Branch + unpushed commits (git bundle, checkpoint refs ride along so revert keeps working), tracked changes (binary patch), untracked files (null-delimited tar), the conversation (turn items + covered run ordinals), attachments (original names, which the items reference), terminal scrollback (restored on first open like after a restart), workspace shape (worktree threads land in worktrees — reuse the branch's worktree or provision one, detached when git forbids attaching). A target that lacks the repository entirely clones it from the bundle — no remote, credentials, or network needed on the receiving machine.

How it moves

Manifest inline, large parts content-addressed and fetched by digest in resumable 4 MB chunks; the receiver rejects a chunk that does not continue the staged bytes and treats an exact re-send of already-staged bytes as a no-op, so interrupted uploads resume. The client brokers the copy — the only component authenticated to both environments — and only offers targets that are connected and advertise the capability. Arrivals go through the event sink, so the thread appears in every connected client's sidebar the moment it lands.

Lineage, not direction

Each hop records the previous hop in a lineage table; a return trip is an ordinary hop toward an environment already in the chain, and the receiver revives the prior thread pair even when the client no longer remembers it — one conversation, one sidebar row, wherever it currently runs. A caller-named return target is validated against that lineage before anything is applied. Provenance survives round trips: every arrival keeps a link recording where the thread came from. Lifecycle actions (delete, archive, rename) apply to the pair once.

Version skew

threadHandoff capability follows the threadSettlement contract: absent means the environment is not offered as a destination.

Verification

• contracts 266 · client-runtime 621 · web 118 · server suites green (orchestration-v2, persistence, environment, ws, startup, terminal) · monorepo typecheck, lint, fmt clean.
• New coverage: tip-classification table, ref-name sanitization, full dispatch-path depart/refuse/complete/abort with reason surfacing, payload ceilings, chunk windows, sidebar pair-visibility rules, migration idempotency and mid-apply recovery.
• Live smoke: repeated MacBook ↔ Linux server transfers of real threads, including the failure modes found and fixed along the way (full-history bundle timeout, empty bundle on a fully pushed branch, missing dispatch routing, JSON codec gap on the handoff timestamp, arrivals invisible to connected clients, post-push navigation, pair dedup after round trips).
• Code review: all Macroscope findings across the review rounds addressed and resolved, including the crash-recovery, payload-abuse, and single-live-side race classes.

Related

• feat(orchestrator): introduce new orchestrator #2829 — orchestration V2 (base of this stack; this PR targets its branch)
• feat(orchestration-v2): import an existing Claude Code or Codex session by id, with two-way transcript sync #5499 — session import on a sibling branch; claims a migration id in the same range as 047–049 here — whichever merges second renumbers
• [WIP] Manage worktree lifecycle on orchestrator V2 #5589 — worktree lifecycle management on orchestrator V2; touches the same worktree-provisioning surface the receive path uses
• [Feature]: Transfer a provider-native session between T3 Connect environments #5363 — the feature request this implements: one-click transfer of a provider-native session between T3 Connect environments
• [Feature]: Rehome an existing thread to another project #5215 — rehoming a thread to another project: adjacent ask, not covered here (this PR moves threads between environments, within the same logical project)
• Add durable GitHub waitpoints to orchestration V2 #5003 / feat(orchestration-v2): subagent and workflow observability — model, providers, UI, visibility #4664 — other orchestration-V2 stacked work, listed for merge-ordering awareness

Migrations

047 (orchestration_v2_thread_handoffs lineage table), 048 (apply_cwd column for projection-independent crash recovery) and 049 (root_stash_ref/root_cwd so root and worktree stashes recover independently). 047 was renumbered from 046 after the base branch inserted a migration.

Note

Add thread handoff to move a running thread between devices

• Introduces an end-to-end thread handoff system allowing a running thread to be transferred between execution environments (devices), preserving git state, conversation history, terminals, and attachments.
• Adds OrchestrationV2HandoffBundleV1 manifest contract, typed part kinds (git-bundle, tracked-patch, untracked-tar, etc.), and versioned DB migrations (047–050) for the orchestration_v2_thread_handoffs table.
• Exposes readHandoffPart/writeHandoffPart HTTP endpoints on the environment API with offset-validated, idempotent chunked transfer and a 4 MB chunk size.
• Adds prepareThreadHandoff and receiveThreadHandoff WebSocket RPCs (requiring AuthOrchestrationOperateScope) handled in the server WS layer and wired into production startup with a handoff recovery phase.
• The web UI gains a ThreadHandoffDialog for progress-tracked moves, a banner for threads running elsewhere (with pull-back and continue-here actions), and sidebar deduplication hiding the 'away' copy when the 'here' peer is visible.
• The mobile UI gains a ThreadHandoffBanner to surface away threads and resume them locally.
• Archiving, unarchiving, and deleting a thread now best-effort mirrors the operation to the handoff peer thread.
• Risk: handoff recovery runs at server startup; interrupted handoffs from a prior session are automatically resumed, which may replay partial git or file operations.

^{Macroscope summarized 0250f02.}

[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: f38d45d4-abf4-498e-bf1f-f44233f84eeb

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.}

[macroscopeapp]

One finding on the new handoff error contract; the migration, its tests, and the bundle schemas otherwise follow the Effect conventions (subpath namespace imports, no service-instance injection, no ManagedRuntime/runPromise, no Layer.succeed shortcuts).

^{Posted via Macroscope — Effect Service Conventions}

[macroscopeapp]

Effect service conventions review of the two new service modules. Three findings, all in apps/server/src/orchestration-v2/. Earlier feedback on OrchestrationV2HandoffError.message still stands and is not repeated here.

^{Posted via Macroscope — Effect Service Conventions}

[macroscopeapp]

Two service-shape conventions are still outstanding after the latest fixes. Previously reported findings that remain unchanged (the handoffError construction helper in ThreadHandoffService.ts and the required free-form message field on OrchestrationV2HandoffError in packages/contracts/src/orchestrationV2.ts) are not re-commented here.

^{Posted via Macroscope — Effect Service Conventions}

[macroscopeapp]

Effect service conventions review of the thread-handoff services. One new finding on the git service's error modeling; four findings from earlier runs are still present in this head commit and are listed in the check summary rather than re-commented.

^{Posted via Macroscope — Effect Service Conventions}

[macroscopeapp]

Reviewed the new Effect service modules (ThreadHandoffGit, ThreadHandoffService) and their call sites against the service conventions. The service definitions, make/layer exports, dependency acquisition and error modelling all look consistent with the conventions; the remaining findings are service-boundary imports in the two new test files that alias layer and erase the module namespace.

^{Posted via Macroscope — Effect Service Conventions}