@zq-silk/yui 2.22.0 → 2.23.0

package/dist/cli/commandCatalog.js

@@ -1289,8 +1289,8 @@ export const ROOT_COMMAND = buildNode({
         {
             name: "update", discovery: { surface: "public", audiences: ["public", "operator"] },
             summary: "Install the latest or an exact published Yui version after storage preflight.",
-            usage: "yui update [--version <exact-version>]",
-            options: ["--version"]
+            usage: "yui update [--version <exact-version>] | --hosts-status",
+            options: ["--version", "--hosts-status"]
         },
         {
             name: "upgrade", discovery: { surface: "public", audiences: ["public", "operator"] },

package/dist/cli/updateCommand.js

@@ -14,9 +14,16 @@ import { usageError } from "../errors/cliError.js";
  * Returns a process exit code: 0 on success or already-current, 5 on abort.
  */
 export function runUpdateCommand(args = [], environment = process.env, spawn, write = (text) => process.stdout.write(text), ports) {
-    const version = parseUpdateVersion(args);
+    const statusOnly = args.length === 1 && args[0] === "--hosts-status";
+    const version = statusOnly ? undefined : parseUpdateVersion(args);
     const home = resolveYuiHome(environment);
     const resolvedPorts = ports ?? createUpdatePorts(environment, spawn);
+    if (statusOnly) {
+        if (!resolvedPorts.hostStatus)
+            throw usageError("Host status inspection is unavailable.");
+        write(`${renderHosts(resolvedPorts.hostStatus(home)).join("\n")}\n`);
+        return 0;
+    }
     const result = runUpdate(resolvedPorts, { home, version });
     write(`${renderUpdateResult(result)}\n`);
     if (result.outcome === "aborted")
@@ -29,7 +36,12 @@ function parseUpdateVersion(args) {
     if (args.length === 2 && args[0] === "--version" && isConcreteVersion(args[1])) {
         return args[1].trim();
     }
-    throw usageError("Update usage: yui update [--version <exact-version>]");
+    throw usageError("Update usage: yui update [--version <exact-version>] | --hosts-status");
+}
+function renderHosts(hosts) {
+    return hosts.length === 0 ? ["Hosts: no recorded active Sessions."] : hosts.map(host => `Host ${host.owner.scope === "task" ? `${host.owner.taskId}/` : "global/"}${host.owner.roleName} `
+        + `(${host.nativeSessionId}): ${host.status}; loaded Host=${host.hostImplementation?.generation ?? "unreported"}; `
+        + `loaded Endpoint=${host.endpointImplementation?.generation ?? "unreported"}${host.detail ? ` — ${host.detail}` : ""}`);
 }
 /** Render an {@link UpdateResult} as concise, CLI-style text. */
 export function renderUpdateResult(result) {
@@ -66,7 +78,12 @@ export function renderUpdateResult(result) {
     return [
         rendered,
         ...(result.outcome === "updated" ? [
-            "Runtime: existing Hosts are retained, not upgraded in place. Host control capabilities and event delivery are checked separately; accepted input is never replayed."
+            result.controllerStarted ? "Controller: target startup verified." : "Controller: not started by this update.",
+            "Hosts: graceful switching is separate from installation; accepted input is never replayed.",
+            ...(result.hosts === undefined ? ["Hosts: not confirmed; existing Hosts may still run older code."]
+                : renderHosts(result.hosts)),
+            "Inspect later without reinstalling: yui update --hosts-status",
+            ...(result.hostUpgradeError === undefined ? [] : [result.hostUpgradeError])
         ] : []),
         ...(result.controllerReconciliation === undefined ? [] : [
             `Controller reconciliation: ${JSON.stringify(result.controllerReconciliation)}`

package/dist/cli/updateOrchestrator.js

@@ -250,9 +250,22 @@ function activateAndVerify(ports, staged, home, lifecycle, preflight) {
                 : restoreControllerOrReport(ports, home, lifecycle, failure);
         }
     }
+    let hosts;
+    let hostUpgradeError;
+    if (lifecycle.ensureRunning && ports.upgradeHosts) {
+        try {
+            hosts = ports.upgradeHosts(home);
+        }
+        catch (error) {
+            hostUpgradeError = `Host upgrade request outcome is unknown: ${messageOf(error)}. Inspect existing requests; do not replay inputs.`;
+        }
+    }
     return {
         outcome: "updated",
         version: staged.version,
+        ...(lifecycle.ensureRunning ? { controllerStarted: true } : {}),
+        ...(hosts === undefined ? {} : { hosts }),
+        ...(hostUpgradeError === undefined ? {} : { hostUpgradeError }),
         ...(migration?.backupPath === undefined ? {} : { backupPath: migration.backupPath })
     };
 }

package/dist/cli/updatePorts.js

@@ -236,9 +236,36 @@ export function createUpdatePorts(environment, spawn = spawnSync, stagingRoot =
         },
         restoreController(home, identity) {
             restoreControllerIdentity(home, identity, environment, spawn);
+        },
+        upgradeHosts(home) {
+            if (!verifiedActivatedBinary)
+                throw new Error("Host upgrade requires the verified activated binary.");
+            const root = dirname(dirname(activatedControllerEntrypoint(verifiedActivatedBinary)));
+            return requestHosts(root, home, "runtime.upgrade-hosts", environment, spawn);
+        },
+        hostStatus(home) {
+            return requestHosts(fileURLToPath(new URL("../", import.meta.url)), home, "runtime.host-upgrade-status", environment, spawn);
         }
     };
 }
+function requestHosts(root, home, method, environment, spawn) {
+    const helper = [
+        "const [root, home] = process.argv.slice(1);",
+        "(async () => {",
+        " const { pathToFileURL } = await import('node:url');",
+        " const { callController } = await import(pathToFileURL(root + '/core/controllerClient.js').href);",
+        " const { AGENT_HOST_IMPLEMENTATION } = await import(pathToFileURL(root + '/runtime/agentHostImplementation.js').href);",
+        ` const data = await callController(home, ${JSON.stringify(method)}, { generation: AGENT_HOST_IMPLEMENTATION.generation });`,
+        " process.stdout.write(JSON.stringify({ok: true, data}));",
+        "})().catch(error => { process.stderr.write(String(error)); process.exitCode = 5; });"
+    ].join(" ");
+    const result = spawn(process.execPath, ["-e", helper, root, home], { cwd: process.cwd(), env: { ...environment, YUI_HOME: home }, shell: false });
+    const data = parseSuccessEnvelopeData(result);
+    if (result.error || result.status !== 0 || !Array.isArray(data?.hosts)) {
+        throw new Error(`Host request was not confirmed: ${result.stderr.toString("utf8")}`);
+    }
+    return data.hosts;
+}
 const UPDATE_CLI_PATH = fileURLToPath(new URL("../cli.js", import.meta.url));
 const UPDATE_CLIENT_RUNTIME_PATH = fileURLToPath(new URL("../controller/clientRuntime.js", import.meta.url));
 const UPDATE_INVENTORY_PATH = fileURLToPath(new URL("../controller/resourceInventoryLinux.js", import.meta.url));

package/dist/commands/taskRoleRuntimeStatus.js

@@ -19,6 +19,10 @@ export function taskRoleHostDiagnostic(host) {
     const delivery = snapshot.eventDelivery;
     return [
         `Provider Host=${snapshot.state}`,
+        `loaded Host=${snapshot.hostImplementation?.generation ?? "unreported"}`,
+        `loaded Endpoint=${snapshot.endpointImplementation?.generation ?? "unreported"}`,
+        snapshot.hostUpgrade === undefined ? undefined
+            : `Host upgrade=${snapshot.hostUpgrade.state} (${snapshot.hostUpgrade.requestId})${snapshot.hostUpgrade.detail ? `: ${snapshot.hostUpgrade.detail}` : ""}`,
         `terminal reconciliation=${snapshot.controlCapabilities?.includes("reconcile-turn") ? "supported" : "unreported/unsupported"}`,
         delivery === undefined ? "event delivery=unreported" :
             `pending facts=${delivery.pending}; native terminals awaiting acknowledgement=${delivery.pendingTerminals}`,

package/dist/context/currentSkills.js

@@ -1,4 +1,5 @@
 import { accessSync, constants, lstatSync, readFileSync, realpathSync } from "node:fs";
+import { access, lstat, readFile, realpath } from "node:fs/promises";
 import { join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 export const BUILTIN_YUI_SKILLS = new Set([
@@ -41,9 +42,39 @@ export function checkCurrentSkills(home, ids) {
         }
     });
 }
+/** Advisory lifecycle observation uses asynchronous filesystem I/O; it neither
+ * blocks a state transition nor substitutes for the exact per-input check. */
+export async function checkCurrentSkillsAsync(home, ids, signal) {
+    const skills = [];
+    for (const id of new Set(ids)) {
+        signal.throwIfAborted();
+        const path = currentSkillPath(home, id);
+        const versionPath = join(path, "VERSION");
+        try {
+            for (const file of [join(path, "SKILL.md"), versionPath]) {
+                if (await realpath(file) !== resolve(file) || !(await lstat(file)).isFile()) {
+                    throw new Error(`Skill files must be regular files without symlinks: ${file}.`);
+                }
+                await access(file, constants.R_OK);
+            }
+            if ((await lstat(versionPath)).size > 128)
+                throw new Error("VERSION exceeds 128 bytes.");
+            const version = (await readFile(versionPath, { encoding: "utf8", signal })).trim();
+            if (!/^[1-9][0-9]{0,8}$/u.test(version))
+                throw new Error("VERSION must contain a positive internal integer.");
+            skills.push({ id, path, version, versionPath });
+        }
+        catch (error) {
+            throw new Error(`Current Skill ${id} is missing, unreadable or invalid at ${path}. `
+                + `${error instanceof Error ? error.message : String(error)}`, { cause: error });
+        }
+    }
+    return skills;
+}
 export const SKILL_CHECK_COMMAND = "yui session skills --json";
 export const SKILL_REUSE_RULE = "The managed Host checks current Skill versions/availability before each input; "
-    + "do not repeat an explicit Host check. Without that notice, check through the Manifest's command. "
+    + "unchanged inputs carry no notice or marker, and do not require a duplicate check. "
+    + "For unmediated clients or uncertain current input routing, check through the Manifest's command; conversation reuse alone does not establish Host mediation. Keep routine checks internal, not user-facing progress. "
     + "Reuse unchanged full instructions in context; messages alone require no reload. "
     + "Read affected entries/references fully on change or localized loss. On first entry, recovery or lost context, "
     + "rebuild the current working set from applicable Skill entry points and action-relevant references, not all past procedures. "

package/dist/context/sessionBootstrapManifest.js

@@ -1,9 +1,10 @@
 import { createHash } from "node:crypto";
 import { chmodSync, readFileSync } from "node:fs";
+import { readFile } from "node:fs/promises";
 import { join, resolve } from "node:path";
 import { writeTextFileAtomically } from "../storage/durableFile.js";
 import { validateSkillPackageRef } from "./skillPackage.js";
-import { checkCurrentSkills, SKILL_CHECK_COMMAND, SKILL_REUSE_RULE } from "./currentSkills.js";
+import { checkCurrentSkills, checkCurrentSkillsAsync, SKILL_CHECK_COMMAND, SKILL_REUSE_RULE } from "./currentSkills.js";
 import { SESSION_BOOTSTRAP_MANIFEST_SCHEMA_VERSION, SESSION_CONTEXT_PROTOCOL, sessionManifestCompatibilityDigest } from "./sessionProtocolIdentity.js";
 export { SESSION_BOOTSTRAP_MANIFEST_SCHEMA_VERSION, SESSION_CONTEXT_PROTOCOL, sessionManifestCompatibilityDigest } from "./sessionProtocolIdentity.js";
 /** Portable read pointers accompany every managed input, including the first
@@ -22,11 +23,11 @@ export function withSessionContextPointer(text, environment) {
  * Unmediated/native clients retain the explicit diagnostic fallback. */
 export function sessionContextInstructions(manifestPath, digest) {
     return `Yui Session Manifest: ${manifestPath}${digest === undefined ? "" : ` (digest ${digest})`}. `
-        + "For inputs carrying the Yui Host Skill-check notice, engineering has checked current versions; do not repeat that check. "
-        + `Otherwise run its contextProtocol.skillCheckCommand (fallback: ${SKILL_CHECK_COMMAND}). `
+        + "The managed Host checks Skills internally and injects guidance only when loading is needed; absence of a notice does not require another check. "
+        + `For unmediated clients or uncertain current input routing, run its contextProtocol.skillCheckCommand (fallback: ${SKILL_CHECK_COMMAND}); conversation reuse alone does not establish Host mediation. `
         + "On first entry or lost instructions, read the current applicable Skill entry points, then only references needed for the current action. "
         + "On change reload affected instructions. Compaction does not require restoring every previously used procedure. "
-        + "Preserve the Manifest Role profile; metadata never proves loading or memory.";
+        + "Preserve the Manifest Role profile; metadata never proves loading or memory. Keep routine role, version and empty-inbox checks internal.";
 }
 /** The caller must already pass the ordinary managed Session/CLI/Home checks.
  * Old manifests remain immutable audit records, while this read resolves their
@@ -40,6 +41,15 @@ export function checkSessionSkills(home, manifestPath) {
         historicalPackagesAreAuditOnly: true
     };
 }
+export async function checkSessionSkillsAsync(home, manifestPath, signal) {
+    const manifest = validateSessionBootstrapManifest(JSON.parse(await readFile(resolve(manifestPath), { encoding: "utf8", signal })));
+    return {
+        skills: await checkCurrentSkillsAsync(home, manifest.skills.map(skill => skill.id), signal),
+        roleProfileRef: manifest.roleProfileRef,
+        rule: SKILL_REUSE_RULE,
+        historicalPackagesAreAuditOnly: true
+    };
+}
 /** Read back one immutable Session Manifest and verify its content digest. */
 export function readSessionBootstrapManifest(path) {
     const source = resolve(path);
@@ -50,6 +60,9 @@ export function readSessionBootstrapManifest(path) {
     catch (error) {
         throw new Error(`Session Manifest is unreadable: ${source}.`, { cause: error });
     }
+    return validateSessionBootstrapManifest(parsed);
+}
+function validateSessionBootstrapManifest(parsed) {
     if (parsed === null || typeof parsed !== "object") {
         throw new Error("Session Manifest is invalid.");
     }

package/dist/context/sessionSkillNotice.js

@@ -1,4 +1,26 @@
-import { checkSessionSkills } from "./sessionBootstrapManifest.js";
+import { checkSessionSkills, checkSessionSkillsAsync } from "./sessionBootstrapManifest.js";
+/** Early advisory checks do not commit notices or assert model memory. The
+ * next input still validates its exact metadata and emits only its own delta.
+ * Invalid metadata may reject that input, never a Session state transition. */
+export function createSessionSkillLifecycleCheck(home, environment) {
+    return {
+        id: "session-skills",
+        run: async (transition, signal) => {
+            if (!["connected", "interactive-connected", "settled"].includes(transition.event.type))
+                return;
+            const manifest = environment().YUI_SESSION_MANIFEST;
+            if (!manifest || signal.aborted)
+                return;
+            try {
+                await checkSessionSkillsAsync(home, manifest, signal);
+            }
+            catch (error) {
+                if (!signal.aborted)
+                    throw error;
+            }
+        }
+    };
+}
 /** Host-local last accepted metadata, never a model loading/memory receipt.
  * A new Host/attachment starts cold. No durable schema or input replay is added. */
 export function createSessionSkillNotice(home) {
@@ -10,9 +32,7 @@ export function createSessionSkillNotice(home) {
         prepare(text, environment, sessionKey, options = {}) {
             const manifest = environment.YUI_SESSION_MANIFEST;
             if (manifest === undefined)
-                return { text, commit() { } };
-            if (options.recovery)
-                invalidate();
+                return { text, inputText: text, commit() { } };
             let current;
             try {
                 current = checkSessionSkills(home, manifest);
@@ -21,7 +41,7 @@ export function createSessionSkillNotice(home) {
                 invalidate();
                 throw error; // Do not submit business input with an invalid current installation.
             }
-            const key = JSON.stringify([sessionKey, manifest, current.roleProfileRef]);
+            const key = JSON.stringify([sessionKey, manifest, current.roleProfileRef, options.contextEpoch]);
             const skills = new Map(current.skills.map(skill => [skill.id, JSON.stringify({
                     id: skill.id, path: skill.path, version: skill.version
                 })]));
@@ -30,17 +50,18 @@ export function createSessionSkillNotice(home) {
                 .map(([, value]) => value);
             const removed = !cold && [...previous.skills.keys()].some(id => !skills.has(id));
             // Every input is checked, but only a lifecycle/metadata event needs an
-            // instruction-loading notice. This marker distinguishes Host-mediated
-            // input from an unmediated client without restating the operating manual.
-            const lines = ["Yui Host checked current Skills; no Agent check needed."];
+            // instruction-loading notice. Unchanged input is passed through exactly.
+            const lines = [];
             if (cold || changed.length > 0 || removed) {
-                lines.push(`Yui Session Manifest: ${manifest}`, cold
-                    ? `First input or recovered attachment: read the exact Role profile at ${current.roleProfileRef.path} and the full current listed Skill entry points. Follow references only for the action you are taking, not to restore every previously used procedure. A Task role-profile projection is not this profile.`
-                    : "Skill metadata changed: load affected entries and applicable references; retain other complete instructions.", `Current Skill pointers: [${(removed ? [...skills.values()] : changed).join(",")}]`, "Metadata is not a loading receipt. Read each required file through EOF; if output is truncated, finish the missing ranges. Recover missing instructions for the current task, not the whole manual.");
+                lines.push(`Yui Session Manifest: ${manifest}`, "Host-managed Skill checks are active; unchanged input has no notice. Detached/unmediated clients must use the Manifest check fallback.", cold
+                    ? `Read the exact Role profile at ${current.roleProfileRef.path} (not a Task projection) and all current Skill entry points below. Follow references only for the current action.`
+                    : "Skill metadata changed: load affected entries and applicable references; retain other complete instructions.", `Current Skill pointers: [${(removed ? [...skills.values()] : changed).join(",")}]`, "Read required files through EOF. Metadata is not loaded instructions. Keep routine checks internal.");
             }
             const preparedGeneration = generation;
             return {
-                text: `${lines.join("\n")}\n\n${text}`,
+                text: lines.length === 0 ? text : `${lines.join("\n")}\n\n${text}`,
+                inputText: text,
+                ...(lines.length === 0 ? {} : { context: lines.join("\n") }),
                 commit() {
                     if (generation !== preparedGeneration)
                         return;

package/dist/controller/clientRuntime.js

@@ -59,21 +59,31 @@ export async function assertFileTaskControllerStorageCompatible(home, options =
 export async function ensureFileTaskController(home, options = {}) {
     const call = options.call ?? callController;
     await waitForForeignHandover(home, options);
-    try {
-        const status = await call(home, "controller.status", {});
-        assertCompatibleControllerStatus(status, options.expectedIdentity);
-        return status;
-    }
-    catch (error) {
-        if (!isUnavailable(error))
-            throw error;
+    const timeoutMs = positive(options.startupTimeoutMs, STARTUP_TIMEOUT_MS, "startupTimeoutMs");
+    const pollMs = positive(options.pollIntervalMs, POLL_INTERVAL_MS, "pollIntervalMs");
+    const probeDeadline = Date.now() + timeoutMs;
+    for (;;) {
+        try {
+            const status = await call(home, "controller.status", {});
+            assertCompatibleControllerStatus(status, options.expectedIdentity);
+            return status;
+        }
+        catch (error) {
+            if (isUnavailable(error))
+                break;
+            // A closing endpoint may reset a read even after its owner exited.
+            // Retry only this observation: ambiguity never authorizes a spawn.
+            if (!(error instanceof ControllerClientError)
+                || error.code !== "CONTROLLER_DELIVERY_UNKNOWN"
+                || Date.now() >= probeDeadline)
+                throw error;
+        }
+        await delay(pollMs);
     }
     // A handover may have started after the first lock check and before the
     // failed discovery/socket call. Re-check before spawning so a managed
     // Session can never resurrect the old Controller during an update.
     await waitForForeignHandover(home, options);
-    const timeoutMs = positive(options.startupTimeoutMs, STARTUP_TIMEOUT_MS, "startupTimeoutMs");
-    const pollMs = positive(options.pollIntervalMs, POLL_INTERVAL_MS, "pollIntervalMs");
     const spawnController = options.spawnController ?? spawnDetachedFileTaskController;
     // A readiness timeout is not exit evidence. Reuse the observable startup
     // process for this exact Home rather than multiplying unready Controllers.
@@ -213,17 +223,26 @@ async function waitForControllerProcessExit(controller, options) {
     const timeoutMs = positive(options.shutdownTimeoutMs, CONTROLLER_SHUTDOWN_TIMEOUT_MS, "shutdownTimeoutMs");
     const pollMs = positive(options.pollIntervalMs, POLL_INTERVAL_MS, "pollIntervalMs");
     const deadline = Date.now() + timeoutMs;
-    // This check is tri-state: unreadable OS identity throws rather than
-    // collapsing an unknown/live process into the absence of a Controller match.
-    while (processGenerationIsLive(controller.pid, controller.processStartIdentity)) {
-        if (process.platform === "linux") {
-            const observed = readLinuxProcessIdentity(controller.pid);
-            // Preserve the existing physical-stop boundary: an exact zombie has
-            // exited, even if its parent has not reaped the process table entry.
-            if (observed?.startIdentity === controller.processStartIdentity && observed.state === "Z")
+    for (;;) {
+        let observationError;
+        try {
+            if (!processGenerationIsLive(controller.pid, controller.processStartIdentity))
                 return;
+            if (process.platform === "linux") {
+                const observed = readLinuxProcessIdentity(controller.pid);
+                // An exact zombie has exited even before its parent reaps it.
+                if (observed?.startIdentity === controller.processStartIdentity && observed.state === "Z")
+                    return;
+            }
+        }
+        catch (error) {
+            // OS identity can disappear before kill(pid, 0) reports absence.
+            // Keep observing within the existing stop budget, never infer exit.
+            observationError = error;
         }
         if (Date.now() >= deadline) {
+            if (observationError !== undefined)
+                throw observationError;
             throw new ControllerClientError("CONTROLLER_TIMEOUT", `Controller process ${controller.pid} did not exit within ${timeoutMs} ms.`);
         }
         await delay(pollMs);

package/dist/controller/controller.js

@@ -14,7 +14,7 @@ import { KeyedWorkQueue } from "../coordination/keyedWorkQueue.js";
 import { MailboxScheduler } from "../coordination/mailboxScheduler.js";
 import { nearestDeadlineBatch } from "../coordination/deadlineScheduler.js";
 import { mailboxHasWork, nextPendingBatch } from "../coordination/workMailbox.js";
-import { hasRuntimeCleanupObligation } from "../runtime/lifecycleReservation.js";
+import { hasRuntimeCleanupObligation, runtimeCleanupDisposition } from "../runtime/lifecycleReservation.js";
 import { formatTaskRecordReference } from "../task/taskRecordReference.js";
 import { parseDurableJobAcknowledgeParams, parseDurableJobCancelParams, parseDurableJobRefParams, parseDurableJobStartParams } from "./jobControl.js";
 const DEFAULT_RECONCILIATION_INTERVAL_MS = reconciliationIntervalMilliseconds();
@@ -211,6 +211,12 @@ async function processSelectedRoleRuntimeCleanups(store, delivery, lifecycleHost
         const owner = runtimeOwner(target);
         const batchId = runtimeLifecycleBatchIdentity(target, mailbox);
         if (hasRuntimeCleanupObligation(mailbox)) {
+            // Upgrade is a graceful, exact-identity operation, never the destructive
+            // cleanup path. Its coordinator owns drain/restore; retain backpressure.
+            if (runtimeCleanupDisposition(mailbox) === "upgrade-host") {
+                markFailedRuntimeTarget(failedRoles, target);
+                continue;
+            }
             try {
                 if (lifecycleHost === undefined) {
                     throw new Error("Role runtime cleanup host is unavailable.");
@@ -698,6 +704,7 @@ export class FileTaskController {
     #providerRetry;
     #continuationReconciler;
     #hostTerminalRecovery;
+    #lifecycleChecks;
     #persistenceMetrics;
     #diagnosticMetrics;
     #current;
@@ -754,6 +761,7 @@ export class FileTaskController {
         this.#schedules = options.schedules;
         this.#continuationReconciler = options.continuationReconciler;
         this.#hostTerminalRecovery = options.hostTerminalRecovery;
+        this.#lifecycleChecks = options.lifecycleChecks;
         this.#globalInputDelivery = options.globalInputDelivery;
         this.#messageHealth = options.messageHealth;
         this.#providerRetry = options.providerRetry;
@@ -842,6 +850,7 @@ export class FileTaskController {
             return;
         if (this.#stopped)
             throw new Error("Controller runtime is stopped.");
+        this.#lifecycleChecks?.notify("startup");
         this.#requestBackgroundPump();
         this.#requestRuntimeObservation();
         // Arm the Operator lane once for work that was already pending when the
@@ -862,6 +871,7 @@ export class FileTaskController {
     }
     stop() {
         this.#stopped = true;
+        this.#lifecycleChecks?.close();
         this.#workspaceWaitAbort.abort(new Error("Controller stopped while waiting for Project maintenance."));
         this.#signalScheduler.stop();
         this.#operatorSignalScheduler.stop();
@@ -905,6 +915,7 @@ export class FileTaskController {
         if (this.#stopped)
             throw new Error("Controller runtime is stopped.");
         parseMailboxKey(key);
+        this.#lifecycleChecks?.notify("signal");
         if (key === "operator") {
             // Main lane owns durable Hook folding; the Operator lane is the sole
             // consumer of the Operator delivery mailbox.
@@ -1017,6 +1028,8 @@ export class FileTaskController {
                         }
                     }
                     const firstRuntimeDrain = await this.#phases.observe("runtime-drain", "home", () => this.#drainRuntimeEvents());
+                    if (scope.kind === "full")
+                        this.#lifecycleChecks?.notify("periodic");
                     if (scope.kind === "full" && this.#hostTerminalRecovery !== undefined) {
                         await this.#observeMaintenance("Host terminal recovery", this.#hostTerminalRecovery);
                     }
@@ -1258,6 +1271,8 @@ export class FileTaskController {
             ? await processor.drainAsync(this.#now())
             : processor.drain(this.#now());
         this.#lastRuntimeDrain = result;
+        if (result.acknowledgedEventIds.length > 0)
+            this.#lifecycleChecks?.notify("events-persisted");
         this.#runtimeDrainPasses += 1;
         const metrics = result.metrics ?? ZERO_DRAIN_METRICS;
         this.#runtimeListedEvents += metrics.listedEventCount;

package/dist/controller/fileSchedulerStoreAdapter.js

@@ -1723,6 +1723,8 @@ export class FileSchedulerStoreAdapter {
             const disposition = runtimeCleanupDisposition(mailbox);
             if (mailbox === null || disposition === null)
                 return false;
+            if (disposition === "upgrade-host")
+                return false;
             if (mailbox.processing !== null) {
                 if (disposition !== "replace-session" && !mailbox.processing.batch.reasons.every(isRuntimeCleanupReason)) {
                     return false;

package/dist/controller/hostLifecycle.js

@@ -0,0 +1,153 @@
+import { createRuntimeBinding } from "../runtime/runtimeBinding.js";
+import { normalizeRuntimeOwner } from "../runtime/runtimeOwner.js";
+import { RuntimeHostContentionError } from "../runtime/ports.js";
+const states = ["unavailable", "stopped", "starting", "running", "stopping"];
+export const CONTROLLER_HOST_TRANSITIONS = {
+    launch: { from: ["unavailable", "stopped", "running"], to: "starting" },
+    launched: { from: ["starting"], to: "running" },
+    stop: { from: states, to: "stopping" },
+    "exit-sent": { from: ["stopping"], to: "stopping" },
+    stopped: { from: ["stopping"], to: "stopped" },
+    failed: { from: ["starting", "stopping"], to: "unavailable" },
+    observed: { from: states, to: (current, observed) => current === "stopping" && (observed.state === "running" || observed.state === "starting")
+            ? "stopping" : observed.state }
+};
+/** All physical effects still require their existing durable caller authority.
+ * This process-local FSM gates competing effects at the shared Host port.
+ * Recovery observes current custody; it never invents a launch or replays one.
+ * Observation revisions reject late reads, not external process identities:
+ * exact OS/native identities remain owned by SessionOwner/Host fences. */
+export function createControllerHostLifecycle(raw, hooks = {}) {
+    const entries = new Map();
+    let nextOperation = 0;
+    const entryFor = (input) => {
+        const owner = normalizeRuntimeOwner(input);
+        const key = JSON.stringify(owner);
+        let entry = entries.get(key);
+        if (!entry) {
+            entry = { owner: Object.freeze(owner), state: "unavailable", revision: 0 };
+            entries.set(key, entry);
+        }
+        return entry;
+    };
+    const send = (entry, event, observed, binding) => {
+        const rule = CONTROLLER_HOST_TRANSITIONS[event];
+        if (!rule.from.includes(entry.state))
+            throw new RuntimeHostContentionError("previous-process", `Host lifecycle cannot ${event} from ${entry.state}.`);
+        const to = typeof rule.to === "function" ? rule.to(entry.state, observed) : rule.to;
+        const nativeSessionId = to === "stopped" ? undefined
+            : binding?.nativeSessionId ?? observed?.nativeSessionId ?? entry.nativeSessionId;
+        const bindingId = to === "stopped" ? undefined
+            : observed?.nativeSessionId && observed.nativeSessionId !== entry.nativeSessionId
+                ? undefined : binding?.id ?? entry.bindingId;
+        if (event === "observed" && to === entry.state && nativeSessionId === entry.nativeSessionId)
+            return;
+        const transition = Object.freeze({ owner: entry.owner, from: entry.state, to, event,
+            revision: entry.revision + 1, operationId: entry.operationId, nativeSessionId, bindingId });
+        hooks.before?.notify(transition);
+        entry.state = to;
+        entry.revision = transition.revision;
+        entry.nativeSessionId = nativeSessionId;
+        entry.bindingId = bindingId;
+        hooks.after?.notify(transition);
+    };
+    const observe = (entry, revision, inspection) => {
+        if (entry.revision === revision && entry.operationId === undefined)
+            send(entry, "observed", inspection);
+        return inspection;
+    };
+    const effect = async (owner, event, run) => {
+        const entry = entryFor(owner);
+        if (entry.operationId !== undefined)
+            throw new RuntimeHostContentionError("previous-process", `Host lifecycle already has an in-flight operation for ${owner.roleName}.`);
+        // Check state before reserving the operation; a rejected edge owns nothing.
+        if (!CONTROLLER_HOST_TRANSITIONS[event].from.includes(entry.state))
+            throw new RuntimeHostContentionError("previous-process", `Host lifecycle cannot ${event} from ${entry.state}.`);
+        entry.operationId = ++nextOperation;
+        send(entry, event);
+        try {
+            return await run(entry);
+        }
+        catch (error) {
+            send(entry, "failed");
+            throw error;
+        }
+        finally {
+            entry.operationId = undefined;
+        }
+    };
+    const inspectOwner = async (owner) => {
+        const entry = entryFor(owner), revision = entry.revision;
+        return observe(entry, revision, await raw.inspectOwner(owner));
+    };
+    const launch = async (request, before) => {
+        await inspectOwner(request.owner);
+        return effect(request.owner, "launch", async (entry) => {
+            const binding = createRuntimeBinding(request.mode === "new"
+                ? await raw.start(request, before) : await raw.restore(request, before));
+            if (JSON.stringify(normalizeRuntimeOwner(binding.owner)) !== JSON.stringify(entry.owner)
+                || binding.agentId !== request.agentId || binding.adapterId !== request.adapterId
+                || request.mode === "resume" && binding.nativeSessionId !== request.nativeSessionId) {
+                throw new Error("Host lifecycle launch handshake has mismatched owner/native identity.");
+            }
+            send(entry, "launched", undefined, binding);
+            return binding;
+        });
+    };
+    const port = {
+        start: launch, restore: launch, inspectOwner,
+        inspect: async (binding) => {
+            const entry = entryFor(binding.owner), revision = entry.revision;
+            const inspection = await raw.inspect(binding);
+            if (entry.bindingId && entry.bindingId !== binding.id
+                || entry.nativeSessionId && binding.nativeSessionId !== entry.nativeSessionId)
+                return inspection;
+            return observe(entry, revision, inspection);
+        },
+        ...(raw.inspectOwners === undefined ? {} : {
+            inspectOwners: async (owners) => {
+                const revisions = new Map(owners.map(owner => {
+                    const entry = entryFor(owner);
+                    return [entry, entry.revision];
+                }));
+                const results = await raw.inspectOwners(owners);
+                for (const { owner, inspection } of results) {
+                    const entry = entryFor(owner), revision = revisions.get(entry);
+                    if (revision !== undefined)
+                        observe(entry, revision, inspection);
+                }
+                return results;
+            }
+        }),
+        stop: async (binding) => {
+            const current = entryFor(binding.owner);
+            if (current.nativeSessionId && binding.nativeSessionId !== current.nativeSessionId
+                || current.bindingId && binding.id !== current.bindingId) {
+                throw new Error("Host lifecycle stop carries a stale binding identity.");
+            }
+            return effect(binding.owner, "stop", async (entry) => {
+                await raw.stop(binding);
+                const observed = await raw.inspect(binding);
+                if (observed.state !== "stopped")
+                    throw new Error("Host lifecycle stop has no physical exit proof.");
+                send(entry, "stopped");
+            });
+        },
+        stopOwner: owner => effect(owner, "stop", async (entry) => {
+            const stopped = await (hooks.stopOwner ? hooks.stopOwner(owner) : raw.stopOwner(owner));
+            send(entry, stopped ? "stopped" : "failed");
+            return stopped;
+        })
+    };
+    return {
+        port,
+        snapshot: (owner) => Object.freeze({ ...entryFor(owner) }),
+        // Graceful exit acknowledgement is not exit proof. A later physical
+        // observation moves stopping -> stopped; no timer or automatic replay.
+        requestExit: (owner, run) => effect(owner, "stop", async (entry) => {
+            const result = await run();
+            send(entry, "exit-sent");
+            return result;
+        })
+    };
+}