Skip to main content
Status: Slice 0 is the transitional desk rule. Slice 1 defines the database foundation. Slice 2 adds the Fleet API for live access, digest publishing and scoped reads. Slice 3 adds intent submission, requester receipts and desk identity linking. Slice 4 adds the desk-owner admission fence and desk digest reads. Slice 5 adds the dry-run consumer and retention purge in Cron Control. Slice 6 adds the Mastermind web Fleet access area and grantee admission. Slice 7 adds the Mastermind mobile Fleet access view. Every surface stays inert until the activation steps run. Later slices need the approvals in the implementation plan. Fleet access lets named teammates (for example an operations lead) read the state of the agent fleet, ask about it, and steer work without routing every request through the platform owner. Agents never act on a teammate’s free text. Every request becomes a typed, authorised intent, and the orchestrator consumes only intents the access rules allow.

Scope and default

  • Scope: every surface that serves fleet data or accepts fleet requests from someone other than the owner. That covers the Mira desks (WhatsApp, Zalo, Discord), the Fleet area of Mastermind web, the Fleet view of the Mastermind mobile section, the /api/v1/fleet/** API and the intent queue the orchestrator reads.
  • Default: deny. Nobody but the owner has fleet access until the owner grants it. A grant names one person, one tier, a set of projects and an optional expiry.
  • Owner: the configured owner UUID that also holds a live explicit root manage_mastermind grant (see Mobile Mastermind). Both checks are required. The Owner tier cannot be granted.
  • Boundary with Mastermind: a fleet grant admits only Fleet routes and /api/v1/fleet/**. Existing Mastermind shell data, hub, push and mobile Mastermind routes keep their owner-only gates.
  • Supplements, never replaces: fleet approval adds to existing custody, review, CI and release gates. An approved deploy intent still needs every gate the release runbooks require.
  • Exceptions: the time-limited Slice 0 Observer described below.

Tiers

Tiers are ordered. Each tier holds every capability of the tiers below it, but only inside the projects its grant names. A grant may hold fewer capabilities than its tier’s ceiling, never more; the database rejects a grant above its ceiling. approve.migration stays Owner-only because production migrations need explicit owner approval. Credentials, secrets and DNS have no fleet capability: no tier can ask the fleet to read, rotate or reveal them.

Intent kinds and binding

Each intent kind defines its request capability, its approval capability and a strict payload schema made of enumerated values and server-resolved identifiers. An Observer ask executes as a read. Every Observer steer request is filed as intent.request and needs Owner approval of the exact action.
  • Authoritative project: the server resolves each target (lane, thread, repository path, deployment) to its owning project from the project catalog. A request naming a target outside the requester’s projects is refused, even when the request labels another project. The catalog’s target mapping carries a version number.
  • Immutable approval: an approval binds one intent ID and a hash of the canonical action: kind, authoritative project IDs, every execution parameter, resolved targets, environment and commit SHA. Project ownership is re-resolved before dispatch, and any drift voids the approval.
  • Desk requests: a desk-filed request never approves itself. Low- and medium-risk requests from a desk wait for approval even when the requester holds approve.low. Desk-filed comment and status_question intents need no approval and still execute.
  • Owner at a desk: desk operations resolve a live grant row, and the Owner tier is never granted. The Owner needs a non-Owner grant, whose projects, capabilities and caps then apply, to use a desk.
  • High risk: needs an approver other than the requester and an interactive step-up (fresh tuturuuu.com sign-in within five minutes). Chat channels can file high-risk requests but cannot approve them.
  • Critical actions (migration, billing, access, fleet stop) stay Owner-only and outside the intent queue’s self-service paths.

Protections

  1. No secrets or private data. Fleet answers come from a digest of schema-validated status fields (lane, project, state, ETA, short SHA, release title, readiness item). Titles and readiness items are controlled values or explicitly approved display strings. Aggregates are computed only from the caller’s authorised projects, and the digest is filtered by those projects before any answer. Receipt reads are scoped to the requester or an authorised approver. It never includes raw coordination files, environment values, logs, transcripts, emails, phone numbers, customer names or host paths.
  2. No production, deploy, billing or credential action below Operator.
  3. Every steer is audited. Each intent, decision and refusal writes an append-only event with actor, channel, time, action and a reason code. The verbatim quote is stored separately, redacted, readable only by the Owner and the requester, and deleted after 90 days.
  4. Rate and budget caps per person. Each grant carries questions_per_hour (default 30), intents_per_day (default 10) and model_budget_per_month. The database enforces them atomically with the insert. Exhausted caps defer the request and audit the refusal.
  5. Requests are untrusted input. Execution briefs are built only from enumerated values and server-resolved identifiers. Quotes and comments stay on the display path and never reach an executing lane. Ask runs in a tool-free model context over the caller’s scoped digest only. Lane tool and target restrictions are enforced by the orchestrator, independent of model output.
  6. Live authorisation, revocation and stop. Every protected read and mutation checks the live grant. Grants and the fleet stop carry generation numbers. The consumer rechecks requester and approver grants and the stop generation at claim and dispatch, and the lease and generation fences are enforced at the side-effect boundary itself, together with the approved target-to-project mapping version, atomically with the action. An operation that cannot honour the fence is rejected. A stale lease, generation or mapping version fails closed and voids the approval. An uncertain dispatch is reconciled before any retry. Resume after a stop requires fresh authorisation for every fenced intent.
  7. Verified identity. See Identity. Display names prove nothing; an unlinked sender gets the desk’s ordinary behaviour.

Identity

  • tuturuuu.com account: the source of truth for a person and their grant.
  • Channel identity: a WhatsApp, Zalo or Discord sender linked to that account. Linking: the person signs in to the Fleet page and takes a single-use code valid for ten minutes, sends it to the desk in a private one-to-one conversation, then confirms the pending link on the signed-in page. The server stores a keyed hash of the provider sender ID, unique per provider account, together with the linked private conversation.
  • Event binding: desks accept only authenticated provider events from approved private conversations. Linking, digest reads and submissions require API-verifiable event evidence from trusted ingress. The evidence binds the provider account, sender, conversation, event ID, the one permitted operation and a hash of its inputs. The API consumes the event ID atomically within its provider account, so a replay fails. The server resolves the actor from the linked provider account, sender and private conversation; desk credentials alone confer no actor authority.
  • Person registry: each desk’s registry mirrors links and tiers for routing only. The API decides every request.

Surfaces

Mastermind web

The Fleet area lives in Mastermind web (apps/mastermind) at mastermind.tuturuuu.com/{locale}/fleet-access. The #fleet anchor on the Mastermind page shows machines and lanes, so the Fleet area takes its own route. Tabs follow the live capabilities that GET /api/v1/fleet/access returns, and the API still decides every read and write:
  • Status (status.read): lanes, releases, readiness items and blockers for the person’s projects, with each snapshot’s generated and received time and a stale badge.
  • Ask (ask and status.read): a project and a typed topic (status, readiness or timeline) answered from the scoped digest in the page, without a model. Free-text questions wait for the tool-free Ask execution path.
  • Requests: the person’s receipts with typed states and short intent IDs, and a typed form per intent kind the grant can file. Kinds filed through intent.request are marked in the kind list, carry a persistent note and confirm as sent for Owner approval. Target keys are typed as catalog keys.
  • Link chat: issue a link code, send it to Mira in a private chat, preview the pending channel and account label, then confirm.
  • Approvals (approve.low) and Access (Owner only: grants, revocation, caps, fleet stop and the audit log) stay hidden until their APIs exist.
The Mastermind shell shows a grantee only the Fleet access entry, and the Owner keeps the full navigation. Every tier gets the language and theme controls. A disabled, stopped or revoked grant shows no tabs. A read refused mid-session asks the person to reload. Server functions call the Fleet API with the caller’s short-lived Mastermind session and validate every response against the @tuturuuu/internal-api/fleet schemas. Admission takes the actor only from the verified Tuturuuu Auth session (the owner also needs a second-factor check from the last 24 hours) and admits a fleet grantee only to the Fleet page, its assets and its server functions, rechecking the live grant on every request. No Cloudflare Access application fronts the host, and identity headers are ignored. See Fleet access admission. All strings ship in English and Vietnamese.

Mira chat

A verified person can ask about status, readiness and timelines. Mira answers from the scoped digest and says when it is more than one hour old. A steering request is acknowledged and filed as an intent; Mira never runs it.

Mastermind mobile

A Fleet view appears to anyone whose fleet access answer is enabled, separate from the owner-only Mastermind entry and its offline fallback. The app decides nothing; the API enforces every rule.
  • Entries: the Apps hub’s “Fleet access” tile (“Quyền truy cập đội máy”), its own app module beside the owner-only Mastermind tile; Today’s navbar action; and a Requests row at the end of Inbox, which opens Requests. Each shows only while the access answer is enabled, never while the check loads or fails. The Apps hub’s pull to refresh and an app resume re-check a failed answer, as they do for Mastermind. ?view=requests, ?view=link and ?view=approvals open a segment, as does the app link /mastermind/fleet-access/requests (or link, approvals).
  • Dock: the route belongs to the Fleet access module, not the Mastermind tab shell. Someone the owner gate admits keeps the Mastermind tabs; anyone else gets only Back, which falls back to the Apps hub. The code lives in apps/mobile/lib/features/mastermind/fleet_access/.
  • Gate: only GET /api/v1/fleet/access decides. The route is held on a skeleton while the check runs and redirected to the Apps hub when the answer is disabled or stopped, or the check is refused. A check that cannot finish shows a retry. The owner-only Mastermind gate does not apply to it. The answer is never stored, so there is no offline fallback. A 403 from any Fleet call, an app resume and pull to refresh re-check it, and logout or an account switch forgets it.
  • Status: lane totals, then each project’s latest snapshot with its received and generated times. A Stale badge shows when the server marks the snapshot stale or an hour has passed since receipt while it stays on screen.
  • Requests: the person’s own receipts, newest first, with their typed state and Show older. New request opens a full-screen form above the shell. It offers the kinds the grant files directly or as intent.request, the grant’s projects, and only the enumerated fields the kind sends. A kind the grant files only as intent.request is marked “Needs Owner approval”, and sending it confirms “Sent for Owner approval.” Target keys and commit SHAs are checked against the API syntax before sending. Closing a filled form asks before discarding it, and a refusal stays on the form with a fixed category message.
  • Link chat: take a code (Copy, ten-minute countdown, a new code once it expires), send it to Mira in a private chat, paste the link ID and confirmation code Mira replies with, check the channel and desk account, then confirm.
  • Approvals: shown only to a grant holding an approval capability, and read-only: no API lists or decides approvals yet.
  • Sessions: the app calls every Fleet route with its Supabase bearer session, the mobile access token. The reads and the writes (POST /api/v1/fleet/intents, identity/link-codes and identity/confirm) accept it; a session the API refuses shows “Fleet couldn’t verify your session”.

Intent queue

  • States: pending_approval, approved, rejected, claimed, dispatched, done, failed, expired, cancelled. Pending intents expire after 72 hours. Transitions are enforced in the database.
  • Dry-run consumption: Cron Control examines at most 20 approved or previously claimed intents per 15-minute tick. It uses a 15-minute lease and the intent’s idempotency key. The database rechecks the stop, live grants, target mapping and medium-risk quota at claim and receipt. dry_run closes the intent as done without moving through dispatched. Owner-required and high-risk approvals remain outside this consumer’s scope. After a restart, a still-live claim keeps its lease and key. An expired or stale lease is settled without renewal. See the consumer runbook.

Machine principals

Machine credentials confer no approval or grant authority.

Transitional Slice 0

Until the API exists, the desk host runs a local Observer rule:
  • the person registry holds an owner-confirmed Observer entry with the owner’s written authorisation as provenance;
  • before every reply and every queue write, the desk verifies the provider’s authentication, matches the configured provider account, sender and private one-to-one conversation, rejects replayed events, and checks the stop file, revocation and expiry;
  • a scheduled script on the desk host writes a sanitised digest from lane receipts every 15 minutes, using the field allowlist above;
  • desks answer the Observer through a tool-free path from the Owner-approved project digest only;
  • steering stays disabled: a steer request is only appended to a local queue for Owner review, and that queue cannot dispatch work;
  • access ends on the local stop file, on revocation, or at the earlier of API cutover and the 2026-12-21 expiry.
Exception: Slice 0 lacks event binding and signed-in confirmation, so it is limited to one Observer grant, read-only digest answers and owner-gated requests.

Data model

Base tables stay private with no grants to anon or authenticated. Callers reach them through SECURITY DEFINER functions with pinned search_path. Each function revokes PUBLIC execution at creation and grants execution only to its designated roles. The functions derive the actor from trusted request identity, scope every read by live capability and project, and enforce quotas, state transitions and audit writes atomically. Triggers reject updates and deletes on audit events, capabilities above the tier ceiling and Owner-tier grants. Fleet access is not a workspace role permission and is never implied by creator, admin or default permissions. The database starts with an empty grant table and an unconfigured Owner UUID. Configuring private.fleet_control.owner_user_id is a separate database-owner operation. The management functions require a database-owner connection with the verified user’s request identity and a live explicit root Mastermind grant. The service role can submit a server-resolved intent. The insert checks the live grant, project versions and the rolling one-hour question and 24-hour intent counts. The daily intent quota is the medium-risk budget. Slice 5 rechecks that budget at claim and dry-run completion. Model budget consumption belongs to the Ask execution path. Auth account deletion revokes the grant and retains its generation and historical intent references. Fleet grant, project and control rows retain their fences. The Observer API uses service-role-only definer functions. It binds read actors to verified Tuturuuu sessions and checks live grants, stop state and project scope before reading digest rows. Slice 3 binds submissions to the signed-in web user, a Supabase session bearer (the mobile access token), a Mastermind app-session user, or a desk event verified against a separate trusted ingress key. The platform CLI audience can read its own receipts and cannot submit, issue a link code, or confirm one. The desk’s event fingerprint, linked actor lookup and intent admission share one database transaction. Authoritative target aliases resolve across the project catalog, and the resolved action hash excludes the display quote. Slice 4 requires v2 desk evidence and a live, unquiesced desk-owner row for every desk operation. FLEET_DESKS carries key material only. The database checks the bearer, verifying key, signed claims and owner generation in the action transaction before consuming the event. Owner changes advance the generation by one through Owner-only audited functions, and a retired desk credential is never admitted again. The desk digest returns the linked actor’s grant-scoped snapshot and uses the same hourly question quota as status-question intents. Approval requires a separate authorized principal. See the desk API and cutover procedure. Link codes expire after ten minutes and a signed-in account must confirm the pending link with proof returned in the verified private conversation. The page can preview the pending provider and account label before confirming. A fresh code or an expired confirmation attempt clears pending identity fingerprints. Authenticated desk-event refusals without a linked actor carry a channel and reason in the append-only audit log. Keep replay fingerprints for 90 days from consumed_at. Trusted ingress must enforce provider-event freshness, including when it signs a redelivered event. The Cloudflare retention job purges expired link codes, expired quotes and event fingerprints older than 90 days. Unconfirmed link codes stay usable until expiry. Confirmation consumes the code and account deletion removes its codes. Every scheduled purge records counts in the append-only audit log. Quote readers must filter on expires_at from their first release.

Activation

Shipping code grants nobody access. Each step below is separate, and each is run by the owner or the release owners:
  1. Database: the gated production migration workflow applies the Fleet migrations after their exact-SQL review, CI and staging.
  2. Grant: the Owner grants a person a tier and projects through the owner-only grant function. That person needs a tuturuuu.com account.
  3. Catalog and digest: the Owner registers project catalog rows and approved display values, and the digest publisher token is issued so status exists to read.
  4. Web admission: none beyond the grant. The person signs in to Mastermind web with their tuturuuu.com account, and the live grant admits them to the Fleet area, as described in the Mastermind web runbook.
  5. Mobile: the next app release carries the Fleet access view and its Apps hub tile.
  6. Chat desks: each desk follows the v2 cutover in the API reference. Until then, Slice 0 stays dormant on the desk host.
  7. Consumer: the Slice 5 consumer token and mode are set only when dry-run receipts are wanted. Its kill switch and the Fleet stop both halt it.
Offboarding reverses step 2: revoking the grant takes effect on the next request and the next session refresh.

Implementation plan

Slice 4 cutover requires Slice 5 acceptance. Slice 8 live dispatch requires passing lease, reconciliation and durable stop-fence tests. New scheduling and delivery for slices 2 and later run on Cloudflare.

Regression coverage

Each slice links its coverage here when it lands:
  • Slice 1 covers default deny, table and function privileges, tier ceilings, Owner-only mutations, audit immutability, quota refusals, quote expiry, grant and project fences, and intent approvals and leases. See fleet-access.sql.
  • Slice 1 also races two PostgreSQL sessions against the final question and steer slots. See fleet-access-quota-race.sql.
  • Slice 2 covers default deny, live revocation, no-store responses, scoped totals, strict schema validation and the machine-only publish boundary in the Fleet route tests. The digest SQL tests cover actual project filtering, revoked and expired grants, stop, label approvals and snapshot ordering.
  • Slice 3 covers write audience restrictions, strict payload schemas, desk signature, input binding and freshness, one-time events and codes, signed-in preview and confirmation, refusal audit, target scope, receipt reads, revocation, quota, quote isolation and digest JSON types. See route tests, mobile write-session tests, and fleet-intent-admission.sql. The write-session tests admit a verified Supabase bearer on intent submit, link-code issue, and link confirmation, and refuse a platform CLI session, an unknown bearer, and a forged x-user-id.
  • Slice 6 covers tab visibility per tier, request options against intent admission, typed drafts, digest answers, redirect refusal, strict response validation, refusal mapping, the link flow and bilingual message parity. See the Fleet access web tests.
  • Slice 6 admission covers grantee reach, 403 on every owner route without session work, revocation and stop on the next request, identity binding, unchanged Owner admission and pinned server-function IDs in fleet-admission.test.ts.
  • Slice 5 covers racing claims, lease expiry, idempotent receipts, requester and approver generations, mapping drift, the dispatch fence and bounded retention in apps/database/supabase/tests/fleet-dry-run-consumer.sql. apps/cron-control/src/fleet-access-consumer.test.ts exercises operation limits, stop and restart through the scheduler and ledger. apps/web/src/app/api/v1/fleet/consumer/route.test.ts checks bearer isolation, request bounds and the private RPC bindings.
  • Slice 7 covers the mobile gate (disabled, enabled, stopped, failed, revoked mid-session, account reset, the owner gate exemption), the Apps hub tile, the grantee and owner docks in the real shell (registered destinations), strict parsing, the stale badge, request validation and payloads, receipts paging and the link flow in the Fleet access mobile tests.
  • Slice 4 covers Owner-only transitions, privileges and pinned search paths, monotonic generations, direct-write fences, credential history, quiesce, every bearer, key and claim mismatch, stale replicas, linked conversation and project scope, capability, stop, revocation, shared question quotas, desk self-approval and cross-operation replay in fleet-desk-admission.sql. The Fleet desk route tests cover v2 proof, v1 claims, signature domain and configuration rejection, strict digest inputs, scoped totals and denial responses.