hippo-memory 1.68.0 → 1.69.0

package/dist/api/promote.js

@@ -1,14 +1,12 @@
 // Promote to the global store, supersede with a successor, and archive raw memories.
-import { openHippoDb, closeHippoDb, isSqliteBusy } from '../db.js';
+import { openHippoDb, closeHippoDb } from '../db.js';
 import { ConflictError, NotFoundError } from '../api-errors.js';
-import { auditRejectionRefusal } from '../store/audit-event.js';
 import { stampOriginProject } from '../store/entry-row.js';
-import { removeEntryMirrors } from '../store/mirrors.js';
-import { writeEntryDbOnly, writeEntryMirrors } from '../store/entry-writes.js';
+import { writeEntryMirrors } from '../store/entry-writes.js';
+import { cleanArchivedMirrors, commitSupersede } from '../store/entry-writes-group.js';
 import { readEntry } from '../store/entry-reads.js';
 import { updateStatsUnlessBusy } from '../store/index-and-stats.js';
-import { markSummaryDirtyInTx } from '../summary-dirty.js';
-import { RejectedValueError } from '../rejection.js';
+import { requireGroup } from '../store-port.js';
 import { log } from '../log.js';
 import { createSuccessor } from '../memory.js';
 import { appendAuditEvent } from '../audit.js';
@@ -16,7 +14,7 @@ import { promoteToGlobal } from '../shared.js';
 import { archiveRawMemory } from '../raw-archive.js';
 import { loadConfig } from '../config.js';
 import { selectMemoryReach } from '../store/tenant-lookup.js';
