@nifrajs/coding-agent 3.3.0 → 4.0.0

package/src/native.ts

@@ -13,6 +13,7 @@ import {
   agentError,
   type CreateSessionInput,
   createAgentEventStream,
+  isAgentEvent,
   type ReloadResult,
   type SendMessageInput,
 } from "@nifrajs/agent-protocol"
@@ -122,6 +123,11 @@ export interface NifraBackendOptions {
   readonly approvalTimeoutMs?: number
   readonly maxSteps?: number
   readonly maxMessageChars?: number
+  /**
+   * Character budget for the conversation a session sends to the model (default 1 MiB). Past it,
+   * whole earlier turns are dropped, oldest first; the current turn is always sent in full.
+   */
+  readonly maxHistoryChars?: number
   readonly now?: () => number
 }
 
@@ -148,15 +154,19 @@ interface NativePendingApproval {
   readonly resolve: (resolution: NativeApprovalResolution) => void
   readonly timer: ReturnType<typeof setTimeout>
   readonly onAbort: () => void
+  readonly signal: AbortSignal
 }
 
 interface NativeSession {
   readonly id: string
   readonly cwd: string
   readonly messages: NativeMessage[]
+  historyChars: number
   controller: AbortController
   snapshot: AgentSessionSnapshot
   active: AgentEventStream | undefined
+  turnId: string | undefined
+  turnAbortCleanup: (() => void) | undefined
   seq: number
   extensionRevision: number
   closed: boolean
@@ -175,7 +185,9 @@ export class NifraBackend implements AgentBackend {
     name: "nifra",
     capabilities: Object.freeze(["sessions", "extensions", "reload", "approvals", "streaming"]),
   })
-  private readonly options: Required<Pick<NifraBackendOptions, "maxSteps" | "maxMessageChars">> &
+  private readonly options: Required<
+    Pick<NifraBackendOptions, "maxSteps" | "maxMessageChars" | "maxHistoryChars">
+  > &
     NifraBackendOptions
   private readonly sessions = new Map<string, NativeSession>()
   private readonly pendingApprovals = new Map<string, NativePendingApproval>()
