@sema-ai/core 1.275.1

package/dist/core/runner/assemble-result.d.ts

@@ -0,0 +1,191 @@
+import type { AssistantMessage } from "../../internal/llm.js";
+import type { TaskResult, TaskSpec } from "../types.js";
+/** Per-task usage/cost accumulator (filled across the run loop, surfaced as `TaskResult.stats`). */
+export interface Stats {
+    turns: number;
+    tokens: number;
+    /** design/97 CORE-8 (②): total tool calls executed (one per `tool_start`). Spread into `TaskResult.stats`. */
+    toolCalls: number;
+    promptTokens: number;
+    cachedTokens: number;
+    cacheWriteTokens: number;
+    cacheWriteTokensLong: number;
+    outputTokens: number;
+    cacheHitRate?: number;
+    totalInputTokens?: number;
+    costUsd: number;
+    costMicroUsd: number;
+    nested?: {
+        tokens: number;
+        turns: number;
+        tasks: number;
+        costUsd?: number;
+        costMicroUsd?: number;
+    };
+    /** Post-task memory-consolidation usage (design/41); set after the result is assembled. Kept out of
+     *  the budget gate (`overBudget` reads `costMicroUsd`/`tokens`, never this). */
+    memory?: {
+        tokens: number;
+        costMicroUsd: number;
+        applied: number;
+    };
+    /** design/91: human-review burden (design/89 §2.4 C2). Wall-clock approval-gate wait + count, bucketed by
+     *  `gate.kind`, accumulated across resume legs. Set by the run loop from the per-task human-review
+     *  accumulator (synchronous `resolveAsk` timing + durable resume latency). **NOT an LLM cost** — never
+     *  folded into `costMicroUsd`/`costBreakdown`/the budget gate (same budget-excluded treatment as `memory`).
+     *  Flows straight through to `TaskResult.stats.humanReview` via the public-stats spread; absent ⇒ no gate. */
+    humanReview?: {
+        count: number;
+        totalWaitMs: number;
+        gates: Array<{
+            kind: string;
+            waitMs: number;
+            decision?: string;
+            toolName?: string;
+            toolArg?: string;
+        }>;
+    };
+    /** TB telemetry B2 (service [397]): deadline-mechanism engagement counters (design/128 nudges +
+     *  design/130 P1 cap shrinks / P2 finalize / P2b callCutoffs=brain-side walltime stream cuts +
+     *  toolClamps=foreground shell timeouts clamped to the soft tool deadline). Set by the run loop
+     *  only when ≥1 engaged; flows straight through to `TaskResult.stats.mechanisms` via the
+     *  public-stats spread. */
+    mechanisms?: {
+        finalizeInjected?: true;
+        nudgesSent?: number;
+        capShrinks?: number;
+        callCutoffs?: number;
+        toolClamps?: number;
+        finalVerifyInjected?: true;
+        finalVerifyInjections?: number;
+        attachmentsInjected?: number;
+        repetitionCuts?: number;
+        repetitionSpared?: number;
+        repetitionEvents?: Array<{
+            turn: number;
+            action: "cut" | "spared";
+            rule: "char-run" | "unit-loop";
+            period: number;
+            reps: number;
+            segment: string;
+        }>;
+    };
+    /** design/80 D-E-core (Part B): within-task compaction LLM cost (micro-USD), accumulated by
+     *  `recordCompactionUsage` as a SEPARATE running total because that cost IS folded into `costMicroUsd`
+     *  (so it can't be re-derived from `costMicroUsd` alone). The {@link costBreakdown.compactionMicroUsd}
+     *  source. Run-loop internal — not a public `TaskResult.stats` field. */
+    compactionMicroUsd?: number;
+    /**
+     * design/80 D-E-core (Part B): a thin FINANCE TAXONOMY of the LLM-derived costs the engine actually
+     * prices, decomposing the task's spend into report categories (no new persisted structure — derived from
+     * the cost sources that already exist). CORE = LLM-token-derived ONLY; the SERVICE adds the infra axes it
+     * owns (tool-call / sandbox-walltime / egress — it has the k8s cost data) and composes them with this.
+     * Each category is ≥ 0 and the parts reconcile to the independently-summed LLM total
+     * (`llmRoot + nestedSubagent + compaction` — `memory` is a separate, budget-excluded line, see its doc).
+     * Filled in assembleResult for `llmRoot`/`nestedSubagent`/`compaction`; the `memoryConsolidation` line is
+     * filled LATER (runtask, alongside `stats.memory`, AFTER the async consolidation pass) — it is 0 here.
+     */
+    costBreakdown?: {
+        /** Root-agent LLM cost (micro-USD): `costMicroUsd` MINUS the sub-categories already folded into it
+         *  (compaction). NOT minus nested — nested subagent cost is tracked separately and is NEVER folded into
+         *  `costMicroUsd` (it lands only in `stats.nested`), so subtracting it would under-report the root. */
+        llmRootMicroUsd: number;
+        /** Delegated sub-agent (nested) LLM cost (micro-USD) = `stats.nested?.costMicroUsd ?? 0`. */
+        nestedSubagentMicroUsd: number;
+        /** Post-task memory-consolidation LLM cost (micro-USD) = `stats.memory?.costMicroUsd ?? 0`. Filled in
+         *  runtask AFTER the (async) consolidation pass sets `stats.memory`; 0 at assembleResult time. */
+        memoryConsolidationMicroUsd: number;
+        /** Within-task compaction LLM cost (micro-USD) = the running `compactionMicroUsd` accumulator (the
+         *  category Framing-4 missed). This IS part of `costMicroUsd`, so it is subtracted from `llmRoot`. */
+        compactionMicroUsd: number;
+    };
+}
+/**
+ * The terminal-state flags the run loop hands {@link assembleResult} — the typed contract between the
+ * loop and result assembly (council design/34 ⑤: exported so it's grep-able and tests can construct it).
+ */
+export interface ResultFlags {
+    threw: unknown;
+    /** design/99 MF-25: the EFFECTIVE (resolved) model id that served the task — echoed on `TaskResult.model`. */
+    model?: string;
+    abortedForTimeout: boolean;
+    abortedForTurns: boolean;
+    /** audit A-1: the abort signal fired DURING the run (user interrupt / timeout / max-turns / budget),
+     *  captured before the run loop's unconditional release-abort. Since the loop now exits CLEANLY on an
+     *  abort (no synthetic stopReason:"aborted" assistant is appended), `final` is the last REAL assistant
+     *  message — this flag is what keeps an interrupted run from being mistaken for a completed one. */
+    abortedLive?: boolean;
+    budgetHit?: "exceeded" | "precall";
+    blockedReason?: string;
+    conflict?: boolean;
+    outputInvalid?: boolean;
+    /** design/72 §2.2 (B): a re-suspend was refused because the task already suspended `maxSuspends` times
+     *  (a resume/restart loop). It aborted the run (no `threw`) but must read as `failed`/`suspend.loop`,
+     *  NOT `suspended` — slotted ABOVE `suspendRef` and the aborted branches (this suspend never minted a
+     *  checkpoint, so `suspendRef` is unset anyway; the ordering makes the intent explicit). */
+    suspendLoop?: boolean;
+    /** design/45: the task deliberately suspended at a durable tool gate (capture + abort fired). When set,
+     *  the result is `status:"suspended"` carrying this token/gate — a clean pause, NOT a failure, so it is
+     *  slotted ABOVE the `!final`/aborted branches (slot 8.5: it beats them but yields to a real
+     *  budget/threw failure that happened to coincide). The abort it used sets `final.stopReason="aborted"`
+     *  but does not set `threw`, so it never reaches the `flags.threw` branch. */
+    suspendRef?: {
+        token: import("../checkpoint-store.js").CheckpointToken;
+        gate: import("../checkpoint-store.js").CheckpointGate;
+    };
+    /** design/76 §2.5 (dry-run / shadow) + design/80 D-B (plan-gate): the task deliberately paused at a
+     *  REVIEW-PAUSE gate — `{kind:"needs_review"}` (a profile's dry-run interception produced a predicted
+     *  state-diff a human/judge must REVIEW) OR `{kind:"plan_review"}` (a profile's plan-gate produced a
+     *  proposed PLAN a human must approve/edit/reject). When set, the result is `status:"needs_review"` +
+     *  errorCode `"review.pending"`, carrying this token/gate (keyed off ref-PRESENCE, not `gate.kind`, so it
+     *  serves both review kinds uniformly). It is the DUAL of `suspendRef` but for DIFFERENT semantics (a human
+     *  REVIEW, not a pre-action tool-call APPROVAL), so it has its OWN flag and its OWN assemble slot (8.6,
+     *  between `suspendRef` 8.5 and the aborted branches 9) — **never both set at once** (the commit-side
+     *  discriminant in prepare-task branches on `gate.kind` and sets exactly one). Disjoint from `suspendRef`
+     *  so this branch is reachable: keying status off `suspendRef` alone (reusing it) would report `"suspended"`
+     *  and make this dead code (v4 MAJOR-A). Like `suspendRef`, it used an abort to stop the loop (no `threw`),
+     *  so it never hits the failure branches above. */
+    reviewRef?: {
+        token: import("../checkpoint-store.js").CheckpointToken;
+        gate: import("../checkpoint-store.js").CheckpointGate;
+    };
+}
+/**
+ * Extract a machine-readable code from a thrown error (e.g. `SessionError.code`, a Node error code).
+ * Walks the `cause` chain because the harness wraps lower-level errors (e.g. a `SessionError("conflict")`
+ * append failure surfaces as an `AgentHarnessError("unknown")` whose cause is the real one) — so we
+ * prefer the first specific code over a generic `"unknown"` wrapper.
+ */
+export declare function errorCodeOf(err: unknown): string | undefined;
+/**
+ * Build the final {@link TaskResult} from the run's terminal state. **The errorCode priority chain is a
+ * public contract** (callers `switch` on these strings) — first match wins, in this exact order
+ * (council design/34 red-line #3, do not reorder):
+ *   1. `outputInvalid`  → `"output.invalid"`
+ *   2. degenerate       → `"output.degenerate"` + `salvagedOutput` (design/39; wins over budget/timeout)
+ *   2.5 walltime cutoff → status `"timeout"` + `"limit.timeout"` + `salvagedOutput` (design/130 P2b:
+ *       the brain cut the final turn at the soft deadline and the bounded write-out recovery was
+ *       exhausted — semantically a walltime timeout WITH salvage, not an opaque provider failure)
+ *   3. `budgetHit`      → `"budget.precall"` | `"budget.exceeded"`
+ *   3.5 `suspendLoop`  → `"suspend.loop"` (design/72 §2.2 B — the re-suspend cap; deterministic root
+ *       cause, above `threw` because it owns the abort)
+ *   4. `threw` + timeout → `"limit.timeout"`
+ *   5. `threw` + turns   → `"limit.max_turns"`
+ *   6. `threw` + conflict→ `"conflict"`
+ *   7. `threw` (other)   → `errorCodeOf(threw)`
+ *   8. `blockedReason`   → status `"blocked"` (no errorCode)
+ *   8.5 `suspendRef`     → status `"suspended"` + checkpointToken/gate (design/45 B4 — a deliberate
+ *       durable pause beats the abort it used, but yields to a real budget/threw failure above)
+ *   8.6 `reviewRef`     → status `"needs_review"` + `"review.pending"` + checkpointToken/gate (design/76 §2.5
+ *       — a dry-run post-prediction REVIEW pause; the DUAL of 8.5, between it and the aborts, same red-line:
+ *       a `suspendRef` at 8.5 still wins if both were somehow set, proving slot order — but the commit-side
+ *       discriminant guarantees only one is ever set)
+ *   9. `abortedLive` | stopReason aborted → `"limit.timeout"` | `"limit.max_turns"` | undefined
+ *       (audit A-1: hoisted ABOVE no-final — the loop exits cleanly on abort, so `final` may be a
+ *       normal message or absent; a plain user interrupt carries NO errorCode — switch on `status`)
+ *  10. no `final`        → status `"failed"`
+ *  11. stopReason error  → brain `[code]` prefix (or `"conflict"` from the storage-layer flag)
+ *  12. else              → `"completed"`
+ */
+export declare function assembleResult(spec: TaskSpec, sessionId: string, final: AssistantMessage | undefined, stats: Stats, flags: ResultFlags): TaskResult;
+//# sourceMappingURL=assemble-result.d.ts.map

