@wrongstack/core 0.277.2 → 0.280.1

package/dist/{null-fleet-bus-C9KsYyrI.d.ts → null-fleet-bus-DkdmZJ_W.d.ts}

@@ -1,328 +1,117 @@
-import { A as AgentPhase, b as AgentDefinition, a as DefaultMultiAgentCoordinator, D as DispatchClassifier } from './multi-agent-coordinator-CcrcncvG.js';
-import { F as FleetBus, j as FleetUsage, S as SubagentConfig, k as FleetUsageAggregator, g as TaskResult, C as CoordinatorStatus, T as TaskSpec, c as MultiAgentConfig, d as SubagentRunner } from './agent-subagent-runner-BimKihiC.js';
-import { b as SessionWriter, T as Tool, k as SessionStore } from './context-DPlA6kid.js';
-import { B as BrainArbiter, E as EventBus } from './brain-CCfuEOdp.js';
+import { A as AgentPhase, b as AgentDefinition, a as DefaultMultiAgentCoordinator, D as DispatchClassifier } from './multi-agent-coordinator-CieyUoEL.js';
+import { E as EventBus, B as BrainArbiter } from './events-Bs2fmldo.js';
+import { F as FleetBus, j as FleetUsage, S as SubagentConfig, k as FleetUsageAggregator, g as TaskResult, C as CoordinatorStatus, T as TaskSpec, c as MultiAgentConfig, d as SubagentRunner } from './agent-subagent-runner-PoqNKiR4.js';
+import { b as SessionWriter, T as Tool, k as SessionStore } from './tool-BkOgs_KL.js';
 import { EventEmitter } from 'node:events';
 import { L as Logger } from './logger-B63L5bTg.js';
 import { D as DirectorStateSnapshot } from './director-state-BfeCUbmk.js';
-import { d as ModelMatrixEntry } from './config-DAOjriz9.js';
-import { I as InMemoryAgentBridge } from './agent-bridge-BFJ2ODzI.js';
+import { d as ModelMatrixEntry } from './config-Cr3312zc.js';
+import { I as InMemoryAgentBridge } from './agent-bridge-DXC6QDJ4.js';
 
 /**
- * Alert levels the Director can emit when a collab session needs attention.
- * These flow through the FleetBus so the host can display them in the UI.
- */
-declare enum DirectorAlertLevel {
-    /** The agent is still making progress but has hit a soft budget limit. */
-    WARNING = "warning",
-    /** The agent has hit a hard limit and the session cannot continue. */
-    CRITICAL = "critical",
-    /** The Director has decided to cancel the session (user request or policy). */
-    CANCELLED = "cancelled"
-}
-interface DirectorAlert {
-    sessionId: string;
-    subagentId: string;
-    role: string;
-    level: DirectorAlertLevel;
-    /** Human-readable message for UI/logs */
-    message: string;
-    /** Budget kind that triggered this alert, if any */
-    budgetKind?: 'timeout' | 'idle_timeout' | 'iterations' | 'tool_calls' | 'tokens' | 'cost' | undefined;
-    /** Elapsed ms at time of alert */
-    elapsedMs?: number | undefined;
-    /** Limit that was hit */
-    limit?: number | undefined;
-    /** /btw notes the director has collected (may be empty) */
-    btwNotes?: string[] | undefined;
-}
-/**
- * Immutable snapshot of target files at the start of a collab session.
- * All agents in the session read from this snapshot — they see the same baseline.
- */
-interface SharedFileSnapshot {
-    id: string;
-    createdAt: string;
-    files: SharedFileEntry[];
-}
-interface SharedFileEntry {
-    path: string;
-    content: string;
-    language?: string | undefined;
-    snapshotMtimeMs?: number | undefined;
-    snapshotSizeBytes?: number | undefined;
-}
-/**
- * Bug finding emitted by BugHunter and consumed by RefactorPlanner + Critic.
+ * Agent catalog aggregator.
+ *
+ * Collects every phase's `AgentDefinition[]` into:
+ *   - `ALL_AGENT_DEFINITIONS` — flat list, catalog order (phase 1 → 9)
+ *   - `AGENT_CATALOG`         — keyed by role for O(1) lookup
+ *   - `AGENTS_BY_PHASE`       — grouped for statusline / dispatcher tie-breaks
+ *
+ * `fleet.ts` derives `FLEET_ROSTER` + `FLEET_ROSTER_BUDGETS` from this, and the
+ * dispatcher routes free-form tasks against `capability` metadata here.
  */
-interface BugFinding {
-    id: string;
-    type: string;
-    severity: 'critical' | 'high' | 'medium' | 'low';
-    location: {
-        file: string;
-        line: number;
-    };
-    description: string;
-    suggestedFix?: string | undefined;
-}
+
+/** Every catalog agent, in phase order. */
+declare const ALL_AGENT_DEFINITIONS: AgentDefinition[];
+/** Phase → its agents, for grouped display and dispatcher fallbacks. */
+declare const AGENTS_BY_PHASE: Record<AgentPhase, AgentDefinition[]>;
 /**
- * Refactoring plan emitted by RefactorPlanner, consuming BugFinding(s).
+ * Role → definition. Built once at module load. Throws on a duplicate role so
+ * a copy-paste collision fails loudly at startup instead of silently shadowing.
  */
