@harness-engineering/orchestrator 0.3.2 → 0.4.1

package/dist/index.d.mts

@@ -1,4 +1,5 @@
-import { Issue, AgentEvent, WorkflowConfig, IssueTrackerClient, TokenUsage, ConcernSignal, ScopeTier, EscalationConfig, RoutingDecision, Result, WorkflowDefinition, TrackerConfig, WorkspaceConfig, HooksConfig, AgentBackend, SessionStartParams, AgentSession, AgentError, TurnParams, TurnResult, BackendDef, RoutingConfig, RoutingUseCase, ContainerConfig, SecretConfig, AgentConfig } from '@harness-engineering/types';
+import { Issue, AgentEvent, WorkflowConfig, TokenUsage, ConcernSignal, ScopeTier, EscalationConfig, RoutingDecision, Result, WorkflowDefinition, WorkspaceConfig, HooksConfig, AgentBackend, SessionStartParams, AgentSession, AgentError, TurnParams, TurnResult, BackendDef, RoutingConfig, RoutingUseCase, ContainerConfig, SecretConfig, AgentConfig } from '@harness-engineering/types';
+import { IssueTrackerClient, Issue as Issue$1, TrackerConfig } from '@harness-engineering/core';
 import { EnrichedSpec, ComplexityScore, SimulationResult, IntelligencePipeline, WeightedRecommendation } from '@harness-engineering/intelligence';
 import { GraphStore } from '@harness-engineering/graph';
 import { execFile } from 'node:child_process';
