@aitne/daemon 0.1.7 → 0.1.9

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

@@ -0,0 +1,100 @@
+/**
+ * Cron placeholder substitution + drift / validity checks
+ * (AGENT_DEFINITIONS_DESIGN.md §4.2 / §5.5).
+ *
+ * Built-in Agents whose cron depends on a runtime config (the day boundary)
+ * carry a placeholder in their YAML `schedule.expression` — e.g.
+ * `"0 {dayBoundaryHour} * * *"` or `"50 {dayBoundaryHour-1} * * *"`. The loader
+ * substitutes the live value before handing the expression to `node-cron`, and
+ * cross-checks the result against the authoritative `BUILTIN_AGENT_REGISTRY`
+ * resolver for drift.
+ *
+ * All three functions are pure, total, and never throw — a malformed input is
+ * surfaced as a returned warning string, not an exception, so a bad YAML can
+ * never crash boot. `node-cron` remains the authoritative schedule-time parser;
+ * `validateCronExpression` here is a cheap pre-flight that catches the two
+ * failure modes the substitution layer can introduce (unresolved placeholder,
+ * wrong field count).
+ */
+/**
+ * Matches `{dayBoundaryHour}` or `{dayBoundaryHour±N}` (e.g.
+ * `{dayBoundaryHour-1}`). The optional `(sign)(digits)` group lets a single
+ * regex cover the bare form and the offset forms the design uses.
+ */
+const DAY_BOUNDARY_PLACEHOLDER = /\{dayBoundaryHour(?:([+-])(\d+))?\}/g;
+/** Wrap an hour offset into `[0, 23]` (a negative offset crosses midnight). */
+function wrapHour(hour) {
+    return ((hour % 24) + 24) % 24;
+}
+/**
+ * Substitute `{dayBoundaryHour[±N]}` placeholders in a cron expression with
+ * the live day-boundary hour (wrapping across midnight). Expressions with no
+ * placeholder pass through unchanged.
+ *
+ * Examples (dayBoundaryHour = 4):
+ *   "0 {dayBoundaryHour} * * *"    → "0 4 * * *"
+ *   "50 {dayBoundaryHour-1} * * *" → "50 3 * * *"   (4 − 1)
+ *   "0 18 * * *"                   → "0 18 * * *"    (unchanged)
+ * Wrap (dayBoundaryHour = 0):
+ *   "45 {dayBoundaryHour-1} * * *" → "45 23 * * *"
+ */
+export function substituteCron(expr, config) {
+    return expr.replace(DAY_BOUNDARY_PLACEHOLDER, (_match, sign, digits) => {
+        let hour = config.dayBoundaryHour;
+        if (sign && digits) {
+            const delta = Number.parseInt(digits, 10);
+            hour = sign === "+" ? hour + delta : hour - delta;
+        }
+        return String(wrapHour(hour));
+    });
+}
+/** Collapse runs of whitespace and trim so cosmetic spacing isn't "drift". */
+function normalizeCron(expr) {
+    return expr.trim().replace(/\s+/g, " ");
+}
+/**
+ * Compare a (resolved) YAML cron expression against the authoritative registry
+ * expression. Returns a non-fatal warning string on mismatch, or `null` when
+ * they agree.
+ *
+ * `registryExpr` is `null` for the runtime-window builtins (`hourly-check`)
+ * 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.
+ */
+export function checkCronDrift(yamlExpr, registryExpr) {
+    if (registryExpr === null)
+        return null;
+    if (normalizeCron(yamlExpr) === normalizeCron(registryExpr))
+        return null;
+    return `cron drift: YAML "${yamlExpr}" differs from registry "${registryExpr}"`;
+}
+/**
+ * Pre-flight validity check for a fully-substituted cron expression. Surfaces
+ * the failure modes the substitution layer can introduce, as a warning string
+ * (or `null` when the expression looks well-formed):
+ *
+ *   - empty / whitespace-only
+ *   - an unresolved `{...}` placeholder (substitution missed it)
+ *   - a field count other than 5 (standard) or 6 (with seconds — node-cron
+ *     accepts both)
+ *
+ * This is intentionally NOT a full cron grammar parser; `node-cron` validates
+ * field syntax at schedule time. The point is to fail loud and early on the
+ * shapes a placeholder typo produces, rather than passing a broken string to
+ * the scheduler.
+ */
+export function validateCronExpression(expr) {
+    const trimmed = expr.trim();
+    if (trimmed.length === 0) {
+        return "empty cron expression";
+    }
+    if (trimmed.includes("{") || trimmed.includes("}")) {
+        return `unresolved placeholder in cron expression: "${expr}"`;
+    }
+    const fieldCount = trimmed.split(/\s+/).length;
+    if (fieldCount !== 5 && fieldCount !== 6) {
+        return `cron expression must have 5 or 6 fields, got ${fieldCount}: "${expr}"`;
+    }
+    return null;
+}

