@aitne-sh/aitne 0.1.8 → 0.1.9

package/agent-assets/docs/features/messaging/overview.md

@@ -19,14 +19,17 @@ tags:
   - core
   - messaging
   - integrations
+  - pairing
+  - notifications
 status: stable
 ask_examples:
   - How do I pair my phone with the agent?
   - Which messaging apps does the agent support?
   - Why didn't I get a notification?
+  - Can I send the agent a voice note?
 locale: en-US
 created: 2026-04-25
-updated: 2026-05-04
+updated: 2026-05-28
 keywords:
   - messaging
   - dm
@@ -52,38 +55,49 @@ ui_anchors:
   - /connections/messaging
   - /settings/connections
   - /settings/commands
+  - /settings/schedule
+process_keys:
+  - message.dm
+  - message.mention
+config_keys:
+  - primaryPlatform
+  - quietHoursStart
+  - quietHoursEnd
 ---
 
 # Messaging Overview
 
-## In One Sentence
-
-Aitne treats DMs from a paired messaging app as its primary
-reactive surface — you message it, it answers; it messages you when a
-notification fires.
+Aitne treats DMs from a paired messaging app as its primary reactive
+surface — you message it, it answers; it messages you when a
+notification fires. Voice notes are transcribed locally with Whisper
+so you can talk to the agent the same way you'd type.
 
 ## What It Does
 
 - **Reactive DMs**: the agent answers every direct message you send.
-- **@-mentions**: in Slack, @-mentioning the agent inside a shared
-  channel routes to `message.mention` and is answered the same way
-  as a DM. Telegram, Discord, and WhatsApp drop all non-DM traffic
-  (no group support); multi-user DMs (Slack `mpim`) are also
-  filtered out — Aitne is single-owner by design.
+- **@-mentions (Slack only)**: @-mentioning the agent inside a shared
+  channel routes to the `message.mention` ProcessKey and is answered
+  the same way as a DM. Telegram, Discord, and WhatsApp drop all
+  non-DM traffic (no group support).
 - **Outbound notifications**: routines and observations fire alerts
   back through the same channel.
 - **Voice attachments**: when the platform attaches audio (Telegram
   voice notes, WhatsApp voice messages, etc.), the daemon transcribes
   it locally with Whisper before handing the turn to the agent.
   Transcription runs entirely on your machine — no audio is shipped
-  to a cloud API. Configurable via the `PA_VOICE_TRANSCRIPTION_*`
-  env vars (model, language, duration cap).
+  to a cloud API. Tune it with the `PA_VOICE_TRANSCRIPTION_*` env
+  vars: `ENABLED`, `MODEL`, `LANGUAGE`, `PRIMARY_LANGUAGE`, and
+  `MAX_DURATION_SEC`.
 - **Magic-phrase pairing**: the operator types a one-time phrase to
   bind their account to the agent (anti-impersonation).
 
-Aitne is **single-owner** by design. Any DM that does not
-match a paired owner channel is dropped (defense in depth — the
-adapter and the dispatcher both check).
+## Single-Owner by Design
+
+Aitne serves exactly one owner. Any message that does not come from a
+paired owner channel is dropped — group chats, multi-user Slack DMs
+(`mpim`), and unrecognized senders never reach the agent. This is
+defense in depth: both the messaging adapter and the dispatcher check
+the owner channel independently.
 
 ## When It Runs / How It Is Triggered
 
@@ -108,14 +122,18 @@ adapter and the dispatcher both check).
 ## Configuration
 
 - Per-app: bot token / OAuth, owner channel, optional default channel.
-- Global: `primaryPlatform` (the fallback when multiple apps are paired).
+- Global: `primaryPlatform` (default `slack`) — the platform the agent
+  prefers for outbound notifications when more than one app is paired.
+- Outbound rate limits and quiet hours live on `/settings/schedule`
+  (see [Quiet Hours](../operations/quiet-hours.md)).
 
 ## When Something Goes Wrong
 
 - An **un-paired DM**: the agent ignores it. Pair the app from
-  `/connections/messaging` first.
+  `/connections/messaging` first (see
+  [Pairing & Magic Phrase](pairing-and-magic-phrase.md)).
 - A **notification you expected but did not get**: check quiet hours
-  on `/settings/schedule`.
+  and rate limits on `/settings/schedule`.
 
 ## Related
 

package/agent-assets/docs/features/messaging/pairing-and-magic-phrase.md

