nlm-memory 0.20.0 → 0.21.0

package/dist/cli/nlm.js

@@ -22,11 +22,12 @@
  *   nlm disconnect claude-code — remove MCP block from ~/.mcp.json
  *   nlm disconnect codex       — remove Codex plugin
  *   nlm digest   — print a daily-activity digest (or --telegram to post)
+ *   nlm init     - print (or write) the agent recall contract snippet
  */
-import { fileURLToPath } from "node:url";
+import { fileURLToPath, pathToFileURL } from "node:url";
 import { dirname, resolve, join } from "node:path";
 import { homedir } from "node:os";
-import { mkdirSync, readFileSync, writeFileSync, existsSync, rmSync, copyFileSync } from "node:fs";
+import { mkdirSync, readFileSync, writeFileSync, existsSync, rmSync, copyFileSync, realpathSync, appendFileSync } from "node:fs";
 import { execFileSync, spawn, spawnSync } from "node:child_process";
 import { Command } from "commander";
 import pkg from "../../package.json" with { type: "json" };
@@ -40,12 +41,14 @@ import { PgStorage } from "../core/storage/pg-storage.js";
 import { applyPendingRestore, stageRestore } from "../core/storage/db-restore.js";
 import { listBackupDates, resolveBackup, runRollingBackup } from "../core/storage/backup-rotation.js";
 import { createApp } from "../http/app.js";
-import { createMcpServer } from "../mcp/server.js";
-import { ClassifierBox } from "../llm/classifier-box.js";
-import { DeepSeekClient } from "../llm/deepseek-client.js";
-import { OllamaClient } from "../llm/ollama-client.js";
-import { OllamaCodeEmbedder } from "../llm/ollama-code-embedder.js";
+import { createMcpServer, listMergeSuggestionsHandler, mergeWorkstreamsHandler, rebindSessionHandler, recallWorkstreamHandler, renameWorkstreamHandler, retireWorkstreamHandler } from "../mcp/server.js";
+import { classifierEgressNotice } from "../llm/classifier-egress.js";
+import { buildClassifier } from "../llm/build-classifier.js";
+import { OllamaCodeEmbedder, DEFAULT_CODE_EMBED_MODEL } from "../llm/ollama-code-embedder.js";
+import { OpenAICodeEmbedderClient } from "../llm/openai-code-embedder-client.js";
+import { resolveEmbedderInfo } from "../llm/embedder-info.js";
 import { autoloadEnv } from "../llm/env-autoload.js";
+import { buildEmbedder as _buildEmbedder } from "../llm/build-embedder.js";
 import { addHook, buildHookCommand, removeHook } from "../core/hook/claude-settings.js";
 import { codexBinaryAvailable, connectCodex, disconnectCodex, repairCodex, pluginScriptsDir, } from "../install/codex.js";
 import { connectClaudeCode, disconnectClaudeCode, installClaudeCodeHooks, mcpConfigPath } from "../install/claude-code.js";
@@ -56,6 +59,10 @@ import { embeddingModelPresent, ensureMcpToken, ollamaModelPresent } from "../in
 import { connectCursor, disconnectCursor } from "../install/cursor.js";
 import { describeRemove, describeUpsert, installCursorRules, installOpencodeRules, installWindsurfRules, uninstallCursorRules, uninstallOpencodeRules, uninstallWindsurfRules, } from "../install/rules-install.js";
 import { runSupersedeCommand } from "./supersede.js";
+import { runInitCommand } from "./init.js";
+import { runScopeBackfill, formatBackfillResult } from "./scope-backfill.js";
+import { runScopeCoverage, formatCoverageResult } from "./scope-coverage.js";
+import { loadAliasMap } from "../core/scope/alias-map.js";
 import { getUpdateStatus } from "../core/update-check/check.js";
 import { connectHermes, disconnectHermes, hermesConfigPath } from "../install/hermes.js";
 import { connectHermesAgent, disconnectHermesAgent, hermesAgentPluginDir } from "../install/hermes-agent.js";
@@ -64,8 +71,16 @@ import { connectPi, disconnectPi, piSettingsPath } from "../install/pi.js";
 import { runSetup } from "../install/setup.js";
 import { runParity } from "./classify-parity.js";
 import { reembedCorpus } from "../core/embedding/embed-backfill.js";
+import { reembedCorpusPg } from "../core/embedding/pg-embed-backfill.js";
+import { backfillExemplarEmbeddings } from "../core/exemplars/embed-backfill.js";
+import { warmCodeEmbedder } from "../core/exemplars/warm-embedder.js";
+import { markWarm } from "../core/health/warmup-state.js";
+import { setLaneHealth } from "../core/health/embedding-lane-state.js";
+import { setCorpusSnapshot, corpusSnapshot } from "../core/health/corpus-state.js";
+import { computeCorpusStats, sqliteCorpusStatsDeps, parseCorpusThresholds, thresholdState } from "../core/metrics/corpus-stats.js";
+import { computeReDerivationRate, sqliteReDerivationDeps } from "../core/metrics/re-derivation.js";
+import { reconcileLane } from "../core/embedding/embedding-config.js";
 import { backfillFacts } from "../core/facts/backfill-facts.js";
-import { normalizeEmbeddings } from "../core/embedding/embed-normalize.js";
 import { ScanScheduler } from "../core/scheduler/scheduler.js";
 import { MemoSweepScheduler } from "../core/hook/memo-sweep.js";
 import { isAgentLoaded, isBenignBootoutError } from "./launchctl-helpers.js";
@@ -75,14 +90,22 @@ import { applyEnvAssignment } from "./config-env.js";
 import { adapterFromSource } from "../core/adapters/from-source.js";
 import { runDigest } from "./digest.js";
 import { installScope } from "../core/signals/install-scope.js";
+import { buildWorkDigest } from "../core/work-digest/build-work-digest.js";
+import { composeWorkDigest } from "../core/work-digest/compose-work-digest.js";
+import { defaultTopicProvider, aliasTopicProvider } from "../core/work-digest/topics.js";
 import { runChecksOnSqlite, runChecksOnPg, applyFixOnSqlite, applyFixOnPg } from "../core/integrity/check-invariants.js";
+import { normalizeLabel } from "../core/workstream/model.js";
+import { resolveWorkstreamId } from "../core/workstream/resolve.js";
+import { suggestMerges } from "../core/entities/dedup-suggest.js";
+import { DEFAULT_NLM_PORT } from "../shared/net.js";
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 const MIGRATIONS_DIR = resolve(__dirname, "../../migrations");
+const CLASSIFIER_FIXTURES_DIR = resolve(__dirname, "../../fixtures/classifier-gold");
 const PG_MIGRATIONS_DIR = join(fileURLToPath(new URL(".", import.meta.url)), "../../migrations/pg");
 const UI_DIST = resolve(__dirname, "../../dist/ui");
 const DEFAULT_DB_PATH = resolve(homedir(), ".nlm/canonical.sqlite");
-const DEFAULT_PORT = 3940;
+const DEFAULT_PORT = Number.parseInt(DEFAULT_NLM_PORT, 10);
 function dbPath() {
     return process.env["NLM_DB_PATH"] ?? DEFAULT_DB_PATH;
 }
