@geravant/sinain 1.0.18 → 1.0.19

package/sinain-knowledge/curation/resilience.ts

@@ -0,0 +1,336 @@
+/**
+ * sinain-knowledge — ResilienceManager + HealthWatchdog
+ *
+ * Manages retry storm detection, outage tracking, overflow watchdog,
+ * and proactive health monitoring. Decoupled from OpenClaw — communicates
+ * through the BackendAdapter interface for transcript access and alerts.
+ */
+
+import type { Logger } from "../data/schema.js";
+
+// ============================================================================
+// Constants
+// ============================================================================
+
+export const ERROR_WINDOW_MS = 5 * 60_000;
+export const OUTAGE_ERROR_RATE_THRESHOLD = 0.8;
+export const OUTAGE_MIN_SAMPLES = 3;
+export const FILE_SYNC_DEBOUNCE_MS = 3 * 60_000;
+export const PLAYBOOK_GEN_DEBOUNCE_MS = 5 * 60_000;
+export const SHORT_FAILURE_THRESHOLD_MS = 10_000;
+export const LONG_FAILURE_THRESHOLD_MS = 3 * 60_000;
+
+export const OVERFLOW_CONSECUTIVE_THRESHOLD = 5;
+export const OVERFLOW_TRANSCRIPT_MIN_BYTES = 1_000_000;
+export const OVERFLOW_ERROR_PATTERN = /overloaded|context.*too.*long|token.*limit|extra usage is required/i;
+
+export const SESSION_HYGIENE_SIZE_BYTES = 2_000_000;
+export const SESSION_HYGIENE_AGE_MS = 24 * 60 * 60 * 1000;
+
+export const WATCHDOG_INTERVAL_MS = 5 * 60_000;
+export const ALERT_COOLDOWN_MS = 15 * 60_000;
+export const STALENESS_WARNING_MS = 10 * 60_000;
+export const STALENESS_CRITICAL_MS = 15 * 60_000;
+export const SESSION_SIZE_WARNING_BYTES = 1_500_000;
+export const SESSION_SIZE_RESTART_BYTES = 2_000_000;
+export const AUTO_RESTART_COOLDOWN_MS = 60 * 60_000;
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export type ErrorRateResult = {
+  rate: number;
+  total: number;
+  failures: number;
+};
+
+export type HealthCheckResult = {
+  transcriptMB: number | null;
+  staleSec: number;
+  errorRate: number;
+  errorTotal: number;
+  overflowCount: number;
+  resetRecently: boolean;
+  issues: string[];
+};
+
+export interface TranscriptInfo {
+  path: string;
+  bytes: number;
+}
+
+/**
+ * Interface for backend operations needed by the resilience layer.
+ * Avoids direct coupling to OpenClaw or any specific backend.
+ */
+export interface ResilienceBackend {
+  getTranscriptSize(): TranscriptInfo | null;
+  performOverflowReset(): boolean;
+  sendAlert(alertType: string, title: string, body: string): Promise<void>;
+}
+
+// ============================================================================
+// ResilienceManager
+// ============================================================================
+
+export class ResilienceManager {
+  recentOutcomes: Array<{ ts: number; success: boolean; error?: string }> = [];
+  lastSuccessTs = 0;
+  consecutiveFailures = 0;
+  outageDetected = false;
+  outageStartTs = 0;
+  consecutiveOverflowErrors = 0;
+  consecutiveHeartbeatSkips = 0;
+  lastResetTs = 0;
+  lastAutoRestartTs = 0;
+
+  // Debounce timestamps
+  lastPlaybookGenTs = 0;
+  lastFileSyncTs = 0;
+  lastEvalReportDate: string | null = null;
+
+  computeErrorRate(): ErrorRateResult {
+    const cutoff = Date.now() - ERROR_WINDOW_MS;
+    while (this.recentOutcomes.length > 0 && this.recentOutcomes[0].ts < cutoff) {
+      this.recentOutcomes.shift();
+    }
+    const total = this.recentOutcomes.length;
+    if (total === 0) return { rate: 0, total: 0, failures: 0 };
+    const failures = this.recentOutcomes.filter((o) => !o.success).length;
+    return { rate: failures / total, total, failures };
+  }
+
+  recordSuccess(backend: ResilienceBackend, logger: Logger): void {
+    const wasOutage = this.outageDetected;
+    const outageDurationMs = this.outageStartTs > 0 ? Date.now() - this.outageStartTs : 0;
+    this.consecutiveFailures = 0;
+    this.outageDetected = false;
+    this.lastSuccessTs = Date.now();
+    if (wasOutage) {
+      logger.info(
+        `sinain-hud: OUTAGE RECOVERED — resumed after ${Math.round(outageDurationMs / 1000)}s`,
+      );
+      backend.sendAlert("recovery", "✅ *sinain-hud* recovered",
+        `• Gateway up, first run succeeded\n• Downtime: ~${Math.round(outageDurationMs / 60_000)}min`);
+    }
+  }
+
+  recordShortFailure(backend: ResilienceBackend, logger: Logger): void {
+    this.consecutiveFailures++;
+    const { rate, total } = this.computeErrorRate();
+    if (!this.outageDetected && total >= OUTAGE_MIN_SAMPLES && rate >= OUTAGE_ERROR_RATE_THRESHOLD) {
+      this.outageDetected = true;
+      this.outageStartTs = Date.now();
+      logger.warn(
+        `sinain-hud: OUTAGE DETECTED — ${Math.round(rate * 100)}% error rate over ${total} samples, ${this.consecutiveFailures} consecutive failures`,
+      );
+      backend.sendAlert("outage", "🔴 *sinain-hud* OUTAGE DETECTED",
+        `• ${Math.round(rate * 100)}% error rate over ${total} samples\n• ${this.consecutiveFailures} consecutive failures`);
+    }
+  }
+
+  checkOverflow(
+    isSuccess: boolean,
+    error: string | undefined,
+    durationMs: number,
+    backend: ResilienceBackend,
+    logger: Logger,
+  ): void {
+    if (!isSuccess && OVERFLOW_ERROR_PATTERN.test(error ?? "")) {
+      this.consecutiveOverflowErrors++;
+      logger.warn(
+        `sinain-hud: overflow watchdog — error #${this.consecutiveOverflowErrors}/${OVERFLOW_CONSECUTIVE_THRESHOLD}`,
+      );
+      if (this.consecutiveOverflowErrors >= OVERFLOW_CONSECUTIVE_THRESHOLD) {
+        logger.warn("sinain-hud: OVERFLOW THRESHOLD REACHED — attempting transcript reset");
+        if (backend.performOverflowReset()) {
+          this._resetAfterOverflow(backend);
+        }
+      }
+    } else if (isSuccess) {
+      this.consecutiveOverflowErrors = 0;
+    }
+
+    // Duration-gated: long failure + overflow pattern = stuck retry loop
+    const isLongFailure = !isSuccess && durationMs > LONG_FAILURE_THRESHOLD_MS;
+    if (isLongFailure && OVERFLOW_ERROR_PATTERN.test(error ?? "")) {
+      logger.warn(
+        `sinain-hud: long failure (${Math.round(durationMs / 1000)}s) with overflow error — immediate reset`,
+      );
+      if (backend.performOverflowReset()) {
+        this._resetAfterOverflow(backend, `• ${Math.round(durationMs / 1000)}s failed run with overflow error\n• Transcript truncated, next heartbeat should recover`);
+      }
+    }
+  }
+
+  private _resetAfterOverflow(backend: ResilienceBackend, body?: string): void {
+    this.lastResetTs = Date.now();
+    this.consecutiveOverflowErrors = 0;
+    this.outageDetected = false;
+    this.consecutiveFailures = 0;
+    this.outageStartTs = 0;
+    backend.sendAlert(
+      "overflow_reset",
+      body ? "⚠️ *sinain-hud* overflow reset (stuck retry)" : "⚠️ *sinain-hud* overflow reset triggered",
+      body ?? `• ${OVERFLOW_CONSECUTIVE_THRESHOLD} consecutive overflow errors\n• Transcript truncated`,
+    );
+  }
+
+  isFileSyncDue(): boolean {
+    return this.lastFileSyncTs === 0 || (Date.now() - this.lastFileSyncTs) >= FILE_SYNC_DEBOUNCE_MS;
+  }
+
+  markFileSynced(): void {
+    this.lastFileSyncTs = Date.now();
+  }
+
+  isPlaybookGenDue(): boolean {
+    return this.lastPlaybookGenTs === 0 || (Date.now() - this.lastPlaybookGenTs) >= PLAYBOOK_GEN_DEBOUNCE_MS;
+  }
+
+  markPlaybookGenerated(): void {
+    this.lastPlaybookGenTs = Date.now();
+  }
+
+  resetAll(): void {
+    this.recentOutcomes.length = 0;
+    this.lastSuccessTs = 0;
+    this.lastPlaybookGenTs = 0;
+    this.lastFileSyncTs = 0;
+    this.outageDetected = false;
+    this.consecutiveFailures = 0;
+    this.outageStartTs = 0;
+    this.consecutiveHeartbeatSkips = 0;
+    this.consecutiveOverflowErrors = 0;
+    this.lastResetTs = 0;
+    this.lastAutoRestartTs = 0;
+    this.lastEvalReportDate = null;
+  }
+}
+
+// ============================================================================
+// HealthWatchdog
+// ============================================================================
+
+export class HealthWatchdog {
+  private interval: ReturnType<typeof setInterval> | null = null;
+
+  constructor(
+    private resilience: ResilienceManager,
+    private backend: ResilienceBackend,
+    private logger: Logger,
+  ) {}
+
+  runChecks(): HealthCheckResult {
+    const transcript = this.backend.getTranscriptSize();
+    const transcriptMB = transcript ? +(transcript.bytes / 1_000_000).toFixed(2) : null;
+    const staleSec = this.resilience.lastSuccessTs > 0
+      ? Math.round((Date.now() - this.resilience.lastSuccessTs) / 1000)
+      : 0;
+    const { rate, total } = this.resilience.computeErrorRate();
+    const resetRecently = this.resilience.lastResetTs > 0
+      && (Date.now() - this.resilience.lastResetTs) < STALENESS_CRITICAL_MS * 2;
+
+    const issues: string[] = [];
+    if (transcriptMB !== null && transcript!.bytes >= SESSION_SIZE_WARNING_BYTES) {
+      issues.push(`transcript ${transcriptMB}MB (threshold ${(SESSION_SIZE_WARNING_BYTES / 1_000_000).toFixed(1)}MB)`);
+    }
+    if (this.resilience.lastSuccessTs > 0 && (Date.now() - this.resilience.lastSuccessTs) >= STALENESS_WARNING_MS && this.resilience.recentOutcomes.length >= 3) {
+      issues.push(`stale ${staleSec}s since last success`);
+    }
+    if (total >= 5 && rate > 0.5) {
+      issues.push(`error rate ${Math.round(rate * 100)}% (${total} samples)`);
+    }
+    if (this.resilience.consecutiveOverflowErrors >= 3) {
+      issues.push(`overflow errors ${this.resilience.consecutiveOverflowErrors}/${OVERFLOW_CONSECUTIVE_THRESHOLD}`);
+    }
+    if (resetRecently && this.resilience.lastSuccessTs > 0 && this.resilience.lastSuccessTs < this.resilience.lastResetTs) {
+      issues.push("post-reset stall (no success since reset)");
+    }
+
+    return { transcriptMB, staleSec, errorRate: rate, errorTotal: total, overflowCount: this.resilience.consecutiveOverflowErrors, resetRecently, issues };
+  }
+
+  async runWatchdog(): Promise<void> {
+    const transcript = this.backend.getTranscriptSize();
+    const now = Date.now();
+
+    // Layer 1: Proactive session size check
+    if (transcript && transcript.bytes >= SESSION_SIZE_WARNING_BYTES) {
+      const sizeMB = (transcript.bytes / 1_000_000).toFixed(1);
+
+      if (transcript.bytes >= SESSION_SIZE_RESTART_BYTES) {
+        this.logger.warn(`sinain-hud: watchdog — transcript ${sizeMB}MB, forcing overflow reset`);
+      } else {
+        this.logger.info(`sinain-hud: watchdog — transcript ${sizeMB}MB, proactive reset`);
+      }
+
+      if (this.backend.performOverflowReset()) {
+        this.resilience.lastResetTs = now;
+        this.resilience.consecutiveOverflowErrors = 0;
+        this.backend.sendAlert("proactive_reset", "⚠️ *sinain-hud* proactive session reset",
+          `• Transcript was ${sizeMB}MB → truncated\n• No downtime expected`);
+      }
+    }
+
+    // Staleness check
+    if (this.resilience.lastSuccessTs > 0 && this.resilience.recentOutcomes.length >= 3) {
+      const staleMs = now - this.resilience.lastSuccessTs;
+
+      if (staleMs >= STALENESS_WARNING_MS && staleMs < STALENESS_CRITICAL_MS) {
+        const staleMin = Math.round(staleMs / 60_000);
+        this.backend.sendAlert("staleness_warning", "⚠️ *sinain-hud* response stale",
+          `• No successful run in ${staleMin}min\n• Error rate: ${Math.round(this.resilience.computeErrorRate().rate * 100)}%`);
+      }
+    }
+
+    // Layer 2: Emergency restart — reset didn't recover
+    if (this.resilience.lastResetTs > 0 && this.resilience.lastSuccessTs > 0 && this.resilience.lastSuccessTs < this.resilience.lastResetTs) {
+      const sinceResetMs = now - this.resilience.lastResetTs;
+      if (sinceResetMs >= STALENESS_CRITICAL_MS) {
+        const canRestart = (now - this.resilience.lastAutoRestartTs) >= AUTO_RESTART_COOLDOWN_MS;
+        if (canRestart) {
+          const staleMin = Math.round((now - this.resilience.lastSuccessTs) / 60_000);
+          this.logger.warn(`sinain-hud: EMERGENCY RESTART — reset ${Math.round(sinceResetMs / 60_000)}min ago, no recovery`);
+          await this.backend.sendAlert("emergency_restart", "🔴 *sinain-hud* EMERGENCY RESTART",
+            `• Queue jammed — reset didn't recover in ${Math.round(sinceResetMs / 60_000)}min\n• Last success: ${staleMin}min ago\n• Gateway restarting now (~5s)`);
+          this.resilience.lastAutoRestartTs = now;
+          await new Promise((r) => setTimeout(r, 1000));
+          process.exit(1);
+        } else {
+          this.logger.warn("sinain-hud: watchdog — would restart but cooldown active (max 1/hour)");
+        }
+      }
+    }
+
+    // Error rate alert
+    const { rate, total } = this.resilience.computeErrorRate();
+    if (total >= 5 && rate > 0.5) {
+      this.backend.sendAlert("high_error_rate", "⚠️ *sinain-hud* high error rate",
+        `• ${Math.round(rate * 100)}% failures over ${total} samples\n• Consecutive overflow errors: ${this.resilience.consecutiveOverflowErrors}/${OVERFLOW_CONSECUTIVE_THRESHOLD}`);
+    }
+
+    // Overflow approaching threshold
+    if (this.resilience.consecutiveOverflowErrors >= 3 && this.resilience.consecutiveOverflowErrors < OVERFLOW_CONSECUTIVE_THRESHOLD) {
+      this.backend.sendAlert("overflow_warning", "⚠️ *sinain-hud* overflow errors accumulating",
+        `• ${this.resilience.consecutiveOverflowErrors}/${OVERFLOW_CONSECUTIVE_THRESHOLD} consecutive overflow errors\n• Auto-reset will trigger at ${OVERFLOW_CONSECUTIVE_THRESHOLD}`);
+    }
+  }
+
+  start(): void {
+    this.interval = setInterval(() => {
+      this.runWatchdog().catch((err) => {
+        this.logger.warn(`sinain-hud: watchdog error: ${String(err)}`);
+      });
+    }, WATCHDOG_INTERVAL_MS);
+    this.logger.info("sinain-hud: health watchdog started (5-min interval)");
+  }
+
+  stop(): void {
+    if (this.interval) {
+      clearInterval(this.interval);
+      this.interval = null;
+    }
+  }
+}

