@zq-silk/yui 2.18.0 → 2.20.0

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/executor/agentExecutor.js

@@ -111,6 +111,8 @@ export function recordRoleAgentSession(set, input, now) {
         adapterId,
         nativeSessionId,
         ...optionalSessionText("title", input.title ?? continuing?.title),
+        ...((input.generatedTitle ?? continuing?.generatedTitle) === undefined ? {}
+            : { generatedTitle: input.generatedTitle ?? continuing?.generatedTitle }),
         ...optionalSessionText("preview", input.preview ?? continuing?.preview),
         policy: input.policy,
         effective: continuing?.effective ?? effective,
@@ -567,6 +569,11 @@ export function validateRoleAgentSession(session, expectedAgentId = session.agen
         throw new Error(`Role Agent session effective identity is inconsistent: ${agentId}.`);
     }
     requireText(session.nativeSessionId, "Native session id");
+    if (session.generatedTitle !== undefined
+        && (typeof session.generatedTitle !== "string" || session.generatedTitle.length > 80
+            || optionalSessionText("title", session.generatedTitle).title !== session.generatedTitle)) {
+        throw new Error("Role Agent generated title is invalid.");
+    }
     if (session.title !== undefined
         && optionalSessionText("title", session.title).title !== session.title) {
         throw new Error("Role Agent session title is invalid.");

package/dist/executor/fileRoleLaunchPlanner.js

@@ -17,7 +17,7 @@ import { managedRuntimeAdmission } from "../runtime/agentDriver.js";
 import { builtinAgentEndpointImplementation, validateAgentEndpointImplementation } from "../runtime/agentEndpointIdentity.js";
 import { builtinAgentDriverRegistry, builtinDriverIdForAdapter } from "../runtime/builtinAgentDrivers.js";
 import { assertProviderConversationReplaceable } from "../runtime/providerRuntimeIdentity.js";
-import { operatorSessionTitle, resolveTaskRoleSessionTitle } from "../runtime/sessionTitle.js";
+import { globalRoleSessionTitle, resolveTaskRoleSessionTitle } from "../runtime/sessionTitle.js";
 import { parseTaskRuntimeIsolationDescriptor, taskRuntimeIsolationEnvironment } from "../runtime/taskRuntimeIsolation.js";
 import { planningRuntimeCwd } from "../storage/homeLayout.js";
 import { resolveAgentAdapter } from "./agentAdapter.js";
@@ -220,7 +220,11 @@ export class FileRoleLaunchPlanner {
             // attempt was rejected, cancelled, or completed.
             assertProviderConversationReplaceable(sessionSet.providerBinding);
         }
-        return this.#compile(role, input, { scope: "task", taskId: task.id }, resolveTaskRoleSessionTitle(input.mode === "resume" ? existing?.title : undefined, task, role.name), input.mode === "resume" && compatibleExisting ? existing.nativeSessionId : undefined, effective, {
+        return this.#compile(role, input, { scope: "task", taskId: task.id }, resolveTaskRoleSessionTitle(input.mode === "resume" ? existing?.title : undefined, task, role.name, {
+            executionAuthority: (input.mode === "resume" ? existing?.effective : effective)?.executionAuthority,
+            instanceCode: role.instanceCode,
+            generatedTitle: existing?.generatedTitle
+        }), input.mode === "resume" && compatibleExisting ? existing.nativeSessionId : undefined, effective, {
             purpose
         });
     }
@@ -249,9 +253,12 @@ export class FileRoleLaunchPlanner {
         if (input.mode === "new" && sessionSet?.providerBinding != null) {
             assertProviderConversationReplaceable(sessionSet.providerBinding);
         }
-        return this.#compile(role, input, { scope: "global" }, input.mode === "new" && role.name === "operator"
-            ? operatorSessionTitle(this.#now(), this.store.getConfig().timeZone)
-            : undefined, input.mode === "resume" && compatibleExisting ? existing.nativeSessionId : undefined, effective, { purpose: "execution" });
+        return this.#compile(role, input, { scope: "global" }, input.mode === "new"
+            ? globalRoleSessionTitle(role.name, this.#now(), this.store.getConfig().timeZone, role.instanceCode)
+            : existing?.generatedTitle !== undefined && existing.title === existing.generatedTitle
+                ? globalRoleSessionTitle(role.name, new Date(existing.createdAt), this.store.getConfig().timeZone, role.instanceCode)
+                    ?? `Yui ${role.name}`
+                : undefined, input.mode === "resume" && compatibleExisting ? existing.nativeSessionId : undefined, effective, { purpose: "execution" });
     }
     #compile(role, input, owner, sessionTitle, knownNativeSessionId, effective, sessionPolicy) {
         const launchRole = effectiveRoleForLaunch(role, effective);
