@deftai/directive-core 0.67.0 → 0.68.0

package/dist/pr-watch/constants.d.ts

@@ -0,0 +1,33 @@
+/**
+ * task pr:watch -- deterministic PR-verdict polling surface (#1056).
+ *
+ * Three-state exit contract (AC-1): mirrors scripts/preflight_branch.py (#747)
+ * and pr:merge-ready (#796) -- the invocation IS the wait, so an orchestrator
+ * cannot promise to poll and then silently forget (2026-05-11 three-strikes on
+ * #1051 / #1054).
+ */
+/** CLEAN: SHA-matched, non-errored, no P0/P1, confidence > 3, CI green. */
+export declare const EXIT_CLEAN = 0;
+/** NEW_P0_P1: blocking findings on the CURRENT (SHA-matched) review. */
+export declare const EXIT_NEW_P0_P1 = 1;
+/** ERRORED | STALL | TIMEOUT | config-error all collapse to a single non-zero. */
+export declare const EXIT_TERMINAL_ERROR = 2;
+export declare const VERDICT_CLEAN = "CLEAN";
+export declare const VERDICT_NEW_P0_P1 = "NEW_P0_P1";
+export declare const VERDICT_ERRORED = "ERRORED";
+export declare const VERDICT_STALL = "STALL";
+export declare const VERDICT_TIMEOUT = "TIMEOUT";
+/** --one-shot only: a single probe with no terminal verdict yet. */
+export declare const VERDICT_PENDING = "PENDING";
+/** External/config fault mid-probe (unresolvable repo/HEAD, gh unavailable). */
+export declare const VERDICT_CONFIG = "CONFIG";
+export declare const DEFAULT_MAX_WAIT_MINUTES = 30;
+export declare const DEFAULT_POLL_SECONDS = 90;
+/**
+ * Consecutive polls with a review PRESENT but stuck on a stale (non-HEAD)
+ * commit before the loop surfaces STALL instead of waiting the full cap. Keeps
+ * a Greptile review that never re-reviews the new HEAD from silently eating the
+ * whole 30-minute budget (#1039 STALL terminal).
+ */
+export declare const DEFAULT_STALL_THRESHOLD = 3;
+//# sourceMappingURL=constants.d.ts.map

package/dist/pr-watch/constants.js

@@ -0,0 +1,33 @@
+/**
+ * task pr:watch -- deterministic PR-verdict polling surface (#1056).
+ *
+ * Three-state exit contract (AC-1): mirrors scripts/preflight_branch.py (#747)
+ * and pr:merge-ready (#796) -- the invocation IS the wait, so an orchestrator
+ * cannot promise to poll and then silently forget (2026-05-11 three-strikes on
+ * #1051 / #1054).
+ */
+/** CLEAN: SHA-matched, non-errored, no P0/P1, confidence > 3, CI green. */
+export const EXIT_CLEAN = 0;
+/** NEW_P0_P1: blocking findings on the CURRENT (SHA-matched) review. */
+export const EXIT_NEW_P0_P1 = 1;
+/** ERRORED | STALL | TIMEOUT | config-error all collapse to a single non-zero. */
+export const EXIT_TERMINAL_ERROR = 2;
+export const VERDICT_CLEAN = "CLEAN";
+export const VERDICT_NEW_P0_P1 = "NEW_P0_P1";
+export const VERDICT_ERRORED = "ERRORED";
+export const VERDICT_STALL = "STALL";
+export const VERDICT_TIMEOUT = "TIMEOUT";
+/** --one-shot only: a single probe with no terminal verdict yet. */
+export const VERDICT_PENDING = "PENDING";
+/** External/config fault mid-probe (unresolvable repo/HEAD, gh unavailable). */
+export const VERDICT_CONFIG = "CONFIG";
+export const DEFAULT_MAX_WAIT_MINUTES = 30;
+export const DEFAULT_POLL_SECONDS = 90;
+/**
+ * Consecutive polls with a review PRESENT but stuck on a stale (non-HEAD)
+ * commit before the loop surfaces STALL instead of waiting the full cap. Keeps
+ * a Greptile review that never re-reviews the new HEAD from silently eating the
+ * whole 30-minute budget (#1039 STALL terminal).
+ */
+export const DEFAULT_STALL_THRESHOLD = 3;
+//# sourceMappingURL=constants.js.map

