Build notes, from 27 Oct 2026 (thread 89b52654). Section 5 is what's built and how to work on it; section 6 the phone's API as agreed with the iPhone thread (f5247e5b). Sections 1 to 4, the 27 Oct research behind it (shape "A": the runner owns the state, Convex mirrors it and carries the phone's requests back), are history now, in docs/archive/convex-backend-research.md.
The Convex project is threadbear on team mikec
(https://dashboard.convex.dev/t/mikec/threadbear). Its code is convex/
at the repo root, with the root package.json holding the convex
dependency; convex/_generated is committed so ./check.sh can typecheck
the functions without a deployment (npm run convex:typecheck). Having a
convex/ folder here also gives threads in this repo the built-in Convex
dashboard panel.
convex/schema.ts:runners,threads,messages,commands,projects,schedules,accounts,tokens,devices,runnerKeys,threadTombstones,runnerLogins(docs/protocol/keys.md, "Runner keys").convex/sync.ts: the runner's mutations (upsertThreads,removeThreads,prune,heartbeat,bye,appendMessages,setProjects,upsertProjects,setSchedules,setAccounts,takeCommand,finishCommand), its queries (threadsOf,runnersList,messageHeads,pendingCommands, which it holds as a live query) andpruneOldforcrons.ts.convex/relay.ts(API 44) is the main Mac's runner reading another runner's thread (remoteTail,remoteMessages,remoteThread, and from API 87picturesAtSeqs, the pictures pasted into its messages) and queueing work for it (queueCommand,commandState,remoteAccounts), owner key only, so the Mac app opens other Macs' threads with no link to them (docs/protocol/runners.md, "Other runners' threads through the backend"). Each takeskey: the deployment'sRUNNER_KEY(the owner key, the main Mac's), or a runner key fromrunnerKeys, which acts as its own runner alone (convex/lib.tsrunnerAuth,convex/runnerAccess.ts; the table of who may call what is docs/protocol/keys.md, "Runner keys").tb runner addon the main Mac makes one for another Mac.convex/phone.ts: the phone's API (section 6).convex/push.ts(Node action) andconvex/devices.ts: APNs over HTTP/2 with the team's token-based key, copied from Poddle'sapns.ts.sync:upsertThreadsschedulespush:notifywhen a thread'sneedsYougoes from false to true (at most once per thread every 30 seconds,pushedAton the row); the action re-reads the row, skips it if the Mac has seen it meanwhile, and sendspushText's title and body (convex/pushText.ts: the question, the approval and its input line, "Failed: …", or the reply) to every registered phone, sandbox and production installs each to their APNs host. A token Apple reports gone is dropped. Only phones whose token is still good get one: eachdevicesrow keeps the token it registered with (tokenId, since 5 Nov 2026), revoking a token deletes its phones' rows, anddevices:targetsskips an expired or revoked token's (convex/pushTargets.ts). Older rows only have the token's name, which isn't unique, so they get no pushes and go when a token of that name is revoked (devices:dropUnlinkedclears them all); a paired phone makes itself a new row by registering again each time the app starts. A backend without its own Apple key goes through the push relay (docs/push-relay.md), and registers with it once, proving it's this deployment through/relay/verifyinconvex/http.tsand therelayCheckstable. Env on both deployments:APNS_KEY_P8,APNS_KEY_ID,APNS_TEAM_ID(Poddle's key, copied 28 Oct and again on 6 Nov 2026 after Poddle's old key was revoked) andAPNS_TOPIC(com.mikecann.threadbear). Each send's outcome goes in thepushHealthrow (convex/pushHealth.ts); while none get through, the owner runner's heartbeat answerspushFailingandtb statussays so.npx convex run push:test '{"body":"hi"}' --prodsends a test;npx convex run devices:list --prodshows the phones.convex/tokens.ts: the token helpers, andissue,revoke,listto run from a terminal withnpx convex run tokens:issue '{"name":"iphone","days":90}'(add--prodfor the Sydney prod deployment). Only the SHA-256 of a token is stored, with a name and a kind (phoneorbrowser). Since API 6 the Mac app issues them through the runner instead:sync:issueToken,sync:listTokensandsync:revokeTokentake the runner key (docs/protocol/moves.md "Devices"), so pairing needs no Convex CLI.runner/src/sync.ts: the mirror, documented in docs/protocol/moves.md ("Sync"): on withsync.urlinrunner.jsonandsecrets/convex-key; threads, messages (all of them, backfilled once), the pending approval on a row, projects, schedules and accounts; coalesced writes, batches, backoff, prune on start, bye on a stop for good; the phone's commands applied through the runner's own methods (origin: "phone"on the message);runner.status.syncand atb statusline.- Tests:
runner/test/unit/sync.test.ts(fake deployment) andrunner/test/e2e/sync.e2e.test.ts, which startsnpx convex devon the repo's local deployment, points a runner at it with its own key and reads back through the HTTP API and the phone queries. It skips without a local deployment in.env.local.
Deployments (made 28 Oct, after Mike freed the team's deployment
quota by deleting its 41 temp-*/tmp-* projects), all in Sydney
(aws-ap-southeast-2):
| name | URL | |
|---|---|---|
| prod | opulent-moose-249 |
https://opulent-moose-249.ap-southeast-2.convex.cloud |
| dev | earnest-puffin-640 |
https://earnest-puffin-640.ap-southeast-2.convex.cloud |
| local (e2e only) | local-mikec-threadbear-1 |
http://127.0.0.1:3210 |
.env.local at the repo root (gitignored) selects the dev deployment, so
npx convex dev pushes there and npx convex deploy ships prod.
.env.e2e names the local one for runner/test/e2e/sync.e2e.test.ts,
which passes --env-file .env.e2e to every convex command it runs. Both
cloud deployments have RUNNER_KEY set to the key in the M5's runner's
secrets/convex-key, and the live runner.json has sync.url pointing
at prod, so the mirror is on from the runner's next start. Bruce has a
runner key of its own on prod (tb runner add bruce --ssh bruce --id cb921b2447ea --replace), not a copy of RUNNER_KEY, and so has the
Hetzner box (cloud, runner befe8df8975c, since 07:03 UTC 5 Nov),
which that day's rotation had cut off while it still had the old shared
key. To rotate RUNNER_KEY with no gap, tb runner rotate-owner on the M5, restart its runner, then tb runner rotate-owner --finish (docs/protocol/keys.md, "Runner keys").
Working on it. npx convex dev at the repo root runs the local
backend and pushes convex/ as it changes; npx convex env set RUNNER_KEY <key> on it once, and a dev runner with THREADBEAR_SYNC_URL set to the
local URL and the same key in its secrets mirrors there. ./check.sh
sets THREADBEAR_SYNC=off so no test runner ever writes to the real
project.
Deploying (since 28 Oct). Nobody runs npx convex deploy for prod by
hand any more. runner/scripts/deploy-backend.mjs deploys convex/ and
web/ at a commit, from a clean git archive in a temp folder, whenever
they've changed since what <data>/backend.json records. It uses the deploy
key in <data>/secrets/convex-deploy.env (CONVEX_DEPLOY_KEY=, made with
npx convex deployment token create threadbear-runner --prod --save-env <file>, never printed) and refuses a key for any deployment but the one
runner.json's sync.url names. The runner's updater runs it for each new
commit of main before it builds a runner release, and holds the runner back
(state failed, a notice) if it fails; deploy-runner.sh runs it as step 4
(--skip-backend to leave it out). --status, --dry-run and --force
do what they say. Log: <data>/runner/update/backend.log.
Notifications and presence (API 3, 28 Oct). Mike was getting pushes
while sitting at the Mac. Now each runner works out whether he's at its Mac
(runner/src/presence.ts: the Mac app connected and the keyboard or mouse
used in the last two minutes, from IOKit's HIDIdleTime), checks every 15
seconds and sends sync:setPresence when it changes. Each phone has a
setting (devices.notify, set with phone:setNotifications from the app's
Settings › Notify me): away (the default) only gets a push while he isn't
at the Mac, always gets every one, off none. A push that's held back
while he's there marks the thread pushHeldAt; leaving the Mac sends it to
the away phones if the thread still needs him. A runner that hasn't
checked in for 3 minutes (a sleeping Mac) counts as away, and what it held
goes then (sync:sendStaleHeldPushes, a cron every 2 minutes): a Mac whose
lid closed with Mike at it never says he left. The cron only hands each
such runner to a mutation of its own (sync:drainHeldPushes), which sends
16 at a time and schedules the next 16, so one runner's backlog (a
secondary key may hold 3,000 large rows) can't read past a mutation's
limit and stop another Mac's pushes (Daybreak 119, 13 Nov). Each drain
ends: it takes only pushes held before it began (one push.notify holds
again because he's back waits for his next leave) and stops as soon as the
runner counts as present again, so a runner that keeps saying he's there
and keeps its threads needing him can't keep a drain going (Daybreak 148,
17 Nov). Holding a push asks again whether he's there, in the same
transaction: if he left since push.notify looked, it goes to the away
phones instead (once: if he's gone again by the next hold, it's held).
The same cron sends anything held for a runner that said he left, so a
push held just after his leave's drain finished waits two minutes at most.
Keeping old and new working together. For a while after any change, an older runner, a newer backend and an App Store phone app from weeks ago all meet. So:
- Change the backend so it still takes what the old runner sends and still returns what the old phone reads (new fields optional, nothing removed or renamed), and only later stop accepting the old shape.
- Since API 67
sync:heartbeattakesfollowProblem, a runner's word that it can't follow GitHub's main (docs/dev-tools.md); the main key reads it fromsync:otherRunnersList. - Since API 91 it also takes
updateFailed, a following runner's failed update to main (cut to fit from a runner key, dropped from a box's), which the main key reads the same way and fixes on the main Mac (docs/dev-tools.md). convex/version.tshasAPI_VERSION, returned bysync:heartbeatandphone:me. Bump it when a client starts relying on something new, along withBACKEND_API_VERSIONinrunner/src/sync.ts(a unit test keeps them equal). The runner shows an older backend intb status; the phone app says "Update it on the Mac" when the backend is belowBackendCompatibility.minimumAPIVersion(ThreadbearKit).
Agreed with thread f5247e5b on 27 Oct. All in convex/phone.ts. Every
function takes token (a phone token from tokens:issue) and throws
ConvexError({ kind: "auth" }) for a bad, expired or revoked one;
{ kind: "notFound" } for a thread or command that isn't there.
Queries:
phone:me({ token })→{ name, expiresAt, apiVersion, pushOff? }.pushOffis true when this backend can't send notifications (a self-hosted one, docs/self-hosting.md); the phone's Settings says so in place of the Notify me picker.phone:runners({ token })→[{ runnerId, name, version, lastSeenAt, draining }]. Offline islastSeenAtolder than 3 minutes (a runner that stopped for good haslastSeenAtof 1970). Since API 45 alsorelease?, startedAt?, threadCount?, pressure?(memoryordiskwhile one's running low). Since API 56 in Mike's order (phone:setRunnerOrder): the runners he's placed as he placed them, then the rest, the main Mac first and the others in the order they first heartbeated (never by thread count, which a runner says of itself), withplaced: trueon the ones in the saved order andmain: trueon the main Mac (owner key, no runner key of its own). The phone's automatic pick is the first placed one online, else the main Mac, else none (it sends norunnerId), so a runner key's Mac is only picked for Mike once he's placed it.phone:wakes({ token })(API 45) →[{ scheduleId, threadId?, nextRunAt? }], a small row per active schedule, fromscheduleWakes: what a sidebar needs all the time: the website's sidebar, and the iPhone's inbox (from the app after 1.0.4; older ones, and any on a backend before 45, followphone:schedules).phone:schedulescosts about 200 KB and re-runs on every claim and run, so it's for a schedules view that's open. Kept open by the phone's inbox it was about 10 MB of Database I/O a day (7 Nov).phone:runnerStats({ token })(API 45) → each runner's machine figures, last reported while someone was watching, andphone:watchRunners({ token })says someone is (docs/protocol/moves.md, Sync, "Runner figures").phone:threads({ token, view: "inbox" | "hibernating" | "den" })→ rows, newestlastActivityAtfirst; the den is capped at 100. A row isthreadId, runnerId, title, cwd, accountId, provider, model?, status, needsYou, unread, preview, createdAt, lastActivityAt, lastActivityMs, snoozedUntil?, snoozedUntilRestart?, archivedAt?, costUsd?, projects?: [{ id, title }], working?, pendingApproval?, asks?, asksSeq?, next?, needs?, pendingReviews?, waitingForRoom?, links?, view.links(API 28) are the thread's patch link buttons ({ title, url, icon? }, web pages only), which the phone shows over its message box and opens itself.asksandasksSeq(API 14) are the open card of the agent's end_turn asks ({ action, why?, reply?, options?, suggested?, links?, ticked? }, web links only), andnexta finished turn's suggested follow-ups, for the done card.needs(you|nothing),pendingReviewsandwaitingForRoom({ until, accountId? }) (API 15) are what the phone needs to sort threads into the Mac sidebar's sections: withphone:wakesit puts an idle thread a schedule will message under Hibernating, by the same rules as app ThreadSections.pendingApproval(from step 2) is{ approvalId, kind: "approval", name, title, options: ("allow" | "allowAlways" | "deny")[], inputSummary? }or{ approvalId, kind: "question", questions: Question[] }with the protocol'sQuestionshape.phone:counts({ token })→{ hibernating, den }(API 17): how many threads are in each, uncapped. The phone shows them on its folded Hibernating and Archived headings and subscribes tophone:threadsfor those views only while their section is open or a search is on.phone:thread({ token, threadId })→{ thread, messages: [{ seq, role, text, origin?, at, pagedAt? }] }, oldest first: the newest 20 text messages plus any paged ones (originis"phone"for one sent from the phone,"schedule"or"runner"as in the protocol). The row'searliestSeqis the seq of the thread's first text message: while the oldest message the phone has is newer than that, there's more to load.phone:messages({ token, threadId, beforeSeq?, limit?, tools? })(since API 2, 28 Oct) →{ messages, hasMore }, oldest first: the newestlimit(default 50, at most 2000; NaN or an infinity is refused, here and in everylimit) or thelimitbeforebeforeSeq. Withouttoolsit looks past at most 4,000 tool rows for the page's text ones, then sayshasMore. Every message is kept since API 2, and withtools: truethere's one row per tool call too (role: "tool", a one-linetextsuch as "Run the unit tests" or "Edited ~/dev/x.ts", andtoolKind). A login's note (role: "note", API 78: the line a thread writes when its login runs out) is in a page only when it's asked for withnotes: true(API 79), as the website and iPhone app builds after 1.0.4 do; an app built before can't read the role.phone:threadnever has them. A user's message that answered the open card's asks carriesanswers(API 89),[{ action, answer }]: each ask's question and the pick, which its text starts with as the Mac wrote them (AskAnswer.message), so the iPhone draws the question small over the answer, as the Mac's bubble does. It reads Convex alone, so it works while the Mac is asleep. The website watches only the newest 30 with it and reads older pages once, withbeforeSeq(web/src/transcript.ts). The iPhone does the same with an 80-row live page and chunks of 200 (MessageHistory.swift), watchingphone:imagesfrom the first row read once for pictures that finish uploading late; builds before 1.0.5 raiselimitas you scroll back, re-reading up to 2,000 rows for each new message (37.6 MB on 8 Nov), which is whyPAGE_MAXstays 2,000 until they're gone.phone:threadstays as API 1 had it (newest 20 text messages plus any paged ones, never tool rows), for phone apps built before.phone:threadsAt({ token, view })(API 43) →{ rows, at }, a list once;phone:threadsSince({ token, since })→{ rows, gone, more? }, every row written at or aftersincein any view, each withupdatedMs, and threads gone or out of the lists. The client merges them and asks again from the newestupdatedMsless 5 seconds (a mutation can commit just after one stamped later), so each run reads only what changed;moresays to load the list again. The website and the iPhone follow the inbox this way; hibernating and archived stay onphone:threads, as they're rarely written.phone:threadRow({ token, threadId })(API 37) → the thread's row alone, for a client that reads messages withphone:messages.phone:images({ token, threadId, from })(API 37) → the thread's pictures from that seq on, for a client passingnoImages: truetophone:messages.phone:command({ token, commandId })→{ state: "pending" | "taken" | "done" | "failed", note?, threadId?, result? }.result(API 62) is aslashCommandscommand's answer, the thread's list.phone:waiting({ token, threadId })(API 57) → the thread'ssendcommands not yet finished, oldest first:{ commandId, state: "pending" | "taken", text, photos, createdAt }. The phone shows each as a faded message under the transcript, so several sent while the runner is asleep don't look lost.phone:cancel({ token, commandId })(API 57) →trueif the send was still pending and is nowfailedwith note "Cancelled" (its photos deleted),falseonce the runner has taken it.sync:takeCommandcheckspendingin its own transaction, so only one of the two wins.
Since API 16, phone:search({ token, text }) returns up to 30 archived
thread rows whose title or last reply has those words (Convex full-text
search, the last word as a prefix), for the phone's search: phone:threads
gives it only the newest 100 of the den.
Also phone:projects({ token, archived? }), phone:schedules({ token })
and phone:accounts({ token }), the runner's lists as it last sent them
(docs/protocol/moves.md "Sync" says which fields). Since API 48 phone:projects
reads projectHeads and returns goals, state, notes and folders empty;
phone:project({ token, runnerId, id }) is one project whole, or null, read
only when its page is open. Since API 5 a project row
has icon?: { symbol?, url?, by }: the Mac's ProjectIcon with the
picture as a URL into file storage (the runner uploads it, docs/protocol/moves.md
"Sync", "Project pictures") in place of a path on the Mac. The phone draws
the picture, else the symbol, else the title's first letter, as the Mac
sidebar does; a runner before API 5 sends projects without icon.
Mutations, each returning a commandId. The owning runner takes it
within a second or two while it's online (state taken, then done or
failed with a note); while it's offline the command waits as
pending, for up to 14 days (then failed, sync:pruneFiles). At most
200 commands, or 8 MB of them, wait for one runner; past that the next is
refused with { kind: "tooMany" } until it takes some. A runnerId the
phone names must be one that has heartbeated (or "any"), else
{ kind: "notFound" }:
phone:send({ token, threadId, text, answers? })(answers, API 14: the card's asks it answers,{ action, answer }[])phone:press({ token, threadId, buttonId })(API 59) → commandId: a reply button's press (docs/protocol/events.md, "Reply buttons"), queued as apresscommand with{ buttonId }. ItsresultThreadIdis the thread the button started or messaged.phone:messagesrows carrybuttons, the state of the buttons an assistant message links, since API 59.phone:slashCommands({ token, threadId })(API 62) → commandId: asks the thread's runner for the slash commands it can run, for the reply box's palette (docs/protocol/threads.md, "Slash commands"). The runner answers with itsthreads.commandslist as the command'sresult(kept bysync:finishCommandas for acall); an older runner fails it as unknown.phone:designReviews({ token, threadId, reviewId? }),phone:respondReview({ token, threadId, reviewId, revision, draft })→ commandId, andphone:reviewImages({ token, threadId, sources })(API 86): the Reviews sheet. The first two are commands the thread's runner answers from its own reviews (the review comes back as the command'sresult); the stills go up only once the phone has opened that review (docs/protocol/events.md, "Reviews on the phone").phone:interrupt({ token, threadId })(API 69) → commandId: Stop, queued as aninterruptcommand, which ends the thread's running turn as Stop on the Mac does. Runners have applied it since API 44 (the main Mac sends it for another runner's thread).phone:respond({ token, threadId, approvalId, decision: "allow" | "allowAlways" | "deny", message? })phone:answer({ token, threadId, approvalId, answers: Record<string, string>, message? }): one answer per question keyed by its text, as the runner'sapprovals.respondwith decisionansweredtakes it;messageis the answers in one line for the transcript (default: joined with "; ").phone:secret({ token, threadId, approvalId, sealed?: { epk, nonce, box }, decline? })(API 35): the answer to apendingApprovalof kindsecret, sealed to that card'skeyso only the runner can open it (docs/protocol/threads.md, "Secrets").sealedis dropped from the command once the runner has finished it.phone:update({ token, threadId, change })wherechangeis one of{ snooze: { until?, untilRestart? } },{ wake: true },{ archive: true },{ unarchive: true },{ markSeen: true },{ title }.phone:setRunnerOrder({ token, runnerIds })(API 56): Mike's order for his runners, from the phone's Settings (or the Mac's, through its runner:sync:runnerOrderandsync:setRunnerOrder, API 58, the owner key only), at most 50 ids, kept in the onerunnerOrderrow. The phone's new thread sheet offers a runner, starting on the first one online in it.phone:create({ token, text, runnerId?, cwd?, accountId?, model? }). With norunnerId, the first runner online and not draining in Mike's order (API 56); with no order, or none of it online, of the runners heartbeating with the owner key (byOwner) seen in the last 3 minutes, the one with the most threads (the Mac Mike works on), or"any", which only the owner key takes, so it waits for that Mac (docs/protocol/keys.md, "Runner keys").phone:quickAsk({ token, question, answer, sources?, askedAt, runnerId? })(API 10): a quick ask the phone has already answered out loud, kept as a thread.questionis 1 to 2,000 characters once trimmed,answer1 to 20,000,sourcesat most 10{ title, url },askedAtms since 1970. Targets a runner asphone:createdoes. The runner makes the thread with the exchange in it and no turn (docs/protocol.md, Sync,quickAsk), so a message sent to it later is an ordinary follow-up;phone:commandgives itsthreadIdoncedone.phone:loadEarlier({ token, threadId, beforeSeq }): the runner writes up to 50 text messages beforebeforeSeqas paged rows, then the command isdone;phone:threadthen returns them too. Paged rows go after a day, so the phone should ask again rather than expect them to stay.phone:registerDevice({ token, apnsToken, environment: "sandbox" | "production", pushKey?, platform? }).apnsTokenis the device token in hex.platform: "android"(API 66) says it is instead the phone's Firebase token (letters, digits and_ - :); the row keeps the name and gets aplatform, and its pushes go through the relay to Firebase, even from a backend with its own Apple key.platform: "webpush"(API 93, the Android app's F-Droid build) saysapnsTokenis a UnifiedPush endpoint, a public https address (no credentials, localhost or private ranges:convex/webPushEndpoint.ts), withwebPush: { p256dh, auth }its keys in base64url; this deployment posts its pushes there itself, no relay (docs/push-relay.md, "UnifiedPush"). The phone first gets the deployment's VAPID public key from the actionphone:webPushKey({ token })→{ vapid }, made once and kept inwebPushVapid. An iPhone sends no platform. A phone token keeps at most 5 registrations; a new one past that replaces its oldest. Revoking a token takes effect in that one small write (its phones get no more pushes at once,devices:targets); their rows are deleted after, 100 a run (tokens:dropDevices). A push arrives when a thread starts needing Mike, as{ aps: { alert: { title, body }, sound: "default", "thread-id": threadId }, threadId }for bundle idcom.mikecann.threadbear; the title is the thread's title and the body the question, the approval with its input line, or the reply.
Changes from the proposal: answers values are strings, not arrays (a
multi-select question's choices go in one string, comma-joined, which is
what the Mac app sends); view and lastActivityMs are on every row; a
title change was added to update.
Threadbear had none until now. Today's mirror was nearly clean only because it sends one-line tool rows: on 5 Nov the rules would have changed 2 of prod's 83,924 message rows and nothing in its other tables. Full sync would be a different story (about 220 of Mike's 200,000 events, tool output mostly), so this came first. The lessons are Agent Archive's:
-
Patterns alone fail, and on the worst leaks.
sed,cut,sortand truncation mangled keys past each version of its rules (Poddle's APNs key, a whole Google key). So there are three layers on the runner: where it came from (runner/src/withhold.ts, for the output ofenv list,.env,.p8and the like, unused until tool output goes up), values it knows (runner/src/secret-values.ts) and shapes (runner/src/redaction.ts, copied from Agent Archive with its tests). -
Scrub on both ends. An older runner sends what it sends, so the backend runs the same rules (
convex/redaction.ts, a byte-identical copy a unit test keeps equal). -
One way up. Agent Archive's tool output over 64 KB took a path the backend didn't scrub, and was never replaced. Here it's one wrapper on
ConvexSync.postand a generic walk over every field, and the backend'sclean()in each mutation. -
New rules need old rows rewritten, without re-sending everything. A bump made every Agent Archive daemon recheck about 3,600 files. Here nothing re-sends: bump
SCRUB_RULES_VERSIONand runnode runner/scripts/scrub-stored.mjs, a dry run unless--apply, which prints ids and counts only. -
Cleaning up isn't undoing. That cleanup also had to reach backups and exports, and the keys had been to the AI providers already. So the docs say to rotate, and never that the data is secret-free.
-
Scrub before cutting. Titles, previews, ask lines, the wake note, tool titles, quoted replies and check output are cut short on the runner, and a rule that needs a secret's end (a connection URL's
@, a closing quote, a length) misses half of one: on 6 Nov Daybreak found a wake note cut throughpostgres://alice:password@hostwith the password intact. So a cut never lands inside anything the scrub would take out (runner/src/safe-cut.ts, with the runner's known values too); it moves back to before it, leaving the runner's own copy unscrubbed. Taking a first line, a first sentence or the last part of something counts as a cut too. The wake note is scrubbed whole on the way up and only then cut.
Not scrubbed, on purpose: a command's words while it's on its way (a message from the phone or another Mac has to reach the runner as typed). Once a command is over, however it ended, its words are dropped from the row rather than scrubbed, so a value only the sender knew doesn't stay. One that's never taken stays as typed until a runner takes it. A value only the sending runner knows still goes up in the message row once the other runner has it, as that runner can't know to take it out. Identity fields aren't scrubbed either. A title or preview is cut before it gets here, so the rules and known values also take out a key's start at the very end of a text, and what's left of a key cut shorter than that is a few characters. A title that holds two different secrets can come out the same for two Pocket cards, so the second replaces the first, and likewise two pictures on one event whose file names hold secrets. That loses a card or a picture and leaks nothing, so it stays.
The on-device check (runner/src/secret-check.ts, runner/src/secret-check/)
is an experiment, off by default, that changes nothing. In a fake test on 5 Nov,
Apple's model caught what the rules can't (9 of 9 values with no known prefix) but
raised 6 false alarms in 19, and on a sample of Mike's real data it flagged 4.4%
of tool outputs and 8% of screenshots, so it counts first. If it's ever trusted,
it may only hold things back, never clear them: tool output is untrusted and can
tell the model to answer "clean". Linux has no such model, so a Linux runner has
the rules and the withhold list, and tb status says so.
Tool output, input and diffs for a runner with sync.full on (the plan, 5 Nov, is
docs/archive/full-convex.md; its step 4 built this, and docs/protocol/moves.md "Sync" has the
fields). Convex charges a read for the whole
document, so they're in eventBodies, not messages: no list ever reads one, and
each is fetched once, by seq, when someone opens that tool. Writes are the cost, plus
reading each row again to delete it after 30 days (pruneBodies), so about twice what
comes up. Bumping the rules re-sends nothing; scrub-stored.mjs covers this table,
but it's the one table where a run over everything costs real I/O.
| Question | Decision |
|---|---|
| Default | Off, and never offered: tb settings full on or Settings turns it on (Mike, 13 Nov; the offer went 16 Nov, as he never opens tool output) |
| Order | Cut reads first, scrubbing before any tool output goes up |
| Tool screenshots | Stay on the runner, fetched on tap, uploaded for a day |
| Pasted pictures | Sync by default, own line in the docs that they can't be scrubbed (lands after the launch video, thread 531a6ae0) |
| Pictures agents post or pin | Sync as they do today |
| Runner with no on-device model | Tool output uploads after the rules and withhold list, and tb status and setup say so |
| Secret check on Macs | Runs silently first, and can only ever hold things back |
| Tool output in Convex | Kept 30 days, then falls back to fetching from the runner (Mike, 5 Nov) |
| Other machines' threads | Show finished messages and the working line, with no streaming writes (Mike, 5 Nov) |
| Situation | What happens |
|---|---|
| The rules fail | Nothing uploads for that item |
| Runner too old to scrub | Backend pass still runs the rules but not the withhold list. Flagged in setup and tb status |
| Model busy, timing out or crashed | Hold and retry. Item stays on the runner and opens on tap |
| Model gone (Apple Intelligence turned off) | Treated as no model, shown in tb status |
| No model at all | Rules and withhold list, then upload, and say so |
| Convex unreachable or over limit | Mirror stops, runner carries on, retries with backoff. Nothing the app does waits on it |
| Off switch used | Today's mirror: text and one-line tool rows. Other machines' threads show the phone-style view, or the direct link while it exists |
- Scrubbing is not a guarantee, and a leaked key has to be rotated: copies have already gone to the AI provider, and Convex backups keep old rows.
- Convex limits are per team, so a stranger's other projects share them. On Free, going over stops writes and can later stop function calls. On Starter it bills $0.22 per GB of I/O (Convex docs, via thread 9b6113da).
- A remote thread shows finished events and the working line, not live typing.
For anything new that reads or writes Convex, from the I/O thread's report (9b6113da, 5 Nov 2026; first written in docs/archive/full-convex.md):
- Keep large output out of the row lists are read from. Convex charges for whole documents, so bodies get their own table and are fetched once by seq.
- Events never change: watch a tail of 20 to 30 rows, read older pages once,
and keep them on the client. If a tail starts past what's held, start over
rather than leave a hole (
web/src/transcript.tsdoes this). - Thread lists subscribe to rows changed since a time, with tombstones
(
threadIndexSince), not the whole inbox. - Never write streaming deltas, only finished events, in batches.
- Starts use a local record of what's up and never scan. No backfill unless someone asks for it.
- Clients drop subscriptions when hidden.
- Anything that writes on a thread change compares first.
A machine's own threads stay on loopback, so most of Mike's reading costs nothing.
The phone's deck of cards for when Mike's out (pocketCards, the pocket
tool in runner/src/threadbear-mcp.ts, ios/Threadbear/PocketView.swift).
Unlike the other lists, this table is the only copy: the tool writes to it
directly through sync:savePocketCard, and the phone removes cards directly
with phone:removePocketCard, not through a command. Both runners then share
one deck, and removing a card works while the Macs sleep. With sync off the
tool isn't offered. The phone saves what it last saw in pocket.json
(PocketStore), which is what makes the deck work with no signal.
The librarian keeps cards current too (pocketChanges in
runner/src/librarian.ts): each look sees the thread's own cards and can
update or remove them, or add one if the thread has none. What it can do is
checked in code, not left to the model: only that thread's cards, one added
card per thread and five a day, and no digits or codes that weren't in what
the look was shown. A thread with cards, or a message saying the user's going
out, is never skipped as a quiet catch-up, since "posted it" is short.
Measured for release card 6b (thread 4b8626ed) before the repo goes public, since every fork runs its own deployment and most will be on the free plan.
From convex.dev/pricing and docs.convex.dev/production/state/limits, read on 2 Nov 2026. The limits are per team, not per deployment.
| Free | Note | |
|---|---|---|
| Function calls | 1M a month | |
| Action compute | 20 GB-hours a month | |
| Database storage | 0.5 GB | a total, not monthly |
| Database I/O | 1 GB a month | "document and index data transferred between Convex functions and the underlying database" |
| File storage | 1 GB | a total |
| Data egress | 1 GB a month |
On the free plan the limits are hard: past them, "new mutations that attempt to commit more insertions or updates may fail", so the mirror stops. Starter has the same included amounts and then charges as it goes ($0.22 a GB of I/O, $2.20 a million calls, 1.3 times that outside US regions).
A runner holds a deploy key and a runner key, and neither can read its team's
usage (that takes a Convex login), so runner/src/convex-use.ts estimates it from
what it can count: the bytes of every mutation it sends, by day, kept for 30 days in
convex-use.json. On Mike's deployment (13 Nov, 15 minutes of prod logs) all reads
and writes came to 1.7 times what runners wrote, so the I/O estimate is twice what
was sent; stored tool output is what full sync sent in 30 days, plus a third. A first
month is scaled up from the days it has. tb status shows both, and past 70% of
Free's 1 GB of I/O or 0.5 GB of storage it warns (and says so to the app when it
connects), suggesting "sync": { "full": false } or a paid plan, and
"sync": { "usageWarning": false } to hide it on one. It's one runner's view of
limits that are the team's, so it can be under, and it never blocks anything. On
Free, Convex also emails as you near a limit.
Dashboard, team usage page filtered to threadbear, last 7 days (26 Oct to
2 Nov; the mirror went live on 28 Oct, so it's about 5 days), with
per-call numbers from npx convex logs --deployment mikec:threadbear:prod --success --jsonl, whose usageStats give each call's database bytes.
That's two runners (the M5 with about 500 threads and Bruce with 6), about
330 turns a day on the M5 alone, and the phone in daily use.
| last 7 days | steady rate | a month at that rate | free limit | |
|---|---|---|---|---|
| Function calls | 131K | 25K to 30K a day | about 850K | 1M |
| Database I/O | 4.78 GB | 1.2 to 1.4 GB a day | about 40 GB | 1 GB |
| Database storage | 67.7 MB | grows 8 to 10 MB a day | 0.5 GB | |
| File storage | 16.2 MB | 1 GB | ||
| Data egress | 46 MB | about 200 MB | 1 GB | |
| Action compute | 0.099 GB-hours | about 0.4 | 20 |
Database I/O by function, last 7 days: sync:otherRunnersThreads 3.48 GB
(73%), sync:setProjects 446 MB, sync:upsertThreads 182 MB,
phone:counts 96 MB, phone:threads 80 MB, sync:messageHeads 69 MB,
sync:setThreadIndex 68 MB, sync:appendMessages 63 MB,
sync:setAccounts 63 MB, sync:setPresence 59 MB, phone:projects 53 MB,
everything else under 31 MB each. Calls: sync:appendMessages 31K,
sync:otherRunnersThreads 27K, sync:upsertThreads 22K, sync:heartbeat
13K, sync:setThreadIndex 6.3K, sync:setAccounts 5.9K, phone:threads
4.5K, sync:setProjects 1.6K, the rest under 1.5K each. Storage is 93%
messages (55K rows; every message is kept). Push relay, Pocket, schedule
lease polling (sync:schedules, sync:claimSchedule) and project task
reads are all small: Notion reads never touch Convex.
What each cost comes from:
otherRunnersThreads: the live query a runner holds on the other runners'threadIndexrows. Every re-run reads all of them. Bruce's re-read the M5's 500 rows (about 220 KB) on every M5 index write and every heartbeat from either runner, about 400 times an hour, though nothing on Bruce shows them: it has no Mac app. That was 99% of this function's I/O. Fixed (below).setProjects: any project change (a thread's activity moves its project'slastActivityAt) rewrites every project row. Mike's 70-odd projects with long notes are about 460 KB a call. Small for a typical user.- Per turn, from the log sample: about 20
appendMessages(1 KB each), 10upsertThreads(3.4 KB), 5setThreadIndex(1.7 KB), 2setAccountsand 1setProjects. That's about 38 calls and, with a typical user's handful of small projects and one or two logins, about 80 KB of I/O. - Always, per runner: a heartbeat a minute (1.1 KB) and, while it watches, a re-run of the other-runners query on each heartbeat. That's about 2,900 calls a day whether or not anything happens.
- Growing with the thread count:
setPresencereads every thread row of the runner (about 4 KB each) each time Mike walks away from the Mac, looking for held pushes;phone:countsreads every hibernating and den row on each re-run;prunereads every row on each runner start.
Assumed: one runner with the Mac app open all day, 5 threads and 15 turns a day, three small projects, one or two logins, a phone opened now and then, about 10 pushes a day.
| a month | share of the free limit | |
|---|---|---|
| Function calls | about 110K (2,900 a day fixed, 600 from turns, 200 from the phone and pushes) | 11% |
| Database I/O, first month | about 250 MB (fixed 2.5 MB a day, turns 1.3 MB, phone about 2 MB, presence 2.5 MB) | 25% |
| Database I/O, after 6 months | about 650 MB, as presence and phone counts read 900 thread rows | 65% |
| Database storage | grows about 10 MB a month | half the limit after 2 years |
| File storage | a few MB (project pictures, shared and reply images) | under 1% |
| Data egress | about 10 MB | 1% |
| Action compute | about 0.03 GB-hours (pushes) | 0.2% |
It fits on day one with room to spare. The one thing that doesn't stay
comfortable is database I/O creeping up with the number of threads kept,
from setPresence and phone:counts reading every row; the backend cuts
below take that away.
A heavy single Mac (Mike's M5 on its own): about 450K calls a month (45%), about 5.5 GB of I/O (5.5 times the limit) and 300 MB more storage a month. Someone using it like that needs Starter, where that's about US$1.50 a month.
Two Macs, each with the app open didn't fit before API 29: each one's watch re-read all the other's index rows on every heartbeat and every index write, about 0.5 GB a day with 300 threads each. Now a change reads only the rows it touched (cut 2 below).
Done (runner only, 3506d3b): a runner watches otherRunnersThreads only
while a Mac app is connected, and for two minutes after it goes
(thread-index.ts). Bruce stops watching altogether. On last week's
numbers that takes Mike's prod from about 1.25 GB of I/O a day to about
0.2 GB, and about 18K calls a week off.
Backend changes (these deploy prod when they land on main; Mike said yes to 1 and 2 on 2 Nov, and 3 and 4 on 3 Nov):
- Done:
setPresencefinds held pushes with an index onpushHeldAtinstead of reading every thread row. Takes the growth out of a typical user's I/O. - Done (API 29): the runners list is its own query
(
sync:otherRunnersList), so a heartbeat doesn't re-run the read of the rows, and the rows are watched from where the last answer left off (sync:threadIndexSinceon an index ofupdatedMs, with a day's tombstones for deleted threads). A change now reads only the rows it touched, so two Macs fit as well as one. - Done (API 30):
phone:countsadds up aviewCountsrow per runner, whichupsertThreadsandremoveThreadskeep as threads move between views, rather than counting every hibernating and den thread. A runner'sprune(each start) counts again from scratch, so a count that drifted puts itself right, and a heartbeat makes a runner's first row. - Done (API 30): after the whole list once per start, the runner sends only
the projects that changed and the ones gone, with
sync:upsertProjects. Mostly Mike's own cost: his 70-odd projects with long notes were about 460 KB each time a turn moved one. - Done (API 40): a project's page reads its threads through
projectThreads, a small row per thread per project kept byupsertThreads(only when a thread is new, taken over or changes projects),removeThreadsandprune, withphone:projectThreadstaking the ones that joined last by an index onrunnerIdandprojectId(since API 82: a project id is only its runner's own, so another runner's thread can't join a project by using its id; and a runner key's project or thread can't take an id another runner has, as older apps look a project up by its id alone; and what the phones and website read has an id only as one runner's, the main Mac's if two have it (projectOwnersin phone.ts), whatever order things were stored in; and a moved thread leaves its old Mac's projects at the switch) and sorting that page by activity. The first version kept each link'slastActivityMscurrent, a patch on every turn, which tookupsertThreadsfrom about 4.1 KB to 7 KB a call (35 MB a day). A thread's projects are an array on its row, which can't be indexed, so the alternative was reading every thread, archived ones included. Threads from before API 40 are linked once per runner bysync:linkProjects, a page at a time, which a heartbeat starts (viewCounts.projectsLinked). The "22 threads" on a project is still the runner's own count, sent on its project row.
Once the cuts above were in, Mike's prod ran at about 215 MB a day (dashboard,
3 and 4 Nov, cumulative totals subtracted), and most of it was runner starts,
not live reads. The M5 started 12 to 15 times a day following main, and each
start rewrote all 710 thread rows and sidebar rows, read them all again to
prune, and read a row and a message per thread for message heads: about 9 MB a
start, over half of the total. What's sent is now remembered as hashes between
starts (runner/src/sync-cache.ts, sync-sent.json), with a full write every
3 days.
Also since then: a row whose only change is its preview or unread waits 20
seconds (73% of row changes on the M5, each re-running a 30 to 40 KB
phone:threads for every open client); a project moving only by
lastActivityAt goes every 10 minutes; sync:upsertAccounts writes one login
rather than all of them, and a new reading time alone isn't a change; the
website watches a 30-row tail, reads older pages once, watches pictures apart
(phone:images) and lets go of its live queries after a minute hidden. The
iPhone app watched phone:thread then, about 70 KB for each message that
arrives while a thread is open; it now watches an 80-row page of
phone:messages and reads older chunks once (9 Nov).
Since measured below: the inbox follows only what changed (API 43), and a reading copied from another runner goes up at most every 10 minutes, or at once if the login is blocked. The runner that made a reading still writes it at once.
Measured from npx convex logs --success --jsonl on 5 Nov. A runner start: 9.6
MB before, 0.39 MB after (5 rows written), though every 3 days one is still a
full write. The functions this changed fell from about 375 to 178 MB a day at
the rate of each hour's sample (0.86 h and 1.05 h, the second with more
starts), but these are busy daytime samples, not daily figures. By then most
I/O was live reads for open clients: phone:threads about 390 MB a day at that
rate (39 KB per re-run), phone:projects 165 MB (190 KB), phone:schedules 68
MB (157 KB). Those cost nothing with no client open. Also new that day: sync:sharedUsage (API 39) reads every login's row, and one
reading gets copied to the other runners' rows, so one change is three writes
and nine re-runs, about 70 MB a day at that rate.
Then, API 48. Measured from the logs on 5 Nov before the change: sync:schedules
168 KB a run, sync:sharedUsage 16 KB a run. A runner key's sync:schedules now
reads only its own rows, so Bruce and Hetzner no longer pay for, or re-run on, the
M5's claims, and every runner of 45 follows only the rows written since (sync:schedulesSince), so a run costs a row or two rather than the table. Finished one-offs already go after 7 days (KEEP_FINISHED_MS), and they're now read only when a runner starts. phone:projects reads
projectHeads rather than projects: 79 projects are 199 KB in projects, 143 KB
of it notes, and the fields a list needs are about 30 KB. Editing notes no longer
re-runs the list. sync:sharedUsage leaves out the caller's rows. A day's real
rate after this hasn't been measured yet.
Measured after API 48 landed (20 minutes of prod logs, 5 Nov, late at night with
almost no client open, so not comparable with the samples above): phone:projects
37 KB a run, sync:schedulesSince one whole read at 178 KB and then little,
sync:sharedUsage still 12 KB a run and the biggest at 78 runs, and about 184 MB/day
overall. A full day's rate is still to come. On 6 Nov sync:sharedUsage became a
query every 5 minutes instead of a subscription (each runner's watch re-ran on
every other runner's login write): 12 runs an hour per runner, about 14 MB a day
for four runners whatever they write.
Then, API 50 (6 Nov). The daily check's 15-minute samples had
sync:upsertProjects at 55 KB a call, 11 to 16 calls a quarter hour while
threads were busy: each update_project (or a project's thread count moving)
rewrote the whole row, and 16 KB of the Threadbear project's 17.7 KB is notes,
so each was about 34 KB read and 17 KB written. Notes now live in
projectNotes (convex/projectNotes.ts) and a runner of 50 sends them only
when they change, so a state update writes the small row alone. An older row's
notes move out the first time it's written; phone:project reads either.
phone:projectSearch and setProjectIcon read the smaller rows too.
An estimate for one Mac with the app open, 300 threads, 15 turns and half an hour of phone use a day: about 6 MB a day, 185 MB a month, under a fifth of the free 1 GB. Heartbeats are 2.4 MB of that and the three-day full write 1.3 MB, which grows with threads kept (about 13 KB a thread).
Confirmed live on 5 Nov: phone:threadsSince costs 2.4 KB a run against
phone:threadsAt's 37.5 KB. Next: sync:schedules, 160 KB a run, as each
schedule write makes every runner read all 113 rows, 61 of them finished
one-offs. It could follow only what changed, as the inbox does.
Not urgent: messages are kept forever, so storage grows about 10 MB a month for a typical user. Dropping the messages of threads archived more than a month ago would hold it flat if it ever matters.