@wrongstack/core 0.283.1 → 0.284.0

package/dist/{agent-subagent-runner-BsuWhB28.d.ts → multi-agent-coordinator-4RCRZKjN.d.ts}

@@ -1,13 +1,14 @@
-import { T as ToolCallPipelinePayload, a as ToolWrapper, E as ExtensionRegistry, S as SystemPromptContributor, b as ToolRegistry, P as ProviderRegistry, A as AgentPipelines, c as ToolExecutorLike, d as AgentInit, e as AgentInput, R as RunResult } from './index-BhCteHAF.js';
-import { C as Container, R as ReadonlyPipeline, a as Renderer } from './pipeline-ixSFe5jg.js';
-import { E as EventBus, a as EventName, L as Listener } from './events-KmxSmvho.js';
-import { R as RetryPolicy, E as ErrorHandler } from './retry-policy-V67lBOJz.js';
+import { T as ToolCallPipelinePayload, a as ToolWrapper, E as ExtensionRegistry, S as SystemPromptContributor, b as ToolRegistry, P as ProviderRegistry, A as AgentPipelines, c as ToolExecutorLike, R as ResolvedLoopDetectionConfig, d as AgentInit, e as AgentInput, f as RunResult } from './index--Gm41aBJ.js';
+import { C as Container, R as ReadonlyPipeline, a as Renderer } from './pipeline-DGDyIohT.js';
+import { E as EventBus, a as EventName, L as Listener } from './events-Bgnh43r9.js';
+import { R as RetryPolicy, E as ErrorHandler } from './retry-policy-CQ7KwXJa.js';
 import { L as Logger } from './logger-B63L5bTg.js';
 import { T as Tracer } from './observability-D-HZN_mF.js';
-import { P as PermissionPolicy } from './permission-B6YAtNFz.js';
-import { d as Context, J as JSONSchema, c as Request, e as Response, i as ContentBlock, s as TextBlock, g as Tool, P as Provider, t as RunOptions, U as Usage } from './tool-LVSLiE1s.js';
-import { W as WireFamily, H as HookEvent, f as HookMatcher, I as InProcessHook, C as Config, M as ModelsRegistry, h as ModelRuntimeConfig } from './config-DkCbA3Bw.js';
+import { P as PermissionPolicy } from './permission-ByDKXEcG.js';
+import { d as Context, J as JSONSchema, c as Request, e as Response, i as ContentBlock, s as TextBlock, g as Tool, P as Provider, t as RunOptions, U as Usage } from './tool-BNlnIJvo.js';
 import { b as Mailbox } from './mailbox-types-BGZWrYTJ.js';
