@zq-silk/yui 0.14.2 → 0.15.1

package/dist/runtime/codexInteractiveHost.js

@@ -0,0 +1,191 @@
+import { spawn } from "node:child_process";
+import { randomBytes } from "node:crypto";
+import { once } from "node:events";
+import WebSocket, { WebSocketServer } from "ws";
+import { AGENT_HOST_CONTROL_PROTOCOL, openAgentHostControl } from "./agentHost.js";
+import { openCodexInteractiveConnection } from "./structuredProviderHost.js";
+/**
+ * Keep the native TUI and its transparent App Server attachment in one pane.
+ * The existing Host acknowledgement carries the ID from that TUI's exact
+ * thread/start or thread/resume response, before any user/model Turn.
+ *
+ * Codex 0.150.1 cannot resume a pre-created empty Thread: no rollout exists
+ * until its first message. Observing the TUI's own startup avoids creating a
+ * second Thread or manufacturing a bootstrap message to materialize history.
+ */
+export async function runCodexInteractiveHost(home, payload) {
+    const environment = payload.environment;
+    if (environment.YUI_SESSION_SCOPE !== "global" || environment.YUI_ADAPTER_ID !== "codex"
+        || payload.providerControl !== undefined) {
+        throw new Error("Interactive Codex Host requires a global native TUI launch.");
+    }
+    const remoteIndex = payload.args.indexOf("--remote");
+    if (remoteIndex < 0 || payload.args[remoteIndex + 1] !== "unix://") {
+        throw new Error("Global Codex must target the default shared daemon.");
+    }
+    const baseArgs = JSON.parse(environment.YUI_AGENT_BASE_ARGS ?? "[]");
+    if (!Array.isArray(baseArgs) || baseArgs.some((arg) => typeof arg !== "string")) {
+        throw new Error("Codex proxy base arguments are invalid.");
+    }
+    const expectedId = environment.YUI_NATIVE_SESSION_ID;
+    let snapshot = {
+        schemaVersion: 2, state: "starting", adapterId: "codex",
+        runtimeGenerationId: payload.runtimeGenerationId, updatedAt: new Date().toISOString()
+    };
+    const control = await openAgentHostControl(home, payload, () => snapshot, async (request) => {
+        if (request.type !== "status") {
+            throw new Error("Global Codex uses its native TUI; stop it before switching Sessions.");
+        }
+        return { protocol: AGENT_HOST_CONTROL_PROTOCOL, outcome: "status", snapshot };
+    });
+    let child;
+    let client;
+    let closing = false;
+    let startupRequestId;
+    let connection;
+    let relay;
+    const signals = ["SIGTERM", "SIGHUP", "SIGINT"];
+    const stop = () => { child?.kill("SIGTERM"); };
+    const fail = (error) => {
+        if (closing || snapshot.state === "failed")
+            return;
+        snapshot = {
+            ...snapshot, state: "failed",
+            detail: error instanceof Error ? error.message : String(error),
+            updatedAt: new Date().toISOString()
+        };
+        process.stderr.write(`Yui Codex attachment failed: ${snapshot.detail}\n`);
+        client?.terminate();
+        stop();
+    };
+    try {
+        // This proxy is a disposable client, not the daemon. No Yui initialization
+        // or Thread request is injected; all requests below belong to the TUI.
+        connection = await openCodexInteractiveConnection({
+            command: payload.command, args: [...baseArgs, "app-server", "proxy"],
+            environment, cwd: payload.cwd
+        });
+        connection.onClose(fail);
+        const token = randomBytes(32).toString("hex");
+        relay = new WebSocketServer({
+            host: "127.0.0.1", port: 0,
+            maxPayload: 16 * 1024 * 1024, perMessageDeflate: false,
+            verifyClient: (info) => info.req.headers.authorization === `Bearer ${token}`
+        });
+        relay.on("error", fail);
+        relay.on("connection", (socket) => {
+            if (client !== undefined || closing) {
+                socket.close(1008, "This attachment already has its native TUI.");
+                return;
+            }
+            client = socket;
+            socket.on("error", fail);
+            socket.on("close", () => {
+                if (!closing) {
+                    closing = true;
+                    connection?.close();
+                    stop();
+                }
+            });
+            socket.on("message", (data, binary) => {
+                try {
+                    if (binary)
+                        throw new Error("Codex TUI sent a binary App Server request.");
+                    const message = jsonObject(JSON.parse(data.toString()));
+                    if (snapshot.nativeSessionId === undefined
+                        && (message.method === "thread/start" || message.method === "thread/resume")) {
+                        if (startupRequestId !== undefined)
+                            throw new Error("Codex sent overlapping startup requests.");
+                        if (typeof message.id !== "string" && typeof message.id !== "number") {
+                            throw new Error("Codex startup request has no correlation id.");
+                        }
+                        const params = jsonObject(message.params);
+                        if (expectedId === undefined ? message.method !== "thread/start"
+                            : message.method !== "thread/resume" || params.threadId !== expectedId) {
+                            throw new Error("Codex TUI startup does not match the reserved Session.");
+                        }
+                        startupRequestId = message.id;
+                    }
+                    void connection.send(message).catch(fail);
+                }
+                catch (error) {
+                    fail(error);
+                }
+            });
+        });
+        connection.onMessage((message) => {
+            try {
+                let nativeSessionId;
+                if (startupRequestId !== undefined && message.id === startupRequestId
+                    && message.method === undefined) {
+                    if (message.error !== undefined) {
+                        throw new Error(`Codex startup failed: ${JSON.stringify(message.error)}`);
+                    }
+                    const id = jsonObject(jsonObject(message.result).thread).id;
+                    if (typeof id !== "string" || id.length === 0 || id.trim() !== id || id.includes("\0")
+                        || (expectedId !== undefined && id !== expectedId)) {
+                        throw new Error("Codex startup returned an invalid or mismatched Thread identity.");
+                    }
+                    nativeSessionId = id;
+                }
+                if (client?.readyState !== WebSocket.OPEN)
+                    throw new Error("Codex TUI attachment is closed.");
+                client.send(JSON.stringify(message), (error) => {
+                    if (error) {
+                        fail(error);
+                        return;
+                    }
+                    if (nativeSessionId === undefined || snapshot.state === "failed")
+                        return;
+                    startupRequestId = undefined;
+                    snapshot = {
+                        ...snapshot, state: "ready", nativeSessionId, conversationId: nativeSessionId,
+                        updatedAt: new Date().toISOString()
+                    };
+                });
+            }
+            catch (error) {
+                fail(error);
+            }
+        });
+        await once(relay, "listening");
+        if (snapshot.state === "failed")
+            throw new Error(snapshot.detail);
+        const address = relay.address();
+        if (typeof address !== "object" || address === null)
+            throw new Error("Codex TUI relay did not bind.");
+        const args = [...payload.args];
+        args[remoteIndex + 1] = `ws://127.0.0.1:${address.port}`;
+        args.splice(remoteIndex + 2, 0, "--remote-auth-token-env", "YUI_CODEX_REMOTE_AUTH_TOKEN");
+        child = spawn(payload.command, args, {
+            cwd: payload.cwd,
+            env: { ...environment, YUI_CODEX_REMOTE_AUTH_TOKEN: token },
+            stdio: "inherit"
+        });
+        for (const signal of signals)
+            process.on(signal, stop);
+        const [code] = await once(child, "exit");
+        return typeof code === "number" ? code : 1;
+    }
+    catch (error) {
+        fail(error);
+        throw error;
+    }
+    finally {
+        closing = true;
+        for (const signal of signals)
+            process.removeListener(signal, stop);
+        stop();
+        client?.terminate();
+        connection?.close();
+        if (relay !== undefined)
+            await new Promise((done) => relay.close(() => done()));
+        await control.close();
+    }
+}
+function jsonObject(value) {
+    if (value === null || typeof value !== "object" || Array.isArray(value)) {
+        throw new Error("Invalid Codex App Server object.");
+    }
+    return value;
+}

