hippo-memory 1.47.0 → 1.49.0

package/README.md

@@ -256,7 +256,7 @@ hippo recall "data pipeline" --why --limit 5
 
 Input enters the buffer. Important things get encoded into episodic memory. During "sleep," repeated episodes compress into semantic patterns. Weak memories decay and disappear.
 
-The store is SQLite (`.hippo/hippo.db`). The markdown files and `index.json` are mirrors written after each change. From 1.46.0, `index.json` is no longer refreshed on every write; it comes only from an explicit export, so read the store through the CLI, the MCP server or the HTTP API.
+The store is SQLite (`.hippo/hippo.db`). The markdown files are mirrors written after each change. `index.json` is no longer refreshed by writes, deletes or recalls: it is written only when you call `rebuildIndex()` from the package, so a copy an older version left on disk goes stale. Read the store through the CLI, the MCP server or the HTTP API.
 
 ```mermaid
 flowchart TD
@@ -629,6 +629,7 @@ hippo watch "npm run build"
 | `hippo dormant restore <id>` | Bring a dormant memory back to active memory |
 | `hippo dormant forget <id>` | Delete a dormant memory permanently |
 | `hippo doctor [--json]` | Check the install: Node, store, schema, sleep, agent hooks; each problem names its fix |
+| `hippo support-bundle [--out <file>] [--include-logs]` | Write a redacted JSON file for a support ticket: versions, doctor checks, config, store counts and log names, never memory text; `--include-logs` adds each log's last 200 lines, which can quote it |
 | `hippo tokens [--days n]` | Estimated tokens of memory text handed to agents, per surface, and what skipping unchanged hook blocks saved |
 | `hippo failures [--days n]` | Failed tool calls the capture-error hook saw, by outcome, and how many errors first happened in another session |
 | `hippo embed` | Embed all memories for semantic search |

package/dist/api.d.ts

@@ -40,6 +40,8 @@ export interface Actor {
     /** 'cli' | 'localhost:cli' | 'api_key:<key_id>' | 'mcp' | 'connector:slack' | 'connector:github' */
     subject: string;
     role: 'admin' | 'member';
+    /** EI2: restricted scopes a member key may read (auth.ts grantScope). Unused for admin actors. */
+    scopes?: readonly string[];
 }
 export interface Context {
     hippoRoot: string;
@@ -875,6 +877,14 @@ export interface AuthRevokeResult {
     revokedAt: string;
 }
 export declare function authRevoke(ctx: Context, keyId: string): AuthRevokeResult;
+/** Shared result shape for authGrant/authUngrant, named per the file's oxlint anti-slop rule. */
+export interface AuthGrantResult {
+    ok: true;
+}
+/** Grant `keyId` read access to one restricted `scope` (ROADMAP Part VIII EI2). Admin only. */
+export declare function authGrant(ctx: Context, keyId: string, scope: string): AuthGrantResult;
+/** Revoke `keyId`'s grant on `scope`. Same authorization and lookup rules as authGrant. */
+export declare function authUngrant(ctx: Context, keyId: string, scope: string): AuthGrantResult;
 export interface AuditListOpts {
     op?: AuditOp;
     /** ISO timestamp lower bound. */

package/dist/api.js

@@ -21,7 +21,7 @@ import { promoteToGlobal, getGlobalRoot, autoShare, searchBothHybrid } from './s
 import { writeRecallTrace, writeRecallTraceAtRoot, recordTraceOutcome } from './recall-trace.js';
 import { evalNow } from './ablation.js';
 import { archiveRawMemory } from './raw-archive.js';
-import { createApiKey, listApiKeys, revokeApiKey, } from './auth.js';
+import { createApiKey, listApiKeys, revokeApiKey, grantScope, ungrantScope, } from './auth.js';
 import { applyGoalStackBoost } from './goals.js';
 import { markRetrieved, estimateTokens, hybridSearch, physicsSearch } from './search.js';
 import { compareEntryIdentity, compareScoredResults } from './compare.js';
@@ -87,7 +87,7 @@ export class ForbiddenError extends Error {
 // back-compat (`api.isPrivateScope`, test imports). NOTE: the import statement
 // is required — a bare `export { x } from` re-export does not bind the local
 // names this module's ~9 call sites use.
-import { isPrivateScope, passesScopeFilterForRecall, assertScopeRequestAllowed } from './recall-scope.js';
+import { isPrivateScope, passesScopeFilterForRecall, assertScopeRequestAllowed, isRestrictedScope } from './recall-scope.js';
 export { isPrivateScope, passesScopeFilterForRecall };
 export { passesCliRecallScopeFilter, ScopeForbiddenError } from './recall-scope.js';
 // v39: classifyOriginProject lives in project-identity.ts (leaf) so
@@ -188,13 +188,13 @@ export function buildSuppressionSummary(counts) {
  */
 export function recall(ctx, opts) {
     // A member key may not unlock a private or quarantined scope by naming it.
-    assertScopeRequestAllowed(ctx.actor.role, opts.scope);
+    assertScopeRequestAllowed(ctx.actor, opts.scope);
     const windowSize = recallWindowSize(opts);
     return recallFrom(ctx, opts, windowSize, loadRecallSearchEntries(ctx.hippoRoot, opts.query, windowSize, ctx.tenantId, opts.scope, 'exact', false));
 }
 /** Mode-aware recall that strengthens each returned row; never writes last_retrieval_ids (v1.11.5 lock). */
 export async function retrieve(ctx, opts) {
-    assertScopeRequestAllowed(ctx.actor.role, opts.scope);
+    assertScopeRequestAllowed(ctx.actor, opts.scope);
     const windowSize = recallWindowSize(opts);
     let candidates = loadRecallSearchEntries(ctx.hippoRoot, opts.query, windowSize, ctx.tenantId, opts.scope, 'exact', false);
     if (opts.mode === 'hybrid' || opts.mode === 'physics') {
@@ -288,7 +288,7 @@ function recallFrom(ctx, opts, windowSize, all) {
         // anchored `<source>:private:*` rule (v1.2.1 generalization) and
         // defense-in-depth: connector authors cannot silently surface private
         // rows to no-scope callers even if the SQL clause regresses.
-        entries = current.filter((e) => !isPrivateScope(e.scope ?? null));
+        entries = current.filter((e) => !isRestrictedScope(e.scope ?? null));
     }
     // v1.12.13 / C5 — WYSIATI dropped_pre_rank counter (JS scope filter drops
     // for api.recall; cmdRecall pipeline rolls --outcome/--layer/--as-of/etc.
@@ -725,7 +725,7 @@ function recallFrom(ctx, opts, windowSize, all) {
  *   - all rows fail the scope/tenant filter
  */
 export function assemble(ctx, sessionId, opts = {}) {
-    assertScopeRequestAllowed(ctx.actor.role, opts.scope);
+    assertScopeRequestAllowed(ctx.actor, opts.scope);
     const budget = opts.budget ?? 4000;
     const freshTailCount = opts.freshTailCount ?? 10;
     const summarizeOlder = opts.summarizeOlder ?? true;
@@ -1152,6 +1152,7 @@ export function supersede(ctx, oldId, newContent) {
         source: old.source,
         confidence: 'verified',
         tenantId: ctx.tenantId,
+        scope: old.scope,
     });
     // Race-safe transition: open a fresh db handle, BEGIN IMMEDIATE, run all
     // three steps (CAS on old + writeEntryDbOnly(new) + supersede audit row)
@@ -1216,11 +1217,11 @@ export function supersede(ctx, oldId, newContent) {
         }
         // 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 (self-heals on next backfill
-        // via writeIndexMirror reading the DB) but DOES NOT desync the DB or
+        // 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, db, newEntry);
+            writeEntryMirrors(ctx.hippoRoot, newEntry);
         }
         catch (mirrorErr) {
             console.error('supersede: mirror write failed (non-fatal, will self-heal):', mirrorErr);
@@ -1401,6 +1402,50 @@ export function authRevoke(ctx, keyId) {
         closeHippoDb(db);
     }
 }
+/** Grant `keyId` read access to one restricted `scope` (ROADMAP Part VIII EI2). Admin only. */
+export function authGrant(ctx, keyId, scope) {
+    return changeScopeGrant(ctx, keyId, scope, 'auth_grant');
+}
+/** Revoke `keyId`'s grant on `scope`. Same authorization and lookup rules as authGrant. */
+export function authUngrant(ctx, keyId, scope) {
+    return changeScopeGrant(ctx, keyId, scope, 'auth_ungrant');
+}
+function changeScopeGrant(ctx, keyId, scope, op) {
+    if (ctx.actor.role !== 'admin') {
+        throw new ForbiddenError('Only an admin key can change scope grants');
+    }
+    const db = openHippoDb(ctx.hippoRoot);
+    try {
+        // SAFETY: row's shape matches the single tenant_id column in the SELECT.
+        const row = db
+            .prepare(`SELECT tenant_id, revoked_at FROM api_keys WHERE key_id = ?`)
+            .get(keyId);
+        if (!row || row.tenant_id !== ctx.tenantId) {
+            throw new Error(`Unknown key_id: ${keyId}`);
+        }
+        if (op === 'auth_grant' && row.revoked_at) {
+            throw new Error(`${keyId} is revoked; a grant on it would never apply`);
+        }
+        if (!isRestrictedScope(scope)) {
+            throw new Error(`${scope} is not a restricted scope; it is already readable by default`);
+        }
+        if (op === 'auth_grant')
+            grantScope(db, keyId, scope);
+        else
+            ungrantScope(db, keyId, scope);
+        try {
+            appendAuditEvent(db, { tenantId: ctx.tenantId, actor: ctx.actor.subject, op, targetId: keyId, metadata: { scope } });
+        }
+        catch (err) {
+            // Audit must not undo a grant change that already committed; surface it instead.
+            console.error(`auth: audit write failed for ${op} ${keyId}: ${err instanceof Error ? err.message : String(err)}`);
+        }
+        return { ok: true };
+    }
+    finally {
+        closeHippoDb(db);
+    }
+}
 /**
  * Read audit events scoped to `ctx.tenantId`. Read-only — no audit emit (matches
  * A5: cmdAuditList does not record a 'recall'-style read event).
@@ -1998,7 +2043,7 @@ export function restoreDormant(ctx, id) {
             }
             throw err;
         }
-        writeEntryMirrors(ctx.hippoRoot, db, restored);
+        writeEntryMirrors(ctx.hippoRoot, restored);
         return restored;
     }
     finally {

package/dist/audit.d.ts

@@ -16,7 +16,7 @@ export interface AuditResult {
 export declare function auditMemory(entry: MemoryEntry): AuditIssue | null;
 export declare function auditMemories(entries: MemoryEntry[]): AuditResult;
 export declare function isContentWorthStoring(content: string): boolean;
-export type AuditOp = 'remember' | 'recall' | 'promote' | 'supersede' | 'forget' | 'archive_raw' | 'auth_revoke' | 'auth_create' | 'outcome' | 'consolidate' | 'audit_prune' | 'summary_marked_dirty' | 'summary_marked_clean' | 'summary_rebuilt' | 'predict_create' | 'predict_close' | 'predict_baserate' | 'recall_autodebias_hint' | 'recall_autodebias_hint_no_class_match' | 'recall_autodebias_hint_tiebreak' | 'recall_anchor_detected_query_repeat' | 'recall_anchor_detected_memory_dominance' | 'recall_anchor_skipped_no_session' | 'recall_availability_detected' | 'decision_create' | 'decision_supersede' | 'decision_close' | 'incident_open' | 'incident_resolve' | 'incident_close' | 'process_create' | 'process_supersede' | 'process_close' | 'policy_create' | 'policy_supersede' | 'policy_close' | 'skill_create' | 'skill_supersede' | 'skill_close' | 'project_brief_create' | 'project_brief_supersede' | 'project_brief_close' | 'customer_note_create' | 'customer_note_supersede' | 'customer_note_close' | 'mv_rescue' | 'reject_value' | 'reject_refusal' | 'unreject_value' | 'half_life_migrate' | 'dormant_restore' | 'conflict_resolve';
+export type AuditOp = 'remember' | 'recall' | 'promote' | 'supersede' | 'forget' | 'archive_raw' | 'auth_revoke' | 'auth_create' | 'outcome' | 'consolidate' | 'audit_prune' | 'summary_marked_dirty' | 'summary_marked_clean' | 'summary_rebuilt' | 'predict_create' | 'predict_close' | 'predict_baserate' | 'recall_autodebias_hint' | 'recall_autodebias_hint_no_class_match' | 'recall_autodebias_hint_tiebreak' | 'recall_anchor_detected_query_repeat' | 'recall_anchor_detected_memory_dominance' | 'recall_anchor_skipped_no_session' | 'recall_availability_detected' | 'decision_create' | 'decision_supersede' | 'decision_close' | 'incident_open' | 'incident_resolve' | 'incident_close' | 'process_create' | 'process_supersede' | 'process_close' | 'policy_create' | 'policy_supersede' | 'policy_close' | 'skill_create' | 'skill_supersede' | 'skill_close' | 'project_brief_create' | 'project_brief_supersede' | 'project_brief_close' | 'customer_note_create' | 'customer_note_supersede' | 'customer_note_close' | 'mv_rescue' | 'reject_value' | 'reject_refusal' | 'unreject_value' | 'half_life_migrate' | 'dormant_restore' | 'conflict_resolve' | 'auth_grant' | 'auth_ungrant';
 export interface AppendAuditOpts {
     tenantId: string;
     actor: string;

package/dist/auth.d.ts

@@ -16,9 +16,17 @@ export interface ValidateResult {
     keyId?: string;
     /** v1.12.0 A5 v2 sub-1: 'admin' | 'member'. Present only when valid=true. */
     role?: 'admin' | 'member';
+    /** EI2: scope grants for this key. Present only when valid=true. */
+    scopes?: string[];
 }
 export declare function validateApiKey(db: DatabaseSyncLike, plaintext: string): ValidateResult;
 export declare function revokeApiKey(db: DatabaseSyncLike, keyId: string): void;
+/** EI2: grant `keyId` read access to one restricted `scope`. Idempotent. */
+export declare function grantScope(db: DatabaseSyncLike, keyId: string, scope: string): void;
+/** EI2: revoke `keyId`'s grant on `scope`. Not an error when no such grant exists. */
+export declare function ungrantScope(db: DatabaseSyncLike, keyId: string, scope: string): void;
+/** EI2: every restricted scope `keyId` may read. */
+export declare function listScopeGrants(db: DatabaseSyncLike, keyId: string): string[];
 export interface ApiKeyListItem {
     keyId: string;
     tenantId: string;
@@ -31,6 +39,8 @@ export interface ApiKeyListItem {
      * Fail-safe-to-member cast: any non-'admin' value reads as 'member'.
      */
     role: 'admin' | 'member';
+    /** EI2: restricted scopes this key may read. */
+    scopes: string[];
 }
 export declare function listApiKeys(db: DatabaseSyncLike, opts: {
     active: boolean;

package/dist/auth.js

@@ -74,12 +74,30 @@ export function validateApiKey(db, plaintext) {
     // 'superuser', or a NULL slipped past the NOT NULL constraint) downgrades to
     // 'member'. The migration constrains to 'admin' DEFAULT, but defense-in-depth.
     const role = row.role === 'admin' ? 'admin' : 'member';
-    return { valid: true, tenantId: row.tenant_id, keyId, role };
+    const scopes = listScopeGrants(db, keyId);
+    return { valid: true, tenantId: row.tenant_id, keyId, role, scopes };
 }
 export function revokeApiKey(db, keyId) {
     db.prepare(`UPDATE api_keys SET revoked_at = ? WHERE key_id = ? AND revoked_at IS NULL`)
         .run(new Date().toISOString(), keyId);
 }
+/** EI2: grant `keyId` read access to one restricted `scope`. Idempotent. */
+export function grantScope(db, keyId, scope) {
+    db.prepare(`INSERT INTO api_key_scope_grants (key_id, scope, granted_at) VALUES (?, ?, ?)
+     ON CONFLICT(key_id, scope) DO NOTHING`).run(keyId, scope, new Date().toISOString());
+}
+/** EI2: revoke `keyId`'s grant on `scope`. Not an error when no such grant exists. */
+export function ungrantScope(db, keyId, scope) {
+    db.prepare(`DELETE FROM api_key_scope_grants WHERE key_id = ? AND scope = ?`).run(keyId, scope);
+}
+/** EI2: every restricted scope `keyId` may read. */
+export function listScopeGrants(db, keyId) {
+    // SAFETY: rows' shape matches the single `scope` column named in the SELECT above.
+    const rows = db
+        .prepare(`SELECT scope FROM api_key_scope_grants WHERE key_id = ? ORDER BY scope`)
+        .all(keyId);
+    return rows.map((r) => r.scope);
+}
 export function listApiKeys(db, opts) {
     const sql = opts.active
         ? `SELECT key_id, tenant_id, label, created_at, revoked_at, role FROM api_keys WHERE revoked_at IS NULL ORDER BY id DESC`
@@ -92,6 +110,7 @@ export function listApiKeys(db, opts) {
         keyId: r.key_id, tenantId: r.tenant_id, label: r.label,
         createdAt: r.created_at, revokedAt: r.revoked_at,
         role: r.role === 'admin' ? 'admin' : 'member',
+        scopes: listScopeGrants(db, r.key_id),
     }));
 }
 //# sourceMappingURL=auth.js.map

package/dist/cli.js

@@ -60,6 +60,8 @@ import { computeSystemEnergy, vecNorm } from './physics.js';
 import { loadConfig } from './config.js';
 import { openHippoDb, closeHippoDb } from './db.js';
 import { runDoctor, formatDoctor } from './doctor.js';
+import { buildSupportBundle, TAIL_MAX_LINES } from './support-bundle.js';
+import { PACKAGE_VERSION } from './version.js';
 import { captureToolFailure } from './capture-error.js';
 import { blockHash, hookPayloadSessionId, lastSentState, recordTokenUse, shouldSkipUnchanged } from './token-ledger.js';
 import { FAILURE_LOG_RETENTION_DAYS } from './failure-log.js';
@@ -264,7 +266,7 @@ export const BOOLEAN_FLAGS = new Set([
     'all', 'all-tenants', 'archive', 'auto', 'bad', 'bootstrap', 'classic', 'continuity',
     'cross-project', 'dry-run', 'equal-sources', 'error', 'evc-adaptive', 'extract',
     'filter-conflicts', 'fix', 'force', 'forget', 'git', 'global', 'good', 'graph-stream',
-    'help', 'include-superseded', 'inferred', 'json', 'last-session', 'multihop', 'no-hooks',
+    'help', 'include-logs', 'include-superseded', 'inferred', 'json', 'last-session', 'multihop', 'no-hooks',
     'no-learn', 'no-mmr', 'no-propagate', 'no-schedule', 'no-share', 'no-summarize-older',
     'observed', 'open', 'physics', 'pin', 'pinned-only', 'reject-loser', 'rerank-utility',
     'reset-physics', 'save-baseline', 'show-cases', 'stats', 'stdin',
@@ -488,7 +490,7 @@ function cmdInit(hippoRoot, flags) {
         initStore(hippoRoot);
         console.log('Initialized Hippo at', hippoRoot);
         console.log('   Directories: buffer/ episodic/ semantic/ conflicts/');
-        console.log('   Files: hippo.db index.json stats.json');
+        console.log('   Files: hippo.db stats.json');
     }
     const globalRoot = getGlobalRoot();
     registerWorkspace(globalRoot, path.dirname(hippoRoot));
@@ -850,6 +852,7 @@ function cmdSupersede(hippoRoot, oldId, newContent, flags) {
         source: old.source,
         confidence: 'verified',
         tenantId: old.tenantId,
+        scope: old.scope,
     });
     // AT1: write the SUCCESSOR first. The rejection guard fires on the new
     // content — if it refuses, nothing has been mutated yet (the old ordering
@@ -7883,6 +7886,41 @@ function cmdAuthRevoke(hippoRoot, keyId, flags) {
     }
     console.log(`Revoked ${keyId} at ${revokedAt}`);
 }
+/** EI2: `hippo auth grant|ungrant <key_id> <scope>`, routed through api so the tenant, restricted-scope and audit checks live in one place. */
+function cmdAuthScopeGrant(hippoRoot, keyId, scope, grant, flags) {
+    const root = resolveAuthRoot(hippoRoot, flags);
+    // The local CLI owns every tenant (as auth revoke does), so the grant runs in the key's own tenant.
+    const db = openHippoDb(root);
+    let keyTenant;
+    try {
+        // SAFETY: row's shape matches the single tenant_id column in the SELECT.
+        const row = db.prepare(`SELECT tenant_id FROM api_keys WHERE key_id = ?`).get(keyId);
+        keyTenant = row?.tenant_id;
+    }
+    finally {
+        closeHippoDb(db);
+    }
+    if (keyTenant === undefined) {
+        console.error(`Unknown key_id: ${keyId}`);
+        process.exit(1);
+    }
+    const ctx = { hippoRoot: root, tenantId: keyTenant, actor: api.adminActor('cli') };
+    try {
+        if (grant)
+            api.authGrant(ctx, keyId, scope);
+        else
+            api.authUngrant(ctx, keyId, scope);
+    }
+    catch (err) {
+        console.error(`Error: ${err instanceof Error ? err.message : String(err)}`);
+        process.exit(1);
+    }
+    if (flags['json']) {
+        console.log(JSON.stringify({ keyId, scope, granted: grant }));
+        return;
+    }
+    console.log(grant ? `Granted ${keyId} read access to ${scope}` : `Removed ${keyId}'s grant on ${scope}`);
+}
 // ---------------------------------------------------------------------------
 // Audit log subcommands (A5 stub auth — `hippo audit list`)
 // ---------------------------------------------------------------------------
