@aitne/daemon 0.1.9 → 0.1.11

package/dist/core/agents/activity-scan-cadence.js

@@ -0,0 +1,127 @@
+/**
+ * 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 const RUNTIME_WINDOW_BOUNDS = {
+    interval_minutes: { min: 5, max: 1440 },
+    active_start_hour: { min: 0, max: 23 },
+    active_end_hour: { min: 1, max: 24 },
+    min_observations: { min: 0, max: 1000 },
+};
+export const RUNTIME_WINDOW_FIELDS = Object.keys(RUNTIME_WINDOW_BOUNDS);
+/** Shipped defaults — mirror `runtime-settings.ts` (`activityScan*` keys). */
+export const ACTIVITY_SCAN_CADENCE_DEFAULTS = {
+    intervalMinutes: 120,
+    activeStartHour: 4,
+    activeEndHour: 24,
+    minObservations: 1,
+};
+/** True when `value` is an integer within the field's bounds. */
+export function isValidRuntimeWindowValue(field, value) {
+    if (typeof value !== "number" || !Number.isInteger(value))
+        return false;
+    const { min, max } = RUNTIME_WINDOW_BOUNDS[field];
+    return value >= min && value <= max;
+}
+/**
+ * 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 function parseRuntimeWindowOverride(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        return {};
+    const raw = value;
+    const out = {};
+    for (const field of RUNTIME_WINDOW_FIELDS) {
+        const v = raw[field];
+        if (isValidRuntimeWindowValue(field, v))
+            out[field] = v;
+    }
+    return out;
+}
+/**
+ * Resolve the effective cadence: per-field `runtime_window` override, else the
+ * legacy config key. A start ≥ end pairing (possible when an override touches
+ * only one side of an old config window) is repaired by widening the end to
+ * `start + 1` so `buildActivityScanCronExpr` always receives a non-empty window.
+ */
+/** Pick `v` when it is a finite number, else `fallback`. */
+function num(v, fallback) {
+    return typeof v === "number" && Number.isFinite(v) ? v : fallback;
+}
+export function resolveActivityScanCadence(override, config) {
+    const o = override ?? {};
+    const activeStartHour = o.active_start_hour
+        ?? num(config.activityScanActiveStartHour, ACTIVITY_SCAN_CADENCE_DEFAULTS.activeStartHour);
+    let activeEndHour = o.active_end_hour
+        ?? num(config.activityScanActiveEndHour, ACTIVITY_SCAN_CADENCE_DEFAULTS.activeEndHour);
+    if (activeEndHour <= activeStartHour)
+        activeEndHour = Math.min(activeStartHour + 1, 24);
+    return {
+        intervalMinutes: o.interval_minutes
+            ?? num(config.activityScanIntervalMinutes, ACTIVITY_SCAN_CADENCE_DEFAULTS.intervalMinutes),
+        activeStartHour,
+        activeEndHour,
+        minObservations: o.min_observations
+            ?? num(config.activityScanMinObservations, ACTIVITY_SCAN_CADENCE_DEFAULTS.minObservations),
+    };
+}
+/**
+ * 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 function mergeRuntimeWindow(current, patch, config) {
+    const next = { ...current };
+    let cadenceChanged = false;
+    for (const [key, value] of Object.entries(patch)) {
+        if (!RUNTIME_WINDOW_FIELDS.includes(key)) {
+            return { ok: false, field: `schedule_window.${key}`, error: "invalid_field_value" };
+        }
+        const field = key;
+        if (value === null) {
+            if (next[field] !== undefined) {
+                delete next[field];
+                if (field !== "min_observations")
+                    cadenceChanged = true;
+            }
+            continue;
+        }
+        if (!isValidRuntimeWindowValue(field, value)) {
+            return { ok: false, field: `schedule_window.${field}`, error: "invalid_field_value" };
+        }
+        if (next[field] !== value) {
+            next[field] = value;
+            if (field !== "min_observations")
+                cadenceChanged = true;
+        }
+    }
+    const requestedEnd = next.active_end_hour
+        ?? num(config.activityScanActiveEndHour, ACTIVITY_SCAN_CADENCE_DEFAULTS.activeEndHour);
+    const requestedStart = next.active_start_hour
+        ?? num(config.activityScanActiveStartHour, ACTIVITY_SCAN_CADENCE_DEFAULTS.activeStartHour);
+    if (requestedEnd <= requestedStart) {
+        return { ok: false, field: "schedule_window.active_end_hour", error: "invalid_window" };
+    }
+    return { ok: true, value: next, cadenceChanged };
+}

package/dist/core/agents/agent-route-override.d.ts

@@ -0,0 +1,53 @@
+import type { BackendId, ProcessModelTier } from "@aitne/shared";
+/**
+ * Built-in Agent runtime route override (AGENT_DEFINITIONS_DESIGN.md §6.4.1,
+ * runtime wiring).
+ *
+ * A built-in Agent's Definition-tab edits land in
+ * `agents.metadata_json.override_snapshot`. Until this module existed they
+ * were display-only — routing stayed governed entirely by
+ * `process_backend_config`. `BackendRouter.resolveBinding` now calls
+ * `extractAgentRouteOverride` on the snapshot of the firing's resolved Agent
+ * (`event.data.agentId`, stamped by `Dispatcher.beginAgentExecution`) and
+ * layers the result UNDER any caller-explicit options:
+ *
+ *     caller-explicit (chat picker, run-now hint, schedule row)
+ *       > agent override (this module)
+ *         > process_backend_config / process-key defaults
+ *
+ * Pure + dependency-light so it stays in the 100%-coverage set; the router
+ * supplies the snapshot it read from the `agents` row.
+ */
+export interface AgentRouteOverride {
+    /** Tier override, applied as a `requestedTier` default. */
+    tier: ProcessModelTier | null;
+    /** Model pin; when set, `backendId` names the owning backend. */
+    modelId: string | null;
+    /** Owning backend for `modelId` (stored, or inferred from the registry). */
+    backendId: BackendId | null;
+    /** Per-execution turn cap, applied onto the resolved binding. */
+    maxTurns: number | null;
+    /** Per-execution budget cap, applied onto the resolved binding. */
+    maxBudgetUsd: number | null;
+}
+/**
+ * Find the backend that owns `modelId` in the static model registry. Needed
+ * for override snapshots written before `backend.backend_id` existed (the
+ * model field was a free-text input then). Returns `null` for an id no
+ * registered backend knows — the model pin is dropped in that case rather
+ * than guessed, because executing a model id on the wrong backend fails the
+ * whole firing.
+ */
+export declare function inferBackendForModel(modelId: string): BackendId | null;
+/**
+ * Extract the routing-relevant overrides from a built-in's
+ * `override_snapshot`. Returns `null` when the snapshot carries nothing that
+ * affects routing (so the router can skip the merge entirely). Values are
+ * re-guarded with the same contracts `override-merge.ts` enforces —
+ * defence-in-depth against a hand-edited snapshot; an out-of-contract value
+ * is dropped, never thrown on.
+ *
+ * A model pin without a resolvable backend (no stored `backend.backend_id`,
+ * no registry match) drops the pin but keeps the tier/limit overrides.
+ */
+export declare function extractAgentRouteOverride(snapshot: unknown): AgentRouteOverride | null;

