quilltap 4.7.0-dev.101 → 4.7.0-dev.129

package/README.md

@@ -89,6 +89,20 @@ Quilltap stores its database, files, and logs in a platform-specific directory:
 
 Override with `--data-dir` or the `QUILLTAP_DATA_DIR` environment variable.
 
+## Named Instances
+
+Register a data directory once and point the CLI at it by name, instead of repeating `--data-dir`:
+
+```bash
+quilltap instances add Friday ~/iCloud/Quilltap/Friday   # Register (prompts for the passphrase if encrypted)
+quilltap instances list                                  # Registered instances (* marks the default)
+quilltap instances default Friday                        # Make it the fall-through for flag-free runs
+quilltap instances rename Friday Weekday                 # Rename, preserving the stored passphrase
+quilltap instances remove Friday                         # Unregister
+```
+
+Every subcommand then accepts `--instance <name>` in place of `--data-dir`. The registry lives at `<app-support>/Quilltap/instances.json` (mode 0600; e.g. `~/Library/Application Support/Quilltap/instances.json` on macOS). **Resolution precedence:** `--data-dir` > `--instance` > registered default > `QUILLTAP_DATA_DIR` > the OS platform default. Pass the **instance root** (e.g. `~/iCloud/Quilltap/Friday`), not its `data/` subdirectory.
+
 ## Database Tool
 
 The encrypted SQLite databases (main, LLM logs, mount index) can be queried directly via `quilltap db`. There are two modes: high-level subcommands that auto-pick the right database and resolve characters/chats/projects by name, and a low-level path for arbitrary SQL.
@@ -216,6 +230,17 @@ quilltap memories status [--character <name|id>]                       # Per-hol
 
 Shared filter flags apply to `ls`, `find`, `grep`, and `status` where they make sense: `--character`, `--about` (with `self` / `none` shortcuts), `--source`, `--chat` (with `none` for manual entries), `--project`, `--since`, `--until`, `--min-importance`, `--min-reinforced`, `--has-embedding` / `--no-embedding`. Sort flags (`--sort reinforced|importance|created|accessed|reinforcement-count|links`, plus `-r` to reverse) apply to `ls`, `find`, and `grep`. Names accept fuzzy substrings; ambiguous names print candidates and exit 2. `--json` is supported by every verb. The legacy `quilltap db memories --character <name>` verb remains undisturbed.
 
+## Memory Extraction Dry-Run
+
+`quilltap memory-diff <chatId>` is a diagnostic that dumps a chat's existing memories and dry-runs re-extraction against it **without writing anything** — useful for seeing how an extractor change would land on a real conversation.
+
+```bash
+quilltap memory-diff <chatId> --instance Friday          # Report to the current directory
+quilltap memory-diff <chatId> --out /tmp/diff --concurrency 8
+```
+
+Needs a running server (`--port`, default 3000) to reach the extraction pipeline. `--out <dir>` sets the report destination (default: cwd); `--concurrency N` bounds parallel turns (default 4, max 32).
+
 ## Maintenance & Cleanup
 
 `quilltap maintenance` is the manual trigger for the retention sweeps that otherwise run on the server's daily maintenance tick. It reaps data with no bearing on characters, stories, or memories.
@@ -228,6 +253,31 @@ quilltap maintenance run --instance Friday    # Run the sweeps once (lock-gated;
 
 `maintenance run` is a DB writer: it claims `<dataDir>/quilltap.lock` and **refuses while a running Quilltap server holds it** — stop the server first. Because it can only run with the server down, it performs the sweeps expressible as direct SQL/filesystem work: reaping finished background jobs (COMPLETED after 7 days, DEAD after 30, keyed off `completedAt`), closed terminal sessions older than 30 days plus their transcript files, and orphaned mount-index files. The **stale-chat asset collapse** (superseded story-backgrounds and wardrobe avatars) needs the server's file-storage machinery and runs only on the server's daily tick — `status` reports a stale-chat count so you can see the backlog. Retention windows mirror `lib/background-jobs/maintenance/retention-constants.ts`.
 
