hippo-memory 1.70.0 → 1.72.0

package/dist/core/project-identity.js

@@ -4,7 +4,7 @@ import * as os from 'os';
 import * as path from 'path';
 import { BadRequestError } from './api-errors.js';
 import { isSharedStore, loadConfig } from './config.js';
-import { MAX_ID_LEN } from '../util/http-util.js';
+import { MAX_ID_LEN } from '../util/limits.js';
 import { errorMessage, log } from '../util/log.js';
 import { originRemoteId, projectFileId } from './project-remote.js';
 import { realpathOrResolve } from '../util/real-path.js';
@@ -23,7 +23,8 @@ function remoteRuleOn() {
         remoteSwitch = { globalRoot, on: loadConfig(globalRoot).projectIdentity.remote };
     return remoteSwitch.on;
 }
-/** The id a root names itself by plus every rung that resolves; only the root's own `.git` is read, so a store nested in another checkout keeps its folder name. */
+/** The id a root names itself by plus every rung that resolves; only the root's own
+ * `.git` is read, so a store nested in another checkout keeps its folder name. */
 function namesAt(root, legacyName) {
     const fileId = projectFileId(root);
     const remoteId = originRemoteId(root);
@@ -48,9 +49,8 @@ function isUnder(child, parent) {
     }
     return false;
 }
