Skip to content

Latest commit

 

History

History
812 lines (735 loc) · 49.9 KB

convex-backend.md

File metadata and controls

812 lines (735 loc) · 49.9 KB

Threadbear's Convex backend

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.

5. What's built (steps 1 to 5) and how to work on it

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) and pruneOld for crons.ts. convex/relay.ts (API 44) is the main Mac's runner reading another runner's thread (remoteTail, remoteMessages, remoteThread, and from API 87 picturesAtSeqs, 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 takes key: the deployment's RUNNER_KEY (the owner key, the main Mac's), or a runner key from runnerKeys, which acts as its own runner alone (convex/lib.ts runnerAuth, convex/runnerAccess.ts; the table of who may call what is docs/protocol/keys.md, "Runner keys"). tb runner add on the main Mac makes one for another Mac.
  • convex/phone.ts: the phone's API (section 6).
  • convex/push.ts (Node action) and convex/devices.ts: APNs over HTTP/2 with the team's token-based key, copied from Poddle's apns.ts. sync:upsertThreads schedules push:notify when a thread's needsYou goes from false to true (at most once per thread every 30 seconds, pushedAt on the row); the action re-reads the row, skips it if the Mac has seen it meanwhile, and sends pushText'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: each devices row keeps the token it registered with (tokenId, since 5 Nov 2026), revoking a token deletes its phones' rows, and devices:targets skips 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:dropUnlinked clears 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/verify in convex/http.ts and the relayChecks table. 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) and APNS_TOPIC (com.mikecann.threadbear). Each send's outcome goes in the pushHealth row (convex/pushHealth.ts); while none get through, the owner runner's heartbeat answers pushFailing and tb status says so. npx convex run push:test '{"body":"hi"}' --prod sends a test; npx convex run devices:list --prod shows the phones.
  • convex/tokens.ts: the token helpers, and issue, revoke, list to run from a terminal with npx convex run tokens:issue '{"name":"iphone","days":90}' (add --prod for the Sydney prod deployment). Only the SHA-256 of a token is stored, with a name and a kind (phone or browser). Since API 6 the Mac app issues them through the runner instead: sync:issueToken, sync:listTokens and sync:revokeToken take 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 with sync.url in runner.json and secrets/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.sync and a tb status line.
  • Tests: runner/test/unit/sync.test.ts (fake deployment) and runner/test/e2e/sync.e2e.test.ts, which starts npx convex dev on 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:heartbeat takes followProblem, a runner's word that it can't follow GitHub's main (docs/dev-tools.md); the main key reads it from sync: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.ts has API_VERSION, returned by sync:heartbeat and phone:me. Bump it when a client starts relying on something new, along with BACKEND_API_VERSION in runner/src/sync.ts (a unit test keeps them equal). The runner shows an older backend in tb status; the phone app says "Update it on the Mac" when the backend is below BackendCompatibility.minimumAPIVersion (ThreadbearKit).

