@nowcrew/daemon 0.6.99 → 0.6.100-beta.1

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;
+    }
+}

package/dist/local-memory/migration-state-invariants.js

@@ -0,0 +1,65 @@
+import { createHash } from 'node:crypto';
+import { MigrationError, MigrationIntentReceiptSchema, } from './migration-schema.js';
+export const migrationOperationRoot = (identity) => `.crew/memory/migrations/${identity.migrationId}`;
+function canonical(data) {
+    if (Array.isArray(data))
+        return data.map(canonical);
+    if (data !== null && typeof data === 'object') {
+        return Object.fromEntries(Object.entries(data)
+            .sort(([left], [right]) => left.localeCompare(right))
+            .map(([key, value]) => [key, canonical(value)]));
+    }
+    return data;
+}
+export const encodeMigrationData = (data) => Buffer.from(JSON.stringify(canonical(data)));
+export const sameMigrationData = (left, right) => encodeMigrationData(left).equals(encodeMigrationData(right));
+export function migrationPlanDigest(identity, sourceDigest, manifest) {
+    return createHash('sha256')
+        .update(encodeMigrationData({ identity, sourceDigest, manifest }))
+        .digest('hex');
+}
+export function verifyMigrationIntent(receipt, state) {
+    const parsed = MigrationIntentReceiptSchema.parse(receipt);
+    for (const key of Object.keys(state.identity)) {
+        if (parsed[key] !== state.identity[key])
+            throw new MigrationError('migration_intent_identity_mismatch');
+    }
+    if (parsed.sourceDigest !== state.sourceDigest || parsed.planDigest !== state.planDigest) {
+        throw new MigrationError('migration_intent_digest_mismatch');
+    }
+    return parsed;
+}
+/** Pure validation shared by migration recovery and read-only inventory. */
+export function assertMigrationStateIntegrity(state, identity) {
+    if (!sameMigrationData(state.identity, identity) || state.migrationId !== identity.migrationId
+        || state.planDigest !== migrationPlanDigest(identity, state.sourceDigest, state.manifest)) {
+        throw new MigrationError('migration_identity_or_manifest_invalid');
+    }
+    // A prepared/applying/rolled-back journal still describes the source store;
+    // only a committed journal describes the V2 target.  repair_required may
+    // represent either side because it can be recorded after a committed target
+    // is found damaged.  Reject contradictory states before any recovery or
+    // pending-only escape hatch can use them.
+    const sourceVersion = state.identity.sourceStorageVersion;
+    const sourcePhase = state.phase === 'prepared' || state.phase === 'applying' || state.phase === 'rolled_back';
+    if (state.origin === 'initialized' && sourceVersion !== 0
+        || sourcePhase && state.storageVersion !== sourceVersion
+        || state.phase === 'committed' && state.storageVersion !== state.targetStorageVersion
+        || state.targetStorageVersion !== identity.targetStorageVersion) {
+        throw new MigrationError('migration_identity_or_manifest_invalid');
+    }
+    const paths = state.manifest.files.map(file => file.path);
+    if (new Set(paths).size !== paths.length || !paths.includes('MEMORY.md')) {
+        throw new MigrationError('migration_manifest_invalid');
+    }
+    const operationRoot = `${migrationOperationRoot(identity)}/`;
+    for (const file of state.manifest.files) {
+        for (const image of [file.before, file.after]) {
+            if (image.exists && !image.ref.startsWith(operationRoot)) {
+                throw new MigrationError('migration_manifest_invalid');
+            }
+        }
+    }
+    if (state.intentReceipt !== undefined)
+        verifyMigrationIntent(state.intentReceipt, state);
+}

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

