quilltap 4.10.0-dev.99 → 4.11.0-dev.106

package/README.md

@@ -135,7 +135,7 @@ quilltap db logs --tail 20                  # Recent LLM logs
 
 quilltap db message <id>                    # Full content of one message
 quilltap db log <id> [--field request|response|both]
-quilltap db memories --character Friday [--about Amy] [--source AUTO]
+quilltap db memories --character Friday [--about Amy] [--source AUTO] [--tier hot|cold]
 quilltap db characters status               # Per-character vault readiness (--id, --diverged, --blocked)
 ```
 
@@ -193,7 +193,7 @@ 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. 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) …`.
+Compressed text columns (`chat_messages.content`, `llm_logs.request` / `response` and friends) are stored as BLOBs. A raw query's output decodes them for display, so `SELECT content …` prints text. Inside SQL — `WHERE`, `LIKE`, `substr`, `json_extract` — wrap the column in `qt_text()` to work on the text: `SELECT json_extract(qt_text(response), '$.error') …`.
 
 In the REPL, `.cols <table>` and `.find <text>` mirror the subcommand helpers.
 
@@ -234,7 +234,8 @@ 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 ls <mount> [path] -R --sort time -r  # Recursive, grouped by folder, sorted by time and reversed
+quilltap docs tree <mount> [path]               # ASCII tree of a folder hierarchy (--depth, --max-nodes, --long)
 quilltap docs read [--rendered] <mount> <path>  # File contents → stdout
 quilltap docs export <mount> <outputDir>        # Mount → directory
 quilltap docs find <pattern>                    # Substring match on file names (--mount, --ext, --type, --limit)
@@ -258,6 +259,8 @@ quilltap docs rmdir <mount> <path>                            # Delete an empty
 quilltap docs mvdir <mount> <fromPath> <toPath>               # Rename/move a folder (server-required)
 ```
 
+`ls` flags: `--recursive` / `-R` lists every file below the path, grouped by folder; `--sort name|time|size|links` (default `name`) with `--reverse` / `-r` to flip it; `--links` lists the other mount/path entries under each file that has more than one hard link. `tree` takes `--depth N` (default 20), `--max-nodes N` (default 1000) and `--long`, which is accepted but reserved — it does not yet add columns.
+
 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
@@ -330,21 +333,33 @@ A character vault's **keystone files** — `properties.json`, the five required
 
 ## 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.
+`quilltap memories` exposes the same Commonplace Book that each character carries — searchable, sortable, graphable. All verbs open the main encrypted DB read-only; the three that change anything (`maintain`, `validate --repair --write`, `keystone --write`) ask the running server to do the work.
 
 ```bash
 quilltap memories ls                                                   # All holders, default sort: reinforcedImportance DESC
 quilltap memories ls --character Ariadne --sort created --limit 10     # One holder, newest first
 quilltap memories find "concrete examples"                             # Substring match on summary (--in content|both)
 quilltap memories grep -i --max 3 --context 1 "concrete examples"      # Pattern search inside content, with snippets
+quilltap memories grep -l "concrete examples"                          # Matching memory IDs only, one per line (--paths-only)
 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 status [--character <name|id>] [--port <n>]          # Per-holder rollup, maintenance ledger + dangling-edge check
+quilltap memories validate [--character <name|id>] [--list]            # Graph health check; exit 1 if any dangling link remains
+quilltap memories validate --repair [--write]                          # Rehearse (or, with --write, apply) the server's graph repair
+quilltap memories keystone <id|prefix> [--off] [--write]               # Rehearse (or, with --write, apply) marking a keystone — a standing fact
 quilltap memories grep --semantic --character Ariadne "the argument"   # Embedding search (server required, one holder)
