@nowcrew/daemon 0.6.90 → 0.6.91-beta.10

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-store.js

@@ -0,0 +1,424 @@
+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, MigrationIntentReceiptSchema, MigrationProcessStoppedReceiptSchema, MigrationStateSchema } from './migration-schema.js';
+import { detectLocalMemoryStorageVersion } from './storage-format.js';
+const opRoot = (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(([a], [b]) => a.localeCompare(b)).map(([key, value]) => [key, canonical(value)]));
+    return data;
+}
+const encode = (data) => Buffer.from(JSON.stringify(canonical(data)));
+const same = (a, b) => encode(a).equals(encode(b));
+const planDigest = (identity, sourceDigest, manifest) => digest(encode({ identity, sourceDigest, manifest }));
+function assertIdentity(state, identity) {
+    if (!same(state.identity, identity) || state.migrationId !== identity.migrationId
+        || state.planDigest !== planDigest(identity, state.sourceDigest, state.manifest))
+        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');
+    for (const file of state.manifest.files)
+        for (const image of [file.before, file.after]) {
+            if (image.exists && !image.ref.startsWith(`${opRoot(identity)}/`))
+                throw new MigrationError('migration_manifest_invalid');
+        }
+}
+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);
+    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 });
+}
+function verifyIntent(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;
+}
+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 pristineSeed = (history.isNewAgent === true && operations.length === 0 || 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) {
+    try {
+        validateMigrationTarget(files);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+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);
+        }
+        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))
+        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))
+        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))
+        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 = 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))
+            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/prompt.js

@@ -1,7 +1,7 @@
 import { dslog } from "../slog.js";
 import { renderPendingMemoryContext, searchPendingMemoryCandidates } from "./pending.js";
 import { renderLocalMemoryResultInstructions, renderLocalMemoryV2WriteGuard } from "./runtime.js";
-import { LOCAL_MEMORY_V2_DEFERRED_GUIDANCE } from "./rollout.js";
+import { LOCAL_MEMORY_V2_DEFERRED_GUIDANCE, LOCAL_MEMORY_LEGACY_GUIDANCE } from "./rollout.js";
 const PENDING_READ_GUIDANCE = "\n\nV2新增资料预览未命中不代表没有资料；先查有效索引，必要时用 crew-memory search-pending --query '关键词'，按 nextCursor 续查；用 read-pending --id ID 分页读正文。容量暂存资料不能覆盖现行规则，未应用修改不作为记忆。用 crew-memory --help 查看参数。\n";
 export async function prepareLocalMemoryPrompt(input) {
     let pending = "";
@@ -22,10 +22,11 @@ export async function prepareLocalMemoryPrompt(input) {
         }
     }
     const original = input.renderBase(0);
-    const guard = input.deferred ? LOCAL_MEMORY_V2_DEFERRED_GUIDANCE
+    const guard = input.legacyFallback ? LOCAL_MEMORY_LEGACY_GUIDANCE : input.deferred ? LOCAL_MEMORY_V2_DEFERRED_GUIDANCE
         : input.strictRollout && input.enabled && input.resultPath === null ? renderLocalMemoryV2WriteGuard() : "";
-    const structured = input.resultPath === null ? "" : renderLocalMemoryResultInstructions(input.resultPath);
+    const structured = input.resultPath === null ? "" : renderLocalMemoryResultInstructions(input.resultPath, input.storageVersion);
     const guidance = input.enabled ? PENDING_READ_GUIDANCE : "";