@@ -0,0 +1,414 @@
+import { statfs, rm, readdir, opendir } from 'node:fs/promises';
+import { dirname } from 'node:path';
+import { z } from 'zod';
+import { atomicBytes, digest, inventory, readBytes, safePath, STATE_PATH, syncDirectory, validateMigrationRoot } from './migration-io.js';
+import { initializeExactWorkspaceSeed, planMemoryMigration, validateMigrationTarget } from './migration-plan.js';
+import { MigrationError, MigrationHistorySchema, MigrationProcessStoppedReceiptSchema, MigrationStateSchema } from './migration-schema.js';
+import { inspectManagedDetailFilesWithMappings } from './inventory-v2.js';
+import { assertMigrationStateIntegrity as assertIdentity, encodeMigrationData as encode, migrationOperationRoot as opRoot, migrationPlanDigest as planDigest, sameMigrationData as same, verifyMigrationIntent as verifyIntent, } from './migration-state-invariants.js';
+import { detectLocalMemoryStorageVersion, parseFullMemoryIndex } from './storage-format.js';
+import { isLocalMemoryInitializationIdentity, localMemoryInitializationIdentity } from './initialization-identity.js';
+async function immutable(root, path, data) {
+    const previous = await readBytes(root, path, 64 * 1024 * 1024);
+    if (previous) {
+        if (digest(previous) !== digest(data))
+            throw new MigrationError('migration_immutable_hash_mismatch', [{ path, reason: 'hash_mismatch' }]);
+        return;
+    }
+    await atomicBytes(root, path, data);
+}
+async function save(root, state) {
+    const parsed = MigrationStateSchema.parse(state);
+    assertIdentity(parsed, parsed.identity);
+    if (parsed.phase === 'committed' || parsed.phase === 'rolled_back') {
+        const previous = await readBytes(root, `${opRoot(parsed.identity)}/terminal.json`, 32 * 1024 * 1024);
+        if (previous && !same(JSON.parse(previous.toString('utf8')), parsed)) {
+            throw new MigrationError('migration_terminal_conflict');
+        }
+    }
+    await atomicBytes(root, STATE_PATH, encode(parsed));
+    // State is the commit point. Retain the same terminal fact separately so accidental state loss cannot replay a completed plan.
+    if (parsed.phase === 'committed' || parsed.phase === 'rolled_back')
+        await immutable(root, `${opRoot(parsed.identity)}/terminal.json`, encode(parsed));
+    return parsed;
+}
+async function readState(root) {
+    const bytes = await readBytes(root, STATE_PATH, 32 * 1024 * 1024);
+    if (!bytes)
+        return null;
+    let state;
+    try {
+        state = MigrationStateSchema.parse(JSON.parse(bytes.toString('utf8')));
+    }
+    catch {
+        throw new MigrationError('migration_state_invalid');
+    }
+    return state;
+}
+async function load(input) {
+    const state = await readState(input.agentDir);
+    if (state)
+        assertIdentity(state, input.identity);
+    return state;
+}
+export async function statusMemoryMigration(input) {
+    const identity = await validateMigrationRoot(input.agentDir, input.identity);
+    return load({ ...input, identity });
+}
+export async function prepareMemoryMigration(input, hooks = {}) {
+    const identity = await validateMigrationRoot(input.agentDir, input.identity);
+    const history = MigrationHistorySchema.parse(input.serverHistory);
+    const existing = await readState(input.agentDir);
+    if (existing?.migrationId === identity.migrationId) {
+        assertIdentity(existing, identity);
+        return existing;
+    }
+    if (history.kind !== 'none' || history.writeIntentConfirmed === true)
+        throw new MigrationError(history.kind === 'existing' ? 'migration_recovery_required' : 'migration_server_history_unavailable');
+    const operations = await readdir(await safePath(input.agentDir, '.crew/memory/migrations')).catch((error) => {
+        if (error.code === 'ENOENT')
+            return [];
+        throw error;
+    });
+    await verifyRolledBackPredecessors(input.agentDir, identity, history, operations, existing);
+    const leftovers = await readBytes(input.agentDir, `${opRoot(identity)}/manifest.json`, 32 * 1024 * 1024);
+    if (leftovers) {
+        const prepared = MigrationStateSchema.parse(JSON.parse(leftovers.toString('utf8')));
+        assertIdentity(prepared, identity);
+        const intent = await readBytes(input.agentDir, `${opRoot(identity)}/intent.json`);
+        const current = await classify(input.agentDir, prepared);
+        if (intent || current.unknown.length || current.classes.some(value => value !== 'B' && value !== 'AB'))
+            throw new MigrationError('migration_recovery_required');
+        if (!await copies(input.agentDir, prepared, 'before') || !await copies(input.agentDir, prepared, 'after'))
+            throw new MigrationError('migration_copy_invalid');
+        return save(input.agentDir, prepared);
+    }
+    const before = await inventory(input.agentDir);
+    const sourceMemory = before.files.get('MEMORY.md');
+    if (history.isNewAgent === true && identity.sourceStorageVersion === 0 && before.files.size === 0 && before.directories.length === 0)
+        throw new MigrationError('migration_workspace_seed_required');
+    const previousSeed = existing?.origin === 'initialized' && existing.phase === 'rolled_back'
+        ? existing.manifest.files.find(file => file.path === 'MEMORY.md')?.before : undefined;
+    const retryingOriginalSeed = previousSeed?.exists === true && sourceMemory !== undefined && digest(sourceMemory) === previousSeed.sha256;
+    const expectedInitializationIdentity = await localMemoryInitializationIdentity(input.agentDir, identity.agentId, {
+        workspaceId: identity.workspaceId,
+        machineId: identity.machineId,
+    });
+    const onlyCurrentOperationResidue = isLocalMemoryInitializationIdentity(identity, expectedInitializationIdentity)
+        && existing === null && operations.length === 1
+        && operations[0] === identity.migrationId;
+    const pristineSeed = (history.isNewAgent === true && (operations.length === 0 || onlyCurrentOperationResidue) || retryingOriginalSeed) && identity.sourceStorageVersion === 0
+        && before.files.size === 1 && sourceMemory !== undefined && before.directories.every(path => path === 'notes' || path === '.crew/memory/pending')
+        ? initializeExactWorkspaceSeed(sourceMemory) : null;
+    const initialized = history.isNewAgent === true && identity.sourceStorageVersion === 0
+        && pristineSeed !== null;
+    const after = pristineSeed !== null ? { files: new Map([['MEMORY.md', pristineSeed]]), recordMappings: [] } : planMemoryMigration(identity, before.files, input.recordMappings);
+    if (pristineSeed !== null)
+        validateMigrationTarget(after.files);
+    const paths = [...new Set([...before.files.keys(), ...after.files.keys()])].sort();
+    const manifest = { directories: before.directories, recordMappings: after.recordMappings, files: paths.map(path => {
+            const b = before.files.get(path);
+            const a = after.files.get(path);
+            return { path, before: b ? { exists: true, sha256: digest(b), ref: `${opRoot(identity)}/backup/${digest(b)}`, bytes: b.length } : { exists: false },
+                after: a ? { exists: true, sha256: digest(a), ref: `${opRoot(identity)}/staged/${digest(a)}`, bytes: a.length } : { exists: false } };
+        }) };
+    const sourceDigest = digest(encode({ directories: before.directories, files: manifest.files.map(file => ({ path: file.path, before: file.before.exists ? { exists: true, sha256: file.before.sha256 } : { exists: false } })) }));
+    const state = { schemaVersion: 1, identity, storageVersion: identity.sourceStorageVersion, targetStorageVersion: 2, origin: initialized ? 'initialized' : 'migrated', migrationId: identity.migrationId, phase: 'prepared', sourceDigest,
+        planDigest: planDigest(identity, sourceDigest, manifest), manifest, issues: [] };
+    MigrationStateSchema.parse(state);
+    const beforeBytes = [...before.files.values()].reduce((sum, value) => sum + value.length, 0);
+    const afterBytes = [...after.files.values()].reduce((sum, value) => sum + value.length, 0);
+    const max = Math.max(0, ...[...before.files.values(), ...after.files.values()].map(value => value.length));
+    const available = hooks.availableBytes ? await hooks.availableBytes() : await statfs(input.agentDir).then(value => value.bavail * value.bsize);
+    if (available < beforeBytes + afterBytes + max + encode(state).length * 3)
+        throw new MigrationError('migration_insufficient_disk_space');
+    for (const file of manifest.files) {
+        if (file.before.exists)
+            await immutable(input.agentDir, file.before.ref, before.files.get(file.path));
+        if (file.after.exists)
+            await immutable(input.agentDir, file.after.ref, after.files.get(file.path));
+    }
+    const current = await inventory(input.agentDir);
+    if (!same([...current.files].map(([path, bytes]) => [path, digest(bytes)]), [...before.files].map(([path, bytes]) => [path, digest(bytes)])) || !same(current.directories, before.directories))
+        throw new MigrationError('migration_source_changed');
+    await immutable(input.agentDir, `${opRoot(identity)}/manifest.json`, encode(state));
+    return save(input.agentDir, state);
+}
+/** 新操作只接纳服务端明确授权、摘要相符的回退终态；旧备份和历史保持不可变。 */
+async function verifyRolledBackPredecessors(root, identity, history, operations, existing) {
+    const authorized = history.rolledBackOperations ?? [];
+    const allowed = new Map(authorized.map(operation => [operation.migrationId, operation]));
+    if (allowed.size !== authorized.length || allowed.has(identity.migrationId)
+        || authorized.length > 0 && history.migrationId !== identity.migrationId
+        || operations.some(name => name !== identity.migrationId && !allowed.has(name))
+        || authorized.some(operation => !operations.includes(operation.migrationId))
+        || existing && !allowed.has(existing.migrationId))
+        throw new MigrationError('migration_operation_residue');
+    for (const previous of authorized) {
+        const bytes = await readBytes(root, `.crew/memory/migrations/${previous.migrationId}/terminal.json`, 32 * 1024 * 1024);
+        if (!bytes)
+            throw new MigrationError('migration_rollback_history_invalid');
+        const terminal = MigrationStateSchema.parse(JSON.parse(bytes.toString('utf8')));
+        assertIdentity(terminal, terminal.identity);
+        if (terminal.phase !== 'rolled_back' || terminal.migrationId !== previous.migrationId
+            || terminal.sourceDigest !== previous.sourceDigest || terminal.planDigest !== previous.planDigest
+            || terminal.storageVersion !== terminal.identity.sourceStorageVersion
+            || ['workspaceId', 'agentId', 'rootFingerprint', 'ownerIdentity', 'machineId'].some(key => terminal.identity[key] !== identity[key])
+            || existing?.migrationId === terminal.migrationId && !same(existing, terminal))
+            throw new MigrationError('migration_rollback_history_invalid');
+        const manifest = await readBytes(root, `${opRoot(terminal.identity)}/manifest.json`, 32 * 1024 * 1024);
+        if (!manifest)
+            throw new MigrationError('migration_rollback_history_invalid');
+        const prepared = MigrationStateSchema.parse(JSON.parse(manifest.toString('utf8')));
+        assertIdentity(prepared, terminal.identity);
+        if (prepared.planDigest !== terminal.planDigest || !await copies(root, terminal, 'before'))
+            throw new MigrationError('migration_rollback_history_invalid');
+    }
+}
+function matches(bytes, image) { return image.exists ? bytes !== undefined && digest(bytes) === image.sha256 : bytes === undefined; }
+function publicationPath(state, path, sha256) {
+    return `${opRoot(state.identity)}/publish/${digest(path)}-${sha256}.tmp`;
+}
+async function validatePublicationCopies(root, state) {
+    const directory = `${opRoot(state.identity)}/publish`;
+    const allowed = new Map();
+    for (const file of state.manifest.files)
+        for (const image of [file.before, file.after]) {
+            if (image.exists)
+                allowed.set(publicationPath(state, file.path, image.sha256), image.sha256);
+        }
+    const stream = await opendir(await safePath(root, directory)).catch((error) => {
+        if (error.code === 'ENOENT')
+            return null;
+        throw error;
+    });
+    if (!stream)
+        return;
+    for await (const entry of stream) {
+        const path = `${directory}/${entry.name}`;
+        const expected = allowed.get(path);
+        if (!expected || !entry.isFile())
+            throw new MigrationError('migration_publication_copy_unknown', [{ path, reason: 'unrecognized_publication_copy' }]);
+        const content = await readBytes(root, path);
+        if (!content || digest(content) !== expected)
+            throw new MigrationError('migration_publication_copy_unknown', [{ path, reason: 'publication_hash_mismatch' }]);
+    }
+}
+async function classify(root, state) {
+    await validatePublicationCopies(root, state);
+    const current = await inventory(root);
+    const known = new Set(state.manifest.files.map(file => file.path));
+    const allowedDirs = new Set(state.manifest.directories);
+    for (const file of state.manifest.files)
+        if (file.after.exists) {
+            let dir = dirname(file.path);
+            while (dir !== '.' && dir !== '.crew' && dir !== '.crew/memory') {
+                allowedDirs.add(dir);
+                dir = dirname(dir);
+            }
+        }
+    const unknown = [...current.files.keys()].filter(path => !known.has(path));
+    unknown.push(...current.directories.filter(path => !allowedDirs.has(path)), ...state.manifest.directories.filter(path => !current.directories.includes(path)));
+    return { files: current.files, unknown, classes: state.manifest.files.map(file => { const b = matches(current.files.get(file.path), file.before), a = matches(current.files.get(file.path), file.after); return a && b ? 'AB' : a ? 'A' : b ? 'B' : 'X'; }) };
+}
+async function copies(root, state, side) {
+    const files = new Map();
+    try {
+        for (const file of state.manifest.files) {
+            const image = file[side];
+            if (image.exists) {
+                const bytes = await readBytes(root, image.ref);
+                if (!bytes || bytes.length !== image.bytes || digest(bytes) !== image.sha256)
+                    return null;
+                files.set(file.path, bytes);
+            }
+        }
+    }
+    catch {
+        return null;
+    }
+    return files;
+}
+async function repair(root, state, paths, reason) { return save(root, { ...state, phase: 'repair_required', issues: paths.map(path => ({ path, reason })) }); }
+async function publish(root, state, side, hooks) {
+    let index = 0;
+    for (const file of state.manifest.files) {
+        const current = await readBytes(root, file.path);
+        const bytes = current ?? undefined;
+        if (matches(bytes, file[side]))
+            continue;
+        const opposite = file[side === 'after' ? 'before' : 'after'];
+        if (!matches(bytes, opposite))
+            throw new MigrationError('migration_unknown_change', [{ path: file.path, reason: 'changed_before_replace' }]);
+        const image = file[side];
+        if (image.exists) {
+            const data = await readBytes(root, image.ref);
+            if (!data || digest(data) !== image.sha256)
+                throw new MigrationError('migration_copy_invalid');
+            const temporaryPath = publicationPath(state, file.path, image.sha256);
+            await atomicBytes(root, file.path, data, { temporaryPath, beforeRename: () => hooks.beforeReplace?.(file.path, temporaryPath, index),
+                afterWriteChunk: (writtenPath, written, total) => hooks.afterPublicationWrite?.(file.path, writtenPath, written, total) });
+        }
+        else {
+            const target = await safePath(root, file.path);
+            await rm(target);
+            await syncDirectory(dirname(target));
+        }
+        await hooks.afterReplace?.(file.path, index++);
+    }
+}
+function validTarget(files, mappings = [], sourceHashes = new Map()) {
+    try {
+        validateMigrationTarget(files);
+        const memory = files.get('MEMORY.md');
+        if (memory === undefined)
+            return false;
+        const entries = [...parseFullMemoryIndex(memory.toString('utf8'))];
+        const sources = [...files]
+            .filter(([path]) => path === 'MEMORY.md' || path.startsWith('notes/'))
+            .map(([path, bytes]) => ({ path, bytes: bytes.length, sha256: digest(bytes), content: bytes.toString('utf8') }));
+        const inspection = inspectManagedDetailFilesWithMappings(entries, sources, mappings, sourceHashes);
+        return inspection.fileIssues.length === 0 && inspection.entryIssues.size === 0;
+    }
+    catch {
+        return false;
+    }
+}
+function manifestSourceHashes(manifest) {
+    return new Map(manifest.files
+        .flatMap(file => file.before.exists ? [[file.path, file.before.sha256]] : []));
+}
+async function finalState(input, state) {
+    const terminalPath = `${opRoot(state.identity)}/terminal.json`;
+    const bytes = await readBytes(input.agentDir, terminalPath, 32 * 1024 * 1024);
+    let terminal = null;
+    if (bytes) {
+        terminal = MigrationStateSchema.parse(JSON.parse(bytes.toString('utf8')));
+        assertIdentity(terminal, input.identity);
+        if ((terminal.phase !== 'committed' && terminal.phase !== 'rolled_back') || terminal.planDigest !== state.planDigest)
+            throw new MigrationError('migration_terminal_invalid');
+    }
+    else if (state.phase === 'committed' || state.phase === 'rolled_back') {
+        // Persist the already-published commit point before any content-health update can replace the mutable state.
+        await immutable(input.agentDir, terminalPath, encode(state));
+        terminal = state;
+    }
+    if (terminal?.phase === 'committed') {
+        let valid = false;
+        try {
+            valid = validTarget((await inventory(input.agentDir)).files, state.manifest.recordMappings, manifestSourceHashes(state.manifest));
+        }
+        catch { /* Protect damaged content without erasing commit history. */ }
+        if (!valid)
+            return repair(input.agentDir, terminal, ['MEMORY.md'], 'committed_target_invalid');
+        return same(state, terminal) ? terminal : save(input.agentDir, terminal);
+    }
+    if (terminal?.phase === 'rolled_back')
+        return same(state, terminal) ? terminal : save(input.agentDir, terminal);
+    return null;
+}
+export async function applyMemoryMigration(input, hooks = {}) {
+    await validateMigrationRoot(input.agentDir, input.identity);
+    let state = await load(input);
+    if (!state)
+        throw new MigrationError('migration_state_missing');
+    const done = await finalState(input, state);
+    if (done)
+        return done;
+    if (state.phase !== 'prepared')
+        throw new MigrationError('migration_recovery_required');
+    const receipt = verifyIntent(input.intentReceipt, state);
+    const classification = await classify(input.agentDir, state);
+    if (classification.unknown.length || classification.classes.some(value => value !== 'B' && value !== 'AB'))
+        return repair(input.agentDir, state, classification.unknown.length ? classification.unknown : ['MEMORY.md'], 'source_changed');
+    const backup = await copies(input.agentDir, state, 'before'), staged = await copies(input.agentDir, state, 'after');
+    if (!backup || !staged || !validTarget(staged, state.manifest.recordMappings, manifestSourceHashes(state.manifest)))
+        throw new MigrationError('migration_copy_invalid');
+    await immutable(input.agentDir, `${opRoot(state.identity)}/intent.json`, encode(receipt));
+    state = await save(input.agentDir, { ...state, phase: 'applying', intentReceipt: receipt });
+    await publish(input.agentDir, state, 'after', hooks);
+    const current = await classify(input.agentDir, state);
+    if (current.unknown.length || current.classes.some(value => value === 'X' || value === 'B') || !validTarget(current.files, state.manifest.recordMappings, manifestSourceHashes(state.manifest)))
+        return repair(input.agentDir, state, ['MEMORY.md'], 'target_validation_failed');
+    return save(input.agentDir, { ...state, phase: 'committed', storageVersion: 2 });
+}
+export async function recoverMemoryMigration(input, hooks = {}) {
+    await validateMigrationRoot(input.agentDir, input.identity);
+    let state = await readState(input.agentDir);
+    if (state && state.migrationId !== input.identity.migrationId) {
+        const history = MigrationHistorySchema.parse(input.serverHistory);
+        if (history.kind !== 'existing' || history.migrationId !== input.identity.migrationId)
+            throw new MigrationError('migration_history_missing_or_mismatch');
+        const operations = await readdir(await safePath(input.agentDir, '.crew/memory/migrations'));
+        await verifyRolledBackPredecessors(input.agentDir, input.identity, history, operations, state);
+        state = null;
+    }
+    if (state)
+        assertIdentity(state, input.identity);
+    if (!state) {
+        const history = MigrationHistorySchema.parse(input.serverHistory);
+        if (history.kind !== 'existing' || history.migrationId !== input.identity.migrationId)
+            throw new MigrationError('migration_history_missing_or_mismatch');
+        const terminal = await readBytes(input.agentDir, `${opRoot(input.identity)}/terminal.json`, 32 * 1024 * 1024);
+        if (terminal) {
+            const terminalState = MigrationStateSchema.parse(JSON.parse(terminal.toString('utf8')));
+            assertIdentity(terminalState, input.identity);
+            if (terminalState.phase !== 'committed' && terminalState.phase !== 'rolled_back')
+                throw new MigrationError('migration_terminal_invalid');
+            const final = await finalState(input, terminalState);
+            if (final)
+                return save(input.agentDir, final);
+        }
+        const bytes = await readBytes(input.agentDir, `${opRoot(input.identity)}/manifest.json`, 32 * 1024 * 1024);
+        if (!bytes)
+            throw new MigrationError('migration_manifest_missing_repair_required');
+        state = MigrationStateSchema.parse(JSON.parse(bytes.toString('utf8')));
+        assertIdentity(state, input.identity);
+        const receipt = await readBytes(input.agentDir, `${opRoot(input.identity)}/intent.json`);
+        if (receipt)
+            state = { ...state, phase: 'applying', intentReceipt: verifyIntent(JSON.parse(receipt.toString('utf8')), state) };
+        else if (history.writeIntentConfirmed && !input.intentReceipt)
+            throw new MigrationError('migration_intent_receipt_required');
+    }
+    const done = await finalState(input, state);
+    if (done)
+        return done;
+    const stopped = MigrationProcessStoppedReceiptSchema.parse(input.stoppedReceipt);
+    if (stopped.migrationId !== state.migrationId || stopped.machineId !== state.identity.machineId || stopped.executionId !== state.identity.executionId || stopped.ownerIdentity !== state.identity.ownerIdentity
+        || (stopped.proof === 'not_started' && (state.phase !== 'prepared' || state.intentReceipt || input.intentReceipt)))
+        throw new MigrationError('migration_stop_proof_invalid');
+    const cancelled = z.boolean().parse(input.cancelled);
+    let receipt = state.intentReceipt;
+    if (input.intentReceipt)
+        receipt = verifyIntent(input.intentReceipt, state);
+    let current;
+    try {
+        current = await classify(input.agentDir, state);
+    }
+    catch {
+        return repair(input.agentDir, state, ['MEMORY.md'], 'unsafe_or_unreadable_source');
+    }
+    if (current.unknown.length || current.classes.includes('X'))
+        return repair(input.agentDir, state, [...current.unknown, ...state.manifest.files.filter((_, index) => current.classes[index] === 'X').map(file => file.path)], 'unknown_change');
+    const allA = current.classes.every(value => value === 'A' || value === 'AB'), allB = current.classes.every(value => value === 'B' || value === 'AB');
+    if (allA && !cancelled && validTarget(current.files, state.manifest.recordMappings, manifestSourceHashes(state.manifest)))
+        return save(input.agentDir, { ...state, phase: 'committed', storageVersion: 2, ...(receipt ? { intentReceipt: receipt } : {}) });
+    if (allB && (!receipt || cancelled))
+        return save(input.agentDir, { ...state, phase: 'rolled_back', storageVersion: state.identity.sourceStorageVersion });
+    const staged = await copies(input.agentDir, state, 'after');
+    if (receipt && !cancelled && staged && validTarget(staged, state.manifest.recordMappings, manifestSourceHashes(state.manifest))) {
+        state = await save(input.agentDir, { ...state, phase: 'applying', intentReceipt: receipt });
+        await publish(input.agentDir, state, 'after', hooks);
+        const target = await classify(input.agentDir, state);
+        if (!target.unknown.length && target.classes.every(value => value === 'A' || value === 'AB') && validTarget(target.files, state.manifest.recordMappings, manifestSourceHashes(state.manifest)))
+            return save(input.agentDir, { ...state, phase: 'committed', storageVersion: 2 });
+    }
+    const backup = await copies(input.agentDir, state, 'before');
+    if (!backup || detectLocalMemoryStorageVersion(backup.get('MEMORY.md')?.toString('utf8') ?? '') !== state.identity.sourceStorageVersion)
+        return repair(input.agentDir, state, ['MEMORY.md'], 'backup_unverifiable');
+    await publish(input.agentDir, state, 'before', hooks);
+    const restored = await classify(input.agentDir, state);
+    if (restored.unknown.length || !restored.classes.every(value => value === 'B' || value === 'AB'))
+        return repair(input.agentDir, state, ['MEMORY.md'], 'rollback_validation_failed');
+    return save(input.agentDir, { ...state, phase: 'rolled_back', storageVersion: state.identity.sourceStorageVersion });
+}