-import { canTouchScope } from '../recall-scope.js';
+import { canTouchScope, personalScopeOf } from '../recall-scope.js';
 export function promote(ctx, id) {
     // Tenant scope: promoteToGlobal reads the entry from the local root via
     // readEntry without a tenant filter, so a Bearer for tenant A could
@@ -49,11 +47,28 @@ export function promote(ctx, id) {
     return { ok: true, sourceId: id, globalId: globalEntry.id };
 }
 export function supersede(ctx, oldId, newContent) {
-    const old = readSupersedable(ctx, oldId);
-    const newEntry = createSuccessor(old, newContent, {
+    const reply = ctx.store ? supersedeThroughStore(ctx, ctx.store, oldId, newContent) : supersedeOnHippoDb(ctx, oldId, newContent);
+    // SAFETY: a C typed with a store gets the promise its path returns; a wide C is typed as the union, which a caller has to await anyway.
+    return reply;
+}
+async function supersedeThroughStore(ctx, store, oldId, newContent) {
+    const entryWrites = requireGroup(store, 'entryWrites');
+    const [old] = await store.entriesByIds([oldId], ctx.tenantId);
+    const newEntry = createSuccessor(assertSupersedable(ctx, oldId, old ?? null), newContent, {
         tenantId: ctx.tenantId,
         baseHalfLifeDays: loadConfig(ctx.hippoRoot).defaultHalfLifeDays,
     });
+    // The store writes origin_project as given, so the served folder's fallback is stamped here.
+    const successor = stampOriginProject(ctx.hippoRoot, newEntry);
+    await entryWrites.supersede({ tenantId: ctx.tenantId, actor: ctx.actor.subject, ownScope: personalScopeOf(ctx.actor), oldId, successor });
+    return { ok: true, oldId, newId: successor.id };
+}
+function supersedeOnHippoDb(ctx, oldId, newContent) {
+    const old = assertSupersedable(ctx, oldId, readEntry(ctx.hippoRoot, oldId, ctx.tenantId));
+    const successor = stampOriginProject(ctx.hippoRoot, createSuccessor(old, newContent, {
+        tenantId: ctx.tenantId,
+        baseHalfLifeDays: loadConfig(ctx.hippoRoot).defaultHalfLifeDays,
+    }));
     // Race-safe transition: open a fresh db handle, BEGIN IMMEDIATE, run all
     // three steps (CAS on old + writeEntryDbOnly(new) + supersede audit row)
     // inside the same transaction. Two concurrent supersedes: exactly one CAS
@@ -62,14 +77,14 @@ export function supersede(ctx, oldId, newContent) {
     // the old.superseded_by pointer.
     const db = openHippoDb(ctx.hippoRoot);
     try {
-        commitSupersede(db, ctx, oldId, old, newEntry);
+        commitSupersede(db, { tenantId: ctx.tenantId, actor: ctx.actor.subject, ownScope: personalScopeOf(ctx.actor), oldId, successor });
         // Mirrors after COMMIT, while the db handle is still open. Same
         // invariant as the original writeEntry: a mirror failure leaves disk
         // MISSING the markdown for the new memory (rebuildIndex rewrites every
         // markdown mirror from the DB) but DOES NOT desync the DB or
         // roll back the supersede. Logged + swallowed, non-fatal.
         try {
-            writeEntryMirrors(ctx.hippoRoot, newEntry);
+            writeEntryMirrors(ctx.hippoRoot, successor);
         }
         catch (mirrorErr) {
             log.error(`supersede: mirror write failed (non-fatal, will self-heal): ${mirrorErr instanceof Error ? mirrorErr.message : String(mirrorErr)}`);
@@ -78,11 +93,10 @@ export function supersede(ctx, oldId, newContent) {
     finally {
         closeHippoDb(db);
     }
-    return { ok: true, oldId, newId: newEntry.id };
+    return { ok: true, oldId, newId: successor.id };
 }
 /** The tenant-scoped row to supersede; another tenant's id, or someone else's personal row, reads as not found. */
-function readSupersedable(ctx, oldId) {
-    const old = readEntry(ctx.hippoRoot, oldId, ctx.tenantId);
+function assertSupersedable(ctx, oldId, old) {
     if (!old || !canTouchScope(ctx.actor, old.scope ?? null)) {
         throw new NotFoundError(`Memory not found: ${oldId}`);
     }
@@ -92,50 +106,22 @@ function readSupersedable(ctx, oldId) {
     }
     return old;
 }
-/** CAS on the old row, the successor's insert and the 'supersede' audit row, in one BEGIN IMMEDIATE transaction. */
-function commitSupersede(db, ctx, oldId, old, newEntry) {
-    db.exec('BEGIN IMMEDIATE');
-    try {
-        // The tenant filter repeats readEntry's check at no cost, closing an ownership change between read and update.
-        const result = db.prepare(`
-      UPDATE memories
-      SET superseded_by = ?
-      WHERE id = ? AND tenant_id = ? AND superseded_by IS NULL
-    `).run(newEntry.id, oldId, ctx.tenantId);
-        if ((result.changes ?? 0) === 0) {
-            db.exec('ROLLBACK');
-            throw new ConflictError(`Memory ${oldId} already superseded by another writer`);
-        }
-        // After the CAS guard, so a lost race throws before the old parent is marked for rebuild.
-        if (old.dag_parent_id) {
-            markSummaryDirtyInTx(db, old.dag_parent_id, ctx.tenantId, ctx.actor.subject);
-        }
-        // Emits its own 'remember' audit row inside the same transaction.
-        writeEntryDbOnly(db, stampOriginProject(ctx.hippoRoot, newEntry), { actor: ctx.actor.subject });
-        appendAuditEvent(db, {
-            tenantId: ctx.tenantId,
-            actor: ctx.actor.subject,
-            op: 'supersede',
-            targetId: oldId,
-            metadata: { newId: newEntry.id },
-        });
-        db.exec('COMMIT');
-    }
-    catch (err) {
-        try {
-            db.exec('ROLLBACK');
-        }
-        catch { /* already rolled back */ }
-        // The refusal audit lands after ROLLBACK, in a fresh implicit transaction the aborted one cannot undo.
-        if (err instanceof RejectedValueError) {
-            auditRejectionRefusal(db, err, ctx.actor.subject);
-        }
-        throw err;
-    }
-}
 export function archiveRaw(ctx, id, reason, opts = {}) {
+    const reply = ctx.store ? archiveRawThroughStore(ctx, ctx.store, id, reason, opts) : archiveRawOnHippoDb(ctx, id, reason, opts);
+    // SAFETY: a C typed with a store gets the promise its path returns; a wide C is typed as the union, which a caller has to await anyway.
+    return reply;
+}
+/** afterArchive writes on hippo.db's own handle, and only connectors send it, so a store refuses it. */
+async function archiveRawThroughStore(ctx, store, id, reason, opts) {
+    const entryWrites = requireGroup(store, 'entryWrites');
+    if (opts.afterArchive)
+        throw new Error('afterArchive runs on hippo.db only, never through a store');
+    const archivedAt = await entryWrites.archiveRaw({ tenantId: ctx.tenantId, actor: ctx.actor.subject, ownScope: personalScopeOf(ctx.actor), id, reason });
+    return { ok: true, archivedAt };
+}
+function archiveRawOnHippoDb(ctx, id, reason, opts) {
     const db = openHippoDb(ctx.hippoRoot);
-    let mirrorOk = false;
+    let archivedAt;
     try {
         // Tenant scope: archiveRawMemory looks up the row by id alone, so a
         // Bearer for tenant A could archive tenant B's raw row without this
@@ -146,40 +132,12 @@ export function archiveRaw(ctx, id, reason, opts = {}) {
         if (reach?.tenantId !== ctx.tenantId || !canTouchScope(ctx.actor, reach.scope)) {
             throw new NotFoundError(`memory not found: ${id}`);
         }
-        archiveRawMemory(db, id, {
+        archivedAt = archiveRawMemory(db, id, {
             reason,
             who: ctx.actor.subject,
             afterArchive: opts.afterArchive,
         });
-        // archiveRawMemory deletes the memories row but leaves any legacy markdown
-        // mirror in <root>/{buffer,episodic,semantic}/<id>.md untouched. If we left
-        // the mirror in place, a subsequent initStore() on an empty memories table
-        // would silently re-import the row via bootstrapLegacyStore — defeating the
-        // archive (and the GDPR right-to-be-forgotten promise on raw rows). Mirror
-        // forget() at src/store.ts:1046, which uses the same removeEntryMirrors call.
-        // The DB transaction has already committed; if filesystem unlink fails here
-        // we log and continue. The mirror reaper in openHippoDb will catch it on
-        // next DB open: raw_archive.mirror_cleaned_at stays NULL until every layer
-        // mirror for this id is gone, so the reaper genuinely retries.
-        try {
-            removeEntryMirrors(ctx.hippoRoot, id);
-            mirrorOk = true;
-        }
-        catch (mirrorErr) {
-            log.error(`archiveRaw: mirror cleanup failed for ${id} (will retry via reaper on next openHippoDb): ${mirrorErr instanceof Error ? mirrorErr.message : String(mirrorErr)}`);
-        }
-        if (mirrorOk) {
-            // Stamp mirror_cleaned_at now so the next openHippoDb reaper SELECT
-            // returns empty for this row. NULL stays untouched on failure -> retry.
-            try {
-                db.prepare(`UPDATE raw_archive SET mirror_cleaned_at = ? WHERE memory_id = ?`).run(new Date().toISOString(), id);
-            }
-            catch (err) {
-                if (!isSqliteBusy(err))
-                    throw err;
-                log.warnThenDebug('archive-mirror-stamp-busy', `archived ${id}; the store was busy, so the mirror reaper will re-check it on the next open`);
-            }
-        }
+        cleanArchivedMirrors(db, ctx.hippoRoot, id);
     }
     finally {
         closeHippoDb(db);
@@ -187,9 +145,6 @@ export function archiveRaw(ctx, id, reason, opts = {}) {
     // Counted here rather than in the CLI: the HTTP archive route calls this too,
     // so a routed archive would otherwise never reach the forgotten counter.
     updateStatsUnlessBusy(ctx.hippoRoot, { forgotten: 1 }, `removed ${id}`);
-    // archiveRawMemory does not return the archive_at timestamp it wrote. We
-    // emit a fresh ISO timestamp here for the API response. Within a millisecond
-    // of the actual write, fine for a server response shape.
-    return { ok: true, archivedAt: new Date().toISOString() };
+    return { ok: true, archivedAt };
 }
 //# sourceMappingURL=promote.js.map

package/dist/api/remember.d.ts

@@ -1,6 +1,6 @@
 import type { DatabaseSyncLike } from '../db.js';
 import { type MemoryKind } from '../memory.js';
-import type { Context } from './types.js';
+import type { Context, StoreReply } from './types.js';
 export interface RememberOpts {
     content: string;
     kind?: MemoryKind;
@@ -38,5 +38,6 @@ export interface RememberResult {
     /** Set only when the content held secret material: untrusted text had it redacted, typed text was stored as sent. */
     warnings?: string[];
 }
-export declare function remember(ctx: Context, opts: RememberOpts): RememberResult;
+/** Store one memory. With `ctx.store`, its entryWrites group writes the row and its remember row; hippo.db is opened only when there is no store. */
+export declare function remember<C extends Context>(ctx: C, opts: RememberOpts): StoreReply<C, RememberResult>;
 //# sourceMappingURL=remember.d.ts.map

package/dist/api/remember.js

@@ -1,5 +1,7 @@
 // Write path: remember stores one memory after secret vetting and, for untrusted content, the instruction check.
 import { writeEntry } from '../store/entry-writes.js';
+import { stampOriginProject } from '../store/entry-row.js';
+import { requireGroup } from '../store-port.js';
 import { detectInstruction } from '../instruction-detect.js';
 import { quarantineScopeFor, recordQuarantine } from '../quarantine.js';
 import { createMemory } from '../memory.js';
@@ -24,7 +26,7 @@ function rememberScope(ctx, opts) {
     }
     return own;
 }
-export function remember(ctx, opts) {
+function prepareRemember(ctx, opts) {
     if (opts.project)
         assertCallerProject(opts.project);
     const requestedScope = rememberScope(ctx, opts);
@@ -39,6 +41,39 @@ export function remember(ctx, opts) {
         tenantId: ctx.tenantId,
         baseHalfLifeDays: loadConfig(ctx.hippoRoot).defaultHalfLifeDays,
     });
+    // Aliases only widen what a reader matches; a row has one origin. A personal row's '' follows its owner into every project.
+    const origin = opts.personal ? '' : opts.project?.name;
+    const stamped = origin !== undefined ? { ...entry, origin_project: origin } : entry;
+    return { entry: stamped, requestedScope, detection, warnings: vetted.warnings };
+}
+function rememberResult(ctx, prepared) {
+    const { entry, detection, warnings } = prepared;
+    const result = { id: entry.id, kind: entry.kind, tenantId: ctx.tenantId };
+    if (detection.flagged)
+        result.quarantined = { reason: detection.reason ?? 'unknown' };
+    if (warnings.length > 0)
+        result.warnings = [...warnings];
+    return result;
+}
+/** Store one memory. With `ctx.store`, its entryWrites group writes the row and its remember row; hippo.db is opened only when there is no store. */
+export function remember(ctx, opts) {
+    const reply = ctx.store ? rememberThroughStore(ctx, ctx.store, opts) : rememberOnHippoDb(ctx, opts);
+    // SAFETY: a C typed with a store gets the promise its path returns; a wide C is typed as the union, which a caller has to await anyway.
+    return reply;
+}
+/** afterWrite and the quarantine row write on hippo.db's own handle, and only connectors send them, so a store refuses both. */
+async function rememberThroughStore(ctx, store, opts) {
+    const entryWrites = requireGroup(store, 'entryWrites');
+    if (opts.afterWrite || opts.untrusted)
+        throw new Error('afterWrite and untrusted content are written to hippo.db only, never through a store');
+    const prepared = prepareRemember(ctx, opts);
+    // The store writes origin_project as given, so the served folder's fallback is stamped here.
+    await entryWrites.writeEntry({ entry: stampOriginProject(ctx.hippoRoot, prepared.entry), actor: ctx.actor.subject });
+    return rememberResult(ctx, prepared);
+}
+function rememberOnHippoDb(ctx, opts) {
+    const prepared = prepareRemember(ctx, opts);
+    const { requestedScope, detection } = prepared;
     // writeEntry threads ctx.actor.subject into its internal audit hook, so exactly
     // one 'remember' event lands in the log with the supplied actor.
     const afterWrite = detection.flagged
@@ -53,15 +88,7 @@ export function remember(ctx, opts) {
             opts.afterWrite?.(db, memoryId);
         }
         : opts.afterWrite;
-    // Aliases only widen what a reader matches; a row has one origin. A personal row's '' follows its owner into every project.
-    const origin = opts.personal ? '' : opts.project?.name;
-    const stamped = origin !== undefined ? { ...entry, origin_project: origin } : entry;
-    writeEntry(ctx.hippoRoot, stamped, { actor: ctx.actor.subject, afterWrite });
-    const result = { id: entry.id, kind: entry.kind, tenantId: ctx.tenantId };
-    if (detection.flagged)
-        result.quarantined = { reason: detection.reason ?? 'unknown' };
-    if (vetted.warnings.length > 0)
-        result.warnings = vetted.warnings;
-    return result;
+    writeEntry(ctx.hippoRoot, prepared.entry, { actor: ctx.actor.subject, afterWrite });
+    return rememberResult(ctx, prepared);
 }
 //# sourceMappingURL=remember.js.map

package/dist/capture/compact.js

@@ -4,10 +4,11 @@ import { isInitialized } from '../store/open.js';
 import { saveActiveTaskSnapshot, loadActiveTaskSnapshot } from '../store/sessions.js';
 import { PRE_COMPACT_INSTRUCTION, 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 { defaultPreCompactLogPath, vscodeUserHooksFile } from '../hooks/shared.js';
 import { readClaudeCodePreCompact } from '../capture-contract.js';
 import { errorMessage } from '../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
@@ -58,6 +59,14 @@ function printPreCompactInstruction(logFile) {
         appendPreCompactLog(logFile, `instruction not printed: ${errorMessage(err)}`);
     }
 }
+/** The Copilot CLI accepts both preCompact and PreCompact, so hippo.json's pair can run twice for one compaction. */
+const TWIN_FIRE_MS = 10_000;
+function snapshotJustSaved(hippoRoot, sessionId) {
+    if (sessionId === null || sessionId === '')
+        return false;
+    const active = loadActiveTaskSnapshot(hippoRoot, resolveTenantId({}));
+    return active?.session_id === sessionId && active.source === 'pre-compact' && Date.now() - Date.parse(active.updated_at) < TWIN_FIRE_MS;
+}
 /** 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;
@@ -74,10 +83,20 @@ function runPreCompact(hippoRoot, options, logFile) {
         return;
     }
     const { sessionId, transcriptPath: payloadTranscriptPath, cwd: payloadCwd, trigger: payloadTrigger } = receipt.input;
+    // With chat.useClaudeHooks on, VS Code runs Claude Code's hooks too; it never sends PostCompact to close a record, nor reads the summariser text.
+    const vscode = runtime === 'claude-code' && isVscodeTranscript(payloadTranscriptPath);
+    if (vscode && fs.existsSync(vscodeUserHooksFile())) {
+        appendPreCompactLog(logFile, 'skip: VS Code payload, hippo.json runs pre-compact for this chat');
+        return;
+    }
+    if (runtime === 'copilot' && snapshotJustSaved(hippoRoot, sessionId)) {
+        appendPreCompactLog(logFile, `skip: snapshot for session ${sessionId} saved under ${TWIN_FIRE_MS / 1000} s ago, by the other preCompact entry`);
+        return;
+    }
     // The record is the "something saved before every compaction", so it lands even when no snapshot is derivable below.
     // Copilot has no PostCompact hook to close a record, so its compactions get the snapshot alone.
     let recordId = null;
-    if (runtime === 'claude-code' && sessionId !== null && sessionId !== '') {
+    if (runtime === 'claude-code' && !vscode && sessionId !== null && sessionId !== '') {
         recordId = recordCompactionStart(hippoRoot, { sessionId, trigger: payloadTrigger, cwd: payloadCwd, transcriptPath: payloadTranscriptPath }, (message) => appendPreCompactLog(logFile, message));
         printPreCompactInstruction(logFile);
     }

package/dist/capture/copilot-transcript.d.ts

@@ -8,8 +8,11 @@ export interface CopilotTurn {
     role: 'user' | 'assistant';
     text: string;
 }
+export declare const SESSION_ID_RE: RegExp;
 /** The Copilot CLI log for a session, `<copilotHome>/session-state/<id>/events.jsonl`; null for an unsafe id or a missing file. */
 export declare function copilotTranscriptFor(sessionId: string): string | null;
+/** True for VS Code's own chat log, `<workspaceStorage>/<id>/github.copilot-chat/transcripts/<session id>.jsonl`, in either slash and any case. */
+export declare function isVscodeTranscript(file: string | null): boolean;
 /** The turn one Copilot event-log line carries: the text of a human user.message or of an assistant.message; null for any other line, a sub-agent's included. */
 export declare function copilotTurn(line: CopilotEventLine): CopilotTurn | null;
 //# sourceMappingURL=copilot-transcript.d.ts.map

package/dist/capture/copilot-transcript.js

@@ -5,7 +5,7 @@ import * as path from 'path';
 import { copilotHomeDir } from '../hooks/shared.js';
 import { isObjectLike, isStringValue } from '../capture-contract.js';
 // A session id becomes a folder name, so anything beyond word characters and hyphens could climb out of session-state.
-const SESSION_ID_RE = /^[\w-]+$/;
+export const SESSION_ID_RE = /^[\w-]+$/;
 // user.message sources that mark text hippo did not get from the human: a hidden skill injection or another agent's prompt.
 const INJECTED_SOURCE_PREFIXES = ['skill-', 'agent-'];
 /** The Copilot CLI log for a session, `<copilotHome>/session-state/<id>/events.jsonl`; null for an unsafe id or a missing file. */
@@ -15,6 +15,13 @@ export function copilotTranscriptFor(sessionId) {
     const file = path.join(copilotHomeDir(), 'session-state', sessionId, 'events.jsonl');
     return fs.existsSync(file) ? file : null;
 }
+/** True for VS Code's own chat log, `<workspaceStorage>/<id>/github.copilot-chat/transcripts/<session id>.jsonl`, in either slash and any case. */
+export function isVscodeTranscript(file) {
+    if (!file)
+        return false;
+    const parts = file.toLowerCase().split(/[\\/]/);
+    return parts.length >= 3 && parts[parts.length - 2] === 'transcripts' && parts[parts.length - 3] === 'github.copilot-chat';
+}
 function isSubagentLine(line, data) {
     if (isStringValue(line.agentId) && line.agentId !== '')
         return true;

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

@@ -0,0 +1,13 @@
+import type { SessionTurn } from './transcript.js';
+/** A turn close runs after each reply; a full close runs once, when the session ends. */
+export type WorkerMode = 'turn' | 'full';
+/** Runs `work` unless a live worker holds this session, which then runs the request after its own so the last reply is never dropped. */
+export declare function runSessionWorker(sessionId: string | null, mode: WorkerMode, work: (mode: WorkerMode) => Promise<void>): Promise<void>;
+/** The cursor position after `turns`: how many there were and a hash of the last. */
+export declare function turnPosition(turns: readonly SessionTurn[]): string;
+/** The turns after `position`; all of them when it is null or its last turn is no longer in view. */
+export declare function turnsAfter(turns: readonly SessionTurn[], position: string | null): readonly SessionTurn[];
+/** The saved position for this session's transcript; null when none was saved, it names another file, or it is unreadable. */
+export declare function loadTurnPosition(sessionId: string, transcriptPath: string): string | null;
+export declare function saveTurnPosition(sessionId: string, transcriptPath: string, turns: readonly SessionTurn[], log: (message: string) => void): void;
+//# sourceMappingURL=session-worker.d.ts.map

package/dist/capture/session-worker.js

@@ -0,0 +1,194 @@
+// One session-end worker per session at a time, plus how far turn capture has read that session's transcript.
+// Two fast replies would otherwise start two workers that both read the dedupe keys before either writes.
+import * as fs from 'fs';
+import * as path from 'path';
+import { createHash } from 'node:crypto';
+import { homeDir } from '../hooks/shared.js';
+import { errorMessage } from '../log.js';
+import { isObjectLike, isStringValue } from '../capture-contract.js';
+import { SESSION_ID_RE } from './copilot-transcript.js';
+/** Null for a missing id or one that could climb out of the sessions folder. */
+function sessionStateFiles(sessionId) {
+    if (sessionId === null || !SESSION_ID_RE.test(sessionId))
+        return null;
+    const base = path.join(homeDir(), '.hippo', 'sessions', sessionId);
+    return { lock: `${base}.lock`, queued: `${base}.queued`, cursor: `${base}.cursor.json` };
+}
+function pidAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (err) {
+        // EPERM means the process exists but belongs to someone else.
+        return err instanceof Error && 'code' in err && err.code === 'EPERM';
+    }
+}
+/** Windows reuses pids, so past this a lock is stale whatever process it names; a worker rarely waits more than minutes on a busy store. */
+const STALE_LOCK_MS = 15 * 60 * 1000;
+/** A dead holder frees its session at once, and any holder at STALE_LOCK_MS. */
+function holderAlive(lock) {
+    let text;
+    let mtimeMs;
+    try {
+        text = fs.readFileSync(lock, 'utf8');
+        mtimeMs = fs.statSync(lock).mtimeMs;
+    }
+    catch (err) {
+        // Gone means released; any other read error is taken as held, so two workers never run on a guess.
+        return !(err instanceof Error && 'code' in err && err.code === 'ENOENT');
+    }
+    const held = /^(\d+):(\d+)$/.exec(text.trim());
+    if (Date.now() - (held ? Number(held[2]) : mtimeMs) > STALE_LOCK_MS)
+        return false;
+    // Empty or torn: its taker is between the create and the write, so it is held.
+    if (!held)
+        return true;
+    const pid = Number(held[1]);
+    return pid !== process.pid && pidAlive(pid);
+}
+// SHORTCUT: two takers racing one stale-lock cleanup can both run, as every worker did before the lock; an atomic link-based take if that shows up.
+function takeSessionLock(lock) {
+    for (let attempt = 0; attempt < 2; attempt++) {
+        try {
+            fs.writeFileSync(lock, `${process.pid}:${Date.now()}`, { flag: 'wx' });
+            return 'taken';
+        }
+        catch (err) {
+            if (!(err instanceof Error && 'code' in err && err.code === 'EEXIST'))
+                return 'unusable';
+            if (holderAlive(lock))
+                return 'held';
+        }
+        try {
+            fs.rmSync(lock, { force: true });
+        }
+        catch {
+            return 'unusable';
+        }
+    }
+    return 'held';
+}
+function releaseSessionLock(lock) {
+    try {
+        fs.rmSync(lock, { force: true });
+    }
+    catch {
+        // A lock left behind names this pid, which is dead once the worker exits, so the next taker clears it.
+    }
+}
+/** False when the sessions folder cannot be written, so the caller runs unlocked as before. */
+function queueRun(files, mode) {
+    try {
+        fs.mkdirSync(path.dirname(files.queued), { recursive: true });
+        // A full close outranks a turn close: it overwrites a queued turn, and a turn never replaces a queued full close.
+        if (mode === 'full')
+            fs.writeFileSync(files.queued, 'full');
+        else
+            fs.writeFileSync(files.queued, 'turn', { flag: 'wx' });
+        return true;
+    }
+    catch (err) {
+        return err instanceof Error && 'code' in err && err.code === 'EEXIST';
+    }
+}
+/** Takes the queued request by renaming it, so one queued while this reads it lands in a fresh file. */
+function takeQueued(queued) {
+    const taken = `${queued}.${process.pid}`;
+    try {
+        fs.renameSync(queued, taken);
+    }
+    catch {
+        // Nothing queued, or a rename refused for a moment; the request stays queued for the next round.
+        return null;
+    }
+    try {
+        return fs.readFileSync(taken, 'utf8') === 'full' ? 'full' : 'turn';
+    }
+    finally {
+        fs.rmSync(taken, { force: true });
+    }
+}
+/** Runs `work` unless a live worker holds this session, which then runs the request after its own so the last reply is never dropped. */
+export async function runSessionWorker(sessionId, mode, work) {
+    const files = sessionStateFiles(sessionId);
+    if (files === null || !queueRun(files, mode))
+        return work(mode);
+    for (let take = takeSessionLock(files.lock); take !== 'held'; take = takeSessionLock(files.lock)) {
+        if (take === 'unusable')
+            return work(mode);
+        let ran = false;
+        try {
+            for (let next = takeQueued(files.queued); next !== null; next = takeQueued(files.queued)) {
+                ran = true;
+                await work(next);
+            }
+        }
+        finally {
+            releaseSessionLock(files.lock);
+        }
+        // A request queued after the last take found the lock still held and left, so it runs here.
+        if (!ran || !fs.existsSync(files.queued))
+            return;
+    }
+}
+function turnKey(turn) {
+    return createHash('sha256').update(`${turn.role}\n${turn.text}`).digest('hex').slice(0, 16);
+}
+/** The cursor position after `turns`: how many there were and a hash of the last. */
+export function turnPosition(turns) {
+    return turns.length === 0 ? '0:' : `${turns.length}:${turnKey(turns[turns.length - 1])}`;
+}
+/** The turns after `position`; all of them when it is null or its last turn is no longer in view. */
+export function turnsAfter(turns, position) {
+    if (position === null)
+        return turns;
+    const [countText, key] = position.split(':');
+    const count = Number(countText);
+    if (!Number.isInteger(count) || count <= 0)
+        return turns;
+    if (count <= turns.length && turnKey(turns[count - 1]) === key)
+        return turns.slice(count);
+    // A transcript too big to read whole is read from its tail, so the count shifts; the last turn's text still marks the place.
+    for (let i = turns.length - 1; i >= 0; i--) {
+        if (turnKey(turns[i]) === key)
+            return turns.slice(i + 1);
+    }
+    return turns;
+}
+/** The saved position for this session's transcript; null when none was saved, it names another file, or it is unreadable. */
+export function loadTurnPosition(sessionId, transcriptPath) {
+    const file = sessionStateFiles(sessionId)?.cursor;
+    if (!file || !fs.existsSync(file))
+        return null;
+    try {
+        const cursor = JSON.parse(fs.readFileSync(file, 'utf8'));
+        if (!isObjectLike(cursor) || !('source' in cursor) || cursor.source !== transcriptPath)
+            return null;
+        return 'position' in cursor && isStringValue(cursor.position) ? cursor.position : null;
+    }
+    catch {
+        // A torn cursor means the next capture reads every turn, which the dedupe keys absorb.
+        return null;
+    }
+}
+// SHORTCUT: one small cursor file per chat is never pruned; prune by age at sleep if the folder grows.
+export function saveTurnPosition(sessionId, transcriptPath, turns, log) {
+    const file = sessionStateFiles(sessionId)?.cursor;
+    if (!file)
+        return;
+    const cursor = {
+        runtime: 'vscode', sessionId, source: transcriptPath, position: turnPosition(turns), updatedAt: new Date().toISOString(),
+    };
+    const tmp = `${file}.${process.pid}.tmp`;
+    try {
+        fs.mkdirSync(path.dirname(file), { recursive: true });
+        fs.writeFileSync(tmp, JSON.stringify(cursor));
+        fs.renameSync(tmp, file);
+    }
+    catch (err) {
+        // Windows refuses the rename (EPERM) while another process has the cursor open; the next reply re-reads these turns, which the dedupe keys absorb.
+        log(`cursor not saved: ${errorMessage(err)}`);
+    }
+}
+//# sourceMappingURL=session-worker.js.map

package/dist/capture-contract.d.ts

@@ -1,5 +1,5 @@
 /** A host lifecycle moment hippo can capture from. */
-export type CaptureEvent = 'prompt' | 'tool-failure' | 'pre-compact' | 'post-compact' | 'session-start' | 'session-end' | 'reset';
+export type CaptureEvent = 'prompt' | 'tool-failure' | 'pre-compact' | 'post-compact' | 'session-start' | 'session-end' | 'turn-end' | 'reset';
 /** What hippo read from one host payload, before anything is written. */
 export interface CaptureInput {
     readonly runtime: string;
@@ -46,4 +46,6 @@ export declare function isObjectLike<T>(value: T): value is T & object;
 export type HookRuntime = 'claude-code' | 'copilot';
 /** Reads a Claude Code PreCompact payload, or a Copilot one after stdin.ts mapped it to the same snake_case keys; only an empty stdin counts as a manual run. */
 export declare function readClaudeCodePreCompact(stdinText: string | undefined, timedOut: boolean, runtime?: HookRuntime): CaptureReceipt;
+/** Reads VS Code's per-reply Stop payload. Pass the raw stdin: stdin.ts would give a Copilot CLI agentStop the same snake_case keys. */
+export declare function readVscodeStop(stdinText: string | undefined, timedOut: boolean): CaptureReceipt;
 //# sourceMappingURL=capture-contract.d.ts.map

package/dist/capture-contract.js

@@ -46,4 +46,40 @@ export function readClaudeCodePreCompact(stdinText, timedOut, runtime = 'claude-
         },
     };
 }
+/** Reads VS Code's per-reply Stop payload. Pass the raw stdin: stdin.ts would give a Copilot CLI agentStop the same snake_case keys. */
+export function readVscodeStop(stdinText, timedOut) {
+    if (!stdinText || stdinText.trim() === '') {
+        return timedOut
+            ? { status: 'unavailable', reason: 'no Stop payload arrived before the stdin wait window closed' }
+            : { status: 'skipped', reason: 'no payload: turn capture runs only from a VS Code Stop hook' };
+    }
+    let payload;
+    try {
+        payload = JSON.parse(stdinText.trim());
+    }
+    catch {
+        // Non-JSON stdin leaves payload undefined, which the shape check rejects.
+    }
+    if (!isObjectLike(payload) || !('hook_event_name' in payload) || payload.hook_event_name !== 'Stop') {
+        return { status: 'skipped', reason: 'not a VS Code Stop payload (no snake_case hook_event_name "Stop")' };
+    }
+    if (!('transcript_path' in payload) || !isStringValue(payload.transcript_path) || !/\.jsonl$/i.test(payload.transcript_path)) {
+        return { status: 'skipped', reason: 'Stop payload names no .jsonl transcript_path' };
+    }
+    if (!('session_id' in payload) || !isStringValue(payload.session_id) || payload.session_id === '') {
+        return { status: 'skipped', reason: 'Stop payload has no session_id' };
+    }
+    return {
+        status: 'received',
+        input: {
+            runtime: 'vscode',
+            event: 'turn-end',
+            manual: false,
+            sessionId: payload.session_id,
+            cwd: 'cwd' in payload && isStringValue(payload.cwd) ? payload.cwd : null,
+            transcriptPath: payload.transcript_path,
+            trigger: null,
+        },
+    };
+}
 //# sourceMappingURL=capture-contract.js.map