@nowcrew/daemon 0.6.89 → 0.6.91-beta.1

package/dist/local-memory/inventory-preview.js

@@ -0,0 +1,159 @@
+import { createHash } from "node:crypto";
+import { LOCAL_MEMORY_INDEX_CODE_POINT_CAP, LOCAL_MEMORY_INDEX_ENTRY_CAP, LOCAL_MEMORY_TOTAL_CODE_POINT_CAP, renderGeneratedIndex, } from "./index-budget.js";
+import { parseLocalMemoryIndex } from "./write.js";
+const GENERATED = /<!--\s*NOWWORK:MEMORY_INDEX:BEGIN\s+schema=1\s*-->[\s\S]*?<!--\s*NOWWORK:MEMORY_INDEX:END\s*-->/gu;
+const REFERENCE = /^notes\/(?!.*(?:^|\/)\.\.?\/)(?:[^/\\\u0000-\u001f]+\/)*[^/\\\u0000-\u001f]+\.md$/u;
+const FIELD = /^-\s+([a-z][a-z_]*)\s*:\s*(.*?)\s*$/iu;
+const WRITABLE_FILES = new Set(["preferences", "project-rules", "testing", "debugging", "git", "incidents", "lessons"]
+    .map((category) => `notes/${category}.md`));
+const length = (text) => Array.from(text).length;
+const digest = (text) => createHash("sha256").update(text).digest("hex");
+export function previewMemoryInventory(sources, readComplete, mode = "migration") {
+    const issues = [];
+    const entries = [];
+    const sourceMap = new Map(sources.map((source) => [source.path, source]));
+    const memory = sourceMap.get("MEMORY.md")?.content ?? "";
+    const add = (code, path = "MEMORY.md") => issues.push({ code, path });
+    // 掩盖注释但保留UTF-16位置，避免把模板示例当成条目，也保留原文供人工复核。
+    const comments = [...memory.matchAll(/<!--[\s\S]*?-->/gu)];
+    // 现有写入器允许正文包含箭头 A --> B；未闭合的注释仍须拒绝。
+    if ((memory.match(/<!--/gu) ?? []).length !== comments.length
+        || (mode === "migration" && (memory.match(/-->/gu) ?? []).length !== comments.length))
+        add("comment_boundary_invalid");
+    const masked = memory.replace(/<!--[\s\S]*?-->/gu, (comment) => comment.replace(/[^\r\n]/gu, (character) => " ".repeat(character.length)));
+    const sections = [...masked.matchAll(/^##[\t ]+Knowledge Index[\t ]*\r?$/gmu)];
+    const heading = sections[0];
+    if (sections.length !== 1 || heading?.index === undefined)
+        add("index_heading_invalid");
+    const start = heading === undefined ? 0 : heading.index + heading[0].length;
+    const next = /^##[\t ]+(?!#)/mu.exec(masked.slice(start));
+    const end = next?.index === undefined ? memory.length : start + next.index;
+    const generated = [...memory.matchAll(GENERATED)];
+    const markerCount = (memory.match(/NOWWORK:MEMORY_INDEX:/gu) ?? []).length;
+    if (markerCount !== generated.length * 2 || generated.length > 1
+        || generated.some((block) => block.index < start || block.index + block[0].length > end))
+        add("index_marker_invalid");
+    const heads = [...masked.slice(start, end).matchAll(/^###[\t ]+(.+?)[\t ]*\r?$/gmu)];
+    if (heads.length > 1000)
+        add("card_limit_exceeded");
+    const ranges = [];
+    for (const [i, head] of heads.slice(0, 1000).entries()) {
+        const cardStart = start + head.index;
+        const cardEnd = heads[i + 1]?.index === undefined ? end : start + heads[i + 1].index;
+        const tailStart = cardStart + head[0].length;
+        const tail = masked.slice(tailStart, cardEnd);
+        const fields = {};
+        const issueStart = issues.length;
+        let lastFieldEnd = tailStart;
+        let proseSeen = false;
+        for (const line of tail.matchAll(/[^\n]*(?:\n|$)/gu)) {
+            const field = FIELD.exec(line[0].replace(/\r?\n$/u, ""));
+            if (field) {
+                const key = field[1].toLowerCase();
+                if (fields[key] !== undefined)
+                    add("duplicate_field");
+                if (proseSeen)
+                    add("ambiguous_card_body");
+                fields[key] = field[2];
+                lastFieldEnd = tailStart + line.index + line[0].length;
+            }
+            else if (line[0].trim())
+                proseSeen = true;
+        }
+        const rawCard = memory.slice(cardStart, lastFieldEnd);
+        const format = generated.some((block) => cardStart >= block.index && cardStart < block.index + block[0].length)
+            ? "managed" : "legacy";
+        const parsed = parseLocalMemoryIndex(`## Knowledge Index\n${rawCard}`)[0];
+        // 状态更新会把已归一化的空触发词数组写回；字段缺失仍是格式错误。
+        const missingTriggers = mode === "existing_v2" && format === "managed" ? fields.triggers === undefined : !fields.triggers;
+        if (!parsed || !fields.type || !fields.summary || missingTriggers || !fields.priority || !fields.updated
+            || (format === "legacy" && !fields.scope)
+            || !["procedural", "semantic", "episodic", "preference"].includes(fields.type)
+            || !["high", "medium", "low"].includes(fields.priority))
+            add("invalid_card");
+        const file = fields.file ?? "";
+        if (!REFERENCE.test(file) || file.split("/").some((part) => part === "." || part === ".."))
+            add("invalid_reference", file);
+        const detail = sourceMap.get(file)?.content ?? null;
+        if (detail === null)
+            add("missing_detail", file);
+        let proposed = null;
+        if (parsed) {
+            const id = format === "legacy" ? `mem_${digest(rawCard).slice(0, 32)}` : parsed.id;
+            proposed = { ...parsed, id, anchor: id, revision: format === "legacy" ? 1 : parsed.revision };
+            if (format === "managed") {
+                if (!fields.id || !/^[a-zA-Z0-9_-]+$/u.test(fields.id) || fields.anchor !== fields.id
+                    || !/^[1-9][0-9]*$/u.test(fields.revision ?? "") || !Number.isSafeInteger(parsed.revision)
+                    || !["active", "pinned"].includes(fields.status ?? ""))
+                    add("managed_metadata_invalid");
+                const begin = `<!-- NOWWORK:MEMORY_ENTRY:BEGIN id=${parsed.id} revision=${parsed.revision} -->`;
+                const finish = `<!-- NOWWORK:MEMORY_ENTRY:END id=${parsed.id} -->`;
+                if (!detail?.includes(begin) || !detail.includes(finish)
+                    || detail.indexOf(finish) < detail.indexOf(begin)
+                    || detail.split(begin).length !== 2 || detail.split(finish).length !== 2)
+                    add("managed_anchor_invalid", file);
+            }
+            else if (fields.status && fields.status !== "active") {
+                add("legacy_status_requires_review", file);
+            }
+            if (format === "legacy" && /NOWWORK:MEMORY_(?:ENTRY|INDEX):/u.test(detail ?? ""))
+                add("legacy_detail_contains_markers", file);
+        }
+        entries.push({
+            title: head[1], format, disposition: issues.length === issueStart ? "review_required" : "blocked",
+            sourceFields: fields, rawCard, detail, proposed,
+        });
+        ranges.push({ start: cardStart, end: lastFieldEnd });
+    }
+    for (const entry of entries) {
+        if (entries.filter((other) => other.sourceFields.file === entry.sourceFields.file).length > 1
+            && entry.format === "legacy")
+            add("shared_legacy_detail", entry.sourceFields.file);
+        if (entries.filter((other) => other.proposed?.id === entry.proposed?.id).length > 1)
+            add("duplicate_id");
+        // 已管理条目由ID区分，现有update允许同名；迁移预演仍要求人工审核同名来源。
+        if ((mode === "migration" || entry.format === "legacy")
+            && entries.filter((other) => other.title.trim().toLowerCase() === entry.title.trim().toLowerCase()).length > 1)
+            add("duplicate_title");
+    }
+    const compatibilityIssues = entries.filter((entry) => !WRITABLE_FILES.has(entry.sourceFields.file ?? ""))
+        .map((entry) => ({ code: "detail_category_mapping_required", path: entry.sourceFields.file ?? "" }));
+    let preview = null;
+    if (readComplete && issues.length === 0) {
+        const index = renderGeneratedIndex(entries.map(entry => entry.proposed));
+        let retained = memory;
+        for (const range of [...ranges].reverse())
+            retained = retained.slice(0, range.start) + retained.slice(range.end);
+        retained = retained.replace(GENERATED, "");
+        // 新生成块仅替换索引卡片，角色、目标、维护说明和其它段落保留。
+        const insertAt = start;
+        const projected = retained.slice(0, insertAt) + `\n${index}\n` + retained.slice(insertAt);
+        const budget = {
+            entries: entries.length, indexCodePoints: length(index), totalCodePoints: length(projected),
+            entryCap: LOCAL_MEMORY_INDEX_ENTRY_CAP, indexCodePointCap: LOCAL_MEMORY_INDEX_CODE_POINT_CAP,
+            totalCodePointCap: LOCAL_MEMORY_TOTAL_CODE_POINT_CAP,
+            fits: entries.length <= LOCAL_MEMORY_INDEX_ENTRY_CAP && length(index) <= LOCAL_MEMORY_INDEX_CODE_POINT_CAP
+                && length(projected) <= LOCAL_MEMORY_TOTAL_CODE_POINT_CAP,
+        };
+        preview = {
+            memory: projected, budget, writerCompatible: compatibilityIssues.length === 0,
+            notes: entries.filter((entry) => entry.format === "legacy").map((entry) => ({
+                path: entry.sourceFields.file,
+                content: `<!-- NOWWORK:MEMORY_ENTRY:BEGIN id=${entry.proposed.id} revision=1 -->\n`
+                    + `## ${entry.title}\n\n旧索引范围（仍需结合正文人工确认）：${entry.sourceFields.scope}\n\n`
+                    + `${entry.detail}${entry.detail.endsWith("\n") ? "" : "\n"}`
+                    + `<!-- NOWWORK:MEMORY_ENTRY:END id=${entry.proposed.id} -->\n`,
+            })),
+        };
+        if (!budget.fits)
+            add("projection_over_budget");
+    }
+    const shownDetails = new Set();
+    const compactEntries = entries.map((entry) => {
+        const file = entry.sourceFields.file ?? "";
+        const detail = shownDetails.has(file) ? null : entry.detail;
+        shownDetails.add(file);
+        return { ...entry, detail };
+    });
+    return { entries: compactEntries, issues: [...issues, ...compatibilityIssues], preview, rawMemory: memory };
+}

package/dist/local-memory/inventory-source.js

@@ -0,0 +1,159 @@
+import { createHash } from "node:crypto";
+import { constants } from "node:fs";
+import { lstat, open, readdir, realpath } from "node:fs/promises";
+import { isAbsolute, join, relative, sep } from "node:path";
+import { TextDecoder } from "node:util";
+const MAX_FILE_BYTES = 32 * 1024 * 1024;
+const MAX_TOTAL_BYTES = 64 * 1024 * 1024;
+const MAX_ITEMS = 10_000;
+const MAX_DEPTH = 32;
+export const inventoryLimits = {
+    fileBytes: MAX_FILE_BYTES, totalBytes: MAX_TOTAL_BYTES, items: MAX_ITEMS, depth: MAX_DEPTH,
+};
+function errorCode(error) {
+    if (error instanceof TypeError)
+        return "invalid_utf8";
+    if (error instanceof Error)
+        return error.code ?? error.message;
+    return "read_failed";
+}
+async function safePath(root, file) {
+    const parts = file.split("/");
+    if (parts.some((part) => !part || part === "." || part === ".." || part.includes("\\"))) {
+        throw new Error("unsafe_path");
+    }
+    let path = root;
+    for (const part of parts) {
+        path = join(path, part);
+        if ((await lstat(path)).isSymbolicLink())
+            throw new Error("unsafe_path");
+    }
+    const actual = await realpath(path);
+    const rel = relative(root, actual);
+    if (actual !== path || isAbsolute(rel) || rel === ".." || rel.startsWith(`..${sep}`)) {
+        throw new Error("unsafe_path");
+    }
+    return path;
+}
+export async function readMemoryInventorySource(root, file, budget) {
+    const path = await safePath(root, file);
+    const handle = await open(path, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0) | (constants.O_NONBLOCK ?? 0));
+    try {
+        const before = await handle.stat();
+        if (!before.isFile())
+            throw new Error("not_regular_file");
+        const limit = Math.min(MAX_FILE_BYTES, budget);
+        if (before.size > limit)
+            throw new Error("read_limit_exceeded");
+        const chunks = [];
+        let bytes = 0;
+        for (;;) {
+            const chunk = Buffer.alloc(Math.min(64 * 1024, limit + 1 - bytes));
+            const { bytesRead } = await handle.read(chunk, 0, chunk.length, null);
+            if (bytesRead === 0)
+                break;
+            bytes += bytesRead;
+            if (bytes > limit)
+                throw new Error("read_limit_exceeded");
+            chunks.push(chunk.subarray(0, bytesRead));
+        }
+        const after = await handle.stat();
+        const current = await lstat(await safePath(root, file));
+        if (before.ino !== current.ino || before.dev !== current.dev || before.size !== after.size
+            || before.mtimeMs !== after.mtimeMs || before.ctimeMs !== after.ctimeMs)
+            throw new Error("source_changed");
+        const data = Buffer.concat(chunks);
+        return {
+            path: file, bytes,
+            sha256: createHash("sha256").update(data).digest("hex"),
+            content: new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(data),
+        };
+    }
+    finally {
+        await handle.close();
+    }
+}
+export async function scanMemorySources(agentDir) {
+    const root = await realpath(agentDir);
+    if ((await lstat(agentDir)).isSymbolicLink())
+        throw new Error("agent_root_symlink");
+    if (!(await lstat(root)).isDirectory())
+        throw new Error("agent_root_not_directory");
+    const sources = [];
+    const issues = [];
+    const directories = new Map();
+    let totalBytes = 0;
+    let items = 0;
+    const addIssue = (code, path) => issues.push({ code, path });
+    async function visit(file, optional = false, depth = 0) {
+        if (++items > MAX_ITEMS || depth > MAX_DEPTH) {
+            addIssue("scan_limit_exceeded", file);
+            return;
+        }
+        try {
+            const path = await safePath(root, file);
+            const stat = await lstat(path);
+            if (file === "MEMORY.md" && !stat.isFile())
+                throw new Error("not_regular_file");
+            if ((file === "notes" || file === ".crew/memory/pending") && !stat.isDirectory())
+                throw new Error("not_directory");
+            if (stat.isDirectory()) {
+                const names = (await readdir(path)).sort();
+                directories.set(file, names);
+                for (const name of names) {
+                    if (items >= MAX_ITEMS) {
+                        addIssue("scan_limit_exceeded", file);
+                        break;
+                    }
+                    await visit(`${file}/${name}`, false, depth + 1);
+                }
+            }
+            else {
+                const source = await readMemoryInventorySource(root, file, MAX_TOTAL_BYTES - totalBytes);
+                totalBytes += source.bytes;
+                sources.push(source);
+            }
+        }
+        catch (error) {
+            const code = errorCode(error);
+            if (optional && code === "ENOENT")
+                directories.set(file, []);
+            else
+                addIssue(code, file);
+        }
+    }
+    await visit("MEMORY.md");
+    await visit("notes", true);
+    await visit(".crew/memory/pending", true);
+    const resultNames = (await readdir(root)).filter((name) => /^\.memory-result\.v1-.*\.json$/u.test(name)).sort();
+    for (const name of resultNames)
+        await visit(name);
+    // 第二遍比对摘要和目录清单，发现扫描期间的变化就拒绝完整性结论；这不是跨文件事务锁。
+    for (const source of sources) {
+        try {
+            if ((await readMemoryInventorySource(root, source.path, MAX_FILE_BYTES)).sha256 !== source.sha256) {
+                addIssue("source_changed", source.path);
+            }
+        }
+        catch (error) {
+            addIssue(errorCode(error), source.path);
+        }
+    }
+    for (const [file, names] of directories) {
+        try {
+            const current = (await readdir(await safePath(root, file))).sort();
+            if (JSON.stringify(current) !== JSON.stringify(names))
+                addIssue("source_changed", file);
+        }
+        catch (error) {
+            if (errorCode(error) !== "ENOENT" || names.length > 0)
+                addIssue("source_changed", file);
+        }
+    }
+    const currentResults = (await readdir(root)).filter((name) => /^\.memory-result\.v1-.*\.json$/u.test(name)).sort();
+    if (JSON.stringify(currentResults) !== JSON.stringify(resultNames))
+        addIssue("source_changed", ".memory-result.v1-*.json");
+    if (await realpath(agentDir) !== root)
+        addIssue("source_changed", "agent_root");
+    return { root, sources: sources.sort((a, b) => a.path.localeCompare(b.path)), issues, totalBytes };
+}

package/dist/local-memory/pending-match.js

@@ -0,0 +1,29 @@
+export function normalizePendingQuery(value) {
+    return value.normalize("NFKC").toLocaleLowerCase().replace(/\s+/gu, " ").trim();
+}
+function containsTerm(text, term) {
+    if (!term)
+        return false;
+    const startBoundary = /^[a-z0-9]/u.test(term);
+    const endBoundary = /[a-z0-9]$/u.test(term);
+    let position = text.indexOf(term);
+    while (position >= 0) {
+        const before = text[position - 1] ?? "";
+        const after = text[position + term.length] ?? "";
+        if ((!startBoundary || !/[a-z0-9_-]/u.test(before)) && (!endBoundary || !/[a-z0-9_-]/u.test(after)))
+            return true;
+        position = text.indexOf(term, position + 1);
+    }
+    return false;
+}
+export function pendingRecallScore(item, query) {
+    const normalized = normalizePendingQuery(query);
+    if (!normalized)
+        return 0;
+    const candidate = item.candidate;
+    const terms = normalized.split(/[\s,，、。！？；：:()[\]{}"'`]+/u).filter(Boolean);
+    const text = normalizePendingQuery([candidate.title, candidate.summary, ...candidate.triggers, candidate.detailCategory, candidate.detailBody].join("\n"));
+    const explicit = [candidate.title, ...candidate.triggers].map(normalizePendingQuery);
+    const explicitScore = explicit.reduce((score, term) => score + (containsTerm(normalized, term) ? 10 : 0), 0);
+    return explicitScore + terms.reduce((score, term) => score + (containsTerm(text, term) ? 1 : 0), 0);
+}

package/dist/local-memory/pending-query.js

@@ -0,0 +1,100 @@
+import { createHash } from "node:crypto";
+import { z } from "zod";
+import { isRecallablePending, PendingIdSchema } from "./pending-schema.js";
+import { normalizePendingQuery, pendingRecallScore } from "./pending-match.js";
+import { pendingDirectorySnapshot, pendingSourceError, PENDING_FILE_BYTES, readPendingSource } from "./pending-source.js";
+const PAGE_FILES = 128;
+const PAGE_BYTES = 1_000_000;
+const OUTPUT_BYTES = 12 * 1024;
+const CursorSchema = z.object({
+    v: z.literal(1), queryHash: z.string().regex(/^[a-f0-9]{64}$/u), version: z.string().regex(/^[a-f0-9]{64}$/u),
+    after: z.string().min(1).max(255), hadWarnings: z.boolean(),
+}).strict();
+const SearchSchema = z.object({
+    agentDir: z.string().min(1), query: z.string().trim().min(1).max(256),
+    cursor: z.string().max(2048).optional(), limit: z.number().int().min(1).max(40).default(10),
+}).strict();
+const excerpt = (text, cap) => Array.from(text).slice(0, cap).join("");
+export async function searchPendingMemoryPage(input) {
+    const parsed = SearchSchema.safeParse(input);
+    if (!parsed.success)
+        throw new Error("memory_pending_arguments_invalid");
+    const args = parsed.data;
+    const queryHash = createHash("sha256").update(normalizePendingQuery(args.query)).digest("hex");
+    let cursor;
+    if (args.cursor !== undefined) {
+        try {
+            cursor = CursorSchema.parse(JSON.parse(Buffer.from(args.cursor, "base64url").toString("utf8")));
+        }
+        catch {
+            throw new Error("memory_pending_cursor_invalid");
+        }
+        if (cursor.queryHash !== queryHash)
+            throw new Error("memory_pending_cursor_invalid");
+    }
+    const snapshot = await pendingDirectorySnapshot(args.agentDir);
+    if (cursor && cursor.version !== snapshot.version)
+        throw new Error("memory_pending_source_changed");
+    const initial = cursor ? snapshot.names.indexOf(cursor.after) + 1 : 0;
+    if (cursor && initial === 0)
+        throw new Error("memory_pending_cursor_invalid");
+    const matches = [];
+    const warnings = [];
+    let position = initial;
+    let scannedFiles = 0;
+    let scannedBytes = 0;
+    // 为游标、错误与元数据预留空间；达到输出上限前停止消费来源，不跳过未输出的命中。
+    let outputBytes = 1600;
+    while (position < snapshot.names.length && scannedFiles < PAGE_FILES && scannedBytes + PENDING_FILE_BYTES <= PAGE_BYTES) {
+        const name = snapshot.names[position];
+        let source;
+        let warning;
+        try {
+            source = await readPendingSource(args.agentDir, name);
+        }
+        catch (error) {
+            const code = pendingSourceError(error);
+            if (code === "memory_pending_source_changed" || code === "memory_pending_not_found")
+                throw new Error("memory_pending_source_changed");
+            warning = { file: name, code };
+        }
+        const match = source && isRecallablePending(source.candidate) && pendingRecallScore(source.candidate, args.query) > 0
+            ? { pendingId: source.candidate.pendingId, sha256: source.sha256, title: source.candidate.candidate.title,
+                summary: excerpt(source.candidate.candidate.summary, 180), triggers: source.candidate.candidate.triggers.slice(0, 4),
+                operation: "create", state: "capacity_deferred" }
+            : null;
+        const addition = match ?? warning;
+        const size = addition ? Buffer.byteLength(JSON.stringify(addition), "utf8") + 2 : 0;
+        if (outputBytes + size > OUTPUT_BYTES)
+            break;
+        if (match)
+            matches.push(match);
+        if (warning)
+            warnings.push(warning);
+        outputBytes += size;
+        scannedFiles += 1;
+        scannedBytes += source?.bytes ?? PENDING_FILE_BYTES;
+        position += 1;
+        if (matches.length >= args.limit)
+            break;
+    }
+    if ((await pendingDirectorySnapshot(args.agentDir)).version !== snapshot.version)
+        throw new Error("memory_pending_source_changed");
+    const hasMore = position < snapshot.names.length;
+    const hadWarnings = cursor?.hadWarnings === true || warnings.length > 0;
+    const nextCursor = hasMore ? Buffer.from(JSON.stringify({ v: 1, queryHash, version: snapshot.version,
+        after: snapshot.names[position - 1], hadWarnings })).toString("base64url") : null;
+    return { matches, warnings, scannedFiles, scannedBytes, hasMore, nextCursor, complete: !hasMore && !hadWarnings };
+}
+export async function readPendingMemoryBody(input) {
+    if (!PendingIdSchema.safeParse(input.pendingId).success)
+        throw new Error("memory_pending_id_invalid");
+    const source = await readPendingSource(input.agentDir, `${input.pendingId}.json`);
+    if (input.ifHash !== undefined && input.ifHash !== source.sha256)
+        throw new Error("memory_pending_source_changed");
+    if (!isRecallablePending(source.candidate))
+        throw new Error("memory_pending_not_recallable");
+    const candidate = source.candidate.candidate;
+    return { pendingId: source.candidate.pendingId, sha256: source.sha256, title: candidate.title,
+        operation: "create", state: "capacity_deferred", content: candidate.detailBody };
+}

package/dist/local-memory/pending-schema.js

@@ -0,0 +1,29 @@
+import { z } from "zod";
+import { LocalMemoryChangeSchema, validateLocalMemoryChange } from "./candidate.js";
+// 索引会按分隔符展开触发词；16 个最多 80 UTF-16 单元的输入可产生 0..640 项。
+const ArchivedMemoryChangeSchema = LocalMemoryChangeSchema.extend({
+    triggers: z.array(LocalMemoryChangeSchema.shape.triggers.element).max(640)
+        .refine((triggers) => triggers.reduce((length, trigger) => length + trigger.length, 0) <= 16 * 80),
+});
+export const PendingIdSchema = z.string().max(200).regex(/^[A-Za-z0-9][A-Za-z0-9._-]*$/u);
+export const PendingMemorySchema = z.object({
+    schemaVersion: z.literal(1), pendingId: PendingIdSchema,
+    createdAt: z.string().min(1).max(100), reason: z.literal("index_over_budget"),
+    source: z.object({ executionId: z.string().min(1).max(500), pruneTraceId: z.string().min(1).max(500).nullable() }).strict(),
+    candidate: ArchivedMemoryChangeSchema,
+}).strict();
+export function parsePendingMemoryCandidate(value) {
+    const parsed = PendingMemorySchema.safeParse(value);
+    if (!parsed.success)
+        throw new Error("local_memory_pending_invalid");
+    validateLocalMemoryChange(parsed.data.candidate);
+    return parsed.data;
+}
+export function isRecallablePending(value) {
+    try {
+        return parsePendingMemoryCandidate(value).candidate.operation === "create";
+    }
+    catch {
+        return false;
+    }
+}

package/dist/local-memory/pending-source.js

@@ -0,0 +1,126 @@
+import { constants } from "node:fs";
+import { lstat, open, opendir, realpath } from "node:fs/promises";
+import { createHash } from "node:crypto";
+import { join } from "node:path";
+import { TextDecoder } from "node:util";
+import { parsePendingMemoryCandidate, PendingIdSchema } from "./pending-schema.js";
+export const PENDING_FILE_BYTES = 128 * 1024;
+const DIRECTORY_ENTRY_CAP = 10_000;
+export function pendingSourceError(error) {
+    if (error instanceof Error && /^memory_pending_[a-z_]+$/u.test(error.message))
+        return error.message;
+    return "memory_pending_file_invalid";
+}
+export async function pendingReadDirectory(agentDir) {
+    const root = await realpath(agentDir);
+    let directory = root;
+    for (const part of [".crew", "memory", "pending"]) {
+        directory = join(directory, part);
+        let stat;
+        try {
+            stat = await lstat(directory);
+        }
+        catch (error) {
+            if (error.code === "ENOENT")
+                return { root, directory: null };
+            throw new Error("memory_pending_directory_unreadable");
+        }
+        if (!stat.isDirectory() || stat.isSymbolicLink() || await realpath(directory) !== directory) {
+            throw new Error("memory_pending_path_invalid");
+        }
+    }
+    return { root, directory };
+}
+export async function pendingFileNames(directory) {
+    if (directory === null)
+        return [];
+    const names = [];
+    let inspected = 0;
+    try {
+        for await (const item of await opendir(directory)) {
+            if (++inspected > DIRECTORY_ENTRY_CAP)
+                throw new Error("memory_pending_directory_over_budget");
+            if (item.name.endsWith(".json"))
+                names.push(item.name);
+        }
+    }
+    catch (error) {
+        if (error instanceof Error && error.message.startsWith("memory_pending_"))
+            throw error;
+        throw new Error("memory_pending_directory_unreadable");
+    }
+    return names.sort();
+}
+function version(stat) {
+    return [stat.dev, stat.ino, stat.mode, stat.size, stat.mtimeMs, stat.ctimeMs].join(":");
+}
+export async function pendingDirectorySnapshot(agentDir) {
+    const location = await pendingReadDirectory(agentDir);
+    const names = await pendingFileNames(location.directory);
+    const digest = createHash("sha256").update(location.root);
+    if (location.directory !== null)
+        digest.update(version(await lstat(location.directory)));
+    for (const name of names) {
+        try {
+            digest.update(JSON.stringify([name, version(await lstat(join(location.directory, name)))]));
+        }
+        catch {
+            throw new Error("memory_pending_source_changed");
+        }
+    }
+    return { ...location, names, version: digest.digest("hex") };
+}
+export async function readPendingSource(agentDir, name, byteBudget = PENDING_FILE_BYTES) {
+    if (!name.endsWith(".json") || !PendingIdSchema.safeParse(name.slice(0, -5)).success) {
+        throw new Error("memory_pending_id_invalid");
+    }
+    const { directory } = await pendingReadDirectory(agentDir);
+    if (directory === null)
+        throw new Error("memory_pending_not_found");
+    const path = join(directory, name);
+    const before = await lstat(path).catch(() => { throw new Error("memory_pending_not_found"); });
+    if (!before.isFile() || before.isSymbolicLink())
+        throw new Error("memory_pending_path_invalid");
+    const limit = Math.min(byteBudget, PENDING_FILE_BYTES);
+    if (before.size > limit)
+        throw new Error("memory_pending_file_over_budget");
+    const handle = await open(path, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0) | (constants.O_NONBLOCK ?? 0));
+    try {
+        const opened = await handle.stat();
+        if (!opened.isFile() || version(opened) !== version(before))
+            throw new Error("memory_pending_source_changed");
+        const chunks = [];
+        let bytes = 0;
+        for (;;) {
+            const chunk = Buffer.alloc(Math.min(16 * 1024, limit + 1 - bytes));
+            const { bytesRead } = await handle.read(chunk, 0, chunk.length, null);
+            if (bytesRead === 0)
+                break;
+            bytes += bytesRead;
+            if (bytes > limit)
+                throw new Error("memory_pending_file_over_budget");
+            chunks.push(chunk.subarray(0, bytesRead));
+        }
+        const after = await handle.stat();
+        const currentDirectory = await pendingReadDirectory(agentDir);
+        const current = await lstat(path);
+        if (currentDirectory.directory !== directory || version(after) !== version(opened) || version(current) !== version(opened)) {
+            throw new Error("memory_pending_source_changed");
+        }
+        const buffer = Buffer.concat(chunks);
+        let parsed;
+        try {
+            const raw = new TextDecoder("utf-8", { fatal: true }).decode(buffer);
+            parsed = parsePendingMemoryCandidate(JSON.parse(raw));
+        }
+        catch {
+            throw new Error("memory_pending_file_invalid");
+        }
+        if (`${parsed.pendingId}.json` !== name)
+            throw new Error("memory_pending_id_invalid");
+        return { candidate: parsed, bytes, sha256: createHash("sha256").update(buffer).digest("hex") };
+    }
+    finally {
+        await handle.close();
+    }
+}