@voybio/ace-swarm 0.2.4 → 2.4.0

package/dist/store/state-reader.js

@@ -58,6 +58,25 @@ export class StoreStateReader {
             r.localModelRuntime.listRuntimeStatuses(),
             r.vericify.list(),
         ]);
+        // Phase 2: fetch transition log for the live session (needs runtimeStatuses from phase 1)
+        const liveStatus = runtimeStatuses.find((s) => {
+            try {
+                process.kill(s.process_id, 0);
+                return true;
+            }
+            catch {
+                return false;
+            }
+        });
+        let recentTransitions = [];
+        if (liveStatus?.session_id) {
+            try {
+                recentTransitions = await r.localModelRuntime.getTransitionLog(liveStatus.session_id, 15);
+            }
+            catch {
+                recentTransitions = [];
+            }
+        }
         return {
             handoffs,
             todos,
@@ -70,6 +89,7 @@ export class StoreStateReader {
             providers,
             runtimeStatuses,
             posts,
+            recentTransitions,
             snapped_at: Date.now(),
         };
     }

package/dist/store/store-artifacts.d.ts

@@ -1,3 +1,4 @@
+import { type StoreWriteCoordinatorOptions } from "./write-coordinator.js";
 export declare const OPERATIONAL_ARTIFACT_REL_PATHS: Set<string>;
 export declare function operationalArtifactKey(relPath: string): string;
 export declare function isOperationalArtifactPath(relPath: string): boolean;
@@ -9,4 +10,10 @@ export declare function writeStoreBlobsSync(workspaceRoot: string, blobs: Readon
 }>): string[];
 export declare function writeStoreBlobSync(workspaceRoot: string, key: string, content: string): string;
 export declare function writeOperationalArtifactSync(workspaceRoot: string, relPath: string, content: string): string;
+export declare function writeStoreBlobsQueued(workspaceRoot: string, blobs: ReadonlyArray<{
+    key: string;
+    content: string;
+}>, options?: StoreWriteCoordinatorOptions): Promise<string[]>;
+export declare function writeStoreBlobQueued(workspaceRoot: string, key: string, content: string, options?: StoreWriteCoordinatorOptions): Promise<string>;
+export declare function writeOperationalArtifactQueued(workspaceRoot: string, relPath: string, content: string, options?: StoreWriteCoordinatorOptions): Promise<string>;
 //# sourceMappingURL=store-artifacts.d.ts.map

package/dist/store/store-artifacts.js

@@ -1,6 +1,8 @@
 import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync, } from "node:fs";
 import { dirname } from "node:path";
-import { getWorkspaceStorePath, readStoreBlobSync, toVirtualStorePath } from "./store-snapshot.js";
+import { openStore } from "./ace-packed-store.js";
+import { getWorkspaceStorePath, invalidateStoreSnapshotCache, readStoreBlobSync, toVirtualStorePath, } from "./store-snapshot.js";
+import { withStoreWriteCoordinator } from "./write-coordinator.js";
 import { HEADER_SIZE, HEADER_SIZE_V1, STORE_VERSION, MAGIC } from "./types.js";
 // ── v2 header constants (mirrors ace-packed-store.ts) ─────────────────────────
 const H_KV_IDX_OFF = 16;
