@harness-engineering/orchestrator 0.2.16 → 0.3.0

package/dist/index.d.mts

@@ -1,4 +1,4 @@
-import { Issue, AgentEvent, WorkflowConfig, IssueTrackerClient, TokenUsage, ConcernSignal, ScopeTier, EscalationConfig, RoutingDecision, Result, WorkflowDefinition, TrackerConfig, WorkspaceConfig, HooksConfig, AgentBackend, SessionStartParams, AgentSession, AgentError, TurnParams, TurnResult } from '@harness-engineering/types';
+import { Issue, AgentEvent, WorkflowConfig, IssueTrackerClient, TokenUsage, ConcernSignal, ScopeTier, EscalationConfig, RoutingDecision, Result, WorkflowDefinition, TrackerConfig, WorkspaceConfig, HooksConfig, AgentBackend, SessionStartParams, AgentSession, AgentError, TurnParams, TurnResult, BackendDef, RoutingConfig, RoutingUseCase, ContainerConfig, SecretConfig, AgentConfig } from '@harness-engineering/types';
 import { EnrichedSpec, ComplexityScore, SimulationResult, IntelligencePipeline, WeightedRecommendation } from '@harness-engineering/intelligence';
 import { GraphStore } from '@harness-engineering/graph';
 import { execFile } from 'node:child_process';
@@ -1093,22 +1093,38 @@ interface MaintenanceStatus {
     history: RunResult[];
 }
 
