@zq-silk/yui 0.6.0 → 0.6.2

package/dist/scheduler/leaderWakeupProcessor.js

@@ -2,7 +2,7 @@ import { createAgentRun } from "../run/agentRun.js";
 import { markYuiRunInput } from "../run/runIdentity.js";
 import { taskRoleSessionTitle } from "../runtime/sessionTitle.js";
 import { formatAgentRunReceiptId } from "../task/taskRecordReference.js";
-import { effectiveLaunchSnapshotsCompatible } from "../executor/effectiveLaunch.js";
+import { effectiveLaunchSnapshotsCompatible, effectiveLaunchSnapshotsCompatibleForTaskMain } from "../executor/effectiveLaunch.js";
 import { hasRuntimeLifecycleWork, runtimeLifecycleTarget } from "../runtime/lifecycleReservation.js";
 import { recordLeaderFailure } from "./leaderFailure.js";
 import { createLeaderRecoveryNotification } from "./operatorNotification.js";
@@ -93,7 +93,9 @@ export async function processLeaderWakeups(store, delivery, now, selection) {
                 }
             }
             const compatibleSession = existingSession !== null
-                && effectiveLaunchSnapshotsCompatible(existingSession.effective, role.effective);
+                && (reopening
+                    ? effectiveLaunchSnapshotsCompatible(existingSession.effective, role.effective)
+                    : effectiveLaunchSnapshotsCompatibleForTaskMain(existingSession.effective, role.effective, role.managedWorkspace));
             const reopenIdentityDrift = reopening
                 && hasNativeSession(existingSession)
                 && !compatibleSession;
@@ -146,7 +148,7 @@ export async function processLeaderWakeups(store, delivery, now, selection) {
                 ...(mode === "resume" ? { nativeSessionId: existingSession.nativeSessionId } : {}),
                 beforeHostStart: (preflight) => {
                     persistPreStartFence(store, task, role, run, existingSession, mode, preflight, now);
-                    effectiveSession = preflightSession(run.effective, existingSession, mode, preflight);
+                    effectiveSession = preflightSession(role, run.effective, existingSession, mode, preflight);
                     preStartFencePersisted = true;
                 }
             });
