> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tuturuuu.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Fleet access

> Live Fleet grants, project digests, intent receipts, and desk identity linking.

The [Fleet access policy](https://docs.tuturuuu.com/platform/features/fleet-access.md) governs these
endpoints on `tuturuuu.com`. Responses use `Cache-Control: private, no-store`.
Use `getFleetAccess`, `getFleetDigest`, `publishFleetDigest`,
`listFleetIntents`, `submitFleetIntent`, `createFleetLinkCode` and
`confirmFleetLink` from `@tuturuuu/internal-api/fleet` for TypeScript callers.
The package also exports the response schemas; validate responses before use.

## Read access

`GET /api/v1/fleet/access` accepts a signed-in Tuturuuu session or an app
access session with the `platform` or `mastermind` audience and
`internal-app:session` scope. The server uses the verified user ID and looks up
the grant and stop state on every request. An unsigned request receives `401`.

A signed-in account without live access receives:

```json theme={null}
{"enabled":false,"tier":null,"projects":[],"capabilities":[],"stopped":false}
```

A live grant returns `enabled: true`, its tier, project keys and capabilities.
While Fleet is stopped, the endpoint returns `stopped: true` and disables
access for every tier.

## Read the digest

`GET /api/v1/fleet/digest` uses the same sessions and requires live
`status.read` access. The response contains `sections` and `totals`. Each
section is the latest visible snapshot for a project in the grant. It carries
the publisher timestamp `generatedAt`, the server timestamp `receivedAt`, and
`stale`, which becomes true one hour after receipt. Totals
count visible sections as projects, and their lanes overall and by state.
An authorized reader with no visible snapshots receives empty sections and
zero totals. A disabled or stopped reader, or a grant without `status.read`,
receives `403`.

## Publish a project snapshot

`PUT /api/v1/fleet/digest` accepts one project snapshot and returns `204`.
The digest publisher uses a dedicated `Authorization: Bearer <token>`
credential over HTTPS. Provision the token as the prefix `ttr_fleet_digest_`
followed by 32 cryptographically random bytes encoded as unpadded base64url.
Store the full token in the publisher's secret store. Set
`FLEET_DIGEST_PUBLISHER_TOKEN_SHA256` on Web to the lowercase hex SHA-256 of
the full token. Remove the configured hash to disable publishing or replace
it with a new hash to rotate the credential. A missing or invalid publisher
credential is denied. A Fleet stop also denies publishing.

| Field | Accepted value |
| - | - |
| `projectKey` | Catalog key, 1–64 lowercase ASCII letters, digits, underscores or hyphens, starting with a letter or digit |
| `generatedAt` | UTC ISO 8601 timestamp with milliseconds, at most 30 seconds in the future |
| `lanes` | Up to 100 entries with unique lane names |
| `lanes[].lane` | Project-approved display value |
| `lanes[].state` | `planned`, `running`, `blocked`, `ready`, `done`, or `paused` |
| `lanes[].eta` | Optional UTC ISO 8601 timestamp with milliseconds |
| `lanes[].shortSha` | Optional 7–12 lowercase hexadecimal characters |
| `lanes[].releaseTitle`, `lanes[].readinessItem` | Optional project-approved display values |
| `lanes[].blockerCodes` | Up to seven distinct codes from `dependency`, `review`, `ci`, `approval`, `release_hold`, `capacity`, and `incident` |

The route rejects unknown fields at every level and caps the body at 128 KiB.
Only the database owner can provision approved display values in
`private.fleet_digest_display_values`. Approvals are specific to a project
and field. Approve only text safe for the project's Fleet readers. A removed
approval hides any affected snapshot while one of its display values lacks approval.

Retrying the same snapshot preserves its original receipt time. A
snapshot older than the stored snapshot, or different content at the same
timestamp, receives `409`. Invalid documents, unapproved labels, and unknown
projects receive `400`. Excess body bytes receive `413`. Unavailable storage
or invalid publisher configuration returns `503`.

## Submit and read intents

`POST /api/v1/fleet/intents` accepts a signed-in Tuturuuu web session cookie, a
Supabase session bearer, a Mastermind access session with `internal-app:session`,
or a desk request with signed event evidence. The mobile app sends its Supabase
access token as `Authorization: Bearer`. That token is not an app-coordination
token. The `platform` audience stays read-only, including a signed CLI session.
Send `Content-Type: application/json` with `{ kind, payload, quote? }`. Bodies
are limited to 4 KiB. Each payload includes a `projectKey`. Targeted requests
also include a catalog `targetKey`, with the same syntax as a project key.

| Kind | Target catalog group | Additional payload fields |
| - | - | - |
| `status_question` | Project only | `topic` of `status`, `readiness`, or `timeline` |
| `comment` | `lane` | Display text in the top-level `quote` |
| `priority.set` | `lane` | `priority` of `low`, `normal`, `high`, or `urgent` |
| `approve.item` | `readiness_item` | |
| `work.create` | `repository_path` | `template` of `investigation`, `maintenance`, or `regression_fix` |
| `work.redirect` | `thread` | `objective` of `investigate`, `verify`, or `prepare_review` |
| `lane.pause` | `lane` | |
| `approve.deploy` | `deployment` | `environment` of `staging` or `production`, and a 40-character lowercase hex `commitSha` |
| `approve.production_change` | `production_change` | `environment` of `production` and a 40-character lowercase hex `commitSha` |

Catalog operators store target aliases under the corresponding group in
`private.fleet_projects.target_mapping`, mapping each alias to a lowercase
UUID. Each alias must uniquely identify one target within its group across
the entire catalog. The server binds the resolved ID, parameters, kind and
owning project version to the action hash. A project mismatch, missing target
or ambiguous alias is denied. The release intent kinds file requests for approval.
Desk requests never approve themselves. A desk-filed low- or medium-risk
request waits for approval even when the requester holds `approve.low`.
Desk-filed `comment` and `status_question` intents need no approval and still
execute. Desk operations resolve a live grant row, so the Owner needs a
non-Owner grant to use them.

The optional `quote` is capped at 1,000 characters and required for comments.
The server scrubs recognizable sensitive values and stores the result separately
as display text. Keep credentials and private data out of submitted quotes.
A successful response is `201 {"id":"<intent UUID>"}`.
Refused desk evidence returns `401`. Denied requests return `403`, event
replays and stale mappings return `409`, and exhausted quotas return `429`. Invalid JSON or unknown fields return `400`.

`GET /api/v1/fleet/intents` accepts the same human sessions as the access
endpoint. It returns the caller's own receipts for currently authorized
projects, newest first, with `id`, `kind`, `state` and `createdAt`. The `intents`
array contains up to 50 entries. Pass `nextBefore` as `?before=<intent UUID>`
for the next page when present. Disabled or stopped access returns `403`.

## Link a private desk conversation

`POST /api/v1/fleet/identity/link-codes` and
`POST /api/v1/fleet/identity/confirm` accept the same signed-in sessions as
`POST /api/v1/fleet/intents`: a web session cookie, a Supabase session bearer,
or a Mastermind access session with `internal-app:session`. They refuse the
`platform` audience. Desk event evidence is not a session on these two routes.

1. A signed-in user with live Fleet access sends `{}` to
   `POST /api/v1/fleet/identity/link-codes`. The `201` response contains
   `code` and `expiresIn: 600`. Issuing a new code invalidates the account's
   current code or pending link.
2. The user sends the code in an approved one-to-one conversation. The desk
   sends `{ code }` to `POST /api/v1/fleet/identity/verify` with signed event
   evidence. It shows the returned `linkId` and `confirmationCode` to the
   sender in the same conversation.
3. The same signed-in user sends `{ linkId, confirmationCode, preview: true }`
   to `POST /api/v1/fleet/identity/confirm` within the original ten-minute
   window to read the pending `channel` and the desk owner's `accountLabel` with
   `linked: false`. Sending `{ linkId, confirmationCode }` to the same route
   confirms the link and returns the channel and label with `linked: true`.
   Neither response exposes provider sender or conversation identifiers.
   A sender can link to one user per provider account. Desk events resolve
   to that user only in the linked conversation and while their grant is live.

### Desk and ingress credentials

Set `FLEET_DESKS` on Web to a JSON object keyed by desk ID. Each entry
contains `tokenSha256` (lowercase hex SHA-256 of the full bearer),
`ingressPublicKey` (an Ed25519 public key in PEM format), and
`credentialVersion` (a positive 32-bit integer). Desk IDs contain 1–40
lowercase letters, digits or hyphens. The bearer format is
`ttr_fleet_desk_<desk-id>.<32 random bytes in unpadded base64url>`. Store
the private signing key only at ingress and the bearer only with its desk.
`FLEET_DESKS` holds key material only and admits nothing by itself. A
configuration that still names a `channel`, `account` or `accountLabel` fails
validation, and every desk request then returns `401`.

Trusted ingress validates the provider event, its original freshness, account,
sender and approved private conversation before constructing the request body.
It repeats the freshness check on provider redelivery and declines to sign
expired events. Send the UTF-8 JSON claims as unpadded base64url in
`X-Fleet-Event`. Sign the ASCII string `fleet-event-v2.<encoded claims>` with
Ed25519 and send the unpadded base64url signature in
`X-Fleet-Event-Signature`. The v1 claims and signature domain are retired.
The v2 claims are:

* `version` of `2`, `channel` (`whatsapp`, `zalo`, or `discord`), `account`,
  `sender`, `conversation`, and `conversationType` of `private_1_to_1`.
* `deskId`, `credentialVersion`, and `ownerGeneration`. Use the decimal
  string returned by the Owner operation for `ownerGeneration`.
* The provider's `eventId`, the allowed `operation` (`identity.verify`,
  `intent.submit`, or `digest.read`), and `inputSha256` (lowercase hex
  SHA-256 of the exact HTTP JSON body bytes).
