@autonome-research/thread-phase 3.2.2 → 3.4.0

package/dist/patterns/bounded-fanout-of.js

@@ -19,7 +19,7 @@
  * form is more direct. When you have one item, just call the adapter
  * directly.
  *
- * @internal — exported via thread-phase/patterns
+ * Stable surface — exported via thread-phase/patterns; covered by semver.
  */
 /**
  * Run an adapter over N items with capped concurrency. Returns results in
@@ -27,8 +27,6 @@
  * error results (finishReason: 'error') and the batch completes. In
  * `fail-fast` (default), the first failure cancels in-flight runs and
  * the function rejects with an Error wrapping the failed item.
- *
- * @internal
  */
 export async function boundedFanoutOf(opts) {
     const items = opts.items;
@@ -40,11 +38,17 @@ export async function boundedFanoutOf(opts) {
     const inFlight = new Set();
     let failed = null;
     let cursor = 0;
-    const abortAllInFlight = () => {
-        for (const entry of inFlight) {
+    const abortAllInFlight = async () => {
+        const snapshot = [...inFlight];
+        for (const entry of snapshot) {
             entry.controller.abort();
             entry.run.abort('boundedFanoutOf fail-fast');
         }
+        // Wait for every aborted run's `result` to settle so adapter-side cleanup
+        // (timers, sockets, subprocesses) finishes before the fanout returns.
+        // We allSettled because the runs may reject as `aborted` and we don't
+        // want to mask the original failure with the abort-induced one.
+        await Promise.allSettled(snapshot.map((e) => e.result));
     };
     const worker = async () => {
         while (true) {
@@ -66,7 +70,7 @@ export async function boundedFanoutOf(opts) {
                 eventBus: opts.eventBus,
                 traceId: opts.traceId,
             });
-            const entry = { controller: itemController, run };
+            const entry = { controller: itemController, run, result: run.result };
             inFlight.add(entry);
             // The adapter's events iterable is intentionally NOT consumed here.
             // The event bus is the multi-subscriber seam; double-iteration would
@@ -84,7 +88,7 @@ export async function boundedFanoutOf(opts) {
                     if (!failed) {
                         failed = { index: i, result };
                         opts.onItemError?.(item, i, result);
-                        abortAllInFlight();
+                        await abortAllInFlight();
                     }
                     return;
                 }
@@ -120,7 +124,6 @@ export async function boundedFanoutOf(opts) {
     }
     return results;
 }
-/** @internal */
 export class BoundedFanoutOfError extends Error {
     itemIndex;
     result;

package/dist/patterns/bounded-fanout-of.js.map

@@ -1 +1 @@
-{"version":3,"file":"bounded-fanout-of.js","sourceRoot":"","sources":["../../src/patterns/bounded-fanout-of.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"bounded-fanout-of.js","sourceRoot":"","sources":["../../src/patterns/bounded-fanout-of.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AA8BH;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CACnC,IAA4C;IAE5C,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC;IACzB,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,CAAC;IAElC,MAAM,WAAW,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,WAAW,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC;IAC1E,MAAM,IAAI,GAAwB,IAAI,CAAC,IAAI,IAAI,WAAW,CAAC;IAC3D,MAAM,OAAO,GAAsC,IAAI,KAAK,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;IAe3E,MAAM,QAAQ,GAAG,IAAI,GAAG,EAAY,CAAC;IAGrC,IAAI,MAAM,GAAwB,IAAI,CAAC;IACvC,IAAI,MAAM,GAAG,CAAC,CAAC;IAEf,MAAM,gBAAgB,GAAG,KAAK,IAAmB,EAAE;QACjD,MAAM,QAAQ,GAAG,CAAC,GAAG,QAAQ,CAAC,CAAC;QAC/B,KAAK,MAAM,KAAK,IAAI,QAAQ,EAAE,CAAC;YAC7B,KAAK,CAAC,UAAU,CAAC,KAAK,EAAE,CAAC;YACzB,KAAK,CAAC,GAAG,CAAC,KAAK,CAAC,2BAA2B,CAAC,CAAC;QAC/C,CAAC;QACD,0EAA0E;QAC1E,sEAAsE;QACtE,sEAAsE;QACtE,gEAAgE;QAChE,MAAM,OAAO,CAAC,UAAU,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC;IAC1D,CAAC,CAAC;IAEF,MAAM,MAAM,GAAG,KAAK,IAAmB,EAAE;QACvC,OAAO,IAAI,EAAE,CAAC;YACZ,IAAI,MAAM;gBAAE,OAAO;YACnB,IAAI,IAAI,CAAC,MAAM,EAAE,OAAO;gBAAE,OAAO;YACjC,MAAM,CAAC,GAAG,MAAM,EAAE,CAAC;YACnB,IAAI,CAAC,IAAI,KAAK,CAAC,MAAM;gBAAE,OAAO;YAC9B,MAAM,IAAI,GAAG,KAAK,CAAC,CAAC,CAAE,CAAC;YAEvB,MAAM,cAAc,GAAG,IAAI,eAAe,EAAE,CAAC;YAC7C,MAAM,eAAe,GAAgB,IAAI,CAAC,MAAM;gBAC9C,CAAC,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,MAAM,EAAE,cAAc,CAAC,MAAM,CAAC,CAAC;gBACvD,CAAC,CAAC,cAAc,CAAC,MAAM,CAAC;YAE1B,MAAM,MAAM,GAAG,IAAI,CAAC,WAAW,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC;YACzC,MAAM,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,MAAM,EAAE;gBACvC,MAAM,EAAE,eAAe;gBACvB,QAAQ,EAAE,IAAI,CAAC,QAAQ;gBACvB,OAAO,EAAE,IAAI,CAAC,OAAO;aACtB,CAAC,CAAC;YAEH,MAAM,KAAK,GAAa,EAAE,UAAU,EAAE,cAAc,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,CAAC;YAChF,QAAQ,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;YAEpB,oEAAoE;YACpE,qEAAqE;YACrE,uEAAuE;YACvE,0BAA0B;YAC1B,IAAI,MAAsB,CAAC;YAC3B,IAAI,CAAC;gBACH,MAAM,GAAG,MAAM,GAAG,CAAC,MAAM,CAAC;YAC5B,CAAC;oBAAS,CAAC;gBACT,QAAQ,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;YACzB,CAAC;YAED,IAAI,MAAM,CAAC,YAAY,KAAK,OAAO,EAAE,CAAC;gBACpC,IAAI,IAAI,KAAK,WAAW,EAAE,CAAC;oBACzB,IAAI,CAAC,MAAM,EAAE,CAAC;wBACZ,MAAM,GAAG,EAAE,KAAK,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC;wBAC9B,IAAI,CAAC,WAAW,EAAE,CAAC,IAAI,EAAE,CAAC,EAAE,MAAM,CAAC,CAAC;wBACpC,MAAM,gBAAgB,EAAE,CAAC;oBAC3B,CAAC;oBACD,OAAO;gBACT,CAAC;gBACD,iCAAiC;gBACjC,OAAO,CAAC,CAAC,CAAC,GAAG,MAAM,CAAC;gBACpB,IAAI,CAAC,SAAS,EAAE,CAAC,IAAI,EAAE,CAAC,EAAE,MAAM,CAAC,CAAC;gBAClC,SAAS;YACX,CAAC;YAED,OAAO,CAAC,CAAC,CAAC,GAAG,MAAM,CAAC;YACpB,IAAI,CAAC,SAAS,EAAE,CAAC,IAAI,EAAE,CAAC,EAAE,MAAM,CAAC,CAAC;QACpC,CAAC;IACH,CAAC,CAAC;IAEF,MAAM,OAAO,GAAoB,EAAE,CAAC;IACpC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,WAAW,EAAE,CAAC,EAAE;QAAE,OAAO,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC;IAC7D,MAAM,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;IAE3B,IAAI,MAAM,EAAE,CAAC;QACX,MAAM,CAAC,GAAiB,MAAM,CAAC;QAC/B,MAAM,IAAI,oBAAoB,CAAC,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC;IACpD,CAAC;IAED,0EAA0E;IAC1E,yEAAyE;IACzE,yEAAyE;IACzE,uEAAuE;IACvE,wEAAwE;IACxE,qCAAqC;IACrC,IAAI,IAAI,CAAC,MAAM,EAAE,OAAO,EAAE,CAAC;QACzB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;YACtC,IAAI,OAAO,CAAC,CAAC,CAAC,KAAK,SAAS,EAAE,CAAC;gBAC7B,OAAO,CAAC,CAAC,CAAC,GAAG,sBAAsB,EAAE,CAAC;YACxC,CAAC;QACH,CAAC;IACH,CAAC;IAED,OAAO,OAA2B,CAAC;AACrC,CAAC;AAED,MAAM,OAAO,oBAAqB,SAAQ,KAAK;IAEpC;IACA;IAFT,YACS,SAAiB,EACjB,MAAsB;QAE7B,KAAK,CAAC,kCAAkC,SAAS,KAAK,MAAM,CAAC,YAAY,EAAE,CAAC,CAAC;QAHtE,cAAS,GAAT,SAAS,CAAQ;QACjB,WAAM,GAAN,MAAM,CAAgB;QAG7B,IAAI,CAAC,IAAI,GAAG,sBAAsB,CAAC;IACrC,CAAC;CACF;AAED,SAAS,sBAAsB;IAC7B,OAAO;QACL,IAAI,EAAE,EAAE;QACR,YAAY,EAAE,SAAS;QACvB,KAAK,EAAE,EAAE,YAAY,EAAE,CAAC,EAAE,gBAAgB,EAAE,CAAC,EAAE,WAAW,EAAE,CAAC,EAAE;QAC/D,iBAAiB,EAAE,EAAE;KACtB,CAAC;AACJ,CAAC"}

package/dist/patterns/index.d.ts

@@ -1,6 +1,28 @@
 /**
  * Reusable phase patterns. Each pattern is a small, opinionated helper that
  * captures a recurring shape — not a black-box framework. Compose freely.
+ *
+ * # API convention
+ *
+ * Patterns in this barrel use ONE of two signature shapes — pick the one
+ * that matches what the pattern returns:
+ *
+ *   - Pattern factories: (name: string, options) => Phase<TCtx>
+ *       parallelPhases, intentGate, match, whileCondition, subPipeline.
+ *       Use when you return a Phase. The `name` survives into telemetry
+ *       and event metadata.
+ *
+ *   - Eager runners: (options) => Promise<T>
+ *       boundedFanout, boundedFanoutOf.
+ *       Use when the function executes immediately and returns a Promise.
+ *       No `name` because there's no Phase identity to attach.
+ *
+ * `withRetry` is a Phase WRAPPER — (innerPhase, options) => Phase<TCtx> —
+ * a minor variant of the factory shape that takes the wrapped phase first.
+ *
+ * Registration helpers (oneShot/schedule/hook in ../helpers) form a third
+ * category with their own convention. See AGENTS.md "API conventions —
+ * three factory shapes" for the full rationale.
  */
 export { parallelPhases } from './parallel-phases.js';
 export { boundedFanout, type BoundedFanOutOptions, type ItemDoneEvent, type ItemErrorEvent, type FanOutResult, } from './bounded-fanout.js';

package/dist/patterns/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/patterns/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAEtD,OAAO,EACL,aAAa,EACb,KAAK,oBAAoB,EACzB,KAAK,aAAa,EAClB,KAAK,cAAc,EACnB,KAAK,YAAY,GAClB,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EAAE,eAAe,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAC;AAC/E,YAAY,EAAE,sBAAsB,EAAE,mBAAmB,EAAE,MAAM,wBAAwB,CAAC;AAE1F,OAAO,EACL,UAAU,EACV,KAAK,oBAAoB,EACzB,KAAK,cAAc,EACnB,KAAK,iBAAiB,GACvB,MAAM,kBAAkB,CAAC;AAE1B,OAAO,EACL,cAAc,EACd,KAAK,qBAAqB,GAC3B,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EACL,KAAK,EACL,KAAK,YAAY,GAClB,MAAM,YAAY,CAAC;AAEpB,OAAO,EACL,SAAS,EACT,KAAK,gBAAgB,GACtB,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EACL,WAAW,EACX,aAAa,EACb,cAAc,EACd,KAAK,kBAAkB,EACvB,KAAK,iBAAiB,GACvB,MAAM,mBAAmB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/patterns/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAEtD,OAAO,EACL,aAAa,EACb,KAAK,oBAAoB,EACzB,KAAK,aAAa,EAClB,KAAK,cAAc,EACnB,KAAK,YAAY,GAClB,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EAAE,eAAe,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAC;AAC/E,YAAY,EAAE,sBAAsB,EAAE,mBAAmB,EAAE,MAAM,wBAAwB,CAAC;AAE1F,OAAO,EACL,UAAU,EACV,KAAK,oBAAoB,EACzB,KAAK,cAAc,EACnB,KAAK,iBAAiB,GACvB,MAAM,kBAAkB,CAAC;AAE1B,OAAO,EACL,cAAc,EACd,KAAK,qBAAqB,GAC3B,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EACL,KAAK,EACL,KAAK,YAAY,GAClB,MAAM,YAAY,CAAC;AAEpB,OAAO,EACL,SAAS,EACT,KAAK,gBAAgB,GACtB,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EACL,WAAW,EACX,aAAa,EACb,cAAc,EACd,KAAK,kBAAkB,EACvB,KAAK,iBAAiB,GACvB,MAAM,mBAAmB,CAAC"}

package/dist/patterns/index.js

@@ -1,6 +1,28 @@
 /**
  * Reusable phase patterns. Each pattern is a small, opinionated helper that
  * captures a recurring shape — not a black-box framework. Compose freely.
+ *
+ * # API convention
+ *
+ * Patterns in this barrel use ONE of two signature shapes — pick the one
+ * that matches what the pattern returns:
+ *
+ *   - Pattern factories: (name: string, options) => Phase<TCtx>
+ *       parallelPhases, intentGate, match, whileCondition, subPipeline.
+ *       Use when you return a Phase. The `name` survives into telemetry
+ *       and event metadata.
+ *
+ *   - Eager runners: (options) => Promise<T>
+ *       boundedFanout, boundedFanoutOf.
+ *       Use when the function executes immediately and returns a Promise.
+ *       No `name` because there's no Phase identity to attach.
+ *
+ * `withRetry` is a Phase WRAPPER — (innerPhase, options) => Phase<TCtx> —
+ * a minor variant of the factory shape that takes the wrapped phase first.
+ *
+ * Registration helpers (oneShot/schedule/hook in ../helpers) form a third
+ * category with their own convention. See AGENTS.md "API conventions —
+ * three factory shapes" for the full rationale.
  */
 export { parallelPhases } from './parallel-phases.js';
 export { boundedFanout, } from './bounded-fanout.js';

package/dist/patterns/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/patterns/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAEtD,OAAO,EACL,aAAa,GAKd,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EAAE,eAAe,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAC;AAG/E,OAAO,EACL,UAAU,GAIX,MAAM,kBAAkB,CAAC;AAE1B,OAAO,EACL,cAAc,GAEf,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EACL,KAAK,GAEN,MAAM,YAAY,CAAC;AAEpB,OAAO,EACL,SAAS,GAEV,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EACL,WAAW,EACX,aAAa,EACb,cAAc,GAGf,MAAM,mBAAmB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/patterns/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAEtD,OAAO,EACL,aAAa,GAKd,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EAAE,eAAe,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAC;AAG/E,OAAO,EACL,UAAU,GAIX,MAAM,kBAAkB,CAAC;AAE1B,OAAO,EACL,cAAc,GAEf,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EACL,KAAK,GAEN,MAAM,YAAY,CAAC;AAEpB,OAAO,EACL,SAAS,GAEV,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EACL,WAAW,EACX,aAAa,EACb,cAAc,GAGf,MAAM,mBAAmB,CAAC"}

package/dist/patterns/parallel-phases.d.ts

@@ -12,8 +12,13 @@
  *     same field, last-write-wins. Keep branches' ctx writes disjoint.
  *   - Events from all branches interleave into the composite phase's
  *     output stream in arrival order.
- *   - If a sub-phase throws, the composite re-throws (after letting other
- *     branches finish what they're doing — no in-flight cancellation).
+ *   - If a sub-phase throws, sibling branches are cooperatively cancelled
+ *     via an internal `AbortSignal` composed onto each branch's `ctx.signal`.
+ *     Siblings still need to OBSERVE their signal to short-circuit awaits —
+ *     between yields they bail immediately via the queue's error flag.
+ *   - If the outer `ctx.signal` aborts, every branch's composed signal
+ *     aborts too. The composite then re-throws the first error encountered
+ *     (or the outer abort).
  *   - If a sub-phase sets `ctx.stop`, sibling branches still run to
  *     completion. The orchestrator's stop check fires AFTER the composite
  *     phase returns, halting subsequent top-level phases.

package/dist/patterns/parallel-phases.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"parallel-phases.d.ts","sourceRoot":"","sources":["../../src/patterns/parallel-phases.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAE7E,wBAAgB,cAAc,CAC5B,IAAI,SAAS,mBAAmB,EAChC,MAAM,GAAG,aAAa,EAEtB,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,aAAa,CAAC,KAAK,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,GACzC,KAAK,CAAC,IAAI,EAAE,MAAM,CAAC,CAkDrB"}
+{"version":3,"file":"parallel-phases.d.ts","sourceRoot":"","sources":["../../src/patterns/parallel-phases.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAE7E,wBAAgB,cAAc,CAC5B,IAAI,SAAS,mBAAmB,EAChC,MAAM,GAAG,aAAa,EAEtB,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,aAAa,CAAC,KAAK,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,GACzC,KAAK,CAAC,IAAI,EAAE,MAAM,CAAC,CAiFrB"}

package/dist/patterns/parallel-phases.js

@@ -12,8 +12,13 @@
  *     same field, last-write-wins. Keep branches' ctx writes disjoint.
  *   - Events from all branches interleave into the composite phase's
  *     output stream in arrival order.
- *   - If a sub-phase throws, the composite re-throws (after letting other
- *     branches finish what they're doing — no in-flight cancellation).
+ *   - If a sub-phase throws, sibling branches are cooperatively cancelled
+ *     via an internal `AbortSignal` composed onto each branch's `ctx.signal`.
+ *     Siblings still need to OBSERVE their signal to short-circuit awaits —
+ *     between yields they bail immediately via the queue's error flag.
+ *   - If the outer `ctx.signal` aborts, every branch's composed signal
+ *     aborts too. The composite then re-throws the first error encountered
+ *     (or the outer abort).
  *   - If a sub-phase sets `ctx.stop`, sibling branches still run to
  *     completion. The orchestrator's stop check fires AFTER the composite
  *     phase returns, halting subsequent top-level phases.
@@ -28,6 +33,22 @@ export function parallelPhases(phaseName, phases) {
         async *run(ctx) {
             if (phases.length === 0)
                 return;
+            // Internal controller fans cancellation across branches. When one
+            // branch throws (or the outer ctx.signal aborts), every other branch
+            // sees its composed ctx.signal flip to aborted — they can observe it
+            // in their inner await loops to bail cooperatively.
+            const internal = new AbortController();
+            const outerSignal = ctx.signal;
+            const composedSignal = outerSignal
+                ? AbortSignal.any([outerSignal, internal.signal])
+                : internal.signal;
+            const onOuterAbort = () => internal.abort(outerSignal.reason);
+            if (outerSignal && !outerSignal.aborted) {
+                outerSignal.addEventListener('abort', onOuterAbort, { once: true });
+            }
+            else if (outerSignal?.aborted) {
+                internal.abort(outerSignal.reason);
+            }
             // Producer/consumer: each sub-phase pushes events into a shared queue;
             // the composite generator drains the queue and yields downstream.
             const queue = [];
@@ -41,17 +62,26 @@ export function parallelPhases(phaseName, phases) {
             let errored = null;
             let running = phases.length;
             const drain = async (phase) => {
+                // Each branch sees the composed signal, not the outer's directly,
+                // so sibling errors propagate as cancellation through ctx.signal.
+                const branchCtx = withSignal(ctx, composedSignal);
                 try {
-                    for await (const ev of phase.run(ctx)) {
+                    for await (const ev of phase.run(branchCtx)) {
                         queue.push(ev);
                         wake();
-                        if (errored)
-                            return;
+                        // Do not short-circuit on `errored` — that would close the
+                        // branch's generator before it had a chance to observe
+                        // composedSignal cooperatively. Branches that check c.signal
+                        // bail themselves; branches that don't run to completion (the
+                        // documented cooperative-cancellation contract).
                     }
                 }
                 catch (err) {
-                    if (!errored)
+                    if (!errored) {
                         errored = err;
+                        // First error fires the internal abort so siblings cancel too.
+                        internal.abort(err);
+                    }
                 }
                 finally {
                     running--;
@@ -59,19 +89,43 @@ export function parallelPhases(phaseName, phases) {
                 }
             };
             const allDone = Promise.all(phases.map(drain));
-            while (running > 0 || queue.length > 0) {
-                if (errored && queue.length === 0)
-                    break;
-                if (queue.length === 0) {
-                    await Promise.race([wait(), allDone]);
-                    continue;
+            try {
+                while (running > 0 || queue.length > 0) {
+                    if (queue.length === 0) {
+                        await Promise.race([wait(), allDone]);
+                        continue;
+                    }
+                    yield queue.shift();
                 }
-                yield queue.shift();
+                await allDone;
+                if (errored)
+                    throw errored;
+            }
+            finally {
+                if (outerSignal)
+                    outerSignal.removeEventListener('abort', onOuterAbort);
             }
-            await allDone;
-            if (errored)
-                throw errored;
         },
     };
 }
+/**
+ * Build a per-branch ctx view whose `signal` is the composed signal.
+ * Other fields share the parent ctx (last-write-wins semantics preserved).
+ */
+function withSignal(ctx, signal) {
+    // A Proxy keeps writes to ctx visible across all branches (the documented
+    // last-write-wins model) while masking `signal` to the composed value.
+    return new Proxy(ctx, {
+        get(target, prop, receiver) {
+            if (prop === 'signal')
+                return signal;
+            return Reflect.get(target, prop, receiver);
+        },
+        set(target, prop, value, receiver) {
+            if (prop === 'signal')
+                return true; // ignore writes to branch-local signal
+            return Reflect.set(target, prop, value, receiver);
+        },
+    });
+}
 //# sourceMappingURL=parallel-phases.js.map

package/dist/patterns/parallel-phases.js.map

@@ -1 +1 @@
-{"version":3,"file":"parallel-phases.js","sourceRoot":"","sources":["../../src/patterns/parallel-phases.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAIH,MAAM,UAAU,cAAc,CAI5B,SAAiB,EACjB,MAA0C;IAE1C,OAAO;QACL,IAAI,EAAE,SAAS;QACf,KAAK,CAAC,CAAC,GAAG,CAAC,GAAG;YACZ,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC;gBAAE,OAAO;YAEhC,uEAAuE;YACvE,kEAAkE;YAClE,MAAM,KAAK,GAAa,EAAE,CAAC;YAC3B,IAAI,aAAa,GAAwB,IAAI,CAAC;YAC9C,MAAM,IAAI,GAAG,GAAG,EAAE;gBAChB,MAAM,EAAE,GAAG,aAAa,CAAC;gBACzB,aAAa,GAAG,IAAI,CAAC;gBACrB,EAAE,EAAE,EAAE,CAAC;YACT,CAAC,CAAC;YACF,MAAM,IAAI,GAAG,GAAG,EAAE,CAAC,IAAI,OAAO,CAAO,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,aAAa,GAAG,CAAC,CAAC,CAAC,CAAC;YAEjE,IAAI,OAAO,GAAY,IAAI,CAAC;YAC5B,IAAI,OAAO,GAAG,MAAM,CAAC,MAAM,CAAC;YAE5B,MAAM,KAAK,GAAG,KAAK,EAAE,KAA0B,EAAiB,EAAE;gBAChE,IAAI,CAAC;oBACH,IAAI,KAAK,EAAE,MAAM,EAAE,IAAI,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC;wBACtC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;wBACf,IAAI,EAAE,CAAC;wBACP,IAAI,OAAO;4BAAE,OAAO;oBACtB,CAAC;gBACH,CAAC;gBAAC,OAAO,GAAG,EAAE,CAAC;oBACb,IAAI,CAAC,OAAO;wBAAE,OAAO,GAAG,GAAG,CAAC;gBAC9B,CAAC;wBAAS,CAAC;oBACT,OAAO,EAAE,CAAC;oBACV,IAAI,EAAE,CAAC;gBACT,CAAC;YACH,CAAC,CAAC;YAEF,MAAM,OAAO,GAAG,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC;YAE/C,OAAO,OAAO,GAAG,CAAC,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;gBACvC,IAAI,OAAO,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;oBAAE,MAAM;gBACzC,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;oBACvB,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,OAAO,CAAC,CAAC,CAAC;oBACtC,SAAS;gBACX,CAAC;gBACD,MAAM,KAAK,CAAC,KAAK,EAAG,CAAC;YACvB,CAAC;YAED,MAAM,OAAO,CAAC;YACd,IAAI,OAAO;gBAAE,MAAM,OAAO,CAAC;QAC7B,CAAC;KACF,CAAC;AACJ,CAAC"}
+{"version":3,"file":"parallel-phases.js","sourceRoot":"","sources":["../../src/patterns/parallel-phases.ts"],"names":[],"mappings":"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"}

package/dist/patterns/sub-pipeline.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sub-pipeline.d.ts","sourceRoot":"","sources":["../../src/patterns/sub-pipeline.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAGH,OAAO,KAAK,EACV,mBAAmB,EACnB,KAAK,EAEN,MAAM,aAAa,CAAC;AAGrB;;;;;GAKG;AACH,MAAM,MAAM,iBAAiB,CAAC,SAAS,SAAS,mBAAmB,IAC/D;IAAE,MAAM,EAAE,aAAa,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC,CAAC;IAAC,GAAG,EAAE,SAAS,CAAA;CAAE,GAC3D,CAAC,MAAM;IAAE,MAAM,EAAE,aAAa,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC,CAAC;IAAC,GAAG,EAAE,SAAS,CAAA;CAAE,GAAG,SAAS,CAAC,CAAC;AAEpF,MAAM,WAAW,kBAAkB,CACjC,SAAS,SAAS,mBAAmB,EACrC,SAAS,SAAS,mBAAmB;IAErC,6DAA6D;IAC7D,QAAQ,EAAE,iBAAiB,CAAC,SAAS,CAAC,CAAC;IACvC;;;;OAIG;IACH,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE,SAAS,KAAK,SAAS,CAAC;IAC3C;;;OAGG;IACH,SAAS,CAAC,EAAE,CAAC,KAAK,EAAE,SAAS,EAAE,KAAK,EAAE,SAAS,KAAK,IAAI,CAAC;CAC1D;AAED,6DAA6D;AAC7D,wBAAgB,WAAW,CACzB,SAAS,SAAS,mBAAmB,EACrC,SAAS,SAAS,mBAAmB,EAErC,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,kBAAkB,CAAC,SAAS,EAAE,SAAS,CAAC,GAChD,KAAK,CAAC,SAAS,CAAC,CA8BlB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,aAAa,CAC3B,SAAS,SAAS,mBAAmB,EACrC,SAAS,SAAS,mBAAmB,GAAG,mBAAmB,EAE3D,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE;IAAE,MAAM,EAAE,aAAa,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC,CAAC;IAAC,GAAG,EAAE,SAAS,CAAA;CAAE,EACnE,OAAO,CAAC,EAAE,IAAI,CAAC,kBAAkB,CAAC,SAAS,EAAE,SAAS,CAAC,EAAE,UAAU,CAAC,GACnE,KAAK,CAAC,SAAS,CAAC,CAKlB;AAED;;;;GAIG;AACH,wBAAsB,cAAc,CAClC,SAAS,SAAS,mBAAmB,EAErC,MAAM,EAAE,iBAAiB,CAAC,SAAS,CAAC,EACpC,OAAO,GAAE;IACP,wEAAwE;IACxE,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,2EAA2E;IAC3E,GAAG,CAAC,EAAE,SAAS,CAAC;CACZ,GACL,OAAO,CAAC;IAAE,GAAG,EAAE,SAAS,CAAC;IAAC,OAAO,EAAE;QAAE,MAAM,EAAE,WAAW,GAAG,SAAS,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE,CAAA;CAAE,CAAC,CA4BhH"}
+{"version":3,"file":"sub-pipeline.d.ts","sourceRoot":"","sources":["../../src/patterns/sub-pipeline.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAGH,OAAO,KAAK,EACV,mBAAmB,EACnB,KAAK,EAEN,MAAM,aAAa,CAAC;AAGrB;;;;;GAKG;AACH,MAAM,MAAM,iBAAiB,CAAC,SAAS,SAAS,mBAAmB,IAC/D;IAAE,MAAM,EAAE,aAAa,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC,CAAC;IAAC,GAAG,EAAE,SAAS,CAAA;CAAE,GAC3D,CAAC,MAAM;IAAE,MAAM,EAAE,aAAa,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC,CAAC;IAAC,GAAG,EAAE,SAAS,CAAA;CAAE,GAAG,SAAS,CAAC,CAAC;AAEpF,MAAM,WAAW,kBAAkB,CACjC,SAAS,SAAS,mBAAmB,EACrC,SAAS,SAAS,mBAAmB;IAErC,6DAA6D;IAC7D,QAAQ,EAAE,iBAAiB,CAAC,SAAS,CAAC,CAAC;IACvC;;;;OAIG;IACH,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE,SAAS,KAAK,SAAS,CAAC;IAC3C;;;OAGG;IACH,SAAS,CAAC,EAAE,CAAC,KAAK,EAAE,SAAS,EAAE,KAAK,EAAE,SAAS,KAAK,IAAI,CAAC;CAC1D;AAED,6DAA6D;AAC7D,wBAAgB,WAAW,CACzB,SAAS,SAAS,mBAAmB,EACrC,SAAS,SAAS,mBAAmB,EAErC,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,kBAAkB,CAAC,SAAS,EAAE,SAAS,CAAC,GAChD,KAAK,CAAC,SAAS,CAAC,CA+BlB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,aAAa,CAC3B,SAAS,SAAS,mBAAmB,EACrC,SAAS,SAAS,mBAAmB,GAAG,mBAAmB,EAE3D,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE;IAAE,MAAM,EAAE,aAAa,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC,CAAC;IAAC,GAAG,EAAE,SAAS,CAAA;CAAE,EACnE,OAAO,CAAC,EAAE,IAAI,CAAC,kBAAkB,CAAC,SAAS,EAAE,SAAS,CAAC,EAAE,UAAU,CAAC,GACnE,KAAK,CAAC,SAAS,CAAC,CAKlB;AAED;;;;GAIG;AACH,wBAAsB,cAAc,CAClC,SAAS,SAAS,mBAAmB,EAErC,MAAM,EAAE,iBAAiB,CAAC,SAAS,CAAC,EACpC,OAAO,GAAE;IACP,wEAAwE;IACxE,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,2EAA2E;IAC3E,GAAG,CAAC,EAAE,SAAS,CAAC;CACZ,GACL,OAAO,CAAC;IAAE,GAAG,EAAE,SAAS,CAAC;IAAC,OAAO,EAAE;QAAE,MAAM,EAAE,WAAW,GAAG,SAAS,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE,CAAA;CAAE,CAAC,CA6BhH"}

package/dist/patterns/sub-pipeline.js

@@ -33,10 +33,14 @@ export function subPipeline(name, options) {
             const inner = options.mapInput
                 ? options.mapInput(outer)
                 : source.ctx;
-            // Isolate the inner pipeline's cache; propagate the outer's signal.
+            // Isolate the inner pipeline's cache so writes can't bleed across
+            // nesting levels. Signal propagation is via runPipeline's options —
+            // the orchestrator assigns ctx.signal canonically, which avoids the
+            // pre-set-then-overwritten footgun at arbitrary depth.
             inner.cache = new PipelineCache();
-            inner.signal = outer.signal;
-            yield* runPipeline(source.phases, inner);
+            yield* runPipeline(source.phases, inner, {
+                signal: outer.signal,
+            });
             options.mapOutput?.(outer, inner);
         },
     };
@@ -70,11 +74,11 @@ export async function runSubPipeline(source, options = {}) {
     }
     const inner = options.ctx ?? resolved.ctx;
     inner.cache = new PipelineCache();
-    if (options.signal)
-        inner.signal = options.signal;
     let eventCount = 0;
     let stopReason;
-    for await (const event of runPipeline(resolved.phases, inner)) {
+    for await (const event of runPipeline(resolved.phases, inner, {
+        signal: options.signal,
+    })) {
         eventCount++;
         if (event.type === 'done') {
             stopReason = event.reason;

package/dist/patterns/sub-pipeline.js.map

@@ -1 +1 @@
-{"version":3,"file":"sub-pipeline.js","sourceRoot":"","sources":["../../src/patterns/sub-pipeline.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAMjD,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AA+B5C,6DAA6D;AAC7D,MAAM,UAAU,WAAW,CAIzB,IAAY,EACZ,OAAiD;IAEjD,OAAO;QACL,IAAI;QACJ,KAAK,CAAC,CAAC,GAAG,CAAC,KAAK;YACd,MAAM,MAAM,GACV,OAAO,OAAO,CAAC,QAAQ,KAAK,UAAU;gBACpC,CAAC,CAAC,OAAO,CAAC,QAAQ,EAAE;gBACpB,CAAC,CAAC,OAAO,CAAC,QAAQ,CAAC;YACvB,IAAI,CAAC,MAAM,EAAE,CAAC;gBACZ,MAAM,IAAI,KAAK,CACb,gBAAgB,IAAI,yCAAyC,CAC9D,CAAC;YACJ,CAAC;YAED,MAAM,KAAK,GAAG,OAAO,CAAC,QAAQ;gBAC5B,CAAC,CAAC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAC;gBACzB,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC;YAEf,oEAAoE;YACnE,KAAkC,CAAC,KAAK,GAAG,IAAI,aAAa,EAAE,CAAC;YAChE,KAAK,CAAC,MAAM,GAAG,KAAK,CAAC,MAAM,CAAC;YAE5B,KAAK,CAAC,CAAC,WAAW,CAAC,MAAM,CAAC,MAAM,EAAE,KAAK,CAGtC,CAAC;YAEF,OAAO,CAAC,SAAS,EAAE,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC;QACpC,CAAC;KACF,CAAC;AACJ,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,aAAa,CAI3B,IAAY,EACZ,MAAmE,EACnE,OAAoE;IAEpE,OAAO,WAAW,CAAuB,IAAI,EAAE;QAC7C,QAAQ,EAAE,MAAM;QAChB,GAAG,OAAO;KACX,CAAC,CAAC;AACL,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAGlC,MAAoC,EACpC,UAKI,EAAE;IAEN,MAAM,QAAQ,GACZ,OAAO,MAAM,KAAK,UAAU,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC;IACnD,IAAI,CAAC,QAAQ,EAAE,CAAC;QACd,MAAM,IAAI,KAAK,CAAC,sDAAsD,CAAC,CAAC;IAC1E,CAAC;IAED,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,IAAI,QAAQ,CAAC,GAAG,CAAC;IACzC,KAAkC,CAAC,KAAK,GAAG,IAAI,aAAa,EAAE,CAAC;IAChE,IAAI,OAAO,CAAC,MAAM;QAAE,KAAK,CAAC,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAElD,IAAI,UAAU,GAAG,CAAC,CAAC;IACnB,IAAI,UAA8B,CAAC;IAEnC,IAAI,KAAK,EAAE,MAAM,KAAK,IAAI,WAAW,CAAC,QAAQ,CAAC,MAAM,EAAE,KAAK,CAAC,EAAE,CAAC;QAC9D,UAAU,EAAE,CAAC;QACb,IAAI,KAAK,CAAC,IAAI,KAAK,MAAM,EAAE,CAAC;YAC1B,UAAU,GAAI,KAA6B,CAAC,MAAM,CAAC;QACrD,CAAC;IACH,CAAC;IAED,OAAO;QACL,GAAG,EAAE,KAAK;QACV,OAAO,EACL,UAAU,KAAK,SAAS;YACtB,CAAC,CAAC,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,UAAU,EAAE;YACvD,CAAC,CAAC,EAAE,MAAM,EAAE,WAAW,EAAE,UAAU,EAAE;KAC1C,CAAC;AACJ,CAAC"}
+{"version":3,"file":"sub-pipeline.js","sourceRoot":"","sources":["../../src/patterns/sub-pipeline.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAMjD,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AA+B5C,6DAA6D;AAC7D,MAAM,UAAU,WAAW,CAIzB,IAAY,EACZ,OAAiD;IAEjD,OAAO;QACL,IAAI;QACJ,KAAK,CAAC,CAAC,GAAG,CAAC,KAAK;YACd,MAAM,MAAM,GACV,OAAO,OAAO,CAAC,QAAQ,KAAK,UAAU;gBACpC,CAAC,CAAC,OAAO,CAAC,QAAQ,EAAE;gBACpB,CAAC,CAAC,OAAO,CAAC,QAAQ,CAAC;YACvB,IAAI,CAAC,MAAM,EAAE,CAAC;gBACZ,MAAM,IAAI,KAAK,CACb,gBAAgB,IAAI,yCAAyC,CAC9D,CAAC;YACJ,CAAC;YAED,MAAM,KAAK,GAAG,OAAO,CAAC,QAAQ;gBAC5B,CAAC,CAAC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAC;gBACzB,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC;YAEf,kEAAkE;YAClE,oEAAoE;YACpE,oEAAoE;YACpE,uDAAuD;YACtD,KAAkC,CAAC,KAAK,GAAG,IAAI,aAAa,EAAE,CAAC;YAEhE,KAAK,CAAC,CAAC,WAAW,CAAC,MAAM,CAAC,MAAM,EAAE,KAAK,EAAE;gBACvC,MAAM,EAAE,KAAK,CAAC,MAAM;aACrB,CAAwC,CAAC;YAE1C,OAAO,CAAC,SAAS,EAAE,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC;QACpC,CAAC;KACF,CAAC;AACJ,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,aAAa,CAI3B,IAAY,EACZ,MAAmE,EACnE,OAAoE;IAEpE,OAAO,WAAW,CAAuB,IAAI,EAAE;QAC7C,QAAQ,EAAE,MAAM;QAChB,GAAG,OAAO;KACX,CAAC,CAAC;AACL,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAGlC,MAAoC,EACpC,UAKI,EAAE;IAEN,MAAM,QAAQ,GACZ,OAAO,MAAM,KAAK,UAAU,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC;IACnD,IAAI,CAAC,QAAQ,EAAE,CAAC;QACd,MAAM,IAAI,KAAK,CAAC,sDAAsD,CAAC,CAAC;IAC1E,CAAC;IAED,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,IAAI,QAAQ,CAAC,GAAG,CAAC;IACzC,KAAkC,CAAC,KAAK,GAAG,IAAI,aAAa,EAAE,CAAC;IAEhE,IAAI,UAAU,GAAG,CAAC,CAAC;IACnB,IAAI,UAA8B,CAAC;IAEnC,IAAI,KAAK,EAAE,MAAM,KAAK,IAAI,WAAW,CAAC,QAAQ,CAAC,MAAM,EAAE,KAAK,EAAE;QAC5D,MAAM,EAAE,OAAO,CAAC,MAAM;KACvB,CAAC,EAAE,CAAC;QACH,UAAU,EAAE,CAAC;QACb,IAAI,KAAK,CAAC,IAAI,KAAK,MAAM,EAAE,CAAC;YAC1B,UAAU,GAAI,KAA6B,CAAC,MAAM,CAAC;QACrD,CAAC;IACH,CAAC;IAED,OAAO;QACL,GAAG,EAAE,KAAK;QACV,OAAO,EACL,UAAU,KAAK,SAAS;YACtB,CAAC,CAAC,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,UAAU,EAAE;YACvD,CAAC,CAAC,EAAE,MAAM,EAAE,WAAW,EAAE,UAAU,EAAE;KAC1C,CAAC;AACJ,CAAC"}

package/dist/patterns/with-retry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"with-retry.d.ts","sourceRoot":"","sources":["../../src/patterns/with-retry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,KAAK,EAAiB,MAAM,aAAa,CAAC;AAE7E,MAAM,WAAW,gBAAgB,CAAC,IAAI,SAAS,mBAAmB;IAChE,8DAA8D;IAC9D,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,0EAA0E;IAC1E,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,mHAAmH;IACnH,SAAS,CAAC,EAAE,CAAC,GAAG,EAAE,IAAI,EAAE,KAAK,CAAC,EAAE,OAAO,KAAK,OAAO,CAAC;IACpD,+DAA+D;IAC/D,OAAO,CAAC,EAAE,CAAC,GAAG,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,OAAO,KAAK,IAAI,CAAC;IAChE,sFAAsF;IACtF,UAAU,CAAC,EAAE,CAAC,GAAG,EAAE,IAAI,KAAK,IAAI,CAAC;CAClC;AAID,wBAAgB,SAAS,CAAC,IAAI,SAAS,mBAAmB,EACxD,KAAK,EAAE,KAAK,CAAC,IAAI,CAAC,EAClB,OAAO,GAAE,gBAAgB,CAAC,IAAI,CAAM,GACnC,KAAK,CAAC,IAAI,CAAC,CAwDb"}
+{"version":3,"file":"with-retry.d.ts","sourceRoot":"","sources":["../../src/patterns/with-retry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,KAAK,EAAiB,MAAM,aAAa,CAAC;AAG7E,MAAM,WAAW,gBAAgB,CAAC,IAAI,SAAS,mBAAmB;IAChE,8DAA8D;IAC9D,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,0EAA0E;IAC1E,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,mHAAmH;IACnH,SAAS,CAAC,EAAE,CAAC,GAAG,EAAE,IAAI,EAAE,KAAK,CAAC,EAAE,OAAO,KAAK,OAAO,CAAC;IACpD,+DAA+D;IAC/D,OAAO,CAAC,EAAE,CAAC,GAAG,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,OAAO,KAAK,IAAI,CAAC;IAChE,sFAAsF;IACtF,UAAU,CAAC,EAAE,CAAC,GAAG,EAAE,IAAI,KAAK,IAAI,CAAC;CAClC;AAED,wBAAgB,SAAS,CAAC,IAAI,SAAS,mBAAmB,EACxD,KAAK,EAAE,KAAK,CAAC,IAAI,CAAC,EAClB,OAAO,GAAE,gBAAgB,CAAC,IAAI,CAAM,GACnC,KAAK,CAAC,IAAI,CAAC,CA2Db"}

package/dist/patterns/with-retry.js

@@ -20,7 +20,7 @@
  * Events emitted by the inner phase pass through unmodified. The wrapper
  * additionally emits `data` events with key `${phase.name}.attempt`.
  */
-const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+import { abortableSleep } from '../internal/sleep.js';
 export function withRetry(phase, options = {}) {
     const maxAttempts = options.maxAttempts ?? 3;
     const baseDelay = options.baseDelayMs ?? 1000;
@@ -65,7 +65,10 @@ export function withRetry(phase, options = {}) {
                 ctx.stop = stopBefore; // restore upstream stop, if any
                 options.resetState?.(ctx);
                 const delay = baseDelay * 2 ** (attempt - 1);
-                await sleep(delay);
+                // ctx.signal is wired by runPipeline; if the caller aborts during a
+                // backoff window, surface it immediately instead of waiting out the
+                // schedule. AbortError propagates up through runPipeline.
+                await abortableSleep(delay, ctx.signal);
             }
         },
     };

package/dist/patterns/with-retry.js.map

@@ -1 +1 @@
-{"version":3,"file":"with-retry.js","sourceRoot":"","sources":["../../src/patterns/with-retry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAiBH,MAAM,KAAK,GAAG,CAAC,EAAU,EAAE,EAAE,CAAC,IAAI,OAAO,CAAO,CAAC,CAAC,EAAE,EAAE,CAAC,UAAU,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC;AAE1E,MAAM,UAAU,SAAS,CACvB,KAAkB,EAClB,UAAkC,EAAE;IAEpC,MAAM,WAAW,GAAG,OAAO,CAAC,WAAW,IAAI,CAAC,CAAC;IAC7C,MAAM,SAAS,GAAG,OAAO,CAAC,WAAW,IAAI,IAAI,CAAC;IAC9C,MAAM,SAAS,GACb,OAAO,CAAC,SAAS,IAAI,CAAC,CAAC,GAAG,EAAE,KAAK,EAAE,EAAE,CAAC,KAAK,KAAK,SAAS,IAAI,GAAG,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC;IAEvF,OAAO;QACL,IAAI,EAAE,KAAK,CAAC,IAAI;QAChB,KAAK,CAAC,CAAC,GAAG,CAAC,GAAG;YACZ,KAAK,IAAI,OAAO,GAAG,CAAC,EAAE,OAAO,IAAI,WAAW,EAAE,OAAO,EAAE,EAAE,CAAC;gBACxD,MAAM;oBACJ,IAAI,EAAE,MAAM;oBACZ,GAAG,EAAE,GAAG,KAAK,CAAC,IAAI,UAAU;oBAC5B,KAAK,EAAE,EAAE,OAAO,EAAE,WAAW,EAAE;iBAChC,CAAC;gBAEF,MAAM,UAAU,GAAG,GAAG,CAAC,IAAI,CAAC;gBAC5B,IAAI,MAAM,GAAY,SAAS,CAAC;gBAEhC,IAAI,CAAC;oBACH,kEAAkE;oBAClE,mEAAmE;oBACnE,oBAAoB;oBACpB,GAAG,CAAC,IAAI,GAAG,SAAS,CAAC;oBACrB,KAAK,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;gBACxB,CAAC;gBAAC,OAAO,GAAG,EAAE,CAAC;oBACb,MAAM,GAAG,GAAG,CAAC;gBACf,CAAC;gBAED,MAAM,MAAM,GAAG,SAAS,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;gBAEtC,IAAI,CAAC,MAAM,EAAE,CAAC;oBACZ,iEAAiE;oBACjE,gEAAgE;oBAChE,mCAAmC;oBACnC,OAAO;gBACT,CAAC;gBAED,IAAI,OAAO,KAAK,WAAW,EAAE,CAAC;oBAC5B,+DAA+D;oBAC/D,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;wBACzB,MAAM,MAAM,CAAC;oBACf,CAAC;oBACD,wDAAwD;oBACxD,OAAO;gBACT,CAAC;gBAED,OAAO,CAAC,OAAO,EAAE,CAAC,GAAG,EAAE,OAAO,EAAE,MAAM,CAAC,CAAC;gBACxC,GAAG,CAAC,IAAI,GAAG,UAAU,CAAC,CAAC,gCAAgC;gBACvD,OAAO,CAAC,UAAU,EAAE,CAAC,GAAG,CAAC,CAAC;gBAE1B,MAAM,KAAK,GAAG,SAAS,GAAG,CAAC,IAAI,CAAC,OAAO,GAAG,CAAC,CAAC,CAAC;gBAC7C,MAAM,KAAK,CAAC,KAAK,CAAC,CAAC;YACrB,CAAC;QACH,CAAC;KACF,CAAC;AACJ,CAAC"}
+{"version":3,"file":"with-retry.js","sourceRoot":"","sources":["../../src/patterns/with-retry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAGH,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAetD,MAAM,UAAU,SAAS,CACvB,KAAkB,EAClB,UAAkC,EAAE;IAEpC,MAAM,WAAW,GAAG,OAAO,CAAC,WAAW,IAAI,CAAC,CAAC;IAC7C,MAAM,SAAS,GAAG,OAAO,CAAC,WAAW,IAAI,IAAI,CAAC;IAC9C,MAAM,SAAS,GACb,OAAO,CAAC,SAAS,IAAI,CAAC,CAAC,GAAG,EAAE,KAAK,EAAE,EAAE,CAAC,KAAK,KAAK,SAAS,IAAI,GAAG,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC;IAEvF,OAAO;QACL,IAAI,EAAE,KAAK,CAAC,IAAI;QAChB,KAAK,CAAC,CAAC,GAAG,CAAC,GAAG;YACZ,KAAK,IAAI,OAAO,GAAG,CAAC,EAAE,OAAO,IAAI,WAAW,EAAE,OAAO,EAAE,EAAE,CAAC;gBACxD,MAAM;oBACJ,IAAI,EAAE,MAAM;oBACZ,GAAG,EAAE,GAAG,KAAK,CAAC,IAAI,UAAU;oBAC5B,KAAK,EAAE,EAAE,OAAO,EAAE,WAAW,EAAE;iBAChC,CAAC;gBAEF,MAAM,UAAU,GAAG,GAAG,CAAC,IAAI,CAAC;gBAC5B,IAAI,MAAM,GAAY,SAAS,CAAC;gBAEhC,IAAI,CAAC;oBACH,kEAAkE;oBAClE,mEAAmE;oBACnE,oBAAoB;oBACpB,GAAG,CAAC,IAAI,GAAG,SAAS,CAAC;oBACrB,KAAK,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;gBACxB,CAAC;gBAAC,OAAO,GAAG,EAAE,CAAC;oBACb,MAAM,GAAG,GAAG,CAAC;gBACf,CAAC;gBAED,MAAM,MAAM,GAAG,SAAS,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;gBAEtC,IAAI,CAAC,MAAM,EAAE,CAAC;oBACZ,iEAAiE;oBACjE,gEAAgE;oBAChE,mCAAmC;oBACnC,OAAO;gBACT,CAAC;gBAED,IAAI,OAAO,KAAK,WAAW,EAAE,CAAC;oBAC5B,+DAA+D;oBAC/D,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;wBACzB,MAAM,MAAM,CAAC;oBACf,CAAC;oBACD,wDAAwD;oBACxD,OAAO;gBACT,CAAC;gBAED,OAAO,CAAC,OAAO,EAAE,CAAC,GAAG,EAAE,OAAO,EAAE,MAAM,CAAC,CAAC;gBACxC,GAAG,CAAC,IAAI,GAAG,UAAU,CAAC,CAAC,gCAAgC;gBACvD,OAAO,CAAC,UAAU,EAAE,CAAC,GAAG,CAAC,CAAC;gBAE1B,MAAM,KAAK,GAAG,SAAS,GAAG,CAAC,IAAI,CAAC,OAAO,GAAG,CAAC,CAAC,CAAC;gBAC7C,oEAAoE;gBACpE,oEAAoE;gBACpE,0DAA0D;gBAC1D,MAAM,cAAc,CAAC,KAAK,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;YAC1C,CAAC;QACH,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/phase.d.ts

@@ -66,6 +66,9 @@ export type PipelineEvent = {
 } | {
     type: 'done';
     reason?: string;
+} | {
+    type: 'cancelled';
+    reason: string;
 } | {
     type: 'error';
     message: string;

package/dist/phase.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"phase.d.ts","sourceRoot":"","sources":["../src/phase.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAOhD,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAC;IAC9B,yDAAyD;IACzD,IAAI,CAAC,EAAE;QAAE,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;IAC1B;;;;;OAKG;IACH,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAWD,MAAM,MAAM,aAAa,GACrB;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAAE,GAClF;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GACpC;IAAE,IAAI,EAAE,gBAAgB,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,GAC1E;IAAE,IAAI,EAAE,WAAW,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAAE,GACzF;IAAE,IAAI,EAAE,aAAa,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GAC3D;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,OAAO,CAAA;CAAE,GAC7C;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,GACjC;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAcvC,MAAM,WAAW,KAAK,CACpB,IAAI,SAAS,mBAAmB,GAAG,mBAAmB,EACtD,MAAM,GAAG,aAAa;IAEtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,GAAG,CAAC,GAAG,EAAE,IAAI,GAAG,cAAc,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;CAC9C;AAMD,wBAAgB,UAAU,CAAC,IAAI,SAAS,mBAAmB,EAAE,CAAC,SAAS,MAAM,IAAI,EAC/E,GAAG,EAAE,IAAI,EACT,GAAG,EAAE,CAAC,EACN,SAAS,EAAE,MAAM,GAChB,WAAW,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAStB"}
+{"version":3,"file":"phase.d.ts","sourceRoot":"","sources":["../src/phase.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAOhD,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAC;IAC9B,yDAAyD;IACzD,IAAI,CAAC,EAAE;QAAE,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;IAC1B;;;;;OAKG;IACH,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAWD,MAAM,MAAM,aAAa,GACrB;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAAE,GAClF;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GACpC;IAAE,IAAI,EAAE,gBAAgB,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,GAC1E;IAAE,IAAI,EAAE,WAAW,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAAE,GACzF;IAAE,IAAI,EAAE,aAAa,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GAC3D;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,OAAO,CAAA;CAAE,GAC7C;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,GAKjC;IAAE,IAAI,EAAE,WAAW,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GACrC;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAcvC,MAAM,WAAW,KAAK,CACpB,IAAI,SAAS,mBAAmB,GAAG,mBAAmB,EACtD,MAAM,GAAG,aAAa;IAEtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,GAAG,CAAC,GAAG,EAAE,IAAI,GAAG,cAAc,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;CAC9C;AAMD,wBAAgB,UAAU,CAAC,IAAI,SAAS,mBAAmB,EAAE,CAAC,SAAS,MAAM,IAAI,EAC/E,GAAG,EAAE,IAAI,EACT,GAAG,EAAE,CAAC,EACN,SAAS,EAAE,MAAM,GAChB,WAAW,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAStB"}

package/dist/phase.js.map

@@ -1 +1 @@
-{"version":3,"file":"phase.js","sourceRoot":"","sources":["../src/phase.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AA6DH,8EAA8E;AAC9E,qEAAqE;AACrE,8EAA8E;AAE9E,MAAM,UAAU,UAAU,CACxB,GAAS,EACT,GAAM,EACN,SAAiB;IAEjB,MAAM,KAAK,GAAG,GAAG,CAAC,GAAG,CAAC,CAAC;IACvB,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;QAC1C,MAAM,IAAI,KAAK,CACb,IAAI,SAAS,8BAA8B,MAAM,CAAC,GAAG,CAAC,eAAe;YACnE,kEAAkE,CACrE,CAAC;IACJ,CAAC;IACD,OAAO,KAA6B,CAAC;AACvC,CAAC"}
+{"version":3,"file":"phase.js","sourceRoot":"","sources":["../src/phase.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAkEH,8EAA8E;AAC9E,qEAAqE;AACrE,8EAA8E;AAE9E,MAAM,UAAU,UAAU,CACxB,GAAS,EACT,GAAM,EACN,SAAiB;IAEjB,MAAM,KAAK,GAAG,GAAG,CAAC,GAAG,CAAC,CAAC;IACvB,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;QAC1C,MAAM,IAAI,KAAK,CACb,IAAI,SAAS,8BAA8B,MAAM,CAAC,GAAG,CAAC,eAAe;YACnE,kEAAkE,CACrE,CAAC;IACJ,CAAC;IACD,OAAO,KAA6B,CAAC;AACvC,CAAC"}

package/dist/session/sse.d.ts

@@ -28,12 +28,16 @@ import type { JobStore } from './job-store.js';
 import type { JobRunner } from './job-runner.js';
 /**
  * Minimal response interface — `http.ServerResponse` and Express's `Response`
- * both satisfy this without modification.
+ * both satisfy this without modification. `once(drain)` is required for
+ * backpressure handling: when `write()` returns false the socket buffer is
+ * full and writes must pause until `drain` fires, or memory grows
+ * unboundedly behind a slow client.
  */
 export interface SSEResponse {
     write(chunk: string): boolean;
     end(): void;
     on(event: 'close', listener: () => void): void;
+    once(event: 'drain', listener: () => void): void;
 }
 export interface StreamToSSEOptions {
     runner: JobRunner;

package/dist/session/sse.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sse.d.ts","sourceRoot":"","sources":["../../src/session/sse.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAC/C,OAAO,KAAK,EAAE,SAAS,EAAa,MAAM,iBAAiB,CAAC;AAE5D;;;GAGG;AACH,MAAM,WAAW,WAAW;IAC1B,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC;IAC9B,GAAG,IAAI,IAAI,CAAC;IACZ,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,IAAI,GAAG,IAAI,CAAC;CAChD;AAED,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE,SAAS,CAAC;IAClB,KAAK,EAAE,QAAQ,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,WAAW,CAAC;IACjB;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;OAIG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;GAGG;AACH,wBAAsB,WAAW,CAAC,OAAO,EAAE,kBAAkB,GAAG,OAAO,CAAC,IAAI,CAAC,CAqE5E"}
+{"version":3,"file":"sse.d.ts","sourceRoot":"","sources":["../../src/session/sse.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAC/C,OAAO,KAAK,EAAE,SAAS,EAAa,MAAM,iBAAiB,CAAC;AAE5D;;;;;;GAMG;AACH,MAAM,WAAW,WAAW;IAC1B,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC;IAC9B,GAAG,IAAI,IAAI,CAAC;IACZ,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,IAAI,GAAG,IAAI,CAAC;IAC/C,IAAI,CAAC,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,IAAI,GAAG,IAAI,CAAC;CAClD;AAED,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE,SAAS,CAAC;IAClB,KAAK,EAAE,QAAQ,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,WAAW,CAAC;IACjB;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;OAIG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;GAGG;AACH,wBAAsB,WAAW,CAAC,OAAO,EAAE,kBAAkB,GAAG,OAAO,CAAC,IAAI,CAAC,CA2G5E"}

package/dist/session/sse.js

@@ -41,19 +41,30 @@ export async function streamToSSE(options) {
     res.on('close', () => {
         closed = true;
     });
-    const writeFrame = (id, type, data) => {
+    // Backpressure: when res.write() returns false the socket buffer is full
+    // and we must wait for 'drain' before continuing. Without this, slow
+    // clients cause unbounded Node-side memory growth as writes accumulate.
+    const writeWithBackpressure = async (payload) => {
         if (closed)
-            return false;
-        const payload = `id: ${id}\n` +
+            return;
+        if (!res.write(payload)) {
+            await new Promise((resolve) => res.once('drain', resolve));
+        }
+    };
+    const writeFrame = async (id, type, data) => {
+        if (closed)
+            return;
+        await writeWithBackpressure(`id: ${id}\n` +
             `event: ${type}\n` +
-            `data: ${JSON.stringify(data)}\n\n`;
-        return res.write(payload);
+            `data: ${JSON.stringify(data)}\n\n`);
     };
     // Step 1: replay anything the client has missed.
     let lastId = afterId;
     const replay = await store.getEvents(jobId, afterId);
     for (const evt of replay) {
-        writeFrame(evt.id, evt.eventType, evt.data);
+        if (closed)
+            return;
+        await writeFrame(evt.id, evt.eventType, evt.data);
         lastId = Math.max(lastId, evt.id);
     }
     // If the job is already finished and replay covered everything, close.
@@ -62,27 +73,56 @@ export async function streamToSSE(options) {
         close();
         return;
     }
-    // Step 2: subscribe to live events. Buffer events that arrived during
-    // replay if their id is past lastId (otherwise they're already sent).
+    // Step 2: subscribe to live events. The EventEmitter listener is sync
+    // and fire-and-forget by API; we buffer events and drain them serially
+    // through writeFrame so backpressure stays honored and ordering is
+    // preserved even when multiple events arrive while a write is pending.
     const channel = `job:${jobId}`;
+    const liveBuffer = [];
+    let draining = false;
+    const drainLive = async () => {
+        if (draining)
+            return;
+        draining = true;
+        try {
+            while (!closed && liveBuffer.length > 0) {
+                const evt = liveBuffer.shift();
+                if (evt.id <= lastId)
+                    continue;
+                lastId = evt.id;
+                await writeFrame(evt.id, evt.eventType, evt.data);
+                if (evt.eventType === 'done' || evt.eventType === 'error') {
+                    close();
+                    return;
+                }
+            }
+        }
+        finally {
+            draining = false;
+        }
+    };
     const onLive = (evt) => {
         if (closed)
             return;
-        if (evt.id <= lastId)
-            return;
-        lastId = evt.id;
-        writeFrame(evt.id, evt.eventType, evt.data);
-        if (evt.eventType === 'done' || evt.eventType === 'error') {
-            close();
-        }
+        liveBuffer.push(evt);
+        // Promise rejection here would be unobserved by the EventEmitter, so
+        // catch and swallow — writes that fail close the socket anyway.
+        void drainLive().catch(() => {
+            /* connection error during drain; close listener will fire */
+        });
     };
     runner.on(channel, onLive);
-    // Heartbeat: comment line every N seconds to keep proxies from idling out.
+    // Heartbeat: comment line every N seconds to keep proxies from idling
+    // out. Skip the heartbeat when the socket is back-pressured rather than
+    // queueing — heartbeats are advisory and stale ones are not useful.
     let heartbeat = null;
     if (heartbeatMs > 0) {
         heartbeat = setInterval(() => {
             if (closed)
                 return;
+            // Discard the boolean intentionally: this is a hint, not data.
+            // Backpressure is handled by event writes, which will pause the
+            // pipeline once drain is pending.
             res.write(`: keepalive ${Date.now()}\n\n`);
         }, heartbeatMs);
     }

package/dist/session/sse.js.map

@@ -1 +1 @@
-{"version":3,"file":"sse.js","sourceRoot":"","sources":["../../src/session/sse.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"sse.js","sourceRoot":"","sources":["../../src/session/sse.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAqCH;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAAC,OAA2B;IAC3D,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,GAAG,EAAE,OAAO,GAAG,CAAC,EAAE,GAAG,OAAO,CAAC;IAC3D,MAAM,WAAW,GAAG,OAAO,CAAC,WAAW,IAAI,MAAM,CAAC;IAElD,IAAI,MAAM,GAAG,KAAK,CAAC;IACnB,MAAM,KAAK,GAAG,GAAG,EAAE;QACjB,IAAI,MAAM;YAAE,OAAO;QACnB,MAAM,GAAG,IAAI,CAAC;QACd,GAAG,CAAC,GAAG,EAAE,CAAC;IACZ,CAAC,CAAC;IAEF,GAAG,CAAC,EAAE,CAAC,OAAO,EAAE,GAAG,EAAE;QACnB,MAAM,GAAG,IAAI,CAAC;IAChB,CAAC,CAAC,CAAC;IAEH,yEAAyE;IACzE,qEAAqE;IACrE,wEAAwE;IACxE,MAAM,qBAAqB,GAAG,KAAK,EAAE,OAAe,EAAiB,EAAE;QACrE,IAAI,MAAM;YAAE,OAAO;QACnB,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,OAAO,CAAC,EAAE,CAAC;YACxB,MAAM,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,EAAE,CAAC,GAAG,CAAC,IAAI,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC;QACnE,CAAC;IACH,CAAC,CAAC;IAEF,MAAM,UAAU,GAAG,KAAK,EAAE,EAAU,EAAE,IAAY,EAAE,IAAa,EAAiB,EAAE;QAClF,IAAI,MAAM;YAAE,OAAO;QACnB,MAAM,qBAAqB,CACzB,OAAO,EAAE,IAAI;YACX,UAAU,IAAI,IAAI;YAClB,SAAS,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,MAAM,CACtC,CAAC;IACJ,CAAC,CAAC;IAEF,iDAAiD;IACjD,IAAI,MAAM,GAAG,OAAO,CAAC;IACrB,MAAM,MAAM,GAAG,MAAM,KAAK,CAAC,SAAS,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;IACrD,KAAK,MAAM,GAAG,IAAI,MAAM,EAAE,CAAC;QACzB,IAAI,MAAM;YAAE,OAAO;QACnB,MAAM,UAAU,CAAC,GAAG,CAAC,EAAE,EAAE,GAAG,CAAC,SAAS,EAAE,GAAG,CAAC,IAAI,CAAC,CAAC;QAClD,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,CAAC,CAAC;IACpC,CAAC;IAED,uEAAuE;IACvE,MAAM,GAAG,GAAG,MAAM,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IACtC,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,MAAM,KAAK,WAAW,IAAI,GAAG,CAAC,MAAM,KAAK,QAAQ,CAAC,EAAE,CAAC;QACnE,KAAK,EAAE,CAAC;QACR,OAAO;IACT,CAAC;IAED,sEAAsE;IACtE,uEAAuE;IACvE,mEAAmE;IACnE,uEAAuE;IACvE,MAAM,OAAO,GAAG,OAAO,KAAK,EAAE,CAAC;IAC/B,MAAM,UAAU,GAAgB,EAAE,CAAC;IACnC,IAAI,QAAQ,GAAG,KAAK,CAAC;IACrB,MAAM,SAAS,GAAG,KAAK,IAAmB,EAAE;QAC1C,IAAI,QAAQ;YAAE,OAAO;QACrB,QAAQ,GAAG,IAAI,CAAC;QAChB,IAAI,CAAC;YACH,OAAO,CAAC,MAAM,IAAI,UAAU,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;gBACxC,MAAM,GAAG,GAAG,UAAU,CAAC,KAAK,EAAG,CAAC;gBAChC,IAAI,GAAG,CAAC,EAAE,IAAI,MAAM;oBAAE,SAAS;gBAC/B,MAAM,GAAG,GAAG,CAAC,EAAE,CAAC;gBAChB,MAAM,UAAU,CAAC,GAAG,CAAC,EAAE,EAAE,GAAG,CAAC,SAAS,EAAE,GAAG,CAAC,IAAI,CAAC,CAAC;gBAClD,IAAI,GAAG,CAAC,SAAS,KAAK,MAAM,IAAI,GAAG,CAAC,SAAS,KAAK,OAAO,EAAE,CAAC;oBAC1D,KAAK,EAAE,CAAC;oBACR,OAAO;gBACT,CAAC;YACH,CAAC;QACH,CAAC;gBAAS,CAAC;YACT,QAAQ,GAAG,KAAK,CAAC;QACnB,CAAC;IACH,CAAC,CAAC;IACF,MAAM,MAAM,GAAG,CAAC,GAAc,EAAQ,EAAE;QACtC,IAAI,MAAM;YAAE,OAAO;QACnB,UAAU,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QACrB,qEAAqE;QACrE,gEAAgE;QAChE,KAAK,SAAS,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE;YAC1B,6DAA6D;QAC/D,CAAC,CAAC,CAAC;IACL,CAAC,CAAC;IACF,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;IAE3B,sEAAsE;IACtE,wEAAwE;IACxE,oEAAoE;IACpE,IAAI,SAAS,GAA0C,IAAI,CAAC;IAC5D,IAAI,WAAW,GAAG,CAAC,EAAE,CAAC;QACpB,SAAS,GAAG,WAAW,CAAC,GAAG,EAAE;YAC3B,IAAI,MAAM;gBAAE,OAAO;YACnB,+DAA+D;YAC/D,gEAAgE;YAChE,kCAAkC;YAClC,GAAG,CAAC,KAAK,CAAC,eAAe,IAAI,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;QAC7C,CAAC,EAAE,WAAW,CAAC,CAAC;IAClB,CAAC;IAED,oCAAoC;IACpC,MAAM,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,EAAE;QAClC,GAAG,CAAC,EAAE,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;IAC3B,CAAC,CAAC,CAAC;IAEH,IAAI,SAAS;QAAE,aAAa,CAAC,SAAS,CAAC,CAAC;IACxC,MAAM,CAAC,GAAG,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;AAC9B,CAAC"}

package/dist/tools/registry.d.ts

@@ -19,9 +19,14 @@ import type { ToolDefinition, ToolExecutor, ToolResult } from '../messages.js';
  * Handler signature — receives parsed args plus optional context, returns the
  * tool's result content as a string. Anything string-shaped works (JSON,
  * markdown, plain text); the agent sees it raw.
+ *
+ * `context.signal` is the agent runner's AbortSignal when one was provided.
+ * Long-running tools (fetch, subprocess, file I/O) can observe it to cancel
+ * cooperatively. Synchronous or fast tools may ignore it.
  */
 export type ToolHandler = (args: Record<string, unknown>, context: {
     toolCallId: string;
+    signal?: AbortSignal;
 }) => Promise<string>;
 export interface ToolRegistryOptions {
     /** When false, skip schema validation. Default: true. */
@@ -39,6 +44,6 @@ export declare class ToolRegistry implements ToolExecutor {
     /** All registered tool definitions, in registration order. Hand to AgentConfig.tools. */
     definitions(): ToolDefinition[];
     has(name: string): boolean;
-    execute(name: string, toolCallId: string, args: Record<string, unknown>): Promise<ToolResult>;
+    execute(name: string, toolCallId: string, args: Record<string, unknown>, signal?: AbortSignal): Promise<ToolResult>;
 }
 //# sourceMappingURL=registry.d.ts.map