package/dist/pr-watch/index.d.ts

@@ -0,0 +1,6 @@
+export * from "./constants.js";
+export { cmdPrWatch, emitWatchJson, type ParsedWatchArgs, parseWatchArgs, printWatchHuman, type RunWatchOptions, runWatch, watchResultToJson, } from "./main.js";
+export { probeOnce } from "./probe.js";
+export * from "./types.js";
+export { formatWatchStatus, watch } from "./watch.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/pr-watch/index.js

@@ -0,0 +1,6 @@
+export * from "./constants.js";
+export { cmdPrWatch, emitWatchJson, parseWatchArgs, printWatchHuman, runWatch, watchResultToJson, } from "./main.js";
+export { probeOnce } from "./probe.js";
+export * from "./types.js";
+export { formatWatchStatus, watch } from "./watch.js";
+//# sourceMappingURL=index.js.map

package/dist/pr-watch/main.d.ts

@@ -0,0 +1,21 @@
+import type { WatchOptions, WatchResult } from "./types.js";
+export interface ParsedWatchArgs {
+    readonly prNumber: number | null;
+    readonly repo: string | null;
+    readonly maxWaitMinutes: number;
+    readonly pollSeconds: number;
+    readonly oneShot: boolean;
+    readonly emitJson: boolean;
+    readonly projectRoot: string | null;
+    readonly error?: string;
+}
+export declare function parseWatchArgs(argv: readonly string[]): ParsedWatchArgs;
+/** AC-4 stable --json shape (same field set as the #1039 Tier-1 instrumentation line). */
+export declare function watchResultToJson(result: WatchResult): Record<string, unknown>;
+export declare function emitWatchJson(result: WatchResult): string;
+export declare function printWatchHuman(result: WatchResult): string;
+export interface RunWatchOptions extends WatchOptions {
+}
+export declare function runWatch(argv: readonly string[], options?: RunWatchOptions): number;
+export declare function cmdPrWatch(argv: readonly string[], options?: RunWatchOptions): number;
+//# sourceMappingURL=main.d.ts.map

package/dist/pr-watch/main.js