@@ -7,63 +7,130 @@ aliases:
   - magic phrase
   - pairing
   - owner pairing
+  - pair my messaging account
 category: features
 summary: |
-  Pair your messaging account to Aitne by typing a one-time
-  "magic phrase" the dashboard generates. The phrase binds the channel
-  to your owner identity so impersonation is impossible.
+  Pair a messaging account to Aitne so the daemon knows which DM channel
+  belongs to you, the owner. Slack and Discord use a one-time "magic
+  phrase" you DM from the app; Telegram uses a QR / deep-link token;
+  WhatsApp links the device by scanning a QR. All of them bind the channel
+  to your owner identity so nobody else can impersonate you.
 section: messaging
 tags:
   - core
   - messaging
   - pairing
   - safety
+  - setup
 status: stable
-ask_examples:
-  - How do I pair my Telegram account?
-  - What is the magic phrase?
-  - Can someone else impersonate me?
 locale: en-US
 created: 2026-04-25
-updated: 2026-04-25
+updated: 2026-05-28
 keywords:
   - pairing
   - magic phrase
-  - owner
+  - owner channel
+  - QR pairing
+  - impersonation
+ask_examples:
+  - How do I pair my Telegram account?
+  - What is the magic phrase?
+  - Can someone else impersonate me as the owner?
+  - Why didn't my pairing DM work?
+ui_anchors:
+  - /connections/messaging
 related:
   - features/messaging/overview
+  - features/messaging/slack
+  - features/messaging/telegram
+  - features/messaging/discord
+  - features/messaging/whatsapp
+  - troubleshooting/messaging-not-pairing
 ---
 
 # Pairing and Magic Phrase
 
-## In One Sentence
+## In one sentence
+
+The dashboard hands you a one-time secret (a typed phrase, a QR code, or
+a deep link, depending on the platform); you send or scan it from the
+messaging app you want to pair; the daemon records that channel as your
+owner channel.
+
+## Why pairing exists
+
+The agent only talks to one person — you, the owner. Pairing is how the
+daemon learns which DM channel is yours.
+
+- **Impersonation protection.** A random bot or stranger can't open a DM
+  and claim the owner role without the secret. Only someone who can see
+  the dashboard can complete the pairing.
+- **One identity, many channels.** Pair Slack, Telegram, Discord, and
+  WhatsApp separately; all of them map to the same owner identity. A DM
+  to any paired channel reaches the agent, and notifications can go out on
+  whichever channels you've configured.
+
+## How each platform pairs
+
+Pairing starts the same way everywhere — open
+**Connections → Messaging** (`/connections/messaging`), find the
+platform's card, and click its pairing button. What you do next depends
+on the platform.
+
+| Platform | Mechanism | What you do |
+|---|---|---|
+| **Slack** | Magic phrase | Dashboard shows a 4-word phrase (e.g. `apple-banana-cherry-date`). DM that phrase to the bot, by itself. |
+| **Discord** | Magic phrase | Same as Slack — DM the displayed phrase to the bot. |
+| **Telegram** | QR / deep link | Dashboard shows a QR code that opens a `https://t.me/<bot>?start=<token>` link. Tap **START** in Telegram. |
+| **WhatsApp** | Device QR | Dashboard shows a QR code; scan it from WhatsApp on your phone (Linked Devices). |
+
+### The magic phrase (Slack, Discord)
 
-The dashboard prints a one-time phrase; you DM that phrase to the
-agent from the messaging app you want to pair; the daemon records the
-channel as your owner channel.
+The dashboard generates a short, memorable phrase of four lowercase words
+joined by hyphens, drawn from a 64-word list (24 bits of entropy). You DM
+that exact phrase to the bot. Matching is tolerant — it ignores case,
+punctuation, and emoji — but the phrase must be **sent by itself**. If you
+wrap it in a sentence ("my phrase is apple-banana-cherry-date"), the agent
+will reply asking you to send the phrase on its own.
 
-## What It Does
+The phrase is single-use and expires after **5 minutes**. If it lapses,
+regenerate a fresh one from the dashboard.
 
-- Prevents drive-by impersonation: a bot can't open a DM and pretend
-  to be the operator without the phrase.
-- Multiple paired channels (e.g. Telegram + Slack) all map to the
-  same owner identity.
+### Token pairing (Telegram, WhatsApp)
 
