Skip to content

feat: move a thread to another computer while its agent is working - #930

Merged
badcuban merged 61 commits into
mainfrom
feat/move-working-thread
Nov 16, 2026
Merged

badcuban merged 61 commits into
mainfrom
feat/move-working-thread

Conversation

@badcuban

Copy link
Copy Markdown
Collaborator

"Move to another computer" refused any thread whose agent was working, so you couldn't hand a thread off before shutting a machine down. It was also hard to find (sidebar right-click or ⌘K only).

Design: docs/design/fleet.md, Part 3b (reviewed twice before building).

What it does

  • The move dialog offers "Move when the agent finishes" or "Stop the agent and move now". Every move goes through a server-side queue that survives restarts.
  • While a move waits, the thread takes no new work. A notice above the message box shows what it's waiting for, with Cancel; it shows Try again when stuck.
  • If something blocks the move (a check-back, a goal, a plan, an archive), it ends with a "Didn't move: …" notice.
  • If the target computer is offline, the move waits for it and starts once it reconnects. Its agent is picked when the move starts.
  • Agents can move their own thread with a new thread_move tool.
  • Clicking the thread title in the chat header opens the thread's menu (the same items as the sidebar's right-click). Press-and-drag on the title or the project name moves the desktop window; a plain click still opens the menu. Drag is off under Wayland.
  • The web fallback menu gains keyboard navigation, including submenus.

Why it's safe (flagging loudly: this touches every provider's stop path)

  • Barrier: before a thread freezes, its sessions are stopped and a session fence (ThreadSessionAdmission) refuses every start or recovery of that thread inside ProviderService. Providers start turns of their own, so a command guard alone couldn't close the gap. The fence also covers v1 moves, which previously could be recovered by a transcript read.
  • Confirmed teardown per driver: v1's export now waits for it too.
    • Codex, ACP, Muse, Pi: the agent's process group plus descendants, from a ps snapshot taken at stop, only for fenced threads and off the event loop.
    • Claude: the CLI pid from the SDK's onProcessSpawned, an undocumented option; if it's missing, the result is "unconfirmed", never a false confirm.
    • OpenCode: asks its server, rebuilding the evidence after a restart.
    • If any driver can't prove it stopped, the move waits and says why.
  • Request-scoped: every queue, cancel and end names its request, so a stale cancel changes nothing. A Cancel that loses the race to the start cancels the transfer instead.
  • Old clients and servers: the new threadMoveQueue capability gates the new path; older servers get moves.start as before.

Cost for people who never move a thread: no process-table reads on ordinary stops, and the move queue reads only the threads it needs (measured 8.6 ms vs 566 ms for a full read model at 3,000 threads). One admission row read per session start or stop.

Context budget: thread_move is loaded on demand like the other thread tools. The prompt grows by its name (+38 bytes); its 1,083-byte definition loads only when an agent looks it up.

Migration: 111 adds pending_move_json only, with no row rewrite.

Checks

  • Outside review of the server diff (6 findings) and of the title/drag diff (3), all fixed. The final 3 small fixes weren't re-reviewed.
  • Live test on two local servers linked through a local relay, with a stand-in agent. Passed:
    • when-done (messages and uncommitted changes arrived, the agent remembered the conversation);
    • stop-now (a detached child was killed, and the move took under 3 s);
    • cancel;
    • an agent moving its own thread;
    • an offline target, which moved about 1 s after reconnect;
    • a blocked move.
  • fmt, lint, typecheck; server 3,861 tests, web unit 3,221, desktop 390, web browser suite 1,067 (move spec 11/11).

Not checked:

  • Windows at all. Its teardown proof is weaker: no descendant snapshot, only the agent's exit after taskkill /T.
  • A real window drag on Mac or Windows.
  • A real Wayland session.
  • Real provider runs (only the stand-in agent).

…ep 1)

Plan for queueing a move until a thread is free, stopping it first, and letting an agent move its own thread, with the session fence and confirmed teardown that make it safe. Reviewed twice by the outside reviewer.
…free

Move v2 step 1 (docs/design/fleet.md, Part 3b). A thread gains pendingMove,
with its commands (thread.move.queue, .unqueue, .quiesce, .queue-status,
.queue-end) and events (thread.move-queued, -quiescing, -queue-status-set,
-queue-ended). thread.move.start and the projected move carry the queued
request they started from, ThreadMovePreview gains waitsFor, and the moves
RPCs (preview, start, cancel, plus the new queue, unqueue and retry) move
into a group of their own.
threadMoveRefusals runs every check and sorts each into a wait (a running
turn, an approval, background work, another thread busy in the same
folder) or a block only the user clears (queued messages, a plan to act on,
plus everything v1 refuses). thread.move.queue is refused on a block and
allowed with any waits; while a move waits, the guard refuses the commands
that start work, and the automatic continue-at-reset arming is skipped.
thread.move.quiesce, .queue-status, .queue-end and .unqueue each name their
request, so an old one changes nothing. A start from the queue must name the
current request and find the session stopped; the pending move ends in the
same decision. The projection keeps pendingMove in pending_move_json
(migration 111).
… proven

