@aitne/daemon 0.1.9 → 0.1.11

package/dist/core/dispatcher-result-processor.js

@@ -42,10 +42,13 @@ import { isAgentTaskEvent, isDocsQAMessage, isMessageEvent, isRoutineEvent, isSc
 import { getContextDir } from "../config.js";
 import { finalizeRetemplate } from "./template-store.js";
 import { recordManagementInitDone, recordManagementScan, } from "../db/repositories-store.js";
-import { formatForwardSuffix, getProactiveForwardType, isProactiveForwardMetadata, parseMessageMetadata, recordProactiveForwardDeliveries, } from "./channel-timeline.js";
+import { formatForwardSuffix, isProactiveForwardMetadata, parseMessageMetadata, recordProactiveForwardDeliveries, } from "./channel-timeline.js";
 import { randomUUID } from "node:crypto";
+import { statSync } from "node:fs";
+import { join } from "node:path";
 import { OWNER_DM_SCOPE, OWNER_SCOPE_KEY, DASHBOARD_CHAT_SCOPE, DASHBOARD_SCOPE_KEY, getConversationScope, } from "../messaging/constants.js";
 import { readEventReplyTarget } from "./wiki/dispatcher.js";
+import { TASK_DELIVERY_ATTACHMENTS_KEY } from "./dispatcher-task-delivery.js";
 import { createLogger } from "../logging.js";
 import { assertOutboundAllowedForAgent, OutboundPurchaseTemplateError, } from "../safety/outbound-purchase-guard.js";
 const logger = createLogger("dispatcher-result");
@@ -138,6 +141,16 @@ export class ResultProcessor {
                     threadId: explicitReply.threadId ?? null,
                 };
             }
+            // BACKGROUND_TASK_RUNNER_DESIGN.md Phase 1 (delivery assets) — the
+            // task.delivery active turn is a no-tool DM turn, so the daemon (not
+            // the agent) attaches any deliverable files the task produced. The
+            // delivery handler resolved them and stashed the refs on the
+            // synthetic event; carry them onto the woven reply send. Only ever
+            // populated for the synthetic scheduled.dm delivery event.
+            const deliveryAttachments = readTaskDeliveryAttachments(event);
+            if (deliveryAttachments.length > 0 && explicitReply) {
+                sendOptions.attachments = deliveryAttachments;
+            }
             // MANAGED_CHROMIUM_IMPLEMENTATION_PLAN.md §17.7 structural-anti-
             // spoofing layer. The LLM's outbound text reaches the messaging
             // adapter via this notificationMgr.send chokepoint; refuse any
