@sellable/mcp 0.1.513 → 0.1.514

package/dist/tools/registry.d.ts

@@ -474,6 +474,39 @@ export declare const allTools: ({
         required: string[];
         additionalProperties: boolean;
     };
+} | {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {
+            intent: {
+                type: string;
+                enum: string[];
+                description: string;
+            };
+            campaignId: {
+                type: string;
+                description: string;
+            };
+            tableId: {
+                type: string;
+                description: string;
+            };
+            limit: {
+                type: string;
+                minimum: number;
+                maximum: number;
+                description: string;
+            };
+            workspaceId: {
+                type: string;
+                description: string;
+            };
+        };
+        required: string[];
+        additionalProperties: boolean;
+    };
 } | {
     name: string;
     description: string;
@@ -2295,6 +2328,24 @@ export declare const allTools: ({
         };
         required: string[];
     };
+} | {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {
+            senderId: {
+                type: string;
+                description: string;
+            };
+            workspaceId: {
+                type: string;
+                description: string;
+            };
+        };
+        required: string[];
+        additionalProperties: boolean;
+    };
 } | {
     name: string;
     description: string;
@@ -2583,6 +2634,43 @@ export declare const allTools: ({
         };
         required: never[];
     };
+} | {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {
+            workspaceId: {
+                type: string;
+                description: string;
+            };
+            senderIds: {
+                type: string;
+                items: {
+                    type: string;
+                };
+            };
+            runState: {
+                type: string;
+                description: string;
+            };
+            intent: {
+                type: string;
+                enum: string[];
+                description: string;
+            };
+            journal: {
+                type: string;
+                description: string;
+            };
+            journalNote: {
+                type: string;
+                description: string;
+            };
+        };
+        required: string[];
+        additionalProperties: boolean;
+    };
 } | {
     name: string;
     description: string;
@@ -7193,6 +7281,33 @@ export declare const allTools: ({
                 type: string;
                 description: string;
             };
+            runId: {
+                type: string;
+                description: string;
+            };
+            fence: {
+                type: string;
+                description: string;
+            };
+            dryRun: {
+                type: string;
+                description: string;
+            };
+            approvalMode: {
+                type: string;
+                enum: string[];
+                description: string;
+            };
+            senderIds: {
+                type: string;
+                items: {
+                    type: string;
+                };
+            };
+            intent: {
+                type: string;
+                enum: string[];
+            };
         };
         required: string[];
         additionalProperties: boolean;
@@ -7541,6 +7656,59 @@ export declare const allTools: ({
         required: string[];
         additionalProperties: boolean;
     };
+} | {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {
+            capacityRequests: {
+                type: string;
+                minItems: number;
+                items: {
+                    type: string;
+                    properties: {
+                        senderId: {
+                            type: string;
+                            description: string;
+                        };
+                        actionType: {
+                            type: string;
+                            enum: string[];
+                            description: string;
+                        };
+                        cellId: {
+                            type: string;
+                            description: string;
+                        };
+                        columnId: {
+                            type: string;
+                            description: string;
+                        };
+                    };
+                    required: string[];
+                    additionalProperties: boolean;
+                };
+                description: string;
+            };
+            targetDate: {
+                type: string;
+                pattern: string;
+                description: string;
+            };
+            mode: {
+                type: string;
+                enum: string[];
+                description: string;
+            };
+            workspaceId: {
+                type: string;
+                description: string;
+            };
+        };
+        required: string[];
+        additionalProperties: boolean;
+    };
 } | {
     name: string;
     description: string;

package/package.json

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

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

@@ -1,6 +1,6 @@
 ---
 name: refill-sends-v2
-description: Plan refill sends v2 work through the read-only three-lane dry-run planner.
+description: Execute refill sends v2 through the fenced evergreen refill loop, with dry-run and resume support.
 visibility: public
 allowed-tools:
   - mcp__sellable__refill_sends_v2
@@ -15,19 +15,20 @@ allowed-tools:
 
 # Refill Sends V2
 
-Use this public command wrapper for refill planning requests such as "refill
-sends", "fill evergreen senders", "load everyone up", "plan Damiano", or "show a
-dry-run for this workspace".
+Use this command for refill requests such as "refill sends", "fill evergreen
+senders", "load everyone up", "run Damiano", or "show a dry run for this
+workspace".
 
 Host command names:
 
 - Claude Code: `/sellable:refill-sends-v2`
 - Codex: `$sellable:refill-sends-v2`
 
-This is plan-only, read-only, dry-run, zero mutations. It creates no campaigns,
-does not prepare or approve messages, does not start campaigns, does not
-schedule or send messages, does not refresh paid InMail credit facts, and does
-not change source configuration. Execution remains in the Phase 86 workflow.
+`refill_sends_v2` is the execution surface. In real-run mode it starts or
+resumes a fenced refill run, reads a fresh packet, executes only the packet's
+named bounded work, verifies the result, and returns either a terminal report, a
+blocked report, or an in-progress resume handle. In dry-run mode it stays
+read-only and writes only a dry-run journal.
 
 ## Entry
 
@@ -36,61 +37,120 @@ 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.
 
-Start with the command contract:
+For a real refill run:
 
 ```text
-refill_sends_v2({ workspaceId })
+refill_sends_v2({ workspaceId, intent:"auto", senderIds?, approvalMode? })
 ```
 
-Then load the internal workflow prompt and flow asset:
+For read-only inspection:
 
 ```text
-get_subskill_prompt({ subskillName: "refill-sends-v2-workflow" })
-get_subskill_asset({ subskillName: "refill-sends-v2-workflow", assetPath: "core/flow.v1.json" })
+refill_sends_v2({ workspaceId, dryRun:true, intent:"auto", senderIds? })
 ```
 
-Continue both loads until `hasMore:false`; parse the flow JSON and verify
-`workflow:"refill-sends-v2-workflow"` with a `v1` version before the planner
-call.
+To resume an in-progress run, pass the handle back exactly:
 
-Call the dry-run planner with the explicit workspace id:
+```text
+refill_sends_v2({ workspaceId, 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.
+
+The default `intent:"auto"` inspects `managed_waterfall`,
+`dashboard_evergreen`, and `active_campaign` lane sources. Report the lane
+source and lane chain as proof for every selected sender.
+
+If membership blocks a workspace read, report the structured
+`workspace_access` blocker instead of retrying auth or switching workspaces.
+
+## Authority
+
+The run may execute only packet-named bounded work:
+
+- approve generated messages that are ready for review (`approve_messages`);
+- enrich the next batch of unenriched rows (`enrich_more`);
+- copy leads already found into the campaign table (`reconcile_source_copy`);
+- re-run errored enrichment/message cells (`rerun_errored_cells`);
+- find more leads via this campaign's original source (`add_leads_same_source`)
+  only for mechanical same-source continuations;
+- start the paused campaign so ready rows can schedule (`start_campaign`) only
+  when the campaign is in the packet's pinned lane chain;
+- refresh paid InMail credit facts during bootstrap and once per scheduler-wait
+  entry when the packet requires it.
+
+The loop records planned -> did -> outcome before and after every foreign
+mutation. It refuses stale packets by fingerprint and validates packet
+coherence before dispatch. The planner owns repair decisions: if a batch needs
+repair, the next packet names the repair rung; the loop bounds and refuses, it
+does not improvise fixes.
+
+Do not create campaigns, switch provider families, lower thresholds, write
+scheduler fields, send messages, archive/delete campaigns, or mutate
+brief/filter/message/sequence/sender config unless a separate exact approval
+packet explicitly authorizes that work. In short: no campaign creation, no
+provider-family switch, no threshold lowering, no scheduler writes, no
+launch/send/archive/delete, and no brief/filter/message/sequence/sender
+mutation.
+
+## Continuations
+
+Sales Nav and Prospeo source continuations that are not yolo-safe are blocked
+as executable scoped handoffs. The report will include text shaped like:
 
 ```text
-get_refill_plan_v2({ workspaceId, intent:"auto", senderIds?, runState?, journal?, journalNote? })
+$sellable:create-campaign [campaignId]
 ```
 
-The default `intent:"auto"` checks the three lane-source families in order:
-
-- `managed_waterfall` for product-managed evergreen waterfall lanes.
-- `dashboard_evergreen` for dashboard-visible evergreen campaigns.
-- `active_campaign` for regular active campaigns that should refill through a
-  deterministic lane chain.
-
-Use `senderIds` only when the user scoped the request to exact senders. Use
-`runState` only for an explicit what-if dry run; otherwise let the MCP read
-local lane memory hints. Leave `journal` enabled unless the user specifically
-asked for no local journal.
-
-## Report
-
-Review the returned packet before giving a recommendation:
-
-- `planRevision` starts with `pr1:`.
-- `stateRevision` identifies the current readback.
-- `packet` is the operator-facing facts receipt.
-- `plans[]` contains per-sender lane decisions and itinerary details.
-- `globalActionQueue[]` is a dry-run sequence only.
-- `evergreen.laneOrder[].source` uses `managed_waterfall`,
-  `dashboard_evergreen`, or `active_campaign`.
-- `evergreen.senderLaneSelections[].laneChain` records the ordered lane chain
-  when a regular active campaign chain is selected.
-- Terminals can include `done` or `no_refillable_campaigns`.
-- A membership 403 must return the structured `workspace_access` blocker; report
-  it as a read-only blocker, not a login retry.
-- `journalPath` points to the dry-run markdown journal written by the MCP.
-- `sideEffects` must be all false.
-
-Report campaign names and sender names first, ids second. Include the lane
-source, lane chain when present, chosen rung, itinerary, plan revision, journal
-path, and any blockers or warnings. Stop after the report; do not execute the
-action queue.
+That handoff is run in a separate thread only after explicit approval. Scope is
+strict: add leads through this campaign's existing source, keep the same
+saved-search identity, import mode `add` into the same source list, and do
+source work only. It is never a new campaign, provider-family switch, brief
+change, rubric change, message change, sequence change, or sender change.
+
+## Verification
+
+The loop verifies whole rows before replanning. It reattaches to an own active
+prep job instead of re-dispatching, waits on foreign prep jobs without adopting
+their outcomes, waits on active enrichment/import work by rereading the packet,
+and treats capped scheduler capacity as complete.
+
+Scheduler waits are cross-invocation. Each tool call polls briefly under the
+host guard, heartbeats the run lease, and may return:
+
+```text
+{ status:"in_progress", runId, fence, gate, guidance }
+```
+
+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.
+
+After the first prep batch, read the conversion-verdict journal line. It is
+rendered from packet facts: `supplyCensus`, `censusReason`, and
+`pipelineDiagnosis.firstFailing`. If the verdict is honest rubric failure, the
+human decision is to update the rubric or change lead source; refill does not
+mutate those automatically.
+
+## Results
+
+Terminal reasons are:
+
+- `complete`
+- `capped_by_scheduler`
+- `loaded_awaiting_scheduler`
+- `lanes_exhausted`
+- `blocked`
+- `no_refillable_campaigns`
+- `not_an_evergreen_workspace`
+
+Report campaign names and sender names first, ids second. Include the terminal
+reason or resume handle, lane source, lane chain, chosen label with token
+secondary, plan revision, journal path, blocked continuation packets, and
+firstFailing checklist when present.
+
+Real-run journals live under `~/.sellable/refill/runs` by default and append an
+index line. Dry runs include the dry marker and do not create run records.

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

@@ -1,6 +1,6 @@
 ---
 name: refill-sends-v2-workflow
-description: Internal read-only workflow for refill sends v2 dry-run planning.
+description: Internal execution workflow for refill sends v2 fenced runs.
 visibility: internal
 allowed-tools:
   - mcp__sellable__refill_sends_v2
@@ -15,113 +15,124 @@ allowed-tools:
 
 # Refill Sends V2 Workflow
 
-This internal workflow is the read-only, dry-run, zero mutations plan surface
-for refill sends v2. The workflow has three gates: bootstrap, plan, and report.
-It covers product-managed evergreen workspaces, dashboard evergreen workspaces,
-and non-evergreen active campaign workspaces without creating new campaigns.
+This internal workflow mirrors the run-record gates enforced by
+`refill_sends_v2`: bootstrap, plan, execute, verify, and report. Dry runs stay
+read-only. Real runs execute only packet-named bounded work under a fenced run
+lease and return terminal, blocked, or in-progress results.
 
 Runtime flow asset: after loading this prompt, load
 `get_subskill_asset({ subskillName: "refill-sends-v2-workflow", assetPath: "core/flow.v1.json" })`
 through MCP, continue chunks until `hasMore:false`, parse the JSON, and verify
-`workflow:"refill-sends-v2-workflow"` with a `v1` version before any planner
-call. If the asset cannot load or parse, stop with
+`workflow:"refill-sends-v2-workflow"` with a `v1` version before driving the
+loop. If the asset cannot load or parse, stop with
 `blocked:refill_sends_v2_workflow_asset_unavailable`; do not emulate it from
 local files or memory.
 
-## G0 Bootstrap Facts
+## G0 Bootstrap
 
-Resolve the request-scoped `workspaceId` using read-only auth and workspace
-tools. Scheduled or autonomous runs must not rely on implicit workspace state.
-Call `refill_sends_v2({ workspaceId })` first to receive the command contract,
-then call `get_refill_plan_v2({ workspaceId, intent:"auto" })` for the dry-run
+Resolve request-scoped `workspaceId` using read-only auth and workspace tools.
+Scheduled or autonomous runs must not rely on implicit workspace state.
+
+Start or resume the execution loop:
+
+```text
+refill_sends_v2({ workspaceId, intent:"auto", senderIds?, approvalMode?, runId?, fence? })
+```
+
+Use `dryRun:true` only when the user asked for read-only inspection. A dry run
+writes a journal only. A real run creates or resumes a run record, refreshes
+paid-credit trust only when packet facts require it, and returns a resume handle
+when the current invocation must pause.
+
+## G1 Plan
+
+The loop reads `get_refill_plan_v2` with runState fed back from the run record.
+It captures `planRevision`, `stateRevision`, and `targetShapeRevision`, then
+validates the packet before dispatch. Packet coherence is required: fingerprint
+shape, tool input completeness, lane-chain membership, census-vs-rung
+consistency, and terminal/action exclusivity. An incoherent packet is replanned
+once, then blocked as `packet_incoherent`.
+
+The packet's `supplyCensus`, `censusReason`, and `pipelineDiagnosis` checklist
+are the reason for the next rung. Repair is replan-driven: the planner names
+the repair rung, such as re-run errored enrichment/message cells
+(`rerun_errored_cells`), approve generated messages that are ready for review
+(`approve_messages`), or start the paused campaign so ready rows can schedule
+(`start_campaign`). The loop bounds and refuses repair loops; it never invents
+a fix list.
+
+Use plain-language labels first and tokens second, for example "copy leads
+already found into the campaign table (`reconcile_source_copy`)".
+
+## G2 Execute
+
+The loop executes only the packet head action whose fingerprint was captured at
+G1. Stale packets are refused and replanned.
+
+Allowed packet-named work:
+
+1. start the paused campaign so ready rows can schedule (`start_campaign`) when
+   the campaign is in the pinned lane chain;
+2. approve generated messages that are ready for review (`approve_messages`);
+3. enrich the next batch of unenriched rows (`enrich_more`);
+4. copy leads already found into the campaign table (`reconcile_source_copy`);
+5. re-run errored enrichment/message cells (`rerun_errored_cells`);
+6. find more leads via this campaign's original source
+   (`add_leads_same_source`) for mechanical same-source continuations;
+7. wait for the scheduler to pick up ready rows (`wait_for_scheduler`).
+
+Never create campaigns, switch providers, lower thresholds, write scheduler
+fields, send/archive/delete, or mutate brief/filter/message/sequence/sender
+config inside refill.
+
+Sales Nav and Prospeo continuations that need human source work are blocked as
+scoped handoffs:
+
+```text
+$sellable:create-campaign [campaignId]
+```
+
+The handoff scope is source work only: same saved-search identity, import mode
+`add` into the same source list, no new campaign, no provider-family switch, and
+no brief/rubric/message/sequence/sender changes without a separate approval
 packet.
 
-Optional inputs:
-
-- `senderIds`: exact sender scope when the user named senders.
-- `intent`: defaults to `auto`. Use explicit `evergreen`, `plain`, or `active`
-  only for a what-if comparison.
-- `runState`: synthetic v1 lane memory for what-if dry runs. Use it only when
-  the user intentionally wants a hypothetical cursor, pin, cooldown state, or
-  laneChain replay.
-- `journal:false`: skip the local journal only when explicitly requested.
-- `journalNote`: append operator context to the dry-run terminal section.
-
-## G1 Lane Sources
-
-The planner reports the lane source for every selected lane:
-
-1. `managed_waterfall`: product-managed evergreen waterfall lanes.
-2. `dashboard_evergreen`: dashboard-visible evergreen campaigns that are not in
-   the managed waterfall snapshot.
-3. `active_campaign`: regular active campaigns ranked into a deterministic
-   laneChain for non-evergreen refill planning.
-
-If no lane family has refillable campaigns, report `no_refillable_campaigns`.
-If the user lacks membership on a requested workspace, report the structured
-`workspace_access` blocker with the workspace id and journal path.
-
-## G2 Refill Ladder
-
-The planner chooses from this locked rung order:
-
-1. `start_campaign`: a paused selected lane has scheduler-ready supply but must
-   be live before the scheduler can pick it up.
-2. `approve_messages`: generated rows are ready for a bounded approval step.
-3. `wait_for_active_work`: enrichment, generation, import, or preparation is
-   already active, so the next honest action is to wait for that work to finish.
-4. `enrich_more`: exact-set enrichment can close the current ready gap.
-5. `reconcile_source_copy`: same-source rows exist and can be copied without
-   changing source family or source fingerprint.
-6. `add_leads_same_source`: the same source path can add bounded new supply.
-7. `paid_lane_fallback`: paid InMail is blocked or below threshold, so the same
-   waterfall can fall back to an existing supported lane.
-8. `next_campaign`: the current lane is exhausted, cooling down, pinned away, or
-   unsafe, and the next surviving campaign lane should be inspected.
-9. `wait_for_scheduler`: ready or projected supply covers the target, and only
-   scheduler pickup remains.
-10. `done`: the sender or lane is complete for the selected target window, a
-    scheduler cap makes additional preparation unnecessary, or
-    `no_refillable_campaigns` is the honest terminal.
-
-Forward-only lane rule: a lane can move to a later rung or a later surviving
-campaign, but the dry-run packet must not jump backward to invent work that the
-facts do not support. Pinned-campaign rule: a pinned campaign stays selected
-until the planner proves a blocker, cooldown, exhaustion, or safer next lane.
-Capped-is-complete rule: when scheduler capacity is lower than the requested
-target and ready/projected coverage satisfies that cap, report `done` with the
-cap reason. Honest-itinerary rule: show what was checked, what was skipped, and
-why; never hide uncertainty behind a confident source recommendation.
-
-Guardrails: no campaign creation, no provider-family switch, no threshold
-lowering, no scheduler writes, no launch/send/archive/delete, no
-brief/filter/message/sequence/sender mutation, no message preparation, no
-message approval, no paid InMail credit refresh, no source mutation, no row
-queueing, and no campaign status change.
-
-## Journal
-
-`get_refill_plan_v2` writes a local dry-run journal unless `journal:false` is
-passed. Read the returned `journalPath` from the tool result and include it in
-the report. The journal contains bootstrap, plan, and terminal sections plus an
-index line under the run journal directory. If the tool returns
-`journalPath:null` with a `journalWriteFailed` warning, report the warning and
-continue with the dry-run packet; do not retry by writing local files yourself.
-
-## Report Contract
-
-Completion means packet reviewed and journal written. Merely calling
-`get_refill_plan_v2` is not completion proof.
-
-Report these facts:
-
-- workspace id and selected sender scope;
-- plan revision and state revision;
-- selected campaign, lane source, and laneChain per sender;
-- chosen rung and dry-run action queue;
-- itinerary, skipped lanes, blockers, cooldowns, and warnings;
-- `no_refillable_campaigns` terminals and `workspace_access` blockers;
-- journal path;
-- side effects proof, which must show all false values.
-
-Stop after the report. This workflow never executes the action queue.
+## G3 Verify
+
+Verification is whole-row and bounded. The loop records planned -> did ->
+outcome, then verifies before replanning.
+
+- Own active prep jobs are reattached by `requestSource` and `requestHash`; do
+  not re-dispatch prep while the job is active.
+- Foreign prep jobs are waited out or blocked as `foreign_prep_active`; their
+  outcomes are not adopted.
+- Active enrichment/import work is handled by bounded packet rereads.
+- The conversion verdict after the first prep batch is journaled from packet
+  facts. The plan gate withholds a second unproven prep batch when
+  `censusReason` is `conversion_blocked`.
+- Honest rubric failure means a human updates the rubric or changes lead source.
+- Capped scheduler capacity is complete.
+
+Scheduler wait is cross-invocation. If the tool returns `in_progress` with
+sweep guidance, re-invoke `refill_sends_v2` with `{runId, fence}`. The scheduler
+budget is cumulative at the run level. Zero pickup after a confirmed sweep is
+debugged from `pipelineDiagnosis`; it is not waited out forever.
+
+## G4 Report
+
+Completion proof is the run record at `g4_terminal` with a named doneReason and
+journal evidence showing planned -> did -> outcome plus a terminal block and
+index line. A plan packet alone is not completion proof.
+
+Terminal reasons are `complete`, `capped_by_scheduler`,
+`loaded_awaiting_scheduler`, `lanes_exhausted`, `blocked`,
+`no_refillable_campaigns`, and `not_an_evergreen_workspace`.
+
+`loaded_awaiting_scheduler` remains the run-record token, but report copy must
+include remaining-ready count, exact expected pickup time, and the resume
+handle. Do not render bare "loaded, awaiting scheduler" as a final answer.
+
+Report campaign names and sender names first, ids second. Include lane source,
+lane chain, chosen label with token secondary, plan revision, terminal reason or
+resume handle, journal path, blocked continuation packets, and firstFailing
+checklist when present.