@harness-engineering/orchestrator 0.2.7 → 0.2.8

package/dist/index.d.mts

@@ -1,11 +1,13 @@
-import { Issue, AgentEvent, TokenUsage, WorkflowConfig, Result, WorkflowDefinition, IssueTrackerClient, TrackerConfig, WorkspaceConfig, HooksConfig, AgentBackend, SessionStartParams, AgentSession, AgentError, TurnParams, TurnResult } from '@harness-engineering/types';
+import { Issue, AgentEvent, TokenUsage, ConcernSignal, ScopeTier, EscalationConfig, RoutingDecision, WorkflowConfig, IssueTrackerClient, Result, WorkflowDefinition, TrackerConfig, WorkspaceConfig, HooksConfig, AgentBackend, SessionStartParams, AgentSession, AgentError, TurnParams, TurnResult } from '@harness-engineering/types';
+import { EnrichedSpec, ComplexityScore, SimulationResult } from '@harness-engineering/intelligence';
+import { execFile } from 'node:child_process';
 import { EventEmitter } from 'node:events';
 
 /**
  * Run attempt lifecycle phases (internal to orchestrator).
  * Tracks the current phase of a single run attempt.
  */
-type RunAttemptPhase = 'PreparingWorkspace' | 'BuildingPrompt' | 'LaunchingAgent' | 'InitializingSession' | 'StreamingTurn' | 'Finishing' | 'Succeeded' | 'Failed' | 'TimedOut' | 'Stalled' | 'CanceledByReconciliation';
+type RunAttemptPhase = 'PreparingWorkspace' | 'BuildingPrompt' | 'LaunchingAgent' | 'InitializingSession' | 'StreamingTurn' | 'RateLimitSleeping' | 'Finishing' | 'Succeeded' | 'Failed' | 'TimedOut' | 'Stalled' | 'CanceledByReconciliation';
 /**
  * Live session metadata tracked while an agent subprocess is running.
  */
@@ -55,12 +57,14 @@ interface TokenTotals {
     inputTokens: number;
     outputTokens: number;
     totalTokens: number;
+    cacheReadTokens: number;
+    cacheCreationTokens: number;
     secondsRunning: number;
 }
 /**
  * Rate limit snapshot (populated by agent events).
  */
