memorix 1.6.0 → 1.6.1

package/src/dashboard/project-classification.ts

@@ -1,64 +1,64 @@
-/**
- * Project classification helpers — shared by /api/projects and /api/identity.
- *
- * Three kinds:
- *   - 'real':        genuine user projects (e.g. AVIDS2/memorix, github.com/org/repo)
- *   - 'temporary':   test/demo/smoke/e2e scratch projects (local/task-*, local/smoke-*, etc.)
- *   - 'placeholder': unresolved / obviously broken IDs (placeholder/*, __unresolved__, System32)
- *
- * A 'dirty' project is one with a clearly broken canonical ID (System32 etc.).
- * 'dirty' and 'temporary' are orthogonal axes:
- *   - local/task-abc        → temporary, NOT dirty
- *   - placeholder/xxx       → placeholder, dirty
- *   - System32\something    → real-looking location but dirty (broken ID)
- */
-
-export type ProjectKind = 'real' | 'temporary' | 'placeholder';
-
-/** Regex list — anything matching is temporary (scratch projects) */
-const TEMPORARY_PATTERNS: RegExp[] = [
-  /^local\/task-/i,
-  /^local\/smoke-/i,
-  /^local\/release-smoke-/i,
-  /^local\/memorix-e2e-/i,
-  /^local\/orchestrate-/i,
-  /^local\/scratch-/i,
-  /^local\/tmp-/i,
-];
-
-/** Regex list — anything matching is placeholder/unresolved */
-const PLACEHOLDER_PATTERNS: RegExp[] = [
-  /^__unresolved__$/,
-  /^placeholder\//i,
-];
-
-/** Regex list — IDs that indicate a broken canonical ID (dirty). */
-const DIRTY_PATTERNS: RegExp[] = [
-  /^placeholder\//i,
-  /System32/i,
-  /Microsoft VS Code/i,
-  /node_modules/i,
-  /\.vscode/i,
-  /^local\/[A-Z]:\\/i,
-];
-
-export function classifyProjectId(id: string): ProjectKind {
-  if (!id) return 'placeholder';
-  if (PLACEHOLDER_PATTERNS.some(p => p.test(id))) return 'placeholder';
-  if (TEMPORARY_PATTERNS.some(p => p.test(id))) return 'temporary';
-  return 'real';
-}
-
-export function isDirtyProjectId(id: string): boolean {
-  if (!id) return false;
-  return DIRTY_PATTERNS.some(p => p.test(id));
-}
-
-/** Friendly label for UI badges */
-export function projectKindLabel(kind: ProjectKind): string {
-  switch (kind) {
-    case 'real': return 'real';
-    case 'temporary': return 'temporary';
-    case 'placeholder': return 'placeholder';
-  }
-}
+/**
+ * Project classification helpers — shared by /api/projects and /api/identity.
+ *
+ * Three kinds:
+ *   - 'real':        genuine user projects (e.g. AVIDS2/memorix, github.com/org/repo)
+ *   - 'temporary':   test/demo/smoke/e2e scratch projects (local/task-*, local/smoke-*, etc.)
+ *   - 'placeholder': unresolved / obviously broken IDs (placeholder/*, __unresolved__, System32)
+ *
+ * A 'dirty' project is one with a clearly broken canonical ID (System32 etc.).
+ * 'dirty' and 'temporary' are orthogonal axes:
+ *   - local/task-abc        → temporary, NOT dirty
+ *   - placeholder/xxx       → placeholder, dirty
+ *   - System32\something    → real-looking location but dirty (broken ID)
+ */
+
+export type ProjectKind = 'real' | 'temporary' | 'placeholder';
+
+/** Regex list — anything matching is temporary (scratch projects) */
+const TEMPORARY_PATTERNS: RegExp[] = [
+  /^local\/task-/i,
+  /^local\/smoke-/i,
+  /^local\/release-smoke-/i,
+  /^local\/memorix-e2e-/i,
+  /^local\/orchestrate-/i,
+  /^local\/scratch-/i,
+  /^local\/tmp-/i,
+];
+
+/** Regex list — anything matching is placeholder/unresolved */
+const PLACEHOLDER_PATTERNS: RegExp[] = [
+  /^__unresolved__$/,
+  /^placeholder\//i,
+];
+
+/** Regex list — IDs that indicate a broken canonical ID (dirty). */
+const DIRTY_PATTERNS: RegExp[] = [
+  /^placeholder\//i,
+  /System32/i,
+  /Microsoft VS Code/i,
+  /node_modules/i,
+  /\.vscode/i,
+  /^local\/[A-Z]:\\/i,
+];
+
+export function classifyProjectId(id: string): ProjectKind {
+  if (!id) return 'placeholder';
+  if (PLACEHOLDER_PATTERNS.some(p => p.test(id))) return 'placeholder';
+  if (TEMPORARY_PATTERNS.some(p => p.test(id))) return 'temporary';
+  return 'real';
+}
+
+export function isDirtyProjectId(id: string): boolean {
+  if (!id) return false;
+  return DIRTY_PATTERNS.some(p => p.test(id));
+}
+
+/** Friendly label for UI badges */
+export function projectKindLabel(kind: ProjectKind): string {
+  switch (kind) {
+    case 'real': return 'real';
+    case 'temporary': return 'temporary';
+    case 'placeholder': return 'placeholder';
+  }
+}

