@aitne/daemon 0.1.10 → 0.1.11

package/dist/core/agents/cron-substitute.d.ts

@@ -36,7 +36,7 @@ export declare function substituteCron(expr: string, config: {
  * expression. Returns a non-fatal warning string on mismatch, or `null` when
  * they agree.
  *
- * `registryExpr` is `null` for the runtime-window builtins (`hourly-check`)
+ * `registryExpr` is `null` for the runtime-window builtins (`activity-scan`)
  * whose cadence is not a fixed expression — drift is meaningless there, so the
  * check is a no-op (returns `null`, §5.5.1). Whitespace differences are
  * normalised away before comparing.

package/dist/core/agents/cron-substitute.js

@@ -57,7 +57,7 @@ function normalizeCron(expr) {
  * expression. Returns a non-fatal warning string on mismatch, or `null` when
  * they agree.
  *
- * `registryExpr` is `null` for the runtime-window builtins (`hourly-check`)
+ * `registryExpr` is `null` for the runtime-window builtins (`activity-scan`)
  * whose cadence is not a fixed expression — drift is meaningless there, so the
  * check is a no-op (returns `null`, §5.5.1). Whitespace differences are
  * normalised away before comparing.

package/dist/core/agents/custom-routine-migration.d.ts

@@ -0,0 +1,60 @@
+import type Database from "better-sqlite3";
+/**
+ * One-time converter: legacy custom routines → user Agents
+ * (AGENTS_HUB_REDESIGN_PLAN.md §3).
+ *
+ * The retired `CustomRoutineScheduler` fired `policies/routines/custom/
+ * <slug>.md` files through its own node-cron path — invisible to `/agents`,
+ * no metrics, no execution history, a second enable switch. This converter
+ * runs at boot BEFORE the agents loader (so the loader pairs the fresh
+ * definitions with `recurring_schedules` rows in the same pass), turning each
+ * valid spec into `policies/agents/<slug>/agent.md`:
+ *
+ *   - frontmatter: cron schedule, tier, `max_budget_usd`, the spec's
+ *     `enabled` (a disabled routine migrates disabled — intent preserved);
+ *   - body: the routine's body after the legacy frontmatter (the `## Checks`
+ *     section), which the Agents pipeline uses as `task_prompt`.
+ *
+ * The source file is never deleted (user vault content): it is rewritten in
+ * place with `enabled: false` + a `migrated_to_agent:` marker so it is
+ * visibly inert. Invalid specs are left untouched and logged — they never
+ * fired under the old scheduler either.
+ *
+ * Idempotent via the `runtime_state` flag; a fresh install (no custom dir)
+ * is a flagged no-op.
+ */
+export declare const CUSTOM_ROUTINES_MIGRATED_KEY = "custom_routines.migrated_to_agents";
+export interface CustomRoutineMigrationOptions {
+    /** Context-vault root (the directory holding `policies/`). */
+    contextDir: string;
+    /** User agents root — `<contextDir>/policies/agents`. */
+    userDir: string;
+    /** IANA timezone the generated cron schedule is pinned to. */
+    timezone: string;
+    now?: () => number;
+}
+export interface CustomRoutineMigrationResult {
+    /** False when the runtime_state flag showed the migration already ran. */
+    applied: boolean;
+    migrated: Array<{
+        fromSlug: string;
+        toSlug: string;
+    }>;
+    skipped: Array<{
+        slug: string;
+        reason: string;
+    }>;
+}
+/**
+ * Body after the closing `---` fence, or the whole content if no frontmatter.
+ * Exported for direct unit tests — callers only ever pass parse-validated
+ * content, so the defensive branches are unreachable through the public path.
+ */
+export declare function stripLegacyFrontmatter(content: string): string;
+/**
+ * Mark a migrated source file inert: `enabled: false` + a
+ * `migrated_to_agent:` marker appended inside the frontmatter block.
+ * Exported for direct unit tests (see stripLegacyFrontmatter note).
+ */
+export declare function markSourceMigrated(content: string, toSlug: string): string;
+export declare function migrateCustomRoutinesToAgents(db: Database.Database, opts: CustomRoutineMigrationOptions): CustomRoutineMigrationResult;

package/dist/core/agents/custom-routine-migration.js

@@ -0,0 +1,149 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { agentDefinitionSchema } from "@aitne/shared";
+import { enumerateCustomRoutines, } from "../custom-routines.js";
+import { CONTEXT_RELATIVE_PATHS } from "../context-paths.js";
+import { renderAgentMarkdown } from "./agent-frontmatter.js";
+import { definitionToFrontmatter } from "./loader.js";
+import { isBuiltinAgentSlug } from "./builtin-registry.js";
+import { getAgent } from "../../db/agents-store.js";
+import { readRuntimeState, writeRuntimeState } from "../../db/runtime-state.js";
+import { createLogger } from "../../logging.js";
+const logger = createLogger("custom-routine-migration");
+/**
+ * One-time converter: legacy custom routines → user Agents
+ * (AGENTS_HUB_REDESIGN_PLAN.md §3).
+ *
+ * The retired `CustomRoutineScheduler` fired `policies/routines/custom/
+ * <slug>.md` files through its own node-cron path — invisible to `/agents`,
+ * no metrics, no execution history, a second enable switch. This converter
+ * runs at boot BEFORE the agents loader (so the loader pairs the fresh
+ * definitions with `recurring_schedules` rows in the same pass), turning each
+ * valid spec into `policies/agents/<slug>/agent.md`:
+ *
+ *   - frontmatter: cron schedule, tier, `max_budget_usd`, the spec's
+ *     `enabled` (a disabled routine migrates disabled — intent preserved);
+ *   - body: the routine's body after the legacy frontmatter (the `## Checks`
+ *     section), which the Agents pipeline uses as `task_prompt`.
+ *
+ * The source file is never deleted (user vault content): it is rewritten in
+ * place with `enabled: false` + a `migrated_to_agent:` marker so it is
+ * visibly inert. Invalid specs are left untouched and logged — they never
+ * fired under the old scheduler either.
+ *
+ * Idempotent via the `runtime_state` flag; a fresh install (no custom dir)
+ * is a flagged no-op.
+ */
+export const CUSTOM_ROUTINES_MIGRATED_KEY = "custom_routines.migrated_to_agents";
+/**
+ * Body after the closing `---` fence, or the whole content if no frontmatter.
+ * Exported for direct unit tests — callers only ever pass parse-validated
+ * content, so the defensive branches are unreachable through the public path.
+ */
+export function stripLegacyFrontmatter(content) {
+    if (!content.startsWith("---\n") && !content.startsWith("---\r\n"))
+        return content;
+    const afterOpen = content.startsWith("---\r\n") ? 5 : 4;
+    const endIdx = content.indexOf("\n---", afterOpen - 1);
+    if (endIdx < 0)
+        return content;
+    const afterFence = content.indexOf("\n", endIdx + 1);
+    return afterFence < 0 ? "" : content.slice(afterFence + 1);
+}
+/**
+ * Mark a migrated source file inert: `enabled: false` + a
+ * `migrated_to_agent:` marker appended inside the frontmatter block.
+ * Exported for direct unit tests (see stripLegacyFrontmatter note).
+ */
+export function markSourceMigrated(content, toSlug) {
+    let out = content.replace(/^enabled\s*:.*$/m, "enabled: false");
+    if (!/^migrated_to_agent\s*:/m.test(out)) {
+        // Insert before the closing fence of the first frontmatter block.
+        const afterOpen = out.startsWith("---\r\n") ? 5 : 4;
+        const endIdx = out.indexOf("\n---", afterOpen - 1);
+        if (endIdx >= 0) {
+            out = `${out.slice(0, endIdx)}\nmigrated_to_agent: ${toSlug}${out.slice(endIdx)}`;
+        }
+    }
+    return out;
+}
+function titleize(slug) {
+    return slug
+        .split("-")
+        .map((part) => (part.length > 0 ? part[0].toUpperCase() + part.slice(1) : part))
+        .join(" ");
+}
+function resolveTargetSlug(db, userDir, slug) {
+    const candidates = [slug, `custom-${slug}`];
+    for (const candidate of candidates) {
+        if (isBuiltinAgentSlug(candidate))
+            continue;
+        if (getAgent(db, candidate) !== null)
+            continue;
+        if (existsSync(join(userDir, candidate, "agent.md")))
+            continue;
+        return candidate;
+    }
+    return null;
+}
+export function migrateCustomRoutinesToAgents(db, opts) {
+    if (readRuntimeState(db, CUSTOM_ROUTINES_MIGRATED_KEY) !== null) {
+        return { applied: false, migrated: [], skipped: [] };
+    }
+    const now = opts.now ?? Date.now;
+    const { specs, errors } = enumerateCustomRoutines(opts.contextDir);
+    const migrated = [];
+    const skipped = [];
+    for (const { slug, error } of errors) {
+        skipped.push({ slug, reason: `parse_error:${error.kind}` });
+        logger.warn({ slug, error }, "Custom routine not migrated (parse error) — left as-is");
+    }
+    for (const spec of specs) {
+        try {
+            const result = migrateOne(db, opts, spec);
+            if (result.ok) {
+                migrated.push({ fromSlug: spec.slug, toSlug: result.toSlug });
+            }
+            else {
+                skipped.push({ slug: spec.slug, reason: result.reason });
+            }
+        }
+        catch (err) {
+            skipped.push({ slug: spec.slug, reason: "write_failed" });
+            logger.error({ err, slug: spec.slug }, "Custom routine migration failed for slug");
+        }
+    }
+    writeRuntimeState(db, CUSTOM_ROUTINES_MIGRATED_KEY, new Date(now()).toISOString());
+    if (migrated.length > 0 || skipped.length > 0) {
+        logger.info({ migrated, skipped }, "Custom routines migrated to user Agents");
+    }
+    return { applied: true, migrated, skipped };
+}
+function migrateOne(db, opts, spec) {
+    const toSlug = resolveTargetSlug(db, opts.userDir, spec.slug);
+    if (toSlug === null) {
+        logger.warn({ slug: spec.slug }, "Custom routine not migrated (slug collision)");
+        return { ok: false, reason: "slug_collision" };
+    }
+    const sourcePath = join(opts.contextDir, CONTEXT_RELATIVE_PATHS.routines.customDir, `${spec.slug}.md`);
+    const sourceContent = readFileSync(sourcePath, "utf-8");
+    const body = stripLegacyFrontmatter(sourceContent).trim();
+    const def = agentDefinitionSchema.parse({
+        slug: toSlug,
+        name: titleize(spec.slug),
+        description: `Migrated from custom routine "${spec.slug}".`,
+        kind: "user",
+        enabled: spec.enabled,
+        schedule: { kind: "cron", expression: spec.cron, timezone: opts.timezone },
+        backend: { process_key: "agent.task", tier: spec.backendTier },
+        limits: { max_budget_usd: spec.maxBudgetUsd },
+    });
+    const markdown = renderAgentMarkdown(definitionToFrontmatter(def), body.length > 0 ? body : def.description);
+    const dir = join(opts.userDir, toSlug);
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(join(dir, "agent.md"), markdown, "utf-8");
+    // Mark the source inert only AFTER the agent.md write succeeded.
+    writeFileSync(sourcePath, markSourceMigrated(sourceContent, toSlug), "utf-8");
+    logger.info({ from: spec.slug, to: toSlug }, "Custom routine migrated to user Agent");
+    return { ok: true, toSlug };
+}

package/dist/core/agents/firing-blocked.d.ts

@@ -3,7 +3,7 @@ import type Database from "better-sqlite3";
  * `agent.firing_blocked` audit throttle (AGENT_DEFINITIONS_DESIGN.md §12.3).
  *
  * When a disabled built-in Agent's cron would have fired, the scheduler records
- * the suppressed firing — but a routine on a tight cadence (hourly_check) could
+ * the suppressed firing — but a routine on a tight cadence (activity_scan) could
  * otherwise write dozens of identical audit rows a day. The throttle keeps **at
  * most one** `agent_actions(action_type='agent.firing_blocked')` row per
  * `(agent_id, agent-day)`; every subsequent suppression in the same agent-day

package/dist/core/agents/hourly-cadence.d.ts

@@ -0,0 +1,102 @@
+/**
+ * Hourly-check cadence resolution (AGENTS_HUB_REDESIGN_PLAN.md §2).
+ *
+ * The hourly-check 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/
+ * hourly-check` (`schedule_window` body block) and preserved across loader
+ * re-runs / `npm i -g` by `loader.ts:nextMetadata`. The legacy `hourlyCheck*`
+ * config keys 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 HourlyCadenceConfig {
+    hourlyCheckIntervalMinutes?: number;
+    hourlyCheckActiveStartHour?: number;
+    hourlyCheckActiveEndHour?: number;
+    hourlyCheckMinObservations?: number;
+}
+/** Shipped defaults — mirror `runtime-settings.ts` (`hourlyCheck*` keys). */
+export declare const HOURLY_CADENCE_DEFAULTS: {
+    readonly intervalMinutes: 60;
+    readonly activeStartHour: 4;
+    readonly activeEndHour: 24;
+    readonly minObservations: 1;
+};
+/** Fully-resolved cadence every consumer (scheduler, gate, API) reads. */
+export interface ResolvedHourlyCadence {
+    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 resolveHourlyCadence(override: RuntimeWindowOverride | undefined, config: HourlyCadenceConfig): ResolvedHourlyCadence;
+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: HourlyCadenceConfig): RuntimeWindowMergeResult;

package/dist/core/agents/hourly-cadence.js

@@ -0,0 +1,126 @@
+/**
+ * Hourly-check cadence resolution (AGENTS_HUB_REDESIGN_PLAN.md §2).
+ *
+ * The hourly-check 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/
+ * hourly-check` (`schedule_window` body block) and preserved across loader
+ * re-runs / `npm i -g` by `loader.ts:nextMetadata`. The legacy `hourlyCheck*`
+ * config keys 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` (`hourlyCheck*` keys). */
+export const HOURLY_CADENCE_DEFAULTS = {
+    intervalMinutes: 60,
+    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 `buildHourlyCronExpr` 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 resolveHourlyCadence(override, config) {
+    const o = override ?? {};
+    const activeStartHour = o.active_start_hour
+        ?? num(config.hourlyCheckActiveStartHour, HOURLY_CADENCE_DEFAULTS.activeStartHour);
+    let activeEndHour = o.active_end_hour
+        ?? num(config.hourlyCheckActiveEndHour, HOURLY_CADENCE_DEFAULTS.activeEndHour);
+    if (activeEndHour <= activeStartHour)
+        activeEndHour = Math.min(activeStartHour + 1, 24);
+    return {
+        intervalMinutes: o.interval_minutes
+            ?? num(config.hourlyCheckIntervalMinutes, HOURLY_CADENCE_DEFAULTS.intervalMinutes),
+        activeStartHour,
+        activeEndHour,
+        minObservations: o.min_observations
+            ?? num(config.hourlyCheckMinObservations, HOURLY_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.hourlyCheckActiveEndHour, HOURLY_CADENCE_DEFAULTS.activeEndHour);
+    const requestedStart = next.active_start_hour
+        ?? num(config.hourlyCheckActiveStartHour, HOURLY_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/loader-boot.js

@@ -4,6 +4,8 @@ import { createLogger } from "../../logging.js";
 import { AgentEnabledCache, loadAgents, resolveTimezone, } from "./loader.js";
 import { startAgentsWatcher, } from "./loader-watcher.js";
 import { createRecurringSchedulePort } from "./recurring-schedule-adapter.js";
+import { reconcileConfigGates } from "./config-gate-reconcile.js";
+import { migrateCustomRoutinesToAgents } from "./custom-routine-migration.js";
 import { listAllSkillSlugs } from "../release-assets.js";
 import { resolveUserSkillsRoot } from "../user-skills-root.js";
 /**
@@ -75,7 +77,28 @@ export function buildAgentLoadOptions(deps) {
  */
 export function bootstrapAgents(deps) {
     const opts = buildAgentLoadOptions(deps);
+    // One-time legacy custom-routine conversion (AGENTS_HUB_REDESIGN_PLAN §3).
+    // Runs BEFORE loadAgents so the loader pairs the generated user agent.md
+    // files with recurring_schedules rows in this same boot pass. Never throws
+    // out of boot.
+    try {
+        migrateCustomRoutinesToAgents(deps.db, {
+            contextDir: getContextDir(deps.config, deps.db),
+            userDir: opts.userDir,
+            timezone: resolveTimezone(undefined, deps.config.timezone),
+        });
+    }
+    catch (err) {
+        logger.error({ err }, "Custom-routine migration failed (continuing boot)");
+    }
     const result = loadAgents(deps.db, opts);
+    // One-time legacy gate carry-over (activityScanEnabled / monthlyReviewEnabled
+    // → agents.enabled). Must run AFTER the loader has seeded the rows;
+    // runtime_state-flagged so it never re-applies (AGENTS_HUB_REDESIGN_PLAN §2).
+    reconcileConfigGates(deps.db, {
+        activityScanEnabled: deps.config.activityScanEnabled,
+        monthlyReviewEnabled: deps.config.monthlyReviewEnabled,
+    });
     if (result.invalid.length > 0) {
         logger.warn({ count: result.invalid.length, slugs: result.invalid.map((d) => d.slug) }, "Some Agent definitions failed to load (surfaced under /api/agents include_invalid)");
     }

package/dist/core/agents/loader.d.ts

@@ -51,6 +51,14 @@ export interface RecurringCreateInput {
     tier: string | null;
     backendId: string | null;
     recurrence: AgentRecurrenceSpec;
+    /**
+     * Row-local flags copied into every materialised `agent_schedule` row by
+     * `generateNextScheduleRow` (the `pin_to_quiet_hours_end` precedent). Today
+     * carries `defer_in_quiet_hours: true` for opted-in Agents
+     * (QUIET_HOURS_HARDENING_PLAN.md §6); omitted/empty otherwise (the store
+     * defaults the column to `{}`).
+     */
+    taskContext?: Record<string, unknown>;
 }
 /** Divergent-field patch applied when reconciling a paired recurring row (YAML wins). */
 export interface RecurringUpdateInput {
@@ -61,6 +69,9 @@ export interface RecurringUpdateInput {
     tier?: string | null;
     backendId?: string | null;
     recurrence?: AgentRecurrenceSpec;
+    /** Full replacement `task_context` (the loader merges off the row's current
+     *  value, so unrelated keys survive a flag flip). */
+    taskContext?: Record<string, unknown>;
 }
 /**
  * Recurring-schedule pairing + auto-import port (§6.1 step 5 / §6.5). The
@@ -162,6 +173,14 @@ export declare function validateDefinition(def: AgentDefinition, source: AgentSo
  * row with no override) lets the YAML win.
  */
 export declare function resolveEnabled(baseEnabled: boolean, existing: AgentDTO | null, fileMtimeMs: number): boolean;
+/**
+ * Render the subset of an `AgentDefinition` worth persisting to an auto-imported
+ * `agent.md` frontmatter. Schema defaults (limits/tools/on_error) are omitted
+ * to keep the generated file readable; they re-populate on the next parse.
+ * Exported for the custom-routine migration, which materialises user Agents
+ * through the same shape (AGENTS_HUB_REDESIGN_PLAN.md §3).
+ */
+export declare function definitionToFrontmatter(def: AgentDefinition): Record<string, unknown>;
 /**
  * Load every Agent definition into the `agents` table. Never throws; per-file
  * failures land in {@link LoadAgentsResult.invalid}. Order: auto-import (writes

package/dist/core/agents/loader.js

@@ -32,7 +32,7 @@ import { cronToRecurrenceSpec, recurrenceSpecToCron, } from "./recurrence-conver
  * the real daemon modules.
  */
 const baseLogger = createLogger("agents-loader");
-/** A built-in whose registry `cronExpression` is `null` (hourly-check) still
+/** A built-in whose registry `cronExpression` is `null` (activity-scan) still
  *  needs a schema-valid `schedule.expression` when synthesised from the
  *  registry. The loader never schedules from it (the runtime window owns the
  *  cadence, §5.5.1); this literal is self-documenting only and drift-free
@@ -236,6 +236,12 @@ function nextMetadata(existing, hashChanged) {
     if (prior.override_snapshot !== undefined) {
         meta.override_snapshot = prior.override_snapshot;
     }
+    // Runtime-window cadence overrides (activity-scan interval / active hours /
+    // observation gate) are operator state exactly like override_snapshot — they
+    // must survive every loader re-run and `npm i -g`.
+    if (prior.runtime_window !== undefined) {
+        meta.runtime_window = prior.runtime_window;
+    }
     const priorVersion = typeof prior.version_counter === "number" ? prior.version_counter : 0;
     meta.version_counter = hashChanged ? priorVersion + 1 : Math.max(priorVersion, 1);
     // last_error is intentionally dropped: this path runs only for a definition
@@ -372,6 +378,14 @@ function pairRecurring(def, expression, body, existing, port, resolvedTz, resolv
         tier: def.backend.tier,
         backendId: def.backend.backend_id,
         recurrence: spec,
+        // QUIET_HOURS_HARDENING_PLAN.md §6 — `generateNextScheduleRow` spreads the
+        // row's `task_context` into every materialised `agent_schedule` row, so the
+        // scheduler can read the flag row-locally at claim time (no `agents` join).
+        // Opt-in only: an absent key keeps default-false context clean (the
+        // `pin_to_quiet_hours_end` convention on `dm_session` rows).
+        taskContext: def.schedule.defer_in_quiet_hours
+            ? { defer_in_quiet_hours: true }
+            : {},
     };
     const existingId = existing?.recurringScheduleId ?? null;
     if (existingId !== null) {
@@ -403,6 +417,22 @@ function pairRecurring(def, expression, body, existing, port, resolvedTz, resolv
             // Structural compare so a re-parsed-but-identical spec is not a "change".
             if (stableStringify(row.recurrence) !== stableStringify(spec))
                 patch.recurrence = spec;
+            // Reconcile the quiet-hours opt-in (YAML wins), merging off the row's
+            // current context so unrelated keys survive the flip. A `taskContext`
+            // update does NOT cancel + re-materialise the pending row (only
+            // recurrence/enabled do), so a pending materialisation keeps the prior
+            // flag until its next generation — the same one-cycle staleness the
+            // model/tier pins already have.
+            const rowOptedIn = row.taskContext.defer_in_quiet_hours === true;
+            const wantOptIn = def.schedule.defer_in_quiet_hours;
+            if (rowOptedIn !== wantOptIn) {
+                const nextContext = { ...row.taskContext };
+                if (wantOptIn)
+                    nextContext.defer_in_quiet_hours = true;
+                else
+                    delete nextContext.defer_in_quiet_hours;
+                patch.taskContext = nextContext;
+            }
             if (Object.keys(patch).length > 0)
                 port.update(existingId, patch);
             return existingId;
@@ -504,8 +534,10 @@ function autoImportOrphans(db, opts, port, result, importedSlugs, logger, now) {
  * Render the subset of an `AgentDefinition` worth persisting to an auto-imported
  * `agent.md` frontmatter. Schema defaults (limits/tools/on_error) are omitted
  * to keep the generated file readable; they re-populate on the next parse.
+ * Exported for the custom-routine migration, which materialises user Agents
+ * through the same shape (AGENTS_HUB_REDESIGN_PLAN.md §3).
  */
-function definitionToFrontmatter(def) {
+export function definitionToFrontmatter(def) {
     // Auto-import always builds a cron schedule with a resolved expression +
     // timezone, so both are emitted unconditionally (no dead-branch guards).
     const backend = { process_key: def.backend.process_key };

package/dist/core/agents/override-merge.d.ts

@@ -36,7 +36,7 @@ import type { AgentDefinition } from "@aitne/shared";
  * (no target). The loader resolves the real enabled-state from the
  * `agents.enabled_overridden_at` column via the §6.4 timestamp comparison.
  */
-export declare const MERGEABLE_OVERRIDE_PATHS: readonly ["enabled", "enabled_overridden_at", "backend.tier", "backend.model", "limits.max_turns", "limits.max_budget_usd", "limits.timeout_minutes", "on_error.notify_owner"];
+export declare const MERGEABLE_OVERRIDE_PATHS: readonly ["enabled", "enabled_overridden_at", "backend.tier", "backend.model", "backend.backend_id", "limits.max_turns", "limits.max_budget_usd", "limits.timeout_minutes", "on_error.notify_owner"];
 export type MergeableOverridePath = (typeof MERGEABLE_OVERRIDE_PATHS)[number];
 /** True when `path` is one of the allow-listed override keys. */
 export declare function isMergeableOverridePath(path: string): path is MergeableOverridePath;

package/dist/core/agents/override-merge.js

@@ -1,4 +1,4 @@
-import { AGENT_TIERS, OVERRIDE_EDIT_PATHS } from "@aitne/shared";
+import { AGENT_TIERS, BACKEND_IDS, OVERRIDE_EDIT_PATHS } from "@aitne/shared";
 /**
  * Built-in override merge (AGENT_DEFINITIONS_DESIGN.md §6.4.1).
  *
@@ -53,6 +53,9 @@ export function isMergeableOverridePath(path) {
 function isAgentTier(value) {
     return typeof value === "string" && AGENT_TIERS.includes(value);
 }
+function isBackendIdValue(value) {
+    return typeof value === "string" && BACKEND_IDS.includes(value);
+}
 function isPositiveInt(value) {
     return typeof value === "number" && Number.isInteger(value) && value > 0;
 }
@@ -86,6 +89,11 @@ function applyOverridePath(def, path, value) {
                 def.backend.model = value;
             }
             break;
+        case "backend.backend_id":
+            if (value === null || isBackendIdValue(value)) {
+                def.backend.backend_id = value;
+            }
+            break;
         case "limits.max_turns":
             if (isPositiveInt(value))
                 def.limits.max_turns = value;

package/dist/core/agents/recurrence-convert.d.ts

@@ -34,7 +34,7 @@
  * is the monthly `onMissingDay` policy, which cron cannot carry — it is dropped
  * on conversion (a `daysOfMonth` cron uses node-cron's own missing-day
  * behaviour). Sub-hourly intervals (every N minutes) are NOT representable —
- * only the built-in hourly-check supports those, via config.
+ * only the built-in activity-scan supports those, via config.
  */
 /** Loader-local mirror of the daemon `recurrence_rule` JSON (§2.2). Covers the
  *  four cron-representable frequencies (`hourly` via the step-form cron). The