@@ -185,6 +197,7 @@ export class NifraBackend implements AgentBackend {
       ...options,
       maxSteps: options.maxSteps ?? 32,
       maxMessageChars: options.maxMessageChars ?? 64 * 1024,
+      maxHistoryChars: options.maxHistoryChars ?? 1024 * 1024,
       tools: Object.freeze([...(options.tools ?? [])]),
     })
     if (
@@ -195,6 +208,8 @@ export class NifraBackend implements AgentBackend {
       throw new RangeError("nifra backend: maxSteps must be between 1 and 512")
     if (!Number.isSafeInteger(this.options.maxMessageChars) || this.options.maxMessageChars < 256)
       throw new RangeError("nifra backend: maxMessageChars must be at least 256")
+    if (!Number.isSafeInteger(this.options.maxHistoryChars) || this.options.maxHistoryChars < 256)
+      throw new RangeError("nifra backend: maxHistoryChars must be at least 256")
     if (
       this.options.approvalTimeoutMs !== undefined &&
       (!Number.isSafeInteger(this.options.approvalTimeoutMs) ||
@@ -205,6 +220,20 @@ export class NifraBackend implements AgentBackend {
   }
 
   async createSession(input: CreateSessionInput): Promise<AgentSessionSnapshot> {
+    if (
+      typeof input.cwd !== "string" ||
+      input.cwd.length === 0 ||
+      input.cwd.length > 4_096 ||
+      input.cwd.includes("\0")
+    )
+      throw new TypeError("nifra backend: cwd must be a bounded non-empty path")
+    if (
+      input.capabilities !== undefined &&
+      (!Array.isArray(input.capabilities) ||
+        input.capabilities.length > 256 ||
+        !input.capabilities.every((value) => boundedApprovalToken(value)))
+    )
+      throw new TypeError("nifra backend: capabilities must be bounded tokens")
     const id = input.sessionId ?? crypto.randomUUID()
     if (!/^[a-zA-Z0-9._:-]{1,128}$/.test(id))
       throw new TypeError("nifra backend: sessionId must be a bounded token")
@@ -225,9 +254,12 @@ export class NifraBackend implements AgentBackend {
       id,
       cwd: input.cwd,
       messages: [],
+      historyChars: 0,
       controller: new AbortController(),
       snapshot,
       active: undefined,
+      turnId: undefined,
+      turnAbortCleanup: undefined,
       seq: 0,
       extensionRevision: 0,
       closed: false,
@@ -251,30 +283,38 @@ export class NifraBackend implements AgentBackend {
     session.cancelled = false
     session.controller = new AbortController()
     const signal = session.controller.signal
+    const turnId = crypto.randomUUID()
+    session.turnId = turnId
     if (input.signal !== undefined) {
       const externalSignal = input.signal
-      if (externalSignal.aborted) session.controller.abort(externalSignal.reason)
-      else
-        externalSignal.addEventListener(
-          "abort",
-          () => session.controller.abort(externalSignal.reason),
-          { once: true },
+      const onAbort = (): void => {
+        // Capture the turn identity. A request signal must never abort a later turn that reused
+        // this session after the original stream settled.
+        if (
+          session.active !== stream ||
+          session.turnId !== turnId ||
+          session.controller.signal !== signal
         )
+          return
+        void this.cancelTurn(session, stream, turnId, "cancelled")
+      }
+      if (externalSignal.aborted) onAbort()
+      else {
+        externalSignal.addEventListener("abort", onAbort, { once: true })
+        session.turnAbortCleanup = () => externalSignal.removeEventListener("abort", onAbort)
+        // Abort can race the registration between the check above and addEventListener.
+        if (externalSignal.aborted) onAbort()
+      }
     }
-    void this.run(session, input.message, stream, signal)
+    void this.run(session, input.message, stream, signal, turnId)
     return stream
   }
 
   async cancel(sessionId: string, reason = "cancelled"): Promise<void> {
     const session = this.requireSession(sessionId)
     if (session.closed) return
-    const stream = session.active
-    session.cancelled = true
-    session.controller.abort(reason)
-    this.update(session, "stopped")
-    this.emit(session, { type: "session.stopped", reason })
-    stream?.complete()
-    session.active = undefined
+    if (session.active === undefined) return
+    await this.cancelTurn(session, session.active, session.turnId, reason)
   }
 
   async snapshot(sessionId: string): Promise<AgentSessionSnapshot> {
@@ -326,9 +366,12 @@ export class NifraBackend implements AgentBackend {
     if (session.closed) return
     session.closed = true
     session.cancelled = true
+    session.turnAbortCleanup?.()
+    session.turnAbortCleanup = undefined
     session.controller.abort("closed")
     session.active?.complete()
     session.active = undefined
+    session.turnId = undefined
     this.sessions.delete(sessionId)
   }
 
@@ -337,18 +380,23 @@ export class NifraBackend implements AgentBackend {
     message: string,
     stream: AgentEventStream,
     signal: AbortSignal,
+    turnId: string,
   ): Promise<void> {
-    const turnId = crypto.randomUUID()
+    if (!this.isCurrentTurn(session, stream, turnId, signal)) {
+      stream.complete()
+      return
+    }
     this.update(session, "running", turnId)
     this.emit(session, { type: "turn.started", turnId, prompt: message })
-    session.messages.push({ role: "user", text: message })
+    this.remember(session, { role: "user", text: message })
     try {
       for (let step = 0; step < this.options.maxSteps; step++) {
-        if (signal.aborted) throw new Error("native turn cancelled")
+        this.assertCurrentTurn(session, stream, turnId, signal)
+        this.trimHistory(session)
         const raw = this.options.model.complete({
           sessionId: session.id,
           cwd: session.cwd,
-          messages: Object.freeze(session.messages.map((item) => Object.freeze({ ...item }))),
+          messages: Object.freeze(session.messages.slice()),
           tools: Object.freeze(
             this.options.tools!.map((tool) => ({
               name: tool.name,
@@ -358,10 +406,12 @@ export class NifraBackend implements AgentBackend {
           ),
           signal,
         })
-        const response = await this.consumeModel(raw, session, turnId, signal)
+        const response = await this.consumeModel(raw, session, stream, turnId, signal)
+        this.assertCurrentTurn(session, stream, turnId, signal)
         if (response.type === "text") {
-          session.messages.push({ role: "assistant", text: response.text })
-          this.emit(session, { type: "assistant.message", turnId, text: response.text })
+          const text = boundedText(response.text, this.options.maxMessageChars)
+          this.remember(session, { role: "assistant", text })
+          this.emit(session, { type: "assistant.message", turnId, text })
           this.finish(session, stream)
           return
         }
@@ -375,7 +425,7 @@ export class NifraBackend implements AgentBackend {
             ok: false,
             error: agentError("UNKNOWN_TOOL", `unknown native tool: ${response.name}`),
           })
-          session.messages.push({ role: "tool", name: response.name, text: "unknown tool" })
+          this.remember(session, { role: "tool", name: response.name, text: "unknown tool" })
           continue
         }
         const callId = crypto.randomUUID()
@@ -391,6 +441,7 @@ export class NifraBackend implements AgentBackend {
           typeof tool.requiresApproval === "function"
             ? await tool.requiresApproval(response.input)
             : tool.requiresApproval === true
+        this.assertCurrentTurn(session, stream, turnId, signal)
         if (needsApproval) {
           const resolution = await this.requestApproval(
             session,
@@ -400,6 +451,7 @@ export class NifraBackend implements AgentBackend {
             response.input,
             signal,
           )
+          this.assertCurrentTurn(session, stream, turnId, signal)
           if (!resolution.approved) {
             const code = resolution.errorCode ?? "APPROVAL_DENIED"
             this.emit(session, {
@@ -410,14 +462,15 @@ export class NifraBackend implements AgentBackend {
               ok: false,
               error: agentError(code, boundedApprovalMessage(code, tool.name, resolution.reason)),
             })
-            session.messages.push({ role: "tool", name: tool.name, text: code })
+            this.remember(session, { role: "tool", name: tool.name, text: code })
             continue
           }
         }
         try {
           const output = await execute(response.input, { cwd: session.cwd, signal })
+          this.assertCurrentTurn(session, stream, turnId, signal)
           const text = boundedText(output)
-          session.messages.push({ role: "tool", name: tool.name, text })
+          this.remember(session, { role: "tool", name: tool.name, text })
           this.emit(session, {
             type: "tool.completed",
             turnId,
@@ -427,8 +480,12 @@ export class NifraBackend implements AgentBackend {
             output: text,
           })
         } catch (error) {
-          const message = error instanceof Error ? error.message : String(error)
-          session.messages.push({ role: "tool", name: tool.name, text: message })
+          if (signal.aborted || !this.isCurrentTurn(session, stream, turnId, signal)) throw error
+          const message = boundedText(
+            error instanceof Error ? error.message : error,
+            this.options.maxMessageChars,
+          )
+          this.remember(session, { role: "tool", name: tool.name, text: message })
           this.emit(session, {
             type: "tool.completed",
             turnId,
@@ -441,50 +498,57 @@ export class NifraBackend implements AgentBackend {
       }
       throw new Error("native turn exceeded maxSteps")
     } catch (error) {
-      if (session.closed || session.cancelled) {
+      if (!this.isCurrentTurn(session, stream, turnId, signal)) {
         stream.complete()
-        if (session.active === stream) session.active = undefined
         return
       }
-      this.update(session, signal.aborted ? "stopped" : "failed")
+      if (signal.aborted || session.cancelled) {
+        await this.cancelTurn(session, stream, turnId, "cancelled")
+        return
+      }
+      this.update(session, "failed")
       this.emit(session, {
         type: "session.failed",
         error: agentError(
-          signal.aborted ? "TURN_CANCELLED" : "NATIVE_TURN_FAILED",
-          error instanceof Error ? error.message : String(error),
+          "NATIVE_TURN_FAILED",
+          boundedText(error instanceof Error ? error.message : error, 4_096),
         ),
         recoverable: true,
       })
       stream.complete()
-      session.active = undefined
+      this.clearTurn(session, stream, turnId)
     }
   }
 
   private async consumeModel(
     raw: ReturnType<NativeModelPort["complete"]>,
     session: NativeSession,
+    stream: AgentEventStream,
     turnId: string,
     signal: AbortSignal,
   ): Promise<NativeModelResponse> {
     if (isAsyncIterable<NativeModelChunk>(raw)) {
       let response: NativeModelResponse | undefined
       for await (const chunk of raw) {
-        if (signal.aborted) throw new Error("native turn cancelled")
+        this.assertCurrentTurn(session, stream, turnId, signal)
         if (chunk.type === "text_delta")
           this.emit(session, { type: "assistant.delta", turnId, text: chunk.text })
         else response = chunk.response
       }
       if (response === undefined) throw new Error("native model stream ended without a response")
+      this.assertCurrentTurn(session, stream, turnId, signal)
       return response
     }
-    return await raw
+    const response = await raw
+    this.assertCurrentTurn(session, stream, turnId, signal)
+    return response
   }
 
   private finish(session: NativeSession, stream: AgentEventStream): void {
     this.update(session, "idle")
     this.emit(session, { type: "session.completed", snapshot: session.snapshot })
     stream.complete()
-    session.active = undefined
+    this.clearTurn(session, stream, session.turnId)
   }
 
   private requestApproval(
@@ -526,6 +590,7 @@ export class NifraBackend implements AgentBackend {
         resolve,
         timer,
         onAbort,
+        signal,
       }
       this.pendingApprovals.set(approvalId, pending)
       signal.addEventListener("abort", onAbort, { once: true })
@@ -595,7 +660,7 @@ export class NifraBackend implements AgentBackend {
     const pending = this.pendingApprovals.get(approvalId)
     if (pending === undefined || pending.sessionId !== session.id) return undefined
     clearTimeout(pending.timer)
-    session.controller.signal.removeEventListener("abort", pending.onAbort)
+    pending.signal.removeEventListener("abort", pending.onAbort)
     this.pendingApprovals.delete(approvalId)
     const boundedReason = reason === undefined ? undefined : boundedApprovalText(reason, 512)
     const resolution: NativeApprovalResolution = Object.freeze({
@@ -614,6 +679,76 @@ export class NifraBackend implements AgentBackend {
     return resolution
   }
 
+  private async cancelTurn(
+    session: NativeSession,
+    expectedStream: AgentEventStream | undefined,
+    expectedTurnId: string | undefined,
+    reason: string,
+  ): Promise<void> {
+    if (
+      expectedStream !== undefined &&
+      (session.active !== expectedStream || session.turnId !== expectedTurnId)
+    )
+      return
+    const stream = session.active
+    const turnId = session.turnId
+    const stopReason = boundedText(reason, 512) || "cancelled"
+    session.cancelled = true
+    this.clearTurnSignal(session)
+    try {
+      session.controller.abort(stopReason)
+    } catch {
+      // AbortController.abort is normally infallible; lifecycle cleanup must still complete if a
+      // host supplies an unusual controller implementation.
+    }
+    this.update(session, "stopped")
+    this.emit(session, { type: "session.stopped", reason: stopReason })
+    stream?.complete()
+    this.clearTurn(session, stream, turnId)
+  }
+
+  private clearTurnSignal(session: NativeSession): void {
+    session.turnAbortCleanup?.()
+    session.turnAbortCleanup = undefined
+  }
+
+  private clearTurn(
+    session: NativeSession,
+    stream: AgentEventStream | undefined,
+    turnId: string | undefined,
+  ): void {
+    if (stream !== undefined && session.active !== stream) return
+    if (turnId !== undefined && session.turnId !== turnId) return
+    this.clearTurnSignal(session)
+    if (stream === undefined || session.active === stream) session.active = undefined
+    if (turnId === undefined || session.turnId === turnId) session.turnId = undefined
+  }
+
+  private isCurrentTurn(
+    session: NativeSession,
+    stream: AgentEventStream,
+    turnId: string,
+    signal: AbortSignal,
+  ): boolean {
+    return (
+      !session.closed &&
+      !session.cancelled &&
+      session.active === stream &&
+      session.turnId === turnId &&
+      session.controller.signal === signal
+    )
+  }
+
+  private assertCurrentTurn(
+    session: NativeSession,
+    stream: AgentEventStream,
+    turnId: string,
+    signal: AbortSignal,
+  ): void {
+    if (signal.aborted || !this.isCurrentTurn(session, stream, turnId, signal))
+      throw new Error("native turn cancelled")
+  }
+
   private emit(
     session: NativeSession,
     payload: import("@nifrajs/agent-protocol").AgentEventPayload,
@@ -625,6 +760,8 @@ export class NifraBackend implements AgentBackend {
       at: this.now(),
       ...payload,
     }) as AgentEvent
+    if (!isAgentEvent(event))
+      throw new Error("nifra backend emitted an event outside protocol bounds")
     session.snapshot = Object.freeze({
       ...session.snapshot,
       lastSeq: event.seq,
@@ -640,7 +777,9 @@ export class NifraBackend implements AgentBackend {
   ): void {
     const next = { ...session.snapshot, status, updatedAt: this.now(), lastSeq: session.seq }
     session.snapshot = Object.freeze(
-      status === "running" && turnId !== undefined ? { ...next, activeTurnId: turnId } : next,
+      status === "running" && turnId !== undefined
+        ? { ...next, activeTurnId: turnId }
+        : removeActiveTurn(next),
     )
     if (session.active !== undefined)
       this.emit(session, { type: "session.updated", snapshot: session.snapshot })
@@ -655,6 +794,26 @@ export class NifraBackend implements AgentBackend {
   private now(): number {
     return this.options.now?.() ?? Date.now()
   }
+
+  private remember(session: NativeSession, message: NativeMessage): void {
+    session.messages.push(Object.freeze(message))
+    session.historyChars += messageChars(message)
+  }
+
+  private trimHistory(session: NativeSession): void {
+    while (session.historyChars > this.options.maxHistoryChars) {
+      const nextTurn = session.messages.findIndex(
+        (item, index) => index > 0 && item.role === "user",
+      )
+      if (nextTurn === -1) return
+      for (const item of session.messages.splice(0, nextTurn))
+        session.historyChars -= messageChars(item)
+    }
+  }
+}
+
+function messageChars(message: NativeMessage): number {
+  return message.text.length + (message.name?.length ?? 0)
 }
 
 function isAsyncIterable<T>(value: unknown): value is AsyncIterable<T> {
@@ -664,12 +823,20 @@ function isAsyncIterable<T>(value: unknown): value is AsyncIterable<T> {
 function boundedText(value: unknown, maxChars = 64 * 1024): string {
   try {
     const text = typeof value === "string" ? value : JSON.stringify(value)
-    return text.length > maxChars ? `${text.slice(0, maxChars)}…[truncated]` : text
+    if (typeof text !== "string") return "[unserializable tool output]"
+    const suffix = "…[truncated]"
+    return text.length > maxChars
+      ? `${text.slice(0, Math.max(0, maxChars - suffix.length))}${suffix}`
+      : text
   } catch {
     return "[unserializable tool output]"
   }
 }
 
+function boundedApprovalToken(value: unknown): value is string {
+  return typeof value === "string" && /^[A-Za-z0-9._:/-]{1,128}$/.test(value)
+}
+
 function boundedApprovalText(value: string, maxChars: number): string {
   const text = value.trim()
   if (text.length === 0) return "native tool"
@@ -701,3 +868,10 @@ function failedStream(error: unknown): AgentEventStream {
   stream.fail(error)
   return stream
 }
+
+function removeActiveTurn(
+  snapshot: Omit<AgentSessionSnapshot, "activeTurnId"> & { readonly activeTurnId?: string },
+): Omit<AgentSessionSnapshot, "activeTurnId"> {
+  const { activeTurnId: _activeTurnId, ...withoutActiveTurn } = snapshot
+  return withoutActiveTurn
+}

package/src/orchestration/compile.ts

@@ -19,7 +19,11 @@ import type {
   RunPlan,
 } from "@nifrajs/agent-protocol"
 import { parseRunPlan } from "@nifrajs/agent-protocol"
-import { BoundedSubagentRunner } from "../subagents.ts"
+import {
+  BoundedSubagentRunner,
+  type SubagentAbandonment,
+  type SubagentAbandonmentLedger,
+} from "../subagents.ts"
 import type { WorkflowContext, WorkflowStep } from "../workflows.ts"
 import { type CatalogStep, type StepCatalog, type StepRunContext, stepVersion } from "./catalog.ts"
 import { deriveNodeEffectKey } from "./effect-key.ts"
@@ -48,6 +52,8 @@ export interface OrchestrationLimits {
   readonly maxChildren?: number
   /** Capability authority ceiling. `undefined` grants all; otherwise a step's needs must be a subset. */
   readonly allowedCapabilities?: readonly string[]
+  /** Refuse a subagent node while this many abandoned subagent executors still run. Default: no bound. */
+  readonly maxAbandonedSubagents?: number
 }
 
 const DEFAULT_MAX_NODES = 256
@@ -69,6 +75,10 @@ export interface CompileOptions {
   onNodeEffect?(nodeId: string, key: NodeEffectKey): void
   /** Called for each artifact ref a node produces through its port. */
   collectArtifact?(nodeId: string, ref: ArtifactRef): void
+  /** Called when a subagent node's run returns while its executor, which ignored the abort, keeps running. */
+  onSubagentAbandoned?(nodeId: string, abandonment: SubagentAbandonment): void
+  /** Where abandoned subagent executors are counted for `maxAbandonedSubagents`. Default: one per compile. */
+  readonly subagentAbandonment?: SubagentAbandonmentLedger
 }
 
 /**
@@ -101,7 +111,11 @@ export function compileRunPlanLayers(
     throw new CompileError(`plan has ${total} nodes over the ${maxNodes} ceiling`, "E_MAX_NODES")
 
   const layers = layerTopLevel(plan.nodes)
-  return layers.map((layer) => compileLayer(layer, options, 1))
+  const wired: CompileOptions =
+    options.subagentAbandonment === undefined
+      ? { ...options, subagentAbandonment: { abandoned: 0 } }
+      : options
+  return layers.map((layer) => compileLayer(layer, wired, 1))
 }
 
 /** Recursive node count over the whole tree. */
@@ -365,6 +379,18 @@ async function runSubagent(
     ...(options.limits?.allowedCapabilities !== undefined
       ? { allowedCapabilities: options.limits.allowedCapabilities }
       : {}),
+    ...(options.limits?.maxAbandonedSubagents !== undefined
+      ? { maxAbandoned: options.limits.maxAbandonedSubagents }
+      : {}),
+    ...(options.subagentAbandonment !== undefined
+      ? { abandonment: options.subagentAbandonment }
+      : {}),
+    ...(options.onSubagentAbandoned !== undefined
+      ? {
+          onAbandoned: (abandonment: SubagentAbandonment) =>
+            options.onSubagentAbandoned?.(node.id, abandonment),
+        }
+      : {}),
   })
   const spec = await step.spec!(context)
   const result = await runner.run(spec)

package/src/orchestration/evidence-store.ts

@@ -51,8 +51,9 @@ async function sha256Bytes(text: string): Promise<Uint8Array> {
 /**
  * The identity of one record for the terminal digest: node outcome only. `seq`, `durationMs`, and
  * `runId` are excluded so two runs of the same plan (or the same plan under a different parallel
- * schedule) produce an identical digest - the deterministic-eval anchor. Each node emits at most one
- * record per status, so XOR accumulation never cancels a distinct outcome.
+ * schedule) produce an identical digest - the deterministic-eval anchor. A retried node emits the same
+ * record more than once, so the accumulator adds hashes (mod 2^256) rather than XORing them: repeats
+ * count instead of cancelling in pairs.
  */
 function digestKey(record: RunEvidence): string {
   return canonicalJson({
@@ -97,7 +98,12 @@ class EvidenceAccumulator {
     if (record.artifacts !== undefined)
       for (const ref of record.artifacts) this.artifactRefs.push(ref)
     const hash = await sha256Bytes(digestKey(record))
-    for (let i = 0; i < 32; i++) this.acc[i] = (this.acc[i] as number) ^ (hash[i] as number)
+    let carry = 0
+    for (let i = 31; i >= 0; i--) {
+      const sum = (this.acc[i] as number) + (hash[i] as number) + carry
+      this.acc[i] = sum & 0xff
+      carry = sum >> 8
+    }
     this.pushLive(record)
   }
 

package/src/orchestration/host.ts

@@ -22,6 +22,7 @@ import type {
   RunPlan,
 } from "@nifrajs/agent-protocol"
 import { parseRunPlan, RUN_PLAN_VERSION } from "@nifrajs/agent-protocol"
+import type { SubagentAbandonment, SubagentAbandonmentLedger } from "../subagents.ts"
 import type { WorkflowStep } from "../workflows.ts"
 import { type WorkflowEvent, WorkflowRunner } from "../workflows.ts"
 import { noopArtifactPort } from "./artifact-port.ts"
@@ -92,6 +93,11 @@ export interface OrchestrationHostOptions {
    * approval requirement. A descriptor, plan, model, or extension cannot override it.
    */
   readonly policy?: HostPolicy
+  /**
+   * Called when a subagent node's run returns while its executor, which ignored the abort, keeps
+   * running. `limits.maxAbandonedSubagents` bounds how many may run at once across all runs.
+   */
+  onSubagentAbandoned?(runId: string, nodeId: string, abandonment: SubagentAbandonment): void
 }
 
 const DEFAULT_MAX_STEPS = 100_000
@@ -128,6 +134,8 @@ export class OrchestrationHost {
   private readonly vectors = new ChildVectorTracker()
   private readonly runs = new Map<string, RunRecord>()
   private counter = 0
+  private readonly subagentAbandonment: SubagentAbandonmentLedger = { abandoned: 0 }
+  private readonly onSubagentAbandoned: OrchestrationHostOptions["onSubagentAbandoned"]
 
   constructor(options: OrchestrationHostOptions) {
     this.catalog = options.catalog
@@ -135,6 +143,12 @@ export class OrchestrationHost {
     this.maxSteps = options.maxSteps ?? DEFAULT_MAX_STEPS
     this.maxDepth = options.maxDepth ?? DEFAULT_MAX_DEPTH
     this.policy = options.policy
+    this.onSubagentAbandoned = options.onSubagentAbandoned
+  }
+
+  /** Subagent executors abandoned by any run of this host that are still running. */
+  get abandonedSubagents(): number {
+    return this.subagentAbandonment.abandoned
   }
 
   /**
@@ -186,6 +200,9 @@ export class OrchestrationHost {
       planDigest,
       artifactPort,
       ...(this.limits !== undefined ? { limits: this.limits } : {}),
+      subagentAbandonment: this.subagentAbandonment,
+      onSubagentAbandoned: (nodeId, abandonment) =>
+        this.onSubagentAbandoned?.(runId, nodeId, abandonment),
       onNodeEffect: (nodeId, key) => effectKeys.set(nodeId, key),
       collectArtifact: (nodeId, ref) => {
         const list = artifacts.get(nodeId)