@aitne/daemon 0.1.4 → 0.1.6

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

@@ -1,33 +1,35 @@
 /**
- * `RoutineFetchWindowRunner` — Phase 4 / D1 pre-pass orchestration.
+ * `RoutineFetchWindowRunner` — pre-pass fan-out coordinator.
  *
- * 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:
+ * 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 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).
+ *     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 (Phase 4 D1 + design §11 R5 / OQ4):
+ * 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
@@ -35,27 +37,39 @@
  *    `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.
+ *    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`). The
- *    block surfaces them so the parent prompt can decide whether to
- *    treat its observations view as complete.
+ *    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 { buildAcquisitionPlan, buildAcquisitionTimestamps, } from "./routine-acquisition-plan.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
@@ -66,6 +80,21 @@ const FETCH_WINDOW_EVENT_TYPE = "routine.fetch_window";
  * 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.
  *
@@ -79,16 +108,16 @@ function buildPrePassDaemonRestPatterns(apiPort) {
     return [
         // Observations — the only write surface the pre-pass touches.
         // Catches both POST /api/observations and GET /api/observations*.
-        `Bash(curl ${root}/observations*)`,
+        `Bash(curl *${root}/observations*)`,
         // Direct-mode mail / calendar / notion reads.
-        `Bash(curl ${root}/mail/*)`,
-        `Bash(curl ${root}/calendar/*)`,
-        `Bash(curl ${root}/notion/*)`,
+        `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/*)`,
+        `Bash(curl *${root}/integrations/*)`,
         // Compact-projection helper used by the partials.
         "Bash(jq *)",
     ];
@@ -150,13 +179,32 @@ function collectIntegrationToolsForBackend(integrations, backend) {
  *    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),
-        ...collectIntegrationToolsForBackend(integrations, sessionBackend),
+        ...integrationTools,
+        ...(needsDeferredDiscovery ? ["ToolSearch"] : []),
     ];
 }
 /**
@@ -336,6 +384,304 @@ export function renderFetchReportBlock(report, meta) {
     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;
@@ -345,6 +691,7 @@ export class RoutineFetchWindowRunner {
     audit;
     prompt;
     getActiveMailAccounts;
+    getEventBroadcaster;
     constructor(deps) {
         this.db = deps.db;
         this.config = deps.config;
@@ -353,6 +700,41 @@ export class RoutineFetchWindowRunner {
         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
@@ -366,6 +748,46 @@ export class RoutineFetchWindowRunner {
      * 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) {
@@ -400,71 +822,21 @@ export class RoutineFetchWindowRunner {
             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;
+        let planContext;
         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,
-                },
-            };
+            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. Treat that as a skip — we
-        // don't pay the Haiku cold-start to confirm the agent has nothing
+        // 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 (!fetcherPlanHasFetches(fetcherEvent.data.acquisitionPlanBlock)) {
+        if (planContext.subPlans.length === 0) {
             const report = {
                 status: "skipped",
                 fetched: 0,
@@ -472,68 +844,647 @@ export class RoutineFetchWindowRunner {
                 duplicates: 0,
                 errors: [],
                 skipped: true,
-                fetcherCorrelationId: fetcherEvent.correlationId,
+                fetcherCorrelationId: planContext.placeholder.correlationId,
             };
             const block = renderFetchReportBlock(report, { routine: key, agentDay });
             logger.debug({
                 routine: key,
-                correlationId: fetcherEvent.correlationId,
+                correlationId: planContext.placeholder.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);
+            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, "context-build-failed", err, {
-                fetcherCorrelationId: fetcherEvent.correlationId,
+            return this.fail(key, agentDay, parentEvent, "fan-out-failed", err, {
+                fetcherCorrelationId: planContext.placeholder.correlationId,
             });
         }
-        let binding;
-        try {
-            binding = this.agentRouter.resolveBinding(fetcherEvent, {
-                processKey: FETCH_WINDOW_PROCESS_KEY,
+    }
+    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,
             });
         }
-        catch (err) {
-            return this.fail(key, agentDay, parentEvent, "binding-resolve-failed", err, {
+        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;
         }
-        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;
+        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 {
-            result = await this.agentRouter.execute({
-                prompt,
-                context,
-                event: fetcherEvent,
-                processKey: FETCH_WINDOW_PROCESS_KEY,
-                preResolvedBinding: binding,
-                reassemblePrompt,
-                allowedToolsOverride,
+            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 (err) {
-            return this.fail(key, agentDay, parentEvent, "agent-execute-failed", err, {
-                fetcherCorrelationId: fetcherEvent.correlationId,
-            });
+        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");
         }
-        // Audit row for the fetcher session itself, distinct from the
-        // parent routine's audit row written by the result processor.
+    }
+    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,
@@ -550,48 +1501,39 @@ export class RoutineFetchWindowRunner {
                 ...(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: 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,
+                err,
+                routine: input.key,
+                integrationKey: input.subPlan.integrationKey,
                 correlationId: fetcherEvent.correlationId,
-                parentCorrelationId: parentEvent.correlationId,
-            }, "Routine fetch-window pre-pass output unparsable — parent routine will see <fetch_report status='failed'>");
-            return { report, block };
+            }, "Failed to log routine.fetch_window fan-out agent_actions row");
         }
-        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">`
@@ -646,16 +1588,4 @@ export class RoutineFetchWindowRunner {
         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