@zq-silk/yui 2.6.0 → 2.7.1

package/dist/scheduler/operatorEvent.js

@@ -1,6 +1,55 @@
 import { enqueueWork } from "../coordination/workMailboxQueue.js";
 import { createTaskEvent } from "../event/taskEvent.js";
+import { claimPending } from "../coordination/workMailbox.js";
 export const LEADER_ATTENTION_REQUIRED_EVENT = "leader.attention-required";
+/** Bound each Operator pass, retaining the exact unclaimed sequence suffix. */
+export function claimOperatorAttention(mailbox, options) {
+    const pending = mailbox.pending;
+    if (pending === null || pending.requestCount <= 64)
+        return claimPending(mailbox, options);
+    // Operator producers append one unique source ref per signal. Mailbox merge
+    // preserves insertion order for refs and keys, including the supported
+    // default sequence keys used by Provider retry attention. Preserve those
+    // keys verbatim; they are valid current data, not a migration or repair.
+    if (pending.requestCount !== pending.dedupeKeys.length
+        || pending.refs.length !== pending.requestCount
+        || pending.toSequence - pending.fromSequence + 1 !== pending.requestCount
+        || pending.dedupeKeys.some((key, index) => {
+            const ref = pending.refs[index];
+            return (ref.type !== "event" && ref.type !== "input")
+                || key !== `operator-${ref.type}:${ref.taskId}:${ref.id}`
+                    && key !== `sequence:${pending.fromSequence + index}`;
+        })) {
+        throw new Error("Operator attention batch cannot be safely partitioned; inspect its source refs and sequence before retrying.");
+    }
+    const prefixKeys = pending.dedupeKeys.slice(0, 64);
+    const suffixKeys = pending.dedupeKeys.slice(64);
+    const through = pending.fromSequence + 63;
+    const prefix = { ...pending, toSequence: through, requestCount: 64,
+        dedupeKeys: prefixKeys, refs: pending.refs.slice(0, 64) };
+    const claimed = claimPending({ ...mailbox, pending: prefix }, {
+        ...options, batchId: `operator:${prefix.fromSequence}-${prefix.toSequence}`
+    });
+    return { ...claimed, pending: { ...pending, fromSequence: through + 1,
+            requestCount: pending.requestCount - 64, dedupeKeys: suffixKeys,
+            refs: pending.refs.slice(64) } };
+}
+/**
+ * Fixed source admission at the durable event write, in the same transaction.
+ * The existing mailbox is the incremental restart cursor: periodic scheduling
+ * reads only outstanding refs, never re-scans or replays historical events.
+ * Context, idle observations and ordinary progress are deliberately absent.
+ */
+export function enqueueDurableOperatorFact(store, event) {
+    const now = new Date(event.createdAt);
+    if (event.type === "input.requested" && typeof event.payload.requestId === "string") {
+        enqueueWork(store, { kind: "operator" }, "input-requested", now, [{ type: "input", taskId: event.taskId, id: event.payload.requestId }], { source: "input-request", dedupeKey: `operator-input:${event.taskId}:${event.payload.requestId}` });
+    }
+    else if (["task.completed", "task.cancelled", "task.retired", "publication.recorded",
+        "publication.candidate-adopted", LEADER_ATTENTION_REQUIRED_EVENT].includes(event.type)) {
+        enqueueOperatorEvent(store, event, event.type.startsWith("task.") ? "task-terminal" : event.type, now);
+    }
+}
 /** One event, one supervisor signal; the Leader wake is this mailbox's projection. */
 export function enqueueSupervisorEvent(store, event, recipient, reason, now) {
     if (store.getTask(event.taskId)?.status === "archived")

package/dist/scheduler/operatorInputNotificationProcessor.js

@@ -28,8 +28,9 @@ export async function processOperatorInputNotifications(store, selection, now =
         }
         if (ref.type !== "event")
             return [];
-        const event = store.listEvents(ref.taskId).find(({ id }) => id === ref.id);
-        return event === undefined ? [] : [{ kind: "event", event }];
+        const event = store.getEvent !== undefined ? store.getEvent(ref.taskId, ref.id)
+            : store.listEvents(ref.taskId).find(({ id }) => id === ref.id);
+        return event == null ? [] : [{ kind: "event", event }];
     }));
     if (attentions.length === 0) {
         store.completeWorkMailbox(targetMailbox, processing.batchId);
@@ -42,9 +43,9 @@ export async function processOperatorInputNotifications(store, selection, now =
             receiptId: presentation.receiptId,
             text: presentation.text
         }, now);
