@xema/omni-protocol 0.1.102 → 0.1.103

package/dist/index.d.ts

@@ -179,12 +179,12 @@ export interface Manifest<C extends Channel = Channel> {
      */
     runningStepReports?: true;
     /**
-     * How long after an applied completion -- `complete`, or a lead's `take-over-call` -- the provider's
-     * `task-ended` is owed, in milliseconds. `applied` says the provider has completed the task;
-     * the ending follows within this, or the host resyncs and shows the task as unsettled. Stated
-     * per provider, since platforms settle at different speeds.
+     * How long after `applied` the wire shows what the provider did, in milliseconds: the
+     * `task-ended` after a `complete` or a lead's `take-over-call`, the `calendar-updated` after a
+     * `schedule`. Past it the host resyncs and shows the thing as unsettled. Stated per provider,
+     * since platforms settle at different speeds.
      */
-    completionSettleMs: number;
+    settleMs: number;
 }
 export interface SecretStore {
     get(key: string): Promise<string | undefined>;
@@ -666,8 +666,10 @@ export type TaskCapabilities<C extends Channel = Channel> = C extends "voice" ?
 } : C extends "chat" ? SharedTaskCapabilities & {
     decline?: Lockable<true>;
     hold?: Lockable<true>;
+    schedule?: Lockable<true>;
 } : SharedTaskCapabilities & {
     decline?: Lockable<true>;
+    schedule?: Lockable<true>;
 };
 /**
  * How a reusing browser's session is keyed.
@@ -948,6 +950,13 @@ export type Task<C extends Channel = Channel> = {
      * Omni said not, and absent past `pending`.
      */
     acceptance?: AcceptanceMode;
