@xema/omni-protocol 0.1.106 → 0.1.108

package/guide.md

@@ -11,6 +11,23 @@ their contract type or use `satisfies` so the relationship between the example a
 visible and compiler-checkable. Use another language only when the artifact itself is not
 TypeScript.
 
+## The guide in files
+
+This file holds what every reader needs and what the others rely on: the terms, the shapes, the
+contract rules, how an adapter is declared, signed in, connected and heard from, and how a
+conformance run holds it to all of that. The rest is by role and by channel, one file each, and
+every cross-reference names the file it points into.
+
+| File | |
+| --- | --- |
+| `guide/agent.md` | **The agent's work.** What an agent does on any channel: the assignment from offer to wrap, the task and its record, the controls a task offers, the commands the desk sends. |
+| `guide/voice.md` | **Voice.** What is true of a call and of nothing else: preview, connecting back, ending a call, conference, every dial and its outcome, recording. |
+| `guide/phone.md` | **The phone.** How the agent hears the call: softphone and desk phone, the station and its headset, opening the audio, the microphone and the record. |
+| `guide/chat.md` | **Chat.** What is true of a chat and of nothing else. |
+| `guide/email.md` | **Email.** What is true of an email and of nothing else. |
+| `guide/breaks.md` | **Breaks.** Asking for a break, a break forced on the agent, capacity, and one break across several providers. |
+| `guide/lead.md` | **Team leads.** The lead's own surface: the team member list, the lead's commands, lead assist, listening to a call. |
+
 ## Terms
 
 **Define a vocabulary; do not merely list it** applies to this document's own prose. These words
@@ -28,10 +45,10 @@ are used precisely throughout and mean nothing looser here.
 | **Call** | The caller’s complete phone call, which may continue through IVRs, queues and several agents. The protocol never describes the IVR or the queue; it carries the call's history and details to whichever agent holds it now. |
 | **Assignment** | The call routed to this agent, from the offer until the task ends. It is the one thing that crosses: the provider assigns, names the assignment with `assignmentId`, and that is the only name the desk ever uses back. A call that comes back is a new assignment on the same call, and a declined or lapsed offer is an assignment that became nothing more. What the platform calls its own record, and whether it reuses that name, is the adapter's business and unknown to the desk. |
 | **Interaction** | The agent's time on the call, from answer until their audio ends: the `in-progress` and `paused` phases. An assignment produces at most one interaction, and a call that returns produces a new assignment and so a new interaction. |
-| **Task** | The desk's record of one assignment, from offer through wrap: the workspace, controls and completion work the agent has for it, described by the provider and held by the desk. A task is identified by the assignment it is the record of. `pending`, `confirmed` and `preview` are assigned and not yet interacting; `in-progress` and `paused` are the interaction; `completing` is the assignment outliving its interaction. A voice task is one assignment, never the caller's whole call. |
+| **Task** in `guide/agent.md` | The desk's record of one assignment, from offer through wrap: the workspace, controls and completion work the agent has for it, described by the provider and held by the desk. A task is identified by the assignment it is the record of. `pending`, `confirmed` and `preview` are assigned and not yet interacting; `in-progress` and `paused` are the interaction; `completing` is the assignment outliving its interaction. A voice task is one assignment, never the caller's whole call. |
 | **Channel** | The kind of work a provider carries: `voice`, `chat`, or `email`. Fixed per provider by its manifest. |
 | **Task type** | The provider's own name for a category of work — a queue, a mailbox folder, a chat source. Free-form, and finer-grained than a channel. |
-| **Capability** | A provider's declaration that a control exists for a task or a session. It says *offer this*; the provider performs it, and the agent application only offers it — see **Where a command executes**. |
+| **Capability** | A provider's declaration that a control exists for a task or a session. It says *offer this*; the provider performs it, and the agent application only offers it — see **Where a command executes** in `guide/agent.md`. |
 | **Login** | One authenticated sign-in to one provider, identified by `loginId`. A transport reconnect keeps it; signing in again replaces it, and nothing tied to the old `loginId` survives. |
 | **Transport** | The adapter's connection to its platform: a WebSocket or SignalR connection, required to be persistent and ordered. Which one and how it reconnects are the adapter's business; losing it does not end a login. |
 | **Connection** | The `Connection` object Omni holds for one login: the methods it can call and the events it receives. |
@@ -40,8 +57,8 @@ are used precisely throughout and mean nothing looser here.
 | **Event** | One completed transaction reported after a snapshot established the baseline. |
 | **Break** | A reported, supervised state in which the agent is not working — one with a reason, a decision behind it and a return. It covers what a platform may call *not-ready*, including equipment trouble. An agent who is merely at capacity is not on a break. |
 | **Workspace** | What Omni shows the agent. The **task workspace** holds the selected task, its controls and its browsers; the **idle workspace** holds what a provider contributes when no task is selected — dialpad, contacts, calendar, team member list. |
-| **Dial** | One outbound call the agent application asks a provider to place — from the idle dialpad, a preview's Call, a conference add, or a connect-back. Identified by the agent application's `dialId`, accepted as `dialling`, and ended by exactly one `dial-outcome`. See **Every dial has an outcome**. |
-| **Listen** | A lead's channel in a member's call, unasked, from the team member list: `listen` in silence, `coach` heard by the agent alone, `join-call` heard by everyone. It is a team act naming the member, never a task on the lead's desk; `listen` and `coach` leave no trace on the member's task, while a lead heard by everyone is on its `onCall` as an `agent`. Every lead sees every lead on the call. A lead who wants the call takes it over. See **Listening to a call**. |
+| **Dial** | One outbound call the agent application asks a provider to place — from the idle dialpad, a preview's Call, a conference add, or a connect-back. Identified by the agent application's `dialId`, accepted as `dialling`, and ended by exactly one `dial-outcome`. See **Every dial has an outcome** in `guide/voice.md`. |
+| **Listen** | A lead's channel in a member's call, unasked, from the team member list: `listen` in silence, `coach` heard by the agent alone, `join-call` heard by everyone. It is a team act naming the member, never a task on the lead's desk; `listen` and `coach` leave no trace on the member's task, while a lead heard by everyone is on its `onCall` as an `agent`. Every lead sees every lead on the call. A lead who wants the call takes it over. See **Listening to a call** in `guide/lead.md`. |
 | **On the call** | Who a voice task's audio joins, or is bringing in, as the provider states it on `Task.onCall`: the party, the agents, and anyone conferenced in from the moment their dial is placed. |
 
 These fields describe state within their containing objects. Both authentication and break
@@ -182,6 +199,24 @@ type DialOutcome = "answered" | "busy" | "no-answer" | "unreachable" | "rejected
 
 type Phone = "softphone" | "deskPhone";
 