package/dist/core/agents/agent-route-override.js

@@ -0,0 +1,69 @@
+import { AGENT_TIERS, BACKEND_IDS } from "@aitne/shared";
+import { findRegisteredModel } from "../backends/model-registry.js";
+function isTier(value) {
+    return typeof value === "string" && AGENT_TIERS.includes(value);
+}
+function isBackendId(value) {
+    return typeof value === "string" && BACKEND_IDS.includes(value);
+}
+function isPositiveInt(value) {
+    return typeof value === "number" && Number.isInteger(value) && value > 0;
+}
+function isNonNegativeFinite(value) {
+    return typeof value === "number" && Number.isFinite(value) && value >= 0;
+}
+/**
+ * Find the backend that owns `modelId` in the static model registry. Needed
+ * for override snapshots written before `backend.backend_id` existed (the
+ * model field was a free-text input then). Returns `null` for an id no
+ * registered backend knows — the model pin is dropped in that case rather
+ * than guessed, because executing a model id on the wrong backend fails the
+ * whole firing.
+ */
+export function inferBackendForModel(modelId) {
+    for (const backendId of BACKEND_IDS) {
+        if (findRegisteredModel(backendId, modelId))
+            return backendId;
+    }
+    return null;
+}
+/**
+ * Extract the routing-relevant overrides from a built-in's
+ * `override_snapshot`. Returns `null` when the snapshot carries nothing that
+ * affects routing (so the router can skip the merge entirely). Values are
+ * re-guarded with the same contracts `override-merge.ts` enforces —
+ * defence-in-depth against a hand-edited snapshot; an out-of-contract value
+ * is dropped, never thrown on.
+ *
+ * A model pin without a resolvable backend (no stored `backend.backend_id`,
+ * no registry match) drops the pin but keeps the tier/limit overrides.
+ */
+export function extractAgentRouteOverride(snapshot) {
+    if (typeof snapshot !== "object" || snapshot === null || Array.isArray(snapshot)) {
+        return null;
+    }
+    const snap = snapshot;
+    const tier = isTier(snap["backend.tier"]) ? snap["backend.tier"] : null;
+    const rawModel = snap["backend.model"];
+    let modelId = typeof rawModel === "string" && rawModel.length > 0 ? rawModel : null;
+    let backendId = null;
+    if (modelId !== null) {
+        const rawBackend = snap["backend.backend_id"];
+        backendId = isBackendId(rawBackend) ? rawBackend : inferBackendForModel(modelId);
+        if (backendId === null)
+            modelId = null;
+    }
+    const maxTurns = isPositiveInt(snap["limits.max_turns"])
+        ? snap["limits.max_turns"]
+        : null;
+    const maxBudgetUsd = isNonNegativeFinite(snap["limits.max_budget_usd"])
+        ? snap["limits.max_budget_usd"]
+        : null;
+    if (tier === null
+        && modelId === null
+        && maxTurns === null
+        && maxBudgetUsd === null) {
+        return null;
+    }
+    return { tier, modelId, backendId, maxTurns, maxBudgetUsd };
+}

