@sellable/mcp 0.1.793 → 0.1.794

package/dist/tools/refill-executors.js

@@ -1,11 +1,11 @@
 import { createHash } from "node:crypto";
 import { getApi, SellableApiError } from "../api.js";
 import { decodeRefillReadinessAuthority, decodeRefillSchedulerDateGuards, refillReadinessExpectationInput, refillReadinessFingerprint, } from "../refill-readiness.js";
+import { hasTerminalSchedulerReceipt, normalizeSchedulerChangedCounts, normalizeSchedulerPrimitiveResult, numberValue, recordValue, SCHEDULER_ATTACHING_ENVELOPE_STATUSES, schedulerEnvelopeIsTerminal, stringArray, stringValue, } from "../scheduler-envelope.js";
 import { startPrepareCampaignMessages } from "./campaign-message-preparation.js";
 import { normalizeMessageTemplateRevision, normalizeRefillRunHandle, normalizeRefillTargetConfig, reviseMessageTemplateAndRerun, } from "./campaign-processing.js";
 import { startCampaign } from "./campaigns.js";
 import { confirmLeadList, importLeads, searchProspeo, searchSalesNav, searchSignals, selectPromisingPosts, } from "./leads.js";
-import { markProviderPromptLoaded } from "./provider-preflight.js";
 import { refreshSenderEngagementCommand } from "./refresh-sender-engagement.js";
 import { runSchedulerSweep, } from "./scheduler-run.js";
 import { refreshPaidInmailCredits } from "./senders.js";
@@ -51,6 +51,80 @@ const USABLE_PAID_INMAIL_REFRESH_RECEIPT_STATUSES = new Set([
     "refreshed",
     "below_threshold",
 ]);
