Skip to main content
Product decision (owner, 21 Nov 2026): every message Mastermind sends into a fleet thread is steered. It is injected into the running turn, or starts a turn when the thread is idle. It is never queued behind a running turn, and that is the default with no opt-out. When steering is impossible the receipt says queued; nothing claims a delivery that did not happen. Scope: owner answers relayed by the orchestrator’s ask tool (iris-ask) and replies the owner posts into a thread from Mastermind web or the mobile app. Out of scope: attachments, commands and new threads. Only text reaches an existing thread.

Steered delivery

  • Why. The t3 thread send CLI always sends with mode queue, so an answer to a busy orchestrator waited for the whole turn to end. The T3 MCP tool t3_thread_send takes a mode; scripts/mastermind-fleet/t3-steer.mjs calls it with auto, which T3 resolves in one step: steer the running turn, or start the idle thread. If T3 still answers queued (the turn cannot take input at that instant) and another run is active, the helper promotes the queued message with t3_queue promote_to_steer.
  • Receipt. steered, started or queued, plus the message and run ids. delivered appears only for an interrupted send that was later found in the thread, where the manner is no longer knowable. The message text is never printed or logged.
  • Idempotency. --request-id is passed as T3’s clientRequestId. T3 remembers that id per MCP sign-in (bearer), so the helper keeps its own send journal (~/.local/share/fleet-sync/t3-steer-journal.jsonl): a request is recorded with a fingerprint of the bearer it used before it is sent, and with its receipt once it lands. Every decision and write happens under one lock file and re-reads the journal, so two processes cannot both claim an id. A retry returns the recorded receipt and sends nothing. A retry of a send that never reported back (a timeout, a crash) first looks for the message in the thread’s timeline (T3 derives the message id from the request id; up to 500 newest items) and sends only when it is not there. If that earlier attempt ran under another bearer, the retry also waits out a 60-second window first (steer_in_flight). iris-ask uses iris-ask:answer:<id> for owner answers.
  • Known limit. T3 does not show a steer it has accepted but not yet injected (the target is in the middle of a tool call), neither in the timeline nor in the queue. A retry in that window is sent again with the same request id: under the same bearer T3 recognises it and delivers once (measured); under a new bearer it arrives twice. The same holds if the first copy has scrolled past the 500 newest timeline items. The helper accepts that over losing an owner message.
  • Sign-in (scripts/mastermind-fleet/t3-mcp.mjs). The local /mcp endpoint refuses t3 auth session issue bearers; it accepts only an MCP client session from T3’s OAuth endpoints (/oauth/mcp/register, approval, decision, token; authorization code with PKCE). The helper runs that flow against http://127.0.0.1:<port> only: the origin comes from ~/.t3/userdata/server-runtime.json and anything but loopback is refused before a request is made. A five-minute local session minted by the t3 CLI approves it and is revoked in a finally. The MCP token is cached in ~/.local/share/fleet-sync/t3-mcp-token.json, bound to origin and access level and replaced a minute before expiry, and one fresh sign-in is made when the server stops accepting it.
  • Access level. full-access: T3 refuses a sender narrower than the target thread, and orchestrator threads run with full access. The cached token therefore carries the same reach as the local t3 CLI, which any process of this user can already invoke.
  • Private files (scripts/mastermind-fleet/private-files.mjs). The token, the journal and the bridge files are opened without following symlinks and without blocking on a FIFO, read only when they are regular files this user owns with no group or world access, and written through an exclusively created mode-0600 temp file.
  • Limits. Existing threads only (a thread id, optionally a linked machine’s environmentId), text only up to 16,000 characters. Ids never start with a dash. Failures are a closed set of codes on stderr.

Install and rollback

Copy private-files.mjs, t3-mcp.mjs and t3-steer.mjs from main next to the publisher in ~/.local/share/fleet-sync/bin/. iris-ask calls the helper for every thread message and falls back to the t3 thread send CLI when the helper file is missing or fails before anything was sent (server not running, sign-in refused, journal unusable). Removing the three files restores the old queueing behaviour. A failure that may have happened after the send is reported as failed and retried with the same request id; it is never resent through the CLI.

Verify

