@orion-agents/orion-code 0.1.0 → 0.1.2

package/dist/services/storage-maintenance.js

@@ -4,11 +4,18 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.collectStorageReport = collectStorageReport;
+exports.collectStorageCleanupPlan = collectStorageCleanupPlan;
 exports.cleanupStorage = cleanupStorage;
+exports.collectProjectMetadataRepairPlan = collectProjectMetadataRepairPlan;
 exports.repairProjectMetadata = repairProjectMetadata;
+exports.serializeStorageMaintenancePlan = serializeStorageMaintenancePlan;
+exports.deserializeStorageMaintenancePlan = deserializeStorageMaintenancePlan;
+exports.consumeStorageMaintenancePlan = consumeStorageMaintenancePlan;
+exports.resetStorageMaintenancePlanRegistry = resetStorageMaintenancePlanRegistry;
 exports.formatStorageReport = formatStorageReport;
 exports.formatStorageCleanupResult = formatStorageCleanupResult;
 const better_sqlite3_1 = __importDefault(require("better-sqlite3"));
+const crypto_1 = require("crypto");
 const fs_1 = require("fs");
 const path_1 = require("path");
 const session_storage_1 = require("./session-storage");
@@ -16,6 +23,8 @@ const config_dir_1 = require("./config-dir");
 const format_1 = require("./format");
 const HASH_PROJECT_RE = /^[a-f0-9]{16}$/;
 const TEMP_PROJECT_RE = /^(private-tmp-|private-var-folders-.*orion-code-|tmp-orion-code-|test-project$)/;
