quilltap 4.10.0-dev.8 → 4.10.0-dev.90

package/README.md

@@ -100,15 +100,19 @@ quilltap instances default Friday                        # Make it the fall-thro
 quilltap instances rename Friday Weekday                 # Rename, preserving the stored passphrase
 quilltap instances remove Friday                         # Unregister
 quilltap instances restore-key Friday                    # Rebuild a lost or passphrase-locked .dbkey
+quilltap instances default --clear                       # Revert to the OS platform default
+quilltap instances list --json                           # The registry as JSON, for scripts
 ```
 
-If an instance's `quilltap.dbkey` goes missing — or its passphrase does — `instances restore-key` rebuilds it. The file only *wraps* the pepper; the pepper itself is the database key, so an operator who kept the one printed at first-run setup can get back in. The pepper is read from `ENCRYPTION_MASTER_PEPPER` or prompted for hidden, never passed as a flag, and it is proved against the encrypted databases on disk before anything is written. Run it with the server down — the command refuses while the instance lock is held. Flags: `--passphrase <pass>` / `--no-passphrase` (the new wrapping), `-d, --data-dir <path>`, `--force`, `-y, --yes`.
+If an instance's `quilltap.dbkey` goes missing — or its passphrase does — `instances restore-key` rebuilds it. The file only *wraps* the pepper; the pepper itself is the database key, so an operator who kept the one printed at first-run setup can get back in. The pepper is read from `ENCRYPTION_MASTER_PEPPER` or prompted for hidden, never passed as a flag, and it is proved against the encrypted databases on disk before anything is written. Run it with the server down — the command refuses while the instance lock is held. Flags: `--passphrase <pass>` / `--no-passphrase` (the new wrapping), `-d, --data-dir <path>`, `--force` (proceed when there is no encrypted database to prove against — a fresh or still-plaintext instance), `-y, --yes`. An existing key file is backed up to `quilltap.dbkey.bak-<timestamp>` first, and a registered instance's stored passphrase is updated to match.
 
-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.
+**It does not re-encrypt character archive bundles.** Those are keyed on the *passphrase*, not the pepper; only the server's Change Passphrase card rewrites them. Bundles made under a passphrase you have just replaced still want the old one.
+
+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 — the CLI appends `data/quilltap.db` itself. `instances list --json` emits the registry (`name`, `path`, `hasPassphrase`, `isDefault`) for scripting.
 
 ## 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.
+The encrypted SQLite databases (main, LLM logs, mount index) can be queried directly via `quilltap db`. They are SQLCipher-encrypted, so the stock `sqlite3` binary **cannot** open them — this is the way in. 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.
 
 ### Subcommands
 
@@ -135,6 +139,27 @@ quilltap db memories --character Friday [--about Amy] [--source AUTO]
 quilltap db characters status               # Per-character vault readiness (--id, --diverged, --blocked)
 ```
 
+SQLite columns are **camelCase**, mirroring the Zod/TypeScript types — `createdAt`, `updatedAt`, `chatType`, `messageCount`, `projectId`, *not* `created_at`. When in doubt, run `quilltap db schema <table>`.
+
+### Character Archive
+
+Archiving prunes a character down to a tombstone and packs everything else into an encrypted `ARCHIVE` bundle in the file library; rehydrating puts it all back at its original ids.
+
+```bash
+quilltap db characters archives                     # Archived characters + the bundles on the shelf
+quilltap db characters archive Ariadne --write      # Archive her (server must be running)
+quilltap db characters rehydrate Ariadne --write    # Wake her again
+quilltap db characters export Ariadne --out /tmp    # Plaintext .qtap, archived or live
+```
+
+`archives` is read-only, and flags **loose** bundles — survivors of a "keep archived bundles" wipe, which are importable but not rehydratable.
+
+`archive` and `rehydrate` run **through the running server's API** (`--port`, default 3000), because the export pipeline and the unlocked passphrase live only in the server process; the server, not the CLI, holds the instance lock for the duration. `--write` is still required as the explicit opt-in. A rehydrate restores the pruned material at its original ids (skip-if-present), clears the tombstone, and queues re-embedding; the bundle stays in the file library afterwards as a spare copy. On failure — wrong-era passphrase, missing bundle, import refusal — the character stays archived and re-running is safe.
+
+`export` writes a **plaintext** `.qtap` and takes no `--write`. For an **archived** character it decrypts the bundle straight off the disk, offline (it tries the internal no-passphrase key, then `QUILLTAP_DB_PASSPHRASE`, then prompts) — the only way to reach packed-away mail, photographs, and summaries without rehydrating. For a **live** character it runs the server's export pipeline, so the server must be up.
+
+**Pre-emptive, not recovery:** exporting an archive needs an instance that can still decrypt it. It is no help to someone holding only a restored backup and a forgotten passphrase — which is also why changing an instance's passphrase rewrites every archive bundle. A bundle reported left behind by a partial rewrite still wants the old one.
+
 ### Maintenance and Snapshots
 
 ```bash
@@ -149,7 +174,7 @@ quilltap db integrity                       # cipher_integrity_check + integrity
 quilltap db integrity llm-logs              # one DB; exit 0 ok, 1 issues, 2 open failure
 ```
 
