hippo-memory 1.59.0 → 1.61.0

package/dist/cli/eval.js

@@ -0,0 +1,213 @@
+// The `hippo eval` verb; main() loads it lazily from the command table.
+import * as path from 'path';
+import * as fs from 'fs';
+import { loadAllEntries } from '../store/entry-reads.js';
+import { loadConfig } from '../config.js';
+import { getGlobalRoot } from '../shared.js';
+import { runEval, bootstrapCorpus, compareSummaries } from '../eval.js';
+import { runFeatureEval, formatResult, resultToBaseline, detectRegressions } from '../eval-suite.js';
+import { PACKAGE_VERSION } from '../version.js';
+import { printError } from './output.js';
+import { requireInit, fmt } from './shared.js';
+/** Runs `hippo eval`: --bootstrap writes a corpus, --suite runs the built-in feature eval, else it scores a corpus file. */
+export async function cmdEval(hippoRoot, corpusPath, flags) {
+    const asJson = Boolean(flags['json']);
+    const minMrr = flags['min-mrr'] !== undefined ? parseFloat(String(flags['min-mrr'])) : null;
+    const comparePath = flags['compare'] ? String(flags['compare']) : null;
+    // Suite mode doesn't need an initialized store
+    if (!flags['suite'])
+        requireInit(hippoRoot);
+    const entries = flags['suite'] ? [] : loadAllEntries(hippoRoot);
+    if (flags['bootstrap']) {
+        writeBootstrapCorpus(entries, flags);
+        return;
+    }
+    if (flags['suite']) {
+        await runEvalSuite(hippoRoot, flags, asJson, minMrr);
+        return;
+    }
+    const cases = readCorpus(corpusPath);
+    const globalRoot = getGlobalRoot();
+    const localBump = flags['equal-sources']
+        ? 1.0
+        : flags['local-bump'] !== undefined
+            ? parseFloat(String(flags['local-bump']))
+            : loadConfig(hippoRoot).search.localBump;
+    const summary = await runEval(cases, entries, {
+        hippoRoot,
+        globalRoot,
+        mmr: !flags['no-mmr'],
+        mmrLambda: flags['mmr-lambda'] !== undefined ? parseFloat(String(flags['mmr-lambda'])) : undefined,
+        embeddingWeight: flags['embedding-weight'] !== undefined ? parseFloat(String(flags['embedding-weight'])) : undefined,
+        localBump,
+    });
+    if (asJson) {
+        console.log(JSON.stringify(summary, null, 2));
+    }
+    else {
+        printEvalSummary(summary, Boolean(flags['show-cases']));
+    }
+    if (minMrr !== null && summary.meanMrr < minMrr) {
+        printError(`MRR ${fmt(summary.meanMrr, 4)} below threshold ${minMrr}`);
+        process.exit(1);
+    }
+    if (comparePath)
+        printEvalCompare(summary, comparePath, asJson);
+}
+/** Bootstrap mode: emit a synthetic corpus built from the store's own memories. */
+function writeBootstrapCorpus(entries, flags) {
+    const outPath = flags['out'] ? String(flags['out']) : null;
+    const max = flags['max-cases'] !== undefined ? parseInt(String(flags['max-cases']), 10) : 50;
+    const corpus = bootstrapCorpus(entries, max);
+    const payload = JSON.stringify({ cases: corpus }, null, 2);
+    if (outPath) {
+        fs.mkdirSync(path.dirname(outPath), { recursive: true });
+        fs.writeFileSync(outPath, payload, 'utf8');
+        console.log(`Wrote ${corpus.length} bootstrap cases to ${outPath}`);
+    }
+    else {
+        console.log(payload);
+    }
+}
+/** Suite mode: run the built-in feature eval (no corpus file needed, no init needed). */
+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 {
+            printError(`Warning: eval baseline ${baselinePath} is unreadable; running without it.`);
+        }
+    }
+    const result = await runFeatureEval(PACKAGE_VERSION);
+    if (asJson) {
+        console.log(JSON.stringify(result, null, 2));
+    }
+    else {
+        console.log(formatResult(result, baseline));
+    }
+    if (flags['save-baseline']) {
+        const newBaseline = resultToBaseline(result);
+        fs.mkdirSync(path.dirname(baselinePath), { recursive: true });
+        fs.writeFileSync(baselinePath, JSON.stringify(newBaseline, null, 2), 'utf8');
+        console.log(`\nBaseline saved to ${baselinePath}`);
+    }
+    if (baseline) {
+        const report = detectRegressions(baseline, result);
+        if (report.verdict === 'REGRESSION' && minMrr === null) {
+            process.exit(1);
+        }
+    }
+}
+/** Loads the corpus file, exiting with the usage line or the read error when there is none to score. */
+function readCorpus(corpusPath) {
+    if (!corpusPath) {
+        printError('Usage: hippo eval <corpus.json>  OR  hippo eval --suite [--save-baseline]  OR  hippo eval --bootstrap');
+        process.exit(1);
+    }
+    if (!fs.existsSync(corpusPath)) {
+        printError(`Corpus file not found: ${corpusPath}`);
+        process.exit(1);
+    }
+    let cases;
+    try {
+        const raw = JSON.parse(fs.readFileSync(corpusPath, 'utf8'));
+        cases = Array.isArray(raw) ? raw : raw.cases;
+        if (!Array.isArray(cases))
+            throw new Error('Corpus JSON must be an array or { cases: [...] }');
+    }
+    catch (err) {
+        printError(`Failed to read corpus: ${err instanceof Error ? err.message : err}`);
+        process.exit(1);
+    }
+    return cases;
+}
+function printEvalSummary(summary, showCases) {
+    console.log(`Eval: ${summary.cases.length} cases, ${summary.durationMs}ms`);
+    console.log();
+    console.log(`MRR:          ${fmt(summary.meanMrr, 4)}`);
+    console.log(`Recall@5:     ${fmt(summary.meanRecallAt5, 4)}`);
+    console.log(`Recall@10:    ${fmt(summary.meanRecallAt10, 4)}`);
+    console.log(`NDCG@10:      ${fmt(summary.meanNdcgAt10, 4)}`);
+    if (showCases) {
+        console.log();
+        console.log('Case details:');
+        for (const c of summary.cases) {
+            const exp = c.case.expectedIds.length;
+            const expectedSet = new Set(c.case.expectedIds);
+            const hitTop10 = c.returnedIds.slice(0, 10).filter((id) => expectedSet.has(id));
+            const missed = c.case.expectedIds.filter((id) => !c.returnedIds.slice(0, 10).includes(id));
+            console.log();
+            console.log(`[${c.case.id}] R@10=${fmt(c.recallAt10, 2)}  MRR=${fmt(c.mrr, 2)}  expected=${exp}  hit=${hitTop10.length}`);
+            console.log(`  query: ${c.case.query}`);
+            console.log(`  top 3: ${c.returnedIds.slice(0, 3).join(', ') || '(none)'}`);
+            if (missed.length > 0) {
+                const shown = missed.slice(0, 4);
+                const more = missed.length > shown.length ? ` +${missed.length - shown.length} more` : '';
+                console.log(`  missed: ${shown.join(', ')}${more}`);
+            }
+        }
+    }
+    console.log();
+    const failing = summary.cases.filter((c) => c.mrr === 0);
+    if (failing.length > 0) {
+        console.log(`${failing.length} case(s) returned zero relevant results:`);
+        for (const f of failing.slice(0, 10)) {
+            console.log(`  [${f.case.id}] "${f.case.query.slice(0, 60)}"`);
+        }
+        if (failing.length > 10)
+            console.log(`  ...and ${failing.length - 10} more`);
+    }
+}
+function printEvalCompare(summary, comparePath, asJson) {
+    if (!fs.existsSync(comparePath)) {
+        printError(`Baseline file not found: ${comparePath}`);
+        process.exit(1);
+    }
+    let baseline;
+    try {
+        baseline = JSON.parse(fs.readFileSync(comparePath, 'utf8'));
+    }
+    catch (err) {
+        printError(`Failed to parse baseline: ${err instanceof Error ? err.message : err}`);
+        process.exit(1);
+    }
+    const cmp = compareSummaries(baseline, summary);
+    if (asJson) {
+        // The main JSON output already emitted; append comparison to stderr so
+        // both can be captured independently.
+        printError(JSON.stringify({ compare: cmp }, null, 2));
+        return;
+    }
+    console.log();
+    console.log('Compare vs baseline:');
+    const sign = (d) => (d >= 0 ? '+' : '') + fmt(d, 4);
+    console.log(`  MRR:        ${sign(cmp.aggregate.mrr)}`);
+    console.log(`  Recall@5:   ${sign(cmp.aggregate.recallAt5)}`);
+    console.log(`  Recall@10:  ${sign(cmp.aggregate.recallAt10)}`);
+    console.log(`  NDCG@10:    ${sign(cmp.aggregate.ndcgAt10)}`);
+    console.log();
+    console.log(`  improved: ${cmp.improved.length}   regressed: ${cmp.regressed.length}   unchanged: ${cmp.unchanged}`);
+    if (cmp.onlyInBaseline.length > 0)
+        console.log(`  only in baseline: ${cmp.onlyInBaseline.length}`);
+    if (cmp.onlyInCurrent.length > 0)
+        console.log(`  only in current:  ${cmp.onlyInCurrent.length}`);
+    const showPerCase = cmp.improved.length + cmp.regressed.length > 0;
+    if (showPerCase) {
+        for (const d of cmp.improved.slice(0, 5)) {
+            const delta = d.ndcgAfter - d.ndcgBefore;
+            console.log(`  + [${d.id}] NDCG ${fmt(d.ndcgBefore, 2)} -> ${fmt(d.ndcgAfter, 2)} (+${fmt(delta, 3)})`);
+        }
+        for (const d of cmp.regressed.slice(0, 5)) {
+            const delta = d.ndcgAfter - d.ndcgBefore;
+            console.log(`  - [${d.id}] NDCG ${fmt(d.ndcgBefore, 2)} -> ${fmt(d.ndcgAfter, 2)} (${fmt(delta, 3)})`);
+        }
+    }
+}
+export async function handleEval({ hippoRoot, args, flags }) {
+    const corpusPath = args[0] ? String(args[0]) : null;
+    await cmdEval(hippoRoot, corpusPath, flags);
+}
+//# sourceMappingURL=eval.js.map

