@zq-silk/yui 0.14.2 → 0.15.1

package/dist/controller/runtimeLaunchCoordinator.js

@@ -1,7 +1,7 @@
-import { createHash, randomUUID } from "node:crypto";
+import { randomUUID } from "node:crypto";
 import { runtimeLifecycleTarget } from "../runtime/lifecycleReservation.js";
 import { createRuntimeBinding, RuntimeGenerationMismatchError, RuntimeHostContentionError, RuntimeLaunchError } from "../runtime/index.js";
-import { effectiveLaunchSnapshotsCompatible, validateEffectiveLaunchSnapshot } from "../executor/effectiveLaunch.js";
+import { sameEffectiveLaunch, validateEffectiveLaunchSnapshot } from "../executor/effectiveLaunch.js";
 class RuntimeBindingContractError extends Error {
     constructor(message, options) {
         super(message, options);
@@ -25,7 +25,6 @@ export class RuntimeLaunchCoordinator {
     #createGenerationId;
     #now;
     #assertCurrent;
-    #launchFingerprint;
     #onCleanupRequired;
     #runtimeIsolation;
     constructor(reservations, host, options = {}) {
@@ -34,8 +33,6 @@ export class RuntimeLaunchCoordinator {
         this.#createGenerationId = options.createGenerationId ?? randomUUID;
         this.#now = options.now ?? (() => new Date());
         this.#assertCurrent = options.assertCurrent;
-        this.#launchFingerprint = options.launchFingerprint
-            ?? defaultLaunchFingerprint;
         this.#onCleanupRequired = options.onCleanupRequired;
         this.#runtimeIsolation = options.runtimeIsolation;
     }
@@ -79,22 +76,19 @@ export class RuntimeLaunchCoordinator {
         if (request.owner.scope === "global" && request.managedWorkspace !== undefined) {
             throw new Error("A global runtime cannot use a Task ManagedWorkspace.");
         }
-        const expectedFingerprint = requireText(this.#launchFingerprint(request), "Launch fingerprint");
         const assertLaunchCurrent = () => {
             this.#assertCurrent?.(request);
             assertCurrent?.();
-            if (this.#launchFingerprint(request) !== expectedFingerprint) {
-                throw new Error(`Role or Agent launch state changed: ${request.owner.roleName}.`);
-            }
         };
-        const generationPrefix = `runtime-${expectedFingerprint}:generation:`;
         const proposedGenerationId = requireText(this.#createGenerationId(), "Launch generation id");
-        let proposedRuntimeGenerationId = `${generationPrefix}${proposedGenerationId}`;
+        // A Host activation id is an opaque durable identity, not a digest of the
+        // launch configuration. Whether a live activation may be reused is answered
+        // by the Role's durable Session record through `assertCurrent`, so launch
+        // configuration that only shapes the next activation never invalidates the
+        // current one.
+        let proposedRuntimeGenerationId = `runtime-${proposedGenerationId}`;
         let reusedConfirmedRunningHost = false;
         if (request.mode === "resume" && request.hostActivationId !== undefined) {
-            if (!request.hostActivationId.startsWith(generationPrefix)) {
-                throw new Error("Session restore targets an incompatible Host activation.");
-            }
             const inspection = await this.host.inspectOwner(request.owner);
             if (inspection.state === "unavailable" || inspection.state === "starting") {
                 throw new RuntimeLaunchError(true, request.hostActivationId, `Host activation is temporarily ${inspection.state}: ${request.owner.roleName}.`);
@@ -112,10 +106,6 @@ export class RuntimeLaunchCoordinator {
             runtimeGenerationId: proposedRuntimeGenerationId
         }, assertLaunchCurrent, this.#now());
         if (reservation.status === "existing") {
-            if (!reservation.runtimeGenerationId.startsWith(generationPrefix)) {
-                this.#requireCleanup(request.owner);
-                throw new Error(`Runtime launch reservation belongs to stale Role or Agent state: ${request.owner.roleName}.`);
-            }
             const inspection = await this.host.inspectOwner(request.owner);
             if (inspection.state === "unavailable" || inspection.state === "starting") {
                 throw new RuntimeLaunchError(true, reservation.runtimeGenerationId, `Runtime is temporarily ${inspection.state}: ${request.owner.roleName}/${reservation.runtimeGenerationId}.`);
@@ -416,7 +406,7 @@ function validateRuntimeLaunchPreflight(preflight, request, runtimeGenerationId)
         || preflight.turnId !== request.turnId
         || preflight.agentId !== request.agentId
         || preflight.adapterId !== request.adapterId
-        || !effectiveLaunchSnapshotsCompatible(preflight.effective, request.effective)
+        || !sameEffectiveLaunch(preflight.effective, request.effective)
         || (request.mode === "resume"
             && preflight.nativeSessionId !== request.nativeSessionId)) {
         throw new Error(`Session host pre-start launch fence does not match the requested runtime: ${request.owner.roleName}.`);
@@ -445,17 +435,6 @@ function requireMatchingRuntimeBinding(raw, request, runtimeGenerationId) {
     }
     return binding;
 }
-function defaultLaunchFingerprint(request) {
-    return createHash("sha256").update(JSON.stringify([
-        request.owner,
-        request.agentId,
-        request.adapterId,
-        request.effective,
-        request.workspace,
-        request.managedWorkspace,
-        request.runtimePolicy
-    ])).digest("hex");
-}
 function requireText(value, label) {
     if (typeof value !== "string"
         || value.length === 0

package/dist/controller/sessionNotify.js

@@ -7,6 +7,11 @@ import { openCurrentTaskStore } from "../storage/currentTaskStore.js";
 /** Hidden CLI entrypoint used by Codex's structured notify hook. */
 export async function runSessionNotifyCommand(payloadArgument, environment = process.env, call, setThreadName = setCodexThreadName) {
     const params = parseCodexSessionNotification(payloadArgument, environment);
+    // Old global TUIs can still emit their invocation-local hook. It is not
+    // evidence of a shared-daemon Thread's identity or process lifecycle.
+    // Global identity is committed from App Server at successful host start.
+    if (params.scope === "global")
+        return;
     const home = requireText(environment.YUI_HOME, "YUI_HOME");
     // A Codex process outlives its Turn, so the notify envelope cannot say which
     // Turn or runtime generation is current. Durable Session state answers both;

package/dist/core/controllerServer.js

@@ -400,8 +400,8 @@ async function routeRequest(socket, line, token, dispatcher, stop, status, telem
                 homeFilesystemId,
                 controllerInstanceId,
                 version: YUI_VERSION,
-                storageLayoutVersion: yuiVersionIdentity().storageLayoutVersion,
-                aggregateSchemaVersion: yuiVersionIdentity().aggregateSchemaVersion,
+                storageVersion: yuiVersionIdentity().storageVersion,
+                minimumStorageVersion: yuiVersionIdentity().minimumStorageVersion,
                 ...(status === undefined ? {} : { runtime: status(telemetry) })
             }
         });
@@ -675,7 +675,7 @@ export function buildRuntimeIdentityReceipt(input) {
         }
     })();
     return Object.freeze({
-        schemaVersion: 1,
+        schemaVersion: 2,
         version: YUI_VERSION,
         executablePath: process.execPath,
         args: process.argv.slice(1),
@@ -685,8 +685,8 @@ export function buildRuntimeIdentityReceipt(input) {
         cliRealpath: controllerCliRealpath(),
         controllerRealpath: realpathSync(fileURLToPath(import.meta.url)),
         controllerProtocolVersion: FILE_TASK_CONTROLLER_PROTOCOL_VERSION,
-        storageLayoutVersion: yuiVersionIdentity().storageLayoutVersion,
-        aggregateSchemaVersion: yuiVersionIdentity().aggregateSchemaVersion,
+        storageVersion: yuiVersionIdentity().storageVersion,
+        minimumStorageVersion: yuiVersionIdentity().minimumStorageVersion,
         storageBackend: input.storageBackend,
         workerEnabled: input.workerEnabled,
         pid: process.pid,

package/dist/doctor/doctor.js

@@ -34,7 +34,7 @@ export const STORAGE_DOCTOR_CHECK_NAMES = Object.freeze([
  * healthy only when schema, compatibility, and state are all `ok`. Any
  * `unsupported` (version mismatch / needs-new-version), `invalid` (corrupted /
  * unreadable), or `missing` (uninitialized) storage check is blocking — even
- * though `yui doctor` itself exits 0.
+ * and the machine-readable command exits non-zero.
  */
 export function summarizeStorageHealth(checks) {
     const names = new Set(STORAGE_DOCTOR_CHECK_NAMES);
@@ -56,14 +56,16 @@ export function buildDoctorReport(env, executor) {
 }
 /**
  * Read the physical-backend facts for a Home (Issue 01 observability). Every
- * field is best-effort read-only evidence: an unreadable database or manifest
- * yields `null` for that field, and the `storage state` check reports the
- * structural problem separately.
+ * field is best-effort read-only evidence: an unreadable database yields
+ * `null` for that field, and the `storage state` check reports the structural
+ * problem separately.
  */
 function inspectStorageDetails(home, env) {
     const schema = inspectStorageSchema(home);
-    const logicalLayout = schema.status === "current" || schema.status === "unsupported"
-        ? schema.currentLayoutVersion
+    const storageVersion = schema.status === "current"
+        || schema.status === "upgradeable"
+        || schema.status === "unsupported"
+        ? schema.currentVersion
         : null;
     const authoritativeBackend = "sqlite";
     const dbPath = join(home, CURRENT_DATABASE_FILENAME);
@@ -88,7 +90,8 @@ function inspectStorageDetails(home, env) {
         }
     }
     return {
-        logicalLayout,
+        storageVersion,
+        minimumSupportedVersion: schema.minimumSupportedVersion,
         authoritativeBackend,
         databasePath,
         journalMode,
@@ -216,13 +219,22 @@ function checkSchema(state) {
             return {
                 name: "storage schema",
                 status: "ok",
-                detail: `current=${state.currentVersion} latest=${state.latestVersion}`
+                detail: `current=${state.currentVersion} latest=${state.latestVersion} `
+                    + `minimum=${state.minimumSupportedVersion}`
+            };
+        case "upgradeable":
+            return {
+                name: "storage schema",
+                status: "unsupported",
+                detail: `current=${state.currentVersion} latest=${state.latestVersion} `
+                    + `minimum=${state.minimumSupportedVersion} migration=available`
             };
         case "unsupported":
             return {
                 name: "storage schema",
                 status: "unsupported",
-                detail: `current=${state.currentVersion} latest=${state.latestVersion} direction=${state.direction}`
+                detail: `current=${state.currentVersion} latest=${state.latestVersion} `
+                    + `minimum=${state.minimumSupportedVersion} direction=${state.direction}`
             };
         case "invalid":
             return { name: "storage schema", status: "invalid", detail: state.detail };
@@ -251,9 +263,20 @@ function inspectCompatibility(home, homeCheck, schema) {
             check: {
                 name,
                 status: "unsupported",
-                detail: `unsupported contract: ${schema.incompatibleComponent} is ${schema.direction} `
-                    + `(current=${schema.currentVersion}, required=${schema.latestVersion}). `
-                    + "Preserve this Home and initialize a new Home."
+                detail: `storage version is ${schema.direction} `
+                    + `(current=${schema.currentVersion}, supported=`
+                    + `${schema.minimumSupportedVersion}..${schema.latestVersion}).`
+            }
+        };
+    }
+    if (schema.status === "upgradeable") {
+        return {
+            storageStatus: "upgradeable",
+            check: {
+                name,
+                status: "unsupported",
+                detail: `migration available from ${schema.currentVersion} to ${schema.latestVersion}; `
+                    + "run `yui upgrade` or `yui update`."
             }
         };
     }
@@ -262,8 +285,8 @@ function inspectCompatibility(home, homeCheck, schema) {
         check: {
             name,
             status: "ok",
-            detail: `current layout=${schema.currentLayoutVersion}/${schema.latestLayoutVersion} `
-                + `aggregate=${schema.currentAggregateSchemaVersion}/${schema.latestAggregateSchemaVersion}`
+            detail: `current=${schema.currentVersion}/${schema.latestVersion} `
+                + `minimum=${schema.minimumSupportedVersion}`
         }
     };
 }

package/dist/executor/agentExecutor.js

@@ -1,6 +1,6 @@
 import { createHash } from "node:crypto";
 import { hasRecentTurnId, rememberRecentTurnId, validateRecentTurnIds } from "../runtime/recentTurnIds.js";
-import { effectiveLaunchSnapshotsCompatible, effectiveLaunchSnapshotsCompatibleForTaskSession, validateEffectiveLaunchSnapshot } from "./effectiveLaunch.js";
+import { roleSessionMayContinue, validateEffectiveLaunchSnapshot } from "./effectiveLaunch.js";
 import { currentProviderActivation, endProviderActivation, settleProviderTurn, settleProviderTurnSubmission, validateProviderRuntimeBinding } from "../runtime/providerRuntimeIdentity.js";
 import { builtinDriverIdForAdapter } from "../runtime/builtinAgentDrivers.js";
 export function createRoleSessionSet(owner, activeAgentId, now) {
@@ -66,10 +66,9 @@ export function recordRoleAgentSession(set, input, now) {
         throw new Error(`Role Agent session effective identity is inconsistent: ${agentId}.`);
     }
     if (existing !== undefined && existing.nativeSessionId === nativeSessionId
-        && !effectiveLaunchSnapshotsCompatible(existing.effective, effective)
-        && !(set.owner.scope === "task"
-            && effectiveLaunchSnapshotsCompatibleForTaskSession(existing.effective, effective))) {
-        throw new Error(`Role Agent session effective launch cannot change: ${agentId}.`);
+        && !roleSessionMayContinue(existing.effective, effective)) {
+        throw new Error(`Role Agent session cannot continue under this launch: ${agentId}. `
+            + "Its Agent, adapter or physical workspace changed.");
     }
     if (existing !== undefined && existing.nativeSessionId !== nativeSessionId
         && existing.status === "active") {
@@ -280,13 +279,11 @@ export function roleAgentSessionResumeMode(set, agentId, desired) {
     if (session.status === "ended") {
         return "new";
     }
-    const compatible = set.owner.scope === "task"
-        ? effectiveLaunchSnapshotsCompatibleForTaskSession(session.effective, desired)
-        : effectiveLaunchSnapshotsCompatible(session.effective, desired);
-    if (compatible)
+    if (roleSessionMayContinue(session.effective, desired))
         return "resume";
-    throw new Error(`Role Agent session is incompatible with the next effective launch: ${agentId}. `
-        + "Stop the existing native process before starting a fresh Session.");
+    throw new Error(`Role Agent session cannot continue under the next launch: ${agentId}. `
+        + "Its Agent, adapter or physical workspace changed; stop the existing native "
+        + "process before starting a fresh Session.");
 }
 export function bindTaskRoleProviderRuntime(set, binding, updatedAt) {
     validateRoleSessionSet(set);

package/dist/executor/effectiveLaunch.js

@@ -69,7 +69,12 @@ function claudeConfigFromSnapshot(snapshot) {
             : { settingsSources: [...snapshot.settingsSources] })
     };
 }
-export function effectiveLaunchSnapshotsCompatible(existing, desired) {
+/**
+ * Exactness fence for one launch: the same resolved launch must be observed by
+ * every participant of that launch. Desired-revision bookkeeping is provenance
+ * and never part of the resolved launch itself.
+ */
+export function sameEffectiveLaunch(existing, desired) {
     validateEffectiveLaunchSnapshot(existing);
     validateEffectiveLaunchSnapshot(desired);
     const withoutDesiredRevision = (snapshot) => {
@@ -79,20 +84,24 @@ export function effectiveLaunchSnapshotsCompatible(existing, desired) {
     return isDeepStrictEqual(withoutDesiredRevision(existing), withoutDesiredRevision(desired));
 }
 /**
- * Task Role Sessions keep one physical workspace while Turn-scoped facts move.
- * Candidate commits, ReviewRound identity and desired-revision bookkeeping do
- * not define a native Session. Agent, adapter, permission, model, sandbox,
- * manifest, Role context and physical workspace identity still do.
+ * Whether a live native Session can still serve the next launch request.
+ *
+ * Only facts that make continuation impossible participate: the Session
+ * protocol, the provider identity that owns the conversation, and the physical
+ * workspace the Session runs in. Launch configuration such as model, effort,
+ * permission, Role context, declared write scope, and Turn-scoped facts like
+ * ReviewRound identity or candidate commits shape the next Host activation
+ * instead of ending the Session; that divergence is acknowledged where the
+ * configuration changes and stays visible as launch provenance.
+ *
+ * Session kind needs no separate check: a Role's review Turns run in their own
+ * ReviewRound workspace, so the physical workspace already separates a review
+ * Session from an execution Session.
  */
-export function effectiveLaunchSnapshotsCompatibleForTaskSession(existing, desired) {
-    if (effectiveLaunchSnapshotsCompatible(existing, desired))
-        return true;
+export function roleSessionMayContinue(existing, desired) {
     validateEffectiveLaunchSnapshot(existing);
     validateEffectiveLaunchSnapshot(desired);
-    if ((existing.reviewRoundId === undefined) !== (desired.reviewRoundId === undefined)) {
-        return false;
-    }
-    return isDeepStrictEqual(taskSessionCompatibleSnapshot(existing), taskSessionCompatibleSnapshot(desired));
+    return isDeepStrictEqual(sessionContinuitySnapshot(existing), sessionContinuitySnapshot(desired));
 }
 /** Preserves a fixed Session's launch configuration while freezing fresh Task-main Git facts. */
 export function effectiveLaunchWithTaskMainWorkspace(existing, workspace) {
@@ -109,13 +118,21 @@ export function effectiveLaunchWithTaskMainWorkspace(existing, workspace) {
         }
     });
 }
-function taskSessionCompatibleSnapshot(snapshot) {
-    const { sourceDesiredRevision: _sourceDesiredRevision, reviewRoundId: _reviewRoundId, reviewBaseCommit: _reviewBaseCommit, workspace, ...launch } = snapshot;
+function sessionContinuitySnapshot(snapshot) {
     return {
-        ...launch,
+        schemaVersion: snapshot.schemaVersion,
+        contextProtocolVersion: snapshot.contextProtocolVersion,
+        agentId: snapshot.agentId,
+        adapterId: snapshot.adapterId,
         workspace: {
-            root: workspace.root,
-            entries: workspace.entries.map(({ baseCommit: _baseCommit, baseRef: _baseRef, ...entry }) => entry)
+            root: snapshot.workspace.root,
+            entries: snapshot.workspace.entries.map((entry) => ({
+                projectId: entry.projectId,
+                directory: entry.directory,
+                access: entry.access,
+                path: entry.path,
+                branch: entry.branch
+            }))
         }
     };
 }

package/dist/executor/fileRoleLaunchPlanner.js

@@ -15,7 +15,7 @@ import { resolveTaskRoleSessionTitle } from "../runtime/sessionTitle.js";
 import { nativeSessionIdForLaunch } from "../runtime/preallocatedNativeSession.js";
 import { classifyWorkspacePreflight, formatWorkspacePreflightError } from "./workspacePreflightClassification.js";
 import { activeLiveRoleAgentSession } from "./agentExecutor.js";
-import { effectiveLaunchSnapshotsCompatibleForTaskSession, effectiveLaunchSnapshotsCompatible, effectiveRoleForLaunch, resolveEffectiveLaunch } from "./effectiveLaunch.js";
+import { roleSessionMayContinue, effectiveRoleForLaunch, resolveEffectiveLaunch } from "./effectiveLaunch.js";
 import { YUI_CONTROL_PLANE_DESCRIPTOR, createExactControlPlaneDescriptor, serializeExactDescriptor } from "../runtime/exactControlPlane.js";
 import { detectRunningRelease } from "../release/runtimeRelease.js";
 import { parseTaskRuntimeIsolationDescriptor, taskRuntimeIsolationEnvironment } from "../runtime/taskRuntimeIsolation.js";
@@ -176,9 +176,7 @@ export class FileRoleLaunchPlanner {
         const effective = input.effective ?? resolvedEffective;
         const existing = sessionSet?.sessions[effective.agentId];
         const compatibleExisting = existing !== undefined
-            && (input.mode === "resume"
-                ? effectiveLaunchSnapshotsCompatibleForTaskSession(existing.effective, effective)
-                : effectiveLaunchSnapshotsCompatible(existing.effective, effective));
+            && roleSessionMayContinue(existing.effective, effective);
         if (input.mode === "resume" && !compatibleExisting) {
             throw new Error(`Task Role resume effective snapshot drifted: ${task.id}/${role.name}.`);
         }
@@ -204,7 +202,7 @@ export class FileRoleLaunchPlanner {
         const effective = input.effective ?? resolvedEffective;
         const existing = sessionSet?.sessions[effective.agentId];
         const compatibleExisting = existing !== undefined
-            && effectiveLaunchSnapshotsCompatible(existing.effective, effective);
+            && roleSessionMayContinue(existing.effective, effective);
         if (input.mode === "resume" && !compatibleExisting) {
             throw new Error(`Global Role resume effective snapshot drifted: ${role.name}.`);
         }
@@ -246,7 +244,9 @@ export class FileRoleLaunchPlanner {
                     : undefined,
                 trustWorkspace: true
             });
-            assertCodexLaunchOverridesAvailable(codexConfig, ["developerInstructions", "notify"]);
+            assertCodexLaunchOverridesAvailable(codexConfig, owner.scope === "global"
+                ? ["developerInstructions"]
+                : ["developerInstructions", "notify"]);
         }
         const runtimeIsolation = input.runtimeIsolation === undefined
             ? undefined
@@ -365,10 +365,10 @@ export class FileRoleLaunchPlanner {
             args.push("--plugin-dir", ensureClaudeLifecyclePlugin(this.home, this.#cliPath));
         }
         if (binding.adapterId === "codex") {
-            // Global/interactive Codex sessions still use notify for presentation.
+            // Interactive Task sessions may use notify for presentation.
             // Managed Turns receive lifecycle facts through their ordinary App Server
             // subscription, avoiding a second Hook channel for the same Turn.
-            if (owner.scope !== "task" || input.turnId === undefined) {
+            if (owner.scope === "task" && input.turnId === undefined) {
                 args = addCodexSessionNotify(args, launchMode, this.#cliPath);
             }
             // Managed Codex Turns use disposable proxy clients against the shared
@@ -472,6 +472,9 @@ export class FileRoleLaunchPlanner {
                 YUI_WORKSPACE: effectiveWorkspace,
                 YUI_SESSION_MANIFEST: sessionContext.sessionManifestPath,
                 YUI_SESSION_CLI: sessionContext.sessionCliPath,
+                ...(owner.scope === "global" && configured.adapterId === "codex"
+                    ? { YUI_AGENT_BASE_ARGS: JSON.stringify(configured.baseArgs) }
+                    : {}),
                 ...(jobCallerKey === undefined ? {} : { YUI_JOB_CALLER_KEY: jobCallerKey }),
                 ...(owner.scope !== "task"
                     ? {}

package/dist/observability/runtimeIdentity.js

@@ -13,7 +13,8 @@ import { spawnSync } from "node:child_process";
 import { existsSync, readdirSync, readFileSync, realpathSync, statSync } from "node:fs";
 import { join } from "node:path";
 import Database from "better-sqlite3";
-import { CURRENT_AGGREGATE_SCHEMA_VERSION, CURRENT_STORAGE_LAYOUT_VERSION } from "../storage/storageVersions.js";
+import { CURRENT_STORAGE_VERSION, MIN_SUPPORTED_STORAGE_VERSION } from "../storage/storageVersions.js";
+import { inspectStorageSchema } from "../storage/storageSchema.js";
 import { resolveStoreWorkerEnabledForHome } from "../storage/storeRpc.js";
 export const UNSUPPORTED = "unsupported";
 /**
@@ -140,14 +141,7 @@ export function collectRuntimeBuildIdentity(ports) {
 export function createProductionStorageIdentityPorts(env = process.env) {
     return {
         env,
-        readText: (path) => {
-            try {
-                return readFileSync(path, "utf8");
-            }
-            catch {
-                return null;
-            }
-        },
+        inspectStorage: (home) => inspectStorageSchema(home),
         fileSize: (path) => {
             try {
                 return statSync(path).size;
@@ -181,36 +175,12 @@ export function createProductionStorageIdentityPorts(env = process.env) {
  * are never treated as an alternate authority or a repair source.
  */
 export function collectStorageIdentity(home, ports = createProductionStorageIdentityPorts()) {
-    const manifestPath = join(home, "schema.json");
-    const manifestText = ports.readText(manifestPath);
-    let manifestStatus = "uninitialized";
-    let logicalLayout = UNSUPPORTED;
-    let aggregateSchemaVersion = UNSUPPORTED;
-    if (manifestText !== null) {
-        manifestStatus = "current";
-        try {
-            const manifest = JSON.parse(manifestText);
-            if (typeof manifest.storageVersion === "number"
-                && Number.isFinite(manifest.storageVersion)) {
-                logicalLayout = manifest.storageVersion;
-            }
-            if (typeof manifest.aggregateSchemaVersion === "number"
-                && Number.isFinite(manifest.aggregateSchemaVersion)) {
-                aggregateSchemaVersion = manifest.aggregateSchemaVersion;
-            }
-            if (typeof logicalLayout !== "number"
-                || typeof aggregateSchemaVersion !== "number"
-                || logicalLayout !== CURRENT_STORAGE_LAYOUT_VERSION
-                || aggregateSchemaVersion !== CURRENT_AGGREGATE_SCHEMA_VERSION) {
-                manifestStatus = "unsupported";
-            }
-        }
-        catch {
-            manifestStatus = "invalid";
-            logicalLayout = UNSUPPORTED;
-            aggregateSchemaVersion = UNSUPPORTED;
-        }
-    }
+    const storage = ports.inspectStorage(home);
+    const storageVersion = storage.status === "current"
+        || storage.status === "upgradeable"
+        || storage.status === "unsupported"
+        ? storage.currentVersion
+        : UNSUPPORTED;
     const statePath = join(home, "state.json");
     const statePresent = ports.exists(statePath);
     const stateBytes = ports.fileSize(statePath);
@@ -223,7 +193,7 @@ export function collectStorageIdentity(home, ports = createProductionStorageIden
     const workerEnabled = resolveStoreWorkerEnabledForHome(home, ports.env);
     const dbHealth = dbPresent ? ports.probeDatabaseHealth(dbPath) : null;
     const findings = [];
-    if (manifestStatus === "current" && !dbPresent) {
+    if (storage.status === "current" && !dbPresent) {
         findings.push({
             code: "current-database-missing",
             severity: "contradiction",
@@ -231,20 +201,48 @@ export function collectStorageIdentity(home, ports = createProductionStorageIden
             remediation: "Preserve this Home for diagnosis and initialize a new Home."
         });
     }
-    if (manifestStatus === "unsupported") {
+    if (storage.status === "uninitialized") {
+        findings.push({
+            code: "storage-uninitialized",
+            severity: "needs-repair",
+            message: "Yui storage has not been initialized for this Home.",
+            remediation: "Run `yui setup` for a new, empty Home."
+        });
+    }
+    if (storage.status === "upgradeable") {
+        findings.push({
+            code: "storage-upgrade-required",
+            severity: "needs-repair",
+            message: `Storage version ${storage.currentVersion} requires migration to `
+                + `${CURRENT_STORAGE_VERSION}.`,
+            remediation: "Run `yui upgrade` or `yui update` before resuming writes."
+        });
+    }
+    if (storage.status === "unsupported") {
         findings.push({
             code: "unsupported-storage-contract",
             severity: "contradiction",
-            message: "The Home does not match this release's exact storage contract.",
-            remediation: "Open it read-only with its original Yui version, then let the Operator recreate unfinished work in a new Home."
+            message: `Storage version ${storage.currentVersion} is outside the supported migration range `
+                + `${MIN_SUPPORTED_STORAGE_VERSION}..${CURRENT_STORAGE_VERSION}.`,
+            remediation: storage.direction === "newer"
+                ? "Use a newer Yui release."
+                : "Use a Yui release whose migration floor includes this Home."
         });
     }
-    if (manifestStatus === "invalid") {
+    if (storage.status === "invalid") {
         findings.push({
-            code: "invalid-storage-manifest",
+            code: "invalid-storage",
             severity: "contradiction",
-            message: "schema.json is invalid.",
-            remediation: "Preserve this Home for diagnosis and initialize a new Home."
+            message: storage.detail,
+            remediation: "Preserve this Home for diagnosis and restore a known-good backup."
+        });
+    }
+    if (ports.exists(join(home, "schema.json"))) {
+        findings.push({
+            code: "ignored-legacy-storage-manifest",
+            severity: "warning",
+            message: "schema.json is legacy metadata and is not a storage authority.",
+            remediation: "A successful storage upgrade removes it automatically."
         });
     }
     if (dbPresent && dbHealth !== null && dbHealth !== "ok") {
@@ -274,9 +272,9 @@ export function collectStorageIdentity(home, ports = createProductionStorageIden
     }
     return {
         home,
-        manifestStatus,
-        logicalLayout,
-        aggregateSchemaVersion,
+        storageStatus: storage.status,
+        storageVersion,
+        minimumStorageVersion: MIN_SUPPORTED_STORAGE_VERSION,
         configuredBackend,
         workerEnabled,
         physicalStateJson: {

package/dist/release/runtimeRelease.js

@@ -484,7 +484,7 @@ function validatePointer(value) {
 function validateRuntimeIdentity(value) {
     if (value === null
         || typeof value !== "object"
-        || value.schemaVersion !== 1
+        || value.schemaVersion !== 2
         || typeof value.version !== "string"
         || typeof value.executablePath !== "string"
         || value.executablePath === ""
@@ -492,6 +492,11 @@ function validateRuntimeIdentity(value) {
         || typeof value.buildId !== "string"
         || typeof value.cliRealpath !== "string"
         || typeof value.controllerRealpath !== "string"
+        || !isPositiveInteger(value.controllerProtocolVersion)
+        || !isPositiveInteger(value.storageVersion)
+        || !isPositiveInteger(value.minimumStorageVersion)
+        || value.minimumStorageVersion
+            > value.storageVersion
         || typeof value.pid !== "number"
         || typeof value.processStartIdentity !== "string"
         || (value.mode !== "primary"
@@ -520,6 +525,9 @@ function isHandoverPhase(value) {
 function isStringArray(value) {
     return Array.isArray(value) && value.every((entry) => typeof entry === "string");
 }
+function isPositiveInteger(value) {
+    return Number.isSafeInteger(value) && value > 0;
+}
 function isEexist(error) {
     return isNodeError(error) && error.code === "EEXIST";
 }

package/dist/runtime/agentHost.js

@@ -17,6 +17,7 @@ import { persistRuntimeProcessExitObservation, replayRuntimeProcessExitOutbox }
 import { readRuntimeStopReceipt, removeRuntimeStopReceipt } from "./runtimeStopReceipt.js";
 import { AGENT_HOST_CONTROL_TIMEOUT_MS, AGENT_HOST_READY_TIMEOUT_MS } from "./runtimeDeadlines.js";
 import { serializeAgentErrorRaw } from "./agentError.js";
+import { runCodexInteractiveHost } from "./codexInteractiveHost.js";
 export const AGENT_HOST_CONTROL_PROTOCOL = "yui-agent-host/v4";
 const HOST_CONTROL_MAX_BYTES = 32 * 1024;
 const CODEX_CLIENT_STABLE_MS = 5_000;
@@ -28,6 +29,11 @@ export async function runAgentHost(input) {
     const hostInstanceId = randomUUID();
     let hostSequence = 0;
     let payload = await redeem(input.home, input.runtimeGenerationId, input.ticket);
+    if (payload.environment.YUI_SESSION_SCOPE === "global"
+        && payload.environment.YUI_ADAPTER_ID === "codex"
+        && payload.providerControl === undefined) {
+        return runCodexInteractiveHost(input.home, payload);
+    }
     let session;
     let sessionPayload;
     let activeTurnPayload;
@@ -882,6 +888,7 @@ export async function waitForAgentHostLaunchAck(input) {
             const code = error.code;
             if (code !== "ENOENT" && code !== "ECONNREFUSED")
                 throw error;
+            await input.assertHostRunning?.();
         }
         await new Promise((resolvePromise) => setTimeout(resolvePromise, 50));
     }