@deftai/directive-core 0.67.0 → 0.68.0

package/dist/platform/agents-md.js

@@ -3,7 +3,9 @@ import { randomUUID } from "node:crypto";
 import { existsSync, readFileSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
+import { atomicWriteText } from "../cache/io.js";
 import { contentRoot } from "../content-root.js";
+import { withAppendLock } from "../slice/lock.js";
 import { composeGreenfieldAgentsMd } from "./agents-consumer-header.js";
 import { AGENTS_MANAGED_CLOSE, AGENTS_MANAGED_OPEN_V3_LITERAL } from "./constants.js";
 import { findManagedOpenMarker } from "./linear-scan.js";
@@ -294,6 +296,38 @@ export function agentsRefreshPlan(projectRoot, seams = {}) {
         new_content: newContent,
     };
 }
+/** Managed-section states whose plan yields a new AGENTS.md body to write. */
+const AGENTS_REFRESH_WRITABLE_STATES = new Set(["absent", "missing", "stale"]);
+/**
+ * Serialize the AGENTS.md managed-section read->compute->write behind an advisory
+ * file lock and write atomically (temp file + rename), so concurrent
+ * install/upgrade/migrate/refresh writers cannot clobber one another's `session=`
+ * write or leave a partially-written file (#1329).
+ *
+ * Reuses the existing cross-process append lock (`withAppendLock`, keyed here on
+ * the AGENTS.md path -> `AGENTS.md.lock`) and atomic writer (`atomicWriteText`)
+ * rather than introducing a competing lock utility. The parallel
+ * `projectDefinitionMutationLock` remains owned by #1260; a general lock helper is
+ * deliberately not added here to avoid two competing mutation-lock utilities.
+ */
+export function applyAgentsRefresh(projectRoot, options = {}, seams = {}, lockDeps = {}) {
+    const agentsMd = join(projectRoot, "AGENTS.md");
+    return withAppendLock(agentsMd, () => {
+        const plan = agentsRefreshPlan(projectRoot, seams);
+        const state = String(plan.state ?? "unknown");
+        const path = String(plan.path ?? agentsMd);
+        const newContent = plan.new_content;
+        if (options.check === true ||
+            options.dryRun === true ||
+            !AGENTS_REFRESH_WRITABLE_STATES.has(state) ||
+            typeof newContent !== "string") {
+            const writable = AGENTS_REFRESH_WRITABLE_STATES.has(state) && typeof newContent === "string";
+            return { state, path, wrote: false, writable };
+        }
+        atomicWriteText(path, newContent);
+        return { state, path, wrote: true, writable: true };
+    }, lockDeps);
+}
 export function hasV3ManagedMarker(projectRoot, readText = defaultReadAgents) {
     const agentsMd = join(projectRoot, "AGENTS.md");
     const text = readText(agentsMd);

package/dist/policy/resolve.js

@@ -1,6 +1,7 @@
 import { appendFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { join, resolve as pathResolve } from "node:path";
 import { resolveProjectDefinitionPath } from "../layout/resolve.js";
+import { atomicWriteProjectDefinition, projectDefinitionMutationLock, } from "../vbrief-build/project-definition-io.js";
 import { migrateLegacyPolicyKey, PLAN_POLICY_KEY, readPlanPolicy } from "./plan-extensions.js";
 /** Filesystem-relative location of the project-definition vBRIEF (display/back-compat). */
 export const PROJECT_DEFINITION_REL_PATH = "vbrief/PROJECT-DEFINITION.vbrief.json";
@@ -184,55 +185,64 @@ export function setPolicy(projectRoot, options) {
     if (!existsSync(path)) {
         throw new Error(`PROJECT-DEFINITION not found at ${path}`);
     }
-    const data = JSON.parse(readFileSync(path, { encoding: "utf8" }));
-    if (typeof data.plan !== "object" || data.plan === null || Array.isArray(data.plan)) {
-        if (data.plan === undefined) {
-            data.plan = {};
+    // Serialise the read-modify-write + audit-log append behind the shared
+    // PROJECT-DEFINITION mutation lock so a concurrent policy/ritual mutator
+    // cannot lose this update or desync the typed flag from the audit row (#1260).
+    return projectDefinitionMutationLock(projectRoot, () => {
+        const parsed = JSON.parse(readFileSync(path, { encoding: "utf8" }));
+        if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+            throw new Error(`PROJECT-DEFINITION at ${path} top-level value is not a JSON object`);
         }
-        else {
-            throw new Error("PROJECT-DEFINITION 'plan' is not an object");
+        const data = parsed;
+        if (typeof data.plan !== "object" || data.plan === null || Array.isArray(data.plan)) {
+            if (data.plan === undefined) {
+                data.plan = {};
+            }
+            else {
+                throw new Error("PROJECT-DEFINITION 'plan' is not an object");
+            }
         }
-    }
-    const plan = data.plan;
-    migrateLegacyPolicyKey(plan);
-    const existingPolicy = plan[PLAN_POLICY_KEY];
-    if (typeof existingPolicy !== "object" ||
-        existingPolicy === null ||
-        Array.isArray(existingPolicy)) {
-        if (existingPolicy === undefined) {
-            plan[PLAN_POLICY_KEY] = {};
+        const plan = data.plan;
+        migrateLegacyPolicyKey(plan);
+        const existingPolicy = plan[PLAN_POLICY_KEY];
+        if (typeof existingPolicy !== "object" ||
+            existingPolicy === null ||
+            Array.isArray(existingPolicy)) {
+            if (existingPolicy === undefined) {
+                plan[PLAN_POLICY_KEY] = {};
+            }
+            else {
+                throw new Error("plan.policy is not an object");
+            }
         }
-        else {
-            throw new Error("plan.policy is not an object");
+        const policyBlock = plan[PLAN_POLICY_KEY];
+        const previous = policyBlock.allowDirectCommitsToMaster;
+        policyBlock.allowDirectCommitsToMaster = Boolean(allowDirectCommits);
+        let legacyDropped = false;
+        const narratives = plan.narratives;
+        if (typeof narratives === "object" &&
+            narratives !== null &&
+            !Array.isArray(narratives) &&
+            LEGACY_NARRATIVE_KEY in narratives) {
+            delete narratives[LEGACY_NARRATIVE_KEY];
+            legacyDropped = true;
         }
-    }
-    const policyBlock = plan[PLAN_POLICY_KEY];
-    const previous = policyBlock.allowDirectCommitsToMaster;
-    policyBlock.allowDirectCommitsToMaster = Boolean(allowDirectCommits);
-    let legacyDropped = false;
-    const narratives = plan.narratives;
-    if (typeof narratives === "object" &&
-        narratives !== null &&
-        !Array.isArray(narratives) &&
-        LEGACY_NARRATIVE_KEY in narratives) {
-        delete narratives[LEGACY_NARRATIVE_KEY];
-        legacyDropped = true;
-    }
-    writeFileSync(path, `${JSON.stringify(data, null, 2)}\n`, { encoding: "utf8" });
-    const changed = previous !== Boolean(allowDirectCommits) || legacyDropped;
-    const parts = [
-        `actor=${actor}`,
-        `allowDirectCommitsToMaster=${allowDirectCommits ? "true" : "false"}`,
-        `previous=${pythonRepr(previous)}`,
-    ];
-    if (legacyDropped) {
-        parts.push("legacy-narrative-migrated=true");
-    }
-    if (note) {
-        parts.push(`note=${note.replace(/\n/g, " ").replace(/\r/g, " ")}`);
-    }
-    const auditEntry = parts.join(" ");
-    appendAuditLog(projectRoot, auditEntry);
-    return { changed, auditEntry };
+        atomicWriteProjectDefinition(path, data);
+        const changed = previous !== Boolean(allowDirectCommits) || legacyDropped;
+        const parts = [
+            `actor=${actor}`,
+            `allowDirectCommitsToMaster=${allowDirectCommits ? "true" : "false"}`,
+            `previous=${pythonRepr(previous)}`,
+        ];
+        if (legacyDropped) {
+            parts.push("legacy-narrative-migrated=true");
+        }
+        if (note) {
+            parts.push(`note=${note.replace(/\n/g, " ").replace(/\r/g, " ")}`);
+        }
+        const auditEntry = parts.join(" ");
+        appendAuditLog(projectRoot, auditEntry);
+        return { changed, auditEntry };
+    });
 }
 //# sourceMappingURL=resolve.js.map

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

@@ -1,9 +1,19 @@
 import type { CiGateOptions } from "./ci-gate.js";
 import { isMergeReady } from "./evaluate.js";
+import { type MergeabilitySignal } from "./mergeability.js";
 import type { SlizardGateOptions } from "./slizard-gate.js";
 import type { GateResult, RunGhFn } from "./types.js";
 declare function buildGateResult(prNumber: number, repo: string | null, headSha: string | null, body: string, via: string, partialData?: Record<string, unknown>, error?: string | null): GateResult;
+/** Injectable GitHub-mergeability read seam (#2260) — keeps unit tests hermetic. */
+export type FetchMergeabilityFn = (prNumber: number, repo: string, runGh: RunGhFn) => MergeabilitySignal;
 export interface ComputeGateOptions extends CiGateOptions, SlizardGateOptions {
+    /** Override the GitHub-mergeability read (defaults to the REST reader). */
+    readonly fetchMergeabilityFn?: FetchMergeabilityFn;
+    /**
+     * Disable the #2260 mergeability reconciliation (defaults to enabled). When
+     * off, an absent/stale review verdict blocks even on a GitHub-CLEAN PR.
+     */
+    readonly disableMergeabilityReconcile?: boolean;
 }
 /** Run the primary->fallback1->fallback2 cascade and return a result. */
 export declare function computeGateResult(prNumber: number, repo: string | null, runGh: RunGhFn, options?: ComputeGateOptions): GateResult;

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

@@ -2,6 +2,7 @@ import { buildCiSummaryLine, evaluateCiGate } from "./ci-gate.js";
 import { FALLBACK2_NOT_CLEAN_MSG, VIA_ERROR, VIA_FALLBACK1, VIA_FALLBACK2, VIA_PRIMARY, } from "./constants.js";
 import { evaluateGates, isMergeReady } from "./evaluate.js";
 import { fetchCheckRunsRest, fetchGreptileBodyRest, fetchGreptileCommentBody, fetchPrHeadSha, fetchPrHeadShaRest, resolveRepo, } from "./gh.js";
+import { fetchMergeability, isGithubMergeableClean, mergeabilityToDict, verdictBlockIsSoftOnly, verdictShaIsStale, } from "./mergeability.js";
 import { emptyVerdict, parseGreptileBody } from "./parse.js";
 import { evaluateSlizardGate, isSlizardCheck } from "./slizard-gate.js";
 function buildGateResult(prNumber, repo, headSha, body, via, partialData = {}, error = null) {
@@ -86,6 +87,54 @@ function applyCiGateForHead(repo, headSha, runGh, options) {
     const outcome = evaluateCiAndSlizard(check.checkRuns, options);
     return { failures: outcome.failures, ci: outcome.ci, slizard: outcome.slizard };
 }
+/**
+ * Score the verdict gate for a resolved head SHA, then (when the review verdict
+ * is only soft-blocked -- absent or stale for the current head) reconcile
+ * against GitHub's own mergeability (#2260). Shared by primary + fallback1.
+ */
+function finalizeVerdictGate(prNumber, repo, headSha, verdict, runGh, options) {
+    const failures = evaluateGates(prNumber, headSha, verdict);
+    const partialData = {};
+    const resolved = resolveRepo(repo, runGh);
+    if (failures.length === 0) {
+        const ci = applyCiGateForHead(resolved.repo, headSha, runGh, options);
+        failures.push(...ci.failures);
+        partialData.ci = ci.ci;
+        partialData.slizard = ci.slizard;
+        return { failures, partialData };
+    }
+    // #2260 reconciliation: the verdict gate failed. If the block is a HARD
+    // finding (genuine P0/P1, ERRORED, low confidence on the current head), keep
+    // blocking. Only reconcile a SOFT block (verdict absent / stale head SHA).
+    if (options.disableMergeabilityReconcile === true ||
+        resolved.repo === null ||
+        !verdictBlockIsSoftOnly(verdict, headSha)) {
+        return { failures, partialData };
+    }
+    const ci = applyCiGateForHead(resolved.repo, headSha, runGh, options);
+    partialData.ci = ci.ci;
+    partialData.slizard = ci.slizard;
+    const fetchMergeabilityFn = options.fetchMergeabilityFn ?? fetchMergeability;
+    const signal = fetchMergeabilityFn(prNumber, resolved.repo, runGh);
+    partialData.mergeability = mergeabilityToDict(signal);
+    if (isGithubMergeableClean(signal)) {
+        // GitHub itself reports CLEAN + MERGEABLE: required checks are green and the
+        // branch is mergeable. Proceed even though the OPTIONAL review verdict is
+        // absent/stale for the head SHA -- exactly the manual `gh pr merge --admin`
+        // case this fix reproduces automatically (#2260).
+        partialData.verdict_override = {
+            reason: verdictShaIsStale(verdict, headSha) ? "verdict-stale-head-sha" : "verdict-absent",
+            basis: "github mergeable_state=clean + mergeable=true (mergeStateStatus:CLEAN + " +
+                "mergeable:MERGEABLE); required checks green per GitHub branch protection (#2260)",
+            overridden_failures: [...failures],
+        };
+        return { failures: [], partialData };
+    }
+    // Not overridable (GitHub not CLEAN/MERGEABLE). Preserve the soft verdict
+    // failures and surface any CI failures so the heartbeat's blocked-on is clear.
+    failures.push(...ci.failures);
+    return { failures, partialData };
+}
 function computePrimary(prNumber, repo, runGh, options) {
     const partial = {};
     const headSha = fetchPrHeadSha(prNumber, repo, runGh);
@@ -100,15 +149,7 @@ function computePrimary(prNumber, repo, runGh, options) {
         return { result: null, partial };
     }
     const verdict = parseGreptileBody(body);
-    const failures = evaluateGates(prNumber, headSha, verdict);
-    const partialData = {};
-    if (failures.length === 0) {
-        const resolved = resolveRepo(repo, runGh);
-        const ci = applyCiGateForHead(resolved.repo, headSha, runGh, options);
-        failures.push(...ci.failures);
-        partialData.ci = ci.ci;
-        partialData.slizard = ci.slizard;
-    }
+    const { failures, partialData } = finalizeVerdictGate(prNumber, repo, headSha, verdict, runGh, options);
     return {
         result: {
             prNumber,
@@ -146,26 +187,21 @@ function computeFallback1(prNumber, repo, primaryPartial, runGh, options) {
         return { result: null, partial };
     }
     const verdict = parseGreptileBody(bodyResult.body);
-    const failures = evaluateGates(prNumber, headSha, verdict);
+    const gate = finalizeVerdictGate(prNumber, resolved.repo, headSha, verdict, runGh, options);
     const partialData = {};
     for (const [key, value] of Object.entries(partial)) {
         if (key !== "head_sha") {
             partialData[key] = value;
         }
     }
-    if (failures.length === 0) {
-        const ci = applyCiGateForHead(resolved.repo, headSha, runGh, options);
-        failures.push(...ci.failures);
-        partialData.ci = ci.ci;
-        partialData.slizard = ci.slizard;
-    }
+    Object.assign(partialData, gate.partialData);
     return {
         result: {
             prNumber,
             repo: resolved.repo,
             headSha,
             verdict,
-            failures,
+            failures: gate.failures,
             via: VIA_FALLBACK1,
             partialData,
             error: null,

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

@@ -1,9 +1,10 @@
 export { buildCiSummaryLine, evaluateCiGate } from "./ci-gate.js";
-export { computeGateResult } from "./compute.js";
+export { type ComputeGateOptions, computeGateResult, type FetchMergeabilityFn } from "./compute.js";
 export * from "./constants.js";
 export { evaluateGates, isMergeReady } from "./evaluate.js";
 export { defaultRunGh } from "./gh.js";
 export { cmdPrMergeReadiness, parseArgs, run } from "./main.js";
+export { fetchMergeability, isGithubMergeableClean, MERGE_STATE_CLEAN, type MergeabilitySignal, mergeabilityToDict, verdictBlockIsSoftOnly, verdictShaIsStale, } from "./mergeability.js";
 export { emitJson, exitCodeFor, gateResultToDict, printHuman } from "./output.js";
 export { emptyVerdict, isInformalCleanMissingCanonicalFields, parseGreptileBody } from "./parse.js";
 export type { SlizardGateOptions, SlizardGateResult, SlizardGateSummary, SlizardVerdict, } from "./slizard-gate.js";

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

@@ -4,6 +4,7 @@ export * from "./constants.js";
 export { evaluateGates, isMergeReady } from "./evaluate.js";
 export { defaultRunGh } from "./gh.js";
 export { cmdPrMergeReadiness, parseArgs, run } from "./main.js";
+export { fetchMergeability, isGithubMergeableClean, MERGE_STATE_CLEAN, mergeabilityToDict, verdictBlockIsSoftOnly, verdictShaIsStale, } from "./mergeability.js";
 export { emitJson, exitCodeFor, gateResultToDict, printHuman } from "./output.js";
 export { emptyVerdict, isInformalCleanMissingCanonicalFields, parseGreptileBody } from "./parse.js";
 export { evaluateSlizardGate, isSlizardCheck, parseSlizardVerdict, SLIZARD_CHECK_NAME, } from "./slizard-gate.js";

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

@@ -0,0 +1,43 @@
+import type { GreptileVerdict, RunGhFn } from "./types.js";
+/**
+ * GitHub's authoritative mergeability signal, read over REST (#2260).
+ *
+ * REST `mergeable_state` maps 1:1 to GraphQL `mergeStateStatus`
+ * (e.g. `"clean"` == `CLEAN`); `mergeable` (boolean|null) maps to
+ * `mergeable` (`MERGEABLE`/`CONFLICTING`/`UNKNOWN`). We read REST to honor
+ * the "prefer REST over GraphQL" rule (#954) and to reuse the same
+ * `gh api repos/<owner>/<repo>/pulls/<N>` surface fallback2 already uses.
+ */
+export interface MergeabilitySignal {
+    readonly mergeableState: string | null;
+    readonly mergeable: boolean | null;
+    readonly error: string | null;
+}
+/** REST `mergeable_state` value that mirrors GraphQL `mergeStateStatus: CLEAN`. */
+export declare const MERGE_STATE_CLEAN = "clean";
+/**
+ * Read GitHub's own mergeability verdict for a PR over REST.
+ *
+ * Injectable via `runGh` so unit tests stay hermetic (no live network).
+ */
+export declare function fetchMergeability(prNumber: number, repo: string, runGh: RunGhFn): MergeabilitySignal;
+/** True when GitHub itself reports the PR as CLEAN + MERGEABLE (#2260). */
+export declare function isGithubMergeableClean(signal: MergeabilitySignal): boolean;
+/** Serialise the mergeability signal into the partial_data envelope shape. */
+export declare function mergeabilityToDict(signal: MergeabilitySignal): Record<string, unknown>;
+/** True when a parsed verdict SHA does not match the current PR head SHA. */
+export declare function verdictShaIsStale(verdict: GreptileVerdict, headSha: string | null): boolean;
+/**
+ * Classify whether the verdict-based merge block is ONLY "soft" (#2260).
+ *
+ * A soft block means the review verdict is absent or pinned to a prior head
+ * SHA (rebased staleness) -- i.e. the review has not spoken about the CURRENT
+ * head. It is safe to reconcile a soft block against GitHub mergeability.
+ *
+ * A HARD block -- a genuine P0/P1 finding, an ERRORED review, or a low
+ * confidence score on the current head -- is NEVER soft; those must keep
+ * blocking regardless of GitHub mergeability (guardrail: do not merge a PR
+ * with a real P0/P1 review finding).
+ */
+export declare function verdictBlockIsSoftOnly(verdict: GreptileVerdict, headSha: string | null): boolean;
+//# sourceMappingURL=mergeability.d.ts.map

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

@@ -0,0 +1,105 @@
+/** REST `mergeable_state` value that mirrors GraphQL `mergeStateStatus: CLEAN`. */
+export const MERGE_STATE_CLEAN = "clean";
+/**
+ * Read GitHub's own mergeability verdict for a PR over REST.
+ *
+ * Injectable via `runGh` so unit tests stay hermetic (no live network).
+ */
+export function fetchMergeability(prNumber, repo, runGh) {
+    const rc = runGh(["gh", "api", `repos/${repo}/pulls/${prNumber}`]);
+    if (rc.returncode !== 0) {
+        return {
+            mergeableState: null,
+            mergeable: null,
+            error: `gh api /pulls/${prNumber} failed: ${rc.stderr.trim()}`,
+        };
+    }
+    if (!rc.stdout.trim()) {
+        return { mergeableState: null, mergeable: null, error: "empty body from gh api /pulls/<N>" };
+    }
+    let payload;
+    try {
+        payload = JSON.parse(rc.stdout);
+    }
+    catch (exc) {
+        const message = exc instanceof Error ? exc.message : String(exc);
+        return { mergeableState: null, mergeable: null, error: `could not parse PR JSON: ${message}` };
+    }
+    if (payload === null || typeof payload !== "object" || Array.isArray(payload)) {
+        return {
+            mergeableState: null,
+            mergeable: null,
+            error: "unexpected PR JSON shape (not a dict)",
+        };
+    }
+    const pr = payload;
+    const rawState = pr.mergeable_state;
+    const rawMergeable = pr.mergeable;
+    return {
+        mergeableState: typeof rawState === "string" ? rawState : null,
+        mergeable: typeof rawMergeable === "boolean" ? rawMergeable : null,
+        error: null,
+    };
+}
+/** True when GitHub itself reports the PR as CLEAN + MERGEABLE (#2260). */
+export function isGithubMergeableClean(signal) {
+    return signal.mergeable === true && signal.mergeableState === MERGE_STATE_CLEAN;
+}
+/** Serialise the mergeability signal into the partial_data envelope shape. */
+export function mergeabilityToDict(signal) {
+    return {
+        mergeable_state: signal.mergeableState,
+        mergeable: signal.mergeable,
+        error: signal.error,
+    };
+}
+/** True when a parsed verdict SHA does not match the current PR head SHA. */
+export function verdictShaIsStale(verdict, headSha) {
+    if (!verdict.found || verdict.lastReviewedSha === null || !headSha) {
+        return false;
+    }
+    const reviewed = verdict.lastReviewedSha;
+    return !(headSha.startsWith(reviewed) || reviewed.startsWith(headSha));
+}
+/**
+ * Classify whether the verdict-based merge block is ONLY "soft" (#2260).
+ *
+ * A soft block means the review verdict is absent or pinned to a prior head
+ * SHA (rebased staleness) -- i.e. the review has not spoken about the CURRENT
+ * head. It is safe to reconcile a soft block against GitHub mergeability.
+ *
+ * A HARD block -- a genuine P0/P1 finding, an ERRORED review, or a low
+ * confidence score on the current head -- is NEVER soft; those must keep
+ * blocking regardless of GitHub mergeability (guardrail: do not merge a PR
+ * with a real P0/P1 review finding).
+ */
+export function verdictBlockIsSoftOnly(verdict, headSha) {
+    // Absent: no Greptile rolling-summary comment at all.
+    if (!verdict.found) {
+        return true;
+    }
+    // informal-clean (#1543) is a present-but-noncanonical verdict with its own
+    // remediation path; it is out of scope for the #2260 mergeability override.
+    if (verdict.informalClean) {
+        return false;
+    }
+    // Stale: verdict pinned to a prior head SHA -> its findings pertain to old code.
+    if (verdictShaIsStale(verdict, headSha)) {
+        return true;
+    }
+    // Verdict is current (or its SHA is unparseable). A genuine current-head
+    // finding is a hard block and must not be overridden.
+    if (verdict.errored) {
+        return false;
+    }
+    if (verdict.confidence !== null && verdict.confidence <= 3) {
+        return false;
+    }
+    if (verdict.p0Count > 0 || verdict.p1Count > 0) {
+        return false;
+    }
+    // No genuine finding: the block is a missing-canonical-field / not-yet-posted
+    // wait, which GitHub mergeability may resolve.
+    return true;
+}
+//# sourceMappingURL=mergeability.js.map

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

@@ -1,7 +1,7 @@
 export { cadenceIntervals } from "./cadence.js";
 export { DEFAULT_CADENCE, EXIT_CAP_REACHED, EXIT_CLEAN, EXIT_CONFIG_ERROR, EXIT_PR_TERMINAL, } from "./constants.js";
 export { cmdPrMonitor, parseMonitorArgs, runMonitor } from "./main.js";
-export { formatPollStatus, isTerminalPrState, monitor, summaryLabelForExit } from "./monitor.js";
+export { formatPollStatus, isTerminalPrState, mergeStateFromPayload, monitor, summaryLabelForExit, } from "./monitor.js";
 export { callReadiness } from "./readiness.js";
 export type { CallReadinessFn, CallReadinessOptions, MonitorOptions, MonitorRunResult, MonotonicClock, PollResult, SleepFn, } from "./types.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/pr-monitor/index.js

@@ -1,6 +1,6 @@
 export { cadenceIntervals } from "./cadence.js";
 export { DEFAULT_CADENCE, EXIT_CAP_REACHED, EXIT_CLEAN, EXIT_CONFIG_ERROR, EXIT_PR_TERMINAL, } from "./constants.js";
 export { cmdPrMonitor, parseMonitorArgs, runMonitor } from "./main.js";
-export { formatPollStatus, isTerminalPrState, monitor, summaryLabelForExit } from "./monitor.js";
+export { formatPollStatus, isTerminalPrState, mergeStateFromPayload, monitor, summaryLabelForExit, } from "./monitor.js";
 export { callReadiness } from "./readiness.js";
 //# sourceMappingURL=index.js.map

package/dist/pr-monitor/monitor.d.ts

@@ -1,6 +1,12 @@
 import type { MonitorOptions, MonitorRunResult, PollResult } from "./types.js";
-/** One-line stderr status mirror per poll. */
-export declare function formatPollStatus(pollIndex: number, pollResult: PollResult): string;
+/** Pull GitHub's merge-state signal out of a readiness payload, if present. */
+export declare function mergeStateFromPayload(payload: Record<string, unknown>): string;
+/**
+ * One-line stderr heartbeat per poll (#2260): elapsed, poll#, via, head,
+ * GitHub merge-state, CLEAN/BLOCKED, and what the poll is blocked on. Emitting
+ * this every poll makes a live poll visibly distinct from a hung process.
+ */
+export declare function formatPollStatus(pollIndex: number, pollResult: PollResult, elapsedSeconds?: number): string;
 /** Detect merged / closed PR via fallback2 partial_data. */
 export declare function isTerminalPrState(payload: Record<string, unknown>): boolean;
 /** Loop readiness with adaptive cadence until CLEAN / cap / terminal. */

package/dist/pr-monitor/monitor.js

@@ -13,8 +13,34 @@ function defaultSleep(seconds) {
         // busy-wait fallback when no injectable sleep in production CLI path
     }
 }
-/** One-line stderr status mirror per poll. */
-export function formatPollStatus(pollIndex, pollResult) {
+/** Pull GitHub's merge-state signal out of a readiness payload, if present. */
+export function mergeStateFromPayload(payload) {
+    const partialRaw = payload.partial_data;
+    const partial = partialRaw !== null && typeof partialRaw === "object" && !Array.isArray(partialRaw)
+        ? partialRaw
+        : {};
+    const mergeabilityRaw = partial.mergeability;
+    if (mergeabilityRaw !== null &&
+        typeof mergeabilityRaw === "object" &&
+        !Array.isArray(mergeabilityRaw)) {
+        const state = mergeabilityRaw.mergeable_state;
+        if (typeof state === "string" && state.length > 0) {
+            return state;
+        }
+    }
+    // fallback2 surfaces mergeable_state directly on partial_data.
+    const flatState = partial.mergeable_state;
+    if (typeof flatState === "string" && flatState.length > 0) {
+        return flatState;
+    }
+    return "?";
+}
+/**
+ * One-line stderr heartbeat per poll (#2260): elapsed, poll#, via, head,
+ * GitHub merge-state, CLEAN/BLOCKED, and what the poll is blocked on. Emitting
+ * this every poll makes a live poll visibly distinct from a hung process.
+ */
+export function formatPollStatus(pollIndex, pollResult, elapsedSeconds = 0) {
     const payload = pollResult.payload;
     const via = typeof payload.via === "string" ? payload.via : "?";
     const mergeReady = payload.merge_ready === true;
@@ -30,10 +56,12 @@ export function formatPollStatus(pollIndex, pollResult) {
     const failures = Array.isArray(failuresRaw) ? failuresRaw.map(String) : [];
     const firstFailure = failures[0] ?? "";
     const label = mergeReady ? "CLEAN" : "BLOCKED";
-    let line = `[monitor_pr] poll #${pollIndex} via=${via} head=${headDisplay} ` +
-        `${label} (${failures.length} failures)`;
+    const elapsed = Math.max(0, Math.round(elapsedSeconds));
+    const mergeState = mergeStateFromPayload(payload);
+    let line = `[monitor_pr] poll #${pollIndex} t=${elapsed}s via=${via} head=${headDisplay} ` +
+        `mergeState=${mergeState} ${label} (${failures.length} failures)`;
     if (firstFailure.length > 0) {
-        line += ` -- ${firstFailure.slice(0, 80)}`;
+        line += ` -- blocked-on: ${firstFailure.slice(0, 80)}`;
     }
     return line;
 }
@@ -65,7 +93,8 @@ export function monitor(prNumber, repo, options = {}) {
         const pollResult = callReadinessFn(prNumber, repo);
         lastPayload = pollResult.payload;
         lastExit = pollResult.exitCode;
-        process.stderr.write(`${formatPollStatus(pollIndex, pollResult)}\n`);
+        const elapsedAtPoll = clockFn.now() - startedAt;
+        process.stderr.write(`${formatPollStatus(pollIndex, pollResult, elapsedAtPoll)}\n`);
         if (pollResult.rawStderr.trim().length > 0) {
             process.stderr.write(pollResult.rawStderr);
         }

package/dist/pr-wait-mergeable/wrappers.d.ts

@@ -4,8 +4,19 @@ export interface CaptureExecResult {
     readonly stdout: string;
     readonly stderr: string;
 }
+export interface CaptureExecOptions {
+    /**
+     * Stream the child's stderr straight to the parent's stderr (live) instead of
+     * capturing it. Used for long polls so the per-poll heartbeat is visible in
+     * real time rather than buffered until the subprocess exits (#2260). When set,
+     * the returned `stderr` is empty because it was not captured.
+     */
+    readonly inheritStderr?: boolean;
+    /** Environment for the child (defaults to `process.env`). */
+    readonly env?: NodeJS.ProcessEnv;
+}
 /** UTF-8-safe subprocess capture via spawnSync (no shell) — mirrors #1366. */
-export declare function captureExec(executable: string, args: readonly string[], timeoutMs: number): CaptureExecResult;
+export declare function captureExec(executable: string, args: readonly string[], timeoutMs: number, options?: CaptureExecOptions): CaptureExecResult;
 export interface RunProtectedCheckOptions {
     readonly nodeExecutable?: string;
     readonly timeout?: number;

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

@@ -4,13 +4,13 @@ import { fileURLToPath } from "node:url";
 import { resolveBinary } from "../scm/binary.js";
 import { SUBPROCESS_MAX_BUFFER } from "../subprocess/max-buffer.js";
 /** UTF-8-safe subprocess capture via spawnSync (no shell) — mirrors #1366. */
-export function captureExec(executable, args, timeoutMs) {
+export function captureExec(executable, args, timeoutMs, options = {}) {
     const result = spawnSync(executable, args, {
         encoding: "utf8",
         timeout: timeoutMs,
-        stdio: ["ignore", "pipe", "pipe"],
+        stdio: ["ignore", "pipe", options.inheritStderr === true ? "inherit" : "pipe"],
         maxBuffer: SUBPROCESS_MAX_BUFFER,
-        env: process.env,
+        env: options.env ?? process.env,
     });
     if (result.error !== undefined) {
         const code = result.error.code;
@@ -56,7 +56,9 @@ export function runProtectedCheck(prNumber, repo, protectedIssues, options = {})
     if (repo) {
         cmd.push("--repo", repo);
     }
-    const result = captureExec(node, cmd, (options.timeout ?? 60) * 1000);
+    const result = captureExec(node, cmd, (options.timeout ?? 60) * 1000, {
+        env: { ...process.env, NODE_NO_WARNINGS: "1" },
+    });
     return [result.returncode, result.stdout, result.stderr];
 }
 /** Invoke pr-monitor CLI with --json and return (returncode, stdout, stderr). */
@@ -72,7 +74,13 @@ export function runMonitor(prNumber, repo, capMinutes, options = {}) {
         String(capMinutes),
         "--json",
     ];
-    const result = captureExec(node, cmd, timeoutSec * 1000);
+    // Stream the monitor's per-poll heartbeat live (a buffered poll looks like a
+    // hang, #2260) and suppress Node deprecation/engine warning noise so it never
+    // leaks onto the captured JSON stream or the final result line (#2240-class).
+    const result = captureExec(node, cmd, timeoutSec * 1000, {
+        inheritStderr: true,
+        env: { ...process.env, NODE_NO_WARNINGS: "1" },
+    });
     return [result.returncode, result.stdout, result.stderr];
 }
 /** Invoke ``gh pr merge --squash --delete-branch --admin``. */