+const STORAGE_PLAN_TOKEN_TTL_MS = 10 * 60 * 1000;
+const issuedStorageMaintenancePlans = new Map();
 function collectStorageReport() {
     const configHome = (0, config_dir_1.getConfigHome)();
     const projectsDir = (0, config_dir_1.getProjectsDir)();
@@ -24,10 +33,11 @@ function collectStorageReport() {
         .filter(project => !HASH_PROJECT_RE.test(project.projectKey) && !TEMP_PROJECT_RE.test(project.projectKey))
         .map(project => project.projectKey));
     const vectorProjects = inspectVectorProjects(configHome, validProjectKeys);
+    const metadataRepairPlan = collectProjectMetadataRepairPlan();
     const issues = [];
     const legacySessions = (0, path_1.join)(configHome, 'sessions');
     const legacyMemory = (0, path_1.join)(configHome, 'memory');
-    if ((0, fs_1.existsSync)(legacySessions)) {
+    if (safeIsDirectory(legacySessions)) {
         issues.push({
             kind: 'legacy-global-sessions',
             path: legacySessions,
@@ -36,7 +46,7 @@ function collectStorageReport() {
             canCleanup: true,
         });
     }
-    if ((0, fs_1.existsSync)(legacyMemory)) {
+    if (safeIsDirectory(legacyMemory)) {
         issues.push({
             kind: 'legacy-global-memory',
             path: legacyMemory,
@@ -79,26 +89,19 @@ function collectStorageReport() {
             });
             continue;
         }
-        if (!project.hasMetadata) {
-            issues.push({
-                kind: 'missing-project-metadata',
-                path: (0, config_dir_1.getProjectMetadataPath)(project.projectPath || project.path),
-                projectKey: project.projectKey,
-                summary: 'Project metadata file is missing',
-                bytes: project.bytes,
-                canCleanup: false,
-            });
-        }
-        else if (project.projectPath && (0, config_dir_1.getCanonicalProjectKey)(project.projectPath) !== project.projectKey) {
-            issues.push({
-                kind: 'invalid-project-metadata',
-                path: (0, config_dir_1.getProjectMetadataPath)(project.projectPath),
-                projectKey: project.projectKey,
-                summary: 'Project metadata does not match the canonical project key',
-                bytes: project.bytes,
-                canCleanup: false,
-            });
-        }
+    }
+    const projectsByKey = new Map(projects.map(project => [project.projectKey, project]));
+    for (const action of metadataRepairPlan.actions) {
+        issues.push({
+            kind: action.kind,
+            path: action.metadataPath,
+            projectKey: action.projectKey,
+            summary: action.kind === 'missing-project-metadata'
+                ? 'Project metadata file is missing'
+                : 'Project metadata is invalid',
+            bytes: projectsByKey.get(action.projectKey)?.bytes,
+            canCleanup: false,
+        });
     }
     for (const vectorProject of vectorProjects) {
         if (!vectorProject.orphan)
@@ -119,74 +122,187 @@ function collectStorageReport() {
         totalBytes: dirSize(configHome),
     };
 }
-function cleanupStorage(options = {}) {
+/** Collect an immutable, serializable cleanup plan without modifying storage. */
+function collectStorageCleanupPlan(options = {}) {
     const opts = {
-        dryRun: options.dryRun ?? false,
         includeLegacy: options.includeLegacy ?? true,
         includeTemp: options.includeTemp ?? true,
         includeEmpty: options.includeEmpty ?? true,
         includeVectorOrphans: options.includeVectorOrphans ?? true,
     };
     const report = collectStorageReport();
-    const deletedPaths = [];
-    const skippedPaths = [];
-    let vectorDeletedRows = 0;
+    const actions = [];
+    const skipped = [];
     for (const issue of report.issues) {
-        const shouldDeletePath = (opts.includeLegacy && (issue.kind === 'legacy-global-sessions' || issue.kind === 'legacy-global-memory' || issue.kind === 'legacy-hash-project')) ||
+        const shouldDeletePath = (opts.includeLegacy &&
+            (issue.kind === 'legacy-global-sessions' ||
+                issue.kind === 'legacy-global-memory' ||
+                issue.kind === 'legacy-hash-project')) ||
             (opts.includeTemp && issue.kind === 'temp-project') ||
             (opts.includeEmpty && issue.kind === 'empty-project');
-        if (shouldDeletePath && issue.path) {
-            if (!opts.dryRun) {
-                (0, fs_1.rmSync)(issue.path, { recursive: true, force: true });
-            }
-            deletedPaths.push(issue.path);
+        if (shouldDeletePath && issue.path && isPathCleanupKind(issue.kind)) {
+            const action = inspectCleanupPathAction(report, issue.kind, issue.path, issue.projectKey);
+            if (action)
+                actions.push(action);
+            else
+                skipped.push(issue.path);
             continue;
         }
         if (opts.includeVectorOrphans && issue.kind === 'vector-orphan-project' && issue.projectKey) {
-            const deleted = deleteVectorProjectRows(report.configHome, issue.projectKey, opts.dryRun);
-            vectorDeletedRows += deleted;
+            const action = inspectVectorCleanupAction(report, issue.projectKey);
+            if (action)
+                actions.push(action);
+            else
+                skipped.push(issue.projectKey);
             continue;
         }
-        if (issue.canCleanup) {
-            skippedPaths.push(issue.path || issue.projectKey || issue.kind);
-        }
+        if (issue.canCleanup)
+            skipped.push(issue.path || issue.projectKey || issue.kind);
     }
-    if (!opts.dryRun) {
-        repairProjectMetadata();
+    actions.sort((a, b) => cleanupActionKey(a).localeCompare(cleanupActionKey(b)));
+    return {
+        version: 1,
+        configHome: report.configHome,
+        projectsDir: report.projectsDir,
+        actions,
+        skipped,
+        issues: report.issues,
+    };
+}
+/** Apply only actions captured in a cleanup plan, after exact state revalidation. */
+function cleanupStorage(options = {}, plan = collectStorageCleanupPlan(options)) {
+    const dryRun = options.dryRun ?? false;
+    const deletedPaths = [];
+    const skippedPaths = [...plan.skipped];
+    const quarantinedPaths = [];
+    let vectorDeletedRows = 0;
+    if (!sameStorageRoots(plan.configHome, plan.projectsDir)) {
+        return {
+            dryRun,
+            deletedPaths,
+            skippedPaths: [...skippedPaths, ...plan.actions.map(cleanupActionKey)],
+            quarantinedPaths,
+            vectorDeletedRows,
+            issues: plan.issues,
+        };
+    }
+    for (const action of plan.actions) {
+        if (action.type === 'path') {
+            const current = inspectCleanupPathAction({
+                configHome: plan.configHome,
+                projectsDir: plan.projectsDir,
+            }, action.kind, action.path, action.projectKey);
+            if (!current || !sameCleanupPathAction(current, action)) {
+                skippedPaths.push(action.path);
+                continue;
+            }
+            if (dryRun) {
+                quarantinedPaths.push(action.path);
+                continue;
+            }
+            const quarantine = quarantinePlannedPath(action);
+            if (quarantine.status === 'restored' || quarantine.status === 'skipped') {
+                skippedPaths.push(action.path);
+            }
+            if (quarantine.quarantinePath)
+                quarantinedPaths.push(quarantine.quarantinePath);
+            continue;
+        }
+        const current = inspectVectorCleanupAction({ configHome: plan.configHome, projectsDir: plan.projectsDir }, action.projectKey);
+        if (!current || !sameVectorCleanupAction(current, action)) {
+            skippedPaths.push(action.projectKey);
+            continue;
+        }
+        if (dryRun) {
+            vectorDeletedRows += action.rowCount;
+            continue;
+        }
+        const deletedRows = deletePlannedVectorRows(plan.configHome, action);
+        if (deletedRows !== action.rowCount) {
+            skippedPaths.push(action.projectKey);
+            continue;
+        }
+        vectorDeletedRows += deletedRows;
     }
     return {
-        dryRun: opts.dryRun,
+        dryRun,
         deletedPaths,
         skippedPaths,
+        quarantinedPaths,
         vectorDeletedRows,
-        issues: report.issues,
+        issues: plan.issues,
     };
 }
-function repairProjectMetadata() {
+/** Collect a read-only, revalidatable plan for safe project metadata repairs. */
+function collectProjectMetadataRepairPlan() {
     const projectsDir = (0, config_dir_1.getProjectsDir)();
-    const repaired = [];
+    const actions = [];
     const skipped = [];
-    if (!(0, fs_1.existsSync)(projectsDir)) {
-        (0, fs_1.mkdirSync)(projectsDir, { recursive: true, mode: 0o700 });
-        return { repaired, skipped };
-    }
+    if (!safeIsDirectory(projectsDir))
+        return { version: 1, projectsDir, actions, skipped };
     for (const entry of (0, fs_1.readdirSync)(projectsDir)) {
         if (HASH_PROJECT_RE.test(entry) || TEMP_PROJECT_RE.test(entry)) {
             skipped.push(entry);
             continue;
         }
-        const projectDir = (0, path_1.join)(projectsDir, entry);
-        if (!safeIsDirectory(projectDir))
-            continue;
-        const projectPath = inferProjectPath(projectDir);
-        if (!projectPath) {
+        const observation = inspectProjectMetadataRepair(projectsDir, entry);
+        if (observation.action) {
+            actions.push(observation.action);
+        }
+        else if (observation.skipped) {
             skipped.push(entry);
-            continue;
         }
-        (0, config_dir_1.updateProjectMetadata)(projectPath);
-        repaired.push(entry);
     }
-    return { repaired, skipped };
+    actions.sort((a, b) => a.projectKey.localeCompare(b.projectKey));
+    return { version: 1, projectsDir, actions, skipped };
+}
+/** Apply only the targets in a repair plan, after revalidating every target. */
+function repairProjectMetadata(plan = collectProjectMetadataRepairPlan()) {
+    const projectsDir = (0, config_dir_1.getProjectsDir)();
+    const repaired = [];
+    const skipped = [...plan.skipped];
+    const blockedReason = 'Writable project metadata repair is disabled because Node.js cannot provide race-safe directory-relative writes on this platform.';
+    if (plan.version !== 1 || plan.projectsDir !== projectsDir) {
+        return {
+            repaired,
+            skipped: [...skipped, ...plan.actions.map(action => action.projectKey)],
+            writeDisabled: true,
+            blockedReason,
+        };
+    }
+    skipped.push(...plan.actions.map(action => action.projectKey));
+    return { repaired, skipped, writeDisabled: true, blockedReason };
+}
+/** Issue an opaque, process-local, expiring token for a previewed maintenance plan. */
+function serializeStorageMaintenancePlan(plan) {
+    if ((plan.kind === 'cleanup' && !isStorageCleanupPlan(plan.plan)) ||
+        (plan.kind === 'repair' && !isProjectMetadataRepairPlan(plan.plan))) {
+        throw new Error('Cannot issue an invalid storage maintenance plan');
+    }
+    pruneExpiredStorageMaintenancePlans();
+    let nonce;
+    do {
+        nonce = (0, crypto_1.randomBytes)(32).toString('base64url');
+    } while (issuedStorageMaintenancePlans.has(nonce));
+    issuedStorageMaintenancePlans.set(nonce, {
+        expiresAt: Date.now() + STORAGE_PLAN_TOKEN_TTL_MS,
+        plan: cloneStorageMaintenancePlan(plan),
+    });
+    return `v2.${nonce}`;
+}
+/** Peek at an active plan token without consuming it (used only for preview/dry-run). */
+function deserializeStorageMaintenancePlan(token) {
+    const issued = readIssuedStorageMaintenancePlan(token, false);
+    return issued ? cloneStorageMaintenancePlan(issued) : undefined;
+}
+/** Consume a plan token exactly once before a confirmed mutation attempt. */
+function consumeStorageMaintenancePlan(token) {
+    const issued = readIssuedStorageMaintenancePlan(token, true);
+    return issued ? cloneStorageMaintenancePlan(issued) : undefined;
+}
+/** Clear process-local plan capabilities, primarily for process-boundary tests. */
+function resetStorageMaintenancePlanRegistry() {
+    issuedStorageMaintenancePlans.clear();
 }
 function formatStorageReport(report) {
     const lines = [
@@ -223,7 +339,8 @@ function formatStorageCleanupResult(result) {
     const lines = [
         result.dryRun ? 'Orion Code Storage Cleanup (dry run)' : 'Orion Code Storage Cleanup',
         '─'.repeat(40),
-        `Paths       ${result.deletedPaths.length}`,
+        `Deleted     ${result.deletedPaths.length}`,
+        `Quarantined ${result.quarantinedPaths.length}`,
         `Vector rows ${result.vectorDeletedRows}`,
     ];
     for (const path of result.deletedPaths.slice(0, 20)) {
@@ -235,65 +352,512 @@ function formatStorageCleanupResult(result) {
     if (result.skippedPaths.length > 0) {
         lines.push(`Skipped    ${result.skippedPaths.length}`);
     }
+    if (result.quarantinedPaths.length > 0) {
+        for (const path of result.quarantinedPaths.slice(0, 20)) {
+            lines.push(`  ${result.dryRun ? 'would quarantine' : 'retained'} ${path}`);
+        }
+    }
     return lines.join('\n');
 }
 function listProjectSummaries(projectsDir) {
-    if (!(0, fs_1.existsSync)(projectsDir))
+    if (!safeIsDirectory(projectsDir))
         return [];
     const summaries = [];
     for (const projectKey of (0, fs_1.readdirSync)(projectsDir)) {
         const projectDir = (0, path_1.join)(projectsDir, projectKey);
         if (!safeIsDirectory(projectDir))
             continue;
-        const projectPath = inferProjectPath(projectDir);
-        const metadata = projectPath ? (0, config_dir_1.readProjectMetadata)(projectPath) : null;
+        const metadata = inspectProjectMetadata(projectDir, projectKey);
+        const repair = inspectProjectMetadataRepair(projectsDir, projectKey).action;
+        const projectPath = metadata.valid ? metadata.projectPath : repair?.projectPath;
         const sessionsDir = (0, path_1.join)(projectDir, 'sessions');
-        const sessions = (0, fs_1.existsSync)(sessionsDir)
-            ? (0, fs_1.readdirSync)(sessionsDir).filter(file => file.endsWith('.json') && !session_storage_1.SESSION_SIDECAR_SUFFIXES.some(s => file.endsWith(s))).length
+        const sessions = safeIsDirectory(sessionsDir)
+            ? (0, fs_1.readdirSync)(sessionsDir).filter(file => file.endsWith('.json') &&
+                !session_storage_1.SESSION_SIDECAR_SUFFIXES.some(s => file.endsWith(s)) &&
+                safeIsFile((0, path_1.join)(sessionsDir, file))).length
             : 0;
         summaries.push({
             projectKey,
             path: projectDir,
             bytes: dirSize(projectDir),
-            hasMetadata: !!metadata,
+            hasMetadata: metadata.valid,
             projectPath,
             sessions,
         });
     }
     return summaries.sort((a, b) => b.bytes - a.bytes || a.projectKey.localeCompare(b.projectKey));
 }
-function inferProjectPath(projectDir) {
+function inspectProjectMetadata(projectDir, expectedProjectKey) {
     const metadataPath = (0, path_1.join)(projectDir, 'project.json');
+    const inspected = readTextFileNoFollow(metadataPath);
+    if (inspected.status === 'missing') {
+        return { exists: false, valid: false, repairable: true, fingerprint: 'missing' };
+    }
+    if (inspected.status !== 'ok') {
+        return {
+            exists: true,
+            valid: false,
+            repairable: false,
+            fingerprint: inspected.fingerprint,
+        };
+    }
+    const fingerprint = fingerprintText(inspected.raw);
     try {
-        const parsed = JSON.parse((0, fs_1.readFileSync)(metadataPath, 'utf8'));
-        if (typeof parsed.projectPath === 'string' && parsed.projectPath) {
-            return parsed.projectPath;
-        }
+        const parsed = JSON.parse(inspected.raw);
+        const projectPath = normalizeProjectPath(parsed.projectPath);
+        const valid = parsed.schemaVersion === config_dir_1.PROJECT_METADATA_SCHEMA_VERSION &&
+            parsed.projectKey === expectedProjectKey &&
+            !!projectPath &&
+            (0, config_dir_1.getCanonicalProjectKey)(projectPath) === expectedProjectKey;
+        return { exists: true, valid, repairable: true, fingerprint, projectPath };
     }
     catch {
-        // Fall through to session metadata.
+        return { exists: true, valid: false, repairable: true, fingerprint };
     }
+}
+function inspectProjectSessions(projectDir) {
     const sessionsDir = (0, path_1.join)(projectDir, 'sessions');
-    if (!(0, fs_1.existsSync)(sessionsDir))
-        return undefined;
-    for (const file of (0, fs_1.readdirSync)(sessionsDir)) {
+    if (!pathExistsNoFollow(sessionsDir)) {
+        return { safe: true, fingerprint: fingerprintText('missing'), projectPaths: [] };
+    }
+    if (!safeIsDirectory(sessionsDir)) {
+        return { safe: false, fingerprint: fingerprintText('unsafe-directory'), projectPaths: [] };
+    }
+    const evidence = [];
+    const projectPaths = [];
+    let files;
+    try {
+        files = (0, fs_1.readdirSync)(sessionsDir).sort();
+    }
+    catch {
+        return { safe: false, fingerprint: fingerprintText('unreadable-directory'), projectPaths: [] };
+    }
+    for (const file of files) {
         if (!file.endsWith('.json') || session_storage_1.SESSION_SIDECAR_SUFFIXES.some(s => file.endsWith(s)))
             continue;
+        const inspected = readTextFileNoFollow((0, path_1.join)(sessionsDir, file));
+        if (inspected.status !== 'ok') {
+            return {
+                safe: false,
+                fingerprint: fingerprintText(`${file}:${inspected.fingerprint}`),
+                projectPaths: [],
+            };
+        }
+        evidence.push(`${file}:${fingerprintText(inspected.raw)}`);
         try {
-            const parsed = JSON.parse((0, fs_1.readFileSync)((0, path_1.join)(sessionsDir, file), 'utf8'));
-            if (typeof parsed.projectPath === 'string' && parsed.projectPath) {
-                return parsed.projectPath;
+            const parsed = JSON.parse(inspected.raw);
+            const projectPath = normalizeProjectPath(parsed.projectPath);
+            if (projectPath)
+                projectPaths.push(projectPath);
+        }
+        catch { }
+    }
+    return {
+        safe: true,
+        fingerprint: fingerprintText(evidence.join('\0')),
+        projectPaths,
+    };
+}
+function inspectProjectMetadataRepair(projectsDir, projectKey) {
+    if (HASH_PROJECT_RE.test(projectKey) || TEMP_PROJECT_RE.test(projectKey)) {
+        return { skipped: true };
+    }
+    const projectDir = (0, path_1.join)(projectsDir, projectKey);
+    if (!safeIsDirectory(projectDir))
+        return { skipped: true };
+    const metadata = inspectProjectMetadata(projectDir, projectKey);
+    if (metadata.valid)
+        return { skipped: false };
+    if (!metadata.repairable)
+        return { skipped: true };
+    const sessions = inspectProjectSessions(projectDir);
+    if (!sessions.safe)
+        return { skipped: true };
+    const inferredPaths = new Set(sessions.projectPaths);
+    if (metadata.projectPath)
+        inferredPaths.add(metadata.projectPath);
+    if (inferredPaths.size !== 1)
+        return { skipped: true };
+    const projectPath = [...inferredPaths][0];
+    if ((0, config_dir_1.getCanonicalProjectKey)(projectPath) !== projectKey)
+        return { skipped: true };
+    return {
+        skipped: false,
+        action: {
+            kind: metadata.exists ? 'invalid-project-metadata' : 'missing-project-metadata',
+            projectKey,
+            projectDir,
+            projectPath,
+            metadataPath: (0, path_1.join)(projectDir, 'project.json'),
+            stateFingerprint: fingerprintText(`${pathIdentityFingerprint(projectDir)}\0${metadata.fingerprint}\0${sessions.fingerprint}`),
+        },
+    };
+}
+function normalizeProjectPath(value) {
+    if (typeof value !== 'string' || !value.trim())
+        return undefined;
+    return (0, config_dir_1.resolveProjectStoragePath)(value);
+}
+function isPathCleanupKind(kind) {
+    return (kind === 'legacy-global-sessions' ||
+        kind === 'legacy-global-memory' ||
+        kind === 'legacy-hash-project' ||
+        kind === 'temp-project' ||
+        kind === 'empty-project');
+}
+function quarantinePlannedPath(action) {
+    const parent = (0, path_1.dirname)(action.path);
+    const quarantinePath = (0, path_1.join)(parent, `.${(0, path_1.basename)(action.path)}.orion-quarantine-${(0, crypto_1.randomBytes)(24).toString('hex')}`);
+    try {
+        if (pathExistsNoFollow(quarantinePath))
+            return { status: 'skipped' };
+        (0, fs_1.renameSync)(action.path, quarantinePath);
+    }
+    catch {
+        return { status: 'skipped' };
+    }
+    const quarantined = inspectPathTreeNoFollow(quarantinePath);
+    if (!quarantined || quarantined.fingerprint !== action.stateFingerprint) {
+        if (!pathExistsNoFollow(action.path)) {
+            try {
+                (0, fs_1.renameSync)(quarantinePath, action.path);
+                return { status: 'restored' };
             }
+            catch { }
         }
-        catch {
-            // Try the next session file.
+        return {
+            status: 'skipped',
+            quarantinePath: pathExistsNoFollow(quarantinePath) ? quarantinePath : undefined,
+        };
+    }
+    return { status: 'quarantined', quarantinePath };
+}
+function inspectCleanupPathAction(roots, kind, path, projectKey) {
+    if (!isExpectedCleanupPath(roots, kind, path, projectKey))
+        return undefined;
+    const state = inspectPathTreeNoFollow(path);
+    if (!state || state.type !== 'directory')
+        return undefined;
+    if (kind === 'empty-project' && state.bytes !== 0)
+        return undefined;
+    return { type: 'path', kind, path, projectKey, stateFingerprint: state.fingerprint };
+}
+function isExpectedCleanupPath(roots, kind, path, projectKey) {
+    if (kind === 'legacy-global-sessions')
+        return path === (0, path_1.join)(roots.configHome, 'sessions');
+    if (kind === 'legacy-global-memory')
+        return path === (0, path_1.join)(roots.configHome, 'memory');
+    if (!projectKey ||
+        !isSafeProjectKey(projectKey) ||
+        path !== (0, path_1.join)(roots.projectsDir, projectKey)) {
+        return false;
+    }
+    if (kind === 'legacy-hash-project')
+        return HASH_PROJECT_RE.test(projectKey);
+    if (kind === 'temp-project')
+        return TEMP_PROJECT_RE.test(projectKey);
+    return !HASH_PROJECT_RE.test(projectKey) && !TEMP_PROJECT_RE.test(projectKey);
+}
+function sameCleanupPathAction(current, planned) {
+    return (current.kind === planned.kind &&
+        current.path === planned.path &&
+        current.projectKey === planned.projectKey &&
+        current.stateFingerprint === planned.stateFingerprint);
+}
+function inspectVectorCleanupAction(roots, projectKey) {
+    if (!isSafeProjectKey(projectKey) || safeIsDirectory((0, path_1.join)(roots.projectsDir, projectKey))) {
+        return undefined;
+    }
+    const snapshot = readVectorProjectSnapshot(roots.configHome, projectKey);
+    if (!snapshot || snapshot.rows.length === 0)
+        return undefined;
+    return {
+        type: 'vector',
+        kind: 'vector-orphan-project',
+        projectKey,
+        rowCount: snapshot.rows.length,
+        databaseIdentity: snapshot.databaseIdentity,
+        rows: snapshot.rows,
+        stateFingerprint: fingerprintText(canonicalJson({ databaseIdentity: snapshot.databaseIdentity, rows: snapshot.rows })),
+    };
+}
+function sameVectorCleanupAction(current, planned) {
+    return (current.projectKey === planned.projectKey &&
+        current.databaseIdentity === planned.databaseIdentity &&
+        canonicalJson(current.rows) === canonicalJson(planned.rows) &&
+        current.stateFingerprint === planned.stateFingerprint &&
+        current.rowCount === planned.rowCount);
+}
+function cleanupActionKey(action) {
+    return action.type === 'path' ? action.path : `vector:${action.projectKey}`;
+}
+function sameStorageRoots(configHome, projectsDir) {
+    return configHome === (0, config_dir_1.getConfigHome)() && projectsDir === (0, config_dir_1.getProjectsDir)();
+}
+function isSafeProjectKey(projectKey) {
+    return (!!projectKey &&
+        projectKey !== '.' &&
+        projectKey !== '..' &&
+        !projectKey.includes('/') &&
+        !projectKey.includes('\\'));
+}
+function inspectPathTreeNoFollow(target) {
+    let before;
+    try {
+        before = (0, fs_1.lstatSync)(target);
+    }
+    catch {
+        return undefined;
+    }
+    if (before.isSymbolicLink())
+        return undefined;
+    if (before.isFile()) {
+        const inspected = readFileNoFollow(target);
+        if (inspected.status !== 'ok' || !inspected.raw)
+            return undefined;
+        return {
+            type: 'file',
+            bytes: inspected.raw.length,
+            fingerprint: fingerprintText(`file:${stableObjectIdentity(before)}:${inspected.fingerprint}`),
+        };
+    }
+    if (!before.isDirectory())
+        return undefined;
+    let entries;
+    try {
+        entries = (0, fs_1.readdirSync)(target).sort();
+    }
+    catch {
+        return undefined;
+    }
+    const children = [];
+    let bytes = 0;
+    for (const entry of entries) {
+        const state = inspectPathTreeNoFollow((0, path_1.join)(target, entry));
+        if (!state)
+            return undefined;
+        bytes += state.bytes;
+        children.push(`${entry}:${state.fingerprint}`);
+    }
+    let after;
+    try {
+        after = (0, fs_1.lstatSync)(target);
+    }
+    catch {
+        return undefined;
+    }
+    if (!after.isDirectory() || !sameStatIdentity(before, after))
+        return undefined;
+    return {
+        type: 'directory',
+        bytes,
+        fingerprint: fingerprintText(`directory:${stableObjectIdentity(after)}\0${children.join('\0')}`),
+    };
+}
+function readTextFileNoFollow(path) {
+    const inspected = readFileNoFollow(path);
+    if (inspected.status !== 'ok')
+        return inspected;
+    return {
+        status: 'ok',
+        fingerprint: inspected.fingerprint,
+        raw: inspected.raw.toString('utf8'),
+    };
+}
+function readFileNoFollow(path) {
+    let before;
+    try {
+        before = (0, fs_1.lstatSync)(path);
+    }
+    catch (error) {
+        const code = error.code;
+        return {
+            status: code === 'ENOENT' ? 'missing' : 'unreadable',
+            fingerprint: fingerprintText(code || 'lstat-error'),
+        };
+    }
+    if (before.isSymbolicLink() || !before.isFile()) {
+        return { status: 'unsafe', fingerprint: fingerprintText(`unsafe:${statIdentity(before)}`) };
+    }
+    let fd;
+    try {
+        fd = (0, fs_1.openSync)(path, fs_1.constants.O_RDONLY | fs_1.constants.O_NOFOLLOW);
+        const opened = (0, fs_1.fstatSync)(fd);
+        if (!opened.isFile() || !sameStatIdentity(before, opened)) {
+            return { status: 'unsafe', fingerprint: fingerprintText('identity-drift') };
         }
+        const raw = (0, fs_1.readFileSync)(fd);
+        const after = (0, fs_1.fstatSync)(fd);
+        if (!sameStatIdentity(opened, after)) {
+            return { status: 'unreadable', fingerprint: fingerprintText('read-drift') };
+        }
+        return { status: 'ok', fingerprint: fingerprintText(raw.toString('base64')), raw };
+    }
+    catch (error) {
+        const code = error.code || 'read-error';
+        return {
+            status: code === 'ELOOP' ? 'unsafe' : 'unreadable',
+            fingerprint: fingerprintText(`${code}:${statIdentity(before)}`),
+        };
+    }
+    finally {
+        if (fd !== undefined)
+            (0, fs_1.closeSync)(fd);
+    }
+}
+function statIdentity(stat) {
+    return [stat.dev, stat.ino, stat.mode, stat.size, stat.mtimeMs, stat.ctimeMs].join(':');
+}
+function stableObjectIdentity(stat) {
+    return [stat.dev, stat.ino, stat.mode].join(':');
+}
+function sameStatIdentity(a, b) {
+    return statIdentity(a) === statIdentity(b);
+}
+function pathIdentityFingerprint(path) {
+    try {
+        const stat = (0, fs_1.lstatSync)(path);
+        if (stat.isSymbolicLink())
+            return fingerprintText('unsafe-symlink');
+        return fingerprintText(stableObjectIdentity(stat));
+    }
+    catch (error) {
+        return fingerprintText(error.code || 'lstat-error');
+    }
+}
+function pathExistsNoFollow(path) {
+    try {
+        (0, fs_1.lstatSync)(path);
+        return true;
+    }
+    catch {
+        return false;
     }
-    return undefined;
+}
+function safeIsFile(path) {
+    try {
+        return (0, fs_1.lstatSync)(path).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function cloneStorageMaintenancePlan(plan) {
+    return JSON.parse(JSON.stringify(plan));
+}
+function readIssuedStorageMaintenancePlan(token, consume) {
+    pruneExpiredStorageMaintenancePlans();
+    const match = token.match(/^v2\.([A-Za-z0-9_-]{43})$/);
+    if (!match)
+        return undefined;
+    const issued = issuedStorageMaintenancePlans.get(match[1]);
+    if (!issued || issued.expiresAt <= Date.now()) {
+        if (issued)
+            issuedStorageMaintenancePlans.delete(match[1]);
+        return undefined;
+    }
+    if (consume)
+        issuedStorageMaintenancePlans.delete(match[1]);
+    return issued.plan;
+}
+function pruneExpiredStorageMaintenancePlans() {
+    const now = Date.now();
+    for (const [nonce, issued] of issuedStorageMaintenancePlans) {
+        if (issued.expiresAt <= now)
+            issuedStorageMaintenancePlans.delete(nonce);
+    }
+}
+function isSha256(value) {
+    return typeof value === 'string' && /^[a-f0-9]{64}$/.test(value);
+}
+function isStringArray(value) {
+    return Array.isArray(value) && value.every(item => typeof item === 'string');
+}
+function isStorageIssue(value) {
+    if (!isRecord(value) || !isStorageIssueKind(value.kind))
+        return false;
+    return (typeof value.summary === 'string' &&
+        typeof value.canCleanup === 'boolean' &&
+        (value.path === undefined || typeof value.path === 'string') &&
+        (value.projectKey === undefined || typeof value.projectKey === 'string') &&
+        (value.bytes === undefined || typeof value.bytes === 'number'));
+}
+function isStorageIssueKind(value) {
+    return (value === 'legacy-global-sessions' ||
+        value === 'legacy-global-memory' ||
+        value === 'legacy-hash-project' ||
+        value === 'temp-project' ||
+        value === 'empty-project' ||
+        value === 'missing-project-metadata' ||
+        value === 'invalid-project-metadata' ||
+        value === 'vector-orphan-project');
+}
+function isStorageCleanupAction(value) {
+    if (!isRecord(value) || !isSha256(value.stateFingerprint))
+        return false;
+    if (value.type === 'path') {
+        return (isPathCleanupKind(value.kind) &&
+            typeof value.path === 'string' &&
+            (value.projectKey === undefined || typeof value.projectKey === 'string'));
+    }
+    return (value.type === 'vector' &&
+        value.kind === 'vector-orphan-project' &&
+        typeof value.projectKey === 'string' &&
+        isSafeProjectKey(value.projectKey) &&
+        Number.isSafeInteger(value.rowCount) &&
+        value.rowCount > 0 &&
+        isSha256(value.databaseIdentity) &&
+        Array.isArray(value.rows) &&
+        value.rows.length === value.rowCount &&
+        value.rows.every(isStorageVectorRowSnapshot) &&
+        new Set(value.rows.map(row => row.id)).size === value.rows.length &&
+        fingerprintText(canonicalJson({ databaseIdentity: value.databaseIdentity, rows: value.rows })) === value.stateFingerprint);
+}
+function isStorageVectorRowSnapshot(value) {
+    return (isRecord(value) &&
+        typeof value.id === 'string' &&
+        typeof value.canonicalRow === 'string' &&
+        isSha256(value.rowFingerprint) &&
+        fingerprintText(value.canonicalRow) === value.rowFingerprint);
+}
+function isStorageCleanupPlan(value) {
+    return (isRecord(value) &&
+        value.version === 1 &&
+        typeof value.configHome === 'string' &&
+        typeof value.projectsDir === 'string' &&
+        Array.isArray(value.actions) &&
+        value.actions.every(isStorageCleanupAction) &&
+        isStringArray(value.skipped) &&
+        Array.isArray(value.issues) &&
+        value.issues.every(isStorageIssue));
+}
+function isProjectMetadataRepairAction(value) {
+    return (isRecord(value) &&
+        (value.kind === 'missing-project-metadata' || value.kind === 'invalid-project-metadata') &&
+        typeof value.projectKey === 'string' &&
+        isSafeProjectKey(value.projectKey) &&
+        typeof value.projectDir === 'string' &&
+        typeof value.projectPath === 'string' &&
+        typeof value.metadataPath === 'string' &&
+        isSha256(value.stateFingerprint));
+}
+function isProjectMetadataRepairPlan(value) {
+    return (isRecord(value) &&
+        value.version === 1 &&
+        typeof value.projectsDir === 'string' &&
+        Array.isArray(value.actions) &&
+        value.actions.every(isProjectMetadataRepairAction) &&
+        isStringArray(value.skipped));
+}
+function fingerprintText(value) {
+    return (0, crypto_1.createHash)('sha256').update(value).digest('hex');
 }
 function inspectVectorProjects(configHome, validProjectKeys) {
     const dbPath = (0, path_1.join)(configHome, 'vector.db');
-    if (!(0, fs_1.existsSync)(dbPath))
+    if (!safeIsFile(dbPath))
         return [];
     let db = null;
     try {
@@ -301,12 +865,14 @@ function inspectVectorProjects(configHome, validProjectKeys) {
         const hasMemories = db.prepare("SELECT name FROM sqlite_master WHERE name = 'memories'").get();
         if (!hasMemories)
             return [];
-        const rows = db.prepare(`
+        const rows = db
+            .prepare(`
       SELECT COALESCE(project, 'global') as project, COUNT(*) as rows
       FROM memories
       GROUP BY COALESCE(project, 'global')
       ORDER BY rows DESC, project ASC
-    `).all();
+    `)
+            .all();
         return rows.map(row => ({
             project: row.project,
             rows: row.rows,
@@ -320,39 +886,140 @@ function inspectVectorProjects(configHome, validProjectKeys) {
         db?.close();
     }
 }
-function deleteVectorProjectRows(configHome, project, dryRun) {
+function readVectorProjectSnapshot(configHome, project) {
     const dbPath = (0, path_1.join)(configHome, 'vector.db');
-    if (!(0, fs_1.existsSync)(dbPath))
-        return 0;
-    const db = new better_sqlite3_1.default(dbPath);
+    const databaseIdentity = databaseFileIdentity(dbPath);
+    if (!databaseIdentity)
+        return undefined;
+    let db;
     try {
+        db = new better_sqlite3_1.default(dbPath, { readonly: true });
+        db.defaultSafeIntegers(true);
         const hasMemories = db.prepare("SELECT name FROM sqlite_master WHERE name = 'memories'").get();
         if (!hasMemories)
-            return 0;
-        const ids = db.prepare('SELECT id FROM memories WHERE project = ?').all(project).map(row => row.id);
-        if (dryRun || ids.length === 0)
-            return ids.length;
-        const placeholders = ids.map(() => '?').join(', ');
-        if (db.prepare("SELECT name FROM sqlite_master WHERE name = 'vec_memories'").get() && db.prepare("SELECT name FROM sqlite_master WHERE name = 'memory_vectors'").get()) {
-            db.prepare(`DELETE FROM vec_memories WHERE rowid IN (SELECT vector_rowid FROM memory_vectors WHERE memory_id IN (${placeholders}))`).run(...ids);
-            db.prepare(`DELETE FROM memory_vectors WHERE memory_id IN (${placeholders})`).run(...ids);
-        }
-        db.prepare(`DELETE FROM memories WHERE id IN (${placeholders})`).run(...ids);
-        return ids.length;
+            return undefined;
+        const rows = readVectorRowsFromDatabase(db, project);
+        if (!rows || databaseFileIdentity(dbPath) !== databaseIdentity)
+            return undefined;
+        return { databaseIdentity, rows };
+    }
+    catch {
+        return undefined;
+    }
+    finally {
+        db?.close();
+    }
+}
+function deletePlannedVectorRows(configHome, action) {
+    const dbPath = (0, path_1.join)(configHome, 'vector.db');
+    if (databaseFileIdentity(dbPath) !== action.databaseIdentity)
+        return 0;
+    const db = new better_sqlite3_1.default(dbPath);
+    db.defaultSafeIntegers(true);
+    try {
+        const apply = db.transaction(() => {
+            const hasMemories = db
+                .prepare("SELECT name FROM sqlite_master WHERE name = 'memories'")
+                .get();
+            if (!hasMemories)
+                return 0;
+            if (databaseFileIdentity(dbPath) !== action.databaseIdentity)
+                return 0;
+            const currentRows = readVectorRowsFromDatabase(db, action.projectKey);
+            if (!currentRows)
+                return 0;
+            const currentStateFingerprint = fingerprintText(canonicalJson({ databaseIdentity: action.databaseIdentity, rows: currentRows }));
+            if (currentRows.length !== action.rowCount ||
+                canonicalJson(currentRows) !== canonicalJson(action.rows) ||
+                currentStateFingerprint !== action.stateFingerprint ||
+                databaseFileIdentity(dbPath) !== action.databaseIdentity) {
+                return 0;
+            }
+            const currentIds = action.rows.map(row => row.id);
+            const placeholders = currentIds.map(() => '?').join(', ');
+            if (db.prepare("SELECT name FROM sqlite_master WHERE name = 'vec_memories'").get() &&
+                db.prepare("SELECT name FROM sqlite_master WHERE name = 'memory_vectors'").get()) {
+                db.prepare(`DELETE FROM vec_memories WHERE rowid IN (SELECT vector_rowid FROM memory_vectors WHERE memory_id IN (${placeholders}))`).run(...currentIds);
+                db.prepare(`DELETE FROM memory_vectors WHERE memory_id IN (${placeholders})`).run(...currentIds);
+            }
+            db.prepare(`DELETE FROM memories WHERE id IN (${placeholders})`).run(...currentIds);
+            return currentIds.length;
+        });
+        return apply.immediate();
     }
     finally {
         db.close();
     }
 }
+function readVectorRowsFromDatabase(db, project) {
+    const rows = db
+        .prepare('SELECT * FROM memories WHERE project = ? ORDER BY id')
+        .all(project);
+    const snapshots = [];
+    for (const row of rows) {
+        if (typeof row.id !== 'string')
+            return undefined;
+        const canonicalRow = canonicalJson(row);
+        snapshots.push({
+            id: row.id,
+            canonicalRow,
+            rowFingerprint: fingerprintText(canonicalRow),
+        });
+    }
+    return snapshots;
+}
+function databaseFileIdentity(path) {
+    try {
+        const stat = (0, fs_1.lstatSync)(path);
+        if (!stat.isFile() || stat.isSymbolicLink())
+            return undefined;
+        return fingerprintText(stableObjectIdentity(stat));
+    }
+    catch {
+        return undefined;
+    }
+}
+function canonicalJson(value) {
+    return JSON.stringify(toCanonicalJsonValue(value));
+}
+function toCanonicalJsonValue(value) {
+    if (value === null || typeof value === 'string' || typeof value === 'boolean')
+        return value;
+    if (typeof value === 'number') {
+        if (Number.isFinite(value))
+            return Object.is(value, -0) ? 0 : value;
+        return { $number: String(value) };
+    }
+    if (typeof value === 'bigint')
+        return { $bigint: value.toString() };
+    if (Buffer.isBuffer(value))
+        return { $buffer: value.toString('base64') };
+    if (Array.isArray(value))
+        return value.map(toCanonicalJsonValue);
+    if (isRecord(value)) {
+        const result = {};
+        for (const key of Object.keys(value).sort()) {
+            result[key] = toCanonicalJsonValue(value[key]);
+        }
+        return result;
+    }
+    return { $unsupported: String(value) };
+}
 function dirSize(target) {
-    if (!(0, fs_1.existsSync)(target))
+    let stat;
+    try {
+        stat = (0, fs_1.lstatSync)(target);
+    }
+    catch {
+        return 0;
+    }
+    if (stat.isSymbolicLink())
+        return 0;
+    if (stat.isFile())
+        return stat.size;
+    if (!stat.isDirectory())
         return 0;
     try {
-        const stat = (0, fs_1.statSync)(target);
-        if (stat.isFile())
-            return stat.size;
-        if (!stat.isDirectory())
-            return 0;
         return (0, fs_1.readdirSync)(target).reduce((sum, entry) => sum + dirSize((0, path_1.join)(target, entry)), 0);
     }
     catch {
@@ -361,7 +1028,7 @@ function dirSize(target) {
 }
 function safeIsDirectory(target) {
     try {
-        return (0, fs_1.statSync)(target).isDirectory();
+        return (0, fs_1.lstatSync)(target).isDirectory();
     }
     catch {
         return false;