@nifrajs/coding-agent 3.5.0 → 4.0.0

package/src/approvals.ts

@@ -52,10 +52,16 @@ export interface ApprovalManagerOptions {
 
 interface PendingApproval {
   readonly request: ApprovalRequest
-  readonly resolve: (approved: boolean) => void
+  /** Settles with the decision; it exists before `onRequired` runs, so no decision can miss it. */
+  readonly decided: Promise<boolean>
+  readonly settle: (approved: boolean) => void
   readonly timer: ReturnType<typeof setTimeout>
 }
 
+/** The agent protocol's token alphabet, so every protocol-valid id is accepted here too. */
+const ID_TOKEN = /^[A-Za-z0-9._:/-]{1,128}$/
+const MAX_ACTION_LENGTH = 512
+
 /**
  * Small approval broker shared by RPC, Workbench, and workflow extensions.
  *
@@ -89,38 +95,37 @@ export class ApprovalManager {
 
   /** Convert a streamed backend approval event into a resolvable pending request. */
   async observe(event: AgentApprovalRequiredEvent): Promise<ApprovalRequest | undefined> {
-    if (this.pendingApprovals.has(event.approvalId))
-      return this.pendingApprovals.get(event.approvalId)?.request
-    return this.create({
+    const existing = this.pendingApprovals.get(event.approvalId)
+    if (existing !== undefined) return existing.request
+    const pending = await this.create({
       id: event.approvalId,
       sessionId: event.sessionId,
       turnId: event.turnId,
-      action: event.action,
+      // The protocol bounds text more loosely; a long label must not fail the backend's turn.
+      action: event.action.slice(0, MAX_ACTION_LENGTH),
       capability: event.capability,
       ...(event.reason === undefined ? {} : { reason: event.reason }),
     })
+    return pending?.request
   }
 
-  /** Publish a pending approval without waiting for its decision (useful for transports). */
+  /**
+   * Publish a pending approval without waiting for its decision (useful for transports). Returns
+   * `undefined` when the broker is full or an approval with the same id is still pending.
+   */
   async offer(
     input: Omit<ApprovalRequest, "createdAt" | "expiresAt">,
   ): Promise<ApprovalRequest | undefined> {
-    return this.create(input)
+    return (await this.create(input))?.request
   }
 
-  /** Create a host-owned approval that can be awaited by a workflow or extension. */
+  /**
+   * Create a host-owned approval that can be awaited by a workflow or extension. Resolves `false`
+   * when the broker is full or an approval with the same id is still pending.
+   */
   async request(input: Omit<ApprovalRequest, "createdAt" | "expiresAt">): Promise<boolean> {
-    const request = await this.offer(input)
-    if (request === undefined) return false
-    const pending = this.pendingApprovals.get(request.id)
-    if (pending === undefined) return false
-    return new Promise<boolean>((resolve) => {
-      // Replace the resolver only for this host-owned request; observed backend requests are
-      // intentionally notification-only and are resolved through `resolve`.
-      const current = this.pendingApprovals.get(request.id)
-      if (current === undefined) return resolve(false)
-      this.pendingApprovals.set(request.id, { ...current, resolve })
-    })
+    const pending = await this.create(input)
+    return pending === undefined ? false : pending.decided
   }
 
   /**
@@ -145,49 +150,68 @@ export class ApprovalManager {
         code: bound.vector !== coordinate.vector ? "stale_vector" : "identity_mismatch",
       }
     if (!coordinateIsFresh(bound, now)) {
-      this.resolve(coordinate.requestId, false, "approval expired")
+      this.settle(coordinate.requestId, false, "approval expired")
       return { ok: false, code: "expired" }
     }
     if (nextApprovalState("pending", approved ? "approve" : "deny") === undefined)
       return { ok: false, code: "illegal_transition" }
-    const decision = this.resolve(coordinate.requestId, approved)
+    const decision = this.settle(coordinate.requestId, approved)
     if (decision === undefined) return { ok: false, code: "unknown_boundary" }
     return { ok: true, decision }
   }
 
+  /**
+   * Settle a pending approval by id. An approval opened with a coordinate is approved only through
+   * {@link resolveMatched}; this untyped path can still deny it, and returns `undefined` for an
+   * approve.
+   */
   resolve(approvalId: string, approved: boolean, reason?: string): ApprovalDecision | undefined {
+    if (
+      approved === true &&
+      this.pendingApprovals.get(approvalId)?.request.coordinate !== undefined
+    )
+      return undefined
+    return this.settle(approvalId, approved, reason)
+  }
+
+  close(): void {
+    for (const approvalId of this.pendingApprovals.keys())
+      this.settle(approvalId, false, "approval manager closed")
+  }
+
+  private settle(
+    approvalId: string,
+    approved: boolean,
+    reason?: string,
+  ): ApprovalDecision | undefined {
     const pending = this.pendingApprovals.get(approvalId)
     if (pending === undefined) return undefined
     clearTimeout(pending.timer)
     this.pendingApprovals.delete(approvalId)
-    pending.resolve(approved === true)
+    pending.settle(approved === true)
     const decision: ApprovalDecision = {
       approvalId,
       approved: approved === true,
       ...(reason === undefined ? {} : { reason: reason.slice(0, 512) }),
       at: Date.now(),
     }
-    void this.options.onResolved?.(decision)
+    // A failing broadcast must not become an unhandled rejection in the host.
+    Promise.resolve(this.options.onResolved?.(decision)).catch(() => {})
     return decision
   }
 
-  close(): void {
-    for (const approvalId of this.pendingApprovals.keys())
-      this.resolve(approvalId, false, "approval manager closed")
-  }
-
   private async create(
     input: Omit<ApprovalRequest, "createdAt" | "expiresAt">,
-  ): Promise<ApprovalRequest | undefined> {
+  ): Promise<PendingApproval | undefined> {
     if (this.pendingApprovals.size >= this.options.maxPending) return undefined
-    if (!/^[A-Za-z0-9._:-]{1,128}$/.test(input.id))
-      throw new TypeError("approvals: approval id is invalid")
-    if (!/^[A-Za-z0-9._:-]{1,128}$/.test(input.sessionId))
-      throw new TypeError("approvals: session id is invalid")
-    if (!input.action || input.action.length > 512)
+    if (!ID_TOKEN.test(input.id)) throw new TypeError("approvals: approval id is invalid")
+    if (!ID_TOKEN.test(input.sessionId)) throw new TypeError("approvals: session id is invalid")
+    if (!input.action || input.action.length > MAX_ACTION_LENGTH)
       throw new TypeError("approvals: action is empty or too long")
     if (!input.capability || input.capability.length > 128)
       throw new TypeError("approvals: capability is empty or too long")
+    // Replacing a pending id would orphan the waiter of the request already holding it.
+    if (this.pendingApprovals.has(input.id)) return undefined
     const createdAt = Date.now()
     const request: ApprovalRequest = Object.freeze({
       ...input,
@@ -197,22 +221,15 @@ export class ApprovalManager {
       createdAt,
       expiresAt: createdAt + this.options.timeoutMs,
     })
-    let resolveApproval = (_approved: boolean): void => {}
+    const { promise: decided, resolve: settle } = Promise.withResolvers<boolean>()
     const timer = setTimeout(() => {
-      this.resolve(request.id, false, "approval timed out")
+      this.settle(request.id, false, "approval timed out")
     }, this.options.timeoutMs)
     ;(timer as unknown as { unref?: () => void }).unref?.()
-    const pending: PendingApproval = {
-      request,
-      resolve: (approved) => resolveApproval(approved),
-      timer,
-    }
+    const pending: PendingApproval = { request, decided, settle, timer }
     this.pendingApprovals.set(request.id, pending)
     await this.options.onRequired?.(request)
-    // A backend-observed request is resolved through `resolve`; a host request swaps this closure
-    // from the promise below before returning to the workflow.
-    resolveApproval = (_approved: boolean): void => {}
-    return request
+    return pending
   }
 }
 

package/src/cli.ts

@@ -25,10 +25,13 @@ Usage:
   nifra-agent [--backend pi|replay] [--cwd <dir>] [--once <prompt>]
               [--json] [--no-session] [--session-dir <dir>] [--session-id <id>]
               [--verify-after-turn check,assure] [--max-repair-attempts <n>]
-              [--pi <command>] [--replay <file>]
+              [--pi <command>] [--replay <file>] [--extensions]
   nifra-agent --migrate-session <id> --migrate-from <dir> --migrate-to <dir> [--json]
   nifra-agent --rpc [--cwd <dir>] [--host 127.0.0.1] [--port 0] [--expose-error-stacks]
 
+--extensions loads and runs .nifra/extensions/** from --cwd. That is the project's own code: pass it
+only for a repository you trust. Without it no extension is loaded.
+
 Commands in interactive mode:
   /reload       reload Pi or Nifra extensions
   /compact      compact the bounded prompt window
@@ -64,6 +67,7 @@ export interface CliOptions {
   readonly migrationTarget?: string
   readonly verifyAfterTurn: readonly ("check" | "assure" | "test")[]
   readonly maxRepairAttempts: number
+  readonly extensions: boolean
 }
 
 export function parseArgs(args: readonly string[]): CliOptions {
@@ -72,6 +76,7 @@ export function parseArgs(args: readonly string[]): CliOptions {
   let once: string | undefined
   let json = false
   let noSession = false
+  let extensions = false
   let piCommand = "pi"
   let replayFile: string | undefined
   let sessionDir: string | undefined
@@ -93,6 +98,7 @@ export function parseArgs(args: readonly string[]): CliOptions {
     else if (arg === "--once" || arg === "--message") once = args[++index]
     else if (arg === "--json") json = true
     else if (arg === "--no-session") noSession = true
+    else if (arg === "--extensions") extensions = true
     else if (arg === "--session-dir") sessionDir = resolve(args[++index] ?? "")
     else if (arg === "--session-id") sessionId = args[++index]
     else if (arg === "--migrate-session") migrateSession = args[++index]
@@ -142,6 +148,7 @@ export function parseArgs(args: readonly string[]): CliOptions {
     ...(once === undefined ? {} : { once }),
     json,
     noSession,
+    extensions,
     piCommand,
     ...(replayFile === undefined ? {} : { replayFile }),
     ...(sessionDir === undefined ? {} : { sessionDir }),
@@ -215,7 +222,9 @@ async function main(): Promise<void> {
           enableNifraTools: true,
           ...(options.sessionDir === undefined ? {} : { sessionDir: options.sessionDir }),
         })
-  const extensionRoots = await discoverExtensions(options.cwd)
+  // A module's top-level code runs as soon as it is imported, before any capability check can refuse
+  // it, so a cloned repository's extensions load only when the user asks.
+  const extensionRoots = options.extensions ? await discoverExtensions(options.cwd) : []
   const extensions = new ExtensionHost({
     cwd: options.cwd,
     roots: extensionRoots,

package/src/handoffs.ts

@@ -27,6 +27,8 @@ import type { ApprovalManager } from "./approvals.ts"
 import { ChildVectorTracker } from "./orchestration/policy.ts"
 
 const ID_TOKEN = /^[A-Za-z0-9._:-]{1,128}$/
+/** The agent protocol's token alphabet, which the approval broker accepts for session ids. */
+const SESSION_TOKEN = /^[A-Za-z0-9._:/-]{1,128}$/
 
 /** Stable, content-free reasons the coordinator refuses a handoff request or decision. */
 export type HandoffRejection =
@@ -136,7 +138,8 @@ export class HandoffCoordinator {
       !input.capability ||
       input.capability.length > 128 ||
       !input.from ||
-      input.from.length > 128
+      input.from.length > 128 ||
+      (input.sessionId !== undefined && !SESSION_TOKEN.test(input.sessionId))
     )
       throw new HandoffError("invalid_handoff")
     if (this.records.has(input.requestId)) throw new HandoffError("duplicate")
@@ -162,13 +165,18 @@ export class HandoffCoordinator {
     }
     this.records.set(input.requestId, record)
 
+    // The mirror carries the boundary's coordinate, so only a matched decision approves it. It is a
+    // notification: a broker that is full or fails to broadcast leaves the handoff itself intact.
     if (record.requireApproval && this.approvals !== undefined)
-      void this.approvals.offer({
-        id: input.requestId,
-        sessionId: input.sessionId ?? input.runId,
-        action: "handoff",
-        capability: input.capability,
-      })
+      this.approvals
+        .offer({
+          id: input.requestId,
+          sessionId: input.sessionId ?? input.runId,
+          action: "handoff",
+          capability: input.capability,
+          coordinate,
+        })
+        .catch(() => {})
     return this.view(record)
   }
 
@@ -264,7 +272,11 @@ export class HandoffCoordinator {
 
   private settleApproval(record: HandoffRecord, op: string): void {
     if (!record.requireApproval || this.approvals === undefined) return
-    this.approvals.resolve(record.coordinate.requestId, op === "accept" || op === "resolve")
+    this.approvals.resolveMatched(
+      record.coordinate,
+      op === "accept" || op === "resolve",
+      this.now(),
+    )
   }
 
   private isTerminal(state: HandoffLifecycleState): boolean {

package/src/index.ts

@@ -133,6 +133,8 @@ export {
 } from "./sessions.ts"
 export {
   BoundedSubagentRunner,
+  type SubagentAbandonment,
+  type SubagentAbandonmentLedger,
   type SubagentExecutor,
   type SubagentResult,
   type SubagentRunnerOptions,

package/src/native.ts

@@ -123,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
 }
 
@@ -156,6 +161,7 @@ interface NativeSession {
   readonly id: string
   readonly cwd: string
   readonly messages: NativeMessage[]
+  historyChars: number
   controller: AbortController
   snapshot: AgentSessionSnapshot
   active: AgentEventStream | undefined
@@ -179,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>()
@@ -189,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 (
@@ -199,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) ||
@@ -243,6 +254,7 @@ export class NifraBackend implements AgentBackend {
       id,
       cwd: input.cwd,
       messages: [],
+      historyChars: 0,
       controller: new AbortController(),
       snapshot,
       active: undefined,
@@ -376,14 +388,15 @@ export class NifraBackend implements AgentBackend {
     }
     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++) {
         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,
@@ -397,7 +410,7 @@ export class NifraBackend implements AgentBackend {
         this.assertCurrentTurn(session, stream, turnId, signal)
         if (response.type === "text") {
           const text = boundedText(response.text, this.options.maxMessageChars)
-          session.messages.push({ role: "assistant", text })
+          this.remember(session, { role: "assistant", text })
           this.emit(session, { type: "assistant.message", turnId, text })
           this.finish(session, stream)
           return
@@ -412,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()
@@ -449,7 +462,7 @@ 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
           }
         }
@@ -457,7 +470,7 @@ export class NifraBackend implements AgentBackend {
           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,
@@ -472,7 +485,7 @@ export class NifraBackend implements AgentBackend {
             error instanceof Error ? error.message : error,
             this.options.maxMessageChars,
           )
-          session.messages.push({ role: "tool", name: tool.name, text: message })
+          this.remember(session, { role: "tool", name: tool.name, text: message })
           this.emit(session, {
             type: "tool.completed",
             turnId,
@@ -781,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> {

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)

package/src/rpc.ts

@@ -162,17 +162,19 @@ export class CodingAgentRpcServer {
     const url = new URL(request.url)
     if (url.pathname === "/health" && request.method === "GET")
       return this.response({ ok: true, protocol: 1 }, 200, cors)
-    const backoffMs = this.authBackoffMs()
-    if (backoffMs > 0) {
-      const throttledCors = new Headers(cors)
-      throttledCors.set("retry-after", String(Math.ceil(backoffMs / 1000)))
-      return this.response(
-        { error: { code: "auth_throttled", message: "too many failed authorization attempts" } },
-        429,
-        throttledCors,
-      )
-    }
     if (!authorized(request, this.token)) {
+      // Only failed attempts are throttled. A caller holding the token is served during a backoff,
+      // or anyone who can reach the port could keep the real client locked out with wrong guesses.
+      const backoffMs = this.authBackoffMs()
+      if (backoffMs > 0) {
+        const throttledCors = new Headers(cors)
+        throttledCors.set("retry-after", String(Math.ceil(backoffMs / 1000)))
+        return this.response(
+          { error: { code: "auth_throttled", message: "too many failed authorization attempts" } },
+          429,
+          throttledCors,
+        )
+      }
       this.noteAuthFailure()
       return this.response(
         { error: { code: "unauthorized", message: "agent RPC authorization required" } },
@@ -180,7 +182,6 @@ export class CodingAgentRpcServer {
         cors,
       )
     }
-    this.noteAuthSuccess()
     if (url.pathname !== "/rpc" || request.method !== "POST")
       return this.response(
         { error: { code: "not_found", message: "unknown agent RPC endpoint" } },
@@ -635,7 +636,7 @@ export class CodingAgentRpcServer {
     const now = Date.now()
     if (this.authFailures === 0) return 0
     if (now - this.authLastFailureAt > AUTH_FAILURE_WINDOW_MS) {
-      this.noteAuthSuccess()
+      this.resetAuthFailures()
       return 0
     }
     return Math.max(0, this.authBackoffUntil - now)
@@ -653,7 +654,7 @@ export class CodingAgentRpcServer {
     }
   }
 
-  private noteAuthSuccess(): void {
+  private resetAuthFailures(): void {
     this.authFailures = 0
     this.authLastFailureAt = 0
     this.authBackoffUntil = 0