@sellable/mcp 0.1.557 → 0.1.559

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

@@ -1,6 +1,6 @@
 ---
 name: refill-sends-workflow
-description: Internal skill-led refill sends workflow for regular campaigns and evergreen campaigns.
+description: Internal typed workflow contract for regular and evergreen campaign refills.
 visibility: internal
 allowed-tools:
   - mcp__sellable__get_subskill_asset
@@ -49,748 +49,105 @@ allowed-tools:
 
 # Refill Sends Workflow
 
-Default mode is read-only research. This workflow decides the next safe refill
-step in the parent thread; backend tools remain narrow route, state, source,
-prep, readiness, and evergreen primitives.
-
-## Entry
-
-Plain phrases that enter here include "fill", "refill sends", "max out sends",
-"load everyone up", and "fill horizon sends".
-
-Sender-scoped phrases include "refill senders", "fill senders", "max out
-senders", and "load everyone up". A sender-scoped request targets senders
-enrolled in active campaign-backed sequence campaigns, not one arbitrary active
-campaign.
-
-Workspace contract: scheduled automation and `--yolo` must carry an explicit
-request-scoped `workspaceId`. Pass that same `workspaceId` on every refill tool
-call in this workflow: `get_refill_target_plan`, `list_senders`,
-`get_sender_routing`, `resolve_campaign_fill_route`,
-`get_campaign_refill_state`, `get_scheduler_fill_capacity`,
-`run_scheduler_sweep`, `refresh_paid_inmail_credits`, source import/readiness
-calls, preparation calls, approval calls, and campaign start calls. Missing
-`workspaceId` in scheduled or `--yolo` mode is a blocker; return or report
-`WORKSPACE_REQUIRED` instead of falling back to shared config state. Manual
-interactive workspace switching is diagnostic setup only and is not an
-automation control path.
-
-Goal-mode continuation: a skill cannot create or invoke `/goal` by itself. When
-this workflow is already running inside an active Codex goal, keep that goal
-open until every selected sender lane is horizon-filled by projected coverage
-(`sent + scheduled`), Christian explicitly stops/statuses the run, or a concrete
-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
-   coverage, scheduler-owned scheduled coverage across active enrolled
-   campaigns, projected coverage (`sent + scheduled`), ready buffer, remaining
-   projected gap, paid-InMail credit/threshold feasibility, bounded action
-   candidates, `targetShapeRevision`, and `stateRevision`.
-   Refill target lanes are connection invites (`send_invite`), standalone paid
-   InMails (`send_inmail_closed`), or unified Sales Nav cascades represented
-   publicly as `send_inmail_closed` with
-   `campaignClassification:"sales_nav_cascade"`. For a Sales Nav cascade, fill
-   the selected campaign first; its sequence can route prospects to Open InMail,
-   paid InMail while fresh credits are >= 5, or same-campaign connection
-   fallback without asking for separate open/paid/connection campaigns. DMs
-   (`send_dm`) are follow-up actions, not refill horizon capacity. Do not count
-   their sent, scheduled, or ready cells when deciding whether a sender needs
-   refill. When `actionTypes` are omitted, trust the target plan's inferred lane;
-   do not ask the operator which campaign class to fill after the plan has
-   inferred that from active campaign future scheduled, recent scheduled, and
-   ready evidence. If a stale planner/tool response selects `send_dm` or
-   `send_inmail_open`, treat that as unsupported stale refill state and re-plan
-   with a current planner before any mutation.
-   Short form: trust the target plan's inferred lane when it is a connection
-   invite, paid-InMail refill lane, or unified Sales Nav cascade.
-   Structured planner packet:
-   - `target.eligibleSenderLedger` is the public sender eligibility ledger.
-   - `target.senderRefillPlans[]` is the canonical sender-level packet; read and
-     display it before mutation.
-   - Each sender packet includes `campaignRanking.options`, `sourcePlan`,
-     `refillReceipt`, `nextActions`, and `manualAlternates`.
-   - `refillReceipt` is the public ladder receipt. It carries the selected
-     campaign/sender/lane summary, skipped rungs, existing-row frontier proof,
-     and any absolute `wait.deadlineAt`.
-   - Preserve these coverage labels exactly: `Need to prepare`, `Goal`,
-     `Already sent`, `Scheduled`, `Ready and waiting to be scheduled`, and
-     `Still need`.
-   - `target.globalActionQueue` is the only cross-sender yolo execution queue.
-     execute exactly one globally ranked primitive from
-     `target.globalActionQueue[0]`, then rerun `get_refill_target_plan` with
-     the same `workspaceId` before
-     choosing another action.
-   - `nextActions[0]` is the current sender's smallest safe primitive.
-   - `manualAlternates` are not yolo actions. Threshold lowering and campaign
-     creation are manual continuations only.
-   Refill action ladder: approve generated rows only when an explicit bounded
-   approval gate exists, process all existing same-campaign
-   unenriched/unprepared rows in bounded batches before any source work, then
-   copy bounded net-new rows from the selected source (`selectedLeadListId`,
-   provider, and source fingerprint preserved), then use provider-aligned
-   source-more. A new source or provider switch changes the reply-rate baseline
-   and is a manual alternate, not a `--yolo` side effect.
-   Source/copy/fallback requires receipt-proven exhaustion of earlier rungs:
-   `existingRowFrontier.hasMoreFrontierRows:false`, zero
-   `approvalCandidates`, no fresh active prep, no `stuckActiveCells`, and no
-   non-terminal `approvedNotDispatched` rows. Treat anomalies,
-   `stuckActiveCells`, and non-terminal `approvedNotDispatched` as
-   diagnose-and-report gates, not exhaustion. Terminal
-   `approvedNotDispatched` blockers may be reported, then the ladder can
-   proceed.
-   Run-local paid-credit guard: in `--yolo`, the `refill_sends` MCP command
-   automatically maintains a `refreshedPaidInmailSenderIds` set for the current
-   command call. If its first target plan has stale/missing paid-InMail credit
-   facts, it refreshes each selected sender at most once, reruns
-   `get_refill_target_plan`, and returns the post-refresh `targetPlan` before
-   choosing the next prep/source-copy/bounded-approval/read-only wait action. If fresh facts are still below
-   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
-   long-running jobs; reread target plans after prep or cancel; treat ready rows
-   as intermediate; avoid huge parallel target-plan reads when output is large.
-   If a campaign produces prepared/ready rows but sender-level projected
-   coverage does not move after one bounded settle loop, pivot to compact prep
-   status or a scheduler-proven lane. Do not keep waiting on campaign-level
-   ready counts.
-   For exact-date requests, pass `targetDate` to `get_refill_target_plan`.
-   When you need raw diagnostic proof, call `get_scheduler_fill_capacity` for
-   the same exact sender/action/date. That query is read-only and tells the MCP
-   how many cells the product scheduler will try to place for that sender; it
-   does not create rows, import, approve, schedule, refresh paid-InMail credits,
-   or mutate thresholds.
-   When ready rows exist and the wait is for scheduler pickup, call
-   `run_scheduler_sweep` with the same explicit `workspaceId` to request the
-   product scheduler placement pass now and read its receipt. This may place
-   cells within existing gates, never sends messages, and never bypasses limits.
-   Scheduler-run receipt interpretation: `cellsConsidered is
-   allocation-attempt count`, not total ready supply, while `readyCellsFound`
-   is ready inventory found before prefilters. Inspect `campaignScopeSummary`
-   before assuming the selected refill campaign/table was included; if absent,
-   do not infer that target was ready-but-blocked. Interpret `prefiltered` as
-   ready cells removed before allocation, `skipped` as considered cells blocked
-   by scheduler gates, and `deferred` as considered cells waiting on
-   windows/capacity/cooldown. For ready closed-InMail cells with stale
-   paid-credit prefilter/defer reasons, refresh paid-InMail credits once through
-   existing tools, then rerun `run_scheduler_sweep` or read `action:"status"`;
-   `refresh_paid_inmail_credits_then_rerun` is that path.
-   `wait_for_capacity_or_window` means report loaded/capped/waiting and do not
-   source or prep more rows; `no_ready_cells_continue_refill_prep` means return
-   to the refill/prep ladder. Do not treat `cellsScheduled:0` alone as failure.
-   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`, 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
-   stop or only receive a status report. Treat
-   `awaiting_scheduler_after_ready_buffer` as an in-progress wait state, not a
-   close-out condition.
-   Wait actions are gates, not competing goals. When `wait_for_active_work` or
-   `wait_for_scheduler` includes receipt `wait.deadlineAt`, honor that absolute
-   deadline; if it is expired on this call, escalate to diagnostics with the
-   receipt evidence instead of issuing another blind wait.
-   If paid InMail credit facts are stale or missing and the first target plan
-   contains `refresh_paid_inmail_credits`, do not present that as the operator's
-   next action in `--yolo`. Do not present paid-credit refresh as the next
-   operator action after `refill_sends` returns `autoPaidInmailRefresh` and the
-   post-refresh `targetPlan`. Trust `refill_sends.autoPaidInmailRefresh`: it
-   should show the exact sender ids refreshed once, sender-credit-cache write
-   receipts, and a returned post-refresh `targetPlan`. Continue from that
-   post-refresh packet. If paid InMail is below threshold after the fresh credit read, report
-   the exact campaign/table/column threshold action or same-campaign
-   connection fallback; `--yolo` does not lower paid-InMail thresholds or create campaigns.
-2. Call `resolve_campaign_fill_route`. Use `intent:"plain"` for generic
-   fill/load language, `intent:"active"` only when the user explicitly narrowed
-   to active regular campaigns or when the plain route has stale managed
-   waterfall evidence, and `intent:"evergreen"` only when the user explicitly
-   asked for evergreen or horizon work. The resolver must refetch current
-   dashboard-active campaigns as well as managed waterfall state. If the plain
-   route returns managed waterfall targets but skipped targets include
-   archived/completed waterfall slots, or if the returned targets do not cover a
-   named sender, immediately call `resolve_campaign_fill_route({ intent:"active" })`
-   and inspect current dashboard-active `ACTIVE` and `PAUSED` campaign-backed
-   sequence campaigns before declaring a sender blocked.
-   Short form: stale waterfall bindings do not overrule current dashboard-active campaigns.
-3. Resolve sender context before choosing a target. Call `list_senders`; when a
-   managed program is involved, also call `get_campaign_waterfall`, and call
-   `get_sender_routing` when territory rules may constrain sender eligibility.
-   If the user named senders, map those names to exact sender ids. If the user
-   did not name senders and the request is sender-scoped:
-   - in `--yolo`, target all eligible healthy senders enrolled in active
-     campaign-backed sequence campaigns returned by the route/state evidence;
-   - outside `--yolo`, ask which eligible enrolled senders to refill before
-     choosing campaigns or mutating.
-   If the request is campaign-scoped or ambiguous "fill sends" language, infer
-   the relevant senders from the most recent scheduler-owned sends in
-   refill-state readbacks and report that inference.
-   Short form: `--yolo refill senders` means all eligible enrolled senders; non-yolo asks which enrolled senders.
-4. Read `get_campaign_refill_state` for candidate campaigns from the resolver
-   result and from the required active-route refetch when managed waterfall
-   evidence looks stale. For a broad `active_campaigns` route, inspect enough
-   candidates to identify the campaign or small campaign set that most recently
-   had scheduler-owned sends for the relevant sender set. Do not stop after the
-   first resolver target unless it is also the most recent sender-relevant send
-   lane. A current dashboard-active `PAUSED` campaign-backed sequence campaign is
-   a start-eligible refill candidate, not an archived blocker; read its refill
-   state first, then include a bounded `start_campaign` packet only when the
-   state proves healthy senders, sequence, source/list, ready/preparable rows,
-   and starting is needed for the product scheduler to schedule/send.
-   Short form: Do not stop after the first resolver target unless recent-send evidence supports it.
-   Short form: `PAUSED` dashboard-active campaigns are start-eligible candidates, not skipped archived inventory.
-   In `--yolo` sender-scoped mode, selecting every active campaign is still a
-   scope error, but selecting one best refill campaign per eligible sender is
-   expected. Pick the single highest-ranked recent-send or best-result campaign
-   for each target sender unless the refill-state evidence proves that a sender
-   already has enough ready/scheduled rows across enrolled campaigns or that a
-   different same-sender campaign is needed because the best lane is blocked.
-   Short form: `--yolo refill senders` selects all eligible enrolled senders, then the best campaign per sender.
-5. Pick exact ids from the selected refill-state response. Do not use campaign
-   names or table names as target identifiers for tool calls.
-6. Classify the target from refill state:
-   - regular campaign: campaign-backed workflow table with normal source,
-     sequence, senders, and send/refill stages.
-   - evergreen campaign: managed always-on lane with current source evidence.
-   - `unsupported_campaign_type`: internal direct campaign table; report the
-     blocker and stop without mutation.
-
-## Research Checklist
-
-Use the refill-state response as the current facts receipt:
-
-- campaign status/current step, workflow table id, table config type, and public
-  type, including whether the route target is dashboard-active `PAUSED` and
-  start-eligible;
-- selected source list/provider identity, source id, target prospect gap,
-  cursor/inventory state, dedupe/DNC/provider exclusions, good-prospect yield,
-  scan/import caps, and proof;
-- sender ids, healthy senders, disconnected senders, and daily capacity;
-- target-window saturation ledger per target sender: sender-local send days in
-  scope, gross target capacity, actual sent coverage, future scheduler-owned
-  scheduled counts in that window, projected coverage (`sent + scheduled`),
-  ready-to-schedule buffer, remaining projected gap, paid-InMail
-  credit/threshold feasibility, `targetShapeRevision`, `stateRevision`, and the
-  next smallest MCP primitive that can reduce the gap;
-- row/stage counts: source available, rows, enriched, passed, generated,
-  approved, ready to schedule, scheduled;
-- active message prep job;
-- scheduler-owned scheduled counts by date/action from cells with non-null
-  `scheduledFor`; treat connection-invite and paid-InMail cells as the refill
-  lane continuation signal and the last sends/continuation signal, and ignore
-  DM/open-InMail cells for refill target capacity;
-- latest scheduled send date, latest scheduled-cell update when present,
-  sender overlap with the requested or inferred sender set, and whether future
-  scheduled sends already exist;
-- `freshness.stateHash` and exact campaign/table/workspace ids.
-
-Empty or unsafe states stop with the blocker: no fillable target, missing or deleted campaign,
-missing table, archived/completed campaign, paused campaign without an explicit
-selected-start packet, zero sender capacity, zero source candidates, zero viable
-rows, no approved/preparable rows, active prep job, awaiting scheduler, or
-unsupported direct campaign type.
-
-## Regular Campaign Decision
-
-For regular campaign workspaces, rank regular campaigns from route and
-`get_campaign_refill_state` evidence. Choose the best existing refill target.
-The default campaign-scoped refill interpretation is "continue the campaign that
-was actually sending most recently for the relevant available senders", not
-"touch every active campaign". The default sender-scoped refill interpretation is
-"fill every eligible target sender from the best enrolled active campaign for
-that sender", not "fill only the first/best campaign globally".
-
-When managed waterfall bindings point at archived/completed campaigns but the
-dashboard has current unarchived `ACTIVE` or `PAUSED` campaigns for the same
-sender/shared lane, prefer the current dashboard-active campaign for target
-discovery. The stale waterfall slot remains diagnostic proof, not a reason to
-skip a visible paused shared campaign that can be started through a bounded
-packet.
-
-Default `--yolo` target is the scheduler-forward 48-hour window when the user
-asks to fill, refill, load, or max sends without naming a different horizon or
-exact `targetDate`.
-The planner selects sender-local days whose configured sending windows overlap
-that rolling target window; do not treat weekends or other no-send-hour days as
-fillable capacity. If the user explicitly names a no-send calendar date, report
-that date as unschedulable and continue only for the next valid send day when
-the packet says "send days" or the user asked to max/refill senders broadly.
-
-For campaign-scoped requests, compute the target from scheduler-fillable
-capacity in the selected target window/date, not the full daily limit. For
-sender-scoped requests, compute that scheduler-fillable gap per target sender
-across all active enrolled campaigns for that sender; count ready-to-schedule
-cells in any active enrolled campaign toward that sender's fillable gap before
-preparing more rows. If ready rows already cover a sender's scheduler-fillable
-gap, do not add rows or prep for that sender; report that the sender is loaded,
-awaiting scheduler. If the gap is positive, prepare only the gap in the best
-same-sender campaign and keep all source-copy/prep caps tied to that target
-window/date packet.
-Short form: default `--yolo refill senders` target is each eligible sender's
-scheduler-forward 48-hour gap.
-
-Lane selection must choose one refill lane per sender from current
-dashboard-active campaign-backed sequence evidence:
-
-1. Prefer the sender's most recent future scheduled refill action, then the most
-   recent recent scheduled refill action, then ready refill rows.
-2. Refill actions are `send_invite` or `send_inmail_closed`; unified Sales Nav
-   cascades also appear as `send_inmail_closed` with
-   `campaignClassification:"sales_nav_cascade"`.
-3. If the most recent active campaign evidence is DM, ignore it for refill lane
-   selection. If open InMail evidence belongs to a unified Sales Nav cascade,
-   keep the cascade campaign as the selected `send_inmail_closed` target; do not
-   create side open/paid/connection campaigns.
-4. If no connection/paid-InMail evidence exists, fall back to the selected
-   active campaign sequence, still choosing only one of `send_invite` or
-   `send_inmail_closed` for that sender.
-
-For `--yolo` fill/schedule requests, do not treat "ready" as completion. Build
-and maintain a target-window saturation ledger for every selected sender from
-`get_refill_target_plan`. A sender is complete only when a final target-plan or
-refill-state reread proves projected coverage (`sent + scheduled`) meets or
-exceeds the sender's capacity for the selected target window. Put another way:
-complete when the same daily-limit/readback model would show no remaining
-send-day capacity for that selected lane. Ready-to-schedule rows are only buffer
-for the product scheduler. If ready plus projected coverage covers the target
-window but scheduled cells do not yet, run a persistent read-only scheduler wait
-loop: wait, reread, recompute the ledger, and continue until projected coverage
-is proved, a concrete non-scheduler blocker appears, or Christian explicitly
-stops or asks for status only. `awaiting_scheduler_after_ready_buffer` is not
-success and is not a terminal blocker for an active refill goal; it is the
-loaded, awaiting scheduler poll state that keeps the thread waiting. It does not
-need a prep/import/approval packet.
-Short form: ready buffer is not success.
-Short form: keep polling the scheduler instead of closing out while ready buffer
-covers the gap.
-Short form: `--yolo refill senders` completes only on projected target-window
-saturation or a concrete blocker.
-
-Rank candidates in this order:
-
-1. **Sender match**: campaigns whose healthy sender ids match the user-named
-   senders, or the inferred sender set when the user said only "fill sends" or
-   "load senders". Do not include campaigns merely because they are active when
-   their sender set is unrelated.
-2. **Recent sends**: campaigns with the newest scheduler-owned scheduled counts
-   and non-null `scheduledFor` cells for those senders. Future scheduled sends
-   are stronger continuation evidence than old historical sends; otherwise use
-   the latest scheduled send date / newest scheduled-cell update from refill
-   state.
-3. **Continuation capacity**: campaigns with healthy senders, remaining daily
-   capacity, and a gap between current ready-to-schedule rows and the desired
-   sender capacity.
-4. **Same-campaign source health**: prefer campaigns whose current source has
-   enough `sourceAvailable` inventory to prepare the gap. If source inventory
-   is low or exhausted, choose same-campaign row replenishment before switching
-   campaigns.
-5. **Campaign scope**: keep the selected set small. For campaign-scoped
-   requests, normally choose one campaign. For sender-scoped requests, choose at
-   most one best campaign per target sender unless evidence shows one sender
-   needs multiple same-sender campaigns because the first is blocked or already
-   loaded.
-
-Do not create side campaigns, warm-post-engager side campaigns, on-demand campaigns,
-or unrelated campaigns as the default answer to a fill request.
-
-For each selected campaign, decide the next action by the smallest sufficient
-step:
-
-- **Enrich/prep more rows in the same campaign** when sender health is good,
-  recent sends point to this campaign, and `sourceAvailable` can cover the
-  ready-to-schedule gap.
-- **Add/import more rows to the same campaign/source path** when the campaign is
-  the right recent-send lane but source inventory or viable rows cannot cover
-  the gap.
-- **Use a different existing campaign** only when the recent-send/best-result
-  campaign for that sender is blocked, archived, missing sequence/source/senders,
-  disconnected, exhausted with no viable same-campaign replenishment path,
-  already loaded while the sender still has a gap, or the user explicitly asks
-  to move to another campaign.
-- **Ask what to create** only after resolver/state evidence shows there is no
-  suitable existing campaign for the requested sender set.
-
-When the best regular campaign is source-exhausted, recommend same-campaign source-ladder replenishment.
-Keep `selectedLeadListId` source identity distinct
-from the campaign `workflowTableId`.
-
-Source replenishment choices:
-
-- existing source list reuse: append/confirm the existing source list when it
-  has enough eligible rows;
-- CSV path: load CSV profiles/domains, then import into the same campaign/source
-  path;
-- Sales Nav path: use Sales Nav lookup/search, then import selected prospects;
-- Prospeo path: use account/person search as appropriate, then import selected
-  prospects;
-- Signal Discovery path: search/select posts or engagers, import selected
-  source prospects into the same campaign/source-list path, then confirm
-  readiness.
-
-When reusing an existing source list on an already-large campaign, handle the
-campaign-table row cap automatically in `--yolo` mode. If `confirm_lead_list`
-fails with `USER_ADDED_ROWS_LIMIT_EXCEEDED`, parse `remainingRows`,
-`currentRows`, `requestedRows`, and `maxRows`; do not stop just because the full
-source list is too large. Instead, create a bounded same-source split:
-
-1. choose a split size no larger than `remainingRows`, the two-day refill row
-   budget, and the first-pass processing cap unless the packet named a higher
-   cap;
-2. read compact rows from the current `selectedLeadListId` with
-   `get_rows_minimal`;
-3. create a temporary bounded LinkedIn profile source list with
-   `load_csv_linkedin_leads`, preserving useful source columns such as post URL,
-   post author, engagement type/text, keyword, confidence, and why;
-4. call `confirm_lead_list` with that bounded source-list id, the same campaign
-   id, and `currentStep:"running"` for ACTIVE campaigns;
-5. verify the campaign table row count and review batch with
-   `get_campaign_table_schema` before any prep/approval.
-
-Do not use `add_on_demand_leads` or create an on-demand table as the automatic
-regular-campaign fallback. The fallback must stay same-campaign and
-source-list-backed.
-Short form: row-cap fallback means bounded same-source split, not stop or on-demand.
-
-### Running Campaign Signal Discovery Recovery
-
-For an already-running regular campaign that needs same-campaign Signal
-Discovery replenishment, treat the watch/current-step transition as a guarded
-repair, not as normal create-campaign navigation.
-
-Do not call `search_signals` with `currentStep:"signal-discovery"` directly from `currentStep:"running"`. The campaign step guard intentionally rejects that
-backwards transition. After exact approval and a fresh refill-state reread, clear `currentStep` only if it still exactly matches `running`:
-
-```text
-update_campaign({ campaignId, currentStep:null, clearCurrentStepIfMatches:"running" })
-```
-
-Then register provider preflight and run a campaign-scoped `search_signals` so
-post rows exist in the campaign's Signal Discovery state:
+This prompt is operator choreography around `core/contract.v2.json` and
+`core/flow.v1.json`. The typed planner and durable run are the executable
+authority. Do not reconstruct allocation, preparation calibration, circuit
+backoff, scheduler selection, or completion mathematics in prose.
+
+Default mode is read-only research for both a regular campaign and an evergreen
+campaign. Mutation begins only through the typed approval or bounded yolo gates
+below.
+
+Call `get_refill_target_plan` first. Use projected coverage (`sent + scheduled`)
+as the completion measure, and preserve `targetShapeRevision` across every
+approved action. The workflow does not lower paid-InMail thresholds. Any
+threshold change remains a separate operator gate.
+
+## Read-only routing compatibility
+
+Preserve the established discovery order without reimplementing its decisions:
+
+1. Call `resolve_campaign_fill_route`; stop on `unsupported_campaign_type`.
+2. Call `get_campaign_refill_state` and bind `freshness.stateHash`. After any
+   primitive, reread `get_campaign_refill_state` before deciding again.
+3. Treat `fill_campaign_horizon` as a legacy evergreen-only lower-level primitive.
+   Reach it only through the durable contract when the current source is exhausted,
+   and preserve all scan/import caps.
+
+## Contract load
+
+Load both assets completely to `hasMore:false`. Require
+`workflow:"refill-sends-workflow"`, a supported v1 flow, contract major 2, and
+matching `contractVersion`, `cacheVersion`, `contractHash`, semantic ID sets,
+and backend projection hash. Any mismatch is a terminal pre-execution blocker.
+
+The public command is `refill_sends`. `refill_sends_v2` remains a
+server-internal implementation detail and is never advertised or invoked by a
+customer prompt.
+
+## Durable choreography
+
+1. Resolve and echo the explicit workspace and sender-local date scope.
+2. Read the canonical target packet. Render its normal bounded approval packet
+   even when yolo auto-accepts it.
+3. Preserve immutable workspace, selectors, date, timezone, contract/cache,
+   expected-target hash, placement cap, approval fingerprint, and installed
+   identities. Display labels never define scope.
+4. Execute exactly one current packet action through the public durable entry.
+   The run records planned -> did -> outcome, reconciles uncertain outcomes,
+   rereads authoritative target truth, and replans before another primitive.
+5. Treat expected scheduler targets as diagnostic receipts only. Placement
+   remains workspace-wide and every expected target must be `included` or
+   `omitted` with a typed reason.
+6. Stop exact preparation only after a fresh canonical deficit read proves the
+   target satisfied. Repeated zero-yield work follows the contract's closed,
+   open, and single-fenced half-open circuit receipts.
+
+Use the packet's campaign and sender names first. Preserve the six coverage
+labels: `Need to prepare`, `Goal`, `Already sent`, `Scheduled`,
+`Ready and waiting to be scheduled`, and `Still need`.
+
+## Approval and safety
+
+Interactive mode posts the complete packet in normal chat, then asks one compact
+host-native question with exactly `Accept` and `Decline`. Codex uses
+`request_user_input`; Claude Code uses `AskUserQuestion`. Decline means no
+mutation. A plain chat yes is not approval. Yolo is explicit bounded
+auto-accept of the rendered packet only.
+
+Preserve workspace access, approval, source-family, threshold, scheduler,
+campaign-lifecycle, send-time, and no-direct-send gates. Never direct-send,
+raw-write `scheduledFor`/`scheduledAt`, create/archive/delete campaigns, lower
+paid InMail thresholds, mutate sender configuration, or broaden source family.
+Only a packet-named paused campaign start or scheduler sweep may use the
+existing product-gated path. A scheduler sweep is customer-visible and may
+place unrelated eligible workspace cells within the approved global cap.
+
+Proof is Sellable MCP evidence only: target plan, refill state, scheduler
+capacity, complete target receipts, sender-dimensional changed counts, and
+durable run events. Never use cell IDs, Prisma, SQL, direct database access, or
+production scripts as completion proof.
+
+## Terminal report
+
+Render `projected_full` only from canonical projected coverage. Otherwise name
+the target-specific `concrete_blocker`, `deadline_reached`, `iteration_limit`,
+or `operator_stopped` receipt. `ready_buffer_exists_is_not_complete`; ready rows
+and `awaiting_scheduler_after_ready_buffer` are progress, not terminal success.
+
+<!-- REFILL_CONTRACT_GENERATED:START -->
+## Generated refill contract metadata
+
+contractVersion: 2.0.0
+cacheVersion: refill-contract-v1
+contractHash: e54ba0f80bc534fd70fd8c10c1caab109fe9a91c205cfc423f5f6735cd53fdc1
 
 ```text