@@ -0,0 +1,206 @@
+import { existsSync } from "node:fs";
+import { resolve } from "node:path";
+import { defaultRunGh } from "../pr-merge-readiness/gh.js";
+import { DEFAULT_MAX_WAIT_MINUTES, DEFAULT_POLL_SECONDS, EXIT_TERMINAL_ERROR, } from "./constants.js";
+import { watch } from "./watch.js";
+function fail(base, error) {
+    return { ...base, error };
+}
+export function parseWatchArgs(argv) {
+    const acc = {
+        prNumber: null,
+        repo: null,
+        maxWaitMinutes: DEFAULT_MAX_WAIT_MINUTES,
+        pollSeconds: DEFAULT_POLL_SECONDS,
+        oneShot: false,
+        emitJson: false,
+        projectRoot: null,
+    };
+    let prNumber = null;
+    let repo = null;
+    let maxWaitMinutes = DEFAULT_MAX_WAIT_MINUTES;
+    let pollSeconds = DEFAULT_POLL_SECONDS;
+    let oneShot = false;
+    let emitJson = false;
+    let projectRoot = null;
+    const takePositive = (label, raw) => {
+        if (raw === undefined) {
+            return { error: `argument ${label}: expected one argument` };
+        }
+        const parsed = Number(raw);
+        if (!Number.isFinite(parsed) || parsed < 0) {
+            return { error: `invalid ${label} value: ${raw}` };
+        }
+        return { value: parsed };
+    };
+    for (let i = 0; i < argv.length; i += 1) {
+        const arg = argv[i];
+        if (arg === "--json") {
+            emitJson = true;
+        }
+        else if (arg === "--one-shot") {
+            oneShot = true;
+        }
+        else if (arg === "--repo") {
+            const value = argv[i + 1];
+            if (value === undefined) {
+                return fail(acc, "argument --repo: expected one argument");
+            }
+            repo = value;
+            i += 1;
+        }
+        else if (arg?.startsWith("--repo=")) {
+            repo = arg.slice("--repo=".length);
+        }
+        else if (arg === "--max-wait-minutes") {
+            const r = takePositive("--max-wait-minutes", argv[i + 1]);
+            if ("error" in r)
+                return fail(acc, r.error);
+            maxWaitMinutes = r.value;
+            i += 1;
+        }
+        else if (arg?.startsWith("--max-wait-minutes=")) {
+            const r = takePositive("--max-wait-minutes", arg.slice("--max-wait-minutes=".length));
+            if ("error" in r)
+                return fail(acc, r.error);
+            maxWaitMinutes = r.value;
+        }
+        else if (arg === "--poll-seconds") {
+            const r = takePositive("--poll-seconds", argv[i + 1]);
+            if ("error" in r)
+                return fail(acc, r.error);
+            pollSeconds = r.value;
+            i += 1;
+        }
+        else if (arg?.startsWith("--poll-seconds=")) {
+            const r = takePositive("--poll-seconds", arg.slice("--poll-seconds=".length));
+            if ("error" in r)
+                return fail(acc, r.error);
+            pollSeconds = r.value;
+        }
+        else if (arg === "--project-root") {
+            const value = argv[i + 1];
+            if (value === undefined) {
+                return fail(acc, "argument --project-root: expected one argument");
+            }
+            projectRoot = value;
+            i += 1;
+        }
+        else if (arg?.startsWith("--project-root=")) {
+            projectRoot = arg.slice("--project-root=".length);
+        }
+        else if (arg?.startsWith("-")) {
+            return fail(acc, `unrecognized arguments: ${arg}`);
+        }
+        else if (prNumber === null) {
+            const n = Number(arg);
+            if (!Number.isInteger(n) || n <= 0) {
+                return fail(acc, `invalid PR number: ${arg}`);
+            }
+            prNumber = n;
+        }
+        else {
+            return fail(acc, `unrecognized arguments: ${arg}`);
+        }
+    }
+    if (prNumber === null) {
+        return fail(acc, "the following arguments are required: pr_number");
+    }
+    return { prNumber, repo, maxWaitMinutes, pollSeconds, oneShot, emitJson, projectRoot };
+}
+/** Match Python json.dumps(..., indent=2) default ensure_ascii=True. */
+function pythonJsonDumps(value) {
+    const json = JSON.stringify(value, null, 2);
+    return json.replace(/[\u007f-\uffff]/g, (ch) => {
+        const code = ch.charCodeAt(0);
+        return `\\u${code.toString(16).padStart(4, "0")}`;
+    });
+}
+/** AC-4 stable --json shape (same field set as the #1039 Tier-1 instrumentation line). */
+export function watchResultToJson(result) {
+    const p = result.probe;
+    return {
+        verdict: result.verdict,
+        pr_number: result.prNumber,
+        head_sha: p.headSha,
+        last_reviewed_sha: p.lastReviewedSha,
+        sha_match: p.shaMatch,
+        confidence: p.confidence,
+        p0_count: p.p0Count,
+        p1_count: p.p1Count,
+        errored: p.errored,
+        ci_failures: p.ciFailures,
+        is_clean: p.isClean,
+        clean_gate_holdout: p.cleanGateHoldout,
+        elapsed_seconds: result.elapsedSeconds,
+        poll_count: result.pollCount,
+    };
+}
+export function emitWatchJson(result) {
+    return `${pythonJsonDumps(watchResultToJson(result))}\n`;
+}
+export function printWatchHuman(result) {
+    const p = result.probe;
+    const lines = [];
+    lines.push(`PR #${result.prNumber} pr:watch verdict: ${result.verdict}`);
+    lines.push(`  HEAD SHA:           ${p.headSha ?? "<unknown>"}`);
+    lines.push(`  Greptile reviewed:  ${p.lastReviewedSha ?? "<not parsed>"}`);
+    lines.push(`  SHA match:          ${p.shaMatch}`);
+    lines.push(`  Confidence:         ${p.confidence !== null ? String(p.confidence) : "<not parsed>"}/5`);
+    lines.push(`  Findings:           P0=${p.p0Count}  P1=${p.p1Count}`);
+    lines.push(`  Errored sentinel:   ${p.errored}`);
+    lines.push(`  CI failures:        ${p.ciFailures}`);
+    if (p.cleanGateHoldout !== null) {
+        lines.push(`  Clean-gate holdout: ${p.cleanGateHoldout}`);
+    }
+    if (p.error !== null) {
+        lines.push(`  Error:              ${p.error}`);
+    }
+    lines.push(`  Polls / elapsed:    ${result.pollCount} poll(s) / ${result.elapsedSeconds}s`);
+    return `${lines.join("\n")}\n`;
+}
+export function runWatch(argv, options = {}) {
+    const args = parseWatchArgs(argv);
+    if (args.error !== undefined) {
+        process.stderr.write(`pr_watch: ${args.error}\n`);
+        return EXIT_TERMINAL_ERROR;
+    }
+    let restoreCwd = null;
+    if (args.projectRoot !== null) {
+        const target = resolve(args.projectRoot);
+        if (!existsSync(target)) {
+            process.stderr.write(`pr_watch: --project-root does not exist: ${target}\n`);
+            return EXIT_TERMINAL_ERROR;
+        }
+        restoreCwd = process.cwd();
+        process.chdir(target);
+    }
+    try {
+        const result = watch(args.prNumber, args.repo ?? process.env.GH_REPO ?? null, {
+            maxWaitMinutes: args.maxWaitMinutes,
+            pollSeconds: args.pollSeconds,
+            oneShot: args.oneShot,
+            runGh: options.runGh ?? defaultRunGh,
+            sleepFn: options.sleepFn,
+            clockFn: options.clockFn,
+            probeFn: options.probeFn,
+            stallThreshold: options.stallThreshold,
+        });
+        if (args.emitJson) {
+            process.stdout.write(emitWatchJson(result));
+        }
+        else {
+            process.stdout.write(printWatchHuman(result));
+        }
+        return result.exitCode;
+    }
+    finally {
+        if (restoreCwd !== null) {
+            process.chdir(restoreCwd);
+        }
+    }
+}
+export function cmdPrWatch(argv, options = {}) {
+    return runWatch(argv, options);
+}
+//# sourceMappingURL=main.js.map

