@aitne/daemon 0.1.0

package/dist/observers/delegated-sync-worker.js

@@ -0,0 +1,1087 @@
+import { INTEGRATION_DESCRIPTORS, INTEGRATION_WRITE_TTL_MS, getSnapshotNormalizer, nextActiveHoursStart, nowInTimezone, } from "@aitne/shared";
+import { applyDriftEffects, emptyDriftSideEffects, } from "../core/drift-effects.js";
+import { reconcile, } from "../services/integrations/reconcile.js";
+import { defaultModelForTier } from "../core/backends/model-registry.js";
+import { readIntegrations } from "../db/integrations-store.js";
+import { readRuntimeState } from "../db/runtime-state.js";
+import { createLogger } from "../logging.js";
+const logger = createLogger("delegated-sync-worker");
+export const DELEGATED_SYNC_OBSERVER_NAME = "delegated-sync";
+export const DELEGATED_SYNC_PROCESS_KEY = "integration_drift_sync";
+const RUNTIME_CONFIG_KEY = "delegatedSync";
+const DEFAULT_TICK_INTERVAL_SECONDS = 60;
+const DEFAULT_MIN_INTERVAL_SECONDS = 60;
+const CIRCUIT_FAILURE_THRESHOLD = 5;
+const CIRCUIT_BACKOFF_MULTIPLIER = 4;
+/**
+ * Default active-hours window for delegated-sync cadences. Mirrors Hourly
+ * Check defaults (`hourlyCheckActiveStartHour=4`, `hourlyCheckActiveEndHour=24`)
+ * so the two schedules align unless an operator overrides one or the other.
+ * See `docs/design/appendices/delegated-sync-opt-in.md`.
+ *
+ * `endHour` is exclusive: `[start, end)`. `end=24` means "up to but not
+ * including 24:00", i.e. the window covers 23:59:59.
+ */
+const DEFAULT_ACTIVE_START_HOUR = 4;
+const DEFAULT_ACTIVE_END_HOUR = 24;
+/**
+ * Per-cadence retry policy for transient subprocess-side failures.
+ *
+ * Why retry only here: cadence-driven calls (`integration_drift_sync`)
+ * are async, idempotent reads — there is no API caller waiting on the
+ * outcome, and the connector tools used by cadences (calendar listEvents,
+ * gmail search_threads, notion search) are read-only by construction.
+ * Retrying is safe.
+ *
+ * Contrast with the synchronous proxy path (skill code in a Claude Code
+ * / Codex / Gemini session calling `POST /api/delegated/run`): there the
+ * tool may be write-class (gmail send, calendar updateEvent), and the
+ * caller has its own deadline budget. The invoker layer must NOT retry
+ * automatically — this module is the only legitimate place for retry.
+ *
+ * Retryable errorClasses are limited to subprocess-side transients —
+ * `timeout` (idle watchdog or wall-clock fired), `subprocess_crashed`
+ * (exit before paired tool_result), and `tool_not_registered` (Gemini
+ * CLI's MCP tool registry hadn't fully populated when the model's
+ * tool_use was dispatched — observed when the cadence's first tick
+ * fires immediately after an integration switches to `delegated` and
+ * the host extension's MCP server is still completing its handshake).
+ * Auth / parse / wrong_tool / tool_error are deterministic; retrying
+ * them would loop without changing outcome.
+ *
+ * MAX_RETRY_ATTEMPTS=1 (so total = 2 attempts) keeps the per-cadence
+ * worst case inside ~2× the per-call ceiling: 75 s gemini idle + 1.5 s
+ * delay + 75 s gemini idle ≈ 152 s. The cadence-tick mutex (`tickRunning`)
+ * skips overlapping ticks during this window, but the next-cadence
+ * (10–60 min interval) is unaffected.
+ */
+const RETRY_DELAY_MS = 1500;
+const MAX_RETRY_ATTEMPTS = 1;
+const RETRYABLE_ERROR_CLASSES = new Set([
+    "timeout",
+    "subprocess_crashed",
+    "tool_not_registered",
+]);
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+const CALENDAR_IMMINENT_CADENCE = {
+    integration: "google_calendar",
+    windowKey: "primary:imminent",
+    displayName: "Calendar — imminent (next 1 h)",
+    description: "Polls upcoming events in the next hour. Required for the 15-min-before-meeting reminder while calendar is in delegated mode.",
+    defaultIntervalSeconds: 10 * 60,
+    softFloorSeconds: 5 * 60,
+    maxResults: 50,
+    buildWindow: (now) => ({
+        windowMin: new Date(now.getTime() - 15 * 60 * 1000).toISOString(),
+        windowMax: new Date(now.getTime() + 60 * 60 * 1000).toISOString(),
+    }),
+    buildToolCall: (backendId, ctx) => ({
+        toolName: namespacedTool("google_calendar", backendId, calendarListBareTool(backendId)),
+        toolArgs: {
+            calendarId: ctx.calendarId,
+            timeMin: ctx.windowMin,
+            timeMax: ctx.windowMax,
+            maxResults: ctx.maxResults,
+        },
+    }),
+    extractItems: (toolResult) => extractItemsByKeys(toolResult, CALENDAR_ITEM_KEYS),
+};
+const CALENDAR_24H_CADENCE = {
+    integration: "google_calendar",
+    windowKey: "primary:24h",
+    displayName: "Calendar — day-ahead (next 24 h)",
+    description: "Polls the next 24 hours of events. Feeds far-future roadmap-refresh detection.",
+    defaultIntervalSeconds: 60 * 60,
+    softFloorSeconds: 30 * 60,
+    maxResults: 250,
+    buildWindow: (now) => ({
+        windowMin: now.toISOString(),
+        windowMax: new Date(now.getTime() + 24 * 60 * 60 * 1000).toISOString(),
+    }),
+    buildToolCall: CALENDAR_IMMINENT_CADENCE.buildToolCall,
+    extractItems: CALENDAR_IMMINENT_CADENCE.extractItems,
+};
+/**
+ * Gmail `inbox:7d` cadence. Plan §8.2 / §8.3:
+ *   - Default 30 min, soft floor 15 min — gmail polls less often than
+ *     calendar so the operator-tunable cost stays bounded.
+ *   - Window is the last 7 days. Reconcile keys by `(integration,
+ *     window_key)` so the partition is wide enough that a recent thread
+ *     with a fresh reply doesn't drop out and falsely emit `deleted`. The
+ *     LLM hourly check still post-filters to "last hour" inside its own
+ *     decision flow; this cadence's job is structural diff, not selection.
+ *   - `query="newer_than:7d"` Gmail search operator. `pageSize` /
+ *     `max_results` / `maxResults` differs by backend (Claude / Codex /
+ *     Gemini) — `gmailSearchToolCall` per-backend wraps the arg shape.
+ */
+const GMAIL_INBOX_7D_CADENCE = {
+    integration: "gmail",
+    windowKey: "inbox:7d",
+    displayName: "Gmail — inbox (last 7 days)",
+    description: "Polls thread-level changes in the last 7 days of inbox. Surfaces new threads and replies for the hourly check.",
+    defaultIntervalSeconds: 30 * 60,
+    softFloorSeconds: 15 * 60,
+    maxResults: 25,
+    buildWindow: (now) => ({
+        windowMin: new Date(now.getTime() - 7 * 24 * 60 * 60 * 1000).toISOString(),
+        // §5.1 sliding-window: a small forward buffer past `now` keeps a
+        // message whose `internalDate` is exactly `now` from being classified
+        // as out-of-window on the next reconcile.
+        windowMax: new Date(now.getTime() + 60 * 1000).toISOString(),
+    }),
+    buildToolCall: gmailSearchToolCall,
+    extractItems: (toolResult) => extractItemsByKeys(toolResult, GMAIL_ITEM_KEYS),
+};
+/**
+ * Notion `recently_updated` cadence. Plan §8.2 / §8.3:
+ *   - Default 60 min, soft floor 30 min.
+ *   - Notion search has no `last_edited_time` filter (per the hourly
+ *     check's existing footnote on coverage gaps); the cadence pulls a
+ *     `created_date_range` window of the last 7 days as a coarse anchor
+ *     and lets reconcile + the per-page `lastEditedTime` payload + the
+ *     Notion normalizer's `inWindow` predicate sort out true churn.
+ *   - The window's `created_date_range.start_date` arg is per the same
+ *     date format the hourly_check prompt uses (`YYYY-MM-DD`), to mirror
+ *     what the LLM-driven path was already producing — connectors uniformly
+ *     accept that.
+ */
+const NOTION_RECENTLY_UPDATED_CADENCE = {
+    integration: "notion",
+    windowKey: "recently_updated",
+    displayName: "Notion — recently updated",
+    description: "Polls pages updated in the last 7 days. Coarse window; per-page lastEditedTime filters in reconcile.",
+    defaultIntervalSeconds: 60 * 60,
+    softFloorSeconds: 30 * 60,
+    maxResults: 25,
+    buildWindow: (now) => ({
+        windowMin: new Date(now.getTime() - 7 * 24 * 60 * 60 * 1000).toISOString(),
+        windowMax: new Date(now.getTime() + 60 * 1000).toISOString(),
+    }),
+    buildToolCall: notionSearchToolCall,
+    extractItems: (toolResult) => extractItemsByKeys(toolResult, NOTION_ITEM_KEYS),
+};
+const DEFAULT_CADENCES = [
+    CALENDAR_IMMINENT_CADENCE,
+    CALENDAR_24H_CADENCE,
+    GMAIL_INBOX_7D_CADENCE,
+    NOTION_RECENTLY_UPDATED_CADENCE,
+];
+const DEFAULT_CADENCE_INTEGRATIONS = new Set(DEFAULT_CADENCES.map((def) => def.integration));
+export function hasActiveDelegatedSyncIntegration(db, override) {
+    const integrations = readIntegrations(db);
+    if (override)
+        integrations[override.key] = override.state;
+    return Object.entries(integrations).some(([key, state]) => DEFAULT_CADENCE_INTEGRATIONS.has(key)
+        && state.mode === "delegated"
+        && state.delegatedSyncEnabled !== false);
+}
+export class DelegatedSyncWorker {
+    options;
+    name = DELEGATED_SYNC_OBSERVER_NAME;
+    timer = null;
+    tickRunning = false;
+    tickIntervalSeconds;
+    now;
+    cadences;
+    states = new Map();
+    constructor(options) {
+        this.options = options;
+        this.tickIntervalSeconds =
+            options.tickIntervalSeconds ?? DEFAULT_TICK_INTERVAL_SECONDS;
+        this.now = options.now ?? (() => new Date());
+        this.cadences = options.cadences ?? DEFAULT_CADENCES;
+    }
+    async start() {
+        if (this.timer)
+            return;
+        // Register the interval before awaiting the initial tick. Two reasons:
+        //  1. A second concurrent `start()` call hits `if (this.timer) return`
+        //     immediately instead of falling through and double-registering.
+        //  2. If the initial tick throws (e.g. transient DB error during boot),
+        //     subsequent scheduled ticks still fire and recover state, instead
+        //     of leaving the worker permanently silent.
+        this.timer = setInterval(() => void this.tick(), this.tickIntervalSeconds * 1000);
+        this.timer.unref?.();
+        // Phase 7 (h): seed per-cadence state from the most recent successful
+        // delegated_sync row in agent_actions before the first tick. Daemon
+        // restarts no longer re-spawn every cadence's subprocess when a sync
+        // ran shortly before the restart; the natural cadenceDue check picks
+        // up where the last process left off. When no history exists (fresh
+        // install or retention-pruned table), states stay null and the first
+        // tick fires for every cadence — same effect as the prior force-on-
+        // start behaviour, achieved without redundant spawns.
+        this.hydrateStateFromHistory();
+        this.warnOnConfigViolations();
+        try {
+            await this.tick();
+        }
+        catch (err) {
+            logger.warn({ err }, "Initial delegated sync tick failed; cadence-driven retries will continue");
+        }
+        logger.info({ tickIntervalSeconds: this.tickIntervalSeconds }, "Delegated sync worker started");
+    }
+    async stop() {
+        if (this.timer) {
+            clearInterval(this.timer);
+            this.timer = null;
+        }
+        logger.info("Delegated sync worker stopped");
+    }
+    async tick(options = {}) {
+        if (this.tickRunning) {
+            logger.debug("Delegated sync tick already running — skipping overlap");
+            return;
+        }
+        this.tickRunning = true;
+        try {
+            await this.runTick(options.force === true);
+        }
+        finally {
+            this.tickRunning = false;
+        }
+    }
+    getStatus(now = this.now()) {
+        const runtimeConfig = this.readRuntimeConfig();
+        // Resolved up front because per-cadence `nextRunAt` projects past
+        // out-of-window candidates to the next active-hours start.
+        const activeHours = resolveActiveHours(runtimeConfig);
+        const cadences = {};
+        const ttlContractViolations = [];
+        let lastSuccessAt = null;
+        let anyTripped = false;
+        for (const def of this.cadences) {
+            const id = cadenceId(def);
+            const state = this.getState(id);
+            const intervalSeconds = this.resolveIntervalSeconds(def, runtimeConfig);
+            const effectiveIntervalSeconds = computeEffectiveIntervalSeconds(intervalSeconds, state.failureCount);
+            const circuitState = state.failureCount >= CIRCUIT_FAILURE_THRESHOLD
+                ? "tripped"
+                : "ok";
+            if (circuitState === "tripped")
+                anyTripped = true;
+            if (state.lastSuccessAt
+                && (lastSuccessAt === null || state.lastSuccessAt > lastSuccessAt)) {
+                lastSuccessAt = state.lastSuccessAt;
+            }
+            cadences[id] = {
+                integration: def.integration,
+                windowKey: def.windowKey,
+                enabled: isCadenceEnabled(def, runtimeConfig),
+                displayName: def.displayName,
+                description: def.description,
+                defaultIntervalSeconds: def.defaultIntervalSeconds,
+                softFloorSeconds: def.softFloorSeconds,
+                intervalSeconds,
+                effectiveIntervalSeconds,
+                circuitState,
+                failureCount: state.failureCount,
+                lastAttemptAt: state.lastAttemptAt,
+                lastSuccessAt: state.lastSuccessAt,
+                lastCompletedAt: state.lastCompletedAt,
+                lastError: state.lastError,
+                nextRunAt: nextRunAt(state, effectiveIntervalSeconds, now, this.options.timezone, activeHours),
+            };
+            const ttlMs = INTEGRATION_WRITE_TTL_MS[def.integration];
+            const ttlSeconds = Math.floor(ttlMs / 1000);
+            if (intervalSeconds * TTL_CONTRACT_RATIO > ttlSeconds) {
+                ttlContractViolations.push({
+                    cadenceId: id,
+                    intervalSeconds,
+                    ttlSeconds,
+                });
+            }
+        }
+        return {
+            workerRunning: this.timer !== null,
+            lastSuccessAt,
+            circuitState: anyTripped ? "tripped" : "ok",
+            activeHours,
+            withinActiveHours: isWithinActiveHours(now, this.options.timezone, activeHours),
+            cadences,
+            unrecognizedIntervalKeys: collectUnrecognizedIntervalKeys(this.cadences, runtimeConfig),
+            ttlContractViolations,
+        };
+    }
+    /**
+     * Hourly-check-driven refresh: fires any cadence whose integration is in
+     * delegated mode but whose per-cadence opt-in flag (`cadenceEnabled[id]`)
+     * is NOT `true`. Cadences the operator opted in run on their own
+     * user-set interval via the regular tick loop and are intentionally
+     * skipped here so we don't spend tokens twice for the same partition.
+     *
+     * Why this exists: when every cadence is disabled (the post-Phase-9
+     * default), Gmail / Notion observations would otherwise dry up entirely
+     * — the delegated `routine.hourly_check` task flow's Step 0a / 0c rely
+     * on `mail:lifecycle` / `notion:<db>` rows the worker writes server-
+     * side, and the agent prompt is explicitly told NOT to call the
+     * gmail / notion `/reconcile` route directly (would poison the worker's
+     * 7 d partition with a narrow window). This method makes the hourly
+     * check itself the producer for those partitions when the user has not
+     * opted into a per-cadence schedule.
+     *
+     * Active-hours are NOT consulted: this method runs only because the
+     * hourly check itself fired, which already passed `hourlyCheckActive*`
+     * gating. The cadence-side `activeStartHour` / `activeEndHour` window
+     * applies only to the worker's own 60 s tick.
+     *
+     * Cadences run in parallel — they target independent integrations and
+     * connector subprocesses, so wall-clock latency is bounded by the
+     * slowest single cadence rather than the sum. Serialised through the
+     * `tickRunning` mutex so the regular timer tick or a dashboard Run-Now
+     * click landing simultaneously doesn't double-spawn the same connector.
+     * Failures are caught per-cadence inside `runCadence` (failureCount /
+     * circuit-breaker) and surfaced through the next `getStatus()` snapshot;
+     * this method does not throw.
+     */
+    async runDisabledCadencesForHourlyCheck() {
+        if (this.tickRunning) {
+            logger.debug("Skipping hourly-check delegated refresh — worker tick already in flight");
+            return;
+        }
+        this.tickRunning = true;
+        try {
+            const integrations = readIntegrations(this.options.db);
+            const runtimeConfig = this.readRuntimeConfig();
+            const tasks = [];
+            for (const def of this.cadences) {
+                const integrationState = integrations[def.integration];
+                if (integrationState.mode !== "delegated"
+                    || !integrationState.delegatedBackend
+                    || integrationState.delegatedSyncEnabled === false) {
+                    continue;
+                }
+                // Skip cadences the operator opted in — the regular tick handles
+                // those on the user-set interval. The whole point of this method
+                // is to cover the opt-OUT case.
+                if (isCadenceEnabled(def, runtimeConfig))
+                    continue;
+                const normalizer = getSnapshotNormalizer(def.integration);
+                /* c8 ignore next 2 — defensive against descriptor-before-normalizer drift. */
+                if (!normalizer)
+                    continue;
+                tasks.push(this.runCadence(def, normalizer, integrationState.delegatedBackend));
+            }
+            if (tasks.length === 0)
+                return;
+            // `runCadence` swallows its own errors; `allSettled` keeps a future
+            // refactor that lets it throw from poisoning the rest of the batch.
+            await Promise.allSettled(tasks);
+        }
+        finally {
+            this.tickRunning = false;
+        }
+    }
+    /**
+     * Run a single cadence on demand (dashboard "Run Now" button). Bypasses
+     * `cadenceEnabled`, `cadenceDue`, and active-hours gating — the user
+     * explicitly asked for one-shot execution. The integration master switch
+     * (`delegatedSyncEnabled === false`) is still honoured because that's a
+     * kill switch, not a schedule.
+     *
+     * Serialised through `tickRunning` so a Run-Now click during the 60 s
+     * scheduled tick window doesn't double-spawn the same connector
+     * subprocess. Returns a structured failure code rather than throwing so
+     * the dashboard can render the four known reasons cleanly.
+     */
+    async runCadenceNow(cadenceIdInput) {
+        const def = this.cadences.find((d) => cadenceId(d) === cadenceIdInput);
+        if (!def)
+            return { ok: false, error: "unknown_cadence" };
+        if (this.tickRunning)
+            return { ok: false, error: "tick_in_progress" };
+        const integrations = readIntegrations(this.options.db);
+        const integrationState = integrations[def.integration];
+        if (integrationState.mode !== "delegated"
+            || !integrationState.delegatedBackend) {
+            return { ok: false, error: "integration_not_delegated" };
+        }
+        if (integrationState.delegatedSyncEnabled === false) {
+            return { ok: false, error: "integration_disabled" };
+        }
+        const normalizer = getSnapshotNormalizer(def.integration);
+        /* c8 ignore start — every shipped integration registers a normalizer;
+         *   defensive against future descriptor-before-normalizer drift. */
+        if (!normalizer)
+            return { ok: false, error: "integration_not_delegated" };
+        /* c8 ignore stop */
+        this.tickRunning = true;
+        try {
+            await this.runCadence(def, normalizer, integrationState.delegatedBackend);
+            return { ok: true };
+        }
+        finally {
+            this.tickRunning = false;
+        }
+    }
+    async runTick(force) {
+        const integrations = readIntegrations(this.options.db);
+        const runtimeConfig = this.readRuntimeConfig();
+        const now = this.now();
+        // Active-hours gate (delegated-sync-opt-in.md). Outside the window the
+        // entire tick is skipped; cadences don't accrue failureCount or move
+        // their lastAttemptAt clock. `force=true` (test fixtures, future
+        // batch-run paths) bypasses time gating; `runCadenceNow` has its own
+        // bypass via the run-once code path above.
+        if (!force) {
+            const activeHours = resolveActiveHours(runtimeConfig);
+            if (!isWithinActiveHours(now, this.options.timezone, activeHours)) {
+                return;
+            }
+        }
+        for (const def of this.cadences) {
+            const integrationState = integrations[def.integration];
+            if (integrationState.mode !== "delegated"
+                || !integrationState.delegatedBackend
+                || integrationState.delegatedSyncEnabled === false) {
+                continue;
+            }
+            // Per-cadence opt-in (default false). `force=true` bypasses so the
+            // existing test fixtures and any future "run all due cadences now"
+            // call stay simple. The integration master switch above is the kill
+            // switch and is honoured even under `force=true`.
+            if (!force && !isCadenceEnabled(def, runtimeConfig))
+                continue;
+            const normalizer = getSnapshotNormalizer(def.integration);
+            // Defensive: every IntegrationKey ships a normalizer after Phase 5.
+            // The branch survives so a future integration whose connector
+            // wiring lands before its normalizer doesn't crash the worker; the
+            // cadence is silently skipped instead.
+            /* c8 ignore start */
+            if (!normalizer) {
+                logger.debug({ integration: def.integration, windowKey: def.windowKey }, "Skipping delegated sync cadence without a snapshot normalizer");
+                continue;
+            }
+            /* c8 ignore stop */
+            const id = cadenceId(def);
+            const state = this.getState(id);
+            const intervalSeconds = this.resolveIntervalSeconds(def, runtimeConfig);
+            const effectiveSeconds = computeEffectiveIntervalSeconds(intervalSeconds, state.failureCount);
+            if (!force && !cadenceDue(state, effectiveSeconds, now))
+                continue;
+            await this.runCadence(def, normalizer, integrationState.delegatedBackend);
+        }
+    }
+    async runCadence(def, normalizer, backendId) {
+        const id = cadenceId(def);
+        const state = this.getState(id);
+        const startedAt = this.now();
+        state.lastAttemptAt = startedAt.toISOString();
+        let invokeResult = null;
+        let diff = null;
+        let sideEffects = emptyDriftSideEffects();
+        let itemsSeen = 0;
+        let retryAttempts = 0;
+        try {
+            const { windowMin, windowMax } = def.buildWindow(startedAt);
+            const ctx = {
+                windowMin,
+                windowMax,
+                now: startedAt,
+                calendarId: this.options.calendarId,
+                maxResults: def.maxResults,
+            };
+            const { toolName, toolArgs } = def.buildToolCall(backendId, ctx);
+            // Cadence-path model pin. The canonical delegated proxy resolver
+            // returns the lite-tier model (Haiku on Claude); audit log
+            // 2026-05-04 showed the cadence calls timing out at the wall-clock
+            // cap on Haiku — the connector tool sequence (ToolSearch → tool →
+            // response) plus session-dir cold-start was overrunning the 30s
+            // window. Pin the cadence to medium tier (Sonnet on Claude / 2.5-
+            // flash on Gemini) so cadence reliability does not regress when an
+            // operator pins Haiku via `integrations.md` for synchronous skill
+            // calls — those still flow through `delegatedModel` resolution and
+            // are unaffected.
+            const cadenceModelOverride = defaultModelForTier(backendId, "medium");
+            const invokeParams = {
+                integrationKey: def.integration,
+                toolName,
+                toolArgs,
+                parentProcessKey: DELEGATED_SYNC_PROCESS_KEY,
+                modelOverride: cadenceModelOverride,
+            };
+            while (true) {
+                invokeResult = await this.options.invoker.invoke(invokeParams);
+                if (invokeResult.ok)
+                    break;
+                if (retryAttempts >= MAX_RETRY_ATTEMPTS
+                    || !RETRYABLE_ERROR_CLASSES.has(invokeResult.errorClass)) {
+                    break;
+                }
+                retryAttempts += 1;
+                logger.info({
+                    integration: def.integration,
+                    windowKey: def.windowKey,
+                    backendId,
+                    errorClass: invokeResult.errorClass,
+                    attempt: retryAttempts,
+                    maxRetryAttempts: MAX_RETRY_ATTEMPTS,
+                }, "Delegated sync cadence retrying after transient failure");
+                await sleep(RETRY_DELAY_MS);
+            }
+            if (!invokeResult.ok) {
+                throw new Error(invokeResult.message);
+            }
+            const rawItems = def.extractItems(invokeResult.toolResult);
+            itemsSeen = rawItems.length;
+            const items = normalizeItems(rawItems, normalizer);
+            const req = {
+                integration: def.integration,
+                windowKey: def.windowKey,
+                windowMin,
+                windowMax,
+                fetchedAt: startedAt.toISOString(),
+                items,
+            };
+            diff = reconcile(this.options.db, req, {
+                normalizer,
+                onDiffInTransaction: (d) => {
+                    sideEffects = applyDriftEffects(req, d, {
+                        db: this.options.db,
+                        calendarId: this.options.calendarId,
+                        timezone: this.options.timezone,
+                        todayWriteLock: this.options.todayWriteLock,
+                        triggerRoadmapRefresh: this.options.triggerRoadmapRefresh,
+                        // Phase 7: forward the worker's clock so today-drift detection
+                        // is deterministic in tests (the worker uses an injected now()
+                        // for window construction; without this forwarder drift-effects
+                        // would call real `new Date()` and the test would flap across
+                        // UTC midnight when the fixed NOW and the real clock disagree
+                        // on what `today` is).
+                        now: this.now,
+                    });
+                },
+            });
+            const completedAt = this.now();
+            state.lastCompletedAt = completedAt.toISOString();
+            state.lastSuccessAt = completedAt.toISOString();
+            state.failureCount = 0;
+            state.lastError = null;
+            recordDelegatedSyncAction(this.options.db, {
+                def,
+                result: "success",
+                startedAt,
+                completedAt,
+                invokeResult,
+                itemsSeen,
+                diff,
+                sideEffects,
+                error: null,
+                retryAttempts,
+            });
+        }
+        catch (err) {
+            const completedAt = this.now();
+            const message = err instanceof Error ? err.message : String(err);
+            state.lastCompletedAt = completedAt.toISOString();
+            state.failureCount += 1;
+            state.lastError = message;
+            recordDelegatedSyncAction(this.options.db, {
+                def,
+                result: "failed",
+                startedAt,
+                completedAt,
+                invokeResult,
+                itemsSeen,
+                diff,
+                sideEffects,
+                error: message,
+                retryAttempts,
+            });
+            logger.warn({
+                err,
+                integration: def.integration,
+                windowKey: def.windowKey,
+                failureCount: state.failureCount,
+            }, "Delegated sync cadence failed");
+        }
+    }
+    getState(id) {
+        let state = this.states.get(id);
+        if (!state) {
+            state = {
+                lastAttemptAt: null,
+                lastSuccessAt: null,
+                lastCompletedAt: null,
+                failureCount: 0,
+                lastError: null,
+            };
+            this.states.set(id, state);
+        }
+        return state;
+    }
+    readRuntimeConfig() {
+        const raw = readRuntimeState(this.options.db, RUNTIME_CONFIG_KEY);
+        if (!raw || typeof raw !== "object")
+            return {};
+        return raw;
+    }
+    resolveIntervalSeconds(def, runtimeConfig) {
+        const configured = runtimeConfig.intervals?.[cadenceId(def)]
+            ?? runtimeConfig.intervals?.[`${def.integration}.${def.windowKey}`]
+            ?? runtimeConfig.intervals?.[def.windowKey];
+        const floor = Math.max(def.softFloorSeconds, positiveNumber(runtimeConfig.minIntervalSeconds)
+            ?? DEFAULT_MIN_INTERVAL_SECONDS);
+        return Math.max(floor, positiveNumber(configured) ?? def.defaultIntervalSeconds);
+    }
+    /**
+     * Phase 7 (h): rebuild per-cadence `lastAttemptAt` / `lastSuccessAt` from
+     * the most recent `delegated_sync` row in `agent_actions` so a daemon
+     * restart shortly after a successful sync does not re-spawn a subprocess
+     * for that cadence. Idempotent — re-running on an already-warm states
+     * map only overwrites with same-or-newer timestamps. Failures during
+     * hydration log warn and leave the cadence's state empty (which falls
+     * back to "due immediately", matching the prior force-on-start
+     * behaviour).
+     */
+    hydrateStateFromHistory() {
+        for (const def of this.cadences) {
+            try {
+                const row = this.options.db
+                    .prepare(`SELECT started_at AS startedAt, completed_at AS completedAt, result
+             FROM agent_actions
+             WHERE action_type = 'delegated_sync'
+               AND json_extract(detail, '$.integration') = ?
+               AND json_extract(detail, '$.windowKey') = ?
+             ORDER BY started_at DESC
+             LIMIT 1`)
+                    .get(def.integration, def.windowKey);
+                if (!row)
+                    continue;
+                const state = this.getState(cadenceId(def));
+                const startedIso = sqliteDatetimeToIso(row.startedAt);
+                const completedIso = sqliteDatetimeToIso(row.completedAt);
+                if (startedIso)
+                    state.lastAttemptAt = startedIso;
+                if (completedIso)
+                    state.lastCompletedAt = completedIso;
+                if (row.result === "success" && completedIso) {
+                    state.lastSuccessAt = completedIso;
+                }
+                /* c8 ignore start — defensive against a stripped test schema or
+                 *   a corrupted agent_actions row; production always has the
+                 *   table and json_extract returns null for missing keys rather
+                 *   than throwing. The worst case is one redundant subprocess
+                 *   spawn on the first tick, which is the prior force-on-start
+                 *   behaviour. */
+            }
+            catch (err) {
+                logger.warn({ err, integration: def.integration, windowKey: def.windowKey }, "Hydration from agent_actions failed; cadence will tick on first cycle");
+            }
+            /* c8 ignore stop */
+        }
+    }
+    /**
+     * Phase 7 (g) + (c): emit a single warn at start when the operator's
+     * `runtime_state.delegatedSync.intervals` includes typo'd keys or when a
+     * resolved cadence violates the TTL × 1.5 contract. Both checks fire
+     * once per `start()` to avoid log spam; they are also exposed via
+     * `getStatus()` so the dashboard can surface them on-screen.
+     */
+    warnOnConfigViolations() {
+        const runtimeConfig = this.readRuntimeConfig();
+        const unrecognized = collectUnrecognizedIntervalKeys(this.cadences, runtimeConfig);
+        if (unrecognized.length > 0) {
+            logger.warn({ unrecognizedIntervalKeys: unrecognized }, "delegatedSync.intervals contains keys that did not resolve to any known cadence id; configured values are ignored for those keys");
+        }
+        const violations = [];
+        for (const def of this.cadences) {
+            const intervalSeconds = this.resolveIntervalSeconds(def, runtimeConfig);
+            const ttlSeconds = Math.floor(INTEGRATION_WRITE_TTL_MS[def.integration] / 1000);
+            if (intervalSeconds * TTL_CONTRACT_RATIO > ttlSeconds) {
+                violations.push({ cadenceId: cadenceId(def), intervalSeconds, ttlSeconds });
+            }
+        }
+        if (violations.length > 0) {
+            logger.warn({ ttlContractViolations: violations, ttlContractRatio: TTL_CONTRACT_RATIO }, "delegatedSync cadence(s) exceed integration_writes TTL × 1.5; agent-originated writes within these cadences may be re-attributed actor='user' on the next reconcile");
+        }
+    }
+}
+function cadenceId(def) {
+    return `${def.integration}:${def.windowKey}`;
+}
+/**
+ * Per-cadence opt-in check (delegated-sync-opt-in.md). Defaults to `false`
+ * when the operator hasn't set the flag, which means a fresh
+ * `runtime_state.delegatedSync` row keeps every cadence dormant. Canonical
+ * fully-qualified IDs only — the legacy alias forms accepted by `intervals`
+ * are intentionally not honoured here so a future cadence collision cannot
+ * silently flip the wrong toggle.
+ */
+function isCadenceEnabled(def, runtimeConfig) {
+    return runtimeConfig.cadenceEnabled?.[cadenceId(def)] === true;
+}
+/**
+ * Resolve the active-hours window from operator config, falling back to
+ * the Hourly-Check-aligned default. A malformed or out-of-range pair (e.g.
+ * `start >= end`, or numbers outside `[0,24]`) is treated as "use defaults"
+ * — the worker can't usefully interpret an inverted window, and falling
+ * back keeps cadences running rather than silently disabling them.
+ */
+export function resolveActiveHours(runtimeConfig) {
+    const start = runtimeConfig.activeStartHour;
+    const end = runtimeConfig.activeEndHour;
+    if (Number.isInteger(start)
+        && Number.isInteger(end)
+        && start >= 0
+        && start <= 23
+        && end >= 1
+        && end <= 24
+        && start < end) {
+        return { startHour: start, endHour: end };
+    }
+    return {
+        startHour: DEFAULT_ACTIVE_START_HOUR,
+        endHour: DEFAULT_ACTIVE_END_HOUR,
+    };
+}
+/**
+ * `true` when `now` falls inside `[startHour, endHour)` in the daemon's
+ * configured timezone. `endHour=24` is exclusive — i.e. covers up to
+ * 23:59:59. Mirrors the semantics of Hourly Check's window so an operator
+ * who already understands one understands the other.
+ */
+export function isWithinActiveHours(now, timezone, activeHours) {
+    const local = nowInTimezone(timezone, now);
+    return local.hours >= activeHours.startHour && local.hours < activeHours.endHour;
+}
+/**
+ * INTEGRATION-DRIFT-DETECTION-PLAN.md §17.11 — `integration_writes.expires_at`
+ * must outlive the slowest reconcile cadence by ~1.5×, otherwise an
+ * agent-originated write at T0 has its mark expire just before the next
+ * worker tick re-fetches and the diff resolves `actor='user'` instead of
+ * `'agent'`. Phase 7 (c) tightens both halves: the TTL constants
+ * (INTEGRATION_WRITE_TTL_MS, in @aitne/shared) cover the default
+ * cadences with margin, and this ratio is the daemon-side check that fires
+ * a warn when an operator-tuned cadence pushes past the boundary.
+ */
+const TTL_CONTRACT_RATIO = 1.5;
+/**
+ * Build the alias set a runtime-config key may take and check operator-
+ * supplied keys against it. Three accepted forms:
+ *   - canonical fully-qualified (`google_calendar:primary:24h`)
+ *   - dotted human-friendly (`google_calendar.primary:24h`)
+ *   - integration-local (`primary:24h` — only unambiguous when the window
+ *     key is unique across cadences, which the §8.2 default set respects)
+ *
+ * Returns the sorted list of operator keys that match none of the three
+ * forms for any registered cadence. Sorted for stable assertions and
+ * stable health-endpoint output.
+ */
+function collectUnrecognizedIntervalKeys(cadences, runtimeConfig) {
+    if (!runtimeConfig.intervals)
+        return [];
+    const known = new Set();
+    for (const def of cadences) {
+        known.add(cadenceId(def));
+        known.add(`${def.integration}.${def.windowKey}`);
+        known.add(def.windowKey);
+    }
+    const unrecognized = [];
+    for (const key of Object.keys(runtimeConfig.intervals)) {
+        if (!known.has(key))
+            unrecognized.push(key);
+    }
+    return unrecognized.sort();
+}
+/**
+ * `agent_actions` stores `started_at` / `completed_at` as SQLite datetime
+ * (`YYYY-MM-DD HH:MM:SS`). Hydration converts them back to ISO 8601 to
+ * match the in-memory `CadenceRuntimeState` format. Returns `null` for an
+ * unparseable value so a malformed historical row does not poison the
+ * runtime state map.
+ */
+function sqliteDatetimeToIso(value) {
+    if (typeof value !== "string" || value.length === 0)
+        return null;
+    const normalised = value.includes("T") ? value : value.replace(" ", "T");
+    const withZone = /[Zz]|[+-]\d{2}:?\d{2}$/.test(normalised)
+        ? normalised
+        : `${normalised}Z`;
+    const ms = Date.parse(withZone);
+    if (!Number.isFinite(ms))
+        return null;
+    return new Date(ms).toISOString();
+}
+function positiveNumber(value) {
+    return typeof value === "number" && Number.isFinite(value) && value > 0
+        ? value
+        : null;
+}
+function computeEffectiveIntervalSeconds(intervalSeconds, failureCount) {
+    return failureCount >= CIRCUIT_FAILURE_THRESHOLD
+        ? intervalSeconds * CIRCUIT_BACKOFF_MULTIPLIER
+        : intervalSeconds;
+}
+function cadenceDue(state, intervalSeconds, now) {
+    if (!state.lastAttemptAt)
+        return true;
+    const lastAttemptMs = Date.parse(state.lastAttemptAt);
+    if (!Number.isFinite(lastAttemptMs))
+        return true;
+    return now.getTime() - lastAttemptMs >= intervalSeconds * 1000;
+}
+/**
+ * `nextRunAt` projects the next time this cadence is expected to fire.
+ * Computes the interval-based candidate (or `now` for first run / malformed
+ * lastAttemptAt), floors to `now` (never returns a past instant), and then
+ * shifts forward to the next active-hours start when the candidate falls
+ * outside the configured window. Mirrors the worker's actual gating order
+ * (active-hours gate first, then cadenceDue) so the dashboard's "next run
+ * in Xm" matches what the operator will observe.
+ */
+function nextRunAt(state, intervalSeconds, now, timezone, activeHours) {
+    let candidateMs;
+    if (!state.lastAttemptAt) {
+        candidateMs = now.getTime();
+    }
+    else {
+        const lastAttemptMs = Date.parse(state.lastAttemptAt);
+        candidateMs = Number.isFinite(lastAttemptMs)
+            ? lastAttemptMs + intervalSeconds * 1000
+            : now.getTime();
+    }
+    // Floor to `now` — a recurrence due in the past would actually fire on
+    // the next tick, not retroactively. Reporting it as "now" is the most
+    // accurate forward-looking value.
+    const candidate = new Date(Math.max(candidateMs, now.getTime()));
+    return nextActiveHoursStart(candidate, timezone, activeHours.startHour, activeHours.endHour).toISOString();
+}
+/**
+ * Resolve the fully-qualified tool name for `(integration, backendId, bareTool)`.
+ * Throws when the descriptor lacks a connector for the requested backend —
+ * defensive against an integration mode change racing the worker tick (the
+ * caller has already confirmed `delegatedBackend` resolves; this is the
+ * second-line check the descriptor lookup performs anyway).
+ */
+function namespacedTool(integration, backendId, bareTool) {
+    const connector = INTEGRATION_DESCRIPTORS[integration].backendConnectors[backendId];
+    /* c8 ignore next 5 */
+    if (!connector) {
+        throw new Error(`${integration} has no delegated connector for backend '${backendId}'`);
+    }
+    return `${connector.toolNamespace}${bareTool}`;
+}
+function calendarListBareTool(backendId) {
+    return backendId === "claude"
+        ? "list_events"
+        : backendId === "codex"
+            ? "search_events"
+            : "listEvents";
+}
+/**
+ * Per-integration item-array key list. Connectors wrap upstream payloads
+ * differently — `events` for calendar list (Google API native field),
+ * `messages` / `threads` for Gmail search, `results` / `pages` for Notion
+ * search. The cadence-supplied list is what the worker walks via
+ * {@link extractItemsByKeys} when normalising the tool result.
+ */
+const CALENDAR_ITEM_KEYS = ["events", "items", "calendarEvents"];
+const GMAIL_ITEM_KEYS = ["threads", "messages", "items"];
+const NOTION_ITEM_KEYS = ["results", "pages", "items"];
+const SHARED_WRAPPER_KEYS = ["toolResult", "data", "result"];
+function extractItemsByKeys(value, keys) {
+    const items = tryExtractItemsByKeys(value, keys, 0);
+    if (items)
+        return items;
+    throw new Error(`delegated tool result did not contain an item array (looked for ${[...keys, ...SHARED_WRAPPER_KEYS].join(", ")})`);
+}
+function tryExtractItemsByKeys(value, keys, depth) {
+    if (depth > 4)
+        return null;
+    if (Array.isArray(value))
+        return value;
+    if (typeof value === "string") {
+        const trimmed = value.trim();
+        if (trimmed.length === 0)
+            return [];
+        if (trimmed.startsWith("[") || trimmed.startsWith("{")) {
+            try {
+                return tryExtractItemsByKeys(JSON.parse(trimmed), keys, depth + 1);
+            }
+            catch {
+                return null;
+            }
+        }
+        return null;
+    }
+    if (!value || typeof value !== "object")
+        return null;
+    const obj = value;
+    for (const key of [...keys, ...SHARED_WRAPPER_KEYS]) {
+        if (key in obj) {
+            const nested = tryExtractItemsByKeys(obj[key], keys, depth + 1);
+            if (nested)
+                return nested;
+        }
+    }
+    return null;
+}
+/**
+ * Per-backend Gmail search tool call. Each Codex / Claude / Gemini Gmail
+ * connector exposes a slightly different search API; this maps the
+ * cadence's intent (`newer_than:7d`, capped to `maxResults`) onto the
+ * connector's actual parameter names. The tool name resolves through
+ * `INTEGRATION_DESCRIPTORS.gmail.backendConnectors[backendId].toolNamespace`
+ * so namespace drift in the descriptor stays the single source of truth.
+ */
+function gmailSearchToolCall(backendId, ctx) {
+    const query = "newer_than:7d";
+    switch (backendId) {
+        case "claude":
+            return {
+                toolName: namespacedTool("gmail", "claude", "search_threads"),
+                toolArgs: { query, pageSize: ctx.maxResults },
+            };
+        case "codex":
+            return {
+                toolName: namespacedTool("gmail", "codex", "search_emails"),
+                toolArgs: { query, max_results: ctx.maxResults },
+            };
+        case "gemini":
+            return {
+                toolName: namespacedTool("gmail", "gemini", "search"),
+                toolArgs: { query, maxResults: ctx.maxResults },
+            };
+        // Exhaustive switch over the BackendId union; a future backend would
+        // surface here at compile time.
+        /* c8 ignore start */
+        default:
+            throw new Error(`unsupported backend '${backendId}' for gmail`);
+        /* c8 ignore stop */
+    }
+}
+/**
+ * Per-backend Notion search tool call. All three connectors accept the
+ * same shape (`query`, `filters.created_date_range.start_date`, page-size
+ * cap), but the bare tool name differs: Codex strips the `notion-` prefix
+ * (`_search` vs `notion-search`).
+ */
+function notionSearchToolCall(backendId, ctx) {
+    const startDate = isoDate(ctx.windowMin);
+    const args = {
+        query: "updated",
+        filters: { created_date_range: { start_date: startDate } },
+        page_size: ctx.maxResults,
+    };
+    switch (backendId) {
+        case "claude":
+            return { toolName: namespacedTool("notion", "claude", "notion-search"), toolArgs: args };
+        case "codex":
+            return { toolName: namespacedTool("notion", "codex", "search"), toolArgs: args };
+        case "gemini":
+            return { toolName: namespacedTool("notion", "gemini", "notion-search"), toolArgs: args };
+        /* c8 ignore start */
+        default:
+            throw new Error(`unsupported backend '${backendId}' for notion`);
+        /* c8 ignore stop */
+    }
+}
+function isoDate(iso) {
+    // Trim ISO-8601 instant down to YYYY-MM-DD. `Date.parse` is the same
+    // mechanism the validation layer uses; we slice the resulting ISO string
+    // rather than risk a per-locale formatter producing zone-shifted dates.
+    const ms = Date.parse(iso);
+    // windowMin is built by buildWindow above; an unparseable value would
+    // mean the caller corrupted it, which the integration tests would catch
+    // before this branch ever fires.
+    /* c8 ignore start */
+    if (!Number.isFinite(ms)) {
+        throw new Error(`isoDate: cannot parse '${iso}'`);
+    }
+    /* c8 ignore stop */
+    return new Date(ms).toISOString().slice(0, 10);
+}
+function normalizeItems(rawEvents, normalizer) {
+    return rawEvents.map((raw) => {
+        const payload = normalizer.payload(raw);
+        return {
+            itemId: normalizer.itemId(raw),
+            contentHash: normalizer.hash(payload),
+            payload,
+            itemStart: normalizer.itemStart(raw),
+        };
+    });
+}
+function zeroCost() {
+    return {
+        tokensInput: 0,
+        tokensOutput: 0,
+        cacheCreationTokens: 0,
+        cacheReadTokens: 0,
+        costUsd: 0,
+        durationMs: 0,
+        numTurns: 0,
+    };
+}
+function resultCost(result) {
+    if (!result)
+        return zeroCost();
+    if (result.ok)
+        return result.cost;
+    return result.cost ?? zeroCost();
+}
+function recordDelegatedSyncAction(db, args) {
+    const cost = resultCost(args.invokeResult);
+    const detail = {
+        integration: args.def.integration,
+        windowKey: args.def.windowKey,
+        itemsSeen: args.itemsSeen,
+        ...(args.diff
+            ? {
+                created: args.diff.created.length,
+                modified: args.diff.modified.length,
+                deleted: args.diff.deleted.length,
+                unchanged: args.diff.unchanged,
+                prunedOutOfWindow: args.diff.prunedOutOfWindow,
+                isInitialSnapshot: args.diff.isInitialSnapshot,
+            }
+            : {}),
+        sideEffects: args.sideEffects,
+        ...(args.retryAttempts > 0 ? { retryAttempts: args.retryAttempts } : {}),
+        errorClass: args.invokeResult && !args.invokeResult.ok
+            ? args.invokeResult.errorClass
+            : undefined,
+    };
+    try {
+        db.prepare(`INSERT INTO agent_actions (
+         event_id, action_type, trigger, model_used,
+         cost_usd, tokens_input, tokens_output,
+         cache_creation_tokens, cache_read_tokens,
+         duration_ms, num_turns, result, detail,
+         started_at, completed_at, error, backend, cost_source, source_kind
+       ) VALUES (
+         NULL, 'delegated_sync', ?, ?,
+         ?, ?, ?,
+         ?, ?,
+         ?, ?, ?, ?,
+         datetime(?), datetime(?), ?, ?, 'sdk', 'cron'
+       )`).run(DELEGATED_SYNC_PROCESS_KEY, args.invokeResult?.modelId ?? null, cost.costUsd, cost.tokensInput, cost.tokensOutput, cost.cacheCreationTokens, cost.cacheReadTokens, cost.durationMs || Math.max(0, args.completedAt.getTime() - args.startedAt.getTime()), cost.numTurns, args.result, JSON.stringify(detail), args.startedAt.toISOString(), args.completedAt.toISOString(), args.error, args.invokeResult?.backendId ?? null);
+    }
+    catch (err) {
+        logger.error({ err }, "failed to record delegated_sync action");
+    }
+}
+export const __delegatedSyncWorkerTestExports = {
+    calendarListBareTool,
+    namespacedTool,
+    extractItemsByKeys,
+    gmailSearchToolCall,
+    notionSearchToolCall,
+    isoDate,
+    collectUnrecognizedIntervalKeys,
+    sqliteDatetimeToIso,
+    isCadenceEnabled,
+    TTL_CONTRACT_RATIO,
+    CALENDAR_ITEM_KEYS,
+    GMAIL_ITEM_KEYS,
+    NOTION_ITEM_KEYS,
+    CALENDAR_IMMINENT_CADENCE,
+    CALENDAR_24H_CADENCE,
+    GMAIL_INBOX_7D_CADENCE,
+    NOTION_RECENTLY_UPDATED_CADENCE,
+    DEFAULT_ACTIVE_START_HOUR,
+    DEFAULT_ACTIVE_END_HOUR,
+};
+//# sourceMappingURL=delegated-sync-worker.js.map