package/dist/core/agents/definition-criteria.d.ts

@@ -0,0 +1,14 @@
+import { type SuccessCriterion } from "@aitne/shared";
+/**
+ * Best-effort load of an Agent's `success_criteria` from its definition file
+ * (AGENT_DEFINITIONS_DESIGN.md §8.3). Read at execution time from the on-disk
+ * `agent.md` so the criteria always reflect the live definition without the
+ * loader having to denormalise them into a column.
+ *
+ * Totally non-throwing: a missing / unreadable / malformed file yields `[]`
+ * (no criteria → a no-op evaluation), so a definition that became unreadable
+ * after the Agent's row was written never breaks completion recording. The
+ * `success_criteria` schema default is also `[]`, so a definition that simply
+ * declares none returns the same empty array.
+ */
+export declare function loadAgentSuccessCriteria(definitionPath: string): SuccessCriterion[];

package/dist/core/agents/definition-criteria.js

@@ -0,0 +1,25 @@
+import { readFileSync } from "node:fs";
+import { agentDefinitionSchema } from "@aitne/shared";
+import { parseAgentFrontmatter } from "./agent-frontmatter.js";
+/**
+ * Best-effort load of an Agent's `success_criteria` from its definition file
+ * (AGENT_DEFINITIONS_DESIGN.md §8.3). Read at execution time from the on-disk
+ * `agent.md` so the criteria always reflect the live definition without the
+ * loader having to denormalise them into a column.
+ *
+ * Totally non-throwing: a missing / unreadable / malformed file yields `[]`
+ * (no criteria → a no-op evaluation), so a definition that became unreadable
+ * after the Agent's row was written never breaks completion recording. The
+ * `success_criteria` schema default is also `[]`, so a definition that simply
+ * declares none returns the same empty array.
+ */
+export function loadAgentSuccessCriteria(definitionPath) {
+    try {
+        const raw = readFileSync(definitionPath, "utf-8");
+        const { frontmatter } = parseAgentFrontmatter(raw);
+        return agentDefinitionSchema.parse(frontmatter).success_criteria;
+    }
+    catch {
+        return [];
+    }
+}

package/dist/core/agents/effective-definition.d.ts