@@ -7939,6 +7977,8 @@ const VALID_AUDIT_OPS = new Set([
     'conflict_resolve', // AT1 — emitted by resolveConflict on every resolution path; lockstep
     'half_life_migrate', // Decay default change — emitted by migrateDefaultHalfLife; lockstep with AuditOp union
     'dormant_restore', // Dormant memories — emitted by api.restoreDormant; lockstep with AuditOp union + server.ts VALID_AUDIT_OPS
+    'auth_grant', // EI2: emitted by api.authGrant; lockstep with AuditOp union + server.ts VALID_AUDIT_OPS
+    'auth_ungrant', // EI2: emitted by api.authUngrant; lockstep with AuditOp union + server.ts VALID_AUDIT_OPS
 ]);
 function formatAuditRow(ev) {
     const target = ev.targetId ?? '-';
@@ -8262,7 +8302,7 @@ function cmdGoal(hippoRoot, args, flags) {
 function cmdAuth(hippoRoot, args, flags) {
     const sub = args[0];
     if (!sub) {
-        console.error('Usage: hippo auth <create|list|revoke> [options]');
+        console.error('Usage: hippo auth <create|list|revoke|grant|ungrant> [options]');
         process.exit(1);
     }
     const subArgs = args.slice(1);
@@ -8282,8 +8322,18 @@ function cmdAuth(hippoRoot, args, flags) {
             cmdAuthRevoke(hippoRoot, keyId, flags);
             return;
         }
+        case 'grant':
+        case 'ungrant': {
+            const [keyId, scope] = subArgs;
+            if (!keyId || !scope) {
+                console.error(`Usage: hippo auth ${sub} <key_id> <scope>`);
+                process.exit(1);
+            }
+            cmdAuthScopeGrant(hippoRoot, keyId, scope, sub === 'grant', flags);
+            return;
+        }
         default:
-            console.error(`Unknown auth subcommand: ${sub}. Expected: create | list | revoke.`);
+            console.error(`Unknown auth subcommand: ${sub}. Expected: create | list | revoke | grant | ungrant.`);
             process.exit(1);
     }
 }
@@ -8675,6 +8725,10 @@ Commands:
                            PostToolUseFailure hook payload on stdin; skips routine failures)
   doctor                   Check the install: Node, store, schema, sleep, agent hooks
     --json                 Machine-readable report (exit code 1 on any failure)
