@zq-silk/yui 2.21.0 → 2.23.0

package/dist/controller/hostUpgrade.js

@@ -0,0 +1,344 @@
+import { createHash } from "node:crypto";
+import { isDeepStrictEqual } from "node:util";
+import { isEnabled } from "../role/availability.js";
+import { createWorkMailbox, enqueueSignal, claimPending, completeProcessing, mailboxHasWork } from "../coordination/workMailbox.js";
+import { RUNTIME_HOST_UPGRADE_REASON, RUNTIME_HOST_UPGRADE_DRAINED as DRAINED, RUNTIME_HOST_UPGRADE_FAILED as FAILED, runtimeLifecycleTarget, runtimeCleanupDisposition } from "../runtime/lifecycleReservation.js";
+const SOURCE = "host-upgrade/v1:";
+/** Reuse the durable role-runtime lane and its fixed claim/settlement contract.
+ * The versioned signal source is a bounded exact request, not a second queue
+ * or writable Session state. No environment, credentials or inputs are copied.
+ * The drain signal is persisted BEFORE asking the old process to exit. */
+export class HostUpgradeCoordinator {
+    store;
+    target;
+    ports;
+    #tail = Promise.resolve();
+    #closed = false;
+    constructor(store, target, ports) {
+        this.store = store;
+        this.target = target;
+        this.ports = ports;
+    }
+    hasPending() {
+        return !this.#closed && this.store.listWorkMailboxes().some(mailbox => reasons(mailbox).includes(RUNTIME_HOST_UPGRADE_REASON));
+    }
+    stop() { this.#closed = true; }
+    async close() {
+        this.stop();
+        await this.#tail;
+    }
+    /** Read-only follow-up: never admits, drains, restores, or settles a request. */
+    async status() {
+        const results = [];
+        for (const { owner, nativeSessionId, adapterId } of this.store.listRuntimeSessionCandidates()) {
+            if (this.#closed)
+                break;
+            const result = (status, detail, snapshot) => ({
+                owner, nativeSessionId, status, detail, hostImplementation: snapshot?.hostImplementation,
+                endpointImplementation: snapshot?.endpointImplementation
+            });
+            try {
+                const mailbox = this.store.getWorkMailbox(runtimeLifecycleTarget(owner));
+                const request = readRequest(mailbox);
+                if (!this.enabled(owner)) {
+                    results.push(result("paused", "Role/Task remains paused."));
+                    continue;
+                }
+                const state = await this.ports.hostState(owner);
+                const live = state === "running" ? await this.ports.inspect(owner) : undefined;
+                if (live && this.verified(live, nativeSessionId, adapterId)) {
+                    results.push(result("current", "Loaded Host and Endpoint match this Controller.", live));
+                }
+                else if (request && (request.nativeSessionId !== nativeSessionId || live
+                    && (live.nativeSessionId !== request.nativeSessionId || live.processInstanceId !== request.processInstanceId))) {
+                    results.push(result("unknown", `Request ${request.requestId} does not match the observed Host/Session.`, live));
+                }
+                else if (request) {
+                    results.push(result(reasons(mailbox).includes(FAILED) || live?.hostUpgrade?.state === "failed" ? "failed"
+                        : state === "unavailable" ? "unknown" : "waiting", `Request ${request.requestId}; target=${request.targetGeneration}; Host=${state}; drain=${live?.hostUpgrade?.state
+                        ?? (reasons(mailbox).includes(DRAINED) ? "persisted" : "unconfirmed")}. ${live?.hostUpgrade?.detail ?? ""}`, live));
+                }
+                else {
+                    results.push(result(live && (!live.controlCapabilities?.includes("prepare-upgrade")
+                        || !live.controlCapabilities.includes("finish-upgrade")) ? "unsupported" : "unknown", "No confirmed switch to this Controller's generation.", live));
+                }
+            }
+            catch (error) {
+                results.push(result("unknown", message(error)));
+            }
+        }
+        return results;
+    }
+    request() {
+        return this.serial(async () => {
+            const results = [];
+            for (const candidate of this.store.listRuntimeSessionCandidates()) {
+                if (this.#closed)
+                    break;
+                const { owner, nativeSessionId } = candidate;
+                const result = (status, detail, snapshot) => ({
+                    owner, nativeSessionId, status, detail, hostImplementation: snapshot?.hostImplementation,
+                    endpointImplementation: snapshot?.endpointImplementation
+                });
+                try {
+                    const existing = this.store.getWorkMailbox(runtimeLifecycleTarget(owner));
+                    if (readRequest(existing)) {
+                        results.push(await this.step(owner));
+                        continue;
+                    }
+                    if (!this.enabled(owner)) {
+                        results.push(result("paused", "Role/Task remains paused; no Host is started."));
+                        continue;
+                    }
+                    const snapshot = await this.ports.inspect(owner);
+                    if (this.#closed)
+                        break;
+                    if (snapshot.nativeSessionId !== nativeSessionId) {
+                        results.push(result("unknown", "Live Host does not match the recorded native Session.", snapshot));
+                        continue;
+                    }
+                    if (this.verified(snapshot, nativeSessionId, candidate.adapterId)) {
+                        results.push(result("current", undefined, snapshot));
+                        continue;
+                    }
+                    if (this.sameImplementations(snapshot, candidate.adapterId)) {
+                        results.push(result("waiting", "Loaded implementations match; lifecycle/event readiness is not a version mismatch.", snapshot));
+                        continue;
+                    }
+                    if (!snapshot.controlCapabilities?.includes("prepare-upgrade")
+                        || !snapshot.controlCapabilities.includes("finish-upgrade")
+                        || !snapshot.hostImplementation?.generation || !snapshot.endpointImplementation?.generation
+                        || !snapshot.processInstanceId) {
+                        results.push(result("unsupported", "Old Host has no graceful-upgrade capability; retained without sending unsupported commands.", snapshot));
+                        continue;
+                    }
+                    if (existing && mailboxHasWork(existing)) {
+                        results.push(result("waiting", "Another exact lifecycle operation owns this Role.", snapshot));
+                        continue;
+                    }
+                    const session = this.session(owner, candidate.agentId);
+                    if (!session || session.nativeSessionId !== nativeSessionId)
+                        throw new Error("Session changed before upgrade admission.");
+                    const body = {
+                        nativeSessionId, processInstanceId: snapshot.processInstanceId,
+                        hostGeneration: snapshot.hostImplementation.generation, targetGeneration: this.target.generation,
+                        agentId: candidate.agentId, adapterId: candidate.adapterId, effectiveDigest: digest(session.effective)
+                    };
+                    const request = { requestId: `host-upgrade-${digest([owner, body])}`, ...body };
+                    this.store.transaction(tx => {
+                        const latest = tx.getWorkMailbox(runtimeLifecycleTarget(owner));
+                        if (latest && mailboxHasWork(latest))
+                            throw new Error("Runtime lane changed before upgrade admission.");
+                        const current = this.session(owner, candidate.agentId);
+                        if (!current || current.nativeSessionId !== nativeSessionId || digest(current.effective) !== request.effectiveDigest) {
+                            throw new Error("Session changed before upgrade admission.");
+                        }
+                        tx.saveWorkMailbox(enqueueSignal(latest ?? createWorkMailbox(runtimeLifecycleTarget(owner)), {
+                            reason: RUNTIME_HOST_UPGRADE_REASON, refs: [{ type: "session", id: nativeSessionId }],
+                            source: SOURCE + JSON.stringify(request), dedupeKey: request.requestId, occurredAt: new Date().toISOString()
+                        }));
+                    });
+                    results.push(await this.step(owner));
+                }
+                catch (error) {
+                    results.push(result("unknown", message(error)));
+                }
+            }
+            return results;
+        });
+    }
+    reconcile() {
+        return this.serial(async () => {
+            const results = [];
+            for (const mailbox of this.store.listWorkMailboxes()) {
+                if (this.#closed)
+                    break;
+                const target = mailbox.target;
+                if (target.kind !== "role-runtime" && target.kind !== "global-role-runtime")
+                    continue;
+                const owner = target.kind === "role-runtime"
+                    ? { scope: "task", taskId: target.taskId, roleName: target.roleName }
+                    : { scope: "global", roleName: target.roleName };
+                try {
+                    if (!readRequest(mailbox))
+                        continue;
+                    results.push(await this.step(owner));
+                }
+                catch (error) {
+                    results.push({ owner, nativeSessionId: "", status: "unknown", detail: message(error) });
+                }
+            }
+            return results;
+        });
+    }
+    async step(owner) {
+        let mailbox = this.store.getWorkMailbox(runtimeLifecycleTarget(owner));
+        const request = readRequest(mailbox);
+        const result = (status, detail, snapshot) => ({
+            owner, nativeSessionId: request.nativeSessionId, status, detail,
+            hostImplementation: snapshot?.hostImplementation, endpointImplementation: snapshot?.endpointImplementation
+        });
+        try {
+            if (runtimeCleanupDisposition(mailbox) !== "upgrade-host")
+                return result("waiting", "Explicit lifecycle cleanup supersedes upgrade.");
+            if (request.targetGeneration !== this.target.generation)
+                return result("waiting", "Controller generation differs from the pinned update target.");
+            if (!this.enabled(owner))
+                return result("paused", "Role/Task remains paused; original upgrade intent retained.");
+            const assertCurrent = () => {
+                const session = this.session(owner, request.agentId);
+                const currentMailbox = this.store.getWorkMailbox(runtimeLifecycleTarget(owner));
+                if (this.#closed || !session || session.status !== "active" || session.nativeSessionId !== request.nativeSessionId
+                    || digest(session.effective) !== request.effectiveDigest || !this.enabled(owner)
+                    || runtimeCleanupDisposition(currentMailbox) !== "upgrade-host"
+                    || !isDeepStrictEqual(readRequest(currentMailbox), request)) {
+                    throw new Error("Upgrade no longer owns the original Session/configuration/lifecycle lane.");
+                }
+                return session;
+            };
+            const session = assertCurrent();
+            let live;
+            const hostState = await this.ports.hostState(owner);
+            if (hostState === "running") {
+                live = await this.ports.inspect(owner);
+                if (this.verified(live, request.nativeSessionId, request.adapterId)) {
+                    assertCurrent();
+                    this.complete(owner, request);
+                    return result("upgraded", undefined, live);
+                }
+                if (reasons(mailbox).includes(FAILED))
+                    return result("failed", "Prior upgrade failed; exact request and drain facts retained. Inspect before retrying.", live);
+                if (live.nativeSessionId !== request.nativeSessionId || live.processInstanceId !== request.processInstanceId
+                    || live.hostImplementation?.generation !== request.hostGeneration) {
+                    return result("unknown", "Host changed without the target handshake; no process was stopped.", live);
+                }
+                if (!reasons(mailbox).includes(DRAINED)) {
+                    assertCurrent();
+                    live = await this.ports.control(owner, "prepare-upgrade", request);
+                    const drain = live.hostUpgrade;
+                    if (drain?.requestId !== request.requestId)
+                        return result("unknown", "Drain acknowledgement is missing or mismatched.", live);
+                    if (drain.state === "failed") {
+                        this.signal(owner, request, FAILED);
+                        return result("failed", drain.detail, live);
+                    }
+                    if (drain.state !== "drained")
+                        return result("waiting", "Admission fenced; waiting for native terminal, event persistence and owned-resource drain.", live);
+                    assertCurrent();
+                    this.signal(owner, request, DRAINED);
+                    mailbox = this.store.getWorkMailbox(runtimeLifecycleTarget(owner));
+                }
+                if (live.hostUpgrade?.requestId !== request.requestId || live.hostUpgrade.state !== "drained") {
+                    return result("unknown", "Persisted drain receipt does not match this live Host.", live);
+                }
+                assertCurrent();
+                await this.ports.control(owner, "finish-upgrade", request);
+                return result("waiting", "Old Host drained; awaiting its graceful process exit.", live);
+            }
+            if (reasons(mailbox).includes(FAILED))
+                return result("failed", "Prior launch is unconfirmed; retained request is not automatically replayed.");
+            if (hostState !== "stopped" || !reasons(mailbox).includes(DRAINED)) {
+                return result("unknown", "No proven old Host drain/exit; original inputs and Session retained.");
+            }
+            assertCurrent();
+            // A failed or unknown launch is NOT automatically replayed. The existing
+            // Host/pane and the exact mailbox request remain available for inspection.
+            try {
+                await this.ports.restore(owner, request, session.effective, assertCurrent);
+            }
+            catch (error) {
+                this.signal(owner, request, FAILED);
+                return result("failed", `Target Host launch/handshake failed: ${message(error)}`);
+            }
+            live = await this.ports.inspect(owner);
+            if (!this.verified(live, request.nativeSessionId, request.adapterId)) {
+                this.signal(owner, request, FAILED);
+                return result("failed", "Target Host did not prove native identity, implementations and control/event capabilities.", live);
+            }
+            assertCurrent();
+            this.complete(owner, request);
+            return result("upgraded", undefined, live);
+        }
+        catch (error) {
+            return result("unknown", message(error));
+        }
+    }
+    verified(snapshot, nativeSessionId, adapterId) {
+        return snapshot.nativeSessionId === nativeSessionId && snapshot.adapterId === adapterId
+            && this.sameImplementations(snapshot, adapterId)
+            && snapshot.controlCapabilities?.includes("reconcile-turn")
+            && snapshot.eventDelivery !== undefined && snapshot.eventDelivery.unpersisted === 0
+            && snapshot.eventDelivery.failure === undefined && ["idle", "ready", "busy"].includes(snapshot.state);
+    }
+    sameImplementations(snapshot, adapterId) {
+        return isDeepStrictEqual(snapshot.hostImplementation, this.target)
+            && isDeepStrictEqual(snapshot.endpointImplementation, this.ports.endpoint(adapterId));
+    }
+    session(owner, agentId) {
+        const set = owner.scope === "task" ? this.store.getTaskRoleSessionSet(owner.taskId, owner.roleName)
+            : this.store.getGlobalRoleSessionSet(owner.roleName);
+        return set?.activeAgentId === agentId ? set.sessions[agentId] : undefined;
+    }
+    enabled(owner) {
+        const role = owner.scope === "task" ? this.store.getRole(owner.taskId, owner.roleName) : this.store.getGlobalRole(owner.roleName);
+        if (!role || !isEnabled(role))
+            return false;
+        if (owner.scope === "global")
+            return true;
+        const task = this.store.getTask(owner.taskId);
+        return !!task && ["active", "draft"].includes(task.status) && task.executionGate.state === "enabled";
+    }
+    signal(owner, request, reason) {
+        this.store.transaction(tx => {
+            const mailbox = tx.getWorkMailbox(runtimeLifecycleTarget(owner));
+            if (!mailbox || !isDeepStrictEqual(readRequest(mailbox), request))
+                throw new Error("Upgrade mailbox changed.");
+            tx.saveWorkMailbox(enqueueSignal(mailbox, { reason, refs: [], source: "host-upgrade",
+                dedupeKey: `${request.requestId}:${reason}`, occurredAt: new Date().toISOString() }));
+        });
+    }
+    complete(owner, request) {
+        this.store.transaction(tx => {
+            let mailbox = tx.getWorkMailbox(runtimeLifecycleTarget(owner));
+            if (!mailbox || !isDeepStrictEqual(readRequest(mailbox), request)
+                || runtimeCleanupDisposition(mailbox) !== "upgrade-host")
+                throw new Error("Upgrade mailbox changed.");
+            if (mailbox.processing)
+                mailbox = completeProcessing(mailbox, mailbox.processing.batchId);
+            if (mailbox.pending) {
+                const batchId = request.requestId;
+                mailbox = completeProcessing(claimPending(mailbox, {
+                    batchId, owner: "runtime-lifecycle", startedAt: new Date().toISOString()
+                }), batchId);
+            }
+            tx.saveWorkMailbox(mailbox); // retain bounded dedupe receipts for repeated update
+        });
+    }
+    serial(run) {
+        const next = this.#tail.then(run);
+        this.#tail = next.catch(() => undefined);
+        return next;
+    }
+}
+function reasons(mailbox) {
+    return [...mailbox?.pending?.reasons ?? [], ...mailbox?.processing?.batch.reasons ?? []];
+}
+function readRequest(mailbox) {
+    if (!reasons(mailbox).includes(RUNTIME_HOST_UPGRADE_REASON))
+        return undefined;
+    const sources = [...mailbox?.pending?.sources ?? [], ...mailbox?.processing?.batch.sources ?? []]
+        .filter(source => source.startsWith(SOURCE));
+    const unique = [...new Set(sources)];
+    if (unique.length !== 1)
+        throw new Error("Host upgrade request is missing or ambiguous.");
+    const request = JSON.parse(unique[0].slice(SOURCE.length));
+    for (const key of ["requestId", "nativeSessionId", "processInstanceId", "hostGeneration",
+        "targetGeneration", "agentId", "adapterId", "effectiveDigest"]) {
+        if (typeof request[key] !== "string" || !request[key] || request[key].includes("\0")) {
+            throw new Error("Host upgrade request is invalid.");
+        }
+    }
+    return request;
+}
+function digest(value) { return createHash("sha256").update(JSON.stringify(value)).digest("hex"); }
+function message(error) { return error instanceof Error ? error.message : String(error); }

package/dist/controller/messageHealth.js

@@ -91,13 +91,14 @@ function recoveryGuidance(o) {
         if (o.wakeId !== null && roleName === "leader") {
             const wakeTarget = `${arg(taskId)} ${arg(o.wakeId)}`;
             if (o.deliveryEvidence?.outcome === "rejected") {
-                lines.push(`After correcting the rejection cause, and only if this exact wake is still unconsumed, its original claim matches and native acceptance/activity are proven absent: yui task wake retry ${wakeTarget} --reason '<verified correction and quiescence>'. Queued is not accepted. Do not retry accepted/unknown input. This candidate does not establish resolve support for rejected wakes; do not assume another recovery package is installed.`);
+                lines.push(`Choose alternative actions, not a sequence. After correcting the rejection cause, and only if this exact wake is still unconsumed, its original claim matches and native acceptance/activity are proven absent: yui task wake retry ${wakeTarget} --reason '<verified correction and quiescence>'. Queued is not accepted. Do not retry accepted/unknown input.`);
+                lines.push(`Alternatively, after exact shared-native/background/writer quiescence and persisted notification-attempt evidence: yui task wake resolve ${wakeTarget} --reason '<exact quiescence evidence>'. A rejection is not quiescence, including rejection after an unknown outcome. Resolve releases only scheduling without replay, ACK or acceptance; it preserves original claims and delivery evidence. If the operational mailbox is absent, the exact durable wake/attempt must still be proven; another current batch is never released. The rightful handler must inspect original effects and settle still-valid obligations separately.`);
             }
             else if (o.deliveryEvidence?.outcome === "unknown") {
-                lines.push(`Do not replay unknown input. After exact shared-native/background/writer quiescence and persisted evidence, with the original unknown claim still current: yui task wake resolve ${wakeTarget} --reason '<exact quiescence evidence>'. This releases only scheduling without replay, ACK or acceptance. The rightful handler must inspect original effects and settle still-valid obligations separately.`);
+                lines.push(`Do not replay unknown input. After exact shared-native/background/writer quiescence and persisted evidence identifying the original wake/notification attempt: yui task wake resolve ${wakeTarget} --reason '<exact quiescence evidence>'. This releases only scheduling without replay, ACK or acceptance; an absent operational mailbox requires exact durable evidence, never release of another current batch. The rightful handler must inspect original effects and settle still-valid obligations separately.`);
             }
             else {
-                lines.push("Deferred, accepted or unreported delivery does not meet this candidate's rejected-retry/unknown-resolve preconditions. Keep the original wake and inspect the runtime barrier instead of mechanically invoking either action.");
+                lines.push("Deferred, accepted or unreported delivery does not meet this candidate's rejected-retry/unknown-or-rejected-resolve preconditions. Keep the original wake and inspect the runtime barrier instead of mechanically invoking either action.");
             }
         }
     }

package/dist/controller/providerRetryAdmission.js

@@ -4,6 +4,7 @@ import { blockingProviderContinuations } from "../runtime/runtimeContinuationPro
 import { validateExactRunReviewRound } from "../lifecycle/exactRunTerminalization.js";
 import { isDeepStrictEqual } from "node:util";
 import { isHandlingReminder } from "../message/inboxTurn.js";
+import { roleSessionMayContinue } from "../executor/effectiveLaunch.js";
 export function ownedProviderInput(input) {
     if (input.runId !== undefined && input.taskId !== undefined) {
         return { kind: "run", taskId: input.taskId, runId: input.runId };
@@ -90,8 +91,21 @@ export function admitOwnedProviderInput(store, binding, input) {
     if (input.taskId !== undefined && input.runId !== undefined) {
         const run = store.getRun(input.taskId, input.runId);
         const sessions = store.getTaskRoleSessionSet(input.taskId, input.roleName);
+        const session = sessions?.sessions[input.agentId];
+        // Session provenance can describe an older ReviewRound. The exact failed
+        // Run, not that first launch, owns this retry's frozen launch configuration.
+        // Continuity still fences the native Session's physical workspace/authority;
+        // exact equality with the failed Run retains model, permission and candidate.
+        const previous = run?.purpose === "review" && retry.previousRunId !== undefined
+            ? store.getRun(input.taskId, retry.previousRunId) : null;
+        const matchesLaunch = run !== null && session !== undefined && (run.purpose === "review"
+            ? previous?.status === "failed" && previous.purpose === "review"
+                && previous.roleName === run.roleName && previous.reviewRoundId === run.reviewRoundId
+                && isDeepStrictEqual(run.effective, previous.effective)
+                && roleSessionMayContinue(session.effective, run.effective)
+            : isDeepStrictEqual(run.effective, session.effective));
         if (run === null || run.status !== "active"
-            || !isDeepStrictEqual(run.effective, sessions?.sessions[input.agentId]?.effective)) {
+            || !matchesLaunch) {
             throw new Error("Retry execution no longer matches its fixed native Session.");
         }
         if (run.workspace !== undefined && !isDeepStrictEqual(store.getManagedWorkspace(run.workspace.owner), run.workspace)) {

package/dist/controller/providerRetryDelivery.js

@@ -171,9 +171,25 @@ export function createProviderRetryHooks(home, store, ports = {}) {
                     }
                     try {
                         if (owner.scope === "task" && retry.previousRunId !== undefined) {
-                            if (retry.successorRunId !== undefined || retry.successorReviewRoundId !== undefined)
-                                continue;
                             const previous = store.getRun(owner.taskId, retry.previousRunId);
+                            if (retry.successorRunId !== undefined || retry.successorReviewRoundId !== undefined) {
+                                const round = retry.successorReviewRoundId === undefined
+                                    ? null : store.getReviewRound(owner.taskId, retry.successorReviewRoundId);
+                                const successorId = retry.successorRunId ?? (previous?.executionLaneId === undefined
+                                    ? round?.reviewerRunId
+                                    : round?.executionGroup?.lanes.find(lane => lane.id === previous.executionLaneId)?.currentRunId);
+                                const successor = successorId === undefined ? null : store.getRun(owner.taskId, successorId);
+                                // A scheduled Run can fail before Host admission, leaving the
+                                // Provider binding on the original failed Turn. Stop waiting;
+                                // this is not proof of native quiescence or permission to replay.
+                                if (successor?.status === "failed" && successor.id !== previous?.id
+                                    && successor.roleName === owner.roleName
+                                    && (retry.successorReviewRoundId === undefined
+                                        || successor.reviewRoundId === retry.successorReviewRoundId)) {
+                                    stop(set, "successor-failed-before-admission", at);
+                                }
+                                continue;
+                            }
                             if (previous?.status === "active")
                                 continue; // ordinary rejected-delivery terminal fold
                             if (previous?.status !== "failed") {

package/dist/controller/runtime.js

@@ -27,7 +27,7 @@ import { launchBrokerForHome } from "../runtime/launchBroker.js";
 import { hasRuntimeCleanupObligation, runtimeLifecycleTarget } from "../runtime/lifecycleReservation.js";
 import { classifyRuntimeProcessExit, validateRuntimeProcessExitObservation } from "../runtime/processExitObservation.js";
 import { replayRuntimeProcessExitOutbox } from "../runtime/processExitOutbox.js";
-import { providerRetryPrompt } from "../runtime/providerRetry.js";
+import { providerRetryContext } from "../runtime/providerRetry.js";
 import { createRuntimeObservation, runtimeObservationFromTaskEvent } from "../runtime/runtimeObservation.js";
 import { openCurrentTaskStore } from "../storage/currentTaskStore.js";
 import { managedRuntimeRoot } from "../storage/homeLayout.js";
@@ -60,6 +60,13 @@ import { ephemeralDomainFromEnvironment, recordEphemeralTmuxTarget } from "./dom
 import { createEphemeralResourceReaper } from "./ephemeralResourceReaper.js";
 import { AgentHostProviderSessionBusyError, AgentHostProviderTurnFenceError, FileSchedulerStoreAdapter } from "./fileSchedulerStoreAdapter.js";
 import { deliverGlobalInputs } from "./globalInputDelivery.js";
+import { HostUpgradeCoordinator } from "./hostUpgrade.js";
+import { createHostLifecycleChecks } from "./hostLifecycleChecks.js";
+import { createControllerHostLifecycle } from "./hostLifecycle.js";
+import { createNonBlockingChecks } from "../runtime/lifecycleChecks.js";
+import { AGENT_HOST_IMPLEMENTATION } from "../runtime/agentHostImplementation.js";
+import { builtinAgentEndpointImplementation } from "../runtime/agentEndpointIdentity.js";
+import { sendAgentHostUpgradeControl } from "../runtime/agentHost.js";
 import { authorizeJobStart } from "./jobControl.js";
 import { authorizeGlobalJobStart, createJobDefinitionControl } from "./jobDefinitionControl.js";
 import { reconcileTaskDelegation } from "./jobTaskDelegationControl.js";
@@ -89,6 +96,7 @@ export async function startFileTaskControllerRuntime(home, options = {}) {
         const running = await createFileTaskControllerRuntime(home, {
             ...options,
             diagnosticMetrics: () => diagnostics.metrics(),
+            onRequestDiagnostic: record => diagnostics.request(record),
             onError: error => { diagnostics.error(error); options.onError?.(error); }
         });
         let expectedAt = monotonicMilliseconds() + 250;
@@ -197,7 +205,7 @@ async function createFileTaskControllerRuntime(home, options) {
             ?? new AgentConfigurationCatalogService(home, {
                 environment: options.environment ?? process.env
             });
-        const sessionHost = options.sessionHost ?? new TmuxSessionHost(planner, tmux, {
+        const rawSessionHost = options.sessionHost ?? new TmuxSessionHost(planner, tmux, {
             validateLaunch: async (request) => {
                 const agent = store.getConfiguredAgent(request.agentId);
                 if (agent === null)
@@ -221,7 +229,7 @@ async function createFileTaskControllerRuntime(home, options) {
                         && typeof session.nativeSessionId === "string" && session.nativeSessionId.trim().length > 0) {
                         return session.nativeSessionId;
                     }
-                    for (const event of runtimeEventInbox.list()) {
+                    for (const event of await runtimeEventInbox.listAsync()) {
                         if (event.type === "runtime-observation" && event.observation.kind === "session.started"
                             && event.observation.fence.taskId === owner.taskId
                             && event.observation.fence.roleName === owner.roleName
@@ -266,13 +274,13 @@ async function createFileTaskControllerRuntime(home, options) {
                     globalInstallPaths: [process.execPath]
                 }
             });
-        const lifecycleHost = {
-            inspectOwner: (owner) => (sessionHost.inspectOwner(owner)),
-            ...(sessionHost.inspectOwners === undefined
-                ? {}
-                : {
-                    inspectOwners: (owners) => sessionHost.inspectOwners(owners)
-                }),
+        const hostStateChecks = createNonBlockingChecks([{
+                id: "host-version-hint",
+                run: (_transition, signal) => { if (!signal.aborted)
+                    hostLifecycleChecks.notify("host-observed"); }
+            }], options.onError);
+        const controllerHosts = createControllerHostLifecycle(rawSessionHost, {
+            after: hostStateChecks,
             stopOwner: (owner) => {
                 // Issue 03: the durable `stopped` transition is gated on physical
                 // exit proof. A blocked result keeps the Session non-terminal and
@@ -286,7 +294,9 @@ async function createFileTaskControllerRuntime(home, options) {
                     return result.outcome === "stop-confirmed";
                 });
             },
-        };
+        });
+        const sessionHost = controllerHosts.port;
+        const lifecycleHost = sessionHost;
         const resourceActivity = createRuntimeResourceActivityTracker();
         let runningRuntime;
         let runningController;
@@ -297,6 +307,32 @@ async function createFileTaskControllerRuntime(home, options) {
             },
             runtimeIsolation
         });
+        const hostUpgrades = new HostUpgradeCoordinator(store, AGENT_HOST_IMPLEMENTATION, {
+            inspect: owner => inspectAgentHost({ home, ...owner }),
+            control: async (owner, type, request) => {
+                const send = async () => {
+                    const result = await sendAgentHostUpgradeControl({
+                        home, ...owner, control: { protocol: AGENT_HOST_CONTROL_PROTOCOL, type, ...request }
+                    });
+                    if (result.outcome === "rejected")
+                        throw new Error(result.failure?.detail ?? "Host upgrade control rejected.");
+                    return result.snapshot;
+                };
+                return type === "finish-upgrade" ? controllerHosts.requestExit(owner, send) : send();
+            },
+            hostState: async (owner) => (await sessionHost.inspectOwner(owner)).state,
+            endpoint: builtinAgentEndpointImplementation,
+            restore: async (owner, request, effective, assertCurrent) => {
+                const workspace = owner.scope === "task" ? currentDesiredManagedWorkspace(store, owner.taskId, owner.roleName) : undefined;
+                await launchCoordinator.prepare({
+                    owner, agentId: request.agentId, adapterId: request.adapterId, effective,
+                    workspace: effective.workspace.root, mode: "resume", nativeSessionId: request.nativeSessionId,
+                    ...(workspace === undefined ? {} : { managedWorkspace: workspace }),
+                    ...(effective.executionAuthority === "planning" ? { workspaceFree: true } : {})
+                }, assertCurrent);
+            }
+        });
+        const hostLifecycleChecks = createHostLifecycleChecks(hostUpgrades, options.onError);
         // One inventory scan per scheduler pass. When the inventory worker is active
         // the blocking /proc scan runs there; otherwise it runs on the main thread.
         const scanInventory = (panes) => inventoryClient !== undefined
@@ -416,7 +452,7 @@ async function createFileTaskControllerRuntime(home, options) {
                 store,
                 environment: options.environment
             });
-        const lifecycleDispatcher = createRuntimeLifecycleDispatcher(store, schedulerStore, sessionHost, options.dispatcher, launchCoordinator, planner);
+        const lifecycleDispatcher = createRuntimeLifecycleDispatcher(store, schedulerStore, sessionHost, options.dispatcher, launchCoordinator, planner, workerMaintenance ? asyncStoreClient : undefined);
         // Process-exit observations are persisted by the Agent Host before socket
         // delivery. Drain them while this Controller is still the only storage
         // writer and before it begins accepting new work after a handover.
@@ -587,10 +623,22 @@ async function createFileTaskControllerRuntime(home, options) {
         let messageHealthHosts = [];
         const running = await startFileTaskController(home, workerMaintenance
             ? workerSchedulerStore(schedulerStore, asyncStoreClient)
-            : schedulerStore, delivery, (method, params) => method === "task.role-capabilities"
-            ? readTaskAgentCapabilities(store, catalogs, params)
-            : method === "web.start" || method === "web.stop" || method === "web.status"
-                ? web.dispatch(method, params) : lifecycleDispatcher(method, params), {
+            : schedulerStore, delivery, (method, params) => method === "runtime.host-upgrade-status"
+            ? hostUpgrades.status().then(hosts => ({ hosts }))
+            : method === "runtime.upgrade-hosts"
+                ? (params.generation === AGENT_HOST_IMPLEMENTATION.generation
+                    ? hostUpgrades.request().then(hosts => ({ hosts }))
+                    : Promise.reject(new Error("Host upgrade target is not this Controller's verified loaded generation.")))
+                : method === "task.role-capabilities"
+                    ? readTaskAgentCapabilities(store, catalogs, params)
+                    : method === "web.start" || method === "web.stop" || method === "web.status"
+                        ? web.dispatch(method, params) : Promise.resolve(lifecycleDispatcher(method, params)).then(result => {
+                        if (["runtime.ensure-role-session", "runtime.process-exit-observe",
+                            "runtime.host-observation-apply", "runtime.observation-apply"].includes(method)) {
+                            hostLifecycleChecks.notify("host-observed");
+                        }
+                        return result;
+                    }), {
             intervalMs: options.intervalMs
                 ?? reconciliationIntervalMilliseconds(store.getConfig().reconciliationIntervalSeconds),
             signalWindowMs: options.signalWindowMs,
@@ -607,7 +655,9 @@ async function createFileTaskControllerRuntime(home, options) {
             now: options.now,
             onError: options.onError,
             diagnosticMetrics: options.diagnosticMetrics,
+            onRequestDiagnostic: options.onRequestDiagnostic,
             lifecycleHost,
+            lifecycleChecks: hostLifecycleChecks,
             providerRetry: createProviderRetryHooks(home, store, {
                 now: options.now,
                 onError: options.onError,
@@ -702,7 +752,9 @@ async function createFileTaskControllerRuntime(home, options) {
         }
         let resourceClose;
         const closeResources = () => {
-            resourceClose ??= closeTelemetry().finally(() => Promise.all([
+            hostStateChecks.close();
+            hostLifecycleChecks.close();
+            resourceClose ??= hostUpgrades.close().then(() => closeTelemetry()).finally(() => Promise.all([
                 web.close(),
                 kernel.close(),
                 asyncStoreClient?.close() ?? Promise.resolve(),
@@ -753,7 +805,7 @@ async function createFileTaskControllerRuntime(home, options) {
         throw error;
     }
 }
-export function createRuntimeLifecycleDispatcher(store, schedulerStore, sessionHost, fallback, sharedLaunchCoordinator, environmentRefresher) {
+export function createRuntimeLifecycleDispatcher(store, schedulerStore, sessionHost, fallback, sharedLaunchCoordinator, environmentRefresher, observationWorker) {
     const launchCoordinator = sharedLaunchCoordinator
         ?? new RuntimeLaunchCoordinator(schedulerStore, sessionHost, {
             assertCurrent: (request) => {
@@ -774,12 +826,20 @@ export function createRuntimeLifecycleDispatcher(store, schedulerStore, sessionH
             if (event.type !== "runtime-observation" || event.host === undefined) {
                 throw applicationError("INVALID_PARAMS", "Expected an Agent Host observation.");
             }
-            return { outcome: schedulerStore.observeAgentHostObservation(event, new Date()) };
+            // Eager Host delivery and the normal Inbox drainer fold the same durable
+            // fact. Share their existing worker writer: a second synchronous writer
+            // here can wait on BEGIN IMMEDIATE and starve even status socket I/O.
+            // Await the original atomic fold; no eager ACK or cursor advancement.
+            return { outcome: observationWorker === undefined
+                    ? schedulerStore.observeAgentHostObservation(event, new Date())
+                    : await observationWorker.invokeObserver("observeAgentHostObservation", [event, new Date()]) };
         }
         if (method === "runtime.observation-apply") {
             try {
                 return {
-                    outcome: schedulerStore.observeRuntimeObservation(createRuntimeObservation(params), new Date())
+                    outcome: observationWorker === undefined
+                        ? schedulerStore.observeRuntimeObservation(createRuntimeObservation(params), new Date())
+                        : await observationWorker.invokeObserver("observeRuntimeObservation", [createRuntimeObservation(params), new Date()])
                 };
             }
             catch (error) {
@@ -835,7 +895,8 @@ export function createRuntimeLifecycleDispatcher(store, schedulerStore, sessionH
             const retry = binding?.retry;
             return { recorded: true, ...(retry?.currentAttemptId === value.attemptId && value.boundedText !== undefined
                     ? { retryInput: {
-                            text: providerRetryPrompt(retry, value.boundedText),
+                            text: value.boundedText,
+                            ...(retry.failedNativeTurnId === undefined ? {} : { context: providerRetryContext(retry) }),
                             ...(retry.failedNativeTurnId === undefined ? {} : { expectedFailedNativeTurnId: retry.failedNativeTurnId })
                         } } : {}) };
         }