@farmslot/protocol 0.5.0

package/dist/types/runs.d.ts

@@ -0,0 +1,1105 @@
+import type { ArtifactRef, SelfReviewIssue } from '../step-io.js';
+import type { AgentContext, SafetyTier } from './agents.js';
+import type { FailureCategory, RunRecoveryProposalConfidence } from './chat.js';
+import type { TaskTemplateSelection, TemplateProvenance } from './evals.js';
+import type { EvidenceQualityReport, RecipeQualityArtifact } from './recipes.js';
+import type { SlotHealth } from './slots.js';
+export type RunStatus = 'created' | 'grading' | 'writing-task' | 'slot-finding' | 'preparing' | 'dispatching' | 'monitoring' | 'self-reviewing' | 'completing' | 'human-gating' | 'ci-watching' | 'paused' | 'done' | 'blocked' | 'failed' | 'cancelled';
+export declare const TERMINAL_RUN_STATUSES: readonly RunStatus[];
+export declare function isTerminalRunStatus(status: RunStatus): boolean;
+export type RunStepStatus = 'pending' | 'running' | 'done' | 'failed' | 'skipped';
+export interface RunStep {
+    name: string;
+    status: RunStepStatus;
+    detail?: string;
+    startedAt?: string;
+    completedAt?: string;
+    durationMs?: number;
+    inputs?: Record<string, unknown>;
+    outputs?: Record<string, unknown>;
+}
+export type LiveRecipeSource = 'decision' | 'recipe-run-live' | 'recipe-run-artifacts' | 'final-artifacts';
+export type LiveRecipeSelectionReason = 'latest-run' | 'user-selected' | 'decision-derived' | 'fallback-none';
+export interface LiveRecipeContext {
+    source: LiveRecipeSource;
+    recipeRunId: string | null;
+    artifactRoot: string | null;
+    artifactManifest: ArtifactRef[] | null;
+    usedTypedArtifactManifest?: boolean;
+    recipeJson: string | null;
+    recipeQualityArtifact: RecipeQualityArtifact | null;
+    qualityReport: EvidenceQualityReport | null;
+    workerLearnings: string | null;
+    isStale: boolean;
+    selectionReason: LiveRecipeSelectionReason;
+}
+export declare const LIVE_RECIPE_EVIDENCE_PURPOSES: Set<string>;
+export declare const LIVE_RECIPE_EVIDENCE_FILES: Set<string>;
+export declare function hasLiveRecipeEvidence(context: Pick<LiveRecipeContext, 'recipeJson' | 'recipeQualityArtifact' | 'qualityReport' | 'workerLearnings' | 'artifactManifest'>): boolean;
+export type RecipeRunArtifactGroupKind = 'current-artifacts' | 'latest-valid' | 'live-run';
+export type RecipeRunArtifactGroupStatus = 'pass' | 'fail' | 'unknown';
+export interface RecipeRunArtifactGroup extends LiveRecipeContext {
+    id: string;
+    label: string;
+    groupKind: RecipeRunArtifactGroupKind;
+    promoted: boolean;
+    status: RecipeRunArtifactGroupStatus;
+}
+export interface ReviewLineComment {
+    path: string;
+    line: number;
+    body: string;
+    severity: string;
+}
+export interface EvidenceManifestStandalone {
+    label: string;
+    covers?: string[];
+    file: string;
+    note?: string;
+}
+export interface ReviewGatePayload {
+    kind: 'review';
+    prNumber: number | null;
+    repo: string | null;
+    recommendation: string;
+    reviewMd: string;
+    lineComments: ReviewLineComment[];
+    artifactManifest?: EvidenceManifestEntry[];
+    artifactUrls?: Record<string, string>;
+    reviewSnapshot?: ReviewDiffSnapshot;
+    reviewInputArtifactPaths?: string[];
+    stale?: boolean;
+    evidenceMarkdown?: string;
+    recipeJson?: string;
+    recipeQualityArtifact?: RecipeQualityArtifact | null;
+    qualityReport?: EvidenceQualityReport | null;
+    workerLearnings?: string;
+}
+export type PublicationTarget = 'draft' | 'ready';
+export type PublicationStatus = 'not_published' | 'pending_publish' | 'published_draft' | 'published_ready' | 'publish_failed';
+export interface ReviewDepthPolicy {
+    minimumIndependentReviews: number;
+    requireCrossRunner: boolean;
+    extraLoopsRequested: number;
+    requestedBy: 'dispatch' | 'human-gate' | 'agent-gate';
+}
+export type ReviewValidationDepth = 'static-code' | 'full-live';
+export declare const REVIEW_VALIDATION_DEPTHS: readonly ReviewValidationDepth[];
+export declare function isReviewValidationDepth(value: unknown): value is ReviewValidationDepth;
+export declare function reviewValidationDepthForLoop(index: number, total: number): ReviewValidationDepth;
+export interface ReviewLoopRequest {
+    order: number;
+    runner: 'same' | ReviewRunnerId;
+    model?: string | null;
+    validationDepth?: ReviewValidationDepth;
+}
+export type ReviewRunnerId = 'claude' | 'codex' | 'cursor' | 'opencode';
+export interface DiffStat {
+    files: number;
+    additions: number;
+    deletions: number;
+}
+export interface EvidenceManifestEntry {
+    path: string;
+    purpose: string;
+    sizeBytes?: number;
+    sha256?: string;
+}
+export interface ReviewDiffSnapshot {
+    baseRef?: string | null;
+    baseSha?: string | null;
+    headRef?: string | null;
+    headSha?: string | null;
+    diffPath?: string | null;
+    diffHash?: string | null;
+    diffStat?: DiffStat;
+    capturedAt: string;
+    source: 'local-git' | 'github-pr' | 'unavailable';
+    missingReason?: string;
+    error?: string;
+}
+export interface ReviewFixDeltaSnapshot extends ReviewDiffSnapshot {
+    fixBaseSha?: string | null;
+    fixHeadSha?: string | null;
+}
+export interface RunnerSessionUsage {
+    runnerSessionId?: string | null;
+    runnerSessionPath?: string | null;
+    runner?: string | null;
+    actualModel?: string | null;
+    turns?: number | null;
+    inputTokens?: number | null;
+    outputTokens?: number | null;
+    cacheCreation?: number | null;
+    cacheRead?: number | null;
+    reasoningOutputTokens?: number | null;
+    totalTokens?: number | null;
+    costUsd?: number | null;
+    measuredAt: string;
+    source: 'runner-transcript' | 'unavailable';
+    /** What this measurement covers. `session-total` is the runner transcript total at measurement time. */
+    scope?: 'session-total';
+    error?: string;
+}
+export type ReviewLoopTimelineSegmentKind = 'review' | 'worker-fix' | 're-review';
+export interface ReviewLoopTimelineSegment {
+    kind: ReviewLoopTimelineSegmentKind;
+    loopNumber: number;
+    runner?: string | null;
+    model?: string | null;
+    startedAt: string;
+    completedAt?: string;
+    durationMs?: number;
+    verdict?: IndependentReviewAttempt['verdict'];
+    unresolvedCount?: number;
+    artifactPaths?: string[];
+}
+export interface IndependentReviewAttempt {
+    loopNumber: number;
+    verdict: 'pending' | 'pass' | 'issues' | 'failed' | 'cancelled' | 'skipped';
+    unresolvedCount: number;
+    issues?: SelfReviewIssue[];
+    validationDepth?: ReviewValidationDepth;
+    usage?: RunnerSessionUsage;
+    reviewSnapshot?: ReviewDiffSnapshot;
+    fixDelta?: ReviewFixDeltaSnapshot;
+    artifactPaths?: string[];
+    taskProgressArtifactPath?: string;
+    timeline?: ReviewLoopTimelineSegment[];
+    startedAt?: string;
+    completedAt?: string;
+}
+export interface IndependentReviewStatus {
+    id: string;
+    source?: 'dispatch' | 'human-gate' | 'self-review';
+    runner?: string | null;
+    model?: string | null;
+    reviewerSessionId?: string | null;
+    crossRunner: boolean;
+    loopNumber: number;
+    verdict: 'pending' | 'pass' | 'issues' | 'failed' | 'cancelled' | 'skipped';
+    unresolvedCount: number;
+    issues?: SelfReviewIssue[];
+    validationDepth?: ReviewValidationDepth;
+    usage?: RunnerSessionUsage;
+    feedbackSent?: boolean;
+    attempts?: IndependentReviewAttempt[];
+    artifactPaths?: string[];
+    taskProgressArtifactPath?: string;
+    timeline?: ReviewLoopTimelineSegment[];
+    reviewSnapshot?: ReviewDiffSnapshot;
+    reviewedHeadSha?: string | null;
+    reviewedPackageInputHash?: string | null;
+    reviewedReviewSubjectHash?: string | null;
+    fixDelta?: ReviewFixDeltaSnapshot;
+    stale?: boolean;
+    startedAt?: string;
+    completedAt?: string;
+}
+export interface GatePolicy {
+    owner: 'human' | 'agent';
+    dispatchMode?: 'interactive' | 'autonomous' | 'validation';
+    publishAuthority: 'human' | 'agent';
+    reason: string;
+}
+export interface ReadyGatePrPackage {
+    id: string;
+    packageHash: string;
+    packageInputHash?: string;
+    reviewSubjectHash?: string;
+    artifactPath: string;
+    branch: string;
+    remoteBranchRef?: string | null;
+    headSha?: string;
+    diffStat: DiffStat;
+    draftTitle: string;
+    draftBody: string;
+    evidenceManifest?: EvidenceManifestEntry[];
+    selectedEvidenceKeys?: string[];
+    validationSummaryPath?: string | null;
+    validationSummaryHash?: string | null;
+    reviewArtifactIds: string[];
+    dispatchMode?: 'interactive' | 'autonomous' | 'validation';
+    gatePolicy: GatePolicy;
+    /** Frozen at package preparation time so approval/review policy cannot drift with config edits. */
+    reviewDepth?: ReviewDepthPolicy;
+    publicationTarget: PublicationTarget;
+    publicationStatus: PublicationStatus;
+    supersededByPackageId?: string | null;
+    createdAt: string;
+    approvedAt?: string;
+}
+export interface ReadyGateInputSnapshot {
+    ticketData?: RunTicketData;
+    taskFile?: string | null;
+    taskPrompt?: string;
+    initialContext?: string;
+    checklist?: string[];
+    templateProvenance?: TemplateProvenance | null;
+}
+export interface ReadyGatePayload {
+    kind: 'ready';
+    prNumber: number | null;
+    repo: string | null;
+    diffStat: DiffStat;
+    workerReport: string;
+    branch: string;
+    slotId?: string;
+    /**
+     * Commit SHA the slot's branch pointed at when this gate was created.
+     * Persisted so post-hoc viewers of a resolved gate know whether the
+     * slot has moved on — the live diff in `ready-workspace` is against the
+     * current HEAD, which may differ from what was reviewed. Undefined on
+     * gates created before this field was introduced.
+     */
+    headSha?: string;
+    recipeJson?: string;
+    recipeQualityArtifact?: RecipeQualityArtifact | null;
+    qualityReport?: EvidenceQualityReport | null;
+    artifactManifest?: EvidenceManifestEntry[];
+    selfReviewVerdict?: string;
+    selfReviewSummary?: string;
+    workerLearnings?: string;
+    ciChecks?: Array<{
+        name: string;
+        status: string;
+        conclusion: string | null;
+    }>;
+    acceptanceCriteria?: string[];
+    inputSnapshot?: ReadyGateInputSnapshot;
+    prPackage?: ReadyGatePrPackage;
+    reviewDepth?: ReviewDepthPolicy;
+    independentReviews?: IndependentReviewStatus[];
+    gatePolicy?: GatePolicy;
+    validationSummary?: string;
+    publicationTarget?: PublicationTarget;
+    publicationStatus?: PublicationStatus;
+    stale?: boolean;
+    draftEdits?: {
+        title?: string;
+        body?: string;
+        selectedEvidenceKeys?: string[];
+    };
+}
+export interface NoChangeGatePayload {
+    kind: 'no-change';
+    disposition: WorkerTerminalDisposition;
+    reason?: string;
+    evidence?: WorkerTerminalEvidence;
+    workerReport?: string;
+    artifactManifest?: EvidenceManifestEntry[];
+}
+export interface SlotPickerPayload {
+    kind: 'slot_picker';
+    project: string;
+    candidates: Array<{
+        slotId: string;
+        score: number;
+        branch: string;
+        lifecycle: string;
+        health: SlotHealth;
+        machine: string;
+    }>;
+    reason: 'no_free_slots' | 'all_stale' | 'all_unhealthy';
+}
+/**
+ * Branch-affinity nudge — surfaced when a busy slot is already on the target PR's branch
+ * and the operator can reuse its loaded context instead of dispatching fresh on a stale slot.
+ *
+ * Emitted by FIND_SLOT only for headless entry points (CI-watch chained pr-complete after CI
+ * fail, CLI dispatch, gateway restart recovery). The dispatch wizard surfaces the same data
+ * inline via DispatchCandidatesResult.nudgeMeta and bypasses this card entirely.
+ */
+export interface BranchAffinityNudgePayload {
+    kind: 'branch_affinity_nudge';
+    project: string;
+    ticketOrPr: string;
+    prNumber?: number | null;
+    candidate: {
+        slotId: string;
+        machine: string;
+        branch: string;
+        /** Runner currently active in the slot. Should always be populated when the candidate is
+         * surfaced (the eligibility gate requires a runner with `supportsTmuxNudges`), but typed
+         * as nullable to mirror `SlotStatus.runner` and avoid empty-string sentinels. */
+        runner: string | null;
+        /** Model of the prior worker, when known. Often null for legacy slots that never recorded one. */
+        model: string | null;
+        nudgeCount: number;
+        /** Runner context-window usage percentage (0-100). Runner-agnostic; populated by whichever
+         * node-side adapter knows how to read the active runner's status surface. Null when the
+         * runner does not expose a value or the parse failed. */
+        ctxPct: number | null;
+        agentStatus: string;
+        dispatchedAt: string | null;
+        /** Run id currently bound to the slot — i.e., the prior run that nudge would supersede.
+         * Read this as "priorRunId" at decision time; the field is named `currentRunId` to mirror
+         * `SlotStatus.currentRunId` so wire-format consumers don't have to think about renames. */
+        currentRunId: string | null;
+        currentFlowType: string | null;
+        uncommittedCount: number;
+        /** First 10 paths from `git status --porcelain`. */
+        uncommittedFiles: string[];
+        /** Whether the match is an authoritative `prHealth.pr === prNumber` hit or a softer branch-slug-only match. */
+        prMatchKind: 'pr-number' | 'branch-slug';
+        /** True when the slot's runner supports tmux send-keys nudges. UI uses this to disable the
+         * Nudge action button when false — only Fresh dispatch is offered for codex / opencode. */
+        canNudge: boolean;
+    };
+    /** Free-slot fallback list. Reused from {@link SlotPickerPayload.candidates} so the 'pick'
+     * action renders through the existing slot-picker UI without a second payload type. The
+     * type alias is intentional: if SlotPicker's row shape evolves the nudge card inherits the
+     * change. If they need to diverge, peel the alias and add explicit fields here. */
+    freeSlotCandidates: SlotPickerPayload['candidates'];
+    /** Soft warnings (e.g. 'family-mismatch', 'high-nudge-count', 'high-ctx-pct'). */
+    riskFlags: string[];
+}
+export interface ImprovementFileChange {
+    filePath: string;
+    before: string;
+    after: string;
+}
+export interface ImprovementDiffPayload {
+    kind: 'improvement';
+    learningContent: string;
+    proposedChanges: ImprovementFileChange[];
+    rationale: string;
+    sourceRunId: string;
+    project: string;
+    analysisStatus?: 'analyzing' | 'completed' | 'no-content' | 'no-changes' | 'error';
+    analysisStartedAt?: string;
+    analysisError?: string;
+}
+export interface CommentsTriageSummary {
+    total: number;
+    real: number;
+    falsePositive: number;
+    outOfScope: number;
+    fixed: number;
+    botAddressed?: number;
+    humanReviewersRequestingChanges?: number;
+    humanCommentsAddressed?: number;
+    unknownSource?: number;
+    actionablePaths?: string[];
+}
+export interface RetrospectivePayload {
+    kind: 'retrospective';
+    outcome: 'success' | 'failure' | 'partial' | 'cancelled' | 'unknown';
+    whatThisIs: string;
+    selfReviewVerdict?: string;
+    selfReviewSummary?: string;
+    workerLearnings?: string;
+    reportExcerpt?: string;
+    ciWatch?: {
+        result?: string;
+        passed?: number;
+        failed?: number;
+        pending?: number;
+        total?: number;
+    };
+    actionEffects: Array<{
+        actionId: string;
+        summary: string;
+    }>;
+    rootRunId?: string;
+    rootLearnings?: string;
+    deltaLearnings?: string;
+    commentsTriageSummary?: CommentsTriageSummary;
+}
+/** Engine-collision decision payload — surfaces the prior runs that own the colliding
+ *  task dirs so UI can deep-link to them (and let the operator retry from there)
+ *  instead of forking a new family via `create-new`. priorRunIds is ordered newest-first.
+ *  dirOwners maps each colliding dir to the owning run id (when resolved at decision
+ *  creation); UI uses it to render per-dir chip links without re-scanning state and
+ *  without risking cross-project taskFile substring collisions. */
+export interface CollisionPayload {
+    kind: 'collision';
+    ticketSlug: string;
+    existingDirs: string[];
+    priorRunIds: string[];
+    /** Pre-resolved owner run id per colliding dir. Absent on legacy decisions —
+     *  UI should fall back to its own state scan when this field is missing. */
+    dirOwners?: Record<string, string>;
+}
+export type RunDecisionPayload = ReviewGatePayload | ReadyGatePayload | NoChangeGatePayload | SlotPickerPayload | BranchAffinityNudgePayload | ImprovementDiffPayload | RetrospectivePayload | CollisionPayload;
+export interface RunDecision {
+    id: string;
+    type: DecisionType;
+    title: string;
+    description: string;
+    actions: DecisionAction[];
+    createdAt: string;
+    resolvedAt?: string;
+    resolvedAction?: string;
+    payload?: RunDecisionPayload;
+    selectionData?: Record<string, unknown>;
+    context?: Record<string, unknown>;
+}
+/** A single ticket referenced by a PR (linked from PR body, commit trailers, etc.) */
+export interface LinkedTicket {
+    ref: string;
+    url: string;
+    title: string;
+    description: string;
+    source: 'jira' | 'github';
+}
+export interface RunTicketData {
+    source: 'jira' | 'github' | 'both' | 'manual';
+    issueType?: string;
+    title: string;
+    description: string;
+    acceptanceCriteria: string[];
+    affectedArea: string;
+    stepsToReproduce: string[];
+    screenshots: string[];
+    labels: string[];
+    jiraKey?: string;
+    githubIssue?: string;
+    comments?: string[];
+    /**
+     * Tickets referenced by a PR (review-pr flow only).
+     * Multiple keys are supported — PRs often fix several tickets at once.
+     * Each entry is pre-fetched from its source so templates can render without
+     * extra round-trips.
+     */
+    linkedTickets?: LinkedTicket[];
+}
+export interface RunGrade {
+    difficulty: 'low' | 'medium' | 'high' | 'extreme';
+    rationale: string;
+    modelRecommendation: string;
+    score?: number;
+}
+export interface ProofTargetVerdict {
+    id: string;
+    target: string;
+    verdict: 'pass' | 'fail' | 'not-applicable';
+    note?: string;
+}
+export interface HumanGrade {
+    recipe_semantic: 'good' | 'ok' | 'bad';
+    reasoning: string;
+    graded_by: string;
+    graded_at: string;
+    proof_target_verdicts?: ProofTargetVerdict[];
+}
+export declare const DEFAULT_GRADER_ID = "unknown";
+export type RunFamilyCompletionState = 'active' | 'complete' | 'failed' | 'mixed';
+export type RunSelfLearningEligibilityState = 'eligible' | 'blocked' | 'unknown';
+export declare const RUN_SELF_LEARNING_MISSING_SIGNALS: readonly ["missing-evidence-signal", "missing-learnings-signal", "missing-recipe-signal", "missing-diff-signal"];
+export type RunSelfLearningMissingSignal = (typeof RUN_SELF_LEARNING_MISSING_SIGNALS)[number];
+export declare const RUN_SELF_LEARNING_BLOCK_REASONS: readonly ["active-runs", "pending-decisions", "no-successful-run"];
+export type RunSelfLearningBlockReason = (typeof RUN_SELF_LEARNING_BLOCK_REASONS)[number];
+export interface RunSelfLearningEligibility {
+    state: RunSelfLearningEligibilityState;
+    reasons: RunSelfLearningBlockReason[];
+    missingSignals: RunSelfLearningMissingSignal[];
+}
+export interface RunFamilyReadinessSummary {
+    familyId: string;
+    familyRootTicketOrPr: string;
+    project: string;
+    latestRunId: string;
+    latestRunAt: string;
+    runCount: number;
+    terminalRunCount: number;
+    activeRunCount: number;
+    failedRunCount: number;
+    completionPercent: number;
+    completionState: RunFamilyCompletionState;
+    eligibility: RunSelfLearningEligibility;
+}
+export interface RunProjectAnalyticsSummary {
+    project: string;
+    familyCount: number;
+    runCount: number;
+    activeFamilyCount: number;
+    completedFamilyCount: number;
+    eligibleFamilyCount: number;
+    blockedFamilyCount: number;
+    unknownFamilyCount: number;
+    latestRunAt: string;
+}
+export interface RunListSummaryMeta {
+    /** First PR summaries describe only the runs returned in this run.list response after filters, sorting, and limit. */
+    scope: 'returned-runs';
+    /** Number of returned runs used to compute family/project summaries. */
+    summaryRunCount: number;
+    /** Matching run count before run.list limit truncation; mirrors RunListResult.totalCount. */
+    totalCount: number;
+    /** True when the returned-run summary is a partial view of the matching result set. */
+    isTruncated: boolean;
+}
+export interface RunMetrics {
+    durationMs?: number;
+    nudgeCount: number;
+    model: string | null;
+    runner: string | null;
+    runnerSessionId?: string | null;
+    runnerSessionPath?: string | null;
+    outcome?: 'success' | 'failure' | 'partial' | 'cancelled';
+    disposition?: WorkerTerminalDisposition;
+    terminalEvidence?: WorkerTerminalEvidence;
+    costEstimate?: number;
+    sessionTurns?: number;
+    sessionInputTokens?: number;
+    sessionOutputTokens?: number;
+    sessionCacheCreation?: number;
+    sessionCacheRead?: number;
+    sessionTotalTokens?: number;
+    actualModel?: string;
+}
+export type RunCompletionPolicy = 'default' | 'artifact-only';
+export type RunStartRefSource = {
+    kind: 'manual';
+} | {
+    kind: 'package';
+    packagePath: string;
+} | {
+    kind: 'merged-pr';
+    repo?: string;
+    prNumber?: number;
+} | {
+    kind: 'git-ref';
+    repository?: string;
+    ref?: string;
+};
+export interface RunStartRefProvenance {
+    requestedRef: string;
+    resolvedSha?: string;
+    resolvedAt?: string;
+    source?: RunStartRefSource;
+}
+export interface SlotRunHistoryEntry {
+    runId: string;
+    familyId: string;
+    status: RunStatus;
+    flowType: FlowType;
+    ticketOrPr: string;
+    summary?: string;
+    project: string;
+    branch: string | null;
+    createdAt: string;
+    updatedAt: string;
+    completedAt?: string;
+    durationMs?: number;
+    runner: string | null;
+    model: string | null;
+    actualModel?: string;
+    runnerSessionId?: string | null;
+    runnerSessionPath?: string | null;
+    taskFile: string | null;
+    taskDir: string | null;
+    artifactDir: string | null;
+    /** PR opened or reviewed by this run, when known. Slot history uses this to keep historical workspace cards linkable. */
+    prNumber: number | null;
+    /** Best-known contribution diff summary from retained run metadata. Used by compact workspace clients without fetching the full run. */
+    diffStat: DiffStat & {
+        available: boolean;
+    };
+    /** Number of retained before/after visual evidence pairs for compact slot-history clients. */
+    visualPairCount: number;
+    links?: RunLink[];
+    runRecordPath: string;
+    currentForSlot: boolean;
+}
+export type WorkerTerminalDisposition = 'fixed' | 'already_fixed' | 'not_reproducible' | 'blocked' | 'failed';
+export interface WorkerTerminalEvidence {
+    reportPath?: string;
+    artifacts?: string[];
+    confidence?: 'low' | 'medium' | 'high';
+    noCodeChange?: boolean;
+    reproductionAttempted?: boolean;
+}
+/**
+ * Compare the dispatched model short-name (e.g. "sonnet") against the actual
+ * model reported by the worker's session transcript (e.g. "claude-sonnet-4-6").
+ * Returns true if they refer to the same family. Used to detect model drift
+ * caused by fast-mode / `/model` sticky config overriding the --model flag.
+ */
+export declare function modelsMatch(dispatched: string | null | undefined, actual: string | null | undefined): boolean;
+/**
+ * Tag a comparison-lane sibling with a `<runner>-<safe(model)>` variant so
+ * the duplicate-run guard (assertDuplicateRunAllowed in run.ts) sees it as
+ * distinct from any existing sibling in the family. The format is shared
+ * between the dispatch wizard's submit handler and run-detail's "Re-run
+ * alongside" href builder — keeping it in protocol prevents the two from
+ * silently drifting apart, which would let the duplicate guard reject runs
+ * that were supposed to be valid forks.
+ *
+ * Returns an empty string when either input is falsy so callers can keep a
+ * fallback to URL-prefilled values without crashing on partial state.
+ */
+export declare function buildComparisonVariant(runner: string | null | undefined, model: string | null | undefined): string;
+/**
+ * Pick the next free comparison-lane variant tag for a (runner, model) pair
+ * within a family. Returns `buildComparisonVariant(runner, model)` when no
+ * sibling already uses that tag; otherwise appends `-v2`, `-v3`, … until a
+ * free slot is found. Used by the dispatch wizard's same-runner+same-model
+ * comparison flow (e.g. operator edited templates and wants to re-run with
+ * the same model) so the duplicate-run guard at run.ts:assertDuplicateRunAllowed
+ * accepts the new sibling.
+ */
+export declare function nextFreeComparisonVariant(familyRuns: ReadonlyArray<{
+    variant?: string | null;
+}>, runner: string | null | undefined, model: string | null | undefined): string;
+export interface RunMonitorState {
+    nudgeCount: number;
+    lastPollAt: string;
+    startedAt: string;
+    lastPaneHash?: string;
+}
+export interface RunLink {
+    label: string;
+    url: string;
+}
+export type RunAutoRecoveryProposalStatus = 'idle' | 'manual-in-progress' | 'auto-in-progress' | 'disabled';
+export interface RunRecoveryRuntimeProposal {
+    status: RunAutoRecoveryProposalStatus;
+    proposalId?: string;
+    generation: number;
+}
+export interface RunReplayStep {
+    id: string;
+    attempt: number;
+    stepName: string;
+    startedAt: string;
+    completedAt?: string;
+    status: 'started' | 'completed' | 'failed' | 'cancelled';
+    triggeredBy: 'auto-recovery' | 'operator';
+    intelligenceActionId?: string;
+}
+export declare const INTELLIGENCE_ACTION_ACTORS: readonly ["auto-recovery", "auto-grade", "auto-nudge"];
+export type IntelligenceActionActor = (typeof INTELLIGENCE_ACTION_ACTORS)[number];
+export declare const INTELLIGENCE_ACTION_TIERS: readonly ["deterministic", "llm-refined", "hybrid"];
+export type IntelligenceActionTier = (typeof INTELLIGENCE_ACTION_TIERS)[number];
+export declare const INTELLIGENCE_ACTION_OUTCOMES: readonly ["applied", "proposed", "skipped", "errored"];
+export type IntelligenceActionOutcome = (typeof INTELLIGENCE_ACTION_OUTCOMES)[number];
+export declare const INTELLIGENCE_ACTION_OUTCOME_REASONS: readonly ["max_attempts_per_step", "family_cap", "cooldown_active", "non_recoverable_category", "low_confidence", "budget_exceeded", "pattern_disabled", "manual_in_progress", "dead_letter"];
+export type IntelligenceActionOutcomeReason = (typeof INTELLIGENCE_ACTION_OUTCOME_REASONS)[number];
+export declare const INTELLIGENCE_ACTION_FOLLOWUPS: readonly ["recovered", "failed-again", "human-overrode", "cancelled"];
+export type IntelligenceActionFollowup = (typeof INTELLIGENCE_ACTION_FOLLOWUPS)[number];
+export declare const INTELLIGENCE_ACTION_PROPOSED_TYPES: readonly ["run.replayStep", "slot.reset", "slot.cleanupProcesses", "slot.fixtureRefresh", "tmux.send"];
+export type IntelligenceActionProposedType = (typeof INTELLIGENCE_ACTION_PROPOSED_TYPES)[number];
+export interface IntelligenceActionGuard {
+    name: string;
+    passed: boolean;
+    reason?: string;
+}
+export interface IntelligenceAction {
+    id: string;
+    timestamp: string;
+    decidedAt: string;
+    runId: string;
+    familyId?: string;
+    project?: string;
+    stepName?: string;
+    actor: IntelligenceActionActor;
+    verdict: {
+        category?: FailureCategory;
+        patternId?: string;
+        confidence: RunRecoveryProposalConfidence;
+        rationale?: string;
+    };
+    guards: IntelligenceActionGuard[];
+    outcome: IntelligenceActionOutcome;
+    outcomeReason?: IntelligenceActionOutcomeReason;
+    latencyMs?: number;
+    appliedAction?: {
+        type: IntelligenceActionProposedType;
+        stepName?: string;
+        replayRunId?: string;
+        tmuxKeys?: string;
+    };
+    followupOutcome?: IntelligenceActionFollowup;
+    tier: IntelligenceActionTier;
+    costUsd: number;
+}
+export interface IntelligenceActionsSummary {
+    /** Count of records after date filtering; independent from the returned page size. */
+    total: number;
+    byActor: Record<string, number>;
+    byOutcome: Record<string, number>;
+    /** Most recent records after date filtering, capped by request limit. */
+    records: IntelligenceAction[];
+    metadata: {
+        parseFailures: number;
+        shapeDriftFailures: number;
+    };
+}
+export interface Run {
+    id: string;
+    familyId: string;
+    parentRunId?: string | null;
+    familyRootTicketOrPr?: string;
+    /** Run policy bucket: production, validation, or comparison. Not a flow type and not an eval identity. */
+    lane: RunLane;
+    /** Required only for comparison-lane sibling attempts; never a mode. */
+    variant?: string | null;
+    /** Selected project-owned worker template version for this run. */
+    taskTemplate?: TaskTemplateSelection;
+    /** Worker pipeline/template carrier. Eval candidates may use dev as a carrier while taskProfile stores rubric semantics. */
+    flowType: FlowType;
+    /** Operator/autonomy behavior preset. mode='validation' implies lane='validation' and is not used for comparison siblings. */
+    mode?: 'interactive' | 'autonomous' | 'validation';
+    /** Dev-only interactive policy. Keeps flowType='dev' while allowing flexible human-steered runs. */
+    devInteractiveProfile?: DevInteractiveProfile;
+    status: RunStatus;
+    project: string;
+    ticketOrPr: string;
+    app?: string;
+    effort?: string;
+    slotId: string | null;
+    branch: string | null;
+    /** Completion side-effect policy; artifact-only suppresses publication/PR mutation paths. */
+    completionPolicy?: RunCompletionPolicy;
+    /** Requested/resolved base ref for artifact-only comparison replay runs. */
+    startRef?: RunStartRefProvenance | null;
+    /** Gateway-captured template provenance for the rendered worker task. */
+    templateProvenance?: TemplateProvenance | null;
+    taskFile: string | null;
+    activeTaskFile?: string;
+    agentContexts?: AgentContext[];
+    prNumber?: number;
+    steps: RunStep[];
+    decisions: RunDecision[];
+    metrics: RunMetrics;
+    createdAt: string;
+    updatedAt: string;
+    ticketData?: RunTicketData;
+    grade?: RunGrade;
+    humanGrade?: HumanGrade;
+    links?: RunLink[];
+    summary?: string;
+    reviewTier?: string;
+    safetyTier?: SafetyTier;
+    /**
+     * Slots the run is allowed to land on, resolved from the UI's global filters
+     * (e.g. machines, future filter dimensions) at dispatch time. `null` = unrestricted.
+     * Honored by FIND_SLOT, affinity reuse, and chained runs. Strictly narrower than
+     * the project-wide pool but wider than `slotId`, which pins a single slot.
+     */
+    allowedSlots?: string[] | null;
+    /** Internal backlog handoff link, persisted so backlog delete/reconcile can find runs. */
+    backlogItemId?: string;
+    completedAt?: string;
+    error?: string;
+    /**
+     * When set, this run was cancelled because the engine forked it into another run
+     * (e.g. the collision → comparison-lane redirect at WRITE_TASK). UI surfaces this as
+     * an info banner with a link to the successor instead of treating the run as a failure.
+     */
+    redirectedToRunId?: string | null;
+    monitorState?: RunMonitorState;
+    /** CI-watch inline-fix dedup + counters. Persisted so the circuit breaker survives gateway restart (ADR-027). */
+    ciWatchState?: RunCiWatchState;
+    /** Run-engine runtime flags + replay generation counter. Persisted so warm-recovery hints
+     * and stale-loop guards survive gateway restart (ADR-027). */
+    engineState?: RunEngineState;
+    /** Provenance-aware live recipe context used by slot-view/dev harness surfaces. */
+    liveRecipeContext?: LiveRecipeContext | null;
+    recoveryAttempts?: RunReplayStep[];
+    recoveryProposal?: RunRecoveryRuntimeProposal;
+    autoRecoveryDisabled?: boolean;
+}
+export declare function isLightweightInteractiveDevRun(run: Pick<Run, 'flowType' | 'mode' | 'devInteractiveProfile'>): boolean;
+export declare function isInteractiveDevRun(run: Pick<Run, 'flowType' | 'mode'>): boolean;
+/** Persisted run-engine state — see ADR-027. */
+export interface RunEngineState {
+    /** Runtime hints set by dispatch UI (e.g. skipPrepare) or engine (warmRecovery on crash resume).
+     * `nudgeReuse` is set when the operator picks "Nudge worker" in the dispatch wizard or the
+     * branch-affinity decision card; FIND_SLOT honors it to bind the busy slot, and DISPATCH
+     * routes through `nudgeDispatch` (skip PREPARE, send-keys to existing tmux session) instead
+     * of `dispatchExecute` (kill + relaunch). `freshReuse` is the "Kill & dispatch fresh"
+     * sibling — FIND_SLOT hard-kills the prior worker BEFORE PREPARE so git reset / checkout /
+     * dependency install don't race a still-writing worker in the same worktree. */
+    flags?: {
+        skipPrepare?: boolean;
+        warmRecovery?: boolean;
+        nudgeReuse?: boolean;
+        freshReuse?: boolean;
+    };
+    /** Monotonic replay generation counter; startRun bails if the run has been superseded. */
+    generation?: number;
+    autoRecoveryDeadLetter?: string;
+    intelligenceAuditDegraded?: boolean;
+    /** Local-first publication gate metadata. Stored on the run JSON snapshot; no DB migration. */
+    publishGate?: {
+        packageId?: string;
+        packageHash?: string;
+        packageInputHash?: string;
+        reviewSubjectHash?: string;
+        packageArtifactPath?: string;
+        approvedPackageHash?: string;
+        approvedAt?: string;
+        publicationTarget?: PublicationTarget;
+        publicationStatus?: PublicationStatus;
+        prNumber?: number | null;
+        reviewDepth?: ReviewDepthPolicy;
+        pendingReviewPlan?: ReviewLoopRequest[];
+        independentReviews?: IndependentReviewStatus[];
+        supersededPackageIds?: string[];
+        feedbackArtifactPath?: string;
+    };
+    /** Artifact-first experiment trial linkage for artifact-only reference/template regression candidates. */
+    evalExperiment?: {
+        /** Matrix/suite-wide cap group for eval queue accounting across per-case experiments. */
+        capGroupId?: string;
+        suiteId?: string;
+        experimentId: string;
+        experimentKey: string;
+        experimentManifestPath: string;
+        packagePath: string;
+        candidateStrategyFingerprint: string;
+        trialId: string;
+    };
+    /** Interactive dev operator workflow metadata and terminal action history. */
+    interactiveDev?: {
+        profile?: DevInteractiveProfile;
+        initialContext?: string;
+        checklist?: string[];
+        terminalActions?: DevInteractiveActionRecord[];
+    };
+}
+/**
+ * Per-run CI-watch inline-fix state — persisted on {@link Run} so dedup signatures
+ * and attempt counters survive gateway restart (ADR-027).
+ */
+export interface RunCiWatchState {
+    /** Last successfully-dispatched fix fingerprint (bot-comment signature + HEAD sha). */
+    dedup?: {
+        signature: string;
+        commitSha: string;
+    };
+    /** When the current no-progress timeout window started. */
+    timeoutWindowStartedAt?: string;
+    /** Last observed progress in watched CI status or PR head. */
+    lastProgressAt?: string;
+    /** Human-readable reason for the last progress reset. */
+    lastProgressReason?: string;
+    /** Last watched-check status fingerprint used to detect progress. */
+    lastCheckFingerprint?: string;
+    /** Last observed local PR head SHA used to detect new commits. */
+    lastHeadSha?: string | null;
+    /** Consecutive-failure counter; resets on success. Gates consecutive fallback (MAX_INLINE_CI_FIX_ATTEMPTS). */
+    consecutiveAttempts: number;
+    /** Lifetime attempt counter; never resets. Gates hard ceiling (MAX_INLINE_CI_FIX_TOTAL). */
+    totalAttempts: number;
+    /** Count of dedup-filtered skips, surfaced in step outputs. */
+    skips: number;
+}
+export type FamilyDiffProvenanceSource = 'artifact' | 'legacy-step-output' | 'unavailable';
+export type FamilyDiffKind = 'contribution' | 'review-input' | 'legacy';
+export interface FamilyDiffProvenance {
+    source: FamilyDiffProvenanceSource;
+    available: boolean;
+    files: number;
+    additions: number;
+    deletions: number;
+    partialStat?: DiffStat;
+    kind: FamilyDiffKind;
+    filter?: 'source-code';
+    artifactPath?: string;
+    baseRef?: string;
+    baseSha?: string;
+    headRef?: string;
+    headSha?: string;
+    capturedAt?: string;
+    configSource?: 'project' | 'gateway-default';
+    configFallbackReason?: string;
+    configFallbackError?: string;
+    missingReason?: string;
+    error?: string;
+    repository?: string;
+    prNumber?: number;
+}
+export declare function isFamilyDiffProvenance(value: unknown): value is FamilyDiffProvenance;
+export interface FamilyInputCommitMetadata {
+    repository?: string;
+    prNumber?: number;
+    baseRef?: string;
+    baseSha?: string;
+    headRef?: string;
+    headSha?: string;
+    capturedAt: string;
+    source: 'github-pr' | 'local-git' | 'unavailable';
+    missingReason?: string;
+    error?: string;
+}
+export interface FamilyReviewSignalSummary {
+    total: number;
+    real: number;
+    fixed: number;
+    botAddressed: number;
+    humanReviewersRequestingChanges: number;
+    humanCommentsAddressed: number;
+    unknownSource: number;
+}
+export interface FamilyArtifactBucketSummary {
+    key: string;
+    count: number;
+    bytes: number;
+}
+export interface FamilyArtifactFootprint {
+    count: number;
+    bytes: number;
+    byPurpose: FamilyArtifactBucketSummary[];
+    bySource: FamilyArtifactBucketSummary[];
+    byExtension: FamilyArtifactBucketSummary[];
+}
+export interface FamilyObservabilityArtifact {
+    runId: string;
+    familyId: string;
+    sourceRunId?: string;
+    sourceFamilyId?: string;
+    stepName?: string | null;
+    path: string;
+    purpose: string;
+    sha256?: string;
+    sizeBytes?: number;
+    source: 'artifact-manifest' | 'step-output' | 'task-artifact' | 'task-input' | 'inherited-context' | 'recovered-provenance';
+}
+export interface FamilyChangeLedgerEntry {
+    runId: string;
+    familyId: string;
+    parentRunId?: string | null;
+    familyRootTicketOrPr: string;
+    lane: RunLane;
+    variant?: string | null;
+    flowType: FlowType;
+    project: string;
+    ticketOrPr: string;
+    branch: string | null;
+    prNumber: number | null;
+    createdAt: string;
+    completedAt?: string;
+    changeKind: 'contribution' | 'review-input' | 'follow-up' | 'legacy' | 'none';
+    contributionDiff: FamilyDiffProvenance;
+    inputDiff?: FamilyDiffProvenance;
+    legacyDiffFallback?: FamilyDiffProvenance;
+    inputCommit?: FamilyInputCommitMetadata;
+    reviewSignals?: FamilyReviewSignalSummary;
+    artifactFootprint: FamilyArtifactFootprint;
+    taskInputArtifacts: FamilyObservabilityArtifact[];
+    missingData: string[];
+}
+export interface FamilyChangeLedgerSummary {
+    /** Runs with any captured contribution or reviewed-input diff. A run counts once even when both kinds are present. */
+    runsWithDiff: number;
+    /** Runs with neither contribution diff nor reviewed-input provenance; explicit empty/unavailable review input is counted in review-input buckets instead. */
+    runsMissingDiff: number;
+    /** Runs with available contribution diff stats, including oversized diffs with partial numstat totals. */
+    runsWithContributionDiff: number;
+    runsWithReviewInputDiff: number;
+    runsWithEmptyReviewInputDiff: number;
+    runsWithUnavailableReviewInputDiff: number;
+    totalContributionFiles: number;
+    totalContributionAdditions: number;
+    totalContributionDeletions: number;
+    reviewRounds: number;
+    bugbotFindingsAddressed: number;
+    humanReviewersRequestingChanges: number;
+    humanCommentsAddressed: number;
+    artifactFootprint: FamilyArtifactFootprint;
+}
+export interface FamilyChangeLedger {
+    summary: FamilyChangeLedgerSummary;
+    entries: FamilyChangeLedgerEntry[];
+}
+export type FlowType = 'fix-bug' | 'review-pr' | 'dev' | 'pr-complete' | 'merge-main';
+export type RunLane = 'production' | 'validation' | 'comparison';
+export type DevInteractiveProfile = 'lightweight' | 'reviewed';
+export declare const DEFAULT_DEV_INTERACTIVE_PROFILE: DevInteractiveProfile;
+export type DevInteractiveCompletionAction = 'done-no-pr' | 'detect-pr-and-ci-watch' | 'link-pr-and-ci-watch' | 'link-pr-and-pr-complete' | 'run-self-review' | 'blocked' | 'failed' | 'abort';
+export interface DevInteractiveActionRecord {
+    action: DevInteractiveCompletionAction;
+    source: 'operator';
+    timestamp: string;
+    reason?: string;
+    prRef?: string;
+}
+/** Pipeline step names — single source of truth. Use these instead of string literals. */
+export declare const PipelineSteps: {
+    readonly GRADE: "grade";
+    readonly FIND_SLOT: "find-slot";
+    readonly WRITE_TASK: "write-task";
+    readonly PREPARE: "prepare";
+    readonly DISPATCH: "dispatch";
+    readonly MONITOR: "monitor";
+    readonly SELF_REVIEW: "self-review";
+    readonly COMPLETE: "complete";
+    readonly HUMAN_GATE: "human-gate";
+    readonly FINALIZE: "finalize";
+    readonly CI_WATCH: "ci-watch";
+};
+export type PipelineStep = (typeof PipelineSteps)[keyof typeof PipelineSteps];
+export declare const FLOW_STEPS: Record<FlowType, PipelineStep[]>;
+/**
+ * Worker report artifact filename(s) per flow type, ordered by preference.
+ * The retrospective decision reads the first non-empty match.
+ *
+ * - `fix-bug` / `dev` workers write `report.md` (build, fixes, validation summary)
+ * - `pr-complete` worker writes `comments-report.md` (triage table, replies, fix commit)
+ * - `review-pr` worker writes `review.md` (verdict + line comments)
+ *
+ * Adding a new flow = add an entry. Adding a new artifact = prepend to the list.
+ * Falls back to `report.md` for any flow not listed.
+ */
+export declare const FLOW_WORKER_REPORT_ARTIFACTS: Record<FlowType, string[]>;
+/** Default branch fallback. Projects should set `default_branch` in project.json. */
+export declare const DEFAULT_BRANCH = "main";
+/** Default worker task directory (relative to repo root). Projects can override via `task_dir` in project.json. */
+export declare const DEFAULT_TASK_DIR = ".task";
+/** Default Claude model used when no slot/task/project/user override is set.
+ * Changing this value alters defaults across the dispatch wizard and gateway
+ * dispatch path — verify all `DEFAULT_CLAUDE_MODEL` callers when touching it. */
+export declare const DEFAULT_CLAUDE_MODEL = "opus";
+/** Default Cursor Agent model used when no slot/task/project/user override is set. */
+export declare const DEFAULT_CURSOR_MODEL = "composer-2";
+export type DecisionType = 'collision_check' | 'plan_confirmation' | 'retrospective' | 'review_posting' | 'blocked_alert' | 'review_comments' | 'improvement' | 'recipe_strategy' | `engine_${string}` | `monitor_${string}` | `ci_${string}`;
+/** Lightweight run summary for contextual display (e.g. decision cards). Derived from Run + RunMetrics. */
+export interface RunMeta {
+    runId: string;
+    familyId?: string;
+    flowType: FlowType;
+    ticketOrPr: string;
+    prNumber?: number;
+    branch?: string;
+    runner?: string;
+    model?: string;
+    summary?: string;
+}
+export interface PendingDecision {
+    id: string;
+    type: DecisionType;
+    slotId: string | null;
+    title: string;
+    description: string;
+    context: Record<string, unknown>;
+    actions: DecisionAction[];
+    createdAt: string;
+    runMeta?: RunMeta;
+    payload?: RunDecisionPayload;
+}
+export interface DecisionAction {
+    id: string;
+    label: string;
+    style: 'primary' | 'secondary' | 'danger';
+    /** Optional one-line explanation of what this action does and when to pick it. Renders as
+     *  hover tooltip + inline subtext under the button so operators don't have to guess. */
+    description?: string;
+}
+export interface ScriptOutput {
+    requestId: string;
+    stream: 'stdout' | 'stderr';
+    data: string;
+    timestamp: number;
+}
+export interface ScriptComplete {
+    requestId: string;
+    exitCode: number;
+    duration: number;
+    error?: string;
+    artifactRoot?: string;
+}
+//# sourceMappingURL=runs.d.ts.map