@@ -98,19 +121,121 @@ function port() {
 function ollamaUrl() {
     return process.env["NLM_OLLAMA_URL"] ?? "http://localhost:11434";
 }
-function buildClassifier() {
-    // qwen3.5:4b is the production classifier as of 2026-06-12 (NLM task #320).
-    // Scored 74.4% decision-precision vs qwen3:4b-instruct-2507-q4_K_M's 58.7% in
-    // the 2026-06-11 eval. Requires think:false (handled by ClassifierBox via
-    // classifierNeedsThinkDisabled) to stay within the 180s classify timeout.
-    // Ollama is the default to keep the daemon local-first and key-free; DeepSeek
-    // remains available via NLM_CLASSIFIER=deepseek for users who prioritize speed.
-    const provider = (process.env["NLM_CLASSIFIER"] ?? "ollama").toLowerCase();
-    if (provider !== "ollama")
+export function resolveDigestDate(date) {
+    if (date !== undefined) {
+        if (!/^\d{4}-\d{2}-\d{2}$/.test(date)) {
+            throw new Error(`invalid --date "${date}"; expected YYYY-MM-DD`);
+        }
+        return date;
+    }
+    const d = new Date();
+    const mo = String(d.getMonth() + 1).padStart(2, "0");
+    const da = String(d.getDate()).padStart(2, "0");
+    return `${d.getFullYear()}-${mo}-${da}`;
+}
+function workDigestEnv() {
+    const idle = Number.parseInt(process.env["NLM_WORK_IDLE_THRESHOLD_MIN"] ?? "5", 10);
+    const deep = Number.parseInt(process.env["NLM_WORK_DEEP_BLOCK_MIN"] ?? "25", 10);
+    return {
+        idleThresholdMin: Number.isFinite(idle) && idle > 0 ? idle : 5,
+        deepBlockMin: Number.isFinite(deep) && deep > 0 ? deep : 25,
+    };
+}
+const TREND_INTERVAL_MS = 7 * 24 * 60 * 60 * 1000;
+export function shouldAppendTrend(lastLineTs, now) {
+    if (lastLineTs === null)
+        return true;
+    const parsed = Date.parse(lastLineTs);
+    if (!Number.isFinite(parsed))
+        return true;
+    return now - parsed >= TREND_INTERVAL_MS;
+}
+function loadTopicProvider() {
+    try {
+        const raw = readFileSync(join(homedir(), ".nlm", "work-topics.json"), "utf8");
+        const map = JSON.parse(raw);
+        return aliasTopicProvider(map);
+    }
+    catch {
+        return defaultTopicProvider;
+    }
+}
+/** Build the recall/document embedder. Delegates to the shared factory in
+ *  src/llm/build-embedder.ts — see that file for provider routing details. */
+function buildEmbedder() {
+    return _buildEmbedder();
+}
+/** Build the code-lane embedder. Follows the same destination as the prose
+ *  embedder (NLM_EMBED_PROVIDER / NLM_EMBED_BASE_URL) but with its own model
+ *  (NLM_CODE_EMBED_MODEL, e.g. text-embedding-coderankembed on LM Studio).
+ *  Switching providers on existing exemplars requires `nlm embed-backfill
+ *  --exemplars`. */
+function buildCodeEmbedder() {
+    const provider = (process.env["NLM_EMBED_PROVIDER"] ?? "ollama").toLowerCase();
+    if (provider === "openai") {
         autoloadEnv();
-    const model = process.env["NLM_CLASSIFIER_MODEL"]
-        ?? (provider === "ollama" ? "qwen3.5:4b" : "deepseek-v4-flash");
-    return new ClassifierBox({ provider, model, ollamaUrl: ollamaUrl() });
+        const baseUrl = process.env["NLM_EMBED_BASE_URL"];
+        if (!baseUrl) {
+            throw new Error("NLM_EMBED_PROVIDER=openai requires NLM_EMBED_BASE_URL for the code embedder too, " +
+                "e.g. http://localhost:1234/v1 for LM Studio.");
+        }
+        return new OpenAICodeEmbedderClient({
+            baseUrl,
+            ...(process.env["NLM_CODE_EMBED_MODEL"] ? { model: process.env["NLM_CODE_EMBED_MODEL"] } : {}),
+            ...(process.env["NLM_EMBED_API_KEY"] ? { apiKey: process.env["NLM_EMBED_API_KEY"] } : {}),
+        });
+    }
+    // The bundled provider has no code-embedding engine (CodeRankEmbed has no ONNX equivalent
+    // in slice 1). Fall through to the Ollama default: the startup probe will fail soft and
+    // the code-exemplar lane stays unknown, which is the intended degradation.
+    return new OllamaCodeEmbedder({ baseUrl: ollamaUrl() });
+}
+async function reconcileEmbeddingLanes(storage, embedder, codeEmbedder) {
+    const configStore = storage.embeddingConfig;
+    if (!configStore)
+        return;
+    const nowIso = new Date().toISOString();
+    try {
+        const result = await embedder.embed("nlm dimension probe", "query");
+        const dim = result.vector.length;
+        const info = resolveEmbedderInfo(process.env, dim);
+        const runtime = { lane: "prose", provider: info.provider, model: info.model, dim };
+        const rec = reconcileLane(configStore, runtime, nowIso);
+        if (rec.state === "stale") {
+            const stored = rec.stored;
+            console.error(`nlm-memory: prose embedding lane stale: stored ${stored.provider}/${stored.model}@${stored.dim}` +
+                ` vs runtime ${info.provider}/${info.model}@${dim}; run \`nlm embed-backfill\` to re-embed`);
+            setLaneHealth("prose", "stale");
+        }
+        else {
+            setLaneHealth("prose", "ok");
+        }
+    }
+    catch {
+        // probe failure; prose lane stays unknown
+    }
+    if (process.env["NLM_CODE_EXEMPLARS_ENABLED"] !== "1")
+        return;
+    try {
+        const result = await codeEmbedder.embed("nlm dimension probe", "query");
+        const dim = result.dim;
+        const provider = (process.env["NLM_EMBED_PROVIDER"] ?? "ollama").toLowerCase();
+        const model = process.env["NLM_CODE_EMBED_MODEL"] ?? DEFAULT_CODE_EMBED_MODEL;
+        const runtime = { lane: "code", provider, model, dim };
+        const rec = reconcileLane(configStore, runtime, nowIso);
+        if (rec.state === "stale") {
+            const stored = rec.stored;
+            console.error(`nlm-memory: code embedding lane stale: stored ${stored.provider}/${stored.model}@${stored.dim}` +
+                ` vs runtime ${provider}/${model}@${dim}; run \`nlm embed-backfill --exemplars\` to re-embed`);
+            setLaneHealth("code", "stale");
+        }
+        else {
+            setLaneHealth("code", "ok");
+        }
+    }
+    catch {
+        // probe failure; code lane stays unknown
+    }
 }
 async function buildAdapters(sources) {
     // Sources table is the source of truth. Each enabled row maps to one
@@ -172,21 +297,56 @@ async function buildStack() {
     // seedDefaults (not on ProviderRegistryPort), so this narrows to the SQLite case.
     if (providers instanceof ProviderRegistry)
         await providers.seedDefaults();
-    // Recall only uses embed(). Embeddings live on Ollama; DeepSeek doesn't
-    // expose them. Classifier is wired separately for Phase D ingest.
-    const embedder = new OllamaClient({ baseUrl: ollamaUrl() });
+    // Recall only uses embed(). Default embedder is local Ollama; NLM_EMBED_*
+    // can point it at any OpenAI-compatible endpoint. Classifier is wired
+    // separately for Phase D ingest.
+    const embedder = buildEmbedder();
     const classifier = buildClassifier();
+    const wsStore = storage.workstreams;
     const recall = new RecallService({
         store,
         llm: embedder,
         factStore: facts,
         exemplarStore: storage.exemplars,
-        codeEmbedder: new OllamaCodeEmbedder({ baseUrl: ollamaUrl() }),
+        codeEmbedder: buildCodeEmbedder(),
         installScope: scope,
+        resolveWorkstreamMembers: async (idOrLabel) => {
+            const all = await wsStore.listAll();
+            const byId = new Map(all.map((w) => [w.id, { id: w.id, mergedInto: w.mergedInto }]));
+            const target = all.find((w) => w.id === idOrLabel)
+                ?? all.find((w) => normalizeLabel(w.label) === normalizeLabel(idOrLabel));
+            if (!target)
+                return [];
+            const survivor = resolveWorkstreamId(target.id, byId);
+            return all.filter((w) => resolveWorkstreamId(w.id, byId) === survivor).map((w) => w.id);
+        },
     });
     const factRecall = new FactRecallService({ factStore: facts, llm: embedder });
     return { storage, store, facts, signals, scope, sources, providers, recall, factRecall, embedder, classifier };
 }
+export async function runClassifierEvalCommand(deps) {
+    const { runClassifierFixtureEval } = await import("../core/eval/classifier-fixture-eval.js");
+    const result = await runClassifierFixtureEval(deps.classify, deps.fixturesDir, deps.limit !== undefined ? { limit: deps.limit } : undefined);
+    if (deps.json) {
+        deps.stdout(JSON.stringify({ ...result, provider: deps.provider, model: deps.model }, null, 2) + "\n");
+        return;
+    }
+    const a = result.aggregate;
+    const pct = (n) => `${(n * 100).toFixed(1)}%`;
+    deps.stdout(`lane: ${deps.provider}/${deps.model}\n`);
+    deps.stdout(`n=${result.perTranscript.length}\n`);
+    deps.stdout(`schema-valid:     ${pct(a.schemaValidRate)}\n`);
+    deps.stdout(`label-accuracy:   ${pct(a.labelAccuracy)}\n`);
+    deps.stdout(`entity-F1:        ${pct(a.entityF1)}\n`);
+    deps.stdout(`decision-F1:      ${pct(a.decisionF1)}\n`);
+    deps.stdout(`conf-calibration: ${pct(a.confidenceCalibrationRate)}\n`);
+    deps.stdout(`p50-latency:      ${a.p50LatencyMs}ms\n`);
+    deps.stdout(`p95-latency:      ${a.p95LatencyMs}ms\n`);
+    if (a.timedOutOrUnreachable > 0) {
+        deps.stdout(`timed-out:        ${a.timedOutOrUnreachable} fixture(s) scored as failures (LLM unreachable/timeout)\n`);
+    }
+    deps.stdout(`see: docs/classifier-tiers.md\n`);
+}
 const program = new Command();
 program
     .name("nlm")
@@ -208,6 +368,7 @@ program
     const { storage, store, facts, signals, scope, sources, providers, recall, factRecall, embedder, classifier } = await buildStack();
     const { existsSync } = await import("node:fs");
     const hasMcpToken = Boolean(process.env["NLM_MCP_TOKEN"]);
+    const codeEmb = buildCodeEmbedder();
     const app = createApp({
         recall,
         store,
@@ -223,15 +384,19 @@ program
             embedder,
             store,
             ...(facts ? { factStore: facts } : {}),
+            classifierDescriptor: { provider: classifier.provider, model: classifier.model },
         },
         signalStore: signals,
         installScope: scope,
+        // Signal scope inheritance (NLM_SCOPE_STAMP): a signal with only a
+        // session_id inherits that session's stamped scope at ingest.
+        sessionScopeReader: store,
         // Code-exemplar lane. The store + code embedder are always wired; the
         // NLM_CODE_EXEMPLARS_ENABLED flag gates capture (POST /api/signal) and
         // the /api/exemplar + /api/recall-code routes at request time.
         exemplarStore: storage.exemplars,
-        codeEmbedder: new OllamaCodeEmbedder({ baseUrl: ollamaUrl() }),
-        embedderInfo: { provider: "ollama", model: "nomic-embed-text", dims: 768 },
+        codeEmbedder: codeEmb,
+        embedderInfo: resolveEmbedderInfo(),
         ...(existsSync(UI_DIST) ? { uiDist: UI_DIST } : {}),
         // Wire POST /mcp only when NLM_MCP_TOKEN is present. Absent = route never
         // mounts, zero attack surface. Present = token-gated Streamable-HTTP MCP
@@ -246,12 +411,28 @@ program
                     // Parity with the stdio `nlm mcp` server: remote/container MCP
                     // clients hitting POST /mcp get recall_code too when the flag is on.
                     exemplarStore: storage.exemplars,
-                    codeEmbedder: new OllamaCodeEmbedder({ baseUrl: ollamaUrl() }),
+                    codeEmbedder: codeEmb,
                     installScope: scope,
+                    signalStore: signals,
+                    sessionScopeReader: store,
+                    workDigest: { store, topicProvider: loadTopicProvider(), workstreams: storage.workstreams, ...workDigestEnv() },
+                    workstreams: { store: storage.workstreams, sessions: store, facts: facts, exemplars: storage.exemplars },
                 },
             }
             : {}),
     });