@@ -243,7 +244,7 @@ interface PRDetectorLogger {
  * Function signature compatible with Node's `child_process.execFile`.
  * Allows injection for testing.
  */
-type ExecFileFn = typeof execFile;
+type ExecFileFn$1 = typeof execFile;
 /**
  * Detects whether GitHub issues or branches already have open pull requests.
  *
@@ -257,7 +258,7 @@ declare class PRDetector {
     private projectRoot;
     constructor(opts: {
         logger: PRDetectorLogger;
-        execFileFn?: ExecFileFn;
+        execFileFn?: ExecFileFn$1;
         projectRoot: string;
     });
     /**
@@ -830,7 +831,7 @@ declare class ClaimManager {
      * Returns true if the claim should be considered expired (the
      * owning orchestrator may have crashed).
      */
-    isStale(issue: Issue, ttlMs: number): boolean;
+    isStale(issue: Issue$1, ttlMs: number): boolean;
     /**
      * Scans the tracker for "in-progress" issues assigned to this orchestrator
      * and releases any that are not currently running in memory.
@@ -878,13 +879,13 @@ declare class RoadmapTrackerAdapter implements IssueTrackerClient {
     /**
      * Fetches all issues that are in an "active" state according to the config.
      */
-    fetchCandidateIssues(): Promise<Result<Issue[], Error>>;
+    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[], Error>>;
+    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
@@ -912,7 +913,7 @@ declare class RoadmapTrackerAdapter implements IssueTrackerClient {
      *
      * @param issueIds - List of issue IDs to fetch
      */
-    fetchIssueStatesByIds(issueIds: string[]): Promise<Result<Map<string, Issue>, Error>>;
+    fetchIssueStatesByIds(issueIds: string[]): Promise<Result<Map<string, Issue$1>, Error>>;
     /**
      * Maps a raw RoadmapFeature from the parser to the unified Issue model.
      */
@@ -934,11 +935,35 @@ declare class LinearGraphQLStub implements LinearGraphQLExtension {
     query(query: string, _variables?: Record<string, unknown>): Promise<Result<unknown, Error>>;
 }
 
+/**
+ * Structured event emitted when {@link WorkspaceManager.resolveBaseRef}
+ * falls back past `origin/HEAD` and `origin/main`/`origin/master` to a
+ * local-only ref. Operators see this in the dashboard's maintenance
+ * event stream when the remote is misconfigured or unreachable.
+ */
+interface BaseRefFallbackEvent {
+    kind: 'baseref_fallback';
+    /** The ref that was selected — `'main'`, `'master'`, or `'HEAD'`. */
+    ref: string;
+    /** Absolute path to the git repository root. */
+    repoRoot: string;
+}
+/** Optional dependencies injected into {@link WorkspaceManager}. */
+interface WorkspaceManagerOptions {
+    /**
+     * Synchronous fire-and-forget callback invoked when {@link
+     * WorkspaceManager.resolveBaseRef} falls back to a local-only ref.
+     * When omitted, fallback emission is silently skipped.
+     */
+    emitEvent?: (event: BaseRefFallbackEvent) => void;
+}
 declare class WorkspaceManager {
     private config;
     /** Absolute path to the git repository root (resolved lazily). */
     private repoRoot;
-    constructor(config: WorkspaceConfig);
+    /** Phase 3 (D6): emit baseref_fallback when fallback chain selects a local-only ref. */
+    private emitEvent;
+    constructor(config: WorkspaceConfig, options?: WorkspaceManagerOptions);
     /** Runs a git command and returns stdout. Extracted for testability. */
     protected git(args: string[], cwd: string): Promise<string>;
     /**
@@ -970,11 +995,22 @@ declare class WorkspaceManager {
      * Priority order:
      *   1. `config.baseRef` (explicit override). Throws if it doesn't resolve.
      *   2. Default branch via `git symbolic-ref --short refs/remotes/origin/HEAD`.
-     *   3. Common fallbacks: `origin/main`, `origin/master`, `main`, `master`.
-     *   4. `HEAD` as an ultimate fallback (preserves old behavior for unusual
-     *      repos without any of the above).
+     *   3. Remote fallbacks: `origin/main`, `origin/master`. (No event.)
+     *   4. Local-only fallbacks: `main`, `master`. (Emits `baseref_fallback`.)
+     *   5. `HEAD` as ultimate fallback. (Emits `baseref_fallback`.)
+     *
+     * Phase 3 / spec D6 / R4: when the priority chain falls past `origin/*`
+     * to a local-only ref, the optional `emitEvent` callback (if injected)
+     * is invoked exactly once with `{ kind: 'baseref_fallback', ref, repoRoot }`
+     * so operators are warned when the remote is misconfigured or unreachable.
      */
     private resolveBaseRef;
+    /**
+     * Phase 3 (D6): emit a `baseref_fallback` event via the injected
+     * callback (if any). Errors from the callback are swallowed so a
+     * broken emitter does not block worktree dispatch.
+     */
+    private emitFallback;
     /** Returns true iff `git rev-parse --verify` accepts the ref. */
     private refExists;
     /**
@@ -1040,6 +1076,19 @@ declare class PromptRenderer {
     render(template: string, context: Record<string, unknown>): Promise<string>;
 }
 
+/**
+ * Internal types for the maintenance module.
+ * Public config types (MaintenanceConfig, TaskOverride) live in @harness-engineering/types.
+ */
+/**
+ * Classification of maintenance task execution strategy.
+ *
+ * - mechanical-ai: Run a check command first; dispatch AI agent only if fixable issues are found.
+ * - pure-ai: Always dispatch an AI agent on schedule regardless of preconditions.
+ * - report-only: Run a command and record metrics; never create branches or PRs.
+ * - housekeeping: Run a mechanical command directly; no AI, no PR.
+ */
+type TaskType = 'mechanical-ai' | 'pure-ai' | 'report-only' | 'housekeeping';
 /**
  * Result of a single maintenance task run.
  */
@@ -1069,6 +1118,16 @@ interface RunResult {
 interface ScheduleEntry {
     /** Task identifier */
     taskId: string;
+    /**
+     * Task type (mechanical-ai | pure-ai | report-only | housekeeping).
+     *
+     * Optional on the WIRE shape so that a newer dashboard rendering data from
+     * an older orchestrator (which did not yet emit this field) does not
+     * produce empty cells of unknown semantics. The current orchestrator
+     * always populates this field via `MaintenanceScheduler.getStatus()`.
+     * Newer dashboards must render `row.type ?? '—'` (or similar fallback).
+     */
+    type?: TaskType;
     /** ISO timestamp of the next scheduled run */
     nextRun: string;
     /** Result of the most recent run, or null if never run */
@@ -1184,7 +1243,7 @@ declare class Orchestrator extends EventEmitter {
     constructor(config: WorkflowConfig, promptTemplate: string, overrides?: {
         tracker?: IssueTrackerClient;
         backend?: AgentBackend;
-        execFileFn?: ExecFileFn;
+        execFileFn?: ExecFileFn$1;
     });
     private createTracker;
     /**
@@ -1199,35 +1258,6 @@ declare class Orchestrator extends EventEmitter {
      */
     private initMaintenance;
     private createIntelligencePipeline;
-    /**
-     * Create the AnalysisProvider for an intelligence-pipeline layer
-     * (`sel` by default; `pesl` when constructing a distinct PESL
-     * provider per Spec 2 SC35).
-     *
-     * Spec 2 Phase 4 (SC31–SC36) — resolution order:
-     *   1. Explicit `intelligence.provider` config wins (preserves Phase 0–3 behavior; SC33).
-     *   2. Otherwise, consult `agent.routing.intelligence.<layer>` (or
-     *      `routing.default`) to pick a `BackendDef` from `agent.backends`,
-     *      then translate via `buildAnalysisProvider` (the per-type factory).
-     *
-     * Closes the Phase 2 deferral (P2-DEF-638): the legacy
-     * `this.config.agent.backend` read at the bottom of this method is
-     * removed; routing is the sole source for non-explicit configs.
-     *
-     * Cyclomatic complexity: pre-Phase-4 was 33 (factory dispatch was
-     * inlined here). Phase 4 extracts the per-type tree into
-     * `buildAnalysisProvider`, dropping this method to ≤ 5 branches
-     * (under the 15 threshold).
-     */
-    private createAnalysisProvider;
-    /**
-     * Look up the routed BackendDef for an intelligence layer, falling
-     * back through `routing.intelligence.<layer>` → `routing.default`
-     * → null. Returns the resolved name alongside the def so callers can
-     * key into the per-name resolver map.
-     */
-    private resolveRoutedBackendForIntelligence;
-    private createProviderFromExplicitConfig;
     /**
      * Lazily initializes the ClaimManager if it hasn't been created yet.
      * Called from both start() and asyncTick() to avoid duplicating the init block.
@@ -1309,7 +1339,7 @@ declare class Orchestrator extends EventEmitter {
      * Dispatch a work item immediately, bypassing the normal tick → roadmap cycle.
      * Used by the dashboard's "Dispatch Now" action.
      */
-    dispatchAdHoc(issue: Issue): Promise<void>;
+    dispatchAdHoc(issue: Issue$1): Promise<void>;
     /**
      * Initialize the LocalModelResolver and intelligence pipeline.
      *
@@ -1481,29 +1511,6 @@ interface MigrationResult {
     config: AgentConfig;
     warnings: string[];
 }
-/**
- * Translate legacy `agent.backend` / `agent.localBackend` /
- * `agent.escalation.autoExecute` into the new `agent.backends` +
- * `agent.routing` shape (Spec 2 D3, D4, D8, D11).
- *
- * Behavior matrix:
- * - `agent.backends` already set, no legacy fields:
- *     no-op; returns input config unchanged, warnings = [].
- * - `agent.backends` already set + at least one legacy field:
- *     no-op on config; warnings name each ignored legacy field (D4).
- * - No `agent.backends`, at least one of `agent.backend` /
- *   `agent.localBackend` / `agent.localEndpoint` / etc. set:
- *     synthesize `backends.primary` (always, from `agent.backend`)
- *     and `backends.local` (when `localBackend` is set), plus a
- *     `routing` map driven by `escalation.autoExecute` (D3).
- * - No `agent.backends`, no legacy fields:
- *     no-op; the caller's downstream Zod validation surfaces the gap
- *     as a missing-required-field error.
- *
- * Throws on internal inconsistencies (e.g., `agent.backend = 'pi'`
- * with no `localEndpoint`/`localModel`) — these are user-config bugs
- * that would have produced a runtime crash today.
- */
 declare function migrateAgentConfig(agent: AgentConfig): MigrationResult;
 
 /**
@@ -1513,4 +1520,45 @@ declare function migrateAgentConfig(agent: AgentConfig): MigrationResult;
  */
 declare function createBackend(def: BackendDef): AgentBackend;
 
-export { type AgentUpdateEvent, AnalysisArchive, type AnalysisRecord, type ApplyEventResult, type ArtifactPresence, type AttemptStats, BackendRouter, type BackendRouterOptions, ClaimManager, type ClaimManagerConfig, type CleanWorkspaceEffect, type DispatchEffect, type EmitLogEffect, type EscalateEffect, type ExecFileFn, type Highlight, type HighlightsInfo, InteractionQueue, type LinearGraphQLExtension, LinearGraphQLStub, type LiveSession, type MigrationResult, MockBackend, ORCHESTRATOR_IDENTITY_FILE, Orchestrator, OrchestratorBackendFactory, type OrchestratorBackendFactoryOptions, type OrchestratorContext, type OrchestratorEvent, type OrchestratorState, PRDetector, type PRDetectorLogger, type PendingInteraction, PromptRenderer, type PublishedIndex, type RateLimitSnapshot as RateLimitComputeSnapshot, type RateLimitConfig, type RateLimitSnapshot$1 as RateLimitSnapshot, type ReleaseClaimEffect, type RetryEntry, type RetryFiredEvent, RoadmapTrackerAdapter, type RunAttemptPhase, type RunningEntry, type ScheduleRetryEffect, type SideEffect, type StallDetectedEvent, type StopEffect, type StreamManifest, StreamRecorder, type TickEvent, type TokenTotals, type TriageConfig, type TriageDecision, type TriageSignals, type TriageSkill, type UpdateTokensEffect, type WorkerExitEvent, WorkflowLoader, WorkspaceHooks, WorkspaceManager, applyEvent, artifactPresenceFromIssue, calculateRetryDelay, canDispatch, computeRateLimitDelay, createBackend, createEmptyState, detectScopeTier, extractHighlights, extractTitlePrefix, getAvailableSlots, getDefaultConfig, getPerStateCount, isEligible, launchTUI, loadPublishedIndex, migrateAgentConfig, reconcile, renderAnalysisComment, renderPRComment, resolveEscalationConfig, resolveOrchestratorId, routeIssue, savePublishedIndex, selectCandidates, sortCandidates, triageIssue, validateWorkflowConfig };
+/**
+ * Function signature compatible with Node's `child_process.execFile`.
+ * Allows injection for testing.
+ */
+type ExecFileFn = typeof execFile;
+/** Reasons `syncMain()` declines to fast-forward (none of which are failures). */
+type SyncSkipReason = 'wrong-branch' | 'diverged' | 'dirty-conflict' | 'no-remote' | 'fetch-failed';
+/** Total result type for `syncMain()`. Discriminated by `status`. */
+type SyncMainResult = {
+    status: 'updated';
+    from: string;
+    to: string;
+    defaultBranch: string;
+} | {
+    status: 'no-op';
+    defaultBranch: string;
+} | {
+    status: 'skipped';
+    reason: SyncSkipReason;
+    detail: string;
+    defaultBranch: string;
+} | {
+    status: 'error';
+    message: string;
+};
+/** Options accepted by `syncMain()`. */
+interface SyncMainOptions {
+    /** Override the `git` runner; defaults to `node:child_process.execFile`. */
+    execFileFn?: ExecFileFn;
+    /** Per-git-call timeout in ms. Defaults to 60_000ms. */
+    timeoutMs?: number;
+}
+/**
+ * Fast-forward the local default branch from `origin/<default>` if it can be
+ * done safely. This function is total: it never throws under expected
+ * conditions. Even unexpected errors are caught and converted to
+ * `{ status: 'error', message }` so the maintenance scheduler does not back
+ * off on transient git issues.
+ */
+declare function syncMain(repoRoot: string, opts?: SyncMainOptions): Promise<SyncMainResult>;
+
+export { type AgentUpdateEvent, AnalysisArchive, type AnalysisRecord, type ApplyEventResult, type ArtifactPresence, type AttemptStats, BackendRouter, type BackendRouterOptions, type BaseRefFallbackEvent, ClaimManager, type ClaimManagerConfig, type CleanWorkspaceEffect, type DispatchEffect, type EmitLogEffect, type EscalateEffect, type ExecFileFn$1 as ExecFileFn, type Highlight, type HighlightsInfo, InteractionQueue, type LinearGraphQLExtension, LinearGraphQLStub, type LiveSession, type MigrationResult, MockBackend, ORCHESTRATOR_IDENTITY_FILE, Orchestrator, OrchestratorBackendFactory, type OrchestratorBackendFactoryOptions, type OrchestratorContext, type OrchestratorEvent, type OrchestratorState, PRDetector, type PRDetectorLogger, type PendingInteraction, PromptRenderer, type PublishedIndex, type RateLimitSnapshot as RateLimitComputeSnapshot, type RateLimitConfig, type RateLimitSnapshot$1 as RateLimitSnapshot, type ReleaseClaimEffect, type RetryEntry, type RetryFiredEvent, RoadmapTrackerAdapter, type RunAttemptPhase, type RunningEntry, type ScheduleRetryEffect, type SideEffect, type StallDetectedEvent, type StopEffect, type StreamManifest, StreamRecorder, type SyncMainOptions, type SyncMainResult, type SyncSkipReason, type TickEvent, type TokenTotals, type TriageConfig, type TriageDecision, type TriageSignals, type TriageSkill, type UpdateTokensEffect, type WorkerExitEvent, WorkflowLoader, WorkspaceHooks, WorkspaceManager, type WorkspaceManagerOptions, applyEvent, artifactPresenceFromIssue, calculateRetryDelay, canDispatch, computeRateLimitDelay, createBackend, createEmptyState, detectScopeTier, extractHighlights, extractTitlePrefix, getAvailableSlots, getDefaultConfig, getPerStateCount, isEligible, launchTUI, loadPublishedIndex, migrateAgentConfig, reconcile, renderAnalysisComment, renderPRComment, resolveEscalationConfig, resolveOrchestratorId, routeIssue, savePublishedIndex, selectCandidates, sortCandidates, syncMain, triageIssue, validateWorkflowConfig };

package/dist/index.d.ts

@@ -1,4 +1,5 @@
-import { Issue, AgentEvent, WorkflowConfig, IssueTrackerClient, TokenUsage, ConcernSignal, ScopeTier, EscalationConfig, RoutingDecision, Result, WorkflowDefinition, TrackerConfig, WorkspaceConfig, HooksConfig, AgentBackend, SessionStartParams, AgentSession, AgentError, TurnParams, TurnResult, BackendDef, RoutingConfig, RoutingUseCase, ContainerConfig, SecretConfig, AgentConfig } from '@harness-engineering/types';
+import { Issue, AgentEvent, WorkflowConfig, TokenUsage, ConcernSignal, ScopeTier, EscalationConfig, RoutingDecision, Result, WorkflowDefinition, WorkspaceConfig, HooksConfig, AgentBackend, SessionStartParams, AgentSession, AgentError, TurnParams, TurnResult, BackendDef, RoutingConfig, RoutingUseCase, ContainerConfig, SecretConfig, AgentConfig } from '@harness-engineering/types';
+import { IssueTrackerClient, Issue as Issue$1, TrackerConfig } from '@harness-engineering/core';
 import { EnrichedSpec, ComplexityScore, SimulationResult, IntelligencePipeline, WeightedRecommendation } from '@harness-engineering/intelligence';
 import { GraphStore } from '@harness-engineering/graph';
 import { execFile } from 'node:child_process';
@@ -243,7 +244,7 @@ interface PRDetectorLogger {
  * Function signature compatible with Node's `child_process.execFile`.
  * Allows injection for testing.
  */
-type ExecFileFn = typeof execFile;
+type ExecFileFn$1 = typeof execFile;
 /**
  * Detects whether GitHub issues or branches already have open pull requests.
  *
@@ -257,7 +258,7 @@ declare class PRDetector {
     private projectRoot;
     constructor(opts: {
         logger: PRDetectorLogger;
-        execFileFn?: ExecFileFn;
+        execFileFn?: ExecFileFn$1;
         projectRoot: string;
     });
     /**
@@ -830,7 +831,7 @@ declare class ClaimManager {
      * Returns true if the claim should be considered expired (the
      * owning orchestrator may have crashed).
      */
-    isStale(issue: Issue, ttlMs: number): boolean;
+    isStale(issue: Issue$1, ttlMs: number): boolean;
     /**
      * Scans the tracker for "in-progress" issues assigned to this orchestrator
      * and releases any that are not currently running in memory.
@@ -878,13 +879,13 @@ declare class RoadmapTrackerAdapter implements IssueTrackerClient {
     /**
      * Fetches all issues that are in an "active" state according to the config.
      */
-    fetchCandidateIssues(): Promise<Result<Issue[], Error>>;
+    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[], Error>>;
+    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
@@ -912,7 +913,7 @@ declare class RoadmapTrackerAdapter implements IssueTrackerClient {
      *
      * @param issueIds - List of issue IDs to fetch
      */
-    fetchIssueStatesByIds(issueIds: string[]): Promise<Result<Map<string, Issue>, Error>>;
+    fetchIssueStatesByIds(issueIds: string[]): Promise<Result<Map<string, Issue$1>, Error>>;
     /**
      * Maps a raw RoadmapFeature from the parser to the unified Issue model.
      */
@@ -934,11 +935,35 @@ declare class LinearGraphQLStub implements LinearGraphQLExtension {
     query(query: string, _variables?: Record<string, unknown>): Promise<Result<unknown, Error>>;
 }
 
+/**
+ * Structured event emitted when {@link WorkspaceManager.resolveBaseRef}
+ * falls back past `origin/HEAD` and `origin/main`/`origin/master` to a
+ * local-only ref. Operators see this in the dashboard's maintenance
+ * event stream when the remote is misconfigured or unreachable.
+ */
+interface BaseRefFallbackEvent {
+    kind: 'baseref_fallback';
+    /** The ref that was selected — `'main'`, `'master'`, or `'HEAD'`. */
+    ref: string;
+    /** Absolute path to the git repository root. */
+    repoRoot: string;
+}
+/** Optional dependencies injected into {@link WorkspaceManager}. */
+interface WorkspaceManagerOptions {
+    /**
+     * Synchronous fire-and-forget callback invoked when {@link
+     * WorkspaceManager.resolveBaseRef} falls back to a local-only ref.
+     * When omitted, fallback emission is silently skipped.
+     */
+    emitEvent?: (event: BaseRefFallbackEvent) => void;
+}
 declare class WorkspaceManager {
     private config;
     /** Absolute path to the git repository root (resolved lazily). */
     private repoRoot;
-    constructor(config: WorkspaceConfig);
+    /** Phase 3 (D6): emit baseref_fallback when fallback chain selects a local-only ref. */
+    private emitEvent;
+    constructor(config: WorkspaceConfig, options?: WorkspaceManagerOptions);
     /** Runs a git command and returns stdout. Extracted for testability. */
     protected git(args: string[], cwd: string): Promise<string>;
     /**
@@ -970,11 +995,22 @@ declare class WorkspaceManager {
      * Priority order:
      *   1. `config.baseRef` (explicit override). Throws if it doesn't resolve.
      *   2. Default branch via `git symbolic-ref --short refs/remotes/origin/HEAD`.
-     *   3. Common fallbacks: `origin/main`, `origin/master`, `main`, `master`.
-     *   4. `HEAD` as an ultimate fallback (preserves old behavior for unusual
-     *      repos without any of the above).
+     *   3. Remote fallbacks: `origin/main`, `origin/master`. (No event.)
+     *   4. Local-only fallbacks: `main`, `master`. (Emits `baseref_fallback`.)
+     *   5. `HEAD` as ultimate fallback. (Emits `baseref_fallback`.)
+     *
+     * Phase 3 / spec D6 / R4: when the priority chain falls past `origin/*`
+     * to a local-only ref, the optional `emitEvent` callback (if injected)
+     * is invoked exactly once with `{ kind: 'baseref_fallback', ref, repoRoot }`
+     * so operators are warned when the remote is misconfigured or unreachable.
      */
     private resolveBaseRef;
+    /**
+     * Phase 3 (D6): emit a `baseref_fallback` event via the injected
+     * callback (if any). Errors from the callback are swallowed so a
+     * broken emitter does not block worktree dispatch.
+     */
+    private emitFallback;
     /** Returns true iff `git rev-parse --verify` accepts the ref. */
     private refExists;
     /**
@@ -1040,6 +1076,19 @@ declare class PromptRenderer {
     render(template: string, context: Record<string, unknown>): Promise<string>;
 }
 
+/**
+ * Internal types for the maintenance module.
+ * Public config types (MaintenanceConfig, TaskOverride) live in @harness-engineering/types.
+ */
+/**
+ * Classification of maintenance task execution strategy.
+ *
+ * - mechanical-ai: Run a check command first; dispatch AI agent only if fixable issues are found.
+ * - pure-ai: Always dispatch an AI agent on schedule regardless of preconditions.
+ * - report-only: Run a command and record metrics; never create branches or PRs.
+ * - housekeeping: Run a mechanical command directly; no AI, no PR.
+ */
+type TaskType = 'mechanical-ai' | 'pure-ai' | 'report-only' | 'housekeeping';
 /**
  * Result of a single maintenance task run.
  */
@@ -1069,6 +1118,16 @@ interface RunResult {
 interface ScheduleEntry {
     /** Task identifier */
     taskId: string;
+    /**
+     * Task type (mechanical-ai | pure-ai | report-only | housekeeping).
+     *
+     * Optional on the WIRE shape so that a newer dashboard rendering data from
+     * an older orchestrator (which did not yet emit this field) does not
+     * produce empty cells of unknown semantics. The current orchestrator
+     * always populates this field via `MaintenanceScheduler.getStatus()`.
+     * Newer dashboards must render `row.type ?? '—'` (or similar fallback).
+     */
+    type?: TaskType;
     /** ISO timestamp of the next scheduled run */
     nextRun: string;
     /** Result of the most recent run, or null if never run */
@@ -1184,7 +1243,7 @@ declare class Orchestrator extends EventEmitter {
     constructor(config: WorkflowConfig, promptTemplate: string, overrides?: {
         tracker?: IssueTrackerClient;
         backend?: AgentBackend;
-        execFileFn?: ExecFileFn;
+        execFileFn?: ExecFileFn$1;
     });
     private createTracker;
     /**
@@ -1199,35 +1258,6 @@ declare class Orchestrator extends EventEmitter {
      */
     private initMaintenance;
     private createIntelligencePipeline;
-    /**
-     * Create the AnalysisProvider for an intelligence-pipeline layer
-     * (`sel` by default; `pesl` when constructing a distinct PESL
-     * provider per Spec 2 SC35).
-     *
-     * Spec 2 Phase 4 (SC31–SC36) — resolution order:
-     *   1. Explicit `intelligence.provider` config wins (preserves Phase 0–3 behavior; SC33).
-     *   2. Otherwise, consult `agent.routing.intelligence.<layer>` (or
-     *      `routing.default`) to pick a `BackendDef` from `agent.backends`,
-     *      then translate via `buildAnalysisProvider` (the per-type factory).
-     *
-     * Closes the Phase 2 deferral (P2-DEF-638): the legacy
-     * `this.config.agent.backend` read at the bottom of this method is
-     * removed; routing is the sole source for non-explicit configs.
-     *
-     * Cyclomatic complexity: pre-Phase-4 was 33 (factory dispatch was
-     * inlined here). Phase 4 extracts the per-type tree into
-     * `buildAnalysisProvider`, dropping this method to ≤ 5 branches
-     * (under the 15 threshold).
-     */
-    private createAnalysisProvider;
-    /**
-     * Look up the routed BackendDef for an intelligence layer, falling
-     * back through `routing.intelligence.<layer>` → `routing.default`
-     * → null. Returns the resolved name alongside the def so callers can
-     * key into the per-name resolver map.
-     */
-    private resolveRoutedBackendForIntelligence;
-    private createProviderFromExplicitConfig;
     /**
      * Lazily initializes the ClaimManager if it hasn't been created yet.
      * Called from both start() and asyncTick() to avoid duplicating the init block.
@@ -1309,7 +1339,7 @@ declare class Orchestrator extends EventEmitter {
      * Dispatch a work item immediately, bypassing the normal tick → roadmap cycle.
      * Used by the dashboard's "Dispatch Now" action.
      */
-    dispatchAdHoc(issue: Issue): Promise<void>;
+    dispatchAdHoc(issue: Issue$1): Promise<void>;
     /**
      * Initialize the LocalModelResolver and intelligence pipeline.
      *
@@ -1481,29 +1511,6 @@ interface MigrationResult {
     config: AgentConfig;
     warnings: string[];
 }
-/**
- * Translate legacy `agent.backend` / `agent.localBackend` /
- * `agent.escalation.autoExecute` into the new `agent.backends` +
- * `agent.routing` shape (Spec 2 D3, D4, D8, D11).
- *
- * Behavior matrix:
- * - `agent.backends` already set, no legacy fields:
- *     no-op; returns input config unchanged, warnings = [].
- * - `agent.backends` already set + at least one legacy field:
- *     no-op on config; warnings name each ignored legacy field (D4).
- * - No `agent.backends`, at least one of `agent.backend` /
- *   `agent.localBackend` / `agent.localEndpoint` / etc. set:
- *     synthesize `backends.primary` (always, from `agent.backend`)
- *     and `backends.local` (when `localBackend` is set), plus a
- *     `routing` map driven by `escalation.autoExecute` (D3).
- * - No `agent.backends`, no legacy fields:
- *     no-op; the caller's downstream Zod validation surfaces the gap
- *     as a missing-required-field error.
- *
- * Throws on internal inconsistencies (e.g., `agent.backend = 'pi'`
- * with no `localEndpoint`/`localModel`) — these are user-config bugs
- * that would have produced a runtime crash today.
- */
 declare function migrateAgentConfig(agent: AgentConfig): MigrationResult;
 
 /**
@@ -1513,4 +1520,45 @@ declare function migrateAgentConfig(agent: AgentConfig): MigrationResult;
  */
 declare function createBackend(def: BackendDef): AgentBackend;
 
-export { type AgentUpdateEvent, AnalysisArchive, type AnalysisRecord, type ApplyEventResult, type ArtifactPresence, type AttemptStats, BackendRouter, type BackendRouterOptions, ClaimManager, type ClaimManagerConfig, type CleanWorkspaceEffect, type DispatchEffect, type EmitLogEffect, type EscalateEffect, type ExecFileFn, type Highlight, type HighlightsInfo, InteractionQueue, type LinearGraphQLExtension, LinearGraphQLStub, type LiveSession, type MigrationResult, MockBackend, ORCHESTRATOR_IDENTITY_FILE, Orchestrator, OrchestratorBackendFactory, type OrchestratorBackendFactoryOptions, type OrchestratorContext, type OrchestratorEvent, type OrchestratorState, PRDetector, type PRDetectorLogger, type PendingInteraction, PromptRenderer, type PublishedIndex, type RateLimitSnapshot as RateLimitComputeSnapshot, type RateLimitConfig, type RateLimitSnapshot$1 as RateLimitSnapshot, type ReleaseClaimEffect, type RetryEntry, type RetryFiredEvent, RoadmapTrackerAdapter, type RunAttemptPhase, type RunningEntry, type ScheduleRetryEffect, type SideEffect, type StallDetectedEvent, type StopEffect, type StreamManifest, StreamRecorder, type TickEvent, type TokenTotals, type TriageConfig, type TriageDecision, type TriageSignals, type TriageSkill, type UpdateTokensEffect, type WorkerExitEvent, WorkflowLoader, WorkspaceHooks, WorkspaceManager, applyEvent, artifactPresenceFromIssue, calculateRetryDelay, canDispatch, computeRateLimitDelay, createBackend, createEmptyState, detectScopeTier, extractHighlights, extractTitlePrefix, getAvailableSlots, getDefaultConfig, getPerStateCount, isEligible, launchTUI, loadPublishedIndex, migrateAgentConfig, reconcile, renderAnalysisComment, renderPRComment, resolveEscalationConfig, resolveOrchestratorId, routeIssue, savePublishedIndex, selectCandidates, sortCandidates, triageIssue, validateWorkflowConfig };
+/**
+ * Function signature compatible with Node's `child_process.execFile`.
+ * Allows injection for testing.
+ */
+type ExecFileFn = typeof execFile;
+/** Reasons `syncMain()` declines to fast-forward (none of which are failures). */
+type SyncSkipReason = 'wrong-branch' | 'diverged' | 'dirty-conflict' | 'no-remote' | 'fetch-failed';
+/** Total result type for `syncMain()`. Discriminated by `status`. */
+type SyncMainResult = {
+    status: 'updated';
+    from: string;
+    to: string;
+    defaultBranch: string;
+} | {
+    status: 'no-op';
+    defaultBranch: string;
+} | {
+    status: 'skipped';
+    reason: SyncSkipReason;
+    detail: string;
+    defaultBranch: string;
+} | {
+    status: 'error';
+    message: string;
+};
+/** Options accepted by `syncMain()`. */
+interface SyncMainOptions {
+    /** Override the `git` runner; defaults to `node:child_process.execFile`. */
+    execFileFn?: ExecFileFn;
+    /** Per-git-call timeout in ms. Defaults to 60_000ms. */
+    timeoutMs?: number;
+}
+/**
+ * Fast-forward the local default branch from `origin/<default>` if it can be
+ * done safely. This function is total: it never throws under expected
+ * conditions. Even unexpected errors are caught and converted to
+ * `{ status: 'error', message }` so the maintenance scheduler does not back
+ * off on transient git issues.
+ */
+declare function syncMain(repoRoot: string, opts?: SyncMainOptions): Promise<SyncMainResult>;
+
+export { type AgentUpdateEvent, AnalysisArchive, type AnalysisRecord, type ApplyEventResult, type ArtifactPresence, type AttemptStats, BackendRouter, type BackendRouterOptions, type BaseRefFallbackEvent, ClaimManager, type ClaimManagerConfig, type CleanWorkspaceEffect, type DispatchEffect, type EmitLogEffect, type EscalateEffect, type ExecFileFn$1 as ExecFileFn, type Highlight, type HighlightsInfo, InteractionQueue, type LinearGraphQLExtension, LinearGraphQLStub, type LiveSession, type MigrationResult, MockBackend, ORCHESTRATOR_IDENTITY_FILE, Orchestrator, OrchestratorBackendFactory, type OrchestratorBackendFactoryOptions, type OrchestratorContext, type OrchestratorEvent, type OrchestratorState, PRDetector, type PRDetectorLogger, type PendingInteraction, PromptRenderer, type PublishedIndex, type RateLimitSnapshot as RateLimitComputeSnapshot, type RateLimitConfig, type RateLimitSnapshot$1 as RateLimitSnapshot, type ReleaseClaimEffect, type RetryEntry, type RetryFiredEvent, RoadmapTrackerAdapter, type RunAttemptPhase, type RunningEntry, type ScheduleRetryEffect, type SideEffect, type StallDetectedEvent, type StopEffect, type StreamManifest, StreamRecorder, type SyncMainOptions, type SyncMainResult, type SyncSkipReason, type TickEvent, type TokenTotals, type TriageConfig, type TriageDecision, type TriageSignals, type TriageSkill, type UpdateTokensEffect, type WorkerExitEvent, WorkflowLoader, WorkspaceHooks, WorkspaceManager, type WorkspaceManagerOptions, applyEvent, artifactPresenceFromIssue, calculateRetryDelay, canDispatch, computeRateLimitDelay, createBackend, createEmptyState, detectScopeTier, extractHighlights, extractTitlePrefix, getAvailableSlots, getDefaultConfig, getPerStateCount, isEligible, launchTUI, loadPublishedIndex, migrateAgentConfig, reconcile, renderAnalysisComment, renderPRComment, resolveEscalationConfig, resolveOrchestratorId, routeIssue, savePublishedIndex, selectCandidates, sortCandidates, syncMain, triageIssue, validateWorkflowConfig };