@dsh-cc/memory-consolidation 0.5.0

package/lib/index.js

@@ -0,0 +1,325 @@
+/**
+ * Background memory consolidation: turn-end extraction and the three-gate
+ * dream rewrite.
+ *
+ * `agent/turn-stopping` fires an extraction subagent (via `ctx.jobs` +
+ * `ctx.subagents`, tools restricted to read/search) that reports durable facts
+ * as structured output, and evaluates the dream gates (time, session count,
+ * lock) to schedule a read-only review whose structured output rewrites
+ * MEMORY.md and the topic files. The forks hold no write tools — the memory
+ * directory sits outside the session workspace, so the fs sandbox would fence
+ * every model-side write with no escalation path from a background job; the
+ * plugin validates each reported batch and writes it host-side under a
+ * per-call policy confined to the memory directory (see `writeback.ts`). A
+ * failed dream rolls back the lock so the time gate re-opens.
+ *
+ * @module @dsh-cc/memory-consolidation
+ */
+import { join } from 'node:path';
+import z from '@deepseek-ai/schemastery';
+import { delegationDepthOf } from '@deepseek-ai/dsh-subagent';
+import { defaultDshHome } from '@deepseek-ai/dsh-home-paths';
+import { MEMORY_TOOL_FILTER } from "./tools.js";
+import { buildConsolidationPrompt, buildExtractionPrompt } from "./prompts.js";
+import { gatesPass } from "./gates.js";
+import { readLastConsolidatedAt, rollbackLock, tryAcquireLock, LOCK_STALE_MS } from "./lock.js";
+import { MEMORY_WRITES_SCHEMA, memoryWritePolicy, resolveWorkspaceMemoryDir, validateMemoryWrites, writeMemoryFiles, } from '@dsh-cc/memory';
+export { LOCK_FILE, LOCK_STALE_MS, readLastConsolidatedAt, rollbackLock, tryAcquireLock } from "./lock.js";
+export { gatesPass, timeGatePasses, sessionGatePasses } from "./gates.js";
+export { MEMORY_AGENT_TOOLS, MEMORY_TOOL_FILTER } from "./tools.js";
+export { buildConsolidationPrompt, buildExtractionPrompt } from "./prompts.js";
+// The write-back lives in @dsh-cc/memory (the memory directory owner);
+// re-exported here for consumers of the pre-move surface.
+export { MEMORY_WRITES_SCHEMA, WRITEBACK_MAX_FILE_BYTES, WRITEBACK_MAX_FILES, WRITEBACK_MAX_TOTAL_BYTES, memoryWritePolicy, validateMemoryWrites, writeMemoryFiles, } from '@dsh-cc/memory';
+export const name = 'memory-consolidation';
+/** Services required for background jobs and the subagent provider. */
+export const inject = ['jobs', 'subagents'];
+export const Config = z.object({
+    memoryHome: z.string(),
+    extractEnabled: z.boolean().default(true),
+    dreamEnabled: z.boolean().default(true),
+    minHours: z.number().default(24),
+    minSessions: z.number().default(5),
+    lockStaleMs: z.number().default(LOCK_STALE_MS),
+    subagentProviderName: z.string().default('fork'),
+});
+/**
+ * Start a memory-scoped forked subagent as a background job. The fork reports
+ * its file set via `outputSchema`; on settlement the plugin validates the
+ * batch and writes it host-side under a policy confined to `dir`. Resolves to
+ * a control object with an abort hook and a settle promise (true only when
+ * the reported writes were validated and persisted).
+ */
+async function startMemoryJob(ctx, agent, dir, provider, label, prompt) {
+    const jobs = ctx.get('jobs');
+    const subagents = ctx.get('subagents');
+    if (jobs === undefined || subagents === undefined) {
+        return { abort: () => { }, settled: Promise.resolve(false) };
+    }
+    const fs = ctx.get('fs');
+    const controller = new AbortController();
+    // `subagents.start` is async upstream — awaiting it is what exposes the run's
+    // `result` promise. Reading `run.result` on the un-awaited Promise throws
+    // "Cannot read properties of undefined (reading 'then')" and poisons the
+    // turn-stopping dispatch.
+    const run = await subagents.start(provider, {
+        label,
+        signal: controller.signal,
+        prompt: [{ type: 'text', text: prompt }],
+        parent: agent,
+        toolFilter: MEMORY_TOOL_FILTER,
+        // Defense-in-depth recursion cap: the top-level listener already gates on
+        // depth zero, so this fork's child never delegates. maxDepth is compared
+        // against the CHILD's resolved depth (parent + 1); a top-level parent's
+        // child resolves to 1 and passes, a grandchild to 2 is rejected.
+        maxDepth: 1,
+        outputSchema: MEMORY_WRITES_SCHEMA,
+    });
+    // Real job-done wiring: `done` maps the subagent outcome onto the JobHooks
+    // contract (must never reject). Aborted → killed (rolls back the dream
+    // lock); a non-completed stopReason, a missing/invalid payload, or a
+    // write-back failure → failed with detail; a validated, persisted batch →
+    // completed. All branches resolve.
+    const done = run.result.then(async (res) => {
+        if (controller.signal.aborted)
+            return { status: 'killed' };
+        if (res?.stopReason !== 'completed') {
+            return { status: 'failed', detail: `memory fork ended with stopReason ${String(res?.stopReason)}` };
+        }
+        if (fs === undefined) {
+            return { status: 'failed', detail: 'fs seam unavailable for memory write-back' };
+        }
+        try {
+            const writes = validateMemoryWrites(res.structured);
+            await writeMemoryFiles(fs, dir, writes);
+            return { status: 'completed' };
+        }
+        catch (err) {
+            return { status: 'failed', detail: String(err) };
+        }
+    }, (err) => controller.signal.aborted ? { status: 'killed' } : { status: 'failed', detail: String(err) });
+    const settled = done.then(o => o.status === 'completed');
+    jobs.start({
+        kind: 'subagent',
+        label,
+        owner: agent,
+        run: () => ({
+            cancel: (reason) => { controller.abort(reason); },
+            done,
+        }),
+    });
+    return { abort: (reason) => { controller.abort(reason); }, settled };
+}
+/**
+ * Register the consolidation plugin.
+ * @param ctx - the host context with jobs, subagents, fs, and sessions.
+ * @param config - consolidation behavior knobs.
+ */
+export function apply(ctx, config = {}) {
+    // The memory home is the ROOT: extraction/dream write into the turning
+    // agent's repository directory (`<home>/projects/<slug>` of the canonical
+    // git root), never the shared root, so memories stay isolated per repo.
+    const home = config.memoryHome ?? join(defaultDshHome(), 'memory');
+    const provider = config.subagentProviderName ?? 'fork';
+    const minHours = config.minHours ?? 24;
+    const minSessions = config.minSessions ?? 5;
+    // Per-session extraction single-flight. Keyed by session id so each top-level
+    // agent's in-flight flag and last-spawned event count are isolated.
+    const flight = new Map();
+    // One dream in flight across the whole plugin instance (per memory dir).
+    let dreamInFlight = false;
+    // Reset the flight state when this plugin fiber is disposed (hygiene / test
+    // isolation). cordis `ctx.on` is typed strictly to `keyof Events`, so cleanup
+    // is registered as a fiber effect rather than a 'dispose' listener.
+    ctx.effect(() => () => {
+        flight.clear();
+        dreamInFlight = false;
+    }, 'memory-consolidation: reset flight state');
+    ctx.on('agent/turn-stopping', ({ agent, signal }) => {
+        // All predicates are synchronous and run before any await, so the flags
+        // below are set before a second, interleaved turn-stopping could observe
+        // them.
+        if (signal.aborted)
+            return;
+        if (!isTopLevel(agent))
+            return;
+        const sessionId = agent.session.header.id;
+        if (config.extractEnabled ?? true) {
+            const entry = flight.get(sessionId);
+            // Single-flight: skip while an extraction is in flight or when no new
+            // events have arrived since the last spawn.
+            if (!entry?.extracting && agent.session.events.length !== entry?.lastEvents) {
+                flight.set(sessionId, { extracting: true, lastEvents: agent.session.events.length });
+                void runExtraction(ctx, agent, home, provider).finally(() => {
+                    const cur = flight.get(sessionId);
+                    if (cur)
+                        cur.extracting = false;
+                });
+            }
+        }
+        if (config.dreamEnabled ?? true) {
+            if (!dreamInFlight) {
+                dreamInFlight = true;
+                void runDream(ctx, agent, home, provider, minHours, minSessions)
+                    .catch(() => { })
+                    .finally(() => { dreamInFlight = false; });
+            }
+        }
+    });
+}
+/**
+ * Whether an agent is top-level (not a delegated subagent). This is the root
+ * fix for the extraction/dream recursion: a subagent's own turn-end must never
+ * spawn another memory fork. Fails CLOSED — any throw from reading the depth
+ * treats the agent as a child so nothing is spawned.
+ */
+function isTopLevel(agent) {
+    try {
+        return delegationDepthOf(agent) === 0;
+    }
+    catch {
+        return false;
+    }
+}
+/** Surface event types whose count a single extraction batch reviews. */
+const SURFACE_EVENT_TYPES = new Set(['user/message', 'assistant/message', 'tool/result']);
+/** Upper bound on the injected index: first 200 lines or 8 KiB, whichever first. */
+const INDEX_CAP_LINES = 200;
+const INDEX_CAP_BYTES = 8 * 1024;
+const INDEX_TRUNCATED_MARKER = '(index truncated; rely on MEMORY.md in-dir for the rest)';
+async function runExtraction(ctx, agent, home, provider) {
+    // The extraction writes into the turning agent's repository directory —
+    // the shared home root holds only explicitly-global memories.
+    const dir = resolveWorkspaceMemoryDir(home, sessionTranscriptDir(agent));
+    // Only model-visible surface events count toward the batch size.
+    const surfaceCount = agent.session.events.filter((e) => SURFACE_EVENT_TYPES.has(e.type)).length;
+    // The index read happens AFTER the in-flight/content gates (runExtraction is
+    // only reached once a spawn is committed), so a skipped spawn never pays the
+    // fs cost. Any failure here degrades to an empty index and still spawns.
+    const existingIndex = await readExistingIndex(ctx, dir);
+    const prompt = buildExtractionPrompt(surfaceCount, dir, existingIndex);
+    // Fire-and-forget: extraction failure must never fail the turn itself. The
+    // job status still reflects the real outcome (the fork's structured report
+    // is validated and written host-side before `done` completes).
+    return startMemoryJob(ctx, agent, dir, provider, 'extract-memories', prompt)
+        .catch(() => { })
+        .then(() => { });
+}
+/**
+ * Read the existing topic index to inject into the extraction prompt: the
+ * MEMORY.md body when present, else the names of sibling topic `.md` files.
+ * Swallow-all: any error or an absent fs yields an empty index so a spawn is
+ * never blocked by the read. Content is capped at 200 lines / 8 KiB so a huge
+ * index cannot bloat the prompt.
+ */
+async function readExistingIndex(ctx, dir) {
+    const fs = ctx.get('fs');
+    if (fs === undefined)
+        return '';
+    try {
+        const memoryTarget = await fs.resolve(join(dir, 'MEMORY.md'));
+        const info = await fs.stat(memoryTarget);
+        let raw;
+        if (info !== undefined) {
+            raw = await fs.readText(memoryTarget);
+        }
+        else {
+            // No index file: fall back to listing topic `.md` files in the directory.
+            const dirTarget = await fs.resolve(dir);
+            const entries = await fs.listDir(dirTarget);
+            raw = entries
+                .filter((e) => e.type === 'file' && e.name.endsWith('.md') && e.name !== 'MEMORY.md')
+                .map((e) => e.name)
+                .sort()
+                .join('\n');
+        }
+        if (raw === '')
+            return '';
+        // Cap at the first 200 lines OR 8 KiB, whichever comes first; append a
+        // marker when truncated so the model knows to rely on the in-dir file.
+        const lines = raw.split('\n');
+        const kept = [];
+        let bytes = 0;
+        let truncated = false;
+        for (const line of lines) {
+            if (kept.length >= INDEX_CAP_LINES) {
+                truncated = true;
+                break;
+            }
+            const add = line.length + (kept.length > 0 ? 1 : 0);
+            if (bytes + add > INDEX_CAP_BYTES) {
+                truncated = true;
+                break;
+            }
+            kept.push(line);
+            bytes += add;
+        }
+        const capped = kept.join('\n');
+        return truncated ? `${capped}\n${INDEX_TRUNCATED_MARKER}` : capped;
+    }
+    catch {
+        return '';
+    }
+}
+async function runDream(ctx, agent, home, provider, minHours, minSessions) {
+    const fs = ctx.get('fs');
+    if (fs === undefined)
+        return;
+    const dir = resolveWorkspaceMemoryDir(home, sessionTranscriptDir(agent));
+    const now = Date.now();
+    const lastAt = await readLastConsolidatedAt(fs, dir);
+    const sessionIds = listNewSessions(ctx, lastAt);
+    if (!gatesPass({
+        lastConsolidatedAt: lastAt,
+        now,
+        minHours,
+        sessionCount: sessionIds.length,
+        minSessions,
+    }))
+        return;
+    const priorAt = await tryAcquireLock(fs, dir, process.pid, now, memoryWritePolicy(dir));
+    if (priorAt === null)
+        return;
+    const prompt = buildConsolidationPrompt(dir, sessionTranscriptDir(agent), sessionIds);
+    const job = await startMemoryJob(ctx, agent, dir, provider, 'memory-consolidation', prompt);
+    void job.settled.then((ok) => {
+        if (!ok)
+            void rollbackLock(fs, dir, priorAt, memoryWritePolicy(dir));
+    });
+}
+/** Live sessions are the transcripts available to review; absent sessions skip. */
+function listNewSessions(ctx, lastAt) {
+    const sessions = ctx.get('sessions');
+    if (sessions === undefined)
+        return [];
+    return sessions
+        .list()
+        // Subagent sessions (validated delegationDepth > 0) are excluded from both
+        // the min-sessions count and the dream input: their content is already
+        // covered by turn-end extraction. Absent/invalid depth is treated as 0.
+        .filter(session => {
+        const d = session.header?.delegationDepth;
+        return !(Number.isSafeInteger(d) && d > 0);
+    })
+        .map(session => ({ id: session.id, at: sessionStartOf(session) }))
+        .filter(session => session.at > lastAt)
+        .sort((a, b) => a.at - b.at)
+        .map(session => session.id);
+}
+/**
+ * Session start epoch, defensively read from the header. The dream gate is
+ * skip-oriented, so an unreadable or absent timestamp conservatively counts as
+ * NEW (over-inclusion only costs a re-read). Accepted limitation: a session
+ * created before `lastAt` but still active after it is excluded from the dream
+ * input — turn-end extraction covers recent content; dream is a coarse
+ * periodic pass.
+ */
+function sessionStartOf(session) {
+    const at = session.header?.createdAt;
+    return Number.isSafeInteger(at) && at > 0 ? at : Number.MAX_SAFE_INTEGER;
+}
+/** The transcript directory is the agent's cwd. */
+function sessionTranscriptDir(agent) {
+    return agent.session.header.cwd ?? process.cwd();
+}
+//# sourceMappingURL=index.js.map

