@sema-agent/core 5.17.0 → 5.18.1

package/dist/core/memory-engine/engine.js

@@ -6,7 +6,7 @@ import { inlineUntrusted } from "../untrusted-text.js";
 import { formatMemoryAge } from "../memory-recall.js";
 import { computeEntryRev, parseEntryFile, serializeEntryFile } from "./frontmatter.js";
 import { DEFAULT_MAX_ENTRY_DEPTH, MEMORY_INDEX_FILENAME, scanEntryFiles } from "./file-backend.js";
-import { QUARANTINE_DIR, SCAN_FUSE_THRESHOLD, quarantineAndTombstone, readIndexRevs, writeIndexRevs, bumpScanFuse, canonicalize, claimRootScope, clearScanFuse, adoptCanonicalKeyedControlDir, deriveControlPlaneDir, drainMemoryAnnouncements, enqueueMemoryAnnouncement, ensureDirExists, isContainedIn, registerScope, registeredScopes, resolveMemoryEngineRoot, scopeDirFor, } from "./layout.js";
+import { QUARANTINE_DIR, SCAN_FUSE_THRESHOLD, quarantineAndTombstone, readIndexRevs, writeIndexRevs, bumpScanFuse, canonicalize, claimRootScope, clearScanFuse, adoptCanonicalKeyedControlDir, deriveControlPlaneDir, drainMemoryAnnouncements, enqueueMemoryAnnouncement, ensureDirExists, isContainedIn, markSessionPolluted, readSessionPollution, recordRetrievedAccount, writeFileNoFollow, readRetrievedAccount, registerScope, registeredScopes, resolveMemoryEngineRoot, scopeDirFor, } from "./layout.js";
 import { scanMemoryFileName, scanMemoryWrite, scanRemediation } from "./scan.js";
 export const MEMORY_INSTRUCTION_TEMPLATE = `# Memory
 
@@ -32,6 +32,7 @@ export function buildMemoryInstruction(memoryDir, instructionFileName) {
     const dir = memoryDir.endsWith("/") ? memoryDir : `${memoryDir}/`;
     return MEMORY_INSTRUCTION_TEMPLATE.replaceAll("{{MEMORY_DIR}}", dir).replaceAll("{{INSTRUCTION_FILE}}", instructionFileName ?? "CLAUDE.md");
 }
+export const MEMORY_RECALL_DISCIPLINE = "Before answering questions about earlier work, decisions, dates, people, or the user's preferences, look them up: `memory_search` finds entries by keyword and `memory_get` reads a full entry — the injected memory index only lists what exists. When a lookup comes up empty, say that you checked memory and found nothing instead of guessing.";
 export const MEMORY_INDEX_MAX_LINES = 200;
 export const MEMORY_INDEX_MAX_BYTES = 25 * 1024;
 export const STUB_ARCHIVED_LINE = "[body archived — request hydration by listing the slug in memory/.hydrate]";
@@ -85,6 +86,56 @@ export class MemoryEngine {
         catch {
         }
     }
+    recordRetrieved(ids) {
+        try {
+            recordRetrievedAccount(this.controlDir, ids, this.now);
+        }
+        catch {
+        }
+    }
+    readRetrievedAccount() {
+        try {
+            return readRetrievedAccount(this.controlDir);
+        }
+        catch {
+            return {};
+        }
+    }
+    pollutedSessions = new Map();
+    markSessionPolluted(sessionId, reason) {
+        if (!this.pollutedSessions.has(sessionId))
+            this.pollutedSessions.set(sessionId, { at: this.now(), reason });
+        let durable = false;
+        try {
+            durable = markSessionPolluted(this.controlDir, sessionId, reason, this.now);
+        }
+        catch {
+            durable = false;
+        }
+        if (!durable) {
+            const sink = this.onIncident;
+            if (sink !== undefined) {
+                try {
+                    const err = new Error(`memory pollution marker for session could not be persisted — the mark holds in-process only until it succeeds`);
+                    err.code = "memory.pollution_mark_failed";
+                    sink(err);
+                }
+                catch {
+                }
+            }
+        }
+    }
+    sessionPollution(sessionId) {
+        const inProcess = this.pollutedSessions.get(sessionId);
+        if (inProcess !== undefined)
+            return inProcess;
+        try {
+            return readSessionPollution(this.controlDir, sessionId);
+        }
+        catch {
+            return undefined;
+        }
+    }
     async materialize(scopes, writeScope) {
         ensureDirExists(this.memoryDir);
         ensureDirExists(this.controlDir);
@@ -246,8 +297,8 @@ export class MemoryEngine {
             : `${f.reason}. ${scanRemediation(f.code)} Nothing was written.`;
         return { ok: false, code: f.code, reason, muted };
     }
-    async harvest(handle) {
-        const report = await this.harvestCore(handle);
+    async harvest(handle, opts) {
+        const report = await this.harvestCore(handle, opts);
         try {
             const gateItems = gateAnnouncementItems(report);
             if (gateItems.length > 0)
@@ -262,7 +313,8 @@ export class MemoryEngine {
         }
         return report;
     }
-    async harvestCore(handle) {
+    async harvestCore(handle, opts) {
+        const pollutedReason = opts?.polluted?.reason;
         const startedAt = this.now();
         const report = {
             ok: true,
@@ -326,6 +378,97 @@ export class MemoryEngine {
             if (r.parsed.id !== undefined)
                 presentIds.add(r.parsed.id);
         const recordByPath = new Map(records.map((r) => [r.canonical, r]));
+        const pollutedStubs = new Map(handle.materialized.filter((m) => !m.readonly && m.stub).map((m) => [m.path, m]));
+        const containPollutedRecord = async (f) => {
+            const rel = f.rel;
+            if (f.canonical !== handle.writableRoot && !f.canonical.startsWith(`${handle.writableRoot}${sep}`)) {
+                report.rejections.push({ path: rel, code: "outside_root", reason: "file resolves outside the writable memory root (containment gate, fail-closed)" });
+                return;
+            }
+            const baseId = handle.baseIds.get(f.canonical);
+            if (baseId !== undefined && !pollutedStubs.has(f.canonical) && revOfText(f.text, baseId) === handle.baseRevs.get(f.canonical))
+                return;
+            const pollutedStub = pollutedStubs.get(f.canonical);
+            if (pollutedStub) {
+                if (revOfText(f.text, pollutedStub.id) !== pollutedStub.rev) {
+                    const sq = quarantineAndTombstone(f.canonical, f.text, join(this.controlDir, QUARANTINE_DIR), this.now);
+                    const stubCaptured = sq.dest !== undefined;
+                    if (stubCaptured && sq.removed)
+                        report.movedToQuarantine.push(rel);
+                    report.rejections.push({
+                        path: rel,
+                        code: "polluted",
+                        reason: `memory write withheld: this session invoked a tool classified as an external content source, so its memory changes were not committed (archived-body stub; ${stubCaptured && sq.removed ? "file moved to quarantine for host review, and the next session re-projects the stub" : "containment incomplete — the edited stub may still be on the model-visible plane"})`,
+                    });
+                    if (sq.detail !== undefined || !sq.removed || !stubCaptured) {
+                        const detail = `${sq.detail ?? (stubCaptured ? "suspect content still on the model-visible plane" : "quarantine capture failed")}${sq.removed ? "" : " — NOT contained"}`;
+                        (report.quarantineFailures ??= []).push({ path: rel, contained: sq.removed, detail });
+                        report.warnings.push(`quarantine escalation for ${rel}: ${detail}`);
+                    }
+                }
+                return;
+            }
+            const q = quarantineAndTombstone(f.canonical, f.text, join(this.controlDir, QUARANTINE_DIR), this.now);
+            let contained = q.removed;
+            const priorId = handle.baseIds.get(f.canonical);
+            if (priorId !== undefined) {
+                const committed = await this.committedContentFor(priorId);
+                if (committed !== undefined) {
+                    try {
+                        writeFileNoFollow(f.canonical, committed);
+                        report.restored.push(rel);
+                        contained = true;
+                    }
+                    catch {
+                    }
+                }
+            }
+            const captured = q.dest !== undefined;
+            if (captured && contained)
+                report.movedToQuarantine.push(rel);
+            report.rejections.push({
+                path: rel,
+                code: "polluted",
+                reason: `memory write withheld: this session invoked a tool classified as an external content source, so its memory changes were not committed (${captured && contained ? "file moved to quarantine for host review" : captured ? "quarantine copy captured; removal from the model-visible plane incomplete" : "quarantine copy FAILED; file removal " + (contained ? "succeeded" : "incomplete")})`,
+            });
+            if (q.detail !== undefined || !contained || !captured) {
+                const parts = [q.detail, !captured ? "quarantine capture failed" : undefined].filter((x) => x !== undefined);
+                const detail = `${parts.length > 0 ? parts.join("; ") : "suspect content still on the model-visible plane"}${contained ? "" : " — NOT contained"}`;
+                (report.quarantineFailures ??= []).push({ path: rel, contained, detail });
+                report.warnings.push(`quarantine escalation for ${rel}: ${detail}`);
+            }
+        };
+        const restorePollutedIndex = () => {
+            const pollutedIndexPath = join(handle.writableRoot, MEMORY_INDEX_FILENAME);
+            const canonicalIndex = canonicalize(pollutedIndexPath);
+            if (canonicalIndex !== pollutedIndexPath && !canonicalIndex.startsWith(`${handle.writableRoot}${sep}`)) {
+                report.warnings.push("memory index NOT restored: its path resolves outside the writable memory root (containment gate, fail-closed)");
+                return;
+            }
+            const indexNow = readSafe(pollutedIndexPath);
+            if (indexNow === undefined || indexNow === handle.indexText)
+                return;
+            try {
+                const dest = join(this.controlDir, QUARANTINE_DIR, `${this.now()}-polluted-${MEMORY_INDEX_FILENAME}`);
+                ensureDirExists(dirname(dest));
+                writeFileSync(dest, indexNow, "utf8");
+            }
+            catch {
+            }
+            try {
+                writeFileNoFollow(pollutedIndexPath, handle.indexText);
+                report.warnings.push("memory index restored to its pre-session state — this session's index additions were not retained (session polluted; the removed text was captured to quarantine)");
+            }
+            catch (err) {
+                report.warnings.push(`memory index could NOT be restored to its pre-session state: ${err instanceof Error ? err.message : String(err)}`);
+            }
+        };
+        const containPollutedDomain = async () => {
+            for (const f of records)
+                await containPollutedRecord(f);
+            restorePollutedIndex();
+            report.warnings.push(`memory harvest committed nothing this session: ${inlineUntrusted(pollutedReason, 200)}`);
+        };
         for (const m of handle.materialized.filter((x) => x.readonly)) {
             const text = readSafe(m.path);
             if (text === undefined) {
@@ -355,6 +498,8 @@ export class MemoryEngine {
                 kind: "mass_deletion",
                 detail: `${missingWritable.length}/${writable.length} materialized memory files are missing — judged an accident, harvest refused (no delete patches produced; explicit frontmatter tombstones are the only deletion channel)`,
             };
+            if (pollutedReason !== undefined)
+                await containPollutedDomain();
             return report;
         }
         const indexPath = join(handle.writableRoot, MEMORY_INDEX_FILENAME);
@@ -362,6 +507,8 @@ export class MemoryEngine {
         if (handle.indexBaselineLines > 0 && indexNow !== undefined && indexNow.trim() === "" && missingWritable.length > 0) {
             report.ok = false;
             report.incident = { kind: "index_cleared", detail: "MEMORY.md was emptied alongside missing memory files — judged an accident, harvest refused" };
+            if (pollutedReason !== undefined)
+                await containPollutedDomain();
             return report;
         }
         for (const m of missingWritable) {
@@ -382,7 +529,7 @@ export class MemoryEngine {
             .sort((a, b) => Number(baselinePaths.has(b.canonical)) - Number(baselinePaths.has(a.canonical)) || a.slug.localeCompare(b.slug));
         const kept = [];
         for (const f of inDomain) {
-            if (kept.length >= this.maxFiles) {
+            if (pollutedReason === undefined && kept.length >= this.maxFiles) {
                 report.rejections.push({ path: f.rel, code: "file_cap", reason: `memory file count exceeds the cap (${this.maxFiles}); consolidate before adding more` });
                 continue;
             }
@@ -401,7 +548,7 @@ export class MemoryEngine {
         let processed = 0;
         for (let i = 0; i < kept.length; i++) {
             const f = kept[i];
-            if (processed >= this.harvestFileBudget || this.now() - startedAt > this.harvestDeadlineMs) {
+            if (pollutedReason === undefined && (processed >= this.harvestFileBudget || this.now() - startedAt > this.harvestDeadlineMs)) {
                 report.degraded = {
                     reason: processed >= this.harvestFileBudget ? "file_budget" : "deadline",
                     pending: kept.slice(i).map((r) => r.rel),
@@ -417,6 +564,10 @@ export class MemoryEngine {
             if (fastBaseId !== undefined && !stubByPath.has(f.canonical) && revOfText(f.text, fastBaseId) === revByBasePath.get(f.canonical))
                 continue;
             processed++;
+            if (pollutedReason !== undefined) {
+                await containPollutedRecord(f);
+                continue;
+            }
             if (f.sizeBytes > this.perFileBytes) {
                 report.rejections.push({ path: rel, code: "too_large", reason: `memory file is ${f.sizeBytes} bytes — over the ${this.perFileBytes}-byte cap; split or trim it (rejected, NOT truncated)` });
                 continue;
@@ -524,13 +675,18 @@ export class MemoryEngine {
             patches.push({ op: "add", id: entry.id, entry });
         }
         let patchReport;
-        try {
-            patchReport = await this.backend.applyPatches(patches);
+        if (pollutedReason !== undefined) {
+            patchReport = { applied: [], conflicts: [] };
         }
-        catch (err) {
-            report.ok = false;
-            report.incident = { kind: "sidecar_corrupt", detail: `memory commit refused: ${err instanceof Error ? err.message : String(err)}` };
-            return report;
+        else {
+            try {
+                patchReport = await this.backend.applyPatches(patches);
+            }
+            catch (err) {
+                report.ok = false;
+                report.incident = { kind: "sidecar_corrupt", detail: `memory commit refused: ${err instanceof Error ? err.message : String(err)}` };
+                return report;
+            }
         }
         const appliedIds = new Set(patchReport.applied.filter((a) => a.op !== "delete").map((a) => a.id));
         for (const p of pendingProjections) {
@@ -558,6 +714,10 @@ export class MemoryEngine {
         const drained = this.backend.drainInboundFindings?.();
         if (drained !== undefined && drained.length > 0)
             report.inboundFindings = drained;
+        if (pollutedReason !== undefined) {
+            restorePollutedIndex();
+            report.warnings.push(`memory harvest committed nothing this session: ${inlineUntrusted(pollutedReason, 200)}`);
+        }
         const indexRejection = this.gateDerivedIndex(handle);
         if (indexRejection !== undefined)
             report.rejections.push(indexRejection);

package/dist/core/memory-engine/file-backend.d.ts

@@ -38,10 +38,14 @@ export declare class FileMemoryEngineBackend implements MemoryBackend {
     private inboundGate;
     private readScope;
     listHeaders(scopes: readonly string[]): Promise<MemoryEntryHeader[]>;
+    private listHeadersWith;
     getByIds(ids: readonly string[]): Promise<MemoryEntry[]>;
+    private getByIdsWith;
+    retrievalView(): MemoryBackend;
     search(query: string, scopes: readonly string[], opts?: {
         limit?: number;
     }): Promise<ScoredMemoryEntry[]>;
+    private searchWith;
     applyPatches(patches: readonly NotePatch[]): Promise<PatchReport>;
     private txnLockDir;
     private acquireTxnLock;

package/dist/core/memory-engine/file-backend.js

@@ -374,27 +374,49 @@ export class FileMemoryEngineBackend {
         return entries;
     }
     async listHeaders(scopes) {
+        return this.listHeadersWith(scopes, true);
+    }
+    listHeadersWith(scopes, adopt) {
         const out = [];
         for (const scope of scopes) {
             const dir = this.scopeDir(scope);
-            for (const e of this.readScope(scope)) {
+            for (const e of this.readScope(scope, adopt)) {
                 out.push(headerOf(e, join(dir, `${e.slug}.md`)));
             }
         }
         return out;
     }
     async getByIds(ids) {
+        return this.getByIdsWith(ids, true);
+    }
+    getByIdsWith(ids, adopt) {
         const want = new Set(ids);
         const out = [];
         for (const scope of Object.keys(registeredScopes(this.controlPlaneRoot))) {
-            for (const e of this.readScope(scope)) {
+            for (const e of this.readScope(scope, adopt)) {
                 if (want.has(e.id))
                     out.push(e);
             }
         }
         return out;
     }
+    retrievalView() {
+        const refuse = (op) => {
+            throw new Error(`memory retrieval view is read-only — ${op} must go through the backend itself`);
+        };
+        return {
+            listHeaders: async (scopes) => this.listHeadersWith(scopes, false),
+            getByIds: async (ids) => this.getByIdsWith(ids, false),
+            search: async (query, scopes, opts) => this.searchWith(query, scopes, opts, false),
+            applyPatches: async () => refuse("applyPatches"),
+            getConsolidationCursor: async (scope) => this.getConsolidationCursor(scope),
+            setConsolidationCursor: async () => refuse("setConsolidationCursor"),
+        };
+    }
     async search(query, scopes, opts) {
+        return this.searchWith(query, scopes, opts, true);
+    }
+    searchWith(query, scopes, opts, adopt) {
         const limit = opts?.limit ?? 20;
         const q = termSet(query);
         if (q.size === 0)
@@ -402,7 +424,7 @@ export class FileMemoryEngineBackend {
         const scored = [];
         for (const scope of scopes) {
             const dir = this.scopeDir(scope);
-            for (const e of this.readScope(scope)) {
+            for (const e of this.readScope(scope, adopt)) {
                 const haystack = `${e.frontmatter.name ?? e.slug} ${e.frontmatter.description ?? ""} ${e.body}`;
                 const d = jaccardDistance(q, haystack);
                 if (d === null)

package/dist/core/memory-engine/index.d.ts

@@ -1,4 +1,5 @@
-export { MemoryEngine, buildMemoryInstruction, truncateIndex, MEMORY_INSTRUCTION_TEMPLATE, MEMORY_INDEX_MAX_LINES, MEMORY_INDEX_MAX_BYTES, STUB_ARCHIVED_LINE, DEFAULT_MAX_MEMORY_FILES, DEFAULT_HARVEST_DEADLINE_MS, DEFAULT_HARVEST_FILE_BUDGET, MASS_DELETION_FUSE_RATIO, renderAnnouncements, type MemoryEngineOptions, type MemoryInjection, } from "./engine.js";
+export { MemoryEngine, buildMemoryInstruction, truncateIndex, MEMORY_INSTRUCTION_TEMPLATE, MEMORY_RECALL_DISCIPLINE, MEMORY_INDEX_MAX_LINES, MEMORY_INDEX_MAX_BYTES, STUB_ARCHIVED_LINE, DEFAULT_MAX_MEMORY_FILES, DEFAULT_HARVEST_DEADLINE_MS, DEFAULT_HARVEST_FILE_BUDGET, MASS_DELETION_FUSE_RATIO, renderAnnouncements, type MemoryEngineOptions, type MemoryInjection, } from "./engine.js";
+export { MEMORY_SEARCH_TOOL_NAME, MEMORY_GET_TOOL_NAME, MEMORY_ENGINE_TOOL_NAMES, type MemorySearchDetails, type MemorySearchHit, type MemoryGetDetails, } from "./tools.js";
 export { scanMemoryWrite, scanMemoryFileName, scanRemediation, MEMORY_FILENAME_SEGMENT_RE } from "./scan.js";
 export { FileMemoryEngineBackend, scanEntryFiles, MEMORY_INDEX_FILENAME, DEFAULT_MAX_ENTRY_DEPTH, type ScannedEntryFile } from "./file-backend.js";
 export { ControlPlaneCorruptError, deriveControlPlaneDir, deriveRepoControlPlaneDir, deriveRepoKey, deriveRepoMemoryDir, deriveProjectMemoryDir, deriveProjectControlDir, recordProjectIdHint, lookupProjectIdHint, PROJECT_ID_HINTS_FILE, resolveMemoryEngineRoot, scopeDirFor, scopeDirName, claimRootScope, rootScopeOf, enqueueMemoryAnnouncement, drainMemoryAnnouncements, peekMemoryAnnouncements, bumpScanFuse, scanFuseCount, clearScanFuse, ANNOUNCEMENTS_FILE, MEMORY_ANNOUNCEMENTS_MAX, SCAN_FUSE_FILE, SCAN_FUSE_THRESHOLD, } from "./layout.js";

package/dist/core/memory-engine/index.js

@@ -1,4 +1,5 @@
-export { MemoryEngine, buildMemoryInstruction, truncateIndex, MEMORY_INSTRUCTION_TEMPLATE, MEMORY_INDEX_MAX_LINES, MEMORY_INDEX_MAX_BYTES, STUB_ARCHIVED_LINE, DEFAULT_MAX_MEMORY_FILES, DEFAULT_HARVEST_DEADLINE_MS, DEFAULT_HARVEST_FILE_BUDGET, MASS_DELETION_FUSE_RATIO, renderAnnouncements, } from "./engine.js";
+export { MemoryEngine, buildMemoryInstruction, truncateIndex, MEMORY_INSTRUCTION_TEMPLATE, MEMORY_RECALL_DISCIPLINE, MEMORY_INDEX_MAX_LINES, MEMORY_INDEX_MAX_BYTES, STUB_ARCHIVED_LINE, DEFAULT_MAX_MEMORY_FILES, DEFAULT_HARVEST_DEADLINE_MS, DEFAULT_HARVEST_FILE_BUDGET, MASS_DELETION_FUSE_RATIO, renderAnnouncements, } from "./engine.js";
+export { MEMORY_SEARCH_TOOL_NAME, MEMORY_GET_TOOL_NAME, MEMORY_ENGINE_TOOL_NAMES, } from "./tools.js";
 export { scanMemoryWrite, scanMemoryFileName, scanRemediation, MEMORY_FILENAME_SEGMENT_RE } from "./scan.js";
 export { FileMemoryEngineBackend, scanEntryFiles, MEMORY_INDEX_FILENAME, DEFAULT_MAX_ENTRY_DEPTH } from "./file-backend.js";
 export { ControlPlaneCorruptError, deriveControlPlaneDir, deriveRepoControlPlaneDir, deriveRepoKey, deriveRepoMemoryDir, deriveProjectMemoryDir, deriveProjectControlDir, recordProjectIdHint, lookupProjectIdHint, PROJECT_ID_HINTS_FILE, resolveMemoryEngineRoot, scopeDirFor, scopeDirName, claimRootScope, rootScopeOf, enqueueMemoryAnnouncement, drainMemoryAnnouncements, peekMemoryAnnouncements, bumpScanFuse, scanFuseCount, clearScanFuse, ANNOUNCEMENTS_FILE, MEMORY_ANNOUNCEMENTS_MAX, SCAN_FUSE_FILE, SCAN_FUSE_THRESHOLD, } from "./layout.js";

package/dist/core/memory-engine/layout.d.ts

@@ -36,6 +36,7 @@ export interface QuarantineOutcome {
     removed: boolean;
     detail?: string;
 }
+export declare function writeFileNoFollow(path: string, content: string): void;
 export declare function quarantineAndTombstone(path: string, content: string, quarantineDir: string, now: () => number): QuarantineOutcome;
 export declare const ANNOUNCEMENTS_FILE = "announcements.json";
 export declare const MEMORY_ANNOUNCEMENTS_MAX = 20;
@@ -57,6 +58,21 @@ export declare function bumpScanFuse(controlDir: string, key: string): number;
 export declare function readIndexRevs(controlDir: string): Record<string, string>;
 export declare function writeIndexRevs(controlDir: string, revs: Record<string, string>): void;
 export declare function scanFuseCount(controlDir: string, key: string): number;
+export declare const SESSION_POLLUTION_DIR = "session-pollution";
+export interface SessionPollutionRecord {
+    at: number;
+    reason: string;
+}
+export declare function markSessionPolluted(controlDir: string, sessionId: string, reason: string, now: () => number): boolean;
+export declare function readSessionPollution(controlDir: string, sessionId: string): SessionPollutionRecord | undefined;
+export declare const USAGE_RETRIEVED_FILE = "usage-retrieved.json";
+export declare const USAGE_RETRIEVED_MAX_IDS = 4096;
+export interface RetrievedAccountRow {
+    count: number;
+    lastAt: number;
+}
+export declare function recordRetrievedAccount(controlDir: string, ids: readonly string[], now: () => number): void;
+export declare function readRetrievedAccount(controlDir: string): Record<string, RetrievedAccountRow>;
 export declare function clearScanFuse(controlDir: string, keys: Iterable<string>): void;
 export declare function writeAllSync(fd: number, data: string): void;
 export declare function atomicWriteFileSync(path: string, data: string): void;

package/dist/core/memory-engine/layout.js

@@ -1,4 +1,5 @@
-import { closeSync, existsSync, fsyncSync, mkdirSync, openSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync, rmdirSync, statSync, unlinkSync, writeFileSync, writeSync } from "node:fs";
+import { closeSync, constants as fsConstants, existsSync, fsyncSync, mkdirSync, openSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync, rmdirSync, statSync, unlinkSync, writeFileSync, writeSync } from "node:fs";
+const { O_WRONLY, O_CREAT, O_TRUNC, O_NOFOLLOW } = fsConstants;
 import { homedir } from "node:os";
 import { createHash } from "node:crypto";
 import { basename, dirname, isAbsolute, join, resolve, sep } from "node:path";
@@ -306,6 +307,15 @@ export function ensureDirExists(dir) {
 }
 export const QUARANTINE_DIR = "quarantine";
 const DELETED_TOMBSTONE = "---\ndeleted: true\n---\n";
+export function writeFileNoFollow(path, content) {
+    const fd = openSync(path, O_WRONLY | O_CREAT | O_TRUNC | O_NOFOLLOW, 0o644);
+    try {
+        writeFileSync(fd, content, "utf8");
+    }
+    finally {
+        closeSync(fd);
+    }
+}
 let quarantineSeq = 0;
 export function quarantineAndTombstone(path, content, quarantineDir, now) {
     let captured;
@@ -340,7 +350,7 @@ export function quarantineAndTombstone(path, content, quarantineDir, now) {
     }
     catch (rmErr) {
         try {
-            writeFileSync(path, DELETED_TOMBSTONE, "utf8");
+            writeFileNoFollow(path, DELETED_TOMBSTONE);
             removed = true;
             detail = `${detail !== undefined ? `${detail}; ` : ""}delete failed (${rmErr instanceof Error ? rmErr.message : String(rmErr)}) — tombstoned in place`;
         }
@@ -589,6 +599,84 @@ export function writeIndexRevs(controlDir, revs) {
 export function scanFuseCount(controlDir, key) {
     return coerceFuse(readSidecarJson(controlDir, SCAN_FUSE_FILE))[key] ?? 0;
 }
+export const SESSION_POLLUTION_DIR = "session-pollution";
+function pollutionPath(controlDir, sessionId) {
+    return join(controlDir, SESSION_POLLUTION_DIR, `${encodeURIComponent(sessionId)}.json`);
+}
+export function markSessionPolluted(controlDir, sessionId, reason, now) {
+    const path = pollutionPath(controlDir, sessionId);
+    try {
+        ensureDirExists(dirname(path));
+        const record = { at: now(), reason };
+        writeFileSync(path, `${JSON.stringify(record, null, 2)}\n`, { encoding: "utf8", flag: "wx" });
+        return true;
+    }
+    catch (err) {
+        if (err instanceof Error && "code" in err && err.code === "EEXIST")
+            return true;
+        return false;
+    }
+}
+export function readSessionPollution(controlDir, sessionId) {
+    const path = pollutionPath(controlDir, sessionId);
+    let raw;
+    try {
+        raw = readFileSync(path, "utf8");
+    }
+    catch {
+        if (!existsSync(path))
+            return undefined;
+        return { at: 0, reason: "pollution marker present but unreadable (kept fail-closed)" };
+    }
+    try {
+        const parsed = JSON.parse(raw);
+        if (parsed !== null && typeof parsed === "object") {
+            const at = parsed.at;
+            const reason = parsed.reason;
+            if (typeof at === "number" && typeof reason === "string")
+                return { at, reason };
+        }
+    }
+    catch {
+    }
+    return { at: 0, reason: "pollution marker present but unreadable (kept fail-closed)" };
+}
+export const USAGE_RETRIEVED_FILE = "usage-retrieved.json";
+export const USAGE_RETRIEVED_MAX_IDS = 4096;
+function coerceRetrievedAccount(raw) {
+    if (!raw || typeof raw !== "object" || Array.isArray(raw))
+        return {};
+    const out = {};
+    for (const [k, v] of Object.entries(raw)) {
+        const row = v;
+        if (row && typeof row === "object" && typeof row.count === "number" && Number.isFinite(row.count) && row.count > 0 && typeof row.lastAt === "number" && Number.isFinite(row.lastAt)) {
+            out[k] = { count: Math.floor(row.count), lastAt: row.lastAt };
+        }
+    }
+    return out;
+}
+export function recordRetrievedAccount(controlDir, ids, now) {
+    if (ids.length === 0)
+        return;
+    const at = now();
+    lockedJournaledUpdate(controlDir, USAGE_RETRIEVED_FILE, (current) => {
+        const rows = coerceRetrievedAccount(current);
+        for (const id of ids) {
+            const prior = rows[id];
+            rows[id] = { count: (prior?.count ?? 0) + 1, lastAt: at };
+        }
+        const keys = Object.keys(rows);
+        if (keys.length > USAGE_RETRIEVED_MAX_IDS) {
+            keys.sort((a, b) => rows[a].lastAt - rows[b].lastAt || (a < b ? -1 : 1));
+            for (const cold of keys.slice(0, keys.length - USAGE_RETRIEVED_MAX_IDS))
+                delete rows[cold];
+        }
+        return rows;
+    });
+}
+export function readRetrievedAccount(controlDir) {
+    return coerceRetrievedAccount(readSidecarJson(controlDir, USAGE_RETRIEVED_FILE));
+}
 export function clearScanFuse(controlDir, keys) {
     const wanted = [...keys];
     if (wanted.length === 0)

package/dist/core/memory-engine/sync-client.d.ts

@@ -46,6 +46,7 @@ export interface SyncMemoryScopeOptions {
     now?: () => number;
     maxPushEntries?: number;
     maxPullEntries?: number;
+    maxEntryBytes?: number;
 }
 export interface MemorySyncClientResult {
     ok: boolean;

package/dist/core/memory-engine/sync-client.js

@@ -1,5 +1,7 @@
-import { computeEntryRev } from "./frontmatter.js";
+import { computeEntryRev, serializeEntryFile } from "./frontmatter.js";
 import { screenInboundEntries } from "./data-plane.js";
+import { scanMemoryFileName, scanMemoryWrite } from "./scan.js";
+import { MAX_MEMORY_BYTES } from "../memory.js";
 import { reconcileMemoryEntries } from "./sync.js";
 function memorySyncPath(scope) {
     return `/v1/memory/sync/${encodeURIComponent(scope)}`;
@@ -153,7 +155,7 @@ export async function syncMemoryScope(opts) {
     if (cursor !== undefined && cursor.peer !== peer) {
         throw new Error(`memory sync: cursor is for peer ${JSON.stringify(cursor.peer)}, not ${JSON.stringify(peer)}`);
     }
-    for (const [name, v] of [["maxPushEntries", opts.maxPushEntries], ["maxPullEntries", opts.maxPullEntries]]) {
+    for (const [name, v] of [["maxPushEntries", opts.maxPushEntries], ["maxPullEntries", opts.maxPullEntries], ["maxEntryBytes", opts.maxEntryBytes]]) {
         if (v !== undefined && (!Number.isSafeInteger(v) || v < 1)) {
             throw new Error(`memory sync: ${name} must be a positive integer (>= 1) when set, got ${String(v)}`);
         }
@@ -167,10 +169,26 @@ export async function syncMemoryScope(opts) {
     if (plan.pull.length > 0 || plan.deleteLocal.length > 0 || plan.conflicts.length > 0 || plan.cleared.length > 0) {
         throw new Error("memory sync: internal invariant violated — a baseline-stub peer produced pull/deleteLocal/conflict/cleared legs");
     }
-    let pushEntries = plan.push;
+    const pushGateConflicts = [];
+    const gatedPush = plan.push.filter((e) => {
+        const findings = [];
+        const nameFinding = scanMemoryFileName(`${e.slug}.md`);
+        if (nameFinding !== undefined)
+            findings.push(nameFinding);
+        findings.push(...scanMemoryWrite(serializeEntryFile(e), { maxBytes: opts.maxEntryBytes ?? MAX_MEMORY_BYTES }));
+        if (findings.length === 0)
+            return true;
+        pushGateConflicts.push({
+            side: "local",
+            id: e.id,
+            reason: `push_gate: ${findings.map((f) => `${f.code}: ${f.reason}`).join("; ")} — the entry was NOT pushed (it stays local; fix or remove it to stop this report)`,
+        });
+        return false;
+    });
+    let pushEntries = gatedPush;
     let pushTruncated = false;
     if (opts.maxPushEntries !== undefined) {
-        pushEntries = [...plan.push].sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+        pushEntries = [...gatedPush].sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
         if (pushEntries.length > opts.maxPushEntries) {
             pushEntries = pushEntries.slice(0, opts.maxPushEntries);
             pushTruncated = true;
@@ -184,7 +202,7 @@ export async function syncMemoryScope(opts) {
         ...(opts.maxPullEntries !== undefined ? { pull: { limit: opts.maxPullEntries } } : {}),
     };
     const resp = parseMemorySyncResponse(await transport(memorySyncPath(scope), request), scope, peer);
-    const conflicts = resp.conflicts.map((c) => ({ side: "server", ...c }));
+    const conflicts = [...pushGateConflicts, ...resp.conflicts.map((c) => ({ side: "server", ...c }))];
     const rejected = new Set();
     const localIds = new Set(local.map((e) => e.id));
     const serverEntryIds = new Set(resp.serverEntries.map((e) => e.id));

package/dist/core/memory-engine/tools.d.ts

@@ -0,0 +1,55 @@
+import type { ToolSpec } from "../types.js";
+import type { MemoryBackend } from "./types.js";
+export declare const MEMORY_SEARCH_TOOL_NAME = "memory_search";
+export declare const MEMORY_GET_TOOL_NAME = "memory_get";
+export declare const MEMORY_ENGINE_TOOL_NAMES: readonly ["memory_search", "memory_get"];
+export declare const MEMORY_SEARCH_DEFAULT_LIMIT = 8;
+export declare const MEMORY_SEARCH_MAX_LIMIT = 20;
+export declare const MEMORY_SEARCH_SNIPPET_CAP = 600;
+export declare const MEMORY_GET_PAGE_LINES = 200;
+export declare const MEMORY_GET_MAX_PAGE_LINES = 1000;
+export declare const MEMORY_GET_PAGE_CAP_BYTES: number;
+export interface MemoryEnginePlane {
+    backend: MemoryBackend;
+    scopes: readonly string[];
+    recordRetrieved: (ids: readonly string[]) => void;
+}
+export interface MemoryEngineToolsOptions {
+    planes: ReadonlyArray<MemoryEnginePlane>;
+    now?: () => number;
+}
+export interface MemorySearchHit {
+    id: string;
+    scope: string;
+    slug: string;
+    name?: string;
+    description?: string;
+    score: number;
+    mtimeMs: number;
+    sizeBytes: number;
+}
+export interface MemorySearchDetails {
+    outcome: "ok" | "refused" | "failed";
+    reason?: string;
+    hits?: MemorySearchHit[];
+}
+export interface MemoryGetDetails {
+    outcome: "ok" | "not_found" | "ambiguous" | "refused" | "failed";
+    reason?: string;
+    id?: string;
+    scope?: string;
+    slug?: string;
+    candidates?: Array<{
+        scope: string;
+        slug: string;
+        id: string;
+    }>;
+    offset?: number;
+    lines?: number;
+    totalLines?: number;
+}
+export declare function cutToBytes(text: string, maxBytes: number): {
+    text: string;
+    omittedBytes: number;
+};
+export declare function createMemoryEngineTools(opts: MemoryEngineToolsOptions): ToolSpec[];