@aitne/daemon 0.1.9 → 0.1.11

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

@@ -45,6 +45,7 @@ function fromDbRow(row) {
         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
@@ -55,8 +56,8 @@ export function createBrowserTask(db, input) {
         originating_channel, schedule_row_id, require_final_confirm,
         state, outcome_detail, report, effective_allowlist_regex,
         blocked_requests_count, extract_chars_total,
-        created_at, started_at, finished_at)
-     VALUES (?, ?, ?, ?, ?, ?, ?, 'pending', NULL, NULL, ?, 0, 0, ?, NULL, NULL)`).run(input.id, input.description, input.siteKey, JSON.stringify([...input.extraAllowedHosts]), input.originatingChannel, input.scheduleRowId, input.requireFinalConfirm ? 1 : 0, input.effectiveAllowlistRegex, input.createdAt);
+        created_at, started_at, finished_at, delivered_at)
+     VALUES (?, ?, ?, ?, ?, ?, ?, 'pending', NULL, NULL, ?, 0, 0, ?, NULL, NULL, NULL)`).run(input.id, input.description, input.siteKey, JSON.stringify([...input.extraAllowedHosts]), input.originatingChannel, input.scheduleRowId, input.requireFinalConfirm ? 1 : 0, input.effectiveAllowlistRegex, input.createdAt);
     const row = getBrowserTask(db, input.id);
     if (!row) {
         throw new Error(`createBrowserTask: post-insert row for ${input.id} missing`);
@@ -69,7 +70,7 @@ export function getBrowserTask(db, id) {
               originating_channel, schedule_row_id, require_final_confirm,
               state, outcome_detail, report, effective_allowlist_regex,
               blocked_requests_count, extract_chars_total,
-              created_at, started_at, finished_at
+              created_at, started_at, finished_at, delivered_at
          FROM browser_task
         WHERE id = ?`)
         .get(id);
@@ -96,7 +97,7 @@ export function listBrowserTasks(db, options = {}) {
                       originating_channel, schedule_row_id, require_final_confirm,
                       state, outcome_detail, report, effective_allowlist_regex,
                       blocked_requests_count, extract_chars_total,
-                      created_at, started_at, finished_at
+                      created_at, started_at, finished_at, delivered_at
                  FROM browser_task
                ${where.length ? `WHERE ${where.join(" AND ")}` : ""}
                ORDER BY created_at DESC
@@ -183,6 +184,30 @@ export function markTerminal(db, input) {
         .run(input.state, input.outcomeDetail, input.report, input.finishedAt, input.id);
     return result.changes > 0 ? getBrowserTask(db, input.id) : null;
 }
+export function markBrowserTaskDelivered(db, id, deliveredAt) {
+    const result = db
+        .prepare(`UPDATE browser_task
+          SET delivered_at = COALESCE(delivered_at, ?)
+        WHERE id = ?`)
+        .run(deliveredAt, id);
+    return result.changes > 0 ? getBrowserTask(db, id) : null;
+}
+export function listUndeliveredBrowserTaskReports(db, limit = 20) {
+    const rows = db
+        .prepare(`SELECT id, description, site_key, extra_allowed_hosts_json,
+              originating_channel, schedule_row_id, require_final_confirm,
+              state, outcome_detail, report, effective_allowlist_regex,
+              blocked_requests_count, extract_chars_total,
+              created_at, started_at, finished_at, delivered_at
+         FROM browser_task
+        WHERE state = 'completed'
+          AND report IS NOT NULL
+          AND delivered_at IS NULL
+        ORDER BY finished_at ASC, created_at ASC
+        LIMIT ?`)
+        .all(limit);
+    return rows.map(fromDbRow);
+}
 /** Increment the per-task CDP-blocked counter. Atomic. */
 export function incrementBlockedRequests(db, id, by) {
     db.prepare(`UPDATE browser_task

package/dist/db/deferred-dm.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Quiet-hours DM deferral — QUIET_HOURS_HARDENING_PLAN.md Phase 1.
+ *
+ * When an autonomous outbound DM fires inside the quiet-hours window, the
+ * message is NOT sent and NOT dropped: it is persisted as a
+ * `task_type='dm'` `agent_schedule` row scheduled for the quiet-hours end
+ * boundary. That reuses the existing zero-cost pre-composed-DM machinery
+ * end to end — full message in `task_description` (no truncation),
+ * restart-safe, visible on the `/schedule` dashboard page, delivered by
+ * the scheduler's `handleDirectDm` (whose deliberate quiet-hours skip is
+ * correct here: the row fires *at* the quiet-hours edge).
+ *
+ * Pile-up guard: a second deferral from the same origin (same
+ * `deferred_from` + agent id / origin session id) appends to the existing
+ * pending row (two-blank-line join, the batch-flush convention) instead
+ * of inserting a sibling — an hourly Agent firing five times overnight
+ * yields one combined DM at the edge, not five.
+ *
+ * Shared by the `/api/notify` gate (Phase 1) and, later, the
+ * NotificationManager `scheduled.task` final-text branch (Phase 1b) —
+ * one implementation instead of bespoke `agent_schedule` SQL per caller.
+ */
+import type Database from "better-sqlite3";
+import { type QuietHoursWindow } from "../core/quiet-hours.js";
+export interface DeferDmParams {
+    /** Full message body — persisted untruncated in `task_description`. */
+    message: string;
+    /** Explicit platform targets; omitted → MessageHub default destinations. */
+    platforms?: string[] | undefined;
+    /** Origin marker for audit + coalescing, e.g. `"api.notify"`. */
+    deferredFrom: string;
+    /** Session that produced the message, when known. */
+    originSessionId?: number | undefined;
+    /** Owning user-Agent slug, when resolvable. */
+    agentId?: string | null | undefined;
+}
+export interface DeferredDmResult {
+    scheduleId: string;
+    /** SQLite-format UTC datetime the row fires at (quiet-hours end). */
+    deliverAfter: string;
+    /** True when appended to an existing pending deferred row. */
+    coalesced: boolean;
+}
+/**
+ * Gate decision + deferred-row insert. Returns `null` when `now` is NOT
+ * inside the quiet-hours window (caller proceeds with the immediate
+ * path); otherwise persists the message for the quiet-hours edge and
+ * returns the row handle.
+ */
+export declare function deferDmToQuietHoursEnd(db: Database.Database, window: QuietHoursWindow, params: DeferDmParams, now?: Date): DeferredDmResult | null;
+/**
+ * Retime pending quiet-hours-deferred DM rows after a quiet-hours config
+ * change (the `syncDmSessionTimesToQuietHours` sibling for this module's
+ * rows). The deferral premise — "the row fires *at* the quiet-hours edge,
+ * so `handleDirectDm`'s quiet-hours skip is correct" — only holds while
+ * the window that produced `scheduled_for` is still the configured one:
+ *
+ *   - window extended (end moved later) → without retiming the row fires
+ *     *inside* the new quiet window;
+ *   - window shortened (end moved earlier) → the row waits past the new
+ *     edge for no reason.
+ *
+ * Rule: inside the new window every deferred row moves to the new edge;
+ * outside it, future-dated rows are pulled up to `now` (the next scheduler
+ * tick delivers them) and already-due rows are left for the tick to claim.
+ * User-scheduled `dm` rows (no `deferred_from` marker) are never touched.
+ * Returns the number of rows retimed.
+ */
+export declare function retimeDeferredDmRows(db: Database.Database, window: QuietHoursWindow, now?: Date): number;
+/**
+ * Retime pending quiet-hours-deferred RUN rows (`agent.task` opt-in and
+ * `browser_task`) after a quiet-hours config change — the
+ * `retimeDeferredDmRows` sibling for rows the ScheduleWatcher's
+ * `deferClaimedRowForQuietHours` pushed to the old window's end. That helper
+ * stamps `task_context.quiet_hours_deferred` at deferral time for exactly
+ * this purpose: rows that merely *carry* the `defer_in_quiet_hours` opt-in on
+ * a future cron slot were never deferred and keep their cron-scheduled time.
+ *
+ * Unlike deferred DM rows (delivered by `handleDirectDm`, which skips the
+ * quiet-hours check by design), run rows re-check the window at claim time,
+ * so a *widened* window self-corrects — retiming it here merely skips the
+ * wasted claim/re-defer cycle and its duplicate audit row. The
+ * narrowed/disabled direction is the real fix: without retiming, the run
+ * waits at the old window's end for no reason.
+ */
+export declare function retimeDeferredRunRows(db: Database.Database, window: QuietHoursWindow, now?: Date): number;

package/dist/db/deferred-dm.js

@@ -0,0 +1,199 @@
+import { formatSqliteDatetime } from "@aitne/shared";
+import { nextQuietHoursEndMs, } from "../core/quiet-hours.js";
+import { createLogger } from "../logging.js";
+const logger = createLogger("deferred-dm");
+/**
+ * Coalescing identity: prefer the Agent slug (stable across an Agent's
+ * overnight firings), fall back to the origin session, else an anonymous
+ * shared bucket. Unrelated anonymous system DMs deferring into one
+ * combined message is intended — that's the pile-up guard, not a bug.
+ */
+function coalesceKey(agentId, originSessionId) {
+    if (agentId)
+        return `agent:${agentId}`;
+    if (originSessionId !== null && originSessionId !== undefined) {
+        return `session:${originSessionId}`;
+    }
+    return "anonymous";
+}
+/** Union of explicit platform targets; either side defaulting (null /
+ *  undefined = MessageHub default destinations) keeps the default. */
+function mergePlatforms(existing, incoming) {
+    if (!Array.isArray(existing) || incoming === undefined)
+        return null;
+    return [...new Set([...existing, ...incoming])];
+}
+/**
+ * Gate decision + deferred-row insert. Returns `null` when `now` is NOT
+ * inside the quiet-hours window (caller proceeds with the immediate
+ * path); otherwise persists the message for the quiet-hours edge and
+ * returns the row handle.
+ */
+export function deferDmToQuietHoursEnd(db, window, params, now = new Date()) {
+    const quietEndMs = nextQuietHoursEndMs(now, window);
+    if (quietEndMs === null)
+        return null;
+    const key = coalesceKey(params.agentId, params.originSessionId);
+    // `json_valid` guard first: a hand-edited row with broken JSON would
+    // otherwise make `json_extract` throw for the whole query. Such a row
+    // simply never coalesces; a fresh row carries this message.
+    const pending = db
+        .prepare(`SELECT id, task_description, task_context, scheduled_for
+         FROM agent_schedule
+        WHERE status = 'pending'
+          AND task_type = 'dm'
+          AND task_context IS NOT NULL
+          AND json_valid(task_context)
+          AND json_extract(task_context, '$.deferred_from') = ?
+        ORDER BY id ASC`)
+        .all(params.deferredFrom);
+    for (const row of pending) {
+        // json_valid in the WHERE clause guarantees parseability here.
+        const ctx = JSON.parse(row.task_context);
+        const rowKey = coalesceKey(typeof ctx.agent_id === "string" ? ctx.agent_id : null, typeof ctx.origin_session_id === "number" ? ctx.origin_session_id : null);
+        if (rowKey !== key)
+            continue;
+        ctx.platforms = mergePlatforms(ctx.platforms, params.platforms);
+        db.prepare(`UPDATE agent_schedule
+          SET task_description = ?, task_context = ?
+        WHERE id = ?`).run(`${row.task_description}\n\n${params.message}`, JSON.stringify(ctx), row.id);
+        const result = {
+            scheduleId: String(row.id),
+            deliverAfter: row.scheduled_for,
+            coalesced: true,
+        };
+        recordDeferralAudit(db, window, params, result);
+        return result;
+    }
+    const deliverAfter = formatSqliteDatetime(new Date(quietEndMs));
+    const taskContext = {
+        platforms: params.platforms ?? null,
+        // Matches the `/schedule/dm` default — deferred pings stay out of
+        // roadmap `Scheduled:` entries.
+        importance: "transient",
+        deferred_from: params.deferredFrom,
+        ...(params.originSessionId !== undefined
+            ? { origin_session_id: params.originSessionId }
+            : {}),
+        ...(params.agentId ? { agent_id: params.agentId } : {}),
+    };
+    const inserted = db
+        .prepare(
+    // task_type='dm' is consumed directly by `handleDirectDm` — the LLM
+    // never runs, so `model` is NULL (same shape as POST /schedule/dm).
+    `INSERT INTO agent_schedule (scheduled_for, task_type, task_description, task_context, model, status)
+       VALUES (?, 'dm', ?, ?, NULL, 'pending')`)
+        .run(deliverAfter, params.message, JSON.stringify(taskContext));
+    const result = {
+        scheduleId: String(inserted.lastInsertRowid),
+        deliverAfter,
+        coalesced: false,
+    };
+    recordDeferralAudit(db, window, params, result);
+    return result;
+}
+/**
+ * Retime pending quiet-hours-deferred DM rows after a quiet-hours config
+ * change (the `syncDmSessionTimesToQuietHours` sibling for this module's
+ * rows). The deferral premise — "the row fires *at* the quiet-hours edge,
+ * so `handleDirectDm`'s quiet-hours skip is correct" — only holds while
+ * the window that produced `scheduled_for` is still the configured one:
+ *
+ *   - window extended (end moved later) → without retiming the row fires
+ *     *inside* the new quiet window;
+ *   - window shortened (end moved earlier) → the row waits past the new
+ *     edge for no reason.
+ *
+ * Rule: inside the new window every deferred row moves to the new edge;
+ * outside it, future-dated rows are pulled up to `now` (the next scheduler
+ * tick delivers them) and already-due rows are left for the tick to claim.
+ * User-scheduled `dm` rows (no `deferred_from` marker) are never touched.
+ * Returns the number of rows retimed.
+ */
+export function retimeDeferredDmRows(db, window, now = new Date()) {
+    const rows = db
+        .prepare(`SELECT id, scheduled_for
+         FROM agent_schedule
+        WHERE status = 'pending'
+          AND task_type = 'dm'
+          AND task_context IS NOT NULL
+          AND json_valid(task_context)
+          AND json_extract(task_context, '$.deferred_from') IS NOT NULL`)
+        .all();
+    return retimeRowsToWindowEdge(db, window, now, rows, "dm");
+}
+/**
+ * Retime pending quiet-hours-deferred RUN rows (`agent.task` opt-in and
+ * `browser_task`) after a quiet-hours config change — the
+ * `retimeDeferredDmRows` sibling for rows the ScheduleWatcher's
+ * `deferClaimedRowForQuietHours` pushed to the old window's end. That helper
+ * stamps `task_context.quiet_hours_deferred` at deferral time for exactly
+ * this purpose: rows that merely *carry* the `defer_in_quiet_hours` opt-in on
+ * a future cron slot were never deferred and keep their cron-scheduled time.
+ *
+ * Unlike deferred DM rows (delivered by `handleDirectDm`, which skips the
+ * quiet-hours check by design), run rows re-check the window at claim time,
+ * so a *widened* window self-corrects — retiming it here merely skips the
+ * wasted claim/re-defer cycle and its duplicate audit row. The
+ * narrowed/disabled direction is the real fix: without retiming, the run
+ * waits at the old window's end for no reason.
+ */
+export function retimeDeferredRunRows(db, window, now = new Date()) {
+    const rows = db
+        .prepare(`SELECT id, scheduled_for
+         FROM agent_schedule
+        WHERE status = 'pending'
+          AND task_context IS NOT NULL
+          AND json_valid(task_context)
+          AND json_extract(task_context, '$.quiet_hours_deferred') = 1`)
+        .all();
+    return retimeRowsToWindowEdge(db, window, now, rows, "run");
+}
+/**
+ * Shared retime rule: inside the new window every row moves to the new edge;
+ * outside it, future-dated rows are pulled up to `now` (the next scheduler
+ * tick handles them) and already-due rows are left for the tick to claim.
+ */
+function retimeRowsToWindowEdge(db, window, now, rows, kind) {
+    if (rows.length === 0)
+        return 0;
+    const quietEndMs = nextQuietHoursEndMs(now, window);
+    const target = formatSqliteDatetime(quietEndMs !== null ? new Date(quietEndMs) : now);
+    const update = db.prepare("UPDATE agent_schedule SET scheduled_for = ? WHERE id = ?");
+    let retimed = 0;
+    for (const row of rows) {
+        // Outside quiet hours only future rows move — an already-due row is
+        // the scheduler's to claim; rewriting it would just delay delivery.
+        if (quietEndMs === null && row.scheduled_for <= target)
+            continue;
+        if (row.scheduled_for === target)
+            continue;
+        update.run(target, row.id);
+        retimed++;
+    }
+    if (retimed > 0) {
+        logger.info({ retimed, target, insideQuietHours: quietEndMs !== null, kind }, "Retimed pending quiet-hours-deferred rows after quiet-hours change");
+    }
+    return retimed;
+}
+/** One `agent_actions` row per deferral so the user can see the delay —
+ *  mirrors the scheduler's `browser_task.deferred_for_quiet_hours`. */
+function recordDeferralAudit(db, window, params, result) {
+    try {
+        db.prepare(`INSERT INTO agent_actions
+         (action_type, detail, result, started_at, completed_at)
+       VALUES (?, ?, 'success', CURRENT_TIMESTAMP, CURRENT_TIMESTAMP)`).run("notify.deferred_for_quiet_hours", JSON.stringify({
+            scheduleId: result.scheduleId,
+            deferredFrom: params.deferredFrom,
+            originSessionId: params.originSessionId ?? null,
+            agentId: params.agentId ?? null,
+            deliverAfter: result.deliverAfter,
+            coalesced: result.coalesced,
+            quietHoursStart: window.start,
+            quietHoursEnd: window.end,
+        }));
+    }
+    catch (err) {
+        logger.warn({ err, scheduleId: result.scheduleId }, "Failed to record notify.deferred_for_quiet_hours audit — deferred row already persisted");
+    }
+}

package/dist/db/feedback-signals-store.d.ts

@@ -0,0 +1,77 @@
+import type Database from "better-sqlite3";
+export type FeedbackSignalSource = "behavioral" | "explicit" | "self_critique";
+export type FeedbackSignalValence = "positive" | "negative" | "neutral" | "correction";
+export type FeedbackScopeType = "user" | "agent" | "agent_slug" | "channel" | "task" | "integration";
+export type FeedbackActionKind = "notification" | "agent_execution" | "vault_write" | "dm_reply";
+export interface FeedbackSignalRow {
+    id: number;
+    created_at: string;
+    source: FeedbackSignalSource;
+    valence: FeedbackSignalValence | null;
+    scope_type: FeedbackScopeType;
+    scope_ref: string | null;
+    action_kind: FeedbackActionKind | null;
+    action_ref: string | null;
+    agent_id: string | null;
+    summary: string;
+    evidence_json: string | null;
+    consumed_at: string | null;
+    lesson_ref: string | null;
+}
+export interface RecordFeedbackSignalParams {
+    source: FeedbackSignalSource;
+    valence?: FeedbackSignalValence | null;
+    scopeType: FeedbackScopeType;
+    scopeRef?: string | null;
+    actionKind?: FeedbackActionKind | null;
+    actionRef?: string | null;
+    agentId?: string | null;
+    summary: string;
+    evidence?: unknown;
+}
+export interface RecentFeedbackSignalLookup {
+    scopeType: FeedbackScopeType;
+    scopeRef?: string | null;
+    summary: string;
+    withinSeconds: number;
+}
+export declare function recordFeedbackSignal(db: Database.Database, params: RecordFeedbackSignalParams): number;
+export declare function findRecentFeedbackSignal(db: Database.Database, params: RecentFeedbackSignalLookup): FeedbackSignalRow | null;
+export declare function hasFeedbackSignalForAction(db: Database.Database, params: {
+    source: FeedbackSignalSource;
+    actionKind: FeedbackActionKind;
+    actionRef: string;
+    valence?: FeedbackSignalValence | null;
+    userReaction?: string;
+}): boolean;
+export declare function getPendingFeedbackSignals(db: Database.Database, params?: {
+    scopeType?: FeedbackScopeType;
+    scopeRef?: string | null;
+    limit?: number;
+    offset?: number;
+}): FeedbackSignalRow[];
+/**
+ * Count unconsumed signals, optionally narrowed to one scope type. Drives the
+ * `GET /api/feedback/lessons` "N signals awaiting tonight's consolidation"
+ * health figure (FEEDBACK_LEARNING_LOOP_DESIGN.md §9 Phase 5) without loading
+ * the rows. Uses the same `consumed_at IS NULL` partial index as
+ * {@link getPendingFeedbackSignals}.
+ */
+export declare function countPendingFeedbackSignals(db: Database.Database, params?: {
+    scopeType?: FeedbackScopeType;
+}): number;
+export declare function consumeFeedbackSignals(db: Database.Database, ids: number[], lessonRef?: string | null): {
+    consumed: number;
+    notFound: number[];
+};
+export declare function sweepConsumedFeedbackSignals(db: Database.Database, cutoff: string): number;
+/**
+ * Compute the retention cutoff ISO timestamp for
+ * {@link sweepConsumedFeedbackSignals} from the `feedbackSignalRetentionDays`
+ * knob. Returns `null` when the knob is missing or non-finite (NaN / Infinity),
+ * so the caller degrades to "skip the sweep" instead of throwing on
+ * `new Date(NaN).toISOString()` and abandoning the whole nightly consolidation
+ * (FEEDBACK_LEARNING_LOOP_DESIGN.md §11 v1.3 robustness). `nowMs` is injected so
+ * the math is deterministically testable.
+ */
+export declare function feedbackRetentionCutoff(retentionDays: number | undefined, nowMs: number): string | null;

package/dist/db/feedback-signals-store.js

@@ -0,0 +1,144 @@
+export function recordFeedbackSignal(db, params) {
+    const evidenceJson = params.evidence === undefined ? "{}" : JSON.stringify(params.evidence);
+    const row = db
+        .prepare(`INSERT INTO feedback_signals (
+         source,
+         valence,
+         scope_type,
+         scope_ref,
+         action_kind,
+         action_ref,
+         agent_id,
+         summary,
+         evidence_json
+       )
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+       RETURNING id`)
+        .get(params.source, params.valence ?? null, params.scopeType, params.scopeRef ?? null, params.actionKind ?? null, params.actionRef ?? null, params.agentId ?? null, params.summary, evidenceJson);
+    return row.id;
+}
+export function findRecentFeedbackSignal(db, params) {
+    const row = db
+        .prepare(`SELECT *
+       FROM feedback_signals
+       WHERE scope_type = ?
+         AND COALESCE(scope_ref, '') = COALESCE(?, '')
+         AND summary = ?
+         AND datetime(created_at) >= datetime('now', '-' || ? || ' seconds')
+       ORDER BY datetime(created_at) DESC, id DESC
+       LIMIT 1`)
+        .get(params.scopeType, params.scopeRef ?? null, params.summary, Math.max(0, Math.floor(params.withinSeconds)));
+    return row ?? null;
+}
+export function hasFeedbackSignalForAction(db, params) {
+    const where = [
+        "source = ?",
+        "action_kind = ?",
+        "action_ref = ?",
+    ];
+    const values = [params.source, params.actionKind, params.actionRef];
+    if (params.valence !== undefined) {
+        where.push(params.valence === null ? "valence IS NULL" : "valence = ?");
+        if (params.valence !== null)
+            values.push(params.valence);
+    }
+    if (params.userReaction !== undefined) {
+        where.push("json_extract(evidence_json, '$.userReaction') = ?");
+        values.push(params.userReaction);
+    }
+    const row = db
+        .prepare(`SELECT 1 AS present
+       FROM feedback_signals
+       WHERE ${where.join(" AND ")}
+       LIMIT 1`)
+        .get(...values);
+    return row !== undefined;
+}
+export function getPendingFeedbackSignals(db, params = {}) {
+    const where = ["consumed_at IS NULL"];
+    const values = [];
+    if (params.scopeType !== undefined) {
+        where.push("scope_type = ?");
+        values.push(params.scopeType);
+    }
+    if (params.scopeRef !== undefined) {
+        where.push("COALESCE(scope_ref, '') = COALESCE(?, '')");
+        values.push(params.scopeRef);
+    }
+    const limit = Math.min(Math.max(params.limit ?? 100, 1), 500);
+    const offset = Math.max(params.offset ?? 0, 0);
+    values.push(limit, offset);
+    return db
+        .prepare(`SELECT *
+       FROM feedback_signals
+       WHERE ${where.join(" AND ")}
+       ORDER BY datetime(created_at) ASC, id ASC
+       LIMIT ? OFFSET ?`)
+        .all(...values);
+}
+/**
+ * Count unconsumed signals, optionally narrowed to one scope type. Drives the
+ * `GET /api/feedback/lessons` "N signals awaiting tonight's consolidation"
+ * health figure (FEEDBACK_LEARNING_LOOP_DESIGN.md §9 Phase 5) without loading
+ * the rows. Uses the same `consumed_at IS NULL` partial index as
+ * {@link getPendingFeedbackSignals}.
+ */
+export function countPendingFeedbackSignals(db, params = {}) {
+    const where = ["consumed_at IS NULL"];
+    const values = [];
+    if (params.scopeType !== undefined) {
+        where.push("scope_type = ?");
+        values.push(params.scopeType);
+    }
+    const row = db
+        .prepare(`SELECT COUNT(*) AS n
+       FROM feedback_signals
+       WHERE ${where.join(" AND ")}`)
+        .get(...values);
+    return row.n;
+}
+export function consumeFeedbackSignals(db, ids, lessonRef) {
+    if (ids.length === 0)
+        return { consumed: 0, notFound: [] };
+    const placeholders = ids.map(() => "?").join(",");
+    const existing = db
+        .prepare(`SELECT id
+       FROM feedback_signals
+       WHERE id IN (${placeholders}) AND consumed_at IS NULL`)
+        .all(...ids);
+    const existingIds = new Set(existing.map((row) => row.id));
+    const notFound = ids.filter((id) => !existingIds.has(id));
+    if (existingIds.size === 0)
+        return { consumed: 0, notFound };
+    const updateIds = Array.from(existingIds);
+    const updatePlaceholders = updateIds.map(() => "?").join(",");
+    const consumed = db
+        .prepare(`UPDATE feedback_signals
+       SET consumed_at = CURRENT_TIMESTAMP, lesson_ref = COALESCE(?, lesson_ref)
+       WHERE id IN (${updatePlaceholders}) AND consumed_at IS NULL`)
+        .run(lessonRef ?? null, ...updateIds).changes;
+    return { consumed, notFound };
+}
+export function sweepConsumedFeedbackSignals(db, cutoff) {
+    return db
+        .prepare(`DELETE FROM feedback_signals
+       WHERE consumed_at IS NOT NULL
+         AND datetime(consumed_at) < datetime(?)`)
+        .run(cutoff).changes;
+}
+/**
+ * Compute the retention cutoff ISO timestamp for
+ * {@link sweepConsumedFeedbackSignals} from the `feedbackSignalRetentionDays`
+ * knob. Returns `null` when the knob is missing or non-finite (NaN / Infinity),
+ * so the caller degrades to "skip the sweep" instead of throwing on
+ * `new Date(NaN).toISOString()` and abandoning the whole nightly consolidation
+ * (FEEDBACK_LEARNING_LOOP_DESIGN.md §11 v1.3 robustness). `nowMs` is injected so
+ * the math is deterministically testable.
+ */
+export function feedbackRetentionCutoff(retentionDays, nowMs) {
+    if (typeof retentionDays !== "number" || !Number.isFinite(retentionDays)) {
+        return null;
+    }
+    const retentionMs = retentionDays * 24 * 60 * 60 * 1000;
+    return new Date(nowMs - retentionMs).toISOString();
+}