@aitne/daemon 0.1.7 → 0.1.9

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

@@ -1,7 +1,7 @@
 /**
  * `RoutineFetchWindowRunner` — pre-pass fan-out coordinator.
  *
- * ROUTINE_DATA_ACQUISITION_DESIGN.md §6.1.1 + PRE_PASS_FAN_OUT_DESIGN.md
+ * docs/design/appendices/routine-data-acquisition.md §6.1.1 + docs/design/appendices/pre-pass-fan-out.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:
@@ -29,7 +29,7 @@
  *     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):
+ * Failure-mode contract (docs/design/appendices/pre-pass-fan-out.md §5):
  *
  *  - **No applicable rows** (routine has no windows in `ROUTINE_WINDOWS`,
  *    every integration is disabled, every account list is empty) — the
@@ -52,9 +52,12 @@
 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 { OBSERVATIONS_MCP_TOOL_NAME } from "../services/mcp/sdk-observations-server.js";
+import { ROUTINE_WINDOWS, routineHasWindows, WINDOW_QUERIES, } from "./routine-windows.js";
 import { buildAcquisitionTimestamps, splitAcquisitionPlanByIntegration, } from "./routine-acquisition-plan.js";
 import { RETRY_REASONS, buildPriorAttemptHintBlock, defaultRetryDecision, } from "./routine-fetch-window-retry.js";
+import { writeRuntimeState } from "../db/runtime-state.js";
+import { prePassLastRunRuntimeStateKey } from "./pre-pass-freshness.js";
 import { createLogger } from "../logging.js";
 const logger = createLogger("routine-fetch-window-runner");
 // ── Module helpers ────────────────────────────────────────────────────────
@@ -62,7 +65,7 @@ const logger = createLogger("routine-fetch-window-runner");
 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
+ * docs/design/appendices/pre-pass-fan-out.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
@@ -95,20 +98,44 @@ const FETCH_WINDOW_INTEGRATION_PARTIAL_PLACEHOLDER = "{integration_partial}";
  * remains the host/port/exfil chokepoint; this clamp now restricts only
  * the daemon-API namespace, which is what we actually need.
  *
+ * 2026-05-29: the observations-WRITE curl pattern is omitted ENTIRELY on
+ * the Claude backend (see `buildPrePassDaemonRestPatterns`). Claude posts
+ * via the in-process `mcp__aitne-observations__submit_observations` MCP
+ * tool — structured transport, never shell-parsed — the only path that
+ * survives the SDK's `Ae6` Unicode-whitespace bash preflight that
+ * otherwise denies `curl … -d @-` bodies and cascades to `budget-cap`.
+ * The wildcard rationale above still governs the surviving READ curls
+ * (mail/calendar/notion/integrations) and codex/gemini's write curl.
+ *
  * `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`)
+ * `process_backend_config` envelope (`max_turns=20`, `max_budget_usd=0.50`)
  * remains the floor on those backends.
  */