package/src/embedding/provider.ts

@@ -175,12 +175,26 @@ let initPromise: Promise<EmbeddingProvider | null> | null = null;
 type EmbeddingMode = 'off' | 'fastembed' | 'transformers' | 'api' | 'auto';
 type ProviderKind = 'api' | 'fastembed' | 'transformers' | 'unknown';
 
+export type EmbeddingRuntimeStatus = 'disabled' | 'uninitialized' | 'ready' | 'degraded';
+export type EmbeddingFailureKind = 'authorization' | 'billing' | 'timeout' | 'upstream';
+
+export interface EmbeddingRuntimeHealth {
+  status: EmbeddingRuntimeStatus;
+  provider?: { name: string; dimensions: number };
+  failure?: {
+    kind: EmbeddingFailureKind;
+    occurredAt: string;
+    retryAfterMs: number;
+  };
+}
+
 /**
  * Tracks whether the last init attempt resulted in a temporary failure
  * (mode != 'off' but provider returned null). When true, the next
  * getEmbeddingProvider() call will retry instead of returning cached null.
  */
 let lastInitWasTemporaryFailure = false;
+let lastEmbeddingFailure: { kind: EmbeddingFailureKind; occurredAt: number } | null = null;
 let lastEmbeddingWarning = '';
 let lastEmbeddingWarningAt = 0;
 const WARNING_COOLDOWN_MS = 30_000;
@@ -271,13 +285,38 @@ function isTemporaryEmbeddingFailure(error: unknown): boolean {
   );
 }
 