+    warmCodeEmbedder(codeEmb);
+    void reconcileEmbeddingLanes(storage, embedder, codeEmb).catch(() => { });
+    void embedder
+        .embed("warmup init", "query")
+        .then(() => markWarm("textEmbedder"))
+        .catch(() => { });
+    setImmediate(() => {
+        void recall
+            .search({ query: "warmup init", mode: "keyword", limit: 1 })
+            .then(() => markWarm("fts5"))
+            .catch(() => { });
+    });
     const p = port();
     serve({ fetch: app.fetch, port: p, hostname: "127.0.0.1" }, (info) => {
         console.error(`nlm-memory http listening on http://localhost:${info.port}`);
@@ -260,6 +441,14 @@ program
         }
         console.error(`  db:     ${dbPath()}`);
         console.error(`  ollama: ${ollamaUrl()}`);
+        const classifier = (process.env["NLM_CLASSIFIER"] ?? "ollama").toLowerCase();
+        const egress = classifierEgressNotice(classifier, process.env["NLM_CLASSIFIER_BASE_URL"]);
+        const classifyTarget = classifier === "openai" && process.env["NLM_CLASSIFIER_BASE_URL"]
+            ? `${classifier} (${process.env["NLM_CLASSIFIER_BASE_URL"]})`
+            : classifier;
+        console.error(`  classify: ${classifyTarget} [${egress ? "cloud egress" : "local"}]`);
+        if (egress)
+            console.error(`  notice: ${egress}`);
         // Passive update notice. Fire-and-forget so a slow npm registry
         // round-trip can't delay the startup banner; surfaced only when
         // strictly behind. See src/core/update-check/check.ts for the
@@ -306,6 +495,61 @@ program
         void signals.pruneOlderThan(cutoff).catch(() => { });
     }, SIGNAL_PRUNE_INTERVAL_MS);
     signalPruneTimer.unref();
