@deftai/directive-core 0.79.2 → 0.79.4

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-wait-mergeable/cascade.js

@@ -2,6 +2,13 @@ import { classifyMonitorOutcome, parseMonitorPayload } from "./classify.js";
 import { EXIT_CONFIG_ERROR, EXIT_MERGED, EXIT_TIMEOUT_OR_ESCALATION } from "./constants.js";
 import { makeResult } from "./result.js";
 import { runGhMerge, runMonitor, runProtectedCheck } from "./wrappers.js";
+/** Node module-not-found / missing script — not a protected-issue overlap (#2667). */
+function isProtectedCheckConfigFailure(stderr) {
+    const tail = stderr.trim();
+    return (tail.includes("MODULE_NOT_FOUND") ||
+        tail.includes("Cannot find module") ||
+        tail.includes("protected-check script not found:"));
+}
 /** Run protected-check -> wait -> merge cascade (#1369). */
 export function waitMergeableAndMerge(prNumber, repo, options) {
     const protectedFn = options.protectedFn ?? runProtectedCheck;
@@ -17,7 +24,7 @@ export function waitMergeableAndMerge(prNumber, repo, options) {
             stderr: prcStderr,
             protected: [...protectedIssues],
         };
-        if (prcRc === 1) {
+        if (prcRc === 1 && !isProtectedCheckConfigFailure(prcStderr)) {
             return makeResult({
                 prNumber,
                 repo,

package/dist/pr-wait-mergeable/classify.js

@@ -5,7 +5,11 @@ export function classifyMonitorOutcome(monitorReturncode, monitorPayload) {
         return ["clean", EXIT_MERGED];
     }
     if (monitorReturncode === 1) {
-        return ["cap-reached", EXIT_TIMEOUT_OR_ESCALATION];
+        // Bare exit 1 (MODULE_NOT_FOUND / missing script) is not budget exhaustion (#2673).
+        if (monitorPayload.monitor_result === "CAP-REACHED") {
+            return ["cap-reached", EXIT_TIMEOUT_OR_ESCALATION];
+        }
+        return ["config-error", EXIT_CONFIG_ERROR];
     }
     if (monitorReturncode === 2) {
         return ["config-error", EXIT_CONFIG_ERROR];

package/dist/pr-wait-mergeable/wrappers.js

@@ -56,14 +56,17 @@ export function cliScriptPath(name) {
     const candidates = [];
     try {
         const require = createRequire(import.meta.url);
-        const pkgJson = require.resolve("@deftai/directive/package.json");
-        candidates.push(resolve(dirname(pkgJson), "dist", script));
+        // package.json is not an exported subpath under @deftai/directive exports (#2667).
+        const mainEntry = require.resolve("@deftai/directive");
+        candidates.push(resolve(dirname(mainEntry), script));
     }
     catch {
         // Core does not declare a runtime dependency on the CLI package; ignore.
     }
     // Monorepo: packages/core/dist/pr-wait-mergeable -> packages/cli/dist
     candidates.push(resolve(here, "../../../cli/dist", script));
+    // npm hoisted: .../@deftai/directive-core/dist/... -> .../@deftai/directive/dist
+    candidates.push(resolve(here, "../../../directive/dist", script));
     // npm nested: .../directive/node_modules/@deftai/directive-core/dist/... -> .../directive/dist
     candidates.push(resolve(here, "../../../../dist", script));
     for (const candidate of candidates) {
@@ -75,9 +78,13 @@ export function cliScriptPath(name) {
 }
 /** Invoke pr-protected-issues CLI and return (returncode, stdout, stderr). */
 export function runProtectedCheck(prNumber, repo, protectedIssues, options = {}) {
+    const scriptPath = cliScriptPath("pr-protected-issues");
+    if (!existsSync(scriptPath)) {
+        return [2, "", `protected-check script not found: ${scriptPath}`];
+    }
     const node = options.nodeExecutable ?? process.execPath;
     const cmd = [
-        cliScriptPath("pr-protected-issues"),
+        scriptPath,
         String(prNumber),
         "--protected",
         protectedIssues.map(String).join(","),
@@ -92,10 +99,14 @@ export function runProtectedCheck(prNumber, repo, protectedIssues, options = {})
 }
 /** Invoke pr-monitor CLI with --json and return (returncode, stdout, stderr). */
 export function runMonitor(prNumber, repo, capMinutes, options = {}) {
+    const scriptPath = cliScriptPath("pr-monitor");
+    if (!existsSync(scriptPath)) {
+        return [2, "", `monitor script not found: ${scriptPath}`];
+    }
     const node = options.nodeExecutable ?? process.execPath;
     const timeoutSec = options.timeout ?? capMinutes * 60 + 60;
     const cmd = [
-        cliScriptPath("pr-monitor"),
+        scriptPath,
         String(prNumber),
         "--repo",
         repo,

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

@@ -17,12 +17,22 @@ 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";
+/**
+ * Greptile side of the clean gate is satisfied on HEAD but required CI is red
+ * (#2688). Exit 2 — fail-loud toward a CI fix loop instead of idle-polling.
+ */
+export declare const VERDICT_CI_BLOCKED = "CI_BLOCKED";
 /** --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;
+/**
+ * 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
@@ -30,4 +40,9 @@ export declare const DEFAULT_POLL_SECONDS = 90;
  * whole 30-minute budget (#1039 STALL terminal).
  */
 export declare const DEFAULT_STALL_THRESHOLD = 3;
+/**
+ * Consecutive polls with clean_gate_holdout=ci_failures (Greptile otherwise
+ * satisfied) before CI_BLOCKED (#2688). Same default as SHA STALL.
+ */
+export declare const DEFAULT_CI_BLOCKED_THRESHOLD = 3;
 //# sourceMappingURL=constants.d.ts.map

package/dist/pr-watch/constants.js

@@ -17,12 +17,44 @@ export const VERDICT_NEW_P0_P1 = "NEW_P0_P1";
 export const VERDICT_ERRORED = "ERRORED";
 export const VERDICT_STALL = "STALL";
 export const VERDICT_TIMEOUT = "TIMEOUT";
+/**
+ * Greptile side of the clean gate is satisfied on HEAD but required CI is red
+ * (#2688). Exit 2 — fail-loud toward a CI fix loop instead of idle-polling.
+ */
+export const VERDICT_CI_BLOCKED = "CI_BLOCKED";
 /** --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;
+/**
+ * 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 | CI_BLOCKED | 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
@@ -30,4 +62,9 @@ export const DEFAULT_POLL_SECONDS = 90;
  * whole 30-minute budget (#1039 STALL terminal).
  */
 export const DEFAULT_STALL_THRESHOLD = 3;
+/**
+ * Consecutive polls with clean_gate_holdout=ci_failures (Greptile otherwise
+ * satisfied) before CI_BLOCKED (#2688). Same default as SHA STALL.
+ */
+export const DEFAULT_CI_BLOCKED_THRESHOLD = 3;
 //# sourceMappingURL=constants.js.map

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) {
@@ -130,6 +151,7 @@ export function watchResultToJson(result) {
         p1_count: p.p1Count,
         errored: p.errored,
         ci_failures: p.ciFailures,
+        ci_failed_checks: [...p.ciFailedChecks],
         is_clean: p.isClean,
         clean_gate_holdout: p.cleanGateHoldout,
         elapsed_seconds: result.elapsedSeconds,
@@ -150,6 +172,9 @@ export function printWatchHuman(result) {
     lines.push(`  Findings:           P0=${p.p0Count}  P1=${p.p1Count}`);
     lines.push(`  Errored sentinel:   ${p.errored}`);
     lines.push(`  CI failures:        ${p.ciFailures}`);
+    if (p.ciFailedChecks.length > 0) {
+        lines.push(`  Failed checks:      ${p.ciFailedChecks.join("; ")}`);
+    }
     if (p.cleanGateHoldout !== null) {
         lines.push(`  Clean-gate holdout: ${p.cleanGateHoldout}`);
     }
@@ -161,8 +186,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/pr-watch/probe.js

@@ -14,6 +14,7 @@ function errorProbe(headSha, message) {
         hasBlocking: false,
         errored: false,
         ciFailures: 0,
+        ciFailedChecks: [],
         terminalCheckRun: false,
         isClean: false,
         cleanGateHoldout: null,
@@ -61,12 +62,14 @@ export function probeOnce(prNumber, repoArg, runGh = defaultRunGh) {
     // 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 ciFailedChecks = [];
     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;
+            ciFailedChecks = ci.summary.failed_required;
+            ciFailures = ciFailedChecks.length;
             terminalCheckRun = ci.summary.pending_required.length === 0;
         }
     }
@@ -91,6 +94,7 @@ export function probeOnce(prNumber, repoArg, runGh = defaultRunGh) {
         hasBlocking: findings.has_blocking,
         errored,
         ciFailures,
+        ciFailedChecks,
         terminalCheckRun,
         isClean,
         cleanGateHoldout,