hippo-memory 1.70.0 → 1.71.0

package/dist/api/tokens.d.ts

@@ -1,21 +1,14 @@
 import type { TokenSummary, TokenSurface } from '../store/token-ledger.js';
 import type { FailureSummary } from '../store/failure-log.js';
 import type { Context } from './types.js';
-/**
- * Record memory text handed to an agent in the token ledger.
- * Best-effort: never throws, because a ledger failure must not fail the
- * recall or context call that produced the text.
- */
+/** Records memory text handed to an agent in the token ledger. Best-effort: never throws, since a ledger failure must not fail the recall or context call. */
 export declare function recordTokens(ctx: Context, surface: TokenSurface, use: {
     items: number;
     tokens: number;
     sessionId?: string | null;
 }): Promise<void>;
-/**
- * Token ledger totals for the tenant over the last `days` days (default 30):
- * tokens sent, skipped as unchanged and re-read by later model calls, per
- * surface, with session counts and mean tokens per session.
- */
+/** Token ledger totals for the tenant over the last `days` days (default 30): tokens sent, skipped as unchanged and re-read,
+ * per surface, with session counts and mean tokens per session. */
 export declare function tokenSummary(ctx: Context, opts?: {
     days?: number;
 }): TokenSummary;

package/dist/api/tokens.js

@@ -4,11 +4,7 @@ import { storeFor } from '../store/index.js';
 import { failureLogSummary, tokenUseSummary } from '../store/usage-reports.js';
 import { errorMessage, log } from '../util/log.js';
 import { DAY_MS } from '../util/time.js';