* `issuedAt`, Unix time in milliseconds. Evidence permits up to 30 seconds
  of future clock skew and expires after five minutes.

Admission requires an active, unquiesced database row for the channel and
provider account. Inside the action transaction, the API matches the bearer
desk ID, the verifying key's desk ID and credential version, and the signed
desk ID, credential version and generation to that row. A missing or
mismatched row, quiesced owner or retired proof returns `401`, leaves the
event unconsumed and appends an audit event without an actor. The API
consumes the event ID once per channel and provider account across all
three operations and across desk rotations and cutovers. Replay fingerprints
are retained for 90 days from consumption. Preserve
`FLEET_IDENTITY_HMAC_KEY` across cutovers. It is 32 random bytes in lowercase
hex stored only on Web. Changing it requires retirement and re-linking of
existing sender and conversation identities.

### Register, rotate and cut over a desk

Change the desk owner only from a trusted database-owner session carrying the
configured Owner's verified request identity and live explicit root
`manage_mastermind` permission. No API role can execute these functions or
read the owner tables. Each function takes the channel and provider account
first, returns the account, desk ID, credential version, owner generation (a
decimal string) and quiesce state, and appends an audit event.

| Function | Further arguments | Result |
| - | - | - |
| `private.fleet_register_desk_owner` | 1–80 character display label, desk ID, credential version | Creates a quiesced row at generation `1` |
| `private.fleet_quiesce_desk_owner` | Current generation | Blocks admission and advances the generation |
| `private.fleet_rotate_desk_credential` | Current generation, higher credential version | Keeps the desk, replaces its admitted credential and advances the generation |
| `private.fleet_promote_desk_owner` or `private.fleet_rollback_desk_owner` | Current generation, different desk ID, higher credential version | Replaces the desk of a quiesced owner and advances the generation |
| `private.fleet_resume_desk_owner` | Current generation | Enables the quiesced desk and advances the generation |