package/dist/local-memory/migration-tool-entry.js

@@ -0,0 +1,21 @@
+import { runMemoryMigrationCommand, MigrationCommandSchema } from "./migration-cli.js";
+import { withMemoryAccess } from "./migration-access.js";
+async function main() {
+    const chunks = [];
+    let bytes = 0;
+    for await (const chunk of process.stdin) {
+        const part = Buffer.from(chunk);
+        bytes += part.length;
+        if (bytes > 8 * 1024 * 1024)
+            throw new Error("migration_input_limit");
+        chunks.push(part);
+    }
+    const input = MigrationCommandSchema.parse(JSON.parse(Buffer.concat(chunks).toString("utf8")));
+    const result = await withMemoryAccess(input.agentDir, () => runMemoryMigrationCommand(input), { maintenance: true });
+    process.stdout.write(JSON.stringify(result) + "\n");
+    process.exitCode = result.result === "success" || result.result === "missing" ? 0 : 1;
+}
+void main().catch(() => {
+    process.stdout.write(JSON.stringify({ result: "failed", issues: [{ path: "", reason: "migration_tool_failed" }] }) + "\n");
+    process.exitCode = 1;
+});

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

@@ -15,6 +15,7 @@ const SearchSchema = z.object({
     cursor: z.string().max(2048).optional(), limit: z.number().int().min(1).max(40).default(10),
 }).strict();
 const excerpt = (text, cap) => Array.from(text).slice(0, cap).join("");
