@sema-agent/core 7.54.1 → 7.55.0

package/dist/engine/execution-env/node-execution-env.d.ts

@@ -101,8 +101,12 @@ export declare class NodeExecutionEnv implements ExecutionEnv, BackgroundShellCa
     private readonly retainBackgroundProcesses;
     private readonly onSecretEnvScrub?;
     private readonly onNotice?;
-    /** design/128 T1-1: lazily-created env-owned spool dir (mkdtemp under os tmp — unpredictable, never the cwd). */
+    /** design/128 T1-1: the env-owned spool dir (mkdtemp under os tmp — unpredictable, never the cwd). It exists only while
+     *  {@link spoolPairs} is non-empty: the last pair's release removes it, the next mint makes a fresh one. */
     private bgSpoolDir?;
+    /** The `outPath` of every spool pair this env minted and has not released — the one fact the dir's lifetime reads. A
+     *  retain-lane bg pair is never released (its files outlive the run by design), so it keeps the dir. */
+    private readonly spoolPairs;
     readonly backgroundCapabilities: BackgroundShellCapability["backgroundCapabilities"];
     constructor(options: {
         cwd: string;
@@ -127,7 +131,8 @@ export declare class NodeExecutionEnv implements ExecutionEnv, BackgroundShellCa
          * env lane; `TaskSpec.retainBackgroundProcesses` is the task lane, without this spooling guarantee on
          * every platform — docs/background-process-lifetime.md). The 2h bg-timeout reaper and `killBackground` still work
          * while the host lives; after host exit, cleanup is the deployment's responsibility (e.g. the TB
-         * container teardown). v1 covers processes spawned via `execBackground` only (a detach-adopted
+         * container teardown) — the retained shells' spool files, and the dir holding them, are never released
+         * by the env (every other spool pair is, and the dir goes with the last one). v1 covers processes spawned via `execBackground` only (a detach-adopted
          * foreground exec keeps pipe stdio — best-effort survival). Incompatible with durable-suspend
          * deployments (their pre-suspend dispose becomes a no-op too — do not combine).
          */
@@ -157,8 +162,8 @@ export declare class NodeExecutionEnv implements ExecutionEnv, BackgroundShellCa
         abortSignal?: AbortSignal;
     }): Promise<Result<string[], FileError>>;
     readBinaryFile(path: string, abortSignal?: AbortSignal): Promise<Result<Uint8Array, FileError>>;
-    /** RB-221: whole-file replace via same-directory staging + fsync + rename (CC 2.1.220 `Q5`,
-     *  (pretty220.js:60808, historical; not relocated in 250 — see cc-250 anchors)). The former single-step `writeFile` was an in-place O_TRUNC: an abort mid-write
+    /** RB-221: whole-file replace via same-directory staging + fsync + rename.
+     *  The former single-step `writeFile` was an in-place O_TRUNC: an abort mid-write
      *  (Esc during a large Write — ctx.signal reaches here directly), ENOSPC, or a crash left the target as
      *  a torn prefix of the NEW content with the original unrecoverable. Post-fix contract: the target is
      *  either fully old or fully new; `aborted` means it was never touched. Known semantic change (same as
@@ -251,10 +256,19 @@ export declare class NodeExecutionEnv implements ExecutionEnv, BackgroundShellCa
      *  the file), while poll slicing keeps using the logical stream totalBytes; the two advance in
      *  lockstep here but are NOT interchangeable after a rotation. */
     private syncSpool;
+    /** The one seat that opens a spool pair (foreground exec and background spawn alike), inside the env's spool dir: made on
+     *  the first mint after the dir was last removed, so a command never runs against a dir an idle reap or a temp cleaner took. */
+    private mintSpoolPair;
+    /** The one seat that gives a spool pair back: unlinks both files (a descendant still writing keeps its fd into the unlinked
+     *  inode — no EPIPE), forgets the pair, and removes the dir once no pair is left in it. Idempotent. */
+    private releaseSpoolPair;
+    /** Removes the spool dir (and whatever a failed unlink stranded in it) when no pair of this env lives in it. A retain-lane
+     *  bg pair is never released, so it keeps its dir; the rest is gone with its last pair. Best-effort, never throws. */
+    private reapSpoolDirIfIdle;
     /** +: reclaim an EPHEMERAL spool (detach-adopted, or any non-retain bg
      *  spawn — the whole unix bg lane is spool-backed now) — fold the final residue into the tails,
      *  unlink both files, and drop the spool reference (later syncs become no-ops). Idempotent;
-     *  never touches design/128 retain-lane spools (no `ephemeral` flag). A still-writing detached
+     *  never touches the spool of a design/128 retain-lane shell that has a process (no `ephemeral` flag). A still-writing detached
      *  descendant keeps its fd into the unlinked inode (RB-26 posture — no EPIPE, auto-reclaim at
      *  its exit). */
     private reclaimEphemeralSpool;

