@aitne/daemon 0.1.7 → 0.1.9

package/dist/db/browser-task-action-log-store.js

@@ -0,0 +1,74 @@
+/**
+ * Browser-task action log — BROWSER_TASK_REDESIGN_PLAN.md §6.6.
+ *
+ * One row per tool call (and per defence-in-depth event: popup close,
+ * dialog dismiss, file-chooser cancel, download block — emitted with
+ * tool_name='browser_internal' per §14.3 / §14.4).
+ *
+ * I/O-bound — the dashboard reads via paginated list, the runner only
+ * appends. Excluded from the coverage gate per the same `db/*` exclusion
+ * rationale as the B-4 stores.
+ */
+function fromDbRow(row) {
+    let args;
+    try {
+        args = JSON.parse(row.args_json);
+    }
+    catch {
+        args = row.args_json;
+    }
+    return {
+        id: row.id,
+        taskId: row.task_id,
+        stepIndex: row.step_index,
+        toolName: row.tool_name,
+        args,
+        outcome: row.outcome,
+        blockedReason: row.blocked_reason,
+        screenshotKey: row.screenshot_key,
+        durationMs: row.duration_ms,
+        at: row.at,
+    };
+}
+export function insertBrowserTaskActionLog(db, input) {
+    const result = db
+        .prepare(`INSERT INTO browser_task_action_log
+         (task_id, step_index, tool_name, args_json,
+          outcome, blocked_reason, screenshot_key,
+          duration_ms, at)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`)
+        .run(input.taskId, input.stepIndex, input.toolName, JSON.stringify(input.args ?? null), input.outcome, input.blockedReason ?? null, input.screenshotKey ?? null, input.durationMs, input.at);
+    const id = Number(result.lastInsertRowid);
+    const row = db
+        .prepare(`SELECT id, task_id, step_index, tool_name, args_json,
+              outcome, blocked_reason, screenshot_key,
+              duration_ms, at
+         FROM browser_task_action_log
+        WHERE id = ?`)
+        .get(id);
+    if (!row) {
+        throw new Error(`insertBrowserTaskActionLog: post-insert row ${id} missing`);
+    }
+    return fromDbRow(row);
+}
+/** Highest existing step_index for this task, or -1 if none yet. The
+ *  runner increments from here to assign the next step's index. */
+export function nextStepIndexFor(db, taskId) {
+    const row = db
+        .prepare(`SELECT MAX(step_index) AS m
+         FROM browser_task_action_log
+        WHERE task_id = ?`)
+        .get(taskId);
+    return (row?.m ?? -1) + 1;
+}
+export function listBrowserTaskActionLog(db, taskId) {
+    const rows = db
+        .prepare(`SELECT id, task_id, step_index, tool_name, args_json,
+              outcome, blocked_reason, screenshot_key,
+              duration_ms, at
+         FROM browser_task_action_log
+        WHERE task_id = ?
+        ORDER BY step_index ASC`)
+        .all(taskId);
+    return rows.map(fromDbRow);
+}

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