-/** A `.hippo` marker must be a DIRECTORY (a store) - a stray file named
- *  `.hippo` must not turn its parent into a project. `.git` stays existsSync
- *  because worktrees legitimately use a `.git` FILE. */
+/** A `.hippo` marker must be a DIRECTORY (a store), so a stray file named `.hippo` cannot make its parent a project;
+ *  `.git` stays existsSync because worktrees use a `.git` FILE. */
 function isDirectoryAt(p) {
     try {
         return fs.statSync(p).isDirectory();
@@ -60,10 +60,7 @@ function isDirectoryAt(p) {
         return false;
     }
 }
-/**
- * Resolve the project identity for a working directory.
- * Defaults to process.cwd(). Results are cached per resolved input path.
- */
+/** Resolves the project identity for a working directory (default process.cwd()); results are cached per resolved input path. */
 export function resolveProjectIdentity(cwd, opts) {
     const startInput = path.resolve(cwd ?? process.cwd());
     const cacheable = !opts?.homeDir && !opts?.stopDir;
@@ -96,7 +93,8 @@ export function resolveProjectIdentity(cwd, opts) {
         identityCache.set(startInput, identity);
     return identity;
 }
-/** The repo name a linked worktree shares with its main checkout (`repo.git` or `repo/.bare` for a bare repo), so one repo is one project; null for any other checkout. */
+/** The repo name a linked worktree shares with its main checkout (`repo.git` or
+ * `repo/.bare` for a bare repo), so one repo is one project; null for any other checkout. */
 function linkedWorktreeRepoName(gitRoot, home) {
     const marker = path.join(gitRoot, '.git');
     if (!fs.existsSync(marker) || isDirectoryAt(marker))
@@ -156,6 +154,15 @@ export function findHippoStoreDir(cwd, opts) {
     const { hippoRoot } = walkProjectMarkers(start, home, stops);
     return hippoRoot === null ? null : path.join(hippoRoot, '.hippo');
 }
+/** Nearest ancestor store like git; the strict join is the fallback so `hippo init` still creates `<cwd>/.hippo`. */
+export function getHippoRoot(cwd = process.cwd(), opts) {
+    return findHippoStoreDir(cwd, opts) ?? path.join(realpathOrResolve(cwd), '.hippo');
+}
+export function isInitialized(hippoRoot) {
+    // autoInstallHooks / setupDailySchedule can create a bare .hippo with no hippo.db; counting
+    // that as initialized makes `hippo init` skip initStore, so only hippo.db counts.
+    return fs.existsSync(path.join(hippoRoot, 'hippo.db'));
+}
 function isBareName(project) {
     return typeof project === 'string';
 }
@@ -172,7 +179,8 @@ export function projectNames(project) {
 // Each project name is matched against every candidate row, so the caller's list stays short.
 export const MAX_PROJECT_ALIASES = 10;
 export const MCP_PROJECT_SCOPED_HEADER = 'X-Hippo-Project-Scoped';
-/** Refuses a caller's project that is blank (it would stamp user-global), past the caps, or unlike the resolver's ids: rows match verbatim, so a rewrite would split a project. Inner spaces pass, since a checkout with no remote is named by its folder. */
+/** Refuses a caller's project that is blank (it would stamp user-global), past the caps, or unlike the resolver's ids: rows match
+ * verbatim, so a rewrite would split a project. Inner spaces pass, since a checkout with no remote is named by its folder. */
 export function assertCallerProject(project) {
     const { name, aliases = [] } = project;
     if (name.trim() === '')
@@ -190,14 +198,8 @@ export function assertCallerProject(project) {
 export function originInSql(names, column = 'origin_project') {
     return names.length === 0 ? '0' : `${column} IN (${names.map(() => '?').join(', ')})`;
 }
-/**
- * v39 memory scope isolation: classify a memory's origin_project against the
- * active project. An empty current id means the session is not in a project
- * (home dir or markerless cwd) - everything is in scope there, matching
- * pre-isolation behavior. NULL/undefined origin means no known project (a legacy
- * row, or a shared-store write that named none) and is treated as cross-project
- * (deny by default) - the safe direction for a security partition.
- */
+/** Classifies a memory's origin_project against the active project. An empty current id (home or markerless cwd) puts everything in scope;
+ * NULL/undefined origin (legacy row, or a shared-store write naming none) counts as cross-project: deny by default for a security partition. */
 export function classifyOriginProject(origin, current) {
     if (projectId(current) === '')
         return 'project';
@@ -207,12 +209,8 @@ export function classifyOriginProject(origin, current) {
         return 'user-global';
     return projectNames(current).includes(origin) ? 'project' : 'cross-project';
 }
-/**
- * The global Hippo store directory, resolved the same way shared.ts does:
- * $HIPPO_HOME > $XDG_DATA_HOME/hippo > ~/.hippo. Lives here (leaf module) so
- * db.ts migrations can use it without importing shared.ts (store.ts cycle);
- * shared.getGlobalRoot delegates to this.
- */
+/** The global Hippo store directory ($HIPPO_HOME > $XDG_DATA_HOME/hippo > ~/.hippo); getGlobalRoot (sharing/global-store.ts) returns it.
+ * Leaf module so store migrations can use it without importing sharing/ (store cycle). */
 export function resolveGlobalRootDir() {
     const hippoHome = envHippoHome();
     if (hippoHome)
@@ -222,23 +220,13 @@ export function resolveGlobalRootDir() {
         return path.join(xdgData, 'hippo');
     return path.join(os.homedir(), '.hippo');
 }
-/**
- * True when `p` IS the global store root. Used by the v39 migration so a
- * global store whose parent chain happens to contain `.git`/`.hippo`
- * (git-managed HIPPO_HOME, dotfiles setups) still backfills as user-global
- * ('') instead of being stamped with the surrounding repo's name - which
- * would hide the user's entire global corpus from every project.
- */
+/** True when `p` IS the global store root, so a global store whose parent chain contains `.git`/`.hippo` (git-managed HIPPO_HOME) still backfills as
+ * user-global ('') instead of being stamped with the surrounding repo's name, which would hide the global corpus from every project. */
 export function isGlobalStoreRoot(p) {
     return samePath(realpathOrResolve(path.resolve(p)), realpathOrResolve(resolveGlobalRootDir()));
 }
-/**
- * Parse a memory's origin from its provenance `source` string, mirroring the
- * v39 migration's evidence rules: `shared:<project>:<ts>` and
- * `promoted:<localRoot>` identify the owning project; the user home dir's
- * basename maps to '' (user-global). Returns null when the source carries no
- * origin evidence. Pure string logic - recorded paths may no longer exist.
- */
+/** Parses a memory's origin from its provenance `source`: `shared:<project>:<ts>` and `promoted:<localRoot>` name the owning project; the home dir basename
+ * maps to '' (user-global). Returns null without origin evidence. Pure string logic, since recorded paths may no longer exist. */
 export function originFromSource(source, homeName) {
     if (!source)
         return null;

package/dist/core/project-remote.js

@@ -7,9 +7,10 @@ import { errorMessage, log } from '../util/log.js';
 export function gitConfigPath(gitRoot) {
     const marker = path.join(gitRoot, '.git');
     try {
-        if (fs.statSync(marker).isDirectory())
+        const pointer = gitFilePointer(marker);
+        if (pointer === null)
             return path.join(marker, 'config');
-        const gitDir = /^gitdir:\s*(.+)$/m.exec(fs.readFileSync(marker, 'utf8'))?.[1]?.trim();
+        const gitDir = /^gitdir:\s*(.+)$/m.exec(pointer)?.[1]?.trim();
         if (!gitDir)
             return null;
         const linkDir = path.resolve(gitRoot, gitDir);
@@ -23,6 +24,16 @@ export function gitConfigPath(gitRoot) {
         return null;
     }
 }
+/** The text of a `.git` file, or null when `.git` is a folder; one descriptor answers both, so the path cannot change in between. */
+function gitFilePointer(marker) {
+    const fd = fs.openSync(marker, 'r');
+    try {
+        return fs.fstatSync(fd).isDirectory() ? null : fs.readFileSync(fd, 'utf8');
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+}
 /** One config value with git's quoting: `"` toggles quoting, backslash escapes, and an unquoted `#` or `;` starts a comment. */
 function configValue(raw) {
     let out = '';

package/dist/core/raw-append-only.d.ts

@@ -0,0 +1,5 @@
+/** The refusal a delete of a raw row gets; a plain Error subclass, so it joins no HTTP status family. */
+export declare class RawAppendOnlyError extends Error {
+    constructor(cause: Error);
+}
+//# sourceMappingURL=raw-append-only.d.ts.map

package/dist/core/raw-append-only.js

@@ -0,0 +1,7 @@
+/** The refusal a delete of a raw row gets; a plain Error subclass, so it joins no HTTP status family. */
+export class RawAppendOnlyError extends Error {
+    constructor(cause) {
+        super('raw is append-only', { cause });
+    }
+}
+//# sourceMappingURL=raw-append-only.js.map

package/dist/core/recall-scope.d.ts

@@ -0,0 +1,69 @@
+/** Recall-side scope predicates, in a leaf module so search-both.ts can apply the same default-deny rule to searchBothHybrid's candidate loads without an
+ * import cycle. src/api/index.ts imports these and re-exports them for back-compat (`api.isPrivateScope`, tests importing `passesScopeFilterForRecall`). */
+import { ForbiddenError } from './api-errors.js';
+/** Literal scopes excluded from recall by default-deny when the caller passes no `scope`; read by the SQL clause in `loadSearchRows` and by
+ * `passesScopeFilterForRecall`. Invariant: never empty, or quarantine scopes would pass both paths silently (the module-load assertion below pins this). */
+export declare const RECALL_DEFAULT_DENY_SCOPES: readonly ["unknown:legacy"];
+/** @internal Runtime guard against blanking a load-bearing literal array; `as const` arrays widen via `readonly T[]` at the call site, so the empty case
+ * is reachable and testable. */
+export declare function assertNonEmpty<T>(arr: readonly T[], name: string): void;
+/** Source-agnostic private-scope detector: private means `<lowercase-source>:private:<rest>` (`slack:private:Cabc`; not `slack:public:x`, null, '',
+ * 'private:foo'). The single source of truth for api.recall, the MCP server, the CLI and search-both.ts, so connector work cannot drift. */
+export declare const PRIVATE_SCOPE_RE: RegExp;
+/** True when `scope` matches the `<source>:private:*` shape. */
+export declare function isPrivateScope(scope: string | null | undefined): boolean;
+export declare const PERSONAL_SCOPE_PREFIX = "personal:private:";
+export declare const PERSONAL_OWNER_MAX: number;
+/** True for a `personal:private:<owner>` scope, any case, so a case variant is never mistaken for a team scope. */
+export declare function isPersonalScope(scope: string | null | undefined): boolean;
+/** The caller's own personal scope, or null when it has no owner that can hold one. */
+export declare function personalScopeOf(actor: {
+    owner?: string;
+} | undefined): string | null;
+/** Refuses a client-sent `personal:` scope: only the server stamps one, from the caller's owner. */
+export declare function assertClientScope(scope: string | null | undefined): void;
+/** True when `actor` may change or delete a row in `scope`: any non-personal scope, or its own personal one. */
+export declare function canTouchScope(actor: {
+    owner?: string;
+}, scope: string | null): boolean;
+/** canTouchScope for a caller known by its own personal scope, as a store method receives it. */
+export declare function ownScopeTouches(ownScope: string | null, scope: string | null): boolean;
+/** JS half of the recall default-deny rule (SQL half: `loadSearchRows`). A non-empty `requested` needs an exact match;
+ * otherwise `<source>:private:*` and `RECALL_DEFAULT_DENY_SCOPES` buckets are denied, while null, public scopes and the caller's `ownScope` pass. */
+export declare function passesScopeFilterForRecall(scope: string | null, requested: string | undefined, ownScope?: string | null): boolean;
+/** CLI `--scope` variant: an explicit `--scope X` UNLOCKS scope X on top of the default-admitted set rather than narrowing to X (api.recall keeps 'exact').
+ * Includes private/quarantine scopes (owner access); a named personal scope never unlocks: the CLI has no caller identity. */
+export declare function passesCliRecallScopeFilter(scope: string | null, requested: string | undefined): boolean;
+/** Thrown when a caller requests a scope its role may not read; the HTTP layer maps it to 403. */
+export declare class ScopeForbiddenError extends ForbiddenError {
+    readonly scope: string;
+    constructor(scope: string);
+}
+/** True for scopes default-deny hides (`<source>:private:*` and the quarantine buckets); naming one explicitly unlocks it, so naming one needs
+ * authorization. */
+export declare function isRestrictedScope(scope: string | null | undefined): boolean;
+/** The identity a scope check runs against: a role, any scope grants, and the person who owns the key. */
+export interface ScopeActor {
+    role: 'admin' | 'member';
+    scopes?: readonly string[];
+    owner?: string;
+}
+/** Personal rows answer to their owner alone: role, key grants and resolver scopes never
+ * open one. Else admin reads all; a member needs an exact grant on a restricted scope. */
+export declare function canReadScope(actor: ScopeActor, scope: string): boolean;
+/** Authorize an explicitly requested scope before any read honours it (member scope grants). */
+export declare function assertScopeRequestAllowed(actor: ScopeActor, requested: string | undefined): void;
+/** Scope a derived row keeps from one source: the restricted scope itself, else null. */
+export declare function derivationScope(scope: string | null | undefined): string | null;
+/** The one derivation scope shared by every source, or `{ ok: false }` when
+ *  two disagree, so the caller skips the derived row instead of under-scoping it. */
+export declare function commonDerivationScope(scopes: readonly (string | null | undefined)[]): {
+    ok: true;
+    scope: string | null;
+} | {
+    ok: false;
+};
+/** Map-partition key for consolidate/dag/dedup producers: tenant + derivation scope + origin project,
+ *  so a derived row never blends two restricted scopes, a mixed pair, or two projects. */
+export declare function derivationPartitionKey(tenantId: string, scope: string | null | undefined, origin: string | null | undefined): string;
+//# sourceMappingURL=recall-scope.d.ts.map

package/dist/core/recall-scope.js

@@ -0,0 +1,138 @@
+/** Recall-side scope predicates, in a leaf module so search-both.ts can apply the same default-deny rule to searchBothHybrid's candidate loads without an
+ * import cycle. src/api/index.ts imports these and re-exports them for back-compat (`api.isPrivateScope`, tests importing `passesScopeFilterForRecall`). */
+import { BadRequestError, ForbiddenError } from './api-errors.js';
+import { MAX_ID_LEN } from '../util/limits.js';
+/** Literal scopes excluded from recall by default-deny when the caller passes no `scope`; read by the SQL clause in `loadSearchRows` and by
+ * `passesScopeFilterForRecall`. Invariant: never empty, or quarantine scopes would pass both paths silently (the module-load assertion below pins this). */
+export const RECALL_DEFAULT_DENY_SCOPES = ['unknown:legacy'];
+/** @internal Runtime guard against blanking a load-bearing literal array; `as const` arrays widen via `readonly T[]` at the call site, so the empty case
+ * is reachable and testable. */
+export function assertNonEmpty(arr, name) {
+    if (arr.length === 0) {
+        throw new Error(`${name} cannot be empty — would silently allow quarantine scopes`);
+    }
+}
+assertNonEmpty(RECALL_DEFAULT_DENY_SCOPES, 'RECALL_DEFAULT_DENY_SCOPES');
+/** Source-agnostic private-scope detector: private means `<lowercase-source>:private:<rest>` (`slack:private:Cabc`; not `slack:public:x`, null, '',
+ * 'private:foo'). The single source of truth for api.recall, the MCP server, the CLI and search-both.ts, so connector work cannot drift. */
+export const PRIVATE_SCOPE_RE = /^[a-z][a-z0-9_-]*:private:/;
+function isScopeString(value) {
+    return typeof value === 'string';
+}
+/** True when `scope` matches the `<source>:private:*` shape. */
+export function isPrivateScope(scope) {
+    if (!isScopeString(scope))
+        return false;
+    return PRIVATE_SCOPE_RE.test(scope);
+}
+export const PERSONAL_SCOPE_PREFIX = 'personal:private:';
+// The scope must fit the 256-character scope caps, so the owner gets what the prefix leaves.
+export const PERSONAL_OWNER_MAX = MAX_ID_LEN - PERSONAL_SCOPE_PREFIX.length;
+/** True for a `personal:private:<owner>` scope, any case, so a case variant is never mistaken for a team scope. */
+export function isPersonalScope(scope) {
+    if (!isScopeString(scope))
+        return false;
+    return /^personal:private:/i.test(scope);
+}
+/** The caller's own personal scope, or null when it has no owner that can hold one. */
+export function personalScopeOf(actor) {
+    const owner = actor?.owner;
+    if (!owner || owner.length > PERSONAL_OWNER_MAX || /\p{Cc}/u.test(owner))
+        return null;
+    return `${PERSONAL_SCOPE_PREFIX}${owner}`;
+}
+/** Refuses a client-sent `personal:` scope: only the server stamps one, from the caller's owner. */
+export function assertClientScope(scope) {
+    if (isScopeString(scope) && /^personal:/i.test(scope)) {
+        throw new BadRequestError(`scope ${scope} is reserved: the server sets personal scopes itself`);
+    }
+}
+/** True when `actor` may change or delete a row in `scope`: any non-personal scope, or its own personal one. */
+export function canTouchScope(actor, scope) {
+    return ownScopeTouches(personalScopeOf(actor), scope);
+}
+/** canTouchScope for a caller known by its own personal scope, as a store method receives it. */
+export function ownScopeTouches(ownScope, scope) {
+    return !isPersonalScope(scope) || scope === ownScope;
+}
+/** JS half of the recall default-deny rule (SQL half: `loadSearchRows`). A non-empty `requested` needs an exact match;
+ * otherwise `<source>:private:*` and `RECALL_DEFAULT_DENY_SCOPES` buckets are denied, while null, public scopes and the caller's `ownScope` pass. */
+export function passesScopeFilterForRecall(scope, requested, ownScope) {
+    if (requested !== undefined && requested !== '') {
+        return scope === requested;
+    }
+    return !isRestrictedScope(scope) || (ownScope != null && scope === ownScope);
+}
+/** CLI `--scope` variant: an explicit `--scope X` UNLOCKS scope X on top of the default-admitted set rather than narrowing to X (api.recall keeps 'exact').
+ * Includes private/quarantine scopes (owner access); a named personal scope never unlocks: the CLI has no caller identity. */
+export function passesCliRecallScopeFilter(scope, requested) {
+    if (requested !== undefined && requested !== '' && !isPersonalScope(requested) && scope === requested) {
+        return true;
+    }
+    return passesScopeFilterForRecall(scope, undefined);
+}
+/** Thrown when a caller requests a scope its role may not read; the HTTP layer maps it to 403. */
+export class ScopeForbiddenError extends ForbiddenError {
+    scope;
+    constructor(scope) {
+        super(`scope ${scope} requires admin role`);
+        this.name = 'ScopeForbiddenError';
+        this.scope = scope;
+    }
+}
+/** True for scopes default-deny hides (`<source>:private:*` and the quarantine buckets); naming one explicitly unlocks it, so naming one needs
+ * authorization. */
+export function isRestrictedScope(scope) {
+    if (!isScopeString(scope))
+        return false;
+    // SAFETY: RECALL_DEFAULT_DENY_SCOPES is a readonly tuple of string literals; widening the array lets .includes() take any scope.
+    // `:private:` anywhere, any case, matches the SQL default-deny in src/store/search-rows.ts so JS never admits what SQL hides.
+    return isPrivateScope(scope) || /:private:/i.test(scope) || RECALL_DEFAULT_DENY_SCOPES.includes(scope);
+}
+/** Personal rows answer to their owner alone: role, key grants and resolver scopes never
+ * open one. Else admin reads all; a member needs an exact grant on a restricted scope. */
+export function canReadScope(actor, scope) {
+    if (isPersonalScope(scope))
+        return scope === personalScopeOf(actor);
+    if (actor.role === 'admin')
+        return true;
+    if (!isRestrictedScope(scope))
+        return true;
+    return (actor.scopes ?? []).includes(scope);
+}
+/** Authorize an explicitly requested scope before any read honours it (member scope grants). */
+export function assertScopeRequestAllowed(actor, requested) {
+    if (requested === undefined || requested === '')
+        return;
+    if (canReadScope(actor, requested))
+        return;
+    throw new ScopeForbiddenError(requested);
+}
+/** Scope a derived row keeps from one source: the restricted scope itself, else null. */
+export function derivationScope(scope) {
+    return isRestrictedScope(scope) ? (scope ?? null) : null;
+}
+/** The one derivation scope shared by every source, or `{ ok: false }` when
+ *  two disagree, so the caller skips the derived row instead of under-scoping it. */
+export function commonDerivationScope(scopes) {
+    let common = null;
+    let seen = false;
+    for (const raw of scopes) {
+        const scope = derivationScope(raw);
+        if (!seen) {
+            common = scope;
+            seen = true;
+        }
+        else if (scope !== common) {
+            return { ok: false };
+        }
+    }
+    return { ok: true, scope: common };
+}
+/** Map-partition key for consolidate/dag/dedup producers: tenant + derivation scope + origin project,
+ *  so a derived row never blends two restricted scopes, a mixed pair, or two projects. */
+export function derivationPartitionKey(tenantId, scope, origin) {
+    const project = origin === undefined ? '\u0002' : origin ?? '\u0001'; // unstamped, unknown and named never share a bucket
+    return `${tenantId}\u0000${derivationScope(scope) ?? ''}\u0000${project}`;
+}
+//# sourceMappingURL=recall-scope.js.map

package/dist/core/salience.d.ts

@@ -1,10 +1,4 @@
-/**
- * Salience gate — decides at memory creation time whether content is worth
- * storing at full strength, should start weakened, or should be skipped.
- *
- * Inspired by the biological salience network (anterior insula + dACC):
- * not everything that enters working memory deserves long-term storage.
- */
+/** Salience gate: decides at memory creation whether content is stored at full strength, starts weakened, or is skipped. */
 import type { MemoryEntry } from './memory.js';
 export type SalienceDecision = 'store' | 'skip' | 'start_weak';
 export interface SalienceResult {

package/dist/core/salience.js

@@ -1,10 +1,4 @@
-/**
- * Salience gate — decides at memory creation time whether content is worth
- * storing at full strength, should start weakened, or should be skipped.
- *
- * Inspired by the biological salience network (anterior insula + dACC):
- * not everything that enters working memory deserves long-term storage.
- */
+/** Salience gate: decides at memory creation whether content is stored at full strength, starts weakened, or is skipped. */
 import { textOverlap } from '../util/tokenize.js';
 import { duplicateKey, heldTextKeys } from '../util/same-text.js';
 // Each store or skip reason carries a score; a novel memory adds bonuses for structure and length.

package/dist/dashboard/dashboard-actions.js

@@ -1,6 +1,7 @@
 // The four dashboard writes, each a thin call into an existing store or api function; the router owns HTTP and the cache.
 import * as api from '../api/index.js';
 import { NotFoundError } from '../core/api-errors.js';
+import { RawAppendOnlyError } from '../core/raw-append-only.js';
 import { listTouchableConflicts, resolveConflict } from '../store/conflicts.js';
 import { readEntry } from '../store/entry-reads.js';
 import { writeEntry } from '../store/entry-writes.js';
@@ -52,8 +53,7 @@ export function forgetMemory(hippoRoot, tenantId, rawId) {
     catch (err) {
         if (err instanceof NotFoundError)
             return notFound();
-        // Same match as cmdForget: the append-only trigger names itself in the message.
-        if (err instanceof Error && /append-only/i.test(err.message)) {
+        if (err instanceof RawAppendOnlyError) {
             const error = `Cannot forget ${id}: it is a raw, append-only memory. Archive it instead: hippo forget ${id} --archive --reason "<why>"`;
             return { status: 409, body: { error }, changed: false };
         }

package/dist/dashboard/dashboard-snapshot.d.ts

@@ -133,6 +133,7 @@ export interface SnapshotService {
     embeddedIds(): ReadonlySet<string> | null;
     close(): void;
 }
-/** Holds one read-only connection for its commit signal (`PRAGMA data_version`) and the snapshot cache; `now` dates the strength projections, `cacheClock` ages the cache. */
+/** Holds one read-only connection for its commit signal (`PRAGMA data_version`) and the
+ * snapshot cache; `now` dates the strength projections, `cacheClock` ages the cache. */
 export declare function createSnapshotService(hippoRoot: string, now: () => number, cacheClock?: () => number): SnapshotService;
 //# sourceMappingURL=dashboard-snapshot.d.ts.map

package/dist/dashboard/dashboard-snapshot.js

@@ -263,7 +263,15 @@ class SnapshotCacheService {
         highestIssuedId = Math.max(highestIssuedId, this.lastId);
         // After loadDashboardRows, whose writable open has run any pending migration and legacy embeddings.json import.
         this.lastEmbeddedIds = this.connection.embeddedIds();
-        return buildSnapshot({ id: this.lastId, tenantId, nowMs, entries: rows?.live ?? [], excluded: rows?.excluded, openConflicts, embeddedIds: this.lastEmbeddedIds });
+        return buildSnapshot({
+            id: this.lastId,
+            tenantId,
+            nowMs,
+            entries: rows?.live ?? [],
+            excluded: rows?.excluded,
+            openConflicts,
+            embeddedIds: this.lastEmbeddedIds
+        });
     }
     get(tenantId, fresh = false) {
         const nowMs = this.now();
@@ -298,7 +306,8 @@ class SnapshotCacheService {
         this.lastEmbeddedIds = undefined;
     }
 }
-/** Holds one read-only connection for its commit signal (`PRAGMA data_version`) and the snapshot cache; `now` dates the strength projections, `cacheClock` ages the cache. */
+/** Holds one read-only connection for its commit signal (`PRAGMA data_version`) and the
+ * snapshot cache; `now` dates the strength projections, `cacheClock` ages the cache. */
 export function createSnapshotService(hippoRoot, now, cacheClock = Date.now) {
     return new SnapshotCacheService(hippoRoot, now, cacheClock);
 }

package/dist/dashboard/dashboard-types.d.ts

@@ -17,7 +17,8 @@ export interface ProjectSummary {
     bands: Record<Band, number>;
     layers: Record<Layer, number>;
 }
-/** One KPI card; `series` is 91 daily cumulative points, oldest first (point 0 is the base at the window start, point 90 is now) so `last - first` over any range plus one points is exact; null when hippo recorded no history. */
+/** One KPI card; `series` is 91 daily cumulative points, oldest first (point 0 is the base at the window start,
+ * point 90 is now) so `last - first` over any range plus one points is exact; null when hippo recorded no history. */
 export interface Kpi {
     id: 'total' | 'projects' | 'atRiskShare' | 'openConflicts' | 'embeddingCoverage';
     label: string;

package/dist/dashboard/dashboard.d.ts

@@ -4,5 +4,6 @@ import * as http from 'http';
 export declare function serveDashboard(hippoRoot: string, port?: number, token?: string, opts?: {
     now?: () => number;
     cacheClock?: () => number;
+    handleSignals?: boolean;
 }): http.Server;
 //# sourceMappingURL=dashboard.d.ts.map

package/dist/dashboard/dashboard.js

@@ -9,12 +9,16 @@ import { listCards } from '../store/cards.js';
 import { resolveTenantId } from '../store/tenant.js';
 import { loadCardDetail } from '../store/card-detail.js';
 import { bodyDeadlineMs, BodyTimeoutError, closeAfterReply, isCrossSite, LOOPBACK_HOST_HEADER } from '../util/http-util.js';
-import { errorMessage, log } from '../util/log.js';
+import { errorFields, errorMessage, log } from '../util/log.js';
 import { createSnapshotService, isLiveMemory } from './dashboard-snapshot.js';
 import { buildMemoryDetail, buildMemoryPage, buildOverview, buildProjectDetail, buildSearch, } from './dashboard-queries.js';
 import { forgetMemory, markWrong, pinMemory, resolveOpenConflict, } from './dashboard-actions.js';
 import { ParamError, parseActionBody, parseConflictId, parseMemoryId, parseMemoryQuery, parseSearchText, } from './dashboard-params.js';
 import { runWithRequestId } from '../util/request-scope.js';
+import { installSignalHandlers } from '../util/crash-handlers.js';
+import { DEFAULT_SHUTDOWN_DRAIN_MS, drainAndClose, setKeepAliveTimeouts, shutdownBoundMs } from '../server/lifecycle.js';
+import { printError } from '../cli/output.js';
+import { PACKAGE_ROOT } from '../core/package-root.js';
 const MIME_TYPES = {
     '.html': 'text/html; charset=utf-8',
     '.js': 'application/javascript; charset=utf-8',
@@ -296,7 +300,7 @@ function answerDashboardFailure(req, res, err) {
     const clientFault = err instanceof ParamError || err instanceof URIError || err instanceof BodyTimeoutError;
     // A cut-short response is logged even for a client fault; a bare 400 is not.
     if (res.headersSent || !clientFault) {
-        log.error('dashboard request failed', { error: errorMessage(err), path: req.url });
+        log.error('dashboard request failed', { ...errorFields(err), error: errorMessage(err), path: req.url });
     }
     if (res.headersSent) {
         res.end();
@@ -321,9 +325,51 @@ function printDashboardBanner(boundPort, token, distUiDir) {
         console.log(`Serving React UI from ${distUiDir}`);
     console.log('Press Ctrl+C to stop.');
 }
+/** A port that will not open is the user's to fix, so it gets one plain line and a failure exit code, not an uncaught error's stack. */
+function reportListenFailure(port, err) {
+    const inUse = 'code' in err && err.code === 'EADDRINUSE';
+    printError(inUse
+        ? `hippo dashboard: port ${port} is already in use. Stop the program that holds it, or choose another port with --port <number>.`
+        : `hippo dashboard: could not listen on port ${port}: ${err.message}. Choose another port with --port <number>.`);
+    process.exitCode = 1;
+}
+/** Ctrl+C or a stop signal: stop listening, give open requests the API server's drain, and leave within its shutdown bound. */
+function stopOnSignal(server) {
+    const inflight = new Set();
+    server.on('request', (_req, res) => {
+        inflight.add(res);
+        res.once('close', () => inflight.delete(res));
+    });
+    installSignalHandlers('dashboard', {
+        run: () => drainAndClose(server, inflight, DEFAULT_SHUTDOWN_DRAIN_MS),
+        boundMs: shutdownBoundMs(DEFAULT_SHUTDOWN_DRAIN_MS),
+    });
+}
+/** Gives the listener the API server's socket deadlines and one close of the store's connection; with `handleSignals`, a signal stops it too. */
+function superviseListener(server, snapshots, port, handleSignals) {
+    setKeepAliveTimeouts(server);
+    let storeClosed = false;
+    const closeStore = () => {
+        if (storeClosed)
+            return;
+        storeClosed = true;
+        snapshots.close();
+    };
+    server.on('close', closeStore);
+    server.on('error', (err) => {
+        // Once it listens, an 'error' is a failed accept: logged, as the API server does, and the dashboard keeps serving.
+        if (server.listening)
+            return log.error(`dashboard: listener error: ${err.message}`, errorFields(err));
+        reportListenFailure(port, err);
+        // A failed listen emits no 'close', so the store closes here.
+        closeStore();
+    });
+    if (handleSignals)
+        stopOnSignal(server);
+}
 /** Serves the dashboard on 127.0.0.1 behind a per-start `token` (tests pass one), since loopback alone lets any local process read every memory; `opts` sets the projection and cache clocks. */
 export function serveDashboard(hippoRoot, port = 3333, token = randomBytes(32).toString('base64url'), opts) {
-    const distUiDir = path.resolve(import.meta.dirname, '..', 'dist-ui');
+    const distUiDir = path.join(PACKAGE_ROOT, 'dist-ui');
     const hasDistUi = fs.existsSync(path.join(distUiDir, 'index.html'));
     const now = opts?.now ?? (() => evalNow().getTime());
     const snapshots = createSnapshotService(hippoRoot, now, opts?.cacheClock);
@@ -356,7 +402,7 @@ export function serveDashboard(hippoRoot, port = 3333, token = randomBytes(32).t
     };
     // One id per request, so the lines it logs can be told apart from a concurrent request's.
     const server = http.createServer((req, res) => runWithRequestId(randomUUID(), () => onRequest(req, res)));
-    server.on('close', () => snapshots.close());
+    superviseListener(server, snapshots, port, opts?.handleSignals === true);
     server.listen(port, '127.0.0.1', () => {
         // SAFETY: listen() was given a TCP port, so address() is AddressInfo, never a pipe name.
         const boundPort = server.address().port;

package/dist/db/busy.d.ts

@@ -1,12 +1,7 @@
 import type { DatabaseSyncLike } from './sqlite.js';
-export declare function isSqliteBusy(error: unknown): boolean;
-export declare const STORE_BUSY_MESSAGE = "store busy (another hippo process holds the write lock); retry shortly";
-/** A store behind the port throws this when its lock wait runs out, so the server answers 503 as it does for a busy hippo.db. */
-export declare class StoreBusyError extends Error {
-    constructor(message?: string, options?: ErrorOptions);
-}
-/** A held lock in any store: SQLite's busy codes or a port's StoreBusyError. */
-export declare function isStoreBusy<E>(error: E): boolean;
+export declare function isSqliteBusy(cause: unknown): boolean;
+/** The lock wait of an open that names none: its busy_timeout and every explicit wait below. */
+export declare const DEFAULT_BUSY_WAIT_MS = 5000;
 export declare function execWithBusyRetry(db: DatabaseSyncLike, sql: string, timeoutMs?: number): void;
 /** Waits for the lock past busy_timeout when given; ignored inside a caller's transaction, which already holds it. */
 export interface WriteScopeOptions {