+  support-bundle           Write a redacted JSON file for a support ticket: versions, doctor,
+                           config without secrets, store counts, log names; never memory text
+    --out <file>           Where to write it (default: hippo-support-<time>.json here)
+    --include-logs         Add the last ${TAIL_MAX_LINES} lines of each hippo log, known secret shapes removed
   tokens                   Tokens of memory text hippo handed agents, per surface
                            (hook, context, recall, MCP, HTTP), and what skipping
                            unchanged hook blocks saved
@@ -8960,6 +9014,12 @@ Commands:
     auth revoke <key_id>   Revoke an API key (subsequent validate fails)
       --json               Output as JSON
       --global             Operate on the global store
+    auth grant <key_id> <scope>    Let a member key read one restricted scope
+      --json               Output as JSON
+      --global             Operate on the global store
+    auth ungrant <key_id> <scope>  Remove a scope grant
+      --json               Output as JSON
+      --global             Operate on the global store
   audit <sub>              Query the append-only audit log (A5 stub auth)
     audit list             List audit events for the active tenant
       --op <op>            Filter by op (remember | recall | promote |
@@ -9433,6 +9493,38 @@ async function main(command, args, flags, hippoRoot) {
                 process.exit(1);
             break;
         }
+        case 'support-bundle': {
+            const outFlag = cardStringFlag(flags, 'out');
+            if (outFlag === '') {
+                console.error('--out requires a file path.');
+                process.exit(1);
+            }
+            const includeLogs = flags['include-logs'] === true;
+            const home = process.env.HOME || process.env.USERPROFILE || os.homedir();
+            const now = new Date();
+            const bundle = buildSupportBundle({ cwd: process.cwd(), home, version: PACKAGE_VERSION, includeLogs, now });
+            const stamp = now.toISOString().replace(/[:.]/g, '-');
+            const file = outFlag ?? path.join(process.cwd(), `hippo-support-${stamp}.json`);
+            const json = JSON.stringify(bundle, null, 2);
+            try {
+                fs.writeFileSync(file, `${json}\n`, { flag: 'wx', mode: 0o600 });
+            }
+            catch (err) {
+                if (err instanceof Error && 'code' in err && err.code === 'EEXIST') {
+                    console.error(`${file} already exists; pass --out to choose another file. Nothing was written.`);
+                }
+                else {
+                    console.error(err instanceof Error ? err.message : String(err));
+                }
+                process.exit(1);
+            }
+            const kb = Math.round(Buffer.byteLength(json) / 1024);
+            console.log(`Wrote ${file} (${kb} KB).`);
+            console.log(includeLogs
+                ? `It holds versions, doctor checks, config with secrets removed, store counts, and the last ${TAIL_MAX_LINES} lines of each hippo log with known secret shapes removed. Those log lines can quote memory text. Read it before you attach it to a ticket.`
+                : 'It holds versions, doctor checks, config with secrets removed, store counts and log file names. It never holds memory text. Read it before you attach it to a ticket.');
+            break;
+        }
         case 'snapshot':
             cmdSnapshot(hippoRoot, args, flags);
             break;

package/dist/consolidate.d.ts

@@ -19,6 +19,8 @@ export interface ConsolidationResult {
     semanticCreated: number;
     replayed: number;
     promotedTraces: number;
+    /** T7: sessions skipped because their events span two derivation scopes. */
+    tracesSkippedMixedScope: number;
     extractionCandidates: number;
     extracted: number;
     dagCandidateClusters: number;

package/dist/consolidate.js

@@ -25,6 +25,7 @@ import { rescueSet, rankNonPinnedByTenant, validateWeights } from './memory-valu
 import { MEMORY_VALUE_WEIGHTS, SOURCE_ARTIFACT_SHA256 } from './memory-value-weights.js';
 import { appendAuditEvent } from './audit.js';
 import { migrateDefaultHalfLife } from './half-life-migration.js';
+import { derivationScope, commonDerivationScope, derivationPartitionKey } from './recall-scope.js';
 const DECAY_THRESHOLD = 0.05;
 const MERGE_OVERLAP_THRESHOLD = 0.35; // Jaccard similarity for "related"
 const MERGE_MIN_CLUSTER = 2; // minimum cluster size to merge
@@ -108,6 +109,7 @@ export async function consolidate(hippoRoot, options = {}) {
         semanticCreated: 0,
         replayed: 0,
         promotedTraces: 0,
+        tracesSkippedMixedScope: 0,
         extractionCandidates: 0,
         extracted: 0,
         dagCandidateClusters: 0,
@@ -368,6 +370,13 @@ export async function consolidate(hippoRoot, options = {}) {
                     session_id: session.session_id,
                     limit: 1000,
                 });
+                // T7: a mixed-scope session would otherwise leak into one trace.
+                const sessionScope = commonDerivationScope(events.map((e) => e.scope));
+                if (!sessionScope.ok) {
+                    result.tracesSkippedMixedScope++;
+                    result.details.push(`  ⏭  skipped session ${session.session_id}: events span mixed scopes`);
+                    continue;
+                }
                 const completeEvent = events.find((e) => e.event_type === 'session_complete');
                 if (!completeEvent)
                     continue; // defence-in-depth; findPromotableSessions filters already.
@@ -391,6 +400,7 @@ export async function consolidate(hippoRoot, options = {}) {
                     source_session_id: session.session_id,
                     tags: ['auto-promoted'],
                     source: 'auto-promote',
+                    scope: sessionScope.scope,
                     // T1 fix (2026-08-15 hardening pass): stamp the trace into the SAME
                     // tenant the traceExistsForSession idempotency check (above) runs
                     // under. Before
@@ -671,11 +681,12 @@ export async function consolidate(hippoRoot, options = {}) {
         // before this fix — byte-identical behavior there.
         const mergeCandidatesByTenant = new Map();
         for (const entry of mergeCandidates) {
-            const bucket = mergeCandidatesByTenant.get(entry.tenantId);
+            const key = derivationPartitionKey(entry.tenantId, entry.scope);
+            const bucket = mergeCandidatesByTenant.get(key);
             if (bucket)
                 bucket.push(entry);
             else
-                mergeCandidatesByTenant.set(entry.tenantId, [entry]);
+                mergeCandidatesByTenant.set(key, [entry]);
         }
         // AT1 consolidation-loop fix (docs/plans/2026-08-15-at1-rejected-value-tombstone.md):
         // reuses the single consolidateDb handle opened once above (before the
@@ -686,7 +697,9 @@ export async function consolidate(hippoRoot, options = {}) {
         // declared up at the try's opening above 1.4, not here — it has to
         // survive the try/finally that now wraps this whole section; see the
         // handle-leak restructure comment there.)
-        for (const [mergeTenant, tenantCandidates] of mergeCandidatesByTenant) {
+        for (const [, tenantCandidates] of mergeCandidatesByTenant) {
+            const mergeTenant = tenantCandidates[0].tenantId;
+            const mergeScope = derivationScope(tenantCandidates[0].scope);
             for (let i = 0; i < tenantCandidates.length; i++) {
                 if (used.has(tenantCandidates[i].id))
                     continue;
@@ -722,6 +735,7 @@ export async function consolidate(hippoRoot, options = {}) {
                         source: 'consolidation',
                         confidence: 'inferred',
                         tenantId: mergeTenant,
+                        scope: mergeScope,
                     });
                 }
                 // mergeContents is DETERMINISTIC CONCATENATION (not an LLM paraphrase)

package/dist/dag.js

@@ -2,6 +2,7 @@ import { createMemory, Layer } from './memory.js';
 import { writeEntry, loadAllDirtySummaries, loadChildrenOfSummary, applyRebuildResult, clearSummaryDirtyAfterBuild, } from './store.js';
 import { RejectedValueError } from './rejection.js';
 import { redactSecrets } from './secret-detect.js';
+import { derivationScope, derivationPartitionKey } from './recall-scope.js';
 export function clusterFacts(facts) {
     if (facts.length === 0)
         return [];
@@ -93,13 +94,16 @@ export async function buildDag(hippoRoot, facts, opts) {
     // behavior there.
     const unparentedByTenant = new Map();
     for (const fact of unparented) {
-        const bucket = unparentedByTenant.get(fact.tenantId);
+        const key = derivationPartitionKey(fact.tenantId, fact.scope);
+        const bucket = unparentedByTenant.get(key);
         if (bucket)
             bucket.push(fact);
         else
-            unparentedByTenant.set(fact.tenantId, [fact]);
+            unparentedByTenant.set(key, [fact]);
     }
-    for (const [factTenant, tenantFacts] of unparentedByTenant) {
+    for (const [, tenantFacts] of unparentedByTenant) {
+        const factTenant = tenantFacts[0].tenantId;
+        const factScope = derivationScope(tenantFacts[0].scope);
         const clusters = clusterFacts(tenantFacts);
         const eligibleClusters = clusters.filter((c) => c.members.length >= 3);
         result.candidateClusters += eligibleClusters.length;
@@ -118,6 +122,7 @@ export async function buildDag(hippoRoot, facts, opts) {
                 confidence: 'inferred',
                 dag_level: 2,
                 tenantId: factTenant,
+                scope: factScope,
             });
             // Schema v25: cache descendant_count + earliest/latest_at on the summary
             // row so DAG-aware recall (docs/plans/2026-05-05-dag-recall.md Task 2)
@@ -299,11 +304,14 @@ export async function buildEntityProfiles(hippoRoot, l2Summaries, opts) {
     const byTenant = new Map();
     for (const l2 of unparented) {
         const tid = l2.tenantId ?? 'default';
-        const list = byTenant.get(tid) ?? [];
+        const key = derivationPartitionKey(tid, l2.scope);
+        const list = byTenant.get(key) ?? [];
         list.push(l2);
-        byTenant.set(tid, list);
+        byTenant.set(key, list);
     }
-    for (const [tenantId, tenantL2s] of byTenant) {
+    for (const [, tenantL2s] of byTenant) {
+        const tenantId = tenantL2s[0].tenantId ?? 'default';
+        const scope = derivationScope(tenantL2s[0].scope);
         const clusters = clusterFacts(tenantL2s);
         const eligible = clusters.filter((c) => c.members.length >= 2);
         result.candidateClusters += eligible.length;
@@ -321,6 +329,7 @@ export async function buildEntityProfiles(hippoRoot, l2Summaries, opts) {
                 confidence: 'inferred',
                 dag_level: 3,
                 tenantId, // HIGH #1 fold: thread tenant explicitly
+                scope,
             });
             profileEntry.descendant_count = cluster.members.length;
             profileEntry.earliest_at = memberCreatedAts[0];

package/dist/db.d.ts

@@ -13,11 +13,18 @@ export interface DatabaseSyncLike {
 }
 export declare function getHippoDbPath(hippoRoot: string): string;
 export declare function getCurrentSchemaVersion(): number;
+/** Thrown by {@link assertBinaryCompatible}; doctor uses it to pick the upgrade fix over a generic permissions fix. */
+export declare class IncompatibleBinaryError extends Error {
+}
 export declare function openHippoDb(hippoRoot: string): DatabaseSyncLike;
+/** Open an existing store without changing it: no mkdir, WAL switch, migration or mirror cleanup. Throws when hippo.db is missing. */
+export declare function openHippoDbReadOnly(hippoRoot: string): DatabaseSyncLike;
 export declare function getSchemaVersion(db: DatabaseSyncLike): number;
 export declare function closeHippoDb(db: DatabaseSyncLike): void;
 export declare function getMeta(db: DatabaseSyncLike, key: string, fallback?: string): string;
 export declare function setMeta(db: DatabaseSyncLike, key: string, value: string): void;
+/** Row count of one table; null when the table is missing or unreadable, which callers show as unknown. */
+export declare function countTableRows(db: DatabaseSyncLike, table: string): number | null;
 export declare function isFtsAvailable(db: DatabaseSyncLike): boolean;
 export declare function pruneConsolidationRuns(db: DatabaseSyncLike, keep?: number): void;
 export {};