@aitne/daemon 0.1.10 → 0.1.11

package/dist/bootstrap/schedule-helpers.js

@@ -11,6 +11,8 @@
 import { existsSync, readFileSync } from "node:fs";
 import { formatSqliteDatetime, getAgentDayBoundsUtc, getAgentDayDateStr, getAgentDayProgressMinutes, nowInTimezone, parseSqliteUtcMs, } from "@aitne/shared";
 import { hasActionInWindow } from "../core/schedule-maintenance.js";
+import { getAgentEnabled, getRuntimeWindow } from "../db/agents-store.js";
+import { resolveActivityScanCadence } from "../core/agents/activity-scan-cadence.js";
 /**
  * Days of week on which the boot-time catchup will fire an unrun
  * `routine.weekly_review`. Friday is the canonical slot; Saturday and
@@ -64,11 +66,10 @@ export function getDueCatchupRoutines(db, config, agentDayStartUtc, agentDayEndU
             routines.push("weekly_review");
         }
     }
-    // Monthly catchup is gated by the same kill switch as the scheduler
-    // cron (see scheduler.ts comment block). Default OFF pre-release until
-    // the Mirror+Prune redesign; operators opt in via
-    // PA_MONTHLY_REVIEW_ENABLED or PATCH /api/config.
-    if (config.monthlyReviewEnabled &&
+    // Monthly catchup is gated by the same switch as the scheduler cron:
+    // the monthly-review AGENT row's `enabled` (default OFF pre-release until
+    // the Mirror+Prune redesign; operators opt in from /agents/monthly-review).
+    if (getAgentEnabled(db, "monthly-review", false) &&
         tomorrowLocal.day === 1 &&
         !hasActionInWindow(db, "routine.monthly_review", agentDayStartUtc, agentDayEndUtc)) {
         routines.push("monthly_review");
@@ -77,11 +78,11 @@ export function getDueCatchupRoutines(db, config, agentDayStartUtc, agentDayEndU
 }
 /**
  * Decide whether the boot sequence should immediately fire one
- * catch-up `routine.hourly_check` (because the cron callback never ran
+ * catch-up `routine.activity_scan` (because the cron callback never ran
  * for the current slot — typically because the host was asleep / the
  * daemon was stopped during the slot window).
  *
- * Slot math mirrors `shouldFireHourlyTickAt` in `scheduler.ts` so the
+ * Slot math mirrors `shouldFireActivityScanTickAt` in `scheduler.ts` so the
  * catch-up always lands on the same slot the cron would have fired at.
  *
  * **Wrap-around active hours are NOT supported.** The active-hours
@@ -101,31 +102,35 @@ export function getDueCatchupRoutines(db, config, agentDayStartUtc, agentDayEndU
  * config-write time, or (b) split the window into two non-wrap
  * ranges in the same call site that consumes them.
  */
