@harness-engineering/orchestrator 0.4.6 → 0.6.0

package/dist/index.d.mts

@@ -1,6 +1,6 @@
-import { Issue, AgentEvent, WorkflowConfig, TokenUsage, ConcernSignal, ScopeTier, EscalationConfig, RoutingDecision, Result, WorkflowDefinition, WorkspaceConfig, HooksConfig, AgentBackend, SessionStartParams, AgentSession, AgentError, TurnParams, TurnResult, BackendDef, RoutingConfig, RoutingUseCase, ContainerConfig, SecretConfig, AgentConfig, TokenScope, AuthToken, AuthTokenPublic } from '@harness-engineering/types';
-import { IssueTrackerClient, Issue as Issue$1, TrackerConfig, CacheMetricsRecorder } from '@harness-engineering/core';
-import { EnrichedSpec, ComplexityScore, SimulationResult, IntelligencePipeline, WeightedRecommendation } from '@harness-engineering/intelligence';
+import { Issue, AgentEvent, WorkflowConfig, TokenUsage, ConcernSignal, ScopeTier, EscalationConfig, RoutingDecision, Result, WorkflowDefinition, WorkspaceConfig, HooksConfig, AgentBackend, SessionStartParams, AgentSession, AgentError, TurnParams, TurnResult, CheckScriptDefinition, OutputRetentionConfig, BackendDef, RoutingConfig, RoutingUseCase, ContainerConfig, SecretConfig, AgentConfig, CustomTaskDefinition, TokenScope, AuthToken, AuthTokenPublic, IndexedFileKind, SessionSearchResult, ReindexStats, SessionSummarizationConfig, SessionSummary, SessionSummaryMeta, SessionsConfig, GatewayEvent, NotificationEnvelope, NotificationDeliveryResult, NotificationSinkConfig, NotificationsConfig } from '@harness-engineering/types';
+import { IssueTrackerClient, Issue as Issue$1, TrackerConfig, CacheMetricsRecorder, ArchiveHooks, SkillProposal, ProposalGateFinding } from '@harness-engineering/core';
+import { EnrichedSpec, ComplexityScore, SimulationResult, IntelligencePipeline, WeightedRecommendation, AnalysisProvider } from '@harness-engineering/intelligence';
 import { GraphStore } from '@harness-engineering/graph';
 import { execFile } from 'node:child_process';
 import { EventEmitter } from 'node:events';