package/dist/engine/execution-env/node-execution-env.js

@@ -1,6 +1,6 @@
 import { spawn } from "node:child_process";
 import { randomUUID } from "node:crypto";
-import { closeSync, constants, createReadStream, mkdtempSync, openSync, readSync, statSync, truncateSync, unlinkSync } from "node:fs";
+import { closeSync, constants, createReadStream, mkdtempSync, openSync, readSync, rmSync, statSync, truncateSync, unlinkSync } from "node:fs";
 import { access, appendFile, lstat, mkdir, mkdtemp, open, readdir, readFile, readlink, rename, rm, stat, unlink, writeFile, } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { isAbsolute, join, resolve } from "node:path";
@@ -336,6 +336,7 @@ export class NodeExecutionEnv {
     onSecretEnvScrub;
     onNotice;
     bgSpoolDir;
+    spoolPairs = new Set();
     backgroundCapabilities;
     constructor(options) {
         this.cwd = options.cwd;
@@ -465,13 +466,7 @@ export class NodeExecutionEnv {
                 if (spoolPumpRef.current)
                     clearInterval(spoolPumpRef.current);
                 if (execSpoolRef.current && !(result.ok && result.value.detached !== undefined)) {
-                    for (const path of [execSpoolRef.current.outPath, execSpoolRef.current.errPath]) {
-                        try {
-                            unlinkSync(path);
-                        }
-                        catch {
-                        }
-                    }
+                    this.releaseSpoolPair(execSpoolRef.current);
                     execSpoolRef.current = undefined;
                 }
                 resolvePromise(result);
@@ -479,9 +474,7 @@ export class NodeExecutionEnv {
             let execSpoolFds;
             if (process.platform !== "win32") {
                 try {
-                    if (!this.bgSpoolDir)
-                        this.bgSpoolDir = mkdtempSync(join(tmpdir(), "sema-bg-"));
-                    const pair = openSpoolPair(join(this.bgSpoolDir, `fg_${randomUUID()}`));
+                    const pair = this.mintSpoolPair(`fg_${randomUUID()}`);
                     execSpoolRef.current = { outPath: pair.outPath, errPath: pair.errPath };
                     execSpoolFds = pair.fds;
                 }
@@ -1309,9 +1302,7 @@ export class NodeExecutionEnv {
         let spoolFds;
         if (this.retainBackgroundProcesses || process.platform !== "win32") {
             try {
-                if (!this.bgSpoolDir)
-                    this.bgSpoolDir = mkdtempSync(join(tmpdir(), "sema-bg-"));
-                const pair = openSpoolPair(join(this.bgSpoolDir, `bg_${this.bgCounter + 1}_${randomUUID()}`));
+                const pair = this.mintSpoolPair(`bg_${this.bgCounter + 1}_${randomUUID()}`);
                 spool = {
                     outPath: pair.outPath,
                     errPath: pair.errPath,
@@ -1345,6 +1336,8 @@ export class NodeExecutionEnv {
                     }
                 }
             }
+            if (spool)
+                this.releaseSpoolPair(spool);
             const cause = toError(error);
             return err(new BackgroundShellError("spawn_failed", cause.message, cause));
         }
@@ -1533,23 +1526,51 @@ export class NodeExecutionEnv {
             }
         }
     }
+    mintSpoolPair(name) {
+        this.bgSpoolDir ??= mkdtempSync(join(tmpdir(), "sema-bg-"));
+        try {
+            const pair = openSpoolPair(join(this.bgSpoolDir, name));
+            this.spoolPairs.add(pair.outPath);
+            return pair;
+        }
+        catch (error) {
+            this.reapSpoolDirIfIdle();
+            throw error;
+        }
+    }
+    releaseSpoolPair(pair) {
+        for (const path of [pair.outPath, pair.errPath]) {
+            try {
+                unlinkSync(path);
+            }
+            catch {
+            }
+        }
+        this.spoolPairs.delete(pair.outPath);
+        this.reapSpoolDirIfIdle();
+    }
+    reapSpoolDirIfIdle() {
+        const dir = this.bgSpoolDir;
+        if (dir === undefined || this.spoolPairs.size > 0)
+            return;
+        this.bgSpoolDir = undefined;
+        try {
+            rmSync(dir, { recursive: true, force: true });
+        }
+        catch {
+        }
+    }
     reclaimEphemeralSpool(entry) {
         if (entry.spoolPump !== undefined) {
             clearInterval(entry.spoolPump);
             entry.spoolPump = undefined;
         }
         const spool = entry.spool;
-        if (!spool?.ephemeral)
+        if (!spool || (!spool.ephemeral && entry.child.pid !== undefined))
             return;
         this.syncSpool(entry);
         entry.spool = undefined;
-        for (const path of [spool.outPath, spool.errPath]) {
-            try {
-                unlinkSync(path);
-            }
-            catch {
-            }
-        }
+        this.releaseSpoolPair(spool);
     }
     async disposeBackgroundShells(opts) {
         if (this.retainBackgroundProcesses)

package/dist/engine/harness/agent-harness.d.ts

@@ -347,6 +347,12 @@ export declare class AgentHarness<TSkill extends Skill = Skill, TPromptTemplate
     private createTurnState;
     private createContext;
     private createStreamFn;
+    /** May a drain take this frame now? The one predicate of the drain, the immediate re-check and {@link pendingInjectionCount}.
+     *  A person's or caller's frame always may. An engine-authored frame is held — a drained steer makes a request — under
+     *  the human-halt hold ({@link engineInjectionsHeld}), and an ADVISORY is held where the loop's own work owes no request
+     *  (`continuing` false): it rides a request, never makes one; a notification's payload is an event and may continue a
+     *  run. Held frames stay queued: later input drains past them, an owed drain takes them, else they end with the run. */
+    private isDrainable;
     private drainQueuedMessages;
     /** #389 — drop these frames from the in-flight account (they went back on a queue, or they landed). */
     private unbookInFlight;
@@ -371,7 +377,7 @@ export declare class AgentHarness<TSkill extends Skill = Skill, TPromptTemplate
     private validateToolNames;
     private flushPendingSessionWrites;
     /**
-     * #506 ㋐ — write the transcript's record of a TERMINAL provider failure (CC 2.1.250 parity, `Oo`/`CIt`).
+     * #506 ㋐ — write the transcript's record of a TERMINAL provider failure.
      *
      * A SEPARATE object, never the live frame: `failure` is the engine's terminal error shell and every
      * other consumer of it (the run result, failover, telemetry, usage accounting) reads its real
@@ -466,7 +472,7 @@ export declare class AgentHarness<TSkill extends Skill = Skill, TPromptTemplate
      *    no frame whose consumption could make the cut self-defeating, so the seat's own liveness is
      *    the only guard. The cut settles exactly as every S1 cut does: finished tool calls keep
      *    their REAL results, never-started ones settle as paired interrupted results, the
-     *    CC-verbatim interruption marker lands.
+     *    the interruption marker lands.
      *
      * Returns `{ turnCut, accepted }` — `turnCut` `true` iff THIS call aborted a live turn seat (an
      * in-flight provider stream / tool batch will settle as interrupted; the completion-race arm is
@@ -489,7 +495,7 @@ export declare class AgentHarness<TSkill extends Skill = Skill, TPromptTemplate
      *    consults the latch at its own boundary, so the stop is provably in place when the forced
      *    boundary arrives (the enqueue-then-abort discipline, one lane over).
      *
-     * Queued injection frames are deliberately NOT touched (CC 2.1.223 `control_request:"interrupt"`
+     * Queued injection frames are deliberately NOT touched (the reference's `control_request:"interrupt"`
      * keeps the queue and answers `still_queued` — see {@link abort}'s recorded ruling): whatever
      * the queues hold settles by the run's ordinary terminal contract for accepted-but-undelivered
      * input (durable park when a suspend seat exists, else the loud undrained accounts).
@@ -516,10 +522,10 @@ export declare class AgentHarness<TSkill extends Skill = Skill, TPromptTemplate
     private noteTurnCutConsumed;
     /**
      * design/373 §3.3 (the final-commit-point double check) — how many queued injection frames a
-     * boundary drain could deliver RIGHT NOW: both lanes, minus frames the current state refuses to
-     * drain (an unwinding run drains nothing — those frames belong to the terminal account; a live
-     * human-halt hold skips engine-authored frames). Synchronous and side-effect-free by contract:
-     * the loop reads it between its last drain and the terminal commit, with zero awaits.
+     * boundary drain could deliver RIGHT NOW where the loop's own work owes none ({@link isDrainable}, `continuing` false):
+     * what could continue the run (an unwinding run drains nothing — its frames belong to the terminal account).
+     * Synchronous and side-effect-free by contract: the loop reads it between its last drain and the terminal
+     * commit, with zero awaits.
      */
     pendingInjectionCount(): number;
     /** design/373 §3.4-3 — the pre-request re-check's drain half (see the loop-config seam): sweep
@@ -607,7 +613,7 @@ export declare class AgentHarness<TSkill extends Skill = Skill, TPromptTemplate
         followUp: number;
     };
     /**
-     * backlog #389 (CC 2.1.223 `control_request:"interrupt"`, `CC:1064478-1064513`) — an interrupt does
+     * backlog #389 (`control_request:"interrupt"`) — an interrupt does
      * NOT destroy accepted user input. CC's default keeps the queue and answers `still_queued`; only an
      * explicit `cancel_queued` cancels, with a per-uuid `cancelled` receipt. This harness had the opposite
      * polarity: both queues were emptied unconditionally and the contents handed back on a result object

package/dist/engine/harness/agent-harness.js

@@ -43,6 +43,9 @@ function createTrailingMessage(seed) {
 }
 const engineNotePayloads = new WeakMap();
 const engineAuthoredInjections = new WeakSet();
+function isEngineAdvisory(m) {
+    return engineAuthoredInjections.has(m) && !engineNotePayloads.has(m);
+}
 const userInputParkRecords = new WeakMap();
 const drainedFromLane = new WeakMap();
 const immediateClassInjections = new WeakSet();
@@ -548,28 +551,34 @@ export class AgentHarness {
             });
         };
     }
-    async drainQueuedMessages(queue, mode) {
-        let messages;
+    isDrainable(m, continuing) {
+        if (!engineAuthoredInjections.has(m))
+            return true;
+        if (this.engineInjectionsHeld?.() === true)
+            return false;
+        return continuing || !isEngineAdvisory(m);
+    }
+    async drainQueuedMessages(queue, mode, continuing) {
         if (this.aborting)
             return [];
-        if (this.engineInjectionsHeld?.() === true) {
-            messages = [];
-            const limit = mode === "all" ? Number.POSITIVE_INFINITY : 1;
-            for (let i = 0; i < queue.length && messages.length < limit; i++) {
-                if (engineAuthoredInjections.has(queue[i]))
+        const messages = [];
+        let first;
+        let selecting = true;
+        for (let i = 0; i < queue.length; i++) {
+            const m = queue[i];
+            if (!this.isDrainable(m, continuing))
+                continue;
+            if (!isEngineAdvisory(m)) {
+                if (!selecting)
                     continue;
-                messages.push(...queue.splice(i, 1));
-                i--;
-            }
-        }
-        else {
-            let count = mode === "all" ? queue.length : 1;
-            if (mode !== "all" && queue.length > 1 && engineNotePayloads.has(queue[0])) {
-                count = 1;
-                while (count < queue.length && engineNotePayloads.has(queue[count]))
-                    count++;
+                if (mode !== "all" && first !== undefined && !(engineNotePayloads.has(first) && engineNotePayloads.has(m))) {
+                    selecting = false;
+                    continue;
+                }
+                first ??= m;
             }
-            messages = queue.splice(0, count);
+            messages.push(...queue.splice(i, 1));
+            i--;
         }
         if (messages.length === 0) {
             return messages;
@@ -682,9 +691,9 @@ export class AgentHarness {
                 return result;
             },
             afterToolCall: ({ toolCall, args, result, isError }) => this.afterToolCallHook(toolCall, args, result, isError),
-            prepareNextTurn: async () => {
+            prepareNextTurn: async ({ continues }) => {
                 await this.flushPendingSessionWrites();
-                await this.emitHook({ type: "turn_boundary", model: this.model });
+                await this.emitHook({ type: "turn_boundary", model: this.model, continues });
                 const nextTurnState = await this.createTurnState();
                 setTurnState(nextTurnState);
                 return {
@@ -693,7 +702,7 @@ export class AgentHarness {
                     thinkingLevel: nextTurnState.thinkingLevel,
                 };
             },
-            getSteeringMessages: async () => this.drainQueuedMessages(this.steerQueue, this.steeringQueueMode),
+            getSteeringMessages: async (continuing) => this.drainQueuedMessages(this.steerQueue, this.steeringQueueMode, continuing),
             publishTurnInterruptSeat: (seat) => {
                 if (seat !== undefined) {
                     this.lastPublishedSeat = seat;
@@ -705,7 +714,7 @@ export class AgentHarness {
             recheckImmediateInjections: async (pending) => this.absorbImmediateSteering(pending),
             pendingInjectionCount: () => this.pendingInjectionCount(),
             getFollowUpMessages: async () => {
-                const queued = await this.drainQueuedMessages(this.followUpQueue, this.followUpQueueMode);
+                const queued = await this.drainQueuedMessages(this.followUpQueue, this.followUpQueueMode, false);
                 if (queued.length > 0)
                     return queued;
                 return this.stopGate ? await this.stopGate() : queued;
@@ -1160,20 +1169,18 @@ export class AgentHarness {
     pendingInjectionCount() {
         if (this.aborting)
             return 0;
-        const held = this.engineInjectionsHeld?.() === true;
-        const drainable = (q) => held ? q.filter((m) => !engineAuthoredInjections.has(m)).length : q.length;
+        const drainable = (q) => q.filter((m) => this.isDrainable(m, false)).length;
         return drainable(this.steerQueue) + drainable(this.followUpQueue);
     }
     async absorbImmediateSteering(pending) {
         if (this.aborting)
             return pending;
-        const held = this.engineInjectionsHeld?.() === true;
         const taken = [];
         for (let i = 0; i < this.steerQueue.length; i++) {
             const m = this.steerQueue[i];
             if (!immediateClassInjections.has(m))
                 break;
-            if (held && engineAuthoredInjections.has(m))
+            if (!this.isDrainable(m, true))
                 continue;
             taken.push(...this.steerQueue.splice(i, 1));
             i--;

package/dist/engine/harness/types.d.ts

@@ -194,7 +194,7 @@ export declare class ExecutionError extends Error {
      * TB triple-fake-green report (2026-07-13) — output produced BEFORE the failure, for the
      * ran-then-cut codes (`timeout` / `liveness_no_output` / `aborted` / `callback_error`; the last is a command that
      * started and was then killed because a host-side output callback failed — its completion was
-     * never observed, but its captured output is real work). CC anchor (2.1.206 BashTask settle): a
+     * never observed, but its captured output is real work). Reference behavior (BashTask settle): a
      * timed-out command keeps ALL captured stdout/stderr and only APPENDS a "Command timed out after
      * X" line — discarding 600s of build logs forces the model to rerun blind. Optional: envs that
      * cannot capture partial output simply omit these; never-started codes
@@ -325,7 +325,7 @@ export interface ExecutionEnvExecOptions {
      */
     detachSignal?: AbortSignal;
     /**
-     * RB-198 F1 (form-one audit, CC 220 `Zry`/`WZi.#m` parity) — when this command's OWN timeout
+     * RB-198 F1 (form-one audit) — when this command's OWN timeout
      * fires, an env that supports detach ADOPTS the running child as a background process (the same
      * mechanism `detachSignal` uses) instead of killing it, settling the exec with
      * `detached: {shellId, cause:"timeout"}` — a non-idempotent long command survives its own timeout
@@ -665,6 +665,14 @@ export interface AnnouncedListingSnapshot {
     models?: string[];
     mcpFailed?: AnnouncedMcpFailure[];
     advisories?: string[];
+    advisor?: AnnouncedAdvisorState;
+}
+/** What the model was told about the advisor tool, and in which SEGMENT of the conversation — the id of the branch's
+ *  latest compaction entry when the telling was delivered, `null` before any. A record from another segment reads as
+ *  nothing told: a compaction summarized the telling away. */
+export interface AnnouncedAdvisorState {
+    state: "announced" | "withdrawn";
+    segment: string | null;
 }
 /** The same snapshot as an APPEND input (borrowed arrays; the store copies through the shape gate). */
 export interface AnnouncedListingSnapshotInput {
@@ -673,6 +681,7 @@ export interface AnnouncedListingSnapshotInput {
     models?: readonly string[];
     mcpFailed?: ReadonlyArray<AnnouncedMcpFailure>;
     advisories?: readonly string[];
+    advisor?: Readonly<AnnouncedAdvisorState>;
 }
 /**
  * REF-D3/D4 merge target: the active EnterWorktree session (M22 live-CC anchor —
@@ -841,8 +850,8 @@ export declare function isValidModelChange(e: {
     modelId?: unknown;
 }): boolean;
 /**
- * #506 ㋐ — the reserved `model` value on a transcript entry NO MODEL PRODUCED. CC-verbatim
- * (`"<synthetic>"`, CC 2.1.250's own single-occurrence constant), and single-occurrence here for the
+ * #506 ㋐ — the reserved `model` value on a transcript entry NO MODEL PRODUCED. Spelled as in the reference
+ * (`"<synthetic>"`, its own single-occurrence constant), and single-occurrence here for the
  * same reason: the mint site and the recognition predicate must read the same literal or the entry
  * becomes unrecognizable the first time one of them is retyped.
  *
@@ -904,6 +913,14 @@ export interface SessionMetadata {
     incarnation?: string;
     /** Fork lineage's OCCUPANT half: the source row's `incarnation` at fork time (the occupant copied, not whoever holds `forkedFrom` later); absent = unknown. */
     forkedFromIncarnation?: string;
+    /** WHO owns this row, recorded by the write that creates it and changed by no later write; `null` = anonymous; absent reads as `null`. */
+    owner?: string | null;
+}
+/** One row's owner, occupant (`undefined` = unknown) and active leaf (`null` = none), read in ONE read so the three answer for one row generation. */
+export interface SessionHead {
+    readonly owner: string | null;
+    readonly incarnation: string | undefined;
+    readonly leafId: string | null;
 }
 export interface JsonlSessionMetadata extends SessionMetadata {
     cwd: string;
@@ -1050,6 +1067,8 @@ export interface SessionCreateOptions {
     placement?: Omit<SessionPlacementRecord, "placedAt"> & {
         placedAt?: number;
     };
+    /** The owner the creating write records (absent ⇒ `null`; on a fork, absent or `null` ⇒ the copied source row's); a create over an existing id records nothing. */
+    owner?: string | null;
 }
 export interface SessionForkOptions {
     entryId?: string;
@@ -1070,10 +1089,11 @@ export interface SessionRepo<TMetadata extends SessionMetadata = SessionMetadata
      * Optional — a backend that supports cross-backend session export/migration implements it.
      */
     exportEntries?(sessionId: string): Promise<SessionTreeEntry[]>;
+    /** The row's {@link SessionHead} in one read (`undefined` = no row); `TtlSessionStore` has a head read and an ownership pair only over a repo that has this. */
+    headOf?(sessionId: string): Promise<SessionHead | undefined>;
     /**
-     * 2c session-sync: write a verbatim entry log (produced by {@link exportEntries} on another backend) into
-     * `sessionId`, re-stamping ownership to `owner` (from the caller's authenticated principal — never trusted
-     * from the bundle). The log MUST be passed through `validateEntriesForImport` first (the single fail-closed
+     * 2c session-sync: write a verbatim entry log (produced by {@link exportEntries} on another backend) into `sessionId` (the log is
+     * replaced, never the row: an existing row keeps its metadata whole; an absent id is a new row recording `owner`, `undefined` ⇒ `null` — the caller's principal, never the bundle's). The log MUST be passed through `validateEntriesForImport` first (the single fail-closed
      * invariant gate); a durable backend persists THAT function's output, it does not re-implement the checks.
      * Optional.
      *
@@ -1160,6 +1180,8 @@ export interface TurnBoundaryEvent {
     type: "turn_boundary";
     /** The model that will run the next turn (authoritative under a mid-task model switch). */
     model: Model;
+    /** The loop's continuation fact, as defined at {@link import("../loop/types.js").PrepareNextTurnContext.continues}. */
+    continues: boolean;
 }
 export interface BeforeProviderRequestEvent {
     type: "before_provider_request";

package/dist/engine/harness/types.js

@@ -212,7 +212,17 @@ export function normalizeAnnouncedListing(v) {
     const models = arm(src.models);
     const mcpFailed = failureArm(src.mcpFailed);
     const advisories = arm(src.advisories);
-    if (agents === null || skills === null || models === null || mcpFailed === null || advisories === null)
+    const advisorArm = (a) => {
+        if (a === undefined)
+            return undefined;
+        if (typeof a !== "object" || a === null)
+            return null;
+        const { state, segment } = a;
+        const segmentOk = segment === null || (typeof segment === "string" && segment.length <= ANNOUNCED_LISTING_MAX_NAME_CHARS);
+        return (state === "announced" || state === "withdrawn") && segmentOk ? { state, segment: segment } : null;
+    };
+    const advisor = advisorArm(src.advisor);
+    if (agents === null || skills === null || models === null || mcpFailed === null || advisories === null || advisor === null)
         return undefined;
     return {
         ...(agents !== undefined ? { agents } : {}),
@@ -220,5 +230,6 @@ export function normalizeAnnouncedListing(v) {
         ...(models !== undefined ? { models } : {}),
         ...(mcpFailed !== undefined ? { mcpFailed } : {}),
         ...(advisories !== undefined ? { advisories } : {}),
+        ...(advisor !== undefined ? { advisor } : {}),
     };
 }

package/dist/engine/llm/types.d.ts

@@ -611,10 +611,10 @@ export interface AssistantMessage {
     /**
      * design/124 tier A: this final message was PARTIALLY FINALIZED after a mid-stream connection
      * loss/stall — the substantive streamed prefix (text and/or completed tool calls) was promoted to
-     * final content instead of failing the turn (CC 198 queryModelStreaming parity: avoid re-billing +
+     * final content instead of failing the turn (avoid re-billing +
      * keep the displayed content consistent with the result). `stopReason` is synthesized from the
      * content ("toolUse" when a completed tool call streamed, else "stop"); `errorMessage` carries the
-     * warning in CC 2.1.220's words ("Response stalled mid-stream." / "Connection closed mid-response."; gone from 2.1.245 on), visible
+     * warning in the reference's former words ("Response stalled mid-stream." / "Connection closed mid-response."), visible
      * to the model in the transcript. Downstream semantics (agent-loop): `partialFinalized &&
      * stopReason==="stop"` gets a BOUNDED continue nudge (an unattended run must not book the cut as an
      * incomplete success); `partialFinalized && stopReason==="toolUse"` executes normally (a truncated
@@ -877,7 +877,7 @@ export interface OpenAIResponsesCompat {
  */
 export interface AnthropicMessagesCompat {
     /**
-     * How this endpoint takes extended thinking (CC 2.1.198 parity, design/119).
+     * How this endpoint takes extended thinking (design/119).
      * - `"budget"` (default, pre-Fable models): `thinking: { type: "enabled", budget_tokens }`.
      * - `"adaptive"` (Fable 5 / Opus 4.8/4.7 class): `thinking: { type: "adaptive" }` — NO
      *   `budget_tokens` (these models 400 on a budget), no max_tokens bump; the intensity is carried
@@ -886,7 +886,7 @@ export interface AnthropicMessagesCompat {
      */
     thinkingMode?: "budget" | "adaptive";
     /**
-     * Effort tiers this endpoint accepts via `output_config.effort` (CC 2.1.198 `effort` /
+     * Effort tiers this endpoint accepts via `output_config.effort` (the reference's `effort` /
      * `xhigh_effort` / `max_effort` capability bits collapsed into one declared set, matching the
      * `reasoningEffortLevels` pattern on {@link OpenAICompletionsCompat}). Present ⇒ the brain sends
      * `output_config: { effort }` plus the `effort-2025-11-24` beta header, clamping the requested
@@ -896,14 +896,14 @@ export interface AnthropicMessagesCompat {
      */
     effortLevels?: ThinkingLevel[];
     /**
-     * Whether the endpoint accepts `temperature` at all. CC 2.1.198 sends temperature only to a
+     * Whether the endpoint accepts `temperature` at all. The reference sends temperature only to a
      * legacy allowlist — Fable-5-class models NEVER receive it (400 risk), independent of thinking
      * state. Default true (existing models unchanged); `false` drops a caller temperature
      * unconditionally, not just under extended thinking.
      */
     supportsTemperature?: boolean;
     /**
-     * design/119 S4 (CC 2.1.198 `context_management` capability): when thinking is enabled, send
+     * design/119 S4 (`context_management` capability): when thinking is enabled, send
      * `context_management: { edits: [{ type: "clear_thinking_20251015", keep: "all" }] }` plus the
      * `context-management-2025-06-27` beta — an explicit opt-OUT of the server's default
      * thinking-clearing, preserving cross-turn reasoning continuity (what CC sends on first-party
@@ -912,7 +912,7 @@ export interface AnthropicMessagesCompat {
      */
     contextManagement?: boolean;
     /**
-     * design/119 S4 (CC 2.1.198): attach the `interleaved-thinking-2025-05-14` beta on tool-enabled
+     * design/119 S4: attach the `interleaved-thinking-2025-05-14` beta on tool-enabled
      * requests with thinking on (thinking blocks may interleave with tool_use). Declare per endpoint;
      * absent = no beta (pre-119 behavior; a deployment could already do this via static `headers`).
      */
@@ -957,7 +957,7 @@ export interface Model<TApi extends Api = Api> {
     /**
      * Optional AUTOCOMPACT window — the window the compaction trigger and the clearStale frontier
      * are derived from when it differs from the physical request window (dual-window semantics).
-     * CC 2.1.207 posture: its 1M sonnet keeps the PHYSICAL window at 1M while a per-model dynamic
+     * The reference's posture: its 1M sonnet keeps the PHYSICAL window at 1M while a per-model dynamic
      * config lowers only the autocompact window to 967000, so the reactive trigger lands at 934000
      * (= 967000 − 33000); a single window value cannot express both. Consumed by the trigger-side
      * geometry only (`editBudget`/`sanitizeCompactionSettings`/`shouldCompact` window); the request
@@ -996,7 +996,7 @@ export interface Model<TApi extends Api = Api> {
     /** Extra request HEADERS merged into the provider call. Cannot override auth / content-type / version. */
     headers?: Record<string, string>;
     /**
-     * design/119 S3 (CC 2.1.198 parity): model-declared system-prompt guidance sections, appended to
+     * design/119 S3: model-declared system-prompt guidance sections, appended to
      * the assembled system prompt. This is the declarative home for per-model behavioral patches (CC
      * ships Fable-5 "mitigations" baked behind model-name checks; sema keeps the MECHANISM generic —
      * any Model can carry guidance — and the CONTENT as preset data, zero model-name matching in core).

package/dist/engine/llm/validation.d.ts

@@ -1,7 +1,10 @@
 import type { Tool, ToolCall } from "./types.js";
 /** Finds the target tool and validates/coerces a model-emitted tool call. */
 export declare function validateToolCall(tools: Tool[], toolCall: ToolCall): unknown;
-/** VENDORED EDIT (design/115 P0): resolve canonical tool names first, then legacy aliases. */
+/** The dispatcher's name resolution over one tool list, indexed once (for a caller resolving many names over the same list):
+ *  canonical names first, then aliases (design/115 P0 order) — the first tool carrying a name, or an alias, owns it. */
+export declare function toolNameIndex<T extends Tool>(tools: readonly T[] | undefined): (name: string) => T | undefined;
+/** VENDORED EDIT (design/115 P0): resolve canonical tool names first, then legacy aliases ({@link toolNameIndex} for one name). */
 export declare function findToolByName<T extends Tool>(tools: readonly T[] | undefined, name: string): T | undefined;
 /** Validates tool arguments against TypeBox or plain JSON-schema parameters. */
 export declare function validateToolArguments(tool: Tool, toolCall: ToolCall): unknown;

package/dist/engine/llm/validation.js

@@ -378,8 +378,20 @@ export function validateToolCall(tools, toolCall) {
     }
     return validateToolArguments(tool, toolCall);
 }
+export function toolNameIndex(tools) {
+    const byName = new Map();
+    const byAlias = new Map();
+    for (const t of tools ?? []) {
+        if (!byName.has(t.name))
+            byName.set(t.name, t);
+        for (const a of t.aliases ?? [])
+            if (!byAlias.has(a))
+                byAlias.set(a, t);
+    }
+    return (name) => byName.get(name) ?? byAlias.get(name);
+}
 export function findToolByName(tools, name) {
-    return tools?.find((t) => t.name === name) ?? tools?.find((t) => t.aliases?.includes(name));
+    return toolNameIndex(tools)(name);
 }
 export function validateToolArguments(tool, toolCall) {
     const args = structuredClone(toolCall.arguments);

package/dist/engine/loop/agent-loop.d.ts

@@ -61,7 +61,7 @@ export type LoopTerminalReason =
  *  loop ended cleanly at a manufactured boundary, no reconcile owed), and which consult caught
  *  it is timing, not semantics. */
  | "stop_requested"
-/** RB-206 (CC 220 counterpart @400176-400230, `Bxs` @397652-397674 buckets it
+/** RB-206 (the reference buckets it
  *  with budget_exhausted/api_error/model_error/turn_setup_failed, explicitly NOT `"completed"`): every
  *  tool call in the turn was dropped as malformed AND the bounded `malformed_tool_use_retry` nudge
  *  budget is used up — the model believes it acted, nothing ran, and there is no more recovery budget