+    // Corpus monitor: 24h stats job + weekly re-derivation trend. SQLite only.
+    // First run is delayed ~60s so warmup finishes first; then repeats every 24h.
+    if (!(storage instanceof PgStorage)) {
+        const CORPUS_MONITOR_INTERVAL_MS = 24 * 60 * 60 * 1000;
+        const CORPUS_MONITOR_INITIAL_DELAY_MS = 60 * 1000;
+        const nlmDataDir = join(homedir(), ".nlm");
+        const corpusStatsPath = join(nlmDataDir, "corpus-stats.jsonl");
+        const rederivTrendPath = join(nlmDataDir, "re-derivation-trend.jsonl");
+        const runCorpusMonitor = async () => {
+            try {
+                const sqliteStorage = storage;
+                const rawDb = sqliteStorage.rawDb();
+                const deps = sqliteCorpusStatsDeps(rawDb, dbPath());
+                const stats = await computeCorpusStats(deps);
+                const thresholds = parseCorpusThresholds(process.env);
+                const state = thresholdState(stats.dbBytes, thresholds);
+                const ts = new Date().toISOString();
+                // hapaxEntities derives from the denormalized entities.session_count column,
+                // which drifts (~6% today) until the entity-merge primitive recomputes counts
+                // exactly. This is a monitoring approximation, not ground truth.
+                const snap = { ...stats, state, lastComputedAt: ts };
+                setCorpusSnapshot(snap);
+                mkdirSync(nlmDataDir, { recursive: true });
+                appendFileSync(corpusStatsPath, JSON.stringify({ ts, ...stats, state }) + "\n", "utf8");
+                if (state === "warn" || state === "alert") {
+                    console.error(`[corpus-monitor] ${state}: db is ${stats.dbBytes} bytes`);
+                }
+                const now = Date.now();
+                let lastTrendTs = null;
+                try {
+                    const trendContent = readFileSync(rederivTrendPath, "utf8");
+                    const lines = trendContent.split("\n").filter(Boolean);
+                    const lastLine = lines[lines.length - 1];
+                    if (lastLine) {
+                        const parsed = JSON.parse(lastLine);
+                        lastTrendTs = typeof parsed.ts === "string" ? parsed.ts : null;
+                    }
+                }
+                catch {
+                    // file absent or unreadable; treat as no prior entry
+                }
+                if (shouldAppendTrend(lastTrendTs, now)) {
+                    const rdDeps = sqliteReDerivationDeps(rawDb);
+                    const report = await computeReDerivationRate(rdDeps, 42);
+                    appendFileSync(rederivTrendPath, JSON.stringify({ ts, windowDays: 42, rate: report.rate, pairCount: report.pairs.length, eligible: report.eligible }) + "\n", "utf8");
+                }
+            }
+            catch (e) {
+                console.error(`[corpus-monitor] error: ${e instanceof Error ? e.message : String(e)}`);
+            }
+        };
+        const corpusMonitorTimer = setInterval(() => { void runCorpusMonitor(); }, CORPUS_MONITOR_INTERVAL_MS);
+        corpusMonitorTimer.unref();
+        setTimeout(() => { void runCorpusMonitor(); }, CORPUS_MONITOR_INITIAL_DELAY_MS).unref();
+    }
     // Memo sweep runs independently of the transcript scheduler — it's the
     // backstop for SessionEnd hook unreliability (crashes, kill -9, IDE
     // force-close don't fire SessionEnd, so memo files would otherwise
@@ -329,7 +573,9 @@ program
                 installScope: scope,
                 intervalMs: opts.intervalMin * 60_000,
                 exemplarStore: storage.exemplars,
-                codeEmbedder: new OllamaCodeEmbedder({ baseUrl: ollamaUrl() }),
+                codeEmbedder: buildCodeEmbedder(),
+                workstreams: storage.workstreams,
+                classifierDescriptor: { provider: classifier.provider, model: classifier.model },
             });
             scheduler.start();
             console.error(`  scheduler: ${adapters.map((a) => a.name).join(", ")} every ${opts.intervalMin}m`);
@@ -368,6 +614,7 @@ program
     .option("-k, --kind <kind>", "filter by marker kind (decision|open)")
     .option("-m, --mode <mode>", "recall mode: keyword, semantic, or hybrid (default: keyword)", "keyword")
     .option("-l, --limit <n>", "max results", (v) => Number.parseInt(v, 10), 10)
+    .option("-w, --workstream <idOrLabel>", "filter by workstream (id or label; merge chains resolve)")
     .option("--json", "emit the raw JSON result instead of rendered lines")
     .action(async (query, opts) => {
     const { storage, recall } = await buildStack();
@@ -381,6 +628,7 @@ program
             includeSuperseded: true,
             ...(opts.entity ? { entity: opts.entity } : {}),
             ...(opts.kind ? { kind: opts.kind } : {}),
+            ...(opts.workstream ? { workstream: opts.workstream } : {}),
         });
         if (opts.json) {
             process.stdout.write(JSON.stringify(result, null, 2) + "\n");
@@ -398,6 +646,149 @@ program
         await storage.close();
     }
 });
+program
+    .command("recall-workstream")
+    .description("Recall a workstream's accumulated context (id or label)")
+    .argument("<idOrLabel>", "workstream id or label")
+    .action(async (idOrLabel) => {
+    const { storage, store } = await buildStack();
+    try {
+        const r = await recallWorkstreamHandler({ recall: {}, store, workstreams: { store: storage.workstreams, sessions: store, facts: storage.facts, exemplars: storage.exemplars } }, { idOrLabel });
+        process.stdout.write(r.content[0].text + "\n");
+    }
+    finally {
+        await storage.close();
+    }
+});
+program
+    .command("rebind-session")
+    .description("Rebind a session to a workstream (operator correction)")
+    .argument("<sessionId>", "session id")
+    .argument("<workstream>", "target workstream id or label")
+    .action(async (sessionId, workstream) => {
+    const { storage, store } = await buildStack();
+    try {
+        const r = await rebindSessionHandler({ recall: {}, store, workstreams: { store: storage.workstreams, sessions: store, facts: storage.facts, exemplars: storage.exemplars } }, { sessionId, workstream });
+        process.stdout.write(r.content[0].text + "\n");
+    }
+    finally {
+        await storage.close();
+    }
+});
+program
+    .command("merge-workstreams")
+    .description("Merge a duplicate workstream into the one to keep")
+    .argument("<from>", "duplicate workstream id or label")
+    .argument("<into>", "survivor workstream id or label")
+    .action(async (from, into) => {
+    const { storage, store } = await buildStack();
+    try {
+        const r = await mergeWorkstreamsHandler({ recall: {}, store, workstreams: { store: storage.workstreams, sessions: store, facts: storage.facts, exemplars: storage.exemplars } }, { from, into });
+        process.stdout.write(r.content[0].text + "\n");
+    }
+    finally {
+        await storage.close();
+    }
+});
+program
+    .command("rename-workstream")
+    .description("Rename a workstream")
+    .argument("<idOrLabel>", "workstream id or current label")
+    .argument("<label>", "new label")
+    .action(async (idOrLabel, label) => {
+    const { storage, store } = await buildStack();
+    try {
+        const r = await renameWorkstreamHandler({ recall: {}, store, workstreams: { store: storage.workstreams, sessions: store, facts: storage.facts, exemplars: storage.exemplars } }, { idOrLabel, label });
+        process.stdout.write(r.content[0].text + "\n");
+    }
+    finally {
+        await storage.close();
+    }
+});
+program
+    .command("retire-workstream")
+    .description("Retire (mark dead) a workstream")
+    .argument("<idOrLabel>", "workstream id or label")
+    .action(async (idOrLabel) => {
+    const { storage, store } = await buildStack();
+    try {
+        const r = await retireWorkstreamHandler({ recall: {}, store, workstreams: { store: storage.workstreams, sessions: store, facts: storage.facts, exemplars: storage.exemplars } }, { idOrLabel });
+        process.stdout.write(r.content[0].text + "\n");
+    }
+    finally {
+        await storage.close();
+    }
+});
+program
+    .command("merge-suggestions")
+    .description("List likely-duplicate workstreams to merge")
+    .option("-m, --min-score <n>", "minimum similarity score 0..1", "0.5")
+    .action(async (opts) => {
+    const minScore = Number(opts.minScore);
+    if (!Number.isFinite(minScore)) {
+        process.stderr.write(`nlm: invalid --min-score "${opts.minScore}" (expected a number 0..1)\n`);
+        process.exitCode = 1;
+        return;
+    }
+    const { storage, store } = await buildStack();
+    try {
+        const r = await listMergeSuggestionsHandler({ recall: {}, store, workstreams: { store: storage.workstreams, sessions: store, facts: storage.facts, exemplars: storage.exemplars } }, { minScore });
+        process.stdout.write(r.content[0].text + "\n");
+    }
+    finally {
+        await storage.close();
+    }
+});
+program
+    .command("eval")
+    .description("Evaluate recall quality (--queries) or classifier extraction quality (--classifier)")
+    .option("--queries <file>", "JSON file: [{ query, expectedIds }]")
+    .option("--classifier", "benchmark the configured classifier lane against shipped gold fixtures")
+    .option("--limit <n>", "run only the first N fixtures (classifier mode)", (v) => Number.parseInt(v, 10))
+    .option("--mode <mode>", "keyword | semantic | hybrid (queries mode)", "keyword")
+    .option("--json", "emit JSON instead of a table")
+    .action(async (opts) => {
+    if (opts.classifier) {
+        const stack = await buildStack();
+        try {
+            const limitVal = opts.limit;
+            await runClassifierEvalCommand({
+                classify: (t) => stack.classifier.classify(t),
+                provider: stack.classifier.provider,
+                model: stack.classifier.model,
+                fixturesDir: CLASSIFIER_FIXTURES_DIR,
+                ...(limitVal !== undefined ? { limit: limitVal } : {}),
+                json: Boolean(opts.json),
+                stdout: (s) => { process.stdout.write(s); },
+            });
+        }
+        finally {
+            await stack.storage.close();
+        }
+        return;
+    }
+    if (!opts.queries) {
+        process.stderr.write("error: required option '--queries <file>' not specified\n");
+        process.exitCode = 1;
+        return;
+    }
+    const { readFile } = await import("node:fs/promises");
+    const queries = JSON.parse(await readFile(opts.queries, "utf8"));
+    const { runEval } = await import("../core/eval/run-eval.js");
+    const { storage, recall } = await buildStack();
+    try {
+        const report = await runEval({ recall }, queries, { mode: opts.mode, k: 5 });
+        if (opts.json) {
+            process.stdout.write(JSON.stringify(report, null, 2) + "\n");
+            return;
+        }
+        process.stdout.write(`mode=${report.mode} n=${report.n} R@1=${(report.rAt1 * 100).toFixed(1)}% ` +
+            `R@5=${(report.rAt5 * 100).toFixed(1)}% MRR=${report.mrr.toFixed(3)}\n`);
+    }
+    finally {
+        await storage.close();
+    }
+});
 program
     .command("recall-code")
     .description("Semantic search over code exemplars (requires NLM_CODE_EXEMPLARS_ENABLED=1)")
