@sellable/mcp 0.1.745 → 0.1.747

package/dist/tools/refill-executors.d.ts

@@ -214,6 +214,8 @@ export type SchedulerChangedCounts = {
     }>;
 };
 export declare function normalizeSchedulerChangedCounts(value: unknown): SchedulerChangedCounts | null;
+export declare function setSweepSettlePollDelayMsForTests(ms: number): void;
+export declare function resetSweepSettlePollDelayMsForTests(): void;
 export declare function schedulerEnvelopeIsTerminal(schedulerStatus: string, receipt?: Record<string, unknown> | null): boolean;
 export declare function normalizeSchedulerPrimitiveResult(value: unknown, expected?: {
     expectedTargets: SchedulerExpectedTargetInput[];

package/dist/tools/refill-executors.js

@@ -294,6 +294,34 @@ function hasTerminalSchedulerReceipt(receipt) {
     const status = receipt ? stringValue(receipt.status) : null;
     return Boolean(status && SCHEDULER_TERMINAL_RECEIPT_STATUSES.has(status));
 }
+// fix(112ap): poll ONLY a genuinely in-flight attach. `!terminal` is the wrong
+// test — it is also true for `backoff` and `failed`, and re-polling those would
+// both waste the budget and misrepresent a refused dispatch as a pending one.
+// In-flight means an attaching envelope (accepted|attached) that has NOT yet
+// yielded a terminal receipt, matching the 112ao-2b contract exactly.
+function schedulerDispatchIsStillRunning(value) {
+    const response = recordValue(value);
+    if (!response)
+        return false;
+    const status = stringValue(response.status) ?? "";
+    if (!SCHEDULER_ATTACHING_ENVELOPE_STATUSES.has(status))
+        return false;
+    return !hasTerminalSchedulerReceipt(recordValue(response.receipt));
+}
+// fix(112ap): bounded self-settle for a dispatched sweep. 4 x 8s = 32s, just past
+// the scheduler's own ~28s observed pass duration and its 30s retryAfterMs hint,
+// while staying well inside the coordinator's per-call budget.
+const SWEEP_SETTLE_POLL_ATTEMPTS = 4;
+const SWEEP_SETTLE_POLL_DEFAULT_DELAY_MS = 8_000;
+// Injectable so pins can exercise the settle loop without real wall-clock waits.
+// Production never calls the setter; the default is what ships.
+let sweepSettlePollDelayMs = SWEEP_SETTLE_POLL_DEFAULT_DELAY_MS;
+export function setSweepSettlePollDelayMsForTests(ms) {
+    sweepSettlePollDelayMs = ms;
+}
+export function resetSweepSettlePollDelayMsForTests() {
+    sweepSettlePollDelayMs = SWEEP_SETTLE_POLL_DEFAULT_DELAY_MS;
+}
 export function schedulerEnvelopeIsTerminal(schedulerStatus, receipt = null) {
     if (SCHEDULER_TERMINAL_ENVELOPE_STATUSES.has(schedulerStatus))
         return true;
@@ -3052,7 +3080,7 @@ export async function executeOneYoloPrimitive(action, workspaceId) {
                     },
                 };
             }
-            const result = await runSchedulerSweep({
+            let result = await runSchedulerSweep({
                 workspaceId,
                 action: "run",
                 targetDate,
@@ -3062,6 +3090,56 @@ export async function executeOneYoloPrimitive(action, workspaceId) {
                 expectedTargetsHash,
                 maxPlacements,
             });
+            // fix(112ap): settle our OWN dispatch before returning.
+            //
+            // The route holds a sweep for SCHEDULER_RUN_RESPONSE_BUDGET_MS (1s,
+            // route.ts:20) and then returns `attached` with the real pass still running
+            // in the background. We used to return that immediately, so the coordinator
+            // replanned; concurrent approve/prepare churned readyCounts, which churns
+            // stateRevision, which is hashed into actionKey/requestKey — so the NEXT
+            // iteration minted a BRAND NEW key and polled a run that had never been
+            // dispatched. scopeMatches was correctly false, and it dispatched again.
+            //
+            // Dotwork 2026-07-29 receipts: 12 DISTINCT run_scheduler_sweep keys, each
+            // dispatched exactly once, every one returning exact_action_complete with
+            // `lanesTouched: []`, coverage frozen at {sent:0, scheduled:0, ready:20}.
+            // approve_messages/prepare_messages in the same runs DID report lanesTouched.
+            // Meanwhile the scheduler itself was healthy — its own on-demand receipt
+            // placed 12 ready / 12 considered / 12 scheduled with zero skips, zero
+            // defers, zero prefilters. The sweeps simply never became scheduler runs.
+            //
+            // The key we just dispatched is in scope RIGHT HERE, so poll it here instead
+            // of trying to remember it across a replan. That matters: per-fence runState
+            // does NOT survive next_exact_target (it reset 112e's cohort guard, 112aj's
+            // counter and 112an's stall bound), so a cross-fence memory would have needed
+            // the WORKSPACE_ATTEMPT_LEDGER_KEYS allowlist. Polling in-scope needs none of
+            // that. Bounded so a slow pass still degrades to the existing in-flight
+            // handling rather than holding the tool call open.
+            for (let attempt = 0; attempt < SWEEP_SETTLE_POLL_ATTEMPTS &&
+                schedulerDispatchIsStillRunning(result); attempt += 1) {
+                await sleep(sweepSettlePollDelayMs);
+                const settled = await runSchedulerSweep({
+                    workspaceId,
+                    action: "status",
+                    targetDate,
+                    requestKey,
+                    targetShapeRevision,
+                    expectedTargetsHash,
+                    maxPlacements,
+                });
+                // Adopt the polled response ONLY when it actually settled. A status
+                // probe returns a DIFFERENT shape ({scopeMatches, running}) than a
+                // dispatch envelope ({status, receipt}); overwriting unconditionally
+                // destroyed the in-flight envelope and with it
+                // matching_scheduler_active / bounded_reread_wait / retryAfterMs, which
+                // is the handling the coordinator relies on when a run is still going.
+                // Keep the dispatch envelope until a terminal receipt exists.
+                const settledRecord = recordValue(settled);
+                if (settledRecord &&
+                    hasTerminalSchedulerReceipt(recordValue(settledRecord.receipt))) {
+                    result = settled;
+                }
+            }
             return {
                 status: "executed_and_reread",
                 result: normalizeSchedulerPrimitiveResult(result, {

package/dist/tools/refill-sends.d.ts

@@ -649,6 +649,9 @@ export declare function refillSendsCommand(input?: RefillSendsCommandInput): {
         subskillName: string;
         assetPath: string;
         expectedVersion: string;
+        minimumVersion: string;
+        compatibleMajor: string;
+        versionPolicy: string;
     };
     yolo: boolean;
     executionMode: RefillSendsExecutionMode;
@@ -656,6 +659,19 @@ export declare function refillSendsCommand(input?: RefillSendsCommandInput): {
     workspaceResolution: string;
     intent: RefillSendsIntent;
 };
+export declare const REFILL_FLOW_MINIMUM_VERSION = "v1.8";
+export declare const REFILL_FLOW_COMPATIBLE_MAJOR = "v1";
+/**
+ * Whether an observed flow-asset version satisfies the consumer's contract.
+ *
+ * Compatible when the major matches and the minor is >= the minimum. An
+ * unparseable or absent version stays a mismatch: this widens the accepted
+ * range, it never weakens the requirement that a version be verified at all.
+ */
+export declare function isCompatibleRefillFlowVersion(actualVersion: unknown, bounds?: {
+    minimumVersion?: string;
+    compatibleMajor?: string;
+}): boolean;
 type WorkspaceExactTarget = {
     campaignId: string;
     tableId: string;
@@ -809,6 +825,9 @@ export declare function executeRefillSendsCommand(input?: RefillSendsCommandInpu
         subskillName: string;
         assetPath: string;
         expectedVersion: string;
+        minimumVersion: string;
+        compatibleMajor: string;
+        versionPolicy: string;
     };
     yolo: boolean;
     executionMode: RefillSendsExecutionMode;
@@ -912,6 +931,9 @@ export declare function executeRefillSendsCommand(input?: RefillSendsCommandInpu
         subskillName: string;
         assetPath: string;
         expectedVersion: string;
+        minimumVersion: string;
+        compatibleMajor: string;
+        versionPolicy: string;
     };
     yolo: boolean;
     executionMode: RefillSendsExecutionMode;
@@ -1020,6 +1042,9 @@ export declare function executeRefillSendsCommand(input?: RefillSendsCommandInpu
         subskillName: string;
         assetPath: string;
         expectedVersion: string;
+        minimumVersion: string;
+        compatibleMajor: string;
+        versionPolicy: string;
     };
     yolo: boolean;
     executionMode: RefillSendsExecutionMode;
@@ -1182,6 +1207,9 @@ export declare function executeRefillSendsCommand(input?: RefillSendsCommandInpu
         subskillName: string;
         assetPath: string;
         expectedVersion: string;
+        minimumVersion: string;
+        compatibleMajor: string;
+        versionPolicy: string;
     };
     yolo: boolean;
     executionMode: RefillSendsExecutionMode;
@@ -1349,6 +1377,9 @@ export declare function executeRefillSendsCommand(input?: RefillSendsCommandInpu
         subskillName: string;
         assetPath: string;
         expectedVersion: string;
+        minimumVersion: string;
+        compatibleMajor: string;
+        versionPolicy: string;
     };
     yolo: boolean;
     executionMode: RefillSendsExecutionMode;
@@ -1465,6 +1496,9 @@ export declare function executeRefillSendsCommand(input?: RefillSendsCommandInpu
         subskillName: string;
         assetPath: string;
         expectedVersion: string;
+        minimumVersion: string;
+        compatibleMajor: string;
+        versionPolicy: string;
     };
     yolo: boolean;
     executionMode: RefillSendsExecutionMode;
@@ -1584,6 +1618,9 @@ export declare function executeRefillSendsCommand(input?: RefillSendsCommandInpu
         subskillName: string;
         assetPath: string;
         expectedVersion: string;
+        minimumVersion: string;
+        compatibleMajor: string;
+        versionPolicy: string;
     };
     yolo: boolean;
     executionMode: RefillSendsExecutionMode;
@@ -1702,6 +1739,9 @@ export declare function executeRefillSendsCommand(input?: RefillSendsCommandInpu
         subskillName: string;
         assetPath: string;
         expectedVersion: string;
+        minimumVersion: string;
+        compatibleMajor: string;
+        versionPolicy: string;
     };
     yolo: boolean;
     executionMode: RefillSendsExecutionMode;
@@ -1823,6 +1863,9 @@ export declare function executeRefillSendsCommand(input?: RefillSendsCommandInpu
         subskillName: string;
         assetPath: string;
         expectedVersion: string;
+        minimumVersion: string;
+        compatibleMajor: string;
+        versionPolicy: string;
     };
     yolo: boolean;
     executionMode: RefillSendsExecutionMode;
@@ -1985,6 +2028,9 @@ export declare function executeRefillSendsCommand(input?: RefillSendsCommandInpu
         subskillName: string;
         assetPath: string;
         expectedVersion: string;
+        minimumVersion: string;
+        compatibleMajor: string;
+        versionPolicy: string;
     };
     yolo: boolean;
     executionMode: RefillSendsExecutionMode;
@@ -2093,6 +2139,9 @@ export declare function executeRefillSendsCommand(input?: RefillSendsCommandInpu
         subskillName: string;
         assetPath: string;
         expectedVersion: string;
+        minimumVersion: string;
+        compatibleMajor: string;
+        versionPolicy: string;
     };
     yolo: boolean;
     executionMode: RefillSendsExecutionMode;
@@ -2259,6 +2308,9 @@ export declare function executeRefillSendsCommand(input?: RefillSendsCommandInpu
         subskillName: string;
         assetPath: string;
         expectedVersion: string;
+        minimumVersion: string;
+        compatibleMajor: string;
+        versionPolicy: string;
     };
     yolo: boolean;
     executionMode: RefillSendsExecutionMode;
@@ -2381,6 +2433,9 @@ export declare function executeRefillSendsCommand(input?: RefillSendsCommandInpu
         subskillName: string;
         assetPath: string;
         expectedVersion: string;
+        minimumVersion: string;
+        compatibleMajor: string;
+        versionPolicy: string;
     };
     yolo: boolean;
     executionMode: RefillSendsExecutionMode;
@@ -2516,6 +2571,9 @@ export declare function executeRefillSendsCommand(input?: RefillSendsCommandInpu
         subskillName: string;
         assetPath: string;
         expectedVersion: string;
+        minimumVersion: string;
+        compatibleMajor: string;
+        versionPolicy: string;
     };
     yolo: boolean;
     executionMode: RefillSendsExecutionMode;
@@ -2641,6 +2699,9 @@ export declare function executeRefillSendsCommand(input?: RefillSendsCommandInpu
         subskillName: string;
         assetPath: string;
         expectedVersion: string;
+        minimumVersion: string;
+        compatibleMajor: string;
+        versionPolicy: string;
     };
     yolo: boolean;
     executionMode: RefillSendsExecutionMode;
@@ -2765,6 +2826,9 @@ export declare function executeRefillSendsCommand(input?: RefillSendsCommandInpu
         subskillName: string;
         assetPath: string;
         expectedVersion: string;
+        minimumVersion: string;
+        compatibleMajor: string;
+        versionPolicy: string;
     };
     yolo: boolean;
     executionMode: RefillSendsExecutionMode;
@@ -2922,6 +2986,9 @@ export declare function executeRefillSendsCommand(input?: RefillSendsCommandInpu
         subskillName: string;
         assetPath: string;
         expectedVersion: string;
+        minimumVersion: string;
+        compatibleMajor: string;
+        versionPolicy: string;
     };
     yolo: boolean;
     executionMode: RefillSendsExecutionMode;
@@ -3042,6 +3109,9 @@ export declare function executeRefillSendsCommand(input?: RefillSendsCommandInpu
         subskillName: string;
         assetPath: string;
         expectedVersion: string;
+        minimumVersion: string;
+        compatibleMajor: string;
+        versionPolicy: string;
     };
     yolo: boolean;
     executionMode: RefillSendsExecutionMode;
@@ -3136,6 +3206,9 @@ export declare function executeRefillSendsCommand(input?: RefillSendsCommandInpu
         subskillName: string;
         assetPath: string;
         expectedVersion: string;
+        minimumVersion: string;
+        compatibleMajor: string;
+        versionPolicy: string;
     };
     yolo: boolean;
     executionMode: RefillSendsExecutionMode;
@@ -3226,6 +3299,9 @@ export declare function executeRefillSendsCommand(input?: RefillSendsCommandInpu
         subskillName: string;
         assetPath: string;
         expectedVersion: string;
+        minimumVersion: string;
+        compatibleMajor: string;
+        versionPolicy: string;
     };
     yolo: boolean;
     executionMode: RefillSendsExecutionMode;
@@ -3343,6 +3419,9 @@ export declare function executeRefillSendsCommand(input?: RefillSendsCommandInpu
         subskillName: string;
         assetPath: string;
         expectedVersion: string;
+        minimumVersion: string;
+        compatibleMajor: string;
+        versionPolicy: string;
     };
     yolo: boolean;
     executionMode: RefillSendsExecutionMode;
@@ -3572,6 +3651,9 @@ export declare function executeRefillSendsCommand(input?: RefillSendsCommandInpu
         subskillName: string;
         assetPath: string;
         expectedVersion: string;
+        minimumVersion: string;
+        compatibleMajor: string;
+        versionPolicy: string;
     };
     yolo: boolean;
     executionMode: RefillSendsExecutionMode;
@@ -3807,6 +3889,9 @@ export declare function executeRefillSendsCommand(input?: RefillSendsCommandInpu
         subskillName: string;
         assetPath: string;
         expectedVersion: string;
+        minimumVersion: string;
+        compatibleMajor: string;
+        versionPolicy: string;
     };
     yolo: boolean;
     executionMode: RefillSendsExecutionMode;
@@ -4040,6 +4125,9 @@ export declare function executeRefillSendsCommand(input?: RefillSendsCommandInpu
         subskillName: string;
         assetPath: string;
         expectedVersion: string;
+        minimumVersion: string;
+        compatibleMajor: string;
+        versionPolicy: string;
     };
     yolo: boolean;
     executionMode: RefillSendsExecutionMode;
@@ -4269,6 +4357,9 @@ export declare function executeRefillSendsCommand(input?: RefillSendsCommandInpu
         subskillName: string;
         assetPath: string;
         expectedVersion: string;
+        minimumVersion: string;
+        compatibleMajor: string;
+        versionPolicy: string;
     };
     yolo: boolean;
     executionMode: RefillSendsExecutionMode;
@@ -4503,6 +4594,9 @@ export declare function executeRefillSendsCommand(input?: RefillSendsCommandInpu
         subskillName: string;
         assetPath: string;
         expectedVersion: string;
+        minimumVersion: string;
+        compatibleMajor: string;
+        versionPolicy: string;
     };
     yolo: boolean;
     executionMode: RefillSendsExecutionMode;
@@ -4739,6 +4833,9 @@ export declare function executeRefillSendsCommand(input?: RefillSendsCommandInpu
         subskillName: string;
         assetPath: string;
         expectedVersion: string;
+        minimumVersion: string;
+        compatibleMajor: string;
+        versionPolicy: string;
     };
     yolo: boolean;
     executionMode: RefillSendsExecutionMode;
@@ -4974,6 +5071,9 @@ export declare function executeRefillSendsCommand(input?: RefillSendsCommandInpu
         subskillName: string;
         assetPath: string;
         expectedVersion: string;
+        minimumVersion: string;
+        compatibleMajor: string;
+        versionPolicy: string;
     };
     yolo: boolean;
     executionMode: RefillSendsExecutionMode;
@@ -5213,6 +5313,9 @@ export declare function executeRefillSendsCommand(input?: RefillSendsCommandInpu
         subskillName: string;
         assetPath: string;
         expectedVersion: string;
+        minimumVersion: string;
+        compatibleMajor: string;
+        versionPolicy: string;
     };
     yolo: boolean;
     executionMode: RefillSendsExecutionMode;
@@ -5445,6 +5548,9 @@ export declare function executeRefillSendsCommand(input?: RefillSendsCommandInpu
         subskillName: string;
         assetPath: string;
         expectedVersion: string;
+        minimumVersion: string;
+        compatibleMajor: string;
+        versionPolicy: string;
     };
     yolo: boolean;
     executionMode: RefillSendsExecutionMode;
@@ -5683,6 +5789,9 @@ export declare function executeRefillSendsCommand(input?: RefillSendsCommandInpu
         subskillName: string;
         assetPath: string;
         expectedVersion: string;
+        minimumVersion: string;
+        compatibleMajor: string;
+        versionPolicy: string;
     };
     yolo: boolean;
     executionMode: RefillSendsExecutionMode;
@@ -5919,6 +6028,9 @@ export declare function executeRefillSendsCommand(input?: RefillSendsCommandInpu
         subskillName: string;
         assetPath: string;
         expectedVersion: string;
+        minimumVersion: string;
+        compatibleMajor: string;
+        versionPolicy: string;
     };
     yolo: boolean;
     executionMode: RefillSendsExecutionMode;
@@ -6151,6 +6263,9 @@ export declare function executeRefillSendsCommand(input?: RefillSendsCommandInpu
         subskillName: string;
         assetPath: string;
         expectedVersion: string;
+        minimumVersion: string;
+        compatibleMajor: string;
+        versionPolicy: string;
     };
     yolo: boolean;
     executionMode: RefillSendsExecutionMode;
@@ -6388,6 +6503,9 @@ export declare function executeRefillSendsCommand(input?: RefillSendsCommandInpu
         subskillName: string;
         assetPath: string;
         expectedVersion: string;
+        minimumVersion: string;
+        compatibleMajor: string;
+        versionPolicy: string;
     };
     yolo: boolean;
     executionMode: RefillSendsExecutionMode;
@@ -6627,6 +6745,9 @@ export declare function executeRefillSendsCommand(input?: RefillSendsCommandInpu
         subskillName: string;
         assetPath: string;
         expectedVersion: string;
+        minimumVersion: string;
+        compatibleMajor: string;
+        versionPolicy: string;
     };
     yolo: boolean;
     executionMode: RefillSendsExecutionMode;
@@ -6864,6 +6985,9 @@ export declare function executeRefillSendsCommand(input?: RefillSendsCommandInpu
         subskillName: string;
         assetPath: string;
         expectedVersion: string;
+        minimumVersion: string;
+        compatibleMajor: string;
+        versionPolicy: string;
     };
     yolo: boolean;
     executionMode: RefillSendsExecutionMode;
@@ -7095,6 +7219,9 @@ export declare function executeRefillSendsCommand(input?: RefillSendsCommandInpu
         subskillName: string;
         assetPath: string;
         expectedVersion: string;
+        minimumVersion: string;
+        compatibleMajor: string;
+        versionPolicy: string;
     };
     yolo: boolean;
     executionMode: RefillSendsExecutionMode;
@@ -7332,6 +7459,9 @@ export declare function executeRefillSendsCommand(input?: RefillSendsCommandInpu
         subskillName: string;
         assetPath: string;
         expectedVersion: string;
+        minimumVersion: string;
+        compatibleMajor: string;
+        versionPolicy: string;
     };
     yolo: boolean;
     executionMode: RefillSendsExecutionMode;
@@ -7567,6 +7697,9 @@ export declare function executeRefillSendsCommand(input?: RefillSendsCommandInpu
         subskillName: string;
         assetPath: string;
         expectedVersion: string;
+        minimumVersion: string;
+        compatibleMajor: string;
+        versionPolicy: string;
     };
     yolo: boolean;
     executionMode: RefillSendsExecutionMode;
@@ -7798,6 +7931,9 @@ export declare function executeRefillSendsCommand(input?: RefillSendsCommandInpu
         subskillName: string;
         assetPath: string;
         expectedVersion: string;
+        minimumVersion: string;
+        compatibleMajor: string;
+        versionPolicy: string;
     };
     yolo: boolean;
     executionMode: RefillSendsExecutionMode;
@@ -8034,6 +8170,9 @@ export declare function executeRefillSendsCommand(input?: RefillSendsCommandInpu
         subskillName: string;
         assetPath: string;
         expectedVersion: string;
+        minimumVersion: string;
+        compatibleMajor: string;
+        versionPolicy: string;
     };
     yolo: boolean;
     executionMode: RefillSendsExecutionMode;
@@ -8272,6 +8411,9 @@ export declare function executeRefillSendsCommand(input?: RefillSendsCommandInpu
         subskillName: string;
         assetPath: string;
         expectedVersion: string;
+        minimumVersion: string;
+        compatibleMajor: string;
+        versionPolicy: string;
     };
     yolo: boolean;
     executionMode: RefillSendsExecutionMode;
@@ -8508,6 +8650,9 @@ export declare function executeRefillSendsCommand(input?: RefillSendsCommandInpu
         subskillName: string;
         assetPath: string;
         expectedVersion: string;
+        minimumVersion: string;
+        compatibleMajor: string;
+        versionPolicy: string;
     };
     yolo: boolean;
     executionMode: RefillSendsExecutionMode;
@@ -8775,6 +8920,9 @@ export declare function executeRefillSendsCommand(input?: RefillSendsCommandInpu
         subskillName: string;
         assetPath: string;
         expectedVersion: string;
+        minimumVersion: string;
+        compatibleMajor: string;
+        versionPolicy: string;
     };
     yolo: boolean;
     executionMode: RefillSendsExecutionMode;
@@ -9007,6 +9155,9 @@ export declare function executeRefillSendsCommand(input?: RefillSendsCommandInpu
         subskillName: string;
         assetPath: string;
         expectedVersion: string;
+        minimumVersion: string;
+        compatibleMajor: string;
+        versionPolicy: string;
     };
     yolo: boolean;
     executionMode: RefillSendsExecutionMode;
@@ -9245,6 +9396,9 @@ export declare function executeRefillSendsCommand(input?: RefillSendsCommandInpu
         subskillName: string;
         assetPath: string;
         expectedVersion: string;
+        minimumVersion: string;
+        compatibleMajor: string;
+        versionPolicy: string;
     };
     yolo: boolean;
     executionMode: RefillSendsExecutionMode;
@@ -9481,6 +9635,9 @@ export declare function executeRefillSendsCommand(input?: RefillSendsCommandInpu
         subskillName: string;
         assetPath: string;
         expectedVersion: string;
+        minimumVersion: string;
+        compatibleMajor: string;
+        versionPolicy: string;
     };
     yolo: boolean;
     executionMode: RefillSendsExecutionMode;
@@ -9713,6 +9870,9 @@ export declare function executeRefillSendsCommand(input?: RefillSendsCommandInpu
         subskillName: string;
         assetPath: string;
         expectedVersion: string;
+        minimumVersion: string;
+        compatibleMajor: string;
+        versionPolicy: string;
     };
     yolo: boolean;
     executionMode: RefillSendsExecutionMode;
@@ -9950,6 +10110,9 @@ export declare function executeRefillSendsCommand(input?: RefillSendsCommandInpu
         subskillName: string;
         assetPath: string;
         expectedVersion: string;
+        minimumVersion: string;
+        compatibleMajor: string;
+        versionPolicy: string;
     };
     yolo: boolean;
     executionMode: RefillSendsExecutionMode;
@@ -10189,6 +10352,9 @@ export declare function executeRefillSendsCommand(input?: RefillSendsCommandInpu
         subskillName: string;
         assetPath: string;
         expectedVersion: string;
+        minimumVersion: string;
+        compatibleMajor: string;
+        versionPolicy: string;
     };
     yolo: boolean;
     executionMode: RefillSendsExecutionMode;
@@ -10426,6 +10592,9 @@ export declare function executeRefillSendsCommand(input?: RefillSendsCommandInpu
         subskillName: string;
         assetPath: string;
         expectedVersion: string;
+        minimumVersion: string;
+        compatibleMajor: string;
+        versionPolicy: string;
     };
     yolo: boolean;
     executionMode: RefillSendsExecutionMode;
@@ -10705,6 +10874,9 @@ export declare function executeRefillSendsCommand(input?: RefillSendsCommandInpu
         subskillName: string;
         assetPath: string;
         expectedVersion: string;
+        minimumVersion: string;
+        compatibleMajor: string;
+        versionPolicy: string;
     };
     yolo: boolean;
     executionMode: RefillSendsExecutionMode;
@@ -10928,6 +11100,9 @@ export declare function executeRefillSendsCommand(input?: RefillSendsCommandInpu
         subskillName: string;
         assetPath: string;
         expectedVersion: string;
+        minimumVersion: string;
+        compatibleMajor: string;
+        versionPolicy: string;
     };
     yolo: boolean;
     executionMode: RefillSendsExecutionMode;
@@ -11186,6 +11361,9 @@ export declare function executeRefillSendsCommand(input?: RefillSendsCommandInpu
         subskillName: string;
         assetPath: string;
         expectedVersion: string;
+        minimumVersion: string;
+        compatibleMajor: string;
+        versionPolicy: string;
     };
     yolo: boolean;
     executionMode: RefillSendsExecutionMode;
@@ -11348,6 +11526,9 @@ export declare function executeRefillSendsCommand(input?: RefillSendsCommandInpu
         subskillName: string;
         assetPath: string;
         expectedVersion: string;
+        minimumVersion: string;
+        compatibleMajor: string;
+        versionPolicy: string;
     };
     yolo: boolean;
     executionMode: RefillSendsExecutionMode;
@@ -11516,6 +11697,9 @@ export declare function executeRefillSendsCommand(input?: RefillSendsCommandInpu
         subskillName: string;
         assetPath: string;
         expectedVersion: string;
+        minimumVersion: string;
+        compatibleMajor: string;
+        versionPolicy: string;
     };
     yolo: boolean;
     executionMode: RefillSendsExecutionMode;
@@ -11682,6 +11866,9 @@ export declare function executeRefillSendsCommand(input?: RefillSendsCommandInpu
         subskillName: string;
         assetPath: string;
         expectedVersion: string;
+        minimumVersion: string;
+        compatibleMajor: string;
+        versionPolicy: string;
     };
     yolo: boolean;
     executionMode: RefillSendsExecutionMode;
@@ -11844,6 +12031,9 @@ export declare function executeRefillSendsCommand(input?: RefillSendsCommandInpu
         subskillName: string;
         assetPath: string;
         expectedVersion: string;
+        minimumVersion: string;
+        compatibleMajor: string;
+        versionPolicy: string;
     };
     yolo: boolean;
     executionMode: RefillSendsExecutionMode;
@@ -12011,6 +12201,9 @@ export declare function executeRefillSendsCommand(input?: RefillSendsCommandInpu
         subskillName: string;
         assetPath: string;
         expectedVersion: string;
+        minimumVersion: string;
+        compatibleMajor: string;
+        versionPolicy: string;
     };
     yolo: boolean;
     executionMode: RefillSendsExecutionMode;
@@ -12180,6 +12373,9 @@ export declare function executeRefillSendsCommand(input?: RefillSendsCommandInpu
         subskillName: string;
         assetPath: string;
         expectedVersion: string;
+        minimumVersion: string;
+        compatibleMajor: string;
+        versionPolicy: string;
     };
     yolo: boolean;
     executionMode: RefillSendsExecutionMode;
@@ -12348,6 +12544,9 @@ export declare function executeRefillSendsCommand(input?: RefillSendsCommandInpu
         subskillName: string;
         assetPath: string;
         expectedVersion: string;
+        minimumVersion: string;
+        compatibleMajor: string;
+        versionPolicy: string;
     };
     yolo: boolean;
     executionMode: RefillSendsExecutionMode;
@@ -12456,6 +12655,9 @@ export declare function executeRefillSendsCommand(input?: RefillSendsCommandInpu
         subskillName: string;
         assetPath: string;
         expectedVersion: string;
+        minimumVersion: string;
+        compatibleMajor: string;
+        versionPolicy: string;
     };
     yolo: boolean;
     executionMode: RefillSendsExecutionMode;
@@ -12577,6 +12779,9 @@ export declare function executeRefillSendsCommand(input?: RefillSendsCommandInpu
         subskillName: string;
         assetPath: string;
         expectedVersion: string;
+        minimumVersion: string;
+        compatibleMajor: string;
+        versionPolicy: string;
     };
     yolo: boolean;
     executionMode: RefillSendsExecutionMode;
@@ -12785,6 +12990,9 @@ export declare function executeRefillSendsCommand(input?: RefillSendsCommandInpu
         subskillName: string;
         assetPath: string;
         expectedVersion: string;
+        minimumVersion: string;
+        compatibleMajor: string;
+        versionPolicy: string;
     };
     yolo: boolean;
     executionMode: RefillSendsExecutionMode;

package/dist/tools/refill-sends.js

@@ -423,6 +423,49 @@ export const refillSendsToolDefinitions = [
 export function refillSendsCommand(input = {}) {
     return buildRefillSendsCommand(normalizeRefillSendsInput(input));
 }
+// fix(112ao-4): the refill flow contract was matched by EXACT STRING across a
+// release boundary — the flow asset ships in the npm package (@sellable/mcp)
+// while the skill that verifies it is installed separately into
+// ~/.codex/plugins/cache. Exact equality makes EVERY contract change breaking:
+// bumping v1.8 -> v1.9 halted every customer-real run with
+// workflow_version_mismatch, and a full repo sweep could not have caught it
+// because the authoritative consumer is not in this repo.
+//
+// The version value itself is deliberately NOT changed here. What changes is
+// the comparison: consumers accept any same-major version at or above the
+// minimum, so additive flow changes ship without a coordinated skill release.
+// A breaking change still gets a major bump (v2), which correctly fails closed.
+export const REFILL_FLOW_MINIMUM_VERSION = "v1.8";
+export const REFILL_FLOW_COMPATIBLE_MAJOR = "v1";
+function parseFlowVersion(value) {
+    if (typeof value !== "string")
+        return null;
+    const match = /^v(\d+)\.(\d+)$/.exec(value.trim());
+    if (!match)
+        return null;
+    const major = Number(match[1]);
+    const minor = Number(match[2]);
+    return Number.isInteger(major) && Number.isInteger(minor)
+        ? { major, minor }
+        : null;
+}
+/**
+ * Whether an observed flow-asset version satisfies the consumer's contract.
+ *
+ * Compatible when the major matches and the minor is >= the minimum. An
+ * unparseable or absent version stays a mismatch: this widens the accepted
+ * range, it never weakens the requirement that a version be verified at all.
+ */
+export function isCompatibleRefillFlowVersion(actualVersion, bounds = {}) {
+    const minimum = parseFlowVersion(bounds.minimumVersion ?? REFILL_FLOW_MINIMUM_VERSION);
+    const actual = parseFlowVersion(actualVersion);
+    if (!minimum || !actual)
+        return false;
+    const expectedMajor = parseFlowVersion(`${bounds.compatibleMajor ?? REFILL_FLOW_COMPATIBLE_MAJOR}.0`);
+    if (!expectedMajor || actual.major !== expectedMajor.major)
+        return false;
+    return actual.minor >= minimum.minor;
+}
 function buildRefillSendsCommand(input) {
     const workspaceId = normalizeExplicitWorkspaceId(input.workspaceId);
     const senders = normalizeStrings(input.senders);
@@ -454,7 +497,13 @@ function buildRefillSendsCommand(input) {
         workflowAsset: {
             subskillName: "refill-sends-workflow",
             assetPath: "core/flow.v1.json",
-            expectedVersion: "v1.8",
+            // fix(112ao-4): `expectedVersion` is retained verbatim so consumers
+            // already installed against the exact-match contract keep working. New
+            // consumers read the range fields instead. See REFILL_FLOW_VERSION_RANGE.
+            expectedVersion: REFILL_FLOW_MINIMUM_VERSION,
+            minimumVersion: REFILL_FLOW_MINIMUM_VERSION,
+            compatibleMajor: REFILL_FLOW_COMPATIBLE_MAJOR,
+            versionPolicy: "compatible_range",
         },
         yolo,
         executionMode,
@@ -502,7 +551,7 @@ function buildRefillSendsCommand(input) {
         },
         firstOperationalSteps: [
             'Load get_subskill_prompt({ subskillName: "refill-sends-workflow" }) before any product operation.',
-            'Load get_subskill_asset({ subskillName: "refill-sends-workflow", assetPath: "core/flow.v1.json" }) before any product operation; continue chunks until hasMore is false, parse JSON, and require exactly workflow:"refill-sends-workflow" and version:"v1.8". Report the verified version before D1. Any other or unverified version is workflow_version_mismatch and must stop before get_refill_target_plan or mutation.',
+            'Load get_subskill_asset({ subskillName: "refill-sends-workflow", assetPath: "core/flow.v1.json" }) before any product operation; continue chunks until hasMore is false, parse JSON, and require workflow:"refill-sends-workflow" plus a COMPATIBLE version: same major (v1) with minor at or above the v1.8 minimum, so v1.8, v1.9, and v1.10 all pass while v2.x does not. Report the verified version before D1. A missing, unparseable, wrong-major, or below-minimum version is workflow_version_mismatch and must stop before get_refill_target_plan or mutation. Do not compare the version by exact string equality.',
             "A skill cannot create or invoke /goal by itself. If this refill 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.",
             `Call get_refill_target_plan({ intent: "${intent}"${workspaceId ? `, workspaceId: "${workspaceId}"` : ""}${input.campaignId ? `, campaignId: "${input.campaignId}"` : ""}${input.tableId ? `, tableId: "${input.tableId}"` : ""}${senderIds.length > 0 ? `, senderIds: ${JSON.stringify(senderIds)}` : ""}${senderNames.length > 0
                 ? `, senderNames: ${JSON.stringify(senderNames)}`

package/package.json

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

package/skills/refill-sends/SKILL.md

@@ -74,10 +74,14 @@ get_subskill_prompt({ subskillName: "refill-sends-workflow" })
 get_subskill_asset({ subskillName: "refill-sends-workflow", assetPath: "core/flow.v1.json" })
 ```
 
-Continue chunks until `hasMore:false`; require
-exactly `workflow:"refill-sends-workflow"` and `version:"v1.8"`, then report
-that verified version before D1. Any other or unverified version is
-`workflow_version_mismatch`: stop before `get_refill_target_plan` or mutation.
+Continue chunks until `hasMore:false`; require `workflow:"refill-sends-workflow"`
+and a COMPATIBLE version: same major (`v1`) and minor at or above the minimum
+`v1.8` — so `v1.8`, `v1.9`, `v1.10` all pass and `v2.x` does not. Report the
+verified version before D1. A missing, unparseable, wrong-major, or
+below-minimum version is `workflow_version_mismatch`: stop before
+`get_refill_target_plan` or mutation. Do NOT require exact string equality: the
+flow asset ships in the npm package while this skill is installed separately,
+so an exact pin makes every additive contract change a breaking one.
 Route intent is immutable:
 workspace-wide `--yolo` uses `intent:"auto"` from first plan through terminal.
 

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

@@ -24,15 +24,20 @@ In `--yolo`, the coordinator may
 perform every fresh planner-ranked safe transition among existing campaigns,
 lanes, and source families. It may not create a new campaign.
 
-The host must load the entire asset and verify exactly `version:"v1.8"` before
-D1. It reports that verified version explicitly. A different or unverified
-version is `workflow_version_mismatch` and stops before planner or mutation.
+The host must load the entire asset and verify a COMPATIBLE version before D1:
+same major (`v1`) and minor at or above the minimum `v1.8`, so `v1.9` and
+`v1.10` are accepted and `v2.x` is not. It reports that verified version
+explicitly. A missing, unparseable, wrong-major, or below-minimum version is
+`workflow_version_mismatch` and stops before planner or mutation. Exact-string
+matching is forbidden here: the asset ships in the npm package while the
+verifying skill installs separately, so an exact pin makes every additive
+change breaking.
 
 ## Closed-loop executor
 
 ```mermaid
 flowchart TD
-    A["Receive exact workspace, sender/action selectors, and date envelope"] --> ASSET["Verify complete flow.v1.json, workflow refill-sends-workflow, exact version v1.8"]
+    A["Receive exact workspace, sender/action selectors, and date envelope"] --> ASSET["Verify complete flow.v1.json, workflow refill-sends-workflow, compatible version v1 >= v1.8"]
     ASSET --> D1["Call get_refill_target_plan read-only with immutable route intent"]
     D1 --> RENDER["Render sender/campaign waterfall, coverage ledger, bounded side effects, forbidden actions, and stop condition"]
     RENDER --> D2["Call refill_sends with workspaceCoordinator true and displayed revision/action pins"]

package/skills/refill-sends-workflow/core/flow.v1.json

@@ -18,6 +18,9 @@
       "validation": {
         "workflow": "refill-sends-workflow",
         "exactVersion": "v1.8",
+        "versionPolicy": "compatible_range",
+        "minimumVersion": "v1.8",
+        "compatibleMajor": "v1",
         "requiredTopLevelKeys": [
           "states",
           "gateOrder",