create-walle 0.9.9 → 0.9.11

package/README.md

@@ -23,7 +23,7 @@ An always-on AI agent that learns from your Slack, email, calendar, and coding s
 - **Second Brain** — Automatically ingests your digital life into a searchable memory store with full-text search, knowledge extraction, and pattern detection
 - **Proactive Intelligence** — Surfaces time-sensitive items, suggests actions, and delivers morning briefings and weekly reflections without being asked
 - **Chat with Tools** — Talk to Wall-E in the browser — it can search your memories, look up people, run skills, and call external tools via MCP (Slack, Glean, etc.)
-- **17 Bundled Skills** — Morning briefing, weekly reflection, proactive alerts, Slack monitoring, email sync, calendar integration, coding agent, model evaluation, and more
+- **19 Bundled Skills** — Morning briefing, weekly reflection, proactive alerts, Slack monitoring, email sync, calendar integration, coding agent, model training, model pricing sync, and more
 - **Multi-Model** — Works with Claude, GPT, Gemini, and local models via Ollama with smart routing
 - **Skill Management GUI** — Search, filter, create, edit, and monitor skills from the browser with rich cards, config forms, execution history, export/import, and pre-flight validation
 - **Multi-Device** — Share your brain across machines via Dropbox or iCloud

package/bin/create-walle.js