@@ -413,11 +804,10 @@ program
         process.exit(1);
     }
     const { storage } = await buildStack();
-    const { OllamaCodeEmbedder } = await import("../llm/ollama-code-embedder.js");
     const { recallCode } = await import("../core/exemplars/recall-code.js");
     const { installScope: getScope } = await import("../core/signals/install-scope.js");
     try {
-        const embedder = new OllamaCodeEmbedder();
+        const embedder = buildCodeEmbedder();
         const result = await recallCode({
             query,
             installScope: getScope(),
@@ -450,6 +840,48 @@ program
         await storage.close();
     }
 });
+program
+    .command("code-signal")
+    .description("Emit a PATH-(b) code signal for a commit (deterministic pass/fail exemplar). Best-effort: never blocks a commit.")
+    .requiredOption("--repo-path <dir>", "path to the git repo whose commit to capture")
+    .requiredOption("--sha <sha>", "commit sha to extract the diff from")
+    .requiredOption("--test-exit <n>", "test gate exit code (0 -> pass, non-zero -> fail)", (v) => Number.parseInt(v, 10))
+    .option("--task <s>", "task description (defaults to the changed funcname/file)")
+    .option("--model <s>", "model that produced the change")
+    .option("--repo <logical>", "logical repo name (defaults to the repo-path basename)")
+    .option("--dry-run", "print the payload and do not POST")
+    .action(async (opts) => {
+    const { buildCodeSignalPayload, formatCodeSignalResult } = await import("../core/signals/code-signal.js");
+    const payload = buildCodeSignalPayload({
+        repoPath: opts.repoPath,
+        sha: opts.sha,
+        testExit: opts.testExit,
+        ...(opts.task ? { task: opts.task } : {}),
+        ...(opts.model ? { model: opts.model } : {}),
+        ...(opts.repo ? { repo: opts.repo } : {}),
+    });
+    if (opts.dryRun) {
+        process.stdout.write(JSON.stringify(payload, null, 2) + "\n");
+        return;
+    }
+    const url = `http://localhost:${port()}/api/signal`;
+    try {
+        const res = await fetch(url, {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify(payload),
+        });
+        if (res.status !== 202) {
+            process.stderr.write(`code-signal: daemon returned ${res.status} (not 202); skipping\n`);
+            return;
+        }
+        const accepted = (await res.json());
+        process.stdout.write(formatCodeSignalResult(payload.outcome, accepted.id ?? "unknown") + "\n");
+    }
+    catch {
+        process.stderr.write(`code-signal: daemon unreachable at ${url}; skipping\n`);
+    }
+});
 program
     .command("misses")
     .description("Show sessions the agent explicitly fetched but the hook never surfaced (recall miss log)")
@@ -532,6 +964,43 @@ program
         }
     }
 });
+program
+    .command("metrics")
+    .description("Read-only retrieval-quality metrics")
+    .argument("<name>", "metric name: re-derivation")
+    .option("--window <days>", "lookback window in days", (v) => Number.parseInt(v, 10), 90)
+    .option("--json", "emit JSON instead of human-readable output")
+    .action(async (name, opts) => {
+    if (name !== "re-derivation") {
+        console.error(`unknown metric '${name}' (available: re-derivation)`);
+        process.exitCode = 1;
+        return;
+    }
+    const { computeReDerivationRate, sqliteReDerivationDeps } = await import("../core/metrics/re-derivation.js");
+    const { storage, store } = await buildStack();
+    try {
+        if (typeof store.rawDb !== "function") {
+            console.error("re-derivation metric requires the SQLite backend");
+            process.exitCode = 1;
+            return;
+        }
+        const deps = sqliteReDerivationDeps(store.rawDb());
+        const report = await computeReDerivationRate(deps, opts.window);
+        if (opts.json) {
+            process.stdout.write(JSON.stringify(report, null, 2) + "\n");
+            return;
+        }
+        const pct = (report.rate * 100).toFixed(1);
+        console.log(`re_derivation_rate (last ${opts.window} day(s)): ${pct}%  ` +
+            `(${report.pairs.length} re-derived pair${report.pairs.length === 1 ? "" : "s"})`);
+        for (const p of report.pairs) {
+            console.log(`  ${p.a} <-> ${p.b}  jaccard=${p.jaccard}  shared=${p.sharedEntities.join(", ")}`);
+        }
+    }
+    finally {
+        await storage.close();
+    }
+});
 program
     .command("supersede")
     .description("Retroactively mark a session as superseded by a newer one")
@@ -572,12 +1041,39 @@ program
     .description("Re-embed every session into session_embedding_chunks (chunk + max-pool)")
     .option("-l, --limit <n>", "session cap (default: all)", (v) => Number.parseInt(v, 10))
     .option("--state <path>", "resume state file (default ~/.nlm/embed_reembed.state)")
