@nowcrew/daemon 0.6.91-beta.4 → 0.6.91-beta.5

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

@@ -1,118 +0,0 @@
-import { lstat, mkdir, open, readFile, realpath } from "node:fs/promises";
-import { join } from "node:path";
-import { z } from "zod";
-import { createJournalLease, createJournalLeaseRegistry, JournalLockedError } from "../execution-journal-lock.js";
-import { defaultProcessController } from "../execution-journal.js";
-import { createHash } from "node:crypto";
-import { MigrationStateSchema } from "./migration-schema.js";
-import { detectLocalMemoryStorageVersion, parseFullMemoryIndex } from "./storage-format.js";
-import { readMemoryInventorySource, inventoryLimits } from "./inventory-source.js";
-const StateGate = z.object({
-    schemaVersion: z.literal(1), migrationId: z.string().min(1),
-    phase: z.enum(["prepared", "applying", "committed", "rolled_back", "repair_required"]),
-}).passthrough();
-async function checkedDirectory(parent, name) {
-    const directory = join(parent, name);
-    await mkdir(directory, { recursive: true, mode: 0o700 });
-    const stat = await lstat(directory);
-    if (!stat.isDirectory() || stat.isSymbolicLink() || await realpath(directory) !== directory) {
-        throw new Error("memory_migration_path_invalid");
-    }
-    return directory;
-}
-export async function assertMemoryAccessAllowed(agentDir) {
-    let state = null;
-    try {
-        const source = await readMemoryInventorySource(agentDir, ".crew/memory/migration.v1.json", inventoryLimits.fileBytes);
-        state = StateGate.parse(JSON.parse(source.content));
-        if (state.phase === "applying" || state.phase === "repair_required")
-            throw new Error("memory_migration_in_progress");
-    }
-    catch (error) {
-        if (error instanceof Error && error.message === "memory_migration_in_progress")
-            throw error;
-        if (error.code !== "ENOENT")
-            throw new Error("memory_migration_state_invalid");
-    }
-    let source;
-    try {
-        source = await readMemoryInventorySource(agentDir, "MEMORY.md", inventoryLimits.fileBytes);
-    }
-    catch (error) {
-        if (error.code === "ENOENT" && state === null)
-            return;
-        if (error instanceof Error && error.message === "read_limit_exceeded")
-            throw new Error("memory_file_too_large");
-        throw error;
-    }
-    const version = detectLocalMemoryStorageVersion(source.content);
-    if (version === 2 || state?.phase === "committed") {
-        if (!state)
-            throw new Error("memory_migration_state_missing");
-        const verified = MigrationStateSchema.parse(state);
-        if (verified.phase !== "committed" || verified.storageVersion !== 2 || version !== 2
-            || verified.identity.rootFingerprint !== createHash("sha256").update(await realpath(agentDir)).digest("hex")) {
-            throw new Error("memory_migration_state_invalid");
-        }
-        parseFullMemoryIndex(source.content);
-    }
-}
-/** 复用现有进程身份锁；仅保护一次本地IO，不持锁等待模型，避免子CLI自锁。 */
-export async function withMemoryAccess(agentDir, operation, options = {}) {
-    let created = false;
-    if (options.create) {
-        created = await lstat(agentDir).then(() => false, (e) => { if (e.code === "ENOENT")
-            return true; throw e; });
-        await mkdir(agentDir, { recursive: true, mode: 0o700 });
-    }
-    const root = await realpath(agentDir);
-    if ((await lstat(agentDir)).isSymbolicLink())
-        throw new Error("memory_migration_path_invalid");
-    const crew = await checkedDirectory(root, ".crew");
-    const memory = await checkedDirectory(crew, "memory");
-    const directory = await checkedDirectory(memory, "access.lock");
-    const lease = createJournalLease({ directory, currentPid: process.pid,
-        captureCurrentIdentity: async () => {
-            const identity = await defaultProcessController.inspectIdentity(process.pid);
-            if (!identity)
-                throw new Error("memory_migration_process_unknown");
-            return identity;
-        },
-        inspectIdentity: pid => defaultProcessController.inspectIdentity(pid),
-        registry: createJournalLeaseRegistry(),
-        syncDirectory: async (path) => {
-            if (process.platform === "win32")
-                return;
-            const handle = await open(path, "r");
-            try {
-                await handle.sync();
-            }
-            finally {
-                await handle.close();
-            }
-        },
-    });
-    const deadline = Date.now() + (options.waitMs ?? 2000);
-    for (;;) {
-        try {
-            await lease.acquire();
-            break;
-        }
-        catch (error) {
-            if (!(error instanceof JournalLockedError))
-                throw error;
-            if (Date.now() >= deadline)
-                throw new Error("memory_migration_access_busy");
-            await new Promise(resolve => setTimeout(resolve, 25));
-        }
-    }
-    try {
-        if (!options.maintenance)
-            await assertMemoryAccessAllowed(root);
-        lease.assertUsable();
-        return await operation({ created });
-    }
-    finally {
-        await lease.close();
-    }
-}

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