node t3-steer.mjs <threadId> "ping" --request-id test-1 --json against a thread that is mid-turn prints "delivery":"steered"; repeating the command prints the same receipt and the thread shows one message. Measured on the orchestrator Mac on 21 Nov 2026: about 0.6 s with a fresh sign-in, under 0.1 s with the cached token.

Regression coverage

scripts/mastermind-fleet/t3-mcp.test.mjs and t3-steer.test.mjs: PKCE sign-in with the verifier matching its challenge, loopback-only origin, the approving session always revoked and never sent to another endpoint, the code taken only from the helper’s own redirect path and state, the private origin-bound token cache, symlink and FIFO refusal, one re-sign-in on 401, one auto call with the idempotency key, a retry that never sends twice even after a new sign-in, an interrupted send resolved from the timeline under the same or another bearer (including a later page), two processes unable to claim one request id, no send when the journal is locked or cannot be written, promotion of a queued message, a truthful queued receipt, closed error codes and input validation before any call.

Fleet bridge

The push path that carries an owner reply from Mastermind to its thread in about a second, in place of the publisher’s 15-second poll.
  • Who may post or read. Only the fleet owner (isFleetOwner: the owner allowlist plus the root Mastermind permission) on every owner route: replies, receipts, live state and the owner ticket. The machine’s ticket route is not an owner route; it takes the publisher’s signed request.
  • Second factor, for posting. POST /replies first asks the platform’s account check (checkRequiredAccountMfa) about exactly the user and credential the route admitted, so a recovery, a removed factor, a banned account or a proof issued for someone else refuses the reply on that very request. On top of that the session that sends the reply must carry a second-factor proof at most 30 minutes old by default (MASTERMIND_REPLY_MFA_MAX_AGE_SECONDS, 60 seconds to 12 hours). An app session carries the proof inside its signed token; a browser session carries it in its own verified claims. Without it the route answers 401 mfa_required with maxAgeSeconds, and the client runs the existing Tuturuuu MFA flow and retries with the same Idempotency-Key. Reading a receipt or live state needs the owner but no fresh proof: neither returns reply text.
  • What Web seals and signs. The text is encrypted for the machine (AES-256-GCM, bound to the reply id and machine) with a key derived from the fleet publisher secret, and recorded as a keyed digest (HMAC-SHA-256), not a plain hash that guesses could be tested against. Web then signs the reply id, machine, environment, thread, actor, issue and expiry times and that digest. The first signed line is mastermind-fleet-reply-v1, so the signature fits no publisher route and no publisher signature fits a reply. The store Worker never holds the secret: it relays and keeps ciphertext only, and cannot forge, alter or read a reply.
  • What the machine checks (scripts/mastermind-fleet/bridge-core.mjs). The signature in constant time, that the reply is addressed to this machine, that it is in date (at most 24 hours, five minutes of clock skew), that the sealed text opens and matches the signed digest, that the id was not settled before (the ledger answers a replay with its first receipt and sends nothing), and a local limit of 6 per thread per minute and 60 per hour. Then it steers with mm-reply:<id> as the request id. T3 only accepts an existing thread, and the frame set is closed: there is no command, attachment or new-thread frame.
  • Receipts. sent (stored, waiting for the machine), delivered with steered, started or queued, failed with a closed code (bad_signature, expired, unknown_thread, rate_limited, thread_refused, unavailable) or expired. The machine signs each delivered or failed outcome with an Ed25519 key derived from the fleet secret. Web hands the store the public half with the reply, so the store drops an acknowledgement that does not verify and keeps the reply pending for the real machine; Web verifies the signature again, under the key it derives itself, before it reports the outcome. So neither the store nor anyone holding its token can make a reply look delivered, or make the bridge drop one. The POST waits up to 2.5 seconds for the machine, so the usual answer already says steered. GET /api/v1/mastermind/fleet/replies/<id> reads it later. Receipts on the owner socket come straight from the store: treat them as a signal to read the receipt route, not as the verified state.
  • Offline machine. The reply stays in the bridge outbox for 24 hours (at most 200 pending) and is replayed in order, 50 per hello, when the machine connects; after a full batch the daemon asks for the next one. When the local T3 server is down the daemon leaves the reply in the outbox and asks again every 15 seconds for 10 minutes before it reports unavailable.
  • Audit. Each reply leaves a record in the bridge (who, when, machine, environment, thread, keyed digest of the text, outcome; kept 90 days; the sealed text is dropped once the reply settles) and a line in ~/.local/share/fleet-sync/bridge-replies.jsonl on the machine. Web logs the same fields with the session id. None of them contains the text.
  • Live notices. The same socket carries pokes: a topic from a closed set (state, usage, status, threads), a revision and a time, never content. A publisher calls sendPoke (scripts/mastermind-fleet/poke.mjs); owner clients read them from GET /api/v1/mastermind/fleet/live or a listen-only owner socket (POST /api/v1/mastermind/fleet/live/ticket) and refetch the topic through its own owner route.

