@aitne/daemon 0.1.0

package/dist/api/routes/dashboard.js

@@ -0,0 +1,2062 @@
+import { Hono } from "hono";
+import { readFileSync, writeFileSync, existsSync } from "node:fs";
+import { join } from "node:path";
+import { randomUUID } from "node:crypto";
+import { APP_NAME, EDITABLE_RUNTIME_KEY_TUPLE, getAgentDayBoundsUtc, normalizeAgentDisplayName, } from "@aitne/shared";
+import { applyConfigUpdates } from "../env-writer.js";
+import { runDefaultSchedulesReconciler } from "../../core/context/default-schedules-runner.js";
+import { syncDmSessionTimesToQuietHours } from "../../core/quiet-hours-sync.js";
+import { detectGoogleCredentialType, getGoogleOAuthClientConfig, parseGoogleCredentialsJson, } from "../../services/google-auth.js";
+import { getContextDir } from "../../config.js";
+import { CONTEXT_RELATIVE_PATHS } from "../../core/context-paths.js";
+import { createLogger, toSafeErrorMessage } from "../../logging.js";
+import { upsertManagementRulesAgentIdentity } from "../../management-rules.js";
+import { DEFAULT_DISALLOWED_TOOLS, runtimeSettingsSchema } from "../../settings/runtime-settings.js";
+import { createSettingsStore } from "../../settings/settings-store.js";
+import { getSessionWorkdirPath } from "../../core/workdir.js";
+import { rewriteCharacterBlock } from "../../core/skills-compiler.js";
+import { DASHBOARD_CHAT_SCOPE, DOCS_QA_SCOPE } from "../../messaging/constants.js";
+import { deleteAllChatSidebarSessions, deleteChatSession, } from "../../core/dashboard-session-cleanup.js";
+import { readJsonBody } from "../json-body.js";
+import { computeDmFreshnessAggregate } from "../../core/dm-freshness-metrics.js";
+const MAX_UPLOAD_SIZE = 100 * 1024; // 100 KB — credential files are small
+const MAX_OAUTH_STATE_AGE_MS = 10 * 60 * 1000;
+const PUBLIC_CONFIG_RUNTIME_KEYS = [
+    "maxConcurrentSessions",
+    "maxReactiveSessions",
+    "delegatedProxyMaxConcurrent",
+    "delegatedTaskModeEnabled",
+    "delegatedTaskMaxPerDay",
+    "delegatedTaskDefaultMaxToolCalls",
+    "delegatedTaskDefaultMaxBudgetUsd",
+    "delegatedTaskDefaultTimeoutMs",
+    "delegatedTaskHeavyEnabled",
+    "executeTimeoutMinutes",
+    "agentDisplayName",
+    "sessionTimeoutDmMinutes",
+    "sessionTimeoutChannelMinutes",
+    "sessionTimeoutDashboardMinutes",
+    "timezone",
+    "dayBoundaryHour",
+    "hourlyCheckEnabled",
+    "hourlyCheckIntervalMinutes",
+    "hourlyCheckActiveStartHour",
+    "hourlyCheckActiveEndHour",
+    "hourlyCheckMinObservations",
+    "authProbeDisabled",
+    "authPreflightFreshnessMs",
+    "maxNotificationsPerHour",
+    "maxNotificationsPerDay",
+    "quietHoursStart",
+    "quietHoursEnd",
+    "batchIntervalMinutes",
+    "primaryPlatform",
+    "defaultNotificationPlatforms",
+    "whatsappEnabled",
+    "whatsappAuthDir",
+    "disallowedTools",
+    "claudeExecutionPermissionMode",
+    "codexExecutionPermissionMode",
+    "geminiExecutionPermissionMode",
+    "externalObsidianVaultPath",
+    "externalObsidianVaultName",
+    // SETUP-FLOW-REDESIGN-PLAN §6.3 — kill switch for the external-vault
+    // file watcher. Surfaced so the Note step's "Watch for changes"
+    // checkbox round-trips through the dashboard.
+    "externalObsidianWatch",
+    "primaryVaultPath",
+    "primaryVaultName",
+    // gitRepos / gitWatchedRepos / githubRepos removed at the unified-
+    // repositories cutover (docs/design/appendices/unified-repositories.md);
+    // dashboard reads the rows from /api/repositories instead.
+    "googleCalendarId",
+    "notionDatabaseIds",
+    "character",
+    "historyInjectionMaxMessages",
+    "historyInjectionMaxTokens",
+    "dmStalenessStrict",
+    "obsidianDebounceSeconds",
+    "schedulePollIntervalSeconds",
+    "gitPollIntervalSeconds",
+    "gitPushOverdueMinutes",
+    "gitProjectUpdateDebounceMinutes",
+    "notionPollIntervalSeconds",
+    "calendarPollIntervalSeconds",
+    "gmailPollIntervalSeconds",
+    "mcpAutoProbeIntervalMinutes",
+    "delegatedProbeIntervalMinutes",
+    "autonomousDailyCostCapUsd",
+    "autonomousMonthlyCostCapUsd",
+    "primaryLanguage",
+    "vaultMode",
+];
+const PUBLIC_CONFIG_NULLABLE_STRING_KEYS = new Set([
+    "whatsappAuthDir",
+    "externalObsidianVaultPath",
+    "externalObsidianVaultName",
+    "primaryVaultPath",
+    "primaryVaultName",
+]);
+/**
+ * Pre-defined static cost queries — no string interpolation of user input.
+ * `byModel` is computed in JS via `aggregateByBilledModel` because the SDK
+ * can route a request for one model to a sibling (e.g. opus-4-7 →
+ * opus-4-6[1m]); SQL `GROUP BY model_used` would lump cost under the
+ * requested model and produce a chart that disagrees with the per-row
+ * billed-model badge on the same page.
+ */
+const COST_QUERIES = {
+    daily: {
+        byPeriod: `SELECT date(started_at) as period,
+            SUM(cost_usd) as total_cost, COUNT(*) as session_count,
+            SUM(tokens_input) as total_input_tokens, SUM(tokens_output) as total_output_tokens
+     FROM agent_actions WHERE started_at > datetime('now', '-30 days') AND cost_usd IS NOT NULL
+     GROUP BY date(started_at) ORDER BY period DESC`,
+        byModelRows: `SELECT model_used, model_usage_json, cost_usd
+     FROM agent_actions
+     WHERE started_at > datetime('now', '-30 days')
+       AND cost_usd IS NOT NULL
+       AND (model_used IS NOT NULL OR model_usage_json IS NOT NULL)`,
+        byEventType: `SELECT action_type as event_type, SUM(cost_usd) as total_cost, COUNT(*) as session_count
+     FROM agent_actions WHERE started_at > datetime('now', '-30 days') AND cost_usd IS NOT NULL
+     GROUP BY action_type ORDER BY total_cost DESC`,
+    },
+    weekly: {
+        byPeriod: `SELECT strftime('%Y-W%W', started_at) as period,
+            SUM(cost_usd) as total_cost, COUNT(*) as session_count,
+            SUM(tokens_input) as total_input_tokens, SUM(tokens_output) as total_output_tokens
+     FROM agent_actions WHERE started_at > datetime('now', '-90 days') AND cost_usd IS NOT NULL
+     GROUP BY strftime('%Y-W%W', started_at) ORDER BY period DESC`,
+        byModelRows: `SELECT model_used, model_usage_json, cost_usd
+     FROM agent_actions
+     WHERE started_at > datetime('now', '-90 days')
+       AND cost_usd IS NOT NULL
+       AND (model_used IS NOT NULL OR model_usage_json IS NOT NULL)`,
+        byEventType: `SELECT action_type as event_type, SUM(cost_usd) as total_cost, COUNT(*) as session_count
+     FROM agent_actions WHERE started_at > datetime('now', '-90 days') AND cost_usd IS NOT NULL
+     GROUP BY action_type ORDER BY total_cost DESC`,
+    },
+    monthly: {
+        byPeriod: `SELECT strftime('%Y-%m', started_at) as period,
+            SUM(cost_usd) as total_cost, COUNT(*) as session_count,
+            SUM(tokens_input) as total_input_tokens, SUM(tokens_output) as total_output_tokens
+     FROM agent_actions WHERE started_at > datetime('now', '-365 days') AND cost_usd IS NOT NULL
+     GROUP BY strftime('%Y-%m', started_at) ORDER BY period DESC`,
+        byModelRows: `SELECT model_used, model_usage_json, cost_usd
+     FROM agent_actions
+     WHERE started_at > datetime('now', '-365 days')
+       AND cost_usd IS NOT NULL
+       AND (model_used IS NOT NULL OR model_usage_json IS NOT NULL)`,
+        byEventType: `SELECT action_type as event_type, SUM(cost_usd) as total_cost, COUNT(*) as session_count
+     FROM agent_actions WHERE started_at > datetime('now', '-365 days') AND cost_usd IS NOT NULL
+     GROUP BY action_type ORDER BY total_cost DESC`,
+    },
+};
+/**
+ * Aggregate raw `byModelRows` into the `{ model, total_cost, session_count }`
+ * shape the dashboard expects, attributing cost to the actually-billed model
+ * from `model_usage_json` rather than the requested `model_used`. When a row
+ * has no usage breakdown we fall back to `model_used`. A row that touches
+ * multiple billed models contributes its split cost to each bucket and is
+ * counted once toward each model's `session_count`.
+ *
+ * Cost reconciliation: the SDK's `r.modelUsage[*].costUSD` covers LLM
+ * inference only — server-side tools (web_search, code_execution) appear in
+ * `r.total_cost_usd` (= row.cost_usd) but not in any per-model entry. If
+ * `Σ per-model cost < row.cost_usd`, the residual is credited to
+ * `model_used` (the requested model) so per-model totals add up to the
+ * dashboard's overall cost. Without this, a chart row's "billed total"
+ * silently drops tool-use spend.
+ */
+export function aggregateByBilledModel(rows) {
+    const map = new Map();
+    // Per-row scratch; a single row counts toward `session_count` exactly once
+    // per model it touched, even when residual handling credits the same model
+    // twice (once from per-model breakdown, once from tool-use residual).
+    const addCost = (model, cost) => {
+        const bucket = map.get(model) ?? { total_cost: 0, session_count: 0 };
+        bucket.total_cost += cost;
+        map.set(model, bucket);
+    };
+    const incSession = (rowSeen, model) => {
+        if (rowSeen.has(model))
+            return;
+        rowSeen.add(model);
+        const bucket = map.get(model) ?? { total_cost: 0, session_count: 0 };
+        bucket.session_count += 1;
+        map.set(model, bucket);
+    };
+    // 0.0001¢ — below this, treat the residual as float-arithmetic noise and
+    // skip the bookkeeping. Real tool-use costs are always orders of magnitude
+    // above this.
+    const RESIDUAL_EPSILON_USD = 0.000001;
+    for (const row of rows) {
+        const seenForRow = new Set();
+        let parsed = null;
+        if (row.model_usage_json) {
+            try {
+                parsed = JSON.parse(row.model_usage_json);
+            }
+            catch {
+                parsed = null;
+            }
+        }
+        let perModelTotal = 0;
+        let touchedAny = false;
+        if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+            for (const [modelId, entry] of Object.entries(parsed)) {
+                if (!entry || typeof entry !== "object")
+                    continue;
+                const v = entry;
+                const cost = typeof v.costUsd === "number" ? v.costUsd : 0;
+                addCost(modelId, cost);
+                incSession(seenForRow, modelId);
+                perModelTotal += cost;
+                touchedAny = true;
+            }
+        }
+        if (!touchedAny) {
+            if (row.model_used) {
+                addCost(row.model_used, row.cost_usd);
+                incSession(seenForRow, row.model_used);
+            }
+            continue;
+        }
+        // Residual handles server-side tool cost (web_search, code execution)
+        // that the SDK adds to total_cost_usd but not to any per-model bucket.
+        const residual = row.cost_usd - perModelTotal;
+        if (residual > RESIDUAL_EPSILON_USD && row.model_used) {
+            addCost(row.model_used, residual);
+            incSession(seenForRow, row.model_used);
+        }
+    }
+    return [...map.entries()]
+        .map(([model, v]) => ({ model, ...v }))
+        .sort((a, b) => b.total_cost - a.total_cost);
+}
+const COST_PERIOD_SPECS = {
+    daily: {
+        bucketExpr: "date(started_at)",
+        sinceExpr: "-30 days",
+    },
+    weekly: {
+        bucketExpr: "strftime('%Y-W%W', started_at)",
+        sinceExpr: "-90 days",
+    },
+    monthly: {
+        bucketExpr: "strftime('%Y-%m', started_at)",
+        sinceExpr: "-365 days",
+    },
+};
+/** Escape HTML special characters to prevent XSS */
+function escapeHtml(s) {
+    return s
+        .replace(/&/g, "&amp;")
+        .replace(/</g, "&lt;")
+        .replace(/>/g, "&gt;")
+        .replace(/"/g, "&quot;")
+        .replace(/'/g, "&#039;");
+}
+function getLocalHourMinute(date, timeZone) {
+    const formatter = new Intl.DateTimeFormat("en-US", {
+        hour: "2-digit",
+        minute: "2-digit",
+        hour12: false,
+        timeZone,
+    });
+    const parts = formatter.formatToParts(date);
+    const hour = Number(parts.find((part) => part.type === "hour")?.value ?? "0");
+    const minute = Number(parts.find((part) => part.type === "minute")?.value ?? "0");
+    return { hour, minute };
+}
+function isHourlyCheckSlot(date, config) {
+    if (!config.hourlyCheckEnabled)
+        return false;
+    const { hour, minute } = getLocalHourMinute(date, config.timezone || undefined);
+    if (hour === config.dayBoundaryHour)
+        return false;
+    if (hour < config.hourlyCheckActiveStartHour || hour >= config.hourlyCheckActiveEndHour) {
+        return false;
+    }
+    return minute % config.hourlyCheckIntervalMinutes === 0;
+}
+function getNextHourlyCheck(config) {
+    if (!config.hourlyCheckEnabled) {
+        return { active: false, nextRunAt: null };
+    }
+    const now = new Date();
+    const active = isHourlyCheckSlot(now, config);
+    const start = new Date(now.getTime() + 60_000);
+    start.setSeconds(0, 0);
+    for (let offset = 0; offset < 48 * 60; offset++) {
+        const candidate = new Date(start.getTime() + offset * 60_000);
+        if (isHourlyCheckSlot(candidate, config)) {
+            return { active, nextRunAt: candidate.toISOString() };
+        }
+    }
+    return { active, nextRunAt: null };
+}
+function isStringRecord(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        return false;
+    }
+    return Object.entries(value).every(([key, entryValue]) => typeof key === "string" && typeof entryValue === "string");
+}
+function sameStringRecord(a, b) {
+    const aEntries = Object.entries(a);
+    const bEntries = Object.entries(b);
+    if (aEntries.length !== bEntries.length) {
+        return false;
+    }
+    return aEntries.every(([key, value]) => b[key] === value);
+}
+function buildSafeConfig(config, secretSummary) {
+    const safeConfig = {};
+    for (const key of PUBLIC_CONFIG_RUNTIME_KEYS) {
+        const value = config[key];
+        safeConfig[key] = PUBLIC_CONFIG_NULLABLE_STRING_KEYS.has(key)
+            ? value ?? ""
+            : value;
+    }
+    safeConfig.apiPort = config.apiPort;
+    safeConfig.allowedTools = config.allowedToolsOverride ?? [];
+    // Derived — the actual directory `getContextDir(config)` resolves to.
+    // Surfaces the mode/path → disk outcome to the dashboard so the
+    // Management Mode section can show the effective location without
+    // reimplementing the resolution logic. Always an absolute path.
+    safeConfig.contextDir = getContextDir(config);
+    safeConfig.slackConfigured = secretSummary.slackConfigured;
+    safeConfig.slackOwnerUserConfigured = !!config.slackOwnerUserId;
+    safeConfig.telegramConfigured = secretSummary.telegramConfigured;
+    safeConfig.telegramOwnerChatConfigured = !!config.telegramOwnerChatId;
+    safeConfig.discordConfigured = secretSummary.discordConfigured;
+    safeConfig.discordOwnerUserConfigured = !!config.discordOwnerUserId;
+    safeConfig.notionConfigured = secretSummary.notionConfigured;
+    safeConfig.githubConfigured = secretSummary.githubConfigured;
+    safeConfig.githubWebhookSecretConfigured = secretSummary.githubWebhookSecretConfigured;
+    safeConfig.apiTokenConfigured = secretSummary.apiTokenConfigured;
+    safeConfig.whatsappOwnerPhoneConfigured = !!config.whatsappOwnerPhone;
+    safeConfig.googleCalendarCredentialsConfigured = secretSummary.googleCalendarCredentialsConfigured;
+    safeConfig.googleCalendarTokenConfigured = secretSummary.googleCalendarTokenConfigured;
+    // SETUP-FLOW-REDESIGN-PLAN §6.1 — surface Outlook BYOA presence so
+    // dashboards can decide when direct-mode Outlook integrations are
+    // resumable.
+    safeConfig.outlookClientConfigConfigured = secretSummary.outlookClientConfigConfigured;
+    safeConfig.googleCredentialType = secretSummary.googleCredentialType;
+    return safeConfig;
+}
+/**
+ * Dashboard API routes — REST endpoints for the Dashboard UI.
+ *
+ * Provides:
+ * - Config management (GET/PATCH /api/config)
+ * - Event/action logs (GET /api/events)
+ * - Conversation history (GET /api/conversations)
+ * - Cost analytics (GET /api/cost)
+ * - Approval queue (GET/POST /api/approvals)
+ */
+const logger = createLogger("dashboard-api");
+export function createDashboardRoutes(deps) {
+    const app = new Hono();
+    const { db, config, services, secretBroker } = deps;
+    const settingsStore = createSettingsStore(db);
+    const oauthStates = new Map();
+    const agentActionColumns = new Set(db.pragma("table_info(agent_actions)").map((column) => column.name));
+    const backendExpr = agentActionColumns.has("backend")
+        ? "COALESCE(backend, 'claude')"
+        : "'claude'";
+    function pruneOauthStates(now = Date.now()) {
+        for (const [state, data] of oauthStates.entries()) {
+            if (now - data.createdAt > MAX_OAUTH_STATE_AGE_MS) {
+                oauthStates.delete(state);
+            }
+        }
+    }
+    async function getSecretConfigSummary() {
+        const [slackBotToken, slackAppToken, telegramBotToken, discordBotToken, notionApiKey, githubToken, githubWebhookSecret, apiToken, googleCredentialsJson, googleTokenJson,] = await Promise.all([
+            secretBroker.getSlackBotToken(),
+            secretBroker.getSlackAppToken(),
+            secretBroker.getTelegramBotToken(),
+            secretBroker.getDiscordBotToken(),
+            secretBroker.getNotionApiKey(),
+            secretBroker.getGitHubToken(),
+            secretBroker.getGitHubWebhookSecret(),
+            secretBroker.getApiToken(),
+            secretBroker.getGoogleCredentialsJson(),
+            secretBroker.getGoogleTokenJson(),
+        ]);
+        // SETUP-FLOW-REDESIGN-PLAN §6.1 — surface BYOA Outlook client config
+        // presence so the connections page knows when direct-mode Outlook
+        // integrations are resumable. Best-effort: if no blob store is
+        // wired (test harness), report `false` rather than crashing.
+        let outlookClientConfigConfigured = false;
+        try {
+            outlookClientConfigConfigured = deps.blobStore
+                ? await deps.blobStore.exists("mail:outlook:client-config")
+                : false;
+        }
+        catch {
+            outlookClientConfigConfigured = false;
+        }
+        return {
+            slackConfigured: !!(slackBotToken && slackAppToken),
+            telegramConfigured: !!telegramBotToken,
+            discordConfigured: !!discordBotToken,
+            notionConfigured: !!notionApiKey,
+            githubConfigured: !!githubToken,
+            githubWebhookSecretConfigured: !!githubWebhookSecret,
+            apiTokenConfigured: !!apiToken,
+            googleCalendarCredentialsConfigured: !!googleCredentialsJson,
+            googleCalendarTokenConfigured: !!googleTokenJson,
+            outlookClientConfigConfigured,
+            googleCredentialType: detectGoogleCredentialType(googleCredentialsJson),
+        };
+    }
+    async function notifySecretChange(scope) {
+        await deps.onSecretChanged?.(scope);
+    }
+    /**
+     * design/15-character.md §15.6.1 live-overwrite: when character changes,
+     * rewrite the `## Character` block inside every active session's
+     * instruction files (CLAUDE.md / AGENTS.md / GEMINI.md) so the next turn
+     * in the session picks up the new value without waiting for a session
+     * spawn. Per-workdir errors are counted and logged but never thrown —
+     * the DB write is already durable at the caller.
+     *
+     * Shared by PATCH /config (dashboard path, Approve tier) and
+     * PATCH /config/character (agent path, Notify tier).
+     */
+    function fanOutCharacterToActiveSessions() {
+        const sessions = db
+            .prepare(`SELECT id FROM conversation_sessions WHERE status = 'active'`)
+            .all();
+        const totals = { rewritten: 0, skipped: 0, failed: 0, missing: 0 };
+        for (const row of sessions) {
+            const sessionId = typeof row.id === "bigint" ? Number(row.id) : row.id;
+            const workdir = getSessionWorkdirPath(config.dataDir, sessionId);
+            if (!existsSync(workdir)) {
+                totals.missing++;
+                continue;
+            }
+            try {
+                const summary = rewriteCharacterBlock(workdir, config.character);
+                totals.rewritten += summary.rewritten;
+                totals.skipped += summary.skipped;
+                totals.failed += summary.failed;
+            }
+            catch (err) {
+                totals.failed++;
+                logger.warn({ err, sessionId, workdir }, "rewriteCharacterBlock threw on character live-overwrite");
+            }
+        }
+        logger.info({ ...totals, activeSessions: sessions.length }, "Character block fanned out to active session workdirs");
+    }
+    // ── Config API ──
+    /** GET /config — return current configuration */
+    app.get("/config", async (c) => {
+        const secretSummary = await getSecretConfigSummary();
+        const safeConfig = buildSafeConfig({ ...config, agentDisplayName: normalizeAgentDisplayName(config.agentDisplayName) }, secretSummary);
+        return c.json(safeConfig);
+    });
+    /** GET /config/defaults — return Zod schema defaults for all editable keys */
+    app.get("/config/defaults", (c) => {
+        const zodDefaults = runtimeSettingsSchema.parse({});
+        const defaults = {};
+        for (const key of EDITABLE_RUNTIME_KEY_TUPLE) {
+            const val = zodDefaults[key];
+            // Mirror GET /config shape: allowedToolsOverride null → empty array
+            if (key === "allowedToolsOverride") {
+                defaults.allowedTools = val ?? [];
+            }
+            else {
+                defaults[key] = val;
+            }
+        }
+        // Bootstrap keys not in runtimeSettingsSchema
+        defaults.apiPort = 8321;
+        return c.json(defaults);
+    });
+    /** PATCH /config — update one or more config fields */
+    app.patch("/config", async (c) => {
+        const parsedBody = await readJsonBody(c);
+        if (!parsedBody.ok)
+            return parsedBody.response;
+        const body = parsedBody.body;
+        if (!body || typeof body !== "object" || Array.isArray(body)) {
+            return c.json({ error: "Body must be a JSON object" }, 400);
+        }
+        const bodyRecord = { ...body };
+        if (Object.hasOwn(bodyRecord, "notionDatabaseIdsBase")) {
+            if (!Object.hasOwn(bodyRecord, "notionDatabaseIds")) {
+                return c.json({
+                    error: "validation_failed",
+                    details: {
+                        notionDatabaseIdsBase: "notionDatabaseIdsBase requires notionDatabaseIds in the same request",
+                    },
+                }, 400);
+            }
+            if (!isStringRecord(bodyRecord.notionDatabaseIdsBase)) {
+                return c.json({
+                    error: "validation_failed",
+                    details: {
+                        notionDatabaseIdsBase: "notionDatabaseIdsBase must be an object mapping labels to database IDs",
+                    },
+                }, 400);
+            }
+            if (!sameStringRecord(config.notionDatabaseIds, bodyRecord.notionDatabaseIdsBase)) {
+                return c.json({
+                    error: "conflict",
+                    message: "Notion database mappings changed on another tab. Reload and try again.",
+                }, 409);
+            }
+            delete bodyRecord.notionDatabaseIdsBase;
+        }
+        // Snapshot WhatsApp state BEFORE applying so we can detect a transition
+        // and trigger live enable/disable of the adapter (no daemon restart).
+        const prevWhatsappEnabled = config.whatsappEnabled;
+        const prevWhatsappOwnerPhone = config.whatsappOwnerPhone;
+        const prevWhatsappAuthDir = config.whatsappAuthDir;
+        // EXECUTION-MODE-DESIGN.md §5.2 / §6.3 — snapshot pre-apply execution mode
+        // so audit rows below can capture before → after per backend. The
+        // dedicated `POST /api/setup/mode` is the usual path (it emits its own
+        // audit row); this PATCH covers the power-user / env-style API caller
+        // who edits the key directly without going through the settings UI.
+        const prevExecMode = {
+            claude: config.claudeExecutionPermissionMode,
+            codex: config.codexExecutionPermissionMode,
+            gemini: config.geminiExecutionPermissionMode,
+        };
+        // design/15-character.md §15.6.1 — snapshot character pre-apply so the
+        // live-overwrite pass below has a stable "after" value to fan out to
+        // every active session workdir.
+        const prevCharacter = config.character;
+        // gitRepos / gitWatchedRepos no longer live in config — repository
+        // changes go through /api/repositories and trigger
+        // `onGitReposChanged` directly from that route.
+        // §6.2 Note Sources regeneration is centralized inside
+        // applyConfigUpdates (via the db option) — no inline hook in this
+        // handler. Any future caller of applyConfigUpdates that carries
+        // externalObsidianVaultPath / externalObsidianWatch automatically
+        // gets the same regeneration without copy-paste.
+        const result = await applyConfigUpdates(config, settingsStore, bodyRecord, {
+            db: deps.db,
+        });
+        if (Object.keys(result.errors).length > 0 && result.updated.length === 0) {
+            return c.json({ error: "validation_failed", details: result.errors }, 400);
+        }
+        // Hot-reload cron schedules when schedule-related config changes
+        const SCHEDULE_KEYS = [
+            "dayBoundaryHour",
+            "timezone",
+            "hourlyCheckEnabled",
+            "hourlyCheckIntervalMinutes",
+            "hourlyCheckActiveStartHour",
+            "hourlyCheckActiveEndHour",
+        ];
+        if (result.updated.some((k) => SCHEDULE_KEYS.includes(k))) {
+            deps.onScheduleConfigChanged?.();
+        }
+        // git repository changes route through POST/PATCH /api/repositories
+        // (unified-repositories cutover); they trigger onGitReposChanged
+        // from there, not from the dashboard config PATCH path.
+        // SCHEDULED-DM-IMPLEMENTATION-PLAN §6.7 — when quietHoursEnd
+        // changes, retime every enabled `dm_session` recurring row whose
+        // `task_context.pin_to_quiet_hours_end === true` so the briefing
+        // tracks the user's quiet-hours edge by default. Rows with the
+        // pin flag false (user-pinned a custom time) are left alone.
+        if (result.updated.includes("quietHoursEnd")
+            && typeof config.quietHoursEnd === "string"
+            && /^\d{2}:\d{2}$/.test(config.quietHoursEnd)) {
+            try {
+                syncDmSessionTimesToQuietHours(db, config.quietHoursEnd);
+                runDefaultSchedulesReconciler({
+                    db,
+                    contextDir: getContextDir(config, db),
+                    writeTracker: deps.writeTracker,
+                    onPromptContextChanged: deps.onPromptContextChanged,
+                    trigger: "manual",
+                }).catch((err) => {
+                    logger.warn({ err }, "Default-schedules reconciler failed after quietHoursEnd change");
+                });
+            }
+            catch (err) {
+                logger.warn({ err }, "syncDmSessionTimesToQuietHours threw after dashboard config PATCH");
+            }
+        }
+        // Hot-refresh DM session skill dirs when enabledMailProviders changes
+        // through the generic config PATCH. The per-endpoint `PATCH /mail/providers`
+        // handler already drives this through MailAccountRegistry.onScopeChanged,
+        // but the dashboard's catch-all config PATCH bypasses that route, so
+        // without this dispatch the scope toggle wouldn't reach active workdirs.
+        if (result.updated.includes("enabledMailProviders")) {
+            try {
+                deps.services.mail?.onProviderSelectionChanged(config.enabledMailProviders);
+            }
+            catch (err) {
+                logger.warn({ err }, "onProviderSelectionChanged threw after dashboard config PATCH");
+            }
+        }
+        // Hot-reload WhatsApp adapter when whatsappEnabled / phone / auth dir change.
+        // This eliminates the daemon-restart requirement that previously made
+        // pairing impossible from the dashboard.
+        const whatsappKeysTouched = result.updated.some((k) => ["whatsappEnabled", "whatsappOwnerPhone", "whatsappAuthDir"].includes(k));
+        if (whatsappKeysTouched && deps.whatsappControls) {
+            const phoneChanged = config.whatsappOwnerPhone !== prevWhatsappOwnerPhone;
+            const authDirChanged = config.whatsappAuthDir !== prevWhatsappAuthDir;
+            try {
+                if (!config.whatsappEnabled && prevWhatsappEnabled) {
+                    // disabled — tear down
+                    await deps.whatsappControls.disable();
+                }
+                else if (config.whatsappEnabled) {
+                    if (!prevWhatsappEnabled) {
+                        // newly enabled — build and start
+                        await deps.whatsappControls.enable();
+                    }
+                    else if (phoneChanged || authDirChanged) {
+                        // settings changed while enabled — bounce
+                        await deps.whatsappControls.disable();
+                        await deps.whatsappControls.enable();
+                    }
+                }
+                // Drop "whatsappEnabled" / phone / auth dir from requiresRestart since
+                // we just hot-reloaded them. Other restart-required keys (like Slack
+                // tokens) still report restart.
+                result.requiresRestart = result.requiresRestart.filter((k) => !["whatsappEnabled", "whatsappOwnerPhone", "whatsappAuthDir"].includes(k));
+            }
+            catch (err) {
+                const message = toSafeErrorMessage(err, "unknown WhatsApp error");
+                result.errors.whatsapp = `WhatsApp hot-reload failed: ${message}`;
+            }
+        }
+        // EXECUTION-MODE-DESIGN.md §6.3 — emit one `execution_mode_changed`
+        // audit row per backend whose mode moved through this PATCH, matching
+        // the row shape that `POST /api/setup/mode` writes. Without this the
+        // PATCH path would silently bypass audit coverage for a power-user
+        // API caller.
+        for (const [backend, key] of [
+            ["claude", "claudeExecutionPermissionMode"],
+            ["codex", "codexExecutionPermissionMode"],
+            ["gemini", "geminiExecutionPermissionMode"],
+        ]) {
+            if (!result.updated.includes(key))
+                continue;
+            const before = prevExecMode[backend];
+            const after = config[key];
+            if (before === after)
+                continue;
+            try {
+                db.prepare(`INSERT INTO agent_actions (action_type, trigger, result, detail, backend)
+             VALUES (?, ?, ?, ?, ?)`).run("execution_mode_changed", "dashboard_config_patch", "success", JSON.stringify({ before, after }), backend);
+            }
+            catch (err) {
+                logger.warn({ err, backend }, "failed to record execution_mode_changed audit row (PATCH path)");
+            }
+        }
+        if (result.updated.includes("agentDisplayName")) {
+            try {
+                const rulesRelPath = CONTEXT_RELATIVE_PATHS.rules.management;
+                const rulesSnapshotKey = rulesRelPath.replace(/\.md$/, "");
+                const rulesPath = join(getContextDir(config, db), rulesRelPath);
+                if (existsSync(rulesPath)) {
+                    const currentRules = readFileSync(rulesPath, "utf-8");
+                    const nextRules = upsertManagementRulesAgentIdentity(currentRules, normalizeAgentDisplayName(config.agentDisplayName));
+                    if (nextRules !== currentRules) {
+                        db.prepare("INSERT INTO md_file_snapshots (file_path, content, trigger) VALUES (?, ?, ?)").run(rulesSnapshotKey, currentRules, "agent_name_update");
+                        writeFileSync(rulesPath, nextRules, "utf-8");
+                    }
+                }
+            }
+            catch (err) {
+                const message = toSafeErrorMessage(err, `unknown ${CONTEXT_RELATIVE_PATHS.rules.management} error`);
+                result.errors.agentDisplayName = `Saved config, but failed to sync ${CONTEXT_RELATIVE_PATHS.rules.management}: ${message}`;
+            }
+            deps.onPromptContextChanged?.("agentDisplayName", "config_update:agentDisplayName", "loud", { tierReason: "config_agent_display_name" });
+        }
+        // design/15-character.md §15.6.1 — character changed; fan the new value
+        // out to every active session's instruction files.
+        if (result.updated.includes("character") && config.character !== prevCharacter) {
+            fanOutCharacterToActiveSessions();
+        }
+        return c.json({
+            status: "updated",
+            updated: result.updated,
+            requiresRestart: result.requiresRestart,
+            errors: result.errors,
+        });
+    });
+    /**
+     * GET /config/character — agent-callable read of the persona string.
+     *
+     * design/15-character.md §15.6 — the general /api/config surface is
+     * Approve-tier (contains secret summaries, OAuth state, schedule keys),
+     * so bearer-less callers (the agent's curl from a session workdir) need
+     * a narrowly scoped read. Returns the single field shape `{character}`
+     * so `jq .character` in skills keeps working.
+     */
+    app.get("/config/character", (c) => {
+        return c.json({ character: config.character });
+    });
+    /**
+     * PATCH /config/character — agent-callable write of the persona string.
+     *
+     * Notify tier: audit-logged by the auth middleware, no Bearer required.
+     * Accepts only `{character: string}` — extra keys are rejected so this
+     * route cannot be used as a side channel into other config fields.
+     * Zod validation (max 1000 chars, no marker substring, non-blank-or-empty)
+     * runs inside `applyConfigUpdates` as usual.
+     */
+    app.patch("/config/character", async (c) => {
+        const parsedBody = await readJsonBody(c);
+        if (!parsedBody.ok)
+            return parsedBody.response;
+        const body = parsedBody.body;
+        if (!body || typeof body !== "object" || Array.isArray(body)) {
+            return c.json({ error: "Body must be a JSON object" }, 400);
+        }
+        const bodyRecord = body;
+        const extraKeys = Object.keys(bodyRecord).filter((k) => k !== "character");
+        if (extraKeys.length > 0) {
+            return c.json({
+                error: "validation_failed",
+                details: {
+                    _extraKeys: `Only "character" is accepted on this endpoint; got: ${extraKeys.join(", ")}`,
+                },
+            }, 400);
+        }
+        if (!Object.hasOwn(bodyRecord, "character")) {
+            return c.json({
+                error: "validation_failed",
+                details: { character: "character field is required" },
+            }, 400);
+        }
+        const prevCharacter = config.character;
+        const result = await applyConfigUpdates(config, settingsStore, {
+            character: bodyRecord.character,
+        });
+        if (Object.keys(result.errors).length > 0 && result.updated.length === 0) {
+            return c.json({ error: "validation_failed", details: result.errors }, 400);
+        }
+        if (result.updated.includes("character") && config.character !== prevCharacter) {
+            fanOutCharacterToActiveSessions();
+        }
+        return c.json({
+            status: "updated",
+            character: config.character,
+            updated: result.updated,
+            errors: result.errors,
+        });
+    });
+    app.put("/secrets/slack", async (c) => {
+        const parsedBody = await readJsonBody(c);
+        if (!parsedBody.ok)
+            return parsedBody.response;
+        const body = parsedBody.body;
+        const botToken = typeof body?.botToken === "string" ? body.botToken.trim() : "";
+        const appToken = typeof body?.appToken === "string" ? body.appToken.trim() : "";
+        const validationErrors = {};
+        if (!botToken && !appToken) {
+            return c.json({
+                status: "validation_failed",
+                configured: false,
+                requiresRestart: false,
+                validationErrors: {
+                    botToken: "Provide at least one Slack token to save.",
+                    appToken: "Provide at least one Slack token to save.",
+                },
+            }, 400);
+        }
+        if (botToken)
+            await secretBroker.set("slackBotToken", botToken);
+        if (appToken)
+            await secretBroker.set("slackAppToken", appToken);
+        await notifySecretChange("slack");
+        return c.json({
+            status: "updated",
+            configured: (await getSecretConfigSummary()).slackConfigured,
+            requiresRestart: false,
+            validationErrors,
+        });
+    });
+    app.put("/secrets/telegram", async (c) => {
+        const parsedBody = await readJsonBody(c);
+        if (!parsedBody.ok)
+            return parsedBody.response;
+        const body = parsedBody.body;
+        const botToken = typeof body?.botToken === "string" ? body.botToken.trim() : "";
+        if (!botToken) {
+            return c.json({
+                status: "validation_failed",
+                configured: false,
+                requiresRestart: false,
+                validationErrors: { botToken: "Telegram bot token is required." },
+            }, 400);
+        }
+        await secretBroker.set("telegramBotToken", botToken);
+        await notifySecretChange("telegram");
+        return c.json({
+            status: "updated",
+            configured: (await getSecretConfigSummary()).telegramConfigured,
+            requiresRestart: false,
+            validationErrors: {},
+        });
+    });
+    app.put("/secrets/discord", async (c) => {
+        const parsedBody = await readJsonBody(c);
+        if (!parsedBody.ok)
+            return parsedBody.response;
+        const body = parsedBody.body;
+        const botToken = typeof body?.botToken === "string" ? body.botToken.trim() : "";
+        if (!botToken) {
+            return c.json({
+                status: "validation_failed",
+                configured: false,
+                requiresRestart: false,
+                validationErrors: { botToken: "Discord bot token is required." },
+            }, 400);
+        }
+        await secretBroker.set("discordBotToken", botToken);
+        await notifySecretChange("discord");
+        return c.json({
+            status: "updated",
+            configured: (await getSecretConfigSummary()).discordConfigured,
+            requiresRestart: false,
+            validationErrors: {},
+        });
+    });
+    app.put("/secrets/notion", async (c) => {
+        const parsedBody = await readJsonBody(c);
+        if (!parsedBody.ok)
+            return parsedBody.response;
+        const body = parsedBody.body;
+        const apiKey = typeof body?.apiKey === "string" ? body.apiKey.trim() : "";
+        if (!apiKey) {
+            return c.json({
+                status: "validation_failed",
+                configured: false,
+                requiresRestart: false,
+                validationErrors: { apiKey: "Notion API key is required." },
+            }, 400);
+        }
+        await secretBroker.set("notionApiKey", apiKey);
+        await notifySecretChange("notion");
+        return c.json({
+            status: "updated",
+            configured: (await getSecretConfigSummary()).notionConfigured,
+            requiresRestart: false,
+            validationErrors: {},
+        });
+    });
+    app.put("/secrets/github", async (c) => {
+        const parsedBody = await readJsonBody(c);
+        if (!parsedBody.ok)
+            return parsedBody.response;
+        const body = parsedBody.body;
+        const token = typeof body?.token === "string" ? body.token.trim() : "";
+        const webhookSecret = typeof body?.webhookSecret === "string" ? body.webhookSecret.trim() : "";
+        if (!token && !webhookSecret) {
+            return c.json({
+                status: "validation_failed",
+                configured: false,
+                requiresRestart: false,
+                validationErrors: {
+                    token: "Provide a GitHub token and/or webhook secret.",
+                    webhookSecret: "Provide a GitHub token and/or webhook secret.",
+                },
+            }, 400);
+        }
+        if (token)
+            await secretBroker.set("githubToken", token);
+        if (webhookSecret)
+            await secretBroker.set("githubWebhookSecret", webhookSecret);
+        await notifySecretChange("github");
+        const summary = await getSecretConfigSummary();
+        return c.json({
+            status: "updated",
+            configured: summary.githubConfigured || summary.githubWebhookSecretConfigured,
+            requiresRestart: false,
+            validationErrors: {},
+        });
+    });
+    app.put("/secrets/google/credentials", async (c) => {
+        const parsedBody = await readJsonBody(c);
+        if (!parsedBody.ok)
+            return parsedBody.response;
+        const body = parsedBody.body;
+        const raw = typeof body?.json === "string" ? body.json : "";
+        if (!raw) {
+            return c.json({
+                status: "validation_failed",
+                configured: false,
+                requiresRestart: false,
+                validationErrors: { json: "Credentials JSON is required." },
+            }, 400);
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(raw);
+        }
+        catch {
+            return c.json({
+                status: "validation_failed",
+                configured: false,
+                requiresRestart: false,
+                validationErrors: { json: "Invalid JSON file" },
+            }, 400);
+        }
+        if (!parsed.installed && !parsed.web && parsed.type !== "service_account") {
+            return c.json({
+                status: "validation_failed",
+                configured: false,
+                requiresRestart: false,
+                validationErrors: {
+                    json: "Invalid credentials format. Expected OAuth2 credentials JSON or a service account JSON.",
+                },
+            }, 400);
+        }
+        await secretBroker.set("googleCredentialsJson", raw);
+        if (parsed.type === "service_account") {
+            await secretBroker.delete("googleTokenJson");
+        }
+        await notifySecretChange("google");
+        deps.onGoogleServicesReady?.();
+        const summary = await getSecretConfigSummary();
+        return c.json({
+            status: "updated",
+            configured: summary.googleCalendarCredentialsConfigured,
+            requiresRestart: false,
+            validationErrors: {},
+        });
+    });
+    app.put("/secrets/google/token", async (c) => {
+        const parsedBody = await readJsonBody(c);
+        if (!parsedBody.ok)
+            return parsedBody.response;
+        const body = parsedBody.body;
+        const raw = typeof body?.json === "string" ? body.json : "";
+        if (!raw) {
+            return c.json({
+                status: "validation_failed",
+                configured: false,
+                requiresRestart: false,
+                validationErrors: { json: "Token JSON is required." },
+            }, 400);
+        }
+        try {
+            JSON.parse(raw);
+        }
+        catch {
+            return c.json({
+                status: "validation_failed",
+                configured: false,
+                requiresRestart: false,
+                validationErrors: { json: "Invalid JSON file" },
+            }, 400);
+        }
+        await secretBroker.saveGoogleTokenJson(raw);
+        await notifySecretChange("google");
+        deps.onGoogleServicesReady?.();
+        const summary = await getSecretConfigSummary();
+        return c.json({
+            status: "updated",
+            configured: summary.googleCalendarTokenConfigured,
+            requiresRestart: false,
+            validationErrors: {},
+        });
+    });
+    app.delete("/secrets/:name", async (c) => {
+        const name = c.req.param("name");
+        if (name === "apiToken") {
+            return c.json({
+                error: "api_token_not_deletable",
+                message: "The daemon API token cannot be deleted from the API. Rotate it explicitly instead.",
+            }, 400);
+        }
+        const secretNameByParam = {
+            slackBotToken: "slackBotToken",
+            slackAppToken: "slackAppToken",
+            telegramBotToken: "telegramBotToken",
+            discordBotToken: "discordBotToken",
+            notionApiKey: "notionApiKey",
+            githubToken: "githubToken",
+            githubWebhookSecret: "githubWebhookSecret",
+            googleCredentialsJson: "googleCredentialsJson",
+            googleTokenJson: "googleTokenJson",
+        };
+        const secretName = secretNameByParam[name];
+        if (!secretName) {
+            return c.json({ error: "unknown_secret" }, 404);
+        }
+        await secretBroker.delete(secretName);
+        const scopeBySecret = {
+            slackBotToken: "slack",
+            slackAppToken: "slack",
+            telegramBotToken: "telegram",
+            discordBotToken: "discord",
+            notionApiKey: "notion",
+            githubToken: "github",
+            githubWebhookSecret: "github",
+            googleCredentialsJson: "google",
+            googleTokenJson: "google",
+        };
+        await notifySecretChange(scopeBySecret[secretName]);
+        return c.json({
+            status: "deleted",
+            configured: false,
+            requiresRestart: false,
+            validationErrors: {},
+        });
+    });
+    app.get("/dashboard/next-check", (c) => {
+        return c.json(getNextHourlyCheck(config));
+    });
+    // STAGE-C-DM-FRESHNESS-PLAN §Task 4 — DM freshness aggregate. Powered
+    // by `agent_actions.detail.dm_freshness.*` rows the DM dispatch path
+    // writes via AuditLogger.logAction. Window defaults to 7 days; query
+    // param `days` overrides for ad-hoc inspection (clamped to 1..90).
+    app.get("/dashboard/dm-freshness", (c) => {
+        const daysParam = c.req.query("days");
+        let windowDays = 7;
+        if (daysParam !== undefined) {
+            const parsed = Number(daysParam);
+            if (!Number.isFinite(parsed) || parsed < 1 || parsed > 90) {
+                return c.json({
+                    error: "invalid_window",
+                    message: "days must be a number between 1 and 90",
+                }, 400);
+            }
+            windowDays = Math.round(parsed);
+        }
+        const aggregate = computeDmFreshnessAggregate(deps.db, windowDays);
+        return c.json(aggregate);
+    });
+    /**
+     * POST /messaging/whatsapp/pair
+     *
+     * Triggers Baileys pairing and waits up to ~10s for the first scannable QR.
+     * If WhatsApp isn't enabled yet, returns 409 with a clear hint instead of
+     * silently 404'ing — this surfaces the original setup-flow bug where users
+     * clicked Pair without first enabling.
+     */
+    app.post("/messaging/whatsapp/pair", async (c) => {
+        if (!deps.whatsappControls) {
+            return c.json({ error: "whatsapp_not_available" }, 404);
+        }
+        if (!config.whatsappEnabled) {
+            return c.json({
+                error: "whatsapp_not_enabled",
+                message: "Enable WhatsApp first (toggle the Enable button), then click Pair.",
+            }, 409);
+        }
+        if (!config.whatsappOwnerPhone) {
+            return c.json({
+                error: "whatsapp_phone_missing",
+                message: "Set the owner phone (E.164, e.g. +818012345678) and save before pairing.",
+            }, 409);
+        }
+        try {
+            const response = await deps.whatsappControls.waitForQr(10_000);
+            return c.json(response);
+        }
+        catch (err) {
+            const message = toSafeErrorMessage(err, "Unknown WhatsApp error");
+            return c.json({
+                error: "whatsapp_pair_failed",
+                message,
+                state: deps.whatsappControls.getQrResponse().state,
+            }, 500);
+        }
+    });
+    /**
+     * GET /messaging/whatsapp/qr
+     *
+     * Returns the current QR snapshot WITHOUT triggering a fresh pair flow.
+     * Dashboard polls this every ~3s while pairing is in progress so the user
+     * always sees the latest QR (Baileys rotates them every ~20s).
+     */
+    app.get("/messaging/whatsapp/qr", (c) => {
+        if (!deps.whatsappControls) {
+            return c.json({ error: "whatsapp_not_available" }, 404);
+        }
+        const response = deps.whatsappControls.getQrResponse();
+        return c.json({
+            ...response,
+            error: response.error ? toSafeErrorMessage(response.error) : null,
+        });
+    });
+    /**
+     * GET /messaging/whatsapp/status
+     *
+     * Lightweight health probe — connection state + last error, no QR fetch.
+     */
+    app.get("/messaging/whatsapp/status", (c) => {
+        if (!deps.whatsappControls) {
+            return c.json({ error: "whatsapp_not_available" }, 404);
+        }
+        const response = deps.whatsappControls.getQrResponse();
+        return c.json({
+            enabled: config.whatsappEnabled,
+            initialized: deps.whatsappControls.isInitialized(),
+            state: response.state,
+            error: response.error ? toSafeErrorMessage(response.error) : null,
+        });
+    });
+    // ── Telegram pairing ──────────────────────────────────────────────────
+    //
+    // Three endpoints support the dashboard's QR-deep-link pairing flow:
+    //   POST /messaging/telegram/test-token   — getMe (validate token)
+    //   POST /messaging/telegram/start-pairing — generate token + QR + deep link
+    //   GET  /messaging/telegram/pairing-status — poll until paired
+    //
+    // The QR encodes `https://t.me/<bot>?start=<token>`. When the user scans
+    // it, Telegram opens the bot and sends `/start <token>`; the adapter
+    // matches the token, captures the chat ID via discovery mode, and the
+    // daemon writes the ID into .env via the onOwnerDetected callback.
+    app.post("/messaging/telegram/test-token", async (c) => {
+        if (!deps.messagingControls?.telegram) {
+            return c.json({ error: "telegram_not_configured" }, 404);
+        }
+        // Accept an optional candidate token in the request body so the
+        // dashboard can validate an UNSAVED draft before persisting it.
+        const body = await c.req.json().catch(() => ({}));
+        const candidate = typeof body?.token === "string" && body.token.length > 0
+            ? body.token
+            : undefined;
+        try {
+            const info = await deps.messagingControls.telegram.testToken(candidate);
+            return c.json(info);
+        }
+        catch (err) {
+            return c.json({
+                error: "telegram_test_failed",
+                message: toSafeErrorMessage(err, "Telegram token validation failed"),
+            }, 400);
+        }
+    });
+    app.post("/messaging/telegram/start-pairing", async (c) => {
+        if (!deps.messagingControls?.telegram) {
+            return c.json({ error: "telegram_not_configured" }, 404);
+        }
+        try {
+            const result = await deps.messagingControls.telegram.startPairing();
+            return c.json(result);
+        }
+        catch (err) {
+            return c.json({
+                error: "telegram_pair_start_failed",
+                message: toSafeErrorMessage(err, "Telegram pairing could not start"),
+            }, 500);
+        }
+    });
+    app.get("/messaging/telegram/pairing-status", (c) => {
+        if (!deps.messagingControls?.telegram) {
+            return c.json({ error: "telegram_not_configured" }, 404);
+        }
+        return c.json(deps.messagingControls.telegram.getPairingStatus());
+    });
+    app.post("/messaging/telegram/cancel-pairing", (c) => {
+        if (!deps.messagingControls?.telegram) {
+            return c.json({ error: "telegram_not_configured" }, 404);
+        }
+        deps.messagingControls.telegram.cancelPairing();
+        return c.json({ status: "cancelled" });
+    });
+    // ── Slack pairing ─────────────────────────────────────────────────────
+    //
+    // Slack has no QR/deep-link mechanism, so we offer two helpers:
+    //   1. Token validation via auth.test
+    //   2. A pre-built app manifest (one-click app creation at api.slack.com)
+    //   3. Discovery mode for owner user ID — user DMs the bot, daemon captures
+    //
+    // The manifest uses Aitne's required scopes (im:history,
+    // chat:write, app_mentions:read) + Socket Mode + bot scopes. We do NOT
+    // include any oauth_redirect_url since Socket Mode bots don't need one.
+    app.post("/messaging/slack/test-token", async (c) => {
+        if (!deps.messagingControls?.slack) {
+            return c.json({ error: "slack_not_configured" }, 404);
+        }
+        const body = await c.req.json().catch(() => ({}));
+        const candidate = typeof body?.token === "string" && body.token.length > 0
+            ? body.token
+            : undefined;
+        try {
+            const info = await deps.messagingControls.slack.testToken(candidate);
+            return c.json(info);
+        }
+        catch (err) {
+            return c.json({
+                error: "slack_test_failed",
+                message: toSafeErrorMessage(err, "Slack token validation failed"),
+            }, 400);
+        }
+    });
+    app.get("/messaging/slack/manifest", (c) => {
+        // App manifest in JSON form. Slack supports both YAML and JSON in the
+        // `?manifest_json=` and `?manifest_yaml=` query params on the new-app
+        // create page (https://docs.slack.dev/app-manifests/...).
+        //
+        // Scope minimization (intentional, do not re-broaden):
+        //   - app_mentions:read — for @mentions in channels the user invited the bot to
+        //   - chat:write        — required to send messages
+        //   - files:read        — required to download user-uploaded files
+        //   - im:history        — required to receive `message.im` events
+        //   - im:read           — list/inspect direct-message channels
+        //   - im:write          — open a DM channel with the owner
+        //
+        // We DELIBERATELY OMIT:
+        //   - channels:history  — would let the bot read every message in every
+        //                         channel it's added to. Aitne only DMs,
+        //                         so this scope is pure attack surface.
+        //   - users:read        — not needed; resolveUserChannel() uses
+        //                         conversations.open with the configured user ID.
+        const manifest = {
+            display_information: {
+                name: APP_NAME,
+                description: "Local-first proactive assistant",
+                background_color: "#1a1a2e",
+            },
+            features: {
+                bot_user: {
+                    display_name: APP_NAME,
+                    always_online: true,
+                },
+            },
+            oauth_config: {
+                scopes: {
+                    bot: [
+                        "app_mentions:read",
+                        "chat:write",
+                        "files:read",
+                        "im:history",
+                        "im:read",
+                        "im:write",
+                    ],
+                },
+            },
+            settings: {
+                event_subscriptions: {
+                    bot_events: ["app_mention", "message.im"],
+                },
+                interactivity: { is_enabled: false },
+                org_deploy_enabled: false,
+                socket_mode_enabled: true,
+                token_rotation_enabled: false,
+            },
+        };
+        const manifestJson = JSON.stringify(manifest);
+        // Slack's "create app from manifest" deep link.
+        const createAppUrl = `https://api.slack.com/apps?new_app=1&manifest_json=${encodeURIComponent(manifestJson)}`;
+        return c.json({
+            manifest,
+            manifestJson,
+            createAppUrl,
+            instructions: [
+                "1. Click 'Open Slack app builder' below — Slack will pre-fill the manifest.",
+                "2. On the app page, scroll to 'Install App' and click Install to your workspace.",
+                "3. Copy the Bot User OAuth Token (xoxb-…) from 'OAuth & Permissions' into the field below.",
+                "4. Generate an App-Level Token (xapp-…) under 'Basic Information' → 'App-Level Tokens' with `connections:write` scope, paste it below.",
+                "5. Click Save Slack Config, then 'Generate pairing phrase' and DM the bot with the phrase.",
+            ],
+        });
+    });
+    /**
+     * POST /messaging/slack/start-pairing
+     *
+     * Generates a fresh magic phrase, registers it as the Slack adapter's
+     * pairing challenge, and returns it to the dashboard. The user must
+     * include this phrase in the next DM they send to the bot — only that
+     * matching DM captures the owner role. The previous "enable-discovery"
+     * endpoint was vulnerable to a 5-minute race where any DM could
+     * hijack ownership; the magic phrase closes that.
+     */
+    app.post("/messaging/slack/start-pairing", async (c) => {
+        if (!deps.messagingControls?.slack) {
+            return c.json({ error: "slack_not_configured" }, 404);
+        }
+        try {
+            const result = await deps.messagingControls.slack.startPairing();
+            return c.json(result);
+        }
+        catch (err) {
+            return c.json({
+                error: "slack_pair_start_failed",
+                message: toSafeErrorMessage(err, "Slack pairing could not start"),
+            }, 400);
+        }
+    });
+    app.post("/messaging/slack/cancel-pairing", (c) => {
+        if (!deps.messagingControls?.slack) {
+            return c.json({ error: "slack_not_configured" }, 404);
+        }
+        deps.messagingControls.slack.cancelPairing();
+        return c.json({ status: "cancelled" });
+    });
+    app.get("/messaging/slack/pairing-status", (c) => {
+        if (!deps.messagingControls?.slack) {
+            return c.json({ error: "slack_not_configured" }, 404);
+        }
+        return c.json(deps.messagingControls.slack.getPairingStatus());
+    });
+    // ── Discord pairing ───────────────────────────────────────────────────
+    //
+    // Discord parity: token validation + magic-phrase pairing for owner user ID.
+    app.post("/messaging/discord/test-token", async (c) => {
+        if (!deps.messagingControls?.discord) {
+            return c.json({ error: "discord_not_configured" }, 404);
+        }
+        const body = await c.req.json().catch(() => ({}));
+        const candidate = typeof body?.token === "string" && body.token.length > 0
+            ? body.token
+            : undefined;
+        try {
+            const info = await deps.messagingControls.discord.testToken(candidate);
+            return c.json(info);
+        }
+        catch (err) {
+            return c.json({
+                error: "discord_test_failed",
+                message: toSafeErrorMessage(err, "Discord token validation failed"),
+            }, 400);
+        }
+    });
+    app.post("/messaging/discord/start-pairing", async (c) => {
+        if (!deps.messagingControls?.discord) {
+            return c.json({ error: "discord_not_configured" }, 404);
+        }
+        try {
+            const result = await deps.messagingControls.discord.startPairing();
+            return c.json(result);
+        }
+        catch (err) {
+            return c.json({
+                error: "discord_pair_start_failed",
+                message: toSafeErrorMessage(err, "Discord pairing could not start"),
+            }, 400);
+        }
+    });
+    app.post("/messaging/discord/cancel-pairing", (c) => {
+        if (!deps.messagingControls?.discord) {
+            return c.json({ error: "discord_not_configured" }, 404);
+        }
+        deps.messagingControls.discord.cancelPairing();
+        return c.json({ status: "cancelled" });
+    });
+    app.get("/messaging/discord/pairing-status", (c) => {
+        if (!deps.messagingControls?.discord) {
+            return c.json({ error: "discord_not_configured" }, 404);
+        }
+        return c.json(deps.messagingControls.discord.getPairingStatus());
+    });
+    /** POST /config/upload/google-credentials — upload Google Calendar credentials JSON */
+    app.post("/config/upload/google-credentials", async (c) => {
+        const body = await c.req.parseBody();
+        const file = body["file"];
+        if (!file || !(file instanceof File)) {
+            return c.json({ error: "No file uploaded. Send as multipart with field name 'file'" }, 400);
+        }
+        if (file.size > MAX_UPLOAD_SIZE) {
+            return c.json({ error: `File too large (max ${MAX_UPLOAD_SIZE / 1024} KB)` }, 400);
+        }
+        const content = await file.text();
+        let parsed;
+        try {
+            parsed = JSON.parse(content);
+        }
+        catch {
+            return c.json({ error: "Invalid JSON file" }, 400);
+        }
+        // Basic validation: must be OAuth2 (installed/web) or service account
+        const obj = parsed;
+        if (!obj.installed && !obj.web && obj.type !== "service_account") {
+            return c.json({ error: "Invalid credentials format. Expected OAuth2 credentials JSON (with 'installed' or 'web' key) or a service account JSON." }, 400);
+        }
+        await secretBroker.set("googleCredentialsJson", content);
+        if (parsed.type === "service_account") {
+            await secretBroker.delete("googleTokenJson");
+        }
+        await notifySecretChange("google");
+        deps.onGoogleServicesReady?.();
+        return c.json({
+            status: "uploaded",
+            path: "keychain://google-credentials",
+            requiresRestart: false,
+            message: "Credentials saved.",
+        });
+    });
+    /** POST /config/upload/google-token — upload Google Calendar OAuth token JSON */
+    app.post("/config/upload/google-token", async (c) => {
+        const body = await c.req.parseBody();
+        const file = body["file"];
+        if (!file || !(file instanceof File)) {
+            return c.json({ error: "No file uploaded. Send as multipart with field name 'file'" }, 400);
+        }
+        if (file.size > MAX_UPLOAD_SIZE) {
+            return c.json({ error: `File too large (max ${MAX_UPLOAD_SIZE / 1024} KB)` }, 400);
+        }
+        const content = await file.text();
+        // Validate JSON
+        try {
+            JSON.parse(content);
+        }
+        catch {
+            return c.json({ error: "Invalid JSON file" }, 400);
+        }
+        await secretBroker.saveGoogleTokenJson(content);
+        await notifySecretChange("google");
+        deps.onGoogleServicesReady?.();
+        return c.json({
+            status: "uploaded",
+            path: "keychain://google-token",
+            requiresRestart: false,
+            message: "Token saved.",
+        });
+    });
+    // ── Google OAuth2 Authorization Flow ──
+    // Allows users to authenticate with just credentials.json — the daemon
+    // handles the full OAuth2 flow and saves the token automatically.
+    /** POST /config/google-auth/start — begin OAuth2 authorization */
+    app.post("/config/google-auth/start", async (c) => {
+        const credRaw = await secretBroker.getGoogleCredentialsJson();
+        if (!credRaw) {
+            return c.json({ error: "Upload credentials.json first" }, 400);
+        }
+        let cred;
+        try {
+            cred = parseGoogleCredentialsJson(credRaw);
+        }
+        catch {
+            return c.json({ error: "Credentials JSON is invalid. Upload it again." }, 400);
+        }
+        // Service accounts don't need OAuth2 authorization
+        if (cred.type === "service_account") {
+            return c.json({ error: "Service account credentials don't require OAuth authorization. Restart the daemon to activate." }, 400);
+        }
+        const clientConfig = getGoogleOAuthClientConfig(cred);
+        if (!clientConfig) {
+            return c.json({ error: "Invalid credentials format" }, 400);
+        }
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        let google;
+        try {
+            const mod = await import("googleapis");
+            google = mod.google;
+        }
+        catch {
+            return c.json({ error: "googleapis package not installed" }, 500);
+        }
+        // Use daemon's own port for the OAuth callback
+        const redirectUri = `http://localhost:${config.apiPort}/api/config/google-auth/callback`;
+        const oauth2Client = new google.auth.OAuth2(clientConfig.client_id, clientConfig.client_secret, redirectUri);
+        // Request scopes for Calendar + Gmail
+        const scopes = [
+            "https://www.googleapis.com/auth/calendar",
+            "https://www.googleapis.com/auth/gmail.modify",
+            "https://www.googleapis.com/auth/gmail.send",
+        ];
+        pruneOauthStates();
+        const state = randomUUID();
+        // Capture the dashboard origin so the callback can postMessage to the correct window
+        const origin = c.req.header("origin");
+        const referer = c.req.header("referer");
+        const dashboardOrigin = origin
+            || (referer ? new URL(referer).origin : `http://localhost:3000`);
+        oauthStates.set(state, { createdAt: Date.now(), dashboardOrigin });
+        const authUrl = oauth2Client.generateAuthUrl({
+            access_type: "offline",
+            scope: scopes,
+            prompt: "consent", // Force consent to always get a refresh_token
+            state,
+        });
+        return c.json({ authUrl, redirectUri, scopes });
+    });
+    /** GET /config/google-auth/callback — OAuth2 redirect handler */
+    app.get("/config/google-auth/callback", async (c) => {
+        const code = c.req.query("code");
+        const error = c.req.query("error");
+        const state = c.req.query("state");
+        if (error) {
+            return c.html(`<!DOCTYPE html><html><body style="font-family:system-ui;text-align:center;padding:60px">
+        <h2 style="color:#dc2626">Authorization Failed</h2>
+        <p>${escapeHtml(error)}</p>
+        <p style="color:#666;font-size:14px">You can close this window.</p>
+      </body></html>`);
+        }
+        pruneOauthStates();
+        const stateData = state ? oauthStates.get(state) : undefined;
+        if (!state || !stateData) {
+            return c.html(`<!DOCTYPE html><html><body style="font-family:system-ui;text-align:center;padding:60px">
+        <h2 style="color:#dc2626">Authorization Failed</h2>
+        <p>Invalid or expired OAuth state.</p>
+        <p style="color:#666;font-size:14px">Start the authorization flow again from the dashboard.</p>
+      </body></html>`);
+        }
+        const { dashboardOrigin } = stateData;
+        oauthStates.delete(state);
+        if (!code) {
+            return c.html(`<!DOCTYPE html><html><body style="font-family:system-ui;text-align:center;padding:60px">
+        <h2 style="color:#dc2626">Error</h2>
+        <p>No authorization code received.</p>
+      </body></html>`);
+        }
+        // Re-create OAuth2 client from stored credentials
+        const credRaw = await secretBroker.getGoogleCredentialsJson();
+        if (!credRaw) {
+            return c.html(`<!DOCTYPE html><html><body style="font-family:system-ui;text-align:center;padding:60px">
+        <h2 style="color:#dc2626">Error</h2>
+        <p>Credentials not configured.</p>
+      </body></html>`);
+        }
+        try {
+            const cred = parseGoogleCredentialsJson(credRaw);
+            const clientConfig = getGoogleOAuthClientConfig(cred);
+            if (!clientConfig)
+                throw new Error("Invalid credentials");
+            const mod = await import("googleapis");
+            const google = mod.google;
+            const redirectUri = `http://localhost:${config.apiPort}/api/config/google-auth/callback`;
+            const oauth2Client = new google.auth.OAuth2(clientConfig.client_id, clientConfig.client_secret, redirectUri);
+            // Exchange authorization code for tokens
+            const { tokens } = await oauth2Client.getToken(code);
+            await secretBroker.saveGoogleTokenJson(JSON.stringify(tokens));
+            await notifySecretChange("google");
+            deps.onGoogleServicesReady?.();
+            const statusMsg = services.calendar || services.gmail
+                ? "Services activated."
+                : "Token saved.";
+            return c.html(`<!DOCTYPE html><html><body style="font-family:system-ui;text-align:center;padding:60px">
+        <h2 style="color:#059669">Authorization Successful</h2>
+        <p>${escapeHtml(statusMsg)}</p>
+        <p style="color:#666;font-size:14px">You can close this window.</p>
+        <script>
+          if (window.opener) {
+            window.opener.postMessage({ type: "google-auth-success" }, ${JSON.stringify(dashboardOrigin)});
+          }
+        </script>
+      </body></html>`);
+        }
+        catch (err) {
+            const msg = toSafeErrorMessage(err, "Unknown error");
+            return c.html(`<!DOCTYPE html><html><body style="font-family:system-ui;text-align:center;padding:60px">
+        <h2 style="color:#dc2626">Token Exchange Failed</h2>
+        <p>${escapeHtml(msg)}</p>
+        <p style="color:#666;font-size:14px">You can close this window and try again.</p>
+      </body></html>`);
+        }
+    });
+    /** POST /config/reset-safety — reset disallowedTools to defaults */
+    app.post("/config/reset-safety", async (c) => {
+        const defaults = [...DEFAULT_DISALLOWED_TOOLS];
+        // Actually persist the reset — update in-memory config and .env
+        // Use null for allowedToolsOverride to match the Zod default (null = "no override")
+        const result = await applyConfigUpdates(config, settingsStore, {
+            disallowedTools: defaults,
+            allowedToolsOverride: null,
+        });
+        return c.json({ status: "reset", disallowedTools: defaults, ...result });
+    });
+    // ── Events/Logs API ──
+    /** GET /events — paginated event/action log */
+    app.get("/events", (c) => {
+        const page = Math.max(1, Number(c.req.query("page") ?? "1"));
+        const limit = Math.min(Number(c.req.query("limit") ?? "50"), 100);
+        const offset = (page - 1) * limit;
+        const type = c.req.query("type");
+        const result = c.req.query("result");
+        const days = c.req.query("days"); // "1" (today), "7", "30"
+        let whereClause = "WHERE 1=1";
+        const params = [];
+        if (type) {
+            whereClause += " AND action_type = ?";
+            params.push(type);
+        }
+        if (result) {
+            whereClause += " AND result = ?";
+            params.push(result);
+        }
+        if (days) {
+            const d = Number(days);
+            if (d > 0 && d <= 365) {
+                // datetime(started_at) normalizes mixed ISO-8601 / SQL formats — the
+                // delegated_proxy.invoke writer historically inserted ISO-with-T-and-Z
+                // strings, which sort lexicographically above same-day SQL strings.
+                whereClause += " AND datetime(started_at) > datetime('now', '-' || ? || ' days')";
+                params.push(d);
+            }
+        }
+        const total = db
+            .prepare(`SELECT COUNT(*) as cnt FROM agent_actions ${whereClause}`)
+            .get(...params);
+        params.push(limit, offset);
+        const rows = db
+            .prepare(`SELECT id, event_id, action_type, trigger, model_used, model_usage_json, cost_usd,
+                tokens_input, tokens_output,
+                cache_creation_tokens, cache_read_tokens,
+                duration_ms, num_turns,
+                result, detail, started_at, completed_at, error
+         FROM agent_actions ${whereClause}
+         ORDER BY datetime(started_at) DESC, id DESC
+         LIMIT ? OFFSET ?`)
+            .all(...params);
+        return c.json({
+            events: rows,
+            pagination: {
+                page,
+                limit,
+                total: total.cnt,
+                totalPages: Math.ceil(total.cnt / limit),
+            },
+        });
+    });
+    // ── Conversations API ──
+    /** GET /conversations — paginated conversation sessions */
+    app.get("/conversations", (c) => {
+        const page = Number(c.req.query("page") ?? "1");
+        const limit = Math.min(Number(c.req.query("limit") ?? "20"), 50);
+        const offset = (page - 1) * limit;
+        const platform = c.req.query("platform");
+        const status = c.req.query("status");
+        const scope = c.req.query("scope");
+        const scopes = scope
+            ?.split(",")
+            .map((value) => value.trim())
+            .filter((value) => value.length > 0);
+        let whereClause = "WHERE 1=1";
+        const params = [];
+        if (platform) {
+            whereClause += " AND platform = ?";
+            params.push(platform);
+        }
+        if (status) {
+            whereClause += " AND status = ?";
+            params.push(status);
+        }
+        if (scopes && scopes.length > 0) {
+            if (scopes.length === 1) {
+                whereClause += " AND scope = ?";
+                params.push(scopes[0]);
+            }
+            else {
+                whereClause += ` AND scope IN (${scopes.map(() => "?").join(", ")})`;
+                params.push(...scopes);
+            }
+        }
+        else {
+            // Default view excludes docs_qa: QA transcripts are short lookups
+            // and would drown out chat in /activity. Operators opt in with the
+            // explicit `?scope=docs_qa` filter chip.
+            whereClause += " AND scope != ?";
+            params.push(DOCS_QA_SCOPE);
+        }
+        const total = db
+            .prepare(`SELECT COUNT(*) as cnt FROM conversation_sessions ${whereClause}`)
+            .get(...params);
+        params.push(limit, offset);
+        const rows = db
+            .prepare(`SELECT id, platform, channel_id, thread_id, scope, model, status,
+                message_count, started_at, last_message_at, is_dm, backend_session_id
+         FROM conversation_sessions ${whereClause}
+         ORDER BY last_message_at DESC
+         LIMIT ? OFFSET ?`)
+            .all(...params);
+        const sourcePlatformsStmt = db.prepare(`SELECT DISTINCT platform
+         FROM messages
+        WHERE session_id = ?
+        ORDER BY CASE platform
+          WHEN 'dashboard' THEN 0
+          WHEN 'whatsapp' THEN 1
+          WHEN 'telegram' THEN 2
+          WHEN 'slack' THEN 3
+          WHEN 'discord' THEN 4
+          ELSE 99
+        END, platform`);
+        const conversations = rows.map((row) => {
+            const sourcePlatforms = sourcePlatformsStmt.all(row.id).map((platformRow) => platformRow.platform);
+            const normalizedSourcePlatforms = sourcePlatforms.length > 0
+                ? sourcePlatforms
+                : row.platform !== "owner"
+                    ? [row.platform]
+                    : [];
+            const browserOnly = normalizedSourcePlatforms.length > 0
+                && normalizedSourcePlatforms.every((platform) => platform === "dashboard");
+            return {
+                id: row.id,
+                platform: row.platform,
+                channel_id: row.channel_id,
+                thread_id: row.thread_id,
+                model: row.model,
+                status: row.status,
+                message_count: row.message_count,
+                started_at: row.started_at,
+                last_message_at: row.last_message_at,
+                summary: null,
+                source_platforms: normalizedSourcePlatforms,
+                read_only_from_dashboard: normalizedSourcePlatforms.length === 0 ||
+                    normalizedSourcePlatforms.some((platform) => platform !== "dashboard"),
+                // A session is continuable when the dispatcher can actually
+                // execute against it — not when its stored SDK session id is
+                // non-null. `continueDashboardSession` legitimately writes
+                // `backend_session_id = NULL` on the `shouldInvalidateSdkSession`
+                // path, and the dispatcher falls back to fresh-execute + history
+                // injection for NULL backends. The real gates are: scope,
+                // browser-only provenance, and the workdir surviving on disk.
+                continue_available: row.scope === DASHBOARD_CHAT_SCOPE
+                    && browserOnly
+                    && existsSync(getSessionWorkdirPath(config.dataDir, row.id)),
+            };
+        });
+        return c.json({
+            conversations,
+            pagination: {
+                page,
+                limit,
+                total: total.cnt,
+                totalPages: Math.ceil(total.cnt / limit),
+            },
+        });
+    });
+    /**
+     * DELETE /conversations — bulk-delete every non-active sidebar session.
+     * Scope is hard-coded to `dashboard_chat` + `owner_dm` (what the chat
+     * sidebar shows); the live active session is filtered out so deleting
+     * "all past sessions" never kills the current chat.
+     */
+    app.delete("/conversations", (c) => {
+        const result = deleteAllChatSidebarSessions({ db, dataDir: config.dataDir });
+        return c.json({ status: "deleted", deleted: result.deleted });
+    });
+    /** DELETE /conversations/:id — delete one non-active sidebar session. */
+    app.delete("/conversations/:id", (c) => {
+        const sessionId = Number(c.req.param("id"));
+        if (!Number.isFinite(sessionId) || sessionId <= 0) {
+            return c.json({ error: "invalid_session_id" }, 400);
+        }
+        const result = deleteChatSession({
+            db,
+            dataDir: config.dataDir,
+            sessionId,
+        });
+        if (!result.ok) {
+            return c.json({ error: "delete_failed", message: result.message }, result.status);
+        }
+        return c.json({ status: "deleted", deleted: result.deleted });
+    });
+    /** GET /conversations/:id/messages — messages for a specific conversation */
+    app.get("/conversations/:id/messages", (c) => {
+        const sessionId = Number(c.req.param("id"));
+        const limit = Math.min(Number(c.req.query("limit") ?? "50"), 200);
+        const before = c.req.query("before"); // cursor-based pagination
+        let whereClause = "WHERE session_id = ?";
+        const params = [sessionId];
+        if (before) {
+            whereClause += " AND id < ?";
+            params.push(Number(before));
+        }
+        params.push(limit);
+        const rows = db
+            .prepare(`SELECT id, role, content, platform, sender_id, timestamp
+         FROM messages ${whereClause}
+         ORDER BY id DESC
+         LIMIT ?`)
+            .all(...params);
+        // Chat-attachments Phase 1 — inline attachment refs per message so
+        // the dashboard transcript can render thumbnails/download chips
+        // alongside past messages without an extra round-trip per row.
+        // Skipped when the chat_attachments table doesn't exist (older DB
+        // snapshots / tests that don't run migrations).
+        const hasAttachments = (() => {
+            try {
+                const row = db
+                    .prepare(`SELECT name FROM sqlite_master WHERE type='table' AND name='chat_attachments'`)
+                    .get();
+                return row !== undefined;
+            }
+            catch {
+                return false;
+            }
+        })();
+        const attachmentsByMessage = new Map();
+        if (hasAttachments && rows.length > 0) {
+            const ids = rows.map((r) => r.id);
+            const placeholders = ids.map(() => "?").join(",");
+            const attachmentRows = db
+                .prepare(`SELECT message_id, id, direction, original_filename, mime_type, size_bytes, caption
+           FROM chat_attachments
+           WHERE message_id IN (${placeholders})
+           ORDER BY created_at ASC`)
+                .all(...ids);
+            for (const a of attachmentRows) {
+                let bucket = attachmentsByMessage.get(a.message_id);
+                if (!bucket) {
+                    bucket = [];
+                    attachmentsByMessage.set(a.message_id, bucket);
+                }
+                bucket.push({
+                    id: a.id,
+                    direction: a.direction,
+                    originalFilename: a.original_filename,
+                    mimeType: a.mime_type,
+                    sizeBytes: a.size_bytes,
+                    caption: a.caption,
+                });
+            }
+        }
+        const enriched = rows.map((row) => {
+            const attachments = attachmentsByMessage.get(row.id);
+            return attachments && attachments.length > 0
+                ? { ...row, attachments }
+                : row;
+        });
+        return c.json({
+            messages: enriched.reverse(), // Return in chronological order
+            hasMore: rows.length === limit,
+        });
+    });
+    // ── Cost API ──
+    /** GET /cost — cost analytics */
+    app.get("/cost", (c) => {
+        const period = c.req.query("period") ?? "daily"; // daily, weekly, monthly
+        const periodKey = period in COST_QUERIES
+            ? period
+            : "daily";
+        const queries = COST_QUERIES[periodKey];
+        const spec = COST_PERIOD_SPECS[periodKey];
+        const byPeriod = db.prepare(queries.byPeriod).all();
+        const byModelRaw = db.prepare(queries.byModelRows).all();
+        const byModel = aggregateByBilledModel(byModelRaw);
+        const byEventType = db.prepare(queries.byEventType).all();
+        const byBackend = db
+            .prepare(`SELECT ${backendExpr} as backend,
+                SUM(cost_usd) as total_cost,
+                COUNT(*) as session_count
+           FROM agent_actions
+          WHERE started_at > datetime('now', ?)
+            AND cost_usd IS NOT NULL
+          GROUP BY 1
+          ORDER BY total_cost DESC`)
+            .all(spec.sinceExpr);
+        const byBackendPeriod = db
+            .prepare(`SELECT ${spec.bucketExpr} as period,
+                ${backendExpr} as backend,
+                SUM(cost_usd) as total_cost,
+                COUNT(*) as session_count
+           FROM agent_actions
+          WHERE started_at > datetime('now', ?)
+            AND cost_usd IS NOT NULL
+          GROUP BY 1, 2
+          ORDER BY period DESC, backend ASC`)
+            .all(spec.sinceExpr);
+        // Today's total (timezone-aware agent day, executed sessions only).
+        // datetime(started_at) normalizes mixed ISO-8601 / SQL formats — same
+        // rationale as the /events ORDER BY fix above.
+        const bounds = getAgentDayBoundsUtc(config.timezone, config.dayBoundaryHour);
+        const today = db
+            .prepare(`SELECT COALESCE(SUM(cost_usd), 0) as cost,
+                COUNT(*) as sessions
+         FROM agent_actions
+         WHERE datetime(started_at) >= ? AND datetime(started_at) < ?
+           AND cost_usd IS NOT NULL`)
+            .get(bounds.start, bounds.end);
+        return c.json({
+            period,
+            today: { costUsd: today.cost, sessions: today.sessions },
+            byPeriod,
+            byModel,
+            byEventType,
+            byBackend,
+            byBackendPeriod,
+        });
+    });
+    // ── Approvals API ──
+    /** GET /approvals — list pending approval requests */
+    app.get("/approvals", (c) => {
+        const rows = db
+            .prepare(`SELECT id, scheduled_for, task_type, task_description,
+                task_context, model, status, created_at
+         FROM agent_schedule
+         WHERE status = 'pending' AND task_type = 'approval'
+         ORDER BY created_at DESC`)
+            .all();
+        return c.json({ approvals: rows });
+    });
+    /** POST /approvals/:id/approve — approve a pending request */
+    app.post("/approvals/:id/approve", (c) => {
+        const id = Number(c.req.param("id"));
+        const result = db
+            .prepare("UPDATE agent_schedule SET status = 'pending', task_type = 'approved_task' WHERE id = ? AND status = 'pending' AND task_type = 'approval'")
+            .run(id);
+        if (result.changes === 0) {
+            return c.json({ error: "approval not found or already processed" }, 404);
+        }
+        return c.json({ status: "approved", id });
+    });
+    /** POST /approvals/:id/deny — deny a pending request */
+    app.post("/approvals/:id/deny", (c) => {
+        const id = Number(c.req.param("id"));
+        const result = db
+            .prepare("UPDATE agent_schedule SET status = 'skipped' WHERE id = ? AND status = 'pending' AND task_type = 'approval'")
+            .run(id);
+        if (result.changes === 0) {
+            return c.json({ error: "approval not found or already processed" }, 404);
+        }
+        return c.json({ status: "denied", id });
+    });
+    // ── Schedule API ──
+    /** GET /schedule/next — next pending scheduled task */
+    app.get("/schedule/next", (c) => {
+        const row = db
+            .prepare(`SELECT id, scheduled_for, task_type, task_description
+         FROM agent_schedule
+         WHERE status = 'pending' AND scheduled_for > datetime('now')
+         ORDER BY scheduled_for ASC LIMIT 1`)
+            .get();
+        return c.json({ next: row ?? null });
+    });
+    /** GET /schedule/list — all scheduled tasks (paginated) */
+    app.get("/schedule/list", (c) => {
+        const page = Math.max(1, Number(c.req.query("page") ?? "1"));
+        const limit = Math.min(Number(c.req.query("limit") ?? "20"), 50);
+        const status = c.req.query("status");
+        const type = c.req.query("type");
+        const offset = (page - 1) * limit;
+        let where = "1=1";
+        const params = [];
+        if (status) {
+            where += " AND status = ?";
+            params.push(status);
+        }
+        if (type) {
+            where += " AND task_type = ?";
+            params.push(type);
+        }
+        const total = db
+            .prepare(`SELECT COUNT(*) as count FROM agent_schedule WHERE ${where}`)
+            .get(...params).count;
+        params.push(limit, offset);
+        const schedules = db
+            .prepare(`SELECT id, scheduled_for, task_type, task_description, task_prompt, model, status, task_context, created_at
+         FROM agent_schedule WHERE ${where}
+         ORDER BY scheduled_for DESC LIMIT ? OFFSET ?`)
+            .all(...params);
+        return c.json({
+            schedules,
+            pagination: { page, limit, total, totalPages: Math.ceil(total / limit) },
+        });
+    });
+    // ── Search API ──
+    /** GET /search?q= — full-text search via FTS5 */
+    app.get("/search", (c) => {
+        const q = c.req.query("q");
+        if (!q || q.length < 2)
+            return c.json({ error: "query too short" }, 400);
+        if (q.length > 200)
+            return c.json({ error: "query too long" }, 400);
+        const limit = Math.min(Number(c.req.query("limit") ?? "20"), 50);
+        // Sanitize: wrap each word in double-quotes to disable FTS5 operators (NEAR, NOT, OR, etc.)
+        const safeQuery = q
+            .replace(/[^\w\s\u3000-\u9FFF\uF900-\uFAFF]/g, " ") // strip punctuation except CJK
+            .split(/\s+/)
+            .filter(Boolean)
+            .map((w) => `"${w}"`)
+            .join(" ");
+        if (!safeQuery)
+            return c.json({ actions: [], messages: [] });
+        let actions = [];
+        let messages = [];
+        try {
+            actions = db
+                .prepare(`SELECT a.id, a.action_type, a.started_at,
+                  highlight(fts_actions, 1, '<mark>', '</mark>') as snippet
+           FROM fts_actions JOIN agent_actions a ON a.id = fts_actions.rowid
+           WHERE fts_actions MATCH ? ORDER BY rank LIMIT ?`)
+                .all(safeQuery, limit);
+        }
+        catch {
+            // FTS table may not exist yet
+        }
+        try {
+            messages = db
+                .prepare(`SELECT m.id, m.role, m.timestamp, m.session_id,
+                  highlight(fts_messages, 0, '<mark>', '</mark>') as snippet
+           FROM fts_messages JOIN messages m ON m.id = fts_messages.rowid
+           WHERE fts_messages MATCH ? ORDER BY rank LIMIT ?`)
+                .all(safeQuery, limit);
+        }
+        catch {
+            // FTS table may not exist yet
+        }
+        return c.json({ actions, messages });
+    });
+    // ── Snapshots API ──
+    /** GET /snapshots/content/:id — single snapshot content */
+    app.get("/snapshots/content/:id", (c) => {
+        const id = Number(c.req.param("id"));
+        if (!Number.isSafeInteger(id) || id <= 0) {
+            return c.json({ error: "invalid id" }, 400);
+        }
+        const row = db
+            .prepare("SELECT id, file_path, content, trigger, created_at FROM md_file_snapshots WHERE id = ?")
+            .get(id);
+        if (!row)
+            return c.json({ error: "not_found" }, 404);
+        return c.json(row);
+    });
+    /** GET /snapshots/* — snapshot history for a context file */
+    app.get("/snapshots/*", (c) => {
+        const filePath = c.req.path.replace("/api/snapshots/", "");
+        // Validate: reject path traversal and unsafe characters
+        if (!filePath || /\.\./.test(filePath) || !/^[\w./-]+$/.test(filePath)) {
+            return c.json({ error: "invalid file path" }, 400);
+        }
+        const limit = Math.min(Number(c.req.query("limit") ?? "20"), 50);
+        const rows = db
+            .prepare(`SELECT id, file_path, trigger, session_id, created_at
+         FROM md_file_snapshots WHERE file_path = ?
+         ORDER BY created_at DESC LIMIT ?`)
+            .all(filePath, limit);
+        return c.json({ snapshots: rows });
+    });
+    // ── Notifications API ──
+    /** GET /notifications — notification history (paginated) */
+    app.get("/notifications", (c) => {
+        const page = Math.max(1, Number(c.req.query("page") ?? "1"));
+        const limit = Math.min(Number(c.req.query("limit") ?? "50"), 100);
+        const status = c.req.query("status");
+        const priority = c.req.query("priority");
+        const offset = (page - 1) * limit;
+        let where = "1=1";
+        const params = [];
+        if (status) {
+            where += " AND status = ?";
+            params.push(status);
+        }
+        if (priority) {
+            where += " AND priority = ?";
+            params.push(priority);
+        }
+        const total = db
+            .prepare(`SELECT COUNT(*) as count FROM notification_log WHERE ${where}`)
+            .get(...params).count;
+        params.push(limit, offset);
+        const notifications = db
+            .prepare(`SELECT
+           id,
+           dispatch_id,
+           content_summary AS message,
+           platform,
+           delivery_channel,
+           priority,
+           status,
+           user_reaction,
+           reacted_at,
+           created_at
+         FROM notification_log WHERE ${where}
+         ORDER BY created_at DESC LIMIT ? OFFSET ?`)
+            .all(...params);
+        return c.json({
+            notifications,
+            pagination: { page, limit, total, totalPages: Math.ceil(total / limit) },
+        });
+    });
+    return app;
+}
+//# sourceMappingURL=dashboard.js.map