+function classifyEmbeddingFailure(error: unknown): EmbeddingFailureKind {
+  const message = error instanceof Error ? error.message : String(error);
+  if (/embedding api error \(401\)|invalid_api_key|incorrect api key|unauthorized/i.test(message)) {
+    return 'authorization';
+  }
+  if (/embedding api error \(402\)|quota exceeded|account balance/i.test(message)) {
+    return 'billing';
+  }
+  if (/embedding api timeout|abort/i.test(message)) {
+    return 'timeout';
+  }
+  return 'upstream';
+}
+
 function markTemporaryFailure(reason: unknown): void {
   provider = null;
   initPromise = null;
   lastInitWasTemporaryFailure = true;
   lastFailureTimestamp = Date.now();
+  lastEmbeddingFailure = {
+    kind: classifyEmbeddingFailure(reason),
+    occurredAt: lastFailureTimestamp,
+  };
   const message = reason instanceof Error ? reason.message : String(reason);
-  warnOnce(`[memorix] Embedding provider temporarily unavailable at runtime: ${message}`);
+  warnOnce(`[memorix] Embedding provider unavailable at runtime: ${message}`);
+}
+
+function markProviderReady(candidate: EmbeddingProvider): EmbeddingProvider {
+  provider = wrapProvider(candidate);
+  lastInitWasTemporaryFailure = false;
+  lastEmbeddingFailure = null;
+  return provider;
 }
 
 async function createFastEmbedProvider(): Promise<EmbeddingProvider | null> {
@@ -438,7 +477,7 @@ export async function getEmbeddingProvider(
     if (mode === 'fastembed') {
       const initialized = await createFastEmbedProvider();
       if (!initialized) return null;
-      provider = wrapProvider(initialized);
+      provider = markProviderReady(initialized);
       warnOnce(`[memorix] Embedding provider: ${provider.name} (${provider.dimensions}d)`);
       return provider;
     }
@@ -447,7 +486,7 @@ export async function getEmbeddingProvider(
     if (mode === 'transformers') {
       const initialized = await createTransformersProvider();
       if (!initialized) return null;
-      provider = wrapProvider(initialized);
+      provider = markProviderReady(initialized);
       warnOnce(`[memorix] Embedding provider: ${provider.name} (${provider.dimensions}d)`);
       return provider;
     }
@@ -456,7 +495,7 @@ export async function getEmbeddingProvider(
     if (mode === 'api') {
       const initialized = await createAPIProvider(options);
       if (!initialized) return null;
-      provider = wrapProvider(initialized);
+      provider = markProviderReady(initialized);
       warnOnce(`[memorix] Embedding provider: ${provider.name} (${provider.dimensions}d)`);
       return provider;
     }
@@ -465,7 +504,7 @@ export async function getEmbeddingProvider(
     if (hasAPIEmbeddingConfig()) {
       const initialized = await createAPIProvider(options);
       if (initialized) {
-        provider = wrapProvider(initialized);
+        provider = markProviderReady(initialized);
         warnOnce(`[memorix] Embedding provider: ${provider.name} (${provider.dimensions}d)`);
         return provider;
       }
@@ -473,7 +512,7 @@ export async function getEmbeddingProvider(
 
     const localFallback = await createLocalFallbackProvider();
     if (localFallback) {
-      provider = wrapProvider(localFallback);
+      provider = markProviderReady(localFallback);
       warnOnce(`[memorix] Embedding provider: ${provider.name} (${provider.dimensions}d)`);
       return provider;
     }
@@ -507,6 +546,36 @@ export async function isVectorSearchAvailable(): Promise<boolean> {
   return p !== null;
 }
 
+/**
+ * Process-local embedding health, intentionally read-only and network-free.
+ * It lets the control plane distinguish a configured provider from one that
+ * has degraded after a live credential, billing, timeout, or upstream error.
+ */
+export function getEmbeddingRuntimeHealth(): EmbeddingRuntimeHealth {
+  const mode = getEmbeddingMode();
+  if (mode === 'off') return { status: 'disabled' };
+
+  if (lastInitWasTemporaryFailure && lastEmbeddingFailure) {
+    return {
+      status: 'degraded',
+      failure: {
+        kind: lastEmbeddingFailure.kind,
+        occurredAt: new Date(lastEmbeddingFailure.occurredAt).toISOString(),
+        retryAfterMs: Math.max(0, RETRY_COOLDOWN_MS - (Date.now() - lastEmbeddingFailure.occurredAt)),
+      },
+    };
+  }
+
+  if (provider) {
+    return {
+      status: 'ready',
+      provider: { name: provider.name, dimensions: provider.dimensions },
+    };
+  }
+
+  return { status: 'uninitialized' };
+}
+
 /**
  * Check if embedding is explicitly disabled by configuration (mode === 'off').
  *
@@ -529,6 +598,7 @@ export function resetProvider(): void {
   initPromise = null;
   lastInitWasTemporaryFailure = false;
   lastFailureTimestamp = 0;
+  lastEmbeddingFailure = null;
   lastEmbeddingWarning = '';
   lastEmbeddingWarningAt = 0;
 }

package/src/git/hooks-path.ts

@@ -1,85 +1,85 @@
-/**
- * Git hooks path resolver — worktree-safe.
- *
- * In a normal repo:   .git is a directory  → hooks at .git/hooks/
- * In a git worktree:  .git is a FILE containing "gitdir: /path/to/actual/git/dir"
- *                     → hooks at that resolved path + /hooks/
- *
- * This utility ensures all hook install/uninstall/check operations
- * work correctly in both scenarios.
- */
-
-import { existsSync, readFileSync, statSync, mkdirSync } from 'node:fs';
-import path from 'node:path';
-
-/**
- * Resolve the actual .git directory path, following worktree indirection.
- *
- * @param projectRoot - The root of the working tree (where .git lives)
- * @returns Absolute path to the real git dir, or null if no .git found
- */
-export function resolveGitDir(projectRoot: string): string | null {
-  const dotGit = path.join(projectRoot, '.git');
-
-  if (!existsSync(dotGit)) return null;
-
-  const stat = statSync(dotGit);
-
-  if (stat.isDirectory()) {
-    // Normal repo — .git is a directory
-    return dotGit;
-  }
-
-  if (stat.isFile()) {
-    // Worktree — .git is a file: "gitdir: /path/to/actual/git/dir"
-    try {
-      const content = readFileSync(dotGit, 'utf-8').trim();
-      const match = content.match(/^gitdir:\s*(.+)$/);
-      if (match) {
-        const gitdir = match[1].trim();
-        // Resolve relative paths against the project root
-        const resolved = path.isAbsolute(gitdir)
-          ? gitdir
-          : path.resolve(projectRoot, gitdir);
-        if (existsSync(resolved)) {
-          return resolved;
-        }
-      }
-    } catch {
-      // Unreadable .git file — fall through
-    }
-  }
-
-  return null;
-}
-
-/**
- * Resolve the hooks directory for a project (read-only — does NOT create directories).
- * Handles both normal repos and git worktrees.
- *
- * @param projectRoot - The root of the working tree
- * @returns Object with hooksDir and hookPath for post-commit, or null if no .git found
- */
-export function resolveHooksDir(projectRoot: string): { hooksDir: string; hookPath: string } | null {
-  const gitDir = resolveGitDir(projectRoot);
-  if (!gitDir) return null;
-
-  const hooksDir = path.join(gitDir, 'hooks');
-
-  return {
-    hooksDir,
-    hookPath: path.join(hooksDir, 'post-commit'),
-  };
-}
-
-/**
- * Resolve hooks directory AND ensure it exists on disk.
- * Use this only in write paths (hook install / autoHook).
- */
-export function ensureHooksDir(projectRoot: string): { hooksDir: string; hookPath: string } | null {
-  const resolved = resolveHooksDir(projectRoot);
-  if (!resolved) return null;
-
-  mkdirSync(resolved.hooksDir, { recursive: true });
-  return resolved;
-}
+/**
+ * Git hooks path resolver — worktree-safe.
+ *
+ * In a normal repo:   .git is a directory  → hooks at .git/hooks/
+ * In a git worktree:  .git is a FILE containing "gitdir: /path/to/actual/git/dir"
+ *                     → hooks at that resolved path + /hooks/
+ *
+ * This utility ensures all hook install/uninstall/check operations
+ * work correctly in both scenarios.
+ */
+
+import { existsSync, readFileSync, statSync, mkdirSync } from 'node:fs';
+import path from 'node:path';
+
+/**
+ * Resolve the actual .git directory path, following worktree indirection.
+ *
+ * @param projectRoot - The root of the working tree (where .git lives)
+ * @returns Absolute path to the real git dir, or null if no .git found
+ */
+export function resolveGitDir(projectRoot: string): string | null {
+  const dotGit = path.join(projectRoot, '.git');
+
+  if (!existsSync(dotGit)) return null;
+
+  const stat = statSync(dotGit);
+
+  if (stat.isDirectory()) {
+    // Normal repo — .git is a directory
+    return dotGit;
+  }
+
+  if (stat.isFile()) {
+    // Worktree — .git is a file: "gitdir: /path/to/actual/git/dir"
+    try {
+      const content = readFileSync(dotGit, 'utf-8').trim();
+      const match = content.match(/^gitdir:\s*(.+)$/);
+      if (match) {
+        const gitdir = match[1].trim();
+        // Resolve relative paths against the project root
+        const resolved = path.isAbsolute(gitdir)
+          ? gitdir
+          : path.resolve(projectRoot, gitdir);
+        if (existsSync(resolved)) {
+          return resolved;
+        }
+      }
+    } catch {
+      // Unreadable .git file — fall through
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Resolve the hooks directory for a project (read-only — does NOT create directories).
+ * Handles both normal repos and git worktrees.
+ *
+ * @param projectRoot - The root of the working tree
+ * @returns Object with hooksDir and hookPath for post-commit, or null if no .git found
+ */
+export function resolveHooksDir(projectRoot: string): { hooksDir: string; hookPath: string } | null {
+  const gitDir = resolveGitDir(projectRoot);
+  if (!gitDir) return null;
+
+  const hooksDir = path.join(gitDir, 'hooks');
+
+  return {
+    hooksDir,
+    hookPath: path.join(hooksDir, 'post-commit'),
+  };
+}
+
+/**
+ * Resolve hooks directory AND ensure it exists on disk.
+ * Use this only in write paths (hook install / autoHook).
+ */
+export function ensureHooksDir(projectRoot: string): { hooksDir: string; hookPath: string } | null {
+  const resolved = resolveHooksDir(projectRoot);
+  if (!resolved) return null;
+
+  mkdirSync(resolved.hooksDir, { recursive: true });
+  return resolved;
+}

package/src/hooks/handler.ts

@@ -21,6 +21,11 @@ import { normalizeHookInput } from './normalizer.js';
 import { detectBestPattern, patternToObservationType } from './pattern-detector.js';
 import { isSignificantKnowledge, isRetrievedResult, isTrivialCommand } from './significance-filter.js';
 import type { AgentName, HookEvent, HookOutput, NormalizedHookInput } from './types.js';
+import {
+  hookObservationRuntimeOptions,
+  readHookStdin,
+  resolveHookStdinTimeoutMs,
+} from './lifecycle.js';
 
 type HookInjectionMode = 'full' | 'minimal' | 'silent';
 type HookContextTarget = 'hook-session-start' | 'hook-user-prompt';
@@ -762,23 +767,9 @@ export function formatHookOutput(
  * Called by the CLI: `memorix hook`
  */
 export async function runHook(agentOverride?: string, eventOverride?: string): Promise<void> {
-  // Read stdin with a timeout — some hosts (e.g. Gemini CLI) may not close
-  // stdin promptly, causing `for await` to hang until the process is killed.
-  const rawInput = await new Promise<string>((resolve) => {
-    const chunks: Buffer[] = [];
-    const finish = () => resolve(Buffer.concat(chunks).toString('utf-8').trim());
-
-    // Hard timeout: resolve with whatever we have after 3 s
-    const timer = setTimeout(() => {
-      process.stdin.removeAllListeners('data');
-      process.stdin.removeAllListeners('end');
-      finish();
-    }, 3_000);
-
-    process.stdin.on('data', (chunk: Buffer) => { chunks.push(chunk); });
-    process.stdin.on('end', () => { clearTimeout(timer); finish(); });
-    process.stdin.on('error', () => { clearTimeout(timer); finish(); });
-  });
+  // Some hosts (e.g. Gemini CLI) may not close stdin promptly. Bound the
+  // read and release the stream so an open pipe cannot keep Node alive.
+  const rawInput = await readHookStdin(process.stdin, resolveHookStdinTimeoutMs());
 
   if (!rawInput) {
     process.stdout.write(JSON.stringify({ continue: true }));
@@ -841,7 +832,7 @@ export async function runHook(agentOverride?: string, eventOverride?: string): P
       await initObservationStore(dataDir);
       await initMSStore(dataDir);
       await initSessStore(dataDir);
-      await initObservations(dataDir);
+      await initObservations(dataDir, hookObservationRuntimeOptions(rawProject.rootPath));
       await storeObservation({ ...observation, projectId, sourceDetail: 'hook' });
       // Automatic capture is deliberately quiet. Candidate state and later
       // qualification are visible through Memorix inspection, not injected as

package/src/hooks/lifecycle.ts

@@ -0,0 +1,173 @@
+/**
+ * Process-level lifecycle for `memorix hook`.
+ *
+ * Hosts invoke this command on every agent event. It must read stdin, emit
+ * one JSON object, and exit. Leftover hook processes are a bug: they reserve
+ * heap, orphan onto PID 1, and can exhaust a laptop.
+ */
+
+import type { ObservationRuntimeOptions } from '../memory/observations.js';
+
+export const DEFAULT_HOOK_TIMEOUT_MS = 20_000;
+export const MIN_HOOK_TIMEOUT_MS = 1_000;
+export const MAX_HOOK_TIMEOUT_MS = 120_000;
+
+export const DEFAULT_HOOK_STDIN_TIMEOUT_MS = 3_000;
+export const MIN_HOOK_STDIN_TIMEOUT_MS = 100;
+export const MAX_HOOK_STDIN_TIMEOUT_MS = 30_000;
+
+type EnvMap = NodeJS.ProcessEnv | Record<string, string | undefined>;
+
+function parseBoundedMs(
+  raw: string | undefined,
+  fallback: number,
+  min: number,
+  max: number,
+): number {
+  const value = raw?.trim();
+  if (!value) return fallback;
+  const parsed = Number(value);
+  if (!Number.isFinite(parsed) || parsed <= 0) return fallback;
+  return Math.max(min, Math.min(max, Math.floor(parsed)));
+}
+
+export function resolveHookTimeoutMs(env: EnvMap = process.env): number {
+  return parseBoundedMs(
+    env.MEMORIX_HOOK_TIMEOUT_MS,
+    DEFAULT_HOOK_TIMEOUT_MS,
+    MIN_HOOK_TIMEOUT_MS,
+    MAX_HOOK_TIMEOUT_MS,
+  );
+}
+
+export function resolveHookStdinTimeoutMs(env: EnvMap = process.env): number {
+  return parseBoundedMs(
+    env.MEMORIX_HOOK_STDIN_TIMEOUT_MS,
+    DEFAULT_HOOK_STDIN_TIMEOUT_MS,
+    MIN_HOOK_STDIN_TIMEOUT_MS,
+    MAX_HOOK_STDIN_TIMEOUT_MS,
+  );
+}
+
+export function hookObservationRuntimeOptions(projectRoot: string): ObservationRuntimeOptions {
+  return {
+    embeddingWriteMode: 'deferred',
+    projectRoot,
+  };
+}
+
+type HookStdin = NodeJS.ReadableStream & {
+  pause?: () => void;
+  destroy?: (error?: Error) => void;
+  unref?: () => void;
+  isTTY?: boolean;
+};
+
+/**
+ * Read hook JSON from a pipe. Resolves on EOF, stream error, or idle timeout.
+ * Always releases the stream so an open stdin cannot keep Node alive.
+ */
+export async function readHookStdin(stdin: HookStdin, timeoutMs: number): Promise<string> {
+  return new Promise<string>((resolve) => {
+    const chunks: Buffer[] = [];
+    let settled = false;
+
+    const finish = () => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      stdin.removeListener('data', onData);
+      stdin.removeListener('end', finish);
+      stdin.removeListener('error', finish);
+      stdin.pause?.();
+      if (!stdin.isTTY) {
+        stdin.destroy?.();
+      } else {
+        stdin.unref?.();
+      }
+      resolve(Buffer.concat(chunks).toString('utf-8').trim());
+    };
+
+    const onData = (chunk: Buffer | string) => {
+      chunks.push(typeof chunk === 'string' ? Buffer.from(chunk) : chunk);
+    };
+
+    const timer = setTimeout(finish, timeoutMs);
+    stdin.on('data', onData);
+    stdin.on('end', finish);
+    stdin.on('error', finish);
+  });
+}
+
+export interface HookDeadlineIo {
+  write(chunk: string): unknown;
+}
+
+export interface HookDeadlineOptions {
+  timeoutMs: number;
+  run: () => Promise<void>;
+  stdout?: HookDeadlineIo;
+  stderr?: HookDeadlineIo;
+  exit?: (code: number) => void;
+}
+
+function writeContinue(stdout: HookDeadlineIo): void {
+  try {
+    stdout.write(JSON.stringify({ continue: true }));
+  } catch {
+    // The host already closed the pipe. Exiting is still required.
+  }
+}
+
+/**
+ * Run a hook body under a hard deadline, then force-exit.
+ * `withTimeout` cannot abort in-flight fetches; process.exit is the backstop.
+ */
+export async function runHookWithDeadline(options: HookDeadlineOptions): Promise<void> {
+  const stdout = options.stdout ?? process.stdout;
+  const stderr = options.stderr ?? process.stderr;
+  const exit = options.exit ?? ((code: number) => { process.exit(code); });
+
+  await new Promise<void>((resolve) => {
+    let finished = false;
+
+    const settle = () => {
+      if (finished) return;
+      finished = true;
+      clearTimeout(timer);
+      resolve();
+    };
+
+    const timer = setTimeout(() => {
+      if (finished) return;
+      try {
+        stderr.write(`[memorix] hook timed out after ${options.timeoutMs}ms\n`);
+      } catch {
+        // stderr may already be closed
+      }
+      writeContinue(stdout);
+      exit(0);
+      settle();
+    }, options.timeoutMs);
+
+    options.run().then(
+      () => {
+        if (finished) return;
+        exit(0);
+        settle();
+      },
+      (error: unknown) => {
+        if (finished) return;
+        try {
+          const message = error instanceof Error ? error.message : String(error);
+          stderr.write(`[memorix] hook failed: ${message}\n`);
+        } catch {
+          // stderr may already be closed
+        }
+        writeContinue(stdout);
+        exit(0);
+        settle();
+      },
+    );
+  });
+}