@@ -0,0 +1,47 @@
+import { type AgentDefinition } from "@aitne/shared";
+import type { AgentDTO } from "../../db/agents-store.js";
+/**
+ * Effective-definition resolver for the `/api/agents/:slug` read path
+ * (AGENT_DEFINITIONS_DESIGN.md §9.2). The stored `agents` row carries the
+ * identity columns the list view needs, but the detail view returns the *full*
+ * `AgentDefinition` body (`limits`, `tools`, `success_criteria`, …). That body
+ * lives only in the `agent.md` file, so this module re-reads + re-composes it
+ * exactly as the loader does at boot:
+ *
+ *     effective = parse(agent.md)  →  merge override_snapshot (built-ins)
+ *
+ * and falls back to the registry-synthesised definition when a built-in's file
+ * is missing or unparseable (the same §6.1-step-3 fallback the loader applies),
+ * so a broken file still renders a usable identity in the dashboard.
+ *
+ * Pure over an injected `readFile` (returns `null` when the file is absent or
+ * unreadable) so it stays in the 100%-coverage set; the route supplies a thin
+ * `fs` adapter.
+ */
+export interface EffectiveDefinitionDeps {
+    /** Read a definition file; `null` when missing/unreadable (never throws). */
+    readFile: (path: string) => string | null;
+    /** Live day-boundary hour for `{dayBoundaryHour}` cron substitution (§4.2). */
+    dayBoundaryHour: number;
+}
+export interface EffectiveDefinitionResult {
+    /**
+     * The composed effective definition, or `null` when it cannot be produced
+     * (a user Agent whose file is missing/unparseable — built-ins always
+     * synthesise from the registry).
+     */
+    definition: AgentDefinition | null;
+    /** Raw `agent.md` bytes when a file exists, else `null` (synthesised). */
+    yaml: string | null;
+    /** True when the definition was synthesised from the registry fallback. */
+    synthesized: boolean;
+    /** Parse/validation error message when the on-disk file is invalid. */
+    error: string | null;
+}
+/**
+ * Compose the effective definition for one Agent row. The runtime `enabled`
+ * authority is the `agents.enabled` column (§6.4 timestamp resolution), not the
+ * YAML/snapshot value, so the composed `definition.enabled` is overwritten with
+ * `dto.enabled` to keep the detail view truthful against the scheduler gate.
+ */
+export declare function loadEffectiveDefinition(dto: AgentDTO, deps: EffectiveDefinitionDeps): EffectiveDefinitionResult;

package/dist/core/agents/effective-definition.js

