@sema-agent/core 7.54.1 → 7.56.0

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

@@ -1,6 +1,6 @@
 import type { ActorAssertion, AssistantMessage, ImageContent, Model, TextContent, UserMessage, UserMessageAttachment } from "../llm/index.js";
 import { type ToolTurnRepair } from "../llm/index.js";
-import { type ExecutedToolCallOutcome } from "../loop/agent-loop.js";
+import { runToolCall, type ExecutedToolCallOutcome } from "../loop/agent-loop.js";
 import type { HaltRemainingDirective } from "../loop/types.js";
 import type { AgentMessage, AgentTool, AgentToolCall, LoopMalformedToolUseRecovery, LoopThinkingOnlyRecovery, LoopTruncatedOutputRecovery, QueueMode, ThinkingLevel } from "../loop/types.js";
 import { type EngineSegment } from "../../core/untrusted-text.js";
@@ -174,6 +174,8 @@ export declare class AgentHarness<TSkill extends Skill = Skill, TPromptTemplate
     private readonly seatCutSources;
     private trailingBatchEndedOn?;
     private turnCutConsumed?;
+    private readonly committedEntryIds;
+    private readonly answerSources;
     /** backlog #389 — one-way latch set by {@link abort}. Read by `drainQueuedMessages`: no boundary may
      *  hand a queued frame to the model once the run is unwinding, and — crucially — none may SPLICE one
      *  out of the queue either (that would delete the terminal undrained account the abort path owes it). */
@@ -308,6 +310,8 @@ export declare class AgentHarness<TSkill extends Skill = Skill, TPromptTemplate
     private maxOutputTokensPerCall?;
     private stallTimeoutsPerCall?;
     private abortResultDetails?;
+    private executeTool?;
+    private activeRun?;
     private loopTrace?;
     private onToolInputValidationFault?;
     private onToolMediaRefused?;
@@ -347,6 +351,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 +381,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 +476,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 +499,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).
@@ -503,6 +513,15 @@ export declare class AgentHarness<TSkill extends Skill = Skill, TPromptTemplate
      *  the loop takes the run-terminal path and never reports that settlement, so the consumption is recorded here, the
      *  only point that can see the causation (synchronous, single-threaded). A LATER abort is the run's own ending. */
     private cutSeat;
+    /** The entry ids of the committed messages an answer `prompt()` returned was read from, in conversation order: the
+     *  final assistant message, or every member of the continuation chain merged into it (members never appended — an
+     *  empty failure — have no id). Bound to the returned object, so a prompt that rejects, or one overlapping another,
+     *  hands its caller nothing to misread. Empty for `undefined` (no answer, read from nothing); `undefined` when the
+     *  sources are not this harness's to state — an object it did not return, or an answer read from a message the
+     *  transcript held before the run began whose append this harness never saw. */
+    answerEntryIdsOf(answer: AssistantMessage | undefined): readonly string[] | undefined;
+    /** Record what an answer was read from (the append receipts of its source messages) and hand the answer back. */
+    private answeredFrom;
     /** The harness's statement of what this run's halt (and its stop siblings) did — {@link HaltConsumption}. Readable
      *  during the run and after `prompt()` settled (cleared by the NEXT prompt). */
     haltConsumption(): HaltConsumption;
@@ -516,10 +535,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
@@ -544,6 +563,17 @@ export declare class AgentHarness<TSkill extends Skill = Skill, TPromptTemplate
     finalizeToolCall(toolCall: AgentToolCall, args: unknown, executed: ExecutedToolCallOutcome): Promise<ExecutedToolCallOutcome & {
         toolCall: AgentToolCall;
     }>;
