@harness-engineering/orchestrator 0.11.2 → 0.13.0

package/dist/index.d.ts

@@ -1,11 +1,12 @@
 import * as _harness_engineering_types from '@harness-engineering/types';
-import { Issue, AgentEvent, WorkflowConfig, TokenUsage, ConcernSignal, ScopeTier, EscalationConfig, IssueRoutingDecision, Result, WorkflowDefinition, BackendDef, RoutingConfig, WorkspaceConfig, HooksConfig, AgentBackend, SessionStartParams, AgentSession, AgentError, TurnParams, TurnResult, CheckScriptDefinition, OutputRetentionConfig, RoutingDecision, RoutingUseCase, ContainerConfig, SecretConfig, AgentConfig, LocalModelStatus, CustomTaskDefinition, MaintenanceConfig, TokenScope, AuthToken, AuthTokenPublic, IndexedFileKind, SessionSearchResult, ReindexStats, SessionSummarizationConfig, SessionSummary, SessionSummaryMeta, SessionsConfig, GatewayEvent, NotificationEnvelope, NotificationDeliveryResult, NotificationSinkConfig, NotificationsConfig } from '@harness-engineering/types';
-import { IssueTrackerClient, Issue as Issue$1, TrackerConfig, eventSourcing, CacheMetricsRecorder, ArchiveHooks, SkillProposal, ProposalGateFinding, SkillKind } from '@harness-engineering/core';
+import { Issue, WorkflowExecutionPlan, StageRun, AgentEvent, WorkflowConfig, TokenUsage, ConcernSignal, ScopeTier, EscalationConfig, IssueRoutingDecision, Result, WorkflowDefinition, BackendDef, RoutingConfig, RoutingDecision, RoutingUseCase, ContainerConfig, SecretConfig, AgentBackend, RoutingRequest, CapabilityTier, WorkspaceConfig, HooksConfig, SessionStartParams, AgentSession, AgentError, TurnParams, TurnResult, CheckScriptDefinition, OutputRetentionConfig, BackendCapabilityRegistry, RoutingPolicy, ComplexityVerdict, RoutingTelemetry, RoutingStatus, RoutingError, PrivacyClass, BackendCapabilities, AgentConfig, LocalModelStatus, CustomTaskDefinition, MaintenanceConfig, TokenScope, AuthToken, AuthTokenPublic, IndexedFileKind, SessionSearchResult, ReindexStats, SessionSummarizationConfig, SessionSummary, SessionSummaryMeta, SessionsConfig, GatewayEvent, NotificationEnvelope, NotificationDeliveryResult, NotificationSinkConfig, NotificationsConfig } from '@harness-engineering/types';
+import { IssueTrackerClient, Issue as Issue$1, CacheMetricsRecorder, TrackerConfig, eventSourcing, ArchiveHooks, SkillProposal, ProposalGateFinding, SkillKind } from '@harness-engineering/core';
 import { EnrichedSpec, ComplexityScore, SimulationResult, IntelligencePipeline, WeightedRecommendation, AnalysisProvider } from '@harness-engineering/intelligence';
 import { GraphStore } from '@harness-engineering/graph';
 import { execFile } from 'node:child_process';
 import { EventEmitter } from 'node:events';
-import { PoolStateProvider, SchedulerTimerHandle } from '@harness-engineering/local-models';
+import { PoolStateProvider, SchedulerTimerHandle, DiscoverCandidatesOptions, DiscoverCandidatesResult } from '@harness-engineering/local-models';
+export { discoverCandidates } from '@harness-engineering/local-models';
 import { z } from 'zod';
 
 /**
@@ -44,6 +45,22 @@ interface RunningEntry {
     startedAt: string;
     phase: RunAttemptPhase;
     session: LiveSession | null;
+    /**
+     * AMR Phase 4 (D10/SC16): the tier the AdaptiveRouter resolved this dispatch
+     * at (`decision.tierRequired`), captured so a later quality outcome can feed
+     * `AdaptiveRouter.recordOutcome(issue.id, lastRoutedTier, ok)`. Absent when
+     * AMR is off (no policy) or the dispatch used an override.
+     */
+    lastRoutedTier?: _harness_engineering_types.CapabilityTier;
+    /** split-routing: the plan this unit is running staged, if any. Engine-owned. */
+    workflow?: WorkflowExecutionPlan;
+    /** split-routing: the stage index currently executing. Engine-owned. */
+    currentStageIndex?: number;
+    /**
+     * split-routing: per-stage runs. The per-stage session/abort live HERE
+     * (C1), never in the issue-level `session` field above.
+     */
+    stageRuns?: StageRun[];
 }
 /**
  * Entry in the retry queue.
@@ -1000,107 +1017,545 @@ declare function discoverSkillCatalog(projectRoot: string): SkillCatalogEntry[];
 declare function discoverSkillCatalogNames(projectRoot: string): string[];
 
 /**
- * Adapter for using a markdown roadmap file as an issue tracker.
+ * split-routing D5/D12/D13 — the result of the doubly-opt-in match.
  *
- * This adapter parses a standard Harness roadmap file, extracts features,
- * and maps them to the internal Issue model using deterministic hashing
- * for identifiers.
+ * `workflowFor` is the SINGLE matching authority: it returns BOTH the execution
+ * `plan` AND the matched decl's optional `stageDeadlineMs` (D12) so `dispatchIssue`
+ * never re-runs the prefix+labels+`>= 2` predicate to recover the deadline. One
+ * match, one source of truth — no drift between the predicate and a second matcher.
  */