package/dist/pr-watch/probe.d.ts

@@ -0,0 +1,13 @@
+import type { RunGhFn } from "../pr-merge-readiness/types.js";
+import type { WatchProbe } from "./types.js";
+/**
+ * Run one PR-verdict probe: resolve HEAD, fetch the latest Greptile/SLizard
+ * rolling-summary body, and score it through the CANONICAL shared detector
+ * (`detect` / `parseConfidence` / `parseLastReviewedSha*` / `evaluateCleanGate`
+ * from content-contracts/skills/greptile-detector.ts -- the same module the
+ * swarm poller template and its #910/#1035/#1039 tests consume). No second
+ * detector (#1056 AC-2). All gh access routes through the injectable RunGhFn
+ * seam, which defaults to the UTF-8-safe execFile capture (#1366).
+ */
+export declare function probeOnce(prNumber: number, repoArg: string | null, runGh?: RunGhFn): WatchProbe;
+//# sourceMappingURL=probe.d.ts.map

package/dist/pr-watch/probe.js

@@ -0,0 +1,100 @@
+import { detect, evaluateCleanGate, parseConfidence, parseLastReviewedShaMarkdownLink, parseLastReviewedShaNaiveInline, } from "../content-contracts/skills/greptile-detector.js";
+import { evaluateCiGate } from "../pr-merge-readiness/ci-gate.js";
+import { GREPTILE_ERRORED_SENTINEL } from "../pr-merge-readiness/constants.js";
+import { defaultRunGh, fetchCheckRunsRest, fetchGreptileBodyRest, fetchGreptileCommentBody, fetchPrHeadSha, fetchPrHeadShaRest, resolveRepo, } from "../pr-merge-readiness/gh.js";
+function errorProbe(headSha, message) {
+    return {
+        found: false,
+        headSha,
+        lastReviewedSha: null,
+        shaMatch: false,
+        confidence: null,
+        p0Count: 0,
+        p1Count: 0,
+        hasBlocking: false,
+        errored: false,
+        ciFailures: 0,
+        terminalCheckRun: false,
+        isClean: false,
+        cleanGateHoldout: null,
+        error: message,
+    };
+}
+/**
+ * Run one PR-verdict probe: resolve HEAD, fetch the latest Greptile/SLizard
+ * rolling-summary body, and score it through the CANONICAL shared detector
+ * (`detect` / `parseConfidence` / `parseLastReviewedSha*` / `evaluateCleanGate`
+ * from content-contracts/skills/greptile-detector.ts -- the same module the
+ * swarm poller template and its #910/#1035/#1039 tests consume). No second
+ * detector (#1056 AC-2). All gh access routes through the injectable RunGhFn
+ * seam, which defaults to the UTF-8-safe execFile capture (#1366).
+ */
+export function probeOnce(prNumber, repoArg, runGh = defaultRunGh) {
+    const resolved = resolveRepo(repoArg, runGh);
+    const repo = resolved.repo;
+    // 1. HEAD SHA -- primary `gh pr view`, then REST fallback when a repo resolved.
+    let headSha = fetchPrHeadSha(prNumber, repo, runGh);
+    if (headSha === null && repo !== null) {
+        headSha = fetchPrHeadShaRest(prNumber, repo, runGh).sha;
+    }
+    if (headSha === null) {
+        const detail = repo === null
+            ? `could not resolve repo (${resolved.error}); run inside a repo or pass --repo OWNER/REPO`
+            : "could not resolve PR HEAD sha (gh pr view + REST both failed)";
+        return errorProbe(null, detail);
+    }
+    // 2. Latest Greptile body -- primary jq path, then REST fallback.
+    let body = fetchGreptileCommentBody(prNumber, repo, runGh);
+    if (body === null && repo !== null) {
+        body = fetchGreptileBodyRest(prNumber, repo, runGh).body;
+    }
+    if (body === null) {
+        return errorProbe(headSha, "could not fetch Greptile comment body (primary + REST both failed)");
+    }
+    const trimmed = body.trim();
+    const found = trimmed.length > 0;
+    const errored = trimmed.startsWith(GREPTILE_ERRORED_SENTINEL);
+    const findings = detect(body);
+    const confidence = parseConfidence(body);
+    const lastReviewedSha = parseLastReviewedShaMarkdownLink(body) ?? parseLastReviewedShaNaiveInline(body);
+    // 3. CI failures (best-effort). When check-runs are unreachable we degrade to
+    // ci_failures=0 / terminal so the Greptile verdict drives; the merge button
+    // still owns the hard CI gate via pr:merge-ready (#796).
+    let ciFailures = 0;
+    let terminalCheckRun = true;
+    if (repo !== null) {
+        const check = fetchCheckRunsRest(headSha, repo, runGh);
+        if (check.summary !== null) {
+            const ci = evaluateCiGate(check.checkRuns, {});
+            ciFailures = ci.summary.failed_required.length;
+            terminalCheckRun = ci.summary.pending_required.length === 0;
+        }
+    }
+    const shaMatch = lastReviewedSha !== null && lastReviewedSha === headSha;
+    const [isClean, cleanGateHoldout] = evaluateCleanGate({
+        lastReviewedSha,
+        headSha,
+        hasBlocking: findings.has_blocking,
+        confidence,
+        ciFailures,
+        errored,
+        terminalCheckRun,
+    });
+    return {
+        found,
+        headSha,
+        lastReviewedSha,
+        shaMatch,
+        confidence,
+        p0Count: findings.p0_count,
+        p1Count: findings.p1_count,
+        hasBlocking: findings.has_blocking,
+        errored,
+        ciFailures,
+        terminalCheckRun,
+        isClean,
+        cleanGateHoldout,
+        error: null,
+    };
+}
+//# sourceMappingURL=probe.js.map

