Part of the runner protocol. docs/protocol.md has the rules for all of it and which file each section is in.
Added 8 Nov 2026 (docs/archive/move-plan.md) as the experiment moveToRunner, on
for everyone from 12 Nov (a runner from between those dates takes part only
with it on). The thread itself moves: the same id, its whole
event log, pictures and Highlights, its Claude session, and the git work in
its own worktree, from the runner that has it (S) to another (T). Exactly
one runner has it at a time. Only the main Mac's runner (the owner key, O)
starts a move, and O can be S or T. Runners still never talk to each other:
everything goes through the backend's threadMoves row (backend API 64).
The row. { moveId, threadId, from, to, state, cwd?, accountId?, info?, plan?, key?, chunks?, sha256?, bytes?, note?, createdAt, updatedAt, frozenAt? }. cwd and accountId are what Mike picked (absent: T
chooses). info is S's description of the thread (below), plan T's
answer, key T's sealing key, chunks the sealed bundle's storage ids in
order. Each runner watches the moves it's in
(moves:moves: rows with from or to its own, still going or
ended in the last day) and acts on the state:
| state | who acts | then |
|---|---|---|
asking |
S describes the thread: moves:moveInfo { moveId, info }; then T checks it can take it: moves:moveReady { moveId, plan, sealKey } |
ready |
ready |
S waits for the thread's turn and sub-agents to end, then freezes it: moves:moveFrozen |
packing |
packing |
S packs, seals, uploads: moves:movePacked { moveId, chunks, sha256, bytes } |
unpacking |
unpacking |
T downloads (moves:moveChunks, T only, the chunks' URLs), checks, opens and unpacks into staging, then moves:moveClaim |
claimed |
claimed |
T adopts the thread and mirrors it: moves:moveDone. The move ends once the thread's mirrored rows have all gone to T too (moves:rehomeRows, a page at a time); until then it stays claimed, so the thread can't start another move |
done |
done |
S puts its copy away (<home>/moved/<id>, kept 7 days), unless a later move has brought the thread back |
Any state before claimed can go to failed (moves:moveFailed { moveId, note }, by S or T, with what went wrong in a line Mike can read) or
cancelled (moves:cancelMove, owner, before unpacking). A move frozen
30 minutes ago and not yet claimed fails by itself, and one still asking
after 10 minutes from its start or S's description (T offline). One ready waits for S's thread to finish
its turn, so it fails only once S hasn't been heard from for 10 minutes,
or after 12 hours whatever S says, so it can't block the thread's next
move for good. On failed or cancelled S unfreezes the
thread if it froze it and T throws away its staging; the chunks are deleted
when a move ends, whichever way. A runner that restarts reads its moves
again and carries on from the state. A call refused with "The backend is
being updated" (a deploy's stepping stone, for a minute) is asked again,
only that call, rather than failing the move: 20 seconds later, then
longer each time, up to 5 minutes, for about 20 minutes in all. T's adopt
and moveDone at claimed, where there's nothing to fail, are tried again
the same way whatever went wrong. Older runners failed the move, or left
it claimed until T restarted, so while the stepping stone is up
moveDone and moveFailed still go through as they did before the
machine.
In the backend a move is a state machine (convex/moveMachine.ts,
machines.md) on its own field, moveState; state stays
these strings, written from it. Its one state runners don't see is
handedOver (every row gone to T, waiting for T's moveDone), shown as
claimed.
- Starting.
moves:startMove { threadId, to, cwd?, accountId?, expect? }(owner only;expectfrom API 83, the preview's binding below): the thread's row must be another runner's or this one's,toa different runner heard from in the last 3 minutes, and the thread in no other move still going. Answers{ moveId }. - S's info.
{ title, cwd, home, provider, accountId, email?, model?, effort?, permissionMode, origin?, repoTop?, subdir?, worktree: boolean, sessionId?, schedules: number }: what T needs to choose a folder and a login (homeis S's home folder, for swapping).originnever carries a password or token (withoutCredentialsin move-git.ts: any address loses its whole user part, in the URL anduser@host:pathforms alike (the host ending at the first:before any/, as git reads it, so an@in the path can't hide the user; one with an@and then a:after that, likeuser:token@host:path, can't be told from a login and is left out altogether), but for ssh's owngit, and the query and fragment go;host:pathwith no user still clones, ssh's own config giving the user), and the backend strips one an older runner sends (moveInfo, and amoves.previewcall's description). It's S's word, and S may be an extra Mac: from API 83 the backend'smoveInfokeeps only these fields, each of its type, strings at most 4096 characters with no control characters (it refuses one that isn't), and T reads it throughmoveInfoFromagain, which also refuses asubdirthat isn't plain names joined by/(no.,.., empty or %-encoded part, no backslash, never absolute). The preview sends T only what it plans from (previewInfoin moves.ts: no title, model, session or schedule count), scrubbed as sync scrubs, as a relay command isn't scrubbed on its way. - T's plan.
{ cwd, accountId, model?, effort?, worktree?: { repo, subdir }, clone?: { url, to }, within?: string, leftBehind: string[] }. The folder is Mike's pick if he made one; else, for a thread with a worktree, a new one of T's own in its copy of the same repo (found byoriginURL among the folders T knows, or cloned fromoriginto the path S has it at, with S's home swapped for T's:clonesays where); else the same repo byoriginURL at the same subfolder; else the same path with the home swapped. T picks the place, never S (Daybreak 136): a path of S's names a place on T only if it's under S'shomeand, swapped, still under T's once normalised, and never a place that isn't plain (plainPlace): T's home itself, or a folder with any folder on the way to it hidden or one tools load from (~/Library,node_modules,vendor,bin,site-packagesand the like), as written and links followed. Mike can pick one. The same goes for a repo T finds byorigin, even one of its own threads' (a dotfiles repo at the home, a checkout inside anode_modules), and one found from S's path must be inside T's home, links followed, unless one of T's own threads works in it. Asubdirin the repo that's a hidden or installed packages' folder (.git,node_modules/x, as written or through a link) runs the thread at the repo's top instead, with a note inleftBehind; in a fresh clone or worktree that's checked as made. A worktree thread's repo needs a worktree patch of its own: one found in a repo around it (a nested checkout) would make the worktree in that other repo, so the preview says so and placing refuses it. A clone is named for the repo (fromorigin, never S's folder name), goes only to a new folder in a plain place beside a repo one of T's own threads works in (its main checkout's folder, links followed), so never somewhere a tool loads from, and isn't made for a worktree thread (clone it by hand first: a worktree patch in a folder above a fresh clone would set it up); and the thread's folder must be inside its repo, Mike's pick, or T's home, links followed (within). T doesn't trust the plan the row gives back: placing plans again with the same checks, just before it clones or makes anything, refuses a plan that differs from the row's, and checks the folder as made (after the clone, the new worktree and its git work) before the thread takes it; a folder the git work didn't make runs at the worktree's top, with a note. The login is Mike's pick, else T's login with the same email, else T's default.leftBehindis what T already knows won't come. T answersmoveFailedwhen there's no folder or login for it. - Preview binding. A move does what its preview showed or nothing
(Daybreak 142). The main Mac's runner, answering
threads.movePreviewwith nothing inproblemsand a folder and login, works out a digest of the thread,to, Mike's picks, the planning half of S's description (cwd,home,provider,email,originwithout credentials,repoTop,subdir,worktree, as T will have it: throughpreviewInfoand the runner's scrubber) and T's answer (cwd,accountId,worktree,cloneand where from) (moveBindingin moves.ts), keeps it for ten minutes under a randompreviewIdit returns, andthreads.movewith thatpreviewId(once only, for the same thread, runner and picks) starts the move with it asexpect. Without one (the Swift app, an oldertb,move_thread)threads.movelooks itself and binds to that, refusing a move with a problem, or one that would clone (a clone is shown first, in the Move sheet). T works the digest out again from the description on the row and its own plan, ataskingand again before it downloads anything, and fails the move ("changed since the Move sheet looked") if they differ or the row has none. T says it does this withchecksPreview: truein its preview answer, and the main Mac's runner gives nopreviewIdfor a T without it (a runner from before this, which would do what the row says): a problem asks it to update first. The row'sexpectis the backend's word, so on the main Mac's runner, which starts every move, T also takes a move only with a binding its ownthreads.moveused in the last day, for that one move (MovePreviews.vouches: the movestartMoveanswered with, or the first to carry it), so a cancelled move's binding on a new move's row takes nothing; a restart between starting a move and taking it in fails it. Any runner leaves alone a move it has seen end (done, failed, cancelled) whose row comes back in an earlier state. Moves between two other runners are checked against the row alone. The main Mac's runner reads another runner's description through the relay, which scrubs anything shaped like a key, while the move's row keeps folder paths whole, so a thread whose folder name looks like a key fails its move as changed: it fails safe, and is left so. The GPUI app's Move to goes straight away only on a look with apreviewIdand no clone, and its Move sheet's Move with a folder or login changed since the look asks again and shows that first. - Freezing. From S's first step (
asking) until the move ends S starts no new turn on the thread: messages (the app's, the phone's, agents', schedules') go in its queue, which moves with it. A running turn goes on; holding the queue is what lets it end, soreadycan freeze.readywaits for that with no timeout (a long turn can take hours); Mike can Cancel. AtmoveFrozenthe CLI is released, so background shells stop.ThreadSummary.movingsays so (below). - The bundle. A tar, gzipped, of:
thread.json,events.ndjson,blobs/andmedia/from the thread's folder; the Claude session's transcript and its<sessionId>/folder; the thread's schedules (fromschedules.list); andgit.bundlewithgit.json. Sealed tokeyas secrets are (X25519, HKDF-SHA256 with infothreadbear move v1 <moveId>, AES-256-GCM), then cut into 9 MB chunks, uploaded as any runner file. Over 100 MB sealed, S fails the move saying what's big. A runner key's chunk (moveChunkUrl, then/runner/upload) is stored only while the move ispackingand the key is S's, is charged to S's stored bytes like a picture (with 120 MB of room on top of its 150 MB, so one move's worth always fits) but not the hour's allowance (the move's 24 tickets bound that), and is named with the move (storageOwners.moveId): when the move ends, however it ends, every upload made for it goes, listed inmovePackedor not, and S gets its bytes back. The main Mac's own chunks are Convex uploads with no such record, so when itsmovePacked(or a chunk) fails because the move ended meanwhile, its runner names them inmoves:moveDropChunks { moveId, chunks }(owner only, once the move has ended), which deletes each one no going move names and nothing else uses. - Git. Only for a thread with a worktree of its own.
git.bundleholds the branch from where it meets S'sorigin/<default>(so commits only on S's main come too), and one more commit,refs/threadbear/move-wip, of every uncommitted and untracked file (.gitignored ones stay).git.jsonis{ branch, head, wip?, base, origin?, subdir }. T fetchesorigin, makes the thread's worktree as for a new thread (branchthread/<id8>, its own slot, setup), fetches the bundle into it, checks out the branch athead, then putswip's changes back as uncommitted. A thread in a shared checkout moves to the same repo there without its changes, andleftBehindnames the files. Every git a move runs, on S and T, the preview's look for uncommitted changes included, goes throughuntrustedGit(runner/src/safe-git.ts): the repo's config is read first, and every filter driver it or yours names is switched off (clean, smudge and process blank, not required), with no hooks, fsmonitor, signing, diff programs or auto gc, and git never looks inside a submodule (--ignore-submodules=allon status and diff,--no-recurse-submoduleson fetch, reset, read-tree and ls-files), as a submodule's own config is one Threadbear hasn't read, nodiff.external(diffs are git's own), only the git commands a move and the done card's check use (log,show,merge,stash,git submoduleand the like are refused), the old runner's commit ids only as full ids, and no fetching at all but the bundle (file only) and T's fetch oforigin(https, ssh or file, git's own upload-pack, and only your own credential helpers, ssh command and alternates command). A repo with a filter name git's-ccan't carry (one with=) fails the step rather than running git. Files cross as the disk has them, so a git-lfs file goes as its content. T clones only from anhttps,sshoruser@host:pathorigin, into a new folder it picks (T's plan above). - The switch.
moves:moveClaimis the one mutation where the thread changes hands. It sets the thread row'srunnerIdto T (clearing any card on it), hands T its Pocket cards on the thread and its share link, deletes S's sidebar row (threadIndex) for it, and moves its mirrored rows (messages, tool bodies, pictures, and the stored files they name) to T in runs of their own, so the thread's history stays on the phone and nothing is cut. From then on commands for the thread go to T, and S's writes under the id are refused. - On T. The thread's folder goes into place with T's
cwd,accountIdand worktree, the transcript into that login's config folder under the new folder's name, and the thread is adopted as a handover adopts one. It gets asystem.note("Moved from M5 to cloud, in ."), plus what was left behind; its next turn resumes the same session (Claude; Codex starts afresh with the handoff note). The schedules are made again on T for the thread, and S deletes its own once the move isdone. T takes only when and what each sends (text,title,cronorat,timezone,paused, andcreatedByif it's the thread itself:movedSchedulesin moves.ts), as the bundle is S's word and S may be an extra Mac: no shell check (and the thread's note says one was left off), folder, login, mode or runner. The thread'sallowRules("Always allow" answers), its reply buttons and an open card's commands are dropped too (as it's placed, and again as it's adopted): asked or made again on T. On the main Mac (the owner key), a thread from another runner arrives with at most Ask: Full or Auto becomes Ask, and so does the mode Plan first would go back to, with a line in its note saying what it had (Mike, 10 Nov 2026: the mode is that runner's word, and the main Mac's sidebar never showed it); a thread in Plan first there goes back to Ask when its plan is approved. Any runner turns a mode it doesn't know into Ask. All of this is applied to the record before it joins the live threads, and again to one a crash left there or loaded. A moved worktree's setup doesn't run by itself when the moved git work changed the patch's copy or any file its setup reaches (from the commit T made the worktree from): Threadbear's own checkout is always trusted, so nothing else would stop the old runner's script running on T. The thread's note says so, and the setup can be run by hand after a look. For the same reason, a worktree whose moved work changed anything patch or Claude settings trust covers (a file under any.threadbearor.claudefolder or a.mcp.json, any case, or a file a patch there or the Claude settings reach, commands or grants), worked out from the move's own commits so an ignored file counts, is unvouched: listed inpatch-trust-unvouched.jsonbesidepatch-trust.json(a file of its own, as an older runner finishing turns rewrites the trust file with only what it knows), where an always-trusted checkout's trust doesn't reach it, so its patches and Claude settings wait to be trusted in Patches like any folder's. It stays so through the thread's delete and cleanup and across restarts, until a worktree is made there afresh. It's worked out again as the move is adopted, before anything loads (for one placed by an older runner, from the worktree, ignored files included). The file is{ "version": 2, "unvouched": [...] }. When it's missing, unreadable or has no version (it moved twice on 10 Nov 2026, from aworktree.unvouchedmark on the thread's record to anunvouchedarray inpatch-trust.jsonto here), the runner works the list out again at start, before anything loads a patch or seeds trust: every thread's worktree its record marks (worktree.movedIn, set for every moved worktree, or the oldunvouched), or whose event log has adoption's "Moved from" note, is held, as nothing says what an old move brought;patch-trust.json's array is taken in whenever that file is read. While the file can't be read, no worktree of an always-trusted checkout has its trust, only the checkout. A first start's seeding trusts none of a held worktree's patches. A thread handed over before start works the list out first, and a record that can't be read (about to be rebuilt without its worktree) holds the linked worktree its log's note names (security review, 11 Nov 2026). A move whose uncommitted work brings anything under anode_modulesfolder fails: those files would be untracked on T, which trust reads as installed packages and doesn't hash (one an older runner placed loses its untrackednode_modulesfiles at adopt, and setup installs them again). A changed symlink unvouches the worktree too. A preview's description in the backend has no title or session either (an older main Mac sends them). Queued messages are sent. T's mirror sends the thread's whole history again (a thread new to it), which overwrites the same seqs.
ThreadSummary.moving?: { moveId, to, toName, state, note? } while a move
is going on S, and for a minute after one fails there (with the note). The
main Mac's runner puts the same moving on another runner's row in
remoteThreads for the moves it knows of: one coming to it (from its own
watch, with a failure's note), and one it started between two other
runners (shown as asking until the thread is listed on its new runner, or
35 minutes, as it can't see that move's steps). Methods on the main Mac's
runner:
| method | params | result |
|---|---|---|
threads.movePreview |
{ threadId, runnerId, cwd?, accountId? } |
{ cwd?, accountId?, accounts: { id, provider, title, email? }[], leftBehind, problems, worktree?: true, clone?: string, cloneFrom?: string, previewId?: string, checksPreview?: true }: T's guess for the folder and login (or for Mike's cwd and accountId, to check them), its logins of the thread's provider to pick from, what won't come at either end (moves.describe adds the thread's own runner's, and sourceChecked: true says it did: without that, an empty leftBehind means nothing), and what stops it (empty when it can move: no folder or login for it, the experiment off on a T from before 12 Nov, a worktree thread's repo there with no worktree patch, T not answering). worktree: a new worktree of its own in cwd's repo; clone: that repo is cloned there first, from cloneFrom. previewId: the main Mac's runner's one-use id for this look, when nothing stops the move (Preview binding). Nothing is made or started. The thread is described by the runner that has it (here, or a moves.describe call to it), then planned by T (here, or a moves.preview call with that description). Both calls are on the relay's allow-list from backend API 65, owner only, and checked again on the runner. Failures come back in problems, not as an error |
threads.move |
{ threadId, runnerId, cwd?, accountId?, previewId? } |
{ moveId }. previewId is a threads.movePreview answer's, asked with the same cwd and accountId: the move does what it showed or nothing. Without one the runner looks itself first (Preview binding). -32602 with the reason when it can't start (the runner offline, a move already going, a used or stale previewId, a problem, or a clone without one) |
threads.moveCancel |
{ threadId, moveId? } |
{}. -32602 once the move is past packing. moveId (a threads.move answer's): that move is cancelled by its id, and -32602 if it's already over, so a cancel that arrives late can't stop a newer one; without it, whichever this runner sees under way. A runner from before 18 Nov ignores moveId |
What a tampered runner key can do: as T, it only ever gets threads Mike
moved to it; as S, only its own. It can't start a move, read another
move's chunks, or claim a move that isn't to it. A runner's name is its
own word, so move_thread and tb move --to pick the runner before
anything else (pickRunner in moves.ts: its id, its whole name, or a
word in only one runner's name; a word that's one's whole name and part
of another's picks neither), a thread that asks first shows that runner
on its card by name and id, and the move goes to that id, refused if
the runner has gone or changed its name since (stillRunner).
The runner mirrors the phone's view of its threads to Threadbear's Convex project (docs/convex-backend.md, shape A: the runner owns the state, Convex mirrors it, the phone asks through it). It's best effort: nothing the runner or the Mac app does waits on it, and the runner never reads the mirror back as state. The Mac app doesn't use it.
- On when
runner.jsonhassync.url(the deployment'shttps://<name>.convex.cloud) andsecrets/convex-key(0600) holds the key the deployment'sRUNNER_KEYwas set to (the main Mac) or this runner's own runner key (any other; see Runner keys).sync.enabled: falseturns it off; so doesTHREADBEAR_SYNC=offin the environment, which check.sh sets so no test runner writes to the real project.THREADBEAR_SYNC_URLpoints a dev or test runner at its own deployment. Every post carries the key, so the URL must behttps:, or plainhttp:only to this machine (a local backend, tests), with no name or password in it (runner/src/secure-url.ts); one that isn't leaves sync off, with the reason assync.reasonand in the log, rather than falling back on runner.json's. Posts and uploads refuse redirects, as fetch would send a 307's body, key and all, on to wherever it points.sync.nameis what the phone calls this runner (default: the Mac's hostname without.localor.localdomain);sync.runnerIdis made once and written back torunner.json, so a data dir stays one runner across releases.sync.iconnames an SF Symbol for the runner in lists (default: worked out from the Mac's model, seeRunnerInfo); the heartbeat carries it to a backend of API 11 or later, andsync:runnersListgives it back. - Threads. One
threadsrow per thread:threadId, runnerId, title, cwd, accountId, provider, model?, status, needsYou, unread, preview, createdAt, lastActivityAt, snoozedUntil?, snoozedUntilRestart?, archivedAt?, starredAt?(API 27; a starred thread that's hibernating stays in viewinbox, so the phone has it without loading Hibernating),wakeNote?(API 49: what a hibernating thread waits for when it's more than a time, in a few words, from runner/src/wake-note.ts: ""Convex I/O" finishes", "you talk about woodworking", "the runner updates"; the phone's and the website's rows put "Until …" before the place),costUsd?(to the cent),projects?: { id, title }[],working?(the first unfinished background task's description),pendingApproval?(below),earliestSeq?(Messages, below),share?(see Sharing; API 8),asks?andasksSeq?(the open card, below; API 14),next?(below; API 14),links?: { title, url, icon? }[](API 28: the thread's url actions, past theirwhen, with only an SF Symbolicon, so the phone shows them and opens them itself) andview(inbox,hibernatingorden, worked out the way the app's lists are). Nothing else fromThreadSummary: nolastSeq, context, panels, other actions, hooks or sub-agents, and never a tool result, diff or image (full sync, below, keeps those in a table of their own). Athread.updatedwhose phone view differs from the last one written marks the thread dirty; dirty threads are written together, at most once every 2 seconds, 50 to a mutation. A change only to its preview or unread waits until 20 seconds after that row's last write, and goes with anything else that changes first. Athread.deletedremoves the row and its messages. What's been written is remembered between starts as hashes (sync-sent.jsonin the data folder), so a start writes only what changed (comparing 20 seconds in, once patch links have loaded); every 3 days, with no such file, or whensync:heartbeatanswersfirstSeen, it writes everything and prunes (keeping the threads still finishing on the release that handed over). A start from the file removes, once it has settled, the rows the file has for threads that aren't here (deleted while sync was off), unless they're finishing on the release that handed over, and only after two minutes still missing, as a thread between releases isn't here for a few seconds. On every start, from the file or not, and every hour after, it askssync:sharedThreads(API 60) which of its rows are shared by link, and removes any whose thread is gone (after the same two minutes) and writes again any it has stopped sharing, so a stop or a delete the mirror never got (a write lost after it landed, a crash) can't leave a link readable. A thread ever shared has its row written as soon as sync starts, settling or not, and a share change never waits for the settle. Until the mirror's row has the link the thread has now (written, not just sent: a write that failed or was left out doesn't count, and a row with a link counts as there from when it's sent), none of that thread's messages go up, by any path (a phone's page of earlier ones included), and its row is tried again every minute; its whole history goes once the row is there.share:viewreads the row's share, so a message going first was readable through a link already stopped. Each write in flight is tracked as that write's own, so a flush that fails after its rows went never forgets another write's row on its way, and a row write that fails may have landed, so the next change to that thread is written even if it's back to what was sent before. - Messages. Each persisted
user.messageandassistant.textgoes up as amessagesrow (threadId, seq, role, text, origin?, at), text cut at 8,000 characters with a note; never a delta, with one row per tool call (role: "tool", one line), and one persystem.notewithloginorsavedMessage(role: "note", since backend API 78: a thread on another runner changed login and nothing on the Mac said so, 13 Nov 2026).relay:remoteTailandrelay:remoteMessagesgive note rows to a runner that asks withnotes: true(one from before API 78 would draw a note as a tool call), which plays them assystem.noteagain.phone:messagesgives them to an app that asks the same way (API 79: the iPhone app and the website draw them as the Mac does; one built before can't read the role).phone:thread, the phone's search and the shared page leave them out: a note names logins. A note a backend from before 78 couldn't take waits on the runner and goes up once it can. No other note goes up. The mirror keeps every one, and each thread's whole history goes up once per deployment. A start sends what's newer than the last one it wrote (sync-sent.json), or askssync:messageHeadson a full write. The row'searliestSeqis the seq of the thread's first text message. Apagecommand (an old phone'sloadEarlier, withbeforeSeq) marks up to 50 text messages before that seq as paged (pagedAt), sophone:threadshows them for a day. - Approvals. An
approval.requestedputs{ approvalId, kind: "approval", name, title, options, inputSummary? }on the thread's row (inputSummaryis one line: the command, the path, or the first string in the input, at most 200 characters, never the whole input). A card that line can't show all of (a command over 160 characters or on more than one line, a command, path or address with anything but printable ASCII in it, as anything else can draw differently from how a shell reads it (U+2028, bidi and zero-width characters, Hebrew or Arabic letters, a no-break space, wide characters:REMOTE_LINEin runner/src/tools.ts; the Mac's own card writes controls and format characters out by name, as⟨U+2028⟩), a path or address over 160 characters or with spaces at its ends, a Codex patch to more than one file or asking to write under a folder, in another folder or asking for the network, one scrubbing changed (checked again as the row goes up, after any value found since), an MCP tool with more than one short thing to read, any file edit (it shows only its path there, and Allow writes all of it), a threadbear tool's own card, Codex asking for more access) has only its non-allow options there, and its title names the runner whose app can allow it ("only the Threadbear app on bruce can allow it"); the runner refuses an allow or allowAlways that comes through the backend for one (Daybreak, 7 Nov 2026). Such a card goes up only on a runner with an app of its own: one connected now, or one that was in the last 14 days (<home>/app-seen.json, written on an app's hello and as it goes,runner/src/app-seen.ts). Elsewhere (a runner nobody runs an app on) it could only be denied, so no card is put up: the call is denied at once (ToolApprovalAnswer.noApp), asystem.notesays "Not asked: ...", and the agent is told to do it a way that doesn't need the OK. A plan's card (ExitPlanMode) still goes up, as it's also where a plan is sent back to be revised; aquestion.requestedputs{ approvalId, kind: "question", questions }.approval.resolved, or the thread no longer waiting, takes it off. - End-of-turn cards (API 14, 30 Oct 2026). The open card of asks
(see Needs you) goes on the row as
asksandasksSeq, each ask withoutwhereand with only itshttp(s)links, as the phone can't open a file on the Mac. While a thread is idle on a turn that said it needsnothing,nextis thatturn.completed's follow-ups. Anassistant.textwithsummary: truegoes up withsummary: true, so the phone can pick a turn's reply as the Mac does and fold the rest of the turn into one "Worked for" line. Asendcommand may carryanswers(AskAnswer[]), passed tothreads.send. A backend older than 14 gets the rows and messages without them. - Projects, schedules, accounts. Each
projects.updated,schedules.updatedandaccounts.updatedreplaces that runner's rows of the table with the whole list (schedules only while they're the runner's own file: once they live in the backend, see Schedules, "Runners", the runner writes them there directly and these mirrored rows are gone) (Projectwith its icon asicon: { symbol?, picture?, by },picturenaming the runner's copy of the picture, the file name without its extension;Schedulewithout effort and permission mode;Accountasid, provider, title, note?, email?, plan?, defaultModel?, usage?, neverconfigDir; from backend API 90 alsologinEndsAt?,signedOut?andyearToken?({ madeAt? }), for the Runners panel's logins; from backend API 20 alsomodels?(eachid, title, effortLevels?, defaultEffort?) anddefaultEffort?, for the phone's new thread pickers). The same at start, and the accounts again once a heartbeat first says the backend is at 20. From backend API 48 each project also has a small row inprojectHeads(no goals, state, notes or folders), written only when what it holds changes apart fromupdatedAt, whichphone:projectsreads. Every project from before is copied there on the first heartbeat any runner sends, once (backendMarks); until thenphone:projectsreadsprojects.sync:sharedUsagetakes the caller'srunnerIdand doesn't read that runner's rows, so it doesn't re-run for the runner's own writes. - Project pictures (backend API 5). A project's picture goes to the
deployment's file storage so the phone can show it: the runner asks
sync:projectIconsonce for what the mirror has, and for each project whosepictureis new or changed gets an upload URL (sync:iconUploadUrl), POSTs the bytes and records the storage id against the project (sync:setProjectIcon), which replaces and deletes the old file. PNG, JPEG and WebP go as they are (at most 256 px, as the runner stores them); an SVG is drawn to a 256 px PNG with Quick Look first, since the phone can't draw SVG. A picture that can't be read is skipped with a warning and tried again when the projects next change.sync:setProjectsdrops the picture of a project that's gone or has a symbol now. Only once a heartbeat has said the backend is at API 5 or later; an older backend gets the project rows alone. - Runner. A
runnersrow for this runner (runnerId, name, version, release?, startedAt, draining, threadCount, lastSeenAt), written once a minute. On start every thread is written once and rows of this runner for threads it no longer has are pruned. A stop for good (not a restart or a handover) setslastSeenAtto 0 so the phone shows it offline at once; a draining runner just stops, and the new release writes everything again under the samerunnerId. - Runner figures (API 45). While the website's Runners view is open it calls
phone:watchRunnersevery 30 seconds, keeping a time in the future inrunnerWatch. Each runner subscribes to that (sync:runnerWatch), and while it's in the future sends its machine's CPU, memory and disk every 10 seconds to a row of its own (sync:setRunnerStats;runner/src/runner-stats.ts). The Mac app's runner details do the same through the main Mac's runner (API 46,runners.stats):sync:watchRunnersFromMacandsync:runnerStatsList, owner key only. With nobody looking nothing's written. The heartbeat carries onlypressure(memoryordisk, looked for every 5 minutes), which rarely changes, as every phone's runner list re-runs when that row does. - Commands. The phone's mutations (
convex/phone.ts) add a row tocommandsfor a runner (runnerId, or"any"). The runner holds a live query on its pending commands over the Convex client's WebSocket (it reconnects by itself; and after a pause the process didn't see, a wall-clock jump of more than 15 s between its 2-second ticks, such as a Mac waking from sleep or a box resumed, the runner drops that client and makes a new one with every live query on it at once, then heartbeats, at most once in 30 s:runner/src/clock-jump.ts,reconnectNowinsync.ts), and for each one: takes it (sync:takeCommand, which says no if it was already taken; from backend API 85 the runner passesattempt, its own id for the take, and the same attempt asking again after an error gets yes, so a take whose answer was lost runs rather than being dropped), applies it through the same methods the app's RPCs use (one about a thread a draining runner still has goes to that runner, as the app's would), then finishes it with the outcome and, for acreateorquickAsk, the new thread's id (from API 85 a finish changes only a taken command, so a repeated or late one can't change how it ended, and a command taken 3 hours ago with no finish shows asfailed, "Its runner never said how it went.", which its runner's late finish still settles; it's never handed out again).sendandcreategive theuser.messageorigin: "phone". Acreatecan nameaccountId,modeland (backend API 20)effort, checked asthreads.createchecks them; an effort that isn't a level is dropped. Either can carryimages: { storageId, url }[](backend API 18), photos the phone put in file storage (phone:imageUploadUrl), whentextmay be empty: the runner fetches each, sends it as an ordinaryImageRef, andsync:finishCommanddeletes them from storage, whether or not the send worked. The phone uploads a photo as soon as it's picked, so one that's never sent goes back withphone:discardImage(backend API 25). Since 7 Nov 2026 the upload URL is the deployment's own/phone/uploadwith a one-use ticket, which records the photo as that phone token's (phoneUploads): a command takes only its own token's photos,discardImagedeletes only those (and not one still in a waiting command), and one never sent is deleted after a day. A token gets 60 upload URLs an hour, 300 and 300 MB a day, 10 MB a photo. The phone's text can place its photos with[Picture N]markers, inimages' order (Pictures in a message). A message row with pictures no marker places gets a[1 picture]line, as the pictures themselves stay on the Mac; the ones a marker places show as chips.updatetakes one of{ snooze: { until?, untilRestart? } },{ wake },{ archive, verdict? }(verdictfrom API 42),{ unarchive },{ markSeen },{ title }or{ star: boolean }(API 27);respondisapprovals.respond's decision, message and answers;pageis{ beforeSeq }(above).quickAsk(backend API 10) is{ question, answer, sources: { title, url }[], askedAt }: a quick ask the phone already answered out loud (from Agent Archive's/api/quick/ask, straight over Tailscale), kept as a thread so Mike can carry on in it. The runner makes a thread as acreatewith nocwdwould (the default folder, never a worktree, the login and model a new thread gets) but runs no turn: it writes the question as auser.messagewithorigin: "phone",turn.started, the answer as anassistant.text(the sources after it as markdown links), asystem.note"Answered by Ask from Agent Archive" and aturn.completed(completed,needs: "nothing"), all under oneturnId, and marks it seen, since Mike has heard it. The title comes from the question, then a model title with the answer as the reply. A spoken follow-up wants a quick reply, so the thread is set to Haiku when the runner has a Claude login, else GPT-6-Luna at low effort with a Codex login, else the account's default. The first message sent to it starts a fresh session with a handoff note saying the thread began as a quick ask that a fast model answered (seethreads.updatefor the note). Likecreate, it finishes with the new thread's id.interrupt(API 44) stops the thread's turn, andcall(API 44) runs one allow-listed method and finishes with its answer asresult; both come only from the main Mac's runner (Other runners' threads through the backend). A failed command getsstate: "failed"and a readablenote. A draining runner takes no commands. Finished commands go after a day. - Failures. A write that fails is kept and tried again after 5 seconds, doubling to 5 minutes, with one log line per distinct error; a newer state for the same thread replaces the one waiting. Rows are current state, so a long outage costs one write per changed thread when it's back.
- Secrets. Every mutation goes through the runner's scrubber on its way up
(
ConvexSync.post,src/scrub.ts), every free-text field at any depth, so a new field is covered without anyone remembering to: known values first (src/secret-values.ts), then the shape rules (src/redaction.ts). Identity fields aren't touched (NOT_TEXTthere: ids,key, timestamps), the digests that decide what's changed are of the row before scrubbing, so a rule changing writes nothing by itself, and the runner's own copy never changes. A message or tool line is also scrubbed before it's cut short. A string whose check throws goes up asHELD_BACK, andsync.scrub.failedcounts them. While the runner is still reading.envfiles, mutations other than the heartbeat wait, for up to a minute, then fail so the flush tries again; a folder that doesn't answer in 5 seconds is left for the next look and counted infoldersUnread. Backend API 47 does the shape check again in every mutation that takes a runner's text, and on a command'snoteand a call'sresult(scrubbed as parsed JSON, so it stays JSON). A command'sargsare stored word for word only so they reach the runner intact, and are dropped when it's over, however it ended, keeping onlyimages(relay:queueCommandskips the runner's scrubbing for the same reason). A question'sanswersmay name it as scrubbed (matchAnswers). A schedule that lives in the backend comes back scrubbed, so one whose text holds a secret runs with[REDACTED]. Pictures aren't scrubbed.src/withhold.tssays which tool calls' output must never upload. - Full sync (API 52, docs/archive/full-convex.md step 4).
sync.full: trueinrunner.json, off by default and never offered (docs/archive/full-convex.md step 6); off, none of this runs. Each finished tool goes up as oneeventBodiesrow under its call's seq, the same seq as itsmessagesrow (sync:appendBodies, at most 50 rows or about 512 KB a mutation, behind the mirror's own writes):text,ok,truncated,inputanddiffsas JSON text,reasoningfrom before it,imagesas a count. Reasoning with no tool after it goes under the next message's seq, or its own at the turn's end; nothing shows those yet.src/withhold.ts's say-so, or a check that throws, makes the rowwithheldwith nothing of the tool in it. Scrubbed then cut (src/full-sync.ts: 96 KB of text, 48 KB of input, 64 KB of diffs, 32 KB of reasoning;cutsays so), and scrubbed again in the mutation. Forward only: where each thread had got to is insync-sent.json(bodies), and a start reads only threads past that, up to 20,000 events, then goes on from now. It's sent again only after a lost reply, and an identical row writes nothing.runner.status'ssync.fullis{ bodies, bytes, withheld, unsent, pending, backendTooOld? }, andsync.useis{ sent, bodies, io, storage, since, warning? }: bytes this runner sent in the last 30 days, the part that was tool output, and estimates of a month's I/O and of stored tool output against Convex's Free plan (src/convex-use.ts), with awarning(also arunner.noticeon connect) past 70% of either limit unlesssync.usageWarningis false. A runner can't read its team's real usage, so these are estimates of this runner alone. Reads:phone:eventBody { token, threadId, seq }andsync:remoteBody { key, threadId, seq }answernull,{ state: "withheld", reason? },{ state: "expired" }or{ state: "text", text, ok?, truncated?, input?, diffs?, reasoning?, images?, cut? }, one query per opening, never live;share:viewhas none of it.pruneBodiesdeletes past 30 days, 100 rows every 15 minutes. A runner key's rows count againstCAP.bodyBytes(32 MB), oldest first. - A tool's picture (API 52).
phone:requestPicture { token, threadId, seq, index }queues apicturecommand for the thread's runner, which checkssync.fullis on, the tool isn't withheld andindexis one its result names in that thread's media folder, then uploads it (sync:addHeldPicture).phone:heldPicturehas its URL for a day (pruneFiles). An older runner fails the command as unknown. A runner key'saddHeldPictureis refused unless it has taken apicturecommand for that thread, seq and index and not finished it yet, so there are only as many as were asked for. - Status.
runner.statushassync: { state: "off" | "ok" | "error", reason?, url?, runnerId?, name?, threads?, messages?, lastSyncAt?, lastError?, pending?, retryAt?, commands?: { state: "off" | "on" | "error", applied, failed, lastError? }, scrub?: { rulesVersion, knownValues, foldersUnread?, changed, failed, lastFailure?, backendChecks? } }, andsecretCheck: { state: "off" | "unsupported" | "unavailable" | "on", reason?, since, checkedText, checkedImages, flaggedText, flaggedImages, errors, rulesAndModel, rulesOnly, lastRunAt?, skippedOnBattery?, file? }(reasonsays why it's off;threadsandmessagesare rows written since start;pendingchanges waiting), andtb statusprints it as one line. - Convex side.
convex/at the repo root (schema,sync.tsfor the runner's mutations and the command queue,phone.tsfor the phone's queries and mutations,tokens.tsfor phone tokens,crons.tsfor pruning). The phone's API is in docs/convex-backend.md.
The phones and browsers that read the mirror (Sync) each hold a phone
token (convex/tokens.ts): only its SHA-256 is kept, under a name, a
kind and an expiry, so each can be listed and revoked on its own. The
Settings window's Phone & browser tab issues them through the runner,
so nobody needs the Convex CLI (ios/scripts/pair-qr.swift and
web/scripts/sign-in.swift still work from a terminal).
type Device = {
id: string // the token's row id, for devices.revoke
kind: "phone" | "browser"
name: string // "iPhone", "Chrome": what the app called it when pairing
createdAt: string
expiresAt: string
expired: boolean
}devices.pairfor a browser asks the backend for a one-use sign-in code (sync:issuePairingCodewithkind: "browser", API 81; one use, ten minutes, only its SHA-256 kept) and hands the app the website's sign-in link,<site>/#code=<tbp_…>, which the app opens in the default browser. The#fragmentnever reaches a server; the site trades the code for the browser's token withtokens:claim({ code })and wipes it from the address bar. The link used to carry the browser's token itself (#token=), good for 90 days wherever the link was seen (copied, synced, in history, offered to another app); the site no longer keeps one from a link, andsync:issueTokenrefuseskind: "browser"too, so an older runner says to update. For a phone it asks for a pairing code instead (sync:issuePairingCode, API 80): one use, good for ten minutes, with only its SHA-256 kept.pairingLinkis then the text the app draws as a QR code:TBPAIR1_and the base64url (no padding) ofurl=<sync.url>&code=<tbp_…>&key=<runnerId>:<key>. It's no link, so no app on the phone can claim it and the Camera opens nothing with it; the phone app's own scanner reads it and trades the code for the phone's token withtokens:claim({ code }), once (Daybreak finding 127, 15 Nov 2026: the code used to be athreadbear://pairlink with the 90-day token in it, and any app can register that scheme). The phone's token is made at the trade, so it shows indevices.listfrom then; the reply'sdevicestands for it until then, with the code's id. A backend older than 80 has no pairing codes, and a phone doesn't pair (-32000, the backend deploys with the runner's next update) rather than getting a token in its QR code. The token and the code are in that reply and nowhere else: the runner never logs them, never writes them to disk, and notbcommand prints them, since a thread's transcript can command agents. The app shows the QR code or opens the link, then forgets it. The phone apps no longer take an older runner'sthreadbear://pair?url=…&token=…from anywhere (that token may already have reached another app), and the backend'ssync:issueTokenrefuseskind: "phone", so an older runner can't make one: it says to update.- A backend on this Mac only (
sync.urlon loopback:setup --self-hosted --local, docs/self-hosting.md) can't pair a phone:devices.pairwithkind: "phone"is-32000saying why, before any token is issued. A browser still signs in, at the loopbacksync.site. The app reads the same fromrunner.status'ssync.urland shows the reason in place of the button. devices.listis the backend's live list (sync:listTokens), never revoked ones; expired ones stay until revoked, so the list says why a phone stopped working. Nothing is cached in the runner.devices.revokemarks the token revoked (sync:revokeToken); the phone's or browser's next call fails as unauthorised and it shows its pairing or sign-in screen. The phone's push registration goes with it, so it gets no more notifications (convex/tokens.ts).- With sync off,
devices.listreturns no devices andreason(the same asrunner.status'ssync.reason), andpairandrevokeare-32000with that reason. A backend older than API 6 has none of these functions:pair,listandrevokeare-32000saying the backend deploys with the runner's next update.