@sellable/install 0.1.304 → 0.1.305

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",
@@ -2088,7 +2089,7 @@ Desktop, then start a new thread.
 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" })\`.
 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, 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" })\` 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,6 +32,7 @@ export const REQUIRED_SELLABLE_MCP_TOOLS = [
   "get_campaign_refill_state",
   "get_refill_target_plan",
   "get_scheduler_fill_capacity",
+  "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.304",
+  "version": "0.1.305",
   "type": "module",
   "description": "One-command installer for Sellable MCP in Claude Code, Codex, and Hermes",
   "bin": {

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

@@ -128,6 +128,17 @@ 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.
+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
@@ -114,10 +115,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 +271,23 @@ 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` with the same explicit `workspaceId`; it 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