agent-recall-core 3.4.31 → 3.4.36

package/dist/tools-logic/store-doctor.js

@@ -0,0 +1,387 @@
+/**
+ * store-doctor.ts — READ-ONLY integrity diagnostics for the on-disk store.
+ *
+ * This is the round-table's integrity recommendation: a sibling to
+ * `palace-lint.ts`, NOT an extension of it. The distinction is deliberate:
+ *
+ *   - palace-lint  = per-project CONTENT hygiene (stale rooms, orphans, low
+ *                    salience). It MUTATES (auto-archives) when `fix:true`.
+ *   - store-doctor = STORE-level structural integrity across ALL projects:
+ *                    index↔disk drift, stuck locks, broken dreaming, orphaned
+ *                    consume markers. It is strictly READ-ONLY.
+ *
+ * HARD INVARIANTS:
+ *   1. NEVER mutates. No write, no mkdir, no rename, no unlink. Only fs reads.
+ *   2. NEVER acquires a write lock. It must run — and return — even while
+ *      another process holds a palace/room lock (no deadlock, no blocking).
+ *   3. NEVER throws to the caller. Any per-check failure degrades that check to
+ *      a best-effort result; the doctor as a whole always returns.
+ *
+ * It is safe to call on the session_start hot path because it does no locking
+ * and bounds its work to directory listings + small JSON/markdown reads.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { getRoot } from "../types.js";
+import { readJsonSafe } from "../storage/fs-utils.js";
+import { listAllProjects } from "../storage/project.js";
+import { countRoomEntries } from "../palace/rooms.js";
+import { palaceDir, archiveRawDir } from "../storage/paths.js";
+import { STALE_LOCK_MS } from "../storage/filelock.js";
+import { getDreamHealth } from "../storage/dream-health.js";
+import { resolveRetentionDays } from "../storage/retention.js";
+// ───────────────────────────────────────────────────────────────────────────
+// Tunable thresholds (documented; not data-fit — see MATH.md §a for the broader
+// "hand-tuned" stance). All are policy knobs for WHEN to surface a warning.
+// ───────────────────────────────────────────────────────────────────────────
+/**
+ * Index-vs-disk drift tolerance, in ENTRY COUNT, per room. A drift of exactly 1
+ * is tolerated because a single in-flight palace write can land a `### ` block
+ * on disk before `updatePalaceIndex()` refreshes the cached `memory_count`
+ * (the room .md is the source of truth, the index is a derived cache). A drift
+ * of 2+ means the index is genuinely out of sync → RED.
+ */
+export const INDEX_DRIFT_TOLERANCE = 1;
+/** A held lock older than this is escalated from WARN (merely stale) to RED. */
+export const LOCK_RED_MS = 5 * 60 * 1000; // 5 minutes
+/**
+ * A `.consumed.json` marker that has NEVER advanced (lastConsumedAt null/absent)
+ * while raw segments older than this sit in the archive → WARN. It signals the
+ * login-free consolidation seam (which advances the marker at every session_end)
+ * has not run even once for that project — a silently-failing `advanceConsumeMarker`
+ * — WITHOUT the false positive of flagging a day-old fresh store. Distinct from
+ * the RED retention window (resolved live via resolveRetentionDays) so the two
+ * severities can't be conflated.
+ */
+export const DREAM_NULL_MARKER_WARN_DAYS = 7;
+// ───────────────────────────────────────────────────────────────────────────
+// Helpers
+// ───────────────────────────────────────────────────────────────────────────
+/** Roll the highest level seen so far. red > warn > ok. */
+function maxLevel(a, b) {
+    if (a === "red" || b === "red")
+        return "red";
+    if (a === "warn" || b === "warn")
+        return "warn";
+    return "ok";
+}
+/** Reduce all check levels into one overall status. */
+function rollupStatus(checks) {
+    return checks.reduce((acc, c) => maxLevel(acc, c.level), "ok");
+}
+function safeReaddir(dir) {
+    try {
+        return fs.existsSync(dir) ? fs.readdirSync(dir) : [];
+    }
+    catch {
+        return [];
+    }
+}
+// ───────────────────────────────────────────────────────────────────────────
+// Check 1 — VECTOR-INDEX vs .md DRIFT
+// ───────────────────────────────────────────────────────────────────────────
+/**
+ * For every project, compare the palace-index.json cached `memory_count` for
+ * each room against the LIVE `### ` block count in that room's .md files.
+ * A per-room drift greater than INDEX_DRIFT_TOLERANCE flips the check to RED.
+ *
+ * READ-ONLY: reads the index JSON and counts blocks via countRoomEntries (which
+ * is itself read-only and lock-free). Never calls updatePalaceIndex().
+ */
+function checkIndexDrift() {
+    const base = {
+        name: "vector_index_drift",
+        level: "ok",
+        detail: "palace-index.json memory_count matches on-disk `### ` block counts.",
+        fix_hint: "",
+    };
+    const drifts = [];
+    let level = "ok";
+    try {
+        for (const proj of listAllProjects()) {
+            const idxPath = path.join(palaceDir(proj.slug), "palace-index.json");
+            const index = readJsonSafe(idxPath);
+            if (!index || !index.rooms)
+                continue;
+            for (const [slug, room] of Object.entries(index.rooms)) {
+                const indexed = room?.memory_count ?? 0;
+                const live = countRoomEntries(proj.slug, slug);
+                const delta = Math.abs(indexed - live);
+                if (delta > INDEX_DRIFT_TOLERANCE) {
+                    level = "red";
+                    drifts.push(`${proj.slug}/${slug}: index=${indexed} disk=${live} (Δ${delta})`);
+                }
+            }
+        }
+    }
+    catch {
+        // Degrade to ok-with-note rather than throwing — never break orientation.
+        return {
+            ...base,
+            detail: "index-drift scan could not complete (store unreadable); skipped.",
+        };
+    }
+    if (level === "red") {
+        return {
+            name: "vector_index_drift",
+            level,
+            detail: `Index/disk drift > ${INDEX_DRIFT_TOLERANCE} entry in ${drifts.length} room(s): ${drifts.slice(0, 8).join("; ")}`,
+            fix_hint: "Run `ar palace lint` (or palaceWrite once) on the affected project to rebuild palace-index.json from the .md source of truth.",
+        };
+    }
+    return base;
+}
+// ───────────────────────────────────────────────────────────────────────────
+// Check 2 — STALE / FORCE-BROKEN LOCK
+// ───────────────────────────────────────────────────────────────────────────
+/**
+ * Scan getRoot()/.lock-* dirs. A lock whose mtime is older than STALE_LOCK_MS
+ * is WARN (it will be force-broken on the next acquire, but its presence hints
+ * a process crashed mid-write); older than LOCK_RED_MS is RED.
+ *
+ * READ-ONLY: stat only. Does NOT remove the lock (acquireLock does that); the
+ * doctor only reports. Never blocks waiting for a lock.
+ */
+function checkStaleLock() {
+    const base = {
+        name: "stale_lock",
+        level: "ok",
+        detail: "No stale .lock-* directories.",
+        fix_hint: "",
+    };
+    let level = "ok";
+    const offenders = [];
+    const now = Date.now();
+    try {
+        const root = getRoot();
+        for (const entry of safeReaddir(root)) {
+            if (!entry.startsWith(".lock-"))
+                continue;
+            const full = path.join(root, entry);
+            let ageMs;
+            try {
+                ageMs = now - fs.statSync(full).mtimeMs;
+            }
+            catch {
+                continue; // raced with a release — fine, it's gone
+            }
+            if (ageMs > LOCK_RED_MS) {
+                level = maxLevel(level, "red");
+                offenders.push(`${entry} (${Math.round(ageMs / 60000)}m old)`);
+            }
+            else if (ageMs > STALE_LOCK_MS) {
+                level = maxLevel(level, "warn");
+                offenders.push(`${entry} (${Math.round(ageMs / 1000)}s old)`);
+            }
+        }
+    }
+    catch {
+        return base;
+    }
+    if (level === "ok")
+        return base;
+    return {
+        name: "stale_lock",
+        level,
+        detail: `${offenders.length} stale lock dir(s): ${offenders.slice(0, 8).join(", ")}.`,
+        fix_hint: level === "red"
+            ? "A writer likely crashed. After confirming no `ar` process is running, remove the stale `.lock-*` dir under ~/.agent-recall."
+            : "Lock is older than the stale threshold; it will be auto-broken on the next write. Investigate if it persists.",
+    };
+}
+// ───────────────────────────────────────────────────────────────────────────
+// Check 3 — STALLED CONSOLIDATION SEAM
+// ───────────────────────────────────────────────────────────────────────────
+/**
+ * Dreaming/consolidation health. Severity tiers:
+ *
+ *   RED  — (a) the AAM LLM dream cron is actively failing (getDreamHealth banner,
+ *          the known OAuth/network-expiry mode), OR (b) a raw segment OLDER than
+ *          the retention window is still UNCONSUMED (mtime newer than the
+ *          `.consumed.json` marker) → the seam that folds raw into the palace and
+ *          prunes the backup has stalled, so the archive will grow unbounded.
+ *   WARN — the marker has NEVER advanced (null/absent) while raw segments older
+ *          than DREAM_NULL_MARKER_WARN_DAYS exist → the login-free seam (which
+ *          advances the marker at every session_end) likely failed silently for
+ *          that project, even though nothing is unbounded yet.
+ *   OK   — everything else, notably a login-free store whose raw is all RECENT.
+ *          That is the normal lossless backup buffer: the content is already
+ *          regex-folded into the palace at session_end and the segments simply
+ *          await their retention-window prune. The earlier "consumed within 24h"
+ *          rule false-positived on EVERY healthy login-free store; anchoring on
+ *          the (config-resolved) retention window fixes that without going blind
+ *          to a genuinely stuck marker (the WARN tier).
+ *
+ * The retention window is resolved LIVE (resolveRetentionDays) from the SAME
+ * source the pruner uses, so the doctor can never flag at a different threshold
+ * than safety-consolidation actually prunes at.
+ *
+ * READ-ONLY: directory listing + per-segment stat + marker read + dream log read.
+ */
+function checkDreamingStale() {
+    const base = {
+        name: "dreaming_stale",
+        level: "ok",
+        detail: "Consolidation seam healthy: no raw segment older than the retention window is unconsumed.",
+        fix_hint: "",
+    };
+    const now = Date.now();
+    const DAY_MS = 24 * 60 * 60 * 1000;
+    const retentionMs = resolveRetentionDays() * DAY_MS;
+    const warnMs = DREAM_NULL_MARKER_WARN_DAYS * DAY_MS;
+    const agedUnconsumed = []; // RED evidence (project slugs)
+    const nullMarkerStale = []; // WARN evidence (project slugs)
+    try {
+        for (const proj of listAllProjects()) {
+            const rawDir = archiveRawDir(proj.slug);
+            const rawFiles = safeReaddir(rawDir).filter((f) => f.endsWith(".md") && f !== "index.md");
+            if (rawFiles.length === 0)
+                continue;
+            const marker = readJsonSafe(path.join(rawDir, ".consumed.json"));
+            const lastConsumed = marker?.lastConsumedAt ?? null;
+            const markerNeverAdvanced = lastConsumed === null;
+            const lastMs = lastConsumed ? new Date(lastConsumed).getTime() : 0;
+            let projAged = false;
+            let projNullStale = false;
+            for (const f of rawFiles) {
+                let mtime;
+                try {
+                    mtime = fs.statSync(path.join(rawDir, f)).mtimeMs;
+                }
+                catch {
+                    continue; // raced with a prune — skip
+                }
+                const age = now - mtime;
+                const unconsumed = mtime > lastMs; // matches pruneRawArchive's `mtime <= lastConsumedAt` consumed contract
+                if (age > retentionMs && unconsumed) {
+                    projAged = true;
+                    break; // RED beats WARN — no need to look further in this project
+                }
+                if (markerNeverAdvanced && age > warnMs) {
+                    projNullStale = true;
+                }
+            }
+            if (projAged)
+                agedUnconsumed.push(proj.slug);
+            else if (projNullStale)
+                nullMarkerStale.push(proj.slug);
+        }
+    }
+    catch {
+        return base; // unreadable store → don't fabricate a failure
+    }
+    // Independent signal: AAM dream cron failure streak (auth/network expiry).
+    let dreamBanner = null;
+    try {
+        dreamBanner = getDreamHealth().banner;
+    }
+    catch {
+        dreamBanner = null;
+    }
+    // RED tier — genuine unbounded growth or an actively-failing cron.
+    if (agedUnconsumed.length > 0 || dreamBanner) {
+        const parts = [];
+        if (agedUnconsumed.length > 0) {
+            parts.push(`${agedUnconsumed.length} project(s) with raw older than the retention window still unconsumed: ${agedUnconsumed.slice(0, 6).join(", ")}`);
+        }
+        if (dreamBanner)
+            parts.push(dreamBanner);
+        return {
+            name: "dreaming_stale",
+            level: "red",
+            detail: `Consolidation seam appears stalled: ${parts.join(" · ")}`,
+            fix_hint: "Run `ar repair --apply` (login-free drain: advances the consume marker + prunes aged raw). If the dream-cron banner is set, also check the dreaming agent's auth (known OAuth-expiry mode).",
+        };
+    }
+    // WARN tier — a marker that never advanced while raw aged past the warn floor.
+    if (nullMarkerStale.length > 0) {
+        return {
+            name: "dreaming_stale",
+            level: "warn",
+            detail: `${nullMarkerStale.length} project(s) have raw segments older than ${DREAM_NULL_MARKER_WARN_DAYS}d but a consume marker that never advanced (login-free seam may have failed silently): ${nullMarkerStale.slice(0, 6).join(", ")}.`,
+            fix_hint: "Run `ar repair --apply` to drain (advances the consume marker). If it recurs, the session_end safety-consolidation pass is not firing for that project.",
+        };
+    }
+    return base;
+}
+// ───────────────────────────────────────────────────────────────────────────
+// Check 4 — ORPHANED CONSUME MARKERS
+// ───────────────────────────────────────────────────────────────────────────
+/**
+ * A `.consumed.json` claiming progress (lastConsumedAt set) but whose raw
+ * archive directory has NO raw .md segments is an orphan — the marker outlived
+ * the data it tracked (manual rm, prune bug, or a half-restored backup). It
+ * means the consume seam can never reconcile → WARN, escalating to RED when
+ * several projects show the same orphan (systemic, not a one-off).
+ *
+ * READ-ONLY: directory listing + marker read only.
+ */
+function checkOrphanedConsumeMarkers() {
+    const base = {
+        name: "orphaned_consume_marker",
+        level: "ok",
+        detail: "No orphaned .consumed.json markers.",
+        fix_hint: "",
+    };
+    const orphans = [];
+    try {
+        for (const proj of listAllProjects()) {
+            const rawDir = archiveRawDir(proj.slug);
+            const markerPath = path.join(rawDir, ".consumed.json");
+            if (!fs.existsSync(markerPath))
+                continue;
+            const marker = readJsonSafe(markerPath);
+            // Only a marker that claims progress is an "orphan" risk; a freshly seeded
+            // marker (lastConsumedAt=null) with no data is the normal empty state.
+            if (!marker || marker.lastConsumedAt === null)
+                continue;
+            const rawFiles = safeReaddir(rawDir).filter((f) => f.endsWith(".md") && f !== "index.md");
+            if (rawFiles.length === 0) {
+                orphans.push(proj.slug);
+            }
+        }
+    }
+    catch {
+        return base;
+    }
+    if (orphans.length === 0)
+        return base;
+    const level = orphans.length >= 3 ? "red" : "warn";
+    return {
+        name: "orphaned_consume_marker",
+        level,
+        detail: `${orphans.length} project(s) have a .consumed.json claiming progress but no raw segments: ${orphans.slice(0, 8).join(", ")}.`,
+        fix_hint: "The consume marker outlived its raw archive (manual delete or prune bug). Verify backups; re-seeding the marker or restoring the raw segments reconciles the seam.",
+    };
+}
+// ───────────────────────────────────────────────────────────────────────────
+// Public entry point
+// ───────────────────────────────────────────────────────────────────────────
+/**
+ * Run all integrity checks. READ-ONLY, lock-free, never throws.
+ * `status` is the worst level across checks ('ok' | 'warn' | 'red').
+ */
+export function runStoreDoctor() {
+    const checks = [
+        checkIndexDrift(),
+        checkStaleLock(),
+        checkDreamingStale(),
+        checkOrphanedConsumeMarkers(),
+    ];
+    return { status: rollupStatus(checks), checks };
+}
+/**
+ * One-line health summary for the session_start hot path. Returns null when
+ * status === 'ok' so callers can stay SILENT on a healthy store (never block
+ * recall). On warn/red, returns a compact, single-line banner naming the
+ * failing checks.
+ */
+export function storeDoctorBanner(result = runStoreDoctor()) {
+    if (result.status === "ok")
+        return null;
+    const flagged = result.checks.filter((c) => c.level !== "ok");
+    const icon = result.status === "red" ? "⛔" : "⚠";
+    const names = flagged.map((c) => `${c.name}[${c.level}]`).join(", ");
+    return `${icon} store-doctor: ${result.status.toUpperCase()} — ${names}. Run \`ar doctor\` for detail.`;
+}
+//# sourceMappingURL=store-doctor.js.map

