@aitne/daemon 0.1.0

package/dist/core/dispatcher.d.ts

@@ -0,0 +1,999 @@
+import type Database from "better-sqlite3";
+import type { Event, MessageEvent, AgentResult, BackendId, IntegrationKey, IntegrationState } from "@aitne/shared";
+import type { AgentConfig } from "../config.js";
+import type { DocsCitationLookup } from "./docs/citation-validator.js";
+import type { SignalDetector } from "./signal-detector.js";
+import type { ServiceRegistry } from "../services/service-registry.js";
+import { EventBus } from "./event-bus.js";
+import { type IAgentRouter } from "./backends/backend-router.js";
+import type { TodayWriteLockManager } from "./today-write-lock.js";
+import type { RoadmapWriteLockManager } from "./roadmap-write-lock.js";
+import type { AgentWriteTracker } from "../safety/agent-write-tracker.js";
+import type { AttachmentStore } from "../services/attachments/store.js";
+import type { VoiceTranscriber } from "../services/voice/transcriber.js";
+import type { SessionInfoPayload } from "../api/chat-binding-query.js";
+import type { DeferredSessionEffects } from "./session-manager.js";
+export type { IAgentCore, StreamCallbacks } from "./agent-core.js";
+export type { IAgentRouter } from "./backends/backend-router.js";
+/**
+ * P22 §3.4 step 4 — the optimizer-only allowedTools envelope. Every
+ * `routine.skill_curation` event runs the agent with exactly these tools
+ * and nothing else. The curl glob is anchored on the daemon's loopback URL
+ * so a hook-bypassed request still hits the curation API's chokepoint
+ * (Zod, run-token, smoke test); `Read` is required for the agent to
+ * consume the inlined data dump under the workdir's `data/` subtree.
+ *
+ * Kept narrow on purpose: adding any other tool here widens the optimizer's
+ * blast radius. If a future signal source needs the agent to write to a
+ * different surface, add a new curation API endpoint and let the curl glob
+ * cover it — do NOT add `Bash(*)` or `Write` here.
+ */
+export declare const SKILL_CURATION_OPTIMIZER_ALLOWED_TOOLS: readonly ["Read", "Bash(curl http://localhost:8321/api/skill-curation/*)"];
+export interface ReplyActivityHandle {
+    stop(): Promise<void>;
+}
+/** Interface for streaming adapter (dashboard SSE) */
+export interface IDashboardStream {
+    sendStreamChunk(channelId: string, chunk: string): void;
+    sendStreamEnd(channelId: string): void;
+    sendMessageMeta?(channelId: string, meta: {
+        backend?: string;
+        model?: string;
+        durationMs?: number;
+        costUsd?: number;
+    }): void;
+    sendSessionInfo?(channelId: string, info: SessionInfoPayload): void;
+    sendError?(channelId: string, message: string): void;
+    /**
+     * Chat-attachments Phase 1 — ship the outbound attachment list produced
+     * during the just-completed turn to the dashboard. Consumed by the
+     * transcript renderer to show download chips / inline thumbnails
+     * alongside the assistant message.
+     */
+    sendAttachments?(channelId: string, attachments: Array<{
+        id: string;
+        originalFilename: string;
+        mimeType: string;
+        sizeBytes: number;
+        caption?: string;
+    }>): void;
+}
+/** Interface for ContextBuilder — implemented in Phase 1D */
+export interface IContextBuilder {
+    build(event: Event): Promise<string>;
+}
+/** Function type for resolving task flow templates by event type */
+export type GetTaskFlow = (eventType: string, backendId?: string, integrations?: Partial<Record<IntegrationKey, IntegrationState>>) => string;
+/** Interface for NotificationManager — implemented in Phase 1F */
+export interface INotificationManager {
+    send(message: string, event: Event, options?: {
+        priority?: string;
+        category?: string;
+        destinationMode?: "default" | "configured_only";
+        originSessionId?: number;
+    }): Promise<void>;
+    beginReplyActivity(event: MessageEvent): Promise<ReplyActivityHandle>;
+}
+/** Interface for SessionManager — implemented in Phase 2A */
+export interface ISessionManager {
+    getOrCreate(params: {
+        platform: string;
+        channel: string;
+        threadId: string | null;
+        isDm?: boolean;
+        /**
+         * MessageEvent.intent — forks the dashboard DM tuple into a separate
+         * scope (chat vs docs_qa) so the two surfaces don't share a session.
+         */
+        intent?: "chat" | "docs_qa";
+        requiredBackend?: BackendId;
+        /**
+         * When set and it differs from the active session's stored `model`,
+         * treat the mismatch like a backend switch: reset the SDK session in
+         * place (dashboard) or close + recreate (other DMs/threads) so the
+         * new model starts fresh and history is re-injected as prompt text.
+         * Omitting it falls back to the pre-existing "backend-only" match.
+         */
+        requiredModel?: string;
+    }): Promise<{
+        id: number;
+        isActive: boolean;
+        sessionId: string | null;
+        model: string;
+        backend?: BackendId;
+        requiresHistoryInjection?: boolean;
+    }>;
+    /** Find an existing active session without creating one. Returns null if none exists. */
+    findActive(params: {
+        platform: string;
+        channel: string;
+        threadId: string | null;
+        isDm?: boolean;
+        intent?: "chat" | "docs_qa";
+    }): Promise<{
+        id: number;
+    } | null>;
+    updateSession(id: number, sessionId: string, model: string, backend?: BackendId): Promise<void>;
+    touchSession(id: number): void;
+    closeSession(id: number): void;
+    /**
+     * Transaction-safe close variant — callers already inside a
+     * `db.transaction(...)` body collect side effects into the supplied
+     * buffer and flush them with `flushEffects` after commit.
+     */
+    closeSessionInTx(id: number, effects: DeferredSessionEffects): void;
+    newEffectsBuffer(): DeferredSessionEffects;
+    flushEffects(effects: DeferredSessionEffects): void;
+    /**
+     * DB-backed lookup for the currently-bound dashboard channel_id of an
+     * active session. Returns null when the session is not active or not
+     * found. Used by dispatcher to route stream/meta/error events to
+     * whichever browser tab is currently connected, instead of the stale
+     * event.channel captured when the user POSTed their message.
+     */
+    getActiveChannelIdForSession(sessionId: number): string | null;
+    isCloseCommand(content: string): boolean;
+    getDmPlatformsWithNewMessages(): string[];
+    getUnsummarizedDmMessages(platform: string): {
+        role: string;
+        content: string;
+        timestamp: string;
+        metadata?: string | null;
+    }[];
+    getPreviousDmSummary(platform: string): string | null;
+    saveDmSummary(platform: string, summary: string, messageCount: number): void;
+}
+/** Interface for MessageRecorder — records messages to DB. Returns
+ *  `true` when the row was persisted, `false` when the INSERT/UPDATE
+ *  transaction rolled back (logged internally). The atomic
+ *  INSERT-plus-touch contract means callers no longer need to pair
+ *  `recordMessage` with a separate `touchSession` — on success the
+ *  session's `last_message_at` and `message_count` are already in sync
+ *  with the `messages` row; on failure, neither moves. */
+export interface IMessageRecorder {
+    recordMessage(params: {
+        sessionId: number;
+        role: "user" | "assistant" | "system";
+        content: string;
+        platform: string;
+        senderId?: string;
+        backend?: BackendId;
+        modelId?: string;
+        metadata?: Record<string, unknown>;
+        notificationDispatchId?: string | null;
+    }): boolean;
+}
+/** Interface for AuditLogger — implemented in Phase 1D */
+export interface IAuditLogger {
+    logAction(params: {
+        event: Event;
+        model: string;
+        costUsd: number;
+        usage: AgentResult["usage"];
+        modelUsage: AgentResult["modelUsage"];
+        durationMs: number;
+        numTurns: number;
+        trigger: "reactive" | "autonomous";
+        backend?: BackendId;
+        costSource?: AgentResult["costSource"];
+        /**
+         * Whether the agent made at least one PUT/PATCH call to /api/context/*.
+         * Used for observer-event observability — see Phase 6 of
+         * docs/observer-context-update-fix.md.
+         */
+        contextUpdated?: boolean;
+        /**
+         * Number of server-side advisor tool invocations. Populated by the Claude
+         * Code backend when the `advisor_20260301` tool is active; otherwise 0.
+         */
+        advisorCallCount?: number;
+        /**
+         * STAGE-C-DM-FRESHNESS-PLAN §Task 4 — DM-only freshness telemetry.
+         * Captured for DM dispatches so the dashboard's
+         * `dm_freshness_metrics` view can roll up resume rate, snapshot lag,
+         * and refetch-hit rate without a separate table. Persisted into
+         * `agent_actions.detail` as `{ dm_freshness: {...} }`.
+         */
+        dmFreshness?: {
+            resumed: boolean;
+            agentLogLagMinutes: number;
+            loudWritesSinceSessionStart: number;
+            quietWritesSinceSessionStart: number;
+            refetchedToday: boolean;
+            triggerMatched: boolean;
+        };
+    }): void;
+    logSkip(event: Event, reason: string, trigger: "reactive" | "autonomous"): void;
+    logError(event: Event, error: Error, trigger: "reactive" | "autonomous", context?: {
+        durationMs?: number;
+        backendId?: BackendId;
+        modelId?: string;
+        failureKind?: string;
+        failureCode?: string;
+    }): void;
+    /**
+     * Chat-attachments Phase 1 — log an inbound (user→agent) or outbound
+     * (agent→user) attachment upload to `agent_actions` so the dashboard
+     * events/cost views surface them alongside agent turns.
+     */
+    logAttachment(params: {
+        direction: "inbound" | "outbound";
+        attachmentId: string;
+        mimeType: string;
+        sizeBytes: number;
+        provenance: string;
+        originalFilename: string;
+    }): void;
+    /**
+     * Messaging bang-commands (`!stop` / `!start` / `!cost` / `!report`) —
+     * write an `agent_actions` row with `action_type='bang_command'` so the
+     * audit trail covers every owner control message, including paused-decline
+     * non-bang DMs. See docs/design/backlog/messaging-bang-commands.md §6.6.
+     */
+    logBangCommand(event: MessageEvent, detail: BangCommandDetail): void;
+}
+/**
+ * Audit detail for `bang_command` rows. `status` distinguishes:
+ *   - `ok`         — recognised + handler ran successfully
+ *   - `skipped`    — recognised but no-op (e.g. `!stop` while already paused)
+ *   - `unknown`    — bang-prefixed but no matching key (not while paused)
+ *   - `paused_decline` — any DM declined while paused (bang or non-bang)
+ *
+ * Map to `agent_actions.result` per §6.6 (ok→success, skipped/paused_decline
+ * →skipped, unknown→failed).
+ */
+export interface BangCommandDetail {
+    command: string;
+    status: "ok" | "skipped" | "unknown" | "paused_decline";
+    [extra: string]: unknown;
+}
+export type TriggerHourlyCheckSkipReason = "morning_routine_active" | "hourly_check_in_progress" | "below_threshold" | "setup_incomplete" | "setup_in_progress" | "vault_degraded" | "user_paused" | "gate_stage0_silent" | "gate_stage2_log_only";
+export type SetupMode = "initial" | "update";
+export interface TriggerHourlyCheckOptions {
+    force?: boolean;
+    /** Optional model hint — injected as `requestedModel` on the enqueued
+     *  routine.hourly_check event so the user can force an Opus run from
+     *  /api/agent/run-now without touching process_backend_config. */
+    requestedModel?: "sonnet" | "opus";
+}
+export interface TriggerHourlyCheckResult {
+    status: "queued" | "skipped";
+    reason?: TriggerHourlyCheckSkipReason;
+    pendingCount?: number;
+    minObservations: number;
+    forced: boolean;
+    /**
+     * cost-reduction-structural §B — populated whenever the gate ran
+     * (any mode). Mirrors what was logged to `agent_actions` so the
+     * cron caller's metrics path can attribute without a re-read.
+     */
+    gateStage?: "stage0_silent" | "stage2" | "stage3";
+    /** Effective stage actually executed when mode!=off. */
+    appliedStage?: "stage0_silent" | "stage2_log_only" | "stage3" | "stage3_shadow";
+    gateMode?: "off" | "shadow" | "live";
+    gateReason?: string;
+}
+/**
+ * cost-reduction-structural §B — extract the JSON verdict from a
+ * Stage 2 triage response. The contract is strict: a single line
+ * matching `{ "action": "log_only" | "escalate", ... }`. Anything else
+ * — empty output, prose around the JSON, missing fields, malformed JSON
+ * — falls back to `failed` so the caller cautiously escalates rather
+ * than silently silencing.
+ */
+export declare function parseStage2Verdict(output: string): "log_only" | "escalate" | "failed";
+export interface InFlightExecutionInfo {
+    kind: "session_chain" | "routine" | "scheduled_task";
+    key?: string;
+    id?: number;
+    taskType?: string;
+    detail?: string;
+}
+export declare class EventDispatcher {
+    private readonly eventBus;
+    private readonly agentRouter;
+    private readonly contextBuilder;
+    private readonly getTaskFlow;
+    private readonly notificationMgr;
+    private readonly sessionMgr;
+    private readonly messageRecorder;
+    private readonly audit;
+    private readonly db;
+    private readonly config;
+    private readonly todayWriteLock?;
+    private readonly services?;
+    private readonly roadmapWriteLock?;
+    private readonly writeTracker?;
+    private readonly reactiveSem;
+    private readonly autonomousSem;
+    private readonly hasMessageBackendMetadataColumns;
+    private shutdown;
+    private readonly shutdownAwaiters;
+    private signalDetector;
+    private dashboardStream;
+    /**
+     * Docs-QA citation lookup. Wired at startup via
+     * `setDocsCitationLookup`; null elsewhere so this module stays tree-
+     * shakable for tests that don't construct the docs indexer. The
+     * dispatcher only consults it when `isDocsQAMessage(event)` is true,
+     * so a null lookup never affects chat / DM / routine flows.
+     */
+    private docsCitationLookup;
+    private authRecovery;
+    private authHealthMonitor;
+    /**
+     * Messaging bang-commands registry — short, exact-match owner controls
+     * (`!stop` / `!start` / `!cost` / `!report`) intercepted in
+     * `handleMessage` before any agent backend is invoked. Optional so tests
+     * that build a dispatcher without the registry continue to pass; when
+     * null, all DMs flow straight to the agent path.
+     *
+     * Spec: docs/design/backlog/messaging-bang-commands.md
+     */
+    private bangCommandRegistry;
+    /**
+     * Current setup mode — scope-agnostic flag that survives internal
+     * direct-message session refresh (day boundary, stale flag, etc). Previously this
+     * was a `Map<sessionId, mode>` keyed by `conversation_sessions.id`, but the
+     * session row is routinely closed and recreated by `getOrCreateDm()` when
+     * a loud prompt-context change marks active DMs stale, which orphaned the
+     * map entry and silently dropped the setup flow back to the generic DM prompt.
+     * A single nullable flag is the right
+     * granularity because the dashboard owner-DM scope is singular.
+     *
+     * Persisted to runtime_state so setup mode survives daemon restart. Without
+     * persistence, an update-flow setup conversation that crashes mid-flight
+     * would re-open the gate on restart and re-introduce the stale-session race.
+     *
+     * No auto-expiry. The original 30-minute safety net turned out to be
+     * actively harmful: it fired DURING legitimate long setup conversations
+     * (which is exactly the pattern that triggered the original report) and
+     * re-opened the bug it was trying to guard. Setup mode is only cleared by
+     * explicit `clearSetupMode()` from `/setup/save-rules`.
+     */
+    private currentSetupMode;
+    /** Per-session FIFO gate: owner DMs share one key; thread sessions
+     *  keep their own lane. SCHEDULED-DM-IMPLEMENTATION-PLAN §3.6 — also
+     *  used by `scheduled.dm` to acquire BOTH owner-facing scopes in
+     *  lex-sorted (deadlock-free) order. */
+    private readonly sessionGates;
+    /** Dedup guard: timestamp of the last roadmap_refresh emission */
+    private lastRoadmapRefreshEmitMs;
+    private morningRoutineInProgress;
+    private hourlyCheckInProgress;
+    /**
+     * P22 §3.4 — wired by `index.ts` after the daemon's data dir + skills root
+     * are known. Returns a `{runId, runToken, workdirPath, targetSkills}` tuple
+     * the optimizer routine then runs against. Injected as a callback so the
+     * dispatcher does not import the workdir module directly (avoids a cycle
+     * with SkillsCompiler / SecretBroker).
+     */
+    private materializeOptimizerWorkdir;
+    private teardownOptimizerWorkdir;
+    setSkillCurationHooks(hooks: {
+        materialize: (opts?: {
+            manual?: boolean;
+            targetSkillsOverride?: string[];
+        }) => Promise<{
+            runId: string;
+            runToken: string;
+            workdirPath: string;
+            targetSkills: string[];
+        }>;
+        teardown: (workdirPath: string) => void;
+    }): void;
+    private static readonly COST_CAP_SQL;
+    /** Map `turn_token → sessionId` for in-flight turns. The API layer
+     *  calls `validateAttachmentTurnToken(token)` to authorise
+     *  `POST /api/chat/outbound-attachments`; the entry is cleared in a
+     *  `finally` so orphan tokens don't survive past the turn that
+     *  spawned them. */
+    private readonly activeTurnTokens;
+    /** Injected lazily via `setAttachmentStore` — optional for tests
+     *  and older code paths that don't wire the store. When null, the
+     *  dispatcher skips attachment staging + outbound collection. */
+    private attachmentStore;
+    /** Injected lazily via `setDelegatedSyncRefresh` — optional. When null,
+     *  hourly check fires without first refreshing delegated-mode snapshots,
+     *  matching the pre-Phase-9 behaviour. Wired in production when at
+     *  least one integration is in delegated mode. See
+     *  `docs/design/appendices/delegated-sync-opt-in.md` and the worker's
+     *  `runDisabledCadencesForHourlyCheck` method. */
+    private delegatedSyncRefresh;
+    /** Injected lazily via `setVoiceTranscriber` — optional. When null,
+     *  inbound audio attachments fall back to the path-only prompt block
+     *  exactly as they did before the local-Whisper layer landed. See
+     *  `docs/design/appendices/voice-transcription.md`. */
+    private voiceTranscriber;
+    /**
+     * Notify-dedup tracking — set of correlationIds for in-flight events
+     * that have already invoked `POST /api/notify` from inside the agent
+     * run. The `/api/notify` route calls `markEventNotified` (via api-deps)
+     * on success, and `processResult` consumes the entry with `Set.delete`.
+     * When present, the implicit "final assistant text → DM" forward is
+     * suppressed — preventing the duplicate-notification bug where the LLM
+     * sends both an explicit notify and a non-empty closing turn.
+     *
+     * In-memory only; single-daemon scope. Cleanup contract:
+     *   - Success path: `processResult.delete()` removes the entry exactly
+     *     once per event run (every dispatch path funnels into it).
+     *   - Throw path: `handleError.delete()` is the defense-in-depth
+     *     cleanup for entries left when execution threw before reaching
+     *     `processResult`.
+     *   - Retry path: `executeWithRetry` reuses the same correlationId
+     *     across attempts, but only one `processResult` call closes the
+     *     run, so the marker is consumed exactly once.
+     *
+     * Cross-event safety: each `createEvent()` mints a fresh UUID, so a
+     * stale entry surviving both cleanup paths cannot poison a later
+     * unrelated event run. Scheduler-resurrected events (scheduler.ts
+     * carries `row.correlation_id` when present) intentionally inherit
+     * the same id, which is the correct behaviour — they continue the
+     * same logical run.
+     */
+    private readonly notifiedEvents;
+    constructor(eventBus: EventBus, agentRouter: IAgentRouter, contextBuilder: IContextBuilder, getTaskFlow: GetTaskFlow, notificationMgr: INotificationManager, sessionMgr: ISessionManager, messageRecorder: IMessageRecorder, audit: IAuditLogger, db: Database.Database, config: AgentConfig, todayWriteLock?: TodayWriteLockManager | undefined, services?: ServiceRegistry | undefined, roadmapWriteLock?: RoadmapWriteLockManager | undefined, writeTracker?: AgentWriteTracker | undefined);
+    private loadPersistedSetupMode;
+    /**
+     * B-007 §5.8 — compose the final prompt by loading the task-flow
+     * template and appending the vault policy-files block (rules/*.md,
+     * routines/<cadence>.md, custom routine file, etc.). Centralised
+     * here so every dispatch path sees the same policy bundle.
+     */
+    private assemblePrompt;
+    /**
+     * Policy-file prompt assembly must not fall back to `<dataDir>/context`
+     * while degraded. Reactive sessions still run so the user can repair the
+     * vault, but the prompt must not silently inject stale rulebooks from a
+     * legacy location.
+     */
+    private getPromptPolicyContextDir;
+    /** Set the SignalDetector for implicit feedback collection from user messages. */
+    setSignalDetector(detector: SignalDetector): void;
+    /** Set the dashboard stream adapter for real-time response streaming. */
+    setDashboardStream(adapter: IDashboardStream): void;
+    /**
+     * Wire the docs-QA citation lookup. Called once at startup from
+     * `index.ts` after the docs indexer is built. The dispatcher uses it
+     * for the persistence-side `validateAndRewrite` pass on docs_qa
+     * assistant output (see DOCS_QA_B7_DESIGN.md §11.1) — chat / DM /
+     * routine paths never touch it.
+     */
+    setDocsCitationLookup(lookup: DocsCitationLookup): void;
+    /** Chat-attachments Phase 1 — inject the shared AttachmentStore. */
+    setAttachmentStore(store: AttachmentStore): void;
+    /** Inject the local-Whisper voice transcriber. Optional — when unset,
+     *  inbound audio attachments are passed to the backend with a path-only
+     *  reference (the pre-feature behaviour). */
+    setVoiceTranscriber(transcriber: VoiceTranscriber): void;
+    /**
+     * Inject the delegated-sync refresh callback. Called from
+     * `triggerHourlyCheck` before the gate decision so any cadence the
+     * operator left opted-OUT (post-Phase-9 default) populates fresh
+     * Gmail / Notion observations the agent can then consume.
+     *
+     * Wired as a thunk rather than a worker reference so the dispatcher
+     * stays decoupled from the observers layer and the live worker
+     * instance can be re-registered (integration mode flips) without the
+     * dispatcher holding a stale reference.
+     *
+     * Pass `null` to detach (e.g. when no delegated integration exists).
+     * The hourly check then proceeds without a refresh — equivalent to the
+     * pre-injection behaviour.
+     */
+    setDelegatedSyncRefresh(fn: (() => Promise<void>) | null): void;
+    /**
+     * Authorise an `X-Turn-Token` for POST /api/chat/outbound-attachments.
+     * Returns the DB session id bound to that token while a turn is still
+     * running, null otherwise.
+     */
+    validateAttachmentTurnToken(token: string): {
+        sessionId: number;
+    } | null;
+    /** Internal — issue a turn token bound to a session. Cleared by
+     *  `releaseAttachmentTurnToken` in a `finally`. */
+    private issueAttachmentTurnToken;
+    private releaseAttachmentTurnToken;
+    /**
+     * Stage inbound attachments into `<sessionDir>/_attachments/` via
+     * hard-link (or copy on EXDEV). Returns the rows that were actually
+     * staged — callers feed these into the prompt-block builder.
+     */
+    private stageInboundAttachments;
+    /**
+     * Read the `messages.id` that was just persisted for this session.
+     * Used to bind inbound attachment rows to the user message (so the
+     * history endpoint can re-serve them) and outbound attachments to the
+     * assistant message. `better-sqlite3`'s `last_insert_rowid()` is
+     * per-connection and authoritative right after `recordMessage` returns
+     * (its transaction has committed synchronously).
+     */
+    private readLastInsertedMessageId;
+    /**
+     * Resolve the `UserBangCommand` row that produced this event, when one
+     * applies. The dispatcher consults the row to apply the per-command
+     * skill set and instruction body to the session workdir before the
+     * agent runs. Returns `null` for non-bang messages, for bang events
+     * whose row was deleted between enqueue and dispatch, and for events
+     * whose `data.customBangCommand.id` is missing or malformed (defense
+     * against a future event constructor that forgets to set it).
+     */
+    private lookupCustomBangCommandForEvent;
+    /**
+     * Run local-Whisper transcription on every audio attachment in `rows`.
+     * Cached transcripts are returned without re-running inference. Returns
+     * an empty map when the transcriber is unset, when no rows are audio,
+     * or when every transcription failed — callers always render the path
+     * even if the transcript is missing.
+     */
+    private transcribeAttachments;
+    /**
+     * Compose the "[Attached files]" prompt block that the dispatcher
+     * appends to the task-flow body for turns with inbound attachments.
+     * Kept in the dispatcher (not in prompts.ts) because the attachment
+     * rows are local state for this turn only.
+     */
+    private buildAttachmentPromptBlock;
+    /**
+     * Phase 5: set the auth recovery manager so owner DMs like `/auth fix codex`
+     * can be intercepted before reaching the agent backend.
+     */
+    setAuthRecovery(recovery: import("./backends/auth-recovery.js").AuthRecovery): void;
+    /**
+     * Phase 5 (M2 fix): set the AuthHealthMonitor so `/auth status` can
+     * render the full summary in-DM instead of a pointer to the dashboard.
+     */
+    setAuthHealthMonitor(monitor: import("./backends/auth-health-monitor.js").AuthHealthMonitor): void;
+    /**
+     * Wire the bang-command registry so owner DMs are intercepted before the
+     * agent path. See docs/design/backlog/messaging-bang-commands.md.
+     */
+    setBangCommandRegistry(registry: import("./bang-commands/registry.js").BangCommandRegistry): void;
+    /** Main event processing loop */
+    run(): Promise<void>;
+    stop(): void;
+    /**
+     * Enter setup mode. Called from `POST /setup/start` so the warm gate
+     * engages the moment the user opens the dashboard setup flow — before any
+     * agent turn runs — so concurrent hourly_check / morning routine / scheduled
+     * wake work cannot race with the setup conversation. Persisted to
+     * `runtime_state` so the flag survives daemon restart.
+     */
+    beginSetupMode(mode: SetupMode): void;
+    /**
+     * Exit setup mode. Called from `POST /setup/save-rules` on success.
+     * Idempotent.
+     */
+    clearSetupMode(): void;
+    /** Observable getter, primarily for tests and the onPromptContextChanged gate. */
+    getCurrentSetupMode(): SetupMode | null;
+    /**
+     * Management Mode Phase 2 — expose in-flight executions so
+     * `/api/setup/migrate-context` can refuse to start while real work is
+     * still running, not just while sessions remain marked active.
+     */
+    getInFlightExecutions(): InFlightExecutionInfo[];
+    /**
+     * Gate for autonomous background work (cron routines, hourly_check,
+     * scheduled wake tasks, startup catchup, calendar-poller reactive events).
+     *
+     * Two layers:
+     *  - **Cold gate**: `rules/management.md` must exist. Before initial setup
+     *    there is no policy document, no user/profile.md, no today.md — running
+     *    routines would produce garbage AND, crucially, any loud prompt-context
+     *    write from such a routine can trigger
+     *    `onPromptContextChanged -> markActiveDmSessionsStale`, which destroys
+     *    the in-flight setup conversation on the next user turn.
+     *  - **Warm gate**: while a setup conversation is active (initial OR
+     *    update), pause autonomous work even though the file exists. This
+     *    covers the update flow where the rules file is present but the same
+     *    race still applies.
+     *
+     * Returns `null` when allowed, or a string reason when blocked.
+     */
+    isAutonomousAllowed(): null | "setup_incomplete" | "setup_in_progress" | "vault_degraded" | "user_paused";
+    /**
+     * Process a catchup or bootstrap event synchronously without going through
+     * the EventBus loop. Uses the same semaphore and error-handling path as the
+     * normal dispatcher.
+     */
+    processInline(event: Event): Promise<void>;
+    /** Get configured services set, rebuilding when ServiceRegistry changes. */
+    private getConfiguredServices;
+    /** Snapshot active mail accounts (§Phase 5 accounts.md materialization). */
+    private getActiveMailAccounts;
+    isReactive(event: Event): boolean;
+    /**
+     * Check whether this autonomous event should be skipped because the daily
+     * autonomous cost cap has been exceeded. Uses priority-based degradation:
+     * hourly_check (lowest priority, skipped first) → roadmap_refresh →
+     * evening_review → morning_routine (highest, last to be cut).
+     *
+     * Lower-priority events are skipped at 100% of cap; higher-priority events
+     * only at 150%+, giving headroom for the morning briefing.
+     */
+    private shouldSkipForCostCap;
+    private handleEvent;
+    private handleEventInner;
+    triggerHourlyCheck(source: string, options?: TriggerHourlyCheckOptions): Promise<TriggerHourlyCheckResult>;
+    /**
+     * cost-reduction-structural §B — pull a fresh signal snapshot and run
+     * the deterministic gate. Helper so the dispatcher's call site stays
+     * compact and tests can spy on the boundary.
+     */
+    private computeHourlyCheckGateDecision;
+    private readTodayMdSafe;
+    /**
+     * cost-reduction-structural §B — daemon-direct silent path. Used by
+     * Stage 0 and Stage 2 log-only verdicts. Consumes pending user
+     * observations + appends a single Agent Log line + records the gate
+     * verdict to `agent_actions`. The flag is reset before return.
+     */
+    private runSilentHourlyCheckPath;
+    private enqueueStage3HourlyCheck;
+    private logGateAuditRow;
+    /**
+     * cost-reduction-structural §B Stage 2 — synchronous lite-tier triage.
+     * Builds a `routine.hourly_check.triage` RoutineEvent and runs it
+     * inline through the agent router (NOT the EventBus, so the result
+     * is available before we decide whether to silence or escalate).
+     *
+     * The agent contract is JSON-only output (`{ "action": "log_only" |
+     * "escalate", "reason": "..." }`); on parse failure we return
+     * `'failed'` and the caller treats that as cautious escalate.
+     *
+     * Tool/turn clamp (defense-in-depth):
+     *   - `allowedToolsOverride: []` removes every tool from the SDK's
+     *     allowlist for the spawn. Stage 2 has nothing to do but emit a
+     *     JSON line; the design's "no write tools" rule is enforced here
+     *     instead of relying on the prompt alone.
+     *   - `maxTurns: 1` caps the spawn at a single assistant turn. Even
+     *     if a future prompt change accidentally invites tool use, the
+     *     spawn cannot loop. Codex/Gemini have no per-spawn `allowedTools`
+     *     surface today (acknowledged gap in `agent-core.ts`); the
+     *     `maxTurns` cap and process_backend_config envelope are the
+     *     remaining safety floor on those backends.
+     */
+    private runStage2Triage;
+    /**
+     * Advisory check: is a morning routine execution or retry currently in
+     * progress? Synchronous (no async) so callers can atomically gate other
+     * work without introducing microtask race windows.
+     *
+     * C5 fix: detects retry rows via `task_context.routine='morning_routine'`
+     * instead of a fragile `task_description LIKE 'Morning routine retry%'`
+     * substring match. The schedule row's task_context is written by
+     * scheduleMorningRetry() below, so this JSON path is authoritative even
+     * if the human-readable description string later changes.
+     *
+     * Public (not private) because Phase 4's `AuthHealthMonitor.checkAll()`
+     * shares the same skip-while-morning-routine-active invariant as the
+     * hourly check, and injects this method as an option so a probe tick
+     * running concurrently with morning routine can no-op cleanly. See
+     * `docs/design/09-safety-cost.md` §9.5.4.
+     */
+    isMorningRoutineActive(): boolean;
+    private dispatchSafe;
+    private dispatch;
+    private getMessageExecutionKey;
+    private runWithSessionGate;
+    /**
+     * Acquire multiple session gates sequentially in lexicographic order
+     * before invoking `fn`. Used by the `scheduled.dm` dispatch path to
+     * serialize a briefing behind ALL owner-facing DM scopes
+     * (messaging-app DMs and dashboard chat).
+     *
+     * SCHEDULED-DM-IMPLEMENTATION-PLAN §3.6.
+     */
+    private runWithSessionGates;
+    /**
+     * Morning routine execution with pre-processing (lock, rotateDayFiles,
+     * prompt variant selection). Only called for routine === "morning_routine".
+     * Tier is resolved by BackendRouter from process-key defaults or user config.
+     */
+    private executeMorningRoutine;
+    /**
+     * Read the operator-or-preset configured tier for `routine.morning_routine`
+     * so the non-configurable `morning_routine_initial` variant can mirror it.
+     * Returns null when no row exists (fresh install before the setup wizard
+     * applies a preset) or when the pinned model isn't in the registry — the
+     * caller falls back to the router's default tier in those cases.
+     */
+    private inferConfiguredMorningRoutineTier;
+    private emitPostMorningCatchups;
+    /**
+     * Schedule a retry of the morning routine when today.md wasn't generated.
+     *
+     * Uses the existing agent_schedule → ScheduleWatcher path rather than
+     * re-enqueuing on the EventBus directly. Benefits:
+     * 1. Retry persists across daemon restarts.
+     * 2. Shares the same Opus cost-limit and concurrency gates.
+     * 3. Back-off delay is enforced by scheduled_for timestamp.
+     *
+     * Retry policy: exponential back-off (5 min → 10 min → 15 min), max 3
+     * attempts. After the 3rd failure, send a critical notification to
+     * the user and stop retrying.
+     *
+     * Retry count is tracked via `event.data.retryCount` on the RoutineEvent.
+     * On the first failure the count comes from the cron-fired RoutineEvent
+     * (undefined → 0). On subsequent failures handleMorningRoutineRetry
+     * synthesizes a new RoutineEvent carrying the previous count from the
+     * wake task's taskContext, so the chain propagates through a single
+     * code path: event.data.retryCount → +1 → task_context.retryCount
+     * → next event.data.retryCount → ...
+     *
+     * Dedup protects against pathological cases:
+     *  - M1: another retry is already pending/running → skip
+     */
+    private scheduleMorningRetry;
+    private buildRepositoryRunPrompt;
+    private prepareRepositoryRunSessionDir;
+    private executeRepositoryRunTask;
+    /**
+     * Execute a scheduled task with the model specified when the task was
+     * registered via POST /api/schedule.
+     *
+     * Morning-routine retry tasks take a dedicated fast path: they skip
+     * the generic scheduled.task prompt and run the *real* morning routine
+     * flow via executeMorningRoutine, so the retry carries the same rotateDayFiles
+     * / prompt selection / roadmap-refresh chain as the cron-fired path.
+     */
+    private executeScheduledTask;
+    /**
+     * Legacy git project documentation tasks used to run as autonomous Claude
+     * task-flows. That made file creation probabilistic: the backend could
+     * finish "successfully" without calling the daemon context API, or fail
+     * before receiving the `<task_context>` block. The daemon now owns these
+     * writes directly, matching the manual Daily git management buttons and
+     * the repository-management cron.
+     */
+    private executeGitProjectDocTaskIfApplicable;
+    private resolveGitProjectDocProcessKey;
+    private resolveRepositoryForGitProjectDocTask;
+    private markScheduledTaskCompleted;
+    private executeScheduledRoutine;
+    /**
+     * Handle a morning-routine retry wake task.
+     *
+     * Steps:
+     *  1. Early skip: if today.md already exists (e.g., the cron-fired
+     *     morning routine raced us to it), mark this wake task completed
+     *     without running the agent — saves one Opus session.
+     *  2. Synthesize a RoutineEvent with `event.data.retryCount` carrying
+     *     the current attempt number, so that the recursive
+     *     scheduleMorningRetry call from executeMorningRoutine can increment the
+     *     retry chain naturally via the event.data code path.
+     *  3. Invoke executeMorningRoutine — this reuses the full morning-routine flow
+     *     (rotateDayFiles, prompt selection, agent execute, post-result
+     *     today.md check, roadmap_refresh emission).
+     *  4. Mark the wake task row completed. processResult inside the
+     *     executeMorningRoutine call operates on the synthetic RoutineEvent, which
+     *     is not an AgentTaskEvent, so it does not touch scheduleId — we
+     *     must do it ourselves.
+     */
+    private handleMorningRoutineRetry;
+    private hasCurrentAgentDayTodayMd;
+    /**
+     * Inspect today.md and report its state relative to the current agent-day.
+     * Used by the post-routine retry gate so the log can distinguish between
+     * "file is missing" and "file has stale H1 date", which are different
+     * failure modes (process crash vs. format-confusion bug).
+     */
+    private diagnoseTodayMdState;
+    /**
+     * Rotate day files before Morning Routine:
+     * 1. today.md → schedule/YYYY-MM-DD.md (archive)
+     * 2. today.md → yesterday.md (rename for context injection)
+     *
+     * After this, ContextBuilder will read yesterday.md as <yesterday>
+     * and today.md will not exist (agent generates it fresh).
+     */
+    private rotateDayFiles;
+    /**
+     * Lightweight execution path — delegates tier selection entirely to the
+     * BackendRouter via process-key defaults (or user-configured
+     * `process_backend_config` overrides).  No hardcoded requestedTier.
+     */
+    /**
+     * Roadmap-refresh execution with an exclusive cross-request write
+     * lock. The lockId is surfaced to the session context as
+     * `<roadmap_write_lock_id>` so the task-flow PUT / PATCH calls can
+     * pass `X-Lock-Id` and other concurrent flows (DM handler, evening
+     * sweeper) that attempt to write `/api/context/roadmap` during the
+     * refresh receive a 409.
+     *
+     * If the lock cannot be acquired (another session is mid-write), the
+     * refresh is skipped — `emitRoadmapRefresh` will retry on the next
+     * qualifying signal (dedup window permitting). This is the correct
+     * behaviour: the holder is already producing a fresher roadmap than
+     * anything we would emit right now.
+     */
+    private executeRoadmapRefresh;
+    /**
+     * P22 §3.4 — skill curation routine. Provisions an isolated optimizer
+     * workdir, hands the runId + runToken into the agent's task context via
+     * `event.data`, and tears the workdir down regardless of success/failure.
+     *
+     * The standard `executeDefault` path produces the agent session itself —
+     * the only differences from a normal routine are: (a) the workdir is the
+     * pre-built optimizer dir (built by `materializeOptimizerWorkdir`), and
+     * (b) `executeDefault` recognises `routine.skill_curation` events and
+     * pins `allowedToolsOverride` to `SKILL_CURATION_OPTIMIZER_ALLOWED_TOOLS`,
+     * which the Claude SDK consumes verbatim and which suspends Allow-mode
+     * `bypassPermissions`. The curation API's run-token + Zod chokepoint
+     * remains the safety floor for the rare case the override is bypassed
+     * (e.g. a future backend that doesn't read `allowedTools`).
+     */
+    private executeSkillCurationRoutine;
+    private executeDefault;
+    /**
+     * Handle `/auth` prefix commands from owner DMs.
+     * Phase 5 §4.2 (fix codex, cancel), Phase 6 §5.3 (fix gemini),
+     * Phase 7 §6.1 (fix all).
+     * Returns `true` if the message was consumed (caller should return).
+     */
+    private handleAuthCommand;
+    private handleMessage;
+    /**
+     * Mark an in-flight event as having sent a user-facing notification via
+     * `POST /api/notify`. Called by the API layer when the route handler sees
+     * an `X-Pa-Event-Correlation-Id` header (auto-injected by the shim
+     * env). `processResult` consumes the entry to suppress the implicit
+     * final-text DM forward.
+     */
+    markEventNotified(correlationId: string): void;
+    /**
+     * STAGE-C-DM-FRESHNESS-PLAN §Task 4 — assemble the DM-only freshness
+     * telemetry payload that gets persisted into `agent_actions.detail`.
+     * Pulled into its own helper so the message-dispatch path stays
+     * readable and so unit tests can exercise the SQL aggregation in
+     * isolation.
+     */
+    private collectDmFreshnessTelemetry;
+    private processResult;
+    /**
+     * P6 (git-lifecycle-and-triggers.md Decision 8) — restore in-flight
+     * `git.project.retemplate` targets from backup whenever a retemplate
+     * scheduled task settles. The agent itself cannot reliably roll back
+     * its own writes (process exit, exceeded turns, backend faults), so
+     * the daemon owns rollback at the dispatcher's two terminal sites
+     * (`processResult` + `handleError`). The status grid is the source of
+     * truth for which files to restore; `finalizeRetemplate` is idempotent
+     * via the `finalizedAt` marker so calling both paths is safe.
+     */
+    private finalizeRetemplateRunIfApplicable;
+    /**
+     * Unified-repositories §4.5 — settle a `repository_management` row when
+     * a `git.project.init` / `git.project.update` event the daemon emitted
+     * for management terminates. Runs unconditionally on every event
+     * because management events live on the EventBus only (no
+     * `agent_schedule` row), so the scheduleId-guarded path can't see
+     * them; the method early-returns for any taskContext that doesn't
+     * carry management metadata.
+     *
+     * Status mapping (v1):
+     *   - `git.project.init` success → `recordManagementInitDone`
+     *   - `git.project.update` success → `recordManagementScan('ok')`
+     *     (resets `scan_failure_count`)
+     *   - either, error → `recordManagementScan('failed')`
+     *     (bumps `scan_failure_count`)
+     *
+     * `'skipped_no_activity'` is reserved for future task-flow callback —
+     * the dispatcher cannot reliably distinguish "agent decided no
+     * journal entry needed" from "agent succeeded but didn't write" here.
+     */
+    private finalizeManagementScanIfApplicable;
+    private hasRecentProactiveForwardContext;
+    private logProactiveForwardDisavowalIfMatched;
+    private formatSummaryRole;
+    private buildCrossSessionConversationHistory;
+    private shouldNotify;
+    /**
+     * Autonomous "observer" events: external-change detections that the
+     * daemon pushes into the pipeline, as opposed to user-initiated
+     * messages, cron routines, or scheduled tasks. Used for the
+     * contextUpdated observability log in processResult.
+     */
+    private isObserverEvent;
+    /**
+     * Create rolling summaries for DM conversations.
+     * Called at 4 AM (day boundary) before morning routine.
+     *
+     * Session-independent: queries messages directly from the DB regardless
+     * of which session they belong to. Does NOT expire active sessions —
+     * session lifecycle is handled by getOrCreateDm's day boundary check.
+     *
+     * Rolling summary: previous summary + new messages → new summary.
+     * This prevents unbounded growth (summarizing days of history each time).
+     *
+     * Threshold gate: only runs AI summarization when accumulated messages
+     * since the LAST summary exceed the threshold (> 30 messages or > 5000
+     * chars of raw text). Below threshold, nothing is saved — the message
+     * count accumulates across days until the threshold is reached.
+     */
+    summarizeDmSessions(): Promise<void>;
+    /** Delegate to shared isRoadmapStale utility. */
+    isRoadmapStale(maxAgeDays?: number): boolean;
+    /**
+     * Emit a roadmap_refresh routine event.
+     * Dedup guard: skips if emitted within the last 5 minutes unless
+     * `options.bypassDedup` is true. Dashboard-initiated regeneration is
+     * the one legal caller that may bypass dedup; all internal call-sites
+     * honor it so a burst of signals (flight + hotel confirmations in the
+     * same minute) collapses into a single refresh.
+     */
+    emitRoadmapRefresh(source: string, options?: {
+        bypassDedup?: boolean;
+    }): void;
+    private localDateTimeToUtcMs;
+    private getTimeZoneOffsetMinutes;
+    private getLocalDateParts;
+    private compareLocalDateParts;
+    private isRetryable;
+    /**
+     * Defense-in-depth retry wrapper around BackendRouter.execute().
+     *
+     * **Primary retry responsibility lives inside each BackendCore** (§12/§13).
+     * Quota errors, timeouts, and auth failures are all normalized into
+     * BackendDecisiveFailure / BackendQuotaError before they reach this layer.
+     * The BackendRouter handles fallback on decisive failures.
+     *
+     * This outer loop exists solely as a safety net for raw 5xx errors that
+     * somehow escape the BackendCore → Router chain (e.g., an unexpected HTTP
+     * error from the SDK transport layer). In practice it almost never fires.
+     */
+    private executeWithRetry;
+    private handleError;
+    /**
+     * Best-effort inline error to the dashboard tab whose POST triggered
+     * this event. `DashboardAdapter` is `notificationEligible=false`, so
+     * the normal `notificationMgr.send` path skips it — without this hook
+     * the browser sees the request accepted (200 OK), watches nothing
+     * happen, and hits the 120s waiting timeout with no explanation. We
+     * target the originating channel id; if the tab already reconnected
+     * with a new UUID the adapter silently drops, which matches the
+     * chat_error semantics.
+     */
+    private notifyDashboardError;
+    private extractQuotaError;
+    private formatQuotaMessage;
+    private formatBackendLabel;
+    private resolveQuotaResetAtMs;
+    /**
+     * DELEGATED-MODE-V2-DESIGN.md §4.5 — at every DM dispatch, consult the
+     * cached probe for delegated integrations whose effective backend
+     * matches the session backend. Surfaces a one-shot DM (deduped via
+     * `runtime_state`) when the cached probe says required capabilities
+     * are no longer present.
+     *
+     * The consult itself is synchronous DB-only work (cheap on the hot
+     * path). The DM dispatch is fire-and-forget so the agent's response
+     * latency is not gated on Slack/Telegram round-trips. Per-warning
+     * dispatch failures are swallowed so a flaky messaging adapter never
+     * breaks the user's actual DM.
+     */
+    /**
+     * Phase 1 of the §4.5 health check — synchronous cache consult only.
+     * Returns the warnings the dispatcher must surface this turn (or `[]`
+     * when nothing is broken / setup mode is active / the consult itself
+     * threw). Recovery markers are cleared inline by the consult helper, so
+     * the caller does not have to track them.
+     *
+     * Split from the dispatch step so the actual DM (and its messages-table
+     * persist) fires AFTER the dispatcher has recorded the inbound user
+     * message — otherwise the warning row's `CURRENT_TIMESTAMP` lands before
+     * the user-message row's, which makes `chat_meta` history reload reorder
+     * the bubbles (warning above user) and a one-time visual flicker leaks
+     * to the user. See `runDelegatedConnectorWarningDispatch` below.
+     */
+    private consultDelegatedConnectorWarnings;
+    /**
+     * Phase 2 of the §4.5 health check — asynchronous DM dispatch + post-
+     * delivery bookkeeping (throttle marker + dashboard-channel persist).
+     * Caller invokes this AFTER the user message is recorded so the DM's
+     * messages-table row carries a strictly-later `CURRENT_TIMESTAMP`
+     * (preserves pre-reconcile chat order on the dashboard).
+     */
+    private runDelegatedConnectorWarningDispatch;
+}
+//# sourceMappingURL=dispatcher.d.ts.map