A stale expected generation fails with `55000`, and an invalid transition
with `22023`. Each generation advances by exactly one, and the database
rejects direct writes that skip, repeat or rename an owner row. Owner rows and
the credential history cannot be deleted. A desk ID and credential version
pair is admitted at most once across all accounts, so a retired credential
never becomes valid again, even when its desk later serves another account.

Each credential version maps to one `FLEET_DESKS` entry. A rollback assigns a
new version. It may reuse the previous desk's key only while that key is still
held and unexpired; otherwise provision a fresh bearer and key. Quiesce before
rotating when Web replicas receive verifier configuration at different times.
After the verifier configuration and the database readback agree, resume and
issue proofs with the returned generation. For a runtime cutover, quiesce both
admission and the provider send fence, reconcile in-flight sends and verify
the desk and send owners before resuming. Use the same sequence for rollback.
If a cutover is aborted, resume the quiesced current owner at a fresh
generation. See the
[Mira cutover procedure](https://docs.tuturuuu.com/platform/ai/mira-cloud-channels.md#migration).

### Cut over from v1 evidence

1. Apply the desk-owner migrations. Every desk request returns `401` until
   the remaining steps finish.
2. Register the owner row, which starts quiesced.
3. Install the matching v2 `FLEET_DESKS` entry for that desk ID and
   credential version on every Web replica.
4. Resume the owner after the configuration and the database readback agree.
5. Sign only v2 proofs carrying the generation that resume returned.

Keep `FLEET_IDENTITY_HMAC_KEY` unchanged so linked identities still resolve.
Retire the v1 signers once v2 proofs are admitted.

**Known gap:** `FLEET_DESKS` holds one key per desk ID, so Web cannot verify
an old and a new credential side by side during rotation. Quiesce before
rotating when replicas receive configuration at different times. A rollback
always mints a higher credential version.

## Read a digest from a desk

Send `POST /api/v1/fleet/desk/digest` with `Content-Type: application/json`,
body `{}` and v2 proof for `digest.read`. A successful response has the same
`sections` and `totals` as the session digest. The transaction consumes the
event, resolves the actor from the linked private conversation, and requires a
live `status.read` grant. It returns only projects in that grant. An unlinked
conversation, inactive grant, missing capability or Fleet stop returns `403`.
A replay returns `409`. Every successful read uses one slot from the actor's
rolling `questions_per_hour` quota, shared with status-question intents.
Quota exhaustion returns `429`. The endpoint returns digest data only.
Generated answers additionally require `ask` and a model budget reservation.
Desk credentials confer no approval authority.

## Dry-run consumer

Cron Control calls these routes with its dedicated
`Authorization: Bearer <token>` over HTTPS. The token is
`ttr_fleet_consumer_` followed by 32 random bytes encoded as unpadded
base64url. Keep the token in the Worker secret `FLEET_CONSUMER_TOKEN`.
Configure its lowercase hex SHA-256 on Web as `FLEET_CONSUMER_TOKEN_SHA256`.
This principal has no submit, approval, grant, or dispatch authority.

Send JSON bodies with `Content-Type: application/json`. Bodies are capped
at 4 KiB and unknown fields are rejected.

| POST path under `/api/v1/fleet/consumer/` | Request | Success response |
| - | - | - |
| `status` | `{}` | `{state:"active",generation}` or `{state:"stopped"}` |
| `claim` | `{slot,generation}` | `{state:"claimed",claims:[{id,leaseId,idempotencyKey}]}`, with at most 20 entries |
| `receipt` | `{slot,generation,id,leaseId,idempotencyKey,state:"dry_run"}` | `{state:"dry_run"}` or `{state:"voided"}` for stale authorization or lease expiry |
| `purge` | `{slot,generation}` | `{state:"purged",counts:{quotes,events,linkCodes}}`, with up to 1,000 rows total |

`slot` is the UTC start of the current 15-minute window in ISO 8601 format
with milliseconds. `generation` is the decimal string returned by `status`.
Use the same generation for the whole run. A stop or generation change returns
`{state:"stopped"}`; an out-of-window request returns `{state:"slot_closed"}`.
A missing or mismatched current lease returns `{state:"lease_conflict"}`.
These protocol states use HTTP `200`. Invalid credentials return `401`,
invalid input returns `400`, oversized bodies return `413`, and unavailable
storage or verifier configuration returns `503`.

A repeated claim in the same slot returns only the batch's remaining live
leases. A new slot reconciles existing leases before admitting fresh work.
A repeated successful receipt or purge in the same slot yields the recorded
result. Claims contain opaque IDs only. A dry-run receipt closes the intent
with state `done` and the database records `dry_run`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.