@deftai/directive-core 0.79.3 → 0.80.0

package/dist/policy/staleness-tickler.js

@@ -0,0 +1,151 @@
+import { readPlanPolicy } from "./plan-extensions.js";
+export const FIELD_STALENESS_TICKLER = "plan.policy.stalenessTickler";
+export const FIELD_STALENESS_TICKLER_CLI_ALIAS = "stalenessTickler";
+const MS_PER_DAY = 24 * 60 * 60 * 1000;
+export const DEFAULT_STALENESS_TICKLER_WEIGHTS = {
+    directiveMajor: 10,
+    directiveMinor: 3,
+    directivePatch: 1,
+    schemaMajor: 15,
+    schemaMinor: 5,
+    agePerDay: 0.1,
+    deferral: 2,
+};
+export const DEFAULT_STALENESS_TICKLER_TIERS = {
+    noticeMinorThreshold: 2,
+    strongAgeMs: 30 * MS_PER_DAY,
+    assertDeferralCap: 5,
+};
+export const DEFAULT_STALENESS_TICKLER_SNOOZE = {
+    quietMs: 7 * MS_PER_DAY,
+    noticeMs: MS_PER_DAY,
+    strongMs: 4 * 60 * 60 * 1000,
+    maxWidenMultiplier: 4,
+};
+export const DEFAULT_STALENESS_TICKLER_POLICY = {
+    enabled: true,
+    optOut: false,
+    weights: DEFAULT_STALENESS_TICKLER_WEIGHTS,
+    tiers: DEFAULT_STALENESS_TICKLER_TIERS,
+    snooze: DEFAULT_STALENESS_TICKLER_SNOOZE,
+};
+function readBoolean(rec, key, fallback) {
+    if (key in rec && typeof rec[key] === "boolean") {
+        return rec[key];
+    }
+    return fallback;
+}
+function readNumber(rec, key, fallback) {
+    if (key in rec && typeof rec[key] === "number" && Number.isFinite(rec[key])) {
+        return rec[key];
+    }
+    return fallback;
+}
+function readWeights(raw) {
+    if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+        return DEFAULT_STALENESS_TICKLER_WEIGHTS;
+    }
+    const rec = raw;
+    return {
+        directiveMajor: readNumber(rec, "directiveMajor", DEFAULT_STALENESS_TICKLER_WEIGHTS.directiveMajor),
+        directiveMinor: readNumber(rec, "directiveMinor", DEFAULT_STALENESS_TICKLER_WEIGHTS.directiveMinor),
+        directivePatch: readNumber(rec, "directivePatch", DEFAULT_STALENESS_TICKLER_WEIGHTS.directivePatch),
+        schemaMajor: readNumber(rec, "schemaMajor", DEFAULT_STALENESS_TICKLER_WEIGHTS.schemaMajor),
+        schemaMinor: readNumber(rec, "schemaMinor", DEFAULT_STALENESS_TICKLER_WEIGHTS.schemaMinor),
+        agePerDay: readNumber(rec, "agePerDay", DEFAULT_STALENESS_TICKLER_WEIGHTS.agePerDay),
+        deferral: readNumber(rec, "deferral", DEFAULT_STALENESS_TICKLER_WEIGHTS.deferral),
+    };
+}
+function readTierThresholds(raw) {
+    if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+        return DEFAULT_STALENESS_TICKLER_TIERS;
+    }
+    const rec = raw;
+    return {
+        noticeMinorThreshold: readNumber(rec, "noticeMinorThreshold", DEFAULT_STALENESS_TICKLER_TIERS.noticeMinorThreshold),
+        strongAgeMs: readNumber(rec, "strongAgeMs", DEFAULT_STALENESS_TICKLER_TIERS.strongAgeMs),
+        assertDeferralCap: readNumber(rec, "assertDeferralCap", DEFAULT_STALENESS_TICKLER_TIERS.assertDeferralCap),
+    };
+}
+function readSnooze(raw) {
+    if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+        return DEFAULT_STALENESS_TICKLER_SNOOZE;
+    }
+    const rec = raw;
+    return {
+        quietMs: readNumber(rec, "quietMs", DEFAULT_STALENESS_TICKLER_SNOOZE.quietMs),
+        noticeMs: readNumber(rec, "noticeMs", DEFAULT_STALENESS_TICKLER_SNOOZE.noticeMs),
+        strongMs: readNumber(rec, "strongMs", DEFAULT_STALENESS_TICKLER_SNOOZE.strongMs),
+        maxWidenMultiplier: readNumber(rec, "maxWidenMultiplier", DEFAULT_STALENESS_TICKLER_SNOOZE.maxWidenMultiplier),
+    };
+}
+export function resolveStalenessTicklerPolicy(raw) {
+    if (raw === null || raw === undefined) {
+        return DEFAULT_STALENESS_TICKLER_POLICY;
+    }
+    if (typeof raw !== "object" || Array.isArray(raw)) {
+        return DEFAULT_STALENESS_TICKLER_POLICY;
+    }
+    const rec = raw;
+    return {
+        enabled: readBoolean(rec, "enabled", DEFAULT_STALENESS_TICKLER_POLICY.enabled),
+        optOut: readBoolean(rec, "optOut", DEFAULT_STALENESS_TICKLER_POLICY.optOut),
+        weights: readWeights(rec.weights),
+        tiers: readTierThresholds(rec.tiers),
+        snooze: readSnooze(rec.snooze),
+    };
+}
+export function validateStalenessTickler(value) {
+    if (value === null || value === undefined) {
+        return [];
+    }
+    if (typeof value !== "object" || Array.isArray(value)) {
+        return [`${FIELD_STALENESS_TICKLER} must be an object; got ${typeof value}`];
+    }
+    const rec = value;
+    const errors = [];
+    for (const key of ["enabled", "optOut"]) {
+        if (key in rec && typeof rec[key] !== "boolean") {
+            errors.push(`${FIELD_STALENESS_TICKLER}.${key} must be a boolean`);
+        }
+    }
+    return errors;
+}
+function fieldFromResolved(resolved, source) {
+    return {
+        name: FIELD_STALENESS_TICKLER,
+        current: resolved,
+        default: DEFAULT_STALENESS_TICKLER_POLICY,
+        source,
+    };
+}
+/** Inspector row for `policy:show --field=stalenessTickler`. */
+export function inspectStalenessTickler(data) {
+    if (data === null) {
+        return fieldFromResolved(DEFAULT_STALENESS_TICKLER_POLICY, "default");
+    }
+    const policyBlock = readPlanPolicy(data.plan);
+    if (typeof policyBlock !== "object" ||
+        policyBlock === null ||
+        Array.isArray(policyBlock) ||
+        !("stalenessTickler" in policyBlock)) {
+        return fieldFromResolved(DEFAULT_STALENESS_TICKLER_POLICY, "default");
+    }
+    const resolved = resolveStalenessTicklerPolicy(policyBlock.stalenessTickler);
+    return fieldFromResolved(resolved, "typed");
+}
+/** Resolve typed staleness tickler policy from PROJECT-DEFINITION. */
+export function loadStalenessTicklerPolicy(data) {
+    if (data === null) {
+        return DEFAULT_STALENESS_TICKLER_POLICY;
+    }
+    const policyBlock = readPlanPolicy(data.plan);
+    if (typeof policyBlock !== "object" ||
+        policyBlock === null ||
+        Array.isArray(policyBlock) ||
+        !("stalenessTickler" in policyBlock)) {
+        return DEFAULT_STALENESS_TICKLER_POLICY;
+    }
+    return resolveStalenessTicklerPolicy(policyBlock.stalenessTickler);
+}
+//# sourceMappingURL=staleness-tickler.js.map

