@zq-silk/yui 2.18.0 → 2.19.0

package/dist/commands/controllerCommands.js

@@ -187,6 +187,7 @@ export function parseControllerRuntimeSnapshot(result, droppedEvents) {
             reads: (runtime.reads ?? null),
             persistence: (runtime.persistence ?? null),
             diagnostics: (runtime.diagnostics ?? null),
+            messageHealth: (runtime.messageHealth ?? null),
             scheduler: (runtime.scheduler ?? null),
             preRoutingWait: "unmeasured; event-loop lag is sampled, not per-request queue time",
             clock: "process-monotonic milliseconds; target/request labels are sha256 prefixes"

package/dist/controller/controller.js

@@ -693,6 +693,8 @@ export class FileTaskController {
     #jobSupervisor;
     #schedules;
     #globalInputDelivery;
+    #messageHealth;
+    #lastMessageHealth = null;
     #providerRetry;
     #continuationReconciler;
     #hostTerminalRecovery;
@@ -753,6 +755,7 @@ export class FileTaskController {
         this.#continuationReconciler = options.continuationReconciler;
         this.#hostTerminalRecovery = options.hostTerminalRecovery;
         this.#globalInputDelivery = options.globalInputDelivery;
+        this.#messageHealth = options.messageHealth;
         this.#providerRetry = options.providerRetry;
         this.#signalScheduler = new MailboxScheduler(async (keys) => { await this.#requestPass({ kind: "dirty", keys }); }, {
             windowMs: options.signalWindowMs ?? DEFAULT_SIGNAL_WINDOW_MS,
@@ -789,6 +792,7 @@ export class FileTaskController {
     runtimeMetrics() {
         const metrics = this.#lastRuntimeDrain?.metrics ?? ZERO_DRAIN_METRICS;
         return {
+            messageHealth: this.#lastMessageHealth,
             diagnostics: this.#diagnosticMetrics?.() ?? null,
             phases: this.#phases.snapshot(),
             persistence: this.#persistenceMetrics?.() ?? null,
@@ -1015,6 +1019,12 @@ export class FileTaskController {
                     if (scope.kind === "full" && this.#hostTerminalRecovery !== undefined) {
                         await this.#observeMaintenance("Host terminal recovery", this.#hostTerminalRecovery);
                     }
+                    if (scope.kind === "full" && this.#messageHealth !== undefined) {
+                        // Consume already collected Host evidence, never another live probe.
+                        const health = await this.#observeMaintenance("message-health", () => this.#messageHealth(this.#now()));
+                        if (health !== undefined)
+                            this.#lastMessageHealth = health;
+                    }
                     await this.#phases.observe("provider-retry", "home", () => this.#providerRetry?.reconcile());
                     await this.#phases.observe("global-input", "home", () => this.#globalInputDelivery?.({ reconcile: scope.kind === "full", now: this.#now() }));
                     for (const taskId of runtimeTaskFailureIds(firstRuntimeDrain)) {

package/dist/controller/fileSchedulerStoreAdapter.js

@@ -35,6 +35,7 @@ import { recordTaskAgentError } from "./taskAgentError.js";
 import { recordGlobalRuntimeAttention, recordGlobalRuntimeFailure, recordGlobalRuntimeRecovery } from "./globalRuntimeAttention.js";
 import { checkInboxTurn } from "./inboxTurnCheck.js";
 import { queueOperatorNotification } from "./operatorNotification.js";
+import { reconcileMessageHealth } from "./messageHealth.js";
 import { reconcileProjectSync } from "../job/projectSync.js";
 import { serializeError } from "../core/boundedRpc.js";
 import { claimOperatorAttention } from "../scheduler/operatorEvent.js";
@@ -95,6 +96,9 @@ export class FileSchedulerStoreAdapter {
         this.drivers = drivers;
         this.snapshotExecutionLaneWorkspace = snapshotExecutionLaneWorkspace;
     }
+    reconcileMessageHealth(now, hosts) {
+        return reconcileMessageHealth(this.store, now, hosts);
+    }
     /** Registry maintenance only; this never executes a Job or starts a process. */
     reconcileProjectSync(now) {
         const errors = [];

package/dist/controller/messageHealth.js

@@ -0,0 +1,354 @@
+import { createTaskEvent } from "../event/taskEvent.js";
+import { createGlobalRoleMessage } from "../message/message.js";
+import { hasRuntimeCleanupObligation, runtimeLifecycleTarget } from "../runtime/lifecycleReservation.js";
+import { providerRetryPending } from "../runtime/providerRetry.js";
+import { globalInputBacklog } from "../message/globalInputBacklog.js";
+// These are observation thresholds, not leases or authority to release a writer.
+export const MESSAGE_HEALTH_WARNING_MS = 5 * 60_000;
+export const MESSAGE_HEALTH_CRITICAL_MS = 30 * 60_000;
+const HEADER = "Yui message health v1\n";
+const NOTICE = "operator-notice:message-health:";
+export function classifyMessageHealth(facts, now) {
+    const ageMs = facts.oldestAt === null ? 0 : Math.max(0, +now - Date.parse(facts.oldestAt));
+    const occupancyMs = facts.processingAt === null ? 0 : Math.max(0, +now - Date.parse(facts.processingAt));
+    let state;
+    let reason;
+    if (facts.stopped) {
+        state = "paused";
+        reason = "explicit-stop-pause-or-lifecycle";
+    }
+    else if (facts.count === 0 && facts.handling) {
+        state = "busy";
+        reason = "claimed-input-handling-is-not-delivery-proof";
+    }
+    else if (facts.count === 0 && facts.processingAt === null) {
+        state = "clear";
+        reason = "no-awaiting-delivery";
+    }
+    else if (facts.turnStatus === "accepted" && !facts.blocked) {
+        state = "busy";
+        reason = "accepted-turn-duration-is-not-a-fault";
+    }
+    else if (facts.retryDeadline !== undefined && +now <= Date.parse(facts.retryDeadline)) {
+        state = "recovering";
+        reason = "bounded-provider-retry-owned";
+    }
+    else {
+        reason = facts.retryDeadline !== undefined ? "retry-budget-expired"
+            : facts.blocked ? "retained-delivery-or-processing-barrier"
+                : facts.turnStatus === "delivery-unknown" ? "delivery-uncertain"
+                    : facts.turnStatus === "submitting" ? "submission-unsettled" : "no-delivery-progress";
+        state = Math.max(ageMs, occupancyMs) >= MESSAGE_HEALTH_CRITICAL_MS ? "critical"
+            : Math.max(ageMs, occupancyMs) >= MESSAGE_HEALTH_WARNING_MS ? "warning" : "waiting";
+    }
+    return { state, reason, ageMs, occupancyMs };
+}
+// Display-only shell arguments; guidance never executes these commands.
+function arg(value) {
+    return /^[a-zA-Z0-9_.:/-]+$/.test(value) ? value : `'${value.replaceAll("'", "'\\''")}'`;
+}
+function recoveryGuidance(o) {
+    const { taskId, roleName } = o.target;
+    const owner = taskId === undefined ? "Operator (or the user if Operator itself is unavailable)"
+        : roleName === "leader" ? "Operator; the affected Leader must not synchronously stop itself"
+            : "the authorized Task Leader, or Operator";
+    const retryRead = taskId === undefined ? `yui session retry ${arg(roleName)} show`
+        : `yui task role session retry ${arg(taskId)} ${arg(roleName)} show`;
+    const lines = [
+        `Responsible: ${owner}. Guidance is not authorization and executes nothing.`,
+        `Snapshot ${o.observedAt}; Current state: ${o.state}; reason: ${o.reason}. Refresh yui controller status --verbose --json before acting; an old notice is not a current instruction.`,
+        `Exact target: Session=${o.session ?? "unreported"}, attempt=${o.attemptId ?? "unreported"}, batch=${o.batchId ?? "none"}, wake=${o.wakeId ?? "none"}.`,
+        `Read first: ${[...o.reads, retryRead, ...(o.deliveryEvidence ? [o.deliveryEvidence.read] : [])].join("; ")}.`,
+        "Check current CLI help and reported Host capabilities as the responsible caller. Missing capability, inaccessible evidence or an identity change blocks the proposed action; do not guess another command or target."
+    ];
+    if (o.state === "recovering") {
+        lines.push("Existing bounded retry owns recovery. Observe its exact attempt/deadline; do not duplicate or interrupt it. Escalate its retained failure only if exhausted or needs-attention.");
+    }
+    else if (o.state === "busy" || o.state === "waiting") {
+        lines.push("No intervention is indicated: accepted work or claimed handling can be slow. Inspect actual progress and delivery evidence; silence or a missing ACK is not permission to interrupt.");
+    }
+    else if (o.state === "paused") {
+        lines.push("Respect the deliberate stop/pause, human ownership, matching InputRequest or pending lifecycle cleanup. Inspect that existing obligation; this notice does not authorize resumption or another stop.");
+    }
+    else if (o.state === "clear") {
+        lines.push("Only delivery backlog clearance was observed. No management action is indicated; inspect original inputs and handling before concluding business recovery.");
+    }
+    else if (taskId === undefined) {
+        lines.push("No per-GlobalRole Host-stop command is established by this candidate. Read the original Global Message/control and retry evidence; use current caller capability discovery for a supported targeted lifecycle action. Do not translate Task commands to a GlobalRole or use a stop-all fallback.");
+    }
+    else {
+        const target = `${arg(taskId)} ${arg(roleName)}`;
+        lines.push("Choose only the path matching refreshed evidence, not a stop/replace/retry sequence. Prefer correction plus guarded retry for a proven rejection when sufficient; stop is for an independently established residual Host barrier, and replacement is not the default.");
+        lines.push(`Observed barrier: delivery=${o.deliveryEvidence?.outcome ?? "unreported"}; detail=${o.deliveryEvidence?.detail ?? "unreported"}; Host=${o.hostObservation.state}/${o.hostObservation.reconciliation ?? "unreported"}; retry=${o.retry?.status ?? "unreported"}. These observations do not establish quiescence or prove Goal is the cause; do not clear Goal merely because it says stalled.`);
+        if (o.session !== null && o.blocked) {
+            lines.push(`For confirmed residual Host ownership, the responsible supervisor may consider the existing targeted management path without waiting for a full repair package or every historical projection to align. Template: yui task role session stop ${target} --reason '<verified target, authority and stop rationale>'. First refresh the exact Session/Host identity, native/background work and event persistence; normal busy work, owned retry, intentional pause, unpersisted Host events or unknown cleanup consequences block a routine stop. The CLI captures and fences the current target; this snapshot cannot pin a later invocation.`);
+            lines.push("A stop request being saved is not physical stop. Require the exact Host/resource cleanup result; if cleanup fails or volatile facts remain, retain that process and evidence and escalate the precise boundary, without force-kill or claiming it stopped. After proven stop, let existing authorized delivery/lifecycle reuse the retained conversation when supported; verify the actual native Session identity, never infer reuse from Host ready.");
+            lines.push(`Only if reuse is unsuitable and deliberate replacement is justified, preserve durable progress and use the separately authorized template: yui task role session new ${target} --reason '<why replacement is necessary>'. This requests fresh Session selection after fenced cleanup, not same-conversation reuse. A self-replacing Leader must end its turn. Retained inputs/claims still require inspection, not replay.`);
+        }
+        else {
+            lines.push("A current controlled Session/residual Host barrier is not established. Inspect the missing runtime or Assignment evidence first; no targeted stop is recommended from this snapshot.");
+        }
+        if (o.wakeId !== null && roleName === "leader") {
+            const wakeTarget = `${arg(taskId)} ${arg(o.wakeId)}`;
+            if (o.deliveryEvidence?.outcome === "rejected") {
+                lines.push(`After correcting the rejection cause, and only if this exact wake is still unconsumed, its original claim matches and native acceptance/activity are proven absent: yui task wake retry ${wakeTarget} --reason '<verified correction and quiescence>'. Queued is not accepted. Do not retry accepted/unknown input. This candidate does not establish resolve support for rejected wakes; do not assume another recovery package is installed.`);
+            }
+            else if (o.deliveryEvidence?.outcome === "unknown") {
+                lines.push(`Do not replay unknown input. After exact shared-native/background/writer quiescence and persisted evidence, with the original unknown claim still current: yui task wake resolve ${wakeTarget} --reason '<exact quiescence evidence>'. This releases only scheduling without replay, ACK or acceptance. The rightful handler must inspect original effects and settle still-valid obligations separately.`);
+            }
+            else {
+                lines.push("Deferred, accepted or unreported delivery does not meet this candidate's rejected-retry/unknown-resolve preconditions. Keep the original wake and inspect the runtime barrier instead of mechanically invoking either action.");
+            }
+        }
+    }
+    lines.push("Verify separately: management request saved; exact physical stop if requested; retained conversation reused or explicit replacement recorded; subsequent original wake/message actually accepted by Provider; real handling/progress and remaining obligations. Host ready, pending=0, command success or alert ACK alone proves none of the later stages. If evidence is missing, recovery remains unverified.");
+    lines.push("If an action is refused or fails, retain its exact target, receipt/error, original input and workspace; report the smallest missing capability, authority or cleanup evidence to the responsible supervisor. No private retry loop, forced ACK, queue clearing, raw DB edits, unknown-effect replay, model/account/permission changes or whole-Controller/all-Session restart.");
+    return lines.join("\n");
+}
+function eventType(roleName) { return `message.health.${roleName}`; }
+function prefix(target) { return `${HEADER}${target.roleName}\n`; }
+function noticeId(saved) { return NOTICE + encodeURIComponent(saved.id); }
+function latest(store, target) {
+    if (target.taskId !== undefined) {
+        const event = store.queryContextRecords(target.taskId, { family: "task-event",
+            eventTypes: [eventType(target.roleName)], descending: true, limit: 1 }).records[0]?.value;
+        return event ? { id: `${target.taskId}/${event.id}`,
+            read: `yui task event show ${arg(target.taskId)} ${arg(event.id)}`,
+            evidence: JSON.parse(event.payload.evidence) } : null;
+    }
+    const message = store.queryGlobalRoleMessages(target.roleName, {
+        systemBodyPrefix: prefix(target), descending: true, limit: 1
+    }).messages[0];
+    return message ? { id: `${target.roleName}/${message.id}`,
+        read: `yui role message show ${arg(target.roleName)} ${arg(message.id)}`,
+        evidence: JSON.parse(message.body.slice(prefix(target).length)) } : null;
+}
+function record(store, target, evidence, now) {
+    if (target.taskId !== undefined) {
+        const event = createTaskEvent(store.nextEventId(target.taskId), target.taskId, eventType(target.roleName), { evidence: JSON.stringify(evidence) }, now);
+        store.saveEvent(target.taskId, event);
+        return { id: `${target.taskId}/${event.id}`, read: `yui task event show ${arg(target.taskId)} ${arg(event.id)}`, evidence };
+    }
+    const message = createGlobalRoleMessage(store.nextGlobalRoleMessageId(), target.roleName, prefix(target) + JSON.stringify(evidence), "system", { type: "system" }, now);
+    store.saveGlobalRoleMessage(message);
+    return { id: `${target.roleName}/${message.id}`, read: `yui role message show ${arg(target.roleName)} ${arg(message.id)}`, evidence };
+}
+function alertStatus(store, saved) {
+    if (!saved)
+        return { stage: "not-generated", reason: null, messageId: null };
+    const message = store.queryGlobalRoleMessages("operator", {
+        requestId: noticeId(saved), limit: 1
+    }).messages[0];
+    if (message?.inbox?.ack)
+        return { stage: "handled", reason: null, messageId: message.id };
+    if (message?.delivery)
+        return { stage: message.delivery.via === "provider" ? "delivered" : "transport-accepted",
+            reason: message.delivery.via === "provider" ? null : "provider-acceptance-unconfirmed", messageId: message.id };
+    if (message)
+        return { stage: "saved", messageId: message.id,
+            reason: message.notDelivered?.reason ?? message.control?.outcome
+                ?? (store.getGlobalRole("operator")?.enabled === false ? "operator-disabled"
+                    : globalInputBacklog([message], store.getGlobalRoleSessionSet("operator")).reason) };
+    return { stage: "generated", messageId: null,
+        reason: store.getGlobalRole("operator") === null ? "operator-unconfigured"
+            : operatorAvailable(store) ? "operator-notice-pending" : "operator-unavailable" };
+}
+function operatorAvailable(store) {
+    const sessions = store.getGlobalRoleSessionSet("operator");
+    return sessions?.sessions[sessions.activeAgentId]?.status === "active" && sessions.providerBinding != null;
+}
+/** Same Global Message queue and receipt contract as ordinary Operator notices.
+ * No Task mailbox is involved. A busy/unavailable Operator never loses evidence.
+ * At most one unsent engineering notice; original failed notices are not replayed. */
+function notify(store, saved, observation, now) {
+    if (store.getGlobalRole("operator") === null
+        || !operatorAvailable(store)
+        || store.queryGlobalRoleMessages("operator", { requestId: noticeId(saved), limit: 1 }).count
+        || store.queryGlobalRoleMessages("operator", { pending: true, operatorNotice: true, limit: 1 }).count)
+        return;
+    const { phase } = saved.evidence;
+    const sessions = store.getGlobalRoleSessionSet("operator");
+    const session = sessions.sessions[sessions.activeAgentId];
+    const message = createGlobalRoleMessage(store.nextGlobalRoleMessageId(), "operator", [
+        `Yui-Summary: Message delivery ${observation.state}: ${observation.target.taskId ?? "global"}/${observation.target.roleName} (retained ${phase} evidence).`,
+        `Inspect: ${saved.read}`,
+        `Original diagnostic phase=${phase}, first=${saved.evidence.firstAt}, latest evidence=${saved.evidence.at}; guidance below uses the current observation.`,
+        "Independent diagnostics: yui controller status --verbose --json",
+        `Waiting=${observation.count}, pending=${observation.pendingCount}, processing=${observation.processingCount}, ageMs=${observation.ageMs}, occupancyMs=${observation.occupancyMs}; answered inputs=${observation.answeredInputs.join(", ") || "none observed"}.`,
+        observation.recovery,
+        "Do not ACK business inputs, release unknown writers, replay input, replace Sessions or change models automatically."
+    ].join("\n"), "system", { type: "system" }, now, { inputControl: { action: "queue", requestId: noticeId(saved) } });
+    store.saveGlobalRoleMessage({ ...message,
+        deliveryTarget: { agentId: session.agentId, nativeSessionId: session.nativeSessionId } });
+}
+function oldest(times) {
+    return times.filter((time) => time != null).sort()[0] ?? null;
+}
+function observe(store, target, now, hosts) {
+    const { taskId, roleName } = target;
+    const owner = taskId === undefined ? { scope: "global", roleName }
+        : { scope: "task", taskId, roleName };
+    const task = taskId === undefined ? null : store.getTask(taskId);
+    const role = taskId === undefined ? store.getGlobalRole(roleName) : store.getRole(taskId, roleName);
+    const sessions = taskId === undefined ? store.getGlobalRoleSessionSet(roleName)
+        : store.getTaskRoleSessionSet(taskId, roleName);
+    const session = sessions?.sessions[sessions.activeAgentId];
+    const binding = sessions?.providerBinding;
+    const currentBinding = binding != null && session !== undefined
+        && binding.conversations.some(conversation => conversation.status === "current"
+            && conversation.epoch === binding.currentConversationEpoch && conversation.conversationId === session.nativeSessionId);
+    const turn = currentBinding && binding?.run?.authorityEpoch === binding.authority.epoch ? binding.run : null;
+    const mailbox = taskId === undefined
+        ? roleName === "operator" ? store.getWorkMailbox({ kind: "operator" }) : null
+        : store.getWorkMailbox({ kind: "role", taskId, roleName });
+    const handlingOnly = mailbox?.processing?.owner.startsWith("agent-inbox:") ?? false;
+    const batches = [mailbox?.pending, handlingOnly ? null : mailbox?.processing?.batch].filter(batch => batch != null);
+    const refs = batches.flatMap(batch => [...batch.refs]);
+    const wakeId = mailbox?.processing?.owner.startsWith("leader-notification:")
+        ? mailbox.processing.owner.slice("leader-notification:".length) : null;
+    const wake = wakeId && taskId ? store.getTaskWake(taskId, wakeId) : null;
+    const delivery = taskId && mailbox?.processing ? store.queryContextRecords(taskId, {
+        family: "task-event", eventTypes: ["notification.delivery"],
+        eventAttemptId: mailbox.processing.batchId, descending: true, limit: 1
+    }).records[0]?.value : undefined;
+    // Delivery failures stay visible even when ordinary pending excludes notDelivered.
+    // Handling-only historical receipts never become new queue work.
+    const globalPage = taskId === undefined ? store.queryGlobalRoleMessages(roleName, {
+        awaitingDelivery: true, unclaimed: true, excludeHealthNotices: true, limit: 8
+    }) : null;
+    const handling = handlingOnly || taskId === undefined && store.queryGlobalRoleMessages(roleName, {
+        awaitingDelivery: true, handling: true, excludeHealthNotices: true, limit: 1
+    }).count > 0;
+    const messages = globalPage?.messages ?? [];
+    const taskPage = taskId === undefined ? null : store.queryContextRecords(taskId, {
+        family: "task-message", queuedForRole: roleName, unhandledMessages: true, limit: 8
+    });
+    const taskMessages = taskPage?.records.map(record => record.value) ?? [];
+    const host = hosts.find(item => item.taskId === taskId && item.roleName === roleName
+        && item.attemptId === turn?.attemptId && item.nativeSessionId === session?.nativeSessionId);
+    let hostObservation = host
+        ? { state: host.state, observedAt: host.observedAt, reconciliation: host.reconciliation }
+        : { state: "unobserved", observedAt: null, reconciliation: null };
+    if (taskId === undefined && turn?.status === "accepted") {
+        // Reuse existing Global Host failure evidence, never probe a second time.
+        const failure = store.queryGlobalRoleMessages(roleName, {
+            systemBodyPrefix: "Yui Global failure evidence ", descending: true, limit: 1
+        }).messages[0];
+        if (failure) {
+            const facts = JSON.parse(failure.body.slice(failure.body.indexOf("\n") + 1));
+            if (facts.reason === "host-terminal-unobservable" && facts.attemptId === turn.attemptId
+                && facts.nativeSessionId === session?.nativeSessionId && failure.createdAt >= turn.updatedAt) {
+                hostObservation = { state: typeof facts.hostState === "string" ? facts.hostState : "unobservable",
+                    observedAt: failure.createdAt, reconciliation: facts.cause ?? null };
+            }
+        }
+    }
+    const count = batches.reduce((n, batch) => n + batch.requestCount, 0)
+        + (globalPage?.count ?? 0) + (taskPage?.count ?? 0);
+    const answeredInputs = refs.flatMap(ref => {
+        if (ref.type !== "input")
+            return [];
+        return store.getInputRequest(ref.taskId, ref.id)?.status === "answered" ? [`${ref.taskId}/${ref.id}`] : [];
+    });
+    // Only explicit matching blocked refs constitute a user wait. An unrelated
+    // open InputRequest must not hide an answered input stuck in the same Task.
+    const waitingInputs = taskId === undefined || roleName === "leader" ? [] :
+        store.listOpenInputRequests([taskId]).filter(request => request.blockedRefs.some(ref => ref.type === "run" && refs.some(queued => queued.type === "run" && queued.id === ref.id)
+            || ref.type === "work-item" && taskMessages.some(message => message.recipient?.workItemId === ref.id)))
+            .map(request => request.id);
+    const facts = {
+        count, handling, oldestAt: oldest([...batches.map(batch => batch.firstQueuedAt), globalPage?.oldestCreatedAt,
+            taskMessages[0]?.createdAt]),
+        processingAt: handlingOnly && count === 0 ? null : mailbox?.processing?.startedAt ?? null,
+        blocked: mailbox?.processing != null && wake?.status !== "consumed"
+            && turn?.status !== "accepted"
+            || messages.some(message => message.notDelivered !== undefined
+                || message.control?.outcome === "delivery-unknown" || message.control?.outcome === "pending")
+            || taskMessages.some(message => message.continuation?.notDeliveredReason !== undefined)
+            || ["idle", "failed", "exited", "unobservable"].includes(hostObservation.state)
+                && hostObservation.reconciliation !== "terminal-republished",
+        stopped: role?.enabled === false || session?.endReason === "stopped"
+            || task !== null && (!["active", "draft"].includes(task.status) || task.executionGate.state !== "enabled")
+            || binding?.authority.owner === "human" || binding?.goal?.status === "paused"
+            || waitingInputs.length > 0
+            || hasRuntimeCleanupObligation(store.getWorkMailbox(runtimeLifecycleTarget(owner))),
+        turnStatus: turn?.status,
+        ...(currentBinding && providerRetryPending(binding)
+            && binding.retry.nativeSessionId === session.nativeSessionId
+            && binding.retry.authorityEpoch === binding.authority.epoch ? { retryDeadline: binding.retry.deadline } : {})
+    };
+    const classification = classifyMessageHealth(facts, now);
+    const readBase = taskId ? `yui task role session inspect ${arg(taskId)} ${arg(roleName)}`
+        : `yui config role show ${arg(roleName)}`;
+    const observation = {
+        ...facts, ...classification, target, observedAt: now.toISOString(),
+        session: session?.nativeSessionId ?? null, agentId: session?.agentId ?? null, hostObservation,
+        attemptId: turn?.attemptId ?? null, nativeTurnId: turn?.nativeTurnId ?? null,
+        host: binding?.authority.holderId ?? null, authority: binding?.authority.owner ?? null,
+        retry: binding?.retry ? { status: binding.retry.status, deadline: binding.retry.deadline,
+            attempts: binding.retry.attempts } : null,
+        wakeId, batchId: mailbox?.processing?.batchId ?? null, processingOwner: mailbox?.processing?.owner ?? null,
+        deliveryEvidence: delivery ? { outcome: delivery.payload.outcome ?? "unreported",
+            detail: delivery.payload.detail ?? null,
+            read: `yui task event show ${arg(taskId)} ${arg(delivery.id)}` } : null,
+        pendingCount: (mailbox?.pending?.requestCount ?? 0) + (globalPage?.count ?? 0) + (taskPage?.count ?? 0),
+        processingCount: mailbox?.processing?.batch.requestCount ?? 0,
+        pendingSince: mailbox?.pending?.firstQueuedAt ?? globalPage?.oldestCreatedAt ?? taskMessages[0]?.createdAt ?? null,
+        waitingInputs,
+        refs: [...refs.slice(0, 8), ...messages.map(message => ({
+                messageId: message.id, control: message.control ?? null, notDelivered: message.notDelivered ?? null
+            })), ...taskMessages.map(message => ({
+                messageId: message.id, recipient: message.recipient, continuation: message.continuation ?? null
+            }))], omittedRefs: Math.max(0, refs.length - 8) + Math.max(0, (globalPage?.count ?? 0) - messages.length)
+            + Math.max(0, (taskPage?.count ?? 0) - taskMessages.length),
+        answeredInputs: answeredInputs.slice(0, 8),
+        reads: [readBase, ...(wakeId && taskId ? [`yui task wake show ${arg(taskId)} ${arg(wakeId)}`] : []),
+            ...messages.map(message => `yui role message show ${arg(roleName)} ${arg(message.id)}`),
+            ...taskMessages.map(message => `yui task message show ${arg(`${taskId}/${message.id}`)}`)]
+    };
+    return { ...observation, recovery: recoveryGuidance(observation) };
+}
+/** Low-rate Controller observation, not an Agent loop. All decisions use current
+ * records inside each short transaction; evidence + queue admission are atomic.
+ * Open Event/Message content carries audit facts; no new storage envelope/index
+ * or independently writable scheduler state is introduced. */
+export function reconcileMessageHealth(store, now = new Date(), hosts = []) {
+    const targets = store.listTasks().filter(task => task.status !== "archived").flatMap(task => store.listRoles(task.id).map(role => ({ taskId: task.id, roleName: role.name })));
+    targets.push(...store.listGlobalRoles().map(role => ({ roleName: role.name })));
+    const items = [];
+    for (const target of targets) {
+        store.transaction(tx => {
+            const observation = observe(tx, target, now, hosts);
+            let saved = latest(tx, target);
+            const previous = saved?.evidence;
+            const active = previous !== undefined && previous.phase !== "recovered";
+            const growing = active && observation.state === "warning" && observation.ageMs >= 15 * 60_000
+                && observation.count >= Math.max(8, previous.initialCount * 2);
+            const desired = growing ? "critical" : observation.state;
+            const phase = desired === "warning" || desired === "critical"
+                ? (!active || desired === "critical" && previous.phase === "warning" ? desired : null)
+                : desired === "clear" && active ? "recovered" : null;
+            if (phase !== null) {
+                saved = record(tx, target, {
+                    phase, firstAt: active ? previous.firstAt : now.toISOString(), at: now.toISOString(),
+                    initialCount: active ? previous.initialCount : observation.count,
+                    peakCount: Math.max(active ? previous.peakCount : 0, observation.count),
+                    previous: saved?.id ?? null, observation
+                }, now);
+            }
+            if (saved !== null)
+                notify(tx, saved, observation, now);
+            if (observation.count > 0 || observation.processingAt !== null || saved !== null) {
+                items.push({ ...observation, evidence: saved?.read ?? null, alert: alertStatus(tx, saved),
+                    incident: saved ? { phase: saved.evidence.phase, firstAt: saved.evidence.firstAt,
+                        latestEvidenceAt: saved.evidence.at, initialCount: saved.evidence.initialCount } : null });
+            }
+        });
+    }
+    // Status is an O(1) cached bounded view; exact originals remain independently readable.
+    const priority = (state) => state === "critical" ? 0 : state === "warning" ? 1 : state === "clear" ? 3 : 2;
+    items.sort((a, b) => priority(a.state) - priority(b.state) || b.ageMs - a.ageMs);
+    return { observedAt: now.toISOString(), warningAfterMs: MESSAGE_HEALTH_WARNING_MS,
+        criticalAfterMs: MESSAGE_HEALTH_CRITICAL_MS, total: items.length, omitted: Math.max(0, items.length - 64),
+        items: items.slice(0, 64) };
+}

package/dist/controller/runtime.js

@@ -1,5 +1,6 @@
 import { isDeepStrictEqual } from "node:util";
 import { ControllerDiagnosticJournal } from "./diagnosticJournal.js";
+import { reconcileMessageHealth } from "./messageHealth.js";
 import { monotonicMilliseconds } from "../core/controllerTelemetry.js";
 import { prepareNativeHostSteer } from "./nativeHostInput.js";
 import { archiveLeaderTask } from "../task/leaderArchive.js";
@@ -583,6 +584,7 @@ async function createFileTaskControllerRuntime(home, options) {
         const continuationReconciler = options.continuationMetadata === undefined
             ? undefined
             : new ProviderContinuationReconciliationService(store, schedulerStore, options.continuationMetadata, options.onError);
+        let messageHealthHosts = [];
         const running = await startFileTaskController(home, workerMaintenance
             ? workerSchedulerStore(schedulerStore, asyncStoreClient)
             : schedulerStore, delivery, (method, params) => method === "task.role-capabilities"
@@ -627,7 +629,13 @@ async function createFileTaskControllerRuntime(home, options) {
                 }
             }),
             jobSupervisor,
-            hostTerminalRecovery: () => recoverTaskHostTerminals(home, store, options.onError ?? (() => undefined)),
+            messageHealth: async (now) => workerMaintenance
+                ? await asyncStoreClient.invokeObserver("reconcileMessageHealth", [now, messageHealthHosts])
+                : reconcileMessageHealth(store, now, messageHealthHosts),
+            hostTerminalRecovery: async () => {
+                messageHealthHosts = [];
+                messageHealthHosts = await recoverTaskHostTerminals(home, store, options.onError ?? (() => undefined));
+            },
             globalInputDelivery: (deliveryOptions) => deliverGlobalInputs(home, store, async (roleName) => {
                 await lifecycleDispatcher("runtime.ensure-role-session", { scope: "global", roleName });
             }, options.onError ?? (() => undefined), deliveryOptions),

package/dist/controller/taskHostTerminalRecovery.js

@@ -3,6 +3,7 @@ import { currentProviderConversation } from "../runtime/providerRuntimeIdentity.
 import { providerRetryPending } from "../runtime/providerRetry.js";
 /** Existing full reconciliation pass only; no new timer, input or Session. */
 export async function recoverTaskHostTerminals(home, store, onError, reconcile = reconcileAgentHostTurn) {
+    const observations = [];
     for (const candidate of store.listRuntimeSessionCandidates({ scope: "task" })) {
         const owner = candidate.owner;
         if (owner.scope !== "task")
@@ -20,14 +21,24 @@ export async function recoverTaskHostTerminals(home, store, onError, reconcile =
                     attemptId: turn.attemptId, nativeTurnId: turn.nativeTurnId,
                     authority: { epoch: binding.authority.epoch, owner: "controller", holderId: binding.authority.holderId }
                 } });
+            observations.push({ taskId: owner.taskId, roleName: owner.roleName,
+                nativeSessionId: currentProviderConversation(binding).conversationId, attemptId: turn.attemptId,
+                state: result.snapshot.state, reconciliation: result.reconciliation ?? null,
+                outcome: result.outcome, observedAt: new Date().toISOString() });
             if (result.outcome === "rejected" || result.reconciliation === "unsupported") {
                 throw new Error(result.failure?.detail
                     ?? "Host terminal reconciliation is unsupported; retain the original input and inspect Host/Inbox evidence.");
             }
         }
         catch (error) {
+            if (!observations.some(item => item.taskId === owner.taskId && item.roleName === owner.roleName)) {
+                observations.push({ taskId: owner.taskId, roleName: owner.roleName,
+                    nativeSessionId: currentProviderConversation(binding).conversationId, attemptId: turn.attemptId,
+                    state: "unobservable", reconciliation: null, outcome: "unavailable", observedAt: new Date().toISOString() });
+            }
             onError(new Error(`Task Host terminal recovery ${owner.taskId}/${owner.roleName}/${turn.attemptId}: `
                 + `${error instanceof Error ? error.message : String(error)} No input was replayed.`, { cause: error }));
         }
     }
+    return observations;
 }

package/dist/storage/contextRecords.js

@@ -54,6 +54,22 @@ export function queryContextRecords(db, taskId, query) {
     const from = `${table} r${candidate ? ", json_each(r.payload, '$.candidates') candidate" : ""}`;
     const where = ["r.task_id = @taskId"];
     const params = { taskId };
+    if (query.eventAttemptId !== undefined) {
+        if (query.family !== "task-event")
+            throw new Error("Attempt selection requires Events.");
+        where.push("json_extract(r.payload, '$.payload.attemptId') = @eventAttemptId");
+        params.eventAttemptId = query.eventAttemptId;
+    }
+    if (query.queuedForRole !== undefined) {
+        if (query.family !== "task-message")
+            throw new Error("Queued Role selection requires Messages.");
+        where.push(`json_extract(r.payload, '$.recipient.roleName') = @queuedRole
+      AND json_extract(r.payload, '$.recipient.ownerRunId') IS NOT NULL
+      AND json_extract(r.payload, '$.inbox') IS NULL
+      AND json_extract(r.payload, '$.continuation.runId') IS NULL
+      AND COALESCE(json_extract(r.payload, '$.inputControl.action'), '') != 'steer'`);
+        params.queuedRole = query.queuedForRole;
+    }
     if (query.ids !== undefined) {
         where.push(`${id} IN (SELECT value FROM json_each(@ids))`);
         params.ids = JSON.stringify(query.ids);

package/dist/storage/sqliteStore.js

@@ -1088,6 +1088,22 @@ export class SqliteTaskStore {
         }
         if (query.operatorNotice)
             where.push("json_extract(payload, '$.inputControl.requestId') LIKE 'operator-notice:%'");
+        if (query.awaitingDelivery)
+            where.push(`(json_extract(payload, '$.delivery') IS NULL
+        OR json_extract(payload, '$.delivery.via') = 'transport')
+      AND json_extract(payload, '$.inbox.ack') IS NULL
+      AND json_extract(payload, '$.inbox.retirement') IS NULL
+      AND (json_extract(payload, '$.inputControl.action') = 'queue'
+        OR json_extract(payload, '$.interruptThen') IS NOT NULL
+        OR json_extract(payload, '$.control.outcome') IN ('pending','delivery-unknown'))`);
+        if (query.excludeHealthNotices)
+            where.push("COALESCE(json_extract(payload, '$.inputControl.requestId'), '') NOT LIKE 'operator-notice:message-health:%'");
+        if (query.systemBodyPrefix !== undefined) {
+            where.push(`json_extract(payload, '$.kind') = 'system'
+        AND json_extract(payload, '$.author.type') = 'system'
+        AND substr(json_extract(payload, '$.body'), 1, length(@bodyPrefix)) = @bodyPrefix`);
+            params.bodyPrefix = query.systemBodyPrefix;
+        }
         if (query.afterSequence !== undefined) {
             where.push("seq > @after");
             params.after = query.afterSequence;

package/docs/managed-turn-and-session-runtime.md

@@ -643,3 +643,99 @@ Operator storage diagnosis/upgrade also reaches the dedicated migration entry
 without first requiring the Home to already have the target storage version.
 Completion, cancellation and archive have distinct authority and resource
 boundaries. Storage changes use the single [upgrade contract](sqlite-control-plane-design.md).
+
+## Message delivery health
+
+The Controller's existing full reconciliation observes Task Role notification
+mailboxes, Assignment continuations, Global Role input and the Operator attention
+mailbox. It reads the real `pending` suffix separately from `processing`, never
+the compatibility `getPendingWakeup` projection. It does not run an Agent polling
+loop, acknowledge input, release a claim, resend an uncertain input or start an
+unavailable Operator.
+
+`yui controller status --verbose --json` exposes a cached, timestamped
+`identity.runtime.observations.messageHealth` view (the Controller RPC exposes
+`runtime.messageHealth`). It includes counts, oldest wait/occupancy, exact
+Session/attempt/wake/message references, answered input references, recorded
+delivery outcome, retry ownership and the existing Host reconciliation evidence.
+`unobserved` is not proof of Host health. Inspect its exact Event/Message read
+commands for durable originals. Status reads perform no database scans or probes.
+The view shows at most 64 owners and reports omissions; records remain readable
+through the existing Task event and Global Role message commands after restart.
+
+An eligible stalled delivery warns after 5 minutes and escalates once at
+30 minutes, or after 15 minutes if the queue at least doubles and reaches eight
+items. A single old input is sufficient. Sampling is on the configured full-pass
+interval (default 120 seconds, permitted 5–300 seconds): with a responsive
+Controller, detection occurs on the first completed pass after the threshold.
+These are not wall-clock delivery guarantees during downtime, blocked I/O or
+unavailable Providers. Accepted long Turns without contrary exact Host evidence
+are busy, not faults; explicit stops, disabled Roles, human ownership, native
+pause and matching open input waits are distinct from blocked delivery. Valid
+bounded retry remains owned by its existing recovery mechanism. Historical
+missing ACKs without a new waiting suffix do not generate backlog alerts.
+
+Each affected delivery owner has one open diagnostic episode: at most a warning,
+one escalation and a backlog-clear observation. Concurrent arrivals coalesce;
+they do not each call a model. Task evidence uses ordinary `message.health.<role>`
+Events; Global evidence uses record-only system Messages. These are append-only
+content in the existing open Event/Message formats, not a new storage envelope,
+schema version or scheduling aggregate. The newest evidence reconstructs
+notification deduplication after restart. Each notice reuses the ordinary
+Operator Global Message queue with a stable request ID, independent of the
+affected Task's occupied mailbox. Only one unsent engineering notice is admitted;
+later evidence stays durable and is reconsidered on subsequent full passes.
+
+If Operator is absent/stopped/uncontrolled, evidence remains generated but no
+new Session is started. If it is busy, the notice stays saved; failures retain
+their exact message and reason and are not replayed. Diagnostics distinguish
+generated evidence, saved notice, transport acceptance, Provider delivery and
+explicit handling. An alert ACK is never recovery. Only an observed empty
+delivery backlog closes an episode; an explicit pause or merely releasing the
+old processing claim while a pending suffix remains does not. Backlog clearance
+itself proves neither business handling nor completion, and grants no recovery
+authority. Moving all pending work to a new processing owner is not clearance:
+retained processing with a deferred delivery remains observable, including its
+exact attempt and rejection detail, even when the current Turn is completed.
+
+### Management recovery guidance
+
+Notices include the current observation time, exact identities, original read
+commands and conditional recovery guidance, also available in the cached
+`recovery` field. A notice delayed by Operator unavailability uses current facts
+when it is finally saved, not the original incident's intervention advice.
+Already-saved notices remain immutable evidence and are not resent merely to
+update advice: always refresh status and exact Session/wake/message evidence
+before acting. A command template is neither authorization nor proof that a
+later invocation still targets the observed Session; current CLI fences apply.
+
+An affected Leader is supervised by Operator; a subordinate Task Role by its
+authorized Leader or Operator. Normal busy work, legitimate pause and owned
+bounded retry receive non-intervention guidance. For an established retained
+Task Host barrier, the supervisor may consider the existing targeted
+`task role session stop` path without waiting for a complete engineering repair
+or perfect historical projections. Inspect exact native/background execution,
+event persistence, authority and cleanup consequences first. Unpersisted Host
+facts must not be destroyed. A saved stop request is not successful physical
+cleanup; retain failure evidence when cleanup cannot be proven. Existing
+authorized lifecycle/delivery may reuse the retained conversation after proven
+stop; verify its identity. Deliberate `task role session new` is a different,
+explicit replacement decision, requiring durable progress and fenced cleanup.
+Goal `stalled` alone neither establishes the cause nor warrants clearing Goal.
+
+In this candidate, `task wake retry` requires a proven-rejected, unconsumed
+exact claim, a corrected cause and no accepted/uncertain native execution.
+`task wake resolve` supports an unknown exact claim after shared-native
+quiescence; it releases scheduling without replay or semantic acknowledgement.
+Deferred delivery meets neither precondition. Do not assume another recovery
+package's extended behavior is installed. For Global Roles, this candidate
+does not establish a dedicated targeted Host-stop command: inspect original
+input/control and `session retry <role> show`, then discover current authorized
+capabilities. There is no guessed Task equivalent or stop-all fallback.
+
+On refusal or failure, preserve the exact receipt, original inputs and work,
+and escalate only the missing authority, capability or cleanup evidence.
+Verify management request, physical stop, conversation reuse/replacement,
+actual subsequent Provider acceptance and business handling separately.
+Missing evidence remains unverified; no automatic recovery, replay, forced
+ACK, model/account/permission change or Controller-wide restart is introduced.

package/docs/managed-turn-and-session-runtime.zh-CN.md

@@ -480,3 +480,68 @@ Task。Operator 诊断和 Controller 重启不先要求一个健康的 Controlle
 也能到达专用的迁移入口，而不先要求 Home 已经处于目标存储版本。完成、取消和归档具有
 彼此不同的权限和资源边界。存储变更使用唯一的
 [升级合同](sqlite-control-plane-design.zh-CN.md)。
+
+## 消息投递健康度
+
+Controller 在既有 full reconciliation 中观察 Task Role 通知 mailbox、
+Assignment continuation、Global Role 输入及 Operator attention mailbox。
+分别读取真实 `pending` 后缀与 `processing`，不把 `getPendingWakeup` 的兼容投影
+当作底层队列；不启动 Agent 私有轮询、不自动 ACK、释放占用或重放未知输入。
+
+`yui controller status --verbose --json` 的
+`identity.runtime.observations.messageHealth` 提供带采样时间的缓存诊断；Controller RPC 对应
+`runtime.messageHealth`。可查看数量、最老等待与占用时长、精确 Session/attempt/wake/
+message、已回答输入、投递证据、重试归属与既有 Host 核对结果。`unobserved` 不代表
+Host 健康。按其中的 Event/Message 读取命令核对持久原始证据。状态读取不会扫描数据库
+或发起探测；最多展示 64 个 owner 并显式报告省略数量，重启后原始记录仍可读取。
+
+符合异常条件的投递等待在 5 分钟后预警，30 分钟后最多升级一次；若队列至少翻倍且达到
+8 条，可在 15 分钟后提前升级。仅一条长期不推进的输入也会检测。采样复用 full-pass
+间隔（默认 120 秒，可设 5–300 秒），健康响应的 Controller 在超过阈值后的首次完整
+检查发现；停机、I/O 堵塞和 Provider 不可用期间不保证墙钟时限或即时送达。没有精确
+Host 反证的 accepted 长 Turn 视为忙碌；显式停止、Role 禁用、human 所有权、原生
+暂停、匹配的未回答输入等待单独区分。有效的有界重试仍由既有恢复机制拥有。只有历史
+缺 ACK、没有新待投递后缀，不会生成积压告警。
+
+按受影响的投递 owner 合并一个未关闭异常，最多保存预警、升级和积压消除三个阶段，
+并发到达不会逐条调用模型。Task 使用普通 `message.health.<role>` Event，Global
+使用 record-only system Message，都是既有开放内容格式中的追加证据，不新增存储
+envelope、schema 或调度权威。最新证据用于重启后的去重。告警使用稳定 request ID，
+走独立于受影响 Task 占用的 Operator Global Message 通道；最多保留一条未发送的
+工程通知，其余待告警证据持久保留并在后续 full pass 检查。
+
+Operator 缺席、已停止或没有受控 binding 时，不自动创建 Session；忙碌时保留已保存
+通知，失败时保留原 Message 和原因、不重放。诊断区分已生成证据、已保存通知、传输
+接受、Provider 送达与显式处置。告警 ACK 不关闭异常。只有观察到投递积压消失才记录
+恢复；显式暂停、或仅释放旧 processing 但 pending 仍在，不算恢复。积压消除也不证明
+业务处理完成、Task 验收或获得任何额外恢复权限。
+pending 全部转入新 processing owner 也不算清除：即便当前 Turn 已完成，持续 deferred
+的 processing 仍保留监测及精确 attempt、投递拒绝详情。
+
+### 管理恢复引导
+
+通知直接包含当前观测时间、精确身份、原始读取命令及有前提的恢复引导，缓存诊断的
+`recovery` 字段也提供同一引导。Operator 不可用导致延迟保存的通知使用保存当时的
+当前观测，不复制旧异常的操作建议；已保存通知不重写，也不为更新建议重复发送。
+执行前必须刷新 status 和准确 Session/wake/message 原始证据。命令模板不是授权，
+也不能固定未来调用的目标身份；实际操作仍受现有 CLI 围栏约束。
+
+Leader 自身受阻由 Operator 处理，下属 Task Role 由有权限的 Leader 或 Operator
+处理。正常忙碌、合法暂停、有界重试仍拥有恢复时，不推荐打断。确认 Task Host 遗留
+占用后，可评估已有准确 `task role session stop` 管理路径，不必等待完整工程修复包
+或所有历史投影对齐；先核对准确原生/后台执行、事件持久化、权限和清理影响，不能丢失
+Host 中尚未持久化的事实。stop 请求保存不等于物理清理成功，失败时保留原证据。
+证明停止后，既有授权生命周期/投递可在支持时复用原 conversation，须验证实际身份。
+`task role session new` 则是另行明确选择新 Session，需保存进展并通过清理围栏。
+仅显示 Goal stalled 不能确定根因，也不能据此要求清 Goal。
+
+本候选的 `task wake retry` 仅适用已纠正原因、原准确 claim 仍未消费的明确 rejected，
+且不能存在已接受或不确定原生执行；`task wake resolve` 仅支持准确 unknown claim
+在共享原生静止证明后释放调度，不重放、不 ACK。deferred 不满足二者前提，不能假定
+其他恢复包的扩展行为已经安装。GlobalRole 未确认有专用准确 Host-stop 命令时，读取
+原输入/control 和 `session retry <role> show`，再发现当前权限下的能力；不臆造
+Task 等价命令，也不退化为 stop-all。
+
+动作拒绝或失败后，保留精确回执、原输入和工作区，只升级缺失的权限、能力或清理证据。
+分别验证管理请求、物理停止、原会话复用/显式替换、后续实际 Provider 接受及业务处置；
+缺证据仍标为未验证。不新增自动恢复、重放、强制 ACK、模型/账号/权限变更或全局重启。

package/docs/release-workflow.md

@@ -51,6 +51,26 @@ merely to avoid a version decision. Package versions remain distinct from protoc
 and persistent-storage contracts: their compatibility checks and required migrations
 are unchanged, and the storage rules below do not authorize a package release.
 
+### 2.19.0 compatibility and migration notes
+
+This minor adds message backlog and blocked-delivery monitoring with Operator
+alerts (PR #492). Observations distinguish live work, paused execution and bounded
+retry from stalled delivery, retain original evidence, and deduplicate alerts
+across Controller restarts. Alerts include evidence-matched management guidance:
+inspect the exact input and execution first, distinguish rejected retry from
+unknown-result resolution, and require scoped stop proof or explicit replacement
+authority where applicable. Monitoring never retries, stops or replaces execution
+automatically; an alert is not recovery authority or proof of a unique root cause.
+
+Storage remains **1.24**, and Controller/Host protocols remain v1. Existing
+messages and events are preserved; this release adds no storage migration.
+Older supported Homes still use the centralized contiguous migration chain.
+With separate update authority, the Operator verifies the published artifact
+then runs `yui update --version 2.19.0`. Compatible live Sessions are retained;
+publishing alone does not update the installed program or recover other Tasks.
+Exact-merge Core CI and the same tarball's fresh-install platform/Node matrix
+remain release gates. These checks do not establish real-model behavior.
+
 ### 2.18.0 compatibility and migration notes
 
 This minor includes the already-merged independent Jobs workspace and global

package/docs/release-workflow.zh-CN.md

@@ -36,6 +36,21 @@ Agent 选择一个预先声明的计划，设施从持久状态驱动该计划
 不能将不兼容冒称为兼容，也不为回避版本选择新增历史兼容机制。包版本与协议、
 持久存储契约仍然独立：兼容性检查和必要迁移要求不变，下文存储规则不授予发版权限。
 
+### 2.19.0 兼容性及迁移说明
+
+本 minor 新增消息积压、投递阻塞监测及 Operator 告警（PR #492）。观测区分正常执行、
+暂停、有界重试与投递停滞，保留原始证据，并跨 Controller 重启去重告警。
+告警包含按证据匹配的管理恢复引导：先检查精确输入和执行状态，区分明确拒绝后的
+retry 与未知结果的 resolve，并在需要时要求精确停止证明或显式替换授权。
+监测不会自动重试、停止或替换执行；告警本身不是恢复授权，也不证明唯一根因。
+
+存储仍为 **1.24**，Controller/Host 协议仍为 v1。已有消息与事件保留，本版本
+不新增存储迁移；较早受支持 Home 仍通过集中式连续迁移链升级。
+另行获得更新授权后，由 Operator 核验实际发布包，再执行
+`yui update --version 2.19.0`。兼容的存活 Session 保留；发布本身不更新运行安装，
+也不恢复其他 Task。精确 merge commit 的 Core CI 与同一 tarball 的全新安装
+平台／Node 矩阵仍为发布门禁，这些验证不代表真实模型行为验证。
+
 ### 2.18.0 兼容性及迁移说明
 
 本 minor 包含已合入的独立 Jobs 工作区和全局 Shell 脚本 Job（PR #490），以及

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zq-silk/yui",
-  "version": "2.18.0",
+  "version": "2.19.0",
   "description": "Local control plane for long-running native agent CLI sessions backed by tmux.",
   "license": "MIT",
   "private": false,