shieldcortex 4.13.1 → 4.14.1

package/dist/cli/doctor.js

@@ -545,8 +545,12 @@ async function checkDiskUsage() {
     }
 }
 // ── Check 7: Lock file ───────────────────────────────────
-async function checkLockFile() {
-    const scDir = getShieldCortexDir();
+//
+// A lock is stale only if its recorded PID is no longer running. Pure mtime age
+// is unreliable: a long-running daemon (e.g. `shieldcortex dashboard` started
+// at boot) holds the same lock for days, and flagging it stale tells the user
+// to delete a file that is still in active use.
+export async function checkLockFile(scDir = getShieldCortexDir()) {
     if (!fs.existsSync(scDir)) {
         return { label: 'Lock', status: 'pass', message: 'clean' };
     }
@@ -561,18 +565,45 @@ async function checkLockFile() {
         if (lockFiles.length === 0) {
             return { label: 'Lock', status: 'pass', message: 'clean' };
         }
-        // Check if lock files are stale (older than 1 hour)
         const stale = [];
         const active = [];
-        const oneHourAgo = Date.now() - 60 * 60 * 1000;
+        // Fallback only used when the lock file is unparseable or has no PID.
+        const oneDayAgo = Date.now() - 24 * 60 * 60 * 1000;
         for (const lockFile of lockFiles) {
             const lockPath = path.join(scDir, lockFile);
-            const stat = fs.statSync(lockPath);
-            if (stat.mtimeMs < oneHourAgo) {
-                stale.push(lockFile);
+            let pid = null;
+            try {
+                const parsed = JSON.parse(fs.readFileSync(lockPath, 'utf-8'));
+                if (typeof parsed.pid === 'number' && Number.isFinite(parsed.pid)) {
+                    pid = parsed.pid;
+                }
+            }
+            catch {
+                // Unparseable lock — fall through to mtime fallback below.
+            }
+            if (pid !== null) {
+                try {
+                    process.kill(pid, 0);
+                    active.push(lockFile);
+                }
+                catch (err) {
+                    if (err.code === 'ESRCH') {
+                        stale.push(lockFile);
+                    }
+                    else {
+                        // EPERM = process exists, owned by another user. Treat as active.
+                        active.push(lockFile);
+                    }
+                }
             }
             else {
-                active.push(lockFile);
+                const stat = fs.statSync(lockPath);
+                if (stat.mtimeMs < oneDayAgo) {
+                    stale.push(lockFile);
+                }
+                else {
+                    active.push(lockFile);
+                }
             }
         }
         if (stale.length > 0) {
@@ -626,6 +657,207 @@ async function checkOpenClawResidue() {
         return { label: 'OpenClaw residue', status: 'warn', message: `check failed — ${msg}` };
     }
 }
+// ── Check 9: Auto-memory sampling rate (#44) ──────────────
+/**
+ * Reports the resolved `autoMemory.stopHookSamplingTurns` and salience-bypass
+ * setting. Defaults dropped 10 → 5 (and salience bypass added) in v4.14.0;
+ * warn if a user pinned a sparser cadence likely to under-feed LTM.
+ *
+ * Reads the config file directly rather than importing the .mjs helper so
+ * doctor doesn't depend on path layout between dist/ and scripts/.
+ */
+async function checkAutoMemorySampling() {
+    try {
+        const configPath = path.join(getShieldCortexDir(), 'config.json');
+        let raw = {};
+        if (fs.existsSync(configPath)) {
+            try {
+                raw = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
+            }
+            catch {
+                /* fall through to defaults */
+            }
+        }
+        const overrides = raw.autoMemory ?? {};
+        const sampling = typeof overrides.stopHookSamplingTurns === 'number' &&
+            Number.isFinite(overrides.stopHookSamplingTurns) &&
+            overrides.stopHookSamplingTurns > 0
+            ? Math.floor(overrides.stopHookSamplingTurns)
+            : 5; // default in auto-memory-config.mjs as of v4.14.0
+        const bypassEnabled = typeof overrides.stopHookSalienceBypass === 'boolean' ? overrides.stopHookSalienceBypass : true;
+        const bypass = bypassEnabled ? 'on' : 'off';
+        if (sampling <= 5) {
+            return {
+                label: 'Auto-memory sampling',
+                status: 'pass',
+                message: `every ${sampling} turn(s), salience-bypass ${bypass}`,
+            };
+        }
+        return {
+            label: 'Auto-memory sampling',
+            status: 'warn',
+            message: `every ${sampling} turn(s), salience-bypass ${bypass} — sparser than recommended`,
+            fix: 'Edit ~/.shieldcortex/config.json autoMemory.stopHookSamplingTurns (≤ 5 recommended)',
+        };
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        return { label: 'Auto-memory sampling', status: 'info', message: `check skipped — ${msg}` };
+    }
+}
+// ── Check 10: Brain-worker freshness (#45) ────────────────
+/**
+ * The MCP server starts a lite-profile brain worker on connect (v4.14.0).
+ * Each light tick writes to ~/.shieldcortex/state/worker.json. If the
+ * timestamp is missing or older than 30 min, consolidation has likely
+ * stalled — STM won't graduate to LTM.
+ */
+async function checkBrainWorker() {
+    if (process.env.SHIELDCORTEX_DISABLE_WORKER === '1') {
+        return {
+            label: 'Brain worker',
+            status: 'info',
+            message: 'disabled via SHIELDCORTEX_DISABLE_WORKER=1',
+        };
+    }
+    const statePath = path.join(getShieldCortexDir(), 'state', 'worker.json');
+    if (!fs.existsSync(statePath)) {
+        return {
+            label: 'Brain worker',
+            status: 'warn',
+            message: 'no worker.json — worker has not run yet',
+            fix: 'Start an MCP-bound session (Claude Code) or run `shieldcortex worker` to drive consolidation',
+        };
+    }
+    try {
+        const raw = JSON.parse(fs.readFileSync(statePath, 'utf-8'));
+        const last = raw.lastLightTick ? new Date(raw.lastLightTick) : null;
+        if (!last || Number.isNaN(last.getTime())) {
+            return {
+                label: 'Brain worker',
+                status: 'warn',
+                message: 'worker.json present but lastLightTick missing/invalid',
+                fix: 'Restart Claude Code to spawn a fresh MCP server',
+            };
+        }
+        const ageMs = Date.now() - last.getTime();
+        const ageMin = Math.round(ageMs / 60000);
+        if (ageMs > 30 * 60 * 1000) {
+            return {
+                label: 'Brain worker',
+                status: 'warn',
+                message: `last tick ${ageMin}m ago (profile=${raw.profile ?? '?'}, pid=${raw.pid ?? '?'})`,
+                fix: 'Restart Claude Code or run `shieldcortex worker` to resume consolidation',
+            };
+        }
+        return {
+            label: 'Brain worker',
+            status: 'pass',
+            message: `last tick ${ageMin}m ago (profile=${raw.profile ?? '?'}, pid=${raw.pid ?? '?'})`,
+        };
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        return { label: 'Brain worker', status: 'warn', message: `check failed — ${msg}` };
+    }
+}
+// ── Check 11: Project-key consistency (#42) ───────────────
+/**
+ * Detects rows tagged with both legacy basename keys and canonical
+ * owner-repo keys (the symptom of pre-v4.14.0 stop-hook writes). If any
+ * basename collides with a `<something>-<basename>` form already in the
+ * DB, point the user at `repair-project-keys`.
+ */
+async function checkProjectKeyConsistency() {
+    const dbPath = getDbPath();
+    if (!fs.existsSync(dbPath)) {
+        return { label: 'Project keys', status: 'info', message: 'skipped (no DB yet)' };
+    }
+    try {
+        const Database = require('better-sqlite3');
+        const db = new Database(dbPath, { readonly: true });
+        try {
+            const rows = db
+                .prepare("SELECT DISTINCT project FROM memories WHERE project IS NOT NULL AND project != ''")
+                .all();
+            const keys = rows.map((r) => r.project);
+            const collisions = [];
+            for (const candidate of keys) {
+                // A candidate is "legacy-looking" if it has no hyphen (cwd basename).
+                if (candidate.includes('-'))
+                    continue;
+                const suffix = `-${candidate}`;
+                const matched = keys.find((k) => k !== candidate && k.endsWith(suffix));
+                if (matched)
+                    collisions.push({ legacy: candidate, canonical: matched });
+            }
+            if (collisions.length === 0) {
+                return { label: 'Project keys', status: 'pass', message: `${keys.length} distinct, no legacy/canonical collisions` };
+            }
+            const example = collisions.slice(0, 3).map((c) => `${c.legacy} ↔ ${c.canonical}`).join('; ');
+            const more = collisions.length > 3 ? ` (+${collisions.length - 3} more)` : '';
+            return {
+                label: 'Project keys',
+                status: 'warn',
+                message: `${collisions.length} legacy/canonical collision(s): ${example}${more}`,
+                fix: 'Run `shieldcortex memories repair-project-keys --scan-paths <root>` (dry-run by default)',
+            };
+        }
+        finally {
+            db.close();
+        }
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        return { label: 'Project keys', status: 'warn', message: `check failed — ${msg}` };
+    }
+}
+// ── Check 12: Hook timeouts (#43) ─────────────────────────
+/**
+ * Compares each ShieldCortex hook's timeout in ~/.claude/settings.json
+ * against the canonical values written by `shieldcortex setup`. Catches
+ * the v4.13.x silent-recall failure mode where users on a hand-edited
+ * settings.json still ran with `UserPromptSubmit.timeout: 2`.
+ */
+async function checkHookTimeouts() {
+    const settingsPath = path.join(os.homedir(), '.claude', 'settings.json');
+    if (!fs.existsSync(settingsPath)) {
+        return { label: 'Hook timeouts', status: 'info', message: 'skipped (settings.json not found)' };
+    }
+    try {
+        const { CANONICAL_HOOK_TIMEOUTS } = await import('../setup/settings-hooks.js');
+        const settings = JSON.parse(fs.readFileSync(settingsPath, 'utf-8'));
+        const hooks = settings.hooks ?? {};
+        const drift = [];
+        for (const [name, expected] of Object.entries(CANONICAL_HOOK_TIMEOUTS)) {
+            const entries = hooks[name];
+            if (!Array.isArray(entries))
+                continue;
+            for (const entry of entries) {
+                for (const h of entry.hooks ?? []) {
+                    if (typeof h.command !== 'string' || !h.command.includes('shieldcortex'))
+                        continue;
+                    if (typeof h.timeout === 'number' && h.timeout < expected) {
+                        drift.push(`${name}=${h.timeout}s (canonical ${expected}s)`);
+                    }
+                }
+            }
+        }
+        if (drift.length === 0) {
+            return { label: 'Hook timeouts', status: 'pass', message: 'all canonical' };
+        }
+        return {
+            label: 'Hook timeouts',
+            status: 'warn',
+            message: `below canonical: ${drift.join(', ')}`,
+            fix: 'Re-run `shieldcortex install` to restore canonical timeouts',
+        };
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        return { label: 'Hook timeouts', status: 'info', message: `check skipped — ${msg}` };
+    }
+}
 // ── Check 8: Model cache ─────────────────────────────────
 async function checkModelCache() {
     const cacheDir = path.join(os.homedir(), '.cache', 'shieldcortex', 'models', 'Xenova', 'all-MiniLM-L6-v2');
@@ -672,7 +904,11 @@ export async function runDoctor() {
         checkWritePath, // Smoke test: real INSERT/SELECT/DELETE round-trip — catches silent schema drift
         checkMemoryStats,
         checkHooks,
+        checkHookTimeouts,
         checkAutoMemoryHooks,
+        checkAutoMemorySampling,
+        checkBrainWorker,
+        checkProjectKeyConsistency,
         checkProcesses,
         checkDiskUsage,
         checkLockFile,

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

@@ -25,4 +25,34 @@ interface MigrationReport {
 }
 export declare function migrateLegacy(options?: MigrateOptions): MigrationReport;
 export declare function handleMemoriesCommand(args: string[]): Promise<void>;
+interface RepairOptions {
+    /** Path to memories.db (defaults to ~/.shieldcortex/memories.db) */
+    dbPath?: string;
+    /** Walk these dev roots one level deep, propose mappings unambiguously */
+    scanPaths?: string[];
+    /** Explicit overrides; basename → canonical-key */
+    map?: Record<string, string>;
+    /** Limit the scan to a single legacy project key */
+    onlyProject?: string;
+    /** Include short-term rows (default: long-term + episodic only) */
+    includeStm?: boolean;
+    /** Default false — must be true to actually write */
+    execute?: boolean;
+    /** When true, never prompt (used by tests). Defaults to interactive. */
+    noConfirm?: boolean;
+}
+interface RepairProposal {
+    legacy: string;
+    canonical: string;
+    count: number;
+    source: 'map' | 'scan';
+}
+interface RepairReport {
+    dryRun: boolean;
+    proposals: RepairProposal[];
+    applied: number;
+    logPath?: string;
+    backupPath?: string;
+}
+export declare function repairProjectKeys(opts?: RepairOptions): Promise<RepairReport>;
 export {};

package/dist/cli/migrate-legacy.js

@@ -2,7 +2,9 @@ import fs from 'fs';
 import path from 'path';
 import os from 'os';
 import { randomUUID } from 'crypto';
+import readline from 'readline';
 import Database from 'better-sqlite3';
+import { deriveProjectKey } from '../context/derive-project-key.js';
 const DEFAULT_LEGACY_SOURCES = [
     path.join(os.homedir(), '.claude-cortex', 'memories.db'),
     path.join(os.homedir(), '.claude-memory', 'memories.db'),
@@ -265,6 +267,14 @@ function printUsage() {
     console.log('      Cluster near-duplicate long-term memories and keep the highest-');
     console.log('      salience representative. DRY-RUN BY DEFAULT — pass --execute.');
     console.log('      Backup auto-saved before any merge.');
+    console.log('');
+    console.log('  repair-project-keys [--scan-paths <dir,dir,...>]');
+    console.log('                      [--map basename=canonical]   (repeatable)');
+    console.log('                      [--project <key>] [--include-stm] [--execute]');
+    console.log('      Relabel memories tagged under a legacy basename project key');
+    console.log('      to their canonical owner-repo key (#42). DRY-RUN BY DEFAULT.');
+    console.log('      Backup auto-saved before any rewrite; per-rewrite log written');
+    console.log('      to ~/.shieldcortex/logs/project-key-repair-<ts>.json.');
 }
 export async function handleMemoriesCommand(args) {
     const sub = args[0];
@@ -286,6 +296,195 @@ export async function handleMemoriesCommand(args) {
         await runDedupe(args.slice(1));
         return;
     }
+    if (sub === 'repair-project-keys') {
+        await runRepairProjectKeys(args.slice(1));
+        return;
+    }
     printUsage();
     process.exit(1);
 }
+function parseMapFlags(args) {
+    const map = {};
+    for (let i = 0; i < args.length; i++) {
+        if (args[i] === '--map' && args[i + 1]) {
+            const pair = args[i + 1];
+            const eq = pair.indexOf('=');
+            if (eq <= 0 || eq === pair.length - 1) {
+                throw new Error(`--map expects 'basename=canonical', got '${pair}'`);
+            }
+            const k = pair.slice(0, eq).trim();
+            const v = pair.slice(eq + 1).trim();
+            if (!k || !v)
+                throw new Error(`--map basename and canonical must be non-empty: '${pair}'`);
+            map[k] = v;
+            i++;
+        }
+    }
+    return map;
+}
+function parseScanPaths(args) {
+    const v = flagValue(args, '--scan-paths');
+    if (!v)
+        return [];
+    return v
+        .split(',')
+        .map((s) => s.trim().replace(/^~(?=\/|$)/, os.homedir()))
+        .filter(Boolean);
+}
+async function confirmExecute(prompt) {
+    if (!process.stdin.isTTY)
+        return false;
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    try {
+        const answer = await new Promise((resolve) => rl.question(prompt, resolve));
+        return /^y(es)?$/i.test(answer.trim());
+    }
+    finally {
+        rl.close();
+    }
+}
+export async function repairProjectKeys(opts = {}) {
+    const dbPath = opts.dbPath ?? DEFAULT_TARGET;
+    if (!fs.existsSync(dbPath)) {
+        throw new Error(`memories DB not found at ${dbPath} — run \`shieldcortex setup\` first`);
+    }
+    const explicit = opts.map ?? {};
+    const scanPaths = opts.scanPaths ?? [];
+    const includeStm = opts.includeStm === true;
+    const dryRun = opts.execute !== true;
+    const db = new Database(dbPath);
+    db.pragma('busy_timeout = 10000');
+    let report;
+    try {
+        // 1. Distinct legacy project keys in the DB.
+        const typeFilter = includeStm ? '' : "AND type IN ('long_term', 'episodic')";
+        const distinct = db
+            .prepare(`SELECT DISTINCT project FROM memories WHERE project IS NOT NULL ${typeFilter}`)
+            .all();
+        const dbProjects = new Set(distinct.map((r) => r.project));
+        // 2. Build the proposal set.
+        const proposals = [];
+        const seen = new Set();
+        const addProposal = (legacy, canonical, source) => {
+            if (legacy === canonical)
+                return;
+            if (opts.onlyProject && legacy !== opts.onlyProject)
+                return;
+            if (!dbProjects.has(legacy))
+                return;
+            const key = `${legacy}${canonical}`;
+            if (seen.has(key))
+                return;
+            seen.add(key);
+            const countQ = db
+                .prepare(`SELECT COUNT(*) AS n FROM memories WHERE project = ? ${typeFilter}`)
+                .get(legacy);
+            proposals.push({ legacy, canonical, count: countQ.n, source });
+        };
+        // 2a. --map overrides win.
+        for (const [legacy, canonical] of Object.entries(explicit)) {
+            addProposal(legacy, canonical, 'map');
+        }
+        // 2b. --scan-paths: walk one level deep, run deriveProjectKey, match by basename.
+        for (const root of scanPaths) {
+            let entries = [];
+            try {
+                entries = fs.readdirSync(root);
+            }
+            catch {
+                continue;
+            }
+            for (const name of entries) {
+                const child = path.join(root, name);
+                let isDir = false;
+                try {
+                    isDir = fs.statSync(child).isDirectory();
+                }
+                catch {
+                    continue;
+                }
+                if (!isDir)
+                    continue;
+                const canonical = deriveProjectKey(child);
+                if (!canonical || canonical === name)
+                    continue;
+                addProposal(name, canonical, 'scan');
+            }
+        }
+        report = {
+            dryRun,
+            proposals,
+            applied: 0,
+        };
+        // 3. Print proposal table.
+        const banner = dryRun ? '[DRY RUN] ' : '';
+        console.log(`${banner}Project-key repair plan (${dbPath}):`);
+        if (proposals.length === 0) {
+            console.log('  No proposed rewrites — nothing to do.');
+            console.log('');
+            console.log('Tip: pass `--scan-paths ~/Development` (or `--map old=new`) so the');
+            console.log('     repair tool can match legacy basename keys against canonical');
+            console.log('     owner-repo keys derived from the git origin.');
+            return report;
+        }
+        for (const p of proposals) {
+            console.log(`  ${p.legacy.padEnd(40)} → ${p.canonical.padEnd(48)} (${p.count} rows, source: ${p.source})`);
+        }
+        const totalRows = proposals.reduce((s, p) => s + p.count, 0);
+        console.log('');
+        console.log(`Total: ${totalRows} rows across ${proposals.length} project key(s).`);
+        if (dryRun) {
+            console.log('');
+            console.log('Re-run with --execute to apply. To undo later:');
+            console.log('  shieldcortex memories repair-project-keys \\');
+            console.log('    ' + proposals.map((p) => `--map ${p.canonical}=${p.legacy}`).join(' \\\n    ') + ' --execute');
+            return report;
+        }
+        // 4. Confirm + backup + write.
+        if (!opts.noConfirm) {
+            const ok = await confirmExecute(`\nApply ${proposals.length} rewrite(s) to ${totalRows} rows? [y/N] `);
+            if (!ok) {
+                console.log('Aborted — no changes written.');
+                return report;
+            }
+        }
+        const backupPath = `${dbPath}.bak.${new Date().toISOString().replace(/[:.]/g, '-')}`;
+        fs.copyFileSync(dbPath, backupPath);
+        report.backupPath = backupPath;
+        console.log(`Backup: ${backupPath}`);
+        const update = db.prepare(`UPDATE memories SET project = ? WHERE project = ? ${typeFilter}`);
+        const txn = db.transaction(() => {
+            for (const p of proposals) {
+                const r = update.run(p.canonical, p.legacy);
+                report.applied += r.changes;
+            }
+        });
+        txn();
+        // 5. Per-rewrite JSON log under ~/.shieldcortex/logs/.
+        const logsDir = path.join(os.homedir(), '.shieldcortex', 'logs');
+        fs.mkdirSync(logsDir, { recursive: true });
+        const logPath = path.join(logsDir, `project-key-repair-${new Date().toISOString().replace(/[:.]/g, '-')}.json`);
+        fs.writeFileSync(logPath, JSON.stringify({
+            dbPath,
+            backupPath,
+            appliedAt: new Date().toISOString(),
+            rewrites: proposals,
+            totalRowsAffected: report.applied,
+        }, null, 2), 'utf-8');
+        report.logPath = logPath;
+        console.log(`Applied: ${report.applied} rows`);
+        console.log(`Log:     ${logPath}`);
+    }
+    finally {
+        db.close();
+    }
+    return report;
+}
+async function runRepairProjectKeys(args) {
+    const map = parseMapFlags(args);
+    const scanPaths = parseScanPaths(args);
+    const onlyProject = flagValue(args, '--project');
+    const includeStm = args.includes('--include-stm');
+    const execute = args.includes('--execute');
+    await repairProjectKeys({ map, scanPaths, onlyProject, includeStm, execute });
+}

package/dist/context/derive-project-key.d.ts

@@ -0,0 +1,36 @@
+/**
+ * TypeScript port of scripts/lib/project-key.mjs.
+ *
+ * Both the MCP-server side (this module) and the hook scripts must agree on
+ * how a cwd maps to a project key — otherwise writes and reads fall under
+ * different scopes and recall silently misses (issue #42).
+ *
+ * Resolution order:
+ *   1. SHIELDCORTEX_PROJECT_KEY env override
+ *   2. CLAUDE_MEMORY_PROJECT env override (legacy alias for SC env var)
+ *   3. ~/.shieldcortex/config.json projectKey
+ *   4. ~/.shieldcortex/config.json projectAliases[basename]
+ *   5. Git origin owner-repo (walk up from cwd)
+ *   6. Cwd basename (legacy behaviour), skipping noise directories
+ */
+export declare function basenameFromCwd(path: string | null | undefined): string | null;
+declare function parseOriginUrl(url: string): {
+    owner: string;
+    repo: string;
+} | null;
+declare function readOriginFromGitConfig(gitPath: string): {
+    owner: string;
+    repo: string;
+} | null;
+/**
+ * Derive the project key for a given working directory. Mirrors
+ * scripts/lib/project-key.mjs::deriveProjectKey so MCP-server-side and
+ * hook-side keys agree.
+ */
+export declare function deriveProjectKey(cwd: string | null | undefined): string | null;
+export declare const __internal: {
+    parseOriginUrl: typeof parseOriginUrl;
+    basenameFromCwd: typeof basenameFromCwd;
+    readOriginFromGitConfig: typeof readOriginFromGitConfig;
+};
+export {};