shieldcortex 4.12.14 → 4.13.0

package/dist/api/routes/digest.js

@@ -0,0 +1,305 @@
+import { getDatabase, isDatabaseInitialized } from '../../database/init.js';
+const WINDOW_HOURS = {
+    '24h': 24,
+    '7d': 168,
+    '30d': 720,
+};
+const HIGH_SALIENCE_THRESHOLD = 0.6;
+function isoSinceHoursAgo(hours) {
+    return new Date(Date.now() - hours * 3600_000).toISOString();
+}
+function safeCount(rows, key) {
+    if (!rows.length)
+        return 0;
+    const v = rows[0][key];
+    return typeof v === 'number' ? v : Number(v ?? 0);
+}
+function getCountsBetween(sinceIso, untilIso, project) {
+    const db = getDatabase();
+    const projectAudit = project ? 'AND da.project = @project' : '';
+    const projectMem = project ? 'AND m.project = @project' : '';
+    const upperBound = untilIso ? 'AND da.timestamp < @until' : '';
+    const upperBoundMem = untilIso ? 'AND m.created_at < @until' : '';
+    const upperBoundRecall = untilIso ? 'AND m.last_accessed < @until' : '';
+    const params = { since: sinceIso };
+    if (project)
+        params.project = project;
+    if (untilIso)
+        params.until = untilIso;
+    // Defence audit counts (single grouped query)
+    const auditRows = db.prepare(`
+    SELECT da.firewall_result AS result, COUNT(*) AS cnt
+    FROM defence_audit da
+    WHERE da.timestamp >= @since ${upperBound} ${projectAudit}
+    GROUP BY da.firewall_result
+  `).all(params);
+    let allowed = 0, blocked = 0, quarantined = 0;
+    for (const row of auditRows) {
+        if (row.result === 'ALLOW')
+            allowed = row.cnt;
+        else if (row.result === 'BLOCK')
+            blocked = row.cnt;
+        else if (row.result === 'QUARANTINE')
+            quarantined = row.cnt;
+    }
+    const scanned = allowed + blocked + quarantined;
+    // Memories captured in window
+    const memCapturedRows = db.prepare(`
+    SELECT COUNT(*) AS cnt FROM memories m
+    WHERE m.created_at >= @since ${upperBoundMem} ${projectMem}
+  `).all(params);
+    const memoriesCaptured = safeCount(memCapturedRows, 'cnt');
+    // High-salience captures (salience >= threshold)
+    const highSalRows = db.prepare(`
+    SELECT COUNT(*) AS cnt FROM memories m
+    WHERE m.created_at >= @since ${upperBoundMem} AND m.salience >= ${HIGH_SALIENCE_THRESHOLD} ${projectMem}
+  `).all(params);
+    const highSalienceCaptures = safeCount(highSalRows, 'cnt');
+    // Memories recalled (last_accessed advanced past created_at within window)
+    const recalledRows = db.prepare(`
+    SELECT COUNT(*) AS cnt FROM memories m
+    WHERE m.last_accessed >= @since ${upperBoundRecall}
+      AND m.last_accessed > m.created_at
+      ${projectMem}
+  `).all(params);
+    const memoriesRecalled = safeCount(recalledRows, 'cnt');
+    return {
+        scanned,
+        allowed,
+        blocked,
+        quarantined,
+        memoriesCaptured,
+        memoriesRecalled,
+        highSalienceCaptures,
+    };
+}
+function getTopMoments(sinceIso, project, limit = 5) {
+    const db = getDatabase();
+    const projectAudit = project ? 'AND da.project = ?' : '';
+    const projectMem = project ? 'AND m.project = ?' : '';
+    const moments = [];
+    // Top blocks/quarantines (most severe firewall actions)
+    const auditParams = project ? [sinceIso, project] : [sinceIso];
+    const blocks = db.prepare(`
+    SELECT da.id, da.timestamp, da.firewall_result, da.reason, da.source_type, da.source_identifier,
+           da.threat_indicators, da.anomaly_score
+    FROM defence_audit da
+    WHERE da.timestamp >= ? ${projectAudit}
+      AND da.firewall_result IN ('BLOCK', 'QUARANTINE')
+    ORDER BY da.anomaly_score DESC, da.timestamp DESC
+    LIMIT 3
+  `).all(...auditParams);
+    for (const b of blocks) {
+        let indicators = [];
+        try {
+            indicators = b.threat_indicators ? JSON.parse(b.threat_indicators) : [];
+        }
+        catch { /* ignore */ }
+        const top = indicators.slice(0, 2).join(', ');
+        moments.push({
+            kind: b.firewall_result === 'BLOCK' ? 'block' : 'quarantine',
+            title: b.firewall_result === 'BLOCK'
+                ? `Blocked ${top || b.reason || 'a suspicious payload'}`
+                : `Quarantined ${top || b.reason || 'a suspicious memory'}`,
+            detail: `${b.source_type}: ${b.source_identifier}`,
+            timestamp: b.timestamp,
+            auditId: b.id,
+        });
+    }
+    // Top high-salience captures
+    const memParams = project ? [sinceIso, project] : [sinceIso];
+    const captures = db.prepare(`
+    SELECT m.id, m.title, m.salience, m.category, m.created_at, m.project
+    FROM memories m
+    WHERE m.created_at >= ? ${projectMem}
+      AND m.salience >= ${HIGH_SALIENCE_THRESHOLD}
+    ORDER BY m.salience DESC, m.created_at DESC
+    LIMIT 3
+  `).all(...memParams);
+    for (const m of captures) {
+        moments.push({
+            kind: 'capture',
+            title: `Captured: ${m.title}`,
+            detail: `${m.category} · salience ${m.salience.toFixed(2)}${m.project ? ` · ${m.project}` : ''}`,
+            timestamp: m.created_at,
+            memoryId: m.id,
+        });
+    }
+    // Top recalls in window (high access count + recently accessed)
+    const recalls = db.prepare(`
+    SELECT m.id, m.title, m.access_count, m.last_accessed, m.salience
+    FROM memories m
+    WHERE m.last_accessed >= ? ${projectMem}
+      AND m.last_accessed > m.created_at
+    ORDER BY m.access_count DESC, m.last_accessed DESC
+    LIMIT 2
+  `).all(...memParams);
+    for (const r of recalls) {
+        moments.push({
+            kind: 'recall',
+            title: `Recalled: ${r.title}`,
+            detail: `accessed ${r.access_count}× · salience ${r.salience.toFixed(2)}`,
+            timestamp: r.last_accessed,
+            memoryId: r.id,
+        });
+    }
+    return moments
+        .sort((a, b) => b.timestamp.localeCompare(a.timestamp))
+        .slice(0, limit);
+}
+function getTopThreatPatterns(sinceIso, project) {
+    const db = getDatabase();
+    const projectCond = project ? 'AND da.project = ?' : '';
+    const params = project ? [sinceIso, project] : [sinceIso];
+    const rows = db.prepare(`
+    SELECT da.threat_indicators
+    FROM defence_audit da
+    WHERE da.timestamp >= ? ${projectCond}
+      AND da.threat_indicators IS NOT NULL
+      AND da.threat_indicators != '[]'
+    LIMIT 500
+  `).all(...params);
+    const counts = {};
+    for (const r of rows) {
+        try {
+            const list = JSON.parse(r.threat_indicators);
+            for (const p of list)
+                counts[p] = (counts[p] ?? 0) + 1;
+        }
+        catch { /* ignore */ }
+    }
+    return Object.entries(counts)
+        .map(([pattern, count]) => ({ pattern, count }))
+        .sort((a, b) => b.count - a.count)
+        .slice(0, 5);
+}
+function buildDeltas(current, previous) {
+    const delta = {};
+    for (const key of Object.keys(current)) {
+        delta[key] = current[key] - previous[key];
+    }
+    return delta;
+}
+function windowLabelFor(window) {
+    switch (window) {
+        case '24h': return 'Last 24 hours';
+        case '7d': return 'Last 7 days';
+        case '30d': return 'Last 30 days';
+    }
+}
+export function buildDigest(window, project) {
+    const hours = WINDOW_HOURS[window];
+    const since = isoSinceHoursAgo(hours);
+    const previousSince = isoSinceHoursAgo(hours * 2);
+    const current = getCountsBetween(since, null, project);
+    const previous = getCountsBetween(previousSince, since, project);
+    return {
+        window,
+        windowLabel: windowLabelFor(window),
+        since,
+        current,
+        previous,
+        delta: buildDeltas(current, previous),
+        topMoments: getTopMoments(since, project, 5),
+        topThreatPatterns: getTopThreatPatterns(since, project),
+        generatedAt: new Date().toISOString(),
+    };
+}
+/**
+ * Returns one row per day for the last `days` days, oldest first.
+ * Days with zero activity are still included (gives a clean sparkline shape).
+ */
+export function buildTimeline(days, project) {
+    const db = getDatabase();
+    const projectAudit = project ? 'AND da.project = @project' : '';
+    const projectMem = project ? 'AND m.project = @project' : '';
+    const since = isoSinceHoursAgo(days * 24);
+    const params = { since };
+    if (project)
+        params.project = project;
+    // Audit counts grouped by day (UTC)
+    const auditRows = db.prepare(`
+    SELECT substr(da.timestamp, 1, 10) AS day, da.firewall_result AS result, COUNT(*) AS cnt
+    FROM defence_audit da
+    WHERE da.timestamp >= @since ${projectAudit}
+    GROUP BY day, da.firewall_result
+  `).all(params);
+    const captureRows = db.prepare(`
+    SELECT substr(m.created_at, 1, 10) AS day, COUNT(*) AS cnt
+    FROM memories m
+    WHERE m.created_at >= @since ${projectMem}
+    GROUP BY day
+  `).all(params);
+    const recallRows = db.prepare(`
+    SELECT substr(m.last_accessed, 1, 10) AS day, COUNT(*) AS cnt
+    FROM memories m
+    WHERE m.last_accessed >= @since
+      AND m.last_accessed > m.created_at
+      ${projectMem}
+    GROUP BY day
+  `).all(params);
+    // Build a complete day map with zero defaults
+    const byDay = {};
+    const today = new Date();
+    for (let i = days - 1; i >= 0; i--) {
+        const d = new Date(today);
+        d.setUTCDate(d.getUTCDate() - i);
+        const key = d.toISOString().slice(0, 10);
+        byDay[key] = { date: key, scanned: 0, blocked: 0, quarantined: 0, captured: 0, recalled: 0 };
+    }
+    for (const row of auditRows) {
+        const day = byDay[row.day];
+        if (!day)
+            continue;
+        if (row.result === 'BLOCK')
+            day.blocked = row.cnt;
+        else if (row.result === 'QUARANTINE')
+            day.quarantined = row.cnt;
+        day.scanned += row.cnt;
+    }
+    for (const row of captureRows) {
+        if (byDay[row.day])
+            byDay[row.day].captured = row.cnt;
+    }
+    for (const row of recallRows) {
+        if (byDay[row.day])
+            byDay[row.day].recalled = row.cnt;
+    }
+    return Object.values(byDay).sort((a, b) => a.date.localeCompare(b.date));
+}
+export function registerDigestRoutes(app) {
+    app.get('/api/digest', (req, res) => {
+        try {
+            if (!isDatabaseInitialized()) {
+                return res.status(503).json({ error: 'Database not initialised' });
+            }
+            const rawWindow = String(req.query.window ?? '24h');
+            const window = (rawWindow === '7d' || rawWindow === '30d') ? rawWindow : '24h';
+            const project = typeof req.query.project === 'string' && req.query.project.trim()
+                ? req.query.project.trim()
+                : undefined;
+            const digest = buildDigest(window, project);
+            res.json(digest);
+        }
+        catch (err) {
+            res.status(500).json({ error: err.message });
+        }
+    });
+    app.get('/api/digest/timeline', (req, res) => {
+        try {
+            if (!isDatabaseInitialized()) {
+                return res.status(503).json({ error: 'Database not initialised' });
+            }
+            const daysRaw = parseInt(String(req.query.days ?? '7'), 10);
+            const days = Number.isFinite(daysRaw) ? Math.max(1, Math.min(90, daysRaw)) : 7;
+            const project = typeof req.query.project === 'string' && req.query.project.trim()
+                ? req.query.project.trim()
+                : undefined;
+            const timeline = buildTimeline(days, project);
+            res.json({ days, project: project ?? null, timeline });
+        }
+        catch (err) {
+            res.status(500).json({ error: err.message });
+        }
+    });
+}