-## When It Runs / How It Is Triggered
+Telegram and WhatsApp don't use a typed phrase:
 
-The phrase is generated when the operator clicks "Pair" on
-`/connections/messaging`. The daemon listens for the phrase from any
-incoming DM until paired or the phrase expires.
+- **Telegram** encodes a high-entropy, single-use token in a QR / deep
+  link. Tapping **START** sends `/start <token>` to the bot, which
+  promotes you to owner. The token is matched exactly and also expires
+  after 5 minutes.
+- **WhatsApp** uses WhatsApp's own linked-device flow — you scan a QR from
+  your phone to attach the daemon as a device. Set the owner phone number
+  first, then click **Pair device** and scan.
 
-## Where in the Dashboard
+## Where in the dashboard
 
-- **Connections → Messaging** is the pairing surface.
+**Connections → Messaging** (`/connections/messaging`) is the single
+pairing surface. Each platform has its own card with a step-by-step setup
+(create the app / paste tokens / pair) and a live status indicator that
+flips to "paired" once the channel is bound.
 
-## When Something Goes Wrong
+## When something goes wrong
 
-- Phrase expired: regenerate it from the dashboard.
-- DM was sent in a group: pairing only works in direct messages.
+- **Phrase or token expired.** The window is 5 minutes. Regenerate from the
+  dashboard and try again.
+- **"Send the pairing phrase by itself" reply.** You wrapped the phrase in
+  other text. Send just the four words.
+- **DM was sent in a group.** Pairing — and all agent messaging — only works
+  in direct messages. Group chats are out of scope by design.
+- **Still not pairing?** See
+  [Messaging not pairing](../../troubleshooting/messaging-not-pairing.md).
 
 ## Related
 
 - [Messaging Overview](overview.md)
+- [Slack setup](slack.md)
+- [Telegram setup](telegram.md)
+- [Discord setup](discord.md)
+- [WhatsApp setup](whatsapp.md)
+- [Messaging not pairing (troubleshooting)](../../troubleshooting/messaging-not-pairing.md)

package/agent-assets/docs/features/messaging/slack.md

@@ -10,54 +10,107 @@ aliases:
   - slack DM
 category: features
 summary: |
-  Pair a Slack workspace by installing a bot user, pasting tokens
-  into Aitne, and DMing the magic phrase.
+  Connect a Slack workspace by creating a bot app with Socket Mode,
+  pasting a bot token and an app-level token into Aitne, then DMing
+  the magic phrase to pair yourself as owner.
 section: messaging
 tags:
   - messaging
   - integrations
   - slack
+  - pairing
 status: stable
 ask_examples:
   - How do I pair Slack?
+  - Why does the agent need two Slack tokens?
   - Can the agent listen in shared channels?
 locale: en-US
 created: 2026-04-25
-updated: 2026-04-25
+updated: 2026-05-28
 keywords:
   - slack
-  - OAuth
+  - socket mode
   - bot token
+  - app token
+  - magic phrase
   - owner channel
   - messaging adapter
 related:
   - features/messaging/overview
   - features/messaging/pairing-and-magic-phrase
+ui_anchors:
+  - /connections/messaging
+config_keys:
+  - primaryPlatform
+  - slackOwnerUserId
 ---
 
 # Slack
 
 ## In One Sentence
 
-A Slack bot user becomes the agent's surface in your workspace; DMs
-to the bot are owner messages, mentions in channels are mention events.
+A Slack bot user becomes the agent's surface in your workspace: DMs to
+the bot are owner messages, and `@`-mentions of the bot in channels are
+mention events — but only from the one paired owner.
 
 ## What It Does
 
-- Listens for DMs (owner reactive path).
-- Listens for `@personalagent` mentions in shared channels.
-- Sends notifications to the owner DM.
+- Listens for **DMs** to the bot (owner reactive path).
+- Listens for **`@`-mentions of the bot** in channels you've added it to.
+- Sends notifications back to your owner DM.
 
-## Where in the Dashboard
+The adapter runs over Slack **Socket Mode** (a WebSocket), so Aitne does
+not need a public inbound URL or webhook endpoint.
 