+// ───────────────────────────────────────────────────────────────────────────
+// Refill V3 source-dispatch seam (Phase 146.5 Plan 09 T3, RV3PRM-002).
+//
+// T3 is the SOLE STRUCTURAL owner of this seam (`A09-EXECUTORS-SERIALIZATION`):
+// it introduces the receipt-shape extension and the dispatcher call seam, and
+// T4/T5 make only additive table-entry and characterization changes. There is
+// EXACTLY ONE receipt-normalization path for source dispatch, because a second
+// one would let two families' receipts drift apart silently (error law 2).
+// ───────────────────────────────────────────────────────────────────────────
+/**
+ * Normalize ONE existing family owner's `YoloPrimitiveAttempt` into the closed
+ * dispatch outcome. Missing or uncertain effect evidence is NEVER success:
+ * `no_action` is a bounded zero-yield success only when its receipt carries
+ * before/after evidence, and a refusal or an absent receipt is a typed failure.
+ */
+/**
+ * The V3 source path is SINGLE-PASS by construction.
+ *
+ * V1 keeps its two-attempt signal helper and its depth-scaled provider target;
+ * V3 removes both. `searchSignalsWithProviderRetry` hides TWO transport attempts
+ * inside one "bounded" owner call, and `priorSearchDepth` is retry/expansion
+ * MEMORY that multiplies the target the AI never asked for. Under V3 a provider
+ * outcome is a typed no-effect receipt followed by a reread, and only a later
+ * fresh attention iteration may choose another action.
+ */
+export const REFILL_V3_SIGNAL_SEARCH_ATTEMPTS = 1;
+export function isRefillV3SinglePassAction(action) {
+    return actionToolInput(action).refillV3SinglePass === true;
+}
+export function normalizeRefillV3SourceOwnerReceipt(params) {
+    const { attempt, ownerKey, requestFingerprint, idempotencyKey } = params;
+    if (attempt.status === "refused") {
+        return {
+            kind: "failure",
+            failureClass: "owner_threw",
+            detail: attempt.refusalReason ?? `${ownerKey} refused without a reason`,
+        };
+    }
+    const record = recordValue(attempt.result) ?? {};
+    const before = stringValue(record.sourceBeforeFingerprint);
+    const after = stringValue(record.sourceAfterFingerprint);
+    if (!before || !after) {
+        return { kind: "timeout", effectIdentity: null };
+    }
+    const importedCount = Math.max(0, numberValue(record.importedCount) ?? 0);
+    const receipt = {
+        ownerKey,
+        requestFingerprint,
+        idempotencyKey,
+        sourceBeforeFingerprint: before,
+        sourceAfterFingerprint: after,
+        sourceBeforeCount: Math.max(0, numberValue(record.sourceBeforeCount) ?? 0),
+        sourceAfterCount: Math.max(0, numberValue(record.sourceAfterCount) ?? 0),
+        importedCount,
+        effects: stringArray(record.effects),
+        replayState: stringValue(record.replayState) === "exact_replay"
+            ? "exact_replay"
+            : importedCount > 0
+                ? "first"
+                : "not_applicable",
+        rollback: importedCount > 0
+            ? {
+                available: true,
+                input: recordValue(record.rollbackInput) ?? {},
+                result: stringValue(record.rollbackResult),
+            }
+            : { available: false, reason: "not_applicable" },
+        postRationales: null,
+        yieldEvidence: null,
+    };
+    return importedCount > 0
+        ? { kind: "receipt", receipt }
+        : { kind: "no_effect", receipt };
+}
 function isSenderOwnedPostEngagersCampaign(campaign) {
     return Boolean((campaign.leadSourceProvider === "signal-discovery" ||
         campaign.leadSourceProvider === "campaign-tracked-post") &&
@@ -148,152 +222,6 @@ export function sleep(ms) {
         return Promise.resolve();
     return new Promise((resolve) => setTimeout(resolve, ms));
 }
-export function recordValue(value) {
-    return value && typeof value === "object" && !Array.isArray(value)
-        ? value
-        : null;
-}
-export function stringValue(value) {
-    return typeof value === "string" && value.trim() ? value.trim() : null;
-}
-export function numberValue(value) {
-    return typeof value === "number" && Number.isFinite(value) ? value : null;
-}
-export function normalizeSchedulerChangedCounts(value) {
-    const changedCounts = recordValue(value);
-    if (!changedCounts ||
-        changedCounts.complete !== true ||
-        changedCounts.truncated !== false) {
-        return null;
-    }
-    const total = numberValue(changedCounts.total);
-    if (total === null || total < 0 || !Number.isInteger(total))
-        return null;
-    if (!Array.isArray(changedCounts.byCampaignTableActionType))
-        return null;
-    const groups = [];
-    const seen = new Set();
-    for (const rawGroup of changedCounts.byCampaignTableActionType) {
-        const group = recordValue(rawGroup);
-        const campaignId = stringValue(group?.campaignId);
-        const tableId = stringValue(group?.tableId);
-        const actionType = stringValue(group?.actionType);
-        const count = numberValue(group?.count);
-        if (!campaignId ||
-            !tableId ||
-            !actionType ||
-            count === null ||
-            count <= 0 ||
-            !Number.isInteger(count)) {
-            return null;
-        }
-        const key = `${campaignId}:${tableId}:${actionType}`;
-        if (seen.has(key))
-            return null;
-        seen.add(key);
-        groups.push({ campaignId, tableId, actionType, count });
-    }
-    groups.sort((a, b) => {
-        if (a.campaignId !== b.campaignId) {
-            return a.campaignId.localeCompare(b.campaignId);
-        }
-        if (a.tableId !== b.tableId)
-            return a.tableId.localeCompare(b.tableId);
-        return a.actionType.localeCompare(b.actionType);
-    });
-    if (groups.reduce((sum, group) => sum + group.count, 0) !== total) {
-        return null;
-    }
-    if (!Array.isArray(changedCounts.byCampaignTableActionTypeSender)) {
-        return null;
-    }
-    const senderGroups = [];
-    const senderSeen = new Set();
-    for (const rawGroup of changedCounts.byCampaignTableActionTypeSender) {
-        const group = recordValue(rawGroup);
-        const campaignId = stringValue(group?.campaignId);
-        const tableId = stringValue(group?.tableId);
-        const actionType = stringValue(group?.actionType);
-        const senderId = stringValue(group?.senderId);
-        const count = numberValue(group?.count);
-        if (!campaignId ||
-            !tableId ||
-            !actionType ||
-            !senderId ||
-            count === null ||
-            count <= 0 ||
-            !Number.isInteger(count)) {
-            return null;
-        }
-        const key = `${campaignId}:${tableId}:${actionType}:${senderId}`;
-        if (senderSeen.has(key))
-            return null;
-        senderSeen.add(key);
-        senderGroups.push({ campaignId, tableId, actionType, senderId, count });
-    }
-    if (senderGroups.reduce((sum, group) => sum + group.count, 0) !== total) {
-        return null;
-    }
-    return {
-        complete: true,
-        truncated: false,
-        total,
-        byCampaignTableActionType: groups,
-        byCampaignTableActionTypeSender: senderGroups,
-    };
-}
-function completeExpectedTargetSummary(value, expectedTargets, maxPlacements) {
-    const summary = recordValue(value);
-    const items = Array.isArray(summary?.items) ? summary.items : [];
-    if (summary?.complete !== true ||
-        summary.truncated !== false ||
-        numberValue(summary.requested) !== expectedTargets.length ||
-        numberValue(summary.included) == null ||
-        numberValue(summary.omitted) == null ||
-        numberValue(summary.included) + numberValue(summary.omitted) !==
-            expectedTargets.length ||
-        numberValue(summary.maxPlacements) !== maxPlacements ||
-        items.length !== expectedTargets.length) {
-        return false;
-    }
-    return items.every((rawItem, index) => {
-        const item = recordValue(rawItem);
-        const target = expectedTargets[index];
-        const senderIds = stringArray(item?.senderIds).sort();
-        const bySender = Array.isArray(item?.bySender) ? item.bySender : [];
-        const accounted = bySender
-            .map((entry) => stringValue(recordValue(entry)?.senderId))
-            .filter((senderId) => Boolean(senderId))
-            .sort();
-        return (Boolean(target) &&
-            item?.campaignId === target?.campaignId &&
-            item?.tableId === target?.tableId &&
-            item?.refillLaneKey === target?.refillLaneKey &&
-            (item?.outcome === "included" || item?.outcome === "omitted") &&
-            JSON.stringify(senderIds) === JSON.stringify(target?.senderIds) &&
-            JSON.stringify(accounted) === JSON.stringify(target?.senderIds));
-    });
-}
-// fix(112ao-2): the scheduler's ATTACHING envelope statuses. These describe a
-// dispatch that joined an existing run rather than producing its own outcome.
-// They are terminal ONLY when the attach actually yielded a terminal receipt.
-const SCHEDULER_ATTACHING_ENVELOPE_STATUSES = new Set(["accepted", "attached"]);
-// The envelope statuses that report an outcome of this dispatch directly.
-const SCHEDULER_TERMINAL_ENVELOPE_STATUSES = new Set([
-    "ran",
-    "window_closed_noop",
-]);
-// The only receipt statuses that constitute a settled outcome. A receipt
-// without one of these is not evidence that anything finished.
-const SCHEDULER_TERMINAL_RECEIPT_STATUSES = new Set([
-    "ran",
-    "window_closed_noop",
-    "failed",
-]);
-function hasTerminalSchedulerReceipt(receipt) {
-    const status = receipt ? stringValue(receipt.status) : null;
-    return Boolean(status && SCHEDULER_TERMINAL_RECEIPT_STATUSES.has(status));
-}
 // fix(112ap): poll ONLY a genuinely in-flight attach. `!terminal` is the wrong
 // test — it is also true for `backoff` and `failed`, and re-polling those would
 // both waste the budget and misrepresent a refused dispatch as a pending one.
@@ -322,103 +250,12 @@ export function setSweepSettlePollDelayMsForTests(ms) {
 export function resetSweepSettlePollDelayMsForTests() {
     sweepSettlePollDelayMs = SWEEP_SETTLE_POLL_DEFAULT_DELAY_MS;
 }
-export function schedulerEnvelopeIsTerminal(schedulerStatus, receipt = null) {
-    if (SCHEDULER_TERMINAL_ENVELOPE_STATUSES.has(schedulerStatus))
-        return true;
-    return (SCHEDULER_ATTACHING_ENVELOPE_STATUSES.has(schedulerStatus) &&
-        hasTerminalSchedulerReceipt(receipt));
-}
-export function normalizeSchedulerPrimitiveResult(value, expected) {
-    const response = recordValue(value);
-    const receipt = recordValue(response?.receipt);
-    const schedulerStatus = stringValue(response?.status) ?? stringValue(receipt?.status) ?? "unknown";
-    const errorCode = stringValue(recordValue(response?.error)?.code);
-    // fix(112ao-2): whether this dispatch finished is decided explicitly from the
-    // envelope status plus the RECEIPT'S OWN STATUS — never from the bare
-    // presence of a receipt field.
-    //
-    // The previous guard was `!receipt && (accepted || attached)`. Truthiness is
-    // the wrong test: an attach that carries a receipt with no terminal status is
-    // not evidence that anything settled, yet it skipped this branch, ran the v3
-    // audit on that non-evidence, and could return auditComplete: true — a
-    // completion claim for a run still in flight, which the coordinator then
-    // treats as done rather than awaiting (Dotwork 2026-07-29: 21 exact runs,
-    // coverage frozen at sent:0/scheduled:0).
-    //
-    // The attach is NOT always in flight, and this deliberately does not treat it
-    // so: scheduler-run.ts:466-483 only returns a receipt from
-    // waitForSchedulerRunReceipt when it is scope-matched to THIS request, so an
-    // attach carrying a terminal receipt is a legitimate idempotent completion of
-    // this exact operation and must keep its counters. Discarding it would report
-    // zero placements for a sweep that really placed cells.
-    //
-    // `ran`/`window_closed_noop` remain terminal. `backoff`/`failed` keep their
-    // existing handling — the run loop already unwraps a backoff envelope's
-    // replayed receipt deliberately (schedulerRunReceiptIsFreshZeroScheduled).
-    if (SCHEDULER_ATTACHING_ENVELOPE_STATUSES.has(schedulerStatus) &&
-        !hasTerminalSchedulerReceipt(receipt)) {
-        return {
-            status: "matching_scheduler_active",
-            schedulerStatus,
-            terminal: false,
-            disposition: "bounded_reread_wait",
-            receipt: null,
-            // A non-terminal receipt is not this dispatch's effect. Surfaced under a
-            // distinct name so it stays readable for diagnostics but can never be
-            // mistaken for a settled outcome.
-            ...(receipt ? { unsettledReceipt: receipt } : {}),
-            retryAfterMs: numberValue(response?.retryAfterMs) ?? 30_000,
-            changedCounts: null,
-            auditComplete: false,
-        };
-    }
-    if (errorCode === "scheduler_scope_busy" ||
-        errorCode === "uncertain_outcome" ||
-        schedulerStatus === "uncertain_outcome") {
-        const status = errorCode === "scheduler_scope_busy"
-            ? "scheduler_scope_busy"
-            : "uncertain_outcome";
-        return {
-            status,
-            schedulerStatus,
-            disposition: status === "scheduler_scope_busy"
-                ? "bounded_backoff_wait"
-                : "diagnostic_stop",
-            receipt: response?.receipt ?? null,
-            retryAfterMs: numberValue(response?.retryAfterMs),
-            changedCounts: null,
-            auditComplete: false,
-            blocker: status,
-        };
-    }
-    const changedCounts = normalizeSchedulerChangedCounts(receipt?.changedCounts ?? response?.changedCounts);
-    const targetAuditComplete = !expected ||
-        (receipt?.receiptVersion === 3 &&
-            receipt.expectedTargetsHash === expected.expectedTargetsHash &&
-            receipt.maxPlacements === expected.maxPlacements &&
-            completeExpectedTargetSummary(receipt.expectedTargetSummary, expected.expectedTargets, expected.maxPlacements));
-    if (!changedCounts || !targetAuditComplete) {
-        return {
-            status: "scheduler_receipt_incomplete",
-            schedulerStatus,
-            receipt: response?.receipt ?? null,
-            retryAfterMs: numberValue(response?.retryAfterMs),
-            changedCounts: null,
-            auditComplete: false,
-            blocker: "scheduler_receipt_incomplete",
-        };
-    }
-    return {
-        status: schedulerStatus,
-        // fix(112ao-2): the completion decision, carried explicitly instead of
-        // leaving each consumer to re-infer it from the status string.
-        terminal: schedulerEnvelopeIsTerminal(schedulerStatus, receipt),
-        receipt: response?.receipt ?? null,
-        retryAfterMs: numberValue(response?.retryAfterMs),
-        changedCounts,
-        auditComplete: true,
-    };
-}
+// The scheduler envelope normalizer, the terminality predicate, and the
+// primitive value readers now live in the dependency-free package module
+// `mcp/sellable/src/scheduler-envelope.ts` so the Next app service can import
+// them without pulling this executor graph. They are re-exported here so every
+// existing caller and pin keeps its exact import path.
+export { hasTerminalSchedulerReceipt, normalizeSchedulerChangedCounts, normalizeSchedulerPrimitiveResult, numberValue, recordValue, schedulerEnvelopeIsTerminal, stringArray, stringValue, };
 function exactDateValue(value) {
     const targetDate = stringValue(value);
     if (!targetDate || !/^\d{4}-\d{2}-\d{2}$/.test(targetDate))
@@ -429,11 +266,6 @@ function exactDateValue(value) {
         ? targetDate
         : null;
 }
-export function stringArray(value) {
-    if (!Array.isArray(value))
-        return [];
-    return value.filter((item) => typeof item === "string");
-}
 export function prepareRowSelectorValue(value) {
     const selector = recordValue(value);
     const type = stringValue(selector?.type);
@@ -687,7 +519,9 @@ function rerunErroredCellsOperations(action) {
     return operations.flatMap((raw) => {
         const operation = recordValue(raw);
         const columnRole = stringValue(operation?.columnRole);
-        if (columnRole !== "icpScore" && columnRole !== "generateMessage") {
+        if (columnRole !== "enrich" &&
+            columnRole !== "icpScore" &&
+            columnRole !== "generateMessage") {
             return [];
         }
         const rowSelector = recordValue(operation?.rowSelector);
@@ -792,6 +626,19 @@ function signalSearchProviderErrors(summary) {
         : [];
     return uniqueStrings(keywordResults.map((result) => stringValue(result?.error)));
 }
+/**
+ * V3-aware single-pass entry. Under V3 `searchSignals` is called AT MOST ONCE
+ * per campaign-attention iteration with the exact validated AI keywords; a
+ * provider-unavailable result becomes a typed no-effect receipt rather than a
+ * hidden second transport attempt.
+ */
+async function searchSignalsBoundedForAction(input, action) {
+    if (isRefillV3SinglePassAction(action)) {
+        const summary = await searchSignals(input);
+        return { summary, attempts: [summary] };
+    }
+    return searchSignalsWithProviderRetry(input);
+}
 async function searchSignalsWithProviderRetry(input) {
     const attempts = [];
     for (let attempt = 0; attempt < SIGNAL_SEARCH_PROVIDER_MAX_ATTEMPTS; attempt += 1) {
@@ -1361,12 +1208,13 @@ export async function continueSignalDiscoverySource(action, workspaceId) {
             },
         };
     }
-    markProviderPromptLoaded({
-        provider: "signal-discovery",
-        campaignOfferId,
-    });
+    // Phase 146.5 Plan 09 T5: the owner self-mark is REMOVED. Only the existing
+    // `get_provider_prompt` tool may mark the exact `(campaignOfferId, provider)`
+    // preflight; an owner that marks its own preflight satisfies the gate it is
+    // supposed to be gated by, which makes the active-provider-only rule
+    // unenforceable. The assertion side of the gate is unchanged.
     const searchAttempt = keywords.length > 0
-        ? await searchSignalsWithProviderRetry({
+        ? await searchSignalsBoundedForAction({
             type: "keywords",
             keywords: keywords.map((keyword) => ({
                 keyword,
@@ -1379,7 +1227,7 @@ export async function continueSignalDiscoverySource(action, workspaceId) {
             confirmed: true,
             limit: 50,
             ...(workspaceId ? { workspaceId } : {}),
-        })
+        }, action)
         : null;
     const searchSummary = searchAttempt?.summary ?? null;
     if (searchSummary && signalSearchProviderUnavailable(searchSummary)) {
@@ -1713,10 +1561,11 @@ export async function broadenSignalSearch(action, workspaceId) {
         searchKeywords = staleKeywords;
         effectiveKeywordSource = "stale_researched";
     }
-    markProviderPromptLoaded({
-        provider: "signal-discovery",
-        campaignOfferId,
-    });
+    // Phase 146.5 Plan 09 T5: the owner self-mark is REMOVED. Only the existing
+    // `get_provider_prompt` tool may mark the exact `(campaignOfferId, provider)`
+    // preflight; an owner that marks its own preflight satisfies the gate it is
+    // supposed to be gated by, which makes the active-provider-only rule
+    // unenforceable. The assertion side of the gate is unchanged.
     let searchSummary = null;
     let providerSearchAttempts = 0;
     let runScopedDerivedTabIds = [];
@@ -1739,7 +1588,7 @@ export async function broadenSignalSearch(action, workspaceId) {
         carriedRemainder = freshCarriedPostIds.slice(scrapeCap);
     }
     else {
-        const searchAttempt = await searchSignalsWithProviderRetry({
+        const searchAttempt = await searchSignalsBoundedForAction({
             type: "keywords",
             keywords: searchKeywords.map((keyword) => ({
                 keyword,
@@ -1756,7 +1605,7 @@ export async function broadenSignalSearch(action, workspaceId) {
             confirmed: true,
             limit: 50,
             ...(workspaceId ? { workspaceId } : {}),
-        });
+        }, action);
         searchSummary = searchAttempt.summary;
         providerSearchAttempts = searchAttempt.attempts.length;
         // Derived/agent broadening keywords are transient (not the campaign's persistent
@@ -2077,10 +1926,11 @@ async function startBoundedProviderSearchClone(params) {
             receipt: { originalSearchId: snapshot.searchId },
         };
     }
-    markProviderPromptLoaded({
-        provider: params.provider,
-        campaignOfferId: params.campaignOfferId,
-    });
+    // Phase 146.5 Plan 09 T5: the owner self-mark is REMOVED. Only the existing
+    // `get_provider_prompt` tool may mark the exact `(campaignOfferId, provider)`
+    // preflight; an owner that marks its own preflight satisfies the gate it is
+    // supposed to be gated by, which makes the active-provider-only rule
+    // unenforceable. The assertion side of the gate is unchanged.
     const searchName = `${snapshot.searchName ?? "Provider search"} · refill trial`;
     const result = params.provider === "sales-nav"
         ? await searchSalesNav({
@@ -2451,9 +2301,15 @@ export async function executeProviderSavedSearch(action, workspaceId, mode) {
         numberValue(toolInput.targetRows) ??
         numberValue(action.targetRows) ??
         PROVIDER_SOURCE_CONTINUATION_DEFAULT_ROWS));
-    const priorDepth = Math.max(1, Math.floor(numberValue(toolInput.priorSearchDepth) ?? 1));
+    // V3 removes `priorSearchDepth` as retry/expansion memory: the target comes
+    // ONLY from the authoritative remaining gap and the provider caps, never from
+    // how many times the campaign has been broadened before.
+    const singlePass = isRefillV3SinglePassAction(action);
+    const priorDepth = singlePass
+        ? 1
+        : Math.max(1, Math.floor(numberValue(toolInput.priorSearchDepth) ?? 1));
     const targetLeadCount = mode === "broadening"
-        ? Math.min(PROVIDER_SEARCH_BROADEN_MAX_ROWS, baseTarget * (priorDepth + 1))
+        ? Math.min(PROVIDER_SEARCH_BROADEN_MAX_ROWS, singlePass ? baseTarget : baseTarget * (priorDepth + 1))
         : Math.min(PROVIDER_SOURCE_CONTINUATION_MAX_ROWS, baseTarget);
     let searchIdForImport = reference.searchId;
     let broadenReceipt = null;
@@ -2511,9 +2367,11 @@ export async function executeProviderSavedSearch(action, workspaceId, mode) {
             });
         }
     }
-    else {
-        markProviderPromptLoaded({ provider, campaignOfferId });
-    }
+    // Phase 146.5 Plan 09 T5: the owner self-mark is REMOVED. Only the existing
+    // `get_provider_prompt` tool may mark the exact `(campaignOfferId, provider)`
+    // preflight; an owner that marks its own preflight satisfies the gate it is
+    // supposed to be gated by, which makes the active-provider-only rule
+    // unenforceable. The assertion side of the gate is unchanged.
     let importResult;
     try {
         importResult = await importLeads({
@@ -2620,8 +2478,8 @@ export async function executeProviderSavedSearch(action, workspaceId, mode) {
             ...(broadenReceipt ?? {}),
             targetLeadCount,
             importSearchId: searchIdForImport,
-            priorSearchDepth: mode === "broadening" ? priorDepth : null,
-            newSearchDepth: mode === "broadening" ? priorDepth + 1 : null,
+            priorSearchDepth: mode === "broadening" && !singlePass ? priorDepth : null,
+            newSearchDepth: mode === "broadening" && !singlePass ? priorDepth + 1 : null,
             netNewRows: rowsGained,
         },
     };
@@ -2636,6 +2494,76 @@ export async function continueProviderSource(action, workspaceId) {
 export async function broadenProviderSearch(action, workspaceId) {
     return executeProviderSavedSearch(action, workspaceId, "broadening");
 }
+export function buildRefillV3SourceOwnerAction(request) {
+    const actionKey = `refill-v3-source:${request.scope.idempotencyKey}`;
+    const effectId = `refill-v3-source-effect:${request.scope.idempotencyKey}`;
+    const providerSearchReference = request.scope.providerSearchReference ?? undefined;
+    return {
+        actionKey,
+        effectId,
+        ...(providerSearchReference ? { providerSearchReference } : {}),
+        ids: {
+            campaignId: request.scope.campaignId,
+            tableId: request.scope.tableId,
+            sourceLeadListId: request.scope.sourceLeadListId,
+            senderId: request.scope.senderId,
+            sourceFingerprint: request.scope.priorSourceFingerprint,
+            ...(providerSearchReference ? { providerSearchReference } : {}),
+        },
+        toolInput: {
+            // The V3 marker. It is the ONLY thing that changes owner behaviour, and
+            // it removes policy rather than adding any.
+            refillV3SinglePass: true,
+            priorSearchDepth: null,
+            leadSourceProvider: request.command.provider,
+            provider: request.command.provider,
+            sourceRowLimit: request.scope.count,
+            sourceLeadListId: request.scope.sourceLeadListId,
+            query: request.command.query,
+            filters: request.command.filterDelta,
+            keywords: request.command.keywordBatch
+                ? [...request.command.keywordBatch]
+                : undefined,
+            selectedPostIds: request.command.selectedPostIds
+                ? [...request.command.selectedPostIds]
+                : undefined,
+            sourceFingerprint: request.command.requestFingerprint,
+            effectId,
+            ...(providerSearchReference ? { providerSearchReference } : {}),
+        },
+    };
+}
+export function refillV3SourceFamilyOwners(workspaceId) {
+    async function run(ownerKey, owner, request) {
+        const action = buildRefillV3SourceOwnerAction(request);
+        let attempt;
+        try {
+            attempt = await owner(action, workspaceId);
+        }
+        catch (error) {
+            // An owner THROW is a typed scoped failure, never a crash that takes the
+            // outer queue down and never a generic no-effect success.
+            return {
+                kind: "failure",
+                failureClass: "owner_threw",
+                detail: `${ownerKey}: ${error instanceof Error ? error.message : "unknown"}`,
+            };
+        }
+        return normalizeRefillV3SourceOwnerReceipt({
+            ownerKey,
+            attempt,
+            requestFingerprint: request.command.requestFingerprint,
+            idempotencyKey: request.scope.idempotencyKey,
+        });
+    }
+    return Object.freeze({
+        refreshSenderPostEngagers: (request) => run("refreshSenderPostEngagers", refreshSenderPostEngagers, request),
+        continueSignalDiscoverySource: (request) => run("continueSignalDiscoverySource", continueSignalDiscoverySource, request),
+        broadenSignalSearch: (request) => run("broadenSignalSearch", broadenSignalSearch, request),
+        continueProviderSource: (request) => run("continueProviderSource", continueProviderSource, request),
+        broadenProviderSearch: (request) => run("broadenProviderSearch", broadenProviderSearch, request),
+    });
+}
 export async function refreshSenderPostEngagers(action, workspaceId) {
     const senderId = actionSenderId(action);
     const campaignId = actionCampaignId(action);

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

@@ -14273,13 +14273,13 @@ export declare function executeRefillSendsCommand(input?: RefillSendsCommandInpu
         planReadCount: number;
         refusalReason?: string | undefined;
         enabled: true;
-        status: "blocked" | "no_action" | "read_only_reread" | "executed_and_reread" | "refused";
+        status: "blocked" | "refused" | "no_action" | "read_only_reread" | "executed_and_reread";
         selectedAction: null;
         result: unknown;
         targetPlanReread: boolean;
     } | {
         enabled: true;
-        status: "blocked" | "no_action" | "read_only_reread" | "executed_and_reread" | "refused";
+        status: "blocked" | "refused" | "no_action" | "read_only_reread" | "executed_and_reread";
         selectedAction: Record<string, unknown>;
         result: unknown;
         targetPlanReread: boolean;
@@ -14293,7 +14293,7 @@ export declare function executeRefillSendsCommand(input?: RefillSendsCommandInpu
         planReadCount: number;
         refusalReason?: string | undefined;
         enabled: true;
-        status: "blocked" | "no_action" | "read_only_reread" | "executed_and_reread" | "refused";
+        status: "blocked" | "refused" | "no_action" | "read_only_reread" | "executed_and_reread";
         selectedAction: Record<string, unknown>;
         result: unknown;
         targetPlanReread: true;

package/dist/tools/refill-sends.js

@@ -293,7 +293,7 @@ function mergeAttemptLedgersIntoWorkspaceRunState(workspaceRunState, fenceRunSta
 export const refillSendsToolDefinitions = [
     {
         name: "refill_sends",
-        description: "Typed command entrypoint for Sellable refill sends. Every mode begins with a read-only visible plan pinned to expectedTargetShapeRevision and expectedActionKey; no credit refresh, refill mutation, or run fence may exist before that render. A first manual call without those pins returns status plan_ready and requires explicit acceptance before its planned_manual_run continuation. A first explicit workspace-wide --yolo coordinator call without pins also returns status plan_ready with the fresh sender/campaign waterfall, selected exact target, and a planned_workspace_run continuation; yolo auto-accepts the displayed packet, then traverses its planner-ranked existing targets autonomously. Execution preflights globalActionQueue[0] against the rendered authority and executes one fenced checkpointed run slice before rereading workspace scope for the next exact target. An active_exact_run continuation carries targetConfig plus exact runId/fence; a next_exact_target continuation carries the next preflighted targetConfig and opens a new fence. Exact target configs bind the issued semantic action and revisions. After a terminal exact run, two fresh read-only preflights stabilize the workspace queue; if the same terminal action remains visible, the coordinator excludes only that exact sender/lane edge and preflights the next planner-ranked existing edge instead of reopening an identical fence. A retryable Signal Discovery provider outage defers that exact signal-search action family within its campaign/table/lane for the remainder of the current workspace command, even if the eligible sender cohort changes, records the blocker in workspaceRunState, and continues independent scheduler, credit, or source-family work; a fresh user command retries the deferred family. If no other exact edge exists while the workspace gap remains positive, it returns the concrete deferred provider blocker or a classified typed terminal: new_campaign_required when receipts prove every existing lane/source family is spent, actionable_supply_not_queued (retryable) when actionable row frontiers remain but no executable exact edge surfaced, or workspace_exact_target_unavailable for the residual case. Once a scheduler sweep is dispatched, the exact fence remains active and every in_progress continuation polls only that request key until its official terminal receipt. A host wait budget never converts the active sweep into loaded_awaiting_scheduler. The post-receipt target reread returns complete, another planner action, or a receipt-backed scheduler_terminal_with_remaining_gap blocker. loaded_awaiting_scheduler is a workspace terminal only when no refill-owned scheduler request is active. After the plan is rendered, the packaged workflow must immediately invoke yolo continuation arguments until workspace projected coverage fills, the workspace scheduler-loaded terminal is returned, or no independent exact work remains behind concrete blockers, without asking the user to continue. Every primitive records actionKey/requestId/effectId before mutation and rereads the fresh target plan afterward. It may refresh stale paid InMail facts once, prepare/approve bounded existing rows, reuse/import receipt-proven source rows, continue or broaden a selected source, traverse any planner-ranked EXISTING campaign/lane/source family, start a route-resolver start-eligible PAUSED existing campaign, run a request-scoped product scheduler sweep, and wait/reread. Each bounded primitive is followed by a full replan. It never sends directly, lowers paid InMail thresholds/floors, creates NEW campaigns, archives/deletes, or invents source selection outside the planner. Provider failure is retryable and never proves source exhaustion. Unselected PAUSED campaigns that are not start-eligible remain paused. Scheduler placement stays product-native; the command never raw-writes scheduler fields.",
+        description: "SUPERSEDED V1 REFILL COORDINATOR — CHECK THE ROUTE BEFORE CALLING. If this server also exposes `refill_v3_advance`, that tool owns refill execution and this one must NOT be called: every ordinary request to refill, top up, fill, max out, or load up sends goes to `refill_v3_advance` with exactly {workspaceId, scope}. Call this tool only on servers where `refill_v3_advance` is absent. Typed command entrypoint for Sellable refill sends. Every mode begins with a read-only visible plan pinned to expectedTargetShapeRevision and expectedActionKey; no credit refresh, refill mutation, or run fence may exist before that render. A first manual call without those pins returns status plan_ready and requires explicit acceptance before its planned_manual_run continuation. A first explicit workspace-wide --yolo coordinator call without pins also returns status plan_ready with the fresh sender/campaign waterfall, selected exact target, and a planned_workspace_run continuation; yolo auto-accepts the displayed packet, then traverses its planner-ranked existing targets autonomously. Execution preflights globalActionQueue[0] against the rendered authority and executes one fenced checkpointed run slice before rereading workspace scope for the next exact target. An active_exact_run continuation carries targetConfig plus exact runId/fence; a next_exact_target continuation carries the next preflighted targetConfig and opens a new fence. Exact target configs bind the issued semantic action and revisions. After a terminal exact run, two fresh read-only preflights stabilize the workspace queue; if the same terminal action remains visible, the coordinator excludes only that exact sender/lane edge and preflights the next planner-ranked existing edge instead of reopening an identical fence. A retryable Signal Discovery provider outage defers that exact signal-search action family within its campaign/table/lane for the remainder of the current workspace command, even if the eligible sender cohort changes, records the blocker in workspaceRunState, and continues independent scheduler, credit, or source-family work; a fresh user command retries the deferred family. If no other exact edge exists while the workspace gap remains positive, it returns the concrete deferred provider blocker or a classified typed terminal: new_campaign_required when receipts prove every existing lane/source family is spent, actionable_supply_not_queued (retryable) when actionable row frontiers remain but no executable exact edge surfaced, or workspace_exact_target_unavailable for the residual case. Once a scheduler sweep is dispatched, the exact fence remains active and every in_progress continuation polls only that request key until its official terminal receipt. A host wait budget never converts the active sweep into loaded_awaiting_scheduler. The post-receipt target reread returns complete, another planner action, or a receipt-backed scheduler_terminal_with_remaining_gap blocker. loaded_awaiting_scheduler is a workspace terminal only when no refill-owned scheduler request is active. After the plan is rendered, the packaged workflow must immediately invoke yolo continuation arguments until workspace projected coverage fills, the workspace scheduler-loaded terminal is returned, or no independent exact work remains behind concrete blockers, without asking the user to continue. Every primitive records actionKey/requestId/effectId before mutation and rereads the fresh target plan afterward. It may refresh stale paid InMail facts once, prepare/approve bounded existing rows, reuse/import receipt-proven source rows, continue or broaden a selected source, traverse any planner-ranked EXISTING campaign/lane/source family, start a route-resolver start-eligible PAUSED existing campaign, run a request-scoped product scheduler sweep, and wait/reread. Each bounded primitive is followed by a full replan. It never sends directly, lowers paid InMail thresholds/floors, creates NEW campaigns, archives/deletes, or invents source selection outside the planner. Provider failure is retryable and never proves source exhaustion. Unselected PAUSED campaigns that are not start-eligible remain paused. Scheduler placement stays product-native; the command never raw-writes scheduler fields.",
         inputSchema: {
             type: "object",
             properties: {

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

@@ -2279,7 +2279,7 @@ function attachExplicitMessageTemplateRevision(params) {
 export const refillTargetPlanToolDefinitions = [
     {
         name: "get_refill_target_plan",
-        description: "read-only refill target planner to call before any refill mutation. It identifies eligible senders and infers one implicit refill lane per sender. For unified Sales Nav cascade campaigns, the public refill lane is the paid-InMail cascade target (send_inmail_closed) with campaign classification sales_nav_cascade; the same campaign can still route prospects to Open InMail or connection-request fallback based on row eligibility and fresh paid credits >= 5. Non-cascade lanes remain connection invites or paid InMails, chosen from future scheduled, recent scheduled, and ready-to-schedule evidence in active campaign-backed sequence campaigns before falling back to campaign sequences. DMs remain follow-up sequence actions, not refill target lanes. By default the planner computes the scheduler-forward 48-hour target window, selected sender-local days whose sending windows overlap that window, gross target, actual sent coverage, scheduler-owned scheduled coverage, projected coverage (sent + scheduled), ready buffer, remaining projected gap, paid InMail credit/threshold/freshness feasibility, same-campaign connection fallback availability, bounded action candidates, and targetRevision drift proof. This tool does not create rows, import leads, prepare messages, approve messages, does not schedule sends, start campaigns, lower paid InMail thresholds, create campaigns, launch, spend InMail credits, or write scheduler fields. Complete projected targets no-op without approval; loaded, awaiting scheduler targets use read-only wait/reread until projected coverage fills.",
+        description: "V1-ROUTE PLANNER — CHECK THE ROUTE BEFORE CALLING. If this server also exposes `refill_v3_advance`, that tool owns refill execution and makes its own fresh observation, so a refill must NOT be opened here; send every ordinary refill, top up, fill, max out, or load up request to `refill_v3_advance` instead. Call this tool only on servers where `refill_v3_advance` is absent. read-only refill target planner to call before any refill mutation. It identifies eligible senders and infers one implicit refill lane per sender. For unified Sales Nav cascade campaigns, the public refill lane is the paid-InMail cascade target (send_inmail_closed) with campaign classification sales_nav_cascade; the same campaign can still route prospects to Open InMail or connection-request fallback based on row eligibility and fresh paid credits >= 5. Non-cascade lanes remain connection invites or paid InMails, chosen from future scheduled, recent scheduled, and ready-to-schedule evidence in active campaign-backed sequence campaigns before falling back to campaign sequences. DMs remain follow-up sequence actions, not refill target lanes. By default the planner computes the scheduler-forward 48-hour target window, selected sender-local days whose sending windows overlap that window, gross target, actual sent coverage, scheduler-owned scheduled coverage, projected coverage (sent + scheduled), ready buffer, remaining projected gap, paid InMail credit/threshold/freshness feasibility, same-campaign connection fallback availability, bounded action candidates, and targetRevision drift proof. This tool does not create rows, import leads, prepare messages, approve messages, does not schedule sends, start campaigns, lower paid InMail thresholds, create campaigns, launch, spend InMail credits, or write scheduler fields. Complete projected targets no-op without approval; loaded, awaiting scheduler targets use read-only wait/reread until projected coverage fills.",
         inputSchema: {
             type: "object",
             properties: {