package/lib/index.js.map

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

package/lib/invariant.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Package-owned invariant companion for `@dsh-cc/memory-consolidation`.
+ * @module @dsh-cc/memory-consolidation/invariant
+ */
+import type { Context } from '@deepseek-ai/cordis';
+/** Cordis companion plugin name. */
+export declare const name = "memory-consolidation-invariant";
+/** Service required before the companion can reserve package ownership. */
+export declare const inject: string[];
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export declare const apply: (ctx: Context) => Promise<() => void>;
+//# sourceMappingURL=invariant.d.ts.map

package/lib/invariant.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"invariant.d.ts","sourceRoot":"","sources":["../src/invariant.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAKlD,oCAAoC;AACpC,eAAO,MAAM,IAAI,mCAAmC,CAAA;AACpD,2EAA2E;AAC3E,eAAO,MAAM,MAAM,UAAiB,CAAA;AAQpC;;;;GAIG;AACH,eAAO,MAAM,KAAK,GAAI,KAAK,OAAO,KAAG,OAAO,CAAC,MAAM,IAAI,CACU,CAAA"}

package/lib/invariant.js

@@ -0,0 +1,22 @@
+/**
+ * Package-owned invariant companion for `@dsh-cc/memory-consolidation`.
+ * @module @dsh-cc/memory-consolidation/invariant
+ */
+const PACKAGE_NAME = '@dsh-cc/memory-consolidation';
+/** Cordis companion plugin name. */
+export const name = 'memory-consolidation-invariant';
+/** Service required before the companion can reserve package ownership. */
+export const inject = ['invariants'];
+/**
+ * No runtime invariant: the dream gates and lock acquisition are enforced at
+ * the owning plugin seams, with no independent event/data relation.
+ */
+const install = () => { };
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export const apply = (ctx) => Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install));
+/* jscpd:ignore-end */
+//# sourceMappingURL=invariant.js.map