package/dist/core/runner/assemble-result.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"assemble-result.d.ts","sourceRoot":"","sources":["../../../src/core/runner/assemble-result.ts"],"names":[],"mappings":"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"}

package/dist/core/runner/assemble-result.js

@@ -0,0 +1,250 @@
+import { DEGENERATE_MESSAGE } from "../../brain/repetition.js";
+import { WALLTIME_CUTOFF_MESSAGE } from "../../brain/walltime.js";
+import { extractErrorCode, stripErrorCodePrefix } from "../../brain/errors.js";
+/**
+ * Extract a machine-readable code from a thrown error (e.g. `SessionError.code`, a Node error code).
+ * Walks the `cause` chain because the harness wraps lower-level errors (e.g. a `SessionError("conflict")`
+ * append failure surfaces as an `AgentHarnessError("unknown")` whose cause is the real one) — so we
+ * prefer the first specific code over a generic `"unknown"` wrapper.
+ */
+export function errorCodeOf(err) {
+    let cur = err;
+    let fallback;
+    for (let depth = 0; cur && typeof cur === "object" && depth < 8; depth++) {
+        const code = cur.code;
+        if (typeof code === "string" && code) {
+            if (code !== "unknown") {
+                return code;
+            }
+            fallback ??= code;
+        }
+        cur = cur.cause;
+    }
+    return fallback;
+}
+/**
+ * Strip leaked reasoning tags from text destined for the machine-readable `result`. Some reasoning
+ * models emit thinking inline in `content` (instead of the dedicated reasoning channel), so a
+ * `<think>…</think>` block — or an orphan `</think>` from a partial split — leaks into the result
+ * (F10). This only sanitizes the returned `result`; the persisted transcript keeps the raw content.
+ */
+function stripThinkTags(text) {
+    // 1. Remove well-formed <think>…</think> blocks.
+    let t = text.replace(/<think>[\s\S]*?<\/think>/gi, "");
+    // 2. An orphan </think> with no preceding <think> means the reasoning leaked inline and only the
+    //    closing tag survived — everything up to and including it is reasoning, so drop it.
+    const lower = t.toLowerCase();
+    const close = lower.lastIndexOf("</think>");
+    if (close !== -1 && !lower.slice(0, close).includes("<think>")) {
+        t = t.slice(close + "</think>".length);
+    }
+    // 3. Drop any remaining stray tags.
+    return t.replace(/<\/?think>/gi, "").trim();
+}
+function assistantText(msg) {
+    const text = msg.content
+        .filter((c) => c.type === "text")
+        .map((c) => c.text)
+        .join("");
+    return stripThinkTags(text);
+}
+/**
+ * Build the final {@link TaskResult} from the run's terminal state. **The errorCode priority chain is a
+ * public contract** (callers `switch` on these strings) — first match wins, in this exact order
+ * (council design/34 red-line #3, do not reorder):
+ *   1. `outputInvalid`  → `"output.invalid"`
+ *   2. degenerate       → `"output.degenerate"` + `salvagedOutput` (design/39; wins over budget/timeout)
+ *   2.5 walltime cutoff → status `"timeout"` + `"limit.timeout"` + `salvagedOutput` (design/130 P2b:
+ *       the brain cut the final turn at the soft deadline and the bounded write-out recovery was
+ *       exhausted — semantically a walltime timeout WITH salvage, not an opaque provider failure)
+ *   3. `budgetHit`      → `"budget.precall"` | `"budget.exceeded"`
+ *   3.5 `suspendLoop`  → `"suspend.loop"` (design/72 §2.2 B — the re-suspend cap; deterministic root
+ *       cause, above `threw` because it owns the abort)
+ *   4. `threw` + timeout → `"limit.timeout"`
+ *   5. `threw` + turns   → `"limit.max_turns"`
+ *   6. `threw` + conflict→ `"conflict"`
+ *   7. `threw` (other)   → `errorCodeOf(threw)`
+ *   8. `blockedReason`   → status `"blocked"` (no errorCode)
+ *   8.5 `suspendRef`     → status `"suspended"` + checkpointToken/gate (design/45 B4 — a deliberate
+ *       durable pause beats the abort it used, but yields to a real budget/threw failure above)
+ *   8.6 `reviewRef`     → status `"needs_review"` + `"review.pending"` + checkpointToken/gate (design/76 §2.5
+ *       — a dry-run post-prediction REVIEW pause; the DUAL of 8.5, between it and the aborts, same red-line:
+ *       a `suspendRef` at 8.5 still wins if both were somehow set, proving slot order — but the commit-side
+ *       discriminant guarantees only one is ever set)
+ *   9. `abortedLive` | stopReason aborted → `"limit.timeout"` | `"limit.max_turns"` | undefined
+ *       (audit A-1: hoisted ABOVE no-final — the loop exits cleanly on abort, so `final` may be a
+ *       normal message or absent; a plain user interrupt carries NO errorCode — switch on `status`)
+ *  10. no `final`        → status `"failed"`
+ *  11. stopReason error  → brain `[code]` prefix (or `"conflict"` from the storage-layer flag)
+ *  12. else              → `"completed"`
+ */
+export function assembleResult(spec, sessionId, final, stats, flags) {
+    const taskId = spec.taskId ?? sessionId;
+    const text = final ? assistantText(final) : "";
+    // OTel-aligned alias: promptTokens is already the normalized total input incl. cache (design/17 §11.5).
+    stats.totalInputTokens = stats.promptTokens;
+    // design/80 D-E-core (Part B): the LLM-derived finance taxonomy. `stats.costMicroUsd` is the root-agent
+    // LLM cost PLUS the within-task compaction LLM cost folded into it (recordCompactionUsage) — and NOTHING
+    // else (nested subagent cost lands only in `stats.nested`, never in `costMicroUsd`; memory consolidation is
+    // a separate budget-excluded line set after assembleResult). So:
+    //   llmRoot = costMicroUsd − compaction   (subtract ONLY what was folded in — get the direction right,
+    //                                            Framing-4 had it inverted; do NOT subtract nested — it was
+    //                                            never folded into costMicroUsd, so subtracting under-reports)
+    //   nestedSubagent = stats.nested.costMicroUsd      (separate accumulator)
+    //   compaction     = stats.compactionMicroUsd       (the category Framing-4 missed)
+    //   memoryConsolidation = 0 HERE — filled in runtask AFTER the async consolidation pass sets stats.memory.
+    // `Math.max(0, …)` is a fail-safe clamp: rounding across the per-turn vs aggregated compaction sums can
+    // leave llmRoot a few micro-USD negative; a negative category is a contract violation the test guards
+    // (each ≥ 0), so clamp. NO total−parts `uncategorized` residual: it is algebraically always 0 and can never
+    // fail-loud — the reconcile test instead asserts the parts SUM to the independently-tracked LLM total.
+    const compactionMicroUsd = stats.compactionMicroUsd ?? 0;
+    const nestedSubagentMicroUsd = stats.nested?.costMicroUsd ?? 0;
+    stats.costBreakdown = {
+        llmRootMicroUsd: Math.max(0, stats.costMicroUsd - compactionMicroUsd),
+        nestedSubagentMicroUsd,
+        memoryConsolidationMicroUsd: 0, // filled in runtask alongside stats.memory (AFTER consolidation)
+        compactionMicroUsd,
+    };
+    let status;
+    const result = text;
+    let errorMessage;
+    let errorCode;
+    let blockedReason;
+    let salvagedOutput;
+    let checkpointToken;
+    let checkpointGate;
+    // Degenerate-repetition cutoff (design/39): identified by the shared `DEGENERATE_MESSAGE` the brain
+    // stamps (not a fragile text match). The text the model produced before/at the loop is salvageable —
+    // surface it via `salvagedOutput` so a `failed` task that already did good work isn't a total loss.
+    const isDegenerate = final?.stopReason === "error" && final.errorMessage === DEGENERATE_MESSAGE;
+    // design/130 P2b: the brain's deliberate walltime stream cut, identified by the shared sentinel.
+    const isWalltimeCutoff = final?.stopReason === "error" && final.errorMessage === WALLTIME_CUTOFF_MESSAGE;
+    if (flags.outputInvalid) {
+        // Output-retry cap hit: the model couldn't produce a schema-valid `submit_output` (council OS3).
+        // Wins over the abort it triggered. Distinct, actionable code vs the ambiguous `limit.max_turns`.
+        status = "failed";
+        errorCode = "output.invalid";
+        errorMessage = "model did not produce a valid structured output within the retry limit";
+    }
+    else if (isDegenerate) {
+        // Slotted right after `output.invalid` (council design/39): garbage output wins over budget/timeout
+        // codes, but a schema-invalid output still wins over it. Salvage the turn's text (v1: whole turn).
+        status = "failed";
+        errorCode = "output.degenerate";
+        errorMessage = final?.errorMessage;
+        salvagedOutput = text.trim() || undefined;
+    }
+    else if (isWalltimeCutoff) {
+        // Slot 2.5 (design/130 P2b): the write-out window collapsed — the brain cut the final turn at
+        // the soft deadline and the bounded recovery was exhausted. This IS a walltime timeout (the
+        // task ran out of clock), reported with the salvage the deliberate cut preserved — strictly
+        // more honest than the pre-P2b shape (hard abort mid-call, work lost, orphan reconcile).
+        status = "timeout";
+        errorCode = "limit.timeout";
+        errorMessage = final?.errorMessage;
+        salvagedOutput = text.trim() || undefined;
+    }
+    else if (flags.budgetHit) {
+        // Budget gate wins over the abort it triggered (abort sets `threw`/aborted too).
+        status = "failed";
+        errorCode = flags.budgetHit === "precall" ? "budget.precall" : "budget.exceeded";
+        errorMessage =
+            flags.budgetHit === "precall"
+                ? "estimated cost exceeds maxCostUsd; task not started"
+                : "cumulative cost or tokens exceeded the task budget";
+    }
+    else if (flags.suspendLoop) {
+        // design/72 §2.2 (B): the suspend-loop cap fired — the task suspended too many times (a restart-prone
+        // model re-issuing the gated call every resume). It aborted WITHOUT minting a checkpoint, so it reads
+        // as a terminal failure (a resumable status would loop forever), distinct from a normal `suspended`.
+        // Above `threw` because the cap is the deterministic root cause (it owns the abort), beating any
+        // secondary error the abort might raise.
+        status = "failed";
+        errorCode = "suspend.loop";
+        errorMessage = "task suspended too many times (resume/restart loop) — exceeded the suspend limit";
+    }
+    else if (flags.threw) {
+        status = flags.abortedForTimeout ? "timeout" : "failed";
+        errorMessage = flags.threw instanceof Error ? flags.threw.message : String(flags.threw);
+        // Terminal codes use a dotted namespace (1.37). A lost CAS is detected at the storage boundary
+        // (the harness flattens the error); otherwise fall back to any code on the thrown error itself.
+        errorCode = flags.abortedForTimeout
+            ? "limit.timeout"
+            : flags.abortedForTurns
+                ? "limit.max_turns"
+                : flags.conflict
+                    ? "conflict"
+                    : errorCodeOf(flags.threw);
+    }
+    else if (flags.blockedReason) {
+        status = "blocked";
+        blockedReason = flags.blockedReason;
+    }
+    else if (flags.suspendRef) {
+        // Slot 8.5 (design/45 B4): a deliberate durable suspension. It used an abort to stop the loop
+        // (final.stopReason === "aborted") but did NOT set `threw`/timeout/turns, so the earlier failure
+        // branches were all skipped — intercept here, ABOVE `!final`/aborted, so it surfaces as the
+        // non-terminal `suspended` (resumable) rather than a spurious failed/timeout.
+        status = "suspended";
+        checkpointToken = flags.suspendRef.token;
+        checkpointGate = flags.suspendRef.gate;
+    }
+    else if (flags.reviewRef) {
+        // Slot 8.6 (design/76 §2.5 + design/80 D-B): a deliberate REVIEW pause — a profile's dry-run
+        // interception (a `needs_review` gate, resumed with `dry_run_review`) OR a profile's plan-gate (a
+        // `plan_review` gate, resumed with `plan_review`). Both share this `needs_review` terminal (keyed off
+        // ref-PRESENCE, not `gate.kind` — the resume discriminant tells them apart). Like the `suspendRef` branch
+        // above it used an abort to stop the loop (final.stopReason === "aborted") but did NOT set `threw`/timeout/
+        // turns, so all the failure branches were skipped — intercept here, BELOW `suspendRef` (8.5, which
+        // wins if both were somehow set — but the commit-side discriminant guarantees they're mutually
+        // exclusive) and ABOVE the aborted/!final branches, surfacing the non-terminal, resumable
+        // `needs_review` rather than a spurious failed/suspended.
+        status = "needs_review";
+        errorCode = "review.pending";
+        checkpointToken = flags.reviewRef.token;
+        checkpointGate = flags.reviewRef.gate;
+    }
+    else if (flags.abortedLive || final?.stopReason === "aborted") {
+        // audit A-1: `abortedLive` replaces what the synthetic aborted assistant used to signal — the loop
+        // now exits cleanly on an abort, so `final` can be a perfectly normal tool-call message. Placed
+        // ABOVE `!final` so an abort before any output still reads "run aborted", not "no message".
+        status = flags.abortedForTimeout ? "timeout" : "failed";
+        errorCode = flags.abortedForTimeout ? "limit.timeout" : flags.abortedForTurns ? "limit.max_turns" : undefined;
+        errorMessage = final?.errorMessage ?? (flags.abortedForTurns ? "max turns exceeded" : "run aborted");
+    }
+    else if (!final) {
+        status = "failed";
+        errorMessage = "no assistant message produced";
+    }
+    else if (final.stopReason === "error") {
+        status = "failed";
+        errorMessage = final.errorMessage ?? "model error";
+        // A brain error carries its kind as a `[code]` prefix (auth/network/rate_limit/…) — lift it into
+        // errorCode so the caller can react (auth → fix the key; network/rate_limit → retry/back off)
+        // without string-matching, and strip the prefix from the human message. Both derive from the shared
+        // code list in brain/errors.ts (council finding: an inline copy of the list silently mis-classifies
+        // any future code that's added to the canonical enum but not here).
+        const lifted = extractErrorCode(errorMessage);
+        if (lifted) {
+            errorCode = lifted;
+            errorMessage = stripErrorCodePrefix(errorMessage);
+        }
+        else if (flags.conflict) {
+            // audit A-1 follow-on: a lost optimistic lock used to reach the caller as a THROW (the loop's
+            // failure message re-append also hit the conflict and re-threw). The loop no longer persists
+            // failure messages, so the conflict surfaces as a resolved error message instead — the storage
+            // layer's conflictRef still flagged it; lift it so the service can evict-and-retry on the code.
+            errorCode = "conflict";
+        }
+    }
+    else {
+        status = "completed";
+    }
+    // codex review #4: `compactionMicroUsd` is a run-loop-INTERNAL accumulator (it is NOT on the public
+    // `TaskResult.stats` type — the public compaction figure is `costBreakdown.compactionMicroUsd`). Strip it so it
+    // doesn't leak onto the returned stats as an untyped runtime field.
+    const { compactionMicroUsd: _internalCompaction, ...publicStats } = stats;
+    void _internalCompaction;
+    return { taskId, sessionId, status, ...(flags.model !== undefined ? { model: flags.model } : {}), result: result.trim(), salvagedOutput, blockedReason, errorMessage, errorCode, checkpointToken, checkpointGate, stats: publicStats };
+}
+//# sourceMappingURL=assemble-result.js.map

