@zq-silk/yui 0.2.0 → 0.4.2

package/dist/setup/setupCommand.js

@@ -1,14 +1,22 @@
-import { existsSync, mkdirSync } from "node:fs";
-import { delimiter, isAbsolute, join, resolve } from "node:path";
+import { existsSync, mkdirSync, realpathSync } from "node:fs";
+import { delimiter, dirname, isAbsolute, join, relative, resolve } from "node:path";
 import { createInterface } from "node:readline/promises";
+import { isDeepStrictEqual } from "node:util";
 import { configuredAgentToDefinition, createConfiguredAgent } from "../agent/agent.js";
+import { selectAgentPermission, selectAgentModelAndEffort } from "../cli/agentConfigurationPicker.js";
 import { runCompletionWizard } from "../completion/completionWizard.js";
 import { usageError } from "../errors/cliError.js";
+import { defaultRoleAgentConfig, resolveAgentAdapter } from "../executor/agentAdapter.js";
+import { AgentConfigurationCatalogService } from "../executor/agentConfigurationCatalog.js";
 import { defaultTableWidth, renderTable } from "../output/table.js";
-import { createGlobalRole, createRoleAgentBinding } from "../role/role.js";
-import { SYSTEM_LEADER_ROLE, SYSTEM_OPERATOR_ROLE } from "../role/systemRoles.js";
-import { ensureYuiHome, FileTaskStore, resolveYuiHome } from "../storage/taskStore.js";
-import { ensureStorageSchema } from "../storage/storageSchema.js";
+import { resolveTimeZone } from "../output/timePresentation.js";
+import { createGlobalRole, createRoleAgentBinding, updateGlobalRole } from "../role/role.js";
+import { SYSTEM_LEADER_ROLE, SYSTEM_OPERATOR_ROLE, SYSTEM_WORKER_ROLE } from "../role/systemRoles.js";
+import { DEFAULT_REVIEWER_ROLE } from "../review/reviewConfig.js";
+import { builtinAgentProfileInputs, createAgentProfile } from "../profile/agentProfile.js";
+import { assertRoleRuntimeMutationAllowed } from "../commands/roleRuntimeGuard.js";
+import { ensureYuiHome, resolveYuiHome } from "../storage/taskStore.js";
+import { initializeCompatibleFileTaskStore } from "../storage/compatibleTaskStore.js";
 const BUILTIN_AGENTS = Object.freeze([
     Object.freeze({
         id: "codex",
@@ -36,15 +44,40 @@ export async function runSetupCommand(args, env, executor, io = {}) {
         const question = createSetupQuestion(readline, io);
         const home = resolveYuiHome(env);
         ensureYuiHome(home);
-        ensureStorageSchema(home);
-        const store = new FileTaskStore(home);
-        const result = await configureYui(store, home, env, question, io);
+        const store = initializeCompatibleFileTaskStore(home);
+        const catalogs = new AgentConfigurationCatalogService(home, { environment: env });
+        const result = await configureYui(store, home, env, question, setupSelectionIo(question, io), catalogs, io);
         const lines = [
             "Yui home initialized.",
             `Agents configured: ${result.agentIds.join(", ")}.`,
             `Default Agent: ${result.defaultAgentId}.`,
             `Operator Agent: ${result.operatorAgentId}.`,
-            `Operator workspace: ${result.workspace}.`
+            `Leader model: ${result.leaderConfig.model ?? "CLI default"}.`,
+            `Leader reasoning effort: ${result.leaderConfig.effort ?? "CLI default"}.`,
+            `Leader permission: ${result.leaderConfig.permission.strategy}.`,
+            `Operator model: ${result.operatorConfig.model ?? "CLI default"}.`,
+            `Operator reasoning effort: ${result.operatorConfig.effort ?? "CLI default"}.`,
+            `Operator permission: ${result.operatorConfig.permission.strategy}.`,
+            `Worker Agent: ${result.workerAgentId}.`,
+            `Worker configuration: ${result.workerReusesLeader
+                ? "Reused Leader configuration"
+                : "Configured separately"}.`,
+            `Worker model: ${result.workerConfig.model ?? "CLI default"}.`,
+            `Worker reasoning effort: ${result.workerConfig.effort ?? "CLI default"}.`,
+            `Worker permission: ${result.workerConfig.permission.strategy}.`,
+            ...(result.reviewerInitialized
+                ? [
+                    `Reviewer Agent: ${result.reviewerAgentId}.`,
+                    `Reviewer model: ${result.reviewerConfig?.model ?? "CLI default"}.`,
+                    `Reviewer reasoning effort: ${result.reviewerConfig?.effort ?? "CLI default"}.`,
+                    `Reviewer permission: ${result.reviewerConfig?.permission.strategy}.`,
+                    ...(result.reviewPolicy === undefined
+                        ? ["Review policy: disabled."]
+                        : [`Review policy: ${result.reviewPolicy.roleName} (${result.reviewPolicy.trigger}).`])
+                ]
+                : []),
+            `Project workspace: ${result.workspace}.`,
+            `Time zone: ${resolveTimeZone(store.getConfig().timeZone)}.`
         ];
         if (dependency === undefined || dependency === "tmux") {
             lines.push(...await setupTmux(env, executor, question));
@@ -63,7 +96,13 @@ export function validateSetupInvocation(args, io = {}) {
     if (!shouldPrompt(io))
         throw setupRequiresInteractiveError();
 }
-async function configureYui(store, home, env, question, io) {
+async function configureYui(store, home, env, question, selectionIo, catalogs, io) {
+    const initialConfig = store.getConfig();
+    const freshHome = store.listGlobalRoles().length === 0
+        && store.listConfiguredAgents().length === 0
+        && initialConfig.defaultAgent === undefined
+        && initialConfig.defaultWorkspace === undefined
+        && initialConfig.review === undefined;
     const candidates = availableAgentChoices(store, env);
     if (candidates.length === 0) {
         throw usageError("No supported Agent CLI was found. Install Codex or Claude, then run setup again.");
@@ -83,45 +122,210 @@ async function configureYui(store, home, env, question, io) {
     ]), tableWidth(io))}\n`);
     const selected = parseAgentSetSelection(await question(`Choose Agents by number or name, comma-separated [all: ${candidates.map(({ id }) => id).join(", ")}]: `), candidates);
     const now = new Date();
-    const persisted = selected.map((choice) => persistAgent(store, choice, now));
-    const configuredIds = new Set(persisted.map(({ id }) => id));
+    const prepared = selected.map((choice) => prepareAgent(store, choice, now));
+    const configuredIds = new Set(prepared.map(({ id }) => id));
     const config = store.getConfig();
-    const defaultFallback = configuredIds.has(config.defaultAgent ?? "")
+    const defaultFallback = prepared.some(({ id }) => id === config.defaultAgent)
         ? config.defaultAgent
-        : persisted[0]?.id;
-    if (defaultFallback === undefined)
-        throw usageError("At least one Agent must be selected.");
-    const defaultAgentId = parseSingleAgentSelection(await question(`Choose default Agent [${defaultFallback}]: `), persisted, defaultFallback);
+        : prepared[0].id;
+    const defaultAgentId = parseSingleAgentSelection(await question(`Choose default Agent [${defaultFallback}]: `), prepared, defaultFallback);
     const currentOperatorAgent = store.getGlobalRole(SYSTEM_OPERATOR_ROLE)?.activeAgentId;
     const operatorFallback = configuredIds.has(currentOperatorAgent ?? "")
         ? currentOperatorAgent
         : defaultAgentId;
-    const operatorAgentId = parseSingleAgentSelection(await question(`Choose Operator Agent [${operatorFallback}]: `), persisted, operatorFallback);
-    const suggestedWorkspace = config.defaultWorkspace?.trim() || join(home, "workspace");
-    const workspaceAnswer = (await question(`Operator workspace [${suggestedWorkspace}]: `)).trim();
-    const workspace = resolveWorkspace(workspaceAnswer || suggestedWorkspace);
-    const defaultAgent = persisted.find(({ id }) => id === defaultAgentId);
-    const operatorAgent = persisted.find(({ id }) => id === operatorAgentId);
+    const operatorAgentId = parseSingleAgentSelection(await question(`Choose Operator Agent [${operatorFallback}]: `), prepared, operatorFallback);
+    const existingReviewer = store.getGlobalRole(DEFAULT_REVIEWER_ROLE);
+    const reviewerInitialized = freshHome || existingReviewer !== null;
+    let reviewerAgentId;
+    let reviewerConfig;
+    if (reviewerInitialized) {
+        const reviewerFallback = configuredIds.has(existingReviewer?.activeAgentId ?? "")
+            ? existingReviewer.activeAgentId
+            : defaultAgentId;
+        reviewerAgentId = parseSingleAgentSelection(await question(`Choose Reviewer Agent [${reviewerFallback}]: `), prepared, reviewerFallback);
+        const reviewerAgent = prepared.find(({ id }) => id === reviewerAgentId);
+        if (reviewerAgent === undefined) {
+            throw usageError("Selected Reviewer Agent is no longer available.");
+        }
+        reviewerConfig = await promptRoleAgentConfig("Reviewer", reviewerAgent, existingReviewer, home, selectionIo, catalogs, true);
+    }
+    const defaultAgent = prepared.find(({ id }) => id === defaultAgentId);
+    const operatorAgent = prepared.find(({ id }) => id === operatorAgentId);
     if (defaultAgent === undefined || operatorAgent === undefined) {
         throw usageError("Selected setup Agent is no longer available.");
     }
-    assertSystemRoleCompatible(store, SYSTEM_OPERATOR_ROLE, operatorAgent, workspace);
-    assertSystemRoleCompatible(store, SYSTEM_LEADER_ROLE, defaultAgent, workspace);
-    mkdirSync(workspace, { recursive: true, mode: 0o700 });
-    store.saveConfig({
-        ...store.getConfig(),
-        defaultAgent: defaultAgentId,
-        defaultWorkspace: workspace
+    const leaderConfig = await promptRoleAgentConfig("Leader", defaultAgent, store.getGlobalRole(SYSTEM_LEADER_ROLE), home, selectionIo, catalogs);
+    const operatorConfig = await promptRoleAgentConfig("Operator", operatorAgent, store.getGlobalRole(SYSTEM_OPERATOR_ROLE), home, selectionIo, catalogs);
+    const existingWorker = store.getGlobalRole(SYSTEM_WORKER_ROLE);
+    const workerModeFallback = workerConfigurationModeFallback(existingWorker, defaultAgentId, leaderConfig);
+    io.output?.write("\nWorker is the default Agent configuration copied into Task Roles such as "
+        + "investigator and implementer. Each Task Role gets its own Session.\n");
+    const workerReusesLeader = parseWorkerConfigurationMode(await question(`Choose Worker configuration (reuse Leader/configure separately) [${workerModeFallback === "reuse-leader" ? "reuse Leader" : "configure separately"}]: `), workerModeFallback) === "reuse-leader";
+    let workerAgentId = defaultAgentId;
+    let workerConfig = structuredClone(leaderConfig);
+    if (!workerReusesLeader) {
+        const existingWorkerAgent = existingWorker?.activeAgentId;
+        const workerFallback = configuredIds.has(existingWorkerAgent ?? "")
+            ? existingWorkerAgent
+            : defaultAgentId;
+        workerAgentId = parseSingleAgentSelection(await question(`Choose Worker Agent [${workerFallback}]: `), prepared, workerFallback);
+        const workerAgent = prepared.find(({ id }) => id === workerAgentId);
+        if (workerAgent === undefined) {
+            throw usageError("Selected Worker Agent is no longer available.");
+        }
+        workerConfig = await promptRoleAgentConfig("Worker", workerAgent, existingWorker, home, selectionIo, catalogs);
+    }
+    const suggestedWorkspace = config.defaultWorkspace?.trim()
+        || join(dirname(resolve(home)), "workspace");
+    const workspaceAnswer = (await question(`Project workspace for stable checkouts and managed worktrees [${suggestedWorkspace}]: `)).trim();
+    const workspace = resolveWorkspace(workspaceAnswer || suggestedWorkspace, home);
+    if (config.defaultWorkspace !== undefined
+        && resolve(config.defaultWorkspace) !== workspace) {
+        throw usageError(`Project workspace is fixed after setup: ${resolve(config.defaultWorkspace)}.`);
+    }
+    store.transaction((tx) => {
+        for (const agent of prepared)
+            tx.saveConfiguredAgent(agent);
+        const latestDefaultAgent = requireSetupAgent(tx, defaultAgentId);
+        const latestOperatorAgent = requireSetupAgent(tx, operatorAgentId);
+        const latestWorkerAgent = requireSetupAgent(tx, workerAgentId);
+        const operatorRole = prepareSystemRole(tx, SYSTEM_OPERATOR_ROLE, latestOperatorAgent, workspace, now, operatorConfig);
+        const leaderRole = prepareSystemRole(tx, SYSTEM_LEADER_ROLE, latestDefaultAgent, workspace, now, leaderConfig);
+        const workerRole = prepareSystemRole(tx, SYSTEM_WORKER_ROLE, latestWorkerAgent, workspace, now, workerConfig);
+        const reviewerRole = reviewerInitialized
+            && reviewerAgentId !== undefined
+            && reviewerConfig !== undefined
+            ? prepareSystemRole(tx, DEFAULT_REVIEWER_ROLE, requireSetupAgent(tx, reviewerAgentId), workspace, now, reviewerConfig, freshHome ? reviewerRoleProfile() : undefined)
+            : null;
+        const latest = tx.getConfig();
+        tx.saveConfig({
+            ...latest,
+            defaultAgent: defaultAgentId,
+            defaultWorkspace: workspace,
+            timeZone: resolveTimeZone(latest.timeZone),
+            ...(freshHome
+                ? { review: { roleName: DEFAULT_REVIEWER_ROLE, trigger: "final" } }
+                : {})
+        });
+        if (operatorRole !== null)
+            savePreparedSystemRole(tx, operatorRole, now);
+        if (leaderRole !== null)
+            savePreparedSystemRole(tx, leaderRole, now);
+        if (workerRole !== null)
+            savePreparedSystemRole(tx, workerRole, now);
+        if (reviewerRole !== null)
+            savePreparedSystemRole(tx, reviewerRole, now);
+        seedBuiltinProfiles(tx, now);
     });
-    ensureSystemRole(store, SYSTEM_OPERATOR_ROLE, operatorAgent, workspace, now);
-    ensureSystemRole(store, SYSTEM_LEADER_ROLE, defaultAgent, workspace, now);
     return {
-        agentIds: persisted.map(({ id }) => id),
+        agentIds: prepared.map(({ id }) => id),
         defaultAgentId,
         operatorAgentId,
+        leaderConfig,
+        operatorConfig,
+        workerAgentId,
+        workerConfig,
+        workerReusesLeader,
+        reviewerInitialized,
+        ...(reviewerAgentId === undefined ? {} : { reviewerAgentId }),
+        ...(reviewerConfig === undefined ? {} : { reviewerConfig }),
+        ...(freshHome
+            ? { reviewPolicy: { roleName: DEFAULT_REVIEWER_ROLE, trigger: "final" } }
+            : initialConfig.review === undefined ? {} : { reviewPolicy: initialConfig.review }),
         workspace
     };
 }
+function reviewerRoleProfile() {
+    const reviewer = builtinAgentProfileInputs().find(({ id }) => id === "reviewer");
+    if (reviewer === undefined)
+        return {};
+    return {
+        ...(reviewer.description === undefined ? {} : { description: reviewer.description }),
+        ...(reviewer.instructions === undefined ? {} : { systemPrompt: reviewer.instructions }),
+        ...(reviewer.skills === undefined ? {} : { skills: [...reviewer.skills] })
+    };
+}
+function workerConfigurationModeFallback(existing, leaderAgentId, leaderConfig) {
+    if (existing === null)
+        return "reuse-leader";
+    return existing.activeAgentId === leaderAgentId
+        && isDeepStrictEqual(existing.agentBindings[leaderAgentId]?.config, leaderConfig)
+        ? "reuse-leader"
+        : "configure-separately";
+}
+function parseWorkerConfigurationMode(answer, fallback) {
+    const value = answer.trim().toLowerCase();
+    if (value.length === 0)
+        return fallback;
+    if (["1", "reuse", "reuse leader", "leader"].includes(value))
+        return "reuse-leader";
+    if (["2", "configure", "configure separately", "separate"].includes(value)) {
+        return "configure-separately";
+    }
+    throw usageError("Choose reuse Leader or configure separately for Worker.");
+}
+function savePreparedSystemRole(store, role, now) {
+    const sessions = store.getGlobalRoleSessionSet(role.name);
+    const activeSession = sessions?.sessions[sessions.activeAgentId];
+    if (sessions === null
+        || sessions.activeAgentId === role.activeAgentId
+        || (activeSession !== undefined && activeSession.status !== "stopped")) {
+        store.saveGlobalRole(role);
+        return;
+    }
+    store.saveGlobalRoleWithSessionSet(role, {
+        ...sessions,
+        activeAgentId: role.activeAgentId,
+        updatedAt: now.toISOString()
+    });
+}
+function seedBuiltinProfiles(store, now) {
+    for (const desired of builtinAgentProfileInputs()) {
+        const existing = store.getAgentProfile(desired.id);
+        if (existing === null)
+            store.saveAgentProfile(createAgentProfile(desired, now));
+    }
+}
+async function promptRoleAgentConfig(label, agent, existingRole, cwd, io, catalogs, selectPermission = false) {
+    const existing = existingRole?.activeAgentId === agent.id
+        ? existingRole.agentBindings[agent.id]?.config
+        : undefined;
+    io.write(`\n${label} Agent configuration: ${agent.id}\n`);
+    const resolved = await catalogs.resolve({
+        agent,
+        cwd,
+        ...(existing === undefined ? {} : { config: existing })
+    });
+    const selection = await selectAgentModelAndEffort(resolved, io, {
+        currentModel: existing?.model,
+        currentEffort: existing?.effort
+    });
+    if (selection.kind === "cancelled") {
+        throw usageError(`${label} Agent configuration was cancelled.`);
+    }
+    const candidate = structuredClone(existing ?? defaultRoleAgentConfig(agent.adapterId));
+    if (selection.model === undefined)
+        delete candidate.model;
+    else
+        candidate.model = selection.model;
+    if (selection.effort === undefined)
+        delete candidate.effort;
+    else
+        candidate.effort = selection.effort;
+    if (selectPermission) {
+        const permission = await selectAgentPermission(resolved, io, candidate.permission);
+        if (permission.kind === "cancelled") {
+            throw usageError(`${label} permission configuration was cancelled.`);
+        }
+        candidate.permission = permission.permission;
+    }
+    try {
+        return resolveAgentAdapter(agent.adapterId).canonicalizeConfig(candidate);
+    }
+    catch (error) {
+        throw usageError(error instanceof Error ? error.message : String(error));
+    }
+}
 function availableAgentChoices(store, env) {
     const existing = new Map(store.listConfiguredAgents().map((agent) => [agent.id, agent]));
     return BUILTIN_AGENTS.flatMap((builtin) => {
@@ -136,7 +340,16 @@ function availableAgentChoices(store, env) {
             }];
     });
 }
-function persistAgent(store, choice, now) {
+function setupSelectionIo(question, io) {
+    return {
+        interactive: true,
+        json: false,
+        width: tableWidth(io),
+        write: (value) => { io.output.write(value); },
+        question
+    };
+}
+function prepareAgent(store, choice, now) {
     const existing = store.getConfiguredAgent(choice.id);
     if (existing !== null
         && existing.adapterId === choice.adapterId
@@ -144,24 +357,49 @@ function persistAgent(store, choice, now) {
         return existing;
     }
     const agent = createConfiguredAgent(choice.id, choice.adapterId, choice.command, existing?.baseArgs ?? [], existing?.environment ?? [], now);
-    store.saveConfiguredAgent(agent);
     return agent;
 }
-function ensureSystemRole(store, name, agent, workspace, now) {
-    const definition = configuredAgentToDefinition(agent);
-    const existing = store.getGlobalRole(name);
-    if (existing !== null)
-        return;
-    store.saveGlobalRole(createGlobalRole(name, [createRoleAgentBinding(definition)], definition.id, workspace, now));
+function requireSetupAgent(store, agentId) {
+    const agent = store.getConfiguredAgent(agentId);
+    if (agent === null)
+        throw usageError(`Configured Agent not found: ${agentId}.`);
+    return agent;
 }
-function assertSystemRoleCompatible(store, name, agent, workspace) {
+function prepareSystemRole(store, name, agent, workspace, now, config, profile) {
     const existing = store.getGlobalRole(name);
-    if (existing === null)
-        return;
-    if (existing.activeAgentId === agent.id && existing.workspace === workspace)
-        return;
-    throw usageError(`Global Role ${name} is already configured with Agent ${existing.activeAgentId} `
-        + `and workspace ${existing.workspace}. Stop its Session and use role update before changing it.`);
+    if (existing !== null) {
+        const definition = configuredAgentToDefinition(agent);
+        const binding = createRoleAgentBinding(definition, config);
+        if (name === "operator" && !Object.hasOwn(existing.agentBindings, agent.id)) {
+            const sameAdapter = Object.values(existing.agentBindings).find((candidate) => candidate.adapterId === agent.adapterId);
+            if (sameAdapter !== undefined) {
+                throw usageError(`${name} already has a ${agent.adapterId} Agent: ${sameAdapter.agentId}. `
+                    + "Update that Agent's configuration, or activate another adapter and "
+                    + "unbind it before selecting this Agent.");
+            }
+        }
+        if (existing.activeAgentId === agent.id
+            && existing.workspace === workspace
+            && isDeepStrictEqual(existing.agentBindings[agent.id], binding)) {
+            return null;
+        }
+        assertRoleRuntimeMutationAllowed(store, {
+            scope: "global",
+            roleName: name
+        }, "desired launch configuration update");
+        return updateGlobalRole(existing, {
+            activeAgentId: agent.id,
+            workspace,
+            agentBindings: { ...existing.agentBindings, [agent.id]: binding },
+            ...(profile === undefined ? {} : profile)
+        }, now);
+    }
+    assertRoleRuntimeMutationAllowed(store, {
+        scope: "global",
+        roleName: name
+    }, "creation");
+    const definition = configuredAgentToDefinition(agent);
+    return createGlobalRole(name, [createRoleAgentBinding(definition, config)], definition.id, workspace, now, profile);
 }
 function parseAgentSetSelection(answer, candidates) {
     const value = answer.trim().toLowerCase();
@@ -197,10 +435,22 @@ function parseSingleAgentSelection(answer, agents, fallback) {
     }
     return selected.id;
 }
-function resolveWorkspace(value) {
+function resolveWorkspace(value, home) {
     if (!isAbsolute(value))
-        throw usageError("Operator workspace must be an absolute path.");
-    return resolve(value);
+        throw usageError("Project workspace must be an absolute path.");
+    const requested = resolve(value);
+    assertWorkspaceOutsideHome(requested, resolve(home));
+    mkdirSync(requested, { recursive: true, mode: 0o700 });
+    const workspace = realpathSync(requested);
+    const homeRoot = realpathSync(resolve(home));
+    assertWorkspaceOutsideHome(workspace, homeRoot);
+    return workspace;
+}
+function assertWorkspaceOutsideHome(workspace, homeRoot) {
+    const fromHome = relative(homeRoot, workspace);
+    if (fromHome === "" || (!fromHome.startsWith("..") && !isAbsolute(fromHome))) {
+        throw usageError("Project workspace must be outside YUI_HOME.");
+    }
 }
 function commandOnPath(command, env) {
     if (command.includes("/") || command.includes("\\"))

package/dist/storage/compatibleTaskStore.js

@@ -0,0 +1,102 @@
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { StorageCompatibilityError, loadCompatibleSnapshot } from "./migration/index.js";
+import { createProductionStorageRegistry } from "./migration/productionRegistry.js";
+import { FileTaskStore, validateCurrentStorageStateSnapshot } from "./taskStore.js";
+import { ensureStorageSchema, inspectStorageSchema, STORAGE_SCHEMA_FILE } from "./storageSchema.js";
+import { classifyHome } from "./upgrade/homeClassification.js";
+import { inspectSnapshotVersionState } from "./upgrade/homeMigrationTarget.js";
+import { latestStorageVersionState } from "./upgrade/recordVersions.js";
+export { createProductionStorageRegistry } from "./migration/productionRegistry.js";
+/**
+ * Initialize a brand-new Home, or open an existing Home through the same
+ * compatibility classification as every ordinary command. Setup is the one
+ * ordinary flow that is also responsible for creating the initial manifest.
+ */
+export function initializeCompatibleFileTaskStore(home, options = {}) {
+    if (inspectStorageSchema(home).status === "uninitialized") {
+        ensureStorageSchema(home);
+    }
+    return openCompatibleFileTaskStore(home, options);
+}
+/**
+ * Open current or explicitly compatible-old storage. Compatible records are
+ * normalized in memory through strict old-shape validators; FileTaskStore then
+ * runs its one current parser and its existing writer emits only current bytes.
+ */
+export function openCompatibleFileTaskStore(home, options = {}) {
+    const registry = options.registry ?? createProductionStorageRegistry();
+    const latest = options.latest ?? latestStorageVersionState();
+    const classification = classifyHome({ home, registry, latest });
+    switch (classification.classification.status) {
+        case "current":
+            return new FileTaskStore(home);
+        case "compatible-old":
+            return new FileTaskStore(home, {
+                normalizeState: (raw) => normalizeState(home, raw, registry, latest)
+            });
+        case "migration-required":
+            throw new StorageCompatibilityError("Storage requires an offline migration. Re-run `yui update` when active Sessions are clear.");
+        case "unsupported":
+            throw new StorageCompatibilityError(describeUnsupported(classification.classification));
+    }
+}
+/**
+ * Eagerly prove that a compatible-old Home reaches the strict current parser.
+ * Staged update/upgrade preflight uses this before any Controller or binary
+ * action; ordinary commands may keep the store's normal lazy-read behavior.
+ */
+export function validateCompatibleFileTaskStore(home, options = {}) {
+    openCompatibleFileTaskStore(home, options).getConfig();
+}
+function normalizeState(home, raw, registry, latest) {
+    let state;
+    try {
+        state = JSON.parse(raw);
+    }
+    catch (error) {
+        throw new StorageCompatibilityError(`Compatible state is not valid JSON: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    if (!isRecord(state)) {
+        throw new StorageCompatibilityError("Compatible state must be a JSON object.");
+    }
+    const schemaManifest = JSON.parse(readFileSync(join(home, STORAGE_SCHEMA_FILE), "utf8"));
+    if (!isRecord(schemaManifest)) {
+        throw new StorageCompatibilityError("Compatible schema manifest must be a JSON object.");
+    }
+    const snapshot = { schemaManifest, state };
+    const source = versionsOf(snapshot, latest);
+    const normalized = loadCompatibleSnapshot({
+        registry,
+        source,
+        latest,
+        snapshot,
+        inspectVersions: (candidate) => versionsOf(candidate, latest),
+        validateCurrent: (candidate) => {
+            if (candidate.state === null) {
+                throw new StorageCompatibilityError("Compatible state unexpectedly disappeared.");
+            }
+            validateCurrentStorageStateSnapshot(candidate.state);
+        }
+    });
+    return `${JSON.stringify(normalized.state)}\n`;
+}
+function versionsOf(snapshot, latest) {
+    const inspection = inspectSnapshotVersionState(snapshot, latest);
+    if ("corruption" in inspection) {
+        throw new StorageCompatibilityError(inspection.corruption.detail);
+    }
+    return inspection.source;
+}
+function describeUnsupported(classification) {
+    if (classification.verdict === "CORRUPTED") {
+        return `Invalid state.json: ${classification.detail}`;
+    }
+    if (classification.verdict === "NEEDS_NEW_VERSION") {
+        return classification.blocker.message;
+    }
+    return "Storage is unsupported by this Yui release.";
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/dist/storage/migration/baseline.js

@@ -0,0 +1,78 @@
+import { CURRENT_AGGREGATE_SCHEMA_VERSION, CURRENT_STORAGE_LAYOUT_VERSION } from "../storageVersions.js";
+import { currentRecordVersions } from "../upgrade/recordVersions.js";
+export const BASELINE_STORAGE_LAYOUT_VERSION = 6;
+export const BASELINE_AGGREGATE_SCHEMA_VERSION = 16;
+const BASELINE_RECORD_DESCRIPTORS = Object.freeze({
+    config: descriptor(1, "state.json#/config"),
+    configuredAgent: descriptor(2, "state.json#/configuredAgents"),
+    project: descriptor(2, "state.json#/projects"),
+    agentProfile: descriptor(2, "state.json#/agentProfiles"),
+    globalRole: descriptor(3, "state.json#/globalRoles"),
+    globalRoleSessionSet: descriptor(3, "state.json#/globalRoleSessionSets"),
+    storedTask: descriptor(14, "state.json#/tasks/*"),
+    task: descriptor(3, "state.json#/tasks/*/task"),
+    taskBrief: descriptor(2, "state.json#/tasks/*/brief"),
+    taskRole: descriptor(3, "state.json#/tasks/*/roles"),
+    managedWorkspace: descriptor(1, "state.json#/tasks/*/managedWorkspaces"),
+    taskRoleSessionSet: descriptor(4, "state.json#/tasks/*/roleSessionSets"),
+    workItem: descriptor(6, "state.json#/tasks/*/workItems"),
+    agentRun: descriptor(5, "state.json#/tasks/*/agentRuns"),
+    reviewRound: descriptor(2, "state.json#/tasks/*/reviewRounds"),
+    changeSet: descriptor(2, "state.json#/tasks/*/changeSets"),
+    integrationAttempt: descriptor(2, "state.json#/tasks/*/integrationAttempts"),
+    activeRunPointer: descriptor(1, "state.json#/tasks/*/activeRuns"),
+    message: descriptor(2, "state.json#/tasks/*/messages"),
+    inputRequest: descriptor(2, "state.json#/tasks/*/inputRequests"),
+    decision: descriptor(1, "state.json#/tasks/*/decisions"),
+    milestone: descriptor(1, "state.json#/tasks/*/milestones"),
+    event: descriptor(2, "state.json#/tasks/*/events"),
+    leaderFailure: descriptor(1, "state.json#/tasks/*/leaderFailure"),
+    operatorNotification: descriptor(1, "state.json#/tasks/*/operatorNotification"),
+    workMailbox: descriptor(1, "state.json#/mailboxes")
+});
+/** Frozen baseline record-family version map retained as a public delivery contract. */
+export const BASELINE_RECORD_VERSIONS = Object.freeze(Object.fromEntries(Object.entries(BASELINE_RECORD_DESCRIPTORS).map(([kind, entry]) => [kind, entry.version])));
+export function baselineStorageVersionState() {
+    return Object.freeze({
+        layout: BASELINE_STORAGE_LAYOUT_VERSION,
+        aggregate: BASELINE_AGGREGATE_SCHEMA_VERSION,
+        record: Object.freeze({ ...BASELINE_RECORD_DESCRIPTORS })
+    });
+}
+/** Constant spelling used by delivery-gate callers and historical tests. */
+export const BASELINE_STORAGE_VERSION_STATE = baselineStorageVersionState();
+/**
+ * Fail the delivery gate if the immutable baseline is ahead of the live schema,
+ * loses a record family, or changes a locator without an explicit scalar
+ * storage boundary. The production registry gate separately proves the full
+ * executable baseline-to-current transition path.
+ */
+export function assertBaselineConsistency(current = {
+    layout: CURRENT_STORAGE_LAYOUT_VERSION,
+    aggregate: CURRENT_AGGREGATE_SCHEMA_VERSION,
+    record: currentRecordVersions()
+}) {
+    if (BASELINE_STORAGE_LAYOUT_VERSION > current.layout) {
+        throw new Error(`Baseline layout ${BASELINE_STORAGE_LAYOUT_VERSION} exceeds current layout ${current.layout}.`);
+    }
+    if (BASELINE_AGGREGATE_SCHEMA_VERSION > current.aggregate) {
+        throw new Error(`Baseline aggregate ${BASELINE_AGGREGATE_SCHEMA_VERSION} exceeds current aggregate ${current.aggregate}.`);
+    }
+    const scalarVersionAdvanced = current.layout > BASELINE_STORAGE_LAYOUT_VERSION
+        || current.aggregate > BASELINE_AGGREGATE_SCHEMA_VERSION;
+    for (const [kind, baselineEntry] of Object.entries(BASELINE_RECORD_DESCRIPTORS)) {
+        const currentEntry = current.record[kind];
+        if (!Number.isSafeInteger(baselineEntry.version) || baselineEntry.version < 1) {
+            throw new Error(`Baseline record family '${kind}' has invalid version ${String(baselineEntry.version)}.`);
+        }
+        if (currentEntry === undefined || baselineEntry.version > currentEntry.version) {
+            throw new Error(`Baseline record family '${kind}' is ahead of or missing from current.`);
+        }
+        if (baselineEntry.path !== currentEntry.path && !scalarVersionAdvanced) {
+            throw new Error(`Baseline record family '${kind}' path drift requires a layout or aggregate version change.`);
+        }
+    }
+}
+function descriptor(version, path) {
+    return Object.freeze({ version, path });
+}