@@ -385,7 +392,9 @@ export class FileRoleLaunchPlanner {
             agent,
             config: effectiveConfig,
             workspace: agentWorkspace,
-            ...(sessionTitle === undefined || postCreateOperatorTitle
+            // CLI --name has no ownership check on resume. Only the Codex native
+            // metadata path below may rename an existing conversation.
+            ...(sessionTitle === undefined || postCreateOperatorTitle || input.mode === "resume"
                 ? {}
                 : { sessionTitle }),
             ...sessionContext
@@ -510,6 +519,9 @@ export class FileRoleLaunchPlanner {
                 mode: "resume",
                 nativeSessionId: requireText(providerNativeSessionId, "Managed Provider restore native session id"),
                 ...(sessionTitle === undefined ? {} : { sessionTitle }),
+                ...(existingSession?.generatedTitle !== undefined
+                    && existingSession.title === existingSession.generatedTitle
+                    ? { previousSessionTitle: existingSession.generatedTitle } : {}),
                 ...(managedCompiled.codexThread === undefined
                     ? {}
                     : { codexThread: managedCompiled.codexThread }),
@@ -594,6 +606,10 @@ export class FileRoleLaunchPlanner {
             },
             launch: ordinaryConversationLaunch,
             session,
+            ...(sessionTitle !== undefined && (input.mode === "new"
+                || existingSession?.title === undefined
+                || existingSession.title === existingSession.generatedTitle)
+                ? { generatedTitle: sessionTitle } : {}),
             ...(sessionTitle === undefined ? {} : { sessionTitle })
         };
     }

package/dist/output/rolePresentation.js

@@ -54,6 +54,7 @@ export function renderRoleDetails(title, role, input) {
         ...(!isEnabled(role) ? [`  Availability     ${roleDisabledReason(role)}`] : []),
         `  Active Agent     ${role.activeAgentId}`,
         `  Workspace        ${role.workspace}`,
+        `  Instance code    ${role.instanceCode ?? "-"} (display only; next Session launch)`,
         ...("taskId" in role ? [
             `  Desired environment ${role.executionEnvironment === undefined
                 ? "managed workspace"

package/dist/role/instanceCode.js

@@ -0,0 +1,7 @@
+export function validateInstanceCode(value) {
+    if (typeof value !== "string" || value.length === 0 || value.length > 24
+        || !/^[\p{L}\p{N}\p{M}_-]+$/u.test(value)) {
+        throw new Error("Instance code must be 1–24 UTF-16 units of Unicode letters, numbers, marks, '_' or '-'; omit '@'.");
+    }
+    return value;
+}

package/dist/role/role.js

@@ -1,4 +1,5 @@
 import { isDeepStrictEqual } from "node:util";
+import { validateInstanceCode } from "./instanceCode.js";
 import { assertRoleEnabled, validateEnabled } from "./availability.js";
 import { requireKnownFields } from "../domain/validation.js";
 import { jobScopeKey } from "../job/jobDefinition.js";
@@ -49,6 +50,7 @@ export function copyGlobalRoleToTaskRole(globalRole, taskId, now, name = globalR
     const timestamp = now.toISOString();
     return validateTaskRole({
         ...cloneProfile(globalRole),
+        ...(globalRole.instanceCode === undefined ? {} : { instanceCode: globalRole.instanceCode }),
         schemaVersion: 1,
         enabled: true,
         launchRevision: 1,
@@ -75,6 +77,8 @@ export function updateGlobalRole(role, patch, now) {
         updatedAt: now.toISOString()
     };
     clearProfileFields(updated, patch);
+    if (Object.hasOwn(patch, "instanceCode") && patch.instanceCode === undefined)
+        delete updated.instanceCode;
     updated.launchRevision = isDeepStrictEqual(desiredBefore, desiredLaunchProjection(updated))
         ? role.launchRevision
         : role.launchRevision + 1;
@@ -94,6 +98,8 @@ export function updateRole(role, patch, now) {
         updated.executionEnvironment = cloneJson(patch.executionEnvironment);
     }
     clearProfileFields(updated, patch);
+    if (Object.hasOwn(patch, "instanceCode") && patch.instanceCode === undefined)
+        delete updated.instanceCode;
     updated.launchRevision = isDeepStrictEqual(desiredBefore, desiredLaunchProjection(updated))
         ? role.launchRevision
         : role.launchRevision + 1;
@@ -222,6 +228,7 @@ function createRoleOwner(name, bindings, activeAgentId, workspace, now, profile,
     const timestamp = now.toISOString();
     return {
         ...cloneProfile(profile),
+        ...(profile.instanceCode === undefined ? {} : { instanceCode: validateInstanceCode(profile.instanceCode) }),
         enabled: true,
         launchRevision: 1,
         defaultAccess,
@@ -234,6 +241,8 @@ function createRoleOwner(name, bindings, activeAgentId, workspace, now, profile,
     };
 }
 function validateRoleOwner(role) {
+    if (role.instanceCode !== undefined)
+        validateInstanceCode(role.instanceCode);
     validateEnabled(role.enabled);
     if (role.schemaVersion !== 1) {
         throw new Error("Role schema version is invalid.");
@@ -303,6 +312,7 @@ function assertSessionOwnerMatchesRole(role, sessions) {
 }
 function cloneRolePatch(patch) {
     return {
+        ...(patch.instanceCode === undefined ? {} : { instanceCode: validateInstanceCode(patch.instanceCode) }),
         ...(patch.enabled === undefined ? {} : { enabled: patch.enabled }),
         ...(patch.name === undefined ? {} : { name: requireSafeIdentity(patch.name, "Role name") }),
         ...(patch.activeAgentId === undefined

package/dist/runtime/agentEndpoint.js

@@ -81,6 +81,7 @@ class BuiltinAgentEndpoint {
     driver;
     configuration;
     get nativeAccess() { return this.driver.nativeAccess; }
+    get appliedGeneratedTitle() { return this.driver.appliedGeneratedTitle; }
     get ownedProcessId() { return this.driver.ownedProcessId; }
     get nativeAccountHome() { return this.driver.nativeAccountHome; }
     capabilities;

package/dist/runtime/agentHost.js

@@ -120,7 +120,13 @@ export async function runAgentHost(input) {
     const recentSteerAttempts = new Map();
     await replayExitOutbox(input.home);
     const updateSnapshot = (next) => {
-        snapshot = validateSnapshot(next);
+        const { appliedGeneratedTitle: _oldTitle, ...rest } = next;
+        snapshot = validateSnapshot({
+            ...rest,
+            ...(session?.appliedGeneratedTitle === undefined ? {} : {
+                appliedGeneratedTitle: session.appliedGeneratedTitle
+            })
+        });
     };
     const authorityFields = () => ({
         ...(session === undefined ? {} : { endpointImplementation: session.configuration.implementation }),
@@ -374,6 +380,8 @@ export async function runAgentHost(input) {
                         && currentPayload.environment.YUI_ROLE === "operator")
                     ? {}
                     : { sessionTitle: previousControl.sessionTitle }),
+                ...(previousControl.previousSessionTitle === undefined
+                    ? {} : { previousSessionTitle: previousControl.previousSessionTitle }),
                 codexThread: disconnectedSession.configuration.threadOptions,
                 endpointImplementation: disconnectedSession.configuration.implementation,
                 ...(ownedTurn === undefined ? {} : { ownedTurn }),

package/dist/runtime/launchBroker.js

@@ -167,6 +167,9 @@ function validateProviderControl(control) {
             throw new Error("Agent Host Provider session title is invalid.");
         }
     }
+    if (control.previousSessionTitle !== undefined) {
+        text(control.previousSessionTitle, "previousSessionTitle");
+    }
     validateProviderAuthorityFence(control.authority);
 }
 function validateCodexThreadOptions(options) {

package/dist/runtime/runtimeBinding.js

@@ -15,6 +15,9 @@ export function createRuntimeBinding(input) {
         ...(input.nativeSessionId === undefined
             ? {}
             : { nativeSessionId: requireText(input.nativeSessionId, "Native session id") }),
+        ...(input.appliedGeneratedTitle === undefined ? {} : {
+            appliedGeneratedTitle: requireText(input.appliedGeneratedTitle, "Applied generated title")
+        }),
         ...(input.providerAuthority === undefined
             ? {}
             : { providerAuthority: validateProviderAuthorityFence(input.providerAuthority) })

package/dist/runtime/sessionTitle.js

@@ -1,29 +1,33 @@
 import { resolveTimeZone } from "../config/timeZone.js";
+import { validateInstanceCode } from "../role/instanceCode.js";
 const TITLE_SEPARATOR = " · ";
 export const MAX_SESSION_TITLE_LENGTH = 80;
 const TASK_TITLE_MAX_LENGTH = 20;
-export function taskRoleSessionTitle(task, roleName) {
-    const prefix = `Yui ${roleLabel(roleName)} ${normalizeSegment(task.id)}`;
+export function taskRoleSessionTitle(task, roleName, options = {}) {
+    const prefix = `Yui ${roleLabel(roleName)} ${normalizeSegment(task.id)}`
+        + (roleName === "leader" && options.executionAuthority === "planning" ? " Draft" : "")
+        + instanceSegment(options.instanceCode);
     const title = displayTitle(normalizeSegment(task.title), TASK_TITLE_MAX_LENGTH);
     const full = `${prefix}${TITLE_SEPARATOR}${title}`;
     if (full.length <= MAX_SESSION_TITLE_LENGTH)
         return full;
     if (prefix.length + TITLE_SEPARATOR.length + 1 > MAX_SESSION_TITLE_LENGTH) {
-        return truncate(prefix, MAX_SESSION_TITLE_LENGTH);
+        throw new Error("Session title identity exceeds the maximum length; shorten the Role name or instance code.");
     }
-    const titleLength = MAX_SESSION_TITLE_LENGTH - prefix.length - TITLE_SEPARATOR.length - 1;
+    const titleLength = MAX_SESSION_TITLE_LENGTH - prefix.length - TITLE_SEPARATOR.length;
     return `${prefix}${TITLE_SEPARATOR}${displayTitle(title, Math.max(titleLength, 1))}`;
 }
-export function resolveTaskRoleSessionTitle(existingTitle, task, roleName) {
+export function resolveTaskRoleSessionTitle(existingTitle, task, roleName, options = {}) {
     if (existingTitle !== undefined
         && existingTitle.length > 0
         && existingTitle.length <= MAX_SESSION_TITLE_LENGTH
-        && !/[\r\n\0]/u.test(existingTitle)) {
+        && !/[\r\n\0]/u.test(existingTitle)
+        && existingTitle !== options.generatedTitle) {
         return existingTitle;
     }
-    return taskRoleSessionTitle(task, roleName);
+    return taskRoleSessionTitle(task, roleName, options);
 }
-export function operatorSessionTitle(now, configuredTimeZone) {
+export function operatorSessionTitle(now, configuredTimeZone, instanceCode) {
     if (!(now instanceof Date) || !Number.isFinite(now.getTime())) {
         throw new TypeError("Operator session title date is invalid.");
     }
@@ -35,7 +39,23 @@ export function operatorSessionTitle(now, configuredTimeZone) {
     if (parts.month === undefined || parts.day === undefined) {
         throw new TypeError("Operator session title date is unavailable.");
     }
-    return `Yui${TITLE_SEPARATOR}Operator${TITLE_SEPARATOR}${parts.month}${parts.day}`;
+    const prefix = instanceCode === undefined
+        ? `Yui${TITLE_SEPARATOR}Operator`
+        : `Yui Operator${instanceSegment(instanceCode)}`;
+    return `${prefix}${TITLE_SEPARATOR}${parts.month}${parts.day}`;
+}
+export function globalRoleSessionTitle(roleName, now, configuredTimeZone, instanceCode) {
+    if (roleName === "operator")
+        return operatorSessionTitle(now, configuredTimeZone, instanceCode);
+    if (instanceCode === undefined)
+        return undefined;
+    const title = `Yui ${roleLabel(roleName)}${instanceSegment(instanceCode)}`;
+    if (title.length > MAX_SESSION_TITLE_LENGTH)
+        throw new Error("Session title identity exceeds the maximum length.");
+    return title;
+}
+function instanceSegment(value) {
+    return value === undefined ? "" : ` @${validateInstanceCode(value)}`;
 }
 function displayTitle(value, maxLength) {
     if (value.length <= maxLength)

package/dist/runtime/structuredProviderHost.js

@@ -384,6 +384,7 @@ class CodexStructuredProviderSession {
     onActivity;
     mirror;
     nativeAccountHome;
+    appliedGeneratedTitle;
     nativeAccess;
     #turnAttempts = new Map();
     adapterId = "codex";
@@ -445,12 +446,20 @@ class CodexStructuredProviderSession {
                 throw error;
             }
         }
-        if (control.sessionTitle !== undefined) {
+        const threadMetadata = nativeConfiguration.thread;
+        const nativeTitle = typeof threadMetadata === "object" && threadMetadata !== null
+            && !Array.isArray(threadMetadata) ? threadMetadata.name : undefined;
+        // A native rename belongs to the user. Missing metadata is not evidence
+        // that an old title is still ours; leave it alone on resume.
+        let appliedGeneratedTitle;
+        if (control.sessionTitle !== undefined && (control.mode === "new"
+            || (control.previousSessionTitle !== undefined && nativeTitle === control.previousSessionTitle))) {
             try {
                 await runtime.setConversationName({
                     conversationId,
                     name: control.sessionTitle
                 });
+                appliedGeneratedTitle = control.sessionTitle;
             }
             catch (error) {
                 onDiagnostic?.({
@@ -465,6 +474,7 @@ class CodexStructuredProviderSession {
         }
         const session = new CodexStructuredProviderSession(child, exit, processInstanceId, conversationId, runtime, onStarted, onTerminal, onGoal, onInput, onActivity, mirror, optionalId(initialized.codexHome));
         session.nativeAccess = createCodexNativeAccess(conversationId, initialized, channel, openingMessages, nativeConfiguration);
+        session.appliedGeneratedTitle = appliedGeneratedTitle;
         session.#activeTurnId = resumedActiveTurnId;
         const ownedTurn = control.kind === "restore" ? control.ownedTurn : undefined;
         session.#clientOwnedTurnId = ownedTurn?.turnId;

package/dist/runtime/tmuxAdapters.js

@@ -246,6 +246,7 @@ export class TmuxSessionHost {
             agentId: request.agentId,
             adapterId: request.adapterId,
             effective: request.effective,
+            ...(planned.generatedTitle === undefined ? {} : { generatedTitle: planned.generatedTitle }),
             ...(planned.launch.env.YUI_SESSION_TITLE === undefined
                 ? {}
                 : { sessionTitle: planned.launch.env.YUI_SESSION_TITLE }),
@@ -436,6 +437,9 @@ export class TmuxSessionHost {
                 roleName: request.owner.roleName
             }),
             hostCreated,
+            ...(providerSnapshot?.appliedGeneratedTitle === undefined ? {} : {
+                appliedGeneratedTitle: providerSnapshot.appliedGeneratedTitle
+            }),
             ...((providerSnapshot?.nativeSessionId ?? nativeSessionId) === undefined
                 ? {}
                 : { nativeSessionId: providerSnapshot?.nativeSessionId ?? nativeSessionId }),

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/sqliteSchema.js

@@ -276,6 +276,16 @@ const MINOR_UPGRADES = Object.freeze([{
         // No payload rewriting or historical revision invention. A newly opened
         // reader starts empty; zero is the initial token until the first mutation.
         sql: TASK_READ_REVISION_SCHEMA_SQL
+    }, {
+        fromVersion: "1.24",
+        toVersion: "1.25",
+        name: "role-instance-code-session-titles",
+        introducedIn: "next",
+        sourceChecksum: CURRENT_SCHEMA_CHECKSUM,
+        targetChecksum: CURRENT_SCHEMA_CHECKSUM,
+        // Optional Role presentation and generated-title provenance. Never infer
+        // ownership of historical titles, rewrite frozen profiles, or fill defaults.
+        sql: ""
     }]);
 export function storageMinorUpgradePlan(from) {
     if (from === CURRENT_STORAGE_VERSION)

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/dist/storage/storageVersions.js

@@ -1,4 +1,4 @@
-export const CURRENT_STORAGE_VERSION = "1.24";
+export const CURRENT_STORAGE_VERSION = "1.25";
 export const MIN_SUPPORTED_STORAGE_VERSION = "1.0";
 export const STORAGE_FORMAT = "yui-home";
 export function isStorageVersion(value) {

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、模型/账号/权限变更或全局重启。