package/dist/core/runner/assemble-result.js.map

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

package/dist/core/runner/call-cap.d.ts

@@ -0,0 +1,130 @@
+/**
+ * design/130 P1+P2 — wall-clock-aware call capping + graceful-finalize estimation.
+ *
+ * Pure state + math, unit-tested in isolation; the runner owns the wiring:
+ *   - prepare-task creates a {@link CallCapRef} and hands the harness a per-call provider closure;
+ *   - runtask feeds samples (model-call latency/output, tool durations) and the walltime deadline;
+ *   - the loop evaluates the provider right before each provider call (maxTokensPerCall seam).
+ *
+ * Throughput prior is deliberately CONSERVATIVE (codex ④: an optimistic prior yields an oversized
+ * cap and a late finalize — the failure direction is silent). The EWMA takes over from the first
+ * completed call. Cross-run per-model priors (P25/P10 history) are deferred — no history store in
+ * this slice.
+ */
+/** Conservative first-call throughput prior (tokens/sec) — err LOW (codex ④). */
+export declare const CALL_CAP_PRIOR_TOK_PER_SEC = 15;
+/** Fraction of the remaining wall-clock a single call may absorb (leave room for tools + next turn). */
+export declare const CALL_CAP_SAFETY = 0.5;
+/** Never cap below this — a starved reply is worse than none (design/130 §2). */
+export declare const CALL_CAP_MIN_FLOOR = 1024;
+/** Anthropic budget-thinking legal minimum (design/119 semantics: below this, thinking is skipped). */
+export declare const CALL_CAP_THINKING_MIN = 2048;
+/** P2b — fixed write-out cushion bounds (design/130: 60–90s band, budget-proportional under it). */
+export declare const WRITEOUT_CUSHION_MAX_MS = 75000;
+export declare const WRITEOUT_CUSHION_MIN_MS = 10000;
+/** P2b — margin under the hard deadline that the finalize write-out turn itself must respect. */
+export declare const FINAL_WRITEOUT_MARGIN_MS = 5000;
+/**
+ * P2b: the write-out cushion for a given wall-clock budget — 15% of the budget, clamped to the
+ * [10s, 75s] band so tiny budgets aren't swallowed and huge budgets don't over-reserve.
+ */
+export declare function writeoutCushionMs(budgetMs: number): number;
+export interface CallCapState {
+    /** EWMA output-token throughput (tok/sec); undefined until the first completed call. */
+    emaTokPerSec?: number;
+    /** EWMA model-call wall latency (ms). */
+    emaCallMs?: number;
+    /** EWMA tool-execution duration (ms). */
+    emaToolMs?: number;
+    /** P2b: decaying max of model-call wall latency (ms) — tail-aware companion to `emaCallMs`. */
+    peakCallMs?: number;
+    /** P2b: decaying max of tool-execution duration (ms) — tail-aware companion to `emaToolMs`. */
+    peakToolMs?: number;
+    /** Diagnostics for the NEXT brain.call trace row (set by the provider, consumed by the tracer). */
+    last?: {
+        cap: number;
+        remainingMs: number;
+        tokPerSec: number;
+        thinkingSkipped: boolean;
+    };
+}
+/**
+ * Shared mutable ref between prepare-task (creates + closes the provider over it) and runtask
+ * (feeds samples + the deadline + finalize mode).
+ */
+export interface CallCapRef {
+    state: CallCapState;
+    /** Absolute walltime deadline (ms epoch); set by runtask once the task clock starts. */
+    deadlineMs?: number;
+    /** P2: finalize was injected — raise the P1 floor so the write-out turn isn't starved. */
+    finalizeMode?: boolean;
+    /**
+     * The static ceiling the shrink respects (spec.limits.maxOutputTokens ?? current model's
+     * maxTokens). MUTABLE (codex delta ②): a mid-run degrade switch to a smaller model must
+     * TIGHTEN it (runtask's degrade site), or the dynamic cap could exceed the served model's
+     * real limit. Only ever lowered, never raised.
+     */
+    staticCapTokens?: number;
+    /** TB telemetry B2 (service [397]): count of calls whose max_tokens was actually shrunk
+     *  (computeCallCap returned a cap). Incremented by the prepare-task provider closure;
+     *  folded into `stats.mechanisms.capShrinks` at result assembly. */
+    shrinks?: number;
+    /**
+     * P2b: the write-out cushion (ms) — set by runtask alongside `deadlineMs` iff graceful finalize
+     * is on. Presence ARMS the soft execution deadline ({@link softExecDeadlineMs}: brain call cutoff
+     * + foreground tool-timeout clamp) and widens the finalize boundary condition
+     * (`remaining < est + cushion`). Absent ⇒ P2b execution hardening is inert.
+     */
+    cushionMs?: number;
+    /** P2b telemetry: count of foreground shell timeouts clamped to the soft tool deadline
+     *  (incremented by the hands-toolkit clamp notifier; folded into `stats.mechanisms.toolClamps`). */
+    toolClamps?: number;
+    /**
+     * service [405] P0 — the run has OBSERVED self-directed reasoning output (an assistant message
+     * carrying a thinking block). P1's cap math (`walltime × visible-output-throughput × safety`)
+     * is structurally WRONG for such models: reasoning tokens bill against max_tokens but produce
+     * no visible output, so a hard cap decapitates the reasoning mid-thought (TB full-89: 14 calls
+     * with completionTokens == callCap, two solved tasks lost). Once observed, the P1 shrink is OFF
+     * for the rest of the run. The first call is protected by `Model.reasoning` metadata instead —
+     * this runtime flag is the safety net for deployments whose metadata is wrong (TB's deepseek
+     * spec said `reasoning:false`; the model reasons anyway).
+     */
+    reasoningObserved?: boolean;
+}
+/**
+ * P2b: the ABSOLUTE soft execution deadline (ms epoch) for the next call/tool, or undefined when
+ * inert (deadline not armed / graceful finalize off). While working: `deadline − cushion`, so a
+ * long call/tool is cut/clamped with the write-out window intact. Once the finalize write-out turn
+ * is in flight (`finalizeMode`): `deadline − a small margin`, so the final turn may use the cushion
+ * it was reserved.
+ */
+export declare function softExecDeadlineMs(ref: CallCapRef): number | undefined;
+export declare function createCallCapRef(): CallCapRef;
+/**
+ * Feed one completed model call (output tokens + wall latency) into the EWMAs.
+ * Zero-output calls are DISCARDED entirely (codex delta ④): a degenerate / aborted /
+ * usage-missing call returns fast with no work — folding its latency into `emaCallMs` would pull
+ * the finalize estimate optimistic exactly when the provider is misbehaving.
+ */
+export declare function recordCallSample(state: CallCapState, outputTokens: number, latencyMs: number): void;
+/** Feed one completed tool execution into the tool-duration EWMA. */
+export declare function recordToolSample(state: CallCapState, durationMs: number): void;
+/**
+ * P1: compute the per-call output cap from the remaining wall-clock.
+ * Returns undefined when no shrink applies (no deadline yet / already past it — the hard-abort
+ * path owns that — or the derived cap would not shrink below the static ceiling).
+ *
+ * @param thinkingActive whether this run requests budget-thinking (the [1024,2047] contract only
+ *   matters then).
+ */
+export declare function computeCallCap(ref: CallCapRef, nowMs: number, thinkingActive: boolean): number | undefined;
+/**
+ * P2: estimate one more full model-call + tool cycle (ms), with headroom. Conservative by
+ * construction: EWMA samples from THIS run, a fat prior before any samples. P2b: TAIL-AWARE — the
+ * per-leg base is `max(EWMA, decayed peak)`, not the mean alone (a run of small tail calls used to
+ * pull the mean low right before one more heavy call crossed the deadline; the decayed peak keeps
+ * the heavy sample in the estimate for several rounds). Only ever raises the estimate, i.e. only
+ * ever finalizes EARLIER — the safe direction.
+ */
+export declare function estimateCycleMs(state: CallCapState): number;
+//# sourceMappingURL=call-cap.d.ts.map

