@aitne/daemon 0.1.9 → 0.1.11

package/dist/db/activity-scan-signals.js

@@ -0,0 +1,378 @@
+/**
+ * Stage-0 signal compute for the three-stage activity_scan gate
+ * (cost-reduction-structural §B). Pure DB-read shape: every value is
+ * derived from existing tables (`observations`, `mail_messages_index`,
+ * `agent_schedule`, `agent_actions`) plus the optional today.md content
+ * passed in by the caller. No LLM call, no filesystem I/O of its own —
+ * the dispatcher injects the today.md snapshot (when available) so this
+ * module stays unit-testable from a synthetic Database handle.
+ *
+ * The shape mirrors the design doc 1:1 so the gate (Stage 1) can be
+ * a pure function over `ActivityScanSignals` + a config block.
+ */
+import { buildSourcePrefixFilter, } from "@aitne/shared";
+/**
+ * Build a `(source LIKE 'a:%' OR source LIKE 'b:%' ...)` clause covering
+ * every direct-poller and pre-pass-partial prefix for the given kinds.
+ * Sourced from `INTEGRATION_DESCRIPTORS` so a new integration shipping
+ * with `prePassPartial: "<kind>-acquire.<key>.md"` auto-extends the
+ * gate's view of the world. Empty `kinds` yields `(1=0)` (defensive).
+ *
+ * CLAUDE.md: "Never hardcode an integration reference outside the
+ * registry."
+ */
+function sourceMatchClause(kinds) {
+    return buildSourcePrefixFilter(kinds);
+}
+/** All-kinds union — every observation source the gate cares about. */
+const ALL_KINDS = [
+    "mail",
+    "calendar",
+    "notion",
+    "vault",
+    "repo",
+];
+export function computeActivityScanSignals(db, options = {}) {
+    const now = options.now ?? new Date();
+    const vipSenders = (options.vipMailSenders ?? []).map((s) => s.toLowerCase());
+    const calendarHorizonMs = (options.calendarHorizonHours ?? 24) * 60 * 60 * 1000;
+    const scheduleHorizonHours = options.scheduleHorizonHours ?? 6;
+    // Gate filters by `source` (mail/calendar/notion/vault/repo), NEVER by
+    // `actor`. Delegated-sync-worker and the routine.fetch_window pre-pass
+    // both POST `actor='agent'` rows; the gate must see them as real
+    // activity. The 30-min `pre_pass_last_run:<key>` freshness window in
+    // `ActivityScanCoordinator.harvestForGate` structurally prevents a
+    // single pre-pass row from being re-counted across ticks.
+    const allFilter = sourceMatchClause(ALL_KINDS);
+    const pending = db
+        .prepare(`SELECT COUNT(*) AS count
+         FROM observations
+        WHERE consumed_at IS NULL
+          AND ${allFilter.clause}`)
+        .get(...allFilter.values);
+    const noveltyMaxRow = db
+        .prepare(`SELECT MAX(novelty_score) AS max_score
+         FROM observations
+        WHERE consumed_at IS NULL
+          AND summary_status = 'done'
+          AND novelty_score IS NOT NULL
+          AND ${allFilter.clause}`)
+        .get(...allFilter.values);
+    const distributionRows = db
+        .prepare(`SELECT novelty_score AS score, COUNT(*) AS count
+         FROM observations
+        WHERE consumed_at IS NULL
+          AND summary_status = 'done'
+          AND novelty_score IS NOT NULL
+          AND ${allFilter.clause}
+        GROUP BY novelty_score`)
+        .all(...allFilter.values);
+    const noveltyDistribution = { low: 0, mid: 0, high: 0 };
+    for (const row of distributionRows) {
+        if (row.score <= 1)
+            noveltyDistribution.low += row.count;
+        else if (row.score === 2)
+            noveltyDistribution.mid += row.count;
+        else if (row.score >= 3)
+            noveltyDistribution.high += row.count;
+    }
+    const vipMailUnreadCount = countVipUnreadMail(db, vipSenders);
+    const calendarFilter = sourceMatchClause(["calendar"]);
+    const calendarRow = db
+        .prepare(`SELECT COUNT(*) AS count
+         FROM observations
+        WHERE consumed_at IS NULL
+          AND ${calendarFilter.clause}`)
+        .get(...calendarFilter.values);
+    const calendarHas24hChange = calendarRow.count > 0;
+    const calendarHasConflict = detectCalendarConflict(db, now, calendarHorizonMs);
+    const agentPlanOverdueCount = countOverdueAgentPlanRows(options.todayMd ?? null, now, options.agentTimezone);
+    const horizon = new Date(now.getTime() + scheduleHorizonHours * 60 * 60 * 1000);
+    const scheduleRow = db
+        .prepare(`SELECT COUNT(*) AS count
+         FROM agent_schedule
+        WHERE status = 'pending'
+          AND scheduled_for >= ?
+          AND scheduled_for < ?`)
+        .get(toSqliteUtc(now), toSqliteUtc(horizon));
+    const hoursSinceLastStage3Run = computeHoursSinceLastStage3(db, now);
+    return {
+        pendingObsCount: pending.count,
+        maxNoveltyScore: noveltyMaxRow.max_score,
+        noveltyDistribution,
+        vipMailUnreadCount,
+        calendarHas24hChange,
+        calendarHasConflict,
+        agentPlanOverdueCount,
+        scheduleApproachingCount: scheduleRow.count,
+        hoursSinceLastStage3Run,
+    };
+}
+function countVipUnreadMail(db, vipSenders) {
+    if (vipSenders.length === 0)
+        return 0;
+    // Primary path (delegated / native / direct-with-pre-pass):
+    // unread VIP mail rides on `observations` with source prefixes
+    // `gmail:%` / `outlook_mail:%` (pre-pass) or `mail:%` (direct
+    // aggregate; only carries lifecycle metadata). The pre-pass payload
+    // is normalized at the `/api/observations` POST chokepoint to surface
+    // `is_read=0` + `from_email=<lowercased>` so this query can read a
+    // single canonical shape regardless of provider. We treat a row as
+    // VIP-unread when EITHER:
+    //   (a) the normalized `is_read=0` + `from_email` keys are present
+    //       and match, OR
+    //   (b) `is_read` is absent (pre-normalization payload or non-mail
+    //       lifecycle row) but `payload.raw.from` is a substring match
+    //       for one of the VIP addresses — captures the legacy case
+    //       where the partial doesn't emit the normalized keys.
+    const mailFilter = sourceMatchClause(["mail"]);
+    const senderPlaceholders = vipSenders.map(() => "?").join(",");
+    const observationsRow = db
+        .prepare(`SELECT COUNT(*) AS count
+         FROM observations
+        WHERE consumed_at IS NULL
+          AND ${mailFilter.clause}
+          AND COALESCE(json_extract(payload, '$.is_read'), 0) = 0
+          AND LOWER(
+                COALESCE(
+                  json_extract(payload, '$.from_email'),
+                  json_extract(payload, '$.raw.from'),
+                  json_extract(payload, '$.from'),
+                  ''
+                )
+              ) IN (${senderPlaceholders})`)
+        .get(...mailFilter.values, ...vipSenders);
+    let observationsCount = observationsRow.count;
+    // Substring fallback for `payload.raw.from` shapes like
+    // "Foo Bar <foo@bar.com>" — the IN-match above only catches exact
+    // address fields. Defensive cap (50 rows) keeps the per-tick cost
+    // bounded; tens of unread VIP mails in one window is already a
+    // hard-escalate signal regardless of exact count.
+    if (observationsCount === 0) {
+        const candidateRows = db
+            .prepare(`SELECT json_extract(payload, '$.raw.from') AS rawFrom
+           FROM observations
+          WHERE consumed_at IS NULL
+            AND ${mailFilter.clause}
+            AND COALESCE(json_extract(payload, '$.is_read'), 0) = 0
+          LIMIT 50`)
+            .all(...mailFilter.values);
+        for (const row of candidateRows) {
+            if (!row.rawFrom)
+                continue;
+            const haystack = row.rawFrom.toLowerCase();
+            if (vipSenders.some((s) => haystack.includes(s))) {
+                observationsCount += 1;
+            }
+        }
+    }
+    // Fallback path (direct mode pre-pre-pass installs whose observations
+    // are aggregate `mail:lifecycle` rows without per-message detail).
+    // The `mail_messages_index` table carries the canonical `is_read` +
+    // `from_email` columns and the MailPoller writes to it on every poll.
+    const tableExists = db
+        .prepare(`SELECT 1 AS present
+         FROM sqlite_master
+        WHERE type = 'table' AND name = 'mail_messages_index'`)
+        .get();
+    let tableCount = 0;
+    if (tableExists) {
+        const row = db
+            .prepare(`SELECT COUNT(*) AS count
+           FROM mail_messages_index
+          WHERE is_read = 0
+            AND deleted_at_utc IS NULL
+            AND LOWER(COALESCE(from_email, '')) IN (${senderPlaceholders})`)
+            .get(...vipSenders);
+        tableCount = row.count;
+    }
+    return Math.max(observationsCount, tableCount);
+}
+function detectCalendarConflict(db, now, horizonMs) {
+    // Pull pending calendar observation payloads. We tolerate the common
+    // shapes (`start`, `end`, `start.dateTime`, `end.dateTime`) and bail
+    // gracefully when neither is recognizable. A "conflict" is two events
+    // whose [start, end) ranges intersect within the lookahead window.
+    const calendarFilter = sourceMatchClause(["calendar"]);
+    const rows = db
+        .prepare(`SELECT payload
+         FROM observations
+        WHERE consumed_at IS NULL
+          AND payload IS NOT NULL
+          AND ${calendarFilter.clause}`)
+        .all(...calendarFilter.values);
+    const ranges = [];
+    const horizon = now.getTime() + horizonMs;
+    for (const row of rows) {
+        if (!row.payload)
+            continue;
+        let parsed;
+        try {
+            parsed = JSON.parse(row.payload);
+        }
+        catch {
+            continue;
+        }
+        const range = extractRange(parsed);
+        if (!range)
+            continue;
+        if (range.end <= now.getTime())
+            continue;
+        if (range.start >= horizon)
+            continue;
+        ranges.push(range);
+    }
+    if (ranges.length < 2)
+        return false;
+    ranges.sort((a, b) => a.start - b.start);
+    for (let i = 1; i < ranges.length; i++) {
+        if (ranges[i].start < ranges[i - 1].end) {
+            return true;
+        }
+    }
+    return false;
+}
+function extractRange(payload) {
+    if (!payload || typeof payload !== "object")
+        return null;
+    const record = payload;
+    const start = parseTimestamp(record["start"] ??
+        (typeof record["startTime"] === "string" ? record["startTime"] : undefined) ??
+        readNested(record, "start", "dateTime") ??
+        readNested(record, "start", "date"));
+    const end = parseTimestamp(record["end"] ??
+        (typeof record["endTime"] === "string" ? record["endTime"] : undefined) ??
+        readNested(record, "end", "dateTime") ??
+        readNested(record, "end", "date"));
+    if (start === null || end === null || end <= start)
+        return null;
+    return { start, end };
+}
+function readNested(record, key, inner) {
+    const child = record[key];
+    if (!child || typeof child !== "object")
+        return undefined;
+    return child[inner];
+}
+function parseTimestamp(value) {
+    if (typeof value !== "string" || value.length === 0)
+        return null;
+    const ts = Date.parse(value);
+    return Number.isFinite(ts) ? ts : null;
+}
+const AGENT_PLAN_HEADING = /^##\s+Agent Plan\b/i;
+const NEXT_HEADING = /^##\s+/;
+const PLAN_ROW_TIME = /^[\s>*-]*?(\d{1,2}):(\d{2})\b/;
+function countOverdueAgentPlanRows(todayMd, now, agentTimezone) {
+    if (!todayMd)
+        return 0;
+    const lines = todayMd.split(/\r?\n/);
+    let inPlan = false;
+    let count = 0;
+    const nowMin = minutesOfDayInTimezone(now, agentTimezone);
+    for (const line of lines) {
+        if (AGENT_PLAN_HEADING.test(line)) {
+            inPlan = true;
+            continue;
+        }
+        if (inPlan && NEXT_HEADING.test(line)) {
+            break;
+        }
+        if (!inPlan)
+            continue;
+        const match = PLAN_ROW_TIME.exec(line);
+        if (!match)
+            continue;
+        const hh = Number(match[1]);
+        const mm = Number(match[2]);
+        if (!Number.isFinite(hh) || !Number.isFinite(mm))
+            continue;
+        if (hh > 23 || mm > 59)
+            continue;
+        const planMin = hh * 60 + mm;
+        if (planMin < nowMin)
+            count += 1;
+    }
+    return count;
+}
+/**
+ * Convert a wall-clock instant into "minutes-of-day in the given IANA
+ * timezone". Falls back to the JS engine's local timezone when no zone
+ * is supplied or the zone string is invalid — the latter avoids the
+ * gate going dark on an operator typo.
+ */
+function minutesOfDayInTimezone(now, timezone) {
+    if (!timezone) {
+        return now.getHours() * 60 + now.getMinutes();
+    }
+    try {
+        const formatter = new Intl.DateTimeFormat("en-GB", {
+            hour: "2-digit",
+            minute: "2-digit",
+            hour12: false,
+            timeZone: timezone,
+        });
+        const parts = formatter.formatToParts(now);
+        const hh = Number(parts.find((p) => p.type === "hour")?.value ?? "0");
+        const mm = Number(parts.find((p) => p.type === "minute")?.value ?? "0");
+        if (!Number.isFinite(hh) || !Number.isFinite(mm)) {
+            return now.getHours() * 60 + now.getMinutes();
+        }
+        return hh * 60 + mm;
+    }
+    catch {
+        return now.getHours() * 60 + now.getMinutes();
+    }
+}
+function computeHoursSinceLastStage3(db, now) {
+    // Prefer the gate-emitted row (`activity_scan.gate` with
+    // stage_reached='stage3') — that matches the design doc's "since the
+    // last Stage 3 run" semantics. Fall back to the legacy
+    // `routine.activity_scan` action-type for installs deployed before
+    // the gate was wired. (The `stage3_shadow` marker was removed when
+    // the gateMode enum collapsed in HOURLY_CHECK_GATE_REDESIGN_PLAN.md
+    // Phase 4 — only the canonical `stage3` is ever written now.)
+    // The `hourly_check.*` legacy action types are pre-v0.1.11 rename rows —
+    // keep them in the union so the heartbeat window doesn't falsely report
+    // "no recent Stage 3" on the first post-upgrade ticks. Safe to drop once
+    // the heartbeat lookback (≤48 h) has fully aged past an upgrade.
+    const gateRow = db
+        .prepare(`SELECT started_at
+         FROM agent_actions
+        WHERE action_type IN ('activity_scan.gate', 'hourly_check.gate')
+          AND json_extract(detail, '$.stage_reached') = 'stage3'
+        ORDER BY started_at DESC
+        LIMIT 1`)
+        .get();
+    let lastStarted = gateRow?.started_at ?? null;
+    if (!lastStarted) {
+        const fallbackRow = db
+            .prepare(`SELECT started_at
+           FROM agent_actions
+          WHERE action_type IN ('routine.activity_scan', 'routine.hourly_check')
+            AND result IN ('success', 'partial', 'failed')
+          ORDER BY started_at DESC
+          LIMIT 1`)
+            .get();
+        lastStarted = fallbackRow?.started_at ?? null;
+    }
+    if (!lastStarted)
+        return Number.POSITIVE_INFINITY;
+    const lastUtc = parseSqliteUtc(lastStarted);
+    if (lastUtc === null)
+        return Number.POSITIVE_INFINITY;
+    const diffMs = now.getTime() - lastUtc;
+    if (diffMs <= 0)
+        return 0;
+    return diffMs / (60 * 60 * 1000);
+}
+function toSqliteUtc(date) {
+    // "YYYY-MM-DD HH:MM:SS" — matches CURRENT_TIMESTAMP / datetime('now').
+    return date.toISOString().replace("T", " ").slice(0, 19);
+}
+function parseSqliteUtc(value) {
+    // Tolerate both "YYYY-MM-DD HH:MM:SS" and ISO 8601.
+    const iso = value.includes("T") ? value : value.replace(" ", "T") + "Z";
+    const ts = Date.parse(iso);
+    return Number.isFinite(ts) ? ts : null;
+}