-interface RefactorPlan {
-    id: string;
-    basedOnBugIds: string[];
-    phases: RefactorPhase[];
-    riskScore: 'low' | 'medium' | 'high';
-    estimatedChangeCount: number;
-    rollbackStrategy: string;
-}
-/** One phase within a refactor plan. */
-interface RefactorPhase {
-    number: number;
-    title: string;
-    tasks: string[];
-    risk: 'low' | 'medium' | 'high';
-}
+declare const AGENT_CATALOG: Record<string, AgentDefinition>;
+/** Role lookup helper. Returns undefined for unknown roles. */
+declare function getAgentDefinition(role: string): AgentDefinition | undefined;
+
 /**
- * Critic evaluation of a bug finding or refactor plan.
+ * Default auto-extend policy for subagent budgets.
+ *
+ * The budget's soft-limit path (`SubagentBudget` → `budget.threshold_reached`)
+ * only negotiates an extension when SOMETHING listens on the EventBus. Under a
+ * `Director`, that listener is the director's own auto-extend handler. On the
+ * plain coordinator path (e.g. a bare `/spawn` with no director) nothing
+ * listens, so the budget falls back to a hard stop and the subagent dies the
+ * moment it crosses a soft limit.
+ *
+ * `attachAutoExtend` is the additive fix: wire it to a subagent's EventBus and
+ * budget overruns are auto-granted headroom instead of killing the run. It is
+ * heartbeat-aware for the timeout kind — wall-clock time always advances, so a
+ * naive "extend timeout forever" would let a wedged agent run indefinitely.
+ * Instead, a timeout extension is granted only when the agent has executed a
+ * new tool call or started a new iteration since the last timeout extension.
+ * No progress since last time ⇒ the agent is genuinely stuck ⇒ deny and let it
+ * fail. The non-timeout kinds (iterations/tool_calls/tokens/cost) extend up to
+ * a per-kind cap, then deny — those ceilings are the real runaway guard.
  */