package/lib/invariant.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"invariant.js","sourceRoot":"","sources":["../src/invariant.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAMH,MAAM,YAAY,GAAG,8BAA8B,CAAA;AAEnD,oCAAoC;AACpC,MAAM,CAAC,MAAM,IAAI,GAAG,gCAAgC,CAAA;AACpD,2EAA2E;AAC3E,MAAM,CAAC,MAAM,MAAM,GAAG,CAAC,YAAY,CAAC,CAAA;AAEpC;;;GAGG;AACH,MAAM,OAAO,GAAuB,GAAG,EAAE,GAAE,CAAC,CAAA;AAE5C;;;;GAIG;AACH,MAAM,CAAC,MAAM,KAAK,GAAG,CAAC,GAAY,EAAuB,EAAE,CACzD,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,UAAU,CAAC,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAC,CAAC,CAAA;AACjE,sBAAsB"}

package/lib/lock.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Memory consolidation lock and last-consolidated timestamp.
+ *
+ * The `ctx.fs` seam exposes no mtime, so the lock file's body carries the
+ * holder PID and the last-consolidated epoch rather than the file mtime (the
+ * reference uses mtime as the timestamp). A holder is stale and reclaimable
+ * once its stored timestamp passes {@link LOCK_STALE_MS}.
+ * @module @dsh-cc/memory-consolidation/lock
+ */
+import type { FileSystem } from '@deepseek-ai/dsh-fs';
+import type { MemoryWritePolicy } from '@dsh-cc/memory';
+/** Lock filename inside the memory directory. */
+export declare const LOCK_FILE = ".consolidation-lock";
+/** A holder is stale past this even if it is still alive (also guards PID reuse). */
+export declare const LOCK_STALE_MS: number;
+/**
+ * Read the last consolidated epoch, 0 when no lock file exists.
+ * @param fs - the filesystem seam.
+ * @param dir - the memory directory holding the lock.
+ * @returns the epoch ms of the last consolidation, or 0.
+ */
+export declare function readLastConsolidatedAt(fs: FileSystem, dir: string): Promise<number>;
+/**
+ * Acquire the consolidation lock. Returns the PRIOR consolidated epoch (for
+ * rollback), or `null` when a non-stale holder blocks acquisition.
+ *
+ * On success the lock is written with this process's PID and `now` as the
+ * consolidated epoch. A stale holder (older than {@link LOCK_STALE_MS}) is
+ * reclaimed; a crash mid-consolidation leaves a stale file the next process
+ * reclaims. The prior epoch is captured before the write so a caller can roll
+ * back to the exact pre-acquire state.
+ * @param fs - the filesystem seam.
+ * @param dir - the memory directory holding the lock.
+ * @param pid - this process's id.
+ * @param now - the current epoch used as the new consolidated timestamp.
+ * @param policy - per-call sandbox policy for the lock write; required when the
+ *   memory directory sits outside the caller's sandbox writable roots.
+ * @returns the pre-acquire epoch (0 when none) to roll back on failure, or `null` when blocked.
+ */
+export declare function tryAcquireLock(fs: FileSystem, dir: string, pid: number, now: number, policy?: MemoryWritePolicy): Promise<number | null>;
+/**
+ * Roll the lock back to `priorAt` after a failed or killed consolidation.
+ * A `priorAt` of 0 encodes the no-file state (the next read returns 0) with
+ * the holder PID cleared. Best-effort: failures are swallowed so the caller's
+ * teardown does not throw.
+ * @param fs - the filesystem seam.
+ * @param dir - the memory directory holding the lock.
+ * @param priorAt - the pre-acquire consolidated epoch to restore.
+ * @param policy - per-call sandbox policy for the lock write (see tryAcquireLock).
+ */
+export declare function rollbackLock(fs: FileSystem, dir: string, priorAt: number, policy?: MemoryWritePolicy): Promise<void>;
+//# sourceMappingURL=lock.d.ts.map