-        if (outcome.status === "unavailable") {
+        if (outcome.status === "unavailable" || outcome.status === "deferred") {
             store.releaseWorkMailbox(targetMailbox, processing.batchId);
-            return attentions.map((attention) => skipped(attention, "operator-unavailable"));
+            return attentions.map((attention) => skipped(attention, outcome.status === "deferred" ? "notice-pending" : "operator-unavailable"));
         }
         return attentions.map((attention) => ({
             ...attentionIdentity(attention),

package/dist/scheduler/taskWake.js

@@ -1,6 +1,7 @@
 import { requireIdentity, requirePositiveInteger, requireText, requireTimestamp } from "../domain/validation.js";
 import { TASK_RECORD_ID_PREFIXES } from "../task/taskRecordReference.js";
 import { copyRef } from "../coordination/workMailbox.js";
+import { validateInboxReceipt } from "../message/inboxReceipt.js";
 export const CURRENT_TASK_WAKE_SCHEMA_VERSION = 1;
 export function createTaskWake(input) {
     if (Object.hasOwn(input, "runId"))
@@ -21,6 +22,10 @@ export function createTaskWake(input) {
     return wake;
 }
 export function validateTaskWake(wake) {
+    validateInboxReceipt(wake.inbox);
+    if (wake.inboxPendingId !== undefined && (!/^pending-[a-f0-9]{64}$/.test(wake.inboxPendingId) || !wake.inbox)) {
+        throw new Error("An active inbox wake requires its exact pending identity and handling claim.");
+    }
     if (Object.hasOwn(wake, "runId"))
         throw new Error("Run-backed wakes are not current notification records.");
     if (wake.refs !== undefined) {

package/dist/sqlite/driver.js

@@ -0,0 +1,108 @@
+import { createRequire } from "node:module";
+export const SQLITE_CANDIDATES = Object.freeze([
+    // N-API avoids node::ObjectWrap's GC cleanup abort on Node 24.19/24.20.
+    Object.freeze({ name: "sqlite-modern", version: "13.0.3", minimumNapi: 10 }),
+    Object.freeze({ name: "sqlite-compat", version: "10.1.0", minimumNapi: 0 })
+]);
+/** Only errors attributable to loading this native candidate, never database errors. */
+function nativeUnavailable(error, candidate) {
+    if (!(error instanceof Error))
+        return false;
+    const code = error.code;
+    const firstLine = error.message.split("\n")[0];
+    if (code === "MODULE_NOT_FOUND") {
+        if (firstLine === `Cannot find module '${candidate.name}'`)
+            return true;
+        // v13 loads its bundled prebuild or these node-gyp paths directly.
+        // Do not swallow an unrelated missing transitive JS dependency.
+        const missing = /^Cannot find module '([^']+)'$/.exec(firstLine)?.[1];
+        return missing !== undefined && ["Debug", "Release"].some((mode) => missing.endsWith(`/node_modules/${candidate.name}/build/${mode}/better_sqlite3.node`));
+    }
+    const tries = error.tries;
+    if (error.message.startsWith("Could not locate the bindings file.") && Array.isArray(tries)) {
+        return tries.length > 0 && tries.every((path) => typeof path === "string" && path.includes(`/node_modules/${candidate.name}/`)
+            && path.endsWith("/better_sqlite3.node"));
+    }
+    if (code !== "ERR_DLOPEN_FAILED")
+        return false;
+    return /NODE_MODULE_VERSION \d+/.test(error.message)
+        || /(?:GLIBC|GLIBCXX|CXXABI)_[\d.]+['’] not found/.test(error.message)
+        || /(?:cannot open shared object file|Library not loaded:|wrong ELF class:|invalid ELF header|incompatible architecture)/.test(error.message);
+}
+const require = createRequire(import.meta.url);
+function selectionFailure(failures) {
+    return new AggregateError(failures, "No usable SQLite driver. " + SQLITE_CANDIDATES.map((candidate, index) => `${candidate.name}@${candidate.version}: ${failures[index] instanceof Error ? failures[index].message : String(failures[index])}`).join("; ")
+        + ". Reinstall with npm optional dependencies enabled (do not use --omit=optional); "
+        + "check Node ABI, system libraries and native build tools. Older systems may require an OS/toolchain upgrade.");
+}
+/**
+ * Selection is isolated from every real database open. No real Home operation
+ * is inside a fallback catch, and successful selection stays fixed per process.
+ * Loader injection supports deterministic native-failure tests, not user config.
+ */
+export function createSqliteDriverSelector(load = (candidate) => require(candidate.name), napiVersion = Number(process.versions.napi ?? 0)) {
+    let selected;
+    return () => {
+        if (selected)
+            return selected;
+        const failures = [];
+        for (const candidate of SQLITE_CANDIDATES) {
+            // An unsupported Node-API constructor can crash outside JS exception
+            // handling. Exclude it before loading native code, not after probing.
+            if (napiVersion < candidate.minimumNapi) {
+                failures.push(new Error(`${candidate.name} requires Node-API ${candidate.minimumNapi}; runtime provides ${napiVersion}`));
+                continue;
+            }
+            let Driver;
+            let probe;
+            try {
+                Driver = load(candidate);
+                probe = new Driver(":memory:");
+            }
+            catch (error) {
+                if (!nativeUnavailable(error, candidate)) {
+                    // Stop on unknown errors, but retain the modern failure when the
+                    // compatibility candidate also fails. This does not permit retry.
+                    if (failures.length)
+                        throw selectionFailure([...failures, error]);
+                    throw error;
+                }
+                failures.push(error);
+                continue;
+            }
+            // SQL and close failures are deliberately outside the native-load catch.
+            let sqliteVersion;
+            try {
+                try {
+                    const result = probe.prepare("SELECT sqlite_version() AS version, 1 AS value").get();
+                    if (typeof result?.version !== "string" || result.value !== 1) {
+                        throw new Error(`SQLite probe returned an invalid result for ${candidate.name}.`);
+                    }
+                    sqliteVersion = result.version;
+                }
+                finally {
+                    probe.close();
+                }
+            }
+            catch (error) {
+                if (failures.length)
+                    throw selectionFailure([...failures, error]);
+                throw error;
+            }
+            selected = Object.freeze({
+                ...candidate, Database: Driver, sqliteVersion,
+                ...(failures.length ? { fallbackReason: failures[0].message } : {})
+            });
+            return selected;
+        }
+        throw selectionFailure(failures);
+    };
+}
+export const selectSqliteDriver = createSqliteDriverSelector();
+// Preserve the existing constructor/type contract without loading native code
+// during module import. All runtime consumers share the same selector.
+const Database = function (filename, options) {
+    const Driver = selectSqliteDriver().Database;
+    return new Driver(filename, options);
+};
+export default Database;

package/dist/storage/sqliteSchema.js

@@ -1,5 +1,5 @@
 import { createHash } from "node:crypto";
-import Database from "better-sqlite3";
+import Database from "../sqlite/driver.js";
 import { BASELINE_SCHEMA_SQL, SQLITE_SCHEMA_TABLES } from "./baselineSchema.js";
 import { migrateTaskMainWorkspaces } from "./upgrade/taskMainWorkspaceMigration.js";
 import { migrateProjectKnowledge } from "./upgrade/projectKnowledgeMigration.js";
@@ -76,6 +76,16 @@ const MINOR_UPGRADES = Object.freeze([{
         targetChecksum: CURRENT_SCHEMA_CHECKSUM,
         // Optional sourced monetary observations; historical missing costs stay unknown.
         sql: ""
+    }, {
+        fromVersion: "1.6",
+        toVersion: "1.7",
+        name: "agent-inbox-consumption",
+        introducedIn: "next",
+        sourceChecksum: CURRENT_SCHEMA_CHECKSUM,
+        targetChecksum: CURRENT_SCHEMA_CHECKSUM,
+        // Additive handling receipts on canonical Messages and wakes. Never invent
+        // historical processing or Provider acceptance; existing records stay intact.
+        sql: ""
     }]);
 export function storageMinorUpgradePlan(from) {
     if (from === CURRENT_STORAGE_VERSION)

package/dist/storage/sqliteStore.js

@@ -32,7 +32,7 @@
  * including writes, reads and explicit Home diagnostics. There is no weaker
  * in-process contract or deferred validation phase.
  */
-import Database from "better-sqlite3";
+import Database from "../sqlite/driver.js";
 import { existsSync, mkdirSync } from "node:fs";
 import { join } from "node:path";
 import { isDeepStrictEqual } from "node:util";
@@ -40,8 +40,10 @@ import { runPurposeAdmitsTaskState } from "../agentRun/agentRun.js";
 import { validateTaskBrief } from "../brief/taskBrief.js";
 import { validateContextSnapshot } from "../context/contextSnapshot.js";
 import { consumePendingBatch, mailboxTargetKey, validateWorkMailbox } from "../coordination/workMailbox.js";
+import { enqueueDurableOperatorFact } from "../scheduler/operatorEvent.js";
 import { validateDurableJob, validDurableJobTransition } from "../job/durableJob.js";
 import { validateGlobalRoleMessage } from "../message/message.js";
+import { assertInboxReceiptPreserved } from "../message/inboxReceipt.js";
 import { validatePluginIntent, validatePluginIntentFailure } from "../plugins/pluginIntent.js";
 import { validatePluginValidation } from "../plugins/pluginPackage.js";
 import { generateHomeIdentity, validateHomeIdentity } from "../repository/homeIdentity.js";
@@ -975,10 +977,58 @@ export class SqliteTaskStore {
     listGlobalRoleMessages(roleName) {
         return this.#sortById(this.#listPayload("global_role_messages", "name = ?", [roleName]), (message) => message.id);
     }
+    queryGlobalRoleMessages(roleName, query) {
+        if (!Number.isSafeInteger(query.limit) || query.limit < 0 || query.limit > 64
+            || !Number.isSafeInteger(query.afterSequence ?? 0) || (query.afterSequence ?? 0) < 0) {
+            throw new Error("Global Message query exceeds its bounded contract.");
+        }
+        const where = ["name = @name"];
+        const params = { name: roleName };
+        if (query.handling)
+            where.push(`json_extract(payload, '$.inbox.claim') IS NOT NULL
+      AND json_extract(payload, '$.inbox.ack') IS NULL`);
+        if (query.pending)
+            where.push(`json_extract(payload, '$.delivery') IS NULL
+      AND json_extract(payload, '$.inbox.ack') IS NULL
+      AND json_extract(payload, '$.notDelivered') IS NULL
+      AND (json_extract(payload, '$.inputControl.action') = 'queue'
+        OR json_extract(payload, '$.interruptThen') IS NOT NULL)`);
+        if (query.interruptThen)
+            where.push("json_extract(payload, '$.interruptThen') IS NOT NULL");
+        if (query.operatorNotice)
+            where.push("json_extract(payload, '$.inputControl.requestId') LIKE 'operator-notice:%'");
+        if (query.afterSequence !== undefined) {
+            where.push("seq > @after");
+            params.after = query.afterSequence;
+        }
+        if (query.id !== undefined) {
+            where.push("message_id = @id");
+            params.id = query.id;
+        }
+        if (query.requestId !== undefined) {
+            where.push("COALESCE(json_extract(payload, '$.inputControl.requestId'), json_extract(payload, '$.interruptThen.reusedInput.requestId')) = @request");
+            params.request = query.requestId;
+        }
+        const filter = where.join(" AND ");
+        const summary = this.#db.prepare(`SELECT count(*) AS count, min(created_at) AS oldestCreatedAt
+      FROM global_role_messages WHERE ${filter}`).get(params);
+        const rows = this.#db.prepare(`SELECT payload FROM global_role_messages WHERE ${filter}
+      ORDER BY seq ${query.descending ? "DESC" : "ASC"} LIMIT @limit`)
+            .all({ ...params, limit: query.limit });
+        return { ...summary, messages: rows.map(row => {
+                const message = this.#parse(row.payload);
+                validateGlobalRoleMessage(message);
+                return message;
+            }) };
+    }
     updateGlobalRoleMessage(message) {
         validateGlobalRoleMessage(message);
         this.#requireGlobalRole(message.roleName);
         this.#mutate(() => {
+            const existing = this.#db.prepare("SELECT payload FROM global_role_messages WHERE name = ? AND message_id = ?")
+                .get(message.roleName, message.id);
+            assertInboxReceiptPreserved(existing === undefined ? undefined
+                : this.#parse(existing.payload).inbox, message.inbox);
             const seq = this.#globalMessageSequence(message.id);
             const result = this.#db.prepare(`UPDATE global_role_messages SET seq = ?, payload = ? WHERE name = ? AND message_id = ?`).run(seq, this.#recordJson("global_role_messages", message), message.roleName, message.id);
             if (result.changes === 0) {
@@ -2001,6 +2051,10 @@ export class SqliteTaskStore {
         }
         this.#requireTask(taskId);
         this.#mutate(() => {
+            const existing = this.#db.prepare("SELECT payload FROM messages WHERE task_id = ? AND message_id = ?")
+                .get(taskId, message.id);
+            assertInboxReceiptPreserved(existing === undefined ? undefined
+                : this.#parse(existing.payload).inbox, message.inbox);
             const result = this.#db.prepare(`UPDATE messages SET payload = ? WHERE task_id = ? AND message_id = ?`).run(this.#recordJson("messages", message), taskId, message.id);
             if (result.changes !== 1) {
                 throw new StorageRecordError(`Message does not exist: ${taskId}/${message.id}`);
@@ -2086,6 +2140,7 @@ export class SqliteTaskStore {
             // Events are terminal/semantic: retained individually, never pruned (§9).
             this.#db.prepare(`INSERT INTO events (task_id, event_id, type, occurred_at, payload) VALUES (?, ?, ?, ?, ?)`).run(taskId, event.id, event.type, event.createdAt, this.#recordJson("events", event));
             this.#observeHighWater(taskId, "event", seq);
+            enqueueDurableOperatorFact(this, event);
         });
     }
     listEvents(taskId) {
@@ -2113,6 +2168,10 @@ export class SqliteTaskStore {
         validateTaskWake(wake);
         this.#requireTask(taskId);
         this.#mutate(() => {
+            const existing = this.#db.prepare("SELECT payload FROM task_wakes WHERE task_id = ? AND wake_id = ?")
+                .get(taskId, wake.id);
+            assertInboxReceiptPreserved(existing === undefined ? undefined
+                : this.#parse(existing.payload).inbox, wake.inbox);
             const seq = this.#idSequence(wake.id, "taskWake");
             this.#db.prepare(`INSERT INTO task_wakes
           (task_id, wake_id, seq, status, from_cursor, to_cursor, reasons, payload, created_at, consumed_at)

package/dist/storage/storageSchema.js

@@ -1,6 +1,6 @@
 import { existsSync, readdirSync } from "node:fs";
 import { join } from "node:path";
-import Database from "better-sqlite3";
+import Database from "../sqlite/driver.js";
 import { inspectSqliteSchema, storageMinorUpgradePlan, SqliteSchemaError } from "./sqliteSchema.js";
 import { compareStorageVersions, CURRENT_STORAGE_VERSION, MIN_SUPPORTED_STORAGE_VERSION } from "./storageVersions.js";
 export { CURRENT_STORAGE_VERSION, MIN_SUPPORTED_STORAGE_VERSION } from "./storageVersions.js";

package/dist/storage/storageVersions.js

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

package/dist/storage/storeRpc.js

@@ -48,6 +48,7 @@ const READ_ONLY_STORE_METHODS = new Set([
     "getGlobalRoleSessionSet",
     "listGlobalRoleSessionSets",
     "listGlobalRoleMessages",
+    "queryGlobalRoleMessages",
     "listTasks",
     "getTask",
     "readNextActionFacts",

package/dist/storage/upgrade/upgradeOrchestrator.js

@@ -1,6 +1,6 @@
 import { join } from "node:path";
 import { copyFileSync, existsSync, mkdirSync, rmdirSync, rmSync } from "node:fs";
-import Database from "better-sqlite3";
+import Database from "../../sqlite/driver.js";
 import { RUNTIME_OBSERVATION_TASK_EVENT, createRuntimeObservation } from "../../runtime/runtimeObservation.js";
 import { RUNTIME_PROCESS_EXIT_TASK_EVENT, validateRuntimeProcessExitObservation } from "../../runtime/processExitObservation.js";
 import { SqliteTaskStore } from "../sqliteStore.js";

package/dist/task/completionReadiness.js

@@ -1,12 +1,18 @@
 import { governingWorkItemDeliveries, integrationAttemptRequiresSettlement, workItemDeliverySettled } from "../integration/deliveryObligation.js";
+import { isLeaderSteer, taskMessageInboxReceipt } from "../message/taskInboxOwnership.js";
 import { operationalTaskRecords } from "./taskRecordRetirement.js";
-/** Mailbox refs locate original durable user intent. No separate acknowledgement
- * state is introduced: finish the current native turn and let the existing
- * notification delivery present the new input before declaring completion. */
+/** Mailbox refs locate original durable user intent. Active inbox handling
+ * retains the same completion fence until the exact window is acknowledged. */
 export function pendingCompletionMessages(store, taskId) {
     const mailbox = store.getWorkMailbox({ kind: "role", taskId, roleName: "leader" });
     const refs = [...(mailbox?.pending?.refs ?? [])];
+    for (const wake of store.listTaskWakes(taskId)) {
+        if (wake.inbox !== undefined && wake.inbox.ack === undefined)
+            refs.push(...(wake.refs ?? []));
+    }
     const processing = mailbox?.processing;
+    if (processing?.owner.startsWith("agent-inbox:"))
+        refs.push(...processing.batch.refs);
     if (processing?.owner.startsWith("leader-notification:")) {
         const native = store.getTaskRoleSessionSet(taskId, "leader")?.providerBinding?.run;
         if (native?.attemptId !== processing.batchId
@@ -16,7 +22,8 @@ export function pendingCompletionMessages(store, taskId) {
     }
     const ids = new Set(refs.filter(ref => ref.type === "message" && ref.taskId === taskId).map(ref => ref.id));
     return operationalTaskRecords(store.listMessages(taskId), store.listEvents(taskId), "message")
-        .filter(message => ids.has(message.id)
+        .filter(message => (ids.has(message.id) || isLeaderSteer(message) && message.inbox !== undefined)
+        && taskMessageInboxReceipt(store, message)?.ack === undefined
         && (message.kind === "user" || message.kind === "operator"));
 }
 const ACTIVE_JOB_STATUSES = new Set([

package/dist/telemetry/sqliteTelemetryStore.js

@@ -1,4 +1,4 @@
-import Database from "better-sqlite3";
+import Database from "../sqlite/driver.js";
 import { existsSync } from "node:fs";
 import { join } from "node:path";
 import { CURRENT_DATABASE_FILENAME as COMMITTED_DATABASE_FILENAME } from "../storage/currentTaskStore.js";

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

@@ -69,11 +69,27 @@ Run Pack is a reference directory: read the relevant requirement and message
 bodies before acting, rather than treating a successful load as the deliverable.
 Planning Packs expose no Project write scope or Task-completion permission.
 
-The Manifest pointer is a recovery locator, not a read receipt. Load its exact
-`yui-runtime`, Role Skills and profile on first entry, a new/version-changed
-Session, or missing context after compaction/recovery. Reuse instructions only
-when the same-version full content is still available; Yui stores no "already
-read" state. Always refresh dynamic facts. Leader notifications use
+The Manifest pointer is a recovery locator, not a read receipt. At the start of
+every turn run `yui session skills --json` through the Session's CLI/Home. It
+checks current paths, internal `VERSION` files and readability, without reading
+Skill bodies or walking/snapshotting resources. Builtins use the running
+installation's `skills/<id>` entry; configured Skills use `YUI_HOME/skills/<id>`.
+These paths do not contain a Session/content digest. After changing installation
+locations the check resolves the current installation, not an old recorded path.
+For Global Sessions the Manifest's `skillCheckCommand` is its self-contained
+`session context <role>` read, which also returns current Skill metadata and works
+after moving to Desktop without the launch shell's environment. An older Global
+Manifest's existing `loadCommand` provides the same check.
+
+Load current `yui-runtime`, applicable Role/custom Skills and necessary references,
+plus the Manifest's profile, on first entry, a version change, recovery, or missing/
+compacted/uncertain context. Reuse only when versions are unchanged and the full
+instructions remain available now. Yui stores no "already read" state and does
+not claim to inspect the model's context. Historical packages remain audit only;
+missing/corrupt snapshots do not prevent valid Session resume or input delivery.
+Missing current files report their exact path and recovery action. Session
+identity, scope, writer fences and real CLI/Home incompatibility still reject.
+Always refresh dynamic facts. Leader notifications use
 `currentCommand`; dispatched AgentRuns use the actual Run ID with
 `loadCommand`/`expandCommand`, never their placeholder templates.
 
@@ -139,6 +155,66 @@ summary store, read-acknowledgement or extra model call is involved. Missing or
 oversized summaries fall back to facts without clipping qualifications.
 Summaries never grant authority, accept results or mark reviews approved.
 
+### Operator backlog and periodic recovery
+
+Task completion/cancellation/retirement, publication records/adoption and input
+requests enqueue Operator attention in the same transaction as their durable
+event. Existing Run failure routing keeps its retry and supervisor guards.
+The ready mailbox is the incremental recovery source: a lost scheduler signal
+or Controller restart does not require a Leader report or a scan of historical
+Tasks. The existing periodic pass retries outstanding mailbox work; an unchanged,
+settled mailbox creates neither a Message nor a model call.
+
+At most one unsent engineering notice is queued. Further facts coalesce in the
+mailbox until that notice is accepted or conclusively not delivered. Each handoff
+claims at most 64 source signals and reads exact records, retaining the unclaimed
+suffix. Global delivery reads at most 64 pending Messages per Role per pass;
+conclusively stale originals retain their nondelivery evidence, with later pages
+handled by subsequent passes. Reserved interrupt-then inputs remain discoverable
+beyond that ordinary page. FIFO user inputs and unknown-effect fences are not
+reordered to make notifications appear healthy. SQL aggregates still inspect
+matching stored rows; these bounds limit materialized records and per-pass
+delivery work, not the size of the persisted mailbox or database.
+
+A full reconciliation may ask the original Host to republish an already observed
+terminal for the exact Session, authority, attempt and native Turn. For a Desktop
+direct Turn, that Host must have retained both the exact start and terminal under
+the unchanged writer fence; `direct:<nativeTurnId>` and the native Turn are both
+required. This bounded latest observation does not make the input client-owned.
+This uses the existing Inbox and canonical observer, including the original result.
+It does not submit input, query another native client, restart a Host, or infer
+quiescence from elapsed time/idle state. Normal terminal processing signals again
+after releasing Host occupancy. Unknown acceptance remains isolated unless exact
+evidence settles that input. Explicit stop/replacement and external writers remain
+hard boundaries.
+
+`yui session context <role> --json` includes bounded `backlog` diagnostics: pending
+count, oldest timestamp, target and attempt identities, blocking reason and
+recovery guidance. Live age is in `backlogObservation`, outside the paged source
+digest. `in-flight-or-unobserved-terminal` deliberately does not label a
+long-running accepted Turn as stuck. An unavailable/older Host or missing retained
+terminal produces one record-only runtime-attention Message per exact attempt;
+inspect it through the existing message list/show commands. No recovery Agent,
+private timer, migration or new acknowledgement state is introduced. If the
+Provider itself never reported a terminal, or the original Host lost its evidence,
+automatic reconciliation cannot prove completion: restore the compatible observation
+path or explicitly stop/replace only with the required native quiescence evidence.
+This change does not backfill arbitrary pre-existing historical events, adopt old
+Hosts, or authorize production upgrades/restarts.
+
+Controller restart preserves live Hosts; it does not replace their loaded code.
+A supported surviving Host writes raw observations to the immutable Inbox even
+while the Controller is down; the restarted Controller applies them under current
+Session fences. A frozen Manifest's CLI/storage mismatch is a context-read failure,
+not proof that the Host publisher failed: this publisher uses the Inbox/RPC, not
+that CLI. An Endpoint checkout generation is not a complete Host build identity.
+The runtime-attention evidence distinguishes an unavailable control channel,
+rejected control (including implementations without reconciliation), and a missing
+exact retained terminal, with reported Endpoint/event-delivery observations.
+Missing delivery diagnostics mean unreported, not healthy. Unsupported live code
+cannot be repaired by another Controller restart or guessed adoption; inspect the
+original evidence and explicitly authorize any necessary lifecycle recovery.
+
 `task wake show <task> <wake>` now defaults to inputs/results and explicit
 references, including older referenced originals. It omits unrelated diagnostic
 events and merely started Runs; `--history` restores full fixed-window discovery.

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

@@ -55,9 +55,19 @@ Run Context 冻结 Assignment、来源引用、生效配置和工作区边界。
 和消息正文，而不是把加载成功当成交付物。规划 Pack 不暴露 Project 写范围或 Task 完成
 权限。
 
-Manifest 指针是恢复定位入口，不是已读凭据。首次进入、新会话、版本变化、压缩或恢复后
-说明缺失时，从其确切路径加载 `yui-runtime`、Role Skills 和 profile；仅当同版本全文仍在
-当前可用上下文中，才复用而不机械重读。系统不保存“已经读过”状态。动态事实仍须刷新：
+Manifest 指针是恢复定位入口，不是已读凭据。每轮开始通过本 Session 的 CLI/Home 执行
+`yui session skills --json`，轻量检查当前路径、内部 `VERSION` 和文件可读性，不读取
+正文或遍历/冻结资源。内置入口是当前安装目录的 `skills/<id>`，自定义入口是
+`YUI_HOME/skills/<id>`，不包含 Session/内容摘要；安装位置变化后由检查重新解析当前入口。
+Global Manifest 的 `skillCheckCommand` 使用自包含的 `session context <role>`，
+同时返回 Skill 元数据，因此切换到 Desktop 后不依赖启动 shell 的环境；
+旧 Global Manifest 的 `loadCommand` 也能执行相同检查。
+首次进入、版本变化、恢复，以及压缩后全文缺失或可用性不确定时，读取当前 Runtime、
+Role/custom Skills 全文及必要引用、Manifest 的 profile。只有版本未变且全文仍在当前
+上下文时才复用。系统不保存“已经读过”状态，也不声称检查了模型上下文。
+历史冻结包仅作审计：缺失或损坏不阻止合法 Session 恢复与消息投递；当前文件缺失则
+报告具体路径和修复动作。身份、作用域、writer fence 与实际 CLI/Home 不兼容仍会拒绝。
+动态事实仍须刷新：
 Leader 通知使用 `currentCommand`，显式 AgentRun 使用真实 Run ID 的
 `loadCommand`/`expandCommand`，不可直接执行占位模板。
 
@@ -110,6 +120,44 @@ Leader 本地编辑保留持久事件，但不创建自唤醒。当 Leader 忙
 Task 叙述。人工输入、显式执行进入和激活失败通过既有唤醒机制及时投递。Worker 结果
 保留其聚合窗口。忙碌的原生输入仍保留待处理的消息。
 
+### Operator 积压与周期恢复
+
+Task 完成／取消／退役、Publication 记录／采用及 InputRequest 与持久事件在同一事务中
+进入 Operator 邮箱；Run 失败继续遵守既有重试和监督路由。邮箱自身就是增量恢复源：
+通知信号遗漏或 Controller 重启后，既有周期协调读取尚未处理的引用，不依赖 Leader
+主动报告，也不遍历历史 Task。已结算且无变化的邮箱不会生成消息或调用模型。
+
+最多保留一条未发送的工程通知，后续事实在原邮箱中合并，直到该通知已接受或明确未投递。
+每次认领最多 64 个来源信号，读取精确记录并保留未认领后缀。Global 投递每个 Role 每轮
+最多读取 64 条待处理消息；已证明失效的原始消息保留未投递证据，后续页由下一轮处理。
+interrupt-then 的预留输入不会因超出普通页而被跳过，用户输入顺序和未知效果围栏保持不变。
+SQL 聚合仍检查匹配的存储行；这些上界约束物化记录和每轮投递工作，不限制持久邮箱或数据库大小。
+
+完整周期协调可要求原 Host 重发它已经观察到的精确终态，严格绑定 Session、
+authority、attempt 和 native Turn。Desktop direct 回合还要求该 Host 保留同一 writer 围栏下
+精确匹配的开始和结束，同时核对 `direct:<nativeTurnId>` 与 native Turn；只保留最近一次
+观察，不把 direct 输入改为 client-owned。通过原 Inbox 和规范观察器处理完整结果；不提交新输入、
+另开原生客户端查询、重启 Host，也不凭时间或 idle 推定静止。正常终态在释放 Host 占用后
+再次发出队列信号。未知接受只有精确证据才能结算，显式停止／替换及外部 writer 仍是硬边界。
+
+`yui session context <role> --json` 的 `backlog` 提供有界待投递数量、最老时间、
+目标与尝试身份、阻塞原因和恢复指引；实时年龄位于分页摘要外的 `backlogObservation`，
+不会令分页游标因时间流逝失效。`in-flight-or-unobserved-terminal` 不把长期 accepted
+误报为卡死。Host 不可达、不支持重观察或缺少保留终态时，每个精确尝试只留下一个 record-only
+runtime-attention Message，可通过既有 message list/show 查看，不自动唤醒恢复 Agent。
+如果 Provider 从未报告终态，或原 Host 已失去证据，则不能自动证明完成；须恢复兼容观察路径，
+或在取得原生静止证据后显式停止／替换。不新增私有定时器、迁移或 ack 状态，不猜补任意旧历史、
+收养旧 Host，也不授权生产升级／重启。
+
+Controller 重启保留存活 Host，不替换它们已加载的代码。支持当前协议的原 Host 在 Controller
+停机期间仍把原始观察写入不可变 Inbox，重启后由 Controller 按当前 Session 围栏应用。
+冻结 Manifest 的旧 CLI/storage 不匹配是 Context 读取失败，不足以证明 Host 发布失败：
+发布器使用 Inbox/RPC，不执行该 CLI。Endpoint 的 checkout generation 也不是完整 Host
+构建身份。runtime-attention 区分控制通道不可达、控制被拒绝（包括实现不支持协调）和
+精确终态未保留，并附已报告的 Endpoint/eventDelivery 观察；缺少诊断表示未报告，而非健康。
+再次重启 Controller 或猜测 adoption 不能修复不支持的存活代码；须检查原证据，并为必要的
+生命周期恢复另行取得明确授权。
+
 | 证据 | 处置 |
 | --- | --- |
 | 忙碌且已证明未接受 | 保留输入；新的传输尝试可以使用同一 Session |