ThreadSessionAdmission is asked before ProviderService starts or recovers
any session of a thread, whatever its key; the real layer reads the
projection and refuses while a queued move is quiescing or once the thread
moves. ProviderService.quiesceThread stops every runtime of a thread and asks
each driver to confirm its processes are gone (confirmThreadStopped), with
an agent-process ledger drivers share: it notes what an agent started when
its stop begins, waits for the agent to exit, and ends what outlived it.
ThreadMoveTargetPreview's refusalCode gains unreachable, so a client can
still queue a move to a computer that is offline right now.
MoveQueue (moves/MoveQueue.ts) queues a move after ThreadMoves checks the
link, cancels it by request (or cancels the transfer when the decider
already started it), and runs a reactor: it subscribes before its startup
scan, starts after the providers settled, and watches thread and link
changes. A block ends the wait with why; a wait is reported; a free thread
goes through the barrier (quiesce, a proven stop, a fresh look) to
ThreadMoves.startQueued. An unreachable target or an unproven stop holds the
move and tries again from 15 seconds up to 2 minutes, at once when a link
changes. v1's export waits for a proven stop too, the dialog's preview says
what the thread waits for, the moves RPCs get their own layer with queue,
unqueue and retry, and early agent starts skip a thread whose move waits.
A room tool on the main runtime, in the changes tier: it queues the
caller's thread to move to a linked computer once its turn ends, with the
target's suggested agent unless it names one. Refused for side runtimes,
room agents, threads a linked computer or an outside agent started, and
outside the caller's turn; a retried call finds the move it queued.
The Fleet topic now says how Move to another computer works, what goes with the thread, what the other computer's user sees, and which threads can't move yet.
The Fleet topic's move paragraph now covers Move when it's done, Stop and
move now, the notice while a move waits, and an agent moving its own thread
with thread_move.
MoveQueue runs against the real decider and projector: a move starts once
the turn completes, waits out background tasks, ends when the agent set a
check-back, holds while the target is offline and retries on its own and on
reconnect, holds while a stop can't be proven, survives a restart, goes
back to waiting when a provider turn slipped in, and a Cancel that lost the
race cancels the transfer. ProviderService refuses to start or recover any
session of a fenced thread and needs each driver's proof to quiesce one.
thread_move queues with the target's suggested agent and is refused for
side runtimes, room agents and threads another computer or an outside agent
started.
…ven gone

The runtime exposes the app server's pid and exit; the adapter tracks it in
an agent-process ledger, notes what it started before closing it, and
answers confirmThreadStopped from the ledger.
…own, are proven gone

The ACP runtime exposes the agent's pid and exit; the adapter tracks it,
notes what the agent started before closing its scope (Grok's background
shells live in process groups of their own and outlive the agent's group
kill), and answers confirmThreadStopped from its ledger.
…d, are proven gone

PiRpc and MuseHost expose their process ids; each adapter tracks every
process or host generation under the session key, notes what it started
before it closes it (replacements included), and answers
confirmThreadStopped from its ledger. Muse still sends task/stopAll first.
…arted, are proven gone

The SDK reports the process it spawned (onProcessSpawned); the adapter
tracks it, notes what it started before closing the query, watches the pid
for its exit only after the stop (bounded), and answers
confirmThreadStopped from its ledger. A session whose process the SDK never
reported can't be proven stopped, and says so.
…y the server that ran it

One OpenCode server runs every thread's agent, so its process can't prove
one thread stopped. A stop that interrupted work records the thread's
OpenCode sessions and shells; confirmThreadStopped asks the server until
none of them is active or running (a little while, for interrupts still
settling), and says when the server doesn't answer.
…move, and off the event loop

Every provider stop ran a synchronous ps. Now ProviderService asks the
driver to note what an agent started (noteBeforeStop) only when the
session fence holds the thread, which the projection already shows before
the reactor stops its sessions; the drivers no longer read the table on
their own stops. The read is an async execFile with a 2 second limit, and
a table that couldn't be read makes the stop unconfirmed rather than
confirmed blind. The Windows tree kill is async with the same limit.

The move queue no longer sends a status that changes nothing: the engine
refuses a command that records no events.
…noted first