+const pendingState = (reason) => reason === "legacy_requires_migration" ? "migration_deferred" : "capacity_deferred";
 export async function searchPendingMemoryPage(input) {
     const parsed = SearchSchema.safeParse(input);
     if (!parsed.success)
@@ -61,7 +62,8 @@ export async function searchPendingMemoryPage(input) {
         const match = source && isRecallablePending(source.candidate) && pendingRecallScore(source.candidate, args.query) > 0
             ? { pendingId: source.candidate.pendingId, sha256: source.sha256, title: source.candidate.candidate.title,
                 summary: excerpt(source.candidate.candidate.summary, 180), triggers: source.candidate.candidate.triggers.slice(0, 4),
-                operation: "create", state: "capacity_deferred" }
+                operation: "create", reason: source.candidate.reason,
+                state: pendingState(source.candidate.reason) }
             : null;
         const addition = match ?? warning;
         const size = addition ? Buffer.byteLength(JSON.stringify(addition), "utf8") + 2 : 0;
@@ -96,5 +98,6 @@ export async function readPendingMemoryBody(input) {
         throw new Error("memory_pending_not_recallable");
     const candidate = source.candidate.candidate;
     return { pendingId: source.candidate.pendingId, sha256: source.sha256, title: candidate.title,
-        operation: "create", state: "capacity_deferred", content: candidate.detailBody };
+        operation: "create", reason: source.candidate.reason,
+        state: pendingState(source.candidate.reason), content: candidate.detailBody };
 }

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