package/lib/lock.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lock.d.ts","sourceRoot":"","sources":["../src/lock.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,KAAK,EAAE,UAAU,EAAY,MAAM,qBAAqB,CAAA;AAC/D,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAA;AAEvD,iDAAiD;AACjD,eAAO,MAAM,SAAS,wBAAwB,CAAA;AAE9C,qFAAqF;AACrF,eAAO,MAAM,aAAa,QAAiB,CAAA;AAmB3C;;;;;GAKG;AACH,wBAAsB,sBAAsB,CAAC,EAAE,EAAE,UAAU,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAQzF;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,cAAc,CAClC,EAAE,EAAE,UAAU,EACd,GAAG,EAAE,MAAM,EACX,GAAG,EAAE,MAAM,EACX,GAAG,EAAE,MAAM,EACX,MAAM,CAAC,EAAE,iBAAiB,GACzB,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CA+BxB;AAED;;;;;;;;;GASG;AACH,wBAAsB,YAAY,CAAC,EAAE,EAAE,UAAU,EAAE,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC,CAI1H"}

package/lib/lock.js

@@ -0,0 +1,114 @@
+/**
+ * Memory consolidation lock and last-consolidated timestamp.
+ *
+ * The `ctx.fs` seam exposes no mtime, so the lock file's body carries the
+ * holder PID and the last-consolidated epoch rather than the file mtime (the
+ * reference uses mtime as the timestamp). A holder is stale and reclaimable
+ * once its stored timestamp passes {@link LOCK_STALE_MS}.
+ * @module @dsh-cc/memory-consolidation/lock
+ */
+import { join } from 'node:path';
+/** Lock filename inside the memory directory. */
+export const LOCK_FILE = '.consolidation-lock';
+/** A holder is stale past this even if it is still alive (also guards PID reuse). */
+export const LOCK_STALE_MS = 60 * 60 * 1000;
+/** Content of the lock file: `<pid>\n<lastConsolidatedAtMs>\n`. */
+const format = (pid, at) => `${pid}\n${at}\n`;
+function parse(content) {
+    const [pidRaw, atRaw] = content.trim().split('\n');
+    const pid = pidRaw !== undefined && Number.isFinite(Number(pidRaw)) ? Number(pidRaw) : undefined;
+    const at = atRaw !== undefined && Number.isFinite(Number(atRaw)) ? Number(atRaw) : 0;
+    return { pid, at };
+}
+/** Resolve the lock target and whether it exists. */
+async function lockTarget(fs, dir) {
+    const target = await fs.resolve(join(dir, LOCK_FILE));
+    const info = await fs.stat(target);
+    return { target, absent: info === undefined };
+}
+/**
+ * Read the last consolidated epoch, 0 when no lock file exists.
+ * @param fs - the filesystem seam.
+ * @param dir - the memory directory holding the lock.
+ * @returns the epoch ms of the last consolidation, or 0.
+ */
+export async function readLastConsolidatedAt(fs, dir) {
+    const { target, absent } = await lockTarget(fs, dir);
+    if (absent)
+        return 0;
+    try {
+        return parse(await fs.readText(target)).at;
+    }
+    catch {
+        return 0;
+    }
+}
+/**
+ * Acquire the consolidation lock. Returns the PRIOR consolidated epoch (for
+ * rollback), or `null` when a non-stale holder blocks acquisition.
+ *
+ * On success the lock is written with this process's PID and `now` as the
+ * consolidated epoch. A stale holder (older than {@link LOCK_STALE_MS}) is
+ * reclaimed; a crash mid-consolidation leaves a stale file the next process
+ * reclaims. The prior epoch is captured before the write so a caller can roll
+ * back to the exact pre-acquire state.
+ * @param fs - the filesystem seam.
+ * @param dir - the memory directory holding the lock.
+ * @param pid - this process's id.
+ * @param now - the current epoch used as the new consolidated timestamp.
+ * @param policy - per-call sandbox policy for the lock write; required when the
+ *   memory directory sits outside the caller's sandbox writable roots.
+ * @returns the pre-acquire epoch (0 when none) to roll back on failure, or `null` when blocked.
+ */
+export async function tryAcquireLock(fs, dir, pid, now, policy) {
+    const { target, absent } = await lockTarget(fs, dir);
+    let priorAt = 0;
+    if (!absent) {
+        try {
+            const { at } = parse(await fs.readText(target));
+            priorAt = at;
+            if (at > 0 && now - at < LOCK_STALE_MS) {
+                // A recently stamped lock is held; the stale window reclaims crashed holders.
+                return null;
+            }
+        }
+        catch {
+            // Unreadable or malformed lock: reclaim below, treating it as empty.
+        }
+    }
+    await fs.writeText(target, format(pid, now), undefined, undefined, policy);
+    // Read the lock back once to verify we own it. If the content is not EXACTLY
+    // ours, a cross-process writer interleaved between our read and write and we
+    // lost the race. This narrows the TOCTOU window to a sub-millisecond
+    // symmetric-collision; the residual race is accepted (the stale-window
+    // reclaim handles crashes, and the worst case is a redundant MEMORY.md
+    // rewrite bounded by minHours). A read-back THROW is treated as a
+    // verify-failure too (conservative).
+    let owned = false;
+    try {
+        owned = (await fs.readText(target)) === format(pid, now);
+    }
+    catch {
+        owned = false;
+    }
+    if (!owned)
+        return null;
+    return priorAt;
+}
+/**
+ * Roll the lock back to `priorAt` after a failed or killed consolidation.
+ * A `priorAt` of 0 encodes the no-file state (the next read returns 0) with
+ * the holder PID cleared. Best-effort: failures are swallowed so the caller's
+ * teardown does not throw.
+ * @param fs - the filesystem seam.
+ * @param dir - the memory directory holding the lock.
+ * @param priorAt - the pre-acquire consolidated epoch to restore.
+ * @param policy - per-call sandbox policy for the lock write (see tryAcquireLock).
+ */
+export async function rollbackLock(fs, dir, priorAt, policy) {
+    const target = await fs.resolve(join(dir, LOCK_FILE)).catch(() => undefined);
+    if (target === undefined)
+        return;
+    await fs.writeText(target, format(0, priorAt), undefined, undefined, policy).catch(() => { });
+}
+//# sourceMappingURL=lock.js.map

