@deftai/directive-core 0.79.1 → 0.79.3

package/dist/pr-merge-readiness/greptile-inline.js

@@ -0,0 +1,239 @@
+import { detect } from "../content-contracts/skills/greptile-detector.js";
+import { GREPTILE_LOGIN } from "./constants.js";
+const REVIEW_THREADS_QUERY = `
+query($owner: String!, $repo: String!, $pr: Int!, $after: String) {
+  repository(owner: $owner, name: $repo) {
+    pullRequest(number: $pr) {
+      reviewThreads(first: 100, after: $after) {
+        pageInfo { hasNextPage endCursor }
+        nodes {
+          isResolved
+          isOutdated
+          comments(first: 50) {
+            nodes {
+              author { login }
+              body
+              path
+              commit { oid }
+            }
+          }
+        }
+      }
+    }
+  }
+}`;
+const EMPTY_INLINE = {
+    p0Count: 0,
+    p1Count: 0,
+    unresolvedThreadCount: 0,
+    error: null,
+};
+/** True when a review comment commit SHA matches the current PR head (#2620 AC-2). */
+export function headShaMatches(commentSha, headSha) {
+    return headSha.startsWith(commentSha) || commentSha.startsWith(headSha);
+}
+export function inlineFindingsToDict(findings) {
+    return {
+        p0_count: findings.p0Count,
+        p1_count: findings.p1Count,
+        unresolved_thread_count: findings.unresolvedThreadCount,
+        error: findings.error,
+    };
+}
+function parseOwnerRepo(ownerRepo) {
+    const slash = ownerRepo.indexOf("/");
+    if (slash <= 0 || slash >= ownerRepo.length - 1) {
+        return null;
+    }
+    return { owner: ownerRepo.slice(0, slash), repo: ownerRepo.slice(slash + 1) };
+}
+function asRecord(value) {
+    if (value === null || typeof value !== "object" || Array.isArray(value)) {
+        return null;
+    }
+    return value;
+}
+function parseReviewComment(node) {
+    const record = asRecord(node);
+    if (record === null) {
+        return null;
+    }
+    const author = asRecord(record.author);
+    const login = author?.login;
+    if (typeof login !== "string" || login.length === 0) {
+        return null;
+    }
+    const body = record.body;
+    if (typeof body !== "string") {
+        return null;
+    }
+    const commit = asRecord(record.commit);
+    const oid = commit?.oid;
+    const path = record.path;
+    return {
+        authorLogin: login,
+        body,
+        path: typeof path === "string" ? path : null,
+        commitOid: typeof oid === "string" && oid.length > 0 ? oid : null,
+    };
+}
+function parseReviewThread(node) {
+    const record = asRecord(node);
+    if (record === null) {
+        return null;
+    }
+    const commentsBlock = asRecord(record.comments);
+    const commentNodes = commentsBlock?.nodes;
+    const comments = [];
+    if (Array.isArray(commentNodes)) {
+        for (const commentNode of commentNodes) {
+            const parsed = parseReviewComment(commentNode);
+            if (parsed !== null) {
+                comments.push(parsed);
+            }
+        }
+    }
+    return {
+        isResolved: record.isResolved === true,
+        isOutdated: record.isOutdated === true,
+        comments,
+    };
+}
+function parseGraphqlReviewThreadsPage(stdout) {
+    if (!stdout.trim()) {
+        return { threads: [], hasNextPage: false, endCursor: null, error: "empty GraphQL body" };
+    }
+    let payload;
+    try {
+        payload = JSON.parse(stdout);
+    }
+    catch (exc) {
+        const message = exc instanceof Error ? exc.message : String(exc);
+        return {
+            threads: [],
+            hasNextPage: false,
+            endCursor: null,
+            error: `could not parse GraphQL JSON: ${message}`,
+        };
+    }
+    const root = asRecord(payload);
+    const errors = root?.errors;
+    if (Array.isArray(errors) && errors.length > 0) {
+        const first = errors[0];
+        const message = typeof first === "object" && first !== null && "message" in first
+            ? String(first.message)
+            : "GraphQL errors present";
+        return { threads: [], hasNextPage: false, endCursor: null, error: message };
+    }
+    const data = asRecord(root?.data);
+    const repository = asRecord(data?.repository);
+    const pullRequest = asRecord(repository?.pullRequest);
+    const reviewThreads = asRecord(pullRequest?.reviewThreads);
+    const nodes = reviewThreads?.nodes;
+    const pageInfo = asRecord(reviewThreads?.pageInfo);
+    const threads = [];
+    if (Array.isArray(nodes)) {
+        for (const node of nodes) {
+            const parsed = parseReviewThread(node);
+            if (parsed !== null) {
+                threads.push(parsed);
+            }
+        }
+    }
+    return {
+        threads,
+        hasNextPage: pageInfo?.hasNextPage === true,
+        endCursor: typeof pageInfo?.endCursor === "string" ? pageInfo.endCursor : null,
+        error: null,
+    };
+}
+/** Score unresolved Greptile inline P0/P1 threads pinned to the current HEAD (#2620). */
+export function evaluateInlineReviewThreads(threads, headSha) {
+    let p0Count = 0;
+    let p1Count = 0;
+    let unresolvedThreadCount = 0;
+    for (const thread of threads) {
+        if (thread.isResolved || thread.isOutdated) {
+            continue;
+        }
+        let threadP0 = 0;
+        let threadP1 = 0;
+        for (const comment of thread.comments) {
+            if (comment.authorLogin !== GREPTILE_LOGIN) {
+                continue;
+            }
+            if (comment.commitOid === null || !headShaMatches(comment.commitOid, headSha)) {
+                continue;
+            }
+            const findings = detect(comment.body);
+            threadP0 += findings.p0_count;
+            threadP1 += findings.p1_count;
+        }
+        if (threadP0 + threadP1 > 0) {
+            p0Count += threadP0;
+            p1Count += threadP1;
+            unresolvedThreadCount += 1;
+        }
+    }
+    return { p0Count, p1Count, unresolvedThreadCount, error: null };
+}
+/** Fetch unresolved Greptile inline P0/P1 on the current HEAD via reviewThreads GraphQL (#2620). */
+export function fetchUnresolvedGreptileInlineFindings(prNumber, repo, headSha, runGh) {
+    const parsed = parseOwnerRepo(repo);
+    if (parsed === null) {
+        return { ...EMPTY_INLINE, error: `invalid repo: ${repo}` };
+    }
+    const allThreads = [];
+    let after = null;
+    const maxPages = 10;
+    let hasNextPage = true;
+    for (let page = 0; hasNextPage && page < maxPages; page += 1) {
+        const cmd = [
+            "gh",
+            "api",
+            "graphql",
+            "-f",
+            `query=${REVIEW_THREADS_QUERY}`,
+            "-f",
+            `owner=${parsed.owner}`,
+            "-f",
+            `repo=${parsed.repo}`,
+            "-F",
+            `pr=${String(prNumber)}`,
+        ];
+        if (after !== null) {
+            cmd.push("-f", `after=${after}`);
+        }
+        const rc = runGh(cmd);
+        if (rc.returncode !== 0) {
+            return {
+                ...EMPTY_INLINE,
+                error: `graphql reviewThreads failed: ${rc.stderr.trim() || rc.stdout.trim()}`,
+            };
+        }
+        const pageResult = parseGraphqlReviewThreadsPage(rc.stdout);
+        if (pageResult.error !== null) {
+            return { ...EMPTY_INLINE, error: pageResult.error };
+        }
+        allThreads.push(...pageResult.threads);
+        hasNextPage = pageResult.hasNextPage;
+        if (!hasNextPage) {
+            break;
+        }
+        if (pageResult.endCursor === null) {
+            return {
+                ...EMPTY_INLINE,
+                error: "graphql reviewThreads pagination missing endCursor while hasNextPage=true",
+            };
+        }
+        after = pageResult.endCursor;
+    }
+    if (hasNextPage) {
+        return {
+            ...EMPTY_INLINE,
+            error: `graphql reviewThreads pagination exceeded ${maxPages} pages`,
+        };
+    }
+    return evaluateInlineReviewThreads(allThreads, headSha);
+}
+//# sourceMappingURL=greptile-inline.js.map