-function buildPrePassDaemonRestPatterns(apiPort) {
+function buildPrePassDaemonRestPatterns(apiPort, sessionBackend) {
     const root = `http://localhost:${apiPort}/api`;
+    // Observations WRITE surface — the only write the pre-pass performs (GET
+    // reads of pending observations live in the hourly-check session, never
+    // here). For Claude the structured MCP tool
+    // `mcp__aitne-observations__submit_observations` (added by
+    // `composePrePassAllowedTools`) is the ONLY sanctioned write path, so we
+    // deliberately OMIT the curl pattern: a `curl … -d @- <<'JSON'` body whose
+    // calendar titles / mail subjects carry Unicode whitespace (U+3000 in JP
+    // titles, NBSP/ZWS in promo subjects) makes the SDK's `Ae6` bash preflight
+    // mark the command `too-complex` ("Contains Unicode whitespace") and deny
+    // it under dontAsk — which the runner then retries until it trips the
+    // per-integration `budget-cap`. Dropping the curl allow-rule forces Claude
+    // onto the MCP transport (structured JSON, never shell-parsed) and closes
+    // that failure class. codex/gemini have no MCP transport, so they retain
+    // the curl pattern (accepted gap — see `composePrePassAllowedTools`).
+    const observationsWrite = sessionBackend === "claude"
+        ? []
+        : [`Bash(curl *${root}/observations*)`];
     return [
-        // Observations — the only write surface the pre-pass touches.
-        // Catches both POST /api/observations and GET /api/observations*.
-        `Bash(curl *${root}/observations*)`,
+        ...observationsWrite,
         // Direct-mode mail / calendar / notion reads.
         `Bash(curl *${root}/mail/*)`,
         `Bash(curl *${root}/calendar/*)`,
@@ -136,6 +163,57 @@ function buildPrePassDaemonRestPatterns(apiPort) {
  * the partial reaches them through `/api/integrations/<key>/exec`, not
  * via the session backend's MCP namespace.
  */
+/**
+ * Observability helper: list integrations whose `<fetch>` row will spawn
+ * on a backend OTHER than the pre-pass default `sessionBackend`. After
+ * the per-integration backend routing fix (see
+ * `routine-acquisition-plan.ts#resolveIntegrationBackend`), native
+ * bindings whose `nativeBackend !== sessionBackend` are NO LONGER
+ * silently dropped — they spawn on the integration's actual
+ * `nativeBackend` via `BackendRouter.resolveBinding({requestedBackendId})`.
+ * The previous "dropped" semantics is dead; this helper is preserved as
+ * a *cross-backend-spawn* signal so the daemon log surfaces "this
+ * routine fans out across multiple backends" up-front (useful when
+ * debugging Codex / Gemini auth issues that only manifest in pre-pass).
+ *
+ * Routine-scoped: only considers integrations that appear in
+ * `ROUTINE_WINDOWS[routine]` (via WINDOW_QUERIES per window symbol). A
+ * native-mismatched gmail row never surfaces under routine.weekly_review
+ * because weekly_review only touches calendar.
+ *
+ * Returns one entry per affected integration with `{ key, nativeBackend }`.
+ * Pure — pulls only from the integrations snapshot + the routine catalog,
+ * no side effects.
+ */
+function collectCrossBackendNativeIntegrations(routine, integrations, sessionBackend) {
+    // Collect the integrations this routine genuinely touches by walking
+    // its window specs against the WINDOW_QUERIES catalog. Using the
+    // same data sources as `collectFetchRows` in routine-acquisition-plan.ts
+    // keeps the WARN aligned with the actual filter logic.
+    const routineIntegrations = new Set();
+    for (const spec of ROUTINE_WINDOWS[routine]) {
+        const cell = WINDOW_QUERIES[spec.window];
+        if (!cell)
+            continue;
+        for (const key of Object.keys(cell)) {
+            routineIntegrations.add(key);
+        }
+    }
+    const out = [];
+    for (const key of INTEGRATION_KEYS) {
+        if (!routineIntegrations.has(key))
+            continue;
+        const state = integrations[key];
+        if (!state || state.mode !== "native")
+            continue;
+        if (!state.nativeBackend)
+            continue;
+        if (state.nativeBackend === sessionBackend)
+            continue;
+        out.push({ key, nativeBackend: state.nativeBackend });
+    }
+    return out;
+}
 function collectIntegrationToolsForBackend(integrations, backend) {
     const out = new Set();
     for (const key of INTEGRATION_KEYS) {
@@ -201,9 +279,23 @@ function collectIntegrationToolsForBackend(integrations, backend) {
 export function composePrePassAllowedTools(apiPort, integrations, sessionBackend) {
     const integrationTools = collectIntegrationToolsForBackend(integrations, sessionBackend);
     const needsDeferredDiscovery = sessionBackend === "claude" && integrationTools.length > 0;
+    // In-process MCP tool `mcp__aitne-observations__submit_observations` is
+    // the structural fix for the Unicode-whitespace-in-curl-body class of
+    // failures (promotional senders + NBSP/ZWS in mail subjects cause the
+    // SDK's `Ae6` bash preflight to mark the command `too-complex` and
+    // deny it under dontAsk, burning attempts and surfacing budget-cap).
+    // Server is registered in-process by
+    // `ClaudeCodeCore.getObservationsMcpServer`; per-session exposure is
+    // controlled here. Claude-only because the SDK MCP transport is
+    // Claude-specific; codex/gemini pre-pass sessions retain the curl
+    // pattern via `buildPrePassDaemonRestPatterns` and remain at risk of
+    // the same class of denial (accepted gap until those backends gain a
+    // parallel structured channel).
+    const observationsMcpTools = sessionBackend === "claude" ? [OBSERVATIONS_MCP_TOOL_NAME] : [];
     return [
-        ...buildPrePassDaemonRestPatterns(apiPort),
+        ...buildPrePassDaemonRestPatterns(apiPort, sessionBackend),
         ...integrationTools,
+        ...observationsMcpTools,
         ...(needsDeferredDiscovery ? ["ToolSearch"] : []),
     ];
 }
@@ -384,7 +476,7 @@ export function renderFetchReportBlock(report, meta) {
     lines.push("</fetch_report>");
     return lines.join("\n");
 }
-// ── Fan-out aggregation (PRE_PASS_FAN_OUT_DESIGN.md §4.5) ─────────────────
+// ── Fan-out aggregation (docs/design/appendices/pre-pass-fan-out.md §4.5) ─────────────────
 /**
  * Resolve the aggregate `<fetch_report>` status from a set of
  * sub-reports' final statuses, per §4.5:
@@ -742,12 +834,16 @@ export class RoutineFetchWindowRunner {
      * 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).
+     * `routineKey` overrides the auto-derived window key. After the
+     * variant collapse documented in
+     * `docs/design/appendices/morning-routine-optimization.md`,
+     * morning_routine no longer toggles to a separate
+     * `routine.morning_routine_initial` — both branches share the same
+     * window plan. The override seam is kept for callers that already
+     * know the canonical RoutineWindowKey and want to skip the event-
+     * shape derivation.
      */
-    async run(parentEvent, routineKey) {
+    async run(parentEvent, routineKey, options) {
         // 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`
@@ -758,7 +854,7 @@ export class RoutineFetchWindowRunner {
         this.broadcastPrepassProgress("prepass_started", parentEvent);
         let outcome;
         try {
-            outcome = await this.runImpl(parentEvent, routineKey);
+            outcome = await this.runImpl(parentEvent, routineKey, options);
             return outcome;
         }
         finally {
@@ -787,7 +883,7 @@ export class RoutineFetchWindowRunner {
             });
         }
     }
-    async runImpl(parentEvent, routineKey) {
+    async runImpl(parentEvent, routineKey, options) {
         const key = routineKey ?? routineWindowKeyFromEvent(parentEvent);
         const agentDay = getAgentDayDateStr(this.config.timezone || undefined, this.config.dayBoundaryHour);
         if (!key) {
@@ -829,6 +925,18 @@ export class RoutineFetchWindowRunner {
         catch (err) {
             return this.fail(key, agentDay, parentEvent, "plan-assembly-failed", err);
         }
+        // HOURLY_CHECK_GATE_REDESIGN_PLAN.md §3.4 — when the caller is the
+        // hourly_check coordinator, the freshness gate restricts pre-pass to
+        // a subset of integrations. `integrationKeyFilter` is honoured here
+        // (before fan-out) so the runner only spawns sub-sessions for stale
+        // integrations.
+        if (options?.integrationKeyFilter) {
+            const filter = options.integrationKeyFilter;
+            planContext = {
+                ...planContext,
+                subPlans: planContext.subPlans.filter((p) => filter.has(p.integrationKey)),
+            };
+        }
         // 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`
@@ -902,28 +1010,59 @@ export class RoutineFetchWindowRunner {
             accounts,
             timestamps,
         };
+        const subPlans = splitAcquisitionPlanByIntegration(planInput);
+        // Observability: surface integrations whose `<fetch>` row will spawn
+        // on a backend OTHER than the pre-pass default. Per-integration
+        // backend routing (resolveIntegrationBackend +
+        // requestedBackendId) means these rows are NOT dropped — they spawn
+        // on the integration's bound backend via the BackendRouter's
+        // backend-only override path. Logged at `info` so the daemon log
+        // surfaces the cross-backend fan-out shape on every routine, which
+        // is the canonical signal when debugging Codex / Gemini auth issues
+        // that only manifest in the pre-pass (the main routine ran on
+        // claude but gmail-native sub-session is spawning on codex).
+        const crossBackendNativeIntegrations = collectCrossBackendNativeIntegrations(key, integrationsSnapshot, preBinding.main.backendId);
+        if (crossBackendNativeIntegrations.length > 0) {
+            logger.info({
+                routine: key,
+                defaultSessionBackend: preBinding.main.backendId,
+                crossBackendNativeIntegrations,
+                parentCorrelationId: parentEvent.correlationId,
+            }, "Routine fetch-window pre-pass: native bindings will spawn on "
+                + "their bound backend via per-integration backend routing "
+                + "(BackendRouter.requestedBackendId override); the default "
+                + "fetch_window backend will run direct / delegated / "
+                + "same-backend-native rows in parallel.");
+        }
         return {
             key,
             agentDay,
             placeholder,
             integrationsSnapshot,
-            subPlans: splitAcquisitionPlanByIntegration(planInput),
+            subPlans,
             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.
+     * Defensive re-derivation of the per-integration sub-plan against the
+     * CURRENT attempt's binding. With per-integration backend routing in
+     * place, the attempt's binding is pinned to `subPlan.requiredBackend`
+     * via `BackendRouter.resolveBinding({ requestedBackendId })`, so
+     * `binding.main.backendId` always equals the original plan's backend
+     * and the recomputed block is bit-identical to `input.subPlan.block`
+     * in production. The defensive branch is retained for two reasons:
+     *
+     *  1. Regression test coverage — the runner unit test mocks
+     *     `resolveBinding` to return a different backend mid-loop,
+     *     exercising the rebuild mechanics so a future change that
+     *     re-introduces cross-backend swaps (e.g. dropping the
+     *     requestedBackendId pin or extending escalation to also flip
+     *     backends) cannot silently regress plan-vs-partial alignment.
+     *  2. Graceful degradation — returns null when the integration is
+     *     unreachable on the attempted backend; the caller logs the
+     *     original sub-plan and lets the agent emit `no-surface` errors
+     *     organically rather than throwing.
      *
      * Pure: snapshot inputs (`integrationsSnapshot`, `accounts`,
      * `timestamps`) are frozen at run() entry; only `sessionBackend`
@@ -970,12 +1109,51 @@ export class RoutineFetchWindowRunner {
     }
     async runFanOut(input) {
         const policy = this.buildRetryPolicy();
-        const globalBudget = new FanOutBudgetGuard(nonNegativeNumber(this.config.prePassMaxBudgetUsdPerRoutine, 1.5));
+        const preResolvedBindings = new Map();
+        let estimatedTotalUsd = 0;
+        for (const subPlan of input.subPlans) {
+            try {
+                // Use the parentEvent as the resolver event so this pre-resolve
+                // call carries no per-attempt correlationId — the inner loop
+                // creates fresh fetcherEvents for the actual sub-session
+                // execution. Attempt 1 inside `runOneIntegrationWithRetry`
+                // REUSES this binding (skip-inner-resolve) so the net
+                // resolveBinding call count is unchanged: 1 placeholder + N
+                // pre-resolves + 0 attempt-1 inner + K escalation/retry inner.
+                // Without that reuse, every test that asserts a call count
+                // would shift by N.
+                const binding = this.agentRouter.resolveBinding(input.parentEvent, {
+                    processKey: FETCH_WINDOW_PROCESS_KEY,
+                    requestedBackendId: subPlan.requiredBackend,
+                });
+                preResolvedBindings.set(subPlan.integrationKey, binding);
+                estimatedTotalUsd += binding.main.maxBudgetUsd;
+            }
+            catch {
+                preResolvedBindings.set(subPlan.integrationKey, null);
+            }
+        }
+        const configuredGlobalCap = nonNegativeNumber(this.config.prePassMaxBudgetUsdPerRoutine, 1.5);
+        const effectiveGlobalCap = Math.max(configuredGlobalCap, estimatedTotalUsd);
+        if (effectiveGlobalCap > configuredGlobalCap) {
+            logger.warn({
+                routine: input.key,
+                configuredCap: configuredGlobalCap,
+                effectiveCap: effectiveGlobalCap,
+                estimatedTotalUsd,
+                parentCorrelationId: input.parentEvent.correlationId,
+            }, "Routine fetch-window per-routine budget cap raised to floor at "
+                + "sum of binding envelopes — configured cap would block the "
+                + "first attempts. Raise prePassMaxBudgetUsdPerRoutine to "
+                + "silence this warning.");
+        }
+        const globalBudget = new FanOutBudgetGuard(effectiveGlobalCap);
         const tasks = input.subPlans.map((subPlan) => async () => this.runOneIntegrationWithRetry({
             ...input,
             subPlan,
             policy,
             globalBudget,
+            preResolvedBinding: preResolvedBindings.get(subPlan.integrationKey) ?? null,
         }));
         const subReports = await runWithConcurrency(tasks, this.fanOutConcurrency());
         const merged = mergeSubReports(subReports, input.key, input.agentDay);
@@ -1018,8 +1196,21 @@ export class RoutineFetchWindowRunner {
         // 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;
+        //
+        // The cap is floored at the pre-resolved binding's per-attempt
+        // envelope so attempt 1 always fits. Same rationale as the
+        // globalBudget floor in `runFanOut`: a static cap below a single
+        // attempt's envelope (e.g. the 0.6 default vs Codex lite's $1.25)
+        // would dead-lock every integration on attempt 1; the cap is meant
+        // to bound retry runaway, not block the first attempt. The cloned
+        // policy threads the same floor through `defaultRetryDecision`'s
+        // soft cumulative-cost check so the two layers stay aligned.
+        const floorBudget = input.preResolvedBinding?.main.maxBudgetUsd ?? 0;
+        const effectivePolicy = floorBudget > input.policy.perIntegrationBudgetUsd
+            ? { ...input.policy, perIntegrationBudgetUsd: floorBudget }
+            : input.policy;
+        const integrationBudget = new FanOutBudgetGuard(effectivePolicy.perIntegrationBudgetUsd);
+        const retryOn = effectivePolicy.retryOn ?? defaultRetryDecision;
         const escalationTier = this.retryEscalationTier();
         let retriesExhausted = false;
         for (let attempt = 1; attempt <= input.policy.maxAttempts; attempt++) {
@@ -1034,15 +1225,47 @@ export class RoutineFetchWindowRunner {
             this.emitSubSessionStarted(input, fetcherEvent.correlationId, attempt);
             let binding;
             try {
-                binding = this.agentRouter.resolveBinding(fetcherEvent, {
-                    processKey: FETCH_WINDOW_PROCESS_KEY,
-                    ...(requestedTier ? { requestedTier } : {}),
-                });
+                // Per-integration backend routing. `subPlan.requiredBackend`
+                // equals the integration's `nativeBackend` (native), the
+                // `delegatedBackend` for userManagedConnector descriptors, or
+                // the configured fetch_window default backend otherwise.
+                // Passing `requestedBackendId` triggers BackendRouter's
+                // backend-only override branch (added alongside this routing
+                // path), which preserves the `routine.fetch_window` process
+                // tier + envelope while spawning the sub-session on the
+                // integration's actual backend. This is the structural fix for
+                // the pre-existing silent-drop when a `native` binding's
+                // `nativeBackend` differed from the configured fetch_window
+                // backend.
+                //
+                // Fallback is dropped on backend-only override (router
+                // contract); the `routine.fetch_window` seed in db/schema.ts
+                // already ships without a fallback, so the override has no
+                // additional cost in the default deployment.
+                //
+                // Attempt 1 reuses the binding that `runFanOut` pre-resolved to
+                // size the budget guards — same args (no `requestedTier`,
+                // `requestedBackendId=subPlan.requiredBackend`), so resolving
+                // again would just spend an extra router call without changing
+                // the binding. Attempts > 1 resolve fresh so escalation-tier
+                // hints can flip the model. Pre-resolve failures (`null`) fall
+                // through to a fresh attempt-1 resolve, which surfaces the same
+                // `binding-resolve-failed` error path as before.
+                if (attempt === 1 && input.preResolvedBinding) {
+                    binding = input.preResolvedBinding;
+                }
+                else {
+                    binding = this.agentRouter.resolveBinding(fetcherEvent, {
+                        processKey: FETCH_WINDOW_PROCESS_KEY,
+                        ...(requestedTier ? { requestedTier } : {}),
+                        requestedBackendId: input.subPlan.requiredBackend,
+                    });
+                }
             }
             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));
+                const decision = retryOn(record, attempt, effectivePolicy, attempts.slice(0, -1));
                 this.logFanOutFailure(input, fetcherEvent, record, decision, {
                     failureKind: "binding-resolve-failed",
                     err,
@@ -1128,7 +1351,7 @@ export class RoutineFetchWindowRunner {
                 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));
+                const decision = retryOn(record, attempt, effectivePolicy, attempts.slice(0, -1));
                 this.logFanOutFailure(input, fetcherEvent, record, decision, {
                     failureKind: "context-build-failed",
                     err,
@@ -1148,7 +1371,7 @@ export class RoutineFetchWindowRunner {
             let record;
             try {
                 const priorAttemptHintBlock = buildPriorAttemptHintBlock(attempts, input.subPlan.integrationKey);
-                // PRE_PASS_FAN_OUT_DESIGN.md §4.2 — every sub-session sees the
+                // docs/design/appendices/pre-pass-fan-out.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
@@ -1243,6 +1466,30 @@ export class RoutineFetchWindowRunner {
         }
         const final = attempts[attempts.length - 1];
         const allErrors = attempts.flatMap((att) => att.errors);
+        // HOURLY_CHECK_GATE_REDESIGN_PLAN.md §3.4 — record the freshness
+        // timestamp on every successful integration completion. The
+        // coordinator's `harvestForGate` reads this key to suppress
+        // redundant pre-pass spawns within the configured freshness window
+        // (default 30 min). Shared across morning_routine / hourly_check /
+        // evening_review / weekly_review / today_refresh by construction:
+        // the runner has no notion of parent routine.
+        //
+        // `success` only. `partial` and `failed` do NOT update the key so a
+        // partial fetch does not suppress the next tick's retry — the gate
+        // gets a fresh shot. `skipped` (no work to do) is also excluded;
+        // there is no fetched data backing the timestamp.
+        if (final.status === "success") {
+            try {
+                writeRuntimeState(this.db, prePassLastRunRuntimeStateKey(input.subPlan.integrationKey), new Date().toISOString());
+            }
+            catch (err) {
+                logger.warn({
+                    err,
+                    routine: input.key,
+                    integrationKey: input.subPlan.integrationKey,
+                }, "Failed to persist pre_pass_last_run runtime_state; freshness gate degraded");
+            }
+        }
         return {
             ...final,
             errors: allErrors.length > 0 ? allErrors : final.errors,
@@ -1588,4 +1835,3 @@ export class RoutineFetchWindowRunner {
         return rows;
     }
 }
-//# sourceMappingURL=routine-fetch-window-runner.js.map

package/dist/core/routine-windows.d.ts

@@ -1,16 +1,12 @@
 /**
  * Routine data-acquisition window catalog.
  *
- * ROUTINE_DATA_ACQUISITION_DESIGN.md §6.5 — declarative map keyed by
+ * docs/design/appendices/routine-data-acquisition.md §6.5 — declarative map keyed by
  * `(routine, window-symbol, integration, mode)` that the pre-pass
  * fetcher (`routine.fetch_window`) and its assembly helper (§6.4)
  * consult to build the `<acquisition-plan>` block.
  *
- * Phase 1 ships the catalog only. The dispatcher hooks that consume it
- * land in Phase 4; the partials that use the `WINDOW_QUERIES` strings
- * land in Phase 2.
- *
- * Design invariants preserved here:
+ * Design invariants:
  *
  *  - **No model IDs.** Routine windows describe *what to fetch*; tier
  *    binding for `routine.fetch_window` lives in
@@ -40,19 +36,20 @@ export type WindowKind = "mail" | "calendar" | "notion";
  * cascades into every partial and every prompt-assembly call site, so
  * treat additions as additive.
  */
-export declare const WINDOW_SYMBOLS: readonly ["inbox_today", "unread_last_hour", "today_outcomes", "cal_next_24h_drift", "cal_past_7d", "imminent_2h", "cal_morning_7d", "updated_24h", "updated_1h"];
+export declare const WINDOW_SYMBOLS: readonly ["inbox_today", "unread_last_hour", "today_outcomes", "cal_next_24h_drift", "cal_iso_week_to_now", "imminent_2h", "cal_morning_7d", "updated_24h", "updated_1h"];
 export type WindowSymbol = (typeof WINDOW_SYMBOLS)[number];
 /**
  * Routine ProcessKeys that the pre-pass fetcher can be dispatched for.
  * Kept narrow on purpose: only routines that need external data
  * acquisition appear here.
  *
- * `routine.morning_routine_initial` shares the morning plan because its
- * deep first-run prose still wants the same external context; the
- * dispatcher reuses the `morning_routine` plan via the alias below
- * rather than introducing a duplicate entry.
+ * `routine.morning_routine_initial` was retired by
+ * `docs/design/appendices/morning-routine-optimization.md`. Both the
+ * recurring and first-run branches now flow through
+ * `routine.morning_routine`; the daemon-prepared `<roadmap_skeleton>`
+ * block (not a window fetch) handles the first-run roadmap populate.
  */
-export declare const ROUTINE_WINDOW_KEYS: readonly ["routine.morning_routine", "routine.morning_routine_initial", "routine.today_refresh", "routine.hourly_check", "routine.evening_review", "routine.weekly_review", "routine.monthly_review"];
+export declare const ROUTINE_WINDOW_KEYS: readonly ["routine.morning_routine", "routine.today_refresh", "routine.hourly_check", "routine.evening_review", "routine.weekly_review", "routine.monthly_review"];
 export type RoutineWindowKey = (typeof ROUTINE_WINDOW_KEYS)[number];
 export interface RoutineWindowSpec {
     /** Fetch shape — drives partial selection (mail-acquire vs calendar-acquire vs notion-acquire). */
@@ -112,8 +109,10 @@ export interface RoutineWindowSpec {
  *    so no calendar row here. Mail `today_outcomes` is the "what did I
  *    send / reply today" retrospective signal.
  *  - `weekly_review`: ContextBuilder covers `<calendar_events_7d>`
- *    forward. The pre-pass adds the retrospective `cal_past_7d` so the
- *    weekly note has both directions.
+ *    forward. The pre-pass adds the retrospective `cal_iso_week_to_now`
+ *    so the weekly note has both directions, and the retrospective is
+ *    anchored at the same ISO-week boundary the `daily/*.md` archive
+ *    keys on (Monday 00:00 local through `now`).
  *  - `monthly_review`: ContextBuilder covers `<calendar_events_30d>`;
  *    monthly signals already flow through daily journals. The
  *    monthly review is summative — no pre-pass rows.
@@ -137,15 +136,15 @@ export declare const ROUTINE_WINDOWS: Readonly<Record<RoutineWindowKey, readonly
  *  - `{day_plus_2h}`     — `{now_iso}` + 2h
  *  - `{hour_start_iso}`  — current hour boundary
  *  - `{now_iso}`         — current instant
- *  - `{week_start_iso}`  — 7 days before `{day_start_iso}`
+ *  - `{iso_week_start_iso}` — current ISO week Monday 00:00 local in UTC
  *  - `{week_end_iso}`    — 7 days after `{day_start_iso}`
  *  - `{month_end_iso}`   — 30 days after `{day_start_iso}`
  *
  *  Date-only (`YYYY-MM-DD`) — used by `/api/calendar/events` and
  *  `/api/calendar/outlook/events`, which take `date=` + `days=`:
- *  - `{day_start_date}`  — agent-day start as `YYYY-MM-DD`
- *  - `{week_start_date}` — 7 days before agent-day start
- *  - `{now_date}`        — today's calendar date
+ *  - `{day_start_date}`     — agent-day start as `YYYY-MM-DD`
+ *  - `{iso_week_start_date}` — current ISO week Monday in local time
+ *  - `{now_date}`           — today's calendar date
  *
  * Missing-cell semantics: if `WINDOW_QUERIES[symbol]?.[integration]?
  * .[mode]` returns `undefined`, the acquisition-plan assembly helper
@@ -168,4 +167,3 @@ export declare function lookupWindowQuery(symbol: WindowSymbol, integration: Int
  * covered by ContextBuilder blocks (today: `monthly_review`).
  */
 export declare function routineHasWindows(key: RoutineWindowKey): boolean;
-//# sourceMappingURL=routine-windows.d.ts.map