-export function shouldCatchUpHourlyCheck(db, config, now) {
-    if (!config.hourlyCheckEnabled) {
+export function shouldCatchUpActivityScan(db, config, now) {
+    // `agents.enabled` on the activity-scan row is the single on/off switch
+    // (AGENTS_HUB_REDESIGN_PLAN.md §2); cadence comes from the row's
+    // runtime_window with the legacy config keys as fallback.
+    if (!getAgentEnabled(db, "activity-scan", true)) {
         return false;
     }
+    const cadence = resolveActivityScanCadence(getRuntimeWindow(db, "activity-scan"), config);
     const tz = config.timezone || undefined;
     const local = nowInTimezone(tz, now);
-    if (local.hours < config.hourlyCheckActiveStartHour ||
-        local.hours >= config.hourlyCheckActiveEndHour ||
+    if (local.hours < cadence.activeStartHour ||
+        local.hours >= cadence.activeEndHour ||
         local.hours === config.dayBoundaryHour) {
         return false;
     }
-    // Slot anchors to `activeStartHour`, mirroring shouldFireHourlyTickAt
+    // Slot anchors to `activeStartHour`, mirroring shouldFireActivityScanTickAt
     // in scheduler.ts so the catch-up function picks the same slot the
     // cron callback would have fired at. The earlier branch already
     // returned false when local.hours < activeStartHour, so the offset is
     // always non-negative here.
-    const anchorMinutes = config.hourlyCheckActiveStartHour * 60;
+    const anchorMinutes = cadence.activeStartHour * 60;
     const offsetFromAnchor = local.hours * 60 + local.minutes - anchorMinutes;
-    const slotOffsetFromAnchor = Math.floor(offsetFromAnchor / config.hourlyCheckIntervalMinutes) *
-        config.hourlyCheckIntervalMinutes;
+    const slotOffsetFromAnchor = Math.floor(offsetFromAnchor / cadence.intervalMinutes) *
+        cadence.intervalMinutes;
     const slotMinutesSinceMidnight = anchorMinutes + slotOffsetFromAnchor;
     const dayStartUtc = getAgentDayBoundsUtc(tz, 0, now).start;
     const slotStartMs = parseSqliteUtcMs(dayStartUtc) + slotMinutesSinceMidnight * 60 * 1000;
     const slotStartUtc = formatSqliteDatetime(new Date(slotStartMs));
-    return !hasActionInWindow(db, "routine.hourly_check", slotStartUtc, formatSqliteDatetime(now));
+    return !hasActionInWindow(db, "routine.activity_scan", slotStartUtc, formatSqliteDatetime(now));
 }
 export function getProgressMinutesForHour(hour, dayBoundaryHour) {
     const scheduledMinutes = hour * 60;
@@ -147,7 +152,7 @@ export function hasFreshAgentDayTodayMd(todayMdPath, timezone, dayBoundaryHour,
 }
 /**
  * Did `routine.morning_routine` complete successfully within the current
- * agent-day window? Used by the pre-routine gate that fronts hourly_check
+ * agent-day window? Used by the pre-routine gate that fronts activity_scan
  * and the review routines (evening / weekly / monthly) so they refuse to
  * run before the day has been properly opened.
  *
@@ -231,10 +236,10 @@ export function readMorningRoutineStallThresholdMinutes(db) {
  * without producing a successful `agent_actions` row. Returns the
  * offending row's metadata if stalled, null when the system is healthy.
  *
- * Pairs with `queueMorningRoutineWake` + the hourly-check pre-routine
+ * Pairs with `queueMorningRoutineWake` + the activity-scan pre-routine
  * gate. The dedup that keeps `queueMorningRoutineWake` from re-inserting
  * means a stuck wake row leaves the system in a silent freeze — the gate
- * skips `routine.hourly_check`, `routine.evening_review`, etc. forever
+ * skips `routine.activity_scan`, `routine.evening_review`, etc. forever
  * without surfacing to the user. This helper is the externally visible
  * signal the watchdog uses to break the silence.
  *
@@ -277,6 +282,154 @@ export function getStalledMorningRoutineWake(db, agentDayConfig, thresholdMinute
         ageMinutes,
     };
 }
+/**
+ * Audit-row action types that count as "a morning-routine attempt started"
+ * for the missed-fire predicate below. The parent row
+ * (`routine.morning_routine`) is written when the pipeline finishes
+ * (success or failure); the Stage A row
+ * (`routine.morning_routine_today`) is written `in_progress` the moment
+ * the agent execution starts, so a hung Stage A is still visible as an
+ * attempt. The fetch-window pre-pass is deliberately NOT included — it
+ * also runs for hourly/scheduled flows, and counting it would let an
+ * unrelated pre-pass mask a dead morning pipeline.
+ */
+export const MORNING_ROUTINE_ATTEMPT_ACTION_TYPES = [
+    "routine.morning_routine",
+    "routine.morning_routine_today",
+];
+/**
+ * Grace period after the agent-day boundary before the missed-fire
+ * self-heal may conclude the 04:00 cron tick was swallowed. Wide enough
+ * that the normal cron → queueMorningRoutineWake → ScheduleWatcher claim
+ * → Stage A start chain has long since produced either a wake row or an
+ * attempt row; short enough that a swallowed tick costs at most ~25 min
+ * (grace + one self-heal interval) once the machine is awake.
+ */
+export const MORNING_MISSED_FIRE_GRACE_MINUTES = 15;
+/**
+ * Epoch ms of the most recent morning-routine attempt (any result,
+ * including `in_progress`) started within the current agent-day, or null
+ * when nothing has been attempted yet. Pure read.
+ */
+export function getLatestMorningAttemptStartMs(db, agentDayConfig, now) {
+    const { start } = getAgentDayBoundsUtc(agentDayConfig.timezone, agentDayConfig.dayBoundaryHour, now);
+    const row = db
+        .prepare(`SELECT MAX(started_at) AS latest
+         FROM agent_actions
+        WHERE action_type IN (${MORNING_ROUTINE_ATTEMPT_ACTION_TYPES.map(() => "?").join(",")})
+          AND started_at >= ?`)
+        .get(...MORNING_ROUTINE_ATTEMPT_ACTION_TYPES, start);
+    if (!row.latest)
+        return null;
+    return parseSqliteUtcMs(row.latest);
+}
+/**
+ * Detect the hung-execution variant of the morning-routine silent stall:
+ * a wake row claimed to `running` at least `thresholdMinutes` ago with
+ * still no `routine.morning_routine` success for the current agent-day
+ * (machine slept mid-run and the backend stream died on the network
+ * change, the SDK call wedged, or the dispatch event was lost).
+ *
+ * `queueMorningRoutineWake`'s dedup treats a `running` row as "already
+ * in flight" and merges into it forever, so without recovery the day
+ * stays frozen until a daemon restart. The caller (scheduler self-heal
+ * tick) flips the returned row back to `pending` so the ScheduleWatcher
+ * re-claims it; the today-write-lock's wall-clock TTL guarantees a hung
+ * original cannot hold the lock against the re-run indefinitely.
+ *
+ * Staleness is measured from `task_context.claimedAt`, stamped by the
+ * ScheduleWatcher at claim time. That is the only signal that survives
+ * every confounder: `created_at` predates sleeps that delay the claim,
+ * `scheduled_for` is bumped by dedup merges, and attempt audit rows are
+ * windowed to the current agent-day (a run that started before the
+ * 04:00 boundary and hung across it has no attempt row "today").
+ * Invariants this leans on:
+ *   - boot recovery (`recoverOrphanedRunningSchedules`) clears every
+ *     `running` row at daemon start, so a live `running` row was always
+ *     claimed by the current process — which always stamps;
+ *   - `queueMorningRoutineWake`'s dedup-merge preserves unknown
+ *     task_context keys, so a 04:00 cron merge cannot strip the stamp.
+ * A row without a readable stamp (stamp UPDATE failed, malformed JSON)
+ * is left to the alert-only watchdog rather than guessed at.
+ *
+ * Pure read — the caller owns the UPDATE.
+ */
+export function getRecoverableStalledMorningWake(db, agentDayConfig, thresholdMinutes, now) {
+    const reference = now ?? new Date();
+    if (morningRoutineRanToday(db, agentDayConfig, reference)) {
+        return null;
+    }
+    const row = db
+        .prepare(`SELECT id, task_context
+         FROM agent_schedule
+        WHERE task_type = 'wake'
+          AND status = 'running'
+          AND json_extract(task_context, '$.routine') = 'morning_routine'
+        ORDER BY created_at ASC
+        LIMIT 1`)
+        .get();
+    if (!row)
+        return null;
+    let claimedAt;
+    try {
+        // The WHERE's json_extract guarantees task_context is non-null and
+        // valid to SQLite's JSON parser — but SQLite ≥3.42 accepts JSON5,
+        // which JSON.parse rejects, so the parse can still throw.
+        claimedAt = JSON.parse(row.task_context).claimedAt;
+    }
+    catch {
+        return null;
+    }
+    if (typeof claimedAt !== "string")
+        return null;
+    const claimedMs = parseSqliteUtcMs(claimedAt);
+    if (!Number.isFinite(claimedMs))
+        return null;
+    const claimedAgeMinutes = Math.floor((reference.getTime() - claimedMs) / 60_000);
+    if (claimedAgeMinutes < thresholdMinutes)
+        return null;
+    return { id: row.id, claimedAgeMinutes };
+}
+/**
+ * Detect the missed-fire variant of the morning-routine silent stall:
+ * the machine was asleep at the day-boundary minute, node-cron silently
+ * dropped the tick (it never replays missed firings), and nothing since
+ * has re-queued the routine. Observable signature, all three at once:
+ *
+ *   1. no morning-routine attempt has *started* this agent-day (any
+ *      result — a failed/exhausted retry chain counts as attempted, so
+ *      this self-heal never resurrects a chain that
+ *      `scheduleMorningRetry` deliberately stopped after MAX_RETRIES);
+ *   2. no `pending`/`running` morning wake row exists (the cron, the
+ *      wake catch-up, and the retry chain all leave one when they are
+ *      mid-flight);
+ *   3. the agent-day is at least `graceMinutes` old, so a healthy cron
+ *      fire has had ample time to produce 1 or 2.
+ *
+ * Complements the WakeDetector: gaps shorter than its 5-min threshold
+ * that straddle the boundary minute (lid closed 03:59–04:02), or a
+ * detector failure, still converge here within one self-heal interval.
+ *
+ * Pure read — the caller routes through `queueMorningRoutineWake`,
+ * whose DB-backed dedup makes double-queueing impossible.
+ */
+export function shouldQueueMissedMorningFire(db, agentDayConfig, graceMinutes, now) {
+    const reference = now ?? new Date();
+    const progressMinutes = getAgentDayProgressMinutes(agentDayConfig.timezone, agentDayConfig.dayBoundaryHour, reference);
+    if (progressMinutes < graceMinutes)
+        return false;
+    const wakeRow = db
+        .prepare(`SELECT 1
+         FROM agent_schedule
+        WHERE task_type = 'wake'
+          AND status IN ('pending', 'running')
+          AND json_extract(task_context, '$.routine') = 'morning_routine'
+        LIMIT 1`)
+        .get();
+    if (wakeRow !== undefined)
+        return false;
+    return (getLatestMorningAttemptStartMs(db, agentDayConfig, reference) === null);
+}
 // P22 — read the operator's chosen cadence for skill curation runs.
 // Mirrors the helper in `core/scheduler.ts` so the dispatcher hook here can
 // resolve cadence at runtime without crossing module boundaries.

package/dist/config.js

@@ -99,8 +99,10 @@ export function loadDefaultRuntimeSettings() {
     // they know the value is now a no-op instead of silently dropping
     // their override. The runtime-settings Zod schema would otherwise
     // ignore the unknown key without any signal.
+    // Reads the LEGACY env name on purpose — the warning exists for operators
+    // who still carry the pre-redesign variable in their .env.
     if (env("HOURLY_CHECK_GATE_MODE") !== undefined) {
-        console.warn("[config] PA_HOURLY_CHECK_GATE_MODE is set but no longer honoured — the hourly_check gate now has a single execution path (see HOURLY_CHECK_GATE_REDESIGN_PLAN.md Phase 4). Remove the env var to silence this warning.");
+        console.warn("[config] PA_HOURLY_CHECK_GATE_MODE is set but no longer honoured — the activity_scan gate now has a single execution path (see HOURLY_CHECK_GATE_REDESIGN_PLAN.md Phase 4). Remove the env var to silence this warning.");
     }
     const parsed = runtimeSettingsSchema.parse({
         slackOwnerUserId: env("SLACK_OWNER_USER_ID") ?? null,
@@ -133,6 +135,9 @@ export function loadDefaultRuntimeSettings() {
         proactiveForwardChannelTimelineEnabled: parseBooleanOrDefault(env("PROACTIVE_FORWARD_CHANNEL_TIMELINE_ENABLED"), true),
         proactiveForwardForceFreshSession: parseBooleanOrDefault(env("PROACTIVE_FORWARD_FORCE_FRESH_SESSION"), false),
         feedbackLearningEnabled: parseBooleanOrDefault(env("FEEDBACK_LEARNING_ENABLED"), true),
+        // SELF_TUNING_REVIEW_CYCLE_DESIGN.md §6 — Phase 3 actuation gate.
+        // Default false = shadow mode (recommend + verdict only, no actuation).
+        selfTuningEnabled: parseBooleanOrDefault(env("SELF_TUNING_ENABLED"), false),
         feedbackPromotionThreshold: parseNumberOrDefault(env("FEEDBACK_PROMOTION_THRESHOLD"), 2),
         feedbackLessonMaxBytesGlobal: parseNumberOrDefault(env("FEEDBACK_LESSON_MAX_BYTES_GLOBAL"), 8192),
         feedbackLessonMaxBytesPerAgent: parseNumberOrDefault(env("FEEDBACK_LESSON_MAX_BYTES_PER_AGENT"), 4096),
@@ -148,19 +153,26 @@ export function loadDefaultRuntimeSettings() {
         // at fire time so the flag takes effect on the next month-end without
         // restart.
         monthlyReviewEnabled: parseBooleanOrDefault(env("MONTHLY_REVIEW_ENABLED"), false),
-        hourlyCheckEnabled: parseBooleanOrDefault(env("HOURLY_CHECK_ENABLED"), true),
-        hourlyCheckIntervalMinutes: parseNumberOrDefault(env("HOURLY_CHECK_INTERVAL_MINUTES"), 60),
-        hourlyCheckActiveStartHour: parseNumberOrDefault(env("HOURLY_CHECK_ACTIVE_START_HOUR"), 4),
-        hourlyCheckActiveEndHour: parseNumberOrDefault(env("HOURLY_CHECK_ACTIVE_END_HOUR"), 24),
-        hourlyCheckMinObservations: parseNumberOrDefault(env("HOURLY_CHECK_MIN_OBSERVATIONS"), 1),
-        hourlyCheckStage2Enabled: parseBooleanOrDefault(env("HOURLY_CHECK_STAGE2_ENABLED"), false),
-        hourlyCheckHeartbeatHours: parseNumberOrDefault(env("HOURLY_CHECK_HEARTBEAT_HOURS"), 4),
-        hourlyCheckLowSignalPendingCeiling: parseNumberOrDefault(env("HOURLY_CHECK_LOW_SIGNAL_PENDING_CEILING"), 0),
-        hourlyCheckPrePassFreshnessMinutes: parseNumberOrDefault(env("HOURLY_CHECK_PRE_PASS_FRESHNESS_MINUTES"), 30),
+        // The `?? env("HOURLY_CHECK_*")` fallbacks honour the pre-rename env
+        // names (the agent was "Hourly Check" until v0.1.11) — drop them after
+        // a deprecation window alongside LEGACY_RUNTIME_SETTING_KEY_ALIASES.
+        activityScanEnabled: parseBooleanOrDefault(env("ACTIVITY_SCAN_ENABLED") ?? env("HOURLY_CHECK_ENABLED"), true),
+        // Default 120 (every 2 hours) — see ACTIVITY_SCAN_CADENCE_DEFAULTS.
+        activityScanIntervalMinutes: parseNumberOrDefault(env("ACTIVITY_SCAN_INTERVAL_MINUTES") ?? env("HOURLY_CHECK_INTERVAL_MINUTES"), 120),
+        activityScanActiveStartHour: parseNumberOrDefault(env("ACTIVITY_SCAN_ACTIVE_START_HOUR") ?? env("HOURLY_CHECK_ACTIVE_START_HOUR"), 4),
+        activityScanActiveEndHour: parseNumberOrDefault(env("ACTIVITY_SCAN_ACTIVE_END_HOUR") ?? env("HOURLY_CHECK_ACTIVE_END_HOUR"), 24),
+        activityScanMinObservations: parseNumberOrDefault(env("ACTIVITY_SCAN_MIN_OBSERVATIONS") ?? env("HOURLY_CHECK_MIN_OBSERVATIONS"), 1),
+        activityScanStage2Enabled: parseBooleanOrDefault(env("ACTIVITY_SCAN_STAGE2_ENABLED") ?? env("HOURLY_CHECK_STAGE2_ENABLED"), false),
+        activityScanHeartbeatHours: parseNumberOrDefault(env("ACTIVITY_SCAN_HEARTBEAT_HOURS") ?? env("HOURLY_CHECK_HEARTBEAT_HOURS"), 4),
+        activityScanLowSignalPendingCeiling: parseNumberOrDefault(env("ACTIVITY_SCAN_LOW_SIGNAL_PENDING_CEILING")
+            ?? env("HOURLY_CHECK_LOW_SIGNAL_PENDING_CEILING"), 0),
+        activityScanPrePassFreshnessMinutes: parseNumberOrDefault(env("ACTIVITY_SCAN_PRE_PASS_FRESHNESS_MINUTES")
+            ?? env("HOURLY_CHECK_PRE_PASS_FRESHNESS_MINUTES"), 30),
         authProbeDisabled: parseBooleanOrDefault(env("AUTH_PROBE_DISABLED"), false),
         authPreflightFreshnessMs: parseNumberOrDefault(env("AUTH_PREFLIGHT_FRESHNESS_MS"), 600000),
         schedulePollIntervalSeconds: parseNumberOrDefault(env("SCHEDULE_POLL_INTERVAL_SECONDS"), 5),
         maxBriefingDelayMinutes: parseNumberOrDefault(env("MAX_BRIEFING_DELAY_MINUTES"), 30),
+        ownerActivityIdleThresholdMinutes: parseNumberOrDefault(env("OWNER_ACTIVITY_IDLE_THRESHOLD_MINUTES"), 5),
         maxNotificationsPerHour: parseNumberOrDefault(env("MAX_NOTIFICATIONS_PER_HOUR"), 3),
         maxNotificationsPerDay: parseNumberOrDefault(env("MAX_NOTIFICATIONS_PER_DAY"), 12),
         quietHoursStart: envOrDefault("QUIET_HOURS_START", "22:00"),
@@ -185,7 +197,7 @@ export function loadDefaultRuntimeSettings() {
         githubPollIntervalSeconds: parseNumberOrDefault(env("GITHUB_POLL_INTERVAL_SECONDS"), 1800),
         // Matches calendar/git poller cadence. Previously 60s, but 3 databases
         // × 1440 polls/day ≈ 4320 API calls/day was excessive when the only
-        // downstream consumer is hourly_check. Override with
+        // downstream consumer is activity_scan. Override with
         // PA_NOTION_POLL_INTERVAL_SECONDS if you need closer to real-time
         // Notion sync (at the cost of API quota). If you raise this beyond
         // ~10 min, also raise `NOTION_WRITE_TTL_MS` in `api/routes/notion.ts`
@@ -202,7 +214,7 @@ export function loadDefaultRuntimeSettings() {
         mailIdleFallbackRecoveryMinutes: parseNumberOrDefault(env("MAIL_IDLE_FALLBACK_RECOVERY_MINUTES"), 60),
         mailMaxMessagesPerPoll: parseNumberOrDefault(env("MAIL_MAX_MESSAGES_PER_POLL"), 20),
         mailAuthFailureRetryHours: parseNumberOrDefault(env("MAIL_AUTH_FAILURE_RETRY_HOURS"), 6),
-        hourlyObservationCharBudget: parseNumberOrDefault(env("HOURLY_OBSERVATION_CHAR_BUDGET"), 8000),
+        activityScanObservationCharBudget: parseNumberOrDefault(env("ACTIVITY_SCAN_OBSERVATION_CHAR_BUDGET") ?? env("HOURLY_OBSERVATION_CHAR_BUDGET"), 8000),
         prePassMaxAttemptsPerIntegration: parseNumberOrDefault(env("PRE_PASS_MAX_ATTEMPTS_PER_INTEGRATION"), 3),
         prePassBackoffMs: parseJsonOrDefault(env("PRE_PASS_BACKOFF_MS"), [1000, 2000, 4000]),
         prePassRetryEscalationTier: parseNullableStringEnv(env("PRE_PASS_RETRY_ESCALATION_TIER")),
@@ -243,6 +255,8 @@ export function loadDefaultRuntimeSettings() {
         // installs pre-seed them.
         primaryLanguage: envOrDefault("PRIMARY_LANGUAGE", "en"),
         vaultMode: env("VAULT_MODE") ?? "plain",
+        // Keep-awake posture (macOS caffeinate); see core/sleep-inhibitor.ts.
+        preventSleepMode: env("PREVENT_SLEEP_MODE") ?? "ac",
     });
     return normalizeRuntimeSettings(parsed);
 }

package/dist/core/agent-core.d.ts

@@ -570,5 +570,37 @@ export declare class BackendDecisiveFailure extends Error {
     readonly backendId: BackendId;
     readonly kind: "quota" | "auth" | "max_turns" | "timeout" | "model_unavailable" | "policy_denied" | "other_non_retryable";
     readonly cause: unknown;
-    constructor(backendId: BackendId, kind: "quota" | "auth" | "max_turns" | "timeout" | "model_unavailable" | "policy_denied" | "other_non_retryable", cause: unknown);
+    /**
+     * PREPASS_COST_REDUCTION_PLAN.md N1 — best-effort spend recovered
+     * from the failed run when the SDK/CLI surfaced usage before the
+     * terminal error (auth rejection mid-run, timeout, transport
+     * failure). Same shape as `BackendQuotaError.spend` so the
+     * dispatcher's post-hoc audit writer can record what the provider
+     * actually billed for a turn that produced no `AgentResult`.
+     * `null` when the failure happened before any usage was observed.
+     */
+    readonly spend: BackendQuotaSpend | null;
+    constructor(backendId: BackendId, kind: "quota" | "auth" | "max_turns" | "timeout" | "model_unavailable" | "policy_denied" | "other_non_retryable", cause: unknown, 
+    /**
+     * PREPASS_COST_REDUCTION_PLAN.md N1 — best-effort spend recovered
+     * from the failed run when the SDK/CLI surfaced usage before the
+     * terminal error (auth rejection mid-run, timeout, transport
+     * failure). Same shape as `BackendQuotaError.spend` so the
+     * dispatcher's post-hoc audit writer can record what the provider
+     * actually billed for a turn that produced no `AgentResult`.
+     * `null` when the failure happened before any usage was observed.
+     */
+    spend?: BackendQuotaSpend | null);
 }
+/**
+ * Recover the spend payload from a backend failover signal, regardless
+ * of which of the two error classes carries it. Handles the nested
+ * `BackendDecisiveFailure(kind="quota", cause=BackendQuotaError)` wrap
+ * the router produces, preferring the inner quota error's spend when
+ * both layers carry one. Returns `null` for non-backend errors.
+ *
+ * PREPASS_COST_REDUCTION_PLAN.md N1 — shared by the dispatcher's
+ * post-hoc audit writer and the pre-pass fan-out runner so both
+ * failure paths record the same figure for the same error.
+ */
+export declare function extractBackendSpend(error: unknown): BackendQuotaSpend | null;

package/dist/core/agent-core.js

@@ -93,11 +93,46 @@ export class BackendDecisiveFailure extends Error {
     backendId;
     kind;
     cause;
-    constructor(backendId, kind, cause) {
+    spend;
+    constructor(backendId, kind, cause, 
+    /**
+     * PREPASS_COST_REDUCTION_PLAN.md N1 — best-effort spend recovered
+     * from the failed run when the SDK/CLI surfaced usage before the
+     * terminal error (auth rejection mid-run, timeout, transport
+     * failure). Same shape as `BackendQuotaError.spend` so the
+     * dispatcher's post-hoc audit writer can record what the provider
+     * actually billed for a turn that produced no `AgentResult`.
+     * `null` when the failure happened before any usage was observed.
+     */
+    spend = null) {
         super(`${backendId} decisive failure: ${kind}`);
         this.backendId = backendId;
         this.kind = kind;
         this.cause = cause;
+        this.spend = spend;
         this.name = "BackendDecisiveFailure";
     }
 }
+/**
+ * Recover the spend payload from a backend failover signal, regardless
+ * of which of the two error classes carries it. Handles the nested
+ * `BackendDecisiveFailure(kind="quota", cause=BackendQuotaError)` wrap
+ * the router produces, preferring the inner quota error's spend when
+ * both layers carry one. Returns `null` for non-backend errors.
+ *
+ * PREPASS_COST_REDUCTION_PLAN.md N1 — shared by the dispatcher's
+ * post-hoc audit writer and the pre-pass fan-out runner so both
+ * failure paths record the same figure for the same error.
+ */
+export function extractBackendSpend(error) {
+    if (error instanceof BackendQuotaError) {
+        return error.spend;
+    }
+    if (error instanceof BackendDecisiveFailure) {
+        if (error.cause instanceof BackendQuotaError && error.cause.spend) {
+            return error.cause.spend;
+        }
+        return error.spend;
+    }
+    return null;
+}

package/dist/core/agents/activity-scan-cadence.d.ts

@@ -0,0 +1,103 @@
+/**
+ * Activity-scan cadence resolution (AGENTS_HUB_REDESIGN_PLAN.md §2).
+ *
+ * The activity-scan Agent's firing window (interval + active hours) and its
+ * observation-threshold gate live on the **agent row** —
+ * `agents.metadata_json.runtime_window`, written by `PATCH /api/agents/
+ * activity-scan` (`schedule_window` body block) and preserved across loader
+ * re-runs / `npm i -g` by `loader.ts:nextMetadata`. The `activityScan*`
+ * config keys (`hourlyCheck*` before the v0.1.11 rename) are deprecated but
+ * still parsed; they act as the per-field fallback so a value an operator
+ * persisted pre-redesign keeps working until they touch the agent-level
+ * setting.
+ *
+ * Resolution order, per field: `runtime_window` override → legacy config key
+ * (which itself carries the shipped default). Pure module — callers fetch the
+ * stored override via `agents-store.ts:getRuntimeWindow` and supply the live
+ * config; this keeps the precedence logic in the 100%-coverage set.
+ */
+/** Field bounds, shared by the PATCH validator and the sanitizer. */
+export declare const RUNTIME_WINDOW_BOUNDS: {
+    readonly interval_minutes: {
+        readonly min: 5;
+        readonly max: 1440;
+    };
+    readonly active_start_hour: {
+        readonly min: 0;
+        readonly max: 23;
+    };
+    readonly active_end_hour: {
+        readonly min: 1;
+        readonly max: 24;
+    };
+    readonly min_observations: {
+        readonly min: 0;
+        readonly max: 1000;
+    };
+};
+export type RuntimeWindowField = keyof typeof RUNTIME_WINDOW_BOUNDS;
+export declare const RUNTIME_WINDOW_FIELDS: readonly RuntimeWindowField[];
+/**
+ * The persisted shape under `metadata_json.runtime_window`. Every field is
+ * optional — only operator-touched fields are stored, so an untouched field
+ * keeps tracking the config fallback.
+ */
+export interface RuntimeWindowOverride {
+    interval_minutes?: number;
+    active_start_hour?: number;
+    active_end_hour?: number;
+    min_observations?: number;
+}
+/**
+ * The legacy config keys the resolver falls back to. Fields are optional at
+ * the type level so partially-stubbed test configs (and any pre-schema boot
+ * edge) resolve to the shipped defaults instead of producing a `NaN` cron.
+ */
+export interface ActivityScanCadenceConfig {
+    activityScanIntervalMinutes?: number;
+    activityScanActiveStartHour?: number;
+    activityScanActiveEndHour?: number;
+    activityScanMinObservations?: number;
+}
+/** Shipped defaults — mirror `runtime-settings.ts` (`activityScan*` keys). */
+export declare const ACTIVITY_SCAN_CADENCE_DEFAULTS: {
+    readonly intervalMinutes: 120;
+    readonly activeStartHour: 4;
+    readonly activeEndHour: 24;
+    readonly minObservations: 1;
+};
+/** Fully-resolved cadence every consumer (scheduler, gate, API) reads. */
+export interface ResolvedActivityScanCadence {
+    intervalMinutes: number;
+    activeStartHour: number;
+    activeEndHour: number;
+    minObservations: number;
+}
+/** True when `value` is an integer within the field's bounds. */
+export declare function isValidRuntimeWindowValue(field: RuntimeWindowField, value: unknown): value is number;
+/**
+ * Sanitize a raw `metadata_json.runtime_window` blob (untrusted: hand-edited
+ * DBs, older daemons). Out-of-bounds / non-integer fields are dropped — the
+ * resolver then falls back to config for them rather than failing the boot.
+ */
+export declare function parseRuntimeWindowOverride(value: unknown): RuntimeWindowOverride;
+export declare function resolveActivityScanCadence(override: RuntimeWindowOverride | undefined, config: ActivityScanCadenceConfig): ResolvedActivityScanCadence;
+export type RuntimeWindowMergeResult = {
+    ok: true;
+    value: RuntimeWindowOverride;
+    cadenceChanged: boolean;
+} | {
+    ok: false;
+    field: string;
+    error: "invalid_field_value" | "invalid_window";
+};
+/**
+ * Merge a PATCH `schedule_window` block onto the stored override. Per-field
+ * type/bounds are validated; the cross-field window check (`end > start`) runs
+ * against the post-merge **resolved** values so a partial patch can't sneak an
+ * empty window past per-field validation. `null` resets a field back to the
+ * config fallback. `cadenceChanged` tells the route whether a cron rebuild
+ * (`reloadCrons`) is needed — `min_observations` is a fire-time gate and never
+ * requires one.
+ */
+export declare function mergeRuntimeWindow(current: RuntimeWindowOverride, patch: Record<string, unknown>, config: ActivityScanCadenceConfig): RuntimeWindowMergeResult;