@claudexor/core 3.0.4 → 3.1.1

package/dist/answer-assembly.d.ts

@@ -7,6 +7,17 @@
 export declare class AnswerAssembly {
     private readonly parts;
     private finalText?;
+    /**
+     * MACHINE-truth final, decoupled from the DISPLAY final (codex #19816 /
+     * QA-009). A codex constrained WorkReport route pre-unwraps its final
+     * message's DISPLAY text to the `output` (so the answer bubble + the app's
+     * twin-removal see the unwrapped output, not raw JSON) and carries the raw
+     * `{work_report, output}` envelope on `payload.work_report_envelope`. The
+     * orchestrator un-nests machine truth via `machineText()`, so the display
+     * unwrap never breaks the envelope parse; adapters that leave the raw envelope
+     * IN the final text (claude) never set this, so `machineText()` === `text()`.
+     */
+    private machineFinalText?;
     /** Feed one already-sanitized harness event; non-answer events are ignored. */
     observe(ev: {
         type: string;
@@ -16,7 +27,12 @@ export declare class AnswerAssembly {
     }): void;
     /** Whether a typed final answer has been accepted. */
     hasFinal(): boolean;
-    /** The assembled answer: the typed final verbatim, else joined narration. */
+    /** The assembled answer for DISPLAY: the typed final verbatim, else joined
+     * narration. For codex constrained routes this is the UNWRAPPED output. */
     text(): string;
+    /** The assembled answer for MACHINE consumption (the WorkReport un-nest): the
+     * raw envelope when the adapter pre-unwrapped the display copy, else identical
+     * to `text()`. The orchestrator passes THIS to `unwrapWorkReportEnvelope`. */
+    machineText(): string;
 }
 //# sourceMappingURL=answer-assembly.d.ts.map

package/dist/answer-assembly.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"answer-assembly.d.ts","sourceRoot":"","sources":["../src/answer-assembly.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,qBAAa,cAAc;IACzB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAgB;IACtC,OAAO,CAAC,SAAS,CAAC,CAAS;IAE3B,+EAA+E;IAC/E,OAAO,CAAC,EAAE,EAAE;QACV,IAAI,EAAE,MAAM,CAAC;QACb,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,KAAK,CAAC,EAAE,OAAO,CAAC;QAChB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;KACnC,GAAG,IAAI;IAiBR,sDAAsD;IACtD,QAAQ,IAAI,OAAO;IAInB,6EAA6E;IAC7E,IAAI,IAAI,MAAM;CAGf"}
+{"version":3,"file":"answer-assembly.d.ts","sourceRoot":"","sources":["../src/answer-assembly.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,qBAAa,cAAc;IACzB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAgB;IACtC,OAAO,CAAC,SAAS,CAAC,CAAS;IAC3B;;;;;;;;;OASG;IACH,OAAO,CAAC,gBAAgB,CAAC,CAAS;IAElC,+EAA+E;IAC/E,OAAO,CAAC,EAAE,EAAE;QACV,IAAI,EAAE,MAAM,CAAC;QACb,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,KAAK,CAAC,EAAE,OAAO,CAAC;QAChB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;KACnC,GAAG,IAAI;IAyBR,sDAAsD;IACtD,QAAQ,IAAI,OAAO;IAInB;+EAC2E;IAC3E,IAAI,IAAI,MAAM;IAId;;kFAE8E;IAC9E,WAAW,IAAI,MAAM;CAGtB"}

package/dist/answer-assembly.js

@@ -7,9 +7,20 @@
 export class AnswerAssembly {
     parts = [];
     finalText;
+    /**
+     * MACHINE-truth final, decoupled from the DISPLAY final (codex #19816 /
+     * QA-009). A codex constrained WorkReport route pre-unwraps its final
+     * message's DISPLAY text to the `output` (so the answer bubble + the app's
+     * twin-removal see the unwrapped output, not raw JSON) and carries the raw
+     * `{work_report, output}` envelope on `payload.work_report_envelope`. The
+     * orchestrator un-nests machine truth via `machineText()`, so the display
+     * unwrap never breaks the envelope parse; adapters that leave the raw envelope
+     * IN the final text (claude) never set this, so `machineText()` === `text()`.
+     */
+    machineFinalText;
     /** Feed one already-sanitized harness event; non-answer events are ignored. */
     observe(ev) {
-        if (ev.type !== "message" || !ev.text)
+        if (ev.type !== "message")
             return;
         if (ev.payload?.["auth_switched"] === true)
             return;
@@ -18,25 +29,40 @@ export class AnswerAssembly {
         if (ev.payload?.["delta"] === true)
             return;
         if (ev.final === true) {
-            // A whitespace-only final is NOT an answer: ignore it, never let it
-            // erase an earlier real final (review sol #3). The accepted final is
-            // kept VERBATIM (the documented contract) — no trimming.
-            if (ev.text.trim().length === 0)
+            const raw = ev.payload?.["work_report_envelope"];
+            const machine = typeof raw === "string" ? raw : undefined;
+            const display = ev.text ?? "";
+            // A whitespace-only DISPLAY final is NOT an answer and must never erase an
+            // earlier real final (review sol #3) — UNLESS it carries machine truth. A
+            // codex constrained route legitimately finalizes `output:""` (all its work
+            // lived in the work_report): keep the RAW envelope so the orchestrator
+            // still un-nests work_state/outcome, with an empty display. Otherwise the
+            // accepted final is kept VERBATIM (the documented contract) — no trimming.
+            if (display.trim().length === 0 && machine === undefined)
                 return;
-            this.finalText = ev.text;
-        }
-        else {
-            pushUniqueText(this.parts, ev.text);
+            this.finalText = display;
+            this.machineFinalText = machine;
+            return;
         }
+        if (!ev.text)
+            return;
+        pushUniqueText(this.parts, ev.text);
     }
     /** Whether a typed final answer has been accepted. */
     hasFinal() {
         return this.finalText !== undefined;
     }
-    /** The assembled answer: the typed final verbatim, else joined narration. */
+    /** The assembled answer for DISPLAY: the typed final verbatim, else joined
+     * narration. For codex constrained routes this is the UNWRAPPED output. */
     text() {
         return this.finalText ?? this.parts.join("\n").trim();
     }
+    /** The assembled answer for MACHINE consumption (the WorkReport un-nest): the
+     * raw envelope when the adapter pre-unwrapped the display copy, else identical
+     * to `text()`. The orchestrator passes THIS to `unwrapWorkReportEnvelope`. */
+    machineText() {
+        return this.machineFinalText ?? this.text();
+    }
 }
 /**
  * Deduplicate the known "final result repeats the last streamed message" shape

package/dist/answer-assembly.js.map

@@ -1 +1 @@
-{"version":3,"file":"answer-assembly.js","sourceRoot":"","sources":["../src/answer-assembly.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,MAAM,OAAO,cAAc;IACR,KAAK,GAAa,EAAE,CAAC;IAC9B,SAAS,CAAU;IAE3B,+EAA+E;IAC/E,OAAO,CAAC,EAKP;QACC,IAAI,EAAE,CAAC,IAAI,KAAK,SAAS,IAAI,CAAC,EAAE,CAAC,IAAI;YAAE,OAAO;QAC9C,IAAI,EAAE,CAAC,OAAO,EAAE,CAAC,eAAe,CAAC,KAAK,IAAI;YAAE,OAAO;QACnD,qEAAqE;QACrE,+DAA+D;QAC/D,IAAI,EAAE,CAAC,OAAO,EAAE,CAAC,OAAO,CAAC,KAAK,IAAI;YAAE,OAAO;QAC3C,IAAI,EAAE,CAAC,KAAK,KAAK,IAAI,EAAE,CAAC;YACtB,oEAAoE;YACpE,qEAAqE;YACrE,yDAAyD;YACzD,IAAI,EAAE,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,MAAM,KAAK,CAAC;gBAAE,OAAO;YACxC,IAAI,CAAC,SAAS,GAAG,EAAE,CAAC,IAAI,CAAC;QAC3B,CAAC;aAAM,CAAC;YACN,cAAc,CAAC,IAAI,CAAC,KAAK,EAAE,EAAE,CAAC,IAAI,CAAC,CAAC;QACtC,CAAC;IACH,CAAC;IAED,sDAAsD;IACtD,QAAQ;QACN,OAAO,IAAI,CAAC,SAAS,KAAK,SAAS,CAAC;IACtC,CAAC;IAED,6EAA6E;IAC7E,IAAI;QACF,OAAO,IAAI,CAAC,SAAS,IAAI,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,CAAC;IACxD,CAAC;CACF;AAED;;;;GAIG;AACH,SAAS,cAAc,CAAC,KAAe,EAAE,IAAY;IACnD,MAAM,UAAU,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC;IAC/B,IAAI,CAAC,UAAU;QAAE,OAAO;IACxB,MAAM,IAAI,GAAG,KAAK,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC;IAC7C,IAAI,IAAI,KAAK,UAAU;QAAE,OAAO;IAChC,KAAK,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;AACzB,CAAC"}
+{"version":3,"file":"answer-assembly.js","sourceRoot":"","sources":["../src/answer-assembly.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,MAAM,OAAO,cAAc;IACR,KAAK,GAAa,EAAE,CAAC;IAC9B,SAAS,CAAU;IAC3B;;;;;;;;;OASG;IACK,gBAAgB,CAAU;IAElC,+EAA+E;IAC/E,OAAO,CAAC,EAKP;QACC,IAAI,EAAE,CAAC,IAAI,KAAK,SAAS;YAAE,OAAO;QAClC,IAAI,EAAE,CAAC,OAAO,EAAE,CAAC,eAAe,CAAC,KAAK,IAAI;YAAE,OAAO;QACnD,qEAAqE;QACrE,+DAA+D;QAC/D,IAAI,EAAE,CAAC,OAAO,EAAE,CAAC,OAAO,CAAC,KAAK,IAAI;YAAE,OAAO;QAC3C,IAAI,EAAE,CAAC,KAAK,KAAK,IAAI,EAAE,CAAC;YACtB,MAAM,GAAG,GAAG,EAAE,CAAC,OAAO,EAAE,CAAC,sBAAsB,CAAC,CAAC;YACjD,MAAM,OAAO,GAAG,OAAO,GAAG,KAAK,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,SAAS,CAAC;YAC1D,MAAM,OAAO,GAAG,EAAE,CAAC,IAAI,IAAI,EAAE,CAAC;YAC9B,2EAA2E;YAC3E,0EAA0E;YAC1E,2EAA2E;YAC3E,uEAAuE;YACvE,0EAA0E;YAC1E,2EAA2E;YAC3E,IAAI,OAAO,CAAC,IAAI,EAAE,CAAC,MAAM,KAAK,CAAC,IAAI,OAAO,KAAK,SAAS;gBAAE,OAAO;YACjE,IAAI,CAAC,SAAS,GAAG,OAAO,CAAC;YACzB,IAAI,CAAC,gBAAgB,GAAG,OAAO,CAAC;YAChC,OAAO;QACT,CAAC;QACD,IAAI,CAAC,EAAE,CAAC,IAAI;YAAE,OAAO;QACrB,cAAc,CAAC,IAAI,CAAC,KAAK,EAAE,EAAE,CAAC,IAAI,CAAC,CAAC;IACtC,CAAC;IAED,sDAAsD;IACtD,QAAQ;QACN,OAAO,IAAI,CAAC,SAAS,KAAK,SAAS,CAAC;IACtC,CAAC;IAED;+EAC2E;IAC3E,IAAI;QACF,OAAO,IAAI,CAAC,SAAS,IAAI,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,CAAC;IACxD,CAAC;IAED;;kFAE8E;IAC9E,WAAW;QACT,OAAO,IAAI,CAAC,gBAAgB,IAAI,IAAI,CAAC,IAAI,EAAE,CAAC;IAC9C,CAAC;CACF;AAED;;;;GAIG;AACH,SAAS,cAAc,CAAC,KAAe,EAAE,IAAY;IACnD,MAAM,UAAU,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC;IAC/B,IAAI,CAAC,UAAU;QAAE,OAAO;IACxB,MAAM,IAAI,GAAG,KAAK,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC;IAC7C,IAAI,IAAI,KAAK,UAAU;QAAE,OAAO;IAChC,KAAK,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;AACzB,CAAC"}

package/dist/effort.d.ts

@@ -1,18 +1,60 @@
 import type { EffortHint } from "@claudexor/schema";
 /**
- * Map a requested reasoning-effort hint onto the nearest level a harness
- * actually supports.
+ * Effort resolution against VENDOR-ordered ladders. There is no static rank
+ * table anywhere in this repo: a level's rank is its position in the ladder the
+ * vendor itself advertised (a model's own ordered list, or the harness's merged
+ * ladder — `mergeEffortLadders` in the schema package). Ranking is NOT
+ * permission: what a run may actually use is whatever the resolved (harness,
+ * model) ADVERTISES, so a level newer than this repo passes through untouched
+ * the moment the vendor ships it.
+ */
+/**
+ * Outcome of resolving a requested effort against an advertised vocabulary.
+ * `rejected` carries actionable text naming what IS advertised — an unknown
+ * level is never silently downgraded into something we merely guessed at.
+ */
+export type EffortCheck = {
+    status: "ok";
+    effort: EffortHint | null;
+    clamped: boolean;
+} | {
+    status: "rejected";
+    message: string;
+};
+/**
+ * Resolve a requested reasoning-effort level against the levels a specific
+ * (harness, model) advertises. THE single owner of effort semantics; every
+ * surface (adapters, settings writes, preflight) resolves through it.
  *
- * - `requested` null/undefined → null (no effort was asked for; pass no flag).
- * - `supported` empty → null (effort is NOT a tunable surface for this adapter;
- *   it passes no effort flag at all — honest, not a silent clamp to a default).
- * - `requested` exactly supported → returned unchanged.
- * - otherwise CLAMP to the nearest supported level BY RANK: above the strongest
- *   supported → the strongest; below the weakest → the weakest; in-between → the
- *   closest by rank, ties resolving to the LOWER (cheaper) level.
+ * `advertised` is what the resolved target accepts (the model's own ordered
+ * list, or the harness ladder when the model recorded none). `ladder` is the
+ * rank authority for clamping: the harness's MERGED vendor order, so a level
+ * one sibling model advertises can clamp onto what THIS model accepts (`ultra`
+ * on gpt-5.4 → `xhigh`, because the merged codex ladder places `ultra` above
+ * it). It defaults to `advertised` itself — the degenerate case where nothing
+ * beyond the target's own order is known, including a harness whose models'
+ * orders CONTRADICT each other: pass `advertised` there, which makes
+ * cross-model clamping impossible by construction and refuses instead of
+ * inventing an order.
  *
- * Pure and data-driven: the adapter feeds its own declared `effort_levels` and
- * never hard-codes a clamp table.
+ * - nothing requested → ok, no effort (pass no flag).
+ * - `advertised` empty → ok, no effort: effort is not a tunable surface here, so
+ *   the caller discloses it as ignored (INV-105) instead of clamping to a guess.
+ * - requested IS advertised → PASS THROUGH VERBATIM. This is what makes a
+ *   future vendor level work with no Claudexor change.
+ * - requested is not advertised but the LADDER places it → CLAMP to the nearest
+ *   advertised level by ladder position (ties resolve to the cheaper one).
+ * - requested is unknown to the ladder too → REJECT, naming the advertised
+ *   set. We cannot place it, so any "nearest" would be invented.
+ */
+export declare function resolveEffort(requested: EffortHint | null | undefined, advertised: readonly EffortHint[], ladder?: readonly EffortHint[]): EffortCheck;
+/**
+ * Map a requested effort onto a level the resolved (harness, model) accepts, or
+ * null when none should be sent. Thin translational wrapper over `resolveEffort`
+ * for arg builders, which must never emit a level the vendor would reject: a
+ * rejection yields null (send NO flag, keep the vendor default) rather than a
+ * fabricated downgrade. Surfaces that can talk back to the user call
+ * `resolveEffort` and report its `message`.
  */
-export declare function normalizeEffort(requested: EffortHint | null | undefined, supported: readonly EffortHint[]): EffortHint | null;
+export declare function normalizeEffort(requested: EffortHint | null | undefined, advertised: readonly EffortHint[], ladder?: readonly EffortHint[]): EffortHint | null;
 //# sourceMappingURL=effort.d.ts.map

package/dist/effort.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"effort.d.ts","sourceRoot":"","sources":["../src/effort.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAiBpD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,eAAe,CAC7B,SAAS,EAAE,UAAU,GAAG,IAAI,GAAG,SAAS,EACxC,SAAS,EAAE,SAAS,UAAU,EAAE,GAC/B,UAAU,GAAG,IAAI,CAoBnB"}
+{"version":3,"file":"effort.d.ts","sourceRoot":"","sources":["../src/effort.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAEpD;;;;;;;;GAQG;AAEH;;;;GAIG;AACH,MAAM,MAAM,WAAW,GACnB;IAAE,MAAM,EAAE,IAAI,CAAC;IAAC,MAAM,EAAE,UAAU,GAAG,IAAI,CAAC;IAAC,OAAO,EAAE,OAAO,CAAA;CAAE,GAC7D;IAAE,MAAM,EAAE,UAAU,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAE5C;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,aAAa,CAC3B,SAAS,EAAE,UAAU,GAAG,IAAI,GAAG,SAAS,EACxC,UAAU,EAAE,SAAS,UAAU,EAAE,EACjC,MAAM,GAAE,SAAS,UAAU,EAAe,GACzC,WAAW,CAkCb;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAC7B,SAAS,EAAE,UAAU,GAAG,IAAI,GAAG,SAAS,EACxC,UAAU,EAAE,SAAS,UAAU,EAAE,EACjC,MAAM,GAAE,SAAS,UAAU,EAAe,GACzC,UAAU,GAAG,IAAI,CAGnB"}

package/dist/effort.js

@@ -1,50 +1,71 @@
-import { EffortHint as EffortHintSchema } from "@claudexor/schema";
 /**
- * The full cross-harness reasoning-effort ladder, ordered weakest→strongest.
- * DERIVED from the EffortHint enum's declaration order (the single source) so the
- * ladder can never drift from the enum: a future level (e.g. `ultra`) appended to
- * the enum is automatically ranked and every adapter clamps it with no code
- * change. An EffortHint's RANK is its index here; the normalizer below clamps any
- * requested level onto the nearest level a given adapter actually supports.
- */
-const EFFORT_LADDER = EffortHintSchema.options;
-function rank(level) {
-    return EFFORT_LADDER.indexOf(level);
-}
-/**
- * Map a requested reasoning-effort hint onto the nearest level a harness
- * actually supports.
+ * Resolve a requested reasoning-effort level against the levels a specific
+ * (harness, model) advertises. THE single owner of effort semantics; every
+ * surface (adapters, settings writes, preflight) resolves through it.
  *
- * - `requested` null/undefined → null (no effort was asked for; pass no flag).
- * - `supported` empty → null (effort is NOT a tunable surface for this adapter;
- *   it passes no effort flag at all — honest, not a silent clamp to a default).
- * - `requested` exactly supported → returned unchanged.
- * - otherwise CLAMP to the nearest supported level BY RANK: above the strongest
- *   supported → the strongest; below the weakest → the weakest; in-between → the
- *   closest by rank, ties resolving to the LOWER (cheaper) level.
+ * `advertised` is what the resolved target accepts (the model's own ordered
+ * list, or the harness ladder when the model recorded none). `ladder` is the
+ * rank authority for clamping: the harness's MERGED vendor order, so a level
+ * one sibling model advertises can clamp onto what THIS model accepts (`ultra`
+ * on gpt-5.4 → `xhigh`, because the merged codex ladder places `ultra` above
+ * it). It defaults to `advertised` itself — the degenerate case where nothing
+ * beyond the target's own order is known, including a harness whose models'
+ * orders CONTRADICT each other: pass `advertised` there, which makes
+ * cross-model clamping impossible by construction and refuses instead of
+ * inventing an order.
  *
- * Pure and data-driven: the adapter feeds its own declared `effort_levels` and
- * never hard-codes a clamp table.
+ * - nothing requested → ok, no effort (pass no flag).
+ * - `advertised` empty → ok, no effort: effort is not a tunable surface here, so
+ *   the caller discloses it as ignored (INV-105) instead of clamping to a guess.
+ * - requested IS advertised → PASS THROUGH VERBATIM. This is what makes a
+ *   future vendor level work with no Claudexor change.
+ * - requested is not advertised but the LADDER places it → CLAMP to the nearest
+ *   advertised level by ladder position (ties resolve to the cheaper one).
+ * - requested is unknown to the ladder too → REJECT, naming the advertised
+ *   set. We cannot place it, so any "nearest" would be invented.
  */
-export function normalizeEffort(requested, supported) {
-    if (requested === null || requested === undefined)
-        return null;
-    if (supported.length === 0)
-        return null;
-    if (supported.includes(requested))
-        return requested;
-    const want = rank(requested);
-    let best = null;
-    let bestDistance = Number.POSITIVE_INFINITY;
-    for (const level of supported) {
-        const distance = Math.abs(rank(level) - want);
-        // Strictly-closer wins; on a tie keep the LOWER-ranked (cheaper) candidate.
+export function resolveEffort(requested, advertised, ladder = advertised) {
+    if (requested === null || requested === undefined) {
+        return { status: "ok", effort: null, clamped: false };
+    }
+    if (advertised.length === 0)
+        return { status: "ok", effort: null, clamped: false };
+    if (advertised.includes(requested))
+        return { status: "ok", effort: requested, clamped: false };
+    const want = ladder.indexOf(requested);
+    // Only levels the ladder places can host a clamp; a level outside the ladder
+    // is a valid TARGET only through the exact-match branch above.
+    const rankable = advertised.filter((level) => ladder.indexOf(level) >= 0);
+    if (want < 0 || rankable.length === 0) {
+        return {
+            status: "rejected",
+            message: `effort "${requested}" is not advertised here and the advertised ladder cannot place it ` +
+                `(advertised: ${advertised.join(", ")})`,
+        };
+    }
+    let best = rankable[0];
+    let bestDistance = Math.abs(ladder.indexOf(best) - want);
+    for (const level of rankable.slice(1)) {
+        const distance = Math.abs(ladder.indexOf(level) - want);
+        // Strictly-closer wins; on a tie keep the LOWER-positioned (cheaper) candidate.
         if (distance < bestDistance ||
-            (distance === bestDistance && best !== null && rank(level) < rank(best))) {
+            (distance === bestDistance && ladder.indexOf(level) < ladder.indexOf(best))) {
             best = level;
             bestDistance = distance;
         }
     }
-    return best;
+    return { status: "ok", effort: best, clamped: true };
+}
+/**
+ * Map a requested effort onto a level the resolved (harness, model) accepts, or
+ * null when none should be sent. Thin translational wrapper over `resolveEffort`
+ * for arg builders, which must never emit a level the vendor would reject: a
+ * rejection yields null (send NO flag, keep the vendor default) rather than a
+ * fabricated downgrade. Surfaces that can talk back to the user call
+ * `resolveEffort` and report its `message`.
+ */
+export function normalizeEffort(requested, advertised, ladder = advertised) {
+    const check = resolveEffort(requested, advertised, ladder);
+    return check.status === "ok" ? check.effort : null;
 }
 //# sourceMappingURL=effort.js.map

package/dist/effort.js.map

@@ -1 +1 @@
-{"version":3,"file":"effort.js","sourceRoot":"","sources":["../src/effort.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,UAAU,IAAI,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAEnE;;;;;;;GAOG;AACH,MAAM,aAAa,GAA0B,gBAAgB,CAAC,OAAO,CAAC;AAEtE,SAAS,IAAI,CAAC,KAAiB;IAC7B,OAAO,aAAa,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;AACtC,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,eAAe,CAC7B,SAAwC,EACxC,SAAgC;IAEhC,IAAI,SAAS,KAAK,IAAI,IAAI,SAAS,KAAK,SAAS;QAAE,OAAO,IAAI,CAAC;IAC/D,IAAI,SAAS,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IACxC,IAAI,SAAS,CAAC,QAAQ,CAAC,SAAS,CAAC;QAAE,OAAO,SAAS,CAAC;IAEpD,MAAM,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC,CAAC;IAC7B,IAAI,IAAI,GAAsB,IAAI,CAAC;IACnC,IAAI,YAAY,GAAG,MAAM,CAAC,iBAAiB,CAAC;IAC5C,KAAK,MAAM,KAAK,IAAI,SAAS,EAAE,CAAC;QAC9B,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,IAAI,CAAC,CAAC;QAC9C,4EAA4E;QAC5E,IACE,QAAQ,GAAG,YAAY;YACvB,CAAC,QAAQ,KAAK,YAAY,IAAI,IAAI,KAAK,IAAI,IAAI,IAAI,CAAC,KAAK,CAAC,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC,EACxE,CAAC;YACD,IAAI,GAAG,KAAK,CAAC;YACb,YAAY,GAAG,QAAQ,CAAC;QAC1B,CAAC;IACH,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC"}
+{"version":3,"file":"effort.js","sourceRoot":"","sources":["../src/effort.ts"],"names":[],"mappings":"AAqBA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,MAAM,UAAU,aAAa,CAC3B,SAAwC,EACxC,UAAiC,EACjC,SAAgC,UAAU;IAE1C,IAAI,SAAS,KAAK,IAAI,IAAI,SAAS,KAAK,SAAS,EAAE,CAAC;QAClD,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;IACxD,CAAC;IACD,IAAI,UAAU,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;IACnF,IAAI,UAAU,CAAC,QAAQ,CAAC,SAAS,CAAC;QAAE,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;IAE/F,MAAM,IAAI,GAAG,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;IACvC,6EAA6E;IAC7E,+DAA+D;IAC/D,MAAM,QAAQ,GAAG,UAAU,CAAC,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC;IAC1E,IAAI,IAAI,GAAG,CAAC,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACtC,OAAO;YACL,MAAM,EAAE,UAAU;YAClB,OAAO,EACL,WAAW,SAAS,qEAAqE;gBACzF,gBAAgB,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG;SAC3C,CAAC;IACJ,CAAC;IAED,IAAI,IAAI,GAAe,QAAQ,CAAC,CAAC,CAAe,CAAC;IACjD,IAAI,YAAY,GAAG,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC,CAAC;IACzD,KAAK,MAAM,KAAK,IAAI,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC;QACtC,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,GAAG,IAAI,CAAC,CAAC;QACxD,gFAAgF;QAChF,IACE,QAAQ,GAAG,YAAY;YACvB,CAAC,QAAQ,KAAK,YAAY,IAAI,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,GAAG,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,EAC3E,CAAC;YACD,IAAI,GAAG,KAAK,CAAC;YACb,YAAY,GAAG,QAAQ,CAAC;QAC1B,CAAC;IACH,CAAC;IACD,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;AACvD,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,eAAe,CAC7B,SAAwC,EACxC,UAAiC,EACjC,SAAgC,UAAU;IAE1C,MAAM,KAAK,GAAG,aAAa,CAAC,SAAS,EAAE,UAAU,EAAE,MAAM,CAAC,CAAC;IAC3D,OAAO,KAAK,CAAC,MAAM,KAAK,IAAI,CAAC,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC;AACrD,CAAC"}

package/dist/env-scope.d.ts

@@ -34,5 +34,5 @@ export declare const CLEAN_ENV_ALLOWLIST: readonly string[];
  * allowlist (agent isolation). The adapter's `spec.env` overrides + the
  * providerScrubEnv patch are applied ON TOP of this by the spawn layer.
  */
-export declare function composeBaseEnv(inheritance: "mirror_native" | "clean", source?: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
+export declare function composeBaseEnv(inheritance: "mirror_native" | "clean", source?: NodeJS.ProcessEnv, execPath?: string, platform?: NodeJS.Platform): NodeJS.ProcessEnv;
 //# sourceMappingURL=env-scope.d.ts.map

package/dist/env-scope.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"env-scope.d.ts","sourceRoot":"","sources":["../src/env-scope.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,mBAAmB,EAAE,SAAS,MAAM,EA4DhD,CAAC;AAEF;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,GAAE,SAAS,MAAM,EAAO,GAAG,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC,CAOnF;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,mBAAmB,EAAE,SAAS,MAAM,EAoChD,CAAC;AAEF;;;;;GAKG;AACH,wBAAgB,cAAc,CAC5B,WAAW,EAAE,eAAe,GAAG,OAAO,EACtC,MAAM,GAAE,MAAM,CAAC,UAAwB,GACtC,MAAM,CAAC,UAAU,CASnB"}
+{"version":3,"file":"env-scope.d.ts","sourceRoot":"","sources":["../src/env-scope.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,mBAAmB,EAAE,SAAS,MAAM,EA4DhD,CAAC;AAEF;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,GAAE,SAAS,MAAM,EAAO,GAAG,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC,CAOnF;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,mBAAmB,EAAE,SAAS,MAAM,EAoChD,CAAC;AAEF;;;;;GAKG;AACH,wBAAgB,cAAc,CAC5B,WAAW,EAAE,eAAe,GAAG,OAAO,EACtC,MAAM,GAAE,MAAM,CAAC,UAAwB,EACvC,QAAQ,GAAE,MAAyB,EACnC,QAAQ,GAAE,MAAM,CAAC,QAA2B,GAC3C,MAAM,CAAC,UAAU,CASnB"}

package/dist/env-scope.js

@@ -139,8 +139,8 @@ export const CLEAN_ENV_ALLOWLIST = [
  * allowlist (agent isolation). The adapter's `spec.env` overrides + the
  * providerScrubEnv patch are applied ON TOP of this by the spawn layer.
  */
-export function composeBaseEnv(inheritance, source = process.env) {
-    const normalizedSource = harnessRuntimeEnv(source);
+export function composeBaseEnv(inheritance, source = process.env, execPath = process.execPath, platform = process.platform) {
+    const normalizedSource = harnessRuntimeEnv(source, execPath, platform);
     if (inheritance !== "clean")
         return normalizedSource;
     const out = {};

package/dist/env-scope.js.map

@@ -1 +1 @@
-{"version":3,"file":"env-scope.js","sourceRoot":"","sources":["../src/env-scope.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"env-scope.js","sourceRoot":"","sources":["../src/env-scope.ts"],"names":[],"mappings":"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"}

package/dist/errors.d.ts

@@ -13,4 +13,15 @@ export declare class ContextOverflowError extends ClaudexorError {
 }
 export declare class WorkspaceError extends ClaudexorError {
 }
+/**
+ * The Claudexor delegation belt (D32) cannot be made operational for this run:
+ * no `cli.js` entry that hosts `mcp serve-belt` exists next to the launching
+ * process OR this module. Emitting the belt descriptor anyway would spawn
+ * `node <missing cli.js> mcp serve-belt`, which MODULE_NOT_FOUNDs inside the
+ * harness — the belt reports `failed`, the harness silently answers from its
+ * own native subagent, and the run terminalizes a false success (QA-024). We
+ * refuse TYPED at preflight instead, naming the probed entry and the remedy.
+ */
+export declare class DelegationBeltUnavailableError extends ClaudexorError {
+}
 //# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,qBAAa,cAAe,SAAQ,KAAK;gBAC3B,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE;CAI3D;AAED,qBAAa,uBAAwB,SAAQ,cAAc;CAAG;AAC9D,qBAAa,oBAAqB,SAAQ,cAAc;CAAG;AAC3D,qBAAa,cAAe,SAAQ,cAAc;CAAG"}
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,qBAAa,cAAe,SAAQ,KAAK;gBAC3B,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE;CAI3D;AAED,qBAAa,uBAAwB,SAAQ,cAAc;CAAG;AAC9D,qBAAa,oBAAqB,SAAQ,cAAc;CAAG;AAC3D,qBAAa,cAAe,SAAQ,cAAc;CAAG;AAErD;;;;;;;;GAQG;AACH,qBAAa,8BAA+B,SAAQ,cAAc;CAAG"}

package/dist/errors.js

@@ -14,4 +14,15 @@ export class ContextOverflowError extends ClaudexorError {
 }
 export class WorkspaceError extends ClaudexorError {
 }
+/**
+ * The Claudexor delegation belt (D32) cannot be made operational for this run:
+ * no `cli.js` entry that hosts `mcp serve-belt` exists next to the launching
+ * process OR this module. Emitting the belt descriptor anyway would spawn
+ * `node <missing cli.js> mcp serve-belt`, which MODULE_NOT_FOUNDs inside the
+ * harness — the belt reports `failed`, the harness silently answers from its
+ * own native subagent, and the run terminalizes a false success (QA-024). We
+ * refuse TYPED at preflight instead, naming the probed entry and the remedy.
+ */
+export class DelegationBeltUnavailableError extends ClaudexorError {
+}
 //# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -1 +1 @@
-{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,OAAO,cAAe,SAAQ,KAAK;IACvC,YAAY,OAAe,EAAE,OAA6B;QACxD,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QACxB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC;IACpC,CAAC;CACF;AAED,MAAM,OAAO,uBAAwB,SAAQ,cAAc;CAAG;AAC9D,MAAM,OAAO,oBAAqB,SAAQ,cAAc;CAAG;AAC3D,MAAM,OAAO,cAAe,SAAQ,cAAc;CAAG"}
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,OAAO,cAAe,SAAQ,KAAK;IACvC,YAAY,OAAe,EAAE,OAA6B;QACxD,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QACxB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC;IACpC,CAAC;CACF;AAED,MAAM,OAAO,uBAAwB,SAAQ,cAAc;CAAG;AAC9D,MAAM,OAAO,oBAAqB,SAAQ,cAAc;CAAG;AAC3D,MAAM,OAAO,cAAe,SAAQ,cAAc;CAAG;AAErD;;;;;;;;GAQG;AACH,MAAM,OAAO,8BAA+B,SAAQ,cAAc;CAAG"}

package/dist/inactivity.d.ts

@@ -1,17 +1,3 @@
-/**
- * Inactivity watchdog for harness event streams: a wedged vendor CLI
- * that stops emitting events would otherwise park the run in `running`
- * forever — only reviewers had a timeout. The combinator pumps the source
- * iterator and re-arms a timer on EVERY event; when the window elapses with
- * no event, `onTimeout` fires exactly once (the caller aborts its per-attempt
- * controller, which kills the process group through the existing abort
- * plumbing) and the pump stops waiting for the source.
- *
- * This is an INACTIVITY window, not a wall-clock cap: long runs are fine as
- * long as they keep talking. Distinct from cancellation by construction —
- * the caller decides what the timeout means (typed harness_timeout failure),
- * and a user cancel still routes through the run signal.
- */
 export declare class HarnessInactivityTimeoutError extends Error {
     readonly timeoutMs: number;
     constructor(timeoutMs: number);
@@ -27,5 +13,12 @@ export declare function withInactivityWatchdog<T>(source: AsyncIterable<T>, opts
      * and the interaction channel enforces its own answer-wait budget.
      */
     isSuspended?: () => boolean;
+    /**
+     * How long to drain the aborted source's cleanup after a timeout (or await
+     * iterator.return on an early caller break) before giving up. MUST exceed
+     * the source's process-reap deadline so its typed termination_unconfirmed
+     * terminal fact surfaces; defaults to {@link REAP_PROOF_DEADLINE_MS}.
+     */
+    cleanupDeadlineMs?: number;
 }): AsyncIterable<T>;
 //# sourceMappingURL=inactivity.d.ts.map

package/dist/inactivity.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"inactivity.d.ts","sourceRoot":"","sources":["../src/inactivity.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,qBAAa,6BAA8B,SAAQ,KAAK;IAC1C,QAAQ,CAAC,SAAS,EAAE,MAAM;gBAAjB,SAAS,EAAE,MAAM;CAQvC;AAED,wBAAuB,sBAAsB,CAAC,CAAC,EAC7C,MAAM,EAAE,aAAa,CAAC,CAAC,CAAC,EACxB,IAAI,EAAE;IACJ,SAAS,EAAE,MAAM,CAAC;IAClB,kEAAkE;IAClE,SAAS,EAAE,MAAM,IAAI,CAAC;IACtB;;;;;OAKG;IACH,WAAW,CAAC,EAAE,MAAM,OAAO,CAAC;CAC7B,GACA,aAAa,CAAC,CAAC,CAAC,CAiDlB"}
+{"version":3,"file":"inactivity.d.ts","sourceRoot":"","sources":["../src/inactivity.ts"],"names":[],"mappings":"AA4BA,qBAAa,6BAA8B,SAAQ,KAAK;IAC1C,QAAQ,CAAC,SAAS,EAAE,MAAM;gBAAjB,SAAS,EAAE,MAAM;CAQvC;AAED,wBAAuB,sBAAsB,CAAC,CAAC,EAC7C,MAAM,EAAE,aAAa,CAAC,CAAC,CAAC,EACxB,IAAI,EAAE;IACJ,SAAS,EAAE,MAAM,CAAC;IAClB,kEAAkE;IAClE,SAAS,EAAE,MAAM,IAAI,CAAC;IACtB;;;;;OAKG;IACH,WAAW,CAAC,EAAE,MAAM,OAAO,CAAC;IAC5B;;;;;OAKG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B,GACA,aAAa,CAAC,CAAC,CAAC,CA8FlB"}

package/dist/inactivity.js

@@ -12,6 +12,19 @@
  * the caller decides what the timeout means (typed harness_timeout failure),
  * and a user cancel still routes through the run signal.
  */
+/** QA-027: how long to await the source's cleanup after an inactivity timeout
+ * (or an early caller break) before the watchdog gives up and lets the terminal
+ * proceed anyway. This MUST exceed spawnProcess's own whole-tree death-proof
+ * deadline (`cancelDeadlineMs`, default `cancelKillDelayMs + 4000` = 5000ms) so
+ * the underlying runCliHarness reap runs to completion and its typed
+ * `termination_unconfirmed` terminal fact (14e958a3) is emitted through the
+ * stream. The previous 2000ms grace was SHORTER than the reap deadline, so on an
+ * inactivity timeout the caller could terminalize BEFORE death was proven and
+ * the unconfirmed-death disclosure was dropped (runCliHarness wires no
+ * `onTerminationUnconfirmed` callback, the only channel an early
+ * iterator.return leaves). A pathological in-memory source still cannot park the
+ * run past this bound. Overridable per-call for deterministic tests. */
+const REAP_PROOF_DEADLINE_MS = 8000;
 export class HarnessInactivityTimeoutError extends Error {
     timeoutMs;
     constructor(timeoutMs) {
@@ -27,6 +40,7 @@ export async function* withInactivityWatchdog(source, opts) {
     let timer = null;
     let timedOut = false;
     let wake = null;
+    const cleanupDeadlineMs = opts.cleanupDeadlineMs ?? REAP_PROOF_DEADLINE_MS;
     const arm = () => {
         if (timer)
             clearTimeout(timer);
@@ -43,35 +57,108 @@ export async function* withInactivityWatchdog(source, opts) {
         // else on the event loop, and an unref'd watchdog would let node exit 0
         // mid-run instead of firing the timeout.
     };
+    // Hold the in-flight next() across the race so a timeout NEVER orphans it: the
+    // very next value the source produces (the source reacting to the abort with
+    // its terminal death-proof events) must be consumed by the drain, not silently
+    // eaten by an abandoned pending promise from this loop.
+    let pending = null;
     try {
         arm();
         for (;;) {
+            if (!pending)
+                pending = iterator.next();
             // Race the next event against the watchdog firing: after onTimeout()
             // aborts the child, the source SHOULD end on its own, but a stuck
             // iterator must not keep the run parked — the sentinel wakes the pump.
-            const next = await Promise.race([
-                iterator.next(),
+            const raced = await Promise.race([
+                pending.then((result) => ({
+                    kind: "next",
+                    result,
+                })),
                 new Promise((resolve) => {
-                    wake = () => resolve("timeout");
+                    wake = () => resolve({ kind: "timeout" });
                     if (timedOut)
-                        resolve("timeout");
+                        resolve({ kind: "timeout" });
                 }),
             ]);
-            if (next === "timeout" || timedOut) {
+            if (raced.kind === "timeout" || timedOut) {
+                // Inactivity fired. onTimeout() already aborted the child. Do NOT throw
+                // and terminalize yet: DRAIN the aborted source to its process-reap
+                // deadline so the underlying spawnProcess whole-tree death proof runs
+                // and its typed `termination_unconfirmed` terminal fact (14e958a3) is
+                // emitted THROUGH the stream — instead of being cut off by an early
+                // iterator.return whose only disclosure channel (spawnProcess's
+                // `onTerminationUnconfirmed` callback) runCliHarness never wires up.
+                // The still-pending next() is handed to the drain so the FIRST terminal
+                // event is not lost; yielding the drained events lets the caller see the
+                // unconfirmed-death error/terminal before it terminalizes on the throw.
+                yield* drainAfterTimeout(iterator, pending, cleanupDeadlineMs);
                 throw new HarnessInactivityTimeoutError(opts.timeoutMs);
             }
-            if (next.done)
+            pending = null;
+            if (raced.result.done)
                 return;
             arm();
-            yield next.value;
+            yield raced.result.value;
         }
     }
     finally {
         if (timer)
             clearTimeout(timer);
-        // Release a source still mid-iteration (also triggers spawnProcess's
-        // finally -> requestCancel when the caller exits the loop early).
-        void iterator.return?.(undefined);
+        // AWAIT the source's cleanup (QA-027): iterator.return() drives
+        // spawnProcess's finally -> requestCancel, i.e. the process teardown. It
+        // used to be fire-and-forgotten, so the agent loop could break on abort and
+        // the run could reach its `cancelled` terminal BEFORE the child was proven
+        // dead. Awaiting makes the terminal strictly follow the death proof.
+        //
+        // Bound the wait by the SAME reap deadline the drain uses (not a shorter
+        // grace): a cooperative spawnProcess-backed stream resolves return() as soon
+        // as the reap settles, so the terminal follows the death proof in the real
+        // path; a pathological in-memory source suspended in an UNRELATED await must
+        // never park the terminal past the reap's own deadline. (After a timeout the
+        // drain above already ran the source to completion, so this return() is then
+        // a fast no-op.)
+        const ret = iterator.return?.(undefined);
+        if (ret) {
+            await Promise.race([
+                Promise.resolve(ret).then(() => undefined, () => undefined),
+                new Promise((resolve) => {
+                    const grace = setTimeout(resolve, cleanupDeadlineMs);
+                    grace.unref?.();
+                }),
+            ]);
+        }
+    }
+}
+/**
+ * After an inactivity timeout aborted the child, pump the source to completion
+ * so its own teardown/death-proof events (the typed `termination_unconfirmed`
+ * terminal fact and terminal `completed`) surface through the stream, bounded by
+ * the process-reap deadline so a source that cannot prove death still cannot
+ * park the run. The inactivity timer is NOT re-armed here — the source is being
+ * torn down, and a second timeout would race the reap it is waiting on.
+ */
+async function* drainAfterTimeout(iterator, pending, deadlineMs) {
+    const deadline = new Promise((resolve) => {
+        const t = setTimeout(() => resolve("deadline"), Math.max(1, deadlineMs));
+        t.unref?.();
+    });
+    // Start from the loop's still-in-flight next() (the abort-reaction event),
+    // then keep pumping until the source ends or the reap deadline elapses.
+    let cur = pending;
+    for (;;) {
+        const drained = await Promise.race([
+            cur.then((result) => ({ kind: "next", result })),
+            deadline,
+        ]);
+        // Source could not prove death within the reap deadline — give up draining;
+        // the outer `finally` runs iterator.return() (also bounded) as a last resort.
+        if (drained === "deadline")
+            return;
+        if (drained.result.done)
+            return;
+        yield drained.result.value;
+        cur = iterator.next();
     }
 }
 //# sourceMappingURL=inactivity.js.map

package/dist/inactivity.js.map

@@ -1 +1 @@
-{"version":3,"file":"inactivity.js","sourceRoot":"","sources":["../src/inactivity.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,MAAM,OAAO,6BAA8B,SAAQ,KAAK;IACjC;IAArB,YAAqB,SAAiB;QACpC,KAAK,CACH,kCAAkC,SAAS,4BAA4B;YACrE,6DAA6D;YAC7D,gFAAgF,CACnF,CAAC;QALiB,cAAS,GAAT,SAAS,CAAQ;QAMpC,IAAI,CAAC,IAAI,GAAG,+BAA+B,CAAC;IAC9C,CAAC;CACF;AAED,MAAM,CAAC,KAAK,SAAS,CAAC,CAAC,sBAAsB,CAC3C,MAAwB,EACxB,IAWC;IAED,MAAM,QAAQ,GAAG,MAAM,CAAC,MAAM,CAAC,aAAa,CAAC,EAAE,CAAC;IAChD,IAAI,KAAK,GAAyC,IAAI,CAAC;IACvD,IAAI,QAAQ,GAAG,KAAK,CAAC;IACrB,IAAI,IAAI,GAAwB,IAAI,CAAC;IACrC,MAAM,GAAG,GAAG,GAAS,EAAE;QACrB,IAAI,KAAK;YAAE,YAAY,CAAC,KAAK,CAAC,CAAC;QAC/B,KAAK,GAAG,UAAU,CAChB,GAAG,EAAE;YACH,IAAI,IAAI,CAAC,WAAW,EAAE,EAAE,EAAE,CAAC;gBACzB,GAAG,EAAE,CAAC;gBACN,OAAO;YACT,CAAC;YACD,QAAQ,GAAG,IAAI,CAAC;YAChB,IAAI,CAAC,SAAS,EAAE,CAAC;YACjB,IAAI,EAAE,EAAE,CAAC;QACX,CAAC,EACD,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,SAAS,CAAC,CAC5B,CAAC;QACF,yEAAyE;QACzE,wEAAwE;QACxE,yCAAyC;IAC3C,CAAC,CAAC;IACF,IAAI,CAAC;QACH,GAAG,EAAE,CAAC;QACN,SAAS,CAAC;YACR,qEAAqE;YACrE,kEAAkE;YAClE,uEAAuE;YACvE,MAAM,IAAI,GAAG,MAAM,OAAO,CAAC,IAAI,CAAC;gBAC9B,QAAQ,CAAC,IAAI,EAAE;gBACf,IAAI,OAAO,CAAY,CAAC,OAAO,EAAE,EAAE;oBACjC,IAAI,GAAG,GAAG,EAAE,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;oBAChC,IAAI,QAAQ;wBAAE,OAAO,CAAC,SAAS,CAAC,CAAC;gBACnC,CAAC,CAAC;aACH,CAAC,CAAC;YACH,IAAI,IAAI,KAAK,SAAS,IAAI,QAAQ,EAAE,CAAC;gBACnC,MAAM,IAAI,6BAA6B,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;YAC1D,CAAC;YACD,IAAI,IAAI,CAAC,IAAI;gBAAE,OAAO;YACtB,GAAG,EAAE,CAAC;YACN,MAAM,IAAI,CAAC,KAAK,CAAC;QACnB,CAAC;IACH,CAAC;YAAS,CAAC;QACT,IAAI,KAAK;YAAE,YAAY,CAAC,KAAK,CAAC,CAAC;QAC/B,qEAAqE;QACrE,kEAAkE;QAClE,KAAK,QAAQ,CAAC,MAAM,EAAE,CAAC,SAAkB,CAAC,CAAC;IAC7C,CAAC;AACH,CAAC"}
+{"version":3,"file":"inactivity.js","sourceRoot":"","sources":["../src/inactivity.ts"],"names":[],"mappings":"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"}