hippo-memory 1.59.0 → 1.61.0

package/dist/capture/command.js

@@ -0,0 +1,264 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import { createMemory, Layer } from '../memory.js';
+import { duplicateKey, storedTextKeys } from '../same-text.js';
+import { stampOriginProject } from '../store/entry-row.js';
+import { isInitialized, openStore } from '../store/open.js';
+import { writeEntryMirrors } from '../store/entry-writes.js';
+import { loadAllEntries } from '../store/entry-reads.js';
+import { updateStats } from '../store/index-and-stats.js';
+import { gatedWrite } from '../gated-write.js';
+import { getGlobalRoot, initGlobal } from '../shared.js';
+import { embedMemory } from '../embeddings.js';
+import { maskEmails, redactSecretsStrict } from '../secret-detect.js';
+import { RejectedValueError, checkRejectionGuard } from '../rejection.js';
+import { openHippoDb, closeHippoDb } from '../db.js';
+import { loadConfig } from '../config.js';
+import { classifyOriginProject } from '../project-identity.js';
+import { isStringValue } from '../capture-contract.js';
+import { errorMessage, log } from '../log.js';
+import { extractFromText } from './extract.js';
+import { collectSessionTurns, summariseSessionTurns, 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.
+    const restoreStdio = options.logFile ? beginLogTee(options.logFile) : null;
+    try {
+        cmdCaptureCore(hippoRoot, options);
+        if (options.logFile)
+            console.log('[hippo] capture complete');
+    }
+    catch (err) {
+        if (options.logFile)
+            console.log(`[hippo] capture failed: ${errorMessage(err)}`);
+        throw err;
+    }
+    finally {
+        if (restoreStdio)
+            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.
+ */
+function beginLogTee(logFile) {
+    try {
+        fs.mkdirSync(path.dirname(logFile), { recursive: true });
+        fs.appendFileSync(logFile, `[hippo] ${new Date().toISOString()} capturing session...\n`, 'utf8');
+    }
+    catch (err) {
+        log.warn(`could not open log file ${logFile}: ${errorMessage(err)}`);
+        return () => { };
+    }
+    const origStdoutWrite = process.stdout.write.bind(process.stdout);
+    const origStderrWrite = process.stderr.write.bind(process.stderr);
+    const tee = (chunk) => {
+        try {
+            const buf = isStringValue(chunk) ? chunk : Buffer.from(chunk).toString('utf8');
+            fs.appendFileSync(logFile, buf, 'utf8');
+        }
+        catch {
+            // log failures are non-fatal
+        }
+    };
+    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.
+            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.
+        return wrapped;
+    };
+    process.stdout.write = wrapWrite(origStdoutWrite);
+    process.stderr.write = wrapWrite(origStderrWrite);
+    return () => {
+        process.stdout.write = origStdoutWrite;
+        process.stderr.write = origStderrWrite;
+    };
+}
+// Console lines here are the `hippo capture` command's printed result, so they stay off the logger.
+function cmdCaptureCore(hippoRoot, options) {
+    const useGlobal = options.global;
+    const targetRoot = useGlobal ? getGlobalRoot() : hippoRoot;
+    if (useGlobal) {
+        initGlobal();
+    }
+    else {
+        if (!isInitialized(hippoRoot)) {
+            console.error(`No hippo store at ${hippoRoot} (searched ${process.cwd()} and its parents up to your home directory). Run \`hippo init\` first.`);
+            process.exit(1);
+        }
+    }
+    // Read input text
+    const text = readCaptureText(options);
+    if (text === null)
+        return;
+    if (!text || text.trim().length === 0) {
+        console.log('No text to capture from.');
+        return;
+    }
+    // Scrub once here, as the snapshot fields are: every source can carry a pasted token (AGENTS.md: no secrets in memories).
+    const extracted = extractFromText(maskEmails(redactSecretsStrict(text)));
+    if (extracted.length === 0) {
+        console.log('No actionable items found in the input.');
+        return;
+    }
+    // Dedup only against rows this capture's reader sees: another tenant's rows (L9), or another
+    // project's, are hidden from it, so they must not stop its own copy.
+    const stored = loadAllEntries(targetRoot, useGlobal ? undefined : options.tenantId);
+    const origin = options.originProject;
+    const keys = storedTextKeys(origin === undefined
+        ? stored
+        : stored.filter((e) => classifyOriginProject(e.origin_project, origin) !== 'cross-project'));
+    const { captured, skipped, rejected } = captureExtractedItems(targetRoot, options, extracted, keys);
+    const prefix = options.dryRun ? '[dry-run] ' : '';
+    const globalPrefix = useGlobal ? '[global] ' : '';
+    console.log(`\n${prefix}${globalPrefix}Captured ${captured} items (${skipped} skipped as duplicates` +
+        (rejected > 0 ? `, ${rejected} rejected` : '') +
+        ')');
+}
+/** The raw text for the chosen source; null after printing why a last-session capture has nothing. */
+function readCaptureText(options) {
+    switch (options.source) {
+        case 'stdin': {
+            try {
+                return fs.readFileSync(0, 'utf8');
+            }
+            catch {
+                console.error('No input on stdin. Pipe text in or use --file <path>.');
+                process.exit(1);
+            }
+        }
+        case 'file': {
+            if (!options.filePath) {
+                console.error('Missing file path. Usage: hippo capture --file <path>');
+                process.exit(1);
+            }
+            if (!fs.existsSync(options.filePath)) {
+                console.error(`File not found: ${options.filePath}`);
+                process.exit(1);
+            }
+            return fs.readFileSync(options.filePath, 'utf8');
+        }
+        case 'last-session': {
+            let turns = options.sessionTurns;
+            if (!turns) {
+                const resolved = resolveLastSessionTranscript(options.transcriptPath, options.stdinText, { mayScan: !options.stdinTimedOut });
+                if (!resolved) {
+                    console.log('No transcript found. Pass --transcript <path> or run from a SessionEnd hook.');
+                    return null;
+                }
+                turns = collectSessionTurns(fs.readFileSync(resolved, 'utf8'));
+            }
+            const text = summariseSessionTurns(turns);
+            if (!text) {
+                console.log('Transcript had no user/assistant messages to summarise.');
+                return null;
+            }
+            return text;
+        }
+    }
+}
+function captureExtractedItems(targetRoot, options, extracted, keys) {
+    const tally = { captured: 0, skipped: 0, rejected: 0 };
+    const baseHalfLifeDays = loadConfig(targetRoot).defaultHalfLifeDays;
+    // AT1 P2 fix (dry-run parity, docs/plans/2026-08-15-at1-rejected-value-tombstone.md):
+    // dry-run used to skip the guarded write branch ENTIRELY, so a tombstoned
+    // extraction printed as `[capture]` and counted toward `captured` — the
+    // preview lied about what a real run would do. Mirrors importers.ts's
+    // importEntries dry-run probe (commit 6146e82): open a read-only handle
+    // once, run the same checkRejectionGuard the real write path uses via
+    // writeEntry, never write anything.
+    const dryRunDb = options.dryRun ? openHippoDb(targetRoot) : null;
+    const writeDb = options.dryRun ? null : openStore(targetRoot);
+    try {
+        for (const item of extracted) {
+            if (keys.has(duplicateKey(item.content))) {
+                tally.skipped++;
+                if (options.dryRun) {
+                    console.log(`  [skip] (${item.category}) ${item.content.slice(0, 80)}`);
+                }
+                continue;
+            }
+            const entry = captureEntry(item, options, baseHalfLifeDays);
+            tally[captureOne({ targetRoot, options, dryRunDb, writeDb, keys }, item, entry)]++;
+        }
+    }
+    finally {
+        if (dryRunDb)
+            closeHippoDb(dryRunDb);
+        if (writeDb)
+            closeHippoDb(writeDb);
+    }
+    return tally;
+}
+function captureEntry(item, options, baseHalfLifeDays) {
+    const useGlobal = options.global;
+    // A3: kind defaults to 'distilled'. capture.ts extracts curated items from
+    // session output (not raw transcript chunks), so distilled is correct. If a
+    // future variant captures full raw session text, it MUST set kind: 'raw'
+    // and route deletions through archiveRawMemory(). See MEMORY_ENVELOPE.md.
+    // L9: the dedup read above is scoped by options.tenantId — the WRITE
+    // must match, or scoped-dedup-passes-then-default-tenant-write breaks
+    // the per-tenant contract. Mirror the dedup-read guard: when
+    // global: true, the global store is host-wide and tenant is irrelevant
+    // (createMemory's default 'default' applies). When global: false,
+    // options.tenantId scopes the write to the same tenant as the dedup.
+    const created = createMemory(item.content, {
+        layer: Layer.Episodic,
+        tags: item.tags,
+        source: 'capture',
+        confidence: 'observed',
+        tenantId: useGlobal ? undefined : options.tenantId,
+        baseHalfLifeDays,
+    });
+    return options.originProject === undefined ? created : { ...created, origin_project: options.originProject };
+}
+/** Previews or writes one non-duplicate item and names the tally it counts toward. */
+function captureOne(ctx, item, entry) {
+    const { targetRoot, options, dryRunDb, writeDb, keys } = ctx;
+    if (options.dryRun) {
+        if (dryRunDb) {
+            try {
+                checkRejectionGuard(dryRunDb, entry.tenantId ?? 'default', entry.id, entry.content);
+            }
+            catch (err) {
+                if (err instanceof RejectedValueError) {
+                    console.log(`  [reject] (${item.category}) ${item.content.slice(0, 80)} - matches a rejected value`);
+                    return 'rejected';
+                }
+                throw err;
+            }
+        }
+        console.log(`  [capture] (${item.category}) ${item.content}`);
+    }
+    else if (writeDb !== null) {
+        // AT1 (plan §3 containment): one rejected item must not abort the
+        // rest of this capture's items.
+        const stamped = stampOriginProject(targetRoot, entry);
+        const outcome = gatedWrite(writeDb, targetRoot, stamped);
+        if (outcome === 'skipped:rejected')
+            return 'rejected';
+        if (outcome !== 'written')
+            return 'skipped';
+        writeEntryMirrors(targetRoot, stamped);
+        updateStats(targetRoot, { remembered: 1 });
+        keys.add(duplicateKey(item.content)); // within-batch dedup
+        void embedMemory(targetRoot, entry);
+    }
+    return 'captured';
+}
+//# sourceMappingURL=command.js.map

package/dist/capture/compact.d.ts

@@ -0,0 +1,44 @@
+import { type TaskSnapshot } from '../store/rows.js';
+export declare const PRE_COMPACT_TASK_CAP = 200;
+export declare const PRE_COMPACT_SUMMARY_CAP = 2000;
+export declare const PRE_COMPACT_NEXT_STEP_CAP = 500;
+/**
+ * Cap from the RECENT end: summariseTranscript emits user turns oldest-to-
+ * newest with assistant responses after them, so a head-first cap keeps
+ * stale context and drops exactly the newest working state this feature
+ * exists to preserve. Keep the LAST maxChars instead, aligned forward to a
+ * nearby line start, with a trim marker (codex round 3).
+ */
+export declare function truncateKeepNewest(text: string, maxChars: number): string;
+/**
+ * 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.
+ */
+export declare function sanitizeLogMessage(message: string): string;
+/** A session's task, summary and next step from its transcript tail, secrets scrubbed and capped, '' where none; null with a logged reason when nothing is derivable. */
+export declare function transcriptWorkingState(transcriptPath: string, log: (message: string) => void): Pick<TaskSnapshot, 'task' | 'summary' | 'next_step'> | null;
+export interface PreCompactOptions {
+    stdinText?: string;
+    stdinTimedOut?: boolean;
+    logFile?: string;
+}
+/**
+ * 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.
+ */
+export declare function cmdPreCompact(hippoRoot: string, options: PreCompactOptions): Promise<void>;
+export interface PostCompactOptions {
+    stdinText?: string;
+    logFile?: string;
+    afterSave?: (transcriptPath: string, originProject: string, log: (message: string) => void) => void;
+}
+/** PostCompact entry point: saves the summary and its items, replays earlier leftovers, returns the one line to show. Never throws, so the hook exits 0. */
+export declare function cmdPostCompact(hippoRoot: string, options: PostCompactOptions): string | null;
+//# sourceMappingURL=compact.d.ts.map

package/dist/capture/compact.js

@@ -0,0 +1,354 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import { isInitialized } from '../store/open.js';
+import { saveActiveTaskSnapshot, loadActiveTaskSnapshot } from '../store/sessions.js';
+import { PRE_COMPACT_INSTRUCTION, compactionOrigin, parsePostCompactPayload, postCompactLine, recordCompactionStart, recordSnapshotSaved, saveCompaction, replayCompactionsAt, COMPACTION_DB_WAIT_MS, } from '../compaction-record.js';
+import { resolveTenantId } from '../tenant.js';
+import { defaultPreCompactLogPath } from '../hooks/shared.js';
+import { maskEmails, redactSecretsStrict } from '../secret-detect.js';
+import { isObjectLike, isStringValue, readClaudeCodePreCompact } from '../capture-contract.js';
+import { errorMessage } from '../log.js';
+import { PRE_COMPACT_TAIL_BYTES, readTranscriptTail, truncateCodePointSafe } from '../transcript-tail.js';
+import { humanUserText, summariseTranscript, resolveLastSessionTranscript } from './transcript.js';
+// ---------------------------------------------------------------------------
+// `hippo pre-compact` — PreCompact hook producer
+// ---------------------------------------------------------------------------
+export const PRE_COMPACT_TASK_CAP = 200;
+export const PRE_COMPACT_SUMMARY_CAP = 2000;
+export const PRE_COMPACT_NEXT_STEP_CAP = 500;
+/**
+ * Cap from the RECENT end: summariseTranscript emits user turns oldest-to-
+ * newest with assistant responses after them, so a head-first cap keeps
+ * stale context and drops exactly the newest working state this feature
+ * exists to preserve. Keep the LAST maxChars instead, aligned forward to a
+ * nearby line start, with a trim marker (codex round 3).
+ */
+export function truncateKeepNewest(text, maxChars) {
+    if (text.length <= maxChars)
+        return text;
+    let start = text.length - maxChars;
+    const code = text.charCodeAt(start);
+    if (code >= 0xdc00 && code <= 0xdfff)
+        start += 1; // never start on a low surrogate
+    const nl = text.indexOf('\n', start);
+    if (nl !== -1 && nl + 1 < text.length && nl - start < 200)
+        start = nl + 1;
+    return '[...earlier turns trimmed]\n' + text.slice(start);
+}
+/** Most recent plain-text user message in a JSONL tail. Claude Code transcript shape only (PreCompact is claude-code-only). */
+function lastPlainUserMessage(jsonl) {
+    const lines = jsonl.split('\n').filter((l) => l.trim());
+    for (let i = lines.length - 1; i >= 0; i--) {
+        let entry;
+        try {
+            entry = JSON.parse(lines[i]);
+        }
+        catch {
+            continue; // the tail read can start mid-line; skip the torn fragment
+        }
+        if (!isObjectLike(entry))
+            continue;
+        if (!('type' in entry) || entry.type !== 'user')
+            continue;
+        // Meta/sidechain lines carry type:'user' but are not the human: after a
+        // FIRST compaction the transcript holds the compact summary as an isMeta
+        // user line, and sub-agent turns are isSidechain — deriving "task" from
+        // either yields junk on every later compaction.
+        if (('isMeta' in entry && entry.isMeta === true) || ('isSidechain' in entry && entry.isSidechain === true))
+            continue;
+        const message = 'message' in entry && isObjectLike(entry.message) ? entry.message : undefined;
+        if (!message)
+            continue;
+        const text = humanUserText(entry, message);
+        if (text)
+            return text;
+    }
+    return '';
+}
+/** Last assistant text block in a JSONL tail (skips thinking + tool_use, same as summariseTranscript). */
+function lastAssistantTextBlock(jsonl) {
+    const lines = jsonl.split('\n').filter((l) => l.trim());
+    for (let i = lines.length - 1; i >= 0; i--) {
+        let entry;
+        try {
+            entry = JSON.parse(lines[i]);
+        }
+        catch {
+            continue; // the tail read can start mid-line; skip the torn fragment
+        }
+        if (!isObjectLike(entry))
+            continue;
+        if (!('type' in entry) || entry.type !== 'assistant')
+            continue;
+        // Same meta/sidechain guard as lastPlainUserMessage: sub-agent turns
+        // (isSidechain) are not this session's next step.
+        if (('isMeta' in entry && entry.isMeta === true) || ('isSidechain' in entry && entry.isSidechain === true))
+            continue;
+        const message = 'message' in entry && isObjectLike(entry.message) ? entry.message : undefined;
+        if (!message)
+            continue;
+        const content = 'content' in message ? message.content : undefined;
+        if (!Array.isArray(content))
+            continue;
+        for (let j = content.length - 1; j >= 0; j--) {
+            const block = content[j];
+            if (isObjectLike(block)) {
+                const blockText = 'type' in block && block.type === 'text' && 'text' in block ? block.text : undefined;
+                if (isStringValue(blockText) && blockText.trim()) {
+                    return blockText.trim();
+                }
+            }
+        }
+    }
+    return '';
+}
+// 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.
+ */
+export function sanitizeLogMessage(message) {
+    // eslint-disable-next-line no-control-regex
+    return message.replace(/[\x00-\x1f]/g, '');
+}
+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
+        }
+        fs.appendFileSync(logFile, `[hippo] ${new Date().toISOString()} ${sanitizeLogMessage(message)}\n`, 'utf8');
+    }
+    catch {
+        // Diagnostic-only; a log write failure must never affect the exit-0 contract.
+    }
+}
+/** True iff `filePath` exists and is readable — checks both in one call. */
+function isReadableFile(filePath) {
+    try {
+        fs.accessSync(filePath, fs.constants.R_OK);
+        return true;
+    }
+    catch {
+        return false; // missing and unreadable both mean "no file" to the caller
+    }
+}
+/** PreCompact stdout is the summariser's instructions; sent before the snapshot work because a locked store can run the hook past its 30 s limit, and via writeSync because process.exit drops buffered pipe output. */
+function printPreCompactInstruction(logFile) {
+    try {
+        fs.writeSync(1, `${PRE_COMPACT_INSTRUCTION}\n`);
+    }
+    catch (err) {
+        appendPreCompactLog(logFile, `instruction not printed: ${errorMessage(err)}`);
+    }
+}
+/** A session's task, summary and next step from its transcript tail, secrets scrubbed and capped, '' where none; null with a logged reason when nothing is derivable. */
+export function transcriptWorkingState(transcriptPath, log) {
+    let tail = '';
+    let rawTask = '';
+    let rawNextStep = '';
+    try {
+        // Compaction fires when a big tool_result lands (CX7), so the last human and assistant turns can sit
+        // megabytes back: grow the window a bounded number of times until both turns are in it.
+        const size = fs.statSync(transcriptPath).size;
+        for (const cap of [PRE_COMPACT_TAIL_BYTES, PRE_COMPACT_TAIL_BYTES * 4, PRE_COMPACT_TAIL_BYTES * 16]) {
+            if (cap > PRE_COMPACT_TAIL_BYTES)
+                log(`tail window grown to ${cap} bytes (last ${rawTask ? 'assistant' : 'user'} turn is further back)`);
+            tail = readTranscriptTail(transcriptPath, cap);
+            rawTask = lastPlainUserMessage(tail);
+            rawNextStep = lastAssistantTextBlock(tail);
+            if ((rawTask && rawNextStep) || size <= cap)
+                break;
+        }
+    }
+    catch (err) {
+        log(`skip: could not read transcript tail: ${errorMessage(err)}`);
+        return null;
+    }
+    const rawSummary = summariseTranscript(tail);
+    if (!rawTask.trim() && !rawSummary.trim() && !rawNextStep.trim()) {
+        log('skip: empty summary');
+        return null;
+    }
+    // X9: these fields skip the capture content gate and reach a prompt, so the strict scrub runs. The caps protect the
+    // re-injection token budget and never split a surrogate pair (X2); `hippo snapshot save` stays uncapped.
+    const task = maskEmails(redactSecretsStrict(rawTask));
+    const summary = maskEmails(redactSecretsStrict(rawSummary));
+    const nextStep = maskEmails(redactSecretsStrict(rawNextStep));
+    return {
+        task: task.trim() ? truncateCodePointSafe(task, PRE_COMPACT_TASK_CAP) : '',
+        summary: summary.trim() ? truncateKeepNewest(summary, PRE_COMPACT_SUMMARY_CAP) : '',
+        next_step: nextStep.trim() ? truncateCodePointSafe(nextStep, PRE_COMPACT_NEXT_STEP_CAP) : '',
+    };
+}
+/** 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, stdinText, stdinTimedOut, logFile) {
+    // X3: 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).
+    if (!isInitialized(hippoRoot)) {
+        appendPreCompactLog(logFile, 'skip: store not initialized');
+        return;
+    }
+    const receipt = readClaudeCodePreCompact(stdinText, stdinTimedOut);
+    if (receipt.status !== 'received') {
+        appendPreCompactLog(logFile, `skip: ${receipt.reason}`);
+        return;
+    }
+    const { sessionId, transcriptPath: payloadTranscriptPath, cwd: payloadCwd, trigger: payloadTrigger } = receipt.input;
+    // The record is the "something saved before every compaction", so it lands even when no snapshot is derivable below.
+    let recordId = null;
+    if (sessionId !== null && sessionId !== '') {
+        recordId = recordCompactionStart(hippoRoot, { sessionId, trigger: payloadTrigger, cwd: payloadCwd, transcriptPath: payloadTranscriptPath }, (message) => appendPreCompactLog(logFile, message));
+        printPreCompactInstruction(logFile);
+    }
+    const transcriptPath = resolvePreCompactTranscript(payloadTranscriptPath, stdinText, logFile);
+    if (!transcriptPath)
+        return;
+    // Nothing derivable skips the write, so a user-authored active snapshot is never clobbered with junk.
+    const derived = transcriptWorkingState(transcriptPath, (message) => appendPreCompactLog(logFile, message));
+    if (!derived)
+        return;
+    saveDerivedSnapshot(hippoRoot, logFile, sessionId, recordId, derived);
+}
+/** The transcript to snapshot, or null after logging why there is none. */
+function resolvePreCompactTranscript(payloadTranscriptPath, stdinText, logFile) {
+    // A payload transcript_path is EXCLUSIVE: never fall back to
+    // newest-transcript auto-discovery when it's missing/unreadable. That
+    // fallback would snapshot a DIFFERENT session's transcript under THIS
+    // payload's session_id — cross-session contamination with wrong linkage
+    // (verify-stage E2E finding, 2026-08-03). Auto-discovery only applies
+    // on a true manual invocation (no payload at all).
+    let transcriptPath;
+    if (payloadTranscriptPath !== null) {
+        if (isReadableFile(payloadTranscriptPath)) {
+            transcriptPath = payloadTranscriptPath;
+        }
+        else {
+            appendPreCompactLog(logFile, `skip: payload transcript_path unreadable: ${payloadTranscriptPath}`);
+            return null;
+        }
+    }
+    else {
+        transcriptPath = resolveLastSessionTranscript(undefined, stdinText, { mayScan: true });
+    }
+    if (!transcriptPath) {
+        appendPreCompactLog(logFile, 'skip: no transcript resolved');
+        return null;
+    }
+    return transcriptPath;
+}
+function saveDerivedSnapshot(hippoRoot, logFile, sessionId, recordId, derived) {
+    const tenantId = resolveTenantId({});
+    // Per-field merge (X1): a tool-heavy tail whose only user turns are
+    // tool_result arrays derives an empty task even though the summary is
+    // non-empty. Loading the existing snapshot first lets each field fall
+    // back independently instead of the whole write clobbering a
+    // user-authored field with blank text.
+    let existing = null;
+    try {
+        existing = loadActiveTaskSnapshot(hippoRoot, tenantId);
+    }
+    catch {
+        // No existing snapshot to merge against — proceed with derived-only.
+    }
+    // CX6 (codex round 2): field fallback must never move content across
+    // sessions — session A's task carried into a snapshot saved under session
+    // B's id would pass compact-resume's session gate wearing the wrong
+    // badge. Fall back only when the existing snapshot has no session, this
+    // payload has none, or they match.
+    const fallback = existing !== null &&
+        (existing.session_id === null || sessionId === null || existing.session_id === sessionId)
+        ? existing
+        : null;
+    // Carried-over fields are not re-capped, as `hippo snapshot save` stays uncapped; saveActiveTaskSnapshot scrubs every field.
+    const task = derived.task || (fallback?.task ?? '');
+    const summary = derived.summary || (fallback?.summary ?? '');
+    const nextStep = derived.next_step || (fallback?.next_step ?? '');
+    // All-empty fields (cross-session tail with nothing derivable) skip the
+    // write so a foreign session's junk never displaces the owning snapshot.
+    if (!task && !summary && !nextStep) {
+        appendPreCompactLog(logFile, 'skip: no snapshot content for this session (nothing derivable; fallback blocked or empty)');
+    }
+    else {
+        try {
+            saveActiveTaskSnapshot(hippoRoot, tenantId, {
+                task,
+                summary,
+                next_step: nextStep,
+                source: 'pre-compact',
+                session_id: sessionId,
+            });
+            appendPreCompactLog(logFile, 'snapshot saved');
+            if (recordId !== null)
+                recordSnapshotSaved(hippoRoot, recordId, (message) => appendPreCompactLog(logFile, message));
+        }
+        catch (err) {
+            appendPreCompactLog(logFile, `snapshot save failed: ${errorMessage(err)}`);
+        }
+    }
+}
+/**
+ * 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.
+ */
+export async function cmdPreCompact(hippoRoot, options) {
+    const logFile = options.logFile ?? defaultPreCompactLogPath();
+    try {
+        runPreCompact(hippoRoot, options.stdinText, options.stdinTimedOut ?? false, logFile);
+    }
+    catch (err) {
+        appendPreCompactLog(logFile, `pre-compact failed: ${errorMessage(err)}`);
+    }
+    process.exit(0);
+}
+/** A PostCompact hook has 10 s in all; replay stops starting new records after this. */
+const POST_COMPACT_REPLAY_BUDGET_MS = 6000;
+/** PostCompact entry point: saves the summary and its items, replays earlier leftovers, returns the one line to show. Never throws, so the hook exits 0. */
+export function cmdPostCompact(hippoRoot, options) {
+    const logFile = options.logFile ?? defaultPreCompactLogPath();
+    const log = (message) => appendPreCompactLog(logFile, `post-compact: ${message}`);
+    const deadline = Date.now() + POST_COMPACT_REPLAY_BUDGET_MS;
+    try {
+        if (!isInitialized(hippoRoot)) {
+            log('skip: no hippo store');
+            return null;
+        }
+        const payload = parsePostCompactPayload(options.stdinText);
+        let line = null;
+        let storeBusy = false;
+        if (payload === null) {
+            log('skip: no PostCompact payload naming a session');
+        }
+        else {
+            const saved = saveCompaction(hippoRoot, payload, log);
+            line = postCompactLine(saved);
+            storeBusy = saved.deferred;
+            if (!storeBusy && payload.transcriptPath !== null && options.afterSave) {
+                try {
+                    options.afterSave(payload.transcriptPath, compactionOrigin(hippoRoot, payload.cwd), log);
+                }
+                catch (err) {
+                    log(`agent memory import failed: ${errorMessage(err)}`);
+                }
+            }
+        }
+        if (!storeBusy)
+            replayCompactionsAt(hippoRoot, log, { busyWaitMs: COMPACTION_DB_WAIT_MS, deadline });
+        return line;
+    }
+    catch (err) {
+        log(`failed: ${errorMessage(err)}`);
+        return null;
+    }
+}
+//# sourceMappingURL=compact.js.map