package/dist/tools-logic/store-doctor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"store-doctor.js","sourceRoot":"","sources":["../../src/tools-logic/store-doctor.ts"],"names":[],"mappings":"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"}

package/dist/tools-logic/store-repair.d.ts

@@ -0,0 +1,64 @@
+/**
+ * store-repair.ts — WRITE-side remediation, the deliberate sibling to the
+ * read-only store-doctor.ts.
+ *
+ *   store-doctor   = DIAGNOSE. Strictly read-only, lock-free, never throws.
+ *   store-repair   = REMEDIATE. Re-derives the same conditions the doctor
+ *                    detects and applies the minimal, idempotent fix each
+ *                    `fix_hint` prescribes.
+ *
+ * SAFETY INVARIANTS:
+ *   1. DRY-RUN BY DEFAULT. `opts.apply` must be EXPLICITLY true to mutate. A
+ *      dry-run computes the full plan (what WOULD change) and writes nothing.
+ *   2. PER-STEP ISOLATION. Each step runs in its own try/catch (mirrors
+ *      safety-consolidation.ts) — one failing step never aborts the others.
+ *   3. IDEMPOTENT. A re-run on an already-clean store is a no-op: drift is
+ *      recomputed from disk truth, locks are re-scanned, and the consume marker
+ *      the drain advances is monotonic.
+ *   4. LOCK SAFETY. Only `.lock-*` dirs older than LOCK_RED_MS (the doctor's RED
+ *      threshold) are removed. The locker's acquire timeout is 5s and it
+ *      force-breaks stale locks at 30s, so a dir older than 5min cannot belong
+ *      to a live writer — removal is safe WITHOUT scanning for processes.
+ *
+ * NOT on any hot path. Invoked manually via `ar repair [--apply]`.
+ */
+import { type StoreDoctorResult } from "./store-doctor.js";
+export interface RepairStepProjects {
+    /** Projects this step acted on (or WOULD act on, in dry-run). */
+    projects: string[];
+    error?: string;
+}
+export interface RepairStepLocks {
+    /** `.lock-*` dir names removed (or that WOULD be, in dry-run). */
+    names: string[];
+    error?: string;
+}
+export interface RepairSnapshot {
+    status: StoreDoctorResult["status"];
+    /** Names of checks at RED level. */
+    red: string[];
+}
+export interface StoreRepairResult {
+    /** false = dry-run (default). true = mutations were applied. */
+    apply: boolean;
+    /** Doctor status BEFORE any repair. */
+    before: RepairSnapshot;
+    reindexed: RepairStepProjects;
+    locksRemoved: RepairStepLocks;
+    drained: RepairStepProjects;
+    /** Doctor status AFTER applying — null in dry-run (nothing changed to re-check). */
+    after: RepairSnapshot | null;
+}
+export interface StoreRepairOptions {
+    /** Must be EXPLICITLY true to mutate. Default false (dry-run). */
+    apply?: boolean;
+}
+/**
+ * Run all repairs. DRY-RUN unless `opts.apply === true`. Each step is isolated;
+ * the result reports exactly what was (or would be) changed, plus the doctor
+ * status before and (when applied) after.
+ */
+export declare function runStoreRepair(opts?: StoreRepairOptions): Promise<StoreRepairResult>;
+/** One-line summary for CLI / logs. */
+export declare function storeRepairSummary(r: StoreRepairResult): string;
+//# sourceMappingURL=store-repair.d.ts.map

