@harness-engineering/orchestrator 0.5.0 → 0.7.0

package/dist/index.d.mts

@@ -1,5 +1,6 @@
-import { Issue, AgentEvent, WorkflowConfig, TokenUsage, ConcernSignal, ScopeTier, EscalationConfig, RoutingDecision, Result, WorkflowDefinition, WorkspaceConfig, HooksConfig, AgentBackend, SessionStartParams, AgentSession, AgentError, TurnParams, TurnResult, BackendDef, RoutingConfig, RoutingUseCase, ContainerConfig, SecretConfig, AgentConfig, 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, CacheMetricsRecorder, ArchiveHooks } from '@harness-engineering/core';
+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, CustomTaskDefinition, 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, CacheMetricsRecorder, ArchiveHooks, SkillProposal, ProposalGateFinding } 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';
@@ -366,6 +367,10 @@ interface TickEvent {
     simulationResults?: Map<string, SimulationResult>;
     /** Pre-computed persona recommendations from specialization scorer (issueId -> recommendations) */
     personaRecommendations?: Map<string, WeightedRecommendation[]>;
+    /** Identity of this orchestrator. Items assigned to a different value are
+     *  filtered out of dispatch by `selectCandidates`. Omit for back-compat
+     *  (preserves today's permissive behavior). */
+    selfAssignee?: string;
 }
 interface WorkerExitEvent {
     type: 'worker_exit';
@@ -485,11 +490,11 @@ declare function sortCandidates(issues: readonly Issue[]): Issue[];
  * Check if a single issue is dispatch-eligible.
  * State comparisons are case-insensitive.
  */
-declare function isEligible(issue: Issue, state: OrchestratorState, activeStates: string[], terminalStates: string[]): boolean;
+declare function isEligible(issue: Issue, state: OrchestratorState, activeStates: string[], terminalStates: string[], selfAssignee?: string | null): boolean;
 /**
  * Select and sort eligible candidates from a list of issues.
  */
-declare function selectCandidates(issues: readonly Issue[], state: OrchestratorState, activeStates: string[], terminalStates: string[]): Issue[];
+declare function selectCandidates(issues: readonly Issue[], state: OrchestratorState, activeStates: string[], terminalStates: string[], selfAssignee?: string | null): Issue[];
 
 /**
  * Get the number of available global concurrency slots.
@@ -549,7 +554,7 @@ declare function detectScopeTier(issue: Issue, artifacts: ArtifactPresence): Sco
  * 4. If tier is in signalGated -> check concern signals
  * 5. Otherwise -> dispatch-local (safe default)
  */
-declare function routeIssue(scopeTier: ScopeTier, concernSignals: ConcernSignal[], config: EscalationConfig): RoutingDecision;
+declare function routeIssue(scopeTier: ScopeTier, concernSignals: ConcernSignal[], config: EscalationConfig): IssueRoutingDecision;
 
 /**
  * Candidate skills the orchestrator may dispatch to. Keep this set
@@ -864,9 +869,107 @@ declare class WorkflowLoader {
     loadWorkflow(filePath: string): Promise<Result<WorkflowDefinition, Error>>;
 }
 
-declare function validateWorkflowConfig(config: unknown): Result<WorkflowConfig, Error>;
+/**
+ * Cross-field check: every value in `routing` must reference a key in
+ * `backends`. Mirrors the Phase 1 standalone helper but returns a flat
+ * array of issues for synchronous consumption inside
+ * `validateWorkflowConfig` (which is hand-rolled, not a Zod parse).
+ *
+ * Exported for unit testing. Production callers should prefer
+ * `validateWorkflowConfig` (which wraps this helper with the surrounding
+ * legacy-vs-modern branching).
+ */
+declare function crossFieldRoutingIssues(backends: Record<string, BackendDef>, routing: RoutingConfig): Array<{
+    path: string[];
+    message: string;
+}>;
+/**
+ * Spec B Phase 2 / S3: produce non-blocking warnings for misconfigured
+ * routing entries that are SYNTACTICALLY valid (the cross-field check
+ * has passed) but SEMANTICALLY suspicious:
+ *
+ *  - `routing.skills.<name>` where `<name>` is not in the local skill
+ *    catalog. Likely a typo or a skill that was renamed / removed.
+ *
+ *  - `routing.modes.<mode>` where `<mode>` is not in the
+ *    STANDARD_COGNITIVE_MODES tuple. Since `CognitiveMode` allows the
+ *    `(string & {})` escape hatch, the type system accepts custom modes
+ *    — but operators are far more likely to typo a standard mode than
+ *    introduce a custom one, so we warn.
+ *
+ * Returns an empty array when `knownSkillNames` is empty (i.e., the
+ * catalog could not be discovered — most likely because `agents/skills/`
+ * is absent). Skipping is preferable to flooding the operator with
+ * false positives when the catalog itself is missing.
+ *
+ * Warnings are advisory; the loader continues to return `Ok` and the
+ * orchestrator starts normally.
+ */
+declare function routingWarnings(routing: RoutingConfig, knownSkillNames: readonly string[]): string[];
+interface ValidateWorkflowConfigOptions {
+    /**
+     * Known skill names from the local catalog. When non-empty, used to
+     * warn (S3) on `routing.skills.<name>` references that are not in
+     * the catalog. When empty, skill-name warnings are suppressed — the
+     * caller is presumed to be running without a discoverable catalog
+     * (e.g., tests, or orchestrator outside a harness project root).
+     */
+    knownSkillNames?: readonly string[];
+}
+interface ValidatedWorkflowConfig {
+    config: WorkflowConfig;
+    /**
+     * Non-blocking warnings produced during validation. Currently
+     * includes (Spec B Phase 2 / S3):
+     *   - `routing.skills.<name>` not in the local catalog
+     *   - `routing.modes.<mode>` not in `STANDARD_COGNITIVE_MODES`
+     */
+    warnings: readonly string[];
+}
+declare function validateWorkflowConfig(config: unknown, options?: ValidateWorkflowConfigOptions): Result<ValidatedWorkflowConfig, Error>;
 declare function getDefaultConfig(): WorkflowConfig;
 
+/**
+ * Spec B Phase 3: an entry in the local skill catalog.
+ *
+ * Carries the skill's catalog `name` AND optional `cognitive_mode`
+ * declaration from `skill.yaml`. Consumed by the orchestrator dispatch
+ * site to construct `{ kind: 'skill', skillName, cognitiveMode }`
+ * RoutingUseCases so per-skill / per-mode routing fires at dispatch.
+ */
+interface SkillCatalogEntry {
+    readonly name: string;
+    readonly cognitiveMode?: string;
+}
+/**
+ * Spec B Phase 3: read the local skill catalog at orchestrator startup,
+ * returning each declared skill's `name` AND optional `cognitive_mode`.
+ *
+ * Reads from EVERY host subdirectory under `agents/skills/` (claude-code,
+ * cursor, gemini, etc.). Names are deduplicated across hosts — first
+ * occurrence wins (matches Phase 2 behavior for `discoverSkillCatalogNames`).
+ *
+ * Returns an empty array when `agents/skills/` is absent (orchestrator
+ * running outside a harness project root). In that case dispatch-site
+ * routing falls through to per-tier resolution, preserving today's
+ * behavior (F11/N2).
+ *
+ * Errors reading individual skill.yaml files (malformed YAML, missing
+ * `name` field, IO errors) are swallowed silently. The catalog is
+ * advisory; a single broken skill.yaml should not block dispatch.
+ */
+declare function discoverSkillCatalog(projectRoot: string): SkillCatalogEntry[];
+/**
+ * Spec B Phase 2: read the local skill catalog at orchestrator startup
+ * for warning-level routing validation (`routing.skills.<name>` where
+ * `<name>` is not in the catalog).
+ *
+ * Spec B Phase 3: thin alias over {@link discoverSkillCatalog} — name
+ * extraction preserved for the Phase 2 WorkflowLoader → validation
+ * pipeline (no behavioral change for Phase 2 callers).
+ */
+declare function discoverSkillCatalogNames(projectRoot: string): string[];
+
 /**
  * Adapter for using a markdown roadmap file as an issue tracker.
  *
@@ -1084,8 +1187,10 @@ declare class PromptRenderer {
 
 /**
  * Internal types for the maintenance module.
- * Public config types (MaintenanceConfig, TaskOverride) live in @harness-engineering/types.
+ * Public config types (MaintenanceConfig, TaskOverride, CustomTaskDefinition,
+ * CheckScriptDefinition, OutputRetentionConfig) live in @harness-engineering/types.
  */
+
 /**
  * Classification of maintenance task execution strategy.
  *
@@ -1095,6 +1200,85 @@ declare class PromptRenderer {
  * - housekeeping: Run a mechanical command directly; no AI, no PR.
  */
 type TaskType = 'mechanical-ai' | 'pure-ai' | 'report-only' | 'housekeeping';
+/**
+ * Hermes Phase 2 — Provenance tag identifying the trigger source of a run.
+ *
+ * Set by the entry point, never user-configurable:
+ *   - 'cron'                      — scheduled by MaintenanceScheduler
+ *   - 'cli'                       — `harness maintenance run <id>`
+ *   - { kind: 'api', tokenName }  — Gateway API trigger (Phase 0)
+ *   - { kind: 'chain', upstreamTaskId } — fired by a downstream `contextFrom`
+ *                                          dependency (reserved; not yet wired)
+ */
+type RunOrigin = 'cron' | 'cli' | {
+    kind: 'api';
+    tokenName: string;
+} | {
+    kind: 'chain';
+    upstreamTaskId: string;
+};
+/**
+ * Per-task cost ceiling (Hermes Phase 5).
+ *
+ * When set, the orchestrator's `CostCeilingMonitor` tracks cumulative
+ * agent spend for the task and aborts dispatch on exceed (D6 — abort
+ * is advisory at the turn boundary).
+ */
+interface TaskCostCeiling {
+    /** Hard cap in USD. Cumulative spend > maxUsd fires the abort path. */
+    maxUsd: number;
+    /** Warn threshold expressed as a percentage of `maxUsd` (1–99). */
+    warnAtPct?: number;
+}
+/**
+ * Definition of a maintenance task (built-in or Phase 2 custom).
+ *
+ * Custom-task-only fields (`checkScript`, `inlineSkills`, `inlineSkillsBudgetTokens`,
+ * `contextFrom`, `contextFromMaxAgeMinutes`, `outputRetention`, `isCustom`) are
+ * populated by the scheduler when merging `MaintenanceConfig.customTasks` into the
+ * resolved task list. Built-ins leave them unset and the runner falls through to
+ * the legacy execution paths unchanged.
+ */
+interface TaskDefinition {
+    /** Unique identifier for this task (e.g., 'arch-violations') */
+    id: string;
+    /** Execution strategy */
+    type: TaskType;
+    /** Human-readable description */
+    description: string;
+    /** Default cron expression (e.g., '0 2 * * *' for daily at 2am) */
+    schedule: string;
+    /** Branch name for PRs, or null for report-only/housekeeping tasks */
+    branch: string | null;
+    /** CLI command args for the mechanical check step (mechanical-ai and report-only) */
+    checkCommand?: string[];
+    /** Skill name to dispatch for AI fix (mechanical-ai and pure-ai) */
+    fixSkill?: string;
+    /**
+     * Per-task cost ceiling (Hermes Phase 5). When set, cumulative agent
+     * spend across all turns dispatched for this task is tracked; the
+     * orchestrator aborts dispatch on `maxUsd` exceedance with
+     * `RunResult.error === 'cost_ceiling_exceeded'`. Default: unset = no cap.
+     */
+    costCeiling?: TaskCostCeiling;
+    /**
+     * Hermes Phase 2 — Arbitrary-executable check (replaces `checkCommand`).
+     * Mutually-exclusive with `checkCommand`; validator rejects both.
+     */
+    checkScript?: CheckScriptDefinition;
+    /** Hermes Phase 2 — Skill names whose markdown is inlined into the agent prompt. */
+    inlineSkills?: string[];
+    /** Hermes Phase 2 — Token-budget cap for inlined skills. Default: 8000. */
+    inlineSkillsBudgetTokens?: number;
+    /** Hermes Phase 2 — Upstream task IDs whose latest output feeds prompt context. */
+    contextFrom?: string[];
+    /** Hermes Phase 2 — Max upstream-output age (minutes). Default: 1440. */
+    contextFromMaxAgeMinutes?: number;
+    /** Hermes Phase 2 — Output retention overrides. */
+    outputRetention?: OutputRetentionConfig;
+    /** Hermes Phase 2 — Marks tasks originating from `customTasks` config. */
+    isCustom?: boolean;
+}
 /**
  * Result of a single maintenance task run.
  */
@@ -1126,6 +1310,12 @@ interface RunResult {
      * and `error === 'cost_ceiling_exceeded'`.
      */
     costUsd?: number;
+    /**
+     * Hermes Phase 2 — Provenance tag set by the entry point.
+     * Older orchestrators may emit this field absent; renderers should fall
+     * back to `'—'` rather than crash.
+     */
+    origin?: RunOrigin;
 }
 /**
  * Schedule entry for a single task, used in MaintenanceStatus.
@@ -1167,6 +1357,144 @@ 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.
+ */
+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;
+    /**
+     * 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.
+     */
+    clearListeners(): void;
+}
+
+interface BackendRouterOptions {
+    backends: Record<string, BackendDef>;
+    routing: RoutingConfig;
+    /**
+     * 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.
+     */
+    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);
+    /**
+     * Resolve a {@link RoutingUseCase} to a {@link RoutingDecision}.
+     *
+     * @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)
+     */
+    resolve(useCase: RoutingUseCase, opts?: {
+        invocationOverride?: string;
+    }): RoutingDecision;
+    /**
+     * 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.
+     */
+    resolveDefinition(useCase: RoutingUseCase, opts?: {
+        invocationOverride?: string;
+    }): BackendDef;
+    /**
+     * 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.
+     */
+    resolveDecisionAndDef(useCase: RoutingUseCase, opts?: {
+        invocationOverride?: string;
+    }): {
+        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`.
+     */
+    private resolveExistingUseCase;
+    private validateReferences;
+}
+
+/**
+ * The central orchestrator that manages the lifecycle of coding agents.
+ *
+ * It polls an issue tracker for candidate tasks, manages ephemeral workspaces,
+ * runs agents to resolve issues, and updates the tracker with progress.
+ *
+ * @fires Orchestrator#state_change Emitted when the internal state machine transitions
+ * @fires Orchestrator#agent_event Emitted when an agent produces an output or thought
+ */
 declare class Orchestrator extends EventEmitter {
     private state;
     private config;
@@ -1191,6 +1519,14 @@ declare class Orchestrator extends EventEmitter {
      * construction time. Eliminating this fallback is autopilot Phase 4+.
      */
     private backendFactory;
+    /**
+     * Spec B Phase 4 (D8): per-orchestrator in-process bus for
+     * `RoutingDecision` events. Constructed alongside backendFactory when
+     * agent.backends synthesis succeeds; null when legacy single-backend
+     * config bypassed backends. Phase 5+ consumers (HTTP, WS, dashboard)
+     * subscribe via `getRoutingDecisionBus()`.
+     */
+    private routingDecisionBus;
     /**
      * Test-only: when overrides.backend is provided, dispatch uses this
      * instance directly (bypassing the factory). Mirrors Phase 1
@@ -1213,6 +1549,15 @@ declare class Orchestrator extends EventEmitter {
      * so this map is the single source of truth post-migration.
      */
     private localResolvers;
+    /**
+     * Spec B Phase 3: skill catalog (name + cognitiveMode) read once at
+     * construction from `projectRoot/agents/skills/`. Consulted by
+     * `buildRoutingUseCase` at dispatch start to construct
+     * `{ kind: 'skill', skillName, cognitiveMode }` RoutingUseCases.
+     * Empty when the orchestrator runs outside a harness project root
+     * (then dispatch falls through to per-tier, preserving F11/N2).
+     */
+    private readonly skillCatalog;
     /**
      * Per-resolver `onStatusChange` unsubscribe callbacks. Spec 2 Phase 5
      * (SC39): each local/pi resolver gets its own listener emitting a
@@ -1395,6 +1740,34 @@ declare class Orchestrator extends EventEmitter {
      * Returns a point-in-time snapshot of the orchestrator's internal state.
      */
     getSnapshot(): Record<string, unknown>;
+    /**
+     * Spec B Phase 4 (D8): expose the bus for Phase 5 (HTTP routes) and
+     * Phase 7 (dashboard WS broadcast). Returns null when the legacy
+     * single-backend config bypassed agent.backends synthesis.
+     */
+    getRoutingDecisionBus(): RoutingDecisionBus | null;
+    /**
+     * Spec B Phase 5: live BackendRouter for HTTP routes. The orchestrator
+     * dispatch path uses the factory-owned router directly; observability
+     * routes (config / decisions) reach it through this accessor. Returns
+     * null when the legacy single-backend config bypassed agent.backends
+     * synthesis (no backendFactory built).
+     */
+    getBackendRouter(): BackendRouter | null;
+    /**
+     * Spec B Phase 5: snapshot of the active RoutingConfig for the config
+     * route and the trace route's bus-less router construction. Returns
+     * null when the operator's harness.config.json carries no
+     * `agent.routing` block.
+     */
+    getRoutingConfig(): _harness_engineering_types.RoutingConfig | null;
+    /**
+     * Spec B Phase 5: snapshot of `agent.backends` for the config route
+     * (existence annotations) and the trace route (bus-less router
+     * construction). Returns null when no synthesized backends map exists
+     * (legacy single-backend configs).
+     */
+    getBackends(): Record<string, _harness_engineering_types.BackendDef> | null;
     /** Returns the maintenance scheduler status, or null if maintenance is not enabled. */
     getMaintenanceStatus(): MaintenanceStatus | null;
 }
@@ -1410,47 +1783,6 @@ declare function launchTUI(orchestrator: Orchestrator): {
     waitUntilExit: () => Promise<void>;
 };
 
-interface BackendRouterOptions {
-    backends: Record<string, BackendDef>;
-    routing: RoutingConfig;
-}
-/**
- * BackendRouter
- *
- * Owns the lookup from a `RoutingUseCase` (a discriminated query — tier,
- * intelligence layer, maintenance, chat) to a named backend.
- * Construction-time validation guarantees every name referenced by
- * `routing` is present in `backends` so runtime lookups are total and
- * never throw on unknown-name references (D6/D7).
- *
- * Lookups for tier/intelligence use cases that fall through to undefined
- * mappings return `routing.default` without throwing — this matches the
- * spec's "every use case inherits default unless explicitly routed"
- * semantics. The `maintenance` and `chat` kinds always resolve to
- * `routing.default` (SC19, SC20).
- */
-declare class BackendRouter {
-    private readonly backends;
-    private readonly routing;
-    constructor(opts: BackendRouterOptions);
-    /**
-     * Returns the backend name for a given use case.
-     *
-     * - `tier`: per-tier override, falling back to `routing.default`.
-     * - `intelligence`: per-layer override under `routing.intelligence`,
-     *   falling back to `routing.default`.
-     * - `maintenance` / `chat`: always `routing.default`.
-     */
-    resolve(useCase: RoutingUseCase): string;
-    /**
-     * Returns the BackendDef reference for the resolved name. Returns the
-     * exact reference held in `backends` (no copy) so identity comparisons
-     * succeed (SC21).
-     */
-    resolveDefinition(useCase: RoutingUseCase): BackendDef;
-    private validateReferences;
-}
-
 /**
  * Options for `OrchestratorBackendFactory`.
  *
@@ -1485,6 +1817,11 @@ interface OrchestratorBackendFactoryOptions {
      * `/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;
 }
 /**
  * High-level factory wrapping `BackendRouter` + `createBackend` plus
@@ -1517,8 +1854,19 @@ declare class OrchestratorBackendFactory {
      * is `undefined` for pure-modern configs. Threading the routed name
      * through dispatch eliminates that gap.
      */