@@ -8,7 +8,7 @@ const ArchivedMemoryChangeSchema = LocalMemoryChangeSchema.extend({
 export const PendingIdSchema = z.string().max(200).regex(/^[A-Za-z0-9][A-Za-z0-9._-]*$/u);
 export const PendingMemorySchema = z.object({
     schemaVersion: z.literal(1), pendingId: PendingIdSchema,
-    createdAt: z.string().min(1).max(100), reason: z.literal("index_over_budget"),
+    createdAt: z.string().min(1).max(100), reason: z.enum(["index_over_budget", "legacy_requires_migration"]),
     source: z.object({ executionId: z.string().min(1).max(500), pruneTraceId: z.string().min(1).max(500).nullable() }).strict(),
     candidate: ArchivedMemoryChangeSchema,
 }).strict();

package/dist/local-memory/pending.js

@@ -1,5 +1,5 @@
 import { randomUUID } from "node:crypto";
-import { lstat, mkdir, realpath, rename, rm, writeFile } from "node:fs/promises";
+import { lstat, mkdir, realpath, rename, rm, readFile, writeFile } from "node:fs/promises";
 import { basename, dirname, join, relative, resolve, sep } from "node:path";
 import { isRecallablePending, parsePendingMemoryCandidate } from "./pending-schema.js";
 import { pendingFileNames, pendingReadDirectory, PENDING_FILE_BYTES, readPendingSource } from "./pending-source.js";
@@ -103,6 +103,17 @@ export async function persistPendingMemoryCandidate(input) {
     const directory = await pendingDirectory(input.agentDir);
     const target = join(directory, `${parsed.pendingId}.json`);
     await assertRegularFile(target);
+    try {
+        const existing = parsePendingMemoryCandidate(JSON.parse(await readFile(target, "utf8")));
+        const dedupKey = (value) => value.reason === "legacy_requires_migration"
+            ? JSON.stringify({ schemaVersion: value.schemaVersion, reason: value.reason, candidate: value.candidate })
+            : JSON.stringify({ ...value, createdAt: "" });
+        if (dedupKey(existing) === dedupKey(parsed))
+            return target;
+    }
+    catch {
+        // A malformed existing candidate is replaced by the validated input below.
+    }
     await atomicWrite(target, `${JSON.stringify(parsed, null, 2)}\n`);
     return target;
 }
@@ -164,7 +175,10 @@ function truncateCodePoints(value, maxCodePoints) {
     return Array.from(value).slice(0, Math.max(0, maxCodePoints)).join("");
 }
 export function renderPendingMemoryContext(candidates, maxCodePoints = 2_000) {
-    const recallable = candidates.filter(isRecallablePending);
+    // Migration-deferred candidates remain explicitly searchable, but must not
+    // be injected into the ordinary prompt before a reviewed migration promotes
+    // them to the active catalog.
+    const recallable = candidates.filter((candidate) => isRecallablePending(candidate) && candidate.reason === "index_over_budget");
     if (recallable.length === 0 || maxCodePoints <= 0)
         return "";
     const header = `\n\n## Archived memory candidates (daemon-managed)\n容量暂存的新增资料，仅为部分预览，不代表完整检索；可参考但不能覆盖现行规则，未包含内容请按需查询。\n`;