-/**
- * Record memory text handed to an agent in the token ledger.
- * Best-effort: never throws, because a ledger failure must not fail the
- * recall or context call that produced the text.
- */
+/** Records memory text handed to an agent in the token ledger. Best-effort: never throws, since a ledger failure must not fail the recall or context call. */
 export async function recordTokens(ctx, surface, use) {
     try {
         await storeFor(ctx).recordTokens({
@@ -25,11 +21,8 @@ export async function recordTokens(ctx, surface, use) {
         log.warnThenDebug('api-token-ledger', `token ledger write failed; the reply is unaffected: ${errorMessage(err)}`);
     }
 }
-/**
- * Token ledger totals for the tenant over the last `days` days (default 30):
- * tokens sent, skipped as unchanged and re-read by later model calls, per
- * surface, with session counts and mean tokens per session.
- */
+/** Token ledger totals for the tenant over the last `days` days (default 30): tokens sent, skipped as unchanged and re-read,
+ * per surface, with session counts and mean tokens per session. */
 export function tokenSummary(ctx, opts = {}) {
     return tokenUseSummary(ctx.hippoRoot, ctx.tenantId, reportWindowStart(opts.days));
 }

package/dist/api/types.d.ts

@@ -1,12 +1,7 @@
 import { BadRequestError } from '../core/api-errors.js';
 import type { HippoStore } from '../store/index.js';
-/**
- * Actor identity + authorization role for a Context.
- *
- * Carries the audit-log subject plus a role for /v1/sleep admin gating. Audit
- * helpers take the bare `string`, so callers pass `ctx.actor.subject`. Role checks happen at the request
- * boundary (e.g. /v1/sleep), except in authCreate and authRevoke (ForbiddenError).
- */
+/** Actor identity + role for a Context: the audit-log subject (pass `ctx.actor.subject` to audit helpers) and the role for admin gating.
+ * Role checks happen at the request boundary (e.g. /v1/sleep), except in authCreate and authRevoke (ForbiddenError). */
 export interface Actor {
     /** 'cli' | 'localhost:cli' | 'api_key:<key_id>' | 'mcp' | 'connector:slack' | 'connector:github' */
     subject: string;
@@ -34,31 +29,13 @@ export type StoreReply<C extends Context, R> = C extends {
     readonly hippoRoot: string;
     readonly store?: undefined;
 } ? R : R | Promise<R>;
-/**
- * Helper for building process-local Actor values (admin and host admin),
- * used by CLI and CLI-run connector Context constructors so the role
- * boilerplate isn't repeated at every site. Bearer-authed callers (HTTP
- * /v1/*) construct Actor directly from the api_keys row's role column via
- * buildContextWithAuth in src/server.ts.
- */
+/** Builds process-local Actor values (admin and host admin) for CLI and CLI-run connector Contexts; Bearer-authed callers build Actor from the api_keys row
+ * instead. */
 export declare function adminActor(subject: string): Actor;
 /** The per-person key: an unowned key gets its own bucket by key id rather than sharing one. */
 export declare function ownerOrSubject(actor: Actor): string;
-/**
- * Thrown by `api.recall` when a caller's options violate a recall contract
- * that has been opted into via env. Carries a stable `code` field for HTTP /
- * MCP / CLI render paths to discriminate without parsing the message.
- *
- * Codes:
- *   - 'fresh_tail_requires_session_id' — `freshTailCount > 0` AND no
- *     `freshTailSessionId` AND `HIPPO_REQUIRE_SESSION_SCOPED_FRESH_TAIL=1`.
- *     Default behaviour (env unset) returns tenant-wide rows; the env gate
- *     is opt-in so multi-session tenants can fail loud instead of silently
- *     surfacing cross-session rows tagged `isFreshTail=true`.
- *   - 'invalid_scorer_window' — `opts.scorerWindow` is set to a non-positive,
- *     non-integer, or non-finite value. 0 would route through FTS/LIKE
- *     `LIMIT 0` and then an uncapped full-store fallback, so it is validated upfront.
- */
+/** Thrown by `api.recall` on a contract violation; the stable `code` lets callers discriminate without parsing the message.
+ * 'fresh_tail_requires_session_id' (needs HIPPO_REQUIRE_SESSION_SCOPED_FRESH_TAIL=1) or 'invalid_scorer_window' (0 would hit an uncapped fallback). */
 export declare class RecallContractError extends BadRequestError {
     readonly code: 'fresh_tail_requires_session_id' | 'invalid_scorer_window';
     constructor(code: 'fresh_tail_requires_session_id' | 'invalid_scorer_window', message: string);

package/dist/api/types.js

@@ -1,12 +1,7 @@
 // Request context (caller identity and tenant) shared by every API module, plus the recall contract error.
 import { BadRequestError } from '../core/api-errors.js';
-/**
- * Helper for building process-local Actor values (admin and host admin),
- * used by CLI and CLI-run connector Context constructors so the role
- * boilerplate isn't repeated at every site. Bearer-authed callers (HTTP
- * /v1/*) construct Actor directly from the api_keys row's role column via
- * buildContextWithAuth in src/server.ts.
- */
+/** Builds process-local Actor values (admin and host admin) for CLI and CLI-run connector Contexts; Bearer-authed callers build Actor from the api_keys row
+ * instead. */
 export function adminActor(subject) {
     return { subject, role: 'admin', hostAdmin: true };
 }
@@ -14,21 +9,8 @@ export function adminActor(subject) {
 export function ownerOrSubject(actor) {
     return actor.owner ?? actor.subject;
 }
-/**
- * Thrown by `api.recall` when a caller's options violate a recall contract
- * that has been opted into via env. Carries a stable `code` field for HTTP /
- * MCP / CLI render paths to discriminate without parsing the message.
- *
- * Codes:
- *   - 'fresh_tail_requires_session_id' — `freshTailCount > 0` AND no
- *     `freshTailSessionId` AND `HIPPO_REQUIRE_SESSION_SCOPED_FRESH_TAIL=1`.
- *     Default behaviour (env unset) returns tenant-wide rows; the env gate
- *     is opt-in so multi-session tenants can fail loud instead of silently
- *     surfacing cross-session rows tagged `isFreshTail=true`.
- *   - 'invalid_scorer_window' — `opts.scorerWindow` is set to a non-positive,
- *     non-integer, or non-finite value. 0 would route through FTS/LIKE
- *     `LIMIT 0` and then an uncapped full-store fallback, so it is validated upfront.
- */
+/** Thrown by `api.recall` on a contract violation; the stable `code` lets callers discriminate without parsing the message.
+ * 'fresh_tail_requires_session_id' (needs HIPPO_REQUIRE_SESSION_SCOPED_FRESH_TAIL=1) or 'invalid_scorer_window' (0 would hit an uncapped fallback). */
 export class RecallContractError extends BadRequestError {
     code;
     constructor(code, message) {

package/dist/capture/command.d.ts

@@ -12,21 +12,13 @@ export interface CaptureOptions {
     stdinText?: string;
     stdinTimedOut?: boolean;
     sessionTurns?: readonly SessionTurn[];
-    /**
-     * Tee stdout/stderr to this log file while capture runs. Mirrors the
-     * pattern used by `hippo sleep --log-file` so the SessionEnd hook output
-     * (invisible during TUI teardown) can be surfaced via `hippo last-sleep`
-     * on the next session start. Appends rather than truncates — `hippo sleep`
-     * writes the same file first in the SessionEnd sequence.
-     */
+    /** Tee stdout/stderr to this log file while capture runs, so SessionEnd output (lost in TUI teardown) shows via `hippo last-sleep`.
+     *  Appends, because `hippo sleep` writes the same file first. */
     logFile?: string;
     dryRun: boolean;
     global: boolean;
-    /**
-     * Tenant scope for the dedup read in `cmdCaptureCore`. When provided
-     * AND `global` is false, the dedup check only considers this tenant's
-     * existing memories. Undefined means host-wide dedup. Ignored when `global: true` (global captures are host-wide).
-     */
+    /** Tenant scope for the dedup read in `cmdCaptureCore`: when set and `global` is false, only this tenant's memories count.
+     *  Undefined means host-wide dedup; ignored when `global: true`. */
     tenantId?: string;
     /** The session's project: rows are stamped with its id, and dedup reads its rows under either name. */
     originProject?: ProjectRef;

package/dist/capture/command.js

@@ -8,7 +8,7 @@ import { writeEntryMirrors } from '../store/entry-writes.js';
 import { EVERY_SCOPE, loadTextsHoldingWords } from '../store/candidates.js';
 import { updateStatsOn } from '../store/index-and-stats.js';
 import { gatedWrite } from '../trust/gated-write.js';
-import { getGlobalRoot, initGlobal } from '../sharing/shared.js';
+import { getGlobalRoot, initGlobal } from '../sharing/global-store.js';
 import { embedMemory } from '../store/embeddings/index.js';
 import { maskEmails, redactSecretsStrict } from '../util/secret-detect.js';
 import { RejectedValueError, checkRejectionGuard } from '../store/rejection.js';
@@ -20,11 +20,7 @@ import { errorMessage, log } from '../util/log.js';
 import { extractFromTexts } from './extract.js';
 import { collectSessionTurns, sessionTail, resolveLastSessionTranscript } from './transcript.js';
 export function cmdCapture(hippoRoot, options) {
-    // Tee stdout/stderr to a log file when --log-file is set. Used by the
-    // SessionEnd hook so output (otherwise swallowed by TUI teardown) surfaces
-    // on the next session start via `hippo last-sleep`. Runs second in the
-    // SessionEnd sequence after `hippo sleep`, so we APPEND rather than
-    // truncate — sleep already wrote its own header + body to this file.
+    // Tee to a log file for the SessionEnd hook; APPEND, because `hippo sleep` runs first in that sequence and already wrote its header and body.
     const restoreStdio = options.logFile ? beginLogTee(options.logFile) : null;
     try {
         cmdCaptureCore(hippoRoot, options);
@@ -41,12 +37,7 @@ export function cmdCapture(hippoRoot, options) {
             restoreStdio();
     }
 }
-/**
- * Append-mode tee: writes a banner line then mirrors every stdout/stderr
- * chunk to `logFile` until the returned restore function is called.
- * Failures to write the log are non-fatal; the real streams still get
- * the data.
- */
+/** Append-mode tee: mirror every stdout/stderr chunk to `logFile` until the returned restore function is called; a log-write failure is non-fatal. */
 function beginLogTee(logFile) {
     if (!writeLogBanner(logFile))
         return () => { };
@@ -56,16 +47,10 @@ function beginLogTee(logFile) {
     const wrapWrite = (origWrite) => {
         const wrapped = (...args) => {
             tee(args[0]);
-            // SAFETY: forwarding the exact arguments Node's real overloaded
-            // `write` received is safe regardless of which overload the call
-            // site used — Node dispatches on the actual argument shapes at
-            // runtime, and `StreamWriteArgs` is the union of both overloads'
-            // parameter lists.
+            // SAFETY: forwarding the exact arguments the real overloaded `write` received is safe; `StreamWriteArgs` is the union of both overloads' parameter lists.
             return origWrite(...args);
         };
-        // SAFETY: `wrapped` matches both real `write` overload shapes it's
-        // assigned to; TS can't verify a single implementation covers an
-        // overloaded type, but this one forwards to the real stream method.
+        // SAFETY: `wrapped` matches both real `write` overload shapes; TS cannot verify one implementation covers an overloaded type.
         return wrapped;
     };
     process.stdout.write = wrapWrite(origStdoutWrite);
@@ -131,8 +116,7 @@ function cmdCaptureCore(hippoRoot, options) {
     };
     printCaptureTally(options, captureExtractedItems(targetRoot, writeOpts, extracted, keys));
 }
-// Dedup only against rows this capture's reader sees: another tenant's rows, or another
-// project's, are hidden from it, so they must not stop its own copy.
+// Dedup only against rows this capture's reader sees: another tenant's or project's rows are hidden, so they must not stop its own copy.
 // Only a row holding an item's longest word can hold that item, so the store returns those rows and no others.
 function storedKeysInView(targetRoot, options, extracted) {
     const stored = loadTextsHoldingWords(targetRoot, options.global ? undefined : options.tenantId, extracted.map((item) => longestWord(item.content)), undefined, EVERY_SCOPE);

package/dist/capture/compact.d.ts

@@ -1,12 +1,6 @@
 import { type HookRuntime } from '../core/capture-contract.js';
-/**
- * Log-forgery guard: messages here interpolate payload-controlled values
- * (transcript paths, session ids). Strip C0 control chars — newlines above
- * all — so a crafted value can't inject fake `[hippo] ...` log lines.
- * Exported for every `[hippo]`-prefixed log writer that interpolates
- * payload-controlled values (cli.ts appendSessionEndCloseLog) — one shared
- * guard, not per-file copies.
- */
+/** Log-forgery guard: strip C0 control chars (newlines above all) from payload-controlled values so a crafted value cannot inject fake `[hippo]` log lines.
+ *  Exported as the one shared guard for every `[hippo]`-prefixed log writer that interpolates payload values. */
 export declare function sanitizeLogMessage(message: string): string;
 export interface PreCompactOptions {
     stdinText?: string;
@@ -16,13 +10,8 @@ export interface PreCompactOptions {
     /** Called once when the hook accepts a compaction, with the text it printed or null when it printed none. */
     onBoundary?: (printed: string | null) => void;
 }
-/**
- * PreCompact hook entry point. Exit code 2 on PreCompact BLOCKS compaction,
- * so this verb must exit 0 on every path — malformed stdin, missing
- * transcript, and store errors all degrade to a logged no-op rather than a
- * thrown error. Callers (src/cli.ts) must not wrap this in anything that
- * could turn a caught-and-logged failure back into a non-zero exit.
- */
+/** PreCompact hook entry point. Exit code 2 BLOCKS compaction, so every path (bad stdin, missing transcript, store error) must exit 0 as a logged no-op.
+ *  Callers must not wrap this in anything that turns a caught-and-logged failure into a non-zero exit. */
 export declare function cmdPreCompact(hippoRoot: string, options: PreCompactOptions): Promise<void>;
 export interface PostCompactOptions {
     stdinText?: string;

package/dist/capture/compact.js

@@ -10,19 +10,10 @@ import { errorMessage, log as logger } from '../util/log.js';
 import { resolveLastSessionTranscript } from './transcript.js';
 import { isVscodeTranscript } from './copilot-transcript.js';
 import { mergeWorkingState, transcriptWorkingState } from './working-state.js';
-// ---------------------------------------------------------------------------
-// `hippo pre-compact` — PreCompact hook producer
-// ---------------------------------------------------------------------------
 // Diagnostic-only log; a long-lived install must not grow it unbounded.
 const PRE_COMPACT_LOG_MAX_BYTES = 256 * 1024;
-/**
- * Log-forgery guard: messages here interpolate payload-controlled values
- * (transcript paths, session ids). Strip C0 control chars — newlines above
- * all — so a crafted value can't inject fake `[hippo] ...` log lines.
- * Exported for every `[hippo]`-prefixed log writer that interpolates
- * payload-controlled values (cli.ts appendSessionEndCloseLog) — one shared
- * guard, not per-file copies.
- */
+/** Log-forgery guard: strip C0 control chars (newlines above all) from payload-controlled values so a crafted value cannot inject fake `[hippo]` log lines.
+ *  Exported as the one shared guard for every `[hippo]`-prefixed log writer that interpolates payload values. */
 export function sanitizeLogMessage(message) {
     // eslint-disable-next-line no-control-regex
     return message.replace(/[\x00-\x1f]/g, '');
@@ -30,11 +21,18 @@ export function sanitizeLogMessage(message) {
 function appendPreCompactLog(logFile, message) {
     try {
         fs.mkdirSync(path.dirname(logFile), { recursive: true });
-        const stat = fs.existsSync(logFile) ? fs.statSync(logFile) : null;
-        if (stat && stat.size > PRE_COMPACT_LOG_MAX_BYTES) {
-            fs.writeFileSync(logFile, '', 'utf8'); // start fresh — dumb cap, no rotation
+        // One handle, so the cap acts on the file it measured; two hooks writing in the same instant can overwrite one diagnostic line, which this log accepts.
+        const fd = fs.openSync(logFile, fs.constants.O_RDWR | fs.constants.O_CREAT);
+        try {
+            const size = fs.fstatSync(fd).size;
+            const startFresh = size > PRE_COMPACT_LOG_MAX_BYTES; // a dumb cap, no rotation
+            if (startFresh)
+                fs.ftruncateSync(fd, 0);
+            fs.writeSync(fd, `[hippo] ${new Date().toISOString()} ${sanitizeLogMessage(message)}\n`, startFresh ? 0 : size, 'utf8');
+        }
+        finally {
+            fs.closeSync(fd);
         }
-        fs.appendFileSync(logFile, `[hippo] ${new Date().toISOString()} ${sanitizeLogMessage(message)}\n`, 'utf8');
     }
     catch (err) {
         // Diagnostic-only; a log write failure must never affect the exit-0 contract.
@@ -74,9 +72,7 @@ function snapshotJustSaved(hippoRoot, sessionId) {
 /** Runs the PreCompact producer: records the compaction, asks the summariser for memories, saves a working-state snapshot. Never extracts memories itself; SessionEnd capture owns that. */
 function runPreCompact(hippoRoot, options, logFile) {
     const { stdinText, stdinTimedOut = false, runtime = 'claude-code' } = options;
-    // The PreCompact hook fires in every Claude Code project, including
-    // ones that never ran `hippo init`, so gate before any store-opening call
-    // (saveActiveTaskSnapshot etc. call initStore, which would create one).
+    // PreCompact fires in every Claude Code project, including ones that never ran `hippo init`; gate before any call that would create a store.
     if (!isInitialized(hippoRoot)) {
         appendPreCompactLog(logFile, 'skip: store not initialized');
         return;
@@ -180,13 +176,8 @@ function saveDerivedSnapshot(hippoRoot, logFile, sessionId, recordId, derived) {
         }
     }
 }
-/**
- * PreCompact hook entry point. Exit code 2 on PreCompact BLOCKS compaction,
- * so this verb must exit 0 on every path — malformed stdin, missing
- * transcript, and store errors all degrade to a logged no-op rather than a
- * thrown error. Callers (src/cli.ts) must not wrap this in anything that
- * could turn a caught-and-logged failure back into a non-zero exit.
- */
+/** PreCompact hook entry point. Exit code 2 BLOCKS compaction, so every path (bad stdin, missing transcript, store error) must exit 0 as a logged no-op.
+ *  Callers must not wrap this in anything that turns a caught-and-logged failure into a non-zero exit. */
 export async function cmdPreCompact(hippoRoot, options) {
     const logFile = options.logFile ?? defaultPreCompactLogPath();
     try {

package/dist/capture/compaction-record.js

@@ -284,6 +284,55 @@ export function saveItems(db, hippoRoot, ctx, log) {
     finishItemWrites(hippoRoot, writes, log);
     return writes.written.length;
 }
+/** One failure, told once to the hook's output and once to the structured log. */
+function reportFailure(log, step, reason) {
+    log(`${step} failed: ${reason}`);
+    logger.error(`post-compact: ${step} failed: ${reason}`);
+}
+function recordStep(step) {
+    try {
+        const record = recordSummary(step.db, step.hippoRoot, step.tenantId, { meta: step.payload, text: step.text, at: step.at });
+        step.result.snapshotSaved = record.snapshotSaved;
+        return record;
+    }
+    catch (err) {
+        if (isSqliteBusy(err))
+            throw err;
+        reportFailure(step.log, 'record step', errorMessage(err));
+        return null;
+    }
+}
+/** Busy with a saved record defers to sleep; any other failure goes to the caller. */
+function itemsStep(step, record) {
+    const { payload, hippoRoot, log } = step;
+    try {
+        step.result.written = saveItems(step.db, hippoRoot, {
+            tenantId: step.tenantId,
+            recordId: record?.id ?? null,
+            sessionId: payload.sessionId,
+            originProject: record?.originProject ?? compactionOrigin(hippoRoot, payload.cwd),
+            cwd: payload.cwd,
+            items: step.text.items,
+        }, log);
+    }
+    catch (err) {
+        if (!isSqliteBusy(err) || record === null)
+            throw err;
+        // The record already holds the items; sleep finishes them.
+        step.result.deferred = true;
+        log(`store busy, items left for the next sleep: ${errorMessage(err)}`);
+    }
+}
+function spoolSummary(hippoRoot, payload, text, at, reason, result, log) {
+    try {
+        spool(hippoRoot, resolveTenantId({}), payload, text, at);
+        result.deferred = true;
+        log(`store busy, summary spooled: ${reason}`);
+    }
+    catch (spoolErr) {
+        reportFailure(log, 'spool', errorMessage(spoolErr));
+    }
+}
 /** The PostCompact work: record the summary, then write its items. Each step is independent; a busy store spools or defers. Never throws. */
 export function saveCompaction(hippoRoot, payload, log) {
     const result = { written: null, deferred: false, snapshotSaved: false };
@@ -298,52 +347,14 @@ export function saveCompaction(hippoRoot, payload, log) {
     let db;
     try {
         db = openHippoDb(hippoRoot, { busyWaitMs: COMPACTION_DB_WAIT_MS });
-        const tenantId = resolveTenantId({});
-        let record = null;
-        try {
-            record = recordSummary(db, hippoRoot, tenantId, { meta: payload, text, at });
-            result.snapshotSaved = record.snapshotSaved;
-        }
-        catch (err) {
-            if (isSqliteBusy(err))
-                throw err;
-            log(`record step failed: ${errorMessage(err)}`);
-            logger.error(`post-compact: record step failed: ${errorMessage(err)}`);
-        }
-        try {
-            result.written = saveItems(db, hippoRoot, {
-                tenantId,
-                recordId: record?.id ?? null,
-                sessionId: payload.sessionId,
-                originProject: record?.originProject ?? compactionOrigin(hippoRoot, payload.cwd),
-                cwd: payload.cwd,
-                items: text.items,
-            }, log);
-        }
-        catch (err) {
-            if (!isSqliteBusy(err) || record === null)
-                throw err;
-            // The record already holds the items; sleep finishes them.
-            result.deferred = true;
-            log(`store busy, items left for the next sleep: ${errorMessage(err)}`);
-        }
+        const step = { db, hippoRoot, tenantId: resolveTenantId({}), payload, text, at, result, log };
+        itemsStep(step, recordStep(step));
     }
     catch (err) {
-        if (isSqliteBusy(err) || db === undefined) {
-            try {
-                spool(hippoRoot, resolveTenantId({}), payload, text, at);
-                result.deferred = true;
-                log(`store busy, summary spooled: ${errorMessage(err)}`);
-            }
-            catch (spoolErr) {
-                log(`spool failed: ${errorMessage(spoolErr)}`);
-                logger.error(`post-compact: spool failed: ${errorMessage(spoolErr)}`);
-            }
-        }
-        else {
-            log(`items step failed: ${errorMessage(err)}`);
-            logger.error(`post-compact: items step failed: ${errorMessage(err)}`);
-        }
+        if (isSqliteBusy(err) || db === undefined)
+            spoolSummary(hippoRoot, payload, text, at, errorMessage(err), result, log);
+        else
+            reportFailure(log, 'items step', errorMessage(err));
     }
     finally {
         if (db)
@@ -400,61 +411,74 @@ function closeWithoutSummary(db, tenantId, id, log) {
 function nextStartedAt(db, record) {
     return nextCompactionStart(db, record.tenantId, record.sessionId, record.startedAt);
 }
+/** The one place a record becomes the argument saveItems takes. */
+function itemContext(tenantId, record, items = record.items) {
+    return { tenantId, recordId: record.id, sessionId: record.sessionId, originProject: record.originProject, cwd: record.cwd, items };
+}
 /** Records a spooled summary, then writes its items. */
 function spoolImporter(db, hippoRoot, log) {
     return (spooled, recorded) => {
         const record = recordSummary(db, hippoRoot, spooled.tenantId, { meta: spooled.payload, text: spooled.text, at: spooled.at });
         // The record holds the items now, so the file is done even if the write below fails.
         recorded();
-        saveItems(db, hippoRoot, { tenantId: spooled.tenantId, recordId: record.id, sessionId: record.sessionId, originProject: record.originProject, cwd: record.cwd, items: record.items }, log);
+        saveItems(db, hippoRoot, itemContext(spooled.tenantId, record), log);
     };
 }
-/** Finishes what a killed hook or a busy store left: `summarised` records, spool files, and `started` records the transcript can fill. Returns how many compactions it saved. */
-export function replayCompactions(db, hippoRoot, log, deadline = Number.POSITIVE_INFINITY) {
-    const tenantId = resolveTenantId({});
-    const now = Date.now();
+function replayStalled(db, hippoRoot, tenantId, now, log, deadline) {
     let finished = 0;
     const stalled = stalledSummarisedRows(db, tenantId, new Date(now - REPLAY_AFTER_MS).toISOString()).map(toRecord);
     for (const record of stalled) {
         if (Date.now() > deadline)
             break;
         try {
-            saveItems(db, hippoRoot, { tenantId, recordId: record.id, sessionId: record.sessionId, originProject: record.originProject, cwd: record.cwd, items: record.items }, log);
+            saveItems(db, hippoRoot, itemContext(tenantId, record), log);
             finished++;
         }
         catch (err) {
             log(`replay of ${record.id} failed: ${errorMessage(err)}`);
         }
     }
+    return finished;
+}
+function replaySpool(db, hippoRoot, tenantId, log, deadline) {
     try {
-        finished += importSpool(hippoRoot, tenantId, log, deadline, spoolImporter(db, hippoRoot, log));
+        return importSpool(hippoRoot, tenantId, log, deadline, spoolImporter(db, hippoRoot, log));
     }
     catch (err) {
         log(`spool import failed: ${errorMessage(err)}`);
+        return 0;
     }
+}
+/** Fills one open record from its transcript; true when it saved items. */
+function fillFromTranscript(db, hippoRoot, tenantId, record, log) {
+    if (record.transcriptPath === null || !fs.existsSync(record.transcriptPath))
+        return false;
+    const next = nextStartedAt(db, record);
+    const found = transcriptSummary(record.transcriptPath, Date.parse(record.startedAt), next === null ? Number.POSITIVE_INFINITY : Date.parse(next));
+    if (found === null) {
+        // The record is past REPLAY_AFTER_MS, so a window that is fully scanned or out of reach stays empty.
+        closeWithoutSummary(db, tenantId, record.id, log);
+        return false;
+    }
+    const { found: listed, ...text } = readCompactionText(found);
+    if (!listed)
+        log(`no memories section in the transcript summary for ${record.id}`);
+    if (!markSummarised(db, tenantId, record.id, { text, summarisedAt: new Date().toISOString() })) {
+        log(`${record.id} was filled by another process`);
+        return false;
+    }
+    saveItems(db, hippoRoot, itemContext(tenantId, record, text.items), log);
+    return true;
+}
+function replayOpen(db, hippoRoot, tenantId, now, log, deadline) {
+    let finished = 0;
     const open = openTranscriptRows(db, tenantId, new Date(now - REPLAY_AFTER_MS).toISOString(), new Date(now - TRANSCRIPT_FILL_WINDOW_MS).toISOString()).map(toRecord);
     for (const record of open) {
         if (Date.now() > deadline)
             break;
         try {
-            if (record.transcriptPath === null || !fs.existsSync(record.transcriptPath))
-                continue;
-            const next = nextStartedAt(db, record);
-            const found = transcriptSummary(record.transcriptPath, Date.parse(record.startedAt), next === null ? Number.POSITIVE_INFINITY : Date.parse(next));
-            if (found === null) {
-                // The record is past REPLAY_AFTER_MS, so a window that is fully scanned or out of reach stays empty.
-                closeWithoutSummary(db, tenantId, record.id, log);
-                continue;
-            }
-            const { found: listed, ...text } = readCompactionText(found);
-            if (!listed)
-                log(`no memories section in the transcript summary for ${record.id}`);
-            if (!markSummarised(db, tenantId, record.id, { text, summarisedAt: new Date().toISOString() })) {
-                log(`${record.id} was filled by another process`);
-                continue;
-            }
-            saveItems(db, hippoRoot, { tenantId, recordId: record.id, sessionId: record.sessionId, originProject: record.originProject, cwd: record.cwd, items: text.items }, log);
-            finished++;
+            if (fillFromTranscript(db, hippoRoot, tenantId, record, log))
+                finished++;
         }
         catch (err) {
             log(`transcript fill of ${record.id} failed: ${errorMessage(err)}`);
@@ -462,6 +486,14 @@ export function replayCompactions(db, hippoRoot, log, deadline = Number.POSITIVE
     }
     return finished;
 }
+/** Finishes what a killed hook or a busy store left: `summarised` records, spool files, and `started` records the transcript can fill. Returns how many compactions it saved. */
+export function replayCompactions(db, hippoRoot, log, deadline = Number.POSITIVE_INFINITY) {
+    const tenantId = resolveTenantId({});
+    const now = Date.now();
+    return replayStalled(db, hippoRoot, tenantId, now, log, deadline)
+        + replaySpool(db, hippoRoot, tenantId, log, deadline)
+        + replayOpen(db, hippoRoot, tenantId, now, log, deadline);
+}
 /** For `hippo sleep` and post-compact: opens the store itself and never throws. */
 export function replayCompactionsAt(hippoRoot, log, opts = {}) {
     let db;

package/dist/capture/compaction-spool.d.ts

@@ -21,7 +21,7 @@ export interface SpoolFs {
     }): void;
 }
 /** Test-only seam, so a test can make one fs call fail; null restores the real fs. */
-export declare function __setSpoolFs(next: SpoolFs | null): void;
+export declare function _setSpoolFsForTests(next: SpoolFs | null): void;
 export interface SpooledCompaction {
     tenantId: string;
     payload: PostCompactPayload;

package/dist/capture/compaction-spool.js

@@ -29,7 +29,7 @@ const NEW_STEM = /^(\d{13})-[0-9a-f]{8}$/;
 const LEGACY_STEM_TIME = /-(\d+)$/;
 let fsx = fs;
 /** Test-only seam, so a test can make one fs call fail; null restores the real fs. */
-export function __setSpoolFs(next) {
+export function _setSpoolFsForTests(next) {
     fsx = next ?? fs;
 }
 const stamp = (ms) => String(Math.trunc(ms)).padStart(STAMP_DIGITS, '0');

package/dist/capture/session-digest.d.ts

@@ -30,7 +30,7 @@ export declare function readSessionTranscript(transcriptPath: string, log: (mess
 /** The transcript, read once and scanned, or null with the reason logged. */
 export declare function readSessionScan(transcriptPath: string, log: (message: string) => void): SessionScan | null;
 /** Test-only seam, the scheduler's pattern: lets a test prove a network path never reaches the probe. Null restores it. */
-export declare function __setDigestExistsProbe(probe: ((p: string) => boolean) | null): void;
+export declare function _setDigestExistsProbeForTests(probe: ((p: string) => boolean) | null): void;
 /** The store root is realpath'd; transcript paths are not, and a deleted file has no realpath of its own. Null for a network path. */
 export declare function realFsPath(p: string): string | null;
 /** Repo-relative with forward slashes, '' for the root itself, null outside the repo or when the path cannot be resolved. */

package/dist/capture/session-digest.js

@@ -18,7 +18,7 @@ import { loadLiveContentsBySourceAndTag } from '../store/entry-reads.js';
 import { SNAPSHOT_AMBIENT_MAX_AGE_MS } from '../store/sessions.js';
 import { loadLatestHandoff } from '../store/handoffs.js';
 import { isSyntheticMessage } from '../store/token-ledger.js';
-import { readTranscriptTail } from '../util/transcript-tail.js';
+import { readOpenTranscriptTail } from '../util/transcript-tail.js';
 /** Five-word runs are stock phrases; six in a row is a copied clause. */
 export const ECHO_WINDOW = 6;
 /** Five sentences of about 150 chars leave room for the Changed line inside the total cap. */
@@ -228,11 +228,17 @@ export function scanSessionTranscript(jsonl) {
     };
 }
 export function readSessionTranscript(transcriptPath, log) {
-    const size = fs.statSync(transcriptPath).size;
-    if (size <= READ_CAP_BYTES)
-        return fs.readFileSync(transcriptPath, 'utf8');
-    log(`digest: transcript is ${size} bytes, reading its last ${READ_CAP_BYTES}`);
-    return readTranscriptTail(transcriptPath, READ_CAP_BYTES);
+    const fd = fs.openSync(transcriptPath, 'r');
+    try {
+        const size = fs.fstatSync(fd).size;
+        if (size <= READ_CAP_BYTES)
+            return fs.readFileSync(fd, 'utf8');
+        log(`digest: transcript is ${size} bytes, reading its last ${READ_CAP_BYTES}`);
+        return readOpenTranscriptTail(fd, size, READ_CAP_BYTES);
+    }
+    finally {
+        fs.closeSync(fd);
+    }
 }
 /** The transcript, read once and scanned, or null with the reason logged. */
 export function readSessionScan(transcriptPath, log) {
@@ -246,7 +252,7 @@ export function readSessionScan(transcriptPath, log) {
 }
 let existsProbe = fs.existsSync;
 /** Test-only seam, the scheduler's pattern: lets a test prove a network path never reaches the probe. Null restores it. */
-export function __setDigestExistsProbe(probe) {
+export function _setDigestExistsProbeForTests(probe) {
     existsProbe = probe ?? fs.existsSync;
 }
 /** A \\host or //host path would make existsSync open an SMB connection to a host named in transcript text. */