@aitne/daemon 0.1.10 → 0.1.11

package/dist/db/background-task-store.js

@@ -0,0 +1,380 @@
+/**
+ * Background-task row store — BACKGROUND_TASK_RUNNER_DESIGN.md §6.
+ *
+ * I/O-bound CRUD over `background_task`. The state machine is enforced
+ * at this layer via the CHECK constraint on the `state` column (closed
+ * set) plus the per-transition CAS helpers below — `markRunning`,
+ * `markAwaitingUser`, `markRunningFromParked`, `markTerminal` — each
+ * one's WHERE clause refuses an out-of-order write so a race between two
+ * writers cannot flip a row backwards.
+ *
+ * The genuinely new shape vs `browser_task` is the ARTIFACT: `report`
+ * (verbatim result — the fidelity anchor), `draft` (worker-authored
+ * summary), `notify` (the worker's disposition vs the spawn-time policy),
+ * `significance`, and `artifact_path`. `markTerminal` writes them in the
+ * same transition as the terminal state so a worker's `finish` (or the
+ * runner's fail-loud synthesis) is atomic.
+ *
+ * Pure decision logic (slot arithmetic) is reused from
+ * `services/browser-task/browser-task-slots.ts`; this module is the SQL
+ * wrapper and is excluded from the coverage gate (same posture as
+ * `browser-task-store.ts`).
+ */
+export const BACKGROUND_TASK_TERMINAL_STATES = new Set(["completed", "failed", "timeout", "cancelled"]);
+export const BACKGROUND_TASK_NON_TERMINAL_STATES = new Set(["pending", "running", "awaiting_user"]);
+const SELECT_COLUMNS = `id, brief, title, state, notification_policy,
+        significance_criteria, report, draft, notify, significance,
+        artifact_path, outcome_detail, originating_channel, correlation_id,
+        schedule_row_id, tier, max_budget_usd, backend_session_id,
+        created_at, started_at, finished_at, delivered_at`;
+/** Parse the persisted `significance_criteria` JSON. Tolerant: a malformed
+ *  or non-array value degrades to null rather than throwing, so a row hand-
+ *  written by a migration / test can never crash a read. */
+function parseSignificanceCriteria(raw) {
+    if (!raw)
+        return null;
+    try {
+        const parsed = JSON.parse(raw);
+        if (!Array.isArray(parsed))
+            return null;
+        const items = parsed.filter((x) => typeof x === "string");
+        return items.length > 0 ? items : null;
+    }
+    catch {
+        return null;
+    }
+}
+function fromDbRow(row) {
+    return {
+        id: row.id,
+        brief: row.brief,
+        title: row.title,
+        state: row.state,
+        notificationPolicy: row.notification_policy,
+        significanceCriteria: parseSignificanceCriteria(row.significance_criteria),
+        report: row.report,
+        draft: row.draft,
+        notify: row.notify === null ? null : row.notify === 1,
+        significance: row.significance,
+        artifactPath: row.artifact_path,
+        outcomeDetail: row.outcome_detail,
+        originatingChannel: row.originating_channel,
+        correlationId: row.correlation_id,
+        scheduleRowId: row.schedule_row_id,
+        tier: row.tier,
+        maxBudgetUsd: row.max_budget_usd,
+        backendSessionId: row.backend_session_id,
+        createdAt: row.created_at,
+        startedAt: row.started_at,
+        finishedAt: row.finished_at,
+        deliveredAt: row.delivered_at,
+    };
+}
+/** Insert a fresh row in state=pending. The slot manager promotes it to
+ *  `running` once a slot frees. */
+export function createBackgroundTask(db, input) {
+    const criteria = input.significanceCriteria && input.significanceCriteria.length > 0
+        ? JSON.stringify([...input.significanceCriteria])
+        : null;
+    db.prepare(`INSERT INTO background_task
+       (id, brief, title, state, notification_policy, significance_criteria,
+        report, draft, notify, significance, artifact_path,
+        outcome_detail, originating_channel, correlation_id, schedule_row_id,
+        tier, max_budget_usd, backend_session_id,
+        created_at, started_at, finished_at, delivered_at)
+     VALUES (?, ?, ?, 'pending', ?, ?,
+             NULL, NULL, NULL, NULL, NULL,
+             NULL, ?, ?, ?,
+             ?, ?, NULL,
+             ?, NULL, NULL, NULL)`).run(input.id, input.brief, input.title, input.notificationPolicy, criteria, input.originatingChannel, input.correlationId, input.scheduleRowId, input.tier, input.maxBudgetUsd, input.createdAt);
+    const row = getBackgroundTask(db, input.id);
+    if (!row) {
+        throw new Error(`createBackgroundTask: post-insert row for ${input.id} missing`);
+    }
+    return row;
+}
+/**
+ * §10.3 brief-dedup — find a still-relevant task with an IDENTICAL brief
+ * spawned inside the dedup window, so a runaway fan-out (the
+ * RESEARCH_CLUSTER_COST_FIX_PLAN class: a replayed trigger POSTing the
+ * same brief many times in minutes) collapses onto the first task instead
+ * of spawning N workers. Matches on `brief` + `tier` (the two inputs that
+ * define "the same work" — `notificationPolicy` only affects delivery, not
+ * the work done) within `sinceMs`, and excludes the FAIL terminals
+ * (`failed`/`timeout`/`cancelled`) so a prior failure is retryable rather
+ * than sticky. A `completed` duplicate inside the window IS returned — the
+ * answer already exists, re-running would just re-spend. Newest first.
+ */
+export function findRecentDuplicateBackgroundTask(db, input) {
+    const row = db
+        .prepare(`SELECT ${SELECT_COLUMNS}
+         FROM background_task
+        WHERE brief = ?
+          AND tier IS ?
+          AND created_at >= ?
+          AND state NOT IN ('failed', 'timeout', 'cancelled')
+        ORDER BY created_at DESC
+        LIMIT 1`)
+        .get(input.brief, input.tier, input.sinceMs);
+    return row ? fromDbRow(row) : null;
+}
+export function getBackgroundTask(db, id) {
+    const row = db
+        .prepare(`SELECT ${SELECT_COLUMNS} FROM background_task WHERE id = ?`)
+        .get(id);
+    return row ? fromDbRow(row) : null;
+}
+/** Shared WHERE builder for list + count so the two never diverge. */
+function buildListWhere(options) {
+    const { states, notify, finishedSinceMs } = options;
+    const where = [];
+    const params = [];
+    if (states && states.length > 0) {
+        where.push(`state IN (${states.map(() => "?").join(", ")})`);
+        params.push(...states);
+    }
+    if (notify !== undefined) {
+        where.push(`notify = ?`);
+        params.push(notify ? 1 : 0);
+    }
+    if (finishedSinceMs !== undefined) {
+        where.push(`finished_at >= ?`);
+        params.push(finishedSinceMs);
+    }
+    return {
+        clause: where.length ? `WHERE ${where.join(" AND ")}` : "",
+        params,
+    };
+}
+export function listBackgroundTasks(db, options = {}) {
+    const { limit = 50, offset = 0 } = options;
+    const { clause, params } = buildListWhere(options);
+    const sql = `SELECT ${SELECT_COLUMNS}
+                 FROM background_task
+               ${clause}
+               ORDER BY created_at DESC
+               LIMIT ? OFFSET ?`;
+    const rows = db
+        .prepare(sql)
+        .all(...params, limit, offset);
+    return rows.map(fromDbRow);
+}
+export function countBackgroundTasks(db, options = {}) {
+    const { clause, params } = buildListWhere(options);
+    const sql = `SELECT COUNT(*) AS c FROM background_task
+               ${clause}`;
+    const row = db.prepare(sql).get(...params);
+    return row?.c ?? 0;
+}
+/** Pending → running. CAS on prior state so a concurrent terminal
+ *  transition (cancel-while-pending) does not get clobbered. */
+export function markRunning(db, id, startedAt) {
+    const result = db
+        .prepare(`UPDATE background_task
+          SET state = 'running', started_at = COALESCE(started_at, ?)
+        WHERE id = ? AND state = 'pending'`)
+        .run(startedAt, id);
+    return result.changes > 0 ? getBackgroundTask(db, id) : null;
+}
+/** Running → awaiting_user. Slot stays held; resume via /clarify. */
+export function markAwaitingUser(db, id) {
+    const result = db
+        .prepare(`UPDATE background_task
+          SET state = 'awaiting_user'
+        WHERE id = ? AND state = 'running'`)
+        .run(id);
+    return result.changes > 0 ? getBackgroundTask(db, id) : null;
+}
+/** awaiting_user → running. Used by /clarify resume. */
+export function markRunningFromParked(db, id) {
+    const result = db
+        .prepare(`UPDATE background_task
+          SET state = 'running'
+        WHERE id = ? AND state = 'awaiting_user'`)
+        .run(id);
+    return result.changes > 0 ? getBackgroundTask(db, id) : null;
+}
+/** Any non-terminal state → terminal, writing the artifact atomically.
+ *  Idempotent — re-running on an already-terminal row CAS-misses and
+ *  returns null. */
+export function markTerminal(db, input) {
+    const result = db
+        .prepare(`UPDATE background_task
+          SET state = ?,
+              outcome_detail = ?,
+              report = COALESCE(?, report),
+              draft = COALESCE(?, draft),
+              notify = COALESCE(?, notify),
+              significance = COALESCE(?, significance),
+              artifact_path = COALESCE(?, artifact_path),
+              finished_at = ?
+        WHERE id = ?
+          AND state IN ('pending', 'running', 'awaiting_user')`)
+        .run(input.state, input.outcomeDetail, input.report ?? null, input.draft ?? null, input.notify === undefined ? null : input.notify ? 1 : 0, input.significance ?? null, input.artifactPath ?? null, input.finishedAt, input.id);
+    return result.changes > 0 ? getBackgroundTask(db, input.id) : null;
+}
+/** Capture the SDK session id once the first turn streams it, so a
+ *  /clarify resume can `query({resume})` the warm session. */
+export function setBackendSessionId(db, id, sessionId) {
+    db.prepare(`UPDATE background_task SET backend_session_id = ? WHERE id = ?`).run(sessionId, id);
+}
+export function markBackgroundTaskDelivered(db, id, deliveredAt) {
+    const result = db
+        .prepare(`UPDATE background_task
+          SET delivered_at = COALESCE(delivered_at, ?)
+        WHERE id = ?`)
+        .run(deliveredAt, id);
+    return result.changes > 0 ? getBackgroundTask(db, id) : null;
+}
+/** Delivery recovery target — completed rows whose worker stored a
+ *  notify=true artifact but whose DM was never sent/recorded (§10.2). */
+export function listUndeliveredBackgroundTaskReports(db, limit = 20) {
+    const rows = db
+        .prepare(`SELECT ${SELECT_COLUMNS}
+         FROM background_task
+        WHERE state = 'completed'
+          AND notify = 1
+          AND delivered_at IS NULL
+          AND draft IS NOT NULL
+        ORDER BY finished_at ASC, created_at ASC
+        LIMIT ?`)
+        .all(limit);
+    return rows.map(fromDbRow);
+}
+/** §10.5 — filed (notify=false) results, for the periodic digest +
+ *  owner pull ("did that monitor ever run?"). */
+export function listFiledBackgroundTaskResults(db, sinceMs, limit = 50) {
+    const rows = db
+        .prepare(`SELECT ${SELECT_COLUMNS}
+         FROM background_task
+        WHERE state = 'completed'
+          AND notify = 0
+          AND finished_at >= ?
+        ORDER BY finished_at DESC
+        LIMIT ?`)
+        .all(sinceMs, limit);
+    return rows.map(fromDbRow);
+}
+/**
+ * §10.2 boot re-dispatch-from-brief — reset every non-terminal row to
+ * `pending` (clearing the lost in-memory session) so the event-pipeline
+ * boot hook can re-run each one's brief through the runner. Returns the
+ * ids reset so the caller can fan out the re-dispatch.
+ *
+ * Unlike browser_task's `sweepNonTerminalRowsForBootRecovery` (which
+ * force-fails), background tasks are re-dispatchable because the brief is
+ * self-contained. `backend_session_id` is cleared since the prior SDK
+ * session is unreachable after a restart.
+ *
+ * Open clarifications belonging to the reset tasks are resolved in the
+ * SAME transaction. The pre-restart run that raised an `ask_user` is
+ * gone, so its clarification row is orphaned: a surviving `resolved = 0`
+ * row would later trip the deadline scanner (`listOverdueClarifications`
+ * → `expireForDeadline`) into transitioning the FRESH re-dispatched run
+ * to `timeout` — and because re-dispatch makes the task ACTIVE again
+ * (pending→running), that `expireForDeadline` is NOT a no-op the way it
+ * is for a terminal row. Clearing them here closes that window.
+ */
+export function resetNonTerminalForBootRedispatch(db, nowMs = Date.now()) {
+    const txn = db.transaction(() => {
+        const rows = db
+            .prepare(`SELECT id FROM background_task
+          WHERE state IN ('pending', 'running', 'awaiting_user')`)
+            .all();
+        if (rows.length === 0)
+            return [];
+        // Abandon orphaned clarifications BEFORE the state reset (so the
+        // `task_id IN (non-terminal)` subquery still matches them).
+        db.prepare(`UPDATE background_task_clarifications
+          SET resolved = 1, answered_at = COALESCE(answered_at, ?)
+        WHERE resolved = 0
+          AND task_id IN (
+            SELECT id FROM background_task
+             WHERE state IN ('pending', 'running', 'awaiting_user')
+          )`).run(nowMs);
+        db.prepare(`UPDATE background_task
+          SET state = 'pending',
+              started_at = NULL,
+              backend_session_id = NULL
+        WHERE state IN ('pending', 'running', 'awaiting_user')`).run();
+        return rows.map((r) => ({ id: r.id }));
+    });
+    return txn();
+}
+/**
+ * Phase 4 resume-across-restart (§10.2) — the non-terminal rows the boot
+ * recovery path partitions into "resume the SDK session" vs "re-dispatch
+ * from brief". Returns just the discriminators (id, state, session id) so
+ * the caller can decide without loading the full artifact.
+ */
+export function listNonTerminalBackgroundTasks(db) {
+    return db
+        .prepare(`SELECT id, state, backend_session_id
+         FROM background_task
+        WHERE state IN ('pending', 'running', 'awaiting_user')
+        ORDER BY created_at ASC`)
+        .all()
+        .map((r) => ({ id: r.id, state: r.state, backendSessionId: r.backend_session_id }));
+}
+/**
+ * Phase 4 resume-across-restart (§10.2) — reset ONE non-terminal row back
+ * to `pending` for re-dispatch-from-brief, clearing its (now unreachable)
+ * SDK session id and resolving its orphaned open clarifications in the same
+ * transaction (same rationale as the bulk
+ * `resetNonTerminalForBootRedispatch`: a surviving `resolved = 0` row would
+ * trip the deadline scanner into timing out the FRESH re-dispatched run).
+ * Used by the boot path for the rows it re-dispatches and by the runner's
+ * resume-failure fallback. Returns the row id when it was non-terminal,
+ * else null (idempotent on an already-terminal / missing row).
+ */
+export function resetSingleForBootRedispatch(db, id, nowMs = Date.now()) {
+    const txn = db.transaction(() => {
+        const row = db
+            .prepare(`SELECT state FROM background_task WHERE id = ?`)
+            .get(id);
+        if (!row || !BACKGROUND_TASK_NON_TERMINAL_STATES.has(row.state)) {
+            return null;
+        }
+        db.prepare(`UPDATE background_task_clarifications
+          SET resolved = 1, answered_at = COALESCE(answered_at, ?)
+        WHERE resolved = 0 AND task_id = ?`).run(nowMs, id);
+        db.prepare(`UPDATE background_task
+          SET state = 'pending',
+              started_at = NULL,
+              backend_session_id = NULL
+        WHERE id = ?`).run(id);
+        return id;
+    });
+    return txn();
+}
+/**
+ * Fold a just-answered clarification into the task's brief so a COLD
+ * re-dispatch (when the warm SDK session can't be resumed across a restart,
+ * §10.2) still carries the owner's answer and doesn't re-ask the same
+ * question. The worker only ever sees the brief, so appending the resolved
+ * Q&A is the only way to thread the answer into a fresh run. Idempotency is
+ * not required — this runs at most once per clarification per re-dispatch,
+ * and the clarify route has already CAS-resolved the row.
+ */
+export function appendResolvedClarificationToBrief(db, id, question, answer) {
+    const block = `\n\n<resolved_clarification>\n`
+        + (question ? `You previously asked: ${question}\n` : "")
+        + `The owner answered: ${answer}\n`
+        + `</resolved_clarification>`;
+    db.prepare(`UPDATE background_task SET brief = brief || ? WHERE id = ?`).run(block, id);
+}
+/**
+ * Retention prune for terminal rows older than `cutoffMs`. Children in
+ * `background_task_clarifications` go with the parent via ON DELETE
+ * CASCADE. Non-terminal rows are never deleted (the boot re-dispatch
+ * sweep owns them). `finished_at` is the lifetime anchor with a
+ * `created_at` fallback for the rare unset-finished_at terminal.
+ */
+export function deleteTerminalBackgroundTasksOlderThan(db, cutoffMs) {
+    const result = db
+        .prepare(`DELETE FROM background_task
+        WHERE state IN ('completed', 'failed', 'timeout', 'cancelled')
+          AND COALESCE(finished_at, created_at) < ?`)
+        .run(cutoffMs);
+    return result.changes;
+}

