@sema-agent/core 5.57.0 → 5.58.0

package/dist/core/types.d.ts

@@ -29,8 +29,18 @@ export interface StaleToolResultOffloadOptions {
  * - `advisor` — the strong "teacher" a cheap student escalates to (`runWithTeacher`).
  * - `classifier` — the auto-mode permission classifier (a roster-cheap tier; falls back
  *   `summarize → default`, tier default `flash` on tier-expanded catalogs).
+ * - `consolidate` — the memory-consolidation distillation driver (design/376). Falls back to
+ *   `summarize` and then REFUSES LOUDLY — deliberately never to `default`: one consolidation run
+ *   is a whole-library read (~10⁵ prompt tokens), so silently escalating to the most expensive
+ *   main-task model is the bad-value-silence family, not a convenience. The divergence from the
+ *   classifier family's `→ default` tail is calibrated on call volume: a classifier resolves one
+ *   short classification, this role resolves a full-library batch. An explicit
+ *   `roles.consolidate = <main model>` is a legal deployment choice; the summarize hop is kept
+ *   because a deployment that declared a cheap summarize tier has already made the cost choice
+ *   this role wants (note the summarize DEFAULT rationale — prompt-cache forking — does not
+ *   apply here: consolidation is an offline independent request with no shared prefix).
  */
-export type ModelRole = "default" | "summarize" | "subagent" | "team" | "synthesize" | "advisor" | "verifier" | "classifier";
+export type ModelRole = "default" | "summarize" | "subagent" | "team" | "synthesize" | "advisor" | "verifier" | "classifier" | "consolidate";
 /**
  * A role's model: a `ModelRef`, or a config object that pins a `model`, **selects** one by
  * capability/price (`select`, design/11 Layer 2), and/or sets a default `thinking` level.
@@ -146,7 +156,7 @@ export interface ToolSpec<TParams extends TSchema = TSchema> {
     aliases?: string[];
     description: string;
     /**
-     * R2 双形轴(clay 2026-07-18 裁):the CLASSIC-profile variant of {@link description}. CC 2.1.212
+     * R2 双形轴(2026-07-18 裁):the CLASSIC-profile variant of {@link description}. CC 2.1.212
      * keys its tool descriptions on `LT(model_id)` (simple short form vs classic long form); sema's
      * counterpart is {@link TaskSpec.promptProfile} — default "simple" (what CC serves every BYOM
      * model id). When the run resolves to "classic" and this field is present, it REPLACES
@@ -207,7 +217,7 @@ export interface ToolSpec<TParams extends TSchema = TSchema> {
         aliases?: readonly string[];
         contentOrigin?: ToolContentOrigin;
     }>;
-    /** [1245] — approval display projection (see AgentTool.approvalPreview): pure args→display value
+    /** approval display projection (see AgentTool.approvalPreview): pure args→display value
      *  for human approval surfaces; clamped + throw-swallowed by the gate; never adjudication input. */
     approvalPreview?: (args: unknown) => unknown;
     /**
@@ -219,7 +229,7 @@ export interface ToolSpec<TParams extends TSchema = TSchema> {
      */
     agentModels?: readonly string[];
     /**
-     * [876] core half — PER-TASK agent-roster rebuild seam, filled ONLY by `createSubagentTool`
+     * core half — PER-TASK agent-roster rebuild seam, filled ONLY by `createSubagentTool`
      * (deployment-authored tools leave it unset). The delegation tool's roster is a mount-time SNAPSHOT
      * baked into its parameter enum/description (see the `SubagentToolOptions` snapshot note), so per-task
      * additions ({@link TaskSpec.agents}) cannot mutate the mounted instance — `prepareTask` instead calls
@@ -423,7 +433,7 @@ export interface ToolSpec<TParams extends TSchema = TSchema> {
      */
     modelGate?: string;
     /**
-     * Tool contract identity (campaign S2, prompt-assembly protocol §7): declares the EXECUTION
+     * Tool contract identity (stage S2, prompt-assembly protocol §7): declares the EXECUTION
      * CONTRACT this tool implements, independent of its presentation text. `defineTool` attaches it
      * to the materialized tool via the catalog side-table (identity follows the OBJECT, never the
      * wire name — a caller tool shadowing a built-in name never inherits the core contract). Omitted
@@ -453,7 +463,7 @@ export type ToolReturn = string | {
     /** Hint the agent to stop after this tool batch. */
     terminate?: boolean;
     /**
-     * RB-211(黑板 [1870] C3,已修 — root-cause widening): a `ToolSpec.execute` can RETURN a failure
+     * RB-211 (root-cause widening): a `ToolSpec.execute` can RETURN a failure
      * receipt instead of throwing (teaching errors that carry structured `details`, e.g. an
      * unrecoverable-but-informative rejection). Before this field existed, `ToolReturn` had NO
      * isError channel at all — `defineTool`'s wrapper builds a fresh `{content,details,terminate}`
@@ -463,7 +473,7 @@ export type ToolReturn = string | {
      * produced `isError:false` on the model-facing `toolResult`, in BOTH the live per-turn path and
      * the durable-resume path — a returned rejection was structurally unable to look like anything
      * other than success. Omitted/false = success (matches `AgentToolResult.isError`'s own
-     * `[1331]③` convention exactly — this is that SAME field, finally reachable from a `ToolSpec`).
+     * convention exactly — this is that SAME field, finally reachable from a `ToolSpec`).
      */
     isError?: boolean;
 };
