@deftai/directive-core 0.96.0 → 0.98.0

package/dist/pr-watch/main.js

@@ -1,6 +1,7 @@
 import { existsSync } from "node:fs";
 import { resolve } from "node:path";
 import { defaultRunGh } from "../pr-merge-readiness/gh.js";
+import { platformStatusUrlsForWeather } from "../pr-merge-readiness/platform-status.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) {
@@ -140,7 +141,7 @@ function pythonJsonDumps(value) {
 /** AC-4 stable --json shape (same field set as the #1039 Tier-1 instrumentation line). */
 export function watchResultToJson(result) {
     const p = result.probe;
-    return {
+    const payload = {
         verdict: result.verdict,
         pr_number: result.prNumber,
         head_sha: p.headSha,
@@ -159,6 +160,13 @@ export function watchResultToJson(result) {
         elapsed_seconds: result.elapsedSeconds,
         poll_count: result.pollCount,
     };
+    // #3180: static status URLs on weather-class ci_ready_state (no network fetch).
+    const statusUrls = platformStatusUrlsForWeather(p.ciReadyState);
+    if (statusUrls !== null) {
+        payload.platform_status_github = statusUrls.platform_status_github;
+        payload.platform_status_blacksmith = statusUrls.platform_status_blacksmith;
+    }
+    return payload;
 }
 export function emitWatchJson(result) {
     return `${pythonJsonDumps(watchResultToJson(result))}\n`;
@@ -183,6 +191,13 @@ export function printWatchHuman(result) {
     if (p.ciCapacityStalledChecks.length > 0) {
         lines.push(`  Capacity-stalled:   ${p.ciCapacityStalledChecks.join("; ")}`);
     }
+    // #3180: probe these pages before workflow thrash on weather states.
+    const statusUrls = platformStatusUrlsForWeather(p.ciReadyState);
+    if (statusUrls !== null) {
+        lines.push(`  Platform status GH: ${statusUrls.platform_status_github}`);
+        lines.push(`  Platform status BS: ${statusUrls.platform_status_blacksmith}`);
+        lines.push("  Probe status pages before workflow edits (#3180)");
+    }
     if (p.cleanGateHoldout !== null) {
         lines.push(`  Clean-gate holdout: ${p.cleanGateHoldout}`);
     }

package/dist/pr-watch/probe.js

@@ -82,7 +82,7 @@ export function probeOnce(prNumber, repoArg, runGh = defaultRunGh, projectRoot =
         }
     }
     const shaMatch = lastReviewedSha !== null && lastReviewedSha === headSha;
-    const [isClean, cleanGateHoldout] = evaluateCleanGate({
+    let [isClean, cleanGateHoldout] = evaluateCleanGate({
         lastReviewedSha,
         headSha,
         hasBlocking: findings.has_blocking,
@@ -92,6 +92,18 @@ export function probeOnce(prNumber, repoArg, runGh = defaultRunGh, projectRoot =
         terminalCheckRun,
         minConfidence,
     });
+    // #3167: weather not-ready states must never surface as CLEAN even when the
+    // Greptile side of the clean gate is satisfied (empty CI was previously ready).
+    if (isClean &&
+        (ciReadyState === "ci_never_scheduled" ||
+            ciReadyState === "runner_capacity_stall" ||
+            ciReadyState === "ci_cancelled_no_failover" ||
+            ciReadyState === "ci_failures" ||
+            ciReadyState === "blocked" ||
+            ciReadyState === "not_ready_yet")) {
+        isClean = false;
+        cleanGateHoldout = ciReadyState === "not_ready_yet" ? "terminal_check_run" : ciReadyState;
+    }
     return {
         found,
         headSha,

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

@@ -16,8 +16,9 @@ export interface WatchProbe {
     /** 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`.
+     * CI gate ready_state from evaluateCiGate (#2169 / #2672 / #3167).
+     * Weather codes: `ci_never_scheduled`, `runner_capacity_stall`,
+     * `ci_failures`, `ci_cancelled_no_failover` (plus `not_ready_yet` / `ready`).
      */
     readonly ciReadyState: string | null;
     /** Required checks classified as capacity-stalled (#2672). */

package/dist/pr-watch/watch.js

@@ -1,5 +1,5 @@
 import { defaultRunGh } from "../pr-merge-readiness/gh.js";
-import { DEFAULT_CI_BLOCKED_THRESHOLD, DEFAULT_MAX_WAIT_MINUTES, DEFAULT_POLL_SECONDS, DEFAULT_STALL_THRESHOLD, EXIT_CLEAN, EXIT_NEW_P0_P1, EXIT_TERMINAL_ERROR, VERDICT_CI_BLOCKED, VERDICT_CLEAN, VERDICT_CONFIG, VERDICT_ERRORED, VERDICT_NEW_P0_P1, VERDICT_PENDING, VERDICT_RUNNER_CAPACITY_STALL, VERDICT_STALL, VERDICT_TIMEOUT, } from "./constants.js";
+import { DEFAULT_CI_BLOCKED_THRESHOLD, DEFAULT_MAX_WAIT_MINUTES, DEFAULT_POLL_SECONDS, DEFAULT_STALL_THRESHOLD, EXIT_CLEAN, EXIT_NEW_P0_P1, EXIT_TERMINAL_ERROR, VERDICT_CI_BLOCKED, VERDICT_CI_CANCELLED_NO_FAILOVER, VERDICT_CI_NEVER_SCHEDULED, VERDICT_CLEAN, VERDICT_CONFIG, VERDICT_ERRORED, VERDICT_NEW_P0_P1, VERDICT_PENDING, VERDICT_RUNNER_CAPACITY_STALL, VERDICT_STALL, VERDICT_TIMEOUT, } from "./constants.js";
 import { probeOnce } from "./probe.js";
 const systemMonotonicClock = {
     now() {
@@ -81,20 +81,27 @@ export function watch(prNumber, repo, options = {}) {
         if (probe.errored) {
             return build(VERDICT_ERRORED, EXIT_TERMINAL_ERROR, probe, poll);
         }
-        // #2672: capacity stall is distinct from ordinary not_ready_yet — surface
-        // immediately (exit 2) so agents wait for auto-failover instead of --skip-ci.
+        // #2672 / #3167: CI weather states are distinct terminal exits (exit 2).
+        // Agents must thrash-cap / BLOCKED rather than multi-hour empty-commit loops.
         if (probe.ciReadyState === "runner_capacity_stall") {
             return build(VERDICT_RUNNER_CAPACITY_STALL, EXIT_TERMINAL_ERROR, probe, poll);
         }
-        // #2688: Greptile side satisfied on HEAD but CI red — fail loud toward a
-        // fix loop instead of burning max-wait-minutes on idle Greptile polls.
-        if (probe.cleanGateHoldout === "ci_failures") {
+        if (probe.ciReadyState === "ci_never_scheduled") {
+            return build(VERDICT_CI_NEVER_SCHEDULED, EXIT_TERMINAL_ERROR, probe, poll);
+        }
+        if (probe.ciReadyState === "ci_cancelled_no_failover") {
+            return build(VERDICT_CI_CANCELLED_NO_FAILOVER, EXIT_TERMINAL_ERROR, probe, poll);
+        }
+        // #2688 / #3167: Greptile side satisfied on HEAD but CI red (ci_failures) —
+        // fail loud toward a fix loop instead of burning max-wait-minutes.
+        const ciProductBlocked = probe.cleanGateHoldout === "ci_failures" || probe.ciReadyState === "ci_failures";
+        if (ciProductBlocked) {
             ciBlockedStreak += 1;
         }
         else {
             ciBlockedStreak = 0;
         }
-        if (oneShot && probe.cleanGateHoldout === "ci_failures") {
+        if (oneShot && ciProductBlocked) {
             return build(VERDICT_CI_BLOCKED, EXIT_TERMINAL_ERROR, probe, poll);
         }
         if (!oneShot && ciBlockedStreak >= DEFAULT_CI_BLOCKED_THRESHOLD) {

package/dist/release/auto-hatch.d.ts

@@ -0,0 +1,114 @@
+/**
+ * Release Step 5 auto-hatch for branch-only coverage hairlines (#3187 / #2866).
+ *
+ * Pure classifier + ledger helpers + debt-issue body. Network I/O is seamed so
+ * unit tests never hit live GitHub.
+ */
+import { type CoverageTotals } from "../vitest-runner/coverage-debt.js";
+/** Machine-checkable Step 5 failure classes (#3187). */
+export type Step5FailureClass = "REAL_FAILURE" | "BRANCH_HAIRLINE" | "OTHER_COVERAGE" | "UNKNOWN";
+export interface ClassifyStep5FailureInput {
+    /** Combined reason / stdout / stderr from the Step 5 check (may be thin). */
+    readonly output?: string | null;
+    /** Aggregated totals from coverage/coverage-final.json when present. */
+    readonly totals?: CoverageTotals | null;
+    /** Exit code when known (124 = hard timeout). */
+    readonly exitCode?: number | null;
+    /** True when the check hit the Step 5 wall-clock budget. */
+    readonly timedOut?: boolean;
+    /** Explicit failed-test count when the runner reports one. */
+    readonly failedTests?: number | null;
+}
+/**
+ * Classify metrics alone (no output / test signals).
+ * Returns null when totals are absent.
+ */
+export declare function classifyCoverageMetrics(totals: CoverageTotals | null | undefined): "ok" | "branch_hairline" | "other_coverage" | null;
+/**
+ * Pure classifier for release Step 5 non-zero outcomes.
+ *
+ * Prefer coverage-final totals when present; fall back to parseable output.
+ * Fail closed to UNKNOWN when evidence is ambiguous.
+ */
+export declare function classifyStep5Failure(input: ClassifyStep5FailureInput): Step5FailureClass;
+/** Open-issue shape used by the coverage-debt ledger probe. */
+export interface CoverageDebtIssueProbe {
+    readonly number: number;
+    readonly title?: string | null;
+    readonly body?: string | null;
+    readonly state?: string | null;
+}
+/** True when title/body carry the mandatory debt markers (#2866). */
+export declare function issueHasCoverageDebtMarkers(issue: CoverageDebtIssueProbe): boolean;
+/**
+ * Filter issues that count as unpaid coverage debt on the ledger.
+ *
+ * Accepts:
+ * - open issues with coverage-debt / --allow-coverage-debt markers
+ * - citation-only probes (`{ number }` only) from CHANGELOG scan after state check
+ */
+export declare function filterOpenCoverageDebtIssues(issues: readonly CoverageDebtIssueProbe[]): number[];
+/**
+ * Parse `--allow-coverage-debt=#N` / `allow-coverage-debt=#N` citations from
+ * CHANGELOG Unreleased + the last few version sections (legacy hatch ledger).
+ */
+export declare function extractCoverageDebtCitationsFromChangelog(changelog: string, maxVersionSections?: number): number[];
+/** Union marker-search hits with CHANGELOG-cited open issues. */
+export declare function mergeOpenDebtLedger(markerHits: readonly number[], changelogCitedOpen: readonly number[]): number[];
+export interface CoverageDebtIssueDraft {
+    readonly title: string;
+    readonly body: string;
+}
+/** Build a marker-compliant coverage-debt issue for auto-hatch (#3187). */
+export declare function buildCoverageDebtIssueDraft(options: {
+    readonly version: string;
+    readonly totals: CoverageTotals;
+    readonly autoHatched?: boolean;
+}): CoverageDebtIssueDraft;
+export type AutoHatchDecision = {
+    readonly kind: "pass_with_debt";
+    readonly issue: number;
+    readonly created: boolean;
+    readonly class: "BRANCH_HAIRLINE";
+    readonly totals: CoverageTotals;
+} | {
+    readonly kind: "fail_closed";
+    readonly class: Step5FailureClass;
+    readonly reason: string;
+    readonly openDebtIssues?: readonly number[];
+};
+export interface AutoHatchEvaluateInput {
+    readonly classification: Step5FailureClass;
+    readonly totals: CoverageTotals | null;
+    readonly openDebtIssues: readonly number[];
+    /** When true, create a new issue via createIssue (seamed). */
+    readonly createIssue?: () => number;
+    /** Operator already supplied --allow-coverage-debt=#N — never auto-create. */
+    readonly existingDebtIssue?: number | null;
+    /** Optional hard cut: refuse auto-hatch even on hairline. */
+    readonly noAutoCoverageDebt?: boolean;
+}
+/**
+ * Decide whether Step 5 may soft-pass after one suite run (#3187).
+ * Never continues without a durable issue number (file-before-continue).
+ */
+export declare function evaluateAutoHatch(input: AutoHatchEvaluateInput): AutoHatchDecision;
+/** Loud stderr banner when Step 5 continues via auto-hatch. */
+export declare function formatAutoHatchBanner(issue: number, totals: CoverageTotals): string;
+/** Parse exit code from the default runReleaseCheck reason string when present. */
+export declare function parseExitCodeFromReason(reason: string): number | null;
+export declare function reasonLooksLikeTimeout(reason: string): boolean;
+/**
+ * Refuse to trust a coverage-final.json older than the Step 5 wall budget (+buffer).
+ * Prevents a stale hairline report from masking a later non-coverage check failure (#3187 Greptile P1).
+ */
+export declare function isCoverageReportFresh(mtimeMs: number | null | undefined, nowMs?: number, maxAgeMs?: number): boolean;
+/**
+ * When totals come only from on-disk coverage-final and the failure reason is thin,
+ * require a fresh report before classifying BRANCH_HAIRLINE.
+ */
+export declare function classifyStep5FailureWithFreshness(input: ClassifyStep5FailureInput & {
+    readonly coverageReportMtimeMs?: number | null;
+    readonly nowMs?: number;
+}): Step5FailureClass;
+//# sourceMappingURL=auto-hatch.d.ts.map

package/dist/release/auto-hatch.js

@@ -0,0 +1,301 @@
+/**
+ * Release Step 5 auto-hatch for branch-only coverage hairlines (#3187 / #2866).
+ *
+ * Pure classifier + ledger helpers + debt-issue body. Network I/O is seamed so
+ * unit tests never hit live GitHub.
+ */
+import { COVERAGE_GOAL, metricsBelowGoal, } from "../vitest-runner/coverage-debt.js";
+const REAL_FAILURE_PATTERNS = [
+    /\btimed?\s*out\b/i,
+    /\bhang(?:ing|ed)?\b/i,
+    /\b\d+\s+failed\b/i,
+    /\bfailed\s+tests?\b/i,
+    /\bTests?\s+failed\b/i,
+    /\bFAIL\s+\S+/i,
+    /\bAssertionError\b/,
+    /\bError:\s/i,
+    /vitest coverage hang/i,
+];
+const COVERAGE_THRESHOLD_PATTERNS = [
+    /Coverage for (\w+)\s*\(([\d.]+)%\)\s*does not meet/i,
+    /ERROR:\s*Coverage for (\w+)/i,
+    /coverage threshold/i,
+    /below (?:the )?(?:global )?threshold/i,
+];
+/**
+ * Classify metrics alone (no output / test signals).
+ * Returns null when totals are absent.
+ */
+export function classifyCoverageMetrics(totals) {
+    if (!totals)
+        return null;
+    const missed = metricsBelowGoal(totals);
+    if (missed.length === 0)
+        return "ok";
+    if (missed.length === 1 && missed[0] === "branches")
+        return "branch_hairline";
+    return "other_coverage";
+}
+function outputSuggestsRealFailure(output) {
+    // Coverage-threshold lines alone are not real product failures.
+    const withoutCoverage = output
+        .split(/\r?\n/)
+        .filter((line) => !COVERAGE_THRESHOLD_PATTERNS.some((re) => re.test(line)))
+        .join("\n");
+    return REAL_FAILURE_PATTERNS.some((re) => re.test(withoutCoverage));
+}
+function outputSuggestsCoverageThreshold(output) {
+    return COVERAGE_THRESHOLD_PATTERNS.some((re) => re.test(output));
+}
+/**
+ * Pure classifier for release Step 5 non-zero outcomes.
+ *
+ * Prefer coverage-final totals when present; fall back to parseable output.
+ * Fail closed to UNKNOWN when evidence is ambiguous.
+ */
+export function classifyStep5Failure(input) {
+    const output = (input.output ?? "").trim();
+    const timedOut = input.timedOut === true || input.exitCode === 124;
+    const failedTests = typeof input.failedTests === "number" && Number.isFinite(input.failedTests)
+        ? input.failedTests
+        : null;
+    if (timedOut)
+        return "REAL_FAILURE";
+    if (failedTests !== null && failedTests > 0)
+        return "REAL_FAILURE";
+    if (output && outputSuggestsRealFailure(output))
+        return "REAL_FAILURE";
+    const metricClass = classifyCoverageMetrics(input.totals ?? null);
+    if (metricClass === "branch_hairline")
+        return "BRANCH_HAIRLINE";
+    if (metricClass === "other_coverage")
+        return "OTHER_COVERAGE";
+    if (metricClass === "ok") {
+        // Coverage met the bar but Step 5 still failed → non-coverage defect.
+        return output ? "REAL_FAILURE" : "UNKNOWN";
+    }
+    // No totals — try output-only signals.
+    if (output && outputSuggestsCoverageThreshold(output)) {
+        // Without totals we cannot prove branch-only; refuse to auto-hatch.
+        return "OTHER_COVERAGE";
+    }
+    if (output)
+        return "UNKNOWN";
+    return "UNKNOWN";
+}
+const DEBT_MARKER_RE = /coverage[- ]debt|--allow-coverage-debt/i;
+/** True when title/body carry the mandatory debt markers (#2866). */
+export function issueHasCoverageDebtMarkers(issue) {
+    const blob = `${issue.title ?? ""}\n${issue.body ?? ""}`;
+    return DEBT_MARKER_RE.test(blob);
+}
+/**
+ * Filter issues that count as unpaid coverage debt on the ledger.
+ *
+ * Accepts:
+ * - open issues with coverage-debt / --allow-coverage-debt markers
+ * - citation-only probes (`{ number }` only) from CHANGELOG scan after state check
+ */
+export function filterOpenCoverageDebtIssues(issues) {
+    const open = new Set();
+    for (const issue of issues) {
+        if (!issue.number || issue.number <= 0)
+            continue;
+        const state = (issue.state ?? "OPEN").toUpperCase();
+        if (state !== "OPEN")
+            continue;
+        const citationOnly = issue.title == null && issue.body == null;
+        if (citationOnly || issueHasCoverageDebtMarkers(issue)) {
+            open.add(issue.number);
+        }
+    }
+    return [...open].sort((a, b) => a - b);
+}
+/**
+ * Parse `--allow-coverage-debt=#N` / `allow-coverage-debt=#N` citations from
+ * CHANGELOG Unreleased + the last few version sections (legacy hatch ledger).
+ */
+export function extractCoverageDebtCitationsFromChangelog(changelog, maxVersionSections = 3) {
+    const versionHeader = /^## \[(?!Unreleased)/m;
+    const parts = changelog.split(versionHeader);
+    // parts[0] includes ## [Unreleased] and preamble; then each version section.
+    const windows = [parts[0] ?? "", ...parts.slice(1, maxVersionSections + 1)];
+    const found = new Set();
+    const re = /allow-coverage-debt=#?(\d+)/gi;
+    for (const section of windows) {
+        let m = re.exec(section);
+        while (m) {
+            const n = Number.parseInt(m[1] ?? "", 10);
+            if (Number.isFinite(n) && n > 0)
+                found.add(n);
+            m = re.exec(section);
+        }
+    }
+    return [...found].sort((a, b) => a - b);
+}
+/** Union marker-search hits with CHANGELOG-cited open issues. */
+export function mergeOpenDebtLedger(markerHits, changelogCitedOpen) {
+    return [...new Set([...markerHits, ...changelogCitedOpen])].sort((a, b) => a - b);
+}
+/** Build a marker-compliant coverage-debt issue for auto-hatch (#3187). */
+export function buildCoverageDebtIssueDraft(options) {
+    const { version, totals } = options;
+    const auto = options.autoHatched !== false;
+    const fmt = (n) => n.toFixed(2);
+    const title = `coverage-debt: restore branch coverage after v${version} hairline (${fmt(totals.branches)}%)`;
+    const body = [
+        `## coverage-debt`,
+        "",
+        auto
+            ? "Auto-filed by `task release` Step 5 auto-hatch (#3187) after a branch-only hairline."
+            : "Filed for release Step 5 coverage-debt hatch (#2866).",
+        "",
+        "### Markers",
+        "",
+        "- `coverage-debt`",
+        "- `--allow-coverage-debt`",
+        "",
+        "### Measured (at hatch)",
+        "",
+        `| Metric | Measured | Goal |`,
+        `| --- | ---: | ---: |`,
+        `| branches | ${fmt(totals.branches)}% | ${COVERAGE_GOAL.branches}% |`,
+        `| lines | ${fmt(totals.lines)}% | ${COVERAGE_GOAL.lines}% |`,
+        `| functions | ${fmt(totals.functions)}% | ${COVERAGE_GOAL.functions}% |`,
+        `| statements | ${fmt(totals.statements)}% | ${COVERAGE_GOAL.statements}% |`,
+        "",
+        `### Cut`,
+        "",
+        `- Release version: \`v${version}\``,
+        "- Trigger: **branches** sole metric below 85% (lines / functions / statements all ≥ 85%)",
+        "",
+        "### Acceptance",
+        "",
+        "- [ ] All four coverage metrics (lines, functions, branches, statements) ≥ 85%",
+        "- [ ] Close this issue only after real coverage is restored (no consecutive soft-pass while open)",
+        "",
+        "Refs #3187, #2866, #2573.",
+    ].join("\n");
+    return { title, body };
+}
+/**
+ * Decide whether Step 5 may soft-pass after one suite run (#3187).
+ * Never continues without a durable issue number (file-before-continue).
+ */
+export function evaluateAutoHatch(input) {
+    if (input.classification !== "BRANCH_HAIRLINE") {
+        return {
+            kind: "fail_closed",
+            class: input.classification,
+            reason: input.classification === "REAL_FAILURE"
+                ? "real failure / hang / failed tests — use file-and-merge (#2859)"
+                : input.classification === "OTHER_COVERAGE"
+                    ? "non-hairline coverage miss — auto-hatch refused"
+                    : "cannot classify Step 5 failure (UNKNOWN) — fail closed",
+        };
+    }
+    if (input.noAutoCoverageDebt) {
+        return {
+            kind: "fail_closed",
+            class: "BRANCH_HAIRLINE",
+            reason: "auto-hatch disabled (--no-auto-coverage-debt)",
+        };
+    }
+    if (!input.totals) {
+        return {
+            kind: "fail_closed",
+            class: "UNKNOWN",
+            reason: "BRANCH_HAIRLINE without measurable totals — refuse auto-hatch",
+        };
+    }
+    if (input.openDebtIssues.length > 0) {
+        const listed = input.openDebtIssues.map((n) => `#${n}`).join(", ");
+        return {
+            kind: "fail_closed",
+            class: "BRANCH_HAIRLINE",
+            reason: `open coverage-debt ledger not empty (${listed}); restore coverage and close before soft-pass`,
+            openDebtIssues: input.openDebtIssues,
+        };
+    }
+    if (input.existingDebtIssue != null && input.existingDebtIssue > 0) {
+        // Operator already bound a debt issue; treat as acknowledged hatch without create.
+        return {
+            kind: "pass_with_debt",
+            issue: input.existingDebtIssue,
+            created: false,
+            class: "BRANCH_HAIRLINE",
+            totals: input.totals,
+        };
+    }
+    if (!input.createIssue) {
+        return {
+            kind: "fail_closed",
+            class: "BRANCH_HAIRLINE",
+            reason: "auto-hatch requires createIssue seam to file durable debt before continue",
+        };
+    }
+    const issue = input.createIssue();
+    if (!Number.isFinite(issue) || issue <= 0) {
+        return {
+            kind: "fail_closed",
+            class: "BRANCH_HAIRLINE",
+            reason: "auto-hatch issue create returned invalid number — refuse continue without ledger",
+        };
+    }
+    return {
+        kind: "pass_with_debt",
+        issue,
+        created: true,
+        class: "BRANCH_HAIRLINE",
+        totals: input.totals,
+    };
+}
+/** Loud stderr banner when Step 5 continues via auto-hatch. */
+export function formatAutoHatchBanner(issue, totals) {
+    return (`*** AUTO-HATCH: coverage-debt #${issue} filed; Step 5 PASS_WITH_DEBT (no suite re-run) ***\n` +
+        `  branches ${totals.branches.toFixed(2)}% (sole metric < ${COVERAGE_GOAL.branches}%); ` +
+        `lines ${totals.lines.toFixed(2)}% | functions ${totals.functions.toFixed(2)}% | ` +
+        `statements ${totals.statements.toFixed(2)}% all ≥ goal\n` +
+        `  Cite #${issue} in CHANGELOG / release notes. Restore all four metrics before close.\n`);
+}
+/** Parse exit code from the default runReleaseCheck reason string when present. */
+export function parseExitCodeFromReason(reason) {
+    const m = /exit\s+(\d+)/i.exec(reason);
+    if (!m)
+        return null;
+    const n = Number.parseInt(m[1] ?? "", 10);
+    return Number.isFinite(n) ? n : null;
+}
+export function reasonLooksLikeTimeout(reason) {
+    return /timed out|timeout/i.test(reason);
+}
+/**
+ * Refuse to trust a coverage-final.json older than the Step 5 wall budget (+buffer).
+ * Prevents a stale hairline report from masking a later non-coverage check failure (#3187 Greptile P1).
+ */
+export function isCoverageReportFresh(mtimeMs, nowMs = Date.now(), maxAgeMs = 25 * 60 * 1000) {
+    if (mtimeMs == null || !Number.isFinite(mtimeMs) || mtimeMs <= 0)
+        return false;
+    const age = nowMs - mtimeMs;
+    if (age < 0)
+        return true; // clock skew: treat as fresh
+    return age <= maxAgeMs;
+}
+/**
+ * When totals come only from on-disk coverage-final and the failure reason is thin,
+ * require a fresh report before classifying BRANCH_HAIRLINE.
+ */
+export function classifyStep5FailureWithFreshness(input) {
+    const classified = classifyStep5Failure(input);
+    if (classified !== "BRANCH_HAIRLINE")
+        return classified;
+    const mtime = input.coverageReportMtimeMs;
+    // Explicit totals injected without mtime (unit tests / seams) remain trusted.
+    if (mtime === undefined)
+        return classified;
+    if (!isCoverageReportFresh(mtime, input.nowMs)) {
+        return "UNKNOWN";
+    }
+    return classified;
+}
+//# sourceMappingURL=auto-hatch.js.map

package/dist/release/coverage-debt-ledger.d.ts

@@ -0,0 +1,22 @@
+import type { ReleaseSeams } from "./types.js";
+export interface CoverageDebtLedgerSeams {
+    readonly spawnText?: ReleaseSeams["spawnText"];
+    readonly whichGh?: ReleaseSeams["whichGh"];
+    readonly readFile?: ReleaseSeams["readFile"];
+    readonly fileExists?: ReleaseSeams["fileExists"];
+    /** Override full ledger probe (tests). */
+    readonly listOpenDebtIssues?: (repo: string, projectRoot: string) => number[];
+    /** Override issue create (tests). */
+    readonly createDebtIssue?: (repo: string, projectRoot: string, title: string, body: string) => number;
+}
+/**
+ * Probe open coverage-debt ledger: marker searches + CHANGELOG citation scan.
+ * Citation numbers whose state is OPEN or UNKNOWN count as unpaid (fail closed).
+ *
+ * Fail closed: gh marker-search failures throw (do not treat as empty ledger).
+ * Missing gh falls through to CHANGELOG citations only (still fail-closed on UNKNOWN).
+ */
+export declare function probeOpenCoverageDebtLedger(repo: string, projectRoot: string, seams?: CoverageDebtLedgerSeams): number[];
+/** Create a coverage-debt issue; returns issue number or throws. */
+export declare function createCoverageDebtIssue(repo: string, projectRoot: string, title: string, body: string, seams?: CoverageDebtLedgerSeams): number;
+//# sourceMappingURL=coverage-debt-ledger.d.ts.map