@sellable/install 0.1.306 → 0.1.307

package/bin/sellable-install.mjs

@@ -1122,6 +1122,7 @@ const REFILL_SENDS_ALLOWED_TOOLS = [
   "mcp__sellable__get_subskill_asset",
   "mcp__sellable__search_subskill_prompts",
   "mcp__sellable__get_scheduler_fill_capacity",
+  "mcp__sellable__run_scheduler_sweep",
   "mcp__sellable__refresh_paid_inmail_credits",
   "mcp__sellable__list_senders",
   "mcp__sellable__get_sender_routing",
@@ -2086,9 +2087,9 @@ Desktop, then start a new thread.
 
 1. Call \`mcp__sellable__get_auth_status({})\`.
 2. Resolve the target workspace id from the user request, automation config, or install-time workspace mapping. Pass \`workspaceId\` on every scheduled or \`--yolo\` refill tool call. Missing \`workspaceId\` in scheduled or \`--yolo\` mode is a blocker; return \`WORKSPACE_REQUIRED\` instead of running against shared config state. Do not solve automation workspace uncertainty by changing the shared active workspace.
-3. Normalize invocation arguments with \`mcp__sellable__refill_sends({ yolo, executionMode, requireWorkspace, workspaceId, senders, senderIds, senderNames, targetDate, untilDate })\` when the host exposes typed MCP tools. Type shape: \`refill_sends({ yolo?: boolean, executionMode?: "manual" | "scheduled" | "yolo", requireWorkspace?: boolean, workspaceId?: string, senders?: string[], senderIds?: string[], senderNames?: string[], horizonSendDays?: number, untilDate?: "YYYY-MM-DD", targetDate?: "YYYY-MM-DD" })\`.
+3. Normalize invocation arguments with \`mcp__sellable__refill_sends({ yolo, executionMode, requireWorkspace, workspaceId, senders, senderIds, senderNames, horizonSendDays, targetDate, untilDate })\` when the host exposes typed MCP tools. Type shape: \`refill_sends({ yolo?: boolean, executionMode?: "manual" | "scheduled" | "yolo", requireWorkspace?: boolean, workspaceId?: string, senders?: string[], senderIds?: string[], senderNames?: string[], horizonSendDays?: number, untilDate?: "YYYY-MM-DD", targetDate?: "YYYY-MM-DD" })\`.
 4. Clover scheduled automation example: \`mcp__sellable__refill_sends({ yolo:false, executionMode:"scheduled", requireWorkspace:true, workspaceId:"cmlq1v8ms0000jx04ang4hi7e" })\`, then \`mcp__sellable__get_refill_target_plan({ intent:"plain", approvalMode:"mark_ready", workspaceId:"cmlq1v8ms0000jx04ang4hi7e" })\`.
-5. Call \`mcp__sellable__get_refill_target_plan({ workspaceId, senders, senderIds, senderNames, targetDate, untilDate })\` before any mutation. Render \`target.eligibleSenderLedger\`, \`target.senderRefillPlans[]\`, and \`target.globalActionQueue\` as the structured packet. Preserve the labels \`Need to prepare\`, \`Goal\`, \`Already sent\`, \`Scheduled\`, \`Ready and waiting to be scheduled\`, and \`Still need\`. In \`--yolo\`, \`mcp__sellable__refill_sends\` maintains a run-local \`refreshedPaidInmailSenderIds\` set, refreshes stale/missing paid InMail facts for each selected paid-InMail sender at most once, reruns \`get_refill_target_plan\`, and returns \`autoPaidInmailRefresh\` plus the post-refresh \`targetPlan\` before choosing the next prep/source-copy/bounded-approval/read-only wait action. Refill ladder: approve generated rows only through the explicit bounded approval gate, process existing same-campaign unenriched/unprepared rows before source work, then same-source copy, then provider-aligned source-more. New source/provider switches change reply-rate baseline and are manual alternates, not \`--yolo\` side effects. Do not present paid-credit refresh as the next operator action after \`refill_sends\` returns that post-refresh plan. For exact-date proof, \`mcp__sellable__get_scheduler_fill_capacity\` is read-only and tells how many cells the scheduler will try to place for a sender/action/date. If the returned target is already complete, stop with the no-op receipt. If ready rows cover the target but scheduled rows do not, keep the run open in the read-only scheduler wait/re-read loop until projected coverage fills, a concrete non-scheduler blocker appears, or Christian explicitly stops/statuses the run.
+5. Call \`mcp__sellable__get_refill_target_plan({ workspaceId, senders, senderIds, senderNames, horizonSendDays, targetDate, untilDate })\` before any mutation. Render \`target.eligibleSenderLedger\`, \`target.senderRefillPlans[]\`, and \`target.globalActionQueue\` as the structured packet. Preserve the labels \`Need to prepare\`, \`Goal\`, \`Already sent\`, \`Scheduled\`, \`Ready and waiting to be scheduled\`, and \`Still need\`. In \`--yolo\`, \`mcp__sellable__refill_sends\` maintains a run-local \`refreshedPaidInmailSenderIds\` set, refreshes stale/missing paid InMail facts for each selected paid-InMail sender at most once, reruns \`get_refill_target_plan\`, and returns \`autoPaidInmailRefresh\` plus the post-refresh \`targetPlan\` before choosing the next prep/source-copy/bounded-approval/read-only wait action. Refill ladder: approve generated rows only through the explicit bounded approval gate, process existing same-campaign unenriched/unprepared rows before source work, then same-source copy, then provider-aligned source-more. New source/provider switches change reply-rate baseline and are manual alternates, not \`--yolo\` side effects. Do not present paid-credit refresh as the next operator action after \`refill_sends\` returns that post-refresh plan. For exact-date proof, \`mcp__sellable__get_scheduler_fill_capacity\` is read-only and tells how many cells the scheduler will try to place for a sender/action/date. When ready rows cover the target but scheduled rows do not, \`mcp__sellable__run_scheduler_sweep({ workspaceId, action:"run", targetDate })\` may request immediate placement within existing gates and returns a receipt, but it never sends or bypasses limits. If the returned target is already complete, stop with the no-op receipt. If ready rows cover the target but scheduled rows do not, keep the run open in the read-only scheduler wait/re-read loop until projected coverage fills, a concrete non-scheduler blocker appears, or Christian explicitly stops/statuses the run.
 6. Load the canonical prompt and deterministic flow asset via
    \`mcp__sellable__get_subskill_prompt({ subskillName: "refill-sends" })\`,
    then load \`mcp__sellable__get_subskill_prompt({ subskillName: "refill-sends-workflow" })\`,

package/lib/runtime-verify.mjs

@@ -32,7 +32,7 @@ export const REQUIRED_SELLABLE_MCP_TOOLS = [
   "get_campaign_refill_state",
   "get_refill_target_plan",
   "get_scheduler_fill_capacity",
-  "refresh_paid_inmail_credits",
+  "run_scheduler_sweep",
   "refill_sends",
   "setup_evergreen_campaigns",
   "start_campaign_message_preparation",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sellable/install",
-  "version": "0.1.306",
+  "version": "0.1.307",
   "type": "module",
   "description": "One-command installer for Sellable MCP in Claude Code, Codex, and Hermes",
   "bin": {

package/skill-templates/refill-sends-v2.md

@@ -37,16 +37,21 @@ active workspace readback. Scheduled or autonomous usage must carry
 `workspaceId` on every tool call. If the workspace is missing or ambiguous, stop
 with `WORKSPACE_REQUIRED`; do not switch the shared active workspace.
 
+Date selectors are sender-local and mutually exclusive by precedence:
+`targetDate > untilDate > horizonSendDays`. Use `targetDate` for one exact sender-local date, `untilDate` for an inclusive through-date, and `horizonSendDays` for the next N sender-local send days. If none is provided, the planner uses the default scheduler-forward 48-hour behavior.
+
 For a real refill run:
 
 ```text
-refill_sends_v2({ workspaceId, intent:"auto", senderIds?, approvalMode? })
+refill_sends_v2({ workspaceId, intent:"auto", senderIds?, approvalMode?, targetDate?, untilDate?, horizonSendDays? })
+refill_sends_v2({ workspaceId, targetDate:"2026-07-07" })
+refill_sends_v2({ workspaceId, untilDate:"2026-07-09" })
 ```
 
 For read-only inspection:
 
 ```text
-refill_sends_v2({ workspaceId, dryRun:true, intent:"auto", senderIds? })
+refill_sends_v2({ workspaceId, dryRun:true, intent:"auto", senderIds?, targetDate?, untilDate?, horizonSendDays? })
 ```
 
 To resume an in-progress run, pass the handle back exactly:
@@ -55,6 +60,11 @@ To resume an in-progress run, pass the handle back exactly:
 refill_sends_v2({ workspaceId, runId, fence })
 ```
 
+The original run's date window is stored in the run record. On resume, the
+stored window is reused and conflicting resume input is blocked; do not add,
+change, or remove `targetDate`, `untilDate`, or `horizonSendDays` while passing
+an existing `{ runId, fence }`.
+
 If a stale handle loses the lease, the tool reports the holder status and the
 approximately 10 minute lockout window. Reinvoke with the current handle or wait
 for lease expiry; never guess a fence.
@@ -125,9 +135,23 @@ host guard, heartbeats the run lease, and may return:
 ```
 
 Reinvoke with that handle. The approximately five minute scheduler budget is at
-the run level, not one tool call. A window-closed or loaded-awaiting scheduler
-report must include remaining-ready count, exact expected pickup time, and the
-resume handle; never treat bare "awaiting scheduler" copy as a final answer.
+the run level, not one tool call. Exact-date runs request pickup with
+`run_scheduler_sweep({ workspaceId, targetDate })`; `untilDate` and
+`horizonSendDays` runs sweep each planner-selected exact target date. A
+window-closed or loaded-awaiting scheduler report must include remaining-ready
+count, exact expected pickup time, and the resume handle; never treat bare
+"awaiting scheduler" copy as a final answer.
+Scheduler-run receipt interpretation still applies to terminal progress:
+`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`, `skipped`, and `deferred` separately. For ready closed-InMail
+cells with stale paid-credit reasons, route to
+`refresh_paid_inmail_credits_then_rerun` once, then rerun/status.
+`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.
 
 After the first prep batch, read the conversion-verdict journal line. It is
 rendered from packet facts: `supplyCensus`, `censusReason`, and

package/skill-templates/refill-sends.md

@@ -6,6 +6,7 @@ allowed-tools:
   - mcp__sellable__refill_sends
   - mcp__sellable__get_refill_target_plan
   - mcp__sellable__get_scheduler_fill_capacity
+  - mcp__sellable__run_scheduler_sweep
   - mcp__sellable__refresh_paid_inmail_credits
   - mcp__sellable__get_subskill_asset
   - mcp__sellable__get_auth_status
@@ -86,6 +87,12 @@ Accepted invocation flags in the same user request:
   preserves natural-language arguments better than shell-style flags.
 - `targetDate: YYYY-MM-DD`: exact-date selector alternative when the host
   preserves natural-language arguments better than shell-style flags.
+- `horizonSendDays: N`: compatibility selector for the next N sender-local send
+  days when no exact or through-date selector is present.
+
+Date selector precedence is `targetDate > untilDate > horizonSendDays`. Use
+`targetDate` for one exact sender-local date, `untilDate` for an inclusive
+through-date, and `horizonSendDays` for the next N sender-local send days.
 
 When the host can call typed MCP tools, start with:
 
@@ -114,10 +121,11 @@ or install-time workspace mapping. Pass `workspaceId` on every scheduled or
 `--yolo` refill tool call, including setup/read calls such as
 `refill_sends`, `get_refill_target_plan`, `list_senders`,
 `get_sender_routing`, `resolve_campaign_fill_route`,
-`get_campaign_refill_state`, `get_scheduler_fill_capacity`, and any later
-refill mutation covered by the packet. Missing `workspaceId` in scheduled or
-`--yolo` mode is a blocker; stop with `WORKSPACE_REQUIRED` instead of running
-against an implicit or guessed workspace.
+`get_campaign_refill_state`, `get_scheduler_fill_capacity`,
+`run_scheduler_sweep`, and any later refill mutation covered by the packet.
+Missing `workspaceId` in scheduled or `--yolo` mode is a blocker; stop with
+`WORKSPACE_REQUIRED` instead of running against an implicit or guessed
+workspace.
 
 Do not solve scheduled or `--yolo` workspace uncertainty by changing the shared
 active workspace. Manual interactive workspace switching remains a separate
@@ -269,6 +277,25 @@ need raw proof, call the read-only `get_scheduler_fill_capacity` query for the
 same sender/action/date; it tells the MCP how many cells the product scheduler
 will try to place and does not import, approve, schedule, refresh credits, or
 mutate.
+When the refill loop has ready rows and needs scheduler pickup now, use
+`run_scheduler_sweep({ workspaceId, targetDate })` for exact-date requests. For
+`untilDate` or `horizonSendDays` requests, sweep each planner-selected
+`targetDate` with the same explicit `workspaceId`. The sweep can place cells
+within existing scheduler gates and returns the receipt, but it never sends or
+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 the target plan is complete by projected coverage, report that the selected
 target is already filled and no-op without asking for approval. If the ready
 buffer covers the projected gap, paid InMail credit facts are fresh for every