@@ -0,0 +1,101 @@
+import { agentDefinitionSchema } from "@aitne/shared";
+import { AgentFrontmatterError, parseAgentFrontmatter } from "./agent-frontmatter.js";
+import { getBuiltinRegistryEntry } from "./builtin-registry.js";
+import { mergeAgentDefinition } from "./override-merge.js";
+import { synthesizeRegistryDefinition } from "./loader.js";
+/** Built-in override snapshot for the merge; `{}` when none / not a built-in. */
+function overrideSnapshotFor(dto) {
+    if (dto.source !== "builtin")
+        return {};
+    const snapshot = dto.metadata.override_snapshot;
+    return snapshot && typeof snapshot === "object" && !Array.isArray(snapshot)
+        ? snapshot
+        : {};
+}
+/** Apply the built-in override snapshot on top of a base definition (§6.4.1). */
+function applyOverride(base, dto) {
+    const snapshot = overrideSnapshotFor(dto);
+    if (Object.keys(snapshot).length === 0)
+        return base;
+    return mergeAgentDefinition(base, base, snapshot);
+}
+/**
+ * Synthesise a built-in's effective definition from `BUILTIN_AGENT_REGISTRY`
+ * (used when the file is missing/invalid). Returns `null` for a slug with no
+ * registry entry — impossible for a real built-in (the loader rejects unknown
+ * built-in slugs), but guarded so a hand-corrupted `source='builtin'` row can't
+ * throw.
+ */
+function synthesizeBuiltin(dto, dayBoundaryHour) {
+    const entry = getBuiltinRegistryEntry(dto.slug);
+    if (!entry)
+        return null;
+    return applyOverride(synthesizeRegistryDefinition(entry, dayBoundaryHour), dto);
+}
+/**
+ * Compose the effective definition for one Agent row. The runtime `enabled`
+ * authority is the `agents.enabled` column (§6.4 timestamp resolution), not the
+ * YAML/snapshot value, so the composed `definition.enabled` is overwritten with
+ * `dto.enabled` to keep the detail view truthful against the scheduler gate.
+ */
+export function loadEffectiveDefinition(dto, deps) {
+    const raw = deps.readFile(dto.definitionPath);
+    if (raw !== null) {
+        try {
+            const { frontmatter } = parseAgentFrontmatter(raw);
+            const parsed = agentDefinitionSchema.parse(frontmatter);
+            const effective = applyOverride(parsed, dto);
+            effective.enabled = dto.enabled;
+            return { definition: effective, yaml: raw, synthesized: false, error: null };
+        }
+        catch (err) {
+            const error = describeParseError(err);
+            // A broken built-in file still renders from the registry fallback; a
+            // broken user file has no fallback, so the body is null (the row's
+            // last_error already explains why, surfaced via the list view).
+            const fallback = dto.source === "builtin"
+                ? synthesizeBuiltin(dto, deps.dayBoundaryHour)
+                : null;
+            if (fallback)
+                fallback.enabled = dto.enabled;
+            return {
+                definition: fallback,
+                yaml: raw,
+                synthesized: fallback !== null,
+                error,
+            };
+        }
+    }
+    // No file on disk — synthesise built-ins from the registry; user Agents
+    // (which always own a file) report the missing definition.
+    if (dto.source === "builtin") {
+        const synth = synthesizeBuiltin(dto, deps.dayBoundaryHour);
+        if (synth)
+            synth.enabled = dto.enabled;
+        return {
+            definition: synth,
+            yaml: null,
+            synthesized: synth !== null,
+            error: synth ? null : "no registry entry for built-in slug",
+        };
+    }
+    return {
+        definition: null,
+        yaml: null,
+        synthesized: false,
+        error: "definition file not found",
+    };
+}
+/**
+ * Render a frontmatter / schema failure as a single-line message. The only two
+ * throwers in the `try` above are `parseAgentFrontmatter` (→ `AgentFrontmatterError`)
+ * and `agentDefinitionSchema.parse` (→ `ZodError`), so the two-branch form is
+ * total — mirrors `loader.ts:processFile`'s identical catch.
+ */
+function describeParseError(err) {
+    if (err instanceof AgentFrontmatterError)
+        return err.message;
+    return `schema validation failed: ${err.issues
+        .map((i) => `${i.path.join(".")}: ${i.message}`)
+        .join("; ")}`;
+}

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

@@ -0,0 +1,28 @@
+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
+ * 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
+ * increments that row's `detail.suppressed_count` instead.
+ *
+ * `agent-day` is the caller-supplied `YYYY-MM-DD` boundary string (04:00-local
+ * by default), matched against `detail.agent_day` — so the first block of each
+ * agent-day opens a fresh row. The increment runs entirely in SQL (`json_set`
+ * over `json_extract`) so there is no read-modify-write race between concurrent
+ * cron ticks. Detail keys are snake_case per design §12.3 (`reason`,
+ * `suppressed_count`, `agent_day`).
+ */
+export type AgentFiringBlockedOutcome = "inserted" | "incremented";
+export interface RecordAgentFiringBlockedInput {
+    /** Owning Agent slug (`agents.id`). */
+    slug: string;
+    /** Agent-day `YYYY-MM-DD` label the suppression belongs to. */
+    agentDay: string;
+    /** Why the firing was blocked (design §12.3 value: `"disabled"`). */
+    reason: string;
+}
+export declare function recordAgentFiringBlocked(db: Database.Database, input: RecordAgentFiringBlockedInput): AgentFiringBlockedOutcome;

package/dist/core/agents/firing-blocked.js

