@harness-engineering/orchestrator 0.8.4 → 0.9.0

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import * as _harness_engineering_types from '@harness-engineering/types';
-import { Issue, AgentEvent, WorkflowConfig, TokenUsage, ConcernSignal, ScopeTier, EscalationConfig, IssueRoutingDecision, Result, WorkflowDefinition, BackendDef, RoutingConfig, WorkspaceConfig, HooksConfig, AgentBackend, SessionStartParams, AgentSession, AgentError, TurnParams, TurnResult, CheckScriptDefinition, OutputRetentionConfig, RoutingDecision, RoutingUseCase, ContainerConfig, SecretConfig, AgentConfig, LocalModelStatus, CustomTaskDefinition, 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 { Issue, AgentEvent, WorkflowConfig, TokenUsage, ConcernSignal, ScopeTier, EscalationConfig, IssueRoutingDecision, Result, WorkflowDefinition, BackendDef, RoutingConfig, WorkspaceConfig, HooksConfig, AgentBackend, SessionStartParams, AgentSession, AgentError, TurnParams, TurnResult, CheckScriptDefinition, OutputRetentionConfig, RoutingDecision, RoutingUseCase, ContainerConfig, SecretConfig, AgentConfig, LocalModelStatus, CustomTaskDefinition, MaintenanceConfig, TokenScope, AuthToken, AuthTokenPublic, IndexedFileKind, SessionSearchResult, ReindexStats, SessionSummarizationConfig, SessionSummary, SessionSummaryMeta, SessionsConfig, GatewayEvent, NotificationEnvelope, NotificationDeliveryResult, NotificationSinkConfig, NotificationsConfig } from '@harness-engineering/types';
+import { IssueTrackerClient, Issue as Issue$1, TrackerConfig, eventSourcing, CacheMetricsRecorder, ArchiveHooks, SkillProposal, ProposalGateFinding } 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';
@@ -1044,6 +1044,15 @@ declare class RoadmapTrackerAdapter implements IssueTrackerClient {
      * state and clearing the assignee field.
      */
     releaseIssue(issueId: string): Promise<Result<void, Error>>;
+    /**
+     * Resolve the roadmap store anchored on the configured aggregate file path.
+     * The shard backend is chosen when a sibling `roadmap.d/` exists next to the
+     * file; otherwise the monolith file is read/written whole. Callers guard
+     * `this.config.filePath` before invoking.
+     */
+    private resolveStore;
+    /** Load the roadmap via the store (sharded or monolith), returning a Result. */
+    private loadRoadmap;
     private findFeatureById;
     /**
      * Fetches full issue details for a list of identifiers.
@@ -1062,12 +1071,47 @@ declare class RoadmapTrackerAdapter implements IssueTrackerClient {
 }
 
 /**
- * Interface for Linear GraphQL tool extension.
- * This is a stub implementation for Phase 4.
+ * Interface for a Linear GraphQL tool extension — a thin authenticated client
+ * over Linear's GraphQL API (https://linear.app/developers/graphql).
  */
 interface LinearGraphQLExtension {
+    /**
+     * Execute a GraphQL operation. Resolves to `Ok(data)` (the `data` object of
+     * the GraphQL envelope) on success, or `Err` on a transport failure, a non-2xx
+     * HTTP status, or a GraphQL `errors` array.
+     */
+    query(query: string, variables?: Record<string, unknown>): Promise<Result<unknown, Error>>;
+}
+interface LinearGraphQLClientOptions {
+    /**
+     * Linear authentication token. A personal API key is sent verbatim in the
+     * `Authorization` header; an OAuth access token must be passed already prefixed
+     * with `Bearer ` (Linear's two supported schemes).
+     */
+    apiKey: string;
+    /** Override the GraphQL endpoint (e.g. a proxy). Defaults to Linear's API. */
+    endpoint?: string;
+    /** Injectable fetch for tests; defaults to the global `fetch`. */
+    fetchFn?: typeof fetch;
+}
+/**
+ * Real Linear GraphQL client. Replaces {@link LinearGraphQLStub}, which only
+ * logged the query and returned an empty object. POSTs the operation to Linear's
+ * GraphQL endpoint with the API key, and normalizes the three failure modes
+ * (transport throw, non-2xx HTTP, GraphQL `errors`) into a single `Err`.
+ */
+declare class LinearGraphQLClient implements LinearGraphQLExtension {
+    private readonly apiKey;
+    private readonly endpoint;
+    private readonly fetchFn;
+    constructor(opts: LinearGraphQLClientOptions);
     query(query: string, variables?: Record<string, unknown>): Promise<Result<unknown, Error>>;
 }
+/**
+ * @deprecated Phase-4 placeholder retained for backward compatibility. It logs
+ * the query and returns an empty object; use {@link LinearGraphQLClient} for a
+ * real authenticated client.
+ */
 declare class LinearGraphQLStub implements LinearGraphQLExtension {
     query(query: string, _variables?: Record<string, unknown>): Promise<Result<unknown, Error>>;
 }
@@ -1264,6 +1308,15 @@ type RunOrigin = 'cron' | 'cli' | {
     kind: 'chain';
     upstreamTaskId: string;
 };
+/**
+ * Run mode for a maintenance task (on-demand pipeline, D4).
+ *
+ * - 'fix'    — current cron behavior: mechanical-ai dispatches on findings,
+ *              pure-ai always dispatches, PRs may be opened. Default.
+ * - 'report' — read-only sweep: run the check step, record findings, and take
+ *              the no-dispatch branch — never dispatch a fix agent or open a PR.
+ */
+type RunMode = 'report' | 'fix';
 /**
  * Per-task cost ceiling (Hermes Phase 5).
  *
@@ -1325,6 +1378,15 @@ interface TaskDefinition {
     outputRetention?: OutputRetentionConfig;
     /** Hermes Phase 2 — Marks tasks originating from `customTasks` config. */
     isCustom?: boolean;
+    /**
+     * On-demand maintenance pipeline (D5). When `true`, the task is excluded
+     * from the human "overdue" sweep computed by `selectTasks` — used for
+     * git-mutating housekeeping (`main-sync`, `perf-baselines`,
+     * `session-cleanup`) and one-shot backfills (`proposal-provenance-backfill`)
+     * that are infra hygiene, not developer-facing health signals.
+     * `undefined` (default) → sweep-eligible.
+     */
+    excludeFromHumanSweep?: boolean;
 }
 /**
  * Result of a single maintenance task run.
@@ -1533,6 +1595,13 @@ declare class BackendRouter {
     private validateReferences;
 }
 
+/**
+ * The lanes projection shape, re-exported so the orchestrator can hold a
+ * read-back snapshot without importing the core `eventSourcing` namespace
+ * directly — keeping this module the single orchestrator<->core lane coupling.
+ */
+type PersistedLanes = eventSourcing.LanesProjection;
+
 /**
  * Derives the worktree seed paths from a workflow config when
  * {@link WorkspaceConfig.seedPaths} is not set explicitly.
@@ -1545,6 +1614,20 @@ declare class BackendRouter {
  * otherwise miss it.
  */
 declare function deriveSeedPaths(config: WorkflowConfig): string[];
+/**
+ * Resolve a maintenance `checkCommand` (or housekeeping command) into a runnable
+ * argv. Built-in maintenance task definitions store the command as harness
+ * SUBCOMMAND argv (e.g. `['check-arch']`, `['graph','scan']`); `main-sync`
+ * carries an explicit leading `'harness'` literal. Either way the command must
+ * be executed through the `harness` binary, so:
+ *   - `['check-arch']`           → `['harness', 'check-arch']`
+ *   - `['harness','sync-main']`  → `['harness', 'sync-main']`  (no double-prefix)
+ *   - `[]`                       → `[]`
+ *
+ * The cron daemon resolves `harness` from PATH (the pre-existing assumption that
+ * `main-sync` already relied on).
+ */
+declare function normalizeHarnessCommand(command: string[]): string[];
 /**
  * The central orchestrator that manages the lifecycle of coding agents.
  *
@@ -1656,6 +1739,11 @@ declare class Orchestrator extends EventEmitter {
     private abortControllers;
     /** Guards against overlapping ticks when a tick takes longer than the polling interval */
     private tickInProgress;
+    /** Phase 4 (DLane-5): lanes read back from the durable log on first tick, for
+     *  observability only — NOT fed into reconciliation. Empty until the first tick. */
+    private persistedLanes;
+    /** Ensures the lane read-back diagnostic runs at most once (first tick). */
+    private laneReadbackDone;
     /** Timestamp of the last stale branch sweep (at most once per hour) */
     private lastBranchSweepMs;
     /** Current tick-phase activity visible to the dashboard */
@@ -1698,6 +1786,25 @@ declare class Orchestrator extends EventEmitter {
      * @param effect - The effect to handle
      */
     private handleEffect;
+    /**
+     * Phase 4 (DLane-5): persist an orchestrator lane transition to the durable
+     * core event log at the effect boundary. NEVER throws — `persistLane` returns
+     * an `Err` Result on failure, which is logged and swallowed here so a
+     * lane-persistence failure can never break orchestrator dispatch.
+     */
+    private persistLaneSafe;
+    /**
+     * Phase 4 (DLane-5): read persisted task lanes back from the durable log and
+     * log a one-line summary. Stores the projection on `this.persistedLanes` for
+     * observability. Read-only — never feeds reconciliation, never throws.
+     */
+    private readBackPersistedLanes;
+    /**
+     * Phase 4 (DLane-5): the task lanes most recently read back from the durable
+     * log on startup, exposed for external observability. Read-only — a fresh
+     * `{ tasks: {} }` until the first tick's read-back has run.
+     */
+    getPersistedLanes(): PersistedLanes;
     /**
      * 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
@@ -1980,6 +2087,30 @@ interface CreateBackendOptions {
  */
 declare function createBackend(def: BackendDef, options?: CreateBackendOptions): AgentBackend;
 
+/**
+ * Maintenance backend resolver: map a configured backend NAME to a live
+ * {@link AgentBackend}, or `null` when the name is absent from the loaded
+ * `agent.backends` map. `null` lets the real agent dispatcher no-op honestly
+ * (graceful degradation on a plain checkout) instead of throwing.
+ */
+type BackendResolver = (backendName: string) => AgentBackend | null;
+/**
+ * Build a {@link BackendResolver} from a synthesized `agent.backends` map.
+ *
+ * This is the ONE shared implementation of "resolve a backend name against a
+ * backends map via `createBackend`, else null". It is consumed by BOTH:
+ *   - the cron orchestrator (`createMaintenanceTaskRunner`), passing
+ *     `this.getBackends()`, and
+ *   - the on-demand CLI (`harness maintenance run --fix` →
+ *     `makeResolveBackend`), passing the config it loaded from
+ *     `harness.orchestrator.md`.
+ *
+ * Keeping it in the orchestrator package (next to `createBackend`) avoids the
+ * two call sites drifting. A `null`/`undefined`/empty map yields a resolver
+ * that always returns `null` — the nothing-configured degradation case.
+ */
+declare function makeBackendResolver(backends: Record<string, BackendDef> | null | undefined): BackendResolver;
+
 /**
  * Zod schema for `BackendDef` (Spec 2 — multi-backend routing).
  *
@@ -2426,6 +2557,520 @@ interface CustomTaskValidatorDeps {
  */
 declare function validateCustomTasks(customTasks: Record<string, CustomTaskDefinition> | undefined, builtIns: readonly TaskDefinition[], deps?: CustomTaskValidatorDeps): Result<void, CustomTaskValidationError[]>;
 
+/** Selection filter for `selectTasks`. `now` is injected for determinism. */
+interface TaskSelectionFilter {
+    mode: 'overdue' | 'all' | 'ids';
+    /** Required when `mode === 'ids'`; ignored otherwise. */
+    ids?: string[];
+    /** Reference instant — never read from the wall clock internally. */
+    now: Date;
+}
+/**
+ * Select the maintenance tasks to run for an on-demand sweep (D3/D5).
+ * Operates only on sweep-eligible tasks (`excludeFromHumanSweep !== true`)
+ * in every mode. Deterministic under the injected `filter.now`.
+ *
+ * - `overdue`: eligible tasks with no satisfying run since their previous fire.
+ * - `all`:     every eligible task.
+ * - `ids`:     the eligible subset named in `filter.ids` (a named excluded id
+ *              is dropped, honoring "excluded tasks never run in either path").
+ *              `filter.ids` is treated as a SET membership test, not an ordered
+ *              request list: results preserve the input `tasks` array order, not
+ *              the order ids appear in `filter.ids`. Duplicate ids are collapsed
+ *              and a task is returned at most once. Callers that need request
+ *              order must reorder the result themselves.
+ */
+declare function selectTasks(tasks: TaskDefinition[], history: RunResult[], filter: TaskSelectionFilter): TaskDefinition[];
+
+/**
+ * Hermes Phase 2 — Result of running an arbitrary check script.
+ *
+ * Structurally compatible with `CheckCommandResult` (`task-runner.ts`) so
+ * `TaskRunner` can consume it through the same interface, plus a parsed
+ * structured envelope and the captured stderr stream. `structured` is
+ * `null` when no JSON status line was found on stdout. The shape is
+ * declared locally (not imported from `task-runner.ts`) to keep the
+ * module dependency one-way: `task-runner.ts` depends on
+ * `check-script-runner.ts`, never the reverse.
+ */
+interface CheckScriptResult {
+    passed: boolean;
+    findings: number;
+    /** Raw stdout. Field name matches `CheckCommandResult.output` for compatibility. */
+    output: string;
+    stderr: string;
+    structured: CheckScriptStatusEnvelope | null;
+}
+interface CheckScriptStatusEnvelope {
+    status: 'ok' | 'findings' | 'skip' | 'error';
+    findings?: number;
+    wakeAgent?: boolean;
+    message?: string;
+    outputs?: Record<string, unknown>;
+}
+/**
+ * Spawns an arbitrary executable for the mechanical/report/housekeeping
+ * check step. Honors the structured JSON status envelope (last non-empty
+ * stdout line) per Hermes Phase 2 D6. Falls back to the legacy heuristic
+ * regex when no JSON envelope is present.
+ *
+ * The runner is intentionally simple and shells out via `execFile` (no
+ * shell, no `sh -c`) — `args` are passed verbatim to avoid argument
+ * injection from operator-supplied config.
+ */
+declare class CheckScriptRunner {
+    private cwd;
+    constructor(cwd: string);
+    run(spec: CheckScriptDefinition, cwd?: string): Promise<CheckScriptResult>;
+}
+
+/**
+ * Hermes Phase 2 — Reads an inline-skill body by name. Wraps the host's
+ * skill registry; absent skills resolve to `null` so the resolver can
+ * warn-and-skip instead of throwing.
+ */
+interface InlineSkillReader {
+    read(skillName: string): Promise<string | null>;
+}
+interface ContextResolverOptions {
+    outputStore: TaskOutputStore;
+    skillReader?: InlineSkillReader;
+    logger?: MaintenanceLogger;
+    /** Per-upstream truncation bound. Default: 2000 chars. */
+    perUpstreamMaxChars?: number;
+}
+/**
+ * Resolves Hermes Phase 2 prompt-context inputs for a maintenance task:
+ *
+ *   - `resolveContextFrom(taskIds, opts)`: pulls each upstream's latest
+ *     output from the store, applies stale/missing markers, and emits a
+ *     `## Upstream context` markdown block.
+ *
+ *   - `resolveInlineSkills(skillNames, budgetTokens)`: pulls each skill's
+ *     markdown body via the registry, applies a per-skill char-count
+ *     budget (4 chars ≈ 1 token), warns-then-truncates on overflow, and
+ *     emits a `## Reference skills` markdown block.
+ *
+ * Both methods return an empty string when their inputs are absent so
+ * callers can `prompt = skills + upstream + base` without conditional
+ * scaffolding.
+ */
+declare class ContextResolver {
+    private outputStore;
+    private skillReader;
+    private logger;
+    private perUpstreamMaxChars;
+    constructor(options: ContextResolverOptions);
+    resolveContextFrom(upstreamTaskIds: string[] | undefined, options?: {
+        maxAgeMinutes?: number;
+    }): Promise<string>;
+    resolveInlineSkills(skillNames: string[] | undefined, budgetTokens?: number): Promise<string>;
+    private formatUpstream;
+}
+
+/**
+ * Interface for running CLI check commands in-process.
+ * Each method returns a structured result with a findings count.
+ */
+interface CheckCommandRunner {
+    /**
+     * Runs a check command and returns its structured output.
+     * @param command - CLI command args (e.g., ['check-arch'])
+     * @param cwd - Working directory
+     * @returns Object with findings count and whether the check passed
+     */
+    run(command: string[], cwd: string): Promise<CheckCommandResult>;
+}
+interface CheckCommandResult {
+    passed: boolean;
+    findings: number;
+    /** Raw output for logging/reporting */
+    output: string;
+    /**
+     * True when the check command could NOT be executed to a usable result —
+     * the process failed to spawn (ENOENT), the subcommand was unknown, or it
+     * crashed with no parseable findings count. This is distinct from a check
+     * that ran fine and legitimately reported findings (`passed: false`,
+     * `findings > 0`). The TaskRunner maps `executionFailed` onto
+     * `status: 'failure'` so an un-runnable check is never masked as a
+     * successful 1-finding run (ADR 0050 — exit-1-on-check-crash). Omitted /
+     * `undefined` is treated as `false` for backward compatibility with runners
+     * that predate this field.
+     */
+    executionFailed?: boolean;
+}
+/**
+ * Interface for dispatching an AI agent to fix issues.
+ * Wraps AgentRunner.runSession() with maintenance-specific parameters.
+ */
+interface AgentDispatcher {
+    /**
+     * Dispatch an AI agent to fix issues on a branch.
+     * @param skill - Skill name to dispatch (e.g., 'harness-arch-fix')
+     * @param branch - Branch to work on
+     * @param backendName - Backend name to use (e.g., 'local', 'claude')
+     * @param cwd - Working directory (worktree path)
+     * @param options - Hermes Phase 2: optional `promptContext` prepended to
+     *                  the agent's system prompt (inlined skills + upstream
+     *                  outputs). The dispatcher MAY ignore this field on
+     *                  backends that don't support context injection; the
+     *                  TaskRunner persists it independently for observability.
+     * @returns Whether the agent produced any commits
+     */
+    dispatch(skill: string, branch: string, backendName: string, cwd: string, options?: AgentDispatchOptions): Promise<AgentDispatchResult>;
+}
+interface AgentDispatchOptions {
+    /** Hermes Phase 2 — prompt context (inlined skills + upstream outputs). */
+    promptContext?: string;
+}
+interface AgentDispatchResult {
+    producedCommits: boolean;
+    fixed: number;
+}
+/**
+ * Interface for running housekeeping commands directly.
+ */
+interface CommandExecutor {
+    /**
+     * Executes a command directly (no AI). Returns captured stdout so
+     * housekeeping tasks emitting a JSON status line (e.g. `sync-main --json`)
+     * can be parsed by the runner.
+     *
+     * @param command - Command args (e.g., ['cleanup-sessions'])
+     * @param cwd - Working directory
+     */
+    exec(command: string[], cwd: string): Promise<CommandExecResult>;
+}
+interface CommandExecResult {
+    /** Captured stdout. May be empty for legacy housekeeping commands. */
+    stdout: string;
+}
+/**
+ * Interface for managing branches and PRs for maintenance tasks.
+ * Matches PRManager's public API shape for DI.
+ */
+interface PRLifecycleManager {
+    ensureBranch(branchName: string, baseBranch: string): Promise<{
+        created: boolean;
+        recreated: boolean;
+    }>;
+    ensurePR(task: TaskDefinition, runSummary: string): Promise<{
+        prUrl: string;
+        prUpdated: boolean;
+    }>;
+}
+interface TaskRunnerOptions {
+    config: MaintenanceConfig;
+    checkRunner: CheckCommandRunner;
+    agentDispatcher: AgentDispatcher;
+    commandExecutor: CommandExecutor;
+    /** Project root directory for running commands */
+    cwd: string;
+    /** Optional PR lifecycle manager for branch/PR operations */
+    prManager?: PRLifecycleManager;
+    /** Base branch for PR operations (defaults to 'main') */
+    baseBranch?: string;
+    /**
+     * Hermes Phase 2 — Optional check-script runner. When a task declares
+     * `checkScript`, the runner consults this instead of `checkRunner`.
+     * Required for any custom task that uses `checkScript`; tests that don't
+     * exercise custom tasks may omit it.
+     */
+    checkScriptRunner?: CheckScriptRunner;
+    /**
+     * Hermes Phase 2 — Optional context resolver providing `contextFrom`
+     * upstream injection and `inlineSkills` payload assembly.
+     */
+    contextResolver?: ContextResolver;
+    /**
+     * Hermes Phase 2 — Persists per-task outputs (stdout / structured /
+     * resolved context) at the end of each run.
+     */
+    outputStore?: TaskOutputStore;
+}
+/**
+ * TaskRunner executes a single maintenance task based on its type.
+ *
+ * Execution paths:
+ * - mechanical-ai: run check -> if findings, dispatch AI agent
+ * - pure-ai: always dispatch AI agent
+ * - report-only: run check, record findings, no AI
+ * - housekeeping: run command directly, no AI
+ */
+declare class TaskRunner {
+    private config;
+    private checkRunner;
+    private agentDispatcher;
+    private commandExecutor;
+    private cwd;
+    private prManager;
+    private baseBranch;
+    private checkScriptRunner;
+    private contextResolver;
+    private outputStore;
+    constructor(options: TaskRunnerOptions);
+    /**
+     * Run a maintenance task and return the result.
+     * Dispatches to the appropriate execution path based on task type.
+     * Never throws -- errors are captured in the RunResult.
+     *
+     * @param task - Resolved task definition.
+     * @param origin - Hermes Phase 2 trigger-source tag; defaults to `'cron'`
+     *                 when called from the scheduler path.
+     */
+    run(task: TaskDefinition, origin?: RunOrigin, mode?: RunMode): Promise<RunResult>;
+    private persistOutput;
+    /**
+     * Run the check step using whichever runner the task asks for. Custom
+     * tasks that declare `checkScript` go through the Hermes Phase 2
+     * `CheckScriptRunner`; built-ins (and customs that use the legacy
+     * `checkCommand` shape) go through the original heuristic runner.
+     */
+    private runCheckStep;
+    /**
+     * Hermes Phase 2 — Compose the agent prompt-context block from inlined
+     * skills + upstream task outputs. Returns an empty string when nothing
+     * is configured (or when the resolver is absent), which is the safe
+     * no-op default.
+     */
+    private composePromptContext;
+    /**
+     * Mechanical-AI: run check (legacy or Phase 2 script), dispatch AI agent
+     * only if fixable findings exist; persist captured stdout/stderr/context
+     * via the output store on the way out.
+     */
+    private runMechanicalAI;
+    /**
+     * Pure-AI: always dispatch agent with configured skill.
+     */
+    private runPureAI;
+    /**
+     * Report-only: run check (legacy or Phase 2 script), record metrics, no AI dispatch.
+     *
+     * Honors the JSON status contract emitted by Phase 4/5 CLIs (`harness pulse run`
+     * and `harness compound scan-candidates` in `--non-interactive` mode):
+     *   {"status":"success"|"skipped"|"failure"|"no-issues",
+     *    "candidatesFound"?: number, "error"?: string, "reason"?: string}
+     *
+     * Legacy report-only tasks emit free-form output and fall through to 'success'.
+     */
+    private runReportOnly;
+    /**
+     * Housekeeping: run command directly, no AI, no PR.
+     *
+     * Captures stdout and parses a trailing JSON status line if present.
+     * Recognized contracts:
+     *   - Phase 4/5 status contract (e.g., harness pulse run): success/skipped/failure/no-issues
+     *   - sync-main contract: updated/no-op/skipped/error → mapped onto the run-result status
+     * Legacy housekeeping commands that emit no JSON keep the prior behavior:
+     *   status: 'success', findings: 0.
+     *
+     * Hermes Phase 2: a `checkScript` may replace `checkCommand` for housekeeping
+     * tasks; the runner falls through to the same JSON-status parsing path.
+     */
+    private runHousekeeping;
+    /**
+     * Resolve which AI backend name to use for a given task.
+     * Priority: per-task override > global config > 'local' default.
+     */
+    private resolveBackend;
+    private failureResult;
+    /**
+     * A precondition-gated check (e.g. `predict` with <3 snapshots, or a
+     * graph-backed check before `harness scan`). The command is correctly
+     * configured; the repo just lacks the state it needs. Reported as `skipped`
+     * — distinct from a hard `failure` — carrying the refusal line as the reason
+     * (surfaced in the run-report summary column). ADR 0050.
+     */
+    private skippedResult;
+}
+/**
+ * Classification of a check that a `CheckCommandRunner` flagged
+ * `executionFailed` (non-zero exit / spawn error with no parseable finding
+ * count). The runners cannot tell these three cases apart with a single
+ * boolean, so the TaskRunner re-classifies the captured output here — keeping
+ * the logic in ONE shared place consumed by BOTH the cron orchestrator and the
+ * on-demand CLI (they each own a thin `CheckCommandRunner` but share this
+ * `TaskRunner`). See ADR 0050 (report-first / execution-honesty).
+ *
+ * - `unrunnable`  → the subcommand could not execute at all (unknown command,
+ *                   ENOENT, missing module, empty output). Maps to `failure`.
+ * - `precondition`→ the subcommand ran but refused because required state is
+ *                   absent in this repo (e.g. `predict` needs ≥3 snapshots;
+ *                   graph-backed checks need `harness scan` first). This is NOT
+ *                   a misconfiguration or a breakage — maps to `skipped` with a
+ *                   reason so dashboards/cron don't cry wolf.
+ * - `ran-no-count`→ the subcommand ran and exited non-zero to SIGNAL drift but
+ *                   emitted no machine-parseable count (e.g. `cleanup`,
+ *                   `check-docs`). A check that ran and flagged work is not an
+ *                   execution failure — maps to a real (recovered or assumed)
+ *                   finding count, never `failure`.
+ */
+type CheckFailureKind = 'unrunnable' | 'precondition' | 'ran-no-count';
+interface CheckFailureClassification {
+    kind: CheckFailureKind;
+    /** Human-readable reason, populated for `precondition` (the refusal line). */
+    reason?: string;
+}
+/**
+ * Parse an EXPLICIT finding count from output the primary `N keyword` parser in
+ * the `CheckCommandRunner` missed — it only matches "45 issues", not the
+ * "Entropy issues: 32264" (count-after-keyword) shape. Returns `null` when no
+ * explicit count is present (vs `recoverFindingsCount`, which defaults to 1).
+ *
+ * A recoverable explicit count is the strongest possible signal that a check
+ * actually RAN and produced findings, so the classifier trusts it over any
+ * scary-looking words ("ENOENT", "not found") buried in the findings body.
+ */
+declare function explicitFindingsCount(output: string): number | null;
+/**
+ * Recover a finding count from a `ran-no-count` output, falling back to 1 — the
+ * check ran and flagged something, exact count unknown.
+ */
+declare function recoverFindingsCount(output: string): number;
+declare function classifyCheckExecutionFailure(output: string): CheckFailureClassification;
+
+/**
+ * Dependencies for {@link createAgentDispatcher}. All side-effecting collaborators
+ * are injected so the dispatcher is unit-testable with a MockBackend and a fake
+ * git seam (no real agent process, no real repository).
+ */
+interface AgentDispatcherDeps {
+    /**
+     * Resolve a configured backend by name (e.g. `'local'`, `'claude'`). Returns
+     * `null` when the name is unknown/unconfigured — the dispatcher then no-ops
+     * rather than throwing, so a misconfigured maintenance task degrades to
+     * "produced nothing" instead of crashing the scheduler.
+     */
+    resolveBackend: (backendName: string) => AgentBackend | null;
+    /** Run `git <args>` in `cwd`, returning trimmed stdout (throws on failure). */
+    git: (args: string[], cwd: string) => string;
+    /** Max agent turns per dispatch. Defaults to 10. */
+    maxTurns?: number;
+    logger: {
+        info: (message: string, meta?: Record<string, unknown>) => void;
+        warn: (message: string, meta?: Record<string, unknown>) => void;
+    };
+}
+/**
+ * Wire the maintenance {@link AgentDispatcher} to a real agent session.
+ *
+ * Replaces the previous stub (which only logged and returned `producedCommits:
+ * false`). Resolves the named backend, drives a multi-turn {@link AgentRunner}
+ * session over the skill prompt in the worktree, then measures whether the agent
+ * actually committed anything by diffing `HEAD` before/after. Commit count — not
+ * the agent's self-report — is the source of truth for `fixed`.
+ */
+declare function createAgentDispatcher(deps: AgentDispatcherDeps): AgentDispatcher;
+
+/**
+ * Options for the MaintenanceReporter.
+ */
+interface MaintenanceReporterOptions {
+    /** Directory where history.json is persisted (default: '.harness/maintenance/') */
+    persistDir?: string;
+    /** Logger for structured error/info output. Falls back to console if not provided. */
+    logger?: MaintenanceLogger;
+}
+declare class MaintenanceReporter {
+    private persistDir;
+    private logger;
+    private history;
+    constructor(options?: MaintenanceReporterOptions);
+    /**
+     * Load history from disk. Creates the persist directory if it does not exist.
+     * Errors in persistence are logged to stderr, not thrown.
+     */
+    load(): Promise<void>;
+    /**
+     * Record a run result. Appends to in-memory history (most recent first),
+     * caps at MAX_HISTORY, and writes to disk asynchronously.
+     */
+    record(result: RunResult): Promise<void>;
+    /**
+     * Returns a paginated slice of the run history (most recent first).
+     */
+    getHistory(limit: number, offset: number): RunResult[];
+    /**
+     * Write history to disk. Errors are logged, not thrown.
+     */
+    private persist;
+}
+
+/**
+ * Generous stdout/stderr capture ceiling for spawned maintenance checks. The
+ * Node `execFile` default (1 MB) is far too small for verbose checks — e.g.
+ * `harness cleanup` on a large repo emits ~8 MB — and an exceeded buffer
+ * rejects with EMPTY stdout/stderr, which the runner would misread as a check
+ * that produced no output (a false execution failure). 64 MB leaves ample
+ * headroom while still bounding memory.
+ */
+declare const MAINTENANCE_CHECK_MAX_BUFFER: number;
+/**
+ * Per-check wall-clock budget. Raised from the original 120 s because heavy
+ * whole-repo checks legitimately need longer on large monorepos — `harness
+ * cleanup` (all entropy types) takes ~165 s here — and a too-tight timeout
+ * SIGTERMs the child, yielding empty output that the runner can only read as a
+ * (false) execution failure. 300 s keeps a bound while letting real checks
+ * finish.
+ */
+declare const MAINTENANCE_CHECK_TIMEOUT_MS = 300000;
+/** A resolved child-process invocation: the file to spawn and its argv. The two
+ * callers build this differently (CLI: `process.execPath` + the CLI's own entry
+ * script; cron: the `harness` binary on PATH) but the spawn/parse core is one. */
+interface HarnessSpawn {
+    file: string;
+    args: string[];
+}
+/** The shape of an `execFile` rejection the timeout/classification logic reads. */
+interface ExecFileError {
+    stdout?: string | Buffer;
+    stderr?: string | Buffer;
+    killed?: boolean;
+    signal?: string | null;
+    code?: string | number | null;
+}
+/** Injectable `execFile` (promisified) so tests can drive the spawn-error,
+ * clean-run, findings, and timeout branches without real subprocesses. */
+type ExecFileAsyncFn = (file: string, args: string[], options: {
+    cwd: string;
+    timeout: number;
+    maxBuffer: number;
+}) => Promise<{
+    stdout: string | Buffer;
+    stderr?: string | Buffer;
+}>;
+interface RunHarnessCheckOptions {
+    /** Injected for tests; defaults to the real promisified `execFile`. */
+    execFileAsync?: ExecFileAsyncFn;
+    /** Per-check wall-clock budget (default {@link MAINTENANCE_CHECK_TIMEOUT_MS}). */
+    timeoutMs?: number;
+    /** stdout/stderr capture ceiling (default {@link MAINTENANCE_CHECK_MAX_BUFFER}). */
+    maxBuffer?: number;
+}
+/** Best-effort detection of a child killed by the `execFile` timeout (SIGTERM /
+ * ETIMEDOUT / killed flag). */
+declare function isCheckTimeoutError(e: ExecFileError): boolean;
+/**
+ * Spawn a resolved harness check invocation and classify its result into a
+ * {@link CheckCommandResult}. Behavior (shared by cron + CLI):
+ *
+ *   - clean exit, parseable count → `{ findings: N }` (or 0 on a parse-miss; a
+ *     check that ran and said nothing is clean, not "1 finding").
+ *   - non-zero exit WITH a parseable count → real findings (`executionFailed:
+ *     false`) — e.g. `check-arch` exits 1 with "45 issues".
+ *   - non-zero exit / spawn error with NO parseable count → `executionFailed:
+ *     true`, findings 0 (a broken check is not "1 finding"; ADR 0050).
+ *   - TIMEOUT (SIGTERM/ETIMEDOUT) → `executionFailed: true`, findings 0, with a
+ *     distinct "check timed out after Nms" marker APPENDED to whatever the child
+ *     flushed. A timed-out check did not complete: even partial parseable output
+ *     ("5 issues") it flushed before SIGTERM is truncated and untrustworthy, so
+ *     the timeout is classified ahead of any finding count — never a "ran-no-
+ *     count" success. {@link import('./task-runner').classifyCheckExecutionFailure}
+ *     matches this marker before `explicitFindingsCount`.
+ */
+declare function runHarnessCheck(spawn: HarnessSpawn, cwd: string, opts?: RunHarnessCheckOptions): Promise<CheckCommandResult>;
+
 interface CreateTokenInput {
     name: string;
     scopes: TokenScope[];
@@ -2875,4 +3520,4 @@ declare function emitProposalCreated(bus: EventEmitter, proposal: SkillProposal)
 declare function emitProposalApproved(bus: EventEmitter, proposal: SkillProposal): void;
 declare function emitProposalRejected(bus: EventEmitter, proposal: SkillProposal): void;
 
-export { type AgentUpdateEvent, AnalysisArchive, type AnalysisRecord, type ApplyEventResult, type ArtifactPresence, type AttemptStats, BUILT_IN_TASKS, BackendDefSchema, 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, LocalModelResolver, type LocalModelResolverOptions, 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 ResolverLogger, type RetryEntry, type RetryFiredEvent, RoadmapTrackerAdapter, RoutingConfigSchema, RoutingValueSchema, 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, defaultFetchModels, deriveSeedPaths, detectScopeTier, discoverSkillCatalog, discoverSkillCatalogNames, emitProposalApproved, emitProposalCreated, emitProposalRejected, extractHighlights, extractTitlePrefix, getAvailableSlots, getDefaultConfig, getPerStateCount, indexSessionDirectory, isEligible, isSummaryEnabled, launchTUI, loadPublishedIndex, migrateAgentConfig, normalizeFts5Query, normalizeLocalModel, openSearchIndex, promote, reconcile, reindexFromArchive, renderAnalysisComment, renderLlmSummaryMarkdown, renderPRComment, resolveEscalationConfig, resolveOrchestratorId, routeIssue, routingWarnings, runGate, savePublishedIndex, searchIndexPath, selectCandidates, sortCandidates, summarizeArchivedSession, syncMain, triageIssue, truncateForBudget, validateCustomTasks, validateWorkflowConfig, wireNotificationSinks, wrapAsEnvelope };
+export { type AgentDispatchResult, type AgentDispatcher, type AgentDispatcherDeps, type AgentUpdateEvent, AnalysisArchive, type AnalysisRecord, type ApplyEventResult, type ArtifactPresence, type AttemptStats, BUILT_IN_TASKS, BackendDefSchema, type BackendResolver, BackendRouter, type BackendRouterOptions, type BaseRefFallbackEvent, type BuildArchiveHooksOptions, type CheckCommandResult, type CheckCommandRunner, type CheckFailureClassification, type CheckFailureKind, CheckScriptRunner, ClaimManager, type ClaimManagerConfig, type CleanWorkspaceEffect, type CommandExecResult, type CommandExecutor, type CreateTokenInput, type CreateTokenResult, type CustomTaskValidationError, type DispatchEffect, type EmitLogEffect, type EscalateEffect, type ExecFileAsyncFn, type ExecFileError, type ExecFileFn$1 as ExecFileFn, type FromConfigOptions, GateNotReadyError, type GateResult, GateRunError, type HarnessSpawn, type Highlight, type HighlightsInfo, type IndexedDoc, InteractionQueue, LinearGraphQLClient, type LinearGraphQLClientOptions, type LinearGraphQLExtension, LinearGraphQLStub, type LiveSession, LocalModelResolver, type LocalModelResolverOptions, MAINTENANCE_CHECK_MAX_BUFFER, MAINTENANCE_CHECK_TIMEOUT_MS, MAX_ATTEMPTS, MaintenanceReporter, type MaintenanceReporterOptions, type MigrationResult, MockBackend, type NotificationSink, type NotificationSinkDeliverInput, ORCHESTRATOR_IDENTITY_FILE, Orchestrator, OrchestratorBackendFactory, type OrchestratorBackendFactoryOptions, type OrchestratorContext, type OrchestratorEvent, type OrchestratorState, PRDetector, type PRDetectorLogger, type PRLifecycleManager, type PendingInteraction, type PersistedOutputEntry, PromotionError, type PromotionResult, PromptRenderer, type ProposalApprovedData, type ProposalCreatedData, type ProposalRejectedData, type PublishedIndex, type QueueInsertInput, type QueueRow, type QueueStats, RETRY_DELAYS_MS, type RateLimitSnapshot as RateLimitComputeSnapshot, type RateLimitConfig, type RateLimitSnapshot$1 as RateLimitSnapshot, type RegistryEntry, type ReleaseClaimEffect, type ResolverLogger, type RetryEntry, type RetryFiredEvent, RoadmapTrackerAdapter, RoutingConfigSchema, RoutingValueSchema, type RunAttemptPhase, type RunHarnessCheckOptions, type RunMode, type RunOrigin, type RunResult, type RunningEntry, type ScheduleRetryEffect, type SearchOptions, type SideEffect, SinkConfigError, SinkRegistry, type SkillCatalogEntry, SlackSink, type SlackSinkOptions, SqliteSearchIndex, type StallDetectedEvent, type StopEffect, type StreamManifest, StreamRecorder, type SummarizeContext, type SummarizeResult, type SyncMainOptions, type SyncMainResult, type SyncSkipReason, type TaskDefinition, TaskOutputStore, TaskRunner, type TaskRunnerOptions, type TaskSelectionFilter, type TaskType, type TickEvent, TokenStore, type TokenTotals, type TriageConfig, type TriageDecision, type TriageSignals, type TriageSkill, type UpdateTokensEffect, type ValidateWorkflowConfigOptions, type ValidatedWorkflowConfig, WebhookQueue, type WorkerExitEvent, WorkflowLoader, WorkspaceHooks, WorkspaceManager, type WorkspaceManagerOptions, applyEvent, artifactPresenceFromIssue, buildArchiveHooks, calculateRetryDelay, canDispatch, classifyCheckExecutionFailure, computeRateLimitDelay, createAgentDispatcher, createBackend, createEmptyState, crossFieldRoutingIssues, defaultFetchModels, deriveSeedPaths, detectScopeTier, discoverSkillCatalog, discoverSkillCatalogNames, emitProposalApproved, emitProposalCreated, emitProposalRejected, explicitFindingsCount, extractHighlights, extractTitlePrefix, getAvailableSlots, getDefaultConfig, getPerStateCount, indexSessionDirectory, isCheckTimeoutError, isEligible, isSummaryEnabled, launchTUI, loadPublishedIndex, makeBackendResolver, migrateAgentConfig, normalizeFts5Query, normalizeHarnessCommand, normalizeLocalModel, openSearchIndex, promote, reconcile, recoverFindingsCount, reindexFromArchive, renderAnalysisComment, renderLlmSummaryMarkdown, renderPRComment, resolveEscalationConfig, resolveOrchestratorId, routeIssue, routingWarnings, runGate, runHarnessCheck, savePublishedIndex, searchIndexPath, selectCandidates, selectTasks, sortCandidates, summarizeArchivedSession, syncMain, triageIssue, truncateForBudget, validateCustomTasks, validateWorkflowConfig, wireNotificationSinks, wrapAsEnvelope };