package/sinain-knowledge/data/git-store.ts

@@ -0,0 +1,310 @@
+/**
+ * sinain-knowledge — Git-backed snapshot store
+ *
+ * Manages a local git repository for periodic knowledge snapshots.
+ * Each save overwrites snapshot.json and commits — git history IS the version history.
+ *
+ * Default location: ~/.sinain/knowledge-snapshots/
+ */
+
+import { execFileSync } from "node:child_process";
+import { copyFileSync, existsSync, mkdirSync, statSync, writeFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { homedir } from "node:os";
+
+import type { KnowledgeStore } from "./store.js";
+import { exportSnapshot, importSnapshot, resolveTriplestorePath } from "./snapshot.js";
+import type { KnowledgeSnapshot } from "./snapshot.js";
+import type { Logger } from "./schema.js";
+
+// ============================================================================
+// Constants
+// ============================================================================
+
+const DEFAULT_REPO_PATH = join(homedir(), ".sinain", "knowledge-snapshots");
+const SNAPSHOT_FILE = "snapshot.json";
+const MAX_SNAPSHOTS = 100; // prune reflog beyond this
+
+// ============================================================================
+// GitSnapshotStore
+// ============================================================================
+
+const TRIPLES_FILE = "triples.db";
+const GITATTRIBUTES_FILE = ".gitattributes";
+
+export class GitSnapshotStore {
+  private repoPath: string;
+  private logger: Logger;
+  private remoteChecked = false;
+
+  constructor(repoPath?: string, logger?: Logger) {
+    this.repoPath = resolve(repoPath ?? DEFAULT_REPO_PATH);
+    this.logger = logger ?? { info: console.log, warn: console.warn };
+  }
+
+  // ── Git helpers ──────────────────────────────────────────────────────────
+
+  private git(...args: string[]): string {
+    return execFileSync("git", args, {
+      cwd: this.repoPath,
+      encoding: "utf-8",
+      timeout: 15_000,
+    }).trim();
+  }
+
+  private async ensureRepo(): Promise<void> {
+    if (!existsSync(this.repoPath)) {
+      mkdirSync(this.repoPath, { recursive: true });
+    }
+
+    const gitDir = join(this.repoPath, ".git");
+    if (!existsSync(gitDir)) {
+      this.git("init");
+      this.git("config", "user.name", "sinain-knowledge");
+      this.git("config", "user.email", "sinain@local");
+
+      // Ensure binary handling for triplestore
+      const gitattrsPath = join(this.repoPath, GITATTRIBUTES_FILE);
+      if (!existsSync(gitattrsPath)) {
+        writeFileSync(gitattrsPath, `${TRIPLES_FILE} binary\n`, "utf-8");
+      }
+
+      this.logger.info(`sinain-knowledge: initialized snapshot repo at ${this.repoPath}`);
+    }
+
+    await this.validateRemoteVisibility();
+  }
+
+  // ── Public repo guard ─────────────────────────────────────────────────
+
+  private async validateRemoteVisibility(): Promise<void> {
+    if (this.remoteChecked) return;
+
+    let remotes: string;
+    try {
+      remotes = this.git("remote", "-v");
+    } catch {
+      this.remoteChecked = true;
+      return; // no remotes
+    }
+    if (!remotes) { this.remoteChecked = true; return; }
+
+    const githubPattern = /github\.com[:/]([^/]+)\/([^/.]+)/;
+    const checked = new Set<string>();
+
+    for (const line of remotes.split("\n")) {
+      const match = line.match(githubPattern);
+      if (!match) {
+        // Non-GitHub remote — warn and skip
+        const remoteName = line.split(/\s/)[0];
+        if (remoteName && !line.includes("github.com")) {
+          this.logger.warn(
+            `sinain-knowledge: remote '${remoteName}' is not GitHub — skipping visibility check`,
+          );
+        }
+        continue;
+      }
+      const [, owner, repo] = match;
+      const key = `${owner}/${repo}`;
+      if (checked.has(key)) continue; // deduplicate fetch/push lines
+      checked.add(key);
+
+      const remoteName = line.split(/\s/)[0];
+      try {
+        const resp = await fetch(`https://api.github.com/repos/${owner}/${repo}`);
+        if (resp.ok) {
+          const data = await resp.json() as { private: boolean };
+          if (data.private === false) {
+            throw new Error(
+              `Refusing to save: remote '${remoteName}' points to public repo ${owner}/${repo}. ` +
+              `Knowledge snapshots contain sensitive data and must only be stored in private repositories.`,
+            );
+          }
+        }
+        // 404 = private (or doesn't exist) → safe
+      } catch (err) {
+        // Re-throw our own Error, swallow network failures
+        if (err instanceof Error && err.message.startsWith("Refusing to save")) throw err;
+        this.logger.warn(
+          `sinain-knowledge: could not check visibility of ${key}: ${String(err)}`,
+        );
+      }
+    }
+
+    this.remoteChecked = true;
+  }
+
+  // ── Save ─────────────────────────────────────────────────────────────────
+
+  /**
+   * Export a snapshot from the store and commit it to the local git repo.
+   * Returns the short commit hash.
+   */
+  async save(store: KnowledgeStore): Promise<string> {
+    await this.ensureRepo();
+
+    // Export snapshot WITHOUT triplestore (avoid loading GB of data into memory)
+    const snapshot = exportSnapshot(store, { skipTriplestore: true });
+    const snapshotPath = join(this.repoPath, SNAPSHOT_FILE);
+
+    // Copy triplestore directly as binary — no base64 round-trip
+    const srcDbPath = resolveTriplestorePath(store.getWorkspaceDir());
+    const hasTriples = srcDbPath !== null;
+    if (hasTriples) {
+      copyFileSync(srcDbPath, join(this.repoPath, TRIPLES_FILE));
+      const size = statSync(srcDbPath).size;
+      (snapshot as any).triplestore = { dbFile: TRIPLES_FILE, sizeBytes: size };
+    }
+
+    // Write snapshot with stable key ordering for minimal diffs
+    writeFileSync(snapshotPath, JSON.stringify(snapshot, null, 2) + "\n", "utf-8");
+
+    // Stage both files
+    const filesToStage = [SNAPSHOT_FILE];
+    if (hasTriples) filesToStage.push(TRIPLES_FILE);
+    this.git("add", ...filesToStage);
+
+    // Check if there are staged changes
+    try {
+      this.git("diff", "--cached", "--quiet");
+      // No changes — skip commit
+      this.logger.info("sinain-knowledge: snapshot unchanged, skipping commit");
+      return this.git("rev-parse", "--short", "HEAD");
+    } catch {
+      // diff --cached --quiet exits non-zero when there ARE changes — this is the expected path
+    }
+
+    // Build commit message
+    const ts = snapshot.exportedAt;
+    const playbookLines = snapshot.playbook.effective.split("\n").length;
+    const moduleCount = snapshot.modules.items.length;
+
+    const message = [
+      `snapshot ${ts.slice(0, 19).replace("T", " ")}`,
+      "",
+      `Playbook: ${playbookLines} lines`,
+      `Modules: ${moduleCount}`,
+      `Triplestore: ${hasTriples ? "yes" : "empty"}`,
+      `Source: ${snapshot.exportedFrom}`,
+      `Integrity: ${snapshot.integrity.slice(0, 12)}…`,
+    ].join("\n");
+
+    this.git("commit", "-m", message);
+    const hash = this.git("rev-parse", "--short", "HEAD");
+    this.logger.info(`sinain-knowledge: snapshot saved → ${hash}`);
+    return hash;
+  }
+
+  // ── List ─────────────────────────────────────────────────────────────────
+
+  /**
+   * List recent snapshots from git log.
+   * Returns an array of { hash, date, subject } objects.
+   */
+  async list(count = 20): Promise<Array<{ hash: string; date: string; subject: string }>> {
+    await this.ensureRepo();
+
+    try {
+      const log = this.git(
+        "log",
+        `--max-count=${count}`,
+        "--format=%h\t%ai\t%s",
+      );
+      if (!log) return [];
+
+      return log.split("\n").map((line) => {
+        const [hash, date, subject] = line.split("\t");
+        return { hash, date, subject };
+      });
+    } catch {
+      return []; // empty repo
+    }
+  }
+
+  // ── Restore ──────────────────────────────────────────────────────────────
+
+  /**
+   * Read a snapshot from a specific git commit (or HEAD).
+   * Reconstitutes triplestore base64 from separate binary file if needed.
+   */
+  async read(ref = "HEAD"): Promise<KnowledgeSnapshot> {
+    await this.ensureRepo();
+    const content = this.git("show", `${ref}:${SNAPSHOT_FILE}`);
+    const snapshot = JSON.parse(content);
+
+    // Reconstitute base64 from separate binary file (new format)
+    if (snapshot.triplestore?.dbFile) {
+      try {
+        const dbBuf = execFileSync("git", ["show", `${ref}:${TRIPLES_FILE}`], {
+          cwd: this.repoPath,
+          timeout: 15_000,
+        });
+        snapshot.triplestore = { dbBase64: dbBuf.toString("base64") };
+      } catch {
+        // triples.db missing for this commit — treat as empty
+        snapshot.triplestore = { dbBase64: "" };
+      }
+    }
+    // Old format with inline dbBase64 — pass through unchanged
+
+    return snapshot as KnowledgeSnapshot;
+  }
+
+  /**
+   * Restore a snapshot from a git commit into the knowledge store.
+   */
+  async restore(store: KnowledgeStore, ref = "HEAD"): Promise<void> {
+    const snapshot = await this.read(ref);
+    importSnapshot(store, snapshot);
+    this.logger.info(`sinain-knowledge: restored snapshot from ${ref}`);
+  }
+
+  // ── Diff ─────────────────────────────────────────────────────────────────
+
+  /**
+   * Show what changed between two snapshots (defaults to last two commits).
+   */
+  async diff(fromRef = "HEAD~1", toRef = "HEAD"): Promise<string> {
+    await this.ensureRepo();
+    try {
+      return this.git("diff", "--stat", fromRef, toRef);
+    } catch {
+      return "(no diff available)";
+    }
+  }
+
+  // ── Prune ────────────────────────────────────────────────────────────────
+
+  /**
+   * Prune old snapshots by squashing history beyond maxSnapshots.
+   * Uses reflog expire + gc to reclaim space.
+   */
+  async prune(maxSnapshots = MAX_SNAPSHOTS): Promise<void> {
+    await this.ensureRepo();
+    try {
+      const count = parseInt(this.git("rev-list", "--count", "HEAD"), 10);
+      if (count <= maxSnapshots) return;
+
+      this.git("reflog", "expire", "--expire=now", "--all");
+      this.git("gc", "--prune=now", "--quiet");
+      this.logger.info(`sinain-knowledge: pruned snapshot repo (${count} commits, gc'd)`);
+    } catch {
+      // gc failure is non-critical
+    }
+  }
+
+  // ── Info ──────────────────────────────────────────────────────────────────
+
+  getRepoPath(): string {
+    return this.repoPath;
+  }
+
+  async getSnapshotCount(): Promise<number> {
+    await this.ensureRepo();
+    try {
+      return parseInt(this.git("rev-list", "--count", "HEAD"), 10);
+    } catch {
+      return 0;
+    }
+  }
+}