pi-mega-compact 0.4.28 → 0.5.1

package/extensions/mega-pipeline.ts

@@ -12,10 +12,11 @@ import { sessionEntryToContextMessages } from "@earendil-works/pi-coding-agent";
 import type { AgentMessage } from "@earendil-works/pi-agent-core";
 import { compactSession } from "../src/engine.js";
 import type { EngineMessage } from "../src/types.js";
-import { recallAndInline } from "../src/recall.js";
+import { recallAndInline, recallAndInlineAsync, formatRecallBlock, type RecallInjectResult } from "../src/recall.js";
 import { normalizeSessionId } from "../src/store.js";
 import { estimateBlockTokens } from "../src/tokens.js";
 import { touchSession, logDaily } from "../src/store/sqlite.js";
+import { consolidateMemories } from "../src/memory.js";
 import {
   MegaRuntime,
   C,
@@ -77,6 +78,10 @@ function doCompact(
   runtime: MegaRuntime,
 ): RunCompactResult {
   runtime.pulsing = true; // animate the status line while the (sync) pipeline runs
+  // S21.2: reset the per-compaction memory-op counter so the post-compact
+  // consolidate pass only fires when memory rows actually changed during the
+  // compaction window (turn_end → auto-review may have written some).
+  runtime.memoriesTouchedThisCompaction = 0;
   const result = compactSession(
     {
       sessionId: sid,
@@ -148,6 +153,28 @@ function doCompact(
     /* non-fatal: stats bookkeeping only */
   }
 
+  // S21.2: best-effort consolidation of near-duplicate memories for this repo.
+  // Runs after the per-repo stats touch so `consolidateMemories` can use the
+  // same stateDir. Non-fatal — a failed consolidate never blocks a compaction.
+  // Only runs when new memory ops landed in this pass (otherwise the prior
+  // compaction's consolidate already had its shot — re-running would just
+  // touch every row again with no merges).
+  if (!result.deduped && runtime.memoriesTouchedThisCompaction > 0) {
+    try {
+      const root = resolveRepoRoot(ctx.cwd);
+      void consolidateMemories(runtime.currentStateDir, root).then(
+        (n) => {
+          if (n > 0) runtime.pushTicker(`${C.green}∫${C.reset} consolidated ${n} memory dup${n === 1 ? "" : "s"}`);
+        },
+        () => {
+          /* swallow: consolidate failures must never surface to the user */
+        },
+      );
+    } catch {
+      /* non-fatal */
+    }
+  }
+
   // Sentinel marker: a non-LLM bookkeeping entry so subsequent triggers can
   // skip re-vectorizing an already-compacted region (zero token cost).
   pi.appendEntry(MARKER_TYPE, {
@@ -363,6 +390,72 @@ export function doRecall(
   return result;
 }
 
+/**
+ * S17: async recall with optional cross-repo augmentation. Used on resume
+ * (session_start) and /mega-recall --cross-repo — NEVER from the mid-turn
+ * context handler (that stays sync). Runs the sync same-repo scan first; if it
+ * returns < config.autoInlineK hits AND crossRepo is enabled, awaits the PGlite
+ * HNSW cross-repo path and merges (source-labeled, deduped by checkpointId). The
+ * recallMaxTokens cap + windowDedupe apply to the merged set so cross-repo can
+ * never net-inflate the window. Cross-repo uses a stricter cosine floor
+ * (config.crossRepoCosine) than same-repo. Non-fatal: any async failure returns
+ * the same-repo result unchanged.
+ */
+export async function doRecallAsync(
+  runtime: MegaRuntime,
+  config: MegaConfig,
+  ctx: ExtensionContext,
+  query: string,
+  source: "resume" | "command",
+  opts: { crossRepo?: boolean } = {},
+): Promise<RecallInjectResult> {
+  runtime.bindRepo(ctx.cwd);
+  const sid = normalizeSessionId(ctx.sessionManager.getSessionId());
+  const liveWindow = config.windowDedupe ? extractLiveWindow(ctx) : undefined;
+  // Sync same-repo first (fast, never blocks).
+  const sameRepo = recallAndInline(
+    {
+      sessionId: sid, query, limit: config.autoInlineK, source, skipInjected: true,
+      recallMaxTokens: config.recallMaxTokens, windowDedupe: config.windowDedupe,
+      liveWindow, dedupSim: config.dedupSim,
+    },
+    runtime.store,
+  );
+  if (!config.crossRepoEnabled || !opts.crossRepo) return sameRepo;
+  if (sameRepo.toInject.length >= config.autoInlineK) return sameRepo; // same-repo satisfied
+  // Augment: cross-repo HNSW (async) with the stricter floor. Non-fatal.
+  try {
+    const x = await recallAndInlineAsync(
+      {
+        sessionId: sid, query, limit: config.autoInlineK, source, skipInjected: true,
+        recallMaxTokens: config.recallMaxTokens, windowDedupe: config.windowDedupe,
+        liveWindow, dedupSim: config.crossRepoCosine, crossRepo: true,
+        globalIndexDir: process.env.MEGACOMPACT_INDEX_DIR,
+      },
+      runtime.store,
+    );
+    runtime.dashboard.event("recall-crossrepo", {
+      source, query: query.slice(0, 120), injected: x.toInject.length,
+      sourceRepos: x.toInject.map((h) => h.repoId).filter(Boolean),
+    });
+    // Merge, dedup by checkpointId, respect the same token cap by reformatting.
+    const seen = new Set(sameRepo.toInject.map((h) => h.checkpoint.checkpointId));
+    const merged = [...sameRepo.toInject];
+    for (const h of x.toInject) {
+      if (!seen.has(h.checkpoint.checkpointId)) { merged.push(h); seen.add(h.checkpoint.checkpointId); }
+    }
+    const block = merged.length ? formatRecallBlock(merged) : "";
+    return {
+      toInject: merged,
+      report: merged.map((h) => `  • ${h.checkpoint.checkpointId}${h.repoId ? ` (from ${h.repoId.split("/").filter(Boolean).pop()})` : ""}`),
+      block,
+      empty: merged.length === 0,
+    };
+  } catch {
+    return sameRepo; // cross-repo failure → same-repo only (non-fatal)
+  }
+}
+
 /**
  * Extract the live-window message texts from the session manager (Fix C),
  * for inline-dedupe of recalled checkpoints. Best-effort: returns [] on any

package/extensions/mega-runtime.ts

@@ -12,7 +12,9 @@
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { sessionEntryToContextMessages } from "@earendil-works/pi-coding-agent";
 import type { AgentMessage } from "@earendil-works/pi-agent-core";
-import { join } from "node:path";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { readFileSync } from "node:fs";
 import { VectorStore } from "../src/vectorStore.js";
 import { toEngineMessages } from "../src/adapt.js";
 import { normalizeSessionId } from "../src/store.js";
@@ -25,6 +27,22 @@ export const STATUS_KEY = "mega-compact";
 export const WIDGET_KEY = "mega-compact-stats";
 export const MARKER_TYPE = "mega-compact-marker";
 
+/** Cached npm version, read once from this extension's own package.json. */
+let CACHED_VERSION: string | null = null;
+function ownVersion(): string {
+  if (CACHED_VERSION !== null) return CACHED_VERSION;
+  let v = "?";
+  try {
+    const here = dirname(fileURLToPath(import.meta.url)); // .../extensions
+    const pkg = JSON.parse(readFileSync(join(here, "..", "package.json"), "utf-8"));
+    v = pkg.version ?? "?";
+  } catch {
+    v = "?";
+  }
+  CACHED_VERSION = v;
+  return v;
+}
+
 /** Per-session runtime state kept in the closure (mirrors neuralwatt-mcr). */
 interface SessionRuntime {
   sessionId: string;
@@ -79,12 +97,17 @@ export class MegaRuntime {
     tokensSaved: 0,
   };
   debounceUntil = 0;
+  // S16: debounce for the agent_end resume nudge (avoid busy-loops).
+  resumeNudgeUntil = 0;
   // Agent tracking for real-time widget updates
   activeAgents = 0;
   currentTurn = 0;
   // Recall block produced by auto-inline (resume/branch) that the next
   // before_agent_start should prepend to the system prompt. Unset after use.
   pendingRecallBlock: string | undefined;
+  // S21: memory recall block, parallel to pendingRecallBlock. Same one-shot
+  // semantics; composed with the checkpoint block in before_agent_start.
+  pendingMemoryRecallBlock: string | undefined;
   statusKey: string | undefined; // current status text for dashboard
   // Active model/provider (for real cost estimation). Captured from ctx.model
   // on model_select + session_start; persisted to SQL so cost + the dashboard
@@ -103,6 +126,11 @@ export class MegaRuntime {
   readonly TICKER_MAX = 5;
   // Pulsing status: set true while a compaction is in flight, cleared on result.
   pulsing = false;
+  // S21.2: set by `applyMemoryOps` when a memory add/replace/remove lands in
+  // the current compaction. The pipeline reads this after a successful compact
+  // to decide whether to fire `consolidateMemories` (skip the work entirely
+  // when no memory rows changed).
+  memoriesTouchedThisCompaction = 0;
   // Rolling "saved" goal for the progress bar — grows as we save more, so the
   // bar always has a meaningful denominator (never sits at 100% forever).
   savedGoal = 50_000;
@@ -255,7 +283,7 @@ export class MegaRuntime {
       // Phase 3 — pulsing status glyph while a compaction is in flight.
       const pulse = this.pulsing ? `${C.cyan}${PULSE[Math.floor(Date.now() / 250) % PULSE.length]}${C.reset} ` : "";
       const lines = [
-        ` ${C.amber}⚡ ${this.config.tier}${C.reset} │ ${tokStr}/${maxStr} tokens (${C.bold}${pctStr}${C.reset}) │ ${st.checkpointCount} saved${agentStr}${turnStr}`,
+        ` ${C.amber}⚡ ${this.config.tier}${C.reset} v${C.bold}${ownVersion()}${C.reset} │ ${tokStr}/${maxStr} tokens (${C.bold}${pctStr}${C.reset}) │ ${st.checkpointCount} saved${agentStr}${turnStr}`,
         `   ${triggerLabel} │ ${C.magenta}repeat-skipped: ${dedupStr}${C.reset} │ ${C.gray}memory held:${C.reset} ${usedStr} │ ${C.gray}space freed:${C.reset} ${savedStr}`,
       ];
       // Phase 3 — compact progress bar: session tokens saved toward the rolling goal.
@@ -364,6 +392,11 @@ export class MegaRuntime {
     } catch { /* non-fatal: cost estimation degrades to model-in-memory only */ }
   }
 
+  /** S21: state dir of the currently bound repo (where memories live). */
+  getStateDir(): string {
+    return this.currentStateDir;
+  }
+
   /** Build the sync onTier callback that paints the live per-tier trace. */
   makeTierCallback(ctx: ExtensionContext): (ev: { tier: "L0" | "L1" | "L2" | "new"; status: "scanning" | "deduped" | "passed" | "stored"; detail?: string }) => void {
     const order: Array<"L0" | "L1" | "L2" | "new"> = ["L0", "L1", "L2", "new"];

package/extensions/mega-trim.test.ts

@@ -0,0 +1,64 @@
+/**
+ * mega-trim.test.ts — tests for the live compaction view builder (S16).
+ */
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { buildLiveTrimmedView } from "./mega-trim.js";
+import type { EngineMessage } from "../src/types.js";
+
+function m(role: EngineMessage["role"], text: string, extra: Partial<EngineMessage> = {}): EngineMessage {
+  return { role, text, toolName: undefined, input: undefined, output: undefined, ...extra };
+}
+
+test("buildLiveTrimmedView: prepends a compacted summary and keeps the recent anchor", () => {
+  const view: EngineMessage[] = [
+    m("user", "old request one"), m("assistant", "old answer one"),
+    m("user", "old request two"), m("assistant", "old answer two"),
+    m("user", "recent keep me"), m("assistant", "recent keep me too"),
+  ];
+  // Compacted region = first 4; recent anchor = last 2.
+  const result = buildLiveTrimmedView(view, {
+    compactedFrom: 4,        // index where the compacted region ends
+    summary: "<summary>earlier work on old requests</summary>",
+    anchorUserMessages: 1,
+  });
+  // First element is the injected compacted summary as a user-role message.
+  assert.equal(result[0].role, "user");
+  assert.ok(String(result[0].text).includes("earlier work on old requests"));
+  // Recent anchor preserved in order, no older messages leak through.
+  assert.equal(result.length, 1 + 2, "summary + 2 recent");
+  assert.ok(result.slice(1).some((x) => String(x.text).includes("recent keep me")));
+});
+
+test("buildLiveTrimmedView: empty summary returns the original view unchanged", () => {
+  const view = [m("user", "x"), m("assistant", "y")];
+  const result = buildLiveTrimmedView(view, { compactedFrom: 0, summary: "", anchorUserMessages: 1 });
+  assert.deepEqual(result, view);
+});
+
+test("buildLiveTrimmedView: never splits a toolCall/toolResult pair (PREVENT-PI-002)", () => {
+  const view: EngineMessage[] = [
+    m("user", "q"), m("assistant", "calls tool", { toolName: "read" }), m("tool", "result"),
+    m("user", "keep"), m("assistant", "ok"),
+  ];
+  // cut=3 would start the preserved run on the orphaned tool result at index 2 —
+  // the builder must snap back so the toolCall/toolResult pair is not split.
+  const result = buildLiveTrimmedView(view, { compactedFrom: 3, summary: "<summary>s</summary>", anchorUserMessages: 1 });
+  // The tool result must never appear preserved WITHOUT its preceding toolCall.
+  const preserved = result.slice(1);
+  const hasToolResult = preserved.some((x) => x.role === "tool");
+  const hasToolCall = preserved.some((x) => x.role === "assistant" && x.toolName);
+  // Either the tool pair is kept together, or the tool result is dropped into
+  // the compacted region — it is never left orphaned.
+  assert.ok(!(hasToolResult && !hasToolCall), "no orphaned tool result in the preserved run");
+});
+
+test("buildLiveTrimmedView: honors the anchor floor (PREVENT-PI-001)", () => {
+  // cut would leave zero user messages in the anchor — must skip the trim.
+  const view: EngineMessage[] = [
+    m("user", "old q"), m("assistant", "old a"),
+    m("assistant", "only assistant kept"),
+  ];
+  const result = buildLiveTrimmedView(view, { compactedFrom: 2, summary: "<summary>s</summary>", anchorUserMessages: 1 });
+  assert.deepEqual(result, view, "below anchor floor → no trim this call");
+});

package/extensions/mega-trim.ts

@@ -0,0 +1,75 @@
+/**
+ * mega-trim.ts — the LIVE compaction view builder (S16).
+ *
+ * Produces the message list returned from the `context` event so the model sees
+ * a compacted window every LLM call WITHOUT aborting the turn (ctx.compact()
+ * would abort; the context-event return feeds pi's transformContext per call).
+ *
+ * Shape: [compactSummaryMessage, ...recentAnchor]. The compacted region
+ * [0, compactedFrom) is collapsed to a single user-role summary; the recent
+ * anchor [compactedFrom, end) is kept verbatim. Honors PREVENT-PI-002 (never
+ * splits a toolCall/toolResult pair) by snapping compactedFrom back to a
+ * boundary-safe index, and PREVENT-PI-001 (anchor floor) via the anchor knob.
+ *
+ * Pure + pi-agnostic: takes EngineMessage[], returns EngineMessage[]. No pi
+ * imports. Non-destructive: the caller still owns the real messages.
+ */
+import type { EngineMessage } from "../src/types.js";
+import { isBoundarySafe } from "../src/boundary.js";
+import { formatCompactSummary } from "../src/compact.js";
+
+export interface BuildLiveTrimViewOpts {
+  /** Index where the compacted region ends (the recent anchor starts here). */
+  compactedFrom: number;
+  /** The compacted-region summary text (already generated by runCompact). */
+  summary: string;
+  /** Min recent user messages to keep as the anchor (PREVENT-PI-001). */
+  anchorUserMessages: number;
+}
+
+/**
+ * Compute the safe cut index for the live trim. Snaps `compactedFrom` back to a
+ * boundary-safe index (PREVENT-PI-002: never start the preserved run on an
+ * orphaned tool result), and enforces the anchor floor (PREVENT-PI-001: keep at
+ * least `anchorUserMessages` user-role messages). Returns `null` when no trim is
+ * safe this call (empty summary, unsafe boundary, or below the anchor floor) so
+ * the caller keeps the original view and retries on the next context event.
+ *
+ * Exposed separately from `buildLiveTrimmedView` so the context handler can map
+ * the cut back onto the original pi `AgentMessage[]` (lossless index alignment,
+ * mirroring `dropCompactedRange` in src/adapt.ts).
+ */
+export function computeLiveTrimCut(view: EngineMessage[], opts: BuildLiveTrimViewOpts): number | null {
+  if (!opts.summary || !opts.summary.trim()) return null;
+  let cut = opts.compactedFrom;
+  while (cut > 0 && !isBoundarySafe(view, cut)) cut--;
+  if (cut <= 0) return null; // nothing safe to cut — keep everything this call
+  const recent = view.slice(cut);
+  const userCount = recent.filter((m) => m.role === "user").length;
+  if (userCount < opts.anchorUserMessages) return null;
+  return cut;
+}
+
+/** The formatted compacted-region summary as a user-role engine message. */
+export function liveTrimSummaryMessage(opts: BuildLiveTrimViewOpts): EngineMessage {
+  return {
+    role: "user",
+    text: formatCompactSummary(opts.summary),
+    toolName: undefined,
+    input: undefined,
+    output: undefined,
+  };
+}
+
+/** Build the live trimmed view. Returns the original view if summary is empty
+ *  or the boundary is unsafe (no trim this call — try next). Pure + tested. */
+export function buildLiveTrimmedView(
+  view: EngineMessage[],
+  opts: BuildLiveTrimViewOpts,
+): EngineMessage[] {
+  const cut = computeLiveTrimCut(view, opts);
+  if (cut === null) return view;
+  const recent = view.slice(cut);
+  const summaryMsg = liveTrimSummaryMessage(opts);
+  return [summaryMsg, ...recent];
+}

package/extensions/openclaw-mega-compact.ts

@@ -21,7 +21,7 @@ import {
   type CompactInput,
   type CompactResult,
 } from "../src/engine.js";
-import { recallAndInline, type RecallInjectResult } from "../src/recall.js";
+import { recallAndInline, recallMemoriesAndInline, type RecallInjectResult } from "../src/recall.js";
 import { VectorStore } from "../src/vectorStore.js";
 import type { EngineMessage } from "../src/types.js";
 
@@ -333,19 +333,34 @@ export default definePluginEntry({
             store,
           );
 
-          if (result.toInject.length === 0) {
+          // S21: parallel memory recall for the slash command. Same query so the
+          // output combines checkpoint + memory context the user actually needs.
+          let memBlock = "";
+          let memReport: string[] = [];
+          try {
+            const mr = await recallMemoriesAndInline({ query, stateDir, limit: 5 });
+            if (!mr.empty) {
+              memBlock = mr.block;
+              memReport = mr.report;
+            }
+          } catch {
+            // best-effort — never break the command over memory recall
+          }
+
+          if (result.toInject.length === 0 && !memBlock) {
             return {
               content: [{ type: "text", text: "No relevant context found in the mega-compact store." }],
             };
           }
 
-          const parts: string[] = [
-            `**Recalled ${result.toInject.length} checkpoint(s):**`,
-            ...result.report,
-            "",
-            "---",
-            result.block,
-          ];
+          const parts: string[] = [];
+          if (result.toInject.length) {
+            parts.push(`**Recalled ${result.toInject.length} checkpoint(s):**`, ...result.report, "");
+          }
+          if (memBlock) {
+            parts.push(`**Recalled ${memReport.length} memory record(s):**`, ...memReport, "");
+          }
+          parts.push("---", result.block, memBlock);
 
           return { content: [{ type: "text", text: parts.join("\n") }] };
         } catch (err) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-mega-compact",
-  "version": "0.4.28",
+  "version": "0.5.1",
   "description": "Layered, local, vector-backed context compressor for pi — supersede/collapse/cluster compaction with deduped inline recall.",
   "type": "module",
   "license": "BSD-2-Clause",
@@ -42,7 +42,7 @@
   "scripts": {
     "build": "tsc -p tsconfig.json",
     "lint": "tsc --noEmit && node scripts/guardrails-scan.mjs",
-    "test": "npm run build && node --test --test-timeout=180000 \"dist/src/**/*.test.js\" \"dist/extensions/**/*.test.js\"",
+    "test": "npm run build && node scripts/run-tests.mjs",
     "guardrails": "python3 scripts/regression_check.py --all || node scripts/guardrails-scan.mjs",
     "precommit": "bash .claude/hooks/pre-commit.sh",
     "prepublishOnly": "npm run build",

package/src/config/dedup.ts

@@ -46,6 +46,7 @@ export interface DedupConfigShape {
   DEDUP_SIM: number; // legacy content-similarity fallback
   MMR_LAMBDA: number; // retrieval diversity
   SEMDEDUP_COSINE: number; // offline SemDeDup pair threshold
+  CONSOLIDATE_COSINE: number; // memory consolidation merge threshold (Sprint 21)
   // Caps / budgets.
   SIMILARITY_BUDGET_MS: number;
   L1_VERIFY_BUDGET_MS: number;
@@ -79,6 +80,7 @@ export function loadDedupConfig(): DedupConfigShape {
     DEDUP_SIM: envNum("MEGACOMPACT_DEDUP_SIM", 0.9),
     MMR_LAMBDA: envNum("MEGACOMPACT_MMR_LAMBDA", 0.5),
     SEMDEDUP_COSINE: envNum("MEGACOMPACT_SEMDEDUP_COSINE", 0.95),
+    CONSOLIDATE_COSINE: envNum("MEGACOMPACT_CONSOLIDATE_COSINE", 0.7),
     SIMILARITY_BUDGET_MS: envNum("MEGACOMPACT_SIMILARITY_BUDGET_MS", 50),
     L1_VERIFY_BUDGET_MS: envNum("MEGACOMPACT_L1_VERIFY_BUDGET_MS", 20),
     L1_CANDIDATE_CAP: envNum("MEGACOMPACT_L1_CANDIDATE_CAP", 100),

package/src/driftDetection.test.ts

@@ -0,0 +1,100 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { upsertRepoRegistry } from "./store/sqlite.js";
+import { detectCrossRepoDrift } from "./driftDetection.js";
+
+const NOW = Math.floor(Date.now() / 1000);
+const D = 86_400;
+
+test("driftDetection: empty registry returns ok report", () => {
+  const dir = mkdtempSync(join(tmpdir(), "drift-empty-"));
+  try {
+    const report = detectCrossRepoDrift(dir);
+    assert.equal(report.totals.ok, 0);
+    assert.equal(report.totals.warn, 0);
+    assert.equal(report.repos.length, 0);
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test("driftDetection: flags stale repos older than 30 days", () => {
+  const dir = mkdtempSync(join(tmpdir(), "drift-stale-"));
+  try {
+    upsertRepoRegistry(
+      { repoRoot: "/r/old", displayName: "old", stateDir: "/r/old", checkpointCount: 1, tokensSaved: 0, compressedOriginalBytes: 0, lastSeen: NOW - 45 * D },
+      dir,
+    );
+    const report = detectCrossRepoDrift(dir);
+    assert.equal(report.repos.length, 1);
+    assert.ok(report.repos[0].signals.some((s) => s.kind === "stale"), "stale signal present");
+    assert.equal(report.repos[0].status, "ok", "stale alone is info, not warn");
+    assert.equal(report.totals.stale, 1);
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test("driftDetection: active repo with no compaction flagged as warn", () => {
+  const dir = mkdtempSync(join(tmpdir(), "drift-lag-"));
+  try {
+    upsertRepoRegistry(
+      { repoRoot: "/r/active", displayName: "active", stateDir: "/r/active", checkpointCount: 1, tokensSaved: 0, compressedOriginalBytes: 0, lastSeen: NOW - 1 * D },
+      dir,
+    );
+    const report = detectCrossRepoDrift(dir);
+    const r = report.repos[0];
+    assert.ok(r.signals.some((s) => s.kind === "compaction_lag"), "lag signal present");
+    assert.equal(r.status, "warn", "compaction lag is warn-level");
+    assert.equal(report.totals.warn, 1);
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test("driftDetection: active repo with recent compaction is ok", () => {
+  const dir = mkdtempSync(join(tmpdir(), "drift-ok-"));
+  try {
+    upsertRepoRegistry(
+      { repoRoot: "/r/healthy", displayName: "healthy", stateDir: "/r/healthy", checkpointCount: 1, tokensSaved: 0, compressedOriginalBytes: 0, lastSeen: NOW, lastCompactedAt: NOW },
+      dir,
+    );
+    const report = detectCrossRepoDrift(dir);
+    const r = report.repos[0];
+    assert.equal(r.status, "ok");
+    assert.equal(r.signals.length, 0);
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test("driftDetection: recent model churn flagged as info", () => {
+  const dir = mkdtempSync(join(tmpdir(), "drift-model-"));
+  try {
+    upsertRepoRegistry(
+      {
+        repoRoot: "/r/swap",
+        displayName: "swap",
+        stateDir: "/r/swap",
+        checkpointCount: 1,
+        tokensSaved: 0,
+        compressedOriginalBytes: 0,
+        lastSeen: NOW,
+        lastCompactedAt: NOW,
+        provider: "anthropic",
+        providerName: "Anthropic",
+        modelName: "sonnet-4.6",
+        modelCapturedAt: NOW - 1 * D,
+      },
+      dir,
+    );
+    const report = detectCrossRepoDrift(dir);
+    assert.ok(report.repos[0].signals.some((s) => s.kind === "model_churn"), "model churn detected");
+    assert.equal(report.totals.modelChurn, 1);
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});

package/src/driftDetection.ts

@@ -0,0 +1,136 @@
+/**
+ * driftDetection.ts — R4: cross-repo drift detection over the machine-wide
+ * repo_registry (index.sqlite). Reads the registry, classifies each repo
+ * against simple drift signals, and returns a structured report that the
+ * dashboard's Multi-repo tab and the /api/drift endpoint can render.
+ *
+ * Signals (all derived from repo_registry alone — no checkpoint scans):
+ *   - stale: last_seen older than STALE_DAYS (default 30). Repo is up but
+ *     hasn't touched the dashboard in a while — usually parked work.
+ *   - compaction_lag: last_seen within ACTIVE_DAYS (default 7) but
+ *     last_compacted_at is null or > 24h behind. The repo is actively running
+ *     work but compaction isn't keeping pace — usually a config regression.
+ *   - model_churn: model_captured_at within MODEL_CHURN_DAYS (default 7) —
+ *     the active model changed recently. Could be a routine upgrade or a
+ *     silent fallback; both worth flagging.
+ *
+ * Scope: read-only by design. No writes — drift reporting should never mutate
+ * the registry. Severity classification is conservative: warnings, not alarms.
+ * @module
+ */
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { DatabaseSync } from "node:sqlite";
+import { getIndexDir } from "./store/sqlite.js";
+
+const DAY_SEC = 86_400;
+const STALE_DAYS = 30;
+const ACTIVE_DAYS = 7;
+const MODEL_CHURN_DAYS = 7;
+/** Compaction lag threshold: last_seen newer than this AND last_compacted_at
+ *  more than this far behind. 24h is generous — compactions usually fire in
+ *  minutes; >24h usually means something is wedged. */
+const COMPACTION_LAG_SEC = 24 * 3600;
+
+export type DriftSeverity = "warn" | "info";
+
+export interface RepoDrift {
+  repoRoot: string;
+  displayName: string;
+  lastSeen: number;
+  lastCompactedAt: number | null;
+  modelCapturedAt: number | null;
+  signals: Array<{ kind: "stale" | "compaction_lag" | "model_churn"; severity: DriftSeverity; detail: string }>;
+  /** Highest severity across signals; "ok" if none. */
+  status: "ok" | "warn";
+}
+
+export interface DriftReport {
+  generatedAt: number;
+  totals: { ok: number; warn: number; stale: number; compactionLag: number; modelChurn: number };
+  repos: RepoDrift[];
+}
+
+/** Read all repos from the machine-wide registry, classify drift, return report. */
+export function detectCrossRepoDrift(indexDir: string = getIndexDir()): DriftReport {
+  const generatedAt = Math.floor(Date.now() / 1000);
+  const indexPath = join(indexDir, "index.sqlite");
+  const totals = { ok: 0, warn: 0, stale: 0, compactionLag: 0, modelChurn: 0 };
+  if (!existsSync(indexPath)) return { generatedAt, totals, repos: [] };
+
+  let db: DatabaseSync | undefined;
+  try {
+    db = new DatabaseSync(indexPath, { readOnly: true });
+    db.exec("PRAGMA journal_mode = WAL");
+    const rows = db
+      .prepare(
+        `SELECT repo_root, display_name, last_seen, last_compacted_at,
+                model_name, provider, model_captured_at
+           FROM repo_registry`,
+      )
+      .all() as Array<{
+        repo_root: string;
+        display_name: string | null;
+        last_seen: number | null;
+        last_compacted_at: number | null;
+        model_name: string | null;
+        provider: string | null;
+        model_captured_at: number | null;
+      }>;
+
+    const repos: RepoDrift[] = [];
+    for (const r of rows) {
+      const lastSeen = r.last_seen ?? 0;
+      const lastCompacted = r.last_compacted_at ?? null;
+      const modelCaptured = r.model_captured_at ?? null;
+      const signals: RepoDrift["signals"] = [];
+
+      if (lastSeen > 0 && generatedAt - lastSeen > STALE_DAYS * DAY_SEC) {
+        const daysAgo = Math.floor((generatedAt - lastSeen) / DAY_SEC);
+        signals.push({ kind: "stale", severity: "info", detail: `last activity ${daysAgo}d ago` });
+        totals.stale++;
+      }
+      if (
+        lastSeen > 0 &&
+        generatedAt - lastSeen <= ACTIVE_DAYS * DAY_SEC &&
+        (lastCompacted === null || generatedAt - lastCompacted > COMPACTION_LAG_SEC)
+      ) {
+        const lagSec = lastCompacted ? generatedAt - lastCompacted : generatedAt - lastSeen;
+        const lagH = Math.floor(lagSec / 3600);
+        signals.push({
+          kind: "compaction_lag",
+          severity: "warn",
+          detail: lastCompacted ? `${lagH}h behind last activity` : "never compacted",
+        });
+        totals.compactionLag++;
+      }
+      if (modelCaptured && generatedAt - modelCaptured <= MODEL_CHURN_DAYS * DAY_SEC) {
+        const label = [r.provider, r.model_name].filter(Boolean).join("/") || "model";
+        signals.push({ kind: "model_churn", severity: "info", detail: `${label} captured recently` });
+        totals.modelChurn++;
+      }
+
+      const status: RepoDrift["status"] = signals.some((s) => s.severity === "warn") ? "warn" : "ok";
+      if (status === "warn") totals.warn++;
+      else totals.ok++;
+
+      repos.push({
+        repoRoot: r.repo_root,
+        displayName: r.display_name ?? r.repo_root,
+        lastSeen,
+        lastCompactedAt: lastCompacted,
+        modelCapturedAt: modelCaptured,
+        signals,
+        status,
+      });
+    }
+    // Sort: warn first, then by lastSeen desc so the active ones are on top.
+    repos.sort((a, b) => {
+      if (a.status !== b.status) return a.status === "warn" ? -1 : 1;
+      return b.lastSeen - a.lastSeen;
+    });
+    return { generatedAt, totals, repos };
+  } finally {
+    db?.close();
+  }
+}