@zq-silk/yui 2.6.0 → 2.8.0

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/nativeAgent/session/backends.js

@@ -1,4 +1,4 @@
-import Database from 'better-sqlite3';
+import Database from "../../sqlite/driver.js";
 import { randomUUID } from 'node:crypto';
 import { isAbsolute, resolve } from 'node:path';
 import { existsSync, lstatSync } from 'node:fs';

package/dist/observability/runtimeIdentity.js

@@ -12,7 +12,7 @@ import { createHash } from "node:crypto";
 import { spawnSync } from "node:child_process";
 import { existsSync, readdirSync, readFileSync, realpathSync, statSync } from "node:fs";
 import { join } from "node:path";
-import Database from "better-sqlite3";
+import Database from "../sqlite/driver.js";
 import { CURRENT_STORAGE_VERSION, MIN_SUPPORTED_STORAGE_VERSION } from "../storage/storageVersions.js";
 import { inspectStorageSchema } from "../storage/storageSchema.js";
 import { resolveStoreWorkerEnabledForHome } from "../storage/storeRpc.js";

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/resources/sqliteResourceRegistry.js

@@ -13,7 +13,7 @@
 import { existsSync } from "node:fs";
 import { join } from "node:path";
 import { isDeepStrictEqual } from "node:util";
