@sellable/mcp 0.1.509 → 0.1.511

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

@@ -183,7 +183,9 @@ function sanitizeActionCandidate(candidate) {
             : undefined,
         activeJobId: stringValue(candidate.activeJobId) ?? null,
         activeImportStatus: stringValue(candidate.activeImportStatus) ?? null,
-        targetRows: typeof candidate.targetRows === "number" ? candidate.targetRows : undefined,
+        targetRows: typeof candidate.targetRows === "number"
+            ? candidate.targetRows
+            : undefined,
         columnRole: stringValue(candidate.columnRole),
         rowSelector: sanitizeRowSelector(candidate.rowSelector),
         actionKey: stringValue(candidate.actionKey),
@@ -209,7 +211,9 @@ function sanitizeRowSelector(value) {
     return {
         type: value.type,
         ...(typeof value.limit === "number" ? { limit: value.limit } : {}),
-        ...(Array.isArray(value.rowIds) ? { rowIds: stringArray(value.rowIds) } : {}),
+        ...(Array.isArray(value.rowIds)
+            ? { rowIds: stringArray(value.rowIds) }
+            : {}),
     };
 }
 function sanitizeToolInput(value) {
@@ -451,11 +455,15 @@ function sanitizeStructuredSenderPlans(value, selectedBySender) {
                     selectedDays: Array.isArray(plan.horizon.selectedDays)
                         ? plan.horizon.selectedDays
                         : [],
+                    requestedTarget: numberValue(plan.horizon.requestedTarget),
                     grossTarget: numberValue(plan.horizon.grossTarget),
                     schedulerFillableSlots: typeof plan.horizon.schedulerFillableSlots === "number"
                         ? plan.horizon.schedulerFillableSlots
                         : null,
                     schedulerFillableSlotsKnown: plan.horizon.schedulerFillableSlotsKnown === true,
+                    schedulerCapacityTarget: typeof plan.horizon.schedulerCapacityTarget === "number"
+                        ? plan.horizon.schedulerCapacityTarget
+                        : null,
                     capacityConfidence: stringValue(plan.horizon.capacityConfidence) ?? "unknown",
                     schedulerCapacityMode: stringValue(plan.horizon.schedulerCapacityMode),
                 }
@@ -517,7 +525,9 @@ function emptyUnsupportedResult(result) {
             eligibleSenderLedger: [],
             senderRefillPlans: [],
             globalActionQueue: [],
+            requestedTarget: 0,
             grossTarget: 0,
+            effectiveTarget: 0,
             sent: 0,
             scheduled: 0,
             projected: 0,
@@ -564,7 +574,7 @@ function sanitizeBlockers(blockers, selectedKeys) {
         if (!actionType)
             return true;
         const senderId = parts[0];
-        return selectedKeys.size === 0 || selectedKeys.has(`${senderId}:${actionType}`);
+        return (selectedKeys.size === 0 || selectedKeys.has(`${senderId}:${actionType}`));
     });
 }
 function sanitizeRefillTargetPlanResult(result) {
@@ -626,6 +636,13 @@ function sanitizeRefillTargetPlanResult(result) {
         };
     });
     const grossTarget = senderPlans.reduce((sum, plan) => sum + numberValue(plan.grossTarget), 0);
+    const requestedTarget = senderPlans.reduce((sum, plan) => sum + numberValue(plan.requestedTarget), 0);
+    const effectiveTarget = senderPlans.reduce((sum, plan) => {
+        const target = typeof plan.schedulerCapacityTarget === "number"
+            ? plan.schedulerCapacityTarget
+            : numberValue(plan.grossTarget);
+        return sum + target;
+    }, 0);
     const sent = senderPlans.reduce((sum, plan) => sum + numberValue(plan.sent), 0);
     const scheduled = senderPlans.reduce((sum, plan) => sum + numberValue(plan.scheduled), 0);
     const projected = sent + scheduled;
