hippo-memory 1.71.0 → 1.72.0

package/dist/store/search-rows.js

@@ -1,6 +1,7 @@
 import { isFtsAvailable, closeHippoDb } from '../db/index.js';
 import { tokenize } from '../util/tokenize.js';
-import { isPersonalScope, scopeAdmitSql } from './recall-scope.js';
+import { isPersonalScope } from '../core/recall-scope.js';
+import { scopeAdmitSql } from './rule-sql.js';
 import { ftsTermParts, RAREST_TERM_COUNT, rarestFtsQuery } from '../core/prompt-recall.js';
 import { errorMessage, log } from '../util/log.js';
 import { originInSql } from '../core/project-identity.js';
@@ -26,7 +27,10 @@ function withProject(scope, col, origin) {
         return scope;
     // A string is the shape published callers passed before a project could carry several names.
     const originProjects = [origin].flat();
-    return { sql: `${scope.sql} AND (${col}origin_project = '' OR ${originInSql(originProjects, `${col}origin_project`)})`, params: [...scope.params, ...originProjects] };
+    return {
+        sql: `${scope.sql} AND (${col}origin_project = '' OR ${originInSql(originProjects, `${col}origin_project`)})`,
+        params: [...scope.params, ...originProjects],
+    };
 }
 /** Scope rule for recall: none requested is default-deny; 'exact' narrows to the request; 'additive' adds it to the default set, unless it is personal,
  * which only `ownScope` opens. */