-import Database from "better-sqlite3";
+import Database from "../sqlite/driver.js";
 import { validateSqliteSchema } from "../storage/sqliteSchema.js";
 import { emptyResourceRegistry, parseResourceRegistryState } from "./resourceRegistry.js";
 import { RESOURCE_REGISTRY_SCHEMA_VERSION } from "./resourceTypes.js";

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";
@@ -93,6 +94,9 @@ export async function runAgentHost(input) {
     let activeRunPayload;
     let lastTerminalPayload;
     let lastTerminal;
+    // One exact direct Turn witnessed by this Endpoint under its original fence.
+    // This is recovery evidence, never ownership of the Desktop client's input.
+    let directObservation;
     let activeRunAttemptId;
     let activeNativeTurnId;
     let codexClientAttachedAt;
@@ -166,6 +170,7 @@ export async function runAgentHost(input) {
     const handleStarted = (started, observedPayload = sessionPayload) => {
         if (started.clientOwned || observedPayload === undefined)
             return;
+        const observedAuthority = authority === undefined ? undefined : { ...authority };
         updateSnapshot(hostSnapshot("busy", {
             adapterId: observedPayload.providerControl?.adapterId,
             processInstanceId: session?.processInstanceId,
@@ -175,6 +180,25 @@ export async function runAgentHost(input) {
             ...authorityFields()
         }));
         void enqueueSerialized(async () => {
+            // Desktop can start another Turn before the Controller's periodic pass.
+            // Persist the previous exact terminal before replacing its bounded cache
+            // or publishing the new start. Never clear the newer native writer.
+            const previous = directObservation;
+            if (previous?.terminal !== undefined && authority !== undefined
+                && sameProviderAuthorityFence(previous.authority, authority)
+                && 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
+                && started.conversationId === session.conversationId && observedAuthority !== undefined
+                && authority !== undefined && sameProviderAuthorityFence(observedAuthority, authority)) {
+                directObservation = { started, payload: observedPayload, authority: observedAuthority };
+            }
             await publishStructuredProviderStarted({
                 home: input.home,
                 environment: observedPayload.environment,
@@ -194,6 +218,14 @@ export async function runAgentHost(input) {
             // AgentRun audit record. It has no WorkItem ownership and no managed input
             // fence; the runtime observer records only visible input/output.
             void enqueueSerialized(async () => {
+                const direct = directObservation;
+                if (direct !== undefined && authority !== undefined
+                    && sameProviderAuthorityFence(direct.authority, authority)
+                    && direct.started.nativeSessionId === terminal.nativeSessionId
+                    && direct.started.conversationId === terminal.conversationId
+                    && direct.started.nativeTurnId === terminal.nativeTurnId) {
+                    direct.terminal = terminal;
+                }
                 await publishStructuredProviderTerminal({
                     home: input.home,
                     environment: busyPayload.environment,
@@ -274,6 +306,7 @@ export async function runAgentHost(input) {
                     conversationId: terminal.conversationId,
                     ...authorityFields()
                 }));
+                signalRoleMailbox(input.home, currentPayload);
                 promptHuman();
             }
             catch (error) {
@@ -565,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.");
         }
@@ -595,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;
@@ -609,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"
@@ -621,6 +654,7 @@ export async function runAgentHost(input) {
                 await recordProviderConnection(input.home, next, started.session);
                 lastTerminalPayload = undefined;
                 lastTerminal = undefined;
+                directObservation = undefined;
                 // Recoverable means a later process can rebind this Conversation by
                 // its native id. The Endpoint answers that from the Driver capability
                 // or, where the protocol settles it per connection, from what this
@@ -756,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.",
@@ -1012,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.");
         }
@@ -1088,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.");
@@ -1157,6 +1196,73 @@ export async function runAgentHost(input) {
             }
             return controlResult("accepted", { ...snapshot, nativeTui: !!nativeTui });
         }
+        if (request.type === "reconcile-turn") {
+            if (session === undefined || session.nativeSessionId !== request.nativeSessionId
+                || 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
+                && request.attemptId === `direct:${request.nativeTurnId}`
+                && direct.started.nativeTurnId === request.nativeTurnId
+                && direct.started.nativeSessionId === request.nativeSessionId
+                && sameProviderAuthorityFence(direct.authority, request.authority);
+            const terminal = directMatch ? direct.terminal : lastTerminal;
+            const terminalPayload = directMatch ? direct.payload : lastTerminalPayload;
+            if (terminal === undefined || terminalPayload === undefined
+                || terminal.nativeSessionId !== request.nativeSessionId
+                || !directMatch && (terminal.clientOwned !== true || terminal.attemptId !== request.attemptId)
+                || request.nativeTurnId !== undefined && terminal.nativeTurnId !== request.nativeTurnId) {
+                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.
+            await enqueueSerialized(async () => {
+                if (session?.nativeSessionId !== request.nativeSessionId || authority === undefined
+                    || !sameProviderAuthorityFence(authority, request.authority)
+                    || directMatch && directObservation !== direct) {
+                    throw new Error("Session changed before terminal reconciliation.");
+                }
+                await publishStructuredProviderTerminal({
+                    home: input.home, environment: terminalPayload.environment, terminal
+                });
+                if (!directMatch && activeRunAttemptId === terminal.attemptId) {
+                    activeRunPayload = undefined;
+                    activeRunAttemptId = undefined;
+                    activeNativeTurnId = undefined;
+                    updateSnapshot(hostSnapshot(session.inspect().activeNativeTurnId === undefined ? "idle" : "busy", {
+                        adapterId: session.adapterId, processInstanceId: session.processInstanceId,
+                        nativeSessionId: session.nativeSessionId, conversationId: session.conversationId,
+                        ...authorityFields()
+                    }));
+                }
+                signalRoleMailbox(input.home, terminalPayload);
+            });
+            return { ...controlResult("status", snapshot), reconciliation: "terminal-republished" };
+        }
         if (request.type === "status") {
             // Read the Agent's configuration at answer time, not from the stored
             // snapshot. The Agent may have changed it since the last state
@@ -1461,6 +1567,22 @@ export async function inspectAgentHost(input) {
     });
     return result.snapshot;
 }
+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.
+    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);
     let lastError;
@@ -1616,7 +1738,12 @@ export async function openAgentHostControl(home, payload, snapshot, dispatch) {
                         ...result,
                         snapshot: {
                             ...result.snapshot,
-                            ...(payload.environment.YUI_SESSION_SCOPE !== "task" ? {} : {
+                            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)
                             })
                         }
@@ -1691,7 +1818,8 @@ function boundControlResponse(result) {
     // visible through an otherwise successful status request.
     result = {
         ...controlResult(result.outcome, validateSnapshot(result.snapshot), result.failure === undefined ? undefined : providerDeliveryFailure(result.failure)),
-        ...(result.cancellation === undefined ? {} : { cancellation: result.cancellation })
+        ...(result.cancellation === undefined ? {} : { cancellation: result.cancellation }),
+        ...(result.reconciliation === undefined ? {} : { reconciliation: result.reconciliation })
     };
     if (withinControlBound(result))
         return result;
@@ -1709,29 +1837,29 @@ function boundControlResponse(result) {
     };
     // Never make an omitted option list look like a complete empty enumeration.
     if (result.snapshot.runConfiguration?.status === "observed") {
-        result = controlResult(result.outcome, validateSnapshot({
-            ...result.snapshot,
-            runConfiguration: unknownAgentRunConfiguration("The Agent's reported configuration is too large for the Agent Host "
-                + "control response, so it could not be carried in full and none of it "
-                + "is shown rather than part of it.")
-        }), result.failure);
+        result = { ...result, ...controlResult(result.outcome, validateSnapshot({
+                ...result.snapshot,
+                runConfiguration: unknownAgentRunConfiguration("The Agent's reported configuration is too large for the Agent Host "
+                    + "control response, so it could not be carried in full and none of it "
+                    + "is shown rather than part of it.")
+            }), result.failure) };
         if (withinControlBound(result))
             return result;
     }
-    let bounded = controlResult(result.outcome, {
-        ...result.snapshot,
-        ...(result.snapshot.detail === undefined ? {} : { detail: clip(result.snapshot.detail, 1200) })
-    }, result.failure === undefined ? undefined : { ...result.failure, detail: clip(result.failure.detail, 1200) });
+    let bounded = { ...result, ...controlResult(result.outcome, {
+            ...result.snapshot,
+            ...(result.snapshot.detail === undefined ? {} : { detail: clip(result.snapshot.detail, 1200) })
+        }, result.failure === undefined ? undefined : { ...result.failure, detail: clip(result.failure.detail, 1200) }) };
     const raw = bounded.failure?.raw;
     if (withinControlBound(bounded) || raw === undefined)
         return bounded;
     let chars = raw.length;
     while (!withinControlBound(bounded) && chars > 0) {
         chars = Math.floor(chars / 2);
-        bounded = controlResult(bounded.outcome, bounded.snapshot, {
-            ...bounded.failure,
-            raw: clip(raw, chars)
-        });
+        bounded = { ...bounded, ...controlResult(bounded.outcome, bounded.snapshot, {
+                ...bounded.failure,
+                raw: clip(raw, chars)
+            }) };
     }
     return bounded;
 }
@@ -1764,6 +1892,14 @@ function validateControl(control) {
     }
     if (control.type === "status")
         return Object.freeze({ ...control });
+    if (control.type === "reconcile-turn") {
+        validateIdentity(control.nativeSessionId, "native Session id");
+        validateIdentity(control.attemptId, "Provider input attempt id");
+        if (control.nativeTurnId !== undefined)
+            validateIdentity(control.nativeTurnId, "native Turn id");
+        validateProviderAuthorityFence(control.authority);
+        return Object.freeze({ ...control });
+    }
     if (control.type === "native-open" || control.type === "native-respond" || control.type === "native-model") {
         validateIdentity(control.nativeSessionId, "native Session id");
         if (control.type === "native-model" && (typeof control.model !== "string"
@@ -1867,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")}`
+});