@zq-silk/yui 2.7.1 → 2.8.1

package/dist/models/modelManagementHttp.js

@@ -0,0 +1,90 @@
+import { lookup } from "node:dns/promises";
+import { request as httpRequest } from "node:http";
+import { request as httpsRequest } from "node:https";
+import { BlockList, isIP } from "node:net";
+import { modelUrl } from "./modelManagementConfig.js";
+const denied = new BlockList();
+for (const [address, bits] of [
+    ["0.0.0.0", 8], ["10.0.0.0", 8], ["100.64.0.0", 10], ["169.254.0.0", 16],
+    ["172.16.0.0", 12], ["192.0.0.0", 24], ["192.168.0.0", 16], ["198.18.0.0", 15],
+    ["224.0.0.0", 4], ["240.0.0.0", 4]
+])
+    denied.addSubnet(address, bits, "ipv4");
+for (const [address, bits] of [["::", 128], ["fc00::", 7], ["fe80::", 10], ["ff00::", 8], ["::ffff:0:0", 96]]) {
+    denied.addSubnet(address, bits, "ipv6");
+}
+/** Small fixed-route client: pinned DNS, no redirects/proxies, deadline and byte cap. */
+export async function readModelJson(base, suffix, key, timeoutMs) {
+    const url = modelUrl(`${base.replace(/\/+$/, "")}${suffix}`);
+    const hostname = url.hostname.replace(/^\[|\]$/g, "");
+    const explicitLoopback = ["127.0.0.1", "::1", "localhost"].includes(hostname);
+    const abort = new AbortController();
+    const timer = setTimeout(() => abort.abort(), timeoutMs);
+    try {
+        const addresses = await Promise.race([
+            isIP(hostname) ? Promise.resolve([{ address: hostname, family: isIP(hostname) }]) : lookup(hostname, { all: true }),
+            new Promise((_, reject) => abort.signal.addEventListener("abort", () => reject(new Error("timeout")), { once: true }))
+        ]);
+        if (abort.signal.aborted || !addresses.length || addresses.some(({ address, family }) => {
+            const loopback = address === "::1" || address.startsWith("127.");
+            return (loopback && !explicitLoopback) || (!loopback && explicitLoopback)
+                || (!loopback && denied.check(address, family === 6 ? "ipv6" : "ipv4"));
+        }))
+            throw new Error("target-rejected");
+        const selected = addresses[0];
+        return await new Promise((resolve, reject) => {
+            const request = (url.protocol === "https:" ? httpsRequest : httpRequest)(url, {
+                method: "GET", signal: abort.signal, agent: false,
+                headers: { accept: "application/json", ...(key ? { authorization: `Bearer ${key}` } : {}) },
+                lookup: (_name, options, callback) => options.all
+                    ? callback(null, addresses)
+                    : callback(null, selected.address, selected.family)
+            }, response => {
+                if (response.statusCode !== 200) {
+                    response.destroy();
+                    reject(new Error(response.statusCode === 401 || response.statusCode === 403 ? "authentication-failed"
+                        : response.statusCode === 404 ? "route-unavailable" : "service-failed"));
+                    return;
+                }
+                let bytes = 0;
+                const chunks = [];
+                response.on("data", chunk => {
+                    bytes += chunk.length;
+                    if (bytes > 2 * 1024 * 1024) {
+                        response.destroy();
+                        reject(new Error("response-too-large"));
+                    }
+                    else
+                        chunks.push(chunk);
+                });
+                response.on("error", () => reject(new Error("read-failed")));
+                response.on("end", () => {
+                    try {
+                        // Even schema-allowed upstream strings must not echo our credential.
+                        const text = Buffer.concat(chunks).toString("utf8");
+                        const parsed = JSON.parse(text);
+                        resolve(key ? redact(parsed, key) : parsed);
+                    }
+                    catch {
+                        reject(new Error("invalid-response"));
+                    }
+                });
+            });
+            request.on("error", () => reject(new Error(abort.signal.aborted ? "timeout" : "connection-failed")));
+            request.end();
+        });
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+function redact(value, key) {
+    if (typeof value === "string")
+        return value.split(key).join("[redacted]");
+    if (Array.isArray(value))
+        return value.map(item => redact(item, key));
+    if (value && typeof value === "object")
+        return Object.fromEntries(Object.entries(value)
+            .map(([name, item]) => [name.split(key).join("[redacted]"), redact(item, key)]));
+    return value;
+}

package/dist/models/modelManagementTypes.js

@@ -0,0 +1 @@
+export {};

package/dist/output/boundedRead.js

@@ -2,6 +2,30 @@ import { createHash } from "node:crypto";
 import { usageError } from "../errors/cliError.js";
 export const READ_PAGE_BYTES = 32 * 1024;
 export const INLINE_DOCUMENT_BYTES = 16 * 1024;
+/** Compact JSON wire budget, including the CLI envelope and small command
+ * wrappers (for example Run Context's `context` field). Never count just items. */
+export function fitsReadBudget(value, bytes = READ_PAGE_BYTES) {
+    return Buffer.byteLength(JSON.stringify({ ok: true, data: value })) + 256 <= bytes;
+}
+export function summaryText(text, bytes = 512) {
+    if (Buffer.byteLength(text) <= bytes)
+        return text;
+    let result = "";
+    let size = 0;
+    for (const character of text) {
+        const length = Buffer.byteLength(character);
+        if (size + length + 3 > bytes)
+            break;
+        result += character;
+        size += length;
+    }
+    return result + "…";
+}
+/** List-only nested metadata. The containing entry must expose an exact read. */
+export function summaryMetadata(value, budget = 2048) {
+    const bytes = Buffer.byteLength(JSON.stringify(value));
+    return bytes <= budget ? value : { omitted: true, digest: readDigest(value), bytes };
+}
 function assertSource(source) {
     if (Buffer.byteLength(source) > 1024)
         throw usageError("Read source identity exceeds its 1024-byte budget.");
@@ -22,7 +46,7 @@ export function encodeReadCursor(cursor) {
 export function decodeReadCursor(raw, source, digest) {
     let cursor;
     try {
-        if (raw.length > 4096)
+        if (raw.length > 16 * 1024)
             throw new Error();
         cursor = JSON.parse(Buffer.from(raw, "base64url").toString("utf8"));
         if (cursor.source !== source || !Number.isSafeInteger(cursor.offset) || cursor.offset < 0
@@ -46,7 +70,7 @@ export function readLimit(value) {
 /** For small in-memory authorized collections. Authorize/filter BEFORE calling.
  * Cursors bind the selected collection, never grant access, and store no state.
  */
-export function recordPage(records, source, options = {}) {
+export function recordPage(records, source, options = {}, metadata = {}) {
     assertSource(source);
     const limit = readLimit(options.limit);
     const digest = readDigest(records);
@@ -54,24 +78,29 @@ export function recordPage(records, source, options = {}) {
     if (offset > records.length)
         throw usageError("Read cursor exceeds this collection.");
     const items = [];
-    // Reserve room for identities, counts and continuation. Oversized individual
-    // records belong in a document read, not silently truncated list metadata.
-    let bytes = 0;
+    const page = () => {
+        const end = offset + items.length;
+        return {
+            ...metadata,
+            source, digest, items, total: records.length, complete: end === records.length,
+            nextCursor: end < records.length ? encodeReadCursor({ source, digest, offset: end }) : null,
+            limits: { items: limit, bytes: READ_PAGE_BYTES }
+        };
+    };
     for (const record of records.slice(offset, offset + limit)) {
         const size = Buffer.byteLength(JSON.stringify(record)) + 1;
         if (size > READ_PAGE_BYTES / 2)
             throw usageError("List entry exceeds its summary budget; read the exact record.");
-        if (bytes + size > READ_PAGE_BYTES - 4096)
-            break;
         items.push(record);
-        bytes += size;
+        if (!fitsReadBudget(page())) {
+            items.pop();
+            break;
+        }
     }
-    const end = offset + items.length;
-    return {
-        source, digest, items, total: records.length, complete: end === records.length,
-        nextCursor: end < records.length ? encodeReadCursor({ source, digest, offset: end }) : null,
-        limits: { items: limit, bytes: READ_PAGE_BYTES }
-    };
+    if (!fitsReadBudget(page()) || items.length === 0 && offset < records.length) {
+        throw usageError("List entry and read identity exceed the response budget; read the exact record.");
+    }
+    return page();
 }
 /** Small exact details stay native JSON. Large details explicitly become a
  * contentPage. Concatenate text in order, then JSON.parse once, never each chunk.

package/dist/runtime/agentEndpointIdentity.js

@@ -78,12 +78,16 @@ export function validateAgentEndpointImplementation(ref) {
     }
     return ref;
 }
-/** Missing old code is an explicit inability to resume, never a Provider fallback. */
+/**
+ * The built-in adapter identity is the supported native connection contract.
+ * Build generations are provenance, not a requirement to retain old code.
+ * Actual native resume still validates the conversation/account/configuration.
+ */
 export function requireBuiltinAgentEndpointImplementation(adapterId, ref) {
     validateAgentEndpointImplementation(ref);
     const current = builtinAgentEndpointImplementation(adapterId);
-    if (ref.id !== current.id || ref.generation !== current.generation) {
-        throw new Error(`Session Endpoint ${ref.id}@${ref.generation} is unavailable; explicitly select a new Session.`);
+    if (ref.id !== current.id) {
+        throw new Error(`Session Endpoint ${ref.id} is incompatible with adapter ${adapterId}.`);
     }
-    return ref;
+    return current;
 }

package/dist/runtime/agentEndpointOwnership.js

@@ -8,9 +8,9 @@ import { createAgentEndpointFactory } from "./agentEndpoint.js";
  * owns its own Host in its own process and never holds an Endpoint client, so
  * the reference facts for a Session live where the Session actually runs.
  *
- * Only the running code can be attached here. Selecting between generations is
- * the launch decision recorded in the durable Session; this owner proves the
- * chosen generation is really held and really released.
+ * Only the running code can be attached here. This owner proves the loaded
+ * generation is held and released; historical launch generations do not select
+ * old code or block a compatible native resume.
  */
 export function createAgentEndpointOwner(factory = createAgentEndpointFactory()) {
     const host = new InstanceHost();
@@ -48,9 +48,8 @@ export function createAgentEndpointOwner(factory = createAgentEndpointFactory())
         await holder.handle.release();
     };
     /**
-     * Pin the implementation for one Session. A pinned reference from the durable
-     * Session must name this exact code; a mismatch is an explicit inability to
-     * resume, never a silent start on a different generation.
+     * Hold the current implementation for one Session. A historical reference
+     * must name the same built-in adapter, not the same package build.
      */
     const pin = (adapterId, pinned) => {
         if (pinned !== undefined)

package/dist/runtime/agentHost.js

@@ -5,7 +5,7 @@ import { homedir, tmpdir } from "node:os";
 import { dirname, join, resolve } from "node:path";
 import { createInterface } from "node:readline";
 import { withSessionContextPointer } from "../context/sessionBootstrapManifest.js";
-import { publishStructuredConversationRecoverability, publishStructuredProviderAccepted, publishStructuredProviderActivity, publishStructuredProviderAttachmentExit, publishStructuredProviderConnection, publishStructuredProviderDiagnostic, publishStructuredProviderGoal, publishStructuredProviderInputObserved, publishStructuredProviderInputSettlement, publishStructuredProviderOpened, publishStructuredProviderStarted, publishStructuredProviderTerminal, structuredProviderEventDelivery } from "../controller/structuredProviderObservation.js";
+import { publishStructuredConversationRecoverability, publishStructuredProviderAccepted, publishStructuredProviderActivity, publishStructuredProviderAttachmentExit, publishStructuredProviderConnection, publishStructuredProviderDiagnostic, publishStructuredProviderGoal, publishStructuredProviderInputObserved, publishStructuredProviderInputSettlement, publishStructuredProviderOpened, publishStructuredProviderStarted, publishStructuredProviderTerminal, replayStructuredProviderPersistence, structuredProviderEventDelivery } from "../controller/structuredProviderObservation.js";
 import { callController, controllerCallMayHaveApplied, ControllerClientError } from "../core/controllerClient.js";
 import { readHomeFilesystemId } from "../core/homeFilesystemIdentity.js";
 import { isForeignHandoverLockHeld } from "../release/runtimeRelease.js";
@@ -14,6 +14,7 @@ import { tmuxSocketDirectory } from "../tmux/tmuxSocketEndpoint.js";
 import { createAgentEndpointOwner } from "./agentEndpointOwnership.js";
 import { providerDeliveryFailure, providerDeliveryFailureFrom, redactAgentErrorText, serializeAgentErrorRaw } from "./agentError.js";
 import { AGENT_HOST_CONTROL_PROTOCOL } from "./agentHostProtocol.js";
+import { AGENT_HOST_IMPLEMENTATION } from "./agentHostImplementation.js";
 import { closeAgentHostEndpoints } from "./agentHostCleanup.js";
 import { readAgentRunConfigurationObservation, unknownAgentRunConfiguration } from "./agentRunConfiguration.js";
 import { CodexPreSubmissionError } from "./codexAppServerRuntime.js";
@@ -188,6 +189,9 @@ export async function runAgentHost(input) {
                 && previous.started.nativeSessionId === session?.nativeSessionId) {
                 await publishStructuredProviderTerminal({
                     home: input.home, environment: previous.payload.environment, terminal: previous.terminal
+                }).catch(() => {
+                    // The publisher retains the original unpersisted bytes. Still
+                    // observe the new start; a failed old write must not hide its writer.
                 });
             }
             if (session !== undefined && started.nativeSessionId === session.nativeSessionId
@@ -594,6 +598,8 @@ export async function runAgentHost(input) {
             throw new Error("Agent Host accepts only managed Provider control launches.");
         }
         if (activeRunPayload !== undefined
+            || sessionPayload !== undefined
+                && (structuredProviderEventDelivery(input.home, sessionPayload.environment).unpersisted ?? 0) > 0
             || ["starting", "ready", "settling", "delivery-unknown"].includes(snapshot.state)) {
             throw new Error("Agent Host still owns an unsettled Provider Turn.");
         }
@@ -624,8 +630,7 @@ export async function runAgentHost(input) {
                     || providerControl.mode !== "resume"
                     || providerControl.nativeSessionId !== session.nativeSessionId
                     || (providerControl.endpointImplementation !== undefined
-                        && (providerControl.endpointImplementation.id !== session.configuration.implementation.id
-                            || providerControl.endpointImplementation.generation !== session.configuration.implementation.generation))) {
+                        && providerControl.endpointImplementation.id !== session.configuration.implementation.id)) {
                     throw new Error("Agent Host launch does not match its live Provider Conversation.");
                 }
                 sessionPayload = next;
@@ -638,9 +643,8 @@ export async function runAgentHost(input) {
                 }
                 // The Controller revalidates the adopted execution environment while
                 // redeeming this launch; a persistent Host must not reopen its schema.
-                // Pin before opening: the Session holds this exact generation for every
-                // later Turn. A pinned reference naming code this process is not running
-                // fails here, rather than silently starting on a different generation.
+                // Hold the code actually loaded by this Host. Historical build identity
+                // is provenance; native resume and current authority remain mandatory.
                 endpointLease ??= endpointOwner.pin(providerControl.adapterId, providerControl.endpointImplementation);
                 endpointAdapterId = providerControl.adapterId;
                 const started = await (providerControl.mode === "new"
@@ -786,6 +790,7 @@ export async function runAgentHost(input) {
             throw new Error("Agent Host rejected a stale Provider writer fence.");
         }
         if (activeRunPayload !== undefined || snapshot.state === "settling"
+            || (structuredProviderEventDelivery(input.home, sessionPayload.environment).unpersisted ?? 0) > 0
             || session.inspect().activeNativeTurnId !== undefined) {
             operation.failure = providerDeliveryFailure({
                 detail: "Agent Host still owns an unsettled Provider Turn.",
@@ -1042,7 +1047,9 @@ export async function runAgentHost(input) {
         if (session === undefined || request.nativeSessionId !== session.nativeSessionId) {
             throw new Error("Agent Host authority targets a different Provider Conversation.");
         }
-        if (activeRunPayload !== undefined
+        if (activeRunPayload !== undefined || session.inspect().activeNativeTurnId !== undefined
+            || sessionPayload !== undefined
+                && (structuredProviderEventDelivery(input.home, sessionPayload.environment).unpersisted ?? 0) > 0
             || ["starting", "ready", "settling", "delivery-unknown"].includes(snapshot.state)) {
             throw new Error("Agent Host authority cannot transfer while a AgentRun is unsettled.");
         }
@@ -1118,7 +1125,9 @@ export async function runAgentHost(input) {
             return enqueueSerialized(async () => {
                 const current = session;
                 if (!current?.nativeAccess || current.nativeSessionId !== request.nativeSessionId
-                    || !sessionPayload || activeNativeTurnId || authority?.owner !== "controller"
+                    || !sessionPayload || activeRunPayload || activeNativeTurnId
+                    || (structuredProviderEventDelivery(input.home, sessionPayload.environment).unpersisted ?? 0) > 0
+                    || authority?.owner !== "controller"
                     || (sessionPayload.environment.YUI_SESSION_SCOPE === "task" && sessionPayload.environment.YUI_ROLE !== "leader")
                     || (sessionPayload.environment.YUI_SESSION_SCOPE === "global" && sessionPayload.environment.YUI_ROLE !== "operator")) {
                     throw new Error("Model switching requires the idle current controlled Codex Session, without a native terminal writer.");
@@ -1192,6 +1201,27 @@ export async function runAgentHost(input) {
                 || authority === undefined || !sameProviderAuthorityFence(authority, request.authority)) {
                 throw new Error("Terminal reconciliation targets a different Session or authority.");
             }
+            const recovered = await enqueueSerialized(async () => {
+                if (session?.nativeSessionId !== request.nativeSessionId || authority === undefined
+                    || !sameProviderAuthorityFence(authority, request.authority)) {
+                    throw new Error("Session changed before original event persistence recovery.");
+                }
+                const persisted = await replayStructuredProviderPersistence(input.home, sessionPayload.environment);
+                if (persisted.length > 0 && activeRunPayload === undefined) {
+                    const active = session.inspect().activeNativeTurnId;
+                    updateSnapshot(hostSnapshot(active === undefined ? "idle" : "busy", {
+                        adapterId: session.adapterId, processInstanceId: session.processInstanceId,
+                        nativeSessionId: session.nativeSessionId, conversationId: session.conversationId,
+                        nativeTurnId: active, ...authorityFields()
+                    }));
+                }
+                return persisted.some(event => ["turn.completed", "turn.failed", "turn.cancelled"].includes(event.kind)
+                    && event.fence.nativeSessionId === request.nativeSessionId
+                    && (request.nativeTurnId === undefined || event.fence.nativeTurnId === request.nativeTurnId)
+                    && (event.fence.receiptId === request.attemptId
+                        || event.fence.receiptId === undefined && request.nativeTurnId !== undefined
+                            && request.attemptId === `direct:${request.nativeTurnId}`));
+            });
             const direct = directObservation;
             const directMatch = direct?.terminal !== undefined
                 && request.nativeTurnId !== undefined
@@ -1205,7 +1235,8 @@ export async function runAgentHost(input) {
                 || terminal.nativeSessionId !== request.nativeSessionId
                 || !directMatch && (terminal.clientOwned !== true || terminal.attemptId !== request.attemptId)
                 || request.nativeTurnId !== undefined && terminal.nativeTurnId !== request.nativeTurnId) {
-                return { ...controlResult("status", snapshot), reconciliation: "unobserved" };
+                return { ...controlResult("status", snapshot),
+                    reconciliation: recovered ? "terminal-republished" : "unobserved" };
             }
             // Serialize with submission/terminal persistence. The original Host and
             // original launch envelope remain the observer, including the full result.
@@ -1539,7 +1570,18 @@ export async function inspectAgentHost(input) {
 export async function reconcileAgentHostTurn(input) {
     // Periodic observation must not hold the scheduler behind an unavailable Host.
     // A timeout is only an observation failure, never permission to submit again.
-    return exchangeAgentHostControl(agentHostControlSocketPath(input), input.control, 1_000);
+    const path = agentHostControlSocketPath(input);
+    const observed = await exchangeAgentHostControl(path, {
+        protocol: AGENT_HOST_CONTROL_PROTOCOL, type: "status"
+    }, 1_000);
+    if (observed.outcome === "rejected")
+        return observed;
+    if (!observed.snapshot.controlCapabilities?.includes("reconcile-turn")) {
+        // Older v1 Hosts still serve status and their immutable Inbox remains
+        // consumable. Neither idle nor absent eventDelivery proves a terminal.
+        return { ...observed, reconciliation: "unsupported" };
+    }
+    return exchangeAgentHostControl(path, input.control, 1_000);
 }
 export async function waitForAgentHostLaunchAck(input) {
     const deadline = Date.now() + (input.timeoutMs ?? AGENT_HOST_READY_TIMEOUT_MS);
@@ -1696,6 +1738,11 @@ export async function openAgentHostControl(home, payload, snapshot, dispatch) {
                         ...result,
                         snapshot: {
                             ...result.snapshot,
+                            hostImplementation: AGENT_HOST_IMPLEMENTATION,
+                            controlCapabilities: payload.providerControl === undefined ? ["status"] : [
+                                "status", "launch", "submit-turn", "steer-turn", "cancel", "set-authority",
+                                "native-open", "native-respond", "native-model", "reconcile-turn"
+                            ],
                             ...(!["task", "global"].includes(payload.environment.YUI_SESSION_SCOPE ?? "") ? {} : {
                                 eventDelivery: structuredProviderEventDelivery(home, payload.environment, result.snapshot.nativeSessionId)
                             })
@@ -1956,6 +2003,11 @@ function validateSnapshot(snapshot) {
         && snapshot.inputAcceptance !== "provider" && snapshot.inputAcceptance !== "transport") {
         throw new Error("Agent Host input acceptance evidence is invalid.");
     }
+    if (snapshot.controlCapabilities !== undefined && (!Array.isArray(snapshot.controlCapabilities) || snapshot.controlCapabilities.length > 64
+        || snapshot.controlCapabilities.some(value => typeof value !== "string"
+            || value.length === 0 || value.length > 64 || value.includes("\0")))) {
+        throw new Error("Agent Host control capability advertisement is invalid.");
+    }
     const authorityFields = [
         snapshot.authorityEpoch,
         snapshot.authorityOwner,

package/dist/runtime/agentHostImplementation.js

@@ -0,0 +1,18 @@
+import { createHash } from "node:crypto";
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { detectRunningRelease } from "../release/runtimeRelease.js";
+// Capture once when this process loads its Host bridge. Never label a live
+// process with the installation currently on disk at status-query time.
+const release = detectRunningRelease(fileURLToPath(import.meta.url));
+const modules = [
+    "agentHost.js", "agentHostProtocol.js", "agentHostImplementation.js",
+    "codexInteractiveHost.js", "../controller/structuredProviderObservation.js",
+    "../controller/runtimeEventInbox.js"
+];
+export const AGENT_HOST_IMPLEMENTATION = Object.freeze({
+    id: "yui.agent-host",
+    generation: release?.manifest.packageDigest ?? `checkout-${createHash("sha256")
+        .update(modules.map(module => `${module}\0${readFileSync(new URL(module, import.meta.url), "utf8")}`).join("\0"))
+        .digest("hex")}`
+});

package/dist/runtime/managedCaller.js

@@ -16,12 +16,31 @@ export function requireManagedGlobalCaller(store, env) {
         || !role || !binding || !set || !session || session.status !== "active"
         || set.activeAgentId !== role.activeAgentId || session.agentId !== binding.agentId
         || session.adapterId !== binding.adapterId || nativeSessionId !== session.nativeSessionId
+        || (env.YUI_WORKSPACE !== undefined && env.YUI_WORKSPACE !== session.effective.workspace.root)
         || (env.YUI_AGENT_ID !== undefined && env.YUI_AGENT_ID !== session.agentId)
         || (env.YUI_ADAPTER_ID !== undefined && env.YUI_ADAPTER_ID !== session.adapterId)) {
         throw new ManagedRuntimeDriftError("This command requires the current managed global native Session; the previous Session has no write authority.");
     }
     return { roleName: role.name, agentId: session.agentId, adapterId: session.adapterId, nativeSessionId };
 }
+/** Historical self diagnostics remain readable, but never authorize inbox
+ * handling, configuration, another Role's records, or lifecycle mutation. */
+export function requireManagedGlobalReader(store, env) {
+    try {
+        requireManagedGlobalCaller(store, env);
+        return;
+    }
+    catch (error) {
+        const set = env.YUI_ROLE === undefined ? null : store.getGlobalRoleSessionSet(env.YUI_ROLE);
+        const known = [...Object.values(set?.sessions ?? {}), ...Object.values(set?.history ?? {})].some(session => session.nativeSessionId === identity(session.adapterId === "codex"
+            ? env.CODEX_THREAD_ID ?? env.YUI_NATIVE_SESSION_ID : env.YUI_NATIVE_SESSION_ID)
+            && (env.YUI_AGENT_ID === undefined || env.YUI_AGENT_ID === session.agentId)
+            && (env.YUI_ADAPTER_ID === undefined || env.YUI_ADAPTER_ID === session.adapterId)
+            && (env.YUI_WORKSPACE === undefined || env.YUI_WORKSPACE === session.effective.workspace.root));
+        if (env.YUI_SESSION_SCOPE !== "global" || env.YUI_TASK_ID !== undefined || !known)
+            throw error;
+    }
+}
 /**
  * A managed Session presented valid self-identity but is no longer the current
  * runtime of its Task Role. This is a bounded diagnosis rather than a bare
@@ -62,7 +81,12 @@ export function resolveManagedTaskCaller(store, environment) {
     const self = managedTaskSessionIdentity(environment);
     if (self === undefined)
         return undefined;
-    return requireCurrentRuntime(store, self);
+    const caller = requireCurrentRuntime(store, self);
+    if (environment?.YUI_AGENT_ID !== undefined && environment.YUI_AGENT_ID !== caller.agentId
+        || environment?.YUI_ADAPTER_ID !== undefined && environment.YUI_ADAPTER_ID !== caller.adapterId) {
+        throw new ManagedRuntimeDriftError("Managed Task Agent/adapter hints conflict with the current native Session.");
+    }
+    return caller;
 }
 /** Same as resolveManagedTaskCaller, but requires a managed Task Session. */
 export function requireManagedTaskCaller(store, environment) {

package/dist/runtime/managedIdentity.js

@@ -2,5 +2,5 @@
  * silently acquire the authority of an unbound public caller. */
 export function hasManagedIdentity(environment) {
     return ["YUI_SESSION_SCOPE", "YUI_ROLE", "YUI_AGENT_ID", "YUI_NATIVE_SESSION_ID",
-        "YUI_TASK_ID", "YUI_SESSION_MANIFEST"].some(key => environment[key] !== undefined);
+        "YUI_TASK_ID", "YUI_SESSION_MANIFEST", "CODEX_THREAD_ID"].some(key => environment[key] !== undefined);
 }

package/dist/runtime/providerRetry.js

@@ -176,7 +176,7 @@ export function providerRetryPrompt(retry, original) {
         original
     ].join("\n");
 }
-/** The same presentation is consumed by CLI, Context and Web. */
+/** The same presentation is consumed by explicit detail reads and Web. */
 export function providerRetryProjection(binding) {
     const retry = binding?.retry;
     if (retry === undefined)
@@ -209,6 +209,24 @@ export function providerRetryProjection(binding) {
         ...(retry.successorRunId === undefined ? {} : { successorRunId: retry.successorRunId })
     };
 }
+/** Entry-point facts, never accumulated retry history or raw diagnostics.
+ * Exact Session retry/show and failureRef retain the original evidence. */
+export function providerRetrySummary(binding) {
+    const view = providerRetryProjection(binding);
+    if (view === null)
+        return null;
+    const { history, error, currentTurn, ...facts } = view;
+    return {
+        ...facts,
+        error: { source: error.source, phase: error.phase, category: error.category,
+            code: error.code, inputDisposition: error.inputDisposition,
+            sessionDisposition: error.sessionDisposition, retryable: error.retryable },
+        currentTurn: currentTurn === null ? null : {
+            attemptId: currentTurn.attemptId, status: currentTurn.status, nativeTurnId: currentTurn.nativeTurnId
+        },
+        historyCount: history.length, detailOmitted: true
+    };
+}
 export function controlProviderRetry(binding, action, at) {
     if (action === "enable")
         return { ...binding, retryDisabled: false };

package/dist/runtime/sessionCaller.js

@@ -0,0 +1,53 @@
+import { hasManagedIdentity } from "./managedIdentity.js";
+import { ManagedRuntimeDriftError, requireManagedGlobalCaller, requireManagedTaskCaller } from "./managedCaller.js";
+/** Resolve location from this Home's registry, not from a launch environment.
+ * The returned hints are not authority: consumers still validate the current
+ * binding (including revocation, Assignment and captured workspace).
+ * Native children with their own Codex thread cannot borrow a parent's hints.
+ */
+export function sessionCallerEnvironment(store, env) {
+    const native = env.CODEX_THREAD_ID ?? env.YUI_NATIVE_SESSION_ID;
+    if (native === undefined) {
+        if (hasManagedIdentity(env))
+            throw new ManagedRuntimeDriftError("Managed Session identity has no native session id.");
+        return env;
+    }
+    if (!native || native.trim() !== native || native.includes("\0")) {
+        throw new ManagedRuntimeDriftError("Managed native Session identity is invalid.");
+    }
+    // Reuse the existing derived active-Session inventory; no new identity index
+    // or scan of every Task body/history is needed.
+    const matches = store.listRuntimeSessionCandidates().filter(session => session.nativeSessionId === (session.adapterId === "codex" ? env.CODEX_THREAD_ID ?? env.YUI_NATIVE_SESSION_ID : env.YUI_NATIVE_SESSION_ID));
+    if (matches.length !== 1) {
+        throw new ManagedRuntimeDriftError(matches.length
+            ? "Native Session identity is ambiguous in this YUI_HOME; no caller authority was selected."
+            : "Native Session is not registered in this YUI_HOME; refusing to infer public user authority.");
+    }
+    const match = matches[0];
+    const set = match.owner.scope === "global" ? store.getGlobalRoleSessionSet(match.owner.roleName)
+        : store.getTaskRoleSessionSet(match.owner.taskId, match.owner.roleName);
+    const session = set?.sessions[match.agentId];
+    if (set === null || session === undefined || session.nativeSessionId !== match.nativeSessionId) {
+        throw new ManagedRuntimeDriftError("Native Session registration changed during caller resolution; read current state again.");
+    }
+    const hints = {
+        YUI_SESSION_SCOPE: set.owner.scope, YUI_ROLE: set.owner.roleName,
+        YUI_AGENT_ID: session.agentId, YUI_ADAPTER_ID: session.adapterId,
+        YUI_WORKSPACE: session.effective.workspace.root,
+        ...(set.owner.scope === "task" ? { YUI_TASK_ID: set.owner.taskId } : {})
+    };
+    for (const key of [...Object.keys(hints), "YUI_TASK_ID"]) {
+        if (env[key] !== undefined && env[key] !== hints[key]) {
+            throw new ManagedRuntimeDriftError(`Managed Session hint ${key} conflicts with this Home's native Session registration.`);
+        }
+    }
+    return { ...env, ...hints };
+}
+/** One current caller for inbox and other own-address operations. */
+export function requireManagedCaller(store, env) {
+    const current = sessionCallerEnvironment(store, env);
+    if (current.YUI_SESSION_SCOPE === "global") {
+        return { scope: "global", ...requireManagedGlobalCaller(store, current) };
+    }
+    return { scope: "task", ...requireManagedTaskCaller(store, current) };
+}

package/dist/storage/contextRecords.js

@@ -58,6 +58,34 @@ export function queryContextRecords(db, taskId, query) {
         where.push(`${id} IN (SELECT value FROM json_each(@ids))`);
         params.ids = JSON.stringify(query.ids);
     }
+    if (query.unhandledMessages) {
+        if (query.family !== "task-message")
+            throw new Error("Unhandled selection requires Messages.");
+        where.push(`json_extract(r.payload, '$.inbox.ack') IS NULL`);
+        where.push(`NOT EXISTS (SELECT 1 FROM events e WHERE e.task_id = r.task_id
+      AND e.type = 'task.record-retired'
+      AND json_extract(e.payload, '$.payload.recordKind') = 'message'
+      AND json_extract(e.payload, '$.payload.recordId') = r.message_id)`);
+        // Match taskMessageInboxReceipt: a direct claim owns the Message, otherwise
+        // a wake receipt covers its exact reference and latest revision event.
+        where.push(`(json_extract(r.payload, '$.inbox') IS NOT NULL OR (
+      SELECT json_extract(w.payload, '$.inbox.ack') FROM task_wakes w
+      WHERE w.task_id = r.task_id AND json_extract(w.payload, '$.inbox') IS NOT NULL
+        AND EXISTS (SELECT 1 FROM json_each(w.payload, '$.refs') ref
+          WHERE json_extract(ref.value, '$.type') = 'message'
+            AND json_extract(ref.value, '$.taskId') = r.task_id
+            AND json_extract(ref.value, '$.id') = r.message_id)
+        AND (NOT EXISTS (SELECT 1 FROM events e WHERE e.task_id = r.task_id AND e.type = 'message.updated'
+          AND json_extract(e.payload, '$.payload.messageId') = r.message_id)
+        OR EXISTS (SELECT 1 FROM json_each(w.payload, '$.refs') update_ref
+          WHERE json_extract(update_ref.value, '$.type') = 'event'
+            AND json_extract(update_ref.value, '$.taskId') = r.task_id
+            AND json_extract(update_ref.value, '$.id') = (
+              SELECT e.event_id FROM events e WHERE e.task_id = r.task_id AND e.type = 'message.updated'
+                AND json_extract(e.payload, '$.payload.messageId') = r.message_id
+              ORDER BY CAST(substr(e.event_id, 7) AS INTEGER) DESC LIMIT 1)))
+      ORDER BY w.seq ASC LIMIT 1) IS NULL)`);
+    }
     for (const [label, statuses, not] of [
         ["statuses", query.statuses, ""],
         ["excludeStatuses", query.excludeStatuses, "NOT"]