package/dist/runtime/exactControlPlane.js

@@ -73,7 +73,7 @@ export function extractExactControlArgument(args) {
 }
 /**
  * One read-only gate shared by every managed Task control command. It verifies
- * the frozen executable/CLI/Home/digest, protocol and scalar-storage identity,
+ * the frozen executable/CLI/Home/digest, protocol and storage identity,
  * on-disk schema, and any live Controller before command routing may construct
  * a writable store. Package version alone may advance at the same managed path
  * so an existing Session can cross an explicitly compatible in-place update.
@@ -92,15 +92,10 @@ export async function assertExactControlPlanePreflight(input, options = {}) {
     if (storage.status !== "current") {
         throw new Error(`Exact control-plane storage is not current: ${storage.status}.`);
     }
-    if (storage.currentLayoutVersion !== descriptor.identity.storageLayoutVersion) {
-        throw new Error("Exact control-plane storage layout does not match its frozen descriptor "
-            + `(expected ${descriptor.identity.storageLayoutVersion}, found `
-            + `${storage.currentLayoutVersion ?? "unknown"}).`);
-    }
-    if (storage.currentAggregateSchemaVersion !== descriptor.identity.aggregateSchemaVersion) {
-        throw new Error("Exact control-plane aggregate schema does not match its frozen descriptor "
-            + `(expected ${descriptor.identity.aggregateSchemaVersion}, found `
-            + `${storage.currentAggregateSchemaVersion ?? "unknown"}).`);
+    if (storage.currentVersion !== descriptor.identity.storageVersion) {
+        throw new Error("Exact control-plane storage version does not match its frozen descriptor "
+            + `(expected ${descriptor.identity.storageVersion}, found `
+            + `${storage.currentVersion ?? "unknown"}).`);
     }
     // A frozen descriptor authenticates the command that created it; it no
     // longer pins the Home's deployment pointer for the lifetime of a Session.
@@ -133,15 +128,10 @@ export async function assertCompatibleControlPlanePreflight(input, options = {})
     if (storage.status !== "current") {
         throw new Error(`Managed control-plane storage is not current: ${storage.status}.`);
     }
-    if (storage.currentLayoutVersion !== identity.storageLayoutVersion) {
-        throw new Error("Managed control-plane storage layout is incompatible "
-            + `(expected ${identity.storageLayoutVersion}, found `
-            + `${storage.currentLayoutVersion ?? "unknown"}).`);
-    }
-    if (storage.currentAggregateSchemaVersion !== identity.aggregateSchemaVersion) {
-        throw new Error("Managed control-plane aggregate schema is incompatible "
-            + `(expected ${identity.aggregateSchemaVersion}, found `
-            + `${storage.currentAggregateSchemaVersion ?? "unknown"}).`);
+    if (storage.currentVersion !== identity.storageVersion) {
+        throw new Error("Managed control-plane storage version is incompatible "
+            + `(expected ${identity.storageVersion}, found `
+            + `${storage.currentVersion ?? "unknown"}).`);
     }
     if (options.checkController !== false) {
         const call = options.callController ?? defaultCallController;
@@ -162,29 +152,31 @@ export function assertControllerStatusIdentity(status, expected = yuiVersionIden
     }
     assertControllerField(status.protocolVersion, expected.controllerProtocolVersion, "protocol");
     assertControllerField(status.version, expected.version, "version");
-    assertControllerField(status.storageLayoutVersion, expected.storageLayoutVersion, "storage layout");
-    assertControllerField(status.aggregateSchemaVersion, expected.aggregateSchemaVersion, "aggregate schema");
+    assertControllerField(status.storageVersion, expected.storageVersion, "storage version");
+    assertControllerField(status.minimumStorageVersion, expected.minimumStorageVersion, "minimum storage migration version");
 }
 function validateVersionIdentity(value) {
     if (!isRecord(value))
         throw new Error("Yui version identity is invalid.");
     const version = requireText(value.version, "Yui version");
     const controllerProtocolVersion = requireVersion(value.controllerProtocolVersion, "Controller protocol version");
-    const storageLayoutVersion = requireVersion(value.storageLayoutVersion, "Storage layout version");
-    const aggregateSchemaVersion = requireVersion(value.aggregateSchemaVersion, "Aggregate schema version");
+    const storageVersion = requireVersion(value.storageVersion, "Storage version");
+    const minimumStorageVersion = requireVersion(value.minimumStorageVersion, "Minimum storage migration version");
+    if (minimumStorageVersion > storageVersion) {
+        throw new Error("Minimum storage migration version cannot exceed the current storage version.");
+    }
     return {
         version,
         controllerProtocolVersion,
-        storageLayoutVersion,
-        aggregateSchemaVersion
+        storageVersion,
+        minimumStorageVersion
     };
 }
 /** Managed continuity is a protocol/storage contract, not a package pin. */
 function assertContinuityIdentity(label, expected, actual) {
     for (const field of [
         "controllerProtocolVersion",
-        "storageLayoutVersion",
-        "aggregateSchemaVersion"
+        "storageVersion"
     ]) {
         if (expected[field] !== actual[field]) {
             throw new Error(`${label} ${field} does not match the frozen control plane `
@@ -200,8 +192,7 @@ function assertControllerContinuityIdentity(status, expected) {
         throw new Error("Controller version is invalid at the managed continuity gate.");
     }
     assertControllerField(status.protocolVersion, expected.controllerProtocolVersion, "protocol");
-    assertControllerField(status.storageLayoutVersion, expected.storageLayoutVersion, "storage layout");
-    assertControllerField(status.aggregateSchemaVersion, expected.aggregateSchemaVersion, "aggregate schema");
+    assertControllerField(status.storageVersion, expected.storageVersion, "storage version");
 }
 function assertControllerField(actual, expected, label) {
     if (actual !== expected) {

package/dist/runtime/structuredProviderHost.js

@@ -78,11 +78,32 @@ export async function startStructuredProviderSession(payload, input = {}) {
         throw error;
     }
 }
+/**
+ * Open an uninitialized, transparent connection for a native TUI. The TUI
+ * owns its requests; Yui observes only its exact startup response.
+ */
+export async function openCodexInteractiveConnection(launch) {
+    const child = spawn(launch.command, [...launch.args], {
+        cwd: launch.cwd,
+        env: { ...launch.environment },
+        stdio: ["pipe", "pipe", "pipe"],
+        detached: true
+    });
+    child.stderr.resume();
+    try {
+        return await CodexProxyWebSocketChannel.connect(child, () => { });
+    }
+    catch (error) {
+        terminateProcessGroup(child, "SIGTERM");
+        throw error;
+    }
+}
 class CodexProxyWebSocketChannel {
     child;
     mirror;
     #pending = new Map();
     #listeners = new Set();
+    #closeListeners = new Set();
     #nextId = 1;
     #closedError;
     #ready = false;
@@ -127,6 +148,17 @@ class CodexProxyWebSocketChannel {
         this.#listeners.add(listener);
         return () => this.#listeners.delete(listener);
     }
+    onClose(listener) {
+        if (this.#closedError !== undefined)
+            listener(this.#closedError);
+        else
+            this.#closeListeners.add(listener);
+        return () => this.#closeListeners.delete(listener);
+    }
+    close() {
+        this.#webSocket.terminate();
+        this.#close(new Error("Codex App Server proxy client closed."));
+    }
     async request(method, params) {
         await this.#readyPromise;
         if (this.#closedError !== undefined)
@@ -227,6 +259,9 @@ class CodexProxyWebSocketChannel {
             pending.reject(error);
         }
         this.#pending.clear();
+        for (const listener of this.#closeListeners)
+            listener(error);
+        this.#closeListeners.clear();
         if (this.child.exitCode === null && this.child.signalCode === null) {
             terminateProcessGroup(this.child, "SIGTERM");
         }

package/dist/runtime/tmuxAdapters.js

@@ -210,6 +210,23 @@ export class TmuxSessionHost {
                 throw toRuntimeLaunchFailure(error, "validation", launchContext);
             }
         }
+        const interactiveCodex = request.owner.scope === "global" && request.adapterId === "codex";
+        let reuseInteractivePane = false;
+        if (interactiveCodex) {
+            let status;
+            try {
+                status = await probeRoleStatus(this.tmux, hostId, request.owner.roleName);
+            }
+            catch (error) {
+                throw new RuntimeHostContentionError("previous-process", `Global Role pane state is unknown; preserving it: ${error instanceof Error ? error.message : String(error)}`);
+            }
+            if (status === "running") {
+                if (request.mode === "new") {
+                    throw new RuntimeHostContentionError("previous-process", "Global Role already has a live pane; stop or record its exact Session first.");
+                }
+                reuseInteractivePane = true;
+            }
+        }
         const plannedNativeSessionId = planned.session?.nativeSessionId;
         if (request.mode === "resume"
             && plannedNativeSessionId !== undefined
@@ -232,23 +249,26 @@ export class TmuxSessionHost {
         });
         const yuiHome = planned.launch.env.YUI_HOME;
         const childLifecycle = planned.launch.childLifecycle;
-        // Interactive/global Roles remain native TUIs even when their Driver
-        // advertises a persistent child lifecycle. Provider control metadata is
-        // the discriminator for the structured Agent Host path. A managed Task
-        // Turn has no terminal-write fallback and must expose that contract.
-        if (yuiHome === undefined
-            || childLifecycle === undefined
-            || planned.launch.providerControl === undefined) {
+        // Global Codex retains the native TUI inside a thin Host that acknowledges
+        // its own App Server startup response. Existing live TUIs (including
+        // 0.15.0 Sessions) remain directly attachable without replacing them.
+        if (reuseInteractivePane
+            || (!interactiveCodex && (yuiHome === undefined
+                || childLifecycle === undefined
+                || planned.launch.providerControl === undefined))) {
             if (request.owner.scope === "task" && request.turnId !== undefined) {
                 throw new Error("Managed Task Turn is missing its structured Agent Host contract.");
             }
             let hostCreated;
             try {
-                hostCreated = await ensureRoleWindow(this.tmux, hostId, planned.role, planned.launch);
+                hostCreated = await ensureRoleWindow(this.tmux, hostId, planned.role, reuseInteractivePane ? undefined : planned.launch);
             }
             catch (error) {
                 throw toRuntimeLaunchFailure(error, "host-start", launchContext);
             }
+            if (reuseInteractivePane && hostCreated) {
+                throw new Error("Global Role pane changed during attachment.");
+            }
             let binding = createRuntimeBinding({
                 id: bindingId,
                 runtimeGenerationId: request.runtimeGenerationId,
@@ -282,6 +302,9 @@ export class TmuxSessionHost {
             }
             return binding;
         }
+        if (yuiHome === undefined || childLifecycle === undefined) {
+            throw new Error("Agent Host launch is missing its Home or child lifecycle.");
+        }
         const broker = launchBrokerForHome(yuiHome);
         const sessionManifest = planned.launch.env.YUI_SESSION_MANIFEST;
         const frozenControlPlane = planned.launch.env[YUI_CONTROL_PLANE_DESCRIPTOR];
@@ -341,17 +364,36 @@ export class TmuxSessionHost {
         try {
             hostCreated = await ensureRoleWindow(this.tmux, hostId, planned.role, hostLaunch);
             if (hostCreated && planned.launch.deferProviderStart !== true) {
+                const assertInteractivePane = async () => {
+                    const pane = await inspectRolePane(this.tmux, hostId, request.owner.roleName);
+                    if (pane === undefined)
+                        throw new Error("Global Codex startup has no observable pane state.");
+                    if (pane.dead) {
+                        await deadHostLaunchFailure(this.tmux, hostId, request.owner.roleName, pane, launchContext);
+                    }
+                };
                 providerSnapshot = await waitForAgentHostLaunchAck({
                     home: yuiHome,
                     scope: request.owner.scope,
                     ...(request.owner.scope === "task" ? { taskId: request.owner.taskId } : {}),
                     roleName: request.owner.roleName,
                     runtimeGenerationId: reservation.runtimeGenerationId,
-                    requireTurnAck: false
+                    requireTurnAck: false,
+                    ...(interactiveCodex ? { assertHostRunning: assertInteractivePane } : {})
                 });
+                if (interactiveCodex) {
+                    if (providerSnapshot.nativeSessionId === undefined) {
+                        throw new Error("Global Codex startup acknowledgement has no Thread identity.");
+                    }
+                    requireSafeIdentity(providerSnapshot.nativeSessionId, "Codex Thread identity");
+                    await assertInteractivePane();
+                }
                 providerDispatchObserved = true;
             }
             if (!hostCreated) {
+                if (interactiveCodex) {
+                    throw new RuntimeHostContentionError("previous-process", "Global Role pane appeared during launch; preserving its existing Session.");
+                }
                 const controlResult = await sendAgentHostLaunchControl({
                     home: yuiHome,
                     scope: request.owner.scope,

package/dist/scheduler/activeRoleTurnDelivery.js

@@ -1,5 +1,5 @@
 import { serializeTurnInputEnvelope } from "../context/turnInputContract.js";
-import { effectiveLaunchSnapshotsCompatible, effectiveLaunchSnapshotsCompatibleForTaskSession } from "../executor/effectiveLaunch.js";
+import { roleSessionMayContinue, sameEffectiveLaunch } from "../executor/effectiveLaunch.js";
 import { RuntimeLifecycleBusyError } from "../runtime/lifecycleReservation.js";
 import { managedProviderTurnId } from "../runtime/providerRuntimeIdentity.js";
 import { serializeAgentErrorRaw } from "../runtime/agentError.js";
@@ -231,8 +231,8 @@ function validateRoleSession(role, turn, existing, mode, session) {
         throw new Error(`Ready Role session identity changed: ${role.taskId}/${role.name}.`);
     }
     const compatible = mode === "resume"
-        ? effectiveLaunchSnapshotsCompatibleForTaskSession(session.effective, turn.effective)
-        : effectiveLaunchSnapshotsCompatible(session.effective, turn.effective);
+        ? roleSessionMayContinue(session.effective, turn.effective)
+        : sameEffectiveLaunch(session.effective, turn.effective);
     if (!compatible) {
         throw new Error(`Ready Role session effective snapshot changed: ${role.taskId}/${role.name}.`);
     }
@@ -249,7 +249,7 @@ function requireResumeSession(role, turn, session) {
     if (session === null || !hasText(session.nativeSessionId)) {
         throw new Error(`Role resume has no fixed native session: ${role.taskId}/${role.name}.`);
     }
-    if (!effectiveLaunchSnapshotsCompatibleForTaskSession(session.effective, turn.effective)) {
+    if (!roleSessionMayContinue(session.effective, turn.effective)) {
         throw new Error(`Role resume effective snapshot drifted: ${role.taskId}/${role.name}.`);
     }
     return session.nativeSessionId;

package/dist/scheduler/leaderWakeupProcessor.js

@@ -1,5 +1,5 @@
 import { createTurnInput } from "../context/turnInputContract.js";
-import { effectiveLaunchSnapshotsCompatible, effectiveLaunchSnapshotsCompatibleForTaskSession } from "../executor/effectiveLaunch.js";
+import { roleSessionMayContinue } from "../executor/effectiveLaunch.js";
 import { roleAgentSessionResumeMode } from "../executor/agentExecutor.js";
 import { createTurn } from "../turn/turn.js";
 import { isSchedulerTaskWorkspaceReady } from "./ports.js";
@@ -63,9 +63,8 @@ export async function processLeaderWakeups(store, delivery, now, selection) {
         try {
             const reopening = wakeup.reasons.includes("task-reopened");
             const existingSession = store.getRoleSession(task.id, role.name, reopening ? undefined : role.effective.agentId);
-            const compatible = existingSession !== null && (reopening
-                ? effectiveLaunchSnapshotsCompatible(existingSession.effective, role.effective)
-                : effectiveLaunchSnapshotsCompatibleForTaskSession(existingSession.effective, role.effective));
+            const compatible = existingSession !== null
+                && roleSessionMayContinue(existingSession.effective, role.effective);
             if (hasNativeSession(existingSession)
                 && existingSession.status === "active"
                 && !compatible

package/dist/storage/currentTaskStore.js

@@ -2,12 +2,11 @@ import { existsSync } from "node:fs";
 import { join } from "node:path";
 import { StorageRecordError } from "./taskStore.js";
 import { readSqliteHomeIdentity, SqliteTaskStore } from "./sqliteStore.js";
-import { ensureStorageSchema, inspectStorageSchema } from "./storageSchema.js";
-export const CURRENT_DATABASE_FILENAME = "yui.db";
+import { CURRENT_DATABASE_FILENAME, inspectStorageSchema } from "./storageSchema.js";
+export { CURRENT_DATABASE_FILENAME } from "./storageSchema.js";
 /** Initialize a new Home, or open an existing Home at the exact current contract. */
 export function initializeCurrentTaskStore(home) {
     if (inspectStorageSchema(home).status === "uninitialized") {
-        ensureStorageSchema(home);
         return new SqliteTaskStore(home);
     }
     return openCurrentTaskStore(home);
@@ -16,7 +15,10 @@ export function initializeCurrentTaskStore(home) {
 export function openCurrentTaskStore(home) {
     const schema = inspectStorageSchema(home);
     if (schema.status !== "current") {
-        throw new StorageRecordError("This Home does not use the current storage contract. Preserve it for read-only history and initialize a new Home.");
+        throw new StorageRecordError(schema.status === "upgradeable"
+            ? `This Home uses storage version ${schema.currentVersion}; run \`yui upgrade\` `
+                + `to reach ${schema.latestVersion}.`
+            : "This Home does not use a supported storage contract.");
     }
     if (!existsSync(join(home, CURRENT_DATABASE_FILENAME))) {
         throw new StorageRecordError("The current Home is incomplete: yui.db is missing. Preserve it for diagnosis and initialize a new Home.");