@@ -0,0 +1,27 @@
+export function recordAgentFiringBlocked(db, input) {
+    const existing = db
+        .prepare(`SELECT id FROM agent_actions
+        WHERE action_type = 'agent.firing_blocked'
+          AND agent_id = ?
+          AND json_extract(detail, '$.agent_day') = ?
+        LIMIT 1`)
+        .get(input.slug, input.agentDay);
+    if (existing !== undefined) {
+        db.prepare(`UPDATE agent_actions
+          SET detail = json_set(
+                detail,
+                '$.suppressed_count',
+                COALESCE(json_extract(detail, '$.suppressed_count'), 0) + 1
+              )
+        WHERE id = ?`).run(existing.id);
+        return "incremented";
+    }
+    db.prepare(`INSERT INTO agent_actions
+        (action_type, agent_id, trigger, result, detail, started_at, completed_at)
+      VALUES ('agent.firing_blocked', ?, 'autonomous', 'skipped', json(?), CURRENT_TIMESTAMP, CURRENT_TIMESTAMP)`).run(input.slug, JSON.stringify({
+        agent_day: input.agentDay,
+        reason: input.reason,
+        suppressed_count: 0,
+    }));
+    return "inserted";
+}

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

@@ -0,0 +1,26 @@
+import type Database from "better-sqlite3";
+import type { AgentConfig } from "../../config.js";
+import { AgentEnabledCache, type AgentLoadOptions, type LoadAgentsResult } from "./loader.js";
+import { type AgentsWatcherHandle } from "./loader-watcher.js";
+export interface BootstrapAgentsDeps {
+    db: Database.Database;
+    config: AgentConfig;
+    /** Dashboard SSE broadcaster; omitted in headless installs. */
+    eventBroadcaster?: {
+        broadcastEvent: (data: unknown) => void;
+    };
+}
+export interface BootstrapAgentsResult {
+    result: LoadAgentsResult;
+    enabledCache: AgentEnabledCache;
+    watcher: AgentsWatcherHandle | null;
+}
+/** Resolve the loader's port set + dirs from daemon config. */
+export declare function buildAgentLoadOptions(deps: BootstrapAgentsDeps): AgentLoadOptions;
+/**
+ * Load every Agent definition at boot, build the enabled cache, and start the
+ * user-root watcher. Wire the returned `enabledCache` into the scheduler via
+ * `scheduler.setAgentEnabledCache(...)` and the `watcher` into the shutdown
+ * sequence.
+ */
+export declare function bootstrapAgents(deps: BootstrapAgentsDeps): BootstrapAgentsResult;

package/dist/core/agents/loader-boot.js

