@xema/omni-protocol 0.1.66 → 0.1.68

package/guide.md

@@ -97,6 +97,7 @@ the semantic name in every contract field rather than repeating the primitive ty
 type IsoTimestamp = string;
 type UserId = string;
 type TaskId = string;
+type AllocationId = string;
 type DialId = string;
 type DurationSeconds = number;
 ```
@@ -314,7 +315,7 @@ type LoginStore = {
 type ConnectContext = {
   protocolVersion: number;
   loginId: string;
-  autoAcceptTasks?: boolean;
+  autoAcceptTasks: boolean;
   timeZone: TimeZone;
   store: LoginStore;
   phone?: Phone;
@@ -396,7 +397,7 @@ type SetPreferenceRequest =
   | { id: PreferenceId; enabled: boolean }
   | { id: PreferenceId; inherit: true };
 
-type HandlingReport = { taskId: TaskId; at: IsoTimestamp } & (
+type HandlingReport = { taskId: TaskId; allocationId: AllocationId; at: IsoTimestamp } & (
   | { step: "muted"; mutedBy: MutedBy }
   | { step: Exclude<HandlingStep, "muted">; mutedBy?: never }
 ) & (
@@ -552,6 +553,7 @@ type PersonalBrowser = Browser;
 type BrowserSessionKeyInput = {
   providerId: string;
   taskId: TaskId;
+  allocationId: AllocationId;
   taskType: string;
   browser: TaskBrowser;
 };
@@ -621,7 +623,8 @@ type OnCallRole = "party" | "agent" | "consulted" | "conferenced";
 type OnCallStage = "ringing" | "joined";
 
 type OnCall = { since: IsoTimestamp; held?: true } & (
-  | { role: "party" }
+  | { role: "party"; dialId?: never; stage?: never }
+  | { role: "party"; stage: OnCallStage; dialId?: DialId }
   | { role: "agent"; userId: UserId }
   | { role: "consulted" | "conferenced"; destinationId: string; stage: OnCallStage; dialId?: DialId; label?: string }
 );
@@ -642,6 +645,7 @@ type TaskAssisting = {
 type TaskMonitoring = {
   memberId: UserId;
   taskId: TaskId;
+  allocationId: AllocationId;
   mode: MonitorMode;
   since: IsoTimestamp;
 };
@@ -666,6 +670,7 @@ type CapabilitySource = "queue" | "ungoverned" | "undetermined";
 
 type Task<C extends Channel = Channel> = {
   id: TaskId;
+  allocationId: AllocationId;
   title: string;
   channel: C;
   taskType: string;
@@ -771,6 +776,7 @@ type TaskCommand<C extends Channel = Channel> =
 
 type TaskCommandRequest<C extends Channel = Channel> = {
   taskId: TaskId;
+  allocationId: AllocationId;
   command: TaskCommand<C>;
 };
 
@@ -923,6 +929,7 @@ type LeadRequest = {
   id: string;
   memberId: UserId;
   taskId: TaskId;
+  allocationId: AllocationId;
   note?: string;
   since: IsoTimestamp;
 };
@@ -1002,6 +1009,7 @@ type OpenMediaResult =
 
 type OpenMediaRequest = {
   taskId: TaskId;
+  allocationId: AllocationId;
   localAudio?: MediaStream;
 };
 ```
@@ -1032,13 +1040,13 @@ type ProviderEvent =
       allocationExpiresAt?: IsoTimestamp;
     }
   | { type: "task-updated"; task: Task }
-  | { type: "task-media-started"; taskId: TaskId }
-  | { type: "task-media-ended"; taskId: TaskId }
-  | { type: "task-ended"; taskId: TaskId; outcome: TaskOutcome }
-  | { type: "dial-outcome"; dialId: DialId; outcome: DialOutcome; taskId?: TaskId; destinationId?: string; reason?: string }
+  | { type: "task-media-started"; taskId: TaskId; allocationId: AllocationId }
+  | { type: "task-media-ended"; taskId: TaskId; allocationId: AllocationId }
+  | { type: "task-ended"; taskId: TaskId; allocationId: AllocationId; outcome: TaskOutcome }
+  | { type: "dial-outcome"; dialId: DialId; outcome: DialOutcome; taskId?: TaskId; allocationId?: AllocationId; destinationId?: string; reason?: string }
   | { type: "announcement"; text: string; html?: string; announcedAt: IsoTimestamp; expiresAt?: IsoTimestamp }
   | { type: "queue-summary"; summary: QueueSummary }
