@aitne/daemon 0.1.3 → 0.1.4

package/dist/core/routine-fetch-window-runner.js

@@ -0,0 +1,661 @@
+/**
+ * `RoutineFetchWindowRunner` — Phase 4 / D1 pre-pass orchestration.
+ *
+ * ROUTINE_DATA_ACQUISITION_DESIGN.md §6.1.1 / Phase 4 D1 — every routine
+ * dispatcher (morning_routine, today_refresh, hourly_check, evening /
+ * weekly / monthly review) calls this runner immediately before
+ * dispatching the parent session. The runner:
+ *
+ *  1. Reads the per-routine plan from `ROUTINE_WINDOWS` and the current
+ *     integration state, fans out per-account where applicable, resolves
+ *     each row's predicate (`direct` / `delegated-same` / `delegated-cross`
+ *     / `native` / skip) via `buildAcquisitionPlan`, and renders an
+ *     `<acquisition-plan>` block.
+ *  2. Synthesises a `routine.fetch_window` RoutineEvent, embeds the plan
+ *     block in `event.data.acquisitionPlanBlock` so ContextBuilder folds
+ *     it into the fetcher's prompt context, and routes the event
+ *     synchronously through the standard `IAgentRouter.execute` /
+ *     `PromptAssembler.assemble` pipeline. The session inherits the
+ *     `routine.fetch_window` ProcessKey binding (lite tier per F1 / §6.9)
+ *     and the dedicated `routine-fetch-window` agent profile.
+ *  3. Parses the agent's single-JSON-line output into a structured
+ *     `FetchReport`, renders a `<fetch_report>` block, and logs one
+ *     `agent_actions` row via the dispatcher's audit logger.
+ *  4. Returns the rendered block + parsed report so the caller can graft
+ *     the block into the **parent** routine event's
+ *     `event.data.fetchReportBlock`. ContextBuilder injects that block
+ *     verbatim into the parent session's prompt (mirrors the
+ *     `<gate_decision>` pattern used by hourly_check Stage 3).
+ *
+ * Failure-mode contract (Phase 4 D1 + design §11 R5 / OQ4):
+ *
+ *  - **No applicable rows** (routine has no windows in `ROUTINE_WINDOWS`,
+ *    every integration is disabled, every account list is empty) — the
+ *    runner returns an empty `<fetch_report>` with `status="skipped"` and
+ *    `fetched=posted=duplicates=0`. The parent routine still runs; the
+ *    block is informational only.
+ *  - **Pre-pass session errors** (binding resolve fails, agent throws,
+ *    JSON parse fails) — the runner logs the failure and returns a
+ *    `<fetch_report status="failed">` with one `pre-pass-failed` error.
+ *    Pre-pass cost gains are forfeit for this tick; the parent routine
+ *    continues with whatever observations the rest of the plan produced.
+ *    Throwing here would otherwise propagate up and abort the parent
+ *    routine — the opposite of P3 ("Lite for Fetch, Medium for Decide").
+ *  - **Partial success** — the report's `errors` array carries per-row
+ *    failures (`no-surface`, `fetch-failed`, `budget-exhausted`). The
+ *    block surfaces them so the parent prompt can decide whether to
+ *    treat its observations view as complete.
+ */
+import { EventPriority, INTEGRATION_KEYS, createEvent, getAgentDayDateStr, getIntegrationDescriptor, isRoutineEvent, } from "@aitne/shared";
+import { readIntegrations } from "../db/integrations-store.js";
+import { ROUTINE_WINDOWS, routineHasWindows, } from "./routine-windows.js";
+import { buildAcquisitionPlan, buildAcquisitionTimestamps, } from "./routine-acquisition-plan.js";
+import { createLogger } from "../logging.js";
+const logger = createLogger("routine-fetch-window-runner");
+// ── Module helpers ────────────────────────────────────────────────────────
+/** The ProcessKey + event type the pre-pass session always runs under. */
+const FETCH_WINDOW_PROCESS_KEY = "routine.fetch_window";
+const FETCH_WINDOW_EVENT_TYPE = "routine.fetch_window";
+/**
+ * Daemon REST surfaces the pre-pass partials may target. Curl prefixes
+ * are constructed with the configured `apiPort` at dispatch time so a
+ * non-default port survives the clamp. Everything OTHER than these
+ * prefixes is denied — the pre-pass cannot reach `/api/notify`,
+ * `/api/context/*`, `/api/agent/*`, etc., even though Bash(curl *) is
+ * the project default. This is the daemon-side enforcement that backs
+ * the agent profile's "no notify, no context writes" guardrails (P3:
+ * Lite for Fetch — the pre-pass has zero business making decisions).
+ *
+ * `jq *` stays allowed because direct-mode partials pipe curl output
+ * through jq for compact projection before posting to /api/observations.
+ *
+ * The clamp is Claude-only — Codex/Gemini have no per-spawn allowedTools
+ * surface today (CLAUDE.md acknowledges the gap). The
+ * `process_backend_config` envelope (`max_turns=20`, `max_budget_usd=0.20`)
+ * remains the floor on those backends.
+ */
+function buildPrePassDaemonRestPatterns(apiPort) {
+    const root = `http://localhost:${apiPort}/api`;
+    return [
+        // Observations — the only write surface the pre-pass touches.
+        // Catches both POST /api/observations and GET /api/observations*.
+        `Bash(curl ${root}/observations*)`,
+        // Direct-mode mail / calendar / notion reads.
+        `Bash(curl ${root}/mail/*)`,
+        `Bash(curl ${root}/calendar/*)`,
+        `Bash(curl ${root}/notion/*)`,
+        // delegated-cross proxy. Only Gmail / Google Calendar / Notion
+        // expose this; user-managed Outlook has no proxy and the runner
+        // collapses cross-backend bindings to delegated-same per
+        // routine-acquisition-plan.ts:resolveFetchMode.
+        `Bash(curl ${root}/integrations/*)`,
+        // Compact-projection helper used by the partials.
+        "Bash(jq *)",
+    ];
+}
+/**
+ * Project the active integrations into the per-backend MCP tool names
+ * the pre-pass needs. Includes both delegated-same bindings (where the
+ * connector is registered through the daemon's Claude SDK) AND native
+ * bindings (where the connector is loaded by the user but the same
+ * descriptor declares which capability tool names exist). User-managed
+ * descriptors (`backendConnectors[backend]` undefined for Outlook) are
+ * skipped — those rows surface as `no-surface` errors per the partial
+ * contract, which is the documented behaviour.
+ *
+ * Cross-backend delegated bindings contribute zero MCP tools because
+ * the partial reaches them through `/api/integrations/<key>/exec`, not
+ * via the session backend's MCP namespace.
+ */
+function collectIntegrationToolsForBackend(integrations, backend) {
+    const out = new Set();
+    for (const key of INTEGRATION_KEYS) {
+        const state = integrations[key];
+        if (!state)
+            continue;
+        let active = false;
+        if (state.mode === "delegated" && state.delegatedBackend === backend) {
+            active = true;
+        }
+        else if (state.mode === "native" && state.nativeBackend === backend) {
+            active = true;
+        }
+        if (!active)
+            continue;
+        const connector = getIntegrationDescriptor(key).backendConnectors[backend];
+        if (!connector)
+            continue; // user-managed (no descriptor connector for this backend)
+        for (const toolNames of Object.values(connector.capabilityTools)) {
+            for (const toolName of toolNames) {
+                out.add(connector.toolNamespace + toolName);
+            }
+        }
+    }
+    return Array.from(out);
+}
+/**
+ * Compose the per-execute `allowedToolsOverride` for the pre-pass. The
+ * override REPLACES the SDK's default allowlist (no union per
+ * claude-code-core.ts:437) so the list must be exhaustive for every
+ * surface the partials use under any (integration, mode) cell. Mode
+ * coverage:
+ *
+ *  - `direct`: daemon REST → curl prefix.
+ *  - `delegated-same`: session backend MCP → integration tool name.
+ *  - `delegated-cross`: daemon delegation proxy → curl prefix
+ *    (`/api/integrations/<key>/exec`).
+ *  - `native` (descriptor-bound): session backend MCP → integration
+ *    tool name.
+ *  - `native` (user-managed) / no-surface: nothing in the override —
+ *    the partial records `no-surface` and the runner's report carries
+ *    the gap forward to the parent routine.
+ *
+ * Exported for unit testing — the runner consumes it via
+ * `composePrePassAllowedTools` at dispatch time.
+ */
+export function composePrePassAllowedTools(apiPort, integrations, sessionBackend) {
+    return [
+        ...buildPrePassDaemonRestPatterns(apiPort),
+        ...collectIntegrationToolsForBackend(integrations, sessionBackend),
+    ];
+}
+/**
+ * Map a `MailAccount.kind` onto the integration key the registry uses
+ * for routing. Today: `gmail` → `gmail`, `outlook` → `outlook_mail`.
+ * Yahoo / iCloud / IMAP accounts are not tied to a routed integration
+ * and therefore do not participate in the pre-pass fan-out today.
+ */
+function mailAccountIntegrationKey(account) {
+    switch (account.kind) {
+        case "gmail":
+            return "gmail";
+        case "outlook":
+            return "outlook_mail";
+        default:
+            return null;
+    }
+}
+/**
+ * Derive the canonical `RoutineWindowKey` from a routine event. The
+ * caller's intent is conveyed by `event.type` (always `routine.<name>`),
+ * with `RoutineEvent.routine` carrying the same suffix without the
+ * `routine.` prefix. Returns null for routines outside the catalog so
+ * the caller can short-circuit before touching plan assembly.
+ */
+export function routineWindowKeyFromEvent(event) {
+    if (!isRoutineEvent(event))
+        return null;
+    const candidate = `routine.${event.routine}`;
+    return (ROUTINE_WINDOWS[candidate] !== undefined
+        ? candidate
+        : null);
+}
+/**
+ * Walk `text` and return every balanced `{...}` slice (top-level objects
+ * only; nested braces are honoured). Strings are tracked so brace
+ * characters inside `"..."` literals don't unbalance the scan. Used by
+ * `parseFetchWindowOutput` to pick the LAST top-level object on stdout —
+ * agents occasionally emit a think-aloud line carrying a JSON snippet
+ * before the verdict, and the fetcher's contract is "the last
+ * top-level JSON object wins."
+ *
+ * Exported for direct unit testing; the runner consumes it via
+ * `parseFetchWindowOutput`.
+ */
+export function extractBalancedJsonObjects(text) {
+    const out = [];
+    let depth = 0;
+    let start = -1;
+    let inString = false;
+    let escape = false;
+    for (let i = 0; i < text.length; i++) {
+        const ch = text[i];
+        if (inString) {
+            if (escape) {
+                escape = false;
+            }
+            else if (ch === "\\") {
+                escape = true;
+            }
+            else if (ch === '"') {
+                inString = false;
+            }
+            continue;
+        }
+        if (ch === '"') {
+            inString = true;
+            continue;
+        }
+        if (ch === "{") {
+            if (depth === 0)
+                start = i;
+            depth++;
+        }
+        else if (ch === "}") {
+            if (depth > 0) {
+                depth--;
+                if (depth === 0 && start >= 0) {
+                    out.push(text.slice(start, i + 1));
+                    start = -1;
+                }
+            }
+        }
+    }
+    return out;
+}
+/** Strict-JSON parse of the fetcher's single-line output. */
+export function parseFetchWindowOutput(output) {
+    const trimmed = (output ?? "").trim();
+    if (!trimmed)
+        return { parseError: "empty-output" };
+    // Tolerate code fences without making them mandatory — mirrors
+    // `parseStage2Verdict` in dispatcher-types.ts.
+    const stripped = trimmed
+        .replace(/^```(?:json)?\s*/i, "")
+        .replace(/```\s*$/i, "")
+        .trim();
+    const candidates = extractBalancedJsonObjects(stripped);
+    if (candidates.length === 0)
+        return { parseError: "no-json-object" };
+    const objText = candidates[candidates.length - 1];
+    let parsed;
+    try {
+        parsed = JSON.parse(objText);
+    }
+    catch (err) {
+        return { parseError: `invalid-json: ${err.message}` };
+    }
+    if (!parsed || typeof parsed !== "object") {
+        return { parseError: "not-an-object" };
+    }
+    const obj = parsed;
+    const fetched = typeof obj.fetched === "number" ? obj.fetched : 0;
+    const posted = typeof obj.posted === "number" ? obj.posted : 0;
+    const duplicates = typeof obj.duplicates === "number" ? obj.duplicates : 0;
+    const errors = Array.isArray(obj.errors)
+        ? obj.errors
+            .filter((row) => typeof row === "object" && row !== null)
+            .map((row) => ({ ...row }))
+        : [];
+    const status = errors.length > 0 ? "partial" : "success";
+    return {
+        status,
+        fetched,
+        posted,
+        duplicates,
+        errors,
+        skipped: false,
+    };
+}
+function xmlEscape(value) {
+    return value
+        .replace(/&/g, "&amp;")
+        .replace(/"/g, "&quot;")
+        .replace(/</g, "&lt;")
+        .replace(/>/g, "&gt;");
+}
+/**
+ * Render the `<fetch_report>` XML block injected into the parent
+ * routine's prompt. Keep the schema narrow — every additional attribute
+ * costs prompt tokens on the cache-warm parent session.
+ *
+ * `meta.routine` accepts any string so the no-routine-key skip path can
+ * render the parent event's actual type (e.g. `routine.skill_curation`)
+ * instead of borrowing a catalog entry as a placeholder. The renderer
+ * strips the `routine.` prefix verbatim — callers may pass either the
+ * fully-qualified ProcessKey or a bare suffix.
+ */
+export function renderFetchReportBlock(report, meta) {
+    const routineAttr = meta.routine.replace(/^routine\./, "");
+    const lines = [
+        `<fetch_report routine="${xmlEscape(routineAttr)}" agent_day="${xmlEscape(meta.agentDay)}" status="${xmlEscape(report.status)}" fetched="${report.fetched}" posted="${report.posted}" duplicates="${report.duplicates}">`,
+    ];
+    if (report.failureReason) {
+        lines.push(`  <failure>${xmlEscape(report.failureReason)}</failure>`);
+    }
+    for (const err of report.errors) {
+        const type = typeof err.type === "string" ? err.type : "unknown";
+        // Compact, attribute-shaped serialisation: every string-typed key
+        // becomes an XML attribute; nested objects are collapsed to JSON
+        // text content so the block stays parseable both as XML and as a
+        // line-by-line scan target.
+        const attrEntries = Object.entries(err).filter(([k, v]) => k !== "type" && (typeof v === "string" || typeof v === "number"));
+        const attrs = attrEntries
+            .map(([k, v]) => `${xmlEscape(k)}="${xmlEscape(String(v))}"`)
+            .join(" ");
+        const nested = Object.entries(err).filter(([k, v]) => k !== "type"
+            && typeof v !== "string"
+            && typeof v !== "number");
+        if (nested.length > 0) {
+            lines.push(`  <error type="${xmlEscape(type)}"${attrs ? " " + attrs : ""}>${xmlEscape(JSON.stringify(Object.fromEntries(nested)))}</error>`);
+        }
+        else {
+            lines.push(`  <error type="${xmlEscape(type)}"${attrs ? " " + attrs : ""} />`);
+        }
+    }
+    lines.push("</fetch_report>");
+    return lines.join("\n");
+}
+// ── Runner ────────────────────────────────────────────────────────────────
+export class RoutineFetchWindowRunner {
+    db;
+    config;
+    contextBuilder;
+    agentRouter;
+    audit;
+    prompt;
+    getActiveMailAccounts;
+    constructor(deps) {
+        this.db = deps.db;
+        this.config = deps.config;
+        this.contextBuilder = deps.contextBuilder;
+        this.agentRouter = deps.agentRouter;
+        this.audit = deps.audit;
+        this.prompt = deps.prompt;
+        this.getActiveMailAccounts = deps.getActiveMailAccounts;
+    }
+    /**
+     * Execute the pre-pass for `parentEvent`. Returns the fetch report
+     * and rendered `<fetch_report>` block; callers graft the block into
+     * the parent event's `event.data.fetchReportBlock` so ContextBuilder
+     * injects it into the parent prompt.
+     *
+     * `routineKey` overrides the auto-derived window key — used by
+     * morning_routine to opt into `routine.morning_routine_initial`'s
+     * plan when `yesterday.md` is absent (their plans currently coincide,
+     * but the seam exists for future divergence).
+     */
+    async run(parentEvent, routineKey) {
+        const key = routineKey ?? routineWindowKeyFromEvent(parentEvent);
+        const agentDay = getAgentDayDateStr(this.config.timezone || undefined, this.config.dayBoundaryHour);
+        if (!key) {
+            const report = {
+                status: "skipped",
+                fetched: 0,
+                posted: 0,
+                duplicates: 0,
+                errors: [],
+                skipped: true,
+                failureReason: "no-routine-window-key",
+            };
+            // Surface the parent's actual event type rather than borrowing a
+            // catalog entry — the report attribution would otherwise lie about
+            // which routine the pre-pass was attempted for, hiding the
+            // misroute behind a plausible-looking placeholder.
+            const block = renderFetchReportBlock(report, {
+                routine: parentEvent.type,
+                agentDay,
+            });
+            return { report, block };
+        }
+        if (!routineHasWindows(key)) {
+            const report = {
+                status: "skipped",
+                fetched: 0,
+                posted: 0,
+                duplicates: 0,
+                errors: [],
+                skipped: true,
+            };
+            const block = renderFetchReportBlock(report, { routine: key, agentDay });
+            return { report, block };
+        }
+        // Build the acquisition plan from the current integration state +
+        // active accounts. The dispatcher's session backend is the resolved
+        // main backend for the routine.fetch_window ProcessKey — resolve via
+        // the agent router so the per-(integration, mode) predicate
+        // (`delegated-same` vs `delegated-cross`) is correct for the actual
+        // run.
+        //
+        // `integrationsSnapshot` and `sessionBackend` are hoisted above the
+        // try block so the `allowedToolsOverride` composer below can re-use
+        // the same snapshot the plan was built from. Recomputing the
+        // snapshot at execute time would risk a TOCTOU drift if the
+        // operator flips an integration mid-pre-pass — the plan would have
+        // a row the override couldn't reach, manifesting as a silent MCP
+        // permission denial.
+        let fetcherEvent;
+        let sessionBackend;
+        let integrationsSnapshot;
+        try {
+            // Resolve binding off a placeholder event so we know the session
+            // backend before we synthesise the real one (the plan attribute
+            // depends on it). The placeholder borrows correlationId so audit
+            // rows correlate back to the parent.
+            const placeholder = {
+                ...createEvent({
+                    type: FETCH_WINDOW_EVENT_TYPE,
+                    source: parentEvent.source,
+                    priority: EventPriority.NORMAL,
+                    correlationId: parentEvent.correlationId,
+                }),
+                routine: "fetch_window",
+            };
+            const preBinding = this.agentRouter.resolveBinding(placeholder, {
+                processKey: FETCH_WINDOW_PROCESS_KEY,
+            });
+            sessionBackend = preBinding.main.backendId;
+            integrationsSnapshot = readIntegrations(this.db);
+            const accounts = this.collectAccounts(integrationsSnapshot);
+            const timestamps = buildAcquisitionTimestamps(new Date(), this.config.timezone || undefined, this.config.dayBoundaryHour);
+            const planBlock = buildAcquisitionPlan({
+                routine: key,
+                agentDay,
+                integrations: integrationsSnapshot,
+                sessionBackend,
+                accounts,
+                timestamps,
+            });
+            fetcherEvent = {
+                ...placeholder,
+                data: {
+                    ...placeholder.data,
+                    acquisitionPlanBlock: planBlock,
+                    parentRoutine: key,
+                    parentCorrelationId: parentEvent.correlationId,
+                },
+            };
+        }
+        catch (err) {
+            return this.fail(key, agentDay, parentEvent, "plan-assembly-failed", err);
+        }
+        // The acquisition plan can resolve to zero `<fetch>` rows when every
+        // integration the routine touches is disabled / cross-backend-bound
+        // on a connector-less integration / etc. Treat that as a skip — we
+        // don't pay the Haiku cold-start to confirm the agent has nothing
+        // to do.
+        if (!fetcherPlanHasFetches(fetcherEvent.data.acquisitionPlanBlock)) {
+            const report = {
+                status: "skipped",
+                fetched: 0,
+                posted: 0,
+                duplicates: 0,
+                errors: [],
+                skipped: true,
+                fetcherCorrelationId: fetcherEvent.correlationId,
+            };
+            const block = renderFetchReportBlock(report, { routine: key, agentDay });
+            logger.debug({
+                routine: key,
+                correlationId: fetcherEvent.correlationId,
+                parentCorrelationId: parentEvent.correlationId,
+            }, "Routine fetch-window pre-pass skipped — acquisition plan empty");
+            return { report, block };
+        }
+        // Execute the fetcher session through the standard router pipeline.
+        let context;
+        try {
+            context = await this.contextBuilder.build(fetcherEvent);
+        }
+        catch (err) {
+            return this.fail(key, agentDay, parentEvent, "context-build-failed", err, {
+                fetcherCorrelationId: fetcherEvent.correlationId,
+            });
+        }
+        let binding;
+        try {
+            binding = this.agentRouter.resolveBinding(fetcherEvent, {
+                processKey: FETCH_WINDOW_PROCESS_KEY,
+            });
+        }
+        catch (err) {
+            return this.fail(key, agentDay, parentEvent, "binding-resolve-failed", err, {
+                fetcherCorrelationId: fetcherEvent.correlationId,
+            });
+        }
+        const reassemblePrompt = (bid) => this.prompt.assemble(FETCH_WINDOW_EVENT_TYPE, FETCH_WINDOW_PROCESS_KEY, bid);
+        const prompt = reassemblePrompt(binding.main.backendId);
+        // Defense-in-depth tool clamp. Replaces the SDK's default
+        // allowlist with a narrow set covering only the surfaces the
+        // partials use. Backs the agent profile's "no notify, no context
+        // writes" guardrails with a daemon-enforced floor so a misbehaving
+        // Haiku turn cannot reach `/api/notify`, `/api/context/*`, or any
+        // tool outside the documented partial contract. Codex / Gemini
+        // ignore per-spawn `allowedToolsOverride` (CLAUDE.md §"Per-spawn
+        // tools surface gap"), but the `process_backend_config` envelope
+        // (max_turns / max_budget_usd) still applies.
+        const allowedToolsOverride = composePrePassAllowedTools(this.config.apiPort, integrationsSnapshot, binding.main.backendId);
+        let result;
+        try {
+            result = await this.agentRouter.execute({
+                prompt,
+                context,
+                event: fetcherEvent,
+                processKey: FETCH_WINDOW_PROCESS_KEY,
+                preResolvedBinding: binding,
+                reassemblePrompt,
+                allowedToolsOverride,
+            });
+        }
+        catch (err) {
+            return this.fail(key, agentDay, parentEvent, "agent-execute-failed", err, {
+                fetcherCorrelationId: fetcherEvent.correlationId,
+            });
+        }
+        // Audit row for the fetcher session itself, distinct from the
+        // parent routine's audit row written by the result processor.
+        try {
+            this.audit.logAction({
+                event: fetcherEvent,
+                model: result.model,
+                costUsd: result.costUsd,
+                usage: result.usage,
+                modelUsage: result.modelUsage,
+                durationMs: result.durationMs,
+                numTurns: result.numTurns,
+                trigger: "autonomous",
+                ...(result.backendId ? { backend: result.backendId } : {}),
+                ...(result.costSource ? { costSource: result.costSource } : {}),
+                contextUpdated: result.contextUpdated,
+                ...(typeof result.advisorCallCount === "number"
+                    ? { advisorCallCount: result.advisorCallCount }
+                    : {}),
+            });
+        }
+        catch (err) {
+            logger.warn({ err, routine: key, correlationId: fetcherEvent.correlationId }, "Failed to log routine.fetch_window agent_actions row");
+        }
+        const parsed = parseFetchWindowOutput(result.output);
+        if ("parseError" in parsed) {
+            const report = {
+                status: "failed",
+                fetched: 0,
+                posted: 0,
+                duplicates: 0,
+                errors: [{ type: "pre-pass-parse-failed", reason: parsed.parseError }],
+                skipped: false,
+                failureReason: parsed.parseError,
+                fetcherCorrelationId: fetcherEvent.correlationId,
+            };
+            const block = renderFetchReportBlock(report, { routine: key, agentDay });
+            logger.warn({
+                routine: key,
+                reason: parsed.parseError,
+                correlationId: fetcherEvent.correlationId,
+                parentCorrelationId: parentEvent.correlationId,
+            }, "Routine fetch-window pre-pass output unparsable — parent routine will see <fetch_report status='failed'>");
+            return { report, block };
+        }
+        const report = {
+            ...parsed,
+            fetcherCorrelationId: fetcherEvent.correlationId,
+        };
+        const block = renderFetchReportBlock(report, { routine: key, agentDay });
+        logger.info({
+            routine: key,
+            status: report.status,
+            fetched: report.fetched,
+            posted: report.posted,
+            duplicates: report.duplicates,
+            errorCount: report.errors.length,
+            correlationId: fetcherEvent.correlationId,
+            parentCorrelationId: parentEvent.correlationId,
+        }, "Routine fetch-window pre-pass completed");
+        return { report, block };
+    }
+    /**
+     * Helper for the failure paths — renders a `<fetch_report status="failed">`
+     * block and logs the underlying error. Never throws so the caller can
+     * always continue with the parent routine dispatch.
+     */
+    fail(routine, agentDay, parentEvent, kind, err, extra = {}) {
+        const message = err instanceof Error ? err.message : String(err);
+        const report = {
+            status: "failed",
+            fetched: 0,
+            posted: 0,
+            duplicates: 0,
+            errors: [{ type: "pre-pass-failed", kind, message }],
+            skipped: false,
+            failureReason: `${kind}: ${message}`,
+            ...(extra.fetcherCorrelationId
+                ? { fetcherCorrelationId: extra.fetcherCorrelationId }
+                : {}),
+        };
+        const block = renderFetchReportBlock(report, { routine, agentDay });
+        logger.warn({
+            routine,
+            kind,
+            err,
+            parentCorrelationId: parentEvent.correlationId,
+        }, "Routine fetch-window pre-pass failed — parent routine will see <fetch_report status='failed'>");
+        return { report, block };
+    }
+    /**
+     * Translate the mail registry's active-account list into the
+     * `AcquisitionAccount[]` shape `buildAcquisitionPlan` expects. Only
+     * accounts whose integration is currently non-disabled survive — a
+     * disabled gmail integration with five accounts produces zero rows,
+     * matching the partial's `<!-- mode:disabled:gmail -->` no-op.
+     */
+    collectAccounts(integrations) {
+        const rows = [];
+        for (const account of this.getActiveMailAccounts()) {
+            const integrationKey = mailAccountIntegrationKey(account);
+            if (integrationKey === null)
+                continue;
+            const state = integrations[integrationKey];
+            if (!state || state.mode === "disabled")
+                continue;
+            rows.push({
+                integration: integrationKey,
+                accountId: account.id,
+                label: account.email,
+            });
+        }
+        return rows;
+    }
+}
+// ── Internal helpers ──────────────────────────────────────────────────────
+/**
+ * Return true when the rendered plan carries at least one `<fetch ...>`
+ * element. The plan is well-formed even when empty (the dispatcher
+ * always emits the wrapper) — we still want to short-circuit so the
+ * pre-pass cold-start never fires for a routine with nothing to do.
+ */
+function fetcherPlanHasFetches(plan) {
+    if (typeof plan !== "string")
+        return false;
+    return /<fetch\s/i.test(plan);
+}
+//# sourceMappingURL=routine-fetch-window-runner.js.map