package/dist/pr-merge-readiness/index.d.ts

@@ -3,6 +3,7 @@ export { type ComputeGateOptions, computeGateResult, type FetchMergeabilityFn }
 export * from "./constants.js";
 export { evaluateGates, isMergeReady } from "./evaluate.js";
 export { defaultRunGh } from "./gh.js";
+export { evaluateInlineReviewThreads, fetchUnresolvedGreptileInlineFindings, headShaMatches, type InlineGreptileFindings, type InlineReviewComment, type InlineReviewThread, inlineFindingsToDict, } from "./greptile-inline.js";
 export { cmdPrMergeReadiness, parseArgs, run } from "./main.js";
 export { fetchMergeability, isGithubMergeableClean, MERGE_STATE_CLEAN, type MergeabilitySignal, mergeabilityToDict, verdictBlockIsSoftOnly, verdictShaIsStale, } from "./mergeability.js";
 export { emitJson, exitCodeFor, gateResultToDict, printHuman } from "./output.js";

package/dist/pr-merge-readiness/index.js

@@ -3,6 +3,7 @@ export { computeGateResult } from "./compute.js";
 export * from "./constants.js";
 export { evaluateGates, isMergeReady } from "./evaluate.js";
 export { defaultRunGh } from "./gh.js";
+export { evaluateInlineReviewThreads, fetchUnresolvedGreptileInlineFindings, headShaMatches, inlineFindingsToDict, } from "./greptile-inline.js";
 export { cmdPrMergeReadiness, parseArgs, run } from "./main.js";
 export { fetchMergeability, isGithubMergeableClean, MERGE_STATE_CLEAN, mergeabilityToDict, verdictBlockIsSoftOnly, verdictShaIsStale, } from "./mergeability.js";
 export { emitJson, exitCodeFor, gateResultToDict, printHuman } from "./output.js";

