@schlessera/brain-ui-server 0.34.1 → 0.35.0

package/src/activity/recorder.ts

@@ -46,8 +46,21 @@ export interface TurnRecorder {
   readonly runId: string;
   observeFrame(msg: ServerMessage): void;
   observeActivity(event: BackendActivityEvent): void;
+  /** Record that this turn's principal was revoked while work kept running. */
+  recordPrincipalRevocation(principalId: string): void;
+  /** Record a live follow-up that joined this already-running turn. */
+  recordFollowUp(principalId: string): void;
+  /** Record who cancelled this turn or an interactive prompt within it. */
+  recordCancellation(principalId: string, kind?: "turn" | "ask_user"): void;
+  /** Record who answered an ask-user interaction. */
+  recordAskUserResponse(principalId: string): void;
   /** The user's approval decision arrived for a gated tool call. */
-  onApprovalDecision(toolUseId: string, allowed: boolean): void;
+  onApprovalDecision(
+    toolUseId: string,
+    decision: "allow" | "always_allow" | "deny",
+    requestKind: "tool" | "command",
+    principalId?: string
+  ): void;
   /**
    * Close the turn: merge the buffered result enrichment into the root's
    * single terminal write, cascade-cancel anything left open, roll up.
@@ -64,6 +77,8 @@ export function createTurnRecorder(
     profileId?: string;
     /** Billing classification of that profile, resolved at run start (U3). */
     billingMode?: BillingMode;
+    /** Principal that initiated this turn; absent means unattributed. */
+    principalId?: string;
   }
 ): TurnRecorder {
   const { store, onWrite, log } = deps;
@@ -76,6 +91,7 @@ export function createTurnRecorder(
   let resultOutcome: SpanOutcome | null = null;
   let resultUsage: SpanUsage | undefined;
   let resultAttrs: Record<string, unknown> | undefined;
+  let principalRevocationRecorded = false;
 
   const guard = (fn: () => void) => {
     try {
@@ -99,6 +115,7 @@ export function createTurnRecorder(
       kind: "turn",
       origin: "session",
       sessionId,
+      principalId: turn.principalId,
       // Profile + billing ride the ROOT span so the rollup can price the run
       // without any registry or env lookup of its own (a root missing the
       // billing attr falls back to env classification at rollup time).
@@ -253,9 +270,57 @@ export function createTurnRecorder(
       });
     },
 
-    onApprovalDecision(toolUseId, allowed) {
+    recordPrincipalRevocation(principalId) {
       guard(() => {
-        if (allowed) {
+        if (finished || principalRevocationRecorded) return;
+        ensureRoot();
+        store.appendEvent(rootSpanId, "principal_revoked", { principalId });
+        principalRevocationRecorded = true;
+        onWrite?.();
+      });
+    },
+
+    recordFollowUp(principalId) {
+      guard(() => {
+        if (finished) return;
+        ensureRoot();
+        store.appendEvent(rootSpanId, "follow_up", { principalId });
+        onWrite?.();
+      });
+    },
+
+    recordCancellation(principalId, kind = "turn") {
+      guard(() => {
+        if (finished) return;
+        ensureRoot();
+        store.appendEvent(rootSpanId, `${kind}_cancelled`, { principalId });
+        onWrite?.();
+      });
+    },
+
+    recordAskUserResponse(principalId) {
+      guard(() => {
+        if (finished) return;
+        ensureRoot();
+        store.appendEvent(rootSpanId, "ask_user_response", { principalId });
+        onWrite?.();
+      });
+    },
+
+    onApprovalDecision(toolUseId, decision, requestKind, principalId) {
+      guard(() => {
+        if (principalId) {
+          // One tool can raise several approval requests. The span-level actor
+          // remains the latest responder for compact views, while this
+          // append-only event preserves every decision and actor in order.
+          store.appendEvent(toolUseId, "approval_decision", {
+            principalId,
+            decision,
+            requestKind,
+          });
+          store.patchSpan(toolUseId, { principalId });
+        }
+        if (decision !== "deny") {
           // Everything before this moment was approval wait, not execution.
           store.patchSpan(toolUseId, { waitUntil: Date.now() });
         } else {

package/src/activity/runtime.ts

@@ -58,11 +58,8 @@ export function createActivityRuntime(
   const store = createActivityStore(db, deps.pricing ? { pricing: deps.pricing } : {});
   const stream = createActivityStream(store, log);
 
-  // The notifier is created BEFORE the boot sweep: its change cursor starts
-  // at the current head, so the terminal changes the sweep writes are above
-  // it and the first tick turns restart-interrupted runs into failure
-  // intents. Created after, the sweep's changes would sit below the cursor
-  // and a turn killed by a restart would never be notified.
+  // The notifier resumes its persisted cursor, including terminal changes
+  // committed while this server was down and interruptions from the boot sweep.
   const notifier = createActivityNotifier({
     db,
     store,

package/src/activity/sql.ts

@@ -17,11 +17,12 @@ export const ACTIVITY_SQL = {
     "SELECT span_id FROM activity_spans WHERE run_id = ? AND outcome IS NULL ORDER BY started_at DESC",
   spansByRun: "SELECT * FROM activity_spans WHERE run_id = ? ORDER BY started_at",
   upsertRollup: `INSERT INTO activity_run_rollups
-         (run_id, origin, name, session_id, job_name, started_at, ended_at, outcome,
+         (run_id, origin, name, session_id, job_name, principal_id, principal_label,
+          principal_kind, started_at, ended_at, outcome,
           duration_ms, span_count, input_tokens, output_tokens, cache_read_tokens,
           cache_creation_tokens, cost_usd, effective_cost_usd, billing_mode,
           pricing_estimate, failure_reason, detail_pruned)
-       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, 0)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, 0)
        ON CONFLICT(run_id) DO UPDATE SET
          ended_at = excluded.ended_at, outcome = excluded.outcome,
          duration_ms = excluded.duration_ms, span_count = excluded.span_count,
@@ -48,10 +49,11 @@ export const ACTIVITY_SQL = {
          END,
          failure_reason = excluded.failure_reason`,
   insertSpan: `INSERT INTO activity_spans
-             (span_id, run_id, parent_span_id, name, kind, origin, session_id, job_name,
+             (span_id, run_id, parent_span_id, name, kind, origin, session_id, job_name, principal_id,
               attrs, started_at, writer, last_heartbeat_at)
-           VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
-  patchSpan: `UPDATE activity_spans SET attrs = ?, wait_until = COALESCE(?, wait_until),
+           VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+  patchSpan: `UPDATE activity_spans SET principal_id = COALESCE(?, principal_id),
+             attrs = ?, wait_until = COALESCE(?, wait_until),
              input_tokens = COALESCE(?, input_tokens),
              output_tokens = COALESCE(?, output_tokens),
              cache_read_tokens = COALESCE(?, cache_read_tokens),

package/src/activity/store.ts

@@ -38,6 +38,7 @@ import {
   resolveStandalonePricingConfig,
 } from "../config/env.js";
 import { createModelPricing, type PricingRates } from "../pricing/model-pricing.js";
+import type { PrincipalKind } from "../db/principals.js";
 import { ACTIVITY_SQL } from "./sql.js";
 
 export const SPAN_OUTCOMES = [
@@ -53,6 +54,12 @@ export type SpanOutcome = (typeof SPAN_OUTCOMES)[number];
 export type SpanKind = "turn" | "tool" | "subagent" | "cron";
 export type SpanOrigin = "session" | "cron";
 
+function isPrincipalKind(value: unknown): value is PrincipalKind {
+  return (
+    value === "owner" || value === "agent" || value === "ambient" || value === "system"
+  );
+}
+
 /** Token usage as spans carry it — OTel GenAI attribute semantics. */
 export interface SpanUsage {
   inputTokens?: number;
@@ -72,6 +79,7 @@ export interface SpanRow {
   origin: SpanOrigin;
   sessionId: string | null;
   jobName: string | null;
+  principalId: string | null;
   attrs: Record<string, unknown>;
   startedAt: number;
   waitUntil: number | null;
@@ -99,6 +107,9 @@ export interface RunRollupRow {
   name: string;
   sessionId: string | null;
   jobName: string | null;
+  principalId: string | null;
+  principalLabel: string | null;
+  principalKind: PrincipalKind | null;
   startedAt: number;
   endedAt: number | null;
   outcome: SpanOutcome | null;
@@ -131,6 +142,9 @@ export function rowToRunRollup(r: any): RunRollupRow {
     name: r.name,
     sessionId: r.session_id,
     jobName: r.job_name,
+    principalId: r.principal_id ?? null,
+    principalLabel: r.principal_label ?? null,
+    principalKind: isPrincipalKind(r.principal_kind) ? r.principal_kind : null,
     startedAt: r.started_at,
     endedAt: r.ended_at,
     outcome: r.outcome,
@@ -183,6 +197,7 @@ export interface StartSpanInput {
   origin: SpanOrigin;
   sessionId?: string;
   jobName?: string;
+  principalId?: string;
   attrs?: Record<string, unknown>;
   startedAt?: number;
 }
@@ -237,7 +252,12 @@ export interface ActivityStore {
   /** Non-terminal field updates (usage enrichment, wait boundary, attrs). */
   patchSpan(
     spanId: string,
-    patch: { attrs?: Record<string, unknown>; usage?: SpanUsage; waitUntil?: number }
+    patch: {
+      principalId?: string;
+      attrs?: Record<string, unknown>;
+      usage?: SpanUsage;
+      waitUntil?: number;
+    }
   ): boolean;
   /**
    * Append one event; null (nothing written) for an unknown span. `cap`
@@ -347,6 +367,7 @@ export function createActivityStore(
       origin: r.origin,
       sessionId: r.session_id,
       jobName: r.job_name,
+      principalId: r.principal_id ?? null,
       attrs: safeParse(r.attrs) ?? {},
       startedAt: r.started_at,
       waitUntil: r.wait_until,
@@ -492,6 +513,11 @@ export function createActivityStore(
             ? (priced.estimate ? 1 : 0)
             : null;
     const costUsd = root.usage.costUsd ?? priced?.costUsd ?? null;
+    const principal = root.principalId
+      ? (db
+          .query("SELECT label, kind FROM principals WHERE id = ?")
+          .get(root.principalId) as { label: string; kind: PrincipalKind } | null)
+      : null;
 
     db.query(
       ACTIVITY_SQL.upsertRollup
@@ -511,6 +537,9 @@ export function createActivityStore(
       root.name,
       root.sessionId,
       root.jobName,
+      root.principalId,
+      principal?.label ?? null,
+      principal?.kind ?? null,
       root.startedAt,
       root.endedAt,
       root.outcome,
@@ -543,6 +572,7 @@ export function createActivityStore(
           input.origin,
           input.sessionId ?? null,
           input.jobName ?? null,
+          input.principalId ?? null,
           input.attrs ? JSON.stringify(input.attrs) : null,
           startedAt,
           writer,
@@ -568,6 +598,7 @@ export function createActivityStore(
           : existing.attrs;
         const u = patch.usage ?? {};
         db.query(ACTIVITY_SQL.patchSpan).run(
+          patch.principalId ?? null,
           attrs,
           patch.waitUntil ?? null,
           u.inputTokens ?? null,

package/src/activity/stream.ts

@@ -77,6 +77,7 @@ export function toWireSpan(span: SpanRow): ActivitySpan {
     origin: span.origin,
     sessionId: span.sessionId ?? undefined,
     jobName: span.jobName ?? undefined,
+    principalId: span.principalId ?? undefined,
     startedAt: span.startedAt,
     waitUntil: span.waitUntil ?? undefined,
     endedAt: span.endedAt ?? undefined,
@@ -122,6 +123,9 @@ export function toWireRollup(r: RunRollupRow): ActivityRunRollup {
     name: r.name,
     sessionId: r.sessionId,
     jobName: r.jobName,
+    principalId: r.principalId,
+    principalLabel: r.principalLabel,
+    principalKind: r.principalKind,
     startedAt: r.startedAt,
     endedAt: r.endedAt,
     outcome: r.outcome,
@@ -136,10 +140,12 @@ export function toWireRollup(r: RunRollupRow): ActivityRunRollup {
 }
 
 export interface ActivityStream {
-  handleSubscribe(ws: WSContext, msg: ClientActivitySubscribe): void;
+  handleSubscribe(ws: WSContext, msg: ClientActivitySubscribe, principalId: string): void;
   handleUnsubscribe(ws: WSContext, msg: ClientActivityUnsubscribe): void;
   /** Forget a closed socket. */
   dropConnection(ws: WSContext): void;
+  /** Forget every subscription attached by one revoked principal. */
+  dropFor(principalId: string): void;
   /** Drain new committed changes to subscribers. Reentrancy-safe. */
   pump(): void;
   /** Whether any connection currently watches the given session's activity. */
@@ -150,7 +156,10 @@ export interface ActivityStream {
 }
 
 export function createActivityStream(store: ActivityStore, log?: Logger): ActivityStream {
-  const subscriptions = new Map<WSContext, Subscription[]>();
+  const subscriptions = new Map<
+    unknown,
+    { ws: WSContext; principalId: string; subscriptions: Subscription[] }
+  >();
   let cursor = store.latestChangeCursor();
   let pumping = false;
   let pollHandle: ReturnType<typeof setInterval> | null = null;
@@ -222,9 +231,9 @@ export function createActivityStream(store: ActivityStore, log?: Logger): Activi
           const span = change.kind === "span" ? change.span : undefined;
           if (span) noteSpan(span);
           const frame = deltaFrame(change);
-          for (const [ws, subs] of subscriptions) {
-            if (subs.some((s) => matches(s, change.runId, span))) {
-              sendTo(ws, frame);
+          for (const entry of subscriptions.values()) {
+            if (entry.subscriptions.some((s) => matches(s, change.runId, span))) {
+              sendTo(entry.ws, frame);
             }
           }
         }
@@ -310,7 +319,7 @@ export function createActivityStream(store: ActivityStore, log?: Logger): Activi
   }
 
   return {
-    handleSubscribe(ws, msg) {
+    handleSubscribe(ws, msg, principalId) {
       // A scoped view without its scope id can never match anything and
       // would only leak an all-runs snapshot shape — ignore it up front.
       if ((msg.view === "session" && !msg.sessionId) || (msg.view === "run" && !msg.runId)) {
@@ -321,9 +330,11 @@ export function createActivityStream(store: ActivityStore, log?: Logger): Activi
         ...(msg.sessionId ? { sessionId: msg.sessionId } : {}),
         ...(msg.runId ? { runId: msg.runId } : {}),
       };
-      const list = subscriptions.get(ws) ?? [];
+      const identity = ws.raw ?? ws;
+      const existing = subscriptions.get(identity);
+      const list = existing?.subscriptions ?? [];
       if (!list.some((s) => subKey(s) === subKey(sub))) list.push(sub);
-      subscriptions.set(ws, list);
+      subscriptions.set(identity, { ws, principalId, subscriptions: list });
       ensurePolling();
       try {
         sendSnapshot(ws, sub);
@@ -337,29 +348,38 @@ export function createActivityStream(store: ActivityStore, log?: Logger): Activi
     },
 
     handleUnsubscribe(ws, msg) {
-      const list = subscriptions.get(ws);
-      if (!list) return;
+      const identity = ws.raw ?? ws;
+      const entry = subscriptions.get(identity);
+      if (!entry) return;
       const key = subKey({
         view: msg.view,
         ...(msg.sessionId ? { sessionId: msg.sessionId } : {}),
         ...(msg.runId ? { runId: msg.runId } : {}),
       });
-      const remaining = list.filter((s) => subKey(s) !== key);
-      if (remaining.length > 0) subscriptions.set(ws, remaining);
-      else subscriptions.delete(ws);
+      const remaining = entry.subscriptions.filter((s) => subKey(s) !== key);
+      if (remaining.length > 0) {
+        subscriptions.set(identity, { ...entry, ws, subscriptions: remaining });
+      } else subscriptions.delete(identity);
       stopPollingIfIdle();
     },
 
     dropConnection(ws) {
-      subscriptions.delete(ws);
+      subscriptions.delete(ws.raw ?? ws);
+      stopPollingIfIdle();
+    },
+
+    dropFor(principalId) {
+      for (const [identity, entry] of subscriptions) {
+        if (entry.principalId === principalId) subscriptions.delete(identity);
+      }
       stopPollingIfIdle();
     },
 
     pump,
 
     isWatched(scope) {
-      for (const subs of subscriptions.values()) {
-        for (const s of subs) {
+      for (const entry of subscriptions.values()) {
+        for (const s of entry.subscriptions) {
           if (s.view === "index") return true;
           if (scope.runId && s.view === "run" && s.runId === scope.runId) return true;
           if (scope.sessionId && s.view === "session" && s.sessionId === scope.sessionId)
@@ -371,7 +391,7 @@ export function createActivityStream(store: ActivityStore, log?: Logger): Activi
 
     subscriptionCount() {
       let n = 0;
-      for (const subs of subscriptions.values()) n += subs.length;
+      for (const entry of subscriptions.values()) n += entry.subscriptions.length;
       return n;
     },
 

package/src/app-env.ts

@@ -0,0 +1,8 @@
+import type { Principal } from "./db/principals.js";
+
+/** Request-scoped values populated by the authentication boundary. */
+export type AppEnv = {
+  Variables: {
+    principal?: Principal;
+  };
+};

package/src/app.ts

@@ -35,7 +35,9 @@ import {
   assertPasskeyConfig,
   type PasskeyContext,
 } from "./middleware/passkeys.js";
+import { principalManagementRoutes } from "./middleware/principals.js";
 import { createUiDb } from "./db/client.js";
+import { isUsablePrincipal, prunePrincipals, resolvePrincipal } from "./db/principals.js";
 import {
   getAutoAllowedTools,
   getBillingOverrides,
@@ -61,6 +63,7 @@ import { createSessionCatalog } from "./ws/session-catalog.js";
 import type { KeytermSettings } from "./voice/keyterm-builder.js";
 import { createObservability, type Observability } from "./observability/index.js";
 import { isSameOriginRequest, originPolicy } from "./middleware/origin.js";
+import type { AppEnv } from "./app-env.js";
 
 export type { AppRenderer };
 
@@ -160,7 +163,7 @@ export function createApp(options: CreateAppOptions = {}): BrainUiApp {
     options.observability ?? createObservability({ minSeverity: config.logLevel });
   const auth: AuthRuntime = { ...config.auth, host: config.host };
 
-  const app = new Hono();
+  const app = new Hono<AppEnv>();
   const authLog = observability.logger("auth");
   const authMode = resolveAuthMode(auth, authLog);
   // Validate inside the factory, not the bin entry: every consumer of the app
@@ -181,6 +184,7 @@ export function createApp(options: CreateAppOptions = {}): BrainUiApp {
   probeBrainCliVersion(config.brainPath, observability.logger("brain"));
   const dbLog = observability.logger("db");
   const db = createUiDb(config.dbPath, { log: dbLog });
+  prunePrincipals(db, Date.now());
   const brain = createBrainClient({ brainPath: config.brainPath });
   const cron = createCronScheduler({ db, brain, log: observability.logger("cron") });
 
@@ -225,6 +229,10 @@ export function createApp(options: CreateAppOptions = {}): BrainUiApp {
     maxConcurrentSessions: () => config.maxConcurrentSessions,
     wsRate: config.wsRate,
     wsMaxConnections: config.wsMaxConnections,
+    isPrincipalValid: (principal) => {
+      const current = resolvePrincipal(db, principal.id);
+      return current !== null && isUsablePrincipal(current, Date.now());
+    },
     toolPermissions: {
       isAutoAllowed: (toolName) => getAutoAllowedTools(db, dbLog).includes(toolName),
       add: (toolName) =>
@@ -233,6 +241,7 @@ export function createApp(options: CreateAppOptions = {}): BrainUiApp {
     activity: {
       store: activity.store,
       stream: activity.stream,
+      pushSender: activity.pushSender,
       query: activity.query,
     },
   });
@@ -244,7 +253,7 @@ export function createApp(options: CreateAppOptions = {}): BrainUiApp {
   });
   const passkeyCtx: PasskeyContext = {
     db,
-    clients: host.clients,
+    revoker: host,
     webauthn: config.webauthn,
     auth,
     allowedOrigins: config.allowedOrigins,
@@ -268,6 +277,7 @@ export function createApp(options: CreateAppOptions = {}): BrainUiApp {
     if (c.req.path === "/api/health") return next();
     const startedAt = Date.now();
     await next();
+    const principal = c.get("principal");
     httpLog.emit({
       severityText: "INFO",
       body: "request",
@@ -276,6 +286,12 @@ export function createApp(options: CreateAppOptions = {}): BrainUiApp {
         path: c.req.path,
         status: c.res.status,
         "duration.ms": Date.now() - startedAt,
+        ...(principal
+          ? {
+              "auth.principal.id": principal.id,
+              "auth.principal.label": principal.label,
+            }
+          : {}),
       },
     });
   });
@@ -335,7 +351,7 @@ export function createApp(options: CreateAppOptions = {}): BrainUiApp {
     "/api",
     authRoutes(authMode, auth, {
       db,
-      clients: host.clients,
+      revoker: host,
       passwordDisabled: (c) => passwordLoginDisabled(c, passkeyCtx),
       log: authLog,
       failures: authFailures,
@@ -351,6 +367,16 @@ export function createApp(options: CreateAppOptions = {}): BrainUiApp {
   // Passkey registration/management: after the guard, so a session is required
   // by mount position (the public assertion routes are registered above).
   app.route("/api", passkeyManagementRoutes(authMode, passkeyCtx));
+  // Principal management: also after the guard. Its router adds the narrower
+  // owner-only check after authentication has resolved the caller principal.
+  app.route(
+    "/api",
+    principalManagementRoutes(authMode, auth, {
+      db,
+      revoker: host,
+      log: authLog,
+    })
+  );
   app.route(
     "/api",
     createStatusRoutes({
@@ -414,9 +440,11 @@ export function createApp(options: CreateAppOptions = {}): BrainUiApp {
     if (!isSameOriginRequest(c, allowedOrigins, auth.trustProxy)) {
       return c.json({ error: "Cross-origin WebSocket rejected" }, 403);
     }
-    if (!(await isWsAuthorized(c, authMode, auth, db))) {
+    const principal = await isWsAuthorized(c, authMode, auth, db);
+    if (!principal) {
       return c.json({ error: "Authentication required" }, 401);
     }
+    c.set("principal", principal);
     if (!host.clients.hasCapacity()) {
       host.reportRefusedConnection();
       return c.text("WebSocket connection limit reached", 503);
@@ -462,6 +490,7 @@ export function createApp(options: CreateAppOptions = {}): BrainUiApp {
     isTurnActive: () => host.coordinator.isTurnActive(),
     cancelActiveTurns: () => host.coordinator.cancelAll("Server shutting down"),
     close: () => {
+      host.close();
       activity.close();
       db.close();
     },

package/src/brain/client.ts

@@ -8,6 +8,7 @@ import type {
   BrainDocument,
   BrainStats,
   BrainSyncResult,
+  BrainAddResult,
 } from "./types.js";
 
 /**
@@ -20,7 +21,7 @@ export interface BrainClient {
   cliCommand(): string[];
   search(
     query: string,
-    opts?: { type?: string; tag?: string; limit?: number; mode?: string }
+    opts?: { type?: string; tag?: string; limit?: number; mode?: string; signal?: AbortSignal }
   ): Promise<BrainSearchResponse>;
   briefing(): Promise<string>;
   stats(): Promise<BrainStats>;
@@ -36,7 +37,7 @@ export interface BrainClient {
   add(
     content: string,
     opts?: { type?: string; title?: string; tags?: string[] }
-  ): Promise<void>;
+  ): Promise<BrainAddResult>;
   index(opts?: { force?: boolean }): Promise<void>;
   validate(): Promise<string>;
   /** Run `brain skills sync` — re-materialize every agent's skill links. */
@@ -157,25 +158,46 @@ export function probeBrainCliVersion(brainPath: string, log: Logger): void {
   }
 }
 
-export function createBrainClient(opts: { brainPath: string }): BrainClient {
+/** Interactive search must finish or fail within a bounded time. */
+const SEARCH_TIMEOUT_MS = 15_000;
+
+export function createBrainClient(opts: { brainPath: string; searchTimeoutMs?: number }): BrainClient {
   const { brainPath } = opts;
+  const searchTimeoutMs = opts.searchTimeoutMs ?? SEARCH_TIMEOUT_MS;
+  if (!Number.isFinite(searchTimeoutMs) || searchTimeoutMs <= 0) {
+    throw new Error("searchTimeoutMs must be a positive finite number");
+  }
 
-  async function execBrain(args: string[]): Promise<ExecResult> {
+  async function execBrain(args: string[], signal?: AbortSignal): Promise<ExecResult> {
+    signal?.throwIfAborted();
     const proc = Bun.spawn([...brainCliCommand(brainPath), ...args], {
       cwd: brainPath,
       stdout: "pipe",
       stderr: "pipe",
       // Force JSON output when not a TTY
       env: subprocessEnv("brainCli", { NO_COLOR: "1" }),
+      // Only read-only search passes a signal. Kill even a CLI that ignores
+      // SIGTERM; abandoning a request must not leave the local process alive.
+      ...(signal ? { signal, killSignal: "SIGKILL" } : {}),
     });
 
-    const [stdout, stderr] = await Promise.all([
-      new Response(proc.stdout).text(),
-      new Response(proc.stderr).text(),
-    ]);
-    const exitCode = await proc.exited;
-
-    return { stdout, stderr, exitCode };
+    try {
+      const [stdout, stderr, exitCode] = await Promise.all([
+        new Response(proc.stdout).text(),
+        new Response(proc.stderr).text(),
+        proc.exited,
+      ]);
+      signal?.throwIfAborted();
+      return { stdout, stderr, exitCode };
+    } catch (error) {
+      // A pipe-read failure also abandons search. Reap before its caller
+      // clears the deadline; otherwise that failure could orphan the child.
+      if (signal) {
+        proc.kill("SIGKILL");
+        await proc.exited;
+      }
+      throw error;
+    }
   }
 
   function parseJsonOutput<T>(result: ExecResult): T {
@@ -197,18 +219,29 @@ export function createBrainClient(opts: { brainPath: string }): BrainClient {
       return brainCliCommand(brainPath);
     },
 
-    async search(query, opts) {
+    async search(query, searchOpts) {
       const args = ["search"];
-      if (opts?.type) args.push("--type", opts.type);
-      if (opts?.tag) args.push("--tag", opts.tag);
-      if (opts?.limit) args.push("--limit", String(opts.limit));
-      if (opts?.mode) args.push("--mode", opts.mode);
+      if (searchOpts?.type) args.push("--type", searchOpts.type);
+      if (searchOpts?.tag) args.push("--tag", searchOpts.tag);
+      if (searchOpts?.limit) args.push("--limit", String(searchOpts.limit));
+      if (searchOpts?.mode) args.push("--mode", searchOpts.mode);
       args.push("--", query);
 
-      const result = await execBrain(args);
-      const parsed = parseJsonOutput<BrainSearchResponse | BrainSearchResult[]>(result);
-      // brain returns {results, warnings} since 22e82e1; tolerate the old bare array
-      return Array.isArray(parsed) ? { results: parsed, warnings: [] } : parsed;
+      const deadline = new AbortController();
+      const timer = setTimeout(() => deadline.abort(
+        new DOMException("Search timed out. Please try again.", "TimeoutError")
+      ), searchTimeoutMs);
+      const signal = searchOpts?.signal
+        ? AbortSignal.any([searchOpts.signal, deadline.signal])
+        : deadline.signal;
+      try {
+        const result = await execBrain(args, signal);
+        const parsed = parseJsonOutput<BrainSearchResponse | BrainSearchResult[]>(result);
+        // brain returns {results, warnings} since 22e82e1; tolerate the old bare array
+        return Array.isArray(parsed) ? { results: parsed, warnings: [] } : parsed;
+      } finally {
+        clearTimeout(timer);
+      }
     },
 
     async briefing() {
@@ -279,6 +312,14 @@ export function createBrainClient(opts: { brainPath: string }): BrainClient {
       if (result.exitCode !== 0) {
         throw new Error(`brain add failed: ${result.stderr}`);
       }
+      const parsed = parseJsonOutput<BrainAddResult>(result);
+      if (!parsed || typeof parsed !== "object" || typeof parsed.path !== "string" ||
+          typeof parsed.indexed !== "boolean" || typeof parsed.title !== "string" ||
+          typeof parsed.type !== "string" || (parsed.indexError !== undefined && typeof parsed.indexError !== "string") ||
+          !["created", "appended"].includes(parsed.action)) {
+        throw new Error("Capture completed but its outcome could not be read. Check your files before adding it again.");
+      }
+      return parsed;
     },
 
     async index(opts) {