/** * Verification run driver shared by `commandmate verify` and `wait --verify` * (Issue #1544). * * The server answers a verify request with 202 and a run id rather than a * verdict — gates are whole test suites and builds — so every caller has to * start a run, poll it to a terminal status, and translate that status into an * exit code. That sequence lives here once so `verify` and `wait` cannot drift * apart on what "passed" means. * * @module cli/utils/verify-runner */ import type { VerificationFlakyDetail, VerificationGateTimingView, VerificationRunStatus, VerificationRunView } from '../types/api-responses'; import { ApiClient } from './api-client'; /** Matches the wait command's cadence; runs are minutes long, not seconds. */ export declare const VERIFY_POLL_INTERVAL_MS = 5000; /** * Issue #3983: how far past `--timeout` the read taken AT the deadline may run. * The poll sleeps only up to the deadline and reads once more there, so a run * that finished in the last interval still reports its verdict (#1544); this * bounds that one read rather than skipping it. */ export declare const VERIFY_FINAL_READ_GRACE_MS = 2000; /** Built-in gate id; mirrors WORK_EVIDENCE_GATE_ID in lib/verification/gate-runner.ts. */ export declare const WORK_EVIDENCE_GATE_ID = "work-evidence"; /** * Marker a mutexed gate writes into its log tail; mirrors MUTEX_LOG_PREFIX in * lib/verification/gate-runner.ts (Issue #1771). * * Mirrored rather than imported because `tsconfig.cli.json` compiles * `src/cli/**` alone with no path aliases, so the CLI bundle never pulls in the * server's dependency graph. `tests/unit/verification/gate-mutex.test.ts` pins * the two together by importing both. */ export declare const MUTEX_LOG_PREFIX = "[mutex]"; /** * Marker line carrying a gate's waits and its execution apart; mirrors * TIMING_LOG_PREFIX in lib/verification/gate-runner.ts (Issue #3884 / #3909). * * Mirrored rather than imported for the same reason the mutex prefix is, and * pinned to the runner's spelling (and to verification-db.ts parseGateTiming, * which reads the same line for the history listing) by * `tests/unit/cli/utils/verify-runner-timing-3909.test.ts`. */ export declare const TIMING_LOG_PREFIX = "[timing]"; /** * Read a gate's `[timing]` marker back into seconds (Issue #3909). * * @returns null for a gate with neither a `mutex` nor a slot wait, and for runs * recorded before the marker existed — those keep their old display. */ export declare function parseTimingMarker(logTail: string | null | undefined): VerificationGateTimingView | null; /** * `queue=… mutex=… run=…` in one decimal second, the spelling the marker uses. * Shared by the GATE line (`, ` between fields, like its other fields) and the * history listing (` `, inside one gate's parentheses). */ export declare function formatGateTiming(timing: VerificationGateTimingView, separator?: string): string; /** * Marker a retried gate writes into its log tail; mirrors FLAKY_LOG_PREFIX in * lib/verification/gate-runner.ts (Issue #1772). * * Mirrored rather than imported for the same reason the mutex prefix is, and * pinned to the runner's spelling by `tests/unit/verification/gate-flaky.test.ts`. */ export declare const FLAKY_LOG_PREFIX = "[flaky]"; /** * Label a gate whose two runs disagreed. Not a `VerificationGateStatus`: the * schema has no such status and #1772 added no migration, so FLAKY is a reading * of the marker laid over the stored `passed`/`failed` verdict. */ export declare const FLAKY_GATE_LABEL = "FLAKY"; /** * Read a retried gate's two runs back out of its log tail (Issue #1772). * * `verification_gate_results` stores one status, one exit code and one duration, * so the second run's numbers only exist in the log — the same carrier * work-evidence's counts and the scope gate's evidence already use. * * @returns null when the gate was never retried, which is every gate that did * not declare `retryOnFail: 1` and every one that passed first time. */ export declare function parseFlakyMarker(logTail: string | null | undefined): VerificationFlakyDetail | null; /** * Marker a gate's OWN command writes to say something about a PASS that the * verdict alone hides (Issue #3478) — e.g. `lint-sh` passing because shellcheck * is not installed, so nothing was linted. Mirrors GATE_NOTICE_LOG_PREFIX in * scripts/run-lint-sh-if-changed.mjs (pinned by its unit test). * * Unlike `[mutex]` / `[flaky]`, the gate writes this, not the runner, so it is * a message from the gate rather than evidence about it. It is printed only * beside a gate whose log is otherwise not shown (a PASS); a failing gate's log * is echoed whole and already carries the line. * * Not a `skipped` status: the runner aggregates `skipped` to RESULT error * (exit 99, no verdict), which would turn a deliberate "warn and continue" * into "could not judge". */ export declare const GATE_NOTICE_LOG_PREFIX = "[cmate-notice]"; /** * Read a gate's notices out of its log tail (Issue #3478). * @returns The notice texts in output order; empty when there are none. */ export declare function parseGateNotices(logTail: string | null | undefined): string[]; /** * Lines of a failing gate's log echoed to stderr before the rest becomes a * count (#1683). * * log_tail is byte-capped only when stored (options.maxLogTailBytes, default * 8KB but configurable up to 1MB), so echoing it whole lets one misconfigured * gate flood the terminal and scroll the GATE verdict lines out of sight. */ export declare const MAX_PRINTED_LOG_TAIL_LINES = 40; export interface VerificationRequest { worktreeId: string; /** 'manual' for the verify command, 'wait' when chained after wait. */ trigger: 'manual' | 'wait'; instanceId?: string; /** * Task the run judges. Omitted lets the server resolve the worktree's own * task, which is enough while that task is still open — `wait` names one * because the agent may close it before the run starts (#1620). */ taskId?: string; /** Omitted means work-evidence plus every gate declared in verify.yaml. */ gateIds?: string[]; /** Seconds before the CLI stops polling and reports TIMEOUT. */ timeoutSec?: number; /** Stream the final `RESULT ` line goes to. Defaults to stdout. */ resultStream?: 'stdout' | 'stderr'; /** Suppress the RESULT line because the caller prints JSON on stdout instead. */ suppressResultLine?: boolean; } export interface VerificationOutcome { exitCode: number; /** Last observed run; on timeout this is still `running`. */ run?: VerificationRunView; } /** * Translate a terminal run status into a process exit code. * * `error` and `cancelled` mean no verdict was reached, so they take the generic * UNEXPECTED_ERROR code rather than VERIFY_FAILED — a caller branching on 20 * must be able to trust that gates actually ran and judged the work. */ export declare function exitCodeForRunStatus(status: VerificationRunStatus): number; /** * Parse `--gates a,b` into a gate id list. * @returns The ids, or null when the value names no gate at all. */ export declare function parseGateIds(value: string | undefined): string[] | null | undefined; /** * Start a verification run and poll it to a verdict. * * @throws ApiError when the run cannot be started or the server stops answering */ export declare function runVerification(client: ApiClient, request: VerificationRequest): Promise; //# sourceMappingURL=verify-runner.d.ts.map