package/dist/cli/explain.d.ts

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

package/dist/cli/explain.js

@@ -0,0 +1,150 @@
+// The `hippo explain` verb; main() loads it lazily from the command table.
+import { confidenceFacets } from '../memory.js';
+import { isInitialized } from '../store/open.js';
+import { loadSearchEntries } from '../store/search-rows.js';
+import { loadIndex } from '../store/index-and-stats.js';
+import { loadConfig } from '../config.js';
+import { dropHeldCopies } from '../same-text.js';
+import { detectScope } from '../scope.js';
+import { getGlobalRoot } from '../shared.js';
+import * as api from '../api.js';
+import { resolveTenantId } from '../tenant.js';
+import { rankRecall } from '../recall-pipeline.js';
+import { printedTokens } from '../context-render.js';
+import { printError } from './output.js';
+import { parseLimitFlag, parseBudgetFlag, requireInit, fmt, recallEntryText, recallHeading, parseAsOfFlag, engineFlags, } from './shared.js';
+/** 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) {
+    const probe = [
+        ...loadSearchEntries(hippoRoot, query, undefined, tenantId),
+        ...(globalRoot ? loadSearchEntries(globalRoot, query, undefined, tenantId) : []),
+    ];
+    // Window-capped, so the count is a floor on large stores; fine for a "why is my row missing" hint.
+    const hidden = probe.filter((e) => !api.passesCliRecallScopeFilter(e.scope ?? null, requested)).length;
+    if (hidden > 0) {
+        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) {
+    requireInit(hippoRoot);
+    const budget = parseBudgetFlag(flags['budget'], 4000);
+    const limit = parseLimitFlag(flags['limit']);
+    const asJson = Boolean(flags['json']);
+    const includeSuperseded = Boolean(flags['include-superseded']);
+    const asOf = parseAsOfFlag(flags);
+    const globalRoot = getGlobalRoot();
+    const tenantId = resolveTenantId({});
+    // Explain shows what recall would see, so it applies the same scope rule.
+    const explicitScope = flags['scope'] !== undefined ? String(flags['scope']).trim() : null;
+    // Unlike recall, explain reads the global store whenever it exists, even when it is the local root.
+    const explainGlobalOn = isInitialized(globalRoot);
+    noteScopeHidden(hippoRoot, explainGlobalOn ? globalRoot : undefined, query, tenantId, explicitScope || undefined);
+    const config = loadConfig(hippoRoot);
+    const engine = engineFlags(flags, config);
+    // Priced as recall prints each result, so explain returns what recall's engines would.
+    const explainIndex = loadIndex(hippoRoot);
+    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 rank = await rankRecall({ hippoRoot, globalRoot: explainGlobalOn ? globalRoot : undefined, tenantId }, {
+        query, budget: entryBudget, cost, limit, includeSuperseded, asOf,
+        explicitScope, activeScope: explicitScope || detectScope(),
+        search: { ...engine, multihop: false, explain: true },
+    });
+    const hasGlobal = rank.globalEntries.length > 0;
+    const modeUsed = engine.usePhysics && !hasGlobal
+        ? 'physics'
+        : hasGlobal ? 'searchBothHybrid' : 'hybrid';
+    const results = dropHeldCopies(rank.results, (r) => r.entry);
+    const candidates = rank.localEntries.length + rank.globalEntries.length;
+    if (asJson) {
+        const output = results.map((r, rank) => ({
+            rank: rank + 1,
+            id: r.entry.id,
+            layer: r.entry.layer,
+            confidence: confidenceFacets(r.entry).tier,
+            aged_out: confidenceFacets(r.entry).agedOut,
+            score: r.score,
+            tokens: r.tokens,
+            tags: r.entry.tags,
+            content: r.entry.content,
+            breakdown: r.breakdown,
+        }));
+        console.log(JSON.stringify({
+            query,
+            mode: modeUsed,
+            candidates,
+            returned: output.length,
+            results: output,
+        }));
+        return;
+    }
+    if (results.length === 0) {
+        console.log(`No memories matched "${query}" (scanned ${candidates}).`);
+        return;
+    }
+    console.log(`Query: "${query}"`);
+    console.log(`Mode:  ${modeUsed}   candidates: ${candidates}   returned: ${results.length}`);
+    console.log();
+    console.log('Rank  Score   Strength  Age    Layer      ID                Preview');
+    console.log('----- ------- --------- ------ ---------- ----------------- ---------------------------------');
+    for (let i = 0; i < results.length; i++) {
+        const r = results[i];
+        const b = r.breakdown;
+        const preview = r.entry.content.replace(/\s+/g, ' ').slice(0, 48);
+        const ageStr = b ? `${b.ageDays}d` : '?';
+        console.log(`${String(i + 1).padEnd(5)} ${fmt(r.score, 3).padEnd(7)} ${fmt(r.entry.strength).padEnd(9)} ${ageStr.padEnd(6)} ${r.entry.layer.padEnd(10)} ${r.entry.id.padEnd(17)} ${preview}`);
+    }
+    console.log();
+    for (let i = 0; i < results.length; i++) {
+        const r = results[i];
+        const b = r.breakdown;
+        console.log(`[${i + 1}] ${r.entry.id}   composite=${fmt(r.score, 4)}`);
+        if (!b) {
+            console.log('    (no breakdown available)');
+            console.log();
+            continue;
+        }
+        if (b.mode === 'physics') {
+            console.log(`    mode:      physics-gravity`);
+            console.log(`    cosine:    ${fmt(b.cosine, 3)}  (pre-amp baseline)`);
+            console.log(`    final:     ${fmt(b.final, 4)}  (post-amp, from physics scorer)`);
+        }
+        else {
+            const matched = b.matchedTerms.length > 0 ? b.matchedTerms.join(', ') : '(none)';
+            console.log(`    mode:      ${b.mode}${b.mode === 'hybrid-no-vec' ? '  (no cached doc vector — run `hippo embed`)' : ''}`);
+            console.log(`    BM25:      raw=${fmt(r.bm25, 3)}  normalized=${fmt(b.normBm25, 3)}  weight=${fmt(b.bm25Weight, 2)}  matched=[${matched}]`);
+            console.log(`    embedding: cosine=${fmt(b.cosine, 3)}  weight=${fmt(b.embeddingWeight, 2)}`);
+            console.log(`    base:      ${fmt(b.bm25Weight, 2)}*${fmt(b.normBm25, 3)} + ${fmt(b.embeddingWeight, 2)}*${fmt(b.cosine, 3)} = ${fmt(b.base, 4)}`);
+            console.log(`    strength:  x${fmt(b.strengthMultiplier, 3)}  (strength=${fmt(r.entry.strength, 3)})`);
+            console.log(`    recency:   x${fmt(b.recencyMultiplier, 3)}  (age=${b.ageDays}d)`);
+            if (b.decisionBoost !== 1)
+                console.log(`    decision:  x${fmt(b.decisionBoost, 2)}  (tagged 'decision')`);
+            if (b.scopeBoost !== 1)
+                console.log(`    scope:     x${fmt(b.scopeBoost, 2)}  (scope tag ${b.scopeBoost > 1 ? 'match' : 'mismatch'})`);
+            if (b.pathBoost !== 1)
+                console.log(`    path:      x${fmt(b.pathBoost, 3)}  (cwd path tag overlap)`);
+            if (b.sourceBump !== 1)
+                console.log(`    source:    x${fmt(b.sourceBump, 2)}  (local priority bump over global)`);
+            if (b.outcomeBoost !== 1)
+                console.log(`    outcome:   x${fmt(b.outcomeBoost, 3)}  (user feedback: pos-neg = ${(r.entry.outcome_positive ?? 0) - (r.entry.outcome_negative ?? 0)})`);
+            if (b.churnStaleMultiplier !== 1)
+                console.log(`    churn:     x${fmt(b.churnStaleMultiplier, 2)}  (tagged 'churn-stale')`);
+            if (b.preMmrRank !== undefined && b.postMmrRank !== undefined && b.preMmrRank !== b.postMmrRank) {
+                const arrow = b.postMmrRank < b.preMmrRank ? 'up' : 'down';
+                console.log(`    mmr:       rank ${b.preMmrRank} -> ${b.postMmrRank}  (diversity ${arrow})`);
+            }
+            console.log(`    final:     ${fmt(b.final, 4)}`);
+        }
+        console.log();
+    }
+    console.log('Note: explain does not mark memories as retrieved (read-only).');
+}
+export async function handleExplain({ hippoRoot, args, flags }) {
+    const query = args.join(' ').trim();
+    if (!query) {
+        printError('Please provide a search query.');
+        process.exit(1);
+    }
+    await cmdExplain(hippoRoot, query, flags);
+}
+//# sourceMappingURL=explain.js.map

package/dist/cli/goals.d.ts

@@ -0,0 +1,2 @@
+export declare function cmdGoal(hippoRoot: string, args: string[], flags: Record<string, string | boolean | string[]>): void;
+//# sourceMappingURL=goals.d.ts.map

package/dist/cli/goals.js

@@ -0,0 +1,196 @@
+// `hippo goal`: the per-session goal stack that recall boosts.
+import { envHippoSessionId } from '../env.js';
+import * as api from '../api.js';
+import { resolveTenantId } from '../tenant.js';
+import { printError } from './output.js';
+// ---------------------------------------------------------------------------
+// `hippo goal <push|list|complete|suspend|resume>` — B3 dlPFC depth (Task 10)
+// ---------------------------------------------------------------------------
+const GOAL_POLICY_TYPES = [
+    'schema-fit-biased',
+    'error-prioritized',
+    'recency-first',
+    'hybrid',
+];
+function sanitizeGoalName(s) {
+    // Strip C0 control chars + DEL to prevent terminal escape injection.
+    return s.replace(/[\x00-\x1f\x7f]/g, '?');
+}
+function resolveGoalSession(flags) {
+    const sessionId = (flags['session-id'] !== undefined
+        ? String(flags['session-id'])
+        : envHippoSessionId() ?? '').trim();
+    if (!sessionId) {
+        printError('session id required (set HIPPO_SESSION_ID or pass --session-id)');
+        process.exit(1);
+    }
+    const tenantId = (flags['tenant-id'] !== undefined
+        ? String(flags['tenant-id'])
+        : resolveTenantId({})).trim() || 'default';
+    return { sessionId, tenantId };
+}
+function cmdGoalPush(hippoRoot, args, flags) {
+    const rawName = args.join(' ').trim();
+    if (!rawName) {
+        printError('Usage: hippo goal push <name> [--policy <type>] [--success "<condition>"] [--level N] [--parent <goalId>]');
+        process.exit(1);
+    }
+    // Sanitize at WRITE time so corrupt names never enter the DB.
+    const name = sanitizeGoalName(rawName);
+    if (name !== rawName) {
+        printError('note: stripped control characters from goal name');
+    }
+    const { sessionId, tenantId } = resolveGoalSession(flags);
+    let policy;
+    const policyRaw = flags['policy'];
+    if (policyRaw === true) {
+        printError('--policy requires a value (e.g., --policy error-prioritized)');
+        process.exit(1);
+    }
+    if (typeof policyRaw === 'string') {
+        if (!GOAL_POLICY_TYPES.includes(policyRaw)) {
+            printError(`Unknown --policy '${policyRaw}'. Expected one of: ${GOAL_POLICY_TYPES.join(' | ')}.`);
+            process.exit(1);
+        }
+        policy = { policyType: policyRaw };
+    }
+    const successRaw = flags['success'];
+    if (successRaw === true) {
+        printError('--success requires a value (e.g., --success "<condition>")');
+        process.exit(1);
+    }
+    const successCondition = typeof successRaw === 'string' ? successRaw : undefined;
+    const levelRaw = flags['level'];
+    let level;
+    if (levelRaw === true) {
+        printError('--level requires a value (e.g., --level 1)');
+        process.exit(1);
+    }
+    if (levelRaw !== undefined) {
+        const parsed = Number(levelRaw);
+        if (!Number.isFinite(parsed) || parsed < 0 || parsed > 2 || !Number.isInteger(parsed)) {
+            printError('--level must be an integer in [0, 2]');
+            process.exit(1);
+        }
+        level = parsed;
+    }
+    const parentRaw = flags['parent'];
+    if (parentRaw === true) {
+        printError('--parent requires a value (e.g., --parent <goalId>)');
+        process.exit(1);
+    }
+    const parentGoalId = typeof parentRaw === 'string' ? parentRaw : undefined;
+    const goal = api.goalPush(goalContext(hippoRoot, tenantId), {
+        sessionId,
+        goalName: name,
+        level,
+        parentGoalId,
+        successCondition,
+        policy,
+    });
+    console.log(goal.id);
+}
+function goalContext(hippoRoot, tenantId = resolveTenantId({})) {
+    return { hippoRoot, tenantId, actor: api.adminActor('cli') };
+}
+function cmdGoalList(hippoRoot, flags) {
+    const { sessionId, tenantId } = resolveGoalSession(flags);
+    const showAll = Boolean(flags['all']);
+    const goals = api.goalList(goalContext(hippoRoot, tenantId), { sessionId, all: showAll });
+    if (goals.length === 0) {
+        console.log('(no goals)');
+        return;
+    }
+    // 4-column table: id, status, goal_name, outcome. Plan calls it a "2-column"
+    // table but the assertion list (id, status, goal_name, outcome) needs four;
+    // tests check for substrings ('active', '0.9', name) so column count is
+    // observably four but not asserted.
+    const rows = goals.map(g => ({
+        id: g.id,
+        status: g.status,
+        name: sanitizeGoalName(g.goalName),
+        outcome: g.outcomeScore !== undefined ? g.outcomeScore.toString() : '-',
+    }));
+    const widths = {
+        id: Math.max(2, ...rows.map(r => r.id.length)),
+        status: Math.max(6, ...rows.map(r => r.status.length)),
+        name: Math.max(4, ...rows.map(r => r.name.length)),
+        outcome: Math.max(7, ...rows.map(r => r.outcome.length)),
+    };
+    const pad = (s, w) => s + ' '.repeat(Math.max(0, w - s.length));
+    console.log(`${pad('id', widths.id)}  ${pad('status', widths.status)}  ${pad('name', widths.name)}  ${pad('outcome', widths.outcome)}`);
+    for (const r of rows) {
+        console.log(`${pad(r.id, widths.id)}  ${pad(r.status, widths.status)}  ${pad(r.name, widths.name)}  ${pad(r.outcome, widths.outcome)}`);
+    }
+}
+function cmdGoalComplete(hippoRoot, args, flags) {
+    const id = args[0];
+    if (!id) {
+        printError('Usage: hippo goal complete <id> [--outcome <0..1>] [--no-propagate]');
+        process.exit(1);
+    }
+    let outcomeScore;
+    const outcomeRaw = flags['outcome'];
+    if (outcomeRaw === true) {
+        printError('--outcome requires a value (e.g., --outcome 0.9)');
+        process.exit(1);
+    }
+    if (outcomeRaw !== undefined) {
+        const parsed = Number(outcomeRaw);
+        if (!Number.isFinite(parsed) || parsed < 0 || parsed > 1) {
+            printError('--outcome must be a number in [0, 1]');
+            process.exit(1);
+        }
+        outcomeScore = parsed;
+    }
+    const noPropagate = flags['no-propagate'] === true;
+    api.goalComplete(goalContext(hippoRoot), id, { outcomeScore, noPropagate });
+    console.log('ok');
+}
+function cmdGoalSuspend(hippoRoot, args) {
+    const id = args[0];
+    if (!id) {
+        printError('Usage: hippo goal suspend <id>');
+        process.exit(1);
+    }
+    api.goalSuspend(goalContext(hippoRoot), id);
+    console.log('ok');
+}
+function cmdGoalResume(hippoRoot, args) {
+    const id = args[0];
+    if (!id) {
+        printError('Usage: hippo goal resume <id>');
+        process.exit(1);
+    }
+    api.goalResume(goalContext(hippoRoot), id);
+    console.log('ok');
+}
+export function cmdGoal(hippoRoot, args, flags) {
+    const sub = args[0];
+    if (!sub) {
+        printError('Usage: hippo goal <push|list|complete|suspend|resume> [args]');
+        process.exit(1);
+    }
+    const subArgs = args.slice(1);
+    switch (sub) {
+        case 'push':
+            cmdGoalPush(hippoRoot, subArgs, flags);
+            return;
+        case 'list':
+            cmdGoalList(hippoRoot, flags);
+            return;
+        case 'complete':
+            cmdGoalComplete(hippoRoot, subArgs, flags);
+            return;
+        case 'suspend':
+            cmdGoalSuspend(hippoRoot, subArgs);
+            return;
+        case 'resume':
+            cmdGoalResume(hippoRoot, subArgs);
+            return;
+        default:
+            printError(`Unknown goal subcommand: ${sub}. Expected: push | list | complete | suspend | resume.`);
+            process.exit(1);
+    }
+}
+//# sourceMappingURL=goals.js.map

package/dist/cli/hook-blocks.d.ts

@@ -0,0 +1,18 @@
+export declare const HOOK_MARKERS: {
+    start: string;
+    end: string;
+};
+export declare const HOOKS: Record<string, {
+    file: string;
+    content: string;
+    description: string;
+}>;
+/** The first hippo block in `text` and the agent whose current or shipped text it is; `owner` is undefined for an edited block. */
+export declare function hippoBlock(text: string): {
+    start: number;
+    end: number;
+    eol: string;
+    inner: string;
+    owner?: string;
+} | null;
+//# sourceMappingURL=hook-blocks.d.ts.map