-  | { type: "diagnostic"; expected: string; observed: string; taskId?: TaskId }
+  | { type: "diagnostic"; expected: string; observed: string; taskId?: TaskId; allocationId?: AllocationId }
   | { type: "team-updated"; team: TeamRoster }
   | { type: "contacts-updated"; contacts: Contact[] }
   | { type: "calendar-updated"; scheduledActivities: ScheduledActivity[] };
@@ -1943,7 +1951,7 @@ Creates one live provider connection for the signed-in agent.
 | --- | --- |
 | `protocolVersion` | Version negotiated before authentication. Fixed for this login. |
 | `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 provisioning policy relayed to the provider at login. Treated as `true` when omitted. 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()`. |
+| `autoAcceptTasks` | Agent provisioning policy relayed to the provider at login, stated by the host 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 host states what its Mute does, and a desk-phone or conversation login's host cannot, so the omission is a compile error rather than a live seat's discovery. See **The station is the host's**. |
 | `store` | The login's operational store, kept by the host for the life of the login, across a reload of the host, and cleared at sign-out: where an adapter that composes a record keeps what its platform cannot hold for it, such as the handling legs a host reported. Three functions, by key. Never for anything sensitive, which is `AuthenticationContext.secrets`, a store a host may clear aggressively. **A task's keys carry the task id and go with the task**: a key written about a task names the task's id in the key, and is deleted before the task's end is published, because a platform retires a task id minutes after closing it and a requeue takes seconds, so a key that outlives its task is inherited by the next offer of the same id -- a record with legs the host never reported against it. A login-scoped key carries no task 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 host's, not the adapter's: a host 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.task-not-found` and writes nothing -- the host ends its own open legs at the task's end, so such a report is the host's error to see, and a host 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. |
@@ -2144,12 +2152,11 @@ provider's requirement, stated on a wire where Omni was willing to accept for th
 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.
 
-**An absent value means `true`**, as `readyOnLogin` does, because an agent who has signed in and
-gone ready is telling the deployment they are working. Requiring a press before every contact is
-the exception a provisioning file asks for, not the state it falls into when a flag is missing.
-
-Nothing is given away by that default. `acceptance` is the provider's own control and outranks
-it: `consent` puts the decision back in the agent's hands for any task where it
+**The value is stated, never assumed.** `autoAcceptTasks` is required of every connection: a
+host 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 host was configured with.
 
 An automatically accepted task still arrives through `task-offered`.
@@ -2221,7 +2228,8 @@ time. Runtime conformance checks also require the task channel to match its prov
 
 | Field | Contract |
 | --- | --- |
-| `id` | Required `TaskId`, unique within the provider. Omni scopes it with the provider ID. |
+| `id` | Required `TaskId`, the platform's own identity for the task. Unique among the tasks open at once; a platform retires an id minutes after closing it, so the same id comes back for another customer. Omni scopes it with the provider ID. |
+| `allocationId` | Required `AllocationId`: this life of the task, minted once per offer and never reused for the life of the login, whatever the id does. Every event, command and report that names a task names its allocation too, so a late dial outcome or a late handling report for the first customer never lands on the next under the same id. The stream refuses an offer reusing one (`stream.taskOffered.allocation`), an update restating another life of the id (`stream.taskUpdated.allocation`), and a media or ending event naming a life that has ended or that nobody has seen (`stream.allocation.ended`, `.unknown`); a `dial-outcome` may name an ended life, since a dial placed late routinely outlives its call, and the host routes it there. See **A task's life on the wire**. |
 | `title` | Agent-facing task title. |
 | `channel` | Channel handling 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`. |