@@ -501,7 +511,7 @@ export interface NestedUsageAccum {
     turns: number;
     tasks: number;
     costMicroUsd: number;
-    /** codex batch-4 F3 (RB-368 reaches the nested face): true once ANY delegated leg reported no cost —
+    /** batch-4 F3 (RB-368 reaches the nested face): true once ANY delegated leg reported no cost —
      *  the summed `costMicroUsd` is then a priced-subtotal, not a total, and the publish site must go
      *  ABSENT instead of impersonating one. REQUIRED so every seeding/snapshot site is tsc-forced to
      *  carry knownness alongside the number it qualifies. */
@@ -525,13 +535,13 @@ export interface ToolExecuteContext {
     /** Publish provenance companion of {@link centerArtifactDigest}. */
     centerSourceRevision?: string;
     /**
-     * design/147 S2a (codex R2) — the SPAWNING run's sessionId (trusted internals chain, same seat as
+     * design/147 S2a — the SPAWNING run's sessionId (trusted internals chain, same seat as
      * {@link parentTaskId}). Sibling resolution/delivery needs the parent's SESSION axis too: a
      * session-scoped sibling registers with owner = the parent's sessionId, which the parent's taskId
      * alone cannot satisfy when the two differ.
      */
     parentSessionId?: string;
-    /** δ 批 [1498]⑦/A-3 — the ROOT host session of the delegation tree (see RunInternals.rootSessionId:
+    /** A-3 — the ROOT host session of the delegation tree (see RunInternals.rootSessionId:
      *  fixed point `ctx.rootSessionId ?? ctx.sessionId` at every spawn). Absent for a top-level run
      *  (its OWN sessionId is the root). */
     rootSessionId?: string;
@@ -561,7 +571,7 @@ export interface ToolExecuteContext {
             ticket: import("./task-registry.js").ParkedClaimTicket;
             outcome: import("./checkpoint-store.js").ResumeOutcome;
             /**
-             * [1596] the CROSS-PROCESS re-supply seat for the checkpoint's opaque parent constraints.
+             * the CROSS-PROCESS re-supply seat for the checkpoint's opaque parent constraints.
              * A checkpoint minted under inherited parent-policy constraints records only
              * `requiresParentConstraint` (live ToolPolicy/onAsk closures cannot persist); the same-process
              * drive is re-supplied automatically from the Runner's in-memory `parentConstraintRegistry`,
@@ -572,7 +582,7 @@ export interface ToolExecuteContext {
              * config-driven) passes it here; the drive threads it into `resumeStream(..., internals)`,
              * where the recorded-count shape check still applies verbatim (a partial/mismatched re-supply
              * is rejected — this seat never widens, it only reopens the documented re-supply channel to
-             * the parked-decide lane). Absent ⇒ exactly the pre-[1596] behavior.
+             * the parked-decide lane). Absent ⇒ exactly the previous behavior.
              *
              * One entry kind is NOT a policy the deployment authored: a hook-wired parent contributes a
              * PreToolUse SCREENING entry (issue #33), whose policy the engine mints. Rebuild it with the
@@ -622,21 +632,21 @@ export interface ToolExecuteContext {
      */
     roster?: import("../agents/roster-store.js").RosterStore;
     /**
-     * [1345] fork source-store fix — the HOST Runner's session-fork face, Runner-filled read-only.
+     * fork source-store fix — the HOST Runner's session-fork face, Runner-filled read-only.
      * The fork arm's source session lives in the store of the Runner RUNNING this task; `opts.runner`
      * is the CHILD-EXECUTION runner, which a deployment may deliberately split (server's subRunner) —
      * forking through it queried an empty store and every fork missed ("source session not found").
      * The fork arm prefers this face and falls back to `opts.runner.sessions.fork` (single-runner
      * deployments unchanged).
      *
-     * ZERO-ARG by design (codex 1350 F2): the source session id AND principal are bound in the Runner's
+     * ZERO-ARG by design: the source session id AND principal are bound in the Runner's
      * closure at injection — a mounted third-party tool holding this context can only branch THIS task's
      * own session under THIS task's principal, never copy a foreign session by supplying its id. The
      * returned handle's `release` is scoped to the just-created branch through the same closure, so
      * failure cleanup releases through the store that OWNS the branch (`opts.runner.sessions.release`
      * may be a different store entirely).
      *
-     * Store contract (codex 1350 F1): the branch is created in the HOST store, but the fork child still
+     * Store contract: the branch is created in the HOST store, but the fork child still
      * executes on `opts.runner` with `requireExistingSession: true` — if the two runners do not share
      * session backing, the child run fails LOUD ("refusing a silent fresh run") instead of silently
      * running an empty session under the forked id. Split-runner deployments must share session backing
@@ -814,7 +824,7 @@ export interface ToolExecuteContext {
      * user. Runner-filled (NOT a tool argument). Undefined when the task carries no clientContext.
      */
     clientContext?: TaskSpec["clientContext"];
-    /** [1043]③/[1044]② (codex F3) — the parent's tool-face controls ({@link TaskSpec.excludeTools} /
+    /**  — the parent's tool-face controls ({@link TaskSpec.excludeTools} /
      *  {@link TaskSpec.deferTools}), inherited down the delegation tree like `principal` (Runner-filled,
      *  read-only): a scenario-wide roster must not be escapable by delegating to a child that remounts
      *  the excluded tool. Children merge these with their own spec values (union — tighten-only). */
@@ -838,7 +848,7 @@ export interface ToolExecuteContext {
      *  tool-face controls (Runner-filled): a classic-profile parent's children speak classic too
      *  unless the child spec says otherwise (child spec wins — profile is presentation, not policy). */
     promptProfile?: "simple" | "classic";
-    /** [1347]② — the parent's declared extra file-tool roots ({@link TaskSpec.additionalDirectories}),
+    /** the parent's declared extra file-tool roots ({@link TaskSpec.additionalDirectories}),
      *  inherited down the delegation tree (Runner-filled, copy-at-spawn): a deployment that widened the
      *  fs fence (e.g. the scratchpad host lane) widened it for the TASK, and a delegated child doing the
      *  same work hit `path_not_in_root` on the very directory the parent could write. Same trust tier as
@@ -848,7 +858,7 @@ export interface ToolExecuteContext {
      *  the same rule (Runner-filled, copy-at-spawn): a child doing the parent's work needs the same
      *  read whitelist, and MUST NOT have it silently widened into a write grant in transit. */
     additionalReadDirectories?: readonly string[];
-    /** [1347]② — the parent's environment facts ({@link TaskSpec.envFacts}), inherited down the
+    /** the parent's environment facts ({@link TaskSpec.envFacts}), inherited down the
      *  delegation tree (Runner-filled, copy-at-spawn): the sandbox binding (profile/egress/scratchpad)
      *  is a DEPLOYMENT property, not a per-task one — a child in the same sandbox needs the same facts
      *  (its env block renders the scratchpad section; its root fence admits the scratchpad dir). */
@@ -865,7 +875,7 @@ export interface ToolExecuteContext {
      */
     memoryPersistenceCapable?: boolean;
     /**
-     * [893]④a — the parent task's per-model auth hook ({@link TaskSpec.getApiKeyAndHeaders}), inherited
+     * the parent task's per-model auth hook ({@link TaskSpec.getApiKeyAndHeaders}), inherited
      * verbatim down the delegation tree like `principal`/`clientContext` (Runner-filled, read-only, NEVER
      * a model/tool argument). Without this seat a per-task agent pinned to a cross-provider model (its own
      * apiKeyEnv) spawned a child whose run had NO auth hook — the brain silently fell back to the global
@@ -1686,15 +1696,15 @@ export interface TaskSpec {
      */
     requireExistingSession?: boolean;
     /**
-     * 黑板 [1909]⑧/[1910]/[1911](cli/server 商定,per-request 语义,无异议)— this SUBMISSION is one-shot:
+     * Per-request semantics — this SUBMISSION is one-shot:
      * no later turn exists in which an async background notification could land (the archetypal case is a
      * headless `sema -p` invocation, whose process exits once this turn ends). Per-request rather than
      * per-connection/per-process on purpose: "does this particular submission expect to be steered/continued"
      * is a property of the submission, not of the channel it arrived on — a persistent connection can still
      * mix interactive and one-shot submissions, which a connection-level flag could not express.
      *
-     * Currently consumed by the `RunWorkflow` tool's guidance text only (RB-215 candidate ①, blackboard
-     * [1870] C6): a workflow started from a one-shot submission is told to actively block-wait via
+     * Currently consumed by the `RunWorkflow` tool's guidance text only (RB-215 candidate ①):
+     * a workflow started from a one-shot submission is told to actively block-wait via
      * `TaskOutput({ block: true })` before ending its turn, instead of the default "end your turn, you will
      * be notified" guidance — the latter is actively wrong here (BGB drilldown case 2, `../sema-test/bench-bg/
      * intel/drilldown-C101-B401-20260727.md`: a model that followed that exact guidance lost background
@@ -1900,10 +1910,10 @@ export interface TaskSpec {
      */
     tools?: ToolSpec[];
     /**
-     * [1043]③ per-scenario tool ROSTER (true unmount, NOT a permission gate): wire names listed here
+     * per-scenario tool ROSTER (true unmount, NOT a permission gate): wire names listed here
      * are removed from the mounted tool set AFTER assembly — their schemas never reach `tools[]`
      * (unlike a policy deny, which gates calls but still ships the schema bytes every request —
-     * measured at zero token savings, [1040]②a). Exact wire-name match (aliases resolve to their
+     * measured at zero token savings). Exact wire-name match (aliases resolve to their
      * canonical wire name at mount, so list the canonical name). Unknown names are ignored (a
      * center-distributed roster may cover tools this deployment doesn't mount). The injected
      * ToolSearch cannot be excluded (it mounts after this filter, only when deferred tools exist).
@@ -1912,7 +1922,7 @@ export interface TaskSpec {
      */
     excludeTools?: string[];
     /**
-     * [1044]② (clay ruling B) per-request DEFERRED disclosure for ALREADY-MOUNTED tools (built-ins
+     * Per-request DEFERRED disclosure for ALREADY-MOUNTED tools (built-ins
      * included — `ToolSpec.defer` only covers caller specs): wire names listed here ship as
      * lightweight placeholders (name + one-line hint, schema bytes OFF the cache prefix) and are
      * activated on demand via the injected ToolSearch (design/36 materialization — prefix untouched).
@@ -1996,7 +2006,7 @@ export interface TaskSpec {
      */
     deferSelfResolve?: boolean;
     /**
-     * R2 双形轴(clay 2026-07-18 裁): which prompt-profile face this task speaks — "simple" (default;
+     * R2 双形轴(2026-07-18 裁): which prompt-profile face this task speaks — "simple" (default;
      * CC 2.1.212's short-form tool descriptions + lean system sections, what CC serves every non-claude
      * model id) or "classic" (the long-form face, ≈ CC 4.x-era wording — switchable per task/model,
      * e.g. serving classic to a model that scores better on it; center distribution rides this field).
@@ -2005,13 +2015,13 @@ export interface TaskSpec {
      */
     promptProfile?: "simple" | "classic";
     /**
-     * [876] core half — PER-TASK custom sub-agents. Same shape as the boot injection point
+     * core half — PER-TASK custom sub-agents. Same shape as the boot injection point
      * ({@link RunnerDeps.agents} / `SubagentToolOptions.agents`): full {@link AgentDefinition} objects
      * (the shell resolves agent files / frontmatter into this shape; `model` is the already-resolved
      * real model ref passed through — core carries no model-word vocabulary). When set (non-empty),
      * `prepareTask` REBUILDS the mounted delegation tool (via {@link ToolSpec.withAgents}) so its roster
      * is the UNION of the boot roster and these definitions — a same-name per-task definition WINS over
-     * the boot one. Validation contract ([901] revision of the [876] posture, dual-leg verified against
+     * the boot one. Validation contract (revision of the posture, dual-leg verified against
      * upstream): an `allowTools` entry naming a tool that does not exist is ITEM-FILTERED at spawn (the
      * agent stays listed and delegable; the only host disclosure is a prepare-time HEURISTIC advisory
      * via `RunnerDeps.onError` phase `"config"` for entries unknown to the parent's assembled roster —
@@ -2041,7 +2051,7 @@ export interface TaskSpec {
     /** How `ask` decisions resolve for this task (headless auto-deny by default). Overrides `RunnerDeps.onAsk`. */
     onAsk?: import("./tool-policy.js").OnAsk;
     /** Content-ask seam (design/64 §5): routes an AskUserQuestion tool call to a real human/UI. When set, the
-     *  AskUserQuestion tool is mounted (one of the delivery faces in the [884] criterion — see
+     *  AskUserQuestion tool is mounted (one of the delivery faces in the criterion — see
      *  {@link interactiveTools}). Overrides `RunnerDeps.onQuestion`. Distinct from `onAsk` (permission). */
     onQuestion?: import("./ask-question.js").OnQuestion;
     /** LSP code-intelligence seam (design/64 §13.1): when set, the `lsp` tool is mounted and routed to this
@@ -2320,7 +2330,7 @@ export interface TaskSpec {
      */
     enablePlanMode?: boolean;
     /**
-     * [884] Interactive-tool mounting override (CC 2.1.207/209 parity: AskUserQuestion / ExitPlanMode /
+     * Interactive-tool mounting override (CC 2.1.207/209 parity: AskUserQuestion / ExitPlanMode /
      * EnterPlanMode share one `isEnabled` gate — in non-interactive mode without an SDK permission-prompt
      * tool the tool is NOT offered at all, so the model never asks into the void). sema's automatic
      * criterion (this knob unset): a human-facing tool mounts only when the deployment has SOME face that
@@ -2427,7 +2437,7 @@ export interface TaskSpec {
          *  tasks trampling each other's temp files and project-dir pollution. Unset ⇒ no section rendered. */
         scratchpadDir?: string;
         /**
-         * [1451]/[1452]③ B-half — PER-LANE resume-continuity facts, rendered ONLY on a durable-resume leg so
+         * B-half — PER-LANE resume-continuity facts, rendered ONLY on a durable-resume leg so
          * the model reasons honestly about what survived the suspension. DEPLOYMENT-supplied per its own lane
          * capability (a VM snapshot lane preserves processes; an ssh park-only workspace usually keeps /tmp;
          * a rebuilt container loses both) — core hardcodes NO lane table and renders NOTHING when a field is
@@ -2457,7 +2467,7 @@ export interface TaskSpec {
      */
     limits?: TaskLimits;
     /**
-     * Config-catalog override declarations (clay ruling 2026-07-19, anti-chaos contract): a HOST that
+     * Config-catalog override declarations (ruled 2026-07-19, anti-chaos contract): a HOST that
      * overrides a recommended knob at its own layer (env cap, adapter flag, harness default) declares
      * it here — key + value + REASON — so the override rides the `config.assembled` trace with
      * provenance `host-declared` instead of being invisible to forensics. Advisory observability
@@ -2491,7 +2501,7 @@ export interface TaskSpec {
      * released (throwaway semantics restored — a retained session never dangles to the store's 7-day TTL).
      * `run_in_background` children are OUT OF SCOPE (no handle, no retain — r1-M3; the bg lane's resume needs
      * durable support and is a separate item). Resume is reachable only while the parent run lives (the
-     * ledger is run-scoped, not a durable registry — codex-B3).
+     * ledger is run-scoped, not a durable registry).
      */
     retainSubagentSessions?: boolean | {
         ttlMs?: number;
@@ -3283,7 +3293,7 @@ export interface TaskResult {
          *  accumulator rather than an alias. Optional BY DESIGN, like every usage field on this stats
          *  face: undefined means the gateway reported no usage (and pre-3.0.0 persisted rows never had
          *  it) — the event-face `turn_end.usage.totalInputTokens` is required because there the whole
-         *  `usage` object is already conditional ([2285] item 3: intentional asymmetry, not a gap). */
+         *  `usage` object is already conditional (intentional asymmetry, not a gap). */
         totalInputTokens?: number;
         /** Completion (output) tokens summed over the task's turns. */
         outputTokens?: number;
@@ -3292,7 +3302,7 @@ export interface TaskResult {
         /** Authoritative (and only) cost figure: **integer micro-USD** (1e-6 USD), computed in core from
          *  injected pricing — integer to avoid float-accumulation error in billing. (design/157 B19: the
          *  float-USD twin was removed; divide by 1e6 at the display edge if you need USD.)
-         *  **ABSENT when any spend was unpriced** (RB-368 [2076]): the serving model had neither a
+         *  **ABSENT when any spend was unpriced** (RB-368): the serving model had neither a
          *  `RunnerDeps.pricing` entry nor a `Model.cost` declaration — an unpriced run reports NO cost
          *  rather than a fabricated 0, so "no price table" stays distinguishable from "declared free"
          *  (an explicit all-zero `Model.cost` still reports 0). `costBreakdown` is omitted with it. */
@@ -3431,7 +3441,7 @@ export interface TaskResult {
          * LLM total: `llmRootMicroUsd + compactionMicroUsd === costMicroUsd` and the fully-reconciled
          * spend is `costMicroUsd + nested.costMicroUsd` — `costMicroUsd` deliberately EXCLUDES nested
          * subagent cost (it lands in `nested`, see assemble-result.ts), so `nestedSubagentMicroUsd` sits
-         * OUTSIDE the costMicroUsd identity, not inside it ([2026] 细账批实测纠偏: the previous wording
+         * OUTSIDE the costMicroUsd identity, not inside it (measured correction: the previous wording
          * `llmRoot + nested + compaction === costMicroUsd` only held when nested was 0).
          * (`memoryConsolidationMicroUsd` is a separate, budget-excluded line, permanently 0 since the
          * runner-integrated consolidation pass was retired — design/157 B19 — and NOT part of any identity).
@@ -3441,7 +3451,7 @@ export interface TaskResult {
         costBreakdown?: {
             /** Root-agent LLM cost (micro-USD) = `costMicroUsd − compactionMicroUsd` (the sub-category folded into
              *  it). NOT minus nested — nested cost is never folded into `costMicroUsd` (it lands in `nested`).
-             *  ⚠️ APPROXIMATE on a multi-slice `resource_limit` RESUME (design/80 D-E-core, codex review #3): the
+             *  ⚠️ APPROXIMATE on a multi-slice `resource_limit` RESUME (design/80 D-E-core): the
              *  durable resource ledger persists only the AGGREGATE prior spend, not its compaction subtotal, so
              *  prior slices' compaction folds in HERE rather than into `compactionMicroUsd`. The TOTAL (`costMicroUsd`)
              *  stays exact; only this llmRoot-vs-compaction split is per-leg-approximate across resource slices. */
@@ -3480,7 +3490,7 @@ export interface TaskEventIdentity {
     eventId?: string;
     parentToolCallId?: string;
     /**
-     * design/122 S2 (codex-M4 name: the `WorkflowRun.sourceTaskId` family, NOT a second `taskId` — that
+     * design/122 S2 (the `WorkflowRun.sourceTaskId` family, NOT a second `taskId` — that
      * field already exists on `task_progress` and a duplicate would bite consumers) — the ORIGINATING task's
      * canonical id (`spec.taskId ?? sessionId`), stamped ONLY on the content events of a task running AS A
      * SUB-AGENT (same condition as {@link parentToolCallId}). A consumer of the C1 forward channel
@@ -3490,7 +3500,7 @@ export interface TaskEventIdentity {
      */
     sourceTaskId?: string;
     /**
-     * design/151 S2 (MED-10 live-tail, [1498]⑦ server half) — the BACKGROUND agent's `a*` registry
+     * design/151 S2 (MED-10 live-tail) — the BACKGROUND agent's `a*` registry
      * handle, stamped on every event a background child's lane forwards up the host `onForwardEvent`
      * channel (content deltas, tool events, progress). THE live-tail routing key: a serving layer
      * pipes "what is agent aXX doing right now" straight off the host forward stream — no uuid→a*
@@ -3572,7 +3582,7 @@ export interface ToolActivity {
     phase: "start" | "end";
     toolCallId: string;
     toolName: string;
-    /** [843]④a — wall-clock stamp (epoch ms, `Date.now()` read at the emitting Runner where the frame is
+    /** wall-clock stamp (epoch ms, `Date.now` read at the emitting Runner where the frame is
      *  minted). Carried on BOTH beats: the `start` beat stamps the moment the tool call began, the `end`
      *  beat the moment it settled — so a consumer derives per-call duration (`end.at − start.at`) and
      *  inter-call idle (an `end.at` → the NEXT `start.at`). Additive/optional: frames recorded by older
@@ -3582,7 +3592,7 @@ export interface ToolActivity {
      *  single most salient input ABBREVIATED (command→name, path→basename, url→origin+path) + SECRET-SCRUBBED +
      *  truncated (~80 code points). Set on `phase: "start"`. NOT the full args object, and NOT `redactHostLeaks`
      *  (that over-redacts the path the monitor needs); the abbreviation + scrub is the leak boundary since the value
-     *  is persisted + SSE-forwarded (codex-reviewed). See `primaryActivityArg`. */
+     *  is persisted + SSE-forwarded. See `primaryActivityArg`. */
     arg?: string;
     /** Set on `phase: "end"` — whether the tool call errored. */
     isError?: boolean;
@@ -3799,7 +3809,7 @@ export type TaskEvent = ({
      */
     truncated?: boolean;
     /**
-     * RB-210(黑板 [1870] C2,已修) — present iff {@link truncated}: the TRUE original size (characters) of
+     * RB-210 — present iff {@link truncated}: the TRUE original size (characters) of
      * the content this event's {@link output} was degraded from — for a string result, the string's own
      * length; for a non-string result (a blocks array), the SUM of each block's own true size (a text
      * block's `.text.length`; an image/document block's `.data.length`, i.e. its base64 payload) — never
@@ -3819,7 +3829,7 @@ export type TaskEvent = ({
     totalChars?: number;
 } & TaskEventIdentity) | ({
     /**
-     * RB-126 / blackboard [1669]⑥ — context occupancy at a compaction boundary, emitted on EVERY
+     * RB-126 — context occupancy at a compaction boundary, emitted on EVERY
      * boundary (not only when a compaction fires). The three numbers are the engine's own trigger
      * inputs, verbatim: `usedTokens > compactAtTokens` IS the predicate `shouldCompact` evaluates, so a
      * consumer's "context is N% full" indicator and the moment compaction actually fires can never
@@ -3880,7 +3890,7 @@ export type TaskEvent = ({
 } & TaskEventIdentity) | ({
     /** design/99 MF-18: a compaction boundary (or, since design/119 #1, mid-turn when the prompt-too-long recovery force-compacts between a failed request and its retry). `trigger` = what caused it: `"auto"` (the context-threshold
      *  auto-compaction), `"manual"` (the `TaskStream.compact` / `/compact` path), or `"forced"` (RB-398-b
-     *  [2105]: the prompt-too-long recovery and trim-pressure lanes — compaction was not optional; the
+     *  the prompt-too-long recovery and trim-pressure lanes — compaction was not optional; the
      *  hook layer's `PreCompactContext.trigger` always had this third state and the wire now carries the
      *  SAME value the hooks saw instead of flattening it to `"auto"`. Additive value space — a consumer
      *  switching on auto/manual keeps its exact old behavior). `tokensBefore` = the
@@ -3940,7 +3950,7 @@ export type TaskEvent = ({
     phaseDurations?: import("./auto-compaction.js").CompactionPhaseDurations;
 } & TaskEventIdentity) | ({
     /**
-     * RB-398-b④ ([2105]): a compaction pass concluded WITHOUT landing — the non-landing outcomes
+     * RB-398-b④: a compaction pass concluded WITHOUT landing — the non-landing outcomes
      * used to exist only as `compaction.*` trace frames, so a stream-only consumer watched a
      * context quietly stop being managed (breaker opens, rapid-refill disable, hook blocks —
      * all invisible). One lightweight additive event, emitted at the same sites as the trace
@@ -4142,12 +4152,12 @@ export type TaskEvent = ({
      * top-level run) has no generation concept, and absence must never be read as "cycle 1".
      */
     seq?: number;
-    /** [1611] workflow-lane self-identification (server field-proof: the SSE-forwarded tick of a
+    /** Workflow-lane self-identification (field-proven: the SSE-forwarded tick of a
      *  WORKFLOW child previously carried a bare uuid with no workflow identity — indistinguishable
      *  from an unknown nested subagent; the fleet lane had `wa*`+workflowRunId but this lane had
      *  nothing). Present iff the tick bubbled out of a workflow-spawned agent. Additive. */
     workflowRunId?: string;
-    /** [1611] the workflow agent's display label (opts.label / auto `agent-N`), riding with
+    /** the workflow agent's display label (opts.label / auto `agent-N`), riding with
      *  {@link workflowRunId} for the same self-identification. Additive. */
     workflowAgentLabel?: string;
     /** design/99 (nested-subagent live tree): the spawning run's taskId — present on a DEEPER-than-1 subagent tick
@@ -4172,7 +4182,7 @@ export type TaskEvent = ({
         toolUses: number;
         durationMs: number;
     };
-    /** Per-turn ticks are `"running"`. [1414]#3: ONE final tick fires at the sub-run's settle with the
+    /** Per-turn ticks are `"running"`. ONE final tick fires at the sub-run's settle with the
      *  terminal face (`"completed"` | `"failed"` — timeout/blocked fold to failed; a suspended durable
      *  pause emits no terminal tick), so a uuid-lane consumer sees the row finish instead of a bare
      *  removal after the last running beat. Additive value space — a consumer switching on "running"
@@ -4422,11 +4432,11 @@ export interface TaskStream extends AsyncIterable<TaskEvent> {
  * design/98 §E.2 / §2.5 (S8b) — the deployment-trusted governance that EVERY sub-agent an LLM-authored
  * workflow script spawns INHERITS (tighten-only). The child spec is BUILT from this baseline + a strict
  * WHITELIST of safe work-fields the script may set — `{ ...base, ...pick(scriptSpec, WHITELIST_KEYS) }` then
- * `tightenTaskSpec(base, child)` (codex BLOCKER2: default-deny / complete-by-construction, NOT a blacklist
+ * `tightenTaskSpec(base, child)` (default-deny / complete-by-construction, NOT a blacklist
  * strip — a missed control-plane field would otherwise leak). It is captured from `RunnerDeps` (trusted,
  * never LLM-influenced), NEVER from the LLM-influenced initiating task spec.
  *
- * Why an EXPLICIT field (codex Q1/Q2 arbitration): `RunnerDeps` has no `tools`/`mcp`/`skills`/`principal`
+ * Why an EXPLICIT field (arbitration): `RunnerDeps` has no `tools`/`mcp`/`skills`/`principal`
  * (those are TaskSpec-only), so the capability a workflow child gets cannot be auto-derived from deps —
  * the deployment must DECLARE it here. Unset ⇒ self-orchestration is FAIL-CLOSED (the `run_workflow` tool is
  * not mounted, same hard deploy gate as a missing sandbox): a script-spawned agent must never run without a
@@ -4467,7 +4477,7 @@ export interface WorkflowGovernanceBaseline {
      */
     worktreeBase?: Partial<TaskSpec>;
     /**
-     * The allowed model NAMES an LLM-authored script may pick (design/98 §2.5, codex 新洞2). A script gives a
+     * The allowed model NAMES an LLM-authored script may pick (design/98 §2.5 新洞2). A script gives a
      * `modelName` string (never a `Model` object — that carries `baseUrl`/`headers` = exfil); the engine
      * resolves it against this list to a deploy-configured `Model` (the script never sees the object).
      * **FAIL-CLOSED**: `undefined`/empty ⇒ the script CANNOT pick a model (its `modelName` is rejected → the
@@ -4534,10 +4544,10 @@ export interface RuntimeCaps {
 export interface BackgroundChildEvent {
     kind: "spawn" | "tick" | "terminal";
     /** Row key, stable across all three kinds. The prefix is the DOMAIN DISCRIMINATOR (load-bearing,
-     *  not opaque — design/149 + [1432]①): `a*` = registry handle (background subagent —
+     *  not opaque — design/149): `a*` = registry handle (background subagent —
      *  TaskOutput/TaskStop addressable, fleet-footer display lane); `wa*` = synthetic workflow-agent
      *  row (NOT a registry row — per-agent read face is the workflow's `TaskOutput(w*)` agent_runs
-     *  projection + journal API). Display contract ([1433] CC anchor): CC's footer renders ONLY the
+     *  projection + journal API). Display contract (CC anchor): CC's footer renders ONLY the
      *  workflow AGGREGATE row — `wa*` rows are read-face/observability rows and SHOULD NOT be
      *  rendered in the footer fleet tree; shells filter on the prefix. */
     taskId: string;
@@ -4549,33 +4559,33 @@ export interface BackgroundChildEvent {
     scope?: string;
     /** spawn: the child's short description (bounded, display-safe). */
     description?: string;
-    /** spawn + tick ([1336]A, [1346]②): the RESOLVED subagent type ("general-purpose" / "Explore" /
+    /** spawn + tick: the RESOLVED subagent type ("general-purpose" / "Explore" /
      *  a roster name / "fork") — the fleet row's TYPE column. Never the description. On ticks it is
      *  the ROW's type (this spawn), not the nested frame's origin — `progressTaskId` keys that. Rides
      *  every tick so a consumer that only forwards ticks (server K-7) still gets the type without
      *  waiting for spawn-frame forwarding; `name` stays the design/99 DISPLAY label (description-backed)
      *  and was never a type field. */
     agentType?: string;
-    /** spawn ([1344]②): the HOST task's DECLARED task id (parent attribution). Omitted when the host
+    /** spawn: the HOST task's DECLARED task id (parent attribution). Omitted when the host
      *  run declared no task id (the `spec.taskId ?? sessionId` fallback would launder a session id into
      *  a task-id field — the orphan-pointer shape); {@link parentSessionId} is the always-on linkage. */
     parentTaskId?: string;
-    /** spawn (codex 1350 r2 F2): the HOST run's session id (uuid domain) — the always-on parent
+    /** spawn: the HOST run's session id (uuid domain) — the always-on parent
      *  linkage, present whether or not a task id was declared. */
     parentSessionId?: string;
-    /** spawn (δ 批 [1498]⑦): the ROOT host session of the delegation tree (uuid domain). For a depth-1
+    /** spawn: the ROOT host session of the delegation tree (uuid domain). For a depth-1
      *  child it equals {@link parentSessionId}; for a nested grandchild it is the TOP session while
      *  parentSessionId is the intermediate spawner — a recovery/enumeration consumer groups the whole
      *  tree under the root without walking intermediate (possibly dead) sessions. */
     rootSessionId?: string;
-    /** spawn (δ 批 [1491]③c): epoch ms the child run was launched — the fleet row's time anchor
+    /** spawn: epoch ms the child run was launched — the fleet row's time anchor
      *  (elapsed rendering without waiting for the first tick). */
     startedAt?: number;
-    /** All kinds, `wa*` rows only (design/149 面2, [1432]② ruling b): the owning workflow run's
+    /** All kinds, `wa*` rows only (design/149 face 2): the owning workflow run's
      *  `w*` id. `parentTaskId` stays task-domain (the HOST task) so parent resolvers that only
      *  forward resolved task rows keep working; workflow grouping/nesting is THIS annotation's job. */
     workflowRunId?: string;
-    /** All kinds ([1832]/[1839] cross-repo P1-2): the delegating Agent tool call's OWN `toolCallId` —
+    /** All kinds: the delegating Agent tool call's OWN `toolCallId` —
      *  the same identity {@link TaskEvent}'s `parentToolCallId` already carries on every forwarded child
      *  content event (via `RunInternals.parentToolCallId`), extended to this SEPARATE observer/fleet
      *  event family so a consumer does not have to reassemble parent attribution from spawn-frame
@@ -4596,7 +4606,7 @@ export interface BackgroundChildEvent {
      */
     currentAction?: string;
     /**
-     * tick [1828] (server cross-repo, structured Progress-section source): the SAME `{tool, target}` pair
+     * tick (structured Progress-section source): the SAME `{tool, target}` pair
      * {@link currentAction} concatenates into prose, exposed separately so a consumer can look `toolName`
      * up in its own tool registry (CC `renderToolActivity` parity) instead of parsing the human line.
      * `target` is UNTRUSTED free text (a file path / command / pattern the child chose) — same trust
@@ -4655,7 +4665,7 @@ export interface BackgroundChildEvent {
      *  knowable (the registry handle / retain ledger's `cycleSeq`, the durable row's `seq` on a tier-3
      *  revival / parked resume), absent when no carrier exists (forging a period would lie). */
     seq?: number;
-    /** terminal, P1-3(黑板 [1920]/[1921]/[1924]/[1925]): the cross-channel completion correlation id —
+    /** terminal: the cross-channel completion correlation id —
      *  MIRROR of the sibling task_notification's `TaskNotificationPayload.completionId` (same settle,
      *  same minted value; the fleet lane was explicitly one of the four channels the original ask named
      *  — "同一完成今天从四条通道扇出" — so it gets the same mirror treatment `seq`/`stoppedBy` already
@@ -4709,7 +4719,7 @@ export interface BackgroundChildEvent {
  *    would stamp delegation frames onto host-resumed root tasks. Rows minted WITH the axis resume
  *    with their spawn/terminal pair even deps-only; a resume that re-supplies trusted internals
  *    (every in-engine lane does) was never affected.
- * PAIRING (codex r2-D2 closed the one hole): a spawn frame is always closed by a terminal frame —
+ * PAIRING (closed the one hole): a spawn frame is always closed by a terminal frame —
  * the ordinary path emits it where the `TaskResult` assembles, and a POST-SPAWN throw that the
  * stream layer converts into a synthesized failed result (e.g. `resume.tool_unavailable` re-thrown
  * past the run tail) emits the failed terminal from that backstop, gated on a carrier that is set
@@ -4805,7 +4815,7 @@ export interface ProjectMemoryLoad {
      */
     instructionSources?: ReadonlyArray<{
         path: string;
-        /** [1001]②a (server request, additive widening): `null` = the source is DECLARED but currently
+        /** (additive widening): `null` = the source is DECLARED but currently
          *  ABSENT from disk — the change probe then watches for its APPEARANCE (renders "absent → hash").
          *  Runtime already handled null (collectInstructionsChange's from===null arm); this widening
          *  only aligns the declared type with the shipped behavior. */
@@ -4979,6 +4989,16 @@ export interface EngineNotice {
      *    mark would have carried, neutralized/length-bounded (tool and agent-type names are
      *    host/model-controlled inputs).
      *
+     *  - `"memory.consolidation_incomplete"` (design/376, LLM consolidation driver) — a driver run
+     *    settled without reaching the fixpoint: `detail` names the stop reason (the closed
+     *    `ConsolidationRunStopReason` set), cycles done, and the residue (write-failure or
+     *    fuse-refused groups by name). Advisory: committed cycles stand (add-only, never rolled
+     *    back); the recovery verb is re-running the host driver, which resumes the same pending run.
+     *  - `"memory.consolidation_driver_superseded"` (same family) — a concurrent driver invocation
+     *    took over this scope's run row (attempt fencing): the losing worker stops with this code
+     *    and MUST NOT retry into the winner's account. Coordination fact between two host calls,
+     *    not a principal ruling — listed in the non-governance disposition table.
+     *
      *  - `"delegation.transcript_integrity"` (subagent transcript persistence) — a durable agent row
      *    with a BOUND transcript sessionId met a session store that attests `not_found` for it: the
      *    deployment's declared transcript durability is being contradicted by reality. Announced at
@@ -5081,7 +5101,7 @@ export interface RunnerDeps {
         isRevoked(serverName: string): boolean;
     };
     /**
-     * design/147 S1c (clay ruling 2026-07-18) — the DURABLE name→agent roster behind explicit-name
+     * design/147 S1c (ruled 2026-07-18) — the DURABLE name→agent roster behind explicit-name
      * addressing, a storage-tier seam like the checkpoint store: core bundles `MemoryRosterStore`
      * (default when omitted... none — omitted means NO durable roster; the in-memory task registry
      * still resolves live/recent names exactly as before) and `FileRosterStore`; a server deployment
@@ -5247,6 +5267,39 @@ export interface RunnerDeps {
      * {@link memoryProvenance}.
      */
     memoryConsolidation?: import("../core/memory-engine/consolidation.js").MemoryConsolidationOptions;
+    /**
+     * design/376 片② — the memory-consolidation DRIVER seat (the LLM half), ORTHOGONAL to
+     * {@link memoryConsolidation} on purpose: that key is the write PROTOCOL's parameters (fuse,
+     * caps, cadence — engine-side), this key is who thinks (model seat + mint knobs — driver-side).
+     * The ENGINE itself keeps zero model seats (design/339 §1.1: engine adjudicates, driver
+     * proposes; an engine-held model would put distillation authority on the wrong side of the
+     * trust boundary), so the seat lives here and is consumed by the host driver verb
+     * (`runMemoryConsolidationDriver` + `resolveMemoryConsolidationDriver(deps)`).
+     *
+     * `chat` — the explicit model seat: an endpoint triple (screened loudly: explicit model id, no
+     * alias spellings, key present) or any JSON-only completion function. ABSENT ⇒ the driver
+     * resolves the `consolidate` role (`consolidate → summarize → coded refusal`; deliberately
+     * never `default` — see the {@link ModelRole} doc). Every other knob mirrors the driver verb's
+     * options and is screened there (#123: bad values refuse coded, never fold to defaults).
+     * DEPLOYMENT seat ONLY, same law as {@link memoryConsolidation}: no TaskSpec twin — a task
+     * author gets no channel to point the library's consolidation at a model of its choosing.
+     * Absent alongside absent {@link memoryConsolidation} ⇒ nothing runs and nothing changes
+     * (the v3 default posture).
+     */
+    memoryConsolidationDriver?: {
+        chat?: {
+            baseUrl: string;
+            apiKey: string;
+            model: string;
+        } | import("../core/memory-engine/distiller.js").DistillerChatFn;
+        /** The audit model id — REQUIRED when `chat` is a bare function (a function carries no id and
+         *  the run/archive must not record a guess); derived from the endpoint triple or the resolved
+         *  role otherwise. */
+        model?: string;
+        contract?: import("../core/memory-engine/distiller.js").LlmDistillerContract;
+        maxCycles?: number;
+        mintRepairBudget?: number;
+    };
     /**
      * design/199 件A — the DEPLOYMENT's read-face declaration
      * ({@link import("../tools/fs/read-face.js").ReadFace}; see {@link TaskSpec.readFace} for the
@@ -5535,7 +5588,7 @@ export interface RunnerDeps {
      *  `SubagentToolOptions.background.agentStore` (spawn-side writer half) — the engine cannot
      *  verify the pairing (the Agent tool is deployment-composed), and a half-wired deployment is a
      *  SILENT degrade: reader-only ⇒ no rows ever exist; writer-only ⇒ the auto-mounted fallbacks
-     *  here never see them (全景复审 F-6; RB-37). Third consumer ([1511] server 复审): delegated
+     *  here never see them (RB-37). Third consumer: delegated
      *  CHILDREN's auto-mounted TaskOutput/TaskStop/AgentTranscript read THIS deps too (prepare-task
      *  wires them from the child's runner) — a sub-runner with different deps splits the read face. */
     backgroundAgentStore?: import("./background-agent-store.js").BackgroundAgentStore;
@@ -5626,12 +5679,12 @@ export interface RunnerDeps {
      * the handle — no host-context leak into the runner); the deployment registers it by `runId`+`label` to route a
      * human/cross-replica steer to `handle.steer(...)`. Unset ⇒ agents run non-steerable (no overhead). Opt-in.
      *
-     * **Interaction with {@link workflowJournalStore} ([1422]② updated)**: a steerable agent runs via
+     * **Interaction with {@link workflowJournalStore}**: a steerable agent runs via
      * `agentStream`, whose results ARE RECORDED in the journal since 1.355 (complete read-face: the journal
      * API / diagnostics coordinate show every agent) but are NEVER REPLAYED — `resumeFromRunId` on a
      * steerable workflow still re-runs agents LIVE (steer input is not deterministic; a cache would replay
      * a result the operator steered). Pre-1.355 the stream lane recorded NOTHING — with both deps set the
-     * journal read empty on every workflow (the [1419]② zero-write case), silently.
+     * journal read empty on every workflow (the zero-write case), silently.
      */
     onWorkflowAgentSpawn?: (handle: import("../orchestration/workflow.js").WorkflowAgentHandle) => void;
     /** design/72 §2.2 (B): deployment default for the suspend-loop cap (see `TaskSpec.maxSuspends`).
@@ -5658,7 +5711,7 @@ export interface RunnerDeps {
      * When set AND `spec.memory.enabled`, the task runs the INJECTION-FIRST file-based memory lifecycle
      * (materialize → session file ops → harvest with the full gate set), the CC-verbatim `# Memory`
      * instruction + fenced derived index replace the legacy `<user_memory>` block, and NO remember/recall
-     * tools are mounted (memory = the model's ordinary file skills). **S4 (codex 1.258 F6 doc fix): unset ⇒
+     * tools are mounted (memory = the model's ordinary file skills). **S4: unset ⇒
      * the task runs MEMORY-LESS** — the legacy `memoryStore` runtime path was retired (one deprecation
      * warning via `onError` phase `"config"`); this field is the ONLY live memory seam.
      */
@@ -5831,7 +5884,7 @@ export interface RunnerDeps {
     onAsk?: import("./tool-policy.js").OnAsk;
     /** Content-ask seam (design/64 §5): when set, every task mounts an AskUserQuestion tool that routes a
      *  model-issued question to this callback (a real human/UI). Distinct from `onAsk` (permission). A task's
-     *  own `onQuestion` overrides this. Unset ⇒ the tool mounts only if another [884] delivery face exists
+     *  own `onQuestion` overrides this. Unset ⇒ the tool mounts only if another delivery face exists
      *  (durable park consumer / explicit `TaskSpec.interactiveTools` — see that knob's criterion table). */
     onQuestion?: import("./ask-question.js").OnQuestion;
     /**