hippo-memory 1.70.0 → 1.71.0

package/dist/{connectors/github/cli-impl.js → cli/github.js}

@@ -1,43 +1,28 @@
-/**
- * Implementation of `hippo github` CLI subcommands. Extracted from the main
- * cli.ts so unit tests can import these functions directly without triggering
- * the cli.ts main() side effects. The cli.ts dispatcher re-exports the
- * top-level cmdGithub.
- *
- * Subcommands mirror the Slack connector shape (cli.ts §Slack subcommands):
- *   - hippo github backfill --repo <owner/name> [--since ISO] [--max <N>]
- *   - hippo github dlq list
- *   - hippo github dlq replay <id> [--force]
- */
-import { envGithubToken, envGithubWebhookSecret, envGithubWebhookSecretPrevious } from '../../util/env.js';
-import { adminActor } from '../../api/index.js';
-import { seedCursors } from '../../store/connectors/github.js';
-import { resolveTenantId } from '../../store/tenant.js';
-import { backfillRepo } from './backfill.js';
-import { realGitHubFetcher } from './octokit-client.js';
-import { listDlq } from '../dlq.js';
-import { githubDlq, replayDlqEntry } from './dlq.js';
-import { ingestEvent } from './ingest.js';
-import { handleCommentDeleted } from './deletion.js';
-import { computeDeletionKey } from './signature.js';
-import { isGitHubIssueEvent, isGitHubIssueCommentEvent, isGitHubPullRequestEvent, isGitHubPullRequestReviewCommentEvent, } from './types.js';
+/** `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 { envGitHubToken, envGitHubWebhookSecret, envGitHubWebhookSecretPrevious } from '../util/env.js';
+import { adminActor } from '../api/index.js';
+import { backfillRepo } from '../connectors/github/backfill.js';
+import { realGitHubFetcher } from '../connectors/github/octokit-client.js';
+import { listDlq } from '../connectors/dlq.js';
+import { githubDlq, replayDlqEntry } from '../connectors/github/dlq.js';
+import { ingestEvent } from '../connectors/github/ingest.js';
+import { handleCommentDeleted } from '../connectors/github/deletion.js';
+import { computeDeletionKey } from '../connectors/github/signature.js';
+import { isGitHubIssueEvent, isGitHubIssueCommentEvent, isGitHubPullRequestEvent, isGitHubPullRequestReviewCommentEvent, } from '../connectors/github/types.js';
+import { CliExit } from './exit.js';
+import { errorMessage } from '../util/log.js';
 function isFlagString(value) {
     return typeof value === 'string';
 }
-// FlagValue never includes `number` (see its declaration above), so a
-// `value is number` predicate directly on FlagValue would not type-check —
-// the generic wrapper narrows a value of any type T instead.
+// FlagValue never includes `number`, so a `value is number` predicate on it would not type-check; the generic wrapper narrows any type T instead.
 function isNumberLike(value) {
     return typeof value === 'number';
 }
 function isFlagValueNumberLike(value) {
     return isNumberLike(value);
 }
-/**
- * Map a parsed envelope + eventName header to an IngestEvent discriminated
- * union. Returns null for unknown event types or shapes that don't pass the
- * type guards.
- */
+/** Map a parsed envelope + eventName header to an IngestEvent; null for unknown event types or shapes failing the type guards. */
 function parsedToIngestEvent(parsed, eventName) {
     if (eventName === 'issues' && isGitHubIssueEvent(parsed, eventName)) {
         return { eventName: 'issues', payload: parsed };
@@ -55,7 +40,7 @@ function parsedToIngestEvent(parsed, eventName) {
     return null;
 }
 // Console lines below are the `hippo github` command's printed result and usage text, so they stay off the logger.
-export function printGithubBackfillUsage() {
+export function printGitHubBackfillUsage() {
     console.log('hippo github backfill --repo <owner/name> [--since ISO] [--max <N>]');
     console.log('  --repo   GitHub repository in owner/name format (required, e.g. acme/widgets)');
     console.log('  --since  Initial high-water-mark for first run (optional, ISO 8601)');
@@ -72,31 +57,21 @@ function maxPerStreamFlag(maxRaw) {
     }
     return undefined;
 }
-/**
- * `hippo github backfill`. The fetcher is injectable so tests can drive the
- * code path without hitting the network. Defaults to `realGitHubFetcher`.
- */
-export async function cmdGithubBackfill(hippoRoot, flags, fetcher = realGitHubFetcher) {
+/** `hippo github backfill`; the fetcher is injectable so tests avoid the network (default `realGitHubFetcher`). */
+export async function cmdGitHubBackfill(hippoRoot, tenantId, flags, fetcher = realGitHubFetcher) {
     const repo = flags['repo'];
     if (!isFlagString(repo) || !repo.includes('/')) {
-        printGithubBackfillUsage();
-        process.exit(2);
+        printGitHubBackfillUsage();
+        throw new CliExit(2);
     }
-    const token = envGithubToken();
+    const token = envGitHubToken();
     if (!token) {
         console.error('GITHUB_TOKEN is not set. Backfill requires a personal access token with repo read scope.');
-        process.exit(2);
+        throw new CliExit(2);
     }
     const maxPerStream = maxPerStreamFlag(flags['max']);
     const sinceFlag = flags['since'];
     const sinceIso = isFlagString(sinceFlag) ? sinceFlag : undefined;
-    const tenantId = resolveTenantId({});
-    // Seed the github_cursors row so all 3 streams use --since on a fresh run.
-    // COALESCE preserves any existing HWM (subsequent runs ignore --since for
-    // streams that already drained at least once — same idempotency story as
-    // Slack's slack_cursors).
-    if (sinceIso)
-        seedCursors(hippoRoot, tenantId, repo, sinceIso);
     const ctx = {
         hippoRoot,
         tenantId,
@@ -108,19 +83,17 @@ export async function cmdGithubBackfill(hippoRoot, flags, fetcher = realGitHubFe
             fetcher,
             token,
             maxPerStream,
+            sinceIso,
         });
         console.log(JSON.stringify(result, null, 2));
     }
     catch (e) {
-        // SAFETY: this is a best-effort error message only; property access on
-        // any JS value is safe (undefined if absent), preserving the existing
-        // lenient formatting even when something non-Error was thrown.
-        console.error('backfill failed:', e.message);
-        process.exit(3);
+        console.error('backfill failed:', errorMessage(e));
+        throw new CliExit(3);
     }
 }
-export function cmdGithubDlqList(hippoRoot, _flags) {
-    const items = listDlq(githubDlq, hippoRoot, { tenantId: resolveTenantId({}) });
+export function cmdGitHubDlqList(hippoRoot, tenantId, _flags) {
+    const items = listDlq(githubDlq, hippoRoot, { tenantId });
     if (items.length === 0) {
         console.log('no entries');
         return;
@@ -150,9 +123,8 @@ const reingestParkedDelivery = async (innerCtx, args) => {
             deliveryId: args.deliveryId,
             eventName: event.eventName,
         });
-        // archivedCount maps to memoryId only loosely — return null since the
-        // archive operation can affect multiple rows. The replay-result audit
-        // trail is in github_dlq.retry_count + retried_at.
+        // archivedCount maps to memoryId only loosely (the archive can affect multiple rows), so return null;
+        // the replay audit trail is github_dlq.retry_count + retried_at.
         return { memoryId: r.archivedCount > 0 ? 'archived' : null };
     }
     const r = await ingestEvent(innerCtx, {
@@ -162,51 +134,51 @@ const reingestParkedDelivery = async (innerCtx, args) => {
     });
     return { memoryId: r.memoryId };
 };
-export async function cmdGithubDlqReplay(hippoRoot, args, flags) {
+export async function cmdGitHubDlqReplay(hippoRoot, tenantId, args, flags) {
     const idArg = args[0];
     if (!idArg) {
         console.error('Usage: hippo github dlq replay <id> [--force]');
-        process.exit(1);
+        throw new CliExit(1);
     }
     const id = Number(idArg);
     if (!Number.isFinite(id) || !Number.isInteger(id) || id < 1) {
         console.error(`replay: invalid id ${idArg}`);
-        process.exit(1);
+        throw new CliExit(1);
     }
     const force = flags['force'] === true;
     const ctx = {
         hippoRoot,
-        tenantId: resolveTenantId({}),
+        tenantId,
         actor: adminActor('cli:github-dlq-replay'),
     };
     // Without an ingestHook replay only bumps retry_count while printing "replay ok"; the real hook re-runs ingest.
     const result = await replayDlqEntry(ctx, id, {
         force,
-        webhookSecret: envGithubWebhookSecret(),
-        previousSecret: envGithubWebhookSecretPrevious(),
+        webhookSecret: envGitHubWebhookSecret(),
+        previousSecret: envGitHubWebhookSecretPrevious(),
         ingestHook: reingestParkedDelivery,
     });
     if (!result.ok) {
         console.error(`replay failed: status=${result.status} retry_count=${result.retryCount}${result.reason ? ` reason=${result.reason}` : ''}`);
-        process.exit(1);
+        throw new CliExit(1);
     }
     console.log(`replay ok: status=${result.status} memory_id=${result.memoryId ?? '(none)'} retry_count=${result.retryCount}`);
 }
-export async function cmdGithub(hippoRoot, args, flags) {
+export async function handleGitHub({ hippoRoot, tenantId, args, flags }) {
     const sub = args[0];
     if (sub === 'backfill') {
-        await cmdGithubBackfill(hippoRoot, flags);
+        await cmdGitHubBackfill(hippoRoot, tenantId, flags);
         return;
     }
     if (sub === 'dlq' && args[1] === 'list') {
-        cmdGithubDlqList(hippoRoot, flags);
+        cmdGitHubDlqList(hippoRoot, tenantId, flags);
         return;
     }
     if (sub === 'dlq' && args[1] === 'replay') {
-        await cmdGithubDlqReplay(hippoRoot, args.slice(2), flags);
+        await cmdGitHubDlqReplay(hippoRoot, tenantId, args.slice(2), flags);
         return;
     }
     console.error('Usage: hippo github <backfill|dlq list|dlq replay <id> [--force]> [...]');
-    process.exit(1);
+    throw new CliExit(1);
 }
-//# sourceMappingURL=cli-impl.js.map
+//# sourceMappingURL=github.js.map

package/dist/cli/goals.d.ts

@@ -1,3 +1,3 @@
-import { type CliFlags } from './flag-values.js';
-export declare function cmdGoal(hippoRoot: string, args: string[], flags: CliFlags): void;
+import { type CommandContext } from './flag-values.js';
+export declare function handleGoal({ hippoRoot, tenantId, args, flags }: CommandContext): void;
 //# sourceMappingURL=goals.d.ts.map

package/dist/cli/goals.js

@@ -1,46 +1,48 @@
 // `hippo goal`: the per-session goal stack that recall boosts.
-import { envHippoSessionId } from '../util/env.js';
+import { DEFAULT_TENANT_ID, envHippoSessionId } from '../util/env.js';
 import * as api from '../api/index.js';
-import { resolveTenantId } from '../store/tenant.js';
+import { cliApiContext } from './api-context.js';
 import { printError } from './output.js';
-import { boolFlag, flagIsTrue, stringFlag } from './flag-values.js';
-// ---------------------------------------------------------------------------
+import { boolFlag, flagIsTrue, isStringFlag, stringFlag } from './flag-values.js';
+import { CliExit } from './exit.js';
 // `hippo goal <push|list|complete|suspend|resume>`
-// ---------------------------------------------------------------------------
 const GOAL_POLICY_TYPES = [
     'schema-fit-biased',
     'error-prioritized',
     'recency-first',
     'hybrid',
 ];
+function isGoalPolicyType(value) {
+    return GOAL_POLICY_TYPES.some((type) => type === value);
+}
 function sanitizeGoalName(s) {
     // Strip C0 control chars + DEL to prevent terminal escape injection.
-    return s.replace(/[\x00-\x1f\x7f]/g, '?');
+    return s.replace(/[^\x20-\x7e\u0080-\uffff]/g, '?');
 }
-function resolveGoalSession(flags) {
+function resolveGoalSession(flags, defaultTenantId) {
     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);
+        throw new CliExit(1);
     }
     const tenantId = (flags['tenant-id'] !== undefined
         ? String(flags['tenant-id'])
-        : resolveTenantId({})).trim() || 'default';
+        : defaultTenantId).trim() || DEFAULT_TENANT_ID;
     return { sessionId, tenantId };
 }
 function readGoalPolicy(flags) {
     const policyRaw = flags['policy'];
     if (policyRaw === true) {
         printError('--policy requires a value (e.g., --policy error-prioritized)');
-        process.exit(1);
+        throw new CliExit(1);
     }
-    if (typeof policyRaw !== 'string')
+    if (!isStringFlag(policyRaw))
         return undefined;
-    if (!GOAL_POLICY_TYPES.includes(policyRaw)) {
+    if (!isGoalPolicyType(policyRaw)) {
         printError(`Unknown --policy '${policyRaw}'. Expected one of: ${GOAL_POLICY_TYPES.join(' | ')}.`);
-        process.exit(1);
+        throw new CliExit(1);
     }
     return { policyType: policyRaw };
 }
@@ -48,44 +50,44 @@ function readGoalLevel(flags) {
     const levelRaw = flags['level'];
     if (levelRaw === true) {
         printError('--level requires a value (e.g., --level 1)');
-        process.exit(1);
+        throw new CliExit(1);
     }
     if (levelRaw === undefined)
         return 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);
+        throw new CliExit(1);
     }
     return parsed;
 }
-function cmdGoalPush(hippoRoot, args, flags) {
+function cmdGoalPush(hippoRoot, defaultTenantId, 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);
+        throw new CliExit(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);
+    const { sessionId, tenantId } = resolveGoalSession(flags, defaultTenantId);
     const policy = readGoalPolicy(flags);
     const successRaw = flags['success'];
     if (successRaw === true) {
         printError('--success requires a value (e.g., --success "<condition>")');
-        process.exit(1);
+        throw new CliExit(1);
     }
     const successCondition = stringFlag(flags, 'success');
     const level = readGoalLevel(flags);
     const parentRaw = flags['parent'];
     if (parentRaw === true) {
         printError('--parent requires a value (e.g., --parent <goalId>)');
-        process.exit(1);
+        throw new CliExit(1);
     }
     const parentGoalId = stringFlag(flags, 'parent');
-    const goal = api.goalPush(goalContext(hippoRoot, tenantId), {
+    const goal = api.goalPush(cliApiContext(hippoRoot, tenantId), {
         sessionId,
         goalName: name,
         level,
@@ -95,21 +97,15 @@ function cmdGoalPush(hippoRoot, args, flags) {
     });
     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);
+function cmdGoalList(hippoRoot, defaultTenantId, flags) {
+    const { sessionId, tenantId } = resolveGoalSession(flags, defaultTenantId);
     const showAll = boolFlag(flags, 'all');
-    const goals = api.goalList(goalContext(hippoRoot, tenantId), { sessionId, all: showAll });
+    const goals = api.goalList(cliApiContext(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.
+    // Four columns (id, status, goal_name, outcome); tests only check substrings, so the count is not asserted.
     const rows = goals.map(g => ({
         id: g.id,
         status: g.status,
@@ -128,74 +124,74 @@ function cmdGoalList(hippoRoot, flags) {
         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) {
+function cmdGoalComplete(hippoRoot, tenantId, args, flags) {
     const id = args[0];
     if (!id) {
         printError('Usage: hippo goal complete <id> [--outcome <0..1>] [--no-propagate]');
-        process.exit(1);
+        throw new CliExit(1);
     }
     let outcomeScore;
     const outcomeRaw = flags['outcome'];
     if (outcomeRaw === true) {
         printError('--outcome requires a value (e.g., --outcome 0.9)');
-        process.exit(1);
+        throw new CliExit(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);
+            throw new CliExit(1);
         }
         outcomeScore = parsed;
     }
     const noPropagate = flagIsTrue(flags, 'no-propagate');
-    api.goalComplete(goalContext(hippoRoot), id, { outcomeScore, noPropagate });
+    api.goalComplete(cliApiContext(hippoRoot, tenantId), id, { outcomeScore, noPropagate });
     console.log('ok');
 }
-function cmdGoalSuspend(hippoRoot, args) {
+function cmdGoalSuspend(hippoRoot, tenantId, args) {
     const id = args[0];
     if (!id) {
         printError('Usage: hippo goal suspend <id>');
-        process.exit(1);
+        throw new CliExit(1);
     }
-    api.goalSuspend(goalContext(hippoRoot), id);
+    api.goalSuspend(cliApiContext(hippoRoot, tenantId), id);
     console.log('ok');
 }
-function cmdGoalResume(hippoRoot, args) {
+function cmdGoalResume(hippoRoot, tenantId, args) {
     const id = args[0];
     if (!id) {
         printError('Usage: hippo goal resume <id>');
-        process.exit(1);
+        throw new CliExit(1);
     }
-    api.goalResume(goalContext(hippoRoot), id);
+    api.goalResume(cliApiContext(hippoRoot, tenantId), id);
     console.log('ok');
 }
-export function cmdGoal(hippoRoot, args, flags) {
+export function handleGoal({ hippoRoot, tenantId, args, flags }) {
     const sub = args[0];
     if (!sub) {
         printError('Usage: hippo goal <push|list|complete|suspend|resume> [args]');
-        process.exit(1);
+        throw new CliExit(1);
     }
     const subArgs = args.slice(1);
     switch (sub) {
         case 'push':
-            cmdGoalPush(hippoRoot, subArgs, flags);
+            cmdGoalPush(hippoRoot, tenantId, subArgs, flags);
             return;
         case 'list':
-            cmdGoalList(hippoRoot, flags);
+            cmdGoalList(hippoRoot, tenantId, flags);
             return;
         case 'complete':
-            cmdGoalComplete(hippoRoot, subArgs, flags);
+            cmdGoalComplete(hippoRoot, tenantId, subArgs, flags);
             return;
         case 'suspend':
-            cmdGoalSuspend(hippoRoot, subArgs);
+            cmdGoalSuspend(hippoRoot, tenantId, subArgs);
             return;
         case 'resume':
-            cmdGoalResume(hippoRoot, subArgs);
+            cmdGoalResume(hippoRoot, tenantId, subArgs);
             return;
         default:
             printError(`Unknown goal subcommand: ${sub}. Expected: push | list | complete | suspend | resume.`);
-            process.exit(1);
+            throw new CliExit(1);
     }
 }
 //# sourceMappingURL=goals.js.map

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

@@ -1,40 +1,22 @@
 import type { HookRuntime } from '../core/capture-contract.js';
 import { type DeliveryEventType, type DeliveryRecorder } from '../store/delivery-recorder.js';
 import type { CliFlags } from './flag-values.js';
-/**
- * Detached worker that counts re-reads, runs sleep, then capture. Invoked via the internal
- * `__session-end-worker` subcommand (not user-facing). Failures in one stage
- * do not block the other.
- */
+/** Detached worker (internal `__session-end-worker`): counts re-reads, runs sleep, then capture; one stage failing does not block the other. */
 /** A folder without its own store never sleeps at session end, so its project's agent notes go to the global store here. */
 export declare function logSessionEndImport(logFile: string | null, transcriptPath: string | undefined): void;
-/**
- * Best-effort log line for the snapshot-close step in
- * `cmdSessionEndWorker`. `cmdSleep`/`cmdCapture` each tee console output to
- * `logFile` only for their own duration (the tee is restored before this
- * runs), so a plain `console.log` here would be silently discarded under
- * the detached worker's `stdio: 'ignore'` — write straight to the file
- * instead, matching capture.ts's `appendPreCompactLog` convention.
- */
+/** Best-effort log line for the cmdSessionEndWorker snapshot-close step: cmdSleep/cmdCapture restore their console tee before this runs,
+ * so console.log would be lost under the worker's `stdio: 'ignore'`; write to the file directly. */
 export declare function appendSessionEndCloseLog(logFile: string | null, message: string, opts?: {
     startFresh?: boolean;
 }): void;
+/** A session-end step that failed: one warn line, and the same text in the session log, the only place a detached worker's output survives. */
+export declare function reportSessionEndFailure<E>(logFile: string | null, step: string, err: E): void;
 export declare function hostSessionId(): string | undefined;
-/**
- * Compaction drops the pinned blocks the per-prompt hook injected
- * earlier, so record a `reset` for the payload's session and the next prompt
- * injects again even if nothing changed. `requiredSource` limits it to hook
- * payloads with that `source` (SessionStart fires for other reasons too).
- * Best-effort and silent: a malformed payload records nothing.
- */
+/** Compaction drops the pinned blocks the per-prompt hook injected, so record a `reset` for the payload's session and the next prompt injects again.
+ * `requiredSource` limits it to payloads with that `source`; best-effort and silent on a malformed payload. */
 export declare function resetHookInjection(hippoRoot: string, stdinText: string | undefined, requiredSource: string | null): void;
-/**
- * The store a Claude Code hook writes to: the project store when there is
- * one, else an existing global store, else the project path (which the hook
- * then skips, since hooks fire in every directory and must not create one).
- * Pre-compact and compact-resume must agree, or a snapshot saved to one store
- * is looked for in the other.
- */
+/** Store a hook writes to: the project store, else an existing global one, else the project path (skipped: hooks must not create a store).
+ * Pre-compact and compact-resume must agree, or a snapshot is looked for in the other store. */
 export declare function hookStoreRoot(hippoRoot: string): string;
 /** `--runtime copilot`, or `--format copilot` on `hippo context`, marks a Copilot hook: the flag decides, never the payload. */
 export declare function hookRuntime(flags: CliFlags): HookRuntime;

package/dist/cli/hook-runtime.js

@@ -13,16 +13,11 @@ import { blockHash } from '../util/token-text.js';
 import { importAtSessionEnd, currentMachine } from '../agent-memories/sync.js';
 import { summaryLine } from '../agent-memories/report.js';
 import { isGlobalStoreRoot } from '../core/project-identity.js';
-import { getGlobalRoot } from '../sharing/shared.js';
+import { getGlobalRoot } from '../sharing/global-store.js';
 import { sanitizeLogMessage } from '../capture/compact.js';
 import { resolveTenantId } from '../store/tenant.js';
 import { errorMessage, log } from '../util/log.js';
-import { printError } from './output.js';
-/**
- * Detached worker that counts re-reads, runs sleep, then capture. Invoked via the internal
- * `__session-end-worker` subcommand (not user-facing). Failures in one stage
- * do not block the other.
- */
+/** Detached worker (internal `__session-end-worker`): counts re-reads, runs sleep, then capture; one stage failing does not block the other. */
 /** A folder without its own store never sleeps at session end, so its project's agent notes go to the global store here. */
 export function logSessionEndImport(logFile, transcriptPath) {
     try {
@@ -37,14 +32,8 @@ export function logSessionEndImport(logFile, transcriptPath) {
         appendSessionEndCloseLog(logFile, `agent memory import failed: ${errorMessage(err)}`);
     }
 }
-/**
- * Best-effort log line for the snapshot-close step in
- * `cmdSessionEndWorker`. `cmdSleep`/`cmdCapture` each tee console output to
- * `logFile` only for their own duration (the tee is restored before this
- * runs), so a plain `console.log` here would be silently discarded under
- * the detached worker's `stdio: 'ignore'` — write straight to the file
- * instead, matching capture.ts's `appendPreCompactLog` convention.
- */
+/** Best-effort log line for the cmdSessionEndWorker snapshot-close step: cmdSleep/cmdCapture restore their console tee before this runs,
+ * so console.log would be lost under the worker's `stdio: 'ignore'`; write to the file directly. */
 export function appendSessionEndCloseLog(logFile, message, opts = {}) {
     if (!logFile)
         return;
@@ -60,17 +49,18 @@ export function appendSessionEndCloseLog(logFile, message, opts = {}) {
         log.debug(`session-end log not written: ${errorMessage(err)}`);
     }
 }
+/** A session-end step that failed: one warn line, and the same text in the session log, the only place a detached worker's output survives. */
+export function reportSessionEndFailure(logFile, step, err) {
+    const line = `${step} failed: ${errorMessage(err)}`;
+    log.warn(line);
+    appendSessionEndCloseLog(logFile, line);
+}
 // Claude Code exports its own session var, not ours; without the fallback agent-run recalls trace with no session.
 export function hostSessionId() {
     return envHippoSessionId() ?? envClaudeCodeSessionId();
 }
-/**
- * Compaction drops the pinned blocks the per-prompt hook injected
- * earlier, so record a `reset` for the payload's session and the next prompt
- * injects again even if nothing changed. `requiredSource` limits it to hook
- * payloads with that `source` (SessionStart fires for other reasons too).
- * Best-effort and silent: a malformed payload records nothing.
- */
+/** Compaction drops the pinned blocks the per-prompt hook injected, so record a `reset` for the payload's session and the next prompt injects again.
+ * `requiredSource` limits it to payloads with that `source`; best-effort and silent on a malformed payload. */
 export function resetHookInjection(hippoRoot, stdinText, requiredSource) {
     const sessionId = hookPayloadSessionId(stdinText, requiredSource);
     // A sub-agent's compaction leaves its parent's context, and the blocks in it, as they were.
@@ -80,13 +70,8 @@ export function resetHookInjection(hippoRoot, stdinText, requiredSource) {
         tenantId: resolveTenantId({}), sessionId, surface: 'hook', event: 'reset', items: 0, tokens: 0,
     });
 }
-/**
- * The store a Claude Code hook writes to: the project store when there is
- * one, else an existing global store, else the project path (which the hook
- * then skips, since hooks fire in every directory and must not create one).
- * Pre-compact and compact-resume must agree, or a snapshot saved to one store
- * is looked for in the other.
- */
+/** Store a hook writes to: the project store, else an existing global one, else the project path (skipped: hooks must not create a store).
+ * Pre-compact and compact-resume must agree, or a snapshot is looked for in the other store. */
 export function hookStoreRoot(hippoRoot) {
     if (isInitialized(hippoRoot))
         return hippoRoot;
@@ -116,8 +101,7 @@ export function startDeliveryRecorder(hippoRoot, stdinText, runtime, eventType)
         });
     }
     catch (error) {
-        // The hook's one-line stderr contract pins this exact text, so it bypasses the leveled logger.
-        printError(`[hippo] delivery ledger skipped:${errorMessage(error)}`);
+        log.warn(`delivery ledger skipped: ${errorMessage(error)}`);
         return null;
     }
 }

package/dist/cli/init.d.ts

@@ -1,3 +1,3 @@
-import { type CliFlags } from './flag-values.js';
-export declare function cmdInit(hippoRoot: string, flags: CliFlags): void;
+import { type CommandContext } from './flag-values.js';
+export declare function handleInit({ hippoRoot, flags }: CommandContext): void;
 //# sourceMappingURL=init.d.ts.map