-/**
- * The central orchestrator that manages the lifecycle of coding agents.
- *
- * It polls an issue tracker for candidate tasks, manages ephemeral workspaces,
- * runs agents to resolve issues, and updates the tracker with progress.
- *
- * @fires Orchestrator#state_change Emitted when the internal state machine transitions
- * @fires Orchestrator#agent_event Emitted when an agent produces an output or thought
- */
 declare class Orchestrator extends EventEmitter {
     private state;
     private config;
     private tracker;
     private workspace;
     private hooks;
-    private runner;
+    /**
+     * Spec 2 SC30 / Task 11: per-dispatch backend factory replaces the
+     * Phase 1 `runner` / `localRunner` two-runner split. Each
+     * `dispatchIssue()` call asks the factory for a `RoutingUseCase`-routed
+     * `AgentBackend`, then wraps it in a fresh `AgentRunner`.
+     *
+     * `AgentRunner` is stateless (just `{ backend, options }`), so
+     * per-dispatch construction is safe and avoids the cross-call state
+     * the old two-runner split had to coordinate.
+     *
+     * Null only in the legacy fallback path: when `migrateAgentConfig`
+     * throws (legacy configs missing supplemental fields, e.g.
+     * `agent.backend='anthropic'` with no `agent.model`) AND no
+     * `overrides.backend` is supplied, factory construction is skipped to
+     * preserve the prior behavior of failing at dispatch time rather than
+     * construction time. Eliminating this fallback is autopilot Phase 4+.
+     */
+    private backendFactory;
+    /**
+     * Test-only: when overrides.backend is provided, dispatch uses this
+     * instance directly (bypassing the factory). Mirrors Phase 1
+     * `overrides.backend → this.runner.backend` behavior so existing
+     * MockBackend-injection tests keep working without touching the
+     * factory's routing path.
+     */
+    private overrideBackend;
     private renderer;
     private promptTemplate;
     private server?;
@@ -1116,7 +1132,22 @@ declare class Orchestrator extends EventEmitter {
     private heartbeatInterval?;
     private logger;
     private interactionQueue;
-    private localRunner;
+    /**
+     * Per-named-backend resolver map (Spec 2 SC37). Each `local`/`pi` entry
+     * in `agent.backends` spawns one `LocalModelResolver`. Legacy
+     * single-backend configs converge here via `migrateAgentConfig` (Task 9),
+     * so this map is the single source of truth post-migration.
+     */
+    private localResolvers;
+    /**
+     * Per-resolver `onStatusChange` unsubscribe callbacks. Spec 2 Phase 5
+     * (SC39): each local/pi resolver gets its own listener emitting a
+     * `NamedLocalModelStatus` event tagged with `backendName` + `endpoint`.
+     * The previous single-resolver field (`localModelStatusUnsubscribe`)
+     * is replaced by this list so multi-local configs can teardown all
+     * listeners on `stop()` without a Map mutation.
+     */
+    private localModelStatusUnsubscribes;
     private pipeline;
     private analysisArchive;
     private graphStore;
@@ -1156,7 +1187,6 @@ declare class Orchestrator extends EventEmitter {
         execFileFn?: ExecFileFn;
     });
     private createTracker;
-    private createBackend;
     /**
      * Creates a TaskRunner for the maintenance scheduler.
      * CheckCommandRunner and CommandExecutor use real child_process execution.
@@ -1168,17 +1198,35 @@ declare class Orchestrator extends EventEmitter {
      * Extracted from start() to keep function length under threshold.
      */
     private initMaintenance;
-    private createLocalBackend;
     private createIntelligencePipeline;
     /**
-     * Create the AnalysisProvider for the intelligence pipeline.
+     * Create the AnalysisProvider for an intelligence-pipeline layer
+     * (`sel` by default; `pesl` when constructing a distinct PESL
+     * provider per Spec 2 SC35).
+     *
+     * Spec 2 Phase 4 (SC31–SC36) — resolution order:
+     *   1. Explicit `intelligence.provider` config wins (preserves Phase 0–3 behavior; SC33).
+     *   2. Otherwise, consult `agent.routing.intelligence.<layer>` (or
+     *      `routing.default`) to pick a `BackendDef` from `agent.backends`,
+     *      then translate via `buildAnalysisProvider` (the per-type factory).
      *
-     * Resolution order:
-     * 1. Explicit `intelligence.provider` config (separate key/endpoint)
-     * 2. Local backend config (agent.localBackend + localEndpoint/localModel)
-     * 3. Primary agent backend config (agent.apiKey + agent.backend)
+     * Closes the Phase 2 deferral (P2-DEF-638): the legacy
+     * `this.config.agent.backend` read at the bottom of this method is
+     * removed; routing is the sole source for non-explicit configs.
+     *
+     * Cyclomatic complexity: pre-Phase-4 was 33 (factory dispatch was
+     * inlined here). Phase 4 extracts the per-type tree into
+     * `buildAnalysisProvider`, dropping this method to ≤ 5 branches
+     * (under the 15 threshold).
      */
     private createAnalysisProvider;
+    /**
+     * Look up the routed BackendDef for an intelligence layer, falling
+     * back through `routing.intelligence.<layer>` → `routing.default`
+     * → null. Returns the resolved name alongside the def so callers can
+     * key into the per-name resolver map.
+     */
+    private resolveRoutedBackendForIntelligence;
     private createProviderFromExplicitConfig;
     /**
      * Lazily initializes the ClaimManager if it hasn't been created yet.
@@ -1262,6 +1310,14 @@ declare class Orchestrator extends EventEmitter {
      * Used by the dashboard's "Dispatch Now" action.
      */
     dispatchAdHoc(issue: Issue): Promise<void>;
+    /**
+     * Initialize the LocalModelResolver and intelligence pipeline.
+     *
+     * Runs the initial probe (so resolver state reflects server availability)
+     * before constructing the intelligence pipeline. Subscribes the dashboard
+     * broadcast stub to status changes. Called exactly once from start().
+     */
+    private initLocalModelAndPipeline;
     /**
      * Starts the polling loop and the internal HTTP server.
      * Runs startup reconciliation to release orphaned claims before the first tick.
@@ -1292,4 +1348,169 @@ declare function launchTUI(orchestrator: Orchestrator): {
     waitUntilExit: () => Promise<void>;
 };
 
-export { type AgentUpdateEvent, AnalysisArchive, type AnalysisRecord, type ApplyEventResult, type ArtifactPresence, type AttemptStats, ClaimManager, type ClaimManagerConfig, type CleanWorkspaceEffect, type DispatchEffect, type EmitLogEffect, type EscalateEffect, type ExecFileFn, type Highlight, type HighlightsInfo, InteractionQueue, type LinearGraphQLExtension, LinearGraphQLStub, type LiveSession, MockBackend, ORCHESTRATOR_IDENTITY_FILE, Orchestrator, type OrchestratorContext, type OrchestratorEvent, type OrchestratorState, PRDetector, type PRDetectorLogger, type PendingInteraction, PromptRenderer, type PublishedIndex, type RateLimitSnapshot as RateLimitComputeSnapshot, type RateLimitConfig, type RateLimitSnapshot$1 as RateLimitSnapshot, type ReleaseClaimEffect, type RetryEntry, type RetryFiredEvent, RoadmapTrackerAdapter, type RunAttemptPhase, type RunningEntry, type ScheduleRetryEffect, type SideEffect, type StallDetectedEvent, type StopEffect, type StreamManifest, StreamRecorder, type TickEvent, type TokenTotals, type TriageConfig, type TriageDecision, type TriageSignals, type TriageSkill, type UpdateTokensEffect, type WorkerExitEvent, WorkflowLoader, WorkspaceHooks, WorkspaceManager, applyEvent, artifactPresenceFromIssue, calculateRetryDelay, canDispatch, computeRateLimitDelay, createEmptyState, detectScopeTier, extractHighlights, extractTitlePrefix, getAvailableSlots, getDefaultConfig, getPerStateCount, isEligible, launchTUI, loadPublishedIndex, reconcile, renderAnalysisComment, renderPRComment, resolveEscalationConfig, resolveOrchestratorId, routeIssue, savePublishedIndex, selectCandidates, sortCandidates, triageIssue, validateWorkflowConfig };
+interface BackendRouterOptions {
+    backends: Record<string, BackendDef>;
+    routing: RoutingConfig;
+}
+/**
+ * BackendRouter
+ *
+ * Owns the lookup from a `RoutingUseCase` (a discriminated query — tier,
+ * intelligence layer, maintenance, chat) to a named backend.
+ * Construction-time validation guarantees every name referenced by
+ * `routing` is present in `backends` so runtime lookups are total and
+ * never throw on unknown-name references (D6/D7).
+ *
+ * Lookups for tier/intelligence use cases that fall through to undefined
+ * mappings return `routing.default` without throwing — this matches the
+ * spec's "every use case inherits default unless explicitly routed"
+ * semantics. The `maintenance` and `chat` kinds always resolve to
+ * `routing.default` (SC19, SC20).
+ */
+declare class BackendRouter {
+    private readonly backends;
+    private readonly routing;
+    constructor(opts: BackendRouterOptions);
+    /**
+     * Returns the backend name for a given use case.
+     *
+     * - `tier`: per-tier override, falling back to `routing.default`.
+     * - `intelligence`: per-layer override under `routing.intelligence`,
+     *   falling back to `routing.default`.
+     * - `maintenance` / `chat`: always `routing.default`.
+     */
+    resolve(useCase: RoutingUseCase): string;
+    /**
+     * Returns the BackendDef reference for the resolved name. Returns the
+     * exact reference held in `backends` (no copy) so identity comparisons
+     * succeed (SC21).
+     */
+    resolveDefinition(useCase: RoutingUseCase): BackendDef;
+    private validateReferences;
+}
+
+/**
+ * Options for `OrchestratorBackendFactory`.
+ *
+ * `sandboxPolicy` and `container`/`secrets` mirror the orchestrator's own
+ * agent-config fields. `getResolverModelFor` is a registration hook the
+ * orchestrator calls to bind each `local`/`pi` backend to its
+ * `LocalModelResolver` (so multi-resolver array-fallback works without
+ * leaking resolver lifetimes into the factory).
+ */
+interface OrchestratorBackendFactoryOptions {
+    backends: Record<string, BackendDef>;
+    routing: RoutingConfig;
+    sandboxPolicy: 'none' | 'docker';
+    container?: ContainerConfig;
+    secrets?: SecretConfig;
+    /**
+     * Hook for resolver injection. Invoked per `local`/`pi` backend at
+     * `forUseCase()` time with the backend's name. When the hook returns a
+     * function, the factory rebuilds the local/pi instance using that
+     * function as `getModel` (overriding the head-of-array placeholder
+     * baked into `createBackend`). Returning `undefined` means "no
+     * resolver registered for this name" — the placeholder stays in place.
+     *
+     * This indirection keeps the factory ignorant of `LocalModelResolver`'s
+     * existence and lifecycle while still letting it produce backends that
+     * route through the resolver Map.
+     */
+    getResolverModelFor?: (backendName: string) => (() => string | null) | undefined;
+}
+/**
+ * High-level factory wrapping `BackendRouter` + `createBackend` plus
+ * orchestrator-side concerns (sandbox wrapping, resolver binding).
+ *
+ * Spec 2 SC22-SC25: every `forUseCase(useCase)` call returns a fresh
+ * `AgentBackend` whose class matches the routed `BackendDef.type`.
+ * `local`/`pi` defs are bound to their per-name resolver before being
+ * returned, and the result is wrapped in `ContainerBackend` when
+ * sandboxPolicy is 'docker'.
+ */
+declare class OrchestratorBackendFactory {
+    private readonly router;
+    private readonly opts;
+    constructor(opts: OrchestratorBackendFactoryOptions);
+    /**
+     * Resolve `useCase` to a backend name, materialize a fresh
+     * `AgentBackend`, optionally rebind its model resolver, and apply
+     * sandbox wrapping. Idempotent across calls (no caching) — the AgentRunner
+     * holds the per-dispatch reference and discards it when the run ends.
+     */
+    /**
+     * Resolve `useCase` to its routed backend name, exposing the
+     * router lookup without materializing a backend. Used by callers
+     * (e.g., the orchestrator's dispatch site) that need to label
+     * telemetry with the routed name BEFORE constructing the backend.
+     *
+     * Spec 2 P2-I2: previously the orchestrator labelled `LiveSession`
+     * + `StreamRecorder` with the legacy `agent.backend` field, which
+     * is `undefined` for pure-modern configs. Threading the routed name
+     * through dispatch eliminates that gap.
+     */
+    resolveName(useCase: RoutingUseCase): string;
+    forUseCase(useCase: RoutingUseCase): AgentBackend;
+    /**
+     * Rebuild a `local`/`pi` backend with a resolver-bound `getModel`,
+     * mirroring `createBackend`'s local/pi branches but substituting the
+     * head-of-array placeholder with the orchestrator-owned resolver.
+     */
+    private buildLocalLikeWithResolver;
+    /**
+     * Apply ContainerBackend wrapping (PFC-3). Pulls the runtime + secret
+     * backend per call so each dispatch sees a fresh container handle map
+     * (ContainerBackend keeps its own per-instance Map<sessionId, handle>).
+     */
+    private wrapInContainer;
+}
+
+/**
+ * Result of running `migrateAgentConfig`.
+ *
+ * `config` is the *effective* AgentConfig — either the input unchanged
+ * (when `agent.backends` is already set or no migration is needed) or
+ * the input augmented with synthesized `backends` and `routing` fields.
+ *
+ * `warnings` is a list of human-readable deprecation messages, one per
+ * legacy field encountered. Each message names the deprecated field
+ * (dotted path) and includes a pointer to the migration guide. The
+ * orchestrator emits these as `warn`-level log entries at startup.
+ */
+interface MigrationResult {
+    config: AgentConfig;
+    warnings: string[];
+}
+/**
+ * Translate legacy `agent.backend` / `agent.localBackend` /
+ * `agent.escalation.autoExecute` into the new `agent.backends` +
+ * `agent.routing` shape (Spec 2 D3, D4, D8, D11).
+ *
+ * Behavior matrix:
+ * - `agent.backends` already set, no legacy fields:
+ *     no-op; returns input config unchanged, warnings = [].
+ * - `agent.backends` already set + at least one legacy field:
+ *     no-op on config; warnings name each ignored legacy field (D4).
+ * - No `agent.backends`, at least one of `agent.backend` /
+ *   `agent.localBackend` / `agent.localEndpoint` / etc. set:
+ *     synthesize `backends.primary` (always, from `agent.backend`)
+ *     and `backends.local` (when `localBackend` is set), plus a
+ *     `routing` map driven by `escalation.autoExecute` (D3).
+ * - No `agent.backends`, no legacy fields:
+ *     no-op; the caller's downstream Zod validation surfaces the gap
+ *     as a missing-required-field error.
+ *
+ * Throws on internal inconsistencies (e.g., `agent.backend = 'pi'`
+ * with no `localEndpoint`/`localModel`) — these are user-config bugs
+ * that would have produced a runtime crash today.
+ */
+declare function migrateAgentConfig(agent: AgentConfig): MigrationResult;
+
+/**
+ * Pure constructor: BackendDef -> concrete AgentBackend instance.
+ * No side effects beyond the underlying class constructors.
+ * Container wrapping (sandbox policy) is the orchestrator's job, not the factory's.
+ */
+declare function createBackend(def: BackendDef): AgentBackend;
+
+export { type AgentUpdateEvent, AnalysisArchive, type AnalysisRecord, type ApplyEventResult, type ArtifactPresence, type AttemptStats, BackendRouter, type BackendRouterOptions, ClaimManager, type ClaimManagerConfig, type CleanWorkspaceEffect, type DispatchEffect, type EmitLogEffect, type EscalateEffect, type ExecFileFn, type Highlight, type HighlightsInfo, InteractionQueue, type LinearGraphQLExtension, LinearGraphQLStub, type LiveSession, type MigrationResult, MockBackend, ORCHESTRATOR_IDENTITY_FILE, Orchestrator, OrchestratorBackendFactory, type OrchestratorBackendFactoryOptions, type OrchestratorContext, type OrchestratorEvent, type OrchestratorState, PRDetector, type PRDetectorLogger, type PendingInteraction, PromptRenderer, type PublishedIndex, type RateLimitSnapshot as RateLimitComputeSnapshot, type RateLimitConfig, type RateLimitSnapshot$1 as RateLimitSnapshot, type ReleaseClaimEffect, type RetryEntry, type RetryFiredEvent, RoadmapTrackerAdapter, type RunAttemptPhase, type RunningEntry, type ScheduleRetryEffect, type SideEffect, type StallDetectedEvent, type StopEffect, type StreamManifest, StreamRecorder, type TickEvent, type TokenTotals, type TriageConfig, type TriageDecision, type TriageSignals, type TriageSkill, type UpdateTokensEffect, type WorkerExitEvent, WorkflowLoader, WorkspaceHooks, WorkspaceManager, applyEvent, artifactPresenceFromIssue, calculateRetryDelay, canDispatch, computeRateLimitDelay, createBackend, createEmptyState, detectScopeTier, extractHighlights, extractTitlePrefix, getAvailableSlots, getDefaultConfig, getPerStateCount, isEligible, launchTUI, loadPublishedIndex, migrateAgentConfig, reconcile, renderAnalysisComment, renderPRComment, resolveEscalationConfig, resolveOrchestratorId, routeIssue, savePublishedIndex, selectCandidates, sortCandidates, triageIssue, validateWorkflowConfig };

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { Issue, AgentEvent, WorkflowConfig, IssueTrackerClient, TokenUsage, ConcernSignal, ScopeTier, EscalationConfig, RoutingDecision, Result, WorkflowDefinition, TrackerConfig, WorkspaceConfig, HooksConfig, AgentBackend, SessionStartParams, AgentSession, AgentError, TurnParams, TurnResult } from '@harness-engineering/types';
+import { Issue, AgentEvent, WorkflowConfig, IssueTrackerClient, TokenUsage, ConcernSignal, ScopeTier, EscalationConfig, RoutingDecision, Result, WorkflowDefinition, TrackerConfig, WorkspaceConfig, HooksConfig, AgentBackend, SessionStartParams, AgentSession, AgentError, TurnParams, TurnResult, BackendDef, RoutingConfig, RoutingUseCase, ContainerConfig, SecretConfig, AgentConfig } from '@harness-engineering/types';
 import { EnrichedSpec, ComplexityScore, SimulationResult, IntelligencePipeline, WeightedRecommendation } from '@harness-engineering/intelligence';
 import { GraphStore } from '@harness-engineering/graph';
 import { execFile } from 'node:child_process';
@@ -1093,22 +1093,38 @@ interface MaintenanceStatus {
     history: RunResult[];
 }
 
-/**
- * The central orchestrator that manages the lifecycle of coding agents.
- *
- * It polls an issue tracker for candidate tasks, manages ephemeral workspaces,
- * runs agents to resolve issues, and updates the tracker with progress.
- *
- * @fires Orchestrator#state_change Emitted when the internal state machine transitions
- * @fires Orchestrator#agent_event Emitted when an agent produces an output or thought
- */
 declare class Orchestrator extends EventEmitter {
     private state;
     private config;
     private tracker;
     private workspace;
     private hooks;
-    private runner;
+    /**
+     * Spec 2 SC30 / Task 11: per-dispatch backend factory replaces the
+     * Phase 1 `runner` / `localRunner` two-runner split. Each
+     * `dispatchIssue()` call asks the factory for a `RoutingUseCase`-routed
+     * `AgentBackend`, then wraps it in a fresh `AgentRunner`.
+     *
+     * `AgentRunner` is stateless (just `{ backend, options }`), so
+     * per-dispatch construction is safe and avoids the cross-call state
+     * the old two-runner split had to coordinate.
+     *
+     * Null only in the legacy fallback path: when `migrateAgentConfig`
+     * throws (legacy configs missing supplemental fields, e.g.
+     * `agent.backend='anthropic'` with no `agent.model`) AND no
+     * `overrides.backend` is supplied, factory construction is skipped to
+     * preserve the prior behavior of failing at dispatch time rather than
+     * construction time. Eliminating this fallback is autopilot Phase 4+.
+     */
+    private backendFactory;
+    /**
+     * Test-only: when overrides.backend is provided, dispatch uses this
+     * instance directly (bypassing the factory). Mirrors Phase 1
+     * `overrides.backend → this.runner.backend` behavior so existing
+     * MockBackend-injection tests keep working without touching the
+     * factory's routing path.
+     */
+    private overrideBackend;
     private renderer;
     private promptTemplate;
     private server?;
@@ -1116,7 +1132,22 @@ declare class Orchestrator extends EventEmitter {
     private heartbeatInterval?;
     private logger;
     private interactionQueue;
-    private localRunner;
+    /**
+     * Per-named-backend resolver map (Spec 2 SC37). Each `local`/`pi` entry
+     * in `agent.backends` spawns one `LocalModelResolver`. Legacy
+     * single-backend configs converge here via `migrateAgentConfig` (Task 9),
+     * so this map is the single source of truth post-migration.
+     */
+    private localResolvers;
+    /**
+     * Per-resolver `onStatusChange` unsubscribe callbacks. Spec 2 Phase 5
+     * (SC39): each local/pi resolver gets its own listener emitting a
+     * `NamedLocalModelStatus` event tagged with `backendName` + `endpoint`.
+     * The previous single-resolver field (`localModelStatusUnsubscribe`)
+     * is replaced by this list so multi-local configs can teardown all
+     * listeners on `stop()` without a Map mutation.
+     */
+    private localModelStatusUnsubscribes;
     private pipeline;
     private analysisArchive;
     private graphStore;
@@ -1156,7 +1187,6 @@ declare class Orchestrator extends EventEmitter {
         execFileFn?: ExecFileFn;
     });
     private createTracker;
-    private createBackend;
     /**
      * Creates a TaskRunner for the maintenance scheduler.
      * CheckCommandRunner and CommandExecutor use real child_process execution.
@@ -1168,17 +1198,35 @@ declare class Orchestrator extends EventEmitter {
      * Extracted from start() to keep function length under threshold.
      */
     private initMaintenance;
-    private createLocalBackend;
     private createIntelligencePipeline;
     /**
-     * Create the AnalysisProvider for the intelligence pipeline.
+     * Create the AnalysisProvider for an intelligence-pipeline layer
+     * (`sel` by default; `pesl` when constructing a distinct PESL
+     * provider per Spec 2 SC35).
+     *
+     * Spec 2 Phase 4 (SC31–SC36) — resolution order:
+     *   1. Explicit `intelligence.provider` config wins (preserves Phase 0–3 behavior; SC33).
+     *   2. Otherwise, consult `agent.routing.intelligence.<layer>` (or
+     *      `routing.default`) to pick a `BackendDef` from `agent.backends`,
+     *      then translate via `buildAnalysisProvider` (the per-type factory).
      *
-     * Resolution order:
-     * 1. Explicit `intelligence.provider` config (separate key/endpoint)
-     * 2. Local backend config (agent.localBackend + localEndpoint/localModel)
-     * 3. Primary agent backend config (agent.apiKey + agent.backend)
+     * Closes the Phase 2 deferral (P2-DEF-638): the legacy
+     * `this.config.agent.backend` read at the bottom of this method is
+     * removed; routing is the sole source for non-explicit configs.
+     *
+     * Cyclomatic complexity: pre-Phase-4 was 33 (factory dispatch was
+     * inlined here). Phase 4 extracts the per-type tree into
+     * `buildAnalysisProvider`, dropping this method to ≤ 5 branches
+     * (under the 15 threshold).
      */
     private createAnalysisProvider;
+    /**
+     * Look up the routed BackendDef for an intelligence layer, falling
+     * back through `routing.intelligence.<layer>` → `routing.default`
+     * → null. Returns the resolved name alongside the def so callers can
+     * key into the per-name resolver map.
+     */
+    private resolveRoutedBackendForIntelligence;
     private createProviderFromExplicitConfig;
     /**
      * Lazily initializes the ClaimManager if it hasn't been created yet.
@@ -1262,6 +1310,14 @@ declare class Orchestrator extends EventEmitter {
      * Used by the dashboard's "Dispatch Now" action.
      */
     dispatchAdHoc(issue: Issue): Promise<void>;
+    /**
+     * Initialize the LocalModelResolver and intelligence pipeline.
+     *
+     * Runs the initial probe (so resolver state reflects server availability)
+     * before constructing the intelligence pipeline. Subscribes the dashboard
+     * broadcast stub to status changes. Called exactly once from start().
+     */
+    private initLocalModelAndPipeline;
     /**
      * Starts the polling loop and the internal HTTP server.
      * Runs startup reconciliation to release orphaned claims before the first tick.
@@ -1292,4 +1348,169 @@ declare function launchTUI(orchestrator: Orchestrator): {
     waitUntilExit: () => Promise<void>;
 };
 
-export { type AgentUpdateEvent, AnalysisArchive, type AnalysisRecord, type ApplyEventResult, type ArtifactPresence, type AttemptStats, ClaimManager, type ClaimManagerConfig, type CleanWorkspaceEffect, type DispatchEffect, type EmitLogEffect, type EscalateEffect, type ExecFileFn, type Highlight, type HighlightsInfo, InteractionQueue, type LinearGraphQLExtension, LinearGraphQLStub, type LiveSession, MockBackend, ORCHESTRATOR_IDENTITY_FILE, Orchestrator, type OrchestratorContext, type OrchestratorEvent, type OrchestratorState, PRDetector, type PRDetectorLogger, type PendingInteraction, PromptRenderer, type PublishedIndex, type RateLimitSnapshot as RateLimitComputeSnapshot, type RateLimitConfig, type RateLimitSnapshot$1 as RateLimitSnapshot, type ReleaseClaimEffect, type RetryEntry, type RetryFiredEvent, RoadmapTrackerAdapter, type RunAttemptPhase, type RunningEntry, type ScheduleRetryEffect, type SideEffect, type StallDetectedEvent, type StopEffect, type StreamManifest, StreamRecorder, type TickEvent, type TokenTotals, type TriageConfig, type TriageDecision, type TriageSignals, type TriageSkill, type UpdateTokensEffect, type WorkerExitEvent, WorkflowLoader, WorkspaceHooks, WorkspaceManager, applyEvent, artifactPresenceFromIssue, calculateRetryDelay, canDispatch, computeRateLimitDelay, createEmptyState, detectScopeTier, extractHighlights, extractTitlePrefix, getAvailableSlots, getDefaultConfig, getPerStateCount, isEligible, launchTUI, loadPublishedIndex, reconcile, renderAnalysisComment, renderPRComment, resolveEscalationConfig, resolveOrchestratorId, routeIssue, savePublishedIndex, selectCandidates, sortCandidates, triageIssue, validateWorkflowConfig };
+interface BackendRouterOptions {
+    backends: Record<string, BackendDef>;
+    routing: RoutingConfig;
+}
+/**
+ * BackendRouter
+ *
+ * Owns the lookup from a `RoutingUseCase` (a discriminated query — tier,
+ * intelligence layer, maintenance, chat) to a named backend.
+ * Construction-time validation guarantees every name referenced by
+ * `routing` is present in `backends` so runtime lookups are total and
+ * never throw on unknown-name references (D6/D7).
+ *
+ * Lookups for tier/intelligence use cases that fall through to undefined
+ * mappings return `routing.default` without throwing — this matches the
+ * spec's "every use case inherits default unless explicitly routed"
+ * semantics. The `maintenance` and `chat` kinds always resolve to
+ * `routing.default` (SC19, SC20).
+ */
+declare class BackendRouter {
+    private readonly backends;
+    private readonly routing;
+    constructor(opts: BackendRouterOptions);
+    /**
+     * Returns the backend name for a given use case.
+     *
+     * - `tier`: per-tier override, falling back to `routing.default`.
+     * - `intelligence`: per-layer override under `routing.intelligence`,
+     *   falling back to `routing.default`.
+     * - `maintenance` / `chat`: always `routing.default`.
+     */
+    resolve(useCase: RoutingUseCase): string;
+    /**
+     * Returns the BackendDef reference for the resolved name. Returns the
+     * exact reference held in `backends` (no copy) so identity comparisons
+     * succeed (SC21).
+     */
+    resolveDefinition(useCase: RoutingUseCase): BackendDef;
+    private validateReferences;
+}
+
+/**
+ * Options for `OrchestratorBackendFactory`.
+ *
+ * `sandboxPolicy` and `container`/`secrets` mirror the orchestrator's own
+ * agent-config fields. `getResolverModelFor` is a registration hook the
+ * orchestrator calls to bind each `local`/`pi` backend to its
+ * `LocalModelResolver` (so multi-resolver array-fallback works without
+ * leaking resolver lifetimes into the factory).
+ */
+interface OrchestratorBackendFactoryOptions {
+    backends: Record<string, BackendDef>;
+    routing: RoutingConfig;
+    sandboxPolicy: 'none' | 'docker';
+    container?: ContainerConfig;
+    secrets?: SecretConfig;
+    /**
+     * Hook for resolver injection. Invoked per `local`/`pi` backend at
+     * `forUseCase()` time with the backend's name. When the hook returns a
+     * function, the factory rebuilds the local/pi instance using that
+     * function as `getModel` (overriding the head-of-array placeholder
+     * baked into `createBackend`). Returning `undefined` means "no
+     * resolver registered for this name" — the placeholder stays in place.
+     *
+     * This indirection keeps the factory ignorant of `LocalModelResolver`'s
+     * existence and lifecycle while still letting it produce backends that
+     * route through the resolver Map.
+     */
+    getResolverModelFor?: (backendName: string) => (() => string | null) | undefined;
+}
+/**
+ * High-level factory wrapping `BackendRouter` + `createBackend` plus
+ * orchestrator-side concerns (sandbox wrapping, resolver binding).
+ *
+ * Spec 2 SC22-SC25: every `forUseCase(useCase)` call returns a fresh
+ * `AgentBackend` whose class matches the routed `BackendDef.type`.
+ * `local`/`pi` defs are bound to their per-name resolver before being
+ * returned, and the result is wrapped in `ContainerBackend` when
+ * sandboxPolicy is 'docker'.
+ */
+declare class OrchestratorBackendFactory {
+    private readonly router;
+    private readonly opts;
+    constructor(opts: OrchestratorBackendFactoryOptions);
+    /**
+     * Resolve `useCase` to a backend name, materialize a fresh
+     * `AgentBackend`, optionally rebind its model resolver, and apply
+     * sandbox wrapping. Idempotent across calls (no caching) — the AgentRunner
+     * holds the per-dispatch reference and discards it when the run ends.
+     */
+    /**
+     * Resolve `useCase` to its routed backend name, exposing the
+     * router lookup without materializing a backend. Used by callers
+     * (e.g., the orchestrator's dispatch site) that need to label
+     * telemetry with the routed name BEFORE constructing the backend.
+     *
+     * Spec 2 P2-I2: previously the orchestrator labelled `LiveSession`
+     * + `StreamRecorder` with the legacy `agent.backend` field, which
+     * is `undefined` for pure-modern configs. Threading the routed name
+     * through dispatch eliminates that gap.
+     */
+    resolveName(useCase: RoutingUseCase): string;
+    forUseCase(useCase: RoutingUseCase): AgentBackend;
+    /**
+     * Rebuild a `local`/`pi` backend with a resolver-bound `getModel`,
+     * mirroring `createBackend`'s local/pi branches but substituting the
+     * head-of-array placeholder with the orchestrator-owned resolver.
+     */
+    private buildLocalLikeWithResolver;
+    /**
+     * Apply ContainerBackend wrapping (PFC-3). Pulls the runtime + secret
+     * backend per call so each dispatch sees a fresh container handle map
+     * (ContainerBackend keeps its own per-instance Map<sessionId, handle>).
+     */
+    private wrapInContainer;
+}
+
+/**
+ * Result of running `migrateAgentConfig`.
+ *
+ * `config` is the *effective* AgentConfig — either the input unchanged
+ * (when `agent.backends` is already set or no migration is needed) or
+ * the input augmented with synthesized `backends` and `routing` fields.
+ *
+ * `warnings` is a list of human-readable deprecation messages, one per
+ * legacy field encountered. Each message names the deprecated field
+ * (dotted path) and includes a pointer to the migration guide. The
+ * orchestrator emits these as `warn`-level log entries at startup.
+ */
+interface MigrationResult {
+    config: AgentConfig;
+    warnings: string[];
+}
+/**
+ * Translate legacy `agent.backend` / `agent.localBackend` /
+ * `agent.escalation.autoExecute` into the new `agent.backends` +
+ * `agent.routing` shape (Spec 2 D3, D4, D8, D11).
+ *
+ * Behavior matrix:
+ * - `agent.backends` already set, no legacy fields:
+ *     no-op; returns input config unchanged, warnings = [].
+ * - `agent.backends` already set + at least one legacy field:
+ *     no-op on config; warnings name each ignored legacy field (D4).
+ * - No `agent.backends`, at least one of `agent.backend` /
+ *   `agent.localBackend` / `agent.localEndpoint` / etc. set:
+ *     synthesize `backends.primary` (always, from `agent.backend`)
+ *     and `backends.local` (when `localBackend` is set), plus a
+ *     `routing` map driven by `escalation.autoExecute` (D3).
+ * - No `agent.backends`, no legacy fields:
+ *     no-op; the caller's downstream Zod validation surfaces the gap
+ *     as a missing-required-field error.
+ *
+ * Throws on internal inconsistencies (e.g., `agent.backend = 'pi'`
+ * with no `localEndpoint`/`localModel`) — these are user-config bugs
+ * that would have produced a runtime crash today.
+ */
+declare function migrateAgentConfig(agent: AgentConfig): MigrationResult;
+
+/**
+ * Pure constructor: BackendDef -> concrete AgentBackend instance.
+ * No side effects beyond the underlying class constructors.
+ * Container wrapping (sandbox policy) is the orchestrator's job, not the factory's.
+ */
+declare function createBackend(def: BackendDef): AgentBackend;
+
+export { type AgentUpdateEvent, AnalysisArchive, type AnalysisRecord, type ApplyEventResult, type ArtifactPresence, type AttemptStats, BackendRouter, type BackendRouterOptions, ClaimManager, type ClaimManagerConfig, type CleanWorkspaceEffect, type DispatchEffect, type EmitLogEffect, type EscalateEffect, type ExecFileFn, type Highlight, type HighlightsInfo, InteractionQueue, type LinearGraphQLExtension, LinearGraphQLStub, type LiveSession, type MigrationResult, MockBackend, ORCHESTRATOR_IDENTITY_FILE, Orchestrator, OrchestratorBackendFactory, type OrchestratorBackendFactoryOptions, type OrchestratorContext, type OrchestratorEvent, type OrchestratorState, PRDetector, type PRDetectorLogger, type PendingInteraction, PromptRenderer, type PublishedIndex, type RateLimitSnapshot as RateLimitComputeSnapshot, type RateLimitConfig, type RateLimitSnapshot$1 as RateLimitSnapshot, type ReleaseClaimEffect, type RetryEntry, type RetryFiredEvent, RoadmapTrackerAdapter, type RunAttemptPhase, type RunningEntry, type ScheduleRetryEffect, type SideEffect, type StallDetectedEvent, type StopEffect, type StreamManifest, StreamRecorder, type TickEvent, type TokenTotals, type TriageConfig, type TriageDecision, type TriageSignals, type TriageSkill, type UpdateTokensEffect, type WorkerExitEvent, WorkflowLoader, WorkspaceHooks, WorkspaceManager, applyEvent, artifactPresenceFromIssue, calculateRetryDelay, canDispatch, computeRateLimitDelay, createBackend, createEmptyState, detectScopeTier, extractHighlights, extractTitlePrefix, getAvailableSlots, getDefaultConfig, getPerStateCount, isEligible, launchTUI, loadPublishedIndex, migrateAgentConfig, reconcile, renderAnalysisComment, renderPRComment, resolveEscalationConfig, resolveOrchestratorId, routeIssue, savePublishedIndex, selectCandidates, sortCandidates, triageIssue, validateWorkflowConfig };