@@ -0,0 +1,98 @@
+import { join } from "node:path";
+import { getContextDir } from "../../config.js";
+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 { listAllSkillSlugs } from "../release-assets.js";
+import { resolveUserSkillsRoot } from "../user-skills-root.js";
+/**
+ * Boot adapter for the Agent loader (AGENT_DEFINITIONS_DESIGN.md §6.1 — the
+ * Phase-7 `(db, config)` wrapper the Phase-5 loader's DI seam expects).
+ *
+ * Resolves the concrete ports the loader's pure core takes as injected deps:
+ *   - `builtinDir` = `<workspaceDir>/agent-assets/agents`,
+ *     `userDir`    = `<contextDir>/policies/agents`;
+ *   - `snapshot`   → an `md_file_snapshots` row writer (mirrors the
+ *     daily-journal / roadmap-maintenance snapshot inserts);
+ *   - `events`     → the dashboard SSE broadcaster (`agent.updated`);
+ *   - `recurring`  → the `recurring-schedule-adapter` over `db/recurring-schedules`.
+ *
+ * Runs the boot scan, builds the live {@link AgentEnabledCache} the scheduler
+ * gate consults, and starts the filesystem watcher (user root only — built-ins
+ * ship read-only) so a dashboard-authored `agent.md` reloads without a restart.
+ * Never throws: the loader is crash-proof by contract and a watcher start
+ * failure degrades to a logged warning.
+ */
+const logger = createLogger("agents-loader-boot");
+/** Resolve the loader's port set + dirs from daemon config. */
+export function buildAgentLoadOptions(deps) {
+    const { db, config, eventBroadcaster } = deps;
+    const builtinDir = join(config.workspaceDir, "agent-assets", "agents");
+    const userDir = join(getContextDir(config, db), "policies", "agents");
+    // A concrete zone for the recurring adapter's fallback (well-formed rows
+    // carry their own; this only fills a hand-edited row with none).
+    const fallbackTz = resolveTimezone(undefined, config.timezone);
+    // Snapshot the known skill slugs once at boot for the loader's `tools.skills`
+    // cross-check (§4.3 step 5). A skill added mid-session is a minor staleness
+    // (re-resolved on the next boot), not a correctness gap — the watcher reuses
+    // the same opts, matching the recurring-port snapshot semantics.
+    const skillSlugs = listAllSkillSlugs(resolveUserSkillsRoot(config), config.workspaceDir);
+    const snapshot = {
+        record: ({ filePath, content, trigger }) => {
+            try {
+                db.prepare("INSERT INTO md_file_snapshots (file_path, content, trigger, session_id) VALUES (?, ?, ?, ?)").run(filePath, content, trigger, null);
+            }
+            catch (err) {
+                logger.warn({ err, filePath, trigger }, "Failed to save agent md_file_snapshots row");
+            }
+        },
+    };
+    const events = eventBroadcaster
+        ? {
+            emit: (event, payload) => eventBroadcaster.broadcastEvent({
+                kind: event,
+                ...payload,
+            }),
+        }
+        : undefined;
+    return {
+        builtinDir,
+        userDir,
+        dayBoundaryHour: config.dayBoundaryHour,
+        timezone: config.timezone,
+        snapshot,
+        ...(events ? { events } : {}),
+        recurring: createRecurringSchedulePort(db, fallbackTz),
+        listSkillSlugs: () => skillSlugs,
+    };
+}
+/**
+ * Load every Agent definition at boot, build the enabled cache, and start the
+ * user-root watcher. Wire the returned `enabledCache` into the scheduler via
+ * `scheduler.setAgentEnabledCache(...)` and the `watcher` into the shutdown
+ * sequence.
+ */
+export function bootstrapAgents(deps) {
+    const opts = buildAgentLoadOptions(deps);
+    const result = loadAgents(deps.db, opts);
+    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)");
+    }
+    for (const warning of result.warnings)
+        logger.debug({ warning }, "agent load warning");
+    logger.info({ upserted: result.upserted.length }, "Agents loaded");
+    const enabledCache = new AgentEnabledCache(deps.db);
+    let watcher = null;
+    try {
+        watcher = startAgentsWatcher(deps.db, opts, {
+            reload: () => loadAgents(deps.db, opts),
+            cache: enabledCache,
+            ...(opts.events ? { events: opts.events } : {}),
+        });
+    }
+    catch (err) {
+        logger.warn({ err }, "Agent definitions watcher failed to start — edits apply on next restart");
+    }
+    return { result, enabledCache, watcher };
+}

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

@@ -0,0 +1,23 @@
+import type Database from "better-sqlite3";
+import { AgentEnabledCache, type AgentEventPort, type AgentLoadOptions, type LoadAgentsResult } from "./loader.js";
+export interface AgentsWatcherHandle {
+    stop(): Promise<void>;
+}
+export interface AgentsWatcherOptions {
+    /** Also watch the shipped built-in root (dev hot-reload). Off in production. */
+    watchBuiltin?: boolean;
+    /** Debounce window before a reload fires after the last filesystem event. */
+    debounceMs?: number;
+    /** Reload implementation (defaults to `loadAgents`); overridable for tests. */
+    reload?: () => LoadAgentsResult;
+    /** Optional enabled-cache to invalidate after each reload. */
+    cache?: AgentEnabledCache;
+    /** Optional SSE port; an `agent.updated` event fires after each reload. */
+    events?: AgentEventPort;
+}
+/**
+ * Start watching the user (and optionally built-in) agent roots. Returns a
+ * handle whose `stop()` closes the chokidar watcher. Errors in the reload
+ * handler are logged, never thrown — a bad edit must not take down the daemon.
+ */
+export declare function startAgentsWatcher(db: Database.Database, opts: AgentLoadOptions, watcherOpts?: AgentsWatcherOptions): AgentsWatcherHandle;