+    /**
+     * In `pending` only: how long the offer has left, in whole seconds from this publication,
+     * restated on every publication that carries it so a reconnect snapshot says what is actually
+     * left. Absent, the offer stands until the provider says otherwise. Runs out: the provider ends
+     * the offer `expired` naming `pending`.
+     */
+    expiresInSeconds?: DurationSeconds;
     /**
      * In `preview` only, and together: how long the preparation has left, in whole seconds from
      * this publication -- restated on every publication that carries it, so a resync starts the
@@ -999,18 +1008,18 @@ export type TaskOutcome = {
     by: "agent" | "provider" | "party";
     reason?: string;
 }
-/** Only the phases in which somebody is still being waited on can expire; an offer whose `expiresInSeconds` runs out names `pending`. */
+/** Only the phases in which somebody is still being waited on can expire: an offer whose `expiresInSeconds` runs out names `pending`, accepted work the platform gave up on names `confirmed`. A preview never lapses: withdrawn, it is `cancelled` by the provider. */
  | {
     type: "expired";
-    phase: "pending" | "confirmed" | "preview";
+    phase: "pending" | "confirmed";
 } | {
     type: "failed";
     failure: ProtocolFailure;
 };
 export declare const TASK_COMMAND_NAMES: {
     readonly voice: readonly ["answer", "decline", "dial", "hold", "resume", "end-call", "terminate-call", "connect-back", "lead-assist", "conference", "recording", "schedule", "complete"];
-    readonly chat: readonly ["accept", "decline", "pause", "resume", "complete"];
-    readonly email: readonly ["accept", "decline", "complete"];
+    readonly chat: readonly ["accept", "decline", "pause", "resume", "schedule", "complete"];
+    readonly email: readonly ["accept", "decline", "schedule", "complete"];
 };
 export type TaskCommandName<C extends keyof typeof TASK_COMMAND_NAMES> = (typeof TASK_COMMAND_NAMES)[C][number];
 export interface OutcomePayload {
@@ -1043,17 +1052,7 @@ export type VoiceTaskCommand = {
  | {
     type: "connect-back";
     dialId: DialId;
-}
-/**
- * Put a time on the calendar for this party: a follow-up promised on the call. Gated by
- * `schedule`, issuable in `in-progress`, `paused` or `completing`; the activity arrives on
- * `calendar-updated`, which is the provider's word that it stands.
- */
- | {
-    type: "schedule";
-    at: IsoTimestamp;
-    note?: string;
-}
+} | ScheduleCommand
 /** Ask a lead to join, with a note. Gated by `leadAssist`. */
  | {
     type: "lead-assist";
@@ -1093,6 +1092,18 @@ export type VoiceTaskCommand = {
 }) | ({
     type: "complete";
 } & OutcomePayload);
+/**
+ * Put a time on the calendar for this party: a follow-up promised on the call or in the
+ * conversation, or written up in wrap. Gated by `schedule` on any channel, issuable in
+ * `in-progress`, `paused` or `completing`, under a manifest that declares `calendar` for it to
+ * land on; `applied` says it is on the calendar, and the `calendar-updated` that shows it follows
+ * within the manifest's `settleMs`.
+ */
+export type ScheduleCommand = {
+    type: "schedule";
+    at: IsoTimestamp;
+    note?: string;
+};
 export type ChatTaskCommand = {
     type: "accept";
 } | {
@@ -1101,14 +1112,14 @@ export type ChatTaskCommand = {
     type: "pause";
 } | {
     type: "resume";
-} | ({
+} | ScheduleCommand | ({
     type: "complete";
 } & OutcomePayload);
 export type EmailTaskCommand = {
     type: "accept";
 } | {
     type: "decline";
-} | ({
+} | ScheduleCommand | ({
     type: "complete";
 } & OutcomePayload);
 export interface CustomTaskCommand {
@@ -1187,9 +1198,11 @@ export interface BreakRequest {
     reasonId?: string;
 }
 /**
- * A break forced on the agent; the agent must explicitly resume when ready. `by` is the lead who
- * forced it, or `provider` where the platform itself did, on its own rule or a schedule: the agent
- * sees who, and a person is named only when there is one.
+ * A break forced on the agent; the agent must explicitly resume when ready. A lead's `force-break`
+ * is a command to the provider, which forces the break: `by` names the lead who asked it to, or
+ * `provider` where the platform itself did, on its own rule or a schedule. The agent sees who, a
+ * person is named only when there is one, and a break the platform imposed is the platform's to
+ * lift: a lead's `end-forced-break` on it fails with `omni.break-forced-by-provider`.
  */
 export type ForcedBreak = {
     by: UserId | "provider";
@@ -1322,6 +1335,7 @@ export interface MemberShift {
     signedOutAt?: IsoTimestamp;
     talkSeconds?: DurationSeconds;
     holdSeconds?: DurationSeconds;
+    /** Every break the member was on today, including time held elsewhere for a break another provider forced: the provider counts it under a break kind of its own. */
     breakSeconds?: DurationSeconds;
     tasksHandled?: number;
     events?: ShiftEvent[];
@@ -1590,8 +1604,6 @@ export type ProviderEvent<C extends Channel = Channel> = {
 } | {
     type: "task-offered";
     task: Task<C>;
-    /** How long the agent has to answer, in whole seconds from this event; the offer expires when it runs out. Absent, it stands until the provider says otherwise. */
-    expiresInSeconds?: DurationSeconds;
 } | {
     type: "task-updated";
     task: Task<C>;
@@ -1669,7 +1681,7 @@ export interface ProviderEventEnvelope<C extends Channel = Channel> {
     occurredAt: IsoTimestamp;
     event: ProviderEvent<C>;
 }
-export declare const OMNI_FAILURE_CODES: readonly ["omni.not-authenticated", "omni.capability-not-enabled", "omni.assignment-not-found", "omni.destination-not-permitted", "omni.phone-not-permitted", "omni.rate-limited", "omni.unavailable", "omni.break-already-committed", "omni.recording-unsettled"];
+export declare const OMNI_FAILURE_CODES: readonly ["omni.not-authenticated", "omni.capability-not-enabled", "omni.assignment-not-found", "omni.destination-not-permitted", "omni.phone-not-permitted", "omni.rate-limited", "omni.unavailable", "omni.break-already-committed", "omni.recording-unsettled", "omni.break-forced-by-provider"];
 export type OmniFailureCode = (typeof OMNI_FAILURE_CODES)[number];
 /**
  * What the host refused, told to the adapter that published it: a snapshot the host would not

package/dist/index.js

@@ -78,8 +78,8 @@ export const CAPABILITY_SOURCES = ["queue", "nobody", "not-yet-read"];
 export const TASK_COMMAND_NAMES = {
     voice: ["answer", "decline", "dial", "hold", "resume", "end-call", "terminate-call",
         "connect-back", "lead-assist", "conference", "recording", "schedule", "complete"],
-    chat: ["accept", "decline", "pause", "resume", "complete"],
-    email: ["accept", "decline", "complete"],
+    chat: ["accept", "decline", "pause", "resume", "schedule", "complete"],
+    email: ["accept", "decline", "schedule", "complete"],
 };
 /** The dial a command places, by the host's identity for it; `undefined` for a command that dials nothing. */
 export function commandDialId(command) {
@@ -105,6 +105,8 @@ export const OMNI_FAILURE_CODES = [
     "omni.break-already-committed",
     /** A recording command the provider could not settle either way: no start, stop, pause or resume it can vouch for. */
     "omni.recording-unsettled",
+    /** A lead asked to lift a break the platform itself imposed; the platform lifts its own. */
+    "omni.break-forced-by-provider",
 ];
 /**
  * Preserves the adapter's inferred concrete type while checking it implements `Adapter`.

package/dist/testing.d.ts

@@ -249,6 +249,13 @@ export interface BreakCandidate {
     /** Whether the agent can currently receive work from it: connected, with a capacity stated. */
     holdsCapacity: boolean;
 }
+/**
+ * A break one provider forces stops the agent everywhere: the host states a capacity of zero on
+ * every other usable provider holding capacity -- taken, never refused, and nothing the agent can
+ * cancel -- and on the forcing provider states nothing, since the break itself holds the agent
+ * there. A provider whose login is not usable is left alone, as a break attempt leaves it.
+ */
+export declare function assertForcedBreakStopsTheRest(forcedOn: string, candidates: readonly BreakCandidate[], stopped: readonly string[]): void;
 /**
  * A break attempt asks every connected provider from which the agent can currently receive work.
  * A provider whose login is not usable -- `expired` above all -- is not asked, whatever else is

package/dist/testing.js

@@ -1626,6 +1626,7 @@ async function driveOneCall(drive) {
         const own = validateTaskCommand(command, latestTask(), `drive.command.${String(command.type)}`, {
             levels: effectiveLevels(drive.manifest.orgLevels).map(level => level.id),
             dialOutcomesDeclared: drive.manifest.dialOutcomes !== undefined,
+            calendarDeclared: drive.manifest.idleCapabilities?.calendar === true,
             autoAcceptTasks: drive.context.autoAcceptTasks,
         });
         found.push(...own);
@@ -1798,6 +1799,38 @@ async function driveOneCall(drive) {
             }
         }
     }
+    // 4a. Schedule a follow-up, where the task offers it: applied says it is on the calendar, and the
+    // calendar-updated that shows it is owed within the manifest's bound. The time is the provider's
+    // own: a day after the instant it published the offer, so no clock of the runner's is read.
+    if (latestTask().phase === "in-progress" && offers("schedule")) {
+        const publishedAt = drive.events.slice(0, cursor).reverse().find(envelope => {
+            const event = envelope.event;
+            return (event.type === "task-offered" || event.type === "task-updated") && isTask(event.task) && event.task.assignmentId === taskId;
+        })?.occurredAt;
+        const at = new Date(Date.parse(String(publishedAt ?? "2026-01-01T00:00:00Z")) + 24 * 60 * 60 * 1000).toISOString();
+        if (await send({ type: "schedule", at, note: "Follow-up promised on the call" }) !== undefined) {
+            ruleEvaluated("drive.schedule.unsettled");
+            const settle = Number(drive.manifest.settleMs);
+            const carries = (calendar) => Array.isArray(calendar) && calendar.some(activity => isRecord(activity) && activity.startsAt === at);
+            let unsettled = false;
+            const shown = await waitFor("a calendar-updated carrying the follow-up", envelope => {
+                const event = envelope.event;
+                return event.type === "calendar-updated" && carries(event.calendar) ? event : undefined;
+            }, cursor, { ms: settle, onExpiry: () => { unsettled = true; } });
+            if (shown === undefined && unsettled) {
+                let resync;
+                try {
+                    resync = await drive.connection.snapshot();
+                }
+                catch (error) {
+                    refuse("drive.command.rejected", "drive.schedule", `snapshot() after an unsettled schedule rejected: ${String(error)}`);
+                }
+                if (!(isRecord(resync) && carries(resync.calendar))) {
+                    refuse("drive.schedule.unsettled", "drive.schedule", `schedule was applied and ${settle}ms later no calendar-updated carries a follow-up at ${at}, and a snapshot does not either: applied says the follow-up is on the calendar, and it is not`);
+                }
+            }
+        }
+    }
     // 5. End the call, where the agent may -- with the microphone muted, as agents do. The leg left
     // open at audio end is the provider's to close, since the provider knows the instant the audio
     // ended; the host's own closing report can only follow what it hears, is answered recorded, and
@@ -1853,7 +1886,7 @@ async function driveOneCall(drive) {
     // provider. A conversation has no audio to end and no completing phase to wait for: a chat or an
     // email, and a voice task offering no end-call, is completed from where it stands.
     const completable = latestTask().phase === "completing" || latestTask().phase === "in-progress" || latestTask().phase === "paused";
-    if (latestTask().wrapAllowance !== 0 && completable) {
+    if (!(latestTask().completionMode === "provider-automatic" && latestTask().wrapAllowance === 0) && completable) {
         const command = { type: "complete" };
         const outcomes = isRecord(latestTask().capabilities) ? latestTask().capabilities.outcomes : undefined;
         if (isRecord(outcomes) && outcomes.required === true && Array.isArray(outcomes.codes) && isRecord(outcomes.codes[0])) {
@@ -1864,7 +1897,7 @@ async function driveOneCall(drive) {
             // the manifest stated. Past it the host resyncs: a snapshot still carrying the task is a task
             // held open by a provider that said it was done, and the desk shows it as unsettled.
             ruleEvaluated("drive.completion.unsettled");
-            const settle = Number(drive.manifest.completionSettleMs);
+            const settle = Number(drive.manifest.settleMs);
             let unsettled = false;
             const end = await ended({ ms: settle, onExpiry: () => { unsettled = true; } });
             if (end !== undefined)
@@ -2083,6 +2116,35 @@ export function stillHost(report = { online: true }, guarantees = {}, mute) {
     return { guarantees, ...(mute === undefined ? {} : { mute }), report: () => report, subscribe: () => () => undefined };
 }
 const usableLogin = (status) => status === "authenticated" || status === "refreshing";
+/**
+ * A break one provider forces stops the agent everywhere: the host states a capacity of zero on
+ * every other usable provider holding capacity -- taken, never refused, and nothing the agent can
+ * cancel -- and on the forcing provider states nothing, since the break itself holds the agent
+ * there. A provider whose login is not usable is left alone, as a break attempt leaves it.
+ */
+export function assertForcedBreakStopsTheRest(forcedOn, candidates, stopped) {
+    if (!candidates.some(candidate => candidate.id === forcedOn))
+        throw new Error(`${forcedOn} is not a provider the host knows`);
+    const chosen = new Set(stopped);
+    for (const id of stopped) {
+        if (!candidates.some(candidate => candidate.id === id))
+            throw new Error(`${id} is not a provider the host knows`);
+    }
+    if (chosen.has(forcedOn))
+        throw new Error(`${forcedOn} forced the break and holds the agent itself: its capacity is not restated`);
+    for (const candidate of candidates) {
+        if (candidate.id === forcedOn)
+            continue;
+        const expected = usableLogin(candidate.authentication) && candidate.holdsCapacity;
+        if (expected && !chosen.has(candidate.id)) {
+            throw new Error(`${candidate.id} can give the agent work and must be stopped: capacity 0 stated`);
+        }
+        if (!expected && chosen.has(candidate.id)) {
+            const why = usableLogin(candidate.authentication) ? "holds no capacity" : `is ${candidate.authentication}`;
+            throw new Error(`${candidate.id} ${why} and is not stopped: there is nothing to stop`);
+        }
+    }
+}
 /**
  * A break attempt asks every connected provider from which the agent can currently receive work.
  * A provider whose login is not usable -- `expired` above all -- is not asked, whatever else is

package/dist/validation.d.ts

@@ -39,6 +39,8 @@ export interface TaskValidationContext {
     autoAcceptTasks?: boolean;
     /** Whether the manifest declares `dialOutcomes`. A task that may dial needs it to; absent, the question is not asked. */
     dialOutcomesDeclared?: boolean;
+    /** Whether the manifest declares the `calendar` idle capability. A task that may schedule needs it to; absent, the question is not asked. */
+    calendarDeclared?: boolean;
     /**
      * The values the queue locked on this login's tasks -- a party's number or email -- as whoever
      * runs the validator knows them. Where a task's party stands locked, no other field of it may

package/dist/validation.js

@@ -91,7 +91,7 @@ const LISTENING_MODES = membersOf({ listen: true, coach: true, "join-call": true
 const COMPLETED_BY = membersOf({ agent: true, provider: true });
 const CANCELLED_BY = membersOf({ agent: true, provider: true, party: true });
 const EXPIRABLE_PHASES = membersOf({
-    pending: true, confirmed: true, preview: true,
+    pending: true, confirmed: true,
 });
 const ISOLATION_SCHEME_VALUES = Object.values(BROWSER_ISOLATION_SCHEMES);
 /** The capabilities each channel arm of `TaskCapabilities` declares, keyed off the type itself. */
@@ -100,8 +100,8 @@ const TASK_CAPABILITIES = {
         browsers: true, outcomes: true, custom: true, decline: true, hold: true,
         endCall: true, terminateCall: true, connectBack: true, schedule: true, leadAssist: true, conference: true, recording: true,
     }),
-    chat: membersOf({ browsers: true, outcomes: true, custom: true, decline: true, hold: true }),
-    email: membersOf({ browsers: true, outcomes: true, custom: true, decline: true }),
+    chat: membersOf({ browsers: true, outcomes: true, custom: true, decline: true, hold: true, schedule: true }),
+    email: membersOf({ browsers: true, outcomes: true, custom: true, decline: true, schedule: true }),
 };
 // The published list and the type's keys are the same set, or one of them is wrong.
 true;
@@ -393,6 +393,10 @@ export function validatePhone(value, manifest, path = "context.phone") {
 function manifestDials(manifest) {
     return isPlainObject(manifest) ? Array.isArray(manifest.dialOutcomes) : undefined;
 }
+/** Whether a manifest declares a calendar, and so may publish tasks that schedule onto it. `undefined` where there is no manifest to ask. */
+function manifestCalendar(manifest) {
+    return isPlainObject(manifest) ? isPlainObject(manifest.idleCapabilities) && manifest.idleCapabilities.calendar === true : undefined;
+}
 /** Undefined explicitly means unavailable; a returned estimate is not a clock guarantee. */
 export function validateProviderTimeEstimate(value, scope, path = "estimate") {
     const into = new Collector();
@@ -520,8 +524,10 @@ export function validateManifest(manifest, path = "manifest") {
     if (manifest.runningStepReports !== undefined) {
         into.require(manifest.runningStepReports === true, "manifest.runningStepReports", `${path}.runningStepReports`, "runningStepReports is declared by presence, as true; a provider that takes begin and end only omits it");
     }
-    into.require(!Object.hasOwn(manifest, "disposalSettleMs"), "manifest.completionSettleMs.renamed", `${path}.disposalSettleMs`, "use completionSettleMs; the former field is not accepted");
-    into.require(typeof manifest.completionSettleMs === "number" && Number.isInteger(manifest.completionSettleMs) && manifest.completionSettleMs > 0, "manifest.completionSettleMs", `${path}.completionSettleMs`, "completionSettleMs is how long after an applied completion the task-ended is owed, a positive whole number of milliseconds, stated by every provider");
+    for (const former of ["disposalSettleMs", "completionSettleMs"]) {
+        into.require(!Object.hasOwn(manifest, former), "manifest.settleMs.renamed", `${path}.${former}`, "use settleMs; the former field is not accepted");
+    }
+    into.require(typeof manifest.settleMs === "number" && Number.isInteger(manifest.settleMs) && manifest.settleMs > 0, "manifest.settleMs", `${path}.settleMs`, "settleMs is 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, stated by every provider");
     if (manifest.orgLevels !== undefined) {
         if (!Array.isArray(manifest.orgLevels)) {
             into.add("manifest.orgLevels.shape", `${path}.orgLevels`, "orgLevels must be an array when present");
@@ -1120,6 +1126,11 @@ function validateTaskInto(task, context, path, into) {
         into.require(context.channel === "voice", "task.phase.channel", `${path}.phase`, `a ${context.channel} task has no call to preview`);
         into.require(context.dialOutcomesDeclared !== false, "task.preview.dialOutcomes.required", `${path}.phase`, "a preview ends in the agent pressing Call, which dials, and the manifest declares no dialOutcomes to say how a dial ends");
     }
+    // How long the offer has left travels on the pending task, so a reconnect snapshot restates it.
+    if (task.expiresInSeconds !== undefined) {
+        into.require(task.phase === "pending", "task.pending.expiresInSeconds.unexpected", `${path}.expiresInSeconds`, "expiresInSeconds is how long an offer has left, and belongs to a pending task; accepted, there is no offer to run out");
+        into.require(isDurationSeconds(task.expiresInSeconds), "task.pending.expiresInSeconds", `${path}.expiresInSeconds`, "expiresInSeconds is how long the offer has left: a whole number of seconds, zero or more, counted from this publication");
+    }
     // The deadline and what happens at it travel together, and only while the record is being previewed.
     if (task.previewEndsInSeconds !== undefined || task.atDeadline !== undefined) {
         into.require(task.phase === "preview", "task.preview.deadline.unexpected", `${path}.previewEndsInSeconds`, "previewEndsInSeconds and atDeadline belong to a task in preview; past it there is nothing to wait for");
@@ -1239,8 +1250,10 @@ function validateTaskInto(task, context, path, into) {
     if (isPlainObject(capabilities.outcomes) && capabilities.outcomes.required === true) {
         into.require(task.completionMode !== "provider-automatic", "task.outcomes.required.mode", `${path}.capabilities.outcomes.required`, "a required outcome is the agent's to give, so the task completes on the agent's command; provider-automatic completion cannot wait for it");
     }
+    // Under agent-command the allowance is the expected wrap, shown and never acted on: the agent
+    // completes whenever they are done, so there is always a wrap to collect the code in.
     if (capabilities.outcomes !== undefined) {
-        into.require(task.wrapAllowance !== 0, "task.outcomes.wrapAllowance", `${path}.capabilities.outcomes`, "outcomes are collected in wrap, and wrapAllowance 0 gives none: publish a wrap or no outcomes");
+        into.require(!(task.completionMode === "provider-automatic" && task.wrapAllowance === 0), "task.outcomes.wrapAllowance", `${path}.capabilities.outcomes`, "outcomes are collected in wrap, and provider-automatic with wrapAllowance 0 gives none: publish a wrap or no outcomes");
     }
     for (const [name, declared] of Object.entries(capabilities)) {
         if (declared === undefined)
@@ -1256,6 +1269,10 @@ function validateTaskInto(task, context, path, into) {
         if (DIALLING_CAPABILITIES.includes(name) && context.dialOutcomesDeclared === false) {
             into.add("task.capability.dialOutcomes.required", `${path}.capabilities.${name}`, `${name} dials, and the manifest declares no dialOutcomes to say how a dial ends`);
         }
+        // A follow-up lands on the calendar, so the manifest has to have one for it to land on.
+        if (name === "schedule" && context.calendarDeclared === false) {
+            into.add("task.capability.calendar.required", `${path}.capabilities.schedule`, "schedule puts a follow-up on the calendar, and the manifest declares no calendar for it to land on");
+        }
         // A control the queue could allow may stand locked in its place, saying whose. What the
         // queue provides -- browsers, outcomes, custom controls -- is content, not a control.
         if (isLocked(declared)) {
@@ -1399,8 +1416,11 @@ export function validateTeamCommand(request, context, path = "teamCommand") {
     else if (command.type === "force-break" || command.type === "end-forced-break") {
         validateBreakState(context.memberBreak, `${path}.memberBreak`, into);
         const state = isPlainObject(context.memberBreak) ? context.memberBreak : {};
-        if (command.type === "end-forced-break")
+        if (command.type === "end-forced-break") {
             into.require(state.forced !== undefined && (state.status === "on-break" || state.status === "starting-after-task"), "team.command.endForcedBreak", path, "lift a current forced-break restriction without resuming the agent");
+            // The platform lifts a break it imposed itself; a lead lifts one a lead asked for.
+            into.require(!(isPlainObject(state.forced) && state.forced.by === "provider"), "team.command.endForcedBreak.provider", path, "the platform put this member on the break, and it lifts it: a lead ends a break a lead forced");
+        }
         if (command.type === "force-break") {
             if (command.expectedDurationMs !== undefined)
                 into.require(typeof command.expectedDurationMs === "number" && Number.isFinite(command.expectedDurationMs) && command.expectedDurationMs > 0, "team.command.expectedDurationMs", `${path}.expectedDurationMs`, "expectedDurationMs must be positive finite milliseconds; it never resumes the agent");
@@ -1717,7 +1737,7 @@ export function validateSnapshot(snapshot, manifest, path = "snapshot", context
     else {
         const seen = new Set();
         snapshot.tasks.forEach((task, index) => {
-            validateTaskInto(task, { channel, levels, autoAcceptTasks: context.autoAcceptTasks, dialOutcomesDeclared: manifestDials(manifest), locked: context.locked }, `${path}.tasks[${index}]`, into);
+            validateTaskInto(task, { channel, levels, autoAcceptTasks: context.autoAcceptTasks, dialOutcomesDeclared: manifestDials(manifest), calendarDeclared: manifestCalendar(manifest), locked: context.locked }, `${path}.tasks[${index}]`, into);
             if (isPlainObject(task) && isAssignmentId(task.assignmentId)) {
                 if (seen.has(task.assignmentId))
                     into.add("task.assignmentId.unique", `${path}.tasks[${index}].assignmentId`, `duplicate assignment id: ${task.assignmentId}`);
@@ -1899,16 +1919,15 @@ export function validateEventEnvelope(envelope, manifest, path = "event", contex
             validateBreakState(event.break, `${at}.break`, into);
             break;
         case "task-offered":
-            validateTaskInto(event.task, { channel, levels, autoAcceptTasks: context.autoAcceptTasks, dialOutcomesDeclared: manifestDials(manifest), locked: context.locked }, `${at}.task`, into);
+            validateTaskInto(event.task, { channel, levels, autoAcceptTasks: context.autoAcceptTasks, dialOutcomesDeclared: manifestDials(manifest), calendarDeclared: manifestCalendar(manifest), locked: context.locked }, `${at}.task`, into);
             // An offer introduces work that is not yet under way; work in progress arrives only on a snapshot.
             if (isPlainObject(event.task) && typeof event.task.phase === "string") {
                 into.require(OFFERABLE_PHASES.includes(event.task.phase), "event.taskOffered.phase", `${at}.task.phase`, `task-offered introduces a task as ${OFFERABLE_PHASES.join(", ")}, never as ${event.task.phase}`);
             }
-            if (event.expiresInSeconds !== undefined)
-                into.require(isDurationSeconds(event.expiresInSeconds), "event.taskOffered.expiresInSeconds", `${at}.expiresInSeconds`, "expiresInSeconds is how long the offer stands: a whole number of seconds, zero or more, counted from this event");
+            into.require(event.expiresInSeconds === undefined, "event.taskOffered.expiresInSeconds.unexpected", `${at}.expiresInSeconds`, "expiresInSeconds travels on the pending task, where a reconnect snapshot restates it, not on the event");
             break;
         case "task-updated":
-            validateTaskInto(event.task, { channel, levels, autoAcceptTasks: context.autoAcceptTasks, dialOutcomesDeclared: manifestDials(manifest), locked: context.locked }, `${at}.task`, into);
+            validateTaskInto(event.task, { channel, levels, autoAcceptTasks: context.autoAcceptTasks, dialOutcomesDeclared: manifestDials(manifest), calendarDeclared: manifestCalendar(manifest), locked: context.locked }, `${at}.task`, into);
             break;
         case "task-audio-started":
             into.require(channel === "voice", "event.audio.channel", `${at}.type`, "only a voice provider publishes audio transitions");
@@ -2543,7 +2562,7 @@ export function validateTaskCommand(command, task, path = "command", taskContext
         case "complete": {
             // The agent may finish early under either mode; the provider is free to end at once. With
             // no wrap at all there is no window to cut short, and nothing for the command to do.
-            into.require(task.wrapAllowance !== 0, "command.complete.wrapAllowance", path, "the task has no wrap: with wrapAllowance 0 the provider ends it itself, and there is nothing to complete");
+            into.require(!(task.completionMode === "provider-automatic" && task.wrapAllowance === 0), "command.complete.wrapAllowance", path, "the task has no wrap: under provider-automatic with wrapAllowance 0 the provider ends it itself, and there is nothing to complete");
             // What travels with complete is what the outcomes capability published: a code from its
             // list where it has one, a code at all where it requires one, notes as it said, nothing where it published nothing.
             const outcomes = capabilities.outcomes;

package/guide.md

@@ -203,7 +203,7 @@ type Manifest<C extends Channel = Channel> = {
   dialOutcomes?: C extends "voice" ? DialOutcome[] : never;
   phones?: C extends "voice" ? Phone[] : never;
   runningStepReports?: true;
-  completionSettleMs: number;
+  settleMs: number;
 };
 ```
 
@@ -569,8 +569,8 @@ type TaskCapabilities<C extends Channel = Channel> =
         recording?: Lockable<TaskRecordingPolicy>;
       }
     : C extends "chat"
-      ? SharedTaskCapabilities & { decline?: Lockable<true>; hold?: Lockable<true> }
-      : SharedTaskCapabilities & { decline?: Lockable<true> };
+      ? SharedTaskCapabilities & { decline?: Lockable<true>; hold?: Lockable<true>; schedule?: Lockable<true> }
+      : SharedTaskCapabilities & { decline?: Lockable<true>; schedule?: Lockable<true> };
 ```
 
 The channel arms are why `Task<"email">` rejects `hold` at compile time rather than at runtime.
@@ -723,6 +723,7 @@ type Task<C extends Channel = Channel> = {
   party?: Contact;
   phase: TaskPhase;
   acceptance?: AcceptanceMode;
+  expiresInSeconds?: DurationSeconds;
   previewEndsInSeconds?: DurationSeconds;
   atDeadline?: PreviewDeadline;
   reference?: string;
@@ -745,7 +746,7 @@ type TaskOutcome =
   | { type: "completed"; by: "agent" | "provider" }
   | { type: "taken-over"; leadId: UserId }
   | { type: "cancelled"; by: "agent" | "provider" | "party"; reason?: string }
-  | { type: "expired"; phase: "pending" | "confirmed" | "preview" }
+  | { type: "expired"; phase: "pending" | "confirmed" }
   | { type: "failed"; failure: ProtocolFailure };
 ```
 
@@ -768,8 +769,8 @@ const TASK_COMMAND_NAMES = {
     "schedule",
     "complete",
   ],
-  chat: ["accept", "decline", "pause", "resume", "complete"],
-  email: ["accept", "decline", "complete"],
+  chat: ["accept", "decline", "pause", "resume", "schedule", "complete"],
+  email: ["accept", "decline", "schedule", "complete"],
 } as const;
 
 type TaskCommandName<C extends keyof typeof TASK_COMMAND_NAMES> =
@@ -786,7 +787,7 @@ type VoiceTaskCommand =
   | { type: "end-call" }
   | { type: "terminate-call" }
   | { type: "connect-back"; dialId: DialId }
-  | { type: "schedule"; at: IsoTimestamp; note?: string }
+  | ScheduleCommand
   | { type: "lead-assist"; action: "request"; note?: string }
   | { type: "lead-assist"; action: "cancel" }
   | { type: "conference"; action: "add"; dialId: DialId; destinationId: string }
@@ -795,16 +796,20 @@ type VoiceTaskCommand =
   | (RecordingCommand & { source: "provider" })
   | ({ type: "complete" } & OutcomePayload);
 
+type ScheduleCommand = { type: "schedule"; at: IsoTimestamp; note?: string };
+
 type ChatTaskCommand =
   | { type: "accept" }
   | { type: "decline" }
   | { type: "pause" }
   | { type: "resume" }
+  | ScheduleCommand
   | ({ type: "complete" } & OutcomePayload);
 
 type EmailTaskCommand =
   | { type: "accept" }
   | { type: "decline" }
+  | ScheduleCommand
   | ({ type: "complete" } & OutcomePayload);
 
 type CustomTaskCommand = { type: "custom"; name: string; [key: string]: unknown };
@@ -1115,7 +1120,6 @@ type ProviderEvent =
   | {
       type: "task-offered";
       task: Task;
-      expiresInSeconds?: DurationSeconds;
     }
   | { type: "task-updated"; task: Task }
   | { type: "task-audio-started"; assignmentId: AssignmentId }
@@ -1254,6 +1258,7 @@ const OMNI_FAILURE_CODES = [
   "omni.unavailable",
   "omni.break-already-committed",
   "omni.recording-unsettled",
+  "omni.break-forced-by-provider",
 ] as const;
 type OmniFailureCode = (typeof OMNI_FAILURE_CODES)[number];
 ```
@@ -1586,7 +1591,7 @@ export default defineAdapter({
     channel: "voice",
     supportedProtocolVersions: [OMNI_PROTOCOL_VERSION],
     authenticationMethods: ["browser-sso"],
-    completionSettleMs: 5000,
+    settleMs: 5000,
     idleCapabilities: {
       dial: { destinations: "any-number" },
     },
@@ -1624,7 +1629,7 @@ compile time.
 | `timeCheck` | Optional `true`: implements `checkTime` for fresh provider-clock samples; agent application polling is independently opt-in. |
 | `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**. |
-| `completionSettleMs` | Required. How long after an applied `complete` the provider's `task-ended` is owed, a positive whole number of milliseconds (`manifest.completionSettleMs`). Stated per provider, since platforms settle at different speeds. See **`task-ended`**. |
+| `settleMs` | Required. How long after `applied` the wire shows what the provider did: the `task-ended` after a `complete`, the `calendar-updated` after a `schedule`. A positive whole number of milliseconds (`manifest.settleMs`). Stated per provider, since platforms settle at different speeds. See **`task-ended`**. |
 
 ### Authentication methods
 
@@ -2318,8 +2323,7 @@ declare const task: Task;
 
 const assignment = {
   type: "task-offered",
-  task: { ...task, phase: "pending", acceptance: "consent" },
-  expiresInSeconds: 30,
+  task: { ...task, phase: "pending", acceptance: "consent", expiresInSeconds: 30 },
 } satisfies Extract<ProviderEvent, { type: "task-offered" }>;
 ```
 
@@ -2337,10 +2341,12 @@ on a desk phone — and is not in question per call. See **How the agent hears t
 
 Automatic acceptance still begins with `task-offered`.
 
-`expiresInSeconds` is how long the offer stands, in whole seconds from this event. Where present,
-Omni counts down from receipt and stops offering **Accept** once it runs out; the provider ends
-the lapsed offer with `task-ended` and an `expired` outcome naming `pending`, since nobody
-cancelled it. **Omit it unless the provider can observe it.** A provider that reports only elapsed
+`expiresInSeconds` is how long the offer has left, in whole seconds from the publication that
+carries it. It rides on the pending task, as `acceptance` does, so a reconnect snapshot restates
+it from what is actually left; it belongs to `pending` alone and is gone once the task is accepted
+(`task.pending.expiresInSeconds`, `.unexpected`). Where present, Omni counts down from receipt and
+stops offering **Accept** once it runs out; the provider ends the lapsed offer with `task-ended`
+and an `expired` outcome naming `pending`, since nobody cancelled it. **Omit it unless the provider can observe it.** A provider that reports only elapsed
 ring time after the fact cannot say how long an offer has left, and a computed value would have
 Omni withdraw **Accept** from a task still pending.
 
@@ -2349,7 +2355,7 @@ different clocks, and a countdown that compares one against the other is a count
 fast or slow by their skew. Seconds from the publication that carries them are the provider's own
 arithmetic, counted down on the desk from the moment they arrive, and the transport delay is the
 only error. Restated on every publication that carries them, so a snapshot after a reconnect
-starts the countdown afresh from what is actually left (`event.taskOffered.expiresInSeconds`,
+starts the countdown afresh from what is actually left (`task.pending.expiresInSeconds`,
 `task.preview.previewEndsInSeconds`: a whole number, zero or more).
 
 A preview's deadline is not on the offer. It travels on the task, as `previewEndsInSeconds` with
@@ -2396,6 +2402,7 @@ time. Runtime conformance checks also require the task channel to match its prov
 | `phase` | Current canonical task phase: `pending`, `confirmed`, `preview`, `in-progress`, `paused`, or `completing`. `preview` is voice only. |
 | `audio` | Voice only. The task's real-time audio as the provider holds it: `started` while audio is attached, `ended` once it ended, omitted while none is. The provider's word — see **`task-audio-started`**. Audio names a task whose work has begun, or whose party the agent application is dialling: on a `pending`, `confirmed` or `preview` task with nobody ringing it is refused (`task.audio.beforeWork`), on a snapshot as on the event, since an agent application opens the microphone on it; with the party ringing by an agent application dial or provider-triggered preview dial, actual ring-back audio may precede answer. |
 | `acceptance` | How this offer is accepted — `no-preference`, `consent`, or `automatic` — stated on the pending task so a reconnect snapshot says it too. Required while `pending` when `autoAcceptTasks` was `true`, forbidden when it was `false`, and absent past `pending`. See **Acceptance modes**. |
+| `expiresInSeconds` | In `pending` only: how long the offer has left, in whole seconds from this publication, restated on every publication that carries it. Absent, the offer stands until the provider says otherwise. See **Pending**. |
 | `previewEndsInSeconds` | Voice only, in `preview`: how long the preparation has left, in whole seconds from this publication, restated on every publication that carries it. Absent, the agent has as long as they need without a preparation countdown. Always with `atDeadline`. See **Preview: the agent presses Call**. |
 | `atDeadline` | Voice only, in `preview`, with `previewEndsInSeconds`: what the system does when it runs out -- `provider-dials` makes the provider initiate dialing, `host-dials` makes the agent application issue Call, `waits` keeps the task in preview awaiting the agent. |
 | `reference` | Optional agent-facing reference such as a case, call, conversation, ticket, or message number. It is distinct from the protocol `id`. |
@@ -2618,18 +2625,26 @@ provider may complete the task without receiving that command.
 **The agent may finish early under either mode.** `complete` is issuable wherever there is a wrap
 to cut short: under `agent-command` it is the end, and under `provider-automatic` it says the agent
 is done before the allowance ran out, and the provider is free to end the task at once. Only a task
-with no wrap at all -- `wrapAllowance: 0` -- has nothing to complete, and the command is refused
-there (`command.complete.wrapAllowance`). An ending the agent asked for says so, `completed` with
-`by: "agent"`, whichever mode the task was under.
+with no wrap at all -- `provider-automatic` with `wrapAllowance: 0` -- has nothing to complete, and
+the command is refused there (`command.complete.wrapAllowance`). An ending the agent asked for says
+so, `completed` with `by: "agent"`, whichever mode the task was under.
 
 **A required outcome is the agent's to give.** A task whose `outcomes` says `required: true` waits
 for a code the agent chooses, so it completes on the agent's command: `provider-automatic` cannot
 wait for it, and the pair is refused (`task.outcomes.required.mode`). Optional outcomes may ride on
 a task the provider completes itself; the agent gives one if in time. And a code is given in wrap,
-so a task with `wrapAllowance: 0` publishes no `outcomes` at all (`task.outcomes.wrapAllowance`).
+so a `provider-automatic` task with `wrapAllowance: 0` publishes no `outcomes` at all
+(`task.outcomes.wrapAllowance`).
+
+**The allowance means one thing per mode.** Under `provider-automatic` it is what the provider
+acts on: the task ends when it runs out. Under `agent-command` it is the expected wrap, stated so
+the agent can see it: the desk counts it down and, past zero, shows how far over they are, and
+nothing acts on it -- the task waits for `complete` however long that takes, with its outcomes
+collected whenever the agent gives them. A provider that would end the task at a time is
+`provider-automatic`.
 
-`wrapAllowance` is independent of that decision. It is fixed, and when it starts depends on
-whether the channel carries real-time audio:
+`wrapAllowance` is fixed, and when it starts depends on whether the channel carries real-time
+audio:
 
 | Channel | Wrap allowance starts at |
 | --- | --- |
@@ -2658,9 +2673,9 @@ const emailCompletion = {
 In this example, the agent has two minutes after sending the email to add notes, select a
 outcome, and complete the task.
 
-`0` means there is no wrap: under `provider-automatic` the provider completes the task at the
-end of the interaction, and under `agent-command` it completes on the interaction's end without
-waiting for `complete`, which has nothing to cut short and is refused.
+`0` means no wrap under `provider-automatic`: the provider completes the task at the end of the
+interaction, and `complete` has nothing to cut short. Under `agent-command` it is an expected wrap
+of nothing -- the desk shows the overrun from the start -- and the task still waits for `complete`.
 
 There is no value meaning "unlimited", because a number that is not a duration would be read as
 one. A provider that imposes no deadline says so by **omitting** `wrapAllowance`, which
@@ -2748,7 +2763,7 @@ The record is the call's, not the task's: most of what it holds happened before
 *Interaction* keeps the one meaning **Terms** gives it, the agent's time on the call, which is why
 the total of earlier agents' time is `interactionSeconds` and the phase rules are
 `command.phase.interaction`. Hosts and providers adopt these names together; no legacy aliases
-are provided. The manifest's `completionSettleMs` bounds final task completion, not entry into
+are provided. The manifest's `settleMs` bounds final task completion, not entry into
 the `completing` wrap-up phase. The `recordStep` method and `complete` command keep their names.
 
 Migration from the earlier spellings:
@@ -2765,7 +2780,7 @@ Migration from the earlier spellings:
 | Task.allocationId, AllocationId, allocationExpiresAt | `Task.assignmentId`, `AssignmentId`, `expiresInSeconds` |
 | Task.id, TaskId, and `taskId` on every event, command, report and lead request | gone: a task is named by `assignmentId` alone, and `assignmentKey(providerId, assignmentId)` scopes it |
 | taskKey, omni.task-not-found, PROVIDER_NAME__TASK_ID__TAB_NAME (ProviderName.TaskId.TabName) | `assignmentKey`, `omni.assignment-not-found`, `PROVIDER_NAME__ASSIGNMENT_ID__TAB_NAME` (`ProviderName.AssignmentId.TabName`) |
-| Manifest.disposalSettleMs | `Manifest.completionSettleMs` |
+| Manifest.disposalSettleMs, Manifest.completionSettleMs | `Manifest.settleMs` (`manifest.settleMs`, `manifest.settleMs.renamed`): the bound after `applied` for `complete` and `schedule` alike |
 | the call command, atDeadline calls and host-calls | `dial`, `"provider-dials"`, `"host-dials"` |
 | media: task-media-started/-ended, team-media-*, Task.media, TaskMediaState, openMedia, OpenMediaRequest/Result, VoiceMediaSession and its session field | audio: `task-audio-started`, `task-audio-ended`, `audio` on the task, `TaskAudioState`, `openAudio`, `OpenAudioRequest`, `OpenAudioResult`, `CallAudio` on the result's `audio`; there is no team audio, the lead's follows `listening` on the member |
 | capabilitySource values ungoverned and undetermined | `nobody`, `not-yet-read` (`capabilitySource.notYetRead`) |
@@ -2777,7 +2792,12 @@ Migration from the earlier spellings:
 | TeamMembers.requests, LeadRequest | `TeamMember.request` (`MemberRequest`): the ask rides on the member (`team.member.request.*`) |
 | team-updated on every change | `team-updated` whole once after the switch and on snapshots; `team-member-updated`, `team-member-removed`, `team-policies-updated` after (`stream.team.baseline`, `stream.teamMember.unknown`) |
 | RecordingCommand.requestId | gone: no request identity; a partial effect is a settled `failed` under `omni.recording-unsettled` |
-| command.complete.mode | `command.complete.wrapAllowance`: `complete` under either mode, refused only with no wrap |
+| command.complete.mode | `command.complete.wrapAllowance`: `complete` under either mode, refused only on `provider-automatic` with no wrap |
+| expiresInSeconds on task-offered | `Task.expiresInSeconds`, in `pending` (`task.pending.expiresInSeconds`, `.unexpected`; `event.taskOffered.expiresInSeconds.unexpected`) |
+| the expired outcome naming preview | gone: nothing expires a preview; withdrawn, it is `cancelled` by the provider |
+| schedule on voice alone | `schedule` on every channel, under a manifest that declares `calendar` (`task.capability.calendar.required`), bounded by `settleMs` (`drive.schedule.unsettled`) |
+| a forced break requesting breaks on the other providers | `setCapacity({ count: 0 })` on every other usable provider (`assertForcedBreakStopsTheRest`) |
+| end-forced-break on a break the platform imposed | refused: `team.command.endForcedBreak.provider`, `omni.break-forced-by-provider` |
 
 Update producers, consumers, saved task snapshots, and validation-rule assertions together.
 History and report rule names use `history` and `historyReport`; assignment rules use
@@ -3377,28 +3397,39 @@ caller to somebody else.
 
 An agent on a call promises to call back on Thursday, or in wrap writes up that the customer wants
 a callback once the refund lands. The follow-up goes on the calendar, and the platform owns the
-calendar: `schedule` asks the provider to put it there.
+calendar: `schedule` asks the provider to put it there. A chat or an email agent promises a
+callback as often, so the control is on every channel.
 
 ```ts
-// From the call, or from its wrap: the time, and a note where the agent wrote one.
+// From the call or the conversation, or from its wrap: the time, and a note where the agent wrote one.
 { type: "schedule", at: "2026-08-28T10:00:00Z", note: "Call back about the refund" }
 ```
 
 `schedule` is gated by the `schedule` capability and issuable in `in-progress`, `paused` or
 `completing` (`command.phase.interaction`): a follow-up is promised on the call and written up in
-wrap alike, and the task names the party it is for. `applied` says the provider has taken it; the
-activity itself arrives on `calendar-updated`, which is the provider's word that it stands, as
-every calendar entry does. The command carries a time and a note and nothing else
+wrap alike, and the task names the party it is for. It lands on the calendar, so a task may offer
+it only under a manifest that declares the `calendar` idle capability
+(`task.capability.calendar.required`), as a control that dials needs `dialOutcomes`; a locked
+`schedule` is still a declared one. The command carries a time and a note and nothing else
 (`command.schedule.at`, `command.schedule.note`, `command.field`): what the platform makes of a
 follow-up -- a campaign record, a reminder, a scheduled dial -- is its own, and the agent sees it
 on the calendar.
 
+**`applied` says the follow-up is on the calendar**, and the `calendar-updated` that shows it
+follows within the manifest's `settleMs`, as a `task-ended` follows an applied `complete`. Past
+the bound the agent application calls `snapshot()`: a calendar carrying an activity at that instant
+clears the wait; one without it shows the follow-up as unsettled -- "Scheduled... the provider has
+not confirmed" -- naming the command. The drive schedules one follow-up where the task offers it,
+at a time it takes from the provider's own publication, and holds the provider to the same bound
+(`drive.schedule.unsettled`).
+
 ### Chat capabilities
 
 | Capability | Omni UI | Contract |
 | --- | --- | --- |
 | `decline` | Pending-task button: Decline | The provider can decline a pending chat offer. Omni shows it only when local policy also permits declining. |
 | `hold` | Primary toggle: Hold | Omni may pause and resume the agent’s interaction in the chat. |
+| `schedule` | Secondary menu item: Schedule | Omni may put a follow-up for this party on the calendar, from the conversation or from its wrap. See **Scheduling a follow-up**. |
 | `outcomes` | Primary button: Complete | Omni may request task completion with a provider outcome and notes. |
 
 ### Email capabilities
@@ -3406,6 +3437,7 @@ on the calendar.
 | Capability | Omni UI | Contract |
 | --- | --- | --- |
 | `decline` | Pending-task button: Decline | The provider can decline a pending email offer. Omni shows it only when local policy also permits declining. |
+| `schedule` | Secondary menu item: Schedule | Omni may put a follow-up for this party on the calendar, from the message or from its wrap. See **Scheduling a follow-up**. |
 | `outcomes` | Primary button: Complete | Omni may request task completion with a provider outcome and notes. |
 
 ### Custom capabilities
@@ -3748,6 +3780,14 @@ entry into `on-break`, excluding any `starting-after-task` wait. Omission means
 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.
 
+**A forced break is the provider's act.** A lead's `force-break` is a command to the provider,
+which forces the break on the member; `by` names the lead who asked it to. A break the platform
+imposed on its own -- a schedule, a compliance hold -- says `by: "provider"`, and is the platform's
+to lift: a lead's `end-forced-break` on it is refused before it is sent
+(`team.command.endForcedBreak.provider`), and a provider that receives one answers `failed` with
+`omni.break-forced-by-provider`. The desk offers End forced break on a member only where
+`forced.by` names a lead.
+
 **A lead lifting the restriction does not resume the agent.** On an applied
 `end-forced-break`, the provider clears `BreakState.forced` while preserving the current
 `on-break` or `starting-after-task` status and `activeReasonId`. This command cannot publish
@@ -3766,14 +3806,21 @@ An agent application may display the expected duration. A countdown requires an
 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.
 
-A break applies to the **agent**, not to one provider. When a provider forces one, Omni immediately
-requests a break on every other connected provider, or they would keep routing work to somebody who
-is not there. On those providers it is the agent's own request, made through `requestBreak` like
-any other, and the provider grants or denies it as its policy says. **The agent application
-guarantees the agent cannot cancel those requests, or end the breaks they become,** while the
-forced break stands: the agent did not ask for them, and a break one provider imposed is not one
-the agent may lift on another. When the forcing provider ends the forced break, the agent
-application ends the follow-on breaks it made. Providers should expect that follow-on request.
+A break applies to the **agent**, not to one provider. When a provider forces one, Omni stops the
+agent everywhere else at once, and not by asking: it states `setCapacity({ count: 0 })` on every
+other usable provider holding capacity, which is taken and never refused, and which their team
+lists show as `elsewhere`. Nobody on those providers can deny it, and the agent cannot cancel it,
+because there is nothing to cancel: a break request on them would be the agent's own to withdraw
+and a lead's to refuse, and a forced break is neither. When the forcing provider ends the forced
+break and the agent resumes there, the agent application restates its capacity on the rest. A
+provider whose login is not usable is left alone, as a break attempt leaves it;
+`assertForcedBreakStopsTheRest` holds an agent application to this set. **The provider keeps its
+shift totals true.** A member held elsewhere is one the provider sees -- `elsewhere` is a state it
+publishes -- and the day's `shift` is its own account of the day, so the time the agent was
+stopped for a break forced on another provider is the provider's to count, as a break of a kind
+its platform has, or introduces, for exactly this. A `breakSeconds` that leaves it out is a total
+the provider knew to be short, and **Never report a value you cannot observe** cuts the other way
+here: the provider observed it.
 
 `ForcedBreak.by` says who forced it: a lead, by user id, or `provider` where the platform itself
 did -- on its own rule, a schedule, a compliance hold. The agent sees who, and `getUserDetails()`
@@ -4241,7 +4288,7 @@ assignment from the member alone.
 | `{ type: "decide-break-request", memberId, decision, reason? }` | Settles one pending request. `decision` is `granted` or `denied`. A grant moves the member to `granted`; a denial ends the request and moves it directly to `not-requested`. |
 | `{ type: "set-break-policy", policy }` | `approval-required`, `automatically-approved`, or `requests-suspended`. |
 | `{ type: "force-break", memberId, reasonId?, reason?, expectedDurationMs? }` | Puts a member on a break they did not ask for. `reasonId` names a published `BreakReason.id` and is required whenever the provider publishes `reasons`; the member's forced break carries it as `activeReasonId`, so its kind is known. Optional `expectedDurationMs` is advisory and is published on the resulting forced break. |
-| `{ type: "end-forced-break", memberId }` | Lifts the forced-break restriction, whoever forced it, by clearing `BreakState.forced`. The committed break continues; only the agent resumes work. |
+| `{ type: "end-forced-break", memberId }` | Asks the provider to lift a forced-break restriction a lead asked for, by clearing `BreakState.forced`; one the platform imposed is its own to lift (`team.command.endForcedBreak.provider`, `omni.break-forced-by-provider`). The committed break continues; only the agent resumes work. |
 | `{ type: "join", memberId, assignmentId? }` | Answers the member's request: the provider bridges the lead's channel into the call. See **Lead assist**. |
 | `{ type: "decline", memberId, assignmentId?, reason? }` | Refuses the member's request. |
 | `{ type: "listen", memberId, assignmentId? }` | The lead's channel joins the member's call unasked, in silence. See **Listening to a call**. |
@@ -4756,9 +4803,9 @@ 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 local policy permitting it. One word for refusing an offer, whatever the channel. |
 | `dial` | The `preview` phase. A record put in front of an agent is there to be called, so the phase is the gate and there is no capability. It is a dial, with a `dialId` and a `dial-outcome`. |
-| `complete` | A wrap to cut short: any task but one with `wrapAllowance: 0`, under either completion mode (`command.complete.wrapAllowance`). The `outcomes` capability decides whether a code travels with the command, never whether the command exists — a task Omni cannot complete never ends. What travels is what the capability published: a code from its list where it has one (`command.complete.outcome.unknown`), a code at all where it requires one (`.outcome.required`), notes as it said (`.notes.required`, `.notes.unexpected`), and neither where the task declares no outcomes (`.outcome.unexpected`). |
+| `complete` | A wrap to cut short: any task but a `provider-automatic` one with `wrapAllowance: 0`, under either completion mode (`command.complete.wrapAllowance`). The `outcomes` capability decides whether a code travels with the command, never whether the command exists — a task Omni cannot complete never ends. What travels is what the capability published: a code from its list where it has one (`command.complete.outcome.unknown`), a code at all where it requires one (`.outcome.required`), notes as it said (`.notes.required`, `.notes.unexpected`), and neither where the task declares no outcomes (`.outcome.unexpected`). |
 | `connect-back` | The `connectBack` capability **and** the `completing` phase. It exists to reach the party again after the call, so it has no meaning while the call is up. |
-| `schedule` | The `schedule` capability, in `in-progress`, `paused` or `completing`: a follow-up is promised on the call and written up in wrap alike. |
+| `schedule` | The `schedule` capability, on any channel, in `in-progress`, `paused` or `completing`: a follow-up is promised on the call and written up in wrap alike. The manifest declares `calendar` for it to land on. |
 | `lead-assist` with `action: "request"` or `"cancel"` | The `leadAssist` capability. `cancel` needs a request standing -- `Task.leadAssist` with status `requested`. |
 | `conference` with `action: "add"` | Its capability, and a `destinationId` the directory offered: the id Omni sends is the id the provider published (`command.destination.unknown`). |
 | `custom` | A control the task published under `capabilities.custom`, by its `id` (`command.capability.custom`), carrying a non-empty string for each `required` prompt field and strings for any optional fields supplied (`command.custom.prompt`). A toggle carries its target `on` boolean (`command.custom.on`). |
@@ -5170,7 +5217,7 @@ take-over as it follows an `end-call` -- see **Lead assist**.
 A successful `complete` command does not clear the task. Omni waits for `task-ended`,
 and not for ever: `applied` to a `complete` says the
 provider has completed the task, and its `task-ended` follows within the
-manifest's `completionSettleMs`. A provider never answers `applied` for a completion it has not yet
+manifest's `settleMs`. A provider never answers `applied` for a completion it has not yet
 performed. Past the bound the agent application calls `snapshot()`: a snapshot still carrying the task is a task
 held open by a provider that said it was done, and the desk shows it as unsettled -- "Completing...
 the provider has not confirmed" -- naming the command; a snapshot no longer carrying it clears the
@@ -5515,6 +5562,7 @@ cannot be established from TypeScript structure alone.
 | `assertBreakFollowsItsRequests(envelopes, snapshot?)` | A break follows its requests: a commit's states only after a grant, never backwards, and a forced break arriving in effect with `forced`. The harness applies the same rules after the connect snapshot. |
 | `assertAudioFollowsTheTask(envelopes, snapshot?)` | The audio follows the task and never decides it: every task is introduced once, `task-audio-started` and `task-audio-ended` alternate on work that has begun, audio ends only where it arrived, and what follows the audio ending is `completing` or `task-ended`. The harness applies the same rules to every event after the connect snapshot (`stream.*`). A sequence with no audio satisfies it by never testing it — pair it with the assertion that the audio end is present. |
 | `assertBreakAttemptProviders(candidates, asked)` | A break attempt asks every usable provider holding capacity, `refreshing` included, and nothing of a provider whose login is `expired`. |
+| `assertForcedBreakStopsTheRest(forcedOn, candidates, stopped)` | A forced break on one provider stops the agent everywhere else: capacity zero stated on every other usable provider holding capacity, nothing on the forcing one, nothing on a dead login. See **Forced breaks**. |
 | `assertBreakBeginsAfterTask(steps)` | A break asked for on a task is committed as `starting-after-task` while work remains and reaches `on-break` only once nothing is outstanding — never beside a task, never later than the step that has none. |
 | `assertDeniedAndRetriedBreak(states)` | A denial transitions directly to `not-requested`; a later request can still be granted. |
 | `assertWrapTimeout(task, audioEndedAt, deadline, toleranceMs?)` | The wrap deadline equals audio end plus the task allowance, within a tolerance that defaults to 1000ms; a task with no allowance has no deadline, and one observed is the violation. |

package/package.json

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