+    /**
+     * A call the host makes while a run is running (an extension's `$.tool.call`): the loop's own per-call pipeline
+     * ({@link runToolCall}) under the run's config and current roster — announced, judged at the gate, executed through the
+     * execution seat, finalized and closed on the run's event stream — with no model message carrying it and nothing added
+     * to the transcript. `admit` reads the tool the name resolves to before anything is announced; its throw is the caller's.
+     * Throws when no run is running or the run mounts no tool of that name.
+     */
+    callTool(toolCall: AgentToolCall, signal: AbortSignal | undefined, admit: (tool: AgentTool) => void): Promise<Awaited<ReturnType<typeof runToolCall>>["finalized"]>;
+    /** Whether the loop would run this call beside others (`isBatchSafeToolCall`, the partitioner's own predicate) on the running
+     *  prompt's roster — false for a name it does not mount, and when no prompt is running. */
+    isBatchSafe(toolName: string, args: unknown): boolean;
     getModel(): Model;
     /** The ref that chose the CURRENT model — {@link getModel}'s companion (a word re-resolves, an object pins). */
     getModelRef(): import("../../core/model-seat.js").ModelRef;
@@ -607,7 +637,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

@@ -1,5 +1,5 @@
-import { createAssistantMessageEventStream, ensureToolTurnInvariants, snapshotActorAssertion, stripEngineMetadata, userAttachmentOf } from "../llm/index.js";
-import { finalizeToolOutcome, runAgentLoop } from "../loop/agent-loop.js";
+import { createAssistantMessageEventStream, ensureToolTurnInvariants, findToolByName, snapshotActorAssertion, stripEngineMetadata, userAttachmentOf } from "../llm/index.js";
+import { finalizeToolOutcome, isBatchSafeToolCall, runAgentLoop, runToolCall } from "../loop/agent-loop.js";
 import { resolveAgentCoreStreamFn } from "../loop/runtime-deps.js";
 import { normalizeEngineSegments } from "../../core/untrusted-text.js";
 import { isCredentialHeaderName } from "../../core/secret-env.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();