-- **Connections → Messaging → Slack** holds bot tokens, channel info,
-  and the magic-phrase pairing flow.
+## Single-Owner Scope
+
+Aitne is a single-owner agent by design. Only messages from the paired
+owner are processed; everything else is dropped silently. Multi-person
+DMs (`mpim`) are rejected outright, so a mention inside a group thread
+never produces a reply visible to non-owners.
+
+A channel mention only fires when the message text contains the bot's
+actual user reference (e.g. `<@U0123ABCD>`, rendered as `@YourBotName`).
+A plain text string like `@personalagent` is not a real Slack mention and
+will not trigger anything.
+
+## Setup
+
+Everything happens under **Connections → Messaging** in the dashboard
+(the Slack card). There are three steps:
+
+1. **Create the Slack app.** Click *Open Slack app builder* — Aitne
+   pre-fills the manifest with the right scopes and Socket Mode enabled.
+   Create the app and install it to your workspace.
+2. **Paste two tokens.** Slack issues two tokens for a Socket Mode app:
+   - a **bot token** (`xoxb-...`) — the bot's identity and API access, and
+   - an **app-level token** (`xapp-...`) — authorizes the Socket Mode
+     WebSocket connection.
+
+   Paste both, then use *Test token* to confirm Aitne can reach the bot.
+3. **Pair with the magic phrase.** Click *Generate pairing phrase*, then
+   DM that exact phrase to the bot from your own Slack account. The first
+   account that sends the matching phrase becomes the owner. See
+   [Pairing and the Magic Phrase](pairing-and-magic-phrase.md) for how
+   the challenge works.
+
+To route notifications to Slack by default, set Slack as your primary
+platform (`primaryPlatform`). The owner's Slack user id is stored as
+`slackOwnerUserId` once pairing succeeds.
 
 ## When Something Goes Wrong
 
-- Bot does not respond: check that the workspace bot has been added
-  to the channel where the DM is happening.
+- **Bot never responds to a DM.** Confirm both tokens are saved and *Test
+  token* succeeds. A failing app-level token (`xapp-`) means the Socket
+  Mode connection never opens, so no events arrive.
+- **Mentions in a channel are ignored.** Make sure the bot has been added
+  to that channel, and that you're mentioning the bot itself (autocomplete
+  `@YourBotName`), not typing a plain word.
+- **Pairing phrase isn't accepted.** Send the phrase by itself, with no
+  surrounding sentence — a wrapped phrase won't match. See the pairing
+  doc for the full rules.
 
 ## Related
 
 - [Messaging Overview](overview.md)
+- [Pairing and the Magic Phrase](pairing-and-magic-phrase.md)

package/agent-assets/docs/features/messaging/telegram.md

@@ -13,14 +13,18 @@ section: messaging
 tags:
   - messaging
   - integrations
-  - core
+  - telegram
 status: stable
+config_keys:
+  - telegramOwnerChatId
+ui_anchors:
+  - /connections/messaging
 ask_examples:
   - How do I pair Telegram?
   - Where do I get a Telegram bot token?
 locale: en-US
 created: 2026-04-25
-updated: 2026-04-25
+updated: 2026-05-28
 keywords:
   - telegram
   - telegram bot
@@ -41,12 +45,14 @@ token, type the magic phrase.
 
 ## What It Does
 
-- Acts as the agent's reactive surface for incoming DMs.
-- Receives outbound notifications.
+- Acts as the agent's reactive surface for your incoming direct messages (owner DMs only — group chats are ignored).
+- Delivers the agent's outbound notifications and replies back to the same Telegram chat.
 
 ## When It Runs / How It Is Triggered
 
-Continuously listening to Telegram's long-polling API once paired.
+Before pairing, nothing listens. Once you paste the bot token and complete
+magic-phrase pairing, Aitne long-polls Telegram's Bot API continuously for new
+direct messages.
 
 ## Where in the Dashboard
 
@@ -63,7 +69,14 @@ Continuously listening to Telegram's long-polling API once paired.
 
 - Bot replied to in a group instead of a DM: group chats are filtered
   out by design; the agent only listens to direct messages.
+- No reply at all after DMing the magic phrase: confirm the bot has a username
+  set via @BotFather (/setname) — the daemon refuses to build the pairing deep
+  link otherwise.
+- Pairing never completes: re-check the token in Connections → Messaging →
+  Telegram, then DM the magic phrase from your own account. See
+  [Pairing & Magic Phrase](pairing-and-magic-phrase.md).
 
 ## Related
 
 - [Pairing & Magic Phrase](pairing-and-magic-phrase.md)
+- [Messaging Overview](overview.md)

package/agent-assets/docs/features/messaging/whatsapp.md

