@aitne/daemon 0.1.3 → 0.1.6

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

@@ -0,0 +1,1591 @@
+/**
+ * `RoutineFetchWindowRunner` — pre-pass fan-out coordinator.
+ *
+ * ROUTINE_DATA_ACQUISITION_DESIGN.md §6.1.1 + PRE_PASS_FAN_OUT_DESIGN.md
+ * — 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 rows out per-account where applicable,
+ *     resolves each row's predicate (`direct` / `delegated-same` /
+ *     `delegated-cross` / `native` / skip), and partitions the plan
+ *     by `IntegrationKey` via `splitAcquisitionPlanByIntegration`.
+ *  2. Spawns one lite-tier `routine.fetch_window` sub-session per
+ *     integration in parallel (bounded by `prePassFanOutConcurrency`).
+ *     Each sub-session sees exactly one partial — the
+ *     `{integration_partial}` placeholder in the
+ *     `routine.fetch_window` task-flow is replaced with the body of
+ *     `_partials/<integration prePassPartial>` so the lite-tier model
+ *     never has to disambiguate cross-API argument names. Each
+ *     sub-session runs through an independent retry loop bounded by
+ *     `prePassMaxAttemptsPerIntegration`, `prePassBackoffMs`, and the
+ *     per-integration / per-routine USD budget caps.
+ *  3. Merges the sub-reports into a single `FetchReport` (additive
+ *     `<integration>` children on the `<fetch_report>` XML block) and
+ *     returns it plus the rendered block.
+ *  4. The caller grafts the block into the **parent** routine event's
+ *     `event.data.fetchReportBlock`. ContextBuilder injects it verbatim
+ *     into the parent session's prompt (mirrors the `<gate_decision>`
+ *     pattern used by hourly_check Stage 3).
+ *
+ * Failure-mode contract (PRE_PASS_FAN_OUT_DESIGN.md §5):
+ *
+ *  - **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) — recorded per-attempt; the retry loop fires up
+ *    to `maxAttempts` before giving up. Final per-integration status
+ *    surfaces in `<integration status="failed">`. Pre-pass cost gains
+ *    are forfeit for that integration; siblings are unaffected.
+ *    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`,
+ *    `budget-cap`, `global-budget-cap`). 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 { renderPartialForFanOut } from "./prompts.js";
+import { ROUTINE_WINDOWS, routineHasWindows, } from "./routine-windows.js";
+import { buildAcquisitionTimestamps, splitAcquisitionPlanByIntegration, } from "./routine-acquisition-plan.js";
+import { RETRY_REASONS, buildPriorAttemptHintBlock, defaultRetryDecision, } from "./routine-fetch-window-retry.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";
+/**
+ * PRE_PASS_FAN_OUT_DESIGN.md §4.2 — the single placeholder the
+ * `routine.fetch_window.md` task-flow carries in place of inline
+ * integration partials. The runner substitutes this with the
+ * integration-specific partial body loaded via
+ * `renderPartialForFanOut`. Kept as a constant so the task-flow file
+ * and the substitution call cannot drift apart.
+ */
+const FETCH_WINDOW_INTEGRATION_PARTIAL_PLACEHOLDER = "{integration_partial}";
+/**
+ * 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).
+ *
+ * Each pattern uses a wildcard `*` between `curl` and the URL so the
+ * SDK's glob matcher accepts both flag orderings the Haiku fetcher
+ * actually emits:
+ *
+ *   - `curl http://localhost:.../api/observations -X POST -d @-` (URL first)
+ *   - `curl -X POST -H 'Content-Type: …' http://localhost:.../api/observations -d @-`
+ *     (flags first)
+ *
+ * The original prefix-anchored form (`Bash(curl http://localhost:.../api/observations*)`)
+ * silently denied the flags-first invocation, manifesting as `posted=0,
+ * fetched=N` reports — Haiku fetched via MCP, then could not POST a single
+ * observation. The curl PreToolUse hook in `claude-tool-collection.ts`
+ * remains the host/port/exfil chokepoint; this clamp now restricts only
+ * the daemon-API namespace, which is what we actually need.
+ *
+ * `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.
+ *
+ * `ToolSearch` is appended for Claude sessions whenever at least one
+ * descriptor-bound MCP tool is present. Claude Code 2.1+ defers large
+ * MCP tool manifests (`mcp__claude_ai_Gmail__*`,
+ * `mcp__claude_ai_Google_Calendar__*`, `mcp__claude_ai_Notion__*`, …)
+ * behind `ToolSearch`, so the model must call `ToolSearch` to load a
+ * deferred tool's schema before it can be invoked. Without `ToolSearch`
+ * allowed, the Haiku fetcher emits a denied ToolSearch call on its
+ * first turn, gives up, and returns text with no JSON — the parent
+ * routine then sees `<fetch_report status="failed" reason="no-json-object">`.
+ * Mirrors the same workaround in `claude-delegated.ts` (delegated proxy
+ * `allowedTools: [toolName, "ToolSearch"]`). Codex / Gemini have no
+ * per-spawn allowedTools surface today and ignore the override entirely
+ * (CLAUDE.md acknowledges the gap), so the `ToolSearch` widening is
+ * gated on `sessionBackend === "claude"` to keep the list minimal for
+ * other backends.
+ *
+ * Exported for unit testing — the runner consumes it via
+ * `composePrePassAllowedTools` at dispatch time.
+ */
+export function composePrePassAllowedTools(apiPort, integrations, sessionBackend) {
+    const integrationTools = collectIntegrationToolsForBackend(integrations, sessionBackend);
+    const needsDeferredDiscovery = sessionBackend === "claude" && integrationTools.length > 0;
+    return [
+        ...buildPrePassDaemonRestPatterns(apiPort),
+        ...integrationTools,
+        ...(needsDeferredDiscovery ? ["ToolSearch"] : []),
+    ];
+}
+/**
+ * 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");
+}
+// ── Fan-out aggregation (PRE_PASS_FAN_OUT_DESIGN.md §4.5) ─────────────────
+/**
+ * Resolve the aggregate `<fetch_report>` status from a set of
+ * sub-reports' final statuses, per §4.5:
+ *
+ *  - `success` iff every non-skipped sub-report is `success`. Skipped
+ *    sub-reports do not count against success.
+ *  - `failed` iff every non-skipped sub-report is `failed`.
+ *  - `partial` for any other mix (incl. one success + one failed).
+ *  - `skipped` only when the input is empty (the caller handles
+ *    "every sub-report skipped" separately — the runner short-circuits
+ *    before fan-out when no integrations are active).
+ *
+ * Exported for unit testing the status-resolution branch in isolation.
+ */
+export function aggregateFanOutStatus(subReports) {
+    if (subReports.length === 0)
+        return "skipped";
+    const nonSkipped = subReports.filter((r) => r.status !== "skipped");
+    if (nonSkipped.length === 0)
+        return "skipped";
+    const allSuccess = nonSkipped.every((r) => r.status === "success");
+    if (allSuccess)
+        return "success";
+    const allFailed = nonSkipped.every((r) => r.status === "failed");
+    if (allFailed)
+        return "failed";
+    return "partial";
+}
+/**
+ * Render the additive `<integration>` children + the `<error>`
+ * grandchildren that go inside a fan-out `<fetch_report>`. The parent
+ * `<fetch_report ...>` open/close lines are produced by
+ * `renderFetchReportBlock`; this helper produces only the body lines so
+ * the two can compose cleanly.
+ */
+function renderPerIntegrationLines(subReports) {
+    const lines = [];
+    for (const sub of subReports) {
+        const errors = errorsForSubReport(sub);
+        const openAttrs = [
+            `key="${xmlEscape(sub.integrationKey)}"`,
+            `status="${xmlEscape(sub.status)}"`,
+            `fetched="${sub.fetched}"`,
+            `posted="${sub.posted}"`,
+            `duplicates="${sub.duplicates}"`,
+            `attempts="${sub.attempts.length}"`,
+        ];
+        if (errors.length === 0) {
+            lines.push(`  <integration ${openAttrs.join(" ")} />`);
+            continue;
+        }
+        lines.push(`  <integration ${openAttrs.join(" ")}>`);
+        for (const err of errors) {
+            const type = typeof err.type === "string" ? err.type : "unknown";
+            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(" ");
+            lines.push(`    <error type="${xmlEscape(type)}"${attrs ? " " + attrs : ""} />`);
+        }
+        lines.push(`  </integration>`);
+    }
+    return lines;
+}
+/**
+ * Flatten every attempt's `errors` into a single sequence — the runner
+ * always pushes at least one record per loop iteration, so the union of
+ * attempts' errors is the canonical list (and equals `sub.errors`,
+ * which is set from `flatMap(attempts, e => e.errors)` at sub-report
+ * construction time). Kept as a helper so the rendering / merge call
+ * sites read declaratively.
+ */
+function errorsForSubReport(sub) {
+    return sub.attempts.flatMap((att) => att.errors);
+}
+function attemptDurationMs(att) {
+    const start = Date.parse(att.startedAt);
+    const end = Date.parse(att.endedAt);
+    if (!Number.isFinite(start) || !Number.isFinite(end))
+        return 0;
+    return Math.max(0, end - start);
+}
+function pickFinalErrorMessage(sub) {
+    if (sub.status !== "failed")
+        return undefined;
+    const finalAttempt = sub.attempts[sub.attempts.length - 1];
+    const firstError = finalAttempt?.errors?.[0];
+    if (!firstError)
+        return undefined;
+    const message = firstError.message ?? firstError.reason ?? firstError.kind;
+    return typeof message === "string" ? message : undefined;
+}
+export function summarizeIntegrationReport(sub) {
+    const costUsd = sub.attempts.reduce((sum, att) => sum + att.costUsd, 0);
+    const durationMs = sub.attempts.reduce((sum, att) => sum + attemptDurationMs(att), 0);
+    const finalError = pickFinalErrorMessage(sub);
+    return {
+        key: sub.integrationKey,
+        status: sub.status,
+        attempts: sub.attempts.length,
+        fetched: sub.fetched,
+        posted: sub.posted,
+        duplicates: sub.duplicates,
+        costUsd,
+        durationMs,
+        ...(finalError ? { finalError } : {}),
+    };
+}
+export function summarizeFetchReport(report) {
+    const perIntegration = report.perIntegration ?? [];
+    const costUsd = perIntegration.reduce((sum, sub) => sum + sub.attempts.reduce((s, att) => s + att.costUsd, 0), 0);
+    return {
+        status: report.status,
+        fetched: report.fetched,
+        posted: report.posted,
+        duplicates: report.duplicates,
+        costUsd,
+    };
+}
+/**
+ * Merge fan-out sub-reports into a single `FetchReport` + the rendered
+ * `<fetch_report>` XML block the parent routine sees. §4.5.
+ *
+ *  - Counts (`fetched`, `posted`, `duplicates`): arithmetic sum.
+ *  - `errors`: concatenation, each error tagged with
+ *    `integration: <key>` (and the per-attempt rows already carry
+ *    `attempt: <n>` via the runner's per-attempt error-recording —
+ *    `mergeSubReports` does not invent annotations beyond `integration`).
+ *  - `status`: `aggregateFanOutStatus`.
+ *  - `failureReason`: only when aggregate is `failed`; one-line summary
+ *    listing the failed integrations and their attempt counts.
+ *  - `perIntegration`: sorted by `INTEGRATION_KEYS` order regardless of
+ *    completion order (deterministic — §4.6).
+ *
+ * Pure function: no side effects, no DB / clock dependencies.
+ */
+export function mergeSubReports(subReports, routine, agentDay) {
+    // Deterministic ordering by INTEGRATION_KEYS enumeration order so the
+    // block is stable across runs regardless of which sub-session
+    // finished first.
+    const ordered = INTEGRATION_KEYS
+        .map((k) => subReports.find((r) => r.integrationKey === k))
+        .filter((r) => r !== undefined);
+    // Defensive — preserve any non-canonical keys at the tail rather
+    // than dropping them. Today every SubReport's integrationKey comes
+    // from the canonical enum, but a future key added to the registry
+    // without the catalog catching up would otherwise be silently
+    // suppressed.
+    for (const r of subReports) {
+        if (!ordered.includes(r))
+            ordered.push(r);
+    }
+    let fetched = 0;
+    let posted = 0;
+    let duplicates = 0;
+    const errors = [];
+    for (const sub of ordered) {
+        fetched += sub.fetched;
+        posted += sub.posted;
+        duplicates += sub.duplicates;
+        for (const err of errorsForSubReport(sub)) {
+            errors.push({ ...err, integration: sub.integrationKey });
+        }
+    }
+    const status = aggregateFanOutStatus(ordered);
+    let failureReason;
+    if (status === "failed") {
+        const failedSummaries = ordered
+            .filter((r) => r.status === "failed")
+            .map((r) => `${r.integrationKey} (${r.attempts.length} attempts)`);
+        failureReason = failedSummaries.length > 0
+            ? `${failedSummaries.length} integrations failed: ${failedSummaries.join(", ")}`
+            : "all sub-sessions failed";
+    }
+    const report = {
+        status,
+        fetched,
+        posted,
+        duplicates,
+        errors,
+        skipped: status === "skipped",
+        ...(failureReason !== undefined ? { failureReason } : {}),
+        perIntegration: ordered,
+    };
+    // Render: open/close come from a `renderFetchReportBlock`-shaped
+    // header line; body interleaves the per-integration children. We
+    // emit a fresh string rather than calling `renderFetchReportBlock`
+    // because the aggregated block carries `<integration>` children that
+    // the short-circuit (skipped / failed) blocks emitted by
+    // `renderFetchReportBlock` do not — keeping the two render paths
+    // explicit avoids cross-contaminating their shapes.
+    const routineAttr = routine.replace(/^routine\./, "");
+    const headerAttrs = [
+        `routine="${xmlEscape(routineAttr)}"`,
+        `agent_day="${xmlEscape(agentDay)}"`,
+        `status="${xmlEscape(status)}"`,
+        `fetched="${fetched}"`,
+        `posted="${posted}"`,
+        `duplicates="${duplicates}"`,
+    ];
+    const lines = [`<fetch_report ${headerAttrs.join(" ")}>`];
+    if (failureReason !== undefined) {
+        lines.push(`  <failure>${xmlEscape(failureReason)}</failure>`);
+    }
+    lines.push(...renderPerIntegrationLines(ordered));
+    lines.push("</fetch_report>");
+    return { report, block: lines.join("\n") };
+}
+/**
+ * Race-free local budget guard for one fan-out coordinator. Reservations
+ * mutate a separate `reservedUsd` bucket before async work starts; commit
+ * releases that reservation and records the measured spend.
+ */
+class FanOutBudgetGuard {
+    capUsd;
+    reservedUsd = 0;
+    spentUsd = 0;
+    constructor(capUsd) {
+        this.capUsd = capUsd;
+    }
+    reserve(estimateUsd) {
+        // Defensive normalisation: a non-finite estimate (NaN / undefined coerced
+        // through Math.max) would poison `reservedUsd` permanently — every
+        // subsequent reserve() would arithmetic-NaN and report `false` for the
+        // headroom check. The binding contract today guarantees a finite number,
+        // but the guard is one strict layer below where a malformed config or a
+        // future backend shape could leak through.
+        const estimate = Number.isFinite(estimateUsd)
+            ? Math.max(0, estimateUsd)
+            : 0;
+        if (!Number.isFinite(this.capUsd)) {
+            return { ok: true, remaining: Number.POSITIVE_INFINITY, estimateUsd: estimate };
+        }
+        const remaining = this.capUsd - this.spentUsd - this.reservedUsd;
+        if (estimate > remaining) {
+            return { ok: false, remaining: Math.max(0, remaining), estimateUsd: estimate };
+        }
+        this.reservedUsd += estimate;
+        return {
+            ok: true,
+            remaining: Math.max(0, this.capUsd - this.spentUsd - this.reservedUsd),
+            estimateUsd: estimate,
+        };
+    }
+    commit(reservation, actualUsd) {
+        if (!reservation.ok)
+            return;
+        this.reservedUsd = Math.max(0, this.reservedUsd - reservation.estimateUsd);
+        // Same defensive guard as reserve() — NaN actualUsd from a misbehaving
+        // backend would otherwise corrupt the spend counter and silently disable
+        // the cap for the remainder of the routine.
+        if (Number.isFinite(actualUsd)) {
+            this.spentUsd += Math.max(0, actualUsd);
+        }
+    }
+    get spent() {
+        return this.spentUsd;
+    }
+}
+function clampInt(value, min, max, fallback) {
+    if (typeof value !== "number" || !Number.isFinite(value))
+        return fallback;
+    return Math.min(max, Math.max(min, Math.trunc(value)));
+}
+function nonNegativeNumber(value, fallback) {
+    if (typeof value !== "number" || !Number.isFinite(value) || value < 0) {
+        return fallback;
+    }
+    return value;
+}
+function sleep(ms) {
+    if (ms <= 0)
+        return Promise.resolve();
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+async function runWithConcurrency(tasks, concurrency) {
+    if (tasks.length === 0)
+        return [];
+    if (concurrency === null || concurrency >= tasks.length) {
+        return Promise.all(tasks.map((task) => task()));
+    }
+    const limit = Math.max(1, Math.trunc(concurrency));
+    const results = new Array(tasks.length);
+    let next = 0;
+    async function worker() {
+        for (;;) {
+            const index = next;
+            next += 1;
+            if (index >= tasks.length)
+                return;
+            results[index] = await tasks[index]();
+        }
+    }
+    const workers = Array.from({ length: Math.min(limit, tasks.length) }, () => worker());
+    await Promise.all(workers);
+    return results;
+}
+// ── Runner ────────────────────────────────────────────────────────────────
+export class RoutineFetchWindowRunner {
+    db;
+    config;
+    contextBuilder;
+    agentRouter;
+    audit;
+    prompt;
+    getActiveMailAccounts;
+    getEventBroadcaster;
+    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;
+        this.getEventBroadcaster = deps.getEventBroadcaster ?? null;
+    }
+    /**
+     * Broadcast a single pre-pass progress event to the dashboard SSE
+     * channel. Failure is contained — the broadcaster contract is
+     * fire-and-forget and a misbehaving writer must not affect the
+     * runner's return value or the parent routine's dispatch.
+     *
+     * Schema (default `event` SSE channel, matches existing
+     * `kind: "main_backend_changed"` / `"routine_started"` pattern):
+     *   { kind, routine, source, correlationId, timestamp, status? }
+     * `status` is set on `prepass_completed` only and reflects the
+     * FetchReport.status field (success / partial / failed / skipped).
+     */
+    broadcastPrepassProgress(kind, parentEvent, extra) {
+        const broadcaster = this.getEventBroadcaster?.();
+        if (!broadcaster)
+            return;
+        try {
+            broadcaster.broadcastEvent({
+                kind,
+                routine: isRoutineEvent(parentEvent) ? parentEvent.routine : null,
+                source: parentEvent.source,
+                correlationId: parentEvent.correlationId,
+                timestamp: new Date().toISOString(),
+                ...(extra?.status ? { status: extra.status } : {}),
+                ...(extra?.reason ? { reason: extra.reason } : {}),
+                ...Object.fromEntries(Object.entries(extra ?? {}).filter(([key]) => key !== "status" && key !== "reason")),
+            });
+        }
+        catch {
+            // Intentionally silent — broadcaster failures are already logged at
+            // the EventBroadcaster.broadcastNamedEvent layer. Re-logging here
+            // would spam during transient SSE client churn.
+        }
+    }
+    /**
+     * 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) {
+        // B2 observability — announce pre-pass entry so the dashboard can
+        // render "Fetching your mail and Notion data…" as a sub-step of the
+        // parent routine's `routine_started` envelope. `prepass_completed`
+        // (with status) fires from the single exit point at the bottom of
+        // `runImpl` via the try/finally below. Symmetric: every started
+        // emit has a matching completed emit, even on the skipped paths
+        // (skipping is itself information the user wants to see).
+        this.broadcastPrepassProgress("prepass_started", parentEvent);
+        let outcome;
+        try {
+            outcome = await this.runImpl(parentEvent, routineKey);
+            return outcome;
+        }
+        finally {
+            // §7.2 — `prepass_completed` payload contract:
+            //   { kind, routine, source, correlationId, timestamp, status, reason?,
+            //     aggregate: {status, fetched, posted, duplicates, costUsd},
+            //     perIntegration: [{key, status, attempts, fetched, posted,
+            //                       duplicates, costUsd, durationMs, finalError?}] }
+            // The aggregate + perIntegration arrays let the dashboard render
+            // the per-integration progress card the design called for without
+            // re-querying the daemon. Skipped / failed short-circuit paths
+            // (no-routine-key / no-windows / empty-plan / plan-assembly-failed)
+            // produce reports without `perIntegration`; in those cases the
+            // aggregate still carries the headline (fetched/posted = 0,
+            // costUsd = 0) and `perIntegration` is the empty array.
+            const report = outcome?.report;
+            const perIntegration = (report?.perIntegration ?? []).map(summarizeIntegrationReport);
+            const aggregate = report
+                ? summarizeFetchReport(report)
+                : undefined;
+            this.broadcastPrepassProgress("prepass_completed", parentEvent, {
+                status: report?.status,
+                ...(report?.failureReason ? { reason: report.failureReason } : {}),
+                ...(aggregate ? { aggregate } : {}),
+                perIntegration,
+            });
+        }
+    }
+    async runImpl(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 };
+        }
+        let planContext;
+        try {
+            planContext = this.buildFanOutPlanContext(parentEvent, key, agentDay);
+        }
+        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. `splitAcquisitionPlanByIntegration`
+        // drops integrations with no rows, so an empty `subPlans` exactly
+        // means the routine has nothing to fetch. Treat that as a skip —
+        // we don't pay the cold-start to confirm the agent has nothing
+        // to do.
+        if (planContext.subPlans.length === 0) {
+            const report = {
+                status: "skipped",
+                fetched: 0,
+                posted: 0,
+                duplicates: 0,
+                errors: [],
+                skipped: true,
+                fetcherCorrelationId: planContext.placeholder.correlationId,
+            };
+            const block = renderFetchReportBlock(report, { routine: key, agentDay });
+            logger.debug({
+                routine: key,
+                correlationId: planContext.placeholder.correlationId,
+                parentCorrelationId: parentEvent.correlationId,
+            }, "Routine fetch-window pre-pass skipped — acquisition plan empty");
+            return { report, block };
+        }
+        try {
+            return await this.runFanOut({
+                key,
+                agentDay,
+                parentEvent,
+                subPlans: planContext.subPlans,
+                integrationsSnapshot: planContext.integrationsSnapshot,
+                accounts: planContext.accounts,
+                timestamps: planContext.timestamps,
+            });
+        }
+        catch (err) {
+            return this.fail(key, agentDay, parentEvent, "fan-out-failed", err, {
+                fetcherCorrelationId: planContext.placeholder.correlationId,
+            });
+        }
+    }
+    buildFanOutPlanContext(parentEvent, key, agentDay) {
+        // Resolve binding off a placeholder event so we know the session
+        // backend before splitting the plan (the partial body's mode markers
+        // and the per-row delegated-same / delegated-cross resolution both
+        // depend on the resolved backend). The placeholder borrows the
+        // parent correlationId so the empty-plan and plan-assembly-failed
+        // short-circuit reports carry a stable correlation id; fan-out
+        // sub-sessions get fresh ids per attempt.
+        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,
+        });
+        const integrationsSnapshot = readIntegrations(this.db);
+        const accounts = this.collectAccounts(integrationsSnapshot);
+        const timestamps = buildAcquisitionTimestamps(new Date(), this.config.timezone || undefined, this.config.dayBoundaryHour);
+        const planInput = {
+            routine: key,
+            agentDay,
+            integrations: integrationsSnapshot,
+            sessionBackend: preBinding.main.backendId,
+            accounts,
+            timestamps,
+        };
+        return {
+            key,
+            agentDay,
+            placeholder,
+            integrationsSnapshot,
+            subPlans: splitAcquisitionPlanByIntegration(planInput),
+            accounts,
+            timestamps,
+        };
+    }
+    /**
+     * §5 BackendQuotaError row + §4.4 retryEscalationTier — re-derive the
+     * per-integration sub-plan against the CURRENT attempt's binding so a
+     * cross-backend swap (escalation tier flips main backend, or
+     * `prePassRetryEscalationTier` swaps the per-attempt tier) keeps the
+     * plan's `<fetch mode="…">` attribute aligned with the partial body's
+     * remaining mode-branch (the partial is filtered for the new backend
+     * via `renderPartialForFanOut`). Returns null only when the
+     * integration becomes unreachable on the new backend (e.g. native
+     * mode bound to A but the attempt re-resolves to B); the runner
+     * passes the call through to record the original sub-plan and let
+     * the agent emit `no-surface` errors organically.
+     *
+     * Pure: snapshot inputs (`integrationsSnapshot`, `accounts`,
+     * `timestamps`) are frozen at run() entry; only `sessionBackend`
+     * varies across attempts. Re-derivation is cheap —
+     * `splitAcquisitionPlanByIntegration` walks `ROUTINE_WINDOWS[routine]`
+     * (a small constant) without I/O.
+     */
+    rebuildSubPlanForBackend(integrationKey, routineKey, agentDay, sessionBackend, integrationsSnapshot, accounts, timestamps) {
+        const subPlans = splitAcquisitionPlanByIntegration({
+            routine: routineKey,
+            agentDay,
+            integrations: integrationsSnapshot,
+            sessionBackend,
+            accounts,
+            timestamps,
+        });
+        return subPlans.find((p) => p.integrationKey === integrationKey) ?? null;
+    }
+    buildRetryPolicy() {
+        return {
+            maxAttempts: clampInt(this.config.prePassMaxAttemptsPerIntegration, 1, 5, 3),
+            backoffMs: Array.isArray(this.config.prePassBackoffMs)
+                ? this.config.prePassBackoffMs
+                : [1000, 2000, 4000],
+            perIntegrationBudgetUsd: nonNegativeNumber(this.config.prePassMaxBudgetUsdPerIntegration, 0.6),
+            retryOnPartial: this.config.prePassRetryOnPartial !== false,
+        };
+    }
+    fanOutConcurrency() {
+        const configured = this.config.prePassFanOutConcurrency;
+        if (configured === null || configured === undefined)
+            return null;
+        // Cap at the integration roster size — fan-out spawns at most one
+        // sub-session per IntegrationKey, so a higher concurrency cannot
+        // help and a hardcoded literal would silently restrict whenever a
+        // new integration descriptor is added to `INTEGRATION_KEYS`.
+        return clampInt(configured, 1, INTEGRATION_KEYS.length, INTEGRATION_KEYS.length);
+    }
+    retryEscalationTier() {
+        const configured = this.config.prePassRetryEscalationTier;
+        return configured === "lite" || configured === "medium" || configured === "high"
+            ? configured
+            : null;
+    }
+    async runFanOut(input) {
+        const policy = this.buildRetryPolicy();
+        const globalBudget = new FanOutBudgetGuard(nonNegativeNumber(this.config.prePassMaxBudgetUsdPerRoutine, 1.5));
+        const tasks = input.subPlans.map((subPlan) => async () => this.runOneIntegrationWithRetry({
+            ...input,
+            subPlan,
+            policy,
+            globalBudget,
+        }));
+        const subReports = await runWithConcurrency(tasks, this.fanOutConcurrency());
+        const merged = mergeSubReports(subReports, input.key, input.agentDay);
+        // §7.1 example shape — `integrations: [{key, status, attempts, fetched,
+        // posted, duplicates, durationMs, costUsd, finalError?}]` plus an
+        // `aggregate` headline. Reuse the helpers so the SSE
+        // `prepass_completed` payload (in `run()` below) and this log line
+        // never disagree on the per-integration numbers.
+        const integrations = subReports.map(summarizeIntegrationReport);
+        logger.info({
+            routine: input.key,
+            parentCorrelationId: input.parentEvent.correlationId,
+            integrations,
+            aggregate: {
+                ...summarizeFetchReport(merged.report),
+                // Use the live `globalBudget.spent` counter here so the daemon
+                // log line is the canonical readout for "what the global cap
+                // saw" — the §7.2 SSE payload mirrors `summarizeFetchReport`'s
+                // sum-over-attempts. Today the two converge (every committed
+                // cost is also reflected in an attempt's `costUsd`), but tying
+                // the log line to the guard means a future divergence (e.g. a
+                // commit path that bypasses the per-attempt record) surfaces
+                // here instead of going silent.
+                costUsd: globalBudget.spent,
+            },
+        }, "Routine fetch-window fan-out completed");
+        return merged;
+    }
+    async runOneIntegrationWithRetry(input) {
+        const attempts = [];
+        // Per-integration budget cap is enforced at TWO complementary layers,
+        // BOTH driven by `policy.perIntegrationBudgetUsd`:
+        //   (1) `integrationBudget` (this guard) — HARD pre-attempt reservation
+        //       against the binding's `max_budget_usd` envelope. Trips before
+        //       the next SDK call when the upper bound on the next attempt
+        //       would exceed the cap. Surfaces as `{type:"budget-cap"}`.
+        //   (2) `defaultRetryDecision`'s cumulative-cost branch — SOFT
+        //       post-attempt check against actual `costUsd` summed across
+        //       priorAttempts. Surfaces as `decision.reason="per-integration-budget-cap"`.
+        // Layer (1) is the pessimistic guard (envelope ≥ actual); layer (2)
+        // catches the case where individual attempts cost more than expected.
+        // Either fires depending on the cost shape — both are intentional.
+        const integrationBudget = new FanOutBudgetGuard(input.policy.perIntegrationBudgetUsd);
+        const retryOn = input.policy.retryOn ?? defaultRetryDecision;
+        const escalationTier = this.retryEscalationTier();
+        let retriesExhausted = false;
+        for (let attempt = 1; attempt <= input.policy.maxAttempts; attempt++) {
+            const startedAt = new Date().toISOString();
+            const fetcherEvent = this.createFanOutFetcherEvent(input.parentEvent, input.key, input.subPlan, attempt, input.policy.maxAttempts);
+            const requestedTier = attempt > 1 && escalationTier !== null ? escalationTier : undefined;
+            // Symmetry guarantee: every iteration emits exactly one
+            // `prepass_subsession_started` BEFORE any work, and exactly one
+            // `prepass_subsession_completed` after the attempt's outcome is
+            // recorded — including the binding-resolve-failed and budget-cap
+            // short-circuits, which previously were invisible to the dashboard.
+            this.emitSubSessionStarted(input, fetcherEvent.correlationId, attempt);
+            let binding;
+            try {
+                binding = this.agentRouter.resolveBinding(fetcherEvent, {
+                    processKey: FETCH_WINDOW_PROCESS_KEY,
+                    ...(requestedTier ? { requestedTier } : {}),
+                });
+            }
+            catch (err) {
+                const record = this.failedAttemptRecord(attempt, fetcherEvent.correlationId, startedAt, "binding-resolve-failed", err);
+                attempts.push(record);
+                const decision = retryOn(record, attempt, input.policy, attempts.slice(0, -1));
+                this.logFanOutFailure(input, fetcherEvent, record, decision, {
+                    failureKind: "binding-resolve-failed",
+                    err,
+                    startedAt,
+                });
+                this.emitSubSessionCompleted(input, fetcherEvent.correlationId, attempt, record, decision);
+                if (!decision.retry) {
+                    retriesExhausted = this.didExhaustRetries(record, decision, input.policy);
+                    break;
+                }
+                await sleep(this.backoffForAttempt(input.policy, attempt));
+                continue;
+            }
+            // §5 BackendQuotaError row + §4.4 retryEscalationTier — the
+            // pre-pass plan was originally rendered against
+            // `preBinding.main.backendId` (set in `buildFanOutPlanContext`).
+            // If THIS attempt's binding picks a different backend (escalation
+            // tier flipped main, or the resolver picked a different default
+            // for a higher tier), re-derive the per-integration sub-plan
+            // against the current backend so the plan's `<fetch mode="…">`
+            // attributes match the partial body's remaining mode-branch
+            // (`renderPartialForFanOut` filters the partial against the
+            // CURRENT backend; the plan must follow). The recompute uses the
+            // frozen accounts + timestamps from `buildFanOutPlanContext` so
+            // the windows don't drift mid-routine.
+            const livePlan = this.rebuildSubPlanForBackend(input.subPlan.integrationKey, input.key, input.agentDay, binding.main.backendId, input.integrationsSnapshot, input.accounts, input.timestamps);
+            // Native-mode integrations bound to a specific backend can become
+            // unreachable after a cross-backend binding swap (the new backend
+            // has no native connector for this integration). When that
+            // happens, `livePlan` is null — fall back to the original
+            // sub-plan so the agent still iterates the rows and surfaces
+            // `no-surface` errors organically. The retry policy will then
+            // either escalate or short-circuit per the existing matrix.
+            if (livePlan && livePlan.block !== input.subPlan.block) {
+                // Mutate the per-attempt fetcher event so ContextBuilder injects
+                // the freshly-rendered plan block instead of the stale one.
+                // Cheap — the event is a one-shot per attempt.
+                fetcherEvent.data.acquisitionPlanBlock
+                    = livePlan.block;
+            }
+            const estimateUsd = binding.main.maxBudgetUsd;
+            const globalReservation = input.globalBudget.reserve(estimateUsd);
+            if (!globalReservation.ok) {
+                const record = this.budgetCapAttemptRecord(attempt, fetcherEvent.correlationId, startedAt, "global-budget-cap", globalReservation.remaining);
+                attempts.push(record);
+                const decision = {
+                    retry: false,
+                    reason: "global-budget-cap",
+                };
+                this.logFanOutFailure(input, fetcherEvent, record, decision, {
+                    failureKind: "global-budget-cap",
+                    binding: binding.main,
+                    startedAt,
+                });
+                this.emitSubSessionCompleted(input, fetcherEvent.correlationId, attempt, record, decision);
+                retriesExhausted = true;
+                break;
+            }
+            const integrationReservation = integrationBudget.reserve(estimateUsd);
+            if (!integrationReservation.ok) {
+                input.globalBudget.commit(globalReservation, 0);
+                const record = this.budgetCapAttemptRecord(attempt, fetcherEvent.correlationId, startedAt, "budget-cap", integrationReservation.remaining);
+                attempts.push(record);
+                const decision = {
+                    retry: false,
+                    reason: "budget-cap",
+                };
+                this.logFanOutFailure(input, fetcherEvent, record, decision, {
+                    failureKind: "budget-cap",
+                    binding: binding.main,
+                    startedAt,
+                });
+                this.emitSubSessionCompleted(input, fetcherEvent.correlationId, attempt, record, decision);
+                retriesExhausted = true;
+                break;
+            }
+            let context;
+            try {
+                context = await this.contextBuilder.build(fetcherEvent);
+            }
+            catch (err) {
+                input.globalBudget.commit(globalReservation, 0);
+                integrationBudget.commit(integrationReservation, 0);
+                const record = this.failedAttemptRecord(attempt, fetcherEvent.correlationId, startedAt, "context-build-failed", err);
+                attempts.push(record);
+                const decision = retryOn(record, attempt, input.policy, attempts.slice(0, -1));
+                this.logFanOutFailure(input, fetcherEvent, record, decision, {
+                    failureKind: "context-build-failed",
+                    err,
+                    binding: binding.main,
+                    startedAt,
+                });
+                this.emitSubSessionCompleted(input, fetcherEvent.correlationId, attempt, record, decision);
+                if (!decision.retry) {
+                    retriesExhausted = this.didExhaustRetries(record, decision, input.policy);
+                    break;
+                }
+                await sleep(this.backoffForAttempt(input.policy, attempt));
+                continue;
+            }
+            let result = null;
+            let executeErr = undefined;
+            let record;
+            try {
+                const priorAttemptHintBlock = buildPriorAttemptHintBlock(attempts, input.subPlan.integrationKey);
+                // PRE_PASS_FAN_OUT_DESIGN.md §4.2 — every sub-session sees the
+                // `routine.fetch_window` task-flow body with `{integration_partial}`
+                // substituted for the one partial its integrationKey owns. The
+                // integrations snapshot fed to both the partial's mode filter
+                // and the composed allowed-tools list is sliced to a single key
+                // so the sub-session cannot see — or call MCP tools for — any
+                // other integration's surface (defense-in-depth on top of the
+                // prompt isolation).
+                const slicedIntegrations = this.sliceIntegrationSnapshot(input.integrationsSnapshot, input.subPlan.integrationKey);
+                const partialFilename = getIntegrationDescriptor(input.subPlan.integrationKey).prePassPartial;
+                if (!partialFilename) {
+                    throw new Error(`Integration "${input.subPlan.integrationKey}" has no prePassPartial descriptor field — cannot dispatch fan-out sub-session`);
+                }
+                const reassemblePrompt = (bid) => {
+                    const assembled = this.prompt.assemble(FETCH_WINDOW_EVENT_TYPE, FETCH_WINDOW_PROCESS_KEY, bid);
+                    // Re-render the partial against the resolved backend each
+                    // time the SDK reassembles (e.g. on quota-driven fallback).
+                    // Mode markers inside the partial depend on the chosen
+                    // backend, so a cross-backend fallback must regenerate the
+                    // body to match the new MCP surface — matches the failure
+                    // mode catalogue's BackendQuotaError row.
+                    const partialBody = renderPartialForFanOut(partialFilename, slicedIntegrations, bid);
+                    const filled = assembled.replaceAll(FETCH_WINDOW_INTEGRATION_PARTIAL_PLACEHOLDER, partialBody);
+                    return priorAttemptHintBlock
+                        ? `${priorAttemptHintBlock}\n\n${filled}`
+                        : filled;
+                };
+                const prompt = reassemblePrompt(binding.main.backendId);
+                const allowedToolsOverride = composePrePassAllowedTools(this.config.apiPort, slicedIntegrations, binding.main.backendId);
+                result = await this.agentRouter.execute({
+                    prompt,
+                    context,
+                    event: fetcherEvent,
+                    processKey: FETCH_WINDOW_PROCESS_KEY,
+                    preResolvedBinding: binding,
+                    reassemblePrompt,
+                    allowedToolsOverride,
+                });
+                input.globalBudget.commit(globalReservation, result.costUsd);
+                integrationBudget.commit(integrationReservation, result.costUsd);
+                record = this.attemptRecordFromResult(attempt, fetcherEvent, startedAt, result);
+            }
+            catch (err) {
+                input.globalBudget.commit(globalReservation, 0);
+                integrationBudget.commit(integrationReservation, 0);
+                executeErr = err;
+                record = this.failedAttemptRecord(attempt, fetcherEvent.correlationId, startedAt, "agent-execute-failed", err);
+            }
+            attempts.push(record);
+            const decision = retryOn(record, attempt, input.policy, attempts.slice(0, -1));
+            if (result) {
+                this.logFanOutAttempt(input, fetcherEvent, result, record, decision, binding.main.backendId);
+            }
+            else {
+                // §7.1 — when the SDK actually invoked a backend session and
+                // that session threw (timeout, BackendQuotaError, transport
+                // failure, …) the audit feed must reflect it. Successful
+                // attempts log via `logFanOutAttempt` with the AgentResult; the
+                // throw path has no result, so we route through
+                // `logFanOutFailure` which carries the same `detail.prePass`
+                // payload the metrics aggregator filters on (preserving the
+                // failure on `/metrics/pre-pass` alongside the other four
+                // pre-execute failure modes).
+                this.logFanOutFailure(input, fetcherEvent, record, decision, {
+                    failureKind: "agent-execute-failed",
+                    err: executeErr,
+                    binding: binding.main,
+                    startedAt,
+                });
+            }
+            this.emitSubSessionCompleted(input, fetcherEvent.correlationId, attempt, record, decision);
+            if (!decision.retry) {
+                retriesExhausted = this.didExhaustRetries(record, decision, input.policy);
+                break;
+            }
+            await sleep(this.backoffForAttempt(input.policy, attempt));
+        }
+        if (attempts.length === 0) {
+            const now = new Date().toISOString();
+            attempts.push({
+                attempt: 0,
+                status: "skipped",
+                fetched: 0,
+                posted: 0,
+                duplicates: 0,
+                errors: [],
+                fetcherCorrelationId: input.parentEvent.correlationId,
+                startedAt: now,
+                endedAt: now,
+                costUsd: 0,
+                numTurns: 0,
+            });
+        }
+        const final = attempts[attempts.length - 1];
+        const allErrors = attempts.flatMap((att) => att.errors);
+        return {
+            ...final,
+            errors: allErrors.length > 0 ? allErrors : final.errors,
+            integrationKey: input.subPlan.integrationKey,
+            attempts,
+            retriesExhausted,
+        };
+    }
+    /**
+     * Emit `prepass_subsession_started` for an attempt that is about to run.
+     * Called at the TOP of every loop iteration so the started/completed
+     * pair is symmetric across all paths — including binding-resolve-failed
+     * and budget-cap short-circuits, which previously emitted neither.
+     */
+    emitSubSessionStarted(input, fetcherCorrelationId, attempt) {
+        this.broadcastPrepassProgress("prepass_subsession_started", input.parentEvent, {
+            routine: input.key,
+            integrationKey: input.subPlan.integrationKey,
+            attempt,
+            maxAttempts: input.policy.maxAttempts,
+            fetcherCorrelationId,
+            parentCorrelationId: input.parentEvent.correlationId,
+        });
+    }
+    /**
+     * Emit `prepass_subsession_completed` for an attempt that has just
+     * recorded its outcome. Mirror of `emitSubSessionStarted` — invoked
+     * once per iteration after every code path that pushes a record
+     * (success, parse error, agent throw, binding-resolve-failed,
+     * global-budget-cap, per-integration-budget-cap).
+     */
+    emitSubSessionCompleted(input, fetcherCorrelationId, attempt, record, decision) {
+        this.broadcastPrepassProgress("prepass_subsession_completed", input.parentEvent, {
+            routine: input.key,
+            integrationKey: input.subPlan.integrationKey,
+            attempt,
+            maxAttempts: input.policy.maxAttempts,
+            fetcherCorrelationId,
+            parentCorrelationId: input.parentEvent.correlationId,
+            status: record.status,
+            fetched: record.fetched,
+            posted: record.posted,
+            duplicates: record.duplicates,
+            willRetry: decision.retry,
+            retryReason: decision.reason,
+        });
+    }
+    createFanOutFetcherEvent(parentEvent, key, subPlan, attempt, maxAttempts) {
+        return {
+            ...createEvent({
+                type: FETCH_WINDOW_EVENT_TYPE,
+                source: parentEvent.source,
+                priority: EventPriority.NORMAL,
+            }),
+            routine: "fetch_window",
+            data: {
+                acquisitionPlanBlock: subPlan.block,
+                parentRoutine: key,
+                parentCorrelationId: parentEvent.correlationId,
+                prePassFanOut: {
+                    integrationKey: subPlan.integrationKey,
+                    attempt,
+                    maxAttempts,
+                    fetchRowCount: subPlan.fetchRowCount,
+                    rowsHaveAccount: subPlan.rowsHaveAccount,
+                },
+            },
+        };
+    }
+    sliceIntegrationSnapshot(integrations, key) {
+        const state = integrations[key];
+        return state ? { [key]: state } : {};
+    }
+    attemptRecordFromResult(attempt, fetcherEvent, startedAt, result) {
+        const parsed = parseFetchWindowOutput(result.output);
+        const endedAt = new Date().toISOString();
+        if ("parseError" in parsed) {
+            return {
+                attempt,
+                status: "failed",
+                fetched: 0,
+                posted: 0,
+                duplicates: 0,
+                errors: [
+                    {
+                        type: "pre-pass-parse-failed",
+                        reason: parsed.parseError,
+                        attempt,
+                    },
+                ],
+                parseError: parsed.parseError,
+                fetcherCorrelationId: fetcherEvent.correlationId,
+                startedAt,
+                endedAt,
+                costUsd: result.costUsd,
+                numTurns: result.numTurns,
+            };
+        }
+        return {
+            attempt,
+            status: parsed.status,
+            fetched: parsed.fetched,
+            posted: parsed.posted,
+            duplicates: parsed.duplicates,
+            errors: parsed.errors.map((err) => ({ ...err, attempt })),
+            fetcherCorrelationId: fetcherEvent.correlationId,
+            startedAt,
+            endedAt,
+            costUsd: result.costUsd,
+            numTurns: result.numTurns,
+        };
+    }
+    failedAttemptRecord(attempt, fetcherCorrelationId, startedAt, kind, err) {
+        const message = err instanceof Error ? err.message : String(err);
+        const endedAt = new Date().toISOString();
+        return {
+            attempt,
+            status: "failed",
+            fetched: 0,
+            posted: 0,
+            duplicates: 0,
+            errors: [{ type: "pre-pass-failed", kind, message, attempt }],
+            fetcherCorrelationId,
+            startedAt,
+            endedAt,
+            costUsd: 0,
+            numTurns: 0,
+        };
+    }
+    budgetCapAttemptRecord(attempt, fetcherCorrelationId, startedAt, type, remaining) {
+        const endedAt = new Date().toISOString();
+        return {
+            attempt,
+            status: "failed",
+            fetched: 0,
+            posted: 0,
+            duplicates: 0,
+            errors: [{ type, remaining, attempt }],
+            fetcherCorrelationId,
+            startedAt,
+            endedAt,
+            costUsd: 0,
+            numTurns: 0,
+        };
+    }
+    didExhaustRetries(record, decision, policy) {
+        if (record.status === "success" || record.status === "skipped")
+            return false;
+        // FanOutBudgetGuard.reserve() failures surface as explicit error rows
+        // — those are the parallel-reservation cap trips covered by §4.7.
+        if (record.errors.some((err) => err.type === "budget-cap" || err.type === "global-budget-cap")) {
+            return true;
+        }
+        // §4.3 contract: "exhausted maxAttempts (or a budget/global cap tripped)".
+        // The per-integration cumulative-cost cap branch in defaultRetryDecision
+        // returns reason=BUDGET_CAP without leaving a budget-cap error row on
+        // the attempt — without this clause the sub-report would carry
+        // retriesExhausted=false even though the loop terminated on a cap.
+        if (decision.reason === RETRY_REASONS.MAX_ATTEMPTS
+            || decision.reason === RETRY_REASONS.BUDGET_CAP) {
+            return true;
+        }
+        return record.attempt >= policy.maxAttempts;
+    }
+    backoffForAttempt(policy, attempt) {
+        if (attempt >= policy.maxAttempts)
+            return 0;
+        const configured = policy.backoffMs[attempt - 1];
+        if (typeof configured === "number")
+            return Math.max(0, configured);
+        const last = policy.backoffMs[policy.backoffMs.length - 1];
+        return typeof last === "number" ? Math.max(0, last) : 0;
+    }
+    /**
+     * Unified audit-row companion for every fan-out failure mode —
+     * binding-resolve-failed, global-budget-cap, budget-cap (per-integration),
+     * context-build-failed, and agent-execute-failed. Routes through
+     * `audit.logError` (writes `result='failed'`) with a `prePass` payload
+     * so `MetricsCollector.collectPrePassMetrics` can see every failure
+     * mode without a parallel `result='success'` row. Before this helper
+     * existed, the four pre-execute branches wrote nothing at all and the
+     * agent-execute path wrote a `failureKind`-only row that the aggregator
+     * silently skipped (it filters on `detail.prePass` being a non-null
+     * object). Cost / tokens are intentionally NOT supplied — pre-execute
+     * paths have zero cost, the agent-execute throw path has no usable
+     * AgentResult, so any figure here would be a guess; the aggregator
+     * coalesces missing `cost_usd` to 0.
+     */
+    logFanOutFailure(input, fetcherEvent, record, decision, options) {
+        try {
+            const message = options.err instanceof Error
+                ? options.err.message
+                : options.err !== undefined
+                    ? String(options.err)
+                    : options.failureKind;
+            const error = new Error(message);
+            const startMs = Date.parse(options.startedAt);
+            const durationMs = Number.isFinite(startMs)
+                ? Math.max(0, Date.now() - startMs)
+                : undefined;
+            this.audit.logError(fetcherEvent, error, "autonomous", {
+                ...(durationMs !== undefined ? { durationMs } : {}),
+                ...(options.binding ? { backendId: options.binding.backendId } : {}),
+                ...(options.binding ? { modelId: options.binding.modelId } : {}),
+                failureKind: options.failureKind,
+                prePass: {
+                    parentCorrelationId: input.parentEvent.correlationId,
+                    parentRoutine: input.key,
+                    integrationKey: input.subPlan.integrationKey,
+                    attempt: record.attempt,
+                    maxAttempts: input.policy.maxAttempts,
+                    retriedFromAttempt: record.attempt > 1 ? record.attempt - 1 : null,
+                    status: record.status,
+                    fetched: record.fetched,
+                    posted: record.posted,
+                    duplicates: record.duplicates,
+                    errors: record.errors,
+                    willRetry: decision.retry,
+                    retryReason: decision.reason,
+                    ...(options.binding ? { requestedBackend: options.binding.backendId } : {}),
+                },
+            });
+        }
+        catch (logErr) {
+            logger.warn({
+                err: logErr,
+                routine: input.key,
+                integrationKey: input.subPlan.integrationKey,
+                failureKind: options.failureKind,
+                correlationId: fetcherEvent.correlationId,
+            }, "Failed to log routine.fetch_window fan-out failure audit row");
+        }
+    }
+    logFanOutAttempt(input, fetcherEvent, result, record, decision, requestedBackend) {
+        // §5 BackendQuotaError mitigation — set `fallbackTriggered` when the
+        // backend that actually executed differs from the binding the runner
+        // asked for. The audit row's `backend` column carries the ACTUAL
+        // backend (set from `result.backendId` above); `requestedBackend`
+        // surfaces what the runner intended, so the operator can spot
+        // recurring fallbacks by grepping `fallbackTriggered: true` rows
+        // without reconstructing the binding state from the daemon log.
+        const fallbackTriggered = result.backendId !== undefined && result.backendId !== requestedBackend;
+        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 }
+                    : {}),
+                prePass: {
+                    parentCorrelationId: input.parentEvent.correlationId,
+                    // §7.3 metric aggregation — every fan-out audit row carries
+                    // the parent routine key so `/metrics/pre-pass` can group by
+                    // routine without joining back to the parent's row.
+                    parentRoutine: input.key,
+                    integrationKey: input.subPlan.integrationKey,
+                    attempt: record.attempt,
+                    maxAttempts: input.policy.maxAttempts,
+                    // §7.1 example surfaces `retriedFromAttempt`. `null` for the
+                    // first attempt in a sub-session's chain; otherwise the prior
+                    // attempt index. Derivable but cheaper than a cross-row join.
+                    retriedFromAttempt: record.attempt > 1 ? record.attempt - 1 : null,
+                    status: record.status,
+                    fetched: record.fetched,
+                    posted: record.posted,
+                    duplicates: record.duplicates,
+                    errors: record.errors,
+                    willRetry: decision.retry,
+                    retryReason: decision.reason,
+                    ...(fallbackTriggered ? { fallbackTriggered: true } : {}),
+                    requestedBackend,
+                },
+            });
+        }
+        catch (err) {
+            logger.warn({
+                err,
+                routine: input.key,
+                integrationKey: input.subPlan.integrationKey,
+                correlationId: fetcherEvent.correlationId,
+            }, "Failed to log routine.fetch_window fan-out agent_actions row");
+        }
+    }
+    /**
+     * 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;
+    }
+}
+//# sourceMappingURL=routine-fetch-window-runner.js.map