+## Logs
+
+`quilltap logs` tails or prints an instance's log files without hunting down the logs directory. Prefer it over `tail -f` — it follows across log rotation and can merge streams.
+
+```bash
+quilltap logs                                 # Last 100 lines of combined.log
+quilltap logs --tail 0 --stream error         # Whole error log
+quilltap logs -f --grep "MEMORY_EXTRACTION"   # Follow, filtered by regex
+quilltap logs --stream combined,error         # Merge streams with [stream] prefixes
+```
+
+Flags: `--stream combined|error|stdout|stderr|startup` (comma-separated for multiple), `--tail N` (default 100; `0` = full file), `--follow` / `-f`, `--grep <pattern>` (JS regex). Resolves the logs directory via the same `--instance` / `--data-dir` plumbing as the rest of the CLI.
+
+## Migrations
+
+`quilltap migrations` inspects migration state read-only. The actual runner stays at server startup (where the loading screen reports progress), so the CLI deliberately won't apply anything.
+
+```bash
+quilltap migrations status        # Counts: in-source vs recorded-applied vs not-yet-recorded
+quilltap migrations pending       # Just the not-yet-recorded list
+quilltap migrations run --dry-run # List what would run (refuses without --dry-run)
+```
+
+`--json` works on all three. "Not yet recorded" includes migrations whose `shouldRun()` is `false` on this instance — the CLI doesn't evaluate the predicate, so it can't distinguish "would skip" from "would run."
+
 ## Theme Management
 
 The CLI includes theme management commands:

package/bin/quilltap.js

@@ -13,7 +13,7 @@ const {
   loadDbKey,
 } = require('../lib/db-helpers');
 const { resolveInstance } = require('../lib/instances');
-const { resolveModuleDir, ensureNativeModules } = require('../lib/native-modules');
+const { resolveModuleDir, ensureNativeModules, ensureDatabaseNativeModule } = require('../lib/native-modules');
 
 const PACKAGE_DIR = path.resolve(__dirname, '..');
 
@@ -94,7 +94,12 @@ Subcommands:
   docs                          Inspect, read, and export document mounts
   memories                      Search, browse, and graph memories
   instances                     Register / inspect named Quilltap instances
+  logs                          Tail or print an instance log file
+  migrations                    Inspect migration status (status / pending / run)
+  maintenance                   Run retention / cleanup sweeps (status / run)
+  file-verify                   Force-download cloud-evicted data files (iCloud, etc.)
   memory-diff <chatId>          Dump existing memories and dry-run re-extraction for a chat
+  completion <shell>            Generate a shell completion script (bash / zsh / fish)
 
 Options:
   -p, --port <number>     Port to listen on (default: 3000)
@@ -1103,7 +1108,7 @@ async function dbCommand(args) {
 // to the subcommand. Each subcommand parses these flags position-independently,
 // so they behave the same before or after the verb.
 const SUBCOMMANDS = new Set([
-  'db', 'themes', 'docs', 'memories', 'instances', 'memory-diff', 'completion', 'logs', 'migrations', 'maintenance',
+  'db', 'themes', 'docs', 'memories', 'instances', 'memory-diff', 'completion', 'logs', 'migrations', 'maintenance', 'file-verify',
 ]);
 // Global flags that consume the following token as their value.
 const GLOBAL_VALUE_FLAGS = new Set(['-p', '--port', '-d', '--data-dir', '-i', '--instance', '--passphrase']);
@@ -1124,6 +1129,16 @@ const subName = subIdx >= 0 ? cliArgs[subIdx] : '';
 // Everything except the subcommand token itself (leading global flags kept).
 const subArgs = subIdx >= 0 ? [...cliArgs.slice(0, subIdx), ...cliArgs.slice(subIdx + 1)] : [];
 
+// Subcommands load the SQLCipher binding directly and never reach main()'s
+// native-module heal, so self-heal the database ABI here first. Cheap no-op when
+// healthy; rebuilds (with a friendly notice, not an error) only on a real
+// Node-ABI mismatch — e.g. after the user upgrades Node under a cached install.
+// `file-verify` is excluded: it's a pure-fs recovery tool that never opens the
+// database, so it must work even when the native binding is broken.
+if (subName && subName !== 'file-verify') {
+  ensureDatabaseNativeModule();
+}
+
 if (subName === 'db') {
   dbCommand(subArgs);
 } else if (subName === 'themes') {
@@ -1177,6 +1192,12 @@ if (subName === 'db') {
     console.error(`Error: ${err.message}`);
     process.exit(1);
   });
+} else if (subName === 'file-verify') {
+  const { fileVerifyCommand } = require('../lib/file-verify-commands');
+  fileVerifyCommand(subArgs).catch(err => {
+    console.error(`Error: ${err.message}`);
+    process.exit(1);
+  });
 } else {
   main();
 }