@@ -189,6 +202,7 @@ export class ResultProcessor {
             // the send itself, so wrap in try/catch.
             if (explicitReply && output.length > 0) {
                 try {
+                    const taskDeliveryRecord = readTaskDeliveryRecord(event);
                     recordProactiveForwardDeliveries({
                         db: this.db,
                         config: this.config,
@@ -203,7 +217,10 @@ export class ResultProcessor {
                         ...(options.originSessionId !== undefined
                             ? { originSessionIds: [options.originSessionId] }
                             : {}),
-                        notificationType: "proactive_forward",
+                        notificationType: taskDeliveryRecord?.notificationType ?? "proactive_forward",
+                        ...(taskDeliveryRecord
+                            ? { extraMetadata: taskDeliveryRecord.metadata }
+                            : {}),
                     });
                 }
                 catch (err) {
@@ -213,6 +230,24 @@ export class ResultProcessor {
                 }
             }
         }
+        // RESEARCH_CLUSTER_COST_FIX_PLAN F5 — outcome verification. The
+        // routine.research_cluster_update flow's ONLY deliverable is the
+        // per-cluster journal at context/research/<slug>.md. The 2026-06-11
+        // incident showed the flow ending "successfully" (no backend error,
+        // num_turns=1) while never writing the file — every "success" was a
+        // text-only narration. Upgrade "success" from "the session ended
+        // without a backend error" to "...AND the journal was written this
+        // run": a clean-but-unwritten run is recorded as `partial` /
+        // `journal_write_missing` (surfaced in the dashboard activity feed,
+        // `!report`, and `aitne audit --result partial`) rather than a
+        // misleading success. Gated to clean runs — a hard error already took
+        // the logError path with a more informative message.
+        const outcomeOverride = isRoutineEvent(event)
+            && event.routine === "research_cluster_update"
+            && !result.isError
+            && !this.researchClusterJournalWritten(event, result)
+            ? { result: "partial", error: "journal_write_missing" }
+            : undefined;
         this.audit.logAction({
             event,
             model: result.model,
@@ -226,6 +261,7 @@ export class ResultProcessor {
             costSource: result.costSource,
             contextUpdated: result.contextUpdated,
             advisorCallCount: result.advisorCallCount,
+            ...(outcomeOverride ?? {}),
             ...(options.dmFreshness ? { dmFreshness: options.dmFreshness } : {}),
             ...(options.dailyWrite ? { dailyWrite: options.dailyWrite } : {}),
         });
@@ -249,7 +285,7 @@ export class ResultProcessor {
         //  - github.*        (GitHub poller high-priority events)
         //  - git.*           (git watcher batched events)
         //  - notion.*        (notion poller)
-        //  - routine.hourly_check (Phase-9 polling sink for obsidian/git/notion)
+        //  - routine.activity_scan (Phase-9 polling sink for obsidian/git/notion)
         if (this.isObserverEvent(event)) {
             logger.info({
                 eventType: event.type,
@@ -450,13 +486,9 @@ export class ResultProcessor {
         if (message.role !== "assistant")
             return message.role;
         const metadata = parseMessageMetadata(message.metadata);
-        const type = getProactiveForwardType(metadata);
-        if (type === "scheduled_dm") {
-            return "assistant (scheduled DM dispatched)";
-        }
-        if (type !== null) {
-            return "assistant (forwarded from autonomous run)";
-        }
+        const suffix = formatForwardSuffix(metadata);
+        if (suffix.length > 0)
+            return `assistant${suffix}`;
         return message.role;
     }
     buildCrossSessionConversationHistory(event) {
@@ -546,13 +578,91 @@ export class ResultProcessor {
      * contextUpdated observability log in processResult.
      */
     isObserverEvent(event) {
-        return ((isRoutineEvent(event) && event.routine === "hourly_check") ||
+        return ((isRoutineEvent(event) && event.routine === "activity_scan") ||
             event.type.startsWith("calendar.") ||
             event.type === "schedule.approaching" ||
             event.type.startsWith("notion.") ||
             event.type.startsWith("github.") ||
             event.type.startsWith("git."));
     }
+    /**
+     * RESEARCH_CLUSTER_COST_FIX_PLAN F5 — was the cluster journal actually
+     * written during this `routine.research_cluster_update` run?
+     *
+     * Detection is the on-disk journal file itself — the authoritative,
+     * path-specific, backend-agnostic signal. The daemon writes the journal
+     * via the context-API chokepoint (`writeFileAtomically`), so the file's
+     * mtime reflects the real write time; a write that landed inside the run
+     * window (`[min(event enqueue, now − durationMs) − buffer, now]`) proves
+     * the agent executed the append rather than narrating success.
+     *
+     * Why not the `context_write` audit row (the plan's first idea): that
+     * row is emitted only inside `notifyPromptContextChanged`, which fires
+     * solely for prompt-refreshing paths (`shouldRefreshPromptContext`).
+     * `research/*` is intentionally a *quiet* namespace — it never triggers
+     * a refresh — so a research write records **no** `context_write` row.
+     * (The plan's §1 "zero context_write rows ⇒ zero writes" inference was
+     * therefore unsound for this namespace; the on-disk check has none of
+     * that coupling.) F1 guarantees ≤ 1 cluster_update run/cluster/day, so
+     * the run window cannot collide with another run writing the same file;
+     * the sibling research flows write *different* files
+     * (`<slug>-assistance-<date>.md`, `<slug>-wiki.md`), never `<slug>.md`.
+     *
+     * Returns `true` (treat as written — do NOT downgrade) when the slug is
+     * absent/invalid or the stat fails for any reason other than ENOENT: a
+     * verification fault must never relabel a genuinely-successful run.
+     */
+    researchClusterJournalWritten(event, result) {
+        const data = (event.data ?? {});
+        const slug = typeof data.slug === "string" ? data.slug : null;
+        // Defense in depth against path traversal even though the slug comes
+        // from the daemon's own cluster table — same sanitized character set
+        // the context-API whitelist enforces (PLACEHOLDER_SEGMENT_RE).
+        if (!slug || !/^[a-z0-9._-]+$/.test(slug)) {
+            logger.warn({ correlationId: event.correlationId, slug }, "research_cluster_update: missing/invalid slug — skipping journal-write verification");
+            return true;
+        }
+        // Resolve the dir WITHOUT the db argument, mirroring the context
+        // route's own `getCurrentContextDir` (api/routes/context/index.ts):
+        // with `db`, `getContextDir` falls back to the legacy
+        // `<dataDir>/context` while the vault is degraded — but the write
+        // route never writes there (degraded mode 503s every request), so
+        // statting the fallback could mislabel a run that wrote to the real
+        // vault just before degraded mode engaged. Always stat the path the
+        // agent's writes would have landed at.
+        const journalPath = join(getContextDir(this.config), "research", `${slug}.md`);
+        // Anchor the window at the event's enqueue time when it is older than
+        // `now − durationMs`: `durationMs` covers only the FINAL backend
+        // attempt, so a write made during an earlier `executeWithRetry`
+        // attempt (or before any dispatcher latency between run end and this
+        // check) would otherwise fall outside the window and downgrade a run
+        // that DID write. Widening backwards is safe — F1 guarantees at most
+        // one run per cluster per agent day and no sibling flow writes
+        // `<slug>.md`, so the only possible writer inside the widened window
+        // is this run.
+        const bufferMs = 5_000;
+        const eventCreatedMs = event.timestamp instanceof Date
+            ? event.timestamp.getTime()
+            : Date.parse(String(event.timestamp));
+        const runStartMs = Date.now() - (result.durationMs ?? 0);
+        const windowStartMs = (Number.isFinite(eventCreatedMs)
+            ? Math.min(eventCreatedMs, runStartMs)
+            : runStartMs) - bufferMs;
+        try {
+            return statSync(journalPath).mtimeMs >= windowStartMs;
+        }
+        catch (err) {
+            if (err.code === "ENOENT") {
+                // File never created — the strongest "not written" signal.
+                return false;
+            }
+            /* c8 ignore next 5 — non-ENOENT stat failure (e.g. EACCES) is not
+             * reproducible in the test harness; the conservative fall-through
+             * (treat as written) is asserted indirectly by the ENOENT path. */
+            logger.warn({ err, journalPath, correlationId: event.correlationId }, "research_cluster_update: journal stat failed — skipping verification");
+            return true;
+        }
+    }
     /**
      * Confirm that a `wiki.ingest_url` session actually wrote a raw note via
      * the Wiki API before letting the agent's claimed success DM reach the
@@ -620,3 +730,49 @@ export class ResultProcessor {
         return `Failed ${url ?? "<url>"} — agent reported completion but no raw note was POSTed via the Wiki API; the vault is unchanged.`;
     }
 }
+export function readTaskDeliveryRecord(event) {
+    const raw = event.data
+        ?.task_delivery_record;
+    if (!raw || typeof raw !== "object" || Array.isArray(raw))
+        return null;
+    const record = raw;
+    if (record.notificationType !== "task_result"
+        && record.notificationType !== "task_clarification"
+        // Phase 4 autonomous-forward natural delivery: the active weave turn
+        // carries a task_delivery_record whose notificationType is
+        // "proactive_forward" (autonomous forwards have no task row, so they
+        // reuse the proactive_forward type). Its metadata still tags the woven
+        // message with taskKind/deliveredTaskId so `deliverActive`'s
+        // message-existence check can confirm the weave landed and skip the
+        // verbatim re-send. Without accepting it here the metadata is dropped,
+        // the existence check misses, and the owner receives BOTH the woven DM
+        // and a verbatim duplicate.
+        && record.notificationType !== "proactive_forward") {
+        return null;
+    }
+    const metadata = record.metadata
+        && typeof record.metadata === "object"
+        && !Array.isArray(record.metadata)
+        ? record.metadata
+        : {};
+    return {
+        notificationType: record.notificationType,
+        metadata,
+    };
+}
+/**
+ * Resolved deliverable-file refs the task.delivery handler stashed on the
+ * synthetic `scheduled.dm` event (BACKGROUND_TASK_RUNNER_DESIGN.md Phase 1
+ * — delivery assets). Returns `[]` for every ordinary event. Shape is
+ * validated loosely — a malformed entry is dropped rather than thrown so a
+ * bad ref never blocks the woven reply.
+ */
+function readTaskDeliveryAttachments(event) {
+    const raw = event.data?.[TASK_DELIVERY_ATTACHMENTS_KEY];
+    if (!Array.isArray(raw))
+        return [];
+    return raw.filter((a) => !!a
+        && typeof a === "object"
+        && typeof a.path === "string"
+        && typeof a.id === "string");
+}

package/dist/core/dispatcher-scheduled-background-task.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Dispatcher handler for `scheduled.background_task`
+ * (BACKGROUND_TASK_RUNNER_DESIGN.md §4.2).
+ *
+ * Lifts fire-time row creation + runner handoff out of `dispatcher.ts`,
+ * mirroring `dispatcher-scheduled-browser-task.ts` but with the whole
+ * allowlist / site-registry plane removed — a background task carries
+ * only a self-contained brief.
+ *
+ * Flow:
+ *   1. Re-validate the persisted `task_context` (a hand-crafted DB row
+ *      cannot smuggle invalid fields through the scheduler boundary).
+ *   2. Dedup on `preGeneratedTaskId` (a scheduler/dispatcher restart
+ *      between event.put and dispatch must not double-insert).
+ *   3. Insert the `background_task` row pinned to the pre-generated id.
+ *   4. Hand off to the runner. The runner's RunResult drives the
+ *      `background_task` lifecycle from here; the `agent_schedule` row's
+ *      status is independent (the dispatcher marks it completed on
+ *      successful dispatch, failed on rejection).
+ */
+import type Database from "better-sqlite3";
+import type { ScheduledBackgroundTaskEvent } from "@aitne/shared";
+import type { BackgroundTaskRunner } from "../services/background-task/background-task-runner.js";
+export type ScheduledBackgroundTaskOutcome = {
+    kind: "dispatched";
+    taskId: string;
+} | {
+    kind: "task_context_invalid";
+    reason: string;
+} | {
+    kind: "row_already_exists";
+    taskId: string;
+} | {
+    kind: "runner_unavailable";
+    taskId: string;
+};
+export interface BackgroundTaskDispatchDeps {
+    db: Database.Database;
+    runner: BackgroundTaskRunner | null;
+    nowFn?: () => number;
+}
+export declare function handleScheduledBackgroundTask(deps: BackgroundTaskDispatchDeps, event: ScheduledBackgroundTaskEvent): Promise<ScheduledBackgroundTaskOutcome>;

package/dist/core/dispatcher-scheduled-background-task.js

@@ -0,0 +1,89 @@
+/**
+ * Dispatcher handler for `scheduled.background_task`
+ * (BACKGROUND_TASK_RUNNER_DESIGN.md §4.2).
+ *
+ * Lifts fire-time row creation + runner handoff out of `dispatcher.ts`,
+ * mirroring `dispatcher-scheduled-browser-task.ts` but with the whole
+ * allowlist / site-registry plane removed — a background task carries
+ * only a self-contained brief.
+ *
+ * Flow:
+ *   1. Re-validate the persisted `task_context` (a hand-crafted DB row
+ *      cannot smuggle invalid fields through the scheduler boundary).
+ *   2. Dedup on `preGeneratedTaskId` (a scheduler/dispatcher restart
+ *      between event.put and dispatch must not double-insert).
+ *   3. Insert the `background_task` row pinned to the pre-generated id.
+ *   4. Hand off to the runner. The runner's RunResult drives the
+ *      `background_task` lifecycle from here; the `agent_schedule` row's
+ *      status is independent (the dispatcher marks it completed on
+ *      successful dispatch, failed on rejection).
+ */
+import { z } from "zod";
+import { createBackgroundTask, getBackgroundTask, markTerminal, } from "../db/background-task-store.js";
+import { createLogger } from "../logging.js";
+const logger = createLogger("dispatcher-scheduled-background-task");
+const taskContextSchema = z.object({
+    preGeneratedTaskId: z.string().uuid(),
+    brief: z.string().min(1).max(16_384),
+    title: z.string().min(1).max(200).nullable().optional(),
+    notificationPolicy: z
+        .enum(["always", "if_significant", "silent"])
+        .optional(),
+    significanceCriteria: z
+        .array(z.string().min(1).max(500))
+        .max(12)
+        .nullable()
+        .optional(),
+    tier: z.enum(["lite", "medium", "high"]).nullable().optional(),
+    maxBudgetUsd: z.number().positive().max(15).nullable().optional(),
+    originatingChannel: z.string().nullable().optional(),
+});
+export async function handleScheduledBackgroundTask(deps, event) {
+    const now = deps.nowFn ?? (() => Date.now());
+    const parsed = taskContextSchema.safeParse(event.taskContext);
+    if (!parsed.success) {
+        const reason = parsed.error.issues
+            .slice(0, 3)
+            .map((issue) => `${issue.path.join(".") || "<root>"}: ${issue.message}`)
+            .join("; ");
+        logger.error({ scheduleId: event.scheduleId, reason }, "scheduled.background_task: task_context failed schema validation");
+        return { kind: "task_context_invalid", reason };
+    }
+    const ctx = parsed.data;
+    const existing = getBackgroundTask(deps.db, ctx.preGeneratedTaskId);
+    if (existing) {
+        logger.warn({ taskId: ctx.preGeneratedTaskId, scheduleId: event.scheduleId, state: existing.state }, "scheduled.background_task: row already exists for preGeneratedTaskId — skipping re-dispatch");
+        return { kind: "row_already_exists", taskId: ctx.preGeneratedTaskId };
+    }
+    createBackgroundTask(deps.db, {
+        id: ctx.preGeneratedTaskId,
+        brief: ctx.brief,
+        title: ctx.title ?? null,
+        notificationPolicy: ctx.notificationPolicy ?? "always",
+        significanceCriteria: ctx.significanceCriteria ?? null,
+        originatingChannel: ctx.originatingChannel ?? null,
+        correlationId: event.correlationId ?? null,
+        scheduleRowId: event.scheduleId,
+        tier: ctx.tier ?? null,
+        maxBudgetUsd: ctx.maxBudgetUsd ?? null,
+        createdAt: now(),
+    });
+    if (!deps.runner) {
+        markTerminal(deps.db, {
+            id: ctx.preGeneratedTaskId,
+            state: "failed",
+            outcomeDetail: "runner_unavailable",
+            finishedAt: now(),
+            report: "The background-task runner was not wired at fire time.",
+            draft: "That scheduled task couldn't start — the runner was unavailable.",
+            notify: true,
+        });
+        logger.warn({ taskId: ctx.preGeneratedTaskId, scheduleId: event.scheduleId }, "scheduled.background_task: runner not wired — marked failed (runner_unavailable)");
+        return { kind: "runner_unavailable", taskId: ctx.preGeneratedTaskId };
+    }
+    void deps.runner.runFromScheduleRow(ctx.preGeneratedTaskId).catch((err) => {
+        logger.error({ err, taskId: ctx.preGeneratedTaskId, scheduleId: event.scheduleId }, "background-task runFromScheduleRow threw — task left in pending state");
+    });
+    logger.info({ taskId: ctx.preGeneratedTaskId, scheduleId: event.scheduleId }, "scheduled.background_task dispatched to runner");
+    return { kind: "dispatched", taskId: ctx.preGeneratedTaskId };
+}

package/dist/core/dispatcher-scheduled-tasks.d.ts

@@ -46,6 +46,7 @@
 import type Database from "better-sqlite3";
 import type { AgentTaskEvent, BackendId, Event } from "@aitne/shared";
 import type { AgentConfig } from "../config.js";
+import type { TodayWriteLockManager } from "./today-write-lock.js";
 import type { IAgentRouter } from "./backends/backend-router.js";
 import type { RoadmapWriteLockManager } from "./roadmap-write-lock.js";
 import type { AgentWriteTracker } from "../safety/agent-write-tracker.js";
@@ -195,6 +196,29 @@ export declare const SKILL_CURATION_OPTIMIZER_ALLOWED_TOOLS: readonly ["Read", "
  *     consciously.
  */
 export declare const REFRESH_ARCHITECTURE_ALLOWED_TOOLS: readonly ["Read", "Glob", "Grep", "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 declare const TASK_DELIVERY_TURN_ALLOWED_TOOLS: readonly string[];
+/**
+ * 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 declare function isTaskDeliveryTurn(taskCtx: AgentTaskEvent["taskContext"]): boolean;
 /**
  * Backends that honor the per-execute `allowedToolsOverride` clamp end-to-
  * end. Claude consumes the list verbatim through the SDK's `dontAsk` +
@@ -206,6 +230,14 @@ export declare const REFRESH_ARCHITECTURE_ALLOWED_TOOLS: readonly ["Read", "Glob
  * 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.
@@ -226,12 +258,21 @@ export interface ScheduledTaskRunnerDeps {
      * in `ROUTINE_WINDOWS` (today_refresh / evening_review / weekly_review;
      * monthly_review is registered but has zero rows so the runner
      * short-circuits without dispatching a session). Idempotent against
-     * the morning_routine + hourly_check paths: when the upstream
+     * the morning_routine + activity_scan paths: when the upstream
      * dispatcher already attached a `fetchReportBlock`, `executeDefault`
      * skips re-running the pre-pass.
      */
     fetchWindowRunner: RoutineFetchWindowRunner;
     roadmapWriteLock: RoadmapWriteLockManager | undefined;
+    /**
+     * Cross-session today.md write lock. Used by `executeDefault` to seed a
+     * `today.md` skeleton (lock-aware, absent-only) before a
+     * `routine.today_refresh` session so its section PATCH never 404s — see
+     * `ensureTodaySkeleton`. Undefined when the dispatcher was constructed
+     * without a lock (tests / degraded boot), in which case the seed is
+     * skipped and the pre-existing behaviour is preserved.
+     */
+    todayWriteLock: TodayWriteLockManager | undefined;
     writeTracker: AgentWriteTracker | undefined;
     /**
      * Returns the dispatcher's currently-configured "services" the
@@ -271,6 +312,7 @@ export declare class ScheduledTaskRunner {
     private readonly morningRoutine;
     private readonly fetchWindowRunner;
     private readonly roadmapWriteLock;
+    private readonly todayWriteLock;
     private readonly writeTracker;
     private readonly getConfiguredServices;
     private readonly getActiveMailAccounts;
@@ -440,6 +482,67 @@ export declare class ScheduledTaskRunner {
      *     the journal line is the defensive trace.
      */
     private runWeeklyInterestsReflectionPreHook;
+    /**
+     * 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.
+     */
+    private prepareFeedbackWorksheet;
+    /**
+     * 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.
+     */
+    private prepareSelfTuningBlocks;
+    /**
+     * 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.
+     */
+    private prepareRegeneralizationWorksheet;
     /**
      * Append a single bullet under `## Weekly interests reflection`
      * inside `context/journal/agent.md`, creating the section (and the