@deftai/directive-core 0.79.2 → 0.79.3

package/dist/check/orchestrator.d.ts

@@ -20,12 +20,16 @@ export interface CheckOrchestratorSeams {
         cwd: string;
         stdio: string;
         env?: NodeJS.ProcessEnv;
+        timeoutMs?: number;
     }) => {
         status: number | null;
+        signal?: NodeJS.Signals | null;
         error?: Error;
     };
     /** Child-process environment (default: process.env). */
     readonly env?: NodeJS.ProcessEnv;
+    /** Wall-clock spawn timeout in milliseconds (default: none). */
+    readonly timeoutMs?: number;
 }
 /**
  * True when `path` is the directive framework source checkout root (not a

package/dist/check/orchestrator.js

@@ -78,11 +78,16 @@ export function dispatchTaskCheck(frameworkRoot, projectRoot, seams = {}) {
         cwd,
         stdio: "inherit",
         env: seams.env,
+        timeoutMs: seams.timeoutMs,
     });
     if (result.error !== undefined) {
         process.stderr.write(`check: failed to invoke task: ${result.error.message}\n`);
         return 2;
     }
+    if (result.signal === "SIGTERM" && result.status === null && seams.timeoutMs !== undefined) {
+        process.stderr.write(`check: timed out after ${seams.timeoutMs / 60_000}m (Step 5 vitest coverage budget; #2652)\n`);
+        return 124;
+    }
     return result.status ?? 1;
 }
 function defaultSpawn(cmd, args, opts) {
@@ -90,7 +95,10 @@ function defaultSpawn(cmd, args, opts) {
         cwd: opts.cwd,
         stdio: opts.stdio,
         env: opts.env ?? process.env,
+        ...(opts.timeoutMs !== undefined
+            ? { timeout: opts.timeoutMs, killSignal: "SIGTERM" }
+            : {}),
     });
-    return { status: result.status, error: result.error };
+    return { status: result.status, signal: result.signal, error: result.error };
 }
 //# sourceMappingURL=orchestrator.js.map

package/dist/platform/resolve-version.d.ts

@@ -1,10 +1,6 @@
+import { isPublishable, NonPublishableVersionError, toPep440 } from "../release/version.js";
 import { DEV_FALLBACK, ENV_VAR } from "./constants.js";
-export { DEV_FALLBACK, ENV_VAR };
-export declare class NonPublishableVersionError extends Error {
-    constructor(message: string);
-}
-export declare function toPep440(version: string): string;
-export declare function isPublishable(version: string): boolean;
+export { DEV_FALLBACK, ENV_VAR, isPublishable, NonPublishableVersionError, toPep440 };
 export declare function tagNameFromRef(ref: string): string;
 export declare function latestPublishableTag(tags: Iterable<string>): string | null;
 export declare function payloadIsOwnGitRoot(payloadDir: string): boolean;

package/dist/platform/resolve-version.js

@@ -2,113 +2,15 @@ import { execFileSync } from "node:child_process";
 import { existsSync, readFileSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
+import { comparePublishableVersions, isPublishable, NonPublishableVersionError, toPep440, } from "../release/version.js";
 import { DEV_FALLBACK, ENV_VAR } from "./constants.js";
-export { DEV_FALLBACK, ENV_VAR };
-export class NonPublishableVersionError extends Error {
-    constructor(message) {
-        super(message);
-        this.name = "NonPublishableVersionError";
-    }
-}
-const PRE_KIND_MAP = {
-    alpha: "a",
-    beta: "b",
-    rc: "rc",
-};
-const NON_PUBLISHABLE_KINDS = new Set(["test"]);
-const PRERELEASE_RANK = {
-    alpha: 0,
-    beta: 1,
-    rc: 2,
-    "": 3,
-};
+export { DEV_FALLBACK, ENV_VAR, isPublishable, NonPublishableVersionError, toPep440 };
 function frameworkRoot() {
     const envRoot = process.env.DEFT_ROOT?.trim();
     if (envRoot)
         return resolve(envRoot);
     return resolve(dirname(fileURLToPath(import.meta.url)), "..", "..", "..", "..");
 }
-/** Parse `[v]X.Y.Z[-(rc|alpha|beta|test).N]` via linear scan. */
-function parsePep440Tag(version) {
-    let i = 0;
-    if (version[i] === "v" || version[i] === "V")
-        i += 1;
-    const readInt = () => {
-        const ch = version[i] ?? "";
-        if (i >= version.length || ch < "0" || ch > "9")
-            return null;
-        let n = 0;
-        while (i < version.length) {
-            const digit = version[i] ?? "";
-            if (digit < "0" || digit > "9")
-                break;
-            n = n * 10 + Number(digit);
-            i += 1;
-        }
-        return n;
-    };
-    const major = readInt();
-    if (major === null || version[i] !== ".")
-        return null;
-    i += 1;
-    const minor = readInt();
-    if (minor === null || version[i] !== ".")
-        return null;
-    i += 1;
-    const patch = readInt();
-    if (patch === null)
-        return null;
-    if (i >= version.length)
-        return { major, minor, patch, kind: null, num: null };
-    if (version[i] !== "-")
-        return null;
-    i += 1;
-    const kindStart = i;
-    while (i < version.length && version[i] !== ".")
-        i += 1;
-    if (i >= version.length || version[i] !== ".")
-        return null;
-    const kind = version.slice(kindStart, i);
-    if (!["rc", "alpha", "beta", "test"].includes(kind))
-        return null;
-    i += 1;
-    const num = readInt();
-    if (num === null || i !== version.length)
-        return null;
-    return { major, minor, patch, kind, num };
-}
-export function toPep440(version) {
-    if (typeof version !== "string") {
-        throw new Error(`version must be a string, got ${typeof version}`);
-    }
-    const candidate = version.trim();
-    if (!candidate)
-        throw new Error("version must be a non-empty string");
-    const parsed = parsePep440Tag(candidate);
-    if (parsed === null) {
-        throw new Error(`Cannot normalize ${JSON.stringify(candidate)} to PEP 440: expected [v]X.Y.Z or [v]X.Y.Z-(rc|alpha|beta|test).N`);
-    }
-    const base = `${parsed.major}.${parsed.minor}.${parsed.patch}`;
-    if (parsed.kind === null)
-        return base;
-    if (NON_PUBLISHABLE_KINDS.has(parsed.kind)) {
-        throw new NonPublishableVersionError(`Version ${JSON.stringify(candidate)} carries non-publishable pre-release tag ${JSON.stringify(parsed.kind)}.${parsed.num} -- release pipeline MUST skip pyproject.toml [project].version sync for this tag.`);
-    }
-    const pepKind = PRE_KIND_MAP[parsed.kind];
-    if (pepKind === undefined) {
-        throw new Error(`Unmapped pre-release kind ${JSON.stringify(parsed.kind)} for version ${JSON.stringify(candidate)}; add it to PRE_KIND_MAP or NON_PUBLISHABLE_KINDS to keep parser in lockstep with the publishability classifier.`);
-    }
-    return `${base}${pepKind}${parsed.num}`;
-}
-export function isPublishable(version) {
-    try {
-        toPep440(version);
-        return true;
-    }
-    catch {
-        return false;
-    }
-}
 export function tagNameFromRef(ref) {
     let candidate = ref.trim();
     if (!candidate)
@@ -123,49 +25,21 @@ export function tagNameFromRef(ref) {
         candidate = candidate.slice(prefix.length);
     return candidate.trim();
 }
-function publishableTagSortKey(version) {
-    const candidate = version.trim();
-    const parsed = parsePep440Tag(candidate);
-    if (parsed === null) {
-        throw new Error(`Cannot sort ${JSON.stringify(candidate)}: expected [v]X.Y.Z or [v]X.Y.Z-(rc|alpha|beta).N`);
-    }
-    if (parsed.kind !== null && NON_PUBLISHABLE_KINDS.has(parsed.kind)) {
-        throw new NonPublishableVersionError(`Version ${JSON.stringify(candidate)} carries non-publishable pre-release tag ${JSON.stringify(parsed.kind)}.`);
-    }
-    const kind = parsed.kind ?? "";
-    const prereleaseRank = PRERELEASE_RANK[kind];
-    if (prereleaseRank === undefined) {
-        throw new Error(`Unmapped pre-release kind ${JSON.stringify(parsed.kind)} for ${JSON.stringify(candidate)}`);
-    }
-    return [parsed.major, parsed.minor, parsed.patch, prereleaseRank, parsed.num ?? 0];
-}
 export function latestPublishableTag(tags) {
     let bestTag = null;
-    let bestKey = null;
     for (const raw of tags) {
         const tag = tagNameFromRef(raw);
         if (!tag || !isPublishable(tag))
             continue;
         try {
-            const key = publishableTagSortKey(tag);
-            if (bestKey === null || compareTuple(key, bestKey) > 0) {
+            if (bestTag === null || comparePublishableVersions(tag, bestTag) > 0) {
                 bestTag = tag;
-                bestKey = key;
             }
         }
         catch { }
     }
     return bestTag;
 }
-function compareTuple(a, b) {
-    for (let i = 0; i < a.length; i += 1) {
-        const av = a[i] ?? 0;
-        const bv = b[i] ?? 0;
-        if (av !== bv)
-            return av > bv ? 1 : -1;
-    }
-    return 0;
-}
 function readManifestTag(baseDir) {
     const manifest = join(baseDir, "VERSION");
     try {

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

@@ -66,7 +66,10 @@ export function fetchGreptileCommentBody(prNumber, repo, runGh) {
         `repos/${resolvedRepo}/issues/${prNumber}/comments`,
         "--paginate",
         "--jq",
-        `[.[] | select(.user.login == "${GREPTILE_LOGIN}")] | last | .body // ""`,
+        // Prefer most recently *updated* Greptile summary. Greptile edits the
+        // primary rolling summary in place; a later-created duplicate can stay
+        // SHA-stale and must not win over the refreshed primary (#1056 / #2658).
+        `[.[] | select(.user.login == "${GREPTILE_LOGIN}")] | sort_by(.updated_at) | last | .body // ""`,
     ];
     const { returncode, stdout, stderr } = runGh(cmd);
     if (returncode !== 0) {
@@ -123,7 +126,8 @@ function parsePaginatedComments(text) {
         }
         idx = end;
     }
-    const greptileBodies = [];
+    let bestBody = "";
+    let bestUpdatedAt = "";
     for (const c of comments) {
         if (c !== null &&
             typeof c === "object" &&
@@ -136,13 +140,17 @@ function parsePaginatedComments(text) {
             c.user.login === GREPTILE_LOGIN &&
             "body" in c &&
             typeof c.body === "string") {
-            greptileBodies.push(c.body);
+            const updatedAt = "updated_at" in c && typeof c.updated_at === "string" ? c.updated_at : "";
+            if (updatedAt >= bestUpdatedAt) {
+                bestUpdatedAt = updatedAt;
+                bestBody = c.body;
+            }
         }
     }
-    if (greptileBodies.length === 0) {
+    if (bestBody.length === 0 && bestUpdatedAt.length === 0) {
         return { body: "", error: "" };
     }
-    return { body: greptileBodies[greptileBodies.length - 1] ?? "", error: "" };
+    return { body: bestBody, error: "" };
 }
 /** Mirrors Python json.JSONDecoder.raw_decode for concatenated paginate arrays. */
 class PaginatedJsonDecoder {

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,