package/lib/__tests__/completion-coverage.test.js

@@ -0,0 +1,61 @@
+/**
+ * Guard test: the shell-completion templates and the top-level `--help` must
+ * stay in sync with the real subcommand dispatch table in bin/quilltap.js.
+ *
+ * This is the check that was missing when the docs/completions drifted behind
+ * the CLI (e.g. the `maintenance` subcommand shipped without ever being added
+ * to any completion script or to `quilltap --help`). If you add a top-level
+ * subcommand to SUBCOMMANDS, this test fails until you also teach the three
+ * completion templates and printHelp() about it.
+ *
+ * @jest-environment node
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const BIN = path.join(__dirname, '..', '..', 'bin', 'quilltap.js');
+const COMPLETION_DIR = path.join(__dirname, '..', 'completion');
+
+function readBin() {
+  return fs.readFileSync(BIN, 'utf8');
+}
+
+/** Parse the authoritative `const SUBCOMMANDS = new Set([...])` literal. */
+function readSubcommands(src) {
+  const m = src.match(/const SUBCOMMANDS = new Set\(\[([\s\S]*?)\]\)/);
+  if (!m) throw new Error('Could not locate SUBCOMMANDS set in bin/quilltap.js');
+  return m[1]
+    .split(',')
+    .map((s) => s.trim().replace(/^['"]|['"]$/g, ''))
+    .filter(Boolean);
+}
+
+const SRC = readBin();
+const SUBCOMMANDS = readSubcommands(SRC);
+
+describe('CLI subcommand surface stays documented', () => {
+  it('parses a non-trivial subcommand set from bin/quilltap.js', () => {
+    expect(SUBCOMMANDS).toContain('db');
+    expect(SUBCOMMANDS).toContain('maintenance');
+    expect(SUBCOMMANDS.length).toBeGreaterThanOrEqual(10);
+  });
+
+  it.each(['bash', 'zsh', 'fish'])(
+    '%s completion template lists every top-level subcommand',
+    (shell) => {
+      const tpl = fs.readFileSync(path.join(COMPLETION_DIR, `${shell}.template`), 'utf8');
+      const missing = SUBCOMMANDS.filter((sub) => !tpl.includes(sub));
+      expect(missing).toEqual([]);
+    }
+  );
+
+  it('top-level --help lists every subcommand', () => {
+    const help = SRC.match(/function printHelp\(\) \{([\s\S]*?)\n\}/);
+    expect(help).toBeTruthy();
+    const missing = SUBCOMMANDS.filter((sub) => !help[1].includes(sub));
+    expect(missing).toEqual([]);
+  });
+});

package/lib/completion/bash.template

@@ -15,7 +15,7 @@ _quilltap_complete() {
   local global_opts="-d --data-dir -i --instance -p --port -o --open -v --version -h --help --update --passphrase"
 
   # Top-level subcommands
-  local top_cmds="db docs themes instances memories memory-diff logs migrations completion"
+  local top_cmds="db docs themes instances memories memory-diff logs migrations maintenance file-verify completion"
 
   # Get the subcommand (first non-option word after quilltap)
   local subcommand=""
@@ -126,7 +126,7 @@ _quilltap_complete() {
       fi
       ;;
     docs)
-      local docs_verbs="list show files ls dir tree read export scan write delete mkdir move copy status find grep reindex embed"
+      local docs_verbs="list show files ls dir tree read export scan write delete mkdir move copy link rmdir mvdir status find grep reindex embed"
       local docs_flags="--mount --instance --data-dir --passphrase --port --json --help \
         --force --rendered --links --folder --type --ext --limit --max --context --top --threshold \
         --ignore-case -l --wait -R --recursive --sort -r --reverse --depth --max-nodes --long --semantic"
@@ -227,6 +227,19 @@ _quilltap_complete() {
         COMPREPLY=($(compgen -W "$mig_flags" -- "$cur"))
       fi
       ;;
+    maintenance)
+      local maint_verbs="status run"
+      local maint_flags="--instance --data-dir --passphrase --json --help"
+      if [[ -z "$subverb" ]]; then
+        if [[ "$cur" == -* ]]; then
+          COMPREPLY=($(compgen -W "$maint_flags" -- "$cur"))
+        else
+          COMPREPLY=($(compgen -W "$maint_verbs" -- "$cur"))
+        fi
+      else
+        COMPREPLY=($(compgen -W "$maint_flags" -- "$cur"))
+      fi
+      ;;
     completion)
       if [[ "$cur" == -* ]]; then
         COMPREPLY=($(compgen -W "--help" -- "$cur"))

package/lib/completion/fish.template

@@ -15,7 +15,7 @@ function __quilltap_no_subcommand
   end
   for i in (seq 2 (count $cmd))
     switch $cmd[$i]
-      case db docs themes instances memories memory-diff logs migrations completion
+      case db docs themes instances memories memory-diff logs migrations maintenance file-verify completion
         return 1
     end
   end
@@ -27,7 +27,7 @@ function __quilltap_using_subcommand
   set -l cmd (commandline -opc)
   for i in (seq 2 (count $cmd))
     switch $cmd[$i]
-      case db docs themes instances memories memory-diff logs migrations completion
+      case db docs themes instances memories memory-diff logs migrations maintenance file-verify completion
         test "$cmd[$i]" = "$target"
         return $status
     end
@@ -57,6 +57,8 @@ complete -c quilltap -n '__quilltap_no_subcommand' -f -a 'memories' -d 'Search a
 complete -c quilltap -n '__quilltap_no_subcommand' -f -a 'memory-diff' -d 'Memory extraction dry-run'
 complete -c quilltap -n '__quilltap_no_subcommand' -f -a 'logs' -d 'Tail or print log files'
 complete -c quilltap -n '__quilltap_no_subcommand' -f -a 'migrations' -d 'Inspect migration status'
+complete -c quilltap -n '__quilltap_no_subcommand' -f -a 'maintenance' -d 'Run retention/cleanup sweeps'
+complete -c quilltap -n '__quilltap_no_subcommand' -f -a 'file-verify' -d 'Force-download cloud-evicted data files'
 complete -c quilltap -n '__quilltap_no_subcommand' -f -a 'completion' -d 'Generate shell completion'
 
 # Global options
@@ -140,6 +142,9 @@ complete -c quilltap -n '__quilltap_using_subcommand docs' -f -a 'delete' -d 'De
 complete -c quilltap -n '__quilltap_using_subcommand docs' -f -a 'mkdir' -d 'Create folder'
 complete -c quilltap -n '__quilltap_using_subcommand docs' -f -a 'move' -d 'Move file'
 complete -c quilltap -n '__quilltap_using_subcommand docs' -f -a 'copy' -d 'Copy file'
+complete -c quilltap -n '__quilltap_using_subcommand docs' -f -a 'link' -d 'Hard-link a file into another mount'
+complete -c quilltap -n '__quilltap_using_subcommand docs' -f -a 'rmdir' -d 'Remove a folder'
+complete -c quilltap -n '__quilltap_using_subcommand docs' -f -a 'mvdir' -d 'Rename or move a folder'
 
 # docs flags
 complete -c quilltap -n '__quilltap_using_subcommand docs' -l 'mount' -d 'Mount name or id' -x
@@ -268,6 +273,10 @@ complete -c quilltap -n '__quilltap_using_subcommand migrations' -f -a 'pending'
 complete -c quilltap -n '__quilltap_using_subcommand migrations' -f -a 'run' -d 'Run pending migrations'
 complete -c quilltap -n '__quilltap_using_subcommand migrations' -l 'dry-run' -d 'Dry run (required for run)'
 
+# ---------- maintenance verbs ----------
+complete -c quilltap -n '__quilltap_using_subcommand maintenance' -f -a 'status' -d 'Show dry-run retention counts'
+complete -c quilltap -n '__quilltap_using_subcommand maintenance' -f -a 'run' -d 'Run retention/cleanup sweeps (lock-gated)'
+
 # ---------- completion sub-args ----------
 complete -c quilltap -n '__quilltap_using_subcommand completion' -f -a 'bash' -d 'Bash completion'
 complete -c quilltap -n '__quilltap_using_subcommand completion' -f -a 'zsh' -d 'Zsh completion'

package/lib/completion/zsh.template

@@ -28,6 +28,8 @@ _quilltap() {
     'memory-diff:Dump existing memories and dry-run re-extraction'
     'logs:Tail or print an instance log file'
     'migrations:Inspect migration status'
+    'maintenance:Run retention/cleanup sweeps'
+    'file-verify:Force-download cloud-evicted data files'
     'completion:Generate shell completion scripts'
   )
 
@@ -76,6 +78,9 @@ _quilltap_subcommand() {
     migrations)
       _quilltap_migrations
       ;;
+    maintenance)
+      _quilltap_maintenance
+      ;;
     completion)
       _quilltap_completion
       ;;
@@ -163,6 +168,9 @@ _quilltap_docs() {
     'mkdir:Create folder'
     'move:Move file'
     'copy:Copy file'
+    'link:Hard-link a file into another mount'
+    'rmdir:Remove a folder'
+    'mvdir:Rename or move a folder'
   )
 
   docs_opts=(
@@ -395,6 +403,27 @@ _quilltap_migrations() {
   _arguments $mig_opts
 }
 
+_quilltap_maintenance() {
+  local -a subverbs maint_opts
+  subverbs=(
+    'status:Show dry-run retention counts'
+    'run:Run retention/cleanup sweeps (lock-gated)'
+  )
+
+  maint_opts=(
+    '(-i --instance)'{-i,--instance}'[Registered instance name]:instance:_quilltap_instance_names'
+    '(-d --data-dir)'{-d,--data-dir}'[Data directory]:directory:_directories'
+    '--passphrase[Database passphrase]:passphrase:'
+    '--json[JSON output]'
+    '(-h --help)'{-h,--help}'[Show help]'
+  )
+
+  if (( CURRENT == 2 )); then
+    _describe 'maintenance subcommand' subverbs
+  fi
+  _arguments $maint_opts
+}
+
 _quilltap_completion() {
   _values 'shell' bash zsh fish
 }

package/lib/file-verify-commands.js

@@ -0,0 +1,222 @@
+'use strict';
+
+/**
+ * `quilltap file-verify` — force-download an instance's cloud-evicted data files.
+ *
+ * An instance can live in a cloud-synced folder (iCloud Drive on macOS today;
+ * OneDrive / Google Drive File Stream on Windows later). Those providers EVICT
+ * idle files to dataless placeholders. If a database file is still dataless when
+ * SQLite/SQLCipher opens it, the read fails with "file is not a database" or
+ * returns partially-materialized garbage — which has wedged whole startups.
+ *
+ * The server does this automatically at boot (Phase -1, before the .dbkey is
+ * read). This command is the manual/diagnostic twin for the CLI, which opens the
+ * encrypted databases directly and benefits from the same guarantee. It needs no
+ * passphrase and never decrypts anything — it just reads the bytes to nowhere,
+ * which is what faults a dataless file in.
+ *
+ * Logic MIRRORS the TypeScript source of truth at
+ * `lib/startup/materialize-cloud-files.ts`. Keep them in sync.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { resolveDataDirAndPassphrase, printDefaultInstanceHint } = require('./db-helpers');
+
+const DEFAULT_STALL_MS = 30_000;
+const READ_CHUNK_BYTES = 8 * 1024 * 1024;
+
+// ---------- detection (platform seam) ----------
+
+// macOS dataless heuristic: a real file (size > 0) with no allocated blocks has
+// not been materialized locally (mirrors the SF_DATALESS flag). Zero-byte files
+// are never flagged. Other platforms fall through as a no-op for now.
+function isDatalessStat(stat) {
+  return stat.size > 0 && stat.blocks === 0;
+}
+
+function listTopLevelFiles(dataDir) {
+  let entries;
+  try {
+    entries = fs.readdirSync(dataDir, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+  const out = [];
+  for (const entry of entries) {
+    if (!entry.isFile()) continue; // skip directories (backups/) and symlinks
+    const full = path.join(dataDir, entry.name);
+    let stat;
+    try {
+      stat = fs.statSync(full);
+    } catch {
+      continue;
+    }
+    out.push({ name: entry.name, full, size: stat.size, dataless: isDatalessStat(stat) });
+  }
+  return out;
+}
+
+// ---------- streaming materialize with per-chunk stall guard ----------
+
+function streamMaterialize(filePath, stallMs) {
+  return new Promise((resolve, reject) => {
+    const stream = fs.createReadStream(filePath, { highWaterMark: READ_CHUNK_BYTES });
+    let timer;
+    const arm = () => {
+      clearTimeout(timer);
+      timer = setTimeout(() => {
+        stream.destroy(new Error(`stalled — no data for ${Math.round(stallMs / 1000)}s`));
+      }, stallMs);
+    };
+    arm();
+    stream.on('data', () => arm()); // discard chunk; the read faults the bytes in
+    stream.on('end', () => {
+      clearTimeout(timer);
+      resolve();
+    });
+    stream.on('error', (err) => {
+      clearTimeout(timer);
+      reject(err);
+    });
+  });
+}
+
+// ---------- argument parsing ----------
+
+function parseFlags(args) {
+  const flags = {
+    dataDir: '',
+    instance: '',
+    all: false,
+    json: false,
+    help: false,
+    stallMs: DEFAULT_STALL_MS,
+  };
+  let i = 0;
+  while (i < args.length) {
+    const a = args[i];
+    switch (a) {
+      case '-d': case '--data-dir': flags.dataDir = args[++i]; break;
+      case '-i': case '--instance': flags.instance = args[++i]; break;
+      case '--all': flags.all = true; break;
+      case '--json': flags.json = true; break;
+      case '--stall-ms': flags.stallMs = Number(args[++i]) || DEFAULT_STALL_MS; break;
+      case '-h': case '--help': flags.help = true; break;
+      default:
+        if (a.startsWith('-')) console.error(`unknown flag: ${a}`);
+        break;
+    }
+    i++;
+  }
+  return flags;
+}
+
+function printHelp() {
+  console.log(`Usage: quilltap file-verify [options]
+
+Force-download the instance's cloud-evicted (dataless) data files so the
+databases are fully local before anything opens them. Reads each placeholder to
+nowhere, which faults it in through the cloud provider (iCloud Drive, etc.).
+Safe to run repeatedly; a no-op when nothing is evicted. macOS only for now.
+
+Only the TOP-LEVEL files of the data directory are considered (the backups/
+subdirectory is left alone).
+
+Options:
+  -d, --data-dir <path>     Use a specific data directory (instance root)
+  -i, --instance <name>     Use a named instance
+  --all                     Read every top-level file, not just dataless ones
+  --stall-ms <ms>           Treat a download as stalled after this many ms with
+                            no bytes (per-chunk, not per-file; default ${DEFAULT_STALL_MS})
+  --json                    Output as JSON
+  -h, --help                Show this help message
+
+Examples:
+  quilltap file-verify --instance Ignite
+  quilltap file-verify --instance Friday --json
+  quilltap file-verify -d ~/iCloud/Quilltap/Ignite
+`);
+}
+
+// ---------- main entry point ----------
+
+async function fileVerifyCommand(args) {
+  const flags = parseFlags(args);
+  if (flags.help) {
+    printHelp();
+    return;
+  }
+
+  let resolved;
+  try {
+    resolved = resolveDataDirAndPassphrase({ dataDir: flags.dataDir, instance: flags.instance });
+  } catch (err) {
+    console.error(`Error: ${err.message}`);
+    process.exit(1);
+  }
+  printDefaultInstanceHint(resolved);
+  // resolved.dataDir already points at the instance's data/ directory.
+  const targetDir = resolved.dataDir;
+
+  const files = listTopLevelFiles(targetDir);
+  const targets = flags.all ? files : files.filter((f) => f.dataless);
+
+  const summary = {
+    dataDir: targetDir,
+    checked: files.length,
+    targeted: targets.length,
+    downloaded: 0,
+    failed: 0,
+    failedNames: [],
+  };
+
+  if (targets.length === 0) {
+    if (flags.json) {
+      console.log(JSON.stringify(summary, null, 2));
+    } else {
+      console.log(
+        `Nothing to fetch — all ${files.length} top-level file(s) in ${targetDir} are already ashore.`,
+      );
+    }
+    return;
+  }
+
+  if (!flags.json) {
+    console.log(
+      `Fetching ${targets.length} file(s) down from the cloud (of ${files.length} top-level):`,
+    );
+  }
+
+  for (let i = 0; i < targets.length; i++) {
+    const file = targets[i];
+    const mb = (file.size / (1024 * 1024)).toFixed(1);
+    if (!flags.json) {
+      process.stdout.write(`  Coaxing «${file.name}» (${mb} MB) down — ${i + 1}/${targets.length}… `);
+    }
+    try {
+      await streamMaterialize(file.full, flags.stallMs);
+      summary.downloaded++;
+      if (!flags.json) console.log('secured.');
+    } catch (err) {
+      summary.failed++;
+      summary.failedNames.push(file.name);
+      if (!flags.json) console.log(`failed (${err.message}).`);
+    }
+  }
+
+  if (flags.json) {
+    console.log(JSON.stringify(summary, null, 2));
+  } else {
+    console.log(
+      `Done — ${summary.downloaded} secured, ${summary.failed} failed.` +
+        (summary.failed ? ` Failed: ${summary.failedNames.join(', ')}` : ''),
+    );
+  }
+
+  if (summary.failed > 0) process.exit(1);
+}
+
+module.exports = {
+  fileVerifyCommand,
+};

package/lib/native-modules.js

@@ -21,6 +21,84 @@ function resolveModuleDir(moduleName) {
   }
 }
 
+// Locate the SQLCipher binding (better-sqlite3-multiple-ciphers, aliased as
+// better-sqlite3). Returns the absolute path to better_sqlite3.node, or null.
+function betterSqlite3BindingPath() {
+  const modDir = resolveModuleDir('better-sqlite3-multiple-ciphers')
+              || resolveModuleDir('better-sqlite3');
+  if (!modDir) return null;
+  return path.join(modDir, 'build', 'Release', 'better_sqlite3.node');
+}
+
+// Read the Node ABI (NODE_MODULE_VERSION) a node-gyp/NAN addon was compiled
+// against, by scanning for its `node_register_module_v<ABI>` export — a few-KB
+// byte read, no dlopen, no rebuild. Returns the ABI as a string, or null when
+// the symbol is absent (e.g. an N-API build, which is ABI-stable) or unreadable.
+function readCompiledAbi(bindingPath) {
+  try {
+    const buf = require('fs').readFileSync(bindingPath);
+    const m = /node_register_module_v(\d+)/.exec(buf.toString('latin1'));
+    return m ? m[1] : null;
+  } catch {
+    return null;
+  }
+}
+
+// True when the SQLCipher binding is missing or was built for a different Node
+// ABI than the one we're running. Reads the compiled-for ABI straight from the
+// binary; only falls back to an actual load probe if the symbol can't be read.
+function betterSqlite3NeedsRebuild() {
+  const bindingPath = betterSqlite3BindingPath();
+  if (!bindingPath) return true; // unresolvable → needs (re)build
+  if (!require('fs').existsSync(bindingPath)) return true;
+  const compiledAbi = readCompiledAbi(bindingPath);
+  if (compiledAbi) return compiledAbi !== process.versions.modules;
+  // Symbol unreadable — fall back to the authoritative dlopen probe.
+  try {
+    require(bindingPath);
+    return false;
+  } catch (err) {
+    return !!(err.message && err.message.includes('NODE_MODULE_VERSION'));
+  }
+}
+
+// Rebuild the named native modules against the current Node ABI. Prints a
+// friendly notice rather than throwing; returns true on success, false on
+// failure. Backfills node-pty's spawn-helper afterward.
+function rebuildModules(moduleNames) {
+  console.log(`  Rebuilding native modules for Node.js ${process.version}...`);
+  try {
+    execSync(`npm rebuild ${moduleNames.join(' ')}`, {
+      cwd: PACKAGE_DIR,
+      stdio: 'inherit',
+    });
+    console.log('  Done.');
+    console.log('');
+    reconcileNodePtySpawnHelper();
+    return true;
+  } catch (err) {
+    console.error('');
+    console.error(`  Warning: Failed to rebuild native modules: ${err.message}`);
+    console.error('  Try running: npm rebuild --prefix ' + PACKAGE_DIR);
+    console.error('');
+    return false;
+  }
+}
+
+// Fast pre-flight for the ONE ABI-fragile native module every DB path needs:
+// better-sqlite3-multiple-ciphers (SQLCipher). sharp and node-pty are N-API and
+// ABI-stable, so they can't hit this failure. Detects an ABI mismatch from the
+// binary itself and rebuilds before anything tries to load it, so a Node upgrade
+// self-heals instead of throwing. Cheap no-op when already healthy. Never throws.
+function ensureDatabaseNativeModule() {
+  try {
+    if (!betterSqlite3NeedsRebuild()) return true;
+  } catch {
+    return true; // detection hiccup — let the real load be the source of truth
+  }
+  return rebuildModules(['better-sqlite3-multiple-ciphers']);
+}
+
 // node-pty needs a `spawn-helper` executable beside the pty.node it loads, or
 // pty.spawn() fails with `posix_spawnp failed`. An ABI rebuild lands a fresh
 // build/Release/pty.node (which node-pty's loader prefers over prebuilds/) but
@@ -74,19 +152,9 @@ function ensureNativeModules() {
   // Check better-sqlite3-multiple-ciphers (provides SQLCipher encryption support).
   // The main app depends on this via an npm alias as 'better-sqlite3', so we must
   // ensure the SQLCipher-capable version is available and link it as 'better-sqlite3'.
-  // We must load the native binding directly to detect NODE_MODULE_VERSION mismatches.
-  try {
-    const modDir = resolveModuleDir('better-sqlite3-multiple-ciphers')
-                || resolveModuleDir('better-sqlite3');
-    if (!modDir) throw Object.assign(new Error('not found'), { code: 'MODULE_NOT_FOUND' });
-    const bindingsPath = path.join(modDir, 'build', 'Release', 'better_sqlite3.node');
-    require(bindingsPath);
-  } catch (err) {
-    if (err.message && err.message.includes('NODE_MODULE_VERSION')) {
-      needsRebuild.push('better-sqlite3-multiple-ciphers');
-    } else if (err.code === 'MODULE_NOT_FOUND') {
-      needsRebuild.push('better-sqlite3-multiple-ciphers');
-    }
+  // This is the only ABI-fragile binding — detected straight from the binary.
+  if (betterSqlite3NeedsRebuild()) {
+    needsRebuild.push('better-sqlite3-multiple-ciphers');
   }
 
   // Check sharp: loads its native binding eagerly on require.
@@ -120,27 +188,18 @@ function ensureNativeModules() {
     return true;
   }
 
-  console.log(`  Rebuilding native modules for Node.js ${process.version}...`);
-
-  try {
-    execSync(`npm rebuild ${needsRebuild.join(' ')}`, {
-      cwd: PACKAGE_DIR,
-      stdio: 'inherit',
-    });
-    console.log('  Done.');
-    console.log('');
-    reconcileNodePtySpawnHelper();
-    return true;
-  } catch (err) {
-    console.error('');
-    console.error(`  Warning: Failed to rebuild native modules: ${err.message}`);
-    console.error('  Try running: npm rebuild --prefix ' + PACKAGE_DIR);
-    console.error('');
-    return false;
-  }
+  return rebuildModules(needsRebuild);
 }
 
-module.exports = { resolveModuleDir, ensureNativeModules, reconcileNodePtySpawnHelper, PACKAGE_DIR };
+module.exports = {
+  resolveModuleDir,
+  readCompiledAbi,
+  betterSqlite3NeedsRebuild,
+  ensureDatabaseNativeModule,
+  ensureNativeModules,
+  reconcileNodePtySpawnHelper,
+  PACKAGE_DIR,
+};
 
 // Allow this file to be invoked directly as a postinstall script:
 //   node lib/native-modules.js

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "quilltap",
-  "version": "4.7.0-dev.101",
+  "version": "4.7.0-dev.129",
   "description": "Self-hosted AI workspace for writers, worldbuilders, and roleplayers. Run with npx quilltap.",
   "author": {
     "name": "Charles Sebold",
@@ -37,11 +37,11 @@
   ],
   "dependencies": {
     "@napi-rs/canvas": "^0.1.100",
-    "better-sqlite3-multiple-ciphers": "^12.10.0",
+    "better-sqlite3-multiple-ciphers": "^12.11.1",
     "node-pty": "^1.1.0",
     "sharp": "^0.34.5",
     "tar": "^7.5.16",
-    "yauzl": "^3.3.2"
+    "yauzl": "^3.4.0"
   },
   "engines": {
     "node": ">=24.0.0"