@sellable/mcp 0.1.535 → 0.1.536

package/dist/refill-run-loop.js

@@ -1,6 +1,7 @@
 import { SellableApiError } from "./api.js";
+import { dateSelectorMatchesWindow, dateWindowFromPlan, dateWindowFromRunState, dateWindowFromSelector, normalizeRefillDateSelector, refillDateSelectorBody, schedulerSweepTargetDates, selectorFromDateWindow, } from "./refill-date-window.js";
 import { buildRunStateFromLocalHints } from "./tools/evergreen-refill-plan.js";
-import { classifyPaidInmailRefreshReceipt, prepareRowSelectorValue as defaultPrepareRowSelectorValue, refillPrepareRequestHash as defaultRefillPrepareRequestHash, } from "./tools/refill-executors.js";
+import { prepareRowSelectorValue as defaultPrepareRowSelectorValue, refillPrepareRequestHash as defaultRefillPrepareRequestHash, } from "./tools/refill-executors.js";
 const DEFAULT_BUDGETS = {
     maxGateCyclesPerInvocation: 8,
     pollIntervalMs: 15_000,
@@ -19,6 +20,43 @@ const REFILL_DONE_REASONS = new Set([
     "not_an_evergreen_workspace",
     "no_refillable_campaigns",
 ]);
+const SCHEDULER_RUN_ENVELOPE_STATUSES = new Set([
+    "ran",
+    "attached",
+    "backoff",
+    "window_closed_noop",
+    "failed",
+]);
+const SCHEDULER_RUN_RECEIPT_STATUSES = new Set([
+    "ran",
+    "window_closed_noop",
+    "failed",
+]);
+const SCHEDULER_RUN_SKIP_REASONS = [
+    "window_closed",
+    "daily_limit",
+    "cooldown",
+    "sender_gate",
+    "credit_threshold",
+    "billing_blocked",
+    "duplicate_lead",
+    "no_senders",
+    "other",
+];
+const SCHEDULER_RUN_HARD_BLOCK_REASONS = new Set([
+    "billing_blocked",
+    "credit_threshold",
+    "cooldown",
+]);
+const SCHEDULER_RUN_NEXT_ACTIONS = new Set([
+    "refresh_paid_inmail_credits_then_rerun",
+    "wait_for_capacity_or_window",
+    "inspect_sender_mismatch",
+    "no_ready_cells_continue_refill_prep",
+    "scheduled_cells",
+    "investigate_deferred_reasons",
+    "investigate_scheduler_failure",
+]);
 function isRecord(value) {
     return Boolean(value) && typeof value === "object" && !Array.isArray(value);
 }
@@ -40,6 +78,253 @@ function arrayValue(value) {
 function hasBlocker(value, blocker) {
     return isRecord(value) && value.blocker === blocker;
 }
+function schedulerRunSkipReasons(value) {
+    const raw = recordValue(value) ?? {};
+    const normalized = {};
+    for (const reason of SCHEDULER_RUN_SKIP_REASONS) {
+        normalized[reason] = numberValue(raw[reason]) ?? 0;
+    }
+    return normalized;
+}
+function schedulerRunCountMap(value) {
+    const raw = recordValue(value) ?? {};
+    return Object.fromEntries(Object.entries(raw)
+        .map(([key, rawCount]) => [key, numberValue(rawCount) ?? 0])
+        .filter(([, count]) => count > 0)
+        .sort(([left], [right]) => left.localeCompare(right)));
+}
+function schedulerRunNestedCountMap(value) {
+    const raw = recordValue(value) ?? {};
+    return Object.fromEntries(Object.entries(raw)
+        .map(([key, nested]) => [key, schedulerRunCountMap(nested)])
+        .filter(([, nested]) => Object.keys(nested).length > 0)
+        .sort(([left], [right]) => left.localeCompare(right)));
+}
+function dominantSchedulerRunSkipReason(skipReasons) {
+    let dominant = null;
+    let dominantCount = 0;
+    for (const reason of SCHEDULER_RUN_SKIP_REASONS) {
+        const count = skipReasons[reason] ?? 0;
+        if (count > dominantCount) {
+            dominant = reason;
+            dominantCount = count;
+        }
+    }
+    return dominantCount > 0 ? dominant : null;
+}
+function dominantSchedulerRunCountReason(counts) {
+    let dominant = null;
+    let dominantCount = 0;
+    for (const reason of Object.keys(counts).sort()) {
+        const count = counts[reason] ?? 0;
+        if (count > dominantCount) {
+            dominant = reason;
+            dominantCount = count;
+        }
+    }
+    return dominantCount > 0 ? dominant : null;
+}
+function schedulerRunReasonLooksLike(reasons, pattern) {
+    return Object.keys(reasons).some((reason) => (reasons[reason] ?? 0) > 0 && pattern.test(reason));
+}
+function schedulerRunHasReason(reasons, reason) {
+    return (reasons[reason] ?? 0) > 0;
+}
+function schedulerRunRecommendedAction(params) {
+    if (params.rawAction && SCHEDULER_RUN_NEXT_ACTIONS.has(params.rawAction)) {
+        return params.rawAction;
+    }
+    if (schedulerRunReasonLooksLike(params.prefilterReasons, /(credit|paid[_ -]?inmail|stale[_ -]?credit|missing[_ -]?credit)/i) ||
+        schedulerRunHasReason(params.skippedReasons, "credit_threshold") ||
+        schedulerRunHasReason(params.deferredReasons, "credit_threshold")) {
+        return "refresh_paid_inmail_credits_then_rerun";
+    }
+    if (schedulerRunReasonLooksLike(params.prefilterReasons, /sender[_ -]?mismatch/i)) {
+        return "inspect_sender_mismatch";
+    }
+    if (schedulerRunReasonLooksLike(params.prefilterReasons, /(no[_ -]?capacity|capacity|window|daily[_ -]?limit|cooldown)/i) ||
+        schedulerRunHasReason(params.skippedReasons, "window_closed") ||
+        schedulerRunHasReason(params.skippedReasons, "daily_limit") ||
+        schedulerRunHasReason(params.skippedReasons, "cooldown") ||
+        schedulerRunHasReason(params.deferredReasons, "window_closed") ||
+        schedulerRunHasReason(params.deferredReasons, "daily_limit") ||
+        schedulerRunHasReason(params.deferredReasons, "cooldown")) {
+        return "wait_for_capacity_or_window";
+    }
+    if (params.cellsScheduled > 0)
+        return "scheduled_cells";
+    if (params.readyCellsFound === 0)
+        return "no_ready_cells_continue_refill_prep";
+    if (params.cellsConsidered > 0)
+        return "investigate_deferred_reasons";
+    return null;
+}
+function schedulerRunCampaignScopeSummary(value) {
+    const raw = recordValue(value);
+    if (!raw) {
+        return {
+            totalEligibleTables: 0,
+            tablesWithReadyCells: 0,
+            returnedTables: 0,
+            omittedTables: 0,
+            truncated: false,
+            tables: [],
+        };
+    }
+    const rawTables = arrayValue(raw.tables).slice(0, 25);
+    const tables = rawTables
+        .map((entry) => {
+        const table = recordValue(entry);
+        if (!table)
+            return null;
+        const tableId = stringValue(table.tableId);
+        if (!tableId)
+            return null;
+        return {
+            tableId,
+            tableName: stringValue(table.tableName),
+            workspaceId: stringValue(table.workspaceId),
+            campaignOfferId: stringValue(table.campaignOfferId),
+            campaignName: stringValue(table.campaignName),
+            readyCells: numberValue(table.readyCells) ?? 0,
+            readyCellsByType: schedulerRunCountMap(table.readyCellsByType),
+            consideredCells: numberValue(table.consideredCells) ?? 0,
+            consideredCellsByType: schedulerRunCountMap(table.consideredCellsByType),
+            prefilteredCells: numberValue(table.prefilteredCells) ?? 0,
+            prefilterReasons: schedulerRunCountMap(table.prefilterReasons),
+            prefilterReasonsByType: schedulerRunNestedCountMap(table.prefilterReasonsByType),
+        };
+    })
+        .filter((entry) => entry != null);
+    return {
+        totalEligibleTables: numberValue(raw.totalEligibleTables) ?? 0,
+        tablesWithReadyCells: numberValue(raw.tablesWithReadyCells) ?? tables.length,
+        returnedTables: tables.length,
+        omittedTables: numberValue(raw.omittedTables) ?? 0,
+        truncated: booleanValue(raw.truncated) ?? false,
+        tables,
+    };
+}
+function sanitizeSchedulerRunReceipt(raw) {
+    const envelope = recordValue(raw);
+    if (!envelope)
+        return null;
+    const status = stringValue(envelope.status);
+    if (!status || !SCHEDULER_RUN_ENVELOPE_STATUSES.has(status))
+        return null;
+    const retryAfterMs = envelope.retryAfterMs == null ? null : numberValue(envelope.retryAfterMs);
+    if (envelope.retryAfterMs != null && retryAfterMs == null)
+        return null;
+    const receiptInput = envelope.receipt;
+    let receipt = null;
+    let dominantSkipReason = null;
+    let dominantPrefilterReason = null;
+    let dominantDeferredReason = null;
+    let recommendedNextAction = null;
+    if (receiptInput != null) {
+        const rawReceipt = recordValue(receiptInput);
+        if (!rawReceipt)
+            return null;
+        const receiptStatus = stringValue(rawReceipt.status);
+        if (!receiptStatus || !SCHEDULER_RUN_RECEIPT_STATUSES.has(receiptStatus)) {
+            return null;
+        }
+        const cellsConsidered = numberValue(rawReceipt.cellsConsidered);
+        const cellsScheduled = numberValue(rawReceipt.cellsScheduled);
+        const cellsSkipped = numberValue(rawReceipt.cellsSkipped);
+        const cellsDeferred = numberValue(rawReceipt.cellsDeferred);
+        const tablesFilteredForNoCapacity = numberValue(rawReceipt.tablesFilteredForNoCapacity);
+        if (cellsConsidered == null ||
+            cellsScheduled == null ||
+            cellsSkipped == null ||
+            cellsDeferred == null ||
+            tablesFilteredForNoCapacity == null) {
+            return null;
+        }
+        const skipReasons = schedulerRunSkipReasons(rawReceipt.skipReasons);
+        const skippedReasons = rawReceipt.skippedReasons
+            ? schedulerRunSkipReasons(rawReceipt.skippedReasons)
+            : skipReasons;
+        const deferredReasons = rawReceipt.deferredReasons
+            ? schedulerRunSkipReasons(rawReceipt.deferredReasons)
+            : schedulerRunSkipReasons(null);
+        const prefilterReasons = schedulerRunCountMap(rawReceipt.prefilterReasons);
+        const prefilterReasonsByType = schedulerRunNestedCountMap(rawReceipt.prefilterReasonsByType);
+        const readyCellsByType = schedulerRunCountMap(rawReceipt.readyCellsByType);
+        const consideredCellsByType = schedulerRunCountMap(rawReceipt.consideredCellsByType);
+        const prefilteredCellsByType = schedulerRunCountMap(rawReceipt.prefilteredCellsByType);
+        const readyCellsFound = numberValue(rawReceipt.readyCellsFound) ?? cellsConsidered;
+        const prefilteredCells = numberValue(rawReceipt.prefilteredCells) ?? 0;
+        const tablesFilteredForSenderMismatch = numberValue(rawReceipt.tablesFilteredForSenderMismatch) ?? 0;
+        dominantSkipReason = dominantSchedulerRunSkipReason(skipReasons);
+        dominantPrefilterReason =
+            dominantSchedulerRunCountReason(prefilterReasons);
+        dominantDeferredReason =
+            dominantSchedulerRunSkipReason(deferredReasons);
+        recommendedNextAction = schedulerRunRecommendedAction({
+            rawAction: stringValue(rawReceipt.nextAction),
+            readyCellsFound,
+            cellsConsidered,
+            cellsScheduled,
+            prefilterReasons,
+            skippedReasons,
+            deferredReasons,
+        });
+        receipt = {
+            status: receiptStatus,
+            ...(numberValue(rawReceipt.receiptVersion) != null
+                ? { receiptVersion: numberValue(rawReceipt.receiptVersion) }
+                : {}),
+            ...(numberValue(rawReceipt.diagnosticsVersion) != null
+                ? { diagnosticsVersion: numberValue(rawReceipt.diagnosticsVersion) }
+                : {}),
+            readyCellsFound,
+            readyCellsByType,
+            cellsConsidered,
+            consideredCellsByType,
+            cellsScheduled,
+            cellsSkipped,
+            cellsDeferred,
+            prefilteredCells,
+            prefilteredCellsByType,
+            tablesFilteredForNoCapacity,
+            tablesFilteredForSenderMismatch,
+            prefilterReasons,
+            prefilterReasonsByType,
+            skippedReasons,
+            deferredReasons,
+            skipReasons,
+            campaignScopeSummary: schedulerRunCampaignScopeSummary(rawReceipt.campaignScopeSummary),
+            ...(stringValue(rawReceipt.summary)
+                ? { summary: stringValue(rawReceipt.summary) }
+                : {}),
+            ...(recommendedNextAction ? { nextAction: recommendedNextAction } : {}),
+        };
+    }
+    return {
+        status,
+        retryAfterMs,
+        receipt,
+        dominantSkipReason,
+        dominantPrefilterReason,
+        dominantDeferredReason,
+        recommendedNextAction,
+        hardBlocked: (dominantSkipReason != null &&
+            SCHEDULER_RUN_HARD_BLOCK_REASONS.has(dominantSkipReason)) ||
+            (dominantDeferredReason != null &&
+                SCHEDULER_RUN_HARD_BLOCK_REASONS.has(dominantDeferredReason)) ||
+            recommendedNextAction === "refresh_paid_inmail_credits_then_rerun",
+    };
+}
+function schedulerRunReceiptIsFreshZeroScheduled(schedulerRunReceipt) {
+    const status = stringValue(schedulerRunReceipt?.status);
+    const fresh = status === "ran" || status === "window_closed_noop";
+    if (!fresh)
+        return false;
+    const receipt = recordValue(schedulerRunReceipt?.receipt);
+    return (status === "window_closed_noop" ||
+        numberValue(receipt?.cellsScheduled) === 0);
+}
 function isLeaseLost(value) {
     return hasBlocker(value, "lease_lost");
 }
@@ -133,6 +418,41 @@ function mergeRunState(current, updates) {
         ...updates,
     };
 }
+function dateSelectorFromInput(input) {
+    return normalizeRefillDateSelector({
+        targetDate: input.targetDate,
+        untilDate: input.untilDate,
+        horizonSendDays: input.horizonSendDays,
+    });
+}
+function runStateWithDateWindow(runState, dateWindow) {
+    return mergeRunState(runState, { dateWindow });
+}
+function readPlanRequest(input) {
+    return {
+        workspaceId: input.workspaceId,
+        intent: input.intent,
+        senderIds: input.senderIds,
+        runState: input.runState,
+        journal: input.journal,
+        ...refillDateSelectorBody(input.dateSelector),
+    };
+}
+async function readLoopPlan(input, deps, ctx, journal) {
+    return deps.readPlan(readPlanRequest({
+        workspaceId: input.workspaceId,
+        intent: input.intent,
+        senderIds: input.senderIds,
+        runState: ctx.runState,
+        journal,
+        dateSelector: ctx.dateSelector,
+    }));
+}
+function applyPlanDateWindow(ctx, plan) {
+    ctx.dateWindow = dateWindowFromPlan(plan, ctx.dateSelector);
+    ctx.dateSelector = selectorFromDateWindow(ctx.dateWindow);
+    ctx.runState = runStateWithDateWindow(ctx.runState, ctx.dateWindow);
+}
 function normalizeDoneReason(value) {
     const raw = stringValue(value);
     if (!raw)
@@ -386,14 +706,63 @@ async function createJournal(input, deps, runId) {
         return null;
     }
 }
-async function startOrResume(input, deps) {
-    const initialRunState = buildRunStateFromLocalHints(input.workspaceId);
+async function preflightResumeDateWindow(input, deps, requestedSelector) {
+    const requestedWindow = dateWindowFromSelector(requestedSelector);
+    if (!input.resume) {
+        return { ok: true, selector: requestedSelector, window: requestedWindow };
+    }
+    const status = await deps.runClient.refillRunStatus({
+        workspaceId: input.workspaceId,
+        runId: input.resume.runId,
+    });
+    if (hasBlocker(status, "lease_lost")) {
+        return {
+            status: "blocked",
+            blocker: "lease_lost",
+            runId: input.resume.runId,
+            fence: input.resume.fence,
+            guidance: "Refill run lease was lost before resume date-window preflight.",
+        };
+    }
+    const storedWindow = dateWindowFromRunState(recordValue(status)?.runState);
+    const explicitSelector = requestedSelector.source !== "default_scheduler_forward";
+    if (!storedWindow) {
+        if (explicitSelector) {
+            return {
+                status: "blocked",
+                blocker: "date_window_conflict",
+                runId: input.resume.runId,
+                fence: input.resume.fence,
+                guidance: "This legacy refill_sends_v2 run has no stored date window. Resume it without a new date selector or start a new run.",
+                report: { requestedDateWindow: requestedWindow },
+            };
+        }
+        return { ok: true, selector: requestedSelector, window: requestedWindow };
+    }
+    if (explicitSelector && !dateSelectorMatchesWindow(requestedSelector, storedWindow)) {
+        return {
+            status: "blocked",
+            blocker: "date_window_conflict",
+            runId: input.resume.runId,
+            fence: input.resume.fence,
+            guidance: "Resume date selector conflicts with the stored refill run date window.",
+            report: { requestedDateWindow: requestedWindow, storedDateWindow: storedWindow },
+        };
+    }
+    const selector = explicitSelector
+        ? requestedSelector
+        : selectorFromDateWindow(storedWindow);
+    return { ok: true, selector, window: storedWindow };
+}
+async function startOrResume(input, deps, dateWindow) {
+    const initialRunState = runStateWithDateWindow(buildRunStateFromLocalHints(input.workspaceId), dateWindow);
     const started = await deps.runClient.startRefillRunRemote({
         workspaceId: input.workspaceId,
         config: {
             intent: input.intent ?? "auto",
             senderIds: input.senderIds,
             approvalMode: input.approvalMode ?? "approve",
+            dateWindow,
         },
         runState: initialRunState,
         resume: input.resume,
@@ -435,6 +804,8 @@ async function startOrResume(input, deps) {
             laneCooldowns: [],
             passRates: [],
         };
+    const storedDateWindow = dateWindowFromRunState(runState) ?? dateWindow;
+    const storedDateSelector = selectorFromDateWindow(storedDateWindow);
     const journalPath = await createJournal(input, deps, runId);
     const ctx = {
         workspaceId: input.workspaceId,
@@ -447,6 +818,8 @@ async function startOrResume(input, deps) {
         plan: null,
         headAction: null,
         lastFingerprint: null,
+        dateSelector: storedDateSelector,
+        dateWindow: storedDateWindow,
         recoveryPoint: recordValue(result.recoveryPoint),
         gateCycles: 0,
         sleptMs: 0,
@@ -465,45 +838,31 @@ async function startOrResume(input, deps) {
     return ctx;
 }
 async function gateBootstrap(input, deps, ctx) {
-    const plan = await deps.readPlan({
-        workspaceId: input.workspaceId,
-        intent: input.intent,
-        senderIds: input.senderIds,
-        runState: ctx.runState,
-        journal: false,
-    });
+    const plan = await readLoopPlan(input, deps, ctx, false);
+    applyPlanDateWindow(ctx, plan);
     const paidCredit = arrayValue(recordValue(plan.bootstrap)?.paidCredit).filter(isRecord);
     const refreshedSenderIds = new Set(arrayValue(recordValue(ctx.runState.creditTrust)?.senderIds)
         .map((entry) => stringValue(entry))
         .filter((entry) => Boolean(entry)));
-    const attemptedSenderIds = new Set(arrayValue(recordValue(ctx.runState.creditTrust)?.attemptedSenderIds)
-        .map((entry) => stringValue(entry))
-        .filter((entry) => Boolean(entry)));
     const receipts = [];
     for (const entry of paidCredit) {
         const senderId = stringValue(entry.senderId);
         if (!senderId ||
             !entry.plannedJitRefresh ||
-            refreshedSenderIds.has(senderId) ||
-            attemptedSenderIds.has(senderId)) {
+            refreshedSenderIds.has(senderId)) {
             continue;
         }
         const receipt = await deps.executors.refreshPaidInmailCreditsWithRetry(senderId, input.workspaceId);
-        attemptedSenderIds.add(senderId);
-        const classification = classifyPaidInmailRefreshReceipt(receipt.receipt);
-        receipts.push({ senderId, receipt, classification });
-        if (classification.usableCurrentFacts) {
-            refreshedSenderIds.add(senderId);
-        }
+        receipts.push({ senderId, receipt });
+        refreshedSenderIds.add(senderId);
     }
-    const nextRunState = mergeRunState(ctx.runState, {
+    const nextRunState = runStateWithDateWindow(mergeRunState(ctx.runState, {
         creditTrust: {
             refreshedAt: (deps.now?.() ?? new Date()).toISOString(),
             senderIds: [...refreshedSenderIds],
-            attemptedSenderIds: [...attemptedSenderIds],
             receipts,
         },
-    });
+    }), ctx.dateWindow);
     await safeJournalAppend(ctx, deps, deps.journal.renderBootstrapSection({
         summary: "Refill v2 execution bootstrap",
         senderSummary: safeJson(recordValue(plan.bootstrap)?.senders ?? []),
@@ -611,13 +970,8 @@ async function completeTerminal(input, deps, ctx, doneReasonInput, reportInput =
     };
 }
 async function gatePlan(input, deps, ctx) {
-    const plan = await deps.readPlan({
-        workspaceId: input.workspaceId,
-        intent: input.intent,
-        senderIds: input.senderIds,
-        runState: ctx.runState,
-        journal: false,
-    });
+    const plan = await readLoopPlan(input, deps, ctx, false);
+    applyPlanDateWindow(ctx, plan);
     if (plan.blocker === "workspace_access") {
         return {
             status: "blocked",
@@ -720,13 +1074,7 @@ async function verifyRecoveryPoint(input, deps, ctx) {
         stateRevision: stringValue(planned.stateRevision),
         targetShapeRevision: stringValue(planned.targetShapeRevision),
     };
-    const fresh = await deps.readPlan({
-        workspaceId: input.workspaceId,
-        intent: input.intent,
-        senderIds: input.senderIds,
-        runState: ctx.runState,
-        journal: false,
-    });
+    const fresh = await readLoopPlan(input, deps, ctx, false);
     const changed = fingerprintChanged(expected, fingerprintFromPlan(fresh));
     if (changed.length > 0) {
         await deps.runClient.recordRunOutcome({
@@ -988,13 +1336,8 @@ async function verifyPrepareAction(input, deps, ctx, action, budgets) {
 }
 async function verifyReadOnlyWait(input, deps, ctx, budgets, waitKind) {
     for (let poll = 0; poll < budgets.maxPollsPerWait; poll += 1) {
-        const fresh = await deps.readPlan({
-            workspaceId: input.workspaceId,
-            intent: input.intent,
-            senderIds: input.senderIds,
-            runState: ctx.runState,
-            journal: false,
-        });
+        const fresh = await readLoopPlan(input, deps, ctx, false);
+        applyPlanDateWindow(ctx, fresh);
         ctx.plan = fresh;
         const doneReason = doneReasonFromPlan(fresh);
         if (doneReason) {
@@ -1022,49 +1365,55 @@ async function verifySchedulerWait(input, deps, ctx, action, budgets) {
     const enteredAt = stringValue(progress.schedulerWaitEnteredAt) ??
         (deps.now?.() ?? new Date()).toISOString();
     const jitFired = booleanValue(progress.schedulerJitFired) ?? false;
+    let schedulerRunReceipt = recordValue(progress.schedulerRunReceipt) ?? null;
     if (!jitFired) {
         const senderId = actionSenderId(action);
         if (senderId) {
-            const refresh = await deps.executors.refreshPaidInmailCreditsWithRetry(senderId, input.workspaceId);
-            const classification = classifyPaidInmailRefreshReceipt(refresh.receipt);
-            if (!classification.usableCurrentFacts) {
-                return {
-                    status: "blocked",
-                    blocker: "paid_inmail_refresh_failed",
-                    runId: ctx.runId,
-                    fence: ctx.fence,
-                    gate: ctx.gate,
-                    guidance: "Paid InMail credit refresh did not return usable current facts, so scheduler JIT was not requested.",
-                    report: {
-                        senderId,
-                        receiptStatus: classification.status,
-                        error: classification.error,
-                        receipt: refresh.receipt,
-                        attempts: refresh.attempts,
-                        errors: refresh.errors,
-                    },
-                    journalPath: ctx.journalPath,
-                };
-            }
+            await deps.executors.refreshPaidInmailCreditsWithRetry(senderId, input.workspaceId);
         }
         if (deps.requestSchedulerRun) {
-            await deps.requestSchedulerRun(input.workspaceId);
+            try {
+                const targetDates = schedulerSweepTargetDates(ctx.dateWindow);
+                const sweepReceipts = [];
+                if (targetDates.length === 0) {
+                    schedulerRunReceipt = sanitizeSchedulerRunReceipt(await deps.requestSchedulerRun(input.workspaceId));
+                }
+                else {
+                    for (const targetDate of targetDates) {
+                        const receipt = sanitizeSchedulerRunReceipt(await deps.requestSchedulerRun(input.workspaceId, { targetDate }));
+                        if (receipt)
+                            sweepReceipts.push({ targetDate, ...receipt });
+                    }
+                    schedulerRunReceipt = sweepReceipts[0] ?? null;
+                }
+                if (sweepReceipts.length > 1) {
+                    ctx.runState = mergeRunState(ctx.runState, {
+                        progress: mergeProgress(ctx, {
+                            schedulerRunReceipts: sweepReceipts,
+                        }),
+                    });
+                }
+            }
+            catch {
+                schedulerRunReceipt = null;
+            }
         }
         ctx.runState = mergeRunState(ctx.runState, {
             progress: mergeProgress(ctx, {
                 schedulerWaitEnteredAt: enteredAt,
                 schedulerJitFired: true,
+                ...(schedulerRunReceipt ? { schedulerRunReceipt } : {}),
             }),
         });
     }
-    for (let poll = 0; poll < budgets.maxSchedulerReadbacks; poll += 1) {
-        const fresh = await deps.readPlan({
-            workspaceId: input.workspaceId,
-            intent: input.intent,
-            senderIds: input.senderIds,
-            runState: ctx.runState,
-            journal: false,
-        });
+    const zeroScheduledFresh = schedulerRunReceiptIsFreshZeroScheduled(schedulerRunReceipt);
+    // EDGE-2: the on-demand run only executes placement; cron can still process
+    // due/timed-out cells later. We still do one readback, then avoid burning the
+    // full wait budget when the fresh receipt says nothing was placeable now.
+    const readbackBudget = zeroScheduledFresh ? 1 : budgets.maxSchedulerReadbacks;
+    for (let poll = 0; poll < readbackBudget; poll += 1) {
+        const fresh = await readLoopPlan(input, deps, ctx, false);
+        applyPlanDateWindow(ctx, fresh);
         ctx.plan = fresh;
         const doneReason = normalizeDoneReason(doneReasonFromPlan(fresh));
         if (doneReason === "complete" || doneReason === "capped_by_scheduler") {
@@ -1120,13 +1469,8 @@ async function gateVerify(input, deps, ctx, budgets) {
         actionType === "wait_for_source_import") {
         return verifyReadOnlyWait(input, deps, ctx, budgets, actionType);
     }
-    const fresh = await deps.readPlan({
-        workspaceId: input.workspaceId,
-        intent: input.intent,
-        senderIds: input.senderIds,
-        runState: ctx.runState,
-        journal: false,
-    });
+    const fresh = await readLoopPlan(input, deps, ctx, false);
+    applyPlanDateWindow(ctx, fresh);
     ctx.plan = fresh;
     const doneReason = doneReasonFromPlan(fresh);
     if (doneReason) {
@@ -1199,15 +1543,21 @@ export async function runRefillV2Loop(input, deps) {
     let ctx = null;
     try {
         if (input.dryRun) {
-            const plan = await deps.readPlan({
+            const dateSelector = dateSelectorFromInput(input);
+            const plan = await deps.readPlan(readPlanRequest({
                 workspaceId: input.workspaceId,
                 intent: input.intent,
                 senderIds: input.senderIds,
                 journal: true,
-            });
+                dateSelector,
+            }));
             return { status: "dry_run", plan };
         }
-        const started = await startOrResume(input, deps);
+        const requestedSelector = dateSelectorFromInput(input);
+        const preflight = await preflightResumeDateWindow(input, deps, requestedSelector);
+        if ("status" in preflight)
+            return preflight;
+        const started = await startOrResume(input, deps, preflight.window);
         if ("status" in started)
             return started;
         ctx = started;

package/dist/server.js

@@ -45,6 +45,7 @@ import { allTools } from "./tools/registry.js";
 import { getRows, getTableRows, getTableRowsMinimal } from "./tools/rows.js";
 import { addRubricItem, checkRubric, deleteRubricItem, draftRubrics, saveRubrics, selectNecessaryRubrics, updateRubricItem, waitForRubricResults, } from "./tools/rubrics.js";
 import { getSchedulerFillCapacity } from "./tools/scheduler-fill-capacity.js";
+import { runSchedulerSweep } from "./tools/scheduler-run.js";
 import { getSenderRoutingTool, setSenderRoutingTool, } from "./tools/sender-routing.js";
 import { getSender, listSenders, refreshPaidInmailCredits, } from "./tools/senders.js";
 import { attachRecommendedSequence, attachSequence, createWorkflowTable, } from "./tools/sequencer.js";
@@ -235,6 +236,9 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             case "get_scheduler_fill_capacity":
                 result = await getSchedulerFillCapacity(args);
                 break;
+            case "run_scheduler_sweep":
+                result = await runSchedulerSweep(args);
+                break;
             case "refill_sends":
                 result = await executeRefillSendsCommand(args);
                 break;