-declare class RoadmapTrackerAdapter implements IssueTrackerClient {
-    private config;
+interface WorkflowMatch {
+    /** The execution plan for the matched >= 2-stage decl. */
+    plan: WorkflowExecutionPlan;
+    /** The matched decl's per-stage deadline override (D12), if declared. */
+    stageDeadlineMs?: number;
+}
+/**
+ * split-routing D5/D13 — the doubly-opt-in gate as a PURE matcher.
+ *
+ * Selects a `WorkflowMatch` for `issue` iff `config.workflows` declares a
+ * matching decl with `stages.length >= 2`. Match grain (v1): an
+ * `identifierPrefix` and/or `labels`; both, when declared, must hold. The FIRST
+ * matching decl wins. The returned `WorkflowMatch` carries the matched decl's
+ * `stageDeadlineMs` (D12) so the caller reads it from HERE rather than
+ * re-matching — this function is the single match authority.
+ *
+ * D13: a matching 1-stage decl returns `undefined` — the unit takes the
+ * single-agent path (a 1-stage "workflow" is not staged). A 0-stage decl never
+ * reaches here (rejected at config validation).
+ *
+ * SC4 — this matcher has ZERO side effects: it never touches the workspace,
+ * claims, routes, logs, or mutates state. When it returns `undefined`
+ * `dispatchIssue` falls through to the byte-identical single-agent path. Keep it
+ * cheap and pure so calling it on every dispatch cannot change non-workflow
+ * behavior.
+ */
+declare function workflowFor(issue: Issue, config: WorkflowConfig): WorkflowMatch | undefined;
+
+interface RoutingDecisionBusFilter {
+    skillName?: string;
+    mode?: string;
+    backendName?: string;
+    limit?: number;
+}
+interface RoutingDecisionBusOptions {
+    /** Default 500. Bound on the in-memory ring buffer. */
+    capacity?: number;
     /**
-     * Creates a new RoadmapTrackerAdapter.
-     *
-     * @param config - The tracker configuration including the file path
+     * Logger for the structured `routing-decision` line (O1) and for
+     * one-off warn() when a subscriber throws (S6). When omitted, the
+     * bus silently swallows subscriber errors (test-mode default).
      */
-    constructor(config: TrackerConfig);
+    logger?: StructuredLogger;
+}
+/**
+ * Spec B Phase 4 (D8): in-process bus + ring buffer for
+ * {@link RoutingDecision} events. One emit() per
+ * {@link BackendRouter.resolve} call; subscribers receive the
+ * decision synchronously after the ring buffer is updated.
+ *
+ * Subscriber errors are isolated (caught + logged, never thrown
+ * back to the emitter) so a misbehaving subscriber cannot block a
+ * dispatch. (S6)
+ *
+ * Capacity-bound (default 500) via Array.shift() — acceptable for
+ * v1 (see plan C4); switch to circular indexing if 24h dispatch
+ * volume ever pushes 10K+ records/min.
+ */
+declare class RoutingDecisionBus {
+    private readonly ringBuffer;
+    private readonly listeners;
+    private readonly capacity;
+    private readonly logger;
+    constructor(opts?: RoutingDecisionBusOptions);
+    emit(decision: RoutingDecision): void;
+    recent(filter?: RoutingDecisionBusFilter): RoutingDecision[];
+    subscribe(listener: (d: RoutingDecision) => void): () => void;
     /**
-     * Fetches all issues that are in an "active" state according to the config.
+     * Spec B Phase 5 (review-S2 fix): release all subscriber references so
+     * teardown can complete without anchoring closures. Called from
+     * `Orchestrator.stop()` before nulling the bus reference. The bus
+     * remains usable after clear — `subscribe()` works as normal.
      */
-    fetchCandidateIssues(): Promise<Result<Issue$1[], Error>>;
+    clearListeners(): void;
+}
+
+interface BackendRouterOptions {
+    backends: Record<string, BackendDef>;
+    routing: RoutingConfig;
     /**
-     * Fetches issues that match any of the given state names.
-     *
-     * @param stateNames - List of statuses to filter by
+     * Spec B Phase 4 (D8): when present, every resolve() emits its
+     * decision onto the bus. The bus owns the structured log line + ring
+     * buffer; the router stays a pure resolution function.
      */
-    fetchIssuesByStates(stateNames: string[]): Promise<Result<Issue$1[], Error>>;
+    decisionBus?: RoutingDecisionBus;
+}
+/**
+ * BackendRouter (Spec B Phase 1)
+ *
+ * Owns the lookup from a {@link RoutingUseCase} (a discriminated query
+ * — tier, intelligence layer, maintenance, chat, isolation, **skill**,
+ * **mode**) to a {@link RoutingDecision} naming a chosen backend and
+ * the full resolution path that produced it.
+ *
+ * Resolution order (D2): invocation override -> per-skill -> per-mode
+ * -> existing per-tier/intelligence/isolation/maintenance/chat ->
+ * `routing.default`. Within each source, fallback chain entries are
+ * tried in declared order; first existing backend wins. Unknown
+ * entries are recorded with `outcome: 'unknown-backend'` and the walk
+ * continues.
+ *
+ * Construction-time validation guarantees every name referenced by
+ * `routing` is present in `backends` so the static-config case can
+ * never produce a runtime exhaustion throw. The runtime throw at the
+ * end of `resolve()` is a safety net for future dynamic-backends
+ * scenarios where a chain entry can become unknown post-construction.
+ */
+declare class BackendRouter {
+    private readonly backends;
+    private readonly routing;
+    private readonly decisionBus;
+    constructor(opts: BackendRouterOptions);
     /**
-     * Transitions a roadmap feature into the first configured terminal state
-     * and rewrites the markdown file. Idempotent: if the feature is already
-     * in a terminal state, this is a no-op.
+     * Resolve a {@link RoutingUseCase} to a {@link RoutingDecision}.
      *
-     * The orchestrator calls this after a successful agent exit so the feature
-     * is no longer returned by `fetchCandidateIssues` on the next tick — and,
-     * critically, after an orchestrator restart.
+     * @param useCase the routing query
+     * @param opts.invocationOverride if set and the named backend exists,
+     *   beats all other sources (D7 — the `--backend <name>` escape hatch)
      */
-    markIssueComplete(issueId: string): Promise<Result<void, Error>>;
+    resolve(useCase: RoutingUseCase, opts?: {
+        invocationOverride?: string;
+    }): RoutingDecision;
     /**
-     * Claims an issue by transitioning its status to "in-progress" and
-     * writing the orchestratorId into the assignee field. Idempotent if
-     * already claimed by the same orchestratorId.
+     * Returns the {@link BackendDef} reference for the resolved name.
+     * Identity-equal to the entry in `backends` (no copy) so callers
+     * relying on reference equality (SC21) continue to work.
      */
-    claimIssue(issueId: string, orchestratorId: string): Promise<Result<void, Error>>;
+    resolveDefinition(useCase: RoutingUseCase, opts?: {
+        invocationOverride?: string;
+    }): BackendDef;
     /**
-     * Releases a claimed issue by transitioning back to the first active
-     * state and clearing the assignee field.
+     * Spec B Phase 4 (closes P1-IMP-2): a single resolve() + def lookup
+     * for callers that need both. Replaces the previous pattern of
+     * `resolveDefinition(useCase) + resolve(useCase)` which produced two
+     * RoutingDecision emissions per dispatch — doubling routing-decision
+     * log volume now that Phase 4 emits.
+     *
+     * Identity-equal `BackendDef` (no copy) so callers relying on
+     * reference equality (SC21) continue to work.
      */
-    releaseIssue(issueId: string): Promise<Result<void, Error>>;
+    resolveDecisionAndDef(useCase: RoutingUseCase, opts?: {
+        invocationOverride?: string;
+    }): {
+        decision: RoutingDecision;
+        def: BackendDef;
+    };
     /**
-     * Resolve the roadmap store anchored on the configured aggregate file path.
-     * The shard backend is chosen when a sibling `roadmap.d/` exists next to the
-     * file; otherwise the monolith file is read/written whole. Callers guard
-     * `this.config.filePath` before invoking.
+     * The pre-Spec-B resolution helper: returns the configured
+     * {@link RoutingValue} for tier/intelligence/isolation/maintenance/chat
+     * use cases (or `undefined` for skill/mode use cases, which are owned
+     * by the per-skill / per-mode steps in {@link resolve}). Returning
+     * `undefined` lets the caller fall through to `routing.default`.
      */
-    private resolveStore;
-    /** Load the roadmap via the store (sharded or monolith), returning a Result. */
-    private loadRoadmap;
-    private findFeatureById;
+    private resolveExistingUseCase;
+    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).
+ */
+/**
+ * Runtime-feedback callbacks a `local`/`pi` backend fires as turns complete.
+ * See {@link OrchestratorBackendFactoryOptions.getModelUsageHooksFor}.
+ */
+interface LocalModelUsageHooks {
+    /** Fired with the resolved model after a successful turn (LRU + breaker clear). */
+    onModelUsed?: (model: string) => void;
+    /** Fired with the resolved model after a failed turn (breaker increment). */
+    onModelFailed?: (model: string) => void;
+}
+interface OrchestratorBackendFactoryOptions {
+    backends: Record<string, BackendDef>;
+    routing: RoutingConfig;
+    sandboxPolicy: 'none' | 'docker';
+    container?: ContainerConfig;
+    secrets?: SecretConfig;
     /**
-     * Fetches full issue details for a list of identifiers.
+     * 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.
      *
-     * @param issueIds - List of issue IDs to fetch
+     * This indirection keeps the factory ignorant of `LocalModelResolver`'s
+     * existence and lifecycle while still letting it produce backends that
+     * route through the resolver Map.
      */
-    fetchIssueStatesByIds(issueIds: string[]): Promise<Result<Map<string, Issue$1>, Error>>;
+    getResolverModelFor?: (backendName: string, useCase: RoutingUseCase) => (() => string | null) | undefined;
     /**
-     * Maps a raw RoadmapFeature from the parser to the unified Issue model.
+     * Consumption Phase 3 (T11): per-`local`/`pi` backend hook returning the
+     * runtime-feedback callbacks bound to that backend's resolver + pool. The
+     * factory forwards them to the constructed `LocalBackend` so a completed turn
+     * stamps `lastUsedAt` (LRU) + clears the circuit breaker, and a failed turn
+     * feeds the breaker. Returning `undefined` means "no feedback wiring" (the
+     * backend runs exactly as before). Kept parallel to `getResolverModelFor` so
+     * the factory stays ignorant of resolver/pool lifecycles.
      */
-    private mapFeatureToIssue;
+    getModelUsageHooksFor?: (backendName: string) => LocalModelUsageHooks | undefined;
     /**
-     * Generates a deterministic, URL-safe identifier for a feature name.
+     * Phase 5: prompt-cache recorder forwarded to Anthropic-capable backends.
+     * Other backends accept-but-ignore. Shared across dispatches so the
+     * `/api/v1/telemetry/cache/stats` endpoint sees the full rolling window.
      */
-    private generateId;
+    cacheMetrics?: CacheMetricsRecorder;
+    /**
+     * Spec B Phase 4 (D8): forwarded to the underlying BackendRouter so
+     * every resolve() during forUseCase / resolveName emits.
+     */
+    decisionBus?: RoutingDecisionBus;
 }
-
 /**
- * Interface for a Linear GraphQL tool extension — a thin authenticated client
- * over Linear's GraphQL API (https://linear.app/developers/graphql).
+ * 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'.
  */
-interface LinearGraphQLExtension {
+declare class OrchestratorBackendFactory {
+    private readonly router;
+    private readonly opts;
+    constructor(opts: OrchestratorBackendFactoryOptions);
     /**
-     * Execute a GraphQL operation. Resolves to `Ok(data)` (the `data` object of
-     * the GraphQL envelope) on success, or `Err` on a transport failure, a non-2xx
-     * HTTP status, or a GraphQL `errors` array.
+     * 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.
      */
-    query(query: string, variables?: Record<string, unknown>): Promise<Result<unknown, Error>>;
-}
-interface LinearGraphQLClientOptions {
     /**
-     * Linear authentication token. A personal API key is sent verbatim in the
-     * `Authorization` header; an OAuth access token must be passed already prefixed
-     * with `Bearer ` (Linear's two supported schemes).
+     * 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.
      */
-    apiKey: string;
-    /** Override the GraphQL endpoint (e.g. a proxy). Defaults to Linear's API. */
-    endpoint?: string;
-    /** Injectable fetch for tests; defaults to the global `fetch`. */
-    fetchFn?: typeof fetch;
-}
-/**
- * Real Linear GraphQL client. Replaces {@link LinearGraphQLStub}, which only
- * logged the query and returned an empty object. POSTs the operation to Linear's
- * GraphQL endpoint with the API key, and normalizes the three failure modes
- * (transport throw, non-2xx HTTP, GraphQL `errors`) into a single `Err`.
- */
+    resolveName(useCase: RoutingUseCase, opts?: {
+        invocationOverride?: string;
+    }): string;
+    /**
+     * Spec B Phase 1: expose the underlying router for callers that need
+     * it directly (e.g., {@link buildIntelligencePipeline} for the
+     * I1 SEL/PESL comparison fix). Read-only access; consumers must not
+     * mutate router state.
+     */
+    getRouter(): BackendRouter;
+    forUseCase(useCase: RoutingUseCase, opts?: {
+        invocationOverride?: string;
+    }): 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;
+}
+
+/**
+ * Narrow surface the stage-execution engine needs. The Orchestrator will
+ * implement this in Phase 4 when dispatchIssue wires the branch; the engine
+ * must NOT import orchestrator.ts (layer cycle). Phase 1 tests inject a fake.
+ */
+interface WorkflowEngineContext {
+    recorder: StreamRecorder;
+    logger: StructuredLogger;
+    /** issueId of the coherence unit — used for recorder keys + terminal transitions. */
+    issueId: string;
+    identifier: string;
+    externalId: string | null;
+    workspacePath: string;
+    /**
+     * D12 (SC7): per-stage wall-clock deadline in ms. If a stage does not finish
+     * within it, the engine fires the per-stage abort (running the runner's
+     * `finally { stopSession }` via `gen.return()`) and treats the stage as
+     * `passed:false` → feeds the D8 retry/terminal path (never an unbounded hang).
+     * Absent ⇒ the engine default (`DEFAULT_STAGE_DEADLINE_MS`). Per-stage/config
+     * override is Phase 4.
+     */
+    stageDeadlineMs?: number;
+    /** Build a runner for a stage's routed backend. Phase 1: single stubbed backend. */
+    makeRunner(backend: AgentBackend): {
+        runSession: (issue: unknown, ws: string, prompt: string) => AsyncGenerator<AgentEvent, {
+            sessionId: string;
+            success: boolean;
+            usage: {
+                inputTokens: number;
+                outputTokens: number;
+                totalTokens: number;
+            };
+        }, void>;
+    };
+    /** Phase 1 stub: resolve the single backend for a stage (Phase 2 replaces with route()). */
+    resolveStageBackend(step: WorkflowExecutionPlan['stages'][number]): AgentBackend;
+    /**
+     * split-routing 4b: render the REAL per-stage prompt (issue + stage role +
+     * prior-stage outputs), replacing the Phase-1 bare skill-name stub. Bound by
+     * `buildWorkflowContext` via a `PromptRenderer` (never imports orchestrator).
+     * `priorOutputs` maps each prior stage's `produces` label → its captured output.
+     * Optional so fake contexts that don't exercise prompt content fall back to the
+     * skill name (byte-identical to the old stub).
+     *
+     * CONTRACT: must be non-blocking (CPU-bound). It runs BEFORE the per-stage
+     * deadline timer is armed, so an I/O-bound renderer that hangs would stall the
+     * stage with no wall-clock bound. The shipped renderer is synchronous LiquidJS.
+     */
+    renderStagePrompt?(step: WorkflowExecutionPlan['stages'][number], index: number, priorOutputs: Record<string, string>): string | Promise<string>;
+    /**
+     * split-routing Phase 2: per-stage adaptive router. Present ⇒ each stage is
+     * routed via `route(buildStageRequest(...))`; ABSENT ⇒ identity fallback via
+     * `resolveStageBackend` (no `routing.policy`). Narrow surface only (route +
+     * recordOutcome) so the engine stays off the orchestrator import cycle.
+     *
+     * `route()` returns `{ decision }` only — the engine derives the backend name
+     * from `decision.backendName` (a `BackendDef` carries no `name`; the name is
+     * the router map key), so `def` is deliberately not part of this surface.
+     */
+    adaptiveRouter?: {
+        route(req: RoutingRequest): Promise<{
+            decision: RoutingDecision;
+        }>;
+        recordOutcome(coherenceUnit: string, tier: CapabilityTier, ok: boolean): void;
+    };
+    /** Terminal success — exactly one running/claimed delete + one lane persist (D6). */
+    emitWorkflowSuccess(unit: string, runs: StageRun[]): Promise<void>;
+    /** Terminal failure/safety-net — exactly one running/claimed delete + one lane persist (D6/I1). */
+    finalizeWorkflowTerminal(unit: string, runs: StageRun[], failingStep?: WorkflowExecutionPlan['stages'][number], err?: unknown): Promise<void>;
+}
+
+/**
+ * split-routing Phase 4 — the narrow adaptive-router surface the workflow engine
+ * consumes (`route` + `recordOutcome`). Structurally identical to
+ * `WorkflowEngineContext.adaptiveRouter` and to the real `AdaptiveRouter`'s public
+ * methods; typed here so the dep bag never depends on the concrete router class
+ * (and never on `orchestrator.ts`).
+ */
+interface WorkflowRouterDep {
+    route(req: RoutingRequest): Promise<{
+        decision: RoutingDecision;
+    }>;
+    recordOutcome(coherenceUnit: string, tier: CapabilityTier, ok: boolean): void;
+}
+/**
+ * The dependency bag `buildWorkflowContext` composes the real
+ * `WorkflowEngineContext` from. It is passed IN by `dispatchIssue` (Task 8) rather
+ * than read off `this`, so this module imports only same-layer siblings
+ * (`agent/runner`, `agent/orchestrator-backend-factory` types, `core/stream-recorder`)
+ * and NEVER `orchestrator.ts` — the layer-cycle guard the context surface exists
+ * for (concern #3). The two terminal seams are supplied as `settleSuccess` /
+ * `settleTerminal` callbacks the orchestrator binds to its private methods (Task 7).
+ */
+interface BuildWorkflowContextDeps {
+    recorder: StreamRecorder;
+    logger: StructuredLogger;
+    /** The dispatch unit; issueId/identifier/externalId flow from here. */
+    issue: Issue;
+    /** The unit's ONE worktree (from the single `ensureWorkspace` in dispatchIssue). */
+    workspacePath: string;
+    /** `this.config.agent.maxTurns` — the per-stage runner turn cap. */
+    maxTurns: number;
+    /**
+     * The orchestrator's backend factory. Used to materialize the real routed
+     * backend for a stage: `forUseCase(useCase, { invocationOverride: name })`
+     * mirrors the AMR dispatch swap (orchestrator.ts:2062-2064). `null` when
+     * migration failed (legacy-only config) — then the identity fallback uses the
+     * name-only `routingDefault` backend.
+     */
+    backendFactory: OrchestratorBackendFactory | null;
+    /**
+     * The real `AdaptiveRouter` (narrowed) when `routing.policy` is set
+     * (orchestrator.ts:698), else `null` ⇒ the engine takes the identity fallback
+     * (D5). Only `route`/`recordOutcome` are consumed.
+     */
+    adaptiveRouter: WorkflowRouterDep | null;
+    /** `this.config.agent.routing?.default` — the identity-fallback backend name. */
+    routingDefault: string | undefined;
+    /** D12 override; absent ⇒ engine default DEFAULT_STAGE_DEADLINE_MS. */
+    stageDeadlineMs?: number;
+    /** Terminal-success seam (Task 6/7): bound to `settleWorkflowSuccess`. */
+    settleSuccess: (unit: string, runs: StageRun[]) => Promise<void>;
+    /** Terminal-failure/safety-net seam (Task 6/7): bound to `settleWorkflowTerminal`. */
+    settleTerminal: (unit: string, runs: StageRun[], failingStep?: WorkflowExecutionPlan['stages'][number], err?: unknown) => Promise<void>;
+}
+/**
+ * split-routing Phase 4 — compose the REAL `WorkflowEngineContext` (minus the two
+ * terminal seams, which Task 6 completes) from orchestrator machinery.
+ *
+ * Seam → real code:
+ *  - `recorder`/`logger`/`issueId`/`identifier`/`externalId`/`workspacePath` → the deps.
+ *  - `stageDeadlineMs` → `deps.stageDeadlineMs` (conditional; engine defaults when absent).
+ *  - `makeRunner(backend)` → `new AgentRunner(realBackend, { maxTurns })`. The engine
+ *    passes a name-only backend for the routed path (execute-workflow.ts:320); we
+ *    re-materialize the real backend from that name via
+ *    `backendFactory.forUseCase(useCase, { invocationOverride: backend.name })`
+ *    (same swap as orchestrator.ts:2062-2064). Its `runSession` returns a
+ *    `TurnResult` (runner.ts:112) — the seam is already typed against it
+ *    (carry-forward #9), confirmed self-documenting by the explicit annotation below.
+ *  - `resolveStageBackend(step)` → identity fallback: `backendFactory.forUseCase(useCase)`
+ *    when the factory exists, else a name-only backend from `routingDefault`.
+ *  - `adaptiveRouter` → present iff `deps.adaptiveRouter !== null` (D5).
+ *
+ * The two TERMINAL seams (`emitWorkflowSuccess` / `finalizeWorkflowTerminal`,
+ * SC5) are thin forwarders to the orchestrator's `settleSuccess` / `settleTerminal`
+ * callbacks. They are NOT routed through `emitWorkerExit`/`handleWorkerExit`
+ * (which fire the ISSUE-keyed `finishRecording(attempt)` + `recordAmrOutcome` — a
+ * DOUBLE-fire, since the engine already ran PER-STAGE recorders + per-stage
+ * `recordOutcome`). The reducer-reproduction (running.delete → completed.set →
+ * claimed.delete → cleanWorkspace → persist → emit for success; and the
+ * finalizeRoutingTerminal + needs-human + cleanWorkspace sequence for terminal)
+ * lives in the orchestrator's private methods (Task 7) the callbacks bind to.
+ */
+declare function buildWorkflowContext(deps: BuildWorkflowContextDeps): WorkflowEngineContext;
+
+/**
+ * Adapter for using a markdown roadmap file as an issue tracker.
+ *
+ * This adapter parses a standard Harness roadmap file, extracts features,
+ * and maps them to the internal Issue model using deterministic hashing
+ * for identifiers.
+ */
+declare class RoadmapTrackerAdapter implements IssueTrackerClient {
+    private config;
+    /**
+     * Creates a new RoadmapTrackerAdapter.
+     *
+     * @param config - The tracker configuration including the file path
+     */
+    constructor(config: TrackerConfig);
+    /**
+     * Fetches all issues that are in an "active" state according to the config.
+     */
+    fetchCandidateIssues(): Promise<Result<Issue$1[], Error>>;
+    /**
+     * Fetches issues that match any of the given state names.
+     *
+     * @param stateNames - List of statuses to filter by
+     */
+    fetchIssuesByStates(stateNames: string[]): Promise<Result<Issue$1[], Error>>;
+    /**
+     * Transitions a roadmap feature into the first configured terminal state
+     * and rewrites the markdown file. Idempotent: if the feature is already
+     * in a terminal state, this is a no-op.
+     *
+     * The orchestrator calls this after a successful agent exit so the feature
+     * is no longer returned by `fetchCandidateIssues` on the next tick — and,
+     * critically, after an orchestrator restart.
+     */
+    markIssueComplete(issueId: string): Promise<Result<void, Error>>;
+    /**
+     * Claims an issue by transitioning its status to "in-progress" and
+     * writing the orchestratorId into the assignee field. Idempotent if
+     * already claimed by the same orchestratorId.
+     */
+    claimIssue(issueId: string, orchestratorId: string): Promise<Result<void, Error>>;
+    /**
+     * Releases a claimed issue by transitioning back to the first active
+     * state and clearing the assignee field.
+     */
+    releaseIssue(issueId: string): Promise<Result<void, Error>>;
+    /**
+     * Resolve the roadmap store anchored on the configured aggregate file path.
+     * The shard backend is chosen when a sibling `roadmap.d/` exists next to the
+     * file; otherwise the monolith file is read/written whole. Callers guard
+     * `this.config.filePath` before invoking.
+     */
+    private resolveStore;
+    /** Load the roadmap via the store (sharded or monolith), returning a Result. */
+    private loadRoadmap;
+    private findFeatureById;
+    /**
+     * Fetches full issue details for a list of identifiers.
+     *
+     * @param issueIds - List of issue IDs to fetch
+     */
+    fetchIssueStatesByIds(issueIds: string[]): Promise<Result<Map<string, Issue$1>, Error>>;
+    /**
+     * Maps a raw RoadmapFeature from the parser to the unified Issue model.
+     */
+    private mapFeatureToIssue;
+    /**
+     * Generates a deterministic, URL-safe identifier for a feature name.
+     */
+    private generateId;
+}
+
+/**
+ * Interface for a Linear GraphQL tool extension — a thin authenticated client
+ * over Linear's GraphQL API (https://linear.app/developers/graphql).
+ */
+interface LinearGraphQLExtension {
+    /**
+     * Execute a GraphQL operation. Resolves to `Ok(data)` (the `data` object of
+     * the GraphQL envelope) on success, or `Err` on a transport failure, a non-2xx
+     * HTTP status, or a GraphQL `errors` array.
+     */
+    query(query: string, variables?: Record<string, unknown>): Promise<Result<unknown, Error>>;
+}
+interface LinearGraphQLClientOptions {
+    /**
+     * Linear authentication token. A personal API key is sent verbatim in the
+     * `Authorization` header; an OAuth access token must be passed already prefixed
+     * with `Bearer ` (Linear's two supported schemes).
+     */
+    apiKey: string;
+    /** Override the GraphQL endpoint (e.g. a proxy). Defaults to Linear's API. */
+    endpoint?: string;
+    /** Injectable fetch for tests; defaults to the global `fetch`. */
+    fetchFn?: typeof fetch;
+}
+/**
+ * Real Linear GraphQL client. Replaces {@link LinearGraphQLStub}, which only
+ * logged the query and returned an empty object. POSTs the operation to Linear's
+ * GraphQL endpoint with the API key, and normalizes the three failure modes
+ * (transport throw, non-2xx HTTP, GraphQL `errors`) into a single `Err`.
+ */
 declare class LinearGraphQLClient implements LinearGraphQLExtension {
     private readonly apiKey;
     private readonly endpoint;
@@ -1123,6 +1578,24 @@ declare class LinearGraphQLStub implements LinearGraphQLExtension {
     query(query: string, _variables?: Record<string, unknown>): Promise<Result<unknown, Error>>;
 }
 
+/**
+ * AMR 4c: a single-agent quality-verdict source (ADR 0069). The escalation
+ * mechanism + seam are complete; this supplies the *sound* signal that was
+ * missing — a BASELINE-RELATIVE scan of the diff the agent introduced. Only the
+ * ADDED lines are scanned, so a pre-existing pattern never counts against the
+ * agent. This is sound (not approximate) because every security rule is
+ * single-line, so per-added-line matching yields exactly the introduced findings.
+ */
+/** One hunk of added lines from a unified diff, with its true start line. */
+interface IntroducedHunk {
+    /** Repo-relative path of the changed file. */
+    file: string;
+    /** The added lines (leading `+` stripped), joined with `\n`. */
+    addedContent: string;
+    /** New-file line number the first added line sits at (for accurate findings). */
+    startLine: number;
+}
+
 /**
  * Structured event emitted when {@link WorkspaceManager.resolveBaseRef}
  * falls back past `origin/HEAD` and `origin/main`/`origin/master` to a
@@ -1162,6 +1635,27 @@ declare class WorkspaceManager {
      * Resolves the full path for an issue's workspace.
      */
     resolvePath(identifier: string): string;
+    /**
+     * AMR 4c: the lines the dispatched agent INTRODUCED in its worktree, as
+     * per-hunk added-line blocks — the sound input for a baseline-relative quality
+     * scan (pre-existing content is excluded by construction). Diffs the working
+     * tree (so both committed AND uncommitted agent work is captured) against the
+     * MERGE-BASE of the worktree HEAD and the base ref — merge-base, not the base
+     * ref itself, so a base branch that advanced mid-dispatch never attributes
+     * other merges to this agent. The seeded handoff overlay (`seedPaths`) is
+     * excluded — those files are not the agent's work.
+     */
+    getIntroducedDiff(identifier: string): Promise<IntroducedHunk[]>;
+    /**
+     * AMR 4c v2: the SAME introduced change as {@link getIntroducedDiff}, but as the
+     * RAW unified diff text (default context, NOT `--unified=0`) — the input an LLM
+     * spec-satisfaction eval needs to judge whether the diff satisfies the spec.
+     * Merge-base relative for the same reason (a base branch that advanced
+     * mid-dispatch never attributes other merges here), and the seeded handoff
+     * overlay is excluded via git `:(exclude)` pathspecs so the judge never reads
+     * pre-seeded proposal/roadmap content as the agent's work.
+     */
+    getIntroducedDiffText(identifier: string): Promise<string>;
     /**
      * Discovers the git repository root from the workspace root directory.
      */
@@ -1473,133 +1967,235 @@ interface MaintenanceStatus {
     history: RunResult[];
 }
 
-interface RoutingDecisionBusFilter {
-    skillName?: string;
-    mode?: string;
-    backendName?: string;
-    limit?: number;
-}
-interface RoutingDecisionBusOptions {
-    /** Default 500. Bound on the in-memory ring buffer. */
-    capacity?: number;
-    /**
-     * Logger for the structured `routing-decision` line (O1) and for
-     * one-off warn() when a subscriber throws (S6). When omitted, the
-     * bus silently swallows subscriber errors (test-mode default).
-     */
-    logger?: StructuredLogger;
-}
 /**
- * Spec B Phase 4 (D8): in-process bus + ring buffer for
- * {@link RoutingDecision} events. One emit() per
- * {@link BackendRouter.resolve} call; subscribers receive the
- * decision synchronously after the ring buffer is updated.
- *
- * Subscriber errors are isolated (caught + logged, never thrown
- * back to the emitter) so a misbehaving subscriber cannot block a
- * dispatch. (S6)
- *
- * Capacity-bound (default 500) via Array.shift() — acceptable for
- * v1 (see plan C4); switch to circular indexing if 24h dispatch
- * volume ever pushes 10K+ records/min.
+ * D10 vertical escalation. Per-`coherenceUnit` quality-failure counter that
+ * raises the unit's floor tier one step on the Nth consecutive QUALITY failure
+ * (never transport — that is the shipped per-model breaker). Monotonic +
+ * `strong`-capped ⇒ cannot loop or thrash. Naming mirrors
+ * `LocalModelResolver.recordSuccess/recordFailure` (local-model-resolver.ts:460/474).
  */
-declare class RoutingDecisionBus {
-    private readonly ringBuffer;
-    private readonly listeners;
-    private readonly capacity;
-    private readonly logger;
-    constructor(opts?: RoutingDecisionBusOptions);
-    emit(decision: RoutingDecision): void;
-    recent(filter?: RoutingDecisionBusFilter): RoutingDecision[];
-    subscribe(listener: (d: RoutingDecision) => void): () => void;
+declare class EscalationState {
+    private readonly threshold;
+    private readonly units;
+    constructor(threshold?: number);
+    /**
+     * The current escalation floor for a unit — the minimum tier `route()` must
+     * resolve at. Defaults to `'fast'` (no-op floor) for an unknown/absent unit,
+     * so an un-escalated request derives its tier normally.
+     */
+    floorFor(coherenceUnit?: string): CapabilityTier;
+    /** D10 mechanism flag: has this unit ever climbed a tier? (Phase 6 reads this for Tier-A disqualification.) */
+    isEscalated(coherenceUnit?: string): boolean;
+    /**
+     * AMR observability: the coherence units that have climbed ABOVE the `fast`
+     * floor, with their current floor tier. Operator status only (read-only) — an
+     * empty list means nothing has escalated. Units still at `fast` are omitted.
+     */
+    climbedUnits(): Array<{
+        coherenceUnit: string;
+        floor: CapabilityTier;
+    }>;
     /**
-     * Spec B Phase 5 (review-S2 fix): release all subscriber references so
-     * teardown can complete without anchoring closures. Called from
-     * `Orchestrator.stop()` before nulling the bus reference. The bus
-     * remains usable after clear — `subscribe()` works as normal.
+     * SC16: a QUALITY failure at `tier` increments this unit's counter; on the
+     * Nth (threshold) consecutive failure the floor climbs one step (fast→standard
+     * →strong), the count resets, and `escalated` latches true. `strong` is the
+     * ceiling: a threshold-crossing failure already at `strong` returns
+     * 'exhausted' (router emits routing:escalation-exhausted). `ok` clears the
+     * in-progress count but leaves the raised floor (monotonic per D10).
+     *
+     * `_tier` (the tier the outcome occurred at) is ADVISORY/UNUSED today: the climb
+     * is driven entirely off the unit's own `state.floorTier`, not off this argument.
+     * It is kept in the signature so the call-site contract stays stable for a future
+     * refinement that guards against out-of-order (stale-tier) reports. (Note: this is
+     * NOT positionally mirroring `LocalModelResolver.recordFailure`, which keys on a
+     * model identifier and takes no tier — the earlier comment claiming that shape was
+     * misleading.)
      */
-    clearListeners(): void;
+    recordOutcome(coherenceUnit: string, _tier: CapabilityTier, ok: boolean): 'ok' | 'escalated' | 'exhausted';
 }
 
-interface BackendRouterOptions {
-    backends: Record<string, BackendDef>;
-    routing: RoutingConfig;
+interface AdaptiveRouterDeps {
+    router: BackendRouter;
+    registry: BackendCapabilityRegistry;
+    policy: RoutingPolicy;
+    /**
+     * Complexity classifier. Accepts a sync verdict-provider (Phase-3 conservative
+     * stub) OR an async classifier (D4 live cascade); `route()` awaits either shape.
+     * A rejection/throw is caught and degraded to `{moderate, low}` (never blocks
+     * dispatch — Failure modes / D4).
+     */
+    classify: (req: RoutingRequest) => ComplexityVerdict | Promise<ComplexityVerdict>;
+    /** name → provider type, derived from agent.backends (Task 6). REQUIRED when policy.allowedProviders is set. */
+    providerOf?: (name: string) => BackendDef['type'] | undefined;
+    /** Injected spend snapshot (D8/S1-001). Defaults to 0-spend. */
+    budgetState?: () => {
+        spentUsd: number;
+    };
     /**
-     * Spec B Phase 4 (D8): when present, every resolve() emits its
-     * decision onto the bus. The bus owns the structured log line + ring
-     * buffer; the router stays a pure resolution function.
+     * D10 vertical escalation state. When present, `route()` uses
+     * `escalation.floorFor(req.coherenceUnit)` as the tier floor (a climbed unit
+     * resolves higher); when absent, the floor is the no-op `'fast'`.
+     */
+    escalation?: EscalationState;
+    /**
+     * D10 steward-escalation seam. Invoked with the `coherenceUnit` when
+     * `recordOutcome` returns `'exhausted'` (floor already `strong`, re-crossed the
+     * threshold). The orchestrator binds this to `routingDecisionBus`/logger to emit
+     * `routing:escalation-exhausted`.
+     */
+    onExhausted?: (coherenceUnit: string) => void;
+    /**
+     * SC9: enriched-decision bus. The shipped `resolveDecisionAndDef` emits the
+     * BASE decision inside the D2-frozen router (no `complexity`/`tierRequired`/
+     * `estCostUsd`). When `AdaptiveRouter` owns live dispatch it emits the
+     * ENRICHED decision here so a subscriber actually receives the AMR telemetry.
+     * Absent ⇒ no enriched emit (and when AMR is off the router isn't constructed,
+     * so nothing changes on the bus — SC8/SC17 preserved).
      */
     decisionBus?: RoutingDecisionBus;
 }
 /**
- * BackendRouter (Spec B Phase 1)
- *
- * Owns the lookup from a {@link RoutingUseCase} (a discriminated query
- * — tier, intelligence layer, maintenance, chat, isolation, **skill**,
- * **mode**) to a {@link RoutingDecision} naming a chosen backend and
- * the full resolution path that produced it.
- *
- * Resolution order (D2): invocation override -> per-skill -> per-mode
- * -> existing per-tier/intelligence/isolation/maintenance/chat ->
- * `routing.default`. Within each source, fallback chain entries are
- * tried in declared order; first existing backend wins. Unknown
- * entries are recorded with `outcome: 'unknown-backend'` and the walk
- * continues.
+ * AMR Phase 3 (D2): wraps — never modifies — the shipped {@link BackendRouter}.
  *
- * Construction-time validation guarantees every name referenced by
- * `routing` is present in `backends` so the static-config case can
- * never produce a runtime exhaustion throw. The runtime throw at the
- * end of `resolve()` is a safety net for future dynamic-backends
- * scenarios where a chain entry can become unknown post-construction.
+ * `route()` classifies the request, derives the required {@link CapabilityTier}
+ * via `deriveRequiredTier`, picks the cheapest qualifying backend
+ * (`selectCheapestQualifying`), and delegates the actual resolution to
+ * `router.resolveDecisionAndDef` — enriching the returned {@link RoutingDecision}
+ * with `complexity`/`tierRequired`/`estCostUsd` (SC9). The shipped router's
+ * identity/default chain still owns the final backend lookup, so when tier
+ * selection abstains (`undefined`) dispatch falls through unchanged.
  */
-declare class BackendRouter {
-    private readonly backends;
-    private readonly routing;
-    private readonly decisionBus;
-    constructor(opts: BackendRouterOptions);
+declare class AdaptiveRouter {
+    private readonly deps;
+    /**
+     * D8 live spend accumulator. Monotonic sum of `estCostUsd` over every decision
+     * this router has made. `route()` reads it (via the `budgetState` default)
+     * BEFORE deriving a tier, so `deriveRequiredTier`'s budget clamp actually fires
+     * as spend accrues — previously `budgetState` was an un-wired `{ spentUsd: 0 }`
+     * stub, so the clamp was dead.
+     *
+     * Semantics (deliberately modest — do NOT read this as a hard ceiling):
+     * - **Soft, lagging cap.** The clamp reads spend accrued from PRIOR dispatches;
+     *   a burst of concurrent dispatches all read a stale-low total before any of
+     *   them accrues, so a burst can overshoot `capUsd` before the clamp engages.
+     *   This is a degrade *signal*, not an admission gate.
+     * - **Single-step degrade.** `deriveRequiredTier` lowers the tier by exactly ONE
+     *   step under budget pressure and never below the D5 privacy veto floor — it
+     *   does not throttle progressively toward `fast`.
+     * - **Monotonic** (NOT the bounded `projectTelemetry` ring-sum): a long run must
+     *   not evict early spend and un-clamp. Preserved across `setPolicy` (instance
+     *   persists) — note a *lowered* `capUsd` then clamps immediately and, since the
+     *   total never decreases, irreversibly for the rest of the run.
+     * An injected `deps.budgetState` overrides this for the clamp (DI/tests).
+     */
+    private spentUsd;
+    constructor(deps: AdaptiveRouterDeps);
+    /**
+     * Construct an `AdaptiveRouter` from an orchestrator's `agent.backends`
+     * (plus optional LMLM pool). Builds the capability registry via
+     * `buildCapabilityRegistry` and — crucially — derives `providerOf`
+     * UNCONDITIONALLY from `agent.backends` (name → `def.type`).
+     *
+     * Phase-1 finding (capability-registry.ts:60-66): passing an allowlist to
+     * `selectCheapestQualifying` WITHOUT a `providerOf` fail-closes EVERY request
+     * (silent DoS), because every candidate's provider reads back as `undefined`.
+     * Deriving `providerOf` here means enabling the (Phase-5) allowlist branch can
+     * never accidentally deny-all.
+     */
+    static fromConfig(args: {
+        router: BackendRouter;
+        backends: Record<string, BackendDef>;
+        pool?: PoolStateProvider;
+        policy: RoutingPolicy;
+        classify: (req: RoutingRequest) => ComplexityVerdict | Promise<ComplexityVerdict>;
+        budgetState?: () => {
+            spentUsd: number;
+        };
+        /** D10: injected escalation state; defaults to a fresh one seeded from `policy.escalationThreshold`. */
+        escalation?: EscalationState;
+        /** D10: steward-escalation seam bound by the orchestrator to the decision bus/logger. */
+        onExhausted?: (coherenceUnit: string) => void;
+        /** SC9: enriched-decision bus (the same instance dispatch emits base decisions onto). */
+        decisionBus?: RoutingDecisionBus;
+    }): AdaptiveRouter;
+    /**
+     * AMR Phase 5 (D1): hot-swap the routing policy in place. Every policy field
+     * takes effect on the NEXT dispatch EXCEPT `escalationThreshold` (see note) —
+     * the capability registry and `providerOf` are derived from `agent.backends`,
+     * NOT from `policy`, so a policy edit leaves them untouched; `route()` /
+     * `buildConstraints` / `deriveRequiredTier` all read `this.deps.policy` fresh,
+     * so the swapped-in tier matrix / privacy floor / allowlist / budget all apply.
+     * The live {@link EscalationState} is preserved by reference: a unit's climbed
+     * floor survives the swap (a policy edit must not reset accumulated escalation).
+     * The monotonic spend accumulator also persists — so a swap that LOWERS `capUsd`
+     * clamps immediately and irreversibly for the rest of the run (see `spentUsd`).
+     *
+     * Threshold note: the `EscalationState` was seeded with the ORIGINAL policy's
+     * `escalationThreshold` and is intentionally NOT re-seeded here — re-seeding
+     * would conflate "raise the bar" with "reset progress". Preserving climbed
+     * floors is the invariant (SC1); a live threshold change is out of scope (D1).
+     */
+    setPolicy(policy: RoutingPolicy): void;
     /**
-     * Resolve a {@link RoutingUseCase} to a {@link RoutingDecision}.
+     * AMR Phase 5 (D2): project the ENRICHED routing decisions in the bus ring
+     * buffer into the Shuttle telemetry wire shape ({@link RoutingTelemetry}).
      *
-     * @param useCase the routing query
-     * @param opts.invocationOverride if set and the named backend exists,
-     *   beats all other sources (D7 — the `--backend <name>` escape hatch)
+     * Non-destructive — this backs the idempotent `GET /api/v1/routing/telemetry`,
+     * so it reads (never clears) the ring; the ring self-evicts FIFO at capacity
+     * and Shuttle dedups by `decisionTs`. `spentUsd` is therefore a sum over the
+     * RETAINED ring (telemetry, not billing-of-record).
+     *
+     * Filters to ENRICHED decisions only — those `AdaptiveRouter.route()` emitted,
+     * carrying `estCostUsd`+`tierRequired`. The SAME bus also carries the BASE emit
+     * from `BackendRouter.resolveDecisionAndDef` (neither field), so an unfiltered
+     * projection would double-count rows and under-fill `spentUsd`. Returns an
+     * empty payload when no bus is wired or no enriched decisions exist.
      */
-    resolve(useCase: RoutingUseCase, opts?: {
-        invocationOverride?: string;
-    }): RoutingDecision;
+    projectTelemetry(): RoutingTelemetry;
     /**
-     * Returns the {@link BackendDef} reference for the resolved name.
-     * Identity-equal to the entry in `backends` (no copy) so callers
-     * relying on reference equality (SC21) continue to work.
+     * D8: the EFFECTIVE spend total the budget clamp reads — the injected
+     * `budgetState` when present, otherwise the router's own monotonic accumulator.
+     * Returning the effective value (not blindly the internal tally) means an
+     * operator reading this always sees the number that actually drove routing.
      */
-    resolveDefinition(useCase: RoutingUseCase, opts?: {
-        invocationOverride?: string;
-    }): BackendDef;
+    getSpentUsd(): number;
     /**
-     * Spec B Phase 4 (closes P1-IMP-2): a single resolve() + def lookup
-     * for callers that need both. Replaces the previous pattern of
-     * `resolveDefinition(useCase) + resolve(useCase)` which produced two
-     * RoutingDecision emissions per dispatch — doubling routing-decision
-     * log volume now that Phase 4 emits.
-     *
-     * Identity-equal `BackendDef` (no copy) so callers relying on
-     * reference equality (SC21) continue to work.
+     * AMR observability: the live operator status — budget spend-vs-cap (using the
+     * monotonic accumulator that drives the clamp, NOT the telemetry ring sum),
+     * the coherence units that have climbed their escalation floor, and the active
+     * provider allowlist. Called only on a live router, so `active` is always true.
      */
-    resolveDecisionAndDef(useCase: RoutingUseCase, opts?: {
-        invocationOverride?: string;
-    }): {
+    getStatus(): RoutingStatus;
+    route(req: RoutingRequest): Promise<{
         decision: RoutingDecision;
         def: BackendDef;
-    };
+    }>;
     /**
-     * The pre-Spec-B resolution helper: returns the configured
-     * {@link RoutingValue} for tier/intelligence/isolation/maintenance/chat
-     * use cases (or `undefined` for skill/mode use cases, which are owned
-     * by the per-skill / per-mode steps in {@link resolve}). Returning
-     * `undefined` lets the caller fall through to `routing.default`.
+     * D4 fail-safe: await the (possibly async) classifier; if it rejects or throws,
+     * degrade to a conservative `{ level:'moderate', confidence:'low' }` verdict.
+     * Classification NEVER blocks dispatch — a classifier failure/timeout must not
+     * propagate out of `route()`.
      */
-    private resolveExistingUseCase;
-    private validateReferences;
+    private classifySafe;
+    /**
+     * D10 outcome feedback (mirrors LocalModelResolver.recordSuccess/recordFailure).
+     * Only QUALITY failures are reported here; transport/inference errors go to the
+     * shipped per-model breaker and must NOT reach this path (they never
+     * double-count). A quality failure that re-crosses the threshold while the floor
+     * is already `strong` returns `'exhausted'` from EscalationState, at which point
+     * the injected `onExhausted` seam emits `routing:escalation-exhausted` for
+     * steward escalation. No-op when no EscalationState is injected.
+     */
+    recordOutcome(coherenceUnit: string, tier: CapabilityTier, ok: boolean): void;
+    private selectTarget;
+    /**
+     * Translate the request's declared constraints into {@link SelectConstraints}.
+     * `policy.privacyFloor`, the provider allowlist (AMR Phase 5, D3), and the
+     * per-request capability needs are threaded in. `providerOf` is derived
+     * unconditionally in `fromConfig`, so the allowlist can never silently
+     * fail-close every request (Phase-1 finding, capability-registry.ts:60-66).
+     */
+    private buildConstraints;
 }
 
 /**
@@ -1668,6 +2264,13 @@ declare class Orchestrator extends EventEmitter {
      * construction time. Eliminating this fallback is autopilot Phase 4+.
      */
     private backendFactory;
+    /**
+     * AMR Phase 3 (D11): opt-in adaptive router. Constructed ONLY when
+     * `agent.routing.policy` is present and non-empty; `null` otherwise so
+     * dispatch stays byte-identical on the shipped `BackendRouter`
+     * (SC8/SC17/SC19). Exposed for tests via {@link getAdaptiveRouter}.
+     */
+    private adaptiveRouter;
     /**
      * Spec B Phase 4 (D8): per-orchestrator in-process bus for
      * `RoutingDecision` events. Constructed alongside backendFactory when
@@ -1698,6 +2301,13 @@ declare class Orchestrator extends EventEmitter {
      * so this map is the single source of truth post-migration.
      */
     private localResolvers;
+    /**
+     * Consumption Phase 1 (T2): bus listener that debounce-refreshes every local
+     * resolver when a `local-models:pool` mutation fires, so a just-installed or
+     * swapped model becomes usable within the refresh window instead of waiting up
+     * to `probeIntervalMs` for the next poll. Held for removal in {@link stop}.
+     */
+    private poolRefreshListener;
     /** Phase 4 (D5): pool-state port shared by all local/pi resolvers. Null when LMLM disabled. */
     private poolStateProvider;
     private poolStateStore;
@@ -1735,6 +2345,10 @@ declare class Orchestrator extends EventEmitter {
      * see the Phase 2 candidate-parser gap noted on `startRefreshScheduler`.
      */
     private modelRecommender;
+    /** Live HF candidate discovery (injectable for tests so startup makes no network calls). */
+    private readonly discoverCandidatesFn;
+    /** Snapshot of the last candidate seeding, surfaced to the refresh route. */
+    private candidateSourceState;
     /** Test seam: injected timer/clock for the scheduler so no real 24h timer runs. */
     private readonly schedulerTimerOverride;
     /**
@@ -1756,6 +2370,15 @@ declare class Orchestrator extends EventEmitter {
      */
     private localModelStatusUnsubscribes;
     private pipeline;
+    /**
+     * AMR live-classifier provider (final-review finding #2). The complexity
+     * cascade may spend a fast-tier LLM tie-break; it borrows the SEL-layer
+     * AnalysisProvider. Built lazily on first classify (the AdaptiveRouter is
+     * constructed before start(), so this cannot be eager); `null` means "no
+     * provider — cascade stays fully offline / static-only". `undefined` means
+     * "not yet resolved".
+     */
+    private complexityProvider;
     private analysisArchive;
     private graphStore;
     private claimManager;
@@ -1813,6 +2436,8 @@ declare class Orchestrator extends EventEmitter {
             now?: () => number;
             random?: () => number;
         };
+        /** Live-candidate-discovery seam: tests inject a fake so startup makes no HF calls. */
+        discoverCandidates?: (opts: DiscoverCandidatesOptions) => Promise<DiscoverCandidatesResult>;
     });
     /**
      * Phase 5: construct the OTLP/HTTP trace exporter and wire telemetry fanout.
@@ -1868,6 +2493,19 @@ declare class Orchestrator extends EventEmitter {
      */
     private initMaintenance;
     private createIntelligencePipeline;
+    /**
+     * AMR live-classifier provider resolution (final-review finding #2). The
+     * complexity cascade's OPTIONAL fast-tier tie-break borrows the SEL-layer
+     * AnalysisProvider (the same one intelligence enrichment uses). Resolved and
+     * memoized on first classify because the AdaptiveRouter is constructed BEFORE
+     * start(), so the provider cannot be resolved eagerly.
+     *
+     * Returns `undefined` when no provider is available (intelligence disabled, no
+     * backendFactory, or the layer resolves to nothing) — the cascade then stays
+     * fully offline and returns the static verdict (never throws). A build failure
+     * degrades the same way: static-only, never blocks dispatch (D4).
+     */
+    private resolveComplexityProvider;
     /**
      * Lazily initializes the ClaimManager if it hasn't been created yet.
      * Called from both start() and asyncTick() to avoid duplicating the init block.
@@ -1954,10 +2592,136 @@ declare class Orchestrator extends EventEmitter {
     private processAgentEvent;
     private awaitRateLimitClearance;
     private runAgentInBackgroundTask;
+    /**
+     * AMR 4c (ADR 0069): the sound single-agent quality-verdict feeder. On a normal
+     * exit, when AMR is active, run a BASELINE-RELATIVE security scan of the lines
+     * the agent INTRODUCED (only added lines — a pre-existing pattern never counts);
+     * a NEW error-severity finding → `'quality-fail'`, which climbs the coherence
+     * unit's escalation floor. Success stays `neutral` (returns `undefined`) — a
+     * premature `'quality-pass'` would clear accumulating failures (ADR 0069).
+     *
+     * Fully guarded: any error (git/scan/parse) → `undefined` → `neutral`, so this
+     * NEVER breaks completion. No-op (zero cost) when AMR is off, keeping the
+     * dispatch path byte-identical. Staged workflows use their own per-stage gate
+     * feeder; this is the single-agent equivalent.
+     */
+    private deriveSingleAgentQualityVerdict;
+    /**
+     * AMR 4c v2: opt-in LLM spec-satisfaction verdict. Gated on
+     * `routing.policy.acceptanceEval.enabled` (HEAVY — one model call + latency per
+     * exit, so separate from the always-on cheap security scan), a present spec, and
+     * an available analysis provider. Runs the shared `OutcomeEvaluator` over the
+     * introduced diff vs the spec's judgment section, reusing the SEL-layer provider
+     * the live classifier already builds; a BLOCKING verdict (high-confidence
+     * NOT_SATISFIED) → `'quality-fail'`. Conservative + fully guarded: no
+     * spec / no provider / empty diff / any error → `undefined` (neutral). The mapper
+     * only ever emits the negative, so success can never become a premature
+     * `'quality-pass'`. An absent GraphStore falls back to an ephemeral one — the
+     * evaluator's `execution_outcome` persistence is best-effort and never blocks.
+     */
+    private deriveAcceptanceEvalVerdict;
     /**
      * Informs the state machine that an agent worker has exited.
      */
     private emitWorkerExit;
+    /**
+     * AMR Phase 4 (D10/SC16): feed a dispatch outcome into vertical escalation.
+     * No-op unless an AdaptiveRouter is live (policy present) AND this dispatch was
+     * AMR-routed (a `lastRoutedTier` was captured). Transport outcomes never reach
+     * `recordOutcome` — the shipped per-model breaker owns those, so the two signals
+     * never double-count. The coherence unit is the issue id (D6 issue-grain pinning).
+     */
+    private recordAmrOutcome;
+    /**
+     * AMR steward-escalation seam (D10, findings item 1 + 2). Queues a `needs-human`
+     * interaction for a coherence unit whose routing hard-failed — either the vertical
+     * escalation exhausted the `strong` ceiling (`escalation-exhausted`) or the
+     * fail-closed selector left no compliant backend (`privacy-no-match`). Both ride
+     * the SAME `needs-human` mechanism as every other escalation. The `RoutingError`
+     * code disambiguates the two on the steward's channel. The coherence unit is the
+     * issue id (D6 issue-grain pinning); title/description are recovered from running
+     * state when still present. Fire-and-forget + `.catch` — a queue write must never
+     * block or throw out of the dispatch/outcome path.
+     */
+    private escalateRoutingToHuman;
+    /**
+     * AMR dispatch-boundary routing-failure handler (finding #3 + live-wiring
+     * review blocker). When `AdaptiveRouter.route()` throws a fail-closed
+     * `PrivacyNoMatch` (`RoutingError` code `'privacy-no-match'`) at dispatch, that
+     * distinct signal MUST NOT be swallowed by the generic transport/dispatch-error
+     * path (S4-001): it is not a runner/transport failure, so it must never be
+     * recorded as one or feed the vertical escalation breaker. Instead it emits a
+     * DISTINCT `routing:no-tier-match` steward escalation (needs-human, same
+     * mechanism as `onExhausted`) carrying the coherence unit + reason.
+     *
+     * It is ALSO deterministic — the `privacyFloor`/allowlist that emptied the
+     * candidate set is config-driven, so re-dispatch would throw the SAME
+     * `PrivacyNoMatch`. Therefore this path is TERMINAL: it drives the unit to the
+     * `canceled` lane and removes it from `running`/`claimed` directly, rather than
+     * routing through `emitWorkerExit('error')` (whose state-machine error branch
+     * enqueues a retry whenever the retry budget is not yet exhausted — which would
+     * re-dispatch, re-fail closed, and re-escalate up to `maxRetries` times). No
+     * retry is scheduled, no transport outcome is recorded, and exactly one
+     * needs-human escalation is queued. Fail-closed is preserved — `route()` already
+     * refused to pick a non-compliant backend, and returning `true` here stops the
+     * caller from falling through to any further routing.
+     *
+     * Returns `true` when the boundary CLAIMED the error (`privacy-no-match` or the
+     * hard-cap `budget-exhausted`), so the caller returns without ANY
+     * `emitWorkerExit`. Returns `false` for any other error (including
+     * `escalation-exhausted`, which the `onExhausted` seam owns) so the generic
+     * dispatch-error path runs unchanged.
+     */
+    private handleRoutingFailure;
+    /**
+     * AMR live-wiring review blocker: terminally retire a unit whose dispatch failed
+     * closed (`privacy-no-match`). Mirrors the terminal side of a worker exit —
+     * remove the unit from `running` and release its `claimed` slot — then persist
+     * the terminal `canceled` lane (`abandon`), matching how retry-exhausted
+     * escalations settle. Crucially it does NOT run the state-machine `worker_exit`
+     * reducer, so no `scheduleRetry` effect is emitted. Best-effort lane persistence
+     * (`persistLaneSafe` never throws). No transport/escalation outcome is recorded —
+     * that stays the sole job of the single `routing:no-tier-match` escalation already
+     * queued by `escalateRoutingToHuman`.
+     */
+    private finalizeRoutingTerminal;
+    /**
+     * split-routing Phase 4 (D6/SC5) — terminal SUCCESS settle for a workflow unit.
+     * The real `WorkflowEngineContext.emitWorkflowSuccess` forwards here (bound via
+     * the context's `settleSuccess` dep in `dispatchIssue`). It reproduces the
+     * `worker_exit`/`reason==='normal'` reducer BY HAND (state-machine.ts:457,467-474):
+     * `running.delete` → `completed.set(now)` → `claimed.delete` → `cleanWorkspace`
+     * effect → then persists the terminal `success` lane and emits one state change.
+     *
+     * It deliberately does NOT route through `emitWorkerExit`/`handleWorkerExit`
+     * (completion/handler.ts): that fires the ISSUE-keyed `finishRecording(issueId,
+     * attempt)` + `recordAmrOutcome`, but the engine already ran PER-STAGE recorders
+     * (`stageAttemptKey(index, attempt)`) and per-stage `recordOutcome`. Going through
+     * the worker-exit path would (a) finish a recording never started at the
+     * issue-attempt key and (b) double-feed the escalation state. This is the ONE
+     * hand-reproduced reducer sequence in Phase 4; the `worker_exit` reducer itself
+     * stays untouched (Task 12 pins it) so the two remain in sync.
+     *
+     * `runs` are the per-stage records (best-effort telemetry; the per-stage cost is
+     * already attributable via the recorders). Never throws — a success settle must
+     * complete the single terminal transition (D6).
+     */
+    private settleWorkflowSuccess;
+    /**
+     * split-routing Phase 4 (D6/I1/SC5) — terminal FAILURE/safety-net settle for a
+     * workflow unit. The real context's `finalizeWorkflowTerminal` forwards here
+     * (bound via `settleTerminal`). Composed from the `finalizeRoutingTerminal`
+     * pattern (`running.delete` + `claimed.delete` + `persistLaneSafe('abandon')`,
+     * orchestrator.ts:2388-2394) PLUS a single `needs-human` escalation
+     * (escalateRoutingToHuman-style queue push, :2301-2316) PLUS `cleanWorkspace`
+     * (S5). It must NEVER rethrow — the engine's `catch` calls it on the I1 safety
+     * net, so a throw here would defeat the single-exit guarantee.
+     *
+     * It is NOT a verbatim `finalizeRoutingTerminal` call (that lacks the needs-human
+     * + cleanWorkspace the Phase-3 terminal contract pinned). Exactly one needs-human
+     * per terminal transition.
+     */
+    private settleWorkflowTerminal;
     /**
      * Hermes Phase 3: wire in-process notification sinks against the
      * orchestrator's event bus (`this`). A misconfigured sink (unknown kind,
@@ -1993,6 +2757,14 @@ declare class Orchestrator extends EventEmitter {
      * `store.load()`.
      */
     private initModelPool;
+    /**
+     * Resume installs interrupted by a restart. A proposal left `installing` had
+     * its background `ollama pull` cut short when the orchestrator went down; the
+     * pull is idempotent (ollama resumes from cached blobs), so we re-drive it.
+     * Fire-and-forget with its own error isolation — a resumed multi-GB download
+     * must not block startup, and a re-drive failure only logs.
+     */
+    private redriveInterruptedInstalls;
     /**
      * LMLM Phase 7 wiring: apply the operator's configured pool bounds (disk
      * budget + org/family allowlist) from `localModels.pool` to the live pool.
@@ -2015,6 +2787,17 @@ declare class Orchestrator extends EventEmitter {
      * breadth is the only piece deferred to the Phase 2 recommender.
      */
     private startRefreshScheduler;
+    /** (Re)build the recommender over `candidates` and record the seeding source. */
+    private seedRecommender;
+    /**
+     * Refresh ranking candidates live from HuggingFace, merge the curated
+     * `ollamaName`/`family` tags from the frozen snapshot (so results stay
+     * installable — decision A), and re-seed the recommender. Fail-closed: on any
+     * error or an empty installable result, the current candidates stand. Runs a
+     * `forceRefresh` tick so recommendations + proposals reflect the fresh set.
+     * Used by both the startup background refresh and the operator "Refresh" button.
+     */
+    private refreshCandidatesLive;
     /** Resolve the hardware profile for a refresh tick (operator override wins). */
     private detectLmlmHardware;
     /** Map the on-disk model-proposal queue to F7 dedup pairs (open→pending, rejected→rejected). */
@@ -2041,6 +2824,51 @@ declare class Orchestrator extends EventEmitter {
      * single-backend config bypassed agent.backends synthesis.
      */
     getRoutingDecisionBus(): RoutingDecisionBus | null;
+    /**
+     * AMR Phase 3 (D11): the opt-in adaptive router, or `null` when no
+     * `routing.policy` is configured (the default-off path). Exposed for the
+     * SC8/SC17/SC19 default-off proof: `null` here means dispatch stays on the
+     * shipped `BackendRouter`, byte-identical, with no classify()/telemetry.
+     */
+    getAdaptiveRouter(): AdaptiveRouter | null;
+    /**
+     * AMR Phase 3 (D11) / Phase 5 (D1): construct the opt-in AdaptiveRouter for a
+     * policy. Extracted from the constructor so runtime ingestion
+     * (`ingestRoutingPolicy`) builds a router IDENTICAL to the constructor's —
+     * same live classify seam, strong-cap escalation-exhaustion hard-fail-to-human
+     * (D10), and enriched-decision bus (SC9). Precondition: the routing subsystem
+     * exists (`backendFactory` + `agent.backends` present); callers guard.
+     */
+    private buildAdaptiveRouter;
+    /**
+     * AMR Phase 5 (D1/D5): ingest a routing policy pushed at runtime by the
+     * Shuttle control plane (`PUT /api/v1/routing/policy`). Hot-swaps the live
+     * router:
+     *   - empty policy (`{}` / no activating fields) → `adaptiveRouter = null`
+     *     (default-off restored, D5 — byte-identical dispatch resumes);
+     *   - an existing router → `setPolicy` (preserves the accumulated
+     *     `EscalationState` climbed floors — a policy edit must not reset them);
+     *   - no router yet → construct one from the pushed policy.
+     *
+     * The field-swap is atomic between `await`s (single-threaded): a dispatch that
+     * already captured the router finishes on it; the next dispatch sees the new
+     * policy. No-op-safe when the routing subsystem is absent (`backendFactory`
+     * null) — the caller (`PUT` handler) reports 503 in that case, so this path is
+     * reached only when routing is available.
+     */
+    ingestRoutingPolicy(policy: RoutingPolicy): void;
+    /**
+     * AMR Phase 5 (D2): project the live router's enriched decision ring into the
+     * Shuttle telemetry wire shape (`GET /api/v1/routing/telemetry`). Returns an
+     * empty payload when routing is off (no router) — a safe, idempotent read.
+     */
+    getRoutingTelemetry(): RoutingTelemetry;
+    /**
+     * AMR observability: the live operator status (budget spend-vs-cap, escalated
+     * units, allowlist), or an inactive payload when AMR is off. Backs
+     * `GET /api/v1/routing/status`.
+     */
+    getRoutingStatus(): RoutingStatus;
     /**
      * Spec B Phase 5: live BackendRouter for HTTP routes. The orchestrator
      * dispatch path uses the factory-owned router directly; observability
@@ -2079,102 +2907,70 @@ declare function launchTUI(orchestrator: Orchestrator): {
 };
 
 /**
- * Options for `OrchestratorBackendFactory`.
+ * Fail-closed signal: privacy floor / allowlist emptied the candidate set (S4-001).
+ * Distinguishable from a tier/cost-only exclusion, which returns `undefined`.
  *
- * `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).
+ * Finding #4 — ONE typed error family: `PrivacyNoMatch` stays orchestrator-local
+ * (it is thrown deep in the selector, a layer below the exported types package) but
+ * EXTENDS the exported `RoutingError`, carrying its canonical `'privacy-no-match'`
+ * code. The dispatch boundary can therefore catch it as either `PrivacyNoMatch`
+ * (ergonomic `instanceof`) or `RoutingError` (code-narrowed), and the sibling
+ * `escalation-exhausted` code is emitted via `RoutingError` too — no divergent
+ * surfaces, no dead exported error type. `code` narrows to the literal here.
  */
-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;
-    /**
-     * Phase 5: prompt-cache recorder forwarded to Anthropic-capable backends.
-     * Other backends accept-but-ignore. Shared across dispatches so the
-     * `/api/v1/telemetry/cache/stats` endpoint sees the full rolling window.
-     */
-    cacheMetrics?: CacheMetricsRecorder;
-    /**
-     * Spec B Phase 4 (D8): forwarded to the underlying BackendRouter so
-     * every resolve() during forUseCase / resolveName emits.
-     */
-    decisionBus?: RoutingDecisionBus;
+declare class PrivacyNoMatch extends RoutingError {
+    readonly code: "privacy-no-match";
+    constructor(message: string);
+}
+interface SelectConstraints {
+    privacyFloor?: PrivacyClass;
+    /** Present ⇒ only these providers allowed. Absent ⇒ all allowed. Empty array ⇒ none. */
+    allowed?: BackendDef['type'][];
+    needsVision?: boolean;
+    needsToolUse?: boolean;
+    minContextTokens?: number;
 }
 /**
- * High-level factory wrapping `BackendRouter` + `createBackend` plus
- * orchestrator-side concerns (sandbox wrapping, resolver binding).
+ * D1 core: filter the registry to backends with tier ≥ requiredTier, privacyClass
+ * at least as strong as the floor, provider in the allowlist, and capabilities ⊇
+ * required (vision/toolUse/minContextTokens); sort by costPer1kTokens ascending;
+ * return the cheapest.
  *
- * 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'.
+ * Fail-closed (S4-001): if a privacy-floor OR allowlist constraint empties the set,
+ * throw PrivacyNoMatch (the item must surface to the steward — never fall through
+ * to identity routing at a non-compliant backend). A tier/cost-only exclusion is
+ * best-effort: return undefined so the caller can fall back to the shipped router's
+ * identity/default chain. No `if (local)` anywhere.
  */
-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, opts?: {
-        invocationOverride?: string;
-    }): string;
-    /**
-     * Spec B Phase 1: expose the underlying router for callers that need
-     * it directly (e.g., {@link buildIntelligencePipeline} for the
-     * I1 SEL/PESL comparison fix). Read-only access; consumers must not
-     * mutate router state.
-     */
-    getRouter(): BackendRouter;
-    forUseCase(useCase: RoutingUseCase, opts?: {
-        invocationOverride?: string;
-    }): 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;
-}
+declare function selectCheapestQualifying(registry: BackendCapabilityRegistry, requiredTier: CapabilityTier, constraints: SelectConstraints, 
+/**
+ * Provider lookup by name, required to enforce a `constraints.allowed` allowlist.
+ * If `allowed` is set but `providerOf` is absent (or returns `undefined` for an
+ * entry), that entry cannot be admitted → excluded; an allowlist with no
+ * `providerOf` therefore excludes ALL candidates and fails closed
+ * (`PrivacyNoMatch`). Phase 3 (`AdaptiveRouter`) MUST derive this from
+ * `agent.backends` whenever it sets an allowlist. Absent `allowed` ⇒ unused.
+ */
+providerOf?: (name: string) => BackendDef['type'] | undefined): {
+    name: string;
+    capabilities: BackendCapabilities;
+} | undefined;
+/** Default capability block derived for an LMLM pool candidate that carries no
+ *  explicit capabilities. On-device ⇒ strongest privacy, zero marginal cost.
+ *  Seed values (tunable in later phases); a candidate is thus visible to tier
+ *  selection (spec "Failure modes": a backend with NO capabilities is invisible,
+ *  but a pool candidate is always given a derived block so it can win on cost). */
+declare function defaultPoolCapabilities(): BackendCapabilities;
+/**
+ * Build the tier-selection registry (name → capabilities) from configured
+ * `agent.backends` (their `capabilities` blocks, when present) merged with LMLM
+ * pool candidates (each given a derived on-device/zero-cost block). A configured
+ * backend WITHOUT a `capabilities` block is omitted — invisible to tier selection,
+ * reachable only via identity routing (spec "Failure modes"). No LMLM code changes.
+ */
+declare function buildCapabilityRegistry(backends: Record<string, BackendDef>, pool?: PoolStateProvider): BackendCapabilityRegistry;
+
+declare function estimateCost(def: BackendDef, _req: RoutingRequest): number;
 
 /**
  * Result of running `migrateAgentConfig`.
@@ -2451,6 +3247,26 @@ interface LocalModelResolverOptions {
     poolState?: PoolStateProvider;
     /** Probe cadence in ms; default 30_000, minimum 1_000. */
     probeIntervalMs?: number;
+    /** Debounce window for event-driven {@link LocalModelResolver.refresh}; default 250ms. */
+    refreshDebounceMs?: number;
+    /**
+     * Consumption Phase 5 (T19/T20): called with the newly-resolved model name
+     * whenever the resolver's composite selection changes (and is non-null), so
+     * the orchestrator can warm it into VRAM before the next dispatch. Naturally
+     * debounced — it fires only on an actual selection change, not every probe.
+     * Best-effort: a throwing hook is swallowed. Injected in tests; wired to
+     * {@link defaultWarmModel} in production.
+     */
+    warmModel?: (ollamaName: string) => void;
+    /**
+     * Consumption Phase 3 (T10): consecutive inference failures before a model is
+     * deprioritized by the circuit breaker. Default 3.
+     */
+    breakerThreshold?: number;
+    /** Cooldown (ms) after which a tripped model is eligible again. Default 60_000. */
+    breakerCooldownMs?: number;
+    /** Injectable clock (ms since epoch) for the circuit-breaker cooldown; default `Date.now`. Test seam. */
+    now?: () => number;
     /**
      * Per-request timeout for the default fetch implementation, in ms.
      * Default: 5_000. Ignored when a custom `fetchModels` is provided
@@ -2482,8 +3298,21 @@ declare class LocalModelResolver {
     private readonly poolState?;
     private readonly probeIntervalMs;
     private readonly fetchModels;
+    private readonly warmModel?;
     private readonly logger;
     private timer;
+    /** Debounce handle for event-driven {@link refresh}; coalesces a burst into one probe. */
+    private refreshTimer;
+    /** Test seam for the refresh debounce delay (0 in tests → next-tick probe). */
+    private readonly refreshDebounceMs;
+    /** Consumption Phase 3 (T10): circuit-breaker config + per-model failure/trip state. */
+    private readonly breakerThreshold;
+    private readonly breakerCooldownMs;
+    private readonly now;
+    /** Consecutive inference failures per model since its last success. */
+    private consecutiveFailures;
+    /** Epoch-ms at which a tripped model becomes eligible again (cooldown expiry). */
+    private trippedUntil;
     private listeners;
     /**
      * Tracks an in-flight probe so concurrent invocations (interval tick while a
@@ -2502,7 +3331,15 @@ declare class LocalModelResolver {
     private warnings;
     private available;
     constructor(opts: LocalModelResolverOptions);
-    resolveModel(): string | null;
+    /**
+     * The model to dispatch to. With no `useCase`, returns the cached composite
+     * resolution from the last probe (byte-identical to the pre-Phase-4 resolver).
+     * With a `useCase`, orders the (pool-derived) candidates by that use-case's
+     * task profile and picks the best loaded, breaker-healthy one — so a
+     * coding-tagged dispatch prefers the coding specialist. A `general`-mapped
+     * use-case returns the cached composite resolution unchanged.
+     */
+    resolveModel(useCase?: RoutingUseCase): string | null;
     getStatus(): LocalModelStatus;
     /**
      * Effective candidate list. With a poolState port present the list derives
@@ -2513,6 +3350,41 @@ declare class LocalModelResolver {
     onStatusChange(handler: (status: LocalModelStatus) => void): () => void;
     probe(): Promise<LocalModelStatus>;
     private runProbe;
+    /** Best-effort warm-hook invocation — a throwing warm never breaks a probe. */
+    private warm;
+    /**
+     * Consumption Phase 3 (T10): pick the resolved model from the candidates that
+     * are actually loaded, preferring ones whose circuit breaker is not tripped.
+     * Candidate order (score-desc from the pool) is preserved within each tier, so
+     * a tripped top pick sinks below a healthy lower pick but still resolves as a
+     * last resort when every loaded candidate is tripped (better a flaky model than
+     * none). Returns null when no candidate is loaded.
+     */
+    private selectMatch;
+    /**
+     * Whether `model`'s circuit breaker is currently tripped. Lazily clears the
+     * trip once its cooldown has elapsed so the model becomes eligible again on the
+     * next resolution without needing a separate timer.
+     */
+    private isTripped;
+    /**
+     * Record a successful inference on `model`: clears its failure count and any
+     * active trip so a recovered model is immediately re-preferred.
+     */
+    recordSuccess(model: string): void;
+    /**
+     * Record a failed inference on `model`. On the Nth consecutive failure the
+     * breaker trips (deprioritizing the model for `breakerCooldownMs`) and a
+     * re-probe is scheduled so the resolver rolls to a healthy alternative.
+     */
+    recordFailure(model: string): void;
+    /**
+     * Event-driven refresh: schedule a debounced re-probe. Called when a
+     * `local-models:pool` mutation fires so a just-installed/swapped model becomes
+     * usable within a debounce window instead of waiting up to `probeIntervalMs`.
+     * A burst of frames coalesces into one probe (the timer is only armed once).
+     */
+    refresh(): void;
     start(): Promise<void>;
     stop(): void;
     private snapshotForDiff;
@@ -3663,4 +4535,4 @@ declare function emitProposalCreated(bus: EventEmitter, proposal: SkillProposal)
 declare function emitProposalApproved(bus: EventEmitter, proposal: SkillProposal): void;
 declare function emitProposalRejected(bus: EventEmitter, proposal: SkillProposal): void;
 
-export { type AgentDispatchResult, type AgentDispatcher, type AgentDispatcherDeps, type AgentUpdateEvent, AnalysisArchive, type AnalysisRecord, type ApplyEventResult, type ArtifactPresence, type AttemptStats, BUILT_IN_TASKS, BackendDefSchema, type BackendResolver, BackendRouter, type BackendRouterOptions, type BaseRefFallbackEvent, type BuildArchiveHooksOptions, type CheckCommandResult, type CheckCommandRunner, type CheckFailureClassification, type CheckFailureKind, CheckScriptRunner, ClaimManager, type ClaimManagerConfig, type CleanWorkspaceEffect, type CommandExecResult, type CommandExecutor, type CreateTokenInput, type CreateTokenResult, type CustomTaskValidationError, type DispatchEffect, type EmitLogEffect, type EscalateEffect, type ExecFileAsyncFn, type ExecFileError, type ExecFileFn$1 as ExecFileFn, type FromConfigOptions, GateNotReadyError, type GateResult, GateRunError, type HarnessSpawn, type Highlight, type HighlightsInfo, type IndexedDoc, InteractionQueue, LinearGraphQLClient, type LinearGraphQLClientOptions, type LinearGraphQLExtension, LinearGraphQLStub, type LiveSession, LocalModelResolver, type LocalModelResolverOptions, MAINTENANCE_CHECK_MAX_BUFFER, MAINTENANCE_CHECK_TIMEOUT_MS, MAX_ATTEMPTS, MaintenanceReporter, type MaintenanceReporterOptions, type MigrationResult, MockBackend, type NotificationSink, type NotificationSinkDeliverInput, ORCHESTRATOR_IDENTITY_FILE, Orchestrator, OrchestratorBackendFactory, type OrchestratorBackendFactoryOptions, type OrchestratorContext, type OrchestratorEvent, type OrchestratorState, PRDetector, type PRDetectorLogger, type PRLifecycleManager, type PendingInteraction, type PersistedOutputEntry, PromotionError, type PromotionResult, PromptRenderer, type ProposalApprovedData, type ProposalCreatedData, type ProposalRejectedData, type PublishedIndex, type QueueInsertInput, type QueueRow, type QueueStats, RETRY_DELAYS_MS, type RateLimitSnapshot as RateLimitComputeSnapshot, type RateLimitConfig, type RateLimitSnapshot$1 as RateLimitSnapshot, type RegistryEntry, type ReleaseClaimEffect, type ResolverLogger, type RetryEntry, type RetryFiredEvent, RoadmapTrackerAdapter, RoutingConfigSchema, RoutingValueSchema, type RunAttemptPhase, type RunHarnessCheckOptions, type RunMode, type RunOrigin, type RunResult, type RunningEntry, type ScheduleRetryEffect, type SearchOptions, type SideEffect, SinkConfigError, SinkRegistry, type SkillCatalogEntry, SlackSink, type SlackSinkOptions, SqliteSearchIndex, type StallDetectedEvent, type StopEffect, type StreamManifest, StreamRecorder, type SummarizeContext, type SummarizeResult, type SyncMainOptions, type SyncMainResult, type SyncSkipReason, type TaskDefinition, TaskOutputStore, TaskRunner, type TaskRunnerOptions, type TaskSelectionFilter, type TaskType, type TickEvent, TokenStore, type TokenTotals, type TriageConfig, type TriageDecision, type TriageSignals, type TriageSkill, type UpdateTokensEffect, type ValidateWorkflowConfigOptions, type ValidatedWorkflowConfig, WebhookQueue, type WorkerExitEvent, WorkflowLoader, WorkspaceHooks, WorkspaceManager, type WorkspaceManagerOptions, applyEvent, artifactPresenceFromIssue, buildArchiveHooks, calculateRetryDelay, canDispatch, classifyCheckExecutionFailure, computeRateLimitDelay, createAgentDispatcher, createBackend, createEmptyState, crossFieldRoutingIssues, defaultFetchModels, deriveSeedPaths, detectScopeTier, discoverSkillCatalog, discoverSkillCatalogNames, emitProposalApproved, emitProposalCreated, emitProposalRejected, explicitFindingsCount, extractHighlights, extractTitlePrefix, getAvailableSlots, getDefaultConfig, getPerStateCount, indexSessionDirectory, isCheckTimeoutError, isEligible, isSummaryEnabled, launchTUI, loadPublishedIndex, makeBackendResolver, migrateAgentConfig, normalizeFts5Query, normalizeHarnessCommand, normalizeLocalModel, openSearchIndex, promote, reconcile, recoverFindingsCount, reindexFromArchive, renderAnalysisComment, renderLlmSummaryMarkdown, renderPRComment, resolveEscalationConfig, resolveOrchestratorId, routeIssue, routingWarnings, runGate, runHarnessCheck, savePublishedIndex, searchIndexPath, selectCandidates, selectTasks, sortCandidates, summarizeArchivedSession, syncMain, triageIssue, truncateForBudget, validateCustomTasks, validateWorkflowConfig, wireNotificationSinks, wrapAsEnvelope };
+export { AdaptiveRouter, type AdaptiveRouterDeps, type AgentDispatchResult, type AgentDispatcher, type AgentDispatcherDeps, type AgentUpdateEvent, AnalysisArchive, type AnalysisRecord, type ApplyEventResult, type ArtifactPresence, type AttemptStats, BUILT_IN_TASKS, BackendDefSchema, type BackendResolver, BackendRouter, type BackendRouterOptions, type BaseRefFallbackEvent, type BuildArchiveHooksOptions, type BuildWorkflowContextDeps, type CheckCommandResult, type CheckCommandRunner, type CheckFailureClassification, type CheckFailureKind, CheckScriptRunner, ClaimManager, type ClaimManagerConfig, type CleanWorkspaceEffect, type CommandExecResult, type CommandExecutor, type CreateTokenInput, type CreateTokenResult, type CustomTaskValidationError, type DispatchEffect, type EmitLogEffect, type EscalateEffect, EscalationState, type ExecFileAsyncFn, type ExecFileError, type ExecFileFn$1 as ExecFileFn, type FromConfigOptions, GateNotReadyError, type GateResult, GateRunError, type HarnessSpawn, type Highlight, type HighlightsInfo, type IndexedDoc, InteractionQueue, LinearGraphQLClient, type LinearGraphQLClientOptions, type LinearGraphQLExtension, LinearGraphQLStub, type LiveSession, LocalModelResolver, type LocalModelResolverOptions, MAINTENANCE_CHECK_MAX_BUFFER, MAINTENANCE_CHECK_TIMEOUT_MS, MAX_ATTEMPTS, MaintenanceReporter, type MaintenanceReporterOptions, type MigrationResult, MockBackend, type NotificationSink, type NotificationSinkDeliverInput, ORCHESTRATOR_IDENTITY_FILE, Orchestrator, OrchestratorBackendFactory, type OrchestratorBackendFactoryOptions, type OrchestratorContext, type OrchestratorEvent, type OrchestratorState, PRDetector, type PRDetectorLogger, type PRLifecycleManager, type PendingInteraction, type PersistedOutputEntry, PrivacyNoMatch, PromotionError, type PromotionResult, PromptRenderer, type ProposalApprovedData, type ProposalCreatedData, type ProposalRejectedData, type PublishedIndex, type QueueInsertInput, type QueueRow, type QueueStats, RETRY_DELAYS_MS, type RateLimitSnapshot as RateLimitComputeSnapshot, type RateLimitConfig, type RateLimitSnapshot$1 as RateLimitSnapshot, type RegistryEntry, type ReleaseClaimEffect, type ResolverLogger, type RetryEntry, type RetryFiredEvent, RoadmapTrackerAdapter, RoutingConfigSchema, RoutingValueSchema, type RunAttemptPhase, type RunHarnessCheckOptions, type RunMode, type RunOrigin, type RunResult, type RunningEntry, type ScheduleRetryEffect, type SearchOptions, type SelectConstraints, type SideEffect, SinkConfigError, SinkRegistry, type SkillCatalogEntry, SlackSink, type SlackSinkOptions, SqliteSearchIndex, type StallDetectedEvent, type StopEffect, type StreamManifest, StreamRecorder, type SummarizeContext, type SummarizeResult, type SyncMainOptions, type SyncMainResult, type SyncSkipReason, type TaskDefinition, TaskOutputStore, TaskRunner, type TaskRunnerOptions, type TaskSelectionFilter, type TaskType, type TickEvent, TokenStore, type TokenTotals, type TriageConfig, type TriageDecision, type TriageSignals, type TriageSkill, type UpdateTokensEffect, type ValidateWorkflowConfigOptions, type ValidatedWorkflowConfig, WebhookQueue, type WorkerExitEvent, WorkflowLoader, type WorkflowRouterDep, WorkspaceHooks, WorkspaceManager, type WorkspaceManagerOptions, applyEvent, artifactPresenceFromIssue, buildArchiveHooks, buildCapabilityRegistry, buildWorkflowContext, calculateRetryDelay, canDispatch, classifyCheckExecutionFailure, computeRateLimitDelay, createAgentDispatcher, createBackend, createEmptyState, crossFieldRoutingIssues, defaultFetchModels, defaultPoolCapabilities, deriveSeedPaths, detectScopeTier, discoverSkillCatalog, discoverSkillCatalogNames, emitProposalApproved, emitProposalCreated, emitProposalRejected, estimateCost, explicitFindingsCount, extractHighlights, extractTitlePrefix, getAvailableSlots, getDefaultConfig, getPerStateCount, indexSessionDirectory, isCheckTimeoutError, isEligible, isSummaryEnabled, launchTUI, loadPublishedIndex, makeBackendResolver, migrateAgentConfig, normalizeFts5Query, normalizeHarnessCommand, normalizeLocalModel, openSearchIndex, promote, reconcile, recoverFindingsCount, reindexFromArchive, renderAnalysisComment, renderLlmSummaryMarkdown, renderPRComment, resolveEscalationConfig, resolveOrchestratorId, routeIssue, routingWarnings, runGate, runHarnessCheck, savePublishedIndex, searchIndexPath, selectCandidates, selectCheapestQualifying, selectTasks, sortCandidates, summarizeArchivedSession, syncMain, triageIssue, truncateForBudget, validateCustomTasks, validateWorkflowConfig, wireNotificationSinks, workflowFor, wrapAsEnvelope };