package/dist/api/routes/memories.js

@@ -4,7 +4,7 @@ import { existsSync, readdirSync, readFileSync } from 'fs';
 import { getDatabase } from '../../database/init.js';
 import { searchMemories, getRecentMemories, getHighPriorityMemories, getMemoryStats, getMemoryById, addMemory, deleteMemory, accessMemory, updateMemory, mergeMemories, promoteMemory, createMemoryLink, rowToMemory, enrichMemory, } from '../../memory/store.js';
 import { calculateDecayedScore } from '../../memory/decay.js';
-import { consolidate, findDuplicateMemoryPairs, formatContextSummary, generateContextSummary, consolidateMemories, } from '../../memory/consolidate.js';
+import { consolidate, findDuplicateMemoryPairs, formatContextSummary, generateContextSummary, } from '../../memory/consolidate.js';
 import { getActivationStats, getActiveMemories } from '../../memory/activation.js';
 import { detectContradictions, getContradictionsFor } from '../../memory/contradiction.js';
 import { emitConsolidation } from '../events.js';
@@ -831,10 +831,15 @@ export function registerMemoryRoutes(app, deps) {
             res.status(500).json({ error: error.message });
         }
     });
+    // Consolidation is a maintenance operation (STM→LTM promotion + low-salience
+    // dedupe), not arbitrary delete. Use 'modify_records' (AMBER) so the
+    // dashboard can trigger it without the RED 'delete' gate that always blocks.
+    // Mirrors the action used by /api/worker/trigger-{light,medium}.
     app.post('/api/consolidate', requireNotLocked, requireIronDomeAction({
-        action: 'delete',
+        action: 'modify_records',
         channel: 'dashboard',
         sourceIdentifier: 'dashboard:consolidate',
+        enforceAmber: true,
     }), (_req, res) => {
         try {
             const result = consolidate();
@@ -845,6 +850,78 @@ export function registerMemoryRoutes(app, deps) {
             res.status(500).json({ error: error.message });
         }
     });
+    // Threshold-based prune: delete memories below salience X older than Y days.
+    // dryRun:true (default) returns counts + sample without touching the DB.
+    // Auto-backs-up the DB before any destructive write — backupPath returned.
+    app.post('/api/memories/prune', requireNotLocked, requireIronDomeAction({
+        action: 'modify_records',
+        channel: 'dashboard',
+        sourceIdentifier: 'dashboard:memories-prune',
+        enforceAmber: true,
+    }), async (req, res) => {
+        try {
+            const { salienceLte, ageDaysGte, project, excludePinned, dryRun } = req.body ?? {};
+            if (salienceLte !== undefined && (typeof salienceLte !== 'number' || salienceLte < 0 || salienceLte > 1)) {
+                return res.status(400).json({ error: 'salienceLte must be a number 0..1' });
+            }
+            if (ageDaysGte !== undefined && (typeof ageDaysGte !== 'number' || ageDaysGte < 0)) {
+                return res.status(400).json({ error: 'ageDaysGte must be a number >= 0' });
+            }
+            if (project !== undefined && project !== null && typeof project !== 'string') {
+                return res.status(400).json({ error: 'project must be a string when provided' });
+            }
+            if (excludePinned !== undefined && typeof excludePinned !== 'boolean') {
+                return res.status(400).json({ error: 'excludePinned must be a boolean' });
+            }
+            if (dryRun !== undefined && typeof dryRun !== 'boolean') {
+                return res.status(400).json({ error: 'dryRun must be a boolean' });
+            }
+            const { pruneMemories } = await import('../../memory/prune.js');
+            const result = await pruneMemories({
+                salienceLte,
+                ageDaysGte,
+                project: project ?? undefined,
+                excludePinned,
+                dryRun,
+            });
+            res.json({ success: true, ...result });
+        }
+        catch (error) {
+            res.status(500).json({ error: error.message });
+        }
+    });
+    // Project-scoped dedupe: cluster near-duplicate long-term memories and keep
+    // the highest-salience representative. dryRun:true (default) returns the
+    // groups without merging. Auto-backs-up the DB before any merge.
+    app.post('/api/memories/dedupe', requireNotLocked, requireIronDomeAction({
+        action: 'modify_records',
+        channel: 'dashboard',
+        sourceIdentifier: 'dashboard:memories-dedupe',
+        enforceAmber: true,
+    }), async (req, res) => {
+        try {
+            const { project, dryRun, limit } = req.body ?? {};
+            if (project !== undefined && project !== null && typeof project !== 'string') {
+                return res.status(400).json({ error: 'project must be a string when provided' });
+            }
+            if (dryRun !== undefined && typeof dryRun !== 'boolean') {
+                return res.status(400).json({ error: 'dryRun must be a boolean' });
+            }
+            if (limit !== undefined && (typeof limit !== 'number' || limit < 1 || limit > 1000)) {
+                return res.status(400).json({ error: 'limit must be a number 1..1000' });
+            }
+            const { dedupeMemories } = await import('../../memory/dedupe-runner.js');
+            const result = await dedupeMemories({
+                project: project ?? undefined,
+                dryRun,
+                limit,
+            });
+            res.json({ success: true, ...result });
+        }
+        catch (error) {
+            res.status(500).json({ error: error.message });
+        }
+    });
     app.get('/api/context', requireNotLocked, async (req, res) => {
         try {
             const project = typeof req.query.project === 'string' ? req.query.project : undefined;
@@ -1151,17 +1228,9 @@ export function registerMemoryRoutes(app, deps) {
             res.status(500).json({ error: error.message });
         }
     });
-    // v4.0.0: Dream Mode — comprehensive memory consolidation
-    app.post('/api/consolidate', requireNotLocked, (_req, res) => {
-        try {
-            const result = consolidateMemories();
-            res.json({
-                success: true,
-                ...result,
-            });
-        }
-        catch (error) {
-            res.status(500).json({ error: error.message });
-        }
-    });
+    // (Note: there used to be a second, ungated `app.post('/api/consolidate', ...)`
+    // here calling `consolidateMemories()`. It was dead code — Express dispatches
+    // to the first matching route and the gated one above won. Removed in
+    // favour of the gated route to avoid future contributors thinking either
+    // would actually run.)
 }

package/dist/api/routes/system.js

@@ -2,7 +2,7 @@ import { WebSocket } from 'ws';
 import { getLifetimeStats } from '../../defence/audit/queries.js';
 import { getAuditStats } from '../../defence/audit/queries.js';
 import { isDatabaseInitialized } from '../../database/init.js';
-import { getCloudConfig, getCloudSyncControls, getDeviceId, getDeviceName, getDefenceMode, getOpenClawMemoryConfig, isConfigTampered, readRawConfig, setCloudConfig, setCloudSyncControls, setDefenceMode, setOpenClawMemoryConfig, } from '../../cloud/config.js';
+import { getCloudConfig, getCloudSyncControls, getDeviceId, getDeviceName, getDefenceMode, getOpenClawMemoryConfig, isConfigTampered, isProactiveRecallEnabled, readRawConfig, setCloudConfig, setCloudSyncControls, setDefenceMode, setOpenClawMemoryConfig, setProactiveRecall, } from '../../cloud/config.js';
 import { getQueueStats, reconcileSyncQueue } from '../../cloud/sync-queue.js';
 import { getDatabase } from '../../database/init.js';
 import { getRequiredTier, isFeatureEnabled } from '../../license/gate.js';
@@ -111,6 +111,7 @@ export function registerSystemRoutes(app, deps) {
                 baseUrl: config.cloudBaseUrl,
                 syncControls: getCloudSyncControls(),
                 openclawMemory: getOpenClawMemoryConfig(),
+                proactiveRecall: isProactiveRecallEnabled(),
             });
         }
         catch (error) {
@@ -125,7 +126,7 @@ export function registerSystemRoutes(app, deps) {
     }), (req, res) => {
         try {
             const existingConfig = getCloudConfig();
-            const { cloudApiKey, cloudEnabled, cloudBaseUrl, cloudSyncProjectMode, cloudSyncProjects, cloudSyncContentMode, cloudSyncExcludeSensitive, openclawAutoMemory, openclawAutoMemoryDedupe, openclawAutoMemoryNoveltyThreshold, openclawAutoMemoryMaxRecent, } = req.body;
+            const { cloudApiKey, cloudEnabled, cloudBaseUrl, cloudSyncProjectMode, cloudSyncProjects, cloudSyncContentMode, cloudSyncExcludeSensitive, openclawAutoMemory, openclawAutoMemoryDedupe, openclawAutoMemoryNoveltyThreshold, openclawAutoMemoryMaxRecent, proactiveRecall, } = req.body;
             if (cloudApiKey !== undefined && typeof cloudApiKey !== 'string') {
                 return res.status(400).json({ error: 'cloudApiKey must be a string' });
             }
@@ -168,6 +169,9 @@ export function registerSystemRoutes(app, deps) {
                 (!Array.isArray(cloudSyncProjects) || cloudSyncProjects.some((value) => typeof value !== 'string'))) {
                 return res.status(400).json({ error: 'cloudSyncProjects must be an array of strings' });
             }
+            if (proactiveRecall !== undefined && typeof proactiveRecall !== 'boolean') {
+                return res.status(400).json({ error: 'proactiveRecall must be a boolean' });
+            }
             const normalizedApiKey = cloudApiKey !== undefined
                 ? cloudApiKey.trim()
                 : existingConfig.cloudApiKey;
@@ -207,6 +211,9 @@ export function registerSystemRoutes(app, deps) {
                 ...(openclawAutoMemoryNoveltyThreshold !== undefined && { noveltyThreshold: openclawAutoMemoryNoveltyThreshold }),
                 ...(openclawAutoMemoryMaxRecent !== undefined && { maxRecent: openclawAutoMemoryMaxRecent }),
             });
+            if (proactiveRecall !== undefined) {
+                setProactiveRecall(proactiveRecall);
+            }
             const updated = getCloudConfig();
             res.json({
                 success: true,
@@ -215,6 +222,7 @@ export function registerSystemRoutes(app, deps) {
                 baseUrl: updated.cloudBaseUrl,
                 syncControls: getCloudSyncControls(),
                 openclawMemory: getOpenClawMemoryConfig(),
+                proactiveRecall: isProactiveRecallEnabled(),
             });
         }
         catch (error) {

package/dist/api/visualization-server.js

@@ -36,6 +36,7 @@ import { registerRecallRoutes } from './routes/recall.js';
 import { registerSystemRoutes } from './routes/system.js';
 import { registerXRayRoutes } from './routes/xray.js';
 import { registerXRayFindingRoutes } from './routes/xray-findings.js';
+import { registerDigestRoutes } from './routes/digest.js';
 import { createIronDomeRouteGuard } from './iron-dome-route-guard.js';
 import { readAndClearDetectionEvents } from '../xray/activity.js';
 const PORT = process.env.PORT || 3001;
@@ -191,6 +192,7 @@ export function startVisualizationServer(dbPath) {
         clients,
         requireIronDomeAction: createIronDomeRouteGuard,
     });
+    registerDigestRoutes(app);
     // ============================================
     // INSIGHTS ENDPOINTS
     // ============================================

package/dist/cli/doctor.d.ts

@@ -2,4 +2,31 @@
  * ShieldCortex Doctor — Installation health checker.
  * Runs diagnostics and reports issues with actionable fixes.
  */
+export type CheckStatus = 'pass' | 'warn' | 'fail' | 'info';
+export interface CheckResult {
+    label: string;
+    status: CheckStatus;
+    message: string;
+    fix?: string;
+}
+/**
+ * The honest "is it working?" check.
+ *
+ * Doctor checks have historically gone green while writes were silently
+ * failing (v4.12.4 path-encoding bug, v4.12.5 NOT NULL UUID schema gap).
+ * The pattern: schema introspection passed (columns existed) but actual
+ * INSERTs threw constraint violations during real workloads.
+ *
+ * This check does a real round-trip — INSERT a tagged probe memory,
+ * SELECT it back, DELETE it. If any step fails, doctor reports the
+ * actual error string instead of "all green". The probe is tagged with
+ * a unique source identifier so it can never be confused with real data
+ * and gets deleted at the end of the check.
+ */
+/**
+ * Pure helper for the write-path round-trip. Exported so tests can
+ * exercise it against any database path (in-memory or temp file)
+ * without going through doctor's homedir-derived getDbPath().
+ */
+export declare function runWritePathProbe(dbPath: string): CheckResult;
 export declare function runDoctor(): Promise<void>;

package/dist/cli/doctor.js

@@ -197,6 +197,93 @@ async function checkMemoryStats() {
         return { label: 'Memories', status: 'warn', message: `check failed — ${msg}` };
     }
 }