@@ -191,6 +193,7 @@ export function writeStoreBlobsSync(workspaceRoot, blobs) {
     const tmpPath = `${storePath}.${process.pid}.${Date.now()}.tmp`;
     writeFileSync(tmpPath, output);
     renameSync(tmpPath, storePath);
+    invalidateStoreSnapshotCache(storePath);
     return blobs.map(({ key }) => toVirtualStorePath(storePath, key));
 }
 export function writeStoreBlobSync(workspaceRoot, key, content) {
@@ -199,4 +202,27 @@ export function writeStoreBlobSync(workspaceRoot, key, content) {
 export function writeOperationalArtifactSync(workspaceRoot, relPath, content) {
     return writeStoreBlobSync(workspaceRoot, operationalArtifactKey(relPath), content);
 }
+export async function writeStoreBlobsQueued(workspaceRoot, blobs, options = {}) {
+    const storePath = getWorkspaceStorePath(workspaceRoot);
+    return withStoreWriteCoordinator(storePath, async () => {
+        const store = await openStore(storePath);
+        try {
+            for (const { key, content } of blobs) {
+                await store.setBlob(key, content);
+            }
+            await store.commit();
+            return blobs.map(({ key }) => toVirtualStorePath(storePath, key));
+        }
+        finally {
+            await store.close();
+        }
+    }, { ...options, operation_label: options.operation_label ?? "writeStoreBlobsQueued" });
+}
+export async function writeStoreBlobQueued(workspaceRoot, key, content, options = {}) {
+    const [path] = await writeStoreBlobsQueued(workspaceRoot, [{ key, content }], options);
+    return path;
+}
+export async function writeOperationalArtifactQueued(workspaceRoot, relPath, content, options = {}) {
+    return writeStoreBlobQueued(workspaceRoot, operationalArtifactKey(relPath), content, options);
+}
 //# sourceMappingURL=store-artifacts.js.map

package/dist/store/store-authority-audit.d.ts

@@ -1,22 +1,39 @@
 export declare const STORE_AUTHORITY_AUDIT_REPORT_REL_PATH = "agent-state/STORE_AUTHORITY_AUDIT.md";
 export type StoreAuthorityClassification = "canonical knowledge artifact" | "canonical runtime state" | "projection only";
+export type StoreAuthorityTopologyClassification = "runtime_hot_path_sync_writer" | "async_handler_sync_writer" | "allowed_offline_sync_writer" | "store_backed_possible" | "non_blocking";
+export type StoreAuthorityCallName = "safeWrite" | "safeWriteWorkspaceFile" | "safeWriteReport" | "withStoreWriteCoordinatorSync" | "writeStoreBlobSync" | "writeStoreBlobsSync" | "appendStatusEvent" | "createWorkspaceSession";
+export interface StoreAuthorityTopologyFlags {
+    runtime_hot_path: boolean;
+    async_handler: boolean;
+    store_backed_possible: boolean;
+    allowed_offline_sync: boolean;
+    must_migrate_to_async: boolean;
+}
 export interface StoreAuthoritySafeWriteSite {
-    call: "safeWrite" | "safeWriteWorkspaceFile" | "safeWriteReport";
+    call: StoreAuthorityCallName;
     classification: StoreAuthorityClassification;
     file: string;
     line: number;
     column: number;
+    enclosing_function?: string;
+    enclosing_function_is_async: boolean;
     target_expression: string;
     target_path?: string;
     fallback_keys: string[];
     bypasses_acepack: boolean;
     regenerable_from_store: boolean;
+    topology: StoreAuthorityTopologyFlags;
+    topology_classification: StoreAuthorityTopologyClassification;
+    blocking: boolean;
+    failure_condition: string;
     note: string;
 }
 export interface StoreAuthorityAuditResult {
     bypassing_sites: StoreAuthoritySafeWriteSite[];
+    blocking_sites: StoreAuthoritySafeWriteSite[];
     classifications: Record<StoreAuthorityClassification, StoreAuthoritySafeWriteSite[]>;
     generated_at: string;
+    topology_failure: boolean;
     non_regenerable_projections: StoreAuthoritySafeWriteSite[];
     report_path: string;
     runtime_files_without_store_fallback_keys: StoreAuthoritySafeWriteSite[];

package/dist/store/store-authority-audit.js

@@ -7,8 +7,32 @@ import { OPERATIONAL_ARTIFACT_REL_PATHS, operationalArtifactKey } from "./store-
 export const STORE_AUTHORITY_AUDIT_REPORT_REL_PATH = "agent-state/STORE_AUTHORITY_AUDIT.md";
 const PACKAGE_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..", "..");
 const SRC_ROOT = resolve(PACKAGE_ROOT, "src");
-const TARGET_CALLS = new Set(["safeWrite", "safeWriteWorkspaceFile", "safeWriteReport"]);
+const TARGET_CALLS = new Set([
+    "safeWrite",
+    "safeWriteWorkspaceFile",
+    "safeWriteReport",
+    "withStoreWriteCoordinatorSync",
+    "writeStoreBlobSync",
+    "writeStoreBlobsSync",
+    "appendStatusEvent",
+    "createWorkspaceSession",
+]);
 const SKIPPED_INTERNAL_FUNCTIONS = new Set(["safeWriteWorkspaceFile", "safeWriteReport"]);
+const OFFLINE_SYNC_HELPER_SOURCES = new Set([
+    "src/helpers/store-resolution.ts",
+    "src/store/store-artifacts.ts",
+    "src/store/write-coordinator.ts",
+    "src/runtime-executor.ts",
+    "src/status-events.ts",
+    "src/run-ledger.ts",
+    "src/handoff-registry.ts",
+    "src/workspace-manager.ts",
+    "src/job-scheduler.ts",
+    "src/astgrep-index.ts",
+    "src/index-store.ts",
+    "src/tools-files.ts",
+]);
+const TOOL_RUNTIME_SOURCE_HINT = /(?:^|\/)(?:tools-[^/]+|tools-framework|runtime-[^/]+|tracker-[^/]+|workspace-manager|status-events|job-scheduler|run-ledger|runtime-profile|handoff-registry|astgrep-index)\.ts$/;
 const TASK_KEY_TO_FILE = {
     todo: "todo.md",
     role_tasks: "role_tasks.md",
@@ -74,6 +98,9 @@ function functionName(node) {
         return undefined;
     return undefined;
 }
+function hasAsyncModifier(node) {
+    return node.modifiers?.some((modifier) => modifier.kind === ts.SyntaxKind.AsyncKeyword) ?? false;
+}
 function callName(node) {
     const expr = node.expression;
     if (ts.isIdentifier(expr))
@@ -82,6 +109,70 @@ function callName(node) {
         return expr.name.text;
     return undefined;
 }
+function isRuntimeHotPathSource(relativeSource) {
+    return TOOL_RUNTIME_SOURCE_HINT.test(relativeSource);
+}
+function isOfflineSyncAllowedSource(relativeSource) {
+    return OFFLINE_SYNC_HELPER_SOURCES.has(relativeSource);
+}
+function classifyTopology(sourcePath, currentFunction, currentFunctionIsAsync, callName, resolved) {
+    const relativeSource = normalizeAuditPath(relative(PACKAGE_ROOT, sourcePath));
+    const runtimeHotPath = isRuntimeHotPathSource(relativeSource) ||
+        (currentFunction ? /(?:runtime|session|workspace|status|tracker|tool|handler|executor|lifecycle|scheduler|ledger)/i.test(currentFunction) : false) ||
+        currentFunctionIsAsync ||
+        callName === "createWorkspaceSession" ||
+        callName === "appendStatusEvent";
+    const asyncHandler = currentFunctionIsAsync &&
+        (isServerToolHandlerFromSource(sourcePath, currentFunction) || /(?:handler|tool|callback|command|action|task)/i.test(currentFunction ?? ""));
+    const allowedOfflineSync = isOfflineSyncAllowedSource(relativeSource) ||
+        (relativeSource === "src/status-events.ts" && currentFunction === "appendStatusEventSafe");
+    const storeBackedPossible = callName === "safeWrite" ||
+        callName === "safeWriteWorkspaceFile" ||
+        callName === "safeWriteReport" ||
+        callName === "withStoreWriteCoordinatorSync" ||
+        callName === "writeStoreBlobSync" ||
+        callName === "writeStoreBlobsSync" ||
+        callName === "appendStatusEvent" ||
+        callName === "createWorkspaceSession" ||
+        resolved.fallbackKeys.length > 0;
+    const mustMigrateToAsync = storeBackedPossible && !allowedOfflineSync && (runtimeHotPath || asyncHandler);
+    const blocking = runtimeHotPath && mustMigrateToAsync;
+    const classification = blocking
+        ? "runtime_hot_path_sync_writer"
+        : asyncHandler && mustMigrateToAsync
+            ? "async_handler_sync_writer"
+            : allowedOfflineSync
+                ? "allowed_offline_sync_writer"
+                : storeBackedPossible
+                    ? "store_backed_possible"
+                    : "non_blocking";
+    return {
+        flags: {
+            runtime_hot_path: runtimeHotPath,
+            async_handler: asyncHandler,
+            store_backed_possible: storeBackedPossible,
+            allowed_offline_sync: allowedOfflineSync,
+            must_migrate_to_async: mustMigrateToAsync,
+        },
+        classification,
+        blocking,
+        failure_condition: mustMigrateToAsync
+            ? "runtime_hot_path && store_backed_possible && !allowed_offline_sync"
+            : "no blocking migration required",
+        note: blocking
+            ? "production runtime hot path still reaches a sync store-backed writer"
+            : allowedOfflineSync
+                ? "sync writer is an allowed offline/library-local helper"
+                : storeBackedPossible
+                    ? "store-backed sync surface is present but not currently blocking"
+                    : "non-store topology site",
+    };
+}
+function isServerToolHandlerFromSource(sourcePath, currentFunction) {
+    if (!currentFunction)
+        return false;
+    return /(?:tools-|runtime-|tracker-|workspace-manager|status-events|job-scheduler|run-ledger|runtime-profile|handoff-registry|astgrep-index)/.test(normalizeAuditPath(relative(PACKAGE_ROOT, sourcePath)));
+}
 function collectResolvableConstants(root, sourceFile, inherited) {
     const constants = new Map(inherited);
     const pending = [];
@@ -325,18 +416,20 @@ function scanSourceFile(sourcePath) {
     const raw = readFileSync(sourcePath, "utf-8");
     const sourceFile = ts.createSourceFile(sourcePath, raw, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS);
     const sites = [];
-    const scanNode = (node, inheritedConstants, currentFunction) => {
+    const scanNode = (node, inheritedConstants, currentFunction, currentFunctionIsAsync = false) => {
         if (node !== sourceFile && isFunctionLike(node)) {
             const name = functionName(node) ?? currentFunction;
             const constants = collectResolvableConstants(node, sourceFile, inheritedConstants);
+            const isAsync = hasAsyncModifier(node);
             if (node.body) {
-                ts.forEachChild(node.body, (child) => scanNode(child, constants, name));
+                ts.forEachChild(node.body, (child) => scanNode(child, constants, name, isAsync));
             }
             return;
         }
         if (ts.isCallExpression(node)) {
             const name = callName(node);
             if (name && TARGET_CALLS.has(name)) {
+                const call = name;
                 if (currentFunction && SKIPPED_INTERNAL_FUNCTIONS.has(currentFunction) && name === "safeWrite") {
                     return;
                 }
@@ -344,22 +437,29 @@ function scanSourceFile(sourcePath) {
                 const targetPath = firstArg ? resolveExpression(firstArg, sourceFile, inheritedConstants) : undefined;
                 const resolved = classifyTarget(targetPath);
                 const location = formatLocation(sourceFile, node);
+                const topology = classifyTopology(sourcePath, currentFunction, currentFunctionIsAsync, call, resolved);
                 sites.push({
-                    call: name,
+                    call,
                     classification: resolved.classification,
                     file: normalizeAuditPath(relative(PACKAGE_ROOT, sourcePath)),
                     line: location.line,
                     column: location.column,
+                    enclosing_function: currentFunction,
+                    enclosing_function_is_async: currentFunctionIsAsync,
                     target_expression: firstArg ? firstArg.getText(sourceFile) : "",
                     target_path: resolved.canonicalTarget,
                     fallback_keys: resolved.fallbackKeys,
                     bypasses_acepack: resolved.bypassesAcepack,
                     regenerable_from_store: resolved.regenerableFromStore,
+                    topology: topology.flags,
+                    topology_classification: topology.classification,
+                    blocking: topology.blocking,
+                    failure_condition: topology.failure_condition,
                     note: resolved.note,
                 });
             }
         }
-        ts.forEachChild(node, (child) => scanNode(child, inheritedConstants, currentFunction));
+        ts.forEachChild(node, (child) => scanNode(child, inheritedConstants, currentFunction, currentFunctionIsAsync));
     };
     const fileConstants = collectResolvableConstants(sourceFile, sourceFile, new Map());
     ts.forEachChild(sourceFile, (child) => scanNode(child, fileConstants));
@@ -377,11 +477,14 @@ export function auditStoreAuthority() {
     const classifications = groupByClassification(safeWriteSites);
     const runtimeFilesWithoutStoreFallbackKeys = safeWriteSites.filter((site) => site.bypasses_acepack);
     const nonRegenerableProjections = safeWriteSites.filter((site) => site.classification === "projection only" && !site.regenerable_from_store);
+    const blockingSites = safeWriteSites.filter((site) => site.blocking);
     const report_path = STORE_AUTHORITY_AUDIT_REPORT_REL_PATH;
     return {
         bypassing_sites: runtimeFilesWithoutStoreFallbackKeys,
+        blocking_sites: blockingSites,
         classifications,
         generated_at: new Date().toISOString(),
+        topology_failure: blockingSites.length > 0,
         non_regenerable_projections: nonRegenerableProjections,
         report_path,
         runtime_files_without_store_fallback_keys: runtimeFilesWithoutStoreFallbackKeys,
@@ -408,6 +511,9 @@ function renderSites(label, sites) {
         lines.push(`  - target: ${site.target_path ? `\`${site.target_path}\`` : "unresolved"}`);
         lines.push(`  - fallback keys: ${site.fallback_keys.length > 0 ? site.fallback_keys.map((key) => `\`${key}\``).join(", ") : "none"}`);
         lines.push(`  - classification: \`${site.classification}\``);
+        lines.push(`  - topology: \`${site.topology_classification}\``);
+        lines.push(`  - flags: runtime_hot_path=${site.topology.runtime_hot_path}, async_handler=${site.topology.async_handler}, store_backed_possible=${site.topology.store_backed_possible}, allowed_offline_sync=${site.topology.allowed_offline_sync}, must_migrate_to_async=${site.topology.must_migrate_to_async}`);
+        lines.push(`  - failure condition: ${site.failure_condition}`);
         lines.push(`  - note: ${site.note}`);
     }
     return lines;
@@ -422,12 +528,16 @@ export function renderStoreAuthorityAuditReport(result) {
         "",
         "## Summary",
         `- bypassing ACEPACK: ${result.bypassing_sites.length}`,
+        `- blocking runtime hot-path writers: ${result.blocking_sites.length}`,
+        `- topology failure: ${result.topology_failure ? "yes" : "no"}`,
         `- runtime files without store fallback keys: ${result.runtime_files_without_store_fallback_keys.length}`,
         `- non-regenerable projections: ${result.non_regenerable_projections.length}`,
         `- canonical knowledge artifacts: ${result.classifications["canonical knowledge artifact"].length}`,
         `- canonical runtime state writers: ${result.classifications["canonical runtime state"].length}`,
         `- projection-only writers: ${result.classifications["projection only"].length}`,
         "",
+        ...renderSites("Blocking Runtime Hot-Path Writers", result.blocking_sites),
+        "",
         ...renderSites("Writers Bypassing ACEPACK", result.bypassing_sites),
         "",
         ...renderSites("Runtime Files Without Store Fallback Keys", result.runtime_files_without_store_fallback_keys),

package/dist/store/store-snapshot.d.ts

@@ -1,3 +1,6 @@
+export declare function invalidateStoreSnapshotCache(storePath?: string): void;
+export declare function getCanonicalWorkspaceStorePath(workspaceRoot: string): string;
+export declare function getLegacyWorkspaceStorePath(workspaceRoot: string): string;
 export declare function getWorkspaceStorePath(workspaceRoot: string): string;
 export declare function storeExistsSync(workspaceRoot: string): boolean;
 export declare function readStoreBlobSync(workspaceRoot: string, key: string): string | undefined;

package/dist/store/store-snapshot.js

@@ -3,6 +3,13 @@ import { resolve } from "node:path";
 import { HEADER_SIZE, MAGIC } from "./types.js";
 const DECODE = new TextDecoder();
 let cached;
+export function invalidateStoreSnapshotCache(storePath) {
+    if (!cached)
+        return;
+    if (!storePath || cached.path === storePath) {
+        cached = undefined;
+    }
+}
 function bytesToUint32(bytes, offset = 0) {
     return new DataView(bytes.buffer, bytes.byteOffset).getUint32(offset, false);
 }
@@ -47,12 +54,25 @@ function loadSnapshot(storePath) {
         return cached;
     }
     catch {
-        return cached?.path === storePath ? cached : undefined;
+        invalidateStoreSnapshotCache(storePath);
+        return undefined;
     }
 }
-export function getWorkspaceStorePath(workspaceRoot) {
+export function getCanonicalWorkspaceStorePath(workspaceRoot) {
+    return resolve(workspaceRoot, "agent-state", "ace-state.ace");
+}
+export function getLegacyWorkspaceStorePath(workspaceRoot) {
     return resolve(workspaceRoot, ".agents", "ACE", "ace-state.ace");
 }
+export function getWorkspaceStorePath(workspaceRoot) {
+    const canonicalPath = getCanonicalWorkspaceStorePath(workspaceRoot);
+    if (existsSync(canonicalPath))
+        return canonicalPath;
+    const legacyPath = getLegacyWorkspaceStorePath(workspaceRoot);
+    if (existsSync(legacyPath))
+        return legacyPath;
+    return canonicalPath;
+}
 export function storeExistsSync(workspaceRoot) {
     return existsSync(getWorkspaceStorePath(workspaceRoot));
 }

package/dist/store/workspace-store-paths.d.ts

@@ -0,0 +1,39 @@
+/**
+ * workspace-store-paths.ts
+ *
+ * Central resolver and adoption helper for the ACE canonical/legacy store transition.
+ *
+ * Contract:
+ *  - canonical: agent-state/ace-state.ace  (new and adopted workspaces)
+ *  - legacy:    .agents/ACE/ace-state.ace   (older workspaces; supported input, not a write target)
+ *
+ * Every command that opens ACEPACK must use this module. No command should
+ * assemble .agents/ACE/ace-state.ace by hand.
+ */
+export interface WorkspaceStoreResolution {
+    storePath: string;
+    canonicalPath: string;
+    legacyPath: string;
+    mode: "canonical" | "legacy_fallback" | "adopted_legacy" | "dual_store_conflict" | "missing";
+    warnings: string[];
+}
+/**
+ * Read-safe, non-mutating resolver. Reports the active store path and whether
+ * legacy also exists. Does not copy or seed any files.
+ */
+export declare function resolveWorkspaceStorePath(workspaceRoot: string): WorkspaceStoreResolution;
+/**
+ * Mutating resolver. Use before any command that writes to the store.
+ *
+ * Adoption behaviour:
+ *  - canonical only        → return canonical
+ *  - canonical + legacy identical → return canonical with low-severity warning
+ *  - canonical + legacy differ    → return dual_store_conflict (caller decides how to handle)
+ *  - legacy only           → copy legacy to canonical atomically, return adopted_legacy
+ *  - neither               → return missing (caller seeds a fresh store)
+ */
+export declare function ensureCanonicalWorkspaceStore(workspaceRoot: string, options?: {
+    operationLabel?: string;
+    allowDualStoreConflict?: boolean;
+}): Promise<WorkspaceStoreResolution>;
+//# sourceMappingURL=workspace-store-paths.d.ts.map

package/dist/store/workspace-store-paths.js

@@ -0,0 +1,94 @@
+/**
+ * workspace-store-paths.ts
+ *
+ * Central resolver and adoption helper for the ACE canonical/legacy store transition.
+ *
+ * Contract:
+ *  - canonical: agent-state/ace-state.ace  (new and adopted workspaces)
+ *  - legacy:    .agents/ACE/ace-state.ace   (older workspaces; supported input, not a write target)
+ *
+ * Every command that opens ACEPACK must use this module. No command should
+ * assemble .agents/ACE/ace-state.ace by hand.
+ */
+import { existsSync, readFileSync, copyFileSync, mkdirSync } from "node:fs";
+import { dirname } from "node:path";
+import { getCanonicalWorkspaceStorePath, getLegacyWorkspaceStorePath, } from "./store-snapshot.js";
+import { withStoreWriteCoordinator } from "./write-coordinator.js";
+/**
+ * Read-safe, non-mutating resolver. Reports the active store path and whether
+ * legacy also exists. Does not copy or seed any files.
+ */
+export function resolveWorkspaceStorePath(workspaceRoot) {
+    const canonicalPath = getCanonicalWorkspaceStorePath(workspaceRoot);
+    const legacyPath = getLegacyWorkspaceStorePath(workspaceRoot);
+    const hasCanonical = existsSync(canonicalPath);
+    const hasLegacy = existsSync(legacyPath);
+    const warnings = [];
+    if (hasCanonical && hasLegacy) {
+        const canonicalBytes = readFileSync(canonicalPath);
+        const legacyBytes = readFileSync(legacyPath);
+        const identical = canonicalBytes.equals(legacyBytes);
+        if (identical) {
+            warnings.push(`Legacy store ${legacyPath} is byte-identical to canonical store. Legacy is redundant and can be removed.`);
+            return { storePath: canonicalPath, canonicalPath, legacyPath, mode: "canonical", warnings };
+        }
+        warnings.push(`Dual ACE stores detected. Canonical: ${canonicalPath} | Legacy: ${legacyPath}. They differ — use 'ace repair' to resolve.`);
+        return {
+            storePath: canonicalPath,
+            canonicalPath,
+            legacyPath,
+            mode: "dual_store_conflict",
+            warnings,
+        };
+    }
+    if (hasCanonical) {
+        return { storePath: canonicalPath, canonicalPath, legacyPath, mode: "canonical", warnings };
+    }
+    if (hasLegacy) {
+        return {
+            storePath: legacyPath,
+            canonicalPath,
+            legacyPath,
+            mode: "legacy_fallback",
+            warnings,
+        };
+    }
+    return { storePath: canonicalPath, canonicalPath, legacyPath, mode: "missing", warnings };
+}
+/**
+ * Mutating resolver. Use before any command that writes to the store.
+ *
+ * Adoption behaviour:
+ *  - canonical only        → return canonical
+ *  - canonical + legacy identical → return canonical with low-severity warning
+ *  - canonical + legacy differ    → return dual_store_conflict (caller decides how to handle)
+ *  - legacy only           → copy legacy to canonical atomically, return adopted_legacy
+ *  - neither               → return missing (caller seeds a fresh store)
+ */
+export async function ensureCanonicalWorkspaceStore(workspaceRoot, options) {
+    const label = options?.operationLabel ?? "ensureCanonicalWorkspaceStore";
+    const resolution = resolveWorkspaceStorePath(workspaceRoot);
+    if (resolution.mode === "legacy_fallback") {
+        // Adopt: copy legacy into canonical atomically under write coordinator.
+        const { canonicalPath, legacyPath } = resolution;
+        await withStoreWriteCoordinator(canonicalPath, async () => {
+            // Re-check after acquiring the write lock — another process may have adopted already.
+            if (!existsSync(canonicalPath)) {
+                mkdirSync(dirname(canonicalPath), { recursive: true });
+                copyFileSync(legacyPath, canonicalPath);
+            }
+        }, { operation_label: `${label}:adopt_legacy` });
+        const warnings = [
+            `Legacy store adopted: copied ${legacyPath} → ${canonicalPath}. Legacy file retained as fallback.`,
+        ];
+        return {
+            storePath: canonicalPath,
+            canonicalPath,
+            legacyPath,
+            mode: "adopted_legacy",
+            warnings,
+        };
+    }
+    return resolution;
+}
+//# sourceMappingURL=workspace-store-paths.js.map

package/dist/store/write-coordinator.d.ts

@@ -0,0 +1,65 @@
+export interface StoreWriteCoordinatorOptions {
+    agent_id?: string;
+    emit_lifecycle_events?: boolean;
+    lifecycle_sink?: (event: StoreWriteLifecycleEvent) => void;
+    operation_label?: string;
+    wait_ms?: number;
+    poll_interval_ms?: number;
+    lease_ttl_ms?: number;
+    stale_grace_ms?: number;
+}
+export interface StoreWriteLeaseInfo {
+    token: string;
+    storePath: string;
+    lockPath: string;
+    metadataPath: string;
+    pid: number;
+    hostname: string;
+    agentId?: string;
+    operationLabel?: string;
+    acquiredAt: string;
+    expiresAt: string;
+    ttlMs: number;
+    waitedMs: number;
+}
+export type StoreWriteLifecycleEventType = "store-write-requested" | "store-write-accepted" | "store-write-started" | "store-write-committed" | "store-write-blocked" | "store-write-failed";
+export interface StoreWriteLifecycleEvent {
+    event: StoreWriteLifecycleEventType;
+    storePath: string;
+    operationLabel?: string;
+    hostname: string;
+    pid: number;
+    timestamp: string;
+    waitedMs?: number;
+    currentHolder?: StoreWriteLeaseInfo;
+    error?: string;
+    asyncOwnership?: {
+        count: number;
+        operationLabels: string[];
+    };
+}
+export declare class StoreWriteLeaseBusyError extends Error {
+    readonly storePath: string;
+    readonly lockPath: string;
+    readonly waitedMs: number;
+    readonly currentHolder?: StoreWriteLeaseInfo;
+    constructor(input: {
+        storePath: string;
+        lockPath: string;
+        waitedMs: number;
+        currentHolder?: StoreWriteLeaseInfo;
+    });
+}
+export declare class StoreSyncWriteBlockedByAsyncLeaseError extends Error {
+    readonly code = "STORE_SYNC_WRITE_BLOCKED_BY_ASYNC_LEASE";
+    readonly storePath: string;
+    readonly currentAsyncOperationLabels: string[];
+    constructor(input: {
+        storePath: string;
+        currentAsyncOperationLabels: string[];
+    });
+}
+export declare function withStoreWriteCoordinator<T>(storePath: string, fn: () => Promise<T>, options?: StoreWriteCoordinatorOptions): Promise<T>;
+export declare function withStoreWriteCoordinatorSync<T>(storePath: string, fn: () => T, options?: StoreWriteCoordinatorOptions): T;
+export declare function resolveStoreWriteLeasePath(workspaceRoot: string): string;
+//# sourceMappingURL=write-coordinator.d.ts.map