shieldcortex 4.31.1 → 4.32.0

package/dist/cloud/quarantine-sync.d.ts

@@ -2,8 +2,14 @@
  * Fire-and-forget: sends quarantined content to ShieldCortex cloud.
  * Never blocks, never throws. Failed requests are logged and queued for retry.
  *
- * IMPORTANT: Content is redacted before transmission — credentials and secrets
- * are replaced with [REDACTED-{type}] placeholders to prevent PII/secret leakage.
+ * IMPORTANT: Quarantine holds the most sensitive payloads, so it applies the
+ * SAME CloudSyncControls gating as memory-sync (see shouldSyncRecord /
+ * applyContentMode in memory-sync.ts) BEFORE any content leaves the device:
+ *   - project filter (`shouldSyncProject`) — excluded projects never sync
+ *   - `excludeSensitive` — CONFIDENTIAL+ items are dropped entirely
+ *   - `contentMode: 'metadata'` — content/title are redacted to a placeholder
+ * On top of that, credentials/secrets are always redacted with
+ * [REDACTED-{type}] placeholders to prevent secret leakage.
  */
 export declare function syncQuarantineToCloud(entry: {
     original_content: string;
@@ -14,4 +20,8 @@ export declare function syncQuarantineToCloud(entry: {
     threat_indicators: string[];
     anomaly_score: number;
     firewall_result: string;
+    /** Project the quarantined write belongs to (for the project filter). */
+    project?: string | null;
+    /** Sensitivity classification of the content (for `excludeSensitive`). */
+    sensitivity_level?: string | null;
 }): void;

package/dist/cloud/quarantine-sync.js

@@ -1,22 +1,44 @@
-import { getCloudConfig, getDeviceId, getDeviceName } from './config.js';
+import { getCloudConfig, getCloudSyncControls, getDeviceId, getDeviceName, isSensitiveLevel, shouldSyncProject, } from './config.js';
 import { enqueueFailedQuarantineSync } from './sync-queue.js';
 import { redactCredentials } from '../defence/credential-leak/index.js';
 /**
  * Fire-and-forget: sends quarantined content to ShieldCortex cloud.
  * Never blocks, never throws. Failed requests are logged and queued for retry.
  *
- * IMPORTANT: Content is redacted before transmission — credentials and secrets
- * are replaced with [REDACTED-{type}] placeholders to prevent PII/secret leakage.
+ * IMPORTANT: Quarantine holds the most sensitive payloads, so it applies the
+ * SAME CloudSyncControls gating as memory-sync (see shouldSyncRecord /
+ * applyContentMode in memory-sync.ts) BEFORE any content leaves the device:
+ *   - project filter (`shouldSyncProject`) — excluded projects never sync
+ *   - `excludeSensitive` — CONFIDENTIAL+ items are dropped entirely
+ *   - `contentMode: 'metadata'` — content/title are redacted to a placeholder
+ * On top of that, credentials/secrets are always redacted with
+ * [REDACTED-{type}] placeholders to prevent secret leakage.
  */
 export function syncQuarantineToCloud(entry) {
     const config = getCloudConfig();
     if (!config.cloudEnabled || !config.cloudApiKey)
         return;
+    // Apply the user's CloudSyncControls (parity with memory-sync).
+    const controls = getCloudSyncControls();
+    if (!shouldSyncProject(entry.project ?? null, controls))
+        return;
+    if (controls.excludeSensitive && isSensitiveLevel(entry.sensitivity_level ?? null))
+        return;
+    const metadataOnly = controls.contentMode === 'metadata';
+    // Always redact credentials; metadata-only mode replaces content entirely.
+    const safeContent = metadataOnly
+        ? '[ShieldCortex] Quarantine content redacted by local sync policy.'
+        : redactCredentials(entry.original_content);
+    const safeTitle = metadataOnly
+        ? '[Metadata only]'
+        : entry.original_title
+            ? redactCredentials(entry.original_title)
+            : entry.original_title;
     const payload = {
         ...entry,
-        // Redact credentials/secrets before sending to cloud
-        original_content: redactCredentials(entry.original_content),
-        original_title: entry.original_title ? redactCredentials(entry.original_title) : entry.original_title,
+        original_content: safeContent,
+        original_title: safeTitle,
+        content_redacted: metadataOnly,
         device_id: getDeviceId(),
         device_name: getDeviceName(),
         timestamp: new Date().toISOString(),

package/dist/cloud/sync-queue.d.ts

@@ -31,6 +31,9 @@ export interface QuarantineSyncEntry {
     threat_indicators: string[];
     anomaly_score: number;
     firewall_result: string;
+    project?: string | null;
+    sensitivity_level?: string | null;
+    content_redacted?: boolean;
     device_id: string;
     device_name: string;
     timestamp: string;
@@ -79,12 +82,28 @@ export declare function enqueueFailedGraphSync(entry: GraphSyncEnvelope): void;
  * number of rows dropped. Best-effort and never throws.
  */
 export declare function enforceQueueCap(maxRows?: number): number;
+export interface ProcessRetryOptions {
+    /**
+     * Maximum number of pending rows to attempt in one call. Bounds the network
+     * work an MCP-profile worker does per light tick (it passes a small budget,
+     * e.g. 25); the full dashboard profile uses the default. Resurrection is
+     * unaffected — only the pending-row SELECT is limited.
+     */
+    maxRows?: number;
+}
 /**
  * Process pending items in the retry queue.
- * SELECT pending WHERE next_retry_at <= now, retry each (up to 10 per tick).
+ *
+ * Runs a resurrection pass first (revive transiently-failed rows within TTL),
+ * then SELECTs pending rows due for retry (up to `maxRows`) and attempts each.
  * Awaits each fetch so results are accurate and no double-processing occurs.
+ *
+ * Failure handling:
+ *   - HTTP 4xx (≠429) → permanent: mark failed, no further retries.
+ *   - network/timeout/5xx/429 → transient: keep pending with capped (≤1h)
+ *     backoff, retrying until the 7-day TTL purge — survives long outages.
  */
-export declare function processRetryQueue(): Promise<SyncQueueResult>;
+export declare function processRetryQueue(options?: ProcessRetryOptions): Promise<SyncQueueResult>;
 /**
  * Get queue statistics by status.
  */

package/dist/cloud/sync-queue.js

@@ -159,26 +159,102 @@ function buildRetryRequest(payloadText) {
     }
     throw new Error('Unsupported sync queue payload');
 }
+/** Cap on transient backoff. A single offline laptop shouldn't wait more than
+ * an hour between retry attempts, but we don't want 2^attempts*30s to grow
+ * unbounded after a long outage (it hits days within ~14 attempts). */
+const MAX_BACKOFF_MS = 60 * 60 * 1000; // 1h
+const BASE_BACKOFF_MS = 30_000;
 /**
- * Mark a queue row as retrying (schedule next attempt) or permanently failed.
- * Exponential backoff: 2^attempts * 30s (30s, 60s, 120s).
+ * Classify a sync failure to decide retry policy.
+ *
+ * - 'permanent': HTTP 4xx. The request is malformed, unauthorised, or points
+ *   at something that doesn't exist — retrying is pointless, so fail fast.
+ * - 'transient': network errors, timeouts/AbortError, HTTP 5xx, HTTP 429.
+ *   The server or link is temporarily unavailable; retrying always makes
+ *   sense, so we keep the row pending (capped backoff) until the 7-day TTL
+ *   purge removes it.
+ *
+ * 429 (rate limited) is deliberately transient — backing off and retrying is
+ * exactly the right response to a rate limit.
+ */
+function classifyHttpStatus(status) {
+    // 4xx (except 429) is a client error → permanent. 429 + 5xx → transient.
+    if (status === 429)
+        return 'transient';
+    if (status >= 400 && status < 500)
+        return 'permanent';
+    return 'transient';
+}
+/**
+ * Heuristic for whether a stored `last_error` describes a transient failure,
+ * used by the resurrection pass to revive rows that the OLD 3-attempt logic
+ * wrongly marked terminal. We can't store the classification (no schema
+ * change), so we infer from the message:
+ *   - `HTTP 4xx` (but not `HTTP 429`) → permanent → leave failed.
+ *   - everything else (timeouts, network messages, `HTTP 5xx`, `HTTP 429`)
+ *     → transient → resurrect.
+ * Conservative by design: an unrecognised message is treated as transient so
+ * we err on the side of retrying rather than silently dropping a sync.
  */
-function markRetryOrFailed(rowId, currentAttempts, newAttempts, maxAttempts, errorMsg) {
+function isTransientErrorMessage(lastError) {
+    if (!lastError)
+        return true;
+    const m = /^HTTP (\d{3})/.exec(lastError);
+    if (m)
+        return classifyHttpStatus(Number(m[1])) === 'transient';
+    return true; // network/timeout/unknown → transient
+}
+/**
+ * Schedule a transient-failure retry. Keeps the row `pending` with a future
+ * `next_retry_at` using capped exponential backoff (min(2^attempts*30s, 1h)).
+ * Crucially this does NOT honour max_attempts — transient errors retry until
+ * the 7-day TTL purge, so an overnight outage recovers instead of being
+ * permanently lost after 3 strikes. `attempts` still increments for observability.
+ */
+function scheduleRetry(rowId, currentAttempts, newAttempts, errorMsg) {
     const db = getDatabase();
-    if (newAttempts >= maxAttempts) {
-        db.prepare(`
-      UPDATE sync_queue SET status = 'failed', attempts = ?, last_error = ?
-      WHERE id = ?
-    `).run(newAttempts, errorMsg, rowId);
-        return true; // permanently failed
-    }
-    const backoffMs = Math.pow(2, currentAttempts) * 30_000;
+    const backoffMs = Math.min(Math.pow(2, currentAttempts) * BASE_BACKOFF_MS, MAX_BACKOFF_MS);
     const nextRetry = new Date(Date.now() + backoffMs).toISOString();
     db.prepare(`
-    UPDATE sync_queue SET attempts = ?, next_retry_at = ?, last_error = ?
+    UPDATE sync_queue SET status = 'pending', attempts = ?, next_retry_at = ?, last_error = ?
     WHERE id = ?
   `).run(newAttempts, nextRetry, errorMsg, rowId);
-    return false;
+}
+/**
+ * Mark a queue row permanently failed (HTTP 4xx). No further retries.
+ */
+function markPermanentlyFailed(rowId, newAttempts, errorMsg) {
+    const db = getDatabase();
+    db.prepare(`
+    UPDATE sync_queue SET status = 'failed', attempts = ?, last_error = ?
+    WHERE id = ?
+  `).run(newAttempts, errorMsg, rowId);
+}
+/**
+ * Revive `failed` rows that were really transient failures (old 3-attempt
+ * logic, or pre-upgrade rows). Only rows still within the 7-day TTL window
+ * and whose `last_error` looks transient are reset to `pending` + due now.
+ * Genuine 4xx failures stay failed. Returns the number of rows resurrected.
+ */
+function resurrectTransientFailures() {
+    const db = getDatabase();
+    const now = new Date().toISOString();
+    const cutoff = new Date(Date.now() - 7 * 24 * 60 * 60 * 1000).toISOString();
+    // Resurrect failed rows within TTL whose last_error is NOT a 4xx (4xx except
+    // 429 are permanent). `HTTP 429` and `HTTP 5xx` and network/timeout messages
+    // all fall through to transient. NULL last_error → transient (be generous).
+    const result = db.prepare(`
+    UPDATE sync_queue
+    SET status = 'pending', next_retry_at = ?
+    WHERE status = 'failed'
+      AND created_at > ?
+      AND (
+        last_error IS NULL
+        OR last_error NOT GLOB 'HTTP 4[0-9][0-9]*'
+        OR last_error GLOB 'HTTP 429*'
+      )
+  `).run(now, cutoff);
+    return Number(result.changes ?? 0);
 }
 function formatQueueError(err) {
     const name = err instanceof Error ? err.name : '';
@@ -191,14 +267,25 @@ function formatQueueError(err) {
     }
     return message;
 }
+// Default per-tick budget for the full profile. Kept at the historical value
+// so dashboard behaviour is unchanged; mcp callers pass a smaller budget.
+const DEFAULT_RETRY_BUDGET = 10;
 /**
  * Process pending items in the retry queue.
- * SELECT pending WHERE next_retry_at <= now, retry each (up to 10 per tick).
+ *
+ * Runs a resurrection pass first (revive transiently-failed rows within TTL),
+ * then SELECTs pending rows due for retry (up to `maxRows`) and attempts each.
  * Awaits each fetch so results are accurate and no double-processing occurs.
+ *
+ * Failure handling:
+ *   - HTTP 4xx (≠429) → permanent: mark failed, no further retries.
+ *   - network/timeout/5xx/429 → transient: keep pending with capped (≤1h)
+ *     backoff, retrying until the 7-day TTL purge — survives long outages.
  */
-export async function processRetryQueue() {
+export async function processRetryQueue(options = {}) {
     const db = getDatabase();
     const config = getCloudConfig();
+    const limit = options.maxRows && options.maxRows > 0 ? options.maxRows : DEFAULT_RETRY_BUDGET;
     const result = {
         processed: 0,
         succeeded: 0,
@@ -209,15 +296,23 @@ export async function processRetryQueue() {
     if (!config.cloudEnabled || !config.cloudApiKey) {
         return result;
     }
+    // Revive any transiently-failed rows (old 3-attempt logic / pre-upgrade)
+    // before selecting the pending batch, so they get a chance this tick.
+    try {
+        resurrectTransientFailures();
+    }
+    catch {
+        /* best-effort — resurrection failure must not block live retries */
+    }
     const now = new Date().toISOString();
-    // Fetch up to 10 pending items ready for retry
+    // Fetch pending items ready for retry, bounded by the budget.
     const rows = db.prepare(`
-    SELECT id, payload, attempts, max_attempts
+    SELECT id, payload, attempts
     FROM sync_queue
     WHERE status = 'pending' AND next_retry_at <= ?
     ORDER BY next_retry_at ASC
-    LIMIT 10
-  `).all(now);
+    LIMIT ?
+  `).all(now, limit);
     if (rows.length === 0) {
         return result;
     }
@@ -250,21 +345,21 @@ export async function processRetryQueue() {
                 }
                 catch { /* non-critical */ }
             }
+            else if (classifyHttpStatus(res.status) === 'permanent') {
+                markPermanentlyFailed(row.id, newAttempts, `HTTP ${res.status}`);
+                result.permanentlyFailed++;
+            }
             else {
-                const permanent = markRetryOrFailed(row.id, row.attempts, newAttempts, row.max_attempts, `HTTP ${res.status}`);
-                if (permanent)
-                    result.permanentlyFailed++;
-                else
-                    result.failed++;
+                // 5xx / 429 — transient, keep retrying with capped backoff.
+                scheduleRetry(row.id, row.attempts, newAttempts, `HTTP ${res.status}`);
+                result.failed++;
             }
         }
         catch (err) {
+            // Network errors, timeouts (AbortError) — all transient.
             const errorMsg = formatQueueError(err);
-            const permanent = markRetryOrFailed(row.id, row.attempts, newAttempts, row.max_attempts, errorMsg);
-            if (permanent)
-                result.permanentlyFailed++;
-            else
-                result.failed++;
+            scheduleRetry(row.id, row.attempts, newAttempts, errorMsg);
+            result.failed++;
         }
     }
     return result;

package/dist/database/better-sqlite3-guard.d.ts

@@ -6,15 +6,40 @@
  * toolchain to compile from source), the native load fails — historically
  * with a bare `libc++abi: terminating ... Napi::Error` crash-loop and zero
  * guidance. This module is the single place better-sqlite3 is loaded at
- * runtime: it turns that failure into one actionable message and a clean
- * exit instead of an opaque abort.
+ * runtime: it turns that failure into one actionable, catchable error
+ * instead of an opaque abort.
+ *
+ * It must NEVER call `process.exit()`: this module is reachable from the
+ * library entry (`shieldcortex` → `initDatabase`), so a host app that merely
+ * imports the package must not be terminated. The load failure is thrown as a
+ * typed `NativeModuleLoadError`; a CLI/server entry point can catch it and
+ * decide to exit, but the module itself stays a well-behaved library.
  */
 import type DatabaseConstructor from 'better-sqlite3';
+/**
+ * Thrown when the better-sqlite3 native binding cannot be loaded (missing /
+ * ABI-mismatched / wrong-arch prebuild, or the module is not installed).
+ *
+ * Carries the actionable, formatted guidance in `.message` so a caller can
+ * print it verbatim. Typed so entry points can distinguish an environmental
+ * install problem from a genuine runtime error and exit cleanly if they choose.
+ */
+export declare class NativeModuleLoadError extends Error {
+    /** The original error raised by `require('better-sqlite3')`. */
+    readonly cause: unknown;
+    constructor(message: string, cause: unknown);
+}
 /**
  * Build the user-facing message for a native-load failure. Pure and
  * side-effect free so it can be unit-tested without breaking the binding.
  */
 export declare function formatNativeLoadError(err: unknown, nodeVersion: string, abi: string): string;
+/**
+ * True when an error from opening the database is a better-sqlite3 native-module
+ * load failure (environmental), as opposed to genuine file corruption. Pure +
+ * exported so the init path can route it away from destructive recovery.
+ */
+export declare function isNativeModuleLoadError(error: unknown): boolean;
 declare const BetterSqlite3: typeof DatabaseConstructor;
 export type { DatabaseConstructor };
 export default BetterSqlite3;

package/dist/database/better-sqlite3-guard.js

@@ -6,11 +6,34 @@
  * toolchain to compile from source), the native load fails — historically
  * with a bare `libc++abi: terminating ... Napi::Error` crash-loop and zero
  * guidance. This module is the single place better-sqlite3 is loaded at
- * runtime: it turns that failure into one actionable message and a clean
- * exit instead of an opaque abort.
+ * runtime: it turns that failure into one actionable, catchable error
+ * instead of an opaque abort.
+ *
+ * It must NEVER call `process.exit()`: this module is reachable from the
+ * library entry (`shieldcortex` → `initDatabase`), so a host app that merely
+ * imports the package must not be terminated. The load failure is thrown as a
+ * typed `NativeModuleLoadError`; a CLI/server entry point can catch it and
+ * decide to exit, but the module itself stays a well-behaved library.
  */
 import { createRequire } from 'module';
 const require = createRequire(import.meta.url);
+/**
+ * Thrown when the better-sqlite3 native binding cannot be loaded (missing /
+ * ABI-mismatched / wrong-arch prebuild, or the module is not installed).
+ *
+ * Carries the actionable, formatted guidance in `.message` so a caller can
+ * print it verbatim. Typed so entry points can distinguish an environmental
+ * install problem from a genuine runtime error and exit cleanly if they choose.
+ */
+export class NativeModuleLoadError extends Error {
+    /** The original error raised by `require('better-sqlite3')`. */
+    cause;
+    constructor(message, cause) {
+        super(message);
+        this.name = 'NativeModuleLoadError';
+        this.cause = cause;
+    }
+}
 /**
  * Build the user-facing message for a native-load failure. Pure and
  * side-effect free so it can be unit-tested without breaking the binding.
@@ -32,15 +55,45 @@ export function formatNativeLoadError(err, nodeVersion, abi) {
         `Underlying error: ${detail}`,
     ].join('\n');
 }
+/**
+ * Signatures of a NATIVE-MODULE load failure (missing / ABI-mismatched / wrong-
+ * arch better-sqlite3 binding, or the module not being installed). These throw
+ * from `new Database()` — better-sqlite3 resolves its binding lazily at
+ * construction, not at require() — and must be distinguished from genuine SQLite
+ * FILE corruption: a load failure is an install problem, and treating it as
+ * corruption (renaming the live DB to .corrupt.*) is data loss.
+ */
+const NATIVE_LOAD_SIGNATURES = [
+    /could not locate the bindings file/i,
+    /better_sqlite3\.node/i,
+    /NODE_MODULE_VERSION/i,
+    /compiled against a different node/i,
+    /invalid ELF header/i,
+    /wrong ELF class/i,
+    /dlopen\(/i,
+    /symbol not found/i,
+    /specified module could not be found/i,
+    /cannot find module ['"]better-sqlite3/i,
+];
+/**
+ * True when an error from opening the database is a better-sqlite3 native-module
+ * load failure (environmental), as opposed to genuine file corruption. Pure +
+ * exported so the init path can route it away from destructive recovery.
+ */
+export function isNativeModuleLoadError(error) {
+    const msg = error instanceof Error ? error.message : String(error ?? '');
+    return NATIVE_LOAD_SIGNATURES.some((re) => re.test(msg));
+}
 function loadBetterSqlite3() {
     try {
         return require('better-sqlite3');
     }
     catch (err) {
         const message = formatNativeLoadError(err, process.version, String(process.versions.modules));
-        // Clean, single-message fatal exit — never the bare libc++abi crash-loop.
-        console.error(`\n${message}\n`);
-        process.exit(1);
+        // THROW, never exit: this module is imported by the library entry, so it
+        // must not kill a host app. The message carries the rebuild guidance; an
+        // entry point (CLI/server) may catch this and exit if it wants to.
+        throw new NativeModuleLoadError(message, err);
     }
 }
 const BetterSqlite3 = loadBetterSqlite3();

package/dist/database/init.js

@@ -1,7 +1,7 @@
 /**
  * Database initialization and connection management
  */
-import BetterSqlite3 from './better-sqlite3-guard.js';
+import BetterSqlite3, { isNativeModuleLoadError } from './better-sqlite3-guard.js';
 import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync, unlinkSync, renameSync, copyFileSync, readdirSync, openSync, closeSync, realpathSync } from 'fs';
 import { basename, dirname, join } from 'path';
 import { homedir } from 'os';
@@ -9,6 +9,7 @@ import { fileURLToPath } from 'url';
 import { execSync } from 'child_process';
 import { runMigrations } from './migrations.js';
 import { getInlineSchema } from './inline-schema.js';
+import { seedDefaultFirewallRules } from './seed-firewall-rules.js';
 const _currentFile = fileURLToPath(import.meta.url);
 const _currentDir = dirname(_currentFile);
 let db = null;
@@ -427,16 +428,45 @@ export function initDatabase(dbPath) {
     currentDbPath = expandedPath;
     acquireStartupLock(expandedPath);
     console.error(`[database] Startup runtime=${resolveRuntimeInfo().kind} db=${expandedPath} wal=${existsSync(expandedPath + '-wal')} shm=${existsSync(expandedPath + '-shm')}`);
-    const healthyBackups = listHealthyBackups(expandedPath);
+    // Lazily inspect `.corrupt.*` backups (Phase 17 B4). Each backup inspection
+    // opens the file read-only and runs a FULL integrity check, so doing it
+    // unconditionally on every startup paid a per-backup scan even when the live
+    // DB opened cleanly. Defer it: the only consumers are the corruption /
+    // empty-live recovery branches below, so the scan now happens ONLY when
+    // recovery is actually invoked. Memoised so a branch that consults it twice
+    // still inspects each backup once.
+    let _healthyBackups = null;
+    const getHealthyBackups = () => {
+        if (_healthyBackups === null) {
+            _healthyBackups = listHealthyBackups(expandedPath);
+        }
+        return _healthyBackups;
+    };
     // Wrap the initial open in try/catch to handle corrupt files gracefully
     let database;
     try {
         database = new BetterSqlite3(expandedPath);
     }
     catch (openError) {
+        // A NATIVE-MODULE load failure (missing / ABI-mismatched better-sqlite3
+        // binding) throws here too — better-sqlite3 resolves its binding lazily in
+        // the constructor, so it surfaces at open time, NOT at require(). That is an
+        // INSTALL problem, not file corruption: renaming a healthy DB to .corrupt.*
+        // here is data loss (observed 2026-06-09 on an arm64 box after a Node/native
+        // mismatch — a live memories.db was moved aside). Never touch the DB file on
+        // a binding error; surface an actionable message and let the caller stop.
+        if (isNativeModuleLoadError(openError)) {
+            const detail = openError instanceof Error ? openError.message : String(openError);
+            throw new Error('ShieldCortex could not load its database engine (the better-sqlite3 native module). ' +
+                `This is an install / Node-version issue, NOT database corruption — your data at ${expandedPath} is untouched. ` +
+                'Rebuild the native module and retry:\n' +
+                '  cd "$(npm root -g)/shieldcortex" && npm rebuild better-sqlite3\n' +
+                '(install a C/C++ toolchain first if it fails to compile)\n' +
+                `Underlying error: ${detail}`);
+        }
         // Database file is corrupt or not a valid SQLite database
         console.error(`❌ Database open failed for ${expandedPath}: ${openError}`);
-        const latestHealthyBackup = healthyBackups[0];
+        const latestHealthyBackup = getHealthyBackups()[0];
         if (latestHealthyBackup) {
             console.error(`[database] Restoring latest healthy backup with ${latestHealthyBackup.count} memories: ${latestHealthyBackup.path}`);
             restoreBackupAsLive(expandedPath, latestHealthyBackup.path, 'failed-open');
@@ -449,13 +479,21 @@ export function initDatabase(dbPath) {
             database = new BetterSqlite3(expandedPath);
         }
     }
-    // Integrity check on existing databases (skip for newly created files)
+    // Integrity check on existing databases (skip for newly created files).
+    // This is the SINGLE live-DB integrity scan on the startup path (Phase 17
+    // B4). `liveIntegrityOk` records its outcome so the empty-live heuristic
+    // below can reuse it instead of re-opening the file and scanning a second
+    // time. It stays true for freshly-created files (size 0, check skipped) and
+    // for connections rebuilt by a recovery branch — both are known-good.
+    let liveIntegrityOk = true;
     if (existsSync(expandedPath) && statSync(expandedPath).size > 0) {
         const integrityResult = runIntegrityCheck(database);
+        liveIntegrityOk = integrityResult === 'ok';
         if (integrityResult !== 'ok') {
             console.warn(`[database] WARNING: Database integrity check failed: ${integrityResult}`);
             if (isLikelyFtsIntegrityIssue(integrityResult) && attemptFtsRecovery(database)) {
                 console.warn('[database] Preserved memory rows by repairing the FTS index in place.');
+                liveIntegrityOk = true; // FTS rebuild re-verified integrity == 'ok'.
             }
             else {
                 const freshIntegrityResult = verifyOnDiskIntegrity(expandedPath);
@@ -463,6 +501,7 @@ export function initDatabase(dbPath) {
                     console.warn('[database] Integrity failure was transient. Reopening the on-disk database without destructive recovery.');
                     database.close();
                     database = new BetterSqlite3(expandedPath);
+                    liveIntegrityOk = true; // On-disk re-check was clean.
                 }
                 else {
                     console.warn(`[database] Fresh integrity check also failed: ${freshIntegrityResult}`);
@@ -474,7 +513,7 @@ export function initDatabase(dbPath) {
                         database = recovered;
                     }
                     else {
-                        const latestHealthyBackup = healthyBackups[0];
+                        const latestHealthyBackup = getHealthyBackups()[0];
                         if (latestHealthyBackup) {
                             console.error(`[database] Recovery failed. Restoring latest healthy backup with ${latestHealthyBackup.count} memories: ${latestHealthyBackup.path}`);
                             restoreBackupAsLive(expandedPath, latestHealthyBackup.path, 'recovery-failed');
@@ -490,23 +529,40 @@ export function initDatabase(dbPath) {
                             database = new BetterSqlite3(expandedPath);
                         }
                     }
+                    // Dump-recovery, backup-restore and fresh-create all yield a
+                    // known-good DB — the empty-live heuristic can trust it.
+                    liveIntegrityOk = true;
                 }
             }
         }
     }
-    const currentInspection = inspectDatabaseFile(expandedPath);
-    const latestHealthyBackup = healthyBackups[0];
+    // Empty-live recovery heuristic (Phase 17 B4): this used to call
+    // `inspectDatabaseFile(expandedPath)`, which RE-OPENED the live file
+    // read-only and ran a SECOND full integrity check purely to obtain the row
+    // count — duplicating the scan already performed above. Now the count comes
+    // from the open connection and integrity is reused from `liveIntegrityOk`.
+    // `getHealthyBackups()` (the eager per-backup scan) is consulted ONLY when
+    // the live DB is actually healthy-but-empty, so a normal startup never
+    // inspects a backup at all.
+    let liveCount = null;
+    try {
+        liveCount = database.prepare('SELECT COUNT(*) AS count FROM memories').get().count;
+    }
+    catch {
+        liveCount = null;
+    }
     const liveStats = existsSync(expandedPath) ? statSync(expandedPath) : null;
-    if (currentInspection.integrity === 'ok'
-        && currentInspection.count === 0
-        && latestHealthyBackup
-        && latestHealthyBackup.count >= 100
-        && liveStats
-        && (liveStats.mtimeMs - latestHealthyBackup.mtimeMs) < (24 * 60 * 60 * 1000)) {
-        console.error(`[database] Empty live database detected alongside a recent healthy backup (${latestHealthyBackup.count} memories). Restoring ${latestHealthyBackup.path}`);
-        database.close();
-        restoreBackupAsLive(expandedPath, latestHealthyBackup.path, 'empty-live');
-        database = new BetterSqlite3(expandedPath);
+    if (liveIntegrityOk && liveCount === 0) {
+        const latestHealthyBackup = getHealthyBackups()[0];
+        if (latestHealthyBackup
+            && latestHealthyBackup.count >= 100
+            && liveStats
+            && (liveStats.mtimeMs - latestHealthyBackup.mtimeMs) < (24 * 60 * 60 * 1000)) {
+            console.error(`[database] Empty live database detected alongside a recent healthy backup (${latestHealthyBackup.count} memories). Restoring ${latestHealthyBackup.path}`);
+            database.close();
+            restoreBackupAsLive(expandedPath, latestHealthyBackup.path, 'empty-live');
+            database = new BetterSqlite3(expandedPath);
+        }
     }
     db = database;
     // Record file identity so getDatabase() can detect if the file was replaced
@@ -561,6 +617,18 @@ export function initDatabase(dbPath) {
         // Inline schema if file not found (for bundled deployment)
         db.exec(getInlineSchema());
     }
+    // Seed built-in firewall rules. This runs AFTER the schema so the
+    // firewall_rules table is guaranteed to exist — `runMigrations()` returns
+    // early on a fresh DB (no `memories` table), so seeding cannot live there or
+    // it never fires for new installs (the case the README's "seeded on first
+    // run" promise covers). Idempotent: the seeder no-ops when built_in rows are
+    // already present, so re-running on every startup is safe and cheap.
+    try {
+        seedDefaultFirewallRules(db);
+    }
+    catch {
+        // Seeder is best-effort; a failure here must never block startup.
+    }
     return db;
 }
 /**