+// ── Check 3b: Write-path smoke test ───────────────────────
+/**
+ * The honest "is it working?" check.
+ *
+ * Doctor checks have historically gone green while writes were silently
+ * failing (v4.12.4 path-encoding bug, v4.12.5 NOT NULL UUID schema gap).
+ * The pattern: schema introspection passed (columns existed) but actual
+ * INSERTs threw constraint violations during real workloads.
+ *
+ * This check does a real round-trip — INSERT a tagged probe memory,
+ * SELECT it back, DELETE it. If any step fails, doctor reports the
+ * actual error string instead of "all green". The probe is tagged with
+ * a unique source identifier so it can never be confused with real data
+ * and gets deleted at the end of the check.
+ */
+/**
+ * Pure helper for the write-path round-trip. Exported so tests can
+ * exercise it against any database path (in-memory or temp file)
+ * without going through doctor's homedir-derived getDbPath().
+ */
+export function runWritePathProbe(dbPath) {
+    if (!fs.existsSync(dbPath)) {
+        return { label: 'Write path', status: 'warn', message: 'skipped (no database)' };
+    }
+    let db = null;
+    const probeUuid = `doctor-probe-${Date.now()}-${Math.random().toString(36).slice(2, 10)}`;
+    const probeTitle = '__shieldcortex_doctor_probe__';
+    try {
+        const Database = require('better-sqlite3');
+        db = new Database(dbPath);
+        // INSERT — exercises NOT NULL columns + CHECK constraints. The schema
+        // adds these silently across versions; an INSERT against a stale schema
+        // is the exact failure mode v4.12.5 had.
+        db.prepare(`
+      INSERT INTO memories (uuid, type, category, title, content, salience, source, capture_method)
+      VALUES (?, 'short_term', 'note', ?, 'doctor probe — safe to delete', 0.01, 'cli:doctor', 'doctor-probe')
+    `).run(probeUuid, probeTitle);
+        // SELECT — exercises the FTS5 + index path
+        const row = db.prepare('SELECT id, title FROM memories WHERE uuid = ?').get(probeUuid);
+        if (!row || row.title !== probeTitle) {
+            return {
+                label: 'Write path',
+                status: 'fail',
+                message: 'wrote a probe row but could not read it back',
+                fix: 'Database may be corrupted. Run `shieldcortex consolidate` then re-run doctor.',
+            };
+        }
+        // DELETE — exercises the cascade triggers (FTS5 cleanup)
+        const deleteResult = db.prepare('DELETE FROM memories WHERE uuid = ?').run(probeUuid);
+        if (deleteResult.changes !== 1) {
+            return {
+                label: 'Write path',
+                status: 'warn',
+                message: `probe row written + read OK but delete affected ${deleteResult.changes} rows (expected 1)`,
+                fix: 'Manual cleanup may be needed. Check ~/.shieldcortex/memories.db for orphaned rows.',
+            };
+        }
+        return { label: 'Write path', status: 'pass', message: 'INSERT/SELECT/DELETE round-trip OK' };
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        // Best-effort cleanup so we don't leave probe rows behind on a partial failure
+        if (db) {
+            try {
+                db.prepare('DELETE FROM memories WHERE uuid = ?').run(probeUuid);
+            }
+            catch { /* ignore */ }
+        }
+        return {
+            label: 'Write path',
+            status: 'fail',
+            message: `round-trip failed — ${msg}`,
+            fix: 'This is the smoking gun for a stale schema or migration drift. Try restarting the MCP server (auto-migrates), or re-install: shieldcortex install',
+        };
+    }
+    finally {
+        if (db) {
+            try {
+                db.close();
+            }
+            catch { /* ignore */ }
+        }
+    }
+}
+async function checkWritePath() {
+    return runWritePathProbe(getDbPath());
+}
 // ── Check 4: Hook installation ────────────────────────────
 async function checkHooks() {
     const settingsPath = path.join(os.homedir(), '.claude', 'settings.json');
@@ -498,6 +585,7 @@ export async function runDoctor() {
     const checks = [
         checkDatabase,
         checkSchema,
+        checkWritePath, // Smoke test: real INSERT/SELECT/DELETE round-trip — catches silent schema drift
         checkMemoryStats,
         checkHooks,
         checkProcesses,

package/dist/cli/migrate-legacy.d.ts

@@ -0,0 +1,28 @@
+interface MigrateOptions {
+    /** Source legacy DB paths to import from. Defaults to both ~/.claude-memory/ and ~/.claude-cortex/ */
+    sources?: string[];
+    /** Target DB path. Default ~/.shieldcortex/memories.db */
+    target?: string;
+    /** If true, count + report only — no writes. */
+    dryRun?: boolean;
+}
+interface SourceReport {
+    path: string;
+    exists: boolean;
+    memoriesFound: number;
+    memoriesImported: number;
+    linksFound: number;
+    linksImported: number;
+    linksSkipped: number;
+    error?: string;
+}
+interface MigrationReport {
+    target: string;
+    dryRun: boolean;
+    sources: SourceReport[];
+    totalMemories: number;
+    totalLinks: number;
+}
+export declare function migrateLegacy(options?: MigrateOptions): MigrationReport;
+export declare function handleMemoriesCommand(args: string[]): Promise<void>;
+export {};