Thread list and history

Product decision (owner, 21 Nov 2026): the owner can list, search and read every fleet thread from Mastermind, and nothing about those threads is kept in the cloud. The list and each page of history are fetched from the orchestrator Mac on demand; while it is not connected the routes answer 503 machine_offline, a state of its own for clients to show.
  • Who may read. The fleet owner, on an account the platform’s second-factor policy still accepts (checkRequiredAccountMfa), for every route in the table. Reads do not need the fresh proof a reply needs.
  • Grouping and filters. projectId keeps one project’s threads and projectId=none those in no project; state keeps one of the four states; total and nextCursor count the filtered threads. A state is the newest run’s status: preparing, queued, starting and running are running, waiting and failed are themselves, everything else is idle.
  • Threads in no project. T3 files a thread that belongs to no project under its own scratch project (titled “No project”, rooted at ~/.t3/scratch). Mastermind reports those threads as unassigned: the scratch project is left out of projects and of total, its threads carry no projectId or project, and projectId=none lists them.
  • When the owner last wrote. include=ownerReply adds lastOwnerReplyAt to each thread the owner has written in: the later of a message the owner wrote in T3 and a reply delivered through this bridge. A message the owner wrote is one T3 marks as created by the user: typed, or given as the answer to a question the thread asked. A scheduled task, a notification, a delegated result and T3’s own prompt to resume a run after a usage limit do not count, and neither does imported history, which is not the owner being active in the thread. It is looked for among the thread’s 400 newest user messages. Bridge replies are taken from the bridge’s own ledger of delivered replies, never from the shape of a message id, so a message an agent sends does not count however it is named.
  • Bridge machine only. The project list, projectId=none and lastOwnerReplyAt exist for the bridge machine only. For a linked machine the first two answer 422 unsupported_for_linked_machine and the third is left out; projectId and state filter a linked machine through T3’s own list filters, where the scratch project is a project like any other.
  • End to end. Web seals the arguments of each read and signs the request (first signed line mastermind-fleet-rpc-v1, valid for 30 seconds); the machine verifies it, checks the type and range of every argument, and seals the answer for that one request. The store Worker relays both as ciphertext, stores neither, and a read it cannot deliver at once is refused, not queued. Web refuses an answer that does not open for the request it sent or does not fit the closed shape for its kind, so no field outside that shape reaches a client.
  • Where the answer comes from. A read of the bridge machine itself is answered from T3’s own projection database, opened read-only the way the publisher opens it (scripts/mastermind-fleet/bridge-local.mjs): the list, title search, project grouping and history take milliseconds there, where T3’s list tool takes seconds on a machine with ten thousand threads. The database is opened read-only with a half-second busy wait, and a database that is busy, missing or not in the expected shape answers unavailable rather than a partial list. The reads that look up rows per thread (grouping by project, the state filter, owner-reply times) first check that an index covering the rows they read exists, and answer unavailable without it: a statement cannot be interrupted once it runs, and without the index it would hold the bridge for minutes. The list of machines, and any read of a linked machine, go through the T3 MCP read tools (t3_environment_links, t3_project_list, t3_thread_list, t3_thread_read) and takes a few seconds. No write tool is reachable from a read.
  • What leaves the machine (scripts/mastermind-fleet/bridge-rpc.mjs). Titles and project names pass the fleet scrubber. Message text keeps its layout, paths and links, which the owner already sees in T3, but credentials are replaced with [redacted]: PEM blocks, passwords inside URLs, named values ("api_key": "…", PASSWORD=… to the end of the line), bearer and basic values, JWTs, provider key prefixes, hex of 32 characters or more (a 40-character commit id named as one stays), 40-character mixed keys and long base64. At most 16,000 characters of a message are scanned, each message is capped at 4,000 characters and a page at 240 KiB, dropping the oldest messages first. Only user and assistant messages are included; tool calls, command output and reasoning are not.
  • Read markers. A count per thread, machine and environment, kept in the Mastermind store for the 300 threads touched last. It only moves forward and holds no content.
  • Limits. 60 list or history reads a minute per session, 8 reads in flight at the bridge, each charged against the bridge’s daily operation budget, each waiting at most 12 seconds for the machine.
