@farmslot/protocol 0.38.0 → 0.40.0

package/dist/contracts/runs.d.ts

@@ -1,4 +1,4 @@
-import type { ArtifactRef, SelfReviewIssue } from '../recipes/step-io.js';
+import type { ArtifactRef, ReviewIssue } from '../recipes/step-io.js';
 import type { WorkerSignalChecklistEvent, WorkerSignalChecklistTiming, WorkerSignalStatus } from '../transport/signal.js';
 import type { AcceptanceStatusLedger } from './acceptance.js';
 import type { AgentContext, AgentContextTarget, RunnerSessionArchiveRef, SafetyTier, ScriptedRunnerConfig, WorkerTransport } from './agents.js';
@@ -8,11 +8,13 @@ import type { EvidenceQualityReport, RecipeQualityArtifact } from './recipes.js'
 import type { ResourcePostureWaitPolicy, RunResourcePostureState } from './resource-posture.js';
 import type { ResourceType } from './resources.js';
 import type { RunImportProvenance } from './run-bundles.js';
+import type { RunGateReadiness } from './run-gate-readiness.js';
 import type { RuntimeCapabilityProofRequirement } from './runtime-capabilities.js';
 import type { SlotHealth } from './slots.js';
 import type { SubtaskSource } from './task.js';
 import type { ProfileFitSuggestion, ValidationPlanStep } from './validation-plan.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';
+import type { DeterministicChecklistCheck } from './worker-terminal.js';
+export type RunStatus = 'created' | 'grading' | 'writing-task' | 'slot-finding' | 'preparing' | 'dispatching' | 'monitoring' | 'reviewing' | 'fixing' | 'review-failed' | 'reconciling' | 'completing' | 'human-gating' | 'ci-watching' | 'paused' | 'done' | 'blocked' | 'failed' | 'cancelled';
 export declare const TERMINAL_RUN_STATUSES: readonly RunStatus[];
 export declare const ACTIVE_RUN_STATUSES: readonly RunStatus[];
 export declare function isTerminalRunStatus(status: RunStatus): boolean;