package/dist/pr-merge-readiness/mergeability.d.ts

@@ -1,3 +1,4 @@
+import type { InlineGreptileFindings } from "./greptile-inline.js";
 import type { GreptileVerdict, RunGhFn } from "./types.js";
 /**
  * GitHub's authoritative mergeability signal, read over REST (#2260).
@@ -41,5 +42,5 @@ export declare function verdictShaIsStale(verdict: GreptileVerdict, headSha: str
  * regardless of GitHub mergeability (guardrail: do not merge a PR with a real
  * P0/P1 review finding).
  */
-export declare function verdictBlockIsSoftOnly(verdict: GreptileVerdict, headSha: string | null): boolean;
+export declare function verdictBlockIsSoftOnly(verdict: GreptileVerdict, headSha: string | null, inline?: InlineGreptileFindings | null): boolean;
 //# sourceMappingURL=mergeability.d.ts.map

package/dist/pr-merge-readiness/mergeability.js

@@ -75,7 +75,13 @@ export function verdictShaIsStale(verdict, headSha) {
  * regardless of GitHub mergeability (guardrail: do not merge a PR with a real
  * P0/P1 review finding).
  */
-export function verdictBlockIsSoftOnly(verdict, headSha) {
+export function verdictBlockIsSoftOnly(verdict, headSha, inline = null) {
+    if (inline !== null && inline.error !== null) {
+        return false;
+    }
+    if (inline !== null && inline.error === null && (inline.p0Count > 0 || inline.p1Count > 0)) {
+        return false;
+    }
     // Absent: no Greptile rolling-summary comment at all.
     if (!verdict.found) {
         return true;

package/dist/pr-merge-readiness/test-gh-fixtures.helpers.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Test-only gh doubles for pr-monitor / merge-readiness suites (#2652).
+ * Not part of the production CLI surface; excluded from coverage via `*.helpers.ts`.
+ */
+import type { RunGhFn } from "./types.js";
+/** Empty GraphQL reviewThreads page for inline Greptile findings (#2620 / #2652). */
+export declare const EMPTY_REVIEW_THREADS_GRAPHQL: string;
+/** Prepend a graphql reviewThreads stub to any hermetic runGh test double. */
+export declare function withGraphqlInlineStub(runGh: RunGhFn): RunGhFn;
+export interface FakeRunGhOptions {
+    readonly headSha?: string;
+    readonly headOk?: boolean;
+    readonly commentsBody?: string;
+    readonly commentsOk?: boolean;
+}
+/** Hermetic runGh stub for monitor / merge-readiness unit tests (#2260 / #2652). */
+export declare function fakeRunGhForMonitor(options?: FakeRunGhOptions): RunGhFn;
+//# sourceMappingURL=test-gh-fixtures.helpers.d.ts.map

package/dist/pr-merge-readiness/test-gh-fixtures.helpers.js

@@ -0,0 +1,76 @@
+/** Empty GraphQL reviewThreads page for inline Greptile findings (#2620 / #2652). */
+export const EMPTY_REVIEW_THREADS_GRAPHQL = JSON.stringify({
+    data: {
+        repository: {
+            pullRequest: {
+                reviewThreads: {
+                    pageInfo: { hasNextPage: false, endCursor: null },
+                    nodes: [],
+                },
+            },
+        },
+    },
+});
+/** Prepend a graphql reviewThreads stub to any hermetic runGh test double. */
+export function withGraphqlInlineStub(runGh) {
+    return (cmd) => {
+        if (cmd.join(" ").includes("graphql")) {
+            return { returncode: 0, stdout: EMPTY_REVIEW_THREADS_GRAPHQL, stderr: "" };
+        }
+        return runGh(cmd);
+    };
+}
+/** Hermetic runGh stub for monitor / merge-readiness unit tests (#2260 / #2652). */
+export function fakeRunGhForMonitor(options = {}) {
+    const headSha = options.headSha ?? "abc1234567890def1234567890abcdef12345678";
+    const headOk = options.headOk ?? true;
+    const commentsOk = options.commentsOk ?? true;
+    const commentsBody = options.commentsBody ?? "";
+    return (cmd) => {
+        if (!headOk) {
+            return { returncode: 1, stdout: "", stderr: "all-down" };
+        }
+        const joined = cmd.join(" ");
+        if (joined.includes("graphql")) {
+            return { returncode: 0, stdout: EMPTY_REVIEW_THREADS_GRAPHQL, stderr: "" };
+        }
+        if (joined.includes("headRefOid")) {
+            return { returncode: 0, stdout: `${headSha}\n`, stderr: "" };
+        }
+        if (joined.includes("/comments")) {
+            return commentsOk
+                ? { returncode: 0, stdout: commentsBody, stderr: "" }
+                : { returncode: 1, stdout: "", stderr: "boom" };
+        }
+        if (joined.includes("/check-runs")) {
+            return {
+                returncode: 0,
+                stdout: JSON.stringify({
+                    check_runs: [
+                        {
+                            name: "TypeScript (build + lint + test)",
+                            status: "completed",
+                            conclusion: "success",
+                        },
+                    ],
+                }),
+                stderr: "",
+            };
+        }
+        if (joined.includes("/pulls/")) {
+            return {
+                returncode: 0,
+                stdout: JSON.stringify({
+                    state: "open",
+                    merged: false,
+                    mergeable: true,
+                    mergeable_state: "clean",
+                    head: { sha: headSha },
+                }),
+                stderr: "",
+            };
+        }
+        return { returncode: 1, stdout: "", stderr: `unexpected: ${joined}` };
+    };
+}
+//# sourceMappingURL=test-gh-fixtures.helpers.js.map

package/dist/pr-monitor/monitor.js

@@ -1,4 +1,4 @@
-import { cadenceIntervalAfterPoll } from "./cadence.js";
+import { cadenceIntervalAfterPoll, cadenceIntervals } from "./cadence.js";
 import { DEFAULT_CADENCE, EXIT_CAP_REACHED, EXIT_CLEAN, EXIT_CONFIG_ERROR, EXIT_PR_TERMINAL, } from "./constants.js";
 import { callReadiness } from "./readiness.js";
 const systemMonotonicClock = {
@@ -127,12 +127,21 @@ export function monitor(prNumber, repo, options = {}) {
     const sleepFn = options.sleepFn ?? defaultSleep;
     const callReadinessFn = options.callReadinessFn ?? ((n, r) => callReadiness(n, r, { runGh: options.runGh }));
     const startedAt = clockFn.now();
+    const intervalSchedule = cadenceIntervals(cadence);
+    const minCadenceSec = intervalSchedule.length > 0
+        ? Math.min(...intervalSchedule)
+        : cadenceIntervalAfterPoll(1, cadence);
+    // Fail closed when an injected clock never advances (infinite poll loop; #2652).
+    const maxPolls = Math.min(10_000, Math.ceil(capSeconds / Math.max(minCadenceSec, 1)) + intervalSchedule.length + 2);
     let pollIndex = 0;
     let lastPayload = {};
     let lastExit = EXIT_CAP_REACHED;
     let priorCadenceSeconds = cadenceIntervalAfterPoll(1, cadence);
     while (true) {
         pollIndex += 1;
+        if (pollIndex > maxPolls) {
+            return { exitCode: EXIT_CAP_REACHED, payload: lastPayload, pollCount: pollIndex - 1 };
+        }
         const elapsed = clockFn.now() - startedAt;
         if (elapsed > capSeconds) {
             return { exitCode: EXIT_CAP_REACHED, payload: lastPayload, pollCount: pollIndex - 1 };

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

@@ -23,6 +23,11 @@ export declare const VERDICT_PENDING = "PENDING";
 export declare const VERDICT_CONFIG = "CONFIG";
 export declare const DEFAULT_MAX_WAIT_MINUTES = 30;
 export declare const DEFAULT_POLL_SECONDS = 90;
+/**
+ * Usage for `task pr:watch -- --help` / `-h` (#2652 / #1056).
+ * Canonical surface is the Task verb; engine stem is `pr-watch`.
+ */
+export declare const WATCH_HELP: string;
 /**
  * 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

package/dist/pr-watch/constants.js

@@ -23,6 +23,33 @@ export const VERDICT_PENDING = "PENDING";
 export const VERDICT_CONFIG = "CONFIG";
 export const DEFAULT_MAX_WAIT_MINUTES = 30;
 export const DEFAULT_POLL_SECONDS = 90;
+/**
+ * Usage for `task pr:watch -- --help` / `-h` (#2652 / #1056).
+ * Canonical surface is the Task verb; engine stem is `pr-watch`.
+ */
+export const WATCH_HELP = "usage: task pr:watch -- <pr_number> [options]\n" +
+    "\n" +
+    "Blocking poll of a PR Greptile/SLizard review to a terminal three-state\n" +
+    "verdict (#1056). The invocation IS the wait — an orchestrator that promises\n" +
+    "to poll cannot silently forget. Canonical: `task pr:watch -- <N>`.\n" +
+    "Engine / CLI stem: `pr-watch` (also `directive pr watch` / `directive pr:watch`).\n" +
+    "\n" +
+    "positional arguments:\n" +
+    "  pr_number             GitHub pull request number (required unless --help)\n" +
+    "\n" +
+    "options:\n" +
+    "  -h, --help            Show this help and exit 0\n" +
+    "  --one-shot            Single probe (PENDING with no terminal verdict → exit 2)\n" +
+    "  --json                Emit the AC-4 JSON shape on stdout\n" +
+    "  --max-wait-minutes N  Cap for the blocking poll (default: 30)\n" +
+    "  --poll-seconds N      Seconds between probes (default: 90)\n" +
+    "  --repo OWNER/REPO     Override repository (default: GH_REPO / origin)\n" +
+    "  --project-root PATH   Chdir before probing (optional)\n" +
+    "\n" +
+    "exit codes:\n" +
+    "  0  CLEAN       SHA-matched review, confidence > 3, no P0/P1, CI green\n" +
+    "  1  NEW_P0_P1   Blocking findings on the current (SHA-matched) review\n" +
+    "  2  ERRORED | STALL | TIMEOUT | config / usage error\n";
 /**
  * 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

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

@@ -1,5 +1,5 @@
 export * from "./constants.js";
-export { cmdPrWatch, emitWatchJson, type ParsedWatchArgs, parseWatchArgs, printWatchHuman, type RunWatchOptions, runWatch, watchResultToJson, } from "./main.js";
+export { cmdPrWatch, emitWatchJson, formatWatchHelp, 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";

package/dist/pr-watch/index.js

@@ -1,5 +1,5 @@
 export * from "./constants.js";
-export { cmdPrWatch, emitWatchJson, parseWatchArgs, printWatchHuman, runWatch, watchResultToJson, } from "./main.js";
+export { cmdPrWatch, emitWatchJson, formatWatchHelp, parseWatchArgs, printWatchHuman, runWatch, watchResultToJson, } from "./main.js";
 export { probeOnce } from "./probe.js";
 export * from "./types.js";
 export { formatWatchStatus, watch } from "./watch.js";

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

@@ -7,9 +7,12 @@ export interface ParsedWatchArgs {
     readonly oneShot: boolean;
     readonly emitJson: boolean;
     readonly projectRoot: string | null;
+    readonly help: boolean;
     readonly error?: string;
 }
 export declare function parseWatchArgs(argv: readonly string[]): ParsedWatchArgs;
+/** Canonical help text for `task pr:watch -- --help` (#2652). */
+export declare function formatWatchHelp(): string;
 /** 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;

package/dist/pr-watch/main.js

@@ -1,7 +1,7 @@
 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 { DEFAULT_MAX_WAIT_MINUTES, DEFAULT_POLL_SECONDS, EXIT_CLEAN, EXIT_TERMINAL_ERROR, WATCH_HELP, } from "./constants.js";
 import { watch } from "./watch.js";
 function fail(base, error) {
     return { ...base, error };
@@ -15,6 +15,7 @@ export function parseWatchArgs(argv) {
         oneShot: false,
         emitJson: false,
         projectRoot: null,
+        help: false,
     };
     let prNumber = null;
     let repo = null;
@@ -23,6 +24,7 @@ export function parseWatchArgs(argv) {
     let oneShot = false;
     let emitJson = false;
     let projectRoot = null;
+    let help = false;
     const takePositive = (label, raw) => {
         if (raw === undefined) {
             return { error: `argument ${label}: expected one argument` };
@@ -35,7 +37,10 @@ export function parseWatchArgs(argv) {
     };
     for (let i = 0; i < argv.length; i += 1) {
         const arg = argv[i];
-        if (arg === "--json") {
+        if (arg === "--help" || arg === "-h") {
+            help = true;
+        }
+        else if (arg === "--json") {
             emitJson = true;
         }
         else if (arg === "--one-shot") {
@@ -103,10 +108,26 @@ export function parseWatchArgs(argv) {
             return fail(acc, `unrecognized arguments: ${arg}`);
         }
     }
+    if (help) {
+        return { prNumber, repo, maxWaitMinutes, pollSeconds, oneShot, emitJson, projectRoot, help };
+    }
     if (prNumber === null) {
         return fail(acc, "the following arguments are required: pr_number");
     }
-    return { prNumber, repo, maxWaitMinutes, pollSeconds, oneShot, emitJson, projectRoot };
+    return {
+        prNumber,
+        repo,
+        maxWaitMinutes,
+        pollSeconds,
+        oneShot,
+        emitJson,
+        projectRoot,
+        help,
+    };
+}
+/** Canonical help text for `task pr:watch -- --help` (#2652). */
+export function formatWatchHelp() {
+    return WATCH_HELP;
 }
 /** Match Python json.dumps(..., indent=2) default ensure_ascii=True. */
 function pythonJsonDumps(value) {
@@ -161,8 +182,13 @@ export function printWatchHuman(result) {
 }
 export function runWatch(argv, options = {}) {
     const args = parseWatchArgs(argv);
+    if (args.help) {
+        process.stdout.write(formatWatchHelp());
+        return EXIT_CLEAN;
+    }
     if (args.error !== undefined) {
         process.stderr.write(`pr_watch: ${args.error}\n`);
+        process.stderr.write(`Try: task pr:watch -- --help\n`);
         return EXIT_TERMINAL_ERROR;
     }
     let restoreCwd = null;

package/dist/release/constants.d.ts

@@ -20,6 +20,11 @@ export declare const DESTRUCTIVE_GH_GATE_BYPASS_ENV = "DEFT_ALLOW_DESTRUCTIVE_GH
 export declare const RELEASE_PREFLIGHT_ENV = "DEFT_RELEASE_PREFLIGHT";
 /** Set only by release Step-5 preflight when --allow-coverage-debt=#N is supplied (#2573). */
 export declare const COVERAGE_DEBT_ENV = "DEFT_ALLOW_COVERAGE_DEBT";
+/** Hard wall-clock cap for release Step 5 `task check` / vitest coverage (#2652). */
+export declare const RELEASE_CHECK_TIMEOUT_MS: number;
+export declare const RELEASE_CHECK_TIMEOUT_MINUTES = 20;
+/** Vitest coverage step cap in GHA CI (mirrors release Step 5 budget, #2652). */
+export declare const CI_VITEST_COVERAGE_TIMEOUT_MINUTES = 20;
 export declare const PYPROJECT_VERSION_LINE_RE: RegExp;
 /** Byte-identical argparse --help from scripts/release.py (Python 3.12). */
 export declare const RELEASE_HELP: string;

package/dist/release/constants.js

@@ -28,10 +28,16 @@ export const DESTRUCTIVE_GH_GATE_BYPASS_ENV = "DEFT_ALLOW_DESTRUCTIVE_GH_VERBS";
 export const RELEASE_PREFLIGHT_ENV = "DEFT_RELEASE_PREFLIGHT";
 /** Set only by release Step-5 preflight when --allow-coverage-debt=#N is supplied (#2573). */
 export const COVERAGE_DEBT_ENV = "DEFT_ALLOW_COVERAGE_DEBT";
+/** Hard wall-clock cap for release Step 5 `task check` / vitest coverage (#2652). */
+export const RELEASE_CHECK_TIMEOUT_MS = 20 * 60 * 1000;
+export const RELEASE_CHECK_TIMEOUT_MINUTES = 20;
+/** Vitest coverage step cap in GHA CI (mirrors release Step 5 budget, #2652). */
+export const CI_VITEST_COVERAGE_TIMEOUT_MINUTES = 20;
 export const PYPROJECT_VERSION_LINE_RE = /version\s*=\s*"[^"]*"/;
 /** Byte-identical argparse --help from scripts/release.py (Python 3.12). */
 export const RELEASE_HELP = "usage: release [-h] [--dry-run] [--skip-tag] [--skip-release] [--allow-dirty]\n" +
     "               [--allow-vbrief-drift] [--allow-coverage-debt #N]\n" +
+    "               [--allow-skip-ci #N]\n" +
     "               [--skip-ci] [--skip-build] [--no-draft]\n" +
     "               [--repo OWNER/REPO] [--base-branch BRANCH]\n" +
     "               [--project-root PATH] [--summary TEXT]\n" +
@@ -66,11 +72,17 @@ export const RELEASE_HELP = "usage: release [-h] [--dry-run] [--skip-tag] [--ski
     "                        flag cites an operator-owned issue number (#2573).\n" +
     "                        PowerShell: use --allow-coverage-debt=N (no bare #)\n" +
     '                        or quote "#N"; unquoted # starts a comment (#2621).\n' +
-    "  --skip-ci             Skip Step 3 (task ci:local / task check fallback).\n" +
+    "  --skip-ci             Skip Step 5 (task ci:local / task check fallback).\n" +
     "                        Used by `task release:e2e` to keep wall-clock\n" +
     "                        manageable inside the auto-created temp repo (CI\n" +
     "                        semantics are covered by the unit-test suite, not the\n" +
-    "                        e2e rehearsal).\n" +
+    "                        e2e rehearsal). Production cuts MUST pass\n" +
+    "                        --allow-skip-ci=#N citing the tracked incident (#2652);\n" +
+    "                        otherwise Step 5 runs with a hard timeout.\n" +
+    "  --allow-skip-ci #N    Acknowledge skipping Step 5 on a production cut (#2652).\n" +
+    "                        Emits a loud WARN — npm ships without vitest coverage.\n" +
+    "                        PowerShell: use --allow-skip-ci=N (no bare #) or quote\n" +
+    '                        "#N"; unquoted # starts a comment (#2621).\n' +
     "  --skip-build          Skip Step 6 (task build). Used by `task release:e2e`\n" +
     "                        to keep wall-clock manageable; build artefacts are not\n" +
     "                        needed for the draft-release verification step.\n" +

package/dist/release/flags.js

@@ -1,5 +1,6 @@
 import { parseCoverageDebtIssueNumber } from "../vitest-runner/coverage-debt.js";
 import { DEFAULT_BASE_BRANCH, RELEASE_HELP } from "./constants.js";
+import { parseSkipCiIncidentArgv } from "./skip-ci-incident.js";
 export function parseReleaseFlags(args) {
     let help = false;
     let dryRun = false;
@@ -8,6 +9,8 @@ export function parseReleaseFlags(args) {
     let allowDirty = false;
     let allowVbriefDrift = false;
     let allowCoverageDebtIssue = null;
+    const skipCiIncident = parseSkipCiIncidentArgv(args);
+    const allowSkipCiIssue = skipCiIncident.kind === "valid" ? skipCiIncident.issue : null;
     let skipCi = false;
     let skipBuild = false;
     let draft = true;
@@ -71,6 +74,15 @@ export function parseReleaseFlags(args) {
         else if (token === "--skip-ci") {
             skipCi = true;
         }
+        else if (token === "--allow-skip-ci") {
+            // Value consumed by parseSkipCiIncidentArgv above; advance past it here.
+            const value = takeValue(token, i);
+            if (value !== null)
+                i += 1;
+        }
+        else if (token.startsWith("--allow-skip-ci=")) {
+            // Value consumed by parseSkipCiIncidentArgv above.
+        }
         else if (token === "--skip-build") {
             skipBuild = true;
         }
@@ -132,6 +144,9 @@ export function parseReleaseFlags(args) {
         }
         i += 1;
     }
+    if (skipCiIncident.kind === "invalid") {
+        unknown.push(`--allow-skip-ci (${skipCiIncident.reason})`);
+    }
     return {
         help,
         version,
@@ -144,6 +159,7 @@ export function parseReleaseFlags(args) {
         allowDirty,
         allowVbriefDrift,
         allowCoverageDebtIssue,
+        allowSkipCiIssue,
         skipCi,
         skipBuild,
         draft,