Regression coverage: scripts/mastermind-fleet/bridge-rpc.test.mjs (protocol parity with Web, request signature, addressee and lifetime checks, silence toward an unverifiable request, argument types and ranges, each read’s closed answer shape, read tools only, a local read without any T3 call, the page size cap, closed failure codes, an answer that opens only for its own request), bridge-local.test.mjs (order, state, literal search, paging back through history, deleted and archived threads, linked machines, grouping by project with the 200 cap, the scratch project as threads in no project, the project and state filters, the state filter agreeing with the state shown for every run status, owner-reply times from typed messages and the reply ledger only, the 400-message window, a missing index refused), bridge-rpc-projects.test.mjs (projects from the database only and for this machine only, filters passed to a local read and mapped to T3’s filters for a linked machine, argument checks), a busy, missing or unexpected database answering unavailable, transcript-scrub.test.mjs (the credential corpus, ordinary text left alone, bounded scanning of a huge message), apps/web/src/app/api/v1/mastermind/fleet/fleet-threads.test.ts (owner and account admission on every read route, sealed and signed arguments, malformed queries, the project, state and owner-reply filters, what a linked machine does not support, the machine states, forged, reflected or misshaped answers refused, read markers) and apps/mastermind-store/src/bridge.test.ts (the relay: offline, the right machine only, a large answer, timeout, the stop fence, nothing stored).

Clients

Screens do not call these routes by hand. Each surface has one typed data layer, and every body is checked against the contract before it is shown.
  • On-device list cache. Product decision (owner, 21 Nov 2026): the last thread list is cached on the device, encrypted, and nowhere else, so the list renders at once and shows its age while the machine is offline. The cache holds the first 50 threads of the 6 lists saved last (a list is a machine with at most one project and one state; searches and history are not cached), each with the time it was saved, which the screen shows as the list’s age. It is sealed with AES-256-GCM and bound to the signed-in account. In a browser the key is a non-extractable CryptoKey in IndexedDB: a copy of the database opens nowhere else, but any script running on the Mastermind origin can use the key, so the cache is no defence against script injection there. On a phone the key lives in the device keystore and the sealed file in the app cache directory.
  • One account at a time. A list is returned only to the account that is still signed in when the read finishes, also when the account changed while the read waited. Clearing takes the account to erase, so a sign-out clears the account that signed out, whoever is signed in when it runs. The in-memory cache used off phones keeps a separate set of lists per account, with the same limits.
  • When storage fails. No cache call throws. While a keystore, database or cache directory cannot be reached, a read finds nothing cached and a write saves nothing, so what is stored stays as it is. A record that is damaged, oversized, sealed for another account or whose key is gone reads as empty and is removed. One cached list that does not fit the contract is dropped; the others stay.
  • One reply, one key. A reply gets its idempotency key when it is first sent and keeps it through every retry, a second-factor step-up included. needs_mfa means the session’s proof is too old for a reply, whatever its age: the owner verifies again and the same reply is sent again, text and key kept. Offline, timeout, rate limit, unavailable and an unreadable answer can be retried under the same key; a refusal, a reply the machine refused and an expired reply cannot. Sending the same text again while its reply can still be resent is that reply again, not a new one; other text is a new reply.
  • A reply held for the machine. While a reply is sent the composer sends nothing else. Its receipt is read again when the owner socket delivers a receipt frame for it, and on retry(), which is the way forward when no frame arrives. Resetting the composer does not withdraw the reply: it stays in the outbox and is delivered when the machine takes it.
  • Delivery states shown. sent (held for the machine), delivered with steered, started or queued, and failed or expired.
