@sellable/mcp 0.1.556 → 0.1.557

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

@@ -1,6 +1,6 @@
 ---
 name: refill-sends-workflow
-description: Internal typed workflow contract for regular and evergreen campaign refills.
+description: Internal skill-led refill sends workflow for regular campaigns and evergreen campaigns.
 visibility: internal
 allowed-tools:
   - mcp__sellable__get_subskill_asset
@@ -49,105 +49,748 @@ allowed-tools:
 
 # Refill Sends Workflow
 
-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
+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:
 
 ```text
-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
+get_provider_prompt({ provider:"signal-discovery", campaignOfferId, confirmed:true })
+search_signals({ campaignOfferId, currentStep:"signal-discovery", confirmed:true, ... })
 ```
-<!-- REFILL_CONTRACT_GENERATED:END -->
+
+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.