package/dist/pr-merge-readiness/ci-gate.d.ts

@@ -1,8 +1,12 @@
 import type { CheckRunRecord } from "./gh.js";
-export type CiReadyState = "ready" | "blocked" | "not_ready_yet" | "skipped";
+export type CiReadyState = "ready" | "blocked" | "not_ready_yet" | "runner_capacity_stall" | "skipped";
 export interface CiGateOptions {
     readonly skipCi?: boolean;
     readonly ignoreCheckNames?: readonly string[];
+    /** Stall budget for runner_capacity_stall (#2672); default 20 minutes. */
+    readonly capacityStallBudgetMs?: number;
+    /** Injectable clock for capacity-stall tests. */
+    readonly nowMs?: number;
 }
 export interface CiCheckConclusion {
     readonly name: string;
@@ -17,6 +21,8 @@ export interface CiGateSummary {
     readonly ignored_checks: readonly string[];
     readonly failed_required: readonly string[];
     readonly pending_required: readonly string[];
+    /** Required checks classified as capacity-stalled (#2672). */
+    readonly capacity_stalled_required: readonly string[];
     readonly conclusions: readonly CiCheckConclusion[];
 }
 export interface CiGateResult {

package/dist/pr-merge-readiness/ci-gate.js

@@ -1,3 +1,4 @@
+import { classifyCapacityStalledRequired, DEFAULT_CAPACITY_STALL_MS, } from "./runner-capacity-stall.js";
 const FAILED_CONCLUSIONS = new Set(["failure", "cancelled", "timed_out"]);
 const PENDING_STATUSES = new Set(["queued", "in_progress"]);
 function isPending(status, conclusion) {
@@ -8,8 +9,12 @@ function isPending(status, conclusion) {
 }
 export function buildCiSummaryLine(summary) {
     const passed = summary.checked_count - summary.failed_required.length - summary.pending_required.length;
+    const stallSuffix = summary.capacity_stalled_required.length > 0
+        ? ` / ${summary.capacity_stalled_required.length} capacity-stalled`
+        : "";
     return (`CI check-runs: ${passed} passed / ` +
-        `${summary.failed_required.length} failed / ${summary.pending_required.length} pending`);
+        `${summary.failed_required.length} failed / ${summary.pending_required.length} pending` +
+        stallSuffix);
 }
 export function evaluateCiGate(checkRuns, options = {}) {
     if (options.skipCi === true) {
@@ -21,6 +26,7 @@ export function evaluateCiGate(checkRuns, options = {}) {
                 ignored_checks: [],
                 failed_required: [],
                 pending_required: [],
+                capacity_stalled_required: [],
                 conclusions: [],
             },
         };
@@ -29,6 +35,7 @@ export function evaluateCiGate(checkRuns, options = {}) {
     const ignoredChecks = [];
     const failedRequired = [];
     const pendingRequired = [];
+    const pendingProbes = [];
     const conclusions = [];
     for (const run of checkRuns) {
         const ignored = ignoredSet.has(run.name);
@@ -52,18 +59,43 @@ export function evaluateCiGate(checkRuns, options = {}) {
         }
         if (isPending(run.status, run.conclusion)) {
             pendingRequired.push(`${run.name} (${run.status})`);
+            pendingProbes.push(run);
         }
     }
+    const stallOpts = {
+        budgetMs: options.capacityStallBudgetMs ?? DEFAULT_CAPACITY_STALL_MS,
+        nowMs: options.nowMs,
+    };
+    const capacityStalledRequired = classifyCapacityStalledRequired(pendingProbes, stallOpts);
     const failures = [];
     if (failedRequired.length > 0) {
         failures.push(`Required CI check-runs failed: ${failedRequired.join(", ")}. ` +
             "Required checks fail closed by default (#2169).");
     }
-    if (pendingRequired.length > 0) {
-        failures.push(`Required CI check-runs still running (not-ready-yet): ${pendingRequired.join(", ")}. ` +
-            "Wait for required checks to finish before merge.");
+    let readyState;
+    if (failedRequired.length > 0) {
+        readyState = "blocked";
+    }
+    else if (pendingRequired.length > 0) {
+        // Capacity stall when every pending required check is a queue stall past
+        // budget — distinct from ordinary not_ready_yet (under budget / in_progress).
+        const allPendingStalled = capacityStalledRequired.length > 0 && capacityStalledRequired.length === pendingProbes.length;
+        if (allPendingStalled) {
+            readyState = "runner_capacity_stall";
+            failures.push(`Required CI check-runs capacity-stalled (runner_capacity_stall): ` +
+                `${capacityStalledRequired.join(", ")}. ` +
+                "Queued past the stall budget with no runner claimed (#2672). " +
+                "Wait for auto-failover to the GH-hosted lane; do NOT use --skip-ci.");
+        }
+        else {
+            readyState = "not_ready_yet";
+            failures.push(`Required CI check-runs still running (not-ready-yet): ${pendingRequired.join(", ")}. ` +
+                "Wait for required checks to finish before merge.");
+        }
+    }
+    else {
+        readyState = "ready";
     }
-    const readyState = failedRequired.length > 0 ? "blocked" : pendingRequired.length > 0 ? "not_ready_yet" : "ready";
     return {
         failures,
         summary: {
@@ -72,6 +104,7 @@ export function evaluateCiGate(checkRuns, options = {}) {
             ignored_checks: ignoredChecks,
             failed_required: failedRequired,
             pending_required: pendingRequired,
+            capacity_stalled_required: capacityStalledRequired,
             conclusions,
         },
     };

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

@@ -5,6 +5,10 @@ export interface CheckRunRecord {
     readonly conclusion: string;
     /** check-run `output.summary` text, when present (used by the SLizard verdict gate, #2189). */
     readonly summary?: string;
+    /** ISO created_at — capacity-stall budget clock (#2672). */
+    readonly created_at?: string | null;
+    /** ISO started_at — null while still queued with no runner (#2672). */
+    readonly started_at?: string | null;
 }
 /** UTF-8-safe gh capture via execFile (no shell) — mirrors _safe_subprocess.run_text (#1366). */
 export declare function defaultRunGh(cmd: readonly string[]): RunGhResult;

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

@@ -296,9 +296,16 @@ export function fetchCheckRunsRest(sha, repo, runGh) {
         const conclusion = typeof r.conclusion === "string" ? r.conclusion : "none";
         const name = typeof r.name === "string" && r.name.length > 0 ? r.name : "<unnamed>";
         const runSummary = extractCheckRunSummary(r);
-        const record = runSummary === null
-            ? { name, status, conclusion }
-            : { name, status, conclusion, summary: runSummary };
+        const createdAt = typeof r.created_at === "string" ? r.created_at : null;
+        const startedAt = typeof r.started_at === "string" ? r.started_at : null;
+        const record = {
+            name,
+            status,
+            conclusion,
+            created_at: createdAt,
+            started_at: startedAt,
+            ...(runSummary === null ? {} : { summary: runSummary }),
+        };
         checkRuns.push(record);
         byStatus[status] = (byStatus[status] ?? 0) + 1;
         byConclusion[conclusion] = (byConclusion[conclusion] ?? 0) + 1;

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

@@ -1,4 +1,4 @@
-export { buildCiSummaryLine, evaluateCiGate } from "./ci-gate.js";
+export { buildCiSummaryLine, type CiCheckConclusion, type CiGateOptions, type CiGateResult, type CiGateSummary, type CiReadyState, evaluateCiGate, } from "./ci-gate.js";
 export { type ComputeGateOptions, computeGateResult, type FetchMergeabilityFn } from "./compute.js";
 export * from "./constants.js";
 export { evaluateGates, isMergeReady } from "./evaluate.js";
@@ -8,6 +8,7 @@ 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";
 export { emptyVerdict, isInformalCleanMissingCanonicalFields, parseGreptileBody } from "./parse.js";
+export { type CapacityStallOptions, type CapacityStallProbe, classifyCapacityStalledRequired, DEFAULT_CAPACITY_STALL_MS, isRunnerCapacityStalled, } from "./runner-capacity-stall.js";
 export type { SlizardGateOptions, SlizardGateResult, SlizardGateSummary, SlizardVerdict, } from "./slizard-gate.js";
 export { evaluateSlizardGate, isSlizardCheck, parseSlizardVerdict, SLIZARD_CHECK_NAME, } from "./slizard-gate.js";
 export type { GateResult, GreptileVerdict, RunGhFn, RunGhResult } from "./types.js";

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

@@ -1,4 +1,4 @@
-export { buildCiSummaryLine, evaluateCiGate } from "./ci-gate.js";
+export { buildCiSummaryLine, evaluateCiGate, } from "./ci-gate.js";
 export { computeGateResult } from "./compute.js";
 export * from "./constants.js";
 export { evaluateGates, isMergeReady } from "./evaluate.js";
@@ -8,5 +8,6 @@ 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";
 export { emptyVerdict, isInformalCleanMissingCanonicalFields, parseGreptileBody } from "./parse.js";
+export { classifyCapacityStalledRequired, DEFAULT_CAPACITY_STALL_MS, isRunnerCapacityStalled, } from "./runner-capacity-stall.js";
 export { evaluateSlizardGate, isSlizardCheck, parseSlizardVerdict, SLIZARD_CHECK_NAME, } from "./slizard-gate.js";
 //# sourceMappingURL=index.js.map

package/dist/pr-merge-readiness/runner-capacity-stall.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Runner capacity-stall classifier for required CI check-runs (#2672).
+ *
+ * Distinct from ordinary `not_ready_yet` (check still under budget / in_progress)
+ * and from execution hangs (#2652). A capacity stall is: required check still
+ * `queued`, no `started_at`, past the stall budget since `created_at`.
+ */
+/** Default stall budget: 20 minutes (matches CI_CAPACITY_STALL_SECONDS in ci.yml). */
+export declare const DEFAULT_CAPACITY_STALL_MS: number;
+export interface CapacityStallProbe {
+    readonly name: string;
+    readonly status: string;
+    readonly conclusion?: string;
+    /** ISO timestamp when the check-run was created (budget clock). */
+    readonly created_at?: string | null;
+    /** ISO timestamp when execution started; null/absent while still queued. */
+    readonly started_at?: string | null;
+}
+export interface CapacityStallOptions {
+    /** Stall budget in ms (default 20m). */
+    readonly budgetMs?: number;
+    /** Injectable clock for tests. */
+    readonly nowMs?: number;
+}
+/**
+ * True when a single check-run looks capacity-stalled (queued, never started,
+ * past budget). Never true for `in_progress` (#2652 must not be conflated).
+ */
+export declare function isRunnerCapacityStalled(run: CapacityStallProbe, options?: CapacityStallOptions): boolean;
+/**
+ * Among pending required check names, return those that are capacity-stalled.
+ * Callers pass only the required/pending subset.
+ */
+export declare function classifyCapacityStalledRequired(pendingRequired: readonly CapacityStallProbe[], options?: CapacityStallOptions): readonly string[];
+//# sourceMappingURL=runner-capacity-stall.d.ts.map

package/dist/pr-merge-readiness/runner-capacity-stall.js

@@ -0,0 +1,46 @@
+/**
+ * Runner capacity-stall classifier for required CI check-runs (#2672).
+ *
+ * Distinct from ordinary `not_ready_yet` (check still under budget / in_progress)
+ * and from execution hangs (#2652). A capacity stall is: required check still
+ * `queued`, no `started_at`, past the stall budget since `created_at`.
+ */
+/** Default stall budget: 20 minutes (matches CI_CAPACITY_STALL_SECONDS in ci.yml). */
+export const DEFAULT_CAPACITY_STALL_MS = 20 * 60 * 1000;
+/**
+ * True when a single check-run looks capacity-stalled (queued, never started,
+ * past budget). Never true for `in_progress` (#2652 must not be conflated).
+ */
+export function isRunnerCapacityStalled(run, options = {}) {
+    if (run.status !== "queued") {
+        return false;
+    }
+    if (run.started_at != null && String(run.started_at).length > 0) {
+        return false;
+    }
+    const createdRaw = run.created_at;
+    if (createdRaw == null || String(createdRaw).length === 0) {
+        return false;
+    }
+    const createdMs = Date.parse(String(createdRaw));
+    if (!Number.isFinite(createdMs)) {
+        return false;
+    }
+    const nowMs = options.nowMs ?? Date.now();
+    const budgetMs = options.budgetMs ?? DEFAULT_CAPACITY_STALL_MS;
+    return nowMs - createdMs >= budgetMs;
+}
+/**
+ * Among pending required check names, return those that are capacity-stalled.
+ * Callers pass only the required/pending subset.
+ */
+export function classifyCapacityStalledRequired(pendingRequired, options = {}) {
+    const stalled = [];
+    for (const run of pendingRequired) {
+        if (isRunnerCapacityStalled(run, options)) {
+            stalled.push(run.name);
+        }
+    }
+    return stalled;
+}
+//# sourceMappingURL=runner-capacity-stall.js.map

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,6 +17,16 @@ 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";
+/**
+ * Required CI is still queued past the capacity-stall budget with no runner
+ * claimed (#2672). Exit 2 — wait for auto-failover; never --skip-ci.
+ */
+export declare const VERDICT_RUNNER_CAPACITY_STALL = "RUNNER_CAPACITY_STALL";
 /** --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). */
@@ -35,4 +45,9 @@ export declare const WATCH_HELP: string;
  * 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,6 +17,16 @@ 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";
+/**
+ * Required CI is still queued past the capacity-stall budget with no runner
+ * claimed (#2672). Exit 2 — wait for auto-failover; never --skip-ci.
+ */
+export const VERDICT_RUNNER_CAPACITY_STALL = "RUNNER_CAPACITY_STALL";
 /** --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). */
@@ -49,7 +59,7 @@ export const WATCH_HELP = "usage: task pr:watch -- <pr_number> [options]\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";
+    "  2  ERRORED | STALL | TIMEOUT | CI_BLOCKED | RUNNER_CAPACITY_STALL | 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
@@ -57,4 +67,9 @@ export const WATCH_HELP = "usage: task pr:watch -- <pr_number> [options]\n" +
  * 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/main.js

@@ -151,6 +151,9 @@ export function watchResultToJson(result) {
         p1_count: p.p1Count,
         errored: p.errored,
         ci_failures: p.ciFailures,
+        ci_failed_checks: [...p.ciFailedChecks],
+        ci_ready_state: p.ciReadyState,
+        ci_capacity_stalled_checks: [...p.ciCapacityStalledChecks],
         is_clean: p.isClean,
         clean_gate_holdout: p.cleanGateHoldout,
         elapsed_seconds: result.elapsedSeconds,
@@ -171,6 +174,15 @@ 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.ciReadyState !== null) {
+        lines.push(`  CI ready_state:     ${p.ciReadyState}`);
+    }
+    if (p.ciFailedChecks.length > 0) {
+        lines.push(`  Failed checks:      ${p.ciFailedChecks.join("; ")}`);
+    }
+    if (p.ciCapacityStalledChecks.length > 0) {
+        lines.push(`  Capacity-stalled:   ${p.ciCapacityStalledChecks.join("; ")}`);
+    }
     if (p.cleanGateHoldout !== null) {
         lines.push(`  Clean-gate holdout: ${p.cleanGateHoldout}`);
     }

package/dist/pr-watch/probe.js

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

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

@@ -13,6 +13,15 @@ export interface WatchProbe {
     readonly hasBlocking: boolean;
     readonly errored: boolean;
     readonly ciFailures: number;
+    /** Failed required check identities (name + conclusion), when CI was probed. */
+    readonly ciFailedChecks: readonly string[];
+    /**
+     * CI gate ready_state from evaluateCiGate (#2169 / #2672).
+     * Includes `runner_capacity_stall` distinct from `not_ready_yet`.
+     */
+    readonly ciReadyState: string | null;
+    /** Required checks classified as capacity-stalled (#2672). */
+    readonly ciCapacityStalledChecks: readonly string[];
     /** All required CI check-runs have a terminal conclusion (none pending). */
     readonly terminalCheckRun: boolean;
     readonly isClean: boolean;