hippo-memory 1.49.0 → 1.51.0

package/dist/api.d.ts

@@ -11,6 +11,7 @@ import { deleteEntry, loadAllEntries, type TaskSnapshot, type SessionEvent } fro
 import { type RejectedValueRow } from './rejection.js';
 import { type DormantMemory, type ListDormantOpts } from './dormant.js';
 import { type TokenSummary, type TokenSurface } from './token-ledger.js';
+import { type QuarantineStatus } from './quarantine.js';
 import { type FailureSummary } from './failure-log.js';
 import { type SessionHandoff } from './handoff.js';
 import { type MemoryKind, type MemoryEntry } from './memory.js';
@@ -110,11 +111,17 @@ export interface RememberOpts {
      * back and the error is rethrown.
      */
     afterWrite?: (db: DatabaseSyncLike, memoryId: string) => void;
+    /** CD5: connector-ingested content an agent doesn't control; gates detectInstruction. CLI/HTTP/MCP never set this. */
+    untrusted?: boolean;
 }
 export interface RememberResult {
     id: string;
     kind: MemoryKind;
     tenantId: string;
+    /** Set only when untrusted content was flagged and quarantined instead of stored under its requested scope. */
+    quarantined?: {
+        reason: string;
+    };
 }
 export declare function remember(ctx: Context, opts: RememberOpts): RememberResult;
 export interface RecallOpts {
@@ -1061,6 +1068,25 @@ export declare function restoreDormant(ctx: Context, id: string): MemoryEntry;
 export declare function forgetDormant(ctx: Context, id: string): void;
 /** Whether the tenant holds a dormant memory with this id (for "not found" hints). */
 export declare function isDormant(ctx: Context, id: string): boolean;
+export interface QuarantineListItem {
+    id: string;
+    originalScope: string | null;
+    reason: string;
+    status: QuarantineStatus;
+    quarantinedAt: string;
+    decidedAt: string | null;
+    decidedBy: string | null;
+    contentPreview: string;
+}
+/** A tenant's quarantined memories, newest first. Default `status` is 'pending' (the review queue). */
+export declare function quarantineList(ctx: Context, opts?: {
+    status?: QuarantineStatus | 'all';
+    limit?: number;
+}): QuarantineListItem[];
+/** Release a quarantined memory to its original scope. Admin only; the scope guard refuses a row moved since (mirrors restoreDormant). */
+export declare function quarantineApprove(ctx: Context, id: string): void;
+/** Keep a quarantined memory hidden for good. Admin only; the raw row is untouched (append-only). */
+export declare function quarantineReject(ctx: Context, id: string): void;
 export interface SleepResult {
     active: number;
     removed: number;

package/dist/api.js

@@ -13,9 +13,11 @@ import { RejectedValueError } from './rejection.js';
 import { rejectValue, unrejectValue, listRejectionsForTenant } from './reject-flow.js';
 import { listDormantRows, readDormantSnapshot, deleteDormantRow, hasDormantRow, } from './dormant.js';
 import { recordTokenUse, summarizeTokenUse } from './token-ledger.js';
+import { detectInstruction } from './instruction-detect.js';
+import { quarantineScopeFor, recordQuarantine, getQuarantineRow, listQuarantineRows, approveQuarantineRow, rejectQuarantineRow, } from './quarantine.js';
 import { summarizeFailures } from './failure-log.js';
 import { formatHandoffEvidenceLine } from './handoff.js';
-import { createMemory, applyOutcome, calculateStrength, Layer, } from './memory.js';
+import { createMemory, applyOutcome, calculateStrength, Layer, CHURN_STALE_TAG, } from './memory.js';
 import { appendAuditEvent, queryAuditEvents, auditMemories, isContentWorthStoring, } from './audit.js';
 import { promoteToGlobal, getGlobalRoot, autoShare, searchBothHybrid } from './shared.js';
 import { writeRecallTrace, writeRecallTraceAtRoot, recordTraceOutcome } from './recall-trace.js';
@@ -23,7 +25,7 @@ import { evalNow } from './ablation.js';
 import { archiveRawMemory } from './raw-archive.js';
 import { createApiKey, listApiKeys, revokeApiKey, grantScope, ungrantScope, } from './auth.js';
 import { applyGoalStackBoost } from './goals.js';
-import { markRetrieved, estimateTokens, hybridSearch, physicsSearch } from './search.js';
+import { markRetrieved, estimateTokens, hybridSearch, physicsSearch, churnStaleFactor } from './search.js';
 import { compareEntryIdentity, compareScoredResults } from './compare.js';
 import { scopeMatch } from './scope.js';
 import { consolidate } from './consolidate.js';
@@ -140,9 +142,11 @@ function loadAmbientEntries(hippoRoot, tenantId, pinnedOnly, includeRecent, admi
     return loadAmbientCandidates(hippoRoot, tenantId, includeRecent, admitAmbient);
 }
 export function remember(ctx, opts) {
+    const detection = opts.untrusted ? detectInstruction(opts.content) : { flagged: false, reason: null };
+    const requestedScope = opts.scope ?? null;
     const entry = createMemory(opts.content, {
         kind: opts.kind ?? 'distilled',
-        scope: opts.scope ?? null,
+        scope: detection.flagged ? quarantineScopeFor(requestedScope) : requestedScope,
         owner: opts.owner ?? null,
         artifact_ref: opts.artifactRef ?? null,
         tags: opts.tags,
@@ -151,8 +155,23 @@ export function remember(ctx, opts) {
     });
     // writeEntry threads ctx.actor.subject into its internal audit hook, so exactly
     // one 'remember' event lands in the log with the supplied actor.
-    writeEntry(ctx.hippoRoot, entry, { actor: ctx.actor.subject, afterWrite: opts.afterWrite });
-    return { id: entry.id, kind: entry.kind, tenantId: ctx.tenantId };
+    const afterWrite = detection.flagged
+        ? (db, memoryId) => {
+            recordQuarantine(db, {
+                tenantId: ctx.tenantId,
+                memoryId,
+                originalScope: requestedScope,
+                reason: detection.reason ?? 'unknown',
+                actor: ctx.actor.subject,
+            });
+            opts.afterWrite?.(db, memoryId);
+        }
+        : opts.afterWrite;
+    writeEntry(ctx.hippoRoot, entry, { actor: ctx.actor.subject, afterWrite });
+    const result = { id: entry.id, kind: entry.kind, tenantId: ctx.tenantId };
+    if (detection.flagged)
+        result.quarantined = { reason: detection.reason ?? 'unknown' };
+    return result;
 }
 /**
  * Shared construction helper for `RecallSuppressionSummary`. Used by
@@ -294,6 +313,10 @@ function recallFrom(ctx, opts, windowSize, all) {
     // for api.recall; cmdRecall pipeline rolls --outcome/--layer/--as-of/etc.
     // into the same field per the plan's Task 3 mapping table).
     droppedPreRankCount = all.length - entries.length;
+    entries = entries
+        .map((e, i) => ({ e, s: (1 - i / entries.length) * churnStaleFactor(e) }))
+        .sort((a, b) => b.s - a.s)
+        .map((r) => r.e);
     // BM25 ordering already comes from loadRecallSearchEntries; cap to `limit`.
     // Score is a placeholder — the physics/hybrid scorers in src/search.ts
     // produce richer breakdowns and will replace this when wired up.
@@ -973,7 +996,10 @@ export function outcome(ctx, ids, good, opts) {
             const entry = readEntry(ctx.hippoRoot, id, ctx.tenantId);
             if (!entry)
                 continue;
-            const updated = applyOutcome(entry, good);
+            let updated = applyOutcome(entry, good);
+            if (good && updated.tags.includes(CHURN_STALE_TAG)) { // FE2: a good outcome reconfirms the entry
+                updated = { ...updated, tags: updated.tags.filter((t) => t !== CHURN_STALE_TAG) };
+            }
             writeEntry(ctx.hippoRoot, updated, { actor: ctx.actor.subject });
             appendAuditEvent(db, {
                 tenantId: ctx.tenantId,
@@ -2090,6 +2116,118 @@ export function isDormant(ctx, id) {
         closeHippoDb(db);
     }
 }
+const QUARANTINE_PREVIEW_CHARS = 200;
+/** A tenant's quarantined memories, newest first. Default `status` is 'pending' (the review queue). */
+export function quarantineList(ctx, opts = {}) {
+    const db = openHippoDb(ctx.hippoRoot);
+    try {
+        const rows = listQuarantineRows(db, ctx.tenantId, opts.status ?? 'pending', opts.limit);
+        return rows.map((row) => {
+            const entry = readEntry(ctx.hippoRoot, row.memoryId, ctx.tenantId);
+            return {
+                id: row.memoryId,
+                originalScope: row.originalScope,
+                reason: row.reason,
+                status: row.status,
+                quarantinedAt: row.quarantinedAt,
+                decidedAt: row.decidedAt,
+                decidedBy: row.decidedBy,
+                contentPreview: entry ? entry.content.slice(0, QUARANTINE_PREVIEW_CHARS) : '',
+            };
+        });
+    }
+    finally {
+        closeHippoDb(db);
+    }
+}
+function loadPendingQuarantineRow(db, tenantId, id) {
+    const row = getQuarantineRow(db, tenantId, id);
+    if (!row)
+        throw new Error(`not quarantined: ${id}`);
+    if (row.status !== 'pending')
+        throw new Error(`${id} is already ${row.status}`);
+    return row;
+}
+/** Release a quarantined memory to its original scope. Admin only; the scope guard refuses a row moved since (mirrors restoreDormant). */
+export function quarantineApprove(ctx, id) {
+    if (ctx.actor.role !== 'admin') {
+        throw new ForbiddenError('Only an admin key can approve a quarantined memory');
+    }
+    const db = openHippoDb(ctx.hippoRoot);
+    try {
+        db.exec('BEGIN IMMEDIATE');
+        try {
+            const row = loadPendingQuarantineRow(db, ctx.tenantId, id);
+            const quarantineScope = quarantineScopeFor(row.originalScope);
+            const updated = db
+                .prepare(`UPDATE memories SET scope = ? WHERE id = ? AND tenant_id = ? AND scope = ?`)
+                .run(row.originalScope, id, ctx.tenantId, quarantineScope);
+            if (Number(updated.changes ?? 0) !== 1) {
+                throw new Error(`memory ${id} scope changed since quarantine; refusing to approve`);
+            }
+            approveQuarantineRow(db, ctx.tenantId, id, ctx.actor.subject);
+            appendAuditEvent(db, {
+                tenantId: ctx.tenantId,
+                actor: ctx.actor.subject,
+                op: 'quarantine_approve',
+                targetId: id,
+                metadata: { originalScope: row.originalScope },
+            });
+            db.exec('COMMIT');
+        }
+        catch (err) {
+            try {
+                db.exec('ROLLBACK');
+            }
+            catch { /* already rolled back */ }
+            throw err;
+        }
+    }
+    finally {
+        closeHippoDb(db);
+    }
+    // Post-commit, best-effort: a failed rewrite leaves the mirror showing the quarantine scope (fail-closed).
+    try {
+        const restored = readEntry(ctx.hippoRoot, id, ctx.tenantId);
+        if (restored)
+            writeEntryMirrors(ctx.hippoRoot, restored);
+    }
+    catch (err) {
+        console.error(`quarantine: mirror rewrite failed for ${id}: ${err instanceof Error ? err.message : String(err)}`);
+    }
+}
+/** Keep a quarantined memory hidden for good. Admin only; the raw row is untouched (append-only). */
+export function quarantineReject(ctx, id) {
+    if (ctx.actor.role !== 'admin') {
+        throw new ForbiddenError('Only an admin key can reject a quarantined memory');
+    }
+    const db = openHippoDb(ctx.hippoRoot);
+    try {
+        db.exec('BEGIN IMMEDIATE');
+        try {
+            loadPendingQuarantineRow(db, ctx.tenantId, id);
+            rejectQuarantineRow(db, ctx.tenantId, id, ctx.actor.subject);
+            appendAuditEvent(db, {
+                tenantId: ctx.tenantId,
+                actor: ctx.actor.subject,
+                op: 'quarantine_reject',
+                targetId: id,
+                metadata: {},
+            });
+            db.exec('COMMIT');
+        }
+        catch (err) {
+            try {
+                db.exec('ROLLBACK');
+            }
+            catch { /* already rolled back */ }
+            throw err;
+        }
+    }
+    finally {
+        closeHippoDb(db);
+    }
+}
 const DEFAULT_SLEEP_PHASES = {
     consolidate,
     deduplicateStore,

package/dist/audit.d.ts

@@ -16,7 +16,7 @@ export interface AuditResult {
 export declare function auditMemory(entry: MemoryEntry): AuditIssue | null;
 export declare function auditMemories(entries: MemoryEntry[]): AuditResult;
 export declare function isContentWorthStoring(content: string): boolean;
-export type AuditOp = 'remember' | 'recall' | 'promote' | 'supersede' | 'forget' | 'archive_raw' | 'auth_revoke' | 'auth_create' | 'outcome' | 'consolidate' | 'audit_prune' | 'summary_marked_dirty' | 'summary_marked_clean' | 'summary_rebuilt' | 'predict_create' | 'predict_close' | 'predict_baserate' | 'recall_autodebias_hint' | 'recall_autodebias_hint_no_class_match' | 'recall_autodebias_hint_tiebreak' | 'recall_anchor_detected_query_repeat' | 'recall_anchor_detected_memory_dominance' | 'recall_anchor_skipped_no_session' | 'recall_availability_detected' | 'decision_create' | 'decision_supersede' | 'decision_close' | 'incident_open' | 'incident_resolve' | 'incident_close' | 'process_create' | 'process_supersede' | 'process_close' | 'policy_create' | 'policy_supersede' | 'policy_close' | 'skill_create' | 'skill_supersede' | 'skill_close' | 'project_brief_create' | 'project_brief_supersede' | 'project_brief_close' | 'customer_note_create' | 'customer_note_supersede' | 'customer_note_close' | 'mv_rescue' | 'reject_value' | 'reject_refusal' | 'unreject_value' | 'half_life_migrate' | 'dormant_restore' | 'conflict_resolve' | 'auth_grant' | 'auth_ungrant';
+export type AuditOp = 'remember' | 'recall' | 'promote' | 'supersede' | 'forget' | 'archive_raw' | 'auth_revoke' | 'auth_create' | 'outcome' | 'consolidate' | 'audit_prune' | 'summary_marked_dirty' | 'summary_marked_clean' | 'summary_rebuilt' | 'predict_create' | 'predict_close' | 'predict_baserate' | 'recall_autodebias_hint' | 'recall_autodebias_hint_no_class_match' | 'recall_autodebias_hint_tiebreak' | 'recall_anchor_detected_query_repeat' | 'recall_anchor_detected_memory_dominance' | 'recall_anchor_skipped_no_session' | 'recall_availability_detected' | 'decision_create' | 'decision_supersede' | 'decision_close' | 'incident_open' | 'incident_resolve' | 'incident_close' | 'process_create' | 'process_supersede' | 'process_close' | 'policy_create' | 'policy_supersede' | 'policy_close' | 'skill_create' | 'skill_supersede' | 'skill_close' | 'project_brief_create' | 'project_brief_supersede' | 'project_brief_close' | 'customer_note_create' | 'customer_note_supersede' | 'customer_note_close' | 'mv_rescue' | 'reject_value' | 'reject_refusal' | 'unreject_value' | 'half_life_migrate' | 'dormant_restore' | 'conflict_resolve' | 'auth_grant' | 'auth_ungrant' | 'quarantine' | 'quarantine_approve' | 'quarantine_reject';
 export interface AppendAuditOpts {
     tenantId: string;
     actor: string;

package/dist/churn-git.d.ts

@@ -0,0 +1,22 @@
+/** Git subprocess helpers for FE2 churn-staleness (src/invalidation.ts). */
+/** A real git failure (not git grep's expected exit-1-no-match). Callers abort the whole run on this. */
+export declare class GitReadError extends Error {
+}
+export declare function gitLsFilesAtHead(repoRoot: string): Set<string>;
+export interface ChurnCommitFile {
+    status: string;
+    path: string;
+}
+export interface ChurnCommit {
+    hash: string;
+    date: string;
+    files: ChurnCommitFile[];
+}
+export declare function fetchChurnWindowLog(repoRoot: string, sinceIso: string): ChurnCommit[];
+/** `git grep -o -h -w -F -f <patternFile> <rev>`; returns the subset of `patterns` found. */
+export declare function gitGrepPresence(repoRoot: string, patterns: string[], rev: string): Set<string>;
+/** Last commit at or before `beforeIso`, or null when the repo has none. */
+export declare function resolveCommitBefore(repoRoot: string, beforeIso: string): string | null;
+/** package.json `scripts` at a revision; {} when the file is absent, null when unparsable. Git failures throw GitReadError. */
+export declare function packageScriptsAt(repoRoot: string, rev: string): Record<string, string> | null;
+//# sourceMappingURL=churn-git.d.ts.map

package/dist/churn-git.js

@@ -0,0 +1,102 @@
+/** Git subprocess helpers for FE2 churn-staleness (src/invalidation.ts). */
+import { execFileSync } from 'child_process';
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+// A `git log --name-status` dump can run to tens of MB; default 1MB pipe would truncate it.
+const GIT_MAX_BUFFER = 64 * 1024 * 1024;
+/** A real git failure (not git grep's expected exit-1-no-match). Callers abort the whole run on this. */
+export class GitReadError extends Error {
+}
+function runGit(args, repoRoot) {
+    try {
+        return execFileSync('git', args, { cwd: repoRoot, encoding: 'utf8', maxBuffer: GIT_MAX_BUFFER });
+    }
+    catch (err) {
+        throw new GitReadError(`git ${args.join(' ')} failed: ${err instanceof Error ? err.message : String(err)}`);
+    }
+}
+// git grep exits 1 for "no match" -- a normal empty result, not a failure.
+function runGitGrepOrEmpty(args, repoRoot) {
+    try {
+        return execFileSync('git', args, { cwd: repoRoot, encoding: 'utf8', maxBuffer: GIT_MAX_BUFFER });
+    }
+    catch (err) {
+        // SAFETY: execFileSync attaches `status` to the thrown Error on a non-zero child exit.
+        const status = err.status;
+        if (status === 1)
+            return '';
+        throw new GitReadError(`git ${args.join(' ')} failed: ${err instanceof Error ? err.message : String(err)}`);
+    }
+}
+// ls-tree, not ls-files: the index can hold staged adds/deletes that HEAD does not.
+export function gitLsFilesAtHead(repoRoot) {
+    const raw = runGit(['ls-tree', '-r', '--name-only', 'HEAD'], repoRoot);
+    return new Set(raw.split('\n').map((l) => l.trim()).filter(Boolean));
+}
+// 1-day buffer guards against git's --since boundary excluding a commit dated exactly at the anchor.
+export function fetchChurnWindowLog(repoRoot, sinceIso) {
+    const buffered = new Date(new Date(sinceIso).getTime() - 24 * 60 * 60 * 1000).toISOString();
+    const raw = runGit(
+    // --first-parent -m: a merge's changes land as one diff against its mainline parent.
+    ['log', '--no-renames', '--first-parent', '-m', `--since=${buffered}`, '--pretty=format:%x01%H%x02%cI', '--name-status'], repoRoot);
+    const commits = [];
+    let current = null;
+    for (const line of raw.split('\n')) {
+        if (line.startsWith('\x01')) {
+            const [hash, date] = line.slice(1).split('\x02');
+            current = { hash, date, files: [] };
+            commits.push(current);
+        }
+        else if (current && line.trim()) {
+            const m = line.match(/^([AMD])\s+(.+)$/);
+            if (m)
+                current.files.push({ status: m[1], path: m[2] });
+        }
+    }
+    return commits;
+}
+/** `git grep -o -h -w -F -f <patternFile> <rev>`; returns the subset of `patterns` found. */
+export function gitGrepPresence(repoRoot, patterns, rev) {
+    if (patterns.length === 0)
+        return new Set();
+    const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'hippo-churn-grep-'));
+    try {
+        const patternFile = path.join(tmpDir, 'patterns.txt');
+        fs.writeFileSync(patternFile, `${patterns.join('\n')}\n`, 'utf8');
+        const raw = runGitGrepOrEmpty(['grep', '-o', '-h', '-w', '-F', '-f', patternFile, rev], repoRoot);
+        const patternSet = new Set(patterns);
+        const found = new Set();
+        for (const line of raw.split('\n')) {
+            const t = line.trim();
+            if (patternSet.has(t))
+                found.add(t);
+        }
+        return found;
+    }
+    finally {
+        fs.rmSync(tmpDir, { recursive: true, force: true });
+    }
+}
+/** Last commit at or before `beforeIso`, or null when the repo has none. */
+export function resolveCommitBefore(repoRoot, beforeIso) {
+    const raw = runGit(['rev-list', '-1', '--first-parent', `--before=${beforeIso}`, 'HEAD'], repoRoot).trim();
+    return raw === '' ? null : raw;
+}
+/** package.json `scripts` at a revision; {} when the file is absent, null when unparsable. Git failures throw GitReadError. */
+export function packageScriptsAt(repoRoot, rev) {
+    if (runGit(['ls-tree', '--name-only', rev, '--', 'package.json'], repoRoot).trim() === '')
+        return {};
+    const raw = runGit(['show', `${rev}:package.json`], repoRoot);
+    try {
+        // SAFETY: optional chaining makes a `null` or scalar package.json read as "no scripts".
+        const parsed = JSON.parse(raw);
+        return parsed?.scripts ?? {};
+    }
+    catch (err) {
+        if (err instanceof SyntaxError)
+            return null;
+        throw err;
+    }
+}
+//# sourceMappingURL=churn-git.js.map

package/dist/cli.js

@@ -68,7 +68,8 @@ import { FAILURE_LOG_RETENTION_DAYS } from './failure-log.js';
 import { pushGoal, getActiveGoals, completeGoal, suspendGoal, resumeGoal, applyGoalStackBoost } from './goals.js';
 import { rowToGoal } from './goals.js';
 import { captureError, extractLessons, partitionLessons, deduplicateLesson, runWatched, fetchGitLog, isGitRepo, } from './autolearn.js';
-import { extractInvalidationTarget, invalidateMatching } from './invalidation.js';
+import { extractInvalidationTarget, invalidateMatching, detectChurnStale } from './invalidation.js';
+import { resolveProjectIdentity } from './project-identity.js';
 import { extractPathTags } from './path-context.js';
 import { detectScope } from './scope.js';
 import { getGlobalRoot, initGlobal, shareMemory, listPeers, autoShare, transferScore, searchBothHybrid, syncGlobalToLocal, } from './shared.js';
@@ -200,6 +201,24 @@ function requireInit(hippoRoot) {
         process.exit(1);
     }
 }
+/** FE2: run detectChurnStale against every store this repo's memories can live in. */
+function runChurnStaleForRepo(hippoRoot, dryRun) {
+    const repoRoot = execFileSync('git', ['rev-parse', '--show-toplevel'], { cwd: process.cwd(), encoding: 'utf8' }).trim();
+    const projectName = resolveProjectIdentity(process.cwd()).name;
+    const globalRoot = getGlobalRoot();
+    const roots = globalRoot !== hippoRoot && isInitialized(globalRoot) ? [hippoRoot, globalRoot] : [hippoRoot];
+    const tenantId = resolveTenantId({});
+    return roots.map((root) => {
+        // One store failing must not abort sleep's later phases or skip the other store.
+        try {
+            return { root, result: detectChurnStale(root, repoRoot, { tenantId, projectName, dryRun }) };
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            return { root, result: { checked: 0, marked: 0, alreadyMarked: 0, skippedPinned: [], dryRun, preview: [], error: message } };
+        }
+    });
+}
 /**
  * H2: when HIPPO_REQUIRE_SERVER is set, the CLI must not silently fall back to
  * direct DB mode — a missing server then masks a real misconfiguration (the
@@ -263,7 +282,7 @@ async function runViaServerIfAvailable(hippoRoot, httpFn) {
 // and as off under === true (`--pin=true` would not pin), so parseArgs and main() refuse one.
 // tests/cli-parse-flag-equals.test.ts fails when a switch read is missing from this set.
 export const BOOLEAN_FLAGS = new Set([
-    'all', 'all-tenants', 'archive', 'auto', 'bad', 'bootstrap', 'classic', 'continuity',
+    'all', 'all-tenants', 'archive', 'auto', 'bad', 'bootstrap', 'classic', 'churn', 'continuity',
     'cross-project', 'dry-run', 'equal-sources', 'error', 'evc-adaptive', 'extract',
     'filter-conflicts', 'fix', 'force', 'forget', 'git', 'global', 'good', 'graph-stream',
     'help', 'include-logs', 'include-superseded', 'inferred', 'json', 'last-session', 'multihop', 'no-hooks',
@@ -2197,6 +2216,8 @@ async function cmdExplain(hippoRoot, query, flags) {
                 console.log(`    source:    x${fmt(b.sourceBump, 2)}  (local priority bump over global)`);
             if (b.outcomeBoost !== 1)
                 console.log(`    outcome:   x${fmt(b.outcomeBoost, 3)}  (user feedback: pos-neg = ${(r.entry.outcome_positive ?? 0) - (r.entry.outcome_negative ?? 0)})`);
+            if (b.churnStaleMultiplier !== 1)
+                console.log(`    churn:     x${fmt(b.churnStaleMultiplier, 2)}  (tagged 'churn-stale')`);
             if (b.preMmrRank !== undefined && b.postMmrRank !== undefined && b.preMmrRank !== b.postMmrRank) {
                 const arrow = b.postMmrRank < b.preMmrRank ? 'up' : 'down';
                 console.log(`    mmr:       rank ${b.preMmrRank} -> ${b.postMmrRank}  (diversity ${arrow})`);
@@ -2840,6 +2861,15 @@ async function cmdSleepCore(hippoRoot, flags) {
             if (added > 0)
                 console.log(`Auto-learned ${added} lessons from today's git commits.`);
         }
+        // FE2: opt-in code-churn staleness, off by default (config.churnStaleness.enabled).
+        if (config.churnStaleness.enabled && isGitRepo(process.cwd())) {
+            for (const { root, result } of runChurnStaleForRepo(hippoRoot, false)) {
+                if (result.marked > 0)
+                    console.log(`Tagged ${result.marked} memories churn-stale in ${root}.`);
+                if (result.error)
+                    console.error(`Churn-staleness check failed for ${root}: ${result.error}`);
+            }
+        }
         // Also learn from Claude Code MEMORY.md files
         const memImported = learnFromMemoryMd(hippoRoot);
         if (memImported > 0)
@@ -3897,6 +3927,56 @@ function cmdDormant(hippoRoot, args, flags) {
     }
     console.log('Bring one back: hippo dormant restore <id>   Delete for good: hippo dormant forget <id>');
 }
+/** `hippo quarantine [list] [--all] [--json] [--global]`, `quarantine approve <id>`, `quarantine reject <id>` (CD5 poisoning defence). */
+function cmdQuarantine(hippoRoot, args, flags) {
+    const root = resolveAuthRoot(hippoRoot, flags);
+    const ctx = {
+        hippoRoot: root,
+        tenantId: resolveTenantId({}),
+        actor: api.adminActor('cli'),
+    };
+    const sub = args[0];
+    if (sub === 'approve' || sub === 'reject') {
+        const id = (args[1] ?? '').trim();
+        if (!id) {
+            console.error(`Usage: hippo quarantine ${sub} <id>`);
+            process.exit(1);
+        }
+        try {
+            if (sub === 'approve') {
+                api.quarantineApprove(ctx, id);
+                console.log(`Approved ${id}: restored to its original scope.`);
+            }
+            else {
+                api.quarantineReject(ctx, id);
+                console.log(`Rejected ${id}: stays quarantined.`);
+            }
+        }
+        catch (err) {
+            console.error(`Could not ${sub} ${id}: ${err instanceof Error ? err.message : String(err)}`);
+            process.exit(1);
+        }
+        return;
+    }
+    const status = flags['all'] ? 'all' : 'pending';
+    const rows = api.quarantineList(ctx, { status });
+    if (flags['json']) {
+        console.log(JSON.stringify({ quarantine: rows }, null, 2));
+        return;
+    }
+    if (rows.length === 0) {
+        console.log(status === 'all' ? 'No quarantined memories.' : 'No pending quarantined memories.');
+        return;
+    }
+    console.log(`${rows.length} quarantined memor${rows.length === 1 ? 'y' : 'ies'} (newest first):\n`);
+    for (const row of rows) {
+        console.log(`--- ${row.id} [${row.status}]`);
+        console.log(`    ${row.contentPreview}`);
+        console.log(`    ${row.reason}, original scope ${row.originalScope ?? '(none)'}, quarantined ${row.quarantinedAt.slice(0, 10)}`);
+        console.log('');
+    }
+    console.log('Approve: hippo quarantine approve <id>   Reject: hippo quarantine reject <id>');
+}
 /**
  * `hippo tokens [--days <n>] [--json] [--global]`: the token ledger
  * (ROADMAP TE0). Tokens of memory text handed to agents per surface, blocks
@@ -7979,6 +8059,9 @@ const VALID_AUDIT_OPS = new Set([
     'dormant_restore', // Dormant memories — emitted by api.restoreDormant; lockstep with AuditOp union + server.ts VALID_AUDIT_OPS
     'auth_grant', // EI2: emitted by api.authGrant; lockstep with AuditOp union + server.ts VALID_AUDIT_OPS
     'auth_ungrant', // EI2: emitted by api.authUngrant; lockstep with AuditOp union + server.ts VALID_AUDIT_OPS
+    'quarantine', // CD5: emitted by recordQuarantine; lockstep with AuditOp union + server.ts VALID_AUDIT_OPS
+    'quarantine_approve', // CD5: emitted by api.quarantineApprove; lockstep
+    'quarantine_reject', // CD5: emitted by api.quarantineReject; lockstep
 ]);
 function formatAuditRow(ev) {
     const target = ev.targetId ?? '-';
@@ -8721,6 +8804,12 @@ Commands:
     --global               Operate on the global store
     dormant restore <id>   Bring a dormant memory back to active memory
     dormant forget <id>    Delete a dormant memory permanently
+  quarantine [list]        List memories a connector flagged as an instruction attempt, pending review
+    --all                  Include approved and rejected rows too (default: pending only)
+    --json                 Output as JSON
+    --global               Operate on the global store
+    quarantine approve <id> Restore a quarantined memory to its original scope
+    quarantine reject <id>  Keep a quarantined memory hidden for good
   capture-error            Store a failed tool call as an error memory (reads the Claude Code
                            PostToolUseFailure hook payload on stdin; skips routine failures)
   doctor                   Check the install: Node, store, schema, sleep, agent hooks
@@ -8963,6 +9052,11 @@ Commands:
                            'invalidated' re-weakens previously invalidated
                            memories - preview with --dry-run first
     --reason "<why>"       Optional: what replaced it
+  invalidate --churn       FE2: tag memories 'churn-stale' whose named file
+                           changed or was deleted, or whose named symbol or
+                           npm script was removed, in this repo's git history
+                           since the memory was stored or confirmed
+    --dry-run              Preview what would be tagged; writes nothing
   wm <sub>                 Working memory — bounded buffer for current state
     wm push                Push a working memory entry
       --scope <scope>      Scope name (default: default)
@@ -9075,6 +9169,7 @@ Examples:
   hippo invalidate "REST API" --dry-run
   hippo invalidate "REST API" --reason "migrated to GraphQL"
   hippo invalidate --id mem_a1b2c3d4e5f6 --reason "superseded by new policy"
+  hippo invalidate --churn --dry-run
   hippo export memories.json
   hippo export --format markdown memories.md
   hippo sleep --dry-run
@@ -9478,6 +9573,9 @@ async function main(command, args, flags, hippoRoot) {
         case 'dormant':
             cmdDormant(hippoRoot, args, flags);
             break;
+        case 'quarantine':
+            cmdQuarantine(hippoRoot, args, flags);
+            break;
         case 'tokens':
             cmdTokens(hippoRoot, flags);
             break;
@@ -9836,6 +9934,42 @@ async function main(command, args, flags, hippoRoot) {
         }
         case 'invalidate': {
             requireInit(hippoRoot);
+            if (flags['churn'] === true) {
+                if (args[0] || flags['id'] !== undefined) {
+                    console.error('Usage: hippo invalidate --churn [--dry-run]');
+                    console.error('--churn takes no pattern or --id.');
+                    process.exit(1);
+                }
+                if (!isGitRepo(process.cwd())) {
+                    console.error('hippo invalidate --churn must run inside a git repository.');
+                    process.exit(1);
+                }
+                const churnDryRun = flags['dry-run'] === true;
+                let churnFailed = false;
+                for (const { root, result } of runChurnStaleForRepo(hippoRoot, churnDryRun)) {
+                    if (result.error) {
+                        console.error(`Churn-staleness check failed for ${root}: ${result.error}`);
+                        churnFailed = true;
+                        continue;
+                    }
+                    if (result.preview.length === 0) {
+                        console.log(`No churn-stale candidates in ${root}.`);
+                    }
+                    else if (churnDryRun) {
+                        console.log(`DRY RUN - ${result.marked} memories in ${root} WOULD be tagged churn-stale (${result.alreadyMarked} already tagged):`);
+                    }
+                    else {
+                        console.log(`Tagged ${result.marked} memories churn-stale in ${root} (${result.alreadyMarked} already tagged):`);
+                    }
+                    result.preview.forEach(p => console.log(`   ${p.id}  ${p.evidence}  ${p.already ? '(already) ' : ''}${p.headline}`));
+                    if (result.skippedPinned.length > 0) {
+                        console.log(`Skipped ${result.skippedPinned.length} pinned: ${result.skippedPinned.join(', ')}`);
+                    }
+                }
+                if (churnFailed)
+                    process.exit(1);
+                break;
+            }
             const target = args[0];
             if (flags['id'] === true) {
                 // Value-less --id must never silently fall through to pattern mode

package/dist/config.d.ts

@@ -116,6 +116,11 @@ export interface HippoConfig {
          *  Default 180. 0 keeps dormant memories forever. */
         retentionDays: number;
     };
+    /** FE2: tags a memory `churn-stale` when its named file/symbol/script
+     *  changed since storage. Default OFF - FE3 measures before it flips. */
+    churnStaleness: {
+        enabled: boolean;
+    };
 }
 export declare function loadConfig(hippoRoot: string): HippoConfig;
 export declare function saveConfig(hippoRoot: string, config: HippoConfig): void;