hippo-memory 1.63.1 → 1.64.0

package/dist/capture/failure-reading.d.ts

@@ -0,0 +1,44 @@
+import type { JsonValue } from '../json.js';
+/** Why a failure was not stored, or `stored`. */
+export type CaptureErrorOutcome = 'stored' | 'duplicate' | 'skipped-interrupt' | 'skipped-routine' | 'skipped-invalid';
+/** Which routine check skipped a failure; the log keeps it so declines can be told apart from empty searches. */
+export type RoutineRule = 'declined' | 'os-permission' | 'no-match' | 'search-tool' | 'quiet-exit';
+/** What {@link lessonFromFailure} read from a payload; `detail` is the finer failure-log key (untruncated, command head). */
+export type FailureReading = {
+    text: string;
+    detail: string;
+} | {
+    skip: 'skipped-routine';
+    rule: RoutineRule;
+    text: string;
+    detail: string;
+} | {
+    skip: 'skipped-interrupt' | 'skipped-invalid';
+    text: null;
+    detail: null;
+};
+/** The longest lesson text a reading gives, so a check of a sent one imports it instead of copying it. */
+export declare const FAILURE_TEXT_MAX_CHARS = 200;
+/** A non-blank string field of the payload, or null. */
+export declare function payloadString(payload: JsonValue, key: 'session_id' | 'tool_name'): string | null;
+/** Normalised form used to spot repeats. The failure log keeps only its hash, so changing it breaks repeat counts. */
+export declare function failureSignature(text: string): string;
+/** The hash the failure log stores for a lesson text or a detail; one function so every writer counts repeats alike. */
+export declare function failureHash(text: string): string;
+/** The memory text for a failure payload, or why it is not stored; a routine skip keeps its text for the log. `scrub` runs before the cap, as a mask can be longer than what it hides. Pure. */
+export declare function lessonFromFailure(payload: JsonValue, scrub?: (text: string) => string): FailureReading;
+/** A failure as it may leave the machine: the capped lesson text and the detail's hash, never the untruncated detail. */
+export interface FailureReport {
+    /** The payload's tool name; null when it named none. */
+    tool: string | null;
+    /** Scrubbed for sharing, then cut to at most 200 chars; null when the payload had no readable error. */
+    text: string | null;
+    /** Why it is not stored; null for a lesson. */
+    skip: Exclude<CaptureErrorOutcome, 'stored' | 'duplicate'> | null;
+    rule: RoutineRule | null;
+    /** What the local failure log stores as `detail_hash` for the same payload. */
+    detail_hash: string | null;
+}
+/** {@link lessonFromFailure} plus the detail's hash, for a writer whose store is elsewhere. Pure. */
+export declare function failureReport(payload: JsonValue): FailureReport;
+//# sourceMappingURL=failure-reading.d.ts.map

package/dist/capture/failure-reading.js

