@sellable/mcp 0.1.512 → 0.1.514

package/dist/refill-run-loop.js

@@ -0,0 +1,1238 @@
+import { SellableApiError } from "./api.js";
+import { buildRunStateFromLocalHints } from "./tools/evergreen-refill-plan.js";
+import { prepareRowSelectorValue as defaultPrepareRowSelectorValue, refillPrepareRequestHash as defaultRefillPrepareRequestHash, } from "./tools/refill-executors.js";
+const DEFAULT_BUDGETS = {
+    maxGateCyclesPerInvocation: 8,
+    pollIntervalMs: 15_000,
+    maxPollsPerWait: 20,
+    maxSchedulerReadbacks: 3,
+    waitWallClockPerInvocationMs: 45_000,
+    schedulerWaitRunBudgetMs: 300_000,
+};
+// Mirrors RefillDoneReason in src/lib/workflow-tables/refill-target-plan.ts.
+const REFILL_DONE_REASONS = new Set([
+    "complete",
+    "capped_by_scheduler",
+    "loaded_awaiting_scheduler",
+    "lanes_exhausted",
+    "blocked",
+    "not_an_evergreen_workspace",
+    "no_refillable_campaigns",
+]);
+function isRecord(value) {
+    return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+function stringValue(value) {
+    return typeof value === "string" && value.trim() ? value.trim() : null;
+}
+function numberValue(value) {
+    return typeof value === "number" && Number.isFinite(value) ? value : null;
+}
+function booleanValue(value) {
+    return typeof value === "boolean" ? value : null;
+}
+function recordValue(value) {
+    return isRecord(value) ? value : null;
+}
+function arrayValue(value) {
+    return Array.isArray(value) ? value : [];
+}
+function hasBlocker(value, blocker) {
+    return isRecord(value) && value.blocker === blocker;
+}
+function isLeaseLost(value) {
+    return hasBlocker(value, "lease_lost");
+}
+function isActiveRun(value) {
+    return hasBlocker(value, "active_run_in_progress");
+}
+function actionToolInput(action) {
+    return recordValue(action.toolInput) ?? {};
+}
+function actionIds(action) {
+    return recordValue(action.ids) ?? {};
+}
+function actionCampaignId(action) {
+    const ids = actionIds(action);
+    const toolInput = actionToolInput(action);
+    return (stringValue(toolInput.campaignId) ??
+        stringValue(toolInput.campaignOfferId) ??
+        stringValue(ids.campaignId) ??
+        stringValue(action.campaignId));
+}
+function actionSenderId(action) {
+    const ids = actionIds(action);
+    const toolInput = actionToolInput(action);
+    return (stringValue(toolInput.senderId) ??
+        stringValue(ids.senderId) ??
+        stringValue(action.senderId));
+}
+function fingerprintFromPlan(plan) {
+    const packet = recordValue(plan.packet) ?? {};
+    return {
+        planRevision: stringValue(plan.planRevision),
+        stateRevision: stringValue(plan.stateRevision) ?? stringValue(packet.stateRevision),
+        targetShapeRevision: stringValue(packet.targetShapeRevision) ??
+            stringValue(packet.targetRevision),
+    };
+}
+function fingerprintChanged(expected, actual) {
+    if (!expected || !actual)
+        return [];
+    const changed = [];
+    if (expected.planRevision !== actual.planRevision)
+        changed.push("planRevision");
+    if (expected.stateRevision !== actual.stateRevision)
+        changed.push("stateRevision");
+    if (expected.targetShapeRevision !== actual.targetShapeRevision) {
+        changed.push("targetShapeRevision");
+    }
+    return changed;
+}
+function firstAction(plan) {
+    const globalActionQueue = arrayValue(plan.globalActionQueue);
+    return recordValue(globalActionQueue[0]);
+}
+function doneReasonFromPlan(plan) {
+    const action = firstAction(plan);
+    return (stringValue(action?.doneReason) ??
+        stringValue(recordValue(plan.packet)?.doneReason) ??
+        stringValue(plan.doneReason));
+}
+function selectedLaneAuthority(plan, action) {
+    const senderId = actionSenderId(action);
+    const evergreen = recordValue(plan.evergreen) ?? {};
+    const laneOrder = arrayValue(evergreen.laneOrder).filter(isRecord);
+    const campaignIdsByLaneKey = new Map();
+    for (const lane of laneOrder) {
+        const laneKey = stringValue(lane.laneKey);
+        const campaignId = stringValue(lane.campaignId);
+        if (laneKey && campaignId)
+            campaignIdsByLaneKey.set(laneKey, campaignId);
+    }
+    const selections = arrayValue(evergreen.senderLaneSelections).filter(isRecord);
+    const selection = selections.find((entry) => stringValue(entry.senderId) === senderId) ??
+        selections[0] ??
+        {};
+    const selectedLane = recordValue(selection.selectedLane) ?? {};
+    const laneChain = arrayValue(selection.laneChain)
+        .map((entry) => stringValue(entry))
+        .filter((entry) => Boolean(entry));
+    const laneChainCampaignIds = laneChain
+        .map((laneKeyOrCampaignId) => campaignIdsByLaneKey.get(laneKeyOrCampaignId) ?? laneKeyOrCampaignId)
+        .filter(Boolean);
+    return {
+        laneChainCampaignIds,
+        pinnedCampaignId: stringValue(selectedLane.campaignId) ?? actionCampaignId(action),
+        planRevision: stringValue(plan.planRevision),
+    };
+}
+function mergeRunState(current, updates) {
+    return {
+        ...current,
+        ...updates,
+    };
+}
+function normalizeDoneReason(value) {
+    const raw = stringValue(value);
+    if (!raw)
+        return "blocked";
+    if (raw === "awaiting_scheduler_after_ready_buffer") {
+        return "loaded_awaiting_scheduler";
+    }
+    return REFILL_DONE_REASONS.has(raw) ? raw : "blocked";
+}
+function runStateProgress(ctx) {
+    return recordValue(ctx.runState.progress) ?? {};
+}
+function mergeProgress(ctx, updates) {
+    return {
+        ...runStateProgress(ctx),
+        ...updates,
+    };
+}
+function filenameFromPath(filePath) {
+    if (!filePath)
+        return null;
+    const normalized = filePath.replace(/\\/g, "/");
+    return normalized.slice(normalized.lastIndexOf("/") + 1);
+}
+function safeJson(value) {
+    try {
+        return JSON.stringify(value);
+    }
+    catch {
+        return String(value);
+    }
+}
+function summarizeAction(action) {
+    if (!action)
+        return "no action";
+    return [
+        stringValue(action.evergreenRung) ?? stringValue(action.type) ?? "action",
+        stringValue(action.toolName),
+        actionCampaignId(action),
+    ]
+        .filter(Boolean)
+        .join(" ");
+}
+function resultPayload(value) {
+    const record = recordValue(value) ?? {};
+    const result = recordValue(record.result);
+    return result ?? record;
+}
+function activeJobIdFromOutcome(value) {
+    const payload = resultPayload(value);
+    return stringValue(payload.activeJobId) ?? stringValue(payload.jobId);
+}
+function isTerminalJobStatus(value) {
+    const status = stringValue(recordValue(value)?.status);
+    const jobStatus = stringValue(recordValue(value)?.jobStatus) ?? status;
+    return Boolean(jobStatus && jobStatus !== "pending" && jobStatus !== "running");
+}
+function preparedCountFromStatus(value) {
+    const status = recordValue(value) ?? {};
+    const progress = recordValue(status.progress) ?? {};
+    return (numberValue(progress.preparedCapacityRows) ??
+        numberValue(progress.preparedMessages) ??
+        numberValue(status.preparedMessages) ??
+        0);
+}
+function checkedRowsFromStatus(value) {
+    const status = recordValue(value) ?? {};
+    const progress = recordValue(status.progress) ?? {};
+    return (numberValue(progress.checkedRows) ?? numberValue(status.checkedRows) ?? 0);
+}
+function expectedPrepareRequestHash(deps, action) {
+    const campaignId = actionCampaignId(action);
+    if (!campaignId)
+        return null;
+    const toolInput = actionToolInput(action);
+    const approvalMode = toolInput.approvalMode === "approve" ? "approve" : "mark_ready";
+    const prepareRowSelector = deps.executors.prepareRowSelectorValue ?? defaultPrepareRowSelectorValue;
+    const requestHash = deps.executors.refillPrepareRequestHash ?? defaultRefillPrepareRequestHash;
+    return requestHash({
+        action,
+        campaignId,
+        tableId: stringValue(toolInput.tableId) ?? undefined,
+        approvalMode,
+        rowSelector: prepareRowSelector(toolInput.rowSelector),
+    });
+}
+function lastAction(ctx) {
+    return (recordValue(ctx.runState.lastExecutedAction) ??
+        ctx.headAction ??
+        recordValue(ctx.runState.headAction));
+}
+function lastEventId(ctx) {
+    return stringValue(ctx.runState.lastEventId) ?? `${ctx.runId}:${ctx.gateSeq}`;
+}
+function coverageSnapshot(plan) {
+    const packet = recordValue(plan.packet) ?? {};
+    const target = recordValue(plan.target) ?? {};
+    const coverage = recordValue(packet.coverage) ??
+        recordValue(target.coverage) ??
+        recordValue(plan.coverage) ??
+        {};
+    return {
+        sent: numberValue(coverage.sent) ?? numberValue(plan.sent) ?? 0,
+        scheduled: numberValue(coverage.scheduled) ?? numberValue(plan.scheduled) ?? 0,
+        ready: numberValue(coverage.ready) ?? numberValue(plan.ready) ?? 0,
+        goal: numberValue(coverage.goal) ?? numberValue(target.goal) ?? 0,
+    };
+}
+function actionTableId(action) {
+    if (!action)
+        return null;
+    const toolInput = actionToolInput(action);
+    const ids = actionIds(action);
+    return stringValue(toolInput.tableId) ?? stringValue(ids.tableId);
+}
+function noProgressSignature(plan, action) {
+    const coverage = coverageSnapshot(plan);
+    return {
+        headRung: stringValue(action.evergreenRung) ?? stringValue(action.type),
+        actionFingerprint: [
+            stringValue(action.type),
+            actionCampaignId(action),
+            actionTableId(action),
+            actionSenderId(action),
+        ]
+            .filter(Boolean)
+            .join(":"),
+        counters: {
+            sent: coverage.sent,
+            scheduled: coverage.scheduled,
+            ready: coverage.ready,
+            goal: coverage.goal,
+            neverRun: numberValue(recordValue(plan.supplyCensus)?.neverRun) ??
+                numberValue(recordValue(recordValue(plan.packet)?.supplyCensus)?.neverRun) ??
+                0,
+            laneCursor: numberValue(recordValue(plan.selectedLane)?.laneCursor) ??
+                numberValue(recordValue(plan.evergreen)?.laneCursor) ??
+                0,
+        },
+    };
+}
+function nextNoProgressState(ctx, plan, action) {
+    const next = noProgressSignature(plan, action);
+    const prior = recordValue(runStateProgress(ctx).noProgress) ?? {};
+    const priorSignature = recordValue(prior.signature);
+    const same = priorSignature && safeJson(priorSignature) === safeJson(next);
+    const repeatCount = same ? (numberValue(prior.repeatCount) ?? 1) + 1 : 1;
+    return {
+        signature: next,
+        repeatCount,
+    };
+}
+function sourceHandoffText(action) {
+    const campaignId = actionCampaignId(action) ?? "campaign";
+    const toolInput = actionToolInput(action);
+    const sourceLeadListId = stringValue(toolInput.sourceLeadListId);
+    return [
+        `$sellable:create-campaign ${campaignId}`,
+        "Scope: add leads via this campaign's existing source only.",
+        sourceLeadListId
+            ? `Import mode: add into sourceLeadListId=${sourceLeadListId}.`
+            : null,
+        "No brief, rubric, message, sequence, sender, provider-family, or campaign changes without a separate approval packet.",
+    ]
+        .filter(Boolean)
+        .join(" ");
+}
+function getPlanLine(plan) {
+    const plans = arrayValue(plan.plans).filter(isRecord);
+    const firstPlan = plans[0] ?? {};
+    const itinerary = recordValue(firstPlan.itinerary) ?? {};
+    const chosen = recordValue(itinerary.chosen) ?? {};
+    const projected = arrayValue(itinerary.projected).filter(isRecord);
+    return {
+        chosenSummary: stringValue(chosen.summary) ?? summarizeAction(firstAction(plan)),
+        projectedSummaries: projected
+            .map((entry) => stringValue(entry.summary))
+            .filter((entry) => Boolean(entry)),
+        fallbackSummary: stringValue(recordValue(itinerary.fallback)?.trigger) ?? "",
+    };
+}
+function packetCoherenceFailure(plan) {
+    const fingerprint = fingerprintFromPlan(plan);
+    if (!fingerprint.planRevision || !fingerprint.targetShapeRevision) {
+        return "missing_fingerprint";
+    }
+    const action = firstAction(plan);
+    const doneReason = doneReasonFromPlan(plan);
+    if (doneReason && action && action.type !== "done") {
+        return "terminal_with_action_queue";
+    }
+    if (!action)
+        return null;
+    const toolInput = actionToolInput(action);
+    const type = stringValue(action.type);
+    if (type === "prepare_messages" &&
+        (!actionCampaignId(action) || !stringValue(toolInput.tableId))) {
+        return "malformed_prepare_tool_input";
+    }
+    return null;
+}
+async function safeJournalAppend(ctx, deps, block) {
+    if (!ctx.journalPath)
+        return;
+    try {
+        deps.journal.appendJournalEvent(ctx.journalPath, block);
+    }
+    catch {
+        // Best effort; journal failure must not stop execution.
+    }
+}
+async function safeLocalStateWrite(input, deps, update) {
+    if (input.dryRun || !deps.localState?.writeRefillWorkspaceState)
+        return;
+    try {
+        await deps.localState.writeRefillWorkspaceState(input.workspaceId, update);
+    }
+    catch {
+        // Best effort; local calibration failure must not kill a leased run.
+    }
+}
+async function sleepForWait(input, deps, ctx, budgets) {
+    if (ctx.sleptMs + budgets.pollIntervalMs >
+        budgets.waitWallClockPerInvocationMs) {
+        return heartbeatAndContinue(input, deps, ctx);
+    }
+    const heartbeat = await deps.runClient.heartbeatRefillRun({
+        workspaceId: input.workspaceId,
+        runId: ctx.runId,
+        fence: ctx.fence,
+    });
+    if (isLeaseLost(heartbeat))
+        return leaseLostResult(ctx);
+    ctx.sleptMs += budgets.pollIntervalMs;
+    await (deps.sleep?.(budgets.pollIntervalMs) ??
+        new Promise((resolve) => {
+            setTimeout(resolve, budgets.pollIntervalMs);
+        }));
+    return null;
+}
+async function createJournal(input, deps, runId) {
+    try {
+        return deps.journal.createRunJournal({
+            workspaceId: input.workspaceId,
+            runId,
+            dryRun: false,
+            now: deps.now?.() ?? new Date(),
+        }).filePath;
+    }
+    catch {
+        return null;
+    }
+}
+async function startOrResume(input, deps) {
+    const initialRunState = buildRunStateFromLocalHints(input.workspaceId);
+    const started = await deps.runClient.startRefillRunRemote({
+        workspaceId: input.workspaceId,
+        config: {
+            intent: input.intent ?? "auto",
+            senderIds: input.senderIds,
+            approvalMode: input.approvalMode ?? "approve",
+        },
+        runState: initialRunState,
+        resume: input.resume,
+    });
+    if (isLeaseLost(started)) {
+        return {
+            status: "blocked",
+            blocker: "lease_lost",
+            guidance: "Refill run lease was lost. Re-invoke after the lease TTL expires or resume with a fresh holder handle.",
+        };
+    }
+    if (isActiveRun(started)) {
+        return {
+            status: "blocked",
+            blocker: "active_run_in_progress",
+            holderRunId: started.runId,
+            gate: started.gate ?? undefined,
+            guidance: "A refill run is already active for this workspace. Use the original handle or wait for the lease TTL window before retrying takeover.",
+        };
+    }
+    const result = started;
+    const runId = stringValue(result.runId);
+    const fence = numberValue(result.fence);
+    if (!runId || fence == null) {
+        return {
+            status: "blocked",
+            blocker: "bad_start_response",
+            guidance: "The refill run route returned an unusable start response.",
+            report: { response: started },
+        };
+    }
+    const gate = (stringValue(result.gate) ?? "g0_bootstrap");
+    const gateSeq = numberValue(result.gateSeq) ?? 0;
+    const runState = recordValue(result.runState) ??
+        recordValue(initialRunState) ??
+        {
+            version: 1,
+            senderCursors: [],
+            laneCooldowns: [],
+            passRates: [],
+        };
+    const journalPath = await createJournal(input, deps, runId);
+    const ctx = {
+        workspaceId: input.workspaceId,
+        runId,
+        fence,
+        gate,
+        gateSeq,
+        runState,
+        journalPath,
+        plan: null,
+        headAction: null,
+        lastFingerprint: null,
+        recoveryPoint: recordValue(result.recoveryPoint),
+        gateCycles: 0,
+        sleptMs: 0,
+        blockedContinuations: [],
+        lanesStarted: [],
+        lanesTouched: [],
+    };
+    const takeover = recordValue(result.takeover);
+    if (takeover && takeover.crashed === true) {
+        await safeJournalAppend(ctx, deps, deps.journal.renderCrashedAbandonedSection({
+            runId,
+            priorGate: stringValue(takeover.priorGate) ?? gate,
+            decidedAt: (deps.now?.() ?? new Date()).toISOString(),
+        }));
+    }
+    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 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 receipts = [];
+    for (const entry of paidCredit) {
+        const senderId = stringValue(entry.senderId);
+        if (!senderId ||
+            !entry.plannedJitRefresh ||
+            refreshedSenderIds.has(senderId)) {
+            continue;
+        }
+        const receipt = await deps.executors.refreshPaidInmailCreditsWithRetry(senderId, input.workspaceId);
+        receipts.push({ senderId, receipt });
+        refreshedSenderIds.add(senderId);
+    }
+    const nextRunState = mergeRunState(ctx.runState, {
+        creditTrust: {
+            refreshedAt: (deps.now?.() ?? new Date()).toISOString(),
+            senderIds: [...refreshedSenderIds],
+            receipts,
+        },
+    });
+    await safeJournalAppend(ctx, deps, deps.journal.renderBootstrapSection({
+        summary: "Refill v2 execution bootstrap",
+        senderSummary: safeJson(recordValue(plan.bootstrap)?.senders ?? []),
+        laneSummary: safeJson(recordValue(plan.bootstrap)?.laneOrder ?? []),
+        targetSummary: safeJson(recordValue(plan.bootstrap)?.target ?? []),
+        creditSummary: safeJson(recordValue(plan.bootstrap)?.paidCredit ?? []),
+    }));
+    const advanced = await deps.runClient.advanceRefillRunGateRemote({
+        workspaceId: input.workspaceId,
+        runId: ctx.runId,
+        fence: ctx.fence,
+        expectedSeq: ctx.gateSeq,
+        nextGate: "g1_plan",
+        runState: nextRunState,
+    });
+    if (isLeaseLost(advanced))
+        return leaseLostResult(ctx);
+    ctx.gate = "g1_plan";
+    ctx.gateSeq += 1;
+    ctx.runState = nextRunState;
+    return null;
+}
+async function completeTerminal(input, deps, ctx, doneReasonInput, reportInput = {}) {
+    const doneReason = normalizeDoneReason(doneReasonInput);
+    const coverage = ctx.plan
+        ? coverageSnapshot(ctx.plan)
+        : { sent: 0, scheduled: 0, ready: 0, goal: 0 };
+    const progress = {
+        sendsLoaded: numberValue(reportInput.sendsLoaded) ??
+            (coverage.scheduled ?? 0) + (coverage.sent ?? 0),
+        lanesTouched: ctx.lanesTouched,
+        lanesStarted: ctx.lanesStarted,
+        gateCycles: ctx.gateCycles,
+        blockedLanes: ctx.blockedContinuations,
+        ...(recordValue(reportInput.progress) ?? {}),
+    };
+    const report = {
+        doneReason,
+        coverage,
+        lanesTouched: ctx.lanesTouched,
+        lanesStarted: ctx.lanesStarted,
+        blockedContinuations: ctx.blockedContinuations,
+        journalPath: ctx.journalPath,
+        ...reportInput,
+    };
+    const terminalRunState = mergeRunState(ctx.runState, {
+        terminal: {
+            doneReason,
+            completedAt: (deps.now?.() ?? new Date()).toISOString(),
+        },
+    });
+    const advanced = await deps.runClient.advanceRefillRunGateRemote({
+        workspaceId: input.workspaceId,
+        runId: ctx.runId,
+        fence: ctx.fence,
+        expectedSeq: ctx.gateSeq,
+        nextGate: "g4_terminal",
+        doneReason,
+        progress,
+        runState: terminalRunState,
+    });
+    if (isLeaseLost(advanced))
+        return leaseLostResult(ctx);
+    ctx.gate = "g4_terminal";
+    ctx.gateSeq += 1;
+    ctx.runState = terminalRunState;
+    const completed = await deps.runClient.completeRefillRun({
+        workspaceId: input.workspaceId,
+        runId: ctx.runId,
+        fence: ctx.fence,
+        doneReason,
+        progress,
+    });
+    if (isLeaseLost(completed))
+        return leaseLostResult(ctx);
+    await safeJournalAppend(ctx, deps, deps.journal.renderTerminalSection({
+        summary: `Run ended with ${doneReason}.`,
+        finalNumbers: doneReason === "loaded_awaiting_scheduler"
+            ? `remainingReady=${String(reportInput.remainingReady ?? "unknown")}; expectedPickupAt=${String(reportInput.expectedPickupAt ?? "unknown")}; resume={runId:${ctx.runId},fence:${ctx.fence},gate:${ctx.gate}}`
+            : undefined,
+        executionNumbers: {
+            doneReason,
+            sendsLoaded: progress.sendsLoaded,
+            lanesTouched: ctx.lanesTouched,
+            lanesStarted: ctx.lanesStarted,
+            gateCycles: ctx.gateCycles,
+        },
+    }));
+    const fileName = filenameFromPath(ctx.journalPath);
+    if (fileName && deps.journal.appendIndexLine) {
+        deps.journal.appendIndexLine({
+            runId: ctx.runId,
+            fileName,
+            workspaceId: input.workspaceId,
+            dryRun: false,
+            summary: doneReason,
+        });
+    }
+    await safeLocalStateWrite(input, deps, {
+        runSummary: {
+            runId: ctx.runId,
+            endedAt: (deps.now?.() ?? new Date()).toISOString(),
+            terminalState: doneReason,
+            sendsLoaded: progress.sendsLoaded,
+            lanesTouched: ctx.lanesTouched,
+        },
+    });
+    return {
+        status: "terminal",
+        doneReason,
+        report,
+        runId: ctx.runId,
+        journalPath: ctx.journalPath,
+    };
+}
+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,
+    });
+    if (plan.blocker === "workspace_access") {
+        return {
+            status: "blocked",
+            blocker: "workspace_access",
+            runId: ctx.runId,
+            fence: ctx.fence,
+            gate: ctx.gate,
+            guidance: stringValue(plan.guidance) ?? "Workspace access blocked.",
+            journalPath: ctx.journalPath,
+            report: plan,
+        };
+    }
+    const coherenceFailure = packetCoherenceFailure(plan);
+    if (coherenceFailure) {
+        await safeJournalAppend(ctx, deps, deps.journal.renderPlanSection({
+            chosenSummary: `packet_incoherent: ${coherenceFailure}`,
+            itinerarySummaries: [],
+            fallbackSummary: "replan once before blocking",
+        }));
+        return {
+            status: "blocked",
+            blocker: "packet_incoherent",
+            runId: ctx.runId,
+            fence: ctx.fence,
+            gate: ctx.gate,
+            guidance: `Planner returned an incoherent packet: ${coherenceFailure}.`,
+            report: { coherenceFailure, plan },
+            journalPath: ctx.journalPath,
+        };
+    }
+    const action = firstAction(plan);
+    const doneReason = doneReasonFromPlan(plan);
+    ctx.plan = plan;
+    if (!action) {
+        if (doneReason) {
+            return completeTerminal(input, deps, ctx, doneReason, { plan });
+        }
+        return {
+            status: "blocked",
+            blocker: "empty_queue_no_reason",
+            runId: ctx.runId,
+            fence: ctx.fence,
+            gate: ctx.gate,
+            guidance: "Planner returned an empty queue without a doneReason.",
+            report: { doneReason, plan },
+            journalPath: ctx.journalPath,
+        };
+    }
+    if (doneReason && stringValue(action.type) === "done") {
+        return completeTerminal(input, deps, ctx, doneReason, { plan });
+    }
+    const line = getPlanLine(plan);
+    await safeJournalAppend(ctx, deps, deps.journal.renderPlanSection({
+        chosenSummary: line.chosenSummary,
+        itinerarySummaries: line.projectedSummaries,
+        fallbackSummary: line.fallbackSummary,
+    }));
+    const fingerprint = fingerprintFromPlan(plan);
+    const noProgress = nextNoProgressState(ctx, plan, action);
+    if (noProgress.repeatCount >= 3) {
+        return completeTerminal(input, deps, ctx, "blocked", {
+            blocker: "no_forward_progress",
+            stuckRung: stringValue(action.evergreenRung) ?? stringValue(action.type),
+            repeatedHeadAction: action,
+            progress: { noProgress },
+            guidance: "The same refill rung repeated three times with no coverage, frontier, or lane movement.",
+        });
+    }
+    const nextRunState = mergeRunState(ctx.runState, {
+        lastPlan: fingerprint,
+        headAction: action,
+        progress: mergeProgress(ctx, { noProgress }),
+    });
+    const advanced = await deps.runClient.advanceRefillRunGateRemote({
+        workspaceId: input.workspaceId,
+        runId: ctx.runId,
+        fence: ctx.fence,
+        expectedSeq: ctx.gateSeq,
+        nextGate: "g2_execute",
+        runState: nextRunState,
+        planRevision: fingerprint.planRevision,
+        stateRevision: fingerprint.stateRevision,
+        targetShapeRevision: fingerprint.targetShapeRevision,
+    });
+    if (isLeaseLost(advanced))
+        return leaseLostResult(ctx);
+    ctx.gate = "g2_execute";
+    ctx.gateSeq += 1;
+    ctx.runState = nextRunState;
+    ctx.headAction = action;
+    ctx.lastFingerprint = fingerprint;
+    return null;
+}
+async function verifyRecoveryPoint(input, deps, ctx) {
+    if (!ctx.recoveryPoint)
+        return null;
+    const planned = recordValue(ctx.recoveryPoint.planned) ?? {};
+    const expected = {
+        planRevision: stringValue(planned.planRevision),
+        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 changed = fingerprintChanged(expected, fingerprintFromPlan(fresh));
+    if (changed.length > 0) {
+        await deps.runClient.recordRunOutcome({
+            workspaceId: input.workspaceId,
+            runId: ctx.runId,
+            fence: ctx.fence,
+            eventId: stringValue(ctx.recoveryPoint.eventId) ?? `${ctx.runId}:recovery`,
+            did: { reverified: true },
+            outcome: { status: "stale_refused", changed },
+        });
+        ctx.recoveryPoint = null;
+        ctx.gate = "g1_plan";
+        return null;
+    }
+    ctx.recoveryPoint = null;
+    return null;
+}
+async function gateExecute(input, deps, ctx) {
+    const recoveryResult = await verifyRecoveryPoint(input, deps, ctx);
+    if (recoveryResult)
+        return recoveryResult;
+    if (ctx.gate !== "g2_execute")
+        return null;
+    const action = ctx.headAction;
+    const plan = ctx.plan;
+    if (!action || !plan) {
+        ctx.gate = "g1_plan";
+        return null;
+    }
+    if (action.yoloEligible === false) {
+        const continuation = {
+            action,
+            handoff: action.type === "continue_sales_nav_source" ||
+                action.type === "continue_prospeo_source"
+                ? sourceHandoffText(action)
+                : undefined,
+        };
+        ctx.blockedContinuations.push(continuation);
+        await safeJournalAppend(ctx, deps, deps.journal.renderExecutionEventSection({
+            gate: ctx.gate,
+            rung: stringValue(action.evergreenRung),
+            planned: {
+                toolName: stringValue(action.toolName),
+                inputSummary: safeJson(continuation),
+                planRevision: ctx.lastFingerprint?.planRevision,
+            },
+            outcome: "blocked continuation packet recorded",
+        }));
+        return {
+            status: "blocked",
+            blocker: "non_yolo_action",
+            runId: ctx.runId,
+            fence: ctx.fence,
+            gate: ctx.gate,
+            guidance: "The head refill action requires explicit continuation.",
+            report: continuation,
+            journalPath: ctx.journalPath,
+        };
+    }
+    const planned = {
+        toolName: stringValue(action.toolName),
+        toolInput: actionToolInput(action),
+        planRevision: ctx.lastFingerprint?.planRevision,
+        stateRevision: ctx.lastFingerprint?.stateRevision,
+        targetShapeRevision: ctx.lastFingerprint?.targetShapeRevision,
+        dispatchKey: stringValue(action.type),
+        evergreenRung: stringValue(action.evergreenRung),
+        sideEffectClass: stringValue(action.sideEffectClass),
+    };
+    const plannedResult = await deps.runClient.recordRunPlanned({
+        workspaceId: input.workspaceId,
+        runId: ctx.runId,
+        fence: ctx.fence,
+        gate: ctx.gate,
+        gateSeq: ctx.gateSeq,
+        planned,
+    });
+    if (isLeaseLost(plannedResult))
+        return leaseLostResult(ctx);
+    const eventId = stringValue(recordValue(plannedResult)?.eventId) ??
+        `${ctx.runId}:${ctx.gateSeq}`;
+    let did;
+    let outcome;
+    if (action.type === "start_paused_campaign") {
+        did = await deps.executors.executeStartCampaignPrimitive({
+            action,
+            workspaceId: input.workspaceId,
+            authority: selectedLaneAuthority(plan, action),
+        });
+        outcome = did;
+    }
+    else {
+        did = await deps.executors.executeOneYoloPrimitive({
+            ...action,
+            toolInput: {
+                ...actionToolInput(action),
+                approvalMode: input.approvalMode ?? actionToolInput(action).approvalMode,
+            },
+        }, input.workspaceId);
+        outcome = did;
+    }
+    await deps.runClient.recordRunOutcome({
+        workspaceId: input.workspaceId,
+        runId: ctx.runId,
+        fence: ctx.fence,
+        eventId,
+        did,
+        outcome,
+    });
+    await safeJournalAppend(ctx, deps, deps.journal.renderExecutionEventSection({
+        gate: ctx.gate,
+        rung: stringValue(action.evergreenRung),
+        planned: {
+            toolName: stringValue(action.toolName),
+            inputSummary: safeJson(planned.toolInput),
+            planRevision: ctx.lastFingerprint?.planRevision,
+        },
+        did: safeJson(did),
+        outcome: safeJson(outcome),
+    }));
+    const nextRunState = mergeRunState(ctx.runState, {
+        lastEventId: eventId,
+        lastExecutedAction: action,
+        lastOutcome: outcome,
+    });
+    const advanced = await deps.runClient.advanceRefillRunGateRemote({
+        workspaceId: input.workspaceId,
+        runId: ctx.runId,
+        fence: ctx.fence,
+        expectedSeq: ctx.gateSeq,
+        nextGate: "g3_verify",
+        runState: nextRunState,
+    });
+    if (isLeaseLost(advanced))
+        return leaseLostResult(ctx);
+    ctx.gate = "g3_verify";
+    ctx.gateSeq += 1;
+    ctx.runState = nextRunState;
+    return null;
+}
+async function advanceBackToPlan(input, deps, ctx, runStateUpdates = {}) {
+    const nextRunState = mergeRunState(ctx.runState, runStateUpdates);
+    const advanced = await deps.runClient.advanceRefillRunGateRemote({
+        workspaceId: input.workspaceId,
+        runId: ctx.runId,
+        fence: ctx.fence,
+        expectedSeq: ctx.gateSeq,
+        nextGate: "g1_plan",
+        runState: nextRunState,
+    });
+    if (isLeaseLost(advanced))
+        return leaseLostResult(ctx);
+    ctx.gate = "g1_plan";
+    ctx.gateSeq += 1;
+    ctx.runState = nextRunState;
+    ctx.headAction = null;
+    return null;
+}
+async function verifyPrepareAction(input, deps, ctx, action, budgets) {
+    const getStatus = deps.executors.getPrepareCampaignMessagesStatus;
+    const jobId = activeJobIdFromOutcome(ctx.runState.lastOutcome);
+    if (!getStatus || !jobId) {
+        return {
+            status: "in_progress",
+            runId: ctx.runId,
+            fence: ctx.fence,
+            gate: ctx.gate,
+            guidance: "Preparation dispatch has no status hook or job id yet; re-invoke with the same handle after the job appears in the run record.",
+            journalPath: ctx.journalPath,
+        };
+    }
+    const expectedHash = expectedPrepareRequestHash(deps, action);
+    const tableId = stringValue(actionToolInput(action).tableId) ?? undefined;
+    const campaignId = actionCampaignId(action) ?? undefined;
+    let latestStatus = null;
+    for (let poll = 0; poll < budgets.maxPollsPerWait; poll += 1) {
+        latestStatus = await getStatus({
+            workspaceId: input.workspaceId,
+            jobId,
+            campaignId,
+            tableId,
+        });
+        const statusRecord = recordValue(latestStatus) ?? {};
+        const requestSource = stringValue(statusRecord.requestSource);
+        const requestHash = stringValue(statusRecord.requestHash);
+        const ownJob = requestSource === "refill_sends" &&
+            (!expectedHash || requestHash === expectedHash);
+        if (!ownJob && !isTerminalJobStatus(latestStatus)) {
+            const waitResult = await sleepForWait(input, deps, ctx, budgets);
+            if (waitResult)
+                return waitResult;
+            continue;
+        }
+        if (!ownJob && isTerminalJobStatus(latestStatus)) {
+            return advanceBackToPlan(input, deps, ctx, {
+                progress: mergeProgress(ctx, {
+                    foreignPrepClearedAt: (deps.now?.() ?? new Date()).toISOString(),
+                }),
+            });
+        }
+        if (isTerminalJobStatus(latestStatus)) {
+            const preparedCount = preparedCountFromStatus(latestStatus);
+            const checkedRows = checkedRowsFromStatus(latestStatus);
+            await deps.runClient.recordRunOutcome({
+                workspaceId: input.workspaceId,
+                runId: ctx.runId,
+                fence: ctx.fence,
+                eventId: lastEventId(ctx),
+                outcome: {
+                    status: "verified",
+                    stopReason: stringValue(statusRecord.stopReason),
+                    preparedCount,
+                    checkedRows,
+                },
+            });
+            await safeJournalAppend(ctx, deps, deps.journal.renderExecutionEventSection({
+                gate: ctx.gate,
+                rung: stringValue(action.evergreenRung),
+                planned: {
+                    toolName: "get_campaign_message_preparation_status",
+                    inputSummary: `jobId=${jobId}`,
+                    planRevision: ctx.lastFingerprint?.planRevision,
+                },
+                did: safeJson(latestStatus),
+                outcome: `conversion-verdict: prepared ${preparedCount}/${checkedRows}`,
+            }));
+            await safeLocalStateWrite(input, deps, {
+                passRates: [
+                    {
+                        campaignId: actionCampaignId(action) ?? "unknown",
+                        enrichedCount: checkedRows,
+                        passedCount: preparedCount,
+                        observedAt: (deps.now?.() ?? new Date()).toISOString(),
+                    },
+                ],
+            });
+            return advanceBackToPlan(input, deps, ctx, {
+                progress: mergeProgress(ctx, {
+                    lastPrepStopReason: stringValue(statusRecord.stopReason),
+                    lastPreparedCount: preparedCount,
+                    lastCheckedRows: checkedRows,
+                }),
+            });
+        }
+        const waitResult = await sleepForWait(input, deps, ctx, budgets);
+        if (waitResult)
+            return waitResult;
+    }
+    return {
+        status: "blocked",
+        blocker: "foreign_prep_active",
+        runId: ctx.runId,
+        fence: ctx.fence,
+        gate: ctx.gate,
+        guidance: "A preparation job is still active and did not verify within the bounded poll budget.",
+        report: { jobId, latestStatus },
+        journalPath: ctx.journalPath,
+    };
+}
+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,
+        });
+        ctx.plan = fresh;
+        const doneReason = doneReasonFromPlan(fresh);
+        if (doneReason) {
+            return completeTerminal(input, deps, ctx, doneReason, {
+                plan: fresh,
+                waitKind,
+            });
+        }
+        const action = firstAction(fresh);
+        if (stringValue(action?.type) !== waitKind) {
+            return advanceBackToPlan(input, deps, ctx, {
+                progress: mergeProgress(ctx, {
+                    [`${waitKind}ClearedAt`]: (deps.now?.() ?? new Date()).toISOString(),
+                }),
+            });
+        }
+        const waitResult = await sleepForWait(input, deps, ctx, budgets);
+        if (waitResult)
+            return waitResult;
+    }
+    return heartbeatAndContinue(input, deps, ctx);
+}
+async function verifySchedulerWait(input, deps, ctx, action, budgets) {
+    const progress = runStateProgress(ctx);
+    const enteredAt = stringValue(progress.schedulerWaitEnteredAt) ??
+        (deps.now?.() ?? new Date()).toISOString();
+    const jitFired = booleanValue(progress.schedulerJitFired) ?? false;
+    if (!jitFired) {
+        const senderId = actionSenderId(action);
+        if (senderId) {
+            await deps.executors.refreshPaidInmailCreditsWithRetry(senderId, input.workspaceId);
+        }
+        if (deps.requestSchedulerRun) {
+            await deps.requestSchedulerRun(input.workspaceId);
+        }
+        ctx.runState = mergeRunState(ctx.runState, {
+            progress: mergeProgress(ctx, {
+                schedulerWaitEnteredAt: enteredAt,
+                schedulerJitFired: true,
+            }),
+        });
+    }
+    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,
+        });
+        ctx.plan = fresh;
+        const doneReason = normalizeDoneReason(doneReasonFromPlan(fresh));
+        if (doneReason === "complete" || doneReason === "capped_by_scheduler") {
+            return completeTerminal(input, deps, ctx, doneReason, { plan: fresh });
+        }
+        if (doneReason === "loaded_awaiting_scheduler") {
+            return completeTerminal(input, deps, ctx, doneReason, {
+                plan: fresh,
+                remainingReady: numberValue(fresh.remainingReady) ?? "unknown",
+                expectedPickupAt: stringValue(fresh.expectedPickupAt) ??
+                    stringValue(recordValue(fresh.packet)?.expectedPickupAt) ??
+                    "next scheduler sweep",
+                resume: { runId: ctx.runId, fence: ctx.fence, gate: ctx.gate },
+            });
+        }
+        const waitResult = await sleepForWait(input, deps, ctx, budgets);
+        if (waitResult?.status === "in_progress") {
+            return {
+                ...waitResult,
+                guidance: `scheduler sweep in progress since ${enteredAt}; re-invoke with this handle`,
+            };
+        }
+        if (waitResult)
+            return waitResult;
+    }
+    return heartbeatAndContinue(input, deps, ctx);
+}
+async function gateVerify(input, deps, ctx, budgets) {
+    if (ctx.gate !== "g3_verify")
+        return null;
+    const action = lastAction(ctx);
+    if (!action) {
+        return advanceBackToPlan(input, deps, ctx);
+    }
+    const actionType = stringValue(action.type);
+    if (actionType === "prepare_messages") {
+        return verifyPrepareAction(input, deps, ctx, action, budgets);
+    }
+    if (actionType === "start_paused_campaign") {
+        return {
+            status: "in_progress",
+            runId: ctx.runId,
+            fence: ctx.fence,
+            gate: ctx.gate,
+            guidance: "Campaign start was dispatched and recorded. Re-invoke with this handle so the next plan read starts from the new campaign state.",
+            journalPath: ctx.journalPath,
+        };
+    }
+    if (actionType === "wait_for_scheduler") {
+        return verifySchedulerWait(input, deps, ctx, action, budgets);
+    }
+    if (actionType === "wait_for_active_work" ||
+        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,
+    });
+    ctx.plan = fresh;
+    const doneReason = doneReasonFromPlan(fresh);
+    if (doneReason) {
+        return completeTerminal(input, deps, ctx, doneReason, { plan: fresh });
+    }
+    return advanceBackToPlan(input, deps, ctx);
+}
+function leaseLostResult(ctx) {
+    return {
+        status: "blocked",
+        blocker: "lease_lost",
+        runId: ctx.runId,
+        fence: ctx.fence,
+        gate: ctx.gate,
+        guidance: "Refill run lease was lost. Re-invoke with a fresh handle or wait for lease takeover.",
+        journalPath: ctx.journalPath,
+    };
+}
+function classifyCaughtError(error, ctx) {
+    const message = error instanceof Error ? error.message : String(error);
+    if (error instanceof SellableApiError &&
+        error.status >= 400 &&
+        error.status < 500) {
+        return {
+            status: "blocked",
+            blocker: "deterministic_api_error",
+            runId: ctx?.runId,
+            fence: ctx?.fence,
+            gate: ctx?.gate,
+            guidance: message,
+            report: { status: error.status, body: error.body },
+            journalPath: ctx?.journalPath,
+        };
+    }
+    if (ctx) {
+        return {
+            status: "in_progress",
+            runId: ctx.runId,
+            fence: ctx.fence,
+            gate: ctx.gate,
+            guidance: `Transient refill loop error recorded; re-invoke with this handle. ${message}`,
+            journalPath: ctx.journalPath,
+        };
+    }
+    return {
+        status: "blocked",
+        blocker: "loop_error",
+        guidance: message,
+    };
+}
+async function heartbeatAndContinue(input, deps, ctx) {
+    const heartbeat = await deps.runClient.heartbeatRefillRun({
+        workspaceId: input.workspaceId,
+        runId: ctx.runId,
+        fence: ctx.fence,
+    });
+    if (isLeaseLost(heartbeat))
+        return leaseLostResult(ctx);
+    return {
+        status: "in_progress",
+        runId: ctx.runId,
+        fence: ctx.fence,
+        gate: ctx.gate,
+        guidance: "Per-invocation gate budget reached. Re-invoke refill_sends_v2 with this runId/fence to continue.",
+        journalPath: ctx.journalPath,
+    };
+}
+export async function runRefillV2Loop(input, deps) {
+    const budgets = { ...DEFAULT_BUDGETS, ...(deps.budgets ?? {}) };
+    let ctx = null;
+    try {
+        if (input.dryRun) {
+            const plan = await deps.readPlan({
+                workspaceId: input.workspaceId,
+                intent: input.intent,
+                senderIds: input.senderIds,
+                journal: true,
+            });
+            return { status: "dry_run", plan };
+        }
+        const started = await startOrResume(input, deps);
+        if ("status" in started)
+            return started;
+        ctx = started;
+        for (let cycle = 0; cycle < budgets.maxGateCyclesPerInvocation; cycle += 1) {
+            ctx.gateCycles += 1;
+            if (ctx.gate === "g0_bootstrap") {
+                const result = await gateBootstrap(input, deps, ctx);
+                if (result)
+                    return result;
+                continue;
+            }
+            if (ctx.gate === "g1_plan") {
+                const result = await gatePlan(input, deps, ctx);
+                if (result)
+                    return result;
+                continue;
+            }
+            if (ctx.gate === "g2_execute") {
+                const result = await gateExecute(input, deps, ctx);
+                if (result)
+                    return result;
+                continue;
+            }
+            if (ctx.gate === "g3_verify") {
+                const result = await gateVerify(input, deps, ctx, budgets);
+                if (result)
+                    return result;
+                continue;
+            }
+            if (ctx.gate === "g4_terminal") {
+                return {
+                    status: "terminal",
+                    doneReason: normalizeDoneReason(recordValue(ctx.runState.terminal)?.doneReason),
+                    report: {
+                        doneReason: normalizeDoneReason(recordValue(ctx.runState.terminal)?.doneReason),
+                        journalPath: ctx.journalPath,
+                    },
+                    runId: ctx.runId,
+                    journalPath: ctx.journalPath,
+                };
+            }
+        }
+        return heartbeatAndContinue(input, deps, ctx);
+    }
+    catch (error) {
+        return classifyCaughtError(error, ctx);
+    }
+}