hippo-memory 1.70.0 → 1.71.0

package/dist/cli/decisions.js

@@ -1,16 +1,16 @@
 // First-class object verbs for predictions, decisions and incidents.
-import { writeEntry } from '../store/entry-writes.js';
-import { readEntry } from '../store/entry-reads.js';
+import { getMemory } from '../api/memories.js';
 import { extractPathTags } from '../search/path-context.js';
 import * as predictionsModule from '../store/predictions.js';
 import * as decisionsModule from '../objects/decisions.js';
 import * as incidentsModule from '../objects/incidents.js';
-import { resolveTenantId } from '../store/tenant.js';
 import { printError } from './output.js';
-import { nonEmptyStringFlag, parseListLimit, flagIsTrue, stringFlag } from './flag-values.js';
+import { nonEmptyStringFlag, parseListLimit, flagIsTrue, isStringFlag, stringFlag } from './flag-values.js';
 import { requireInit } from './shared.js';
+import { cliApiContext } from './api-context.js';
 import { closeObject, foundOrExit, idArgOrExit, listObjects, printLifecycleTail, requireStatus } from './object-verbs.js';
 import { errorMessage } from '../util/log.js';
+import { CliExit } from './exit.js';
 const BASERATE_DECIMALS = 3;
 const DECISION = { cmd: 'decide', noun: 'Decision', idLabel: 'decision' };
 const INCIDENT = { cmd: 'incident', noun: 'Incident', idLabel: 'incident' };
@@ -20,28 +20,28 @@ function parseObjectId(idRaw, noun) {
     const id = parseInt(String(idRaw), 10);
     if (!Number.isFinite(id) || id <= 0) {
         printError(`Invalid ${noun} id: "${idRaw}"`);
-        process.exit(1);
+        throw new CliExit(1);
     }
     return id;
 }
-// ---------------------------------------------------------------------------
 // Prediction first-class object
-// ---------------------------------------------------------------------------
 function predictClose(hippoRoot, tenantId, args, flags) {
     const id = idArgOrExit(args, 'Usage: hippo predict close <id> --state <closed|closed-unknown> [--actual <v>] [--note "..."]', 'prediction', parseObjectId);
     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 (!predictionsModule.VALID_CLOSURE_STATES.has(stateRaw) || stateRaw === 'open') {
         printError(`Invalid --state: "${stateRaw}". Must be one of: closed | closed-unknown.`);
-        process.exit(1);
+        throw new CliExit(1);
     }
     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.`);
-        process.exit(1);
+        throw new CliExit(1);
     }
     const closureNote = stringFlag(flags, 'note');
     const closed = predictionsModule.closePrediction(hippoRoot, tenantId, id, {
+        // SAFETY: the check above exits unless stateRaw is in VALID_CLOSURE_STATES.
         closureState: stateRaw,
         actualValue,
         closureNote,
@@ -64,7 +64,7 @@ function loadPredictionList(hippoRoot, tenantId, status, classTag, limit) {
     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.');
-        process.exit(1);
+        throw new CliExit(1);
     }
     return predictionsModule.loadPredictionsByClass(hippoRoot, tenantId, classTag, {
         closureState,
@@ -117,7 +117,7 @@ function predictBaserate(hippoRoot, tenantId, flags) {
     const classTag = stringFlag(flags, 'class')?.trim();
     if (!classTag) {
         printError('Usage: hippo predict baserate --class <c>');
-        process.exit(1);
+        throw new CliExit(1);
     }
     const baserate = predictionsModule.computePredictionBaserate(hippoRoot, tenantId, classTag);
     if (baserate.nClosed === 0) {
@@ -140,9 +140,8 @@ function predictBaserate(hippoRoot, tenantId, flags) {
     if (baserate.mae !== null)
         console.log(`  mae:              ${baserate.mae.toFixed(BASERATE_DECIMALS)}`);
 }
-export function cmdPredict(hippoRoot, args, flags) {
+export function handlePredict({ hippoRoot, tenantId, args, flags }) {
     requireInit(hippoRoot);
-    const tenantId = resolveTenantId({});
     const subcommand = args[0] ?? '';
     if (subcommand === 'close')
         return predictClose(hippoRoot, tenantId, args, flags);
@@ -161,18 +160,18 @@ function predictCreate(hippoRoot, tenantId, claimText, flags) {
         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>');
-        process.exit(1);
+        throw new CliExit(1);
     }
     const classTag = stringFlag(flags, 'class')?.trim();
     if (!classTag) {
         printError('--class is required for prediction creation.');
-        process.exit(1);
+        throw new CliExit(1);
     }
     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.`);