package/dist/db/agents-store.d.ts

@@ -1,5 +1,6 @@
 import type Database from "better-sqlite3";
 import type { AgentKind, ScheduleKind, StopWarning } from "@aitne/shared";
+import { type RuntimeWindowOverride } from "../core/agents/activity-scan-cadence.js";
 /**
  * Agents store — durable identity layer for the Agent Definitions feature
  * (AGENT_DEFINITIONS_DESIGN.md §5.1). One `agents` row per built-in routine
@@ -37,6 +38,13 @@ export interface AgentMetadata {
     last_error?: string;
     /** Built-in field-level edits that must survive `npm i -g` (§6.4.1). */
     override_snapshot?: Record<string, unknown>;
+    /**
+     * Runtime-window cadence overrides for `activity-scan` (interval / active
+     * hours / observation threshold) — AGENTS_HUB_REDESIGN_PLAN.md §2. Written
+     * by `PATCH /api/agents/:slug` (`schedule_window`), preserved by the loader
+     * like `override_snapshot`, resolved by `core/agents/activity-scan-cadence.ts`.
+     */
+    runtime_window?: Record<string, unknown>;
     [key: string]: unknown;
 }
 /** Raw row as stored in SQLite (snake_case, JSON columns unparsed). */
@@ -170,6 +178,26 @@ export declare function deleteAgent(db: Database.Database, slug: string): boolea
  * or carries no snapshot, so callers can treat the result uniformly.
  */
 export declare function getOverrideSnapshot(db: Database.Database, slug: string): Record<string, unknown>;