-`backup` and `integrity` are safe to run while the server is up; `optimize` refuses while a live lock is held. Backups default to `<dataDir>/backups/<timestamp>/` and inherit the source's encryption key transparently.
+`backup` and `integrity` are safe to run while the server is up; `optimize` refuses while a live lock is held (see [Locking](#locking)). Backups default to `<dataDir>/backups/<timestamp>/` and inherit the source's encryption key transparently.
 
 Most subcommands accept `--json` (for piping) and `--limit N`. Names are case-insensitive; aliases are searched alongside character names. Ambiguous matches print all candidates and exit non-zero.
 
@@ -166,10 +191,39 @@ quilltap db --llm-logs --tables                     # Target the LLM logs DB
 quilltap db --mount-points --tables                 # Target the mount index DB
 ```
 
-The database is opened **read-only by default**. Add `--write` to make changes: it opens the database read-write, **claims the instance lock** (`<dataDir>/quilltap.lock`) for the duration, and releases it on exit. It **refuses — with no override — if a running server or another instance holds the lock**, so stop the server first. `--repl` is read-only unless combined with `--write`. Attempting a write without `--write` fails with a hint to re-run with the flag.
+The database is opened **read-only by default**. Add `--write` to make changes: it opens the database read-write, **claims the instance lock** (`<dataDir>/quilltap.lock`) for the duration, and releases it on exit. It **refuses — with no override — if a running server or another instance holds the lock**, so stop the server first. `--repl` is read-only unless combined with `--write`. Attempting a write without `--write` fails with a hint to re-run with the flag. What "held" means, and how to tell a live lock from a stale one, is [below](#locking).
+
+Compressed text columns (`chat_messages.content`, `llm_logs.request` / `response` and friends) are stored as BLOBs. Wrap them in `qt_text()` to read the text: `SELECT qt_text(content) …`.
 
 In the REPL, `.cols <table>` and `.find <text>` mirror the subcommand helpers.
 
+## Locking
+
+Everything that writes to an instance claims `<dataDir>/quilltap.lock` — the same lockfile the server itself uses — for the duration, and releases it on exit. That is `db --write` (including `db --repl --write`), `db optimize`, `maintenance run`, and `instances restore-key`. All four **refuse while the lock is held**: stop the server first. Read-only work — plain `db`, the `docs` read verbs, `memories`, `logs`, `migrations`, `maintenance status`, `db backup`, `db integrity` — never touches the lock and is safe alongside a running instance.
+
+### The five-minute heartbeat window
+
+A lock counts as held until its heartbeat is **five minutes** stale, whether or not the process that set it is still alive. Freshness is the fallback for every environment, not just containers: a PID check is not reliable everywhere, and cleaning a *live* instance's lock is much the worse failure.
+
+So for up to five minutes after stopping the server, `--write`, `optimize`, `maintenance run`, `restore-key`, and `--lock-clean` all still refuse. That is correct behaviour, not a stale lock. Wait it out; the next startup reclaims the lock regardless.
+
+```bash
+quilltap db --lock-status      # Who holds it, and how old the heartbeat is
+quilltap db --lock-clean       # Remove a lock whose heartbeat has gone stale
+```
+
+`--lock-status` shows the heartbeat age, which is the tell. `--lock-clean` says so explicitly rather than muttering about liveness, because that arm is only reached once the PID check has come back dead:
+
+```
+Lock heartbeat is still fresh (82s ago). Cannot clean.
+A lock counts as held until its heartbeat is 5 minutes stale, even if its process has gone.
+Wait it out, or use --lock-override to force.
+```
+
+When a live process really does hold the lock, it refuses with "Lock is held by a live Quilltap process" instead.
+
+**`--lock-override` exists and is almost never the right answer** — it defeats the protection the lock provides. Reach for `--lock-status` first.
+
 ## Document Stores (Scriptorium)
 
 `quilltap docs` exposes the document-store machinery from the command line. Read-only verbs open the mount-index DB directly and work without the server; write and pipeline verbs talk to the running server via `/api/v1/mount-points/[id]`.
@@ -178,6 +232,7 @@ In the REPL, `.cols <table>` and `.find <text>` mirror the subcommand helpers.
 # Read
 quilltap docs list                              # All mounts
 quilltap docs show <mount>                      # One mount, with counts
+quilltap docs files <mount> [--folder <path>]   # Flat file list for a mount
 quilltap docs ls <mount> [path] [--links]       # POSIX-flavoured listing (alias: dir)
 quilltap docs tree <mount> [path]               # ASCII tree of a folder hierarchy (--depth, --max-nodes)
 quilltap docs read [--rendered] <mount> <path>  # File contents → stdout
@@ -203,7 +258,24 @@ quilltap docs rmdir <mount> <path>                            # Delete an empty
 quilltap docs mvdir <mount> <fromPath> <toPath>               # Rename/move a folder (server-required)
 ```
 
-Mount arguments accept the mount name (case-insensitive) or a UUID; ambiguous names print candidates and exit non-zero. `--json` is supported by every verb; `reindex`, `embed`, `link`, `rmdir`, and `mvdir` refuse to run without a reachable server.
+Mount arguments accept the mount name (case-insensitive) or a UUID; ambiguous names print candidates and exit non-zero. `--json` is supported by every verb; `reindex`, `embed`, `link`, `rmdir`, and `mvdir` refuse to run without a reachable server. `grep --semantic` goes through `POST /api/v1/mount-points?action=semantic-search`, because the embedding provider lives in the server; it defaults to `--top 20`, `--threshold 0.5`, `--port 3000`.
+
+### Addressing documents with `qtap://` URIs
+
+Anywhere a verb takes a positional `<mount> <relativePath>` pair — `read`, `write`, `delete`, `mkdir`, `ls`/`dir`, `tree`, `files`, `move`, `copy`, `link`, `rmdir`, `mvdir` — you may pass a single `qtap://…` URI in its place:
+
+```bash
+quilltap docs read qtap://notes/today.md
+quilltap docs move qtap://drafts/foo.md qtap://notes/2026/foo.md
+quilltap docs grep --mount qtap://notes/ "TODO"
+quilltap docs find --uri Manifesto
+```
+
+The URI authority is matched name-first, UUID as fallback — the same rule as a bare `<mount>` (`qtap://<store name>/…` or `qtap://<uuid>/…`). Two-target verbs (`move` / `copy` / `link` / `mvdir`) take either two `qtap://` URIs or the four legacy positionals; `find` and `grep` take one via `--mount`.
+
+**CLI limitation:** the CLI addresses document stores only. `qtap://self/…` needs a character context, and there is none at a shell prompt, so it is rejected with guidance; `qtap://project/…` and `qtap://general/…` are likewise not CLI-addressable — pass a store name or UUID instead.
+
+**Emitting URIs:** `--json` output for `find`, `grep`, `ls`, `files`, and `tree` carries a `uri` field on every row or node. `--uri` switches the text output of `find`, `grep`, and `files` to show the canonical `qtap://` URI as the locator (name form, UUID when the store name is ambiguous).
 
 ### `--base64` flag
 
@@ -213,12 +285,49 @@ Mount arguments accept the mount name (case-insensitive) or a UUID; ambiguous na
 
 ### `link`, `rmdir`, `mvdir`
 
+**`link` vs `copy`:** `docs link` makes two addresses into one document — it shares the content row *and* enrols both link rows in a `linkGroupId`, so a later write through either path repoints both and re-chunks the sibling. `docs copy` produces an independent document that merely shares a deduplicated content row until the first write. The `links` column in `ls` counts group members, not rows that happen to share identical bytes.
+
 `link` calls `POST /api/v1/mount-points/{srcMountId}?action=link-file` with `{sourcePath, destMountPointId, destPath}`. Creates a true hard link with no byte copy; the server reports back a `strategy` field. Errors: `DEST_EXISTS` (exit 2), `UNSUPPORTED` (cross-storage or cross-device), `SOURCE_NOT_FOUND`.
 
 `rmdir` calls `POST /api/v1/mount-points/{mountId}?action=delete-folder` with `{path}`. Fails with a clear message if the folder is not empty (`NOT_EMPTY` / `CONFLICT`).
 
 `mvdir` calls `POST /api/v1/mount-points/{mountId}?action=move-folder` with `{fromPath, toPath}`. Fails with exit 2 if the destination already exists (`DEST_EXISTS`).
 
+### Docker binds
+
+`quilltap docs docker-mounts` reports the bind mounts an instance's filesystem and Obsidian stores need in order to be reachable inside a container. Binds are **path-identical** (`-v /host/vault:/host/vault`), so the `basePath` recorded in the database resolves the same inside and out. Stores sharing a path collapse to a single bind, paths nested inside another bind are dropped, and a path that does not exist is **skipped** rather than handed to Docker to fabricate as an empty directory. It warns about macOS paths outside Docker Desktop's default shares and about a Linux uid mismatch, and refuses on Windows, where path-identical binds are not possible. `--format args` puts only the flags on stdout and all advice on stderr, which is what makes it pipeable into a `docker run`.
+
+## Sync a Store to a Directory
+
+`quilltap sync <store|qtap://store/> <path>` mirrors a **database-backed** document store and a directory on disk in both directions. Edit a file in your own editor and the next run carries it into the store; edit it in the Scriptorium and the next run carries it out.
+
+```bash
+quilltap sync Lore ~/Documents/lore --dry-run   # plan only
+quilltap sync Lore ~/Documents/lore             # apply
+quilltap sync Lore ~/Documents/lore --prefer disk
+```
+
+```text
+--dry-run             Plan and print; change nothing on either side
+--direction <which>   both (default), to-disk, or to-store
+--prefer <which>      newer (default), store, or disk — resolves conflicts
+--no-delete           Never propagate a deletion
+--no-manifest         Ignore .quilltap-sync.json (first-run rules every time)
+--json                Machine-readable plan and results
+-p, --port <n>        Server port (default 3000)
+-i, -d, --passphrase  The usual instance plumbing (used only to resolve <store>)
+```
+
+Compares by SHA-256 first and modification time second, so equal bytes with unequal clocks are re-stamped rather than re-copied. The side that changed wins; when both changed since the last run it is a `conflict` and nothing happens. After a content action both sides carry the winner's `lastModified` and the **older** of the two `createdAt`s. Deletions propagate only when `.quilltap-sync.json` — a manifest the verb keeps in the directory — proves the entry was there at the last run; on a first run an entry present on one side is created on the other, never deleted.
+
+Files and folders whose names begin with a dot are **invisible in both directions**, the manifest being the one exception. A binary's description travels as `<file>.description.md` beside it. Bytes are preserved verbatim: a `.png` pushed from disk stays a `.png`, unlike a Scriptorium upload. Chunks and embedding vectors are never touched by the sync — the store's own post-write hooks re-index.
+
+Exit codes: `0` clean, `1` error or failed action, `2` unresolved conflict; `--dry-run` uses the same codes. Report lines go to stdout, warnings and the summary to stderr.
+
+Server-required (as `docs write` already is for database stores), and the path is resolved **on the server** — under Docker it must sit inside a bind mount (`quilltap docs docker-mounts`). Refused for a filesystem or Obsidian store (one pointed at its own `basePath`), an archived character's vault, a store mid-conversion or mid-scan, a second concurrent run, and a manifest belonging to another store.
+
+A character vault's **keystone files** — `properties.json`, the five required `.md` files, and `Wardrobe/instructions.md` — are never deleted from the store by a sync. The planner reports a `conflict` instead.
+
 ## Memories
 
 `quilltap memories` exposes the same Commonplace Book that each character carries — searchable, sortable, graphable, but never writable. All verbs open the main encrypted DB read-only.
@@ -231,10 +340,11 @@ quilltap memories grep -i --max 3 --context 1 "concrete examples"      # Pattern
 quilltap memories show <id|prefix> [--depth N] [--no-related]          # Full record + related-memory neighbourhood
 quilltap memories tree <id|prefix> [--depth N] [--max-nodes N]         # ASCII walk of the bidirectional related-memory graph
 quilltap memories status [--character <name|id>]                       # Per-holder rollup + dangling-edge check
+quilltap memories validate [--character <name|id>] [--list]            # Dangling-edge health check; exit 1 if any remain
 quilltap memories grep --semantic --character Ariadne "the argument"   # Embedding search (server required, one holder)
 ```
 
-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.
+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. `validate` is `status`'s terse twin — read-only, exit 1 if any dangling related-memory edge remains, `--list` to print the offending source IDs and their dangling targets. `grep --semantic` defaults to `--top 20`, `--threshold 0.5`, `--port 3000`, and scopes to **one holder at a time**: `--character all` is rejected. The legacy `quilltap db memories --character <name>` verb remains undisturbed.
 
 ## Memory Extraction Dry-Run
 

package/bin/quilltap.js

@@ -11,6 +11,7 @@ const {
   printDefaultInstanceHint,
   promptPassphrase,
   loadDbKey,
+  openEncryptedDb,
 } = require('../lib/db-helpers');
 const { resolveInstance } = require('../lib/instances');
 const { resolveModuleDir, ensureNativeModules, ensureDatabaseNativeModule } = require('../lib/native-modules');
@@ -92,6 +93,7 @@ Subcommands:
   db                            Query encrypted databases
   themes                        Manage theme bundles
   docs                          Inspect, read, and export document mounts
+  sync <store> <path>           Mirror a database-backed store to a directory
   memories                      Search, browse, and graph memories
   instances                     Register / inspect named Quilltap instances
   logs                          Tail or print an instance log file
@@ -484,6 +486,51 @@ function verifyPidIsNode(pid, expectedArgv0) {
   }
 }
 
+const HEARTBEAT_FRESH_MS = 5 * 60 * 1000;
+
+/**
+ * The freshness window in words, derived from the constant the check actually
+ * uses — so the sentence `--lock-clean` prints cannot drift away from the
+ * behaviour it describes.
+ */
+function describeFreshWindow() {
+  const seconds = Math.round(HEARTBEAT_FRESH_MS / 1000);
+  if (seconds % 60 !== 0) return `${seconds} seconds`;
+  const minutes = seconds / 60;
+  return minutes === 1 ? '1 minute' : `${minutes} minutes`;
+}
+
+/**
+ * Decide whether a lock record belongs to a live process.
+ *
+ * A hostname that differs from ours does NOT mean a different machine: macOS
+ * derives gethostname() dynamically when `scutil --get HostName` is unset, so
+ * one Mac reports e.g. "MacBook-Pro.local" and "Mac" at different times. So
+ * check PID liveness regardless of the recorded name, and fall back to
+ * heartbeat freshness for any environment rather than only for containers.
+ * See bug 126.
+ */
+function assessLock(lock, hostname) {
+  const sameHost = lock.hostname === hostname;
+  const alive = isPidAlive(lock.pid);
+  const isNode = alive ? verifyPidIsNode(lock.pid, lock.processArgv0 || '') : false;
+  const heartbeatAgeMs = lock.lastHeartbeat
+    ? Date.now() - new Date(lock.lastHeartbeat).getTime()
+    : Infinity;
+  const heartbeatFresh = heartbeatAgeMs < HEARTBEAT_FRESH_MS;
+
+  return {
+    sameHost,
+    alive,
+    isNode,
+    heartbeatAgeMs,
+    heartbeatFresh,
+    // Held by something running: a confirmed local process, or any holder
+    // still refreshing its heartbeat.
+    live: (alive && isNode) || heartbeatFresh,
+  };
+}
+
 /**
  * Handle --lock-status, --lock-clean, --lock-override commands.
  */
@@ -518,32 +565,20 @@ function handleLockCommand(dataDir, opts) {
       return;
     }
 
-    const sameHost = lock.hostname === hostname;
-    const alive = sameHost && isPidAlive(lock.pid);
-    const isNode = alive ? verifyPidIsNode(lock.pid, lock.processArgv0 || '') : false;
+    const { sameHost, alive, isNode, heartbeatAgeMs, heartbeatFresh } =
+      assessLock(lock, hostname);
 
     // Status line
     let status;
     if (alive && isNode) {
       status = '\x1b[32mACTIVE\x1b[0m (process confirmed running)';
+    } else if (heartbeatFresh) {
+      const ageStr = Math.round(heartbeatAgeMs / 1000) + 's';
+      status = `\x1b[32mACTIVE\x1b[0m (${lock.environment || 'unknown'}, heartbeat ${ageStr} ago)`;
     } else if (alive && !isNode) {
       status = '\x1b[33mSUSPECT\x1b[0m (PID alive but does not look like Quilltap — possible PID reuse)';
     } else if (!sameHost) {
-      // Different hostname — could be a container on this machine
-      const isVMOrContainer = lock.environment === 'docker';
-      const heartbeatAgeMs = lock.lastHeartbeat
-        ? Date.now() - new Date(lock.lastHeartbeat).getTime()
-        : Infinity;
-      const heartbeatFreshMs = 5 * 60 * 1000;
-
-      if (isVMOrContainer && heartbeatAgeMs < heartbeatFreshMs) {
-        const ageStr = Math.round(heartbeatAgeMs / 1000) + 's';
-        status = `\x1b[32mACTIVE (${lock.environment}, heartbeat ${ageStr} ago)\x1b[0m`;
-      } else if (isVMOrContainer) {
-        status = `\x1b[33mSTALE (${lock.environment}, no recent heartbeat)\x1b[0m — will be auto-claimed on next startup`;
-      } else {
-        status = '\x1b[33mSTALE (different host)\x1b[0m — will be auto-claimed on next startup';
-      }
+      status = `\x1b[33mSTALE (${lock.environment || 'unknown'} on ${lock.hostname}, no recent heartbeat)\x1b[0m — will be auto-claimed on next startup`;
     } else {
       status = '\x1b[31mSTALE (process dead)\x1b[0m — will be auto-claimed on next startup';
     }
@@ -551,7 +586,7 @@ function handleLockCommand(dataDir, opts) {
     console.log(`Instance Lock Status: ${status}`);
     console.log();
     console.log(`  PID:          ${lock.pid}`);
-    console.log(`  Hostname:     ${lock.hostname}${sameHost ? ' (this host)' : ' (different host)'}`);
+    console.log(`  Hostname:     ${lock.hostname}${sameHost ? ' (this host)' : ` (recorded name differs from ours: ${hostname})`}`);
     console.log(`  Environment:  ${lock.environment || 'unknown'}`);
     console.log(`  Process:      ${lock.processTitle || 'unknown'}`);
     console.log(`  Started:      ${lock.startedAt || 'unknown'}`);
@@ -599,37 +634,31 @@ function handleLockCommand(dataDir, opts) {
       return;
     }
 
-    const sameHost = lock.hostname === hostname;
-    const alive = sameHost && isPidAlive(lock.pid);
+    const { sameHost, alive, isNode, heartbeatAgeMs, heartbeatFresh } =
+      assessLock(lock, hostname);
 
-    if (alive) {
-      const isNode = verifyPidIsNode(lock.pid, lock.processArgv0 || '');
-      if (isNode) {
-        console.log(`Lock is held by a live Quilltap process (PID ${lock.pid}). Cannot clean.`);
-        console.log('Stop the running instance first, or use --lock-override to force.');
-        process.exit(1);
-      } else {
-        console.log(`Lock references PID ${lock.pid} which is alive but does NOT look like a Quilltap process.`);
-        console.log('This is likely a stale lock with a reused PID. Removing.');
-      }
+    if (alive && isNode) {
+      console.log(`Lock is held by a live Quilltap process (PID ${lock.pid}). Cannot clean.`);
+      console.log('Stop the running instance first, or use --lock-override to force.');
+      process.exit(1);
+    } else if (heartbeatFresh) {
+      // Reached only when `alive` is false — the arm above has already claimed
+      // every confirmed-live case — so this must not assert that anything is
+      // running. Freshness alone is the deliberate fallback (bug 126) for
+      // environments where PID checks are unreliable; the refusal is right,
+      // and what it says is simply what was tested.
+      const ageStr = Math.round(heartbeatAgeMs / 1000) + 's';
+      console.log(`Lock heartbeat is still fresh (${ageStr} ago). Cannot clean.`);
+      console.log(
+        `A lock counts as held until its heartbeat is ${describeFreshWindow()} stale, even if its process has gone. ` +
+          'Wait it out, or use --lock-override to force.'
+      );
+      process.exit(1);
+    } else if (alive && !isNode) {
+      console.log(`Lock references PID ${lock.pid} which is alive but does NOT look like a Quilltap process.`);
+      console.log('This is likely a stale lock with a reused PID. Removing.');
     } else if (!sameHost) {
-      // Different hostname — check if it's a container with a recent heartbeat
-      const isVMOrContainer = lock.environment === 'docker';
-      const heartbeatAgeMs = lock.lastHeartbeat
-        ? Date.now() - new Date(lock.lastHeartbeat).getTime()
-        : Infinity;
-      const heartbeatFreshMs = 5 * 60 * 1000;
-
-      if (isVMOrContainer && heartbeatAgeMs < heartbeatFreshMs) {
-        const ageStr = Math.round(heartbeatAgeMs / 1000) + 's';
-        console.log(`Lock is held by a live ${lock.environment} instance (heartbeat ${ageStr} ago). Cannot clean.`);
-        console.log('Stop the other instance first, or use --lock-override to force.');
-        process.exit(1);
-      } else if (isVMOrContainer) {
-        console.log(`Lock was held by ${lock.environment} (${lock.hostname}) with no recent heartbeat. Removing stale lock.`);
-      } else {
-        console.log(`Lock was held by a different host (${lock.hostname}). Removing stale lock.`);
-      }
+      console.log(`Lock was held by ${lock.environment || 'unknown'} on ${lock.hostname} with no recent heartbeat. Removing stale lock.`);
     } else {
       console.log(`Lock was held by PID ${lock.pid} which is no longer running. Removing stale lock.`);
     }
@@ -954,9 +983,10 @@ async function dbCommand(args) {
   }
 
   let dbFilename;
-  if (useLlmLogs) dbFilename = 'quilltap-llm-logs.db';
-  else if (useMountPoints) dbFilename = 'quilltap-mount-index.db';
-  else dbFilename = 'quilltap.db';
+  let dbFriendlyName;
+  if (useLlmLogs) { dbFilename = 'quilltap-llm-logs.db'; dbFriendlyName = 'LLM logs database'; }
+  else if (useMountPoints) { dbFilename = 'quilltap-mount-index.db'; dbFriendlyName = 'mount index database'; }
+  else { dbFilename = 'quilltap.db'; dbFriendlyName = 'main database'; }
   const dbPath = path.join(dataDir, dbFilename);
 
   if (!fs.existsSync(dbPath)) {
@@ -986,27 +1016,16 @@ async function dbCommand(args) {
     }
   }
 
-  // Open database — prefer SQLCipher-capable build
-  let Database;
+  // Open through the one shared opener. It picks the SQLCipher-capable build,
+  // keys the connection, verifies it, and — the reason the low-level path may
+  // not roll its own — registers qt_text(). Without it raw SQL cannot read
+  // inside a compressed text column, and a --write to chat_messages fails
+  // outright because the search-index triggers call it (bug 162).
+  let db;
   try {
-    Database = require('better-sqlite3-multiple-ciphers');
-  } catch {
-    Database = require('better-sqlite3');
-  }
-  const db = new Database(dbPath, { readonly: !writable });
-
-  if (pepper) {
-    const keyHex = Buffer.from(pepper, 'base64').toString('hex');
-    db.pragma(`key = "x'${keyHex}'"`);
-  }
-
-  try {
-    // Verify database is readable
-    db.prepare('SELECT 1').get();
+    db = openEncryptedDb(dbPath, pepper, { readonly: !writable, friendlyName: dbFriendlyName });
   } catch (err) {
-    console.error(`Cannot open database: ${err.message}`);
-    console.error('The database may be encrypted with a different key, or the .dbkey file may be missing.');
-    db.close();
+    console.error(err.message);
     process.exit(1);
   }
 
@@ -1147,7 +1166,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', 'recall-replay', 'completion', 'logs', 'migrations', 'maintenance', 'file-verify',
+  'db', 'themes', 'docs', 'sync', 'memories', 'instances', 'memory-diff', 'recall-replay', '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']);
@@ -1186,6 +1205,12 @@ if (subName === 'db') {
 } else if (subName === 'docs') {
   const { docsCommand } = require('../lib/docs-commands');
   docsCommand(subArgs);
+} else if (subName === 'sync') {
+  const { syncCommand } = require('../lib/sync-command');
+  syncCommand(subArgs).catch(err => {
+    console.error(`Error: ${err.message}`);
+    process.exit(1);
+  });
 } else if (subName === 'memories') {
   const { memoriesCommand } = require('../lib/memories-commands');
   memoriesCommand(subArgs).catch(err => {

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

@@ -108,6 +108,7 @@ describe('every subcommand has its own completion arm', () => {
 const HELP_SOURCES = {
   db: ['bin/quilltap.js', 'printDbHelp'],
   docs: ['lib/docs-commands.js', 'printDocsHelp'],
+  sync: ['lib/sync-command.js', 'printSyncHelp'],
   memories: ['lib/memories-commands.js', 'printMemoriesHelp'],
   themes: ['lib/theme-commands.js', 'printHelp'],
   instances: ['lib/instances-commands.js', 'printHelp'],

package/lib/__tests__/sync-report.test.js

@@ -0,0 +1,158 @@
+/**
+ * How `quilltap sync` renders a plan.
+ *
+ * The formatter is the operator's whole view of what the verb did, and its
+ * two load-bearing claims are easy to get subtly wrong: the second column is
+ * the side that CHANGES (so `modify store` means the store is rewritten from
+ * disk, not the other way round), and the exit code distinguishes "an
+ * unresolved conflict" from "something failed" so a script can tell them apart.
+ *
+ * @jest-environment node
+ */
+
+'use strict';
+
+const {
+  formatActionLine,
+  formatActionLines,
+  formatSummary,
+  exitCodeFor,
+  displayPath,
+  formatBytes,
+} = require('../sync-report');
+
+function action(over = {}) {
+  return { kind: 'create', side: 'disk', relativePath: 'a.md', entryKind: 'file', ...over };
+}
+
+function summary(over = {}) {
+  return {
+    created: 0, modified: 0, deleted: 0, touched: 0,
+    described: 0, conflicts: 0, skipped: 0, failed: 0, ...over,
+  };
+}
+
+describe('one action, one line', () => {
+  it('puts the action first and the side that changes second', () => {
+    expect(formatActionLine(action({ kind: 'modify', side: 'store', relativePath: 'ch.md' }), false))
+      .toBe('modify   store  ch.md');
+  });
+
+  it('pads the columns so paths line up under each other', () => {
+    const lines = formatActionLines([
+      action({ kind: 'mkdir', side: 'disk', relativePath: 'lore', entryKind: 'folder' }),
+      action({ kind: 'conflict', side: null, relativePath: 'ch.md' }),
+    ], false);
+    const column = lines.map((l) => l.indexOf(l.trim().split(/\s+/)[2] || ''));
+    expect(new Set(column).size).toBe(1);
+  });
+
+  it('marks a folder with a trailing slash so it cannot be mistaken for a file', () => {
+    expect(displayPath(action({ entryKind: 'folder', relativePath: 'drafts' }))).toBe('drafts/');
+    expect(displayPath(action({ entryKind: 'file', relativePath: 'drafts' }))).toBe('drafts');
+  });
+
+  it('writes an em dash where no side changes', () => {
+    expect(formatActionLine(action({ kind: 'conflict', side: null }), false))
+      .toContain('conflict —');
+  });
+
+  it('appends the engine’s reason in parentheses', () => {
+    expect(formatActionLine(action({ kind: 'modify', side: 'store', reason: 'disk newer by 2h 14m' }), false))
+      .toContain('(disk newer by 2h 14m)');
+  });
+
+  it('shows the sha and size on a line that moved bytes', () => {
+    const line = formatActionLine(
+      action({ sha256: '3f9a' + '0'.repeat(60), sizeBytes: 421888 }), false
+    );
+    expect(line).toContain('sha 3f9a…');
+    expect(line).toContain('412.0 KB');
+  });
+
+  it('says nothing about bytes on a delete', () => {
+    expect(formatActionLine(action({ kind: 'delete', side: 'store', sha256: 'x'.repeat(64) }), false))
+      .not.toContain('sha');
+  });
+
+  it('leads with the error when an action failed', () => {
+    const line = formatActionLine(
+      action({ outcome: 'failed', error: 'EACCES', reason: 'store newer' }), false
+    );
+    expect(line).toContain('FAILED: EACCES');
+    expect(line).not.toContain('store newer');
+  });
+
+  it('emits no escape codes when colour is off', () => {
+    const lines = formatActionLines(
+      [action(), action({ kind: 'conflict', side: null }), action({ kind: 'delete', side: 'store' })],
+      false
+    );
+    expect(lines.join('\n')).not.toMatch(/\x1b\[/);
+  });
+
+  it('tints the line when colour is on', () => {
+    expect(formatActionLine(action({ kind: 'conflict', side: null }), true)).toMatch(/\x1b\[31m/);
+  });
+
+  it('caps the path column so one long path does not push every detail off screen', () => {
+    const lines = formatActionLines([
+      action({ relativePath: 'a/'.repeat(60) + 'deep.md', reason: 'why' }),
+      action({ relativePath: 'b.md', reason: 'why' }),
+    ], false);
+    expect(lines[1].indexOf('(why)')).toBeLessThan(80);
+  });
+});
+
+describe('the summary', () => {
+  it('names only the categories that actually happened', () => {
+    expect(formatSummary(summary({ created: 3, modified: 1 }), 800, false))
+      .toBe('3 created, 1 modified — 0.8 s');
+  });
+
+  it('says so plainly when there was nothing to do', () => {
+    expect(formatSummary(summary(), 120, false)).toBe('Already in step — 0.1 s');
+  });
+
+  it('speaks in the conditional under --dry-run', () => {
+    expect(formatSummary(summary({ created: 2 }), 300, true)).toBe('Would do: 2 created — 0.3 s');
+    expect(formatSummary(summary(), 300, true)).toBe('Nothing to do — 0.3 s');
+  });
+
+  it('pluralises conflicts', () => {
+    expect(formatSummary(summary({ conflicts: 1 }), 0, false)).toContain('1 conflict —');
+    expect(formatSummary(summary({ conflicts: 2 }), 0, false)).toContain('2 conflicts');
+  });
+
+  it('reports failures last, where they are hardest to miss', () => {
+    const line = formatSummary(summary({ created: 1, failed: 2 }), 0, false);
+    expect(line.indexOf('2 failed')).toBeGreaterThan(line.indexOf('1 created'));
+  });
+});
+
+describe('the exit code', () => {
+  it('is 0 when the run was clean', () => {
+    expect(exitCodeFor(summary({ created: 5, touched: 2 }))).toBe(0);
+  });
+
+  it('is 2 for an unresolved conflict', () => {
+    expect(exitCodeFor(summary({ conflicts: 1 }))).toBe(2);
+  });
+
+  it('is 1 when something failed outright, even alongside a conflict', () => {
+    expect(exitCodeFor(summary({ conflicts: 1, failed: 1 }))).toBe(1);
+  });
+});
+
+describe('byte formatting', () => {
+  it('scales through the units', () => {
+    expect(formatBytes(512)).toBe('512 B');
+    expect(formatBytes(2048)).toBe('2.0 KB');
+    expect(formatBytes(5 * 1024 * 1024)).toBe('5.0 MB');
+    expect(formatBytes(3 * 1024 ** 3)).toBe('3.00 GB');
+  });
+
+  it('says nothing for a size it was not given', () => {
+    expect(formatBytes(undefined)).toBe('');
+  });
+});