@aitne/daemon 0.1.8 → 0.1.10

package/dist/core/dispatcher-scheduled-tasks.js

@@ -44,18 +44,31 @@
  *     does not own the manager's lifecycle.
  */
 import { EventPriority, createEvent, formatSqliteDatetime, getAgentDayDateStr, isBackendId, isKnowledgeImportEvent, isRoutineEvent, resolveProcessKey, } from "@aitne/shared";
-import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync, } from "node:fs";
+import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, writeFileSync, } from "node:fs";
 import { join } from "node:path";
 import { randomUUID } from "node:crypto";
-import { CONTEXT_RELATIVE_PATHS } from "./context-paths.js";
+import { CONTEXT_RELATIVE_PATHS, agentLessonsPath } from "./context-paths.js";
 import { getContextDir } from "../config.js";
+import { ensureTodaySkeleton } from "./today-direct-writer.js";
 import { cleanupSessionWorkdir, ensureBackendMaterialized, } from "./workdir.js";
-import { readIntegrations } from "../db/integrations-store.js";
+import { readIntegrations, readIntegrationState } from "../db/integrations-store.js";
+import { refreshInterestsReflection } from "../services/browser-history/refresh-interests-reflection.js";
+import { InterestsReflectionLockBusyError } from "../services/browser-history/interests-reflection-lock.js";
+import { findSectionLineBounds } from "./roadmap-validate.js";
+import { writeFileAtomically } from "./atomic-write.js";
+import { serializeContextFileWrite } from "./context-file-serializer.js";
 import { getRepository, getRepositoryByLocalPath, recordManagementInitDone, recordManagementScan, } from "../db/repositories-store.js";
 import { runRepositoryManagementInit, runRepositoryManagementScan, } from "./repository-management-docs.js";
 import { routineWindowKeyFromEvent } from "./routine-fetch-window-runner.js";
 import { routineHasWindows } from "./routine-windows.js";
+import { buildFeedbackWorksheet, gatherFeedbackWorksheetScopes, lessonCapsForScope, GLOBAL_LESSON_ENTRY_CAP, PER_AGENT_LESSON_ENTRY_CAP, } from "./feedback/consolidation-prep.js";
+import { buildRegeneralizationWorksheet, } from "./feedback/regeneralization-prep.js";
+import { isSafeAgentSlug, scopeStoreFile, } from "./feedback/scope-parser.js";
+import { feedbackRetentionCutoff, sweepConsumedFeedbackSignals, } from "../db/feedback-signals-store.js";
 import { morningRoutineRanToday } from "../bootstrap/schedule-helpers.js";
+import { resolveAgentId } from "./agents/agent-id-resolver.js";
+import { loadEffectiveDefinition } from "./agents/effective-definition.js";
+import { getAgent } from "../db/agents-store.js";
 import { releaseWikiCompileLock } from "./wiki/compile-lock.js";
 import { parseGithubRepoSlug, normalizeRepositoryClassification, normalizeRepositoryCategory, parseRepositoryRunTaskContext, repositoryRunInstructionFilename, safeRepositoryRunDirName, } from "./dispatcher-repository-helpers.js";
 import { createLogger } from "../logging.js";