-    resolveName(useCase: RoutingUseCase): string;
-    forUseCase(useCase: RoutingUseCase): AgentBackend;
+    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
@@ -1614,6 +1962,147 @@ interface SyncMainOptions {
  */
 declare function syncMain(repoRoot: string, opts?: SyncMainOptions): Promise<SyncMainResult>;
 
+/**
+ * All 21 built-in maintenance task definitions with default schedules.
+ *
+ * Tasks are grouped by type:
+ * - mechanical-ai (7): Run check first, dispatch AI only if fixable issues found
+ * - pure-ai (4): Always dispatch AI agent on schedule
+ * - report-only (7): Run command, record metrics, no PR
+ * - housekeeping (3): Mechanical command, no AI, no PR
+ */
+declare const BUILT_IN_TASKS: readonly TaskDefinition[];
+
+/**
+ * Unified logger interface for all maintenance classes.
+ * Matches StructuredLogger's shape.
+ */
+interface MaintenanceLogger {
+    info(message: string, context?: Record<string, unknown>): void;
+    warn(message: string, context?: Record<string, unknown>): void;
+    error(message: string, context?: Record<string, unknown>): void;
+    debug?(message: string, context?: Record<string, unknown>): void;
+}
+
+/**
+ * Hermes Phase 2 — A single persisted run entry.
+ *
+ * Mirrors `RunResult` plus the captured stdout/stderr, the parsed structured
+ * status envelope (if any), the resolved upstream context that was injected
+ * into the prompt (if any), and the trigger origin.
+ */
+interface PersistedOutputEntry {
+    taskId: string;
+    startedAt: string;
+    completedAt: string;
+    status: RunResult['status'];
+    findings: number;
+    fixed: number;
+    prUrl: string | null;
+    prUpdated: boolean;
+    error?: string;
+    costUsd?: number;
+    origin?: RunOrigin;
+    /** Raw captured stdout from the check step (or housekeeping command). */
+    stdout?: string;
+    /** Raw captured stderr from the check step. */
+    stderr?: string;
+    /** Structured envelope when a JSON status line was parsed; null otherwise. */
+    structured?: Record<string, unknown> | null;
+    /** Resolved upstream-context block, if any. */
+    context?: string;
+}
+interface TaskOutputStoreOptions {
+    /** Root directory under which `<taskId>/outputs/` lives. Default: `.harness/maintenance`. */
+    rootDir: string;
+    /** Default retention bounds applied when a task doesn't specify its own. */
+    retentionDefaults?: Required<OutputRetentionConfig>;
+    logger?: MaintenanceLogger;
+}
+/**
+ * Persists per-task run outputs to disk and applies retention. The store is
+ * intentionally simple: one file per run keyed by completion timestamp, JSON
+ * payload, no SQLite. The chain-context read path (`latest`) and the
+ * dashboard list path (`list`) both consume the same on-disk format.
+ *
+ * Concurrency: `processQueue` already serializes runs of the same task ID,
+ * so the store assumes exclusive write access per task.
+ */
+declare class TaskOutputStore {
+    private rootDir;
+    private retentionDefaults;
+    private logger;
+    constructor(options: TaskOutputStoreOptions);
+    /**
+     * Reject task IDs that don't match the validator's kebab-case pattern —
+     * defends `dirFor()` against caller-supplied path-traversal segments
+     * (`'../foo'`) when the store is invoked from CLI surfaces that don't
+     * round-trip through `validateCustomTasks`.
+     */
+    private ensureSafeTaskId;
+    /**
+     * Persist a single run entry. Retention is applied after the write so
+     * the latest record is durable even if pruning fails.
+     */
+    write(taskId: string, entry: PersistedOutputEntry, retention?: OutputRetentionConfig): Promise<void>;
+    /**
+     * Return the most recent persisted entry for the task, or null if none.
+     */
+    latest(taskId: string): Promise<PersistedOutputEntry | null>;
+    /**
+     * List entries newest-first with offset+limit pagination.
+     */
+    list(taskId: string, limit: number, offset: number): Promise<PersistedOutputEntry[]>;
+    /**
+     * Lookup a specific run by its file name (without the `.json` suffix) or
+     * by its raw completion timestamp.
+     */
+    get(taskId: string, runId: string): Promise<PersistedOutputEntry | null>;
+    /**
+     * The on-disk root for a given task. Exposed for tooling that needs to walk
+     * outputs from outside the store API.
+     */
+    dirFor(taskId: string): string;
+    private readEntry;
+    private applyRetention;
+}
+
+/**
+ * Hermes Phase 2 — Validation errors surfaced by `validateCustomTasks`.
+ *
+ * `path` always begins with `customTasks.<taskId>` so the caller can render
+ * it directly without re-prefixing. Multiple errors may be returned in a
+ * single call; the validator does not short-circuit on the first failure.
+ */
+interface CustomTaskValidationError {
+    path: string;
+    message: string;
+}
+interface CustomTaskValidatorDeps {
+    /** Returns true if a skill with this name exists in the project's registry. */
+    skillExists?: (name: string) => boolean;
+    /** Returns true if the executable referenced by a checkScript.path exists. */
+    scriptExists?: (path: string) => boolean;
+}
+/**
+ * Validates a `MaintenanceConfig.customTasks` map.
+ *
+ * Checks:
+ *  - kebab-case task IDs (matching the BUILT_IN_TASKS convention)
+ *  - no collision with built-in IDs
+ *  - per-type required fields (e.g., mechanical-ai must have `branch` + `fixSkill`)
+ *  - exactly one of `checkCommand` / `checkScript` for types that need a check step
+ *  - `contextFrom` cycle detection across the merged graph (built-ins + customs)
+ *  - `contextFrom` entries reference existing task IDs
+ *  - `inlineSkills` entries exist in the skill registry (when `skillExists` is provided)
+ *  - `checkScript.path` exists on disk (when `scriptExists` is provided)
+ *
+ * Returns `Ok(void)` when all custom tasks pass; otherwise an `Err` carrying
+ * every distinct violation. The validator is pure: no I/O outside the
+ * injected predicates.
+ */
+declare function validateCustomTasks(customTasks: Record<string, CustomTaskDefinition> | undefined, builtIns: readonly TaskDefinition[], deps?: CustomTaskValidatorDeps): Result<void, CustomTaskValidationError[]>;
+
 interface CreateTokenInput {
     name: string;
     scopes: TokenScope[];
@@ -1980,4 +2469,87 @@ interface WireParams {
 }
 declare function wireNotificationSinks({ bus, registry }: WireParams): () => void;
 
-export { type AgentUpdateEvent, AnalysisArchive, type AnalysisRecord, type ApplyEventResult, type ArtifactPresence, type AttemptStats, BackendRouter, type BackendRouterOptions, type BaseRefFallbackEvent, type BuildArchiveHooksOptions, ClaimManager, type ClaimManagerConfig, type CleanWorkspaceEffect, type CreateTokenInput, type CreateTokenResult, type DispatchEffect, type EmitLogEffect, type EscalateEffect, type ExecFileFn$1 as ExecFileFn, type FromConfigOptions, type Highlight, type HighlightsInfo, type IndexedDoc, InteractionQueue, type LinearGraphQLExtension, LinearGraphQLStub, type LiveSession, MAX_ATTEMPTS, type MigrationResult, MockBackend, type NotificationSink, type NotificationSinkDeliverInput, ORCHESTRATOR_IDENTITY_FILE, Orchestrator, OrchestratorBackendFactory, type OrchestratorBackendFactoryOptions, type OrchestratorContext, type OrchestratorEvent, type OrchestratorState, PRDetector, type PRDetectorLogger, type PendingInteraction, PromptRenderer, 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 RetryEntry, type RetryFiredEvent, RoadmapTrackerAdapter, type RunAttemptPhase, type RunningEntry, type ScheduleRetryEffect, type SearchOptions, type SideEffect, SinkConfigError, SinkRegistry, SlackSink, type SlackSinkOptions, SqliteSearchIndex, type StallDetectedEvent, type StopEffect, type StreamManifest, StreamRecorder, type SummarizeContext, type SummarizeResult, type SyncMainOptions, type SyncMainResult, type SyncSkipReason, type TickEvent, TokenStore, type TokenTotals, type TriageConfig, type TriageDecision, type TriageSignals, type TriageSkill, type UpdateTokensEffect, WebhookQueue, type WorkerExitEvent, WorkflowLoader, WorkspaceHooks, WorkspaceManager, type WorkspaceManagerOptions, applyEvent, artifactPresenceFromIssue, buildArchiveHooks, calculateRetryDelay, canDispatch, computeRateLimitDelay, createBackend, createEmptyState, detectScopeTier, extractHighlights, extractTitlePrefix, getAvailableSlots, getDefaultConfig, getPerStateCount, indexSessionDirectory, isEligible, isSummaryEnabled, launchTUI, loadPublishedIndex, migrateAgentConfig, normalizeFts5Query, openSearchIndex, reconcile, reindexFromArchive, renderAnalysisComment, renderLlmSummaryMarkdown, renderPRComment, resolveEscalationConfig, resolveOrchestratorId, routeIssue, savePublishedIndex, searchIndexPath, selectCandidates, sortCandidates, summarizeArchivedSession, syncMain, triageIssue, truncateForBudget, validateWorkflowConfig, wireNotificationSinks, wrapAsEnvelope };
+/**
+ * Phase 4 gate (degraded mode, see spec D5).
+ *
+ * The full design calls for `harness skill run harness-soundness-review
+ * --mode skill` against materialized proposal content. The skill-mode check
+ * vocabulary is not yet designed; its design is the explicit follow-up spec
+ * referenced in Phase 4's Non-goals.
+ *
+ * In v1 we run a small set of mechanical checks inline against the proposal
+ * payload. They cover the obvious structural failures (unparseable YAML,
+ * empty markdown, name/regex drift) without needing an LLM. The result
+ * shape mirrors the eventual soundness-review output so the downstream
+ * promote step (and dashboard panel) does not need to change when
+ * skill-mode lands.
+ */
+declare class GateRunError extends Error {
+    constructor(message: string);
+}
+interface GateResult {
+    proposalId: string;
+    status: SkillProposal['status'];
+    findings: ProposalGateFinding[];
+    runAt: string;
+}
+/**
+ * Synchronously run the gate against the given proposal. The proposal is
+ * read from disk, checks are computed, and the proposal JSON is patched
+ * with the gate result. Returns the post-update gate snapshot for the
+ * caller to render.
+ */
+declare function runGate(projectPath: string, proposalId: string): Promise<GateResult>;
+
+declare class GateNotReadyError extends Error {
+    constructor(message: string);
+}
+declare class PromotionError extends Error {
+    constructor(message: string);
+}
+interface PromotionResult {
+    proposalId: string;
+    skillPath: string;
+    /** Provenance field stamped onto the promoted skill. */
+    provenance: 'agent-proposed';
+}
+/**
+ * Promote a proposal to the skill catalog. Caller is responsible for
+ * emitting `proposal.approved` after a successful return.
+ */
+declare function promote(projectPath: string, proposalId: string, decidedBy: string): Promise<PromotionResult>;
+
+/**
+ * Phase 4 — thin wrappers around the orchestrator event bus that emit the
+ * three `proposal.*` lifecycle events with a stable, validated payload
+ * shape. Both the webhook fan-out (gateway/webhooks/events.ts) and the
+ * in-process notification dispatcher (notifications/events.ts) subscribe
+ * to these topics; their envelope derivers know the field names below.
+ */
+interface ProposalCreatedData {
+    id: string;
+    kind: SkillProposal['kind'];
+    name: string;
+    targetSkill?: string;
+    proposedBy: string;
+    justification: string;
+}
+interface ProposalApprovedData {
+    id: string;
+    kind: SkillProposal['kind'];
+    name: string;
+    targetSkill?: string;
+    decidedBy: string;
+}
+interface ProposalRejectedData {
+    id: string;
+    kind: SkillProposal['kind'];
+    name: string;
+    decidedBy: string;
+    reason: string;
+}
+declare function emitProposalCreated(bus: EventEmitter, proposal: SkillProposal): void;
+declare function emitProposalApproved(bus: EventEmitter, proposal: SkillProposal): void;
+declare function emitProposalRejected(bus: EventEmitter, proposal: SkillProposal): void;
+
+export { type AgentUpdateEvent, AnalysisArchive, type AnalysisRecord, type ApplyEventResult, type ArtifactPresence, type AttemptStats, BUILT_IN_TASKS, BackendRouter, type BackendRouterOptions, type BaseRefFallbackEvent, type BuildArchiveHooksOptions, ClaimManager, type ClaimManagerConfig, type CleanWorkspaceEffect, type CreateTokenInput, type CreateTokenResult, type CustomTaskValidationError, type DispatchEffect, type EmitLogEffect, type EscalateEffect, type ExecFileFn$1 as ExecFileFn, type FromConfigOptions, GateNotReadyError, type GateResult, GateRunError, type Highlight, type HighlightsInfo, type IndexedDoc, InteractionQueue, type LinearGraphQLExtension, LinearGraphQLStub, type LiveSession, MAX_ATTEMPTS, type MigrationResult, MockBackend, type NotificationSink, type NotificationSinkDeliverInput, ORCHESTRATOR_IDENTITY_FILE, Orchestrator, OrchestratorBackendFactory, type OrchestratorBackendFactoryOptions, type OrchestratorContext, type OrchestratorEvent, type OrchestratorState, PRDetector, type PRDetectorLogger, 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 RetryEntry, type RetryFiredEvent, RoadmapTrackerAdapter, type RunAttemptPhase, type RunOrigin, 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, 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, computeRateLimitDelay, createBackend, createEmptyState, crossFieldRoutingIssues, detectScopeTier, discoverSkillCatalog, discoverSkillCatalogNames, emitProposalApproved, emitProposalCreated, emitProposalRejected, extractHighlights, extractTitlePrefix, getAvailableSlots, getDefaultConfig, getPerStateCount, indexSessionDirectory, isEligible, isSummaryEnabled, launchTUI, loadPublishedIndex, migrateAgentConfig, normalizeFts5Query, openSearchIndex, promote, reconcile, reindexFromArchive, renderAnalysisComment, renderLlmSummaryMarkdown, renderPRComment, resolveEscalationConfig, resolveOrchestratorId, routeIssue, routingWarnings, runGate, savePublishedIndex, searchIndexPath, selectCandidates, sortCandidates, summarizeArchivedSession, syncMain, triageIssue, truncateForBudget, validateCustomTasks, validateWorkflowConfig, wireNotificationSinks, wrapAsEnvelope };