@sema-agent/core 7.15.0 → 7.17.0

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

@@ -1,37 +1,38 @@
 import type { AssistantMessage } from "../../internal/llm.js";
 import type { NestedUsage, PausedCause, TaskResult, TaskSpec, TerminalCause } from "../types.js";
+import type { HaltConsumption } from "../../internal/harness.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`. */
+    /** Total tool calls executed (one per `tool_start`). Spread into `TaskResult.stats`. */
     toolCalls: number;
-    /** RB-457-a: prompt tokens that MISSED the cache (Anthropic-protocol `input_tokens` shape). */
+    /** Prompt tokens that MISSED the cache (Anthropic-protocol `input_tokens` shape). */
     promptTokens: number;
     cachedTokens: number;
     cacheWriteTokens: number;
     cacheWriteTokensLong: number;
     outputTokens: number;
     cacheHitRate?: number;
-    /** RB-457-a: cache-INCLUSIVE prompt total (`promptTokens + cachedTokens + cacheWriteTokens*`) — the
+    /** Cache-INCLUSIVE prompt total (`promptTokens + cachedTokens + cacheWriteTokens*`) — the
      *  billing/window/hit-rate denominator. Required (not derived) so a new accumulation site that forgets
      *  it fails the type check instead of silently reporting a total short by its own leg. */
     totalInputTokens: number;
     costMicroUsd: number;
-    /** #692 C-b — present (`true`) when at least one model round of this leg reported NO usage frame (the brain's
+    /** Present (`true`) when at least one model round of this leg reported NO usage frame (the brain's
      *  own `usageMissing` mark on the assistant message: an aborted / errored / usage-less provider reply). The
      *  numeric fields stay required and stay what was COUNTED — with this key present they are a LOWER BOUND,
      *  not a measurement ("0 is unknown, not free"). Absent ⇔ every round reported usage. */
     usageMissing?: true;
     nested?: NestedUsage;