+quilltap memories maintain --character Ariadne --dry-run               # Rehearse every maintenance phase (server required)
+quilltap memories maintain --character Ariadne --phases consolidate    # Queue a consolidation-only maintenance job
+quilltap memories maintain --character all [--phases demote,retire]    # Queue maintenance for every character
 ```
 
-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.
+Shared filter flags apply to `ls`, `find`, `grep`, and `status` where they make sense: `--character`, `--about` (with `self` / `none` shortcuts), `--source` (AUTO / MANUAL / CONSOLIDATED), `--tier` (hot / cold; both by default, cold rows are starred in the `src` column), `--keystone` (keystones only; a keystone's summary is prefixed `◆` in tables, and `show` prints a `Keystone:` line), `--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` / `--reverse` to flip it, `--limit N` (default 50) and `--full-titles` to stop chat titles being truncated to 32 characters) apply to `ls`, `find`, and `grep`. `grep -l` / `--paths-only` prints only the IDs of matching memories, one per line. 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; it counts dangling `relatedMemoryIds` edges, dangling `consolidatedFrom` members (digests naming notes that are gone), dangling `supersededById` pointers, and rows with no embedding. It exits 1 if any dangling link remains (a missing embedding only warns), and `--list` prints the offending IDs. `grep --semantic` defaults to `--top 20`, `--threshold 0.5`, and scopes to **one holder at a time**: `--character all` is rejected. The legacy `quilltap db memories --character <name>` verb remains, now with `--tier hot|cold` (rows with no tier count as hot).
+
+Verbs that call the server (`grep --semantic`, `status`'s ledger, `maintain`, `validate --repair`, `keystone --write`) take `--port`; without it they use the port recorded in the `--instance` / `--data-dir` instance's lock, else 3000.
+
+`maintain` runs the memory maintenance job by hand: `fold-near-duplicates`, `consolidate`, `demote`, `retire`, `mirror`, always in that order. `--character <name|id|all>` is required (`all` is every character you own); `--phases a,b,…` picks a subset (checked by the server, which answers an unknown name with a 400; naming `consolidate` brings `mirror` along, since the Commonplace mirror follows consolidation). The CLI resolves the character locally and asks the running server — the model, the embeddings and the only database writer live there. With `--dry-run` the server rehearses the run and writes nothing: the CLI prints each phase's status (ran / skipped, and why), then the fold groups, the consolidation clusters (member notes, proposed digests, standalones, contradictions, run stats), the demotion arithmetic (cap, hot total, demotable, protected, excess, demoted), the retire count and the mirror subjects. A dry run over `all` gives one table row per character and may not include `consolidate` (each would call the model). Without `--dry-run` the server queues one `MEMORY_MAINTENANCE` job per character and the CLI prints the job ids; manual runs ignore the master `enabled` switches. `--max N` caps clusters consolidated (`maxClustersPerRun`, 1–1000; a dry run defaults to 10, at most 40), `--threshold 0..1` overrides the cluster similarity (neural embedding profiles), `--cap N` overrides the hot-row cap for demotion (100–100000). `--json` prints the raw API payload. There is no `consolidate` verb any more: use `maintain --phases consolidate`.
+
+`validate --repair` asks the running server to repair what `validate` finds. Without `--write` it is a dry run that prints what would be repaired and changes nothing; with `--write` the server scrubs dangling `relatedMemoryIds`, `consolidatedFrom` and `supersededById` links and queues embedding jobs for rows with none (up to 2000 per run; it needs a default embedding profile). As with `db characters archive`, the write runs inside the server, which holds the instance lock, so the server must be up. `status` also shows the character's maintenance ledger — when each phase last ran and whether the last demotion was effective — when it can reach the running server, and the last three maintenance job rows either way.
 
 ## Memory Extraction Dry-Run
 
@@ -355,7 +370,9 @@ quilltap memory-diff <chatId> --instance Friday          # Report to the current
 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).
+Needs a running server to reach the extraction pipeline: pass `--port`, or name the server's instance with `--instance`/`--data-dir` and the port is read from its lock file (see [Finding the server](#finding-the-server)); otherwise 3000. `--out <dir>` sets the report destination (default: cwd); `--concurrency N` bounds parallel turns (default 4, max 32).
+
+The dry run is the live pipeline with nothing written: every turn, then both fold passes (`other-fold`, `episode-fold`) over the history a regenerate would rebuild, autonomous rooms included. Each re-extracted candidate records `extractionPass` and `decision` — what admission would do with it (`insert`, `reinforce`, `absorb`, …). Admission embeds each candidate to decide, so a dry run makes embedding calls.
 
 ## Recall Replay
 
@@ -365,9 +382,45 @@ Needs a running server (`--port`, default 3000) to reach the extraction pipeline
 quilltap recall-replay <chatId>                 # Replay the last turn
 quilltap recall-replay <chatId> --turn 42       # Replay at interchange 42 (its own clock)
 quilltap recall-replay <chatId> --json          # Raw JSON for scripting
+quilltap recall-replay <chatId> --memory-budget 4000  # Budget-sized dynamic head
+quilltap recall-replay <chatId> --turn 42 --json > t42.json
+quilltap recall-replay <chatId> --turn 42 --signals-from t42.json --as-of \
+  --tuning '{"boostGateAbs":0.45,"boostGateMargin":0.15,"boostGateRamp":0.1}'
+```
+
+Flags: `--turn <n>` (default: last), `--char <characterId>` (default: first LLM-controlled participant), `--limit <n>` (default: the larger of 25 and the new path's head size + 10), `--memory-budget <tokens>` (positive integer; the new path's selected rows then follow the budget-sized dynamic head, which scales with the model's memory budget, while the old path keeps the historical fixed 5-entry head; each path header prints its head size), `--instance <name>` / `--data-dir <path>` (find the server's port, see [Finding the server](#finding-the-server)), `--port <n>` (default: from the instance lock, else 3000), `--json`.
+
+Tuning and comparable runs:
+
+- `--tuning '<json>'` / `--tuning-file <path>` — retuning constants for the new path only (the old path stays the reference): `boostGateAbs`, `boostGateMargin`, `boostGateRamp` (relevance gate on boosts), `boostCap`, `freshBypassesGate`, `windowBypassesGate`, `multipliers` (`{ "freshEvent24h": 1.3, … }`), `specificAnchors`, `anchorMinHits`, `anchorOrder`, `backgroundReserve`, `innerCircleShare` (share of the frozen archive the group inner circle may take, default `0.333…`), `innerCircleAllowance` (digests per circle member by tier, tightest group first, default `[3, 2, 1]`). Unknown keys are rejected. The header's `Tuning` line shows what is active.
+- `--signals-from <replay.json>` — reuse the signals saved in an earlier `--json` replay of the same chat and turn. The distillation is a cheap-LLM call and words the same turn differently each time, so runs you mean to compare should share it.
+- `--as-of` — search only memories created before the turn's opening message, with weights decayed to the turn's own clock: the corpus as it stood then. The header's `Harness` line shows the cutoff and how many later memories were left out.
+
+The server memoises the replay's embeddings by text until it restarts, so repeat runs embed identical vectors.
+
+After the two tables the replay prints:
+
+- **TEXT FALLBACK** — what the new path returns with no usable vector (the text strategy over the same question).
+- **STAGE TRACE** — one line per recall stage: `query` (distilled or pinned, embedding calls), `gather` / `hydrate` / `score` / `select` for the head search (pool size, floor, window mode, expansion, the cut), and `assemble` per pool (what the archive held and its budget cut, how many pool rows the archive removed from the head, what the inter-character section took and skipped as already delivered).
+- **Ring** — the anti-repetition ring the replay ranked under: the one in force at that turn, rebuilt from the `[Recall:ring]` lines each reply's `debugMemoryLogs` carries, or the chat's current ring for a chat older than those records.
+
+`--json` adds `fallbackPath`, `trace`, `pools`, `ring` and `ringSource` to the result.
+
+## Anchor Probe
+
+`quilltap anchor-probe <characterId>` measures whether the episodic anchor line embedded with each memory suppresses reinforcement at admission. It re-embeds the character's most recent memories with and without the anchor line, compares each against older rows, asks admission's own decider (the same subject, kind, source and date-guard rules a new memory meets) what it would do each way, and reports how many rows would fold into an older one and how many would be absorbed as near-duplicates, plus a per-row table (rows that would fold only without anchors are highlighted). Read-only, but it costs embedding calls (roughly up to 7 per sampled row).
+
+```bash
+quilltap anchor-probe <characterId>             # Sample the 50 most recent memories
+quilltap anchor-probe <characterId> --limit 20  # Smaller, cheaper sample
+quilltap anchor-probe <characterId> --json      # Raw JSON for scripting
 ```
 
-Flags: `--turn <n>` (default: last), `--char <characterId>` (default: first LLM-controlled participant), `--limit <n>` (default 25), `--port <n>` (default 3000), `--json`.
+Flags: `--limit <n>` (1–200, default 50), `--instance <name>` / `--data-dir <path>` (find the server's port, see [Finding the server](#finding-the-server)), `--port <n>` (default: from the instance lock, else 3000), `--json`.
+
+### Finding the server
+
+`memory-diff`, `recall-replay` and `anchor-probe` call a running server over HTTP. The server records the port it listens on in its instance lock (`<dataDir>/data/quilltap.lock`, field `port`; shown by `quilltap db --lock-status`). Resolution order: an explicit `--port` wins; otherwise, if `--instance` or `--data-dir` is given and that lock is live and records a port, that port is used (a dim note says so); otherwise 3000. Giving both `--instance` and `--data-dir` is an error. `--passphrase` is accepted by all three for uniformity; `recall-replay` and `anchor-probe` ignore it. Locks written before this field existed carry no port, so restart the server once to record it.
 
 ## Maintenance & Cleanup
 
@@ -432,7 +485,13 @@ quilltap themes create sunset           # Scaffold a new theme
 quilltap themes search "dark"           # Search registries
 quilltap themes update                  # Check for theme updates
 quilltap themes registry list           # List configured registries
-quilltap themes registry add <url>      # Add a registry source
+quilltap themes registry add <url>      # Add a registry source (--key <pubkey>, --name <name>)
+quilltap themes registry remove <name>  # Remove a registry source
+quilltap themes registry refresh        # Refresh all registry indexes
+
+# For registry operators
+quilltap themes registry keygen [--output <dir>]     # Generate an Ed25519 keypair
+quilltap themes registry sign <dir> --key <private>  # Sign a registry directory
 ```
 
 ## Shell Completion
@@ -511,7 +570,7 @@ Fish picks new completion files up automatically — no shell restart needed.
 
 Completions **parse the line rather than counting words**, so a flag typed anywhere the CLI itself accepts one does not derail them: `quilltap docs --instance Friday <TAB>` still offers the `docs` verbs. bash and zsh also reuse the `-i` / `-d` / `--passphrase` already on the line when looking store names up, so the names offered come from the instance you are addressing rather than the default one. fish completes `--mount` but not the positionals, and always reads the default instance.
 
-Dynamic completions shell out to `quilltap`'s own subcommands. If the active instance is encrypted and no passphrase is reachable, the completion silently returns nothing rather than prompting in the middle of a tab.
+Dynamic completions shell out to `quilltap`'s own subcommands — `quilltap instances list --names-only` and `quilltap docs list --names-only`, which print one name per line and are handy in scripts too. If the active instance is encrypted and no passphrase is reachable, the completion silently returns nothing rather than prompting in the middle of a tab.
 
 ## Requirements
 

package/bin/quilltap.js

@@ -14,6 +14,7 @@ const {
   openEncryptedDb,
 } = require('../lib/db-helpers');
 const { resolveInstance } = require('../lib/instances');
+const { decodeCompressedTextInRows } = require('../lib/text-codec');
 const { resolveModuleDir, ensureNativeModules, ensureDatabaseNativeModule } = require('../lib/native-modules');
 
 const PACKAGE_DIR = path.resolve(__dirname, '..');
@@ -102,6 +103,7 @@ Subcommands:
   file-verify                   Force-download cloud-evicted data files (iCloud, etc.)
   memory-diff <chatId>          Dump existing memories and dry-run re-extraction for a chat
   recall-replay <chatId>        Replay a turn's memory recall, old vs episodic ranking
+  anchor-probe <characterId>    Probe whether episodic anchor lines suppress reinforcement at admission
   completion <shell>            Generate a shell completion script (bash / zsh / fish)
 
 Options:
@@ -590,6 +592,9 @@ function handleLockCommand(dataDir, opts) {
     console.log(`  Environment:  ${lock.environment || 'unknown'}`);
     console.log(`  Process:      ${lock.processTitle || 'unknown'}`);
     console.log(`  Started:      ${lock.startedAt || 'unknown'}`);
+    if (Number.isInteger(lock.port)) {
+      console.log(`  Port:         ${lock.port}`);
+    }
 
     // Show heartbeat age if available
     if (lock.lastHeartbeat) {
@@ -764,7 +769,10 @@ Subcommands (high-level shortcuts; auto-pick the right database):
   message <id>                Full content of a single chat message
   log <id>                    Full request/response of a single LLM log
   memories --character <id>   Memories held by a character
-                              (flags: --about <id|name> --source AUTO|MANUAL)
+                              (flags: --about <id|name>
+                              --source AUTO|MANUAL|CONSOLIDATED
+                              --tier hot|cold (NULL tier counts as hot)
+                              --limit N)
   characters status           Per-character vault readiness report:
                               flag value, vault present, single-file count,
                               Prompts/ and Scenarios/ folder counts, and any
@@ -1037,11 +1045,13 @@ async function dbCommand(args) {
     } else if (countTable) {
       const row = db.prepare(`SELECT count(*) as count FROM "${countTable}"`).get();
       if (asJson) console.log(JSON.stringify({ table: countTable, count: row.count }, null, 2));
-      else console.log(row.count);
+      else console.log(String(row.count));
     } else if (sql) {
       const stmt = db.prepare(sql);
       if (stmt.reader) {
         const rows = stmt.all();
+        // Compressed text columns arrive as Buffers; print them as text (bug 173).
+        decodeCompressedTextInRows(rows);
         if (asJson) {
           console.log(JSON.stringify(rows, null, 2));
         } else if (rows.length === 0) {
@@ -1110,6 +1120,7 @@ async function dbCommand(args) {
             const stmt = db.prepare(trimmed);
             if (stmt.reader) {
               const rows = stmt.all();
+              decodeCompressedTextInRows(rows);
               if (rows.length === 0) console.log('(no results)');
               else console.table(rows);
             } else {
@@ -1166,7 +1177,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', 'sync', 'memories', 'instances', 'memory-diff', 'recall-replay', 'completion', 'logs', 'migrations', 'maintenance', 'file-verify',
+  'db', 'themes', 'docs', 'sync', 'memories', 'instances', 'memory-diff', 'recall-replay', 'anchor-probe', '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']);
@@ -1238,6 +1249,12 @@ if (subName === 'db') {
     console.error(`Error: ${err.message}`);
     process.exit(1);
   });
+} else if (subName === 'anchor-probe') {
+  const { anchorProbeCommand } = require('../lib/anchor-probe-command');
+  anchorProbeCommand(subArgs).catch(err => {
+    console.error(`Error: ${err.message}`);
+    process.exit(1);
+  });
 } else if (subName === 'completion') {
   const { completionCommand } = require('../lib/completion-commands');
   completionCommand(subArgs).catch(err => {

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

@@ -118,6 +118,7 @@ const HELP_SOURCES = {
   'file-verify': ['lib/file-verify-commands.js', 'printHelp'],
   'memory-diff': ['lib/memory-diff-command.js', 'printMemoryDiffHelp'],
   'recall-replay': ['lib/recall-replay-command.js', 'printRecallReplayHelp'],
+  'anchor-probe': ['lib/anchor-probe-command.js', 'printAnchorProbeHelp'],
   completion: ['lib/completion-commands.js', 'printCompletionHelp'],
 };
 

package/lib/__tests__/memories-maintain-command.test.js

@@ -0,0 +1,276 @@
+/**
+ * `quilltap memories maintain` and `validate --repair`: flag parsing, phase
+ * validation, request bodies, report rendering, and the integrity scan.
+ *
+ * @jest-environment node
+ */
+
+'use strict';
+
+const { parseFlags, renderRepairText } = require('../memories-commands');
+const {
+  parsePhases,
+  buildMaintainBody,
+  renderMaintenanceReport,
+  renderReportsTable,
+} = require('../memories-maintain-command');
+const { scanDigestIntegrity } = require('../graph-integrity');
+
+const ID = '11111111-2222-3333-4444-555555555555';
+
+describe('memories maintain flags', () => {
+  it('parses verb, character, phases, dry-run, max, threshold, cap and port', () => {
+    const { flags, positional } = parseFlags([
+      'maintain', '--instance', 'Friday', '--character', 'Friday', '--phases', 'consolidate,demote',
+      '--dry-run', '--max', '12', '--threshold', '0.8', '--cap', '500', '--port', '3005', '--json',
+    ]);
+    expect(positional).toEqual(['maintain']);
+    expect(flags).toMatchObject({
+      instance: 'Friday', character: 'Friday', phases: 'consolidate,demote', dryRun: true,
+      max: 12, threshold: 0.8, cap: 500, port: 3005, json: true,
+    });
+  });
+
+  it('leaves the port undefined so the instance lock can supply it', () => {
+    expect(parseFlags(['maintain', '--character', 'X']).flags.port).toBeUndefined();
+    expect(parseFlags(['maintain', '-p', '3007']).flags.port).toBe(3007);
+  });
+
+  it('parses --repair and --write for validate', () => {
+    const { flags } = parseFlags(['validate', '--repair', '--write']);
+    expect(flags).toMatchObject({ repair: true, write: true });
+  });
+});
+
+describe('parsePhases', () => {
+  it('returns null for every phase', () => {
+    expect(parsePhases('')).toBeNull();
+    expect(parsePhases(undefined)).toBeNull();
+  });
+
+  it('trims and drops duplicates, leaving names and order to the server', () => {
+    expect(parsePhases('mirror, demote,fold-near-duplicates,demote')).toEqual(['mirror', 'demote', 'fold-near-duplicates']);
+    // No local phase list: an unknown name is the server's 400 to report.
+    expect(parsePhases('consolidate,housekeep')).toEqual(['consolidate', 'housekeep']);
+  });
+});
+
+describe('buildMaintainBody', () => {
+  it('defaults to a real run of every phase with no overrides', () => {
+    const { flags } = parseFlags(['maintain', '--character', 'X']);
+    expect(buildMaintainBody(ID, flags)).toEqual({ characterId: ID, dryRun: false });
+  });
+
+  it('maps the knobs onto settings', () => {
+    const { flags } = parseFlags([
+      'maintain', '--dry-run', '--phases', 'consolidate', '--max', '5', '--threshold', '0.65', '--cap', '300',
+    ]);
+    expect(buildMaintainBody(ID, flags)).toEqual({
+      characterId: ID,
+      dryRun: true,
+      phases: ['consolidate'],
+      settings: { maxClustersPerRun: 5, consolidation: { clusterThreshold: 0.65 }, cap: 300 },
+    });
+  });
+
+  it('omits characterId for a user-wide run', () => {
+    const { flags } = parseFlags(['maintain', '--character', 'all']);
+    expect(buildMaintainBody(null, flags)).toEqual({ dryRun: false });
+  });
+
+  it('allows a user-wide dry run of the model-free phases', () => {
+    const { flags } = parseFlags(['maintain', '--dry-run', '--phases', 'demote,retire']);
+    expect(buildMaintainBody(null, flags)).toEqual({ dryRun: true, phases: ['demote', 'retire'] });
+  });
+
+  it('passes bounds through for the server to judge (no local copy of its limits)', () => {
+    expect(buildMaintainBody(ID, parseFlags(['maintain', '--cap', '50']).flags)).toMatchObject({ settings: { cap: 50 } });
+    expect(buildMaintainBody(ID, parseFlags(['maintain', '--max', '5000']).flags)).toMatchObject({ settings: { maxClustersPerRun: 5000 } });
+    expect(buildMaintainBody(null, parseFlags(['maintain', '--dry-run']).flags)).toEqual({ dryRun: true });
+  });
+});
+
+describe('renderMaintenanceReport', () => {
+  function capture(fn) {
+    let out = '';
+    fn((s) => { out += s; });
+    return out.replace(/\x1b\[[0-9;]*m/g, '');
+  }
+
+  it('prints phase lines and every phase detail', () => {
+    const out = capture((write) => renderMaintenanceReport({
+      characterId: ID, characterName: 'Ariadne', dryRun: true, durationMs: 2500,
+      phases: [
+        { phase: 'fold-near-duplicates', status: 'ran', durationMs: 10 },
+        { phase: 'consolidate', status: 'ran', durationMs: 2000 },
+        { phase: 'demote', status: 'ran', durationMs: 5 },
+        { phase: 'retire', status: 'skipped', skippedBecause: 'no-retention-window', durationMs: 0 },
+        { phase: 'mirror', status: 'ran', durationMs: 3 },
+      ],
+      fold: {
+        eligible: 80, deferred: 0, groupsDeferred: 0, folded: 2, groupsFailed: 0,
+        groups: [{ survivorId: 'aaaaaaaa-1', absorbedIds: ['bbbbbbbb-2', 'cccccccc-3'], minCosine: 0.97 }],
+      },
+      consolidation: {
+        dryRun: true,
+        clusters: [{
+          bucket: { kind: 'other', subjectName: 'Calvin', subjectCharacterId: 'c' },
+          clusterKind: 'semantic', status: 'planned',
+          memberIds: ['aaaaaaaa-1', 'bbbbbbbb-2'], memberContents: ['Calvin likes tea', 'Calvin drinks tea daily'],
+          keepStandalone: ['bbbbbbbb-2'], contradictions: [{ olderId: 'aaaaaaaa-1', newerId: 'bbbbbbbb-2', note: 'tea vs coffee' }],
+          digests: [{ id: 'd1', action: 'create', content: 'Calvin is a devoted tea drinker', importance: 0.6, memberIds: ['aaaaaaaa-1'] }],
+        }],
+        stats: { candidates: 40, clustersFound: 3, clustersAttempted: 1, clustersDeferred: 2, durationMs: 1500 },
+      },
+      demote: {
+        cap: 1000, hotTotal: 1300, demotable: 1200, protected: 100, excess: 200, demoted: 200,
+        demotedIds: [], highestScoreDemoted: 0.4,
+      },
+      mirror: { subjects: ['self', 'Calvin'], filesWritten: 0, deferredToCommit: false },
+    }, write));
+    expect(out).toContain('Maintenance dry run');
+    expect(out).toContain('Ariadne');
+    expect(out).toContain('no-retention-window');
+    expect(out).toContain('aaaaaaaa <=');
+    expect(out).toContain('folded 2');
+    expect(out).toContain('about Calvin');
+    expect(out).toContain('Calvin likes tea');
+    expect(out).toContain('[kept standalone]');
+    expect(out).toContain('Calvin is a devoted tea drinker');
+    expect(out).toContain('tea vs coffee');
+    expect(out).toContain('candidates 40');
+    expect(out).toContain('cap 1000');
+    expect(out).toContain('demotable 1200');
+    expect(out).toContain('excess 200');
+    expect(out).toContain('self, Calvin');
+  });
+
+  it('reports a skipped run', () => {
+    const out = capture((write) => renderMaintenanceReport({
+      characterId: ID, characterName: null, dryRun: true, skippedReason: 'archived', phases: [],
+    }, write));
+    expect(out).toContain('Skipped: archived');
+  });
+
+  it('reports a skipped consolidation', () => {
+    const out = capture((write) => renderMaintenanceReport({
+      characterId: ID, characterName: 'A', dryRun: true, phases: [],
+      consolidation: { dryRun: true, skippedReason: 'no-llm', clusters: [], stats: {} },
+    }, write));
+    expect(out).toContain('Skipped: no-llm');
+  });
+});
+
+describe('renderReportsTable', () => {
+  it('prints one row per character', () => {
+    let out = '';
+    renderReportsTable([
+      {
+        characterId: ID, characterName: 'Ariadne', dryRun: true,
+        phases: [{ phase: 'demote', status: 'ran', durationMs: 1 }, { phase: 'retire', status: 'ran', durationMs: 1 }],
+        demote: { cap: 1000, hotTotal: 10, demotable: 10, protected: 0, excess: 0, demoted: 0, demotedIds: [], highestScoreDemoted: null },
+        retire: { retentionDays: 90, retired: 3, retiredIds: [] },
+      },
+      { characterId: 'ffffffff-0', characterName: null, dryRun: true, skippedReason: 'archived', phases: [] },
+    ], (s) => { out += s; });
+    out = out.replace(/\x1b\[[0-9;]*m/g, '');
+    expect(out).toContain('across 2 characters');
+    expect(out).toMatch(/Ariadne\s+demote,retire\s+-\s+10\/1000 -0\s+3/);
+    expect(out).toContain('ffffffff');
+    expect(out).toContain('skipped: archived');
+  });
+});
+
+describe('scanDigestIntegrity', () => {
+  // better-sqlite3 is mocked under jest, so drive the scanner with a fake
+  // that answers the handful of queries it issues.
+  function fakeDb(rows, columns) {
+    const has = new Set(columns);
+    const scoped = (sql, params) => (sql.includes('characterId = ?') ? rows.filter((r) => r.characterId === params[0]) : rows);
+    return {
+      prepare(sql) {
+        return {
+          all: (...params) => {
+            if (sql.startsWith('PRAGMA')) return [...has].map((name) => ({ name }));
+            if (sql.trim() === 'SELECT id FROM memories') return rows.map((r) => ({ id: r.id }));
+            if (sql.includes('consolidatedFrom FROM')) {
+              return scoped(sql, params).filter((r) => r.consolidatedFrom && r.consolidatedFrom !== '[]');
+            }
+            if (sql.includes('supersededById FROM')) return scoped(sql, params).filter((r) => r.supersededById != null);
+            throw new Error(`unexpected query: ${sql}`);
+          },
+          get: (...params) => {
+            if (sql.includes('embedding IS NULL')) return { n: scoped(sql, params).filter((r) => r.embedding == null).length };
+            throw new Error(`unexpected query: ${sql}`);
+          },
+        };
+      },
+    };
+  }
+
+  const ALL_COLUMNS = ['id', 'characterId', 'relatedMemoryIds', 'consolidatedFrom', 'supersededById', 'embedding'];
+
+  it('counts dangling digest members, dangling supersededById and missing embeddings', () => {
+    const db = fakeDb([
+      { id: 'digest', characterId: 'c1', consolidatedFrom: JSON.stringify(['m1', 'gone1', 'gone2']), supersededById: null, embedding: 'x' },
+      { id: 'm1', characterId: 'c1', consolidatedFrom: '[]', supersededById: 'digest', embedding: 'x' },
+      { id: 'm2', characterId: 'c1', consolidatedFrom: '[]', supersededById: 'gone-digest', embedding: null },
+      { id: 'other', characterId: 'c2', consolidatedFrom: JSON.stringify(['gone3']), supersededById: null, embedding: null },
+    ], ALL_COLUMNS);
+
+    const one = scanDigestIntegrity(db, { characterId: 'c1', includePairs: true });
+    expect(one.consolidatedFrom).toEqual({ links: 2, digests: 1 });
+    expect(one.supersededBy).toBe(1);
+    expect(one.missingEmbeddings).toBe(1);
+    expect(one.consolidatedFromPairs).toEqual([{ digestId: 'digest', characterId: 'c1', memberIds: ['gone1', 'gone2'] }]);
+    expect(one.supersededByPairs).toEqual([{ memberId: 'm2', characterId: 'c1', digestId: 'gone-digest' }]);
+
+    const all = scanDigestIntegrity(db);
+    expect(all.consolidatedFrom).toEqual({ links: 3, digests: 2 });
+    expect(all.missingEmbeddings).toBe(2);
+  });
+
+  it('reads an instance without the tier-era columns as nothing to scan', () => {
+    const db = fakeDb([{ id: 'm1', characterId: 'c1', embedding: null }], ['id', 'characterId', 'relatedMemoryIds', 'embedding']);
+    expect(scanDigestIntegrity(db)).toEqual({
+      consolidatedFrom: { links: 0, digests: 0 }, supersededBy: 0, missingEmbeddings: 1,
+    });
+  });
+});
+
+describe('renderRepairText', () => {
+  function captureLog(fn) {
+    const lines = [];
+    const spy = jest.spyOn(console, 'log').mockImplementation((...args) => { lines.push(args.join(' ')); });
+    try { fn(); } finally { spy.mockRestore(); }
+    return lines.join('\n').replace(/\x1b\[[0-9;]*m/g, '');
+  }
+  const found = {
+    related: { links: 3, rows: 2 }, consolidatedFrom: { links: 1, digests: 1 }, supersededBy: 2, missingEmbeddings: 4,
+  };
+
+  it('prints a dry run with the --write hint', () => {
+    const out = captureLog(() => renderRepairText({ dryRun: true, characterId: null, found }));
+    expect(out).toContain('dry run, every memory');
+    expect(out).toContain('3 dangling related link(s) on 2 row(s)');
+    expect(out).toContain('1 dangling consolidatedFrom member(s) on 1 digest(s)');
+    expect(out).toContain('2 dangling supersededById');
+    expect(out).toContain('4 row(s) without an embedding');
+    expect(out).toContain('Add --write');
+  });
+
+  it('prints the repaired counts and a skipped embedding pass', () => {
+    const out = captureLog(() => renderRepairText({
+      dryRun: false, characterId: ID, found,
+      repaired: {
+        relatedRowsTouched: 2, digestsTouched: 1, membersCut: 2, charactersAffected: 1,
+        embeddingJobsQueued: 0, embeddingSkippedReason: 'no-embedding-profile',
+      },
+    }));
+    expect(out).toContain('(applied)');
+    expect(out).toContain('2 row(s) relinked, 1 digest(s) touched, 2 member(s) cut loose');
+    expect(out).toContain('0 embedding job(s) queued');
+    expect(out).toContain('no-embedding-profile');
+    expect(out).not.toContain('Add --write');
+  });
+});

package/lib/__tests__/migrations-source-ids.test.js

@@ -0,0 +1,54 @@
+/**
+ * `quilltap migrations status` compares the ledger against the ids it reads
+ * out of `migrations/scripts/*.ts`. Most migrations declare their id through a
+ * `MIGRATION_ID` constant rather than a string literal; when the reader only
+ * understood literals, every one of those vanished from "source" and showed up
+ * as "retired" on any instance that had run it.
+ *
+ * @jest-environment node
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const { extractMigrationId } = require('../migrations-commands');
+
+describe('extractMigrationId', () => {
+  it('reads a string-literal id', () => {
+    expect(extractMigrationId(`export const m = {\n  id: 'foo-v1',\n};`)).toBe('foo-v1');
+  });
+
+  it('resolves an id declared through MIGRATION_ID', () => {
+    const src = `const MIGRATION_ID = 'bar-v1';\nexport const m = {\n  id: MIGRATION_ID,\n};`;
+    expect(extractMigrationId(src)).toBe('bar-v1');
+  });
+
+  it('accepts a typed MIGRATION_ID constant', () => {
+    const src = `const MIGRATION_ID: string = 'baz-v1'\nexport const m = {\n  id: MIGRATION_ID,\n};`;
+    expect(extractMigrationId(src)).toBe('baz-v1');
+  });
+
+  it('returns null when no id is declared', () => {
+    expect(extractMigrationId('export const nothing = 1;')).toBeNull();
+  });
+});
+
+describe('every migration script yields an id', () => {
+  const scriptsDir = path.join(__dirname, '..', '..', '..', '..', 'migrations', 'scripts');
+  const files = fs.existsSync(scriptsDir)
+    ? fs.readdirSync(scriptsDir).filter((f) => f.endsWith('.ts') && f !== 'index.ts')
+    : [];
+
+  it('finds the migration scripts', () => {
+    expect(files.length).toBeGreaterThan(100);
+  });
+
+  it('extracts an id from each one', () => {
+    const missing = files.filter(
+      (f) => !extractMigrationId(fs.readFileSync(path.join(scriptsDir, f), 'utf8'))
+    );
+    expect(missing).toEqual([]);
+  });
+});