package/dist/core/runner/call-cap.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"call-cap.d.ts","sourceRoot":"","sources":["../../../src/core/runner/call-cap.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAIH,iFAAiF;AACjF,eAAO,MAAM,0BAA0B,KAAK,CAAC;AAC7C,wGAAwG;AACxG,eAAO,MAAM,eAAe,MAAM,CAAC;AACnC,iFAAiF;AACjF,eAAO,MAAM,kBAAkB,OAAO,CAAC;AACvC,uGAAuG;AACvG,eAAO,MAAM,qBAAqB,OAAO,CAAC;AAkB1C,oGAAoG;AACpG,eAAO,MAAM,uBAAuB,QAAS,CAAC;AAC9C,eAAO,MAAM,uBAAuB,QAAS,CAAC;AAC9C,iGAAiG;AACjG,eAAO,MAAM,wBAAwB,OAAQ,CAAC;AAE9C;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAE1D;AAED,MAAM,WAAW,YAAY;IAC3B,wFAAwF;IACxF,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,yCAAyC;IACzC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,yCAAyC;IACzC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,+FAA+F;IAC/F,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,+FAA+F;IAC/F,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,mGAAmG;IACnG,IAAI,CAAC,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAC;QAAC,eAAe,EAAE,OAAO,CAAA;KAAE,CAAC;CAC1F;AAED;;;GAGG;AACH,MAAM,WAAW,UAAU;IACzB,KAAK,EAAE,YAAY,CAAC;IACpB,wFAAwF;IACxF,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,0FAA0F;IAC1F,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB;;;;;OAKG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB;;wEAEoE;IACpE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;;OAKG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;wGACoG;IACpG,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;;;;;;;OASG;IACH,iBAAiB,CAAC,EAAE,OAAO,CAAC;CAC7B;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,UAAU,GAAG,MAAM,GAAG,SAAS,CAKtE;AAED,wBAAgB,gBAAgB,IAAI,UAAU,CAE7C;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI,CASnG;AAED,qEAAqE;AACrE,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,GAAG,IAAI,CAK9E;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,UAAU,EAAE,KAAK,EAAE,MAAM,EAAE,cAAc,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CA8B1G;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,YAAY,GAAG,MAAM,CAQ3D"}