@@ -205,6 +208,8 @@ export class AgentHarness {
     seatCutSources = new WeakMap();
     trailingBatchEndedOn;
     turnCutConsumed;
+    committedEntryIds = new WeakMap();
+    answerSources = new WeakMap();
     aborting = false;
     drainedPendingInjection = [];
     runAbortController;
@@ -292,6 +297,8 @@ export class AgentHarness {
     maxOutputTokensPerCall;
     stallTimeoutsPerCall;
     abortResultDetails;
+    executeTool;
+    activeRun;
     loopTrace;
     onToolInputValidationFault;
     onToolMediaRefused;
@@ -328,6 +335,7 @@ export class AgentHarness {
         this.maxOutputTokensPerCall = options.maxOutputTokensPerCall;
         this.stallTimeoutsPerCall = options.stallTimeoutsPerCall;
         this.abortResultDetails = options.abortResultDetails;
+        this.executeTool = options.executeTool;
         this.loopTrace = options.loopTrace;
         this.onToolInputValidationFault = options.onToolInputValidationFault;
         this.onToolMediaRefused = options.onToolMediaRefused;
@@ -548,28 +556,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;
@@ -641,6 +655,7 @@ export class AgentHarness {
             ...(this.maxOutputTokensPerCall !== undefined ? { maxTokensPerCall: this.maxOutputTokensPerCall } : {}),
             ...(this.stallTimeoutsPerCall !== undefined ? { stallTimeoutsPerCall: this.stallTimeoutsPerCall } : {}),
             ...(this.abortResultDetails !== undefined ? { abortResultDetails: this.abortResultDetails } : {}),
+            ...(this.executeTool !== undefined ? { executeTool: this.executeTool } : {}),
             ...(this.onToolInputValidationFault !== undefined ? { onToolInputValidationFault: this.onToolInputValidationFault } : {}),
             ...(this.onToolMediaRefused !== undefined ? { onToolMediaRefused: this.onToolMediaRefused } : {}),
             ...(this.resilience !== undefined ? { resilience: this.resilience } : {}),
@@ -682,9 +697,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 +708,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 +720,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;
@@ -825,6 +840,7 @@ export class AgentHarness {
             let entryId;
             if (!isEmptyFailureAssistant(event.message)) {
                 entryId = await this.session.appendMessage(event.message);
+                this.committedEntryIds.set(event.message, entryId);
                 this.settleInjectedFrame(event.message, entryId);
                 if (entryId !== undefined && event.message.role === "toolResult" && typeof event.message.toolCallId === "string") {
                     try {
@@ -934,9 +950,12 @@ export class AgentHarness {
         const setTurnState = (nextTurnState) => {
             activeTurnState = nextTurnState;
         };
+        const loopConfig = this.createLoopConfig(getTurnState, setTurnState, beforeResult?.systemPrompt);
+        const emitRunEvent = (event) => this.handleAgentEvent(event, abortController.signal);
+        this.activeRun = { config: loopConfig, context: () => this.createContext(getTurnState(), beforeResult?.systemPrompt), emit: emitRunEvent, signal: abortController.signal };
         const runResultPromise = (async () => {
             try {
-                return await runAgentLoop(takePrompts, this.createContext(turnState, beforeResult?.systemPrompt), this.createLoopConfig(getTurnState, setTurnState, beforeResult?.systemPrompt), (event) => this.handleAgentEvent(event, abortController.signal), abortController.signal, this.createStreamFn(getTurnState), undefined, this.loopTrace, {
+                return await runAgentLoop(takePrompts, this.createContext(turnState, beforeResult?.systemPrompt), loopConfig, emitRunEvent, abortController.signal, this.createStreamFn(getTurnState), undefined, this.loopTrace, {
                     ...(options?.settleUnansweredToolCalls !== undefined
                         ? {
                             settle: {
@@ -966,13 +985,14 @@ export class AgentHarness {
             for (let i = newMessages.length - 1; i >= 0; i--) {
                 const message = newMessages[i];
                 if (message.role === "assistant") {
-                    return mergeTruncatedOutputChain(newMessages, i);
+                    const answer = mergeTruncatedOutputChain(newMessages, i);
+                    return this.answeredFrom(answer.message, answer.members);
                 }
             }
             if (this.stopRequested || abortController.signal.aborted)
                 return undefined;
             if (this.trailingBatchEndedOn !== undefined)
-                return this.trailingBatchEndedOn;
+                return this.answeredFrom(this.trailingBatchEndedOn, [this.trailingBatchEndedOn]);
             throw new AgentHarnessError("invalid_state", "AgentHarness prompt completed without an assistant message");
         }
         finally {
@@ -981,6 +1001,7 @@ export class AgentHarness {
             }
             finally {
                 this.runAbortController = undefined;
+                this.activeRun = undefined;
             }
         }
     }
@@ -1136,6 +1157,21 @@ export class AgentHarness {
         if (runQuietBefore && this.runAbortController?.signal.aborted === true)
             this.turnCutConsumed = { source };
     }
+    answerEntryIdsOf(answer) {
+        return answer === undefined ? [] : this.answerSources.get(answer);
+    }
+    answeredFrom(answer, members) {
+        const ids = [];
+        for (const m of members) {
+            const id = this.committedEntryIds.get(m);
+            if (id !== undefined)
+                ids.push(id);
+            else if (this.runHistory?.has(m) === true)
+                return answer;
+        }
+        this.answerSources.set(answer, ids);
+        return answer;
+    }
     haltConsumption() {
         const turnCut = this.turnCutConsumed?.source;
         return {
@@ -1160,20 +1196,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--;
@@ -1237,6 +1271,23 @@ export class AgentHarness {
     finalizeToolCall(toolCall, args, executed) {
         return finalizeToolOutcome(toolCall, executed, (result, isError) => this.afterToolCallHook(toolCall, args, result, isError), this.onToolMediaRefused);
     }
+    async callTool(toolCall, signal, admit) {
+        const run = this.activeRun;
+        if (run === undefined)
+            throw new AgentHarnessError("invalid_state", "a host's tool call runs inside a running prompt, and none is running");
+        const context = run.context();
+        const tool = findToolByName(context.tools, toolCall.name);
+        if (tool === undefined)
+            throw new AgentHarnessError("invalid_state", `no tool named "${toolCall.name}" in this run (it has ${(context.tools ?? []).map((t) => t.name).join(", ") || "none"})`);
+        admit(tool);
+        const both = signal !== undefined ? AbortSignal.any([signal, run.signal]) : run.signal;
+        return (await runToolCall(context, undefined, toolCall, run.config, both, run.emit)).finalized;
+    }
+    isBatchSafe(toolName, args) {
+        const tools = this.activeRun?.context().tools;
+        const tool = findToolByName(tools, toolName);
+        return tool !== undefined && isBatchSafeToolCall(tool, { type: "toolCall", id: "", name: toolName, arguments: (typeof args === "object" && args !== null ? args : {}) });
+    }
     getModel() {
         return this.model;
     }
@@ -1456,6 +1507,7 @@ function mergeTruncatedOutputChain(messages, lastAssistantIndex) {
     const last = messages[lastAssistantIndex];
     const lastText = last.content.map((c) => (c.type === "text" ? c.text : "")).join("");
     const parts = [];
+    const members = [last];
     let i = lastAssistantIndex;
     while (i - 2 >= 0) {
         const mid = messages[i - 1];
@@ -1470,18 +1522,20 @@ function mergeTruncatedOutputChain(messages, lastAssistantIndex) {
         if (!step)
             break;
         parts.unshift(head.content.map((c) => (c.type === "text" ? c.text : "")).join(""));
+        members.unshift(head);
         i = i - 2;
     }
     if (parts.length === 0) {
-        return last;
+        return { message: last, members };
     }
-    return {
+    const message = {
         ...last,
         content: [
             { type: "text", text: parts.join("") + lastText },
             ...last.content.filter((c) => c.type !== "text"),
         ],
     };
+    return { message, members };
 }
 function toLintErrorObject(value, fallbackMessage) {
     if (value instanceof Error) {

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

@@ -2,6 +2,7 @@ import type { PromptEpochDescriptor } from "../../prompt-assembly/epoch.js";
 import type { DocumentContent, ImageContent, Model, SimpleStreamOptions, TextContent, Transport } from "../llm/index.js";
 import type { AfterToolCallResult, AgentEvent, AgentMessage, AgentTool, BeforeToolCallResult, QueueMode, ThinkingLevel } from "../loop/types.js";
 import type { AgentCoreRuntimeDeps } from "../loop/runtime-deps.js";
+import type { SecretEnvFinding } from "../../core/secret-env.js";
 /** Result of a fallible operation. Expected failures are returned as `ok: false` instead of thrown. */
 export type Result<TValue, TError> = {
     ok: true;
@@ -103,7 +104,11 @@ export interface WriteReceipt {
     created: boolean;
 }
 /** Stable, backend-independent file error codes returned by {@link FileSystem} file operations. */
-export type FileErrorCode = "aborted" | "not_found" | "permission_denied" | "not_directory" | "is_directory" | "invalid" | "not_supported"
+export type FileErrorCode = "aborted" | "not_found" | "permission_denied" | "not_directory" | "is_directory"
+/** A name this filesystem cannot hold (POSIX `ENAMETOOLONG` for a path component past `NAME_MAX`) — nothing can be there, and
+ *  a program that opens it fails the same way: an absence as conclusive as `not_found`. A path past `PATH_MAX` whose
+ *  components are short is not this word (such a file may exist, reached from a directory below it). */
+ | "name_too_long" | "invalid" | "not_supported"
 /** Exclusive create refused because the path already exists ({@link FileSystem.writeFileExclusive},
  *  POSIX `O_EXCL` shape). Discriminable so a caller can distinguish "lost the create race" from a
  *  write failure and give honest guidance instead of overwriting. */
@@ -194,7 +199,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 +330,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
@@ -550,6 +555,11 @@ export interface ExecutionEnv extends FileSystem, Shell {
     readonly homeDir?: string;
     /** #1554 — the `CDPATH` entries the shell child receives (`[]` = none), or `"unknown"` when the adapter cannot say. */
     readonly cdPath: readonly string[] | "unknown";
+    /** #1963 — the entries of the environment the shell child inherits that it does NOT receive: the findings of the one
+     *  composition its spawns read (`inheritedHostEnv(policy, findings)`), less the keys the adapter's explicit grants
+     *  re-supply — names and rules, never a value. `[]` = none withheld, or none inherited (a shell environment built
+     *  rather than inherited from this process); `"unknown"` = the adapter cannot say. A read: it announces nothing. */
+    readonly withheldEnv: readonly SecretEnvFinding[] | "unknown";
 }
 /** Base fields shared by append-only session tree entries. */
 export interface SessionTreeEntryBase {
@@ -665,6 +675,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 +691,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 +860,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 +923,24 @@ 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 of {@link SessionRepo.list}: the row's metadata, plus the newest activity the repo records for the row. `lastActiveAt` is
+ * epoch ms — on the File repo its log's modification time (every write to a row is an append to its log, and {@link SessionRepo.touch}
+ * moves the same time), on the in-memory repo its last {@link SessionRepo.touch} (it never sees its sessions' writes). Absent = the repo
+ * records none; a reader then takes the row's `createdAt`. It is what the repo records, never what one process saw — so a dropped
+ * cache, a restart or another replica reads the same time, and only a later activity moves it.
+ */
+export type SessionRow<TMetadata extends SessionMetadata = SessionMetadata> = TMetadata & {
+    readonly lastActiveAt?: number;
+};
+/** 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 +1087,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;
@@ -1059,7 +1098,12 @@ export interface SessionForkOptions {
 export interface SessionRepo<TMetadata extends SessionMetadata = SessionMetadata, TCreateOptions extends SessionCreateOptions = SessionCreateOptions, TListOptions = void> {
     create(options: TCreateOptions): Promise<Session<TMetadata>>;
     open(metadata: TMetadata): Promise<Session<TMetadata>>;
-    list(options?: TListOptions): Promise<TMetadata[]>;
+    /** Every ordinary row (placed rows are not listed), each with the newest write the repo holds for it ({@link SessionRow}), in no
+     *  promised order. The source `TtlSessionStore.list` reads; the store, not the repo, orders, filters and pages. */
+    list(options?: TListOptions): Promise<SessionRow<TMetadata>[]>;
+    /** Record activity on the row now: the time {@link list} answers as the row's `lastActiveAt` moves to now. A missing row is a no-op; a
+     *  fault rejects. Optional: a repo without it records only what its writes record. */
+    touch?(sessionId: string): Promise<void>;
     delete(metadata: TMetadata): Promise<void>;
     /** A fork is a NEW row: `options.id` equal to the source's id is refused (`invalid_fork_target`) — onto its source it would mint a new occupant over the source's own transcript. */
     fork(source: TMetadata, options: SessionForkOptions & TCreateOptions): Promise<Session<TMetadata>>;
@@ -1070,10 +1114,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 +1205,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";
@@ -1442,6 +1489,8 @@ export interface AgentHarnessOptions<TSkill extends Skill = Skill, TPromptTempla
      * texts themselves never change.
      */
     abortResultDetails?: () => Record<string, unknown> | undefined;
+    /** The host's station around one tool execution, forwarded verbatim to the loop config (`AgentLoopConfig.executeTool`). */
+    executeTool?: import("../loop/types.js").AgentLoopConfig["executeTool"];
     /**
      * C2: the loop's recovery/terminal trace sink, forwarded to `runAgentLoop`'s trace
      * parameter (previously test-only — never passed in production, so the loop's six self-heal

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 } : {}),
     };
 }