@xema/omni-protocol 0.1.93 → 0.1.95

package/dist/index.d.ts

@@ -237,7 +237,7 @@ export interface AuthenticationFailure {
 export interface TeamCapabilities {
     /**
      * This lead may act on their team's breaks through `executeTeamBreak` -- force-break, end-forced-break, decide-break-request,
-     * set policy -- as far as the provider supports; a command it lacks answers
+     * set-break-policy -- as far as the provider supports; a command it lacks answers
      * `omni.capability-not-enabled`. Requires `executeTeamBreak`.
      */
     breakControl?: true;
@@ -1217,13 +1217,13 @@ export type DialResult = {
     status: "failed";
     failure: ProtocolFailure;
 };
-export type BreakApproval = "not-requested"
+export type BreakStatus = "not-requested"
 /** Somebody has to decide. The agent is waiting on a person. */
- | "awaiting-decision"
+ | "awaiting-approval"
 /** Granted, and a promise to honour a later commit. */
  | "granted"
 /** Granted and begins when the current task ends. Nobody needs to act. */
- | "starting-after-task" | "in-effect";
+ | "starting-after-task" | "on-break";
 export declare const BREAK_KINDS: readonly ["short-break", "meal", "rest", "training", "coaching", "meeting", "administrative", "technical", "personal", "other"];
 /**
  * The breaks a contact centre runs, named once so providers can agree.
@@ -1245,38 +1245,29 @@ export interface BreakReason {
     label: string;
     group?: string;
     kind?: BreakKind;
-    /** Survives `mayAsk: false`: a mandatory rest is not something a busy hour can cancel. */
+    /** Survives `canRequestBreak: false`: a mandatory rest is not something a busy hour can cancel. */
     alwaysAvailable?: true;
 }
 export interface BreakRequest {
+    /** Optional explanatory text. Omit when no explanation is needed; separate from reasonId. */
     reason?: string;
     /** The chosen `BreakReason.id`, where the provider publishes codes. */
     reasonId?: string;
 }
-/**
- * A break forced on the agent rather than requested by them.
- *
- * `by` is required in both arms. Who put somebody off the floor survives whether or not the
- * break ends on a clock -- a forced break with no origin is a state the agent cannot reason
- * about, and one that ends on a condition is still somebody's decision.
- */
+/** A break forced on the agent; the agent must explicitly resume when ready. */
 export type ForcedBreak = {
     by: UserId;
-    endsAutomatically: true;
-    endsAt: IsoTimestamp;
-} | {
-    by: UserId;
-    endsAutomatically: false;
-    endsAt?: never;
+    /** Optional expected time on break, in milliseconds from actual start. Advisory only. */
+    expectedDurationMs?: number;
 };
 export interface BreakState {
-    approval: BreakApproval;
+    status: BreakStatus;
     /** Whether the agent may ask at all. Distinct from the fate of a request already made. */
-    mayAsk: boolean;
-    /** Shown when `mayAsk` is false, such as "Busy hours". */
-    refusedReason?: string;
+    canRequestBreak: boolean;
+    /** Shown when `canRequestBreak` is false, such as "Busy hours". */
+    requestUnavailableReason?: string;
     decisionReason?: string;
-    retryAfterMs?: number;
+    retryRequestAfterMs?: number;
     /** Not-ready codes this provider offers. Omitted when it defines none. */
     reasons?: BreakReason[];
     /** Which reason the current break is on, a published `BreakReason.id`. Omitted when there is no break; required on a break in effect or starting after the task where the provider publishes `reasons`, a forced one included. */
@@ -1320,8 +1311,8 @@ export interface TeamMember {
     availability: TeamMemberAvailability;
     /** Omitted rather than invented: Omni renders it as a duration. */
     since?: IsoTimestamp;
-    /** A request in flight or a grant not yet in effect. `not-requested` is absence, and `in-effect` is `availability: "on-break"`. */
-    break?: Extract<BreakApproval, "awaiting-decision" | "granted" | "starting-after-task">;
+    /** A request in flight or a grant not yet in effect. `not-requested` is absence, and `on-break` is `availability: "on-break"`. */
+    break?: Extract<BreakStatus, "awaiting-approval" | "granted" | "starting-after-task">;
 }
 /** A member asking this lead to join their call. */
 export interface LeadRequest {
@@ -1395,16 +1386,19 @@ export type TeamBreakCommand = {
     decision: "granted" | "denied";
     reason?: string;
 } | {
-    type: "policy";
-    policy: "ask" | "auto-approve" | "suspended";
+    type: "set-break-policy";
+    policy: "approval-required" | "automatically-approved" | "requests-suspended";
 }
-/** `reasonId` names a published `BreakReason.id`, required whenever the provider publishes reasons: the member's forced break carries it as `activeReasonId`. */
+/** `reason` text is optional. `reasonId` selects a published `BreakReason.id`, required when reasons are published; the forced break carries it as `activeReasonId`. */
  | {
     type: "force-break";
     memberId: UserId;
     reasonId?: string;
     reason?: string;
-} | {
+    expectedDurationMs?: number;
+}
+/** Clears forced metadata only; preserves the committed break until the agent explicitly resumes. */
+ | {
     type: "end-forced-break";
     memberId: UserId;
 };

package/dist/testing.d.ts

@@ -1,4 +1,4 @@
-import { type Adapter, type AuthenticationState, type ProviderEventEnvelope, type Snapshot, type Task, type TaskCompletion, type BreakApproval, type BrowserSessionKeyInput, type Channel, type ConnectContext, type Host, type HostGuarantees, type HostMute, type LoginStore, type HostReport, type Manifest, type ProviderEvent } from "./index.js";
+import { type Adapter, type AuthenticationState, type ProviderEventEnvelope, type Snapshot, type Task, type TaskCompletion, type BreakStatus, type BrowserSessionKeyInput, type Channel, type ConnectContext, type Host, type HostGuarantees, type HostMute, type LoginStore, type HostReport, type Manifest, type ProviderEvent } from "./index.js";
 import { type ProtocolViolation } from "./validation.js";
 export { ProtocolConformanceError, assertNoViolations, type ProtocolViolation } from "./validation.js";
 /**
@@ -135,11 +135,11 @@ export declare function assertReconnectWithMissedAssignments<C extends Channel>(
  * pending request nobody is coming to decide is worse than none. So the scenario is a request
  * that goes back to not-requested, and a later one that is granted.
  *
- * A request shows as `awaiting-decision` where a person decides, and as `granted` at once where
+ * A request shows as `awaiting-approval` where a person decides, and as `granted` at once where
  * the provider decides alone; either is the request being made, and the rule is the same for
  * both.
  */
-export declare function assertDeniedAndRetriedBreak(approvals: readonly BreakApproval[]): void;
+export declare function assertDeniedAndRetriedBreak(approvals: readonly BreakStatus[]): void;
 /**
  * The event kinds a snapshot restates, and so supersedes when delivered while it is read. Every
  * other kind reports a transaction no snapshot carries, and a host applies it after the snapshot.
@@ -242,13 +242,13 @@ export interface BreakCandidate {
 export declare function assertBreakAttemptProviders(candidates: readonly BreakCandidate[], asked: readonly string[]): void;
 /** One published moment of a break asked for on a task: the approval, and how many tasks were outstanding. */
 export interface BreakOnTaskStep {
-    approval: BreakApproval;
+    approval: BreakStatus;
     outstanding: number;
 }
 /**
  * A break asked for on a task begins when the work ends. `steps` is the sequence the provider
  * published, first to last: the request is made while work is outstanding, the commit is reported
- * as `starting-after-task` while it remains, and `in-effect` arrives only once nothing is
+ * as `starting-after-task` while it remains, and `on-break` arrives only once nothing is
  * outstanding -- never beside a task, and never later than the step that has none.
  */
 export declare function assertBreakBeginsAfterTask(steps: readonly BreakOnTaskStep[]): void;

package/dist/testing.js

@@ -938,22 +938,22 @@ export function assertReconnectWithMissedAssignments(before, reconnect, missedTa
  * pending request nobody is coming to decide is worse than none. So the scenario is a request
  * that goes back to not-requested, and a later one that is granted.
  *
- * A request shows as `awaiting-decision` where a person decides, and as `granted` at once where
+ * A request shows as `awaiting-approval` where a person decides, and as `granted` at once where
  * the provider decides alone; either is the request being made, and the rule is the same for
  * both.
  */
 export function assertDeniedAndRetriedBreak(approvals) {
-    const asked = approvals.findIndex(approval => approval === "awaiting-decision" || approval === "granted");
+    const asked = approvals.findIndex(approval => approval === "awaiting-approval" || approval === "granted");
     if (asked < 0)
         throw new Error("Break retry scenario requires an initial request");
     const refused = approvals.indexOf("not-requested", asked + 1);
     if (refused < 0)
         throw new Error("A refused break must return to not-requested, leaving nothing pending");
-    const granted = approvals.findIndex((approval, index) => index > refused && (approval === "granted" || approval === "in-effect"));
+    const granted = approvals.findIndex((approval, index) => index > refused && (approval === "granted" || approval === "on-break"));
     if (granted < 0)
         throw new Error("Break retry scenario must grant a later request");
     const last = approvals.at(-1);
-    if (last !== "granted" && last !== "in-effect") {
+    if (last !== "granted" && last !== "on-break") {
         throw new Error(`Break retry scenario must end granted or in effect, ended ${String(last)}`);
     }
 }
@@ -1865,9 +1865,10 @@ async function driveOneCall(drive) {
     nothingLate();
     return found;
 }
-// A request goes not-requested -> awaiting-decision | granted; a commit goes granted ->
-// starting-after-task | in-effect; work ending goes starting-after-task -> in-effect; a denial,
-// a cancel, an agent end or a lead end goes back to not-requested; a forced break arrives in-effect
+// A request goes not-requested -> awaiting-approval | granted; a commit goes granted ->
+// starting-after-task | on-break; work ending goes starting-after-task -> on-break; a denial,
+// a cancel or an explicit agent end goes back to not-requested; a lead lifting forced status
+// preserves the committed break. A forced break arrives on-break
 // with `forced`. Nothing else is a move the guide describes.
 /** What a stream has said about the agent's break, and the moves it may not make. */
 export class BreakStream {
@@ -1990,11 +1991,11 @@ export function assertBreakAttemptProviders(candidates, asked) {
 /**
  * A break asked for on a task begins when the work ends. `steps` is the sequence the provider
  * published, first to last: the request is made while work is outstanding, the commit is reported
- * as `starting-after-task` while it remains, and `in-effect` arrives only once nothing is
+ * as `starting-after-task` while it remains, and `on-break` arrives only once nothing is
  * outstanding -- never beside a task, and never later than the step that has none.
  */
 export function assertBreakBeginsAfterTask(steps) {
-    const asked = steps.findIndex(step => step.approval === "awaiting-decision" || step.approval === "granted");
+    const asked = steps.findIndex(step => step.approval === "awaiting-approval" || step.approval === "granted");
     if (asked < 0)
         throw new Error("Break-on-task scenario requires a request");
     if ((steps[asked]?.outstanding ?? 0) < 1)
@@ -2003,14 +2004,14 @@ export function assertBreakBeginsAfterTask(steps) {
     if (committed < 0)
         throw new Error("A break committed on a task is reported as starting-after-task while the work remains");
     steps.forEach((step, index) => {
-        if (step.approval === "in-effect" && step.outstanding > 0) {
-            throw new Error(`steps[${index}] reports in-effect with ${step.outstanding} task(s) outstanding: a break begins when the work ends`);
+        if (step.approval === "on-break" && step.outstanding > 0) {
+            throw new Error(`steps[${index}] reports on-break with ${step.outstanding} task(s) outstanding: a break begins when the work ends`);
         }
         if (step.approval === "starting-after-task" && step.outstanding < 1) {
             throw new Error(`steps[${index}] reports starting-after-task with nothing outstanding: the break should have begun`);
         }
     });
-    if (steps.at(-1)?.approval !== "in-effect") {
+    if (steps.at(-1)?.approval !== "on-break") {
         throw new Error(`Break-on-task scenario must end in effect, ended ${String(steps.at(-1)?.approval)}`);
     }
 }

package/dist/validation.js

@@ -52,7 +52,7 @@ const AUTHENTICATION_STATUSES = membersOf({
     "signed-out": true, authenticating: true, authenticated: true, refreshing: true, expired: true,
 });
 const BREAK_APPROVALS = membersOf({
-    "not-requested": true, "awaiting-decision": true, granted: true, "starting-after-task": true, "in-effect": true,
+    "not-requested": true, "awaiting-approval": true, granted: true, "starting-after-task": true, "on-break": true,
 });
 const TEAM_AVAILABILITIES = membersOf({
     ready: true, "on-task": true, "on-break": true, reserved: true, "signed-out": true,
@@ -80,7 +80,7 @@ const SNAPSHOT_REASONS = membersOf({
 });
 const SESSION_CAPABILITIES = membersOf({ breaks: true, team: true, preferences: true });
 const MEMBER_BREAKS = membersOf({
-    "awaiting-decision": true, granted: true, "starting-after-task": true,
+    "awaiting-approval": true, granted: true, "starting-after-task": true,
 });
 const OFFERABLE_PHASES = membersOf({
     pending: true,
@@ -1298,19 +1298,12 @@ function validateForcedBreak(value, path, into) {
         into.add("break.forced.shape", path, "a forced break must be an object");
         return;
     }
-    // `by` is required either way. Who put somebody off the floor survives whether or not the
-    // break ends on a clock -- a forced break with no origin is a state the agent cannot
-    // reason about.
     into.require(isUserId(value.by), "break.forced.by", `${path}.by`, "a forced break must say who forced it");
-    if (value.endsAutomatically === true) {
-        into.timestamp(value.endsAt, "break.forced.endsAt", `${path}.endsAt`);
-    }
-    else if (value.endsAutomatically === false) {
-        into.require(value.endsAt === undefined, "break.forced.endsAt.unexpected", `${path}.endsAt`, "a break that does not end automatically must not carry an end time");
-    }
-    else {
-        into.add("break.forced.endsAutomatically", `${path}.endsAutomatically`, "a forced break must say whether it ends automatically");
+    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");
 }
 /** Checks break status against the full currently retained task set, after a transaction. */
 export function validateBreakStatus(state, tasks, path = "snapshot") {
@@ -1329,15 +1322,15 @@ export function validateBreakStatus(state, tasks, path = "snapshot") {
     // no task is a break waiting on work that does not exist, and an empty list reading as "still
     // finishing" is the plausible nought.
     ruleEvaluated("break.starting-after-task.tasks");
-    if (isPlainObject(state) && state.approval === "starting-after-task"
+    if (isPlainObject(state) && state.status === "starting-after-task"
         && Array.isArray(tasks) && tasks.length === 0) {
-        into.add("break.starting-after-task.tasks", `${path}.break.approval`, "a break starting after the task waits on a task, and the snapshot carries none: with nothing outstanding the break is in-effect");
+        into.add("break.starting-after-task.tasks", `${path}.break.status`, "a break starting after the task waits on a task, and the snapshot carries none: with nothing outstanding the break is on-break");
     }
-    if (isPlainObject(state) && state.approval === "in-effect"
+    if (isPlainObject(state) && state.status === "on-break"
         && Array.isArray(tasks) && tasks.length > 0) {
         const listening = tasks.every((task) => isPlainObject(task) && task.listening !== undefined);
         if (!listening) {
-            into.add("break.in-effect.tasks", `${path}.tasks`, "a break in effect holds no task: it begins when the work ends, and until then the state is starting-after-task");
+            into.add("break.on-break.tasks", `${path}.tasks`, "a break in effect holds no task: it begins when the work ends, and until then the state is starting-after-task");
         }
         else {
             const reasons = Array.isArray(state.reasons) ? state.reasons : [];
@@ -1366,8 +1359,8 @@ export function validateTeamBreakCommand(request, context, path = "teamBreakComm
     into.require(isPlainObject(caps.team) && caps.team.breakControl === true, "team.break.command.capability", path, "the login must declare team.breakControl");
     const command = request.command;
     const allowed = {
-        "decide-break-request": ["type", "memberId", "decision", "reason"], policy: ["type", "policy"],
-        "force-break": ["type", "memberId", "reasonId", "reason"], "end-forced-break": ["type", "memberId"],
+        "decide-break-request": ["type", "memberId", "decision", "reason"], "set-break-policy": ["type", "policy"],
+        "force-break": ["type", "memberId", "reasonId", "reason", "expectedDurationMs"], "end-forced-break": ["type", "memberId"],
     };
     const fields = typeof command.type === "string" && Object.hasOwn(allowed, command.type) ? allowed[command.type] : undefined;
     if (!fields) {
@@ -1380,8 +1373,8 @@ export function validateTeamBreakCommand(request, context, path = "teamBreakComm
         into.require(fields.includes(key), "team.break.command.field", `${path}.${key}`, "field is not supported for this command");
     if (command.reason !== undefined)
         into.filled(command.reason, "team.break.command.reason", path, "reason must not be empty");
-    if (command.type === "policy") {
-        into.require(["ask", "auto-approve", "suspended"].includes(command.policy), "team.break.command.policy", path, "unknown break policy");
+    if (command.type === "set-break-policy") {
+        into.require(["approval-required", "automatically-approved", "requests-suspended"].includes(command.policy), "team.break.command.policy", path, "unknown break policy");
         return into.violations;
     }
     into.filled(command.memberId, "team.break.command.member", path, "name the target member");
@@ -1392,14 +1385,16 @@ export function validateTeamBreakCommand(request, context, path = "teamBreakComm
     into.require(isPlainObject(member) && command.memberId !== self, "team.break.command.member", path, "the target must be another member of the current authorized team member list");
     if (command.type === "decide-break-request") {
         into.require(command.decision === "granted" || command.decision === "denied", "team.break.command.decision", path, "decide granted or denied");
-        into.require(isPlainObject(member) && member.break === "awaiting-decision", "team.break.command.awaiting", path, "decide only a currently awaiting-decision request");
+        into.require(isPlainObject(member) && member.break === "awaiting-approval", "team.break.command.awaiting", path, "decide only a currently awaiting-approval request");
     }
     else {
         validateBreakState(context.memberBreak, `${path}.memberBreak`, into);
         const state = isPlainObject(context.memberBreak) ? context.memberBreak : {};
         if (command.type === "end-forced-break")
-            into.require(state.forced !== undefined && (state.approval === "in-effect" || state.approval === "starting-after-task"), "team.break.command.endForcedBreak", path, "end a currently forced break");
+            into.require(state.forced !== undefined && (state.status === "on-break" || state.status === "starting-after-task"), "team.break.command.endForcedBreak", path, "lift a current forced-break restriction without resuming the agent");
         if (command.type === "force-break") {
+            if (command.expectedDurationMs !== undefined)
+                into.require(typeof command.expectedDurationMs === "number" && Number.isFinite(command.expectedDurationMs) && command.expectedDurationMs > 0, "team.break.command.expectedDurationMs", `${path}.expectedDurationMs`, "expectedDurationMs must be positive finite milliseconds; it never resumes the agent");
             if (command.reasonId !== undefined)
                 into.filled(command.reasonId, "team.break.command.reasonId", path, "reasonId must not be empty");
             const reasons = Array.isArray(state.reasons) ? state.reasons : [];
@@ -1431,9 +1426,9 @@ export function validateBreakCommand(method, request, state, context, path = "br
     }
     if (!isPlainObject(state) || into.violations.length)
         return into.violations;
-    const approval = state.approval;
+    const status = state.status;
     if (method === "requestBreak") {
-        into.require(approval === "not-requested", "break.command.request.pending", path, "a new request starts only from not-requested");
+        into.require(status === "not-requested", "break.command.request.pending", path, "a new request starts only from not-requested");
         if (!isPlainObject(request)) {
             into.add("break.request.shape", path, "requestBreak takes a request object");
             return into.violations;
@@ -1449,17 +1444,17 @@ export function validateBreakCommand(method, request, state, context, path = "br
             into.require(selected !== undefined, "break.request.reasonId", path, "choose a currently published reasonId; free text is not a substitute");
         else
             into.require(request.reasonId === undefined, "break.request.reasonId.unexpected", path, "no reason codes were published");
-        into.require(state.mayAsk === true || (isPlainObject(selected) && selected.alwaysAvailable === true), "break.request.mayAsk", path, "asking is disabled except for the selected alwaysAvailable reason");
+        into.require(state.canRequestBreak === true || (isPlainObject(selected) && selected.alwaysAvailable === true), "break.request.canRequestBreak", path, "asking is disabled except for the selected alwaysAvailable reason");
     }
     else {
         into.require(request === undefined, "break.command.arguments", path, "this break method takes no arguments");
         if (method === "commitBreak")
-            into.require(approval === "granted" || approval === "starting-after-task" || approval === "in-effect", "break.command.commit.grant", path, "commit requires a grant; repeated committed state is idempotent");
+            into.require(status === "granted" || status === "starting-after-task" || status === "on-break", "break.command.commit.grant", path, "commit requires a grant; repeated committed state is idempotent");
         if (method === "cancelBreak")
-            into.require(approval === "awaiting-decision" || approval === "granted", "break.command.cancel.precommit", path, "cancel only a pre-commit request; a raced commit requires commit recovery");
+            into.require(status === "awaiting-approval" || status === "granted", "break.command.cancel.precommit", path, "cancel only a pre-commit request; a raced commit requires commit recovery");
         if (method === "endBreak") {
-            into.require(approval === "starting-after-task" || approval === "in-effect", "break.command.end.started", path, "end a committed break, including a returning provider still finishing work");
-            into.require(state.forced === undefined, "break.command.end.forced", path, "an agent cannot end a forced break; an authorized lead ends it");
+            into.require(status === "starting-after-task" || status === "on-break", "break.command.end.started", path, "end a committed break, including a returning provider still finishing work");
+            // A forced break also ends only when the agent explicitly resumes.
         }
     }
     return into.violations;
@@ -1477,17 +1472,17 @@ export function validateBreakTransition(before, after, path = "break") {
     validateBreakState(after, `${path}.after`, into);
     if (into.violations.length || !isPlainObject(before) || !isPlainObject(after))
         return into.violations;
-    const from = before.approval;
-    const to = after.approval;
-    const committed = to === "starting-after-task" || to === "in-effect";
-    if (committed && (from === "not-requested" || from === "awaiting-decision") && after.forced === undefined) {
-        into.add("stream.breakState.commitBeforeGrant", `${path}.after.approval`, `${to} follows a commit, and a commit follows granted; the break stood at ${from}`);
-    }
-    const backwards = (from === "in-effect" && (to === "awaiting-decision" || to === "granted" || to === "starting-after-task")) ||
-        (from === "starting-after-task" && (to === "awaiting-decision" || to === "granted")) ||
-        (from === "granted" && to === "awaiting-decision");
+    const from = before.status;
+    const to = after.status;
+    const committed = to === "starting-after-task" || to === "on-break";
+    if (committed && (from === "not-requested" || from === "awaiting-approval") && after.forced === undefined) {
+        into.add("stream.breakState.commitBeforeGrant", `${path}.after.status`, `${to} follows a commit, and a commit follows granted; the break stood at ${from}`);
+    }
+    const backwards = (from === "on-break" && (to === "awaiting-approval" || to === "granted" || to === "starting-after-task")) ||
+        (from === "starting-after-task" && (to === "awaiting-approval" || to === "granted")) ||
+        (from === "granted" && to === "awaiting-approval");
     if (backwards)
-        into.add("stream.breakState.backwards", `${path}.after.approval`, `a break does not go from ${from} back to ${to}; a new request passes through not-requested`);
+        into.add("stream.breakState.backwards", `${path}.after.status`, `a break does not go from ${from} back to ${to}; a new request passes through not-requested`);
     return into.violations;
 }
 function validateBreakState(value, path, into) {
@@ -1496,32 +1491,36 @@ function validateBreakState(value, path, into) {
         return;
     }
     into.require(!Object.hasOwn(value, "imposed"), "break.forced.renamed", `${path}.imposed`, "imposed was renamed to forced; use only forced");
-    into.oneOf(value.approval, BREAK_APPROVALS, "break.approval", `${path}.approval`);
-    into.require(typeof value.mayAsk === "boolean", "break.mayAsk", `${path}.mayAsk`, "mayAsk says whether the agent may ask for a break: a boolean");
-    for (const field of ["refusedReason", "decisionReason"]) {
+    into.require(!Object.hasOwn(value, "approval"), "break.status.renamed", `${path}.approval`, "BreakState.approval was renamed to status; use only status");
+    into.oneOf(value.status, BREAK_APPROVALS, "break.status", `${path}.status`);
+    into.require(!Object.hasOwn(value, "mayAsk"), "break.canRequestBreak.renamed", `${path}.mayAsk`, "mayAsk was renamed to canRequestBreak; use only canRequestBreak");
+    into.require(typeof value.canRequestBreak === "boolean", "break.canRequestBreak", `${path}.canRequestBreak`, "canRequestBreak says whether the agent may ask for a break: a boolean");
+    into.require(!Object.hasOwn(value, "refusedReason"), "break.requestUnavailableReason.renamed", `${path}.refusedReason`, "refusedReason was renamed to requestUnavailableReason; use only requestUnavailableReason");
+    for (const field of ["requestUnavailableReason", "decisionReason"]) {
         if (value[field] !== undefined) {
             into.filled(value[field], `break.${field}`, `${path}.${field}`, `${field} must not be empty when present`);
         }
     }
-    // The refusal is the reason the control is withdrawn; beside `mayAsk: true` it explains nothing.
-    if (value.refusedReason !== undefined) {
-        into.require(value.mayAsk !== true, "break.refusedReason.mayAsk", `${path}.refusedReason`, "refusedReason is shown when mayAsk is false; omit it while the agent may ask");
+    // The refusal is the reason the control is withdrawn; beside `canRequestBreak: true` it explains nothing.
+    if (value.requestUnavailableReason !== undefined) {
+        into.require(value.canRequestBreak !== true, "break.requestUnavailableReason.canRequestBreak", `${path}.requestUnavailableReason`, "requestUnavailableReason is shown when canRequestBreak is false; omit it while the agent may ask");
     }
-    if (value.retryAfterMs !== undefined) {
-        into.require(typeof value.retryAfterMs === "number" && Number.isFinite(value.retryAfterMs) && value.retryAfterMs >= 0, "break.retryAfterMs", `${path}.retryAfterMs`, "retryAfterMs must be a non-negative number when present");
+    into.require(!Object.hasOwn(value, "retryAfterMs"), "break.retryRequestAfterMs.renamed", `${path}.retryAfterMs`, "retryAfterMs was renamed to retryRequestAfterMs on BreakState");
+    if (value.retryRequestAfterMs !== undefined) {
+        into.require(typeof value.retryRequestAfterMs === "number" && Number.isFinite(value.retryRequestAfterMs) && value.retryRequestAfterMs >= 0, "break.retryRequestAfterMs", `${path}.retryRequestAfterMs`, "retryRequestAfterMs must be a non-negative number when present");
     }
     if (value.activeReasonId !== undefined) {
         into.filled(value.activeReasonId, "break.activeReasonId", `${path}.activeReasonId`, "activeReasonId must not be empty when present");
         // A break nobody is on has no reason. Reporting one beside `not-requested` describes a
         // break that is not happening.
-        into.require(value.approval !== "not-requested", "break.activeReasonId.approval", `${path}.activeReasonId`, "activeReasonId must be omitted when no break is requested or in effect");
+        into.require(value.status !== "not-requested", "break.activeReasonId.status", `${path}.activeReasonId`, "activeReasonId must be omitted when no break is requested or in effect");
     }
     if (value.forced !== undefined) {
         validateForcedBreak(value.forced, `${path}.forced`, into);
         // A forced break is a break somebody forced; beside `not-requested` there is no break.
-        // A forced break is a break in progress or about to be: it travels with in-effect or
+        // A forced break is a break in progress or about to be: it travels with on-break or
         // starting-after-task and nothing else. Beside granted, the host would commit a break nobody asked for.
-        into.require(value.approval === "in-effect" || value.approval === "starting-after-task", "break.forced.approval", `${path}.forced`, `a forced break is in effect or starting after the task; ${describeValue(value.approval)} says the agent asked, or that there is none`);
+        into.require(value.status === "on-break" || value.status === "starting-after-task", "break.forced.status", `${path}.forced`, `a forced break is in effect or starting after the task; ${describeValue(value.status)} says the agent asked, or that there is none`);
     }
     if (value.reasons === undefined)
         return;
@@ -1560,8 +1559,8 @@ function validateBreakState(value, path, into) {
     // forced one included, since the lead's force-break command named it. A break of no kind is a break whose
     // rules -- who may listen through it, whether it counts -- nobody can apply.
     ruleEvaluated("break.activeReasonId.required");
-    if (seen.size > 0 && (value.approval === "in-effect" || value.approval === "starting-after-task")) {
-        into.require(typeof value.activeReasonId === "string" && value.activeReasonId.length > 0, "break.activeReasonId.required", `${path}.activeReasonId`, `a break ${describeValue(value.approval)} on a provider that publishes reasons names the one it is on`);
+    if (seen.size > 0 && (value.status === "on-break" || value.status === "starting-after-task")) {
+        into.require(typeof value.activeReasonId === "string" && value.activeReasonId.length > 0, "break.activeReasonId.required", `${path}.activeReasonId`, `a break ${describeValue(value.status)} on a provider that publishes reasons names the one it is on`);
     }
 }
 export function validateTeamMembers(teamMembers, path = "team", context = {}) {
@@ -1652,7 +1651,7 @@ function validateTeamMembersInto(teamMembers, path, context, into) {
         if (member.since !== undefined)
             into.timestamp(member.since, "team.member.since", `${at}.since`);
         if (member.break !== undefined) {
-            // Only an outstanding request appears here: `not-requested` is absence, `in-effect` is
+            // Only an outstanding request appears here: `not-requested` is absence, `on-break` is
             // `availability: "on-break"`, and a denial never survives to be reported.
             if (into.oneOf(member.break, MEMBER_BREAKS, "team.member.break", `${at}.break`)) {
                 into.require(member.availability !== "signed-out" && member.availability !== "on-break", "team.member.break.availability", `${at}.break`, "a member on a break or signed out has no request outstanding");

package/guide.md

@@ -43,9 +43,8 @@ are used precisely throughout and mean nothing looser here.
 | **Listen** | A lead listening to a member's call unasked, from the team member list: `listen` in silence, `coach` heard by the agent alone, `join-call` heard by everyone. Nothing of it reaches the member's task, and there is no take-over in it. See **Listening to a call**. |
 | **On the call** | Who a voice task's audio joins, or is bringing in, as the provider states it on `Task.onCall`: the party, the agents, and anyone consulted or conferenced in from the moment their dial is placed. |
 
-Six words describe *what state a thing is in*, and they are not interchangeable: each belongs to
-one thing, so a bare "status" in conversation is always the authentication session's, and a
-transport, a task, a break and a call each have a word of their own:
+These fields describe state within their containing objects. Both authentication and break
+state use `status`; name the object when discussing them to avoid ambiguity.
 
 | Word | Belongs to | Values |
 | --- | --- | --- |
@@ -53,7 +52,7 @@ transport, a task, a break and a call each have a word of their own:
 | `media` | A task's audio | `started`, `ended` |
 | `transport` | A connection | `connecting`, `active`, `error` |
 | `status` | An authentication session | `signed-out`, `authenticating`, `authenticated`, `refreshing`, `expired` |
-| `approval` | A break request | `not-requested`, `awaiting-decision`, `granted`, `starting-after-task`, `in-effect` |
+| `status` | The agent’s break lifecycle | `not-requested`, `awaiting-approval`, `granted`, `starting-after-task`, `on-break` |
 | `availability` | A team member | `ready`, `on-task`, `on-break`, `signed-out` |
 
 ## Versioning
@@ -929,12 +928,12 @@ keeps a choice about it. See **The station is the host's**.
 ## Breaks
 
 ```ts
-type BreakApproval =
+type BreakStatus =
   | "not-requested"
-  | "awaiting-decision"
+  | "awaiting-approval"
   | "granted"
   | "starting-after-task"
-  | "in-effect";
+  | "on-break";
 
 type BreakReason = {
   id: string;
@@ -949,16 +948,17 @@ type BreakRequest = {
   reasonId?: string;
 };
 
-type ForcedBreak =
-  | { by: UserId; endsAutomatically: true; endsAt: IsoTimestamp }
-  | { by: UserId; endsAutomatically: false; endsAt?: never };
+type ForcedBreak = {
+  by: UserId;
+  expectedDurationMs?: number;
+};
 
 type BreakState = {
-  approval: BreakApproval;
-  mayAsk: boolean;
-  refusedReason?: string;
+  status: BreakStatus;
+  canRequestBreak: boolean;
+  requestUnavailableReason?: string;
   decisionReason?: string;
-  retryAfterMs?: number;
+  retryRequestAfterMs?: number;
   reasons?: BreakReason[];
   activeReasonId?: string;
   forced?: ForcedBreak;
@@ -990,7 +990,7 @@ type TeamMember = {
   id: UserId;
   availability: TeamMemberAvailability;
   since?: IsoTimestamp;
-  break?: Extract<BreakApproval, "awaiting-decision" | "granted" | "starting-after-task">;
+  break?: Extract<BreakStatus, "awaiting-approval" | "granted" | "starting-after-task">;
 };
 
 type LeadRequest = {
@@ -1035,8 +1035,8 @@ type TeamLeadAssistCommand =
 
 type TeamBreakCommand =
   | { type: "decide-break-request"; memberId: UserId; decision: "granted" | "denied"; reason?: string }
-  | { type: "policy"; policy: "ask" | "auto-approve" | "suspended" }
-  | { type: "force-break"; memberId: UserId; reasonId?: string; reason?: string }
+  | { type: "set-break-policy"; policy: "approval-required" | "automatically-approved" | "requests-suspended" }
+  | { type: "force-break"; memberId: UserId; reasonId?: string; reason?: string; expectedDurationMs?: number }
   | { type: "end-forced-break"; memberId: UserId };
 
 type TeamBreakCommandRequest = {
@@ -1924,7 +1924,7 @@ them from what arrives later.
 | --- | --- |
 | `breaks` | This login may request a break. Requires the four break methods on the connection. |
 | `team` | This login leads a team. The provider publishes a `TeamMembers` object to it on every snapshot — `members: []` when nobody is in it — and to nobody else. |
-| `team.breakControl` | This lead may act on their team's breaks through `executeTeamBreak` — force-break, end-forced-break, decide-break-request, set policy — as far as the provider supports; a command it lacks answers `omni.capability-not-enabled`. Omni asks for a decision only against a member whose `break` is `awaiting-decision`, so a provider that grants on request is never asked to decide. Requires `executeTeamBreak`. |
+| `team.breakControl` | This lead may act on their team's breaks through `executeTeamBreak` — force-break, end-forced-break, decide-break-request, set-break-policy — as far as the provider supports; a command it lacks answers `omni.capability-not-enabled`. Omni asks for a decision only against a member whose `break` is `awaiting-approval`, so a provider that grants on request is never asked to decide. Requires `executeTeamBreak`. |
 | `team.leadAssistControl` | This lead may join a member's call on request. Requires `executeTeamLeadAssist`. |
 | `team.listeningControl` | This lead may listen to a member's call unasked, in the listed modes and no others: `listen`, `coach`, `join-call`. The list always includes `listen`, since the other two begin from one. Requires `executeTeamListen`. See **Listening to a call**. |
 | `team.policyControl` | This lead sets the team's policy per capability — on, off, or the person's — within what the queue allows. Requires `executeTeamPolicy`; the team member list carries `policies`. |
@@ -2131,7 +2131,7 @@ 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. |
-| `break` | Complete break state, including approval, whether the agent may ask, reasons, retry details, and any forced break. |
+| `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. |
@@ -3607,45 +3607,88 @@ nothing while none are being accepted — so they are not published separately.
 
 | Field | Contract |
 | --- | --- |
-| `approval` | Where the agent's current request stands. See the states below. |
-| `mayAsk` | Whether the agent may ask at all. Distinct from `approval`. |
-| `refusedReason` | Display-ready reason shown when `mayAsk` is false — a standing gate that applies to everyone. |
+| `status` | Where the agent’s break lifecycle stands. See the states below. |
+| `canRequestBreak` | Whether the agent may ask at all. Distinct from `status`. |
+| `requestUnavailableReason` | Display-ready reason shown when `canRequestBreak` is false — a standing gate that applies to everyone. |
 | `decisionReason` | The words whoever decided attached, from `decide.reason`. About one request and one decision, not a standing gate. |
-| `retryAfterMs` | How long until the agent may retry, when the provider can say. |
+| `retryRequestAfterMs` | Milliseconds until the agent may retry a break request, when the provider can say. |
 | `reasons` | Not-ready codes this provider offers. Omitted when it defines none; an empty list is refused, being a second spelling of the same fact. |
-| `activeReasonId` | The `BreakReason.id` the current break is on. Omitted when there is no break. Required on a break `in-effect` or `starting-after-task` where the provider publishes `reasons`, a forced break included (`break.activeReasonId.required`): a break with a kind the provider cannot name is a break whose rules nobody can apply. |
+| `activeReasonId` | The `BreakReason.id` the current break is on. Omitted when there is no break. Required on a break `on-break` or `starting-after-task` where the provider publishes `reasons`, a forced break included (`break.activeReasonId.required`): a break with a kind the provider cannot name is a break whose rules nobody can apply. |
 | `forced` | Set when the break was forced on the agent rather than requested. |
 
 A request can be waiting for two unrelated things, and they are separate values because
 rendering one as the other tells an agent to wait for somebody who is never coming:
 
-| `approval` | Meaning |
+| `status` | Meaning |
 | --- | --- |
 | `not-requested` | No request outstanding. |
-| `awaiting-decision` | A person has to decide. The agent is waiting on somebody. |
+| `awaiting-approval` | A person has to decide. The agent is waiting on somebody. |
 | `granted` | A person decided yes. Omni may now tell this provider to stop the agent; until it does, work continues normally, and this says nothing about why Omni has not. |
-| `starting-after-task` | Omni has told the provider to stop; the break begins when the current task ends. No new work arrives meanwhile, and nobody needs to act. It waits on a task, so beside no task it is refused (`break.starting-after-task.tasks`): a committed break with nothing outstanding is `in-effect`. |
-| `in-effect` | The agent is on the break now. It holds no task: a break begins when the work ends, so a snapshot reporting `in-effect` beside a task is refused as `break.in-effect.tasks`. The one exception is a lead's listening task during a `coaching`, `administrative` or `training` break -- see **Listening to a call**. |
+| `starting-after-task` | Omni has told the provider to stop; the break begins when the current task ends. No new work arrives meanwhile, and nobody needs to act. It waits on a task, so beside no task it is refused (`break.starting-after-task.tasks`): a committed break with nothing outstanding is `on-break`. |
+| `on-break` | The agent is on the break now. It holds no task: a break begins when the work ends, so a snapshot reporting `on-break` beside a task is refused as `break.on-break.tasks`. The one exception is a lead's listening task during a `coaching`, `administrative` or `training` break -- see **Listening to a call**. |
 
 A denial is a decision, not a standing approval state. The provider transitions the request directly
 to `not-requested`; Omni returns the agent to idle and never asks again on their behalf. They saw the
 answer and ask again when they want to. `decisionReason` may carry the words attached to that
-decision, but `approval` does not remain denied.
+decision, but `status` does not remain denied.
 
 A provider reports `starting-after-task` only after Omni commits a `granted` request while
 work is still active. Omni does not send the request again, because asking again would not move
 it; it sends the commit again only from a reconnect snapshot that shows the grant still standing.
 
-`mayAsk: false` is what lets Omni withdraw the control rather than let an agent ask and be
+`canRequestBreak: false` is what lets Omni withdraw the control rather than let an agent ask and be
 refused. A `BreakReason` marked `alwaysAvailable` survives it: a mandatory rest period is not
 something a busy hour can cancel, and Omni keeps offering those while the rest are withdrawn.
 
 ### Forced breaks
 
+Migration: the former awaiting-decision value is now `awaiting-approval` in break status
+and the team member’s pending break state. The old value is rejected without an alias;
+the request can still be granted or denied, and ordering rules are unchanged.
+
+Migration: the former BreakApproval type is now `BreakStatus`, matching `BreakState.status`.
+The former type is not exported as an alias; its values and behavior are unchanged.
+
+Migration: `BreakState.status` replaces the former approval field. It covers the full break
+lifecycle. The old field is rejected even alongside status; related diagnostics now use status.
+The `BreakStatus` union and its values, `reasons`, `activeReasonId`, and the separate testing
+helper BreakOnTaskStep.approval are unchanged. Hosts and providers must update together.
+
+Migration: the break-state field formerly named retryAfterMs is now `BreakState.retryRequestAfterMs`,
+with diagnostic `break.retryRequestAfterMs`. It remains an optional non-negative finite number
+of milliseconds; the former break field is rejected even alongside the new field.
+The separate authentication and general failure retryAfterMs fields are unchanged.
+
+Migration: the former in-effect break approval value is now `on-break`. It means the
+agent is on the break, not merely granted permission. The old value is rejected without an
+alias. The task prerequisite, supported listening exceptions and ordering rules are unchanged;
+the task-conflict diagnostic is `break.on-break.tasks`. Team member availability already uses
+`on-break` and is unchanged.
+
+Migration: the former refusedReason field is now `BreakState.requestUnavailableReason`.
+It explains why requests are unavailable when `canRequestBreak` is false; `decisionReason`
+continues to explain a particular approval or denial. The old field is rejected even alongside
+the new one, and related diagnostics use requestUnavailableReason.
+
+Migration: the former mayAsk field is now `BreakState.canRequestBreak`. The old field is
+rejected even beside the new field. Validation diagnostics use canRequestBreak in place of
+mayAsk. Request eligibility remains distinct from approval; existing alwaysAvailable reason
+exceptions are unchanged. Hosts and providers must update together.
+
 Migration: ImposedBreak is now `ForcedBreak`, and the former imposed field is now
-`BreakState.forced`. Diagnostic and harness coverage names use `break.forced`; the agent-end
-diagnostic is `break.command.end.forced`. Update hosts and providers together. The old field
+`BreakState.forced`. Diagnostic and harness coverage names use `break.forced`. The former agent-end prohibition
+has been removed: forced breaks also permit explicit agent resumption. Update hosts and providers together. The old field
 is rejected, including when both spellings are sent; no compatibility alias is provided.
+The break policy value formerly named auto-approve is now `automatically-approved`.
+Requests are approved automatically; approval does not skip commitment or the prerequisites
+for starting a break. The former value is rejected without an alias.
+The break policy value formerly named suspended is now `requests-suspended`. The former
+value is rejected without an alias. It suspends new requests, not breaks already underway.
+The break policy value formerly named ask is now `approval-required`: requests require
+approval. The former value is rejected without an alias; automatically-approved and requests-suspended retain
+their existing behavior.
+The team break command formerly named policy is now `set-break-policy`. The former
+command is rejected without an alias; its policy field is unchanged. Hosts and providers must adopt the new name together.
 The team break command formerly named decide is now `decide-break-request`. The former
 spelling is rejected without an alias; the granted/denied decisions and pending-request
 prerequisite are unchanged.
@@ -3653,11 +3696,11 @@ The team break command formerly named place is now `force-break`. Hosts and prov
 adopt the new command together; place and the interim force spelling are rejected without aliases.
 The team break command formerly named release is now `end-forced-break`, and its diagnostic is
 `team.break.command.endForcedBreak`. The former release command and the interim end spelling are rejected without aliases.
-**End a forced break** is a lead action through `executeTeamBreak`; the agent’s `endBreak`
-method still cannot end a forced break. Break ordering and permission rules are unchanged.
+The agent’s `endBreak` now applies to forced breaks as well as requested breaks.
 
-`ForcedBreak` says who forced the break, whether automatic ending is enabled, and, when enabled,
-when the provider will end it. A break the agent did not choose is not manually resumable by them.
+`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
@@ -3667,9 +3710,9 @@ them, not the machinery that carried it out.
 Omni resolves the name to show with `describeUsers()`, so a provider sends the identifier and never
 a display name.
 
-**A forced break travels with `in-effect` or `starting-after-task`, and nothing else.** It is a
-break in progress or about to be; beside `granted` or `awaiting-decision` the host would read a
-request the agent never made and commit it (`break.forced.approval`). Where the provider publishes
+**A forced break travels with `on-break` or `starting-after-task`, and nothing else.** It is a
+break in progress or about to be; beside `granted` or `awaiting-approval` the host would read a
+request the agent never made and commit it (`break.forced.status`). Where the provider publishes
 `reasons`, the lead's `force-break` named one, and the member's state carries it as `activeReasonId`.
 
 For example:
@@ -3677,17 +3720,34 @@ For example:
 ```ts
 forced: {
   by: "manager-1042",
-  endsAutomatically: true,
-  endsAt: "2026-08-21T10:00:00.000Z"
+  expectedDurationMs: 600000
 }
 ```
 
-The presence of `forced` means the agent cannot end the break manually, so Omni withdraws its
-Resume control from that agent. With `endsAutomatically: true`, the provider ends the break at
-`endsAt`; with `endsAutomatically: false`, it does not end the break on a timer. An authorized lead
-may end either form with **Resume**, not only whoever forced it. Omni shows **Stopped by <who>**,
-resolving the name with `describeUsers()`, and shows when the break will end where automatic ending
-is enabled.
+The host keeps **Resume** available for an agent on a forced break. The agent explicitly chooses
+Resume; the host 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 host
+or provider to end the break, restore availability, or route work to the agent.
+
+**A lead lifting the restriction does not resume the agent.** On an applied
+`end-forced-break`, the provider clears `BreakState.forced` while preserving the current
+`on-break` or `starting-after-task` status and `activeReasonId`. This command cannot publish
+`not-requested`, restore readiness, or start routing work. Ordinary progress from
+`starting-after-task` to `on-break` still happens when work finishes. The host follows the
+published state and waits for the agent's explicit Resume, even after reconnect. Historical
+attribution is not rewritten by clearing the current forced marker.
+
+The agent may explicitly resume either before or after the lead lifts the restriction. A lead
+command, timer, late snapshot or reconnect is never a substitute for that choice. Providers
+must correlate resumption to the authenticated agent's action; a state-only ordering validator
+cannot establish the cause of a transition. The usual multi-provider end/reconciliation flow
+still applies, and work resumes only on confirmed provider state.
+
+A host 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.
 
 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
@@ -3771,10 +3831,10 @@ request object only to the request method, and undefined to the other three.
 
 | Method | Required current state |
 | --- | --- |
-| `requestBreak` | `not-requested`; selected current reason code when codes exist; `mayAsk` or the selected reason's `alwaysAvailable` exception. Free text does not replace a code. |
-| `commitBreak` | `granted`, or already committed for an idempotent repeat. A later change to `mayAsk` does not revoke the grant. |
-| `cancelBreak` | `awaiting-decision` or `granted`. A concurrent commit winning still answers `omni.break-already-committed` and requires recovery. |
-| `endBreak` | `in-effect` or `starting-after-task` during reconciliation; an agent cannot end a forced break. |
+| `requestBreak` | `not-requested`; selected current reason code when codes exist; `canRequestBreak` or the selected reason's `alwaysAvailable` exception. Free text does not replace a code. |
+| `commitBreak` | `granted`, or already committed for an idempotent repeat. A later change to `canRequestBreak` does not revoke the grant. |
+| `cancelBreak` | `awaiting-approval` or `granted`. A concurrent commit winning still answers `omni.break-already-committed` and requires recovery. |
+| `endBreak` | `on-break` or `starting-after-task` during reconciliation; the agent may explicitly end a requested or forced break. |
 
 Use `validateTeamBreakCommand(request, context)` for lead decisions, forcing a break, ending a forced break and
 policy commands. It requires the live lead capability and active transport, a current target
@@ -3798,8 +3858,18 @@ required; per-provider validation does not implement the multi-provider coordina
 
 ### `requestBreak(request)`
 
+**Explanatory text is optional.** An agent may omit `BreakRequest.reason` for any break type.
+A lead may likewise omit reason text from `force-break`. Do not require a text explanation
+just because a break is agent-requested or forced. If supplied, text must be nonempty; omit
+it rather than sending an empty string. A selected `reasonId` identifies a published break
+choice and is separate from this optional text.
+
+With published choices, `{ reasonId: "lunch" }` is a valid request without explanation;
+without published choices, `{}` is valid. A lead can similarly send a `force-break` command
+with its member ID and, where required, the selected reason ID, without reason text.
+
 Requests permission to stop the agent later; it does not itself stop work. The provider continues
-offering work and reports `awaiting-decision` or `granted` through `break-state` events. If the request is denied, the
+offering work and reports `awaiting-approval` or `granted` through `break-state` events. If the request is denied, the
 provider reports `not-requested` directly, with `decisionReason` when one was supplied.
 
 **An agent asks from anywhere — idle or on a task** — and Omni offers the request in the task
@@ -3928,22 +3998,22 @@ Omni coordinates one break attempt as follows:
    capacity until then. `refreshing` keeps a provider in — its identity and capabilities remain
    available and work continues. `assertBreakAttemptProviders` holds a host to this set.
 2. Enter `requesting-break`. Keep the agent's normal capacity in place throughout this phase.
-3. Send one `requestBreak` to every asked provider. A provider reports `awaiting-decision` or
+3. Send one `requestBreak` to every asked provider. A provider reports `awaiting-approval` or
    `granted`; neither state stops work. A denial transitions directly to `not-requested` and
    causes Omni to take the cancel path.
 4. If every asked provider reports `granted`, durably choose commit, enter `committing-break`,
    and send `commitBreak()` to each of them. A provider then stops offering new work
-   and reports `starting-after-task` or `in-effect`. The **commit bound** — ten seconds from the
+   and reports `starting-after-task` or `on-break`. The **commit bound** — ten seconds from the
    decision, tunable per deployment — decides who is kept: a provider that has not applied the
    commit by then, still `granted` or unreachable, is set aside as unreconciled and the break
-   begins without it. `in-effect` decides `on-break`: Omni enters it once every kept provider
-   reports `in-effect`. A kept provider reporting `starting-after-task` has applied the commit
+   begins without it. `on-break` decides `on-break`: Omni enters it once every kept provider
+   reports `on-break`. A kept provider reporting `starting-after-task` has applied the commit
    and is finishing a task; the bound is on delivery, not on that task. Omni shows the break as
    settled and beginning when the task ends, and offers no cancel, because the commit is durable.
 5. If any asked provider fails or denies the request, cannot be reconciled within the bounded
    decision timeout, or the agent cancels before commit, durably choose cancel and enter
    `cancelling-break`. Send `cancelBreak()` to every provider still reporting
-   `awaiting-decision` or `granted`. Work continues during cancellation because no stop was
+   `awaiting-approval` or `granted`. Work continues during cancellation because no stop was
    committed. Return to `working` only after no provider retains either state.
 
 Commit and cancel are mutually exclusive decisions for one break attempt. Once Omni chooses commit
@@ -3970,7 +4040,7 @@ Setting a provider aside is not a rollback and not a cancel. The commit stands a
 obligation stands: until that provider is stopped it has not stopped. When it returns it emits a
 snapshot before anything else, and the snapshot decides:
 
-- `in-effect` or `starting-after-task` — the commit arrived after all. Nothing to send.
+- `on-break` or `starting-after-task` — the commit arrived after all. Nothing to send.
 - still `granted` — the commit was lost. Omni sends `commitBreak()` now. If the original turns up
   late behind it, the provider stops an agent who is already stopped; nothing happens, because a
   commit is a state to be in, not an act to be done.
@@ -3983,7 +4053,7 @@ no capacity until it is reconciled.
 
 **If the agent has already ended the break elsewhere, the break attempt is over** and the returning
 provider is reconciled to that instead: still `granted` gets `cancelBreak()`, because committing
-would stop an agent who is working again; `starting-after-task` or `in-effect` gets `endBreak()`.
+would stop an agent who is working again; `starting-after-task` or `on-break` gets `endBreak()`.
 Never rolling back is about a break that is still on, not one the agent has finished.
 
 Omni may tell the agent which platforms the break has not yet reached, as it already does when a
@@ -4013,11 +4083,11 @@ asked for, but only until the session ends — after a reload or reconnect, or w
 the agent on the break itself, the provider is the only one who knows.
 
 Omit it when you cannot say, and when there is no break: reporting a reason alongside
-`approval: "not-requested"` describes a break that is not happening, and is rejected.
+`status: "not-requested"` describes a break that is not happening, and is rejected.
 
 ### `cancelBreak()`
 
-Cancels the active pre-commit request while its approval is `awaiting-decision` or `granted`.
+Cancels the active pre-commit request while its status is `awaiting-approval` or `granted`.
 Cancellation releases the request but does not restore work because work never stopped. If
 commit already won, the provider returns `omni.break-already-committed`. The resulting state is
 reported through `break-state`.
@@ -4026,7 +4096,7 @@ reported through `break-state`.
 
 Commits the `granted` request. Once the provider has reported `granted`, it cannot fail for a
 business reason. On commit the provider stops offering new work and reports
-`starting-after-task` while existing work finishes, or `in-effect` when the break is in effect.
+`starting-after-task` while existing work finishes, or `on-break` when the break is in effect.
 Committing a break that is already in effect changes nothing and answers `committed`.
 
 ### `endBreak()`
@@ -4107,16 +4177,16 @@ One method, `executeTeamBreak`, taking a discriminated command exactly as `execu
 | Command | Effect |
 | --- | --- |
 | `{ type: "decide-break-request", memberId: UserId, 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: "policy", policy }` | `ask`, `auto-approve`, or `suspended`. |
-| `{ type: "force-break", memberId: UserId, reasonId?, reason? }` | 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. |
-| `{ type: "end-forced-break", memberId: UserId }` | Ends a forced break on that member, whoever forced it. |
+| `{ type: "set-break-policy", policy }` | `approval-required`, `automatically-approved`, or `requests-suspended`. |
+| `{ type: "force-break", memberId: UserId, 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: UserId }` | Lifts the forced-break restriction, whoever forced it, by clearing `BreakState.forced`. The committed break continues; only the agent resumes work. |
 
 `memberId` is this provider's own identifier for the member, as published on its team member list. It is
 never an identifier from another provider, and Omni does not translate between them; names come
 from `describeUsers()`.
 
-`suspended` means requests are **rejected outright** rather than left pending — nobody is coming to
-approve them. A provider that suspends breaks must also publish `mayAsk: false` to the team's
+`requests-suspended` means requests are **rejected outright** rather than left pending — nobody is coming to
+approve them. A provider that suspends break requests must also publish `canRequestBreak: false` to the team's
 agents so they see it before asking. A `force-break` must likewise reach that member as a `forced` break
 on their own `BreakState`, or they are stopped from working with no way to see why.
 
@@ -4163,8 +4233,8 @@ they joined -- is answered `failed`, whatever their ceiling; the request stands
 or until it is withdrawn or declined.
 
 **A lead on a break does not join.** A break is a reported state in which the agent is not working,
-and a join is work. Omni offers Join to a lead only while their own `BreakState.approval` is neither
-`starting-after-task` nor `in-effect` -- a committed break waiting for the lead's current work to
+and a join is work. Omni offers Join to a lead only while their own `BreakState.status` is neither
+`starting-after-task` nor `on-break` -- a committed break waiting for the lead's current work to
 finish is not given more -- and a provider answers a `join` from a lead on such a break `failed`.
 The request stands for another lead, as it does when this one is already on a call.
 
@@ -4314,17 +4384,17 @@ about whether anybody has to act on it, and the difference is a lead's entire ac
 
 | `break` | Means |
 | --- | --- |
-| `awaiting-decision` | Somebody has to decide. This is the lead's queue. |
+| `awaiting-approval` | Somebody has to decide. This is the lead's queue. |
 | `granted` | Decided yes, but Omni has not told the provider to stop yet. Work continues and nobody needs to decide. |
 | `starting-after-task` | Already granted; it begins when their current task ends. Nobody needs to act. |
 
 Those three are the only values that appear here. `not-requested` is absence — omit `break`
-instead. `in-effect` is `availability: "on-break"`, and a denial transitions to `not-requested`,
-so neither survives to be reported. It is otherwise the same `BreakApproval` the member's own
+instead. `on-break` is `availability: "on-break"`, and a denial transitions to `not-requested`,
+so neither survives to be reported. It is otherwise the same `BreakStatus` the member's own
 break state uses, rather than a parallel vocabulary for the lead's view, so the two cannot drift
 apart.
 
-Omni offers Approve and Deny only while a member is `awaiting-decision`, shows `granted` as agreed
+Omni offers Approve and Deny only while a member is `awaiting-approval`, shows `granted` as agreed
 but not started, and shows `starting-after-task` as settled.
 
 **Live status, not a record.** The provider derives it from what is true now — not stored, not
@@ -4949,17 +5019,17 @@ covers a `diagnostic`: shown where the agent works, and counted.
 
 ### `break-state`
 
-Replaces this provider's complete `break` object. Its `approval` uses the canonical
-`not-requested`, `awaiting-decision`, `granted`, `starting-after-task` and
-`in-effect` states defined under Breaks; the event also carries the corresponding may-ask state,
+Replaces this provider's complete `break` object. Its `status` uses the canonical
+`not-requested`, `awaiting-approval`, `granted`, `starting-after-task` and
+`on-break` states defined under Breaks; the event also carries the corresponding may-ask state,
 reasons, retry details, and any forced break.
 
 Each state is also held to the one before it. A commit's states, `starting-after-task` and
-`in-effect`, follow a grant — the one arrival in a committed state nobody asked for is a forced
+`on-break`, follow a grant — the one arrival in a committed state nobody asked for is a forced
 break, which says so with `forced`: in effect at once, or `starting-after-task` while the member
 finishes the call they are on (`stream.breakState.commitBeforeGrant`); and a break never moves backwards —
-from `in-effect` or `starting-after-task` to a grant or a request, or from `granted` to
-`awaiting-decision` — a new request passes through `not-requested` (`stream.breakState.backwards`).
+from `on-break` or `starting-after-task` to a grant or a request, or from `granted` to
+`awaiting-approval` — a new request passes through `not-requested` (`stream.breakState.backwards`).
 `exerciseAdapter` holds the stream to that from the connect snapshot on;
 `assertBreakFollowsItsRequests` holds any sequence.
 
@@ -4981,14 +5051,14 @@ provider rechecks current permission and state atomically before acting. The pro
 the resulting break/task state before publication and serializes those publications. The host
 validates the envelope, transition and full task consistency before replacing local state. A
 request result does not optimistically advance break state, and a delayed command cannot apply
-to a later attempt merely because its approval happens to look compatible. Keep at most one
+to a later attempt merely because its status happens to look compatible. Keep at most one
 unresolved operation per provider/attempt; recovery must resolve uncertainty before another
 operation is dispatched. The source must fence delayed operations against its own attempt state.
 
-Normal order is `not-requested` → `awaiting-decision` → `granted` →
-`starting-after-task` → `in-effect` → `not-requested`. Auto-approval may go directly to
-`granted`; a commit with no outstanding work may go directly to `in-effect`. Denial/cancel
-returns a precommit request to `not-requested`; an authorized agent or lead end returns a committed
+Normal order is `not-requested` → `awaiting-approval` → `granted` →
+`starting-after-task` → `on-break` → `not-requested`. Auto-approval may go directly to
+`granted`; a commit with no outstanding work may go directly to `on-break`. Denial/cancel
+returns a precommit request to `not-requested`; an explicit agent end returns a committed
 break there. Same-state restatements are allowed. An evidenced forced break is the explicit
 exception to requesting/granting, and must carry its forced actor/state. Neither skipped
 publication nor a host-local guess creates another exception. A later normal attempt starts
@@ -4998,7 +5068,7 @@ A fresh authoritative snapshot establishes a new baseline; do not run this event
 check across it. A snapshot may legitimately establish a later request or an already active
 break after reconnect. Its freshness must be established by the source/adapter's ordered
 snapshot/publication boundary and fencing of obsolete callbacks and reads. A delayed old
-snapshot is not detectable from break approval alone. Neither envelope time nor event ID
+snapshot is not detectable from break status alone. Neither envelope time nor event ID
 supplies a break revision. Do not suppress all requests after an active break: a later attempt
 passes through `not-requested`, and then may request again. Do not replay earlier ProviderEvents
 after recovery. Raw backend break handlers must preserve source order too; this helper does
@@ -5008,7 +5078,7 @@ not implement or assume invocation of Protocol's two-phase request/commit coordi
 For a multi-provider break attempt, "every provider" is the set of providers frozen when the
 attempt entered `requesting-break`. Omni commits only after every asked provider reports `granted` —
 that one is unconditional, because nothing has stopped yet and waiting costs only time. It enters
-`on-break` once every kept provider reports `in-effect`; the commit bound decides who is kept,
+`on-break` once every kept provider reports `on-break`; the commit bound decides who is kept,
 setting aside a provider that has not applied the commit rather than holding a break that has
 already begun elsewhere. Otherwise it follows the two-phase rules under **Coordinating a
 multi-provider break**.
@@ -5391,7 +5461,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. |
 | `assertMediaFollowsTheTask(envelopes, snapshot?)` | The media follows the task and never decides it: every task is introduced once, `task-media-started` and `task-media-ended` alternate on work that has begun, media ends only where it arrived, and what follows the media ending is `completing` or `task-ended`. The harness applies the same rules to every event after the connect snapshot (`stream.*`). A sequence with no media satisfies it by never testing it — pair it with the assertion that the media 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`. |
-| `assertBreakBeginsAfterTask(steps)` | A break asked for on a task is committed as `starting-after-task` while work remains and reaches `in-effect` only once nothing is outstanding — never beside a task, never later than the step that has none. |
+| `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, mediaEndedAt, deadline, toleranceMs?)` | The wrap deadline equals media 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. |
 | `assertBrowserSessionIsolation(left, right, expected)` | Browser reuse follows only the declared isolation scheme. |

package/package.json

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