-    /** Post-task memory-consolidation usage (design/41); set after the result is assembled. Kept out of
+    /** Post-task memory-consolidation usage; 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
+    /** Human-review burden. 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`).
@@ -65,21 +66,21 @@ export interface Stats {
             segment: string;
         }>;
     };
-    /** design/80 D-E-core (Part B): within-task compaction LLM cost (micro-USD), accumulated by
+    /** 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
+     * 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
-     * permanently 0 since design/157 B19 retired the runner-integrated consolidation pass (field kept — it is
-     * public stats contract; an engine-plane re-mount per design/138 §7 would fill it again).
+     * permanently 0 since B19 retired the runner-integrated consolidation pass (field kept — it is
+     * public stats contract; an engine-plane re-mount would fill it again).
      */
     costBreakdown?: {
         /** Root-agent LLM cost (micro-USD): `costMicroUsd` MINUS the sub-categories already folded into it
@@ -97,29 +98,29 @@ export interface Stats {
         compactionMicroUsd: number;
     };
 }
-/** design/164 — the two cumulative budget ceilings a task can trip. Tokens outrank cost when both are
+/** The two cumulative budget ceilings a task can trip. Tokens outrank cost when both are
  *  over at the same boundary. */
 export type BudgetAxis = "tokens" | "cost";
 /**
  * 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).
+ * loop and result assembly (exported so it's grep-able and tests can construct it).
  */
 export interface ResultFlags {
     threw: unknown;
-    /** #499 — the run's ENGINE-minted identity (`Prepared.runId`), echoed verbatim on
+    /** The run's ENGINE-minted identity (`Prepared.runId`), echoed verbatim on
      *  `TaskResult.runId`. Pure pass-through on every terminal: assembly neither mints nor derives it
      *  (a caller reaching assembly at all has completed prepare, so the value exists), and a
      *  hand-constructed flags bag without one simply produces a result without one. */
     runId?: string;
-    /** design/99 MF-25: the EFFECTIVE (resolved) model id that served the task — echoed on `TaskResult.model`. */
+    /** The EFFECTIVE (resolved) model id that served the task — echoed on `TaskResult.model`. */
     model?: string;
-    /** RB-368: some spend was accounted while the serving model had NO configured price table
+    /** Some spend was accounted while the serving model had NO configured price table
      *  (no `RunnerDeps.pricing` entry, no `Model.cost`). The numeric total is then a fabricated
      *  undercount — `stats.costMicroUsd`/`costBreakdown` are OMITTED from the public result instead of
      *  reporting a 0 indistinguishable from "declared free". The internal accumulator (budget gate's
      *  coordinate) is untouched. */
     unpricedSpend?: boolean;
-    /** RB-430-a (design/101 §E19): prepare-time rewind disclosures to echo on `TaskResult.rewindNotes`.
+    /** Prepare-time rewind disclosures to echo on `TaskResult.rewindNotes`.
      *  Pure pass-through — assembly neither adds nor filters (a rewind that FAILED never reaches here; it
      *  throws at prepare and lands in the `threw` slot as a terminal errorCode). */
     rewindNotes?: TaskResult["rewindNotes"];
@@ -134,37 +135,36 @@ export interface ResultFlags {
      *  path the terminal is `completed`, and this is what tells that completion apart from a natural
      *  one — the model did not finish; the person stopped it and the run awaits their direction). */
     haltedOnUserRejection?: boolean;
-    /** design/373 (#504) — a `TaskStream.halt` (the bare user interrupt, CC Esc form) was accepted
-     *  while the run was live; echoed on `TaskResult.haltedByUser`. Pure pass-through on every
-     *  terminal (the sibling `haltedOnUserRejection` law: the fact is about the leg that ran) PLUS
-     *  one status decision it owns (slot 9.7 below): a run whose ONLY stop was this halt reads
-     *  `"completed"`, never the `!final` failure and never the aborted terminal — whether the halt
-     *  landed before the model said anything (empty result) or cut a turn whose partial text the
-     *  brain kept (that text IS the result). The person stopped the run, which is the verb working,
-     *  not a defect. A REAL abort/limit that also fired still owns the terminal above it. */
-    userHalted?: boolean;
-    /** design/174 final-round: call ids of answered-but-never-collected questions, echoed on
+    /** the harness's STATEMENT of what the run's halt did (see `HaltConsumption`):
+     *  the loop's report that the halt's cut settled the final turn, and/or the boundary consult that
+     *  stopped the loop for the halt's request. This is the ONLY input to `TaskResult.haltedByUser`
+     *  (`haltConsumed`, halt-attribution.ts) and to slot 9.7 — the assembly never infers causation from the
+     *  final's shape or from the verb's acceptance. A halt that was accepted but consumed nothing (the run
+     *  ended for its own reason first) leaves this empty: the original terminal stands and the seat is
+     *  NOT signed (the settle lane mints `task.halt_unconsumed` for it). */
+    haltConsumption?: HaltConsumption;
+    /** Call ids of answered-but-never-collected questions, echoed on
      *  `TaskResult.strandedHumanAnswers`. Pure pass-through; empty/absent ⇒ the field is omitted. The
      *  optional `onError` alert is NOT the disclosure — this mandatory result face is. */
     strandedHumanAnswers?: TaskResult["strandedHumanAnswers"];
-    /** RB-439-a: the run's remote-workspace lifecycle failures, echoed on `TaskResult.remoteEnvFailures`.
+    /** The run's remote-workspace lifecycle failures, echoed on `TaskResult.remoteEnvFailures`.
      *  Pure pass-through (assembly neither adds nor filters) and INDEPENDENT of the status/errorCode chain:
      *  a refused `suspendVM` still ends the task exactly the way it did before — this only stops the eleven
      *  distinct codes from arriving as one anonymous `limits.max_turns_exceeded`. Empty/absent ⇒ the field is omitted. */
     remoteEnvFailures?: TaskResult["remoteEnvFailures"];
-    /** #240 (design/199 v1.1) — the run's effective read posture (resolved face + normalized deny
+    /** The run's effective read posture (resolved face + normalized deny
      *  additions), echoed on `TaskResult.effectiveReadFace` / `.effectiveReadDenyPatterns`. Pure
      *  pass-through (assembly neither adds nor filters) and INDEPENDENT of the status/errorCode chain:
      *  the posture is a fact about the leg that ran, whatever terminal it reached — a post-completion
      *  spawner folds it stricter-wins into follow-on legs; every other consumer may ignore it. */
     effectiveReadFace?: TaskResult["effectiveReadFace"];
     effectiveReadDenyPatterns?: TaskResult["effectiveReadDenyPatterns"];
-    /** design/178 v2 §2.3 (件①) — the memory-visibility observation, echoed on
+    /** The memory-visibility observation, echoed on
      *  `TaskResult.effectiveMemoryScopes`. Pure pass-through on every terminal, same law as the
      *  read-posture seats above: present iff prepare completed (the memory-less states are their own
      *  values — absence means only "prepare never ran to completion"). */
     effectiveMemoryScopes?: TaskResult["effectiveMemoryScopes"];
-    /** #327 — the leg's effective reasoning resolution, echoed on `TaskResult.effectiveReasoning`.
+    /** The leg's effective reasoning resolution, echoed on `TaskResult.effectiveReasoning`.
      *  Pure pass-through on every terminal (same law as the read-posture seats): the SAME object the
      *  `reasoning.resolved` trace frame carried (runtask resolves once per leg — two faces, one mint);
      *  absent when thinking was off/unset for the leg, so the key is omitted. */
@@ -188,7 +188,7 @@ export interface ResultFlags {
      *  and the run takes the completed floor. Absent/false = the abort's ordinary reading. */
     answerSettled?: boolean;
     budgetHit?: "exceeded" | "precall";
-    /** design/164 — which budget ceiling the hit belongs to. Set together with {@link budgetHit} at every
+    /** Which budget ceiling the hit belongs to. Set together with {@link budgetHit} at every
      *  site that records one; it picks the terminal code (`limits.max_tokens_exceeded` vs
      *  `limits.max_cost_exceeded`), so a hit without an axis would be an unattributable terminal. */
     budgetAxis?: BudgetAxis;
@@ -198,7 +198,7 @@ export interface ResultFlags {
      *  the loop folded it into a text-only failure message, so the typed code rides this flag. */
     gitCoreOverBudget?: boolean;
     outputInvalid?: boolean;
-    /** design/72 §2.2 (B): a re-suspend was refused because the task already suspended `maxSuspends` times
+    /** 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). */
@@ -278,13 +278,13 @@ export declare function terminalCauseOf(final: AssistantMessage | undefined, sta
 /**
  * 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):
+ * (red-line #3, do not reorder):
  *   1. `outputInvalid`  → `"output.invalid"`
- *   2. degenerate       → `"output.degenerate"` + `salvagedOutput` (design/39; wins over budget/timeout)
+ *   2. degenerate       → `"output.degenerate"` + `salvagedOutput` (wins over budget/timeout)
  *   3. `budgetHit`      → `"limits.max_tokens_exceeded"` | `"limits.max_cost_exceeded"` (by `budgetAxis`;
  *       the pre-call estimate rejection and the after-spend crossing share the code — the distinction
  *       lives in `errorMessage`, not in a second code)
- *   3.5 `suspendLoop`  → `"suspend.loop"` (design/72 §2.2 B — the re-suspend cap; deterministic root
+ *   3.5 `suspendLoop`  → `"suspend.loop"` (the re-suspend cap; deterministic root
  *       cause, above `threw` because it owns the abort)
  *   4. `threw` + walltime → `"limits.max_walltime_exceeded"`
  *   5. `threw` + turns   → `"limits.max_turns_exceeded"`
@@ -293,18 +293,20 @@ export declare function terminalCauseOf(final: AssistantMessage | undefined, sta
  *   8. `blockedReason`   → status `"blocked"` (no errorCode)
  *   8.5 `paused`         → status by the pause's registry row (`suspended` for an approval / resource
  *       slice / platform pause, `needs_review` + `"review.pending"` for a plan or dry-run review) +
- *       checkpointToken/gate (design/45 B4 — a deliberate durable pause beats the abort it used, but
+ *       checkpointToken/gate (a deliberate durable pause beats the abort it used, but
  *       yields to a real budget/threw failure above)
  *   9. `abortedLive` | stopReason aborted → `"limits.max_walltime_exceeded"` | `"limits.max_turns_exceeded"` | 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`),
- *       EXCEPT when the aborted `final` is the bare halt's OWN cut artifact (`haltOwnsAbortedFinal`),
+ *       EXCEPT when the aborted `final` is the bare halt's OWN cut artifact (`haltOwnsAbortedFinal`: the
+ *       loop reported the halt's cut settled the final turn — never shape inference),
  *       and EXCEPT when the answer had already settled (`answerSettled`: a clean `"stop"` final, not
  *       partial) — a stop landing on the run's tail cuts no work, so the run falls through to 12
  *       (`completed`, the answer as `result`, no `limits.*` code for the axis; three axes, one law)
- *   9.7 `userHalted` + (no `final` | the halt's own aborted `final`) → status `"completed"` (#504: a
- *       bare user halt — the verb working, not a defect; below the aborts on purpose, a real
- *       abort/limit that also fired owns the terminal and the halt rides as the pass-through seat)
+ *   9.7 halt CONSUMED (`haltConsumed(flags.haltConsumption)`) + (no `final` | the halt's own aborted
+ *       `final`) → status `"completed"` (a bare user halt — the verb working, not a defect; below the
+ *       aborts on purpose, a real abort/limit that also fired owns the terminal and the halt rides as
+ *       the pass-through seat; an accepted-but-unconsumed halt never reaches this slot)
  *  10. no `final`        → status `"failed"`
  *  11. stopReason error  → brain `[code]` prefix (or `"conflict"` from the storage-layer flag)
  *  12. else              → `"completed"`

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

@@ -1,6 +1,7 @@
 import { isDegenerateCutMessage } from "../../brain/terminal-cause.js";
 import { extractErrorCode, stripErrorCodePrefix } from "../../brain/errors.js";
 import { terminalProjection } from "./terminal-projection.js";
+import { haltConsumed } from "./halt-attribution.js";
 const SALVAGE_ELIGIBLE_TERMINALS = new Set([
     "output.degenerate",
     "limits.max_tokens_exceeded",
@@ -47,7 +48,7 @@ export function answerSettled(final, continuationCut = false) {
 export function terminalCauseOf(final, stats, flags) {
     let terminal;
     let apiFailure;
-    const haltOwnsAbortedFinal = flags.userHalted === true &&
+    const haltOwnsAbortedFinal = flags.haltConsumption?.turnCut === "halt" &&
         final?.stopReason === "aborted" &&
         !flags.abortedLive &&
         flags.abortedForTimeout !== true &&
@@ -103,7 +104,7 @@ export function terminalCauseOf(final, stats, flags) {
         const code = flags.abortedForTimeout ? "limits.max_walltime_exceeded" : flags.abortedForTurns ? "limits.max_turns_exceeded" : undefined;
         terminal = { kind: "failed", ...(code !== undefined ? { code } : {}), message: final?.errorMessage ?? (flags.abortedForTurns ? "max turns exceeded" : "run aborted") };
     }
-    else if (flags.userHalted === true && (!final || haltOwnsAbortedFinal)) {
+    else if (haltConsumed(flags.haltConsumption) && (!final || haltOwnsAbortedFinal)) {
         terminal = { kind: "completed" };
     }
     else if (!final) {
@@ -155,7 +156,7 @@ export function assembleResult(spec, sessionId, final, stats, flags) {
     const result = text;
     let salvagedOutput;
     const { terminal, apiFailure } = terminalCauseOf(final, stats, flags);
-    const { status, errorCode } = terminalProjection(terminal);
+    const { errorCode } = terminalProjection(terminal);
     if (errorCode !== undefined && SALVAGE_ELIGIBLE_TERMINALS.has(errorCode)) {
         salvagedOutput = text.trim() || undefined;
     }
@@ -164,6 +165,6 @@ export function assembleResult(spec, sessionId, final, stats, flags) {
     void _internalCompaction;
     if (flags.unpricedSpend)
         delete publicStats.costMicroUsd;
-    const stampHaltedByUser = flags.userHalted === true && status !== "suspended" && status !== "needs_review";
+    const stampHaltedByUser = haltConsumed(flags.haltConsumption);
     return { taskId, ...(flags.runId !== undefined ? { runId: flags.runId } : {}), sessionId, terminal, ...(flags.model !== undefined ? { model: flags.model } : {}), result: result.trim(), salvagedOutput, ...(apiFailure !== undefined ? { apiFailure } : {}), ...(retryAfterMs !== undefined ? { retryAfterMs } : {}), ...(flags.rewindNotes !== undefined && flags.rewindNotes.length > 0 ? { rewindNotes: flags.rewindNotes } : {}), ...(flags.editedFiles !== undefined && flags.editedFiles.length > 0 ? { editedFiles: flags.editedFiles } : {}), ...(flags.haltedOnUserRejection === true ? { haltedOnUserRejection: true } : {}), ...(stampHaltedByUser ? { haltedByUser: true } : {}), ...(flags.remoteEnvFailures !== undefined && flags.remoteEnvFailures.length > 0 ? { remoteEnvFailures: [...flags.remoteEnvFailures] } : {}), ...(flags.strandedHumanAnswers !== undefined && flags.strandedHumanAnswers.length > 0 ? { strandedHumanAnswers: flags.strandedHumanAnswers } : {}), ...(flags.effectiveReadFace !== undefined ? { effectiveReadFace: flags.effectiveReadFace } : {}), ...(flags.effectiveReadDenyPatterns !== undefined && flags.effectiveReadDenyPatterns.length > 0 ? { effectiveReadDenyPatterns: flags.effectiveReadDenyPatterns } : {}), ...(flags.effectiveMemoryScopes !== undefined ? { effectiveMemoryScopes: flags.effectiveMemoryScopes } : {}), ...(flags.effectiveReasoning !== undefined ? { effectiveReasoning: flags.effectiveReasoning } : {}), stats: publicStats };
 }

package/dist/core/runner/checkpoint-scope.d.ts

@@ -5,19 +5,19 @@
  * the driver (the restore fold) and runtask (the resume rung) reach DOWN for the same names. Pure: a constant and two
  * string functions.
  */
-/** design/77 §4.4: the multi-tenant scope used when a durable suspend fires for an IRREVERSIBLE tool in an
+/** The multi-tenant scope used when a durable suspend fires for an IRREVERSIBLE tool in an
  *  unattended deployment that did NOT opt into `durableApproval` (so there is no caller-supplied scope). The
  *  checkpoint carries this scope; resume reads it back from the checkpoint (`cp.scope`), so it is
  *  self-consistent without needing the original `TaskSpec`. Kept distinct from any tenant key to make an
  *  unattended irreversible suspend auditable as such. */
 export declare const DEFAULT_IRREVERSIBLE_SCOPE = "irreversible";
 /**
- * design/153 §7.1 — the SINGLE derivation of a durable-suspend checkpoint's scope (both gate mint
+ * The SINGLE derivation of a durable-suspend checkpoint's scope (both gate mint
  * sites + the bg-watcher park lane's expire compensation/arbitration consume THIS; a re-derived copy
  * that drifted was the exact bug the park tests caught — expire against the wrong scope silently
  * no-ops). `|| DEFAULT` (not `??`): an EMPTY-string principal must not become a shared scope bucket.
  *
- * RB-75 (2026-07-25, red probe): that rule is stated twice in this file and was enforced on ONE of the two
+ * That rule is stated twice in this file and was enforced on ONE of the two
  * inputs — the principal half used `||`, the `durableApproval.scope` half used `??`, so an empty string
  * arriving through the scope field (a config-centre / env lookup that came back blank is the realistic
  * source) sailed through as the literal scope `""`. Two different tenants both landed in that one bucket,
@@ -33,7 +33,7 @@ export declare function checkpointScopeOf(spec: {
     principal?: string;
 }): string;
 /**
- * rescan C5 — the ONE spelling of the placement fields' empty-string discipline: `""` is absence
+ * The ONE spelling of the placement fields' empty-string discipline: `""` is absence
  * wearing clothes (the resume entry's principal-rung posture), and every placement read that must
  * treat it so — the resume rung's two sides (runtask), the restore fold's seed and the suspend
  * stamp — goes through THIS helper, so three sites cannot drift into three readings. Deliberately

package/dist/core/runner/clock-and-limits.d.ts

@@ -18,7 +18,7 @@ import type { PlatformLimitReason } from "../checkpoint-store.js";
 import type { TaskSpec } from "../types.js";
 import type { Prepared } from "./contracts.js";
 /**
- * design/164 — the LIMIT-APPROACH frames, the successor to the retired deadline-nudge family. Two facts
+ * The LIMIT-APPROACH frames, the successor to the retired deadline-nudge family. Two facts
  * make them a different mechanism, not a rename:
  *  - they are measured in BUDGET (the tightest armed axis's fill ratio), not in wall-clock, so they need
  *    no throughput estimate and cannot mis-fire on a starved event loop;
@@ -36,7 +36,7 @@ export declare function limitApproachFrames(index: 0 | 1, axis: string, percent:
 /**
  * Resolve the effective turn cap. `undefined` = no turn cap; `0` (explicit) = unbounded.
  *
- * design/164: this is now a pure read of what the caller wrote. The two clauses it used to carry —
+ * This is now a pure read of what the caller wrote. The two clauses it used to carry —
  * "a wall-clock bound was set, so drop the turn cap" and "neither was set, so apply the engine's
  * safety net" — are both gone: the axes no longer interact (each binds on its own), and there is no
  * engine-side net to apply. A task with no `maxTurns` has no turn ceiling.
@@ -88,7 +88,7 @@ export declare function awaitChargeWithSlowDisclosure<T>(charge: Promise<T>, onS
  */
 export declare function raceUntilDeadline<T>(p: Promise<T>, deadline: number): Promise<T | typeof GOVERNANCE_READ_STALLED>;
 /**
- * design/164 件四/件五 — the TYPED terminal for an external stop cause that could NOT be suspended durably.
+ * The TYPED terminal for an external stop cause that could NOT be suspended durably.
  * Carried on `rs.limits.platformTerminal` and adopted as the run's `threw`, so the caller reads the cause
  * on `TaskResult.errorCode` (`errorCodeOf` lifts `.code`) instead of the anonymous error an abort produces.
  * `retryAfterMs` rides the error object because a wait hint has no `TaskResult` seat — a host reads it from

package/dist/core/runner/compaction-call-options.d.ts

@@ -5,7 +5,7 @@ import type { Context } from "../../internal/llm.js";
 import { type ToolResultStore } from "../tool-result-store.js";
 import type { Prepared } from "./contracts.js";
 /**
- * REF-A2 (car R11) — the maybeCompact call arguments that MUST be assembled identically on all three
+ * The maybeCompact call arguments that MUST be assembled identically on all three
  * of runtask's compaction lanes (turn boundary / prompt-too-long recovery / end-of-task).
  *
  * Those lanes carried three hand-copied assemblies whose own comments said "must not silently
@@ -30,100 +30,36 @@ import type { Prepared } from "./contracts.js";
  */
 export declare function buildWorkingFileAttachments(spec: TaskSpec, prepared: Prepared): MaybeCompactOptions["workingFileAttachments"];
 /**
- * #500 — `MaybeCompactOptions.contextInstructionFiles`: the seat that delivers the deployment's own
- * instruction-file content (the CLAUDE.md family) to the SUMMARIZER, assembled once here and spread
- * on all three lanes. Without it the compaction boundary is the one place a long task loses the
- * standing instructions every other turn has been reading — and it loses them exactly where the
- * summary REPLACES the transcript that carried them, so the loss is durable.
+ * `MaybeCompactOptions.contextInstructionFiles`: the deployment's instruction-file content (the CLAUDE.md
+ * family) delivered to the SUMMARIZER, assembled once here and spread on all three lanes — the compaction
+ * boundary is where the summary REPLACES the transcript that carried those instructions.
  *
- * WHICH BYTES, and why the neighbours are not candidates. `Prepared.projectInstructionContent` =
- * the RAW loader text (`ProjectMemoryLoad.content`, exactly the string prepare-task feeds
- * `composeMemoryBlock(projectMem, "project")`), captured beside the existing `instructionSources`
- * capture under the SAME non-blank predicate that composes the project layer:
- *   · the assembled `memoryBlock` is NOT a candidate. It is the memory ENGINE's composed layers —
- *     bytes the model itself authored in-band this session through the memory tools — with the
- *     project layer appended at the tail. The seat's contract is host/systemPrompt tier and says in
- *     terms: never from tool output, model text, or any other in-band channel. Handing
- *     model-authored bytes an envelope whose preamble tells the summarizer they may instruct it is
- *     the laundering shape, not a purity nit. (Mechanically moot too — `memoryBlock` is a
- *     prepare-task local and never reaches `Prepared`.)
- *   · the COMPOSED project block is not it either, and this one is checkable rather than a
- *     judgement: `contextInstructionFilesSection` neutralizes the whole authority family
- *     (ENGINE_AUTHORITY_ENVELOPE_TAGS) over its payload, and `user_memory`/`scope` ARE in that
- *     family — so feeding a composed block would have the engine rewrite the tags of its own
- *     composition. Raw text in, one fence at the mint.
- *   · `prepared.instructionSources` carries path + contentHash only, by design (core never learns a
- *     file-name policy), so it cannot serve this seat at all.
- *
- * PROVENANCE, stated plainly because "the host supplies it" is the easy half of the truth. On this
- * engine the value is REPOSITORY-CONTROLLED text: the loading block one file over calls a CLAUDE.md
- * of unknown authorship untrusted in so many words, the MAIN lane's own framing tells the model it is
- * "repository-controlled DATA, not instructions to obey", and this seat hands the same bytes to the
- * summarizer with instruction standing for the summarization task. Delivery THROUGH a host callback
- * is not host AUTHORSHIP: a prior agent, or anyone who can land a commit, can write a
- * "## Compact Instructions" section, and the mint's neutralization stops tag breakout — not a
- * sentence asking for a fact to be left out of the summary that replaces the transcript.
- * Why it is nevertheless this value: the seat's own contract names this path ("hosts pass the same
- * instruction-file content their prompt assembly mounts... on the runner path"), the parity form this
- * channel exists to reach reads the user's and the project's instruction files at every boundary with
- * exactly this standing, and the two alternatives are worse for reasons above rather than better.
- * The standing is also narrower than the framing gap suggests — the section's preamble scopes it to
- * guidance about HOW to summarize and classifies the rest as background — and a deployment that does
- * not want it has two exits that need no code: do not wire the loader, or return content it vouches
- * for. Recorded as an open design candidate rather than built here, because it is a contract change
- * and not a wiring one: a SEPARATE deployment-vouched summarization-instructions seat, leaving
- * repository-derived context at data tier.
- *
- * RULING ① — BOTH summary forms, no per-form split. Fork eligibility is decided per pass INSIDE
- * maybeCompact (main-model-only, recorded-request-present, not lossy), so a call site cannot say
- * "independent form only"; the closest approximation — pass the seat only when `prepared.compModel`
- * is set, since an independent compaction model has no main prefix to fork — leaves the hole the
- * wrong way round: the configuration it does NOT cover (no compaction model) is precisely the one
- * where a fork degrades mid-pass to the independent form, which would then run WITHOUT the files.
- * Feeding both forms closes that case by construction, and the library face already handles the fork
- * half (the section rides the APPENDED instruction message, never the cached prefix, so the fork's
- * whole economic point is untouched).
- *
- * RULING ② — no new size knob. The bound is the library's own `fitContextInstructionFilesSection`
- * (independent form: cap against the compaction model's window, disclosed elision, and a complete
- * yield when not even the framing fits). Its three KNOWN LIMITS are accepted here KNOWINGLY, as the
- * pre-condition of this wiring rather than something it discovered: a token-dense payload (CJK,
- * emoji) can pass a chars-domain fit and still overflow the gateway's tokenizer; an unknown
- * `contextWindow` leaves the section unbounded (the conversation clamp declines to guess there too);
- * and the FORK form cannot fit at all — its bound is a prompt-too-long that degrades ONCE to the
- * independent form, which the engine's own note records as real but NOT total (an oversize rejection
- * the classifier cannot read as prompt-too-long returns terminally instead).
- *
- * HOW BIG THAT ACCEPTANCE ACTUALLY IS — measured, because the sentence above is easy to read more
- * comfortably than it deserves. The fitted form is NOT the default path: when a fork is eligible and
- * the model answers in its envelope, the fork IS the pass, and its section is delivered WHOLE at any
- * size. The independent form — the only one that fits — runs when there is no fork to take or the
- * fork's answer did not conform. Both facts are pinned in the REF-A2 suite (a 55 KB payload: whole on
- * the fork, elided on the independent fallback). And when a limit does bite, the failure is not a
- * quiet degradation: the section is a FIXED part of the request, the reactive retry loop may drop
- * only CONVERSATION groups, so a request the SECTION overflowed cannot converge and the boundary
- * fails — the task loses that compaction (or that prompt-too-long recovery, or its end-of-task
- * summary) rather than sending a shorter one. The exposure is what the wiring widened: this was
- * previously reachable only by hosts calling the library directly, and is now reachable by every
- * deployment that wires `loadProjectMemory` with a large instruction file and an unknown or small
- * window. Making the section participate in the retry loop is the structural answer; it is a change
- * to that loop's contract, tracked at the library face, and a runner-side knob would only move the
- * decision to a place with less information.
- *
- * WHAT IT COSTS, measured rather than rounded: every deployment that wires `loadProjectMemory` now
- * sends its instruction-file content plus EXACTLY 716 chars of framing (the preamble and the fence)
- * on EVERY summarization request, both forms, once per pass — where a real project instruction file
- * in this family runs to tens of KB, so the payload, not the framing, is the bill. The number is
- * pinned in the REF-A2 suite against the engine's own renderer, so a preamble edit shows up as a
- * changed assertion rather than as prose drifting away from the code it describes.
- * Deployments that never wired the loader pay nothing: the key is absent, not
- * `undefined`, so their requests are byte-identical to the pre-wiring shape on the independent and
- * UPDATE passes (the FORK form appends its ~860-char authority clause with or without the seat, and
- * always did).
+ * Contract:
+ *  - Bytes = `Prepared.projectInstructionContent`, the RAW loader text captured under the same non-blank
+ *    predicate that composes the project layer. Not the assembled `memoryBlock` (model-authored in-band
+ *    bytes would gain an instructing envelope), not the COMPOSED project block (`contextInstructionFilesSection`
+ *    neutralizes the whole authority family, `user_memory`/`scope` included), not `instructionSources`
+ *    (path + hash only). Raw text in, one fence at the mint.
+ *  - Provenance: REPOSITORY-CONTROLLED text delivered through a host callback — delivery is not authorship;
+ *    the mint's neutralization stops tag breakout, not a sentence asking for an omission. Two no-code exits
+ *    for a deployment that does not want it: do not wire the loader, or return vouched content. A separate
+ *    deployment-vouched summarization-instructions seat is an open design candidate, not built here.
+ *  - Both summary forms, no per-form split: fork eligibility is decided per pass inside maybeCompact, and the
+ *    form NOT covered by a `compModel`-gated split is exactly the fork that degrades mid-pass to the
+ *    independent form; the section rides the APPENDED instruction message, never the cached prefix.
+ *  - No new size knob: the bound is `fitContextInstructionFilesSection` (independent form only). Its three
+ *    known limits are accepted knowingly: a token-dense payload can pass a chars-domain fit and still overflow;
+ *    an unknown `contextWindow` leaves the section unbounded; the FORK form cannot fit and degrades ONCE. When
+ *    a limit bites the boundary FAILS (the section is a fixed request part the retry loop cannot drop) — the
+ *    task loses that compaction rather than sending a shorter one; making the section participate in the
+ *    retry loop is a library-face contract change, tracked there.
+ *  - Cost: instruction-file content + exactly 716 chars of framing on every summarization request, both
+ *    forms, once per pass (pinned in the REF-A2 suite). Deployments that never wired the loader pay nothing:
+ *    the key is ABSENT, so their requests are byte-identical to the pre-wiring shape.
  */
 export declare function contextInstructionFilesOption(prepared: Prepared): Partial<Pick<MaybeCompactOptions, "contextInstructionFiles">>;
 /**
- * design/169-A — the CC-form fork seam, assembled identically on all three lanes (REF-A2): the
+ * The CC-form fork seam, assembled identically on all three lanes (REF-A2): the
  * summary request forks the main lane's latest real request (recorded by prepare-task's provider
  * shim) instead of re-serializing the conversation into an independent full-price request.
  * `maybeCompact` consults the accessor per pass and only when the summary model IS the main model;
@@ -135,7 +71,7 @@ export declare function contextInstructionFilesOption(prepared: Prepared): Parti
  * clearStale content blanking, the aggregate tool-result/media caps, the orphan sweep), that
  * projection is missing history the summary would PERMANENTLY replace — measured live: a fork of a
  * trimmed request loses the fact-survival suite's fact; a fork of a clearStale'd request summarizes
- * `[tool result cleared …]` markers (独立复审 HIGH,已修). That guard lives at the RECORDING side
+ * `[tool result cleared …]` markers. That guard lives at the RECORDING side
  * (prepare-task arms `requestLossyRef` per request build; a lossy request records `undefined`), so
  * every lane degrades to the independent form — which reads the FULL session — automatically.
  *
@@ -145,12 +81,12 @@ export declare function contextInstructionFilesOption(prepared: Prepared): Parti
  */
 export declare function forkContextOption(prepared: Prepared, disable: boolean): Pick<MaybeCompactOptions, "forkContext">;
 /**
- * RB-31 — compaction-boundary center-candidate adoption. Absent (an empty object, NOT a
+ * Compaction-boundary center-candidate adoption. Absent (an empty object, NOT a
  * `centerAdoption: undefined` key) = restate as before; a boundary re-pin hashes the same artifact
  * identity on every lane.
  */
 export declare function centerAdoptionOption(prepared: Prepared): Partial<Pick<MaybeCompactOptions, "centerAdoption">>;
-/** design/169-F defaults (object-present, field-absent). Named per the magic-number rule. */
+/** Defaults (object-present, field-absent). Named per the magic-number rule. */
 export declare const STALE_OFFLOAD_DEFAULT_KEEP_RECENT_PER_TOOL = 3;
 export declare const STALE_OFFLOAD_DEFAULT_MIN_SAVINGS_CHARS = 2000;
 /** Resolved (validated, defaulted) knob — see {@link resolveStaleToolResultOffload}. */
@@ -159,7 +95,7 @@ export interface ResolvedStaleToolResultOffload {
     minSavingsChars: number;
 }
 /**
- * design/169-F — validate + default the spec knob. Fail-loud on non-finite/negative/fractional
+ * Validate + default the spec knob. Fail-loud on non-finite/negative/fractional
  * values (a computed NaN silently re-defaulting is the ||0-fold this repo's engineering code bans);
  * `undefined` knob ⇒ `undefined` (feature completely off).
  */
@@ -171,14 +107,14 @@ export declare function resolveStaleToolResultOffload(knob: StaleToolResultOfflo
  *  crossing the staleness line as newer same-tool results arrive) rewrites that message's bytes
  *  once, invalidating the provider cache from that position for one request — a bounded,
  *  once-per-result break the `minSavingsChars` floor is there to amortize.
- *  Deliberately NOT `offloadPagebackHint` (the design/30 preview's hint): that hint's wording is a
+ *  Deliberately NOT `offloadPagebackHint` (the preview's hint): that hint's wording is a
  *  function of the LIVE reachable-tool set, and this pointer is re-derived per request — a mid-run
  *  ToolSearch activation would flip its bytes and break the very prefix stability this file pins.
- *  The reader is named by its real mounted name (独立复审 MED,已修: `read_tool_result` is a
+ *  The reader is named by its real mounted name (`read_tool_result` is a
  *  retired alias — a model following it burned a rejected call first). */
 export declare function buildStaleOffloadPointer(toolName: string, ref: string, chars: number): string;
 /**
- * design/169-F — the request-side projection: replace STALE same-tool results with byte-stable
+ * The request-side projection: replace STALE same-tool results with byte-stable
  * pointers. "Stale" = has ≥ `keepRecentPerTool` NEWER results of the same tool name in this request
  * — a monotone predicate (a result never gains "recency" back), so a replacement decision made on
  * one request holds on every later one and re-derivation is deterministic: no run-scoped mutable
@@ -194,7 +130,7 @@ export declare function buildStaleOffloadPointer(toolName: string, ref: string,
  * tool-call ids carry no cross-turn uniqueness contract), readable back via `read_tool_result`.
  */
 export declare function projectStaleToolResults(context: Context, cfg: ResolvedStaleToolResultOffload, store: ToolResultStore, sessionId: string, 
-/** Run-scoped cache of refs already persisted by THIS run (独立复审 MED,已修): without it the
+/** Run-scoped cache of refs already persisted by THIS run: without it the
  *  write-once `put` is still re-issued every request — on the file backend that is a
  *  write-then-discard round-trip per stale result per turn. Caller owns the Set's lifetime. */
 writtenRefs: Set<string>): Promise<Context>;

package/dist/core/runner/compaction-knobs.d.ts

@@ -1,5 +1,5 @@
 /**
- * The run loop's three compaction knobs (design/393 S5): the consecutive-failure breaker trip, the anti-thrash
+ * The run loop's three compaction knobs: the consecutive-failure breaker trip, the anti-thrash
  * regrowth factor and the effective-compaction epsilon. They were declared at the turn-boundary lane and the driver
  * reached DOWN for them; the recovery lane (the forced-compaction pass the prompt-too-long and guard-chain arms
  * share) reads the same three, and a lane may not name a sibling lane — so the three values sank to the machinery
@@ -9,12 +9,12 @@
  * lane, and the prefix would put it under the phase-api gate and the run-lanes glob.
  */
 /**
- * §17.4 (design/64 GAP-25): stop attempting within-task compaction after this many CONSECUTIVE
+ * §17.4: stop attempting within-task compaction after this many CONSECUTIVE
  * failures in one task — a never-recovering summary gateway must not burn an API call at every turn
  * boundary (CC: MAX_CONSECUTIVE_AUTOCOMPACT_FAILURES = 3). Reset on any success; an open breaker also
  * skips the end-of-task attempt in `finish()` (teardown unaffected). Per-task scope.
  *
- * RB-190 — this used to say "a flaky/never-recovering gateway", and the word `flaky` was not true. Because
+ * This used to say "a flaky/never-recovering gateway", and the word `flaky` was not true. Because
  * any success zeroes the counter, a gateway that alternates never reaches three CONSECUTIVE failures and
  * the breaker never opens; it keeps paying for a call at every failed boundary, indefinitely.
  *
@@ -37,7 +37,7 @@ export declare const MAX_CONSECUTIVE_COMPACTION_FAILURES = 3;
  */
 export declare const COMPACTION_REGROWTH_FACTOR = 1.5;
 /**
- * design/84 Seam C reuse guard (b): a compaction that frees fewer than this many (structural) tokens is
+ * A compaction that frees fewer than this many (structural) tokens is
  * treated as NO-EFFECTIVE-COMPACTION and does NOT raise the anti-thrash floor. Guards against a reused
  * provider summary (or a pathological LLM summary) that reclaims no headroom yet suppresses the next real
  * summary by inflating the floor to trigger×factor.

package/dist/core/runner/compaction-seams.d.ts

@@ -2,17 +2,17 @@ import type { MaybeCompactOptions } from "../auto-compaction.js";
 import type { TaskSpec } from "../types.js";
 import type { Prepared, RunnerDepsSeat } from "./contracts.js";
 /**
- * design/84 Seam C — the cost-optimization compaction options threaded into BOTH `maybeCompact` call
+ * The cost-optimization compaction options threaded into BOTH `maybeCompact` call
  * sites (within-task turn boundary + `finish()`). All three fields come from `RunnerDeps` (a trusted
  * FUNCTION seam — never `TaskSpec`, which is serializable/durable-resumable/untrusted-caller). The
  * Runner OWNS the consecutive-reuse counter (`prepared.compactionReuseRef`) so the
  * `maxConsecutiveProviderReuse` drift guard spans the whole task across both sites: it FEEDS the current
  * count in as `consecutiveProviderReuse`, and {@link recordCompactionReuse} updates it from the result.
  * Returns `undefined` when no provider is wired (so the call site spreads nothing → byte-identical to
- * the pre-design/84 behavior).
+ * the prior behavior).
  */
 export declare function seamCCompactionOptions(runner: RunnerDepsSeat, prepared: Prepared): Pick<MaybeCompactOptions, "summaryProvider" | "onCompaction" | "maxConsecutiveProviderReuse" | "consecutiveProviderReuse"> | undefined;
-/** design/134 §3.2 — resolve the pre/postCompact lifecycle callbacks (whole-slot `spec.hooks ??
+/** Resolve the pre/postCompact lifecycle callbacks (whole-slot `spec.hooks ??
  *  deps.hooks`, same resolution as the stop hook) and wrap each in a SWALLOW+TRACE shell before
  *  threading them into maybeCompact. The wrapper owns the observability half of the R3 MED contract
  *  (maybeCompact swallows defensively too, but has no sink): a throwing callback is reported via
@@ -20,7 +20,7 @@ export declare function seamCCompactionOptions(runner: RunnerDepsSeat, prepared:
  *  reported as ignored (maybeCompact enforces the ignore — blocking a compaction the provider/trim
  *  layer already demanded would kill the run). */
 export declare function compactionHookOptions(runner: RunnerDepsSeat, spec: TaskSpec, sessionId: string, trigger: "auto" | "manual" | "forced", 
-/** #281 件A — the leg's identity envelope, spread onto both compaction contexts by the wrappers
+/** The leg's identity envelope, spread onto both compaction contexts by the wrappers
  *  below (the compaction module builds its contexts below the runner and cannot know the leg;
  *  the wrapper is the runner's seam). Every runner call site supplies `prepared.hookIdentity`;
  *  optional only so a context built without a leg stays honestly identity-less. */
@@ -33,7 +33,7 @@ seatBound?: {
     timeoutMs: number;
     signal?: AbortSignal;
 }): Pick<MaybeCompactOptions, "trigger" | "preCompact" | "postCompact">;
-/** design/84 Seam C — fold a finished compaction's `reused` flag into the run-scoped consecutive-reuse
+/** Fold a finished compaction's `reused` flag into the run-scoped consecutive-reuse
  *  counter: a reused (provider) summary increments it, a real (LLM) summary resets it to 0. A no-op
  *  compaction (`compacted:false`) leaves the counter untouched. No-op when no provider is wired. */
 export declare function recordCompactionReuse(runner: RunnerDepsSeat, prepared: Prepared, comp: {