@nowcrew/daemon 0.6.101-beta.3 → 0.6.101-beta.5

package/dist/local-memory/runtime.js

@@ -2,6 +2,12 @@ import { createHash } from "node:crypto";
 import { constants } from "node:fs";
 import { lstat, mkdir, open, readFile, rm, writeFile } from "node:fs/promises";
 import { join } from "node:path";
+import { applyMemoryMigration, prepareMemoryMigration, recoverMemoryMigration } from "./migration-store.js";
+import { MigrationStateSchema } from "./migration-schema.js";
+import { detectLocalMemoryStorageVersion } from "./storage-format.js";
+import { isLocalMemoryInitializationIdentity, localMemoryInitializationIdentity } from "./initialization-identity.js";
+import { inventory } from "./migration-io.js";
+import { initializeExactWorkspaceSeed } from "./migration-plan.js";
 import { applyLocalMemoryResult, parseLocalMemoryResult } from "./write.js";
 import { verifyWorkLogSource } from "./work-log.js";
 export function isLocalMemoryV2Eligible(input) {
@@ -12,7 +18,8 @@ export function isLocalMemoryV2Eligible(input) {
     return input.enabledForHandle && input.memoryPrune;
 }
 const LOCAL_MEMORY_V2_MARKER = "v2-enabled";
-export async function initializeLocalMemoryV2(agentDir) {
+const DELIVERY_EVIDENCE_PATTERN = /release(?:[-_.]\S+)?\.md|publish(?:[-_.]\S+)?\.md|build(?:[-_.]\S+)?\.md|deploy(?:[-_.]\S+)?\.md|artifact(?:[-_.]\S+)?\.md|registry|manifest|changelog|tarball|sha256|发布|构建|打包|发版|注册表|交付/iu;
+async function writeLocalMemoryV2Marker(agentDir) {
     const crewDir = join(agentDir, ".crew");
     const memoryDir = join(crewDir, "memory");
     await mkdir(crewDir, { recursive: true });
@@ -31,24 +38,151 @@ export async function initializeLocalMemoryV2(agentDir) {
             throw error;
     }
 }
-export async function initializeLocalMemoryV2ForWorkspace(workspace, enabledForHandle) {
+function initializedIntent(identity, state) {
+    return {
+        ...identity,
+        kind: "server_write_intent",
+        sourceDigest: state.sourceDigest,
+        planDigest: state.planDigest,
+        intentVersion: 1,
+        // New-Agent initialization is derived from the exact pristine seed.  Keep
+        // the receipt deterministic so a crash between intent publication and the
+        // mutable state update can be retried without creating a conflicting fact.
+        confirmedAt: "1970-01-01T00:00:00.000Z",
+    };
+}
+/**
+ * Initialize a pristine new Agent through the same journaled schema2
+ * publication path used by migration.  The marker is written only after the
+ * committed catalog and state have both been verified.
+ */
+async function initializeLocalMemoryV2WithBinding(agentDir, agentId, binding) {
+    const identity = await localMemoryInitializationIdentity(agentDir, agentId, binding);
+    let state = await prepareMemoryMigration({
+        agentDir,
+        identity,
+        serverHistory: { kind: "none", isNewAgent: true },
+    });
+    if (state.origin !== "initialized")
+        throw new Error("local_memory_v2_initialization_source_invalid");
+    if (state.phase === "prepared") {
+        state = await applyMemoryMigration({
+            agentDir,
+            identity,
+            intentReceipt: initializedIntent(identity, state),
+        });
+    }
+    else if (state.phase === "applying" || state.phase === "repair_required") {
+        state = await recoverMemoryMigration({
+            agentDir,
+            identity,
+            intentReceipt: state.intentReceipt ?? initializedIntent(identity, state),
+            stoppedReceipt: {
+                kind: "migration_process_stopped",
+                migrationId: identity.migrationId,
+                machineId: identity.machineId,
+                executionId: identity.executionId,
+                ownerIdentity: identity.ownerIdentity,
+                pid: null,
+                stoppedAt: new Date().toISOString(),
+                proof: "journal_reconciled",
+            },
+            cancelled: false,
+        });
+    }
+    const memory = await readFile(join(agentDir, "MEMORY.md"), "utf8");
+    if (state.phase !== "committed" || state.origin !== "initialized" || state.storageVersion !== 2
+        || detectLocalMemoryStorageVersion(memory) !== 2) {
+        throw new Error("local_memory_v2_initialization_incomplete");
+    }
+    await writeLocalMemoryV2Marker(agentDir);
+}
+/** Fresh initialization requires the identity from the authenticated ready frame. */
+export function initializeLocalMemoryV2(agentDir, agentId, binding) {
+    return initializeLocalMemoryV2WithBinding(agentDir, agentId, binding);
+}
+export async function initializeLocalMemoryV2ForWorkspace(workspace, enabledForHandle, agentId, binding) {
     const initialized = workspace.localMemoryV2Initialized === true;
-    if (!enabledForHandle || initialized || workspace.localMemoryV2Initialized !== false
-        || workspace.agentHomePreexisted === true || workspace.memorySeedCreated !== true)
-        return initialized;
-    try {
-        await initializeLocalMemoryV2(workspace.dir);
+    if (initialized)
         return true;
-    }
-    catch {
+    // Real workspaces always report this boolean.  Keep partial/mock workspace
+    // callers side-effect free instead of probing an unrelated filesystem path.
+    if (workspace.localMemoryV2Initialized !== false)
         return false;
+    let resumable = false;
+    let effectiveBinding = binding;
+    try {
+        const state = MigrationStateSchema.parse(JSON.parse(await readFile(join(workspace.dir, ".crew", "memory", "migration.v1.json"), "utf8")));
+        const identity = await localMemoryInitializationIdentity(workspace.dir, agentId, binding);
+        const legacyIdentity = binding === undefined
+            ? identity
+            : await localMemoryInitializationIdentity(workspace.dir, agentId);
+        resumable = state.origin === "initialized"
+            && state.phase !== "rolled_back"
+            && (isLocalMemoryInitializationIdentity(state.identity, identity)
+                || isLocalMemoryInitializationIdentity(state.identity, legacyIdentity));
+        if (resumable && isLocalMemoryInitializationIdentity(state.identity, legacyIdentity))
+            effectiveBinding = undefined;
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw error;
+        try {
+            const migrations = await lstat(join(workspace.dir, ".crew", "memory", "migrations"));
+            if (!migrations.isDirectory() || migrations.isSymbolicLink()) {
+                throw new Error("local_memory_v2_initialization_residue_invalid");
+            }
+            const identity = await localMemoryInitializationIdentity(workspace.dir, agentId, binding);
+            const legacyIdentity = binding === undefined
+                ? identity
+                : await localMemoryInitializationIdentity(workspace.dir, agentId);
+            let operationIdentity = identity;
+            const operation = await lstat(join(workspace.dir, ".crew", "memory", "migrations", identity.migrationId))
+                .catch(async (error) => {
+                if (error.code !== "ENOENT" || identity.migrationId === legacyIdentity.migrationId)
+                    throw error;
+                operationIdentity = legacyIdentity;
+                return lstat(join(workspace.dir, ".crew", "memory", "migrations", legacyIdentity.migrationId));
+            });
+            if (!operation.isDirectory() || operation.isSymbolicLink()) {
+                throw new Error("local_memory_v2_initialization_residue_invalid");
+            }
+            const current = await inventory(workspace.dir);
+            const memory = current.files.get("MEMORY.md");
+            resumable = current.files.size === 1 && memory !== undefined
+                && current.directories.every(path => path === "notes" || path === ".crew/memory/pending")
+                && initializeExactWorkspaceSeed(memory) !== null;
+            if (resumable && operationIdentity.migrationId === legacyIdentity.migrationId)
+                effectiveBinding = undefined;
+        }
+        catch (residueError) {
+            if (residueError.code !== "ENOENT")
+                throw residueError;
+        }
     }
+    const pristineFirstInitialization = enabledForHandle
+        && workspace.localMemoryV2Initialized === false
+        && workspace.agentHomePreexisted !== true
+        && workspace.memorySeedCreated === true;
+    if (!resumable && !pristineFirstInitialization)
+        return false;
+    // Never create another unbound sentinel. Undefined is retained solely to
+    // finish a pre-upgrade journal already proven above.
+    if (!resumable && effectiveBinding === undefined)
+        return false;
+    await initializeLocalMemoryV2WithBinding(workspace.dir, agentId, effectiveBinding);
+    return true;
 }
 export function localMemoryResultPath(runDir, executionId) {
     const suffix = createHash("sha256").update(executionId, "utf8").digest("hex").slice(0, 32);
     return join(runDir, `.memory-result.v1-${suffix}.json`);
 }
-export function renderLocalMemoryResultInstructions(resultPath) {
+export function renderLocalMemoryResultInstructions(resultPath, storageVersion = 1, migrationDeferred = false) {
+    const storagePolicy = migrationDeferred
+        ? "该 Agent 的旧记忆仍在迁移审阅中。本轮只允许提交新的 create 候选；daemon 会把候选原子保存到 .crew/memory/pending/，reason=legacy_requires_migration，并提供 search-pending/read-pending 查询。候选不会进入 active，也不会自动注入普通上下文；更新、替代和 statusChanges 必须留待迁移完成后按当前 V2 ID/revision/hash 重新核对。旧 MEMORY.md、notes 和已有 active/pending 保持不变。"
+        : storageVersion === 2
+            ? "完整目录保存在 MEMORY.md，模型只看到有界预览；未展示记录仍然有效。涉及旧规则时先用 crew-memory search 查询完整目录，按当前 ID/revision 更新，不因预览未命中就重复新建。20条预览不是有效记录上限；完整存储超出资源上限会拒绝提交，不得自行删除或降级旧记录。已有 pending 仍是未应用候选，须重新核对授权、重复与版本后通过 changes 申请保存，不因迁移自动生效。"
+            : "daemon 会校验、去重、限制 MEMORY.md 大小，超出索引容量的候选会保存在 pending 归档中。容量暂存的 create 可按需检索参考但不能覆盖现行规则；有空间的后续 proposed 提交可提升。未应用的 update/supersede 不进入普通召回，必须重新核对目标版本后处理。";
     return `
 
 ## Structured memory prune (daemon-managed)
@@ -61,17 +195,18 @@ outcome 只允许 no_change、proposed、conflict、failed。新增、更新、
 
 新增记忆的完整合法示例（内容须替换为本任务实际候选）：
 \`\`\`json
-{"schemaVersion":1,"purpose":"memory_prune","baseCatalogRevision":0,"outcome":"proposed","changes":[{"operation":"create","memoryId":null,"baseRevision":null,"supersedesMemoryId":null,"title":"发布验收约定","kind":"procedural","summary":"发布前必须验证回滚步骤。","triggers":["发布","回滚"],"priority":"medium","detailCategory":"project-rules","detailBody":"发布前必须验证回滚步骤，并将验证结果写入发布报告。","reviewAfter":null}],"statusChanges":[]}
+{"schemaVersion":1,"purpose":"memory_prune","baseCatalogRevision":0,"outcome":"proposed","changes":[{"operation":"create","memoryId":null,"baseRevision":null,"supersedesMemoryId":null,"title":"发布验收约定","kind":"procedural","summary":"发布前必须验证回滚步骤。","triggers":["发布","回滚"],"priority":"medium","detailCategory":"project-rules","detailBody":"发布前必须验证回滚步骤，并将验证结果写入发布报告。","reviewAfter":null}],"statusChanges":[],"workLogDisposition":"clear"}
 \`\`\`
 
 没有需要变更的记忆时：
 \`\`\`json
-{"schemaVersion":1,"purpose":"memory_prune","baseCatalogRevision":0,"outcome":"no_change","changes":[],"statusChanges":[]}
+{"schemaVersion":1,"purpose":"memory_prune","baseCatalogRevision":0,"outcome":"no_change","changes":[],"statusChanges":[],"workLogDisposition":"clear"}
 \`\`\`
 
 每个 changes 项须保留示例中的全部字段。operation=create|update|supersede；kind=procedural|semantic|episodic|preference；priority=high|medium|low；detailCategory=preferences|project-rules|testing|debugging|git|incidents|lessons。create 的 memoryId/baseRevision/supersedesMemoryId 必须为 null；update 按现有索引填写 memoryId/baseRevision，supersedesMemoryId 为 null；supersede 填 supersedesMemoryId/baseRevision，memoryId 为 null。
-只提交可复用、与本次任务明确相关的少量候选；不要写入凭证、token、隐私或内部控制标记。daemon 会校验、去重、限制 MEMORY.md 大小，超出索引容量的候选会保存在 pending 归档中。容量暂存的 create 可按需检索参考但不能覆盖现行规则；有空间的后续 proposed 提交可提升。未应用的 update/supersede 不进入普通召回，必须重新核对目标版本后处理。
-写入候选文件只表示提交候选，不能提前宣称已经记住或规则已经更新；daemon 在本轮结束后才处理，候选持久化与进入有效索引也不是同一结果。本结构化轮次覆盖前文提前清理工作日志的要求：保留 $CREW_TASK_LOG，不要清空或删除；daemon 将在处理成功后清理，失败时保留日志和候选用于排查或重试。
+只提交可复用、与本次任务明确相关的少量候选；不要写入凭证、token、隐私或内部控制标记。${storagePolicy}
+发布、构建、打包、发版和注册表交付证据属于任务产物，不是长期记忆；不要直接创建或更新 notes/release.md 或 notes/release-*.md、notes/publish.md 或 notes/publish-*.md、notes/build.md 或 notes/build-*.md、notes/deploy.md 或 notes/deploy-*.md、notes/artifact.md 或 notes/artifact-*.md，也不要把 release/changelog/manifest 证据复制进 MEMORY.md 或 notes。只有明确授权且内容本身是跨任务可复用的流程规则时，才提交 project-rules 候选。
+写入候选文件只表示提交候选，不能提前宣称已经记住或规则已经更新；daemon 在本轮结束后才处理，候选持久化与进入有效索引也不是同一结果。默认保留 $CREW_TASK_LOG；只有确认没有交付证据且所有后置条件满足时，才在 JSON 中显式填写 workLogDisposition="clear"。缺少该字段或填写 preserve 时，daemon 保留日志；daemon 发现日志包含交付证据关键词时会保守保留，即使结果填写 clear；失败、冲突或证据不完整时不得清理。
 `;
 }
 /** Prevent ordinary V2 turns from racing the daemon-managed memory writer. */
@@ -81,6 +216,20 @@ export function renderLocalMemoryV2WriteGuard() {
 ## V2 shared memory write safety
 本节覆盖前文关于普通任务直接更新共享记忆的例外规则。本 Agent 已启用结构化本地记忆 V2。普通任务不得直接编辑共享的 $CREW_HOME/MEMORY.md 或 $CREW_HOME/notes/ 文件；即使用户明确要求记住内容，也只把候选、用户授权和分类理由记录到本任务的 $CREW_TASK_LOG，留给任务结束后的 memory-prune 结构化收尾应用。只有 memory-prune 收尾提示明确要求写入 daemon 提供的 result 文件时，才按该协议提交候选。`;
 }
+async function localMemoryStorageFacts(agentDir) {
+    const memory = await readFile(join(agentDir, "MEMORY.md"), "utf8");
+    const storageVersion = detectLocalMemoryStorageVersion(memory);
+    let committedState = false;
+    try {
+        const state = MigrationStateSchema.parse(JSON.parse(await readFile(join(agentDir, ".crew", "memory", "migration.v1.json"), "utf8")));
+        committedState = state.phase === "committed" && state.storageVersion === 2;
+    }
+    catch (error) {
+        if (error.code !== "ENOENT" && storageVersion === 2)
+            throw error;
+    }
+    return { storageVersion, committedState };
+}
 function workLogFailure(error) {
     const reason = error instanceof Error ? error.message : "";
     return { status: "failed", error: reason === "local_memory_work_log_source_changed"
@@ -98,30 +247,50 @@ export async function commitLocalMemoryResultAfterExit(input) {
             return { status: "missing" };
         return { status: "failed", error: error instanceof Error ? error.message : "read_failed" };
     }
+    let storageBefore;
+    let storageAfter;
+    let applied;
+    let shouldClearWorkLog = false;
     try {
         const result = parseLocalMemoryResult(raw);
         if (result.outcome === "conflict" || result.outcome === "failed") {
             return { status: "failed", error: `local_memory_result_${result.outcome}` };
         }
+        shouldClearWorkLog = result.workLogDisposition === "clear";
         if (input.workLogPath !== undefined) {
             try {
                 await verifyWorkLogSource(input.agentDir, input.workLogPath, input.expectedWorkLogSha256);
+                if (shouldClearWorkLog)
+                    shouldClearWorkLog = !DELIVERY_EVIDENCE_PATTERN.test(await readFile(input.workLogPath, "utf8"));
             }
             catch (error) {
                 return workLogFailure(error);
             }
         }
-        await applyLocalMemoryResult({
+        storageBefore = await localMemoryStorageFacts(input.agentDir);
+        if (input.requiredStorageVersion === 2
+            && (storageBefore.storageVersion !== 2 || !storageBefore.committedState)) {
+            return { status: "failed", error: "local_memory_v2_state_invalid_before_commit" };
+        }
+        applied = await applyLocalMemoryResult({
             agentDir: input.agentDir,
             result,
             executionId: input.executionId,
             pruneTraceId: input.pruneTraceId,
+            ...(input.writerCapabilities === undefined ? {} : { writerCapabilities: input.writerCapabilities }),
+            ...(input.requiredStorageVersion === undefined ? {} : { requiredStorageVersion: input.requiredStorageVersion }),
+            ...(input.migrationDeferredPending ? { migrationDeferredPending: true } : {}),
         });
+        storageAfter = await localMemoryStorageFacts(input.agentDir);
+        if (input.requiredStorageVersion === 2
+            && (storageAfter.storageVersion !== 2 || !storageAfter.committedState)) {
+            return { status: "failed", error: "local_memory_v2_state_invalid_after_commit" };
+        }
     }
     catch (error) {
         return { status: "failed", error: error instanceof Error ? error.message : "apply_failed" };
     }
-    if (input.workLogPath !== undefined) {
+    if (input.workLogPath !== undefined && shouldClearWorkLog) {
         try {
             const before = await verifyWorkLogSource(input.agentDir, input.workLogPath, input.expectedWorkLogSha256);
             const handle = await open(input.workLogPath, constants.O_WRONLY | (constants.O_NOFOLLOW ?? 0) | (constants.O_NONBLOCK ?? 0));
@@ -147,5 +316,10 @@ export async function commitLocalMemoryResultAfterExit(input) {
     catch {
         return { status: "failed", error: "local_memory_result_cleanup_failed" };
     }
-    return { status: "applied" };
+    return { status: "applied", storageVersionBefore: storageBefore.storageVersion,
+        storageVersionAfter: storageAfter.storageVersion, committedState: storageAfter.committedState,
+        createdIds: applied.createdIds, updatedIds: applied.updatedIds,
+        statusChangedIds: applied.statusChangedIds, pendingIds: applied.pendingIds,
+        ...(input.migrationDeferredPending
+            ? { pendingReason: "legacy_requires_migration" } : {}) };
 }

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

@@ -0,0 +1,13 @@
+/**
+ * Files retained for audit/rollback but excluded from current memory coverage.
+ * The patterns are deliberately conservative and only recognize obvious
+ * backup/previous-version names.
+ */
+export function isDeferredMemoryArtifactPath(path) {
+    if (!path.startsWith("notes/"))
+        return false;
+    const name = path.slice("notes/".length);
+    return name === "MEMORY.md"
+        || /^MEMORY\.md(?:\.bak(?:[-_.].*)?|[-_.]20\d{2}[-_]\d{2}[-_]\d{2}.*)$/iu.test(name)
+        || /^(?!bak(?:[-_.]|$)|backup(?:[-_.]|$)|prev(?:[-_.]|$)).*(?:[-_.](?:bak|backup|prev))(?:[-_.]|$).*$/iu.test(name);
+}

package/dist/local-memory/storage-format.js

@@ -0,0 +1,249 @@
+import { LOCAL_MEMORY_INDEX_CODE_POINT_CAP, LOCAL_MEMORY_INDEX_ENTRY_CAP, LOCAL_MEMORY_TOTAL_CODE_POINT_CAP, renderGeneratedIndex, renderLocalMemoryIndexCard, selectLocalMemoryIndexEntries, } from "./index-budget.js";
+export const LOCAL_MEMORY_STORAGE_BYTE_CAP = 16 * 1024 * 1024;
+export const LOCAL_MEMORY_STORAGE_ENTRY_CAP = 10_000;
+export const LOCAL_MEMORY_NOTE_BYTE_CAP = 32 * 1024 * 1024;
+export const LOCAL_MEMORY_READ_BYTE_CAP = 64 * 1024 * 1024;
+export const LOCAL_MEMORY_GENERATED_INDEX_PATTERN = /<!--\s*NOWWORK:MEMORY_INDEX:BEGIN\s+schema=[12]\s*-->[\s\S]*?<!--\s*NOWWORK:MEMORY_INDEX:END\s*-->/u;
+const LEGACY_INDEX_HEADING = /^##[\t ]+Knowledge Index[\t ]*\r?\n/mu;
+const LEGACY_NEXT_SECTION = /^##[\t ]+(?!#)/mu;
+const LEGACY_CARD_HEADING = /^###[\t ]+(.+?)[\t ]*\r?$/gmu;
+const MEMORY_PREVIEW_NOTICE = "[MEMORY.md preview truncated; use crew-memory search/read for more.]\n";
+const length = (text) => {
+    let count = 0;
+    for (const _character of text)
+        count += 1;
+    return count;
+};
+function queryTerms(query) {
+    const normalized = query.normalize("NFKC").toLowerCase();
+    // 空白切词对中文混排请求只会产生一个无法命中的长 token；同时提取英文/数字
+    // 子 token，让 legacy 和 V2 预览共用同一套召回规则。
+    const whitespaceTokens = normalized.split(/\s+/u).filter(Boolean);
+    const alnumTokens = Array.from(normalized.matchAll(/[a-z0-9]{2,}/gu)).map((match) => match[0]);
+    return Array.from(new Set([...whitespaceTokens, ...alnumTokens]));
+}
+function fitsLegacyPreview(text, maxUnits, maxBytes) {
+    return text.length <= maxUnits && Buffer.byteLength(text, "utf8") <= maxBytes;
+}
+function truncateLegacyText(text, maxUnits, maxBytes) {
+    if (maxUnits <= 0 || maxBytes <= 0)
+        return "";
+    let result = "";
+    let units = 0;
+    let bytes = 0;
+    for (const character of text) {
+        const characterBytes = Buffer.byteLength(character, "utf8");
+        if (units + character.length > maxUnits || bytes + characterBytes > maxBytes)
+            break;
+        result += character;
+        units += character.length;
+        bytes += characterBytes;
+    }
+    return result;
+}
+/**
+ * Legacy MEMORY.md has no schema-2 generated index, so the old path used to
+ * inject only the first 6k UTF-16 units and could hide a matching late card.
+ * Keep identity/preamble intact, then select complete legacy cards by query
+ * while retaining the same UTF-16 and UTF-8 byte bounds.
+ */
+export function selectLegacyMemoryPreview(memory, query = "", options = {}) {
+    // Keep legacy behavior: MEMORY_INJECT_CAP historically counted UTF-16 units.
+    const maxUnits = Math.min(LOCAL_MEMORY_TOTAL_CODE_POINT_CAP, options.maxCodePoints ?? Infinity);
+    const maxBytes = options.maxBytes ?? Infinity;
+    if (fitsLegacyPreview(memory, maxUnits, maxBytes))
+        return memory;
+    if (!fitsLegacyPreview(MEMORY_PREVIEW_NOTICE, maxUnits, maxBytes))
+        return "";
+    const heading = LEGACY_INDEX_HEADING.exec(memory);
+    if (heading?.index === undefined) {
+        const noticeBytes = Buffer.byteLength(MEMORY_PREVIEW_NOTICE, "utf8");
+        return `${MEMORY_PREVIEW_NOTICE}${truncateLegacyText(memory, maxUnits - MEMORY_PREVIEW_NOTICE.length, maxBytes - noticeBytes)}`;
+    }
+    const indexStart = heading.index + heading[0].length;
+    const rest = memory.slice(indexStart);
+    const nextSection = LEGACY_NEXT_SECTION.exec(rest);
+    const indexEnd = nextSection?.index === undefined ? memory.length : indexStart + nextSection.index;
+    const indexContent = memory.slice(indexStart, indexEnd);
+    const masked = indexContent.replace(/<!--[\s\S]*?-->/gu, (comment) => comment.replace(/[^\r\n]/gu, " "));
+    const headings = [...masked.matchAll(LEGACY_CARD_HEADING)];
+    if (headings.length === 0) {
+        const noticeBytes = Buffer.byteLength(MEMORY_PREVIEW_NOTICE, "utf8");
+        return `${MEMORY_PREVIEW_NOTICE}${truncateLegacyText(memory, maxUnits - MEMORY_PREVIEW_NOTICE.length, maxBytes - noticeBytes)}`;
+    }
+    const terms = queryTerms(query);
+    const cards = headings.map((card, index) => {
+        const start = card.index ?? 0;
+        const end = headings[index + 1]?.index ?? indexContent.length;
+        const text = indexContent.slice(start, end);
+        const searchable = text.normalize("NFKC").toLowerCase();
+        return {
+            text,
+            index,
+            relevance: terms.filter((term) => searchable.includes(term)).length,
+        };
+    });
+    const ranked = [...cards].sort((left, right) => right.relevance - left.relevance || left.index - right.index);
+    const firstCard = headings[0]?.index ?? 0;
+    const preamble = indexContent.slice(0, firstCard);
+    const before = memory.slice(0, indexStart);
+    const suffix = memory.slice(indexEnd);
+    const fixed = `${MEMORY_PREVIEW_NOTICE}${before}${preamble}`;
+    if (!fitsLegacyPreview(fixed, maxUnits, maxBytes)) {
+        const noticeBytes = Buffer.byteLength(MEMORY_PREVIEW_NOTICE, "utf8");
+        return `${MEMORY_PREVIEW_NOTICE}${truncateLegacyText(memory, maxUnits - MEMORY_PREVIEW_NOTICE.length, maxBytes - noticeBytes)}`;
+    }
+    let selected = fixed;
+    let selectedCount = 0;
+    for (const card of ranked) {
+        const candidate = `${selected}${card.text}`;
+        if (!fitsLegacyPreview(candidate, maxUnits, maxBytes))
+            continue;
+        selected = candidate;
+        selectedCount += 1;
+    }
+    if (selectedCount === 0)
+        return fixed;
+    const withSuffix = `${selected}${suffix}`;
+    return fitsLegacyPreview(withSuffix, maxUnits, maxBytes) ? withSuffix : selected;
+}
+const TYPES = new Set(["procedural", "semantic", "episodic", "preference"]);
+const STATUSES = new Set(["candidate", "active", "pinned", "stale", "superseded", "archived"]);
+const PRIORITIES = new Set(["high", "medium", "low"]);
+const FIELDS = new Set(["id", "file", "type", "status", "summary", "triggers", "priority", "revision", "anchor", "updated", "review_after"]);
+/** A malformed/unknown marker is never treated as an unmarked legacy file. */
+export function detectLocalMemoryStorageVersion(memory) {
+    const markerCount = (memory.match(/NOWWORK:MEMORY_INDEX:/gu) ?? []).length;
+    if (markerCount === 0)
+        return 0;
+    const block = LOCAL_MEMORY_GENERATED_INDEX_PATTERN.exec(memory);
+    if (markerCount !== 2 || block?.index === undefined)
+        throw new Error("local_memory_storage_version_invalid");
+    const headings = [...memory.matchAll(/^##[\t ]+Knowledge Index[\t ]*\r?$/gmu)];
+    const heading = headings[0];
+    if (headings.length !== 1 || heading?.index === undefined)
+        throw new Error("local_memory_storage_index_invalid");
+    const sectionStart = heading.index + heading[0].length;
+    const nextSection = /^##[\t ]+(?!#)/mu.exec(memory.slice(sectionStart));
+    const sectionEnd = nextSection?.index === undefined ? memory.length : sectionStart + nextSection.index;
+    if (block.index < sectionStart || block.index + block[0].length > sectionEnd) {
+        throw new Error("local_memory_storage_index_invalid");
+    }
+    return /schema=2\s*-->/u.test(block[0].slice(0, block[0].indexOf("\n") + 1) || block[0]) ? 2 : 1;
+}
+function validateEntry(entry) {
+    const singleLine = (value) => !/[\r\n\u0000-\u001f\u007f]/u.test(value)
+        && !/<!--/u.test(value);
+    if (!entry.title.trim() || !entry.summary.trim()
+        || ![entry.title, entry.summary, entry.updated, ...entry.triggers].every(singleLine)
+        || !/^[A-Za-z0-9_-]+$/u.test(entry.id) || entry.anchor !== entry.id
+        || !/^notes\/(?:preferences|project-rules|testing|debugging|git|incidents|lessons)\.md$/u.test(entry.file)
+        || !TYPES.has(entry.type) || !STATUSES.has(entry.status) || !PRIORITIES.has(entry.priority)
+        || !Number.isSafeInteger(entry.revision) || entry.revision < 1
+        || !entry.updated.trim()
+        || (entry.reviewAfter !== null && !singleLine(entry.reviewAfter))) {
+        throw new Error("local_memory_storage_entry_invalid");
+    }
+}
+function validateEntries(entries) {
+    if (entries.length > LOCAL_MEMORY_STORAGE_ENTRY_CAP)
+        throw new Error("local_memory_storage_entry_limit");
+    const ids = new Set();
+    for (const entry of entries) {
+        validateEntry(entry);
+        if (ids.has(entry.id))
+            throw new Error("local_memory_storage_duplicate_id");
+        ids.add(entry.id);
+    }
+}
+export function assertLocalMemoryStorageSize(memory) {
+    if (Buffer.byteLength(memory, "utf8") > LOCAL_MEMORY_STORAGE_BYTE_CAP)
+        throw new Error("local_memory_storage_byte_limit");
+}
+/** schema=2 stores every lifecycle state, unlike the schema=1 prompt projection. */
+export function parseFullMemoryIndex(memory) {
+    assertLocalMemoryStorageSize(memory);
+    if (detectLocalMemoryStorageVersion(memory) !== 2)
+        throw new Error("local_memory_storage_version_invalid");
+    const block = LOCAL_MEMORY_GENERATED_INDEX_PATTERN.exec(memory)[0];
+    const body = block.replace(/^<!--[^>]*-->\s*/u, "").replace(/<!--[^>]*-->$/u, "");
+    const headings = [...body.matchAll(/^###[\t ]+(.+?)[\t ]*\r?$/gmu)];
+    if (headings.length > LOCAL_MEMORY_STORAGE_ENTRY_CAP)
+        throw new Error("local_memory_storage_entry_limit");
+    if (body.slice(0, headings[0]?.index ?? body.length).trim())
+        throw new Error("local_memory_storage_entry_invalid");
+    const entries = headings.map((heading, index) => {
+        const fields = {};
+        const tail = body.slice(heading.index + heading[0].length, headings[index + 1]?.index ?? body.length);
+        for (const line of tail.split(/\r?\n/u)) {
+            if (!line.trim())
+                continue;
+            const field = /^-\s+([a-z][a-z_]*)\s*:\s*(.*?)\s*$/u.exec(line);
+            if (!field || !FIELDS.has(field[1]) || fields[field[1]] !== undefined)
+                throw new Error("local_memory_storage_entry_invalid");
+            fields[field[1]] = field[2];
+        }
+        if ([...FIELDS].filter(field => field !== "review_after").some(field => fields[field] === undefined)) {
+            throw new Error("local_memory_storage_entry_invalid");
+        }
+        if (!/^[1-9][0-9]*$/u.test(fields.revision))
+            throw new Error("local_memory_storage_entry_invalid");
+        return {
+            id: fields.id, title: heading[1], file: fields.file, type: fields.type,
+            status: fields.status, summary: fields.summary,
+            triggers: fields.triggers.split(/[,，、]/u).map(value => value.trim()).filter(Boolean),
+            priority: fields.priority, revision: Number(fields.revision),
+            anchor: fields.anchor, updated: fields.updated, reviewAfter: fields.review_after ?? null,
+        };
+    });
+    validateEntries(entries);
+    const section = memory.slice(memory.indexOf("## Knowledge Index") + "## Knowledge Index".length);
+    const remaining = section.replace(LOCAL_MEMORY_GENERATED_INDEX_PATTERN, "").split(/^##[\t ]+(?!#)/mu)[0] ?? "";
+    if (/^###[\t ]+/mu.test(remaining.replace(/<!--[\s\S]*?-->/gu, "")))
+        throw new Error("local_memory_legacy_index_requires_migration");
+    return entries;
+}
+export function renderFullMemoryIndex(entries) {
+    validateEntries(entries);
+    const block = `<!-- NOWWORK:MEMORY_INDEX:BEGIN schema=2 -->\n${entries.map(renderLocalMemoryIndexCard).join("\n")}<!-- NOWWORK:MEMORY_INDEX:END -->`;
+    assertLocalMemoryStorageSize(block);
+    return block;
+}
+export function replaceFullMemoryIndex(memory, entries) {
+    if (detectLocalMemoryStorageVersion(memory) !== 2)
+        throw new Error("local_memory_storage_version_invalid");
+    const updated = memory.replace(LOCAL_MEMORY_GENERATED_INDEX_PATTERN, () => renderFullMemoryIndex(entries));
+    assertLocalMemoryStorageSize(updated);
+    return updated;
+}
+export function selectLocalMemoryPreview(memory, query = "", options = {}) {
+    const entries = parseFullMemoryIndex(memory);
+    const totalActiveEntries = entries.filter(entry => entry.status === "active" || entry.status === "pinned").length;
+    const emptyIndex = renderGeneratedIndex([]);
+    // Reserve the largest count label before selecting; all discovery text counts toward the same cap.
+    const hint = (shown) => `\nMemory preview: ${shown}/${totalActiveEntries} active entries. Use crew-memory search --query <text> and crew-memory read --file <file> for more.\n`;
+    const base = memory.replace(LOCAL_MEMORY_GENERATED_INDEX_PATTERN, () => `${emptyIndex}${hint(totalActiveEntries)}`);
+    const remaining = Math.min(LOCAL_MEMORY_TOTAL_CODE_POINT_CAP, options.maxCodePoints ?? Infinity) - length(base);
+    const remainingBytes = (options.maxBytes ?? Infinity) - Buffer.byteLength(base, "utf8");
+    if (remaining < 0 || remainingBytes < 0 || Number.isNaN(remaining) || Number.isNaN(remainingBytes)) {
+        throw new Error("local_memory_identity_budget_exceeded");
+    }
+    const terms = queryTerms(query);
+    const selection = selectLocalMemoryIndexEntries(entries, {
+        entryCap: LOCAL_MEMORY_INDEX_ENTRY_CAP,
+        indexCodePointCap: Math.min(LOCAL_MEMORY_INDEX_CODE_POINT_CAP - length(emptyIndex), remaining),
+        indexByteCap: remainingBytes,
+    }, {
+        protectedIds: new Set(entries.filter(entry => entry.status === "pinned").map(entry => entry.id)),
+        relevance: entry => {
+            const searchable = `${entry.title} ${entry.summary} ${entry.triggers.join(" ")}`.normalize("NFKC").toLowerCase();
+            return terms.filter(term => searchable.includes(term)).length;
+        },
+    });
+    if (selection.reason === "index_over_budget_pinned")
+        throw new Error("local_memory_pinned_budget_exceeded");
+    return {
+        ...selection, totalActiveEntries,
+        memory: memory.replace(LOCAL_MEMORY_GENERATED_INDEX_PATTERN, () => `${renderGeneratedIndex(selection.entries)}${hint(selection.entries.length)}`),
+    };
+}