hippo-memory 1.72.0 → 2.1.0

package/dist/cli/predictions.js

@@ -1,28 +1,25 @@
 // First-class object verbs for predictions: record a claim, close it against the actual, and read the class base rate.
-import * as predictionsApi from '../api/predictions.js';
+import * as predictionsApi from '../api/objects/predictions.js';
 import { VALID_CLOSURE_STATES } from '../core/prediction.js';
 import { cliApiContext } from './api-context.js';
 import { printError } from './output.js';
 import { parseListLimit, stringFlag } from './flag-values.js';
 import { requireInit } from './shared.js';
 import { foundOrExit, idArgOrExit, requireStatus } from './object-verbs.js';
-import { parseObjectId } from './lenient-id.js';
-import { CliExit } from './exit.js';
+import { fail } from './exit.js';
 const BASERATE_DECIMALS = 3;
 const PREDICTION_NOUN = 'Prediction';
 async function predictClose(ctx, args, flags) {
-    const id = idArgOrExit(args, 'Usage: hippo predict close <id> --state <closed|closed-unknown> [--actual <v>] [--note "..."]', 'prediction', parseObjectId);
+    const id = idArgOrExit(args, 'Usage: hippo predict close <id> --state <closed|closed-unknown> [--actual <v>] [--note "..."]', 'prediction');
     const stateRaw = (stringFlag(flags, 'state') ?? '').trim();
     // SAFETY: Set.has only compares by value, so a string outside the closure states is a plain miss.
     if (!VALID_CLOSURE_STATES.has(stateRaw) || stateRaw === 'open') {
-        printError(`Invalid --state: "${stateRaw}". Must be one of: closed | closed-unknown.`);
-        throw new CliExit(1);
+        fail(`Invalid --state: "${stateRaw}". Must be one of: closed | closed-unknown.`);
     }
     const actualRaw = flags['actual'];
     const actualValue = actualRaw !== undefined ? Number(actualRaw) : undefined;
     if (actualRaw !== undefined && !Number.isFinite(actualValue)) {
-        printError(`Invalid --actual: "${actualRaw}". Must be a number.`);
-        throw new CliExit(1);
+        fail(`Invalid --actual: "${actualRaw}". Must be a number.`);
     }
     const closureNote = stringFlag(flags, 'note');
     const closed = await predictionsApi.closePrediction(ctx, id, {
@@ -47,8 +44,7 @@ async function loadPredictionList(ctx, status, classTag, limit) {
     const closureState = requireStatus(status, VALID_CLOSURE_STATES);
     if (!classTag) {
         // status filter without class: scan all classes is more complex; v1 requires --class for non-default status
-        printError('--status filter (non-open) requires --class to be set.');
-        throw new CliExit(1);
+        fail('--status filter (non-open) requires --class to be set.');
     }
     return predictionsApi.listPredictions(ctx, {
         classTag,
@@ -77,14 +73,15 @@ async function predictList(ctx, flags) {
     }
 }
 async function predictShow(ctx, args) {
-    const id = idArgOrExit(args, 'Usage: hippo predict show <id>', 'prediction', parseObjectId);
+    const id = idArgOrExit(args, 'Usage: hippo predict show <id>', 'prediction');
     const pred = foundOrExit(await predictionsApi.predictionById(ctx, id), PREDICTION_NOUN, id);
     console.log(`Prediction #${pred.id}`);
     console.log(`  class: ${pred.classTag}`);
     console.log(`  claim: ${pred.claimText}`);
     console.log(`  state: ${pred.closureState}`);
-    if (pred.estimateValue !== null)
+    if (pred.estimateValue !== null) {
         console.log(`  estimate: ${pred.estimateValue}${pred.estimateUnit ? ' ' + pred.estimateUnit : ''}`);
+    }
     if (pred.targetDate)
         console.log(`  target: ${pred.targetDate}`);
     if (pred.actualValue !== null)
@@ -101,8 +98,7 @@ async function predictBaserate(ctx, flags) {
     // Reference-class / planning-fallacy detector
     const classTag = stringFlag(flags, 'class')?.trim();
     if (!classTag) {
-        printError('Usage: hippo predict baserate --class <c>');
-        throw new CliExit(1);
+        fail('Usage: hippo predict baserate --class <c>');
     }
     const baserate = await predictionsApi.predictionBaserate(ctx, classTag);
     if (baserate.nClosed === 0) {
@@ -114,10 +110,12 @@ async function predictBaserate(ctx, flags) {
     console.log(baserate.summary);
     console.log(`  n_closed:         ${baserate.nClosed}`);
     console.log(`  n_ratio_eligible: ${baserate.nRatioEligible}`);
-    if (baserate.meanEstimate !== null)
+    if (baserate.meanEstimate !== null) {
         console.log(`  mean_estimate:    ${baserate.meanEstimate.toFixed(BASERATE_DECIMALS)}`);
-    if (baserate.meanActual !== null)
+    }
+    if (baserate.meanActual !== null) {
         console.log(`  mean_actual:      ${baserate.meanActual.toFixed(BASERATE_DECIMALS)}`);
+    }
     if (baserate.meanRatio !== null)
         console.log(`  mean_ratio:       ${baserate.meanRatio.toFixed(BASERATE_DECIMALS)}x`);
     if (baserate.p50Ratio !== null)
@@ -145,19 +143,16 @@ async function predictCreate(ctx, claimText, flags) {
         printError('Usage: hippo predict "<claim>" --class <c> [--estimate <v>] [--unit <u>] [--target <YYYY-MM-DD>]');
         printError('       hippo predict close <id> --state <closed|closed-unknown> [--actual <v>] [--note "..."]');
         printError('       hippo predict list [--class X] [--status open|closed|closed-unknown|all] [--limit N]');
-        printError('       hippo predict show <id>');
-        throw new CliExit(1);
+        fail('       hippo predict show <id>');
     }
     const classTag = stringFlag(flags, 'class')?.trim();
     if (!classTag) {
-        printError('--class is required for prediction creation.');
-        throw new CliExit(1);
+        fail('--class is required for prediction creation.');
     }
     const estimateRaw = flags['estimate'];
     const estimateValue = estimateRaw !== undefined ? Number(estimateRaw) : undefined;
     if (estimateRaw !== undefined && !Number.isFinite(estimateValue)) {
-        printError(`Invalid --estimate: "${estimateRaw}". Must be a number.`);
-        throw new CliExit(1);
+        fail(`Invalid --estimate: "${estimateRaw}". Must be a number.`);
     }
     const estimateUnit = stringFlag(flags, 'unit');
     const targetDate = stringFlag(flags, 'target');

package/dist/cli/print.js

@@ -15,9 +15,11 @@ export function recallEntryText(r, query, showWhy, isGlobal) {
     const bars = Math.round(e.strength * 10);
     const graphMark = r.graphVia ? ` [graph: ${r.graphVia.hops}hop ${r.graphVia.relType}]` : '';
     const lines = [
-        `--- ${e.id} [${e.layer}] ${confLabel}${isGlobal ? ' [global]' : ''}${e.superseded_by ? ' [superseded]' : ''}${graphMark} ` +
+        `--- ${e.id} [${e.layer}] ` +
+            `${confLabel}${isGlobal ? ' [global]' : ''}${e.superseded_by ? ' [superseded]' : ''}${graphMark} ` +
             `score=${fmt(r.score, 3)} strength=${fmt(e.strength)}`,
-        `    [${'█'.repeat(bars)}${'░'.repeat(10 - bars)}] tags: ${e.tags.join(', ') || 'none'} | retrieved: ${e.retrieval_count}x`,
+        `    [${'█'.repeat(bars)}${'░'.repeat(10 - bars)}] tags: ${e.tags.join(', ') || 'none'} | retrieved: ` +
+            `${e.retrieval_count}x`,
     ];
     if (showWhy) {
         const explanation = explainMatch(query, r);

package/dist/cli/projects.js

@@ -1,4 +1,5 @@
-// The `hippo projects` verb: list a store's project names, fold an old worktree name into its repo, repair old tags in one pass.
+// The `hippo projects` verb: list a store's project names, fold an old worktree name into its repo, repair old tags in
+// one pass.
 import * as path from 'path';
 import { execFileSync } from 'child_process';
 import * as api from '../api/index.js';
@@ -17,7 +18,10 @@ function worktreeNames() {
             stdio: ['ignore', 'pipe', 'ignore'],
             windowsHide: true,
         });
-        const paths = out.split(/\r?\n/).filter((l) => l.startsWith('worktree ')).map((l) => path.basename(l.slice('worktree '.length)));
+        const paths = out
+            .split(/\r?\n/)
+            .filter((l) => l.startsWith('worktree '))
+            .map((l) => path.basename(l.slice('worktree '.length)));
         return new Map(paths.slice(1).map((name) => [name, paths[0]]));
     }
     catch {
@@ -32,7 +36,9 @@ function hint(p, worktrees) {
     const main = p.origin ? worktrees.get(p.origin) : undefined;
     if (main)
         return `\n    a worktree of ${main}: hippo projects merge ${p.origin} ${main}`;
-    return p.copiesElsewhere > 0 ? `\n    ${p.copiesElsewhere} of its imported notes are copies also held under another name` : '';
+    return p.copiesElsewhere > 0
+        ? `\n    ${p.copiesElsewhere} of its imported notes are copies also held under another name`
+        : '';
 }
 function count(n, one, many = `${one}s`) {
     return `${n} ${n === 1 ? one : many}`;
@@ -60,11 +66,12 @@ function projectsMerge(ctx, args, flags) {
         return;
     }
     console.log(`${apply ? 'Merged' : 'Dry run: would merge'} ${from} into ${into}:`);
-    console.log(`  ${count(r.setAside.length, 'imported note ' +
-        'copy', 'imported note copies')} set aside (${into} already holds the same note; the rest move under ${into} on the next sync)`);
+    console.log(`  ${count(r.setAside.length, 'imported note ' + 'copy', 'imported note copies')} set aside (${into} already holds the same note; the rest move under ${into} on the next sync)`);
     console.log(`  ${count(r.restamped.length, 'memory', 'memories')} re-tagged, plus ${r.dormantRestamped.length} dormant ` +
         `and ${count(r.compactions, 'compaction record')}`);
-    console.log(apply ? `Backup: ${r.backup}\nEvery id is in the audit log: hippo audit list --op project_merge` : 'Nothing written. Add --apply to run it.');
+    console.log(apply
+        ? `Backup: ${r.backup}\nEvery id is in the audit log: hippo audit list --op project_merge`
+        : 'Nothing written. Add --apply to run it.');
 }
 function projectsRepair(ctx, flags) {
     const root = ctx.hippoRoot;
@@ -75,17 +82,20 @@ function projectsRepair(ctx, flags) {
         return;
     }
     console.log(`${apply ? 'Repaired' : 'Dry run: would repair'} ${root}:`);
-    console.log(`  ${count(r.copies.length, 'imported note ' +
-        'copy', 'imported note copies')} under the wrong project set aside (the note stays under its own, or user-global)`);
+    console.log(`  ${count(r.copies.length, 'imported note ' + 'copy', 'imported note copies')} under the wrong project set aside (the note stays under its own, or user-global)`);
     for (const f of r.folds)
         console.log(`  ${f.from} folded into ${f.into} (its sessions' folders resolve there now)`);
     for (const c of r.collisions) {
-        console.log(`  ${c.name} left as it is: its folders now resolve to ${c.ids.join(', ')}; fold it by hand with hippo projects merge`);
+        console.log(`  ${c.name} left as it is: its folders now resolve to ${c.ids.join(', ')}; fold it by hand with hippo ` +
+            `projects merge`);
     }
     console.log(`  sleep's user-global merged rows: ${r.toProject.length} re-tagged to their parents' project`);
     console.log(`  ${r.setAside.length} set aside (parents in two projects; sleep re-merges them per project)`);
-    console.log(`  ${r.untraced.length} left as they are (no parent left to show which project; check them with hippo inspect <id>)`);
-    console.log(apply ? `Backup: ${r.backup}\nEvery id is in the audit log: hippo audit list --op project_repair` : 'Nothing written. Add --apply to run it.');
+    console.log(`  ${r.untraced.length} left as they are (no parent left to show which project; check them with hippo inspect ` +
+        `<id>)`);
+    console.log(apply
+        ? `Backup: ${r.backup}\nEvery id is in the audit log: hippo audit list --op project_repair`
+        : 'Nothing written. Add --apply to run it.');
 }
 export function handleProjects({ hippoRoot, tenantId, args, flags }) {
     const ctx = cliApiContext(resolveAuthRoot(hippoRoot, flags), tenantId);

package/dist/cli/quality-repair-once.d.ts

@@ -1,3 +1,3 @@
 /** Fault-isolated like the project tag repair: a failure warns, leaves the store unmarked and runs again next time. */
-export declare function repairQualityOnceAt(root: string, tenantId: string): void;
+export declare function repairQualityOnceAt(root: string, tenantId: string): Promise<void>;
 //# sourceMappingURL=quality-repair-once.d.ts.map

package/dist/cli/quality-repair-once.js

@@ -1,13 +1,13 @@
 // Sleep and the daily runner clean a store's old automatic memories once, so an upgrade needs no command.
 import * as path from 'path';
-import { errorMessage, log } from '../util/log.js';
+import { errorMessage, log, errorFields } from '../util/log.js';
 import { getGlobalRoot } from '../sharing/global-store.js';
-import { repairMemoryQualityOnce } from '../api/audit.js';
+import { repairMemoryQualityOnce } from '../api/auth/audit.js';
 import { cliApiContext } from './api-context.js';
 /** Fault-isolated like the project tag repair: a failure warns, leaves the store unmarked and runs again next time. */
-export function repairQualityOnceAt(root, tenantId) {
+export async function repairQualityOnceAt(root, tenantId) {
     try {
-        const result = repairMemoryQualityOnce(cliApiContext(root, tenantId));
+        const result = await repairMemoryQualityOnce(cliApiContext(root, tenantId));
         if (result === null)
             return;
         if (!result.supported) {
@@ -25,13 +25,14 @@ export function repairQualityOnceAt(root, tenantId) {
         const review = result.issues.filter((issue) => issue.disposition === 'review').length;
         if (review > 0) {
             const lead = moved > 0 ? `  ${review} more` : `Checked old automatic memories once after the upgrade: ${review}`;
-            console.log(`${lead} ${review === 1 ? 'looks' : 'look'} doubtful and ${review === 1 ? 'was' : 'were'} kept; hippo audit repair${scope} lists them.`);
+            console.log(`${lead} ${review === 1 ? 'looks' : 'look'} doubtful and ${review === 1 ? 'was' : 'were'} kept; hippo audit ` +
+                `repair${scope} lists them.`);
         }
         for (const warning of result.warnings)
             log.warn(warning);
     }
     catch (err) {
-        log.warn(`memory quality repair skipped, tried again next time: ${errorMessage(err)}`);
+        log.warn(`memory quality repair skipped, tried again next time: ${errorMessage(err)}`, errorFields(err));
     }
 }
 //# sourceMappingURL=quality-repair-once.js.map

package/dist/cli/recall.js

@@ -6,22 +6,20 @@ import { loadConfig } from '../core/config.js';
 import { estimateTokens } from '../util/token-text.js';
 import { dropHeldCopies } from '../util/same-text.js';
 import * as api from '../api/index.js';
-import { detectAnchoring, hashQueryText, biasHintEnabled, snapshotRing } from '../api/recall-history.js';
-import { sessionRing, shownRecallRows } from '../api/recall-record.js';
-import { detectAvailabilityBias } from '../api/availability.js';
-import { cliRecallOrigin, cliRecallReranker, cliRecallSetting, DEFAULT_MAX_NEIGHBORS, fitRecallRows, loadCliRecallContinuity, MAX_HOPS, recallJsonRow, } from '../api/recall-cli.js';
+import { availabilityPool, cutoffClauses, detectRecallHints, handoffText, hashQueryText, printedTokens, sessionRing, sessionTrailText, settleTokens, shownRecallRows, shrinkToFit, snapshotText, suppressionSummary, tokenPurse, } from '../api/cli-surface.js';
+import { cliRecallOrigin, cliRecallReranker, cliRecallSetting, DEFAULT_MAX_NEIGHBORS, fitRecallRows, loadCliRecallContinuity, MAX_HOPS, recallJsonRow, } from '../api/recall/rows.js';
 import { cliApiContext } from './api-context.js';
-import { handoffText, printedTokens, sessionTrailText, settleTokens, snapshotText } from '../api/context-render.js';
 import { printError } from './output.js';
-import { parseLimitFlag, parseBudgetFlag, parseAsOfFlag, engineFlags, boolFlag, flagIsTrue, isBooleanFlag, numberFlag, } from './flag-values.js';
+import { parseLimitFlag, parseBudgetFlag, parseAsOfFlag, engineFlags, boolFlag, flagIsTrue, isBooleanFlag, isStringFlag, numberFlag, stringFlag, stringFlagOrExit, } from './flag-values.js';
 import { requireInit } from './shared.js';
-import { recallEntryText, recallHeading, printActiveTaskSnapshot, printSessionEvents, printHandoff, captureConsole } from './print.js';
+import { recallEntryText, recallHeading, printActiveTaskSnapshot, printSessionEvents, printHandoff, captureConsole, } from './print.js';
 import { hostSessionId, hookStoreRoot } from './hook-runtime.js';
-import { CliExit } from './exit.js';
+import { fail } from './exit.js';
 // JSON.stringify keeps quotes or parens in the matched phrase from blurring the line.
 function planningLine(p) {
-    if (p.hint)
+    if (p.hint) {
         return `Planning fallacy hint (class: ${p.hint.classTag}): ${p.hint.baserateSummary} [detected: ${JSON.stringify(p.hint.detectedPhrase)}]`;
+    }
     if (p.watching) {
         return `Planning fallacy: watching this query (reason: ${p.watching.reason}). ${p.watching.suggestion} ` +
             `[detected: ${JSON.stringify(p.watching.detectedPhrase)}]`;
@@ -29,45 +27,38 @@ function planningLine(p) {
     return null;
 }
 function cutoffLine(shown, s) {
-    const clauses = [];
-    // The residual covers rank, budget and limit drops alike, and fires with no --limit at all.
-    if (s.droppedByBudget > 0)
-        clauses.push(`${s.droppedByBudget} not shown (rank, budget or limit)`);
-    if (s.droppedPreRank > 0)
-        clauses.push(`${s.droppedPreRank} filtered pre-rank`);
-    if (s.summarySubstitutionsAdded > 0)
-        clauses.push(`${s.summarySubstitutionsAdded} summary substitutions added`);
-    if (s.freshTailAdded > 0)
-        clauses.push(`${s.freshTailAdded} fresh-tail added`);
-    if (s.suppressedByInterference > 0)
-        clauses.push(`${s.suppressedByInterference} suppressed by interference`);
-    return clauses.length > 0 ? `Cutoff: showing ${shown} of ${s.totalCandidates} candidates; ${clauses.join('; ')}.` : null;
+    const clauses = cutoffClauses(s);
+    return clauses.length > 0
+        ? `Cutoff: showing ${shown} of ${s.totalCandidates} candidates; ${clauses.join('; ')}.`
+        : null;
 }
 function failWith(message) {
     return () => {
-        printError(message);
-        throw new CliExit(1);
+        fail(message);
     };
 }
 /** `--graph-stream` implies rrf fusion as well as the graph stream; the CLI fuses the local store only. */
 function parseGraphStreamFlags(flags) {
     let hops;
     if (flags['graph-hops'] !== undefined) {
-        if (isBooleanFlag(flags['graph-hops']))
+        if (isBooleanFlag(flags['graph-hops'])) {
             failWith(`--graph-hops requires an integer value 1..${MAX_HOPS} (e.g. --graph-hops 2).`)();
+        }
         const h = Number(flags['graph-hops']);
         if (!Number.isInteger(h) || h < 1 || h > MAX_HOPS) {
-            failWith(`Invalid --graph-hops: "${String(flags['graph-hops'])}". Must be an integer 1..${MAX_HOPS}.`)();
+            failWith(`Invalid --graph-hops: "${stringFlag(flags, 'graph-hops')}". Must be an integer 1..${MAX_HOPS}.`)();
         }
         hops = h;
     }
     let seeds;
     if (flags['graph-seeds'] !== undefined) {
-        if (isBooleanFlag(flags['graph-seeds']))
+        if (isBooleanFlag(flags['graph-seeds'])) {
             failWith('--graph-seeds requires a positive integer value (e.g. --graph-seeds 10).')();
+        }
         const s = Number(flags['graph-seeds']);
-        if (!Number.isInteger(s) || s < 1)
-            failWith(`Invalid --graph-seeds: "${String(flags['graph-seeds'])}". Must be a positive integer.`)();
+        if (!Number.isInteger(s) || s < 1) {
+            failWith(`Invalid --graph-seeds: "${stringFlag(flags, 'graph-seeds')}". Must be a positive integer.`)();
+        }
         seeds = s;
     }
     return { hops, seeds };
@@ -76,11 +67,12 @@ function parseHopsFlags(flags) {
     if (flags['hops'] === undefined)
         return {};
     // A value-less `--hops` parses as true, and Number(true) === 1 would silently run a 1-hop expansion.
-    if (isBooleanFlag(flags['hops']))
+    if (isBooleanFlag(flags['hops'])) {
         return { fail: failWith(`--hops requires an integer value 0..${MAX_HOPS} (e.g. --hops 1).`) };
+    }
     const hops = Number(flags['hops']);
     if (!Number.isInteger(hops) || hops < 0 || hops > MAX_HOPS) {
-        return { fail: failWith(`Invalid --hops: "${String(flags['hops'])}". Must be an integer 0..${MAX_HOPS}.`) };
+        return { fail: failWith(`Invalid --hops: "${stringFlag(flags, 'hops')}". Must be an integer 0..${MAX_HOPS}.`) };
     }
     const raw = flags['max-neighbors'];
     if (raw === undefined)
@@ -94,7 +86,10 @@ function parseHopsFlags(flags) {
     return { value: { hops, maxNeighbors } };
 }
 function parseRerankerFlag(flags) {
-    const name = flags['reranker'] !== undefined ? String(flags['reranker']).trim() : '';
+    const nameRaw = flags['reranker'];
+    if (nameRaw !== undefined && !isStringFlag(nameRaw))
+        return { fail: failWith('--reranker requires a value.') };
+    const name = nameRaw?.trim() ?? '';
     let picked;
     try {
         picked = cliRecallReranker(name);
@@ -125,11 +120,16 @@ function parseSalienceFlag(flags) {
     return { value: threshold };
 }
 function parseChoiceFlag(flags, name, valid) {
-    const value = flags[name] !== undefined ? String(flags[name]).trim() : '';
+    const raw = flags[name];
+    if (raw !== undefined && !isStringFlag(raw)) {
+        return { fail: failWith(`--${name} requires a value. Must be one of: ${valid.join(', ')}.`) };
+    }
+    const value = raw?.trim() ?? '';
     if (!value)
         return {};
-    if (!valid.includes(value))
+    if (!valid.includes(value)) {
         return { fail: failWith(`Invalid --${name}: "${value}". Must be one of: ${valid.join(', ')}.`) };
+    }
     return { value };
 }
 /** Parses every flag a ranking stage reads; the first invalid one in pipeline order becomes `error`. */
@@ -140,7 +140,11 @@ function parseRecallLateFlags(flags) {
     const outcome = parseChoiceFlag(flags, 'outcome', ['success', 'failure', 'partial']);
     const layer = parseChoiceFlag(flags, 'layer', Object.values(Layer));
     const staged = [
-        ['expand', graphHops.fail], ['rerank', reranker.fail], ['salience', salience.fail], ['outcome', outcome.fail], ['layer', layer.fail],
+        ['expand', graphHops.fail],
+        ['rerank', reranker.fail],
+        ['salience', salience.fail],
+        ['outcome', outcome.fail],
+        ['layer', layer.fail],
     ];
     let error;
     for (const [stage, fail] of staged) {
@@ -158,7 +162,8 @@ function parseRecallLateFlags(flags) {
         error,
     };
 }
-/** Runs `hippo recall`: the flags name the ranking core and this verb's presenter, `retrieve` ranks and records, then the block prints. */
+/** Runs `hippo recall`: the flags name the ranking core and this verb's presenter, `retrieve` ranks and records,
+ * then the block prints. */
 async function cmdRecall(hippoRoot, tenantId, query, flags) {
     requireInit(hippoRoot);
     const ctx = cliApiContext(hippoRoot, tenantId);
@@ -173,11 +178,13 @@ async function cmdRecall(hippoRoot, tenantId, query, flags) {
         cliCore: {
             rank: rankOptions(query, flags, o, priced),
             // The global store is a second source for this surface alone, and never when it is the store being searched.
-            sources: { globalRoot: globalRoot !== hippoRoot && priced.globalOn ? globalRoot : undefined },
+            sources: globalRoot !== hippoRoot && priced.globalOn
+                ? { globalRoot, globalStore: cliApiContext(globalRoot, tenantId).store }
+                : undefined,
             note: (line) => printError(line),
             hostSessionId: hostSessionId(),
-            show: (rank, planning) => {
-                slot.presented = presentRecall(ctx, query, o, { rank, ...priced }, planning);
+            show: async (rank, planning) => {
+                slot.presented = await presentRecall(ctx, query, o, { rank, ...priced }, planning);
                 return slot.presented.shown;
             },
         },
@@ -197,16 +204,14 @@ function parseRecallOptions(ctx, flags) {
     const includeSuperseded = boolFlag(flags, 'include-superseded');
     const asOf = parseAsOfFlag(flags);
     // The explicit --scope is the filter input; the detected scope only boosts, so auto-detection never filters.
-    const explicitScope = flags['scope'] !== undefined ? String(flags['scope']).trim() : null;
+    const explicitScope = stringFlagOrExit(flags, 'scope') ?? null;
     const setting = cliRecallSetting(ctx, explicitScope);
     const config = loadConfig(ctx.hippoRoot);
     const minResults = numberFlag(flags, 'min-results');
     const graphStream = flagIsTrue(flags, 'graph-stream') ? parseGraphStreamFlags(flags) : undefined;
     const late = parseRecallLateFlags(flags);
-    const goalTag = flags['goal'] !== undefined ? String(flags['goal']).trim() : '';
-    const sessionId = (flags['session-id'] !== undefined
-        ? String(flags['session-id'])
-        : envHippoSessionId() ?? '').trim();
+    const goalTag = stringFlagOrExit(flags, 'goal') ?? '';
+    const sessionId = (stringFlagOrExit(flags, 'session-id') ?? envHippoSessionId() ?? '').trim();
     return {
         budget, limit, asJson, showWhy, includeSuperseded, asOf, setting, tenantId: ctx.tenantId,
         explicitScope, config, minResults, graphStream, late, goalTag, sessionId,
@@ -226,8 +231,14 @@ function rankOptions(query, flags, o, priced) {
     // Engines spend the budget on the text each result prints as, less the header, so selection and print agree.
     const entryBudget = Math.max(0, o.budget - printedTokens(recallHeading(o.budget, o.budget, query)));
     return {
-        budget: entryBudget, cost: priced.printCost, limit: o.limit, why: o.showWhy, includeSuperseded: o.includeSuperseded, asOf: o.asOf,
-        explicitScope: o.explicitScope, activeScope: o.setting.activeScope,
+        budget: entryBudget,
+        cost: priced.printCost,
+        limit: o.limit,
+        why: o.showWhy,
+        includeSuperseded: o.includeSuperseded,
+        asOf: o.asOf,
+        explicitScope: o.explicitScope,
+        activeScope: o.setting.activeScope,
         search: {
             ...engineFlags(flags, o.config),
             multihop: flagIsTrue(flags, 'multihop') || o.config.multihop.enabled,
@@ -253,23 +264,17 @@ function recallHinter(query, o, rank) {
     // HIPPO_ANCHORING=off and HIPPO_AVAILABILITY=off skip the work entirely.
     const anchorRing = sessionRing('cli', tenantId, sessionId);
     const queryHash = hashQueryText(query);
-    const availabilityPool = biasHintEnabled('availability')
-        ? [...rank.localEntries, ...rank.globalEntries].map((e) => ({ id: e.id, created: e.created }))
-        : null;
+    const pool = availabilityPool(() => [...rank.localEntries, ...rank.globalEntries]);
     const hintsFor = (list, held) => {
-        const anchoring = anchorRing ? detectAnchoring(snapshotRing(anchorRing), queryHash, list[0]?.entry.id ?? null) : null;
-        const availability = availabilityPool
-            ? detectAvailabilityBias({ topK: list.map((r) => ({ id: r.entry.id, created: r.entry.created })), pool: availabilityPool })
-            : null;
-        const summary = {
-            // The published total includes graph-surfaced rows, so total == preRank + byBudget + returned holds for callers.
+        const { anchoring, availability } = detectRecallHints({ list, pool, anchorRing, queryHash });
+        const summary = suppressionSummary({
+            // The total includes graph-surfaced rows, so total == preRank + byBudget + returned holds for callers.
             totalCandidates: rank.totalCandidates + rank.graphAdded,
             droppedPreRank: rank.droppedPreRank + held,
             droppedByBudget: Math.max(0, rank.totalCandidates + rank.graphAdded - rank.droppedPreRank - held - list.length),
             summarySubstitutionsAdded: 0,
             freshTailAdded: 0,
-            suppressedByInterference: anchoring?.reason === 'memory_dominance' ? 1 : 0, // a query_repeat is a re-ask, not competition
-        };
+        }, anchoring);
         return { anchoring, availability, summary };
     };
     return { anchorRing, hintsFor };
@@ -325,59 +330,89 @@ function renderRecallBlock(list, h, v) {
             console.log(entryText(r));
     }));
 }
-/** Pays the continuity sections and the plan hint first, then fits the memories into what is left. */
-function fitRecallBlock(query, o, ranked, loaded, planning) {
-    const { budget } = o;
+/** Pays the continuity sections in print order after the header; one that does not fit is dropped. */
+function payContinuity(loaded, sectionBudget) {
     let { activeSnapshot, sessionHandoff, recentSessionEvents } = loaded;
-    // Sections print ahead of the memories, so they are paid first, after the header; one that does not fit is dropped.
-    const sectionBudget = budget - printedTokens(recallHeading(budget, budget, query));
-    let left = sectionBudget;
-    const pays = (tokens) => { if (tokens > left)
-        return false; left -= tokens; return true; };
+    const { pays, left } = tokenPurse(sectionBudget);
     if (activeSnapshot && !pays(printedTokens(snapshotText(activeSnapshot))))
         activeSnapshot = null;
     if (sessionHandoff && !pays(printedTokens(handoffText(sessionHandoff))))
         sessionHandoff = null;
-    if (recentSessionEvents.length > 0 && !pays(printedTokens(sessionTrailText(recentSessionEvents))))
+    if (recentSessionEvents.length > 0 && !pays(printedTokens(sessionTrailText(recentSessionEvents)))) {
         recentSessionEvents = [];
-    const continuityTokens = sectionBudget - left;
+    }
     const continuity = { activeSnapshot, sessionHandoff, recentSessionEvents };
+    return { continuity, continuityTokens: sectionBudget - left() };
+}
+/** Drops the lowest-ranked entry until the whole block, hints and header included, fits the budget. */
+function renderWithinBudget(fitted, hintsFor, view, floor, budget) {
+    // Copies go after every cut, so a merged row the budget drops never hides its sources.
+    const render = (kept) => {
+        const results = dropHeldCopies(fitted.slice(0, kept), (r) => r.entry);
+        const hints = hintsFor(results, kept - results.length);
+        return { results, hints, recallText: renderRecallBlock(results, hints, view) };
+    };
+    return shrinkToFit(fitted.length, floor, budget, render, (r) => r.recallText);
+}
+/** Pays the continuity sections and the plan hint first, then fits the memories into what is left. */
+function fitRecallBlock(query, o, ranked, loaded, planning) {
+    const { budget } = o;
+    // Sections print ahead of the memories, so they are paid first, after the header; one that does not fit is dropped.
+    const sectionBudget = budget - printedTokens(recallHeading(budget, budget, query));
+    const { continuity, continuityTokens } = payContinuity(loaded, sectionBudget);
+    let left = sectionBudget - continuityTokens;
+    const { activeSnapshot, sessionHandoff, recentSessionEvents } = continuity;
     const hasContinuity = activeSnapshot !== null || sessionHandoff !== null || recentSessionEvents.length > 0;
     // The baserate hint depends on the query alone, so `retrieve` evaluates it and this only prices the line.
     const planText = planningLine(planning);
-    const showPlan = planText !== null && pays(printedTokens(`${planText}\n`));
-    const cmdPlanningFallacyHint = showPlan ? planning.hint ?? null : null;
-    const cmdPlanningFallacyWatching = showPlan ? planning.watching ?? null : null;
+    const planTokens = planText === null ? 0 : printedTokens(`${planText}\n`);
+    const showPlan = planText !== null && planTokens <= left;
+    if (showPlan)
+        left -= planTokens;
+    const cmdPlanningFallacyHint = showPlan ? (planning.hint ?? null) : null;
+    const cmdPlanningFallacyWatching = showPlan ? (planning.watching ?? null) : null;
     // The first --min-results are kept whatever they cost (the documented exception); the rest skip and continue.
     const floor = o.minResults ?? 1;
     const fitted = fitRecallRows(ranked.rank.results, left, floor, ranked.printCost);
-    // Copies go after every cut, so a merged row the budget drops never hides its sources.
-    const shown = (n) => dropHeldCopies(fitted.slice(0, n), (r) => r.entry);
-    let kept = fitted.length;
-    let results = shown(kept);
     const { anchorRing, hintsFor } = recallHinter(query, o, ranked.rank);
-    const view = { query, showWhy: o.showWhy, showPlan, planText, hasContinuity, continuity, entryText: ranked.entryText };
-    let hints = hintsFor(results, kept - results.length);
-    let recallText = renderRecallBlock(results, hints, view);
-    // The hints, Cutoff line and header vary with the list, so the lowest-ranked entry goes until the whole block fits.
-    while (kept > floor && estimateTokens(recallText) > budget) {
-        kept--;
-        results = shown(kept);
-        hints = hintsFor(results, kept - results.length);
-        recallText = renderRecallBlock(results, hints, view);
-    }
-    return { results, hints, recallText, continuity, continuityTokens, cmdPlanningFallacyHint, cmdPlanningFallacyWatching, anchorRing };
+    const view = {
+        query,
+        showWhy: o.showWhy,
+        showPlan,
+        planText,
+        hasContinuity,
+        continuity,
+        entryText: ranked.entryText,
+    };
+    const { results, hints, recallText } = renderWithinBudget(fitted, hintsFor, view, floor, budget);
+    return {
+        results,
+        hints,
+        recallText,
+        continuity,
+        continuityTokens,
+        cmdPlanningFallacyHint,
+        cmdPlanningFallacyWatching,
+        anchorRing,
+    };
 }
-/** The presenter `retrieve` calls once ranking ends: fits and renders the block, and names the rows and hint rows to record. */
-function presentRecall(ctx, query, o, ranked, planning) {
+/** The presenter `retrieve` calls once ranking ends: fits and
+ * renders the block, and names the rows and hint rows to record. */
+async function presentRecall(ctx, query, o, ranked, planning) {
     // Loaded before the zero-result branch, so a no-match query with live continuity still returns a resume packet.
-    const fit = fitRecallBlock(query, o, ranked, loadCliRecallContinuity(ctx, o.setting, o.includeContinuity), planning);
+    const loaded = await loadCliRecallContinuity(ctx, o.setting, o.includeContinuity);
+    const fit = fitRecallBlock(query, o, ranked, loaded, planning);
     const { results, hints } = fit;
     const text = recallOutput(query, o, fit, ranked.isGlobal);
     const audit = shownRecallRows({ tenantId: o.tenantId, actor: 'cli' }, {
-        query, ring: fit.anchorRing, topId: results[0]?.entry.id ?? null, anchoring: hints.anchoring, availability: hints.availability,
+        query,
+        ring: fit.anchorRing,
+        topId: results[0]?.entry.id ?? null,
+        anchoring: hints.anchoring,
+        availability: hints.availability,
     });
-    // The token ledger books the text this recall prints, on whichever exit it takes; the ring keeps the hint the final detect made.
+    // The token ledger books the text this recall prints, on whichever
+    // exit it takes; the ring keeps the hint the final detect made.
     return { text, shown: { results, audit, tokens: estimateTokens(text), anchoredOn: hints.anchoring?.memoryId } };
 }
 /** What this recall prints: the JSON object, or the fitted block. */
@@ -386,7 +421,9 @@ function recallOutput(query, o, fit, isGlobal) {
     const { results, recallText } = fit;
     if (results.length === 0) {
         // HTTP and MCP surface the hint whatever matched, so the zero-result JSON keeps it for parity.
-        return asJson ? JSON.stringify({ query, results: [], total: 0, ...recallJsonTail(fit, includeContinuity) }) : recallText;
+        return asJson
+            ? JSON.stringify({ query, results: [], total: 0, ...recallJsonTail(fit, includeContinuity) })
+            : recallText;
     }
     if (!asJson)
         return recallText;
@@ -426,8 +463,7 @@ function recallJsonTail(fit, includeContinuity) {
 export async function handleRecall({ hippoRoot, tenantId, args, flags }) {
     const query = args.join(' ').trim();
     if (!query) {
-        printError('Please provide a search query.');
-        throw new CliExit(1);
+        fail('Please provide a search query.');
     }
     await cmdRecall(hookStoreRoot(hippoRoot), tenantId, query, flags);
 }