@@ -2230,7 +2238,7 @@ time. Runtime conformance checks also require the task channel to match its prov
 | `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. |
-| `media` | 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-media-started`**. |
+| `media` | 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-media-started`**. Media names a task whose work has begun: on a `pending`, `confirmed` or `preview` task it is refused (`task.media.beforeWork`), on a snapshot as on the event, since a host opens the microphone on it. |
 | `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**. |
 | `previewEndsAt` | Voice only, in `preview`: when the system stops waiting for the agent to press Call. Absent, the agent has as long as they need. Always with `atDeadline`. See **Preview: the agent presses Call**. |
 | `atDeadline` | Voice only, in `preview`, with `previewEndsAt`: what the system does at the deadline -- `calls` places the call itself, `expires` takes the record back and the task ends `expired`. |
@@ -2239,7 +2247,7 @@ time. Runtime conformance checks also require the task channel to match its prov
 | `wrapAllowance` | Fixed time allowed to complete the task after primary handling ends. For real-time media, it begins after `task-media-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. |
 | `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. |
 | `handlingHistory` | The call record: `steps` — the ordered handling history of this open task, one entry per occurrence, oldest first — and what they add up to before this agent, `handleSeconds`, `holdSeconds`, `queueSeconds`, `transfers`, each present when the provider knows it. Live task data restated with the task, not a permanent archive. See **How a task has been handled**. |
-| `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, `agent` a person by user id, `consulted` and `conferenced` somebody a dial is bringing in, listed from the moment the dial is placed -- with the `destinationId` dialled, the `dialId` where a host placed it, the `stage` reached (`ringing` until answered, `joined` after), and `held: true` on anyone joined and parked. A `consulted` entry is what makes `transfer` `complete` and `cancel` issuable. `label` names a destination -- a person, a queue -- not a phrase; the host supplies the verb. Present when the provider knows the room, absent when it does not. See **Every dial has an outcome**. |
+| `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 host'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, `consulted` and `conferenced` somebody a dial is bringing in, listed from the moment the dial is placed -- with the `destinationId` dialled, the `dialId` where a host placed it, the `stage` reached (`ringing` until answered, `joined` after), and `held: true` on anyone joined and parked. A `consulted` entry is what makes `transfer` `complete` and `cancel` issuable. `label` names a destination -- a person, a queue -- not a phrase; the host 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**. |
 | `assisting` | Voice only, on the lead's own task for a call they joined: which member asked, with their note. Its presence is what makes `lead-assist` `take-over` and `leave` issuable. See **Lead assist**. |
 | `monitoring` | Voice only, on the lead's own task while they listen to a member's call: whose call, which call, and the `mode` they are heard in, restated on every change. Never on the member's task, and never together with `assisting`. See **Monitoring a call**. |
@@ -2287,6 +2295,24 @@ The canonical task transitions are:
 | `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 id is the platform's, and platforms reuse them: a closed id is retired minutes later, a
+requeue takes seconds, and on one platform a call was offered twice, thirteen seconds apart, under
+one id, through a close and a re-offer. Everything that names a task after the fact -- a dial
+outcome, a media event, an ending, a handling report, a command -- would land on whichever life of
+the id is open when it arrives. So every offer mints an `allocationId`, unique for the life of the
+login, and every one of those names it beside the `taskId`. The host keys its state on the pair, a
+late event finds the life it belongs to or is refused, and a task-scoped browser session
+(`PROVIDER_NAME__TASK_ID__TAB_NAME`) lives one allocation, never the next customer's cookies under
+a reused id. A dial the host placed was already safe, since its outcome is placed by the host's own
+`dialId`; where the allocation earns its place is everything the host does not mint --
+`task-media-started`, `task-media-ended`, `task-ended`, a `recordStep` naming a task -- any of which
+would otherwise find the new task under the old id and act on it. The allocation is part of the task
+the adapter keeps, not a field held in memory beside it: a rebuilt adapter comes back with the same
+allocation on the same task, or every late event it was minted to catch mismatches
+(`drive.reload.allocation`).
+
 Allocation, 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
@@ -2422,6 +2448,16 @@ whose outcome says so and a call whose media ended: the task returns to `complet
 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 again.** From the moment the connect-back is placed the