package/dist/pr-watch/types.d.ts

@@ -0,0 +1,47 @@
+import type { RunGhFn } from "../pr-merge-readiness/types.js";
+/** One resolved poll snapshot -- the parsed verdict + SHA-match gate for a PR. */
+export interface WatchProbe {
+    /** A Greptile/SLizard rolling-summary comment was present (non-empty body). */
+    readonly found: boolean;
+    readonly headSha: string | null;
+    readonly lastReviewedSha: string | null;
+    /** last_reviewed_sha === head_sha -- the SHA-match gate (#1056 stale-review guard). */
+    readonly shaMatch: boolean;
+    readonly confidence: number | null;
+    readonly p0Count: number;
+    readonly p1Count: number;
+    readonly hasBlocking: boolean;
+    readonly errored: boolean;
+    readonly ciFailures: number;
+    /** All required CI check-runs have a terminal conclusion (none pending). */
+    readonly terminalCheckRun: boolean;
+    readonly isClean: boolean;
+    /** First unmet clean-gate condition (evaluateCleanGate holdout), or null when clean. */
+    readonly cleanGateHoldout: string | null;
+    /** Non-null when the probe hit an external/config fault (unresolvable repo/HEAD, gh down). */
+    readonly error: string | null;
+}
+export type SleepFn = (seconds: number) => void;
+export interface MonotonicClock {
+    now(): number;
+}
+export type ProbeFn = (prNumber: number, repo: string | null, runGh: RunGhFn) => WatchProbe;
+export interface WatchOptions {
+    readonly maxWaitMinutes?: number;
+    readonly pollSeconds?: number;
+    readonly oneShot?: boolean;
+    readonly stallThreshold?: number;
+    readonly runGh?: RunGhFn;
+    readonly sleepFn?: SleepFn;
+    readonly clockFn?: MonotonicClock;
+    readonly probeFn?: ProbeFn;
+}
+export interface WatchResult {
+    readonly verdict: string;
+    readonly exitCode: number;
+    readonly prNumber: number;
+    readonly probe: WatchProbe;
+    readonly elapsedSeconds: number;
+    readonly pollCount: number;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/pr-watch/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/pr-watch/watch.d.ts

@@ -0,0 +1,12 @@
+import type { WatchOptions, WatchProbe, WatchResult } from "./types.js";
+/** One-line stderr status mirror per poll (Tier 1 instrumentation shape, #1039). */
+export declare function formatWatchStatus(poll: number, maxPolls: number, probe: WatchProbe, elapsedSeconds: number): string;
+/**
+ * Blocking-by-default poll to a terminal three-state verdict (#1056). Default
+ * behaviour is a synchronous wait, so a linear caller (human shell, CI step,
+ * single-process agent) gets the verdict for free; --one-shot degrades to a
+ * single probe. SHA-match gating means a stale review posted BEFORE your push
+ * is never read as the verdict.
+ */
+export declare function watch(prNumber: number, repo: string | null, options?: WatchOptions): WatchResult;
+//# sourceMappingURL=watch.d.ts.map

package/dist/pr-watch/watch.js

@@ -0,0 +1,122 @@
+import { defaultRunGh } from "../pr-merge-readiness/gh.js";
+import { DEFAULT_MAX_WAIT_MINUTES, DEFAULT_POLL_SECONDS, DEFAULT_STALL_THRESHOLD, EXIT_CLEAN, EXIT_NEW_P0_P1, EXIT_TERMINAL_ERROR, VERDICT_CLEAN, VERDICT_CONFIG, VERDICT_ERRORED, VERDICT_NEW_P0_P1, VERDICT_PENDING, VERDICT_STALL, VERDICT_TIMEOUT, } from "./constants.js";
+import { probeOnce } from "./probe.js";
+const systemMonotonicClock = {
+    now() {
+        return performance.now() / 1000;
+    },
+};
+/** Synchronous, non-CPU-spinning sleep (Atomics.wait); injectable in tests. */
+function defaultSleep(seconds) {
+    const ms = Math.max(0, Math.trunc(seconds * 1000));
+    if (ms === 0) {
+        return;
+    }
+    const shared = new Int32Array(new SharedArrayBuffer(4));
+    Atomics.wait(shared, 0, 0, ms);
+}
+function shortSha(sha) {
+    return sha === null ? "<none>" : sha.slice(0, 12);
+}
+/** One-line stderr status mirror per poll (Tier 1 instrumentation shape, #1039). */
+export function formatWatchStatus(poll, maxPolls, probe, elapsedSeconds) {
+    if (probe.error !== null) {
+        return `[pr:watch poll ${poll}/${maxPolls}] CONFIG-ERROR elapsed=${elapsedSeconds}s -- ${probe.error}`;
+    }
+    return (`[pr:watch poll ${poll}/${maxPolls}] head=${shortSha(probe.headSha)} ` +
+        `last_reviewed=${shortSha(probe.lastReviewedSha)} sha_match=${probe.shaMatch} ` +
+        `confidence=${probe.confidence} p0=${probe.p0Count} p1=${probe.p1Count} ` +
+        `errored=${probe.errored} ci_failures=${probe.ciFailures} is_clean=${probe.isClean} ` +
+        `clean_gate_holdout=${probe.cleanGateHoldout} elapsed=${elapsedSeconds}s`);
+}
+/**
+ * Blocking-by-default poll to a terminal three-state verdict (#1056). Default
+ * behaviour is a synchronous wait, so a linear caller (human shell, CI step,
+ * single-process agent) gets the verdict for free; --one-shot degrades to a
+ * single probe. SHA-match gating means a stale review posted BEFORE your push
+ * is never read as the verdict.
+ */
+export function watch(prNumber, repo, options = {}) {
+    const maxWaitMinutes = options.maxWaitMinutes ?? DEFAULT_MAX_WAIT_MINUTES;
+    const pollSeconds = Math.max(1, options.pollSeconds ?? DEFAULT_POLL_SECONDS);
+    const oneShot = options.oneShot ?? false;
+    const stallThreshold = options.stallThreshold ?? DEFAULT_STALL_THRESHOLD;
+    const runGh = options.runGh ?? defaultRunGh;
+    const clockFn = options.clockFn ?? systemMonotonicClock;
+    const sleepFn = options.sleepFn ?? defaultSleep;
+    const probeFn = options.probeFn ?? probeOnce;
+    const capSeconds = Math.max(0, maxWaitMinutes * 60);
+    // Bounded loop (time is still the authority via the cap check below) so no
+    // unbounded `while (true)`; +1 covers the trailing poll after the final wait.
+    const maxPolls = oneShot ? 1 : Math.max(1, Math.ceil(capSeconds / pollSeconds) + 1);
+    const startedAt = clockFn.now();
+    let lastProbe = null;
+    let stallStreak = 0;
+    const build = (verdict, exitCode, probe, poll) => ({
+        verdict,
+        exitCode,
+        prNumber,
+        probe,
+        elapsedSeconds: Math.round(clockFn.now() - startedAt),
+        pollCount: poll,
+    });
+    for (let poll = 1; poll <= maxPolls; poll += 1) {
+        const probe = probeFn(prNumber, repo, runGh);
+        lastProbe = probe;
+        const elapsed = Math.round(clockFn.now() - startedAt);
+        process.stderr.write(`${formatWatchStatus(poll, maxPolls, probe, elapsed)}\n`);
+        if (probe.error !== null) {
+            return build(VERDICT_CONFIG, EXIT_TERMINAL_ERROR, probe, poll);
+        }
+        if (probe.isClean) {
+            return build(VERDICT_CLEAN, EXIT_CLEAN, probe, poll);
+        }
+        // SHA-match gate: blocking findings only count as a verdict when the review
+        // is on the CURRENT HEAD -- a stale pre-push review is not read as NEW_P0_P1.
+        if (probe.hasBlocking && probe.shaMatch) {
+            return build(VERDICT_NEW_P0_P1, EXIT_NEW_P0_P1, probe, poll);
+        }
+        if (probe.errored) {
+            return build(VERDICT_ERRORED, EXIT_TERMINAL_ERROR, probe, poll);
+        }
+        // Stall = a review IS present but stuck on a non-HEAD commit; surface it
+        // rather than burning the whole cap waiting for a re-review that isn't coming.
+        if (probe.found && !probe.shaMatch) {
+            stallStreak += 1;
+        }
+        else {
+            stallStreak = 0;
+        }
+        if (stallStreak >= stallThreshold) {
+            return build(VERDICT_STALL, EXIT_TERMINAL_ERROR, probe, poll);
+        }
+        if (oneShot) {
+            return build(VERDICT_PENDING, EXIT_TERMINAL_ERROR, probe, poll);
+        }
+        const elapsedNow = clockFn.now() - startedAt;
+        if (poll >= maxPolls || elapsedNow + pollSeconds >= capSeconds) {
+            return build(VERDICT_TIMEOUT, EXIT_TERMINAL_ERROR, probe, poll);
+        }
+        sleepFn(pollSeconds);
+    }
+    // Unreachable in practice (the in-loop cap check returns TIMEOUT first); kept
+    // as a total-function fallback so the return type is honoured.
+    const probe = lastProbe ?? {
+        found: false,
+        headSha: null,
+        lastReviewedSha: null,
+        shaMatch: false,
+        confidence: null,
+        p0Count: 0,
+        p1Count: 0,
+        hasBlocking: false,
+        errored: false,
+        ciFailures: 0,
+        terminalCheckRun: false,
+        isClean: false,
+        cleanGateHoldout: null,
+        error: null,
+    };
+    return build(VERDICT_TIMEOUT, EXIT_TERMINAL_ERROR, probe, maxPolls);
+}
+//# sourceMappingURL=watch.js.map