-get_provider_prompt({ provider:"signal-discovery", campaignOfferId, confirmed:true })
-search_signals({ campaignOfferId, currentStep:"signal-discovery", confirmed:true, ... })
+scope: workspace_id, target_date, sender_selectors, campaign_selectors, approval_mode, contract_identity, installed_identity
+gates: approval_packet, one_primitive, fresh_reread, normalized_accounting, prep_circuit
+release identities (independent of semantic hash): mcpPackageVersion, installPackageVersion, codexPluginVersion
+forbidden: direct_send, raw_scheduler_write, campaign_create, campaign_archive_delete, threshold_lowering, unselected_source_mutation, unapproved_campaign_start, sender_config_write
+terminal: projected_full, concrete_blocker, deadline_reached, iteration_limit, operator_stopped, capped_by_scheduler, loaded_awaiting_scheduler, lanes_exhausted, not_an_evergreen_workspace, no_refillable_campaigns
+ready_buffer_exists_is_not_complete
 ```
-
-Use `select_promising_posts` before importing. For a fresh source refill, prefer
-`selectionMode:"replace"` and `scrapePlanMode:"all-selected"`, then call
-`import_leads` without `targetEngagerCount` or `maxPostsToScrape` so the scrape
-uses the selected posts' max available engagers within backend provider caps.
-Do not invent, lower, or pass a people-to-check target for refill imports unless
-Christian explicitly supplied that target or post cap in the current request or
-approval packet. If Christian did supply an explicit `targetEngagerCount` or
-`maxPostsToScrape`, use `scrapePlanMode:"capacity-target"` and respect the
-under-capacity refusal: ask for approval to expand the selected post set or
-switch source instead of scraping a target-mismatched set.
-
-If `import_leads` returns `reusedExistingSourceList` but the user explicitly
-approved a different selected-post scrape, retry `import_leads` with the existing `sourceLeadListId` from that response or from refill state. For Signal
-Discovery this bypasses the stale reuse guard and materializes the newly
-selected campaign-scoped posts into a fresh source list.
-
-After `wait_for_lead_list_ready`, call `confirm_lead_list` with the new
-source-list id and same campaign id. Pass `currentStep:"running"` to `confirm_lead_list` for an ACTIVE already-running campaign so the watched state
-returns to Running after same-campaign source rows are copied. Do not call
-`update_campaign` to fake this after the copy; `confirm_lead_list` owns the
-post-copy state transition.
-
-Before any source mutation, show exact approval evidence: workspace id,
-campaign name, campaign id, workflow table id, source/provider id, source-list
-id when known, import caps, target dates/caps, dedupe/DNC/provider exclusion expectations, and expected row side effects. Present the campaign name and plain-English reason first; include ids only as proof and execution targets.
-Then reread `get_campaign_refill_state`; if `freshness.stateHash` or exact ids
-changed, stop and ask for a fresh approval.
-
-After source import, call `wait_for_lead_list_ready` and `confirm_lead_list`
-with the source-list id and campaign id. Imports append to the existing
-campaign/source path; they must not reset campaign state, sequence, sender
-assignment, current step, or watch state. If provider auth, rate limit, timeout,
-partial import, duplicate-only import, DNC-only result, CSV parse failure,
-readiness timeout, or `confirm_lead_list` failure occurs, stop before prep and
-report the blocker/retry path.
-
-## Prep, Approval, And Scheduler Proof
-
-Existing rows normally move through enrichment/prep/approval using
-`start_campaign_message_preparation` and
-`get_campaign_message_preparation_status`. Standalone Generate Message is not the normal refill action;
-it is only for a manual/user-authored message path
-that requires it.
-
-Approval mode:
-
-- default is `approvalMode:"mark_ready"`, not approve;
-- use `approvalMode:"approve"` only when the user explicitly asks to approve
-  messages or schedule sends and has approved the exact bounded cohort;
-- `start_campaign` is allowed only as a bounded start/resume step for a
-  selected `PAUSED`, dashboard-active, campaign-backed sequence refill target;
-- never launch/start unrelated, archived, completed, draft, direct, or
-  non-selected campaigns from refill.
-
-Paused campaign start discipline:
-
-- `PAUSED`, dashboard-active campaign-backed sequence campaigns are existing
-  refill targets, not archived inventory.
-- If the route or active-campaign refetch marks a target as start-eligible, read
-  `get_campaign_refill_state` for that campaign/table before deciding whether to
-  start, prep, or skip it.
-- If the selected refill target is `PAUSED` and has healthy senders, sequence,
-  source/list, and ready/preparable rows or a bounded source/prep packet, the
-  final packet may include `start_campaign` when starting is needed for the
-  scheduler to schedule/send approved eligible rows.
-- In non-yolo mode, the `Accept` choice must say that starting the paused
-  campaign can let the product scheduler schedule/send approved eligible
-  sequence actions.
-- In `--yolo`, `start_campaign` is auto-accepted only for the exact selected
-  paused campaign ids, sender scope, caps, approval mode, and start side effect
-  named in the packet after the final reread.
-- Do not start if the campaign is archived, completed, draft, direct, lacks a
-  sequence/senders/source, has no viable row path, or state drifts.
-
-Before prep or approval mutation, reread `get_campaign_refill_state` and compare
-`freshness.stateHash`, campaign id, table id, workspace id, source id, and caps.
-If they changed, stop. A second concurrent refill run must see the first run's
-import/prep state on reread and avoid duplicate work.
-
-After the final reread and before the first mutating refill primitive, render
-one final approval packet in normal chat, in campaign-name-first language, so
-Codex/Claude can display the packet as Markdown. Then ask a host-native
-structured question with exactly two choices: `Accept` and `Decline`. The
-question is the execution boundary, but the full packet belongs in chat, not in
-the structured question body.
-Short form: exactly two choices: `Accept` and `Decline`.
-
-- In Codex interactive sessions, use `request_user_input`.
-- In Claude Code interactive sessions, use `AskUserQuestion`.
-- The normal chat message immediately before the structured question must
-  include this exact operator output packet shape:
-  - workspace name/id and mode (`--yolo` or approval-required);
-  - sender scope, including selected sender names and skipped sender names with
-    health/enrollment reasons;
-  - a campaign-by-campaign plan table with campaign name, sender names, action,
-    target count/cap, source/list, and blocker/skip reason;
-  - exact workspace id, campaign id, workflow table id, source/action ids when
-    relevant, freshness/state hash, caps/dates, approval mode, and the next
-    MCP primitive to call;
-  - expected side effects, including any exact-sender
-    `refresh_paid_inmail_credits` credit-cache writes, forbidden actions, and the
-    stop/rollback condition.
-- The structured question body must be compact and refer back to the posted
-  chat packet. Do not duplicate the campaign table or full operator packet
-  inside `request_user_input` / `AskUserQuestion`; refer back to the posted
-  packet instead of duplicating it.
-- The `Accept` choice description must name that it accepts only the posted
-  packet, with its exact workspace, campaign/table/source/action ids,
-  caps/dates, approval mode, side effects, and stop condition.
-- The `Decline` choice must stop with no mutation.
-- Do not proceed from a plain chat "ok", "yes", "go", or "do it" when the
-  structured question tool is available. If the structured question tool is not
-  available in an interactive session, stop and tell the user the quick question
-  panel is required for refill approvals. In non-interactive exec/automation,
-  print the approval packet and stop before mutation.
-
-`--yolo` mode is explicit auto-accept. If Christian includes `--yolo` in the
-same refill request, do not ask the `Accept` / `Decline` question. Instead:
-
-1. render the same final approval packet;
-2. reread `get_campaign_refill_state` and, when the packet includes paid-InMail
-   credit refreshes, verify the current `get_refill_target_plan` action
-   candidates still name the same sender ids, campaign ids, table ids, and
-   column ids;
-3. verify the route, workspace id, campaign id, table id, source/action ids,
-   caps/dates, approval mode, blockers, and side-effect class still match the
-   packet;
-4. execute only the exact packet;
-5. after each terminal credit-refresh/apply/prep/source-copy/bounded-approval/read-only wait result, rerun
-   `get_refill_target_plan`, reread state, settle processing when needed,
-   recompute the target-window saturation ledger, and continue with the next smallest
-   safe action inside the same bounded packet until every selected sender is
-   saturated by projected coverage or blocked by non-scheduler evidence. Do not
-   stop at "loaded" or "awaiting scheduler"; when no in-packet MCP mutation
-   remains and ready rows cover the gap, keep the run open in read-only
-   scheduler polling until the sender is projected-full or Christian stops it.
-
-In `--yolo`, do not stop after the first selected campaign if the request was
-sender-scoped and more selected senders or same-packet start-eligible campaigns
-remain. If the first candidate is duplicate-only, already loaded, awaiting
-scheduler, source-exhausted, or otherwise blocked, continue to the next
-same-sender candidate that was already in the rendered packet and still matches
-the fresh route/refill-state evidence. If no in-packet safe action remains, stop
-before mutation and return continuation options instead of guessing.
-
-Continuation options must be campaign-name-first and concrete. For each blocked
-sender/campaign, list the next viable options with exact ids and the approval
-boundary, for example: start an already selected start-eligible paused campaign,
-repair stale waterfall bindings, replenish the current source, expand Signal
-Discovery post selection, use the next same-sender campaign, or run evergreen
-setup/repair. Mark which options are covered by the current `--yolo` packet and
-which require a new approval packet.
-Short form: in `--yolo`, go as far as the packet safely allows, then give exact continuation options.
-
-`--yolo` authorizes `start_campaign` only for selected `PAUSED` refill targets
-named in the exact packet. It never authorizes starting unrelated, archived,
-completed, draft, or direct campaigns, separate launch/send actions,
-archive/delete cleanup, raw scheduler writes, sender reassignment, paid-InMail
-credit refreshes for senders not named in the packet, extra senders beyond the
-eligible sender set, or higher caps than the packet named. In
-sender-scoped `--yolo`, a bounded packet containing all eligible enrolled
-senders and at most one best campaign per sender is covered; arbitrary expanded
-campaign sets are not. If any state or scope drifts, stop and re-plan instead of
-auto-accepting the changed action.
-Short form: all eligible enrolled senders are covered by sender-scoped `--yolo`; arbitrary expanded campaign sets are not.
-Short form: direct scheduler writes are not covered by `--yolo`.
-Short form: stop and re-plan instead of auto-accepting the changed action.
-
-Before choosing a refill prep primitive, inspect the table frontier from
-`get_campaign_refill_state.preparationFrontier`. If
-`hasLaterPreparedIsland:true` or `earliestUnpreparedRow` exists before later
-successful enrichment, treat that as a top-down gap: use
-`select_campaign_cells`/`queue_campaign_cells` with
-`rowSelector:{ type:"needsEnrichment" }` and `columnRole:"enrich"` in bounded
-row-position order, or use `start_campaign_message_preparation` with the
-adaptive defaults for the full enrich -> rubric -> Generate Message loop. Do not
-use the UI Jump anchor as the automation cursor; Jump is a navigation affordance
-and can be fooled by a later enriched island.
-
-After same-campaign source copy, inspect the actual campaign-table position of
-the copied rows before starting prep. Newly copied rows often land after the
-first 100 table rows. Use `get_campaign_table_schema` to read the `reviewBatch`
-and `select_campaign_cells` diagnostics against
-`rowSelector:{ type:"reviewBatch" }` only to understand the copied row set. Do
-not operate on `reviewBatch` before earlier `needsEnrichment` rows unless the
-approved packet explicitly says to prioritize the just-copied bounded split and
-the earlier rows are exhausted, dependency-blocked, or intentionally excluded.
-
-For bounded split refills, prefer top-down `needsEnrichment` or adaptive
-`start_campaign_message_preparation` first. If the bounded packet explicitly
-uses `approvalMode:"approve"` because the user asked to fill/schedule sends or
-provided `--yolo` for a two-day send fill, inspect approval candidates with
-`rowSelector:{ type:"needsApproval" }` after current generated messages exist,
-then approve only the bounded cohort covered by the packet. Do not broad approve
-existing table rows.
-
-If enrich cells are pending or Generate Message cells are dependency-blocked,
-omit `maxRowsToCheck` so the adaptive prep job can cover the bounded table scan,
-or set a bounded cap high enough to include the necessary row-position frontier
-when row count evidence requires it. Do not run a fixed `maxRowsToCheck:100`
-prep pass after appending rows to a larger existing campaign table; it can spend
-the whole budget on older rows and miss the refill batch.
-
-Bound `targetPreparedMessages` to the actual ready-to-schedule gap for the
-selected campaign and sender set. In sender-scoped mode, compute and report the
-gap per sender. If ready/scheduled rows across active enrolled campaigns already
-cover a sender's gap, do not start prep for that sender; report that the sender
-is already loaded and awaiting the scheduler. If source inventory is available
-and the gap is small, prepare only the sender gap instead of filling every active
-campaign.
-Short form: prepare only the per-sender gap instead of filling every active campaign.
-
-Scheduled success requires a post-action reread proving scheduler-owned cells
-with non-null `scheduledFor`. Prepared, approved, and ready-to-schedule rows are
-intermediate states; report them as awaiting scheduler unless scheduled cells
-are present.
-
-preparedMessages can remain 0 while scheduler-ready state changes downstream.
-After a prep job reaches a terminal state, run `wait_for_campaign_processing`
-when generated/pass counts are still settling, then poll `get_campaign_refill_state` until `readyToSchedule` drops, scheduled counts increase, or the state clearly
-remains awaiting scheduler. Do not force scheduler fields directly.
-
-For requested fill/refill completion, continue the saturation loop after each
-poll: recompute projected target-window coverage by sender and date, subtract it
-from the requested target capacity, and decide whether another safe prep/import/
-approval pass is required. If projected coverage is still short and ready buffer
-is also short, run the next bounded MCP primitive that can create more eligible
-rows: `fill_campaign_horizon` for the selected evergreen target, or
-`start_campaign_message_preparation`, source import/replenishment, and bounded
-approval for the selected regular target. If projected coverage is short but
-ready buffer covers the gap, keep polling the scheduler until it fills, a
-concrete non-scheduler blocker appears, or Christian explicitly stops/statuses
-the run. Never mark the refill complete or blocked while a daily limit/readback
-equivalent would still show the selected send day below capacity and the only
-remaining state is scheduler pickup.
-
-## Evergreen Campaign Discipline
-
-`fill_campaign_horizon` is a legacy evergreen-only lower-level primitive. Call it
-only after `resolve_campaign_fill_route` and `get_campaign_refill_state` prove an
-evergreen campaign target.
-
-For evergreen campaigns, do not advance down the source ladder while the current source can produce enough good prospects.
-The current source is exhausted, or
-unable to produce enough good prospects, only when evidence includes source id,
-target prospect gap, cursor/inventory state, dedupe/DNC/provider exclusions,
-good-prospect yield, and scan/import caps. If that proof is missing, continue
-the current source or ask for more research instead of walking the ladder.
-
-## Hard Safety Rules
-
-- Never call launch/start tools except `start_campaign` for an exact selected
-  `PAUSED`, dashboard-active, campaign-backed sequence refill target in the
-  rendered packet.
-- Never raw-write `scheduledFor`, `scheduledAt`, scheduled status, or sender
-  assignment fields.
-- Never expose internal direct campaign types as an operator refill path.
-- Never claim scheduled success without rereading scheduler-owned cells with
-  non-null `scheduledFor`.
-- Never call `refresh_paid_inmail_credits` except for exact sender ids named in
-  the rendered refill packet; after refresh, rerun `get_refill_target_plan` and
-  stop if the fresh status is still missing, stale, below threshold, or drifts to
-  a different campaign/table/column.
-- No mutation in production unless Christian explicitly approves exact
-  workspace, campaign/table ids, source/action ids, caps/dates, approval mode,
-  expected side effects, and rollback/stop condition.
-- In interactive Codex or Claude Code, that explicit approval must be collected
-  through the host-native `Accept` / `Decline` question gate.
-- `--yolo` in the current refill request is explicit auto-accept for the
-  rendered bounded refill packet only; it does not loosen the unrelated-campaign
-  start/send, scheduler-write, archive/delete, or drift rules above.
-
-## Report
-
-Report in campaign-name-first language:
-
-- selected campaign name(s), target type, and sender names;
-- why they were selected, including last scheduled send date/future scheduled
-  send evidence and sender overlap;
-- whether the smallest next step is enrich/prep more in that campaign, add rows
-  to that campaign/source, use a different existing campaign, or ask what to
-  create;
-- source state, blockers, exact next primitive, approval required, and the
-  freshness hash used.
-- for `--yolo`, how far the run continued automatically, which selected senders
-  are loaded/scheduled/awaiting scheduler, and the exact continuation options for
-  any sender/campaign that remains blocked.
-
-Keep ids visible but secondary: show them under "Exact target" or "Proof", not
-as the main decision text. Say explicitly whether a selected paused campaign was
-started; otherwise say nothing was started and nothing was sent.
+<!-- REFILL_CONTRACT_GENERATED:END -->