package/lib/lock.js.map

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

package/lib/prompts.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Prompt builders for the extraction and dream forks. Both are pure text
+ * assembly so they are unit-testable and stable model-visible contracts.
+ *
+ * The forks hold no write tools: they report their file set through the
+ * driver-injected `structured_output` tool, and the plugin writes the files
+ * host-side (see `writeback.ts`). The prompts below are the model-facing half
+ * of that contract.
+ * @module @dsh-cc/memory-consolidation/prompts
+ */
+/**
+ * Build the <system-reminder> user prompt that extracts durable facts from a
+ * batch of recent model-visible messages into structured memory writes.
+ * @param surfaceMessageCount - how many model-visible surface events (user/message
+ *   + assistant/message + tool/result) this run reviews.
+ * @param memoryDir - the memory directory the reported files belong to.
+ * @param existingIndex - a prior topic manifest, if any.
+ * @returns the prompt text.
+ */
+export declare function buildExtractionPrompt(surfaceMessageCount: number, memoryDir: string, existingIndex: string): string;
+/**
+ * Build the <system-reminder> user prompt that reviews past sessions and
+ * consolidates them into the memory directory, returned as structured writes.
+ * @param memoryDir - the memory directory being rewritten.
+ * @param transcriptDir - the directory holding past session transcripts.
+ * @param sessionHints - a list of session ids to review.
+ * @returns the prompt text.
+ */
+export declare function buildConsolidationPrompt(memoryDir: string, transcriptDir: string, sessionHints: readonly string[]): string;
+//# sourceMappingURL=prompts.d.ts.map

package/lib/prompts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompts.d.ts","sourceRoot":"","sources":["../src/prompts.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAOH;;;;;;;;GAQG;AACH,wBAAgB,qBAAqB,CACnC,mBAAmB,EAAE,MAAM,EAC3B,SAAS,EAAE,MAAM,EACjB,aAAa,EAAE,MAAM,GACpB,MAAM,CAeR;AAED;;;;;;;GAOG;AACH,wBAAgB,wBAAwB,CACtC,SAAS,EAAE,MAAM,EACjB,aAAa,EAAE,MAAM,EACrB,YAAY,EAAE,SAAS,MAAM,EAAE,GAC9B,MAAM,CAYR"}