@@ -1084,8 +1084,10 @@ declare class PromptRenderer {
 
 /**
  * Internal types for the maintenance module.
- * Public config types (MaintenanceConfig, TaskOverride) live in @harness-engineering/types.
+ * Public config types (MaintenanceConfig, TaskOverride, CustomTaskDefinition,
+ * CheckScriptDefinition, OutputRetentionConfig) live in @harness-engineering/types.
  */
+
 /**
  * Classification of maintenance task execution strategy.
  *
@@ -1095,6 +1097,85 @@ declare class PromptRenderer {
  * - housekeeping: Run a mechanical command directly; no AI, no PR.
  */
 type TaskType = 'mechanical-ai' | 'pure-ai' | 'report-only' | 'housekeeping';
+/**
+ * Hermes Phase 2 — Provenance tag identifying the trigger source of a run.
+ *
+ * Set by the entry point, never user-configurable:
+ *   - 'cron'                      — scheduled by MaintenanceScheduler
+ *   - 'cli'                       — `harness maintenance run <id>`
+ *   - { kind: 'api', tokenName }  — Gateway API trigger (Phase 0)
+ *   - { kind: 'chain', upstreamTaskId } — fired by a downstream `contextFrom`
+ *                                          dependency (reserved; not yet wired)
+ */
+type RunOrigin = 'cron' | 'cli' | {
+    kind: 'api';
+    tokenName: string;
+} | {
+    kind: 'chain';
+    upstreamTaskId: string;
+};
+/**
+ * Per-task cost ceiling (Hermes Phase 5).
+ *
+ * When set, the orchestrator's `CostCeilingMonitor` tracks cumulative
+ * agent spend for the task and aborts dispatch on exceed (D6 — abort
+ * is advisory at the turn boundary).
+ */
+interface TaskCostCeiling {
+    /** Hard cap in USD. Cumulative spend > maxUsd fires the abort path. */
+    maxUsd: number;
+    /** Warn threshold expressed as a percentage of `maxUsd` (1–99). */
+    warnAtPct?: number;
+}
+/**
+ * Definition of a maintenance task (built-in or Phase 2 custom).
+ *
+ * Custom-task-only fields (`checkScript`, `inlineSkills`, `inlineSkillsBudgetTokens`,
+ * `contextFrom`, `contextFromMaxAgeMinutes`, `outputRetention`, `isCustom`) are
+ * populated by the scheduler when merging `MaintenanceConfig.customTasks` into the
+ * resolved task list. Built-ins leave them unset and the runner falls through to
+ * the legacy execution paths unchanged.
+ */
+interface TaskDefinition {
+    /** Unique identifier for this task (e.g., 'arch-violations') */
+    id: string;
+    /** Execution strategy */
+    type: TaskType;
+    /** Human-readable description */
+    description: string;
+    /** Default cron expression (e.g., '0 2 * * *' for daily at 2am) */
+    schedule: string;
+    /** Branch name for PRs, or null for report-only/housekeeping tasks */
+    branch: string | null;
+    /** CLI command args for the mechanical check step (mechanical-ai and report-only) */
+    checkCommand?: string[];
+    /** Skill name to dispatch for AI fix (mechanical-ai and pure-ai) */
+    fixSkill?: string;
+    /**
+     * Per-task cost ceiling (Hermes Phase 5). When set, cumulative agent
+     * spend across all turns dispatched for this task is tracked; the
+     * orchestrator aborts dispatch on `maxUsd` exceedance with
+     * `RunResult.error === 'cost_ceiling_exceeded'`. Default: unset = no cap.
+     */
+    costCeiling?: TaskCostCeiling;
+    /**
+     * Hermes Phase 2 — Arbitrary-executable check (replaces `checkCommand`).
+     * Mutually-exclusive with `checkCommand`; validator rejects both.
+     */
+    checkScript?: CheckScriptDefinition;
+    /** Hermes Phase 2 — Skill names whose markdown is inlined into the agent prompt. */
+    inlineSkills?: string[];
+    /** Hermes Phase 2 — Token-budget cap for inlined skills. Default: 8000. */
+    inlineSkillsBudgetTokens?: number;
+    /** Hermes Phase 2 — Upstream task IDs whose latest output feeds prompt context. */
+    contextFrom?: string[];
+    /** Hermes Phase 2 — Max upstream-output age (minutes). Default: 1440. */
+    contextFromMaxAgeMinutes?: number;
+    /** Hermes Phase 2 — Output retention overrides. */
+    outputRetention?: OutputRetentionConfig;
+    /** Hermes Phase 2 — Marks tasks originating from `customTasks` config. */
+    isCustom?: boolean;
+}
 /**
  * Result of a single maintenance task run.
  */
@@ -1117,6 +1198,21 @@ interface RunResult {
     prUpdated: boolean;
     /** Error message if status is 'failure' */
     error?: string;
+    /**
+     * Cumulative agent spend in USD for this run (Hermes Phase 5).
+     *
+     * Always present (defaults to 0). Populated by the
+     * `CostCeilingMonitor` from per-turn `TokenUsage` × `ModelPricing`.
+     * When the run aborted on cost-ceiling exceed, `status === 'failure'`
+     * and `error === 'cost_ceiling_exceeded'`.
+     */
+    costUsd?: number;
+    /**
+     * Hermes Phase 2 — Provenance tag set by the entry point.
+     * Older orchestrators may emit this field absent; renderers should fall
+     * back to `'—'` rather than crash.
+     */
+    origin?: RunOrigin;
 }
 /**
  * Schedule entry for a single task, used in MaintenanceStatus.
@@ -1226,6 +1322,8 @@ declare class Orchestrator extends EventEmitter {
     private cacheMetrics?;
     private otlpExporter?;
     private telemetryFanoutOff?;
+    private notificationsRegistry?;
+    private notificationFanoutOff?;
     private orchestratorIdPromise;
     private recorder;
     private intelligenceRunner;
@@ -1341,6 +1439,15 @@ declare class Orchestrator extends EventEmitter {
      * Informs the state machine that an agent worker has exited.
      */
     private emitWorkerExit;
+    /**
+     * Hermes Phase 3: wire in-process notification sinks against the
+     * orchestrator's event bus (`this`). A misconfigured sink (unknown kind,
+     * missing env var) logs + skips rather than breaking startup — the
+     * hardened doctor (`harness doctor`) surfaces the gap. Sinks subscribe
+     * to the same topics as `wireWebhookFanout`; a slow Slack call cannot
+     * block webhook delivery because the two paths fan out independently.
+     */
+    private setupNotifications;
     /**
      * Stops execution for a specific issue.
      *
@@ -1594,6 +1701,147 @@ interface SyncMainOptions {
  */
 declare function syncMain(repoRoot: string, opts?: SyncMainOptions): Promise<SyncMainResult>;
 
+/**
+ * All 21 built-in maintenance task definitions with default schedules.
+ *
+ * Tasks are grouped by type:
+ * - mechanical-ai (7): Run check first, dispatch AI only if fixable issues found
+ * - pure-ai (4): Always dispatch AI agent on schedule
+ * - report-only (7): Run command, record metrics, no PR
+ * - housekeeping (3): Mechanical command, no AI, no PR
+ */
+declare const BUILT_IN_TASKS: readonly TaskDefinition[];
+
+/**
+ * Unified logger interface for all maintenance classes.
+ * Matches StructuredLogger's shape.
+ */
+interface MaintenanceLogger {
+    info(message: string, context?: Record<string, unknown>): void;
+    warn(message: string, context?: Record<string, unknown>): void;
+    error(message: string, context?: Record<string, unknown>): void;
+    debug?(message: string, context?: Record<string, unknown>): void;
+}
+
+/**
+ * Hermes Phase 2 — A single persisted run entry.
+ *
+ * Mirrors `RunResult` plus the captured stdout/stderr, the parsed structured
+ * status envelope (if any), the resolved upstream context that was injected
+ * into the prompt (if any), and the trigger origin.
+ */
+interface PersistedOutputEntry {
+    taskId: string;
+    startedAt: string;
+    completedAt: string;
+    status: RunResult['status'];
+    findings: number;
+    fixed: number;
+    prUrl: string | null;
+    prUpdated: boolean;
+    error?: string;
+    costUsd?: number;
+    origin?: RunOrigin;
+    /** Raw captured stdout from the check step (or housekeeping command). */
+    stdout?: string;
+    /** Raw captured stderr from the check step. */
+    stderr?: string;
+    /** Structured envelope when a JSON status line was parsed; null otherwise. */
+    structured?: Record<string, unknown> | null;
+    /** Resolved upstream-context block, if any. */
+    context?: string;
+}
+interface TaskOutputStoreOptions {
+    /** Root directory under which `<taskId>/outputs/` lives. Default: `.harness/maintenance`. */
+    rootDir: string;
+    /** Default retention bounds applied when a task doesn't specify its own. */
+    retentionDefaults?: Required<OutputRetentionConfig>;
+    logger?: MaintenanceLogger;
+}
+/**
+ * Persists per-task run outputs to disk and applies retention. The store is
+ * intentionally simple: one file per run keyed by completion timestamp, JSON
+ * payload, no SQLite. The chain-context read path (`latest`) and the
+ * dashboard list path (`list`) both consume the same on-disk format.
+ *
+ * Concurrency: `processQueue` already serializes runs of the same task ID,
+ * so the store assumes exclusive write access per task.
+ */
+declare class TaskOutputStore {
+    private rootDir;
+    private retentionDefaults;
+    private logger;
+    constructor(options: TaskOutputStoreOptions);
+    /**
+     * Reject task IDs that don't match the validator's kebab-case pattern —
+     * defends `dirFor()` against caller-supplied path-traversal segments
+     * (`'../foo'`) when the store is invoked from CLI surfaces that don't
+     * round-trip through `validateCustomTasks`.
+     */
+    private ensureSafeTaskId;
+    /**
+     * Persist a single run entry. Retention is applied after the write so
+     * the latest record is durable even if pruning fails.
+     */
+    write(taskId: string, entry: PersistedOutputEntry, retention?: OutputRetentionConfig): Promise<void>;
+    /**
+     * Return the most recent persisted entry for the task, or null if none.
+     */
+    latest(taskId: string): Promise<PersistedOutputEntry | null>;
+    /**
+     * List entries newest-first with offset+limit pagination.
+     */
+    list(taskId: string, limit: number, offset: number): Promise<PersistedOutputEntry[]>;
+    /**
+     * Lookup a specific run by its file name (without the `.json` suffix) or
+     * by its raw completion timestamp.
+     */
+    get(taskId: string, runId: string): Promise<PersistedOutputEntry | null>;
+    /**
+     * The on-disk root for a given task. Exposed for tooling that needs to walk
+     * outputs from outside the store API.
+     */
+    dirFor(taskId: string): string;
+    private readEntry;
+    private applyRetention;
+}
+
+/**
+ * Hermes Phase 2 — Validation errors surfaced by `validateCustomTasks`.
+ *
+ * `path` always begins with `customTasks.<taskId>` so the caller can render
+ * it directly without re-prefixing. Multiple errors may be returned in a
+ * single call; the validator does not short-circuit on the first failure.
+ */
+interface CustomTaskValidationError {
+    path: string;
+    message: string;
+}
+interface CustomTaskValidatorDeps {
+    /** Returns true if a skill with this name exists in the project's registry. */
+    skillExists?: (name: string) => boolean;
+    /** Returns true if the executable referenced by a checkScript.path exists. */
+    scriptExists?: (path: string) => boolean;
+}
+/**
+ * Validates a `MaintenanceConfig.customTasks` map.
+ *
+ * Checks:
+ *  - kebab-case task IDs (matching the BUILT_IN_TASKS convention)
+ *  - no collision with built-in IDs
+ *  - per-type required fields (e.g., mechanical-ai must have `branch` + `fixSkill`)
+ *  - exactly one of `checkCommand` / `checkScript` for types that need a check step
+ *  - `contextFrom` cycle detection across the merged graph (built-ins + customs)
+ *  - `contextFrom` entries reference existing task IDs
+ *  - `inlineSkills` entries exist in the skill registry (when `skillExists` is provided)
+ *  - `checkScript.path` exists on disk (when `scriptExists` is provided)
+ *
+ * Returns `Ok(void)` when all custom tasks pass; otherwise an `Err` carrying
+ * every distinct violation. The validator is pure: no I/O outside the
+ * injected predicates.
+ */
+declare function validateCustomTasks(customTasks: Record<string, CustomTaskDefinition> | undefined, builtIns: readonly TaskDefinition[], deps?: CustomTaskValidatorDeps): Result<void, CustomTaskValidationError[]>;
+
 interface CreateTokenInput {
     name: string;
     scopes: TokenScope[];
@@ -1697,4 +1945,350 @@ declare class WebhookQueue {
     close(): void;
 }
 
-export { type AgentUpdateEvent, AnalysisArchive, type AnalysisRecord, type ApplyEventResult, type ArtifactPresence, type AttemptStats, BackendRouter, type BackendRouterOptions, type BaseRefFallbackEvent, ClaimManager, type ClaimManagerConfig, type CleanWorkspaceEffect, type CreateTokenInput, type CreateTokenResult, type DispatchEffect, type EmitLogEffect, type EscalateEffect, type ExecFileFn$1 as ExecFileFn, type Highlight, type HighlightsInfo, InteractionQueue, type LinearGraphQLExtension, LinearGraphQLStub, type LiveSession, MAX_ATTEMPTS, 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 QueueInsertInput, type QueueRow, type QueueStats, RETRY_DELAYS_MS, 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, TokenStore, type TokenTotals, type TriageConfig, type TriageDecision, type TriageSignals, type TriageSkill, type UpdateTokensEffect, WebhookQueue, 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 };
+interface IndexedDoc {
+    sessionId: string;
+    archived: boolean;
+    fileKind: IndexedFileKind;
+    /** Path relative to project root, posix-style. */
+    path: string;
+    mtimeMs: number;
+    body: string;
+}
+interface SearchOptions {
+    limit?: number;
+    archivedOnly?: boolean;
+    fileKinds?: IndexedFileKind[];
+    /** Maximum bytes to retain per doc body (defaults 256 KiB; longer bodies are truncated with a marker). */
+    maxBytesPerBody?: number;
+}
+/**
+ * Convert a user-typed query string into a safe FTS5 expression.
+ *
+ * If the caller's query already contains explicit FTS5 syntax markers (double
+ * quotes, parens, asterisk, caret, plus, the literal words AND/OR/NOT or a
+ * `column:` selector) it is passed through unchanged so power users keep the
+ * full FTS5 grammar.
+ *
+ * Otherwise each whitespace-separated token is wrapped as an FTS5 phrase so
+ * characters like `-`, `:` and `*` inside the token are treated as content
+ * (not operators), and the tokens are implicitly AND-joined by FTS5.
+ *
+ * Without this, `idx.search('token-aleph')` is parsed by FTS5 as
+ * `token NOT aleph` and fails with `no such column: aleph`.
+ */
+declare function normalizeFts5Query(query: string): string;
+/**
+ * Filesystem path of the search-index sqlite file for a given project root.
+ * Stable so consumers (cleanup tools, doctor, gitignore guards) can locate it.
+ */
+declare function searchIndexPath(projectPath: string): string;
+declare class SqliteSearchIndex {
+    private readonly db;
+    private readonly upsertStmt;
+    private readonly removeSessionStmt;
+    private readonly totalStmt;
+    constructor(dbPath: string);
+    upsertSessionDoc(doc: IndexedDoc): void;
+    removeSession(sessionId: string): number;
+    /**
+     * Drop all `archived=1` rows. Used by `reindexFromArchive` before a full
+     * re-walk. Live (archived=0) rows are preserved.
+     */
+    resetArchived(): void;
+    /** Total rows currently indexed (across both live and archived). */
+    totalIndexed(): number;
+    /**
+     * Ranked FTS5 query. Returns BM25-sorted matches. The `query` is passed to
+     * FTS5 as-is; FTS5 syntax (phrases with quotes, AND/OR/NOT, `column:term`)
+     * is therefore the user-facing language. Errors from malformed queries
+     * surface as thrown `SqliteError` so the CLI can catch + render them.
+     */
+    search(query: string, opts?: SearchOptions): SessionSearchResult;
+    close(): void;
+}
+/** Open (or create) the project's search index. Idempotent. */
+declare function openSearchIndex(projectPath: string): SqliteSearchIndex;
+/**
+ * Walk a session/archive directory and upsert one row per existing file_kind.
+ * Used by both the archive hook (`indexArchivedSession`) and `reindexFromArchive`.
+ *
+ * Bodies larger than `maxBytesPerBody` are truncated with a marker so the index
+ * does not bloat on pathological session files.
+ */
+declare function indexSessionDirectory(idx: SqliteSearchIndex, args: {
+    sessionId: string;
+    sessionDir: string;
+    archived: boolean;
+    projectPath: string;
+    /** Subset of file_kinds to consider (defaults to all). */
+    fileKinds?: IndexedFileKind[];
+    maxBytesPerBody?: number;
+}): {
+    docsWritten: number;
+};
+/**
+ * Drop and rebuild the `archived=1` portion of the index from
+ * `.harness/archive/sessions/<slug-date>/`. Idempotent.
+ *
+ * Each subdirectory is treated as one session whose id is the basename.
+ */
+declare function reindexFromArchive(projectPath: string, opts?: {
+    fileKinds?: IndexedFileKind[];
+    maxBytesPerBody?: number;
+}): ReindexStats;
+
+interface SummarizeContext {
+    /** Path to the archived session directory, e.g. .harness/archive/sessions/foo-2026-05-16. */
+    archiveDir: string;
+    /** Resolved AnalysisProvider — caller skips this step when no provider is available. */
+    provider: AnalysisProvider;
+    /** Optional session summary config, defaults applied when fields are missing. */
+    config?: SessionSummarizationConfig | undefined;
+    /** Optional logger; falls back to console.warn for diagnostics. */
+    logger?: {
+        warn?: (msg: string, meta?: Record<string, unknown>) => void;
+    };
+    /** When true, on provider error a stub `llm-summary.md` is still written. Default true. */
+    writeStubOnError?: boolean;
+}
+interface SummarizeResult {
+    summary: SessionSummary;
+    meta: SessionSummaryMeta;
+    filePath: string;
+}
+/** Approximate token cap via char count; conservative because tokens average ~4 chars. */
+declare function truncateForBudget(text: string, inputBudgetTokens: number): string;
+/** Render the structured summary as the `llm-summary.md` markdown payload. */
+declare function renderLlmSummaryMarkdown(summary: SessionSummary, meta: SessionSummaryMeta): string;
+/**
+ * Summarise a single archived session via the provided AnalysisProvider.
+ *
+ * On success: writes `llm-summary.md` into the archive directory and returns
+ * the structured summary + metadata.
+ *
+ * On provider error: optionally writes a stub `llm-summary.md` so callers can
+ * still detect that summarization was attempted, then returns `Err`.
+ *
+ * Empty / missing input corpus is returned as `Err` and never produces a file.
+ */
+declare function summarizeArchivedSession(ctx: SummarizeContext): Promise<Result<SummarizeResult, Error>>;
+/** Resolve whether summarization should run for the given config. */
+declare function isSummaryEnabled(config?: SessionSummarizationConfig): boolean;
+
+/**
+ * Session archive hook bundle.
+ *
+ * `buildArchiveHooks()` returns an `ArchiveHooks` implementation that wires
+ * `summarizeArchivedSession()` + `indexSessionDirectory()` together so the
+ * core `archiveSession()` lifecycle invokes both after a successful move.
+ *
+ * Both steps are individually wrapped in try/catch — failure of either does
+ * not propagate up the call stack. Spec: §"Risks" treats summary + index
+ * failure as non-fatal.
+ */
+
+interface BuildArchiveHooksOptions {
+    /** Absolute path to the project root (contains `.harness/`). */
+    projectPath: string;
+    /** Optional AnalysisProvider — summarization is skipped when omitted. */
+    provider?: AnalysisProvider | undefined;
+    /** Optional sessions config slice. */
+    config?: SessionsConfig | undefined;
+    /** Optional logger; falls back to console.warn. */
+    logger?: HookLogger | undefined;
+}
+interface HookLogger {
+    warn?: (msg: string, meta?: Record<string, unknown>) => void;
+}
+/**
+ * Construct the `ArchiveHooks` impl. Always returns a working hook bundle —
+ * missing provider or disabled config simply skips that step.
+ */
+declare function buildArchiveHooks(opts: BuildArchiveHooksOptions): ArchiveHooks;
+
+/**
+ * Wrap a `GatewayEvent` into a platform-agnostic `NotificationEnvelope`.
+ * Used when a sink has `wrap_response: true` in its config. Unknown event
+ * types fall back to a generic title/summary so newly-emitted events do
+ * not require a code change to be deliverable.
+ */
+declare function wrapAsEnvelope(event: GatewayEvent): NotificationEnvelope;
+
+/**
+ * Payload passed to `NotificationSink.deliver`. `wrapped` discriminates
+ * which member of the union `payload` is. Sinks branch on `wrapped`
+ * rather than runtime-detecting the shape.
+ */
+interface NotificationSinkDeliverInput {
+    payload: GatewayEvent | NotificationEnvelope;
+    wrapped: boolean;
+}
+/**
+ * Hermes Phase 3 sink contract.
+ *
+ * Sinks subscribe to the orchestrator event bus via `wireNotificationSinks`
+ * and deliver each filtered event to a destination (chat channel, webhook
+ * URL, etc.). Delivery is best-effort: no retry, no persistence.
+ *
+ * Sinks MUST be idempotent w.r.t. their own delivery semantics — the bus
+ * may emit the same logical state transition more than once during testing
+ * or recovery. Sinks should not assume one-shot semantics.
+ */
+interface NotificationSink {
+    /** Stable id used in config + CLI; lowercase, kebab-case. */
+    readonly id: string;
+    /** Sink kind literal (matches `NotificationSinkKind`). */
+    readonly kind: string;
+    /** One-shot delivery. Returns Ok on 2xx, Err on any other outcome. */
+    deliver(input: NotificationSinkDeliverInput): Promise<NotificationDeliveryResult>;
+    /** Optional teardown hook called on orchestrator stop. */
+    dispose?(): Promise<void>;
+}
+
+interface SlackSinkOptions {
+    id: string;
+    webhookUrl: string;
+    fetchImpl?: typeof fetch;
+    timeoutMs?: number;
+}
+/**
+ * Slack sink shipped with Hermes Phase 3. Uses incoming-webhook URLs only;
+ * OAuth + bot tokens are intentionally out of scope (spec D3). Sends one
+ * HTTP POST per delivery and never retries — retries are the operator's
+ * call via the Phase 0 webhook fanout if they need durable delivery.
+ */
+declare class SlackSink implements NotificationSink {
+    readonly kind = "slack";
+    readonly id: string;
+    private readonly webhookUrl;
+    private readonly fetchImpl;
+    private readonly timeoutMs;
+    constructor(opts: SlackSinkOptions);
+    deliver(input: NotificationSinkDeliverInput): Promise<NotificationDeliveryResult>;
+    private renderEnvelope;
+    private renderRawEvent;
+}
+
+interface RegistryEntry {
+    config: NotificationSinkConfig;
+    adapter: NotificationSink;
+}
+interface FromConfigOptions {
+    env: NodeJS.ProcessEnv;
+    /** Optional per-sink fetch override (testing). */
+    fetchImpl?: typeof fetch;
+}
+/**
+ * Surfaced when a sink config refers to an unknown kind, or its env-var
+ * secret cannot be resolved. Carrying the sinkId helps the doctor + CLI
+ * print operator-actionable messages.
+ */
+declare class SinkConfigError extends Error {
+    readonly sinkId: string;
+    constructor(sinkId: string, message: string);
+}
+/**
+ * In-memory registry of configured notification sinks. Built once at
+ * orchestrator startup from `harness.config.json` `notifications.sinks[]`.
+ * Disposed on orchestrator stop.
+ */
+declare class SinkRegistry {
+    private readonly entries;
+    private constructor();
+    static fromConfig(config: NotificationsConfig, options: FromConfigOptions): SinkRegistry;
+    list(): readonly RegistryEntry[];
+    get(id: string): RegistryEntry | null;
+    ids(): string[];
+    dispose(): Promise<void>;
+}
+
+interface WireParams {
+    bus: EventEmitter;
+    registry: SinkRegistry;
+}
+declare function wireNotificationSinks({ bus, registry }: WireParams): () => void;
+
+/**
+ * Phase 4 gate (degraded mode, see spec D5).
+ *
+ * The full design calls for `harness skill run harness-soundness-review
+ * --mode skill` against materialized proposal content. The skill-mode check
+ * vocabulary is not yet designed; its design is the explicit follow-up spec
+ * referenced in Phase 4's Non-goals.
+ *
+ * In v1 we run a small set of mechanical checks inline against the proposal
+ * payload. They cover the obvious structural failures (unparseable YAML,
+ * empty markdown, name/regex drift) without needing an LLM. The result
+ * shape mirrors the eventual soundness-review output so the downstream
+ * promote step (and dashboard panel) does not need to change when
+ * skill-mode lands.
+ */
+declare class GateRunError extends Error {
+    constructor(message: string);
+}
+interface GateResult {
+    proposalId: string;
+    status: SkillProposal['status'];
+    findings: ProposalGateFinding[];
+    runAt: string;
+}
+/**
+ * Synchronously run the gate against the given proposal. The proposal is
+ * read from disk, checks are computed, and the proposal JSON is patched
+ * with the gate result. Returns the post-update gate snapshot for the
+ * caller to render.
+ */
+declare function runGate(projectPath: string, proposalId: string): Promise<GateResult>;
+
+declare class GateNotReadyError extends Error {
+    constructor(message: string);
+}
+declare class PromotionError extends Error {
+    constructor(message: string);
+}
+interface PromotionResult {
+    proposalId: string;
+    skillPath: string;
+    /** Provenance field stamped onto the promoted skill. */
+    provenance: 'agent-proposed';
+}
+/**
+ * Promote a proposal to the skill catalog. Caller is responsible for
+ * emitting `proposal.approved` after a successful return.
+ */
+declare function promote(projectPath: string, proposalId: string, decidedBy: string): Promise<PromotionResult>;
+
+/**
+ * Phase 4 — thin wrappers around the orchestrator event bus that emit the
+ * three `proposal.*` lifecycle events with a stable, validated payload
+ * shape. Both the webhook fan-out (gateway/webhooks/events.ts) and the
+ * in-process notification dispatcher (notifications/events.ts) subscribe
+ * to these topics; their envelope derivers know the field names below.
+ */
+interface ProposalCreatedData {
+    id: string;
+    kind: SkillProposal['kind'];
+    name: string;
+    targetSkill?: string;
+    proposedBy: string;
+    justification: string;
+}
+interface ProposalApprovedData {
+    id: string;
+    kind: SkillProposal['kind'];
+    name: string;
+    targetSkill?: string;
+    decidedBy: string;
+}
+interface ProposalRejectedData {
+    id: string;
+    kind: SkillProposal['kind'];
+    name: string;
+    decidedBy: string;
+    reason: string;
+}
+declare function emitProposalCreated(bus: EventEmitter, proposal: SkillProposal): void;
+declare function emitProposalApproved(bus: EventEmitter, proposal: SkillProposal): void;
+declare function emitProposalRejected(bus: EventEmitter, proposal: SkillProposal): void;
+
+export { type AgentUpdateEvent, AnalysisArchive, type AnalysisRecord, type ApplyEventResult, type ArtifactPresence, type AttemptStats, BUILT_IN_TASKS, BackendRouter, type BackendRouterOptions, type BaseRefFallbackEvent, type BuildArchiveHooksOptions, ClaimManager, type ClaimManagerConfig, type CleanWorkspaceEffect, type CreateTokenInput, type CreateTokenResult, type CustomTaskValidationError, type DispatchEffect, type EmitLogEffect, type EscalateEffect, type ExecFileFn$1 as ExecFileFn, type FromConfigOptions, GateNotReadyError, type GateResult, GateRunError, type Highlight, type HighlightsInfo, type IndexedDoc, InteractionQueue, type LinearGraphQLExtension, LinearGraphQLStub, type LiveSession, MAX_ATTEMPTS, type MigrationResult, MockBackend, type NotificationSink, type NotificationSinkDeliverInput, ORCHESTRATOR_IDENTITY_FILE, Orchestrator, OrchestratorBackendFactory, type OrchestratorBackendFactoryOptions, type OrchestratorContext, type OrchestratorEvent, type OrchestratorState, PRDetector, type PRDetectorLogger, type PendingInteraction, type PersistedOutputEntry, PromotionError, type PromotionResult, PromptRenderer, type ProposalApprovedData, type ProposalCreatedData, type ProposalRejectedData, type PublishedIndex, type QueueInsertInput, type QueueRow, type QueueStats, RETRY_DELAYS_MS, type RateLimitSnapshot as RateLimitComputeSnapshot, type RateLimitConfig, type RateLimitSnapshot$1 as RateLimitSnapshot, type RegistryEntry, type ReleaseClaimEffect, type RetryEntry, type RetryFiredEvent, RoadmapTrackerAdapter, type RunAttemptPhase, type RunOrigin, type RunningEntry, type ScheduleRetryEffect, type SearchOptions, type SideEffect, SinkConfigError, SinkRegistry, 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, WebhookQueue, type WorkerExitEvent, WorkflowLoader, WorkspaceHooks, WorkspaceManager, type WorkspaceManagerOptions, applyEvent, artifactPresenceFromIssue, buildArchiveHooks, calculateRetryDelay, canDispatch, computeRateLimitDelay, createBackend, createEmptyState, detectScopeTier, emitProposalApproved, emitProposalCreated, emitProposalRejected, extractHighlights, extractTitlePrefix, getAvailableSlots, getDefaultConfig, getPerStateCount, indexSessionDirectory, isEligible, isSummaryEnabled, launchTUI, loadPublishedIndex, migrateAgentConfig, normalizeFts5Query, openSearchIndex, promote, reconcile, reindexFromArchive, renderAnalysisComment, renderLlmSummaryMarkdown, renderPRComment, resolveEscalationConfig, resolveOrchestratorId, routeIssue, runGate, savePublishedIndex, searchIndexPath, selectCandidates, sortCandidates, summarizeArchivedSession, syncMain, triageIssue, truncateForBudget, validateCustomTasks, validateWorkflowConfig, wireNotificationSinks, wrapAsEnvelope };