@@ -219,6 +232,7 @@ export class ScheduledTaskRunner {
     morningRoutine;
     fetchWindowRunner;
     roadmapWriteLock;
+    todayWriteLock;
     writeTracker;
     getConfiguredServices;
     getActiveMailAccounts;
@@ -235,6 +249,7 @@ export class ScheduledTaskRunner {
         this.morningRoutine = deps.morningRoutine;
         this.fetchWindowRunner = deps.fetchWindowRunner;
         this.roadmapWriteLock = deps.roadmapWriteLock;
+        this.todayWriteLock = deps.todayWriteLock;
         this.writeTracker = deps.writeTracker;
         this.getConfiguredServices = deps.getConfiguredServices;
         this.getActiveMailAccounts = deps.getActiveMailAccounts;
@@ -312,12 +327,20 @@ export class ScheduledTaskRunner {
             ?? (event.requestedModel
                 ? (event.requestedModel === "sonnet" ? "medium" : "high")
                 : undefined);
-        const internalBackendOverride = event.requestedBackendId
-            && isBackendId(event.requestedBackendId)
-            && typeof event.requestedModelId === "string"
+        // Forward the backend pin carried by the scheduled-row event. A
+        // `requestedModelId` companion is honored when present (exact model
+        // pin) but is NOT required: a standalone `requestedBackendId`
+        // (engine-only Agent pin) routes to that backend via resolveBinding's
+        // backend-only branch, which fills the model from `requestedTier` / the
+        // backend default. Before 2026-06-01 the `typeof requestedModelId ===
+        // "string"` co-guard silently dropped engine-only pins
+        // (AGENT_DEFINITIONS_KNOWN_LIMITATIONS §1).
+        const internalBackendOverride = event.requestedBackendId && isBackendId(event.requestedBackendId)
             ? {
                 requestedBackendId: event.requestedBackendId,
-                requestedModelId: event.requestedModelId,
+                ...(typeof event.requestedModelId === "string"
+                    ? { requestedModelId: event.requestedModelId }
+                    : {}),
             }
             : {};
         const binding = this.agentRouter.resolveBinding(event, {
@@ -397,12 +420,20 @@ export class ScheduledTaskRunner {
             ?? (event.requestedModel
                 ? (event.requestedModel === "sonnet" ? "medium" : "high")
                 : undefined);
-        const internalBackendOverride = event.requestedBackendId
-            && isBackendId(event.requestedBackendId)
-            && typeof event.requestedModelId === "string"
+        // Forward the backend pin carried by the scheduled-row event. A
+        // `requestedModelId` companion is honored when present (exact model
+        // pin) but is NOT required: a standalone `requestedBackendId`
+        // (engine-only Agent pin) routes to that backend via resolveBinding's
+        // backend-only branch, which fills the model from `requestedTier` / the
+        // backend default. Before 2026-06-01 the `typeof requestedModelId ===
+        // "string"` co-guard silently dropped engine-only pins
+        // (AGENT_DEFINITIONS_KNOWN_LIMITATIONS §1).
+        const internalBackendOverride = event.requestedBackendId && isBackendId(event.requestedBackendId)
             ? {
                 requestedBackendId: event.requestedBackendId,
-                requestedModelId: event.requestedModelId,
+                ...(typeof event.requestedModelId === "string"
+                    ? { requestedModelId: event.requestedModelId }
+                    : {}),
             }
             : {};
         const binding = this.agentRouter.resolveBinding(event, {
@@ -430,6 +461,11 @@ export class ScheduledTaskRunner {
             this.markScheduledTaskCompleted(event);
             return;
         }
+        // AGENT_DEFINITIONS_DESIGN.md §4.2 — fold the firing Agent's
+        // `tools.skills` onto the process-key skill bundle. `undefined` for every
+        // non-Agent firing (managed task, git project doc, automation trigger) and
+        // for Agents declaring no extra skills, so the common path is unchanged.
+        const agentSkillOverride = this.resolveAgentSkillOverride(taskCtx);
         const result = await this.errorRouter.executeWithRetry(() => this.agentRouter.execute({
             prompt,
             context,
@@ -441,9 +477,62 @@ export class ScheduledTaskRunner {
             ...(refreshArchitectureOverride
                 ? { allowedToolsOverride: refreshArchitectureOverride }
                 : {}),
+            ...(agentSkillOverride
+                ? {
+                    extraSkills: agentSkillOverride.extraSkills,
+                    skillsReplace: agentSkillOverride.skillsReplace,
+                }
+                : {}),
         }), event);
         await this.resultProcessor.processResult(result, event);
     }
+    /**
+     * AGENT_DEFINITIONS_DESIGN.md §4.2 — resolve the firing Agent's
+     * `tools.skills` override for a `scheduled.task` firing.
+     *
+     * Returns `undefined` for every firing that is NOT a user Agent run, and for
+     * Agents that declare no extra skills, so the common dispatch path stays a
+     * pure no-op. Only firings carrying a stamped `task_context.agent_id` (§7.2)
+     * or a `recurring_schedule_id` that joins an Agent row resolve a slug —
+     * built-in routines (which manage skills via the process-key manifest, not
+     * `tools.skills`) and legacy/managed/automation tasks fall through to
+     * `null`. The effective definition is re-read from the Agent's `agent.md` on
+     * disk, so a live `tools.skills` edit takes effect on the next firing.
+     */
+    resolveAgentSkillOverride(taskCtx) {
+        const ctx = taskCtx && typeof taskCtx === "object"
+            ? taskCtx
+            : {};
+        const agentId = resolveAgentId(this.db, {
+            taskContextAgentId: typeof ctx.agent_id === "string" ? ctx.agent_id : null,
+            recurringScheduleId: typeof ctx.recurringScheduleId === "number"
+                ? ctx.recurringScheduleId
+                : null,
+        });
+        if (!agentId)
+            return undefined;
+        const dto = getAgent(this.db, agentId);
+        if (!dto)
+            return undefined;
+        const { definition } = loadEffectiveDefinition(dto, {
+            readFile: (path) => {
+                try {
+                    return existsSync(path) ? readFileSync(path, "utf-8") : null;
+                }
+                catch {
+                    return null;
+                }
+            },
+            dayBoundaryHour: this.config.dayBoundaryHour ?? 4,
+        });
+        const skills = definition?.tools.skills ?? [];
+        if (skills.length === 0)
+            return undefined;
+        return {
+            extraSkills: skills,
+            skillsReplace: definition?.tools.skills_replace ?? false,
+        };
+    }
     /**
      * Legacy git project documentation tasks used to run as autonomous Claude
      * task-flows. That made file creation probabilistic: the backend could
@@ -800,7 +889,7 @@ export class ScheduledTaskRunner {
      * failure modes (process crash vs. format-confusion bug).
      */
     diagnoseTodayMdState() {
-        const todayPath = join(getContextDir(this.config, this.db), "today.md");
+        const todayPath = join(getContextDir(this.config, this.db), CONTEXT_RELATIVE_PATHS.today);
         if (!existsSync(todayPath)) {
             return { kind: "missing" };
         }
@@ -825,7 +914,7 @@ export class ScheduledTaskRunner {
      */
     rotateDayFiles() {
         const contextDir = getContextDir(this.config, this.db);
-        const todayPath = join(contextDir, "today.md");
+        const todayPath = join(contextDir, CONTEXT_RELATIVE_PATHS.today);
         if (!existsSync(todayPath))
             return;
         const content = readFileSync(todayPath, "utf-8");
@@ -844,7 +933,7 @@ export class ScheduledTaskRunner {
         try {
             this.db
                 .prepare("INSERT INTO md_file_snapshots (file_path, content, trigger) VALUES (?, ?, ?)")
-                .run("today", content, "day_rotation");
+                .run("state/today", content, "day_rotation");
         }
         catch (err) {
             logger.warn({ err }, "Failed to save rotation snapshot");
@@ -1003,6 +1092,94 @@ export class ScheduledTaskRunner {
                     };
                 }
             }
+            // Deterministic pre-step for `routine.today_refresh`. rotateDayFiles()
+            // intentionally leaves today.md absent at the day boundary for the
+            // morning routine to recreate; when that routine has not yet run (or
+            // failed — e.g. a quota/budget death with no fallback), today.md is
+            // missing and this section-only refresh would 404 on its PATCH and
+            // fall back to budget-burning full-file PUTs against the strict
+            // validateTodayContent schema (the "Refresh Today does nothing"
+            // symptom). Guarantee the canonical skeleton exists (lock-aware,
+            // absent-only) so the refresh session has a valid PATCH target; full
+            // creation/repair stays the morning routine's job. See
+            // ensureTodaySkeleton. Skipped when no today-write-lock was wired.
+            if (this.todayWriteLock
+                && isRoutineEvent(effectiveEvent)
+                && effectiveEvent.routine === "today_refresh") {
+                // Failure-isolated like the sibling pre-steps below: this seed is a
+                // best-effort convenience so the refresh has a valid PATCH target.
+                // A throw here (e.g. getContextDir / serializer-lock internals) must
+                // NOT abort the whole today_refresh — that would reproduce the exact
+                // "Refresh Today does nothing" symptom the skeleton was added to
+                // prevent. The morning routine remains responsible for real repair.
+                try {
+                    await ensureTodaySkeleton({
+                        contextDir: getContextDir(this.config, this.db),
+                        todayWriteLock: this.todayWriteLock,
+                    });
+                }
+                catch (err) {
+                    logger.warn({ err }, "Failed to seed today.md skeleton for today_refresh");
+                }
+            }
+            // FEEDBACK_LEARNING_LOOP_DESIGN.md §4 — deterministic consolidation
+            // pre-step for `routine.evening_review`. Runs synchronously BEFORE
+            // `contextBuilder.build` so the `<feedback_worksheet>` (unconsumed
+            // signals grouped by scope + per-candidate promotion verdicts +
+            // eviction ranking + consume ids) lands in the review session's
+            // context. Failure-isolated inside `prepareFeedbackWorksheet`: a throw
+            // there is swallowed and the review still ships. Skipped when feedback
+            // learning is off or no signals pend (no empty block in the prompt).
+            if (isRoutineEvent(effectiveEvent)
+                && effectiveEvent.routine === "evening_review") {
+                const worksheetBlock = this.prepareFeedbackWorksheet();
+                if (worksheetBlock) {
+                    effectiveEvent = {
+                        ...effectiveEvent,
+                        data: {
+                            ...effectiveEvent.data,
+                            feedbackWorksheetBlock: worksheetBlock,
+                        },
+                    };
+                }
+            }
+            // FEEDBACK_LEARNING_LOOP_DESIGN.md §4 "Monthly re-generalization" /
+            // Phase 5 — deterministic pre-step for `routine.monthly_review`. Re-reads
+            // the consolidated lesson stores (global + per-agent) and stamps a
+            // `<feedback_regeneralization>` block so the monthly session collapses
+            // same-theme lessons into higher-level principles. Distinct from the
+            // nightly evening-review pass: it carries no signals and consumes
+            // nothing — it only surfaces existing lessons ranked for collapse.
+            // Failure-isolated inside `prepareRegeneralizationWorksheet`; skipped
+            // when feedback learning is off or no scope has enough lessons. Rides the
+            // same `monthlyReviewEnabled` kill switch as the rest of the monthly
+            // routine (the routine never dispatches while it is off).
+            if (isRoutineEvent(effectiveEvent)
+                && effectiveEvent.routine === "monthly_review") {
+                const regeneralizationBlock = this.prepareRegeneralizationWorksheet();
+                if (regeneralizationBlock) {
+                    effectiveEvent = {
+                        ...effectiveEvent,
+                        data: {
+                            ...effectiveEvent.data,
+                            regeneralizationBlock,
+                        },
+                    };
+                }
+            }
+            // WEEKLY_INTERESTS_REFLECTION_PLAN.md §10.4 — deterministic
+            // pre-hook for `routine.weekly_review`. Runs synchronously
+            // BEFORE `contextBuilder.build` so the freshly-refreshed
+            // `## Current research themes (auto)` block lands in the
+            // session's `<user>` injection. Failure-isolated: a throw
+            // here is caught (`appendWeeklyInterestsJournalLine`) and the
+            // user-facing weekly artifact still ships. Skip when the
+            // upstream `browser-history` integration is disabled, mirroring
+            // the F1 / F2 / F4 gate.
+            if (isRoutineEvent(effectiveEvent)
+                && effectiveEvent.routine === "weekly_review") {
+                this.runWeeklyInterestsReflectionPreHook(effectiveEvent);
+            }
             const context = await this.contextBuilder.build(effectiveEvent);
             const processKey = resolveProcessKey(effectiveEvent);
             // Honour run-now's `requestedModel` hint for routine events. Other event
@@ -1091,5 +1268,453 @@ export class ScheduledTaskRunner {
     static formatScheduledFor(date) {
         return formatSqliteDatetime(date);
     }
+    /**
+     * WEEKLY_INTERESTS_REFLECTION_PLAN.md §10.4 pre-hook.
+     *
+     * Synchronous and failure-isolated. The only side-effect the caller
+     * cares about is the freshly-refreshed `context/identity/profile.md`
+     * block — which `contextBuilder.build` (called immediately after
+     * this method returns) picks up via its normal read path. Every
+     * branch below routes through a try/catch so a throw cannot abort
+     * the user-facing weekly artifact.
+     *
+     * Three terminal states:
+     *
+     *   - `browser_history` mode is `disabled` → no-op (with a journal
+     *     line for traceability so an operator wondering "why didn't the
+     *     reflection run this week?" finds the answer in
+     *     `journal/agent.md` rather than having to greppling
+     *     `agent_actions`).
+     *   - The helper returns `{ skipped }` → journal line + audit row
+     *     already emitted by the helper.
+     *   - The helper throws → log + journal line. Audit row may or may
+     *     not have been written depending on how far the helper got;
+     *     the journal line is the defensive trace.
+     */
+    runWeeklyInterestsReflectionPreHook(event) {
+        try {
+            const browserHistory = readIntegrationState(this.db, "browser_history");
+            const integrationDisabled = browserHistory.mode === "disabled";
+            // Pass `this.db` so degraded-Obsidian-mode falls back to the
+            // internal `~/.personal-agent/context/` — the rest of this file
+            // (lines 424, 698, 725, 1107, 1135) follows the same convention;
+            // without the db argument the pre-hook would write into the
+            // user's Obsidian vault even when the daemon has decided to skip
+            // it, leaving the LLM's contextBuilder reading from a different
+            // location than the writer wrote to.
+            const contextDir = getContextDir(this.config, this.db);
+            const boundary = {
+                timezone: this.config.timezone ? this.config.timezone : undefined,
+                dayBoundaryHour: this.config.dayBoundaryHour ?? 4,
+            };
+            // rev 4 — the disabled gate is now enforced INSIDE the helper
+            // (via `integrationDisabled`) so the audit-row shape is uniform
+            // across both skip reasons. The helper short-circuits without
+            // taking the lock or touching disk; it still emits the audit
+            // row + returns `{ skipped: { reason: "no_browser_history" } }`.
+            const result = refreshInterestsReflection(this.db, contextDir, {
+                trigger: "scheduler",
+                boundary,
+                integrationDisabled,
+                // Thread the agent-write tracker so each write the helper does
+                // to user/profile.md, user/research-themes.md, user/_index.md,
+                // and projects/*.md is attributed to the agent by FS-watch
+                // consumers (the context-index reconciler chain + future
+                // observers). Without this thread the chokidar `change` events
+                // would be classified as user edits and feed into the hourly-
+                // check pending floor as if the user had typed them.
+                writeTracker: this.writeTracker,
+                // `correlationId` is the routine event's identifier in the
+                // bus; thread it as `event_id` on the audit row so the
+                // dashboard's audit log can join the reflection trace to the
+                // triggering weekly_review event.
+                eventId: event.correlationId,
+            });
+            if (result.skipped) {
+                this.appendWeeklyInterestsJournalLine(`interest reflection skipped: ${result.skipped.reason} (weekStart=${result.weekStart})`);
+            }
+            else {
+                logger.info({
+                    correlationId: event.correlationId,
+                    weekStart: result.weekStart,
+                    targetsWritten: result.targetsWritten.length,
+                    themesSelected: result.themesSelected.length,
+                    projectsAnnotated: result.projectsAnnotated,
+                }, "Weekly interests reflection pre-hook completed");
+            }
+        }
+        catch (err) {
+            // Catch-all: never propagate up to `executeDefault` — the user-
+            // facing weekly artifact must still ship. Lock contention is a
+            // distinct, expected failure mode (e.g. the dashboard's
+            // "Refresh now" button is mid-flight when the scheduler tick
+            // fires) so we tag it separately for operator clarity.
+            if (err instanceof InterestsReflectionLockBusyError) {
+                logger.warn({ err, correlationId: event.correlationId }, "Weekly interests reflection pre-hook hit lock contention — yielding to in-flight run");
+                this.appendWeeklyInterestsJournalLine(`interest reflection deferred: lock busy (${err.heldBy})`);
+                return;
+            }
+            logger.error({ err, correlationId: event.correlationId }, "Weekly interests reflection pre-hook threw — continuing to LLM session");
+            const message = err instanceof Error ? err.message : String(err);
+            this.appendWeeklyInterestsJournalLine(`interest reflection failed: ${message}`);
+        }
+    }
+    /**
+     * FEEDBACK_LEARNING_LOOP_DESIGN.md §4 — the deterministic consolidation
+     * pre-step. Reads unconsumed `feedback_signals` (user + agent + `agent:<slug>`
+     * scope as of Phase 4), reads each lessons store's current contents, and
+     * composes the `<feedback_worksheet>` block via the pure `core/feedback/*`
+     * modules. Returns the block string, or `null` when feedback learning is off,
+     * nothing pends, or anything throws — so the caller simply skips stamping and
+     * the evening review proceeds unchanged.
+     *
+     * The DB read + per-scope file read live here (the FS-/DB-heavy dispatcher
+     * is coverage-excluded); the byte-deterministic worksheet composition lives
+     * in `buildFeedbackWorksheet`, which is 100% unit-tested.
+     */
+    prepareFeedbackWorksheet() {
+        if (this.config.feedbackLearningEnabled === false)
+            return null;
+        try {
+            // Nightly retention close-out (§4 step 6 / §6): drop signal rows that
+            // were consumed past the retention horizon so the raw table stays
+            // bounded. Only touches already-consumed rows — an unconsolidated
+            // signal is never lost to retention. Runs once per Evening Review.
+            // Guarded against a missing/NaN retention knob so a config gap degrades
+            // to "skip the sweep", not "throw and abandon the whole consolidation".
+            // The guard + cutoff math live in the pure, 100%-covered
+            // `feedbackRetentionCutoff` helper (returns null → skip).
+            const retentionCutoff = feedbackRetentionCutoff(this.config.feedbackSignalRetentionDays, Date.now());
+            if (retentionCutoff) {
+                sweepConsumedFeedbackSignals(this.db, retentionCutoff);
+            }
+            const groups = gatherFeedbackWorksheetScopes(this.db, {
+                // Phase 4 adds `agent_slug` — per-agent (`agent:<slug>`) signals captured
+                // by the explicit route + behavioral sink now fold into
+                // `policies/agents/<slug>/lessons.md`. Per-scope-type fetch (not a global
+                // LIMIT) keeps an `agent_slug` backlog from starving user/agent.
+                scopeTypes: ["user", "agent", "agent_slug"],
+            });
+            if (groups.length === 0)
+                return null;
+            const contextDir = getContextDir(this.config, this.db);
+            const byteCaps = {
+                global: this.config.feedbackLessonMaxBytesGlobal,
+                perAgent: this.config.feedbackLessonMaxBytesPerAgent,
+            };
+            const scopes = [];
+            for (const group of groups) {
+                const caps = lessonCapsForScope(group.scope, byteCaps);
+                let existingFileMd = null;
+                if (caps) {
+                    const rel = scopeStoreFile(group.scope);
+                    if (rel) {
+                        const full = join(contextDir, rel);
+                        // Per-scope read isolation (FEEDBACK_LEARNING_LOOP_DESIGN.md §11
+                        // v1.9 nuance #3, now closed). A *missing* file is the normal
+                        // first-write case (existingFileMd stays null → the LLM PUTs a
+                        // fresh store); but a *present-but-unreadable* file (EACCES, a
+                        // mid-write truncation) must NOT forfeit the whole night's
+                        // consolidation. Skip just this scope: its signals stay unconsumed
+                        // and retry next Evening Review, the file is left untouched, and the
+                        // user/agent scopes that read cleanly still consolidate. Crucially
+                        // we do NOT fall back to existingFileMd=null on a read error — that
+                        // would make the LLM PUT a fresh file and destroy the existing
+                        // lessons.
+                        try {
+                            existingFileMd = existsSync(full)
+                                ? readFileSync(full, "utf-8")
+                                : null;
+                        }
+                        catch (err) {
+                            logger.warn({ err, path: rel }, "Skipping feedback scope — lessons file present but unreadable; its signals will retry next Evening Review");
+                            continue;
+                        }
+                    }
+                }
+                scopes.push({
+                    scope: group.scope,
+                    signals: group.signals,
+                    existingFileMd,
+                    caps,
+                });
+            }
+            if (scopes.length === 0)
+                return null;
+            const result = buildFeedbackWorksheet(scopes, {
+                promotionThreshold: this.config.feedbackPromotionThreshold,
+                nowIso: new Date().toISOString(),
+                staleDays: this.config.feedbackLessonStaleDays,
+            });
+            return result?.block ?? null;
+        }
+        catch (err) {
+            logger.warn({ err }, "Failed to prepare feedback worksheet");
+            return null;
+        }
+    }
+    /**
+     * FEEDBACK_LEARNING_LOOP_DESIGN.md §4 "Monthly re-generalization" / Phase 5 —
+     * the deterministic monthly pre-step. Enumerates the consolidated lesson
+     * stores on disk (the global `policies/agent-lessons.md` plus every per-agent
+     * `policies/agents/<slug>/lessons.md`), reads their contents, and composes a
+     * `<feedback_regeneralization>` block via the pure
+     * `buildRegeneralizationWorksheet`. Returns the block, or `null` when feedback
+     * learning is off, no store holds enough lessons to collapse, or anything
+     * throws — so the caller simply skips stamping and the monthly review
+     * proceeds unchanged.
+     *
+     * The FS enumeration lives here (the dispatcher is coverage-excluded); the
+     * byte-deterministic composition lives in `buildRegeneralizationWorksheet`,
+     * which is 100% unit-tested.
+     */
+    prepareRegeneralizationWorksheet() {
+        if (this.config.feedbackLearningEnabled === false)
+            return null;
+        try {
+            const contextDir = getContextDir(this.config, this.db);
+            const scopes = [];
+            // Per-file read isolation (FEEDBACK_LEARNING_LOOP_DESIGN.md §11 v1.9
+            // nuance #3, now closed): one present-but-unreadable lessons file must
+            // skip only that scope, not abandon the whole monthly collapse. A scope
+            // that fails to read is simply not surfaced for re-generalization this
+            // month; the file is left untouched.
+            const readScopeFile = (rel) => {
+                const full = join(contextDir, rel);
+                if (!existsSync(full))
+                    return null;
+                try {
+                    return readFileSync(full, "utf-8");
+                }
+                catch (err) {
+                    logger.warn({ err, path: rel }, "Skipping re-generalization scope — lessons file present but unreadable");
+                    return null;
+                }
+            };
+            // Global `agent`-scope store.
+            const globalRel = CONTEXT_RELATIVE_PATHS.agentLessons;
+            const globalMd = readScopeFile(globalRel);
+            if (globalMd !== null) {
+                scopes.push({
+                    scope: { kind: "agent" },
+                    storeFile: globalRel,
+                    existingFileMd: globalMd,
+                    caps: {
+                        capBytes: this.config.feedbackLessonMaxBytesGlobal,
+                        maxEntries: GLOBAL_LESSON_ENTRY_CAP,
+                    },
+                });
+            }
+            // Per-agent `agent:<slug>` stores under `policies/agents/<slug>/lessons.md`.
+            // The slug is the directory name; the same `isSafeAgentSlug` guard the
+            // inject + consolidate sides apply rejects any unsafe directory name so a
+            // hand-created `..`-style dir never reaches the worksheet.
+            const agentsDir = join(contextDir, "policies", "agents");
+            if (existsSync(agentsDir)) {
+                for (const entry of readdirSync(agentsDir, { withFileTypes: true })) {
+                    if (!entry.isDirectory() || !isSafeAgentSlug(entry.name))
+                        continue;
+                    const rel = agentLessonsPath(entry.name);
+                    const md = readScopeFile(rel);
+                    if (md === null)
+                        continue;
+                    scopes.push({
+                        scope: { kind: "agent_slug", ref: entry.name },
+                        storeFile: rel,
+                        existingFileMd: md,
+                        caps: {
+                            capBytes: this.config.feedbackLessonMaxBytesPerAgent,
+                            maxEntries: PER_AGENT_LESSON_ENTRY_CAP,
+                        },
+                    });
+                }
+            }
+            if (scopes.length === 0)
+                return null;
+            const result = buildRegeneralizationWorksheet(scopes, {
+                nowIso: new Date().toISOString(),
+                staleDays: this.config.feedbackLessonStaleDays,
+            });
+            return result?.block ?? null;
+        }
+        catch (err) {
+            logger.warn({ err }, "Failed to prepare feedback re-generalization worksheet");
+            return null;
+        }
+    }
+    /**
+     * Append a single bullet under `## Weekly interests reflection`
+     * inside `context/journal/agent.md`, creating the section (and the
+     * file) when absent. Mirrors the `appendToJournalSection` pattern
+     * `roadmap-maintenance.ts` uses for its own one-liner trace; kept
+     * inline here because the section header is feature-specific and
+     * the helper has zero call sites outside this module.
+     *
+     * Best-effort: any FS failure is logged and swallowed.
+     */
+    appendWeeklyInterestsJournalLine(message) {
+        // Same `this.db` thread-through as the pre-hook — keep the
+        // journal write in the same file tree the reflection writes to.
+        const contextDir = getContextDir(this.config, this.db);
+        const journalPath = join(contextDir, CONTEXT_RELATIVE_PATHS.agent.journal);
+        const now = new Date();
+        const tz = this.config.timezone ? this.config.timezone : undefined;
+        const dayStr = getAgentDayDateStr(tz, this.config.dayBoundaryHour ?? 4, now);
+        const hm = formatJournalTime(now, tz);
+        const bullet = `- ${dayStr} ${hm}: ${message}`;
+        // Fire-and-forget through the per-path serializer so the read AND
+        // the write run inside the daemon-wide write fence on
+        // `journal/agent.md`. Mirrors the roadmap-maintenance journal-line
+        // appender — without the fence, two concurrent journal appenders
+        // (this one, the morning routine, or an HTTP PATCH) would read the
+        // same pre-state and the loser's bullet would be silently dropped.
+        //
+        // The journal line is a best-effort trace — never fail the pre-hook
+        // on a journal write hiccup. The structured log is sufficient for
+        // daemon-log triage.
+        void serializeContextFileWrite(journalPath, () => {
+            const original = existsSync(journalPath)
+                ? readFileSync(journalPath, "utf-8")
+                : null;
+            // Thread `now.getTime()` so the 30-day retention window cuts
+            // deterministically against the same instant the bullet's date
+            // prefix was computed from — without it, prune would default to
+            // `Date.now()` and a long-running test (or a slow disk) could
+            // see the two diverge across the read/append boundary.
+            const next = appendToWeeklyInterestsJournalSection(original, bullet, now.getTime());
+            // The agent-write tracker must see the new content BEFORE the
+            // rename so a downstream FS-watch consumer attributes the
+            // resulting event to the agent (and not to the user). The same
+            // mark-then-write-then-unmark-on-failure dance the roadmap-
+            // maintenance journal appender uses.
+            this.writeTracker?.markWriting(journalPath, next);
+            try {
+                writeFileAtomically(journalPath, next);
+            }
+            catch (writeErr) {
+                this.writeTracker?.unmark(journalPath);
+                throw writeErr;
+            }
+        }).catch((err) => {
+            logger.error({ err }, "Failed to append weekly interests journal line");
+        });
+    }
+}
+const WEEKLY_INTERESTS_JOURNAL_SECTION = "## Weekly interests reflection";
+/**
+ * rev 4 — monthly retention window for the `## Weekly interests
+ * reflection` section. Bullets whose date prefix is older than this
+ * window get pruned on the next append. At the weekly cadence the
+ * pre-hook fires, this caps the section at ~4-5 entries.
+ *
+ * Rationale: `context/journal/agent.md` is the operator-facing trace
+ * for "why didn't my reflection fire?" type questions. Six months of
+ * weekly skip/success lines is noise — the load-bearing detail is
+ * "did it work this month and last?", which a 30-day window captures
+ * comfortably. Lines older than that live in git history if needed.
+ */
+const WEEKLY_INTERESTS_JOURNAL_RETENTION_DAYS = 30;
+/**
+ * Match the date prefix our journal bullets carry — `- YYYY-MM-DD HH:MM:`
+ * — and capture the date component. Lines that don't match (e.g. a
+ * user-authored note inside the section) are left untouched by the
+ * rotation pass; only daemon-emitted bullets get pruned.
+ */
+const JOURNAL_BULLET_DATE_RE = /^- (\d{4}-\d{2}-\d{2})\s/;
+/**
+ * Drop bullets whose date prefix is older than `retentionDays` days
+ * before `nowMs`. Pure of FS/DB; exported for tests.
+ *
+ * Lines that aren't recognisable as daemon-emitted bullets (no
+ * `- YYYY-MM-DD` prefix) are preserved as-is — the rotation only
+ * targets entries we created, never user prose someone may have
+ * dropped into the section by hand.
+ */
+export function pruneWeeklyInterestsJournalBullets(lines, bodyStart, bodyEnd, nowMs, retentionDays = WEEKLY_INTERESTS_JOURNAL_RETENTION_DAYS) {
+    const cutoffMs = nowMs - retentionDays * 24 * 60 * 60 * 1000;
+    const kept = [];
+    for (let i = bodyStart; i < bodyEnd; i++) {
+        const line = lines[i];
+        const match = JOURNAL_BULLET_DATE_RE.exec(line);
+        if (!match) {
+            kept.push(line);
+            continue;
+        }
+        // Anchor at noon UTC so a DST flip in the host's local zone
+        // cannot move the parsed date into the day before/after.
+        const dateMs = Date.parse(`${match[1]}T12:00:00Z`);
+        if (Number.isNaN(dateMs) || dateMs >= cutoffMs) {
+            kept.push(line);
+        }
+    }
+    return [...lines.slice(0, bodyStart), ...kept, ...lines.slice(bodyEnd)];
+}
+/**
+ * Append `bullet` to the `## Weekly interests reflection` section of
+ * an agent-journal file, creating section + skeleton when absent.
+ * Also prunes bullets older than the retention window (rev 4 — see
+ * `WEEKLY_INTERESTS_JOURNAL_RETENTION_DAYS`).
+ *
+ * The function is pure of FS / DB — exported only for tests.
+ */
+export function appendToWeeklyInterestsJournalSection(original, bullet, nowMs = Date.now()) {
+    if (original === null) {
+        return `# Agent journal\n\n${WEEKLY_INTERESTS_JOURNAL_SECTION}\n\n${bullet}\n`;
+    }
+    const lines = original.split("\n");
+    const bounds = findSectionLineBounds(lines, "Weekly interests reflection");
+    if (bounds) {
+        // Prune first so the section contains only the last `RETENTION_DAYS`
+        // worth of entries BEFORE we compute the insertion point — without
+        // this, a long-stale bullet at the end would push the new bullet
+        // into a section that's about to lose half its content.
+        const pruned = pruneWeeklyInterestsJournalBullets(lines, bounds.bodyStart, bounds.bodyEnd, nowMs);
+        // Re-resolve bounds after pruning — bodyEnd shifted by the
+        // delta. Section header position is unchanged so re-using
+        // bodyStart is safe; we recompute bodyEnd as the old end minus
+        // the number of lines we dropped.
+        const removedCount = lines.length - pruned.length;
+        const newBodyStart = bounds.bodyStart;
+        const newBodyEnd = bounds.bodyEnd - removedCount;
+        let insertAt = newBodyEnd;
+        while (insertAt > newBodyStart && pruned[insertAt - 1].trim() === "") {
+            insertAt -= 1;
+        }
+        const next = [
+            ...pruned.slice(0, insertAt),
+            bullet,
+            ...pruned.slice(insertAt),
+        ];
+        let out = next.join("\n");
+        if (!out.endsWith("\n"))
+            out += "\n";
+        return out;
+    }
+    const trimmed = original.replace(/\n+$/, "");
+    return `${trimmed}\n\n${WEEKLY_INTERESTS_JOURNAL_SECTION}\n\n${bullet}\n`;
+}
+/**
+ * Local 2-digit "HH:MM". Mirrors `roadmap-maintenance.ts:formatHm`
+ * (which is module-private) without re-exporting from there — the
+ * roadmap helper has the same posture (best-effort wall-clock for a
+ * journal bullet) but lives in a feature-specific module.
+ */
+function formatJournalTime(now, timezone) {
+    if (!timezone) {
+        return (`${String(now.getHours()).padStart(2, "0")}:`
+            + `${String(now.getMinutes()).padStart(2, "0")}`);
+    }
+    const fmt = new Intl.DateTimeFormat("en-US", {
+        timeZone: timezone,
+        hour: "2-digit",
+        minute: "2-digit",
+        hour12: false,
+    });
+    const parts = fmt.formatToParts(now);
+    const hh = parts.find((p) => p.type === "hour")?.value ?? "00";
+    const mm = parts.find((p) => p.type === "minute")?.value ?? "00";
+    // Intl can emit "24" for midnight in some locales — guard so the
+    // journal line is stable regardless of host locale.
+    const normalizedHh = hh === "24" ? "00" : hh;
+    return `${normalizedHh}:${mm}`;
 }
-//# sourceMappingURL=dispatcher-scheduled-tasks.js.map