+`party` entry carries `stage: "ringing"` and the host's `dialId`, exactly as a consulted or
+conferenced entry does from its dial, and `joined` on the answered `dial-outcome` and never before
+it (`stream.taskUpdated.stage`); a host 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
+host `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
@@ -2500,7 +2536,10 @@ entries, one per join. Order is enforced: an entry earlier than the one before i
 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.
+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 host has already read, by step and instant, and
@@ -2590,11 +2629,12 @@ writes it into its record as it writes every other leg:
 ```ts
 declare const connection: Connection<"voice">;
 declare const taskId: TaskId;
+declare const allocationId: AllocationId;
 declare const at: IsoTimestamp;
 
-void connection.recordStep?.({ taskId, step: "muted", at, mutedBy: "host" });                          // the moment the agent mutes
-void connection.recordStep?.({ taskId, step: "muted", at, mutedBy: "host", seconds: 15 });             // still running, if the host chooses to say
-void connection.recordStep?.({ taskId, step: "muted", at, mutedBy: "host", seconds: 42, ended: true }); // the moment they unmute
+void connection.recordStep?.({ taskId, allocationId, step: "muted", at, mutedBy: "host" });                          // the moment the agent mutes
+void connection.recordStep?.({ taskId, allocationId, step: "muted", at, mutedBy: "host", seconds: 15 });             // still running, if the host chooses to say
+void connection.recordStep?.({ taskId, allocationId, step: "muted", at, mutedBy: "host", seconds: 42, ended: true }); // the moment they unmute
 ```
 
 The entry is keyed by `step` and `at`, so every report about one leg names the same instant. The
@@ -2711,7 +2751,7 @@ The supported `BrowserIsolationScheme` values, declared under **Shapes**, key as
 
 | Enum member | Example session key |
 | --- | --- |
-| `PROVIDER_NAME__TASK_ID__TAB_NAME` | `mailflow.EMAIL-829102.CRM` |
+| `PROVIDER_NAME__TASK_ID__TAB_NAME` | `mailflow.EMAIL-829102%2Ea1.CRM` -- the task's allocation, so one life of the id, 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` |
@@ -2795,7 +2835,17 @@ Terms once read stay read: a re-read that fails mid-task is not a new fact about
 last statement stands and the failure is a `diagnostic`, and a task that was published under
 `queue` or `ungoverned` never returns to `undetermined`, 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.handlingHistory`, `stream.snapshot.handlingHistory`).
+entry the same two ways (`stream.taskUpdated.handlingHistory`, `stream.snapshot.handlingHistory`);
+and a task does not go backwards (`stream.taskUpdated.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 on the call carrying a `stage`. 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-media-started` on a `completing` task
+is refused as it is on a pending one (`stream.taskMediaStarted.beforeWork`), since a connect-back
+returns the task to `in-progress` before any media.
 
 What the agent is told differs by source, and only one source tells them anything. Under `queue`
 and `ungoverned` the agent sees controls and nothing about where they came from: both are facts,
@@ -2850,8 +2900,10 @@ See **Which commands need a capability**.
 
 ### Publishing codes and destinations
 
-Four capabilities accept an object instead of `true` when the provider wants Omni to render real
-choices. `true` remains valid and means "offer the control with nothing published".
+Four capabilities accept an object when the provider wants Omni to render real choices. For
+`dispositions` alone, `true` remains valid and means "offer the control with nothing published";
+the three directory controls -- `coldTransfer`, `warmTransfer`, `conference` -- carry their
+directory or are refused, since once nothing is typed the directory is the control.
 
 #### `dispositions`
 
@@ -3060,15 +3112,16 @@ across the installation, and it travels four ways so no leg is a lookup:
 ```ts
 declare const connection: Connection<"voice">;
 declare const taskId: TaskId;
+declare const allocationId: AllocationId;
 
 // 1. Out, minted by the host.