-interface RateLimitSnapshot {
+interface RateLimitSnapshot$1 {
     requestsRemaining: number | null;
     requestsLimit: number | null;
     tokensRemaining: number | null;
@@ -72,25 +76,50 @@ interface RateLimitSnapshot {
 interface OrchestratorState {
     pollIntervalMs: number;
     maxConcurrentAgents: number;
+    globalCooldownUntilMs: number | null;
+    recentRequestTimestamps: number[];
+    recentInputTokens: {
+        timestamp: number;
+        tokens: number;
+    }[];
+    recentOutputTokens: {
+        timestamp: number;
+        tokens: number;
+    }[];
+    globalCooldownMs: number;
+    maxRequestsPerMinute: number;
+    maxRequestsPerSecond: number;
+    maxInputTokensPerMinute: number;
+    maxOutputTokensPerMinute: number;
     running: Map<string, RunningEntry>;
     claimed: Set<string>;
     retryAttempts: Map<string, RetryEntry>;
     completed: Set<string>;
     tokenTotals: TokenTotals;
-    rateLimits: RateLimitSnapshot;
+    rateLimits: RateLimitSnapshot$1;
+    /** Running count of claim rejections (another orchestrator won the race). */
+    claimRejections: number;
 }
 
 /**
  * Discriminated union of events that drive the orchestrator state machine.
  * All events are data -- the caller constructs them from I/O results.
  */
-type OrchestratorEvent = TickEvent | WorkerExitEvent | AgentUpdateEvent | RetryFiredEvent | StallDetectedEvent;
+type OrchestratorEvent = TickEvent | WorkerExitEvent | AgentUpdateEvent | RetryFiredEvent | StallDetectedEvent | ClaimRejectedEvent;
 interface TickEvent {
     type: 'tick';
     candidates: Issue[];
     runningStates: Map<string, Issue>;
     /** Caller-supplied wall clock (ms since epoch). Keeps state machine pure. */
     nowMs: number;
+    /** Pre-computed concern signals from intelligence pipeline (issueId → signals) */
+    concernSignals?: Map<string, ConcernSignal[]>;
+    /** Pre-computed enriched specs from intelligence pipeline (issueId → spec) */
+    enrichedSpecs?: Map<string, EnrichedSpec>;
+    /** Pre-computed complexity scores from intelligence pipeline (issueId → score) */
+    complexityScores?: Map<string, ComplexityScore>;
+    /** Pre-computed PESL simulation results from intelligence pipeline (issueId -> result) */
+    simulationResults?: Map<string, SimulationResult>;
 }
 interface WorkerExitEvent {
     type: 'worker_exit';
@@ -115,15 +144,21 @@ interface StallDetectedEvent {
     type: 'stall_detected';
     issueId: string;
 }
+interface ClaimRejectedEvent {
+    type: 'claim_rejected';
+    issueId: string;
+}
 /**
  * Discriminated union of side effects returned by the state machine.
  * These are data describing what to do -- the orchestrator loop executes them.
  */
-type SideEffect = DispatchEffect | StopEffect | ScheduleRetryEffect | ReleaseClaimEffect | CleanWorkspaceEffect | UpdateTokensEffect | EmitLogEffect;
+type SideEffect = DispatchEffect | StopEffect | ScheduleRetryEffect | ReleaseClaimEffect | CleanWorkspaceEffect | UpdateTokensEffect | EmitLogEffect | EscalateEffect | ClaimEffect;
 interface DispatchEffect {
     type: 'dispatch';
     issue: Issue;
     attempt: number | null;
+    /** Which backend to dispatch to. Defaults to 'primary' for backward compat. */
+    backend?: 'local' | 'primary';
 }
 interface StopEffect {
     type: 'stop';
@@ -158,6 +193,28 @@ interface EmitLogEffect {
     message: string;
     context?: Record<string, unknown>;
 }
+interface EscalateEffect {
+    type: 'escalate';
+    issueId: string;
+    identifier: string;
+    reasons: string[];
+    /** Issue title for context in the interaction queue */
+    issueTitle?: string;
+    /** Issue description for context in the interaction queue */
+    issueDescription?: string | null;
+    /** Enriched spec from intelligence pipeline, if available */
+    enrichedSpec?: EnrichedSpec;
+    /** Complexity score from intelligence pipeline, if available */
+    complexityScore?: ComplexityScore;
+}
+interface ClaimEffect {
+    type: 'claim';
+    issue: Issue;
+    /** Which backend to dispatch to after a successful claim */
+    backend?: 'local' | 'primary';
+    /** Retry attempt number, if this is a retry dispatch */
+    attempt: number | null;
+}
 
 /**
  * Calculate retry delay based on attempt number and retry type.
@@ -211,10 +268,245 @@ declare function canDispatch(state: OrchestratorState, issueState: string, maxCo
  */
 declare function reconcile(state: OrchestratorState, runningStates: ReadonlyMap<string, Issue>, activeStates: string[], terminalStates: string[]): SideEffect[];
 
+/**
+ * Artifact presence metadata for scope tier detection.
+ */
+interface ArtifactPresence {
+    hasSpec: boolean;
+    hasPlans: boolean;
+}
+/**
+ * Derive artifact presence from an Issue's spec and plans fields.
+ */
+declare function artifactPresenceFromIssue(issue: Issue): ArtifactPresence;
+/**
+ * Detect the scope tier for an issue based on label overrides and artifact presence.
+ *
+ * Label override (e.g., `scope:quick-fix`) takes precedence.
+ * Otherwise, infer from spec/plan presence:
+ *   - No spec, no plan -> full-exploration
+ *   - Spec or plan exists -> guided-change
+ */
+declare function detectScopeTier(issue: Issue, artifacts: ArtifactPresence): ScopeTier;
+/**
+ * Pure routing function. Determines whether an issue should be dispatched
+ * to the local backend, the primary backend, or escalated to needs-human.
+ *
+ * Routing rules (in order):
+ * 1. If tier is in alwaysHuman -> needs-human
+ * 2. If tier is in primaryExecute -> dispatch-primary
+ * 3. If tier is in autoExecute -> dispatch-local
+ * 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;
+
+/**
+ * Candidate skills the orchestrator may dispatch to. Keep this set
+ * small on purpose — the triage router is a coarse routing layer, not
+ * a skill registry.
+ */
+type TriageSkill = 'code-review' | 'security-review' | 'planning' | 'debugging' | 'refactoring' | 'docs';
+/**
+ * Shape-of-work signals the triage router consumes. These are derived
+ * from the Issue plus diff metadata by the caller.
+ */
+interface TriageSignals {
+    /** Raw title/body prefix, e.g. "feat:", "fix:", "docs:", "security:" */
+    titlePrefix?: string;
+    /** True if the diff touches auth, crypto, session, or similar paths */
+    touchesSecuritySensitivePaths?: boolean;
+    /** True if the diff touches a migrations or schema directory */
+    touchesMigrationPaths?: boolean;
+    /** Count of changed files in the diff */
+    changedFileCount?: number;
+    /** Whether tests are failing on the issue branch */
+    hasFailingTests?: boolean;
+    /** Whether the issue is marked or labeled as a rollback */
+    isRollback?: boolean;
+    /** True if every changed file is `.md` */
+    isDocsOnly?: boolean;
+}
+/**
+ * Structured decision the orchestrator persists and consumes.
+ */
+interface TriageDecision {
+    /** Target skill for dispatch. */
+    skill: TriageSkill;
+    /** Specific agent within the skill, optional. */
+    agent?: string;
+    /** Router confidence in the decision. */
+    confidence: 'high' | 'medium' | 'low';
+    /** Human-readable justifications (one entry per rule that matched). */
+    reasons: string[];
+}
+/**
+ * Optional user/project overrides for path heuristics and rule thresholds.
+ */
+interface TriageConfig {
+    /** Max changed files for a fix to still route to code-review (default 3). */
+    smallFixChangedFileMax?: number;
+}
+/**
+ * Extract the conventional-commit prefix (lowercased) from a title.
+ * Returns undefined if no prefix is present.
+ */
+declare function extractTitlePrefix(title: string | null | undefined): string | undefined;
+/**
+ * Decide which skill/agent the orchestrator should dispatch this issue to.
+ *
+ * Rule order (first match wins):
+ *  1. isRollback                          → debugging (high)
+ *  2. security prefix or security paths   → security-review (high)
+ *  3. docs prefix or docs-only diff       → docs (high)
+ *  4. hasFailingTests                     → debugging (medium)
+ *  5. touchesMigrationPaths               → planning (high)
+ *  6. fix: with small change              → code-review (high)
+ *  7. feat:                               → planning (medium)
+ *  8. refactor:                           → refactoring (medium)
+ *  9. default                             → code-review (low)
+ *
+ * Triage is meant to run BEFORE `routeIssue()`; the selected skill is
+ * persisted on the live session so downstream dispatch does not
+ * re-derive it.
+ */
+declare function triageIssue(issue: Issue, signals: TriageSignals, config?: TriageConfig): TriageDecision;
+
+/**
+ * A pending human interaction, typically from an escalation.
+ */
+interface PendingInteraction {
+    /** Unique interaction ID */
+    id: string;
+    /** ID of the related issue */
+    issueId: string;
+    /** Interaction type */
+    type: 'needs-human';
+    /** Reasons for escalation */
+    reasons: string[];
+    /** Context for the human */
+    context: {
+        issueTitle: string;
+        issueDescription: string | null;
+        specPath: string | null;
+        planPath: string | null;
+        relatedFiles: string[];
+        /** Enriched spec from intelligence pipeline, if available */
+        enrichedSpec?: {
+            intent: string;
+            summary: string;
+            affectedSystems: unknown[];
+            unknowns: string[];
+            ambiguities: string[];
+            riskSignals: string[];
+        };
+        /** Complexity score from intelligence pipeline, if available */
+        complexityScore?: {
+            overall: number;
+            confidence: number;
+            riskLevel: string;
+            blastRadius: {
+                services: number;
+                modules: number;
+                filesEstimated: number;
+                testFilesAffected: number;
+            };
+            dimensions: {
+                structural: number;
+                semantic: number;
+                historical: number;
+            };
+            reasoning: string[];
+            recommendedRoute: string;
+        };
+    };
+    /** ISO timestamp of creation */
+    createdAt: string;
+    /** Current status */
+    status: 'pending' | 'claimed' | 'resolved';
+}
+/**
+ * Persistent queue of pending human interactions.
+ * Each interaction is stored as a separate JSON file in the configured directory.
+ */
+declare class InteractionQueue {
+    private dir;
+    private pushListeners;
+    /**
+     * @param dir - Directory path for storing interaction JSON files
+     */
+    constructor(dir: string);
+    /**
+     * Register a listener that fires after each push.
+     */
+    onPush(listener: (interaction: PendingInteraction) => void): void;
+    /**
+     * Push a new interaction to the queue.
+     * If a pending interaction for the same issueId already exists, it is
+     * replaced (upsert) so the directory never accumulates duplicates.
+     */
+    push(interaction: PendingInteraction): Promise<void>;
+    /**
+     * List all interactions (regardless of status).
+     */
+    list(): Promise<PendingInteraction[]>;
+    /**
+     * List only pending interactions.
+     */
+    listPending(): Promise<PendingInteraction[]>;
+    /**
+     * Update the status of an interaction.
+     */
+    updateStatus(id: string, status: PendingInteraction['status']): Promise<void>;
+}
+
+/**
+ * A persisted record of a single intelligence pipeline analysis run.
+ */
+interface AnalysisRecord {
+    /** Issue ID this analysis belongs to */
+    issueId: string;
+    /** Issue identifier (human-readable) */
+    identifier: string;
+    /** Enriched spec from SEL, or null if skipped */
+    spec: EnrichedSpec | null;
+    /** Complexity score from CML, or null if skipped */
+    score: ComplexityScore | null;
+    /** PESL simulation result, or null if not run */
+    simulation: SimulationResult | null;
+    /** ISO timestamp when this analysis was recorded */
+    analyzedAt: string;
+    /** External tracker ID (e.g., "github:owner/repo#42"), populated at analysis time. Null if no tracker configured. */
+    externalId: string | null;
+}
+/**
+ * Persistent archive of intelligence pipeline analysis results.
+ * Each analysis is stored as a separate JSON file keyed by issue ID.
+ * Overwrites previous analysis for the same issue (latest result wins).
+ */
+declare class AnalysisArchive {
+    private dir;
+    constructor(dir: string);
+    private safePath;
+    /**
+     * Write an analysis record to disk, overwriting any previous record for the same issue.
+     */
+    save(record: AnalysisRecord): Promise<void>;
+    /**
+     * Read the analysis record for a specific issue.
+     */
+    get(issueId: string): Promise<AnalysisRecord | null>;
+    /**
+     * List all archived analysis records.
+     */
+    list(): Promise<AnalysisRecord[]>;
+}
+
 interface ApplyEventResult {
     nextState: OrchestratorState;
     effects: SideEffect[];
 }
+declare function resolveEscalationConfig(config: WorkflowConfig): EscalationConfig;
 /**
  * Pure state machine transition function.
  *
@@ -229,6 +521,189 @@ declare function applyEvent(state: OrchestratorState, event: OrchestratorEvent,
  */
 declare function createEmptyState(config: WorkflowConfig): OrchestratorState;
 
+/**
+ * Computes the delay (in ms) needed before the next API request can be made,
+ * based on a snapshot of recent request/token activity and rate-limit config.
+ *
+ * Returns 0 when no throttling is needed.
+ */
+interface RateLimitSnapshot {
+    globalCooldownUntilMs: number | null;
+    recentRequestTimestamps: number[];
+    recentInputTokens: {
+        timestamp: number;
+        tokens: number;
+    }[];
+    recentOutputTokens: {
+        timestamp: number;
+        tokens: number;
+    }[];
+}
+interface RateLimitConfig {
+    maxRequestsPerMinute: number;
+    maxRequestsPerSecond: number;
+    maxInputTokensPerMinute: number;
+    maxOutputTokensPerMinute: number;
+}
+declare function computeRateLimitDelay(snapshot: RateLimitSnapshot, config: RateLimitConfig): number;
+
+/**
+ * Renders an AnalysisRecord as a structured markdown comment.
+ * Format: summary header + reasoning bullets + collapsible JSON with discriminator.
+ *
+ * Used by both the orchestrator auto-publish and the CLI publish-analyses command.
+ */
+declare function renderAnalysisComment(record: AnalysisRecord): string;
+
+interface PublishedIndex {
+    [issueId: string]: string;
+}
+/**
+ * Load the published analyses index from disk.
+ * Returns an empty object if the file does not exist or is unparseable.
+ */
+declare function loadPublishedIndex(projectRoot: string): PublishedIndex;
+/**
+ * Persist the published analyses index to disk.
+ * Creates parent directories if they do not exist.
+ */
+declare function savePublishedIndex(projectRoot: string, index: PublishedIndex): void;
+
+/**
+ * Resolves the orchestrator identity. Uses the explicit configId if
+ * provided; otherwise reads or creates a persisted machine UUID at
+ * ~/.harness/orchestrator-id and derives a stable hash.
+ *
+ * Format: `orchestrator-{first8charsOfSha256(uuid)}`
+ * Example: `orchestrator-a7f3b2c1`
+ */
+declare function resolveOrchestratorId(configId?: string): Promise<string>;
+/** Exposed for testing only -- returns the path to the identity file. */
+declare const ORCHESTRATOR_IDENTITY_FILE: string;
+
+interface ClaimManagerConfig {
+    /** Delay in ms between claim write and verification read. Default: 2000 */
+    verifyDelayMs?: number;
+    /** State name used for claimed/in-progress issues. Default: 'in-progress' */
+    claimedState?: string;
+}
+/**
+ * Manages claim coordination for multi-orchestrator dispatch.
+ *
+ * Uses the tracker as the shared state layer. Claims are optimistic:
+ * write then verify after a delay to detect races.
+ */
+declare class ClaimManager {
+    private tracker;
+    private orchestratorId;
+    private verifyDelayMs;
+    private claimedState;
+    constructor(tracker: IssueTrackerClient, orchestratorId: string, config?: ClaimManagerConfig);
+    /**
+     * Optimistically claims an issue then verifies ownership after a delay.
+     *
+     * Returns 'claimed' if the assignee matches this orchestrator after
+     * the verify delay, 'rejected' if another orchestrator won the race.
+     */
+    claimAndVerify(issueId: string): Promise<Result<'claimed' | 'rejected', Error>>;
+    /**
+     * Releases a claimed issue back to the available pool.
+     */
+    release(issueId: string): Promise<Result<void, Error>>;
+    /**
+     * Refreshes claim timestamps for all running issues in parallel.
+     * Failures are non-fatal — individual heartbeat failures are swallowed
+     * so one failing claim does not block others.
+     */
+    heartbeat(issueIds: string[]): Promise<void>;
+    /**
+     * Checks whether an issue's claim is stale based on its updatedAt
+     * timestamp and the configured TTL.
+     *
+     * Returns true if the claim should be considered expired (the
+     * owning orchestrator may have crashed).
+     */
+    isStale(issue: Issue, ttlMs: number): boolean;
+    /**
+     * Scans the tracker for "in-progress" issues assigned to this orchestrator
+     * and releases any that are not currently running in memory.
+     *
+     * Called once during orchestrator startup to clean up orphaned claims
+     * from a previous crash or unclean shutdown.
+     *
+     * @param runningIssueIds - Set of issue IDs currently in the running map
+     * @returns List of issue IDs that were released
+     */
+    reconcileOnStartup(runningIssueIds: ReadonlySet<string>): Promise<Result<string[], Error>>;
+}
+
+/**
+ * Minimal logger interface for PR detection.
+ * Accepts any structured logger that provides debug/info/warn.
+ */
+interface PRDetectorLogger {
+    debug(message: string, meta?: Record<string, unknown>): void;
+    info(message: string, meta?: Record<string, unknown>): void;
+    warn(message: string, meta?: Record<string, unknown>): void;
+}
+/**
+ * Function signature compatible with Node's `child_process.execFile`.
+ * Allows injection for testing.
+ */
+type ExecFileFn = typeof execFile;
+/**
+ * Detects whether GitHub issues or branches already have open pull requests.
+ *
+ * Uses the `gh` CLI under the hood. All checks are fail-open: if `gh` is not
+ * installed, auth is missing, or the network is down, candidates pass through
+ * rather than being incorrectly blocked.
+ */
+declare class PRDetector {
+    private logger;
+    private execFileFn;
+    private projectRoot;
+    constructor(opts: {
+        logger: PRDetectorLogger;
+        execFileFn?: ExecFileFn;
+        projectRoot: string;
+    });
+    /**
+     * Parse a `github:owner/repo#N` externalId into its parts.
+     * Returns null for invalid or non-GitHub formats.
+     */
+    parseExternalId(externalId: string): {
+        owner: string;
+        repo: string;
+        number: number;
+    } | null;
+    /**
+     * Checks whether a remote branch has an open pull request via `gh`.
+     * Returns true if a PR exists, false otherwise. Failures are treated
+     * as "no PR" to err on the side of preserving work.
+     */
+    branchHasPullRequest(branch: string): Promise<boolean>;
+    /**
+     * Checks whether a GitHub issue (identified by externalId) has an open PR
+     * linked to it via `closes #N` or similar keywords. Fail-open on API errors
+     * or non-GitHub externalId formats.
+     */
+    hasOpenPRForExternalId(externalId: string): Promise<boolean>;
+    /**
+     * Checks whether an issue identifier has an open GitHub PR by searching
+     * for a branch matching the `feat/<identifier>` naming convention used
+     * by dispatched agents. Fail-open on API errors.
+     */
+    hasOpenPRForIdentifier(identifier: string): Promise<boolean>;
+    /**
+     * Filters out candidates that already have an open GitHub PR, running
+     * checks with limited concurrency to avoid overwhelming the GitHub API.
+     * For candidates with an externalId, searches for PRs linked to the
+     * GitHub issue. Falls back to `feat/<identifier>` branch lookup otherwise.
+     * Fail-open on API errors.
+     */
+    filterCandidatesWithOpenPRs(candidates: Issue[]): Promise<Issue[]>;
+}
+
 declare class WorkflowLoader {
     loadWorkflow(filePath: string): Promise<Result<WorkflowDefinition, Error>>;
 }
@@ -261,6 +736,28 @@ declare class RoadmapTrackerAdapter implements IssueTrackerClient {
      * @param stateNames - List of statuses to filter by
      */
     fetchIssuesByStates(stateNames: string[]): Promise<Result<Issue[], 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>>;
+    private findFeatureById;
     /**
      * Fetches full issue details for a list of identifiers.
      *
@@ -290,7 +787,11 @@ declare class LinearGraphQLStub implements LinearGraphQLExtension {
 
 declare class WorkspaceManager {
     private config;
+    /** Absolute path to the git repository root (resolved lazily). */
+    private repoRoot;
     constructor(config: WorkspaceConfig);
+    /** Runs a git command and returns stdout. Extracted for testability. */
+    protected git(args: string[], cwd: string): Promise<string>;
     /**
      * Sanitizes an issue identifier to be safe for use as a directory name.
      */
@@ -300,15 +801,45 @@ declare class WorkspaceManager {
      */
     resolvePath(identifier: string): string;
     /**
-     * Ensures the workspace directory exists.
+     * Discovers the git repository root from the workspace root directory.
+     */
+    private getRepoRoot;
+    /**
+     * Ensures the workspace exists as a git worktree so the agent has
+     * access to the full project source.
      */
     ensureWorkspace(identifier: string): Promise<Result<string, Error>>;
+    /**
+     * Best-effort `git fetch origin` so subsequent ref resolution sees the
+     * latest remote state. Failures (offline, no remote, auth errors) are
+     * swallowed — dispatch should not be blocked by transient network issues.
+     */
+    private tryFetch;
+    /**
+     * Resolves the ref that new worktrees should be based on.
+     *
+     * 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).
+     */
+    private resolveBaseRef;
+    /** Returns true iff `git rev-parse --verify` accepts the ref. */
+    private refExists;
     /**
      * Checks if a workspace exists.
      */
     exists(identifier: string): Promise<boolean>;
     /**
-     * Removes a workspace directory.
+     * Checks whether a worktree has commits ahead of the base branch that have
+     * been pushed to a remote branch. Returns the remote branch name if found,
+     * or null if the worktree is on a detached HEAD with no pushed branch.
+     */
+    findPushedBranch(identifier: string): Promise<string | null>;
+    /**
+     * Removes a workspace directory and its git worktree registration.
      */
     removeWorkspace(identifier: string): Promise<Result<void, Error>>;
 }
@@ -334,86 +865,65 @@ declare class MockBackend implements AgentBackend {
     healthCheck(): Promise<Result<void, AgentError>>;
 }
 
-declare class ClaudeBackend implements AgentBackend {
-    readonly name = "claude";
-    private command;
-    constructor(command?: string);
-    startSession(params: SessionStartParams): Promise<Result<AgentSession, AgentError>>;
-    runTurn(session: AgentSession, params: TurnParams): AsyncGenerator<AgentEvent, TurnResult, void>;
-    stopSession(_session: AgentSession): Promise<Result<void, AgentError>>;
-    healthCheck(): Promise<Result<void, AgentError>>;
-}
-
-interface OpenAIBackendConfig {
-    /** OpenAI model to use. Defaults to 'gpt-4o'. */
-    model?: string;
-    /** API key. Defaults to process.env.OPENAI_API_KEY. */
-    apiKey?: string;
-}
-interface OpenAISession extends AgentSession {
-    systemPrompt?: string;
-}
-declare class OpenAIBackend implements AgentBackend {
-    readonly name = "openai";
-    private config;
-    private client;
-    private cacheAdapter;
-    constructor(config?: OpenAIBackendConfig);
-    startSession(params: SessionStartParams): Promise<Result<AgentSession, AgentError>>;
-    runTurn(session: AgentSession, params: TurnParams): AsyncGenerator<AgentEvent, TurnResult, void>;
-    stopSession(_session: AgentSession): Promise<Result<void, AgentError>>;
-    healthCheck(): Promise<Result<void, AgentError>>;
-}
-
-interface GeminiBackendConfig {
-    /** Gemini model to use. Defaults to 'gemini-2.0-flash'. */
-    model?: string;
-    /** API key. Defaults to process.env.GEMINI_API_KEY or process.env.GOOGLE_API_KEY. */
-    apiKey?: string;
-}
-interface GeminiSession extends AgentSession {
-    systemPrompt?: string;
-}
-declare class GeminiBackend implements AgentBackend {
-    readonly name = "gemini";
-    private config;
-    private cacheAdapter;
-    constructor(config?: GeminiBackendConfig);
-    startSession(params: SessionStartParams): Promise<Result<AgentSession, AgentError>>;
-    runTurn(session: AgentSession, params: TurnParams): AsyncGenerator<AgentEvent, TurnResult, void>;
-    stopSession(_session: AgentSession): Promise<Result<void, AgentError>>;
-    healthCheck(): Promise<Result<void, AgentError>>;
-}
-
-interface AnthropicBackendConfig {
-    /** Anthropic model to use. Defaults to 'claude-sonnet-4-20250514'. */
-    model?: string;
-    /** API key. Defaults to process.env.ANTHROPIC_API_KEY. */
-    apiKey?: string;
-    /** Maximum output tokens. Defaults to 4096. */
-    maxTokens?: number;
-}
-interface AnthropicSession extends AgentSession {
-    systemPrompt?: string;
-}
-declare class AnthropicBackend implements AgentBackend {
-    readonly name = "anthropic";
-    private config;
-    private client;
-    private cacheAdapter;
-    constructor(config?: AnthropicBackendConfig);
-    startSession(params: SessionStartParams): Promise<Result<AgentSession, AgentError>>;
-    runTurn(session: AgentSession, params: TurnParams): AsyncGenerator<AgentEvent, TurnResult, void>;
-    stopSession(_session: AgentSession): Promise<Result<void, AgentError>>;
-    healthCheck(): Promise<Result<void, AgentError>>;
-}
-
 declare class PromptRenderer {
     private engine;
     constructor();
     render(template: string, context: Record<string, unknown>): Promise<string>;
 }
 
+/**
+ * Result of a single maintenance task run.
+ */
+interface RunResult {
+    /** ID of the task that was run */
+    taskId: string;
+    /** ISO timestamp when the run started */
+    startedAt: string;
+    /** ISO timestamp when the run completed */
+    completedAt: string;
+    /** Outcome of the run */
+    status: 'success' | 'failure' | 'skipped' | 'no-issues';
+    /** Number of issues/findings detected */
+    findings: number;
+    /** Number of issues fixed */
+    fixed: number;
+    /** URL of the created/updated PR, or null if no PR was created */
+    prUrl: string | null;
+    /** Whether an existing PR was updated (vs newly created) */
+    prUpdated: boolean;
+    /** Error message if status is 'failure' */
+    error?: string;
+}
+/**
+ * Schedule entry for a single task, used in MaintenanceStatus.
+ */
+interface ScheduleEntry {
+    /** Task identifier */
+    taskId: string;
+    /** ISO timestamp of the next scheduled run */
+    nextRun: string;
+    /** Result of the most recent run, or null if never run */
+    lastRun: RunResult | null;
+}
+/**
+ * Overall maintenance module status, exposed via dashboard API.
+ */
+interface MaintenanceStatus {
+    /** Whether this orchestrator instance is the maintenance leader */
+    isLeader: boolean;
+    /** ISO timestamp of the last successful leader claim, or null */
+    lastLeaderClaim: string | null;
+    /** Schedule state for all enabled tasks */
+    schedule: ScheduleEntry[];
+    /** Currently executing task, or null if idle */
+    activeRun: {
+        taskId: string;
+        startedAt: string;
+    } | null;
+    /** History of completed runs (most recent first) */
+    history: RunResult[];
+}
+
 /**
  * The central orchestrator that manages the lifecycle of coding agents.
  *
@@ -434,7 +944,28 @@ declare class Orchestrator extends EventEmitter {
     private promptTemplate;
     private server?;
     private interval?;
+    private heartbeatInterval?;
     private logger;
+    private interactionQueue;
+    private localRunner;
+    private pipeline;
+    private analysisArchive;
+    private graphStore;
+    private claimManager;
+    private prDetector;
+    private maintenanceScheduler;
+    private maintenanceReporter;
+    private orchestratorIdPromise;
+    /** Project root directory, derived from workspace root. */
+    private get projectRoot();
+    private graphLoaded;
+    private enrichedSpecsByIssue;
+    /** Tracks recently-failed intelligence analysis to avoid re-requesting every tick */
+    private analysisFailureCache;
+    /** Guards against overlapping ticks when a tick takes longer than the polling interval */
+    private tickInProgress;
+    /** Current tick-phase activity visible to the dashboard */
+    private tickActivity;
     /**
      * Creates a new Orchestrator instance.
      *
@@ -445,15 +976,71 @@ declare class Orchestrator extends EventEmitter {
     constructor(config: WorkflowConfig, promptTemplate: string, overrides?: {
         tracker?: IssueTrackerClient;
         backend?: AgentBackend;
+        execFileFn?: ExecFileFn;
     });
     private createTracker;
     private createBackend;
     /**
-     * Run a single tick of the orchestrator loop.
+     * Creates a TaskRunner for the maintenance scheduler.
+     * Provides stub implementations for check/agent/command execution.
+     * Phase 4 (PRManager) and Phase 5 (Reporter) will enhance these.
+     */
+    private createMaintenanceTaskRunner;
+    /**
+     * Initializes the maintenance subsystem: reporter, scheduler, and server route wiring.
+     * Extracted from start() to keep function length under threshold.
+     */
+    private initMaintenance;
+    private createLocalBackend;
+    private createIntelligencePipeline;
+    /**
+     * Create the AnalysisProvider for the intelligence pipeline.
+     *
+     * Resolution order:
+     * 1. Explicit `intelligence.provider` config (separate key/endpoint)
+     * 2. Local backend config (agent.localBackend + localEndpoint/localModel)
+     * 3. Primary agent backend config (agent.apiKey + agent.backend)
+     */
+    private createAnalysisProvider;
+    private createProviderFromExplicitConfig;
+    private runPeslSimulations;
+    private archiveAnalysisResults;
+    /**
+     * Auto-publish analysis results to the external tracker as structured comments.
+     * Fires only when:
+     * - A tracker is configured in harness.config.json (roadmap.tracker)
+     * - GITHUB_TOKEN env var is available
+     * - The record has a non-null externalId
+     * - The record has not already been published (per the published index)
      *
-     * This method fetches the latest issue states, applies them to the state machine,
-     * and executes any resulting side effects (dispatching new agents, stopping agents, etc.).
+     * Errors are non-fatal: a failed publish logs a warning but does not block
+     * the orchestrator tick.
      */
+    private autoPublishAnalyses;
+    private publishAnalysisForIssue;
+    private runIntelligencePipeline;
+    /**
+     * Analyzes a single candidate issue through the intelligence pipeline.
+     * Returns connection error state and whether the circuit breaker tripped.
+     */
+    private analyzeCandidate;
+    private evictExpiredFailures;
+    private filterEligibleForAnalysis;
+    private analyzeCandidates;
+    /**
+     * Lazily initializes the ClaimManager if it hasn't been created yet.
+     * Called from both start() and asyncTick() to avoid duplicating the init block.
+     */
+    private ensureClaimManager;
+    /**
+     * Loads the graph store and hydrates the enriched spec cache from the analysis
+     * archive on the first tick. Subsequent calls are no-ops. All failures are
+     * non-fatal — empty graph / empty cache are valid fallbacks.
+     */
+    private loadPersistedData;
+    private loadGraphStore;
+    private hydrateSpecCache;
+    asyncTick(): Promise<void>;
     tick(): Promise<void>;
     /**
      * Processes a side effect generated by the state machine.
@@ -461,6 +1048,53 @@ declare class Orchestrator extends EventEmitter {
      * @param effect - The effect to handle
      */
     private handleEffect;
+    /**
+     * Guards workspace cleanup by checking whether the agent pushed a branch
+     * that does not yet have a pull request. If so, the worktree is preserved
+     * and an interaction is queued so a human can create the PR manually.
+     */
+    private cleanWorkspaceWithGuard;
+    /**
+     * Delegates to PRDetector.branchHasPullRequest.
+     * @see PRDetector#branchHasPullRequest
+     */
+    private branchHasPullRequest;
+    /**
+     * Delegates to PRDetector.filterCandidatesWithOpenPRs.
+     * @see PRDetector#filterCandidatesWithOpenPRs
+     */
+    private filterCandidatesWithOpenPRs;
+    /**
+     * Scans candidate issues for stale claims from other orchestrators.
+     * An issue is considered stale if:
+     * - It is in an "in-progress" state
+     * - It has an assignee that is NOT this orchestrator
+     * - Its updatedAt timestamp exceeds the heartbeat TTL
+     *
+     * Stale claims are released so the issue becomes available on subsequent ticks.
+     */
+    private releaseStaleClaims;
+    /**
+     * Handles an escalation effect by writing to the interaction queue and logging.
+     */
+    private handleEscalation;
+    /**
+     * Handles a claim effect by calling claimAndVerify on the ClaimManager.
+     * If claimed, proceeds to dispatch. If rejected, emits a claim_rejected
+     * event to clean up the state machine.
+     */
+    private handleClaimEffect;
+    /**
+     * Posts a structured comment on the GitHub issue when the orchestrator claims it.
+     * Fire-and-forget: failures are logged but never block dispatch.
+     */
+    private postClaimComment;
+    /**
+     * Posts a lifecycle event comment to the GitHub issue.
+     * Supports: claimed, completed, released.
+     * Fire-and-forget: failures are logged but never block the caller.
+     */
+    private postLifecycleComment;
     /**
      * Dispatches a new agent to work on an issue.
      *
@@ -468,10 +1102,9 @@ declare class Orchestrator extends EventEmitter {
      * @param attempt - The retry attempt number
      */
     private dispatchIssue;
-    /**
-     * Runs an agent session in a background task to avoid blocking the main loop.
-     */
     private runAgentInBackgroundTask;
+    private recordOutcomeIfPipelineEnabled;
+    private handleCompletionSideEffects;
     /**
      * Informs the state machine that an agent worker has exited.
      */
@@ -482,26 +1115,39 @@ declare class Orchestrator extends EventEmitter {
      * @param issueId - The ID of the issue to stop
      */
     private stopIssue;
+    /**
+     * Dispatch a work item immediately, bypassing the normal tick → roadmap cycle.
+     * Used by the dashboard's "Dispatch Now" action.
+     */
+    dispatchAdHoc(issue: Issue): Promise<void>;
     /**
      * Starts the polling loop and the internal HTTP server.
+     * Runs startup reconciliation to release orphaned claims before the first tick.
      */
-    start(): void;
+    start(): Promise<void>;
     /**
      * Stops the orchestrator, clearing the polling interval and stopping the server.
      */
     stop(): Promise<void>;
+    /** Update tick activity and broadcast the change to connected clients. */
+    private setTickActivity;
     /**
      * Returns a point-in-time snapshot of the orchestrator's internal state.
      */
     getSnapshot(): Record<string, unknown>;
+    /** Returns the maintenance scheduler status, or null if maintenance is not enabled. */
+    getMaintenanceStatus(): MaintenanceStatus | null;
 }
 
 /**
  * Launches the Ink TUI for the given Orchestrator instance.
  * Returns a function to wait for the TUI to exit.
+ *
+ * @deprecated The TUI is maintained as a fallback for headless/SSH environments.
+ * The web dashboard (served at port 8080) is the primary monitoring interface.
  */
 declare function launchTUI(orchestrator: Orchestrator): {
     waitUntilExit: () => Promise<void>;
 };
 
-export { type AgentUpdateEvent, AnthropicBackend, type AnthropicBackendConfig, type AnthropicSession, type ApplyEventResult, ClaudeBackend, type CleanWorkspaceEffect, type DispatchEffect, type EmitLogEffect, GeminiBackend, type GeminiBackendConfig, type GeminiSession, type LinearGraphQLExtension, LinearGraphQLStub, type LiveSession, MockBackend, OpenAIBackend, type OpenAIBackendConfig, type OpenAISession, Orchestrator, type OrchestratorEvent, type OrchestratorState, PromptRenderer, type RateLimitSnapshot, type ReleaseClaimEffect, type RetryEntry, type RetryFiredEvent, RoadmapTrackerAdapter, type RunAttemptPhase, type RunningEntry, type ScheduleRetryEffect, type SideEffect, type StallDetectedEvent, type StopEffect, type TickEvent, type TokenTotals, type UpdateTokensEffect, type WorkerExitEvent, WorkflowLoader, WorkspaceHooks, WorkspaceManager, applyEvent, calculateRetryDelay, canDispatch, createEmptyState, getAvailableSlots, getDefaultConfig, getPerStateCount, isEligible, launchTUI, reconcile, selectCandidates, sortCandidates, validateWorkflowConfig };
+export { type AgentUpdateEvent, AnalysisArchive, type AnalysisRecord, type ApplyEventResult, type ArtifactPresence, ClaimManager, type ClaimManagerConfig, type CleanWorkspaceEffect, type DispatchEffect, type EmitLogEffect, type EscalateEffect, type ExecFileFn, InteractionQueue, type LinearGraphQLExtension, LinearGraphQLStub, type LiveSession, MockBackend, ORCHESTRATOR_IDENTITY_FILE, Orchestrator, 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 TickEvent, type TokenTotals, type TriageConfig, type TriageDecision, type TriageSignals, type TriageSkill, type UpdateTokensEffect, type WorkerExitEvent, WorkflowLoader, WorkspaceHooks, WorkspaceManager, applyEvent, artifactPresenceFromIssue, calculateRetryDelay, canDispatch, computeRateLimitDelay, createEmptyState, detectScopeTier, extractTitlePrefix, getAvailableSlots, getDefaultConfig, getPerStateCount, isEligible, launchTUI, loadPublishedIndex, reconcile, renderAnalysisComment, resolveEscalationConfig, resolveOrchestratorId, routeIssue, savePublishedIndex, selectCandidates, sortCandidates, triageIssue, validateWorkflowConfig };