-        process.exit(1);
+        throw new CliExit(1);
     }
     const estimateUnit = stringFlag(flags, 'unit');
     const targetDate = stringFlag(flags, 'target');
@@ -215,9 +214,8 @@ function decideGet(hippoRoot, tenantId, args) {
 function decideClose(hippoRoot, tenantId, args) {
     closeObject(args, DECISION, (id) => decisionsModule.closeDecision(hippoRoot, tenantId, id), parseObjectId);
 }
-export function cmdDecide(hippoRoot, args, flags) {
+export async function handleDecide({ hippoRoot, tenantId, args, flags }) {
     requireInit(hippoRoot);
-    const tenantId = resolveTenantId({});
     const subcommand = args[0] ?? '';
     if (subcommand === 'list')
         return decideList(hippoRoot, tenantId, flags);
@@ -226,9 +224,9 @@ export function cmdDecide(hippoRoot, args, flags) {
     if (subcommand === 'close')
         return decideClose(hippoRoot, tenantId, args);
     // Default subcommand: create. args[0] is the decision text.
-    decideCreate(hippoRoot, tenantId, subcommand, flags);
+    await decideCreate(hippoRoot, tenantId, subcommand, flags);
 }
-function decideCreate(hippoRoot, tenantId, decisionText, flags) {
+async function decideCreate(hippoRoot, tenantId, decisionText, flags) {
     if (!decisionText)
         exitWithDecideUsage();
     const context = nonEmptyStringFlag(flags, 'context');
@@ -236,21 +234,18 @@ function decideCreate(hippoRoot, tenantId, decisionText, flags) {
     // than silently creating a non-superseding decision.
     if (flagIsTrue(flags, 'supersedes')) {
         printError('--supersedes requires a memory id, e.g. hippo decide "<text>" --supersedes mem_abc123.');
-        process.exit(1);
+        throw new CliExit(1);
     }
     const supersedesMemId = stringFlag(flags, 'supersedes') ?? null;
-    // Backward-compat: --supersedes takes a MEMORY id. Validate it exists and
-    // resolve it to the active decision row (if any). Commit the
-    // canonical table create+supersede FIRST (inside saveDecision's SAVEPOINT),
-    // weaken the old memory LAST (best-effort) so a memory-write failure cannot
-    // leave the memory stale without the table reflecting the supersession.
+    // Commit the table create+supersede first (inside saveDecision's SAVEPOINT) and weaken the old memory last, best-effort,
+    // so a memory-write failure cannot leave the memory stale while the table shows the supersession.
     let supersedesDecisionId;
     let oldEntry = null;
     if (supersedesMemId) {
-        oldEntry = readEntry(hippoRoot, supersedesMemId, tenantId) ?? null;
+        oldEntry = await getMemory(cliApiContext(hippoRoot, tenantId), supersedesMemId);
         if (!oldEntry) {
             printError(`Memory ${supersedesMemId} not found.`);
-            process.exit(1);
+            throw new CliExit(1);
         }
         supersedesDecisionId =
             decisionsModule.resolveActiveDecisionIdByMemory(hippoRoot, tenantId, supersedesMemId) ?? undefined;
@@ -275,20 +270,13 @@ function exitWithDecideUsage() {
     printError('       hippo decide list [--status active|superseded|closed|all] [--limit N]');
     printError('       hippo decide get <id>');
     printError('       hippo decide close <id>');
-    process.exit(1);
+    throw new CliExit(1);
 }
 function weakenSupersededMemory(hippoRoot, oldEntry, supersedesMemId) {
-    // Legacy memory-weaken (best-effort, LAST): half-life halved, marked stale +
-    // 'superseded' tag. Preserves the exact pre-promotion behavior for the memory
-    // mirror; the canonical table supersession already committed above.
-    // Best-effort: saveDecision already committed. Failing here would make a retry find no active
+    // Best-effort and last: saveDecision already committed. Failing here would make a retry find no active
     // decision for the old memory and create a duplicate active successor, so warn instead.
     try {
-        oldEntry.half_life_days = Math.max(1, Math.floor(oldEntry.half_life_days / 2));
-        oldEntry.confidence = 'stale';
-        if (!oldEntry.tags.includes('superseded'))
-            oldEntry.tags.push('superseded');
-        writeEntry(hippoRoot, oldEntry);
+        decisionsModule.weakenSupersededMemory(hippoRoot, oldEntry);
     }
     catch (e) {
         printError(`  warning: decision recorded and superseded, but failed to weaken the prior memory ${supersedesMemId}: ${errorMessage(e)}`);
@@ -341,7 +329,7 @@ function incidentResolve(hippoRoot, tenantId, args, flags) {
     const resolutionRaw = stringFlag(flags, 'resolution');
     if (!resolutionRaw?.trim()) {
         printError('--resolution requires a non-empty value, e.g. hippo incident resolve <id> --resolution "root cause fixed".');
-        process.exit(1);
+        throw new CliExit(1);
     }
     const resolved = incidentsModule.resolveIncident(hippoRoot, tenantId, id, resolutionRaw);
     console.log(`Incident #${resolved.id} resolved.`);
@@ -349,9 +337,8 @@ function incidentResolve(hippoRoot, tenantId, args, flags) {
 function incidentClose(hippoRoot, tenantId, args) {
     closeObject(args, INCIDENT, (id) => incidentsModule.closeIncident(hippoRoot, tenantId, id));
 }
-export function cmdIncident(hippoRoot, args, flags) {
+export function handleIncident({ hippoRoot, tenantId, args, flags }) {
     requireInit(hippoRoot);
-    const tenantId = resolveTenantId({});
     const subcommand = args[0] ?? '';
     if (subcommand === 'list')
         return incidentList(hippoRoot, tenantId, flags);
@@ -361,9 +348,8 @@ export function cmdIncident(hippoRoot, args, flags) {
         return incidentResolve(hippoRoot, tenantId, args, flags);
     if (subcommand === 'close')
         return incidentClose(hippoRoot, tenantId, args);
-    // Default subcommand: open (create). Accept both the documented
-    // `incident open "<text>"` form and the bare `incident "<text>"` form: for the
-    // `open` keyword the text is args[1], otherwise args[0] IS the text.
+    // Default subcommand is open (create): accept both `incident open "<text>"` and bare `incident "<text>"`;
+    // for the `open` keyword the text is args[1], otherwise args[0] is the text.
     incidentCreate(hippoRoot, tenantId, subcommand === 'open' ? (args[1] ?? '') : subcommand, flags);
 }
 function incidentCreate(hippoRoot, tenantId, incidentText, flags) {
@@ -373,7 +359,7 @@ function incidentCreate(hippoRoot, tenantId, incidentText, flags) {
         printError('       hippo incident get <id>');
         printError('       hippo incident resolve <id> --resolution "<text>"');
         printError('       hippo incident close <id>');
-        process.exit(1);
+        throw new CliExit(1);
     }
     const context = nonEmptyStringFlag(flags, 'context');
     // --link is a repeatable flag (collected into an array by parseArgs). A
@@ -383,12 +369,12 @@ function incidentCreate(hippoRoot, tenantId, incidentText, flags) {
     if (Array.isArray(linkRaw)) {
         linkedMemoryIds = linkRaw;
     }
-    else if (typeof linkRaw === 'string') {
+    else if (isStringFlag(linkRaw)) {
         linkedMemoryIds = [linkRaw];
     }
     else if (linkRaw === true) {
         printError('--link requires a memory id, e.g. hippo incident "<text>" --link mem_abc123.');
-        process.exit(1);
+        throw new CliExit(1);
     }
     const incidentPathTags = extractPathTags(process.cwd());
     const created = incidentsModule.saveIncident(hippoRoot, tenantId, {

package/dist/cli/eval.js

@@ -3,7 +3,7 @@ import * as path from 'path';
 import * as fs from 'fs';
 import { loadAllEntries } from '../store/entry-reads.js';
 import { loadConfig } from '../core/config.js';
-import { getGlobalRoot } from '../sharing/shared.js';
+import { getGlobalRoot } from '../sharing/global-store.js';
 import { runEval, bootstrapCorpus, compareSummaries } from '../eval/eval.js';
 import { runFeatureEval, formatResult, resultToBaseline, detectRegressions } from '../eval/eval-suite.js';
 import { PACKAGE_VERSION } from '../util/version.js';
@@ -12,6 +12,7 @@ import { requireInit } from './shared.js';
 import { fmt } from './print.js';
 import { boolFlag } from './flag-values.js';
 import { errorMessage } from '../util/log.js';
+import { CliExit } from './exit.js';
 const HIT_TOP_K = 10;
 const MAX_FAILING_SHOWN = 10;
 const TOP_IDS_SHOWN = 3;
@@ -44,7 +45,7 @@ async function cmdEval(hippoRoot, corpusPath, flags) {
     }
     if (minMrr !== null && summary.meanMrr < minMrr) {
         printError(`MRR ${fmt(summary.meanMrr, 4)} below threshold ${minMrr}`);
-        process.exit(1);
+        throw new CliExit(1);
     }
     if (comparePath)
         printEvalCompare(summary, comparePath, asJson);
@@ -85,11 +86,12 @@ function writeBootstrapCorpus(entries, flags) {
 async function runEvalSuite(hippoRoot, flags, asJson, minMrr) {
     const baselinePath = flags['baseline'] ? String(flags['baseline']) : path.join(hippoRoot, 'eval-baseline.json');
     let baseline;
-    if (fs.existsSync(baselinePath)) {
-        try {
-            baseline = JSON.parse(fs.readFileSync(baselinePath, 'utf8'));
-        }
-        catch {
+    try {
+        baseline = JSON.parse(fs.readFileSync(baselinePath, 'utf8'));
+    }
+    catch (err) {
+        // No baseline file is a first run and says nothing; a file that is there and cannot be used warns.
+        if (!(err instanceof Error && 'code' in err && err.code === 'ENOENT')) {
             printError(`Warning: eval baseline ${baselinePath} is unreadable; running without it.`);
         }
     }
@@ -109,7 +111,7 @@ async function runEvalSuite(hippoRoot, flags, asJson, minMrr) {
     if (baseline) {
         const report = detectRegressions(baseline, result);
         if (report.verdict === 'REGRESSION' && minMrr === null) {
-            process.exit(1);
+            throw new CliExit(1);
         }
     }
 }
@@ -117,11 +119,11 @@ async function runEvalSuite(hippoRoot, flags, asJson, minMrr) {
 function readCorpus(corpusPath) {
     if (!corpusPath) {
         printError('Usage: hippo eval <corpus.json>  OR  hippo eval --suite [--save-baseline]  OR  hippo eval --bootstrap');
-        process.exit(1);
+        throw new CliExit(1);
     }
     if (!fs.existsSync(corpusPath)) {
         printError(`Corpus file not found: ${corpusPath}`);
-        process.exit(1);
+        throw new CliExit(1);
     }
     let cases;
     try {
@@ -132,7 +134,7 @@ function readCorpus(corpusPath) {
     }
     catch (err) {
         printError(`Failed to read corpus: ${errorMessage(err)}`);
-        process.exit(1);
+        throw new CliExit(1);
     }
     return cases;
 }
@@ -176,7 +178,7 @@ function printEvalSummary(summary, showCases) {
 function printEvalCompare(summary, comparePath, asJson) {
     if (!fs.existsSync(comparePath)) {
         printError(`Baseline file not found: ${comparePath}`);
-        process.exit(1);
+        throw new CliExit(1);
     }
     let baseline;
     try {
@@ -184,7 +186,7 @@ function printEvalCompare(summary, comparePath, asJson) {
     }
     catch (err) {
         printError(`Failed to parse baseline: ${errorMessage(err)}`);
-        process.exit(1);
+        throw new CliExit(1);
     }
     const cmp = compareSummaries(baseline, summary);
     if (asJson) {

package/dist/cli/exit.d.ts

@@ -0,0 +1,6 @@
+/** Thrown after the verb has printed its own message, so it carries the exit code and nothing for the entry to print. */
+export declare class CliExit extends Error {
+    readonly code: number;
+    constructor(code: number);
+}
+//# sourceMappingURL=exit.d.ts.map

package/dist/cli/exit.js

@@ -0,0 +1,11 @@
+// The one error a CLI verb throws to stop its command; runCli is the one place that turns it into the process exit code.
+/** Thrown after the verb has printed its own message, so it carries the exit code and nothing for the entry to print. */
+export class CliExit extends Error {
+    code;
+    constructor(code) {
+        super(`hippo exits with code ${code}`);
+        this.name = 'CliExit';
+        this.code = code;
+    }
+}
+//# sourceMappingURL=exit.js.map

package/dist/cli/explain.d.ts

@@ -1,4 +1,3 @@
-import { type CliFlags, type CommandContext } from './flag-values.js';
-export declare function cmdExplain(hippoRoot: string, query: string, flags: CliFlags): Promise<void>;
+import { type CommandContext } from './flag-values.js';
 export declare function handleExplain({ hippoRoot, args, flags }: CommandContext): Promise<void>;
 //# sourceMappingURL=explain.d.ts.map

package/dist/cli/explain.js

@@ -7,14 +7,16 @@ import { DEFAULT_RECALL_BUDGET } from '../core/search-types.js';
 import { loadConfig } from '../core/config.js';
 import { dropHeldCopies } from '../util/same-text.js';
 import { detectScope } from '../sharing/scope.js';
-import { getGlobalRoot } from '../sharing/shared.js';
+import { getGlobalRoot } from '../sharing/global-store.js';
 import * as api from '../api/index.js';
 import { resolveTenantId } from '../store/tenant.js';
+import { cliApiContext } from './api-context.js';
 import { printedTokens } from '../api/context-render.js';
 import { printError } from './output.js';
 import { parseLimitFlag, parseBudgetFlag, parseAsOfFlag, engineFlags, boolFlag } from './flag-values.js';
 import { requireInit } from './shared.js';
 import { fmt, recallEntryText, recallHeading } from './print.js';
+import { CliExit } from './exit.js';
 const EXPLAIN_PREVIEW_CHARS = 48;
 /** The SQL predicate drops denied rows before the window, so an unscoped probe counts what the policy hides. */
 function noteScopeHidden(hippoRoot, globalRoot, query, tenantId, requested) {
@@ -28,7 +30,7 @@ function noteScopeHidden(hippoRoot, globalRoot, query, tenantId, requested) {
         printError(`[note] ${hidden} candidate${hidden === 1 ? '' : 's'} hidden by recall scope policy (pass an explicit --scope to inspect).`);
     }
 }
-export async function cmdExplain(hippoRoot, query, flags) {
+async function cmdExplain(hippoRoot, query, flags) {
     requireInit(hippoRoot);
     const budget = parseBudgetFlag(flags['budget'], DEFAULT_RECALL_BUDGET);
     const limit = parseLimitFlag(flags['limit']);
@@ -49,7 +51,7 @@ export async function cmdExplain(hippoRoot, query, flags) {
     const cost = (r) => printedTokens(recallEntryText(r, query, false, explainGlobalOn && !explainIndex.entries[r.entry.id]));
     const entryBudget = Math.max(0, budget - printedTokens(recallHeading(budget, budget, query)));
     const slot = {};
-    await api.retrieve({ hippoRoot, tenantId, actor: api.adminActor('cli') }, {
+    await api.retrieve(cliApiContext(hippoRoot, tenantId), {
         query,
         cliCore: {
             rank: {
@@ -166,7 +168,7 @@ export async function handleExplain({ hippoRoot, args, flags }) {
     const query = args.join(' ').trim();
     if (!query) {
         printError('Please provide a search query.');
-        process.exit(1);
+        throw new CliExit(1);
     }
     await cmdExplain(hippoRoot, query, flags);
 }

package/dist/cli/flag-values.d.ts

@@ -1,19 +1,24 @@
 import type { RecallSearchOpts } from '../api/recall-pipeline.js';
 import type { HippoConfig } from '../core/config.js';
+export declare function isBooleanFlag(value: string | boolean | string[] | undefined): value is boolean;
+export declare function isStringFlag(value: string | boolean | string[] | undefined): value is string;
 export declare function parseLimitFlag(value: string | boolean | string[] | undefined): number;
 export declare function parseCountFlag(value: string | boolean | string[] | undefined): number;
 export declare function parseBudgetFlag(value: string | boolean | string[] | undefined, fallback: number): number;
 export type CliFlags = Record<string, string | boolean | string[]>;
-export declare function parsePositiveId(idRaw: unknown, label: string): number;
+export declare function parsePositiveId(idRaw: string | undefined, label: string): number;
 export declare function parseListLimit(flags: CliFlags): number;
 export declare function stringFlag(flags: CliFlags, name: string): string | undefined;
 export declare function nonEmptyStringFlag(flags: CliFlags, name: string): string | undefined;
+export declare function stringListFlag(flags: CliFlags, name: string): string[] | undefined;
+export declare function isOneOf<T extends string>(allowed: readonly T[], value: string): value is T;
 export declare function numberFlag(flags: CliFlags, name: string): number | undefined;
 export declare function boolFlag(flags: CliFlags, name: string): boolean;
 export declare function flagIsTrue(flags: CliFlags, name: string): boolean;
 /** What the command table hands each verb's run(). */
 export interface CommandContext {
     readonly hippoRoot: string;
+    readonly tenantId: string;
     readonly args: string[];
     readonly flags: CliFlags;
 }

package/dist/cli/flag-values.js

@@ -1,5 +1,12 @@
 // Readers that turn parsed CLI flags into typed values, and the flag types they share.
 import { printError } from './output.js';
+import { CliExit } from './exit.js';
+export function isBooleanFlag(value) {
+    return typeof value === 'boolean';
+}
+export function isStringFlag(value) {
+    return typeof value === 'string';
+}
 export function parseLimitFlag(value) {
     if (!value)
         return Infinity;
@@ -16,15 +23,15 @@ export function parseBudgetFlag(value, fallback) {
     if (value === undefined)
         return fallback;
     // A value-less flag and a junk value are different typos; the --hops guard already splits them.
-    if (typeof value !== 'string') {
+    if (!isStringFlag(value)) {
         printError('--budget requires an integer value (e.g. --budget 1500).');
-        process.exit(1);
+        throw new CliExit(1);
     }
     // Number(), like the --hops guard: parseInt('12abc') is 12, silently accepting what this message rejects.
     const parsed = Number(value);
     if (!Number.isInteger(parsed) || parsed < 0) {
         printError(`Invalid --budget: "${value}". Must be a non-negative integer.`);
-        process.exit(1);
+        throw new CliExit(1);
     }
     return parsed;
 }
@@ -34,7 +41,7 @@ export function parsePositiveId(idRaw, label) {
     const id = parseInt(s, 10);
     if (!/^\d+$/.test(s) || id <= 0 || !Number.isSafeInteger(id)) {
         printError(`Invalid ${label} id: "${idRaw}" (expected a positive integer).`);
-        process.exit(1);
+        throw new CliExit(1);
     }
     return id;
 }
@@ -43,22 +50,32 @@ export function parseListLimit(flags) {
     const limit = limitRaw !== undefined ? parseInt(String(limitRaw), 10) : 100;
     if (!Number.isFinite(limit) || limit <= 0) {
         printError(`Invalid --limit: "${limitRaw}". Must be a positive integer.`);
-        process.exit(1);
+        throw new CliExit(1);
     }
     return limit;
 }
 // A value-less flag is `true` and a repeated one is a string[]; only a string counts here.
 export function stringFlag(flags, name) {
     const v = flags[name];
-    return typeof v === 'string' ? v : undefined;
+    return isStringFlag(v) ? v : undefined;
 }
 // An empty value reads as absent, so `--change ""` keeps the default.
 export function nonEmptyStringFlag(flags, name) {
     return stringFlag(flags, name) || undefined;
 }
+// A repeated flag is already a list; a single value is a comma-separated list.
+export function stringListFlag(flags, name) {
+    const v = flags[name];
+    if (Array.isArray(v))
+        return v;
+    return isStringFlag(v) ? v.split(',').map((t) => t.trim()).filter(Boolean) : undefined;
+}
+export function isOneOf(allowed, value) {
+    return allowed.some((a) => a === value);
+}
 export function numberFlag(flags, name) {
     const v = flags[name];
-    return typeof v === 'string' ? Number(v) : undefined;
+    return isStringFlag(v) ? Number(v) : undefined;
 }
 // Any truthy value counts, so a string value is true too.
 export function boolFlag(flags, name) {
@@ -72,7 +89,7 @@ export function parseAsOfFlag(flags) {
     const asOf = stringFlag(flags, 'as-of');
     if (asOf !== undefined && Number.isNaN(new Date(asOf).getTime())) {
         printError(`Error: --as-of value "${asOf}" is not a valid ISO date (e.g. 2026-04-22 or 2026-04-22T12:00:00Z).`);
-        process.exit(1);
+        throw new CliExit(1);
     }
     return asOf;
 }
@@ -89,14 +106,14 @@ export function engineFlags(flags, config) {
     };
 }
 // parseArgs turns a value-less flag into `true`; refuse rather than silently
-// stringifying it (String(true) === 'true'), mirroring cmdHandoff's guard.
+// stringifying it (String(true) === 'true'), mirroring handleHandoff's guard.
 export function stringFlagOrExit(flags, key) {
     const v = flags[key];
     if (v === undefined)
         return undefined;
     if (v === true || v === false || Array.isArray(v)) {
         printError(`--${key} requires a value`);
-        process.exit(1);
+        throw new CliExit(1);
     }
     return v.trim();
 }

package/dist/cli/flags.d.ts

@@ -96,6 +96,7 @@ export declare const VERB_FLAGS: {
     auth: {
         switches: string[];
         values: string[];
+        numbers: string[];
     };
     goal: {
         switches: string[];

package/dist/cli/flags.js

@@ -48,7 +48,7 @@ export const VERB_FLAGS = {
     '__codex-session-end-worker': { values: ['codex-home', 'history-path', 'log-file', 'start-offset', 'started-at'] },
     dedup: { switches: ['dry-run'], numbers: ['threshold'] },
     dag: { switches: ['stats'] },
-    auth: { switches: ['all', 'global', 'json'], values: ['label', 'role', 'tenant'] },
+    auth: { switches: ['all', 'global', 'json', 'no-expiry'], values: ['label', 'role', 'tenant'], numbers: ['ttl-days'] },
     goal: {
         switches: ['all', 'no-propagate'],
         values: ['level', 'outcome', 'parent', 'policy', 'session-id', 'success', 'tenant-id'],

package/dist/cli/github.d.ts

@@ -0,0 +1,14 @@
+/** `hippo github` subcommands, split out of cli.ts so tests can import them without triggering main().
+ * The dispatcher in cli.ts re-exports handleGitHub. */
+import { type GitHubFetcher } from '../connectors/github/octokit-client.js';
+import type { CommandContext } from './flag-values.js';
+type FlagValue = string | boolean | string[];
+type Flags = Record<string, FlagValue>;
+export declare function printGitHubBackfillUsage(): void;
+/** `hippo github backfill`; the fetcher is injectable so tests avoid the network (default `realGitHubFetcher`). */
+export declare function cmdGitHubBackfill(hippoRoot: string, tenantId: string, flags: Flags, fetcher?: GitHubFetcher): Promise<void>;
+export declare function cmdGitHubDlqList(hippoRoot: string, tenantId: string, _flags: Flags): void;
+export declare function cmdGitHubDlqReplay(hippoRoot: string, tenantId: string, args: string[], flags: Flags): Promise<void>;
+export declare function handleGitHub({ hippoRoot, tenantId, args, flags }: CommandContext): Promise<void>;
+export {};
+//# sourceMappingURL=github.d.ts.map