package/dist/core/agents/loader-watcher.js

@@ -0,0 +1,84 @@
+import { basename } from "node:path";
+import * as chokidar from "chokidar";
+import { createLogger } from "../../logging.js";
+import { loadAgents, } from "./loader.js";
+/**
+ * Filesystem watcher for Agent definitions (AGENT_DEFINITIONS_DESIGN.md §6.2).
+ *
+ * Mirrors the `core/management-md.ts` chokidar pattern: debounced
+ * (`awaitWriteFinish`), `ignoreInitial`, resilient to handler errors, and —
+ * importantly — it watches the agent *directories* and filters events to
+ * `agent.md` basenames rather than passing a glob to `chokidar.watch`
+ * (chokidar v4 dropped glob support, so a `**​/agent.md` argument would be
+ * treated as a literal path and never fire).
+ *
+ * On any add/change/unlink of an `agent.md` it re-runs {@link loadAgents} (the
+ * full pass is cheap — the loader's hash/override efficiency-skip writes only
+ * the rows that actually changed) and invalidates the enabled-cache so the
+ * scheduler gate sees the new state on its next firing.
+ *
+ * The reload is injectable so the unit test can assert it fires without
+ * standing up the whole pass; production defaults to `loadAgents`.
+ */
+const logger = createLogger("agents-watcher");
+const AGENT_FILE_NAME = "agent.md";
+/**
+ * Start watching the user (and optionally built-in) agent roots. Returns a
+ * handle whose `stop()` closes the chokidar watcher. Errors in the reload
+ * handler are logged, never thrown — a bad edit must not take down the daemon.
+ */
+export function startAgentsWatcher(db, opts, watcherOpts = {}) {
+    const roots = [opts.userDir];
+    if (watcherOpts.watchBuiltin) {
+        roots.push(opts.builtinDir);
+    }
+    const debounceMs = watcherOpts.debounceMs ?? 300;
+    const reload = watcherOpts.reload ?? (() => loadAgents(db, opts));
+    const watcher = chokidar.watch(roots, {
+        persistent: true,
+        ignoreInitial: true,
+        awaitWriteFinish: {
+            stabilityThreshold: 300,
+            pollInterval: 100,
+        },
+    });
+    let timer = null;
+    const runReload = (reason) => {
+        try {
+            const result = reload();
+            watcherOpts.cache?.invalidate();
+            watcherOpts.events?.emit("agent.updated", { reason, upserted: result.upserted });
+            logger.info({ reason, upserted: result.upserted.length, invalid: result.invalid.length }, "agents reloaded after filesystem change");
+        }
+        catch (err) {
+            logger.error({ err, reason }, "agents reload failed");
+        }
+    };
+    const schedule = (reason) => {
+        if (timer)
+            clearTimeout(timer);
+        timer = setTimeout(() => {
+            timer = null;
+            runReload(reason);
+        }, debounceMs);
+        timer.unref?.();
+    };
+    // Only `agent.md` files matter; ignore the surrounding directory churn.
+    const onEvent = (reason) => (filePath) => {
+        if (basename(filePath) === AGENT_FILE_NAME)
+            schedule(reason);
+    };
+    watcher.on("add", onEvent("add"));
+    watcher.on("change", onEvent("change"));
+    watcher.on("unlink", onEvent("unlink"));
+    watcher.on("error", (err) => logger.error({ err }, "agents watcher error"));
+    logger.info({ roots }, "agents watcher started");
+    return {
+        async stop() {
+            if (timer)
+                clearTimeout(timer);
+            await watcher.close();
+            logger.info("agents watcher stopped");
+        },
+    };
+}