@@ -1,54 +0,0 @@
-import { isAbsolute, resolve } from 'node:path';
-import { fileURLToPath } from 'node:url';
-import { z } from 'zod';
-import { applyMemoryMigration, prepareMemoryMigration, recoverMemoryMigration, statusMemoryMigration } from './migration-store.js';
-import { MigrationError, MigrationHistorySchema, MigrationIdentitySchema, MigrationIntentReceiptSchema, MigrationProcessStoppedReceiptSchema, MigrationRecordMappingSchema } from './migration-schema.js';
-const base = z.object({ agentDir: z.string().refine(isAbsolute), identity: MigrationIdentitySchema });
-export const MigrationCommandSchema = z.discriminatedUnion('command', [
-    base.extend({ command: z.literal('prepare'), serverHistory: MigrationHistorySchema, recordMappings: z.array(MigrationRecordMappingSchema).max(10000).optional() }).strict(),
-    base.extend({ command: z.literal('status') }).strict(),
-    base.extend({ command: z.literal('apply'), intentReceipt: MigrationIntentReceiptSchema }).strict(),
-    base.extend({ command: z.literal('recover'), serverHistory: MigrationHistorySchema.optional(), intentReceipt: MigrationIntentReceiptSchema.optional(), stoppedReceipt: MigrationProcessStoppedReceiptSchema.optional(), cancelled: z.boolean() }).strict(),
-]);
-export function summarizeMemoryMigration(state) {
-    return { migrationId: state?.migrationId ?? null, phase: state?.phase ?? null, storageVersion: state?.storageVersion ?? null, sourceDigest: state?.sourceDigest ?? null, planDigest: state?.planDigest ?? null,
-        issues: state?.issues ?? [], result: state === null ? 'missing' : state.phase === 'repair_required' ? 'repair_required' : 'success' };
-}
-/** The caller owns the execution/maintenance lease. This boundary never accepts or reads credentials. */
-export async function runMemoryMigrationCommand(raw) {
-    let migrationId = null;
-    try {
-        const input = MigrationCommandSchema.parse(raw);
-        migrationId = input.identity.migrationId;
-        const state = input.command === 'prepare' ? await prepareMemoryMigration(input) : input.command === 'apply' ? await applyMemoryMigration(input)
-            : input.command === 'recover' ? await recoverMemoryMigration(input) : await statusMemoryMigration(input);
-        return summarizeMemoryMigration(state);
-    }
-    catch (error) {
-        const reason = error instanceof MigrationError ? error.code : error instanceof z.ZodError ? 'migration_input_invalid' : 'migration_operation_failed';
-        return { ...summarizeMemoryMigration(null), migrationId, result: reason === 'migration_needs_review' ? 'needs_review' : reason.includes('repair_required') ? 'repair_required' : 'failed',
-            issues: error instanceof MigrationError && error.issues.length ? error.issues : [{ path: '', reason }] };
-    }
-}
-async function main() {
-    try {
-        const chunks = [];
-        let bytes = 0;
-        for await (const chunk of process.stdin) {
-            const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
-            bytes += buffer.length;
-            if (bytes > 8 * 1024 * 1024)
-                throw new Error('input_limit');
-            chunks.push(buffer);
-        }
-        const result = await runMemoryMigrationCommand(JSON.parse(Buffer.concat(chunks).toString('utf8')));
-        process.stdout.write(`${JSON.stringify(result)}\n`);
-        process.exitCode = result.result === 'success' || result.result === 'missing' ? 0 : 1;
-    }
-    catch {
-        process.stdout.write(`${JSON.stringify({ ...summarizeMemoryMigration(null), result: 'failed', issues: [{ path: '', reason: 'migration_input_invalid' }] })}\n`);
-        process.exitCode = 1;
-    }
-}
-if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url))
-    void main();

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

@@ -1,199 +0,0 @@
-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

@@ -1,278 +0,0 @@
-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 };
-}