@zq-silk/yui 0.14.2 → 0.15.1

package/dist/storage/upgrade/upgradeOrchestrator.js

@@ -1,5 +1,6 @@
-import { existsSync } from "node:fs";
-import { join } from "node:path";
+import { basename, dirname, join } from "node:path";
+import { copyFileSync, existsSync, mkdirSync, rmSync } from "node:fs";
+import Database from "better-sqlite3";
 import { RUNTIME_OBSERVATION_TASK_EVENT, createRuntimeObservation } from "../../runtime/runtimeObservation.js";
 import { RUNTIME_PROCESS_EXIT_TASK_EVENT, validateRuntimeProcessExitObservation } from "../../runtime/processExitObservation.js";
 import { validateAgentProfile } from "../../profile/agentProfile.js";
@@ -8,56 +9,168 @@ import { validateReviewRound } from "../../review/reviewRound.js";
 import { validateTurn } from "../../turn/turn.js";
 import { validateWorkItem } from "../../workItem/workItem.js";
 import { SqliteTaskStore } from "../sqliteStore.js";
-import { inspectStorageSchema } from "../storageSchema.js";
-const CURRENT_DATABASE_FILENAME = "yui.db";
+import { migrateSqliteSchema, storageMigrationPlan } from "../sqliteSchema.js";
+import { CURRENT_DATABASE_FILENAME, inspectStorageSchema } from "../storageSchema.js";
+import { CURRENT_STORAGE_VERSION, MIN_SUPPORTED_STORAGE_VERSION } from "../storageVersions.js";
 /**
- * Validate the one supported storage contract.
+ * Upgrade one valid Home through the complete linear migration chain.
  *
- * Aggregate 31 deliberately has no historical migration path. `upgrade`
- * remains as a read-only compatibility/preflight surface for current Homes;
- * every non-current contract is rejected without touching the Home.
+ * Supported earlier versions are readable only here. Ordinary stores still
+ * admit exactly {@link CURRENT_STORAGE_VERSION}; no old-shape normalizer or
+ * dual read path enters runtime code. Execute mode is an offline primitive:
+ * its caller must own the maintenance fence and keep the Controller quiesced
+ * for the whole backup, migration, and validation interval.
  */
 export async function runStorageUpgrade(options) {
-    const schema = inspectStorageSchema(options.home);
-    if (schema.status === "uninitialized") {
-        return blocked({ ...currentClassification(options.latest), uninitialized: true }, "uninitialized", "Yui storage is not initialized for this Home.", "Run `yui setup` with a new Home.");
+    const state = inspectStorageSchema(options.home);
+    if (state.status === "uninitialized") {
+        return blocked({ ...corruptedClassification("Storage is not initialized."), uninitialized: true }, "uninitialized", "Yui storage is not initialized for this Home.", "Run `yui setup` with a new Home.");
     }
-    if (schema.status === "invalid") {
-        return blocked(corruptedClassification(options.latest, schema.detail), "corruption", `Storage schema is invalid: ${schema.detail}`, "Preserve this Home for diagnosis and restore it from a known-good backup.");
+    if (state.status === "invalid") {
+        return blocked(corruptedClassification(state.detail), "corruption", `Storage is invalid: ${state.detail}`, "Preserve this Home for diagnosis and restore it from a known-good backup.");
     }
-    if (!existsSync(join(options.home, CURRENT_DATABASE_FILENAME))) {
-        return blocked(corruptedClassification(options.latest, "The SQLite database is missing."), "corruption", "The SQLite Home is incomplete: yui.db is missing.", "Preserve this Home for diagnosis and restore it from a known-good backup.");
+    if (state.status === "unsupported") {
+        const classification = unsupportedClassification(state);
+        return blocked(classification, "unsupported", classification.classification.verdict === "NEEDS_NEW_VERSION"
+            ? classification.classification.blocker.message
+            : "Storage is unsupported.", classification.classification.verdict === "NEEDS_NEW_VERSION"
+            ? classification.classification.blocker.action
+            : "Use a compatible Yui release.");
     }
-    if (schema.status === "unsupported") {
-        const classification = unsupportedClassification(schema, options.latest);
-        return blocked(classification, "unsupported", "This Home does not exactly match the current storage contract; this release provides no migration path.", schema.direction === "newer"
-            ? "Use a newer Yui release that supports this exact Home."
-            : "Open it with its matching Yui version, or initialize a new Home.");
+    if (state.status === "current") {
+        try {
+            validateCurrentStore(options.home);
+        }
+        catch (error) {
+            return blocked(corruptedClassification(messageOf(error)), "corruption", `Current storage validation failed: ${messageOf(error)}`, "Preserve this Home for diagnosis and restore it from a known-good backup.");
+        }
+        const classification = currentClassification();
+        if (options.mode === "update-preflight") {
+            return {
+                outcome: "update-preflight",
+                status: "already-current",
+                stepCount: 0,
+                steps: [],
+                classification
+            };
+        }
+        return {
+            outcome: "already-current",
+            classification,
+            report: {
+                outcome: "already-current",
+                mode: options.mode,
+                sourceVersion: CURRENT_STORAGE_VERSION,
+                targetVersion: CURRENT_STORAGE_VERSION,
+                steps: []
+            }
+        };
+    }
+    const plan = storageMigrationPlan(state.currentVersion);
+    if (plan === null) {
+        return blocked(corruptedClassification(`No complete migration path exists from ${state.currentVersion} `
+            + `to ${CURRENT_STORAGE_VERSION}.`), "corruption", "The storage migration registry is incomplete.", "Install a Yui release that carries the complete migration chain.");
+    }
+    const classification = migratableClassification(state.currentVersion);
+    if (options.mode === "update-preflight") {
+        return {
+            outcome: "update-preflight",
+            status: "migration-ready",
+            stepCount: plan.length,
+            steps: plan,
+            classification
+        };
     }
+    if (options.mode === "dry-run") {
+        return {
+            outcome: "upgrade-plan",
+            classification,
+            report: {
+                outcome: "upgrade-plan",
+                mode: "dry-run",
+                sourceVersion: state.currentVersion,
+                targetVersion: CURRENT_STORAGE_VERSION,
+                steps: plan
+            }
+        };
+    }
+    let backupPath;
     try {
+        backupPath = await createDatabaseBackup(options.home, state.currentVersion, options.now ?? new Date());
+    }
+    catch (error) {
+        return {
+            outcome: "failed",
+            stage: "backup",
+            message: `Storage backup failed: ${messageOf(error)}`,
+            action: "Storage was not modified. Resolve the backup path, permissions, or free-space problem "
+                + "and rerun `yui upgrade`.",
+            classification,
+            sceneUnchanged: true
+        };
+    }
+    let migrationCommitted = false;
+    try {
+        const database = new Database(join(options.home, CURRENT_DATABASE_FILENAME));
+        try {
+            database.pragma("journal_mode = WAL");
+            database.pragma("synchronous = FULL");
+            database.pragma("foreign_keys = ON");
+            database.pragma("busy_timeout = 5000");
+            migrateSqliteSchema(database, { mode: "apply" });
+            migrationCommitted = true;
+        }
+        finally {
+            database.close();
+        }
         validateCurrentStore(options.home);
+        rmSync(join(options.home, "schema.json"), { force: true });
     }
     catch (error) {
-        return blocked(corruptedClassification(options.latest, messageOf(error)), "corruption", `Current storage validation failed: ${messageOf(error)}`, "Preserve this Home for diagnosis and restore it from a known-good backup.");
+        const restoration = migrationCommitted
+            ? tryRestoreDatabaseBackup(options.home, backupPath)
+            : { restored: true };
+        return {
+            outcome: "failed",
+            stage: "migration",
+            message: `Storage migration failed: ${messageOf(error)}`,
+            action: restoration.restored
+                ? "The original database was restored from the timestamped backup. "
+                    + "Resolve the reported problem and rerun `yui upgrade`."
+                : "Automatic restore also failed. Keep the Home quiesced and restore "
+                    + `${backupPath} manually before retrying. Restore error: ${restoration.error}`,
+            backupPath,
+            classification,
+            sceneUnchanged: restoration.restored
+        };
     }
-    const classification = currentClassification(options.latest);
-    if (options.mode === "update-preflight") {
+    const finalState = inspectStorageSchema(options.home);
+    if (finalState.status !== "current") {
+        const restoration = tryRestoreDatabaseBackup(options.home, backupPath);
         return {
-            outcome: "update-preflight",
-            status: "already-current",
-            stepCount: 0,
-            steps: [],
-            classification
+            outcome: "failed",
+            stage: "migration",
+            message: `Storage migration did not reach version ${CURRENT_STORAGE_VERSION}.`,
+            action: restoration.restored
+                ? "The original database was restored from the timestamped backup. "
+                    + "Inspect the migration registry before retrying."
+                : "Automatic restore also failed. Keep the Home quiesced and restore "
+                    + `${backupPath} manually before retrying. Restore error: ${restoration.error}`,
+            backupPath,
+            classification,
+            sceneUnchanged: restoration.restored
         };
     }
     return {
-        outcome: "already-current",
-        classification,
+        outcome: "upgraded",
+        classification: currentClassification(),
         report: {
-            outcome: "already-current",
-            mode: options.mode,
-            source: options.latest,
-            target: options.latest
+            outcome: "upgraded",
+            mode: "execute",
+            sourceVersion: state.currentVersion,
+            targetVersion: CURRENT_STORAGE_VERSION,
+            steps: plan,
+            backupPath
         }
     };
 }
@@ -96,59 +209,108 @@ function validateCurrentStore(home) {
                 }
             }
         }
+        const quickCheck = store.databaseHandle().pragma("quick_check", { simple: true });
+        if (quickCheck !== "ok") {
+            throw new Error(`SQLite quick_check failed: ${String(quickCheck)}.`);
+        }
     }
     finally {
         store.close();
     }
 }
-function currentClassification(latest) {
+async function createDatabaseBackup(home, sourceVersion, now) {
+    const source = join(home, CURRENT_DATABASE_FILENAME);
+    if (!existsSync(source))
+        throw new Error("The authoritative yui.db is missing.");
+    const backupDirectory = join(dirname(home), `${basename(home)}-backups`);
+    mkdirSync(backupDirectory, { recursive: true, mode: 0o700 });
+    const timestamp = now.toISOString().replaceAll(":", "-");
+    const backupPath = join(backupDirectory, `pre-storage-v${sourceVersion}-${timestamp}.db`);
+    const database = new Database(source, { readonly: true, fileMustExist: true });
+    try {
+        await database.backup(backupPath);
+    }
+    finally {
+        database.close();
+    }
+    return backupPath;
+}
+function restoreDatabaseBackup(home, backupPath) {
+    const databasePath = join(home, CURRENT_DATABASE_FILENAME);
+    rmSync(`${databasePath}-wal`, { force: true });
+    rmSync(`${databasePath}-shm`, { force: true });
+    copyFileSync(backupPath, databasePath);
+}
+function tryRestoreDatabaseBackup(home, backupPath) {
+    try {
+        restoreDatabaseBackup(home, backupPath);
+        return { restored: true };
+    }
+    catch (error) {
+        return { restored: false, error: messageOf(error) };
+    }
+}
+function currentClassification() {
     return {
         classification: { verdict: "USABLE", status: "current" },
-        layoutVersion: latest.layout,
-        aggregateVersion: latest.aggregate,
-        latestLayoutVersion: latest.layout,
-        latestAggregateVersion: latest.aggregate
+        storageVersion: CURRENT_STORAGE_VERSION,
+        currentStorageVersion: CURRENT_STORAGE_VERSION,
+        minimumSupportedStorageVersion: MIN_SUPPORTED_STORAGE_VERSION
     };
 }
-function unsupportedClassification(schema, latest) {
-    const axis = schema.incompatibleComponent;
-    const found = schema.currentVersion;
-    const supported = schema.latestVersion;
-    const future = schema.direction === "newer";
+function migratableClassification(storageVersion) {
+    return {
+        classification: { verdict: "MIGRATABLE", status: "migration-ready" },
+        storageVersion,
+        currentStorageVersion: CURRENT_STORAGE_VERSION,
+        minimumSupportedStorageVersion: MIN_SUPPORTED_STORAGE_VERSION
+    };
+}
+function unsupportedClassification(state) {
+    const future = state.direction === "newer";
+    const message = future
+        ? `Storage version ${state.currentVersion} is newer than this CLI supports `
+            + `(${CURRENT_STORAGE_VERSION}).`
+        : `Storage version ${state.currentVersion} is older than the minimum supported `
+            + `migration version ${MIN_SUPPORTED_STORAGE_VERSION}.`;
     const action = future
-        ? "Use a newer Yui release that supports this exact Home."
-        : "Open it with its matching Yui version, or initialize a new Home.";
+        ? "Use a newer Yui release."
+        : "Preserve this Home for use with its matching historical Yui release, "
+            + "or initialize a new Home with Yui 0.15.0 or later.";
     return {
         classification: {
             verdict: "NEEDS_NEW_VERSION",
             status: "unsupported",
             blocker: {
-                reason: future ? "future-version" : "missing-step",
-                axis,
-                ...(schema.recordFamily === undefined ? {} : { recordKind: schema.recordFamily }),
-                ...(future ? { found, supported } : { from: found, to: supported }),
-                message: future
-                    ? "The Home is newer than this Yui release."
-                    : "This release provides no migration path for the older Home.",
+                reason: future ? "future-version" : "below-minimum",
+                found: state.currentVersion,
+                current: CURRENT_STORAGE_VERSION,
+                minimum: MIN_SUPPORTED_STORAGE_VERSION,
+                message,
                 action
             }
         },
-        layoutVersion: schema.currentLayoutVersion,
-        aggregateVersion: schema.currentAggregateSchemaVersion,
-        latestLayoutVersion: latest.layout,
-        latestAggregateVersion: latest.aggregate,
-        incompatibleComponent: axis
+        storageVersion: state.currentVersion,
+        currentStorageVersion: CURRENT_STORAGE_VERSION,
+        minimumSupportedStorageVersion: MIN_SUPPORTED_STORAGE_VERSION
     };
 }
-function corruptedClassification(latest, detail) {
+function corruptedClassification(detail) {
     return {
         classification: { verdict: "CORRUPTED", status: "unsupported", detail },
-        latestLayoutVersion: latest.layout,
-        latestAggregateVersion: latest.aggregate
+        currentStorageVersion: CURRENT_STORAGE_VERSION,
+        minimumSupportedStorageVersion: MIN_SUPPORTED_STORAGE_VERSION
     };
 }
 function blocked(classification, stage, message, action) {
-    return { outcome: "blocked", stage, message, action, classification, sceneUnchanged: true };
+    return {
+        outcome: "blocked",
+        stage,
+        message,
+        action,
+        classification,
+        sceneUnchanged: true
+    };
 }
 function messageOf(error) {
     return error instanceof Error ? error.message : String(error);

package/dist/tmux/tmuxManager.js

@@ -79,10 +79,23 @@ export class TmuxManager {
     }
     ensureRoleWindow(taskId, role, launch) {
         if (this.windowNames(taskId).includes(role.name)) {
+            const pane = this.inspectPane(taskId, role.name);
+            if (pane.dead && launch === undefined) {
+                throw runtimeError(`Role ${role.name} has an exited-retained pane; a launch plan is required to restart it.`);
+            }
             this.recordRoleTarget(taskId, role.name);
             this.configureServerHistory();
+            if (pane.dead) {
+                // Without -k tmux refuses to replace a live process, even if the pane
+                // changed after inspection. Reads alone never discard the exit scene.
+                this.run([
+                    "respawn-window", "-t", this.exactTarget(taskId, role.name),
+                    "-c", safeValue(role.cwd ?? role.workspace, "Role cwd"),
+                    "--", ...launchCommand(launch)
+                ]);
+            }
             this.configureRoleWindowSizing(taskId, role.name);
-            return false;
+            return pane.dead;
         }
         if (launch === undefined) {
             throw runtimeError(`Agent launch plan is required to create Role window: ${role.name}.`);
@@ -127,10 +140,21 @@ export class TmuxManager {
     async ensureRoleWindowAsync(taskId, role, launch) {
         const snapshot = await this.sessionWindowNamesAsync(taskId);
         if (snapshot.names.includes(role.name)) {
+            const pane = await this.inspectPaneAsync(taskId, role.name);
+            if (pane.dead && launch === undefined) {
+                throw runtimeError(`Role ${role.name} has an exited-retained pane; a launch plan is required to restart it.`);
+            }
             this.recordRoleTarget(taskId, role.name);
             await this.configureServerHistoryAsync();
+            if (pane.dead) {
+                await this.runAsync([
+                    "respawn-window", "-t", this.exactTarget(taskId, role.name),
+                    "-c", safeValue(role.cwd ?? role.workspace, "Role cwd"),
+                    "--", ...launchCommand(launch)
+                ]);
+            }
             await this.configureRoleWindowSizingAsync(taskId, role.name);
-            return false;
+            return pane.dead;
         }
         if (launch === undefined) {
             throw runtimeError(`Agent launch plan is required to create Role window: ${role.name}.`);
@@ -364,7 +388,7 @@ export class TmuxManager {
     inspectPane(taskId, roleName) {
         const target = this.target(taskId, roleName);
         const output = this.run([
-            "display-message", "-p", "-t", target,
+            "display-message", "-p", "-t", this.exactTarget(taskId, roleName),
             [
                 "#{pane_dead}",
                 "#{pane_pid}",
@@ -379,6 +403,9 @@ export class TmuxManager {
             throw runtimeError(`Tmux returned an invalid pane state for ${roleName}.`);
         }
         const dead = output.slice(0, separator);
+        if (dead !== "0" && dead !== "1") {
+            throw runtimeError(`Tmux returned an invalid pane state for ${roleName}.`);
+        }
         const pidText = output.slice(separator + 1, secondSeparator);
         const currentCommand = output.slice(secondSeparator + 1, lastSeparator);
         const exitStatusText = output.slice(lastSeparator + 1);
@@ -405,7 +432,7 @@ export class TmuxManager {
             : deliveryReceiptOption(receiptId);
         const receiptFormat = receiptOption === undefined ? "" : `#{${receiptOption}}`;
         const output = await this.runAsync([
-            "display-message", "-p", "-t", target,
+            "display-message", "-p", "-t", this.exactTarget(taskId, roleName),
             [
                 PANE_STATE_MARKER,
                 "#{pane_dead}",
@@ -798,22 +825,16 @@ export class TmuxManager {
         }
         this.enterRole(taskId, role, launch);
     }
-    detectRoleStatus(taskId, roleName, fallback = "exited") {
-        try {
-            return this.probeRoleStatus(taskId, roleName);
-        }
-        catch {
-            return fallback;
-        }
-    }
     probeRoleStatus(taskId, roleName) {
-        if (!this.hasSession(taskId))
+        if (!this.windowNames(taskId).includes(roleName))
             return "exited";
-        return this.windowNames(taskId).includes(roleName) ? "running" : "exited";
+        return this.inspectPane(taskId, roleName).dead ? "exited" : "running";
     }
     async probeRoleStatusAsync(taskId, roleName) {
         const snapshot = await this.sessionWindowNamesAsync(taskId);
-        return snapshot.names.includes(roleName) ? "running" : "exited";
+        if (!snapshot.names.includes(roleName))
+            return "exited";
+        return (await this.inspectPaneAsync(taskId, roleName)).dead ? "exited" : "running";
     }
     /** Exact pane process state for one Role, used by owner-identity recording. */
     inspectRolePane(taskId, roleName) {
@@ -901,10 +922,6 @@ export class TmuxManager {
         catch (error) {
             if (isExplicitlyAbsentTmuxSession(error))
                 return false;
-            // Older/fake executors do not expose stderr. A failed has-session is the
-            // tmux absence contract; other operations remain strict.
-            if (!(error instanceof CommandExecutionError))
-                return false;
             throw error;
         }
     }
@@ -916,8 +933,6 @@ export class TmuxManager {
         catch (error) {
             if (isExplicitlyAbsentTmuxSession(error))
                 return false;
-            if (!(error instanceof CommandExecutionError))
-                return false;
             throw error;
         }
     }
@@ -930,7 +945,7 @@ export class TmuxManager {
             ]).split("\n").map((name) => name.trim()).filter(Boolean);
         }
         catch (error) {
-            if (isUnavailableTmuxStatus(error))
+            if (isExplicitlyAbsentTmuxSession(error))
                 return [];
             throw error;
         }
@@ -943,7 +958,7 @@ export class TmuxManager {
             return { exists: true, names };
         }
         catch (error) {
-            if (isUnavailableTmuxStatus(error))
+            if (isExplicitlyAbsentTmuxSession(error))
                 return { exists: false, names: [] };
             throw error;
         }
@@ -990,6 +1005,11 @@ export class TmuxManager {
     target(taskId, roleName) {
         return yuiTmuxTarget(this.#yuiHome, taskId, roleName);
     }
+    exactTarget(taskId, roleName) {
+        // tmux otherwise accepts prefix/glob matches after the selected Role
+        // disappears. Keep identity inspection and dead-pane replacement exact.
+        return `=${this.sessionName(taskId)}:=${safeValue(roleName, "Role name")}`;
+    }
     recordRoleTarget(taskId, roleName) {
         this.#onRoleTargetRecorded?.(this.target(taskId, roleName));
     }
@@ -1225,11 +1245,6 @@ function isExplicitlyAbsentTmuxSession(error) {
     return /can't find (?:session|window|pane)|no server running|no current target|session not found|error connecting to .+ \(No such file or directory\)/i
         .test(error.stderr);
 }
-function isUnavailableTmuxStatus(error) {
-    return isExplicitlyAbsentTmuxSession(error)
-        || (error instanceof CommandExecutionError
-            && /server exited unexpectedly/i.test(error.stderr));
-}
 function tmuxWord(value) {
     return JSON.stringify(value);
 }

package/dist/version.js

@@ -1,13 +1,13 @@
 import { readFileSync } from "node:fs";
 import { FILE_TASK_CONTROLLER_PROTOCOL_VERSION } from "./core/protocol.js";
-import { CURRENT_AGGREGATE_SCHEMA_VERSION, CURRENT_STORAGE_LAYOUT_VERSION } from "./storage/storageSchema.js";
+import { CURRENT_STORAGE_VERSION, MIN_SUPPORTED_STORAGE_VERSION } from "./storage/storageVersions.js";
 export const YUI_VERSION = readPackageVersion();
 export function yuiVersionIdentity() {
     return {
         version: YUI_VERSION,
         controllerProtocolVersion: FILE_TASK_CONTROLLER_PROTOCOL_VERSION,
-        storageLayoutVersion: CURRENT_STORAGE_LAYOUT_VERSION,
-        aggregateSchemaVersion: CURRENT_AGGREGATE_SCHEMA_VERSION
+        storageVersion: CURRENT_STORAGE_VERSION,
+        minimumStorageVersion: MIN_SUPPORTED_STORAGE_VERSION
     };
 }
 function readPackageVersion() {

package/docs/task-local-identity.md

@@ -51,12 +51,12 @@ There is no compatibility lookup, cross-Task guess, or bare-ID fallback.
 
 ## Current-schema boundary
 
-Runtime opens only aggregate v31 / Task v7. It does not convert,
-dual-read, or infer records from an older schema. If an existing `YUI_HOME`
-does not match the current schema, keep it untouched for external archival
-and initialize a fresh home for this runtime.
-
-This hard cut keeps Task-local references, Role desired configuration, and
-immutable Turn/RoleSession effective snapshots under one unambiguous
-contract. There is no compatibility lookup, conversion command, or
-intermediate storage format.
+Runtime opens only the current Home storage version and current record shapes.
+It does not dual-read or infer historical records during ordinary work.
+Historical decoding and rewriting are confined to the explicit `yui upgrade`
+boundary and the migration phase of `yui update`; every valid Home at or above
+the CLI's minimum supported storage version can advance directly to current.
+
+This boundary keeps Task-local references, Role desired configuration, and
+immutable Turn/RoleSession effective snapshots under one unambiguous runtime
+contract while the append-only migration chain preserves supported history.