@sellable/mcp 0.1.520 → 0.1.522

package/dist/tools/refill-executors.d.ts

@@ -5,6 +5,15 @@ export type PaidInmailRefreshAction = {
     actionKey?: string | null;
     action?: Record<string, unknown>;
 };
+export type PaidInmailCreditRefreshOptions = {
+    actionType?: string | null;
+    campaignId?: string | null;
+    tableId?: string | null;
+    columnId?: string | null;
+    threshold?: number | null;
+    maxStalenessSeconds?: number | null;
+    paidInmailCreditsMaxStalenessSeconds?: number | null;
+};
 export type YoloPrimitiveExecution = {
     enabled: true;
     status: "no_action" | "read_only_reread" | "executed_and_reread" | "refused" | "skipped_after_paid_refresh";
@@ -161,7 +170,7 @@ export declare function approveGeneratedMessagesBatch(action: Record<string, unk
     refusalReason?: undefined;
 }>;
 export declare function continueSignalDiscoverySource(action: Record<string, unknown>, workspaceId?: string): Promise<YoloPrimitiveAttempt>;
-export declare function refreshPaidInmailCreditsWithRetry(senderId: string, workspaceId: string): Promise<{
+export declare function refreshPaidInmailCreditsWithRetry(senderId: string, workspaceId: string, options?: PaidInmailCreditRefreshOptions): Promise<{
     receipt: import("./senders.js").RefreshPaidInmailCreditsResponse;
     attempts: number;
     errors: string[];

package/dist/tools/refill-executors.js

@@ -365,6 +365,79 @@ export function refillPrepareRequestHash(params) {
             : "no-row-selector",
     ].join(":");
 }
+function prepReceiptFromResult(result) {
+    const root = recordValue(result);
+    if (!root)
+        return null;
+    const status = recordValue(root.status);
+    const progress = recordValue(root.progress) ?? recordValue(status?.progress);
+    return (recordValue(root.prepReceipt) ??
+        recordValue(progress?.receipt) ??
+        recordValue(root.receipt));
+}
+function normalizePrepareMessagesResult(result) {
+    const receipt = prepReceiptFromResult(result);
+    const root = recordValue(result);
+    if (!receipt || !root)
+        return result;
+    const world = recordValue(receipt.world);
+    const batchStop = stringValue(receipt.batchStop);
+    const brokenByReason = recordValue(world?.brokenByReason) ?? {};
+    const approvalCandidates = numberValue(world?.approvalCandidates) ?? 0;
+    const hasMoreFrontierRows = world?.hasMoreFrontierRows === true;
+    const stuckActiveCells = Array.isArray(world?.stuckActiveCells)
+        ? world.stuckActiveCells
+        : [];
+    const approvedNotDispatched = Array.isArray(world?.approvedNotDispatched)
+        ? world.approvedNotDispatched
+        : [];
+    return {
+        ...root,
+        prepReceipt: receipt,
+        exhaustionEvidence: {
+            clean: batchStop === "frontier_exhausted" &&
+                hasMoreFrontierRows === false &&
+                stuckActiveCells.length === 0 &&
+                approvedNotDispatched.every((entry) => {
+                    const row = recordValue(entry);
+                    return row?.terminal === true || approvedNotDispatched.length === 0;
+                }),
+            batchStop,
+            hasMoreFrontierRows,
+            approvalCandidates,
+            brokenByReason,
+            stuckActiveCells,
+            approvedNotDispatched,
+        },
+    };
+}
+function waitReceiptFromAction(action) {
+    const toolInput = actionToolInput(action);
+    const wait = recordValue(toolInput.wait) ??
+        recordValue(action.wait) ??
+        recordValue(recordValue(toolInput.refillReceipt)?.wait);
+    if (!wait)
+        return null;
+    const deadlineAt = stringValue(wait.deadlineAt);
+    const onExpiry = stringValue(wait.onExpiry);
+    if (!deadlineAt || !onExpiry)
+        return null;
+    return { deadlineAt, onExpiry };
+}
+function waitResultForAction(action) {
+    const wait = waitReceiptFromAction(action);
+    if (!wait)
+        return { waited: true };
+    const deadlineMs = Date.parse(wait.deadlineAt);
+    if (Number.isFinite(deadlineMs) && deadlineMs <= Date.now()) {
+        return {
+            waited: false,
+            reason: "wait_deadline_expired",
+            wait,
+        };
+    }
+    return { waited: true, wait };
+}
 export function boundedApprovalLimit(action) {
     const toolInput = actionToolInput(action);
     const rowSelector = recordValue(toolInput.rowSelector);
@@ -545,13 +618,14 @@ export async function continueSignalDiscoverySource(action, workspaceId) {
         },
     };
 }
-export async function refreshPaidInmailCreditsWithRetry(senderId, workspaceId) {
+export async function refreshPaidInmailCreditsWithRetry(senderId, workspaceId, options = {}) {
     const errors = [];
     for (let attempt = 1; attempt <= PAID_INMAIL_REFRESH_MAX_ATTEMPTS; attempt += 1) {
         try {
             const receipt = await refreshPaidInmailCredits({
                 senderId,
                 workspaceId,
+                ...options,
             });
             return { receipt, attempts: attempt, errors };
         }
@@ -673,7 +747,7 @@ export async function executeOneYoloPrimitive(action, workspaceId) {
         case "wait_for_scheduler":
         case "wait_for_active_work":
         case "wait_for_source_import":
-            return { status: "read_only_reread", result: { waited: true } };
+            return { status: "read_only_reread", result: waitResultForAction(action) };
         case "prepare_messages": {
             const campaignId = actionCampaignId(action);
             const tableId = actionTableId(action) ?? undefined;
@@ -712,7 +786,10 @@ export async function executeOneYoloPrimitive(action, workspaceId) {
                 }),
                 requestSource: "refill_sends",
             });
-            return { status: "executed_and_reread", result };
+            return {
+                status: "executed_and_reread",
+                result: normalizePrepareMessagesResult(result),
+            };
         }
         case "copy_selected_source_rows": {
             const campaignOfferId = actionCampaignId(action);

package/dist/tools/refill-sends.js

@@ -2,6 +2,7 @@ import { actionIds, collectPaidInmailRefreshActions, executeOneYoloPrimitive, fi
 import { getRefillTargetPlan } from "./refill-target-plan.js";
 import { createWorkspaceContext, normalizeExplicitWorkspaceId, } from "./workspace-context.js";
 const DEFAULT_SCHEDULER_FORWARD_HOURS = 48;
+const MCP_PAID_INMAIL_CREDITS_MAX_STALENESS_SECONDS = 4 * 60 * 60;
 function normalizeHorizonSendDays(value) {
     if (value === undefined || value === null)
         return null;
@@ -50,7 +51,7 @@ function normalizeTargetDate(value) {
 export const refillSendsToolDefinitions = [
     {
         name: "refill_sends",
-        description: "Typed command entrypoint for Sellable refill sends. Accepts --yolo semantics and optional sender selectors, then returns the bounded execution contract for the skill-led refill workflow. In --yolo, it may refresh stale paid InMail credit cache facts once, or execute exactly one safe primitive from target.globalActionQueue[0] (bounded existing-row preparation, bounded same-source copy, bounded generated-message approval, or read-only wait) and reread. It does not run unbounded approval, lower paid InMail thresholds, switch source families, create campaigns, schedule sends, launch, archive, delete, or write scheduler rows.",
+        description: "Typed command entrypoint for Sellable refill sends. Accepts --yolo semantics and optional sender selectors, then returns the bounded execution contract for the skill-led refill workflow. In --yolo, it may refresh stale paid InMail credit cache facts once, or execute exactly one safe primitive from target.globalActionQueue[0] (bounded existing-row preparation, bounded generated-message approval, receipt-proven same-source copy, or read-only wait) and reread. Same-source copy/source fallback is only safe after receipt-proven exhaustion: hasMoreFrontierRows:false, zero approvalCandidates, no stuckActiveCells, and no non-terminal approvedNotDispatched work. Wait primitives are gates, not competing goals, and carry absolute wait.deadlineAt when present. It does not run unbounded approval, lower paid InMail thresholds, switch source families, create campaigns, schedule sends, launch, archive, delete, or write scheduler rows.",
         inputSchema: {
             type: "object",
             properties: {
@@ -209,6 +210,7 @@ export function refillSendsCommand(input = {}) {
                         : `, horizonSendDays: ${horizonSendDays}`}, approvalMode: "${approvalMode}" }) before any import, prep, approval, start, or schedule-affecting action.`,
             "Render target.eligibleSenderLedger and target.senderRefillPlans before mutation. Preserve the coverage labels Need to prepare, Goal, Already sent, Scheduled, Ready and waiting to be scheduled, and Still need.",
             "Use target.globalActionQueue as the only cross-sender yolo queue: execute only target.globalActionQueue[0], one globally ranked primitive, then rerun get_refill_target_plan before choosing another action.",
+            "Read target.senderRefillPlans[].refillReceipt as the public ladder receipt: it carries the selected campaign/sender/lane summary, skippedRungs, existingRowFrontier, and any absolute wait.deadlineAt. Do not choose source/copy/fallback work until that receipt proves the earlier ready/prep/approval rungs are exhausted.",
             "If get_refill_target_plan returns status complete, report eligible sender ledger, target.senderRefillPlans, gross target, selected days, sent count, scheduled count, projected count, campaign ids, targetShapeRevision, and no-op proof without asking for approval.",
             "Refill target lanes are connection invites (send_invite), standalone paid InMails (send_inmail_closed), or unified Sales Nav cascades represented publicly as send_inmail_closed with campaign classification sales_nav_cascade. For a Sales Nav cascade, refill the selected campaign first; its sequence can route prospects to Open InMail, paid InMail while fresh credits are >= 5, or same-campaign connection fallback without asking for separate open/paid/connection campaigns. Do not count send_dm as horizon target capacity.",
             "If remainingReadyOrProjectedGap is 0 but remainingProjectedGap is positive, run only a persistent read-only scheduler wait/reread loop; do not ask for prep/import/approval and do not close out while scheduler pickup is the only remaining state.",
@@ -228,15 +230,17 @@ export function refillSendsCommand(input = {}) {
             "Treat current dashboard-active PAUSED campaign-backed sequence campaigns as start-eligible candidates: read refill state before deciding whether to prep, approve, start, or skip.",
             "Fresh reread get_campaign_refill_state immediately before any import, prep, approval, or horizon-fill mutation.",
             "Maintain a target-window saturation ledger per selected sender from get_refill_target_plan: selected days, gross capacity, actual sent counts, future scheduler-owned scheduled counts, projected counts, ready-to-schedule buffer, remaining projected gap, paid InMail threshold feasibility, targetShapeRevision, stateRevision, and next MCP primitive.",
+            "Source/fallback primitives require receipt-proven exhaustion: existingRowFrontier.hasMoreFrontierRows:false, approvalCandidates:0, no fresh active prep, no stuckActiveCells, and no non-terminal approvedNotDispatched rows. Treat anomalies, stuckActiveCells, and non-terminal approvedNotDispatched as diagnose-and-report gates, not exhaustion. Terminal approvedNotDispatched blockers may be reported and then the ladder can proceed.",
             "In --yolo, this tool automatically maintains a run-local refreshedPaidInmailSenderIds set: when the first target plan returns refresh_paid_inmail_credits candidates for selected paid-InMail lanes, it refreshes each exact sender at most once, reruns get_refill_target_plan, and returns the post-refresh targetPlan before any prep/source-copy/bounded-approval/read-only wait action is chosen.",
             "Freshness gate precedes scheduler wait: if any selected target.senderRefillPlans[].paidInmail.status is missing_credit_facts or stale_credit_facts, or the target plan contains refresh_paid_inmail_credits, do not enter wait_for_scheduler even when remainingReadyOrProjectedGap is 0; refresh exact sender credit facts once, reread get_refill_target_plan, then choose scheduler wait only if freshness is clean.",
+            "For wait_for_active_work and wait_for_scheduler, honor the receipt's absolute wait.deadlineAt when present. If the deadline is expired on this call, escalate to diagnostics with the receipt evidence instead of issuing another blind wait.",
             "Do not present paid-credit refresh as the next operator action after refill_sends returns autoPaidInmailRefresh and the post-refresh targetPlan.",
             "If paid InMail feasibility remains below threshold after that automatic refresh, report the exact sender/campaign/table/column threshold action or same-campaign connection fallback; --yolo must not lower paid InMail thresholds or create campaigns.",
             "In --yolo or after one Accept, continue through every safe selected sender/campaign action covered by the rendered target packet; sent/scheduled-count progress changes stateRevision and should continue while targetShapeRevision is stable.",
             "Do not complete a fill/schedule request until a final get_refill_target_plan or refill-state reread proves projected coverage (sent + scheduled) fills the scheduler-forward target window. Treat awaiting_scheduler_after_ready_buffer as loaded, awaiting scheduler when ready buffer covers the gap; do not import/prep more rows in that state, and keep polling unless Christian stops/statuses the run or a concrete non-scheduler blocker such as paid_inmail_below_threshold appears.",
         ],
         approvalContract: yolo
-            ? "Auto-accept only the rendered bounded refill target packet after get_refill_target_plan and fresh reread. Execute one globally ranked primitive from target.globalActionQueue at a time, then rerun get_refill_target_plan before taking another action. Continue through every safe prep/source-copy/bounded-approval/read-only wait action inside that packet. Unbounded approval, start_campaign, source-family switches, threshold changes, and campaign creation require their own explicit gates. After each safe action, rerun get_refill_target_plan; keep going while targetShapeRevision is stable and projected coverage (sent + scheduled) progresses toward the target, even though stateRevision changes. Ready-to-schedule rows are buffer, not completion. If ready buffer covers the projected gap, use only persistent read-only scheduler wait/reread and keep the run open until projected coverage fills or Christian stops/statuses it. Stop immediately if targetShapeRevision changes because sender set, route, ids, caps, dates, blockers, action class, paid InMail threshold feasibility, or side-effect class drifts. --yolo does not authorize lowering paid InMail thresholds or creating connection campaigns."
+            ? "Auto-accept only the rendered bounded refill target packet after get_refill_target_plan and fresh reread. Execute one globally ranked primitive from target.globalActionQueue at a time, then rerun get_refill_target_plan before taking another action. Continue through every safe prep/source-copy/bounded-approval/read-only wait action inside that packet, but source-copy/fallback requires receipt-proven exhaustion of earlier ready/prep/approval rungs. Unbounded approval, start_campaign, source-family switches, threshold changes, and campaign creation require their own explicit gates. After each safe action, rerun get_refill_target_plan; keep going while targetShapeRevision is stable and projected coverage (sent + scheduled) progresses toward the target, even though stateRevision changes. Ready-to-schedule rows are buffer, not completion. If ready buffer covers the projected gap, use only persistent read-only scheduler wait/reread and keep the run open until projected coverage fills or Christian stops/statuses it. Stop immediately if targetShapeRevision changes because sender set, route, ids, caps, dates, blockers, action class, paid InMail threshold feasibility, side-effect class, or receipt exhaustion proof drifts. --yolo does not authorize lowering paid InMail thresholds or creating connection campaigns."
             : hasSenderSelectors
                 ? "Before mutation, post the full bounded refill packet in normal chat as Markdown, including workspace, sender scope, campaign table, exact ids, caps/dates, gross target, sent count, scheduled count, projected count, ready buffer, remaining projected gap, paid InMail threshold feasibility, targetShapeRevision/stateRevision, side effects, forbidden actions, and stop condition. Then ask the final Accept/Decline structured approval question with a compact body that refers back to the posted packet instead of duplicating it. Only ask when get_refill_target_plan reports a positive remaining projected/ready gap. If target is complete by projected coverage, no-op without approval. If ready buffer covers the projected gap, run only persistent read-only scheduler wait/reread and keep the run open until projected coverage fills or Christian stops/statuses it. Threshold changes and campaign creation need separate explicit approval."
                 : "Ask which eligible enrolled senders to refill first, then, before mutation, post the full bounded refill packet in normal chat as Markdown and ask the final Accept/Decline structured approval question with a compact body that refers back to the posted packet.",
@@ -249,7 +253,7 @@ export function refillSendsCommand(input = {}) {
             "direct scheduler writes",
             "sender reassignment",
             "campaigns outside the rendered eligible sender packet",
-            "on-demand or unrelated active-campaign fallback unless the refill workflow proves the selected same-sender lane is blocked or exhausted",
+            "on-demand or unrelated active-campaign fallback unless the refill workflow shows receipt-proven exhaustion for the selected same-sender lane",
         ],
         hostExamples: {
             claude: [
@@ -326,6 +330,9 @@ function paidRefreshApprovalPacket(params) {
     const action = params.action.action ?? {};
     const ids = actionIds(action);
     const threshold = numberValue(action.oldThreshold) ?? numberValue(action.threshold);
+    const maxStalenessSeconds = Math.max(numberValue(action.maxStalenessSeconds) ??
+        numberValue(action.paidInmailCreditsMaxStalenessSeconds) ??
+        MCP_PAID_INMAIL_CREDITS_MAX_STALENESS_SECONDS, MCP_PAID_INMAIL_CREDITS_MAX_STALENESS_SECONDS);
     return {
         approvalSource: "explicit_yolo_flag",
         workspaceId: params.workspaceId ?? null,
@@ -336,12 +343,22 @@ function paidRefreshApprovalPacket(params) {
         tableId: stringValue(ids.tableId) ?? stringValue(action.tableId) ?? null,
         columnId: stringValue(ids.columnId) ?? stringValue(action.columnId) ?? null,
         threshold: threshold ?? null,
-        maxStalenessSeconds: numberValue(action.maxStalenessSeconds) ??
-            numberValue(action.paidInmailCreditsMaxStalenessSeconds) ??
-            null,
+        maxStalenessSeconds,
         targetPlanFingerprint: targetPlanFingerprint(params.targetPlan),
     };
 }
+function paidRefreshOptionsFromApprovalPacket(packet) {
+    return {
+        ...(packet.actionType ? { actionType: packet.actionType } : {}),
+        ...(packet.campaignId ? { campaignId: packet.campaignId } : {}),
+        ...(packet.tableId ? { tableId: packet.tableId } : {}),
+        ...(packet.columnId ? { columnId: packet.columnId } : {}),
+        ...(typeof packet.threshold === "number"
+            ? { threshold: packet.threshold }
+            : {}),
+        maxStalenessSeconds: packet.maxStalenessSeconds,
+    };
+}
 export async function executeRefillSendsCommand(input = {}) {
     const yolo = input.yolo === true;
     const executionMode = input.executionMode ?? (yolo ? "yolo" : "manual");
@@ -404,7 +421,7 @@ export async function executeRefillSendsCommand(input = {}) {
             });
             continue;
         }
-        const refreshResult = await refreshPaidInmailCreditsWithRetry(action.senderId, workspaceId);
+        const refreshResult = await refreshPaidInmailCreditsWithRetry(action.senderId, workspaceId, paidRefreshOptionsFromApprovalPacket(approvalPacket));
         if (refreshResult.receipt) {
             refreshedPaidInmailSenderIds.push(action.senderId);
             refreshReceipts.push({

package/dist/tools/refill-target-plan.js

@@ -36,6 +36,11 @@ const TERMINAL_NO_ACTION_BLOCKER_CODES = new Set([
     "paid_inmail_credit_missing",
     "paid_inmail_credit_stale",
 ]);
+const MCP_PAID_INMAIL_CREDITS_MAX_STALENESS_SECONDS = 4 * 60 * 60;
+const PAID_INMAIL_REFRESH_STATUSES = new Set([
+    "missing_credit_facts",
+    "stale_credit_facts",
+]);
 const SOURCE_PLAN_STATES = new Set([
     "not_needed",
     "use_existing_rows",
@@ -73,15 +78,37 @@ function actionTypesFrom(value) {
 function numberValue(value) {
     return typeof value === "number" && Number.isFinite(value) ? value : 0;
 }
+function optionalNumberValue(value) {
+    return typeof value === "number" && Number.isFinite(value) ? value : null;
+}
 function stringValue(value) {
     return typeof value === "string" ? value : undefined;
 }
 function booleanValue(value) {
     return typeof value === "boolean" ? value : undefined;
 }
+function numericRecord(value) {
+    if (!isRecord(value))
+        return {};
+    return Object.fromEntries(Object.entries(value).filter((entry) => typeof entry[1] === "number" && Number.isFinite(entry[1])));
+}
 function campaignClassificationValue(value) {
     return value === "sales_nav_cascade" ? "sales_nav_cascade" : undefined;
 }
+function normalizePaidInmailMaxStalenessSeconds(value) {
+    const numeric = optionalNumberValue(value);
+    return numeric !== null && numeric > 0
+        ? Math.max(Math.trunc(numeric), MCP_PAID_INMAIL_CREDITS_MAX_STALENESS_SECONDS)
+        : MCP_PAID_INMAIL_CREDITS_MAX_STALENESS_SECONDS;
+}
+function isFreshWithinMcpPaidInmailWindow(checkedAt, maxStalenessSeconds) {
+    if (!checkedAt)
+        return false;
+    const checkedAtMs = new Date(checkedAt).getTime();
+    if (!Number.isFinite(checkedAtMs))
+        return false;
+    return Date.now() - checkedAtMs <= maxStalenessSeconds * 1000;
+}
 function stringArray(value) {
     if (!Array.isArray(value))
         return [];
@@ -133,7 +160,7 @@ function sanitizeCounts(counts, selectedKeys) {
         return Boolean(key && selectedKeys.has(key));
     });
 }
-function sanitizeActionCandidates(candidates, selectedKeys, status, remainingReadyOrProjectedGap, remainingProjectedGap) {
+function sanitizeActionCandidates(candidates, selectedKeys, paidRefreshNeededSenderIds, status, remainingReadyOrProjectedGap, remainingProjectedGap) {
     const filtered = Array.isArray(candidates)
         ? candidates
             .filter((item) => {
@@ -144,6 +171,13 @@ function sanitizeActionCandidates(candidates, selectedKeys, status, remainingRea
                 return false;
             }
             const actionType = item.actionType;
+            if (item.type === "refresh_paid_inmail_credits") {
+                const ids = isRecord(item.ids) ? item.ids : {};
+                const senderId = stringValue(item.senderId) ?? stringValue(ids.senderId);
+                return Boolean(senderId &&
+                    paidRefreshNeededSenderIds.has(senderId) &&
+                    selectedKeys.has(`${senderId}:send_inmail_closed`));
+            }
             if (actionType === undefined)
                 return item.type === "wait_for_scheduler";
             const allowed = allowedActionType(actionType);
@@ -190,6 +224,8 @@ function sanitizeActionCandidate(candidate) {
         columnRole: stringValue(candidate.columnRole),
         rowSelector: sanitizeRowSelector(candidate.rowSelector),
         actionKey: stringValue(candidate.actionKey),
+        wait: sanitizeWait(candidate.wait),
+        refillReceipt: sanitizeRefillReceipt(candidate.refillReceipt),
         rereadAfter: candidate.rereadAfter === "get_refill_target_plan"
             ? "get_refill_target_plan"
             : undefined,
@@ -217,6 +253,98 @@ function sanitizeRowSelector(value) {
             : {}),
     };
 }
+function sanitizeWait(value) {
+    if (!isRecord(value))
+        return undefined;
+    const deadlineAt = stringValue(value.deadlineAt);
+    const onExpiry = stringValue(value.onExpiry);
+    if (!deadlineAt && !onExpiry)
+        return undefined;
+    return { deadlineAt, onExpiry };
+}
+function sanitizeStuckActiveCells(value) {
+    if (!Array.isArray(value))
+        return [];
+    return value
+        .filter((cell) => isRecord(cell))
+        .map((cell) => ({
+        cellId: stringValue(cell.cellId),
+        rowId: stringValue(cell.rowId),
+        status: stringValue(cell.status),
+        ageMs: typeof cell.ageMs === "number" ? cell.ageMs : undefined,
+    }));
+}
+function sanitizeApprovedNotDispatched(value) {
+    if (!Array.isArray(value))
+        return [];
+    return value
+        .filter((row) => isRecord(row))
+        .map((row) => ({
+        rowId: stringValue(row.rowId),
+        attempts: typeof row.attempts === "number" ? row.attempts : undefined,
+        reason: stringValue(row.reason),
+        terminal: booleanValue(row.terminal),
+    }));
+}
+function sanitizeExistingRowFrontier(value) {
+    if (!isRecord(value))
+        return undefined;
+    return {
+        proof: stringValue(value.proof),
+        batchStop: stringValue(value.batchStop),
+        hasMoreFrontierRows: booleanValue(value.hasMoreFrontierRows),
+        stageCounts: numericRecord(value.stageCounts),
+        activeCellCount: typeof value.activeCellCount === "number"
+            ? value.activeCellCount
+            : undefined,
+        approvalCandidates: typeof value.approvalCandidates === "number"
+            ? value.approvalCandidates
+            : undefined,
+        brokenByReason: numericRecord(value.brokenByReason),
+        stuckActiveCells: sanitizeStuckActiveCells(value.stuckActiveCells),
+        approvedNotDispatched: sanitizeApprovedNotDispatched(value.approvedNotDispatched),
+        wait: sanitizeWait(value.wait),
+    };
+}
+function sanitizeSkippedRungs(value) {
+    if (!Array.isArray(value))
+        return [];
+    return value
+        .filter((rung) => isRecord(rung))
+        .map((rung) => ({
+        rung: stringValue(rung.rung),
+        reason: stringValue(rung.reason),
+        detail: stringValue(rung.detail),
+    }));
+}
+function sanitizeRefillReceipt(value) {
+    if (!isRecord(value))
+        return undefined;
+    return {
+        summary: stringValue(value.summary),
+        schedulableGap: typeof value.schedulableGap === "number"
+            ? value.schedulableGap
+            : undefined,
+        schedulerFillableGap: typeof value.schedulerFillableGap === "number"
+            ? value.schedulerFillableGap
+            : undefined,
+        selectedCampaignId: stringValue(value.selectedCampaignId),
+        selectedCampaignName: stringValue(value.selectedCampaignName),
+        selectedTableId: stringValue(value.selectedTableId),
+        senderId: stringValue(value.senderId),
+        senderName: stringValue(value.senderName),
+        actionType: allowedActionType(value.actionType),
+        dateWindow: isRecord(value.dateWindow)
+            ? { selectedDates: stringArray(value.dateWindow.selectedDates) }
+            : undefined,
+        readyBuffer: typeof value.readyBuffer === "number" ? value.readyBuffer : undefined,
+        approvalCandidates: typeof value.approvalCandidates === "number"
+            ? value.approvalCandidates
+            : undefined,
+        existingRowFrontier: sanitizeExistingRowFrontier(value.existingRowFrontier),
+        skippedRungs: sanitizeSkippedRungs(value.skippedRungs),
+    };
+}
 function sanitizeRerunErroredCellsOperations(value) {
     if (!Array.isArray(value))
         return [];
@@ -285,6 +413,8 @@ function sanitizeToolInput(value) {
             : undefined,
         threshold: typeof value.threshold === "number" ? value.threshold : undefined,
         operations: sanitizeRerunErroredCellsOperations(value.operations),
+        wait: sanitizeWait(value.wait),
+        refillReceipt: sanitizeRefillReceipt(value.refillReceipt),
     };
 }
 function sanitizePacketIds(value) {
@@ -328,6 +458,7 @@ function sanitizeStructuredAction(action, selectedBySender, mode, rank) {
         toolInput: sanitizeToolInput(action.toolInput),
         inputSummary: stringValue(action.inputSummary) ?? "",
         reason: stringValue(action.reason) ?? "",
+        refillReceipt: sanitizeRefillReceipt(action.refillReceipt),
         prerequisites: stringArray(action.prerequisites),
         rereadAfter: action.rereadAfter === "get_refill_target_plan"
             ? "get_refill_target_plan"
@@ -430,20 +561,41 @@ function sanitizeSourcePlan(value) {
 function sanitizePaidInmail(value) {
     if (!isRecord(value))
         return null;
+    const originalMaxStalenessSeconds = optionalNumberValue(value.maxStalenessSeconds);
+    const maxStalenessSeconds = normalizePaidInmailMaxStalenessSeconds(value.maxStalenessSeconds);
+    const checkedAt = stringValue(value.checkedAt) ?? null;
+    const availableCredits = numberValue(value.availableCredits);
+    const threshold = numberValue(value.threshold);
+    let status = stringValue(value.status) ?? "missing_credit_facts";
+    let reason = stringValue(value.reason) ?? "";
+    let freshnessPolicy;
+    if (status === "stale_credit_facts" &&
+        isFreshWithinMcpPaidInmailWindow(checkedAt, maxStalenessSeconds)) {
+        status = availableCredits < threshold ? "below_threshold" : "ok";
+        reason =
+            status === "below_threshold"
+                ? "MCP normalized paid InMail freshness to 4h; cached credits are fresh enough but below threshold."
+                : "MCP normalized paid InMail freshness to 4h; cached credits are fresh enough.";
+        freshnessPolicy = {
+            normalizedBy: "mcp",
+            minMaxStalenessSeconds: MCP_PAID_INMAIL_CREDITS_MAX_STALENESS_SECONDS,
+            originalMaxStalenessSeconds,
+        };
+    }
     return {
-        status: stringValue(value.status) ?? "missing_credit_facts",
-        reason: stringValue(value.reason) ?? "",
-        checkedAt: stringValue(value.checkedAt) ?? null,
+        status,
+        reason,
+        checkedAt,
         balance: typeof value.balance === "number" ? value.balance : null,
         sentSince: numberValue(value.sentSince),
-        availableCredits: numberValue(value.availableCredits),
-        threshold: numberValue(value.threshold),
+        availableCredits,
+        threshold,
         campaignId: stringValue(value.campaignId) ?? null,
         campaignName: stringValue(value.campaignName) ?? null,
         tableId: stringValue(value.tableId) ?? null,
         tableName: stringValue(value.tableName) ?? null,
         columnId: stringValue(value.columnId) ?? null,
-        maxStalenessSeconds: numberValue(value.maxStalenessSeconds),
+        maxStalenessSeconds,
         campaignClassification: campaignClassificationValue(value.campaignClassification) ?? null,
         connectionFallbackAvailable: booleanValue(value.connectionFallbackAvailable) ?? false,
         connectionFallbackCampaignId: stringValue(value.connectionFallbackCampaignId) ?? null,
@@ -451,8 +603,19 @@ function sanitizePaidInmail(value) {
         suggestedThreshold: typeof value.suggestedThreshold === "number"
             ? value.suggestedThreshold
             : null,
+        ...(freshnessPolicy ? { freshnessPolicy } : {}),
     };
 }
+function paidInmailNeedsRefresh(value) {
+    if (!isRecord(value))
+        return false;
+    const status = stringValue(value.status);
+    return Boolean(status && PAID_INMAIL_REFRESH_STATUSES.has(status));
+}
+function filterFreshPaidInmailRefreshAction(action, paidInmail) {
+    return (action.type !== "refresh_paid_inmail_credits" ||
+        paidInmailNeedsRefresh(paidInmail));
+}
 function sanitizeStructuredSenderPlans(value, selectedBySender) {
     if (!Array.isArray(value))
         return [];
@@ -464,10 +627,12 @@ function sanitizeStructuredSenderPlans(value, selectedBySender) {
         return Boolean(selectedLane && selectedBySender.get(plan.senderId) === selectedLane);
     })
         .map((plan) => {
+        const paidInmail = sanitizePaidInmail(plan.paidInmail);
         const nextActions = Array.isArray(plan.nextActions)
             ? plan.nextActions
                 .map((action, index) => sanitizeStructuredAction(action, selectedBySender, "next", index + 1))
                 .filter((action) => Boolean(action))
+                .filter((action) => filterFreshPaidInmailRefreshAction(action, paidInmail))
             : [];
         const manualAlternates = Array.isArray(plan.manualAlternates)
             ? plan.manualAlternates
@@ -512,8 +677,9 @@ function sanitizeStructuredSenderPlans(value, selectedBySender) {
                 : {},
             coverageDisplay: stringArray(plan.coverageDisplay),
             campaignRanking: sanitizeCampaignRanking(plan.campaignRanking),
-            paidInmail: sanitizePaidInmail(plan.paidInmail),
+            paidInmail,
             sourcePlan: sanitizeSourcePlan(plan.sourcePlan),
+            refillReceipt: sanitizeRefillReceipt(plan.refillReceipt),
             nextActions,
             manualAlternates,
             ...(isRecord(plan.emptyState)
@@ -537,6 +703,17 @@ function buildSanitizedGlobalActionQueue(senderRefillPlans) {
         rank: index + 1,
     }));
 }
+function paidRefreshNeededSenderIds(senderRefillPlans) {
+    const senderIds = new Set();
+    for (const plan of senderRefillPlans) {
+        if (!paidInmailNeedsRefresh(plan.paidInmail))
+            continue;
+        const senderId = stringValue(plan.senderId);
+        if (senderId)
+            senderIds.add(senderId);
+    }
+    return senderIds;
+}
 function emptyUnsupportedResult(result) {
     if (!isRecord(result) || !isRecord(result.target))
         return result;
@@ -579,7 +756,7 @@ function emptyUnsupportedResult(result) {
         mcpSanitizedRefillLanes: true,
     };
 }
-function sanitizeBlockers(blockers, selectedKeys) {
+function sanitizeBlockers(blockers, selectedKeys, paidRefreshNeededSenderIds) {
     if (!Array.isArray(blockers))
         return [];
     return blockers.filter((item) => {
@@ -591,6 +768,10 @@ function sanitizeBlockers(blockers, selectedKeys) {
             return true;
         const detailSenderId = detail.split(":")[0];
         if (code.startsWith("paid_inmail_")) {
+            if (code === "paid_inmail_credit_stale" &&
+                !paidRefreshNeededSenderIds.has(detailSenderId)) {
+                return false;
+            }
             return selectedKeys.has(`${detailSenderId}:send_inmail_closed`);
         }
         if (detail.includes(":send_dm") || detail.includes(":send_inmail_open")) {
@@ -679,9 +860,10 @@ function sanitizeRefillTargetPlanResult(result) {
     const remainingScheduledGap = senderPlans.reduce((sum, plan) => sum + numberValue(plan.remainingScheduledGap), 0);
     const remainingProjectedGap = senderPlans.reduce((sum, plan) => sum + numberValue(plan.remainingProjectedGap), 0);
     const remainingReadyOrProjectedGap = senderPlans.reduce((sum, plan) => sum + numberValue(plan.remainingReadyOrProjectedGap), 0);
-    const blockers = sanitizeBlockers(result.blockers, selectedKeys);
     const eligibleSenderLedger = sanitizeEligibleSenderLedger(target.eligibleSenderLedger, selectedBySender);
     const senderRefillPlans = sanitizeStructuredSenderPlans(target.senderRefillPlans, selectedBySender);
+    const paidRefreshNeededSenderIdSet = paidRefreshNeededSenderIds(senderRefillPlans);
+    const blockers = sanitizeBlockers(result.blockers, selectedKeys, paidRefreshNeededSenderIdSet);
     const globalActionQueue = buildSanitizedGlobalActionQueue(senderRefillPlans);
     const hasTerminalNoActionBlocker = globalActionQueue.length === 0 &&
         blockers.some((blocker) => TERMINAL_NO_ACTION_BLOCKER_CODES.has(String(blocker.code)));
@@ -728,7 +910,7 @@ function sanitizeRefillTargetPlanResult(result) {
                 readyCounts: sanitizeCounts(result.coverage.readyCounts, selectedKeys),
             }
             : result.coverage,
-        actionCandidates: sanitizeActionCandidates(result.actionCandidates, selectedKeys, status, remainingReadyOrProjectedGap, remainingProjectedGap),
+        actionCandidates: sanitizeActionCandidates(result.actionCandidates, selectedKeys, paidRefreshNeededSenderIdSet, status, remainingReadyOrProjectedGap, remainingProjectedGap),
         blockers,
         mcpSanitizedRefillLanes: true,
     };

package/dist/tools/registry.d.ts

@@ -584,6 +584,97 @@ export declare const allTools: ({
         required: string[];
         additionalProperties: boolean;
     };
+} | {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {
+            campaignId: {
+                type: string;
+                description: string;
+            };
+            tableId: {
+                type: string;
+            };
+            targetPreparedMessages: {
+                type: string;
+                minimum: number;
+                maximum: number;
+            };
+            maxRowsToCheck: {
+                type: string;
+                minimum: number;
+                maximum: number;
+                description: string;
+            };
+            batchSize: {
+                type: string;
+                minimum: number;
+                maximum: number;
+                description: string;
+            };
+            maxBatchRows: {
+                type: string;
+                minimum: number;
+                maximum: number;
+                description: string;
+            };
+            approvalMode: {
+                type: string;
+                enum: string[];
+                description: string;
+            };
+            rowSelector: {
+                type: string;
+                description: string;
+                properties: {
+                    type: {
+                        type: string;
+                        enum: string[];
+                    };
+                    limit: {
+                        type: string;
+                        minimum: number;
+                        maximum: number;
+                    };
+                };
+                required: string[];
+                additionalProperties: boolean;
+            };
+            excludeRowIds: {
+                type: string;
+                items: {
+                    type: string;
+                };
+                maxItems: number;
+                description: string;
+            };
+            autoContinue: {
+                type: string;
+            };
+            senderId: {
+                type: string;
+                description: string;
+            };
+            actionType: {
+                type: string;
+                enum: string[];
+                description: string;
+            };
+            disableLowPassRateStop: {
+                type: string;
+                description: string;
+            };
+            workspaceId: {
+                type: string;
+                description: string;
+            };
+            jobId?: undefined;
+        };
+        required: string[];
+        additionalProperties: boolean;
+    };
 } | {
     name: string;
     description: string;
@@ -2343,6 +2434,13 @@ export declare const allTools: ({
                 type: string;
                 description: string;
             };
+            actionType?: undefined;
+            campaignId?: undefined;
+            tableId?: undefined;
+            columnId?: undefined;
+            threshold?: undefined;
+            maxStalenessSeconds?: undefined;
+            paidInmailCreditsMaxStalenessSeconds?: undefined;
         };
         required: string[];
         additionalProperties: boolean;

package/dist/tools/senders.d.ts

@@ -35,6 +35,13 @@ export type SenderDetailResponse = {
 export type RefreshPaidInmailCreditsInput = {
     senderId: string;
     workspaceId: string;
+    actionType?: string | null;
+    campaignId?: string | null;
+    tableId?: string | null;
+    columnId?: string | null;
+    threshold?: number | null;
+    maxStalenessSeconds?: number | null;
+    paidInmailCreditsMaxStalenessSeconds?: number | null;
 };
 export type PaidInmailCreditStatus = {
     available: number;
@@ -68,6 +75,13 @@ export declare const senderToolDefinitions: ({
                 description: string;
             };
             senderId?: undefined;
+            actionType?: undefined;
+            campaignId?: undefined;
+            tableId?: undefined;
+            columnId?: undefined;
+            threshold?: undefined;
+            maxStalenessSeconds?: undefined;
+            paidInmailCreditsMaxStalenessSeconds?: undefined;
         };
         required: never[];
         additionalProperties: boolean;
@@ -86,6 +100,59 @@ export declare const senderToolDefinitions: ({
                 type: string;
                 description: string;
             };
+            actionType?: undefined;
+            campaignId?: undefined;
+            tableId?: undefined;
+            columnId?: undefined;
+            threshold?: undefined;
+            maxStalenessSeconds?: undefined;
+            paidInmailCreditsMaxStalenessSeconds?: undefined;
+        };
+        required: string[];
+        additionalProperties: boolean;
+    };
+} | {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {
+            senderId: {
+                type: string;
+                description: string;
+            };
+            workspaceId: {
+                type: string;
+                description: string;
+            };
+            actionType: {
+                type: string;
+                description: string;
+            };
+            campaignId: {
+                type: string;
+                description: string;
+            };
+            tableId: {
+                type: string;
+                description: string;
+            };
+            columnId: {
+                type: string;
+                description: string;
+            };
+            threshold: {
+                type: string;
+                description: string;
+            };
+            maxStalenessSeconds: {
+                type: string;
+                description: string;
+            };
+            paidInmailCreditsMaxStalenessSeconds: {
+                type: string;
+                description: string;
+            };
         };
         required: string[];
         additionalProperties: boolean;

package/dist/tools/senders.js

@@ -11,6 +11,19 @@ function pickString(...values) {
     }
     return null;
 }
+const DEFAULT_PAID_INMAIL_CREDITS_MAX_STALENESS_SECONDS = 4 * 60 * 60;
+function numberOrNull(value) {
+    return typeof value === "number" && Number.isFinite(value) ? value : null;
+}
+function normalizePaidInmailCreditsMaxStalenessSeconds(...values) {
+    for (const value of values) {
+        const numeric = numberOrNull(value);
+        if (numeric === null || numeric <= 0)
+            continue;
+        return Math.max(Math.trunc(numeric), DEFAULT_PAID_INMAIL_CREDITS_MAX_STALENESS_SECONDS);
+    }
+    return DEFAULT_PAID_INMAIL_CREDITS_MAX_STALENESS_SECONDS;
+}
 function computeDisplayName(sender) {
     const profile = sender?.unipileAccount?.profileData;
     const name = pickString(profile?.name);
@@ -148,6 +161,34 @@ export const senderToolDefinitions = [
                     type: "string",
                     description: "Explicit request-scoped workspace id for scheduled/yolo refill automation. Pass this instead of switching the shared active workspace.",
                 },
+                actionType: {
+                    type: "string",
+                    description: "Optional action type context for the credit freshness check. Defaults to send_inmail_closed.",
+                },
+                campaignId: {
+                    type: "string",
+                    description: "Optional campaign context for the refresh receipt.",
+                },
+                tableId: {
+                    type: "string",
+                    description: "Optional workflow table context for the refresh receipt.",
+                },
+                columnId: {
+                    type: "string",
+                    description: "Optional workflow column context for the refresh receipt.",
+                },
+                threshold: {
+                    type: "number",
+                    description: "Optional paid InMail threshold used by the planner for this sender.",
+                },
+                maxStalenessSeconds: {
+                    type: "number",
+                    description: "Optional cache freshness window in seconds. Values below 4h are clamped to 4h.",
+                },
+                paidInmailCreditsMaxStalenessSeconds: {
+                    type: "number",
+                    description: "Optional legacy alias for maxStalenessSeconds. Values below 4h are clamped to 4h.",
+                },
             },
             required: ["senderId", "workspaceId"],
             additionalProperties: false,
@@ -213,7 +254,25 @@ export async function refreshPaidInmailCredits(input) {
         throw new Error("workspaceId is required.");
     }
     const requestOptions = workspaceRequestOptions(workspaceId);
-    const body = { workspaceId };
+    const threshold = numberOrNull(input.threshold);
+    const body = {
+        workspaceId,
+        maxStalenessSeconds: normalizePaidInmailCreditsMaxStalenessSeconds(input.maxStalenessSeconds, input.paidInmailCreditsMaxStalenessSeconds),
+    };
+    const actionType = pickString(input.actionType);
+    const campaignId = pickString(input.campaignId);
+    const tableId = pickString(input.tableId);
+    const columnId = pickString(input.columnId);
+    if (actionType)
+        body.actionType = actionType;
+    if (campaignId)
+        body.campaignId = campaignId;
+    if (tableId)
+        body.tableId = tableId;
+    if (columnId)
+        body.columnId = columnId;
+    if (threshold !== null)
+        body.threshold = threshold;
     const result = await api.post(`/api/v3/mcp/senders/${encodeURIComponent(senderId)}/refresh-inmail-credits`, body, requestOptions);
     return {
         senderId,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sellable/mcp",
-  "version": "0.1.520",
+  "version": "0.1.522",
   "type": "module",
   "description": "Sellable MCP server for Claude Code and Codex campaign workflows",
   "main": "dist/index.js",

package/skills/refill-sends/SKILL.md

@@ -97,8 +97,11 @@ That command helper normalizes arguments and returns the execution contract. In
 non-yolo mode it does not mutate. In `--yolo`, it may execute exactly one safe
 bounded primitive from the fresh `target.globalActionQueue[0]`, then reread and
 return the new target plan; currently safe primitives are paid-credit refresh,
-existing-row message preparation, same-source row copy, and read-only wait
-rereads. It does not run unbounded approval, lower
+existing-row message preparation, generated-message approval, receipt-proven
+same-source row copy, and read-only wait rereads. Same-source copy/source
+fallback is safe only after receipt-proven exhaustion:
+`hasMoreFrontierRows:false`, zero `approvalCandidates`, no `stuckActiveCells`,
+and no non-terminal `approvedNotDispatched` work. It does not run unbounded approval, lower
 paid-InMail thresholds, switch source families, create campaigns, launch, send,
 or write scheduler rows. Continue with the workflow below for route selection,
 state rereads, approval gating, source import, preparation, and bounded
@@ -198,7 +201,10 @@ Structured planner packet:
 - `target.senderRefillPlans[]` is the canonical sender-level packet; read and
   display it before mutation.
 - Each sender packet includes `campaignRanking.options`, `sourcePlan`,
-  `nextActions`, and `manualAlternates`.
+  `refillReceipt`, `nextActions`, and `manualAlternates`.
+- `refillReceipt` is the public ladder receipt. It carries the selected
+  campaign/sender/lane summary, skipped rungs, existing-row frontier proof, and
+  any absolute `wait.deadlineAt`.
 - Preserve these coverage labels exactly: `Need to prepare`, `Goal`,
   `Already sent`, `Scheduled`, `Ready and waiting to be scheduled`, and
   `Still need`.
@@ -217,6 +223,13 @@ from the selected source (`selectedLeadListId`, provider, and source
 fingerprint preserved), then use provider-aligned source-more. A new source or
 provider switch changes the reply-rate baseline and is a manual alternate, not a
 `--yolo` side effect.
+Source/copy/fallback requires receipt-proven exhaustion of earlier rungs:
+`existingRowFrontier.hasMoreFrontierRows:false`, zero `approvalCandidates`, no
+fresh active prep, no `stuckActiveCells`, and no non-terminal
+`approvedNotDispatched` rows. Treat anomalies, `stuckActiveCells`, and
+non-terminal `approvedNotDispatched` as diagnose-and-report gates, not
+exhaustion. Terminal `approvedNotDispatched` blockers may be reported, then the
+ladder can proceed.
 
 Run-local paid-credit guard: in `--yolo`, the `refill_sends` MCP command
 automatically maintains a `refreshedPaidInmailSenderIds` set for the current
@@ -266,6 +279,10 @@ interval, until projected coverage fills the target, a concrete non-scheduler
 blocker appears, or Christian explicitly asks to stop or only receive a status
 report. Treat `awaiting_scheduler_after_ready_buffer` as an in-progress wait
 state, not a close-out condition.
+Wait actions are gates, not competing goals. When `wait_for_active_work` or
+`wait_for_scheduler` includes receipt `wait.deadlineAt`, honor that absolute
+deadline; if it is expired on this call, escalate to diagnostics with the
+receipt evidence instead of issuing another blind wait.
 If paid InMail credit facts are stale or missing and the first target plan
 contains `refresh_paid_inmail_credits`, do not present that as the operator's
 next action in `--yolo`. Do not present paid-credit refresh as the next operator

package/skills/refill-sends-workflow/SKILL.md

@@ -119,7 +119,10 @@ files or memory.
    - `target.senderRefillPlans[]` is the canonical sender-level packet; read and
      display it before mutation.
    - Each sender packet includes `campaignRanking.options`, `sourcePlan`,
-     `nextActions`, and `manualAlternates`.
+     `refillReceipt`, `nextActions`, and `manualAlternates`.
+   - `refillReceipt` is the public ladder receipt. It carries the selected
+     campaign/sender/lane summary, skipped rungs, existing-row frontier proof,
+     and any absolute `wait.deadlineAt`.
    - Preserve these coverage labels exactly: `Need to prepare`, `Goal`,
      `Already sent`, `Scheduled`, `Ready and waiting to be scheduled`, and
      `Still need`.
@@ -138,6 +141,14 @@ files or memory.
    provider, and source fingerprint preserved), then use provider-aligned
    source-more. A new source or provider switch changes the reply-rate baseline
    and is a manual alternate, not a `--yolo` side effect.
+   Source/copy/fallback requires receipt-proven exhaustion of earlier rungs:
+   `existingRowFrontier.hasMoreFrontierRows:false`, zero
+   `approvalCandidates`, no fresh active prep, no `stuckActiveCells`, and no
+   non-terminal `approvedNotDispatched` rows. Treat anomalies,
+   `stuckActiveCells`, and non-terminal `approvedNotDispatched` as
+   diagnose-and-report gates, not exhaustion. Terminal
+   `approvedNotDispatched` blockers may be reported, then the ladder can
+   proceed.
    Run-local paid-credit guard: in `--yolo`, the `refill_sends` MCP command
    automatically maintains a `refreshedPaidInmailSenderIds` set for the current
    command call. If its first target plan has stale/missing paid-InMail credit
@@ -187,6 +198,10 @@ files or memory.
    stop or only receive a status report. Treat
    `awaiting_scheduler_after_ready_buffer` as an in-progress wait state, not a
    close-out condition.
+   Wait actions are gates, not competing goals. When `wait_for_active_work` or
+   `wait_for_scheduler` includes receipt `wait.deadlineAt`, honor that absolute
+   deadline; if it is expired on this call, escalate to diagnostics with the
+   receipt evidence instead of issuing another blind wait.
    If paid InMail credit facts are stale or missing and the first target plan
    contains `refresh_paid_inmail_credits`, do not present that as the operator's
    next action in `--yolo`. Do not present paid-credit refresh as the next