@aitne/daemon 0.1.10 → 0.1.11

package/dist/core/scheduler.d.ts

@@ -4,7 +4,37 @@ import type { EventBus } from "./event-bus.js";
 import type { MessageDelivery } from "../adapters/message-hub.js";
 import type { AgentEnabledCache } from "./agents/loader.js";
 /**
- * Build the cron expression that drives the hourly check.
+ * 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 declare const MORNING_SELF_HEAL_INTERVAL_MS: number;
+/**
+ * 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 declare 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 declare const MISSED_FIRE_BOOT_SUPPRESSION_MS: number;
+/**
+ * Build the cron expression that drives the activity scan.
  *
  * Two regimes:
  *
@@ -17,7 +47,7 @@ import type { AgentEnabledCache } from "./agents/loader.js";
  * 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
@@ -29,9 +59,9 @@ import type { AgentEnabledCache } from "./agents/loader.js";
  *
  * 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 declare function buildHourlyCronExpr(intervalMinutes: number, startHour: number, endHourExclusive: number): string;
+export declare function buildActivityScanCronExpr(intervalMinutes: number, startHour: number, endHourExclusive: number): string;
 /**
  * Returns true when a minute-tick of the hourly cron should actually fire.
  *
@@ -50,7 +80,7 @@ export declare function buildHourlyCronExpr(intervalMinutes: number, startHour:
  * so the divisor early-return doesn't change behavior — it's just
  * explicit about which path the cron expression itself handles.
  */
-export declare function shouldFireHourlyTickAt(localHour: number, localMinute: number, intervalMinutes: number, activeStartHour: number): boolean;
+export declare function shouldFireActivityScanTickAt(localHour: number, localMinute: number, intervalMinutes: number, activeStartHour: number): boolean;
 /**
  * Cron expression for the morning user-profile sweep: 10 min before the
  * day boundary, wrapping backward across midnight. For the default
@@ -109,12 +139,12 @@ export declare class AgentScheduler {
     private noFutureTasksWarned;
     private onDayBoundary;
     private sendDm;
-    private onHourlyCheck;
+    private onActivityScan;
     /**
      * 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.
@@ -122,10 +152,24 @@ export declare 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`.
      */
     private onAuthProbe;
+    /**
+     * 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.
+     */
+    private onSelfTuningRevertMonitor;
     /**
      * B-004 Phase 2a — nightly context-index reconciler callback (§4.1).
      * Fires at 03:45 local (dayBoundaryHour - 15 min) via an internal cron
@@ -201,6 +245,25 @@ export declare class AgentScheduler {
     private nudgeSeq;
     private observedSeq;
     private sleepWaiter;
+    /**
+     * Detects machine sleep / forward clock jumps and replays the cron
+     * triggers the sleep swallowed (node-cron never fires missed ticks).
+     * See {@link runWakeCatchup}.
+     */
+    private readonly wakeDetector;
+    /**
+     * 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.
+     */
+    private morningSelfHealTimer;
+    /**
+     * 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.
+     */
+    private startedAtMs;
     constructor(eventBus: EventBus, db: Database.Database, config: AgentConfig);
     /**
      * Register a callback that runs at the day boundary (4 AM) BEFORE
@@ -212,14 +275,21 @@ export declare class AgentScheduler {
      * When a task_type='dm' row is due, the message is sent directly without an agent.
      */
     setSendDmCallback(fn: (message: string, platforms?: string[]) => Promise<MessageDelivery[]>): void;
-    setHourlyCheckCallback(fn: (source: string) => Promise<unknown>): void;
+    setActivityScanCallback(fn: (source: string) => Promise<unknown>): void;
     /**
      * 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: () => Promise<unknown>): void;
+    /**
+     * 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: () => Promise<unknown>): void;
     /**
      * Register the context-index reconciler cron callback. Called every
      * night at 03:45 local; the callback is expected to be fire-and-forget
@@ -284,9 +354,9 @@ export declare 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
@@ -307,6 +377,75 @@ export declare class AgentScheduler {
      * cron-callback exception.
      */
     private checkMorningRoutineStall;
+    /**
+     * 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.
+     */
+    private runMorningSelfHeal;
+    /**
+     * 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).
+     */
+    private countSelfHealRequeuesToday;
+    /**
+     * 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.
+     */
+    private runWakeCatchup;
     start(): void;
     stop(): void;
     /**
@@ -347,7 +486,7 @@ export declare class AgentScheduler {
      */
     queueMorningRoutineWake(source: string, options?: {
         postCatchupRoutines?: string[];
-        postCatchupHourlyCheck?: boolean;
+        postCatchupActivityScan?: boolean;
     }): {
         inserted: boolean;
         existingId?: number;
@@ -360,6 +499,26 @@ export declare class AgentScheduler {
      * UPDATE ... SET status='running' WHERE status='pending' succeeds.
      */
     private startScheduleWatcher;
+    /**
+     * 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.
+     */
+    private deferClaimedRowForQuietHours;
     /**
      * Sleep for `ms` milliseconds, but resolve early when `stop()` or
      * `nudgeWatcher()` fire. Used by the ScheduleWatcher between polls so