+    let requiredMemoryBudgetError;
     // 短命令指引放在当前轮，独立于可舍弃预览；收尾契约仍保持系统与当前轮两份。
     for (const choice of [
         { suffix: pending + guard + structured, wake: guard + structured + guidance },
@@ -33,11 +34,26 @@ export async function prepareLocalMemoryPrompt(input) {
         { suffix: guard + structured, wake: guard + structured },
     ]) {
         const reserved = Buffer.byteLength(choice.suffix + choice.wake, "utf8");
-        const systemPrompt = (reserved === 0 ? original : input.renderBase(reserved)) + choice.suffix;
+        let base;
+        try {
+            base = reserved === 0 ? original : input.renderBase(reserved);
+        }
+        catch (error) {
+            // 可选候选先让出预算；最后仍不能容纳身份/置顶时必须拒绝，不能省略必需记忆。
+            if (input.storageVersion === 2 && error instanceof Error
+                && ["local_memory_identity_budget_exceeded", "local_memory_pinned_budget_exceeded"].includes(error.message)) {
+                requiredMemoryBudgetError = error;
+                continue;
+            }
+            throw error;
+        }
+        const systemPrompt = base + choice.suffix;
         if (input.maxBytes === undefined || Buffer.byteLength(systemPrompt + choice.wake, "utf8") <= input.maxBytes) {
             return { systemPrompt, resultPath: input.resultPath, wakePromptSuffix: choice.wake };
         }
     }
+    if (requiredMemoryBudgetError)
+        throw requiredMemoryBudgetError;
     if (input.strictRollout)
         throw new Error("local_memory_v2_prompt_over_budget");
     // 强制基础指令与契约本身仍无法共存时，保留既有非结构化兼容回退，不裁基础指令。

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

@@ -6,6 +6,9 @@ import { pathToFileURL } from "node:url";
 import { parseArgs, TextDecoder } from "node:util";
 import { z } from "zod";
 import { readPendingMemoryBody, searchPendingMemoryPage } from "./pending-query.js";
+import { detectLocalMemoryStorageVersion } from "./storage-format.js";
+import { searchFullMemoryIndex } from "./full-index-search.js";
+import { withMemoryAccess } from "./migration-access.js";
 const OUTPUT_BYTES = 12 * 1024;
 const FILE_BYTES = 32 * 1024 * 1024;
 const READ_LIMIT_MAX = 4_000;
@@ -27,6 +30,12 @@ const Common = {
     ifHash: z.string().regex(/^[a-f0-9]{64}$/u).optional(),
 };
 const CommandSchema = z.discriminatedUnion("command", [
+    z.object({
+        command: z.literal("search-history"), ...Common,
+        query: z.string().trim().min(1).max(256),
+        limit: z.coerce.number().int().min(1).max(Number.MAX_SAFE_INTEGER).default(10),
+        afterLine: z.coerce.number().int().min(0).max(Number.MAX_SAFE_INTEGER).default(0),
+    }).strict(),
     z.object({
         command: z.literal("search"), ...Common,
         query: z.string().trim().min(1).max(256),
@@ -54,6 +63,7 @@ const CommandSchema = z.discriminatedUnion("command", [
 ]);
 const USAGE = `只读记忆工具，默认输出 JSON，不修改任何记忆文件。
 crew-memory search --query <关键词> [--file MEMORY.md|notes/文件.md] [--limit 10] [--after-line 0]
+crew-memory search-history --query <关键词> [--limit 10] [--after-line 0] [--if-hash <sha256>]
 crew-memory read [--file MEMORY.md|notes/文件.md] [--offset 0] [--limit 2000]
 crew-memory search-pending --query <关键词> [--cursor <游标>] [--limit 10]
 crew-memory read-pending --id <候选ID> [--offset 0] [--limit 2000] [--if-hash <sha256>]
@@ -62,7 +72,8 @@ search 关键词按空白分隔，同一行须全部命中；返回完整文件
 读取的 offset/limit 按 Unicode 字符计数；用 nextOffset 继续，eof=true 表示结束。
 读取的 --limit 超出范围时，工具会自动降到 2000 并在结果中标记 warning；保留原文件或候选 ID 及 offset，按 nextOffset 分页，不要一次读完整文件。
 后续页可传 --if-hash <前一页的 sha256>，文件变化时停止，避免混读不同版本。
-search/read 读取 MEMORY.md 和 notes 原文，不过滤失效段落，也不扫描 pending。
+schema=2 的 search 查询完整有效目录（active/pinned），按标题、摘要、触发词联合匹配并返回 ID、revision 和正文引用；search-history 显式查询历史/失效记录。预览未展示不代表记录不存在。
+旧格式 search 及 read 读取原文；read 按指定文件和哈希分页，不扫描 pending。
 search-pending 只查因容量延期的 create 候选；有 nextCursor 就继续，即使本页 matches 为空。
 complete=true 才表示全部候选已检索完成且无遗漏；warnings 或非零退出码表示读取未完成，不能当作零命中。
 read-pending 只返回候选正文；offset 非零时必须传 --if-hash，update/supersede 候选不可读取。
@@ -232,6 +243,18 @@ function writeResult(result, io) {
     io.out(output);
 }
 export async function runMemoryReadCommand(argv, io) {
+    if (!io.env.CREW_HOME || argv.includes("--help") || argv.includes("-h"))
+        return runMemoryReadUnlocked(argv, io);
+    try {
+        return await withMemoryAccess(io.env.CREW_HOME, () => runMemoryReadUnlocked(argv, io));
+    }
+    catch (error) {
+        const reason = error instanceof Error && /^(?:local_)?memory_[a-z_]+$/u.test(error.message) ? error.message : "memory_migration_access_failed";
+        io.err(JSON.stringify({ error: reason, message: "记忆读取受到迁移或状态保护，不能当作没有记忆。" }));
+        return 1;
+    }
+}
+async function runMemoryReadUnlocked(argv, io) {
     let command;
     try {
         const { values, positionals } = parseArgs({
@@ -289,6 +312,18 @@ export async function runMemoryReadCommand(argv, io) {
         const source = await readSource(io.env.CREW_HOME, command.file);
         if (command.ifHash !== undefined && command.ifHash !== source.sha256)
             throw new Error("memory_file_changed");
+        const fullIndex = command.file === "MEMORY.md" && detectLocalMemoryStorageVersion(source.text) === 2;
+        if ((command.command === "search" || command.command === "search-history") && fullIndex) {
+            const normalized = normalizeLimit(command.limit, SEARCH_LIMIT_MAX, SEARCH_LIMIT_SAFE);
+            const result = searchFullMemoryIndex(source.text, source.sha256, {
+                ...command, limit: normalized.limit, history: command.command === "search-history",
+            }, OUTPUT_BYTES - 256);
+            writeResult({ ...result, ...(normalized.warning ? { warning: normalized.warning,
+                    requestedLimit: normalized.warning.requestedLimit, limit: normalized.warning.appliedLimit } : {}) }, io);
+            return 0;
+        }
+        if (command.command === "search-history")
+            throw new Error("memory_history_requires_full_index");
         const result = command.command === "search"
             ? (() => {
                 const normalized = normalizeLimit(command.limit, SEARCH_LIMIT_MAX, SEARCH_LIMIT_SAFE);