@@ -144,12 +144,14 @@ function install(targetDir) {
   console.log(`  Installing dependencies...\n`);
   npmInstall(targetDir);
 
+  compileHotkeyDaemon(targetDir);
+
   // .env
   const envLines = [
     `# Wall-E configuration — generated ${new Date().toISOString().split('T')[0]}`,
     `# Finish setup at http://localhost:${port}/setup.html`,
     '',
-    `WALLE_OWNER_NAME=${ownerName}`,
+    `WALLE_OWNER_NAME="${ownerName.replace(/"/g, '\\"')}"`,
     '# ANTHROPIC_API_KEY=',
     '',
     '# AI Provider: anthropic, openai, google, ollama',
@@ -247,6 +249,8 @@ function update() {
   console.log(`  Installing dependencies...\n`);
   npmInstall(dir);
 
+  compileHotkeyDaemon(dir);
+
   // 7. Start again
   console.log(`\n  Starting Wall-E...`);
   startForegroundOrService(dir, port);
@@ -331,9 +335,8 @@ function stopQuiet(dir, port) {
   while (Date.now() < deadline) {
     try {
       execFileSync('curl', ['-s', '--max-time', '1', `http://localhost:${port}/api/services/status`], { encoding: 'utf8', timeout: 2000 });
-      // Still running — busy-wait briefly
-      const waitUntil = Date.now() + 500;
-      while (Date.now() < waitUntil) { /* spin */ }
+      // Still running — sleep briefly (avoid CPU spin)
+      try { execFileSync('sleep', ['0.5'], { timeout: 2000 }); } catch {}
     } catch {
       break; // Port is free
     }
@@ -370,15 +373,18 @@ function installService(walleDir, port) {
     fs.mkdirSync(plistDir, { recursive: true });
     const plistPath = path.join(plistDir, `${LABEL}.plist`);
 
-    let envDict = `    <key>PATH</key>\n    <string>/usr/local/bin:/opt/homebrew/bin:/usr/bin:/bin</string>\n`;
-    envDict += `    <key>HOME</key>\n    <string>${process.env.HOME}</string>\n`;
+    const xmlEsc = (s) => String(s).replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+    const nodeBinDir = path.dirname(nodePath);
+    let envDict = `    <key>PATH</key>\n    <string>${xmlEsc(nodeBinDir)}:/usr/local/bin:/opt/homebrew/bin:/usr/bin:/bin</string>\n`;
+    envDict += `    <key>HOME</key>\n    <string>${xmlEsc(process.env.HOME)}</string>\n`;
     envDict += `    <key>CTM_PORT</key>\n    <string>${port}</string>\n`;
+    envDict += `    <key>CTM_MANAGED_BY_LAUNCHD</key>\n    <string>1</string>\n`;
     try {
       const envFile = fs.readFileSync(path.join(walleDir, '.env'), 'utf8');
       for (const line of envFile.split('\n')) {
         const m = line.match(/^\s*([^#=\s]+)\s*=\s*(.+?)\s*$/);
         if (m && m[1] !== 'CTM_PORT' && m[1] !== 'PATH' && m[1] !== 'HOME') {
-          envDict += `    <key>${m[1]}</key>\n    <string>${m[2]}</string>\n`;
+          envDict += `    <key>${xmlEsc(m[1])}</key>\n    <string>${xmlEsc(m[2])}</string>\n`;
         }
       }
     } catch {}
@@ -402,11 +408,16 @@ ${envDict}  </dict>
   <key>RunAtLoad</key>
   <true/>
   <key>KeepAlive</key>
-  <true/>
+  <dict>
+    <key>SuccessfulExit</key>
+    <false/>
+  </dict>
+  <key>ThrottleInterval</key>
+  <integer>5</integer>
   <key>StandardOutPath</key>
-  <string>${logDir}/walle.log</string>
+  <string>${logDir}/ctm.log</string>
   <key>StandardErrorPath</key>
-  <string>${logDir}/walle.err</string>
+  <string>${logDir}/ctm.err</string>
 </dict>
 </plist>`;
 
@@ -414,10 +425,34 @@ ${envDict}  </dict>
     try { execFileSync('launchctl', ['unload', plistPath], { stdio: 'ignore' }); } catch {}
     execFileSync('launchctl', ['load', plistPath]);
   } else {
-    const child = spawn(process.execPath, ['claude-task-manager/server.js'], {
+    // Linux/other: spawn with a restart-on-crash wrapper shell script
+    const watchdogScript = path.join(walleDir, 'bin', 'watchdog.sh');
+    const watchdogContent = `#!/bin/bash
+# Auto-restart CTM on crash. Clean exit (code 0) stops the watchdog.
+CRASHES=0
+while true; do
+  "${process.execPath}" claude-task-manager/server.js >> "${logDir}/ctm.log" 2>> "${logDir}/ctm.err"
+  EXIT_CODE=$?
+  if [ $EXIT_CODE -eq 0 ]; then
+    echo "[watchdog] Clean exit (code 0), stopping." >> "${logDir}/ctm.log"
+    break
+  fi
+  CRASHES=$((CRASHES + 1))
+  echo "[watchdog] CTM exited with code $EXIT_CODE (crash #$CRASHES), restarting in 5s..." >> "${logDir}/ctm.log"
+  if [ $CRASHES -ge 5 ]; then
+    echo "[watchdog] Too many crashes ($CRASHES), giving up." >> "${logDir}/ctm.log"
+    break
+  fi
+  sleep 5
+done
+`;
+    fs.mkdirSync(path.join(walleDir, 'bin'), { recursive: true });
+    fs.writeFileSync(watchdogScript, watchdogContent, { mode: 0o755 });
+
+    const child = spawn('bash', [watchdogScript], {
       cwd: walleDir,
       detached: true,
-      stdio: ['ignore', fs.openSync(path.join(logDir, 'walle.log'), 'a'), fs.openSync(path.join(logDir, 'walle.err'), 'a')],
+      stdio: 'ignore',
       env: { ...process.env, CTM_PORT: port },
     });
     child.unref();
@@ -505,6 +540,22 @@ function detectTimezone() {
   return 'UTC';
 }
 
+function compileHotkeyDaemon(walleDir) {
+  if (process.platform !== 'darwin') return; // macOS only
+  const swiftSource = path.join(walleDir, 'claude-task-manager', 'bin', 'ctm-hotkey.swift');
+  if (!fs.existsSync(swiftSource)) return;
+  const binary = path.join(process.env.HOME, '.local', 'bin', 'ctm-hotkey');
+  try {
+    fs.mkdirSync(path.dirname(binary), { recursive: true });
+    execFileSync('swiftc', ['-O', '-o', binary, swiftSource, '-framework', 'Cocoa'], { timeout: 120000, stdio: 'pipe' });
+    fs.chmodSync(binary, 0o755);
+    console.log(`  ${GREEN}Compiled hotkey daemon${RESET} ${DIM}(${binary})${RESET}`);
+  } catch {
+    // swiftc not available or compilation failed — non-fatal
+    console.log(`  ${DIM}Skipped hotkey daemon (Swift compiler not available)${RESET}`);
+  }
+}
+
 function copyRecursive(src, dest) {
   const stat = fs.statSync(src);
   if (stat.isDirectory()) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-walle",
-  "version": "0.9.9",
+  "version": "0.9.11",
   "description": "CTM + Wall-E \u2014 AI coding dashboard and personal digital twin agent. Multi-agent terminal for Claude Code, Codex, Gemini & Aider, plus prompt editor, task queue, and an agent that learns from Slack, email & calendar.",
   "bin": {
     "create-walle": "bin/create-walle.js"

package/template/CLAUDE.md

@@ -24,6 +24,18 @@ When developing CTM or Wall-E code:
 4. Test ONLY against your dev port, never 3456
 5. Only restart primary when the user explicitly asks — and ask for confirmation first
 
+## Testing
+
+Both projects use Node.js built-in test runner with `--test-force-exit` to prevent hangs:
+- **Wall-E**: `cd wall-e && npm test`
+- **CTM**: `cd claude-task-manager && npm test`
+
+When writing new tests, follow these rules to avoid handle leaks and cross-test contamination:
+- **Never set `process.env` at module top level** — set in `before()`, restore in `after()`
+- **Close every DB connection you open** — store `readDb` handles in module scope, close in `after()`/teardown
+- **Call `brain.closeDb()` before `brain.initDb()`** in tests that reinitialize the brain singleton
+- **Don't change `journal_mode`** on readonly connections (causes SQLITE_BUSY against WAL dbs)
+
 ## Publishing to npm (create-walle)
 
 When publishing with `/publish`:
@@ -32,3 +44,10 @@ When publishing with `/publish`:
 3. Bump version in both `create-walle/package.json` AND root `package.json`
 4. Run `bash build.sh` and verify file count
 5. Ask for confirmation before `npm publish`
+
+## Architecture reference
+
+For Wall-E architecture (loops, brain DB, scheduler, skills, channels, anti-patterns):
+read `wall-e/docs/architecture.md` before making non-trivial changes. The
+"Non-goals" section is a guardrail — coordinate via data, not via
+manager-of-managers.

package/template/bin/dev.sh

@@ -3,50 +3,64 @@
 # Primary instance stays untouched. Ctrl+C to stop.
 #
 # Usage:
-#   bash bin/dev.sh              # Start dev instance (snapshot DBs on first run)
-#   bash bin/dev.sh --refresh    # Re-copy production DBs before starting
-#   bash bin/dev.sh --fresh      # Start with empty DBs
+#   bash bin/dev.sh              # Start dev instance with fresh empty DBs
+#   bash bin/dev.sh --refresh    # Explicitly copy production DBs before starting
+#   bash bin/dev.sh --fresh      # Reset to empty DBs before starting
 
 set -e
 ROOT="$(cd "$(dirname "$0")/.." && pwd)"
 DEV_DIR="${WALLE_DEV_DIR:-/tmp/walle-dev}"
 DEV_CTM_PORT="${DEV_CTM_PORT:-4000}"
 DEV_WALLE_PORT="${DEV_WALLE_PORT:-4001}"
+DEV_OAUTH_PROXY_PORT="${DEV_OAUTH_PROXY_PORT:-$((DEV_CTM_PORT + 2))}"
 
-# Source production .env to find DB paths
-PROD_CTM_DIR="$HOME/.walle/data"
-PROD_WALLE_DIR="$HOME/.walle/data"
+# Source production .env to find DB paths. DEV_SOURCE_* lets worktrees without
+# their own .env refresh from the primary repo's configured data directory.
+PROD_CTM_DIR="${DEV_SOURCE_CTM_DATA_DIR:-$HOME/.walle/data}"
+PROD_WALLE_DIR="${DEV_SOURCE_WALL_E_DATA_DIR:-$HOME/.walle/data}"
 if [[ -f "$ROOT/.env" ]]; then
   eval "$(grep -E '^(CTM_DATA_DIR|WALL_E_DATA_DIR)=' "$ROOT/.env" 2>/dev/null)" || true
-  [[ -n "$CTM_DATA_DIR" ]] && PROD_CTM_DIR="$CTM_DATA_DIR"
-  [[ -n "$WALL_E_DATA_DIR" ]] && PROD_WALLE_DIR="$WALL_E_DATA_DIR"
+  [[ -z "$DEV_SOURCE_CTM_DATA_DIR" && -n "$CTM_DATA_DIR" ]] && PROD_CTM_DIR="$CTM_DATA_DIR"
+  [[ -z "$DEV_SOURCE_WALL_E_DATA_DIR" && -n "$WALL_E_DATA_DIR" ]] && PROD_WALLE_DIR="$WALL_E_DATA_DIR"
 fi
 
 mkdir -p "$DEV_DIR"
 
+cleanup_processes() {
+  pkill -f "ctm-dev-$DEV_CTM_PORT" 2>/dev/null || true
+  pkill -f "walle-dev-$DEV_CTM_PORT" 2>/dev/null || true
+  lsof -ti ":$DEV_CTM_PORT" -sTCP:LISTEN 2>/dev/null | xargs kill 2>/dev/null || true
+  lsof -ti ":$DEV_WALLE_PORT" -sTCP:LISTEN 2>/dev/null | xargs kill 2>/dev/null || true
+  lsof -ti ":$DEV_OAUTH_PROXY_PORT" -sTCP:LISTEN 2>/dev/null | xargs kill 2>/dev/null || true
+}
+
+cleanup_dev() {
+  cleanup_processes
+  # Remove dev data directory to prevent /tmp bloat (each copy is ~2-6 GB)
+  if [[ "$DEV_DIR" == /tmp/walle-* && -d "$DEV_DIR" ]]; then
+    echo "[dev] Cleaning up $DEV_DIR ..."
+    rm -rf "$DEV_DIR"
+  fi
+}
+
+cleanup_processes
+
 # Handle flags
-if [[ "$1" == "--fresh" ]]; then
+if [[ "$1" == "--fresh" || -z "$1" ]]; then
   echo "[dev] Starting with fresh (empty) databases"
   rm -f "$DEV_DIR"/*.db "$DEV_DIR"/*.db-wal "$DEV_DIR"/*.db-shm
-elif [[ "$1" == "--refresh" || ! -f "$DEV_DIR/task-manager.db" ]]; then
-  echo "[dev] Copying production databases to $DEV_DIR ..."
-  # Copy CTM DB
-  if [[ -f "$PROD_CTM_DIR/task-manager.db" ]]; then
-    cp "$PROD_CTM_DIR/task-manager.db" "$DEV_DIR/task-manager.db"
-    echo "  CTM: $PROD_CTM_DIR/task-manager.db → $DEV_DIR/"
-  fi
-  # Copy Wall-E brain
-  if [[ -f "$PROD_WALLE_DIR/wall-e-brain.db" ]]; then
-    cp "$PROD_WALLE_DIR/wall-e-brain.db" "$DEV_DIR/wall-e-brain.db"
-    echo "  Brain: $PROD_WALLE_DIR/wall-e-brain.db → $DEV_DIR/"
-  fi
-  # Clean WAL files (they're specific to the source process)
+elif [[ "$1" == "--refresh" ]]; then
+  echo "[dev] Snapshotting production databases to $DEV_DIR ..."
+  node "$ROOT/bin/sqlite-snapshot.js" "$PROD_CTM_DIR/task-manager.db" "$DEV_DIR/task-manager.db" "CTM"
+  node "$ROOT/bin/sqlite-snapshot.js" "$PROD_WALLE_DIR/wall-e-brain.db" "$DEV_DIR/wall-e-brain.db" "Brain"
+  # Ensure the dev instance owns its WAL files from first open.
   rm -f "$DEV_DIR"/*.db-wal "$DEV_DIR"/*.db-shm
 fi
 
 echo ""
 echo "  Dev CTM:    http://localhost:$DEV_CTM_PORT"
 echo "  Dev Wall-E: port $DEV_WALLE_PORT"
+echo "  Dev OAuth:  port $DEV_OAUTH_PROXY_PORT"
 echo "  Dev data:   $DEV_DIR"
 echo "  Source:     $ROOT"
 echo ""
@@ -59,14 +73,23 @@ export WALL_E_PORT="$DEV_WALLE_PORT"
 export CTM_DATA_DIR="$DEV_DIR"
 export WALL_E_DATA_DIR="$DEV_DIR"
 export CTM_HOST="127.0.0.1"
+export CTM_INSTANCE_TAG="dev-$DEV_CTM_PORT"
+export OAUTH_PROXY_PORT="$DEV_OAUTH_PROXY_PORT"
 
 # Source the rest of .env (API keys, owner name, etc.)
 if [[ -f "$ROOT/.env" ]]; then
   set -a
-  source <(grep -v '^#' "$ROOT/.env" | grep -vE '^(CTM_PORT|WALL_E_PORT|CTM_DATA_DIR|WALL_E_DATA_DIR|CTM_HOST)=' | grep '=')
+  source <(grep -v '^#' "$ROOT/.env" | grep -vE '^(CTM_PORT|WALL_E_PORT|CTM_DATA_DIR|WALL_E_DATA_DIR|CTM_HOST|CTM_INSTANCE_TAG|OAUTH_PROXY_PORT)=' | grep '=')
   set +a
 fi
 
+trap cleanup_dev EXIT
+
+# Clean up stale dev/e2e data dirs older than 24h (from crashed sessions)
+find /tmp -maxdepth 1 -name "walle-dev-*" -type d -mmin +1440 -exec rm -rf {} + 2>/dev/null || true
+find /tmp -maxdepth 1 -name "walle-e2e-*" -type d -mmin +1440 -exec rm -rf {} + 2>/dev/null || true
+find /tmp -maxdepth 1 -name "ctm-dev-*" -type d -mmin +1440 -exec rm -rf {} + 2>/dev/null || true
+
 # Run in foreground so Ctrl+C stops it cleanly
 cd "$ROOT"
 exec node claude-task-manager/server.js

package/template/bin/install-service.sh

@@ -1,5 +1,6 @@
 #!/bin/bash
-# Install Wall-E as a macOS Launch Agent so it starts automatically on login.
+# Install CTM + Wall-E as a macOS Launch Agent so it starts automatically on login
+# and auto-restarts on crash (but NOT on clean exit).
 # Usage: bash bin/install-service.sh [--uninstall]
 
 set -e
@@ -7,22 +8,40 @@ SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
 ROOT="$(dirname "$SCRIPT_DIR")"
 LABEL="com.walle.server"
 PLIST="$HOME/Library/LaunchAgents/$LABEL.plist"
-PORT="${CTM_PORT:-4567}"
+PORT="${CTM_PORT:-3456}"
 
 if [[ "$1" == "--uninstall" ]]; then
-  launchctl unload "$PLIST" 2>/dev/null || true
+  launchctl bootout "gui/$(id -u)/$LABEL" 2>/dev/null || \
+    launchctl unload "$PLIST" 2>/dev/null || true
   rm -f "$PLIST"
-  echo "Wall-E service uninstalled."
+  echo "CTM service uninstalled."
   exit 0
 fi
 
-# Source .env to get the port
+# Source .env for port and data dir overrides
+ENV_VARS=""
 if [[ -f "$ROOT/.env" ]]; then
-  export $(grep -v '^#' "$ROOT/.env" | grep '=' | xargs)
-  PORT="${CTM_PORT:-4567}"
+  while IFS='' read -r line || [[ -n "$line" ]]; do
+    [[ -z "$line" || "$line" == \#* ]] && continue
+    key="${line%%=*}"
+    value="${line#*=}"
+    key=$(echo "$key" | xargs)
+    value=$(echo "$value" | xargs | sed 's/^["'"'"']//;s/["'"'"']$//')
+    [[ -z "$key" ]] && continue
+    case "$key" in
+      CTM_PORT) PORT="$value" ;;
+    esac
+    # XML-escape for plist safety
+    esc_key=$(echo "$key" | sed 's/&/\&amp;/g;s/</\&lt;/g;s/>/\&gt;/g')
+    esc_val=$(echo "$value" | sed 's/&/\&amp;/g;s/</\&lt;/g;s/>/\&gt;/g')
+    ENV_VARS="$ENV_VARS
+    <key>$esc_key</key>
+    <string>$esc_val</string>"
+  done < "$ROOT/.env"
 fi
 
 NODE=$(which node)
+NODE_BIN_DIR=$(dirname "$NODE")
 LOG_DIR="$HOME/.walle/logs"
 mkdir -p "$LOG_DIR"
 
@@ -43,30 +62,45 @@ cat > "$PLIST" << EOF
   <key>EnvironmentVariables</key>
   <dict>
     <key>PATH</key>
-    <string>/usr/local/bin:/opt/homebrew/bin:/usr/bin:/bin</string>
+    <string>$NODE_BIN_DIR:/usr/local/bin:/opt/homebrew/bin:/usr/bin:/bin</string>
     <key>HOME</key>
     <string>$HOME</string>
     <key>CTM_PORT</key>
     <string>$PORT</string>
+    <key>CTM_MANAGED_BY_LAUNCHD</key>
+    <string>1</string>$ENV_VARS
   </dict>
   <key>RunAtLoad</key>
   <true/>
   <key>KeepAlive</key>
-  <true/>
+  <dict>
+    <key>SuccessfulExit</key>
+    <false/>
+  </dict>
+  <key>ThrottleInterval</key>
+  <integer>5</integer>
   <key>StandardOutPath</key>
-  <string>$LOG_DIR/walle.log</string>
+  <string>$LOG_DIR/ctm.log</string>
   <key>StandardErrorPath</key>
-  <string>$LOG_DIR/walle.err</string>
+  <string>$LOG_DIR/ctm.err</string>
 </dict>
 </plist>
 EOF
 
-launchctl unload "$PLIST" 2>/dev/null || true
-launchctl load "$PLIST"
+# Load the service (unload first if previously loaded, wait for clean exit)
+launchctl bootout "gui/$(id -u)/$LABEL" 2>/dev/null || \
+  launchctl unload "$PLIST" 2>/dev/null || true
+sleep 1  # Let old process release port before bootstrapping new one
+launchctl bootstrap "gui/$(id -u)" "$PLIST" 2>/dev/null || \
+  launchctl load "$PLIST"
 
-echo "Wall-E installed as a macOS service."
+echo "CTM installed as a macOS Launch Agent."
 echo ""
-echo "  Status:    launchctl list | grep walle"
-echo "  Logs:      tail -f ~/.walle/logs/walle.log"
+echo "  Status:    launchctl list $LABEL"
+echo "  Logs:      tail -f ~/.walle/logs/ctm.log"
+echo "  Errors:    tail -f ~/.walle/logs/ctm.err"
 echo "  Dashboard: http://localhost:$PORT"
 echo "  Uninstall: bash bin/install-service.sh --uninstall"
+echo ""
+echo "  Auto-restarts on crash. Clean exit (SIGTERM/SIGINT) stops the service."
+echo "  To manually stop: launchctl kill SIGTERM gui/$(id -u)/$LABEL"

package/template/bin/sqlite-snapshot.js

@@ -0,0 +1,148 @@
+#!/usr/bin/env node
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { spawn } = require('child_process');
+
+function loadBetterSqlite() {
+  try { return require('../claude-task-manager/node_modules/better-sqlite3'); } catch {}
+  try { return require('../wall-e/node_modules/better-sqlite3'); } catch {}
+  return require('better-sqlite3');
+}
+
+const Database = loadBetterSqlite();
+
+function removeFile(file) {
+  try { fs.rmSync(file, { force: true }); } catch {}
+}
+
+function removeDbFamily(file) {
+  removeFile(file);
+  removeFile(file + '-wal');
+  removeFile(file + '-shm');
+}
+
+function loadOptionalVec(db) {
+  try {
+    const sqliteVec = require('../wall-e/node_modules/sqlite-vec');
+    sqliteVec.load(db);
+  } catch {}
+}
+
+function logDebug(label, message) {
+  if (process.env.SQLITE_SNAPSHOT_DEBUG === '1') {
+    console.warn(`  ${label}: ${message}`);
+  }
+}
+
+function quickCheck(dbPath) {
+  let db;
+  try {
+    db = new Database(dbPath, { readonly: true, fileMustExist: true });
+    loadOptionalVec(db);
+    const rows = db.pragma('quick_check');
+    const value = rows?.[0] ? Object.values(rows[0])[0] : '';
+    return value === 'ok' ? { ok: true } : { ok: false, error: String(value || 'quick_check failed') };
+  } catch (err) {
+    return { ok: false, error: err.message };
+  } finally {
+    try { if (db) db.close(); } catch {}
+  }
+}
+
+async function sqliteBackup(src, dest) {
+  const db = new Database(src, { readonly: true, fileMustExist: true });
+  try {
+    loadOptionalVec(db);
+    await db.backup(dest);
+  } finally {
+    db.close();
+  }
+}
+
+function pipeRecover(input, output) {
+  return new Promise((resolve, reject) => {
+    removeFile(output);
+    const sqlite = process.env.SQLITE3_BIN || '/usr/bin/sqlite3';
+    const recover = spawn(sqlite, [input, '.recover'], { stdio: ['ignore', 'pipe', 'inherit'] });
+    const apply = spawn(sqlite, [output], { stdio: ['pipe', 'ignore', 'inherit'] });
+    let recoverCode = null;
+    let applyCode = null;
+    let settled = false;
+    const fail = (err) => {
+      if (settled) return;
+      settled = true;
+      reject(err);
+    };
+    const maybeDone = () => {
+      if (settled || recoverCode === null || applyCode === null) return;
+      if (recoverCode !== 0) return fail(new Error(`sqlite3 .recover exited ${recoverCode}`));
+      if (applyCode !== 0) return fail(new Error(`sqlite3 restore exited ${applyCode}`));
+      settled = true;
+      resolve();
+    };
+    recover.stdout.pipe(apply.stdin);
+    recover.on('error', fail);
+    apply.on('error', fail);
+    recover.on('close', (code) => {
+      recoverCode = code;
+      if (code !== 0) try { apply.stdin.destroy(); } catch {}
+      maybeDone();
+    });
+    apply.on('close', (code) => {
+      applyCode = code;
+      maybeDone();
+    });
+  });
+}
+
+async function main() {
+  const [src, dest, label = 'SQLite'] = process.argv.slice(2);
+  if (!src || !dest) {
+    console.error('Usage: sqlite-snapshot.js <source.db> <dest.db> [label]');
+    process.exit(2);
+  }
+  if (!fs.existsSync(src)) {
+    console.log(`  ${label}: source missing (${src}) - starting fresh`);
+    removeDbFamily(dest);
+    return;
+  }
+
+  fs.mkdirSync(path.dirname(dest), { recursive: true });
+  removeDbFamily(dest);
+  const tmp = `${dest}.tmp-${process.pid}`;
+  const recovered = `${dest}.recovered-${process.pid}`;
+  removeDbFamily(tmp);
+  removeDbFamily(recovered);
+
+  try {
+    await sqliteBackup(src, tmp);
+    const check = quickCheck(tmp);
+    if (check.ok) {
+      fs.renameSync(tmp, dest);
+      console.log(`  ${label}: snapshotted ${src} -> ${dest}`);
+      return;
+    }
+
+    logDebug(label, `snapshot quick_check failed: ${check.error.slice(0, 160)}`);
+    console.log(`  ${label}: snapshot required recovery - attempting sqlite .recover`);
+    await pipeRecover(tmp, recovered);
+    const recoveredCheck = quickCheck(recovered);
+    if (!recoveredCheck.ok) throw new Error(`recovered DB failed quick_check: ${recoveredCheck.error.slice(0, 160)}`);
+    fs.renameSync(recovered, dest);
+    console.log(`  ${label}: recovered snapshot written to ${dest}`);
+  } catch (err) {
+    logDebug(label, `unable to create healthy snapshot: ${err.message}`);
+    console.warn(`  ${label}: unable to create healthy snapshot - starting fresh`);
+    removeDbFamily(dest);
+  } finally {
+    removeDbFamily(tmp);
+    removeDbFamily(recovered);
+  }
+}
+
+main().catch((err) => {
+  console.error(`sqlite snapshot failed: ${err.stack || err.message}`);
+  process.exit(1);
+});