@aitne/daemon 0.1.0

package/dist/core/dispatcher.js

@@ -0,0 +1,4378 @@
+import { EventPriority, createEvent, getAgentDayDateStr, getAgentDayBoundsUtc, isBackendId, isDocsQAMessage, isMessageEvent, isRoutineEvent, isAgentTaskEvent, isScheduledDmEvent, isScheduledEvent, isKnowledgeImportEvent, parseSqliteUtcMs, formatSqliteDatetime, resolveProcessKey, } from "@aitne/shared";
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync, } from "node:fs";
+import { join } from "node:path";
+import { CONTEXT_RELATIVE_PATHS } from "./context-paths.js";
+import { getContextDir, isRoadmapStale } from "../config.js";
+import { appendPolicyBlocks, createPromptInjectionBudget, } from "./policy-files.js";
+import { appendReviewContextBlocks } from "./review-context.js";
+import { anyMcpServerEnabled } from "../services/mcp/registry.js";
+import { OWNER_DM_SCOPE, OWNER_SCOPE_KEY, DASHBOARD_CHAT_SCOPE, DASHBOARD_SCOPE_KEY, getConversationScope, } from "../messaging/constants.js";
+import { upsertOwnerChannel } from "../messaging/owner-channels.js";
+import { logInvalidCitations, validateAndRewrite, } from "./docs/citation-validator.js";
+import { cleanupSessionWorkdir, ensureBackendMaterialized, ensureSessionWorkdir, getSessionWorkdirPath, syncAllUserSkills, buildConfiguredServices, } from "./workdir.js";
+import { SessionGateRegistry } from "./session-gate.js";
+import { Semaphore } from "./semaphore.js";
+import { consumeObservations, getPendingCount, getPendingObservations } from "../db/observations.js";
+import { computeHourlyCheckSignals } from "../db/hourly-check-signals.js";
+import { buildGateAuditDetail, decideStage, renderGateDecisionBlock, } from "../scheduler/hourly-check-gate.js";
+import { appendAgentLogLine } from "./today-direct-writer.js";
+import { readIntegrations } from "../db/integrations-store.js";
+import { getRepository, getRepositoryByLocalPath, recordManagementInitDone, recordManagementScan, selectGithubRepoSlugs, } from "../db/repositories-store.js";
+import { runRepositoryManagementInit, runRepositoryManagementScan, } from "./repository-management-docs.js";
+import { consultDelegatedConnectorHealth, markSignoutWarned, renderSignoutDm, } from "./delegated-connector-health.js";
+import { isDegraded as readDegradedMode, isUserPaused, } from "../db/runtime-state.js";
+import { finalizeRetemplate } from "./template-store.js";
+import { countContextWritesInWindow, didRefetchTodayDuringTurn, matchesRecentActivityTrigger, } from "./dm-freshness-metrics.js";
+import { deleteRuntimeState, readRuntimeState, writeRuntimeState, } from "../db/runtime-state.js";
+import { BackendDecisiveFailure, BackendQuotaError, } from "./agent-core.js";
+import { BackendRouterHandledError, } from "./backends/backend-router.js";
+import { maybeTriggerRoadmapRefresh } from "./schedule-insert-helper.js";
+import { flushPendingTodayRefresh } from "./drift-effects.js";
+import { isProactiveForwardMetadata, parseMessageMetadata, } from "./channel-timeline.js";
+import { randomUUID } from "node:crypto";
+import { findRegisteredModel, getModelLabel } from "./backends/model-registry.js";
+import { parseGeminiAuthCode } from "./backends/auth-recovery.js";
+import { tryHandle as tryHandleBangCommand } from "./bang-commands/registry.js";
+import { CUSTOM_BANG_COMMAND_SOURCE, createUserBangCommandEvent, getUserBangCommandById, resolveCommandSkillSlugs, } from "./bang-commands/user-commands.js";
+import { createLogger } from "../logging.js";
+const logger = createLogger("dispatcher");
+/**
+ * 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 const SKILL_CURATION_OPTIMIZER_ALLOWED_TOOLS = [
+    "Read",
+    "Bash(curl http://localhost:8321/api/skill-curation/*)",
+];
+/**
+ * Unwrap the partial-run context the audit logger needs for a failed
+ * event. The dispatcher owns wall-clock timing (caller passes
+ * `durationMs`); the rest is recovered from `BackendRouterHandledError`
+ * if the throw came through the router. For non-router errors we still
+ * record the duration so the dashboard "Duration" column is honest.
+ */
+function buildLogErrorContext(err, durationMs) {
+    if (err instanceof BackendRouterHandledError) {
+        const cause = err.cause;
+        const failure = cause instanceof BackendQuotaError
+            ? {
+                backendId: cause.backendId,
+                kind: "quota",
+                code: cause.originalCode,
+            }
+            : cause instanceof BackendDecisiveFailure
+                ? { backendId: cause.backendId, kind: cause.kind }
+                : { backendId: err.mainFailure.backendId };
+        return {
+            durationMs,
+            backendId: failure.backendId,
+            ...(failure.kind ? { failureKind: failure.kind } : {}),
+            ...(failure.code ? { failureCode: failure.code } : {}),
+        };
+    }
+    if (err instanceof BackendQuotaError) {
+        return {
+            durationMs,
+            backendId: err.backendId,
+            failureKind: "quota",
+            failureCode: err.originalCode,
+        };
+    }
+    if (err instanceof BackendDecisiveFailure) {
+        return {
+            durationMs,
+            backendId: err.backendId,
+            failureKind: err.kind,
+        };
+    }
+    return { durationMs };
+}
+function parseRepositoryRunTaskContext(taskCtx) {
+    if (!taskCtx || typeof taskCtx !== "object")
+        return null;
+    const ctx = taskCtx;
+    if (ctx.triggerSource !== "manual"
+        && ctx.triggerSource !== "trigger_manual_fire"
+        && ctx.triggerSource !== "repository_trigger") {
+        return null;
+    }
+    if (typeof ctx.repositoryId !== "string"
+        || typeof ctx.slug !== "string"
+        || typeof ctx.prompt !== "string"
+        || (ctx.workdirMode !== "temp" && ctx.workdirMode !== "local-clone")) {
+        return null;
+    }
+    const localPath = typeof ctx.localPath === "string" && ctx.localPath.length > 0
+        ? ctx.localPath
+        : null;
+    const githubRepo = typeof ctx.githubRepo === "string" && ctx.githubRepo.length > 0
+        ? ctx.githubRepo
+        : null;
+    return {
+        triggerSource: ctx.triggerSource,
+        repositoryId: ctx.repositoryId,
+        slug: ctx.slug,
+        localPath,
+        githubRepo,
+        workdirMode: ctx.workdirMode,
+        prompt: ctx.prompt,
+        instructionMd: typeof ctx.instructionMd === "string" ? ctx.instructionMd : null,
+        timeoutMinutes: typeof ctx.timeoutMinutes === "number" ? ctx.timeoutMinutes : null,
+        ...(typeof ctx.triggerId === "string" ? { triggerId: ctx.triggerId } : {}),
+        ...(typeof ctx.triggerName === "string" ? { triggerName: ctx.triggerName } : {}),
+        ...(typeof ctx.triggerEventType === "string" ? { triggerEventType: ctx.triggerEventType } : {}),
+        ...("triggerEventPayload" in ctx ? { triggerEventPayload: ctx.triggerEventPayload } : {}),
+    };
+}
+function repositoryRunInstructionFilename(backendId) {
+    if (backendId === "codex")
+        return "AGENTS.md";
+    if (backendId === "gemini")
+        return "GEMINI.md";
+    return "CLAUDE.md";
+}
+function safeRepositoryRunDirName(slug) {
+    const safe = slug
+        .toLowerCase()
+        .replace(/[^a-z0-9._-]+/g, "-")
+        .replace(/^-+|-+$/g, "");
+    return safe || "repository";
+}
+function parseGithubRepoSlug(value) {
+    if (!value)
+        return [null, null];
+    const parts = value.split("/");
+    if (parts.length !== 2 || !parts[0] || !parts[1])
+        return [null, null];
+    return [parts[0], parts[1]];
+}
+function normalizeRepositoryClassification(value) {
+    return value === "project" ? "project" : "repo-only";
+}
+function normalizeRepositoryCategory(value) {
+    return value === "work" ||
+        value === "personal" ||
+        value === "research" ||
+        value === "client" ||
+        value === "other"
+        ? value
+        : "other";
+}
+/**
+ * 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 function parseStage2Verdict(output) {
+    const trimmed = (output ?? "").trim();
+    if (!trimmed)
+        return "failed";
+    // Tolerate code fences (```json … ```) without making them mandatory.
+    const stripped = trimmed
+        .replace(/^```(?:json)?\s*/i, "")
+        .replace(/```\s*$/i, "")
+        .trim();
+    // Find the FIRST balanced JSON object — agents occasionally emit
+    // trailing prose after the JSON line.
+    const objMatch = stripped.match(/\{[\s\S]*?\}/);
+    if (!objMatch)
+        return "failed";
+    let parsed;
+    try {
+        parsed = JSON.parse(objMatch[0]);
+    }
+    catch {
+        return "failed";
+    }
+    if (!parsed || typeof parsed !== "object")
+        return "failed";
+    const action = parsed.action;
+    if (action === "log_only" || action === "escalate")
+        return action;
+    return "failed";
+}
+const CURRENT_SETUP_MODE_STATE_KEY = "current_setup_mode";
+// English-only patterns by CLAUDE.md convention. The disavowal tripwire
+// is a numerator over a `disavowed / injected` ratio (dm-channel-timeline.md
+// §C.1) — false negatives are tolerated; non-English replies that happen to
+// disavow will simply not contribute to the numerator. Operators monitor the
+// ratio and flip `proactiveForwardForceFreshSession` on rise; that fallback
+// path is language-agnostic.
+const PROACTIVE_FORWARD_DISAVOWAL_PATTERNS = [
+    /\b(?:don't|do not) (?:recall|remember)\b/i,
+    /\bI (?:didn't|did not) (?:say|send|mention)\b/i,
+    /\breferenc(?:ing|e) what\b/i,
+    /\bwhat did .* (?:say|mean|refer)\b/i,
+];
+export class EventDispatcher {
+    eventBus;
+    agentRouter;
+    contextBuilder;
+    getTaskFlow;
+    notificationMgr;
+    sessionMgr;
+    messageRecorder;
+    audit;
+    db;
+    config;
+    todayWriteLock;
+    services;
+    roadmapWriteLock;
+    writeTracker;
+    reactiveSem;
+    autonomousSem;
+    hasMessageBackendMetadataColumns;
+    shutdown = false;
+    shutdownAwaiters = new Set();
+    signalDetector = null;
+    dashboardStream = null;
+    /**
+     * 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.
+     */
+    docsCitationLookup = null;
+    authRecovery = null;
+    authHealthMonitor = null;
+    /**
+     * 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
+     */
+    bangCommandRegistry = null;
+    /**
+     * 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`.
+     */
+    currentSetupMode = null;
+    /** 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. */
+    sessionGates = new SessionGateRegistry();
+    /** Dedup guard: timestamp of the last roadmap_refresh emission */
+    lastRoadmapRefreshEmitMs = 0;
+    morningRoutineInProgress = false;
+    hourlyCheckInProgress = false;
+    /**
+     * 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).
+     */
+    materializeOptimizerWorkdir = null;
+    teardownOptimizerWorkdir = null;
+    setSkillCurationHooks(hooks) {
+        this.materializeOptimizerWorkdir = hooks.materialize;
+        this.teardownOptimizerWorkdir = hooks.teardown;
+    }
+    static COST_CAP_SQL = `SELECT COALESCE(SUM(cost_usd), 0) as cost
+     FROM agent_actions
+     WHERE trigger = 'autonomous'
+       AND started_at >= ? AND started_at < ?`;
+    /** 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. */
+    activeTurnTokens = new Map();
+    /** 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. */
+    attachmentStore = null;
+    /** 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. */
+    delegatedSyncRefresh = null;
+    /** 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`. */
+    voiceTranscriber = null;
+    /**
+     * 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.
+     */
+    notifiedEvents = new Set();
+    constructor(eventBus, agentRouter, contextBuilder, getTaskFlow, notificationMgr, sessionMgr, messageRecorder, audit, db, config, todayWriteLock, services, roadmapWriteLock, writeTracker) {
+        this.eventBus = eventBus;
+        this.agentRouter = agentRouter;
+        this.contextBuilder = contextBuilder;
+        this.getTaskFlow = getTaskFlow;
+        this.notificationMgr = notificationMgr;
+        this.sessionMgr = sessionMgr;
+        this.messageRecorder = messageRecorder;
+        this.audit = audit;
+        this.db = db;
+        this.config = config;
+        this.todayWriteLock = todayWriteLock;
+        this.services = services;
+        this.roadmapWriteLock = roadmapWriteLock;
+        this.writeTracker = writeTracker;
+        this.reactiveSem = new Semaphore(config.maxReactiveSessions);
+        this.autonomousSem = new Semaphore(config.maxConcurrentSessions);
+        const messageColumns = new Set(this.db.pragma("table_info(messages)").map((column) => column.name));
+        this.hasMessageBackendMetadataColumns =
+            messageColumns.has("backend") && messageColumns.has("model_id");
+        // Restore setup mode from runtime_state. If the daemon crashed or was
+        // restarted during a setup conversation, the in-memory flag would be
+        // lost and autonomous work would resume mid-setup — re-opening the
+        // exact race this gate was designed to prevent.
+        this.currentSetupMode = this.loadPersistedSetupMode();
+        if (this.currentSetupMode !== null) {
+            logger.info({ mode: this.currentSetupMode }, "Restored setup mode from runtime_state — autonomous work remains paused");
+        }
+    }
+    loadPersistedSetupMode() {
+        const raw = readRuntimeState(this.db, CURRENT_SETUP_MODE_STATE_KEY);
+        if (raw && (raw.mode === "initial" || raw.mode === "update")) {
+            return raw.mode;
+        }
+        return null;
+    }
+    /**
+     * 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.
+     */
+    assemblePrompt(eventType, processKey, backendId, flags) {
+        const integrations = readIntegrations(this.db);
+        const base = this.getTaskFlow(eventType, backendId, integrations);
+        const contextDir = this.getPromptPolicyContextDir();
+        if (!contextDir) {
+            return base;
+        }
+        // B-003 Phase 3 — the `rules/mcp.md` PolicyFileRef is registered with
+        // `injectIf: ctx.flags?.mcpEnabled === true`. Compute the flag here so
+        // every dispatch path (DM, routine, scheduled task, fallback reassembly)
+        // injects the policy without each call site having to remember it.
+        const mergedFlags = {
+            ...(flags ?? {}),
+            mcpEnabled: anyMcpServerEnabled(this.db),
+        };
+        // Share a single budget across policy + review-context injection so the
+        // aggregate cap (POLICY_TOTAL_MAX_BYTES) covers both — avoids the
+        // double-accounting bug where each injector independently consumed the
+        // full cap and inflated the effective prompt-injection ceiling to 2×.
+        const budget = createPromptInjectionBudget();
+        const withPolicies = appendPolicyBlocks(base, {
+            contextDir,
+            processKey,
+            flags: mergedFlags,
+            budget,
+        });
+        return appendReviewContextBlocks(withPolicies, {
+            contextDir,
+            processKey,
+            flags: {
+                useReviewDossiers: this.config.useReviewDossiers,
+                useContextIndex: this.config.useContextIndex,
+            },
+            budget,
+        });
+    }
+    /**
+     * 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.
+     */
+    getPromptPolicyContextDir() {
+        if (readDegradedMode(this.db)) {
+            return null;
+        }
+        return getContextDir(this.config);
+    }
+    /** Set the SignalDetector for implicit feedback collection from user messages. */
+    setSignalDetector(detector) {
+        this.signalDetector = detector;
+    }
+    /** Set the dashboard stream adapter for real-time response streaming. */
+    setDashboardStream(adapter) {
+        this.dashboardStream = adapter;
+    }
+    /**
+     * 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) {
+        this.docsCitationLookup = lookup;
+    }
+    /** Chat-attachments Phase 1 — inject the shared AttachmentStore. */
+    setAttachmentStore(store) {
+        this.attachmentStore = store;
+    }
+    /** 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) {
+        this.voiceTranscriber = transcriber;
+    }
+    /**
+     * 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) {
+        this.delegatedSyncRefresh = fn;
+    }
+    /**
+     * 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) {
+        const sessionId = this.activeTurnTokens.get(token);
+        if (sessionId === undefined)
+            return null;
+        return { sessionId };
+    }
+    /** Internal — issue a turn token bound to a session. Cleared by
+     *  `releaseAttachmentTurnToken` in a `finally`. */
+    issueAttachmentTurnToken(sessionId) {
+        const token = randomUUID();
+        this.activeTurnTokens.set(token, sessionId);
+        return token;
+    }
+    releaseAttachmentTurnToken(token) {
+        this.activeTurnTokens.delete(token);
+    }
+    /**
+     * 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.
+     */
+    stageInboundAttachments(event, sessionDir) {
+        if (!this.attachmentStore || !sessionDir)
+            return [];
+        if (!event.attachments || event.attachments.length === 0)
+            return [];
+        const staged = [];
+        for (const ref of event.attachments) {
+            const row = this.attachmentStore.get(ref.id);
+            if (!row)
+                continue;
+            try {
+                this.attachmentStore.stageIntoWorkdir({ row, sessionDir });
+                staged.push(row);
+            }
+            catch (err) {
+                logger.warn({ err, attachmentId: row.id }, "Failed to stage attachment");
+            }
+        }
+        return staged;
+    }
+    /**
+     * 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).
+     */
+    readLastInsertedMessageId(sessionId) {
+        try {
+            const row = this.db
+                .prepare(`SELECT last_insert_rowid() AS id`)
+                .get();
+            if (!row || !Number.isFinite(row.id) || row.id <= 0)
+                return null;
+            // Guard against a completely unrelated insert racing in on the same
+            // connection (shouldn't happen — better-sqlite3 is sync — but cheap
+            // to verify). If the latest insert isn't for this session, abandon.
+            const check = this.db
+                .prepare(`SELECT session_id FROM messages WHERE id = ?`)
+                .get(row.id);
+            if (!check || check.session_id !== sessionId)
+                return null;
+            return row.id;
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * 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).
+     */
+    lookupCustomBangCommandForEvent(event) {
+        if (event.source !== CUSTOM_BANG_COMMAND_SOURCE)
+            return null;
+        const ref = event.data?.customBangCommand;
+        if (!ref || typeof ref !== "object")
+            return null;
+        const id = ref.id;
+        if (typeof id !== "number" || !Number.isInteger(id) || id <= 0) {
+            return null;
+        }
+        return getUserBangCommandById(this.db, id);
+    }
+    /**
+     * 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.
+     */
+    async transcribeAttachments(rows) {
+        const transcripts = new Map();
+        if (!this.voiceTranscriber || rows.length === 0)
+            return transcripts;
+        for (const row of rows) {
+            if (!this.voiceTranscriber.isAudio(row.mimeType))
+                continue;
+            try {
+                const result = await this.voiceTranscriber.transcribe({
+                    attachmentId: row.id,
+                    path: row.path,
+                    mimeType: row.mimeType,
+                });
+                if (result)
+                    transcripts.set(row.id, result);
+            }
+            catch (err) {
+                logger.warn({ err, attachmentId: row.id }, "voice transcription threw; falling back to path-only prompt");
+            }
+        }
+        return transcripts;
+    }
+    /**
+     * 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.
+     */
+    buildAttachmentPromptBlock(rows, transcripts) {
+        if (rows.length === 0)
+            return "";
+        const lines = [
+            "",
+            "[Attached files]",
+            "The user attached the following files for this turn. Paths are relative",
+            "to your working directory. Use the appropriate local tool for each",
+            "file type: images/PDFs may be readable directly, while audio/video",
+            "are staged as files for inspection, transcription, or conversion when",
+            "the active backend has suitable tools.",
+        ];
+        const transcriberEnabled = this.voiceTranscriber?.isEnabled() ?? false;
+        for (const row of rows) {
+            const rel = `_attachments/${row.safeFilename}`;
+            const size = `${Math.max(1, Math.round(row.sizeBytes / 1024))} KB`;
+            const captionPart = row.caption ? ` — caption: ${JSON.stringify(row.caption)}` : "";
+            lines.push(`- ${rel} (${row.mimeType}, ${size})${captionPart}`);
+            const transcript = transcripts?.get(row.id);
+            if (transcript) {
+                const langPart = transcript.language
+                    ? ` (lang=${transcript.language})`
+                    : "";
+                const durationPart = transcript.durationSec !== null
+                    ? `, ${transcript.durationSec.toFixed(1)}s`
+                    : "";
+                lines.push(`  Voice transcript${langPart}${durationPart}: ${JSON.stringify(transcript.transcript)}`);
+            }
+            else if (transcriberEnabled &&
+                this.voiceTranscriber?.isAudio(row.mimeType)) {
+                // Audio attachment but no transcript was produced. Could be too long,
+                // a decoder/inference failure, or a model still warming up. Surface a
+                // marker so the agent can ask the user to retype rather than silently
+                // pretending the audio was readable.
+                lines.push("  (voice transcript unavailable — audio may be too long, untranscribable, or the local model is unavailable)");
+            }
+        }
+        lines.push("", "If your reply should include a generated file (md/PDF/CSV/image/etc.),", "deliver it via the `attach` skill — write the bytes to a temp path, then", "POST /api/chat/outbound-attachments with `X-Turn-Token: $PA_TURN_TOKEN`.", "`_attachments/` is the read-only inbound staging area, not an output", "location. Never write a filesystem path into your reply and claim you", "created a file unless you actually uploaded it through that endpoint.");
+        return lines.join("\n");
+    }
+    /**
+     * Phase 5: set the auth recovery manager so owner DMs like `/auth fix codex`
+     * can be intercepted before reaching the agent backend.
+     */
+    setAuthRecovery(recovery) {
+        this.authRecovery = recovery;
+    }
+    /**
+     * 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) {
+        this.authHealthMonitor = monitor;
+    }
+    /**
+     * Wire the bang-command registry so owner DMs are intercepted before the
+     * agent path. See docs/design/backlog/messaging-bang-commands.md.
+     */
+    setBangCommandRegistry(registry) {
+        this.bangCommandRegistry = registry;
+    }
+    /** Main event processing loop */
+    async run() {
+        while (!this.shutdown) {
+            const event = await this.eventBus.get();
+            if (!event)
+                break; // EventBus was closed
+            void this.handleEvent(event); // fire-and-forget
+        }
+    }
+    stop() {
+        this.shutdown = true;
+        this.eventBus.close();
+        for (const onShutdown of this.shutdownAwaiters) {
+            try {
+                onShutdown();
+            }
+            catch {
+                // Awaiter callbacks just resolve a promise — never throw — but keep
+                // the loop defensive so one bad callback can't strand the rest.
+            }
+        }
+        this.shutdownAwaiters.clear();
+    }
+    /**
+     * 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) {
+        if (this.currentSetupMode !== null && this.currentSetupMode !== mode) {
+            logger.warn({ previous: this.currentSetupMode, next: mode }, "Setup mode replaced with a different mode while one was already active");
+        }
+        this.currentSetupMode = mode;
+        try {
+            writeRuntimeState(this.db, CURRENT_SETUP_MODE_STATE_KEY, { mode });
+        }
+        catch (err) {
+            // Non-fatal: in-memory state still protects the current process.
+            logger.warn({ err, mode }, "Failed to persist setup mode to runtime_state");
+        }
+        logger.info({ mode }, "Setup mode engaged — autonomous work paused");
+    }
+    /**
+     * Exit setup mode. Called from `POST /setup/save-rules` on success.
+     * Idempotent.
+     */
+    clearSetupMode() {
+        if (this.currentSetupMode === null) {
+            // Still attempt a best-effort runtime_state cleanup so any stray row
+            // (e.g., from a previous run that crashed before clearing) is removed.
+            try {
+                deleteRuntimeState(this.db, CURRENT_SETUP_MODE_STATE_KEY);
+            }
+            catch {
+                // ignore
+            }
+            return;
+        }
+        const mode = this.currentSetupMode;
+        this.currentSetupMode = null;
+        try {
+            deleteRuntimeState(this.db, CURRENT_SETUP_MODE_STATE_KEY);
+        }
+        catch (err) {
+            logger.warn({ err }, "Failed to clear setup mode from runtime_state (in-memory state cleared)");
+        }
+        logger.info({ mode }, "Setup mode cleared — autonomous work resumed");
+    }
+    /** Observable getter, primarily for tests and the onPromptContextChanged gate. */
+    getCurrentSetupMode() {
+        return this.currentSetupMode;
+    }
+    /**
+     * 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() {
+        const executions = [];
+        for (const key of this.sessionGates.activeKeys()) {
+            executions.push({ kind: "session_chain", key });
+        }
+        if (this.morningRoutineInProgress) {
+            executions.push({ kind: "routine", key: "morning_routine" });
+        }
+        if (this.hourlyCheckInProgress) {
+            executions.push({ kind: "routine", key: "hourly_check" });
+        }
+        const runningTasks = this.db
+            .prepare(`SELECT id, task_type, task_description
+           FROM agent_schedule
+          WHERE status = 'running'`)
+            .all();
+        for (const task of runningTasks) {
+            executions.push({
+                kind: "scheduled_task",
+                id: task.id,
+                taskType: task.task_type,
+                detail: task.task_description,
+            });
+        }
+        return executions;
+    }
+    /**
+     * 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() {
+        // Management Mode (plan §5.4): schedulers and observer-driven routines
+        // must skip ticks while the primary vault is unreachable. Reactive DM
+        // sessions still run — the user may be messaging the agent precisely
+        // to ask about the broken vault. Writes still hit the context 503 gate.
+        if (readDegradedMode(this.db)) {
+            return "vault_degraded";
+        }
+        // Owner-initiated pause via `!stop` (docs/design/backlog/messaging-
+        // bang-commands.md). Distinct from setup gates so the dashboard banner
+        // and audit rows can surface it independently. Cron callbacks consult
+        // this via `setAutonomousGate(() => dispatcher.isAutonomousAllowed())`.
+        if (isUserPaused(this.db)) {
+            return "user_paused";
+        }
+        const rulesPath = join(getContextDir(this.config, this.db), CONTEXT_RELATIVE_PATHS.rules.management);
+        if (!existsSync(rulesPath)) {
+            return "setup_incomplete";
+        }
+        if (this.currentSetupMode !== null) {
+            return "setup_in_progress";
+        }
+        return null;
+    }
+    /**
+     * 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.
+     */
+    async processInline(event) {
+        await this.handleEventInner(event);
+    }
+    /** Get configured services set, rebuilding when ServiceRegistry changes. */
+    getConfiguredServices() {
+        // ServiceRegistry is mutable (services come online after OAuth etc.), so
+        // rebuild each call. buildConfiguredServices is a cheap set construction.
+        // GitHub is sourced from the unified `repositories` table — also live so
+        // a row added via /api/repositories shows up on the next session
+        // materialization without a daemon restart.
+        const hasGithub = selectGithubRepoSlugs(this.db).length > 0;
+        if (this.services) {
+            return buildConfiguredServices(this.config, {
+                ...this.services,
+                github: hasGithub,
+            });
+        }
+        // Test fallback (no ServiceRegistry). Cannot cache when `hasGithub`
+        // changes between calls, so just rebuild — the construction is cheap.
+        return buildConfiguredServices(this.config, { github: hasGithub });
+    }
+    /** Snapshot active mail accounts (§Phase 5 accounts.md materialization). */
+    getActiveMailAccounts() {
+        return this.services?.mail?.listActiveAccounts() ?? [];
+    }
+    isReactive(event) {
+        if (isMessageEvent(event) && (event.isDm || event.isMention))
+            return true;
+        if (event.priority === EventPriority.CRITICAL)
+            return true;
+        // Dashboard-triggered tasks are user-initiated — treat as reactive.
+        // Both the regenerate button and the Knowledge upload form fire while
+        // the user is on the dashboard waiting for a response, so neither
+        // should be gated by setup mode or the autonomous cost cap.
+        if (event.source === "dashboard_regenerate")
+            return true;
+        if (isKnowledgeImportEvent(event))
+            return true;
+        return false;
+    }
+    /**
+     * 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.
+     */
+    shouldSkipForCostCap(event) {
+        const cap = this.config.autonomousDailyCostCapUsd;
+        if (cap == null)
+            return false;
+        const tz = this.config.timezone || undefined;
+        const bounds = getAgentDayBoundsUtc(tz, this.config.dayBoundaryHour);
+        // better-sqlite3 caches prepared statements internally by SQL string,
+        // so this.db.prepare() with a static string is effectively free.
+        const row = this.db
+            .prepare(EventDispatcher.COST_CAP_SQL)
+            .get(bounds.start, bounds.end);
+        const todayCost = row.cost;
+        if (todayCost < cap)
+            return false;
+        // Priority-based degradation: assign each routine a threshold multiplier.
+        // Lower multiplier = skipped sooner.
+        const routine = isRoutineEvent(event)
+            ? event.routine
+            : null;
+        const thresholds = {
+            hourly_check: 1.0, // skipped first (at 100% of cap)
+            roadmap_refresh: 1.2, // skipped at 120%
+            evening_review: 1.5, // skipped at 150%
+            morning_routine: 2.0, // last to be cut (only at 200%)
+        };
+        const threshold = routine ? (thresholds[routine] ?? 1.0) : 1.0;
+        return todayCost >= cap * threshold;
+    }
+    async handleEvent(event) {
+        try {
+            await this.handleEventInner(event);
+        }
+        catch (err) {
+            // Top-level catch prevents unhandled promise rejections from crashing the process
+            // (handleEvent is called with `void` — fire-and-forget — so rejections are unhandled)
+            logger.error({ err, eventType: event.type, source: event.source }, "Unhandled error in event processing");
+        }
+    }
+    async handleEventInner(event) {
+        const sem = this.isReactive(event) ? this.reactiveSem : this.autonomousSem;
+        await sem.acquire();
+        try {
+            await this.dispatchSafe(event);
+        }
+        finally {
+            sem.release();
+        }
+    }
+    async triggerHourlyCheck(source, options = {}) {
+        const forced = options.force === true;
+        const minObservations = this.config.hourlyCheckMinObservations;
+        // C1 fix: atomic check-and-set on hourlyCheckInProgress BEFORE any await
+        // boundary. Previously `await this.isMorningRoutineActive()` yielded to
+        // the microtask queue, allowing cron + /api/agent/run-now arriving in
+        // the same tick to both observe `hourlyCheckInProgress === false` and
+        // both enqueue. Because Node is single-threaded and better-sqlite3 is
+        // synchronous, doing set-first + sync checks + rollback-on-skip is now
+        // race-free.
+        if (this.hourlyCheckInProgress) {
+            logger.info({ source }, "Hourly check skipped — previous hourly check is still running");
+            return {
+                status: "skipped",
+                reason: "hourly_check_in_progress",
+                minObservations,
+                forced,
+            };
+        }
+        this.hourlyCheckInProgress = true;
+        // Rollback flag unless we actually enqueue the event or land on a
+        // silent path that owns its own reset.
+        let enqueued = false;
+        let silentPathOwnsReset = false;
+        try {
+            const setupBlock = this.isAutonomousAllowed();
+            if (setupBlock !== null) {
+                logger.info({ source, reason: setupBlock }, "Hourly check skipped — autonomous work paused for setup");
+                return {
+                    status: "skipped",
+                    reason: setupBlock,
+                    minObservations,
+                    forced,
+                };
+            }
+            if (this.isMorningRoutineActive()) {
+                logger.info({ source }, "Hourly check skipped — morning routine is active");
+                return {
+                    status: "skipped",
+                    reason: "morning_routine_active",
+                    minObservations,
+                    forced,
+                };
+            }
+            // Refresh delegated-sync snapshots for any cadence the operator
+            // left opted-OUT (the post-Phase-9 default). Without this, Gmail /
+            // Notion observations would dry up entirely in delegated mode and
+            // the routine.hourly_check.delegated.* task flow's Step 0a / 0c
+            // would have nothing to consume — Step 1's `/api/observations`
+            // call would return only Obsidian / Git rows. Calendar's Step 0b
+            // already fetches actively via `/reconcile`, so the gap is
+            // specific to gmail / notion. See `docs/design/appendices/
+            // delegated-sync-opt-in.md` and the worker's
+            // `runDisabledCadencesForHourlyCheck` doc-comment for the full
+            // reasoning. Failures are logged but do NOT block the check —
+            // a stuck cadence cannot starve the entire hourly loop.
+            if (this.delegatedSyncRefresh) {
+                try {
+                    await this.delegatedSyncRefresh();
+                }
+                catch (err) {
+                    logger.warn({ err, source }, "Pre-hourly-check delegated sync refresh failed; proceeding with stale snapshot");
+                }
+            }
+            const pendingCount = getPendingCount(this.db, { actorFilter: "user" });
+            // cost-reduction-structural §B — three-stage gate.
+            // Mode `off` falls through to the legacy min-observations gate +
+            // straight enqueue (rollback path for the gate); `shadow`/`live`
+            // compute the gate verdict before any other branch fires.
+            const gateMode = (this.config.hourlyCheckGateMode
+                ?? "shadow");
+            if (gateMode === "off") {
+                if (!forced && pendingCount < minObservations) {
+                    logger.debug({ source, pendingCount, minObservations }, "Hourly check skipped — not enough pending observations");
+                    return {
+                        status: "skipped",
+                        reason: "below_threshold",
+                        pendingCount,
+                        minObservations,
+                        forced,
+                    };
+                }
+                await this.eventBus.put({
+                    ...createEvent({
+                        type: "routine.hourly_check",
+                        source,
+                        priority: EventPriority.NORMAL,
+                    }),
+                    routine: "hourly_check",
+                    data: { pendingCount, forced },
+                    ...(options.requestedModel ? { requestedModel: options.requestedModel } : {}),
+                });
+                enqueued = true;
+                return {
+                    status: "queued",
+                    pendingCount,
+                    minObservations,
+                    forced,
+                    gateMode: "off",
+                };
+            }
+            const decision = this.computeHourlyCheckGateDecision();
+            if (gateMode === "shadow") {
+                // Shadow mode: log the gate verdict, then proceed to Stage 3
+                // exactly as before so the existing pipeline is uncovered.
+                this.logGateAuditRow(decision, {
+                    mode: "shadow",
+                    appliedDecision: "stage3_shadow",
+                    forced,
+                });
+                if (!forced && pendingCount < minObservations) {
+                    logger.debug({ source, pendingCount, minObservations, gateStage: decision.stage }, "Hourly check skipped (shadow) — not enough pending observations");
+                    return {
+                        status: "skipped",
+                        reason: "below_threshold",
+                        pendingCount,
+                        minObservations,
+                        forced,
+                        gateMode: "shadow",
+                        gateStage: decision.stage,
+                        gateReason: decision.reason,
+                        appliedStage: "stage3_shadow",
+                    };
+                }
+                await this.enqueueStage3HourlyCheck(source, { ...decision }, { mode: "shadow", forced, pendingCount, requestedModel: options.requestedModel });
+                enqueued = true;
+                return {
+                    status: "queued",
+                    pendingCount,
+                    minObservations,
+                    forced,
+                    gateMode: "shadow",
+                    gateStage: decision.stage,
+                    gateReason: decision.reason,
+                    appliedStage: "stage3_shadow",
+                };
+            }
+            // gateMode === 'live'
+            // Honour the legacy min-observations floor only when the gate
+            // would have proceeded to Stage 3 anyway. The silent gate path
+            // already short-circuits the noisy "1 obs, no signal" case below
+            // it, so keeping the floor active there would just suppress the
+            // gate's telemetry.
+            if (!forced
+                && decision.stage === "stage3"
+                && pendingCount < minObservations) {
+                this.logGateAuditRow(decision, {
+                    mode: "live",
+                    appliedDecision: "stage3",
+                    forced,
+                    // Mark the row as a skip even though the gate wanted Stage 3 —
+                    // the legacy min-observations floor short-circuited it. Without
+                    // this, every `below_threshold` skip would persist as a phantom
+                    // `result='success'` row in the audit feed.
+                    resultOverride: "skipped",
+                    extra: { skipped: "below_threshold" },
+                });
+                return {
+                    status: "skipped",
+                    reason: "below_threshold",
+                    pendingCount,
+                    minObservations,
+                    forced,
+                    gateMode: "live",
+                    gateStage: decision.stage,
+                    gateReason: decision.reason,
+                };
+            }
+            if (decision.stage === "stage0_silent") {
+                const silentResult = this.runSilentHourlyCheckPath(decision, "stage0_silent", {
+                    source,
+                    forced,
+                });
+                silentPathOwnsReset = true;
+                return {
+                    ...silentResult,
+                    minObservations,
+                    gateMode: "live",
+                    gateStage: decision.stage,
+                    gateReason: decision.reason,
+                    appliedStage: "stage0_silent",
+                };
+            }
+            if (decision.stage === "stage2") {
+                const verdict = await this.runStage2Triage(decision, source);
+                if (verdict === "log_only") {
+                    const silentResult = this.runSilentHourlyCheckPath(decision, "stage2_log_only", { source, forced });
+                    silentPathOwnsReset = true;
+                    return {
+                        ...silentResult,
+                        minObservations,
+                        gateMode: "live",
+                        gateStage: decision.stage,
+                        gateReason: decision.reason,
+                        appliedStage: "stage2_log_only",
+                    };
+                }
+                // verdict === 'escalate' OR 'failed' (failed → cautious escalate
+                // since a malformed JSON should not silently skip a hour's worth
+                // of signals; matches the prompt contract's stated default).
+                await this.enqueueStage3HourlyCheck(source, decision, {
+                    mode: "live",
+                    forced,
+                    pendingCount,
+                    requestedModel: options.requestedModel,
+                    stage2Verdict: verdict,
+                });
+                enqueued = true;
+                return {
+                    status: "queued",
+                    pendingCount,
+                    minObservations,
+                    forced,
+                    gateMode: "live",
+                    gateStage: decision.stage,
+                    gateReason: decision.reason,
+                    appliedStage: "stage3",
+                };
+            }
+            // decision.stage === 'stage3'
+            await this.enqueueStage3HourlyCheck(source, decision, { mode: "live", forced, pendingCount, requestedModel: options.requestedModel });
+            enqueued = true;
+            return {
+                status: "queued",
+                pendingCount,
+                minObservations,
+                forced,
+                gateMode: "live",
+                gateStage: decision.stage,
+                gateReason: decision.reason,
+                appliedStage: "stage3",
+            };
+        }
+        finally {
+            // Flag is only left true when we successfully enqueued OR the
+            // silent path explicitly opted out of resetting (it resets at
+            // the end of its own helper). The event loop's dispatchSafe()
+            // finally block clears the flag when an enqueued routine event
+            // finishes processing.
+            if (!enqueued && !silentPathOwnsReset) {
+                this.hourlyCheckInProgress = false;
+            }
+        }
+    }
+    /**
+     * 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.
+     */
+    computeHourlyCheckGateDecision() {
+        const todayMd = this.readTodayMdSafe();
+        const signals = computeHourlyCheckSignals(this.db, {
+            vipMailSenders: this.config.vipMailSenders ?? [],
+            todayMd,
+            // Pass the configured agent timezone so `agentPlanOverdueCount`
+            // compares HH:MM rows in the right zone. Falls back to the
+            // engine's local TZ inside `computeHourlyCheckSignals` when this
+            // config field is empty (the common single-user case).
+            ...(this.config.timezone
+                ? { agentTimezone: this.config.timezone }
+                : {}),
+        });
+        return decideStage(signals, {
+            heartbeatHours: this.config.hourlyCheckHeartbeatHours ?? 4,
+            stage2Enabled: this.config.hourlyCheckStage2Enabled ?? false,
+            pendingObsLowSignalCeiling: this.config.hourlyCheckLowSignalPendingCeiling ?? 0,
+        });
+    }
+    readTodayMdSafe() {
+        try {
+            const path = join(getContextDir(this.config, this.db), CONTEXT_RELATIVE_PATHS.today);
+            if (!existsSync(path))
+                return null;
+            return readFileSync(path, "utf-8");
+        }
+        catch (err) {
+            logger.warn({ err }, "Failed to read today.md for hourly_check signals");
+            return null;
+        }
+    }
+    /**
+     * 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.
+     */
+    runSilentHourlyCheckPath(decision, appliedDecision, ctx) {
+        const reason = appliedDecision === "stage0_silent"
+            ? "gate_stage0_silent"
+            : "gate_stage2_log_only";
+        let pendingCount = 0;
+        try {
+            pendingCount = decision.signals.pendingObsCount;
+            // Append a single bullet to today.md ## Agent Log. Best-effort —
+            // when today.md is missing or the lock is held, we still consume
+            // the observations so the queue doesn't grow indefinitely.
+            const message = appliedDecision === "stage0_silent"
+                ? `[hourly_check] Quiet (${decision.reason}) — ${pendingCount} obs consumed silently`
+                : `[hourly_check] Stage 2 log-only (${decision.reason}) — ${pendingCount} obs consumed silently`;
+            if (this.todayWriteLock) {
+                appendAgentLogLine({
+                    contextDir: getContextDir(this.config, this.db),
+                    message,
+                    todayWriteLock: this.todayWriteLock,
+                    timezone: this.config.timezone || undefined,
+                });
+            }
+            // Consume the observations under the gate's correlation id so
+            // dashboards can attribute "consumed by gate" rows separately
+            // from agent-driven consumption.
+            try {
+                const pending = getPendingObservations(this.db, {
+                    actorFilter: "user",
+                    limit: 100,
+                });
+                if (pending.length > 0) {
+                    consumeObservations(this.db, pending.map((row) => row.id), `hourly_check_gate:${appliedDecision}`);
+                }
+            }
+            catch (err) {
+                logger.warn({ err }, "Failed to consume observations on silent gate path");
+            }
+            this.logGateAuditRow(decision, {
+                mode: "live",
+                appliedDecision,
+                forced: ctx.forced,
+            });
+            logger.info({
+                source: ctx.source,
+                gateStage: decision.stage,
+                gateReason: decision.reason,
+                appliedDecision,
+                pendingCount,
+            }, "Hourly check silenced by Stage-1 gate");
+        }
+        finally {
+            this.hourlyCheckInProgress = false;
+        }
+        return {
+            status: "skipped",
+            reason,
+            pendingCount,
+            forced: ctx.forced,
+        };
+    }
+    async enqueueStage3HourlyCheck(source, decision, extra) {
+        const gateBlock = renderGateDecisionBlock(decision, {
+            mode: extra.mode,
+            forced: extra.forced,
+        });
+        if (extra.mode === "live") {
+            this.logGateAuditRow(decision, {
+                mode: extra.mode,
+                appliedDecision: "stage3",
+                forced: extra.forced,
+                ...(extra.stage2Verdict ? { stage2Verdict: extra.stage2Verdict } : {}),
+            });
+        }
+        await this.eventBus.put({
+            ...createEvent({
+                type: "routine.hourly_check",
+                source,
+                priority: EventPriority.NORMAL,
+            }),
+            routine: "hourly_check",
+            data: {
+                pendingCount: extra.pendingCount,
+                forced: extra.forced,
+                gateDecision: {
+                    mode: extra.mode,
+                    stage: decision.stage,
+                    reason: decision.reason,
+                    forced: extra.forced,
+                    ...(extra.stage2Verdict ? { stage2Verdict: extra.stage2Verdict } : {}),
+                    block: gateBlock,
+                },
+            },
+            ...(extra.requestedModel ? { requestedModel: extra.requestedModel } : {}),
+        });
+    }
+    logGateAuditRow(decision, params) {
+        try {
+            // The gate-audit helper only knows about the canonical stages
+            // (gate output) plus the shadow-mode marker. Map the silent-path
+            // alias `stage2_log_only` onto its canonical sibling so the
+            // helper's typing stays narrow; the verdict is preserved verbatim
+            // alongside `stage_reached` in the merged detail.
+            const auditAppliedDecision = params.appliedDecision === "stage2_log_only"
+                ? "stage0_silent"
+                : params.appliedDecision;
+            const detail = {
+                ...buildGateAuditDetail(decision, {
+                    mode: params.mode,
+                    appliedDecision: auditAppliedDecision,
+                    forced: params.forced,
+                    ...(params.stage2Verdict ? { stage2Verdict: params.stage2Verdict } : {}),
+                }),
+                // Always reflect the *real* applied stage in the row regardless
+                // of the alias mapping above.
+                stage_reached: params.appliedDecision,
+                ...(params.extra ?? {}),
+            };
+            const isShadow = params.appliedDecision === "stage3_shadow";
+            const isSilentPath = params.appliedDecision === "stage0_silent"
+                || params.appliedDecision === "stage2_log_only";
+            const result = params.resultOverride
+                ?? (isShadow ? "success" : isSilentPath ? "skipped" : "success");
+            this.db
+                .prepare(`INSERT INTO agent_actions
+             (action_type, trigger, result, detail, started_at, completed_at)
+           VALUES ('hourly_check.gate', 'autonomous', ?, json(?), datetime('now'), datetime('now'))`)
+                .run(result, JSON.stringify(detail));
+        }
+        catch (err) {
+            logger.warn({ err }, "Failed to record hourly_check.gate audit row");
+        }
+    }
+    /**
+     * 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.
+     */
+    async runStage2Triage(decision, source) {
+        const triageEvent = {
+            ...createEvent({
+                type: "routine.hourly_check.triage",
+                source,
+                priority: EventPriority.NORMAL,
+            }),
+            routine: "hourly_check.triage",
+            data: {
+                forced: false,
+                gateDecision: {
+                    mode: "live",
+                    stage: decision.stage,
+                    reason: decision.reason,
+                    forced: false,
+                    block: renderGateDecisionBlock(decision, { mode: "live", forced: false }),
+                },
+            },
+        };
+        let context;
+        try {
+            context = await this.contextBuilder.build(triageEvent);
+        }
+        catch (err) {
+            logger.error({ err }, "Stage 2 triage context build failed");
+            return "failed";
+        }
+        const processKey = "routine.hourly_check.triage";
+        const reassemblePrompt = (bid) => this.assemblePrompt(triageEvent.type, processKey, bid);
+        let binding;
+        try {
+            binding = this.agentRouter.resolveBinding(triageEvent, { processKey });
+        }
+        catch (err) {
+            logger.error({ err }, "Stage 2 triage binding resolve failed");
+            return "failed";
+        }
+        const prompt = reassemblePrompt(binding.main.backendId);
+        let result;
+        try {
+            result = await this.agentRouter.execute({
+                prompt,
+                context,
+                event: triageEvent,
+                processKey,
+                preResolvedBinding: binding,
+                reassemblePrompt,
+                // Defense-in-depth: Stage 2 must not call any tool. Empty
+                // `allowedToolsOverride` REPLACES the default allowlist on
+                // Claude (Codex/Gemini have no per-spawn `allowedTools` surface
+                // — acknowledged gap in `agent-core.ts`). The `max_turns=1` cap
+                // for the spawn comes from the seeded `process_backend_config`
+                // row for `routine.hourly_check.triage` (see `db/schema.ts`),
+                // which the router reads via `binding.main.maxTurns`. Together
+                // these mean: zero tools on Claude, one assistant turn on every
+                // backend.
+                allowedToolsOverride: [],
+            });
+        }
+        catch (err) {
+            logger.error({ err }, "Stage 2 triage agent execution failed");
+            return "failed";
+        }
+        // Audit row for the lite-tier session itself, distinct from the gate
+        // audit row written by `logGateAuditRow`.
+        try {
+            this.audit.logAction({
+                event: triageEvent,
+                model: result.model,
+                costUsd: result.costUsd,
+                usage: result.usage,
+                modelUsage: result.modelUsage,
+                durationMs: result.durationMs,
+                numTurns: result.numTurns,
+                trigger: "autonomous",
+                backend: result.backendId,
+                costSource: result.costSource,
+                contextUpdated: result.contextUpdated,
+                advisorCallCount: result.advisorCallCount,
+            });
+        }
+        catch (err) {
+            logger.warn({ err }, "Failed to log Stage 2 triage agent_actions row");
+        }
+        return parseStage2Verdict(result.output);
+    }
+    /**
+     * 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() {
+        if (this.morningRoutineInProgress) {
+            return true;
+        }
+        const row = this.db.prepare(`SELECT 1 as active
+       FROM agent_schedule
+       WHERE status IN ('pending', 'running')
+         AND task_type = 'wake'
+         AND json_extract(task_context, '$.routine') = 'morning_routine'
+       LIMIT 1`).get();
+        return !!row;
+    }
+    async dispatchSafe(event) {
+        const trigger = this.isReactive(event) ? "reactive" : "autonomous";
+        const startMs = Date.now();
+        logger.info({ eventType: event.type, source: event.source, trigger }, "Event processing started");
+        try {
+            // Setup gate — skip all autonomous work while initial setup is
+            // incomplete or a setup conversation is active. Reactive work is
+            // exempt: user DMs (including the dashboard setup chat itself),
+            // mentions in channels, CRITICAL-priority events, and explicit
+            // dashboard-initiated actions (e.g. dashboard_regenerate). The
+            // `isReactive` check is the semantic match — `isMessageEvent` alone
+            // is both too broad (channel messages without mention are dropped
+            // as a personal-agent policy) and too narrow (dashboard_regenerate
+            // is not a message event but is user-initiated).
+            //
+            // Scheduled wake tasks stay in the agent_schedule table in 'pending'
+            // — ScheduleWatcher's top-level gate prevents claiming them, and
+            // `discardStalePendingSchedules` will tidy anything left over
+            // across day boundaries.
+            if (!this.isReactive(event)) {
+                const setupBlock = this.isAutonomousAllowed();
+                if (setupBlock !== null) {
+                    this.audit.logSkip(event, setupBlock, trigger);
+                    logger.info({ eventType: event.type, source: event.source, reason: setupBlock }, "Event skipped — autonomous work paused for setup");
+                    return;
+                }
+                // Autonomous daily cost cap — safety net distinct from removed Phase 9
+                // maxDailyCostUsd (which blanket-blocked all sessions including DMs).
+                // Reactive sessions always pass. Degradation priority: hourly_check is
+                // skipped first, morning_routine last.
+                if (this.shouldSkipForCostCap(event)) {
+                    this.audit.logSkip(event, "autonomous_cost_cap_exceeded", trigger);
+                    logger.info({ eventType: event.type, source: event.source }, "Event skipped — autonomous daily cost cap exceeded");
+                    return;
+                }
+            }
+            await this.dispatch(event);
+            logger.info({ eventType: event.type, source: event.source, durationMs: Date.now() - startMs }, "Event processing completed");
+        }
+        catch (err) {
+            const durationMs = Date.now() - startMs;
+            logger.error({ err, eventType: event.type, source: event.source, durationMs }, "Event processing failed");
+            this.audit.logError(event, err, trigger, buildLogErrorContext(err, durationMs));
+            await this.handleError(event, err);
+        }
+        finally {
+            if (isRoutineEvent(event) && event.routine === "hourly_check") {
+                this.hourlyCheckInProgress = false;
+            }
+        }
+    }
+    async dispatch(event) {
+        if (isMessageEvent(event)) {
+            if (event.isDm || event.isMention) {
+                await this.runWithSessionGate(this.getMessageExecutionKey(event), () => this.handleMessage(event));
+            }
+            else {
+                // Personal agent — channel messages without mention are dropped.
+                // Adapters already filter these, but guard here as defense-in-depth.
+                this.audit.logSkip(event, "channel_message_ignored", "autonomous");
+                logger.debug({ eventType: event.type, source: event.source, channel: event.channel }, "Channel message without mention dropped — personal agent does not process multi-user channel traffic");
+                return;
+            }
+        }
+        else if (isRoutineEvent(event)) {
+            const routine = event.routine;
+            if (routine === "morning_routine") {
+                await this.executeMorningRoutine(event);
+            }
+            else if (routine === "roadmap_refresh") {
+                await this.executeRoadmapRefresh(event);
+            }
+            else if (routine === "skill_curation") {
+                // P22 §3.4 step 4. The optimizer runs in an isolated workdir under
+                // ~/.personal-agent/optimizer-workdir/<runId>/ with a hard-restricted
+                // allowedTools envelope (curl + Read only). The MaterializeOptimizer
+                // hook is wired in `index.ts`; if absent, the routine no-ops with an
+                // audit log. This is the safety floor — without the materializer the
+                // session would otherwise inherit standard executor allowedTools, so
+                // declining to execute is the correct behaviour for an unwired
+                // installation.
+                if (!this.materializeOptimizerWorkdir) {
+                    this.audit.logSkip(event, "skill_curation_unwired", "autonomous");
+                    return;
+                }
+                await this.executeSkillCurationRoutine(event);
+            }
+            else {
+                // hourly_check, evening_review, weekly_review, monthly_review
+                // Tier is resolved from process-key defaults by BackendRouter.
+                await this.executeDefault(event);
+            }
+        }
+        else if (isScheduledDmEvent(event)) {
+            // SCHEDULED-DM-IMPLEMENTATION-PLAN §3.6 — serialize behind any
+            // in-flight owner-facing DM (across BOTH OWNER_DM_SCOPE and
+            // DASHBOARD_CHAT_SCOPE) so the briefing never composes
+            // concurrently with a DM reply that's currently answering the
+            // same topic. Sort order on key acquisition is the
+            // deadlock-prevention contract.
+            await this.runWithSessionGates([
+                `${OWNER_DM_SCOPE}:${OWNER_SCOPE_KEY}`,
+                `${DASHBOARD_CHAT_SCOPE}:${DASHBOARD_SCOPE_KEY}`,
+            ], async () => {
+                // §3.6.1 max-wait — drop the briefing if gate-acquisition
+                // pushed delivery past `maxBriefingDelayMinutes` of the
+                // scheduled time. Loses the daily heartbeat on chatty
+                // mornings; preserves "morning" semantics on quiet ones.
+                if (event.scheduleId !== undefined) {
+                    const row = this.db
+                        .prepare("SELECT scheduled_for FROM agent_schedule WHERE id = ?")
+                        .get(event.scheduleId);
+                    if (row) {
+                        const lateMs = Date.now() - parseSqliteUtcMs(row.scheduled_for);
+                        const budgetMs = this.config.maxBriefingDelayMinutes * 60_000;
+                        if (lateMs > budgetMs) {
+                            this.db
+                                .prepare("UPDATE agent_schedule SET status = 'skipped' WHERE id = ? AND status = 'running'")
+                                .run(event.scheduleId);
+                            logger.info({
+                                eventType: event.type,
+                                scheduleId: event.scheduleId,
+                                lateMs,
+                                budgetMs,
+                            }, "scheduled.dm dropped — gate acquisition exceeded max delay");
+                            return;
+                        }
+                    }
+                }
+                await this.executeScheduledTask(event);
+            });
+        }
+        else if (isAgentTaskEvent(event)) {
+            // scheduled.task — no gate, retains existing parallel-execution
+            // behavior. (scheduled.dm subtype is handled above.)
+            await this.executeScheduledTask(event);
+        }
+        else {
+            await this.executeDefault(event);
+        }
+    }
+    getMessageExecutionKey(event) {
+        const { scope, scopeKey } = getConversationScope({
+            platform: event.platform,
+            channel: event.channel,
+            threadId: event.threadId,
+            isDm: event.isDm,
+            // Forks docs_qa traffic onto its own gate so a QA lookup does not
+            // queue behind an in-flight chat turn (or vice versa).
+            intent: event.intent,
+        });
+        return `${scope}:${scopeKey}`;
+    }
+    async runWithSessionGate(key, fn) {
+        return this.sessionGates.runWithSessionGate(key, fn);
+    }
+    /**
+     * 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.
+     */
+    async runWithSessionGates(keys, fn) {
+        return this.sessionGates.runWithSessionGates(keys, fn);
+    }
+    /**
+     * 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.
+     */
+    async executeMorningRoutine(event) {
+        let lockId = null;
+        let effectiveEvent = event;
+        if (this.todayWriteLock) {
+            const lock = this.todayWriteLock.acquire();
+            if (!lock.ok) {
+                logger.warn({
+                    eventType: event.type,
+                    source: event.source,
+                    holder: lock.holder,
+                }, "today.md write lock held during morning routine — scheduling retry");
+                this.scheduleMorningRetry(event);
+                return;
+            }
+            lockId = lock.lockId;
+            effectiveEvent = {
+                ...event,
+                data: {
+                    ...event.data,
+                    todayWriteLockId: lockId,
+                },
+            };
+        }
+        this.rotateDayFiles();
+        // Check roadmap staleness BEFORE agent runs (agent may PATCH roadmap, updating mtime)
+        const roadmapStaleBeforeMorning = this.isRoadmapStale();
+        // Select prompt variant based on whether yesterday.md exists
+        const contextDir = getContextDir(this.config, this.db);
+        const hasYesterday = existsSync(join(contextDir, "yesterday.md"));
+        const promptKey = hasYesterday
+            ? "routine.morning_routine"
+            : "routine.morning_routine_initial";
+        // Retry runs on the light tier (Sonnet) instead of the configured heavy
+        // tier (Opus). Cost trade-off: a wrong-date or malformed today.md is
+        // cheap to regenerate — the heavy work (mail classification, journal
+        // synthesis, roadmap walk) was already done by the first attempt and its
+        // outputs persisted via /api/context/* writes that survive into the
+        // retry's prompt context. Sonnet at ~1/5 of Opus's per-turn cost keeps
+        // the worst-case retry chain (3 attempts) under $2 instead of $12,
+        // which is the cap the user asked for after observing $25/hour
+        // burn during a date-format loop. See morning-routine fix doc.
+        const retryCount = Number(effectiveEvent.data?.retryCount ?? 0);
+        const isRetry = retryCount > 0 || effectiveEvent.data?.isRetry === true;
+        let requestedTier = isRetry
+            ? "medium"
+            : undefined;
+        // `routine.morning_routine_initial` is non-configurable, so plan presets
+        // and operator pins on `routine.morning_routine` are silently ignored
+        // here without explicit inheritance — Max5/Max20/Team/Enterprise users
+        // pinned to Sonnet would still run Opus on the initial variant whenever
+        // `yesterday.md` is missing (cf. plan-presets.ts and process-key.ts §
+        // morning_routine_initial). Mirror morning_routine's configured tier
+        // onto the initial run when available.
+        if (!isRetry && promptKey === "routine.morning_routine_initial") {
+            const inheritedTier = this.inferConfiguredMorningRoutineTier();
+            if (inheritedTier) {
+                requestedTier = inheritedTier;
+            }
+        }
+        logger.info({ hasYesterday, promptKey, roadmapStale: roadmapStaleBeforeMorning, isRetry, retryCount, requestedTier: requestedTier ?? "default" }, "Morning routine prompt selected");
+        const context = await this.contextBuilder.build(effectiveEvent);
+        const binding = this.agentRouter.resolveBinding(effectiveEvent, {
+            processKey: promptKey,
+            ...(requestedTier ? { requestedTier } : {}),
+        });
+        const reassemblePrompt = (bid) => this.assemblePrompt(promptKey, promptKey, bid);
+        const prompt = reassemblePrompt(binding.main.backendId);
+        // B2 fix: wrap the entire retry chain — NOT just the inner execute() —
+        // so that `morningRoutineInProgress` stays true across retry attempts.
+        // Previously .finally() was attached to the inner promise, causing the
+        // flag to reset at attempt #1 completion and letting hourly_check race
+        // with the morning routine during retry backoff / attempt #2.
+        this.morningRoutineInProgress = true;
+        let result;
+        try {
+            result = await this.executeWithRetry(() => this.agentRouter.execute({
+                prompt,
+                context,
+                event: effectiveEvent,
+                processKey: promptKey,
+                preResolvedBinding: binding,
+                reassemblePrompt,
+                ...(requestedTier ? { requestedTier } : {}),
+            }), effectiveEvent);
+        }
+        finally {
+            this.morningRoutineInProgress = false;
+            if (lockId && this.todayWriteLock) {
+                this.todayWriteLock.release(lockId);
+            }
+        }
+        await this.processResult(result, effectiveEvent);
+        // Post-morning-routine: verify today.md was generated, retry if not.
+        // This catches agent failures that don't throw (e.g., early stop, context
+        // building succeeded but the PUT /api/context/today call was skipped).
+        //
+        // Distinguish the two failure modes so the operator can tell from the log
+        // whether the agent skipped the write entirely vs. wrote with the wrong
+        // agent-day date. Pre-fix, both paths logged the same "does not exist"
+        // string and the wrong-date case looked indistinguishable from a hard
+        // crash, masking the date-confusion root cause.
+        const todayMdState = this.diagnoseTodayMdState();
+        if (todayMdState.kind !== "fresh") {
+            logger.warn({
+                eventType: effectiveEvent.type,
+                isError: result.isError,
+                numTurns: result.numTurns,
+                todayMdState: todayMdState.kind,
+                ...(todayMdState.kind === "wrong_date"
+                    ? {
+                        writtenDate: todayMdState.writtenDate,
+                        expectedAgentDay: todayMdState.expectedAgentDay,
+                    }
+                    : {}),
+            }, todayMdState.kind === "missing"
+                ? "Morning routine completed but today.md does not exist — scheduling retry"
+                : "Morning routine completed but today.md has wrong agent-day date — scheduling retry");
+            this.scheduleMorningRetry(effectiveEvent);
+        }
+        else {
+            if (effectiveEvent.data?.deferPostMorningCatchupsUntilStartupReady === true) {
+                logger.info({ eventType: effectiveEvent.type, source: effectiveEvent.source }, "Deferring post-morning catchups until startup messaging is ready");
+            }
+            else {
+                await this.emitPostMorningCatchups(effectiveEvent);
+            }
+            const todayRefreshFlush = flushPendingTodayRefresh(this.db);
+            if (todayRefreshFlush.hadPending) {
+                logger.info({ scheduled: todayRefreshFlush.scheduled }, "Flushed pending today_refresh after morning routine");
+            }
+        }
+        // Post-morning-routine: trigger roadmap refresh if stale
+        if (roadmapStaleBeforeMorning) {
+            if (effectiveEvent.data?.deferPostMorningCatchupsUntilStartupReady === true) {
+                logger.info({ eventType: effectiveEvent.type, source: effectiveEvent.source }, "Deferring roadmap_refresh until startup messaging is ready");
+            }
+            else {
+                this.emitRoadmapRefresh("post_morning_routine");
+            }
+        }
+    }
+    /**
+     * 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.
+     */
+    inferConfiguredMorningRoutineTier() {
+        try {
+            const row = this.db
+                .prepare("SELECT main_backend, main_model FROM process_backend_config WHERE process_key = 'routine.morning_routine'")
+                .get();
+            if (!row || !isBackendId(row.main_backend))
+                return null;
+            return findRegisteredModel(row.main_backend, row.main_model)?.tier ?? null;
+        }
+        catch (err) {
+            logger.debug({ err }, "Failed to infer morning_routine configured tier");
+            return null;
+        }
+    }
+    async emitPostMorningCatchups(event) {
+        const queuedRoutines = Array.isArray(event.data?.postCatchupRoutines)
+            ? event.data.postCatchupRoutines.filter((value) => typeof value === "string")
+            : [];
+        for (const routine of queuedRoutines) {
+            logger.info({ routine }, "Emitting deferred post-morning catchup routine");
+            await this.eventBus.put({
+                ...createEvent({
+                    type: `routine.${routine}`,
+                    source: "post_morning_catchup",
+                    priority: EventPriority.HIGH,
+                }),
+                routine,
+            });
+        }
+        if (event.data?.postCatchupHourlyCheck === true) {
+            logger.info("Triggering deferred hourly_check after morning catchup");
+            await this.triggerHourlyCheck("post_morning_catchup");
+        }
+    }
+    /**
+     * 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
+     */
+    scheduleMorningRetry(event) {
+        const previousCount = Number(event.data?.retryCount ?? 0);
+        const retryCount = previousCount + 1;
+        const MAX_RETRIES = 3;
+        // Preserve the original cron morning_routine correlationId through
+        // the chain if present. On the first call this is the cron event's
+        // own id. On later calls it's propagated via event.correlationId
+        // (which handleMorningRoutineRetry sets from taskCtx).
+        const originalCorrelationId = event.data?.originalCorrelationId ??
+            event.correlationId;
+        if (retryCount > MAX_RETRIES) {
+            logger.error({
+                retryCount: previousCount,
+                maxRetries: MAX_RETRIES,
+                originalCorrelationId,
+            }, "Morning routine retry exhausted — sending critical notification");
+            void this.notificationMgr
+                .send(`⚠️ Morning routine failed to generate today.md after ${MAX_RETRIES} attempts. Please regenerate manually from the dashboard.`, event, { category: "critical", priority: "critical" })
+                .catch((err) => {
+                logger.error({ err }, "Failed to send morning-routine-retry-exhausted notification");
+            });
+            return;
+        }
+        // Exponential back-off: 5 / 10 / 15 minutes
+        const delayMinutes = retryCount * 5;
+        const retryTime = new Date(Date.now() + delayMinutes * 60 * 1000);
+        const scheduledFor = formatSqliteDatetime(retryTime);
+        // Encode the retry state in task_context so the wake agent (via
+        // executeScheduledTask → handleMorningRoutineRetry) can propagate
+        // retryCount into the synthesized RoutineEvent's event.data.
+        // `importance: "low"` keeps the retry out of roadmap.md — the
+        // originating morning_routine is already tracked elsewhere.
+        const taskContext = JSON.stringify({
+            routine: "morning_routine",
+            retryCount,
+            originalCorrelationId,
+            source: typeof event.data?.queuedSource === "string" ? event.data.queuedSource : event.source,
+            postCatchupRoutines: Array.isArray(event.data?.postCatchupRoutines)
+                ? event.data.postCatchupRoutines
+                : [],
+            postCatchupHourlyCheck: event.data?.postCatchupHourlyCheck === true,
+            importance: "low",
+        });
+        // M1: dedup + INSERT in a single transaction so two concurrent
+        // retry schedulers cannot both race past the dedup check and both
+        // insert new rows. better-sqlite3 is synchronous so the transaction
+        // callback runs atomically relative to any other DB access from
+        // this process.
+        //
+        // Dedup checks for 'pending' only — not 'running' — because the
+        // retry chain legitimately calls this method while the current
+        // wake task is still in 'running' state (handleMorningRoutineRetry
+        // → executeMorningRoutine → this). Including 'running' would break chain
+        // continuation.
+        const insertRetryTxn = this.db.transaction(() => {
+            // C5 fix: dedup on task_context.routine, not task_description prefix.
+            // Both `scheduleMorningRetry` (here) and `isMorningRoutineActive`
+            // (above) now use the same JSON-path check, so the detection path
+            // doesn't depend on the human-readable description string.
+            const existing = this.db
+                .prepare(`SELECT id FROM agent_schedule
+           WHERE task_type = 'wake'
+             AND status = 'pending'
+             AND json_extract(task_context, '$.routine') = 'morning_routine'
+           LIMIT 1`)
+                .get();
+            if (existing) {
+                return { inserted: false, existingId: existing.id };
+            }
+            this.db
+                .prepare(`INSERT INTO agent_schedule
+             (scheduled_for, task_type, task_description, task_context, correlation_id, model, status)
+           VALUES (?, 'wake', ?, ?, ?, NULL, 'pending')`)
+                .run(scheduledFor, `Morning routine retry (attempt ${retryCount}/${MAX_RETRIES}). Generate today.md per the morning_routine flow.`, taskContext, originalCorrelationId);
+            return { inserted: true };
+        });
+        try {
+            const outcome = insertRetryTxn();
+            if (!outcome.inserted) {
+                logger.info({
+                    existingScheduleId: outcome.existingId,
+                    retryCount,
+                    originalCorrelationId,
+                }, "Morning routine retry dedup — another pending retry already exists");
+                return;
+            }
+            logger.info({
+                retryCount,
+                delayMinutes,
+                scheduledFor,
+                originalCorrelationId,
+                // Retries always fall back to the medium tier (Sonnet) per the
+                // cost-cap fix in executeMorningRoutine — surface that explicitly
+                // in the schedule log so the operator can confirm the
+                // downgrade happened without grepping the next agent-execute line.
+                plannedTier: "medium",
+                plannedTierReason: "morning_routine_retry_cost_cap",
+            }, "Morning routine retry scheduled (will run on Sonnet)");
+            // Route the INSERT through the shared roadmap-refresh gate.
+            // `importance:"low"` short-circuits the trigger — the morning
+            // routine is already represented elsewhere — but going through
+            // the helper keeps all five INSERT call-sites on one path.
+            maybeTriggerRoadmapRefresh({ scheduledFor, taskContext: { importance: "low" } }, (src) => this.emitRoadmapRefresh(src), "morning_retry");
+        }
+        catch (err) {
+            logger.error({ err, retryCount }, "Failed to schedule morning routine retry");
+        }
+    }
+    buildRepositoryRunPrompt(ctx) {
+        const lines = [
+            "{context}",
+            "",
+            "## Repository Run",
+            `Repository id: ${ctx.repositoryId}`,
+            `Repository slug: ${ctx.slug}`,
+            `GitHub repo: ${ctx.githubRepo ?? "(none)"}`,
+            `Local path: ${ctx.localPath ?? "(none)"}`,
+            `Workdir mode: ${ctx.workdirMode}`,
+            `Trigger source: ${ctx.triggerSource}`,
+        ];
+        if (ctx.triggerId || ctx.triggerName || ctx.triggerEventType) {
+            lines.push("", "## Trigger", `Trigger id: ${ctx.triggerId ?? "(manual)"}`, `Trigger name: ${ctx.triggerName ?? "(manual)"}`, `Event type: ${ctx.triggerEventType ?? "(manual)"}`);
+            if (ctx.triggerEventPayload !== undefined) {
+                lines.push("", "<trigger_event_payload>", JSON.stringify(ctx.triggerEventPayload, null, 2), "</trigger_event_payload>");
+            }
+        }
+        lines.push("", "## User Prompt", ctx.prompt);
+        return lines.join("\n");
+    }
+    prepareRepositoryRunSessionDir(ctx, backendId) {
+        if (ctx.workdirMode === "local-clone") {
+            if (!ctx.localPath) {
+                throw new Error("Repository local-clone run missing localPath");
+            }
+            ensureBackendMaterialized(this.config.workspaceDir, ctx.localPath, backendId, "scheduled.task", "agent.task", this.getConfiguredServices(), this.getActiveMailAccounts(), readIntegrations(this.db), this.config.character);
+            return { sessionDir: ctx.localPath, cleanup: false };
+        }
+        if (!ctx.instructionMd) {
+            throw new Error("Repository temp run missing instructionMd");
+        }
+        const sessionDir = join(this.config.dataDir, "run", `${safeRepositoryRunDirName(ctx.slug)}-${Date.now()}-${randomUUID().slice(0, 8)}`);
+        mkdirSync(sessionDir, { recursive: true, mode: 0o700 });
+        try {
+            ensureBackendMaterialized(this.config.workspaceDir, sessionDir, backendId, "scheduled.task", "agent.task", this.getConfiguredServices(), this.getActiveMailAccounts(), readIntegrations(this.db), this.config.character);
+            writeFileSync(join(sessionDir, repositoryRunInstructionFilename(backendId)), ctx.instructionMd, "utf-8");
+            return { sessionDir, cleanup: true };
+        }
+        catch (err) {
+            cleanupSessionWorkdir(sessionDir);
+            throw err;
+        }
+    }
+    async executeRepositoryRunTask(event, ctx) {
+        const context = await this.contextBuilder.build(event);
+        const processKey = "agent.task";
+        const requestedTier = event.requestedModel
+            ? (event.requestedModel === "sonnet" ? "medium" : "high")
+            : undefined;
+        const internalBackendOverride = event.requestedBackendId
+            && isBackendId(event.requestedBackendId)
+            && typeof event.requestedModelId === "string"
+            ? {
+                requestedBackendId: event.requestedBackendId,
+                requestedModelId: event.requestedModelId,
+            }
+            : {};
+        const binding = this.agentRouter.resolveBinding(event, {
+            processKey,
+            requestedTier,
+            ...internalBackendOverride,
+        });
+        const prompt = this.buildRepositoryRunPrompt(ctx);
+        const { sessionDir, cleanup } = this.prepareRepositoryRunSessionDir(ctx, binding.main.backendId);
+        try {
+            const result = await this.executeWithRetry(() => this.agentRouter.execute({
+                prompt,
+                context,
+                event,
+                processKey,
+                requestedTier,
+                preResolvedBinding: binding,
+                reassemblePrompt: () => prompt,
+                sessionDir,
+                workdirEventType: "scheduled.task",
+                workdirProcessKey: processKey,
+                ...internalBackendOverride,
+            }), event);
+            await this.processResult(result, event);
+        }
+        finally {
+            if (cleanup) {
+                cleanupSessionWorkdir(sessionDir);
+            }
+        }
+    }
+    /**
+     * 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.
+     */
+    async executeScheduledTask(event) {
+        // Morning-routine retry detection: if taskContext says this wake
+        // task is a morning-routine retry, dispatch through executeMorningRoutine
+        // with a synthesized RoutineEvent instead of the generic flow.
+        const taskCtx = event.taskContext;
+        if (taskCtx &&
+            typeof taskCtx === "object" &&
+            taskCtx.routine === "morning_routine") {
+            await this.handleMorningRoutineRetry(event, taskCtx);
+            return;
+        }
+        if (taskCtx &&
+            typeof taskCtx === "object" &&
+            taskCtx.routine === "today_refresh") {
+            await this.executeScheduledRoutine(event, "today_refresh");
+            return;
+        }
+        const repositoryRunCtx = parseRepositoryRunTaskContext(taskCtx);
+        if (repositoryRunCtx) {
+            await this.executeRepositoryRunTask(event, repositoryRunCtx);
+            return;
+        }
+        if (await this.executeGitProjectDocTaskIfApplicable(event, taskCtx)) {
+            return;
+        }
+        const context = await this.contextBuilder.build(event);
+        const processKeyOverride = taskCtx
+            && typeof taskCtx === "object"
+            && typeof taskCtx.processKey === "string"
+            ? taskCtx.processKey
+            : null;
+        const processKey = (processKeyOverride ?? resolveProcessKey(event));
+        const promptKey = processKeyOverride ?? event.type;
+        const requestedTier = event.requestedModel
+            ? (event.requestedModel === "sonnet" ? "medium" : "high")
+            : undefined;
+        const internalBackendOverride = event.requestedBackendId
+            && isBackendId(event.requestedBackendId)
+            && typeof event.requestedModelId === "string"
+            ? {
+                requestedBackendId: event.requestedBackendId,
+                requestedModelId: event.requestedModelId,
+            }
+            : {};
+        const binding = this.agentRouter.resolveBinding(event, {
+            processKey,
+            requestedTier,
+            ...internalBackendOverride,
+        });
+        const reassemblePrompt = (bid) => this.assemblePrompt(promptKey, processKey, bid);
+        const prompt = reassemblePrompt(binding.main.backendId);
+        const result = await this.executeWithRetry(() => this.agentRouter.execute({
+            prompt,
+            context,
+            event,
+            processKey,
+            requestedTier,
+            preResolvedBinding: binding,
+            reassemblePrompt,
+        }), event);
+        await this.processResult(result, event);
+    }
+    /**
+     * 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.
+     */
+    async executeGitProjectDocTaskIfApplicable(event, taskCtx) {
+        const processKey = this.resolveGitProjectDocProcessKey(event, taskCtx);
+        if (!processKey)
+            return false;
+        const ctx = taskCtx && typeof taskCtx === "object"
+            ? taskCtx
+            : {};
+        const repo = this.resolveRepositoryForGitProjectDocTask(ctx);
+        const triggerSource = typeof ctx.triggerSource === "string"
+            ? ctx.triggerSource
+            : null;
+        const isManagementSource = triggerSource === "repository_management_cron" ||
+            triggerSource === "repository_management_manual";
+        try {
+            if (processKey === "git.project.init") {
+                const result = runRepositoryManagementInit({
+                    db: this.db,
+                    repo,
+                    contextDir: getContextDir(this.config, this.db),
+                    timezone: this.config.timezone || undefined,
+                    writeTracker: this.writeTracker,
+                });
+                if (isManagementSource) {
+                    recordManagementInitDone(this.db, repo.id);
+                }
+                this.markScheduledTaskCompleted(event);
+                logger.info({
+                    scheduleId: event.scheduleId ?? null,
+                    repositoryId: repo.id,
+                    slug: repo.slug,
+                    result: result.status,
+                    architectureScheduleId: result.architectureScheduleId,
+                }, "Handled git.project.init with direct markdown writer");
+            }
+            else {
+                const lookbackHours = typeof ctx.lookbackHours === "number"
+                    && Number.isFinite(ctx.lookbackHours)
+                    && ctx.lookbackHours > 0
+                    ? ctx.lookbackHours
+                    : undefined;
+                const result = await runRepositoryManagementScan({
+                    db: this.db,
+                    repo,
+                    contextDir: getContextDir(this.config, this.db),
+                    timezone: this.config.timezone || undefined,
+                    lookbackHours,
+                    writeTracker: this.writeTracker,
+                });
+                if (isManagementSource) {
+                    recordManagementScan(this.db, repo.id, result.status === "skipped_no_activity" ? "skipped_no_activity" : "ok");
+                }
+                this.markScheduledTaskCompleted(event);
+                logger.info({
+                    scheduleId: event.scheduleId ?? null,
+                    repositoryId: repo.id,
+                    slug: repo.slug,
+                    result: result.status,
+                    journalPath: result.journalPath,
+                }, "Handled git.project.update with direct markdown writer");
+            }
+            return true;
+        }
+        catch (err) {
+            if (isManagementSource) {
+                try {
+                    recordManagementScan(this.db, repo.id, "failed");
+                }
+                catch (recordErr) {
+                    logger.error({ err: recordErr, repositoryId: repo.id }, "Failed to record repository management direct-writer failure");
+                }
+            }
+            if (event.scheduleId) {
+                this.db
+                    .prepare("UPDATE agent_schedule SET status = 'failed' WHERE id = ? AND status = 'running'")
+                    .run(event.scheduleId);
+            }
+            logger.error({ err, scheduleId: event.scheduleId ?? null, repositoryId: repo.id }, "Git project documentation direct writer failed");
+            throw err;
+        }
+    }
+    resolveGitProjectDocProcessKey(event, taskCtx) {
+        const ctxProcessKey = taskCtx &&
+            typeof taskCtx === "object" &&
+            typeof taskCtx.processKey === "string"
+            ? taskCtx.processKey
+            : null;
+        const value = ctxProcessKey ?? event.source;
+        return value === "git.project.init" || value === "git.project.update"
+            ? value
+            : null;
+    }
+    resolveRepositoryForGitProjectDocTask(ctx) {
+        const repositoryId = typeof ctx.repositoryId === "string"
+            ? ctx.repositoryId
+            : null;
+        if (repositoryId) {
+            const byId = getRepository(this.db, repositoryId);
+            if (byId)
+                return byId;
+        }
+        const localPath = typeof ctx.localPath === "string"
+            ? ctx.localPath
+            : typeof ctx.repository?.localPath === "string"
+                ? ctx.repository.localPath
+                : null;
+        if (localPath) {
+            const byPath = getRepositoryByLocalPath(this.db, localPath);
+            if (byPath)
+                return byPath;
+        }
+        const slug = typeof ctx.slug === "string"
+            ? ctx.slug
+            : typeof ctx.repository?.slug === "string"
+                ? ctx.repository.slug
+                : null;
+        if (!slug || !localPath) {
+            throw new Error("git project documentation task requires repositoryId or slug/localPath task context");
+        }
+        const githubRepo = typeof ctx.githubRepo === "string"
+            ? ctx.githubRepo
+            : typeof ctx.repository?.githubRepo === "string"
+                ? ctx.repository.githubRepo
+                : null;
+        const [githubOwner, githubRepoName] = parseGithubRepoSlug(githubRepo);
+        const now = Date.now();
+        return {
+            id: repositoryId ?? (githubRepo ? `github:${githubRepo}` : `local:${slug}`),
+            githubOwner,
+            githubRepo: githubRepoName,
+            githubAccount: null,
+            localPath,
+            localOnly: githubRepo === null,
+            displayName: typeof ctx.displayName === "string" ? ctx.displayName : slug,
+            classification: normalizeRepositoryClassification(ctx.classification),
+            category: normalizeRepositoryCategory(ctx.category),
+            pollPriority: "normal",
+            pollIntervalSec: null,
+            slug,
+            createdAt: now,
+            updatedAt: now,
+        };
+    }
+    markScheduledTaskCompleted(event) {
+        if (!event.scheduleId)
+            return;
+        this.db
+            .prepare("UPDATE agent_schedule SET status = 'completed' WHERE id = ? AND status = 'running'")
+            .run(event.scheduleId);
+    }
+    async executeScheduledRoutine(event, routine) {
+        const routineEvent = {
+            ...createEvent({
+                type: `routine.${routine}`,
+                source: typeof event.taskContext.source === "string"
+                    ? event.taskContext.source
+                    : event.source,
+                priority: EventPriority.NORMAL,
+                correlationId: event.correlationId,
+                data: {
+                    ...event.taskContext,
+                    scheduleId: event.scheduleId ?? null,
+                },
+            }),
+            routine,
+            ...(event.requestedModel ? { requestedModel: event.requestedModel } : {}),
+        };
+        try {
+            await this.executeDefault(routineEvent);
+            if (event.scheduleId) {
+                this.db
+                    .prepare("UPDATE agent_schedule SET status = 'completed' WHERE id = ? AND status = 'running'")
+                    .run(event.scheduleId);
+            }
+        }
+        catch (err) {
+            if (event.scheduleId) {
+                this.db
+                    .prepare("UPDATE agent_schedule SET status = 'failed' WHERE id = ? AND status = 'running'")
+                    .run(event.scheduleId);
+            }
+            throw err;
+        }
+    }
+    /**
+     * 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.
+     */
+    async handleMorningRoutineRetry(event, taskCtx) {
+        const retryCount = Number(taskCtx.retryCount ?? 0);
+        // O1: early skip only when the current agent day's today.md already exists
+        if (this.hasCurrentAgentDayTodayMd()) {
+            logger.info({
+                retryCount,
+                originalCorrelationId: taskCtx.originalCorrelationId,
+            }, "Morning routine retry skipped — today.md already exists (cron likely raced us)");
+            if (event.scheduleId) {
+                this.db
+                    .prepare("UPDATE agent_schedule SET status = 'completed' WHERE id = ? AND status = 'running'")
+                    .run(event.scheduleId);
+            }
+            return;
+        }
+        // Synthesize a RoutineEvent for executeMorningRoutine. event.data.retryCount
+        // carries the previous attempt so executeMorningRoutine → scheduleMorningRetry
+        // can increment properly. correlationId tracks back to the original
+        // cron morning_routine for log correlation.
+        const synthEvent = {
+            ...createEvent({
+                type: "routine.morning_routine",
+                source: typeof taskCtx.source === "string"
+                    ? taskCtx.source
+                    : retryCount > 0
+                        ? `morning_routine_retry_${retryCount}`
+                        : "scheduled_morning_routine",
+                priority: retryCount > 0 ? EventPriority.NORMAL : EventPriority.HIGH,
+                correlationId: taskCtx.originalCorrelationId ?? event.correlationId,
+                data: {
+                    ...(retryCount > 0 ? { retryCount, isRetry: true } : {}),
+                    ...(Array.isArray(taskCtx.postCatchupRoutines)
+                        ? { postCatchupRoutines: taskCtx.postCatchupRoutines }
+                        : {}),
+                    ...(taskCtx.postCatchupHourlyCheck === true
+                        ? { postCatchupHourlyCheck: true }
+                        : {}),
+                    ...(typeof taskCtx.source === "string"
+                        ? { queuedSource: taskCtx.source }
+                        : {}),
+                },
+            }),
+            routine: "morning_routine",
+        };
+        logger.info({ retryCount, correlationId: synthEvent.correlationId }, "Morning routine retry — routing to executeMorningRoutine with synthesized RoutineEvent");
+        await this.executeMorningRoutine(synthEvent);
+        // Mark the wake task row completed — executeMorningRoutine doesn't know about
+        // scheduleId since it received a RoutineEvent, not an AgentTaskEvent.
+        if (event.scheduleId) {
+            this.db
+                .prepare("UPDATE agent_schedule SET status = 'completed' WHERE id = ? AND status = 'running'")
+                .run(event.scheduleId);
+        }
+    }
+    hasCurrentAgentDayTodayMd() {
+        return this.diagnoseTodayMdState().kind === "fresh";
+    }
+    /**
+     * 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).
+     */
+    diagnoseTodayMdState() {
+        const todayPath = join(getContextDir(this.config, this.db), "today.md");
+        if (!existsSync(todayPath)) {
+            return { kind: "missing" };
+        }
+        const content = readFileSync(todayPath, "utf-8");
+        const writtenDate = content.match(/^#.*(\d{4}-\d{2}-\d{2})/)?.[1];
+        if (!writtenDate) {
+            return { kind: "no_h1_date" };
+        }
+        const expectedAgentDay = getAgentDayDateStr(this.config.timezone || undefined, this.config.dayBoundaryHour);
+        if (writtenDate !== expectedAgentDay) {
+            return { kind: "wrong_date", writtenDate, expectedAgentDay };
+        }
+        return { kind: "fresh" };
+    }
+    /**
+     * 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).
+     */
+    rotateDayFiles() {
+        const contextDir = getContextDir(this.config, this.db);
+        const todayPath = join(contextDir, "today.md");
+        if (!existsSync(todayPath))
+            return;
+        const content = readFileSync(todayPath, "utf-8");
+        const dateStr = content.match(/^#.*(\d{4}-\d{2}-\d{2})/)?.[1];
+        // Skip if today.md is already today's date (no rotation needed)
+        const todayDateStr = getAgentDayDateStr(this.config.timezone || undefined, this.config.dayBoundaryHour);
+        if (dateStr === todayDateStr)
+            return;
+        if (!dateStr)
+            return;
+        // B-007 §5.9 — mechanical copy to schedule/ is retired. The only
+        // rotation artifact we preserve is a DB snapshot of the closing
+        // today.md; the synthesized `daily/YYYY-MM-DD.md` is written later by
+        // the morning routine from yesterday.md + SQLite event records.
+        // 1. Snapshot to DB for rebuild safety
+        try {
+            this.db
+                .prepare("INSERT INTO md_file_snapshots (file_path, content, trigger) VALUES (?, ?, ?)")
+                .run("today", content, "day_rotation");
+        }
+        catch (err) {
+            logger.warn({ err }, "Failed to save rotation snapshot");
+        }
+        // 2. Rename today.md → yesterday.md
+        const yesterdayPath = join(contextDir, CONTEXT_RELATIVE_PATHS.yesterday);
+        renameSync(todayPath, yesterdayPath);
+        logger.info({ archived: `schedule/${dateStr}.md` }, "Day files rotated");
+    }
+    /**
+     * 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.
+     */
+    async executeRoadmapRefresh(event) {
+        let lockId = null;
+        let effectiveEvent = event;
+        if (this.roadmapWriteLock) {
+            const lock = this.roadmapWriteLock.acquire();
+            if (!lock.ok) {
+                logger.info({
+                    eventType: event.type,
+                    source: event.source,
+                    holder: lock.holder,
+                }, "roadmap.md write lock held — skipping this refresh");
+                return;
+            }
+            lockId = lock.lockId;
+            effectiveEvent = {
+                ...event,
+                data: {
+                    ...event.data,
+                    roadmapWriteLockId: lockId,
+                },
+            };
+        }
+        try {
+            await this.executeDefault(effectiveEvent);
+        }
+        finally {
+            if (lockId && this.roadmapWriteLock) {
+                this.roadmapWriteLock.release(lockId);
+            }
+        }
+    }
+    /**
+     * 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`).
+     */
+    async executeSkillCurationRoutine(event) {
+        if (!this.materializeOptimizerWorkdir)
+            return;
+        // P22 §6.4 — manual run flag rides on the routine event's `data.manual`
+        // (set by `POST /api/skill-curation/runs/manual` from the dashboard).
+        // Cadence-driven cron events have no `manual` key, so the default is
+        // false — exactly the desired contract.
+        const eventData = event.data ?? {};
+        const manual = eventData.manual === true;
+        const targetSkillsOverride = Array.isArray(eventData.target_skills)
+            ? eventData.target_skills
+            : undefined;
+        let workdir = null;
+        try {
+            workdir = await this.materializeOptimizerWorkdir({ manual, ...(targetSkillsOverride ? { targetSkillsOverride } : {}) });
+            logger.info({ runId: workdir.runId, targetSkills: workdir.targetSkills, workdirPath: workdir.workdirPath, manual }, "Skill-curation optimizer run starting");
+            // Inject the runId + token into the event so the agent core can pick
+            // them up. The standard executor path runs from here.
+            const enriched = {
+                ...event,
+                data: {
+                    ...event.data,
+                    skill_curation_run_id: workdir.runId,
+                    skill_curation_run_token: workdir.runToken,
+                    skill_curation_workdir: workdir.workdirPath,
+                    skill_curation_target_skills: workdir.targetSkills,
+                },
+            };
+            await this.executeDefault(enriched);
+        }
+        catch (err) {
+            logger.error({ err, runId: workdir?.runId }, "Skill-curation routine failed");
+            throw err;
+        }
+        finally {
+            if (workdir && this.teardownOptimizerWorkdir) {
+                try {
+                    this.teardownOptimizerWorkdir(workdir.workdirPath);
+                }
+                catch (err) {
+                    logger.warn({ err, workdirPath: workdir.workdirPath }, "Skill-curation workdir teardown failed");
+                }
+            }
+        }
+    }
+    async executeDefault(event) {
+        const context = await this.contextBuilder.build(event);
+        const processKey = resolveProcessKey(event);
+        // Honour run-now's `requestedModel` hint for routine events. Other event
+        // types (messages, scheduled.task) have their own dedicated paths that
+        // already handle tier selection, so this branch is routine-only.
+        const routineHint = isRoutineEvent(event) && event.requestedModel
+            ? event.requestedModel === "opus"
+                ? "high"
+                : "medium"
+            : undefined;
+        // Knowledge-import events carry the dashboard form's backend/model
+        // pick. Honor the (backendId, modelId) pair only when the event was
+        // emitted by the dashboard route — same defense-in-depth gate as the
+        // chat picker — so a malformed event from another path cannot pin a
+        // specific model.
+        const importOverride = isKnowledgeImportEvent(event)
+            && event.platform === "dashboard"
+            && event.requestedBackendId
+            && event.requestedModelId
+            ? {
+                requestedBackendId: event.requestedBackendId,
+                requestedModelId: event.requestedModelId,
+            }
+            : undefined;
+        const binding = this.agentRouter.resolveBinding(event, {
+            processKey,
+            ...(routineHint ? { requestedTier: routineHint } : {}),
+            ...(importOverride ?? {}),
+        });
+        const reassemblePrompt = (bid) => this.assemblePrompt(event.type, processKey, bid);
+        const prompt = reassemblePrompt(binding.main.backendId);
+        // P22 §3.4 step 4 — optimizer agent runs with a hard-clamped tool
+        // envelope. The check is on event type rather than processKey so the
+        // override is impossible to widen by accident from a downstream
+        // dispatch refactor; the only path to skill_curation execution is
+        // through `routine.skill_curation` events, which have no other code
+        // path that strips the override.
+        const skillCurationOverride = isRoutineEvent(event) && event.routine === "skill_curation"
+            ? SKILL_CURATION_OPTIMIZER_ALLOWED_TOOLS
+            : undefined;
+        const result = await this.executeWithRetry(() => this.agentRouter.execute({
+            prompt,
+            context,
+            event,
+            processKey,
+            preResolvedBinding: binding,
+            reassemblePrompt,
+            ...(skillCurationOverride
+                ? { allowedToolsOverride: skillCurationOverride }
+                : {}),
+        }), event);
+        await this.processResult(result, event);
+    }
+    /**
+     * 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).
+     */
+    async handleAuthCommand(event) {
+        const text = event.content.trim().toLowerCase();
+        // `/auth status` — show current auth state
+        if (text === "/auth status") {
+            const summary = this.authHealthMonitor
+                ? this.authHealthMonitor.renderStatusSummary()
+                : "Check auth status on the dashboard or via `GET /api/backends`.";
+            await this.notificationMgr.send(summary, event);
+            return true;
+        }
+        // `/auth fix claude` — start Claude browser auth recovery (Phase 9)
+        if (text === "/auth fix claude") {
+            if (!this.authRecovery)
+                return false;
+            if (this.authRecovery.isRecoveryActive("claude")) {
+                const active = this.authRecovery.getActiveRecovery("claude");
+                await this.notificationMgr.send(`Claude auth recovery already in progress.\n` +
+                    `URL: ${active?.authUrl}`, event);
+                return true;
+            }
+            try {
+                const recovery = await this.authRecovery.initiateClaudeAuth();
+                await this.notificationMgr.send(`Claude auth recovery started.\n` +
+                    `Open the following URL in your browser to sign in:\n${recovery.authUrl}` +
+                    `\n(timeout in ${recovery.expiresMinutes} min)`, event);
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : "Unknown error";
+                await this.notificationMgr.send(`Failed to start Claude auth recovery: ${msg}`, event);
+            }
+            return true;
+        }
+        // `/auth fix codex` — start Codex device auth recovery
+        if (text === "/auth fix codex") {
+            if (!this.authRecovery)
+                return false;
+            if (this.authRecovery.isRecoveryActive("codex")) {
+                const active = this.authRecovery.getActiveRecovery("codex");
+                await this.notificationMgr.send(`Codex auth recovery already in progress.\n` +
+                    `URL: ${active?.authUrl}\nCode: ${active?.userCode}`, event);
+                return true;
+            }
+            try {
+                const recovery = await this.authRecovery.initiateCodexDeviceAuth();
+                // The recovery itself sends a notification with URL/code,
+                // but also reply directly to the DM for immediate feedback.
+                await this.notificationMgr.send(`Codex auth recovery started.\n` +
+                    `Open ${recovery.authUrl} in your browser and enter code ${recovery.userCode}.` +
+                    `\n(expires in ${recovery.expiresMinutes} min)`, event);
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : "Unknown error";
+                await this.notificationMgr.send(`Failed to start Codex auth recovery: ${msg}`, event);
+            }
+            return true;
+        }
+        // `/auth fix all` — recover all expired backends sequentially
+        if (text === "/auth fix all") {
+            if (!this.authRecovery || !this.authHealthMonitor)
+                return false;
+            const expired = this.authHealthMonitor.listExpiredBackends();
+            if (expired.length === 0) {
+                await this.notificationMgr.send("All backends are healthy. No recovery needed.", event);
+                return true;
+            }
+            const results = [];
+            for (const bid of expired) {
+                // Skip backends that already have an active recovery session
+                if (this.authRecovery.isRecoveryActive(bid)) {
+                    results.push(`🔄 ${bid} — Recovery already in progress.`);
+                    continue;
+                }
+                try {
+                    if (bid === "claude") {
+                        const recovery = await this.authRecovery.initiateClaudeAuth();
+                        results.push(`✅ claude — Recovery started. Open the following URL in your browser to sign in:\n${recovery.authUrl}\n(timeout in ${recovery.expiresMinutes} min)`);
+                    }
+                    else if (bid === "codex") {
+                        const recovery = await this.authRecovery.initiateCodexDeviceAuth();
+                        results.push(`✅ codex — Recovery started. Open ${recovery.authUrl} in your browser and enter code ${recovery.userCode} (expires in ${recovery.expiresMinutes} min).`);
+                    }
+                    else if (bid === "gemini") {
+                        const recovery = await this.authRecovery.initiateGeminiAuth();
+                        results.push(`✅ gemini — Recovery started. Open the following URL in your browser and authenticate, then send the code here:\n${recovery.authUrl}\n(expires in ${recovery.expiresMinutes} min)`);
+                    }
+                    else {
+                        results.push(`⚠️ ${bid} — No automated recovery available for this backend.`);
+                    }
+                }
+                catch (err) {
+                    const msg = err instanceof Error ? err.message : "Unknown error";
+                    results.push(`❌ ${bid} — Failed to start recovery: ${msg}`);
+                }
+            }
+            const summary = this.authHealthMonitor.renderStatusSummary();
+            await this.notificationMgr.send(`Auth recovery results:\n\n${results.join("\n\n")}\n\n---\n${summary}`, event);
+            return true;
+        }
+        // `/auth fix gemini` — start Gemini OAuth recovery
+        if (text === "/auth fix gemini") {
+            if (!this.authRecovery)
+                return false;
+            if (this.authRecovery.isRecoveryActive("gemini")) {
+                const active = this.authRecovery.getActiveRecovery("gemini");
+                await this.notificationMgr.send(`Gemini auth recovery already in progress.\n` +
+                    `Open the following URL in your browser to authenticate:\n${active?.authUrl}\n` +
+                    `Then send the authorization code here.`, event);
+                return true;
+            }
+            try {
+                const recovery = await this.authRecovery.initiateGeminiAuth();
+                await this.notificationMgr.send(`Gemini auth recovery started.\n` +
+                    `Open the following URL in your browser and sign in with your Google account:\n${recovery.authUrl}\n` +
+                    `Then send the authorization code here.` +
+                    `\n(expires in ${recovery.expiresMinutes} min)`, event);
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : "Unknown error";
+                await this.notificationMgr.send(`Failed to start Gemini auth recovery: ${msg}`, event);
+            }
+            return true;
+        }
+        // `/auth cancel` — cancel active recovery
+        if (text === "/auth cancel" || text.startsWith("/auth cancel ")) {
+            if (!this.authRecovery)
+                return false;
+            const parts = text.split(/\s+/);
+            const backendHint = parts[2];
+            // Cancel all active recoveries, or a specific one
+            let cancelled = false;
+            for (const bid of ["codex", "gemini", "claude"]) {
+                if (backendHint && bid !== backendHint)
+                    continue;
+                if (this.authRecovery.cancelRecovery(bid))
+                    cancelled = true;
+            }
+            await this.notificationMgr.send(cancelled ? "Auth recovery cancelled." : "No active auth recovery to cancel.", event);
+            return true;
+        }
+        // Not an auth command
+        return false;
+    }
+    async handleMessage(event) {
+        // Bang-command interceptor — runs first so `!stop` / `!cost` / `!report`
+        // succeed even mid-setup, mid-auth-recovery, etc., and so non-bang DMs
+        // received while the agent is paused short-circuit before reaching the
+        // backend (I-3). See docs/design/backlog/messaging-bang-commands.md §6.2.
+        if (this.bangCommandRegistry) {
+            const handled = await tryHandleBangCommand(this.bangCommandRegistry, {
+                event,
+                db: this.db,
+                config: this.config,
+                audit: this.audit,
+                rawSend: (text) => this.notificationMgr.send(text, event),
+                enqueueUserBangCommand: async (command, sourceEvent) => {
+                    await this.eventBus.put(createUserBangCommandEvent(sourceEvent, command));
+                },
+            });
+            if (handled)
+                return;
+        }
+        // Cross-platform DM lockout during setup.
+        // The owner-DM scope is singular across platforms (Slack/Discord/Telegram/
+        // WhatsApp/dashboard all share one conversation_sessions row). While a
+        // dashboard setup conversation is in progress, a DM from any other
+        // platform would otherwise be routed through the active `setup.initial`
+        // / `setup.update` prompt — taking a Slack "ping" and feeding it to the
+        // rules-generator agent. Reject non-dashboard DMs with a fixed message
+        // so the user knows why we are stalling and where to finish setup.
+        // Dashboard messages are exempt so the user can still progress setup.
+        // Channel mentions (not DMs) are also exempt — they have their own
+        // session scope and do not interact with the owner-DM row.
+        if (event.isDm &&
+            event.platform !== "dashboard" &&
+            this.currentSetupMode !== null) {
+            logger.info({ platform: event.platform, mode: this.currentSetupMode }, "Non-dashboard DM rejected — setup in progress");
+            this.audit.logSkip(event, "setup_in_progress", "reactive");
+            await this.notificationMgr.send("Setup is in progress. Please complete setup on the dashboard first, then try again.", event);
+            return;
+        }
+        // Phase 6 §5.2: intercept Google OAuth auth codes during pending Gemini
+        // recovery. Must come before `/auth` command check so the code isn't
+        // treated as an unknown command or routed to the agent backend.
+        if (event.isDm && this.authRecovery?.isRecoveryActive("gemini")) {
+            const code = parseGeminiAuthCode(event.content);
+            if (code) {
+                try {
+                    const result = await this.authRecovery.handleGeminiAuthCode(code);
+                    const icon = result.ok ? "✅" : "❌";
+                    await this.notificationMgr.send(`${icon} Gemini auth: ${result.detail}`, event);
+                }
+                catch (err) {
+                    const msg = err instanceof Error ? err.message : "Unknown error";
+                    await this.notificationMgr.send(`Failed to process Gemini auth code: ${msg}`, event);
+                }
+                return;
+            }
+        }
+        // Phase 5: intercept `/auth` commands before they reach the agent backend.
+        // Gated on DM + at least one auth subsystem being available (/auth status
+        // only needs the monitor; /auth fix needs the recovery manager).
+        if (event.isDm && (this.authRecovery || this.authHealthMonitor)) {
+            const authResult = await this.handleAuthCommand(event);
+            if (authResult)
+                return;
+        }
+        // Check for explicit close command before processing.
+        // Use findActive (not getOrCreate) to avoid creating an orphan session.
+        if (this.sessionMgr.isCloseCommand(event.content)) {
+            const existing = await this.sessionMgr.findActive({
+                platform: event.platform,
+                channel: event.channel,
+                threadId: event.threadId,
+                isDm: event.isDm,
+                intent: event.intent,
+            });
+            if (existing) {
+                // recordMessage persists the row and touches
+                // last_message_at/message_count in a single transaction, so
+                // retention + dashboard sidebar stay consistent with the actual
+                // `messages` row count. closeSession then flips status.
+                this.messageRecorder.recordMessage({
+                    sessionId: existing.id,
+                    role: "user",
+                    content: event.content,
+                    platform: event.platform,
+                    senderId: event.sender,
+                });
+                this.sessionMgr.closeSession(existing.id);
+            }
+            await this.notificationMgr.send("Session closed.", event);
+            return;
+        }
+        const replyActivity = await this.notificationMgr.beginReplyActivity(event);
+        let turnToken = null;
+        // STAGE-C-DM-FRESHNESS-PLAN §Task 4 — capture the turn-start reference
+        // BEFORE any context_write/context_read row could be written during
+        // this turn. Used as the upper bound when counting writes the agent
+        // missed pre-resume, and as the lower bound when detecting whether
+        // the agent issued a refetch during the current turn.
+        const turnStartedAtSqlite = formatSqliteDatetime(new Date());
+        try {
+            // Docs-QA traffic is a side-channel that must never participate in
+            // setup state. Two invariants enforced here:
+            //   1. A docs_qa event with a smuggled `data.setupMode` must NOT
+            //      flip the dispatcher's global `currentSetupMode` — that would
+            //      hijack subsequent owner DMs into the rules-generator agent.
+            //   2. A docs_qa event arriving while `currentSetupMode` is already
+            //      set (operator opens Docs QA in another tab during setup)
+            //      must still resolve via `dashboard.docs_qa` so TIER_LOCKED
+            //      fires and the QA workdir/skill set is materialized — not the
+            //      setup processKey/light tier/setup skill set. Without this
+            //      gate, the §11.2 promptKey fix would load the QA prompt while
+            //      the binding/workdir came from setup, producing an incoherent
+            //      "QA prompt + setup tools" execution.
+            const eventSetupMode = event.data?.setupMode;
+            const isDocsQA = isDocsQAMessage(event);
+            if (eventSetupMode && this.currentSetupMode === null && !isDocsQA) {
+                // Defensive sync — normally `/setup/start` has already called
+                // beginSetupMode, but this keeps prompt selection consistent even if
+                // a future caller bypasses the helper and only sets event.data.
+                this.beginSetupMode(eventSetupMode);
+            }
+            const setupMode = isDocsQA
+                ? null
+                : (eventSetupMode ?? this.currentSetupMode);
+            const processKey = setupMode === "initial" || setupMode === "update"
+                ? "setup"
+                : resolveProcessKey(event);
+            // Honor the dashboard chat model picker. MessageEvent.requestedModel
+            // and the (requestedBackendId, requestedModelId) pair are only
+            // populated by the dashboard adapter (see POST /chat/messages in
+            // api/routes/sse.ts); other platforms never set them. Defense-in-depth:
+            // even if a future adapter were to set them, we gate on platform here
+            // so Slack/Telegram/Discord/WhatsApp can never force a specific model
+            // through these fields. Setup mode also ignores them — setup runs on
+            // the configured setup process key regardless of the user's pick.
+            //
+            // When both the explicit (backendId, modelId) pair and the legacy
+            // requestedModel are set, the pair wins: it is the superset that
+            // supports all backends and models, not just Claude sonnet/opus.
+            const honorOverride = (event.platform === "dashboard" || event.source === CUSTOM_BANG_COMMAND_SOURCE)
+                && !setupMode;
+            const requestedTier = honorOverride && event.requestedModel
+                ? event.requestedModel === "sonnet"
+                    ? "medium"
+                    : "high"
+                : undefined;
+            const overrideBackendId = honorOverride && event.requestedBackendId && event.requestedModelId
+                ? event.requestedBackendId
+                : undefined;
+            const overrideModelId = honorOverride && event.requestedBackendId && event.requestedModelId
+                ? event.requestedModelId
+                : undefined;
+            const route = this.agentRouter.resolveBinding(event, {
+                processKey,
+                ...(requestedTier ? { requestedTier } : {}),
+                ...(overrideBackendId && overrideModelId
+                    ? { requestedBackendId: overrideBackendId, requestedModelId: overrideModelId }
+                    : {}),
+            });
+            const session = await this.sessionMgr.getOrCreate({
+                platform: event.platform,
+                channel: event.channel,
+                threadId: event.threadId,
+                isDm: event.isDm,
+                intent: event.intent,
+                requiredBackend: route.main.backendId,
+                requiredModel: route.main.modelId,
+            });
+            const forwardContextAvailable = this.hasRecentProactiveForwardContext(event, session.id);
+            // Custom messaging bang command (`!commandname`): the owner's
+            // saved row carries an opt-in skill set + an optional custom
+            // profile body. We forward those to `ensureSessionWorkdir` as a
+            // re-materialize override so the agent runs with the row's
+            // configuration for THIS turn. The override forces re-write of
+            // CLAUDE.md / AGENTS.md / GEMINI.md and the skill dirs even when
+            // the workdir already exists (regular DMs share the same dir).
+            // The next regular DM turn detects the bang stamp file written
+            // by `ensureSessionWorkdir` and re-materializes back to manifest
+            // defaults — keeping `!cmd` configurations from leaking into a
+            // natural conversation that follows.
+            const customBangCommand = this.lookupCustomBangCommandForEvent(event);
+            const workdirOverride = customBangCommand
+                ? {
+                    skillSlugs: [...resolveCommandSkillSlugs(customBangCommand)],
+                    profileBody: customBangCommand.instructionMd,
+                }
+                : undefined;
+            // Skip the owner-channel pairing record for docs_qa: the QA panel
+            // is not a messaging-app surface and would otherwise clutter
+            // /connections/messaging with synthetic "dashboard" pairings.
+            //
+            // `pendingConnectorWarnings` is captured here so both the resume and
+            // fresh-execute branches below can call the §4.5 DM dispatch via
+            // `dispatchPendingConnectorHealth()` AFTER each branch's user-message
+            // recordMessage — the dispatch's persist must follow the user message
+            // in DB-timestamp order or the dashboard's chat_meta history reload
+            // reorders the bubbles.
+            let pendingConnectorWarnings = [];
+            const dispatchPendingConnectorHealth = () => {
+                if (pendingConnectorWarnings.length === 0)
+                    return;
+                this.runDelegatedConnectorWarningDispatch(pendingConnectorWarnings, event, route.main.backendId, session.id);
+            };
+            if (event.isDm && !isDocsQAMessage(event)) {
+                upsertOwnerChannel(this.db, {
+                    platform: event.platform,
+                    senderId: event.sender,
+                    channelId: event.channel,
+                    metadata: { threadId: event.threadId },
+                    touchInbound: true,
+                });
+                // 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. If the cached probe shows
+                // missing required capabilities (the wizard / a future periodic
+                // re-probe wrote `present=false`), fire a one-shot DM warning the
+                // owner that same-backend mode is non-functional. The helper
+                // dedupes via `runtime_state` so resume-vs-fresh-execute do not
+                // spam the user. Cheap, synchronous DB-only inspection — runs on
+                // the hot path so the warning lands before the agent's reply.
+                //
+                // Skipped while the dispatcher is in setup mode: the wizard's
+                // background `probeLive` call may have just landed a `present=false`
+                // row for a connector the user is in the middle of authorising, and
+                // a DM telling them to "Re-authorize from your … connector
+                // settings, then re-run the integration probe from the dashboard"
+                // is wrong-tense for the in-flight setup conversation. The §10
+                // post-setup sign-out scenario the check exists for fires correctly
+                // on the first DM after `clearSetupMode` runs.
+                //
+                // Two-phase: consult the cached probe NOW (synchronous DB read),
+                // but defer the actual DM dispatch + dashboard messages-table
+                // persist until both branches below have recorded the inbound user
+                // message. Otherwise the warning's persist row carries a
+                // CURRENT_TIMESTAMP that lands BEFORE the user-message row's, and
+                // the dashboard's chat_meta history reload re-orders the bubbles
+                // (warning above user) — a one-time UX flicker.
+                pendingConnectorWarnings =
+                    this.currentSetupMode === null
+                        ? this.consultDelegatedConnectorWarnings(route.main.backendId)
+                        : [];
+            }
+            // `event.channel` is captured at the moment the user POSTed their
+            // message. If the tab navigates away and reconnects, the SSE route
+            // calls `rebindSessionChannel` to update `conversation_sessions.
+            // channel_id` to the new UUID — but our closure here still holds
+            // the old value. `resolveDashboardChannel` reads the live DB value
+            // on every send so stream/meta/info/error events reach whichever
+            // tab is currently connected for this session.
+            const resolveDashboardChannel = () => this.sessionMgr.getActiveChannelIdForSession(session.id) ?? event.channel;
+            // Send resolved model info + DB session ID to dashboard so the
+            // sidebar badge is accurate and the frontend can persist the session.
+            if (event.platform === "dashboard" && this.dashboardStream?.sendSessionInfo) {
+                this.dashboardStream.sendSessionInfo(resolveDashboardChannel(), {
+                    sessionId: session.id,
+                    model: route.main.modelId,
+                    backend: route.main.backendId,
+                    modelLabel: getModelLabel(route.main.backendId, route.main.modelId),
+                });
+            }
+            // Feed user message to SignalDetector for implicit feedback
+            // detection. Docs-QA messages are docs lookups, not feedback
+            // signals, so they bypass the detector entirely.
+            if (!isDocsQAMessage(event)) {
+                this.signalDetector?.onUserMessage({
+                    platform: event.platform,
+                    content: event.content,
+                });
+            }
+            // Create stream callbacks for dashboard events (real-time SSE text).
+            // Each callback re-resolves the channel on invocation so a user
+            // who navigates away and returns mid-execute still receives the
+            // tail of the stream on their new tab.
+            let didStream = false;
+            const streamCb = event.platform === "dashboard" && this.dashboardStream
+                ? {
+                    onText: (text) => {
+                        didStream = true;
+                        this.dashboardStream.sendStreamChunk(resolveDashboardChannel(), text);
+                    },
+                    onEnd: () => {
+                        this.dashboardStream.sendStreamEnd(resolveDashboardChannel());
+                    },
+                }
+                : undefined;
+            // Chat-attachments Phase 1 — issue a per-turn capability token the
+            // agent's `attach` skill will present via `X-Turn-Token`. Valid only
+            // while this turn is running; always cleared in the outer `finally`
+            // below so leakage is bounded to the lifetime of the turn.
+            turnToken = this.attachmentStore
+                ? this.issueAttachmentTurnToken(session.id)
+                : null;
+            // Can we resume an existing SDK session?
+            // Resume whenever this conversation already has a stored SDK session.
+            // Never resume on the FIRST message of a new setup — event.data.setupMode means
+            // "start a new setup", not "continue an existing one".
+            //
+            // Also require the session's persistent workdir to exist on disk. If
+            // it was removed out of band (manual cleanup, stale-workdir scanner
+            // bug, disk failure), attempting to resume would land the SDK in a
+            // freshly-created empty directory with no CLAUDE.md / AGENTS.md /
+            // skills tree, producing confusing output. Fall back to the fresh-
+            // execute branch, which re-materializes the workdir via
+            // `ensureSessionWorkdir`.
+            const isNewSetupStart = !!event.data?.setupMode;
+            const existingSessionDirPresent = session.isActive
+                && existsSync(getSessionWorkdirPath(this.config.dataDir, session.id));
+            const canResume = session.isActive
+                && session.sessionId
+                && existingSessionDirPresent
+                && !isNewSetupStart;
+            if (session.isActive && session.sessionId && !existingSessionDirPresent) {
+                logger.warn({ sessionId: session.id }, "Session marked resumable but workdir missing — falling back to fresh execute");
+            }
+            let result;
+            let userMessageId = null;
+            // STAGE-C-DM-FRESHNESS-PLAN §Task 2 — `<turn_context>` is injected on
+            // resume only. The resume payload is the bare user-message text; the
+            // SDK's cached system prompt holds the original `<current_time>` and
+            // the snapshot anchored by `<today snapshot_at="...">` (Task 1), both
+            // frozen at session start. Without a per-turn fresh-clock anchor, the
+            // model cannot compute "how stale is my snapshot" and answers from
+            // an out-of-date view of `## Agent Log`. On the fresh-execute branch,
+            // the system prompt's `<current_time>` is built at the moment of
+            // dispatch — adding `<turn_context>` there would be redundant AND
+            // would diverge the prompt prefix per turn, defeating prompt caching.
+            // If a future change rebuilds `<today>` mid-session, this code must
+            // be revisited because `started_at` would no longer be the snapshot
+            // reference.
+            let resumeTurnContext = null;
+            let resumeSnapshotAgeMinutes = 0;
+            if (canResume) {
+                // ── Resume existing SDK session ──
+                const proactiveForwardContext = forwardContextAvailable
+                    ? await this.contextBuilder.build(event)
+                    : null;
+                const userMsgRecorded = this.messageRecorder.recordMessage({
+                    sessionId: session.id,
+                    role: "user",
+                    content: event.content,
+                    platform: event.platform,
+                    senderId: event.sender,
+                });
+                if (userMsgRecorded) {
+                    userMessageId = this.readLastInsertedMessageId(session.id);
+                }
+                // Compute the freshness anchors for this resumed turn. `started_at`
+                // is the moment `<today>` was captured (the fresh-execute branch
+                // builds the system prompt then). Reading from the session row
+                // (rather than the in-memory `session` value) keeps this side-
+                // effect-free: the row was just fetched by `getOrCreate` and is
+                // authoritative.
+                const turnNow = new Date();
+                const sessionTimingRow = this.db
+                    .prepare(`SELECT started_at FROM conversation_sessions WHERE id = ?`)
+                    .get(session.id);
+                const sessionStartedAtSqlite = sessionTimingRow?.started_at ?? null;
+                const sessionStartedAtMs = sessionStartedAtSqlite
+                    ? parseSqliteUtcMs(sessionStartedAtSqlite)
+                    : turnNow.getTime();
+                resumeSnapshotAgeMinutes = Math.max(0, Math.round((turnNow.getTime() - sessionStartedAtMs) / 60_000));
+                resumeTurnContext =
+                    `<turn_context current_time="${turnNow.toISOString()}" `
+                        + `snapshot_age_minutes="${resumeSnapshotAgeMinutes}" />`;
+                // §4.5 connector-health DM is dispatched AFTER recordMessage so the
+                // warning's messages-table row carries a strictly-later timestamp
+                // than the user message. See `consultDelegatedConnectorWarnings`.
+                dispatchPendingConnectorHealth();
+                const sessionDir = ensureSessionWorkdir(this.config.workspaceDir, this.config.dataDir, session.id, event.type, {
+                    backendId: session.backend ?? "claude",
+                    processKey: route.processKey,
+                    configuredServices: this.getConfiguredServices(),
+                    mailAccounts: this.getActiveMailAccounts(),
+                    integrations: readIntegrations(this.db),
+                    character: this.config.character,
+                    ...(workdirOverride ? { override: workdirOverride } : {}),
+                });
+                // Sync user-authored skills into the workdir before resuming, so any
+                // skill added/edited/deleted via /api/skills since the last turn is
+                // visible to the SDK's `.claude/skills/` discovery. Cheap and idempotent.
+                syncAllUserSkills(sessionDir, join(this.config.dataDir, "skills"));
+                // Phase 1 — stage inbound attachments + bind rows + append
+                // bracketed prompt block. For resume we can't prepend to the
+                // task-flow template (there isn't one on this path), so the
+                // attachment block is appended to the user's message text. A
+                // Claude SDK `query()` call sees `prompt` as a single string, so
+                // this is the only surface available.
+                const resumeStaged = isMessageEvent(event)
+                    ? this.stageInboundAttachments(event, sessionDir)
+                    : [];
+                if (resumeStaged.length > 0 && userMessageId !== null && this.attachmentStore) {
+                    this.attachmentStore.bindInbound({
+                        attachmentIds: resumeStaged.map((r) => r.id),
+                        sessionId: session.id,
+                        messageId: userMessageId,
+                    });
+                }
+                const resumeTranscripts = await this.transcribeAttachments(resumeStaged);
+                const resumeMessage = resumeStaged.length > 0
+                    ? `${event.content}\n${this.buildAttachmentPromptBlock(resumeStaged, resumeTranscripts)}`
+                    : event.content;
+                const resumeMessageWithForwardContext = proactiveForwardContext
+                    ? `${resumeTurnContext}\n\n${proactiveForwardContext}\n\n<current_user_message>\n${resumeMessage}\n</current_user_message>`
+                    : `${resumeTurnContext}\n\n${resumeMessage}`;
+                const resumeStagedForBackend = resumeStaged.length > 0
+                    ? resumeStaged.map((row) => ({
+                        id: row.id,
+                        safeFilename: row.safeFilename,
+                        mimeType: row.mimeType,
+                        absolutePath: `${sessionDir}/_attachments/${row.safeFilename}`,
+                        relativePath: `_attachments/${row.safeFilename}`,
+                    }))
+                    : [];
+                result = await this.executeWithRetry(() => this.agentRouter.executeResume({
+                    backendId: session.backend ?? "claude",
+                    sessionId: session.sessionId,
+                    message: resumeMessageWithForwardContext,
+                    modelId: route.main.modelId,
+                    maxTurns: route.main.maxTurns,
+                    maxBudgetUsd: route.main.maxBudgetUsd,
+                    sessionDir,
+                    sessionDbId: session.id,
+                    eventCorrelationId: event.correlationId,
+                    ...(turnToken ? { turnToken } : {}),
+                    ...(resumeStagedForBackend.length > 0
+                        ? { stagedAttachments: resumeStagedForBackend }
+                        : {}),
+                }, streamCb), event);
+            }
+            else {
+                // ── Fresh execute ──
+                // Docs-QA branches FIRST. Without this gate, `event.isDm` would
+                // route the QA event into the generic DM task flow and the
+                // agent would run without the QA system prompt (citation
+                // enforcement, search budget, "no write tools"). The
+                // `dashboard.docs_qa` task flow lives at
+                // agent-assets/task-flows/dashboard.docs_qa.md.
+                const promptKey = isDocsQAMessage(event)
+                    ? "dashboard.docs_qa"
+                    : setupMode === "initial"
+                        ? "setup.initial"
+                        : setupMode === "update"
+                            ? "setup.update"
+                            : event.isDm && !session.isActive
+                                ? "message.received.dm_first"
+                                : event.isDm
+                                    ? "message.received.dm"
+                                    : event.type;
+                const context = await this.contextBuilder.build(event);
+                // Setup flows route through processKey="setup" for backend binding,
+                // but the workdir must materialize with the mode-specific processKey
+                // so `setup.update` doesn't inherit `setup.initial`'s skill set via
+                // PROCESS_TO_EVENT_TYPE["setup"]="setup.initial".
+                const workdirEventType = setupMode ? `setup.${setupMode}` : promptKey;
+                const workdirProcessKey = setupMode
+                    ? `setup.${setupMode}`
+                    : route.processKey;
+                const reassemblePrompt = (bid) => this.assemblePrompt(promptKey, route.processKey, bid);
+                const prompt = reassemblePrompt(route.main.backendId);
+                // DMs need persistent workdirs/session ids for real resume semantics.
+                // Channel/thread conversations only persist high-tier sessions.
+                const shouldPersistSessionState = event.isDm || route.resolvedTier === "high";
+                const sessionDir = shouldPersistSessionState
+                    ? ensureSessionWorkdir(this.config.workspaceDir, this.config.dataDir, session.id, workdirEventType, {
+                        backendId: route.main.backendId,
+                        processKey: workdirProcessKey,
+                        configuredServices: this.getConfiguredServices(),
+                        mailAccounts: this.getActiveMailAccounts(),
+                        integrations: readIntegrations(this.db),
+                        character: this.config.character,
+                        ...(workdirOverride ? { override: workdirOverride } : {}),
+                    })
+                    : undefined;
+                // Re-sync user skills on every Opus message. ensureSessionWorkdir is
+                // idempotent and skips the copy step on subsequent calls, so without
+                // this explicit sync a skill created mid-session (via POST /api/skills)
+                // would never reach the session's `.claude/skills/` tree and the SDK
+                // wouldn't discover it. The sync is a cheap diff operation backed by
+                // a manifest file inside the workdir.
+                if (sessionDir) {
+                    syncAllUserSkills(sessionDir, join(this.config.dataDir, "skills"));
+                }
+                // Docs-QA sessions are stateless lookups (DOCS_QA_B7_DESIGN.md
+                // §11.6 — "QA panel state lives in React state, not the DB").
+                // After a docs_qa session reset (day boundary, model switch),
+                // session-manager's `requiresHistoryInjection` would still fire
+                // because prior messages exist in the docs_qa scope; without
+                // this gate they'd bleed back into the prompt as cross-session
+                // history, contradicting the stateless contract and silently
+                // ballooning the QA token budget across days.
+                const conversationHistory = session.requiresHistoryInjection && !isDocsQAMessage(event)
+                    ? this.buildCrossSessionConversationHistory(event)
+                    : null;
+                // Record user message AFTER context/history build (avoids injecting
+                // the current turn into cross-session history) but BEFORE execute
+                // (ensures DB has the message even if execute crashes).
+                const freshUserMsgRecorded = this.messageRecorder.recordMessage({
+                    sessionId: session.id,
+                    role: "user",
+                    content: event.content,
+                    platform: event.platform,
+                    senderId: event.sender,
+                });
+                if (freshUserMsgRecorded) {
+                    userMessageId = this.readLastInsertedMessageId(session.id);
+                }
+                // §4.5 connector-health DM is dispatched AFTER recordMessage so the
+                // warning's messages-table row carries a strictly-later timestamp
+                // than the user message. See `consultDelegatedConnectorWarnings`.
+                dispatchPendingConnectorHealth();
+                // Phase 1 — stage inbound attachments + bind rows + append
+                // bracketed prompt block to the prompt body.
+                const freshStaged = isMessageEvent(event)
+                    ? this.stageInboundAttachments(event, sessionDir)
+                    : [];
+                if (freshStaged.length > 0 && userMessageId !== null && this.attachmentStore) {
+                    this.attachmentStore.bindInbound({
+                        attachmentIds: freshStaged.map((r) => r.id),
+                        sessionId: session.id,
+                        messageId: userMessageId,
+                    });
+                }
+                const freshTranscripts = await this.transcribeAttachments(freshStaged);
+                const executePrompt = freshStaged.length > 0
+                    ? `${prompt}\n${this.buildAttachmentPromptBlock(freshStaged, freshTranscripts)}`
+                    : prompt;
+                // DMs should always persist backend sessions so same-session resume and
+                // dashboard history continue do not fall back to history reinjection.
+                const persistSession = shouldPersistSessionState;
+                const freshStagedForBackend = freshStaged.length > 0 && sessionDir
+                    ? freshStaged.map((row) => ({
+                        id: row.id,
+                        safeFilename: row.safeFilename,
+                        mimeType: row.mimeType,
+                        absolutePath: `${sessionDir}/_attachments/${row.safeFilename}`,
+                        relativePath: `_attachments/${row.safeFilename}`,
+                    }))
+                    : [];
+                result = await this.executeWithRetry(() => this.agentRouter.execute({
+                    prompt: executePrompt,
+                    context,
+                    event,
+                    processKey: setupMode === "initial" || setupMode === "update"
+                        ? "setup"
+                        : resolveProcessKey(event),
+                    sessionDir,
+                    sessionDbId: session.id,
+                    persistSession,
+                    conversationHistory: conversationHistory ?? undefined,
+                    preResolvedBinding: route,
+                    workdirEventType,
+                    workdirProcessKey,
+                    reassemblePrompt,
+                    ...(turnToken ? { turnToken } : {}),
+                    ...(freshStagedForBackend.length > 0
+                        ? { stagedAttachments: freshStagedForBackend }
+                        : {}),
+                }, streamCb), event);
+                // Store SDK sessionId for future resume, including normal owner DMs.
+                if (persistSession && result.sessionId) {
+                    await this.sessionMgr.updateSession(session.id, result.sessionId, result.modelId ?? result.model, result.backendId);
+                }
+                else if (persistSession && !result.sessionId) {
+                    // Successful DM/heavy execute, but the backend didn't emit a
+                    // resumable session id (observed with certain Gemini CLI
+                    // streams where the `init` event fired without `session_id`).
+                    // The row keeps its previous `backend_session_id` (possibly
+                    // NULL) and the next turn will fall through to fresh-execute
+                    // + history injection — still resumable from the sidebar via
+                    // the relaxed gate. Log so this stops being invisible.
+                    logger.warn({
+                        sessionId: session.id,
+                        backend: result.backendId,
+                        model: result.modelId ?? result.model,
+                    }, "Execute completed without a backend session id — next resume will rebuild via history injection");
+                }
+            }
+            // Record assistant response. `recordMessage` also bumps the
+            // session's `last_message_at` and `message_count` in the same
+            // transaction, so nothing else needs to touch the session row here.
+            let assistantMessageId = null;
+            let assistantOutput = result.output.trim();
+            // Docs-QA persistence-side citation validator (DOCS_QA_B7_DESIGN.md
+            // §11.1). The streaming side runs in DocsQAAdapter.sendStreamChunk;
+            // this one-shot pass guarantees the persisted `messages.content`
+            // matches what the dashboard rendered on reload — without it, an
+            // invalid `[doc:slug]` token would be stripped from the SSE wire
+            // but reappear in history. Slug-missing tokens are also logged to
+            // `agent_actions(action_type='qa_invalid_citation')`.
+            if (isDocsQAMessage(event)
+                && this.docsCitationLookup
+                && assistantOutput.length > 0) {
+                const validation = validateAndRewrite(assistantOutput, this.docsCitationLookup);
+                assistantOutput = validation.text;
+                logInvalidCitations(this.db, validation, { sessionId: session.id });
+            }
+            if (assistantOutput.length > 0) {
+                const persisted = this.messageRecorder.recordMessage({
+                    sessionId: session.id,
+                    role: "assistant",
+                    content: assistantOutput,
+                    platform: event.platform,
+                    backend: result.backendId,
+                    modelId: result.modelId ?? result.model,
+                });
+                if (persisted) {
+                    assistantMessageId = this.readLastInsertedMessageId(session.id);
+                    if (forwardContextAvailable) {
+                        this.logProactiveForwardDisavowalIfMatched(session.id, assistantOutput);
+                    }
+                }
+                if (!persisted && event.platform === "dashboard" && this.dashboardStream?.sendError) {
+                    // The agent produced a response but we couldn't persist it. The
+                    // dashboard tab has no other signal that the turn finished —
+                    // without this inline surfacing the user would watch the reply
+                    // stream in, then hit the 120s waiting timeout on refresh with
+                    // no history row to reconcile against. Tell them directly.
+                    this.dashboardStream.sendError(resolveDashboardChannel(), "The agent's reply could not be saved. Please try again.");
+                }
+            }
+            else {
+                // Agent returned no output — send error feedback so the user isn't left waiting
+                const errorMsg = "Could not generate a response. Please try again.";
+                logger.warn({ sessionId: session.id, isError: result.isError, stopReason: result.stopReason }, "Agent returned empty output for message event");
+                this.messageRecorder.recordMessage({
+                    sessionId: session.id,
+                    role: "assistant",
+                    content: errorMsg,
+                    platform: event.platform,
+                    backend: result.backendId,
+                    modelId: result.modelId ?? result.model,
+                });
+                // Send error to dashboard chat so the user sees it inline
+                if (event.platform === "dashboard" && this.dashboardStream?.sendError) {
+                    this.dashboardStream.sendError(resolveDashboardChannel(), errorMsg);
+                }
+                await this.notificationMgr.send(errorMsg, event);
+            }
+            // Send message metadata to dashboard for per-message footer display.
+            // This is also the client's cue to refetch history after a mid-execute
+            // reconnect — the chunks that arrived before the user reopened the tab
+            // were dropped into the old channel, so the live messages state may be
+            // missing content that is already in the DB.
+            if (event.platform === "dashboard" && this.dashboardStream?.sendMessageMeta) {
+                this.dashboardStream.sendMessageMeta(resolveDashboardChannel(), {
+                    backend: result.backendId,
+                    model: result.modelId ?? result.model,
+                    durationMs: result.durationMs,
+                    costUsd: result.costUsd,
+                });
+            }
+            // Update session-level model info with actual execution result.
+            // This corrects the pre-execution estimate when fallback kicked in,
+            // and pushes the cumulative costUsd to the sidebar badge.
+            if (event.platform === "dashboard" && this.dashboardStream?.sendSessionInfo) {
+                const actualModel = result.modelId ?? result.model;
+                const actualBackend = result.backendId ?? route.main.backendId;
+                this.dashboardStream.sendSessionInfo(resolveDashboardChannel(), {
+                    model: actualModel,
+                    backend: actualBackend,
+                    modelLabel: getModelLabel(actualBackend, actualModel),
+                    costUsd: result.costUsd,
+                });
+            }
+            // Chat-attachments Phase 1 — collect outbound files the agent
+            // produced during this turn and deliver them via the originating
+            // adapter. Currently only the Dashboard adapter delivers outbound
+            // attachments on-wire; other platforms ignore the `attachments`
+            // field until Phase 2.
+            if (turnToken
+                && this.attachmentStore
+                && assistantMessageId !== null
+                && assistantOutput.length > 0) {
+                const outboundRows = this.attachmentStore.collectOutboundForTurn({
+                    turnToken,
+                    sessionId: session.id,
+                });
+                if (outboundRows.length > 0) {
+                    for (const row of outboundRows) {
+                        this.attachmentStore.bindOutboundToMessage(row.id, assistantMessageId);
+                    }
+                    if (event.platform === "dashboard" && this.dashboardStream?.sendAttachments) {
+                        this.dashboardStream.sendAttachments(resolveDashboardChannel(), outboundRows.map((row) => ({
+                            id: row.id,
+                            originalFilename: row.originalFilename,
+                            mimeType: row.mimeType,
+                            sizeBytes: row.sizeBytes,
+                            ...(row.caption ? { caption: row.caption } : {}),
+                        })));
+                    }
+                }
+            }
+            // STAGE-C-DM-FRESHNESS-PLAN §Task 4 — collect the per-turn DM
+            // freshness telemetry before notification + audit. Limited to DM
+            // events: the metric only makes sense for the resume-or-fresh-
+            // execute decision the message dispatch makes. We compute counts
+            // bounded by the captured `turnStartedAtSqlite` so writes the
+            // agent itself made during THIS turn are not folded back in.
+            const dmFreshness = event.isDm
+                ? this.collectDmFreshnessTelemetry({
+                    sessionId: session.id,
+                    canResume: Boolean(canResume),
+                    resumeSnapshotAgeMinutes,
+                    turnStartedAtSqlite,
+                    userContent: event.content,
+                })
+                : undefined;
+            // Skip notification if we already streamed (avoids duplicate message)
+            await this.processResult(result, event, didStream, {
+                originSessionId: session.id,
+                ...(dmFreshness ? { dmFreshness } : {}),
+            });
+        }
+        finally {
+            // Always release the turn token, even on error paths. Any outbound
+            // rows the agent posted that weren't collected above fall into the
+            // orphan reaper's domain on the next daemon restart.
+            if (turnToken) {
+                this.releaseAttachmentTurnToken(turnToken);
+                this.attachmentStore?.releaseTurnToken(turnToken);
+            }
+            await replyActivity.stop();
+        }
+    }
+    /**
+     * 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) {
+        if (correlationId) {
+            this.notifiedEvents.add(correlationId);
+        }
+    }
+    /**
+     * 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.
+     */
+    collectDmFreshnessTelemetry(input) {
+        const sessionRow = this.db
+            .prepare(`SELECT started_at FROM conversation_sessions WHERE id = ?`)
+            .get(input.sessionId);
+        // Fall back to turnStart so a missing started_at yields zero counts
+        // instead of poisoning the aggregation with a wide-open lower bound.
+        const sessionStartedAtSqlite = sessionRow?.started_at ?? input.turnStartedAtSqlite;
+        const writeCounts = countContextWritesInWindow(this.db, sessionStartedAtSqlite, input.turnStartedAtSqlite);
+        // Bound the refetch window at "now" so a context_read that lands
+        // AFTER this turn's executeWithRetry returns (e.g. from a future
+        // parallel dispatcher, an unrelated routine, or a dashboard reload)
+        // is not wrongly attributed to this turn.
+        const turnEndSqlite = formatSqliteDatetime(new Date());
+        const refetchedToday = didRefetchTodayDuringTurn(this.db, input.turnStartedAtSqlite, turnEndSqlite);
+        return {
+            resumed: input.canResume,
+            // Fresh-execute branch sets resumeSnapshotAgeMinutes=0 by default;
+            // that's the correct lag because the system prompt's <today> was
+            // built at this very turn.
+            agentLogLagMinutes: input.canResume ? input.resumeSnapshotAgeMinutes : 0,
+            loudWritesSinceSessionStart: writeCounts.loud,
+            quietWritesSinceSessionStart: writeCounts.quiet,
+            refetchedToday,
+            triggerMatched: matchesRecentActivityTrigger(input.userContent),
+        };
+    }
+    async processResult(result, event, skipNotify = false, options = {}) {
+        // Notify-dedup: consume the marker (if present) so this method also
+        // serves as the cleanup point — every event run reaches processResult
+        // exactly once on the success path, and on the error path the entry
+        // is harmless (next event gets a fresh UUID).
+        const alreadyNotified = this.notifiedEvents.delete(event.correlationId);
+        const output = result.output.trim();
+        if (!skipNotify
+            && !alreadyNotified
+            && output.length > 0
+            && this.shouldNotify(event)) {
+            if (options.originSessionId !== undefined) {
+                await this.notificationMgr.send(output, event, {
+                    originSessionId: options.originSessionId,
+                });
+            }
+            else {
+                await this.notificationMgr.send(output, event);
+            }
+        }
+        this.audit.logAction({
+            event,
+            model: result.model,
+            costUsd: result.costUsd,
+            usage: result.usage,
+            modelUsage: result.modelUsage,
+            durationMs: result.durationMs,
+            numTurns: result.numTurns,
+            trigger: this.isReactive(event) ? "reactive" : "autonomous",
+            backend: result.backendId,
+            costSource: result.costSource,
+            contextUpdated: result.contextUpdated,
+            advisorCallCount: result.advisorCallCount,
+            ...(options.dmFreshness ? { dmFreshness: options.dmFreshness } : {}),
+        });
+        // Observer-event observability: log whether an external-change
+        // event actually produced a context-file update. Makes it obvious
+        // from the logs when the pipeline ran but the agent decided the
+        // change wasn't actionable. Covers every autonomous observer:
+        //  - calendar.* / schedule.approaching (calendar observer)
+        //  - github.*        (GitHub poller high-priority events)
+        //  - git.*           (git watcher batched events)
+        //  - notion.*        (notion poller)
+        //  - routine.hourly_check (Phase-9 polling sink for obsidian/git/notion)
+        if (this.isObserverEvent(event)) {
+            logger.info({
+                eventType: event.type,
+                source: event.source,
+                contextUpdated: result.contextUpdated,
+                numTurns: result.numTurns,
+                costUsd: result.costUsd,
+            }, result.contextUpdated
+                ? "Observer event processed — context files updated"
+                : "Observer event processed — no context updates");
+        }
+        // Mark scheduled task as completed or failed (covers both
+        // scheduled.task and scheduled.dm — both share the agent_schedule
+        // row lifecycle).
+        if (isScheduledEvent(event) && event.scheduleId) {
+            const newStatus = result.isError ? "failed" : "completed";
+            this.db
+                .prepare("UPDATE agent_schedule SET status = ? WHERE id = ? AND status = 'running'")
+                .run(newStatus, event.scheduleId);
+            this.finalizeRetemplateRunIfApplicable(event, { errored: result.isError });
+        }
+        // Repository-management events from the daily cron and the manual
+        // /api/repositories/:id/management/{init,scan} routes are
+        // `scheduled.task` events emitted directly to the EventBus (no
+        // `agent_schedule` row), so the finalize hook lives outside the
+        // `scheduleId` guard above. The finalizer is a no-op for any event
+        // whose taskContext doesn't match the management ProcessKey set.
+        this.finalizeManagementScanIfApplicable(event, { errored: result.isError });
+    }
+    /**
+     * 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.
+     */
+    finalizeRetemplateRunIfApplicable(event, options) {
+        if (!isAgentTaskEvent(event) || !event.scheduleId)
+            return;
+        const taskCtx = event.taskContext;
+        const processKey = taskCtx
+            && typeof taskCtx === "object"
+            && typeof taskCtx.processKey === "string"
+            ? taskCtx.processKey
+            : null;
+        if (processKey !== "git.project.retemplate")
+            return;
+        try {
+            const result = finalizeRetemplate({
+                db: this.db,
+                contextDir: getContextDir(this.config, this.db),
+                scheduleId: event.scheduleId,
+                errored: options.errored,
+            });
+            if (result.applied && result.rolledBackSlugs.length > 0) {
+                logger.info({
+                    scheduleId: event.scheduleId,
+                    rolledBack: result.rolledBackSlugs,
+                    finalStatus: result.finalStatus,
+                }, "Re-template run finalized — rolled back in-flight files from backup");
+            }
+        }
+        catch (err) {
+            logger.error({ err, scheduleId: event.scheduleId }, "Failed to finalize re-template run");
+        }
+    }
+    /**
+     * 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.
+     */
+    finalizeManagementScanIfApplicable(event, options) {
+        if (!isAgentTaskEvent(event))
+            return;
+        const taskCtx = event.taskContext;
+        if (!taskCtx || typeof taskCtx !== "object")
+            return;
+        const ctx = taskCtx;
+        const processKey = typeof ctx.processKey === "string" ? ctx.processKey : null;
+        const repositoryId = typeof ctx.repositoryId === "string" ? ctx.repositoryId : null;
+        const triggerSource = typeof ctx.triggerSource === "string" ? ctx.triggerSource : null;
+        if (!processKey || !repositoryId || !triggerSource)
+            return;
+        // Only management-emitted events should mutate `repository_management`.
+        // Trigger-fired sessions (`triggerSource === 'repository_trigger'`)
+        // share `processKey` in some cases but must not flip the management
+        // row — they have their own observability (`fire_count`).
+        if (triggerSource !== "repository_management_cron"
+            && triggerSource !== "repository_management_manual") {
+            return;
+        }
+        try {
+            if (processKey === "git.project.init") {
+                if (!options.errored) {
+                    recordManagementInitDone(this.db, repositoryId);
+                }
+                else {
+                    recordManagementScan(this.db, repositoryId, "failed");
+                }
+            }
+            else if (processKey === "git.project.update") {
+                recordManagementScan(this.db, repositoryId, options.errored ? "failed" : "ok");
+            }
+        }
+        catch (err) {
+            logger.error({ err, repositoryId, processKey, errored: options.errored }, "Failed to finalize repository management state");
+        }
+    }
+    hasRecentProactiveForwardContext(event, sessionId) {
+        if (!event.isDm || isDocsQAMessage(event))
+            return false;
+        const activeRows = this.db
+            .prepare(`SELECT metadata
+           FROM messages
+          WHERE session_id = ?
+          ORDER BY timestamp DESC, id DESC
+          LIMIT ?`)
+            .all(sessionId, this.config.historyInjectionMaxMessages ?? 20);
+        if (activeRows.some((row) => isProactiveForwardMetadata(parseMessageMetadata(row.metadata)))) {
+            return true;
+        }
+        const windowMinutes = this.config.historyOtherSurfaceWindowMinutes ?? 1440;
+        if (!Number.isFinite(windowMinutes) || windowMinutes <= 0)
+            return false;
+        const { scope } = getConversationScope({
+            platform: event.platform,
+            channel: event.channel,
+            threadId: event.threadId,
+            isDm: true,
+            intent: event.intent,
+        });
+        const other = scope === OWNER_DM_SCOPE
+            ? { scope: DASHBOARD_CHAT_SCOPE, scopeKey: DASHBOARD_SCOPE_KEY }
+            : scope === DASHBOARD_CHAT_SCOPE
+                ? { scope: OWNER_DM_SCOPE, scopeKey: OWNER_SCOPE_KEY }
+                : null;
+        if (!other)
+            return false;
+        const sinceUtc = formatSqliteDatetime(new Date(Date.now() - windowMinutes * 60_000));
+        const otherRows = this.db
+            .prepare(`SELECT m.metadata
+           FROM messages m
+           JOIN conversation_sessions s ON m.session_id = s.id
+          WHERE s.scope = ?
+            AND s.scope_key = ?
+            AND s.status = 'active'
+            AND m.timestamp >= ?
+          ORDER BY m.timestamp DESC, m.id DESC
+          LIMIT 60`)
+            .all(other.scope, other.scopeKey, sinceUtc);
+        return otherRows.some((row) => isProactiveForwardMetadata(parseMessageMetadata(row.metadata)));
+    }
+    logProactiveForwardDisavowalIfMatched(sessionId, reply) {
+        const matchedPattern = PROACTIVE_FORWARD_DISAVOWAL_PATTERNS.find((pattern) => pattern.test(reply));
+        if (!matchedPattern)
+            return;
+        try {
+            this.db
+                .prepare(`INSERT INTO agent_actions (
+             action_type, trigger, result, detail, started_at
+           )
+           VALUES (
+             'proactive_forward_disavowed',
+             'reactive',
+             'success',
+             ?,
+             CURRENT_TIMESTAMP
+           )`)
+                .run(JSON.stringify({
+                sessionId,
+                replyExcerpt: reply.slice(0, 240),
+                matchedPattern: matchedPattern.source,
+            }));
+        }
+        catch (err) {
+            logger.warn({ err, sessionId }, "Failed to log proactive forward disavowal");
+        }
+    }
+    formatSummaryRole(message) {
+        const metadata = parseMessageMetadata(message.metadata);
+        if (message.role === "assistant" && isProactiveForwardMetadata(metadata)) {
+            return "assistant (forwarded from autonomous run)";
+        }
+        return message.role;
+    }
+    buildCrossSessionConversationHistory(event) {
+        const { scope, scopeKey } = getConversationScope({
+            platform: event.platform,
+            channel: event.channel,
+            threadId: event.threadId,
+            isDm: event.isDm,
+            intent: event.intent,
+        });
+        const summary = event.isDm && scope === OWNER_DM_SCOPE
+            ? this.sessionMgr.getPreviousDmSummary(OWNER_SCOPE_KEY)
+            : null;
+        const statement = this.hasMessageBackendMetadataColumns
+            ? this.db.prepare(`SELECT m.role, m.content, m.timestamp, m.metadata, m.backend, m.model_id
+           FROM messages m
+           JOIN conversation_sessions s ON m.session_id = s.id
+           WHERE s.scope = ? AND s.scope_key = ?
+           ORDER BY m.timestamp DESC, m.id DESC
+           LIMIT 20`)
+            : this.db.prepare(`SELECT m.role, m.content, m.timestamp, m.metadata,
+                  NULL AS backend,
+                  NULL AS model_id
+           FROM messages m
+           JOIN conversation_sessions s ON m.session_id = s.id
+           WHERE s.scope = ? AND s.scope_key = ?
+           ORDER BY m.timestamp DESC, m.id DESC
+           LIMIT 20`);
+        const rows = statement
+            .all(scope, scopeKey);
+        if (!summary && rows.length === 0) {
+            return null;
+        }
+        const parts = ["## Previous conversation in this thread"];
+        if (summary) {
+            parts.push("", "### Earlier summary", summary);
+        }
+        if (rows.length > 0) {
+            parts.push("", "### Recent messages (oldest first)");
+            for (const row of rows.reverse()) {
+                const tag = row.backend
+                    ? `[${row.role}/${row.backend}:${row.model_id ?? "?"}]`
+                    : `[${row.role}/user]`;
+                const forwardSuffix = row.role === "assistant"
+                    && isProactiveForwardMetadata(parseMessageMetadata(row.metadata))
+                    ? " (forwarded from autonomous run)"
+                    : "";
+                parts.push(`${tag}${forwardSuffix}: ${row.content}`);
+            }
+        }
+        return parts.join("\n");
+    }
+    shouldNotify(event) {
+        if (isMessageEvent(event))
+            return true;
+        if (isScheduledEvent(event)) {
+            // Dashboard-triggered tasks (e.g. regenerate) already show status
+            // in the UI — suppress DM notification to avoid noisy messages.
+            // Both scheduled.task and scheduled.dm share this gate; the
+            // briefing path's final assistant turn IS the DM.
+            const ctx = event.taskContext;
+            if (ctx?.triggeredBy === "dashboard")
+                return false;
+            return true;
+        }
+        // Routine events are silent-by-default: result.output is an internal
+        // agent log, never forwarded as a user notification. Routines reach
+        // the user only via explicit POST /api/notify from their prompt. Do
+        // not re-add routines here — the routine_protocol header injected by
+        // the context-builder carries this rule to the agent.
+        return false;
+    }
+    /**
+     * 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.
+     */
+    isObserverEvent(event) {
+        return ((isRoutineEvent(event) && event.routine === "hourly_check") ||
+            event.type.startsWith("calendar.") ||
+            event.type === "schedule.approaching" ||
+            event.type.startsWith("notion.") ||
+            event.type.startsWith("github.") ||
+            event.type.startsWith("git."));
+    }
+    /**
+     * 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.
+     */
+    async summarizeDmSessions() {
+        const platforms = this.sessionMgr.getDmPlatformsWithNewMessages();
+        if (platforms.length === 0)
+            return;
+        const MSG_THRESHOLD = 30;
+        const SIZE_THRESHOLD = 5000;
+        // Force summarization before session retention (7 days) deletes messages
+        const DAYS_THRESHOLD = 6;
+        for (const platform of platforms) {
+            try {
+                const newMessages = this.sessionMgr.getUnsummarizedDmMessages(platform);
+                if (newMessages.length === 0)
+                    continue;
+                const rawNew = newMessages
+                    .map((m) => `[${this.formatSummaryRole(m)}] ${m.content}`)
+                    .join("\n");
+                // Check if oldest message is approaching retention cutoff
+                const oldestMs = parseSqliteUtcMs(newMessages[0].timestamp);
+                const daysOld = (Date.now() - oldestMs) / (1000 * 60 * 60 * 24);
+                const approachingRetention = daysOld >= DAYS_THRESHOLD;
+                // Below threshold: skip — count accumulates until next check
+                if (newMessages.length <= MSG_THRESHOLD &&
+                    rawNew.length <= SIZE_THRESHOLD &&
+                    !approachingRetention) {
+                    logger.debug({ platform, messageCount: newMessages.length, rawSize: rawNew.length }, "DM messages below threshold, skipping summarization");
+                    continue;
+                }
+                // AI compression (rolling: previous summary + new messages → condensed)
+                const previousSummary = this.sessionMgr.getPreviousDmSummary(platform);
+                const parts = [];
+                if (previousSummary) {
+                    parts.push(`Previous context:\n${previousSummary}`);
+                }
+                parts.push(`New messages:\n${newMessages.map((m) => `${this.formatSummaryRole(m)}: ${m.content}`).join("\n")}`);
+                const summary = await this.agentRouter.summarize(parts.join("\n\n"));
+                this.sessionMgr.saveDmSummary(platform, summary, newMessages.length);
+                logger.info({ platform, messageCount: newMessages.length, hadPreviousSummary: !!previousSummary }, "DM conversation summarized");
+            }
+            catch (err) {
+                logger.error({ err, platform }, "Failed to summarize DM conversation");
+            }
+        }
+    }
+    /** Delegate to shared isRoadmapStale utility. */
+    isRoadmapStale(maxAgeDays = 15) {
+        return isRoadmapStale(getContextDir(this.config, this.db), maxAgeDays);
+    }
+    /**
+     * 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, options) {
+        const DEDUP_MS = 5 * 60 * 1000;
+        const bypassDedup = options?.bypassDedup === true;
+        if (!bypassDedup && Date.now() - this.lastRoadmapRefreshEmitMs < DEDUP_MS) {
+            logger.info({ source }, "Skipping roadmap_refresh (dedup, emitted recently)");
+            return;
+        }
+        this.lastRoadmapRefreshEmitMs = Date.now();
+        logger.info({ source, bypassDedup }, "Emitting roadmap_refresh");
+        void this.eventBus.put({
+            ...createEvent({
+                type: "routine.roadmap_refresh",
+                source,
+                priority: EventPriority.NORMAL,
+            }),
+            routine: "roadmap_refresh",
+        });
+    }
+    localDateTimeToUtcMs(parts, timeZone) {
+        if (!timeZone) {
+            return new Date(parts.year, parts.month - 1, parts.day, parts.hour, parts.minute, 0, 0).getTime();
+        }
+        const baseUtc = Date.UTC(parts.year, parts.month - 1, parts.day, parts.hour, parts.minute, 0, 0);
+        let guess = baseUtc;
+        for (let attempt = 0; attempt < 3; attempt++) {
+            const offsetMinutes = this.getTimeZoneOffsetMinutes(new Date(guess), timeZone);
+            if (offsetMinutes === null) {
+                return null;
+            }
+            const nextGuess = baseUtc - offsetMinutes * 60 * 1000;
+            if (nextGuess === guess) {
+                break;
+            }
+            guess = nextGuess;
+        }
+        const resolved = this.getLocalDateParts(new Date(guess), timeZone);
+        if (this.compareLocalDateParts(resolved, parts) !== 0) {
+            return null;
+        }
+        return guess;
+    }
+    getTimeZoneOffsetMinutes(date, timeZone) {
+        let formatter;
+        try {
+            formatter = new Intl.DateTimeFormat("en-US", {
+                timeZone,
+                timeZoneName: "shortOffset",
+            });
+        }
+        catch {
+            return null;
+        }
+        const zonePart = formatter.formatToParts(date).find((part) => part.type === "timeZoneName")?.value;
+        if (!zonePart) {
+            return null;
+        }
+        if (zonePart === "GMT") {
+            return 0;
+        }
+        const match = /^GMT([+-])(\d{1,2})(?::?(\d{2}))?$/.exec(zonePart);
+        if (!match) {
+            return null;
+        }
+        const sign = match[1] === "-" ? -1 : 1;
+        const hours = Number(match[2]);
+        const minutes = Number(match[3] ?? "0");
+        return sign * (hours * 60 + minutes);
+    }
+    getLocalDateParts(date, timeZone) {
+        let formatter;
+        try {
+            formatter = new Intl.DateTimeFormat("en-US", {
+                timeZone,
+                year: "numeric",
+                month: "2-digit",
+                day: "2-digit",
+                hour: "2-digit",
+                minute: "2-digit",
+                hourCycle: "h23",
+            });
+        }
+        catch {
+            formatter = new Intl.DateTimeFormat("en-US", {
+                year: "numeric",
+                month: "2-digit",
+                day: "2-digit",
+                hour: "2-digit",
+                minute: "2-digit",
+                hourCycle: "h23",
+            });
+        }
+        const parts = formatter.formatToParts(date);
+        const valueOf = (type) => Number(parts.find((part) => part.type === type)?.value ?? "0");
+        return {
+            year: valueOf("year"),
+            month: valueOf("month"),
+            day: valueOf("day"),
+            hour: valueOf("hour"),
+            minute: valueOf("minute"),
+        };
+    }
+    compareLocalDateParts(a, b) {
+        if (a.year !== b.year)
+            return a.year - b.year;
+        if (a.month !== b.month)
+            return a.month - b.month;
+        if (a.day !== b.day)
+            return a.day - b.day;
+        if (a.hour !== b.hour)
+            return a.hour - b.hour;
+        return a.minute - b.minute;
+    }
+    isRetryable(error) {
+        // BackendCore implementations wrap all errors into BackendQuotaError or
+        // BackendDecisiveFailure before they reach the dispatcher. Both are
+        // decisive (no retry). BackendRouterHandledError is also decisive.
+        if (error instanceof BackendQuotaError ||
+            error instanceof BackendDecisiveFailure ||
+            error instanceof BackendRouterHandledError) {
+            return false;
+        }
+        // Raw 5xx from an unclassified path — retry once.
+        const status = typeof error === "object" && error !== null && "status" in error
+            ? error.status
+            : undefined;
+        return typeof status === "number" && status >= 500;
+    }
+    /**
+     * 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.
+     */
+    async executeWithRetry(fn, event) {
+        const maxRetries = 1;
+        let lastError;
+        for (let attempt = 0; attempt <= maxRetries; attempt++) {
+            try {
+                return await fn();
+            }
+            catch (error) {
+                lastError = error;
+                if (attempt < maxRetries && this.isRetryable(error)) {
+                    logger.warn({
+                        eventType: event.type,
+                        attempt: attempt + 1,
+                        error: error instanceof Error ? error.message : String(error),
+                    }, "Retrying agent execution after backoff");
+                    // Shutdown-aware sleep: race a single 5-minute timer against the
+                    // shutdown signal so SIGTERM unwinds the retry loop promptly
+                    // instead of blocking for up to 5 minutes.
+                    await new Promise((resolve) => {
+                        const onShutdown = () => {
+                            clearTimeout(timer);
+                            this.shutdownAwaiters.delete(onShutdown);
+                            resolve();
+                        };
+                        const timer = setTimeout(() => {
+                            this.shutdownAwaiters.delete(onShutdown);
+                            resolve();
+                        }, 5 * 60 * 1000);
+                        this.shutdownAwaiters.add(onShutdown);
+                    });
+                    if (this.shutdown) {
+                        throw lastError;
+                    }
+                    continue;
+                }
+                break;
+            }
+        }
+        throw lastError;
+    }
+    async handleError(event, error) {
+        logger.error({ event: event.type, error: error.message }, "Event processing error");
+        // Defense-in-depth cleanup of the notify-dedup marker — processResult
+        // is the primary collection point, but if execution threw before
+        // reaching it, drop any orphan entry here so the set cannot grow
+        // unbounded across error storms.
+        this.notifiedEvents.delete(event.correlationId);
+        const routerHandledError = error instanceof BackendRouterHandledError
+            ? error
+            : null;
+        // Mark scheduled task as failed whenever execution terminates
+        // without a result. Covers both scheduled.task and scheduled.dm —
+        // a scheduled.dm row that throws would otherwise stick in
+        // `running` forever.
+        if (isScheduledEvent(event) && event.scheduleId) {
+            this.db
+                .prepare("UPDATE agent_schedule SET status = 'failed' WHERE id = ? AND status = 'running'")
+                .run(event.scheduleId);
+            this.finalizeRetemplateRunIfApplicable(event, { errored: true });
+        }
+        // Same rationale as the success-path call: management events have no
+        // `agent_schedule` row, so this hook is intentionally outside the
+        // scheduleId guard.
+        this.finalizeManagementScanIfApplicable(event, { errored: true });
+        if (routerHandledError) {
+            const quotaError = this.extractQuotaError(routerHandledError.cause);
+            if (quotaError && isMessageEvent(event)) {
+                this.notifyDashboardError(event, this.formatQuotaMessage(quotaError));
+            }
+            return;
+        }
+        const quotaError = this.extractQuotaError(error);
+        if (quotaError && isMessageEvent(event)) {
+            const quotaMsg = this.formatQuotaMessage(quotaError);
+            this.notifyDashboardError(event, quotaMsg);
+            await this.notificationMgr.send(quotaMsg, event);
+            return;
+        }
+        if (isMessageEvent(event)) {
+            const errorMsg = "An error occurred during processing. Please try again.";
+            this.notifyDashboardError(event, errorMsg);
+            await this.notificationMgr.send(errorMsg, event);
+        }
+    }
+    /**
+     * 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.
+     */
+    notifyDashboardError(event, message) {
+        if (!isMessageEvent(event))
+            return;
+        if (event.platform !== "dashboard")
+            return;
+        this.dashboardStream?.sendError?.(event.channel, message);
+    }
+    extractQuotaError(error) {
+        if (error instanceof BackendQuotaError) {
+            return error;
+        }
+        if (error instanceof BackendDecisiveFailure &&
+            error.kind === "quota" &&
+            error.cause instanceof BackendQuotaError) {
+            return error.cause;
+        }
+        // All BackendCore implementations normalize quota errors before they
+        // reach the dispatcher, so no Claude-specific fallback is needed here.
+        return null;
+    }
+    formatQuotaMessage(quotaError) {
+        const backendLabel = this.formatBackendLabel(quotaError.backendId);
+        const resetHint = quotaError.resetHint;
+        if (quotaError.originalCode === "max_budget_usd") {
+            return `${backendLabel} reached the per-turn budget limit. Please try a shorter request or raise max_budget_usd in backend settings.`;
+        }
+        if (resetHint) {
+            const timeZone = resetHint.timeZone || this.config.timezone || undefined;
+            const resetAtMs = this.resolveQuotaResetAtMs(resetHint);
+            if (resetAtMs !== null) {
+                const formatted = new Intl.DateTimeFormat("en-US", {
+                    timeZone,
+                    year: "numeric",
+                    month: "2-digit",
+                    day: "2-digit",
+                    hour: "2-digit",
+                    minute: "2-digit",
+                    hourCycle: "h12",
+                }).format(new Date(resetAtMs));
+                const zoneLabel = timeZone ? ` (${timeZone})` : "";
+                return `${backendLabel} has reached its usage limit. Resets at ${formatted}${zoneLabel}. Please try again after the reset.`;
+            }
+            try {
+                new Intl.DateTimeFormat("en-US", { timeZone }).format(new Date());
+            }
+            catch {
+                // Fall through to rawLabel/generic message if the timezone label is invalid.
+            }
+            const rawLabel = resetHint.rawLabel.trim();
+            if (rawLabel) {
+                return `${backendLabel} has reached its usage limit. Resets at ${rawLabel}. Please try again after the reset.`;
+            }
+        }
+        return `${backendLabel} has reached its usage limit. Please wait and try again later.`;
+    }
+    formatBackendLabel(backendId) {
+        switch (backendId) {
+            case "claude":
+                return "Claude Code";
+            case "codex":
+                return "Codex";
+            case "gemini":
+                return "Gemini CLI";
+            default:
+                return backendId;
+        }
+    }
+    resolveQuotaResetAtMs(resetHint) {
+        const timeZone = resetHint.timeZone || this.config.timezone || undefined;
+        const now = new Date();
+        const current = this.getLocalDateParts(now, timeZone);
+        let target = {
+            year: current.year,
+            month: current.month,
+            day: current.day,
+            hour: resetHint.hour,
+            minute: resetHint.minute,
+        };
+        if (this.compareLocalDateParts(current, target) >= 0) {
+            const nextDate = new Date(Date.UTC(current.year, current.month - 1, current.day + 1));
+            target = {
+                year: nextDate.getUTCFullYear(),
+                month: nextDate.getUTCMonth() + 1,
+                day: nextDate.getUTCDate(),
+                hour: resetHint.hour,
+                minute: resetHint.minute,
+            };
+        }
+        return this.localDateTimeToUtcMs(target, timeZone);
+    }
+    /**
+     * 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.
+     */
+    consultDelegatedConnectorWarnings(sessionBackend) {
+        try {
+            const result = consultDelegatedConnectorHealth(this.db, sessionBackend);
+            if (result.recovered.length > 0) {
+                logger.info({ recovered: result.recovered, sessionBackend }, "Delegated connector(s) recovered — sign-out warning markers cleared");
+            }
+            return result.warnings;
+        }
+        catch (err) {
+            logger.warn({ err, sessionBackend }, "Delegated connector-health consult failed — skipping DM warning");
+            return [];
+        }
+    }
+    /**
+     * 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).
+     */
+    runDelegatedConnectorWarningDispatch(warnings, event, sessionBackend, sessionId) {
+        for (const warning of warnings) {
+            logger.warn({
+                integration: warning.integration,
+                backend: warning.backend,
+                missingRequired: warning.missingRequired,
+            }, "Delegated connector reports missing required capabilities — DM owner");
+            const message = renderSignoutDm(warning);
+            // Mark the throttle ONLY after a successful dispatch — if the
+            // messaging adapter is down, an absent marker keeps the next
+            // consult ready to re-issue the warning. The .send() promise
+            // resolves on adapter-acknowledged delivery; .catch() is the
+            // failure side, which deliberately leaves the marker unset.
+            //
+            // After delivery, persist the warning to `messages` so it survives
+            // dashboard chat reload + the chat_meta history-reconcile pass
+            // (`reconcileLiveMessagesAfterHistoryReload` drops live bubbles whose
+            // timestamp is before the sync started AND whose signature is not in
+            // the restored history; without this persist the DM bubble vanishes
+            // the moment the agent's reply chat_meta arrives). For non-dashboard
+            // platforms (Slack/Telegram) the message-store is the platform itself,
+            // so we deliberately persist only when `event.platform === "dashboard"`
+            // to avoid duplicating remote-platform messages locally.
+            void this.notificationMgr
+                .send(message, event, {
+                priority: "high",
+                category: "delegated_signout",
+            })
+                .then(() => {
+                try {
+                    markSignoutWarned(this.db, warning);
+                }
+                catch (err) {
+                    logger.warn({
+                        err,
+                        integration: warning.integration,
+                        backend: warning.backend,
+                    }, "Failed to persist delegated-signout marker — next consult may re-warn");
+                }
+                if (event.platform === "dashboard") {
+                    try {
+                        this.messageRecorder.recordMessage({
+                            sessionId,
+                            role: "assistant",
+                            content: message,
+                            platform: event.platform,
+                            backend: sessionBackend,
+                        });
+                    }
+                    catch (err) {
+                        logger.warn({
+                            err,
+                            integration: warning.integration,
+                            backend: warning.backend,
+                            sessionId,
+                        }, "Failed to persist delegated-signout DM into messages — bubble may vanish on chat reload");
+                    }
+                }
+            })
+                .catch((err) => {
+                logger.error({ err, integration: warning.integration, backend: warning.backend }, "Failed to deliver delegated-signout DM — marker not set, will retry next dispatch");
+            });
+        }
+    }
+}
+//# sourceMappingURL=dispatcher.js.map