package/dist/core/agents/builtin-registry.d.ts

@@ -29,8 +29,8 @@ import type { ProcessKey, StopWarning } from "@aitne/shared";
  */
 /**
  * Resolves a built-in's cron expression from the live `dayBoundaryHour`
- * config. `null` for the interval-gated `hourly-check`, whose cadence is a
- * runtime window (`buildHourlyCronExpr(intervalMinutes, activeStart,
+ * config. `null` for the interval-gated `activity-scan`, whose cadence is a
+ * runtime window (`buildActivityScanCronExpr(intervalMinutes, activeStart,
  * activeEnd)`), not a fixed expression — the loader's drift check is a no-op
  * for a `null` resolver (§5.5.1).
  */
@@ -39,8 +39,8 @@ export type CronExpressionResolver = (config: {
 }) => string;
 /**
  * How `setupRecurringJobs` fires a built-in. NB: a non-null `processKey` does
- * NOT imply `emit_routine`/`queue_wake` — `hourly-check` carries
- * `routine.hourly_check` yet fires via `in_process_callback`.
+ * NOT imply `emit_routine`/`queue_wake` — `activity-scan` carries
+ * `routine.activity_scan` yet fires via `in_process_callback`.
  *
  *   - `emit_routine`  — `emitRoutine(routine, data?)` puts a `routine.<name>`
  *     event on the bus. `data` is the fixed payload the scheduler passes; the
@@ -50,7 +50,7 @@ export type CronExpressionResolver = (config: {
  *     baked literal would be wrong).
  *   - `queue_wake`    — `queueMorningRoutineWake(...)` enqueues a durable wake
  *     row instead of a transient event (morning-routine only).
- *   - `in_process_callback` — a typed daemon callback (`onHourlyCheck`,
+ *   - `in_process_callback` — a typed daemon callback (`onActivityScan`,
  *     `onRoadmapMaintenance`, `onContextIndexReconcile`); the last two are
  *     no-LLM passes with `processKey: null`.
  */
