@aitne/daemon 0.1.7 → 0.1.9

package/dist/core/bang-commands/registry.d.ts

@@ -9,6 +9,7 @@ import type Database from "better-sqlite3";
 import type { Event, MessageEvent } from "@aitne/shared";
 import type { AgentConfig } from "../../config.js";
 import type { IAuditLogger } from "../dispatcher.js";
+import type { AgentWriteTracker } from "../../safety/agent-write-tracker.js";
 import { type UserBangCommand } from "./user-commands.js";
 export interface BangCommandContext {
     event: MessageEvent;
@@ -22,9 +23,45 @@ export interface BangCommandContext {
      */
     notify(text: string): Promise<void>;
     audit: IAuditLogger;
+    /**
+     * Optional commit-attribution tracker (C1). `!compile` forwards this
+     * to `runGitPreCompile` so the snapshot SHA is registered before
+     * `GitWatcher`'s next poll cycle observes it — closing the
+     * daemon-side self-trigger loop in wiki pre-compile.
+     *
+     * Production callers (dispatcher-message-handler) ALWAYS supply one
+     * — the optional shape here is purely so existing test fixtures that
+     * never exercise `!compile` don't have to construct a tracker.
+     * Forwarding into commands-wiki.ts goes through this field, and
+     * `runGitPreCompile`'s `writeTracker` is itself optional, so
+     * missing → no attribution mark (the pre-fix behaviour, still safe).
+     */
+    writeTracker?: AgentWriteTracker;
     registry: BangCommandRegistry;
+    /**
+     * Close the active DM session for this event's routing tuple. Returns
+     * `{ closedId }` so the caller can distinguish "closed a session" from
+     * "no active session existed" without coupling the command to the
+     * session manager. Implementations record the inbound `!close` turn
+     * before closing so the close action shows up in chat history.
+     *
+     * Optional so that bang-command unit tests can construct minimal
+     * contexts; production wiring always supplies it.
+     */
+    closeActiveDmSession?: () => Promise<{
+        closedId: number | null;
+    }>;
     enqueueUserBangCommand?: (command: UserBangCommand, event: MessageEvent) => Promise<void>;
     enqueueWikiEvent?: (event: Event) => Promise<void>;
+    /**
+     * BROWSER_HISTORY_INTEGRATION_PLAN P3 — wire-through for the
+     * `!research accept` / `!research wiki` paths. The bang handler
+     * constructs an Event via `createResearchCommandEvent` and the
+     * dispatcher-message-handler binds this callback to
+     * `await this.eventBus.put(event)`. Optional so unit-test fixtures
+     * without an EventBus can still exercise list / show / mute / rename.
+     */
+    enqueueBrowserResearchEvent?: (event: Event) => Promise<void>;
     /**
      * Approval handoff for `!compile full` when the cost estimate exceeds
      * the per-workspace threshold (WIKI_BUILDER_DESIGN.md §5.5). Inserts
@@ -50,6 +87,19 @@ export interface BangCommand {
     describe: string;
     /** Longer dashboard-facing details. */
     details?: readonly string[];
+    /**
+     * When true, the command runs normally while the agent is paused
+     * (`!stop` state). Reserve for commands that do not enqueue LLM work
+     * — pure DB reads, audit lookups, and state toggles (`!start`,
+     * `!cost`, `!report`, `!help`, `!close`, `!wiki` status). Commands
+     * that dispatch an autonomous session (`!compile`, `!ingest`,
+     * `!ask`, `!lint`, `!trace`, `!connect`) must leave this false so
+     * the pause gate can block them with an informative reply.
+     *
+     * Defaults to false. The pause gate falls back to a generic "Agent
+     * is paused" notice on any command that opts out.
+     */
+    runsWhilePaused?: boolean;
     handler: (ctx: BangCommandContext) => Promise<void>;
 }
 export declare class BangArgError extends Error {
@@ -64,6 +114,8 @@ export interface BangPrefixCommand {
     describe: string;
     /** Longer dashboard-facing details. */
     details?: readonly string[];
+    /** See {@link BangCommand.runsWhilePaused}. Defaults to false. */
+    runsWhilePaused?: boolean;
     parseArgs?: (rest: string, ctx: BangCommandContext) => unknown | Promise<unknown>;
     handler: (ctx: BangCommandContext, args: unknown) => Promise<void>;
 }
@@ -91,6 +143,13 @@ export declare function getBangCommandName(cmd: RegisteredBangCommand): string;
  * DM (bang or non-bang) while the agent is paused.
  */
 export declare function buildPausedNotice(): string;
+/**
+ * Reply text for a recognised command that opts out of pause execution
+ * (LLM-dispatching commands). Tells the user the command was understood
+ * but is gated by the pause state, so the next action is `!start` — not
+ * "you typed the wrong thing".
+ */
+export declare function buildPausedCommandUnavailableNotice(commandName: string): string;
 /**
  * Reply for an unrecognised bang while NOT paused. Lists up to 6 known
  * commands so the user can recover without checking the docs.
@@ -112,4 +171,3 @@ export declare function makeNotify(rawSend: (text: string) => Promise<void>, fal
 export declare function tryHandle(registry: BangCommandRegistry, ctx: Omit<BangCommandContext, "notify" | "registry"> & {
     rawSend: (text: string) => Promise<void>;
 }): Promise<boolean>;
-//# sourceMappingURL=registry.d.ts.map

package/dist/core/bang-commands/registry.js

@@ -1,4 +1,4 @@
-import { isDocsQAMessage } from "@aitne/shared";
+import { RUNTIME_AVAILABLE_BACKEND_IDS, isDocsQAMessage } from "@aitne/shared";
 import { isUserPaused } from "../../db/runtime-state.js";
 import { CUSTOM_BANG_COMMAND_SOURCE, getEnabledUserBangCommandByCommand, listUserBangCommands, } from "./user-commands.js";
 import { ensureSystemMarker, buildSystemMarker, truncateForMobile, } from "./format-utils.js";
@@ -19,10 +19,23 @@ export class BangCommandRegistry {
         if (!key.startsWith("!")) {
             throw new Error(`BangCommand key must start with "!": ${key}`);
         }
+        // Hard-fail on duplicate registration. Silently overwriting hid
+        // accidental double-registers (e.g. `!stop` defined in two
+        // `commands-*.ts` files) behind a clean test pass; the failure only
+        // surfaced in production as "the command I edited doesn't do anything"
+        // because the loser's handler never ran. Throwing here surfaces the
+        // collision the first time `createDefaultBangCommandRegistry()` is
+        // built at boot.
         if ("name" in cmd) {
+            if (this.byName.has(cmd.name)) {
+                throw new Error(`BangCommand "${cmd.name}" is already registered`);
+            }
             this.byName.set(cmd.name, cmd);
         }
         else {
+            if (this.prefixes.some((existing) => existing.prefix === cmd.prefix)) {
+                throw new Error(`BangCommand prefix "${cmd.prefix}" is already registered`);
+            }
             this.prefixes.push(cmd);
             this.prefixes.sort((a, b) => b.prefix.length - a.prefix.length);
         }
@@ -61,7 +74,19 @@ export function normalizeBangCommandText(text) {
     return normalizeBangCommandRestText(text).toLowerCase();
 }
 export function normalizeBangCommandRestText(text) {
-    return text.trim().replace(/[ \t\f\v]+/g, " ");
+    // Map the fullwidth bang U+FF01 — produced by CJK input methods when the
+    // user is in a wide-character mode — to ASCII U+0021 so the registry
+    // resolves them identically. Without this a CJK-keyboard user types the
+    // wide bang, the prefix check below misses, and the message lands in the
+    // unknown-command path (or the pause notice while paused). The U+3000
+    // ideographic space is also folded into the inner-whitespace collapse so
+    // mixed-IME spacing like `!{U+3000}stop` survives too. Uses Unicode
+    // escapes (not literal CJK chars) per the project's English-only source
+    // policy in CLAUDE.md.
+    return text
+        .trim()
+        .replace(/\uFF01/g, "!")
+        .replace(/[ \t\f\v\u3000]+/g, " ");
 }
 export function getBangCommandName(cmd) {
     return "name" in cmd ? cmd.name : cmd.prefix;
@@ -77,10 +102,24 @@ export function buildPausedNotice() {
         "",
         "Available commands:",
         "- !start to resume",
-        "- !cost (or !cost claude / codex / gemini)",
+        `- !cost (or !cost ${RUNTIME_AVAILABLE_BACKEND_IDS.join(" / ")})`,
         "- !report",
     ].join("\n");
 }
+/**
+ * Reply text for a recognised command that opts out of pause execution
+ * (LLM-dispatching commands). Tells the user the command was understood
+ * but is gated by the pause state, so the next action is `!start` — not
+ * "you typed the wrong thing".
+ */
+export function buildPausedCommandUnavailableNotice(commandName) {
+    return [
+        buildSystemMarker(commandName),
+        `\`${commandName}\` is unavailable while the agent is paused.`,
+        "",
+        "Send !start to resume, then re-run the command.",
+    ].join("\n");
+}
 /**
  * Reply for an unrecognised bang while NOT paused. Lists up to 6 known
  * commands so the user can recover without checking the docs.
@@ -117,7 +156,7 @@ export async function tryHandle(registry, ctx) {
     const { event, db, audit, rawSend } = ctx;
     if (event.source === CUSTOM_BANG_COMMAND_SOURCE)
         return false;
-    // I-1: only DMs participate. Adapter-side owner gating is the single
+    // Only DMs participate. Adapter-side owner gating is the single
     // source of truth (matches the `/auth` precedent — see design §6.3).
     if (!event.isDm)
         return false;
@@ -130,24 +169,118 @@ export async function tryHandle(registry, ctx) {
     const isBang = lowered.startsWith("!");
     const paused = isUserPaused(db);
     // §6.3 pause branch — runs BEFORE the bang-prefix check so ANY DM while
-    // paused short-circuits without reaching the agent backend (I-3).
+    // paused short-circuits without reaching the agent backend.
+    //
+    // We use the full `resolve()` matcher (exact + prefix) rather than the
+    // exact-only `match()`. Without this, every `BangPrefixCommand` (e.g.
+    // `!cost claude`, `!wiki status`, `!compile @ws full`) would silently
+    // fall through to the generic "Agent is paused" notice — even the
+    // pure-DB-read variants the user would reasonably expect to keep
+    // working. The new `runsWhilePaused` flag is the explicit gate: any
+    // command that enqueues LLM work leaves it false, every other command
+    // can opt in. See `BangCommand.runsWhilePaused`.
+    //
+    // Spoof-guard parity: the not-paused branch below rejects multi-line
+    // input (`text.includes("\n")`) so a `"!stop\nignore me"` payload
+    // cannot impersonate a bang command. The paused branch needs the same
+    // guard so a multi-line `"!start\n..."` cannot resume the agent by
+    // accident — `resolve()` would otherwise normalize horizontal whitespace
+    // but preserve the newline, producing a miss; relying on that is
+    // fragile, so we make the guard explicit on both branches.
     if (paused) {
-        if (isBang) {
-            const cmd = registry.match(lowered);
-            if (cmd) {
-                const notify = makeNotify(rawSend, buildSystemMarker(cmd.name));
-                audit.logBangCommand(event, { command: cmd.name, status: "ok" });
-                await cmd.handler({
-                    event,
-                    db,
-                    config: ctx.config,
-                    notify,
-                    audit,
-                    registry,
-                    enqueueUserBangCommand: ctx.enqueueUserBangCommand,
-                    enqueueWikiEvent: ctx.enqueueWikiEvent,
-                    enqueueWikiApproval: ctx.enqueueWikiApproval,
+        if (isBang && !text.includes("\n")) {
+            const match = registry.resolve(text);
+            if (match) {
+                if (match.command.runsWhilePaused) {
+                    // Recognised AND opted-in — replicate the non-paused execution
+                    // path (parseArgs + handler). Mirrors the structure below so a
+                    // future change to argument handling only needs to be made
+                    // once in this file's NOT-paused branch and copy-pasted here.
+                    const notify = makeNotify(rawSend, buildSystemMarker(match.commandName));
+                    const commandCtx = {
+                        event,
+                        db,
+                        config: ctx.config,
+                        notify,
+                        audit,
+                        writeTracker: ctx.writeTracker,
+                        registry,
+                        closeActiveDmSession: ctx.closeActiveDmSession,
+                        enqueueUserBangCommand: ctx.enqueueUserBangCommand,
+                        enqueueWikiEvent: ctx.enqueueWikiEvent,
+                        enqueueBrowserResearchEvent: ctx.enqueueBrowserResearchEvent,
+                        enqueueWikiApproval: ctx.enqueueWikiApproval,
+                    };
+                    // Stamp the wall-clock the handler started so we can back-fill
+                    // runMs into the audit row on success/failure.
+                    const startedAtMs = Date.now();
+                    try {
+                        const args = match.kind === "prefix" && "prefix" in match.command
+                            ? await match.command.parseArgs?.(match.rest, commandCtx)
+                            : undefined;
+                        audit.logBangCommand(event, {
+                            command: match.commandName,
+                            status: "ok",
+                            kind: match.kind,
+                            args: match.rest,
+                            runMs: Date.now() - startedAtMs,
+                        });
+                        if ("name" in match.command) {
+                            await match.command.handler(commandCtx);
+                        }
+                        else {
+                            await match.command.handler(commandCtx, args);
+                        }
+                    }
+                    catch (err) {
+                        if (!(err instanceof BangArgError))
+                            throw err;
+                        audit.logBangCommand(event, {
+                            command: match.commandName,
+                            status: "invalid_args",
+                            message: err.message,
+                            kind: match.kind,
+                            args: match.rest,
+                            runMs: Date.now() - startedAtMs,
+                        });
+                        await notify(err.message);
+                    }
+                    return true;
+                }
+                // Recognised but the command enqueues LLM work — refuse with a
+                // command-aware notice so the user knows their input was
+                // understood (and what to do next), instead of getting the
+                // generic decline that reads as if the command was unknown.
+                audit.logBangCommand(event, {
+                    command: match.commandName,
+                    status: "paused_blocked",
+                    kind: match.kind,
+                    args: match.rest,
+                });
+                const notify = makeNotify(rawSend, buildSystemMarker(match.commandName));
+                await notify(buildPausedCommandUnavailableNotice(match.commandName));
+                return true;
+            }
+            // User-defined bang commands ARE LLM dispatch by construction
+            // (`enqueueUserBangCommand` puts an event the dispatcher then
+            // runs through `executeCustomBangCommand`). Mirror the built-in
+            // LLM-command refusal so the user sees one consistent shape —
+            // "command recognised; unavailable while paused; send !start to
+            // resume" — regardless of whether the command came from the
+            // built-in registry or `user_bang_commands`. Without this branch,
+            // `!digest` (user) and `!compile` (built-in) would emit visibly
+            // different refusal messages, with the user-defined case looking
+            // like an unknown command.
+            const userCommandPaused = getEnabledUserBangCommandByCommand(db, lowered);
+            if (userCommandPaused) {
+                audit.logBangCommand(event, {
+                    command: userCommandPaused.command,
+                    status: "paused_blocked",
+                    kind: "user",
+                    userCommandId: userCommandPaused.id,
                 });
+                const notify = makeNotify(rawSend, buildSystemMarker(userCommandPaused.command));
+                await notify(buildPausedCommandUnavailableNotice(userCommandPaused.command));
                 return true;
             }
             // Unknown bang while paused — falls through to the pause notice
@@ -167,7 +300,7 @@ export async function tryHandle(registry, ctx) {
     if (!isBang)
         return false;
     // §7 spoof guard: a multi-line message that happens to start with `!stop`
-    // is "treated as agent input" — bang-command parsing is exact-match (I-2),
+    // is "treated as agent input" — bang-command parsing is exact-match,
     // so anything spanning newlines never produces a registry hit and must
     // fall through to the agent path instead of emitting the unknown-bang
     // help. Mirrors the intent of "Avoids spoofing by users embedding
@@ -183,16 +316,33 @@ export async function tryHandle(registry, ctx) {
             config: ctx.config,
             notify,
             audit,
+            writeTracker: ctx.writeTracker,
             registry,
+            closeActiveDmSession: ctx.closeActiveDmSession,
             enqueueUserBangCommand: ctx.enqueueUserBangCommand,
             enqueueWikiEvent: ctx.enqueueWikiEvent,
+            // BROWSER_HISTORY_INTEGRATION_PLAN P3 — `!research accept|wiki` rely
+            // on this wire. The paused branch above forwards it too but never
+            // executes the LLM-dispatching variant (`!research` isn't
+            // `runsWhilePaused`); production runs land here, so omitting the
+            // forward turned every accept/wiki bang into "dispatch not wired"
+            // even when the dispatcher-message-handler caller had supplied it.
+            enqueueBrowserResearchEvent: ctx.enqueueBrowserResearchEvent,
             enqueueWikiApproval: ctx.enqueueWikiApproval,
         };
+        // Stamp wall-clock start so audit rows carry runMs.
+        const startedAtMs = Date.now();
         try {
             const args = match.kind === "prefix" && "prefix" in match.command
                 ? await match.command.parseArgs?.(match.rest, commandCtx)
                 : undefined;
-            audit.logBangCommand(event, { command: match.commandName, status: "ok" });
+            audit.logBangCommand(event, {
+                command: match.commandName,
+                status: "ok",
+                kind: match.kind,
+                args: match.rest,
+                runMs: Date.now() - startedAtMs,
+            });
             if ("name" in match.command) {
                 await match.command.handler(commandCtx);
             }
@@ -207,6 +357,9 @@ export async function tryHandle(registry, ctx) {
                 command: match.commandName,
                 status: "invalid_args",
                 message: err.message,
+                kind: match.kind,
+                args: match.rest,
+                runMs: Date.now() - startedAtMs,
             });
             await notify(err.message);
         }
@@ -241,4 +394,3 @@ export async function tryHandle(registry, ctx) {
     ]));
     return true;
 }
-//# sourceMappingURL=registry.js.map

package/dist/core/bang-commands/user-commands.d.ts

@@ -83,4 +83,3 @@ export declare function serializeEnabledSkills(skills: readonly string[] | null
  * (it falls back to the default skill set).
  */
 export declare function parseEnabledSkills(raw: string | null): string[] | null;
-//# sourceMappingURL=user-commands.d.ts.map

package/dist/core/bang-commands/user-commands.js

@@ -209,4 +209,3 @@ function normalizeInstructionMd(value) {
     const trimmed = value.trim();
     return trimmed.length === 0 ? null : trimmed;
 }
-//# sourceMappingURL=user-commands.js.map

package/dist/core/browser-history/pre-morning-digest-job.d.ts

@@ -0,0 +1,79 @@
+import type Database from "better-sqlite3";
+import { type DigestBoundary } from "../../services/browser-history/pipeline/pre-morning-digest.js";
+import { type PreMorningDigest } from "@aitne/shared";
+/**
+ * Daemon-side wrapper around the pure digest builder. Three roles:
+ *
+ *  1. `runPreMorningDigestJob` — called by the scheduler at
+ *     `dayBoundaryHour − 1` (BROWSER_HISTORY_INTEGRATION_PLAN §5.F2
+ *     Stage 1). Builds the digest for the agent-day that's just about
+ *     to end and writes `<contextDir>/browser/yesterday-<date>.md`
+ *     plus a JSON sidecar (`yesterday-<date>.json`) so the API route
+ *     can return the exact same payload the journal sees, without
+ *     parsing markdown back into Zod-validated JSON.
+ *
+ *  2. `readPreMorningDigestJsonForDate` — used by the API route. Reads
+ *     the JSON sidecar when present; returns null otherwise. The route
+ *     then falls back to building fresh from the DB.
+ *
+ *  3. `digestDate` / `digestPaths` — small helpers exported for tests
+ *     and the cron call site to share a single source of truth for the
+ *     filename layout.
+ *
+ * The job is intentionally fire-and-forget: a build / write failure
+ * logs loudly and never re-throws. The morning journal's task-flow
+ * tolerates a missing digest by calling
+ * `GET /api/browser-history/pre-morning-digest/{date}` as the
+ * documented fallback (§5.F2 Stage 2). Either path satisfies the
+ * journal's contract; the file path is the primary one because it
+ * pre-warms the morning context window without a network hop.
+ */
+export interface PreMorningDigestPaths {
+    /** Absolute path to the markdown file the journal reads. */
+    markdownPath: string;
+    /** Absolute path to the parallel JSON sidecar the API serves. */
+    jsonPath: string;
+    /**
+     * The `<path>` portion of `PUT /api/context/<path>.md` — useful for
+     * task-flow strings and log lines that need a stable agent-facing
+     * reference, independent of the on-disk `contextDir`.
+     */
+    contextRelative: string;
+}
+export declare function digestPaths(contextDir: string, dateStr: string): PreMorningDigestPaths;
+export interface RunPreMorningDigestJobArgs {
+    readonly db: Database.Database;
+    readonly contextDir: string;
+    readonly boundary: DigestBoundary;
+    /** Override `Date.now()` for tests and the API on-demand path. */
+    readonly nowMs?: number;
+}
+export interface RunPreMorningDigestJobResult {
+    readonly date: string;
+    readonly paths: PreMorningDigestPaths;
+    readonly digest: PreMorningDigest;
+}
+/**
+ * Build + persist the digest for the agent-day "now" is inside of.
+ * Returns the typed digest so callers (the API route's
+ * rebuild-on-demand path, tests) can use the same code shape as the
+ * cron call site.
+ */
+export declare function runPreMorningDigestJob(args: RunPreMorningDigestJobArgs): RunPreMorningDigestJobResult;
+/**
+ * Read the JSON sidecar for the given agent-day, Zod-validate it, and
+ * return the typed digest. Returns null when the file is missing or
+ * the bytes do not parse — the API caller can then rebuild fresh.
+ *
+ * Validation matters here: the journal Stage B task-flow trusts the
+ * file's schema invariants (no raw URLs / titles). Returning unvetted
+ * JSON would let a corrupt sidecar bypass that boundary.
+ */
+export declare function readPreMorningDigestJsonForDate(contextDir: string, dateStr: string): PreMorningDigest | null;
+/**
+ * Wrapper safe to register as a fire-and-forget cron callback. Catches
+ * every error so a transient SQL failure or filesystem hiccup cannot
+ * crash the scheduler's cron tick. Returns the result for callers that
+ * want to inspect outcomes (tests / dashboards / future audit hooks).
+ */
+export declare function safeRunPreMorningDigestJob(args: RunPreMorningDigestJobArgs): RunPreMorningDigestJobResult | null;

package/dist/core/browser-history/pre-morning-digest-job.js

@@ -0,0 +1,89 @@
+import { resolve } from "node:path";
+import { existsSync, readFileSync } from "node:fs";
+import { writeFileAtomically } from "../atomic-write.js";
+import { buildPreMorningDigest, digestDateForNow, preMorningDigestRelativePath, renderPreMorningDigestMarkdown, } from "../../services/browser-history/pipeline/pre-morning-digest.js";
+import { preMorningDigestSchema, } from "@aitne/shared";
+import { createLogger } from "../../logging.js";
+const logger = createLogger("browser-history-pre-morning-digest");
+export function digestPaths(contextDir, dateStr) {
+    const contextRelative = preMorningDigestRelativePath(dateStr);
+    const markdownPath = resolve(contextDir, contextRelative);
+    const jsonPath = markdownPath.replace(/\.md$/, ".json");
+    return { markdownPath, jsonPath, contextRelative };
+}
+/**
+ * Build + persist the digest for the agent-day "now" is inside of.
+ * Returns the typed digest so callers (the API route's
+ * rebuild-on-demand path, tests) can use the same code shape as the
+ * cron call site.
+ */
+export function runPreMorningDigestJob(args) {
+    const { db, contextDir, boundary } = args;
+    const nowMs = args.nowMs ?? Date.now();
+    const date = digestDateForNow(boundary, nowMs);
+    const digest = buildPreMorningDigest({
+        db,
+        date,
+        boundary,
+        options: { nowMs },
+    });
+    const paths = digestPaths(contextDir, date);
+    const markdown = renderPreMorningDigestMarkdown(digest);
+    // JSON sidecar first — it is the API's source of truth. Writing the
+    // markdown after means a partial-failure leaves the JSON missing if
+    // the markdown write fails, but never the other way around (which
+    // would let the journal read stale prose with no API parity).
+    writeFileAtomically(paths.jsonPath, JSON.stringify(digest, null, 2) + "\n");
+    writeFileAtomically(paths.markdownPath, markdown);
+    return { date, paths, digest };
+}
+/**
+ * Read the JSON sidecar for the given agent-day, Zod-validate it, and
+ * return the typed digest. Returns null when the file is missing or
+ * the bytes do not parse — the API caller can then rebuild fresh.
+ *
+ * Validation matters here: the journal Stage B task-flow trusts the
+ * file's schema invariants (no raw URLs / titles). Returning unvetted
+ * JSON would let a corrupt sidecar bypass that boundary.
+ */
+export function readPreMorningDigestJsonForDate(contextDir, dateStr) {
+    const { jsonPath } = digestPaths(contextDir, dateStr);
+    if (!existsSync(jsonPath))
+        return null;
+    try {
+        const raw = readFileSync(jsonPath, "utf-8");
+        const parsed = preMorningDigestSchema.safeParse(JSON.parse(raw));
+        return parsed.success ? parsed.data : null;
+    }
+    catch (err) {
+        // A read / parse error is recoverable — caller rebuilds. We log so
+        // the operator can investigate, but do not throw upward into the
+        // request handler.
+        logger.warn({ err, jsonPath }, "Failed to read pre-morning digest JSON sidecar; caller will rebuild");
+        return null;
+    }
+}
+/**
+ * Wrapper safe to register as a fire-and-forget cron callback. Catches
+ * every error so a transient SQL failure or filesystem hiccup cannot
+ * crash the scheduler's cron tick. Returns the result for callers that
+ * want to inspect outcomes (tests / dashboards / future audit hooks).
+ */
+export function safeRunPreMorningDigestJob(args) {
+    try {
+        const result = runPreMorningDigestJob(args);
+        logger.info({
+            date: result.date,
+            clusters: result.digest.clusters.length,
+            shopping: result.digest.shopping.length,
+            reloads: result.digest.reloads.length,
+            pendingOffers: result.digest.pendingOffers.length,
+            newThresholds: result.digest.newThresholdsCount,
+        }, "Pre-morning digest written");
+        return result;
+    }
+    catch (err) {
+        logger.error({ err }, "Pre-morning digest job failed; the morning journal will fall back to the API endpoint");
+        return null;
+    }
+}

package/dist/core/browser-history/research-cluster-fanout.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Day-boundary fan-out helper — enumerates active research clusters
+ * with new meaningful activity in the last 24h and emits one
+ * `routine.research_cluster_update` event per cluster onto the
+ * EventBus. Called once per agent-day from the scheduler's day-boundary
+ * callback (see `bootstrap/index.ts`).
+ *
+ * BROWSER_HISTORY_INTEGRATION_PLAN §10.6 step 3.
+ *
+ * Pure orchestration — no LLM in this path. The fan-out is bounded by
+ * the `limit` parameter (default 25) so a backlog from a long outage
+ * cannot flood the event queue. Clusters that miss this cycle pick up
+ * on the next day-boundary fire; the next cycle's DB query naturally
+ * sees them as "still active with new activity since prior update".
+ */
+import type Database from "better-sqlite3";
+export interface EventBusLike {
+    put(event: import("@aitne/shared").Event): Promise<void>;
+}
+export declare const RESEARCH_CLUSTER_FANOUT_LOOKBACK_MS: number;
+export declare const RESEARCH_CLUSTER_FANOUT_LIMIT = 25;
+export interface FanoutResult {
+    enqueuedSlugs: string[];
+}
+/**
+ * Enumerate active clusters with new meaningful activity since the last
+ * day-boundary cycle and enqueue one `routine.research_cluster_update`
+ * event per cluster. Always returns the slugs it enqueued so the caller
+ * can log a structured summary.
+ *
+ * When `eventBus` is absent (early-boot path before EventBus wiring),
+ * the function returns an empty result without throwing — the next
+ * day-boundary tick re-evaluates and picks up the clusters once
+ * messaging is live.
+ */
+export declare function fanoutResearchClusterUpdates(db: Database.Database, eventBus: EventBusLike | null | undefined, options?: {
+    lookbackMs?: number;
+    limit?: number;
+    nowMs?: number;
+}): Promise<FanoutResult>;

package/dist/core/browser-history/research-cluster-fanout.js

@@ -0,0 +1,47 @@
+/**
+ * Day-boundary fan-out helper — enumerates active research clusters
+ * with new meaningful activity in the last 24h and emits one
+ * `routine.research_cluster_update` event per cluster onto the
+ * EventBus. Called once per agent-day from the scheduler's day-boundary
+ * callback (see `bootstrap/index.ts`).
+ *
+ * BROWSER_HISTORY_INTEGRATION_PLAN §10.6 step 3.
+ *
+ * Pure orchestration — no LLM in this path. The fan-out is bounded by
+ * the `limit` parameter (default 25) so a backlog from a long outage
+ * cannot flood the event queue. Clusters that miss this cycle pick up
+ * on the next day-boundary fire; the next cycle's DB query naturally
+ * sees them as "still active with new activity since prior update".
+ */
+import { listClustersNeedingUpdate } from "../../db/browser-history-store.js";
+import { createResearchCommandEvent } from "./research-events.js";
+export const RESEARCH_CLUSTER_FANOUT_LOOKBACK_MS = 24 * 60 * 60 * 1000;
+export const RESEARCH_CLUSTER_FANOUT_LIMIT = 25;
+/**
+ * Enumerate active clusters with new meaningful activity since the last
+ * day-boundary cycle and enqueue one `routine.research_cluster_update`
+ * event per cluster. Always returns the slugs it enqueued so the caller
+ * can log a structured summary.
+ *
+ * When `eventBus` is absent (early-boot path before EventBus wiring),
+ * the function returns an empty result without throwing — the next
+ * day-boundary tick re-evaluates and picks up the clusters once
+ * messaging is live.
+ */
+export async function fanoutResearchClusterUpdates(db, eventBus, options = {}) {
+    if (!eventBus)
+        return { enqueuedSlugs: [] };
+    const lookbackMs = options.lookbackMs ?? RESEARCH_CLUSTER_FANOUT_LOOKBACK_MS;
+    const limit = options.limit ?? RESEARCH_CLUSTER_FANOUT_LIMIT;
+    const nowMs = options.nowMs ?? Date.now();
+    const rows = listClustersNeedingUpdate(db, lookbackMs, nowMs, limit);
+    const enqueuedSlugs = [];
+    for (const row of rows) {
+        await eventBus.put(createResearchCommandEvent({
+            processKey: "routine.research_cluster_update",
+            slug: row.slug,
+        }));
+        enqueuedSlugs.push(row.slug);
+    }
+    return { enqueuedSlugs };
+}