@@ -7,53 +7,107 @@ aliases:
   - whatsapp bot
   - whatsapp adapter
   - whatsapp pairing
+  - whatsapp linked device
 category: features
 summary: |
-  Pair WhatsApp via the Cloud API or a bridge service. Once paired, DMs
-  to the configured number are owner messages.
+  Link WhatsApp by scanning a QR code with your phone, the same way the
+  WhatsApp desktop app links. No Cloud API, business account, or webhook
+  is involved. Once linked, DMs to your own number are owner messages and
+  flow exactly like Telegram.
 section: messaging
 tags:
   - messaging
-  - integrations
   - whatsapp
+  - integrations
+  - pairing
 status: stable
 ask_examples:
   - Can I use WhatsApp with Aitne?
-  - How do I set up the WhatsApp Cloud API?
+  - How do I link WhatsApp by scanning a QR code?
+  - Why does WhatsApp say the device is unlinked?
 locale: en-US
 created: 2026-04-25
-updated: 2026-04-25
+updated: 2026-05-28
 keywords:
   - whatsapp
-  - twilio
-  - bot token
-  - owner channel
+  - qr code
+  - linked devices
+  - owner phone
+  - e.164
   - messaging adapter
+  - baileys
 related:
   - features/messaging/overview
+  - features/messaging/pairing-and-magic-phrase
+config_keys:
+  - whatsappEnabled
+  - whatsappOwnerPhone
+  - whatsappAuthDir
+ui_anchors:
+  - /connections/messaging
 ---
 
 # WhatsApp
 
 ## In One Sentence
 
-A WhatsApp Cloud API number can act as the agent's owner surface; DMs
-flow exactly like Telegram.
+Link WhatsApp by scanning a QR code with your phone — the same flow as
+WhatsApp's own desktop/web app — and DMs to your number become owner
+messages that flow exactly like Telegram.
+
+## How It Works
+
+Aitne connects to WhatsApp as a **linked device** (the multi-device feature
+in the WhatsApp mobile app), not through the WhatsApp Cloud API or a paid
+bridge such as Twilio. There is no business account, no bot token, and no
+inbound webhook to expose:
+
+- You scan a QR code once to link the daemon as a device on your account.
+- Incoming WhatsApp messages arrive over the linked-device connection.
+- The agent replies and sends notifications back through the same channel.
+- It is **owner-only**: only DMs involving your one configured number are
+  accepted. Self-DMs you send from another linked device are also accepted,
+  so you can talk to the agent from your own number without a second account.
+  All other senders are dropped.
+
+## Setup
+
+You configure WhatsApp from the dashboard — there is no `aitne` CLI command
+for it.
 
-## What It Does
+1. Go to **Connections → Messaging → WhatsApp**.
+2. Set the **Owner phone** in E.164 format (e.g. `+818012345678`). This is
+   required before you can enable WhatsApp.
+3. (Optional) Set the **Auth dir** — where the linked-device credentials are
+   stored. Defaults to `~/.personal-agent/whatsapp/auth`.
+4. Click **Enable WhatsApp**, then **Pair device**. A QR code appears.
+5. On your phone: open **WhatsApp → Settings → Linked Devices → Link a
+   device**, and scan the QR code.
 
-- Receives WhatsApp messages routed through the configured number.
-- Sends notifications back through the same channel.
+Once the status shows connected, message your own number and the agent
+responds.
 
-## Where in the Dashboard
+### Configuration keys
 
-- **Connections → Messaging → WhatsApp**.
+| Key | Meaning |
+|---|---|
+| `whatsappEnabled` | Master on/off (default `false`). |
+| `whatsappOwnerPhone` | Owner number in E.164 format. Validated; must start with `+` and 8–15 digits. |
+| `whatsappAuthDir` | Directory holding linked-device credentials. |
 
 ## When Something Goes Wrong
 
-- WhatsApp's webhook timed out: check that the daemon is reachable
-  from the WhatsApp side (the simplest way is a tunnel during dev).
+- **QR code expired.** Each QR is short-lived and rotates. Click **Refresh
+  QR** in the dashboard to get a new one, then scan it.
+- **WhatsApp says the device is unlinked**, or pairing keeps failing. Click
+  **Reset connection** in the dashboard. This wipes the cached pairing data
+  in the auth dir so you can scan a fresh QR from scratch.
+- **Session logged out.** If WhatsApp logs the device out (account banned,
+  device conflict, or you unlinked it from the phone), the connection stops
+  retrying and surfaces an error. Use **Reset connection**, then **Pair
+  device** again.
 
 ## Related
 
 - [Messaging Overview](overview.md)