@@ -65,6 +65,35 @@ export type BuiltinSchedulerFn = {
     kind: "in_process_callback";
     callbackName: string;
 };
+/**
+ * Hub grouping for the `/agents` dashboard (AGENTS_HUB_REDESIGN_PLAN.md §1).
+ * Built-ins declare one of the three operational categories; user Agents are
+ * implicitly `"user"` at the API layer (not a registry value).
+ *
+ *   - `synthesis`   — routines that write the user-facing synthesis surfaces
+ *     (today.md, journals, reviews).
+ *   - `monitoring`  — interval watchers that triage observations and surface
+ *     activity proactively.
+ *   - `maintenance` — mechanical / background upkeep passes.
+ */
+export declare const AGENT_CATEGORIES: readonly ["synthesis", "monitoring", "maintenance"];
+export type AgentCategory = (typeof AGENT_CATEGORIES)[number];
+/**
+ * A context-vault policy file a built-in reads at prompt-assembly time —
+ * its editable "rulebook" surface (AGENTS_HUB_REDESIGN_PLAN.md §1 / §4.2).
+ * The dashboard's per-agent Rulebook tab renders one editor per entry,
+ * loading/saving through the context API chokepoint (`/api/context/<path>`);
+ * the vault stays the storage, this is declaration only. Paths are the
+ * canonical class-prefixed form (`context-paths.ts`).
+ */
+export interface AgentPolicyFile {
+    /** Canonical vault-relative path, e.g. `policies/routines/morning.md`. */
+    path: string;
+    /** Short editor-card title, e.g. "Morning rulebook". */
+    label: string;
+    /** One-liner explaining what the file controls. */
+    description: string;
+}
 export interface BuiltinAgentRegistryEntry {
     /** Kebab-case slug; also the `agents.id` and the `agent.md` directory name. */
     slug: string;
@@ -80,7 +109,7 @@ export interface BuiltinAgentRegistryEntry {
     description: string;
     /**
      * Cron with `{dayBoundaryHour}` / `{dayBoundaryHour-1}` resolved from live
-     * config, or `null` for the runtime-window `hourly-check` (§5.5.1).
+     * config, or `null` for the runtime-window `activity-scan` (§5.5.1).
      */
     cronExpression: CronExpressionResolver | null;
     /**
@@ -103,6 +132,14 @@ export interface BuiltinAgentRegistryEntry {
     stopWarning: StopWarning;
     /** The mechanism `setupRecurringJobs` uses to fire this slug. */
     schedulerFn: BuiltinSchedulerFn;
+    /** Hub grouping for the `/agents` dashboard (see `AGENT_CATEGORIES`). */
+    category: AgentCategory;
+    /**
+     * The vault policy files this built-in reads at prompt-assembly time —
+     * surfaced as its Rulebook tab. Empty for built-ins with no editable
+     * rulebook (no-LLM passes, sweeps).
+     */
+    policyFiles: readonly AgentPolicyFile[];
 }
 export declare const BUILTIN_AGENT_REGISTRY: readonly BuiltinAgentRegistryEntry[];
 /** Slug → entry, for O(1) lookup from the loader and the scheduler gate. */
@@ -115,15 +152,15 @@ export declare function getBuiltinRegistryEntry(slug: string): BuiltinAgentRegis
 export declare function isBuiltinAgentSlug(slug: string): boolean;
 /**
  * The live config a runtime-window built-in's cadence is resolved from. Today
- * the only runtime-window built-in is `hourly-check`, whose firing window is
- * `buildHourlyCronExpr(intervalMinutes, activeStart, activeEnd)` — so the three
- * `hourlyCheck*` fields are all that's needed. A narrow shape (not the whole
+ * the only runtime-window built-in is `activity-scan`, whose firing window is
+ * `buildActivityScanCronExpr(intervalMinutes, activeStart, activeEnd)` — so the three
+ * `activityScan*` fields are all that's needed. A narrow shape (not the whole
  * `AgentConfig`) keeps this module pure / coverage-friendly.
  */
 export interface RuntimeWindowCadenceConfig {
-    hourlyCheckIntervalMinutes: number;
-    hourlyCheckActiveStartHour: number;
-    hourlyCheckActiveEndHour: number;
+    activityScanIntervalMinutes: number;
+    activityScanActiveStartHour: number;
+    activityScanActiveEndHour: number;
 }
 /**
  * The interval cadence of a runtime-window built-in: how often it fires
@@ -146,8 +183,8 @@ export interface IntervalCadence {
  *
  * A built-in is "runtime-window" iff its registry `cronExpression` resolver is
  * `null` — the documented marker (§5.5.1) that its cadence is owned by
- * `buildHourlyCronExpr` from live config, not a baked cron. Today `hourly-check`
- * is the sole such entry, so the mapping reads the `hourlyCheck*` config. A
+ * `buildActivityScanCronExpr` from live config, not a baked cron. Today `activity-scan`
+ * is the sole such entry, so the mapping reads the `activityScan*` config. A
  * second runtime-window built-in would need its own branch here — the
  * `cronExpression === null` gate plus this comment keep that requirement
  * visible. Pure: the caller supplies the live config (read at request time so a

package/dist/core/agents/builtin-registry.js

@@ -1,3 +1,15 @@
+/**
+ * Hub grouping for the `/agents` dashboard (AGENTS_HUB_REDESIGN_PLAN.md §1).
+ * Built-ins declare one of the three operational categories; user Agents are
+ * implicitly `"user"` at the API layer (not a registry value).
+ *
+ *   - `synthesis`   — routines that write the user-facing synthesis surfaces
+ *     (today.md, journals, reviews).
+ *   - `monitoring`  — interval watchers that triage observations and surface
+ *     activity proactively.
+ *   - `maintenance` — mechanical / background upkeep passes.
+ */
+export const AGENT_CATEGORIES = ["synthesis", "monitoring", "maintenance"];
 /**
  * Backward-wrapping hour arithmetic shared by the `{dayBoundaryHour-1}`
  * builtins. `(dayBoundaryHour + 23) % 24` in the scheduler is the same value;
@@ -25,6 +37,28 @@ export const BUILTIN_AGENT_REGISTRY = [
             reactivation_hint: "Re-enable from /agents/morning-routine. The next firing catches up with a broader observation window.",
         },
         schedulerFn: { kind: "queue_wake", routine: "morning_routine" },
+        category: "synthesis",
+        // journal-format / journal-export hang off morning-routine because the
+        // morning pipeline is their only consumer (task-flows
+        // `routine.morning_routine_{today,journal}` + the morning composers —
+        // verified 2026-06-10, AGENTS_HUB_REDESIGN_PLAN.md §1).
+        policyFiles: [
+            {
+                path: "policies/routines/morning.md",
+                label: "Morning rulebook",
+                description: "Checks and rules injected into the morning routine prompt.",
+            },
+            {
+                path: "policies/journal-format.md",
+                label: "Journal format",
+                description: "Template and voice rules for the daily journal synthesis.",
+            },
+            {
+                path: "policies/journal-export.md",
+                label: "Journal export rules",
+                description: "Redaction and inclusion rules applied when journal content is exported.",
+            },
+        ],
     },
     {
         slug: "evening-review",
@@ -43,6 +77,14 @@ export const BUILTIN_AGENT_REGISTRY = [
             reactivation_hint: "Re-enable from /agents/evening-review. Resumes on the next 18:00 firing.",
         },
         schedulerFn: { kind: "emit_routine", routine: "evening_review" },
+        category: "synthesis",
+        policyFiles: [
+            {
+                path: "policies/routines/evening.md",
+                label: "Evening rulebook",
+                description: "Checks and rules injected into the evening review prompt.",
+            },
+        ],
     },
     {
         slug: "weekly-review",
@@ -61,6 +103,14 @@ export const BUILTIN_AGENT_REGISTRY = [
             reactivation_hint: "Re-enable from /agents/weekly-review. Resumes on the next Friday 19:00 firing.",
         },
         schedulerFn: { kind: "emit_routine", routine: "weekly_review" },
+        category: "synthesis",
+        policyFiles: [
+            {
+                path: "policies/routines/weekly.md",
+                label: "Weekly rulebook",
+                description: "Checks and rules injected into the weekly review prompt.",
+            },
+        ],
     },
     {
         slug: "monthly-review",
@@ -78,33 +128,50 @@ export const BUILTIN_AGENT_REGISTRY = [
                 "Month-end retrospective",
             ],
             dependent_agents: [],
-            reactivation_hint: "Monthly review is opt-in (monthlyReviewEnabled, default off). Re-enable from /agents/monthly-review.",
+            reactivation_hint: "Monthly review is opt-in (off by default). Enable from /agents/monthly-review.",
         },
         schedulerFn: { kind: "emit_routine", routine: "monthly_review" },
+        category: "synthesis",
+        policyFiles: [
+            {
+                path: "policies/routines/monthly.md",
+                label: "Monthly rulebook",
+                description: "Checks and rules injected into the monthly review prompt.",
+            },
+        ],
     },
     {
-        slug: "hourly-check",
-        name: "Hourly Check",
+        slug: "activity-scan",
+        name: "Activity Scan",
         description: "Triages pending observations and proactively surfaces new mail / calendar / git / notion activity each interval within active hours.",
-        // Runtime-window cadence — `buildHourlyCronExpr(...)` owns the expression,
+        // Runtime-window cadence — `buildActivityScanCronExpr(...)` owns the expression,
         // so the registry resolver is `null` and the loader's drift check skips
         // this slug (§5.5.1). The Phase 4 YAML still carries a self-documenting
         // literal to satisfy the schema's `cron → expression` refinement.
         cronExpression: null,
-        processKey: "routine.hourly_check",
-        // Agent-enabled defaults true; the feature's real opt-in is the scheduler's
-        // `hourlyCheckEnabled` config gate, which is ANDed on top at fire time.
+        processKey: "routine.activity_scan",
+        // `agents.enabled` is the single on/off switch (AGENTS_HUB_REDESIGN_PLAN.md
+        // §2 — the legacy `activityScanEnabled` config gate was unified into it; a
+        // one-time boot reconcile carries an operator's old `false` forward).
         defaultEnabled: true,
         stopWarning: {
             level: "high",
             services_lost: [
-                "Hourly observation triage",
+                "Periodic observation triage",
                 "Proactive surfacing of new mail / calendar / git / notion activity",
             ],
             dependent_agents: [],
-            reactivation_hint: "Re-enable from /agents/hourly-check. Resumes on the next interval tick within active hours.",
+            reactivation_hint: "Re-enable from /agents/activity-scan. Resumes on the next interval tick within active hours.",
         },
-        schedulerFn: { kind: "in_process_callback", callbackName: "onHourlyCheck" },
+        schedulerFn: { kind: "in_process_callback", callbackName: "onActivityScan" },
+        category: "monitoring",
+        policyFiles: [
+            {
+                path: "policies/routines/activity-scan.md",
+                label: "Activity scan rulebook",
+                description: "Checks and rules injected into the activity scan prompt.",
+            },
+        ],
     },
     {
         slug: "user-profile-sweep-morning",
@@ -128,6 +195,8 @@ export const BUILTIN_AGENT_REGISTRY = [
             routine: "user_profile_sweep",
             data: { phase: "morning" },
         },
+        category: "maintenance",
+        policyFiles: [],
     },
     {
         slug: "user-profile-sweep-evening",
@@ -151,6 +220,8 @@ export const BUILTIN_AGENT_REGISTRY = [
             routine: "user_profile_sweep",
             data: { phase: "evening" },
         },
+        category: "maintenance",
+        policyFiles: [],
     },
     {
         slug: "roadmap-maintenance",
@@ -174,6 +245,8 @@ export const BUILTIN_AGENT_REGISTRY = [
             kind: "in_process_callback",
             callbackName: "onRoadmapMaintenance",
         },
+        category: "maintenance",
+        policyFiles: [],
     },
     {
         slug: "context-index-reconcile",
@@ -197,6 +270,8 @@ export const BUILTIN_AGENT_REGISTRY = [
             kind: "in_process_callback",
             callbackName: "onContextIndexReconcile",
         },
+        category: "maintenance",
+        policyFiles: [],
     },
     {
         slug: "skill-curation",
@@ -218,6 +293,8 @@ export const BUILTIN_AGENT_REGISTRY = [
         // `cadence` (daily/weekly/monthly) is read from the DB at fire time, so it
         // is intentionally absent from `data` here — see BuiltinSchedulerFn.
         schedulerFn: { kind: "emit_routine", routine: "skill_curation" },
+        category: "maintenance",
+        policyFiles: [],
     },
 ];
 /** Slug → entry, for O(1) lookup from the loader and the scheduler gate. */
@@ -238,8 +315,8 @@ export function isBuiltinAgentSlug(slug) {
  *
  * A built-in is "runtime-window" iff its registry `cronExpression` resolver is
  * `null` — the documented marker (§5.5.1) that its cadence is owned by
- * `buildHourlyCronExpr` from live config, not a baked cron. Today `hourly-check`
- * is the sole such entry, so the mapping reads the `hourlyCheck*` config. A
+ * `buildActivityScanCronExpr` from live config, not a baked cron. Today `activity-scan`
+ * is the sole such entry, so the mapping reads the `activityScan*` config. A
  * second runtime-window built-in would need its own branch here — the
  * `cronExpression === null` gate plus this comment keep that requirement
  * visible. Pure: the caller supplies the live config (read at request time so a
@@ -250,8 +327,8 @@ export function resolveRuntimeWindowCadence(slug, config) {
     if (!entry || entry.cronExpression !== null)
         return null;
     return {
-        interval_minutes: config.hourlyCheckIntervalMinutes,
-        active_start_hour: config.hourlyCheckActiveStartHour,
-        active_end_hour: config.hourlyCheckActiveEndHour,
+        interval_minutes: config.activityScanIntervalMinutes,
+        active_start_hour: config.activityScanActiveStartHour,
+        active_end_hour: config.activityScanActiveEndHour,
     };
 }

package/dist/core/agents/config-gate-reconcile.d.ts

@@ -0,0 +1,38 @@
+import type Database from "better-sqlite3";
+/**
+ * One-time enable-switch unification (AGENTS_HUB_REDESIGN_PLAN.md §2).
+ *
+ * Pre-redesign, two built-ins carried a SECOND on/off switch in runtime
+ * config, ANDed on top of `agents.enabled` at fire time:
+ *
+ *   - `activityScanEnabled` (persisted as `hourlyCheckEnabled` before the
+ *     v0.1.11 rename; default true) → activity-scan
+ *   - `monthlyReviewEnabled` (default false) → monthly-review
+ *
+ * The scheduler now consults only `agents.enabled`, so an operator's
+ * non-default config value must be carried onto the agent row exactly once —
+ * otherwise an old `hourlyCheckEnabled=false` would silently re-enable the
+ * activity scan on upgrade (and an opted-in monthly review would stop firing).
+ * The legacy settings row reaches `settings.activityScanEnabled` here via
+ * `LEGACY_RUNTIME_SETTING_KEY_ALIASES` (settings-store read aliasing), so a
+ * pre-agents-hub DB upgrading straight past the rename still carries its
+ * disable forward.
+ *
+ * Boot-time, not a DB `Migration`: it must run AFTER the agents loader has
+ * seeded the rows (migrations run before the loader), and it uses the same
+ * `setEnabled` dashboard-toggle semantics (stamps `enabled_overridden_at`).
+ * Idempotent via the `runtime_state` flag; defaults produce zero changes, so
+ * a fresh install is a flagged no-op.
+ */
+export declare const CONFIG_GATES_RECONCILED_KEY = "agents.config_gates_reconciled";
+export interface ConfigGateSettings {
+    activityScanEnabled: boolean;
+    monthlyReviewEnabled: boolean;
+}
+export interface ConfigGateReconcileResult {
+    /** False when the runtime_state flag showed the reconcile already ran. */
+    applied: boolean;
+    /** Slugs whose `agents.enabled` was changed (empty on default configs). */
+    changes: string[];
+}
+export declare function reconcileConfigGates(db: Database.Database, settings: ConfigGateSettings, now?: number): ConfigGateReconcileResult;

package/dist/core/agents/config-gate-reconcile.js

@@ -0,0 +1,51 @@
+import { getAgent, setEnabled } from "../../db/agents-store.js";
+import { readRuntimeState, writeRuntimeState } from "../../db/runtime-state.js";
+import { createLogger } from "../../logging.js";
+const logger = createLogger("agents-config-gate-reconcile");
+/**
+ * One-time enable-switch unification (AGENTS_HUB_REDESIGN_PLAN.md §2).
+ *
+ * Pre-redesign, two built-ins carried a SECOND on/off switch in runtime
+ * config, ANDed on top of `agents.enabled` at fire time:
+ *
+ *   - `activityScanEnabled` (persisted as `hourlyCheckEnabled` before the
+ *     v0.1.11 rename; default true) → activity-scan
+ *   - `monthlyReviewEnabled` (default false) → monthly-review
+ *
+ * The scheduler now consults only `agents.enabled`, so an operator's
+ * non-default config value must be carried onto the agent row exactly once —
+ * otherwise an old `hourlyCheckEnabled=false` would silently re-enable the
+ * activity scan on upgrade (and an opted-in monthly review would stop firing).
+ * The legacy settings row reaches `settings.activityScanEnabled` here via
+ * `LEGACY_RUNTIME_SETTING_KEY_ALIASES` (settings-store read aliasing), so a
+ * pre-agents-hub DB upgrading straight past the rename still carries its
+ * disable forward.
+ *
+ * Boot-time, not a DB `Migration`: it must run AFTER the agents loader has
+ * seeded the rows (migrations run before the loader), and it uses the same
+ * `setEnabled` dashboard-toggle semantics (stamps `enabled_overridden_at`).
+ * Idempotent via the `runtime_state` flag; defaults produce zero changes, so
+ * a fresh install is a flagged no-op.
+ */
+export const CONFIG_GATES_RECONCILED_KEY = "agents.config_gates_reconciled";
+export function reconcileConfigGates(db, settings, now = Date.now()) {
+    if (readRuntimeState(db, CONFIG_GATES_RECONCILED_KEY) !== null) {
+        return { applied: false, changes: [] };
+    }
+    const changes = [];
+    // Non-default legacy value → carry onto the agent row. Default values are
+    // left alone so the YAML/registry-shipped enabled state stays authoritative.
+    if (!settings.activityScanEnabled && getAgent(db, "activity-scan")?.enabled === true) {
+        setEnabled(db, "activity-scan", false, now, now);
+        changes.push("activity-scan");
+    }
+    if (settings.monthlyReviewEnabled && getAgent(db, "monthly-review")?.enabled === false) {
+        setEnabled(db, "monthly-review", true, now, now);
+        changes.push("monthly-review");
+    }
+    writeRuntimeState(db, CONFIG_GATES_RECONCILED_KEY, new Date(now).toISOString());
+    if (changes.length > 0) {
+        logger.info({ changes }, "Carried legacy config enable gates onto agent rows");
+    }
+    return { applied: true, changes };
+}