@@ -662,7 +679,9 @@ function sanitizeRefillTargetPlanResult(result) {
             eligibleSenderLedger,
             senderRefillPlans,
             globalActionQueue,
+            requestedTarget,
             grossTarget,
+            effectiveTarget,
             sent,
             scheduled,
             projected,

package/dist/tools/registry.d.ts

@@ -1079,7 +1079,6 @@ export declare const allTools: ({
             useMessagingTemplate?: undefined;
             rubric?: undefined;
             flowVersion?: undefined;
-            workspaceId?: undefined;
         };
         required: string[];
         additionalProperties: boolean;
@@ -1118,7 +1117,6 @@ export declare const allTools: ({
             useMessagingTemplate?: undefined;
             rubric?: undefined;
             flowVersion?: undefined;
-            workspaceId?: undefined;
         };
         required: never[];
         additionalProperties?: undefined;
@@ -1157,7 +1155,6 @@ export declare const allTools: ({
             useMessagingTemplate?: undefined;
             rubric?: undefined;
             flowVersion?: undefined;
-            workspaceId?: undefined;
         };
         required: string[];
         additionalProperties?: undefined;
@@ -1239,7 +1236,6 @@ export declare const allTools: ({
             useMessagingTemplate?: undefined;
             rubric?: undefined;
             flowVersion?: undefined;
-            workspaceId?: undefined;
         };
         required: string[];
         additionalProperties: boolean;
@@ -1434,7 +1430,6 @@ export declare const allTools: ({
             useMessagingTemplate?: undefined;
             rubric?: undefined;
             flowVersion?: undefined;
-            workspaceId?: undefined;
         };
         required: never[];
         additionalProperties?: undefined;
@@ -1640,49 +1635,6 @@ export declare const allTools: ({
             clientProspectId?: undefined;
             senderLinkedinUrl?: undefined;
             messageGenerationMode?: undefined;
-            workspaceId?: undefined;
-        };
-        required: string[];
-        additionalProperties?: undefined;
-    };
-} | {
-    name: string;
-    description: string;
-    inputSchema: {
-        type: string;
-        properties: {
-            campaignId: {
-                type: string;
-                description: string;
-            };
-            workspaceId: {
-                type: string;
-                description: string;
-            };
-            limit?: undefined;
-            tableId?: undefined;
-            leadLimit?: undefined;
-            page?: undefined;
-            filters?: undefined;
-            name?: undefined;
-            clientProspectId?: undefined;
-            senderLinkedinUrl?: undefined;
-            offerPositioning?: undefined;
-            campaignBrief?: undefined;
-            messageGenerationMode?: undefined;
-            currentStep?: undefined;
-            watchNarration?: undefined;
-            leadSourceType?: undefined;
-            leadSourceProvider?: undefined;
-            selectedLeadListId?: undefined;
-            senderIds?: undefined;
-            currentStepTransition?: undefined;
-            clearCurrentStepIfMatches?: undefined;
-            interactionMode?: undefined;
-            enableICPFilters?: undefined;
-            useMessagingTemplate?: undefined;
-            rubric?: undefined;
-            flowVersion?: undefined;
         };
         required: string[];
         additionalProperties?: undefined;
@@ -1724,7 +1676,6 @@ export declare const allTools: ({
             useMessagingTemplate?: undefined;
             rubric?: undefined;
             flowVersion?: undefined;
-            workspaceId?: undefined;
         };
         required: string[];
         additionalProperties?: undefined;

package/dist/tools/senders.d.ts

@@ -34,7 +34,7 @@ export type SenderDetailResponse = {
 };
 export type RefreshPaidInmailCreditsInput = {
     senderId: string;
-    workspaceId?: string;
+    workspaceId: string;
 };
 export type PaidInmailCreditStatus = {
     available: number;
@@ -47,6 +47,7 @@ export type RefreshPaidInmailCreditsResponse = {
     senderId: string;
     refreshed: true;
     credits: PaidInmailCreditStatus;
+    receipt?: unknown;
     sideEffects: {
         refreshedLinkedInDerivedCreditFacts: true;
         updatedSenderCreditCache: true;

package/dist/tools/senders.js

@@ -136,20 +136,20 @@ export const senderToolDefinitions = [
     },
     {
         name: "refresh_paid_inmail_credits",
-        description: "Refresh the cached paid InMail credit facts for one exact sender in the active workspace by calling Sellable's product credit refresh path. This updates only the sender credit cache (balance, sentSince, checkedAt) and returns the fresh status. It does not mutate campaigns, lower thresholds, approve messages, schedule sends, start campaigns, send messages, spend InMail credits, or write scheduler fields. refill_sends --yolo normally handles get_refill_target_plan refresh_paid_inmail_credits candidates internally; use this standalone tool for manual diagnostics or explicit one-off refreshes, then rerun get_refill_target_plan before any refill mutation.",
+        description: "Refresh the cached paid InMail credit facts for one exact sender in the explicit request-scoped workspace by calling Sellable's scoped MCP credit refresh path. This updates only the sender credit cache/attempt metadata (balance, sentSince, checkedAt, last attempted/error/lease) and returns the sanitized coordinator receipt. It does not mutate campaigns, lower thresholds, approve messages, schedule sends, start campaigns, send messages, spend InMail credits, or write scheduler fields. refill_sends --yolo normally handles get_refill_target_plan refresh_paid_inmail_credits candidates internally; use this standalone tool for manual diagnostics or explicit one-off refreshes, then rerun get_refill_target_plan before any refill mutation.",
         inputSchema: {
             type: "object",
             properties: {
                 senderId: {
                     type: "string",
-                    description: "Exact Sender.id to refresh. The API verifies the sender belongs to the active workspace.",
+                    description: "Exact Sender.id to refresh. The API verifies the sender belongs to the explicit workspace.",
                 },
                 workspaceId: {
                     type: "string",
                     description: "Explicit request-scoped workspace id for scheduled/yolo refill automation. Pass this instead of switching the shared active workspace.",
                 },
             },
-            required: ["senderId"],
+            required: ["senderId", "workspaceId"],
             additionalProperties: false,
         },
     },
@@ -209,15 +209,17 @@ export async function refreshPaidInmailCredits(input) {
     }
     const api = getApi();
     const workspaceId = normalizeExplicitWorkspaceId(input.workspaceId);
+    if (!workspaceId) {
+        throw new Error("workspaceId is required.");
+    }
     const requestOptions = workspaceRequestOptions(workspaceId);
-    const body = workspaceId ? { workspaceId } : {};
-    const result = requestOptions
-        ? await api.post(`/api/v3/senders/${encodeURIComponent(senderId)}/refresh-inmail-credits`, body, requestOptions)
-        : await api.post(`/api/v3/senders/${encodeURIComponent(senderId)}/refresh-inmail-credits`, body);
+    const body = { workspaceId };
+    const result = await api.post(`/api/v3/mcp/senders/${encodeURIComponent(senderId)}/refresh-inmail-credits`, body, requestOptions);
     return {
         senderId,
         refreshed: true,
         credits: normalizeCreditStatus(result?.credits),
+        receipt: result?.receipt,
         sideEffects: {
             refreshedLinkedInDerivedCreditFacts: true,
             updatedSenderCreditCache: true,

package/package.json

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

package/skills/refill-sends/SKILL.md

@@ -7,6 +7,7 @@ allowed-tools:
   - mcp__sellable__get_refill_target_plan
   - mcp__sellable__get_scheduler_fill_capacity
   - mcp__sellable__refresh_paid_inmail_credits
+  - mcp__sellable__get_subskill_asset
   - mcp__sellable__get_auth_status
   - mcp__sellable__start_cli_login
   - mcp__sellable__wait_for_cli_login
@@ -151,19 +152,23 @@ explicitly stops/statuses the run, or a concrete non-scheduler blocker appears.
 Do not call the goal complete or blocked only because the current state is
 `awaiting_scheduler_after_ready_buffer`; treat it as loaded, awaiting scheduler.
 
-Load the internal workflow prompt before taking any operational step:
+Load the internal workflow prompt and deterministic flow asset before taking
+any operational step:
 
 ```text
 get_subskill_prompt({ subskillName: "refill-sends-workflow" })
+get_subskill_asset({ subskillName: "refill-sends-workflow", assetPath: "core/flow.v1.json" })
 ```
 
-Then follow that workflow exactly. The default path is read-only research:
-compute the refill target plan first, resolve the route, identify the
-sender-relevant campaign that most recently had scheduler-owned sends, read
-refill state for that target, report the next safe step using campaign names
-first, and stop before mutation unless the user has explicitly approved the
-exact workspace, campaign/table/source ids, caps/dates, approval mode, expected
-side effects, and stop/rollback condition.
+Continue both loads until `hasMore:false`; parse the flow JSON and verify
+`workflow:"refill-sends-workflow"` with a `v1` version. Then follow that
+workflow exactly. The default path is read-only research: compute the refill
+target plan first, resolve the route, identify the sender-relevant campaign
+that most recently had scheduler-owned sends, read refill state for that target,
+report the next safe step using campaign names first, and stop before mutation
+unless the user has explicitly approved the exact workspace,
+campaign/table/source ids, caps/dates, approval mode, expected side effects,
+and stop/rollback condition.
 
 Immediately after loading the internal workflow, call
 `get_refill_target_plan`. The target plan is the canonical first fact receipt:
@@ -223,6 +228,20 @@ threshold, below-threshold paid-InMail facts fall back to an existing connection
 lane, the same Sales Nav cascade campaign's connection branch, or a manual
 continuation.
 
+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 a
+`refresh_paid_inmail_credits` candidate, do not enter `wait_for_scheduler` even
+when `remainingReadyOrProjectedGap:0`. Refresh the exact selected sender credit
+facts once, rerun `get_refill_target_plan`, and only then decide whether
+scheduler wait is the next safe action. If facts remain missing/stale after the
+single refresh attempt, stop with a paid-InMail freshness blocker instead of
+waiting on scheduler pickup.
+The standalone MCP refresh surface is the scoped route
+`/api/v3/mcp/senders/:senderId/refresh-inmail-credits` with explicit
+`workspaceId`; do not use active-workspace mutation as the automation control
+path.
+
 Compact refill lessons: sender-level target plan is final truth; trust
 `schedulerGate.sendable` and scheduler gate blockers, not raw
 `unipileAccountStatus` labels alone; use compact prep status checks for
@@ -239,8 +258,9 @@ will try to place and does not import, approve, schedule, refresh credits, or
 mutate.
 If the target plan is complete by projected coverage, report that the selected
 target is already filled and no-op without asking for approval. If the ready
-buffer covers the projected gap but scheduled coverage is still short, keep the
-run open in a persistent read-only scheduler wait loop. Poll
+buffer covers the projected gap, paid InMail credit facts are fresh for every
+selected paid-InMail lane, but scheduled coverage is still short, keep the run
+open in a persistent read-only scheduler wait loop. Poll
 `get_refill_target_plan` every 60-120 seconds, or on the host's next continuation
 interval, until projected coverage fills the target, a concrete non-scheduler
 blocker appears, or Christian explicitly asks to stop or only receive a status

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

@@ -3,6 +3,7 @@ name: refill-sends-workflow
 description: Internal skill-led refill sends workflow for regular campaigns and evergreen campaigns.
 visibility: internal
 allowed-tools:
+  - mcp__sellable__get_subskill_asset
   - mcp__sellable__get_refill_target_plan
   - mcp__sellable__get_scheduler_fill_capacity
   - mcp__sellable__refresh_paid_inmail_credits
@@ -79,6 +80,16 @@ open until every selected sender lane is horizon-filled by projected coverage
 non-scheduler blocker appears. `awaiting_scheduler_after_ready_buffer` is an
 in-progress wait state, not a reason to mark the goal complete or blocked.
 
+Runtime flow asset: after loading this prompt, load
+`get_subskill_asset({ subskillName: "refill-sends-workflow", assetPath: "core/flow.v1.json" })`
+through MCP, continue chunks until `hasMore:false`, parse the JSON, and verify
+`workflow:"refill-sends-workflow"` with a `v1` version before any operational
+step. The flow asset is the deterministic gate order: target-plan read, paid
+InMail credit freshness gate, action selection, bounded table action, scheduler
+wait readback, then completion/blocker. If the asset cannot load or parse, stop
+with `blocked:refill_workflow_asset_unavailable`; do not emulate it from local
+files or memory.
+
 1. Call `get_refill_target_plan` first. This read-only target plan is the
    canonical opening receipt: eligible senders, selected sender-local days,
    gross target, inferred per-sender send lane/action selections, actual sent
@@ -136,6 +147,19 @@ in-progress wait state, not a reason to mark the goal complete or blocked.
    threshold, below-threshold paid-InMail facts fall back to an existing
    connection lane, the same Sales Nav cascade campaign's connection branch, or
    a manual continuation.
+   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 a
+   `refresh_paid_inmail_credits` candidate, do not enter
+   `wait_for_scheduler` even when `remainingReadyOrProjectedGap:0`. Refresh the
+   exact selected sender credit facts once, rerun `get_refill_target_plan`, and
+   only then decide whether scheduler wait is the next safe action. If facts
+   remain missing/stale after the single refresh attempt, stop with a
+   paid-InMail freshness blocker instead of waiting on scheduler pickup.
+   The standalone MCP refresh surface is the scoped route
+   `/api/v3/mcp/senders/:senderId/refresh-inmail-credits` with explicit
+   `workspaceId`; do not use active-workspace mutation as the automation
+   control path.
    Compact refill lessons: sender-level target plan is final truth; trust
    `schedulerGate.sendable` and scheduler gate blockers, not raw
    `unipileAccountStatus` labels alone; use compact prep status checks for
@@ -154,8 +178,9 @@ in-progress wait state, not a reason to mark the goal complete or blocked.
    If `status:"complete"`, report the target, selected dates, sent count,
    scheduled count, projected count, campaign ids, and no-op proof without
    asking for approval or mutating.
-   If `remainingReadyOrProjectedGap:0` but `remainingProjectedGap>0`, run only a
-   persistent read-only scheduler wait/reread loop; do not ask for
+   If `remainingReadyOrProjectedGap:0` but `remainingProjectedGap>0`, and paid
+   InMail credit freshness is clean for every selected paid-InMail lane, run
+   only a persistent read-only scheduler wait/reread loop; do not ask for
    prep/import/approval. Poll `get_refill_target_plan` every 60-120 seconds, or
    on the host's next continuation interval, until projected coverage fills,
    a concrete non-scheduler blocker appears, or Christian explicitly asks to

package/skills/refill-sends-workflow/core/flow.v1.json

@@ -0,0 +1,281 @@
+{
+  "version": "v1.0",
+  "workflow": "refill-sends-workflow",
+  "principle": "Use the target planner and scheduler readback as canonical facts. Refresh stale paid-InMail credit facts before scheduler-wait decisions; do not change scheduler allocation logic.",
+  "requiredBootstrap": [
+    {
+      "tool": "get_subskill_prompt",
+      "requiredValues": {
+        "subskillName": "refill-sends-workflow"
+      },
+      "mustReadUntil": {
+        "hasMore": false
+      }
+    },
+    {
+      "tool": "get_subskill_asset",
+      "requiredValues": {
+        "subskillName": "refill-sends-workflow",
+        "assetPath": "core/flow.v1.json"
+      },
+      "mustReadUntil": {
+        "hasMore": false
+      },
+      "validation": {
+        "workflow": "refill-sends-workflow",
+        "versionPrefix": "v1",
+        "requiredTopLevelKeys": [
+          "states",
+          "gateOrder",
+          "yoloMode"
+        ]
+      }
+    }
+  ],
+  "gateOrder": [
+    "target_plan_read",
+    "paid_inmail_credit_freshness_gate",
+    "target_action_selection",
+    "bounded_table_action",
+    "scheduler_wait_readback",
+    "completion_or_blocker"
+  ],
+  "sharedFacts": [
+    "workspaceId",
+    "senderId",
+    "campaignId",
+    "tableId",
+    "columnId",
+    "actionType",
+    "targetDate",
+    "untilDate",
+    "targetShapeRevision",
+    "stateRevision",
+    "paidInmail.status",
+    "paidInmail.available",
+    "paidInmail.threshold",
+    "paidInmail.maxStalenessSeconds",
+    "remainingProjectedGap",
+    "remainingReadyOrProjectedGap",
+    "readyToSchedule",
+    "scheduled",
+    "projected"
+  ],
+  "states": [
+    {
+      "id": "target_plan_read",
+      "description": "Read the canonical target plan before any mutation or wait loop.",
+      "allowedTools": [
+        "get_refill_target_plan"
+      ],
+      "requiredOutput": [
+        "target.eligibleSenderLedger",
+        "target.senderRefillPlans",
+        "target.globalActionQueue",
+        "targetShapeRevision",
+        "stateRevision"
+      ],
+      "transitions": [
+        {
+          "when": "status == complete",
+          "to": "completion_or_blocker"
+        },
+        {
+          "when": "any selected senderRefillPlans[].paidInmail.status is missing_credit_facts or stale_credit_facts",
+          "to": "paid_inmail_credit_freshness_gate"
+        },
+        {
+          "when": "globalActionQueue or actionCandidates contains refresh_paid_inmail_credits",
+          "to": "paid_inmail_credit_freshness_gate"
+        },
+        {
+          "otherwise": "target_action_selection"
+        }
+      ]
+    },
+    {
+      "id": "paid_inmail_credit_freshness_gate",
+      "description": "Make paid-InMail credit freshness deterministic before trusting scheduler wait decisions.",
+      "allowedTools": [
+        "refresh_paid_inmail_credits",
+        "get_refill_target_plan"
+      ],
+      "rules": [
+        "This gate precedes scheduler_wait_readback, even when remainingReadyOrProjectedGap is 0.",
+        "Refresh only exact sender ids present in the rendered target packet.",
+        "Refresh each selected sender at most once per refill_sends command call.",
+        "The refresh receipt must include approvalSource, workspaceId, senderId, actionKey, campaignId, tableId, columnId, threshold, maxStalenessSeconds, and targetPlanFingerprint.",
+        "After refresh, rerun get_refill_target_plan with the same workspaceId and selectors before choosing a prep, approval, source-copy, or scheduler-wait action.",
+        "If facts remain missing or stale after the single refresh attempt, stop with paid_inmail_credit_freshness_blocked rather than entering scheduler wait.",
+        "If fresh facts are below threshold, report the exact threshold blocker or same-campaign connection fallback; do not lower thresholds in yolo mode."
+      ],
+      "disallowedBeforeReread": [
+        "wait_for_scheduler",
+        "start_campaign_message_preparation",
+        "confirm_lead_list",
+        "select_campaign_cells",
+        "queue_campaign_cells",
+        "start_campaign"
+      ],
+      "transitions": [
+        {
+          "when": "post_refresh_target_plan has no missing/stale paid-InMail facts for selected lanes",
+          "to": "target_action_selection"
+        },
+        {
+          "when": "post_refresh_target_plan still has missing/stale paid-InMail facts",
+          "to": "completion_or_blocker"
+        }
+      ]
+    },
+    {
+      "id": "target_action_selection",
+      "description": "Choose only the globally ranked planner primitive after freshness gates pass.",
+      "allowedTools": [
+        "get_refill_target_plan",
+        "get_campaign_refill_state",
+        "get_scheduler_fill_capacity"
+      ],
+      "rules": [
+        "Use target.globalActionQueue[0] as the only cross-sender yolo action.",
+        "manualAlternates are not yolo actions.",
+        "If projected coverage is complete, no-op.",
+        "If remainingReadyOrProjectedGap is 0 and remainingProjectedGap is positive, scheduler wait is allowed only after paid_inmail_credit_freshness_gate is clean.",
+        "If ready buffer is short, choose bounded existing-row prep, bounded approval, same-source copy, or provider-aligned source-more according to the planner."
+      ],
+      "transitions": [
+        {
+          "when": "next action is wait_for_scheduler and paid freshness gate is clean",
+          "to": "scheduler_wait_readback"
+        },
+        {
+          "when": "next action is a bounded table/source/prep/approval primitive",
+          "to": "bounded_table_action"
+        },
+        {
+          "when": "no safe action remains or non-scheduler blocker exists",
+          "to": "completion_or_blocker"
+        }
+      ]
+    },
+    {
+      "id": "bounded_table_action",
+      "description": "Run one safe primitive, then reread the target plan.",
+      "allowedTools": [
+        "start_campaign_message_preparation",
+        "get_campaign_message_preparation_status",
+        "import_leads",
+        "wait_for_lead_list_ready",
+        "confirm_lead_list",
+        "select_campaign_cells",
+        "queue_campaign_cells",
+        "wait_for_campaign_processing",
+        "get_refill_target_plan"
+      ],
+      "rules": [
+        "One primitive per loop.",
+        "No broad approval.",
+        "No scheduler writes.",
+        "Reread get_refill_target_plan before any second primitive.",
+        "Continue while targetShapeRevision is stable and projected coverage progresses."
+      ],
+      "transitions": [
+        {
+          "after": "terminal primitive result and target reread",
+          "to": "target_plan_read"
+        }
+      ]
+    },
+    {
+      "id": "scheduler_wait_readback",
+      "description": "Read-only scheduler polling after rows are ready and paid-credit facts are fresh.",
+      "allowedTools": [
+        "get_refill_target_plan",
+        "get_scheduler_fill_capacity"
+      ],
+      "entryConditions": [
+        "remainingReadyOrProjectedGap == 0",
+        "remainingProjectedGap > 0",
+        "no selected paid-InMail lane has missing_credit_facts or stale_credit_facts",
+        "no refresh_paid_inmail_credits action remains in target.globalActionQueue or actionCandidates"
+      ],
+      "rules": [
+        "Poll every 60-120 seconds or on the host continuation interval.",
+        "Stop waiting when projected coverage fills the target.",
+        "Leave wait if a concrete non-scheduler blocker appears.",
+        "Do not mark complete or blocked only because awaiting_scheduler_after_ready_buffer persists."
+      ],
+      "transitions": [
+        {
+          "when": "projected coverage fills target",
+          "to": "completion_or_blocker"
+        },
+        {
+          "when": "paid facts become missing/stale again",
+          "to": "paid_inmail_credit_freshness_gate"
+        },
+        {
+          "when": "ready buffer no longer covers gap",
+          "to": "target_action_selection"
+        }
+      ]
+    },
+    {
+      "id": "completion_or_blocker",
+      "description": "Report exact no-op, completion proof, or blocker with ids and revisions.",
+      "allowedTools": [
+        "get_refill_target_plan",
+        "get_campaign_refill_state",
+        "get_scheduler_fill_capacity"
+      ],
+      "terminal": true
+    }
+  ],
+  "yoloMode": {
+    "approvalSource": "explicit_yolo_flag",
+    "autoExecutableActions": [
+      "refresh_paid_inmail_credits",
+      "start_campaign_message_preparation",
+      "same_source_copy",
+      "bounded_generated_message_approval",
+      "wait_for_scheduler"
+    ],
+    "neverAutoExecute": [
+      "lower_paid_inmail_threshold",
+      "create_campaign",
+      "create_connection_campaign",
+      "switch_source_family",
+      "direct_scheduler_write",
+      "start_unselected_campaign",
+      "archive_or_delete"
+    ],
+    "driftStops": [
+      "workspaceId",
+      "sender set",
+      "campaignId",
+      "tableId",
+      "columnId",
+      "actionType",
+      "targetDate",
+      "untilDate",
+      "targetShapeRevision",
+      "paid-InMail threshold feasibility",
+      "side-effect class"
+    ]
+  },
+  "verification": {
+    "requiredProof": [
+      "final get_refill_target_plan",
+      "projected coverage sent + scheduled",
+      "scheduler-owned cells with non-null scheduledFor when claiming scheduled",
+      "paid-InMail freshness status clean before scheduler wait",
+      "refresh receipt for each refreshed sender"
+    ],
+    "notCompletionProof": [
+      "prepared rows alone",
+      "approved rows alone",
+      "ready-to-schedule rows alone",
+      "awaiting_scheduler_after_ready_buffer"
+    ]
+  }
+}