-interface CriticEvaluation {
-    id: string;
-    subjectType: 'bug_finding' | 'refactor_plan';
-    subjectId: string;
-    score: number;
-    verdict: 'approve' | 'needs_revision' | 'reject';
-    strengths: string[];
-    weaknesses: string[];
-    concerns: CriticConcern[];
-}
-interface CriticConcern {
-    description: string;
-    location?: {
-        file: string | undefined;
-        line: number;
-    };
-    severity: 'blocking' | 'advisory';
+
+interface AutoExtendCeiling {
+    maxIterations?: number | undefined;
+    maxToolCalls?: number | undefined;
+    maxTokens?: number | undefined;
+    maxCostUsd?: number | undefined;
+    timeoutMs?: number | undefined;
 }
-/**
- * Full structured report produced when a CollabSession resolves.
- */
-interface CollabDebugReport {
-    sessionId: string;
-    startedAt: string;
-    completedAt: string;
-    targetPaths: string[];
-    /** How the session ended. 'completed' = all agents finished normally.
-     * 'cancelled' = Director called cancelCollabSession().
-     * 'timeout' = session-level timeout elapsed before all agents finished.
-     * 'critical_alert' = Director escalated a warning to a cancel decision.
+interface AutoExtendPolicy {
+    /** Multiplier applied to the tripped limit when extending. Default 0.5 (+50%). */
+    factor?: number | undefined;
+    /**
+     * Max extensions per NON-timeout kind before denying. Timeout is governed by
+     * the heartbeat check, not this cap, so it can extend indefinitely while the
+     * agent makes progress. Default 8.
      */
-    disposition: 'completed' | 'cancelled' | 'timeout' | 'critical_alert';
-    bugs: BugFinding[];
-    refactorPlans: RefactorPlan[];
-    evaluations: CriticEvaluation[];
-    /** Alerts that were raised during the session (may be empty). */
-    alerts: DirectorAlert[];
-    /** Files modified after the initial static snapshot was captured. */
-    snapshotWarnings?: string[] | undefined;
-    /** Overall verdict from the Critic across all evaluated subjects. */
-    overallVerdict: 'approve' | 'needs_revision' | 'reject';
-    /** Markdown-formatted summary for the director's context window. */
-    summary: string;
-}
-/**
- * Per-agent budget configuration for collab sessions.
- * Allows the caller (Director) to control the exact limits instead of
- * using hard-coded defaults that may not match the director's policy.
- */
-interface CollabBudgetConfig {
-    maxIterations: number;
-    maxToolCalls: number;
-    timeoutMs: number;
+    maxExtensionsPerKind?: number | undefined;
+    /** Absolute ceilings — an extension never pushes a limit past these. */
+    ceiling?: AutoExtendCeiling | undefined;
 }
 /**
- * Budget overrides for specific roles in a collab session.
- * When a role is not present in the map, the default budget is used.
- */
-type CollabBudgetOverrides = Partial<Record<string, CollabBudgetConfig>>;
-/**
- * Emitted by a collab agent when it hits a soft budget limit.
- * The Director's fleet handler receives this and calls collabAlert().
+ * Attach an auto-extend policy to a subagent's EventBus. Returns an unsubscribe
+ * function that detaches all listeners — call it when the subagent task ends.
  */
-interface CollabBudgetWarningPayload {
-    sessionId: string;
-    role: string;
-    kind: 'timeout' | 'idle_timeout' | 'iterations' | 'tool_calls' | 'tokens' | 'cost';
-    used: number;
-    limit: number;
-    timeoutMs?: number | undefined;
-    elapsedMs: number;
-}
+declare function attachAutoExtend(events: EventBus, policy?: AutoExtendPolicy): () => void;
+
 /**
- * Emitted by the Director to cancel all agents in a collab session.
- * CollabSession listens for this and causes its agent pool to finish early.
+ * Interface for fleet-level lifecycle and policy. Covers:
+ * - Spawn lifecycle hooks (canSpawn check, recordSpawn after-effects)
+ * - Budget enforcement (fleet-wide cost cap, spawn count/depth caps)
+ * - Fleet manifest assembly and writing
+ * - Subagent metadata and usage tracking
+ *
+ * `FleetBus` is pure event fan-out and implements no policy.
+ * `FleetManager` encapsulates all fleet-level policy decisions.
+ * `Director` currently owns all of this — this interface lets us
+ * extract it into a swappable component in Phase 5.
  */
-interface DirectorCancelCollabPayload {
-    sessionId: string;
-    reason: string;
-    cancelledAt: string;
-}
-interface CollabSessionOptions {
-    /** Paths to scan — used to build the SharedFileSnapshot. */
-    targetPaths: string[];
-    /** Files already read and snapshot. When provided, snapshot is skipped. */
-    prebuiltSnapshot?: SharedFileSnapshot | undefined;
-    /** Max time to wait for the session to resolve (ms). Default: 10 min. */
-    timeoutMs?: number | undefined;
+interface IFleetManager {
+    /** The FleetBus this manager publishes lifecycle events to. */
+    readonly fleetBus: FleetBus;
     /**
-     * Maximum number of files to include in the snapshot.
-     * - If set explicitly: use this value (hard override).
-     * - If `contextWindow` is set: calculate dynamically from estimated token budget.
-     * - If neither: use `DEFAULT_MAX_TARGET_FILES` (30).
+     * Snapshot of fleet-wide token usage and cost rollup.
+     * Safe to call from a tool's execute() body.
      */
-    maxTargetFiles?: number | undefined;
+    snapshot(): FleetUsage;
     /**
-     * Context window size (in tokens) of the model running the subagents.
-     * When provided and `maxTargetFiles` is not set, the limit is computed
-     * dynamically: `floor((contextWindow * 0.4) / AVG_TOKENS_PER_FILE)`.
-     * If not provided, `DEFAULT_MAX_TARGET_FILES` is used as the fallback.
+     * Per-subagent metadata captured at spawn time (provider/model/name).
+     * Returns undefined if the subagent is not known to this manager.
      */
-    contextWindow?: number | undefined;
+    getSubagentMeta(id: string): {
+        provider?: string | undefined;
+        model?: string | undefined;
+        name?: string | undefined;
+    } | undefined;
     /**
-     * Budget overrides per role. When provided, these override the hard-coded
-     * defaults so the Director can enforce fleet-wide budget policy.
-     * Keys must match role names: 'bug-hunter', 'refactor-planner', 'critic'.
-     */
-    budgetOverrides?: CollabBudgetOverrides | undefined;
-    /**
-     * Called by the Director when a collab agent hits a soft budget limit.
-     * The Director uses this to decide whether to cancel the session or extend.
-     * Return 'cancel' to stop the session immediately; 'extend' to continue
-     * with the agent's proposed new limits; 'ignore' to let the default
-     * auto-extend logic handle it.
-     */
-    onBudgetWarning?: ((alert: DirectorAlert) => 'cancel' | 'extend' | 'ignore') | undefined;
-}
-declare class CollabSession extends EventEmitter {
-    readonly sessionId: string;
-    readonly options: CollabSessionOptions;
-    readonly snapshot: SharedFileSnapshot;
-    private readonly director;
-    private readonly fleetBus;
-    private readonly subagentIds;
-    private readonly bugs;
-    private readonly plans;
-    private readonly evaluations;
-    private readonly disposers;
-    private settled;
-    private readonly timeoutMs;
-    private cancelled;
-    private _raceResolved;
-    private readonly alerts;
-    private snapshotWarnings;
-    /** Tracks tool call counts per subagent for progress-based timeout decisions. */
-    private readonly progressBySubagent;
-    /** Last tool call count when a timeout warning was handled. */
-    private readonly lastTimeoutProgress;
-    /** Session-level timeout timer handle (cleared on cancel or natural completion). */
-    private _timeoutTimer?;
-    constructor(director: Director, fleetBus: FleetBus, options: CollabSessionOptions);
-    get id(): string;
-    getSessionAlerts(): DirectorAlert[];
-    isCancelled(): boolean;
-    /**
-     * Snapshot of role → subagentId map. The Director calls coordinator.stop()
-     * for each agent when cancelling the session, using this map to enumerate
-     * all three collab agents.
-     */
-    getSubagentIds(): ReadonlyMap<string, string>;
-    /**
-     * Returns the effective file limit for this session.
-     * Priority: explicit `maxTargetFiles` > dynamic from `contextWindow` > `DEFAULT_MAX_TARGET_FILES`.
-     */
-    effectiveFileLimit(): number;
-    buildSnapshot(): Promise<SharedFileSnapshot>;
-    /**
-     * Cancel the session. Emits director.cancel_collab on the FleetBus so all
-     * collab agents finish early. The session-level timeout timer is also cleared.
-     * Safe to call multiple times (idempotent after first call).
-     */
-    cancel(reason?: string): void;
-    start(): Promise<CollabDebugReport>;
-    private parseAndEmit;
-    private extractJsonObjects;
-    private budgetForRole;
-    private spawnAgent;
-    private buildBugHunterTask;
-    private buildRefactorPlannerTask;
-    private buildCriticTask;
-    private wireFleetBus;
-    private roleFromSubagentId;
-    private assembleReport;
-    private checkSnapshotFreshness;
-    private buildMarkdownSummary;
-    private cleanup;
-}
-
-/**
- * Agent catalog aggregator.
- *
- * Collects every phase's `AgentDefinition[]` into:
- *   - `ALL_AGENT_DEFINITIONS` — flat list, catalog order (phase 1 → 9)
- *   - `AGENT_CATALOG`         — keyed by role for O(1) lookup
- *   - `AGENTS_BY_PHASE`       — grouped for statusline / dispatcher tie-breaks
- *
- * `fleet.ts` derives `FLEET_ROSTER` + `FLEET_ROSTER_BUDGETS` from this, and the
- * dispatcher routes free-form tasks against `capability` metadata here.
- */
-
-/** Every catalog agent, in phase order. */
-declare const ALL_AGENT_DEFINITIONS: AgentDefinition[];
-/** Phase → its agents, for grouped display and dispatcher fallbacks. */
-declare const AGENTS_BY_PHASE: Record<AgentPhase, AgentDefinition[]>;
-/**
- * Role → definition. Built once at module load. Throws on a duplicate role so
- * a copy-paste collision fails loudly at startup instead of silently shadowing.
- */
-declare const AGENT_CATALOG: Record<string, AgentDefinition>;
-/** Role lookup helper. Returns undefined for unknown roles. */
-declare function getAgentDefinition(role: string): AgentDefinition | undefined;
-
-/**
- * Interface for fleet-level lifecycle and policy. Covers:
- * - Spawn lifecycle hooks (canSpawn check, recordSpawn after-effects)
- * - Budget enforcement (fleet-wide cost cap, spawn count/depth caps)
- * - Fleet manifest assembly and writing
- * - Subagent metadata and usage tracking
- *
- * `FleetBus` is pure event fan-out and implements no policy.
- * `FleetManager` encapsulates all fleet-level policy decisions.
- * `Director` currently owns all of this — this interface lets us
- * extract it into a swappable component in Phase 5.
- */
-interface IFleetManager {
-    /** The FleetBus this manager publishes lifecycle events to. */
-    readonly fleetBus: FleetBus;
-    /**
-     * Snapshot of fleet-wide token usage and cost rollup.
-     * Safe to call from a tool's execute() body.
-     */
-    snapshot(): FleetUsage;
-    /**
-     * Per-subagent metadata captured at spawn time (provider/model/name).
-     * Returns undefined if the subagent is not known to this manager.
-     */
-    getSubagentMeta(id: string): {
-        provider?: string | undefined;
-        model?: string | undefined;
-        name?: string | undefined;
-    } | undefined;
-    /**
-     * Called before a spawn is recorded. Returns a reason string if the
-     * spawn should be rejected (budget cap, depth limit, cost cap, context
-     * overload, etc.), or null to proceed. Director.spawn() calls this
-     * internally.
+     * Called before a spawn is recorded. Returns a reason string if the
+     * spawn should be rejected (budget cap, depth limit, cost cap, context
+     * overload, etc.), or null to proceed. Director.spawn() calls this
+     * internally.
      */
     canSpawn(config: SubagentConfig): {
         kind: 'max_spawns' | 'max_spawn_depth' | 'max_cost_usd' | 'max_context_load';
@@ -1471,64 +1260,262 @@ declare class Director implements ICoordinator {
     resumeFromCheckpoint(snapshot: DirectorStateSnapshot): void;
 }
 
-declare function makeSpawnTool(director: Director, roster?: Record<string, SubagentConfig>): Tool;
-declare function makeAssignTool(director: Director): Tool;
-declare function makeAwaitTasksTool(director: Director): Tool;
-declare function makeAskTool(director: Director): Tool;
 /**
- * Retrieve a previously stored `ask_subagent` answer by its store key.
- * The key was returned as `_answerKey` in the ask_subagent response.
- * Use this only for large responses that were stored out-of-context.
+ * Alert levels the Director can emit when a collab session needs attention.
+ * These flow through the FleetBus so the host can display them in the UI.
  */
-declare function makeAskResultTool(director: Director): Tool;
-declare function makeRollUpTool(director: Director): Tool;
-declare function makeTerminateTool(director: Director): Tool;
-declare function makeTerminateAllTool(director: Director): Tool;
+declare enum DirectorAlertLevel {
+    /** The agent is still making progress but has hit a soft budget limit. */
+    WARNING = "warning",
+    /** The agent has hit a hard limit and the session cannot continue. */
+    CRITICAL = "critical",
+    /** The Director has decided to cancel the session (user request or policy). */
+    CANCELLED = "cancelled"
+}
+interface DirectorAlert {
+    sessionId: string;
+    subagentId: string;
+    role: string;
+    level: DirectorAlertLevel;
+    /** Human-readable message for UI/logs */
+    message: string;
+    /** Budget kind that triggered this alert, if any */
+    budgetKind?: 'timeout' | 'idle_timeout' | 'iterations' | 'tool_calls' | 'tokens' | 'cost' | undefined;
+    /** Elapsed ms at time of alert */
+    elapsedMs?: number | undefined;
+    /** Limit that was hit */
+    limit?: number | undefined;
+    /** /btw notes the director has collected (may be empty) */
+    btwNotes?: string[] | undefined;
+}
 /**
- * Unified fleet observation tool — consolidates the former fleet_status,
- * fleet_usage, fleet_session, and fleet_health tools under a single `action`
- * parameter (status, usage, health, session).
- *
- * These four are all read-only fleet queries; merging them into one tool
- * reduces tool-schema token overhead (4 × ~150 tokens → 1 × ~250 tokens)
- * and eliminates model confusion when choosing between similar tools.
+ * Immutable snapshot of target files at the start of a collab session.
+ * All agents in the session read from this snapshot — they see the same baseline.
  */
-declare function makeFleetTool(director: Director): Tool;
+interface SharedFileSnapshot {
+    id: string;
+    createdAt: string;
+    files: SharedFileEntry[];
+}
+interface SharedFileEntry {
+    path: string;
+    content: string;
+    language?: string | undefined;
+    snapshotMtimeMs?: number | undefined;
+    snapshotSizeBytes?: number | undefined;
+}
 /**
- * Collaborative debugging session: BugHunter, RefactorPlanner, and Critic
- * run in parallel on the same target files, with findings flowing through
- * the FleetBus (bug.found → refactor.plan → critic.evaluation).
- *
- * Returns a structured CollabDebugReport containing all bug findings,
- * refactor plans, critic evaluations, and an overall verdict.
+ * Bug finding emitted by BugHunter and consumed by RefactorPlanner + Critic.
  */
-declare function makeCollabDebugTool(director: Director): Tool;
+interface BugFinding {
+    id: string;
+    type: string;
+    severity: 'critical' | 'high' | 'medium' | 'low';
+    location: {
+        file: string;
+        line: number;
+    };
+    description: string;
+    suggestedFix?: string | undefined;
+}
 /**
- * Tool for subagents to emit structured events on the FleetBus.
- * Any agent can emit any event type; the Director routes it to all listeners.
- * Common event types in collaborative sessions:
- *   bug.found        — BugHunter emits per-finding
- *   refactor.plan    — RefactorPlanner emits per-plan
- *   critic.evaluation — Critic emits per-evaluation
- *
- * The payload structure is event-type-specific. Use null for empty payloads.
+ * Refactoring plan emitted by RefactorPlanner, consuming BugFinding(s).
  */
-declare function makeFleetEmitTool(director: Director): Tool;
+interface RefactorPlan {
+    id: string;
+    basedOnBugIds: string[];
+    phases: RefactorPhase[];
+    riskScore: 'low' | 'medium' | 'high';
+    estimatedChangeCount: number;
+    rollbackStrategy: string;
+}
+/** One phase within a refactor plan. */
+interface RefactorPhase {
+    number: number;
+    title: string;
+    tasks: string[];
+    risk: 'low' | 'medium' | 'high';
+}
 /**
- * Signal that the director's work is satisfied and the fleet should wind down.
- *
- * Once called:
- * - `spawn_subagent` throws — no new subagents can be created
- * - `assign_task` synthesizes an immediate `aborted_by_parent` completion
- *   for any queued task (callers awaiting those tasks unblock immediately)
- * - Running subagents are NOT killed — they finish naturally; no new
- *   tasks are dispatched to them
- *
- * Use this when you are satisfied with the results and want the fleet to
- * stop spawning without forcibly stopping in-flight work. Call
- * `terminate_subagent` separately for any subagent you need to stop immediately.
+ * Critic evaluation of a bug finding or refactor plan.
  */
-declare function makeWorkCompleteTool(director: Director): Tool;
+interface CriticEvaluation {
+    id: string;
+    subjectType: 'bug_finding' | 'refactor_plan';
+    subjectId: string;
+    score: number;
+    verdict: 'approve' | 'needs_revision' | 'reject';
+    strengths: string[];
+    weaknesses: string[];
+    concerns: CriticConcern[];
+}
+interface CriticConcern {
+    description: string;
+    location?: {
+        file: string | undefined;
+        line: number;
+    };
+    severity: 'blocking' | 'advisory';
+}
+/**
+ * Full structured report produced when a CollabSession resolves.
+ */
+interface CollabDebugReport {
+    sessionId: string;
+    startedAt: string;
+    completedAt: string;
+    targetPaths: string[];
+    /** How the session ended. 'completed' = all agents finished normally.
+     * 'cancelled' = Director called cancelCollabSession().
+     * 'timeout' = session-level timeout elapsed before all agents finished.
+     * 'critical_alert' = Director escalated a warning to a cancel decision.
+     */
+    disposition: 'completed' | 'cancelled' | 'timeout' | 'critical_alert';
+    bugs: BugFinding[];
+    refactorPlans: RefactorPlan[];
+    evaluations: CriticEvaluation[];
+    /** Alerts that were raised during the session (may be empty). */
+    alerts: DirectorAlert[];
+    /** Files modified after the initial static snapshot was captured. */
+    snapshotWarnings?: string[] | undefined;
+    /** Overall verdict from the Critic across all evaluated subjects. */
+    overallVerdict: 'approve' | 'needs_revision' | 'reject';
+    /** Markdown-formatted summary for the director's context window. */
+    summary: string;
+}
+/**
+ * Per-agent budget configuration for collab sessions.
+ * Allows the caller (Director) to control the exact limits instead of
+ * using hard-coded defaults that may not match the director's policy.
+ */
+interface CollabBudgetConfig {
+    maxIterations: number;
+    maxToolCalls: number;
+    timeoutMs: number;
+}
+/**
+ * Budget overrides for specific roles in a collab session.
+ * When a role is not present in the map, the default budget is used.
+ */
+type CollabBudgetOverrides = Partial<Record<string, CollabBudgetConfig>>;
+/**
+ * Emitted by a collab agent when it hits a soft budget limit.
+ * The Director's fleet handler receives this and calls collabAlert().
+ */
+interface CollabBudgetWarningPayload {
+    sessionId: string;
+    role: string;
+    kind: 'timeout' | 'idle_timeout' | 'iterations' | 'tool_calls' | 'tokens' | 'cost';
+    used: number;
+    limit: number;
+    timeoutMs?: number | undefined;
+    elapsedMs: number;
+}
+/**
+ * Emitted by the Director to cancel all agents in a collab session.
+ * CollabSession listens for this and causes its agent pool to finish early.
+ */
+interface DirectorCancelCollabPayload {
+    sessionId: string;
+    reason: string;
+    cancelledAt: string;
+}
+interface CollabSessionOptions {
+    /** Paths to scan — used to build the SharedFileSnapshot. */
+    targetPaths: string[];
+    /** Files already read and snapshot. When provided, snapshot is skipped. */
+    prebuiltSnapshot?: SharedFileSnapshot | undefined;
+    /** Max time to wait for the session to resolve (ms). Default: 10 min. */
+    timeoutMs?: number | undefined;
+    /**
+     * Maximum number of files to include in the snapshot.
+     * - If set explicitly: use this value (hard override).
+     * - If `contextWindow` is set: calculate dynamically from estimated token budget.
+     * - If neither: use `DEFAULT_MAX_TARGET_FILES` (30).
+     */
+    maxTargetFiles?: number | undefined;
+    /**
+     * Context window size (in tokens) of the model running the subagents.
+     * When provided and `maxTargetFiles` is not set, the limit is computed
+     * dynamically: `floor((contextWindow * 0.4) / AVG_TOKENS_PER_FILE)`.
+     * If not provided, `DEFAULT_MAX_TARGET_FILES` is used as the fallback.
+     */
+    contextWindow?: number | undefined;
+    /**
+     * Budget overrides per role. When provided, these override the hard-coded
+     * defaults so the Director can enforce fleet-wide budget policy.
+     * Keys must match role names: 'bug-hunter', 'refactor-planner', 'critic'.
+     */
+    budgetOverrides?: CollabBudgetOverrides | undefined;
+    /**
+     * Called by the Director when a collab agent hits a soft budget limit.
+     * The Director uses this to decide whether to cancel the session or extend.
+     * Return 'cancel' to stop the session immediately; 'extend' to continue
+     * with the agent's proposed new limits; 'ignore' to let the default
+     * auto-extend logic handle it.
+     */
+    onBudgetWarning?: ((alert: DirectorAlert) => 'cancel' | 'extend' | 'ignore') | undefined;
+}
+declare class CollabSession extends EventEmitter {
+    readonly sessionId: string;
+    readonly options: CollabSessionOptions;
+    readonly snapshot: SharedFileSnapshot;
+    private readonly director;
+    private readonly fleetBus;
+    private readonly subagentIds;
+    private readonly bugs;
+    private readonly plans;
+    private readonly evaluations;
+    private readonly disposers;
+    private settled;
+    private readonly timeoutMs;
+    private cancelled;
+    private _raceResolved;
+    private readonly alerts;
+    private snapshotWarnings;
+    /** Tracks tool call counts per subagent for progress-based timeout decisions. */
+    private readonly progressBySubagent;
+    /** Last tool call count when a timeout warning was handled. */
+    private readonly lastTimeoutProgress;
+    /** Session-level timeout timer handle (cleared on cancel or natural completion). */
+    private _timeoutTimer?;
+    constructor(director: Director, fleetBus: FleetBus, options: CollabSessionOptions);
+    get id(): string;
+    getSessionAlerts(): DirectorAlert[];
+    isCancelled(): boolean;
+    /**
+     * Snapshot of role → subagentId map. The Director calls coordinator.stop()
+     * for each agent when cancelling the session, using this map to enumerate
+     * all three collab agents.
+     */
+    getSubagentIds(): ReadonlyMap<string, string>;
+    /**
+     * Returns the effective file limit for this session.
+     * Priority: explicit `maxTargetFiles` > dynamic from `contextWindow` > `DEFAULT_MAX_TARGET_FILES`.
+     */
+    effectiveFileLimit(): number;
+    buildSnapshot(): Promise<SharedFileSnapshot>;
+    /**
+     * Cancel the session. Emits director.cancel_collab on the FleetBus so all
+     * collab agents finish early. The session-level timeout timer is also cleared.
+     * Safe to call multiple times (idempotent after first call).
+     */
+    cancel(reason?: string): void;
+    start(): Promise<CollabDebugReport>;
+    private parseAndEmit;
+    private extractJsonObjects;
+    private budgetForRole;
+    private spawnAgent;
+    private buildBugHunterTask;
+    private buildRefactorPlannerTask;
+    private buildCriticTask;
+    private wireFleetBus;
+    private roleFromSubagentId;
+    private assembleReport;
+    private checkSnapshotFreshness;
+    private buildMarkdownSummary;
+    private cleanup;
+}
 
 /**
  * Opaque host interface so this factory doesn't have to depend on the
@@ -1619,73 +1606,6 @@ interface CreateDelegateToolOptions {
  */
 declare function createDelegateTool(opts: CreateDelegateToolOptions): Tool;
 
-/**
- * Per-subagent session factory.
- *
- * Director runs produce many parallel transcripts — one per spawned
- * subagent — and we want them all rooted under the same director-run
- * directory so a future `wstack replay <runId>` can rehydrate the whole
- * fleet from a single tree.
- *
- * The factory builds (or accepts) a `SessionStore` whose `dir` points at
- * `<sessionsRoot>/<directorRunId>/`, and returns a small `create()`
- * function that the orchestration layer calls per-spawn. Each call
- * yields a fresh `SessionWriter` whose JSONL file lives in that
- * directory, named by either the caller-supplied `subagentId` (preferred,
- * so the file name is human-readable) or a derived id.
- *
- * **Why a thin factory instead of plumbing options through every spawn
- * site?** Because the director is the only caller that needs this
- * isolation pattern, and shoving `sessionStore` options into
- * `SubagentConfig` would leak storage details into a config shape that
- * agents and the coordinator have no business knowing about.
- */
-interface DirectorSessionFactoryOptions {
-    /**
-     * Either a parent directory where `<directorRunId>/` will be created,
-     * or a pre-built `SessionStore` whose `dir` already points at the
-     * director run directory. Tests pass an in-memory store for isolation;
-     * production code passes the path under `~/.wrongstack/sessions/`.
-     */
-    store?: SessionStore | undefined;
-    sessionsRoot?: string | undefined;
-    /**
-     * Director run id — namespaces all subagent JSONLs under one folder.
-     * Defaults to a timestamped id; supplied explicitly when resuming a
-     * prior fleet manifest.
-     */
-    directorRunId?: string | undefined;
-    /**
-     * Session-level trace ID for correlating subagent storage events with
-     * the parent session's trace in observability pipelines.
-     */
-    traceId?: string | undefined;
-}
-interface DirectorSessionFactory {
-    /** Absolute directory where this director run's transcripts live. */
-    readonly dir: string;
-    /** The director run id used to namespace the directory. */
-    readonly directorRunId: string;
-    /**
-     * Create a fresh `SessionWriter` for the named subagent. Each
-     * subagent gets its own JSONL file. The writer's `id` matches the
-     * supplied `subagentId` so disk paths line up with in-memory ids.
-     */
-    createSubagentSession(args: {
-        subagentId: string;
-        provider?: string | undefined;
-        model?: string | undefined;
-        title?: string | undefined;
-    }): Promise<SessionWriter>;
-}
-/**
- * Build a `DirectorSessionFactory`. Pass either a pre-configured
- * `SessionStore` (tests) or a `sessionsRoot` path (production). When
- * neither is supplied the factory throws — there's no sane default for
- * "where do these JSONLs live".
- */
-declare function makeDirectorSessionFactory(opts: DirectorSessionFactoryOptions): DirectorSessionFactory;
-
 /**
  * System-prompt composition helpers for the Director ecosystem.
  *
@@ -1805,6 +1725,132 @@ declare function rosterSummaryFromConfigs(roster: Record<string, {
     role?: string | undefined;
 }>): string;
 
+/**
+ * Per-subagent session factory.
+ *
+ * Director runs produce many parallel transcripts — one per spawned
+ * subagent — and we want them all rooted under the same director-run
+ * directory so a future `wstack replay <runId>` can rehydrate the whole
+ * fleet from a single tree.
+ *
+ * The factory builds (or accepts) a `SessionStore` whose `dir` points at
+ * `<sessionsRoot>/<directorRunId>/`, and returns a small `create()`
+ * function that the orchestration layer calls per-spawn. Each call
+ * yields a fresh `SessionWriter` whose JSONL file lives in that
+ * directory, named by either the caller-supplied `subagentId` (preferred,
+ * so the file name is human-readable) or a derived id.
+ *
+ * **Why a thin factory instead of plumbing options through every spawn
+ * site?** Because the director is the only caller that needs this
+ * isolation pattern, and shoving `sessionStore` options into
+ * `SubagentConfig` would leak storage details into a config shape that
+ * agents and the coordinator have no business knowing about.
+ */
+interface DirectorSessionFactoryOptions {
+    /**
+     * Either a parent directory where `<directorRunId>/` will be created,
+     * or a pre-built `SessionStore` whose `dir` already points at the
+     * director run directory. Tests pass an in-memory store for isolation;
+     * production code passes the path under `~/.wrongstack/sessions/`.
+     */
+    store?: SessionStore | undefined;
+    sessionsRoot?: string | undefined;
+    /**
+     * Director run id — namespaces all subagent JSONLs under one folder.
+     * Defaults to a timestamped id; supplied explicitly when resuming a
+     * prior fleet manifest.
+     */
+    directorRunId?: string | undefined;
+    /**
+     * Session-level trace ID for correlating subagent storage events with
+     * the parent session's trace in observability pipelines.
+     */
+    traceId?: string | undefined;
+}
+interface DirectorSessionFactory {
+    /** Absolute directory where this director run's transcripts live. */
+    readonly dir: string;
+    /** The director run id used to namespace the directory. */
+    readonly directorRunId: string;
+    /**
+     * Create a fresh `SessionWriter` for the named subagent. Each
+     * subagent gets its own JSONL file. The writer's `id` matches the
+     * supplied `subagentId` so disk paths line up with in-memory ids.
+     */
+    createSubagentSession(args: {
+        subagentId: string;
+        provider?: string | undefined;
+        model?: string | undefined;
+        title?: string | undefined;
+    }): Promise<SessionWriter>;
+}
+/**
+ * Build a `DirectorSessionFactory`. Pass either a pre-configured
+ * `SessionStore` (tests) or a `sessionsRoot` path (production). When
+ * neither is supplied the factory throws — there's no sane default for
+ * "where do these JSONLs live".
+ */
+declare function makeDirectorSessionFactory(opts: DirectorSessionFactoryOptions): DirectorSessionFactory;
+
+declare function makeSpawnTool(director: Director, roster?: Record<string, SubagentConfig>): Tool;
+declare function makeAssignTool(director: Director): Tool;
+declare function makeAwaitTasksTool(director: Director): Tool;
+declare function makeAskTool(director: Director): Tool;
+/**
+ * Retrieve a previously stored `ask_subagent` answer by its store key.
+ * The key was returned as `_answerKey` in the ask_subagent response.
+ * Use this only for large responses that were stored out-of-context.
+ */
+declare function makeAskResultTool(director: Director): Tool;
+declare function makeRollUpTool(director: Director): Tool;
+declare function makeTerminateTool(director: Director): Tool;
+declare function makeTerminateAllTool(director: Director): Tool;
+/**
+ * Unified fleet observation tool — consolidates the former fleet_status,
+ * fleet_usage, fleet_session, and fleet_health tools under a single `action`
+ * parameter (status, usage, health, session).
+ *
+ * These four are all read-only fleet queries; merging them into one tool
+ * reduces tool-schema token overhead (4 × ~150 tokens → 1 × ~250 tokens)
+ * and eliminates model confusion when choosing between similar tools.
+ */
+declare function makeFleetTool(director: Director): Tool;
+/**
+ * Collaborative debugging session: BugHunter, RefactorPlanner, and Critic
+ * run in parallel on the same target files, with findings flowing through
+ * the FleetBus (bug.found → refactor.plan → critic.evaluation).
+ *
+ * Returns a structured CollabDebugReport containing all bug findings,
+ * refactor plans, critic evaluations, and an overall verdict.
+ */
+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.
+ * Common event types in collaborative sessions:
+ *   bug.found        — BugHunter emits per-finding
+ *   refactor.plan    — RefactorPlanner emits per-plan
+ *   critic.evaluation — Critic emits per-evaluation
+ *
+ * The payload structure is event-type-specific. Use null for empty payloads.
+ */
+declare function makeFleetEmitTool(director: Director): Tool;
+/**
+ * Signal that the director's work is satisfied and the fleet should wind down.
+ *
+ * Once called:
+ * - `spawn_subagent` throws — no new subagents can be created
+ * - `assign_task` synthesizes an immediate `aborted_by_parent` completion
+ *   for any queued task (callers awaiting those tasks unblock immediately)
+ * - Running subagents are NOT killed — they finish naturally; no new
+ *   tasks are dispatched to them
+ *
+ * Use this when you are satisfied with the results and want the fleet to
+ * stop spawning without forcibly stopping in-flight work. Call
+ * `terminate_subagent` separately for any subagent you need to stop immediately.
+ */
+declare function makeWorkCompleteTool(director: Director): Tool;
+
 /**
  * Pre-built subagent role configurations for the WrongStack fleet.
  * These can be passed to `MultiAgentHost.spawn()` or used as templates
@@ -1856,52 +1902,6 @@ declare const ACP_AGENTS: SubagentConfig[];
 /** Extended roster including ACP agents. */
 declare const FLEET_ROSTER_WITHACP: Record<string, SubagentConfig>;
 
-/**
- * Default auto-extend policy for subagent budgets.
- *
- * The budget's soft-limit path (`SubagentBudget` → `budget.threshold_reached`)
- * only negotiates an extension when SOMETHING listens on the EventBus. Under a
- * `Director`, that listener is the director's own auto-extend handler. On the
- * plain coordinator path (e.g. a bare `/spawn` with no director) nothing
- * listens, so the budget falls back to a hard stop and the subagent dies the
- * moment it crosses a soft limit.
- *
- * `attachAutoExtend` is the additive fix: wire it to a subagent's EventBus and
- * budget overruns are auto-granted headroom instead of killing the run. It is
- * heartbeat-aware for the timeout kind — wall-clock time always advances, so a
- * naive "extend timeout forever" would let a wedged agent run indefinitely.
- * Instead, a timeout extension is granted only when the agent has executed a
- * new tool call or started a new iteration since the last timeout extension.
- * No progress since last time ⇒ the agent is genuinely stuck ⇒ deny and let it
- * fail. The non-timeout kinds (iterations/tool_calls/tokens/cost) extend up to
- * a per-kind cap, then deny — those ceilings are the real runaway guard.
- */
-
-interface AutoExtendCeiling {
-    maxIterations?: number | undefined;
-    maxToolCalls?: number | undefined;
-    maxTokens?: number | undefined;
-    maxCostUsd?: number | undefined;
-    timeoutMs?: number | undefined;
-}
-interface AutoExtendPolicy {
-    /** Multiplier applied to the tripped limit when extending. Default 0.5 (+50%). */
-    factor?: number | undefined;
-    /**
-     * Max extensions per NON-timeout kind before denying. Timeout is governed by
-     * the heartbeat check, not this cap, so it can extend indefinitely while the
-     * agent makes progress. Default 8.
-     */
-    maxExtensionsPerKind?: number | undefined;
-    /** Absolute ceilings — an extension never pushes a limit past these. */
-    ceiling?: AutoExtendCeiling | undefined;
-}
-/**
- * Attach an auto-extend policy to a subagent's EventBus. Returns an unsubscribe
- * function that detaches all listeners — call it when the subagent task ends.
- */
-declare function attachAutoExtend(events: EventBus, policy?: AutoExtendPolicy): () => void;
-
 /**
  * A no-op FleetBus that discards all events. Used when no real fleet
  * bus is available (non-director mode) so the runner's `fleetBus`