package/dist/db/browser-history-store.d.ts

@@ -184,16 +184,49 @@ export declare function renameResearchCluster(db: Database.Database, slug: strin
  */
 export declare function bumpClusterAgentSummaryRevision(db: Database.Database, slug: string): number;
 /**
- * Clusters whose `last_activity_at` is newer than the row's most recent
- * cluster_update session — i.e. the agent has new visits to journal.
- * Surfaces only `active` rows: muted / concluded / dormant clusters do
- * not get nightly journal appends. Capped by `limit` so a backlog never
- * floods the schedule fan-out.
+ * Clusters eligible for a `routine.research_cluster_update` enqueue this
+ * agent-day: `active` rows with meaningful activity inside the lookback
+ * window that have NOT already been enqueued for `todayAgentDay`
+ * (`journal_update_enqueued_on` is the stamp `claimClusterJournalEnqueue`
+ * writes at fan-out time; ISO 'YYYY-MM-DD' strings compare lexically =
+ * chronologically, so `< todayAgentDay` means "last enqueued on an
+ * earlier agent day"). This filter is the efficiency gate for SEQUENTIAL
+ * replays (a wake catch-up / morning self-heal re-running after a prior
+ * fire completed); the atomic per-row claim in `claimClusterJournalEnqueue`
+ * is what additionally protects against two CONCURRENTLY in-flight
+ * callbacks — RESEARCH_CLUSTER_COST_FIX_PLAN.md RC1. Muted / concluded / dormant clusters do not get nightly journal
+ * appends. Capped by `limit` so a backlog never floods the fan-out.
  */
-export declare function listClustersNeedingUpdate(db: Database.Database, lookbackMs: number, nowMs?: number, limit?: number): Array<{
+export declare function listClustersNeedingUpdate(db: Database.Database, lookbackMs: number, nowMs: number, limit: number, todayAgentDay: string): Array<{
     slug: string;
     displayName: string;
 }>;
+/**
+ * Atomically CLAIM `agentDay`'s `routine.research_cluster_update` enqueue
+ * slot for this cluster. Returns `true` iff THIS call wrote the stamp —
+ * the prior value was NULL or an earlier agent-day; `false` if the slot
+ * was already claimed for `agentDay` (or a newer one) or the slug is
+ * unknown. Called BEFORE `eventBus.put` (claim-before-enqueue — same
+ * rationale as `fireDecision`'s `stampClusterDmFields` call in
+ * browser-history-poller.ts).
+ *
+ * The conditional UPDATE is a single atomic SQLite statement, so two
+ * day-boundary callbacks racing on the same cluster cannot both claim
+ * it: the 04:00 cron fires `onDayBoundary` fire-and-forget (scheduler.ts)
+ * and can overlap a wake catch-up, and each fan-out iterates its own
+ * `listClustersNeedingUpdate` snapshot — so the per-row claim, not the
+ * snapshot filter, is what guarantees exactly one enqueue per cluster per
+ * agent day. Exactly one caller sees `changes === 1` and enqueues; the
+ * loser skips. The `< ?` guard doubles as monotonicity — a stale replay
+ * carrying an older agent-day matches no row and cannot regress a newer
+ * stamp (ISO 'YYYY-MM-DD' strings compare lexically = chronologically).
+ *
+ * Failure semantics are intentional: the claim persists even if the
+ * subsequent `eventBus.put` throws, so a cluster whose enqueue failed
+ * retries on the NEXT agent day — bounded, no same-day loop (the F6
+ * backfill covers the missed day).
+ */
+export declare function claimClusterJournalEnqueue(db: Database.Database, slug: string, agentDay: string): boolean;
 export declare const OFFER_DEFAULT_TTL_MS: number;
 export interface PendingOfferInput {
     slug: string;

package/dist/db/browser-history-store.js

@@ -498,22 +498,66 @@ export function bumpClusterAgentSummaryRevision(db, slug) {
     return row.rev;
 }
 /**
- * Clusters whose `last_activity_at` is newer than the row's most recent
- * cluster_update session — i.e. the agent has new visits to journal.
- * Surfaces only `active` rows: muted / concluded / dormant clusters do
- * not get nightly journal appends. Capped by `limit` so a backlog never
- * floods the schedule fan-out.
+ * Clusters eligible for a `routine.research_cluster_update` enqueue this
+ * agent-day: `active` rows with meaningful activity inside the lookback
+ * window that have NOT already been enqueued for `todayAgentDay`
+ * (`journal_update_enqueued_on` is the stamp `claimClusterJournalEnqueue`
+ * writes at fan-out time; ISO 'YYYY-MM-DD' strings compare lexically =
+ * chronologically, so `< todayAgentDay` means "last enqueued on an
+ * earlier agent day"). This filter is the efficiency gate for SEQUENTIAL
+ * replays (a wake catch-up / morning self-heal re-running after a prior
+ * fire completed); the atomic per-row claim in `claimClusterJournalEnqueue`
+ * is what additionally protects against two CONCURRENTLY in-flight
+ * callbacks — RESEARCH_CLUSTER_COST_FIX_PLAN.md RC1. Muted / concluded / dormant clusters do not get nightly journal
+ * appends. Capped by `limit` so a backlog never floods the fan-out.
  */
-export function listClustersNeedingUpdate(db, lookbackMs, nowMs = Date.now(), limit = 25) {
+export function listClustersNeedingUpdate(db, lookbackMs, nowMs, limit, todayAgentDay) {
     const since = nowMs - lookbackMs;
     return db
         .prepare(`SELECT slug, display_name AS displayName
        FROM browser_research_clusters
        WHERE status = 'active'
          AND last_activity_at >= ?
+         AND (journal_update_enqueued_on IS NULL
+              OR journal_update_enqueued_on < ?)
        ORDER BY last_activity_at DESC
        LIMIT ?`)
-        .all(since, limit);
+        .all(since, todayAgentDay, limit);
+}
+/**
+ * Atomically CLAIM `agentDay`'s `routine.research_cluster_update` enqueue
+ * slot for this cluster. Returns `true` iff THIS call wrote the stamp —
+ * the prior value was NULL or an earlier agent-day; `false` if the slot
+ * was already claimed for `agentDay` (or a newer one) or the slug is
+ * unknown. Called BEFORE `eventBus.put` (claim-before-enqueue — same
+ * rationale as `fireDecision`'s `stampClusterDmFields` call in
+ * browser-history-poller.ts).
+ *
+ * The conditional UPDATE is a single atomic SQLite statement, so two
+ * day-boundary callbacks racing on the same cluster cannot both claim
+ * it: the 04:00 cron fires `onDayBoundary` fire-and-forget (scheduler.ts)
+ * and can overlap a wake catch-up, and each fan-out iterates its own
+ * `listClustersNeedingUpdate` snapshot — so the per-row claim, not the
+ * snapshot filter, is what guarantees exactly one enqueue per cluster per
+ * agent day. Exactly one caller sees `changes === 1` and enqueues; the
+ * loser skips. The `< ?` guard doubles as monotonicity — a stale replay
+ * carrying an older agent-day matches no row and cannot regress a newer
+ * stamp (ISO 'YYYY-MM-DD' strings compare lexically = chronologically).
+ *
+ * Failure semantics are intentional: the claim persists even if the
+ * subsequent `eventBus.put` throws, so a cluster whose enqueue failed
+ * retries on the NEXT agent day — bounded, no same-day loop (the F6
+ * backfill covers the missed day).
+ */
+export function claimClusterJournalEnqueue(db, slug, agentDay) {
+    const info = db
+        .prepare(`UPDATE browser_research_clusters
+          SET journal_update_enqueued_on = ?
+        WHERE slug = ?
+          AND (journal_update_enqueued_on IS NULL
+               OR journal_update_enqueued_on < ?)`)
+        .run(agentDay, slug, agentDay);
+    return info.changes > 0;
 }
 // ── browser_pending_offers — materialised view of open offer state ──
 export const OFFER_DEFAULT_TTL_MS = 14 * 24 * 60 * 60 * 1000;

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

@@ -26,6 +26,7 @@ export interface BrowserTaskClarificationRow {
     screenshotKey: string | null;
     askedAt: number;
     deadlineAt: number;
+    deliveredAt: number | null;
     answer: string | null;
     answeredAt: number | null;
     resolved: boolean;
@@ -65,3 +66,14 @@ export declare function listOverdueClarifications(db: Database.Database, nowMs:
  *  Differs from `resolveClarification` in that it skips the deadline
  *  check — the scanner is calling this BECAUSE the deadline passed. */
 export declare function expireClarification(db: Database.Database, id: string, nowMs: number): BrowserTaskClarificationRow | null;
+export declare function markClarificationDelivered(db: Database.Database, id: string, deliveredAt: number): BrowserTaskClarificationRow | null;
+/** A recovery-sweep clarification row enriched with the parent task's
+ *  delivery fields. The list query already INNER JOINs `browser_task`
+ *  (on `state='awaiting_user'`), so the originating channel + description
+ *  are folded in here — the sweep needs no second `getBrowserTask` fetch
+ *  and carries no unreachable "task missing" guard. */
+export interface UndeliveredClarificationRow extends BrowserTaskClarificationRow {
+    taskOriginatingChannel: string | null;
+    taskDescription: string;
+}
+export declare function listUndeliveredClarifications(db: Database.Database, nowMs: number, limit?: number): readonly UndeliveredClarificationRow[];

package/dist/db/browser-task-clarifications-store.js

@@ -26,6 +26,7 @@ function fromDbRow(row) {
         screenshotKey: row.screenshot_key,
         askedAt: row.asked_at,
         deadlineAt: row.deadline_at,
+        deliveredAt: row.delivered_at,
         answer: row.answer,
         answeredAt: row.answered_at,
         resolved: row.resolved === 1,
@@ -38,8 +39,8 @@ export function createClarification(db, input) {
     const deadline = input.askedAt + CLARIFICATION_TTL_MS;
     db.prepare(`INSERT INTO browser_task_clarifications
        (id, task_id, question, context_summary, screenshot_key,
-        asked_at, deadline_at, answer, answered_at, resolved)
-     VALUES (?, ?, ?, ?, ?, ?, ?, NULL, NULL, 0)`).run(input.id, input.taskId, input.question, input.contextSummary, input.screenshotKey, input.askedAt, deadline);
+        asked_at, deadline_at, delivered_at, answer, answered_at, resolved)
+     VALUES (?, ?, ?, ?, ?, ?, ?, NULL, NULL, NULL, 0)`).run(input.id, input.taskId, input.question, input.contextSummary, input.screenshotKey, input.askedAt, deadline);
     const row = getClarification(db, input.id);
     if (!row) {
         throw new Error(`createClarification: post-insert row for ${input.id} missing`);
@@ -49,7 +50,7 @@ export function createClarification(db, input) {
 export function getClarification(db, id) {
     const row = db
         .prepare(`SELECT id, task_id, question, context_summary, screenshot_key,
-              asked_at, deadline_at, answer, answered_at, resolved
+              asked_at, deadline_at, delivered_at, answer, answered_at, resolved
          FROM browser_task_clarifications
         WHERE id = ?`)
         .get(id);
@@ -58,7 +59,7 @@ export function getClarification(db, id) {
 export function listClarificationsForTask(db, taskId) {
     const rows = db
         .prepare(`SELECT id, task_id, question, context_summary, screenshot_key,
-              asked_at, deadline_at, answer, answered_at, resolved
+              asked_at, deadline_at, delivered_at, answer, answered_at, resolved
          FROM browser_task_clarifications
         WHERE task_id = ?
         ORDER BY asked_at ASC`)
@@ -96,7 +97,7 @@ export function resolveClarification(db, input) {
 export function listOverdueClarifications(db, nowMs) {
     const rows = db
         .prepare(`SELECT id, task_id, question, context_summary, screenshot_key,
-              asked_at, deadline_at, answer, answered_at, resolved
+              asked_at, deadline_at, delivered_at, answer, answered_at, resolved
          FROM browser_task_clarifications
         WHERE resolved = 0 AND deadline_at < ?
         ORDER BY deadline_at ASC`)
@@ -116,3 +117,32 @@ export function expireClarification(db, id, nowMs) {
         return null;
     return getClarification(db, id);
 }
+export function markClarificationDelivered(db, id, deliveredAt) {
+    const result = db
+        .prepare(`UPDATE browser_task_clarifications
+          SET delivered_at = COALESCE(delivered_at, ?)
+        WHERE id = ?`)
+        .run(deliveredAt, id);
+    return result.changes > 0 ? getClarification(db, id) : null;
+}
+export function listUndeliveredClarifications(db, nowMs, limit = 20) {
+    const rows = db
+        .prepare(`SELECT c.id, c.task_id, c.question, c.context_summary, c.screenshot_key,
+              c.asked_at, c.deadline_at, c.delivered_at,
+              c.answer, c.answered_at, c.resolved,
+              t.originating_channel, t.description
+         FROM browser_task_clarifications c
+         JOIN browser_task t ON t.id = c.task_id
+        WHERE c.resolved = 0
+          AND c.delivered_at IS NULL
+          AND c.deadline_at >= ?
+          AND t.state = 'awaiting_user'
+        ORDER BY c.asked_at ASC
+        LIMIT ?`)
+        .all(nowMs, limit);
+    return rows.map((row) => ({
+        ...fromDbRow(row),
+        taskOriginatingChannel: row.originating_channel,
+        taskDescription: row.description,
+    }));
+}

package/dist/db/browser-task-store.d.ts

@@ -34,6 +34,7 @@ export interface BrowserTaskRow {
     createdAt: number;
     startedAt: number | null;
     finishedAt: number | null;
+    deliveredAt: number | null;
 }
 export interface CreateBrowserTaskInput {
     id: string;
@@ -79,6 +80,8 @@ export interface TerminalTransitionInput {
 /** Any non-terminal state → terminal. Idempotent — re-running on an
  *  already-terminal row CAS-misses and returns null. */
 export declare function markTerminal(db: Database.Database, input: TerminalTransitionInput): BrowserTaskRow | null;
+export declare function markBrowserTaskDelivered(db: Database.Database, id: string, deliveredAt: number): BrowserTaskRow | null;
+export declare function listUndeliveredBrowserTaskReports(db: Database.Database, limit?: number): readonly BrowserTaskRow[];
 /** Increment the per-task CDP-blocked counter. Atomic. */
 export declare function incrementBlockedRequests(db: Database.Database, id: string, by: number): void;
 /** Increment the per-task cumulative untrusted-content counter. */