@aitne/daemon 0.1.9 → 0.1.11

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

@@ -44,11 +44,12 @@
  *     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, readIntegrationState } from "../db/integrations-store.js";
 import { refreshInterestsReflection } from "../services/browser-history/refresh-interests-reflection.js";
@@ -60,6 +61,13 @@ import { getRepository, getRepositoryByLocalPath, recordManagementInitDone, reco
 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 { buildSelfPerformanceBlock, gatherSelfPerformanceData, summarizeLessonStoreUtilization, } from "./feedback/self-performance-prep.js";
+import { TUNING_PENDING_CYCLE_STATE_KEY, buildTuningRecommendations, createPendingTuningCycle, gatherFailingRecurringSchedules, renderTuningRecommendationsBlock, } from "./feedback/tuning-recommender.js";
+import { readRuntimeState, writeRuntimeState } from "../db/runtime-state.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";
@@ -198,6 +206,33 @@ export const REFRESH_ARCHITECTURE_ALLOWED_TOOLS = [
     "Bash(curl http://localhost:8321/api/repositories/*/architecture-section*)",
     "Bash(jq *)",
 ];
+/**
+ * BACKGROUND_TASK_RUNNER_DESIGN.md §4.5 / §4.5-bis / Phase 4 — the active
+ * delivery turn is a NO-TOOL DM turn. Its sole job is to weave the
+ * already-injected artifact (`taskContext.task_delivery.report` carries the
+ * full verbatim result) into the live conversation; the agent's reply text
+ * IS the DM (recorded by the result processor) and any deliverable files
+ * are attached by the daemon, not by the agent. So the turn needs no tools
+ * at all — and an EMPTY override structurally prevents it from taking
+ * "further action" (spawning another task, writing memory, sending mail)
+ * during what should be a pure phrasing turn. Follow-up turns ("what did it
+ * find?") are ordinary DM turns and keep the full envelope, including the
+ * `GET /api/background-task/:id` read affordance.
+ */
+export const TASK_DELIVERY_TURN_ALLOWED_TOOLS = [];
+/**
+ * True when `taskCtx` is a synthetic `scheduled.dm` event minted by the
+ * task-delivery handler (`createScheduledDmDeliveryEvent`) — the only place
+ * that sets the `task_delivery` block. Used to pin the no-tool clamp above.
+ * Keying off this structural marker (not `event.source`) is fail-safe: the
+ * clamp only ever NARROWS the envelope, so a false positive degrades a turn
+ * to no-tool rather than widening anything.
+ */
+export function isTaskDeliveryTurn(taskCtx) {
+    return (!!taskCtx
+        && typeof taskCtx === "object"
+        && "task_delivery" in taskCtx);
+}
 /**
  * Backends that honor the per-execute `allowedToolsOverride` clamp end-to-
  * end. Claude consumes the list verbatim through the SDK's `dontAsk` +
@@ -209,6 +244,14 @@ export const REFRESH_ARCHITECTURE_ALLOWED_TOOLS = [
  * envelope; the operator sees an `agent_actions` row of action_type
  * `scheduled_task_clamp_unsupported` and a clear log line.
  *
+ * Exception — the Phase-4 task-delivery turn (`isTaskDeliveryTurn`)
+ * consumes this same set but DEGRADES rather than refuses: when the
+ * resolved backend can't enforce `[]` it still runs the delivery turn
+ * with the default envelope (logged), because failing to deliver the
+ * owner's result is worse than running the phrasing turn untooled. The
+ * clamp is keyed off `binding.main.backendId`, so — as with the refuse
+ * path — a runtime fallback to a non-claude backend is not re-evaluated.
+ *
  * Add a backend here only after verifying its core threads
  * `allowedToolsOverride` through to its concrete deny enforcement layer
  * — NOT just into the CLI flag set.
@@ -227,6 +270,7 @@ export class ScheduledTaskRunner {
     morningRoutine;
     fetchWindowRunner;
     roadmapWriteLock;
+    todayWriteLock;
     writeTracker;
     getConfiguredServices;
     getActiveMailAccounts;
@@ -243,6 +287,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;
@@ -454,6 +499,23 @@ export class ScheduledTaskRunner {
             this.markScheduledTaskCompleted(event);
             return;
         }
+        // BACKGROUND_TASK_RUNNER_DESIGN.md §4.5 / Phase 4 — pin the no-tool
+        // clamp on the active delivery turn. Mutually exclusive with the
+        // refresh-architecture clamp (a delivery turn is never that process
+        // key). Unlike the safety-critical refresh/curation clamps, this is a
+        // HARDENING: when the resolved backend can't enforce a per-execute
+        // clamp we DEGRADE (deliver with the default envelope) rather than
+        // refuse — failing to deliver the owner's result would be the worse
+        // outcome. The degrade is logged per the "no silent drops" posture.
+        const taskDeliveryToolClamp = isTaskDeliveryTurn(taskCtx)
+            ? TOOL_CLAMP_SUPPORTING_BACKENDS.has(binding.main.backendId)
+                ? TASK_DELIVERY_TURN_ALLOWED_TOOLS
+                : undefined
+            : undefined;
+        if (isTaskDeliveryTurn(taskCtx) && taskDeliveryToolClamp === undefined) {
+            logger.info({ backendId: binding.main.backendId, correlationId: event.correlationId }, "task.delivery active turn: resolved backend does not honor the per-execute tool clamp; delivering with the default DM envelope (degraded, not refused)");
+        }
+        const effectiveAllowedToolsOverride = refreshArchitectureOverride ?? taskDeliveryToolClamp;
         // 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
@@ -467,8 +529,8 @@ export class ScheduledTaskRunner {
             requestedTier,
             preResolvedBinding: binding,
             reassemblePrompt,
-            ...(refreshArchitectureOverride
-                ? { allowedToolsOverride: refreshArchitectureOverride }
+            ...(effectiveAllowedToolsOverride
+                ? { allowedToolsOverride: effectiveAllowedToolsOverride }
                 : {}),
             ...(agentSkillOverride
                 ? {
@@ -801,7 +863,7 @@ export class ScheduledTaskRunner {
         //     row insert (today.md is fresh, audit row is missing);
         //   - the user manually edits today.md to the current date (CLAUDE.md
         //     calls this out as a documented edit path).
-        // In both, the hourly_check pre-routine gate (`morningRoutineRanToday`)
+        // In both, the activity_scan pre-routine gate (`morningRoutineRanToday`)
         // would keep refusing to run because the audit row is absent, the
         // pre-routine gate kept enqueuing wake rows, and each wake row was
         // fast-path completed here — never producing the audit row that would
@@ -837,6 +899,15 @@ export class ScheduledTaskRunner {
         // carries the previous attempt so executeMorningRoutine → scheduleMorningRetry
         // can increment properly. correlationId tracks back to the original
         // cron morning_routine for log correlation.
+        //
+        // `agentId` is carried over from the wake event (stamped there by
+        // `Dispatcher.beginAgentExecution` via `task_context.agent_id` /
+        // `task_context.routine`): the cron path's RoutineEvent gets the stamp
+        // directly, so dropping it here would make run-now / retry firings
+        // ignore the morning-routine Agent's overrides + lesson injection while
+        // cron firings honour them — the same manual-vs-cron divergence class
+        // AGENT_DEFINITIONS_KNOWN_LIMITATIONS §1 fixed for user Agents.
+        const wakeAgentId = event.data?.agentId;
         const synthEvent = {
             ...createEvent({
                 type: "routine.morning_routine",
@@ -848,12 +919,15 @@ export class ScheduledTaskRunner {
                 priority: retryCount > 0 ? EventPriority.NORMAL : EventPriority.HIGH,
                 correlationId: taskCtx.originalCorrelationId ?? event.correlationId,
                 data: {
+                    ...(typeof wakeAgentId === "string" && wakeAgentId.length > 0
+                        ? { agentId: wakeAgentId }
+                        : {}),
                     ...(retryCount > 0 ? { retryCount, isRetry: true } : {}),
                     ...(Array.isArray(taskCtx.postCatchupRoutines)
                         ? { postCatchupRoutines: taskCtx.postCatchupRoutines }
                         : {}),
-                    ...(taskCtx.postCatchupHourlyCheck === true
-                        ? { postCatchupHourlyCheck: true }
+                    ...(taskCtx.postCatchupActivityScan === true
+                        ? { postCatchupActivityScan: true }
                         : {}),
                     ...(typeof taskCtx.source === "string"
                         ? { queuedSource: taskCtx.source }
@@ -1061,7 +1135,7 @@ export class ScheduledTaskRunner {
         try {
             // docs/design/appendices/routine-data-acquisition.md Phase 4 / D4 — pre-pass for
             // routine events whose ProcessKey appears in `ROUTINE_WINDOWS`
-            // (today_refresh, evening_review, weekly_review). The hourly_check
+            // (today_refresh, evening_review, weekly_review). The activity_scan
             // and morning_routine dispatch paths attach their own
             // `fetchReportBlock` upstream (D2 / D3); we honour an existing
             // attachment to avoid double-spawning the fetcher. `monthly_review`
@@ -1085,6 +1159,81 @@ 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
@@ -1097,6 +1246,36 @@ export class ScheduledTaskRunner {
             if (isRoutineEvent(effectiveEvent)
                 && effectiveEvent.routine === "weekly_review") {
                 this.runWeeklyInterestsReflectionPreHook(effectiveEvent);
+                // SELF_TUNING_REVIEW_CYCLE_DESIGN.md §3.1 + §3.2 / Phases 1–2 —
+                // deterministic Measure + Recommend pre-steps for
+                // `routine.weekly_review`. Run synchronously BEFORE
+                // `contextBuilder.build` so the `<self_performance>` block (7-day
+                // per-routine run/cost/duration aggregates + fetch_window empty-run
+                // rates + hourly-gate stage distribution + notification reaction
+                // breakdown + self-tuning ledger) and the `<tuning_recommendations>`
+                // block (Phase 2 rule-table output for the Phase 3c verdict step)
+                // land in the weekly session's context. Both share one gather pass;
+                // each is independently failure-isolated inside
+                // `prepareSelfTuningBlocks` — a throw is swallowed and the review
+                // still ships. Either block is omitted entirely when empty (no
+                // empty XML in the prompt).
+                const selfTuning = this.prepareSelfTuningBlocks();
+                if (selfTuning.selfPerformanceBlock || selfTuning.tuningRecommendationsBlock) {
+                    effectiveEvent = {
+                        ...effectiveEvent,
+                        data: {
+                            ...effectiveEvent.data,
+                            ...(selfTuning.selfPerformanceBlock
+                                ? { selfPerformanceBlock: selfTuning.selfPerformanceBlock }
+                                : {}),
+                            ...(selfTuning.tuningRecommendationsBlock
+                                ? {
+                                    tuningRecommendationsBlock: selfTuning.tuningRecommendationsBlock,
+                                }
+                                : {}),
+                        },
+                    };
+                }
             }
             const context = await this.contextBuilder.build(effectiveEvent);
             const processKey = resolveProcessKey(effectiveEvent);
@@ -1277,6 +1456,299 @@ export class ScheduledTaskRunner {
             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;
+        }
+    }
+    /**
+     * SELF_TUNING_REVIEW_CYCLE_DESIGN.md §3.1 + §3.2 / Phases 1–2 — the
+     * deterministic Measure + Recommend pre-steps. Computes the 7-day window +
+     * 7-day-prior baseline SQL aggregates over `agent_actions` /
+     * `notification_log` / the `runtime_state.self_tuning:*` ledger, reads each
+     * lesson store's byte pressure (§3.5), and composes the
+     * `<self_performance>` block via the pure
+     * `core/feedback/self-performance-prep.ts` module. The same gathered data
+     * then feeds the Phase 2 rule table (`core/feedback/tuning-recommender.ts`):
+     * the resulting pending cycle is persisted to
+     * `runtime_state.self_tuning.pending_cycle` — overwriting (and thereby
+     * expiring, §3.4 single-use ids) the previous cycle even when this week
+     * produced zero recommendations — and rendered as the
+     * `<tuning_recommendations>` block for the Phase 3c verdict step.
+     *
+     * Either field is `null` when there is nothing to inject or its step threw —
+     * the caller simply skips stamping and the weekly review proceeds
+     * unchanged. The Recommend step is failure-isolated from the Measure step:
+     * a recommender throw never drops the `<self_performance>` block.
+     *
+     * The DB handle + lesson-file FS reads live here (the dispatcher is
+     * coverage-excluded); the byte-deterministic aggregation, rule table, and
+     * rendering live in the pure modules, which are 100% unit-tested. Unlike
+     * the consolidation/re-generalization pre-steps this is NOT gated on
+     * `feedbackLearningEnabled` — it measures core daemon telemetry, not the
+     * lesson loop; nor on `selfTuningEnabled` — that flag gates Phase 3
+     * *actuation* only, while recommendation generation + verdict recording IS
+     * the Phase 2 shadow period (§7). An unreadable lesson store only drops the
+     * `<lesson_stores>` rows / the R5 input, never the whole block.
+     */
+    prepareSelfTuningBlocks() {
+        try {
+            const now = new Date();
+            const data = gatherSelfPerformanceData(this.db, { now });
+            const lessonStores = [];
+            const contextDir = getContextDir(this.config, this.db);
+            const readStoreFile = (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 lesson store in self-performance block — file present but unreadable");
+                    return null;
+                }
+            };
+            const globalMd = readStoreFile(CONTEXT_RELATIVE_PATHS.agentLessons);
+            if (globalMd !== null) {
+                lessonStores.push(summarizeLessonStoreUtilization("agent", globalMd, this.config.feedbackLessonMaxBytesGlobal));
+            }
+            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 md = readStoreFile(agentLessonsPath(entry.name));
+                    if (md === null)
+                        continue;
+                    lessonStores.push(summarizeLessonStoreUtilization(`agent:${entry.name}`, md, this.config.feedbackLessonMaxBytesPerAgent));
+                }
+            }
+            const selfPerformanceBlock = buildSelfPerformanceBlock(data, {
+                generatedAt: now.toISOString(),
+                lessonStores,
+            });
+            // Phase 2 Recommend step — isolated so a recommender failure cannot
+            // cost the weekly session its Measure block.
+            let tuningRecommendationsBlock = null;
+            try {
+                const recommendations = buildTuningRecommendations({
+                    data,
+                    knobs: {
+                        activityScanPrePassFreshnessMinutes: this.config.activityScanPrePassFreshnessMinutes,
+                        activityScanLowSignalPendingCeiling: this.config.activityScanLowSignalPendingCeiling,
+                        feedbackLessonMaxBytesGlobal: this.config.feedbackLessonMaxBytesGlobal,
+                    },
+                    lessonStores,
+                    failingSchedules: gatherFailingRecurringSchedules(this.db),
+                    now,
+                });
+                // Read the outgoing blob before overwriting: a SAME-day re-run
+                // (manual `!run` / crash retry) regenerates the same cycle id and
+                // ids, and verdicts already recorded against them must survive —
+                // otherwise the re-run session re-verdicts judged ids and
+                // double-posts rejection self_critique signals. A prior-day blob
+                // is ignored inside createPendingTuningCycle (§3.4 expiry).
+                const previousCycle = readRuntimeState(this.db, TUNING_PENDING_CYCLE_STATE_KEY);
+                const cycle = createPendingTuningCycle(recommendations, now.toISOString(), previousCycle);
+                // Always persist — an empty cycle still expires last week's
+                // single-use verdict ids (§3.4).
+                writeRuntimeState(this.db, TUNING_PENDING_CYCLE_STATE_KEY, cycle);
+                // Phase 3 — the block's `mode` attribute tells the weekly session
+                // whether apply verdicts actuate (`live`) or are recorded only
+                // (`shadow`), so the task-flow never has to guess the flag state.
+                tuningRecommendationsBlock = renderTuningRecommendationsBlock(cycle, {
+                    mode: this.config.selfTuningEnabled === true ? "live" : "shadow",
+                });
+            }
+            catch (err) {
+                logger.warn({ err }, "Failed to prepare tuning recommendations");
+            }
+            return { selfPerformanceBlock, tuningRecommendationsBlock };
+        }
+        catch (err) {
+            logger.warn({ err }, "Failed to prepare self-performance block");
+            return { selfPerformanceBlock: null, tuningRecommendationsBlock: 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