package/dist/tools-logic/store-repair.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"store-repair.d.ts","sourceRoot":"","sources":["../../src/tools-logic/store-repair.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAYH,OAAO,EAKL,KAAK,iBAAiB,EACvB,MAAM,mBAAmB,CAAC;AAG3B,MAAM,WAAW,kBAAkB;IACjC,iEAAiE;IACjE,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,eAAe;IAC9B,kEAAkE;IAClE,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,iBAAiB,CAAC,QAAQ,CAAC,CAAC;IACpC,oCAAoC;IACpC,GAAG,EAAE,MAAM,EAAE,CAAC;CACf;AAED,MAAM,WAAW,iBAAiB;IAChC,gEAAgE;IAChE,KAAK,EAAE,OAAO,CAAC;IACf,uCAAuC;IACvC,MAAM,EAAE,cAAc,CAAC;IACvB,SAAS,EAAE,kBAAkB,CAAC;IAC9B,YAAY,EAAE,eAAe,CAAC;IAC9B,OAAO,EAAE,kBAAkB,CAAC;IAC5B,oFAAoF;IACpF,KAAK,EAAE,cAAc,GAAG,IAAI,CAAC;CAC9B;AAED,MAAM,WAAW,kBAAkB;IACjC,kEAAkE;IAClE,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAuHD;;;;GAIG;AACH,wBAAsB,cAAc,CAClC,IAAI,GAAE,kBAAuB,GAC5B,OAAO,CAAC,iBAAiB,CAAC,CAwE5B;AAED,uCAAuC;AACvC,wBAAgB,kBAAkB,CAAC,CAAC,EAAE,iBAAiB,GAAG,MAAM,CAS/D"}