@@ -101,6 +103,8 @@ export interface EvidenceManifestStandalone {
 }
 export interface ReviewGatePayload {
     kind: 'review';
+    gateReadiness?: RunGateReadiness;
+    session?: ReviewSessionTrace;
     prNumber: number | null;
     repo: string | null;
     /** PR/project base branch used by the review diff workspace. */
@@ -120,48 +124,65 @@ export interface ReviewGatePayload {
     workerLearnings?: string;
 }
 /** Review evidence retained independently of the decision to publish it. */
-export type RunReviewResult = Pick<ReviewGatePayload, 'recommendation' | 'reviewMd' | 'lineComments' | 'reviewSnapshot' | 'artifactManifest' | 'reviewInputArtifactPaths'>;
+export type RunReviewResult = Pick<ReviewGatePayload, 'recommendation' | 'session' | 'reviewMd' | 'lineComments' | 'reviewSnapshot' | 'artifactManifest' | 'reviewInputArtifactPaths'>;
 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;
-    /** Independent review loops required beyond `minimumIndependentReviews`. */
-    extraLoopsRequested: number;
-    /** V2 counts the first configured loop in the minimum, not again as an extra. */
-    countingVersion?: 2;
+/** Publication count policy. Rechecking a review never creates another counted review. */
+export interface ReviewPolicy {
+    minimumReviews: number;
     requestedBy: 'dispatch' | 'human-gate' | 'agent-gate';
 }
-/**
- * Reviewer session lifecycle across one run's review loops:
- * `fresh-per-pass` relaunches a cold reviewer every pass; `warm-per-reviewer`
- * resumes the same reviewer runner session for re-reviews within the run.
- * Warm is the default: after the worker fixes findings, the re-review resumes
- * the reviewer's context instead of rebuilding the whole review. First passes
- * are always cold; runners without session reload fall back to cold.
- */
-export type ReviewSessionPolicy = 'fresh-per-pass' | 'warm-per-reviewer';
-export declare const REVIEW_SESSION_POLICIES: readonly ReviewSessionPolicy[];
-export declare const DEFAULT_REVIEW_SESSION_POLICY: ReviewSessionPolicy;
+/** Session and diff range are selected together. A first review is COLD. */
+export type ReviewMode = 'warm' | 'cold';
+export declare const REVIEW_MODES: readonly ReviewMode[];
+export declare const DEFAULT_REVIEW_MODE: ReviewMode;
+export declare function isReviewMode(value: unknown): value is ReviewMode;
+/** The only configurable review dimensions. Null explicitly selects the runner default. */
+export interface ReviewSelection {
+    runner: string;
+    model: string | null;
+    effort: string | null;
+    mode: ReviewMode;
+}
+/** Ordered reviewer selections. Array order is the execution order. */
+export type ReviewSequence = ReviewSelection[];
+/** Trusted request provenance, separate from the four configurable choices. */
+export interface ReviewContinuationContext {
+    repository: string;
+    prNumber: number;
+    reviewId: string;
+}
+/** Context rows align with the complete sequence, including the first request row. */
+export interface ReviewRequestContext {
+    reviewLineages: Array<ReviewContinuationContext | null>;
+}
+/** One gate receipt contains the first selection and any remaining ordered selections. */
+export interface ReviewRequestPayload extends ReviewSelection {
+    sequence?: ReviewSequence;
+    context?: ReviewRequestContext;
+}
 export type ReviewValidationDepth = 'static-code' | 'full-live';
-export type ReviewScope = 'incremental' | 'full';
-export declare const REVIEW_SCOPES: readonly ReviewScope[];
-export declare function isReviewScope(value: unknown): value is ReviewScope;
 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;
-/** Whether a repeat review should resume prior reviewer reasoning or start clean. */
-export type ReviewSessionIntent = 'resume' | 'reset';
-/** What actually happened when the reviewer generation launched. */
-export type ReviewSessionContinuity = 'fresh' | 'resumed' | 'fallback-fresh' | 'resume-unconfirmed';
-export type ReviewSessionFallbackReason = 'unsupported-runner' | 'slot-mismatch' | 'runner-mismatch' | 'model-mismatch' | 'missing-session' | 'session-unavailable';
+/** Observed launch provenance, kept separate from user selection. */
+export type ReviewSessionContinuity = 'fresh' | 'resumed' | 'resume-unconfirmed' | 'refused';
+export type ReviewSessionRefusalReason = 'unsupported-runner' | 'repository-mismatch' | 'pr-mismatch' | 'slot-mismatch' | 'runner-mismatch' | 'model-mismatch' | 'effort-mismatch' | 'missing-session' | 'missing-reviewed-head' | 'session-busy' | 'session-unavailable';
 export interface ReviewSessionTrace {
-    intent: ReviewSessionIntent;
+    mode: ReviewMode;
     continuity: ReviewSessionContinuity;
+    /** Durable reviewer lineage, independent of retry and run IDs. */
+    reviewId?: string;
+    repository?: string;
+    prNumber?: number;
+    lastReviewedHeadSha?: string;
+    runner?: string;
+    model?: string | null;
+    effort?: string | null;
     priorRunId?: string;
     priorSessionId?: string;
     sessionId?: string;
-    fallbackReason?: ReviewSessionFallbackReason;
+    refusalReason?: ReviewSessionRefusalReason;
 }
 /** Frozen summary for one run in a repeated-PR review chain. */
 export interface ReviewChainEntry {
@@ -173,7 +194,7 @@ export interface ReviewChainEntry {
     prNumber: number;
     baseSha?: string;
     headSha?: string;
-    reviewScope: ReviewScope;
+    mode: ReviewMode;
     validationDepth: ReviewValidationDepth;
     verdict: string;
     unresolvedCount: number | null;
@@ -188,7 +209,6 @@ export interface RepeatReviewContext {
     version: 1;
     chainId: string;
     generation: number;
-    contextMode: 'reuse' | 'fresh';
     priorRunId: string;
     priorFamilyId: string;
     repository: string;
@@ -197,31 +217,19 @@ export interface RepeatReviewContext {
     currentHeadSha: string;
     baseRef?: string;
     verdict: string;
-    unresolvedFindings: SelfReviewIssue[];
+    unresolvedFindings: ReviewIssue[];
     artifactRefs: EvidenceManifestEntry[];
     farmslotEvidenceRefs: EvidenceManifestEntry[];
     originatingRunId?: string;
-    reviewScope: ReviewScope;
+    mode: ReviewMode;
     validationDepth: ReviewValidationDepth;
-    incrementalUnavailableReason?: string;
-    /** Incremental may resume; every full review resets reviewer reasoning. */
-    sessionIntent?: ReviewSessionIntent;
+    warmUnavailableReason?: string;
     /** Dispatch-time observation of the requested reviewer-session transition. */
     session?: ReviewSessionTrace;
     /** Completed predecessors, oldest first. The current run is derived from this Run record. */
     priorGenerations?: ReviewChainEntry[];
 }
-export interface ReviewLoopRequest {
-    order: number;
-    runner: 'same' | ReviewRunnerId;
-    model?: string | null;
-    /** Reasoning / thinking level for this reviewer. Runner-specific (Codex, Grok, PI). */
-    effort?: string | null;
-    validationDepth?: ReviewValidationDepth;
-    /** Resume this run's reviewer context, or reset it before this review generation. */
-    sessionIntent?: ReviewSessionIntent;
-}
-export type ReviewRunnerId = 'claude' | 'codex' | 'cursor' | 'grok' | 'opencode' | 'pi';
+export type ReviewRunnerId = string;
 export interface DiffStat {
     files: number;
     additions: number;
@@ -283,17 +291,19 @@ export interface ReviewLoopTimelineSegment {
     startedAt: string;
     completedAt?: string;
     durationMs?: number;
-    verdict?: IndependentReviewAttempt['verdict'];
+    verdict?: ReviewAttempt['verdict'];
     unresolvedCount?: number;
     artifactPaths?: string[];
 }
-export interface IndependentReviewAttempt {
+export interface ReviewAttempt {
+    mode: ReviewMode;
+    session?: ReviewSessionTrace;
     loopNumber: number;
     verdict: 'pending' | 'pass' | 'issues' | 'failed' | 'cancelled' | 'skipped';
     unresolvedCount: number;
     /** Transport/lifecycle explanation when a review did not complete normally. */
     reason?: string;
-    issues?: SelfReviewIssue[];
+    issues?: ReviewIssue[];
     validationDepth?: ReviewValidationDepth;
     usage?: RunnerSessionUsage;
     /** Checklist marks and timings captured from this review round's role-scoped signal. */
@@ -306,21 +316,23 @@ export interface IndependentReviewAttempt {
     startedAt?: string;
     completedAt?: string;
 }
-export interface IndependentReviewStatus {
+export interface ReviewStatus {
     id: string;
-    source?: 'dispatch' | 'human-gate' | 'self-review';
+    source?: 'dispatch' | 'human-gate' | 'pipeline';
     runner?: string | null;
     model?: string | null;
     /** Reasoning / thinking level this reviewer launched with. */
     effort?: string | null;
+    mode: ReviewMode;
+    /** Verified review-session and exact-PR provenance, supplied by the runtime. */
+    session?: ReviewSessionTrace;
     reviewerSessionId?: string | null;
-    crossRunner: boolean;
     loopNumber: number;
     verdict: 'pending' | 'pass' | 'issues' | 'failed' | 'cancelled' | 'skipped';
     unresolvedCount: number;
     /** Transport/lifecycle explanation when a review did not complete normally. */
     reason?: string;
-    issues?: SelfReviewIssue[];
+    issues?: ReviewIssue[];
     validationDepth?: ReviewValidationDepth;
     usage?: RunnerSessionUsage;
     feedbackSent?: boolean;
@@ -328,11 +340,11 @@ export interface IndependentReviewStatus {
     recoveryContinuationPending?: boolean;
     /** Worker-fix attempts already consumed in this review loop. */
     retryCount?: number;
-    /** Effective worker-fix cap for this loop (`self_review.max_retries`, raised if Continue Fixing authorizes another pass). */
+    /** Effective worker-fix cap for this loop (`review.max_retries`, raised if Continue Fixing authorizes another pass). */
     maxRetries?: number;
     /** True when the loop stopped because retryCount reached maxRetries with findings still open. */
     maxRetriesExhausted?: boolean;
-    attempts?: IndependentReviewAttempt[];
+    attempts?: ReviewAttempt[];
     artifactPaths?: string[];
     taskProgressArtifactPath?: string;
     timeline?: ReviewLoopTimelineSegment[];
@@ -385,7 +397,7 @@ export type GateSummaryKind = (typeof GATE_SUMMARY_KINDS)[keyof typeof GATE_SUMM
  * review outcomes are the headline; token cost is a supporting section.
  *
  * Built by `buildGateSummary` in the gateway by *projecting* already-captured
- * state ({@link IndependentReviewStatus}, {@link RunMetrics}, family runs) — it
+ * state ({@link ReviewStatus}, {@link RunMetrics}, family runs) — it
  * does not re-derive review state or re-read artifacts.
  */
 export interface GateSummary {
@@ -394,7 +406,7 @@ export interface GateSummary {
     flowType?: FlowType;
     /** Who owns/authorizes the gate and why (reused from the gate policy). */
     gatePolicy?: GatePolicy;
-    /** One-line human narrative, e.g. "Worker done in 55 turns; self-review skipped (lightweight dev); 0 reviews triggered re-work." */
+    /** One-line human narrative, e.g. "Worker done in 55 turns; review skipped (lightweight dev); 0 reviews triggered re-work." */
     headline?: string;
     worker: {
         model: string | null;
@@ -440,9 +452,9 @@ export interface GateSummary {
     custom?: Record<string, unknown>;
     capturedAt?: string;
 }
-/** Review outcomes for a gate, projected from self-review + independent reviews. */
+/** Review outcomes for a gate, projected from review + reviews. */
 export interface ReviewSummary {
-    selfReview?: {
+    review?: {
         status: 'skipped' | 'done' | 'failed' | 'pending';
         /** Descriptive reason when skipped/failed, e.g. "disabled-lightweight-dev-flow". */
         reason?: string;
@@ -452,13 +464,12 @@ export interface ReviewSummary {
         triggeredReWork: boolean;
         artifactPaths?: string[];
     };
-    /** Projected from {@link IndependentReviewStatus} — outcome-first, no raw artifacts. */
-    independentReviews: Array<{
+    /** Projected from {@link ReviewStatus} — outcome-first, no raw artifacts. */
+    reviews: Array<{
         id: string;
-        source?: 'dispatch' | 'human-gate' | 'self-review';
+        source?: 'dispatch' | 'human-gate' | 'pipeline';
         runner?: string | null;
         model?: string | null;
-        crossRunner: boolean;
         loopNumber: number;
         verdict: 'pending' | 'pass' | 'issues' | 'failed' | 'cancelled' | 'skipped';
         unresolvedCount: number;
@@ -470,7 +481,7 @@ export interface ReviewSummary {
         startedAt?: string;
         completedAt?: string;
     }>;
-    /** Reviews required by the gate's {@link ReviewDepthPolicy}, if any. */
+    /** Reviews required by the gate's {@link ReviewPolicy}, if any. */
     requiredReviews?: number;
     passingReviews: number;
     totalUnresolved: number;
@@ -489,7 +500,7 @@ export interface GateTokenSummary {
         turns: number;
     };
     /**
-     * Per independent review (from {@link IndependentReviewStatus.usage}). The
+     * Per review (from {@link ReviewStatus.usage}). The
      * input/output/cache split is present when the review's usage record carried
      * it; older entries may only have `total`.
      */
@@ -560,7 +571,7 @@ export interface ReadyGatePrPackage {
     remoteBranchRef?: string | null;
     headSha?: string;
     diffStat: DiffStat;
-    /** Exact worktree diff identity captured with the same scope as independent reviews. */
+    /** Exact worktree diff identity captured with the same scope as reviews. */
     reviewSnapshot?: ReviewDiffSnapshot;
     draftTitle: string;
     draftBody: string;
@@ -568,11 +579,13 @@ export interface ReadyGatePrPackage {
     selectedEvidenceKeys?: string[];
     validationSummaryPath?: string | null;
     validationSummaryHash?: string | null;
+    /** Verified local command receipts for this package's source inputs, ADR-064. */
+    deterministicChecks?: DeterministicChecklistCheck[];
     reviewArtifactIds: string[];
     dispatchMode?: 'interactive' | 'autonomous' | 'validation';
     gatePolicy: GatePolicy;
     /** Frozen at package preparation time so approval/review policy cannot drift with config edits. */
-    reviewDepth?: ReviewDepthPolicy;
+    reviewPolicy?: ReviewPolicy;
     publicationTarget: PublicationTarget;
     publicationStatus: PublicationStatus;
     supersededByPackageId?: string | null;
@@ -589,6 +602,7 @@ export interface ReadyGateInputSnapshot {
 }
 export interface ReadyGatePayload {
     kind: 'ready';
+    gateReadiness?: RunGateReadiness;
     prNumber: number | null;
     repo: string | null;
     diffStat: DiffStat;
@@ -607,8 +621,8 @@ export interface ReadyGatePayload {
     recipeQualityArtifact?: RecipeQualityArtifact | null;
     qualityReport?: EvidenceQualityReport | null;
     artifactManifest?: EvidenceManifestEntry[];
-    selfReviewVerdict?: string;
-    selfReviewSummary?: string;
+    reviewVerdict?: string;
+    reviewSummary?: string;
     workerLearnings?: string;
     ciChecks?: Array<{
         name: string;
@@ -638,8 +652,8 @@ export interface ReadyGatePayload {
         body: string;
         publishedAt?: string;
     };
-    reviewDepth?: ReviewDepthPolicy;
-    independentReviews?: IndependentReviewStatus[];
+    reviewPolicy?: ReviewPolicy;
+    reviews?: ReviewStatus[];
     reviewLaunchRejection?: PublicationReviewLaunchRejection;
     gatePolicy?: GatePolicy;
     /** Consolidated "what happened to reach this gate" snapshot (worker → reviews → cost). */
@@ -685,6 +699,7 @@ export interface EvidenceRefreshOverrideRecord {
 }
 export interface NoChangeGatePayload {
     kind: 'no-change';
+    gateReadiness?: RunGateReadiness;
     disposition: WorkerTerminalDisposition;
     reason?: string;
     evidence?: WorkerTerminalEvidence;
@@ -873,8 +888,8 @@ export interface RetrospectivePayload {
     kind: 'retrospective';
     outcome: 'success' | 'failure' | 'partial' | 'cancelled' | 'unknown';
     whatThisIs: string;
-    selfReviewVerdict?: string;
-    selfReviewSummary?: string;
+    reviewVerdict?: string;
+    reviewSummary?: string;
     workerLearnings?: string;
     reportExcerpt?: string;
     ciWatch?: {
@@ -1005,10 +1020,11 @@ export interface RunDecision {
     triageAssessmentId?: string;
     payload?: RunDecisionPayload;
     /**
-     * Payload keys `run.list` left out because their values are large (review
+     * Detail keys `run.list` left out because their values are large (review
      * markdown, input snapshots, PR packages, artifact manifests). Absent on
      * `run.get`, `run.forSlot` and every run event, which carry the full
-     * payload; a reader that needs one of these keys fetches the run directly.
+     * payload/context; `context.checkSnapshot` also names omitted CI context.
+     * A reader that needs one of these keys fetches the run directly.
      */
     payloadTrimmed?: string[];
     selectionData?: Record<string, unknown>;
@@ -2052,7 +2068,8 @@ export interface Run {
     /** Code breadth for review-pr. Independent from runtime validation depth. */
     /** Explicitly finish static review without waiting for operator questions/publication. */
     reviewAutoFinish?: boolean;
-    reviewScope?: ReviewScope;
+    reviewMode?: ReviewMode;
+    reviewContext?: ReviewRequestContext;
     /** Static by default; full-live is an explicit operator escalation. */
     reviewValidationDepth?: ReviewValidationDepth;
     /** Frozen provenance for a repeated review of the same canonical PR. */
@@ -2125,13 +2142,13 @@ export declare function isInteractiveDevRun(run: Pick<Run, 'flowType' | 'mode'>)
 /** Persisted run-engine state — see ADR-027. */
 export interface RunEngineState {
     /**
-     * What the last passing review (pipeline self-review or a publication review)
+     * What the last passing review (pipeline review or a publication review)
      * judged on the slot: HEAD, the evidence manifest and the evidence files. When
-     * any of them changes, self-review must run again before publication is
+     * any of them changes, review must run again before publication is
      * approved; the PR description is not part of it. Records taken while the
      * description was still included keep matching until HEAD or evidence changes,
-     * except that a description edit on such a record re-runs self-review once.
-     * `rerunFor` is the changed state self-review already ran again for, so it runs
+     * except that a description edit on such a record re-runs review once.
+     * `rerunFor` is the changed state review already ran again for, so it runs
      * once per change.
      */
     reviewedInputs?: {
@@ -2199,11 +2216,12 @@ export interface RunEngineState {
         publicationTarget?: PublicationTarget;
         publicationStatus?: PublicationStatus;
         prNumber?: number | null;
-        reviewDepth?: ReviewDepthPolicy;
-        pendingReviewPlan?: ReviewLoopRequest[];
+        reviewPolicy?: ReviewPolicy;
+        reviewSequence?: ReviewSequence;
+        reviewSequenceContext?: ReviewRequestContext;
         /** Creation time for the current pending plan, used to ignore reviews from earlier work orders. */
-        pendingReviewPlanRequestedAt?: string;
-        independentReviews?: IndependentReviewStatus[];
+        reviewSequenceRequestedAt?: string;
+        reviews?: ReviewStatus[];
         /** Latest recoverable refusal to launch a publication reviewer. */
         reviewLaunchRejection?: PublicationReviewLaunchRejection;
         supersededPackageIds?: string[];
@@ -2293,7 +2311,7 @@ export interface FamilyDiffProvenance {
     error?: string;
     repository?: string;
     prNumber?: number;
-    reviewScope?: ReviewScope;
+    reviewMode?: ReviewMode;
 }
 export declare function isFamilyDiffProvenance(value: unknown): value is FamilyDiffProvenance;
 export interface FamilyInputCommitMetadata {
@@ -2303,7 +2321,7 @@ export interface FamilyInputCommitMetadata {
     baseSha?: string;
     headRef?: string;
     headSha?: string;
-    reviewScope?: ReviewScope;
+    reviewMode?: ReviewMode;
     capturedAt: string;
     source: 'github-pr' | 'local-git' | 'unavailable';
     missingReason?: string;
@@ -2425,7 +2443,7 @@ export declare function normalizeFlowType(value: string | null | undefined): Flo
 export declare function normalizeCiActionId(actionId: string): string;
 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 type DevInteractiveCompletionAction = 'done-no-pr' | 'detect-pr-and-ci-watch' | 'link-pr-and-ci-watch' | 'link-pr-and-pr-complete' | 'run-review' | 'blocked' | 'failed' | 'abort';
 export interface DevInteractiveActionRecord {
     action: DevInteractiveCompletionAction;
     source: 'operator';
@@ -2441,7 +2459,7 @@ export declare const PipelineSteps: {
     readonly PREPARE: "prepare";
     readonly DISPATCH: "dispatch";
     readonly MONITOR: "monitor";
-    readonly SELF_REVIEW: "self-review";
+    readonly REVIEW: "review";
     readonly COMPLETE: "complete";
     readonly HUMAN_GATE: "human-gate";
     readonly FINALIZE: "finalize";