+import { W as WireFamily, H as HookEvent, f as HookMatcher, I as InProcessHook, g as HookRegistrationOptions, j as Config, M as ModelsRegistry, k as ModelRuntimeConfig } from './config-MRqn1V-u.js';
+import { EventEmitter } from 'node:events';
 
 type BridgeMessageType = 'task' | 'result' | 'progress' | 'error' | 'heartbeat' | 'stop' | 'delegate' | 'budget_threshold';
 interface BridgeMessage<T = unknown> {
@@ -260,7 +261,7 @@ interface PluginAPI {
      * context — see `HookOutcome`. Automatically removed when the plugin is
      * uninstalled. Returns an unregister function.
      */
-    registerHook(event: HookEvent, matcher: HookMatcher | undefined, hook: InProcessHook): () => void;
+    registerHook(event: HookEvent, matcher: HookMatcher | undefined, hook: InProcessHook, options?: HookRegistrationOptions | undefined): () => void;
     config: Config;
     log: Logger;
     /**
@@ -447,6 +448,8 @@ declare class Agent {
     private readonly plugins;
     readonly toolExecutor: ToolExecutorLike;
     readonly autoExtendLimit: boolean;
+    /** Resolved loop-detector settings (see `tools.loopDetection`). */
+    readonly loopDetection: ResolvedLoopDetectionConfig;
     private readonly autonomousContinue;
     readonly tracer: Tracer | undefined;
     readonly extensions: ExtensionRegistry;
@@ -788,6 +791,22 @@ declare class SubagentBudget {
     usage(): BudgetUsage;
 }
 
+/** Internal, non-user-authored budget/depth inheritance for nested directors. */
+interface SubagentSpawnLineage {
+    parentDirectorId: string;
+    /** Depth of the spawned child; root Director is depth 0. */
+    spawnDepth: number;
+    /** Hard ceiling inherited by descendants. */
+    maxSpawnDepth: number;
+    fleetBudget: {
+        maxSpawns?: number | undefined;
+        remainingSpawns?: number | undefined;
+        maxTokens?: number | undefined;
+        remainingTokens?: number | undefined;
+        maxCostUsd?: number | undefined;
+        remainingCostUsd?: number | undefined;
+    };
+}
 interface SubagentConfig {
     id?: string | undefined;
     name: string;
@@ -836,6 +855,11 @@ interface SubagentConfig {
     allowedCapabilities?: readonly string[] | undefined;
     model?: string | undefined;
     priority?: number | undefined;
+    /**
+     * Director-authored recursion/budget inheritance. Director.spawn overwrites
+     * caller input so a model cannot forge a shallower depth or larger budget.
+     */
+    spawnLineage?: SubagentSpawnLineage | undefined;
     /**
      * Working directory for this subagent's tools. Defaults to the factory's
      * cwd. AutoPhase sets this to a per-phase git worktree so parallel phases
@@ -973,6 +997,30 @@ interface SubagentError {
         stack?: string | undefined;
     } | undefined;
 }
+/**
+ * Bounded, best-effort work recovered before a non-successful task ended.
+ * This is deliberately separate from `result`: callers must not mistake an
+ * incomplete stream tail for a completed deliverable.
+ */
+interface SubagentPartialResult {
+    /** Last useful assistant text observed, capped by the coordinator. */
+    text: string;
+    /** Where the snapshot came from. */
+    source: 'stream' | 'run_result' | 'runner';
+    capturedAt: number;
+}
+/**
+ * Compact machine-readable result submitted independently from the agent's
+ * human-facing final text. Additive and optional for legacy/custom runners.
+ */
+interface SubagentStructuredReport {
+    summary: string;
+    findings: string[];
+    files_examined: string[];
+    /** 0.0 (uncertain) through 1.0 (fully verified). */
+    confidence: number;
+    suggested_next_steps: string[];
+}
 interface TaskResult<T = unknown> {
     subagentId: string;
     taskId: string;
@@ -983,6 +1031,10 @@ interface TaskResult<T = unknown> {
      * Prefer reading `error.kind` over substring-matching `error.message`.
      */
     error?: SubagentError | undefined;
+    /** Verified control-plane report, when the subagent called submit_result. */
+    report?: SubagentStructuredReport | undefined;
+    /** Useful incomplete work captured before timeout/abort/failure. */
+    partial?: SubagentPartialResult | undefined;
     iterations: number;
     toolCalls: number;
     durationMs: number;
@@ -1131,9 +1183,12 @@ interface SubagentRunContext {
     signal: AbortSignal;
     /** Null until `setSubagentBridge` is called for this subagent. */
     bridge: AgentBridge | null;
+    /** Publish a bounded in-memory snapshot that survives timeout races. */
+    reportProgress?: ((partial: SubagentPartialResult) => void) | undefined;
 }
 interface SubagentRunOutcome {
     result?: unknown | undefined;
+    report?: SubagentStructuredReport | undefined;
     iterations: number;
     toolCalls: number;
 }
@@ -1359,4 +1414,357 @@ interface AgentRunnerOptions {
  */
 declare function makeAgentSubagentRunner(opts: AgentRunnerOptions): SubagentRunner;
 
-export { type SubagentRunContext as $, Agent as A, type BudgetSessionIdSource as B, type CoordinatorStatus as C, type DoneCondition as D, BudgetExceededError as E, FleetBus as F, type BudgetKind as G, type BudgetLimits as H, type BudgetNegotiationMode as I, type BudgetThresholdDecision as J, type BudgetThresholdHandler as K, BudgetThresholdSignal as L, type MultiAgentCoordinator as M, type BudgetUsage as N, type CoordinatorEvents as O, type PluginAPI as P, DECISION_TIMEOUT_MS as Q, type FleetEvent as R, type SubagentConfig as S, type TaskSpec as T, type FleetHandler as U, type PluginLLMOptions as V, type PluginLLMResult as W, SubagentBudget as X, type SubagentContext as Y, type SubagentError as Z, type SubagentErrorKind as _, type AgentFactory as a, type SubagentRunOutcome as a0, type SubagentUsageSnapshot as a1, TIMEOUT_PREEMPT_FRACTION as a2, type TaskDelegation as a3, makeAgentSubagentRunner as a4, withDisabledToolFiltering as a5, type ProviderFactory as a6, type MultiAgentConfig as b, type SubagentRunner as c, type SpawnResult as d, type BridgeMessage as e, type AgentBridge as f, type TaskResult as g, type AwaitAnyResult as h, type BridgeTransport as i, type AgentBridgeConfig as j, type FleetUsage as k, FleetUsageAggregator as l, type SlashCommand as m, type PluginPipelines as n, type ToolRegistryView as o, type ProviderRegistryView as p, type MCPRegistryView as q, type SlashCommandRegistryView as r, type SessionWriterView as s, type MetricsSinkView as t, type PluginLLM as u, type PluginCapabilities as v, type PluginDependency as w, type Plugin as x, type AgentFactoryResult as y, type AgentRunnerOptions as z };
+/**
+ * Catalog types for the WrongStack agent fleet.
+ *
+ * An `AgentDefinition` bundles the runtime `SubagentConfig` (id/name/role/
+ * prompt/tools) with two things the bare config lacks:
+ *   - a per-role `budget` tier (consumed by FLEET_ROSTER_BUDGETS), and
+ *   - dispatcher `capability` metadata (keywords + summary + phase) used by
+ *     the smart dispatcher to route a free-form task to the best agent.
+ *
+ * Phase files (`phase1-discovery.ts` … `phase9-meta.ts`) each export an
+ * `AgentDefinition[]`; `index.ts` aggregates them into `AGENT_CATALOG`.
+ * `fleet.ts` derives `FLEET_ROSTER` + `FLEET_ROSTER_BUDGETS` from the catalog.
+ */
+
+/** Lifecycle phase grouping. Drives statusline labels + dispatcher tie-breaks. */
+type AgentPhase = 'discovery' | 'planning' | 'build' | 'verify' | 'review' | 'domain' | 'knowledge' | 'delivery' | 'meta';
+/** Per-role budget tier. Same shape as fleet.ts `FleetRosterBudget`. */
+interface AgentBudgetTier {
+    timeoutMs?: number | undefined;
+    maxIterations?: number | undefined;
+    maxToolCalls?: number | undefined;
+    maxTokens?: number | undefined;
+    maxCostUsd?: number | undefined;
+}
+/** Dispatcher routing metadata. */
+interface AgentCapability {
+    phase: AgentPhase;
+    /**
+     * One-line capability summary. Fed to the LLM dispatcher classifier as the
+     * candidate's description, and shown to the user when explaining a routing
+     * decision. Keep it concrete and distinct from sibling agents.
+     */
+    summary: string;
+    /**
+     * Lowercased signal words/phrases for the heuristic dispatcher. A task whose
+     * description contains these scores toward this agent. Order doesn't matter;
+     * prefer specific terms ("graphql", "wcag") over generic ones ("code").
+     */
+    keywords: string[];
+}
+/** A single catalog entry: runtime config + budget tier + routing metadata. */
+interface AgentDefinition {
+    config: SubagentConfig;
+    budget: AgentBudgetTier;
+    capability: AgentCapability;
+}
+/**
+ * Budget tiers by workload weight. Deliberately generous — the project's
+ * existing roster uses multi-hour ceilings to avoid spurious timeouts on
+ * monorepo-scale work, and the auto-extend handshake raises them further when
+ * a subagent is still making progress.
+ */
+declare const LIGHT_BUDGET: AgentBudgetTier;
+declare const MEDIUM_BUDGET: AgentBudgetTier;
+declare const HEAVY_BUDGET: AgentBudgetTier;
+/**
+ * Tool allowlist presets. Agents pass the smallest set that covers their job —
+ * a planning agent should not hold `write`/`bash`, a reviewer should be
+ * read-only. Spread + extend per-agent where a role needs one extra tool.
+ */
+declare const TOOLS: {
+    /** Pure read/inspect — safe for analysis and review agents. */
+    readonly read: readonly ["read", "grep", "glob", "search", "tree", "mailbox"];
+    /** Read + structured inspection (logs, diffs, json, dependency audit). */
+    readonly inspect: readonly ["read", "grep", "glob", "search", "tree", "json", "diff", "logs", "audit", "mailbox"];
+    /** Read + edit (no shell). For agents that write code/docs but don't run it. */
+    readonly write: readonly ["read", "grep", "glob", "search", "tree", "write", "edit", "replace", "patch", "mailbox"];
+    /** Full build loop: edit + run (lint/format/typecheck/test/bash). */
+    readonly build: readonly ["read", "grep", "glob", "search", "tree", "write", "edit", "replace", "patch", "bash", "exec", "lint", "format", "typecheck", "test", "mailbox"];
+    /** Version control. */
+    readonly vcs: readonly ["read", "grep", "glob", "git", "diff"];
+    /** Dependency management + CVE audit. */
+    readonly deps: readonly ["read", "grep", "glob", "install", "outdated", "audit", "json", "mailbox"];
+    /** Documentation authoring. */
+    readonly docs: readonly ["read", "grep", "glob", "search", "tree", "write", "edit", "document", "mailbox"];
+    /** Web research. */
+    readonly research: readonly ["read", "grep", "glob", "search", "fetch", "mailbox"];
+};
+
+/**
+ * Smart agent dispatcher.
+ *
+ * Routes a free-form task description to the best agent in the catalog using a
+ * two-stage strategy:
+ *
+ *   1. Heuristic — keyword/phrase scoring against each agent's `capability`
+ *      metadata. Deterministic, instant, no provider call. Multi-word phrases
+ *      score higher than single words (they're more specific signals).
+ *
+ *   2. LLM fallback — when the heuristic is ambiguous (confidence below the
+ *      threshold, or no keyword hit at all) an injected `classifier` resolves
+ *      the tie. The classifier is provider-agnostic: callers wire it to any
+ *      `complete(prompt) => text` function via `makeLLMClassifier`, so core
+ *      stays free of provider dependencies and the path is unit-testable.
+ *
+ * If neither stage yields a confident pick, the dispatcher falls back to the
+ * `executor` generalist rather than failing.
+ */
+
+/** Default agent used when nothing else matches — the generalist builder. */
+declare const DEFAULT_DISPATCH_ROLE = "executor";
+interface DispatchCandidate {
+    role: string;
+    name: string;
+    score: number;
+    /** Capability keywords that matched the task text. */
+    matched: string[];
+}
+type DispatchMethod = 'heuristic' | 'llm' | 'fallback';
+interface DispatchResult {
+    role: string;
+    definition: AgentDefinition;
+    /** 0..1 — heuristic margin, or 1 when an LLM made a definite choice. */
+    confidence: number;
+    method: DispatchMethod;
+    /** Human-readable explanation of why this agent was chosen. */
+    reason: string;
+    /** Runner-up candidates (top heuristic scorers), best-first. */
+    alternatives: DispatchCandidate[];
+}
+/**
+ * Provider-agnostic classifier seam. Given the task and the candidate agents
+ * (role + summary), return the chosen role (and optional reason), or null to
+ * decline. Wire via `makeLLMClassifier`.
+ */
+type DispatchClassifier = (task: string, candidates: {
+    role: string;
+    name: string;
+    summary: string;
+}[]) => Promise<{
+    role: string;
+    reason?: string | undefined;
+} | null>;
+interface DispatchOptions {
+    /** Optional LLM fallback for ambiguous tasks. */
+    classifier?: DispatchClassifier | undefined;
+    /** Heuristic confidence below this triggers the classifier. Default 0.4. */
+    confidenceThreshold?: number | undefined;
+    /** How many top candidates to offer the classifier. Default 6. */
+    maxCandidates?: number | undefined;
+    /** Override the catalog (testing). Defaults to the full `AGENT_CATALOG`. */
+    catalog?: Record<string, AgentDefinition> | undefined;
+}
+/**
+ * Score every agent against the task. A keyword hit adds 1 point; a multi-word
+ * keyword phrase adds points equal to its word count (more specific = stronger
+ * signal). Returns candidates sorted best-first, zero-score agents dropped.
+ */
+declare function scoreAgents(task: string, catalog?: Record<string, AgentDefinition>): DispatchCandidate[];
+/**
+ * Route a task to the best agent. Async because the LLM fallback may run; the
+ * pure-heuristic path resolves without awaiting anything.
+ */
+declare function dispatchAgent(task: string, opts?: DispatchOptions): Promise<DispatchResult>;
+/**
+ * Build a `DispatchClassifier` from a minimal `complete(prompt) => text`
+ * function. The caller supplies the provider call; this owns the prompt and
+ * the parsing. Keeps `dispatcher` free of any provider import.
+ */
+declare function makeLLMClassifier(complete: (prompt: string) => Promise<string>): DispatchClassifier;
+
+interface MultiAgentCoordinatorOptions {
+    /**
+     * Callback that executes a task on behalf of a subagent. Required for
+     * `assign()` to actually run anything — without it, tasks queue forever.
+     * The coordinator provides per-subagent isolation (own budget, own signal,
+     * own bridge) and enforces timeout + concurrency.
+     */
+    runner?: SubagentRunner | undefined;
+    /**
+     * Session id for EventBus/FleetBus emissions produced by this coordinator.
+     * Accepts a getter so a long-lived coordinator follows session resume/new.
+     */
+    sessionId?: BudgetSessionIdSource | undefined;
+}
+declare class DefaultMultiAgentCoordinator extends EventEmitter implements MultiAgentCoordinator {
+    readonly coordinatorId: string;
+    readonly config: MultiAgentConfig;
+    private runner?;
+    private readonly sessionId;
+    private fleetBus?;
+    private readonly subagents;
+    /**
+     * Base nickname keys already handed out this run (e.g. `einstein`, `tesla`).
+     * Prevents two workers sharing a name. Direct `coordinator.spawn()` callers
+     * (parallel/eternal engine, SDD parallel run) don't go through
+     * `Director.spawn()` where nicknames are normally assigned, so the
+     * coordinator upgrades placeholder names ("Executor", "slot-ab12cd", role
+     * names) to memorable ones here — that's what surfaces in the fleet monitor.
+     */
+    private readonly usedNicknames;
+    /** Maps subagentId → nickname key (e.g. 'einstein'). Used to free the slot on remove(). */
+    private readonly subagentNicknames;
+    private pendingTasks;
+    private completedResults;
+    /** Prevents completedResults from growing unbounded in long-running coordinators. */
+    private static readonly MAX_COMPLETED_RESULTS;
+    private totalIterations;
+    private inFlight;
+    /**
+     * Subagents currently being stopped. Set on entry to `stop()`, cleared
+     * once `recordCompletion` lands the terminal TaskResult. Used by
+     * `runDispatched` and `findIdleSubagent` to refuse mid-flight dispatch
+     * to a subagent the caller has already asked to terminate — closes the
+     * assign+terminate race where a fresh task could land on a worker that
+     * was about to be killed.
+     */
+    private readonly terminating;
+    constructor(config: MultiAgentConfig, options?: MultiAgentCoordinatorOptions);
+    private currentSessionId;
+    /**
+     * Replace the runner after construction. Used when the runner depends
+     * on infrastructure (e.g. FleetBus) that isn't available until after
+     * the coordinator's owning Director is built.
+     */
+    setRunner(runner: SubagentRunner): void;
+    /**
+     * Wire a FleetBus for director-mode event emission. Call after the
+     * FleetManager is constructed so the coordinator can emit lifecycle
+     * events the TUI and monitoring tools subscribe to.
+     */
+    setFleetBus(fleet: FleetBus): void;
+    /**
+     * Change the in-flight dispatch ceiling at runtime. Lowering does NOT
+     * preempt running tasks — already-dispatched subagents finish their
+     * current task; only future dispatches respect the new cap. Raising
+     * immediately tries to fill the freed slots from the pending queue.
+     */
+    setMaxConcurrent(n: number): void;
+    /**
+     * Upgrade a placeholder/role-derived name to a memorable scientist nickname
+     * (e.g. "Einstein (Executor)"). A name is treated as a placeholder when it is
+     * empty, equals the role (case-insensitive), is a generic default
+     * ("subagent"/"adhoc"/"generic"), or is an auto-generated `slot-…` id.
+     * Explicit, human-chosen names — including nicknames already assigned by
+     * `Director.spawn()` — are left untouched, so this never double-assigns.
+     */
+    private withNickname;
+    spawn(subagent: SubagentConfig): Promise<SpawnResult>;
+    assign(task: TaskSpec): Promise<void>;
+    delegate(to: string, msg: BridgeMessage): Promise<void>;
+    /**
+     * Wire up the communication bridge for a subagent. Call after spawn() once
+     * the caller has created the bidirectional connection.
+     */
+    setSubagentBridge(subagentId: string, bridge: AgentBridge): void;
+    stop(subagentId: string): Promise<void>;
+    stopAll(): Promise<void>;
+    /**
+     * Get current coordinator stats for monitoring/debugging.
+     */
+    getStats(): {
+        total: number;
+        running: number;
+        idle: number;
+        stopped: number;
+        inFlight: number;
+        pending: number;
+        completed: number;
+    };
+    /** Emit a reactive coordinator.stats event on FleetBus so the TUI can subscribe. */
+    private emitCoordinatorStats;
+    getStatus(): CoordinatorStatus;
+    /** Expose snapshot of completed results — useful for callers awaiting all done. */
+    results(): readonly TaskResult[];
+    /** Defensive snapshot of the still-queued (not yet dispatched) tasks. */
+    listPendingTasks(): readonly TaskSpec[];
+    /**
+     * Re-pin a still-PENDING task to a different subagent (`undefined` =
+     * unpin, any idle worker may take it), then try to dispatch. Returns
+     * `false` when the task is not in the pending queue — already
+     * dispatched, completed, or unknown. Running tasks can never be pulled;
+     * they can only be steered or terminated. The mutation is synchronous
+     * (same tick as the check), so it cannot race a concurrent dispatch:
+     * `tryDispatchNext` runs on this same call stack or a later one.
+     *
+     * The task keeps its id, so waiters, the report-back notifier, and
+     * checkpoint bookkeeping resolve unchanged when it eventually completes.
+     */
+    retargetPendingTask(taskId: string, subagentId: string | undefined): boolean;
+    /**
+     * Wait for one or more tasks to complete and return their results.
+     * If a task is already done when called, returns immediately.
+     * Resolves to an array in the same order as `taskIds`.
+     */
+    awaitTasks(taskIds: string[]): Promise<TaskResult[]>;
+    /**
+     * Wait until AT LEAST ONE of the named tasks completes. Returns every
+     * requested result already available at that moment (drain-what's-done)
+     * plus the ids still outstanding, so callers can loop "handle finishers,
+     * re-await the remainder" instead of blocking on the whole batch.
+     *
+     * Unlike `awaitTasks`, this never rejects and deliberately does NOT
+     * inherit `config.timeoutMs` — a "return whatever is done" call has no
+     * business timing out unless the caller asks for a window explicitly.
+     */
+    awaitTasksAny(taskIds: string[], opts?: {
+        timeoutMs?: number;
+    }): Promise<AwaitAnyResult>;
+    /**
+     * Manual completion — for callers that drive subagents without a runner
+     * (e.g. external orchestrators). When a runner is configured the coordinator
+     * calls this itself.
+     */
+    completeTask(result: TaskResult): void;
+    private tryDispatchNext;
+    private canDispatch;
+    private takeNextDispatchableTask;
+    private findIdleSubagent;
+    private isIdleSubagent;
+    /**
+     * Returns true iff at least one spawned subagent could still
+     * process a task. A "live" subagent is one that is not stopped
+     * AND not mid-termination — `running` workers count because they
+     * will eventually finish and become idle.
+     *
+     * When no subagent has ever been spawned, returns `true` so a
+     * pre-spawn `assign()` simply queues (legacy behaviour). The
+     * dead-end detection only fires after `stop()` has retired every
+     * spawned worker.
+     *
+     * Used by `tryDispatchNext` to detect a dead-end pending queue.
+     */
+    private hasLiveSubagent;
+    /**
+     * Drain every pending task with a synthetic `aborted_by_parent`
+     * completion event. Same shape as the `stopAll()` drain — we go
+     * around `recordCompletion` because pending tasks were never
+     * counted in `inFlight` and routing them through would trip the
+     * underflow guard on every task after the first.
+     */
+    private drainPendingAsAborted;
+    /**
+     * Emit a synthetic `stopped`/`aborted_by_parent` completion for a single
+     * PENDING task — one that was never counted in `inFlight`. This MUST bypass
+     * `recordCompletion`: that path does `inFlight--`, which for a pending task
+     * steals a decrement from a genuinely in-flight task and trips the underflow
+     * guard — suppressing that real task's `task.completed` and hanging its
+     * `awaitTasks()` caller. Pushes the result and fires the event directly.
+     */
+    private emitPendingAborted;
+    private runDispatched;
+    private executeWithTimeout;
+    private recordCompletion;
+    /**
+     * Stop a subagent and remove it from the coordinator. Releases all
+     * associated resources (AbortController, context, budget state).
+     * The subagent entry is deleted so the id can be reused in a future spawn.
+     */
+    remove(subagentId: string): Promise<void>;
+    private isDone;
+}
+
+export { type DispatchResult as $, Agent as A, type BridgeTransport as B, type CoordinatorStatus as C, type DispatchClassifier as D, type AgentBudgetTier as E, FleetBus as F, type AgentCapability as G, type AgentFactoryResult as H, type AgentRunnerOptions as I, BudgetExceededError as J, type BudgetKind as K, type BudgetLimits as L, type MultiAgentConfig as M, type BudgetNegotiationMode as N, type BudgetThresholdDecision as O, type PluginAPI as P, type BudgetThresholdHandler as Q, BudgetThresholdSignal as R, type SubagentRunner as S, type TaskSpec as T, type BudgetUsage as U, type CoordinatorEvents as V, DECISION_TIMEOUT_MS as W, DEFAULT_DISPATCH_ROLE as X, type DispatchCandidate as Y, type DispatchMethod as Z, type DispatchOptions as _, type AgentFactory as a, type FleetEvent as a0, type FleetHandler as a1, HEAVY_BUDGET as a2, LIGHT_BUDGET as a3, MEDIUM_BUDGET as a4, type MultiAgentCoordinator as a5, type MultiAgentCoordinatorOptions as a6, type PluginLLMOptions as a7, type PluginLLMResult as a8, type SpawnResult as a9, SubagentBudget as aa, type SubagentContext as ab, type SubagentError as ac, type SubagentErrorKind as ad, type SubagentPartialResult as ae, type SubagentRunContext as af, type SubagentRunOutcome as ag, type SubagentSpawnLineage as ah, type SubagentStructuredReport as ai, type SubagentUsageSnapshot as aj, TIMEOUT_PREEMPT_FRACTION as ak, type TaskDelegation as al, dispatchAgent as am, makeAgentSubagentRunner as an, makeLLMClassifier as ao, scoreAgents as ap, withDisabledToolFiltering as aq, type ProviderFactory as ar, DefaultMultiAgentCoordinator as b, type DoneCondition as c, type BridgeMessage as d, type AgentBridge as e, type AgentBridgeConfig as f, type AgentPhase as g, type AgentDefinition as h, type SubagentConfig as i, type FleetUsage as j, FleetUsageAggregator as k, type TaskResult as l, type AwaitAnyResult as m, type SlashCommand as n, type PluginPipelines as o, type ToolRegistryView as p, type ProviderRegistryView as q, type MCPRegistryView as r, type SlashCommandRegistryView as s, type SessionWriterView as t, type MetricsSinkView as u, type PluginLLM as v, type PluginCapabilities as w, type PluginDependency as x, type Plugin as y, TOOLS as z };

package/dist/{null-fleet-bus-D4e9R7Qc.d.ts → null-fleet-bus-CFoNVQEK.d.ts}

@@ -1,12 +1,11 @@
-import { i as BridgeTransport, e as BridgeMessage, f as AgentBridge, j as AgentBridgeConfig, c as SubagentRunner, T as TaskSpec, S as SubagentConfig, F as FleetBus, k as FleetUsage, l as FleetUsageAggregator, g as TaskResult, C as CoordinatorStatus, b as MultiAgentConfig, h as AwaitAnyResult } from './agent-subagent-runner-BsuWhB28.js';
-import { A as AgentPhase, b as AgentDefinition, a as DefaultMultiAgentCoordinator, D as DispatchClassifier } from './multi-agent-coordinator-CrjeTB9i.js';
-import { E as EventBus, B as BrainArbiter } from './events-KmxSmvho.js';
-import { b as SessionWriter, g as Tool, k as SessionStore } from './tool-LVSLiE1s.js';
+import { B as BridgeTransport, d as BridgeMessage, e as AgentBridge, f as AgentBridgeConfig, g as AgentPhase, h as AgentDefinition, S as SubagentRunner, T as TaskSpec, i as SubagentConfig, F as FleetBus, j as FleetUsage, k as FleetUsageAggregator, b as DefaultMultiAgentCoordinator, l as TaskResult, C as CoordinatorStatus, D as DispatchClassifier, M as MultiAgentConfig, m as AwaitAnyResult } from './multi-agent-coordinator-4RCRZKjN.js';
+import { E as EventBus, B as BrainArbiter } from './events-Bgnh43r9.js';
+import { b as SessionWriter, g as Tool, k as SessionStore } from './tool-BNlnIJvo.js';
 import { EventEmitter } from 'node:events';
-import { D as DirectorStateSnapshot } from './director-state-B_GPa78Q.js';
-import { F as FleetConfig, a as ModelMatrixEntry } from './config-DkCbA3Bw.js';
+import { D as DirectorStateSnapshot } from './director-state-CMS_bMs4.js';
+import { F as FleetConfig, a as ModelMatrixEntry } from './config-MRqn1V-u.js';
 import { L as Logger } from './logger-B63L5bTg.js';
-import { W as WorktreeManager } from './worktree-manager-BjyAW30D.js';
+import { W as WorktreeManager } from './worktree-manager-DzwxKE35.js';
 
 /**
  * In-memory pub/sub transport for agent-to-agent messaging.
@@ -188,10 +187,22 @@ interface IFleetManager {
      * internally.
      */
     canSpawn(config: SubagentConfig): {
-        kind: 'max_spawns' | 'max_spawn_depth' | 'max_cost_usd' | 'max_context_load';
+        kind: 'max_spawns' | 'max_spawn_depth' | 'max_cost_usd' | 'max_tokens' | 'max_context_load';
         limit: number;
         observed: number;
     } | null;
+    /** Current fleet-wide token/cost ceiling and remaining headroom. */
+    budgetSnapshot?: (() => {
+        maxSpawns: number;
+        usedSpawns: number;
+        remainingSpawns: number;
+        maxTokens: number;
+        usedTokens: number;
+        remainingTokens: number;
+        maxCostUsd: number;
+        usedCostUsd: number;
+        remainingCostUsd: number;
+    }) | undefined;
     /**
      * Update the leader agent's current context pressure (tokens used in the
      * full API request: messages + systemPrompt + toolDefs). The fleet manager
@@ -328,6 +339,7 @@ interface FleetManagerOptions {
     checkpointDebounceMs?: number | undefined;
     directorBudget?: {
         maxCostUsd?: number | undefined;
+        maxTokens?: number | undefined;
     } | undefined;
     /**
      * Maximum context load (as a fraction of maxContext) the leader agent
@@ -389,6 +401,8 @@ declare class FleetManager implements IFleetManager {
     /** Fleet-wide cost cap. Infinity = no cap. Distinct from SubagentBudget limits,
      *  which track per-subagent spend — this field caps the entire fleet total. */
     private readonly maxFleetCostUsd;
+    /** Fleet-wide input+output token ceiling. Infinity = no cap. */
+    private readonly maxFleetTokens;
     private readonly manifestEntries;
     /** Pending tasks with their descriptions — populated by `addPendingTask`
      *  and cleared by `removePendingTask`. Replaces the host-side `pending`
@@ -426,10 +440,21 @@ declare class FleetManager implements IFleetManager {
      * how to surface the rejection.
      */
     canSpawn(_config: SubagentConfig): {
-        kind: 'max_spawns' | 'max_spawn_depth' | 'max_cost_usd' | 'max_context_load';
+        kind: 'max_spawns' | 'max_spawn_depth' | 'max_cost_usd' | 'max_tokens' | 'max_context_load';
         limit: number;
         observed: number;
     } | null;
+    budgetSnapshot(): {
+        maxSpawns: number;
+        usedSpawns: number;
+        remainingSpawns: number;
+        maxTokens: number;
+        usedTokens: number;
+        remainingTokens: number;
+        maxCostUsd: number;
+        usedCostUsd: number;
+        remainingCostUsd: number;
+    };
     setLeaderContextPressure(tokens: number): void;
     private resolveMaxContext;
     /**
@@ -672,6 +697,12 @@ declare class FleetCostCapError extends Error {
     readonly observed: number;
     constructor(limit: number, observed: number);
 }
+declare class FleetTokenCapError extends Error {
+    readonly kind: 'max_tokens';
+    readonly limit: number;
+    readonly observed: number;
+    constructor(limit: number, observed: number);
+}
 
 /**
  * Director — high-level orchestrator that owns a `MultiAgentCoordinator`,
@@ -702,6 +733,10 @@ interface TaskResultNotification {
     resultText?: string | undefined;
     /** Flattened `kind: message` error string for non-success statuses. */
     errorText?: string | undefined;
+    /** Bounded incomplete text recovered before a non-successful exit. */
+    partialText?: string | undefined;
+    /** Machine-readable result submitted through submit_result. */
+    report?: TaskResult['report'] | undefined;
     iterations: number;
     toolCalls: number;
     durationMs: number;
@@ -771,7 +806,8 @@ interface DirectorOptions {
      * user is at depth `spawnDepth` (default 0); any subagent that itself
      * acts as a director would construct its own `Director` with
      * `spawnDepth: parent.spawnDepth + 1`. When `spawnDepth >= maxSpawnDepth`,
-     * `spawn()` rejects. Default: 2 (root director can spawn workers; a
+     * `spawn()` rejects. The process-wide hard ceiling is 2; configuration can
+     * narrow it but cannot widen it. Default: 2 (root director can spawn workers; a
      * worker that becomes a sub-director cannot itself spawn further).
      * This stops infinite recursive director chains from a hostile or
      * confused prompt.
@@ -829,6 +865,8 @@ interface DirectorOptions {
          * Default: Infinity (no cap).
          */
         maxCostUsd?: number | undefined;
+        /** Maximum cumulative input+output tokens across the fleet. */
+        maxTokens?: number | undefined;
     } | undefined;
     /**
      * Maximum auto-extensions per subagent per budget kind before the
@@ -1045,6 +1083,8 @@ declare class Director implements ICoordinator {
     private readonly manifestDebounceMs;
     /** Fleet-wide cost cap (entire fleet total, distinct from SubagentBudget limits). Infinity means no cap. */
     private readonly maxFleetCostUsd;
+    /** Fleet-wide input+output token cap. Infinity means no cap. */
+    private readonly maxFleetTokens;
     /** Max auto-extensions per subagent per budget kind before denying. */
     private readonly maxBudgetExtensions;
     /** Sessions root for direct subagent JSONL reads (fleet tool, action: session). */
@@ -1998,7 +2038,8 @@ declare function makeFleetTool(director: Director): Tool;
 declare function makeCollabDebugTool(director: Director): Tool;
 /**
  * Tool for subagents to emit structured events on the FleetBus.
- * Any agent can emit any event type; the Director routes it to all listeners.
+ * Custom event types are extensible; known collab events are schema-validated
+ * and restricted to their owning role before the Director routes them.
  * Common event types in collaborative sessions:
  *   bug.found        — BugHunter emits per-finding
  *   refactor.plan    — RefactorPlanner emits per-plan
@@ -2083,4 +2124,4 @@ declare const FLEET_ROSTER_WITHACP: Record<string, SubagentConfig>;
  */
 declare const NULL_FLEET_BUS: FleetBus;
 
-export { type WorktreeIsolationDecision as $, ACP_AGENTS as A, BUG_HUNTER_AGENT as B, type CollabBudgetConfig as C, DEFAULT_DIRECTOR_PREAMBLE as D, FLEET_ROSTER_WITHACP as E, FLEET_ROSTER as F, FleetCostCapError as G, FleetManager as H, type FleetManagerOptions as I, type FleetRosterBudget as J, FleetSpawnBudgetError as K, type FleetWorktreePolicy as L, type ICoordinator as M, type IFleetManager as N, InMemoryAgentBridge as O, InMemoryBridgeTransport as P, LargeAnswerStore as Q, NULL_FLEET_BUS as R, REFACTOR_PLANNER_AGENT as S, type RefactorPhase as T, type RefactorPlan as U, SECURITY_SCANNER_AGENT as V, type SharedFileEntry as W, type SharedFileSnapshot as X, type SubagentPromptParts as Y, type TaskResultNotification as Z, WorktreeIntegrationError as _, AGENTS_BY_PHASE as a, type WorktreeTaskRunnerOptions as a0, type WorktreeTaskStateUpdate as a1, applyRosterBudget as a2, attachAutoExtend as a3, composeDirectorPrompt as a4, composeSubagentPrompt as a5, createDelegateTool as a6, createMessage as a7, getAgentDefinition as a8, makeAskResultTool as a9, makeAskTool as aa, makeAssignTool as ab, makeAwaitTasksTool as ac, makeCollabDebugTool as ad, makeDirectorSessionFactory as ae, makeFleetEmitTool as af, makeFleetTool as ag, makeKanbanQueueTool as ah, makeQualityGateTool as ai, makeRollUpTool as aj, makeSpawnTool as ak, makeTerminateAllTool as al, makeTerminateTool as am, makeWorkCompleteTool as an, resolveSubagentWorktreeDecision as ao, rosterSummaryFromConfigs as ap, subagentNeedsWorktree as aq, wrapSubagentRunnerWithWorktrees as ar, AGENT_CATALOG as b, ALL_AGENT_DEFINITIONS as c, ALL_FLEET_AGENTS as d, AUDIT_LOG_AGENT as e, type AutoExtendCeiling as f, type AutoExtendPolicy as g, type BugFinding as h, type CollabBudgetOverrides as i, type CollabBudgetWarningPayload as j, type CollabDebugReport as k, CollabSession as l, type CollabSessionOptions as m, type CreateDelegateToolOptions as n, type CriticConcern as o, type CriticEvaluation as p, DEFAULT_SUBAGENT_BASELINE as q, type DelegateHost as r, Director as s, type DirectorAlert as t, DirectorAlertLevel as u, type DirectorCancelCollabPayload as v, type DirectorPromptParts as w, type DirectorSessionFactory as x, type DirectorSessionFactoryOptions as y, FLEET_ROSTER_BUDGETS as z };
+export { WorktreeIntegrationError as $, ACP_AGENTS as A, BUG_HUNTER_AGENT as B, type CollabBudgetConfig as C, DEFAULT_DIRECTOR_PREAMBLE as D, FLEET_ROSTER_WITHACP as E, FLEET_ROSTER as F, FleetCostCapError as G, FleetManager as H, type FleetManagerOptions as I, type FleetRosterBudget as J, FleetSpawnBudgetError as K, FleetTokenCapError as L, type FleetWorktreePolicy as M, type ICoordinator as N, type IFleetManager as O, InMemoryAgentBridge as P, InMemoryBridgeTransport as Q, LargeAnswerStore as R, NULL_FLEET_BUS as S, REFACTOR_PLANNER_AGENT as T, type RefactorPhase as U, type RefactorPlan as V, SECURITY_SCANNER_AGENT as W, type SharedFileEntry as X, type SharedFileSnapshot as Y, type SubagentPromptParts as Z, type TaskResultNotification as _, AGENTS_BY_PHASE as a, type WorktreeIsolationDecision as a0, type WorktreeTaskRunnerOptions as a1, type WorktreeTaskStateUpdate as a2, applyRosterBudget as a3, attachAutoExtend as a4, composeDirectorPrompt as a5, composeSubagentPrompt as a6, createDelegateTool as a7, createMessage as a8, getAgentDefinition as a9, makeAskResultTool as aa, makeAskTool as ab, makeAssignTool as ac, makeAwaitTasksTool as ad, makeCollabDebugTool as ae, makeDirectorSessionFactory as af, makeFleetEmitTool as ag, makeFleetTool as ah, makeKanbanQueueTool as ai, makeQualityGateTool as aj, makeRollUpTool as ak, makeSpawnTool as al, makeTerminateAllTool as am, makeTerminateTool as an, makeWorkCompleteTool as ao, resolveSubagentWorktreeDecision as ap, rosterSummaryFromConfigs as aq, subagentNeedsWorktree as ar, wrapSubagentRunnerWithWorktrees as as, AGENT_CATALOG as b, ALL_AGENT_DEFINITIONS as c, ALL_FLEET_AGENTS as d, AUDIT_LOG_AGENT as e, type AutoExtendCeiling as f, type AutoExtendPolicy as g, type BugFinding as h, type CollabBudgetOverrides as i, type CollabBudgetWarningPayload as j, type CollabDebugReport as k, CollabSession as l, type CollabSessionOptions as m, type CreateDelegateToolOptions as n, type CriticConcern as o, type CriticEvaluation as p, DEFAULT_SUBAGENT_BASELINE as q, type DelegateHost as r, Director as s, type DirectorAlert as t, DirectorAlertLevel as u, type DirectorCancelCollabPayload as v, type DirectorPromptParts as w, type DirectorSessionFactory as x, type DirectorSessionFactoryOptions as y, FLEET_ROSTER_BUDGETS as z };

package/dist/observability/index.d.ts

@@ -1,7 +1,7 @@
 import { M as MetricsSink, d as MetricLabels, f as MetricsSnapshot, H as HealthRegistry, a as HealthCheck, A as AggregateHealth, T as Tracer, S as Span } from '../observability-D-HZN_mF.js';
-import { E as EventBus } from '../events-KmxSmvho.js';
-import '../tool-LVSLiE1s.js';
-import '../permission-B6YAtNFz.js';
+import { E as EventBus } from '../events-Bgnh43r9.js';
+import '../tool-BNlnIJvo.js';
+import '../permission-ByDKXEcG.js';
 
 /**
  * In-memory metrics sink. Suitable for embedded use, tests, and /metrics