aisnitch 0.2.19 → 0.2.21

package/dist/index.d.ts

@@ -68,6 +68,8 @@ declare const ConfigSchema: z.ZodObject<{
         kiro: "kiro";
         "augment-code": "augment-code";
         mistral: "mistral";
+        zed: "zed";
+        pi: "pi";
         unknown: "unknown";
     }> & z.core.$partial, z.ZodObject<{
         enabled: z.ZodDefault<z.ZodBoolean>;
@@ -106,7 +108,7 @@ type AISnitchConfig = infer<typeof ConfigSchema>;
  * @description Runtime Zod schemas and constants for the AISnitch CloudEvents-based event contract.
  * @functions
  *   → createUuidV7
- * @exports AISNITCH_EVENT_TYPES, TOOL_NAMES, ERROR_TYPES, CESP_CATEGORIES, ToolInputSchema, EventDataSchema, AISnitchEventTypeSchema, ToolNameSchema, ErrorTypeSchema, CESPCategorySchema, AISnitchEventSchema, createUuidV7
+ * @exports AISNITCH_EVENT_TYPES, TOOL_NAMES, ERROR_TYPES, CESP_CATEGORIES, ToolInputSchema, ToolCallNameSchema, ThinkingContentSchema, FinalMessageSchema, ToolResultSchema, MessageContentSchema, EventDataSchema, AISnitchEventTypeSchema, ToolNameSchema, ErrorTypeSchema, CESPCategorySchema, AISnitchEventSchema, createUuidV7
  * @see ./types.ts
  * @see ./cesp.ts
  * @see ./factory.ts
@@ -119,7 +121,7 @@ declare const AISNITCH_EVENT_TYPES: readonly ["session.start", "session.end", "t
 /**
  * Supported AI tool identifiers recognized by AISnitch.
  */
-declare const TOOL_NAMES: readonly ["claude-code", "opencode", "gemini-cli", "codex", "goose", "copilot-cli", "cursor", "aider", "amp", "cline", "continue", "windsurf", "qwen-code", "openclaw", "openhands", "kilo", "devin", "kiro", "augment-code", "mistral", "unknown"];
+declare const TOOL_NAMES: readonly ["claude-code", "opencode", "gemini-cli", "codex", "goose", "copilot-cli", "cursor", "aider", "amp", "cline", "continue", "windsurf", "qwen-code", "openclaw", "openhands", "kilo", "devin", "kiro", "augment-code", "mistral", "zed", "pi", "unknown"];
 /**
  * Normalized error categories attached to `agent.error` events.
  */
@@ -139,6 +141,34 @@ declare const ToolInputSchema: z.ZodObject<{
     filePath: z.ZodOptional<z.ZodString>;
     command: z.ZodOptional<z.ZodString>;
 }, z.core.$strict>;
+/**
+ * 📖 Thinking content extracted from AI model reasoning chains.
+ * This field captures the internal "thinking" or reasoning output that
+ * models like Claude produce before generating their final response.
+ */
+declare const ThinkingContentSchema: z.ZodString;
+/**
+ * 📖 Tool call name — the specific tool being invoked.
+ * Examples: "Edit", "Bash", "Grep", "Read", "Write", "WebSearch"
+ * Different from `toolInput` which contains the tool's parameters.
+ */
+declare const ToolCallNameSchema: z.ZodString;
+/**
+ * 📖 Final message shown at the end of an AI run.
+ * This is typically a summary, completion message, or result text
+ * displayed to the user after the agent finishes its work.
+ */
+declare const FinalMessageSchema: z.ZodString;
+/**
+ * 📖 Tool execution result — short result from a tool call.
+ * Can include success messages, error messages, or short outputs.
+ */
+declare const ToolResultSchema: z.ZodString;
+/**
+ * 📖 Raw message content from AI responses.
+ * Captures the actual text generated by the model before tool calls.
+ */
+declare const MessageContentSchema: z.ZodString;
 /**
  * Runtime schema for the supported tool names.
  */
@@ -163,6 +193,8 @@ declare const ToolNameSchema: z.ZodEnum<{
     kiro: "kiro";
     "augment-code": "augment-code";
     mistral: "mistral";
+    zed: "zed";
+    pi: "pi";
     unknown: "unknown";
 }>;
 /**
@@ -248,6 +280,11 @@ declare const EventDataSchema: z.ZodObject<{
     instanceId: z.ZodOptional<z.ZodString>;
     instanceIndex: z.ZodOptional<z.ZodNumber>;
     instanceTotal: z.ZodOptional<z.ZodNumber>;
+    thinkingContent: z.ZodOptional<z.ZodString>;
+    toolCallName: z.ZodOptional<z.ZodString>;
+    finalMessage: z.ZodOptional<z.ZodString>;
+    toolResult: z.ZodOptional<z.ZodString>;
+    messageContent: z.ZodOptional<z.ZodString>;
 }, z.core.$strict>;
 /**
  * Runtime schema for the full normalized AISnitch event envelope.
@@ -292,6 +329,8 @@ declare const AISnitchEventSchema: z.ZodObject<{
         kiro: "kiro";
         "augment-code": "augment-code";
         mistral: "mistral";
+        zed: "zed";
+        pi: "pi";
         unknown: "unknown";
     }>;
     'aisnitch.sessionid': z.ZodString;
@@ -336,6 +375,11 @@ declare const AISnitchEventSchema: z.ZodObject<{
         instanceId: z.ZodOptional<z.ZodString>;
         instanceIndex: z.ZodOptional<z.ZodNumber>;
         instanceTotal: z.ZodOptional<z.ZodNumber>;
+        thinkingContent: z.ZodOptional<z.ZodString>;
+        toolCallName: z.ZodOptional<z.ZodString>;
+        finalMessage: z.ZodOptional<z.ZodString>;
+        toolResult: z.ZodOptional<z.ZodString>;
+        messageContent: z.ZodOptional<z.ZodString>;
     }, z.core.$strict>;
 }, z.core.$strict>;
 
@@ -440,6 +484,11 @@ declare const NormalizedAdapterHookPayloadSchema: z.ZodObject<{
         instanceId: z.ZodOptional<z.ZodOptional<z.ZodString>>;
         instanceIndex: z.ZodOptional<z.ZodOptional<z.ZodNumber>>;
         instanceTotal: z.ZodOptional<z.ZodOptional<z.ZodNumber>>;
+        thinkingContent: z.ZodOptional<z.ZodOptional<z.ZodString>>;
+        toolCallName: z.ZodOptional<z.ZodOptional<z.ZodString>>;
+        finalMessage: z.ZodOptional<z.ZodOptional<z.ZodString>>;
+        toolResult: z.ZodOptional<z.ZodOptional<z.ZodString>>;
+        messageContent: z.ZodOptional<z.ZodOptional<z.ZodString>>;
     }, z.core.$strict>>;
     pid: z.ZodOptional<z.ZodNumber>;
     transcriptPath: z.ZodOptional<z.ZodString>;
@@ -1036,6 +1085,91 @@ declare class OpenCodeAdapter extends BaseAdapter {
     private pollOpenCodeProcesses;
 }
 
+/**
+ * @file src/adapters/pi.ts
+ * @description Pi AI Agent adapter using Pi's local API and log monitoring.
+ * @functions
+ *   → detectPiInstance
+ * @exports PiAdapter
+ * @see ./base.ts
+ * @see ../core/events/types.ts
+ */
+
+/**
+ * 📖 Pi is a coding agent by MiniMax. This adapter detects Pi activity through:
+ * 1. Process detection (pgrep for pi processes)
+ * 2. MiniMax API / local socket detection
+ * 3. Log file monitoring
+ */
+declare class PiAdapter extends BaseAdapter {
+    readonly displayName = "Pi (MiniMax)";
+    readonly name: "pi";
+    readonly strategies: readonly InterceptionStrategy[];
+    private readonly apiPort;
+    private readonly logPath;
+    private poller;
+    private activePiSessions;
+    private lastCheckedTime;
+    constructor(options: AdapterRuntimeOptions);
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    handleHook(payload: unknown): Promise<void>;
+    private startPolling;
+    private pollPiActivity;
+    private detectPiInstance;
+    private checkMiniMaxApi;
+    private processPiApiResponse;
+    private emitSessionStart;
+    private emitThinking;
+    private emitToolCall;
+    private emitOutput;
+    private emitError;
+    private emitIdle;
+    private mapEventType;
+    private buildEventData;
+}
+
+/**
+ * @file src/adapters/zed.ts
+ * @description Zed AI Agent adapter using log file monitoring and IPC detection.
+ * @functions
+ *   → extractZedEventFromLog
+ * @exports ZedAdapter
+ * @see ./base.ts
+ * @see ../core/events/types.ts
+ */
+
+/**
+ * 📖 Zed Agent (zed.dev) exposes a local HTTP API on port 9876 for its agent.
+ * This adapter polls that endpoint and watches Zed's log file for activity.
+ */
+declare class ZedAdapter extends BaseAdapter {
+    readonly displayName = "Zed AI";
+    readonly name: "zed";
+    readonly strategies: readonly InterceptionStrategy[];
+    private readonly logPaths;
+    private readonly apiPort;
+    private readonly pollIntervalMs;
+    private poller;
+    private lastEventTime;
+    private activeZedSessions;
+    constructor(options: AdapterRuntimeOptions);
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    handleHook(payload: unknown): Promise<void>;
+    private startPolling;
+    private pollZedStatus;
+    private checkLogFiles;
+    private parseLogContent;
+    private extractZedEventFromLog;
+    private emitSessionStart;
+    private emitThinking;
+    private emitToolCall;
+    private emitIdle;
+    private mapEventType;
+    private buildEventData;
+}
+
 /**
  * @file src/adapters/registry.ts
  * @description Adapter registry that owns built-in adapter instances and orchestrates their lifecycle.
@@ -1164,12 +1298,402 @@ declare function analyzeTerminalOutputChunk(input: {
  * @see ./codex.ts
  * @see ./openclaw.ts
  * @see ./opencode.ts
+ * @see ./pi.ts
+ * @see ./zed.ts
  */
 
 /**
  * Instantiates the built-in adapters that ship with AISnitch.
  */
-declare function createDefaultAdapters(options: AdapterRuntimeOptions): readonly [AiderAdapter, ClaudeCodeAdapter, CopilotCLIAdapter, CursorAdapter, DevinAdapter, GeminiCLIAdapter, GooseAdapter, KiloAdapter, CodexAdapter, OpenClawAdapter, OpenCodeAdapter];
+declare function createDefaultAdapters(options: AdapterRuntimeOptions): readonly [AiderAdapter, ClaudeCodeAdapter, CopilotCLIAdapter, CursorAdapter, DevinAdapter, GeminiCLIAdapter, GooseAdapter, KiloAdapter, CodexAdapter, OpenClawAdapter, OpenCodeAdapter, PiAdapter, ZedAdapter];
+
+/**
+ * @file src/core/errors.ts
+ * @description Centralized error hierarchy for AISnitch with typed error codes and context.
+ *
+ * This module provides a consistent error taxonomy across the entire application:
+ * - `AISnitchError` — base class for all AISnitch-specific errors
+ * - `AdapterError` — adapter lifecycle, parsing, or emission failures
+ * - `PipelineError` — pipeline orchestration, component startup, or shutdown failures
+ * - `ValidationError` — Zod parsing failures and schema violations
+ * - `NetworkError` — HTTP, WebSocket, or Unix Domain Socket failures
+ * - `TimeoutError` — async operations that exceed their deadline
+ *
+ * Each error carries a machine-readable `code` field for programmatic handling
+ * and an optional `context` bag for debugging. Errors serialize cleanly to JSON
+ * so they can be logged via pino without losing structure.
+ *
+ * @functions
+ *   → none
+ * @exports AISnitchError, AdapterError, PipelineError, ValidationError, NetworkError, TimeoutError, isAISnitchError, isRetryableError
+ * @see ./result.ts
+ * @see ./retry.ts
+ * @see ./timeout.ts
+ */
+/**
+ * Base class for all AISnitch-specific errors.
+ *
+ * @example
+ * ```typescript
+ * throw new AISnitchError(
+ *   'Event validation failed',
+ *   'EVENT_VALIDATION_ERROR',
+ *   { eventId: event.id, issues: parseResult.error.issues }
+ * );
+ * ```
+ */
+declare class AISnitchError extends Error {
+    /**
+     * Machine-readable error code for programmatic handling.
+     * Format: `SUBCATEGORY_SPECIFIC_DETAIL` (uppercase with underscores).
+     */
+    readonly code: string;
+    /**
+     * Arbitrary context bag forwarded to the logger for structured debugging.
+     */
+    readonly context?: Readonly<Record<string, unknown>>;
+    constructor(message: string, code: string, context?: Readonly<Record<string, unknown>>);
+    /**
+     * Full error chain for logging: `[name] code — message`.
+     */
+    toString(): string;
+    /**
+     * JSON serialization friendly to pino serializers.
+     */
+    toJSON(): object;
+}
+/**
+ * Errors originating from adapter lifecycle, payload parsing, or event emission.
+ *
+ * @example
+ * ```typescript
+ * throw new AdapterError(
+ *   'Claude Code transcript read failed',
+ *   'ADAPTER_CLAUDE_CODE_FILE_ERROR',
+ *   { filePath: transcriptPath, cause: error }
+ * );
+ * ```
+ */
+declare class AdapterError extends AISnitchError {
+    constructor(message: string, code: string, context?: Readonly<Record<string, unknown>>);
+    /**
+     * Factory for adapter-specific errors with auto-generated codes.
+     */
+    static withAutoCode(message: string, tool: string, context?: Readonly<Record<string, unknown>>): AdapterError;
+}
+/**
+ * Errors originating from pipeline orchestration, component startup, or shutdown.
+ *
+ * @example
+ * ```typescript
+ * throw new PipelineError(
+ *   'Failed to start WebSocket server',
+ *   'PIPELINE_WS_START_FAILED',
+ *   { port: configuredPort, cause: error }
+ * );
+ * ```
+ */
+declare class PipelineError extends AISnitchError {
+    constructor(message: string, code: string, context?: Readonly<Record<string, unknown>>);
+}
+/**
+ * Errors from Zod schema parsing failures and data validation violations.
+ *
+ * @example
+ * ```typescript
+ * const result = EventDataSchema.safeParse(rawPayload);
+ * if (!result.success) {
+ *   throw new ValidationError(
+ *     'Invalid event data payload',
+ *     'VALIDATION_EVENT_DATA_INVALID',
+ *     { issues: result.error.issues }
+ *   );
+ * }
+ * ```
+ */
+declare class ValidationError extends AISnitchError {
+    constructor(message: string, code: string, context?: Readonly<Record<string, unknown>>);
+}
+/**
+ * Errors from network operations: HTTP requests, WebSocket connections, UDS.
+ *
+ * @example
+ * ```typescript
+ * throw new NetworkError(
+ *   'Health endpoint unreachable',
+ *   'NETWORK_HTTP_CONNECT_FAILED',
+ *   { host: '127.0.0.1', port: 4821, cause: error }
+ * );
+ * ```
+ */
+declare class NetworkError extends AISnitchError {
+    constructor(message: string, code: string, context?: Readonly<Record<string, unknown>>);
+}
+/**
+ * Errors from async operations that exceed their configured deadline.
+ *
+ * @example
+ * ```typescript
+ * throw new TimeoutError(
+ *   'Adapter stop timed out after 5 seconds',
+ *   'TIMEOUT_SHUTDOWN',
+ *   { component: 'ClaudeCodeAdapter', timeoutMs: 5_000 }
+ * );
+ * ```
+ */
+declare class TimeoutError extends AISnitchError {
+    constructor(message: string, code: string, context?: Readonly<Record<string, unknown>>);
+}
+/**
+ * Type guard to narrow any `unknown` error to an AISnitch error.
+ *
+ * @example
+ * ```typescript
+ * } catch (error: unknown) {
+ *   if (isAISnitchError(error)) {
+ *     console.error(`AISnitch error ${error.code}: ${error.message}`);
+ *   } else {
+ *     console.error('Unexpected error', error);
+ *   }
+ * }
+ * ```
+ */
+declare function isAISnitchError(error: unknown): error is AISnitchError;
+/**
+ * Determines whether an error is safe to retry (transient vs. permanent).
+ *
+ * Returns `true` for network timeouts, connection reset, and rate-limit errors.
+ * Returns `false` for validation errors, authentication failures, and programming bugs.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   return await operation();
+ * } catch (error: unknown) {
+ *   if (isRetryableError(error)) {
+ *     throw error; // let retry logic handle it
+ *   }
+ *   throw error; // propagate as-is (non-retryable)
+ * }
+ * ```
+ */
+declare function isRetryableError(error: unknown): boolean;
+
+/**
+ * @file src/core/circuit-breaker.ts
+ * @description Circuit breaker pattern implementation for resilient adapter operation.
+ *
+ * The circuit breaker prevents cascading failures when an adapter repeatedly fails:
+ *
+ * ```
+ *  CLOSED (normal) ──[N failures]──→ OPEN (failing fast)
+ *       ↑                              │
+ *       │                         [half-open after timeout]
+ *       │                              ↓
+ *       └──────[success]──── HALF-OPEN (testing recovery)
+ * ```
+ *
+ * When an adapter fails `threshold` times within `windowMs`, the breaker opens:
+ * - Subsequent calls fail immediately with `CircuitOpenError` (no network round-trips)
+ * - After `halfOpenAfterMs`, one test call is allowed to check recovery
+ * - If it succeeds → close the circuit (back to normal operation)
+ * - If it fails → reopen and wait again
+ *
+ * ## When to use this
+ *
+ * - Adapter `emit()` calls that can fail repeatedly (file system errors, hook timeouts)
+ * - Network operations with unreliable backends
+ * - Any operation where persistent failure is worse than temporary unavailability
+ *
+ * ## When NOT to use this
+ *
+ * - One-off errors that are unlikely to repeat
+ * - Validation failures (these indicate a programming bug, not a transient fault)
+ * - Operations that are already idempotent with built-in retry (prefer `withRetry`)
+ *
+ * @functions
+ *   → none
+ * @exports CircuitState, CircuitOpenError, CircuitBreaker
+ * @see ./errors.ts
+ * @see ./retry.ts
+ * @see ./timeout.ts
+ */
+
+/**
+ * Observable state of a circuit breaker.
+ */
+interface CircuitState {
+    /**
+     * Number of consecutive failures since last success.
+     */
+    readonly failures: number;
+    /**
+     * Timestamp of the last failure (ms since epoch), or null if never failed.
+     */
+    readonly lastFailureAt: number | null;
+    /**
+     * Current state of the circuit.
+     * - `closed`: Normal operation, requests pass through
+     * - `open`: Failing fast, requests are rejected immediately
+     * - `half-open`: Testing recovery, one request is allowed through
+     */
+    readonly state: 'closed' | 'open' | 'half-open';
+}
+/**
+ * Error thrown when a circuit is open and the operation is rejected.
+ */
+declare class CircuitOpenError extends AISnitchError {
+    readonly circuitId: string;
+    readonly state: CircuitState;
+    constructor(circuitId: string, state: CircuitState);
+    toString(): string;
+}
+/**
+ * Configuration for a circuit breaker instance.
+ */
+interface CircuitBreakerOptions {
+    /**
+     * Number of consecutive failures before opening the circuit.
+     * @default 5
+     */
+    readonly failureThreshold?: number;
+    /**
+     * Time window in milliseconds to count failures within.
+     * @default 60_000 (1 minute)
+     */
+    readonly windowMs?: number;
+    /**
+     * Time to wait before transitioning from OPEN to HALF-OPEN.
+     * @default 30_000 (30 seconds)
+     */
+    readonly halfOpenAfterMs?: number;
+    /**
+     * Human-readable identifier for this circuit (shown in logs).
+     * @default 'unnamed'
+     */
+    readonly id?: string;
+    /**
+     * Optional predicate to decide which errors count toward the threshold.
+     * Return `true` to count as a failure, `false` to ignore (success-like failure).
+     * @default isRetryableError
+     */
+    readonly shouldCountAsFailure?: (error: unknown) => boolean;
+    /**
+     * Set to `true` to reset the failure counter after any success in CLOSED state.
+     * Set to `false` to only reset after `failureThreshold` successes.
+     * @default true
+     */
+    readonly resetOnSuccess?: boolean;
+}
+/**
+ * Circuit breaker state machine.
+ *
+ * ## State transitions
+ *
+ * ```
+ * CLOSED ──[failure + threshold reached]──→ OPEN
+ *   ▲                                      │
+ *   │                                [halfOpenAfterMs elapsed]
+ *   │                                      ↓
+ *   │                                HALF-OPEN
+ *   │                                      │
+ *   │                         [test call succeeds]
+ *   │                                      ↓
+ *   └────────────[reset]───────────────────┘
+ * ```
+ *
+ * ## Usage
+ *
+ * ```typescript
+ * const breaker = new CircuitBreaker({
+ *   id: 'claude-code.emit',
+ *   failureThreshold: 3,
+ *   windowMs: 60_000,
+ * });
+ *
+ * async function safeEmit(event: AISnitchEvent) {
+ *   return breaker.execute(() => adapter.emit(event));
+ * }
+ * ```
+ */
+declare class CircuitBreaker {
+    private failures;
+    private lastFailureAt;
+    private state;
+    private halfOpenTestStartedAt;
+    private readonly options;
+    constructor(options?: CircuitBreakerOptions);
+    /**
+     * Executes an async operation through the circuit breaker.
+     *
+     * - If the circuit is CLOSED → runs `fn` and updates state based on result
+     * - If the circuit is HALF-OPEN → runs `fn` once to test recovery
+     * - If the circuit is OPEN → throws `CircuitOpenError` immediately (no call)
+     *
+     * @param fn - The async operation to protect
+     * @returns The result of `fn` if successful
+     * @throws CircuitOpenError if the circuit is OPEN
+     * @throws The error from `fn` if it throws (and `shouldCountAsFailure` returns true)
+     */
+    execute<T>(fn: () => Promise<T>): Promise<T>;
+    /**
+     * Returns the current observable circuit state.
+     */
+    getState(): CircuitState;
+    /**
+     * Forces the circuit to CLOSED (resets failure count and state).
+     * Useful for manual recovery after a known-fix or after a maintenance window.
+     */
+    reset(): void;
+    /**
+     * Pre-warms the circuit by performing one test call in HALF-OPEN state.
+     * If the circuit is already HALF-OPEN, this does nothing.
+     * If the circuit is CLOSED, this does nothing.
+     */
+    preWarm(fn: () => Promise<void>): Promise<void>;
+    private executeClosed;
+    private executeHalfOpen;
+    private onSuccess;
+    private onFailure;
+    private transitionToOpen;
+    private transitionToHalfOpen;
+    private transitionToClosed;
+    private shouldTransitionToHalfOpen;
+}
+/**
+ * Shared circuit breaker instances for common AISnitch operations.
+ * These are module-level singletons to avoid creating new breakers on every call.
+ *
+ * Usage:
+ * ```typescript
+ * import { SHARED_BREAKERS } from './circuit-breaker.js';
+ *
+ * // Wrap an adapter emit call
+ * await SHARED_BREAKERS.adapterEmit.execute(() => adapter.emit(event));
+ * ```
+ */
+declare const SHARED_BREAKERS: Readonly<{
+    /**
+     * Breaker for adapter event emission.
+     * Threshold: 5 failures in 60s → open for 30s → half-open test.
+     */
+    adapterEmit: CircuitBreaker;
+    /**
+     * Breaker for file system operations (transcript reading, config loading).
+     * More tolerant: 10 failures in 60s → open for 30s.
+     */
+    fileSystem: CircuitBreaker;
+    /**
+     * Breaker for HTTP/HTTPS requests.
+     * Stricter: 3 failures in 30s → open for 15s.
+     */
+    httpRequest: CircuitBreaker;
+    /**
+     * Breaker for process detection operations.
+     * Most tolerant: 20 failures in 60s → open for 10s.
+     */
+    processDetection: CircuitBreaker;
+}>;
 
 /**
  * @file src/core/config/defaults.ts
@@ -1762,12 +2286,815 @@ declare class Pipeline {
      * Returns the in-process event bus for direct wiring in tests or future TUI code.
      */
     getEventBus(): EventBus;
+    /**
+     * Returns the adapter registry for graceful shutdown coordination.
+     */
+    getAdapterRegistry(): AdapterRegistry | undefined;
+    /**
+     * Returns the HTTP receiver for graceful shutdown coordination.
+     */
+    getHttpReceiver(): HTTPReceiver;
+    /**
+     * Returns the UDS server for graceful shutdown coordination.
+     */
+    getUdsServer(): UDSServer;
+    /**
+     * Returns the WebSocket server for graceful shutdown coordination.
+     */
+    getWsServer(): WSServer;
     private getHealthSnapshot;
     private handleHook;
     private handleHookInner;
     private isPlainRecord;
 }
 
+/**
+ * @file src/core/graceful-shutdown.ts
+ * @description Graceful shutdown coordination to prevent orphaned resources and partial state.
+ *
+ * Graceful shutdown is critical for a long-running daemon like AISnitch:
+ * - **No orphaned servers**: HTTP/WebSocket/UDS servers must be closed cleanly
+ * - **No resource leaks**: file watchers, pollers, timers must be stopped
+ * - **Clean PID files**: stale PID files confuse subsequent launches
+ * - **Clean state files**: daemon-state.json must be removed on exit
+ *
+ * This module provides:
+ * - `withShutdownTimeout()` — wrap a shutdown function with a deadline
+ * - `shutdownInOrder()` — stop components in reverse dependency order
+ * - `GracefulShutdownManager` — coordinates all shutdown signals (SIGTERM, SIGINT, SIGHUP)
+ *
+ * ## Shutdown order for AISnitch pipeline
+ *
+ * ```
+ * 1. adapters.stopAll()       — stop watching files, kill pollers, close watchers
+ * 2. httpReceiver.stop()      — close HTTP server
+ * 3. udsServer.stop()         — close Unix Domain Socket
+ * 4. wsServer.stop()          — close WebSocket server (consumers get disconnected)
+ * 5. eventBus.unsubscribeAll() — remove all listeners
+ * 6. cleanup PID/state files  — prevent stale state on next launch
+ * ```
+ *
+ * @functions
+ *   → withShutdownTimeout
+ *   → shutdownInOrder
+ * @exports GracefulShutdownManager, ShutdownComponents, withShutdownTimeout, shutdownInOrder
+ * @see ./errors.ts (TimeoutError)
+ * @see ./timeout.ts (DEFAULT_TIMEOUTS)
+ * @see ../cli/runtime.ts (shutdown orchestration)
+ */
+/**
+ * All AISnitch components that participate in graceful shutdown.
+ * Stopped in reverse dependency order (last-started = first-stopped).
+ */
+interface ShutdownComponents {
+    readonly adapterRegistry?: {
+        stopAll: () => Promise<void>;
+    };
+    readonly httpReceiver?: {
+        stop: () => Promise<void>;
+    };
+    readonly udsServer?: {
+        stop: () => Promise<void>;
+    };
+    readonly wsServer?: {
+        stop: () => Promise<void>;
+    };
+    readonly eventBus?: {
+        unsubscribeAll: () => void;
+    };
+    readonly cleanupFns?: ReadonlyArray<() => Promise<void> | void>;
+}
+/**
+ * Wraps an async shutdown operation with a deadline.
+ *
+ * If the shutdown completes within `timeoutMs`, returns normally.
+ * If the timeout fires first, logs a warning and continues (forces through).
+ *
+ * This ensures that a misbehaving component can never indefinitely block
+ * daemon shutdown and leave the system in a half-dead state.
+ *
+ * @example
+ * ```typescript
+ * await withShutdownTimeout(
+ *   () => adapter.stop(),
+ *   DEFAULT_TIMEOUTS.adapterShutdown,
+ *   'ClaudeCodeAdapter'
+ * );
+ * ```
+ *
+ * @param fn - Async shutdown function to execute
+ * @param timeoutMs - Maximum time to wait in milliseconds
+ * @param component - Human-readable name for logging
+ */
+declare function withShutdownTimeout(fn: () => Promise<void>, timeoutMs: number, component: string): Promise<void>;
+/**
+ * Stops AISnitch components in safe reverse-dependency order with individual timeouts.
+ *
+ * ## Why reverse order?
+ *
+ * The pipeline starts: adapters → HTTP → UDS → WS → eventBus
+ * If we stop WS before HTTP, new connections keep arriving at HTTP.
+ * If we stop eventBus before WS, consumers get events from the bus but can't send them.
+ * Therefore, stop in reverse: eventBus → WS → UDS → HTTP → adapters.
+ *
+ * @example
+ * ```typescript
+ * await shutdownInOrder(
+ *   {
+ *     eventBus: pipeline.getEventBus(),
+ *     wsServer: pipeline.getWSServer(),
+ *     httpReceiver: pipeline.getHTTPReceiver(),
+ *     udsServer: pipeline.getUDSServer(),
+ *     adapterRegistry: pipeline.getAdapterRegistry(),
+ *     cleanupFns: [
+ *       () => removePid(pathOptions),
+ *       () => removeDaemonState(pathOptions),
+ *     ],
+ *   },
+ *   {
+ *     eventBus: 1_000,
+ *     wsServer: 3_000,
+ *     httpReceiver: 2_000,
+ *     udsServer: 2_000,
+ *     adapterRegistry: 5_000,
+ *   },
+ *   'AISnitch pipeline'
+ * );
+ * ```
+ *
+ * @param components - Components to shut down
+ * @param timeouts - Per-component timeout in milliseconds
+ * @param label - Human-readable label for logging
+ */
+declare function shutdownInOrder(components: ShutdownComponents, timeouts: Partial<Record<keyof ShutdownComponents, number>>, label: string): Promise<void>;
+/**
+ * Coordinates all shutdown signals (SIGTERM, SIGINT, SIGHUP) for a process.
+ *
+ * ## Why a manager class?
+ *
+ * - Multiple signals can arrive in quick succession (e.g., SIGTERM then SIGINT)
+ * - Handlers must be idempotent (second call does nothing)
+ * - The manager tracks whether shutdown is already in progress
+ * - It ensures the main process exits with the correct exit code
+ *
+ * @example
+ * ```typescript
+ * const manager = new GracefulShutdownManager({
+ *   onShutdown: async (signal) => {
+ *     await shutdownInOrder(pipeline, timeouts, 'pipeline');
+ *     await cleanupFiles(pathOptions);
+ *   },
+ *   signal: 'SIGTERM',
+ * });
+ *
+ * process.on('SIGTERM', manager.handler);
+ * process.on('SIGINT', manager.handler);
+ *
+ * // Call handler manually to trigger shutdown from anywhere
+ * await manager.shutdown('manual-trigger');
+ * ```
+ */
+declare class GracefulShutdownManager {
+    private readonly options;
+    private shuttingDown;
+    private readonly pendingHandlers;
+    /**
+     * Creates a new shutdown manager.
+     *
+     * @param options - Configuration options
+     * @param options.onShutdown - Async function called when shutdown is triggered
+     * @param options.exitCode - Exit code to use (default: 0 for graceful, 1 for errors)
+     * @param options.exitDelayMs - Delay before `process.exit()` (default: 100ms for flush)
+     */
+    constructor(options: {
+        readonly onShutdown: (signal: string) => Promise<void>;
+        readonly exitCode?: number;
+        readonly exitDelayMs?: number;
+    });
+    /**
+     * Synchronous handler function suitable for `process.on()`.
+     *
+     * Multiple calls are safe — only the first call executes `onShutdown`.
+     * Subsequent calls queue to the internal pending set and run after the
+     * first shutdown completes.
+     */
+    get handler(): (signal: string) => void;
+    /**
+     * Manually triggers shutdown from async code (e.g., TUI quit button).
+     *
+     * @param signal - Signal name (for logging)
+     */
+    shutdown(signal?: string): void;
+    /**
+     * Returns whether shutdown is currently in progress.
+     */
+    isShuttingDown(): boolean;
+    private runShutdown;
+}
+/**
+ * Wraps a shutdown promise with an overall deadline.
+ * If the overall shutdown exceeds the deadline, forces the process to exit.
+ *
+ * This is the last resort: no shutdown operation should ever take this long,
+ * but a runaway deadlock could theoretically block forever without it.
+ *
+ * @example
+ * ```typescript
+ * const shutdownComplete = shutdownInOrder(components, timeouts, 'pipeline');
+ * await withOverallShutdownTimeout(shutdownComplete, DEFAULT_TIMEOUTS.daemonShutdown, 'AISnitch');
+ * ```
+ */
+declare function withOverallShutdownTimeout(shutdownPromise: Promise<void>, timeoutMs: number, label: string): Promise<void>;
+
+/**
+ * @file src/core/result.ts
+ * @description Simple Result type for explicit error handling without relying on try/catch.
+ *
+ * This is a lightweight alternative to fp-ts Either for cases where you want to force
+ * callers to handle the error case explicitly but don't need the full fp-ts ecosystem.
+ *
+ * The `Result<T, E>` type has two states:
+ * - `{ success: true, value: T }` — operation succeeded with a value
+ * - `{ success: false, error: E }` — operation failed with an error
+ *
+ * Usage pattern:
+ * ```typescript
+ * function parseConfig(raw: unknown): Result<AISnitchConfig, ValidationError> {
+ *   const result = ConfigSchema.safeParse(raw);
+ *   if (!result.success) {
+ *     return err(new ValidationError(
+ *       'Invalid config', 'VALIDATION_CONFIG_INVALID',
+ *       { issues: result.error.issues }
+ *     ));
+ *   }
+ *   return ok(result.data);
+ * }
+ *
+ * // Caller must handle both cases
+ * const result = parseConfig(raw);
+ * if (isErr(result)) {
+ *   logger.error({ error: result.error }, 'Config parsing failed');
+ *   return;
+ * }
+ * // result.value is guaranteed to exist here
+ * useConfig(result.value);
+ * ```
+ *
+ * @functions
+ *   → ok
+ *   → err
+ *   → isOk
+ *   → isErr
+ *   → mapOk
+ *   → mapErr
+ *   → flatMap
+ *   → fromPromise
+ * @exports Result, ok, err, isOk, isErr, mapOk, mapErr, flatMap, fromPromise
+ * @see ./errors.ts
+ * @see ./retry.ts
+ */
+/**
+ * Discriminated union representing either a successful value or a failure error.
+ *
+ * @typeParam T - The success value type
+ * @typeParam E - The error type (defaults to `Error`)
+ */
+type Result<T, E = Error> = {
+    readonly success: true;
+    readonly value: T;
+} | {
+    readonly success: false;
+    readonly error: E;
+};
+/**
+ * Narrowing type guard for the success case.
+ *
+ * @example
+ * ```typescript
+ * const result = maybeDoSomething();
+ * if (isOk(result)) {
+ *   console.log(result.value); // TypeScript knows result.value exists
+ * }
+ * ```
+ */
+declare function isOk<T, E>(result: Result<T, E>): result is {
+    success: true;
+    value: T;
+};
+/**
+ * Narrowing type guard for the error case.
+ *
+ * @example
+ * ```typescript
+ * const result = maybeDoSomething();
+ * if (isErr(result)) {
+ *   console.error(result.error); // TypeScript knows result.error exists
+ * }
+ * ```
+ */
+declare function isErr<T, E>(result: Result<T, E>): result is {
+    success: false;
+    error: E;
+};
+/**
+ * Constructs a successful result with a value.
+ *
+ * @example
+ * ```typescript
+ * const result = ok({ userId: 42, name: 'Alice' });
+ * // { success: true, value: { userId: 42, name: 'Alice' } }
+ * ```
+ */
+declare function ok<T>(value: T): Result<T, never>;
+/**
+ * Constructs a failed result with an error.
+ *
+ * @example
+ * ```typescript
+ * const result = err(new Error('Not found'));
+ * // { success: false, error: Error('Not found') }
+ * ```
+ */
+declare function err<E extends Error = Error>(error: E): Result<never, E>;
+/**
+ * Maps the success value through a transformation function.
+ * Errors pass through unchanged.
+ *
+ * @example
+ * ```typescript
+ * const result: Result<User, Error> = ok({ id: 1, name: 'Alice' });
+ * const mapped = mapOk(result, (user) => user.name.toUpperCase());
+ * // { success: true, value: 'ALICE' }
+ * ```
+ */
+declare function mapOk<T, E, U>(result: Result<T, E>, fn: (value: T) => U): Result<U, E>;
+/**
+ * Maps the error value through a transformation function.
+ * Success values pass through unchanged.
+ *
+ * @example
+ * ```typescript
+ * const result: Result<User, Error> = err(new Error('original'));
+ * const mapped = mapErr(result, (error) => new CustomError(error.message));
+ * // { success: false, error: CustomError('original') }
+ * ```
+ */
+declare function mapErr<T, E, F extends Error>(result: Result<T, E>, fn: (error: E) => F): Result<T, F>;
+/**
+ * Chains Result operations: if the first Result succeeds, apply `fn` to its value.
+ * If it fails, propagate the error without calling `fn`.
+ *
+ * @example
+ * ```typescript
+ * const result = await flatMap(
+ *   await parseConfig(raw),
+ *   (config) => validateAdapters(config.adapters)
+ * );
+ * // Either returns parseConfig's error, or the error from validateAdapters
+ * ```
+ */
+declare function flatMap<T, E, U, F extends Error>(result: Result<T, E>, fn: (value: T) => Result<U, F> | Promise<Result<U, F>>): Promise<Result<U, E | F>>;
+/**
+ * Converts a Promise to a Result, catching errors automatically.
+ * Rejections become `{ success: false, error: E }`.
+ *
+ * @example
+ * ```typescript
+ * const result = await fromPromise(
+ *   fetch('http://127.0.0.1:4821/health'),
+ *   (error) => new NetworkError(
+ *     'Health check failed',
+ *     'NETWORK_HTTP_CONNECT_FAILED',
+ *     { cause: error }
+ *   )
+ * );
+ * if (isErr(result)) {
+ *   logger.warn({ error: result.error }, 'Daemon health check failed');
+ *   return null;
+ * }
+ * const health = await result.value.json();
+ * ```
+ */
+declare function fromPromise<T, E extends Error>(promise: Promise<T>, mapError: (reason: unknown) => E): Promise<Result<T, E>>;
+/**
+ * Synchronous version of `fromPromise` for non-async functions.
+ *
+ * @example
+ * ```typescript
+ * const result = fromSync(() => JSON.parse(rawJson), (e) =>
+ *   new ValidationError('Invalid JSON', 'VALIDATION_JSON_PARSE', { cause: e })
+ * );
+ * ```
+ */
+declare function fromSync<T, E extends Error>(fn: () => T, mapError: (reason: unknown) => E): Result<T, E>;
+
+/**
+ * @file src/core/retry.ts
+ * @description Exponential backoff retry utilities for transient operations.
+ *
+ * Retry logic is essential for resilience against:
+ * - Network flakiness (connection refused, timeouts, DNS failures)
+ * - Transient file-system contention (file locked, directory not ready)
+ * - External API rate limits (backoff on 429 Too Many Requests)
+ *
+ * This module provides:
+ * - `withRetry()` — async function with exponential backoff
+ * - `RetryOptions` — configurable retry parameters
+ * - `DefaultRetryOptions` — sensible defaults for AISnitch workloads
+ *
+ * Usage:
+ * ```typescript
+ * const result = await withRetry(
+ *   () => fetchHealth(daemonPort),
+ *   {
+ *     attempts: 3,
+ *     delayMs: 500,
+ *     backoff: 2,
+ *     context: 'daemon-health-check',
+ *   }
+ * );
+ * ```
+ *
+ * @functions
+ *   → withRetry
+ *   → sleep
+ *   → DefaultRetryOptions
+ * @exports RetryOptions, DefaultRetryOptions, withRetry, sleep
+ * @see ./errors.ts
+ * @see ./result.ts
+ */
+/**
+ * Configuration for retry behaviour.
+ */
+interface RetryOptions {
+    /**
+     * Maximum number of attempts before giving up.
+     * @default 3
+     */
+    readonly attempts: number;
+    /**
+     * Initial delay in milliseconds between retries.
+     * @default 500
+     */
+    readonly delayMs: number;
+    /**
+     * Multiplicative factor for delay after each attempt.
+     * @default 2
+     */
+    readonly backoff: number;
+    /**
+     * Maximum total time in milliseconds across all retries.
+     * @default 30_000
+     */
+    readonly maxTotalDelayMs: number;
+    /**
+     * Human-readable label used in log messages for traceability.
+     */
+    readonly context: string;
+    /**
+     * Optional predicate to filter which errors trigger a retry.
+     * By default, `isRetryableError()` is used.
+     * Return `true` to retry, `false` to give up immediately.
+     */
+    readonly shouldRetry?: (error: unknown) => boolean;
+    /**
+     * Set to `true` to jitter the delay slightly (±25%) to avoid thundering herd.
+     * @default true
+     */
+    readonly jitter?: boolean;
+}
+/**
+ * Sensible defaults tuned for AISnitch workloads:
+ * - Quick first retry (500ms) for responsiveness
+ * - Exponential backoff to back off gracefully
+ * - 3 attempts to avoid long stalls
+ * - Jitter enabled to spread load
+ */
+declare const DefaultRetryOptions: Readonly<RetryOptions>;
+/**
+ * Blocks the current async execution for the given number of milliseconds.
+ *
+ * @example
+ * ```typescript
+ * await sleep(1000); // wait 1 second
+ * ```
+ */
+declare function sleep(ms: number): Promise<void>;
+/**
+ * Wraps an async operation with exponential-backoff retry logic.
+ *
+ * ## How it works
+ *
+ * 1. Executes `fn` immediately (no initial delay)
+ * 2. If it succeeds → returns the result
+ * 3. If it throws and `shouldRetry(error)` returns `true` and attempts remain:
+ *    - Logs a warning at attempt level (warn) and at failure level (error)
+ *    - Waits `delayMs * backoff^attempt` milliseconds (with optional jitter)
+ *    - Repeats from step 1
+ * 4. If it throws and `shouldRetry(error)` returns `false` → throws immediately
+ * 5. If all attempts are exhausted → throws the last error
+ *
+ * ## When NOT to use this
+ *
+ * - **Permanent failures** (e.g., validation errors, missing required files)
+ *   → Use `isRetryableError()` to filter these out automatically
+ * - **Operations that are not idempotent** → only retry if `fn` is safe to re-execute
+ * - **User-facing latency-sensitive paths** → use a shorter `delayMs` and fewer `attempts`
+ *
+ * @example
+ * ```typescript
+ * // Retry a flaky health check up to 3 times
+ * const health = await withRetry(
+ *   () => fetch('http://127.0.0.1:4821/health').then(r => r.json()),
+ *   {
+ *     ...DefaultRetryOptions,
+ *     context: 'daemon-health-check',
+ *   }
+ * );
+ * ```
+ */
+declare function withRetry<T>(fn: () => Promise<T>, options: Partial<RetryOptions> & {
+    context: string;
+}): Promise<T>;
+/**
+ * Convenience wrapper for fire-and-forget retries (no return value needed).
+ * Logs failures but never throws — useful for non-critical background tasks.
+ *
+ * @example
+ * ```typescript
+ * // Best-effort metric reporting — don't fail the main flow
+ * fireAndForgetRetry(
+ *   () => sendMetrics(metrics),
+ *   { context: 'metrics-report', attempts: 2 }
+ * );
+ * ```
+ */
+declare function fireAndForgetRetry<T>(fn: () => Promise<T>, options: Partial<RetryOptions> & {
+    context: string;
+}): void;
+/**
+ * Builds a retry-enabled version of any async function.
+ * The returned function will automatically retry on retryable errors.
+ *
+ * @example
+ * ```typescript
+ * const safeReadFile = withRetryOn(
+ *   (path: string) => readFile(path, 'utf8'),
+ *   { attempts: 3, delayMs: 200, context: 'file-read' }
+ * );
+ *
+ * const content = await safeReadFile('/path/to/file.txt');
+ * ```
+ */
+declare function withRetryOn<T extends (...args: never[]) => Promise<unknown>>(fn: T, options: Partial<RetryOptions> & {
+    context: string;
+}): T;
+
+/**
+ * @file src/core/safety.ts
+ * @description Type-safe extraction helpers for working with untyped record data.
+ *
+ * AISnitch often deals with loosely-typed payloads:
+ * - Hook payloads from third-party tools (Claude Code, OpenCode, etc.)
+ * - JSONL transcript observations parsed from raw JSON
+ * - Config files loaded from disk
+ * - Event data fields that may be undefined
+ *
+ * This module provides:
+ * - `getString()` / `getNumber()` / `getBoolean()` — safe extractors with type narrowing
+ * - `getStringOrDefault()` / `getNumberOrDefault()` — with fallback defaults
+ * - `getArray()` / `getObject()` — structural validation
+ * - `getSafeInteger()` — integer with bounds checking
+ * - `getPositiveNumber()` — positive values only
+ * - `isValidPort()` — network port validation (1-65535)
+ * - `isValidPathLength()` — POSIX path limit check (4096 chars)
+ * - `isValidStringLength()` — max string length check
+ *
+ * ## Why not just use optional chaining?
+ *
+ * Optional chaining (`?.`) protects against null/undefined access chains, but it:
+ * - Does NOT validate the type of the value (e.g., `obj.key` could be `string | number | null`)
+ * - Does NOT enforce constraints (e.g., port range, string max length)
+ * - Does NOT normalize values (e.g., trimming strings, clamping numbers)
+ *
+ * These helpers do all of the above in one call.
+ *
+ * @functions
+ *   → getString
+ *   → getNumber
+ *   → getBoolean
+ *   → getSafeInteger
+ *   → getPositiveNumber
+ *   → isValidPort
+ *   → isValidPathLength
+ *   → isValidStringLength
+ *   → getArray
+ *   → getObject
+ * @exports getString, getNumber, getBoolean, getSafeInteger, getPositiveNumber, isValidPort, isValidPathLength, isValidStringLength, getArray, getObject
+ * @see ./errors.ts
+ * @see ./result.ts
+ */
+/**
+ * Maximum valid TCP/UDP port number.
+ * Ports below 1024 require root privileges on Unix.
+ */
+declare const MAX_PORT = 65535;
+/**
+ * Minimum valid TCP/UDP port number.
+ */
+declare const MIN_PORT = 1;
+/**
+ * Maximum path length per POSIX (NAME_MAX).
+ * Most filesystems support 255 bytes per path component, but the total path
+ * can grow much longer. 4096 is a safe upper bound for in-memory validation.
+ */
+declare const MAX_PATH_LENGTH = 4096;
+/**
+ * Maximum string length for most AISnitch fields (file paths, model names, etc.).
+ * Beyond this, truncation or rejection is safer than silent truncation.
+ */
+declare const MAX_GENERIC_STRING_LENGTH = 10000;
+/**
+ * Maximum length for short labels (tool names, session IDs, event types).
+ * These should always be kept short for display.
+ */
+declare const MAX_LABEL_LENGTH = 255;
+/**
+ * Extracts a non-empty trimmed string from a record field.
+ *
+ * @example
+ * ```typescript
+ * const model = getString(payload, 'model');
+ * // → 'claude-sonnet-4-20250514' | undefined
+ * ```
+ */
+declare function getString(record: Record<string, unknown>, key: string): string | undefined;
+/**
+ * Extracts a string and enforces a maximum length.
+ * If the string exceeds `maxLength`, it is truncated to that length.
+ *
+ * @example
+ * ```typescript
+ * const truncated = getStringWithMaxLength(payload, 'errorMessage', 10_000);
+ * ```
+ */
+declare function getStringWithMaxLength(record: Record<string, unknown>, key: string, maxLength: number): string | undefined;
+/**
+ * Extracts a finite number from a record field.
+ *
+ * Filters out `NaN`, `Infinity`, `-Infinity`.
+ *
+ * @example
+ * ```typescript
+ * const pid = getNumber(payload, 'pid');
+ * // → 12345 | undefined
+ * ```
+ */
+declare function getNumber(record: Record<string, unknown>, key: string): number | undefined;
+/**
+ * Extracts a finite integer within a range.
+ *
+ * @example
+ * ```typescript
+ * const seqnum = getSafeInteger(payload, 'seqnum', { min: 1 });
+ * // → 42 | undefined
+ * ```
+ */
+declare function getSafeInteger(record: Record<string, unknown>, key: string, options?: {
+    min?: number;
+    max?: number;
+}): number | undefined;
+/**
+ * Extracts a positive number ( > 0).
+ *
+ * @example
+ * ```typescript
+ * const tokens = getPositiveNumber(payload, 'tokensUsed');
+ * // → 1500 | undefined (rejects 0, negative)
+ * ```
+ */
+declare function getPositiveNumber(record: Record<string, unknown>, key: string): number | undefined;
+/**
+ * Extracts a boolean from a record field.
+ *
+ * Handles the common "stringified boolean" pattern where config files
+ * or query parameters store booleans as strings ('true', 'false').
+ *
+ * @example
+ * ```typescript
+ * const enabled = getBoolean(record, 'enabled');
+ * // → true | false | undefined
+ * ```
+ */
+declare function getBoolean(record: Record<string, unknown>, key: string): boolean | undefined;
+/**
+ * Extracts an array from a record field.
+ *
+ * @example
+ * ```typescript
+ * const parts = getArray(payload, 'content');
+ * // → unknown[] | undefined
+ * ```
+ */
+declare function getArray<T = unknown>(record: Record<string, unknown>, key: string): T[] | undefined;
+/**
+ * Extracts a plain object from a record field.
+ *
+ * Returns `undefined` for arrays, class instances, `null`, primitives.
+ *
+ * @example
+ * ```typescript
+ * const toolInput = getObject(payload, 'tool_input');
+ * // → Record<string, unknown> | undefined
+ * ```
+ */
+declare function getObject(record: Record<string, unknown>, key: string): Record<string, unknown> | undefined;
+/**
+ * Validates whether a port number is within the valid TCP/UDP range (1-65535).
+ *
+ * @example
+ * ```typescript
+ * const port = getSafeInteger(payload, 'port', { min: 1, max: 65535 });
+ * if (isValidPort(port)) {
+ *   server.listen(port);
+ * }
+ * ```
+ */
+declare function isValidPort(port: number | undefined): port is number;
+/**
+ * Validates whether a path string is within the POSIX NAME_MAX limit.
+ *
+ * Uses the conservative 4096-character limit (actual NAME_MAX varies by FS).
+ * This check is useful for in-memory validation before file system operations.
+ *
+ * @example
+ * ```typescript
+ * const filePath = getString(payload, 'filePath');
+ * if (filePath && isValidPathLength(filePath)) {
+ *   readFile(filePath);
+ * }
+ * ```
+ */
+declare function isValidPathLength(path: string | undefined): path is string;
+/**
+ * Validates whether a string does not exceed a maximum length.
+ *
+ * @example
+ * ```typescript
+ * const message = getString(payload, 'errorMessage');
+ * if (message && isValidStringLength(message, 10_000)) {
+ *   log(message);
+ * }
+ * ```
+ */
+declare function isValidStringLength(value: string | undefined, maxLength: number): value is string;
+/**
+ * Checks whether a value is a plain object (not null, not array, not class instance).
+ *
+ * Uses `Object.prototype.toString` to detect class instances:
+ * - Plain objects return `'[object Object]'`
+ * - Class instances return `'[object ClassName]'`
+ *
+ * @example
+ * ```typescript
+ * if (isRecord(payload)) {
+ *   const value = payload[key]; // TypeScript narrows to Record<string, unknown>
+ * }
+ * ```
+ */
+declare function isRecord(value: unknown): value is Record<string, unknown>;
+/**
+ * Type guard to narrow any `unknown` to a non-null value.
+ *
+ * @example
+ * ```typescript
+ * const cleaned = value != null ? value : defaultValue;
+ * // or using the guard:
+ * if (isNotNull(value)) { ... }
+ * ```
+ */
+declare function isNotNull<T>(value: T): value is T & NonNullable<unknown>;
+/**
+ * Extracts a port number with full validation (in range, integer, finite).
+ *
+ * @example
+ * ```typescript
+ * const port = getPort(record, 'httpPort');
+ * // → 4821 | undefined
+ * ```
+ */
+declare function getPort(record: Record<string, unknown>, key: string): number | undefined;
+/**
+ * Extracts a sequence number (positive integer >= 1).
+ *
+ * @example
+ * ```typescript
+ * const seqnum = getSeqnum(record, 'seqnum');
+ * // → 42 | undefined
+ * ```
+ */
+declare function getSeqnum(record: Record<string, unknown>, key: string): number | undefined;
+
 /**
  * @file src/core/session-identity.ts
  * @description Shared helpers for deriving stable session ids and readable session labels from partial runtime metadata.
@@ -1821,6 +3148,166 @@ declare function formatSessionShortId(tool: ToolName, sessionId: string | undefi
  */
 declare function formatSessionLabelFromEvent(event: AISnitchEvent): string;
 
+/**
+ * @file src/core/timeout.ts
+ * @description Async operation timeout wrappers to prevent indefinite blocking.
+ *
+ * AISnitch processes many async operations (file reads, HTTP requests, process
+ * detection, file watchers, adapter startup/shutdown). Without explicit timeouts,
+ * any of these can block the entire daemon indefinitely if the underlying resource
+ * becomes unresponsive (e.g., NFS mount stuck, disk I/O stalled, external API hanging).
+ *
+ * This module provides:
+ * - `withTimeout()` — race a promise against a deadline
+ * - `TimeoutError` — typed error thrown on timeout
+ * - `DEFAULT_TIMEOUTS` — sane defaults per operation type
+ *
+ * Usage:
+ * ```typescript
+ * // Fail-fast: don't wait more than 3s for a file read
+ * const content = await withTimeout(
+ *   readFile('/path/to/transcript.jsonl', 'utf8'),
+ *   3_000,
+ *   'claude-transcript-read'
+ * );
+ * ```
+ *
+ * @functions
+ *   → withTimeout
+ *   → DEFAULT_TIMEOUTS
+ * @exports DEFAULT_TIMEOUTS, withTimeout
+ * @see ./errors.ts (TimeoutError)
+ * @see ./graceful-shutdown.ts
+ */
+
+/**
+ * Named timeout windows for common AISnitch operations.
+ *
+ * These defaults are conservative but reasonable for local development:
+ * - File operations: fast on local SSDs, need headroom for larger logs
+ * - HTTP requests: generous (30s) because AI tool hooks can be slow
+ * - Process detection: frequent polling, keep each poll short
+ * - Adapter lifecycle: moderate (10s) for graceful shutdowns
+ *
+ * Override per-call via the `withTimeout()` `timeoutMs` parameter.
+ */
+declare const DEFAULT_TIMEOUTS: Readonly<{
+    /**
+     * File read/write operations (JSONL transcripts, config files).
+     * Default: 5 seconds
+     */
+    readonly fileOperation: 5000;
+    /**
+     * HTTP requests to health endpoint or external APIs.
+     * Default: 30 seconds
+     */
+    readonly httpRequest: 30000;
+    /**
+     * Process detection commands (`pgrep`, `ps aux`).
+     * Default: 3 seconds
+     */
+    readonly processDetection: 3000;
+    /**
+     * Adapter startup (file watchers, hook bridges, pollers).
+     * Default: 10 seconds
+     */
+    readonly adapterStartup: 10000;
+    /**
+     * Adapter shutdown (graceful cleanup, watcher close).
+     * Default: 5 seconds — after this, resources are force-closed
+     */
+    readonly adapterShutdown: 5000;
+    /**
+     * Daemon graceful shutdown (stop all components in order).
+     * Default: 30 seconds
+     */
+    readonly daemonShutdown: 30000;
+    /**
+     * WebSocket connection establishment.
+     * Default: 10 seconds
+     */
+    readonly wsConnection: 10000;
+    /**
+     * Overall pipeline start (all components).
+     * Default: 15 seconds
+     */
+    readonly pipelineStartup: 15000;
+}>;
+/**
+ * Type representing the keys of `DEFAULT_TIMEOUTS`.
+ */
+type TimeoutName = keyof typeof DEFAULT_TIMEOUTS;
+/**
+ * Races a promise against a deadline.
+ *
+ * If the promise resolves first, returns the resolved value.
+ * If the timeout fires first, throws a `TimeoutError`.
+ *
+ * The timeout is implemented via `Promise.race()` so it does not
+ * forcefully abort the underlying promise — the promise continues
+ * running in the background. For truly cancellable operations,
+ * consider `AbortController` in addition to this utility.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   const result = await withTimeout(
+ *     fetch('http://example.com/slow-endpoint'),
+ *     5_000,
+ *     'external-api-call'
+ *   );
+ *   return await result.json();
+ * } catch (error) {
+ *   if (error instanceof TimeoutError) {
+ *     logger.warn({ context: error.context }, 'Operation timed out');
+ *     return null;
+ *   }
+ *   throw error;
+ * }
+ * ```
+ *
+ * @param promise - The async operation to race
+ * @param timeoutMs - Maximum time to wait in milliseconds
+ * @param context - Human-readable label for logging and error context
+ * @returns The resolved value if `promise` wins the race
+ * @throws TimeoutError if the timeout fires first
+ */
+declare function withTimeout<T>(promise: Promise<T>, timeoutMs: number, context: string): Promise<T>;
+/**
+ * Wraps a promise with a timeout and logs a warning if it times out.
+ * Unlike `withTimeout()`, this never throws — it falls through to the
+ * original promise's result (or error) if the timeout fires first.
+ *
+ * Best-effort: useful for non-critical background operations where a
+ * timeout should log a warning but not crash the flow.
+ *
+ * @example
+ * ```typescript
+ * // Log a warning but don't fail if process detection hangs
+ * await timeoutWarning(
+ *   listProcesses(processListCommand),
+ *   DEFAULT_TIMEOUTS.processDetection,
+ *   'claude-process-detection'
+ * );
+ * ```
+ */
+declare function timeoutWarning<T>(promise: Promise<T>, timeoutMs: number, context: string): Promise<T>;
+/**
+ * Gets the timeout value for a named operation.
+ *
+ * @example
+ * ```typescript
+ * const timeoutMs = getTimeout('adapterShutdown');
+ * // → 5_000
+ * ```
+ */
+declare function getTimeout(name: TimeoutName): number;
+/**
+ * Checks whether an error is a TimeoutError.
+ * Shorthand for `error instanceof TimeoutError` with explicit return type.
+ */
+declare function isTimeoutError(error: unknown): error is TimeoutError;
+
 /**
  * @file src/package-info.ts
  * @description Shared package metadata constants consumed by the public index, CLI, and TUI without creating import cycles.
@@ -2596,4 +4083,4 @@ declare function renderAttachedTui(options: AttachedTuiOptions): Promise<void>;
  */
 declare function renderManagedTui(options: ManagedTuiOptions): Promise<void>;
 
-export { AISNITCH_DESCRIPTION, AISNITCH_EVENT_TYPES, AISNITCH_PACKAGE_NAME, AISNITCH_VERSION, type AISnitchConfig, type AISnitchEvent, AISnitchEventSchema, type AISnitchEventType, AISnitchEventTypeSchema, type AISnitchLoggerLevel, type AISnitchScaffoldInfo, AUTO_UPDATE_MANAGERS, type AdapterConfig, AdapterConfigSchema, type AdapterPublishContext, AdapterRegistry, type AdapterRuntimeOptions, type AdapterStatus, AiderAdapter, type AiderAdapterOptions, type AiderHistoryObservation, type AiderHistoryParseResult, App, type AppProps, type AttachedTuiOptions, type AutoUpdateConfig, AutoUpdateConfigSchema, BaseAdapter, type CESPCategory, CESPCategorySchema, CESP_CATEGORIES, CESP_MAP, ClaudeCodeAdapter, type ClaudeCodeAdapterOptions, CodexAdapter, type CodexAdapterOptions, type ConfigPathOptions, ConfigSchema, ContextDetector, CopilotCLIAdapter, type CopilotCLIAdapterOptions, type CreateEventInput, CursorAdapter, type CursorAdapterOptions, DEFAULT_CONFIG, DEFAULT_TUI_FILTERS, DEFAULT_VISIBLE_EVENT_COUNT, DevinAdapter, type DevinAdapterOptions, ERROR_TYPES, EVENT_COLORS, EVENT_ICONS, EVENT_STREAM_LIMIT, type EnrichedContextFields, type ErrorType, ErrorTypeSchema, EventBus, type EventBusStats, type EventData, EventDataSchema, type EventHandler, EventLine, type EventLineProps, EventStream, type EventStreamProps, type EventStreamSource, FilterBar, type FilterBarProps, type FocusedPanel, type ForegroundTuiOptions, GeminiCLIAdapter, type GeminiCLIAdapterOptions, type GenericPTYObservation, GenericPTYSession, type GenericPTYSessionOptions, type GlobalActivityStatus, GlobalBadge, type GlobalBadgeProps, GooseAdapter, type GooseAdapterOptions, HTTPReceiver, type HTTPReceiverStartOptions, type HTTPReceiverStats, Header, type HeaderProps, type HealthSnapshot, HelpOverlay, type HookHandler, type InterceptionStrategy, KiloAdapter, type KiloAdapterOptions, LOG_LEVELS, ManagedDaemonApp, type ManagedDaemonAppProps, type ManagedTuiOptions, type ManagedTuiSnapshot, type MonitorCloseHandler, type MonitorOutput, type NormalizedAdapterHookPayload, OpenClawAdapter, type OpenClawAdapterOptions, OpenCodeAdapter, type OpenCodeAdapterOptions, Panel, type PanelProps, PanelStack, type PanelStackProps, Pipeline, type PipelineStartOptions, type PipelineStatus, type PortResolutionOptions, type ProcessContext, type ProcessInfo, RingBuffer, SESSION_STALE_AFTER_MS, type SelectorOption, type SessionFilterTarget, type SessionIdentityInput, SessionPanel, type SessionPanelProps, type SessionState, StatusBar, type StatusBarProps, TOOL_COLORS, TOOL_NAMES, TUI_THEME, TUI_VIEW_MODES, type ToolInput, ToolInputSchema, type ToolName, ToolNameSchema, type TuiDaemonSnapshot, type TuiFilters, type TuiInitialFilters, type TuiInteractionMode, type TuiStatusSnapshot, type TuiThemeColor, type TuiViewMode, UDSServer, type UDSServerStartOptions, type UDSServerStats, type UseEventStreamOptions, type UseEventStreamState, type UseKeyBindsOptions, type UseKeyBindsState, WSServer, type WSServerStartOptions, type WSServerStats, type WelcomeMessage, analyzeTerminalOutputChunk, appendEventToStream, applyEventFilters, applySessionFilters, attachEventBusMonitor, attachWebSocketMonitor, countActiveFilters, createDefaultAdapters, createEvent, createUuidV7, deriveGlobalActivityStatus, deriveSessions, ensureConfigDir, formatEventDetail, formatEventLine, formatEventTime, formatSessionLabel, formatSessionLabelFromEvent, formatSessionShortId, formatWelcomeLine, getAISnitchHomePath, getCESPCategory, getConfigPath, getPackageScaffoldInfo, getPendingFrozenEventCount, getSocketPath, getVisibleEventWindow, isGenericSessionId, loadConfig, logger, parseAiderHistoryMarkdown, renderAttachedTui, renderForegroundTui, renderManagedTui, resolveAvailablePort, resolveSessionId, saveConfig, setLoggerLevel, useEventStream, useKeyBinds, useSessions };
+export { AISNITCH_DESCRIPTION, AISNITCH_EVENT_TYPES, AISNITCH_PACKAGE_NAME, AISNITCH_VERSION, type AISnitchConfig, AISnitchError, type AISnitchEvent, AISnitchEventSchema, type AISnitchEventType, AISnitchEventTypeSchema, type AISnitchLoggerLevel, type AISnitchScaffoldInfo, AUTO_UPDATE_MANAGERS, type AdapterConfig, AdapterConfigSchema, AdapterError, type AdapterPublishContext, AdapterRegistry, type AdapterRuntimeOptions, type AdapterStatus, AiderAdapter, type AiderAdapterOptions, type AiderHistoryObservation, type AiderHistoryParseResult, App, type AppProps, type AttachedTuiOptions, type AutoUpdateConfig, AutoUpdateConfigSchema, BaseAdapter, type CESPCategory, CESPCategorySchema, CESP_CATEGORIES, CESP_MAP, CircuitBreaker, type CircuitBreakerOptions, CircuitOpenError, type CircuitState, ClaudeCodeAdapter, type ClaudeCodeAdapterOptions, CodexAdapter, type CodexAdapterOptions, type ConfigPathOptions, ConfigSchema, ContextDetector, CopilotCLIAdapter, type CopilotCLIAdapterOptions, type CreateEventInput, CursorAdapter, type CursorAdapterOptions, DEFAULT_CONFIG, DEFAULT_TIMEOUTS, DEFAULT_TUI_FILTERS, DEFAULT_VISIBLE_EVENT_COUNT, DefaultRetryOptions, DevinAdapter, type DevinAdapterOptions, ERROR_TYPES, EVENT_COLORS, EVENT_ICONS, EVENT_STREAM_LIMIT, type EnrichedContextFields, type ErrorType, ErrorTypeSchema, EventBus, type EventBusStats, type EventData, EventDataSchema, type EventHandler, EventLine, type EventLineProps, EventStream, type EventStreamProps, type EventStreamSource, FilterBar, type FilterBarProps, FinalMessageSchema, type FocusedPanel, type ForegroundTuiOptions, GeminiCLIAdapter, type GeminiCLIAdapterOptions, type GenericPTYObservation, GenericPTYSession, type GenericPTYSessionOptions, type GlobalActivityStatus, GlobalBadge, type GlobalBadgeProps, GooseAdapter, type GooseAdapterOptions, GracefulShutdownManager, HTTPReceiver, type HTTPReceiverStartOptions, type HTTPReceiverStats, Header, type HeaderProps, type HealthSnapshot, HelpOverlay, type HookHandler, type InterceptionStrategy, KiloAdapter, type KiloAdapterOptions, LOG_LEVELS, MAX_GENERIC_STRING_LENGTH, MAX_LABEL_LENGTH, MAX_PATH_LENGTH, MAX_PORT, MIN_PORT, ManagedDaemonApp, type ManagedDaemonAppProps, type ManagedTuiOptions, type ManagedTuiSnapshot, MessageContentSchema, type MonitorCloseHandler, type MonitorOutput, NetworkError, type NormalizedAdapterHookPayload, OpenClawAdapter, type OpenClawAdapterOptions, OpenCodeAdapter, type OpenCodeAdapterOptions, Panel, type PanelProps, PanelStack, type PanelStackProps, PiAdapter, Pipeline, PipelineError, type PipelineStartOptions, type PipelineStatus, type PortResolutionOptions, type ProcessContext, type ProcessInfo, type Result, type RetryOptions, RingBuffer, SESSION_STALE_AFTER_MS, SHARED_BREAKERS, type SelectorOption, type SessionFilterTarget, type SessionIdentityInput, SessionPanel, type SessionPanelProps, type SessionState, type ShutdownComponents, StatusBar, type StatusBarProps, TOOL_COLORS, TOOL_NAMES, TUI_THEME, TUI_VIEW_MODES, ThinkingContentSchema, TimeoutError, type TimeoutName, ToolCallNameSchema, type ToolInput, ToolInputSchema, type ToolName, ToolNameSchema, ToolResultSchema, type TuiDaemonSnapshot, type TuiFilters, type TuiInitialFilters, type TuiInteractionMode, type TuiStatusSnapshot, type TuiThemeColor, type TuiViewMode, UDSServer, type UDSServerStartOptions, type UDSServerStats, type UseEventStreamOptions, type UseEventStreamState, type UseKeyBindsOptions, type UseKeyBindsState, ValidationError, WSServer, type WSServerStartOptions, type WSServerStats, type WelcomeMessage, ZedAdapter, analyzeTerminalOutputChunk, appendEventToStream, applyEventFilters, applySessionFilters, attachEventBusMonitor, attachWebSocketMonitor, countActiveFilters, createDefaultAdapters, createEvent, createUuidV7, deriveGlobalActivityStatus, deriveSessions, ensureConfigDir, err, fireAndForgetRetry, flatMap, formatEventDetail, formatEventLine, formatEventTime, formatSessionLabel, formatSessionLabelFromEvent, formatSessionShortId, formatWelcomeLine, fromPromise, fromSync, getAISnitchHomePath, getArray, getBoolean, getCESPCategory, getConfigPath, getNumber, getObject, getPackageScaffoldInfo, getPendingFrozenEventCount, getPort, getPositiveNumber, getSafeInteger, getSeqnum, getSocketPath, getString, getStringWithMaxLength, getTimeout, getVisibleEventWindow, isAISnitchError, isErr, isGenericSessionId, isNotNull, isOk, isRecord, isRetryableError, isTimeoutError, isValidPathLength, isValidPort, isValidStringLength, loadConfig, logger, mapErr, mapOk, ok, parseAiderHistoryMarkdown, renderAttachedTui, renderForegroundTui, renderManagedTui, resolveAvailablePort, resolveSessionId, saveConfig, setLoggerLevel, shutdownInOrder, sleep, timeoutWarning, useEventStream, useKeyBinds, useSessions, withOverallShutdownTimeout, withRetry, withRetryOn, withShutdownTimeout, withTimeout };