@aitne/daemon 0.1.10 → 0.1.11

package/dist/adapters/telegram-adapter.js

@@ -37,6 +37,15 @@ export class TelegramAdapter {
     attachmentStore;
     bot = null;
     botInfo = null;
+    /**
+     * Non-null when the long-poll loop has died. telegraf's `launch()`
+     * promise stays pending while polling runs and settles when the loop
+     * exits: it self-retries network errors / 429 / 5xx internally, but any
+     * other failure (401 invalid token, 409 conflicting consumer, an
+     * unexpected throw) kills the loop for good. Without observing that
+     * settlement the daemon would sit "connected" while receiving nothing.
+     */
+    pollingDeadError = null;
     /** Active pairing challenge (null when pairing isn't in progress). */
     pairingChallenge = null;
     /** Buffers for Telegram media albums (media_group_id → accumulated items). */
@@ -134,8 +143,26 @@ export class TelegramAdapter {
                 logger.error({ err }, "telegram message handler threw");
             });
         });
-        // Start long polling (non-blocking)
-        this.bot.launch({ dropPendingUpdates: true });
+        // Start long polling (non-blocking). The launch() promise settles only
+        // when the poll loop exits — track that settlement so a dead loop is
+        // observable instead of becoming an unhandled rejection with the
+        // adapter silently deaf until daemon restart.
+        this.pollingDeadError = null;
+        const bot = this.bot;
+        bot.launch({ dropPendingUpdates: true }).then(() => {
+            // Resolves on stop() (AbortError path). If we did NOT initiate the
+            // stop, the loop ended on its own — mark the adapter down.
+            if (this.bot === bot) {
+                this.pollingDeadError = "Telegram polling loop exited unexpectedly";
+                logger.error("Telegram polling loop exited unexpectedly");
+            }
+        }, (err) => {
+            if (this.bot === bot) {
+                this.pollingDeadError =
+                    err instanceof Error ? err.message : String(err);
+                logger.error({ err }, "Telegram polling loop died");
+            }
+        });
         logger.info({ botUsername: this.botInfo?.username }, "Telegram adapter connected (Long Polling)");
     }
     async stop() {
@@ -153,6 +180,18 @@ export class TelegramAdapter {
     async resolveUserChannel() {
         return this.mutableOwnerId;
     }
+    /**
+     * Live long-poll liveness for the adapter watchdog. "ok" means the
+     * polling loop is still running (telegraf retries transient network /
+     * 429 / 5xx failures internally, so an offline laptop stays "ok" and
+     * recovers on its own); "down" means the loop has exited and only a
+     * full stop→start cycle brings messages back.
+     */
+    getConnectionState() {
+        if (!this.bot)
+            return "unknown";
+        return this.pollingDeadError === null ? "ok" : "down";
+    }
     async sendMessage(params) {
         if (!this.bot) {
             throw new Error("Telegram bot not started");

package/dist/adapters/types.d.ts

@@ -24,6 +24,20 @@ export interface NotificationRuntimeStatus {
     runtimeState: "ok" | "error" | "connecting";
     error: string | null;
 }
+/**
+ * Live transport-level connection state, read by the adapter watchdog
+ * (`adapter-watchdog.ts`).
+ *
+ *  - `"ok"`      — the underlying socket / poll loop is alive right now.
+ *  - `"down"`    — the library reports the connection dead (socket closed,
+ *                  poll loop exited, gateway session invalidated). The
+ *                  watchdog restarts the adapter after consecutive `"down"`
+ *                  observations.
+ *  - `"unknown"` — liveness cannot be determined (adapter not started, or
+ *                  the library's internals are not introspectable). The
+ *                  watchdog takes no action on `"unknown"`.
+ */
+export type AdapterConnectionState = "ok" | "down" | "unknown";
 /**
  * MessageAdapter — platform-specific messaging integration.
  *
@@ -50,6 +64,12 @@ export interface MessageAdapter {
      * generic registered/error state tracked by MessageHub.
      */
     getNotificationRuntimeStatus?(): NotificationRuntimeStatus;
+    /**
+     * Cheap synchronous probe of the live transport state, for the adapter
+     * watchdog. Adapters that cannot introspect their library (or manage
+     * their own reconnection, like WhatsApp) omit this.
+     */
+    getConnectionState?(): AdapterConnectionState;
     /** Start receiving messages (connects to platform) */
     start(): Promise<void>;
     /** Graceful shutdown */

package/dist/adapters/whatsapp-adapter.d.ts

@@ -110,9 +110,17 @@ export declare class WhatsAppAdapter implements MessageAdapter {
      * watch's async connectivity probe) is in flight, and we have NOT
      * permanently given up. Lets the status accessors report "connecting"
      * during the brief timer-less window of a sustained probe instead of
-     * flashing a red error. Cleared on open / give-up / logout / stop.
+     * flashing a red error. Cleared on open / logout / stop.
      */
     private reconnecting;
+    /**
+     * True while the slow app-layer watch is armed (fast phase exhausted on a
+     * non-network close). Unlike the network-class sustained watch, this state
+     * IS surfaced as an error by {@link getStatusError} — WhatsApp is actively
+     * rejecting us and the user may want to act (re-pair, check the dashboard)
+     * rather than wait out the ~30-min retry cadence.
+     */
+    private appLayerWatch;
     /**
      * Connectivity probe used by the sustained watch. Injectable so tests can
      * drive the offline / back-online transitions without real DNS; production
@@ -141,9 +149,10 @@ export declare class WhatsAppAdapter implements MessageAdapter {
      *   - `logged_out` → terminal, surface the error.
      *   - `disconnected` → recovery is in flight when a reconnect timer is
      *     pending OR a sustained-watch attempt is mid-probe ({@link reconnecting}
-     *     covers the brief timer-less DNS window). Only when neither holds have
-     *     we permanently given up (app-layer rejection past the fast cap) — a
-     *     real, user-actionable failure.
+     *     covers the brief timer-less DNS window) — EXCEPT the slow app-layer
+     *     watch ({@link appLayerWatch}), which is surfaced even though a timer
+     *     is pending: WhatsApp is actively rejecting us and the ~30-min retry
+     *     cadence is slow enough that the user may want to act first.
      */
     getStatusError(): string | null;
     getNotificationRuntimeStatus(): NotificationRuntimeStatus;
@@ -233,9 +242,13 @@ export declare class WhatsAppAdapter implements MessageAdapter {
      *     on its own instead of wedging in an error state.
      *
      * If the fast phase exhausts on a *non*-network close (WhatsApp rejecting us
-     * at the app layer — bad version, bad session, throttle) we stop and surface
-     * an error: hammering a relay that keeps closing us is the fast path to an
-     * IP-level block and needs operator action (re-pair / wait it out).
+     * at the app layer — bad version, bad session, throttle) we drop into the
+     * slow **app-layer watch**: same timer machinery as the sustained watch but
+     * on a much longer cadence ({@link RECONNECT_APP_LAYER_WATCH_DELAY_MS}) and
+     * with the error surfaced to the dashboard. Hammering a relay that keeps
+     * closing us is the fast path to an IP-level block, but a permanent stop
+     * would wedge the adapter until daemon restart over conditions that
+     * routinely clear on their own (throttles, server restarts, version churn).
      */
     private scheduleReconnect;
     /**
@@ -252,6 +265,12 @@ export declare class WhatsAppAdapter implements MessageAdapter {
      * `exhausted && !network` in {@link scheduleReconnect} and falsely give up.
      * A fresh fast phase gives those handshake closes their proper retry budget
      * (a clean `open` doesn't fire before a 515, so we can't rely on it here).
+     *
+     * The app-layer watch (`appLayerWatch=true`) reuses this path but grants
+     * only {@link RECONNECT_APP_LAYER_RETRY_BUDGET} fast attempts instead of a
+     * full fresh phase: the network never went away, so a still-broken app
+     * layer should fall back into the slow watch after a short burst rather
+     * than re-earning ten rapid connects every watch tick.
      */
     private runReconnectAttempt;
     /**

package/dist/adapters/whatsapp-adapter.js

@@ -39,14 +39,28 @@ const WA_VERSION_TTL_MS = 12 * 60 * 60 * 1000;
  *     networks) drops into the sustained connectivity watch below, which never
  *     gives up and recovers on its own once the network returns;
  *   - any other close (WhatsApp rejected us at the app layer — bad version,
- *     bad session, throttle) surfaces an error and stops, because hammering a
- *     relay that keeps closing us is the fast path to an IP-level ban.
+ *     bad session, throttle) surfaces an error and drops into the slow
+ *     app-layer watch below — hammering a relay that keeps closing us is the
+ *     fast path to an IP-level ban, but stopping forever turns a transient
+ *     server-side condition into a wedge only a daemon restart clears.
  */
 const RECONNECT_INITIAL_DELAY_MS = 1_000;
 const RECONNECT_MAX_DELAY_MS = 60_000;
 const RECONNECT_BACKOFF_FACTOR = 2;
 const RECONNECT_JITTER_MS = 500;
 const RECONNECT_MAX_ATTEMPTS = 10;
+/**
+ * App-layer watch tunables. Once the fast phase exhausts on a *non*-network
+ * close (WhatsApp rejecting us at the app layer), we retry on this long
+ * cadence instead of giving up: throttles lift, server-side restarts settle,
+ * and version rejections clear after the cache refetch. Each watch tick
+ * grants only {@link RECONNECT_APP_LAYER_RETRY_BUDGET} fast attempts (enough
+ * for the 515 → version-refetch → connect handshake chain) rather than a full
+ * fresh fast phase, keeping the worst-case connect rate low enough to pose no
+ * ban risk while still recovering unattended.
+ */
+const RECONNECT_APP_LAYER_WATCH_DELAY_MS = 30 * 60_000;
+const RECONNECT_APP_LAYER_RETRY_BUDGET = 3;
 /**
  * Sustained-watch tunables. Once the fast phase exhausts on a *network-class*
  * close we keep watching for connectivity indefinitely on this long, fixed
@@ -282,9 +296,17 @@ export class WhatsAppAdapter {
      * watch's async connectivity probe) is in flight, and we have NOT
      * permanently given up. Lets the status accessors report "connecting"
      * during the brief timer-less window of a sustained probe instead of
-     * flashing a red error. Cleared on open / give-up / logout / stop.
+     * flashing a red error. Cleared on open / logout / stop.
      */
     reconnecting = false;
+    /**
+     * True while the slow app-layer watch is armed (fast phase exhausted on a
+     * non-network close). Unlike the network-class sustained watch, this state
+     * IS surfaced as an error by {@link getStatusError} — WhatsApp is actively
+     * rejecting us and the user may want to act (re-pair, check the dashboard)
+     * rather than wait out the ~30-min retry cadence.
+     */
+    appLayerWatch = false;
     /**
      * Connectivity probe used by the sustained watch. Injectable so tests can
      * drive the offline / back-online transitions without real DNS; production
@@ -323,9 +345,10 @@ export class WhatsAppAdapter {
      *   - `logged_out` → terminal, surface the error.
      *   - `disconnected` → recovery is in flight when a reconnect timer is
      *     pending OR a sustained-watch attempt is mid-probe ({@link reconnecting}
-     *     covers the brief timer-less DNS window). Only when neither holds have
-     *     we permanently given up (app-layer rejection past the fast cap) — a
-     *     real, user-actionable failure.
+     *     covers the brief timer-less DNS window) — EXCEPT the slow app-layer
+     *     watch ({@link appLayerWatch}), which is surfaced even though a timer
+     *     is pending: WhatsApp is actively rejecting us and the ~30-min retry
+     *     cadence is slow enough that the user may want to act first.
      */
     getStatusError() {
         switch (this.connectionState) {
@@ -337,6 +360,8 @@ export class WhatsAppAdapter {
             case "logged_out":
                 return this.lastError ?? "WhatsApp logged out";
             case "disconnected":
+                if (this.appLayerWatch)
+                    return this.lastError ?? "WhatsApp disconnected";
                 if (this.reconnectTimer !== null || this.reconnecting)
                     return null;
                 return this.lastError ?? "WhatsApp disconnected";
@@ -392,6 +417,7 @@ export class WhatsAppAdapter {
         this.lastError = null;
         this.reconnectAttempts = 0;
         this.reconnecting = false;
+        this.appLayerWatch = false;
         this.lastCloseWasNetwork = false;
         if (this.reconnectTimer) {
             clearTimeout(this.reconnectTimer);
@@ -484,6 +510,7 @@ export class WhatsAppAdapter {
         }
         this.reconnectAttempts = 0;
         this.reconnecting = false;
+        this.appLayerWatch = false;
         this.lastCloseWasNetwork = false;
         this.sentMessageIds.clear();
         this.clearQrSnapshot();
@@ -923,6 +950,7 @@ export class WhatsAppAdapter {
             this.lastError = null;
             this.reconnectAttempts = 0;
             this.reconnecting = false;
+            this.appLayerWatch = false;
             this.lastCloseWasNetwork = false;
             this.clearQrSnapshot();
             this.clearQrFile();
@@ -956,6 +984,7 @@ export class WhatsAppAdapter {
             this.lastError = `WhatsApp logged out (status ${statusCode ?? "unknown"}) — re-pair required`;
             this.reconnectAttempts = 0;
             this.reconnecting = false;
+            this.appLayerWatch = false;
             logger.error({ statusCode }, "whatsapp connection closed: logged out");
             if (this.onLoggedOut) {
                 try {
@@ -971,6 +1000,7 @@ export class WhatsAppAdapter {
             this.connectionState = "disabled";
             this.reconnectAttempts = 0;
             this.reconnecting = false;
+            this.appLayerWatch = false;
             return;
         }
         // Classify the close: a transport/network failure (or a raw socket error
@@ -1013,9 +1043,13 @@ export class WhatsAppAdapter {
      *     on its own instead of wedging in an error state.
      *
      * If the fast phase exhausts on a *non*-network close (WhatsApp rejecting us
-     * at the app layer — bad version, bad session, throttle) we stop and surface
-     * an error: hammering a relay that keeps closing us is the fast path to an
-     * IP-level block and needs operator action (re-pair / wait it out).
+     * at the app layer — bad version, bad session, throttle) we drop into the
+     * slow **app-layer watch**: same timer machinery as the sustained watch but
+     * on a much longer cadence ({@link RECONNECT_APP_LAYER_WATCH_DELAY_MS}) and
+     * with the error surfaced to the dashboard. Hammering a relay that keeps
+     * closing us is the fast path to an IP-level block, but a permanent stop
+     * would wedge the adapter until daemon restart over conditions that
+     * routinely clear on their own (throttles, server restarts, version churn).
      */
     scheduleReconnect() {
         if (this.reconnectTimer || this.shuttingDown)
@@ -1023,15 +1057,25 @@ export class WhatsAppAdapter {
         if (this.connectionState === "logged_out")
             return;
         const exhaustedFastPhase = this.reconnectAttempts >= RECONNECT_MAX_ATTEMPTS;
-        if (exhaustedFastPhase && !this.lastCloseWasNetwork) {
-            const previousError = this.lastError ?? "unknown error";
-            this.lastError = `WhatsApp reconnect gave up after ${RECONNECT_MAX_ATTEMPTS} attempts (${previousError})`;
-            this.reconnecting = false;
-            logger.error({ attempts: this.reconnectAttempts, lastError: previousError }, "whatsapp reconnect: max attempts exceeded");
-            return;
-        }
+        const appLayerWatch = exhaustedFastPhase && !this.lastCloseWasNetwork;
         let delayMs;
-        if (exhaustedFastPhase) {
+        if (appLayerWatch) {
+            // Wrap lastError and log only on ENTRY into the watch. Re-scheduling
+            // from within it (the probe-unreachable path of runReconnectAttempt
+            // calls scheduleReconnect on every watch tick) must not re-wrap —
+            // each pass would nest the previous wrapped message inside the new
+            // one, growing lastError without bound, and would re-emit the
+            // error-level log every ~30 min for one underlying condition.
+            if (!this.appLayerWatch) {
+                const previousError = this.lastError ?? "unknown error";
+                this.lastError = `WhatsApp reconnect: ${RECONNECT_MAX_ATTEMPTS} fast attempts failed at the app layer (${previousError}); retrying every ~${Math.round(RECONNECT_APP_LAYER_WATCH_DELAY_MS / 60_000)} min`;
+                logger.error({ attempts: this.reconnectAttempts, lastError: previousError }, "whatsapp reconnect: fast phase exhausted at app layer; entering slow watch");
+            }
+            delayMs =
+                RECONNECT_APP_LAYER_WATCH_DELAY_MS
+                    + Math.floor(Math.random() * RECONNECT_SUSTAINED_JITTER_MS);
+        }
+        else if (exhaustedFastPhase) {
             // Sustained network watch — fixed cadence, counter left pinned at the
             // cap so we stay in this branch without growing reconnectAttempts.
             delayMs =
@@ -1044,14 +1088,15 @@ export class WhatsAppAdapter {
             this.reconnectAttempts += 1;
         }
         this.reconnecting = true;
-        logger.info({ attempt: this.reconnectAttempts, delayMs, sustained: exhaustedFastPhase }, "whatsapp reconnect scheduled");
+        this.appLayerWatch = appLayerWatch;
+        logger.info({ attempt: this.reconnectAttempts, delayMs, sustained: exhaustedFastPhase, appLayerWatch }, "whatsapp reconnect scheduled");
         this.reconnectTimer = setTimeout(() => {
             this.reconnectTimer = null;
             if (this.shuttingDown || this.connectionState === "logged_out") {
                 this.reconnecting = false;
                 return;
             }
-            void this.runReconnectAttempt(exhaustedFastPhase);
+            void this.runReconnectAttempt(exhaustedFastPhase, appLayerWatch);
         }, delayMs);
         this.reconnectTimer.unref?.();
     }
@@ -1069,8 +1114,14 @@ export class WhatsAppAdapter {
      * `exhausted && !network` in {@link scheduleReconnect} and falsely give up.
      * A fresh fast phase gives those handshake closes their proper retry budget
      * (a clean `open` doesn't fire before a 515, so we can't rely on it here).
+     *
+     * The app-layer watch (`appLayerWatch=true`) reuses this path but grants
+     * only {@link RECONNECT_APP_LAYER_RETRY_BUDGET} fast attempts instead of a
+     * full fresh phase: the network never went away, so a still-broken app
+     * layer should fall back into the slow watch after a short burst rather
+     * than re-earning ten rapid connects every watch tick.
      */
-    async runReconnectAttempt(sustained) {
+    async runReconnectAttempt(sustained, appLayerWatch = false) {
         if (sustained) {
             const reachable = await this.isNetworkReachable();
             // shuttingDown / logged_out may have flipped during the async probe.
@@ -1084,7 +1135,9 @@ export class WhatsAppAdapter {
                 return;
             }
             logger.info("whatsapp reconnect: network reachable, reconnecting");
-            this.reconnectAttempts = 0;
+            this.reconnectAttempts = appLayerWatch
+                ? RECONNECT_MAX_ATTEMPTS - RECONNECT_APP_LAYER_RETRY_BUDGET
+                : 0;
         }
         try {
             await this.connect();

package/dist/api/env-writer.js

@@ -67,14 +67,17 @@ function isRestartRequiredKey(key) {
 const NUMERIC_RANGE = {
     dayBoundaryHour: { min: 0, max: 9, label: "0–9 (before 10:00)" },
     executeTimeoutMinutes: { min: 1, max: 1440, label: "1–1440 minutes" },
-    hourlyCheckActiveStartHour: { min: 0, max: 23, label: "0–23" },
-    hourlyCheckActiveEndHour: { min: 1, max: 24, label: "1–24" },
+    activityScanActiveStartHour: { min: 0, max: 23, label: "0–23" },
+    activityScanActiveEndHour: { min: 1, max: 24, label: "1–24" },
     // Any positive integer up to one day. Intervals that evenly divide 60
     // produce a tight cron; arbitrary intervals run a minute-tick cron with an
     // in-callback modulo gate anchored at activeStartHour. See
-    // scheduler.ts:buildHourlyCronExpr / shouldFireHourlyTickAt.
-    hourlyCheckIntervalMinutes: { min: 1, max: 1440, label: "1–1440 minutes" },
-    hourlyCheckMinObservations: { min: 0, max: 1000, label: "0–1000" },
+    // scheduler.ts:buildActivityScanCronExpr / shouldFireActivityScanTickAt.
+    activityScanIntervalMinutes: { min: 1, max: 1440, label: "1–1440 minutes" },
+    activityScanMinObservations: { min: 0, max: 1000, label: "0–1000" },
+    // Twin of the runtimeSettingsSchema bound; cap 480 = the self-tuning R1
+    // freshness ladder's top notch (SELF_TUNING_REVIEW_CYCLE_DESIGN.md D2).
+    activityScanPrePassFreshnessMinutes: { min: 0, max: 480, label: "0–480 minutes" },
     gitPollIntervalSeconds: { min: 60, max: 86400, label: "60–86400 seconds" },
     githubPollIntervalSeconds: { min: 60, max: 86400, label: "60–86400 seconds" },
     // 0 disables the observer; 20160 min = 14 days which is already well past

package/dist/api/helpers/agent-errors-registry.d.ts

@@ -1261,7 +1261,7 @@ export declare const AGENT_ERROR_REGISTRY: {
     };
     readonly "observations.invalid_actor": {
         readonly expected: "actor = 'user' | 'agent' | 'system'";
-        readonly hint: "The `?actor=` filter accepts only `user`, `agent`, or `system`. `user` is the hourly-check default (excludes agent's own writes). Omit to get all observations.";
+        readonly hint: "The `?actor=` filter accepts only `user`, `agent`, or `system`. `user` is the activity-scan default (excludes agent's own writes). Omit to get all observations.";
         readonly skillAnchor: "observations#actor-filter";
         readonly legacyErrorCode: "invalid_actor";
         readonly constraint: {
@@ -1868,11 +1868,11 @@ export declare const AGENT_ERROR_REGISTRY: {
         readonly legacyErrorCode: "daemon_starting";
         readonly retryable: true;
     };
-    readonly "agent.hourly_check_unavailable": {
-        readonly expected: "triggerHourlyCheck wired into the API server";
-        readonly hint: "POST /agent/run-now/hourly was called before the hourly-check engine was wired (typically only the first ~1s of boot). Wait ~3s and retry.";
+    readonly "agent.activity_scan_unavailable": {
+        readonly expected: "triggerActivityScan wired into the API server";
+        readonly hint: "POST /api/agent/run-now was called before the activity-scan engine was wired (typically only the first ~1s of boot). Wait ~3s and retry.";
         readonly skillAnchor: "agent#run-now";
-        readonly legacyErrorCode: "hourly_check_unavailable";
+        readonly legacyErrorCode: "activity_scan_unavailable";
         readonly retryable: true;
     };
     readonly "agent.roadmap_maintenance_unavailable": {

package/dist/api/helpers/agent-errors-registry.js

@@ -1194,7 +1194,7 @@ export const AGENT_ERROR_REGISTRY = {
     // ── /api/observations/* — Phase 9 pending/consume.
     "observations.invalid_actor": {
         expected: "actor = 'user' | 'agent' | 'system'",
-        hint: "The `?actor=` filter accepts only `user`, `agent`, or `system`. `user` is the hourly-check default (excludes agent's own writes). Omit to get all observations.",
+        hint: "The `?actor=` filter accepts only `user`, `agent`, or `system`. `user` is the activity-scan default (excludes agent's own writes). Omit to get all observations.",
         skillAnchor: "observations#actor-filter",
         legacyErrorCode: "invalid_actor",
         constraint: { type: "enum", enum: ["user", "agent", "system"] },
@@ -1794,11 +1794,11 @@ export const AGENT_ERROR_REGISTRY = {
         legacyErrorCode: "daemon_starting",
         retryable: true,
     },
-    "agent.hourly_check_unavailable": {
-        expected: "triggerHourlyCheck wired into the API server",
-        hint: "POST /agent/run-now/hourly was called before the hourly-check engine was wired (typically only the first ~1s of boot). Wait ~3s and retry.",
+    "agent.activity_scan_unavailable": {
+        expected: "triggerActivityScan wired into the API server",
+        hint: "POST /api/agent/run-now was called before the activity-scan engine was wired (typically only the first ~1s of boot). Wait ~3s and retry.",
         skillAnchor: "agent#run-now",
-        legacyErrorCode: "hourly_check_unavailable",
+        legacyErrorCode: "activity_scan_unavailable",
         retryable: true,
     },
     "agent.roadmap_maintenance_unavailable": {

package/dist/api/routes/agent.js

@@ -24,10 +24,10 @@ export function createAgentRoutes(deps) {
                 },
             });
         }
-        if (!deps.triggerHourlyCheck) {
+        if (!deps.triggerActivityScan) {
             return respondWithAgentError(c, 503, [
-                composeIssue("agent.hourly_check_unavailable", {
-                    field: "triggerHourlyCheck",
+                composeIssue("agent.activity_scan_unavailable", {
+                    field: "triggerActivityScan",
                     received: "<unavailable>",
                 }),
             ]);
@@ -37,7 +37,7 @@ export function createAgentRoutes(deps) {
             ? body.reason.trim()
             : "api";
         // Default to `force: true` for manual runs — the user explicitly asked
-        // us to check now, so bypass the `hourlyCheckMinObservations` threshold.
+        // us to check now, so bypass the `activityScanMinObservations` threshold.
         // Callers may pass `{ force: false }` to respect the threshold (e.g.,
         // for a gentle cron-style "check if anything is pending" ping).
         const force = body.force === undefined ? true : body.force === true;
@@ -61,7 +61,7 @@ export function createAgentRoutes(deps) {
                 });
             }
         }
-        const result = await deps.triggerHourlyCheck(`manual:${reason}`, {
+        const result = await deps.triggerActivityScan(`manual:${reason}`, {
             force,
             ...(requestedModel ? { requestedModel } : {}),
         });
@@ -251,6 +251,7 @@ export function createAgentRoutes(deps) {
         const normalizedPlatforms = platforms ?? (platform ? [platform] : undefined);
         const messageSummary = message.slice(0, 200);
         const originSessionId = parsePositiveIntegerHeader(c.req.header("x-pa-session-id"));
+        const correlationId = c.req.header("x-pa-event-correlation-id");
         let dispatchId = randomUUID();
         let notificationId = dispatchId;
         if (sendNotification) {
@@ -260,7 +261,29 @@ export function createAgentRoutes(deps) {
                 priority: priority ?? "normal",
                 notificationType: "agent",
                 ...(originSessionId !== null ? { originSessionId } : {}),
+                ...(correlationId ? { correlationId } : {}),
             });
+            // QUIET_HOURS_HARDENING_PLAN.md Phase 1 — quiet-hours deferral. The
+            // message WILL deliver (durable `task_type='dm'` row at the
+            // quiet-hours edge, visible on /schedule), so the event is marked
+            // notified exactly like the sent path: not marking would double-send
+            // once the dispatcher's implicit final-text forward fires.
+            if (result.status === "deferred_quiet_hours") {
+                if (deps.markEventNotified && correlationId) {
+                    deps.markEventNotified(correlationId);
+                }
+                return c.json({
+                    status: "deferred_quiet_hours",
+                    scheduleId: result.scheduleId,
+                    deliverAfter: result.deliverAfter,
+                });
+            }
+            // Rate-limited: nothing was sent and nothing was queued — the live
+            // session can adapt (write to today.md, retry later). The event is
+            // deliberately NOT marked notified.
+            if (result.status === "rate_limited") {
+                return c.json({ status: "rate_limited", retryAfter: result.retryAfter }, 429);
+            }
             dispatchId = result.dispatchId;
             notificationId = dispatchId;
         }
@@ -283,13 +306,11 @@ export function createAgentRoutes(deps) {
         // Notify-dedup — when the agent's shim auto-attached the correlation
         // header, mark the event so the dispatcher skips the implicit
         // final-text DM forward in processResult. We only mark on the
-        // success branch (sendNotification path); the warn-fallback branch
-        // is daemon-misconfiguration, not user-visible delivery.
-        if (sendNotification && deps.markEventNotified) {
-            const correlationId = c.req.header("x-pa-event-correlation-id");
-            if (correlationId) {
-                deps.markEventNotified(correlationId);
-            }
+        // delivery branches (sent above-the-fold here, deferred earlier); the
+        // warn-fallback branch is daemon-misconfiguration, not user-visible
+        // delivery, and the rate-limited branch never delivers.
+        if (sendNotification && deps.markEventNotified && correlationId) {
+            deps.markEventNotified(correlationId);
         }
         return c.json({
             status: "sent",