+    .option("--exemplars", "instead: embed code_exemplars rows missing a vector (repairs dropped capture embeds)")
+    .option("--dry-run", "report dim mismatch and what would be dropped without writing")
     .option("-v, --verbose", "per-session progress on stderr")
     .action(async (opts) => {
-    const embedder = new OllamaClient({ baseUrl: ollamaUrl() });
-    const report = await reembedCorpus({
-        dbPath: dbPath(),
+    if (opts.exemplars) {
+        const { storage } = await buildStack();
+        try {
+            const report = await backfillExemplarEmbeddings({
+                dbPath: dbPath(),
+                embedder: buildCodeEmbedder(),
+                store: storage.exemplars,
+                ...(opts.limit ? { limit: opts.limit } : {}),
+                ...(opts.verbose
+                    ? {
+                        onProgress: (i, n, id, status) => {
+                            process.stderr.write(`  [${i}/${n}] ${id}  ${status}\n`);
+                        },
+                    }
+                    : {}),
+            });
+            process.stdout.write(JSON.stringify(report, null, 2) + "\n");
+        }
+        finally {
+            await storage.close();
+        }
+        return;
+    }
+    const embedder = buildEmbedder();
+    const pgUrl = process.env["NLM_PG_URL"];
+    const sharedOpts = {
         embedder,
+        embedderProvider: resolveEmbedderInfo(process.env).provider,
+        ...(opts.dryRun ? { dryRun: true } : {}),
         ...(opts.state ? { statePath: opts.state } : {}),
         ...(opts.limit ? { limit: opts.limit } : {}),
         ...(opts.verbose
@@ -587,7 +1083,10 @@ program
                 },
             }
             : {}),
-    });
+    };
+    const report = pgUrl
+        ? await reembedCorpusPg({ pgUrl, ...sharedOpts })
+        : await reembedCorpus({ dbPath: dbPath(), ...sharedOpts });
     process.stdout.write(JSON.stringify(report, null, 2) + "\n");
 });
 program
@@ -649,6 +1148,7 @@ program
             factStore: stack.storage.facts,
             embedder: stack.embedder,
             classifier: stack.classifier,
+            classifierDescriptor: { provider: stack.classifier.provider, model: stack.classifier.model },
             adapters,
         }, { ...(opts.limit ? { limit: opts.limit } : {}), dryRun: Boolean(opts.dryRun) });
         console.log(`reclassify-oversized: attempted=${r.attempted} ingested=${r.ingested} ` +
@@ -660,33 +1160,108 @@ program
     }
 });
 program