+/**
+ * Read just the `enabled` flag for a slug, with a caller-supplied fallback for
+ * a missing row (pass the registry's `defaultEnabled` for built-ins). Cheap
+ * single-column read for fire-time / catch-up gates outside the scheduler's
+ * cached `isAgentEnabledForFiring` path.
+ */
+export declare function getAgentEnabled(db: Database.Database, slug: string, fallback: boolean): boolean;
+/**
+ * Read the sanitized runtime-window override (`metadata_json.runtime_window`)
+ * for a slug. Returns `{}` when the Agent is missing or carries no override,
+ * so callers can hand the result straight to `resolveActivityScanCadence`.
+ */
+export declare function getRuntimeWindow(db: Database.Database, slug: string): RuntimeWindowOverride;
+/**
+ * Replace the runtime-window override, preserving every other `metadata_json`
+ * key. An empty override removes the `runtime_window` key entirely (all fields
+ * back on the config fallback). Returns the updated DTO, or `null` when no row
+ * matches.
+ */
+export declare function setRuntimeWindow(db: Database.Database, slug: string, window: RuntimeWindowOverride, now?: number): AgentDTO | null;
 /**
  * Replace the override snapshot, preserving every other `metadata_json` key.
  * An empty snapshot removes the `override_snapshot` key entirely (so a fully

package/dist/db/agents-store.js

@@ -1,3 +1,4 @@
+import { parseRuntimeWindowOverride, } from "../core/agents/activity-scan-cadence.js";
 // ── JSON parsing (defensive — store is the writer, but never trust bytes) ──
 function parseTags(json) {
     try {
@@ -240,6 +241,67 @@ export function getOverrideSnapshot(db, slug) {
         return {};
     return parseMetadata(row.metadata_json).override_snapshot ?? {};
 }
+/**
+ * Read just the `enabled` flag for a slug, with a caller-supplied fallback for
+ * a missing row (pass the registry's `defaultEnabled` for built-ins). Cheap
+ * single-column read for fire-time / catch-up gates outside the scheduler's
+ * cached `isAgentEnabledForFiring` path.
+ */
+export function getAgentEnabled(db, slug, fallback) {
+    try {
+        const row = db
+            .prepare("SELECT enabled FROM agents WHERE id = ?")
+            .get(slug);
+        return row ? row.enabled === 1 : fallback;
+    }
+    catch {
+        // Defensive: a DB without the agents table (minimal test fixtures,
+        // pre-applySchema boot edge) behaves like a missing row.
+        return fallback;
+    }
+}
+/**
+ * Read the sanitized runtime-window override (`metadata_json.runtime_window`)
+ * for a slug. Returns `{}` when the Agent is missing or carries no override,
+ * so callers can hand the result straight to `resolveActivityScanCadence`.
+ */
+export function getRuntimeWindow(db, slug) {
+    try {
+        const row = db
+            .prepare("SELECT metadata_json FROM agents WHERE id = ?")
+            .get(slug);
+        if (!row)
+            return {};
+        return parseRuntimeWindowOverride(parseMetadata(row.metadata_json).runtime_window);
+    }
+    catch {
+        // Defensive: a DB without the agents table (minimal test fixtures,
+        // pre-applySchema boot edge) behaves like a missing row.
+        return {};
+    }
+}
+/**
+ * Replace the runtime-window override, preserving every other `metadata_json`
+ * key. An empty override removes the `runtime_window` key entirely (all fields
+ * back on the config fallback). Returns the updated DTO, or `null` when no row
+ * matches.
+ */
+export function setRuntimeWindow(db, slug, window, now = Date.now()) {
+    const row = db
+        .prepare("SELECT metadata_json FROM agents WHERE id = ?")
+        .get(slug);
+    if (!row)
+        return null;
+    const metadata = parseMetadata(row.metadata_json);
+    if (Object.keys(window).length === 0) {
+        delete metadata.runtime_window;
+    }
+    else {
+        metadata.runtime_window = window;
+    }
+    db.prepare("UPDATE agents SET metadata_json = ?, updated_at = ? WHERE id = ?").run(JSON.stringify(metadata), now, slug);
+    return getAgent(db, slug);
+}
 /**
  * Replace the override snapshot, preserving every other `metadata_json` key.
  * An empty snapshot removes the `override_snapshot` key entirely (so a fully

package/dist/db/background-task-clarifications-store.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Background-task clarifications — BACKGROUND_TASK_RUNNER_DESIGN.md §6.
+ *
+ * One row per `ask_user` round-trip. The worker writes the row when it
+ * calls `ask_user`, the runner transitions the task to `awaiting_user`,
+ * and the delivery boundary surfaces the question to the owner (active
+ * delivery turn or idle draft send). The owner replies via DM; the DM
+ * agent forwards the answer through `POST /api/background-task/:id/clarify`
+ * which calls `resolveClarification` here.
+ *
+ * Deadline enforcement: a daemon housekeeping tick sweeps
+ * `WHERE resolved = 0 AND deadline_at < now()` via
+ * `listOverdueClarifications` and transitions the parent task to
+ * `timeout` (releasing the slot). The TTL is CONFIGURABLE
+ * (`backgroundTaskClarificationTtlMinutes`) and longer than
+ * browser-task's fixed 5 min — no browser resource is held while parked.
+ *
+ * I/O-bound. Excluded from the coverage gate.
+ */
+import type Database from "better-sqlite3";
+export interface BackgroundTaskClarificationRow {
+    id: string;
+    taskId: string;
+    question: string;
+    contextSummary: string | null;
+    askedAt: number;
+    deadlineAt: number;
+    deliveredAt: number | null;
+    answer: string | null;
+    answeredAt: number | null;
+    resolved: boolean;
+}
+export interface CreateClarificationInput {
+    id: string;
+    taskId: string;
+    question: string;
+    contextSummary: string | null;
+    askedAt: number;
+    /** TTL in ms — the deadline is computed here (asked_at + ttlMs) so the
+     *  runner and the scanner cannot disagree. The caller reads
+     *  `backgroundTaskClarificationTtlMinutes` and passes ms. */
+    ttlMs: number;
+}
+export declare function createClarification(db: Database.Database, input: CreateClarificationInput): BackgroundTaskClarificationRow;
+export declare function getClarification(db: Database.Database, id: string): BackgroundTaskClarificationRow | null;
+export declare function listClarificationsForTask(db: Database.Database, taskId: string): readonly BackgroundTaskClarificationRow[];
+/** The most-recent unresolved clarification for a task — the one a
+ *  /clarify reply without an explicit id resolves against. */
+export declare function getOpenClarificationForTask(db: Database.Database, taskId: string): BackgroundTaskClarificationRow | null;
+export interface ResolveClarificationResult {
+    ok: boolean;
+    row: BackgroundTaskClarificationRow | null;
+    reason?: "not_found" | "already_resolved" | "expired";
+}
+/** CAS-resolve a clarification with the owner's answer. Refuses if
+ *  already resolved (idempotent forwarding) or past deadline (the
+ *  deadline scanner owns the timeout transition). */
+export declare function resolveClarification(db: Database.Database, input: {
+    id: string;
+    answer: string;
+    answeredAt: number;
+}): ResolveClarificationResult;
+/** Sweep target — every unresolved clarification whose deadline has
+ *  passed. The scanner transitions each parent task to `timeout`. */
+export declare function listOverdueClarifications(db: Database.Database, nowMs: number): readonly BackgroundTaskClarificationRow[];
+/** Mark a clarification resolved without an answer (deadline path). */
+export declare function expireClarification(db: Database.Database, id: string, nowMs: number): BackgroundTaskClarificationRow | null;
+export declare function markClarificationDelivered(db: Database.Database, id: string, deliveredAt: number): BackgroundTaskClarificationRow | null;
+/** A recovery-sweep clarification row enriched with the parent task's
+ *  delivery fields. The list query already INNER JOINs `background_task`
+ *  (on `state='awaiting_user'`), so these are folded in here — the sweep
+ *  needs no second `getBackgroundTask` fetch and carries no unreachable
+ *  "task missing" guard. */
+export interface UndeliveredClarificationRow extends BackgroundTaskClarificationRow {
+    taskOriginatingChannel: string | null;
+    taskTitle: string | null;
+    taskBrief: string;
+}
+/** Delivery recovery target — undelivered, still-open clarifications
+ *  whose parent task is parked, joined with that task's delivery fields. */
+export declare function listUndeliveredClarifications(db: Database.Database, nowMs: number, limit?: number): readonly UndeliveredClarificationRow[];