quiesceThread ends early starts that are still starting; when one's agent
already runs, each driver notes what it started before the stop, as a
listed session's stop does.
One look of the move queue loaded the whole command read model when the
thread looked free: 566 ms with 3,000 threads of 30 messages, 859 ms with
10,000. It now reads the thread, its attached children and the threads in
its checkout (threadMoveView.ts): 8.6 ms and 9.3 ms. ThreadMoves' preview,
start and queue checks use the same read, and the startup scan lists only
threads with a queued move.
Capabilities gain threadMoveQueue: a client that sees it may use
moves.queue, moves.unqueue and moves.retry and send every move through the
queue, since a free thread's move starts at once. Without it, moves.start.
agent is optional in moves.queue, thread.move.queue and pendingMove. Left
out, the move takes the agent the target suggests for the thread when it
starts (as the dialog picks it), so a move queued while the target is
offline still gets one; a target that suggests none ends the move as
blocked: "<target> has no agent ready." A named agent is kept. thread_move
leaves the agent out unless the caller names one.
… a move freezes

quiesceThread counted only listed sessions and early starts, so a recovery
that had passed the session fence and was still opening its runtime went
unseen: the move confirmed, froze, and then the runtime came up. It now
waits for every start or recovery of the thread that holds its key's gate,
then stops what they opened. Recovery reads the fence holding the gate, as
starts already did, so one that waited behind the move is refused.
…pped

What a stop interrupted lived only in memory, so after a restart an empty
record confirmed a thread whose work the shared server may still run (an
external server outlives us). confirmThreadStopped now gets what the
session directory keeps of each of the thread's sessions; for one this
process never ran, OpenCode asks the server whether its root session or any
child is active and whether a shell runs in its folder, and confirms only
when nothing does.
…thing started

When the snapshot at a move's stop failed, the agent's exit watcher read
the unknown list as empty and forgot the agent once its group was gone, so
confirm passed while a shell in a group of its own lived on. The entry now
stays, and confirm says the process list couldn't be read.
… new work

The queue ignored a refused thread.move.quiesce and went on to end the
thread's sessions, so cancelling and sending a new message could have
that message's session stopped by a look already under way. It now ends
sessions only when the projection shows this request quiescing.
…ransfer

If the start committed between the Cancel's read and its unqueue, the
frozen thread refused the unqueue and the error ended the Cancel before it
could cancel the transfer. A refused unqueue now reads again and cancels
the move that started from the same request; it fails only when the queued
move is still there.
…r's terminal

A suggested command runs in the user's own terminal tab, and the server has
no way to stop one there, so Stop and move now sat on a command-run wait
with nothing to say why. It is now refused with words: stop the command
there, or move the thread when it's done. Move when it's done still waits
for it.
…pped

A when-done move's quiesce and the reactor's thread.session-stop-requested
both stop the same session. The one that lost the race got the driver's
"Unknown adapter thread" (ACP) or "thread is closed" (Claude) error, and
the reactor's handler stopped there, skipping room agents, early starts,
the side answer and the outside-work bookkeeping. ProviderService's stop now
reads either error as nothing left to stop, for every caller.
The only frame that changed is the session's allowed tools, which now include thread_move; Claude's replies don't depend on it, so the recordings gain the name instead of a re-record against the real service.
Computers name themselves, so a linked computer could take another's id or name as its label and catch a thread_move (or thread_start) meant for it. An exact id now always wins, and a name counts only when one linked computer has it; two with one name are refused with their ids. Found by Vercel Security Review.
…se matches

Computers choose their own ids and names, so preferring an exact id let one take another's name as its id. A computer is now picked only when it is the one whose id or name matches; any collision is refused and the agent asks the user. Found by Vercel Security Review.
…rgument

The generated wrapper embedded a temp path inside the helper's code, which CodeQL flags as code built from an unsanitized value. The wrapper now passes the path beside itself as an argument, and the helper's code is fixed text.
The evals added in #958 list a canned handler for every room tool; thread_move was missing, so the server typecheck failed once main and this branch met.
@badcuban
badcuban added this pull request to the merge queue Nov 16, 2026
Merged via the queue into main with commit 0fba726 Nov 16, 2026
24 checks passed
@badcuban
badcuban deleted the feat/move-working-thread branch November 16, 2026 15:56
badcuban added a commit that referenced this pull request Nov 16, 2026
Step 2 of keeping threads going on another computer (docs/design/fleet.md, Part 3c): the Move threads dialog in Fleet and the command palette, the quit dialog's move-then-quit with a main-process wait, receive-before-allow on the target with its own staging budget, busy targets as a wait, durable batches and move outcomes, and one Allow all card for a computer's moves. Rebuilt on main after #930 merged.

This branch was previously deployed

1 inactive deployment
Preview — 88bdc311 Deployed Nov 16, 2026 by vercel[bot]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants