@aitne/daemon 0.1.10 → 0.1.11

package/dist/core/scheduler.js

@@ -7,7 +7,10 @@ import { discardStalePendingSchedules } from "./schedule-maintenance.js";
 import { createLogger } from "../logging.js";
 import { reconcileRecurringSchedules } from "../db/recurring-schedules.js";
 import { recordAgentFiringBlocked } from "./agents/firing-blocked.js";
-import { getStalledMorningRoutineWake, readMorningRoutineStallThresholdMinutes, } from "../bootstrap/schedule-helpers.js";
+import { resolveActivityScanCadence } from "./agents/activity-scan-cadence.js";
+import { getRuntimeWindow } from "../db/agents-store.js";
+import { getDueCatchupRoutines, getRecoverableStalledMorningWake, getStalledMorningRoutineWake, MORNING_MISSED_FIRE_GRACE_MINUTES, morningRoutineRanToday, readMorningRoutineStallThresholdMinutes, shouldCatchUpActivityScan, shouldQueueMissedMorningFire, } from "../bootstrap/schedule-helpers.js";
+import { WakeDetector } from "./wake-detector.js";
 import { readRuntimeState, writeRuntimeState } from "../db/runtime-state.js";
 import { recordProactiveForwardDeliveries } from "./channel-timeline.js";
 import { isInQuietHoursAt, nextQuietHoursEndMs } from "./quiet-hours.js";
@@ -18,6 +21,47 @@ import { isInQuietHoursAt, nextQuietHoursEndMs } from "./quiet-hours.js";
  * agent-day even if the cron tick that owns it runs every minute.
  */
 const MORNING_ROUTINE_STALL_ALERT_KEY = "morning_routine.stall_alert_day";
+/**
+ * Cadence of the morning self-heal tick. The tick is cheap (three indexed
+ * SQLite reads in the common healthy case), and 10 minutes bounds the
+ * worst-case detection latency for a swallowed 04:00 cron fire at
+ * `MORNING_MISSED_FIRE_GRACE_MINUTES + 10`. Deliberately a dedicated
+ * interval rather than a rider on the activity-scan cron: the watchdog
+ * historically rode that cron and went silently dead the moment an
+ * operator set `activityScanEnabled=false` — exactly the configuration
+ * where the morning routine has no other safety net.
+ */
+export const MORNING_SELF_HEAL_INTERVAL_MS = 10 * 60_000;
+/**
+ * Per-agent-day cap on hung-run recovery flips. Each flip re-runs the
+ * morning pipeline (pre-pass + Stage A — real backend spend), so a
+ * deterministically-wedging environment must not be retried every
+ * stall-threshold window all day. Past the cap the self-heal degrades to
+ * alert-only; the owner DM and a daemon restart are the escape hatches.
+ */
+export const MAX_SELFHEAL_REQUEUES_PER_AGENT_DAY = 2;
+/**
+ * Missed-fire suppression window after process start. Boot catchup owns
+ * stale-today.md recovery at startup and runs the morning routine
+ * INLINE — no wake row exists for `shouldQueueMissedMorningFire` to
+ * dedup against, and its attempt audit row only appears once the
+ * fetch-window pre-pass hands over to Stage A. A pathologically slow
+ * pre-pass must not read as a missed fire, so the layer stays quiet
+ * until the boot path has long since either produced attempt rows or
+ * died (in which case the next tick after the window picks it up).
+ */
+export const MISSED_FIRE_BOOT_SUPPRESSION_MS = 30 * 60_000;
+/**
+ * Routine name → built-in Agent slug, for the per-agent enabled gate on the
+ * wake catch-up path. Must match the slugs the corresponding cron callbacks
+ * pass to `isAgentEnabledForFiring` so a disabled Agent is suppressed
+ * identically whether its trigger arrives via cron or via wake catch-up.
+ */
+const WAKE_CATCHUP_AGENT_SLUGS = {
+    evening_review: "evening-review",
+    weekly_review: "weekly-review",
+    monthly_review: "monthly-review",
+};
 const logger = createLogger("scheduler");
 /**
  * True iff `intervalMinutes` cleanly fits inside an hour, so the firing
@@ -29,7 +73,7 @@ function isDivisorOfHour(intervalMinutes) {
     return intervalMinutes >= 1 && intervalMinutes <= 60 && 60 % intervalMinutes === 0;
 }
 /**
- * Build the cron expression that drives the hourly check.
+ * Build the cron expression that drives the activity scan.
  *
  * Two regimes:
  *
@@ -42,7 +86,7 @@ function isDivisorOfHour(intervalMinutes) {
  * 2. **Arbitrary interval** (anything else, e.g. 7, 45, 90, 120, 720,
  *    1440): we emit `"* <hourRange> * * *"` (every minute within active
  *    hours). The caller is expected to gate each tick with
- *    `shouldFireHourlyTickAt(...)`, which anchors the cadence to
+ *    `shouldFireActivityScanTickAt(...)`, which anchors the cadence to
  *    `activeStartHour` via `((h*60 + m) - activeStartHour*60) %
  *    intervalMinutes`. This anchor matters: a midnight-anchored modulo
  *    plus `activeStartHour > 0` would silently drop intervals where the
@@ -54,9 +98,9 @@ function isDivisorOfHour(intervalMinutes) {
  *
  * The minute-tick cron does fire 60× per hour even when most ticks are
  * no-ops, but the callback's first action is the modulo check — overhead
- * is negligible compared to the actual hourly-check work.
+ * is negligible compared to the actual activity-scan work.
  */
-export function buildHourlyCronExpr(intervalMinutes, startHour, endHourExclusive) {
+export function buildActivityScanCronExpr(intervalMinutes, startHour, endHourExclusive) {
     const endHour = Math.max(startHour, endHourExclusive - 1);
     const hourRange = startHour === endHour ? `${startHour}` : `${startHour}-${endHour}`;
     if (isDivisorOfHour(intervalMinutes)) {
@@ -86,7 +130,7 @@ export function buildHourlyCronExpr(intervalMinutes, startHour, endHourExclusive
  * so the divisor early-return doesn't change behavior — it's just
  * explicit about which path the cron expression itself handles.
  */
-export function shouldFireHourlyTickAt(localHour, localMinute, intervalMinutes, activeStartHour) {
+export function shouldFireActivityScanTickAt(localHour, localMinute, intervalMinutes, activeStartHour) {
     if (isDivisorOfHour(intervalMinutes))
         return true;
     const minutesSinceMidnight = localHour * 60 + localMinute;
@@ -163,12 +207,12 @@ export class AgentScheduler {
     noFutureTasksWarned = false;
     onDayBoundary = null;
     sendDm = null;
-    onHourlyCheck = null;
+    onActivityScan = null;
     /**
      * Phase 4 auth probe hook — fired on every hourly cron tick BEFORE
-     * `onHourlyCheck` so the probe gets a chance to refresh DB cache +
+     * `onActivityScan` so the probe gets a chance to refresh DB cache +
      * emit DMs even when the observation-threshold gate would skip the
-     * hourly check itself. The AuthHealthMonitor.checkAll() method owns
+     * activity scan itself. The AuthHealthMonitor.checkAll() method owns
      * its own kill-switch and morning-routine skip; the scheduler only
      * applies the same `autonomousGate` short-circuit that protects the
      * other cron callbacks.
@@ -176,10 +220,24 @@ export class AgentScheduler {
      * See `docs/design/09-safety-cost.md` §9.5.4 for the gate
      * ordering: morning-routine → hourly-already-running → auth probe
      * → observation-threshold. Steps 1 + 2 are handled inside
-     * `triggerHourlyCheck`; step 3 is this callback; step 4 is the
-     * threshold gate inside `triggerHourlyCheck`.
+     * `triggerActivityScan`; step 3 is this callback; step 4 is the
+     * threshold gate inside `triggerActivityScan`.
      */
     onAuthProbe = null;
+    /**
+     * SELF_TUNING_REVIEW_CYCLE_DESIGN.md §3.4 Phase 3 — auto-revert monitor.
+     * Piggybacks the hourly cron tick (P2 — zero new scheduled sessions),
+     * fired AHEAD of the per-agent enabled gate and the autonomous setup
+     * gate so rollback safety survives the owner disabling the activity-scan
+     * Agent or a setup-gated daemon; the callback owns its own 1/day
+     * throttle, per-entry isolation, and DM emission. Remaining coupling:
+     * with `activityScanEnabled=false` this cron is never registered and
+     * applied changes stay unverified until the check is re-enabled —
+     * acceptable because R1/R3 govern the (now-idle) hourly pipeline
+     * itself; an applied R5 (`feedbackLessonMaxBytesGlobal`) change would
+     * sit unverified, with `!revert tuning` as the manual escape hatch.
+     */
+    onSelfTuningRevertMonitor = null;
     /**
      * B-004 Phase 2a — nightly context-index reconciler callback (§4.1).
      * Fires at 03:45 local (dayBoundaryHour - 15 min) via an internal cron
@@ -255,6 +313,27 @@ export class AgentScheduler {
     nudgeSeq = 0;
     observedSeq = 0;
     sleepWaiter = null;
+    /**
+     * Detects machine sleep / forward clock jumps and replays the cron
+     * triggers the sleep swallowed (node-cron never fires missed ticks).
+     * See {@link runWakeCatchup}.
+     */
+    wakeDetector = new WakeDetector({
+        onWake: (gapMs) => this.runWakeCatchup(gapMs),
+    });
+    /**
+     * Independent self-heal tick for the morning routine (alert + recover +
+     * missed-fire re-queue). See {@link runMorningSelfHeal}. Kept off the
+     * activity-scan cron on purpose — that cron is operator-disableable.
+     */
+    morningSelfHealTimer = null;
+    /**
+     * Wall-clock instant this scheduler instance was constructed (one
+     * instance per daemon process). Drives the missed-fire boot
+     * suppression; tests override via cast to simulate a long-lived
+     * process.
+     */
+    startedAtMs = Date.now();
     constructor(eventBus, db, config) {
         this.eventBus = eventBus;
         this.db = db;
@@ -274,18 +353,27 @@ export class AgentScheduler {
     setSendDmCallback(fn) {
         this.sendDm = fn;
     }
-    setHourlyCheckCallback(fn) {
-        this.onHourlyCheck = fn;
+    setActivityScanCallback(fn) {
+        this.onActivityScan = fn;
     }
     /**
      * Register the Phase 4 auth probe callback. Called on each hourly
-     * cron tick BEFORE the hourly-check observation threshold gate so
-     * the probe continues to run even when the hourly check itself
+     * cron tick BEFORE the activity-scan observation threshold gate so
+     * the probe continues to run even when the activity scan itself
      * would be skipped for lack of pending observations.
      */
     setAuthProbeCallback(fn) {
         this.onAuthProbe = fn;
     }
+    /**
+     * Register the Phase 3 self-tuning auto-revert monitor. Called on each
+     * hourly cron tick alongside the auth probe; the monitor throttles
+     * itself to one pass per day and is a no-op until the actuator has
+     * written ledger entries.
+     */
+    setSelfTuningRevertMonitorCallback(fn) {
+        this.onSelfTuningRevertMonitor = fn;
+    }
     /**
      * Register the context-index reconciler cron callback. Called every
      * night at 03:45 local; the callback is expected to be fire-and-forget
@@ -380,9 +468,9 @@ export class AgentScheduler {
      * (CLAUDE.md "morning_routine wake stall"). When the morning routine
      * never writes an `agent_actions.result='success'` row, the dedup
      * inside `queueMorningRoutineWake` keeps the stuck wake row pinned in
-     * `pending`/`running` and the hourly-check pre-routine gate silently
+     * `pending`/`running` and the activity-scan pre-routine gate silently
      * skips every subsequent autonomous tick. The user gets no morning
-     * brief, no evening review, no hourly check, and no error — the
+     * brief, no evening review, no activity scan, and no error — the
      * system is functionally dead until the wake row clears.
      *
      * Detection: oldest `task_type='wake'` row tied to
@@ -446,7 +534,7 @@ export class AgentScheduler {
                 return;
             }
             const message = `Aitne: morning routine stalled ${stalled.ageMinutes} min `
-                + `(wake #${stalled.id}, status=${stalled.status}). Hourly check + `
+                + `(wake #${stalled.id}, status=${stalled.status}). Activity scan + `
                 + `evening review blocked. Check logs or \`aitne restart\`.`;
             try {
                 await this.sendDm(message);
@@ -470,13 +558,251 @@ export class AgentScheduler {
             this.morningStallWatchdogRunning = false;
         }
     }
+    /**
+     * Self-heal tick for the morning routine. Three layers:
+     *
+     * 1. **Recover** — a wake row stuck in `running` whose claim
+     *    (`task_context.claimedAt`) is ≥ stall-threshold minutes old with
+     *    no success today (machine slept mid-run, the backend stream died)
+     *    is flipped back to `pending` so the ScheduleWatcher re-claims it.
+     *    Without this, `queueMorningRoutineWake` dedups into the corpse
+     *    forever and the day stays frozen until a daemon restart. Runs
+     *    BEFORE the alert so a stall the self-heal is about to fix doesn't
+     *    burn the once-per-day DM budget on a misleading "restart the
+     *    daemon" message; if the re-run wedges too, the next tick still
+     *    alerts (the row's created_at age keeps growing). Capped at
+     *    {@link MAX_SELFHEAL_REQUEUES_PER_AGENT_DAY} re-runs per agent-day
+     *    so a deterministic hang cannot burn backend spend every
+     *    threshold-window all day. Worst case if the original execution is
+     *    alive after all: one duplicate morning run, serialized by the
+     *    today-write-lock.
+     * 2. **Alert** — the stall watchdog ({@link checkMorningRoutineStall}).
+     *    Previously this only ran on activity-scan cron ticks, so
+     *    `activityScanEnabled=false` silently disabled it; this timer is the
+     *    guaranteed host now (the cron-tick invocation remains, made safe
+     *    by the watchdog's mutex + per-day DM dedup).
+     * 3. **Missed fire** — no attempt, no wake row, agent-day older than the
+     *    grace window: the boundary cron tick was swallowed (sleep shorter
+     *    than the WakeDetector's gap threshold straddling 04:00, or a
+     *    detector failure) — open the day exactly the way the cron and the
+     *    wake catch-up do (day-boundary callback → daily cleanup → wake row
+     *    with due reviews riding the post-catchup context). Never resurrects
+     *    an exhausted retry chain: failed attempts leave audit rows, which
+     *    `shouldQueueMissedMorningFire` treats as "attempted". Suppressed
+     *    during the first {@link MISSED_FIRE_BOOT_SUPPRESSION_MS} of process
+     *    life: that window belongs to the boot catchup, whose INLINE morning
+     *    run leaves no wake row for the predicate to dedup against (a slow
+     *    pre-pass there must not look like a missed fire).
+     *
+     * Fire-and-forget; each layer owns its own error containment.
+     */
+    async runMorningSelfHeal(now) {
+        const gateReason = this.autonomousGate();
+        if (gateReason !== null) {
+            this.logGateBlock(gateReason, { timer: "morning_self_heal" });
+            return;
+        }
+        const agentDayConfig = {
+            timezone: this.config.timezone || undefined,
+            dayBoundaryHour: this.config.dayBoundaryHour,
+        };
+        // Layer 1 — hung-claim recovery.
+        try {
+            const thresholdMinutes = readMorningRoutineStallThresholdMinutes(this.db);
+            const recoverable = getRecoverableStalledMorningWake(this.db, agentDayConfig, thresholdMinutes, now);
+            if (recoverable
+                && this.countSelfHealRequeuesToday(now) < MAX_SELFHEAL_REQUEUES_PER_AGENT_DAY) {
+                const flipped = this.db
+                    .prepare(`UPDATE agent_schedule
+                SET status = 'pending', scheduled_for = ?
+              WHERE id = ? AND status = 'running'`)
+                    .run(formatSqliteDatetime(now), recoverable.id);
+                if (flipped.changes > 0) {
+                    logger.warn({
+                        scheduleId: recoverable.id,
+                        claimedAgeMinutes: recoverable.claimedAgeMinutes,
+                        thresholdMinutes,
+                    }, "Morning routine wake stuck in 'running' — flipped back to pending for re-claim");
+                    try {
+                        this.db
+                            .prepare(`INSERT INTO agent_actions
+                   (action_type, detail, result, started_at, completed_at)
+                 VALUES (?, ?, 'success', CURRENT_TIMESTAMP, CURRENT_TIMESTAMP)`)
+                            .run("morning_routine.selfheal_requeued", JSON.stringify({
+                            scheduleId: recoverable.id,
+                            claimedAgeMinutes: recoverable.claimedAgeMinutes,
+                            thresholdMinutes,
+                        }));
+                    }
+                    catch (auditErr) {
+                        logger.warn({ err: auditErr, scheduleId: recoverable.id }, "Failed to record morning_routine.selfheal_requeued audit");
+                    }
+                    this.nudgeWatcher();
+                    // Skip the alert for this tick — the recovery is the response.
+                    // The missed-fire layer cannot apply (a wake row exists).
+                    return;
+                }
+            }
+            // Recoverable-but-capped (or lost the flip race) falls through to
+            // the alert so the operator hears about a hang the self-heal is no
+            // longer allowed to chase.
+        }
+        catch (err) {
+            logger.warn({ err }, "Morning self-heal recovery step failed");
+        }
+        // Layer 2 — alert-only watchdog.
+        await this.checkMorningRoutineStall(now).catch((err) => {
+            logger.warn({ err }, "Morning routine stall watchdog threw (self-heal tick)");
+        });
+        // Layer 3 — missed boundary fire.
+        try {
+            if (Date.now() - this.startedAtMs < MISSED_FIRE_BOOT_SUPPRESSION_MS) {
+                return;
+            }
+            if (!shouldQueueMissedMorningFire(this.db, agentDayConfig, MORNING_MISSED_FIRE_GRACE_MINUTES, now)) {
+                return;
+            }
+            if (!this.isAgentEnabledForFiring("morning-routine", "morning_self_heal")) {
+                return;
+            }
+            // Mirror runWakeCatchup's morning branch: open the day properly and
+            // let any due reviews / activity scan ride the wake row's
+            // post-catchup context instead of being skipped by the dispatcher's
+            // morning-pending gate.
+            const tz = this.config.timezone || undefined;
+            const { start, end } = getAgentDayBoundsUtc(tz, this.config.dayBoundaryHour, now);
+            const dueRoutines = getDueCatchupRoutines(this.db, this.config, start, end, now).filter((routine) => this.isAgentEnabledForFiring(WAKE_CATCHUP_AGENT_SLUGS[routine] ?? routine, `${routine}_self_heal`));
+            const needsActivityScan = shouldCatchUpActivityScan(this.db, this.config, now)
+                && this.isAgentEnabledForFiring("activity-scan", "activity_scan_self_heal");
+            try {
+                if (this.onDayBoundary) {
+                    await this.onDayBoundary();
+                }
+            }
+            catch (err) {
+                logger.error({ err }, "Day boundary callback failed during morning self-heal");
+            }
+            this.dailyCleanup();
+            const queued = this.queueMorningRoutineWake("missed_cron_selfheal", {
+                postCatchupRoutines: dueRoutines,
+                postCatchupActivityScan: needsActivityScan,
+            });
+            this.nudgeWatcher();
+            logger.warn({ queued, dueRoutines, needsActivityScan }, "Morning routine fire was missed (sleep swallowed the boundary cron tick) — self-heal queued wake");
+        }
+        catch (err) {
+            logger.warn({ err }, "Morning self-heal missed-fire step failed");
+        }
+    }
+    /**
+     * Number of self-heal re-queues already performed this agent-day,
+     * counted from the `morning_routine.selfheal_requeued` audit rows the
+     * recovery layer writes. Throws propagate to the recovery layer's
+     * catch (fail-closed: an unreadable counter must not unlock unlimited
+     * re-runs).
+     */
+    countSelfHealRequeuesToday(now) {
+        const { start } = getAgentDayBoundsUtc(this.config.timezone || undefined, this.config.dayBoundaryHour, now);
+        const row = this.db
+            .prepare(`SELECT COUNT(*) AS cnt
+           FROM agent_actions
+          WHERE action_type = 'morning_routine.selfheal_requeued'
+            AND started_at >= ?`)
+            .get(start);
+        return row.cnt;
+    }
+    /**
+     * Replay cron triggers swallowed by a machine sleep (or forward clock
+     * jump). node-cron does not fire ticks whose time passed while the
+     * process was suspended, so without this a daemon that sleeps through
+     * 04:00 / 18:00 / a Friday 19:00 recovers those routines only on the
+     * next daemon RESTART (`bootstrap/catchup.ts`) — possibly days later.
+     *
+     * Reuses the boot-time catchup's decision predicates so the two paths
+     * cannot drift: `getDueCatchupRoutines` dedups against `agent_actions`,
+     * `shouldCatchUpActivityScan` replays at most the current slot, and the
+     * morning routine goes through `queueMorningRoutineWake`'s DB-backed
+     * dedup. Downstream dispatch-time gates (autonomous setup gate,
+     * morning-pending review gate) still apply.
+     *
+     * Ordering: when the morning routine has not completed for the current
+     * agent-day, the review routines and the activity scan ride along on the
+     * wake row's `postCatchupRoutines` / `postCatchupActivityScan` context
+     * (same replay mechanism the boot catchup uses) so they run AFTER the
+     * day is opened instead of being skipped by the dispatcher's
+     * pre-routine gate.
+     */
+    async runWakeCatchup(gapMs) {
+        const gapMinutes = Math.round(gapMs / 60_000);
+        const gateReason = this.autonomousGate();
+        if (gateReason !== null) {
+            this.logGateBlock(gateReason, { cron: "wake_catchup", gapMinutes });
+            return;
+        }
+        const now = new Date();
+        const tz = this.config.timezone || undefined;
+        const { start, end } = getAgentDayBoundsUtc(tz, this.config.dayBoundaryHour, now);
+        const dueRoutines = getDueCatchupRoutines(this.db, this.config, start, end, now).filter((routine) => this.isAgentEnabledForFiring(WAKE_CATCHUP_AGENT_SLUGS[routine] ?? routine, `${routine}_wake_catchup`));
+        const needsActivityScan = shouldCatchUpActivityScan(this.db, this.config, now)
+            && this.isAgentEnabledForFiring("activity-scan", "activity_scan_wake_catchup");
+        if (!morningRoutineRanToday(this.db, { timezone: tz, dayBoundaryHour: this.config.dayBoundaryHour }, now)) {
+            // Slept across the day boundary (or the morning routine never
+            // succeeded today) — re-run the full 04:00 flow. The wake row
+            // dedups against an already-pending/running morning run, merging
+            // the post-catchup context instead of double-firing.
+            if (!this.isAgentEnabledForFiring("morning-routine", "morning_routine_wake_catchup")) {
+                return;
+            }
+            try {
+                if (this.onDayBoundary) {
+                    await this.onDayBoundary();
+                }
+            }
+            catch (err) {
+                logger.error({ err }, "Day boundary callback failed during wake catch-up");
+            }
+            this.dailyCleanup();
+            const queued = this.queueMorningRoutineWake("wake_catchup", {
+                postCatchupRoutines: dueRoutines,
+                postCatchupActivityScan: needsActivityScan,
+            });
+            this.nudgeWatcher();
+            logger.info({ gapMinutes, queued, dueRoutines, needsActivityScan }, "Wake catch-up queued morning routine");
+            return;
+        }
+        for (const routine of dueRoutines) {
+            logger.info({ routine, gapMinutes }, "Wake catch-up replaying missed routine");
+            this.emitRoutine(routine);
+        }
+        if (needsActivityScan && this.onActivityScan) {
+            logger.info({ gapMinutes }, "Wake catch-up triggering missed activity scan");
+            void Promise.resolve(this.onActivityScan("wake_catchup")).catch((err) => {
+                logger.warn({ err }, "Wake catch-up activity scan failed");
+            });
+        }
+        if (dueRoutines.length === 0 && !needsActivityScan) {
+            logger.info({ gapMinutes }, "Wake catch-up: nothing missed");
+        }
+    }
     start() {
         this.setupRecurringJobs();
         this.startScheduleWatcher();
+        this.wakeDetector.start();
+        this.morningSelfHealTimer = setInterval(() => {
+            void this.runMorningSelfHeal(new Date()).catch((err) => {
+                logger.warn({ err }, "Morning self-heal tick threw");
+            });
+        }, MORNING_SELF_HEAL_INTERVAL_MS);
+        this.morningSelfHealTimer.unref?.();
         logger.info("Scheduler started");
     }
     stop() {
         this.shutdown = true;
+        this.wakeDetector.stop();
+        if (this.morningSelfHealTimer) {
+            clearInterval(this.morningSelfHealTimer);
+            this.morningSelfHealTimer = null;
+        }
         // Wake up the ScheduleWatcher's poll sleep so the loop returns
         // immediately instead of waiting for the next interval tick. The
         // sleepInterruptible body re-checks `shutdown` before re-entering
@@ -647,17 +973,16 @@ export class AgentScheduler {
         // node-cron doesn't directly support "last day of month",
         // so we run daily at 18:00 and check if tomorrow is the 1st.
         //
-        // Default OFF pre-release (see runtime-settings.ts:monthlyReviewEnabled).
-        // The cron is always registered, but the callback consults
-        // `this.config.monthlyReviewEnabled` at fire time so a runtime PATCH
-        // takes effect on the next month-end without restart — that is also
-        // why this key is intentionally absent from SCHEDULE_KEYS in
-        // dashboard/config.ts (no cron rebuild needed). The routine itself
-        // (task-flow, context-builder branch, retention coupling) stays in
-        // tree as a concept pending the Mirror+Prune redesign.
+        // Default OFF pre-release: the monthly-review AGENT row ships
+        // `enabled: false`, and `isAgentEnabledForFiring` below is the single
+        // fire-time switch (AGENTS_HUB_REDESIGN_PLAN.md §2 — the legacy
+        // `monthlyReviewEnabled` config gate was unified into it; a one-time
+        // boot reconcile carries an operator's old `true` forward). A toggle
+        // takes effect on the next month-end without restart or cron rebuild.
+        // The routine itself (task-flow, context-builder branch, retention
+        // coupling) stays in tree as a concept pending the Mirror+Prune
+        // redesign.
         const monthlyJob = cron.schedule("0 18 * * *", () => {
-            if (!this.config.monthlyReviewEnabled)
-                return;
             // Check if tomorrow (in configured timezone) is the 1st
             const tomorrow = new Date();
             tomorrow.setDate(tomorrow.getDate() + 1);
@@ -725,9 +1050,19 @@ export class AgentScheduler {
             }
         }, { timezone: tz });
         this.cronJobs.push(browserDigestJob);
-        if (this.config.hourlyCheckEnabled) {
-            const hourlyExpr = buildHourlyCronExpr(this.config.hourlyCheckIntervalMinutes, this.config.hourlyCheckActiveStartHour, this.config.hourlyCheckActiveEndHour);
-            const hourlyJob = cron.schedule(hourlyExpr, () => {
+        {
+            // Cadence is owned by the activity-scan AGENT ROW (metadata_json.
+            // runtime_window, edited via PATCH /api/agents/activity-scan) with the
+            // legacy `activityScan*` config keys as per-field fallback —
+            // AGENTS_HUB_REDESIGN_PLAN.md §2. Resolved once at registration; the
+            // agents PATCH route triggers `reloadCrons()` on a cadence change, so
+            // the closure below never goes stale. The job is registered
+            // UNCONDITIONALLY: `agents.enabled` (fire-time `isAgentEnabledForFiring`
+            // gate below) is the single on/off switch — the legacy
+            // `activityScanEnabled` registration gate was unified into it.
+            const activityScanCadence = resolveActivityScanCadence(getRuntimeWindow(this.db, "activity-scan"), this.config);
+            const activityScanExpr = buildActivityScanCronExpr(activityScanCadence.intervalMinutes, activityScanCadence.activeStartHour, activityScanCadence.activeEndHour);
+            const activityScanJob = cron.schedule(activityScanExpr, () => {
                 const now = new Date();
                 // Pull both hour and minute from the canonical timezone helper
                 // so the day-boundary skip and the interval gate observe the
@@ -744,22 +1079,34 @@ export class AgentScheduler {
                 // of each agent-day lands at the start of the active window —
                 // critical for intervals near or equal to the window length.
                 // Divisor-of-60 cases short-circuit inside the helper.
-                if (!shouldFireHourlyTickAt(local.hours, local.minutes, this.config.hourlyCheckIntervalMinutes, this.config.hourlyCheckActiveStartHour)) {
+                if (!shouldFireActivityScanTickAt(local.hours, local.minutes, activityScanCadence.intervalMinutes, activityScanCadence.activeStartHour)) {
                     return;
                 }
+                // Self-tuning auto-revert monitor — ahead of BOTH the per-agent
+                // enabled gate and the autonomous setup gate below: rollback
+                // safety must survive the owner disabling the activity-scan
+                // Agent (a plausible cost-saving move while a tuned knob sits
+                // unverified) and a degraded/setup-gated daemon. It is pure
+                // daemon code (no LLM dispatch), owns its own 1/day throttle,
+                // and is a no-op until the actuator has written ledger entries.
+                if (this.onSelfTuningRevertMonitor) {
+                    void this.onSelfTuningRevertMonitor().catch((err) => {
+                        logger.warn({ err }, "Self-tuning revert monitor failed");
+                    });
+                }
                 // Per-built-in enabled gate, AFTER the interval gate so a
                 // per-minute non-firing tick never inflates the suppressed count.
-                if (!this.isAgentEnabledForFiring("hourly-check", "hourly_check"))
+                if (!this.isAgentEnabledForFiring("activity-scan", "activity_scan"))
                     return;
-                // triggerHourlyCheck has its own setup gate, but short-circuit
+                // triggerActivityScan has its own setup gate, but short-circuit
                 // here to avoid the in-progress flag toggling for no reason.
                 const gateReason = this.autonomousGate();
                 if (gateReason !== null) {
-                    this.logGateBlock(gateReason, { cron: "hourly_check" });
+                    this.logGateBlock(gateReason, { cron: "activity_scan" });
                     return;
                 }
-                // Phase 4 auth probe runs BEFORE the hourly check so that the
-                // observation-threshold gate (which can skip `onHourlyCheck`
+                // Phase 4 auth probe runs BEFORE the activity scan so that the
+                // observation-threshold gate (which can skip `onActivityScan`
                 // entirely when there's no pending user activity) does not
                 // also stall auth health detection. The probe owns its own
                 // morning-routine / probe-disabled gating; we only respect
@@ -771,16 +1118,16 @@ export class AgentScheduler {
                 }
                 // Morning-routine stall watchdog. Runs alongside the auth probe
                 // because both are observability hooks that should fire even
-                // when the hourly check itself gets gated (e.g., the gate
+                // when the activity scan itself gets gated (e.g., the gate
                 // skip is the *symptom* the watchdog needs to catch).
                 void this.checkMorningRoutineStall(now).catch((err) => {
                     logger.warn({ err }, "Morning routine stall watchdog threw");
                 });
-                if (this.onHourlyCheck) {
-                    void this.onHourlyCheck("cron");
+                if (this.onActivityScan) {
+                    void this.onActivityScan("cron");
                 }
             }, { timezone: tz });
-            this.cronJobs.push(hourlyJob);
+            this.cronJobs.push(activityScanJob);
         }
         // P22 §6.3, §6.4 — skill curation. Registered only when the operator
         // has opted in via /settings/self-learning (`enabled=true`). Always
@@ -814,12 +1161,15 @@ export class AgentScheduler {
             }, { timezone: tz });
             this.cronJobs.push(skillCurationJob);
         }
-        logger.info({
-            morningHour: this.config.dayBoundaryHour,
-            timezone: tz ?? "system",
-            hourlyCheckEnabled: this.config.hourlyCheckEnabled,
-            hourlyCheckIntervalMinutes: this.config.hourlyCheckIntervalMinutes,
-        }, "Recurring cron jobs configured");
+        {
+            const cadence = resolveActivityScanCadence(getRuntimeWindow(this.db, "activity-scan"), this.config);
+            logger.info({
+                morningHour: this.config.dayBoundaryHour,
+                timezone: tz ?? "system",
+                activityScanIntervalMinutes: cadence.intervalMinutes,
+                activityScanActiveHours: `${cadence.activeStartHour}-${cadence.activeEndHour}`,
+            }, "Recurring cron jobs configured");
+        }
     }
     emitRoutine(routineName, data) {
         const event = {
@@ -855,7 +1205,7 @@ export class AgentScheduler {
             routine: "morning_routine",
             source,
             postCatchupRoutines: options?.postCatchupRoutines ?? [],
-            postCatchupHourlyCheck: options?.postCatchupHourlyCheck ?? false,
+            postCatchupActivityScan: options?.postCatchupActivityScan ?? false,
             importance: "low",
         });
         const insertTxn = this.db.transaction(() => {
@@ -875,13 +1225,19 @@ export class AgentScheduler {
                         : []),
                     ...(options?.postCatchupRoutines ?? []),
                 ]));
-                const mergedHourlyCheck = existingContext.postCatchupHourlyCheck === true ||
-                    options?.postCatchupHourlyCheck === true;
+                const mergedActivityScan = existingContext.postCatchupActivityScan === true ||
+                    options?.postCatchupActivityScan === true;
+                // Spread the existing context FIRST so keys this merge doesn't
+                // know about survive — in particular the ScheduleWatcher's
+                // `claimedAt` stamp on a running row: dropping it would blind
+                // the self-heal recovery predicate exactly when the 04:00 cron
+                // merges into a hung overnight run.
                 const mergedContext = {
+                    ...existingContext,
                     routine: "morning_routine",
                     source: existingContext.source ?? source,
                     postCatchupRoutines: mergedRoutines,
-                    postCatchupHourlyCheck: mergedHourlyCheck,
+                    postCatchupActivityScan: mergedActivityScan,
                     importance: "low",
                 };
                 // Bump `scheduled_for` forward when the new caller's NOW lies
@@ -990,6 +1346,25 @@ export class AgentScheduler {
                             .run(row.id);
                         if (result.changes === 0)
                             continue;
+                        // Stamp the claim time on morning-routine wake rows. This is
+                        // the staleness signal the self-heal recovery predicate
+                        // (`getRecoverableStalledMorningWake`) measures from —
+                        // `created_at` and `scheduled_for` both lie after sleeps and
+                        // dedup merges. Best-effort and morning-scoped: a failure
+                        // here only demotes that row from auto-recovery to the
+                        // alert-only watchdog path.
+                        try {
+                            this.db
+                                .prepare(`UPDATE agent_schedule
+                      SET task_context = json_set(COALESCE(task_context, '{}'), '$.claimedAt', ?)
+                    WHERE id = ?
+                      AND json_valid(COALESCE(task_context, '{}'))
+                      AND json_extract(task_context, '$.routine') = 'morning_routine'`)
+                                .run(formatSqliteDatetime(new Date()), row.id);
+                        }
+                        catch (stampErr) {
+                            logger.warn({ err: stampErr, taskId: row.id }, "Failed to stamp claimedAt on claimed schedule row");
+                        }
                         // Per-row try/catch: if the row body throws (e.g. malformed
                         // task_context JSON), flip the claim to 'failed' so the row
                         // doesn't stay 'running' forever and the watcher can move on.
@@ -1073,57 +1448,10 @@ export class AgentScheduler {
                             // delay; the row's status is reverted to `pending` so
                             // the next ScheduleWatcher tick re-evaluates.
                             if (row.task_type === "browser_task") {
-                                const fireAt = new Date();
                                 const respectQuietHours = this.config.browserTaskRespectQuietHours !== false;
-                                if (respectQuietHours) {
-                                    const quietHoursWindow = {
-                                        start: this.config.quietHoursStart,
-                                        end: this.config.quietHoursEnd,
-                                        timezone: this.config.timezone || undefined,
-                                    };
-                                    if (isInQuietHoursAt(fireAt, quietHoursWindow)) {
-                                        const deferUntilMs = nextQuietHoursEndMs(fireAt, quietHoursWindow);
-                                        if (deferUntilMs !== null) {
-                                            const deferredFor = formatSqliteDatetime(new Date(deferUntilMs));
-                                            this.db
-                                                .prepare(`UPDATE agent_schedule
-                              SET scheduled_for = ?, status = 'pending'
-                            WHERE id = ?`)
-                                                .run(deferredFor, row.id);
-                                            try {
-                                                this.db
-                                                    .prepare(`INSERT INTO agent_actions
-                               (action_type, detail, result, started_at, completed_at)
-                             VALUES (?, ?, 'success', CURRENT_TIMESTAMP, CURRENT_TIMESTAMP)`)
-                                                    .run("browser_task.deferred_for_quiet_hours", JSON.stringify({
-                                                    scheduleId: row.id,
-                                                    originalScheduledFor: row.scheduled_for,
-                                                    deferredUntil: deferredFor,
-                                                    quietHoursStart: this.config.quietHoursStart,
-                                                    quietHoursEnd: this.config.quietHoursEnd,
-                                                }));
-                                            }
-                                            catch (auditErr) {
-                                                /* c8 ignore start -- defensive against schema partials */
-                                                logger.warn({ err: auditErr, scheduleId: row.id }, "Failed to record browser_task.deferred_for_quiet_hours audit");
-                                                /* c8 ignore stop */
-                                            }
-                                            logger.info({
-                                                scheduleId: row.id,
-                                                deferredUntil: deferredFor,
-                                                quietHoursStart: this.config.quietHoursStart,
-                                                quietHoursEnd: this.config.quietHoursEnd,
-                                            }, "scheduled.browser_task deferred for quiet hours");
-                                            continue;
-                                        }
-                                        // `nextQuietHoursEndMs` returning null inside a quiet-
-                                        // hours predicate that just returned true would mean
-                                        // a 24-hour window — the runtime-settings schema
-                                        // disallows this (equal start/end short-circuits the
-                                        // predicate), so it cannot occur in normal operation.
-                                        // Fall through to dispatch rather than re-deferring
-                                        // forever.
-                                    }
+                                if (respectQuietHours &&
+                                    this.deferClaimedRowForQuietHours(row, "browser_task.deferred_for_quiet_hours")) {
+                                    continue;
                                 }
                                 const base = createEvent({
                                     type: "scheduled.browser_task",
@@ -1151,12 +1479,64 @@ export class AgentScheduler {
                                 logger.info({ scheduleId: row.id, taskType: row.task_type }, "Scheduled browser-task dispatched");
                                 continue;
                             }
+                            // BACKGROUND_TASK_RUNNER_DESIGN.md §4.2 — generic background
+                            // task firing at its scheduled time. Body lives in
+                            // `task_context` (frozen at schedule time); the dispatcher's
+                            // `scheduled.background_task` handler creates the row at fire
+                            // time and hands off to the runner. No quiet-hours deferral
+                            // on dispatch — the worker may run at any hour; the DELIVERY
+                            // boundary quiet-hours-gates the owner-facing DM (§10.6).
+                            if (row.task_type === "background_task") {
+                                const base = createEvent({
+                                    type: "scheduled.background_task",
+                                    source: row.task_type,
+                                    priority: EventPriority.NORMAL,
+                                });
+                                let parsedContext;
+                                try {
+                                    parsedContext = JSON.parse(row.task_context ?? "{}");
+                                }
+                                catch (parseErr) {
+                                    logger.error({ err: parseErr, scheduleId: row.id }, "scheduled.background_task: task_context JSON parse failed — marking row failed");
+                                    this.db
+                                        .prepare("UPDATE agent_schedule SET status = 'failed' WHERE id = ? AND status = 'running'")
+                                        .run(row.id);
+                                    continue;
+                                }
+                                const event = {
+                                    ...base,
+                                    taskContext: parsedContext,
+                                    correlationId: row.correlation_id ?? base.correlationId,
+                                    scheduleId: row.id,
+                                };
+                                await this.eventBus.put(event);
+                                logger.info({ scheduleId: row.id, taskType: row.task_type }, "Scheduled background-task dispatched");
+                                continue;
+                            }
+                            const parsedTaskContext = JSON.parse(row.task_context ?? "{}");
+                            // QUIET_HOURS_HARDENING_PLAN.md §6 — per-row opt-in quiet-hours
+                            // deferral for user-Agent firings. The Agent loader copies the
+                            // definition's `schedule.defer_in_quiet_hours: true` into the
+                            // recurring row's task_context and `generateNextScheduleRow`
+                            // spreads it into every materialised row, so the check is
+                            // row-local (no `agents` join). The whole RUN moves past the
+                            // quiet window (fresh data at delivery time, no wasted 03:00
+                            // session), mirroring the browser_task deferral above. Built-ins
+                            // fire outside `recurring_schedules` and never carry the flag;
+                            // manual run-now rows omit it too (an explicit "run now" click
+                            // must fire immediately).
+                            if (row.task_type === "agent.task" &&
+                                parsedTaskContext.defer_in_quiet_hours === true &&
+                                this.deferClaimedRowForQuietHours(row, "agent.task.deferred_for_quiet_hours", typeof parsedTaskContext.agent_id === "string"
+                                    ? parsedTaskContext.agent_id
+                                    : null)) {
+                                continue;
+                            }
                             const base = createEvent({
                                 type: "scheduled.task",
                                 source: row.task_type,
                                 priority: EventPriority.NORMAL,
                             });
-                            const parsedTaskContext = JSON.parse(row.task_context ?? "{}");
                             // WIKI_BUILDER_DESIGN.md §3.4-bis — bang-spawned approval rows
                             // (today: wiki.compile via `!compile full` above threshold;
                             // generalisable to any future bang→approval path) carry a
@@ -1243,6 +1623,83 @@ export class AgentScheduler {
         };
         void loop();
     }
+    /**
+     * Quiet-hours deferral for a claimed `agent_schedule` row (shared by the
+     * `browser_task` always-on-by-config path and the `agent.task` per-row
+     * opt-in, QUIET_HOURS_HARDENING_PLAN.md §6). When the current wall-clock
+     * instant falls inside the configured quiet-hours window, the row is pushed
+     * forward to the next quiet-hours-end boundary (status reverted to
+     * `pending` so the next ScheduleWatcher tick re-evaluates), one
+     * `agent_actions` audit row is written per deferral so the user can see the
+     * delay, and `true` is returned. Returns `false` when outside the window —
+     * or when `nextQuietHoursEndMs` cannot resolve a boundary, which inside a
+     * quiet-hours predicate that just returned true would mean a 24-hour
+     * window; the runtime-settings schema disallows this (equal start/end
+     * short-circuits the predicate), so it cannot occur in normal operation.
+     * Falling through to dispatch beats re-deferring forever.
+     *
+     * `agentId` (the owning user Agent's slug from `task_context.agent_id`)
+     * stamps the audit row's `agent_id` column so the deferral is attributable
+     * per Agent; the browser_task path has no owning Agent and passes none.
+     */
+    deferClaimedRowForQuietHours(row, actionType, agentId = null) {
+        const fireAt = new Date();
+        const quietHoursWindow = {
+            start: this.config.quietHoursStart,
+            end: this.config.quietHoursEnd,
+            timezone: this.config.timezone || undefined,
+        };
+        if (!isInQuietHoursAt(fireAt, quietHoursWindow))
+            return false;
+        const deferUntilMs = nextQuietHoursEndMs(fireAt, quietHoursWindow);
+        if (deferUntilMs === null)
+            return false;
+        const deferredFor = formatSqliteDatetime(new Date(deferUntilMs));
+        // `quiet_hours_deferred` marks the row as ACTUALLY deferred (vs merely
+        // carrying the `defer_in_quiet_hours` opt-in on a future cron slot) so a
+        // quiet-hours config change can retime exactly these rows
+        // (`retimeDeferredRunRows` in db/deferred-dm.ts, the sibling of the
+        // Phase-1 deferred-DM retime). Invalid task_context JSON is left
+        // untouched — stamping must never destroy a browser_task's frozen body.
+        this.db
+            .prepare(`UPDATE agent_schedule
+            SET scheduled_for = ?, status = 'pending',
+                task_context = CASE
+                  WHEN task_context IS NULL
+                    THEN json_object('quiet_hours_deferred', json('true'))
+                  WHEN json_valid(task_context)
+                    THEN json_set(task_context, '$.quiet_hours_deferred', json('true'))
+                  ELSE task_context
+                END
+          WHERE id = ?`)
+            .run(deferredFor, row.id);
+        try {
+            this.db
+                .prepare(`INSERT INTO agent_actions
+             (action_type, detail, result, agent_id, started_at, completed_at)
+           VALUES (?, ?, 'success', ?, CURRENT_TIMESTAMP, CURRENT_TIMESTAMP)`)
+                .run(actionType, JSON.stringify({
+                scheduleId: row.id,
+                originalScheduledFor: row.scheduled_for,
+                deferredUntil: deferredFor,
+                quietHoursStart: this.config.quietHoursStart,
+                quietHoursEnd: this.config.quietHoursEnd,
+            }), agentId);
+        }
+        catch (auditErr) {
+            /* c8 ignore start -- defensive against schema partials */
+            logger.warn({ err: auditErr, scheduleId: row.id, actionType }, "Failed to record quiet-hours deferral audit");
+            /* c8 ignore stop */
+        }
+        logger.info({
+            scheduleId: row.id,
+            taskType: row.task_type,
+            deferredUntil: deferredFor,
+            quietHoursStart: this.config.quietHoursStart,
+            quietHoursEnd: this.config.quietHoursEnd,
+        }, "Scheduled row deferred for quiet hours");
+        return true;
+    }
     /**
      * Sleep for `ms` milliseconds, but resolve early when `stop()` or
      * `nudgeWatcher()` fire. Used by the ScheduleWatcher between polls so