-const result = await connection.execute({ taskId, command: { type: "conference", action: "add", dialId: "dial-7f2", destinationId: "tier2" } });
+const result = await connection.execute({ taskId, allocationId, command: { type: "conference", action: "add", dialId: "dial-7f2", destinationId: "tier2" } });
 
 // 2. Back on the result, restated, so the host 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", taskId, destinationId: "tier2", outcome: "no-answer", reason: "No route to destination" };
+const outcome: ProviderEvent<"voice"> = { type: "dial-outcome", dialId: "dial-7f2", taskId, allocationId, destinationId: "tier2", outcome: "no-answer", reason: "No route to destination" };
 
 // 4. In the record, so a dial made before a transfer is placeable by whoever holds the task now.
 const step: TaskHandlingStep = { step: "unanswered", at: "2026-08-21T09:15:30Z", by: "A-12", dialId: "dial-7f2", destinationId: "tier2" };
@@ -3698,7 +3751,7 @@ choice that is no command at all:
 
 | The lead | The agent's task | The lead's task |
 | --- | --- | --- |
-| `{ type: "lead-assist", action: "take-over" }` | `task-ended` with `{ type: "transferred", destination: leadId }`, straight from `in-progress`: **no `completing` window**, the agent is idle at once | Continues alone, and ends as any call does |
+| `{ type: "lead-assist", action: "take-over" }` | `task-ended` with `{ type: "transferred", destinationId: leadId }`, straight from `in-progress`: **no `completing` window**, the agent is idle at once | Continues alone, and ends as any call does |
 | `{ type: "lead-assist", action: "leave" }` | Continues; `leadAssist` is cleared | `task-ended` with `{ type: "left" }` -- the call goes on without them |
 | Stays until the customer hangs up | `task-media-ended`, `completing`, its own disposition | The same, independently: **both have the disposal window** |
 
@@ -3744,7 +3797,7 @@ executeTeamMonitor({ command: { type: "monitor", memberId: "A-1" } })
 
 // 2. The lead's own task arrives -- task-offered with `automatic`, as a joined call does -- and
 //    carries `monitoring`; the task id is the lead's, the member's call is named inside it.
-//    monitoring: { memberId: "A-1", taskId: "call-42", mode: "monitor", since }
+//    monitoring: { memberId: "A-1", taskId: "call-42", allocationId: "alloc-42", mode: "monitor", since }
 
 // 3. The lead changes how they are heard; the provider restates the task with the new mode.
 executeTeamMonitor({ command: { type: "whisper" } })
