@xema/omni-protocol 0.1.103 → 0.1.105

package/dist/index.d.ts

@@ -153,6 +153,12 @@ export interface Manifest<C extends Channel = Channel> {
     authenticationMethods: AuthenticationMethod[];
     idleCapabilities?: IdleCapabilities<C>;
     /** Optional provider-clock sampling through Connection.checkTime; absent means unsupported. */
+    /**
+     * 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
+     * lead's `listening.since`, an `onCall.since`, a shift's `signedInAt` -- so every screen counts
+     * from the provider's clock and two screens differ by their delay alone.
+     */
     timeCheck?: true;
     /** Provider uses its own timestamps for final records; host timestamps are advisory. Omission makes no trust promise. */
     timestampAuthority?: "provider";
@@ -583,7 +589,8 @@ export type TransportStatus = "connecting" | "active" | "error";
  * connection and call `connect()` again -- or `reauthenticate` -- run the authentication flow
  * first. The adapter knows which; the host acts on its word.
  */
-export type TransportRecovery = "reconnect" | "reauthenticate";
+/** What revives an errored connection: `displaced` says another client took the login, and nothing revives this one until the agent takes it back. */
+export type TransportRecovery = "reconnect" | "reauthenticate" | "displaced";
 /** Every field is optional: a provider sends what it knows and omits what it does not. */
 export interface Contact {
     name?: string;
@@ -967,6 +974,14 @@ export type Task<C extends Channel = Channel> = {
      */
     previewEndsInSeconds?: DurationSeconds;
     atDeadline?: PreviewDeadline;
+    /**
+     * 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, so a reloaded
+     * desk and a lead's screen count down the same number. 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.
+     */
+    wrapEndsInSeconds?: DurationSeconds;
     /** The identifier an agent reads back to a customer, where the provider has one. */
     reference?: string;
     attributes?: TaskAttribute[];
@@ -1206,8 +1221,13 @@ export interface BreakRequest {
  */
 export type ForcedBreak = {
     by: UserId | "provider";
-    /** Optional expected time on break, in milliseconds from actual start. Advisory only. */
-    expectedDurationMs?: number;
+    /**
+     * How long the break is expected to run yet, in whole seconds from this publication, restated
+     * on every publication that carries it so every screen counts down the same number from
+     * receipt. Advisory only: nothing ends the break but the agent. Absent once it has run out, or
+     * where none was expected.
+     */
+    expectedEndsInSeconds?: DurationSeconds;
 };
 export interface BreakState {
     status: BreakStatus;
@@ -1264,10 +1284,10 @@ export interface TeamMember {
     break?: Extract<BreakStatus, "awaiting-approval" | "granted" | "starting-after-task">;
     /** The member's open tasks, trimmed, kept current by the provider; `[]` when they hold none, omitted only where the provider cannot see them. */
     tasks?: MemberTask[];
-    /** Present while this lead is on the member's call, listening, coaching or joined; absent otherwise. */
-    listening?: MemberListening;
-    /** The member's own history for the day: sign-in, sign-out, breaks and productivity. Omitted where the provider cannot say. */
-    shift?: MemberShift;
+    /** Every lead on this member's call, listening, coaching or joined, published to every lead alike; absent while none is. */
+    listening?: MemberListening[];
+    /** The member's own history for the day: sign-in, sign-out, breaks and productivity, the same numbers the member's own snapshot carries. Omitted where the provider cannot say. */
+    shift?: Shift;
     /** The member's standing ask for a lead on one of their calls; absent when they are not asking. */
     request?: MemberRequest;
 }
@@ -1278,10 +1298,11 @@ export interface MemberRequest {
     since: IsoTimestamp;
 }
 /**
- * A member's task as the lead sees it: the same task the member's desk holds, trimmed by the
- * provider. The assignment, what the call is and where it stands, the room and the full history
- * are always here; the workspace -- browsers, controls, completion terms -- is the member's and
- * travels only if the provider chooses to send it.
+ * A member's task as the lead sees it: the same task the member's desk holds, less the workspace.
+ * The assignment, what the call is and where it stands, the party as the provider shows it to
+ * leads, the room, the audio, the completion terms and the whole record are here; the controls,
+ * their source and the browsers are the member's desk's alone and never travel. Published to every
+ * lead whenever the member's own desk hears of the task.
  */
 export type MemberTask<C extends Channel = Channel> = {
     assignmentId: AssignmentId;
@@ -1293,11 +1314,9 @@ export type MemberTask<C extends Channel = Channel> = {
     reference?: string;
     attributes?: TaskAttribute[];
     history?: TaskHistory;
-    capabilities?: TaskCapabilities<C>;
-    capabilitySource?: CapabilitySource;
-    browsers?: TaskBrowser[];
     completionMode?: CompletionMode;
     wrapAllowance?: DurationSeconds;
+    wrapEndsInSeconds?: DurationSeconds;
 } & (C extends "voice" ? {
     onCall?: OnCall[];
     leadAssist?: TaskLeadAssist;
@@ -1310,11 +1329,14 @@ export type MemberTask<C extends Channel = Channel> = {
     audio?: never;
 });
 /**
- * The lead on this member's call: which of the member's calls, in the mode they are heard, since
- * when. Its appearance on the team member list is the provider's word that the lead's audio is up,
- * and the application opens `openAudio` on the assignment named; its disappearance closes it.
+ * A lead on this member's call: who, which of the member's calls, in the mode they are heard,
+ * since when. Every lead sees every entry; the application opens `openAudio` on the entry whose
+ * `leadId` is the signed-in lead, and closes it when that entry goes. A lead who is heard --
+ * `join-call` -- is also on the task's `onCall` as an `agent`; `listen` and `coach` leave no trace
+ * on the member's task.
  */
 export interface MemberListening {
+    leadId: UserId;
     assignmentId: AssignmentId;
     mode: ListeningMode;
     since: IsoTimestamp;
@@ -1326,11 +1348,13 @@ export interface ShiftEvent {
     kind: ShiftEventKind;
 }
 /**
- * The member's own history for the day, about the person rather than any one call: when they
+ * An agent's own history for the day, about the person rather than any one call: when they
  * signed in and out, today's totals as the provider counts them, each present only when the
- * provider knows it, and the day's sign-in, sign-out and break events, oldest first.
+ * provider knows it, and the day's sign-in, sign-out and break events, oldest first. Published
+ * to the agent on their snapshot and on `shift-updated`, and to their lead on the team member
+ * list: the same numbers from the same count.
  */
-export interface MemberShift {
+export interface Shift {
     signedInAt: IsoTimestamp;
     signedOutAt?: IsoTimestamp;
     talkSeconds?: DurationSeconds;
@@ -1550,6 +1574,12 @@ export type PreferenceResult = {
 export interface Snapshot<C extends Channel = Channel> {
     transport: TransportStatus;
     loginId: string;
+    /**
+     * The provider's own instant of this read, required of a provider that declares `timeCheck`:
+     * every duration the desk renders off the active call is counted from the provider's clock, and
+     * this sample saves a `checkTime` for it. Every envelope's `occurredAt` is a sample too.
+     */
+    providerTime?: IsoTimestamp;
     break: BreakState;
     /** Every task currently owned by this agent for this provider. */
     tasks: Task<C>[];
@@ -1557,6 +1587,8 @@ export interface Snapshot<C extends Channel = Channel> {
     taskCount: number;
     contacts?: Contact[];
     calendar?: ScheduledActivity[];
+    /** The agent's own day so far, as the provider counts it; replaced whole by `shift-updated`. Omitted where the provider cannot say. */
+    shift?: Shift;
     team?: TeamMembers;
 }
 /**
@@ -1668,6 +1700,11 @@ export type ProviderEvent<C extends Channel = Channel> = {
 } | {
     type: "calendar-updated";
     calendar: ScheduledActivity[];
+}
+/** The agent's own day, whole, whenever a total moves: a task ended, a break ended. */
+ | {
+    type: "shift-updated";
+    shift: Shift;
 };
 /**
  * The `Provider` prefix survives here for a mechanical reason rather than a naming one: `Event`

package/dist/testing.d.ts

@@ -7,7 +7,7 @@ export { ProtocolConformanceError, assertNoViolations, type ProtocolViolation }
  * rules -- each optional part of a task, each optional part of the break state and team member list, each
  * declared contribution, and each event type.
  */
-declare const STATE_SUBJECTS: readonly ["tasks", "task.browsers", "task.attributes", "task.history", "task.onCall", "task.leadAssist", "task.takenOver", "task.audio", "task.acceptance", "task.outcomes", "task.destinations", "task.custom", "task.locked", "break.reasons", "break.forced", "team.members", "team.request", "team.tasks", "team.listening", "team.shift", "contacts", "calendar", "team.policies"];
+declare const STATE_SUBJECTS: readonly ["tasks", "task.browsers", "task.attributes", "task.history", "task.onCall", "task.leadAssist", "task.takenOver", "task.audio", "task.acceptance", "task.outcomes", "task.destinations", "task.custom", "task.locked", "break.reasons", "break.forced", "team.members", "team.request", "team.tasks", "team.listening", "team.shift", "shift", "contacts", "calendar", "team.policies"];
 export type ContractSubject = (typeof STATE_SUBJECTS)[number] | `event.${ProviderEvent["type"]}`;
 export interface AdapterContractResult {
     events: ProviderEventEnvelope[];

package/dist/testing.js

@@ -28,6 +28,7 @@ const STATE_SUBJECTS = [
     "team.tasks",
     "team.listening",
     "team.shift",
+    "shift",
     "contacts",
     "calendar",
     "team.policies",
@@ -38,7 +39,7 @@ const EVENT_TYPES = {
     snapshot: true, "transport-status": true, "break-state": true, "task-offered": true, "task-updated": true,
     "task-audio-started": true, "task-audio-ended": true, "task-ended": true, "dial-outcome": true, announcement: true, "queue-summary": true, diagnostic: true,
     "team-updated": true, "team-member-updated": true, "team-member-removed": true, "team-policies-updated": true,
-    "contacts-updated": true, "calendar-updated": true,
+    "contacts-updated": true, "calendar-updated": true, "shift-updated": true,
 };
 const CONTRACT_SUBJECTS = [
     ...STATE_SUBJECTS,
@@ -94,7 +95,7 @@ function observeMember(member, seen) {
         return;
     if (some(member.tasks))
         seen.add("team.tasks");
-    if (member.listening !== undefined)
+    if (some(member.listening))
         seen.add("team.listening");
     if (member.shift !== undefined)
         seen.add("team.shift");
@@ -126,6 +127,8 @@ function observeSnapshot(value, seen) {
         seen.add("contacts");
     if (some(value.calendar))
         seen.add("calendar");
+    if (value.shift !== undefined)
+        seen.add("shift");
 }
 function observeEvent(envelope, seen) {
     const event = isRecord(envelope) ? envelope.event : undefined;
@@ -162,6 +165,9 @@ function observeEvent(envelope, seen) {
             if (some(event.calendar))
                 seen.add("calendar");
             break;
+        case "shift-updated":
+            seen.add("shift");
+            break;
         default: break;
     }
 }
@@ -719,9 +725,14 @@ function userIdsIn(snapshot) {
         add(snapshot?.break?.forced?.by);
     const team = snapshot?.team;
     if (isRecord(team)) {
-        for (const member of Array.isArray(team.members) ? team.members : [])
-            if (isRecord(member))
-                add(member.id);
+        for (const member of Array.isArray(team.members) ? team.members : []) {
+            if (!isRecord(member))
+                continue;
+            add(member.id);
+            for (const entry of Array.isArray(member.listening) ? member.listening : [])
+                if (isRecord(entry))
+                    add(entry.leadId);
+        }
     }
     for (const task of Array.isArray(snapshot?.tasks) ? snapshot.tasks : []) {
         const t = task;
@@ -1063,7 +1074,7 @@ const REACHABLE_PHASES = {
 export const SUPERSEDED_BY_A_SNAPSHOT = new Set([
     "snapshot", "transport-status", "break-state", "task-offered", "task-updated", "task-ended",
     "task-audio-started", "task-audio-ended", "team-updated", "team-member-updated", "team-member-removed", "team-policies-updated",
-    "contacts-updated", "calendar-updated",
+    "contacts-updated", "calendar-updated", "shift-updated",
 ]);
 export class TaskStream {
     tasks = new Map();

package/dist/validation.js

@@ -36,7 +36,7 @@ export function assertNoViolations(violations, summary) {
  */
 const membersOf = (members) => Object.keys(members);
 const CHANNELS = membersOf({ voice: true, chat: true, email: true });
-const TRANSPORT_RECOVERIES = membersOf({ reconnect: true, reauthenticate: true });
+const TRANSPORT_RECOVERIES = membersOf({ reconnect: true, reauthenticate: true, displaced: true });
 const TASK_PHASES = membersOf({
     pending: true, confirmed: true, preview: true, "in-progress": true, paused: true, completing: true,
 });
@@ -1185,6 +1185,18 @@ function validateTaskInto(task, context, path, into) {
     else {
         into.require(isDurationSeconds(task.wrapAllowance), "task.wrapAllowance", `${path}.wrapAllowance`, "wrapAllowance must be a whole number of seconds, zero or more, or omitted under agent-command");
     }
+    // How much wrap is left travels with the completing task, restated, so every screen counts the same number.
+    if (task.phase === "completing" && task.wrapAllowance !== undefined) {
+        if (task.wrapEndsInSeconds === undefined) {
+            into.add("task.completing.wrapEndsInSeconds.required", `${path}.wrapEndsInSeconds`, "a completing task with a wrap allowance says how much of it is left, so a reloaded desk and a lead's screen count down the same number");
+        }
+        else {
+            into.require(isDurationSeconds(task.wrapEndsInSeconds), "task.completing.wrapEndsInSeconds", `${path}.wrapEndsInSeconds`, "wrapEndsInSeconds is how much wrap is left: a whole number of seconds, zero or more, counted from this publication");
+        }
+    }
+    else if (task.wrapEndsInSeconds !== undefined) {
+        into.add("task.completing.wrapEndsInSeconds.unexpected", `${path}.wrapEndsInSeconds`, task.phase === "completing" ? "no wrap allowance was stated, so there is nothing to count down" : "wrapEndsInSeconds belongs to a completing task; before the wrap there is nothing to count");
+    }
     // The channel is fixed per provider by its manifest, so a task claiming another one is a
     // task Omni would render with the wrong controls.
     into.require(task.channel === context.channel, "task.channel", `${path}.channel`, `a ${context.channel} provider may not publish a ${describeValue(task.channel)} task`);
@@ -1207,7 +1219,7 @@ function validateTaskInto(task, context, path, into) {
                 into.violations.push(...validateRecordingState(task.recording.provider, `${path}.recording.provider`));
         }
     }
-    if (context.member !== true || task.browsers !== undefined)
+    if (context.member !== true)
         validateBrowsers(task.browsers, `${path}.browsers`, into);
     validateTaskAttributes(task.attributes, `${path}.attributes`, into, context.levels);
     validateHistory(task.history, `${path}.history`, into, { phase: task.phase, audio: task.audio });
@@ -1226,11 +1238,16 @@ function validateTaskInto(task, context, path, into) {
     validateTakenOver(task.takenOver, context.channel, `${path}.takenOver`, into);
     // Where the terms came from is stated with them: a host cannot tell "the platform permits
     // nothing" from "the terms could not be read" from the set alone, and the provider knows which.
-    if (context.member !== true || task.capabilitySource !== undefined)
-        into.oneOf(task.capabilitySource, CAPABILITY_SOURCES, "task.capabilitySource", `${path}.capabilitySource`);
-    const capabilities = task.capabilities;
-    if (context.member === true && capabilities === undefined && task.browsers === undefined)
+    if (context.member === true) {
+        // The lead's copy is the record, the room and the terms; the workspace stays on the member's desk.
+        for (const field of ["capabilities", "capabilitySource", "browsers"]) {
+            if (task[field] !== undefined)
+                into.add("team.member.task.workspace", `${path}.${field}`, `${field} is the member's workspace, and never travels to a lead`);
+        }
         return;
+    }
+    into.oneOf(task.capabilitySource, CAPABILITY_SOURCES, "task.capabilitySource", `${path}.capabilitySource`);
+    const capabilities = task.capabilities;
     if (!isPlainObject(capabilities)) {
         into.add("task.capabilities.shape", `${path}.capabilities`, "a task needs a capabilities object");
         return;
@@ -1313,8 +1330,9 @@ function validateForcedBreak(value, path, into) {
     for (const field of ["endsAutomatically", "endsAt"]) {
         into.require(!Object.hasOwn(value, field), "break.forced.manualResume", `${path}.${field}`, "automatic ending fields are unsupported; the agent must resume manually");
     }
-    if (value.expectedDurationMs !== undefined)
-        into.require(typeof value.expectedDurationMs === "number" && Number.isFinite(value.expectedDurationMs) && value.expectedDurationMs > 0, "break.forced.expectedDurationMs", `${path}.expectedDurationMs`, "expectedDurationMs must be a positive finite number of milliseconds");
+    into.require(!Object.hasOwn(value, "expectedDurationMs"), "break.forced.expectedDurationMs.renamed", `${path}.expectedDurationMs`, "the state says how long is left, as expectedEndsInSeconds; the duration asked for travels on the lead's command alone");
+    if (value.expectedEndsInSeconds !== undefined)
+        into.require(isDurationSeconds(value.expectedEndsInSeconds), "break.forced.expectedEndsInSeconds", `${path}.expectedEndsInSeconds`, "expectedEndsInSeconds is how long the break is expected to run yet: a whole number of seconds, zero or more, counted from this publication");
 }
 /** Checks break status against the full currently retained task set, after a transaction. */
 export function validateBreakStatus(state, tasks, path = "snapshot") {
@@ -1435,7 +1453,8 @@ export function validateTeamCommand(request, context, path = "teamCommand") {
         into.require(asked !== undefined && (command.assignmentId === undefined || asked.assignmentId === command.assignmentId), "team.command.request", path, `${command.type} answers a request the team member list carries on the member, and this member has none`);
     }
     else if (command.type === "coach" || command.type === "join-call" || command.type === "leave") {
-        into.require(isPlainObject(target) && target.listening !== undefined, "team.command.listening", path, `${command.type} needs the lead on this member's call: the team member list shows listening on them`);
+        // Every lead's entry is on the member; the one this command moves is the signed-in lead's.
+        into.require(isPlainObject(target) && Array.isArray(target.listening) && target.listening.some((entry) => isPlainObject(entry) && entry.leadId === self), "team.command.listening", path, `${command.type} needs this lead on this member's call: the team member list shows listening on them naming this lead`);
     }
     return into.violations;
 }
@@ -1631,10 +1650,19 @@ function validateTeamMembersInto(teamMembers, path, context, into) {
         }
         validateTeamMemberInto(member, at, context, into);
     });
-    // One member's call at a time.
-    const listened = teamMembers.members.filter((member) => isPlainObject(member) && member.listening !== undefined);
-    if (listened.length > 1)
-        into.add("team.listening.single", `${path}.members`, "a lead is on one member's call at a time");
+    // One member's call at a time, per lead.
+    const onCalls = new Map();
+    for (const member of teamMembers.members) {
+        if (!isPlainObject(member) || !Array.isArray(member.listening))
+            continue;
+        const leads = new Set(member.listening.filter(isPlainObject).map(entry => entry.leadId).filter((id) => typeof id === "string"));
+        for (const leadId of leads)
+            onCalls.set(leadId, (onCalls.get(leadId) ?? 0) + 1);
+    }
+    for (const [leadId, count] of onCalls) {
+        if (count > 1)
+            into.add("team.listening.single", `${path}.members`, `${leadId} is on ${count} members' calls: a lead is on one member's call at a time`);
+    }
 }
 /** One member as the lead sees them, whole: on the list, and on `team-member-updated` alone. */
 export function validateTeamMember(member, path = "member", context = {}) {
@@ -1669,7 +1697,7 @@ function validateTeamMemberInto(member, at, context, into) {
             const held = new Set();
             member.tasks.forEach((task, index) => {
                 const channel = isPlainObject(task) && typeof task.channel === "string" && isChannel(task.channel) ? task.channel : context.channel ?? "voice";
-                validateTaskInto(task, { channel, levels: context.levels, member: true }, `${at}.tasks[${index}]`, into);
+                validateTaskInto(task, { channel, levels: context.levels, member: true, locked: context.locked }, `${at}.tasks[${index}]`, into);
                 if (isPlainObject(task) && isAssignmentId(task.assignmentId)) {
                     if (held.has(task.assignmentId))
                         into.add("team.member.tasks.unique", `${at}.tasks[${index}].assignmentId`, `duplicate assignment on one member: ${task.assignmentId}`);
@@ -1679,23 +1707,41 @@ function validateTeamMemberInto(member, at, context, into) {
             into.require(member.availability !== "signed-out" || member.tasks.length === 0, "team.member.tasks.availability", `${at}.tasks`, "a member signed out holds no task");
         }
     }
-    // The lead on this member's call, in the mode they are heard.
+    // Every lead on this member's call, in the mode they are heard, published to every lead alike.
     if (member.listening !== undefined) {
-        if (!isPlainObject(member.listening)) {
-            into.add("team.member.listening.shape", `${at}.listening`, "listening must be an object when present");
+        if (!Array.isArray(member.listening)) {
+            into.add("team.member.listening.shape", `${at}.listening`, "listening is an array of the leads on the member's call: absent while none is");
         }
         else {
-            const listened = member.listening;
-            if (into.require(isAssignmentId(member.listening.assignmentId), "team.member.listening.assignmentId", `${at}.listening.assignmentId`, "listening names which of the member's calls the lead is on: the application opens the lead's audio on it") && Array.isArray(member.tasks)) {
-                into.require(member.tasks.some((task) => isPlainObject(task) && task.assignmentId === listened.assignmentId), "team.member.listening.assignment", `${at}.listening.assignmentId`, "the call the lead is on is one the member's tasks carry");
-            }
-            into.oneOf(member.listening.mode, LISTENING_MODES, "team.member.listening.mode", `${at}.listening.mode`);
-            into.timestamp(member.listening.since, "team.member.listening.since", `${at}.listening.since`);
+            into.require(member.listening.length > 0, "team.member.listening.empty", `${at}.listening`, "nobody on the call is absence, not an empty list");
+            const leads = new Set();
+            member.listening.forEach((entry, index) => {
+                const here = `${at}.listening[${index}]`;
+                if (!isPlainObject(entry)) {
+                    into.add("team.member.listening.entry", here, "each listening entry must be an object");
+                    return;
+                }
+                if (into.require(isUserId(entry.leadId), "team.member.listening.leadId", `${here}.leadId`, "a listening entry names the lead on the call, by user id")) {
+                    if (leads.has(entry.leadId))
+                        into.add("team.member.listening.unique", `${here}.leadId`, `${entry.leadId} is listed twice on one member: a lead is on a member's call once`);
+                    leads.add(entry.leadId);
+                }
+                const task = Array.isArray(member.tasks) ? member.tasks.find((task) => isPlainObject(task) && task.assignmentId === entry.assignmentId) : undefined;
+                if (into.require(isAssignmentId(entry.assignmentId), "team.member.listening.assignmentId", `${here}.assignmentId`, "a listening entry names which of the member's calls the lead is on: the application opens its own audio on it") && Array.isArray(member.tasks)) {
+                    into.require(task !== undefined, "team.member.listening.assignment", `${here}.assignmentId`, "the call the lead is on is one the member's tasks carry");
+                }
+                if (into.oneOf(entry.mode, LISTENING_MODES, "team.member.listening.mode", `${here}.mode`) && entry.mode === "join-call"
+                    && isPlainObject(task) && Array.isArray(task.onCall) && isUserId(entry.leadId)) {
+                    // A lead who is heard is in the room the member sees; a silent one is not.
+                    into.require(task.onCall.some((who) => isPlainObject(who) && who.role === "agent" && who.userId === entry.leadId), "team.member.listening.heard", `${here}.mode`, `${entry.leadId} has joined the call and is heard, so the task's onCall carries them as an agent`);
+                }
+                into.timestamp(entry.since, "team.member.listening.since", `${here}.since`);
+            });
         }
     }
     // The member's own history for the day: about the person, not any one call.
     if (member.shift !== undefined)
-        validateShiftInto(member.shift, `${at}.shift`, into);
+        validateShiftInto(member.shift, `${at}.shift`, into, "team.member.shift");
     // The member's standing ask for a lead, on one of the calls they hold.
     if (member.request !== undefined) {
         if (!isPlainObject(member.request)) {
@@ -1721,6 +1767,18 @@ export function validateSnapshot(snapshot, manifest, path = "snapshot", context
     const channel = isPlainObject(manifest) && typeof manifest.channel === "string" ? manifest.channel : "voice";
     const levels = context.levels ?? manifestLevels(manifest);
     into.oneOf(snapshot.transport, TRANSPORT_STATUSES, "snapshot.transport", `${path}.transport`);
+    // The provider's own instant of the read: required where the provider has a clock to state, and
+    // a clock nobody declared is not one the desk may count from.
+    if (isPlainObject(manifest) && manifest.timeCheck === true) {
+        into.timestamp(snapshot.providerTime, "snapshot.providerTime", `${path}.providerTime`);
+    }
+    else if (snapshot.providerTime !== undefined) {
+        into.add("snapshot.providerTime.unexpected", `${path}.providerTime`, "providerTime is the clock of a provider that declares timeCheck; declare it, or send none");
+    }
+    requireClockInto(snapshot, manifest, path, into);
+    // The agent's own day, as the provider counts it: the same numbers their lead sees.
+    if (snapshot.shift !== undefined)
+        validateShiftInto(snapshot.shift, `${path}.shift`, into, "shift");
     if (into.filled(snapshot.loginId, "snapshot.loginId", `${path}.loginId`, "a snapshot needs the login id it belongs to")
         && context.loginId !== undefined) {
         into.require(snapshot.loginId === context.loginId, "snapshot.loginId.mismatch", `${path}.loginId`, `a snapshot for session ${describeValue(snapshot.loginId)} on a login whose session is ${context.loginId}`);
@@ -1894,6 +1952,9 @@ export function validateEventEnvelope(envelope, manifest, path = "event", contex
         return into.violations;
     }
     const at = `${path}.event`;
+    // A snapshot event is read by validateSnapshot, which asks the clock question of it there.
+    if (event.type !== "snapshot")
+        requireClockInto(event, manifest, at, into);
     into.require(!Object.hasOwn(event, "taskId"), "event.assignmentId.renamed", `${at}.taskId`, "an event names a task by its assignment alone; the former field is not accepted");
     switch (event.type) {
         case "snapshot":
@@ -2004,6 +2065,9 @@ export function validateEventEnvelope(envelope, manifest, path = "event", contex
                 event.contacts.forEach((contact, index) => validateContactInto(contact, `${at}.contacts[${index}]`, into, levels));
             }
             break;
+        case "shift-updated":
+            validateShiftInto(event.shift, `${at}.shift`, into, "shift");
+            break;
         case "calendar-updated":
             into.require(idle.calendar === true, "event.calendar.capability", `${at}.calendar`, "calendar-updated requires the calendar idle capability");
             if (!Array.isArray(event.calendar)) {
@@ -2055,38 +2119,65 @@ function validatePreferencesInto(value, path, into, levels) {
     });
 }
 /** The team's policy per capability as the lead sees it: the setting, who set it, who locked it. */
-function validateShiftInto(value, path, into) {
+/** Whether a publication carries an instant the desk renders as a running duration, which the provider's clock reads. */
+function carriesRunningInstant(value) {
+    if (!isPlainObject(value))
+        return false;
+    if (isPlainObject(value.shift) && value.shift.signedInAt !== undefined)
+        return true;
+    const tasks = [
+        ...(Array.isArray(value.tasks) ? value.tasks : []),
+        ...(isPlainObject(value.task) ? [value.task] : []),
+    ];
+    if (tasks.some(task => isPlainObject(task) && Array.isArray(task.onCall) && task.onCall.some((who) => isPlainObject(who) && who.since !== undefined)))
+        return true;
+    const members = [
+        ...(isPlainObject(value.team) && Array.isArray(value.team.members) ? value.team.members : []),
+        ...(isPlainObject(value.member) ? [value.member] : []),
+    ];
+    return members.some(member => isPlainObject(member) && (member.since !== undefined
+        || (Array.isArray(member.listening) && member.listening.some((entry) => isPlainObject(entry) && entry.since !== undefined))
+        || (isPlainObject(member.shift) && member.shift.signedInAt !== undefined)
+        || (Array.isArray(member.tasks) && member.tasks.some((task) => isPlainObject(task) && Array.isArray(task.onCall) && task.onCall.some((who) => isPlainObject(who) && who.since !== undefined)))));
+}
+/** A running duration is counted from the provider's clock: a provider that publishes one declares timeCheck. */
+function requireClockInto(value, manifest, path, into) {
+    if (!isPlainObject(manifest) || manifest.timeCheck === true || !carriesRunningInstant(value))
+        return;
+    into.add("manifest.timeCheck.required", path, "this publishes an instant the desk renders as a running duration -- a since, a signedInAt -- and the manifest declares no timeCheck: every screen counts such a duration from the provider's clock, so the provider states one");
+}
+function validateShiftInto(value, path, into, rule) {
     if (!isPlainObject(value)) {
-        into.add("team.member.shift.shape", path, "shift must be an object when present");
+        into.add(`${rule}.shape`, path, "shift must be an object when present");
         return;
     }
-    const signedIn = into.timestamp(value.signedInAt, "team.member.shift.signedInAt", `${path}.signedInAt`);
-    if (value.signedOutAt !== undefined && into.timestamp(value.signedOutAt, "team.member.shift.signedOutAt", `${path}.signedOutAt`) && signedIn) {
-        into.require(Date.parse(value.signedOutAt) >= Date.parse(value.signedInAt), "team.member.shift.signedOutAt.order", `${path}.signedOutAt`, "a member signs out after signing in");
+    const signedIn = into.timestamp(value.signedInAt, `${rule}.signedInAt`, `${path}.signedInAt`);
+    if (value.signedOutAt !== undefined && into.timestamp(value.signedOutAt, `${rule}.signedOutAt`, `${path}.signedOutAt`) && signedIn) {
+        into.require(Date.parse(value.signedOutAt) >= Date.parse(value.signedInAt), `${rule}.signedOutAt.order`, `${path}.signedOutAt`, "a member signs out after signing in");
     }
     for (const field of ["talkSeconds", "holdSeconds", "breakSeconds"]) {
         if (value[field] !== undefined)
             into.require(isDurationSeconds(value[field]), `team.member.shift.${field}`, `${path}.${field}`, `${field} must be a whole number of seconds, zero or more, or omitted when unknown`);
     }
     if (value.tasksHandled !== undefined)
-        into.require(Number.isInteger(value.tasksHandled) && value.tasksHandled >= 0, "team.member.shift.tasksHandled", `${path}.tasksHandled`, "tasksHandled must be a whole number, zero or more, or omitted when unknown");
+        into.require(Number.isInteger(value.tasksHandled) && value.tasksHandled >= 0, `${rule}.tasksHandled`, `${path}.tasksHandled`, "tasksHandled must be a whole number, zero or more, or omitted when unknown");
     if (value.events !== undefined) {
         if (!Array.isArray(value.events)) {
-            into.add("team.member.shift.events.shape", `${path}.events`, "events must be an array when present");
+            into.add(`${rule}.events.shape`, `${path}.events`, "events must be an array when present");
             return;
         }
         let previous;
         value.events.forEach((event, index) => {
             const at = `${path}.events[${index}]`;
             if (!isPlainObject(event)) {
-                into.add("team.member.shift.event.shape", at, "each shift event must be an object");
+                into.add(`${rule}.event.shape`, at, "each shift event must be an object");
                 return;
             }
-            into.oneOf(event.kind, SHIFT_EVENT_KINDS, "team.member.shift.event.kind", `${at}.kind`);
-            if (into.timestamp(event.at, "team.member.shift.event.at", `${at}.at`)) {
+            into.oneOf(event.kind, SHIFT_EVENT_KINDS, `${rule}.event.kind`, `${at}.kind`);
+            if (into.timestamp(event.at, `${rule}.event.at`, `${at}.at`)) {
                 const instant = Date.parse(event.at);
                 if (previous !== undefined && instant < previous)
-                    into.add("team.member.shift.events.order", `${at}.at`, "shift events are oldest first; this event is earlier than the one before it");
+                    into.add(`${rule}.events.order`, `${at}.at`, "shift events are oldest first; this event is earlier than the one before it");
                 previous = instant;
             }
         });

package/guide.md

@@ -474,11 +474,13 @@ type PreferenceResult =
 type Snapshot = {
   transport: TransportStatus;
   loginId: string;
+  providerTime?: IsoTimestamp;
   break: BreakState;
   tasks: Task[];
   taskCount: number;
   contacts?: Contact[];
   calendar?: ScheduledActivity[];
+  shift?: Shift;
   team?: TeamMembers;
 };
 
@@ -726,6 +728,7 @@ type Task<C extends Channel = Channel> = {
   expiresInSeconds?: DurationSeconds;
   previewEndsInSeconds?: DurationSeconds;
   atDeadline?: PreviewDeadline;
+  wrapEndsInSeconds?: DurationSeconds;
   reference?: string;
   attributes?: TaskAttribute[];
   history?: TaskHistory;
@@ -880,7 +883,15 @@ The adapter is the one that knows the value, so it is the one held to it: given
 queue locked, the validator refuses any other field carrying one, digits compared as digits so no
 formatting hides them (`task.locked.leak`), and a conformance run whose tasks lock a party's number
 or email states those values in `lockedValues`, since a run that cannot ask the question is not a
-pass. An agent application never has the value and never asks. A name is not locked. What the queue provides rather than permits — browsers, outcomes, custom
+pass. An agent application never has the value and never asks. A name is not locked.
+
+**The lock is per audience.** Who sees the number is the provider's choice for each copy of the
+task: the member's, on their desk, and the leads', on the team member list. Hidden from the agent
+and shown to the lead, shown to the agent and hidden from the lead, hidden from both, shown to
+both -- any of the four, as the platform's policy says, and each copy is the provider's statement
+to that audience. Each copy keeps its own lock whole: where the lead's copy locks the number,
+nothing else on that copy carries it, exactly as on the member's (`task.locked.leak`, applied to a
+member's tasks with the same `lockedValues`). What the queue provides rather than permits — browsers, outcomes, custom
 controls — is content, and is never locked.
 
 **A lead sets the team's policy from their team member list.** A login that declares
@@ -933,7 +944,7 @@ type BreakRequest = {
 
 type ForcedBreak = {
   by: UserId | "provider";
-  expectedDurationMs?: number;
+  expectedEndsInSeconds?: DurationSeconds;
 };
 
 type BreakState = {
@@ -975,8 +986,8 @@ type TeamMember = {
   since?: IsoTimestamp;
   break?: Extract<BreakStatus, "awaiting-approval" | "granted" | "starting-after-task">;
   tasks?: MemberTask[];
-  listening?: MemberListening;
-  shift?: MemberShift;
+  listening?: MemberListening[];
+  shift?: Shift;
   request?: MemberRequest;
 };
 
@@ -996,16 +1007,15 @@ type MemberTask<C extends Channel = Channel> = {
   reference?: string;
   attributes?: TaskAttribute[];
   history?: TaskHistory;
-  capabilities?: TaskCapabilities<C>;
-  capabilitySource?: CapabilitySource;
-  browsers?: TaskBrowser[];
   completionMode?: CompletionMode;
   wrapAllowance?: DurationSeconds;
+  wrapEndsInSeconds?: DurationSeconds;
 } & (C extends "voice"
   ? { onCall?: OnCall[]; leadAssist?: TaskLeadAssist; takenOver?: TaskTakenOver; audio?: TaskAudioState }
   : { onCall?: never; leadAssist?: never; takenOver?: never; audio?: never });
 
 type MemberListening = {
+  leadId: UserId;
   assignmentId: AssignmentId;
   mode: ListeningMode;
   since: IsoTimestamp;
@@ -1018,7 +1028,7 @@ type ShiftEvent = {
   kind: ShiftEventKind;
 };
 
-type MemberShift = {
+type Shift = {
   signedInAt: IsoTimestamp;
   signedOutAt?: IsoTimestamp;
   talkSeconds?: DurationSeconds;
@@ -1110,7 +1120,7 @@ type QueueSummary = {
   metrics?: SummaryMetric[];
 };
 
-type TransportRecovery = "reconnect" | "reauthenticate";
+type TransportRecovery = "reconnect" | "reauthenticate" | "displaced";
 
 type ProviderEvent =
   | { type: "snapshot"; reason: "reconnected" | "provider-requested"; snapshot: Snapshot }
@@ -1134,7 +1144,8 @@ type ProviderEvent =
   | { type: "team-member-removed"; memberId: UserId }
   | { type: "team-policies-updated"; policies: TeamPolicies }
   | { type: "contacts-updated"; contacts: Contact[] }
-  | { type: "calendar-updated"; calendar: ScheduledActivity[] };
+  | { type: "calendar-updated"; calendar: ScheduledActivity[] }
+  | { type: "shift-updated"; shift: Shift };
 
 type ProviderEventEnvelope = {
   id: string;
@@ -1626,7 +1637,7 @@ compile time.
 | `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**. |
-| `timeCheck` | Optional `true`: implements `checkTime` for fresh provider-clock samples; agent application polling is independently opt-in. |
+| `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 lead's `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**. |
 | `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`**. |
@@ -2069,6 +2080,12 @@ Creates one live provider connection for the signed-in agent.
 - Must resolve only when the connection can provide a meaningful snapshot.
 - May reject for authentication, configuration, or startup failure.
 - Must not create a second agent session merely because the underlying transport reconnects.
+- **One client at a time per login, and the later one wins.** A second `connect()` on a login
+  that already has a live client is the agent moving desks -- a desk left open at work, signed in
+  from home. The provider takes the new connection, and ends the first with `transport-status`
+  `error` and `recovery: "displaced"`, so the first desk stops stating capacity and reporting legs
+  and shows the agent they are signed in elsewhere. Two live clients on one login would be two
+  sources for one agent, and the lead's list would follow whichever spoke last.
 - The returned connection owns reconnect until Omni calls `disconnect()` or aborts `context.signal`.
 - May be called again on the same login after that: once per `Connection`, not once per login.
   Omni disposes a connection whose `error` named `recovery: "reconnect"` with `disconnect()` and
@@ -2142,11 +2159,13 @@ a capability it agrees with the login: a lead's snapshot carries `team`, nobody
 | --- | --- |
 | `transport` | Current `TransportStatus` — whether this provider's transport can serve the login. Defined under **`transport-status`**. |
 | `loginId` | Identity of this login. It must match the connection context. |
+| `providerTime` | The provider's own instant of this read. Required of a provider that declares `timeCheck` (`snapshot.providerTime`), forbidden of one that does not (`snapshot.providerTime.unexpected`): a clock sample the desk counts durations from, saving it a `checkTime`. |
 | `break` | Complete break state, including status, whether the agent may ask, reasons, retry details, and any forced break. |
 | `tasks` | Complete set of tasks currently offered to or owned by this agent. |
 | `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. |
+| `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
@@ -2407,7 +2426,8 @@ time. Runtime conformance checks also require the task channel to match its prov
 | `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. `0` is no wrap at all, so a task with it publishes no `outcomes` (`task.outcomes.wrapAllowance`). |
+| `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**. |
@@ -2643,6 +2663,15 @@ nothing acts on it -- the task waits for `complete` however long that takes, wit
 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:
 
@@ -2798,6 +2827,15 @@ Migration from the earlier spellings:
 | 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
@@ -2919,7 +2957,8 @@ 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.
+  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
@@ -3747,14 +3786,14 @@ The team break command formerly named release is now `end-forced-break`, and its
 `team.break.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 include an advisory `expectedDurationMs`.
-The agent must explicitly resume when ready. The retired endsAutomatically and endsAt fields
-are rejected, including when an expected duration is also provided.
-
-**Every forced break has a person behind it.** A lead or a manager forced it; there is no such
-thing as a break the platform forced on its own. Where a platform applies one automatically, it is
-executing a preference somebody configured, and that person is the owner of the action — `by` names
-them, not the machinery that carried it out.
+`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.
@@ -3769,16 +3808,16 @@ For example:
 ```ts
 forced: {
   by: "manager-1042",
-  expectedDurationMs: 600000
+  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. An expected duration is a positive finite number of milliseconds, measured from actual
-entry into `on-break`, excluding any `starting-after-task` wait. Omission means no expected
-duration was supplied. Neither duration expiry nor an overdue indication authorizes the agent application
-or provider to end the break, restore availability, or route work to the agent.
+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
@@ -3802,9 +3841,9 @@ must correlate resumption to the authenticated agent's action; a state-only orde
 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 may display the expected duration. A countdown requires an evidenced actual start;
-a received snapshot, replay or reconnect is not a new start and cannot restart the duration.
-Without that evidence, show the duration without inventing a start or return time.
+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
@@ -4210,10 +4249,10 @@ computes nothing. See **`team-updated`** and its companions.
 | `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, trimmed by the provider. The assignment, title, task type, phase, party, room and audio are what the lead reads; the task's history is carried in the same shape as on the member's desk, as much of it as the provider chooses to send; the workspace — controls, their source, browsers, completion terms — is the member's and travels only if the provider sends it. `[]` when the member holds none; omitted only where the provider cannot see them. |
-| `listening` | Present while this lead's channel is in this member's call — listening, coaching or joined — naming which of the member's calls by `assignmentId`, the `mode` they are heard in, and since when. Its appearance is what the lead's audio opens on. One member's call at a time (`team.listening.single`). |
+| `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. Omitted where the provider cannot say. |
+| `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:
 
@@ -4236,11 +4275,28 @@ by it, as a colleague signing in is. `team-member-removed` takes one off. Never
 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.
+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
@@ -4333,9 +4389,10 @@ 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 }`, the member on the team member list carries
-`listening: { 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
+`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
@@ -4403,10 +4460,11 @@ history. The three modes determine who hears the lead:
 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: `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. Nothing else says
+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.
 
@@ -4417,13 +4475,15 @@ The flow, end to end:
 // 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; the member carries
-//    listening: { assignmentId: "alloc-42", mode: "listen", since }
-//    -- the application opens openAudio({ assignmentId: "alloc-42" }) on the lead's connection.
-// 4. The lead changes how they are heard; the member is published again with the new listening.mode. The audio stays open.
+// 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 listening; the application closes the audio.
+// 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 listening no later than the offer, the application
@@ -4434,22 +4494,29 @@ 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 listening on the member, so the audio is reopened.
+//    still carries this lead's entry in listening on the member, so the audio is reopened.
 ```
 
-**`listening` on the member is the state**, restated on every change of mode, naming the call so
-the application knows which audio to open (`team.member.listening.assignmentId`, and one the
-member's tasks carry, `team.member.listening.assignment`), and a lead is on one member's call at a
-time (`team.listening.single`).
+**`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.
 
-**Nothing reaches the member.** The member's task carries no trace of a listening lead in any
-mode: 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.
+**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
 
@@ -4917,7 +4984,7 @@ The current exceptions and their reasons are:
 
 | Case | Exception and reason |
 | --- | --- |
-| Agent application display of provider deadlines (`expiresInSeconds`, `previewEndsInSeconds`, wrap deadline) | Each is seconds from the publication that carried it, counted down on the desk from receipt: the provider's own arithmetic, so no clock is compared and the transport delay is the only error. The countdown estimates the display only; it does not establish that the provider acted. Without usable time, show timing uncertainty. |
+| Agent application display of provider deadlines (`expiresInSeconds`, `previewEndsInSeconds`, `wrapEndsInSeconds`) | Each is seconds from the publication that carried it, counted down on the desk from receipt: the provider's own arithmetic, so no clock is compared and the transport delay is the only error. The countdown estimates the display only; it does not establish that the provider acted. Without usable time, show timing uncertainty. |
 | Agent application-triggered preview deadline | A bounded clock estimate with monotonic aging may schedule the agent application's Call command because the provider owns the deadline but the agent application owns the trigger. Do not trigger before the deadline is known to have passed; invalidate on clock discontinuity and reconcile when uncertain. |
 | Recording evidence expiry | A bounded observer-domain clock estimate with monotonic aging may assess freshness because observation and expiry belong to the recorder's clock. If time cannot be trusted, recording state is unknown; never renew evidence from receipt or replay. |
 | Unknown recording state | `observedAt` and `validUntil` are absent because there is no confirmed observation. The containing provider event still has its own `occurredAt`; that publication is not a recorder observation. |
@@ -4931,6 +4998,30 @@ must specify their uncertainty and validity; elapsed time should use monotonic a
 jump invalidates the estimate. The optional check below samples provider time without changing event timestamps. Report
 source-measured durations where required; timestamp subtraction is not a substitute.
 
+#### Every screen counts from the provider's clock
+
+Two screens watching the same agent -- their own desk, their lead's, a manager's on another floor
+-- must show the same numbers. Delay between them is fine; arithmetic that differs is not. So
+nothing the desk shows is its own count, with one exception: the running duration of the active
+task or call, which a screen times itself from the moment it saw the call begin -- the
+`task-audio-started` on a softphone, the answer it sent on a desk phone -- and which two such
+screens may therefore disagree on, since their clocks differ. That is the whole exception. A call
+a screen found already up -- on a connect or reconnect snapshot, on a lead's list, after a reload
+-- is counted from the provider's `answered` step's `at` against the provider's clock, like every
+other duration, so a reloaded desk shows 12:40 beside the lead's 12:40 and not 0:05. And a leg
+that has closed shows the provider's `seconds` on every screen, never the count a screen kept.
+Everything else comes from the wire.
+
+Durations off the active call -- how long a member has been `on-break` from their `since`, how
+long a lead has been listening, how long since `signedInAt` -- are counted from the provider's
+clock, never the screen's. The desk keeps the latest provider instant it has received -- a
+snapshot's `providerTime`, an envelope's `occurredAt`, a `checkTime` result -- with the monotonic
+elapsed time since receipt, and renders every such duration from that; a sample older than
+`maxSampleAgeMs` is refreshed with `checkTime`. Without a usable sample the desk shows the instant
+and no count. A provider that publishes any of these instants therefore declares `timeCheck`
+(`manifest.timeCheck.required`) and states `providerTime` on every snapshot
+(`snapshot.providerTime`). Two screens then differ by their delay and nothing else.
+
 #### Optional periodic provider time checks and agent application estimates
 
 A provider may declare `Manifest.timeCheck: true` and implement `Connection.checkTime(request)`.
@@ -5068,6 +5159,11 @@ died; the agent application knows how to run a login. `recovery` joins the two:
   disposes the errored connection with `disconnect()` and calls `connect()` afresh, as for
   `reconnect`, and the fresh snapshot re-establishes state. The adapter tears nothing down itself
   and expects nothing to carry on: the connection that reported `error` is finished.
+- **`displaced`** — another client connected on this login and took it: the agent moved desks.
+  Nothing revives this connection on its own -- Omni does not reconnect, or it would take the
+  login straight back from the desk the agent just sat down at -- and the desk shows the agent
+  they are signed in elsewhere, with a way to take the login back, which is a `connect()` that
+  displaces the other. See **`Adapter.connect(context)`**.
 
 **Patience is the agent application's.** An adapter in `connecting` retries for as long as it takes and never
 has to decide when to stop. Omni owns giving up: after however long it chooses to wait, it may
@@ -5292,8 +5388,8 @@ turned the feature off (`event.team.features`).
 One member, whole, as they now stand: their availability, their tasks, their listening, their
 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 a member's hold, answer, mute or take-over
-publishes to the lead.
+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.
 
 ### `team-member-removed`
 
@@ -5316,6 +5412,13 @@ the `contacts` idle capability.
 Replaces this provider's complete scheduled-activity contribution. It is emitted only when the manifest
 declares the `calendar` idle capability.
 
+### `shift-updated`
+
+The agent's own day, whole, replacing `Snapshot.shift`: emitted whenever a total moves -- a task
+ended, a break ended, a sign-out -- and never to say nothing changed. It carries the same `Shift`
+the agent's lead sees for them on the team member list, so the two screens show one day. See
+**The agent's day is on the wire**.
+
 ## Utilities
 
 ### `assignmentKey(providerId, assignmentId)`
@@ -5380,7 +5483,9 @@ carries that agent reports `team.member.self`, on a `team-member-updated` and a
 reports `team.unentitled`, and a team event to such a login reports `event.team.capability`; given
 `leadFeatures: true`, a snapshot without a team reports `team.required`, and given `leadFeatures: false`,
 anything of the team reaching the lead reports `team.unexpected` or `event.team.features`. Without them those rules are not checked, because they cannot be.
-`exerciseAdapter` passes all three, holding the switch off until it has sent it.
+`exerciseAdapter` passes all three, holding the switch off until it has sent it. Given the manifest, a
+snapshot or event that carries an instant the desk renders as a running duration under a manifest
+without `timeCheck` reports `manifest.timeCheck.required`.
 
 `assertNoViolations(violations)` throws `ProtocolConformanceError` — which carries the full
 `violations` array — when the list is non-empty.

package/package.json

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