@zq-silk/yui 2.21.0 → 2.23.0

package/dist/runtime/codexAppServerRuntime.js

@@ -49,9 +49,10 @@ export class CodexAppServerRuntime {
         const result = await this.transport.request("thread/resume", {
             threadId: id,
             ...(options.cwd === undefined ? {} : { cwd: text(options.cwd, "Codex thread cwd") }),
-            ...threadOptions(options)
+            ...threadOptions(options),
+            excludeTurns: true
         });
-        return parseThreadSnapshot(result, id, true);
+        return this.withLatestTurn(parseThreadSnapshot(result, id, true));
     }
     async setConversationName(input) {
         await this.transport.request("thread/name/set", {
@@ -63,9 +64,81 @@ export class CodexAppServerRuntime {
         const id = text(conversationId, "Codex thread id");
         const result = await this.transport.request("thread/read", {
             threadId: id,
-            includeTurns: options.includeTurns ?? true
+            includeTurns: false
         });
-        return parseThreadSnapshot(result, id, "unknown");
+        const snapshot = parseThreadSnapshot(result, id, "unknown");
+        return options.includeTurns === false ? snapshot : this.withLatestTurn(snapshot);
+    }
+    /** Current execution metadata, never an unbounded transcript hydration. */
+    async withLatestTurn(snapshot) {
+        const page = await this.transport.request("thread/turns/list", {
+            threadId: snapshot.threadId, limit: 1, sortDirection: "desc", itemsView: "notLoaded"
+        });
+        const records = codexPage(page, new Set()).data;
+        if (records.length > 1)
+            throw new Error("Codex latest Turn page exceeded its requested bound.");
+        const turns = records.map(parseTurnSnapshot);
+        const latest = turns[0];
+        return {
+            ...snapshot,
+            // The metadata response may contain no Turns. Do not carry an old active
+            // identity over a separately observed latest Turn.
+            activeTurnId: latest?.status === "inProgress" ? latest.turnId : undefined,
+            latestTurnStatus: latest?.status,
+            turns
+        };
+    }
+    /** Recover only the persisted owned Turn. Scan metadata, then its items,
+     * newest first, stopping at the last nonempty assistant message. A malformed
+     * page or oversized individual item remains an error, never guessed success. */
+    async readTurn(conversationId, turnId) {
+        const threadId = text(conversationId, "Codex thread id");
+        const expectedTurnId = text(turnId, "Codex owned Turn id");
+        const seen = new Set();
+        let cursor;
+        for (;;) {
+            const page = codexPage(await this.transport.request("thread/turns/list", {
+                threadId, limit: 50, sortDirection: "desc", itemsView: "notLoaded",
+                ...(cursor === undefined ? {} : { cursor })
+            }), seen);
+            if (page.data.length > 50)
+                throw new Error("Codex Turn page exceeded its requested bound.");
+            const found = page.data.map(parseTurnSnapshot).find(turn => turn.turnId === expectedTurnId);
+            if (found !== undefined) {
+                if (found.status === "inProgress")
+                    return found;
+                const output = await this.readTurnOutput(threadId, expectedTurnId);
+                return { ...found, ...(output === undefined ? {} : { output }) };
+            }
+            if (page.nextCursor === null)
+                return undefined;
+            cursor = page.nextCursor;
+        }
+    }
+    async readTurnOutput(threadId, turnId) {
+        const seen = new Set();
+        let cursor;
+        for (;;) {
+            const page = codexPage(await this.transport.request("thread/items/list", {
+                threadId, turnId, limit: 1, sortDirection: "desc",
+                ...(cursor === undefined ? {} : { cursor })
+            }), seen);
+            if (page.data.length > 1)
+                throw new Error("Codex item page exceeded its requested bound.");
+            for (const value of page.data) {
+                const entry = object(value);
+                const item = object(entry?.item);
+                if (entry?.turnId !== turnId || item === null) {
+                    throw new Error("Codex item page does not belong to the owned Turn.");
+                }
+                if (item.type === "agentMessage" && typeof item.text === "string" && item.text.trim().length > 0) {
+                    return item.text;
+                }
+            }
+            if (page.nextCursor === null)
+                return undefined;
+            cursor = page.nextCursor;
+        }
     }
     async readGoal(conversationId) {
         const id = text(conversationId, "Codex thread id");
@@ -98,6 +171,7 @@ export class CodexAppServerRuntime {
         return this.startTurn({
             conversationId: input.conversationId,
             text: input.text,
+            ...(input.additionalContext === undefined ? {} : { additionalContext: input.additionalContext }),
             expectedNoActiveTurn: input.expectedNoActiveTurn,
             ...(input.requireQuiescent ? { requireQuiescent: true } : {}),
             ...(input.expectedFailedNativeTurnId === undefined ? {} : {
@@ -157,6 +231,7 @@ export class CodexAppServerRuntime {
         try {
             const result = await this.transport.request("turn/start", {
                 threadId,
+                ...(input.additionalContext === undefined ? {} : { additionalContext: input.additionalContext }),
                 ...(input.clientUserMessageId === undefined
                     ? {}
                     : { clientUserMessageId: text(input.clientUserMessageId, "Codex input attempt id") }),
@@ -192,6 +267,7 @@ export class CodexAppServerRuntime {
         try {
             const result = await this.transport.request("turn/steer", {
                 threadId,
+                ...(input.additionalContext === undefined ? {} : { additionalContext: input.additionalContext }),
                 expectedTurnId,
                 ...(input.clientUserMessageId === undefined
                     ? {}
@@ -330,26 +406,7 @@ function parseThreadSnapshot(result, expectedThreadId, loaded) {
         throw new Error("Codex thread status is missing or unsupported.");
     if (!Array.isArray(thread.turns))
         throw new Error("Codex thread turns are missing or invalid.");
-    const turnSnapshots = thread.turns.map((value) => {
-        const turn = object(value);
-        if (turn === null)
-            throw new Error("Codex thread contains an invalid Turn.");
-        const turnId = text(optionalId(turn.id), "Codex response Turn id");
-        const status = optionalTurnStatus(turn.status);
-        if (status === undefined)
-            throw new Error("Codex Turn status is missing or unsupported.");
-        const output = codexTurnOutput(turn);
-        const error = providerError(turn.error);
-        return {
-            turnId,
-            status,
-            ...(output === undefined ? {} : { output }),
-            ...(error === undefined ? {} : { error }),
-            ...(turn.error === undefined || turn.error === null ? {} : {
-                rawError: serializeAgentErrorRaw(turn.error)
-            })
-        };
-    });
+    const turnSnapshots = thread.turns.map(parseTurnSnapshot);
     const active = [...turnSnapshots].reverse().find((turn) => turn.status === "inProgress");
     const latestStatus = turnSnapshots.at(-1)?.status;
     return {
@@ -365,6 +422,38 @@ function parseThreadSnapshot(result, expectedThreadId, loaded) {
         raw: result
     };
 }
+function parseTurnSnapshot(value) {
+    const turn = object(value);
+    if (turn === null)
+        throw new Error("Codex thread contains an invalid Turn.");
+    const turnId = text(optionalId(turn.id), "Codex response Turn id");
+    const status = optionalTurnStatus(turn.status);
+    if (status === undefined)
+        throw new Error("Codex Turn status is missing or unsupported.");
+    const output = codexTurnOutput(turn);
+    const error = providerError(turn.error);
+    return {
+        turnId,
+        status,
+        ...(output === undefined ? {} : { output }),
+        ...(error === undefined ? {} : { error }),
+        ...(turn.error === undefined || turn.error === null ? {} : {
+            rawError: serializeAgentErrorRaw(turn.error)
+        })
+    };
+}
+function codexPage(page, seen) {
+    if (!Array.isArray(page.data)
+        || !(page.nextCursor === null || typeof page.nextCursor === "string" && page.nextCursor.length > 0)) {
+        throw new Error("Codex history page is missing data or its continuation boundary.");
+    }
+    if (typeof page.nextCursor === "string") {
+        if (seen.has(page.nextCursor))
+            throw new Error("Codex history cursor repeated.");
+        seen.add(page.nextCursor);
+    }
+    return { data: page.data, nextCursor: page.nextCursor };
+}
 /** Extract the last assistant message from one native Codex Turn without rewriting it. */
 export function codexTurnOutput(turn) {
     for (const value of [...arrayMember(turn, "items")].reverse()) {

package/dist/runtime/codexInteractiveHost.js

@@ -4,6 +4,11 @@ import { once } from "node:events";
 import WebSocket, { WebSocketServer } from "ws";
 import { AGENT_HOST_CONTROL_PROTOCOL } from "./agentHostProtocol.js";
 import { openCodexInteractiveConnection } from "./structuredProviderHost.js";
+import { createSessionSkillNotice, createSessionSkillLifecycleCheck } from "../context/sessionSkillNotice.js";
+import { isNativeContextRecovery } from "./contextRecovery.js";
+import { createHostSessionLifecycle } from "./hostSessionLifecycle.js";
+import { createNonBlockingChecks } from "./lifecycleChecks.js";
+import { createNativeTitleSync } from "./nativeTitleSync.js";
 /**
  * Keep the native TUI and its transparent App Server attachment in one pane.
  * The existing Host acknowledgement carries the ID from that TUI's exact
@@ -15,6 +20,8 @@ import { openCodexInteractiveConnection } from "./structuredProviderHost.js";
  */
 export async function runCodexInteractiveHost(home, payload, openAgentHostControl) {
     const environment = payload.environment;
+    const skillNotice = createSessionSkillNotice(home);
+    const pendingNotices = new Map();
     if (environment.YUI_SESSION_SCOPE !== "global" || environment.YUI_ADAPTER_ID !== "codex"
         || payload.providerControl !== undefined) {
         throw new Error("Interactive Codex Host requires a global native TUI launch.");
@@ -28,8 +35,19 @@ export async function runCodexInteractiveHost(home, payload, openAgentHostContro
         throw new Error("Codex proxy base arguments are invalid.");
     }
     const expectedId = environment.YUI_NATIVE_SESSION_ID;
+    const lifecycleChecks = createNonBlockingChecks([createSessionSkillLifecycleCheck(home, () => environment)], error => process.stderr.write(`Session lifecycle check failed: ${String(error)}\n`));
+    const lifecycle = createHostSessionLifecycle({ after: lifecycleChecks });
+    lifecycle.send({ type: "launch" });
     let snapshot = {
-        schemaVersion: 1, state: "starting", adapterId: "codex", updatedAt: new Date().toISOString()
+        schemaVersion: 1, state: lifecycle.state, adapterId: "codex", updatedAt: new Date().toISOString()
+    };
+    const transition = (event, fields = {}) => {
+        const result = lifecycle.send(event);
+        if (result.status === "ignored")
+            return;
+        if (result.status === "invalid")
+            throw new Error(result.reason);
+        snapshot = { ...snapshot, ...fields, state: result.state, updatedAt: new Date().toISOString() };
     };
     const control = await openAgentHostControl(home, payload, () => snapshot, async (request) => {
         if (request.type !== "status") {
@@ -41,6 +59,9 @@ export async function runCodexInteractiveHost(home, payload, openAgentHostContro
     let client;
     let closing = false;
     let startupRequestId;
+    let initializeRequestId;
+    let nativeAccountHome;
+    let titleSync;
     let connection;
     let relay;
     const signals = ["SIGTERM", "SIGHUP", "SIGINT"];
@@ -48,11 +69,9 @@ export async function runCodexInteractiveHost(home, payload, openAgentHostContro
     const fail = (error) => {
         if (closing || snapshot.state === "failed")
             return;
-        snapshot = {
-            ...snapshot, state: "failed",
-            detail: error instanceof Error ? error.message : String(error),
-            updatedAt: new Date().toISOString()
-        };
+        transition({ type: "failure", outcome: "failed" }, {
+            detail: error instanceof Error ? error.message : String(error)
+        });
         process.stderr.write(`Yui Codex attachment failed: ${snapshot.detail}\n`);
         client?.terminate();
         stop();
@@ -91,6 +110,11 @@ export async function runCodexInteractiveHost(home, payload, openAgentHostContro
                     if (binary)
                         throw new Error("Codex TUI sent a binary App Server request.");
                     const message = jsonObject(JSON.parse(data.toString()));
+                    if (message.method === "thread/name/set")
+                        titleSync?.close();
+                    if (message.method === "initialize"
+                        && (typeof message.id === "string" || typeof message.id === "number"))
+                        initializeRequestId = message.id;
                     if (snapshot.nativeSessionId === undefined
                         && (message.method === "thread/start" || message.method === "thread/resume")) {
                         if (startupRequestId !== undefined)
@@ -106,6 +130,23 @@ export async function runCodexInteractiveHost(home, payload, openAgentHostContro
                         startupRequestId = message.id;
                         message.params = codexInteractiveStartupParameters(payload, params);
                     }
+                    if (message.method === "turn/start" || message.method === "turn/steer") {
+                        if (snapshot.nativeSessionId === undefined)
+                            throw new Error("Skill check requires the reserved native Thread.");
+                        if (typeof message.id !== "string" && typeof message.id !== "number"
+                            || pendingNotices.has(message.id))
+                            throw new Error("Turn input requires a unique correlation id.");
+                        const params = jsonObject(message.params);
+                        if (params.threadId !== snapshot.nativeSessionId)
+                            throw new Error("Turn input targets another Thread.");
+                        const prepared = codexInteractiveSkillInput(skillNotice, environment, snapshot.nativeSessionId, params);
+                        message.params = prepared.params;
+                        pendingNotices.set(message.id, {
+                            commit: prepared.commit,
+                            ...(message.method === "turn/steer" && typeof params.expectedTurnId === "string"
+                                ? { expectedTurnId: params.expectedTurnId } : {})
+                        });
+                    }
                     void connection.send(message).catch(fail);
                 }
                 catch (error) {
@@ -115,6 +156,30 @@ export async function runCodexInteractiveHost(home, payload, openAgentHostContro
         });
         connection.onMessage((message) => {
             try {
+                if (snapshot.nativeSessionId !== undefined
+                    && isNativeContextRecovery("codex", snapshot.nativeSessionId, message))
+                    skillNotice.invalidate();
+                if (message.method === "thread/name/updated"
+                    && message.params?.threadId === snapshot.nativeSessionId)
+                    titleSync?.close();
+                if (message.method === undefined && message.id === initializeRequestId) {
+                    const initialized = message.result;
+                    nativeAccountHome = typeof initialized?.codexHome === "string" ? initialized.codexHome : undefined;
+                    initializeRequestId = undefined;
+                }
+                if (message.method === undefined && (typeof message.id === "string" || typeof message.id === "number")) {
+                    const pending = pendingNotices.get(message.id);
+                    if (pending !== undefined) {
+                        pendingNotices.delete(message.id);
+                        const result = message.result;
+                        const turnId = result?.turn?.id ?? result?.turnId;
+                        if (message.error === undefined && typeof turnId === "string" && turnId.length > 0
+                            && (pending.expectedTurnId === undefined || pending.expectedTurnId === turnId)) {
+                            pending.commit();
+                            titleSync?.notify();
+                        }
+                    }
+                }
                 let nativeSessionId;
                 if (startupRequestId !== undefined && message.id === startupRequestId
                     && message.method === undefined) {
@@ -135,13 +200,17 @@ export async function runCodexInteractiveHost(home, payload, openAgentHostContro
                         fail(error);
                         return;
                     }
-                    if (nativeSessionId === undefined || snapshot.state === "failed")
+                    if (nativeSessionId === undefined || closing || snapshot.state === "failed")
                         return;
                     startupRequestId = undefined;
-                    snapshot = {
-                        ...snapshot, state: "ready", nativeSessionId, conversationId: nativeSessionId,
-                        updatedAt: new Date().toISOString()
-                    };
+                    // Ready here means the native TUI attachment is ready, not a managed
+                    // AgentRun acceptance or proof that the native Thread is idle.
+                    transition({ type: "interactive-connected", nativeSessionId }, {
+                        nativeSessionId, conversationId: nativeSessionId
+                    });
+                    titleSync = createNativeTitleSync(payload, nativeSessionId, nativeAccountHome, result => process.stderr.write(`Native title: ${JSON.stringify(result)}\n`));
+                    if (expectedId !== undefined)
+                        titleSync.notify();
                 });
             }
             catch (error) {
@@ -165,6 +234,7 @@ export async function runCodexInteractiveHost(home, payload, openAgentHostContro
         for (const signal of signals)
             process.on(signal, stop);
         const [code] = await once(child, "exit");
+        transition({ type: "exit" });
         return typeof code === "number" ? code : 1;
     }
     catch (error) {
@@ -172,7 +242,9 @@ export async function runCodexInteractiveHost(home, payload, openAgentHostContro
         throw error;
     }
     finally {
+        lifecycleChecks.close();
         closing = true;
+        titleSync?.close();
         for (const signal of signals)
             process.removeListener(signal, stop);
         stop();
@@ -183,6 +255,25 @@ export async function runCodexInteractiveHost(home, payload, openAgentHostContro
         await control.close();
     }
 }
+/** Keep application metadata out of native user input, including on steer.
+ * Formal titles are synchronized separately; no automatic-title heuristic is assumed. */
+export function codexInteractiveSkillInput(notice, environment, nativeSessionId, params) {
+    if (!Array.isArray(params.input))
+        throw new Error("Turn input must be an array.");
+    const prepared = notice.prepare("", environment, nativeSessionId);
+    return {
+        params: {
+            ...params,
+            ...(prepared.context === undefined ? {} : {
+                additionalContext: {
+                    ...(params.additionalContext == null ? {} : jsonObject(params.additionalContext)),
+                    "yui.session-skills": { kind: "application", value: prepared.context }
+                }
+            })
+        },
+        commit: prepared.commit
+    };
+}
 /** The remote TUI can omit local launch configuration. Apply the reserved
  * workspace and managed identity on its actual startup, never by starting a
  * second Thread or changing daemon-wide configuration. */

package/dist/runtime/codexNativeAccess.js

@@ -5,7 +5,7 @@ const READS = new Set([
     "config/read", "configRequirements/read", "model/list", "collaborationMode/list",
     "experimentalFeature/list", "skills/list", "hooks/list", "mcpServerStatus/list", "account/read",
     "account/rateLimits/read", "modelProvider/capabilities/read", "permissionProfile/list",
-    "thread/read", "thread/turns/list", "thread/items/list", "thread/goal/get"
+    "thread/read", "thread/turns/list", "thread/items/list", "thread/goal/get", "thread/backgroundTerminals/list"
 ]);
 const REQUESTS = new Set([
     "item/commandExecution/requestApproval", "item/fileChange/requestApproval",

package/dist/runtime/contextRecovery.js

@@ -0,0 +1,15 @@
+/** Only explicit, identity-bound native lifecycle events invalidate context.
+ * Absence of an event never proves that instructions are still in memory. */
+export function isNativeContextRecovery(adapter, nativeSessionId, message) {
+    if (adapter === "claude") {
+        return message.type === "system" && message.subtype === "compact_boundary"
+            && message.session_id === nativeSessionId;
+    }
+    const params = message.params;
+    if (!params || params.threadId !== nativeSessionId)
+        return false;
+    if (message.method === "thread/compacted")
+        return true;
+    const item = params.item;
+    return message.method === "item/completed" && item?.type === "contextCompaction";
+}

package/dist/runtime/hostSessionLifecycle.js

@@ -0,0 +1,83 @@
+const live = [
+    "idle", "starting", "ready", "busy", "settling", "delivery-unknown", "rejected", "failed"
+];
+const available = ["idle", "busy", "rejected", "failed"];
+const occupancy = (value) => (event) => "occupancy" in event && event.occupancy === value;
+/** Lifecycle only: no version checks, upgrade phases, I/O or business policy.
+ * Each event selects one guarded edge; callers cannot assign a target state.
+ * Existing authority/admission checks must succeed before sending commands. */
+export const HOST_SESSION_LIFECYCLE_TRANSITIONS = {
+    launch: [{ from: [...available, "exited"], to: "starting" }],
+    submit: [{ from: available, to: "starting" }],
+    connected: [
+        { from: live, guard: occupancy("owned"), to: "ready" },
+        { from: live, guard: occupancy("unknown"), to: "delivery-unknown" },
+        { from: live, guard: occupancy("busy"), to: "busy" },
+        { from: live, guard: occupancy("idle"), to: "idle" }
+    ],
+    accepted: [{ from: ["starting", "ready", "delivery-unknown"], to: "ready" }],
+    "interactive-connected": [{ from: ["starting", "ready"], to: "ready" }],
+    "native-started": [{ from: live, to: "busy" }],
+    terminal: [{ from: ["starting", "ready", "busy", "delivery-unknown", "settling", "failed"], to: "settling" }],
+    settled: [
+        { from: live, guard: occupancy("idle"), to: "idle" },
+        { from: live, guard: occupancy("busy"), to: "busy" }
+    ],
+    disconnected: [{ from: live, to: "starting" }],
+    "authority-changed": [{ from: available, to: "idle" }],
+    failure: ["busy", "delivery-unknown", "rejected", "failed"].map(outcome => ({
+        from: live, guard: event => event.type === "failure" && event.outcome === outcome, to: outcome
+    })),
+    exit: [{ from: live, to: "exited" }]
+};
+export function createHostSessionLifecycle(hooks = {}) {
+    let state = "idle";
+    let revision = 0;
+    let identity = {};
+    const edgeFor = (event) => HOST_SESSION_LIFECYCLE_TRANSITIONS[event.type].find(rule => rule.from.includes(state) && (!rule.guard || rule.guard(event)));
+    return {
+        get state() { return state; },
+        get revision() { return revision; },
+        /** State eligibility only; caller still owns exact writer/resource guards. */
+        can(event) { return edgeFor(event) !== undefined; },
+        send(input) {
+            const event = Object.freeze({ ...input });
+            if (state === "exited" && event.type !== "launch")
+                return { status: "ignored", state, reason: "exited" };
+            if (!["launch", "connected"].includes(event.type)) {
+                for (const key of ["processInstanceId", "nativeSessionId"]) {
+                    if (identity[key] && event[key] && identity[key] !== event[key]) {
+                        return { status: "ignored", state, reason: `stale-${key}` };
+                    }
+                }
+                if (["accepted", "terminal"].includes(event.type)
+                    && identity.attemptId && event.attemptId && identity.attemptId !== event.attemptId) {
+                    return { status: "ignored", state, reason: "stale-attempt" };
+                }
+                if (event.type === "terminal" && identity.nativeTurnId && event.nativeTurnId
+                    && identity.nativeTurnId !== event.nativeTurnId) {
+                    return { status: "ignored", state, reason: "stale-turn" };
+                }
+            }
+            const edge = edgeFor(event);
+            if (!edge)
+                return { status: "invalid", state, reason: `No ${event.type} edge from ${state}` };
+            const transition = Object.freeze({ from: state, to: edge.to, revision: revision + 1, event });
+            hooks.before?.notify(transition);
+            state = edge.to;
+            revision += 1;
+            // A new authorized attachment must not inherit the departed proxy's
+            // identity fence. A launch reusing a live connection supplies its IDs.
+            if (event.type === "launch")
+                identity = {};
+            identity = {
+                processInstanceId: event.processInstanceId ?? identity.processInstanceId,
+                nativeSessionId: event.nativeSessionId ?? identity.nativeSessionId,
+                attemptId: event.attemptId,
+                nativeTurnId: event.nativeTurnId
+            };
+            hooks.after?.notify(transition);
+            return { status: "applied", state };
+        }
+    };
+}

package/dist/runtime/hostUpgradeGate.js

@@ -0,0 +1,43 @@
+/** Host-local input admission fence. The existing lifecycle mailbox owns the
+ * durable request; this gate owns only the actual loaded process's drain. */
+export function createHostUpgradeGate() {
+    let current;
+    let draining;
+    return {
+        get observation() { return current; },
+        get fenced() { return current !== undefined; },
+        request(fence, identity) {
+            if (fence.nativeSessionId !== identity.nativeSessionId
+                || fence.processInstanceId !== identity.processInstanceId
+                || fence.hostGeneration !== identity.hostGeneration)
+                throw new Error("Host upgrade identity changed.");
+            if (current && (fence.requestId !== current.requestId || fence.nativeSessionId !== current.nativeSessionId
+                || fence.processInstanceId !== current.processInstanceId || fence.hostGeneration !== current.hostGeneration)) {
+                throw new Error("Host already holds a different upgrade request.");
+            }
+            current ??= { requestId: fence.requestId, nativeSessionId: fence.nativeSessionId,
+                processInstanceId: fence.processInstanceId, hostGeneration: fence.hostGeneration, state: "waiting" };
+        },
+        async drain(input) {
+            if (!current || current.state !== "waiting")
+                return;
+            if (input.busy || input.events.pending !== 0 || input.events.pendingTerminals !== 0
+                || input.events.unpersisted !== 0 || input.events.failure !== undefined)
+                return;
+            draining ??= (async () => {
+                try {
+                    if (!await input.checkQuiescent())
+                        return;
+                    await input.release();
+                    current = { ...current, state: "drained" };
+                }
+                catch (error) {
+                    current = { ...current, state: "failed",
+                        detail: error instanceof Error ? error.message : String(error) };
+                }
+            })();
+            await draining;
+            draining = undefined;
+        }
+    };
+}

package/dist/runtime/lifecycleChecks.js

@@ -0,0 +1,47 @@
+export function createNonBlockingChecks(checks, onError = () => { }) {
+    if (new Set(checks.map(check => check.id)).size !== checks.length)
+        throw new Error("Duplicate lifecycle check id.");
+    const abort = new AbortController();
+    const lanes = checks.map(check => ({ check, running: false, pending: undefined }));
+    const launch = (lane) => {
+        if (lane.running || abort.signal.aborted)
+            return;
+        lane.running = true;
+        // Defer even synchronous callbacks until the caller has committed its state.
+        void Promise.resolve().then(async () => {
+            while (lane.pending && !abort.signal.aborted) {
+                const { value } = lane.pending;
+                lane.pending = undefined;
+                try {
+                    await lane.check.run(value, abort.signal);
+                }
+                catch (error) {
+                    try {
+                        onError(error);
+                    }
+                    catch { /* Diagnostics cannot gate lifecycle. */ }
+                }
+            }
+        }).finally(() => {
+            lane.running = false;
+            if (lane.pending)
+                launch(lane);
+        });
+    };
+    return {
+        notify(observation) {
+            if (abort.signal.aborted)
+                return;
+            for (const lane of lanes) {
+                lane.pending = { value: observation };
+                launch(lane);
+            }
+        },
+        get pendingCount() { return lanes.filter(lane => lane.pending !== undefined).length; },
+        close() {
+            abort.abort();
+            for (const lane of lanes)
+                lane.pending = undefined;
+        }
+    };
+}

package/dist/runtime/lifecycleReservation.js

@@ -3,6 +3,9 @@ export const RUNTIME_LIFECYCLE_OWNER = "runtime-lifecycle";
 export const RUNTIME_CLEANUP_REQUIRED_REASON = "runtime-cleanup-required";
 export const RUNTIME_HOST_DETACH_REQUIRED_REASON = "runtime-host-detach-required";
 export const RUNTIME_SESSION_REPLACE_REQUIRED_REASON = "runtime-session-replace-required";
+export const RUNTIME_HOST_UPGRADE_REASON = "runtime-host-upgrade-required";
+export const RUNTIME_HOST_UPGRADE_DRAINED = "runtime-host-upgrade-drained";
+export const RUNTIME_HOST_UPGRADE_FAILED = "runtime-host-upgrade-failed";
 /**
  * A Role runtime lifecycle lane already holds an explicit cleanup obligation.
  * This is scheduler
@@ -48,12 +51,17 @@ export function runtimeCleanupDisposition(mailbox) {
         return "end-session";
     if (reasons.includes(RUNTIME_HOST_DETACH_REQUIRED_REASON))
         return "detach-host";
+    if (reasons.includes(RUNTIME_HOST_UPGRADE_REASON))
+        return "upgrade-host";
     return null;
 }
 export function isRuntimeCleanupReason(reason) {
     return reason === RUNTIME_CLEANUP_REQUIRED_REASON
         || reason === RUNTIME_SESSION_REPLACE_REQUIRED_REASON
-        || reason === RUNTIME_HOST_DETACH_REQUIRED_REASON;
+        || reason === RUNTIME_HOST_DETACH_REQUIRED_REASON
+        || reason === RUNTIME_HOST_UPGRADE_REASON
+        || reason === RUNTIME_HOST_UPGRADE_DRAINED
+        || reason === RUNTIME_HOST_UPGRADE_FAILED;
 }
 export function hasRuntimeLifecycleWork(mailbox) {
     return mailbox !== null && mailboxHasWork(mailbox);

package/dist/runtime/nativeTitleReceipt.js

@@ -0,0 +1,31 @@
+import { createHash } from "node:crypto";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+export function nativeTitleDirectory(home, identity) {
+    const key = createHash("sha256").update(JSON.stringify([
+        identity.scope, identity.taskId ?? null, identity.roleName, identity.agentId, identity.threadId
+    ])).digest("hex");
+    return join(home, "runtime", "native-titles", key);
+}
+export function parseNativeTitleReceipt(text, identity) {
+    const value = JSON.parse(text);
+    if (value.schemaVersion !== 1 || JSON.stringify(value.identity) !== JSON.stringify(identity)
+        || !value.accountHome || !value.attemptId || !value.requestedTitle
+        || !(value.expectedTitle === null || typeof value.expectedTitle === "string")
+        || !["submitted", "confirmed", "unknown", "preserved"].includes(value.status)
+        || !Array.isArray(value.generatedTitles) || value.generatedTitles.some(title => typeof title !== "string")) {
+        throw new Error("Invalid native title receipt; preserve it for diagnosis.");
+    }
+    return value;
+}
+/** Read-only diagnostics can reuse confirmation, never a submitted naming intent.
+ * Unavailable/uncertain evidence supplies no ownership of an existing title. */
+export function confirmedNativeTitles(home, identity) {
+    try {
+        const receipt = parseNativeTitleReceipt(readFileSync(join(nativeTitleDirectory(home, identity), "receipt.json"), "utf8"), identity);
+        return receipt.status === "confirmed" ? receipt.generatedTitles : [];
+    }
+    catch {
+        return [];
+    }
+}