+type PhoneStatus = "ready" | "unregistered" | "do-not-disturb" | "off-hook";
+
+type PhoneChannelState = "ringing" | "active" | "held";
+
+type PhoneChannel = {
+  state: PhoneChannelState;
+  since: IsoTimestamp;
+  assignmentId?: AssignmentId;
+};
+
+type PhoneState = {
+  phone: Phone;
+  status: PhoneStatus;
+  muted?: true;
+  since?: IsoTimestamp;
+  channels: PhoneChannel[];
+};
+
 type IdleCapabilities<C extends Channel = Channel> = {
   personalBrowser?: PersonalBrowserCapability;
   calendar?: true;
@@ -202,6 +237,7 @@ type Manifest<C extends Channel = Channel> = {
   orgLevels?: LevelDeclaration[];
   dialOutcomes?: C extends "voice" ? DialOutcome[] : never;
   phones?: C extends "voice" ? Phone[] : never;
+  phoneStatus?: C extends "voice" ? true : never;
   runningStepReports?: true;
   settleMs: number;
 };
@@ -481,6 +517,7 @@ type Snapshot = {
   contacts?: Contact[];
   calendar?: ScheduledActivity[];
   shift?: Shift;
+  phone?: PhoneState;
   team?: TeamMembers;
 };
 
@@ -917,7 +954,7 @@ the capability's own name because it is the same capability at another level: ef
 command `hold` acts on one call; the preference `hold` says whether the person wants the control
 at all, and an agent application renders it in its settings, never as the button on a call. Mute is in none of
 these ladders: the microphone is the agent application's, and nobody on the provider's side allows, locks or
-keeps a choice about it. See **The station is the agent application's**.
+keeps a choice about it. See **The station is the agent application's** in `guide/phone.md`.
 
 ## Breaks
 
@@ -989,6 +1026,7 @@ type TeamMember = {
   listening?: MemberListening[];
   shift?: Shift;
   request?: MemberRequest;
+  phone?: PhoneState;
 };
 
 type MemberRequest = {
@@ -1145,7 +1183,8 @@ type ProviderEvent =
   | { type: "team-policies-updated"; policies: TeamPolicies }
   | { type: "contacts-updated"; contacts: Contact[] }
   | { type: "calendar-updated"; calendar: ScheduledActivity[] }
-  | { type: "shift-updated"; shift: Shift };
+  | { type: "shift-updated"; shift: Shift }
+  | { type: "phone-updated"; phone: PhoneState };
 
 type ProviderEventEnvelope = {
   id: string;
@@ -1444,7 +1483,7 @@ The commands every task has are authorized by other fields the provider declared
 offered can be accepted, one in `preview` can be called, any task under `agent-command` and one
 with a wrap under `provider-automatic` can be completed.
 Nothing is issuable that the provider did not publish; only
-which field says so varies. See **Which commands need a capability**.
+which field says so varies. See **Which commands need a capability** in `guide/agent.md`.
 
 ### 5. Snapshots establish state; events report transactions
 
@@ -1636,11 +1675,12 @@ compile time.
 | `phaseLabels` | Optional static adapter-defined display names for canonical `TaskPhase` values. They cannot vary at runtime. |
 | `taskTypePresentation` | Optional static adapter-defined presentation keyed by exact `taskType`. It names the item and its optional agent-facing reference. |
 | `orgLevels` | The organisation's whole ladder as the provider calls it, each level with the label a desk shows for "who decided". Stated outright, `person` included: what it leaves out does not exist. Omitted for the typical four, `DEFAULT_LEVELS`. See **Who decides what an agent may do**. |
-| `phones` | Voice only, and required there: the phones this platform can put an agent on, `softphone` (the call's audio lands in the agent application) and/or `deskPhone` (a handset the platform rings; the agent application shows the call and opens nothing). The agent application picks one per login. See **How the agent hears the call**. |
-| `dialOutcomes` | Voice only. How a dial can end on this platform, as it distinguishes them: `answered` and at least one way of not reaching the destination. Required of a provider that dials at all — an idle dialpad, or tasks that conference or call back — and a `dial-outcome` carries only a declared member. See **Every dial has an outcome**. |
+| `phones` | Voice only, and required there: the phones this platform can put an agent on, `softphone` (the call's audio lands in the agent application) and/or `deskPhone` (a handset the platform rings; the agent application shows the call and opens nothing). The agent application picks one per login. See **How the agent hears the call** in `guide/phone.md`. |
+| `phoneStatus` | Voice only, declared by presence as `true`: the platform sees the phone itself -- its registration, its do-not-disturb, its hook, its calls -- and publishes it as `Snapshot.phone` and `phone-updated`. A platform that cannot see the phone omits it, and then publishes no phone (`manifest.phoneStatus`). See **The phone's own view** in `guide/phone.md`. |
+| `dialOutcomes` | Voice only. How a dial can end on this platform, as it distinguishes them: `answered` and at least one way of not reaching the destination. Required of a provider that dials at all — an idle dialpad, or tasks that conference or call back — and a `dial-outcome` carries only a declared member. See **Every dial has an outcome** in `guide/voice.md`. |
 | `timeCheck` | `true`: implements `checkTime` and states `providerTime` on every snapshot. Required of a provider that publishes an instant the desk renders as a running duration -- a member's `since`, a `listening[].since`, an `onCall.since`, a shift's `signedInAt` -- so every screen counts from the provider's clock (`manifest.timeCheck.required`); agent application polling is independently opt-in. See **Every screen counts from the provider's clock**. |
 | `timestampAuthority` | Optional `"provider"`: provider timestamps are final; agent application instants are advisory. Omission makes no trust promise. |
-| `runningStepReports` | The provider takes running reports of an agent application-performed step — `recordStep` with `seconds` so far and no `ended`. Omitted, the agent application sends exactly two reports per leg, when it began and when it ended, and a running one is refused. See **The agent application records what it performs**. |
+| `runningStepReports` | The provider takes running reports of an agent application-performed step — `recordStep` with `seconds` so far and no `ended`. Omitted, the agent application sends exactly two reports per leg, when it began and when it ended, and a running one is refused. See **The agent application records what it performs** in `guide/agent.md`. |
 | `settleMs` | Required. How long after `applied` the wire shows what the provider did: the `task-ended` after a `complete`, the `calendar-updated` after a `schedule`. A positive whole number of milliseconds (`manifest.settleMs`). Stated per provider, since platforms settle at different speeds. See **`task-ended`**. |
 
 ### Authentication methods
@@ -1773,7 +1813,7 @@ in the agent's view would show that it had happened.
 `calendar` is available to voice, chat, and email providers. It contributes a calendar to the idle
 dashboard for callbacks and other scheduled activities associated with that provider. Calendar is
 the provider's: Omni displays activities and, where a task offers `schedule`, asks the provider to
-create one -- see **Scheduling a follow-up** -- but cannot reschedule, cancel, or complete them.
+create one -- see **Scheduling a follow-up** in `guide/agent.md` -- but cannot reschedule, cancel, or complete them.
 
 ```ts
 idleCapabilities: { calendar: true }
@@ -1896,7 +1936,7 @@ Creates the provider-scoped authentication session.
 | `protocolVersion` | The negotiated version, fixed for this login. |
 | `loginId` | Omni-generated identity for this login. The same value Omni later passes as `ConnectContext.loginId`, and how an adapter ties a connection back to the session that authenticated it. |
 | `timeZone` | The zone the agent's day is reckoned in, as an IANA name from the agent application's clock, stated before any identity exists so the first `authenticated` state already carries it. The same value Omni later passes as `ConnectContext.timeZone`. See **The agent's day**. |
-| `phone` | How this login hears its calls, chosen by the agent application from the manifest's `phones`: required for a voice provider, absent for any other. The same value Omni later passes as `ConnectContext.phone`. See **How the agent hears the call**. |
+| `phone` | How this login hears its calls, chosen by the agent application from the manifest's `phones`: required for a voice provider, absent for any other. The same value Omni later passes as `ConnectContext.phone`. See **How the agent hears the call** in `guide/phone.md`. |
 | `secrets` | Omni-provided `SecretStore`, scoped to this provider's manifest id. |
 | `signal` | Optional cancellation signal. |
 | `log` | Optional structured logging callback. Never include credentials, tokens, or sensitive contact data. |
@@ -1950,7 +1990,7 @@ to infer them from what arrives later.
 | Field | Contract |
 | --- | --- |
 | `breaks` | This login may request a break. Requires the four break methods on the connection. |
-| `lead` | This login leads a team. The flag alone turns on the team feature in the agent application, and every lead act comes with it; there is no per-action permission beside it. While the lead has the feature on, the provider publishes a `TeamMembers` object to them on every snapshot — `members: []` when nobody is in it — and to nobody else. Requires `executeTeam`. See **Team leads**. |
+| `lead` | This login leads a team. The flag alone turns on the team feature in the agent application, and every lead act comes with it; there is no per-action permission beside it. While the lead has the feature on, the provider publishes a `TeamMembers` object to them on every snapshot — `members: []` when nobody is in it — and to nobody else. Requires `executeTeam`. See **Team leads** in `guide/lead.md`. |
 | `preferences` | What the team left to this person, with where each stands and who set it. Omitted when nothing was. Requires `setPreference`. See **Who decides what an agent may do**. |
 
 A session action is available only when both the capability and Omni local policy permit it.
@@ -2103,9 +2143,9 @@ Creates one live provider connection for the signed-in agent.
 | `loginId` | Omni-generated identity for this login. It is the same value passed as `AuthenticationContext.loginId`, so an adapter can correlate this connection with the session that authenticated it. Stable across transport reconnects and changed only by a new login. |
 | `autoAcceptTasks` | Agent local policy policy relayed to the provider at login, stated by the agent application on every connection and never assumed from its absence. When `true`, a pending task states its `acceptance`; when `false`, every task requires agent acceptance. Fixed for this connection, like everything else here: the provider states or omits `acceptance` by the value it was sent, and Omni validates by that same value, not by a policy that has since moved — a change reaches the provider through a fresh `connect()`. |
 | `timeZone` | The same value passed as `AuthenticationContext.timeZone`. The provider stores it on the agent and carries it on the identity. See **The agent's day**. |
-| `phone` | The same value passed as `AuthenticationContext.phone`: how this login hears its calls. The type ties `host.mute` to it: a `softphone` login's agent application states what its Mute does, and a desk-phone or conversation login's agent application cannot, so the omission is a compile error rather than a live seat's discovery. See **The station is the agent application's**. |
+| `phone` | The same value passed as `AuthenticationContext.phone`: how this login hears its calls. The type ties `host.mute` to it: a `softphone` login's agent application states what its Mute does, and a desk-phone or conversation login's agent application cannot, so the omission is a compile error rather than a live seat's discovery. See **The station is the agent application's** in `guide/phone.md`. |
 | `store` | The login's operational store, kept by the agent application for the life of the login, across a reload of the agent application, and cleared at sign-out: where an adapter that composes a record keeps what its platform cannot hold for it, such as the interaction legs an agent application reported. Three functions, by key. Never for anything sensitive, which is `AuthenticationContext.secrets`, a store an agent application may clear aggressively. **A task's keys carry its assignment id and go with the task**: a key written about a task names the assignment id in the key, and is deleted before the task's end is published, so that nothing of a closed task survives its ending and nothing is left for whatever comes next -- a record with legs the agent application never reported against it. A login-scoped key carries no assignment id and outlives any task. The harness requires the store of every connection (`store.shape`, `store.get`, `.set`, `.delete`), watches the one it hands over, and names a task's key still held after `task-ended` (`drive.store.retained`) or written about the task after its end -- a persist hung off a timer that saw the task as it was (`drive.store.late`). The ordinary late write is the agent application's, not the adapter's: an agent application reports a leg without waiting for the answer, so an unmute can follow `complete` by a tick, and the adapter answers a report about a task that has ended `failed` with `omni.assignment-not-found` and writes nothing -- the agent application ends its own open legs at the task's end, so such a report is the agent application's error to see, and an agent application reads every `recordStep` answer and awaits the one for the leg it closes at a task's end, the only moment a refusal is expected, since a report nobody waits for is an error nobody can see; an adapter that names no task in its keys gets no cleanup check, which is a gap rather than a pass, never an exemption: the obligation is that nothing of a closed task survives its ending, and an adapter that keeps every open task in one login-scoped value owes exactly that inside the value, where the harness cannot look. One key per task, named for it, is the shape the harness can hold, and the shape to reach for. The store lists nothing, so an adapter that needs to find its tasks keeps a login-scoped index of ids beside them; at the task's end it deletes the body first and reindexes after, since a crash between the two then leaves an index naming a task with no body, which a reader skips, where the other order leaves a body for a task that has ended, which is the hazard itself. A reader of the index tolerates an id with no body as an ending that was underway, not as corruption. |
-| `host` | The agent application's report of the agent's station — devices, permissions, network — to consult before declaring the agent ready to the platform, and on every change. See **The agent application reports, the adapter decides**. |
+| `host` | The agent application's report of the agent's station — devices, permissions, network — to consult before declaring the agent ready to the platform, and on every change. See **The agent application reports, the adapter decides** in `guide/phone.md`. |
 | `signal` | Optional cancellation signal. Stop startup promptly when aborted and do not begin new work. |
 | `log` | Optional structured logging callback. Never include credentials, tokens, or sensitive contact data. |
 
@@ -2166,13 +2206,14 @@ a capability it agrees with the login: a lead's snapshot carries `team`, nobody
 | `taskCount` | The provider's own count of those tasks, stated rather than inferred, and it must equal `tasks.length`. A snapshot with no work says `taskCount: 0` in so many words — a blank or unanswered state lacks the count and cannot pass as a confirmed empty. |
 | `contacts` | Required complete contact contribution when the manifest declares `contacts`; `[]` clears it. Omitted only when it does not. |
 | `calendar` | Required complete calendar contribution when the manifest declares `calendar`; `[]` clears it. Omitted only when it does not. |
+| `phone` | The phone as the platform sees it -- the device, whether it can take a call, its own mute where observed -- from a provider whose manifest declares `phoneStatus`; required there (`snapshot.phone.required`) and forbidden otherwise (`snapshot.phone.unexpected`). Replaced whole by `phone-updated`. See **The phone's own view** in `guide/phone.md`. |
 | `shift` | The agent's own day so far, as the provider counts it -- the same `Shift` their lead sees on the team member list, the same numbers from the same count. Replaced whole by `shift-updated`. Omitted only where the provider cannot say. See **The agent's day is on the wire**. |
 | `team` | Required `TeamMembers` when the login declares `capabilities.lead` and the lead has the team feature on, `members: []` when nobody is in it. Forbidden otherwise — the login is the permission, and a lead who turned the feature off gets nothing of the team. |
 
 ## Live connection
 
 `Connection` is what `connect()` returns. Its methods are documented in the sections that follow
-and under **Breaks**, **Team leads**, **Real-time audio** and **Task commands**; this is the whole
+and under **Breaks** in `guide/breaks.md`, **Team leads** in `guide/lead.md`, **Real-time audio** in `guide/phone.md` and **Task commands** in `guide/agent.md`; this is the whole
 surface in one place, and what obliges an adapter to implement each one.
 
 | Method | Implement it when |
@@ -2183,21 +2224,21 @@ surface in one place, and what obliges an adapter to implement each one.
 | `disconnect()` | Always. |
 | `refused(report)` | Always. The agent application tells the adapter what it would not take -- a snapshot it did not replace its state with, an event it dropped -- with every rule broken, so a refusal is visible on both sides. See **What the agent application does with what it refuses**. |
 | `setCapacity(capacity)` | Always. Nothing may be assigned until a capacity is stated, so there is no connection that does not receive it. |
-| `execute(request)` | Always. Every channel has commands no capability gates — see **Which commands need a capability**. |
+| `execute(request)` | Always. Every channel has commands no capability gates — see **Which commands need a capability** in `guide/agent.md`. |
 | `getUserDetails(ids)` | The adapter publishes any `UserId`: on `ForcedBreak.by` where a person forced it, a team member list, or `history[].by`. Each `User` carries its `timeZone`; a person whose zone the provider cannot name is omitted from the answer, as any unresolvable id is. |
 | `dial(request)` | The manifest declares `idleCapabilities.dial`, and with it `dialOutcomes`. |
 | `requestBreak(request)` | The login declares `capabilities.breaks`. |
 | `commitBreak()` | The login declares `capabilities.breaks`. Commit and cancel are not optional halves of it. |
 | `cancelBreak()` | The login declares `capabilities.breaks`. |
 | `endBreak()` | The login declares `capabilities.breaks`. |
-| `executeTeam(request)` | The login declares `capabilities.lead`: every lead act, on the team surface and nowhere else. See **Lead commands**. |
+| `executeTeam(request)` | The login declares `capabilities.lead`: every lead act, on the team surface and nowhere else. See **Lead commands** in `guide/lead.md`. |
 | `setPreference(request)` | The login declares `capabilities.preferences`: the person's choice has to have somewhere to go. |
-| `recordStep(report)` | The manifest lists `softphone` among its `phones`. On a softphone the agent application mutes its own microphone on any call, and the provider's record has to have somewhere to take that leg; a desk phone's microphone is the phone's. See **The agent application records what it performs**. |
+| `recordStep(report)` | The manifest lists `softphone` among its `phones`. On a softphone the agent application mutes its own microphone on any call, and the provider's record has to have somewhere to take that leg; a desk phone's microphone is the phone's. See **The agent application records what it performs** in `guide/agent.md`. |
 | `openAudio(request)` | The manifest lists `softphone` among its `phones`. On a softphone the call's audio lands in Omni, so the adapter has to open it; a platform of desk phones alone never does. |
 
 **The four break methods stand or fall together.** Declaring `capabilities.breaks` at login and then
 implementing `requestBreak` without `commitBreak` leaves an agent granted a break that can never
-start, and the two-phase coordination in **Coordinating a multi-provider break** has no way to
+start, and the two-phase coordination in **Coordinating a multi-provider break** in `guide/breaks.md` has no way to
 report that: `granted` is a promise to honour a later commit.
 
 ### `Connection.snapshot()`
@@ -2267,2699 +2308,6 @@ Stops the connection and releases adapter-owned resources.
 - Must remove event handlers and release audio resources owned by the adapter.
 - Does not imply that active tasks were completed or removed.
 
-## Task assignment lifecycle
-
-The task-assignment lifecycle has five ordered stages:
-
-**1. The agent signs in.** Nothing on the wire says ready or not-ready: the agent is not ready
-until the agent application has stated a capacity, and ready once it has. A provider assigns nothing before a
-capacity is stated, and needs no other word for it.
-
-**2. The agent becomes ready.** The agent application states the capacity when its local policy says: at once,
-or when the agent presses Ready. A successful connection, a healthy provider, or the absence of a
-break does not imply readiness. After that, an agent stops taking work on this provider only by a
-break under `capabilities.breaks`, or by the agent application restating `count: 0` -- which is how
-a forced break on another provider reaches this one; a login that declares no breaks has no
-not-ready of its own, and `count: 0` is the agent application's division of capacity, not the
-agent's choice.
-
-**3. Omni states their concurrent capacity.** Only now does Omni ask providers for work, saying how
-much the agent can take at once. It is a standing declaration rather than a poll: Omni restates the
-capacity every time it changes, in either direction, and does not ask again while that value holds.
-Silence keeps the last one in force, so a provider that waits to be asked a second time will never
-deliver again once it has gone quiet. Hold the capacity and deliver when work arrives.
-
-**4. A provider offers a task.** The provider emits `task-offered` within the stated capacity, and
-the task is `pending`: an offer introduces work nobody has accepted, so it is the only phase an
-offer introduces (`event.taskOffered.phase`). `confirmed`, `preview` and the rest are reached from
-it, or carried on a snapshot.
-
-**5. Omni decides how the task is accepted.** When `autoAcceptTasks` is `false`, every task requires
-agent acceptance. When it is `true`, the pending task's `acceptance` states the provider's
-intent.
-
-### Acceptance modes
-
-During login, Omni sends the agent's `autoAcceptTasks` value to the provider. When it is `true`, the
-provider states `acceptance` on each pending task — on the task rather than the offer, so a
-reconnect snapshot says it too and an offer the agent application never received is not accepted on the
-person's behalf for want of a word:
-
-| Directive | Contract |
-| --- | --- |
-| `no-preference` | The provider leaves acceptance to Omni; with `autoAcceptTasks: true`, Omni accepts automatically. |
-| `consent` | The provider requires the person's explicit consent: Omni presents **Accept** and waits, whatever its own policy would have done. An agent application that declares `guarantees.personConsent` promises exactly this; a provider checks it before offering work only a person may take. |
-| `automatic` | Omni accepts immediately without agent interaction. |
-
-When Omni sent `autoAcceptTasks: false`, the provider omits `acceptance` and every task the
-queue routes requires agent acceptance. The two are never confused on the wire: `consent` is always the
-provider's requirement, stated on a wire where Omni was willing to accept for the agent; Omni's own
-no-auto-accept policy puts no word on the wire at all — the field is absent, and the **Accept**
-press is Omni's doing, not the provider's.
-
-**The value is stated, never assumed.** `autoAcceptTasks` is required of every connection: a
-agent application says which policy the deployment provisioned, and a validator that is not told checks
-neither rule rather than guess the permissive one (`task.acceptance.required` and
-`.unexpected` fire only against a stated value). `acceptance` is the provider's own control and
-outranks the policy: `consent` puts the decision back in the agent's hands for any task where it
-belongs, whatever the agent application was configured with.
-
-An automatically accepted task still arrives through `task-offered`.
-
-**Work the agent originated is accepted by the command that created it.** A task born of the
-agent's own act — a dialpad call or a connect-back, recognisable by the agent application's `dialId` on
-`onCall`; a call a lead took over, carrying `takenOver` — arrives
-through `task-offered` with `acceptance: "automatic"` whatever `autoAcceptTasks` says, and the
-validator holds it there under either local policy and under none (`task.acceptance.originated`):
-the desk shows no **Accept** for a call the agent placed. The local policy governs work the queue
-routes to the agent, and nothing else.
-
-### Pending
-
-A task in the `pending` phase has been **offered to the agent and not yet accepted**. Omni applies
-`autoAcceptTasks` and the task's `acceptance` to decide whether acceptance is
-automatic or requires the agent. A provider that requires automatic acceptance still emits
-`task-offered`; it does not introduce new work as `in-progress`.
-
-```ts
-declare const task: Task;
-
-const assignment = {
-  type: "task-offered",
-  task: { ...task, phase: "pending", acceptance: "consent", expiresInSeconds: 30 },
-} satisfies Extract<ProviderEvent, { type: "task-offered" }>;
-```
-
-The rule the phase exists to express: **nothing is acquired on the agent's behalf while a task
-is pending.** An agent application that carries audio must not open the microphone until the task is
-accepted. Omni does not open the task's browsers either — a task that rings out costs nothing.
-
-When consent is required, Omni offers the agent an **Accept** control. The call is the
-medium the task arrives on, not a separate decision.
-
-**Once a task is accepted, the call that comes with it is answered.** Omni has no discretion
-there and the provider is not consulted twice: one decision about the work, and the medium
-follows it. Where the audio lands was settled at sign-in — in Omni on a softphone, on the handset
-on a desk phone — and is not in question per call. See **How the agent hears the call**.
-
-Automatic acceptance still begins with `task-offered`.
-
-`expiresInSeconds` is how long the offer has left, in whole seconds from the publication that
-carries it. It rides on the pending task, as `acceptance` does, so a reconnect snapshot restates
-it from what is actually left; it belongs to `pending` alone and is gone once the task is accepted
-(`task.pending.expiresInSeconds`, `.unexpected`). Where present, Omni counts down from receipt and
-stops offering **Accept** once it runs out; the provider ends the lapsed offer with `task-ended`
-and an `expired` outcome naming `pending`, since nobody cancelled it. **Omit it unless the provider can observe it.** A provider that reports only elapsed
-ring time after the fact cannot say how long an offer has left, and a computed value would have
-Omni withdraw **Accept** from a task still pending.
-
-**A deadline is seconds left, never an instant.** The agent application and the provider keep
-different clocks, and a countdown that compares one against the other is a countdown that runs
-fast or slow by their skew. Seconds from the publication that carries them are the provider's own
-arithmetic, counted down on the desk from the moment they arrive, and the transport delay is the
-only error. Restated on every publication that carries them, so a snapshot after a reconnect
-starts the countdown afresh from what is actually left (`task.pending.expiresInSeconds`,
-`task.preview.previewEndsInSeconds`: a whole number, zero or more).
-
-A preview's deadline is not on the offer. It travels on the task, as `previewEndsInSeconds` with
-`atDeadline`, so a snapshot carries it too -- see **Preview: the agent presses Call**.
-
-A provider may withdraw a pending task by emitting `task-ended` with a `cancelled` outcome, `by:
-"provider"`. **`cancelled` says who called the work off**, as `completed` says who completed it:
-`agent` for a decline, `provider` for a withdrawal or a re-route, `party` for a caller who abandoned
-the ring. One word for the three left a supervisor's record unable to tell them apart, so `by` is
-required and closed (`event.taskEnded.outcome.cancelled.by`). An offer nobody acted on while
-`expiresInSeconds` ran is not cancelled by anyone: it lapses, and ends `expired` naming `pending`.
-
-### Tasks already in progress
-
-The provider does not introduce new work as already `in-progress`.
-
-A task appears already `in-progress` only in a snapshot taken after a reconnect or a resync,
-reporting work that began earlier in this login and never stopped. A fresh login has none to
-report: nothing has been assigned yet, and work the agent was working elsewhere is not carried
-into a new session.
-
-## Tasks
-
-### `Task`
-
-`Task` is the provider-owned description of one task presented to Omni.
-
-`task-offered` introduces a new task and does not imply acceptance.
-
-`Task<C>` is channel-discriminated. For example, `Task<"email">` accepts
-`browsers` and `outcomes`, but rejects voice-only controls such as `hold` and `endCall` at compile
-time. Runtime conformance checks also require the task channel to match its provider manifest.
-
-| Field | Contract |
-| --- | --- |
-| `assignmentId` | Required `AssignmentId`: the assignment this task is the record of, and its one identity. Issued by the provider, unique within the provider, never reused. Every event, command and report that names a task names it by this, so a late dial outcome or a late history report for one customer never lands on the next. The stream refuses an assignment introduced twice (`stream.taskOffered.duplicate`) and an audio or ending event naming one that has ended or that nobody has seen (`stream.assignment.ended`, `.unknown`); a `dial-outcome` may name an ended assignment, since a dial placed late routinely outlives its call, and the agent application routes it there. See **A task's life on the wire**. |
-| `title` | Agent-facing task title. |
-| `channel` | Channel used for this task. It must equal the source provider's manifest channel. |
-| `taskType` | Required provider-defined source or category of work, such as a voice `Queue Name`, `Mailbox Folder`, `Chat Source`, `Support`, `Billing`, or `Returns`. |
-| `capabilities` | Controls and workspace features available for this specific task. |
-| `capabilitySource` | Required. Who chose the capabilities: `queue` when somebody configured these terms, `nobody` when nothing handed the work over -- an agent's own outbound -- and `not-yet-read` when a queue was named and its terms could not be read, in which case `capabilities` is what the provider will honour, not what the platform permits. An agent application shows `not-yet-read` where the agent works. See **Task capabilities**. |
-| `browsers` | Named browser definitions for the task workspace: at least one when the task declares the `browsers` capability, empty when it does not. |
-| `party` | The person or entity on the other end of this task, as a `Contact`: often a name and one address; a withheld caller ID may leave nothing to send at all. Optional. The party is who the task is *with*; `contacts` is the directory. |
-| `phase` | Current canonical task phase: `pending`, `confirmed`, `preview`, `in-progress`, `paused`, or `completing`. `preview` is voice only. |
-| `audio` | Voice only. The task's real-time audio as the provider holds it: `started` while audio is attached, `ended` once it ended, omitted while none is. The provider's word — see **`task-audio-started`**. Audio names a task whose work has begun, or whose party the agent application is dialling: on a `pending`, `confirmed` or `preview` task with nobody ringing it is refused (`task.audio.beforeWork`), on a snapshot as on the event, since an agent application opens the microphone on it; with the party ringing by an agent application dial or provider-triggered preview dial, actual ring-back audio may precede answer. |
-| `acceptance` | How this offer is accepted — `no-preference`, `consent`, or `automatic` — stated on the pending task so a reconnect snapshot says it too. Required while `pending` when `autoAcceptTasks` was `true`, forbidden when it was `false`, and absent past `pending`. See **Acceptance modes**. |
-| `expiresInSeconds` | In `pending` only: how long the offer has left, in whole seconds from this publication, restated on every publication that carries it. Absent, the offer stands until the provider says otherwise. See **Pending**. |
-| `previewEndsInSeconds` | Voice only, in `preview`: how long the preparation has left, in whole seconds from this publication, restated on every publication that carries it. Absent, the agent has as long as they need without a preparation countdown. Always with `atDeadline`. See **Preview: the agent presses Call**. |
-| `atDeadline` | Voice only, in `preview`, with `previewEndsInSeconds`: what the system does when it runs out -- `provider-dials` makes the provider initiate dialing, `host-dials` makes the agent application issue Call, `waits` keeps the task in preview awaiting the agent. |
-| `reference` | Optional agent-facing reference such as a case, call, conversation, ticket, or message number. It is distinct from the protocol `id`. |
-| `completionMode` | `agent-command` waits for the channel's `complete` command; `provider-automatic` completes without one, and takes the agent's `complete` as finishing early. A required outcome is the agent's to give, so it needs `agent-command` (`task.outcomes.required.mode`). |
-| `wrapAllowance` | Fixed time allowed to complete the task after primary interaction ends. For real-time audio, it begins after `task-audio-ended`. Required under `provider-automatic`, where the provider acts on it. Optional under `agent-command`: omitted says the provider imposes no deadline, and Omni counts nothing down; stated, it is the expected wrap, shown and never acted on. `0` under `provider-automatic` is no wrap at all, so such a task publishes no `outcomes` (`task.outcomes.wrapAllowance`). |
-| `wrapEndsInSeconds` | In `completing`, wherever `wrapAllowance` is stated: how much of the wrap is left, in whole seconds from this publication, restated on every publication that carries it (`task.completing.wrapEndsInSeconds`, `.required`, `.unexpected`). A reloaded desk and a lead's screen count down the same number. See **Completion timing**. |
-| `attributes` | Optional ordered, typed `TaskAttribute` entries with keys unique within the task. Each contact or timestamp is a separate array item; new attribute shapes require new union members. |
-| `history` | The call record: `steps` — the ordered interaction history of this open task, one entry per occurrence, oldest first — and what they add up to before this agent, `interactionSeconds`, `holdSeconds`, `queueSeconds`, `transfers`, each present when the provider knows it. Live task data restated with the task, not a permanent archive. See **Interaction history**. |
-| `onCall` | Voice only. Who is on the call, or being brought onto it, as the provider states it, replaced whole with the task: `party` is the customer -- carrying a `stage` while being dialled again on the same task, a connect-back with the agent application's `dialId` or a platform's callback without, ringing from the moment the dial is placed and joined on its answered outcome --, `agent` a person by user id, `conferenced` somebody a dial is bringing in, listed from the moment the dial is placed -- with the `destinationId` dialled, the `dialId` where an agent application placed it, the `stage` reached (`ringing` until answered, `joined` after), and `held: true` on anyone joined and parked. `label` names a destination -- a person, a queue -- not a phrase; the agent application supplies the verb. Present when the provider knows the room, absent when it does not. See **Every dial has an outcome**. |
-| `leadAssist` | Voice only. Present from the agent's request for a lead until the lead leaves or the request ends: `requested` while nobody has joined, `joined` with the lead's `leadId` once somebody has. See **Lead assist**. |
-| `takenOver` | Voice only, on a task that reached this agent by a lead's take-over: which member the call was taken from, and when. It is an ordinary assignment with the call's history, offered whatever break the lead is on and counted against their capacity like any other call. See **Lead assist**. |
-
-`TaskAttribute` entries carry typed detail alongside the task:
-
-```ts
-const attributes: TaskAttribute[] = [
-  {
-    key: "related-contact",
-    label: "Related contact",
-    type: "contact",
-    party: { name: "Asha Rao", number: "+919876543210" },
-  },
-  {
-    key: "answered",
-    label: "Answered",
-    type: "timestamp",
-    at: "2026-08-27T09:30:00.000Z",
-  },
-];
-```
-
-`key` is the stable machine identifier and must be unique within the task's `attributes` array.
-`label` is the optional agent-facing name.
-
-The canonical task transitions are:
-
-| From | Decision or event | To |
-| --- | --- | --- |
-| No task | Provider assigns a task | `pending` |
-| `pending` | Task is accepted | `confirmed` |
-| `confirmed` | The customer's record is put in front of the agent before any call goes out (voice) | `preview` |
-| `confirmed` | Work begins | `in-progress` |
-| `preview` | Agent presses Call (`dial`) and the customer answers, or the deadline `provider-dials` and they answer | `in-progress` |
-| `preview` | The call goes out and nobody answers | `completing` |
-| `preview` | The preparation target passes with `atDeadline: "waits"` | Remains `preview`, waiting for the agent to press Call |
-| `pending` | Provider withdraws the assignment, the agent declines, or the party abandons the ring | Removed by `task-ended` with `cancelled` outcome, `by` saying which |
-| `pending` | The offer's `expiresInSeconds` runs out | Removed by `task-ended` with `expired` outcome naming `pending` |
-| No task | Snapshot reports work already underway | `in-progress` |
-| `in-progress` | Provider or agent pauses the task | `paused` |
-| `paused` | Provider or agent resumes the task | `in-progress` |
-| `in-progress` or `paused` | Contact interaction ends and follow-up work remains | `completing` |
-| `completing` | Agent connects back to the party (`connect-back`) | `in-progress` |
-| Any phase | Provider emits `task-ended` | Removed |
-
-#### A task's life on the wire
-
-A task has one name, the assignment it is the record of, and the provider issues it. Platforms
-reuse their own handles: a closed one is retired minutes later, a requeue takes seconds, and on
-one platform a call was offered twice, thirteen seconds apart, under one handle, through a close
-and a re-offer. Everything that names a task after the fact -- a dial outcome, an audio event, an
-ending, a history report, a command -- would land on whichever assignment is open when it arrives.
-So the assignment id is unique within the provider and never reused: where the platform's handle
-never comes back, the adapter passes it through; where it does, the adapter mints the assignment id
-and keeps the mapping, and the desk never learns which. A late event finds the assignment it
-belongs to or is refused, and a task-scoped browser session (`PROVIDER_NAME__ASSIGNMENT_ID__TAB_NAME`)
-lives one assignment, never the next customer's cookies. A dial the agent application placed was
-already safe, since its outcome is placed by the agent application's own `dialId`; where the
-assignment earns its place is everything the agent application does not mint --
-`task-audio-started`, `task-audio-ended`, `task-ended`, a `recordStep` naming a task -- any of which
-would otherwise find the next customer under a reused handle and act on them. A minted id is part
-of the task the adapter keeps, not a field held in memory beside it: it lives in the login's
-`store` with the task, or is derived from a platform handle that itself never reuses, so a rebuilt
-adapter comes back with the same assignment on the same task, or every late event it was minted to
-catch mismatches and the second adapter's snapshot no longer carries the task (`drive.reload.snapshot`).
-
-Assignment, acceptance, and progress are distinct. Acceptance follows `autoAcceptTasks` and the
-task's `acceptance`, moving the task from `pending` to `confirmed`. The provider reports
-subsequent transitions to `preview` or `in-progress`; Omni does not infer them from the acceptance
-command.
-
-#### Preview: the agent presses Call
-
-An outbound campaign that lets the agent see who they are about to call is a **preview**: the
-record arrives as a task and sits in `preview` with the party on it before a call goes
-out. The agent prepares; manual or declared automatic initiation may then begin dialing. It
-remains preview while ringing until an evidenced answer or non-answer outcome. The agent may press Call. That is the whole phase, and it exists on voice alone --
-chat and email have no call to place, and their reading is ordinary work in `in-progress`.
-
-```ts
-const previewed = {
-  channel: "voice",
-  capabilities: {},
-  phase: "preview",
-  party: { name: "Maya Rao", number: "+919876543210" },
-  previewEndsInSeconds: 120,
-  atDeadline: "provider-dials",
-} satisfies Pick<Task<"voice">, "channel" | "capabilities" | "phase" | "party" | "previewEndsInSeconds" | "atDeadline">;
-
-// The agent presses Call. It is a dial like any other.
-const pressed: TaskCommand<"voice"> = { type: "dial", dialId: "dial-7f2" };
-```
-
-**Call is a dial.** It carries the agent application's `dialId`, is answered `dialling`, and ends in exactly one
-`dial-outcome`; the phase is its gate and there is no capability, since a record put in front of an
-agent is there to be called. Its audio starts on `dialling`, as every agent application-placed dial's does --
-ring-back is audio the agent hears -- so `task-audio-started` arrives on the `preview` task with
-its party ringing. On `answered` the task is `in-progress`; on any other outcome the audio ends,
-`task-audio-ended` starts the wrap clock as on every voice task, and the task goes to
-`completing`, so the agent records the
-no-answer as the outcome it is -- in a campaign that is the commonest outcome there is, and it
-is work, not a cancellation. A `preview` task therefore needs a manifest that says how a dial ends
-(`task.preview.dialOutcomes.required`).
-
-**Preparation and trigger ownership are per task.** Unlimited preparation omits both
-`previewEndsInSeconds` and `atDeadline`: only an agent pressing Call starts dialing. Fixed
-preparation carries the seconds the provider says are left, counted down on the desk from the
-publication that carried them and restated on every later one, and exactly one trigger owner:
-
-| Declaration | At preparation end |
-| --- | --- |
-| `atDeadline: "provider-dials"` | The provider initiates dialing. The agent application never sends a timer-triggered Call. |
-| `atDeadline: "host-dials"` | The agent application sends the ordinary `dial` command with a fresh agent application `dialId`. The provider does not independently auto-dial this task. |
-| `atDeadline: "waits"` | Neither side auto-dials. The task remains in preview until the agent presses Call. |
-
-The agent may press Call early in either fixed-preparation dialing mode, or at any time in
-`waits` mode. With `waits`, the countdown is a preparation target, not an expiry: when it reaches
-zero the UI says "Waiting for agent" and keeps Call available. There is no automatic task-ended,
-completion, dialing or phase change. No repeating timer action occurs on later snapshots. This differs
-from unlimited preparation only by displaying a preparation target. The former `expires` deadline
-value is not supported; elapsed preparation must not withdraw the task. For `provider-dials` and `host-dials`, the deadline ends
-preparation and triggers initiation; it does not promise ringing, playable audio or customer
-answer at that exact instant. Scheduling/dispatch delay must remain visible, and a failed or
-prevented initiation must be reported rather than leaving a silently expired countdown.
-A source eligibility threshold that may never trigger an attempt is not this promise.
-
-The two deadline fields travel together and only in preview. The countdown is the seconds the
-publication carried, counted from its receipt: the agent application infers no deadline where none
-was stated and reads no clock against another. Neither elapsed time nor submission changes the
-task phase: subsequent authoritative events state ringing, answer, audio and completion.
-
-An agent application must serialize manual clicks and its timer under the exact provider/login/task/assignment
-scope, allowing at most one unresolved submission. Recheck the current phase, deadline owner,
-assignment and whether an attempt already exists before dispatch. A new snapshot or policy update
-cancels an obsolete timer; login loss, disconnect, task end and assignment replacement fence its
-callback. Reconnect past a deadline first reconciles current task and attempt state; it must not
-blindly submit again. An uncertain prior submission remains unresolved, without automatic retry.
-The provider atomically arbitrates any residual manual/timer race and does not accept a second
-command as ownership of an already-running independent attempt.
-
-Agent application-triggered automatic dialing is an ordinary agent application dial: its result is `dialling` with the same
-agent application `dialId`, followed by exactly one correlated terminal `dial-outcome`. A provider-triggered
-dial has no invented agent application ID or agent application dial outcome. It reports source-evidenced party ringing,
-actual audio and customer answer separately. In preview with `atDeadline: "provider-dials"`, a ringing
-party without an agent application ID may carry actual pre-answer audio; the deadline alone permits no audio.
-Audio is still introduced/ended by the corresponding events and must not imply customer answer.
-Submission acceptance is never an answered outcome or permission to publish `in-progress` early.
-Unsupported source correlation/outcome/audio evidence remains an integration blocker.
-
-**Drop both fields when the phase moves.** A provider that builds the `in-progress` task by
-spreading the `preview` one carries `previewEndsInSeconds` and `atDeadline` with it, and the agent application refuses
-the update (`task.preview.deadline.unexpected`): the desk keeps the task as it last stood, and the
-provider is told through `refused` exactly which rule, so the state that looked right on its side
-is named on its side. The task past preview has no deadline to wait for, so it carries neither
-field.
-
-**Provider execution and agent application controls are distinct.** Answer, hold/resume, conference,
-lead assist and interaction completion are executed by the provider
-through the adapter. The task's applicable capability, phase, completion mode and command-specific
-prerequisites decide which controls are offered. Caller disconnect also executes at the provider. Microphone mute is agent application-owned, never a provider
-TaskCommand or task capability. The separately declared agent application recording facility keeps its existing
-recording contract; this distinction does not remove it or move provider call operations to the agent application.
-
-A caller journey may revisit the same agent while an earlier interaction still wraps. Each is its
-own assignment, and two open at once carry two assignment ids. Restore them unchanged on
-reconnect. Commands, audio, endings and history reports name the exact assignment; never retarget
-an old command to the newest interaction of a journey. `validateTaskCommandRequest` checks the
-request's assignment against the supplied published task and then its command prerequisites. The
-caller must select that task within the correct provider/login and recheck at the provider; the
-validator cannot prove source freshness or authorization.
-`task-ended` retires only that interaction's resources. Another interaction, caller channel or IVR/queue
-portion must not be cleared because this task ended. Snapshot counts include all still-owned wrap
-and active interactions; task completion is not caller hangup.
-
-**Voice describes the agent's interaction within the wider call.** The task defines that agent's
-workspace, tools, permissions, audio participation and completion work. The caller's channel may
-continue through IVR, queues, other agents, holds or conferences while this interaction ends or wraps.
-Completing this task ends this interaction responsibility; it is not evidence that the caller's channel
-or journey ended. Task audio describes this agent's attachment, not the lifetime of every party's
-connection. Commands retain their explicit targets and effects; task completion must not silently
-become a caller-disconnect operation.
-
-**A task is never its audio.** A voice task represents the agent’s interaction: the call is offered when it is
-routed to the agent and accepted as its `acceptance` dictates, and its presence and phase follow
-the provider's reports about the work — never the audio. Wherever audio moves — an offer, a hold, a
-conference leg joining or leaving, a lead joining, a take-over, a connect-back — the audio follows
-separately, arriving on `task-audio-started`, attaching through `openAudio` and ending with
-`task-audio-ended`. Omni does not ring,
-bridge, or hold a line. How the phone rings, whether it rings at all, and where legs join and leave
-are the adapter's and the platform's, transient, and decide neither when a task exists nor what
-phase it is in.
-
-The line runs between the provider's word and Omni's own senses. `task-audio-ended` is the
-provider's report that primary interaction ended — a fact about the work, which is why the completion
-allowance starts on it and the Connect back control appears on it — and Omni follows that report as it
-follows any other. What Omni never does is derive a task's state from its own audio session: a
-stream that drops, a track that ends, a transport that disconnects, a microphone that fails, an
-endpoint re-registering change nothing about the task until the provider says so. Structurally:
-`task-audio-started` and `task-audio-ended` alternate on a task whose work has begun, audio ends
-only where it arrived, what follows the audio ending is `completing` or `task-ended`, and every
-task is introduced once — `exerciseAdapter` holds the stream to that from the connect snapshot on,
-and `assertAudioFollowsTheTask` holds any sequence.
-
-#### Completion timing
-
-`completionMode` determines how completion is triggered. With `agent-command`, the provider keeps
-the task open until Omni sends the channel's `complete` command. With `provider-automatic`, the
-provider may complete the task without receiving that command.
-
-**The agent may finish early under either mode.** `complete` is issuable wherever there is a wrap
-to cut short: under `agent-command` it is the end, and under `provider-automatic` it says the agent
-is done before the allowance ran out, and the provider is free to end the task at once. Only a task
-with no wrap at all -- `provider-automatic` with `wrapAllowance: 0` -- has nothing to complete, and
-the command is refused there (`command.complete.wrapAllowance`). An ending the agent asked for says
-so, `completed` with `by: "agent"`, whichever mode the task was under.
-
-**A required outcome is the agent's to give.** A task whose `outcomes` says `required: true` waits
-for a code the agent chooses, so it completes on the agent's command: `provider-automatic` cannot
-wait for it, and the pair is refused (`task.outcomes.required.mode`). Optional outcomes may ride on
-a task the provider completes itself; the agent gives one if in time. And a code is given in wrap,
-so a `provider-automatic` task with `wrapAllowance: 0` publishes no `outcomes` at all
-(`task.outcomes.wrapAllowance`).
-
-**The allowance means one thing per mode.** Under `provider-automatic` it is what the provider
-acts on: the task ends when it runs out. Under `agent-command` it is the expected wrap, stated so
-the agent can see it: the desk counts it down and, past zero, shows how far over they are, and
-nothing acts on it -- the task waits for `complete` however long that takes, with its outcomes
-collected whenever the agent gives them. A provider that would end the task at a time is
-`provider-automatic`.
-
-**What is left travels with the task.** The allowance is the length; `wrapEndsInSeconds` is how
-much of it remains, stated on the `completing` task and restated on every publication that
-carries it, as `previewEndsInSeconds` is on a preview. A desk that reloads mid-wrap finds the
-number on the snapshot; a lead's screen finds it on the member; neither starts a clock of its own,
-and both count down from receipt. Under `provider-automatic` the provider ends the task when it
-reaches zero; under `agent-command` it is the expected wrap left, `0` once overrun, and nothing
-acts on it. Off voice, where `completing` is the provider's word that interaction ended, the field
-arrives with that word, so the clock starts nowhere else.
-
-`wrapAllowance` is fixed, and when it starts depends on whether the channel carries real-time
-audio:
-
-| Channel | Wrap allowance starts at |
-| --- | --- |
-| Voice and any channel with real-time audio | The `task-audio-ended` event |
-| Chat | The `task-updated` that moves the task to `completing`: the provider's word that the conversation is closed on its side; what is left arrives on that publication as `wrapEndsInSeconds` and is counted down from receipt |
-| Email | The `task-updated` that moves the task to `completing`: the provider's word that the platform has accepted the outgoing message; what is left arrives on that publication as `wrapEndsInSeconds` and is counted down from receipt |
-| Other non-audio channels | The `task-updated` that moves the task to `completing` |
-
-**Off voice, `completing` is the provider's word that interaction ended.** There is no audio event to
-carry it, so the phase does; an agent application starts the wrap clock at that publication and nowhere else. It
-is optional: a conversation with nothing to wrap moves from `in-progress` to `task-ended` and
-`completing` is never published. Under `provider-automatic` with a non-zero `wrapAllowance` it is
-required, because the clock has to start somewhere: a chat or email task the provider completes
-from `in-progress` with an allowance to run gave the agent none of it, and the stream refuses the
-ending (`stream.taskEnded.unwrapped`); an ending the agent's own `complete` brought forward says
-`by: "agent"` and is not that. Under `agent-command` the agent's `complete` is the end, from
-`in-progress` or from `completing` alike.
-
-```ts
-const emailCompletion = {
-  completionMode: "agent-command",
-  wrapAllowance: 120,
-} satisfies Pick<Task<"email">, "completionMode" | "wrapAllowance">;
-```
-
-In this example, the agent has two minutes after sending the email to add notes, select a
-outcome, and complete the task.
-
-`0` means no wrap under `provider-automatic`: the provider completes the task at the end of the
-interaction, and `complete` has nothing to cut short. Under `agent-command` it is an expected wrap
-of nothing -- the desk shows the overrun from the start -- and the task still waits for `complete`.
-
-There is no value meaning "unlimited", because a number that is not a duration would be read as
-one. A provider that imposes no deadline says so by **omitting** `wrapAllowance`, which
-only `agent-command` permits: the provider will not complete the task itself, so there is nothing
-for a deadline to trigger, and Omni counts nothing down. **Omitted and empty are different
-claims** applies -- omitted says there is no deadline to see, where `0` says the deadline is now.
-Under `provider-automatic` the field is required, because the provider is going to act on it.
-
-```ts
-const untimedWrap = {
-  completionMode: "agent-command",
-} satisfies Pick<Task<"voice">, "completionMode" | "wrapAllowance">;
-```
-
-Here the customer has hung up, `task-audio-ended` has been sent on time, the task is `completing`,
-and the agent takes as long as the work needs. Moving the task to `completing` late to avoid a
-deadline is not an alternative on an audio channel: the clock starts at a real event, and delaying
-that event would falsify the phase and everything timed from it.
-
-#### Connecting back during completion
-
-A task that declares `connectBack` lets the agent connect back to the party while the task is
-`completing` -- to finish what the call left unfinished, on the same task rather than a new one,
-whoever placed the call in the first place. Most such calls came in, so this is not a redial: the
-agent rings a party who rang them. Omni issues `{ type: "connect-back", dialId }`; it is issuable
-only in `completing`, and only where the capability is declared. The provider knows who the party
-is; the command carries no destination, and it is a dial like any other, so it carries the agent application's
-`dialId`, is answered `dialling`, and ends in one `dial-outcome`.
-
-On `dialling` the provider is placing the call and the task returns to `in-progress`: the agent is
-working again, and the wrap allowance is **discarded, not paused**. From there the call is
-reported as any call is -- `paused`, `in-progress`, and when its audio ends, `task-audio-ended`
-again, which starts a fresh allowance from that instant. A party who does not answer is a dial
-whose outcome says so and a call whose audio ended: the task returns to `completing` through the
-same event and the clock starts again from there. At no point is an agent dialling against a
-deadline.
-
-**The room shows the party being dialled.** From the moment any agent application dial places the party -- a
-dialpad call, a preview Call, a connect-back -- the `party` entry carries `stage: "ringing"` and
-the agent application's `dialId`, exactly as a conferenced entry does from its dial; `joined` on
-the publication that follows the answered `dial-outcome` and never before it
-(`stream.taskUpdated.stage`); and no stage from the next publication on, so `joined` is transient
-and a later copy still carrying it is stale (`stream.taskUpdated.stage.lingering`). An agent application shows a
-call being placed, not a party it asserts is on a call that is still ringing. A callback the platform places itself on the same task -- the first
-call over, the platform dialling the party again without a command -- shows the same thing with no
-agent application `dialId`, as any platform-placed dial does. A party with no stage is on the call, and a dial
-with no stage is half a claim (`task.onCall.party.dial`). The stage is also what lets the stream
-tell a task coming back from one going backwards (`stream.taskUpdated.phase`).
-
-**The control exists only while there is a window to use it in.** Under `agent-command` the task
-stays `completing` until the agent completes it, so the window is open for as long as they need.
-Under `provider-automatic` the window is the allowance -- and with `wrapAllowance: 0` there
-is none: the provider completes the task at provider end, and Omni does not offer Connect back,
-whatever the task declares. A capability names a control that can be used; on a task with no `completing`
-window it cannot, and declaring it there changes nothing.
-
-```ts
-const connectBackCapable = {
-  channel: "voice",
-  capabilities: { hold: true, connectBack: true, outcomes: true },
-  phase: "completing",
-  completionMode: "provider-automatic",
-  wrapAllowance: 30,
-} satisfies Pick<Task<"voice">, "channel" | "capabilities" | "phase" | "completionMode" | "wrapAllowance">;
-```
-
-With ten seconds of the thirty left, the agent presses Connect back: `execute({ command: { type:
-"connect-back", dialId } })` returns `dialling`, the task is `in-progress`, and the thirty seconds
-are gone.
-The second call ends: `task-audio-ended`, the task is `completing`, and a new thirty seconds runs
-from that instant.
-
-```ts
-const immediateProviderCompletion = {
-  completionMode: "provider-automatic",
-  wrapAllowance: 0,
-} satisfies Pick<Task, "completionMode" | "wrapAllowance">;
-```
-
-### History
-
-The record is the call's, not the task's: most of what it holds happened before this agent, and
-`queued` and `offered` are not interactions at all, so the field is `history` and its types are
-`TaskHistory`, `TaskHistoryStep`, `HistoryStep`, `HistoryReport` and `HistoryReportResult`.
-*Interaction* keeps the one meaning **Terms** gives it, the agent's time on the call, which is why
-the total of earlier agents' time is `interactionSeconds` and the phase rules are
-`command.phase.interaction`. Hosts and providers adopt these names together; no legacy aliases
-are provided. The manifest's `settleMs` bounds final task completion, not entry into
-the `completing` wrap-up phase, and bounds an applied `schedule` the same way. The `recordStep` method and `complete` command keep their names.
-
-Migration from the earlier spellings:
-
-| Former API | Current API |
-| --- | --- |
-| Task.handlingHistory, Task.interactionHistory | `Task.history` |
-| TaskHandlingHistory, TaskInteractionHistory | `TaskHistory` |
-| TaskHandlingStep, HandlingStep, TaskInteractionStep, InteractionStep | `TaskHistoryStep`, `HistoryStep` |
-| HandlingReport, HandlingReportResult, validateHandlingReport, and their Interaction spellings | `HistoryReport`, `HistoryReportResult`, `validateHistoryReport` |
-| HANDLING_STEPS_WITH_A_PERSON, HANDLING_STEPS_THAT_DIAL, and their INTERACTION spellings | `HISTORY_STEPS_WITH_A_PERSON`, `HISTORY_STEPS_THAT_DIAL` |
-| handlingStepExpectsAPerson, handlingStepDials, and their interaction spellings | `historyStepExpectsAPerson`, `historyStepDials` |
-| handleSeconds | `interactionSeconds` |
-| Task.allocationId, AllocationId, allocationExpiresAt | `Task.assignmentId`, `AssignmentId`, `expiresInSeconds` |
-| Task.id, TaskId, and `taskId` on every event, command, report and lead request | gone: a task is named by `assignmentId` alone, and `assignmentKey(providerId, assignmentId)` scopes it |
-| taskKey, omni.task-not-found, PROVIDER_NAME__TASK_ID__TAB_NAME (ProviderName.TaskId.TabName) | `assignmentKey`, `omni.assignment-not-found`, `PROVIDER_NAME__ASSIGNMENT_ID__TAB_NAME` (`ProviderName.AssignmentId.TabName`) |
-| Manifest.disposalSettleMs, Manifest.completionSettleMs | `Manifest.settleMs` (`manifest.settleMs`, `manifest.settleMs.renamed`): the bound after `applied` for `complete` and `schedule` alike |
-| the call command, atDeadline calls and host-calls | `dial`, `"provider-dials"`, `"host-dials"` |
-| media: task-media-started/-ended, team-media-*, Task.media, TaskMediaState, openMedia, OpenMediaRequest/Result, VoiceMediaSession and its session field | audio: `task-audio-started`, `task-audio-ended`, `audio` on the task, `TaskAudioState`, `openAudio`, `OpenAudioRequest`, `OpenAudioResult`, `CallAudio` on the result's `audio`; there is no team audio, the lead's follows `listening` on the member |
-| capabilitySource values ungoverned and undetermined | `nobody`, `not-yet-read` (`capabilitySource.notYetRead`) |
-| Snapshot.scheduledActivities, and scheduledActivities on calendar-updated | `calendar` in both |
-| availability reserved | `elsewhere` |
-| recording destinationId, HostRecording.destinationIds | `storageId`, `storageIds` (`recording.storage`, `recording.host.storage`) |
-| coldTransfer, warmTransfer, the transfer command and its four actions, the consulted role, the transferred outcome | gone: help arrives by **Lead assist**; the `transferred` history step and the `transfers` total stay, since the platform's own routing still changes hands |
-| assignmentExpiresAt on task-offered, previewEndsAt on the task | `expiresInSeconds`, `previewEndsInSeconds`: seconds left from the publication, never an instant (`event.taskOffered.expiresInSeconds`, `task.preview.previewEndsInSeconds`) |
-| TeamMembers.requests, LeadRequest | `TeamMember.request` (`MemberRequest`): the ask rides on the member (`team.member.request.*`) |
-| team-updated on every change | `team-updated` whole once after the switch and on snapshots; `team-member-updated`, `team-member-removed`, `team-policies-updated` after (`stream.team.baseline`, `stream.teamMember.unknown`) |
-| RecordingCommand.requestId | gone: no request identity; a partial effect is a settled `failed` under `omni.recording-unsettled` |
-| command.complete.mode | `command.complete.wrapAllowance`: `complete` under either mode, refused only on `provider-automatic` with no wrap |
-| expiresInSeconds on task-offered | `Task.expiresInSeconds`, in `pending` (`task.pending.expiresInSeconds`, `.unexpected`; `event.taskOffered.expiresInSeconds.unexpected`) |
-| the expired outcome naming preview | gone: nothing expires a preview; withdrawn, it is `cancelled` by the provider |
-| schedule on voice alone | `schedule` on every channel, under a manifest that declares `calendar` (`task.capability.calendar.required`), bounded by `settleMs` (`drive.schedule.unsettled`) |
-| a forced break requesting breaks on the other providers | `setCapacity({ count: 0 })` on every other usable provider (`assertForcedBreakStopsTheRest`) |
-| end-forced-break on a break the platform imposed | refused: `team.command.endForcedBreak.provider`, `omni.break-forced-by-provider` |
-| ForcedBreak.expectedDurationMs | `expectedEndsInSeconds`: seconds left, restated (`break.forced.expectedEndsInSeconds`, `.expectedDurationMs.renamed`); the command keeps `expectedDurationMs` |
-| MemberShift; the day on the lead's list alone | `Shift`, on `Snapshot.shift` and `shift-updated` for the agent, on `TeamMember.shift` for the lead |
-| TeamMember.listening as this lead's one entry | `MemberListening[]`, every lead's, each with `leadId` (`team.member.listening.leadId`, `.unique`, `.empty`, `.entry`, `.heard`) |
-| a member's history trimmed on the lead's list | the record whole, as the member's desk holds it |
-| durations counted from the screen's clock | the provider's: `timeCheck` required of a provider publishing a running instant (`manifest.timeCheck.required`), `Snapshot.providerTime` with it (`snapshot.providerTime`, `.unexpected`) |
-| a wrap the desk timed from an event's receipt | `Task.wrapEndsInSeconds` in `completing`, restated (`task.completing.wrapEndsInSeconds`, `.required`, `.unexpected`) |
-| MemberTask.capabilities, capabilitySource, browsers | gone: the workspace never travels to a lead (`team.member.task.workspace`); the record and the completion terms do |
-| a member republished on a hold, a mute, a take-over | on every publication of the member's task to the member |
-| two clients on one login | the later wins; the first is ended with `recovery: "displaced"` |
-
-Update producers, consumers, saved task snapshots, and validation-rule assertions together.
-History and report rule names use `history` and `historyReport`; assignment rules use
-`assignment` (`task.assignmentId`, `stream.taskOffered.duplicate`, `stream.assignment.ended`);
-phase and conformance rules use `interaction` and final-task rules use `completion`. The former
-fields are refused even when the new field is also supplied (`task.history.renamed`,
-`task.assignmentId.renamed` for a task's `id` or `allocationId`, `event.assignmentId.renamed`,
-`command.request.assignmentId.renamed` and `historyReport.assignmentId.renamed` for a `taskId`).
-
-
-`Task.history` is the call record: the steps that brought the task to the agent, oldest
-first, and what they add up to before this agent:
-
-```ts
-history: {
-  steps: [
-    { step: "queued",      at: "2026-08-21T00:59:00Z", seconds: 41 },
-    { step: "answered",    at: "2026-08-21T00:59:41Z", seconds: 312, by: "a-17" },
-    { step: "held",        at: "2026-08-21T01:02:10Z", seconds: 35, by: "a-17" },
-    { step: "transferred", at: "2026-08-21T01:04:53Z", by: "a-17" },
-    { step: "answered",    at: "2026-08-21T01:05:02Z", by: "a-23" },
-  ],
-  interactionSeconds: 312,   // handled by others before this agent
-  holdSeconds: 35,      // holds others put the caller on
-  queueSeconds: 41,     // waiting before anyone answered
-  transfers: 1,         // hands the call has changed
-}
-```
-
-**This is not an archive.** It is live data about a task that is still open: it travels with the task
-to whoever holds it next and ends when the task does. Nothing stores it, nothing queries it, and
-there is no archive behind it. A provider that keeps a record of *completed* contacts is describing
-something else, which will arrive under its own name and must not be folded in here.
-
-It rides in the snapshot and is replaced whole like everything else there.
-
-Steps are `queued`, `offered`, `answered`, `held`, `muted`, `transferred`, `conferenced`,
-`unanswered`, and each is defined on `TaskHistoryStep`.
-
-**The record is one entry per occurrence, oldest first.** Each hold is its own `held` entry — `at`
-when it began, `seconds` once it ended and omitted while it runs — and a second hold is a second
-entry after the first, never a revision of it. A leg that has ended states its duration, and the
-task says whether a leg can still be running: a hold runs only while the task is `paused`, a mute
-only while its audio is up, so a `held` entry without `seconds` on a task that is not paused, or a
-`muted` one on a call that is over, is a leg nobody closed and reads exactly like a leg running now
-(`task.history.held.open`, `.muted.open`). Whoever performs the leg closes it — the
-provider whose platform parks the caller, the agent application whose microphone it is — by restating the entry
-with its duration, and **an entry that cannot be closed is not written**: open for ever is a
-plausible nought one level down from a total. **A leg still open when the audio ends is closed by
-the provider**, at that instant, in the same publication that says the audio ended: the provider
-is the one that knows the instant, and the agent application can only learn of it afterwards. Agents end calls
-muted, so the agent application's leg is routinely open at audio end; the provider closes it with the duration
-from the leg's `at` to the audio's end, and the agent application's own closing report for that leg, which
-follows what it hears, is answered `recorded` and changes nothing, the entry standing as the
-provider closed it. One publisher of the closed leg, and no order between them to get right. There is no resumed step; a resume is the end of a
-hold, at the entry's `at` plus its `seconds`, and nothing is lost by not naming it twice. The same goes for every step: two mutes are two
-`muted` entries, and a call that joined two queues -- a menu's, then this one -- has two `queued`
-entries, one per join. Order is enforced: an entry earlier than the one before it is refused
-(`task.history.order`). **Intervals between steps are the agent application's to subtract**, never a
-total the provider adds: *time to offer*, from the call's arrival to the agent's screen lighting
-up, is the `offered` entry's `at` minus the last `queued` entry's, and the ring is outside it.
-`queueSeconds` keeps the industry's meaning -- the whole wait until somebody answered -- and is not
-that interval. **The second is the record's grain.** A duration is a positive whole number of
-seconds, and nought is refused because it claims no time; a leg that happened is stated at the
-grain: rounded to the nearest second, and a leg that rounds to nought is stated as `1`, the error
-being under the contract's resolution, where dropping the entry would say the leg never happened.
-
-**A record once read is not unread.** Every restatement of a task's record -- on `task-updated`,
-on a resync snapshot -- carries every entry the agent application has already read, by step and instant, and
-may add to them; it never has fewer, and never drops the record while the task is open. A fact
-stated to the agent application and then withdrawn without an event is a record contradicting itself, exactly
-as a task that lost the terms it had read would be, and the stream refuses it the same way
-(`stream.taskUpdated.history`, `stream.snapshot.history`). A provider whose
-platform cannot hold a leg the agent application reported keeps it in the login's `store` for the life of the
-task, so a reload of the agent application restates the same record; the entry is keyed by `step` and `at`, so
-a running hold restated with its final `seconds` is the same entry.
-
-**The provider owns the timestamps in its record.** Agent application timestamps are advisory. The provider
-may retain an agent application instant it accepts or assign its own observation/receipt instant; it need not
-copy the agent application clock. A provider declaring `timestampAuthority: "provider"` uses its own timestamps
-for final records. Receipt time is an observation boundary, not a claim about when the physical
-agent application action happened. Records are ordered by their published provider-selected instants, with no
-rewriting of an already-published entry when a later agent application report arrives.
-
-The incoming agent application `step` and `at`, scoped to the task and its current life, identify one reported
-leg for correlation only. The provider retains a binding from that key to its chosen history
-`at`. Every successful `recordStep` returns `{ status: "recorded", at }` with that same canonical
-history instant, even for subsequent duration/end reports. The agent application keeps sending the original
-report key, never the returned history timestamp. A changed agent application timestamp is not a correction
-to the same report: it names a different leg. Bindings survive reconnect/reload for the retained
-task lifetime. The agent application renders provider-published history unchanged. It never compares the
-provider instant back to its own clock, substitutes its own timestamp, or adjusts later messages
-to match an earlier agent application estimate. The acknowledgment identifies the provider record for
-correlation/conformance only; it is not an application-side timestamp reconciliation instruction. Conflicting reuse is refused visibly, not paired by arrival time or nearest instant.
-If two distinct entries would collide under the history's `(step, at)` key, do not invent a time
-or combine them: report the representation conflict. No ambiguous event is silently accepted.
-
-**Interaction time is anchored, not restarted.** It runs from the
-`answered` step's `at` — from the task's first `in-progress` where the provider reports no
-history — until the task's audio ends, and a hold neither pauses nor resets it: the hold's own
-duration is the `held` entry's `seconds`, and a desk that restarts its counter on resume is
-counting the wrong thing.
-
-`muted` is there because the mute is the agent application's and never the provider's — see **The station is
-the agent application's** — so without a step the provider, which alone keeps the task's record, would have no
-account of a period the agent could not be heard. Each `muted` entry carries `mutedBy`, as the agent application
-reported it: `host` for the agent's own Mute, `station` for a headset or system mute the agent application
-observed. No other step has it (`task.history.mutedBy`, `.mutedBy.unexpected`).
-
-**A step that dialled says which dial and where.** `conferenced` and `unanswered` each end a dial,
-and `transferred` a hand-over on the platform's own routing, so the entry carries the `destinationId`
-it went to and, where an agent application placed the dial, the `dialId` the agent application minted; no other step dialled, and either field on one is refused
-(`task.history.dialId.unexpected`). This is how a dial made before a take-over is placeable
-by whoever holds the task now: a `dial-outcome` naming a `dialId` the agent application never minted is looked
-up in the record, not discarded.
-
-Four rules a provider has to keep:
-
-- **Report `seconds`; never expect Omni to derive it.** Omni does not subtract one timestamp from
-  the next. An entry can be written while its leg is still running, so the arithmetic has no second
-  operand, and a provider holding the authoritative number should not have it recomputed from
-  instants that may be rounded or clock-skewed. And once stated, `seconds` is what every screen
-  shows for that leg: a count a screen kept while the leg ran is replaced by it, never kept beside it.
-- **Omit `seconds` while it is unknown. Never send `0`.** A leg still talking is not a zero-second
-  conversation, and on live data that is the ordinary case rather than an edge. A zero is rejected.
-- **`by` is a bare `UserId`, and not necessarily an agent.** A lead or a manager takes part
-  during an interaction too — a call taken over, a call conferenced in — so the field names whoever it was,
-  from the same directory `ForcedBreak.by` names a lead from. It comes from this provider's own directory, the same
-  namespace as `AuthenticationState.identity.id` and the team member list, so entries pair
-  within a provider and never across one.
-- **A task carries no names.** Omni resolves what to display with `getUserDetails()`. Two people
-  called Arun on one site is ordinary, and anything pairing entries on a display name pairs them
-  wrongly; carrying the name here would also copy it into every task and leave it to go stale.
-
-**An absent `by` means different things on different steps, and both are legitimate.** On
-`queued` nobody takes part, so there is nothing to name. On every other step somebody did — see
-`HISTORY_STEPS_WITH_A_PERSON` and `historyStepExpectsAPerson()` — so an absent `by` there says
-*this was handled and the provider cannot say by whom*. The one step that is never unattributed is
-`muted`: the agent application has exactly one agent and the provider knows who, so `by` is required there
-(`task.history.muted.by`).
-
-That case is ordinary rather than theoretical: a leg answered on a shared phone, a manager's
-handset, or a device the provider cannot resolve to a person. **Report the step without `by`
-rather than dropping it.** A list missing a real handler looks complete and is wrong, which is
-worse than one saying plainly it could not attribute a leg — and far better than publishing
-nothing because a single leg could not be named.
-
-An agent application must render the two differently. Showing an unattributed `answered` the same way as
-`queued` tells the agent nobody was involved, which is not what was said. Omni renders it as
-*"not recorded"* in the place the name would go.
-
-Omit `history` entirely when the provider cannot observe the steps. Empty `steps` is a
-different claim — it says the task has had none.
-
-**What the record adds up to is stated, not summed.** A call that has changed hands arrives
-carrying what others already used of it, and the agent reads that before they say hello: the
-totals are the provider's own — never a desk summing instants that may be rounded or skewed, for
-the same reason `seconds` is reported and not derived — and each is present when the provider
-knows it and absent when it does not, never a plausible nought. A fresh call from the queue has
-`steps` with no prior `answered` and no totals to state, and a desk shows nothing rather than
-zeros. The record is restated with the task on every `task-updated` and snapshot, so an entry
-that arrives late corrects the sums. These four are what every platform reports; more will be
-added here as a need is shown, not invented ahead of one.
-
-#### The agent application records what it performs
-
-`muted` is the one leg the agent application performs rather than the provider, and a record kept by the
-provider would have a hole exactly there. So the agent application reports it, through `recordStep`, and the provider
-writes it into its record as it writes every other leg:
-
-```ts
-declare const connection: Connection<"voice">;
-declare const assignmentId: AssignmentId;
-declare const at: IsoTimestamp;
-
-void connection.recordStep?.({ assignmentId, step: "muted", at, mutedBy: "host" });                          // the moment the agent mutes
-void connection.recordStep?.({ assignmentId, step: "muted", at, mutedBy: "host", seconds: 15 });             // still running, if the agent application chooses to say
-void connection.recordStep?.({ assignmentId, step: "muted", at, mutedBy: "host", seconds: 42, ended: true }); // the moment they unmute
-```
-
-Every report about one leg repeats its original `step` and agent application `at` as a correlation key;
-the published history uses the provider-selected `at` returned by `recordStep`. The agent application reports
-the action it performed and its measured duration, not an authoritative provider timestamp. It may say how long so far — `seconds` is
-elapsed while the leg runs and final once it has ended — and **the end is stated, never
-inferred**: `ended: true` marks the last report, and it carries the final duration. **What a
-provider never asked for never crosses.** The running report is sent only to a provider whose
-manifest declares `runningStepReports`; every other provider receives exactly two reports per
-leg, when it began and when it ended, and `validateHistoryReport(report, path, manifest)` refuses
-a running one it was never asked for (`historyReport.running.unexpected`). What a provider that
-did ask for them forwards upstream, and how often, is its own business. The step appears in
-`history` when the *provider* publishes it: Omni never writes the record itself.
-`recordStep` is required of every softphone login's connection, since every call on a softphone
-can be muted by the agent application, and answers `recorded` with the canonical history `at`. A `muted` report says whose the silence was,
-`mutedBy: "host"` or `"station"`, and no other report has the word (`historyReport.mutedBy`,
-`.mutedBy.unexpected`). On a desk phone the microphone is the phone's:
-the agent application mutes nothing and records nothing.
-
-**The record is a record.** The microphone is the agent application's, and nothing in the
-history moves it: a `muted` entry the provider publishes, or closes with a final `seconds`, is the
-provider's account of a leg the agent application reported, and the mute itself ends only when the
-agent, or the station, ends it. The agent application keeps its own mute state, reports each leg
-as it begins and ends, and takes the provider's published entry as the closed account of that leg:
-it does not reopen the leg, replace the provider's timestamp, or overwrite the provider's final
-duration with a later report. A later agent mute is a new leg, never a reopening of the ended one.
-
-Correlate the provider-published `muted` entry using the provider-selected `at` acknowledged
-for the current report key; a final `seconds` closes that leg under the history contract.
-This is identity matching, not reconciliation between clocks. An old closed entry, an unrelated
-task, or a stale connection cannot end a newer local mute. If publication precedes the acknowledgment,
-retain the current provider view and apply the matching closure once correlation is available;
-never guess a match from arrival order or nearest timestamp. Failure to release an agent application-controlled
-mute is reported visibly; local device reports still describe the actual device state.
-
-At a provider-confirmed task/audio end, the agent application also stops the associated local mute and reports
-its observed ending where the report is still accepted. An agent application closing report repeats its original
-key and may include its measured duration, but cannot reverse an already confirmed provider end.
-The provider acknowledges a known closed leg without rewriting its final record; after the task
-has been completed, it may refuse the report as assignment-not-found. The agent application reads that response rather
-than retrying or recreating the task. An observed agent application end before a provider closure is still
-reported normally; the provider decides the final timestamp and publishes the record.
-
-### Browser capability
-
-`browsers` is available to voice, chat, and email tasks. When declared, Omni renders the task's
-`TaskBrowser` entries as named browsers in the task workspace. A task that supplies one or more
-browser definitions must declare:
-
-```ts
-capabilities: { browsers: true }
-```
-
-Tasks without browser definitions omit the capability and provide an empty `browsers` array.
-
-**A browser is one tab, and each workspace keeps its own.** `Browser` is what a tab is — an id, a
-name, a URL. The task workspace shows the task's `TaskBrowser` entries, one tab each, fixed at the
-task's definition: their count and their details, `urlVisibility` included, arrive with the task,
-and nothing adds a tab to a task later. The personal workspace is the agent's: as many
-`PersonalBrowser` tabs as they open, never on the wire, and no provider says anything about what
-they may see there.
-
-#### `TaskBrowser` and isolation
-
-Each `TaskBrowser` defines one named browser in the task workspace.
-
-| Field | Contract |
-| --- | --- |
-| `id` | Stable internal selection and update identity within the task. |
-| `name` | Agent-facing tab label, unique within the task, and an input to schemes containing `TAB_NAME`. |
-| `purpose` | Human-readable explanation of the browser's role. |
-| `url` | Initial URL. Must use `http:` or `https:`; see below. Later navigation comes from Chromium. |
-| `sharedSession` | Required. `false` creates a task-specific browser session. |
-| `isolationScheme` | **Required when `sharedSession` is `true`**, and rejected when it is `false`. There is no default: see below. |
-| `urlVisibility` | What the agent sees of this tab's URL in Omni's chrome: `hidden`, `domain`, or `full`. Omitted, the URL shows as any browser's does; a provider says `hidden` where the URL carries what the agent may not read — a caller's number, a CRM token. Per browser, on the provider's word; an agent application that declares `guarantees.browserUrlVisibility` honours it tab by tab, and a provider checks that guarantee before it sends such a URL at all. |
-
-##### Choosing an isolation scheme
-
-Every scheme is supported and the provider picks the one its deployment needs. There is no
-default, and a `sharedSession: true` browser that declares none is invalid — the type will not compile
-it and `validateSnapshot` reports `task.browser.isolationScheme.required`.
-
-That is deliberate. Sharing a signed-in session decides **who else may see those credentials**,
-and it is not a decision to inherit from whichever value happened to be the default. `TAB_NAME`
-keys on the tab label alone, so two providers that each publish a browser named "CRM" share one
-signed-in session — legitimate where a deployment wants exactly that, and a silent credential
-leak where it does not. It remains available; it has to be asked for.
-
-`browserSessionKey` fails closed: given a reusing browser with no scheme it returns `undefined`
-and the browser is isolated. The safe reading of an invalid declaration is "do not share", never
-"share with everyone named the same".
-
-##### Permitted URL schemes
-
-`TaskBrowser.url` is provider-supplied and is loaded inside Omni's managed browser, so it is
-restricted to the schemes in `ALLOWED_BROWSER_URL_SCHEMES` — currently `http:` and `https:`.
-`file:`, `chrome:`, `javascript:`, and every other scheme are rejected. Omni substitutes a blank
-page rather than following a disallowed URL, and `isAllowedBrowserUrl()` is the shared predicate.
-
-##### Reuse and isolation
-
-With `sharedSession: true`, definitions producing the same isolation key share one **storage profile**:
-cookies, local storage, session storage, permissions, and cached credentials. Different keys are
-isolated from one another.
-
-Sharing a profile is not sharing a window. Two browsers in the same task keep their own tab, their
-own visible label, and their own navigation state and history even when their keys match — a
-scheme that omits `TAB_NAME`, such as `PROVIDER_NAME__TASK_TYPE_NAME`, deliberately places every
-named browser of that task type in one signed-in profile without merging them into one page.
-
-`browserSessionKey()` derives the key. Every part is escaped before the `.` separator is applied,
-because `encodeURIComponent` leaves `.` untouched and a raw join would let one value forge
-another key: provider `Acme.Voice` with task type `Support` would otherwise produce the same key
-as provider `Acme` with task type `Voice.Support`, silently placing two providers in one cookie
-jar. Hosts that must flatten the key further — for a native window label or a partition name with
-a restricted charset — must keep the mapping injective, for example by appending a fingerprint of
-the exact key, since lowercasing or replacing punctuation reintroduces exactly this collision.
-
-```ts
-browsers: [
-  {
-    id: "crm",
-    name: "CRM",
-    purpose: "Contact record",
-    url: "https://crm.example.com/contact/42",
-    sharedSession: true,
-    isolationScheme: BROWSER_ISOLATION_SCHEMES.PROVIDER_NAME__TASK_TYPE_NAME__TAB_NAME,
-  }
-]
-```
-
-The supported `BrowserIsolationScheme` values, declared under **Shapes**, key as follows:
-
-| Enum member | Example session key |
-| --- | --- |
-| `PROVIDER_NAME__ASSIGNMENT_ID__TAB_NAME` | `mailflow.EMAIL-829102%2Ea1.CRM` -- the task's assignment id, so one assignment, never the next customer's cookies |
-| `TAB_NAME` | `CRM` |
-| `PROVIDER_NAME__TASK_TYPE_NAME__TAB_NAME` | `mailflow.Support.CRM` |
-| `PROVIDER_NAME__TAB_NAME` | `mailflow.CRM` |
-| `PROVIDER_NAME__TASK_TYPE_NAME` | `mailflow.Support` |
-| `TASK_TYPE_NAME__TAB_NAME` | `Support.CRM` |
-
-`TASK_TYPE_NAME` refers to the mandatory `Task.taskType`. The isolation scheme never changes
-the browser tab label. Serialized values are stable protocol values and must not be renamed or
-reused.
-
-**`PROVIDER_NAME` is `manifest.id`, never `manifest.displayName`.** Only the id is required unique
-across an installation; two providers may legitimately share a display label, and keying a cookie
-jar on one would put them in the same signed-in session. The id is also stable across launches,
-where a display name may be re-worded — and a changed key silently signs the agent out of every
-browser that used it.
-
-### Task capabilities
-
-Task capabilities belong to each `Task`. If `hold` is omitted on one task, Omni
-must not show or issue hold for that task even if another task from the same provider supports it.
-
-**A capability is a property of the task, and of nothing the task names.** A provider derives it
-from no other source -- not the queue the task came from, not the login, not its own configuration
--- because each of those answers a question about this task from somewhere that does not know
-about this task, and a client with two sources and a rule for choosing between them is the shape
-that produces two consumers disagreeing about one fact. The task is the one source, and the
-provider puts on the task what the platform permits for it -- and says, in `capabilitySource`, who
-chose those terms. `queue` says somebody configured them. `nobody` says nothing handed the work
-over: an agent's own outbound call has no queue behind it, and the provider states what it permits
-for such a call. Neither changes where an agent application reads the capabilities from, which is the task; the
-source is one more published fact about them, and the one that lets an agent application tell a fact from a fault
-(see below).
-
-**Completing the task is not a capability, and no capability set withholds it.** `complete` is
-governed by `completionMode` alone: under `agent-command` it is always available, whatever the set
-says, and the `outcomes` capability decides only whether a code travels with it. Likewise
-Answer on a pending task and Call on a preview are the phase's controls, not the set's. The
-capability set governs what the agent may do *with* the task; completing it is never on the
-list.
-
-**A permission that changes while the task is open is republished on the task at the moment it
-changes.** An agent on a billing dispute may refund up to their own limit and no further. The
-customer wants more, the agent asks for a lead, and the moment the lead joins the call the task is
-republished with the Refund control the agent could not have a minute ago; when the lead leaves, it
-is republished without it. Nothing about the agent changed -- who is on the call did -- and the
-task said so both times, at the moment it became true. A call moves queues the same way: a caller
-identified as a priority customer is transferred to the priority queue, and the task arrives under
-that queue's terms -- a longer wrap allowance, a discount control the general queue never offered --
-restated on the task at the hand-over, not inferred from the queue it left. A capability stated
-once at offer or answer and never corrected is a fact with a shelf life and no expiry, and an agent application
-draws a control the provider will now refuse -- or withholds one the agent now has. So the provider republishes
-the task, with its capabilities as they now stand, and an agent application treats the last statement as current
-rather than re-deriving anything. This is the same shape as a room left full after the call ends
--- a field describing the present, carried past the moment it stopped being true -- carried past
-this time not by a spread but by nobody sending the correction. A provider whose platform can
-change a permission mid-task and does not republish is in breach, however conformant its offer was.
-A capability set can shrink as well as grow, and an agent application that has only ever seen it grow meets a
-control that was there a moment ago and is gone; a command that arrives after its capability was
-withdrawn is refused with a reason, never acted on. The asymmetry decides which direction a
-provider gets right first: a control gained late is a nicety, a control withdrawn and not
-republished is a button that fails when pressed. `assertTaskCapabilityWithdrawal` is the test for that
-direction: the task as offered and as republished, and one command that was issuable under the
-first and is refused under the last for want of the capability withdrawn -- and nothing else.
-
-**An empty capability set is a statement, not a shrug.** `capabilities: {}` under `queue` or
-`nobody` says the platform permits nothing capability-gated on this task, and an agent application draws
-nothing beyond what the phase and `completionMode` require. A provider that has not yet learned
-what the platform permits -- a queue's configuration that has not reached it -- knows nothing of
-the kind, and must not publish the task as if it did, neither as `{}` nor as every control it has.
-It publishes the task under `capabilitySource: "not-yet-read"`, with the capabilities it will
-honour until it knows, and an agent application shows that where the agent works, beside the controls it draws
-from them: "no queue governs this call" is a fact, "the configuration has not arrived" is a fault,
-and the set alone cannot tell them apart, so the provider says which. What a provider honours
-under not-yet-read terms is its own call -- a floor that would rather an agent briefly hold a
-control the platform might not have granted than lose hold or hang-up mid-call over a slow
-configuration read publishes those -- and the protocol chooses no default set for it. The fault is
-also reported as a `diagnostic` naming the task, one per occurrence, so an operator counts it. When
-the terms arrive, the task is republished under `queue` with the set as it now stands: the same
-republish as any other permission that changed while the task was open. The move goes one way.
-Terms once read stay read: a re-read that fails mid-task is not a new fact about the task, so the
-last statement stands and the failure is a `diagnostic`, and a task that was published under
-`queue` or `nobody` never returns to `not-yet-read`, on an update (`stream.taskUpdated.capabilitySource`)
-or on a resync snapshot (`stream.snapshot.capabilitySource`); a record once read never loses an
-entry the same two ways (`stream.taskUpdated.history`, `stream.snapshot.history`);
-a snapshot carrying a task still at work does not forget the audio the stream held up, since audio
-ends on `task-audio-ended` and the call moves on (`stream.snapshot.audio`); a voice task ends after
-its audio ends, never around it, whatever the outcome (`stream.taskEnded.audioOpen`); and a task does not go
-backwards, on an update or on a resync (`stream.taskUpdated.phase`, `stream.snapshot.phase`): the
-stream sees publications, not
-transitions, and a task may pass through a phase between two, so `pending` to `in-progress` stands
-with `confirmed` between them, and what is refused is a phase unreachable from the last one read by
-the transition table -- back to `pending`, back to `confirmed` or `preview` once work began, out of
-`completing` except by the party being dialled again, a connect-back or a platform's callback,
-which the update itself shows: the party ringing, or joined by a dial whose answered outcome the
-stream saw in this life. A completing task republished as `in-progress` from a stale copy carries
-no such stage, and that is the ending the agent never saw. Audio arrives only on a task at work: `task-audio-started` on a `completing` task
-is refused as it is on a pending one (`stream.taskAudioStarted.beforeWork`), since a connect-back
-returns the task to `in-progress` before any audio. And a task completes after its audio ends,
-never around it: an update moving a task to `completing` while the stream holds its audio as
-started is refused (`stream.taskUpdated.audioOpen`), whoever caused the ending, and a task stating
-`completing` with `audio: "started"` contradicts itself on any snapshot or update
-(`task.audio.completing`). The consequence the rule exists for is concrete: the customer's audio
-keeps playing through the agent's wrap-up.
-
-What the agent is told differs by source, and only one source tells them anything. Under `queue`
-and `nobody` the agent sees controls and nothing about where they came from: both are facts,
-and an agent working a call has no use for the name of the rule behind its buttons. Under
-`not-yet-read` the agent is told, beside the controls, that these are what the provider will honour
-until the queue's terms arrive, and that the controls may change when they do -- a statement about
-the buttons in front of them now, not about the provider, because that is what changes when the
-republish lands. It stays for as long as the set is provisional, beside the controls it qualifies;
-a message that shows and clears has said nothing about the buttons still on the screen. The two
-words are close in English and far apart on the desk: `nobody` is silence, `not-yet-read` is a
-standing notice.
-
-One consequence for whoever builds the agent application: because a conformance run fails on `not-yet-read`, a
-conformant adapter never shows an agent application `not-yet-read` under test, and a clean `exerciseAdapter`
-result says nothing about how the agent application renders it. That rendering is tested against a fixture --
-a task published under `not-yet-read` shows the notice, the same task under `queue` shows none --
-and never against an adapter, even in principle. `exerciseAdapter` treats a
-task published under `not-yet-read` as a violation (`capabilitySource.notYetRead`), as it treats
-a diagnostic: a conformance run against a platform that cannot say what it permits fails loudly
-rather than passing with a note.
-
-```ts
-const taskCapabilities = {
-  channel: "voice",
-  capabilities: {
-    hold: true,
-    outcomes: true,
-  },
-  browsers: [],
-} satisfies Pick<Task<"voice">, "channel" | "capabilities" | "browsers">;
-```
-
-A capability says the control may be offered; the task's phase says whether there is anything to use
-it on. Every control below that acts on the call or the conversation -- everything but `decline`,
-`connectBack`, `schedule` and `outcomes` -- is offered only while the task is `in-progress` or `paused`.
-See **Which commands need a capability**.
-
-### Voice capabilities
-
-| Capability | Omni UI | Contract |
-| --- | --- | --- |
-| `decline` | Pending-task button: Decline | The provider can decline a pending voice offer. Omni shows it only when local policy also permits declining. |
-| `hold` | Primary toggle: Hold | Omni may issue voice-task `hold` and `resume` commands. |
-| `endCall` | Primary button: End call | The provider ends the agent's channel and every channel the agent added; the caller continues on the provider's path. The task goes to its wrap. See **Ending a call, and removing one person from it**. |
-| `terminateCall` | Primary button: Terminate call | The provider ends the whole call: every channel on it, the agent's, the caller's, any colleague's and anyone else's. The task goes to its wrap. See **Ending a call, and removing one person from it**. |
-| `connectBack` | Completing-task button: Connect back | Omni may have the provider connect the agent back to the task's party while the task is `completing`, returning it to `in-progress` on the same task. Not offered where there is no `completing` window: `provider-automatic` with a zero allowance completes the task at provider end. See **Connecting back during completion**. |
-| `schedule` | Secondary menu item: Schedule | Omni may put a follow-up for this party on the calendar, from the call or from its wrap: a time, and a note. See **Scheduling a follow-up**. |
-| `leadAssist` | Secondary menu item: Lead assist | Omni may ask a lead to join this call, with a note. The lead's decision reaches the agent on `Task.leadAssist`. See **Lead assist**. |
-| `conference` | Secondary button: Conference | Omni may dial a destination into the active call, and remove one person from it -- a conferenced entry, one still ringing included, which calls the dial off, or the party, leaving the agent with the colleague. See **Ending a call, and removing one person from it**. |
-| `recording` | Overflow menu item: Recording | Per-task provider and agent application policies expose only their permitted recording actions; each has independent state and routing. |
-| `outcomes` | Primary button: Complete | Omni may request task completion with a provider outcome and notes. |
-
-### Publishing codes and destinations
-
-Two capabilities accept an object when the provider wants Omni to render real choices. For
-`outcomes`, `true` remains valid and means "offer the control with nothing published"; the one
-directory control, `conference`, carries its directory or is refused, since once nothing is typed
-the directory is the control.
-
-#### `outcomes`
-
-An outcome describes what happened; completion finishes the task. Outcome codes are selected
-from the task's own published list. They are distinct from `DialOutcome`, which reports the
-result of a dial attempt.
-
-Migration requires providers and hosts to adopt the renamed types and fields together:
-
-| Former API | Current API |
-| --- | --- |
-| DispositionCode | `OutcomeCode` |
-| DispositionRules | `OutcomeRules` |
-| DispositionPayload | `OutcomePayload` |
-| Task.capabilities.dispositions | `Task.capabilities.outcomes` |
-| complete.disposition | `complete.outcome` |
-
-Validation and conformance diagnostics use `task.outcomes`, `task.outcome`, and
-`command.complete.outcome` in place of the former names. Update retained task snapshots and
-command producers as well as imports. Old capability and command fields are rejected, including
-payloads containing both names; there are no compatibility aliases. Code IDs, notes, required
-selection rules, and completion behavior are unchanged.
-
-```ts
-capabilities: {
-  outcomes: {
-    required: true,
-    notes: "optional",
-    codes: [
-      { id: "resolved", label: "Resolved" },
-      { id: "callback", label: "Callback needed", group: "Follow-up" },
-    ],
-  },
-}
-```
-
-| Field | Contract |
-| --- | --- |
-| `required` | When `true`, Omni must collect a code before issuing `complete`. A required policy must publish at least one code. |
-| `notes` | `required`, `optional`, or `none`; controls the free-text field beside the code. |
-| `codes` | Codes Omni offers. `id` values are non-empty and unique; Omni sends the chosen `id` as `TaskCommand.complete.outcome`. |
-
-With `outcomes: true` Omni shows a Complete control and sends `complete` with no code, because
-the provider published none.
-
-#### `conference`
-
-```ts
-capabilities: {
-  conference: {
-    destinations: [
-      { id: "tier2", label: "Tier 2 support" },
-      { id: "main-menu", label: "Back to the main menu" },
-    ],
-  },
-}
-```
-
-| Field | Contract |
-| --- | --- |
-| `destinations` | The items the control offers, at least one, with unique `id` values. Each is a button or a menu item on the desk. |
-| `id` | What Omni sends as `destinationId` on a `conference` command, and what the provider executes. |
-| `label` | What the agent reads. |
-
-**The protocol does not say what an item does.** A queue, an IVR menu, an outside line, a
-skill group -- that is the queue's configuration and the provider's business. The agent sees a
-list of labels, picks one, and Omni sends its `id`; the provider executes whatever the item is. No
-kind travels, nothing is typed, and a control with an empty directory has nothing to offer and is
-refused (`task.destinations.offer`). A control declared as bare `true` is refused for the same
-reason (`task.destinations.shape`): once nothing is typed, the directory is the control.
-
-**The provider chooses the supported destinations.** A published item may route to an IVR,
-queue, named agent or another configured destination. No destination kind is inferred from its
-label. The agent application offers only the directory attached to this task's `conference` capability,
-and sends the exact destination ID; it does not invent an agent picker or arbitrary dial target.
-The provider rechecks eligibility and executes the routing. Returning to an IVR or queue does not
-end the caller journey; a later assignment to the same agent is a new interaction.
-
-#### Ending a call, and removing one person from it
-
-A call has everyone on `Task.onCall`, and three commands take people off it, all performed by the
-provider. Two of them end the agent's part; they differ in what happens to the caller.
-
-```ts
-{ type: "end-call" }                                             // the agent's channel and the channels the agent added end; the caller continues
-{ type: "terminate-call" }                                       // every channel on the call ends
-{ type: "conference", action: "remove", party: true }            // the customer leaves; the agent stays with the colleague
-{ type: "conference", action: "remove", destinationId: "tier2" } // the conferenced person leaves; ringing, this calls the dial off
-```
-
-**`end-call` ends my part.** The agent's channel and every channel the agent added -- a
-conferenced colleague, a lead who joined -- end, and the caller continues on the path the
-provider decides: another IVR, a queue, a survey, or the end of the call. Gated by `endCall`.
-
-**`terminate-call` ends the whole call.** Every channel on it ends at the provider: the agent's,
-the caller's, any colleague the agent added, and anyone else on the call. Nobody is left on the
-line. Gated by `terminateCall`, a separate permission, since ending a customer's call is a
-different thing from putting my own side down.
-
-Both are commands to the provider through `execute`, and nothing happens on the desk until the
-provider reports it: the agent's audio ends on `task-audio-ended`, the task moves to `completing`,
-any wrap allowance runs, and the agent completes. Neither is `task-ended`, and `complete` is
-neither of them. Both capabilities are the queue's to grant and a level's to lock, and both may
-change while the task is open: the provider republishes the task at the moment a permission
-changes, and a command that arrives after its capability was withdrawn is refused, as **Task
-capabilities** sets out. The provider knows which channels are the agent's and which were added;
-the agent application sends the command and no channel list, and the provider rechecks ownership
-when it acts.
-
-`conference` `remove` takes one person off, named as the room names them, and the call goes on
-for the rest; it is gated by `conference`, since it only means something with a third person on
-the line. Removing the party leaves the agent with the colleague, a warm hand-over in reverse. A
-remove that would leave the agent alone is not a remove but an `end-call`, and a provider answers
-it `failed`.
-
-**There is no transfer.** The agent hands the call to nobody, cold or warm: help arrives by
-**Lead assist**, where a lead joins the call or takes it over, and a call that changes hands does
-so on the platform's own routing -- an IVR return, a queue, a lead's take-over -- with the record
-saying so in a `transferred` step and the `transfers` total. Nothing the agent commands moves the
-caller to somebody else.
-
-#### Scheduling a follow-up
-
-An agent on a call promises to call back on Thursday, or in wrap writes up that the customer wants
-a callback once the refund lands. The follow-up goes on the calendar, and the platform owns the
-calendar: `schedule` asks the provider to put it there. A chat or an email agent promises a
-callback as often, so the control is on every channel.
-
-```ts
-// From the call or the conversation, or from its wrap: the time, and a note where the agent wrote one.
-{ type: "schedule", at: "2026-08-28T10:00:00Z", note: "Call back about the refund" }
-```
-
-`schedule` is gated by the `schedule` capability and issuable in `in-progress`, `paused` or
-`completing` (`command.phase.interaction`): a follow-up is promised on the call and written up in
-wrap alike, and the task names the party it is for. It lands on the calendar, so a task may offer
-it only under a manifest that declares the `calendar` idle capability
-(`task.capability.calendar.required`), as a control that dials needs `dialOutcomes`; a locked
-`schedule` is still a declared one. The command carries a time and a note and nothing else
-(`command.schedule.at`, `command.schedule.note`, `command.field`): what the platform makes of a
-follow-up -- a campaign record, a reminder, a scheduled dial -- is its own, and the agent sees it
-on the calendar.
-
-**`applied` says the follow-up is on the calendar**, and the `calendar-updated` that shows it
-follows within the manifest's `settleMs`, as a `task-ended` follows an applied `complete`. Past
-the bound the agent application calls `snapshot()`: a calendar carrying an activity at that instant
-clears the wait; one without it shows the follow-up as unsettled -- "Scheduled... the provider has
-not confirmed" -- naming the command. The drive schedules one follow-up where the task offers it,
-at a time it takes from the provider's own publication, and holds the provider to the same bound
-(`drive.schedule.unsettled`).
-
-### Chat capabilities
-
-| Capability | Omni UI | Contract |
-| --- | --- | --- |
-| `decline` | Pending-task button: Decline | The provider can decline a pending chat offer. Omni shows it only when local policy also permits declining. |
-| `hold` | Primary toggle: Hold | Omni may pause and resume the agent’s interaction in the chat. |
-| `schedule` | Secondary menu item: Schedule | Omni may put a follow-up for this party on the calendar, from the conversation or from its wrap. See **Scheduling a follow-up**. |
-| `outcomes` | Primary button: Complete | Omni may request task completion with a provider outcome and notes. |
-
-### Email capabilities
-
-| Capability | Omni UI | Contract |
-| --- | --- | --- |
-| `decline` | Pending-task button: Decline | The provider can decline a pending email offer. Omni shows it only when local policy also permits declining. |
-| `schedule` | Secondary menu item: Schedule | Omni may put a follow-up for this party on the calendar, from the message or from its wrap. See **Scheduling a follow-up**. |
-| `outcomes` | Primary button: Complete | Omni may request task completion with a provider outcome and notes. |
-
-### Custom capabilities
-
-Every task may publish additional provider-specific controls in `capabilities.custom`:
-
-```ts
-capabilities: {
-  hold: true,
-  custom: [
-    { id: "request-supervisor", ui: { control: "button", label: "Request supervisor", placement: "secondary" } },
-    { id: "mark-vip", ui: { control: "toggle", label: "Mark as VIP", placement: "overflow" } },
-  ],
-}
-```
-
-Custom capability IDs must be non-empty and unique within the task. `ui.control` is `button`, `toggle`,
-or `menu-item`; `ui.placement` is `primary`, `secondary`, or `overflow`. `ui.render` says where the
-control's work appears: `inline`, in the workspace beside the task, or `page`, as a page of its own
-— a tab in the same work area as the task's browsers, beside them, and alone on a task that has
-none; stated on every control, never defaulted (`task.custom.ui.render`). `prompt.fields` are what the agent supplies before the action runs — a
-destination number, a reference — as `CredentialField`s Omni renders as a form; the values travel
-on the custom command under the fields' names, as strings, and Omni sends the command only once
-every `required` field has a value. The provider validates what arrives as it validates any
-command; a form is a declaration, not a contract for what the agent typed. Omni renders the
-control and invokes it with the shared custom task command:
-
-```ts
-{
-  type: "custom",
-  name: "request-supervisor",
-}
-```
-
-`name` is the `id` of the custom capability the agent used. There is no `assignmentId` here: like every
-other command it travels on the `TaskCommandRequest` around it. A `toggle` carries the state it
-wants — `{ type: "custom", name: "mark-vip", on: true }` — never a flip, for the reason under
-**Task commands**.
-
-Custom capabilities must not redefine the meaning of a standard channel capability.
-
-## Idle actions
-
-### `dial(request)`
-
-Starts one outbound call from the idle dialpad. It is present only when the voice provider
-declares `dial`.
-
-- `dialId` is the agent application's identity for this dial, minted before the request leaves.
-- `destination` is the original number selected or entered by the agent.
-- The provider holds `destination` to its declared `destinations`: under `contacts-only`, a
-  number that is not one of its contacts answers `failed` with `omni.destination-not-permitted`.
-- `dialling` says the request was accepted and the call is being placed, and restates the
-  `dialId`. It says nothing about whether anyone will answer.
-- `failed` contains a `ProtocolFailure` and confirms no call was placed.
-
-The resulting call is offered through the normal `task-offered` event, and how the dial ended
-arrives on `dial-outcome` under the same `dialId`. A `dialling` result does not manufacture a task
-inside Omni.
-
-## Every dial has an outcome
-
-Four commands place a call: `dial()` from the idle dialpad, the `dial` command from preview, a
-`conference` `add`, and `connect-back`. Each is accepted or refused at once, and each then ends later
-and apart from its answer -- the destination picks up, is busy, or never does -- and a dial placed
-late in a call routinely outlives the call. Nothing in between is reported: the wire says
-`dialling`, then says how it ended, once.
-
-**The agent application mints the identity.** Every command that dials carries a `dialId` the agent application made, unique
-across the installation, and it travels four ways so no leg is a lookup:
-
-```ts
-declare const connection: Connection<"voice">;
-declare const assignmentId: AssignmentId;
-
-// 1. Out, minted by the agent application.
-const result = await connection.execute({ assignmentId, command: { type: "conference", action: "add", dialId: "dial-7f2", destinationId: "tier2" } });
-
-// 2. Back on the result, restated, so the agent application compares and confirms.
-expect(result).toEqual({ status: "dialling", dialId: "dial-7f2" });
-
-// 3. On the outcome, however late, against the task it belonged to.
-const outcome: ProviderEvent<"voice"> = { type: "dial-outcome", dialId: "dial-7f2", assignmentId, destinationId: "tier2", outcome: "no-answer", reason: "No route to destination" };
-
-// 4. In the record, so a dial made before a take-over is placeable by whoever holds the task now.
-const step: TaskHistoryStep = { step: "unanswered", at: "2026-08-21T09:15:30Z", by: "A-12", dialId: "dial-7f2", destinationId: "tier2" };
-```
-
-The identity is a correlation handle between agent application and provider and **is never shown to the
-agent**. An agent application holding several tasks places an outcome by the `dialId` it minted; one it did not
-mint -- a dial made by the previous agent before a take-over -- it finds on the task's `onCall` or in
-its `history`, which is why the steps that dial carry it. The `dialId` is not a retry key:
-Omni never repeats a dial, and a command still carries no key for that purpose.
-
-**`dialling` is the answer to a dial, and `applied` is not.** A command that dials answers
-`{ status: "dialling", dialId }`, restating the agent application's identity (`result.dialId`,
-`result.dialId.mismatch`); `applied` from such a command, or `dialling` from one that dialled
-nothing, is refused (`result.status`). `validateResult(result, method, path, dialId)` takes the
-`dialId` the agent application sent for that reason.
-
-**The outcome is stated, once, either way.** A `dial-outcome` names the `dialId`, the task where
-there was one, the directory item it went to where there was one, and how the dial ended -- from a closed
-set: `answered`, `busy`, `no-answer`, `unreachable`, `rejected`, `cancelled`, `unexplained`.
-`answered` is stated rather than read off somebody appearing on the call, because an agent application that infers
-success cannot tell "reached" from "still ringing". `cancelled` is the dialler calling the dial off
-before anyone answered -- the agent hanging up while a conferenced colleague still rings -- which is not a
-`no-answer` the destination never gave. `unexplained` is the switch dropping the call with no cause among
-those named here: a statement about the switch, sent instead of the nearest cause it did not give.
-`reason` is the switch's own words, optional, and shown to the agent attributed to the switch rather
-than to Omni. The two are different things and may travel together: a switch can say "could not
-create dialog" in words and still name no cause a code would carry, so `unexplained` with a
-`reason` is a dial the switch described but did not classify, and a desk renders the words without
-inventing the class.
-
-**`assignmentId` is the task the dial was placed on**, resolved from the dial's own identity and never from
-whatever task the agent is looking at when the outcome arrives. That task may already have ended,
-and the harness places the outcome all the same (`TaskStream`, `stream.dialOutcome.unknown`,
-`stream.dialOutcome.duplicate`); an agent who moved on still learns nobody was reached, against the
-call it belonged to and never against the next one.
-
-The stream knows a dial from three places: `TaskStream.dialled(dialId)`, which an agent application calls when it
-places one; an entry on a task's `onCall`; and a step in its `history`. Since a dialled entry
-is listed from placement, `dialled()` is load-bearing only for a dial that never has an entry -- an
-idle dialpad call, which has no task yet -- or whose entry has already left the room; an
-outcome for a dial nobody placed and no task mentions is what `stream.dialOutcome.unknown` refuses.
-
-**`answered` says what happened to the dial; `onCall` says who is in the room.** They are two
-claims, and both are true at once when a leg answers and never joins. A desk shows `answered` as the
-dial's conclusion and says "on the call" only when the person appears on `Task.onCall`; the obvious
-reading of `answered` -- that they are on the line -- is the one it does not make.
-
-**A provider says which outcomes it can tell apart.** No switch distinguishes all five, and a
-provider that cannot tell busy from unreachable must not pick one. The manifest declares
-`dialOutcomes`, and a `dial-outcome` carries only a declared member
-(`event.dialOutcome.undeclared`). The list includes `answered`, or the provider could never state a
-success (`manifest.dialOutcomes.answered`), and at least one other member, or it could never state
-a failure (`manifest.dialOutcomes.failure`). `unexplained` is declarable only beside a cause the
-provider does report -- `busy`, `no-answer`, `unreachable`, `rejected` or `cancelled`
-(`manifest.dialOutcomes.unexplained.alone`): a provider that reports causes may honestly say the
-switch gave none, while one that reports none would be sending the generic failure this set exists
-to refuse. A provider that dials at all declares it: an idle
-dialpad requires it (`manifest.dialOutcomes.required`), and a task that declares `connectBack`
-or `conference` under a manifest without it is refused
-(`task.capability.dialOutcomes.required`). Off voice nothing dials, and the field is a compile
-error there.
-
-**Who is on the call is stated on the task.** `Task.onCall` lists everyone the task's audio joins
-right now, replaced whole with the task like every other field, and present when the provider
-knows the room:
-
-```ts
-const onCall: OnCall[] = [
-  { role: "party", since: "2026-08-21T09:12:00Z" },
-  { role: "agent", userId: "A-12", since: "2026-08-21T09:12:04Z" },
-  { role: "conferenced", destinationId: "tier2", dialId: "dial-7f2", stage: "joined", held: true, since: "2026-08-21T09:15:30Z" },
-  { role: "conferenced", destinationId: "main-menu", dialId: "dial-3c9", stage: "ringing", since: "2026-08-21T09:16:02Z" },
-];
-```
-
-`party` is the customer and `agent` a person by user id; neither was dialled from anywhere, so
-neither carries a destination. A `conferenced` colleague was, so the entry carries the
-`destinationId` of the directory item and, where an agent application's dial brought them, its `dialId`; a person
-the platform added itself carries none. `held: true` is presence as claim. A snapshot establishes state, so an agent application that attaches
-after a take-over reads the room from here rather than inferring it from a sequence of outcomes it
-never saw.
-
-**`onCall` describes this agent's current interaction.** When the caller disconnects but the agent
-and added channels remain connected, the remaining room is still valid. When this interaction's
-audio ends or the task enters `completing`, clear its `onCall` view; absence is used only by a
-provider that never publishes the room. This does not assert that the caller, bridge or other
-agents' channels ended. A published room receives a final empty view for this interaction, and the
-task may remain open for wrap. Completion is a separate task action, not the caller's disconnect.
-
-**A field that describes the present is cleared by the transition that ends it.** `onCall`,
-`previewEndsInSeconds` and `atDeadline` are three instances of one shape, and there will be more: each
-describes a state that is true now, and each is carried past the moment it stops being true by the
-most natural implementation there is, building the next task by spreading the last one. The
-provider's own state looks right, the claim on the wire is stale, and only the agent application sees it. An
-adapter that builds each transition from what is true after it, rather than from what was true
-before, needs none of these rules named. Two agents were
-once shown on calls for the better part of an hour while callers queued, because the last message
-describing the room live was never followed by one saying it had emptied, and every consumer that
-derived anything from it was wrong in a way that looked like its own bug.
-
-**A dialled entry is listed from the moment the dial is placed, not from the answer.** The entry is
-what `conference` `remove` names, and a destination the agent cannot call off while it rings is a
-customer kept waiting with no way back -- which is the very case `cancelled` exists for. The
-`conferenced` entry appears with its `dialId` when the dial is placed, and a `conference` `remove`
-naming a still-ringing `destinationId` calls that dial off, with `cancelled` as its outcome.
-
-**The entry says where it stands.** A dialled entry carries `stage`: `ringing` until its dial is
-answered, `joined` after. The `dial-outcome` is the transition and the stage is the state, the same
-pairing as `task-audio-started` and `audio`: an `answered` outcome and the task restated with the
-entry `joined` say one thing twice, and any other outcome removes the entry. The outcome comes
-first: a `task-updated` that itself moves an entry from `ringing` to `joined` before an `answered`
-outcome for its dial is refused (`stream.taskUpdated.stage`), as an update that moves `audio` is.
-The rule keys on the entry's `dialId`, so an entry the platform added itself, with none, is one
-whose move the stream cannot hold to an outcome: a clean stream proves nothing about ordering there. It is stated rather
-than left to whoever placed the dial because that knowledge lives in one process: after a reload,
-on a second session, or on a supervisor's screen the snapshot is the only source, and a room that
-cannot tell ringing from joined says it contains someone who may never arrive. Nobody ringing is
-held (`task.onCall.held.ringing`). A colleague who never answers is a dial that ended: the
-provider restates the room without the entry, and the agent is back with the customer.
-
-The desk shows a dial as placed on `dialling`, never as reached; shows the person in the room when
-they appear on `onCall`; and shows the outcome, with the switch's reason, against the call it
-belonged to -- with no retry, since a wrong number is not worth redialling and the decision is the
-agent's.
-
-## Breaks
-
-Everything about an agent's breaks on one provider arrives as one object, `Snapshot.break`,
-replaced whole by a single `break-state` event. These facts are only meaningful together — an
-approval says nothing without knowing whether the agent chose the break, and a list of reasons says
-nothing while none are being accepted — so they are not published separately.
-
-| Field | Contract |
-| --- | --- |
-| `status` | Where the agent’s break lifecycle stands. See the states below. |
-| `canRequestBreak` | Whether the agent may ask at all. Distinct from `status`. |
-| `requestUnavailableReason` | Display-ready reason shown when `canRequestBreak` is false — a standing gate that applies to everyone. |
-| `decisionReason` | The words whoever decided attached, from `decide.reason`. About one request and one decision, not a standing gate. |
-| `retryRequestAfterMs` | Milliseconds until the agent may retry a break request, when the provider can say. |
-| `reasons` | Not-ready codes this provider offers. Omitted when it defines none; an empty list is refused, being a second spelling of the same fact. |
-| `activeReasonId` | The `BreakReason.id` the current break is on. Omitted when there is no break. Required on a break `on-break` or `starting-after-task` where the provider publishes `reasons`, a forced break included (`break.activeReasonId.required`): a break with a kind the provider cannot name is a break whose rules nobody can apply. |
-| `forced` | Set when the break was forced on the agent rather than requested. |
-
-A request can be waiting for two unrelated things, and they are separate values because
-rendering one as the other tells an agent to wait for somebody who is never coming:
-
-| `status` | Meaning |
-| --- | --- |
-| `not-requested` | No request outstanding. |
-| `awaiting-approval` | A person has to decide. The agent is waiting on somebody. |
-| `granted` | The request was granted, by a person or by an `automatically-approved` policy. Omni may now tell this provider to stop the agent; until it does, work continues normally, and this says nothing about why Omni has not. |
-| `starting-after-task` | Omni has told the provider to stop; the break begins when the current task ends. No new work arrives meanwhile, and nobody needs to act. It waits on a task, so beside no task it is refused (`break.starting-after-task.tasks`): a committed break with nothing outstanding is `on-break`. |
-| `on-break` | The agent is on the break now. It holds no task: a break begins when the work ends, so a snapshot reporting `on-break` beside a task is refused as `break.on-break.tasks`. The one exception is a call a lead took over, which the provider assigns whatever break the lead is on -- see **Lead assist**. |
-
-A denial is a decision, not a standing approval state. The provider transitions the request directly
-to `not-requested`; Omni returns the agent to idle and never asks again on their behalf. They saw the
-answer and ask again when they want to. `decisionReason` may carry the words attached to that
-decision, but `status` does not remain denied.
-
-A provider reports `starting-after-task` only after Omni commits a `granted` request while
-work is still active. Omni does not send the request again, because asking again would not move
-it; it sends the commit again only from a reconnect snapshot that shows the grant still standing.
-
-`canRequestBreak: false` is what lets Omni withdraw the control rather than let an agent ask and be
-refused. A `BreakReason` marked `alwaysAvailable` survives it: a mandatory rest period is not
-something a busy hour can cancel, and Omni keeps offering those while the rest are withdrawn.
-
-### Forced breaks
-
-Migration: the former awaiting-decision value is now `awaiting-approval` in break status
-and the team member’s pending break state. The old value is rejected without an alias;
-the request can still be granted or denied, and ordering rules are unchanged.
-
-Migration: the former BreakApproval type is now `BreakStatus`, matching `BreakState.status`.
-The former type is not exported as an alias; its values and behavior are unchanged.
-
-Migration: `BreakState.status` replaces the former approval field. It covers the full break
-lifecycle. The old field is rejected even alongside status; related diagnostics now use status.
-The `BreakStatus` union and its values, `reasons`, `activeReasonId`, and the separate testing
-helper BreakOnTaskStep.approval are unchanged. Hosts and providers must update together.
-
-Migration: the break-state field formerly named retryAfterMs is now `BreakState.retryRequestAfterMs`,
-with diagnostic `break.retryRequestAfterMs`. It remains an optional non-negative finite number
-of milliseconds; the former break field is rejected even alongside the new field.
-The separate authentication and general failure retryAfterMs fields are unchanged.
-
-Migration: the former in-effect break approval value is now `on-break`. It means the
-agent is on the break, not merely granted permission. The old value is rejected without an
-alias. The task prerequisite, the take-over exception and ordering rules are unchanged;
-the task-conflict diagnostic is `break.on-break.tasks`. Team member availability already uses
-`on-break` and is unchanged.
-
-Migration: the former refusedReason field is now `BreakState.requestUnavailableReason`.
-It explains why requests are unavailable when `canRequestBreak` is false; `decisionReason`
-continues to explain a particular approval or denial. The old field is rejected even alongside
-the new one, and related diagnostics use requestUnavailableReason.
-
-Migration: the former mayAsk field is now `BreakState.canRequestBreak`. The old field is
-rejected even beside the new field. Validation diagnostics use canRequestBreak in place of
-mayAsk. Request eligibility remains distinct from approval; existing alwaysAvailable reason
-exceptions are unchanged. Hosts and providers must update together.
-
-Migration: ImposedBreak is now `ForcedBreak`, and the former imposed field is now
-`BreakState.forced`. Diagnostic and harness coverage names use `break.forced`. The former agent-end prohibition
-has been removed: forced breaks also permit explicit agent resumption. Update hosts and providers together. The old field
-is rejected, including when both spellings are sent; no compatibility alias is provided.
-The break policy value formerly named auto-approve is now `automatically-approved`.
-Requests are approved automatically; approval does not skip commitment or the prerequisites
-for starting a break. The former value is rejected without an alias.
-The break policy value formerly named suspended is now `requests-suspended`. The former
-value is rejected without an alias. It suspends new requests, not breaks already underway.
-The break policy value formerly named ask is now `approval-required`: requests require
-approval. The former value is rejected without an alias; automatically-approved and requests-suspended retain
-their existing behavior.
-The team break command formerly named policy is now `set-break-policy`. The former
-command is rejected without an alias; its policy field is unchanged. Hosts and providers must adopt the new name together.
-The team break command formerly named decide is now `decide-break-request`. The former
-spelling is rejected without an alias; the granted/denied decisions and pending-request
-prerequisite are unchanged.
-The team break command formerly named place is now `force-break`. Hosts and providers must
-adopt the new command together; place and the interim force spelling are rejected without aliases.
-The team break command formerly named release is now `end-forced-break`, and its diagnostic is
-`team.command.endForcedBreak`. The former release command and the interim end spelling are rejected without aliases.
-The agent’s `endBreak` now applies to forced breaks as well as requested breaks.
-
-`ForcedBreak` names who forced the break and may say how long it is expected to run yet, as
-`expectedEndsInSeconds`: whole seconds from the publication that carries it, restated on every
-publication, so every screen -- the agent's, reloaded or not, and every lead's -- counts down the
-same number from receipt (`break.forced.expectedEndsInSeconds`). The duration the lead asked for
-travels on the `force-break` command alone; the state says what is left, and drops the field once
-it has run out. The agent must explicitly resume when ready. The retired endsAutomatically and
-endsAt fields are rejected, including when an expectation is also provided. Who forced it is
-`by`, as **A forced break is the provider's act** below sets out.
-
-Omni resolves the name to show with `getUserDetails()`, so a provider sends the identifier and never
-a display name.
-
-**A forced break travels with `on-break` or `starting-after-task`, and nothing else.** It is a
-break in progress or about to be; beside `granted` or `awaiting-approval` the agent application would read a
-request the agent never made and commit it (`break.forced.status`). Where the provider publishes
-`reasons`, the lead's `force-break` named one, and the member's state carries it as `activeReasonId`.
-
-For example:
-
-```ts
-forced: {
-  by: "manager-1042",
-  expectedEndsInSeconds: 600
-}
-```
-
-The agent application keeps **Resume** available for an agent on a forced break. The agent explicitly chooses
-Resume; the agent application sends `endBreak()` and follows the provider-confirmed state before resuming
-work. The expectation is whole seconds still to run, restated on every publication; omission
-means none was stated, or it has run out. Neither its reaching zero nor an overdue indication
-authorizes the agent application or provider to end the break, restore availability, or route
-work to the agent.
-
-**A forced break is the provider's act.** A lead's `force-break` is a command to the provider,
-which forces the break on the member; `by` names the lead who asked it to. A break the platform
-imposed on its own -- a schedule, a compliance hold -- says `by: "provider"`, and is the platform's
-to lift: a lead's `end-forced-break` on it is refused before it is sent
-(`team.command.endForcedBreak.provider`), and a provider that receives one answers `failed` with
-`omni.break-forced-by-provider`. The desk offers End forced break on a member only where
-`forced.by` names a lead.
-
-**A lead lifting the restriction does not resume the agent.** On an applied
-`end-forced-break`, the provider clears `BreakState.forced` while preserving the current
-`on-break` or `starting-after-task` status and `activeReasonId`. This command cannot publish
-`not-requested`, restore readiness, or start routing work. Ordinary progress from
-`starting-after-task` to `on-break` still happens when work finishes. The agent application follows the
-published state and waits for the agent's explicit Resume, even after reconnect. Historical
-attribution is not rewritten by clearing the current forced marker.
-
-The agent may explicitly resume either before or after the lead lifts the restriction. A lead
-command, timer, late snapshot or reconnect is never a substitute for that choice. Providers
-must correlate resumption to the authenticated agent's action; a state-only ordering validator
-cannot establish the cause of a transition. The usual multi-provider end/reconciliation flow
-still applies, and work resumes only on confirmed provider state.
-
-An agent application counts `expectedEndsInSeconds` down from receipt, on every publication that
-carries it, and shows nothing of it where the provider sends none. It invents no start and no
-return time, and nothing acts on the number reaching zero.
-
-A break applies to the **agent**, not to one provider. When a provider forces one, Omni stops the
-agent everywhere else at once, and not by asking: it states `setCapacity({ count: 0 })` on every
-other usable provider holding capacity, which is taken and never refused, and which their team
-lists show as `elsewhere`. Nobody on those providers can deny it, and the agent cannot cancel it,
-because there is nothing to cancel: a break request on them would be the agent's own to withdraw
-and a lead's to refuse, and a forced break is neither. When the forcing provider ends the forced
-break and the agent resumes there, the agent application restates its capacity on the rest. A
-provider whose login is not usable is left alone, as a break attempt leaves it;
-`assertForcedBreakStopsTheRest` holds an agent application to this set. **The provider keeps its
-shift totals true.** A member held elsewhere is one the provider sees -- `elsewhere` is a state it
-publishes -- and the day's `shift` is its own account of the day, so the time the agent was
-stopped for a break forced on another provider is the provider's to count, as a break of a kind
-its platform has, or introduces, for exactly this. A `breakSeconds` that leaves it out is a total
-the provider knew to be short, and **Never report a value you cannot observe** cuts the other way
-here: the provider observed it.
-
-`ForcedBreak.by` says who forced it: a lead, by user id, or `provider` where the platform itself
-did -- on its own rule, a schedule, a compliance hold. The agent sees who, and `getUserDetails()`
-is owed for a person, never for `provider` (`break.forced.by`).
-
-## Capacity and break actions
-
-**Each method answers in its own words.** A result is read by a person far more often than it is
-branched on by code — in a log, a support ticket, a conformance failure — so it says what happened
-rather than that something happened. `failed` is shared, because failing is the same act
-everywhere; success is not.
-
-| Method | Succeeded |
-| --- | --- |
-| `setCapacity` | `applied` |
-| `recordStep` | `recorded` |
-| `requestBreak` | `requested` |
-| `commitBreak` | `committed` |
-| `cancelBreak` | `cancelled` |
-| `endBreak` | `ended` |
-
-`failed` carries a typed `ProtocolFailure` and means the provider did not take the action, whether
-it would not or could not.
-
-**Succeeding is not the outcome.** `requested` says the provider holds the request, not that a
-break was granted; `ended` says the provider has the instruction, not that the agent is working
-again.
-Every break method reports its real result through `break-state`; `setCapacity` reports none at
-all, because capacity is a statement rather than a request.
-
-`execute` keeps `applied` rather than a verb per command, because the command
-is in the request: `execute({ command: { type: "hold" } })` returning `applied` already says the
-hold applied. A `held` result would repeat the discriminant that travelled with it.
-
-### `setCapacity(capacity)`
-
-States how many tasks this provider may have assigned to the agent **at once**.
-
-`count` is an absolute ceiling, not an increment, a whole number of zero or more
-(`capacity.count`). An agent's capacity is a property of the agent, not of the moment: it is
-stated when the agent is set up and restated only when it genuinely changes, which is a
-local policy change rather than a task starting or ending -- with one exception below.
-
-**The provider counts its own outstanding tasks against it.** Assign while you hold fewer than
-`count` tasks for this agent, and stop when you hold that many; when one of yours ends you have
-room again and need no new signal to know it. Omni does not re-state capacity as tasks come and
-go, and a provider that waits for it will stall.
-
-Your own tasks are the only ones you count. What the agent holds at other providers is not your
-concern — Omni set `count` knowing it, and this is how: the agent is one person on several
-providers, and the agent application divides their capacity among them rather than telling each the whole. A
-provider that has none of it for now is told **`count: 0`, agent application-stopped**: assign nothing, show
-the member as `elsewhere` on the team member list -- signed in here, capacity held by the agent application for elsewhere,
-a fact this provider holds, where `on-task` would assert work it cannot see -- and take the next
-count as any other when the agent application has capacity for this provider again. Zero is the one restatement
-that follows work rather than local policy.
-
-**A capacity is taken, never refused.** `setCapacity` answers `applied` and nothing else: a
-statement has no failure to report, and a `failed` arm gave four agent application-provider pairings four
-readings of which ceiling stood after it. A provider that cannot carry the count assigns within
-what it can and says so on a `diagnostic`, so the gap is visible and nothing is inferred from a
-refusal.
-
-Capacity supersedes rather than accumulates: the latest value is the ceiling, and a decrease is as
-ordinary as an increase. A provider whose ceiling can only rise -- one that keeps the highest count
-it was ever told, or returns early on a small one -- cannot be told to take less work, and an agent application
-taking capacity away is answered `applied` while the work keeps coming. The harness moves the axis
-both ways after the drive, two then one then nought, and an offer after a lower count is caught
-against it (`stream.taskOffered.overCapacity`).
-
-**Capacity gates what the provider assigns, not what the agent starts.** A call placed from the
-idle dialpad arrives through `task-offered` like any other task, and a full agent does not forbid
-it: the ceiling binds assignment, not the agent's own hand.
-
-### Runtime break prerequisite checks
-
-Use `validateBreakCommand(method, request, state, context)` from the validation entry point
-before any agent break dispatch. The context supplies current authentication and transport;
-all four methods require the live login's break capability and active transport. Pass the
-request object only to the request method, and undefined to the other three.
-
-| Method | Required current state |
-| --- | --- |
-| `requestBreak` | `not-requested`; selected current reason code when codes exist; `canRequestBreak` or the selected reason's `alwaysAvailable` exception. Free text does not replace a code. |
-| `commitBreak` | `granted`, or already committed for an idempotent repeat. A later change to `canRequestBreak` does not revoke the grant. |
-| `cancelBreak` | `awaiting-approval` or `granted`. A concurrent commit winning still answers `omni.break-already-committed` and requires recovery. |
-| `endBreak` | `on-break` or `starting-after-task` during reconciliation; the agent may explicitly end a requested or forced break. |
-
-Use `validateTeamCommand(request, context)` before every lead act: the team feature switch, break
-decisions, forcing and ending a forced break, policy, and every act on a member's call. It requires
-the live `lead` flag and active transport, a current team member list for any command naming a
-member, and the target's complete break state for forcing/ending a break. Approve/deny requires an
-awaiting decision; forcing a break uses the target's reason codes; ending a forced break requires a
-forced committed break; join and decline need the member's request on the list; coach, join-call
-and leave need the lead already on that member's call; an assignment named must be one the list
-shows the member holding. The context's target state must belong to the named member; that
-association and backend authorization are provider responsibilities.
-
-Use `validateBreakStatus(state, tasks)` on the complete retained task view after each transaction,
-as well as `validateBreakTransition` for event ordering. Snapshot validation shares the status
-checks. Pending and completing tasks still count as work. Only a call a lead took over
-(`takenOver`) sits beside a break in effect. Validate full task shapes and the envelope separately.
-
-These validators report violations without dispatching, rewriting state or proving freshness.
-Recheck prerequisites atomically at the provider; client validation cannot prevent a race.
-Continue to use `validateResult` for each method's response vocabulary. A request acknowledgment
-is not a grant, and no method response overwrites a newer state emission. Rejected promises
-remain unknown and recover by snapshot, not automatic retry. The agent application's frozen provider set,
-durable mutually exclusive commit/cancel decision and reconciliation obligations under
-**Coordinating a multi-provider break** remain
-required; per-provider validation does not implement the multi-provider coordinator.
-
-### `requestBreak(request)`
-
-**Explanatory text is optional.** An agent may omit `BreakRequest.reason` for any break type.
-A lead may likewise omit reason text from `force-break`. Do not require a text explanation
-just because a break is agent-requested or forced. If supplied, text must be nonempty; omit
-it rather than sending an empty string. A selected `reasonId` identifies a published break
-choice and is separate from this optional text.
-
-With published choices, `{ reasonId: "lunch" }` is a valid request without explanation;
-without published choices, `{}` is valid. A lead can similarly send a `force-break` command
-with its member ID and, where required, the selected reason ID, without reason text.
-
-Requests permission to stop the agent later; it does not itself stop work. The provider continues
-offering work and reports `awaiting-approval` or `granted` through `break-state` events. If the request is denied, the
-provider reports `not-requested` directly, with `decisionReason` when one was supplied.
-
-**An agent asks from anywhere — idle or on a task** — and Omni offers the request in the task
-workspace as it does on the idle dashboard. Asked on a task, the break is decided and committed like
-any other and begins when the work ends: that is `starting-after-task`, and
-`assertBreakBeginsAfterTask` is the scenario that holds a provider to it.
-
-#### Break reasons
-
-A provider that defines not-ready reason codes publishes them on `Snapshot.break.reasons`,
-and Omni returns the agent's choice as `BreakRequest.reasonId`:
-
-```ts
-break: {
-  reasons: [
-    { id: "lunch", label: "Lunch" },
-    { id: "training", label: "Training", group: "Scheduled" },
-  ]
-}
-```
-
-Reason ids are non-empty and unique within the provider. They live on the snapshot rather than the
-manifest because a provider may change the codes it offers during a shift; a `snapshot` event
-replaces the list. `BreakRequest.reason` remains available for free text and is never a substitute
-for `reasonId` when the provider publishes codes. A provider that defines no codes omits the
-field.
-
-#### One break across several providers
-
-An agent connected to several providers takes **one** break, not one per platform. Omni gathers
-what every connected provider offers, shows the distinct breaks, and on a choice sends one request
-per provider: the same `reason`, and each provider's own `reasonId`.
-
-To do that, Omni has to know when two providers mean the same break. Say so with `kind`:
-
-```ts
-break: {
-  reasons: [
-    { id: "lunch", label: "Lunch", kind: "meal" },
-    { id: "rest",  label: "Mandatory rest period", kind: "rest", alwaysAvailable: true },
-  ]
-}
-```
-
-A provider decides which breaks it offers and what it calls them. `BREAK_KINDS` is the list Omni
-supports mapping them onto, and every member means something specific:
-
-| Kind | What it means |
-| --- | --- |
-| `short-break` | A brief rest between contacts — the comfort break a shift plan allows for. |
-| `meal` | A meal: lunch, dinner, whatever the shift calls it. |
-| `rest` | A rest period the agent is entitled to and a busy hour cannot cancel. Usually the reason also marked `alwaysAvailable`, though the two are separate: this says what the break *is*, that says whether policy can withdraw it. |
-| `training` | Learning something the agent is expected to know afterwards: a course, e-learning, a product walkthrough. However it is delivered, and whoever attends. |
-| `coaching` | Reviewing this agent's own work with somebody accountable for it: a call listened back, quality feedback, a one-to-one about their interactions. Even where the outcome is that they learn something. |
-| `meeting` | A scheduled gathering that is neither — a team huddle, a project call, a town hall. The agent attends and contributes; nobody is assessing their work and there is nothing they must know by the end. |
-| `administrative` | Paperwork and follow-up not attached to a particular contact. |
-| `technical` | Equipment or system trouble stopping the agent taking work: a dead headset, a phone that never registered, a tool that will not load. The one member that is not an activity — it says why the agent *cannot* work rather than what they are doing, which makes it the right home for a not-ready state raised about the agent's equipment. |
-| `personal` | Personal time the deployment does not classify further. |
-| `other` | None of the above. Matches nothing, including another provider's `other`. |
-
-**The definitions are the point, not decoration.** Ten undefined strings would be the label
-problem one level up: two providers could both declare `technical`, one meaning a dead headset
-and the other scheduled maintenance, match on it, and nothing could tell the difference.
-
-`training`, `coaching` and `meeting` can all fit one session, so take them in that order of
-specificity: about this agent's own work is `coaching`, else something they must know afterwards is
-`training`, else `meeting`.
-
-**A break somebody forced on the agent is not automatically one of these.** Where the agent was
-stopped rather than choosing to stop — see **Forced breaks** — set `BreakState.forced` and prefer
-omitting `kind` to reaching for `other`. None of the ten describes "something was done to this
-agent", and `other` claims a classification that was never made.
-
-Omni matches in this order:
-
-1. **`kind`**, where both providers declare one. This wins over the label, so `{ id: "MEAL",
-   label: "Meal", kind: "meal" }` lines up with `{ id: "lunch", label: "Lunch", kind: "meal" }`
-   and nobody has to word their codes the same way.
-2. **The label**, folded for case and surrounding spacing, where a kind is missing. `"other"`
-   counts as missing: two providers saying `"other"` have only said their break is not on the
-   list, which is no evidence they mean the same thing.
-
-Nothing else is matched. A break Omni cannot pair stays on its own, the agent is told how many
-platforms their break will actually reach, and they can pair the odd one by hand — Omni remembers
-that for next time.
-
-Three rules for a provider:
-
-- **Declare `kind` where you can, and leave it out where you cannot.** Leaving it out costs a
-  little precision. Getting it wrong sends an agent to lunch on one platform and to training on
-  another, and nothing can detect that.
-- **You may publish several reasons of one kind** — two meal slots, say. Omni will not choose
-  between them for the agent; saying they are the same kind is not saying they are interchangeable.
-- **Do not read `reason` as your own label.** It is the agent's single choice, in whichever
-  provider's wording they picked it from, sent unchanged to every provider in the break.
-
-A provider that publishes no reason codes still receives the request, with `reason` set and
-`reasonId` omitted.
-
-#### Coordinating a multi-provider break
-
-Sending the requests is a two-phase operation, not independent best effort. A provider first grants
-permission for the agent to stop, then Omni either commits or cancels that permission.
-
-`granted` is provider-visible state. It means only that this provider has granted the active
-request and is ready to stop the agent when Omni asks. It does not reveal that other providers exist
-or why Omni has not committed yet. While reporting `granted`, the provider remains available,
-continues to honour Omni's current capacity, and continues offering work normally.
-
-Omni separately tracks the aggregate agent application states `working`, `requesting-break`, `committing-break`,
-`cancelling-break`, and `on-break`. While `requesting-break`, Omni shows which providers remain
-outstanding and offers **Cancel break request**, but does not tell the agent that their break has
-begun.
-
-Omni offers the aggregate Break control only when every provider currently holding capacity
-declares `capabilities.breaks` at login. If one cannot be stopped, offering a global break would
-knowingly permit partial availability.
-
-Omni coordinates one break attempt as follows:
-
-1. Freeze the providers the attempt asks: every connected provider from which the agent can
-   currently receive work. A provider joining during the attempt is given no capacity until it
-   finishes. A provider whose authentication is `expired` is not one the agent can receive work
-   from and is not asked: nothing is asked of it, the break proceeds without it, and when the
-   login is restored it is reconciled from its snapshot as a set-aside provider is, with no
-   capacity until then. `refreshing` keeps a provider in — its identity and capabilities remain
-   available and work continues. `assertBreakAttemptProviders` holds an agent application to this set.
-2. Enter `requesting-break`. Keep the agent's normal capacity in place throughout this phase.
-3. Send one `requestBreak` to every asked provider. A provider reports `awaiting-approval` or
-   `granted`; neither state stops work. A denial transitions directly to `not-requested` and
-   causes Omni to take the cancel path.
-4. If every asked provider reports `granted`, durably choose commit, enter `committing-break`,
-   and send `commitBreak()` to each of them. A provider then stops offering new work
-   and reports `starting-after-task` or `on-break`. The **commit bound** — ten seconds from the
-   decision, tunable per deployment — decides who is kept: a provider that has not applied the
-   commit by then, still `granted` or unreachable, is set aside as unreconciled and the break
-   begins without it. `on-break` decides `on-break`: Omni enters it once every kept provider
-   reports `on-break`. A kept provider reporting `starting-after-task` has applied the commit
-   and is finishing a task; the bound is on delivery, not on that task. Omni shows the break as
-   settled and beginning when the task ends, and offers no cancel, because the commit is durable.
-5. If any asked provider fails or denies the request, cannot be reconciled within the bounded
-   decision timeout, or the agent cancels before commit, durably choose cancel and enter
-   `cancelling-break`. Send `cancelBreak()` to every provider still reporting
-   `awaiting-approval` or `granted`. Work continues during cancellation because no stop was
-   committed. Return to `working` only after no provider retains either state.
-
-Commit and cancel are mutually exclusive decisions for one break attempt. Once Omni chooses commit
-it never rolls that attempt back: it is reconciled by snapshot until every asked provider is stopped.
-A provider that reports `granted` must therefore preserve the request across reconnects and must
-honour a later commit or cancel. This
-durable promise prevents a provider from failing the commit after another provider has already
-stopped the agent.
-
-#### Why the commit phase is bounded and the decision is not
-
-Waiting for unanimity forever is the one way this algorithm can strand an agent. The commit is
-durable and cannot be rolled back, so a provider that crashes, has its authentication revoked,
-or is uninstalled between granting and committing would hold Omni in `committing-break` with no
-exit: the providers that did commit have already stopped the agent, and the agent is neither
-working nor on a break.
-
-Unanimity is required for a reason that survives the bound. It exists so the agent is not stopped
-on one platform while another keeps routing work to them — and **a provider Omni cannot reach is
-routing nothing.** Setting it aside therefore costs none of the property it was protecting. Waiting
-for it costs the agent their break.
-
-Setting a provider aside is not a rollback and not a cancel. The commit stands and the
-obligation stands: until that provider is stopped it has not stopped. When it returns it emits a
-snapshot before anything else, and the snapshot decides:
-
-- `on-break` or `starting-after-task` — the commit arrived after all. Nothing to send.
-- still `granted` — the commit was lost. Omni sends `commitBreak()` now. If the original turns up
-  late behind it, the provider stops an agent who is already stopped; nothing happens, because a
-  commit is a state to be in, not an act to be done.
-- `not-requested` — the grant did not survive. Omni makes a new request for that provider alone,
-  against an agent who is already on break elsewhere. **A new login is this case too**: the grant
-  belonged to the old session.
-
-The provider must not offer work in the meantime, and the commit is what stops it; Omni gives it
-no capacity until it is reconciled.
-
-**If the agent has already ended the break elsewhere, the break attempt is over** and the returning
-provider is reconciled to that instead: still `granted` gets `cancelBreak()`, because committing
-would stop an agent who is working again; `starting-after-task` or `on-break` gets `endBreak()`.
-Never rolling back is about a break that is still on, not one the agent has finished.
-
-Omni may tell the agent which platforms the break has not yet reached, as it already does when a
-break cannot be paired across every provider.
-
-The decision phase needs no such bound, because nothing has stopped. Work continues throughout
-`requesting-break`, so a provider that never answers costs the agent a wait rather than their
-availability, and the existing decision timeout resolves it by cancelling — which is safe precisely
-because no stop was ever committed.
-
-If cancel races with a late approval, the provider remains on the cancel path. If commit has already
-won, cancel returns `omni.break-already-committed`, and Omni resumes commit recovery rather than
-returning the agent to `working`.
-
-A forced break is not rolled back by this algorithm. If one appears during either the request or
-cancellation, the attempt is abandoned: Omni cancels every grant still outstanding and states
-`setCapacity({ count: 0 })` on every other usable provider, as **Forced breaks** sets out; no grant
-is committed, because the agent has already stopped everywhere.
-
-This is two-phase coordination across vendor systems: the approval phase keeps the agent working;
-the durable commit decision and snapshot reconciliation provide convergence after partial delivery.
-
-#### Reporting the break the agent is on
-
-`BreakState.activeReasonId` is the `BreakReason.id` the current break is on. Omni remembers what it
-asked for, but only until the session ends — after a reload or reconnect, or where the provider put
-the agent on the break itself, the provider is the only one who knows.
-
-Omit it when you cannot say, and when there is no break: reporting a reason alongside
-`status: "not-requested"` describes a break that is not happening, and is rejected.
-
-### `cancelBreak()`
-
-Cancels the active pre-commit request while its status is `awaiting-approval` or `granted`.
-Cancellation releases the request but does not restore work because work never stopped. If
-commit already won, the provider returns `omni.break-already-committed`. The resulting state is
-reported through `break-state`.
-
-### `commitBreak()`
-
-Commits the `granted` request. Once the provider has reported `granted`, it cannot fail for a
-business reason. On commit the provider stops offering new work and reports
-`starting-after-task` while existing work finishes, or `on-break` when the break is in effect.
-Committing a break that is already in effect changes nothing and answers `committed`.
-
-### `endBreak()`
-
-Tells a provider that an agent already on a break wants to become available again. The provider
-reports the resulting state through `break-state` and provider status events.
-
-It ends the break, which is the thing that started. Nothing about the connection was ever paused,
-so there is nothing on it to resume.
-
-## Team leads
-
-The team feature is the lead's own surface, beside the agent's and never mixed with it. The
-login's `lead` flag turns it on in the agent application; the lead retrieves their members and
-sees, for each, their assignments as they stand and the full history of each, and acts on them
-with the authority the flag carries. Nothing the lead does here is a task on their desk. A lead
-who also takes calls is an agent like any other on the agent side, and a lead who does not want
-the agent role for now places themself on a break of a working kind and keeps the team feature on.
-
-The team reaches the lead whole once, on `team-updated` after the lead switches the feature on
-and on every snapshot while it is on, and from then on one member at a time: when a member is
-offered a call, answers, holds, mutes or is taken over, the provider publishes that member whole
-on `team-member-updated`, so the lead's screen moves when the member's does and a team of two
-hundred is never resent because one of them held. The agent application asks for nothing and
-computes nothing. See **`team-updated`** and its companions.
-
-| Field | Contract |
-| --- | --- |
-| `members` | Every member of this lead's team, whatever their state, each with their open tasks. `[]` says the lead has a team with nobody in it; omitting the team member list says something else entirely — see **The login is the permission** below. |
-| `policies` | The team's policy per capability as it stands — the setting, who set it, and `lockedBy` where a level above the team made it theirs to keep. Present where the provider offers policy control; absent where it does not. See **Who decides what an agent may do**. |
-
-| `TeamMember` field | Contract |
-| --- | --- |
-| `id` | Required `UserId`. A task carries no names and neither does a team member list: Omni resolves what to display with `getUserDetails()`. |
-| `availability` | Required. What the member is doing now. |
-| `since` | Optional. When the current `availability` began — not when they signed in, and not when the team member list was read. |
-| `break` | Present only while the member has an outstanding break request. See **A member waiting for a break**. |
-| `tasks` | The member's open tasks as `MemberTask`s: the same task the member's desk holds, less the workspace. The assignment, title, task type, phase, party, room, audio and completion terms -- `completionMode`, `wrapAllowance`, `wrapEndsInSeconds` -- are what the lead reads, and the task's record -- `history`, steps and totals -- travels whole, exactly as the member's desk holds it, so the lead's screen and the member's show the same record. The workspace -- `capabilities`, `capabilitySource`, `browsers` and their URLs -- is the member's desk's alone and never travels (`team.member.task.workspace`). The party's number and email are shown to leads or locked as the provider decides for leads, apart from what it decides for the member -- see **What the queue locks is locked on the whole task**. `[]` when the member holds none; omitted only where the provider cannot see them. |
-| `listening` | Every lead on this member's call — listening, coaching or joined — published to every lead alike: each entry names the lead by `leadId`, which of the member's calls by `assignmentId`, the `mode` they are heard in, and since when. The entry naming the signed-in lead is what their own audio opens on. Absent while nobody is on the call, never `[]` (`team.member.listening.*`); a lead is on one member's call at a time (`team.listening.single`), and a lead who is heard is also in the task's `onCall` (`team.member.listening.heard`). |
-| `request` | Present while the member is asking a lead to join one of their calls: which assignment, the note they wrote, since when. The call named is one their `tasks` carry (`team.member.request.assignment`). Absent when they are not asking. See **Lead assist**. |
-| `shift` | The member's own history for the day, about the person rather than any one call: `signedInAt`, `signedOutAt` once it has happened, today's totals as the provider counts them — `talkSeconds`, `holdSeconds`, `breakSeconds`, `tasksHandled`, each present only when the provider knows it — and the day's sign-in, sign-out and break `events`, oldest first. The same `Shift` the member's own snapshot carries, the same numbers from the same count. Omitted where the provider cannot say. |
-
-Each availability value means one thing:
-
-| Value | Meaning |
-| --- | --- |
-| `ready` | Signed in, able to take work, none assigned. |
-| `on-task` | Working on at least one task. It says nothing about how many, and nothing about whether more will fit. |
-| `on-break` | Stopped and not taking work, whether they asked or somebody stopped them. The reason lives on their own `BreakState`, not here. |
-| `elsewhere` | Signed in here, and the agent application holds this agent's capacity for another provider (`count: 0`, agent application-stopped): not receiving this provider's work, and not on a break. See **Capacity**. |
-| `signed-out` | Known to this team but not signed in to this provider. |
-
-**Publish the whole team once, then each member whole.** Team presence typically reaches an
-adapter over a best-effort channel with no ordering and no delivery guarantee, so the adapter
-reconciles against its own authoritative read before it publishes anything. What it publishes is
-the whole team on `team-updated` -- after the switch, and on every snapshot -- and after that one
-member at a time on `team-member-updated`, carrying the member whole: their availability, their
-tasks, their listening, their shift, their request, as they now stand. Applying the same member
-twice changes nothing, so a redelivery is harmless, and a member the team never carried is added
-by it, as a colleague signing in is. `team-member-removed` takes one off. Never a field of a
-member, never a task of theirs on its own: a hold on a member's desk is that member republished
-whole on the lead's, and nothing else on the lead's screen moves.
-
-**Whatever the member's desk hears of a task, every lead hears of the member.** The trigger is
-not a list of changes but the publication itself: each `task-offered`, `task-updated`,
-`task-audio-started`, `task-audio-ended` and `task-ended` the provider sends to the member is
-matched by a `team-member-updated` to every lead with the feature on, carrying the member whole
-with the task as it now stands, or without it once it has ended. A held leg closing with its
-`seconds`, a room restated, a phase moving, the wrap left ticking on a restatement: each reaches
-the lead's copy in the same round it reaches the member's, and the two copies of the record never
-part for longer than the delay between them.
-
-**The agent's day is on the wire.** The lead sees `shift` totals as the provider counts them, and
-the agent sees the same: `Snapshot.shift` and `shift-updated` carry the agent's own day in the same
-shape, from the same count, so "calls today: 12" is one number on both screens. The desk computes
-nothing of the day; `tasksHandled` moves when a task ends and `talkSeconds` when a leg closes, and
-the active call's running time is the screen's own until then, as **Every screen counts from the
-provider's clock** sets out.
-
-**Omit `since` rather than inventing one.** Omni renders it as a duration, so a timestamp
-synthesised from the adapter's own clock at seed time reads as "on task for 0 seconds" for
-everybody — worse than showing nothing, because it looks like data. Send it only when the provider
-knows when the state actually began. It times the current `availability`, so it moves every time
-that value does. And it is counted from the provider's clock, never the screen's, so a provider
-that publishes it declares `timeCheck` -- see **Every screen counts from the provider's clock**.
-
-**The login is the permission.** A team member list goes to a login that declares
-`capabilities.lead`, once the team feature is on, and to nobody else. Omni never decides who
-leads a team: the provider said so at sign-in, and the team member list agrees with it — owed,
-`members: []` included, once a lead has switched the feature on; absent for everybody else, which
-is the correct rendering for an agent who leads nobody (`team.required`, `team.unentitled`). What
-the lead may do with it comes with the flag: there is no per-action permission on the login or on
-the list.
-
-**The lead switches the feature on and off, and the provider is told.** A lead may work as an
-agent alone, as agent and lead, or as lead alone, and moves between them on the fly. The
-agent application says which with `{ type: "lead-features", enabled }`: while it is on, the
-provider sends team events scoped to the lead's team and the lead may act; while it is off, the
-lead is an ordinary agent, nothing of the team is owed or expected (`team.unexpected`,
-`event.team.features`), and no lead act is possible, since the lead learns their members'
-assignments only from the list.
-
-**The provider assumes nothing.** The switch is not remembered across connections: the agent
-application sends `lead-features` on every connect, after it has stated capacity, and until it has
-the provider treats the feature as off. The connect snapshot therefore carries no team, whatever
-the login declares; the whole team arrives on `team-updated` once the switch is on, and every
-snapshot after that carries it. A conformance run switches the feature on for a lead and holds the
-provider to that first `team-updated` (`team.required`); a team on the connect snapshot is the
-provider assuming (`team.unexpected`).
-
-**The team member list never carries the agent it is published to.** A lead does not report to
-themself: their own break request and their own ask for a lead go up to whoever leads them and
-appear on *that* person's team member list, as a member with a `request`, while the requester sees
-only their own `BreakState` and their task's `leadAssist` move. An adapter whose platform lists the lead
-among their own members filters the signed-in identity out before publishing. **Being a lead is a
-role the provider knows, never inferred from who is listed:** it is declared at sign-in, a lead
-with nobody in their team publishes `members: []`, an agent with no such role publishes nothing, and no
-member count can tell those two apart.
-
-### Lead commands
-
-One method, `executeTeam`, taking a discriminated command exactly as `execute` takes a
-`TaskCommand`. Every act on a member's call names the member, `memberId`, and may name the
-assignment, `assignmentId`, where the lead has it; the provider resolves the member's current
-assignment from the member alone.
-
-| Command | Effect |
-| --- | --- |
-| `{ type: "lead-features", enabled }` | The team feature on or off. See **The lead switches the feature on and off** above. |
-| `{ type: "decide-break-request", memberId, decision, reason? }` | Settles one pending request. `decision` is `granted` or `denied`. A grant moves the member to `granted`; a denial ends the request and moves it directly to `not-requested`. |
-| `{ type: "set-break-policy", policy }` | `approval-required`, `automatically-approved`, or `requests-suspended`. |
-| `{ type: "force-break", memberId, reasonId?, reason?, expectedDurationMs? }` | Puts a member on a break they did not ask for. `reasonId` names a published `BreakReason.id` and is required whenever the provider publishes `reasons`; the member's forced break carries it as `activeReasonId`, so its kind is known. Optional `expectedDurationMs` is advisory; the resulting forced break publishes what is left of it as `expectedEndsInSeconds`, restated on every publication. |
-| `{ type: "end-forced-break", memberId }` | Asks the provider to lift a forced-break restriction a lead asked for, by clearing `BreakState.forced`; one the platform imposed is its own to lift (`team.command.endForcedBreak.provider`, `omni.break-forced-by-provider`). The committed break continues; only the agent resumes work. |
-| `{ type: "join", memberId, assignmentId? }` | Answers the member's request: the provider bridges the lead's channel into the call. See **Lead assist**. |
-| `{ type: "decline", memberId, assignmentId?, reason? }` | Refuses the member's request. |
-| `{ type: "listen", memberId, assignmentId? }` | The lead's channel joins the member's call unasked, in silence. See **Listening to a call**. |
-| `{ type: "coach", memberId, assignmentId? }` | The lead is heard by the member alone. Needs the lead on that member's call. |
-| `{ type: "join-call", memberId, assignmentId? }` | The lead is heard by everyone on the call. Needs the lead on that member's call. |
-| `{ type: "leave", memberId, assignmentId? }` | The lead's channel leaves the member's call, however it got there. The member's call goes on. |
-| `{ type: "take-over-call", memberId, assignmentId? }` | The provider moves the call to the lead as its new agent, from a joined call or a listened one alike. See **Lead assist**. |
-| `{ type: "set-policy", capability, setting }` | Sets the team's policy for one capability: `on`, `off`, or `person`. See **Who decides what an agent may do**. |
-
-`memberId` is this provider's own identifier for the member, as published on its team member list. It is
-never an identifier from another provider, and Omni does not translate between them; names come
-from `getUserDetails()`. `validateTeamCommand` holds each command to the team member list as it
-stands -- see **Runtime break prerequisite checks**.
-
-`requests-suspended` means requests are **rejected outright** rather than left pending — nobody is coming to
-approve them. A provider that suspends break requests must also publish `canRequestBreak: false` to the team's
-agents so they see it before asking. A `force-break` must likewise reach that member as a `forced` break
-on their own `BreakState`, or they are stopped from working with no way to see why.
-
-What happens when no lead is online — auto-approving, for instance — is the provider's decision and is
-never expressed here.
-
-### Lead assist
-
-An agent on a call may ask a lead to join it -- a dispute that needs approval, a customer who
-asks for a manager, a moment the agent wants a second pair of ears. A call centre calls this
-assistance or escalation, and the name says who assists: the capability is `leadAssist` on the
-task; the lead's side is the team member list, which is already the lead's view of the team. The
-flow, in order:
-
-```ts
-// 1. The agent asks, with a small note. Their task carries `leadAssist` from here on.
-execute({ assignmentId: "alloc-42", command: { type: "lead-assist", action: "request", note: "Refund dispute, needs approval" } })
-//    task.leadAssist = { stage: "requested", note: "Refund dispute, needs approval", since }
-
-// 2. Every lead with the team feature on sees the request on the member.
-//    team-member-updated: member: { id: "A-1", ..., request: { assignmentId: "alloc-42", note, since } }
-
-// 3. A lead joins, or declines.
-executeTeam({ command: { type: "join", memberId: "A-1", assignmentId: "alloc-42" } })
-executeTeam({ command: { type: "decline", memberId: "A-1", reason: "In a call" } })
-```
-
-**On `join` the provider bridges the lead's channel into the call.** The member's task moves to
-`leadAssist: { stage: "joined", leadId }` and its `onCall` gains the lead as an `agent`, since a
-lead who is heard is in the room; the member on the team member list carries
-`listening: [{ leadId, assignmentId, mode: "join-call", since }]`, and the lead's audio opens on
-it as **Listening to a call** describes. Nothing is a task on the lead's desk: a join is the lead's act on the team surface, not
-work assigned to them.
-
-**A lead is on one member's call at a time.** A `join` from a lead already on a call -- their own
-or a member's -- is answered `failed`; the request stands for another lead, or until it is
-withdrawn or declined. A join is work, so Omni offers Join only to a lead whose voice channel is
-free, and a provider answers a `join` from one whose channel is not `failed`.
-
-**On `decline`, or a request the agent withdraws with `{ type: "lead-assist", action: "cancel" }`, the
-provider clears `leadAssist` from the agent's task** and drops the request from every team member list. Nothing
-else changes; the agent is still on the call.
-
-**On `leave`, the lead's channel drops and the call goes on**: the member's task loses its
-`leadAssist`, the member loses this lead's entry in `listening`, and the lead is free. Nothing ended for the member.
-
-**On `take-over-call`, the provider moves the call from the member to the lead**, and the lead is
-its new agent. There are two paths to it -- the agent asked and the lead joined, or the lead was
-listening unasked -- and one act at the end of either. What follows is the same on both:
-
-| | The member's task | The lead's desk |
-| --- | --- | --- |
-| Take-over | `task-audio-ended`, then `completing`: the member's interaction is over and their wrap runs, exactly as after `end-call`. The audio ends first, as before every voice ending (`stream.taskEnded.audioOpen`). The member loses this lead's `listening` entry on the team member list no later than the offer, and the lead's listening audio closes. | An ordinary assignment arrives: `task-offered` with `acceptance: "automatic"`, carrying the call's history and `takenOver: { memberId, since }`, within the lead's capacity. |
-| The member completes | `task-ended` with `{ type: "taken-over", leadId }`, at the member's own completion. The lead is named by user id, since a lead is not a directory item. | The lead works the call as any agent would, and ends it as any call ends. |
-
-**The taken-over call is offered whatever break the lead is on, and counted like any other.** A
-lead working as lead alone is on a break of a working kind, and the provider assigns the call
-regardless: it is the one task a break in effect may hold (`break.on-break.tasks` allows it, and
-nothing else). It is a call landing on the lead's desk, so it counts against their capacity as
-every call does, with no exemption: a lead at capacity cannot take over, and the provider answers
-`failed`. The other conditions are that the lead is not already on another call and their voice
-channel is free. A lead with the team feature off cannot take over, since they have no member's
-assignment to name.
-
-```ts
-const leadAssistCapable = {
-  channel: "voice",
-  capabilities: { hold: true, leadAssist: true, outcomes: true },
-  phase: "in-progress",
-  leadAssist: { stage: "joined", leadId: "L-9", note: "Refund dispute, needs approval", since: "2026-08-21T09:04:00Z" },
-} satisfies Pick<Task<"voice">, "channel" | "capabilities" | "phase" | "leadAssist">;
-
-const takenOver = {
-  channel: "voice",
-  capabilities: { hold: true, endCall: true, outcomes: true },
-  phase: "in-progress",
-  takenOver: { memberId: "A-1", since: "2026-08-21T09:06:00Z" },
-} satisfies Pick<Task<"voice">, "channel" | "capabilities" | "phase" | "takenOver">;
-```
-
-Lead and member alike are `UserId`s of this provider, so an adapter publishing them implements
-`getUserDetails()`; names never travel on a task or a team member list.
-
-### Listening to a call
-
-A lead may listen to a member's call without being asked -- to coach, to check quality, to step in
-when it goes wrong. It is a team act naming the member, and no task on the lead's desk carries it:
-the lead's view of the call is the member's task on the team member list, with its room and its
-history. The three modes determine who hears the lead:
-
-| Mode | Who hears the lead |
-| --- | --- |
-| `listen` | Nobody. The lead hears both sides in silence. |
-| `coach` | The agent alone. The customer hears nothing. |
-| `join-call` | Everyone on the call. |
-
-All three come with the `lead` flag; a centre reserves none of them per lead.
-
-**There is no team audio.** Audio is the agent's or the lead's, and the lead's audio while
-listening follows the provider's published state exactly as a task's does: the entry naming this
-lead in `listening` on the member is the provider's word that the lead's channel is in the call.
-When it appears, the application opens `openAudio({ assignmentId })` on the lead's connection for
-the call it names, and plays the `CallAudio` returned; when it goes, the application closes it.
-Another lead's entry opens nothing: it is shown, and that is all. Nothing else says
-when the lead's audio is up, and a reload reopens it from the snapshot's team member list as a task
-carried with `audio: "started"` is reopened.
-
-The flow, end to end:
-
-```ts
-// 1. The lead, with the feature on, sees a member on-task with their tasks, and picks a call.
-// 2. The lead's channel joins it in silence. Conditions: the lead's voice channel is free --
-//    not on a call, not listening elsewhere. Capacity is not involved: nothing is assigned.
-executeTeam({ command: { type: "listen", memberId: "A-1", assignmentId: "alloc-42" } })
-// 3. The provider publishes the member whole on team-member-updated, to every lead; the member carries
-//    listening: [{ leadId: "L-9", assignmentId: "alloc-42", mode: "listen", since }]
-//    -- L-9's application opens openAudio({ assignmentId: "alloc-42" }) on its own connection; every
-//    other lead's shows L-9 on the call and opens nothing.
-// 4. The lead changes how they are heard; the member is published again with the entry's new mode. The audio stays open.
-//    join-call is heard by everyone, so the member's task is also republished with L-9 on onCall as an agent.
-executeTeam({ command: { type: "coach", memberId: "A-1" } })
-executeTeam({ command: { type: "join-call", memberId: "A-1" } })
-// 5. The lead leaves: the provider publishes the member without L-9's entry, and the task without L-9 in the room; the application closes the audio.
-executeTeam({ command: { type: "leave", memberId: "A-1" } })
-// 6. The member's call ends: the same as leave, from the provider's side.
-// 7. The lead takes the call: the member loses this lead's listening entry no later than the offer, the application
-//    closes the listening audio, and the lead's own call arrives as an ordinary assignment marked
-//    takenOver, counted against capacity, with its audio following task-audio-started as any call's does.
-//    At capacity the take-over is refused and the lead stays listening.
-executeTeam({ command: { type: "take-over-call", memberId: "A-1" } })
-// 8. A join on the member's request is the same flow entered at step 3 with mode: "join-call",
-//    and the member's task shows leadAssist: joined.
-// 9. A reload of the lead's application: the switch is sent again, the team-updated that follows
-//    still carries this lead's entry in listening on the member, so the audio is reopened.
-```
-
-**`listening` on the member is the state**, one entry per lead on the call, restated on every
-change of mode, naming the lead (`team.member.listening.leadId`, once per member,
-`team.member.listening.unique`) and the call, so the application knows which audio is its own to
-open (`team.member.listening.assignmentId`, and one the member's tasks carry,
-`team.member.listening.assignment`). Every lead sees every entry: a silent lead is hidden from
-the agent, never from the other leads and managers watching the same member on other screens.
-A lead is on one member's call at a time (`team.listening.single`).
-
-**A lead listens while holding no call of their own.** Omni offers Listen to a lead whose voice
-channel is free, and a provider answers a `listen` from one whose channel is not `failed`. That
-includes a lead on a break: a lead working as lead alone is on a break of a working kind, and
-listens through it.
-
-**A silent lead reaches nobody but the leads.** In `listen` and `coach` the member's task carries
-no trace of the lead: not on `onCall`, not in the record. Whether coaching is announced to the
-agent is the platform's business and travels on the audio, not on this wire. In `join-call`, and
-on a `join` answering a request, the lead is heard by everyone and is in the room: the task's
-`onCall` carries them as an `agent` by user id, on the member's desk and on every lead's copy of
-the task alike, and `leave` takes the entry off as it takes the channel off
-(`team.member.listening.heard`).
-
-### A member waiting for a break
-
-A member who has asked for a break **keeps working** until Omni commits it, so asking is not an
-availability of its own — it rides alongside one on `break`. That a request exists says nothing
-about whether anybody has to act on it, and the difference is a lead's entire action list:
-
-| `break` | Means |
-| --- | --- |
-| `awaiting-approval` | Somebody has to decide. This is the lead's queue. |
-| `granted` | Decided yes, but Omni has not told the provider to stop yet. Work continues and nobody needs to decide. |
-| `starting-after-task` | Already granted; it begins when their current task ends. Nobody needs to act. |
-
-Those three are the only values that appear here. `not-requested` is absence — omit `break`
-instead. `on-break` is `availability: "on-break"`, and a denial transitions to `not-requested`,
-so neither survives to be reported. It is otherwise the same `BreakStatus` the member's own
-break state uses, rather than a parallel vocabulary for the lead's view, so the two cannot drift
-apart.
-
-Omni offers Approve and Deny only while a member is `awaiting-approval`, shows `granted` as agreed
-but not started, and shows `starting-after-task` as settled.
-
-**Live status, not a record.** The provider derives it from what is true now — not stored, not
-historical, carrying no decision made earlier. Like the team member list it belongs to, it is published
-whole and replaced whole, and a provider that cannot say omits it.
-
-**An agent is not waiting on one person.** Authority is held by several, everyone who holds it
-sees the request on their own console, and **any one of them settles it**. Omni offers the
-decision to every login that declares `lead` and has the team feature on — which is how the provider already
-says who may decide — and does not try to work out whose turn it is.
-
-A request needing *more than one* approval is not something this contract describes. There is
-no partial state to report and no progress to display: a request is either still owed a
-decision or it is not.
-
-## Real-time audio
-
-Every voice provider has audio: `channel: "voice"` says audio exists. Where the agent hears it
-depends on the `phone` the agent application selected at authentication and connect from the manifest's
-`phones`. On a softphone, audio lands in Omni; on a desk phone, it lands on the handset and Omni
-opens no audio. See **How the agent hears the call**. Audio transitions are voice-only;
-chat and email publish none (`event.audio.channel`, `stream.taskAudio.channel`).
-
-The provider owns signalling and the platform's endpoint configuration. The agent application selects the
-declared phone mode; it does not enumerate or reconfigure the platform's devices. The selected
-mode stays with the login rather than being inferred from a snapshot or a device failure.
-
-Nor does the audio ever stand in for the task: a task's presence and
-phase follow the provider's reports about the work, and the audio — attaching, moving through a
-hold, a conference, a lead joining or a take-over, and ending — is transient beside it. See **A task is
-never its audio** under **Task assignment lifecycle**.
-
-### The agent application reports, the adapter decides
-
-The adapter runs inside Omni and sees nothing of the station for itself: the devices, the
-permissions, the audio element and the network are the agent application's, and only the agent application can tell. So
-the agent application reports, and the adapter asks. **An adapter consults `ConnectContext.host` before it
-declares the agent ready to its platform, and again whenever the report changes**, and it decides
-what any of it means and what to relay upstream — go not-ready, refuse calls, carry on because the
-platform's audio lands elsewhere. Omni facilitates and does not take responsibility: it captures
-the microphone once as the voice connection opens, so the permission prompt lands while the agent
-is signing in rather than over a contact, prompts, retries on the agent's request, tells the agent
-what failed, and reports. It never decides for the adapter what a missing microphone means.
-
-**The agent application also guarantees, and a promise the provider cannot see is not one it can rely on.**
-Two of this contract's obligations fall on the agent application rather than the provider — honouring a task
-browser's `urlVisibility`, and taking a `consent` offer only on the person's own press — and more
-than one desk speaks this contract: a browser and a native application differ in what they can
-reach, and a provider never branches on which it is talking to, only on what it has declared —
-here, and in `host.mute` (see **The station is the agent application's**). So `ConnectContext.host.guarantees` says which promises the
-connected agent application makes, declared once per connection, presence being the guarantee exactly as it is
-the permission everywhere else:
-
-| Guarantee | Contract |
-| --- | --- |
-| `browserUrlVisibility` | Every task browser's `urlVisibility` is honoured in this agent application's chrome, tab by tab. A provider that would send a caller's number in a URL checks this first and tokenises where the promise is absent. |
-| `personConsent` | A `consent` offer is accepted only by the person's own explicit act, never on their behalf. A provider whose work may only be taken by a human checks this first and does not offer it where the promise is absent. |
-
-A guarantee the agent application does not make is an absent key, never `false` — `validateHostGuarantees`
-refuses a false one, as it refuses a name this contract does not list.
-
-| Field | Contract |
-| --- | --- |
-| `online` | Whether the agent application has a network interface up. Not a claim that anything is reachable — the adapter knows whether it can reach its own platform far better than the agent application does — so `false` is a reason not to go ready and `true` is not a reason to. |
-| `audio` | Present on a voice connection, absent where there is no audio. |
-| `audio.input` | `available` with `localAudio` — the microphone as captured, the same stream `openAudio` receives — and `flowing`, false while no audio moves through it, when `mutedBy` says who stopped it: `host`, the agent application's own Mute on an agent application that mutes the station, or `station`, a slider on the headset or the operating system, which the agent application observed and did not do. An adapter treats `host` as the agent's act on a call and `station` as a condition of the station. `unavailable` with `reason`, since each wants a different fix from the agent: `no-device`; `denied`; `not-asked`, which an agent application that asks at connect never publishes; `in-use`, a device present and permitted that another application holds — on an agent desktop the commonest of all; `lost`, a capture that ended. An agent application decides the reason from the devices before the error name: a browser can report a permission error on a machine with no microphone at all, and "grant permission" is the wrong instruction for an agent who needs to plug one in. `failure` carries the words Omni showed them. |
-| `audio.output` | `available`, with `flowing` where the agent application can know whether audio reaches the speaker — a browser mostly cannot, and omits it; a native agent application reads the endpoint — false while it is silenced, when `mutedBy` says who did it, as on input. Or `unavailable` with `reason` — `no-device`, or `lost` for one removed — and `failure`: an agent who cannot hear is as unable to take a call as one who cannot speak. |
-
-Omni republishes the report whenever it changes — a permission granted late, a headset unplugged,
-a network gone — and it publishes a state, not a flicker: a change that resolves within moments is
-not reported, so an adapter may act on what it reads without debouncing it again. Nothing in the
-report is a task fact or a capacity fact; it is what the station can do, and the adapter's platform
-is the one that knows whether an agent without a microphone, or without a speaker, can work.
-
-The agent application's own obligations here — asking at connect, never publishing `not-asked` when it does,
-publishing a state and not a flicker — are Omni's tests' to hold. `exerciseAdapter` holds the
-other side: it validates the shape of whatever agent application a test hands the adapter, requires `audio` on
-a softphone login and none elsewhere -- not on a desk phone, not off voice
-(`context.host.audio.required` / `.unexpected`), holds `host.mute` to the same line (`host.mute.required`
-/ `.unexpected`, `host.mute` for a third word) -- and refuses a voice adapter that never asked the
-agent application anything (`connection.host.consulted`), and one that subscribed to nothing will never hear of a
-change (`connection.host.subscribed`): the obligation has two halves, and each is held.
-
-### Capacity around setup
-
-Connecting is not the same as being able to take a call. A provider that treats a live connection
-as reachability opens a window where it believes the agent is available and the agent is not yet
-set up — the adapter's own registration incomplete, its credentials not yet renewed.
-
-Nothing closes that window, because nothing opens it: **Omni states no capacity until the
-connection is established**, and **Work is pulled, never pushed** makes an assignment with none
-stated a violation. Capacity does not wait on the microphone: whether an agent without agent application audio
-can take calls is the platform's question, answered by the adapter from the agent application's report, not by
-Omni withholding capacity for every platform alike.
-
-Capacity follows **automatically** once the connection is established; the agent does not press
-anything to become available.
-
-| Situation | What Omni sends |
-| --- | --- |
-| Connecting | Nothing. No capacity has been stated, so nothing may be assigned. |
-| Connected and idle | `setCapacity({ count: n })`, with the agent application's report already available to consult. |
-| A task starts or ends | Nothing. The provider counts its own against the ceiling. |
-| The agent's provisioned capacity changes | `setCapacity({ count: n })` |
-| Agent asks for a break | `requestBreak`. Capacity is unchanged and work continues. |
-| Omni commits a break | `commitBreak`. The break stops assignment, not the ceiling. |
-| Agent returns from break | `endBreak` |
-
-**A break is not a capacity of zero, and neither is the reverse.** Capacity says how much of this
-agent this provider may carry; a break says they are not working at all. A provider told
-`count: 0` shows an agent whose capacity is elsewhere, `elsewhere`; a provider told a break shows
-`on-break`. Collapsing the two would leave a provider unable to tell an agent working on another
-provider from an agent who has gone to lunch, and only one of those needs a reason, a decision and
-a return.
-
-### How the agent hears the call
-
-A voice platform can put an agent on a **softphone**, where the call's audio lands in the agent application
-and Omni owns the microphone and the playback, or on a **desk phone**, a handset on the platform's
-switch that the platform rings, where the agent application owns no audio and only shows the call. Which of
-these a platform can do is a fact about the platform, and which one a login is on is a choice the
-agent application makes for that agent -- so the manifest declares and the agent application chooses.
-
-```ts
-// Manifest: what the platform can do
-phones: ["softphone", "deskPhone"]
-// The agent application, at authentication and again at connect: which one this login is on
-{ phone: "softphone" }
-```
-
-A voice manifest lists its `phones` and any other channel lists none (`manifest.phones.required`,
-`manifest.phones.channel`). The agent application's `phone` is required on a voice login, absent on any other,
-and one the manifest listed (`context.phone.required`, `.unexpected`, `.unsupported`). Everything
-about audio then follows the phone rather than the channel: on a softphone the agent application reports its
-audio, the adapter implements `openAudio`, and `task-audio-started` is the word to open it; on a
-desk phone the agent application reports no audio, opens nothing, and `task-audio-started` still marks the
-moment the call is live so the desk shows it, with the sound on the handset. A platform that lists
-`deskPhone` alone never implements `openAudio`; one that lists `softphone` always does.
-
-**The mode comes from the agent application; the status comes from the provider.** The agent application knows which kind
-of station the agent signed in at, because the person chose it, and nothing else can know that.
-The provider knows whether that station can carry a call right now -- whether a handset is
-registered -- which an agent application in a browser cannot see. So the agent application's `phone` selects the branch, and
-the provider's own knowledge of the device decides readiness within it. A provider never overrides
-the agent application's declaration from its device record: treating a desk-phone login as a softphone because
-the handset is momentarily unregistered, and demanding a microphone of it, is the reading this
-sentence exists to refuse. What the provider does when the handset is not registered is what it
-does for any station that cannot take a call -- hold the agent not-ready and say why.
-
-**On a desk-phone login the agent application never calls `openAudio`.** There is no stream to hand over and
-no audio to attach; an agent application that calls it anyway is in error, and an adapter that receives the call
-answers `unavailable` with a non-retryable failure, since waiting changes nothing about a station
-that is a telephone. The harness requires no `openAudio` of such an adapter and never calls it.
-
-**Which handset a desk-phone login rings is the platform's configuration for that agent**, and
-this wire never asks the agent for it: an agent application declares `phone` and nothing more. What a platform
-asks on surfaces of its own is its own decision.
-
-**A declared phone the platform does not permit for this agent is a login that cannot be
-established.** The manifest says what the platform can do; the agent's record, kept by an
-administrator, says what this agent is configured for, and the two can disagree with the agent application's
-declaration -- a softphone declared for an agent whose record says desk phone. Honouring that
-declaration on a switch that allows one registration per endpoint would evict the handset: the
-agent's phone stops ringing and their calls land in a tab, and nobody is told. So the provider
-refuses the login at authentication, with `omni.phone-not-permitted` and a message the agent application shows
--- "this agent is configured for a desk phone" -- and refusing is correct, not an override of the
-agent application. It is a refusal, never a negotiation afterwards and never a quiet substitution, and it is
-never retryable: trying again does not reconfigure the agent, and an agent application validating the answer
-(`validateAuthenticationResult`) refuses a phone refusal marked otherwise
-(`authentication.failure.phone.retryable`). And **a
-provider never makes a declared phone true by changing the platform's configuration**: the record
-is the administrator's, and a login is not a request to reconfigure an agent.
-
-### Opening the audio
-
-`openAudio` hands Omni the remote audio for one task. Every adapter whose manifest lists
-`softphone` implements it, because on a softphone the call's audio lands in Omni:
-
-```ts
-openAudio({ assignmentId, localAudio }): Promise<OpenAudioResult>
-// { status: "opened", session } | { status: "unavailable", failure }
-```
-
-The adapter speaks whatever its platform speaks — SIP over WebSocket, a vendor SDK, plain
-WebRTC — and **none of that appears in this contract**. Registration, signalling, credential
-renewal and reconnect are the adapter's, exactly as its authentication and transport already
-are. Omni owns what belongs to the agent application: the microphone, the output element, mute, and when a
-session ends — owning the microphone meaning capturing it, prompting, retrying and reporting how
-it stands, never deciding for the adapter what a missing one means (see **The agent application reports, the
-adapter decides**).
-
-| Member | Contract |
-| --- | --- |
-| `remoteAudio` | `MediaStream` Omni plays. |
-| `setMuted(muted)` | Mutes the agent's microphone on this session. |
-| `close()` | Releases the session. Omni calls it when the task ends. |
-
-`localAudio` is the agent's microphone as Omni captured it, the same stream the agent application's report
-carries as `audio.input.localAudio`, and absent while that input is `unavailable`. A provider that
-bridges audio without an application-side input may ignore it; one that needs it and finds it absent
-answers `unavailable` with a failure Omni shows the agent.
-
-**When to ask is the provider's word, not Omni's guess.** On a softphone login, Omni opens audio on `task-audio-started`,
-and on a task arriving with `audio: "started"` on a snapshot; it closes on `task-audio-ended` and
-when the task ends. Between those words, nothing Omni's own senses report — a stream that drops, a
-track that ends — moves the task or its audio.
-
-**A task-scoped session does not oblige one call per task.** A platform holding a nailed-up
-leg for a whole shift may return the same session for every task and release the underlying
-path only when the connection closes. A platform placing a call per contact returns a new one
-each time. Omni asks when it needs audio and closes when it is done; how that maps to the
-platform is the adapter's business.
-
-## Task commands
-
-Command names follow the channel's operational vocabulary, and each channel's command is a union
-discriminated by `type` — the same discriminant `executeTeam` and `custom` already use. The
-unions are declared under **Shapes**.
-
-`assignmentId` is not repeated on the command. It travels on the `TaskCommandRequest` around it.
-
-**A toggle carries the state it wants, not a flip.** Inverting whatever is found cannot converge
-with a stale view: a flip against a state the provider has already changed turns something on and
-then off again. A custom `toggle` control therefore carries its own boolean. `hold` and `resume`,
-`pause` and `resume` need no flag, being pairs rather than toggles.
-
-**`complete` sends an outcome only where one was published.** `outcome` is a
-`OutcomeCode.id` from the task's own `outcomes` capability, and `notes` obeys that
-capability's `notes` setting. A task publishing no codes still receives `complete`, with neither.
-
-### Where a command executes
-
-Every command reaches the provider through `execute`, with no branch at the call site, and every
-command asks the provider to **perform** something: `hold`, `conference`, `schedule`, `end-call`,
-Provider-targeted `recording` commands and the rest act on the platform's own call leg, its bridge, or its record of the
-task. Nothing has happened until the provider applies them, and `failed` means nothing happened.
-
-**The provider performs every action; the agent application only offers it.** A control drawn on the agent application is
-an affordance, never the enforcement: the agent application asks, and the provider does or declines. A provider
-answers `failed` for a command whose capability it did not publish, and that is the provider
-honouring its own declaration, not the agent application deciding policy -- an agent application that refuses a command on
-its own reading of a queue's flag has decided something that was never its to decide. What a
-command means on the platform is the provider's to work out: `end-call` disconnects the caller channel, and
-which legs on which bridge that touches is a fact about the switch, never a choice the agent application makes.
-The one thing the agent application performs physically is the microphone, and that is not a command at all.
-
-### The station is the agent application's
-
-The microphone, the speaker, the headset and its buttons are the station's, and the station is the
-agent application's. So mute is not a capability a provider declares, not a control a queue allows or a team
-locks, not a preference the person keeps with the provider, and not a command: nothing about the
-station crosses to the provider except two things -- the station's condition, in the agent application report,
-and the record of when the agent could not be heard, through `recordStep`. An agent application offers Mute on
-every voice task with audio open, under its own local policy, in `in-progress` and `paused`
-alone, and performs it through `CallAudio.setMuted()`. A task carrying
-`capabilities.mute` is refused (`task.capability.unknown`), and so is a `mute` command
-(`command.type`), a `mute` preference (`preference.id`) and a `mute` policy (`team.policy.key`).
-
-**Two mutes, and the agent application states which its Mute performs.** A *stream* mute stops the audio the
-agent application sends: the microphone keeps capturing, the party hears silence, nothing else on the machine
-changes, and every softphone agent application can do it. A *station* mute silences the microphone itself at
-the operating system: every application on the machine goes quiet, the system shows it, and a
-headset that follows the system follows it. Only a native agent application can do it. `Host.mute` says which
-this agent application does -- `stream` or `station` -- stated on a softphone login, where the agent application holds the
-microphone, and absent on a desk phone and off voice (`host.mute.required` / `.unexpected`). A
-browser says `stream`. A native agent application says whichever it does. Nothing on the wire says what kind of
-application the agent application is; a provider reads only what the agent application declared.
-
-**A silenced device says who silenced it.** `audio.input.flowing: false` and
-`audio.output.flowing: false` carry `mutedBy`: `host` when the agent application's own Mute did it -- which is
-only ever true of an agent application whose mute is `station`, since a stream mute leaves the microphone
-flowing -- and `station` when a slider on the headset or the operating system did, which the agent application
-observed and did not do. Without the word, a station-muting agent application's own Mute would read as a fault
-and an adapter would take the agent out of ready in the middle of a call. A browser reads a station
-mute through the capture track's muted state, read-only, and cannot lift it; a native agent application reads
-the endpoint and can clear an operating-system mute. A hardware slider is nobody's to clear.
-
-**The record carries the same word.** A `muted` interaction leg is a period the agent could not be
-heard, and the record exists so that period is not a hole. The agent application reports every such period
-through `recordStep` -- its own Mute, and a station mute it observed during a call -- with
-`mutedBy` saying whose the silence was, and the provider writes the word into the entry
-(`task.history.mutedBy`). The report names no agent because the agent application has exactly one, and
-the provider knows who that is: it attributes the leg to the login's agent in `by`, a fact it
-holds and not an inference, for a station mute as much as for the agent application's own. An unattributed
-`muted` entry is refused (`task.history.muted.by`); a shared handset's unattributed hold
-is a different claim, and stands. A supervisor reading the record then sees "the agent muted for
-forty seconds" and "the agent's headset was muted for forty seconds" as the different things they
-are. See **The agent application records what it performs**.
-
-**Mute has a lifecycle, and none of it is inferred.** A call that starts while the station is
-already muted begins a `muted` leg the moment its audio starts, `mutedBy: "station"`. Audio that
-ends while any leg is open ends the leg at that instant, as every agent application-performed leg ends. And the
-agent application's own Mute starts off on every call, which is every `task-audio-started` -- a connect-back
-opens a second call on the same task with no offer -- so an agent is never muted by the call before.
-
-**Every press on a headset is the agent's own press**, performed the agent application's way, and the lights
-follow the agent application's state. The `personConsent` guarantee is honoured by a hook-switch press exactly
-as by a click. What a call-control headset sends, and what becomes of it:
-
-| Input | Where it comes from | What the agent application does | What crosses to the provider |
-| --- | --- | --- | --- |
-| Mute button | The headset, on the HID Telephony usage page: a Phone Mute report on the press, a Mute LED the agent application writes back | A press of the agent application's Mute, performed the agent application's way; the LED follows the agent application's state, so button, light and control are one state with one owner | The `muted` leg, `mutedBy: "host"` |
-| Hook switch | The headset, HID Telephony | A press of the agent application's Answer or End call, only where the task is in a phase that has one; the off-hook and ring lights follow the task | The existing `answer` and `end-call` commands |
-| Flash, redial, speed dial | Older headsets and desk-phone style devices | Flash is Hold and Resume where the task offers `hold`; redial and speed dial map to nothing on a desk that never redials, and are ignored | Nothing new |
-| Volume up and down | The headset's own amplifier, or the operating system through the consumer-control keys | Nothing: the device and the system handle it | Nothing, except that a speaker at nought is `audio.output.flowing: false` where the agent application can know it |
-| Microphone gain and level | The operating system, the headset's own boost | A level meter, so the agent can see they are heard | Nothing: a level is a flicker, not a state |
-| Hardware or operating-system mute | A slider on the headset, the system's input mute | Observes it, publishes `flowing: false, mutedBy: "station"`, records the leg during a call, and tells the agent which it is where it knows -- headset or system -- and what to do; an agent application whose mute is `station` clears a system mute itself, a browser can only say so | The report and the leg |
-| Device changed, unplugged, permission revoked | The operating system | Re-capture, prompt, report | Already `audio.input` and `audio.output` with `lost`, `denied`, `no-device` |
-
-**What the agent application shows.** Beside Mute, a standing line while the station is muted, saying which and
-what to do, with a button that clears a system mute only on an agent application whose mute is `station`. The
-Mute control does not pretend: while the station is muted it shows the agent cannot be heard and
-that pressing it will not change that, and a press still toggles the agent application's own mute, so the two
-states stay separate and the agent is not unmuted by surprise when the slider moves back. Before a
-call, the same line in the ready state, so an agent does not learn of it from a silent customer;
-whether work is held back is the adapter's decision from the report, as it is for every station
-fact. Where a provider's own platform holds a mute of its own -- a bridge that silences a leg --
-that is a fact about the switch, reported as the provider sees fit, and never the agent application's Mute.
-
-### Which commands need a capability
-
-**Presence is the permission** gates the controls a provider chooses to offer. Four commands are
-not among them, because every task has them; each is authorized by a different field the provider
-declared:
-
-| Command | What makes it available |
-| --- | --- |
-| `answer`, `accept` | Nothing. A task that was offered can be accepted, or offering it meant nothing. |
-| `end-call` | The `endCall` capability: ends my part, the caller continues. |
-| `terminate-call` | The `terminateCall` capability: ends the whole call, every channel on it. |
-| `conference` with `action: "remove"` | The `conference` capability, and somebody else on the call: a remove that would leave the agent alone is `end-call`, and a provider answers it `failed`. |
-| `decline` | The `decline` capability on any channel, **and** Omni local policy permitting it. One word for refusing an offer, whatever the channel. |
-| `dial` | The `preview` phase. A record put in front of an agent is there to be called, so the phase is the gate and there is no capability. It is a dial, with a `dialId` and a `dial-outcome`. |
-| `complete` | A wrap to cut short: any task but a `provider-automatic` one with `wrapAllowance: 0`, under either completion mode (`command.complete.wrapAllowance`). The `outcomes` capability decides whether a code travels with the command, never whether the command exists — a task Omni cannot complete never ends. What travels is what the capability published: a code from its list where it has one (`command.complete.outcome.unknown`), a code at all where it requires one (`.outcome.required`), notes as it said (`.notes.required`, `.notes.unexpected`), and neither where the task declares no outcomes (`.outcome.unexpected`). |
-| `connect-back` | The `connectBack` capability **and** the `completing` phase. It exists to reach the party again after the call, so it has no meaning while the call is up. |
-| `schedule` | The `schedule` capability, on any channel, in `in-progress`, `paused` or `completing`: a follow-up is promised on the call and written up in wrap alike. The manifest declares `calendar` for it to land on. |
-| `lead-assist` with `action: "request"` or `"cancel"` | The `leadAssist` capability. `cancel` needs a request standing -- `Task.leadAssist` with `stage: "requested"`. |
-| `conference` with `action: "add"` | Its capability, and a `destinationId` the directory offered: the id Omni sends is the id the provider published (`command.destination.unknown`). |
-| `custom` | A control the task published under `capabilities.custom`, by its `id` (`command.capability.custom`), carrying a non-empty string for each `required` prompt field and strings for any optional fields supplied (`command.custom.prompt`). A toggle carries its target `on` boolean (`command.custom.on`). |
-| Everything else | Its own named capability. |
-
-**A control on the contact belongs to the interaction phases**, `in-progress` and `paused`:
-`hold`, `resume` and `pause`, `end-call` and `terminate-call`, every `conference` action, and
-every `lead-assist` action; `schedule` alone reaches into `completing`. These controls act within this agent's current interaction.
-In `completing`, that interaction has ended and its wrap work remains. The caller may still be in
-an IVR, queue or another agent's interaction, and other channels may remain connected. Completion
-of this interaction does not establish that the caller or bridge ended. The capability stays
-declared while the task remains open; the phase prevents this task from controlling an interaction
-it no longer owns. Omni shows these controls only in the two interaction phases, and
-`validateTaskCommand` refuses them outside those phases (`command.phase.interaction`).
-The commands with a phase of their own -- `answer`, `accept` and `decline` in `pending`,
-`dial` in `preview`, `connect-back` in `completing`, `complete` in any -- are not among them.
-
-`validateTaskCommand(command, task)` holds a command to this table at runtime, both ways: the
-capability it needs, the phase it belongs to, and the state that has to stand. The task it wants
-is the one the provider published, not an agent application's own mapping of it: an agent application that keeps only its
-mapped shape has nothing honest to pass, and then checks shape alone, which is still worth doing
--- it names a command the wire never had -- but is not the table. Keeping the published task
-beside the mapped one is what the full check costs an agent application; an adapter has it for free. The
-validator holds a command only to a task that stands: a task handed in that is not one the wire
-published is named (`command.task`) rather than checked against.
-
-Declining a pending offer ends it without accepting or completing it. The provider confirms the
-end with `task-ended` and a `cancelled` outcome, `by: "agent"`.
-
-### `execute(request)`
-
-Applies a `TaskCommandRequest` to one provider-local task.
-
-- Omni serializes commands per task and sends the next only after the previous settled or was
-  given up as unknown; it stops sending when `task-ended` arrives.
-- `applied` confirms the side effect completed. `failed` confirms it did **not**, with a typed
-  `ProtocolFailure`; a provider that will not and one that cannot report the same shape, and `code`
-  says which.
-- A command sent while `transport-status` is not `active` answers `failed` with `omni.unavailable`.
-  Neither Omni nor the adapter queues it.
-- **A command that asks for a state answers `applied` when that state holds, whoever brought it
-  about; a command that acts answers `failed` when it cannot act.** Declining a lead request
-  already gone is `applied`; joining one already gone is `failed`, since nobody joined. A lead
-  deciding a member's break that another lead has already decided is `applied` when the decisions
-  agree and `failed`, saying so in `message`, when they differ. `commitBreak()` on a break already
-  in effect is `committed` for the same reason.
-- **A result is untrusted for the same reason a snapshot is.** It comes from an adapter that may be
-  compiled against another version, and Omni shows the agent what it says. Omni validates it at
-  the boundary with `validateResult(result, "execute")` — a status the method does not answer, a
-  `failed` without its failure, a success carrying one, or an `omni.` code this contract lacks is
-  refused, and the command is treated as unsettled.
-- **A settled result is a fact; an unsettled promise is not.** Transport uncertainty may reject the
-  promise with no result at all, and that means *unknown*, not *failed*, and a snapshot follows —
-  see **An unsettled result is unknown**. `failed` must never be returned for something the
-  provider is unsure of, because Omni will show the agent it did not happen.
-
-### `ProtocolFailure`
-
-| Field | Contract |
-| --- | --- |
-| `code` | Required stable machine-readable value. See the reserved codes below. |
-| `message` | Required, and safe for logs or agent display. |
-| `retryable` | Whether repeating the action can succeed at all. |
-| `retryAfterMs` | Optional minimum suggested delay before a retry. A suggestion, not a guarantee. |
-
-The `omni.` prefix is **reserved**. Adapters must not invent codes under it; every other value is
-provider-private and Omni treats it as opaque. Using a reserved code where it applies lets Omni
-react rather than only display the message:
-
-| Code | Meaning |
-| --- | --- |
-| `omni.not-authenticated` | The provider session is no longer usable. The adapter has published `expired` at or before this answer — the state is what Omni surfaces reauthentication from; the code says why this action failed, and is never the only signal. |
-| `omni.capability-not-enabled` | The action targets a capability this task, manifest, or login did not declare — including a lead command from a login whose `capabilities` no longer carry it. |
-| `omni.assignment-not-found` | The assignment named is not one the provider holds, typically after the task already ended. |
-| `omni.phone-not-permitted` | The agent application declared a `phone` the platform does not permit for this agent -- a softphone for an agent configured for a desk phone, or the reverse. The login is refused at authentication, and the provider never reconfigures the agent to make the declaration true. See **How the agent hears the call**. |
-| `omni.destination-not-permitted` | The dialled number, or the `destinationId` named, is not one the provider offers this agent. |
-| `omni.rate-limited` | The action was throttled. Pair with `retryAfterMs`. |
-| `omni.unavailable` | The provider is temporarily unable to serve the action, including any command sent while `transport-status` is not `active`. |
-| `omni.break-already-committed` | Cancellation lost the commit/cancel race; Omni must finish commit recovery. |
-| `omni.recording-unsettled` | A recording command the provider could not settle either way: a settled `failed`, never a promise left unresolved. See **Independent task recording**. |
-| `omni.break-forced-by-provider` | A lead asked to lift a break the platform imposed; the platform lifts its own. See **Forced breaks**. |
-
-They are published as `OMNI_FAILURE_CODES`.
-
 ## Event delivery
 
 ### `ProviderEventEnvelope`
@@ -5075,7 +2423,7 @@ used for final records, and agent application-supplied timestamps are advisory.
 of time-check support and the optional agent application estimate; neither changes who owns the final record.
 Omission makes no promise that agent application timestamps will be trusted. No agent application-authoritative default
 is inferred. Successful `recordStep` responses identify the provider-selected history instant;
-see **The agent application records what it performs** for correlation and retained bindings.
+see **The agent application records what it performs** in `guide/agent.md` for correlation and retained bindings.
 
 A provider need not trust or adopt any agent application-supplied timestamp. It may timestamp an incoming
 message using its own clock at receipt and use that for its own processing/accounting. The reason
@@ -5315,7 +2663,7 @@ Every outcome ends the task for this agent. On `task-ended`, Omni:
 - selects another task or returns to the idle workspace.
 
 A `taken-over` outcome arrives at the member's own completion, after the wrap that follows a
-take-over as it follows an `end-call` -- see **Lead assist**.
+take-over as it follows an `end-call` -- see **Lead assist** in `guide/lead.md`.
 
 A successful `complete` command does not clear the task. Omni waits for `task-ended`,
 and not for ever: `applied` to a `complete` says the
@@ -5360,7 +2708,7 @@ provider does not batch. `exerciseAdapter` treats a diagnostic delivered during
 violation (`diagnostic.raised`): a conformance run against a platform that is breaking its rules
 fails loudly rather than passing with a note. A task published under `capabilitySource:
 "not-yet-read"` is the same kind of fact, stated on the task instead, and fails a run the same way
-(`capabilitySource.notYetRead`); see **Task capabilities**.
+(`capabilitySource.notYetRead`); see **Task capabilities** in `guide/agent.md`.
 
 | Field | Contract |
 | --- | --- |
@@ -5396,7 +2744,7 @@ One member, whole, as they now stand: their availability, their tasks, their lis
 shift, their request. It replaces the member of that `id` on the lead's list, or adds them where
 the list did not carry them, so applying it twice changes nothing. It comes only after the whole
 team has (`stream.team.baseline`), and it is what every publication of a member's task to the
-member publishes to the lead, as **Team leads** sets out: never fewer.
+member publishes to the lead, as **Team leads** in `guide/lead.md` sets out: never fewer.
 
 ### `team-member-removed`
 
@@ -5419,6 +2767,14 @@ the `contacts` idle capability.
 Replaces this provider's complete scheduled-activity contribution. It is emitted only when the manifest
 declares the `calendar` idle capability.
 
+### `phone-updated`
+
+The phone as the platform now sees it, whole, replacing `Snapshot.phone`: a registration lost or
+back, do-not-disturb pressed or cleared, the handset lifted with no call or replaced, the desk
+phone's own mute. Emitted only by a provider whose manifest declares `phoneStatus`
+(`event.phone.capability`). The lead's member carries the same `PhoneState`, republished with the
+member. See **The phone's own view** in `guide/phone.md`.
+
 ### `shift-updated`
 
 The agent's own day, whole, replacing `Snapshot.shift`: emitted whenever a total moves -- a task
@@ -5674,7 +3030,7 @@ cannot be established from TypeScript structure alone.
 | `assertBreakFollowsItsRequests(envelopes, snapshot?)` | A break follows its requests: a commit's states only after a grant, never backwards, and a forced break arriving in effect with `forced`. The harness applies the same rules after the connect snapshot. |
 | `assertAudioFollowsTheTask(envelopes, snapshot?)` | The audio follows the task and never decides it: every task is introduced once, `task-audio-started` and `task-audio-ended` alternate on work that has begun, audio ends only where it arrived, and what follows the audio ending is `completing` or `task-ended`. The harness applies the same rules to every event after the connect snapshot (`stream.*`). A sequence with no audio satisfies it by never testing it — pair it with the assertion that the audio end is present. |
 | `assertBreakAttemptProviders(candidates, asked)` | A break attempt asks every usable provider holding capacity, `refreshing` included, and nothing of a provider whose login is `expired`. |
-| `assertForcedBreakStopsTheRest(forcedOn, candidates, stopped)` | A forced break on one provider stops the agent everywhere else: capacity zero stated on every other usable provider holding capacity, nothing on the forcing one, nothing on a dead login. See **Forced breaks**. |
+| `assertForcedBreakStopsTheRest(forcedOn, candidates, stopped)` | A forced break on one provider stops the agent everywhere else: capacity zero stated on every other usable provider holding capacity, nothing on the forcing one, nothing on a dead login. See **Forced breaks** in `guide/breaks.md`. |
 | `assertBreakBeginsAfterTask(steps)` | A break asked for on a task is committed as `starting-after-task` while work remains and reaches `on-break` only once nothing is outstanding — never beside a task, never later than the step that has none. |
 | `assertDeniedAndRetriedBreak(states)` | A denial transitions directly to `not-requested`; a later request can still be granted. |
 | `assertBrowserSessionIsolation(left, right, expected)` | Browser reuse follows only the declared isolation scheme. |
@@ -5693,151 +3049,3 @@ belongs in this contract is the boundary. A provider says what a control **is**
 capabilities and what its work is **called** through `phaseLabels` and `taskTypePresentation`; how
 any of it is drawn is Omni's. A task cannot select a design language, inject a component, or
 override the agent's theme and font preferences.
-
-## Independent task recording
-
-Recording is voice-only. A task can arrive already recording, including while pending, and offer
-no recording controls. The provider publishes only its own current state on
-the provider field of the task’s `recording` state. The agent application publishes its own full scoped view in `HostReport.recordings`.
-A provider task update cannot replace agent application state. Neither a capability nor an accepted command
-establishes recording. Missing state, lost recorder observation, transport loss and expired
-observation mean unknown; they never mean stopped. Paused means a recording remains open without
-capturing. Task hold, task pause and recording pause are independent.
-
-The per-task policy is `Task.capabilities.recording`, with independently optional provider and agent application
-action sets. The outer capability may be locked. Absence grants no permission, and a state may
-exist without any permission. A provider may offer only stop for a recording started automatically,
-or withdraw a control on a later task update. There is no global recording mode and no automatic
-start from a capability declaration. Agent application support is declared on `ConnectContext.host.recording`,
-not the provider-owned manifest. The task names one of the storage places the agent application provisioned, by `storageId`;
-an unknown storage place or an unsupported action is refused visibly, never redirected to provider
-recording or a default upload location. Initial agent application support requires voice softphone audio and
-capture of both local and remote audio; an agent application unable to capture either must refuse start/resume.
-This package declares that contract; it supplies no recorder, audio mixing, storage or upload.
-
-| Action | Required current recording state | Confirmed outcome |
-| --- | --- | --- |
-| start | inactive | active with a new recording identity |
-| pause | active | paused, preserving recording identity and captured audio |
-| resume | paused | active with the same recording identity |
-| stop | active or paused | inactive; finish and retain captured audio |
-| cancel | active or paused | inactive; abandon and discard captured audio |
-
-Stop finishes the recording and retains captured audio. Cancel abandons the recording and discards
-its captured audio; the task policy offers it with `cancel: true`. There is no configurable cancel
-effect. A recorder that cannot confirm completion must not offer Cancel; it can offer Stop instead.
-Cancel never means cancelling an in-flight start request or deleting arbitrary past recordings.
-Stop can be applied only after finalization/retention succeeds; Cancel only after both cessation
-and completion of this recording's audio succeed under the recorder's storage contract.
-Partial success -- capture stopped but the storage outcome unknown, a start the recorder cannot
-vouch for either way -- is a settled `failed`, under the code `omni.recording-unsettled`: the
-command did not do what it promised, and the state the provider publishes with it is whatever
-capture state is actually known. It is never `applied`, and never an unsettled promise the agent
-application would be left to resync, since the provider knows exactly what it could not settle.
-There is no request identity on a recording command: the outcome is the state, and what the
-agent sees is the state. Retention is not a promise of sample-perfect audio.
-
-Provider commands go exclusively to `Connection.execute`; agent application commands go exclusively to
-`HostRecording.execute`. Both include the assignment and observation identities; all
-non-start commands identify the particular recording. IDs are opaque and scoped by provider login,
-task and recorder owner. They are never inferred from filenames or current agent identity. A
-recording ID survives pause/resume and reassignment only where the same recorder confirms continuity;
-commands always name the current assignment. A later start gets a different ID. Reconnect does not
-create a new recording or fresh evidence. After lost continuity, use unknown until reconciled.
-There is no automatic restart, hand-over to another recorder, or stop on task hold/disconnect.
-Task removal does not prove recording stopped: outstanding agent application recorders remain tracked by the
-agent application until its executor reconciles/finishes them, with visible unresolved cleanup failures.
-
-Only start/resume require an in-progress or paused task with started audio. Pause/stop/cancel may
-also finish an independently observed recorder while the task is completing. A pending task may
-show active recording, but agent controls wait until interaction begins. The two recording paths may
-both be active. A command to either path has no implied effect on the other.
-
-Each confirmed observation has a fresh opaque observation identity, a canonical UTC millisecond
-observation instant and an exclusive expiry. These times describe current evidence, never historical
-capture boundaries. A trusted observer-domain current time must satisfy observedAt <= now < validUntil.
-Use `effectiveRecordingState` with that explicitly trusted time; an unavailable clock yields unknown.
-Receipt, replay and task publication never extend freshness. Clock discontinuity invalidates evidence;
-consumers using the explicit recording-expiry clock-estimation exception must invalidate that
-estimate and use monotonic aging so clock rollback cannot
-revive expired evidence. The executor compares observation identity and recording identity against
-its latest state atomically before I/O. An intervening observation or assignment change refuses the
-stale command; it never acts on a replacement recorder. Providers lacking trustworthy current-state
-identity or observation time publish unknown and offer no issuable controls.
-
-Use `validateTask` and `validateTaskCommand` for published shape and static permissions.
-Immediately before dispatch, additionally use `validateRecordingRequest` against the full current
-task and explicit observer-domain time. For agent application commands also supply the current agent application declaration,
-full agent application report and softphone context. The same checks must run at the executing boundary;
-client validation alone is not authorization. The executor serializes operations on each recorder
-and compares `observationId` and `recordingId` against its latest evidence before acting: a
-command against superseded evidence is refused, and nothing is retried on the executor's own
-account.
-
-Keep command progress in agent application UI separately from authoritative state. Applied means the requested
-recording transition and any retain/discard effect actually completed; publish the confirming task or agent application report before
-resolving applied. Failed means confirmed no effect. Rejected promise means outcome unknown:
-show the failure, reconcile that path and do not automatically retry or pretend inactive. Authoritative
-updates remain full current task/agent application views, not replayed provider events. These current-state fields
-create no interaction-history entries and infer no actors, durations or historical capture boundaries.
-
-Migration is explicit: replace the old true recording capability with per-path action policies,
-replace untargeted commands with scoped commands, and retain protocol version 1. During pre-release
-development, hosts and adapters must align their recording contracts; negotiation does not detect
-differences between package revisions that share that protocol number. No legacy-shape fallback is provided.
-This change does not publish a package or enable recording in any existing agent application/provider by itself.
-
-`validateRecordingOutcome` checks confirming observations against recording-specific applied/failed
-semantics, including pause/resume identity and rejection of a dialling result. It cannot prove audio
-retention/completion or source truth from a status flag; those remain executor obligations.
-
-The storage place named on the task is bound when start actually creates a recording. Existing recordings
-keep that binding through pause/resume/stop/cancel; a later policy cannot redirect their stored audio.
-The executor rejects a mismatched storage place rather than moving or discarding another binding.
-Action permission does not authorize unattended invocation: agent application controls require the agent's explicit
-act, and provider authorization remains enforced at its authenticated command boundary.
-
-
-Recording dispatch must receive the same known task-validation context as the published task.
-Pass organisation levels and other known restrictions through the optional fourth argument of
-`validateTaskCommand`, and through `taskContext` in `validateRecordingRequest`. This keeps a valid
-custom organisation lock from being rejected against the default ladder, and prevents known
-capability restrictions from disappearing at dispatch. The standalone `validateRecordingCommandState`
-requires an affirmative permission; false, malformed permission declarations and unknown actions grant nothing.
-
-
-### Agent application recording announcements to the caller
-
-`HostRecording.announcesToCaller`, when true, is a guarantee that the agent application delivers audible recording
-status messages to the remote party over the call's outgoing audio. It belongs inside the optional
-agent application recording capability: without that capability there is no such guarantee. Omission makes no
-promise; false is invalid. It does not belong in the provider manifest, the task's recording policy
-or the general `HostGuarantees` object. A provider can inspect this agent application guarantee when deciding
-whether to permit agent application recording on a task.
-
-The guarantee applies only to agent application-owned recordings. Providers implement announcements for their
-own recordings at their end; provider state updates must not cause the agent application to announce those
-recordings. Both recorders can operate independently on the same call.
-
-On a confirmed agent application start, the remote party hears that recording started. On a confirmed stop or
-cancel, they hear that recording stopped. If pause/resume is supported, say paused/resumed so a
-pause is not presented as a finished recording. Announcements follow actual capture transitions,
-not button clicks, accepted requests or task-policy changes. When attaching to an already-active
-agent application recording, announce that recording is active, without inventing its original start time.
-Repeated observations of the same state do not repeat announcements. Unknown or expired evidence
-must never produce a stopped announcement.
-
-A local sound, UI indicator, screen-reader message to the agent, or sound leaking through the
-microphone does not fulfil this guarantee. The agent application must deliver the message directly in the audio
-sent to the remote party, even when the agent microphone is muted. It may also notify the agent.
-Only declare the guarantee when the agent application can provide that outgoing audio path. An announcement
-that cannot be delivered, including after the remote party has disconnected, is a visible failure;
-never claim delivery or replay the notice into a different call.
-
-For a command under this guarantee, applied requires both the recording action and its announcement
-to succeed. If capture changes but announcement delivery fails, publish the actual recording state,
-report the announcement failure visibly and answer `failed` under `omni.recording-unsettled`. Do not claim no
-effect, automatically repeat the recording action or silently switch to an agent-only notice.
-
-`validateHostRecording` checks the declaration, including its true-or-absent guarantee. Actual audio
-delivery remains the agent application implementation's responsibility and must be exercised in its own tests.