@@ -0,0 +1,78 @@
+// What a PostToolUseFailure payload says, read with no store, so a hook with no store sends the same reading the local log keeps.
+import { redactSecretsStrict } from '../secret-detect.js';
+import { scrubForSharing } from '../share-scrub.js';
+import { blockHash } from '../token-ledger.js';
+import { truncateCodePointSafe } from '../transcript-tail.js';
+/** The longest lesson text a reading gives, so a check of a sent one imports it instead of copying it. */
+export const FAILURE_TEXT_MAX_CHARS = 200;
+/** The user, a permission prompt or a hook said no: routine, not a lesson. */
+const DECLINED = /user (?:doesn't|does not) want|denied by (?:the )?user|user (?:rejected|declined|denied)|permission to use|was blocked by (?:a )?hook/i;
+/** The OS or a remote host refused access (EACCES, SSH publickey): routine too, but nobody declined anything. */
+const OS_PERMISSION = /permission denied/i;
+/** Leading `cd` or `pushd` steps say where a command ran, not what it ran. */
+const LEADING_CD = /^\s*(?:(?:cd|pushd)\b[^;&|]*(?:&&|\|\||;)\s*)+/;
+const NO_MATCH = /\bno (?:matches|files|results) found\b/i;
+/** Shell commands whose exit code 1 means "nothing found" or "differs", not an error. */
+const QUIET_EXIT_1 = /^\s*(?:grep|rg|egrep|fgrep|find|test|\[|diff|cmp|git diff|git grep)\b/;
+function isString(v) {
+    return v !== undefined && v !== null && v.constructor === String;
+}
+function isObject(v) {
+    return v !== undefined && v !== null && !Array.isArray(v) && v.constructor === Object;
+}
+/** A non-blank string field of the payload, or null. */
+export function payloadString(payload, key) {
+    if (!isObject(payload))
+        return null;
+    const value = payload[key];
+    return isString(value) && value.trim() !== '' ? value : null;
+}
+/** Normalised form used to spot repeats. The failure log keeps only its hash, so changing it breaks repeat counts. */
+export function failureSignature(text) {
+    return text.toLowerCase().replace(/[0-9a-f]{7,}/g, '#').replace(/\d+/g, '#').replace(/\s+/g, ' ').trim();
+}
+/** The hash the failure log stores for a lesson text or a detail; one function so every writer counts repeats alike. */
+export function failureHash(text) {
+    return blockHash(failureSignature(text));
+}
+/** The memory text for a failure payload, or why it is not stored; a routine skip keeps its text for the log. `scrub` runs before the cap, as a mask can be longer than what it hides. Pure. */
+export function lessonFromFailure(payload, scrub = (text) => text) {
+    if (!isObject(payload))
+        return { skip: 'skipped-invalid', text: null, detail: null };
+    // SAFETY: isObject narrowed payload to a plain JSON object; the fields read are all optional.
+    const p = payload;
+    if (p.is_interrupt === true)
+        return { skip: 'skipped-interrupt', text: null, detail: null };
+    if (!isString(p.error) || p.error.trim().length < 12)
+        return { skip: 'skipped-invalid', text: null, detail: null };
+    const tool = isString(p.tool_name) ? p.tool_name : 'tool';
+    const error = redactSecretsStrict(p.error.replace(/\s+/g, ' ').trim());
+    const text = truncateCodePointSafe(scrub(`${tool}: ${error}`), FAILURE_TEXT_MAX_CHARS);
+    const command = isObject(p.tool_input) && isString(p.tool_input['command']) ? p.tool_input['command'].replace(LEADING_CD, '') : '';
+    const head = command.trim().split(/\s+/).slice(0, 2).join(' ');
+    const detail = `${tool}${head ? ` ${head}` : ''}: ${error}`;
+    const routine = (rule) => ({ skip: 'skipped-routine', rule, text, detail });
+    if (DECLINED.test(error))
+        return routine('declined');
+    if (OS_PERMISSION.test(error))
+        return routine('os-permission');
+    if (NO_MATCH.test(error))
+        return routine('no-match');
+    if (tool === 'Grep' || tool === 'Glob')
+        return routine('search-tool');
+    if (tool === 'Bash' && QUIET_EXIT_1.test(command) && /exit code 1\b/i.test(error))
+        return routine('quiet-exit');
+    return { text, detail };
+}
+/** {@link lessonFromFailure} plus the detail's hash, for a writer whose store is elsewhere. Pure. */
+export function failureReport(payload) {
+    const reading = lessonFromFailure(payload, scrubForSharing);
+    return {
+        tool: payloadString(payload, 'tool_name'),
+        text: reading.text,
+        skip: 'skip' in reading ? reading.skip : null,
+        rule: 'rule' in reading ? reading.rule : null,
+        detail_hash: reading.detail === null ? null : failureHash(reading.detail),
+    };
+}
+//# sourceMappingURL=failure-reading.js.map

package/dist/capture/pre-compact-caller.d.ts

@@ -0,0 +1,16 @@
+import type { Context } from '../api/types.js';
+import type { CallerProject } from '../prompt-hook.js';
+import { type WorkingState } from './working-state.js';
+export interface CallerPreCompactRequest {
+    readonly sessionId: string;
+    readonly project: CallerProject;
+    readonly trigger: string | null;
+    /** What the caller read off its transcript; null when nothing was derivable. */
+    readonly workingState: WorkingState | null;
+}
+export interface CallerHookOutput {
+    /** What the hook prints; '' prints nothing. */
+    readonly stdout: string;
+}
+export declare function preCompactForCaller(ctx: Context, req: CallerPreCompactRequest): CallerHookOutput;
+//# sourceMappingURL=pre-compact-caller.d.ts.map

package/dist/capture/pre-compact-caller.js

@@ -0,0 +1,39 @@
+import { markSnapshotSaved, PRE_COMPACT_INSTRUCTION, startCompaction } from '../compaction-record.js';
+import { errorMessage, log } from '../log.js';
+import { loadActiveTaskSnapshot, saveActiveTaskSnapshot } from '../store/sessions.js';
+import { assertTrigger, bindCaller, callerInHoldout, checkedWorkingState, withCallerDb } from './caller-session.js';
+import { mergeWorkingState } from './working-state.js';
+/** A failed step is logged and the instruction still goes out, as the local hook prints it before any store work. */
+function logged(what, fn) {
+    try {
+        return fn();
+    }
+    catch (err) {
+        log.warn(`pre-compact: ${what}: ${errorMessage(err)}`);
+        return null;
+    }
+}
+export function preCompactForCaller(ctx, req) {
+    assertTrigger(req.trigger);
+    const state = checkedWorkingState(req.workingState);
+    const key = bindCaller(ctx, req.sessionId, req.project);
+    if (callerInHoldout(ctx, req.sessionId))
+        return { stdout: '' };
+    const start = { sessionId: req.sessionId, originProject: req.project.name, trigger: req.trigger, cwd: null, transcriptPath: null };
+    const recordId = logged('compaction record not started', () => withCallerDb(ctx, (db) => startCompaction(db, ctx.tenantId, start)));
+    if (state !== null && saveOwnerSnapshot(ctx, req.sessionId, key, state) && recordId !== null) {
+        // Marked under ctx.tenantId, which the environment's tenant may not be.
+        logged('compaction record not marked with its snapshot', () => withCallerDb(ctx, (db) => markSnapshotSaved(db, ctx.tenantId, recordId)));
+    }
+    return { stdout: PRE_COMPACT_INSTRUCTION };
+}
+/** True when the owner's snapshot was saved. */
+function saveOwnerSnapshot(ctx, sessionId, key, state) {
+    const existing = logged('snapshot not loaded', () => loadActiveTaskSnapshot(ctx.hippoRoot, ctx.tenantId, key));
+    const merged = mergeWorkingState(state, existing, sessionId);
+    if (merged === null)
+        return false;
+    const snapshot = { ...merged, source: 'pre-compact', session_id: sessionId };
+    return logged('snapshot not saved', () => saveActiveTaskSnapshot(ctx.hippoRoot, ctx.tenantId, snapshot, key)) !== null;
+}
+//# sourceMappingURL=pre-compact-caller.js.map

package/dist/capture/session-end-caller.d.ts

@@ -0,0 +1,21 @@
+import type { Context } from '../api/types.js';
+import type { HandoffEvidence } from '../handoff.js';
+import type { CallerProject } from '../prompt-hook.js';
+import type { WorkingState } from './working-state.js';
+export type CallerEvidence = Pick<HandoffEvidence, 'gitRef' | 'dirtyTree' | 'testStatus'>;
+export interface CallerSessionEndRequest {
+    readonly sessionId: string;
+    readonly project: CallerProject;
+    /** Read off the transcript at session end; the handoff's source when the owner has no snapshot for the session. */
+    readonly workingState: WorkingState | null;
+    /** The git state the caller saw when the session ended. */
+    readonly evidence: CallerEvidence | null;
+}
+export interface CallerSessionEndResult {
+    /** False when an earlier handoff already covers the session, as on a retry. */
+    readonly handoffWritten: boolean;
+    readonly snapshotsClosed: number;
+}
+/** Call on a session's final end only, since it closes the snapshot. A failed close throws so the sender retries, and the retry writes no second handoff. */
+export declare function sessionEndHandoffForCaller(ctx: Context, req: CallerSessionEndRequest): CallerSessionEndResult;
+//# sourceMappingURL=session-end-caller.d.ts.map

package/dist/capture/session-end-caller.js

@@ -0,0 +1,30 @@
+// SessionEnd for a caller on another machine: the owner's handoff, then the owner's snapshot for the session closed, both under its tenant and project.
+import { BadRequestError } from '../api-errors.js';
+import { writeSessionEndHandoff } from '../store/handoffs.js';
+import { closeTaskSnapshotsForSession } from '../store/sessions.js';
+import { bindCaller, checkedWorkingState } from './caller-session.js';
+const TEST_STATUSES = new Set(['pass', 'fail', 'unknown']);
+/** Only the three fields a caller may send: `derivedFrom` is the handoff writer's to set. */
+function checkedEvidence(evidence) {
+    if (evidence === null)
+        return null;
+    const { gitRef = null, dirtyTree = null, testStatus = null } = evidence;
+    // `git rev-parse HEAD` gives 40 hex, or 64 in a SHA-256 repository.
+    if (gitRef !== null && !/^(?:[0-9a-f]{40}|[0-9a-f]{64})$/.test(gitRef))
+        throw new BadRequestError('evidence gitRef: 40 or 64 lowercase hex characters or null');
+    if (dirtyTree !== null && dirtyTree !== true && dirtyTree !== false)
+        throw new BadRequestError('evidence dirtyTree: true, false or null');
+    if (testStatus !== null && !TEST_STATUSES.has(testStatus))
+        throw new BadRequestError('evidence testStatus: pass, fail, unknown or null');
+    return { gitRef, dirtyTree, testStatus };
+}
+/** Call on a session's final end only, since it closes the snapshot. A failed close throws so the sender retries, and the retry writes no second handoff. */
+export function sessionEndHandoffForCaller(ctx, req) {
+    const state = checkedWorkingState(req.workingState);
+    const evidence = checkedEvidence(req.evidence);
+    const key = bindCaller(ctx, req.sessionId, req.project);
+    const handoff = writeSessionEndHandoff(ctx.hippoRoot, ctx.tenantId, req.sessionId, evidence, state, key);
+    const snapshotsClosed = closeTaskSnapshotsForSession(ctx.hippoRoot, ctx.tenantId, req.sessionId, 'session-ended', key);
+    return { handoffWritten: handoff !== null, snapshotsClosed };
+}
+//# sourceMappingURL=session-end-caller.js.map

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

@@ -0,0 +1,14 @@
+import type { Context } from '../api/types.js';
+import { type CallerProject } from '../prompt-hook.js';
+import { type CaptureTally } from './command.js';
+export interface SessionCaptureRequest {
+    readonly sessionId: string;
+    readonly project: CallerProject;
+    /** The session's turns, as sessionTail returns them; scrubbed again here, since the caller's scrub is not trusted. */
+    readonly texts: readonly string[];
+}
+export type SessionCaptureResult = Readonly<CaptureTally>;
+/** Captures the session's statements into `ctx`'s tenant under the caller's project, skipping each text a row the caller can see already holds.
+ *  Synchronous from the dedup read to the last write, so no other write lands between them. No console output and no process.exit. */
+export declare function captureSessionTexts(ctx: Context, req: SessionCaptureRequest): SessionCaptureResult;
+//# sourceMappingURL=session-texts.d.ts.map

package/dist/capture/session-texts.js

@@ -0,0 +1,42 @@
+// `hippo capture --last-session` for a caller whose transcript was read on another machine: its project names the rows, never the store's folder.
+import { BadRequestError } from '../api-errors.js';
+import { assertCallerIds } from '../prompt-hook.js';
+import { assertCallerProject, projectNames } from '../project-identity.js';
+import { longestWord, storedTextKeys } from '../same-text.js';
+import { scrubForSharing } from '../share-scrub.js';
+import { loadTextsHoldingWords } from '../store/candidates.js';
+import { captureExtractedItems } from './command.js';
+import { extractFromTexts } from './extract.js';
+const MAX_TEXTS = 30;
+const MAX_TEXT_BYTES = 32 * 1024;
+const MAX_TOTAL_BYTES = 256 * 1024;
+const MAX_ITEMS = 50;
+function assertSessionCapture(req) {
+    assertCallerIds(req.sessionId, req.project);
+    if (req.sessionId.trim() === '')
+        throw new BadRequestError('session id: required');
+    // A '' project would read every project's rows as its own and write user-global rows; a rewritten one would split a project.
+    assertCallerProject(req.project);
+    if (req.texts.length > MAX_TEXTS)
+        throw new BadRequestError(`texts: at most ${MAX_TEXTS}`);
+    const sizes = req.texts.map((t) => Buffer.byteLength(t, 'utf8'));
+    if (sizes.some((n) => n > MAX_TEXT_BYTES))
+        throw new BadRequestError(`each text: at most ${MAX_TEXT_BYTES} bytes`);
+    if (sizes.reduce((a, b) => a + b, 0) > MAX_TOTAL_BYTES)
+        throw new BadRequestError(`texts: at most ${MAX_TOTAL_BYTES} bytes in all`);
+}
+/** Captures the session's statements into `ctx`'s tenant under the caller's project, skipping each text a row the caller can see already holds.
+ *  Synchronous from the dedup read to the last write, so no other write lands between them. No console output and no process.exit. */
+export function captureSessionTexts(ctx, req) {
+    assertSessionCapture(req);
+    const extracted = extractFromTexts(req.texts.map(scrubForSharing));
+    // The newest items win, since the end of a session states where it landed.
+    const items = extracted.slice(-MAX_ITEMS);
+    if (items.length === 0)
+        return { captured: 0, skipped: 0, rejected: 0 };
+    // The project filter is classifyOriginProject's in SQL: the caller's rows and user-global rows block a copy, other projects' rows do not.
+    const held = loadTextsHoldingWords(ctx.hippoRoot, ctx.tenantId, items.map((i) => longestWord(i.content)), projectNames(req.project));
+    const tally = captureExtractedItems(ctx.hippoRoot, { dryRun: false, tenantId: ctx.tenantId, originProject: req.project, sessionId: req.sessionId, actor: ctx.actor.subject, lean: true }, items, storedTextKeys(held));
+    return { ...tally, skipped: tally.skipped + extracted.length - items.length };
+}
+//# sourceMappingURL=session-texts.js.map

package/dist/capture/transcript.d.ts

@@ -22,6 +22,11 @@ export interface TranscriptRecord extends TranscriptLineFlags {
 }
 export declare function collectSessionTurns(jsonl: string, visit?: (record: TranscriptRecord) => void): SessionTurn[];
 export declare function summariseTranscript(jsonl: string): string;
+/** The last 20 user turns and last 10 replies: session-end is about what was decided near the end, not at the start. */
+export declare function sessionTail(turns: readonly SessionTurn[]): {
+    users: string[];
+    assistants: string[];
+};
 export declare function summariseSessionTurns(turns: readonly SessionTurn[]): string;
 /**
  * Resolve a transcript path for `--last-session`.
@@ -29,7 +34,7 @@ export declare function summariseSessionTurns(turns: readonly SessionTurn[]): st
  * Priority, where the first source present is the only one tried:
  *   1. Explicit `transcriptPath` option (from `--transcript <path>`)
  *   2. Stdin JSON payload (Claude Code / OpenCode SessionEnd hook shape)
- *   3. Most recent `.jsonl` under `~/.claude/projects/<any>/`, only when the caller passes `mayScan` (only the caller knows it is not a hook) and there is no path and no stdin text, because this scan spans every project on the box
+ *   3. Most recent `.jsonl` under `<claude config dir>/projects/<any>/` (`~/.claude` unless CLAUDE_CONFIG_DIR is set), only when the caller passes `mayScan` (only the caller knows it is not a hook) and there is no path and no stdin text, because this scan spans every project on the box
  *
  * Returns null when nothing resolves, a named transcript or payload whose file is missing included. Never throws.
  */

package/dist/capture/transcript.js

@@ -1,12 +1,13 @@
-import { envHomeDir } from '../env.js';
+import { envHomeDir, processEnv } from '../env.js';
+import { claudeConfigDir } from '../hooks/shared.js';
 import * as fs from 'fs';
 import * as path from 'path';
 import { isObjectLike, isStringValue } from '../capture-contract.js';
 /**
  * Build a compact text summary from a Claude Code / OpenCode JSONL transcript.
  * Keeps plain user messages and the final chunk of assistant text, drops
- * thinking blocks, tool_use, and tool_result noise. Output is fed to the
- * existing `extractFromText` pipeline.
+ * thinking blocks, tool_use, and tool_result noise. Capture reads the same
+ * turns through `sessionTail`, one text per turn.
  *
  * Exported for tests.
  */
@@ -114,23 +115,26 @@ export function collectSessionTurns(jsonl, visit) {
 export function summariseTranscript(jsonl) {
     return summariseSessionTurns(collectSessionTurns(jsonl));
 }
+/** The last 20 user turns and last 10 replies: session-end is about what was decided near the end, not at the start. */
+export function sessionTail(turns) {
+    return {
+        users: turns.filter((t) => t.role === 'user').map((t) => t.text).slice(-20),
+        assistants: turns.filter((t) => t.role === 'assistant').map((t) => t.text).slice(-10),
+    };
+}
 export function summariseSessionTurns(turns) {
-    const userMessages = turns.filter((t) => t.role === 'user').map((t) => t.text);
-    const assistantTexts = turns.filter((t) => t.role === 'assistant').map((t) => t.text);
-    if (userMessages.length === 0 && assistantTexts.length === 0)
+    const { users: tailUsers, assistants: tailAssistants } = sessionTail(turns);
+    if (tailUsers.length === 0 && tailAssistants.length === 0)
         return '';
-    // Keep the tail: last ~20 user turns and last ~10 assistant replies.
-    // Session-end is about what was decided near the end, not at the start.
-    const tailUsers = userMessages.slice(-20);
-    const tailAssistants = assistantTexts.slice(-10);
     return [
         '# Session Summary',
         '',
         '## User Messages',
-        ...tailUsers.map((m) => `- ${m.replace(/\s+/g, ' ').slice(0, 500)}`),
+        ...tailUsers.map((m) => `- ${m}`),
         '',
         '## Assistant Responses',
-        ...tailAssistants.map((t) => t.slice(0, 2000)),
+        // A blank line between replies keeps capture from joining two of them; each user turn opens its own list item.
+        tailAssistants.join('\n\n'),
     ].join('\n');
 }
 /**
@@ -139,7 +143,7 @@ export function summariseSessionTurns(turns) {
  * Priority, where the first source present is the only one tried:
  *   1. Explicit `transcriptPath` option (from `--transcript <path>`)
  *   2. Stdin JSON payload (Claude Code / OpenCode SessionEnd hook shape)
- *   3. Most recent `.jsonl` under `~/.claude/projects/<any>/`, only when the caller passes `mayScan` (only the caller knows it is not a hook) and there is no path and no stdin text, because this scan spans every project on the box
+ *   3. Most recent `.jsonl` under `<claude config dir>/projects/<any>/` (`~/.claude` unless CLAUDE_CONFIG_DIR is set), only when the caller passes `mayScan` (only the caller knows it is not a hook) and there is no path and no stdin text, because this scan spans every project on the box
  *
  * Returns null when nothing resolves, a named transcript or payload whose file is missing included. Never throws.
  */
@@ -162,10 +166,10 @@ export function resolveLastSessionTranscript(explicit, stdinText, opts) {
     }
     if (!opts.mayScan)
         return null;
-    const home = envHomeDir();
-    if (!home)
+    // With no home set, os.homedir() would send the scan into the real profile's transcripts.
+    if (!processEnv().CLAUDE_CONFIG_DIR && !envHomeDir())
         return null;
-    const projectsDir = path.join(home, '.claude', 'projects');
+    const projectsDir = path.join(claudeConfigDir(), 'projects');
     if (!fs.existsSync(projectsDir))
         return null;
     let newest = null;

package/dist/capture/working-state.d.ts

@@ -0,0 +1,21 @@
+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;
+/** The longest each field of {@link transcriptWorkingState} can be, so a check of a sent working state imports these instead of copying them. */
+export declare const WORKING_STATE_CAPS: {
+    readonly task: 200;
+    readonly summary: number;
+    readonly next_step: 500;
+};
+export type WorkingState = Pick<TaskSnapshot, 'task' | 'summary' | 'next_step'>;
+/** Cuts each field to {@link WORKING_STATE_CAPS}, for after a scrub, as a mask can run longer than what it hides. */
+export declare function fitWorkingState(state: WorkingState): WorkingState;
+/** Each empty field falls back to `existing`'s, since a tool-heavy tail derives no task; null when all are empty, so blanks never replace a snapshot.
+ *  Never across sessions: another session's task saved under this id would pass compact-resume's session check. */
+export declare function mergeWorkingState(derived: WorkingState, existing: TaskSnapshot | null, sessionId: string | null): WorkingState | null;
+/** Keeps the LAST maxChars behind a trim marker, aligned to a nearby line start: the summary runs oldest first, so a head cap would drop the newest working state. */
+export declare function truncateKeepNewest(text: string, maxChars: number): 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;
+//# sourceMappingURL=working-state.d.ts.map

package/dist/capture/working-state.js

@@ -0,0 +1,154 @@
+// A session's working state read from its transcript tail, with no store in the imports, so a hook with no store can derive it.
+import * as fs from 'fs';
+import { maskEmails, redactSecretsStrict } from '../secret-detect.js';
+import { isObjectLike, isStringValue } from '../capture-contract.js';
+import { errorMessage } from '../log.js';
+import { PRE_COMPACT_TAIL_BYTES, readTranscriptTail, truncateCodePointSafe } from '../transcript-tail.js';
+import { humanUserText, summariseTranscript } from './transcript.js';
+export const PRE_COMPACT_TASK_CAP = 200;
+export const PRE_COMPACT_SUMMARY_CAP = 2000;
+export const PRE_COMPACT_NEXT_STEP_CAP = 500;
+const TRIM_MARKER = '[...earlier turns trimmed]\n';
+/** The longest each field of {@link transcriptWorkingState} can be, so a check of a sent working state imports these instead of copying them. */
+export const WORKING_STATE_CAPS = {
+    task: PRE_COMPACT_TASK_CAP,
+    summary: PRE_COMPACT_SUMMARY_CAP + TRIM_MARKER.length,
+    next_step: PRE_COMPACT_NEXT_STEP_CAP,
+};
+/** Cuts each field to {@link WORKING_STATE_CAPS}, for after a scrub, as a mask can run longer than what it hides. */
+export function fitWorkingState(state) {
+    return {
+        task: truncateCodePointSafe(state.task, WORKING_STATE_CAPS.task),
+        // Only past the cap, since re-trimming a summary that fits would drop its head again; the cut keeps the newest turns.
+        summary: state.summary.length > WORKING_STATE_CAPS.summary ? truncateKeepNewest(state.summary, PRE_COMPACT_SUMMARY_CAP) : state.summary,
+        next_step: truncateCodePointSafe(state.next_step, WORKING_STATE_CAPS.next_step),
+    };
+}
+/** Each empty field falls back to `existing`'s, since a tool-heavy tail derives no task; null when all are empty, so blanks never replace a snapshot.
+ *  Never across sessions: another session's task saved under this id would pass compact-resume's session check. */
+export function mergeWorkingState(derived, existing, sessionId) {
+    const fallback = existing !== null && (existing.session_id === null || sessionId === null || existing.session_id === sessionId) ? existing : null;
+    const merged = {
+        task: derived.task || (fallback?.task ?? ''),
+        summary: derived.summary || (fallback?.summary ?? ''),
+        next_step: derived.next_step || (fallback?.next_step ?? ''),
+    };
+    return merged.task || merged.summary || merged.next_step ? merged : null;
+}
+/** Keeps the LAST maxChars behind a trim marker, aligned to a nearby line start: the summary runs oldest first, so a head cap would drop the newest working state. */
+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 TRIM_MARKER + 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;
+        // An isMeta user line holds an earlier compact summary and an isSidechain one is a sub-agent turn; neither is the human's task.
+        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 '';
+}
+/** 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, 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;
+    }
+    // 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; `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) : '',
+    };
+}
+//# sourceMappingURL=working-state.js.map

package/dist/capture-error.d.ts

@@ -1,26 +1,12 @@
+import { type CaptureErrorOutcome } from './capture/failure-reading.js';
 import type { JsonValue } from './json.js';
-/** Why a failure was not stored, or `stored`. */
-export type CaptureErrorOutcome = 'stored' | 'duplicate' | 'skipped-interrupt' | 'skipped-routine' | 'skipped-invalid';
-/** Which routine check skipped a failure; the log keeps it so declines can be told apart from empty searches. */
-export type RoutineRule = 'declined' | 'os-permission' | 'no-match' | 'search-tool' | 'quiet-exit';
-/** What {@link lessonFromFailure} read from a payload; `detail` is the finer failure-log key (untruncated, command head). */
-export type FailureReading = {
-    text: string;
-    detail: string;
-} | {
-    skip: 'skipped-routine';
-    rule: RoutineRule;
-    text: string;
-    detail: string;
-} | {
-    skip: 'skipped-interrupt' | 'skipped-invalid';
-    text: null;
-    detail: null;
-};
-/** Normalised form used to spot repeats. The failure log keeps only its hash, so changing it breaks repeat counts. */
-export declare function failureSignature(text: string): string;
-/** The memory text for a failure payload, or why it is not stored; a routine skip keeps its text for the log. Pure. */
-export declare function lessonFromFailure(payload: JsonValue): FailureReading;
 /** Store a failure as an error memory unless it is routine or a repeat, and log it either way, even when storing throws. */
 export declare function captureToolFailure(hippoRoot: string, tenantId: string, payload: JsonValue): CaptureErrorOutcome;
+/** Who sent a failure from another machine: the audit actor and the project its lesson and repeat check belong to. */
+export interface LessonCaller {
+    actor: string;
+    originProject: string;
+    origins: readonly string[];
+}
+export declare function storeLesson(hippoRoot: string, tenantId: string, text: string, caller?: LessonCaller): 'stored' | 'duplicate';
 //# sourceMappingURL=capture-error.d.ts.map