@@ -164,7 +166,7 @@ export async function processLeaderWakeups(store, delivery, now, selection) {
             if (!preStartFencePersisted) {
                 const preparedFenceSession = prepared.session === undefined
                     ? existingSession
-                    : validateReadySession(run.effective, existingSession, mode, prepared.session);
+                    : validateReadySession(role, run.effective, existingSession, mode, prepared.session);
                 effectiveSession = preparedFenceSession;
                 store.saveRoleRunPrepared({
                     task,
@@ -191,7 +193,7 @@ export async function processLeaderWakeups(store, delivery, now, selection) {
                 results.push({ taskId: task.id, status: "skipped", reason: "unavailable" });
                 continue;
             }
-            effectiveSession = validateReadySession(run.effective, existingSession, mode, ready.session);
+            effectiveSession = validateReadySession(role, run.effective, existingSession, mode, ready.session);
             store.saveRoleRunPrepared({
                 task,
                 role,
@@ -309,7 +311,7 @@ export async function processLeaderWakeups(store, delivery, now, selection) {
     }
     return results;
 }
-function validateReadySession(effective, existing, mode, session) {
+function validateReadySession(role, effective, existing, mode, session) {
     if (mode === "new" && session === null)
         return null;
     if (session === null)
@@ -317,7 +319,10 @@ function validateReadySession(effective, existing, mode, session) {
     if (session.agentId !== effective.agentId || session.adapterId !== effective.adapterId) {
         throw new Error(`Ready session belongs to another Agent: ${session.agentId}.`);
     }
-    if (!effectiveLaunchSnapshotsCompatible(session.effective, effective)) {
+    const compatible = mode === "resume"
+        ? effectiveLaunchSnapshotsCompatibleForTaskMain(session.effective, effective, role.managedWorkspace)
+        : effectiveLaunchSnapshotsCompatible(session.effective, effective);
+    if (!compatible) {
         throw new Error("Ready Leader session effective snapshot changed.");
     }
     if (!hasNativeSession(session)) {
@@ -326,7 +331,13 @@ function validateReadySession(effective, existing, mode, session) {
     if (mode === "resume" && session.nativeSessionId !== existing?.nativeSessionId) {
         throw new Error("Leader resume changed the fixed native session id.");
     }
-    return { ...session, status: "running" };
+    return {
+        ...session,
+        status: "running",
+        ...(mode === "resume" && existing !== null
+            ? { effective: existing.effective }
+            : {})
+    };
 }
 function persistPreStartFence(store, task, role, run, existingSession, mode, preflight, now) {
     if (preflight.owner.scope !== "task"
@@ -336,7 +347,7 @@ function persistPreStartFence(store, task, role, run, existingSession, mode, pre
         || preflight.launchId.trim().length === 0) {
         throw new Error(`Pre-start launch fence changed the Leader Run: ${task.id}/${role.name}.`);
     }
-    const session = preflightSession(run.effective, existingSession, mode, preflight);
+    const session = preflightSession(role, run.effective, existingSession, mode, preflight);
     store.saveRoleRunPrepared({
         task,
         role,
@@ -346,7 +357,7 @@ function persistPreStartFence(store, task, role, run, existingSession, mode, pre
         now
     });
 }
-function preflightSession(effective, existing, mode, preflight) {
+function preflightSession(role, effective, existing, mode, preflight) {
     const session = preflight.nativeSessionId === undefined
         ? null
         : {
@@ -357,7 +368,7 @@ function preflightSession(effective, existing, mode, preflight) {
             status: "ready",
             effective: preflight.effective
         };
-    return validateReadySession(effective, existing, mode, session);
+    return validateReadySession(role, effective, existing, mode, session);
 }
 function hasNativeSession(session) {
     return session !== null &&

package/dist/scheduler/roleRunStall.js

@@ -17,6 +17,22 @@ export const RUN_RESOURCE_SUPPRESSED_EVENT = "run.resource-suppressed";
 /** Structured, non-Message recovery evidence written by an explicit Leader. */
 export const RUN_RECOVERY_REQUESTED_EVENT = "run.recovery-requested";
 export const RUN_RECOVERY_APPLIED_EVENT = "run.recovery-applied";
+/** Event types that count as Run activity for the durable progress clock. */
+const ACTIVITY_EVENT_TYPES = new Set([
+    RUN_PROGRESS_EVENT,
+    "runtime.provider-turn-progress",
+    "message.sent",
+    "input.answered",
+    "input.auto-answered",
+    "input.cancelled",
+    "work.accepted",
+    "work.updated",
+    "review.completed",
+    "review.failed",
+    "integration.updated",
+    "integration.completed",
+    "integration.failed"
+]);
 /**
  * Clear only the Operator projection raised for this exact Leader Run. A
  * later Run (or a recovery notification of another kind) must remain intact;
@@ -195,16 +211,23 @@ export function currentRoleRunProgressAt(store, taskId, roleName, run, events =
     }
     if (run.deliveredAt === undefined)
         return { progressAt: run.createdAt };
+    // The richer fold is authoritative when present; skip the per-candidate
+    // full-history scans that every stall candidate otherwise pays.
+    if (richerProgress !== undefined && richerProgress !== null) {
+        return {
+            progressAt: richerProgress.progressAt,
+            ...(richerProgress.evidence === undefined
+                ? {}
+                : { evidence: richerProgress.evidence })
+        };
+    }
     const fallbackProgressAt = latestDurableProgressAt({
         deliveredAt: run.deliveredAt,
         latestCheckpointAt: latestRunProgressAt(events, run.id),
         latestActivityAt: latestRunActivityAt(events, run.id)
     });
     return {
-        progressAt: richerProgress?.progressAt ?? fallbackProgressAt,
-        ...(richerProgress?.evidence === undefined
-            ? {}
-            : { evidence: richerProgress.evidence })
+        progressAt: fallbackProgressAt
     };
 }
 /**
@@ -212,13 +235,23 @@ export function currentRoleRunProgressAt(store, taskId, roleName, run, events =
  * related-record readers mirror the adapter's Work/Review/Integration fold;
  * narrow scheduler ports can omit them and still retain Run/Event evidence.
  */
-export function latestRunDurableProgressAt(store, taskId, roleName, runId) {
+export function latestRunDurableProgressAt(store, taskId, roleName, runId, precomputed) {
     const run = store.getAgentRun(taskId, runId);
     if (run === null || run.taskId !== taskId || run.roleName !== roleName)
         return null;
     const events = store.listEvents(taskId);
-    const latestCheckpointAt = latestRunProgressAt(events, run.id);
-    const latestActivityAt = latestRunActivityAt(events, run.id);
+    // The adapter folds checkpoint/activity once per revision. When the fold
+    // port exists, a missing per-Run entry is an authoritative empty fold: use
+    // its (possibly undefined) values directly and never re-scan the whole
+    // history per candidate. Legacy callers without the port omit precomputed
+    // and keep the per-candidate full-history scans.
+    const folded = precomputed !== undefined;
+    const latestCheckpointAt = folded
+        ? precomputed.latestCheckpointAt
+        : latestRunProgressAt(events, run.id);
+    const latestActivityAt = folded
+        ? precomputed.latestActivityAt
+        : latestRunActivityAt(events, run.id);
     const baseline = run.deliveredAt === undefined
         ? run.createdAt
         : latestDurableProgressAt({
@@ -280,24 +313,9 @@ export function latestRunEventTime(events, type, runId) {
 }
 /** Most recent non-control event carrying a Run identity. */
 export function latestRunActivityAt(events, runId) {
-    const semanticTypes = new Set([
-        RUN_PROGRESS_EVENT,
-        "runtime.provider-turn-progress",
-        "message.sent",
-        "input.answered",
-        "input.auto-answered",
-        "input.cancelled",
-        "work.accepted",
-        "work.updated",
-        "review.completed",
-        "review.failed",
-        "integration.updated",
-        "integration.completed",
-        "integration.failed"
-    ]);
     let latest;
     for (const event of events) {
-        if (!semanticTypes.has(event.type)
+        if (!ACTIVITY_EVENT_TYPES.has(event.type)
             || event.payload.runId !== runId
             || event.type === RUN_STALLED_EVENT
             || event.type === RUN_RECOVERED_EVENT)
@@ -347,6 +365,79 @@ export function latestStallEvidenceKey(events, runId) {
         evidenceKey: latest.payload.evidenceKey ?? "live-pane-no-progress"
     };
 }
+/**
+ * Folds a Task's event history into per-Run progress facts in one O(events)
+ * pass. The adapter builds this once per durable revision and serves the
+ * stall reconciliation from it, replacing the per-candidate full-history
+ * clones and scans that turned one pass into an O(candidates x events) hot
+ * read. The fold mirrors latestRunProgressAt/latestRunActivityAt/
+ * latestStallProgressAt/latestStallEvidenceKey exactly.
+ */
+export function foldRunProgressFacts(events) {
+    const byRun = new Map();
+    const latestStallCreatedAt = new Map();
+    for (const event of events) {
+        const runId = event.payload.runId;
+        if (typeof runId !== "string")
+            continue;
+        let facts = byRun.get(runId);
+        if (facts === undefined) {
+            facts = {};
+            byRun.set(runId, facts);
+        }
+        const type = event.type;
+        const isProgress = type === RUN_PROGRESS_EVENT
+            || type === "runtime.provider-turn-progress";
+        if (isProgress) {
+            const validProgress = typeof event.payload.progressAt === "string"
+                && Number.isFinite(Date.parse(event.payload.progressAt));
+            if (type === "runtime.provider-turn-progress" && !validProgress)
+                continue;
+            const progressAt = validProgress
+                ? event.payload.progressAt
+                : event.createdAt;
+            if (facts.latestCheckpointAt === undefined
+                || Date.parse(progressAt) > Date.parse(facts.latestCheckpointAt)) {
+                facts.latestCheckpointAt = progressAt;
+            }
+            // Both progress event types are activity events; the stall/recovered
+            // exclusion in latestRunActivityAt is structural here because a progress
+            // event can never be either type.
+            if (facts.latestActivityAt === undefined
+                || Date.parse(progressAt) > Date.parse(facts.latestActivityAt)) {
+                facts.latestActivityAt = progressAt;
+            }
+        }
+        else if (type === RUN_STALLED_EVENT) {
+            const previousCreatedAt = latestStallCreatedAt.get(runId);
+            if (previousCreatedAt === undefined
+                || Date.parse(event.createdAt) > Date.parse(previousCreatedAt)) {
+                latestStallCreatedAt.set(runId, event.createdAt);
+                facts.latestStall = typeof event.payload.progressAt === "string"
+                    ? {
+                        progressAt: event.payload.progressAt,
+                        evidenceKey: typeof event.payload.evidenceKey === "string"
+                            ? event.payload.evidenceKey
+                            : "live-pane-no-progress"
+                    }
+                    : undefined;
+            }
+        }
+        else if (ACTIVITY_EVENT_TYPES.has(type)
+            && type !== RUN_STALLED_EVENT
+            && type !== RUN_RECOVERED_EVENT) {
+            if (facts.latestActivityAt === undefined
+                || Date.parse(event.createdAt) > Date.parse(facts.latestActivityAt)) {
+                facts.latestActivityAt = event.createdAt;
+            }
+        }
+    }
+    return byRun;
+}
+/** Yield the event loop so already-written control requests stay responsive. */
+function yieldEventLoop() {
+    return new Promise((resolve) => setImmediate(resolve));
+}
 /**
  * True while a Run remains in an unresolved stall episode: a stall was raised
  * and no later checkpoint has advanced its durable progress since. This is the
@@ -388,6 +479,11 @@ export async function reconcileStalledRoleRuns(store, delivery, now, selection,
         return [];
     if (store.listEvents === undefined || store.recordRoleRunStall === undefined)
         return [];
+    // When the fold port exists, a missing per-Run entry is an authoritative
+    // empty fold: the stall reconciliation must not re-scan the whole history
+    // per candidate. Legacy stores without the port keep the per-candidate
+    // scans.
+    const foldPortPresent = store.getRunProgressFacts !== undefined;
     const candidates = selectedSchedulerTasks(store, selection).flatMap((task) => (task.status !== "active"
         ? []
         : selectedSchedulerRoles(store, task.id, selection).flatMap((role) => {
@@ -473,7 +569,12 @@ export async function reconcileStalledRoleRuns(store, delivery, now, selection,
         }
     }
     const raised = [];
-    for (const candidate of stallCandidates) {
+    for (const [candidateIndex, candidate] of stallCandidates.entries()) {
+        // A large Task's per-candidate reads are now bounded, but many candidates
+        // in one pass still add up. Yield periodically so already-written control
+        // requests are not starved by the whole reconciliation.
+        if (candidateIndex > 0 && candidateIndex % 16 === 0)
+            await yieldEventLoop();
         const key = `${candidate.task.id}\0${candidate.role.name}`;
         let live;
         try {
@@ -514,6 +615,7 @@ export async function reconcileStalledRoleRuns(store, delivery, now, selection,
             continue;
         }
         const events = store.listEvents(candidate.task.id);
+        const progressFacts = store.getRunProgressFacts?.(candidate.task.id, candidate.run.id);
         // Before exact acceptance there is no execution progress clock. Keep the
         // delivery watch anchored to the Run creation/transport boundary even if
         // checkpoints, output, or related WorkItem/Review/Integration records are
@@ -526,7 +628,9 @@ export async function reconcileStalledRoleRuns(store, delivery, now, selection,
             progressAt,
             now,
             windowMs,
-            lastAttentionProgressAt: latestStallProgressAt(events, candidate.run.id)
+            lastAttentionProgressAt: foldPortPresent
+                ? progressFacts?.latestStall?.progressAt
+                : latestStallProgressAt(events, candidate.run.id)
         });
         const runAgentId = candidate.run.effective.agentId;
         const runAdapterId = candidate.run.effective.adapterId;
@@ -605,8 +709,9 @@ export async function reconcileStalledRoleRuns(store, delivery, now, selection,
         if (current.live !== "present" || !current.stalled || !current.stallCandidate)
             continue;
         const { candidate, progressAt } = current;
-        const events = store.listEvents(candidate.task.id);
-        const previous = latestStallEvidenceKey(events, candidate.run.id);
+        const previous = foldPortPresent
+            ? store.getRunProgressFacts?.(candidate.task.id, candidate.run.id)?.latestStall
+            : latestStallEvidenceKey(store.listEvents(candidate.task.id), candidate.run.id);
         if (previous !== undefined
             && Date.parse(progressAt) > Date.parse(previous.progressAt)) {
             // A new semantic progress point closes the previous episode first. It
@@ -678,8 +783,9 @@ export async function reconcileStalledRoleRuns(store, delivery, now, selection,
         if (current.live !== "present" || current.stalled || !current.stallCandidate)
             continue;
         const { candidate, progressAt } = current;
-        const events = store.listEvents(candidate.task.id);
-        const previous = latestStallEvidenceKey(events, candidate.run.id);
+        const previous = foldPortPresent
+            ? store.getRunProgressFacts?.(candidate.task.id, candidate.run.id)?.latestStall
+            : latestStallEvidenceKey(store.listEvents(candidate.task.id), candidate.run.id);
         if (previous !== undefined
             && Date.parse(progressAt) > Date.parse(previous.progressAt)) {
             store.recordRoleRunProgress?.({

package/dist/scheduler/taskExecutionProjection.js

@@ -50,6 +50,17 @@ export function buildTaskExecutionProjection(store, taskId, taskOverride) {
         roleSessions
     });
 }
+/**
+ * Fold a Task projection from already-read facts. The Task overview reads each
+ * per-Task fact once and reuses it here, instead of letting
+ * buildTaskExecutionProjection read the store a second time for the same
+ * unchanged revision.
+ */
+export function projectTaskExecutionFromFacts(facts) {
+    const executionGroups = facts.executionGroups
+        ?? collectExecutionGroups(facts.workItems ?? [], facts.reviewRounds ?? []);
+    return projectTaskExecution({ ...facts, executionGroups });
+}
 /** Alias kept intentionally small for scheduler callers and external read models. */
 export const deriveTaskExecutionProjection = projectTaskExecution;
 export function projectTaskExecution(facts) {

package/dist/storage/compatibleTaskStore.js

@@ -1,9 +1,11 @@
-import { readFileSync } from "node:fs";
+import { existsSync, 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 { FileTaskStore, STORAGE_STATE_FILE, stateFileFingerprint, StorageRecordError, validateCurrentStorageStateSnapshot } from "./taskStore.js";
+import { SqliteTaskStore } from "./sqliteStore.js";
+import { COMMITTED_DATABASE_FILENAME } from "./upgrade/sqliteStateMigration.js";
+import { ensureStorageSchema, inspectStorageSchema, readStorageSchemaManifest, STORAGE_SCHEMA_FILE } from "./storageSchema.js";
 import { classifyHome } from "./upgrade/homeClassification.js";
 import { inspectSnapshotVersionState } from "./upgrade/homeMigrationTarget.js";
 import { latestStorageVersionState } from "./upgrade/recordVersions.js";
@@ -23,14 +25,52 @@ export function initializeCompatibleFileTaskStore(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.
+ *
+ * A current Home is opened from a single fingerprint-fenced `state.json`
+ * snapshot: the same bytes drive the record-version inspection, the strict
+ * shape/reference validation, and the returned store's initial cache seed, so
+ * the open never re-reads the (large) state merely to construct or first use
+ * the store.
  */
 export function openCompatibleFileTaskStore(home, options = {}) {
     const registry = options.registry ?? createProductionStorageRegistry();
     const latest = options.latest ?? latestStorageVersionState();
+    const schema = inspectStorageSchema(home);
+    // Issue 01: a layout-7 Home's authoritative backend is SQLite WAL. When
+    // `yui.db` exists, open it directly — never fall back to a FileTaskStore
+    // over a `state.json` that the repair may already have archived.
+    if (!options.forceStateSource
+        &&
+            (schema.status === "current" || schema.status === "unsupported")
+        && schema.currentLayoutVersion >= 7
+        && existsSync(join(home, COMMITTED_DATABASE_FILENAME))) {
+        return new SqliteTaskStore(home);
+    }
+    if (schema.status === "current") {
+        return openCurrentFileTaskStore(home, latest);
+    }
     const classification = classifyHome({ home, registry, latest });
     switch (classification.classification.status) {
         case "current":
-            return new FileTaskStore(home);
+        case "needs-storage-repair":
+            // A pseudo-layout-7 Home whose aggregate axis is also older cannot be
+            // normalized in memory: the compatible loader (requireCompatibleStorageSchema)
+            // only bypasses record-axis mismatches, not aggregate/layout ones. Such a
+            // Home needs the offline migration path (repair + aggregate migration in
+            // one upgrade), so surface the same migration-required error the pure
+            // version classifier would have produced, rather than a lazy strict-schema
+            // error from the first store read.
+            if (classification.classification.status === "needs-storage-repair"
+                && classification.aggregateVersion !== undefined
+                && classification.aggregateVersion < latest.aggregate) {
+                throw new StorageCompatibilityError("Storage requires an offline migration. Re-run `yui update` when active Sessions are clear.");
+            }
+            // A pseudo-layout-7 Home (manifest 7, no yui.db) may also carry
+            // compatible-old record versions, so open with the same normalization
+            // path as `compatible-old` rather than the strict current gate.
+            return new FileTaskStore(home, {
+                normalizeState: (raw) => normalizeState(home, raw, registry, latest)
+            });
         case "compatible-old":
             return new FileTaskStore(home, {
                 normalizeState: (raw) => normalizeState(home, raw, registry, latest)
@@ -41,13 +81,80 @@ export function openCompatibleFileTaskStore(home, options = {}) {
             throw new StorageCompatibilityError(describeUnsupported(classification.classification));
     }
 }
+/**
+ * The one-snapshot open for a Home whose manifest is already current. A single
+ * fingerprint-fenced read of `state.json` supplies:
+ *  - the record-version inspection (structural scan cross-checked against the
+ *    durable manifest, never the strict loader),
+ *  - the strict shape/reference validation (the store's own parser, run while
+ *    seeding its cache), and
+ *  - the returned store's initial cache seed under the same fingerprint.
+ *
+ * A fingerprint that drifts across the read retries once and then fails
+ * closed; a later external writer still invalidates the seeded cache on the
+ * store's next read. Corruption surfaces as the same `StorageCompatibilityError`
+ * diagnosis the classifier produced before this fast path existed.
+ */
+function openCurrentFileTaskStore(home, latest) {
+    const statePath = join(home, STORAGE_STATE_FILE);
+    if (!existsSync(statePath)) {
+        // No state.json yet: the store's own missing-file path seeds an empty
+        // state without reading anything.
+        return new FileTaskStore(home);
+    }
+    const manifest = readStorageSchemaManifest(home);
+    const snapshot = readFingerprintFencedState(statePath);
+    let parsed;
+    try {
+        parsed = JSON.parse(snapshot.raw);
+    }
+    catch (error) {
+        throw new StorageCompatibilityError(`Invalid state.json: state.json is not valid JSON: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    if (!isRecord(parsed)) {
+        throw new StorageCompatibilityError("Invalid state.json: state.json is not a JSON object.");
+    }
+    const inspection = inspectSnapshotVersionState(Object.freeze({ schemaManifest: manifest, state: parsed }), latest);
+    if ("corruption" in inspection) {
+        throw new StorageCompatibilityError(`Invalid state.json: ${inspection.corruption.detail}`);
+    }
+    try {
+        return new FileTaskStore(home, {
+            initialStateSnapshot: { fingerprint: snapshot.fingerprint, raw: snapshot.raw }
+        });
+    }
+    catch (error) {
+        if (error instanceof StorageRecordError) {
+            throw new StorageCompatibilityError(`Invalid state.json: ${error.message}`);
+        }
+        throw error;
+    }
+}
+/**
+ * Read `state.json` once, fenced by the same fingerprint the store's read cache
+ * is keyed on. A fingerprint that changes between the before and after stat
+ * means a concurrent writer is mid-update: retry once (bounded), then fail
+ * closed rather than seed a store from bytes that may be torn.
+ */
+export function readFingerprintFencedState(statePath, io = {}) {
+    const fingerprint = io.fingerprint ?? stateFileFingerprint;
+    const read = io.read ?? ((path) => readFileSync(path, "utf8"));
+    for (let attempt = 0; attempt < 2; attempt += 1) {
+        const before = fingerprint(statePath);
+        const raw = read(statePath);
+        const after = fingerprint(statePath);
+        if (before === after)
+            return { raw, fingerprint: after };
+    }
+    throw new StorageCompatibilityError("state.json changed while opening; a concurrent writer is updating the Home. Retry the command.");
+}
 /**
  * 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();
+    openCompatibleFileTaskStore(home, { ...options, forceStateSource: true }).getConfig();
 }
 function normalizeState(home, raw, registry, latest) {
     let state;