+- [Pairing and the Magic Phrase](pairing-and-magic-phrase.md)

package/agent-assets/docs/features/operations/activity-and-conversations.md

@@ -18,6 +18,7 @@ tags:
   - core
   - operations
   - audit
+  - dashboard
 status: stable
 ask_examples:
   - Where can I see what the agent did today?
@@ -25,7 +26,7 @@ ask_examples:
   - How do I find why a routine failed?
 locale: en-US
 created: 2026-04-25
-updated: 2026-04-25
+updated: 2026-05-28
 keywords:
   - activity
   - conversations
@@ -36,6 +37,12 @@ related:
   - features/operations/notifications
   - features/operations/cost-tracking
   - features/operations/backend-routing
+config_keys:
+  - executeTimeoutMinutes
+process_keys:
+  - routine.morning_routine
+api_endpoints:
+  - POST /api/system/purge-history
 ui_anchors:
   - /
   - /activity
@@ -62,15 +69,16 @@ Activity is the unified view of:
 
 Each row links to the underlying conversation when one exists.
 
-## When It Runs / How It Is Triggered
+## How It Works
 
-There is no trigger — Activity is a read-only projection. It is
-written to as a side-effect of every other event in the system
-(`agent_actions` / `conversation_sessions` / `messages`).
+Activity has no trigger of its own — it is a read-only projection.
+Every other event in the system writes to it as a side effect, landing
+in three SQLite tables: `agent_actions` (what happened), and
+`conversation_sessions` + `messages` (what was said).
 
-## What It Outputs
+## What You See
 
-- A timeline filterable by event type, ProcessKey, backend, outcome.
+- A timeline filterable by event type, ProcessKey, backend, and outcome.
 - Per-row cost, token counts, and turn count.
 - A direct link to the message transcript for any session.
 
@@ -81,21 +89,42 @@ written to as a side-effect of every other event in the system
 - **Conversations (`/conversations/<id>`)** opens a single session's
   message-by-message transcript.
 
+To read the morning routine's full reply, open Activity, filter to the
+`routine.morning_routine` row, and click through to its conversation —
+the transcript holds the agent's complete output, not just the summary
+that reached your DM.
+
 ## Configuration
 
 There is nothing to configure on the Activity view itself; what shows
 up is a function of which routines are enabled and which integrations
-are connected. Retention is unlimited locally — the SQLite database
-keeps everything until you `aitne stop && rm ~/.personal-agent/data/personal_agent.db*` (the `*` also clears the `-shm`/`-wal` companions).
+are connected.
+
+Retention is unlimited locally — the SQLite database keeps every row
+forever. To prune history without losing your configuration, use
+`POST /api/system/purge-history` (it clears `agent_actions`,
+`conversation_sessions`, and `messages` but leaves settings and the
+context vault intact). To wipe everything, `aitne uninstall --wipe-data`
+removes the whole `~/.personal-agent` data directory after a `WIPE`
+confirmation.
 
 ## When Something Goes Wrong
 
-- A row showing **"timed out"** points at a backend or SDK hang.
-  `executeTimeoutMinutes` (`/settings/models`) is the wall-clock cap.
-- A row showing **"fallback"** means main backend failed; check the
-  detail for the `BackendQuotaError` / `BackendDecisiveFailure`.
-- A row showing **"blocked_absolute"** means the absolute-block layer
-  refused a tool call. The detail names which tool and why.
+To find why a routine failed, open Activity, filter the outcome to
+**failed**, and open the offending row. Its outcome label tells you the
+failure class; the linked conversation shows the exact error and the
+turn it happened on.
+
+Common outcome labels:
+
+- **"timed out"** — a backend or SDK hang. `executeTimeoutMinutes`
+  (`/settings/models`) is the wall-clock cap.
+- **"fallback"** — the main backend failed and routing moved to the
+  fallback; the detail carries the `BackendQuotaError` or
+  `BackendDecisiveFailure` that triggered it.
+- **"blocked_absolute"** — the absolute-block layer refused a tool call.
+  The detail names which tool and why (logged as
+  `agent_actions.action_type='blocked_absolute'`).
 
 ## Related