@@ -85,7 +89,8 @@ function searchPredicates(tenantId, scopeFilter, includeSuperseded, originProjec
 }
 /** Every admitted row, oldest first; the no-terms path and the last-resort fallback share it. */
 function selectAllCandidates(db, p, limit) {
-    const sql = `SELECT ${MEMORY_SELECT_COLUMNS} FROM memories${p.tenantOnlyPredicate}${p.archivedClauseTenantOnly}${p.plainScope.sql}${p.currentNoAlias} ORDER BY created ASC, id ASC LIMIT ?`;
+    const sql = `SELECT ${MEMORY_SELECT_COLUMNS} FROM memories${p.tenantOnlyPredicate}${p.archivedClauseTenantOnly}` +
+        `${p.plainScope.sql}${p.currentNoAlias} ORDER BY created ASC, id ASC LIMIT ?`;
     // SAFETY: sql selects exactly MEMORY_SELECT_COLUMNS, whose column list
     // matches MemoryRow's field set.
     return db.prepare(sql).all(...p.tenantParams, ...p.scopeParams, limit);
@@ -155,7 +160,7 @@ export function loadRecallSearchEntries(hippoRoot, query, limit = DEFAULT_SEARCH
 // Split out so callers with an already-open db (the prompt-recall path) skip
 // the initStore+open/close cycle per store per call.
 export function loadRecallSearchEntriesFromDb(db, query, options = {}) {
-    const { limit = DEFAULT_SEARCH_CANDIDATE_LIMIT, tenantId, requestedScope, explicitScopeMode = 'exact', includeSuperseded = true, originProjects, ownScope } = options;
+    const { limit = DEFAULT_SEARCH_CANDIDATE_LIMIT, tenantId, requestedScope, explicitScopeMode = 'exact', includeSuperseded = true, originProjects, ownScope, } = options;
     const scopeFilter = recallScopeFilter(requestedScope, explicitScopeMode, ownScope);
     return loadSearchRows(db, query, limit, tenantId, { scopeFilter, includeSuperseded, originProjects }).map(rowToEntry);
 }

package/dist/store/sessions.js

@@ -1,3 +1,4 @@
+import { HOUR_MS } from '../util/time.js';
 import { isSharedStore } from '../core/config.js';
 import { closeHippoDb, HOOK_DB_WAIT_MS, scopedBusyWait, withWriteScope } from '../db/index.js';
 import { raiseMinBinary } from '../db/meta.js';
@@ -24,8 +25,9 @@ export function continuityStamp(key) {
 }
 // An unkeyed write acts on the tenant's newest or every active row, which on a shared store belong to other owners.
 function assertKeyedOnSharedStore(fn, hippoRoot, key) {
-    if (!key && isSharedStore(hippoRoot))
+    if (!key && isSharedStore(hippoRoot)) {
         throw new Error(`${fn}: a shared store keeps one task snapshot per owner and project, so this write needs their continuity key`);
+    }
 }
 function insertSnapshot(db, tenantId, snapshot, now, stamp) {
     const result = db.prepare(`
@@ -95,7 +97,7 @@ export function loadActiveTaskSnapshot(hippoRoot, tenantId, key) {
 }
 /** Default freshness bound for AMBIENT active-task-snapshot reads: 72h rather than 48h so a Friday-evening orphan still offers continuity on Monday;
  * override via `loadFreshActiveTaskSnapshot`'s `opts.maxAgeMs`; deliberately no env knob. */
-export const SNAPSHOT_AMBIENT_MAX_AGE_MS = 72 * 60 * 60 * 1000;
+export const SNAPSHOT_AMBIENT_MAX_AGE_MS = 72 * HOUR_MS;
 /** A usable session id: non-null, non-empty string; named so the owner-match rule in `loadFreshActiveTaskSnapshot` states its contract once. */
 function isNonEmptySessionId(value) {
     return typeof value === 'string' && value.length > 0;

package/dist/store/set-aside.d.ts

@@ -0,0 +1,14 @@
+import type { DatabaseSyncLike } from '../db/index.js';
+import { type MemoryEntry } from '../core/memory.js';
+export declare const SYNC_ACTOR = "agent-memories";
+export type SetAsideWhy = 'note-gone' | 'note-changed' | 'handover' | 'project-merge' | 'project-repair';
+export type SetAsideResult = {
+    readonly kind: 'untagged';
+    readonly entry: MemoryEntry;
+} | {
+    readonly kind: 'dormant';
+    readonly id: string;
+};
+/** Design 6's set-aside on the caller's transaction: a pinned row only loses the tag, any other goes dormant, restorable. */
+export declare function setAsideRow(db: DatabaseSyncLike, tag: string, row: MemoryEntry, why: SetAsideWhy): SetAsideResult;
+//# sourceMappingURL=set-aside.d.ts.map

package/dist/store/set-aside.js

@@ -0,0 +1,23 @@
+// Takes an imported agent note out of recall on the caller's transaction; the note sync and the project repair both use it.
+import { appendAuditEvent } from './audit.js';
+import { insertDormantRow } from './dormant.js';
+import { calculateStrength } from '../core/memory.js';
+import { deleteEntryRowInTx, setEntryTagsInTx } from './entry-writes.js';
+export const SYNC_ACTOR = 'agent-memories';
+/** Design 6's set-aside on the caller's transaction: a pinned row only loses the tag, any other goes dormant, restorable. */
+export function setAsideRow(db, tag, row, why) {
+    const untagged = { ...row, tags: row.tags.filter((t) => t !== tag) };
+    const audit = (metadata) => appendAuditEvent(db, { tenantId: row.tenantId, actor: SYNC_ACTOR, op: 'agent_memory_set_aside', targetId: row.id, metadata });
+    if (row.pinned) {
+        setEntryTagsInTx(db, untagged);
+        audit({ why, untagged: true });
+        return { kind: 'untagged', entry: untagged };
+    }
+    const now = new Date();
+    // Sleep's dormant move skips kept rows, so the steps are written out here without its filter.
+    insertDormantRow(db, { entry: untagged, strength: calculateStrength(row, now), reason: 'source-deleted', dormantAt: now.toISOString() });
+    deleteEntryRowInTx(db, row, SYNC_ACTOR);
+    audit({ why });
+    return { kind: 'dormant', id: row.id };
+}
+//# sourceMappingURL=set-aside.js.map

package/dist/store/sqlite/busy.d.ts

@@ -0,0 +1,3 @@
+/** A held lock in any store: SQLite's busy codes or a port's StoreBusyError. */
+export declare function isStoreBusy<E>(error: E): boolean;
+//# sourceMappingURL=busy.d.ts.map

package/dist/store/sqlite/busy.js

@@ -0,0 +1,8 @@
+// Busy detection lives with the adapter, so the port names no SQLite error code.
+import { isSqliteBusy } from '../../db/busy.js';
+import { StoreBusyError } from '../port.js';
+/** A held lock in any store: SQLite's busy codes or a port's StoreBusyError. */
+export function isStoreBusy(error) {
+    return error instanceof StoreBusyError || isSqliteBusy(error);
+}
+//# sourceMappingURL=busy.js.map

package/dist/store/sqlite/connector-events-group.js

@@ -1,22 +1,19 @@
 // hippo.db's half of the ConnectorEvents store group: each call on a handle of its own.
-import { archiveDeletedArtifact, eventSeenAt, githubRouting, insertGitHubDlq, logEvent, seenEvent } from '../connectors/github.js';
+import { archiveDeletedArtifact, githubEventRecord, githubEventSeenAt, githubRouting, insertGitHubDlq, markGitHubEventSeen } from '../connectors/github.js';
 import { insertSlackDlq, markSlackEventSeen, rawMemoryIdForArtifactAt, slackEventRecord, slackEventSeenAt, slackTeamRoute } from '../connectors/slack.js';
 import { onHandle } from '../open.js';
 function eventRecord(hippoRoot, event) {
-    if (event.connector === 'slack')
-        return slackEventRecord(hippoRoot, event.eventId);
-    const logged = seenEvent(hippoRoot, event.idempotencyKey);
-    return logged ? { seen: true, memoryId: logged.memoryId } : { seen: false };
+    return event.connector === 'slack' ? slackEventRecord(hippoRoot, event.eventId) : githubEventRecord(hippoRoot, event.idempotencyKey);
 }
 function markEventSeen(hippoRoot, event) {
     if (event.connector === 'slack')
         return markSlackEventSeen(hippoRoot, event.eventId, null);
     const { idempotencyKey, deliveryId, eventName } = event;
-    logEvent(hippoRoot, { idempotencyKey, deliveryId, eventName, memoryId: null });
+    markGitHubEventSeen(hippoRoot, { idempotencyKey, deliveryId, eventName, memoryId: null });
 }
 function deletionTarget(hippoRoot, { event, artifactRef, tenantId }) {
     return onHandle(hippoRoot, (db) => {
-        const seen = event.connector === 'slack' ? slackEventSeenAt(db, event.eventId) : eventSeenAt(db, event.idempotencyKey);
+        const seen = event.connector === 'slack' ? slackEventSeenAt(db, event.eventId) : githubEventSeenAt(db, event.idempotencyKey);
         return seen ? { seen: true } : { seen: false, memoryId: rawMemoryIdForArtifactAt(db, artifactRef, tenantId) };
     });
 }

package/dist/store/sqlite/connector-writes-group.js

@@ -1,4 +1,4 @@
-import { eventMemoryAt, logEventAt } from '../connectors/github.js';
+import { githubEventMemoryAt, markGitHubEventSeenAt } from '../connectors/github.js';
 import { markSlackEventSeenAt, slackEventMemoryAt } from '../connectors/slack.js';
 import { stampOriginProject } from '../entry-row.js';
 import { writeEntryMirrors } from '../entry-writes.js';
@@ -13,10 +13,10 @@ function logEvent(db, event, memoryId) {
     if (event.connector === 'slack')
         return markSlackEventSeenAt(db, event.eventId, memoryId);
     const { idempotencyKey, deliveryId, eventName } = event;
-    return logEventAt(db, { idempotencyKey, deliveryId, eventName, memoryId });
+    return markGitHubEventSeenAt(db, { idempotencyKey, deliveryId, eventName, memoryId });
 }
 function loggedMemory(db, event) {
-    return event.connector === 'slack' ? slackEventMemoryAt(db, event.eventId) : eventMemoryAt(db, event.idempotencyKey);
+    return event.connector === 'slack' ? slackEventMemoryAt(db, event.eventId) : githubEventMemoryAt(db, event.idempotencyKey);
 }
 /** The record, then the log row, go in after the memory row and ahead of its remember row, as a second store must order them. */
 function writeWithCompanions(db, { entry, actor, event, quarantine }) {

package/dist/store/sqlite/entry-writes-group.js

@@ -5,9 +5,9 @@ import { isSqliteBusy, withWriteScope } from '../../db/index.js';
 import { errorFields, errorMessage, log } from '../../util/log.js';
 import { entryAfterOutcome } from '../../core/memory.js';
 import { archiveRawMemory } from '../raw-archive.js';
-import { ownScopeTouches } from '../recall-scope.js';
+import { ownScopeTouches } from '../../core/recall-scope.js';
 import { recordTraceOutcome } from '../recall-trace.js';
-import { RejectedValueError } from '../rejection.js';
+import { RejectedValueError } from '../../core/api-errors.js';
 import { markSummaryDirtyInTx } from '../summary-dirty.js';
 import { auditRejectionRefusal } from '../audit-event.js';
 import { deleteEntryCore } from '../delete-and-batch.js';

package/dist/store/sqlite/error-codec.js

@@ -2,11 +2,12 @@
 // of its class: the server's mappers test `instanceof`, `errcode` and fields.
 import { BadRequestError, ConflictError, ForbiddenError, NotFoundError } from '../../core/api-errors.js';
 import { RawAppendOnlyError } from '../../core/raw-append-only.js';
-import { IncompatibleBinaryError, StoreBusyError } from '../../db/index.js';
+import { IncompatibleBinaryError } from '../../db/index.js';
+import { StoreBusyError } from '../port.js';
 import { BodyTimeoutError, BodyTooLargeError, HttpError } from '../../util/http-util.js';
 import { errorMessage, log } from '../../util/log.js';
-import { ScopeForbiddenError } from '../recall-scope.js';
-import { RejectedValueError } from '../rejection.js';
+import { ScopeForbiddenError } from '../../core/recall-scope.js';
+import { RejectedValueError } from '../../core/api-errors.js';
 import { OtherStoreFolderError, SqliteBlockedError, StoreNotPortedError } from '../../util/sqlite-blocked.js';
 // Every class the server maps by, at or below the store layer. Abstract ApiError is absent: only its four subclasses are thrown.
 const CLASSES = [

package/dist/store/sqlite/executor.js

@@ -2,11 +2,12 @@
 import { fileURLToPath } from 'node:url';
 import { SHARE_ENV, Worker } from 'node:worker_threads';
 import { addAuditWriteFailures } from '../audit.js';
-import { getHippoDbPath, SERVER_DB_WAIT_MS, StoreBusyError } from '../../db/index.js';
+import { getHippoDbPath, SERVER_DB_WAIT_MS } from '../../db/index.js';
+import { StoreBusyError } from '../port.js';
 import { autoCheckpointPages } from '../../db/wal-checkpointer.js';
 import { envStoreQueueMax } from '../../util/env.js';
 import { DeadlineExceededError } from '../../util/http-util.js';
-import { errorMessage, log } from '../../util/log.js';
+import { errorFields, errorMessage, log } from '../../util/log.js';
 import { requestScopes } from '../../util/request-scope.js';
 import { decodeError } from './error-codec.js';
 import { workerCounts } from './executor-counts.js';
@@ -27,6 +28,10 @@ const DEFAULT_WRITE_GRACE_MS = 2000;
 function laneOf(mode) {
     return { mode, queue: [], running: undefined, worker: undefined, stopping: undefined, commitFlag: undefined };
 }
+// A thread that will not stop leaves a live worker behind, so the rejection is logged rather than dropped.
+function terminateLogged(worker) {
+    worker.terminate().catch((err) => log.warn('the store worker did not terminate cleanly', errorFields(err)));
+}
 /** Gives `pending`'s caller its one answer; a second call does nothing. */
 function finish(pending, answer) {
     if (pending.answered)
@@ -153,7 +158,7 @@ class WorkerPool {
     #stopReader(lane, worker, pending) {
         finish(pending, () => pending.fail(new DeadlineExceededError(READ_LATE)));
         lane.stopping = worker;
-        void worker.terminate();
+        terminateLogged(worker);
     }
     // Before its commit flag a stopped write is a known rollback; after it the thread is left to finish, since stopping it could not undo the write.
     #stopWriter(lane, worker, pending) {
@@ -195,7 +200,8 @@ class WorkerPool {
         return this.#exits.size;
     }
     terminateWriter() {
-        void this.#writer.worker?.terminate();
+        if (this.#writer.worker)
+            terminateLogged(this.#writer.worker);
     }
     #pump(lane) {
         if (lane.running !== undefined)

package/dist/store/sqlite/graph-reads-group.js

@@ -1,5 +1,5 @@
 // hippo.db's half of the GraphReads store group: one read snapshot around the walk the CLI graph commands run.
-import { canReadScope } from '../recall-scope.js';
+import { canReadScope } from '../../core/recall-scope.js';
 import { withGraphReadSnapshot } from '../graph-reads.js';
 import { graphViewRows } from '../graph-view-rows.js';
 export function sqliteGraphReads(hippoRoot) {

package/dist/store/sqlite/held-connection.d.ts

@@ -0,0 +1,9 @@
+/** What the server calls around its responses to keep its store connection. */
+export interface StoreHolder {
+    hold: () => void;
+    afterResponse: () => void;
+    release: () => Promise<void>;
+}
+/** Holds a connection to the hippo.db under `hippoRoot` once it exists, so serving never creates one. */
+export declare function holdSqliteConnection(hippoRoot: string): StoreHolder;
+//# sourceMappingURL=held-connection.d.ts.map

package/dist/store/sqlite/held-connection.js

@@ -0,0 +1,41 @@
+// A served hippo.db keeps one connection open for the life of the server, beside the worker that checkpoints its WAL.
+import { existsSync } from 'node:fs';
+import { closeHippoDb, getHippoDbPath, openHippoDb, outsideRequestStores, outsideSqliteOffLoop, SERVER_DB_WAIT_MS, } from '../../db/index.js';
+import { startWalCheckpointer } from '../../db/wal-checkpointer.js';
+import { errorMessage, log } from '../../util/log.js';
+/** Holds a connection to the hippo.db under `hippoRoot` once it exists, so serving never creates one. */
+export function holdSqliteConnection(hippoRoot) {
+    // Handlers open and close their own connections; while this one is held, none of those closes is SQLite's last,
+    // which checkpoints and deletes the WAL.
+    let heldDb;
+    let checkpointer;
+    let stopHolding = false;
+    const hold = () => {
+        if (heldDb || stopHolding || !existsSync(getHippoDbPath(hippoRoot)))
+            return;
+        try {
+            // The 'finish' listener can fire inside a request scope (closing this connection with the request) and inside a `loop: 'off'` block (refusing the open).
+            // The server's lock wait: this open runs on the event loop, where SQLite's 5 s default and the 30 s journal-mode retry would stall every request.
+            heldDb = outsideSqliteOffLoop(() => outsideRequestStores(() => openHippoDb(hippoRoot, { busyWaitMs: SERVER_DB_WAIT_MS })));
+            checkpointer = startWalCheckpointer(getHippoDbPath(hippoRoot));
+        }
+        catch (err) {
+            stopHolding = true;
+            log.warn(`serve: could not hold a store connection; requests still work, only slower: ${errorMessage(err)}`);
+        }
+    };
+    const afterResponse = () => {
+        hold();
+        checkpointer?.noteResponse();
+    };
+    const release = async () => {
+        stopHolding = true;
+        // The worker's connection closes first, so the held one is SQLite's last and its close checkpoints and deletes the WAL.
+        await checkpointer?.stop();
+        if (heldDb)
+            closeHippoDb(heldDb);
+        heldDb = undefined;
+    };
+    return { hold, afterResponse, release };
+}
+//# sourceMappingURL=held-connection.js.map

package/dist/store/sqlite/object-rows.d.ts

@@ -1,7 +1,7 @@
 import type { AuditOp } from '../audit.js';
 import type { JsonObject } from '../working-memory.js';
 import type { SourceObjectType } from '../graph-rows.js';
-import type { BriefStatus, DecisionStatus, IncidentStatus, NoteStatus, ObjectByKind, ObjectFields, ObjectKind, PolicyStatus, ProcessStatus, SavableKind, SkillStatus } from '../object-types.js';
+import type { BriefStatus, DecisionStatus, IncidentStatus, NoteStatus, ObjectByKind, ObjectFields, ObjectKind, PolicyStatus, ProcessStatus, SavableKind, SkillStatus } from '../../core/object-types.js';
 interface HeadRow {
     id: number;
     memory_id: string | null;

package/dist/store/sqlite/objects-group.d.ts

@@ -1,4 +1,4 @@
-import type { BriefReceipt, Incident, ObjectByKind, ObjectKind, Policy, SavableKind, Skill } from '../object-types.js';
+import type { BriefReceipt, Incident, ObjectByKind, ObjectKind, Policy, SavableKind, Skill } from '../../core/object-types.js';
 import { type IncidentOpen, type IncidentOpenRefusal, type IncidentResolve, type ObjectClose, type ObjectListQuery, type ObjectRefusal, type Objects, type ObjectSave, type PoliciesInForceQuery } from '../port.js';
 /** The group with each answer as its value; spelled out because `Sync<Objects>` would widen each method's kind to every kind. */
 export interface SyncObjects {

package/dist/store/sqlite/objects-group.js

@@ -4,7 +4,7 @@ import { getMeta, withWriteScopeOr } from '../../db/index.js';
 import { escapeLike } from '../../util/escape.js';
 import { keysetAfter } from '../../util/keyset.js';
 import { calculateStrength, deriveHalfLife } from '../../core/memory.js';
-import { scopeAdmitSql } from '../recall-scope.js';
+import { scopeAdmitSql } from '../rule-sql.js';
 import { stampOriginProject, upsertEntryRow } from '../entry-row.js';
 import { auditEntryWrite, writeEntryMirrors } from '../entry-writes.js';
 import { markGraphDirty } from '../graph-queue.js';

package/dist/store/sqlite/store.js

@@ -277,18 +277,20 @@ function continuityAt(hippoRoot, tenantId, eventLimit, key) {
 /** sqliteStore's finishRecall, for the synchronous recall that cannot await the port. */
 export function finishRecallAt(hippoRoot, writes) {
     return onHandle(hippoRoot, (db) => {
-        // With no row to write the scope would only take the write lock.
-        if (writes.goalLog.length > 0 || writes.audit.length > 0) {
-            withWriteScope(db, 'finish_recall', () => {
-                writeGoalRecallLog(db, localGoalRecallRows(db, writes.goalLog));
-                for (const event of writes.audit)
-                    appendAuditEvent(db, event);
-            });
-        }
-        // Each opens its own transaction, so neither can share the scope above.
-        const traceId = writes.trace ? writeRecallTrace(db, writes.trace) : null;
-        const strengthened = writes.strengthen ? strengthenRetrievedInOwnTx(db, writes.strengthen.ids, writes.strengthen.opts) : new Set();
-        return { traceId, strengthened };
+        const traceAndStrengthen = () => ({
+            traceId: writes.trace ? writeRecallTrace(db, writes.trace) : null,
+            strengthened: writes.strengthen ? strengthenRetrievedInOwnTx(db, writes.strengthen.ids, writes.strengthen.opts) : new Set(),
+        });
+        // Alone, the fail-soft trace and strengthen keep their own scopes so a busy lock loses them, never the read.
+        if (writes.goalLog.length === 0 && writes.audit.length === 0)
+            return traceAndStrengthen();
+        // Inside this scope both run as savepoints, so one recall commits once and a failed trace or strengthen still unwinds alone.
+        return withWriteScope(db, 'finish_recall', () => {
+            writeGoalRecallLog(db, localGoalRecallRows(db, writes.goalLog));
+            for (const event of writes.audit)
+                appendAuditEvent(db, event);
+            return traceAndStrengthen();
+        });
     });
 }
 //# sourceMappingURL=store.js.map

package/dist/store/summaries.d.ts

@@ -2,9 +2,9 @@ import type { MemoryEntry } from '../core/memory.js';
 /** Host-wide loader for L2 topic summaries without an L3 parent, for consolidate phase 1.9 (buildEntityProfiles); SQL-level filter, since in-memory
  * `survivors` lacks L2s created by phase 1.7. Entries carry tenantId so per-cluster writes stay tenant-scoped. */
 export declare function loadAllL2Summaries(hippoRoot: string): MemoryEntry[];
-/** Dirty summaries across all tenants in one query, newest change first (latest_at DESC NULLS LAST, id ASC) so HIPPO_DAG_REBUILD_CAP takes the most
- * recently changed. Each entry carries its own tenantId so the children read and rebuild UPDATE stay tenant-scoped. */
-export declare function loadAllDirtySummaries(hippoRoot: string): MemoryEntry[];
+/** Dirty summaries across all tenants, newest change first (latest_at DESC NULLS LAST, id ASC), at most `limit` (all when omitted)
+ * so HIPPO_DAG_REBUILD_CAP reads only the most recently changed. Each entry carries its tenantId so later writes stay tenant-scoped. */
+export declare function loadAllDirtySummaries(hippoRoot: string, limit?: number): MemoryEntry[];
 /** Live (non-archived) children of a DAG summary, so a rebuild regenerates from the CURRENT child set; tenant-scoped as defence in depth. */
 export declare function loadChildrenOfSummary(hippoRoot: string, summaryId: string, tenantId: string): MemoryEntry[];
 /** Patch applied by applyRebuildResult; `bumpRebuildCount` is false for the zero-child case, true for a normal rebuild. */

package/dist/store/summaries.js

@@ -27,9 +27,9 @@ export function loadAllL2Summaries(hippoRoot) {
         return rows.map(rowToEntry);
     }, openStore);
 }
-/** Dirty summaries across all tenants in one query, newest change first (latest_at DESC NULLS LAST, id ASC) so HIPPO_DAG_REBUILD_CAP takes the most
- * recently changed. Each entry carries its own tenantId so the children read and rebuild UPDATE stay tenant-scoped. */
-export function loadAllDirtySummaries(hippoRoot) {
+/** Dirty summaries across all tenants, newest change first (latest_at DESC NULLS LAST, id ASC), at most `limit` (all when omitted)
+ * so HIPPO_DAG_REBUILD_CAP reads only the most recently changed. Each entry carries its tenantId so later writes stay tenant-scoped. */
+export function loadAllDirtySummaries(hippoRoot, limit) {
     return onHandle(hippoRoot, (db) => {
         // SAFETY: this query selects exactly MEMORY_SELECT_COLUMNS, matching
         // MemoryRow's field set.
@@ -39,7 +39,8 @@ export function loadAllDirtySummaries(hippoRoot) {
        WHERE summary_dirty = 1
          AND kind != 'archived'
        ORDER BY latest_at DESC NULLS LAST, id ASC
-    `).all();
+       LIMIT ?
+    `).all(limit ?? -1);
         return rows.map(rowToEntry);
     }, openStore);
 }

package/dist/store/token-ledger.d.ts

@@ -82,13 +82,6 @@ interface ModelTagged {
 }
 /** Claude Code writes its own API errors and limit notices as assistant lines from this model; no model call made them. */
 export declare function isSyntheticMessage(message: ModelTagged): boolean;
-/** A hook payload's non-empty `session_id`, or null; with `requiredSource`, also null when its `source` differs. */
-export declare function hookPayloadSessionId(stdinText: string | undefined, requiredSource?: string | null): string | null;
-/** A hook payload's string `field` as sent, or null when the payload or the field is missing or not a string. */
-export declare function hookPayloadString(stdinText: string | undefined, field: string): string | null;
-/** Whether a hook fired inside a sub-agent, the only payload with `agent_id` (https://code.claude.com/docs/en/hooks#common-input-fields).
- *  Its `session_id` is the parent's, so a sub-agent's blocks and compactions must not count as the parent's. */
-export declare function isSubagentPayload(stdinText: string | undefined): boolean;
 /** Tokens hippo sent and skipped in one session, for {@link tokensBySession}. */
 export interface SessionTokens {
     sessionId: string;

package/dist/store/token-ledger.js

@@ -90,41 +90,6 @@ export function summarizeTokenUse(db, tenantId, sinceIso) {
 export function isSyntheticMessage(message) {
     return message.model === '<synthetic>';
 }
-/** A Claude Code hook payload on stdin as a JSON object; null when empty, malformed or not an object. */
-function parseHookPayload(stdinText) {
-    if (!stdinText || stdinText.trim() === '')
-        return null;
-    try {
-        // SAFETY: JSON.parse returns a JSON value by definition.
-        const payload = JSON.parse(stdinText.trim());
-        return isJsonObjectLiteral(payload) ? payload : null;
-    }
-    catch {
-        // Malformed is one of the null cases the docblock names.
-        return null;
-    }
-}
-/** A hook payload's non-empty `session_id`, or null; with `requiredSource`, also null when its `source` differs. */
-export function hookPayloadSessionId(stdinText, requiredSource = null) {
-    const payload = parseHookPayload(stdinText);
-    const sessionId = payload?.session_id;
-    if (!payload || !isJsonString(sessionId) || sessionId.trim() === '')
-        return null;
-    if (requiredSource !== null && payload.source !== requiredSource)
-        return null;
-    return sessionId;
-}
-/** A hook payload's string `field` as sent, or null when the payload or the field is missing or not a string. */
-export function hookPayloadString(stdinText, field) {
-    const value = parseHookPayload(stdinText)?.[field];
-    return isJsonString(value) ? value : null;
-}
-/** Whether a hook fired inside a sub-agent, the only payload with `agent_id` (https://code.claude.com/docs/en/hooks#common-input-fields).
- *  Its `session_id` is the parent's, so a sub-agent's blocks and compactions must not count as the parent's. */
-export function isSubagentPayload(stdinText) {
-    const agentId = parseHookPayload(stdinText)?.agent_id;
-    return isJsonString(agentId) && agentId.trim() !== '';
-}
 /** Ledger totals per session id since `sinceIso`, across surfaces; hook rows carry the host's session id (the transcript file name), so they join to its
  * usage records. */
 export function tokensBySession(db, tenantId, sinceIso) {

package/dist/store/vector-index.js

@@ -1,10 +1,11 @@
 // Owns hippo.db's stored vectors, the identity of the model that built them, and the particle rows: every read and write of the three.
 import { getMeta, setMeta, withWriteScope } from '../db/index.js';
 import { onHandle } from './open.js';
-import { DEFAULT_EMBEDDING_MODEL } from './embeddings/local.js';
+import { DEFAULT_EMBEDDING_MODEL } from '../embeddings/local.js';
 import { float32ToBuffer, initializeParticle, loadPhysicsState, resetAllPhysicsState, savePhysicsState } from '../db/physics-state.js';
 import { EMBEDDING_MODEL_META_KEY, deleteOrphanVectors, hasStoredVectors, loadVectors, loadVectorViews, replaceAllVectors, storedVectorDims, storedVectorIds, upsertVectors, } from '../db/vector-store.js';
-import { chunked, selectEntriesByIds } from './entry-reads.js';
+import { selectEntriesByIds } from './entry-reads.js';
+import { chunked } from '../util/chunked.js';
 import { MEMORY_SELECT_COLUMNS, rowToEntry } from './rows.js';
 const MAX_BACKFILL_PAGE = 500;
 /** The model the index was built by: the stored identity, else the default model when vectors exist. */

package/dist/support-bundle.js

@@ -5,10 +5,9 @@ import * as fs from 'fs';
 import * as os from 'os';
 import * as path from 'path';
 import { pathToFileURL } from 'url';
-import { findHippoStoreDir, isGlobalStoreRoot } from './core/project-identity.js';
+import { findHippoStoreDir, isGlobalStoreRoot, isInitialized } from './core/project-identity.js';
 import { realpathOrResolve } from './util/real-path.js';
 import { getGlobalRoot } from './sharing/global-store.js';
-import { isInitialized } from './store/open.js';
 import { readStoreInventory } from './store/diagnostics.js';
 import { runDoctor } from './doctor.js';
 import { loadConfig } from './core/config.js';
@@ -21,7 +20,7 @@ export const TAIL_MAX_LINES = 200;
 const TAIL_MAX_LINE_CHARS = 2000;
 // Greedy on purpose: complete key blocks are redacted first, so any END left is an orphan and what precedes it may be key body.
 const ORPHAN_KEY_END_RE = /^[\s\S]*-----END [A-Z ]*PRIVATE KEY-----/;
-// The other env vars hippo reads outside the HIPPO_ prefix (src/store/embeddings/provider.ts, connectors/*).
+// The other env vars hippo reads outside the HIPPO_ prefix (src/embeddings/provider.ts, connectors/*).
 const OTHER_ENV_NAMES = [
     'ANTHROPIC_API_KEY', 'OPENAI_API_KEY', 'VOYAGE_API_KEY', 'COHERE_API_KEY', 'TYPESAFE_API_KEY',
     'GITHUB_TOKEN', 'GITHUB_WEBHOOK_SECRET', 'GITHUB_WEBHOOK_SECRET_PREVIOUS',

package/dist/trust/reject-flow.js

@@ -1,8 +1,8 @@
 // The reject, unreject and list flow the CLI verbs and the api functions share: the rules and their wording live here,
 // and src/store/rejected-values.ts runs each one on a single handle.
 import { BadRequestError } from '../core/api-errors.js';
-import { isPersonalScope } from '../store/recall-scope.js';
-import { mergedSuccessor } from '../consolidate/merged-row.js';
+import { isPersonalScope } from '../core/recall-scope.js';
+import { mergedSuccessor } from '../core/merged-row.js';
 import { normalizeValueForRejection } from '../store/rejection.js';
 import { applyRejection, liftRejection, loadRejectedValues, } from '../store/rejected-values.js';
 function assertRejectOpts(opts) {

package/dist/util/agent-homes.d.ts

@@ -0,0 +1,15 @@
+type Env = Readonly<Record<string, string | undefined>>;
+export declare function homeDir(): string;
+/** Codex's config folder: $CODEX_HOME, else ~/.codex, as the Codex hooks docs describe. */
+export declare function codexHomeDir(home?: string, env?: Env): string;
+/** Claude Code's config folder, where it reads settings.json: $CLAUDE_CONFIG_DIR when set and non-empty, else
+ * ~/.claude under os.homedir(), as Claude Code does (a HOME that differs from the profile must not move it). */
+export declare function claudeConfigDir(home?: string, env?: Env): string;
+/** VS Code's user-data resolution: portable install first, then the app-data override, then the platform default. */
+export declare function vscodeDataFolders(ctx: {
+    readonly env: Env;
+    readonly home: string;
+    readonly platform: NodeJS.Platform;
+}): string[];
+export {};
+//# sourceMappingURL=agent-homes.d.ts.map

package/dist/util/agent-homes.js

@@ -0,0 +1,34 @@
+// Where the agent tools keep their config and data, shared by the hook installers and the agent-memory readers.
+import * as os from 'os';
+import * as path from 'path';
+import { envHomeDir, processEnv } from './env.js';
+const VSCODE_PRODUCTS = ['Code', 'Code - Insiders'];
+export function homeDir() {
+    return envHomeDir() || os.homedir();
+}
+/** Codex's config folder: $CODEX_HOME, else ~/.codex, as the Codex hooks docs describe. */
+export function codexHomeDir(home = homeDir(), env = processEnv()) {
+    return env.CODEX_HOME || path.join(home, '.codex');
+}
+/** Claude Code's config folder, where it reads settings.json: $CLAUDE_CONFIG_DIR when set and non-empty, else
+ * ~/.claude under os.homedir(), as Claude Code does (a HOME that differs from the profile must not move it). */
+export function claudeConfigDir(home = os.homedir(), env = processEnv()) {
+    return env.CLAUDE_CONFIG_DIR || path.join(home, '.claude');
+}
+/** VS Code's user-data resolution: portable install first, then the app-data override, then the platform default. */
+export function vscodeDataFolders(ctx) {
+    const { env, home, platform } = ctx;
+    if (env.VSCODE_PORTABLE)
+        return [path.join(env.VSCODE_PORTABLE, 'user-data')];
+    let appData;
+    if (env.VSCODE_APPDATA)
+        appData = env.VSCODE_APPDATA;
+    else if (platform === 'win32')
+        appData = env.APPDATA || path.join(home, 'AppData', 'Roaming');
+    else if (platform === 'darwin')
+        appData = path.join(home, 'Library', 'Application Support');
+    else
+        appData = env.XDG_CONFIG_HOME || path.join(home, '.config');
+    return VSCODE_PRODUCTS.map((product) => path.join(appData, product));
+}
+//# sourceMappingURL=agent-homes.js.map

package/dist/util/anthropic-messages.d.ts

@@ -13,6 +13,7 @@ export type AnthropicMessageFailure = {
 } | {
     kind: 'http';
     status: number;
+    detail: string;
 } | {
     kind: 'unreadable';
     message: string;
@@ -24,6 +25,8 @@ export type AnthropicMessageResult = {
     ok: false;
     failure: AnthropicMessageFailure;
 };
+/** True for a failure the next call would repeat, so a caller looping over items should stop rather than retry. */
+export declare function isPermanentFailure(failure: AnthropicMessageFailure): boolean;
 /** The reply's first text block, trimmed (empty when the reply has none); never throws. */
 export declare function sendAnthropicMessage(req: AnthropicMessageRequest): Promise<AnthropicMessageResult>;
 /** The text extraction and DAG summaries hand to their `onError` callback. */