6. The phone's API

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? }. pushOff is 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 is lastSeenAt older than 3 minutes (a runner that stopped for good has lastSeenAt of 1970). Since API 45 also release?, startedAt?, threadCount?, pressure? (memory or disk while 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), with placed: true on the ones in the saved order and main: true on 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 no runnerId), 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, from scheduleWakes: 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, follow phone:schedules). phone:schedules costs 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, and phone:watchRunners({ token }) says someone is (docs/protocol/moves.md, Sync, "Runner figures").
  • phone:threads({ token, view: "inbox" | "hibernating" | "den" }) → rows, newest lastActivityAt first; the den is capped at 100. A row is threadId, 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. asks and asksSeq (API 14) are the open card of the agent's end_turn asks ({ action, why?, reply?, options?, suggested?, links?, ticked? }, web links only), and next a finished turn's suggested follow-ups, for the done card. needs (you | nothing), pendingReviews and waitingForRoom ({ until, accountId? }) (API 15) are what the phone needs to sort threads into the Mac sidebar's sections: with phone:wakes it 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's Question shape.
  • 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 to phone:threads for 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 (origin is "phone" for one sent from the phone, "schedule" or "runner" as in the protocol). The row's earliestSeq is 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 newest limit (default 50, at most 2000; NaN or an infinity is refused, here and in every limit) or the limit before beforeSeq. Without tools it looks past at most 4,000 tool rows for the page's text ones, then says hasMore. Every message is kept since API 2, and with tools: true there's one row per tool call too (role: "tool", a one-line text such as "Run the unit tests" or "Edited ~/dev/x.ts", and toolKind). 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 with notes: 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:thread never has them. A user's message that answered the open card's asks carries answers (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, with beforeSeq (web/src/transcript.ts). The iPhone does the same with an 80-row live page and chunks of 200 (MessageHistory.swift), watching phone:images from the first row read once for pictures that finish uploading late; builds before 1.0.5 raise limit as you scroll back, re-reading up to 2,000 rows for each new message (37.6 MB on 8 Nov), which is why PAGE_MAX stays 2,000 until they're gone. phone:thread stays 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 after since in any view, each with updatedMs, and threads gone or out of the lists. The client merges them and asks again from the newest updatedMs less 5 seconds (a mutation can commit just after one stamped later), so each run reads only what changed; more says to load the list again. The website and the iPhone follow the inbox this way; hibernating and archived stay on phone:threads, as they're rarely written.
  • phone:threadRow({ token, threadId }) (API 37) → the thread's row alone, for a client that reads messages with phone:messages.
  • phone:images({ token, threadId, from }) (API 37) → the thread's pictures from that seq on, for a client passing noImages: true to phone:messages.
  • phone:command({ token, commandId }) → { state: "pending" | "taken" | "done" | "failed", note?, threadId?, result? }. result (API 62) is a slashCommands command's answer, the thread's list.
  • phone:waiting({ token, threadId }) (API 57) → the thread's send commands 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) → true if the send was still pending and is now failed with note "Cancelled" (its photos deleted), false once the runner has taken it. sync:takeCommand checks pending in 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 a press command with { buttonId }. Its resultThreadId is the thread the button started or messaged. phone:messages rows carry buttons, 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 its threads.commands list as the command's result (kept by sync:finishCommand as for a call); an older runner fails it as unknown.
  • phone:designReviews({ token, threadId, reviewId? }), phone:respondReview({ token, threadId, reviewId, revision, draft }) → commandId, and phone: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's result); 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 an interrupt command, 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's approvals.respond with decision answered takes it; message is 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 a pendingApproval of kind secret, sealed to that card's key so only the runner can open it (docs/protocol/threads.md, "Secrets"). sealed is dropped from the command once the runner has finished it.
  • phone:update({ token, threadId, change }) where change is 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:runnerOrder and sync:setRunnerOrder, API 58, the owner key only), at most 50 ids, kept in the one runnerOrder row. 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 no runnerId, 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. question is 1 to 2,000 characters once trimmed, answer 1 to 20,000, sources at most 10 { title, url }, askedAt ms since 1970. Targets a runner as phone:create does. 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:command gives its threadId once done.
  • phone:loadEarlier({ token, threadId, beforeSeq }): the runner writes up to 50 text messages before beforeSeq as paged rows, then the command is done; phone:thread then 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? }). apnsToken is 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 a platform, 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) says apnsToken is a UnifiedPush endpoint, a public https address (no credentials, localhost or private ranges: convex/webPushEndpoint.ts), with webPush: { 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 action phone:webPushKey({ token }) → { vapid }, made once and kept in webPushVapid. 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 id com.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.

Secret scrubbing (API 47, 5 Nov 2026)

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, sort and 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 of env list, .env, .p8 and 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.post and a generic walk over every field, and the backend's clean() 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_VERSION and run node 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 through postgres://alice:password@host with 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.

Full sync (API 52, 6 Nov 2026)

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.

Decided so far

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)

What happens when something fails

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

Limits to say out loud

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

Read rules

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):

  1. 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.
  2. 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.ts does this).
  3. Thread lists subscribe to rows changed since a time, with tombstones (threadIndexSince), not the whole inbox.
  4. Never write streaming deltas, only finished events, in batches.
  5. Starts use a local record of what's up and never scan. No backfill unless someone asks for it.
  6. Clients drop subscriptions when hidden.
  7. 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 Pocket (API 19)

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.

Usage and the free plan (2 Nov 2026)

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.

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

Warning before the limits (13 Nov 2026)

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.

What Mike's prod used

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' threadIndex rows. 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's lastActivityAt) 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), 10 upsertThreads (3.4 KB), 5 setThreadIndex (1.7 KB), 2 setAccounts and 1 setProjects. 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: setPresence reads every thread row of the runner (about 4 KB each) each time Mike walks away from the Mac, looking for held pushes; phone:counts reads every hibernating and den row on each re-run; prune reads every row on each runner start.

A typical user: one Mac, a few threads a day

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

Cuts

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):

  1. Done: setPresence finds held pushes with an index on pushHeldAt instead of reading every thread row. Takes the growth out of a typical user's I/O.
  2. 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:threadIndexSince on an index of updatedMs, 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.
  3. Done (API 30): phone:counts adds up a viewCounts row per runner, which upsertThreads and removeThreads keep as threads move between views, rather than counting every hibernating and den thread. A runner's prune (each start) counts again from scratch, so a count that drifted puts itself right, and a heartbeat makes a runner's first row.
  4. 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.
  5. Done (API 40): a project's page reads its threads through projectThreads, a small row per thread per project kept by upsertThreads (only when a thread is new, taken over or changes projects), removeThreads and prune, with phone:projectThreads taking the ones that joined last by an index on runnerId and projectId (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 (projectOwners in 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's lastActivityMs current, a patch on every turn, which took upsertThreads from 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 by sync: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.

The restart cost (5 Nov 2026, API 37)

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.