Regression coverage: packages/internal-api/src/mastermind-threads.test.ts (queries, bodies, refusals as states, misshaped bodies refused, change notices on the live read, any project id on a thread), apps/web/src/app/api/v1/mastermind/fleet/fleet-threads.test.ts (each route’s answer fits the typed client), apps/mastermind/src/fleet/thread-cache.test.ts and apps/mobile/test/features/mastermind/fleet/fleet_thread_cache_test.dart (nothing readable at rest, per-account binding, an account change during a read, clearing one account on a cache two accounts used, storage that cannot be reached neither removed nor replaced, damaged records, one unreadable list among good ones, limits, values read back from another realm), apps/mastermind/src/fleet/thread-reply.test.ts and fleet_thread_reply_cubit_test.dart (the same key through a step-up, a retry and the same text sent again, one reply at a time, a held reply read again on retry and left in the outbox by a reset, a failing listener, the delivery states), fleet_thread_repository_test.dart (queries, parsing, refusals).

Bridge daemon

scripts/mastermind-fleet/bridge.mjs runs under launchd as com.tuturuuu.mastermind-fleet-bridge (KeepAlive, ThrottleInterval 10), as node bridge.mjs --origin https://tuturuuu.com from ~/.local/share/fleet-sync/bin/, next to the publisher and with the same publisher-secret and config.json. Each connection needs a single-use, 60-second ticket from POST /api/v1/mastermind/fleet/bridge/ticket, signed like every publisher request; the ticket travels as the second WebSocket subprotocol, never in the address. Reconnects back off with jitter, from about a second up to a minute, and reset after a connection held for 30 seconds. An idle connection sends pings, which the bridge answers without waking, and one hello every ten minutes as a safety net for a lost push or a refused replay (144 a day). Beyond that the daemon says hello on connect and while a reply is waiting for the local T3 server or the last replay came back full. It logs counts and closed codes only. Install: copy bridge.mjs, bridge-core.mjs, bridge-rpc.mjs, poke.mjs, bridge-local.mjs, private-files.mjs, t3-mcp.mjs and t3-steer.mjs from main into the bin folder (scrub.mjs and fleet-state.mjs are there with the publisher), add the launchd plist, then launchctl bootstrap gui/$(id -u) <plist>. Install only after Web and the store Worker from the same commit are deployed. Rollback: launchctl bootout gui/$(id -u)/com.tuturuuu.mastermind-fleet-bridge and remove the plist; replies then stay sent and expire, and the publisher’s answer poll is unaffected. The operator stop fence of the store Worker stops the bridge too (see Mastermind store).

Regression coverage

apps/mastermind-store/src/bridge-engine.test.ts (idempotent enqueue, conflicting reuse of a key including another environment, acknowledgement only from the addressed machine with its signature kept verbatim, outbox order and expiry, per-thread and hourly limits, the daily operation budget including charged replays and counted acknowledgements, the stop fence, single-use tickets, poke revisions, retention), apps/mastermind-store/src/bridge.test.ts (the emitted Worker in workerd: ticket admission, push and acknowledgement inside the wait, offline replay once, one replay per interval, a socket flooding any kind of message retired, a forged acknowledgement leaving the reply pending for the real one, an unsigned acknowledgement and a plain-text reply dropped, one socket per machine, owner fan-out with listen-only owner sockets, the fence, the budget, malformed sends), apps/web/src/app/api/v1/mastermind/fleet/fleet-bridge.test.ts (owner only, the account check asked for the admitted principal and credential and its refusals honoured, the second-factor window on both session kinds, the sealed and signed envelope, delivered or failed only with the machine’s signature, closed errors, the audit line without text, signed and once-only ticket requests) and scripts/mastermind-fleet/bridge.test.mjs and bridge-daemon.test.mjs (protocol parity with Web, signature, sealed text, addressee and lifetime checks, replay from the ledger across a restart, closed refusal codes, the retry window, the local limit, pokes, ticket signing, the socket loop, an idle connection that only pings and makes its ten-minute safety request, a full replay batch followed by another request and bounded backoff).