@voybio/ace-swarm 2.4.4 → 2.4.6

package/dist/store/store-artifacts.js

@@ -1,9 +1,10 @@
 import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync, } from "node:fs";
 import { dirname } from "node:path";
 import { openStore } from "./ace-packed-store.js";
-import { getWorkspaceStorePath, invalidateStoreSnapshotCache, readStoreBlobSync, toVirtualStorePath, } from "./store-snapshot.js";
+import { getWorkspaceStorePath, invalidateStoreSnapshotCache, readStoreBlobSync, toVirtualStorePath, validateChunkBounds, } from "./store-snapshot.js";
 import { withStoreWriteCoordinator } from "./write-coordinator.js";
 import { HEADER_SIZE, HEADER_SIZE_V1, STORE_VERSION, MAGIC } from "./types.js";
+import { crc32 } from "./crc32.js";
 // ── v2 header constants (mirrors ace-packed-store.ts) ─────────────────────────
 const H_KV_IDX_OFF = 16;
 const H_KV_IDX_LEN = 24;
@@ -125,6 +126,29 @@ function defaultStoreBuffer() {
     buf.set(indexBytes, kvIdxOff);
     return buf;
 }
+/**
+ * Validates the structural invariants of a parsed v2 header before any code
+ * splices bytes out of the file using it. A corrupt header (e.g. kvChunkEnd
+ * pointing past EOF) must never be trusted to build a new file — that would
+ * bake a zero-filled/garbage region into the *new* store and spread
+ * corruption to every key, not just the bad one.
+ */
+function validateStoreHeaderInvariants(hdr, index, fileLength) {
+    if (!(HEADER_SIZE <= hdr.kvChunkEnd && hdr.kvChunkEnd <= hdr.evtOffset && hdr.evtOffset <= hdr.kvIndexOffset && hdr.kvIndexOffset <= fileLength)) {
+        return `header region ordering invalid (kvChunkEnd=${hdr.kvChunkEnd}, evtOffset=${hdr.evtOffset}, kvIndexOffset=${hdr.kvIndexOffset}, fileLength=${fileLength})`;
+    }
+    for (const [key, entry] of Object.entries(index)) {
+        if (!validateChunkBounds(entry, hdr.kvChunkEnd, HEADER_SIZE)) {
+            return `index entry '${key}' out of KV region bounds (offset=${entry.offset}, length=${entry.length}, kvChunkEnd=${hdr.kvChunkEnd})`;
+        }
+    }
+    return undefined;
+}
+function quarantineCorruptStore(storePath, rawFile) {
+    const quarantinePath = `${storePath}.corrupt-${Date.now()}`;
+    writeFileSync(quarantinePath, rawFile);
+    return quarantinePath;
+}
 function readStoreBuffer(storePath) {
     const rawFile = existsSync(storePath) ? readFileSync(storePath) : defaultStoreBuffer();
     // Buffer (from readFileSync) is a Uint8Array subclass — wrap to get a plain Uint8Array view
@@ -135,11 +159,25 @@ function readStoreBuffer(storePath) {
         return { file: def, kvChunkEnd: HEADER_SIZE, evtBytes: new Uint8Array(4), evtCount: 0, evtBaseId: 0, index: {} };
     }
     const hdr = readStoreHeader(file.subarray(0, Math.max(HEADER_SIZE, hdrSize)));
+    if (hdr.kvIndexOffset < 0 ||
+        hdr.kvIndexLength < 0 ||
+        hdr.kvIndexOffset + hdr.kvIndexLength > file.length ||
+        hdr.evtOffset < 0 ||
+        hdr.evtLength < 0 ||
+        hdr.evtOffset + hdr.evtLength > file.length) {
+        const quarantinePath = quarantineCorruptStore(storePath, rawFile);
+        throw new Error(`AcePackedStore artifact write refused: header region exceeds file bounds — quarantined corrupt store at ${quarantinePath}, original left in place. Run 'ace repair' or 'ace fsck --repair'.`);
+    }
     const evtBytes = hdr.evtLength > 0
         ? file.slice(hdr.evtOffset, hdr.evtOffset + hdr.evtLength)
         : new Uint8Array(4); // empty event section
     const indexRaw = file.subarray(hdr.kvIndexOffset, hdr.kvIndexOffset + hdr.kvIndexLength);
     const index = JSON.parse(DECODE.decode(indexRaw));
+    const invariantError = validateStoreHeaderInvariants(hdr, index, file.length);
+    if (invariantError) {
+        const quarantinePath = quarantineCorruptStore(storePath, rawFile);
+        throw new Error(`AcePackedStore artifact write refused: ${invariantError} — quarantined corrupt store at ${quarantinePath}, original left in place. Run 'ace repair' or 'ace fsck --repair'.`);
+    }
     return { file, kvChunkEnd: hdr.kvChunkEnd, evtBytes, evtCount: hdr.evtCount, evtBaseId: hdr.evtBaseId, index };
 }
 export function operationalArtifactKey(relPath) {
@@ -169,7 +207,11 @@ export function writeStoreBlobsSync(workspaceRoot, blobs) {
     const nextIndex = { ...index };
     let cursor = kvChunkEnd;
     for (const entry of encoded) {
-        nextIndex[entry.key] = { offset: cursor, length: entry.contentBytes.length };
+        nextIndex[entry.key] = {
+            offset: cursor,
+            length: entry.contentBytes.length,
+            crc: crc32(entry.contentBytes),
+        };
         cursor += 4 + entry.contentBytes.length;
     }
     const indexBytes = TEXT.encode(JSON.stringify(nextIndex));

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

@@ -31,6 +31,7 @@ const OFFLINE_SYNC_HELPER_SOURCES = new Set([
     "src/astgrep-index.ts",
     "src/index-store.ts",
     "src/tools-files.ts",
+    "src/source-mutation-coordinator.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 = {

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

@@ -0,0 +1,30 @@
+export interface StoreLsEntry {
+    /** Logical path as a user would recognize it (e.g. "agent-state/kanban.json"), or the raw key with --keys. */
+    path: string;
+    key: string;
+    bytes: number;
+}
+export declare function listStoreEntries(workspaceRoot: string, prefix?: string, useRawKeys?: boolean): StoreLsEntry[];
+export declare function runLsCommand(workspaceRoot: string, args: string[]): Promise<void>;
+export interface ReadTarget {
+    content: string;
+    source: "virtual" | "store" | "disk";
+    key?: string;
+    divergent: boolean;
+    diskContent?: string;
+    storeContent?: string;
+    storeKey?: string;
+}
+/**
+ * Resolves a path to its content using the documented precedence:
+ *   1. `.ace#`-style virtual path -> direct store key read.
+ *   2. Logical path -> resolveStoreFallbackKeysForPath, first hit wins.
+ *   3. Raw store key (namespace-prefixed) -> direct store key read.
+ *   4. Workspace disk file.
+ * When both a disk copy and a store copy exist and differ, the result is
+ * flagged `divergent` with both variants attached so the caller can warn
+ * and honor an explicit `preferSource` override.
+ */
+export declare function resolveReadTarget(workspaceRoot: string, inputPath: string, preferSource?: "disk" | "store"): ReadTarget | undefined;
+export declare function runReadCommand(workspaceRoot: string, args: string[]): Promise<void>;
+//# sourceMappingURL=store-cli.d.ts.map

package/dist/store/store-cli.js

@@ -0,0 +1,242 @@
+/**
+ * `ace ls` / `ace read` (aliases: `ace get`, `ace cat`) — the human read
+ * surface for the ACEPACK store. Precondition for hiding generated
+ * artifacts by default (Phase 2): once content only lives in the store,
+ * these are the only way a human sees it without opening the binary file.
+ *
+ * Read contract: content is either the complete decoded block whose byte
+ * length equals the index entry's length (see `validateChunkBounds` /
+ * `decodeChunkSync` in store-snapshot.ts), or resolution fails loudly.
+ * Reads are length-driven, never delimiter-driven — a block containing the
+ * literal text "EOF" mid-content is read in full, not truncated at it.
+ */
+import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { resolveStoreFallbackKeysForPath, resolveWorkspaceReadPath } from "../helpers.js";
+import { getWorkspaceStorePath, listStoreEntrySizesSync, listStoreKeysSync, readStoreBlobSync } from "./store-snapshot.js";
+function logicalPathForKey(key) {
+    const artifactPrefix = "state/artifacts/";
+    if (key.startsWith(artifactPrefix))
+        return key.slice(artifactPrefix.length);
+    const snapshotPrefix = "state/memory/context_snapshots/";
+    if (key.startsWith(snapshotPrefix))
+        return `agent-state/context-snapshots/${key.slice(snapshotPrefix.length)}`;
+    if (key === "state/source-edit-events.ndjson")
+        return "agent-state/source-edit-events.ndjson";
+    if (key === "state/source-edit-events-archive.ndjson")
+        return "agent-state/source-edit-events-archive.ndjson";
+    return key;
+}
+function logicalPrefixToKeyPrefix(prefix) {
+    if (!prefix)
+        return "";
+    const snapshotPrefix = "agent-state/context-snapshots";
+    if (prefix.startsWith(snapshotPrefix)) {
+        return `state/memory/context_snapshots/${prefix.slice(snapshotPrefix.length).replace(/^\//, "")}`;
+    }
+    if (prefix.startsWith("agent-state")) {
+        return `state/artifacts/${prefix}`;
+    }
+    return prefix;
+}
+function sectionForKey(key) {
+    if (key.startsWith("state/artifacts/") || key.startsWith("state/memory/context_snapshots/"))
+        return "operational";
+    if (key.startsWith("knowledge/"))
+        return "knowledge";
+    return "state";
+}
+export function listStoreEntries(workspaceRoot, prefix = "", useRawKeys = false) {
+    const rawPrefix = useRawKeys ? prefix : logicalPrefixToKeyPrefix(prefix);
+    const keys = new Set(listStoreKeysSync(workspaceRoot, rawPrefix));
+    if (!useRawKeys) {
+        const sourceEditLogicalPath = "agent-state/source-edit-events.ndjson";
+        if (sourceEditLogicalPath.startsWith(prefix || "agent-state") ||
+            (prefix || "agent-state").startsWith(sourceEditLogicalPath)) {
+            for (const key of listStoreKeysSync(workspaceRoot, "state/source-edit-events.ndjson")) {
+                keys.add(key);
+            }
+        }
+        const sourceEditArchiveLogicalPath = "agent-state/source-edit-events-archive.ndjson";
+        if (sourceEditArchiveLogicalPath.startsWith(prefix || "agent-state") ||
+            (prefix || "agent-state").startsWith(sourceEditArchiveLogicalPath)) {
+            for (const key of listStoreKeysSync(workspaceRoot, "state/source-edit-events-archive.ndjson")) {
+                keys.add(key);
+            }
+        }
+    }
+    const sizeByKey = new Map(listStoreEntrySizesSync(workspaceRoot, "").map((entry) => [entry.key, entry.length]));
+    return [...keys].map((key) => ({
+        path: useRawKeys ? key : logicalPathForKey(key),
+        key,
+        bytes: sizeByKey.get(key) ?? 0,
+    }));
+}
+export async function runLsCommand(workspaceRoot, args) {
+    const positional = args.filter((a) => !a.startsWith("--"));
+    const prefixArg = positional[0] ?? "";
+    const useRawKeys = args.includes("--keys");
+    const asJson = args.includes("--json");
+    const storePath = getWorkspaceStorePath(workspaceRoot);
+    if (!existsSync(storePath)) {
+        console.error(`No store found at ${storePath}. Run 'ace init' first.`);
+        process.exitCode = 1;
+        return;
+    }
+    const entries = listStoreEntries(workspaceRoot, prefixArg, useRawKeys);
+    if (asJson) {
+        console.log(JSON.stringify(entries, null, 2));
+        return;
+    }
+    if (entries.length === 0) {
+        console.log(prefixArg ? `No store entries under '${prefixArg}'.` : "Store is empty.");
+        return;
+    }
+    const sections = { operational: [], knowledge: [], state: [] };
+    for (const entry of entries)
+        sections[sectionForKey(entry.key)].push(entry);
+    const labels = {
+        operational: "Operational artifacts",
+        knowledge: "Knowledge",
+        state: "State",
+    };
+    for (const section of ["operational", "knowledge", "state"]) {
+        const list = sections[section];
+        if (list.length === 0)
+            continue;
+        console.log(`\n${labels[section]} (${list.length}):`);
+        for (const entry of [...list].sort((a, b) => a.path.localeCompare(b.path))) {
+            console.log(`  ${entry.path}  (${entry.bytes}B)`);
+        }
+    }
+}
+function tryDiskRead(workspaceRoot, inputPath) {
+    try {
+        const abs = resolveWorkspaceReadPath(inputPath);
+        if (existsSync(abs) && statSync(abs).isFile()) {
+            return readFileSync(abs, "utf-8");
+        }
+    }
+    catch {
+        // not a resolvable disk path — not a divergence candidate
+    }
+    return undefined;
+}
+/**
+ * Resolves a path to its content using the documented precedence:
+ *   1. `.ace#`-style virtual path -> direct store key read.
+ *   2. Logical path -> resolveStoreFallbackKeysForPath, first hit wins.
+ *   3. Raw store key (namespace-prefixed) -> direct store key read.
+ *   4. Workspace disk file.
+ * When both a disk copy and a store copy exist and differ, the result is
+ * flagged `divergent` with both variants attached so the caller can warn
+ * and honor an explicit `preferSource` override.
+ */
+export function resolveReadTarget(workspaceRoot, inputPath, preferSource) {
+    if (inputPath.includes(".ace#")) {
+        const marker = ".ace#";
+        const idx = inputPath.indexOf(marker);
+        const key = inputPath.slice(idx + marker.length);
+        const content = readStoreBlobSync(workspaceRoot, key);
+        if (typeof content !== "string")
+            return undefined;
+        return { content, source: "virtual", key, divergent: false };
+    }
+    const fallbackKeys = resolveStoreFallbackKeysForPath(inputPath);
+    for (const key of fallbackKeys) {
+        const storeContent = readStoreBlobSync(workspaceRoot, key);
+        if (typeof storeContent !== "string")
+            continue;
+        const diskContent = tryDiskRead(workspaceRoot, inputPath);
+        const divergent = typeof diskContent === "string" && diskContent !== storeContent;
+        const useDisk = divergent && preferSource === "disk";
+        return {
+            content: useDisk ? diskContent : storeContent,
+            source: useDisk ? "disk" : "store",
+            key,
+            storeKey: key,
+            divergent,
+            diskContent,
+            storeContent,
+        };
+    }
+    if (/^(state|knowledge|topology|meta)\//.test(inputPath)) {
+        const content = readStoreBlobSync(workspaceRoot, inputPath);
+        if (typeof content === "string") {
+            return { content, source: "store", key: inputPath, storeKey: inputPath, divergent: false };
+        }
+    }
+    const diskOnly = tryDiskRead(workspaceRoot, inputPath);
+    if (typeof diskOnly === "string") {
+        return { content: diskOnly, source: "disk", divergent: false };
+    }
+    return undefined;
+}
+const VALUE_FLAGS = new Set(["--out", "--prefer"]);
+function parsePositionalArgs(args) {
+    const positional = [];
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (arg.startsWith("--")) {
+            if (VALUE_FLAGS.has(arg))
+                i++; // skip the flag's value
+            continue;
+        }
+        positional.push(arg);
+    }
+    return positional;
+}
+export async function runReadCommand(workspaceRoot, args) {
+    const positional = parsePositionalArgs(args);
+    const inputPath = positional[0];
+    if (!inputPath) {
+        console.error("Usage: ace read <path> [--out <file>] [--source] [--prefer disk|store] [--json]");
+        process.exitCode = 1;
+        return;
+    }
+    const outIdx = args.indexOf("--out");
+    const outFile = outIdx >= 0 ? args[outIdx + 1] : undefined;
+    const preferIdx = args.indexOf("--prefer");
+    const preferRaw = preferIdx >= 0 ? args[preferIdx + 1] : undefined;
+    if (preferIdx >= 0 && preferRaw !== "disk" && preferRaw !== "store") {
+        console.error(`ace read: --prefer expects disk|store, got: ${preferRaw ?? "(missing)"}`);
+        process.exitCode = 1;
+        return;
+    }
+    const preferSource = preferRaw === "disk" || preferRaw === "store" ? preferRaw : undefined;
+    const showSource = args.includes("--source");
+    const asJson = args.includes("--json");
+    const result = resolveReadTarget(workspaceRoot, inputPath, preferSource);
+    if (!result) {
+        console.error(`ace read: not found: ${inputPath}`);
+        process.exitCode = 1;
+        return;
+    }
+    if (result.divergent) {
+        console.error(`⚠ store/disk copies differ for '${inputPath}' (use --prefer disk|store) — showing ${result.source}`);
+    }
+    if (asJson) {
+        console.log(JSON.stringify({
+            path: inputPath,
+            source: result.source,
+            key: result.key,
+            divergent: result.divergent,
+            content: result.content,
+        }, null, 2));
+        return;
+    }
+    if (outFile) {
+        const absOut = resolve(outFile);
+        mkdirSync(dirname(absOut), { recursive: true });
+        writeFileSync(absOut, result.content, "utf-8");
+        console.log(`Wrote ${Buffer.byteLength(result.content, "utf-8")} bytes to ${absOut}`);
+        return;
+    }
+    if (showSource) {
+        console.error(`# source=${result.source}${result.key ? ` key=${result.key}` : ""}`);
+    }
+    process.stdout.write(result.content);
+    if (!result.content.endsWith("\n"))
+        process.stdout.write("\n");
+}
+//# sourceMappingURL=store-cli.js.map

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

@@ -1,3 +1,11 @@
+import { type ChunkIndexEntry } from "./types.js";
+/**
+ * Bounds-checks an index entry against the file it was read from. Every
+ * index-driven read must pass through this before slicing — JS `slice`
+ * silently clamps at EOF instead of erroring, which previously let a
+ * corrupt/short index produce truncated content that looked plausible.
+ */
+export declare function validateChunkBounds(entry: ChunkIndexEntry, fileLength: number, minOffset?: number): boolean;
 export declare function invalidateStoreSnapshotCache(storePath?: string): void;
 export declare function getCanonicalWorkspaceStorePath(workspaceRoot: string): string;
 export declare function getLegacyWorkspaceStorePath(workspaceRoot: string): string;
@@ -9,6 +17,10 @@ export declare function readStoreJsonSync<T>(workspaceRoot: string, key: string)
 export declare function readStoreJsonByPathSync<T>(storePath: string, key: string): T | undefined;
 export declare function listStoreKeysSync(workspaceRoot: string, prefix?: string): string[];
 export declare function listStoreKeysByPathSync(storePath: string, prefix?: string): string[];
+export declare function listStoreEntrySizesSync(workspaceRoot: string, prefix?: string): Array<{
+    key: string;
+    length: number;
+}>;
 export declare function getStoreStatSync(storePath: string): {
     mtimeMs: number;
     size: number;

package/dist/store/store-snapshot.js

@@ -1,7 +1,56 @@
 import { existsSync, readFileSync, statSync } from "node:fs";
 import { resolve } from "node:path";
-import { HEADER_SIZE, MAGIC } from "./types.js";
+import { HEADER_SIZE, HEADER_SIZE_V1, MAGIC } from "./types.js";
+import { crc32 } from "./crc32.js";
 const DECODE = new TextDecoder();
+/**
+ * Bounds-checks an index entry against the file it was read from. Every
+ * index-driven read must pass through this before slicing — JS `slice`
+ * silently clamps at EOF instead of erroring, which previously let a
+ * corrupt/short index produce truncated content that looked plausible.
+ */
+export function validateChunkBounds(entry, fileLength, minOffset = HEADER_SIZE_V1) {
+    if (!Number.isFinite(entry.offset) || !Number.isFinite(entry.length))
+        return false;
+    if (entry.offset < minOffset || entry.length < 0)
+        return false;
+    return entry.offset + 4 + entry.length <= fileLength;
+}
+function warnStoreReadOutOfBounds(key, entry, fileLength, reason) {
+    console.error(JSON.stringify({
+        event: "store_read_out_of_bounds",
+        key,
+        offset: entry.offset,
+        length: entry.length,
+        fileSize: fileLength,
+        reason,
+    }));
+}
+/**
+ * Decodes a chunk only if its bounds are valid AND the length prefix stored
+ * at `entry.offset` agrees with the index's `entry.length`. Any mismatch
+ * (index corruption, short read of a partially-visible file) returns
+ * `undefined` instead of silently-wrong or cross-section-bled content.
+ */
+function decodeChunkSync(file, entry, key) {
+    if (!validateChunkBounds(entry, file.length)) {
+        warnStoreReadOutOfBounds(key, entry, file.length, "out_of_bounds");
+        return undefined;
+    }
+    const prefixed = bytesToUint32(file, entry.offset);
+    if (prefixed !== entry.length) {
+        warnStoreReadOutOfBounds(key, entry, file.length, "length_prefix_mismatch");
+        return undefined;
+    }
+    const start = entry.offset + 4;
+    const end = start + entry.length;
+    const chunk = file.slice(start, end);
+    if (typeof entry.crc === "number" && crc32(chunk) !== entry.crc) {
+        warnStoreReadOutOfBounds(key, entry, file.length, "crc_mismatch");
+        return undefined;
+    }
+    return DECODE.decode(chunk);
+}
 let cached;
 export function invalidateStoreSnapshotCache(storePath) {
     if (!cached)
@@ -28,19 +77,27 @@ function readHeader(bytes) {
     };
 }
 function loadSnapshot(storePath) {
-    if (!existsSync(storePath))
+    if (!existsSync(storePath)) {
+        invalidateStoreSnapshotCache(storePath);
         return undefined;
+    }
     const stats = statSync(storePath);
     if (cached &&
         cached.path === storePath &&
         cached.mtimeMs === stats.mtimeMs &&
-        cached.size === stats.size) {
+        cached.size === stats.size &&
+        cached.ino === stats.ino) {
         return cached;
     }
     try {
         const file = readFileSync(storePath);
-        if (file.length < HEADER_SIZE)
-            return cached?.path === storePath ? cached : undefined;
+        // Never serve a stale cached snapshot as a fallback for an unreadable or
+        // short file — that would silently return deleted/old data. Missing is
+        // the safe answer; the caller already treats undefined as "not present".
+        if (file.length < HEADER_SIZE) {
+            invalidateStoreSnapshotCache(storePath);
+            return undefined;
+        }
         const { indexOffset, indexLength } = readHeader(file);
         const indexBytes = file.slice(indexOffset, indexOffset + indexLength);
         const parsed = JSON.parse(DECODE.decode(indexBytes));
@@ -48,6 +105,7 @@ function loadSnapshot(storePath) {
             path: storePath,
             mtimeMs: stats.mtimeMs,
             size: stats.size,
+            ino: stats.ino,
             file,
             index: new Map(Object.entries(parsed)),
         };
@@ -81,18 +139,14 @@ export function readStoreBlobSync(workspaceRoot, key) {
     const entry = snapshot?.index.get(key);
     if (!snapshot || !entry)
         return undefined;
-    const start = entry.offset + 4;
-    const end = start + entry.length;
-    return DECODE.decode(snapshot.file.slice(start, end));
+    return decodeChunkSync(snapshot.file, entry, key);
 }
 export function readStoreBlobByPathSync(storePath, key) {
     const snapshot = loadSnapshot(storePath);
     const entry = snapshot?.index.get(key);
     if (!snapshot || !entry)
         return undefined;
-    const start = entry.offset + 4;
-    const end = start + entry.length;
-    return DECODE.decode(snapshot.file.slice(start, end));
+    return decodeChunkSync(snapshot.file, entry, key);
 }
 export function readStoreJsonSync(workspaceRoot, key) {
     const raw = readStoreBlobSync(workspaceRoot, key);
@@ -132,6 +186,15 @@ export function listStoreKeysByPathSync(storePath, prefix = "") {
         .filter((key) => key.startsWith(prefix))
         .sort((a, b) => a.localeCompare(b));
 }
+export function listStoreEntrySizesSync(workspaceRoot, prefix = "") {
+    const snapshot = loadSnapshot(getWorkspaceStorePath(workspaceRoot));
+    if (!snapshot)
+        return [];
+    return [...snapshot.index.entries()]
+        .filter(([key]) => key.startsWith(prefix))
+        .map(([key, entry]) => ({ key, length: entry.length }))
+        .sort((a, b) => a.key.localeCompare(b.key));
+}
 export function getStoreStatSync(storePath) {
     const snapshot = loadSnapshot(storePath);
     if (!snapshot)

package/dist/store/types.d.ts

@@ -46,6 +46,7 @@ export declare const HEADER_SIZE_V1 = 64;
 export interface ChunkIndexEntry {
     offset: number;
     length: number;
+    crc?: number;
 }
 /** Zarrita AsyncReadable protocol */
 export interface AsyncReadable {

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

@@ -59,6 +59,13 @@ export declare class StoreSyncWriteBlockedByAsyncLeaseError extends Error {
         currentAsyncOperationLabels: string[];
     });
 }
+export type StoreWriteLockClassification = "active" | "stale" | "unreadable";
+/**
+ * Classifies a write-lock directory for maintenance tools. "active" leases
+ * must never be removed; "stale" (expired past TTL+grace) and "unreadable"
+ * (no/invalid lease.json) are safe repair targets.
+ */
+export declare function classifyStoreWriteLockDir(lockPath: string, staleGraceMs?: number): StoreWriteLockClassification;
 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;

package/dist/store/write-coordinator.js

@@ -159,6 +159,17 @@ function leaseIsStale(lease, staleGraceMs) {
         return true;
     return Date.now() > expiresAt + staleGraceMs;
 }
+/**
+ * Classifies a write-lock directory for maintenance tools. "active" leases
+ * must never be removed; "stale" (expired past TTL+grace) and "unreadable"
+ * (no/invalid lease.json) are safe repair targets.
+ */
+export function classifyStoreWriteLockDir(lockPath, staleGraceMs = DEFAULT_STALE_GRACE_MS) {
+    const lease = readLeaseRecord(lockPath);
+    if (!lease)
+        return "unreadable";
+    return leaseIsStale(lease, staleGraceMs) ? "stale" : "active";
+}
 function canRecoverStaleLease(lease, staleGraceMs) {
     if (!leaseIsStale(lease, staleGraceMs))
         return false;

package/dist/todo-state.d.ts

@@ -14,6 +14,14 @@ export interface TodoStateFile {
     order: string[];
     nodes: Record<string, TodoNode>;
 }
+export interface TodoAppendResult {
+    ok: boolean;
+    path: string;
+    todo_path: string;
+    node_id?: string;
+    section?: string;
+    error?: string;
+}
 export interface TodoTransitionResult {
     ok: boolean;
     path: string;
@@ -38,4 +46,17 @@ export declare function syncTodoStateSafe(todoContent?: string): Promise<{
 export declare function readTodoState(): TodoStateFile;
 export declare function transitionTodoNode(nodeId: string, targetStatus: TodoNodeStatus): TodoTransitionResult;
 export declare function transitionTodoNodeSafe(nodeId: string, targetStatus: TodoNodeStatus): Promise<TodoTransitionResult>;
+/**
+ * Atomically append a new TODO item under a section, without requiring the
+ * caller to read the whole board and resubmit it via update_todo(new_content).
+ * That read-modify-write dance is what let concurrent agents silently clobber
+ * each other's appended items: the read and write are separate MCP calls, so
+ * a lock around the write alone cannot close the race. Here the read, insert,
+ * and write all happen inside one TODO_MARKDOWN_REL lock acquisition.
+ */
+export declare function appendTodoItemSafe(title: string, options?: {
+    section?: string;
+    depends_on?: string[];
+    id?: string;
+}): Promise<TodoAppendResult>;
 //# sourceMappingURL=todo-state.d.ts.map