@nowcrew/daemon 0.6.91-beta.7 → 0.6.91-beta.9

package/dist/local-memory/migration-io.js

@@ -0,0 +1,199 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { constants } from 'node:fs';
+import { lstat, mkdir, open, opendir, realpath, rename, rm } from 'node:fs/promises';
+import { dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
+import { MigrationError, MigrationIdentitySchema } from './migration-schema.js';
+import { LOCAL_MEMORY_NOTE_BYTE_CAP, LOCAL_MEMORY_READ_BYTE_CAP, LOCAL_MEMORY_STORAGE_BYTE_CAP } from './storage-format.js';
+export const digest = (data) => createHash('sha256').update(data).digest('hex');
+export const STATE_PATH = '.crew/memory/migration.v1.json';
+export async function validateMigrationRoot(agentDir, raw) {
+    const identity = MigrationIdentitySchema.parse(raw);
+    if (!isAbsolute(agentDir) || resolve(agentDir) !== agentDir)
+        throw new MigrationError('migration_root_invalid');
+    // macOS /var -> /private/var is a trusted system alias; the agent root itself may not be a symlink.
+    const stat = await lstat(agentDir);
+    if (!stat.isDirectory() || stat.isSymbolicLink() || String(stat.uid) !== identity.ownerIdentity)
+        throw new MigrationError('migration_owner_invalid');
+    if (digest(await realpath(agentDir)) !== identity.rootFingerprint)
+        throw new MigrationError('migration_root_fingerprint_invalid');
+    return identity;
+}
+export async function safePath(root, path, createParents = false) {
+    const target = resolve(root, path);
+    const rel = relative(root, target);
+    if (!rel || rel.startsWith(`..${sep}`) || rel === '..' || isAbsolute(rel))
+        throw new MigrationError('migration_path_invalid', [{ path, reason: 'outside_root' }]);
+    const parts = rel.split(sep);
+    let current = root;
+    for (let i = 0; i < parts.length; i++) {
+        current = join(current, parts[i]);
+        let stat = await lstat(current).catch((error) => {
+            if (error.code === 'ENOENT')
+                return null;
+            throw error;
+        });
+        if (!stat && createParents && i < parts.length - 1) {
+            await mkdir(current, { mode: 0o700 });
+            stat = await lstat(current);
+        }
+        if (stat?.isSymbolicLink() || (stat && i < parts.length - 1 && !stat.isDirectory()))
+            throw new MigrationError('migration_path_unsafe', [{ path, reason: 'symlink_or_non_directory' }]);
+    }
+    return target;
+}
+export async function readBytes(root, path, cap = LOCAL_MEMORY_NOTE_BYTE_CAP) {
+    const target = await safePath(root, path);
+    const file = await open(target, constants.O_RDONLY | constants.O_NOFOLLOW).catch((error) => {
+        if (error.code === 'ENOENT')
+            return null;
+        throw error;
+    });
+    if (!file)
+        return null;
+    try {
+        const stat = await file.stat();
+        if (!stat.isFile() || stat.size > cap)
+            throw new MigrationError('migration_read_limit', [{ path, reason: 'invalid_file_or_size' }]);
+        const data = Buffer.alloc(stat.size + 1);
+        const { bytesRead } = await file.read(data, 0, data.length, 0);
+        if (bytesRead !== stat.size || (await file.stat()).size !== stat.size)
+            throw new MigrationError('migration_source_changed', [{ path, reason: 'changed_during_read' }]);
+        return data.subarray(0, bytesRead);
+    }
+    finally {
+        await file.close();
+    }
+}
+export async function atomicBytes(root, path, data, options = {}) {
+    const target = await safePath(root, path, true);
+    const temporaryPath = options.temporaryPath ?? `${path}.tmp-${randomUUID()}`;
+    const temp = await safePath(root, temporaryPath, true);
+    if ((await lstat(dirname(target))).dev !== (await lstat(dirname(temp))).dev) {
+        throw new MigrationError('migration_publication_filesystem_mismatch');
+    }
+    const existing = options.temporaryPath ? await readBytes(root, temporaryPath) : null;
+    if (existing && digest(existing) !== digest(data)) {
+        throw new MigrationError('migration_publication_copy_unknown', [{ path: temporaryPath, reason: 'publication_hash_mismatch' }]);
+    }
+    if (!existing) {
+        // The plan-recognized name is only published after every byte is complete and synced.
+        // An interrupted unpublished file is never a recovery source and is preserved as evidence.
+        const writePath = options.temporaryPath
+            ? `${dirname(dirname(temporaryPath))}/unpublished/${randomUUID()}.tmp`
+            : temporaryPath;
+        const unpublished = await safePath(root, writePath, true);
+        if ((await lstat(dirname(unpublished))).dev !== (await lstat(dirname(temp))).dev) {
+            throw new MigrationError('migration_publication_filesystem_mismatch');
+        }
+        const file = await open(unpublished, 'wx', 0o600);
+        try {
+            if (options.temporaryPath) {
+                for (let offset = 0; offset < data.length; offset += 64 * 1024) {
+                    const end = Math.min(offset + 64 * 1024, data.length);
+                    await file.writeFile(data.subarray(offset, end));
+                    await options.afterWriteChunk?.(writePath, end, data.length);
+                }
+            }
+            else
+                await file.writeFile(data);
+            await file.sync();
+        }
+        finally {
+            await file.close();
+        }
+        if (options.temporaryPath) {
+            const complete = await readBytes(root, writePath);
+            if (!complete || digest(complete) !== digest(data))
+                throw new MigrationError('migration_unpublished_copy_invalid');
+            const appeared = await readBytes(root, temporaryPath);
+            if (appeared && digest(appeared) !== digest(data))
+                throw new MigrationError('migration_publication_copy_unknown');
+            if (!appeared) {
+                await safePath(root, temporaryPath);
+                await rename(unpublished, temp);
+                await syncDirectory(dirname(temp));
+                await syncDirectory(dirname(unpublished));
+            }
+        }
+    }
+    try {
+        await options.beforeRename?.();
+        await safePath(root, path);
+        if (options.temporaryPath) {
+            const verified = await readBytes(root, temporaryPath);
+            if (!verified || digest(verified) !== digest(data))
+                throw new MigrationError('migration_publication_copy_unknown');
+        }
+        await rename(temp, target);
+        await syncDirectory(dirname(target));
+    }
+    finally {
+        // Controlled copies survive interruption; recovery verifies their plan-bound name and content before reuse.
+        if (!options.temporaryPath)
+            await rm(temp, { force: true });
+    }
+}
+export async function syncDirectory(path) {
+    const fd = await open(path, 'r');
+    try {
+        await fd.sync();
+    }
+    finally {
+        await fd.close();
+    }
+}
+export async function inventory(root) {
+    const files = new Map();
+    const directories = [];
+    let bytes = 0;
+    let fileCount = 0;
+    let directoryCount = 0;
+    function reserveFile() {
+        if (++fileCount > 20000)
+            throw new MigrationError('migration_file_limit');
+    }
+    function reserveDirectory() {
+        if (++directoryCount > 10000)
+            throw new MigrationError('migration_directory_limit');
+    }
+    async function scan(path, reserved = false) {
+        const target = await safePath(root, path);
+        const stat = await lstat(target).catch((error) => {
+            if (error.code === 'ENOENT')
+                return null;
+            throw error;
+        });
+        if (!stat)
+            return;
+        if (stat.isDirectory()) {
+            if (!reserved)
+                reserveDirectory();
+            directories.push(path);
+            const children = [];
+            for await (const entry of await opendir(target)) {
+                if (entry.isDirectory())
+                    reserveDirectory();
+                else
+                    reserveFile();
+                children.push(entry.name);
+            }
+            for (const name of children.sort())
+                await scan(`${path}/${name}`, true);
+        }
+        else {
+            if (!reserved)
+                reserveFile();
+            const content = await readBytes(root, path, path === 'MEMORY.md' ? LOCAL_MEMORY_STORAGE_BYTE_CAP : LOCAL_MEMORY_NOTE_BYTE_CAP);
+            if (content) {
+                bytes += content.length;
+                if (bytes > LOCAL_MEMORY_READ_BYTE_CAP)
+                    throw new MigrationError('migration_read_limit');
+                files.set(path, content);
+            }
+        }
+    }
+    await scan('MEMORY.md');
+    await scan('notes');
+    await scan('.crew/memory/pending');
+    return { files, directories: directories.sort() };
+}

package/dist/local-memory/migration-plan.js

@@ -0,0 +1,278 @@
+import { digest } from './migration-io.js';
+import { MigrationError, MigrationRecordMappingSchema } from './migration-schema.js';
+import { assertLocalMemoryStorageSize, detectLocalMemoryStorageVersion, LOCAL_MEMORY_GENERATED_INDEX_PATTERN, LOCAL_MEMORY_NOTE_BYTE_CAP, LOCAL_MEMORY_READ_BYTE_CAP, parseFullMemoryIndex, renderFullMemoryIndex, selectLocalMemoryPreview } from './storage-format.js';
+import { memorySeed } from '../workspace.js';
+/** Reproduce the current workspace seed with its original handle and Role before accepting it as pristine. */
+export function initializeExactWorkspaceSeed(bytes) {
+    const memory = bytes.toString('utf8');
+    const prefix = /^# ([^\r\n]+)\n\n## Role\n/u.exec(memory);
+    if (!prefix)
+        return null;
+    const template = memorySeed(prefix[1]);
+    const tail = template.slice(template.indexOf('\n\n## Core Goals\n'));
+    if (!memory.endsWith(tail))
+        return null;
+    const role = memory.slice(prefix[0].length, memory.length - tail.length);
+    if (!bytes.equals(Buffer.from(memorySeed(prefix[1], role))))
+        return null;
+    const heading = '\n## Knowledge Index\n';
+    const insertion = memory.length - tail.length + tail.indexOf(heading) + heading.length;
+    return Buffer.from(`${memory.slice(0, insertion)}${renderFullMemoryIndex([])}\n${memory.slice(insertion)}`);
+}
+const categories = /^(?:preferences|project-rules|testing|debugging|git|incidents|lessons)$/u;
+const blockPattern = /<!--\s*NOWWORK:MEMORY_ENTRY:BEGIN\s+id=([A-Za-z0-9_-]+)\s+revision=([1-9][0-9]*)\s*-->([\s\S]*?)<!--\s*NOWWORK:MEMORY_ENTRY:END\s+id=\1\s*-->/gu;
+const controlMarker = /<!--\s*NOWWORK:MEMORY_/u;
+const harmless = (text) => !text.replace(/<!--[\s\S]*?-->/gu, '').replace(/^#{1,2}[^\n]*$/gmu, '').trim();
+export function validateMigrationTarget(files) {
+    let totalBytes = 0;
+    for (const [path, bytes] of files) {
+        totalBytes += bytes.length;
+        if (bytes.length > LOCAL_MEMORY_NOTE_BYTE_CAP || totalBytes > LOCAL_MEMORY_READ_BYTE_CAP)
+            throw new MigrationError('migration_target_resource_limit', [{ path, reason: 'target_bytes_exceeded' }]);
+    }
+    const memory = files.get('MEMORY.md')?.toString('utf8');
+    if (!memory)
+        throw new MigrationError('migration_memory_missing');
+    const entries = parseFullMemoryIndex(memory);
+    selectLocalMemoryPreview(memory);
+    for (const entry of entries) {
+        const content = files.get(entry.file)?.toString('utf8') ?? '';
+        const blocks = [...content.matchAll(blockPattern)].filter(match => match[1] === entry.id);
+        if (blocks.length !== 1 || Number(blocks[0][2]) > entry.revision)
+            throw new MigrationError('migration_detail_invalid', [{ path: entry.file, reason: `missing_or_newer_detail:${entry.id}` }]);
+    }
+}
+/** Pure conversion; every source range is measured in UTF-16 offsets in the exact UTF-8 decoded source. */
+export function planMemoryMigration(identity, files, supplied = []) {
+    for (const [path, bytes] of files) {
+        if ((path === 'MEMORY.md' || path.startsWith('notes/')) && !Buffer.from(bytes.toString('utf8')).equals(bytes)) {
+            throw new MigrationError('migration_source_encoding_invalid', [{ path, reason: 'invalid_utf8' }]);
+        }
+    }
+    const memory = files.get('MEMORY.md')?.toString('utf8');
+    if (memory === undefined)
+        throw new MigrationError('migration_memory_missing');
+    assertLocalMemoryStorageSize(memory);
+    if (detectLocalMemoryStorageVersion(memory) !== identity.sourceStorageVersion)
+        throw new MigrationError('migration_source_version_mismatch');
+    const confirmedMappings = supplied.map(value => MigrationRecordMappingSchema.parse(value));
+    const mappingSourceDigests = new Map();
+    for (const mapping of confirmedMappings) {
+        if (mapping.sourceSha256 === undefined)
+            continue;
+        const source = files.get(mapping.sourceFile);
+        const actual = source === undefined ? undefined : mappingSourceDigests.get(mapping.sourceFile) ?? digest(source);
+        if (actual !== undefined)
+            mappingSourceDigests.set(mapping.sourceFile, actual);
+        if (actual !== mapping.sourceSha256) {
+            throw new MigrationError('migration_source_changed', [{ path: mapping.sourceFile, reason: 'mapping_source_digest_mismatch', start: mapping.start, end: mapping.end }]);
+        }
+    }
+    const output = new Map(files);
+    const issues = [];
+    let mappings = [];
+    if (identity.sourceStorageVersion === 1) {
+        const upgraded = memory.replace(LOCAL_MEMORY_GENERATED_INDEX_PATTERN, block => block.replace(/schema=1(?=\s*-->)/u, 'schema=2'));
+        const entries = parseFullMemoryIndex(upgraded);
+        const existingIds = new Set(entries.map(entry => entry.id));
+        const additions = confirmedMappings.map(mapping => ({ ...mapping, targetId: mapping.targetId
+                ?? `mem_${digest(`${identity.migrationId}:${mapping.sourceFile}:${mapping.start}:${mapping.end}`).slice(0, 24)}` }));
+        const retainedHistory = new Map();
+        for (const mapping of additions) {
+            const body = files.get(mapping.sourceFile)?.toString('utf8');
+            if (!mapping.sourceFile.startsWith('notes/') || body === undefined || mapping.end > body.length)
+                issues.push({ path: mapping.sourceFile, reason: 'mapping_range_not_unindexed_notes', start: mapping.start, end: mapping.end });
+            if (existingIds.has(mapping.targetId))
+                issues.push({ path: mapping.sourceFile, reason: 'mapping_target_id_conflict' });
+            existingIds.add(mapping.targetId);
+        }
+        for (const [path, bytes] of files) {
+            if (!path.startsWith('notes/'))
+                continue;
+            const content = bytes.toString('utf8');
+            const blocks = [...content.matchAll(blockPattern)];
+            const ranges = additions.filter(mapping => mapping.sourceFile === path);
+            for (const block of blocks) {
+                const entry = entries.find(entry => entry.file === path && entry.id === block[1]);
+                if (!entry) {
+                    const mapping = ranges.find(value => value.start === block.index && value.end === block.index + block[0].length);
+                    // schema1 归档/替代会移除索引而保留正文。只接入确认过的完整历史块，不重包或推断其状态。
+                    if (mapping?.sourceSha256 && mapping.targetId === block[1] && path === `notes/${mapping.category}.md`
+                        && mapping.status !== 'active' && mapping.status !== 'pinned' && !controlMarker.test(block[3]))
+                        retainedHistory.set(mapping.targetId, { revision: Number(block[2]), body: block[3] });
+                    else
+                        issues.push({ path, reason: 'unindexed_detail', start: block.index, end: block.index + block[0].length });
+                }
+                else
+                    mappings.push({ sourceFile: path, start: block.index, end: block.index + block[0].length, scope: `agent:${identity.agentId}`, category: path.slice(6, -3), targetId: entry.id, title: entry.title, status: entry.status });
+            }
+            const covered = [...blocks.map(block => ({ start: block.index, end: block.index + block[0].length })),
+                ...ranges.filter(mapping => !retainedHistory.has(mapping.targetId))].sort((a, b) => a.start - b.start);
+            let cursor = 0, remainder = '';
+            for (const range of covered) {
+                if (range.start < cursor)
+                    issues.push({ path, reason: 'mapping_overlaps_controlled_or_confirmed_range', start: range.start, end: range.end });
+                remainder += content.slice(cursor, range.start);
+                cursor = Math.max(cursor, range.end);
+            }
+            remainder += content.slice(cursor);
+            if (!harmless(remainder))
+                issues.push({ path, reason: 'unindexed_text_requires_mapping' });
+        }
+        for (const mapping of additions) {
+            const body = files.get(mapping.sourceFile)?.toString('utf8').slice(mapping.start, mapping.end) ?? '';
+            if (!retainedHistory.has(mapping.targetId) && controlMarker.test(body))
+                issues.push({ path: mapping.sourceFile, reason: 'mapping_contains_control_marker', start: mapping.start, end: mapping.end });
+        }
+        if (issues.length)
+            throw new MigrationError('migration_needs_review', issues);
+        const appended = new Map();
+        const replacements = new Map();
+        const newEntries = additions.map(mapping => ({ id: mapping.targetId, title: mapping.title,
+            file: `notes/${mapping.category}.md`, type: 'semantic', status: mapping.status,
+            summary: (retainedHistory.get(mapping.targetId)?.body ?? files.get(mapping.sourceFile).toString('utf8').slice(mapping.start, mapping.end)).replace(/\s+/gu, ' ').slice(0, 180),
+            triggers: [], priority: 'medium', updated: '1970-01-01', anchor: mapping.targetId, revision: retainedHistory.get(mapping.targetId)?.revision ?? 1, reviewAfter: null }));
+        for (const mapping of additions) {
+            if (retainedHistory.has(mapping.targetId))
+                continue;
+            const body = files.get(mapping.sourceFile).toString('utf8').slice(mapping.start, mapping.end);
+            const file = `notes/${mapping.category}.md`;
+            const block = `<!-- NOWWORK:MEMORY_ENTRY:BEGIN id=${mapping.targetId} revision=1 -->\n## ${mapping.title}\n\nScope: ${mapping.scope}\n\n${body}\n<!-- NOWWORK:MEMORY_ENTRY:END id=${mapping.targetId} -->\n`;
+            if (mapping.sourceFile === file)
+                replacements.set(file, [...(replacements.get(file) ?? []), { start: mapping.start, end: mapping.end, block }]);
+            else
+                appended.set(file, [...(appended.get(file) ?? []), block]);
+        }
+        for (const path of new Set([...replacements.keys(), ...appended.keys()])) {
+            let content = files.get(path)?.toString('utf8') ?? '';
+            for (const replacement of (replacements.get(path) ?? []).sort((a, b) => b.start - a.start))
+                content = content.slice(0, replacement.start) + replacement.block + content.slice(replacement.end);
+            const blocks = appended.get(path);
+            if (blocks)
+                content += '\n' + blocks.join('\n');
+            output.set(path, Buffer.from(content));
+        }
+        mappings.push(...additions);
+        const target = upgraded.replace(LOCAL_MEMORY_GENERATED_INDEX_PATTERN, () => renderFullMemoryIndex([...entries, ...newEntries]));
+        output.set('MEMORY.md', Buffer.from(target));
+    }
+    else {
+        const knownMetadata = new Map();
+        mappings = confirmedMappings;
+        if (mappings.length > 0) {
+            const heading = /^## Knowledge Index\s*$/mu.exec(memory);
+            if (heading?.index !== undefined) {
+                const start = heading.index + heading[0].length;
+                const tail = memory.slice(start);
+                const next = /^## (?!#)/mu.exec(tail);
+                const end = next?.index === undefined ? memory.length : start + next.index;
+                let uncovered = memory.slice(start, end);
+                for (const mapping of mappings.filter(value => value.sourceFile === 'MEMORY.md').sort((a, b) => b.start - a.start)) {
+                    if (mapping.start < start || mapping.end > end) {
+                        issues.push({ path: 'MEMORY.md', reason: 'mapping_crosses_identity_or_index_boundary' });
+                        continue;
+                    }
+                    uncovered = uncovered.slice(0, mapping.start - start) + ' '.repeat(mapping.end - mapping.start) + uncovered.slice(mapping.end - start);
+                }
+                uncovered = uncovered.replace(/^[-*]\s+\[[^\]]+\]\((notes\/[^)]+)\)\s*$/gmu, (line, path) => mappings.some(value => value.sourceFile === path) ? '' : line);
+                if (uncovered.trim())
+                    issues.push({ path: 'MEMORY.md', reason: 'index_text_requires_mapping', start, end });
+            }
+        }
+        // Known complete cards may declare their exact scope and unique whole-file body.
+        if (mappings.length === 0) {
+            const section = /^## Knowledge Index\s*\n([\s\S]*?)(?=^## (?!#)|$(?![\s\S]))/mu.exec(memory);
+            const content = section?.[1] ?? '';
+            const cards = [...content.matchAll(/^### (.+)\r?\n([\s\S]*?)(?=^### |$(?![\s\S]))/gmu)];
+            if (content.slice(0, cards[0]?.index ?? content.length).trim())
+                issues.push({ path: 'MEMORY.md', reason: 'index_text_requires_mapping' });
+            const seenFiles = new Set();
+            for (const card of cards) {
+                const fieldMatches = [...card[2].matchAll(/^- ([a-z_]+):[^\S\r\n]*(.*)$/gmu)];
+                const fields = Object.fromEntries(fieldMatches.map(match => [match[1], match[2].trim()]));
+                const allowedFields = new Set(['file', 'scope', 'type', 'status', 'summary', 'priority', 'updated', 'triggers', 'review_after', 'id', 'anchor', 'revision']);
+                if (card[2].replace(/^- ([a-z_]+):[^\S\r\n]*(.*)$/gmu, '').trim() || fieldMatches.length !== Object.keys(fields).length || Object.keys(fields).some(key => !allowedFields.has(key))) {
+                    issues.push({ path: 'MEMORY.md', reason: 'card_contains_unmapped_text', start: card.index });
+                    continue;
+                }
+                const path = fields.file ?? '';
+                const category = /^notes\/(.+)\.md$/u.exec(path)?.[1] ?? '';
+                const body = files.get(path)?.toString('utf8');
+                if (!fields.scope || !categories.test(category) || !body?.trim() || seenFiles.has(path)
+                    || !fields.summary || !['procedural', 'semantic', 'episodic', 'preference'].includes(fields.type ?? '') || !fields.status || !['high', 'medium', 'low'].includes(fields.priority ?? '') || !fields.updated) {
+                    issues.push({ path: 'MEMORY.md', reason: 'card_mapping_unconfirmed', start: card.index });
+                    continue;
+                }
+                seenFiles.add(path);
+                const parsed = MigrationRecordMappingSchema.safeParse({ sourceFile: path, start: 0, end: body.length, scope: fields.scope, category, title: card[1], status: fields.status });
+                if (!parsed.success)
+                    issues.push({ path, reason: 'card_metadata_invalid' });
+                else {
+                    mappings.push(parsed.data);
+                    knownMetadata.set(path, { type: fields.type, summary: fields.summary, priority: fields.priority, updated: fields.updated,
+                        triggers: (fields.triggers ?? '').split(/[,，、]/u).map(value => value.trim()).filter(Boolean), reviewAfter: fields.review_after ?? null });
+                }
+            }
+            if (!cards.length)
+                issues.push({ path: 'MEMORY.md', reason: 'legacy_source_requires_mapping' });
+        }
+        const entries = [];
+        for (const mapping of mappings) {
+            const body = files.get(mapping.sourceFile)?.toString('utf8');
+            if (body === undefined || mapping.end > body.length) {
+                issues.push({ path: mapping.sourceFile, reason: 'range_out_of_bounds' });
+                continue;
+            }
+            const id = mapping.targetId ?? `mem_${digest(`${identity.migrationId}:${mapping.sourceFile}:${mapping.start}:${mapping.end}`).slice(0, 24)}`;
+            entries.push({ id, title: mapping.title, file: `notes/${mapping.category}.md`, type: 'semantic', status: mapping.status, summary: body.slice(mapping.start, mapping.end).replace(/\s+/gu, ' ').slice(0, 180),
+                triggers: [], priority: 'medium', updated: '1970-01-01', anchor: id, revision: 1, reviewAfter: null, ...knownMetadata.get(mapping.sourceFile) });
+        }
+        for (const [path, bytes] of files) {
+            if (!path.startsWith('notes/') && path !== 'MEMORY.md')
+                continue;
+            const text = bytes.toString('utf8');
+            const ranges = mappings.filter(mapping => mapping.sourceFile === path).sort((a, b) => a.start - b.start);
+            if (path === 'MEMORY.md')
+                continue; // Retained identity stays byte-for-byte; replaced index coverage is checked above.
+            let cursor = 0;
+            for (const range of ranges) {
+                if (range.start < cursor || text.slice(cursor, range.start).trim())
+                    issues.push({ path, reason: 'mapping_gap_or_overlap', start: cursor, end: range.start });
+                cursor = range.end;
+            }
+            if (text.slice(cursor).trim())
+                issues.push({ path, reason: 'unmapped_source_text', start: cursor, end: text.length });
+        }
+        if (issues.length)
+            throw new MigrationError('migration_needs_review', issues);
+        // Retain original files (external references may exist); only same-path fully covered sources are rewritten.
+        const targets = new Map();
+        mappings.forEach((mapping, index) => {
+            const entry = entries[index];
+            const body = files.get(mapping.sourceFile).toString('utf8').slice(mapping.start, mapping.end);
+            const blocks = targets.get(entry.file) ?? [];
+            targets.set(entry.file, [...blocks, `<!-- NOWWORK:MEMORY_ENTRY:BEGIN id=${entry.id} revision=1 -->\n## ${entry.title}\n\nScope: ${mapping.scope}\n\n${body}\n<!-- NOWWORK:MEMORY_ENTRY:END id=${entry.id} -->\n`]);
+        });
+        for (const [path, blocks] of targets) {
+            const existing = files.get(path);
+            if (existing && !mappings.some(mapping => mapping.sourceFile === path))
+                throw new MigrationError('migration_needs_review', [{ path, reason: 'target_contains_unmapped_text' }]);
+            output.set(path, Buffer.from(blocks.join('\n')));
+        }
+        const index = renderFullMemoryIndex(entries);
+        const heading = /^## Knowledge Index\s*$/mu.exec(memory);
+        let target;
+        if (heading?.index !== undefined) {
+            const start = heading.index + heading[0].length;
+            const tail = memory.slice(start);
+            const next = /^## (?!#)/mu.exec(tail);
+            target = memory.slice(0, start) + `\n${index}\n` + (next?.index === undefined ? '' : tail.slice(next.index));
+        }
+        else
+            target = `${memory}\n\n## Knowledge Index\n${index}\n`;
+        output.set('MEMORY.md', Buffer.from(target));
+        mappings = mappings.map((mapping, index) => ({ ...mapping, targetId: entries[index].id }));
+    }
+    validateMigrationTarget(output);
+    return { files: output, recordMappings: mappings };
+}

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

@@ -0,0 +1,55 @@
+import { z } from 'zod';
+const identifier = z.string().min(1).max(256).regex(/^[A-Za-z0-9_.:@-]+$/u);
+export const MigrationDigestSchema = z.string().regex(/^[a-f0-9]{64}$/u);
+export const MigrationIdentitySchema = z.object({
+    workspaceId: identifier, agentId: identifier, migrationId: identifier,
+    sourceStorageVersion: z.union([z.literal(0), z.literal(1)]), targetStorageVersion: z.literal(2),
+    rootFingerprint: MigrationDigestSchema, ownerIdentity: identifier, machineId: identifier, executionId: identifier,
+}).strict();
+export const MigrationIntentReceiptSchema = MigrationIdentitySchema.extend({
+    kind: z.literal('server_write_intent'), sourceDigest: MigrationDigestSchema, planDigest: MigrationDigestSchema,
+    intentVersion: z.number().int().positive(), confirmedAt: z.string().datetime(),
+}).strict();
+export const MigrationProcessStoppedReceiptSchema = z.object({
+    kind: z.literal('migration_process_stopped'), migrationId: identifier, machineId: identifier,
+    executionId: identifier, ownerIdentity: identifier, pid: z.number().int().positive().nullable(),
+    stoppedAt: z.string().datetime(), proof: z.enum(['supervisor_exit', 'journal_reconciled', 'not_started']),
+}).strict().refine(value => value.proof === 'not_started' ? value.pid === null : value.proof === 'supervisor_exit' ? value.pid !== null : true, 'migration_stop_proof_invalid');
+export const MigrationPathSchema = z.string().max(512).refine(value => (value === 'MEMORY.md' || value === 'notes' || value === '.crew/memory/pending'
+    || value.startsWith('notes/') || value.startsWith('.crew/memory/pending/'))
+    && !/[\\\u0000-\u001f\u007f:]/u.test(value)
+    && value.split('/').every(part => part !== '.' && part !== '..' && part.length > 0), 'migration_path_invalid');
+export const MigrationRecordMappingSchema = z.object({
+    sourceFile: MigrationPathSchema.refine(value => value === 'MEMORY.md' || value.startsWith('notes/'), 'migration_pending_promotion_forbidden'), start: z.number().int().nonnegative(), end: z.number().int().positive(),
+    sourceSha256: MigrationDigestSchema.optional(),
+    scope: z.string().min(1).max(1000), category: z.enum(['preferences', 'project-rules', 'testing', 'debugging', 'git', 'incidents', 'lessons']),
+    targetId: z.string().regex(/^[A-Za-z0-9_-]+$/u).optional(), title: z.string().min(1).max(300),
+    status: z.enum(['active', 'pinned', 'candidate', 'stale', 'superseded', 'archived']).default('active'),
+}).strict().refine(value => value.end > value.start, 'migration_mapping_range_invalid');
+const image = z.discriminatedUnion('exists', [z.object({ exists: z.literal(false) }).strict(),
+    z.object({ exists: z.literal(true), sha256: MigrationDigestSchema, ref: z.string().regex(/^\.crew\/memory\/migrations\/[A-Za-z0-9_.:@-]+\/(?:backup|staged)\/[a-f0-9]{64}$/u), bytes: z.number().int().nonnegative() }).strict()]);
+export const MigrationManifestSchema = z.object({
+    directories: z.array(MigrationPathSchema).max(10000),
+    files: z.array(z.object({ path: MigrationPathSchema, before: image, after: image }).strict()).max(20000),
+    recordMappings: z.array(MigrationRecordMappingSchema).max(10000),
+}).strict();
+export const MigrationIssueSchema = z.object({ path: z.string(), reason: z.string(), start: z.number().optional(), end: z.number().optional() }).strict();
+export const MigrationStateSchema = z.object({
+    schemaVersion: z.literal(1), identity: MigrationIdentitySchema,
+    storageVersion: z.union([z.literal(0), z.literal(1), z.literal(2)]), targetStorageVersion: z.literal(2), origin: z.enum(['migrated', 'initialized']),
+    migrationId: identifier, phase: z.enum(['prepared', 'applying', 'committed', 'rolled_back', 'repair_required']),
+    sourceDigest: MigrationDigestSchema, planDigest: MigrationDigestSchema, manifest: MigrationManifestSchema,
+    intentReceipt: MigrationIntentReceiptSchema.optional(), issues: z.array(MigrationIssueSchema),
+}).strict();
+export const MigrationHistorySchema = z.object({ kind: z.enum(['none', 'existing', 'unavailable']), migrationId: identifier.optional(), writeIntentConfirmed: z.boolean().optional(), isNewAgent: z.boolean().optional(),
+    rolledBackOperations: z.array(z.object({ migrationId: identifier, sourceDigest: MigrationDigestSchema, planDigest: MigrationDigestSchema }).strict()).max(10000).optional(),
+}).strict();
+export class MigrationError extends Error {
+    code;
+    issues;
+    constructor(code, issues = []) {
+        super(code);
+        this.code = code;
+        this.issues = issues;
+    }
+}