quilltap 4.10.0-dev.146 → 4.10.0-dev.173

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)
 ```
 
@@ -330,7 +330,7 @@ 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 two that change anything (`maintain`, `validate --repair --write`) ask the running server to do the work.
 
 ```bash
 quilltap memories ls                                                   # All holders, default sort: reinforcedImportance DESC
@@ -339,16 +339,22 @@ quilltap memories find "concrete examples"                             # Substri
 quilltap memories grep -i --max 3 --context 1 "concrete examples"      # Pattern search inside content, with snippets
 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 grep --semantic --character Ariadne "the argument"   # Embedding search (server required, one holder)
-quilltap memories consolidate --character Ariadne --dry-run            # Rehearse consolidation, print proposed digests (server required)
-quilltap memories consolidate --character Ariadne [--max N]            # Queue a real consolidation job (server required)
+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` (AUTO / MANUAL / CONSOLIDATED), `--tier` (hot / cold; both by default, cold rows are starred in the `src` column), `--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), `--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; 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).
 
-`consolidate` folds clusters of near-duplicate hot memories into denser digests and sends the originals to the cold tier. It resolves `--character <name|id>` locally (required; `all` is rejected) and then asks the running server (`--port`, default 3000) — the model and embedding provider live there, not in the CLI. With `--dry-run` the server rehearses a bounded run (default 10 clusters, at most 40; `--max N` sets the bound, `--threshold 0..1` overrides the cluster similarity for this run), writes nothing, and the CLI prints each cluster as its member notes followed by the proposed digest(s), standalones, contradictions, and run stats. Without `--dry-run` it queues a background `MEMORY_CONSOLIDATION` job (`--max N` overrides `maxClustersPerRun`; a real run uses the stored settings, so `--threshold` is honoured only by dry runs) and prints the job id; manual runs ignore the master `enabled` switch. `--json` prints the raw API payload.
+Verbs that call the server (`grep --semantic`, `status`'s ledger, `maintain`, `validate --repair`) 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
 
@@ -359,7 +365,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
 
@@ -375,7 +383,7 @@ 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), `--port <n>` (default 3000), `--json`.
+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:
 
@@ -385,9 +393,17 @@ Tuning and comparable runs:
 
 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 Memory Gate reinforcement. It re-embeds the character's most recent memories with and without the anchor line, compares each against older rows, and reports how many would cross the reinforce (0.85) and near-duplicate (0.90) thresholds each way, plus a per-row table (rows that cross 0.85 only without anchors are highlighted). Read-only, but it costs embedding calls (roughly up to 7 per sampled row).
+`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
@@ -395,7 +411,11 @@ quilltap anchor-probe <characterId> --limit 20  # Smaller, cheaper sample
 quilltap anchor-probe <characterId> --json      # Raw JSON for scripting
 ```
 
-Flags: `--limit <n>` (1–200, default 50), `--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
 

package/bin/quilltap.js

@@ -592,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) {
@@ -766,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

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__/server-port-resolution.test.js

@@ -0,0 +1,122 @@
+/**
+ * Universal-flag parsing and server-port resolution for the HTTP diagnostic
+ * tools (anchor-probe, recall-replay, memory-diff).
+ *
+ * @jest-environment node
+ */
+
+'use strict';
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const { resolveServerPort } = require('../lock-helpers');
+const tools = {
+  'anchor-probe': require('../anchor-probe-command').parseFlags,
+  'recall-replay': require('../recall-replay-command').parseFlags,
+  'memory-diff': require('../memory-diff-command').parseFlags,
+};
+
+describe.each(Object.keys(tools))('%s flag parsing', (name) => {
+  const parseFlags = tools[name];
+
+  it.each([
+    [['--instance', 'V4test', 'ID']],
+    [['ID', '--instance', 'V4test']],
+    [['-i', 'V4test', 'ID']],
+    [['ID', '-i', 'V4test']],
+  ])('accepts the instance flag around the positional id (%j)', (args) => {
+    const { flags, positional } = parseFlags(args);
+    expect(flags.instance).toBe('V4test');
+    expect(positional).toEqual(['ID']);
+  });
+
+  it.each([
+    [['--data-dir', '/x/y', 'ID']],
+    [['ID', '-d', '/x/y']],
+  ])('accepts the data-dir flag (%j)', (args) => {
+    const { flags, positional } = parseFlags(args);
+    expect(flags.dataDir).toBe('/x/y');
+    expect(positional).toEqual(['ID']);
+  });
+
+  it('accepts --passphrase without treating its value as the id', () => {
+    const { positional } = parseFlags(['--passphrase', 'hunter2', 'ID']);
+    expect(positional).toEqual(['ID']);
+    expect(parseFlags(['ID', '--passphrase', 'hunter2']).positional).toEqual(['ID']);
+  });
+
+  it('leaves the port undefined unless --port is given', () => {
+    expect(parseFlags(['ID']).flags.port).toBeUndefined();
+    expect(parseFlags(['ID', '--port', '3005']).flags.port).toBe(3005);
+  });
+});
+
+describe('resolveServerPort', () => {
+  let root;
+  let lockPath;
+
+  function writeLock(overrides = {}) {
+    const now = new Date().toISOString();
+    fs.writeFileSync(lockPath, JSON.stringify({
+      pid: process.pid,
+      hostname: os.hostname(),
+      startedAt: now,
+      lastHeartbeat: now,
+      environment: 'local',
+      processTitle: 'node',
+      processArgv0: process.argv[0],
+      history: [],
+      ...overrides,
+    }));
+  }
+
+  beforeEach(() => {
+    root = fs.mkdtempSync(path.join(os.tmpdir(), 'qtap-port-test-'));
+    fs.mkdirSync(path.join(root, 'data'));
+    lockPath = path.join(root, 'data', 'quilltap.lock');
+  });
+
+  afterEach(() => fs.rmSync(root, { recursive: true, force: true }));
+
+  it('defaults to 3000 with no flags at all', () => {
+    expect(resolveServerPort({})).toMatchObject({ port: 3000, source: 'default', note: null });
+  });
+
+  it('lets an explicit --port win over a live lock', () => {
+    writeLock({ port: 3005 });
+    expect(resolveServerPort({ port: 4000, dataDir: root })).toMatchObject({ port: 4000, source: 'flag' });
+  });
+
+  it('uses the port from a live lock and says so', () => {
+    writeLock({ port: 3005 });
+    const r = resolveServerPort({ dataDir: root });
+    expect(r).toMatchObject({ port: 3005, source: 'lock' });
+    expect(r.note).toContain('3005');
+  });
+
+  it('falls back to 3000 when the live lock records no port', () => {
+    writeLock();
+    const r = resolveServerPort({ dataDir: root });
+    expect(r).toMatchObject({ port: 3000, source: 'default', note: null });
+    expect(r.hint).toContain('records no port');
+  });
+
+  it('ignores the port of a stale lock', () => {
+    writeLock({ pid: 2 ** 22 + 12345, port: 3005 });
+    const r = resolveServerPort({ dataDir: root });
+    expect(r.port).toBe(3000);
+    expect(r.hint).toContain('stale');
+  });
+
+  it('falls back to 3000 when there is no lock', () => {
+    const r = resolveServerPort({ dataDir: root });
+    expect(r.port).toBe(3000);
+    expect(r.hint).toContain('no instance lock');
+  });
+
+  it('rejects --instance together with --data-dir', () => {
+    expect(() => resolveServerPort({ instance: 'x', dataDir: root })).toThrow(/not both/);
+  });
+});