@@ -0,0 +1,67 @@
+/**
+ * Browser-task clarifications — BROWSER_TASK_REDESIGN_PLAN.md §6.7.
+ *
+ * One row per `ask_user` round-trip. The runner writes the row when the
+ * sub-agent calls `ask_user`, transitions the task to `awaiting_user`,
+ * and DMs the question + screenshot. The user replies via DM; the
+ * adapter forwards the reply through `POST /api/browser-task/:id/clarify`
+ * which calls `resolveClarification` here.
+ *
+ * Deadline enforcement: a single 30 s daemon tick scans
+ * `WHERE resolved = 0 AND deadline_at < now()` via
+ * `listOverdueClarifications` and the deadline scanner transitions the
+ * parent task to `abandoned` (releasing the slot + DMing the user once).
+ *
+ * I/O-bound. Excluded from the coverage gate.
+ */
+import type Database from "better-sqlite3";
+/** §5 ask_user — 5-minute clarification TTL. The runner reads this
+ *  constant when writing `deadline_at = asked_at + CLARIFICATION_TTL_MS`. */
+export declare const CLARIFICATION_TTL_MS: number;
+export interface BrowserTaskClarificationRow {
+    id: string;
+    taskId: string;
+    question: string;
+    contextSummary: string | null;
+    screenshotKey: string | null;
+    askedAt: number;
+    deadlineAt: number;
+    answer: string | null;
+    answeredAt: number | null;
+    resolved: boolean;
+}
+export interface CreateClarificationInput {
+    id: string;
+    taskId: string;
+    question: string;
+    contextSummary: string | null;
+    screenshotKey: string | null;
+    askedAt: number;
+}
+/** Insert a fresh clarification row. The deadline is computed at this
+ *  layer (asked_at + CLARIFICATION_TTL_MS) so the runner and the
+ *  scanner cannot disagree. */
+export declare function createClarification(db: Database.Database, input: CreateClarificationInput): BrowserTaskClarificationRow;
+export declare function getClarification(db: Database.Database, id: string): BrowserTaskClarificationRow | null;
+export declare function listClarificationsForTask(db: Database.Database, taskId: string): readonly BrowserTaskClarificationRow[];
+export interface ResolveClarificationResult {
+    ok: boolean;
+    row: BrowserTaskClarificationRow | null;
+    reason?: "not_found" | "already_resolved" | "expired";
+}
+/** CAS-resolve a clarification with the user's answer. Refuses if
+ *  already resolved (idempotent DM forwarding) or past deadline (the
+ *  deadline scanner owns the abandoned 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 deadline scanner walks the list and transitions each
+ *  parent task to `abandoned`. */
+export declare function listOverdueClarifications(db: Database.Database, nowMs: number): readonly BrowserTaskClarificationRow[];
+/** Mark a clarification resolved without an answer (deadline path).
+ *  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;

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

@@ -0,0 +1,118 @@
+/**
+ * Browser-task clarifications — BROWSER_TASK_REDESIGN_PLAN.md §6.7.
+ *
+ * One row per `ask_user` round-trip. The runner writes the row when the
+ * sub-agent calls `ask_user`, transitions the task to `awaiting_user`,
+ * and DMs the question + screenshot. The user replies via DM; the
+ * adapter forwards the reply through `POST /api/browser-task/:id/clarify`
+ * which calls `resolveClarification` here.
+ *
+ * Deadline enforcement: a single 30 s daemon tick scans
+ * `WHERE resolved = 0 AND deadline_at < now()` via
+ * `listOverdueClarifications` and the deadline scanner transitions the
+ * parent task to `abandoned` (releasing the slot + DMing the user once).
+ *
+ * I/O-bound. Excluded from the coverage gate.
+ */
+/** §5 ask_user — 5-minute clarification TTL. The runner reads this
+ *  constant when writing `deadline_at = asked_at + CLARIFICATION_TTL_MS`. */
+export const CLARIFICATION_TTL_MS = 5 * 60 * 1000;
+function fromDbRow(row) {
+    return {
+        id: row.id,
+        taskId: row.task_id,
+        question: row.question,
+        contextSummary: row.context_summary,
+        screenshotKey: row.screenshot_key,
+        askedAt: row.asked_at,
+        deadlineAt: row.deadline_at,
+        answer: row.answer,
+        answeredAt: row.answered_at,
+        resolved: row.resolved === 1,
+    };
+}
+/** Insert a fresh clarification row. The deadline is computed at this
+ *  layer (asked_at + CLARIFICATION_TTL_MS) so the runner and the
+ *  scanner cannot disagree. */
+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);
+    const row = getClarification(db, input.id);
+    if (!row) {
+        throw new Error(`createClarification: post-insert row for ${input.id} missing`);
+    }
+    return row;
+}
+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
+         FROM browser_task_clarifications
+        WHERE id = ?`)
+        .get(id);
+    return row ? fromDbRow(row) : null;
+}
+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
+         FROM browser_task_clarifications
+        WHERE task_id = ?
+        ORDER BY asked_at ASC`)
+        .all(taskId);
+    return rows.map(fromDbRow);
+}
+/** CAS-resolve a clarification with the user's answer. Refuses if
+ *  already resolved (idempotent DM forwarding) or past deadline (the
+ *  deadline scanner owns the abandoned transition). */
+export function resolveClarification(db, input) {
+    const existing = getClarification(db, input.id);
+    if (!existing)
+        return { ok: false, row: null, reason: "not_found" };
+    if (existing.resolved) {
+        return { ok: false, row: existing, reason: "already_resolved" };
+    }
+    if (input.answeredAt > existing.deadlineAt) {
+        return { ok: false, row: existing, reason: "expired" };
+    }
+    const result = db
+        .prepare(`UPDATE browser_task_clarifications
+          SET answer = ?, answered_at = ?, resolved = 1
+        WHERE id = ? AND resolved = 0`)
+        .run(input.answer, input.answeredAt, input.id);
+    if (result.changes === 0) {
+        const after = getClarification(db, input.id);
+        return { ok: false, row: after, reason: "already_resolved" };
+    }
+    const row = getClarification(db, input.id);
+    return { ok: true, row };
+}
+/** Sweep target — every unresolved clarification whose deadline has
+ *  passed. The deadline scanner walks the list and transitions each
+ *  parent task to `abandoned`. */
+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
+         FROM browser_task_clarifications
+        WHERE resolved = 0 AND deadline_at < ?
+        ORDER BY deadline_at ASC`)
+        .all(nowMs);
+    return rows.map(fromDbRow);
+}
+/** Mark a clarification resolved without an answer (deadline path).
+ *  Differs from `resolveClarification` in that it skips the deadline
+ *  check — the scanner is calling this BECAUSE the deadline passed. */
+export function expireClarification(db, id, nowMs) {
+    const result = db
+        .prepare(`UPDATE browser_task_clarifications
+          SET resolved = 1, answered_at = ?
+        WHERE id = ? AND resolved = 0`)
+        .run(nowMs, id);
+    if (result.changes === 0)
+        return null;
+    return getClarification(db, id);
+}

package/dist/db/browser-task-final-confirm-tokens-store.d.ts

@@ -0,0 +1,108 @@
+/**
+ * Lite-final-confirm tokens — BROWSER_TASK_REDESIGN_PLAN.md §5 / §14.11.
+ *
+ * Parallel primitive to B-4's `browser-automation-purchase-tokens-store`.
+ * The wire shape and CAS contract intentionally mirror the B-4 path so
+ * the messaging adapter's `jti`-prefix dispatcher (§14.11 Q#6) can fan
+ * a single inbound `!~xxxxxxxx` reply to whichever handler holds the
+ * matching token — without coupling lite-final-confirm to B-4's purchase
+ * site config, currency, or spend caps.
+ *
+ * I/O-bound. Excluded from the coverage gate; the pure mint / classify
+ * helpers live in
+ * `services/browser-history/automation/lite-final-confirm-tokens.ts`
+ * and are 100% covered (mirror of `purchase-tokens.ts`).
+ */
+import type Database from "better-sqlite3";
+export type LiteFinalConfirmTokenStatus = "pending" | "confirmed" | "cancelled" | "expired";
+export type LiteFinalConfirmCancelReason = "user_reply" | "wrong_token" | "wrong_channel" | "timeout" | "explicit" | "task_cancelled" | "dashboard_cancel";
+export interface LiteFinalConfirmTokenRow {
+    jti: string;
+    /** Raw `!~xxxxxxxx` while the row is in a state where redemption /
+     *  audit cross-referencing needs the pre-image. NULL after the daily
+     *  cleanup cron rotates terminal rows. */
+    token: string | null;
+    taskId: string;
+    actionSummary: string;
+    preScreenshotPath: string;
+    deliveredChannels: readonly string[];
+    issuedAt: number;
+    expiresAt: number;
+    consumedAt: number | null;
+    consumedViaChannel: string | null;
+    cancelledAt: number | null;
+    cancelReason: LiteFinalConfirmCancelReason | null;
+    status: LiteFinalConfirmTokenStatus;
+}
+export interface IssueLiteFinalConfirmTokenInput {
+    jti?: string;
+    token: string;
+    taskId: string;
+    actionSummary: string;
+    preScreenshotPath: string;
+    deliveredChannels: readonly string[];
+    issuedAt: number;
+    expiresAt: number;
+}
+export type IssueLiteFinalConfirmTokenResult = {
+    ok: true;
+    row: LiteFinalConfirmTokenRow;
+} | {
+    ok: false;
+    reason: "pending_exists";
+    pendingJti: string;
+} | {
+    ok: false;
+    reason: "token_collision";
+};
+/**
+ * Atomic issuance — per-task concurrency 1. Rejects when another
+ * pending token exists for the same task (two parallel final-confirm
+ * gate trips would silently corrupt the round-trip).
+ */
+export declare function issueLiteFinalConfirmToken(db: Database.Database, input: IssueLiteFinalConfirmTokenInput): IssueLiteFinalConfirmTokenResult;
+export declare function getLiteFinalConfirmTokenByJti(db: Database.Database, jti: string): LiteFinalConfirmTokenRow | null;
+export declare function getLiteFinalConfirmTokenByRaw(db: Database.Database, raw: string): LiteFinalConfirmTokenRow | null;
+export interface ConsumeLiteFinalConfirmTokenInput {
+    jti: string;
+    channelRef: string;
+    consumedAt: number;
+    nowMs: number;
+}
+/** CAS consume — atomic UPDATE guarded by status='pending' AND
+ *  consumed_at IS NULL AND cancelled_at IS NULL AND expires_at >= now.
+ *  Two concurrent replies on different channels cannot both win. */
+export declare function consumeLiteFinalConfirmToken(db: Database.Database, input: ConsumeLiteFinalConfirmTokenInput): LiteFinalConfirmTokenRow | null;
+export interface CancelLiteFinalConfirmTokenInput {
+    jti: string;
+    reason: LiteFinalConfirmCancelReason;
+    cancelledAt: number;
+    /** When true, refuse to cancel a row that has already been consumed. */
+    onlyIfPending: boolean;
+}
+export declare function cancelLiteFinalConfirmToken(db: Database.Database, input: CancelLiteFinalConfirmTokenInput): LiteFinalConfirmTokenRow | null;
+/** Pending tokens whose `delivered_channels` JSON contains the given
+ *  channel ref. Used by the non-token-reply strict-cancel path. */
+export declare function listPendingLiteFinalConfirmTokensForChannel(db: Database.Database, channelRef: string, nowMs: number): readonly LiteFinalConfirmTokenRow[];
+export declare function listPendingLiteFinalConfirmTokens(db: Database.Database, nowMs: number, limit?: number): readonly LiteFinalConfirmTokenRow[];
+/**
+ * Retention sweep helpers — mirror the B-4 trio in
+ * `browser-automation-purchase-tokens-store.ts`. Three passes match the
+ * BROWSER_TASK_REDESIGN_PLAN.md §6.5 "Phase 6.5 deferred follow-up" + §14.7
+ * posture:
+ *   1. `expireStaleLiteFinalConfirmTokens` — flip past-TTL pending rows to
+ *      `expired` so a daemon restart or runner stall does not leave a
+ *      pending row behind the dashboard's "Pending tokens" view.
+ *   2. `scrubRotatedLiteFinalConfirmTokens` — set `token = NULL` on
+ *      terminal rows older than `cutoffMs`. Reduces at-rest raw-token
+ *      footprint, matching B-4's
+ *      `browserAutomationPurchaseTokenScrub: 1` day window.
+ *
+ * No counterpart to B-4's `sweepOrphanedConsumedPurchaseTokens` is
+ * needed: the lite token's contract is single-use CAS at consume time —
+ * there is no separate "consumed but not finalized" window. The driver
+ * either confirms (status -> 'confirmed', cancel_reason NULL) or the
+ * confirm path bails and cancels the row directly.
+ */
+export declare function expireStaleLiteFinalConfirmTokens(db: Database.Database, nowMs: number): readonly LiteFinalConfirmTokenRow[];
+export declare function scrubRotatedLiteFinalConfirmTokens(db: Database.Database, cutoffMs: number): number;

package/dist/db/browser-task-final-confirm-tokens-store.js

@@ -0,0 +1,251 @@
+/**
+ * Lite-final-confirm tokens — BROWSER_TASK_REDESIGN_PLAN.md §5 / §14.11.
+ *
+ * Parallel primitive to B-4's `browser-automation-purchase-tokens-store`.
+ * The wire shape and CAS contract intentionally mirror the B-4 path so
+ * the messaging adapter's `jti`-prefix dispatcher (§14.11 Q#6) can fan
+ * a single inbound `!~xxxxxxxx` reply to whichever handler holds the
+ * matching token — without coupling lite-final-confirm to B-4's purchase
+ * site config, currency, or spend caps.
+ *
+ * I/O-bound. Excluded from the coverage gate; the pure mint / classify
+ * helpers live in
+ * `services/browser-history/automation/lite-final-confirm-tokens.ts`
+ * and are 100% covered (mirror of `purchase-tokens.ts`).
+ */
+import { randomUUID } from "node:crypto";
+function fromDbRow(row) {
+    let delivered;
+    try {
+        const parsed = JSON.parse(row.delivered_channels);
+        delivered = Array.isArray(parsed)
+            ? parsed.filter((v) => typeof v === "string")
+            : [];
+    }
+    catch {
+        delivered = [];
+    }
+    return {
+        jti: row.jti,
+        token: row.token,
+        taskId: row.task_id,
+        actionSummary: row.action_summary,
+        preScreenshotPath: row.pre_screenshot_path,
+        deliveredChannels: delivered,
+        issuedAt: row.issued_at,
+        expiresAt: row.expires_at,
+        consumedAt: row.consumed_at,
+        consumedViaChannel: row.consumed_via_channel,
+        cancelledAt: row.cancelled_at,
+        cancelReason: row.cancel_reason,
+        status: row.status,
+    };
+}
+/**
+ * Atomic issuance — per-task concurrency 1. Rejects when another
+ * pending token exists for the same task (two parallel final-confirm
+ * gate trips would silently corrupt the round-trip).
+ */
+export function issueLiteFinalConfirmToken(db, input) {
+    const jti = input.jti ?? randomUUID();
+    const txn = db.transaction(() => {
+        const pendingRow = db
+            .prepare(`SELECT MIN(jti) AS jti, COUNT(*) AS c
+           FROM browser_task_final_confirm_tokens
+          WHERE task_id = ?
+            AND status = 'pending'
+            AND expires_at > ?`)
+            .get(input.taskId, input.issuedAt);
+        if ((pendingRow?.c ?? 0) > 0) {
+            return {
+                ok: false,
+                reason: "pending_exists",
+                pendingJti: pendingRow?.jti ?? "",
+            };
+        }
+        try {
+            db.prepare(`INSERT INTO browser_task_final_confirm_tokens
+           (jti, token, task_id, action_summary, pre_screenshot_path,
+            delivered_channels, issued_at, expires_at,
+            consumed_at, consumed_via_channel,
+            cancelled_at, cancel_reason, status)
+         VALUES (?, ?, ?, ?, ?, ?, ?, ?, NULL, NULL, NULL, NULL, 'pending')`).run(jti, input.token, input.taskId, input.actionSummary, input.preScreenshotPath, JSON.stringify([...input.deliveredChannels]), input.issuedAt, input.expiresAt);
+        }
+        catch (err) {
+            // Detect the token-column UNIQUE collision robustly: better-sqlite3
+            // surfaces the SQLite extended code on the error object as `.code`,
+            // and the message still names the specific column when the error is
+            // a UNIQUE violation. Requiring both removes brittleness against
+            // SQLite versions that reformat the message text while still
+            // pinning the collision to the `token` column (not e.g. `jti`).
+            const sqliteCode = err instanceof Error && "code" in err
+                ? err.code
+                : undefined;
+            const message = err instanceof Error ? err.message : String(err);
+            if (sqliteCode === "SQLITE_CONSTRAINT_UNIQUE" &&
+                message.includes("browser_task_final_confirm_tokens.token")) {
+                return { ok: false, reason: "token_collision" };
+            }
+            throw err;
+        }
+        const inserted = getLiteFinalConfirmTokenByJti(db, jti);
+        if (!inserted) {
+            throw new Error("issueLiteFinalConfirmToken: post-insert row missing");
+        }
+        return { ok: true, row: inserted };
+    });
+    return txn();
+}
+export function getLiteFinalConfirmTokenByJti(db, jti) {
+    const row = db
+        .prepare(`SELECT jti, token, task_id, action_summary, pre_screenshot_path,
+              delivered_channels, issued_at, expires_at,
+              consumed_at, consumed_via_channel,
+              cancelled_at, cancel_reason, status
+         FROM browser_task_final_confirm_tokens
+        WHERE jti = ?`)
+        .get(jti);
+    return row ? fromDbRow(row) : null;
+}
+export function getLiteFinalConfirmTokenByRaw(db, raw) {
+    const row = db
+        .prepare(`SELECT jti, token, task_id, action_summary, pre_screenshot_path,
+              delivered_channels, issued_at, expires_at,
+              consumed_at, consumed_via_channel,
+              cancelled_at, cancel_reason, status
+         FROM browser_task_final_confirm_tokens
+        WHERE token = ?`)
+        .get(raw);
+    return row ? fromDbRow(row) : null;
+}
+/** CAS consume — atomic UPDATE guarded by status='pending' AND
+ *  consumed_at IS NULL AND cancelled_at IS NULL AND expires_at >= now.
+ *  Two concurrent replies on different channels cannot both win. */
+export function consumeLiteFinalConfirmToken(db, input) {
+    const result = db
+        .prepare(`UPDATE browser_task_final_confirm_tokens
+          SET status = 'confirmed',
+              consumed_at = ?,
+              consumed_via_channel = ?
+        WHERE jti = ?
+          AND status = 'pending'
+          AND consumed_at IS NULL
+          AND cancelled_at IS NULL
+          AND expires_at >= ?`)
+        .run(input.consumedAt, input.channelRef, input.jti, input.nowMs);
+    if (result.changes === 0)
+        return null;
+    return getLiteFinalConfirmTokenByJti(db, input.jti);
+}
+export function cancelLiteFinalConfirmToken(db, input) {
+    const sql = input.onlyIfPending
+        ? `UPDATE browser_task_final_confirm_tokens
+         SET status = 'cancelled',
+             cancelled_at = ?,
+             cancel_reason = ?
+       WHERE jti = ?
+         AND status = 'pending'
+         AND consumed_at IS NULL
+         AND cancelled_at IS NULL`
+        : `UPDATE browser_task_final_confirm_tokens
+         SET status = 'cancelled',
+             cancelled_at = ?,
+             cancel_reason = ?
+       WHERE jti = ?
+         AND status IN ('pending')
+         AND cancelled_at IS NULL`;
+    const result = db
+        .prepare(sql)
+        .run(input.cancelledAt, input.reason, input.jti);
+    if (result.changes === 0)
+        return null;
+    return getLiteFinalConfirmTokenByJti(db, input.jti);
+}
+/** Pending tokens whose `delivered_channels` JSON contains the given
+ *  channel ref. Used by the non-token-reply strict-cancel path. */
+export function listPendingLiteFinalConfirmTokensForChannel(db, channelRef, nowMs) {
+    // SQLite's JSON1 `json_each` lets the index walk row-by-row; for
+    // the small in-flight set (≤ browserTaskMaxConcurrent rows) the
+    // straightforward "load and filter in JS" is the simpler shape.
+    const rows = db
+        .prepare(`SELECT jti, token, task_id, action_summary, pre_screenshot_path,
+              delivered_channels, issued_at, expires_at,
+              consumed_at, consumed_via_channel,
+              cancelled_at, cancel_reason, status
+         FROM browser_task_final_confirm_tokens
+        WHERE status = 'pending'
+          AND consumed_at IS NULL
+          AND cancelled_at IS NULL
+          AND expires_at > ?`)
+        .all(nowMs);
+    return rows
+        .map(fromDbRow)
+        .filter((r) => r.deliveredChannels.includes(channelRef));
+}
+export function listPendingLiteFinalConfirmTokens(db, nowMs, limit = 32) {
+    const rows = db
+        .prepare(`SELECT jti, token, task_id, action_summary, pre_screenshot_path,
+              delivered_channels, issued_at, expires_at,
+              consumed_at, consumed_via_channel,
+              cancelled_at, cancel_reason, status
+         FROM browser_task_final_confirm_tokens
+        WHERE status = 'pending'
+          AND consumed_at IS NULL
+          AND cancelled_at IS NULL
+          AND expires_at > ?
+        ORDER BY issued_at DESC
+        LIMIT ?`)
+        .all(nowMs, limit);
+    return rows.map(fromDbRow);
+}
+/**
+ * Retention sweep helpers — mirror the B-4 trio in
+ * `browser-automation-purchase-tokens-store.ts`. Three passes match the
+ * BROWSER_TASK_REDESIGN_PLAN.md §6.5 "Phase 6.5 deferred follow-up" + §14.7
+ * posture:
+ *   1. `expireStaleLiteFinalConfirmTokens` — flip past-TTL pending rows to
+ *      `expired` so a daemon restart or runner stall does not leave a
+ *      pending row behind the dashboard's "Pending tokens" view.
+ *   2. `scrubRotatedLiteFinalConfirmTokens` — set `token = NULL` on
+ *      terminal rows older than `cutoffMs`. Reduces at-rest raw-token
+ *      footprint, matching B-4's
+ *      `browserAutomationPurchaseTokenScrub: 1` day window.
+ *
+ * No counterpart to B-4's `sweepOrphanedConsumedPurchaseTokens` is
+ * needed: the lite token's contract is single-use CAS at consume time —
+ * there is no separate "consumed but not finalized" window. The driver
+ * either confirms (status -> 'confirmed', cancel_reason NULL) or the
+ * confirm path bails and cancels the row directly.
+ */
+export function expireStaleLiteFinalConfirmTokens(db, nowMs) {
+    const ids = db
+        .prepare(`SELECT jti
+         FROM browser_task_final_confirm_tokens
+        WHERE status = 'pending'
+          AND consumed_at IS NULL
+          AND cancelled_at IS NULL
+          AND expires_at < ?`)
+        .all(nowMs)
+        .map((row) => row.jti);
+    if (ids.length === 0)
+        return [];
+    const placeholders = ids.map(() => "?").join(",");
+    db.prepare(`UPDATE browser_task_final_confirm_tokens
+        SET status = 'expired',
+            cancelled_at = ?,
+            cancel_reason = 'timeout'
+      WHERE jti IN (${placeholders})`).run(nowMs, ...ids);
+    return ids
+        .map((id) => getLiteFinalConfirmTokenByJti(db, id))
+        .filter((row) => row !== null);
+}
+export function scrubRotatedLiteFinalConfirmTokens(db, cutoffMs) {
+    const result = db
+        .prepare(`UPDATE browser_task_final_confirm_tokens
+          SET token = NULL
+        WHERE token IS NOT NULL
+          AND status IN ('confirmed', 'cancelled', 'expired')
+          AND COALESCE(consumed_at, cancelled_at, issued_at) < ?`)
+        .run(cutoffMs);
+    return result.changes;
+}