@@ -3781,7 +3834,7 @@ const monitoringLead = {
   channel: "voice",
   capabilities: {},
   phase: "in-progress",
-  monitoring: { memberId: "A-1", taskId: "call-42", mode: "whisper", since: "2026-08-21T09:04:00Z" },
+  monitoring: { memberId: "A-1", taskId: "call-42", allocationId: "alloc-42", mode: "whisper", since: "2026-08-21T09:04:00Z" },
 } satisfies Pick<Task<"voice">, "channel" | "capabilities" | "phase" | "monitoring">;
 ```
 
@@ -4134,12 +4187,14 @@ declared:
 | `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 provisioning permitting it. One word for refusing an offer, whatever the channel. |
 | `call` | 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` | `completionMode: "agent-command"`. The `dispositions` capability decides whether a code travels with the command, never whether the command exists — a task Omni cannot complete never ends. |
+| `complete` | `completionMode: "agent-command"`. The `dispositions` 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.disposition.unknown`), a code at all where it requires one (`.disposition.required`), notes as it said (`.notes.required`, `.notes.unexpected`), and neither where the task declares no dispositions (`.disposition.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. |
 | `transfer` with `action: "warm"` | The `warmTransfer` capability. `action: "cold"` is gated by `coldTransfer`; the two are declared and offered separately. |
 | `transfer` with `action: "complete"` or `"cancel"` | A consultation in progress -- a `consulted` entry on `Task.onCall`. Without one there is nothing to complete or cancel, and a provider that receives either answers `failed`. |
 | `lead-assist` with `action: "request"` or `"cancel"` | The `leadAssist` capability. `cancel` needs a request standing -- `Task.leadAssist` with status `requested`. |
 | `lead-assist` with `action: "take-over"` or `"leave"` | The lead's own task, on a call they joined -- `Task.assisting` present. An agent's task never has it, and a provider that receives either without it answers `failed`. |
+| `transfer` with a destination, `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 every field the control's `prompt` asked for (`command.custom.prompt`). |
 | Everything else | Its own named capability. |
 
 **A control on the contact belongs to the handling phases**, `in-progress` and `paused`:
@@ -4150,7 +4205,7 @@ call with nobody on it, a conversation closed -- and a wrap-up that still shows
 for nothing. The capability stays declared, because it is a property of the task and the task is
 still open; the phase says there is nothing to use it on. Omni shows none of these controls outside
 the two phases, and `validateTaskCommand` refuses each of them there (`command.phase.handling`).
-The commands with a phase of their own -- `answer`, `accept`, `decline` and `reject` in `pending`,
+The commands with a phase of their own -- `answer`, `accept` and `decline` in `pending`,
 `call` 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
@@ -4411,7 +4466,8 @@ when a lead who joined it leaves -- see **Lead assist**.
 A successful `complete` or `transfer` command does not clear the task. Omni waits for `task-ended`.
 The `task-media-ended` event and the `completing` phase are likewise non-terminal. A replacement
 snapshot that no longer contains the task also clears it. Repeated `task-ended` delivery with the
-same envelope ID is harmless.
+same envelope ID is harmless, and a `task-ended` naming an allocation that has already ended is
+recognised as the late event it is, never applied to the life now open under the same id.
 
 ### `dial-outcome`
 
@@ -4448,7 +4504,7 @@ fails loudly rather than passing with a note. A task published under `capability
 | --- | --- |
 | `expected` | Required. The rule that was broken, as a sentence a person can read. |
 | `observed` | Required. What the platform answered instead. |
-| `taskId` | Optional. The task concerned, where there is one. |
+| `taskId` | Optional. The task concerned, where there is one, with its `allocationId` beside it: a task is named with its life, and an allocation never alone. |
 
 ### `queue-summary`
 
@@ -4594,7 +4650,18 @@ complete it with a disposition where the agent completes -- and holds every step
 host holds a provider to. Each command is validated against the task as published
 (`drive.command.*`), each answer for its method, a refusal of a control the task offered is a
 violation (`drive.command.failed`), and an event the provider owes and never sends is one too
-(`drive.timeout`, after `driveTimeoutMs`, 5000 by default). With the audio open on a softphone,
+(`drive.timeout`, after `driveTimeoutMs`, 5000 by default). Around the drive the exercise holds
+the run to what a host holds a provider to between commands: an offer before the host stated
+capacity, or beyond the count with nothing dialled on it, is named
+(`stream.taskOffered.beforeCapacity`, `.overCapacity`); every user the snapshot names is looked up
+through `describeUsers` and the answer held to the shape, nobody unasked, nobody described as
+nothing (`describeUsers.user.*`, `describeUsers.unasked`, `connection.describeUsers.empty`); and
+the second adapter a `rebuild` gives comes up signed in as the same login from the secrets alone
+before it reads anything (`drive.reload.login`). The result also says which rules the
+run evaluated, pass or fail, in `rulesEvaluated`: the validators' as each was applied, the stream's
+as each case was considered, so a test that needs a rule to have run asserts it there rather than
+inferring it from an empty `violations`, and a rule absent from it was never looked at, which is a
+gap and not a pass. With the audio open on a softphone,
 the drive mutes it for one second and reports the leg through `recordStep`, begun and then ended,
 expecting each report `recorded` (`drive.recordStep.failed`, `.rejected`); and where the provider
 restates the task's record afterwards, the leg is in it or the hole is named

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xema/omni-protocol",
-  "version": "0.1.66",
+  "version": "0.1.68",
   "description": "The Omni protocol: the contract every provider adapter implements",
   "type": "module",
   "license": "MIT",