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 sendCLI always sends with modequeue, so an answer to a busy orchestrator waited for the whole turn to end. The T3 MCP toolt3_thread_sendtakes amode;scripts/mastermind-fleet/t3-steer.mjscalls it withauto, which T3 resolves in one step: steer the running turn, or start the idle thread. If T3 still answersqueued(the turn cannot take input at that instant) and another run is active, the helper promotes the queued message witht3_queuepromote_to_steer. - Receipt.
steered,startedorqueued, plus the message and run ids.deliveredappears 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-idis passed as T3’sclientRequestId. 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-askusesiris-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/mcpendpoint refusest3 auth session issuebearers; 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 againsthttp://127.0.0.1:<port>only: the origin comes from~/.t3/userdata/server-runtime.jsonand anything but loopback is refused before a request is made. A five-minute local session minted by thet3CLI approves it and is revoked in afinally. 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 localt3CLI, 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
Copyprivate-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 /repliesfirst 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 401mfa_requiredwithmaxAgeSeconds, 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 withmm-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),deliveredwithsteered,startedorqueued,failedwith a closed code (bad_signature,expired,unknown_thread,rate_limited,thread_refused,unavailable) orexpired. The machine signs eachdeliveredorfailedoutcome 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 sayssteered.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 reportsunavailable. - 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.jsonlon 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 callssendPoke(scripts/mastermind-fleet/poke.mjs); owner clients read them fromGET /api/v1/mastermind/fleet/liveor 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 503machine_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.
projectIdkeeps one project’s threads andprojectId=nonethose in no project;statekeeps one of the four states;totalandnextCursorcount the filtered threads. A state is the newest run’s status:preparing,queued,startingandrunningarerunning,waitingandfailedare themselves, everything else isidle. - 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 asunassigned: the scratch project is left out ofprojectsand oftotal, its threads carry noprojectIdorproject, andprojectId=nonelists them. - When the owner last wrote.
include=ownerReplyaddslastOwnerReplyAtto 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=noneandlastOwnerReplyAtexist for the bridge machine only. For a linked machine the first two answer 422unsupported_for_linked_machineand the third is left out;projectIdandstatefilter 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 answersunavailablerather 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 answerunavailablewithout 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.
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
CryptoKeyin 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_mfameans 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
sentthe composer sends nothing else. Its receipt is read again when the owner socket delivers areceiptframe for it, and onretry(), 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),deliveredwithsteered,startedorqueued, andfailedorexpired.
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).