-    .command("embed-normalize")
-    .description("L2-normalize every row in session_embeddings (idempotent)")
-    .option("--dim <n>", "vector dimension (default 768)", (v) => Number.parseInt(v, 10), 768)
-    .option("--batch <n>", "rows per commit batch (default 100)", (v) => Number.parseInt(v, 10), 100)
-    .option("--dry-run", "report what would change without writing")
-    .action((opts) => {
-    const report = normalizeEmbeddings({
-        dbPath: dbPath(),
-        dim: opts.dim,
-        batchSize: opts.batch,
-        dryRun: Boolean(opts.dryRun),
-    });
-    process.stdout.write(JSON.stringify(report, null, 2) + "\n");
+    .command("reprocess")
+    .description("Retroactive: re-classify sessions that lack classification or were classified by a weaker lane.\n" +
+    "Workstream binding (workstream_id) is NOT changed by this command.\n" +
+    "Below-floor results (<0.4 confidence) update the session row but preserve its prior facts.")
+    .option("-l, --limit <n>", "max sessions to process this run", (v) => Number.parseInt(v, 10))
+    .option("--min-confidence <f>", "also reprocess same-model sessions below this confidence", (v) => Number.parseFloat(v))
+    .option("--only-null", "select only sessions with no classifier stamp yet (safe lane-switch resume: sessions already stamped by a stronger model are left untouched)")
+    .option("--exclude-model <tag>", "exclude sessions stamped by this model tag (repeatable; use once per model to preserve corpus quality when switching classifier lanes)", (v, prev) => [...prev, v], [])
+    .option("--state <path>", "resume state file (default ~/.nlm/reprocess.state)")
+    .option("--dry-run", "print cohort report without writing")
+    .option("-v, --verbose", "per-session progress on stderr")
+    .option("--force-embed", "proceed even when the stored prose embedding lane mismatches the runtime embedder")
+    .action(async (opts) => {
+    const { reprocess: runReprocess } = await import("../core/ingest/reprocess.js");
+    const stack = await buildStack();
+    try {
+        if (!(stack.storage instanceof SqliteStorage)) {
+            console.error("reprocess: only supported with SQLite storage (NLM_PG_URL must not be set)");
+            await stack.storage.close();
+            process.exit(1);
+        }
+        const embedderInfo = resolveEmbedderInfo();
+        const report = await runReprocess({
+            db: stack.storage.rawDb(),
+            store: stack.storage.sessions,
+            factStore: stack.storage.facts,
+            embedder: stack.embedder,
+            classifier: stack.classifier,
+            classifierDescriptor: { provider: stack.classifier.provider, model: stack.classifier.model },
+            embeddingConfig: stack.storage.embeddingConfig,
+            embedderDescriptor: { provider: embedderInfo.provider, model: embedderInfo.model },
+        }, {
+            ...(opts.limit ? { limit: opts.limit } : {}),
+            ...(opts.minConfidence !== undefined ? { minConfidence: opts.minConfidence } : {}),
+            ...(opts.onlyNull ? { onlyNull: true } : {}),
+            ...(opts.excludeModel && opts.excludeModel.length > 0 ? { excludeModels: opts.excludeModel } : {}),
+            ...(opts.state ? { statePath: opts.state } : {}),
+            dryRun: Boolean(opts.dryRun),
+            verbose: Boolean(opts.verbose),
+            forceEmbed: Boolean(opts.forceEmbed),
+            ...(opts.verbose
+                ? {
+                    onProgress: (i, n, sid, status) => {
+                        process.stderr.write(`  [${i}/${n}] ${sid}  ${status}\n`);
+                    },
+                }
+                : {}),
+        });
+        process.stdout.write(JSON.stringify(report, null, 2) + "\n");
+    }
+    finally {
+        await stack.storage.close();
+    }
+});
+program
+    .command("backfill-derivables")
+    .description("Retroactive: stamp agent_persona + parent_session_id (#352 phase 2) onto sessions ingested\n" +
+    "before the scheduler started stamping them at classify time. Idempotent (WHERE agent_persona IS NULL).")
+    .option("--dry-run", "report counts without writing")
+    .option("--with-transcript-scan", "also scan each candidate's transcript for primary_model/total_tokens/skill (slower)")
+    .action(async (opts) => {
+    const { backfillDerivables } = await import("../core/ingest/backfill-derivables.js");
+    const stack = await buildStack();
+    try {
+        if (!(stack.storage instanceof SqliteStorage)) {
+            console.error("backfill-derivables: only supported with SQLite storage (NLM_PG_URL must not be set)");
+            await stack.storage.close();
+            process.exit(1);
+        }
+        const report = await backfillDerivables(stack.storage.rawDb(), {
+            dryRun: Boolean(opts.dryRun),
+            withTranscriptScan: Boolean(opts.withTranscriptScan),
+        });
+        console.log(`backfill-derivables${opts.dryRun ? " (dry-run)" : ""}: ` +
+            `updated=${report.updated} skipped(already-stamped)=${report.skippedAlreadyStamped} ` +
+            `skipped(no-op)=${report.skippedNoop} subagent-candidates=${report.subagentCandidates} ` +
+            `unknown-parent=${report.unknownParent} transcript-scanned=${report.transcriptScanned} total=${report.total}`);
+    }
+    finally {
+        await stack.storage.close();
+    }
 });
 program
     .command("mcp")
     .description("Run as an MCP stdio server (for ~/.mcp.json)")
     .action(async () => {
-    const { recall, store, facts, factRecall, storage, scope } = await buildStack();
+    const { recall, store, facts, factRecall, storage, scope, signals } = await buildStack();
     const server = createMcpServer({
         recall,
         store,
         factStore: facts,
         factRecall,
         exemplarStore: storage.exemplars,
-        codeEmbedder: new OllamaCodeEmbedder({ baseUrl: ollamaUrl() }),
+        codeEmbedder: buildCodeEmbedder(),
         installScope: scope,
+        signalStore: signals,
+        sessionScopeReader: store,
+        workDigest: { store, topicProvider: loadTopicProvider(), workstreams: storage.workstreams, ...workDigestEnv() },
+        workstreams: { store: storage.workstreams, sessions: store, facts: facts, exemplars: storage.exemplars },
+        // Tier-B outcome rollup (#352 phase 2) only has a SQLite adapter today;
+        // PgStorage deployments skip get_session's `outcome` field until parity lands.
+        ...(storage instanceof SqliteStorage ? { outcomeDb: storage.rawDb() } : {}),
     });
     const transport = new StdioServerTransport();
     await server.connect(transport);
@@ -1074,14 +1649,12 @@ const SESSION_START_HOOK_JS = resolve(__dirname, "../hook/session-start-hook.js"
 const SESSION_END_HOOK_JS = resolve(__dirname, "../hook/session-end-hook.js");
 const STOP_HOOK_JS = resolve(__dirname, "../hook/stop-hook.js");
 const PRE_COMPACT_HOOK_JS = resolve(__dirname, "../hook/pre-compact-hook.js");
-const SUBAGENT_START_HOOK_JS = resolve(__dirname, "../hook/subagent-start-hook.js");
 const ALL_HOOKS = [
     { event: "UserPromptSubmit", script: HOOK_JS, label: "recall" },
     { event: "SessionStart", script: SESSION_START_HOOK_JS, label: "session-start" },
     { event: "SessionEnd", script: SESSION_END_HOOK_JS, label: "session-end" },
     { event: "Stop", script: STOP_HOOK_JS, label: "stop" },
     { event: "PreCompact", script: PRE_COMPACT_HOOK_JS, label: "pre-compact" },
-    { event: "SubagentStart", script: SUBAGENT_START_HOOK_JS, label: "subagent-start" },
 ];
 function claudeSettingsPath() {
     return process.env["NLM_CLAUDE_SETTINGS"] ?? join(homedir(), ".claude", "settings.json");
@@ -1091,7 +1664,7 @@ const hook = program
     .description("Manage the Claude Code NLM hooks");
 hook
     .command("install")
-    .description("Add the NLM hooks (recall + session-end + stop) to ~/.claude/settings.json (live mode)")
+    .description("Add the NLM hooks (recall + session-start + session-end + stop + pre-compact) to ~/.claude/settings.json (live mode)")
     .action(() => {
     const path = claudeSettingsPath();
     const installed = [];
@@ -1597,7 +2170,7 @@ program
 program
     .command("digest")
     .description("Compose a daily-activity digest from the running daemon (optionally post to Telegram)")
-    .option("-p, --port <n>", "daemon port", (v) => Number.parseInt(v, 10), Number.parseInt(process.env["NLM_PORT"] ?? "3940", 10))
+    .option("-p, --port <n>", "daemon port", (v) => Number.parseInt(v, 10), Number.parseInt(process.env["NLM_PORT"] ?? DEFAULT_NLM_PORT, 10))
     .option("--telegram", "post to Telegram instead of printing to stdout (requires TELEGRAM_BOT_TOKEN + TELEGRAM_CHAT_ID)")
     .action(async (opts) => {
     autoloadEnv();
@@ -1615,6 +2188,21 @@ program
         process.exit(1);
     }
 });
+program
+    .command("work-digest")
+    .description("Print the operator's agent-assisted work recap for a day")
+    .option("-d, --date <date>", "day to summarize, YYYY-MM-DD (default: today)")
+    .action(async (opts) => {
+    const date = resolveDigestDate(opts.date);
+    const { storage, store } = await buildStack();
+    try {
+        const digest = await buildWorkDigest({ store, topicProvider: loadTopicProvider(), workstreams: storage.workstreams, ...workDigestEnv() }, date);
+        console.log(composeWorkDigest(digest));
+    }
+    finally {
+        await storage.close();
+    }
+});
 async function gatherInstallProbe() {
     autoloadEnv();
     let reachable = false;
@@ -1678,7 +2266,7 @@ async function gatherInstallProbe() {
 program
     .command("doctor")
     .description("Check database integrity invariants and install/runtime health, optionally repair safe violations")
-    .option("--fix", "repair mechanically safe violations: delete self-loop edges (I1), restore orphaned superseded/replaced sessions to closed (I2)")
+    .option("--fix", "repair mechanically safe violations: delete self-loop edges (I1), restore orphaned superseded/replaced sessions to closed (I2), delete ghost fact embeddings (I7)")
     .action(async (opts) => {
     const storage = await buildStorage(dbPath());
     let violations;
@@ -1697,7 +2285,10 @@ program
             if (fixReport.restoredToClosed > 0) {
                 console.log(`  fixed I2: restored ${fixReport.restoredToClosed} session(s) to closed`);
             }
-            if (fixReport.deletedSelfLoops === 0 && fixReport.restoredToClosed === 0) {
+            if (fixReport.deletedGhostEmbeddings > 0) {
+                console.log(`  fixed I7: deleted ${fixReport.deletedGhostEmbeddings} ghost embedding(s)`);
+            }
+            if (fixReport.deletedSelfLoops === 0 && fixReport.restoredToClosed === 0 && fixReport.deletedGhostEmbeddings === 0) {
                 console.log("  --fix: nothing to repair");
             }
         }
@@ -1711,7 +2302,7 @@ program
     finally {
         await storage.close();
     }
-    const ALL_CHECKS = ["I1", "I2", "I3", "I4", "I5a", "I5b", "I6"];
+    const ALL_CHECKS = ["I1", "I2", "I3", "I4", "I5a", "I5b", "I6", "I7"];
     const byId = new Map(violations.map((v) => [v.id, v]));
     let anyFail = false;
     console.log("Database integrity:");
@@ -1726,6 +2317,12 @@ program
             console.log(`PASS ${id}`);
         }
     }
+    // I5a-mv is informational: multi-valued predicate groups legitimately exempt
+    // from I5a. Not a violation; printed separately so the count is visible.
+    const i5aMv = byId.get("I5a-mv");
+    if (i5aMv) {
+        console.log(`INFO I5a-mv  count=${i5aMv.count}  ${i5aMv.description}`);
+    }
     console.log("\nInstall & runtime health:");
     if (printHealthChecks(evaluateInstallHealth(await gatherInstallProbe())))
         anyFail = true;
@@ -1746,9 +2343,11 @@ function printHealthChecks(checks) {
 async function dbIntegrityCheck() {
     const storage = await buildStorage(dbPath());
     try {
-        const violations = storage instanceof PgStorage
+        const all = storage instanceof PgStorage
             ? await runChecksOnPg(storage.pgPool())
             : runChecksOnSqlite(storage.rawDb());
+        // I5a-mv is informational (exempted multi-valued groups), not a true violation.
+        const violations = all.filter((v) => v.id !== "I5a-mv");
         if (violations.length === 0)
             return { id: "db-integrity", status: "ok", detail: "all invariants hold" };
         return {
@@ -1800,6 +2399,35 @@ program
     if (anyFail)
         process.exit(1);
 });
+program
+    .command("health")
+    .description("Print corpus monitoring snapshot from the running daemon (null before first 24h run)")
+    .action(async () => {
+    let corpus = null;
+    try {
+        const ctrl = new AbortController();
+        const timer = setTimeout(() => ctrl.abort(), 1_500);
+        const res = await fetch(`http://localhost:${port()}/api/health`, { signal: ctrl.signal });
+        clearTimeout(timer);
+        if (res.ok) {
+            const body = (await res.json());
+            corpus = body.corpus ?? null;
+        }
+    }
+    catch {
+        // daemon not reachable
+    }
+    if (corpus) {
+        console.log(`corpus.state:          ${corpus.state}`);
+        console.log(`corpus.dbBytes:        ${corpus.dbBytes}`);
+        console.log(`corpus.sessions:       ${corpus.sessions}`);
+        console.log(`corpus.entities:       ${corpus.entities}`);
+        console.log(`corpus.lastComputedAt: ${corpus.lastComputedAt}`);
+    }
+    else {
+        console.log("corpus: (not yet available; daemon runs the first check ~60s after start)");
+    }
+});
 program
     .command("backup")
     .description("Write a dated snapshot to ~/.nlm/backups/ and prune ones past the retention window")
@@ -1862,8 +2490,191 @@ program
     console.log(`Staged ${opts.from} (${validation.sessions} sessions, schema v${validation.schemaVersion}).`);
     console.log("Run `nlm restart` to apply — the current DB is archived aside, not deleted.");
 });
-program.parseAsync().catch((e) => {
-    console.error("nlm: fatal", e);
-    process.exit(1);
+program
+    .command("init")
+    .description("Print (or write) the agent recall contract snippet")
+    .requiredOption("--agent <name>", "agent variant: claude-code or generic")
+    .option("--write <path>", "append the contract to this file instead of printing to stdout")
+    .option("--force", "when --write: replace the existing block instead of refusing")
+    .action((opts) => {
+    runInitCommand({
+        agent: opts.agent,
+        write: opts.write,
+        force: Boolean(opts.force),
+        stdout: (s) => { process.stdout.write(s); },
+        stderr: (s) => { process.stderr.write(s); },
+    });
 });
+const entitiesCmd = program.command("entities").description("Entity table operations");
+entitiesCmd
+    .command("dedup")
+    .description("Suggest (or apply) conservative entity merge pairs. Default: dry run.")
+    .option("--apply-safe", "execute safe-class merges via the merge primitive", false)
+    .option("--interactive", "step through likely-class pairs with y/n on stdin", false)
+    .action(async (opts) => {
+    const storage = await buildStorage(dbPath());
+    let rows;
+    try {
+        if (storage instanceof SqliteStorage) {
+            rows = storage
+                .rawDb()
+                .prepare("SELECT canonical, session_count, status FROM entities ORDER BY canonical")
+                .all();
+        }
+        else {
+            const res = await storage
+                .pgPool()
+                .query("SELECT canonical, session_count, status FROM entities ORDER BY canonical");
+            rows = res.rows;
+        }
+    }
+    catch (err) {
+        await storage.close();
+        console.error("nlm entities dedup: failed to enumerate entities:", err);
+        process.exit(1);
+    }
+    const inputs = rows.map((r) => ({
+        canonical: r.canonical,
+        sessionCount: r.session_count,
+        status: r.status,
+    }));
+    const suggestions = suggestMerges(inputs);
+    const safe = suggestions.filter((s) => s.cls === "safe");
+    const likely = suggestions.filter((s) => s.cls === "likely");
+    let merged = 0;
+    let failed = 0;
+    let skipped = 0;
+    if (!opts.applySafe && !opts.interactive) {
+        console.log(`safe (${safe.length}):`);
+        for (const s of safe)
+            console.log(`  ${s.source}  ->  ${s.target}`);
+        console.log(`likely (${likely.length}):`);
+        for (const s of likely)
+            console.log(`  ${s.source}  ->  ${s.target}`);
+        console.log(`\ntotal: safe=${safe.length} likely=${likely.length} (dry run)`);
+        await storage.close();
+        return;
+    }
+    if (opts.applySafe) {
+        for (const s of safe) {
+            try {
+                await storage.entities.merge(s.source, s.target);
+                console.log(`merged: ${s.source} -> ${s.target}`);
+                merged++;
+            }
+            catch (err) {
+                console.error(`failed: ${s.source} -> ${s.target}: ${err}`);
+                failed++;
+            }
+        }
+    }
+    else {
+        for (const s of safe) {
+            console.log(`safe (skipped): ${s.source}  ->  ${s.target}`);
+            skipped++;
+        }
+    }
+    if (opts.interactive && likely.length > 0) {
+        const { createInterface } = await import("node:readline");
+        const rl = createInterface({ input: process.stdin, output: process.stdout });
+        const ask = (prompt) => new Promise((resolve) => rl.question(prompt, resolve));
+        for (const s of likely) {
+            const answer = await ask(`merge ${s.source} -> ${s.target}? [y/N] `);
+            if (answer.trim().toLowerCase() === "y") {
+                try {
+                    await storage.entities.merge(s.source, s.target);
+                    console.log(`merged: ${s.source} -> ${s.target}`);
+                    merged++;
+                }
+                catch (err) {
+                    console.error(`failed: ${s.source} -> ${s.target}: ${err}`);
+                    failed++;
+                }
+            }
+            else {
+                skipped++;
+            }
+        }
+        rl.close();
+    }
+    else {
+        skipped += likely.length;
+    }
+    await storage.close();
+    const remaining = suggestions.length - merged - failed;
+    console.log(`\nsummary: merged=${merged} failed=${failed} suggested-remaining=${remaining}`);
+    if (failed > 0)
+        process.exit(1);
+});
+const scopeCmd = program
+    .command("scope")
+    .description("Scope management commands");
+scopeCmd
+    .command("backfill")
+    .description("Derive and stamp scope on legacy sessions/facts/exemplars/signals/workstreams from stored transcript evidence")
+    .option("--apply", "write changes (default: dry run, no writes)")
+    .option("--db <path>", "SQLite DB file to backfill (default: canonical NLM DB)")
+    .option("--json", "emit machine-readable JSON summary instead of human-readable output")
+    .action(async (opts) => {
+    const targetPath = opts.db ?? dbPath();
+    const storage = SqliteStorage.create({ dbPath: targetPath, migrationsDir: MIGRATIONS_DIR });
+    const aliasMap = loadAliasMap();
+    try {
+        const result = await runScopeBackfill({
+            db: storage.rawDb(),
+            apply: Boolean(opts.apply),
+            aliasMap,
+        });
+        if (opts.json) {
+            const out = {
+                dryRun: result.dryRun,
+                sessions: { total: result.sessions.total, byScope: result.sessions.byScope },
+                facts: { total: result.facts.total, byScope: result.facts.byScope },
+                exemplars: { total: result.exemplars.total, byScope: result.exemplars.byScope },
+                signals: { total: result.signals.total, byScope: result.signals.byScope },
+                workstreams: { total: result.workstreams.total, byScope: result.workstreams.byScope },
+                skipped: result.skipped,
+            };
+            process.stdout.write(JSON.stringify(out, null, 2) + "\n");
+        }
+        else {
+            formatBackfillResult(result, (s) => process.stdout.write(s));
+        }
+    }
+    finally {
+        await storage.close();
+    }
+});
+scopeCmd
+    .command("coverage")
+    .description("Report per-table and recall-weighted scope coverage fractions")
+    .option("--db <path>", "SQLite DB file (default: canonical NLM DB)")
+    .option("--query-log <path>", "query log path for recall-weighted coverage")
+    .option("--window <n>", "last N log entries for recall-weighted coverage (default 200)", (v) => Number.parseInt(v, 10), 200)
+    .option("--json", "emit machine-readable JSON instead of human-readable output")
+    .action(async (opts) => {
+    const targetPath = opts.db ?? dbPath();
+    const result = await runScopeCoverage({
+        dbPath: targetPath,
+        ...(opts.queryLog ? { queryLogPath: opts.queryLog } : {}),
+        window: opts.window,
+    });
+    if (opts.json) {
+        process.stdout.write(JSON.stringify(result, null, 2) + "\n");
+    }
+    else {
+        formatCoverageResult(result, (s) => process.stdout.write(s));
+    }
+});
+// Entrypoint guard: only parse argv when this file IS the executed script.
+// realpathSync resolves the npm bin symlink so the global `nlm` shim still
+// matches; without the guard, importing any helper from this module inside
+// vitest ran the CLI against the test runner's argv and exited the worker.
+const entryPath = process.argv[1];
+if (entryPath && import.meta.url === pathToFileURL(realpathSync(entryPath)).href) {
+    program.parseAsync().catch((e) => {
+        console.error("nlm: fatal", e);
+        process.exit(1);
+    });
+}
 //# sourceMappingURL=nlm.js.map