@phnx-labs/agents-cli 1.22.120 → 1.22.121

package/dist/lib/github/ci-failure.d.ts

@@ -0,0 +1,30 @@
+import { type GhExec } from './pr-mergeable.js';
+export declare const EXCERPT_LIMIT = 12;
+export interface FailingCheck {
+    name: string;
+    url: string | null;
+    runId: number | null;
+    jobId: number | null;
+    conclusion: string;
+    excerpt: string[];
+    excerptError: string | null;
+}
+export interface CiFailureReport {
+    repo: string;
+    sha: string;
+    checks: FailingCheck[];
+    error: string | null;
+}
+export interface RerunResult {
+    repo: string;
+    runId: number;
+    requested: boolean;
+    message: string;
+}
+export declare function excerptFromLog(log: string): string[];
+export declare function actionsIds(url: string | null): {
+    runId: number | null;
+    jobId: number | null;
+};
+export declare function readCiFailure(repo: string, sha: string, gh?: GhExec): Promise<CiFailureReport>;
+export declare function rerunFailedJobs(repo: string, runId: number, gh?: GhExec): Promise<RerunResult>;

package/dist/lib/github/ci-failure.js

@@ -0,0 +1,95 @@
+import { ghExec } from './pr-mergeable.js';
+import { FAILING_CONCLUSIONS, FAILING_STATES, ghFailure } from './project-prs.js';
+import { rollupForSha } from './rest.js';
+export const EXCERPT_LIMIT = 12;
+// Fork-controlled logs are hostile terminal input: strip CSI/OSC/DCS/APC/PM and C0/C1 controls.
+const TIMESTAMP = /^\d{4}-\d\d-\d\dT\d\d:\d\d:\d\d(?:\.\d+)?Z ?/;
+// eslint-disable-next-line no-control-regex
+const ESCAPES = /\x1b\[[0-9;?]*[ -/]*[@-~]|\x1b[\]P^_][\s\S]*?(?:\x07|\x1b\\|$)|\x1b[@-Z\\-_]|\x9b[0-9;?]*[ -/]*[@-~]/g;
+// eslint-disable-next-line no-control-regex
+const CONTROLS = /[\x00-\x08\x0b-\x1f\x7f-\x9f]/g;
+const ERRORISH = /error|fail|exit(?:ed|ing)? (?:with )?code|✗|×/i;
+const ALL_CLEAR = /(?:^|\W)0 (?:failed|failures?|errors?)\b|\b(?:failed|failures?|errors?):? 0\b/i;
+const NOISE = /^(?:##\[(?:group|endgroup)\]|\[command\]|shell: |env:$)/;
+const CLEANUP = /^Post job cleanup\.?$/;
+function cleanLine(raw) {
+    return raw.replace(TIMESTAMP, '').replace(ESCAPES, '').replace(CONTROLS, '').replace(/^##\[(?:error|warning)\]/, '').trimEnd();
+}
+export function excerptFromLog(log) {
+    const lines = [];
+    for (const raw of log.replace(/^\uFEFF/, '').split(/\r?\n/)) {
+        const line = cleanLine(raw);
+        if (CLEANUP.test(line.trim()))
+            break;
+        lines.push(line);
+    }
+    const usable = (i) => i >= 0 && i < lines.length && lines[i].trim() !== '' && !NOISE.test(lines[i]);
+    const keep = new Set();
+    lines.forEach((line, i) => {
+        if (!usable(i) || !ERRORISH.test(line) || ALL_CLEAR.test(line))
+            return;
+        for (const j of [i - 1, i, i + 1])
+            if (usable(j))
+                keep.add(j);
+    });
+    const picked = [];
+    for (const i of [...keep].sort((a, b) => a - b)) {
+        if (picked.at(-1) !== lines[i])
+            picked.push(lines[i]);
+    }
+    if (picked.length <= EXCERPT_LIMIT)
+        return picked;
+    return [...picked.slice(0, 7), '…', ...picked.slice(-4)];
+}
+export function actionsIds(url) {
+    const m = url?.match(/\/actions\/runs\/(\d+)\/jobs?\/(\d+)/);
+    return m ? { runId: Number(m[1]), jobId: Number(m[2]) } : { runId: null, jobId: null };
+}
+async function readJobLog(repo, jobId, gh) {
+    return gh(['api', '--allow-escape-sequences', `repos/${repo}/actions/jobs/${jobId}/logs`]);
+}
+function logFailure(err) {
+    const raw = `${String(err?.stderr ?? '')} ${err instanceof Error ? err.message : String(err)}`;
+    if (/unknown flag: --allow-escape-sequences/.test(raw))
+        return 'This gh is too old to read job logs (it lacks --allow-escape-sequences); upgrade gh.';
+    if (/maxBuffer/i.test(raw))
+        return 'The job log is larger than 8 MB; open it on GitHub.';
+    if (err?.killed)
+        return 'The job log did not download within 30 s; open it on GitHub.';
+    return ghFailure(err);
+}
+const isFailing = (item) => (item.state === undefined
+    ? FAILING_CONCLUSIONS.has(item.conclusion ?? '')
+    : FAILING_STATES.has(item.state));
+export async function readCiFailure(repo, sha, gh = ghExec) {
+    let items;
+    try {
+        items = await rollupForSha(repo, sha, gh);
+    }
+    catch (err) {
+        return { repo, sha, checks: [], error: ghFailure(err) };
+    }
+    const checks = await Promise.all(items.filter(isFailing).map(async (item) => {
+        const url = item.link || null;
+        const check = { name: item.name, url, ...actionsIds(url), conclusion: (item.conclusion ?? item.state ?? '') };
+        if (check.jobId === null) {
+            return { ...check, excerpt: [], excerptError: 'Not a GitHub Actions job: open the check for its log.' };
+        }
+        try {
+            return { ...check, excerpt: excerptFromLog(await readJobLog(repo, check.jobId, gh)), excerptError: null };
+        }
+        catch (err) {
+            return { ...check, excerpt: [], excerptError: logFailure(err) };
+        }
+    }));
+    return { repo, sha, checks, error: null };
+}
+export async function rerunFailedJobs(repo, runId, gh = ghExec) {
+    try {
+        await gh(['api', '-X', 'POST', `repos/${repo}/actions/runs/${runId}/rerun-failed-jobs`]);
+    }
+    catch (err) {
+        return { repo, runId, requested: false, message: ghFailure(err) };
+    }
+    return { repo, runId, requested: true, message: 'Re-run of the failed jobs requested' };
+}

package/dist/lib/github/gh-overload.d.ts

@@ -1,54 +1,16 @@
-/**
- * The delegate behind the `gh` PATH shim (`agents __gh --real-gh <path> -- <argv>`).
- *
- * Agents are statically trained to type `gh pr checks …`; the shim intercepts that
- * habit and routes it here so the rate-limit-prone read runs over REST instead of
- * GraphQL — no new command for an agent to remember. This is the Tier-1 scope:
- * only `gh pr checks` is handled; every other invocation execs the real gh
- * byte-for-byte (the shim already passes non-`pr checks` verbs straight to real gh,
- * and this file passes through defensively for anything it cannot cleanly serve).
- *
- * Two switch modes (see the PHNX-3501 plan):
- *   - `--watch` → EAGER REST: own the poll loop, re-anchored to the live head SHA
- *     each tick, so a superseded run's red can never be reported (PHNX-3042).
- *   - one-shot → LAZY: run real gh first; only translate to REST when it fails with
- *     the exact GraphQL rate-limit signal. An over-budget GraphQL call is rejected
- *     at 0 points, so this is nearly free and never reproduces gh's happy path.
- *
- * Fail-open is the rule: anything not cleanly resolvable (no PR number/URL, an
- * unmappable request) execs real gh rather than returning wrong data.
- */
 import { type RollupItem } from './rest.js';
 interface Parsed {
     realGh: string;
     ghArgs: string[];
 }
-/** Split `--real-gh <path> -- <gh argv>`; defaults realGh to bare `gh`. */
 export declare function parseDelegateArgs(argv: string[]): Parsed;
 export interface Target {
     repo: string;
     number: number;
 }
-/** owner/repo from a git remote URL, or null. */
 export declare function repoFromRemote(remoteUrl: string): string | null;
-/**
- * Resolve `{repo, number}` from the `gh pr checks` argv + cwd, over git/REST only.
- * Returns null (→ caller passes through to real gh) when it can't be resolved
- * cleanly, e.g. no number and no open PR for the current branch.
- */
 export declare function resolveTarget(ghArgs: string[], cwd: string, realGh: string): Promise<Target | null>;
-/** Render one rollup as `gh pr checks`-ish lines (or JSON when asked). */
 export declare function renderRollup(input: RollupItem[], json: boolean): string;
-/**
- * True once CI has settled for this SHA.
- *
- * Check-suites only disambiguate an EMPTY rollup: no checks + no pending suites is
- * "genuinely none" (settled); no checks + a pending suite is "not registered yet"
- * (wait). Once real checks exist we decide on THEM alone and ignore suites — some
- * App integrations (claude/cursor reviewers) register a suite that stays `queued`
- * forever and never posts a run, exactly what `gh pr checks` also ignores.
- */
 export declare function isSettled(rollup: RollupItem[], pendingSuites: number): boolean;
-/** Entry point for the `__gh` early branch in index.ts. */
 export declare function runGhOverload(argv: string[], cwd?: string): Promise<number>;
 export {};

package/dist/lib/github/gh-overload.js

@@ -1,29 +1,8 @@
-/**
- * The delegate behind the `gh` PATH shim (`agents __gh --real-gh <path> -- <argv>`).
- *
- * Agents are statically trained to type `gh pr checks …`; the shim intercepts that
- * habit and routes it here so the rate-limit-prone read runs over REST instead of
- * GraphQL — no new command for an agent to remember. This is the Tier-1 scope:
- * only `gh pr checks` is handled; every other invocation execs the real gh
- * byte-for-byte (the shim already passes non-`pr checks` verbs straight to real gh,
- * and this file passes through defensively for anything it cannot cleanly serve).
- *
- * Two switch modes (see the PHNX-3501 plan):
- *   - `--watch` → EAGER REST: own the poll loop, re-anchored to the live head SHA
- *     each tick, so a superseded run's red can never be reported (PHNX-3042).
- *   - one-shot → LAZY: run real gh first; only translate to REST when it fails with
- *     the exact GraphQL rate-limit signal. An over-budget GraphQL call is rejected
- *     at 0 points, so this is nearly free and never reproduces gh's happy path.
- *
- * Fail-open is the rule: anything not cleanly resolvable (no PR number/URL, an
- * unmappable request) execs real gh rather than returning wrong data.
- */
 import { execFile, spawn } from 'child_process';
 import { promisify } from 'util';
 import { isCiGreen } from './pr-verdict.js';
 import { isRateLimitError, pendingCheckSuites, prHead, rollupForSha } from './rest.js';
 const execFileAsync = promisify(execFile);
-/** Split `--real-gh <path> -- <gh argv>`; defaults realGh to bare `gh`. */
 export function parseDelegateArgs(argv) {
     let realGh = 'gh';
     const rest = [];
@@ -42,18 +21,11 @@ export function parseDelegateArgs(argv) {
     return { realGh, ghArgs: rest };
 }
 const PR_URL = /github\.com\/([^/]+)\/([^/]+)\/pull\/(\d+)/;
-/** owner/repo from a git remote URL, or null. */
 export function repoFromRemote(remoteUrl) {
     const m = remoteUrl.trim().match(/github\.com[:/]([^/]+)\/(.+?)(?:\.git)?$/);
     return m ? `${m[1]}/${m[2]}` : null;
 }
-/**
- * Resolve `{repo, number}` from the `gh pr checks` argv + cwd, over git/REST only.
- * Returns null (→ caller passes through to real gh) when it can't be resolved
- * cleanly, e.g. no number and no open PR for the current branch.
- */
 export async function resolveTarget(ghArgs, cwd, realGh) {
-    // `pr checks <n|url>` — the arg after "checks", if any.
     const idx = ghArgs.indexOf('checks');
     const arg = idx >= 0 ? ghArgs.slice(idx + 1).find((a) => !a.startsWith('-')) : undefined;
     if (arg) {
@@ -67,7 +39,6 @@ export async function resolveTarget(ghArgs, cwd, realGh) {
         }
         return null;
     }
-    // No number: resolve the open PR for the current branch over REST.
     const repo = await repoFromCwd(cwd, ghArgs);
     if (!repo)
         return null;
@@ -89,7 +60,6 @@ export async function resolveTarget(ghArgs, cwd, realGh) {
         return null;
     }
 }
-/** `--repo owner/name` on the argv wins; else derive from cwd's origin remote. */
 async function repoFromCwd(cwd, ghArgs) {
     const ri = ghArgs.indexOf('--repo');
     if (ri >= 0 && ghArgs[ri + 1])
@@ -102,7 +72,6 @@ async function repoFromCwd(cwd, ghArgs) {
         return null;
     }
 }
-/** Env for any real-gh child: mark the shim sentinel + strip color (FORCE_COLOR breaks JSON). */
 function ghChildEnv() {
     const env = { ...process.env };
     env.AGENTS_GH_SHIM = '1';
@@ -113,7 +82,6 @@ function ghChildEnv() {
     delete env.CLICOLOR_FORCE;
     return env;
 }
-/** A REST GhExec bound to the real gh + sentinel env, so it never re-enters the shim. */
 function restExec(realGh) {
     return async (args) => {
         const { stdout } = await execFileAsync(realGh, args, {
@@ -123,7 +91,6 @@ function restExec(realGh) {
         return String(stdout ?? '');
     };
 }
-/** Passthrough: exec real gh inheriting stdio, resolve its exit code. */
 function passthrough(realGh, ghArgs) {
     return new Promise((resolve) => {
         const child = spawn(realGh, ghArgs, { stdio: 'inherit', env: ghChildEnv() });
@@ -131,10 +98,7 @@ function passthrough(realGh, ghArgs) {
         child.on('error', () => resolve(127));
     });
 }
-/** Render one rollup as `gh pr checks`-ish lines (or JSON when asked). */
 export function renderRollup(input, json) {
-    // Sort by name so identical states render identically across polls — otherwise
-    // non-deterministic REST/Map order defeats the watch's change-detection dedup.
     const rollup = [...input].sort((a, b) => a.name.localeCompare(b.name));
     if (json) {
         return JSON.stringify(rollup.map((c) => ({
@@ -152,28 +116,18 @@ export function renderRollup(input, json) {
         .join('\n');
 }
 const NON_TERMINAL = new Set(['IN_PROGRESS', 'QUEUED', 'PENDING', 'WAITING', 'REQUESTED']);
-/**
- * True once CI has settled for this SHA.
- *
- * Check-suites only disambiguate an EMPTY rollup: no checks + no pending suites is
- * "genuinely none" (settled); no checks + a pending suite is "not registered yet"
- * (wait). Once real checks exist we decide on THEM alone and ignore suites — some
- * App integrations (claude/cursor reviewers) register a suite that stays `queued`
- * forever and never posts a run, exactly what `gh pr checks` also ignores.
- */
 export function isSettled(rollup, pendingSuites) {
     if (rollup.length === 0)
         return pendingSuites === 0;
     return rollup.every((c) => !NON_TERMINAL.has((c.conclusion || c.state || c.status || '').toUpperCase()));
 }
 const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
-/** Eager REST watch: poll to a terminal state, re-anchored to the live head SHA. */
 async function watchChecks(target, json, realGh) {
     const gh = restExec(realGh);
-    const deadline = Date.now() + 30 * 60_000; // 30-min guard against a hung matrix
+    const deadline = Date.now() + 30 * 60_000;
     let last = '';
     for (;;) {
-        const head = await prHead(target.repo, target.number, gh); // re-anchor each tick
+        const head = await prHead(target.repo, target.number, gh);
         const [rollup, pending] = await Promise.all([
             rollupForSha(target.repo, head.sha, gh),
             pendingCheckSuites(target.repo, head.sha, gh),
@@ -200,9 +154,7 @@ async function watchChecks(target, json, realGh) {
         await sleep(10_000);
     }
 }
-/** Lazy one-shot: real gh first; translate to REST only on the exact rate-limit signal. */
 async function checksOnce(target, json, realGh, ghArgs) {
-    // Try real gh, capturing output so we can detect the rate-limit signal.
     try {
         const { stdout } = await execFileAsync(realGh, ghArgs, { env: ghChildEnv(), maxBuffer: 16 * 1024 * 1024 });
         process.stdout.write(stdout);
@@ -211,7 +163,6 @@ async function checksOnce(target, json, realGh, ghArgs) {
     catch (err) {
         const e = err;
         if (!isRateLimitError(String(e.stderr ?? ''))) {
-            // A real failure (checks failing, bad flag). Pass gh's own output/exit through.
             if (e.stdout)
                 process.stdout.write(e.stdout);
             if (e.stderr)
@@ -219,7 +170,6 @@ async function checksOnce(target, json, realGh, ghArgs) {
             return typeof e.code === 'number' ? e.code : 1;
         }
     }
-    // Rate-limited: serve from REST if we can resolve the PR, else re-raise real gh.
     if (!target)
         return passthrough(realGh, ghArgs);
     const gh = restExec(realGh);
@@ -228,10 +178,8 @@ async function checksOnce(target, json, realGh, ghArgs) {
     process.stdout.write(renderRollup(rollup, json) + '\n');
     return isCiGreen(rollup) ? 0 : 1;
 }
-/** Entry point for the `__gh` early branch in index.ts. */
 export async function runGhOverload(argv, cwd = process.cwd()) {
     const { realGh, ghArgs } = parseDelegateArgs(argv);
-    // Only `pr checks` is Tier-1. Anything else → real gh, untouched.
     if (ghArgs[0] !== 'pr' || ghArgs[1] !== 'checks')
         return passthrough(realGh, ghArgs);
     const json = ghArgs.includes('--json');
@@ -239,7 +187,7 @@ export async function runGhOverload(argv, cwd = process.cwd()) {
     const target = await resolveTarget(ghArgs, cwd, realGh);
     if (watch) {
         if (!target)
-            return passthrough(realGh, ghArgs); // can't resolve → let real gh try
+            return passthrough(realGh, ghArgs);
         return watchChecks(target, json, realGh);
     }
     return checksOnce(target, json, realGh, ghArgs);

package/dist/lib/github/pr-mergeable.d.ts

@@ -1,48 +1,17 @@
-/**
- * List this user's mergeable PRs across registered project repos.
- *
- * The built-in `pr-merge-on-green` monitor used to run `gh pr list --author @me`
- * with no `--repo`. `gh` then infers the repository from the working directory,
- * and the daemon's cwd is not a git repo, so every poll returned empty.
- *
- * This helper:
- *   1. Collects GitHub slugs from `~/.agents/projects/*.yaml` (`repo` / `repos[].slug`).
- *   2. Canonicalizes each slug (REST `repos/{slug}` — `phnx-labs/agents-cli` lists
- *      nothing; the live name is `phnx-labs/agi-cli`).
- *   3. Runs `gh pr list --repo <slug> --author @me` (cwd-independent).
- *   4. Keeps CI-green PRs with a merge-guard verdict (formal APPROVED review
- *      OR an APPROVE comment on THIS PR).
- *
- * Stdout is a single line of `owner/repo#n` refs (or empty). Empty is a silent
- * observation under `condition.mode: every` — do not write to stderr on the
- * no-match path, or command.ts will treat stderr as the observation and fire.
- */
 import { type ProjectDef } from '../projects.js';
 import { type MergeablePrInput, type StatusCheck } from './pr-verdict.js';
 export type GhExec = (args: string[]) => Promise<string>;
-/** Default runner: `gh` with a 30s timeout. Non-zero exit throws. */
-export declare function ghExec(args: string[]): Promise<string>;
-/** Unique GitHub slugs declared on project definitions. */
+export declare function ghExec(args: string[], opts?: {
+    timeoutMs?: number;
+}): Promise<string>;
 export declare function projectRepoSlugs(defs: readonly ProjectDef[]): string[];
-/**
- * Resolve a slug to GitHub's current `nameWithOwner`. A renamed repo
- * (`phnx-labs/agents-cli` → `phnx-labs/agi-cli`) lists zero PRs under the old
- * name; the REST repo read follows the rename redirect and returns the live one.
- * REST + a 24h gh cache: a rename is rare, and every `projects prs` refresh asks.
- * On error, keep the input slug.
- */
 export declare function canonicalizeRepo(slug: string, gh: GhExec): Promise<string>;
 interface ListedPr {
     number: number;
     reviewDecision?: string | null;
     statusCheckRollup?: StatusCheck[] | null;
 }
-/**
- * Given PRs already listed for one repo, attach verdict payloads only for the
- * CI-green ones that lack a formal APPROVED reviewDecision, then select.
- */
 export declare function selectListedMergeable(repo: string, listed: readonly ListedPr[], gh: GhExec): Promise<MergeablePrInput[]>;
-/** List mergeable `owner/repo#n` refs, space-separated. Empty string if none. */
 export declare function listMergeableRefs(opts?: {
     gh?: GhExec;
     defs?: ProjectDef[];

package/dist/lib/github/pr-mergeable.js

@@ -1,33 +1,8 @@
-/**
- * List this user's mergeable PRs across registered project repos.
- *
- * The built-in `pr-merge-on-green` monitor used to run `gh pr list --author @me`
- * with no `--repo`. `gh` then infers the repository from the working directory,
- * and the daemon's cwd is not a git repo, so every poll returned empty.
- *
- * This helper:
- *   1. Collects GitHub slugs from `~/.agents/projects/*.yaml` (`repo` / `repos[].slug`).
- *   2. Canonicalizes each slug (REST `repos/{slug}` — `phnx-labs/agents-cli` lists
- *      nothing; the live name is `phnx-labs/agi-cli`).
- *   3. Runs `gh pr list --repo <slug> --author @me` (cwd-independent).
- *   4. Keeps CI-green PRs with a merge-guard verdict (formal APPROVED review
- *      OR an APPROVE comment on THIS PR).
- *
- * Stdout is a single line of `owner/repo#n` refs (or empty). Empty is a silent
- * observation under `condition.mode: every` — do not write to stderr on the
- * no-match path, or command.ts will treat stderr as the observation and fire.
- */
 import { execFile } from 'child_process';
 import { promisify } from 'util';
 import { listProjectDefs } from '../projects.js';
 import { formatMergeableRef, hasApproveVerdict, isCiGreen, } from './pr-verdict.js';
 const execFileAsync = promisify(execFile);
-/**
- * `gh --json` is not color-safe when this fleet exports FORCE_COLOR /
- * CLICOLOR_FORCE: gh paints the payload and JSON.parse / jq die on the ANSI
- * prefix (live miss on the sibling poll script). Strip the force vars and
- * pin GH_NO_COLOR for every gh spawn.
- */
 function ghEnv() {
     const env = { ...process.env };
     env.CLICOLOR = '0';
@@ -39,17 +14,15 @@ function ghEnv() {
     delete env.GH_FORCE_TTY;
     return env;
 }
-/** Default runner: `gh` with a 30s timeout. Non-zero exit throws. */
-export async function ghExec(args) {
+export async function ghExec(args, opts = {}) {
     const { stdout } = await execFileAsync('gh', args, {
-        timeout: 30_000,
+        timeout: opts.timeoutMs ?? 30_000,
         maxBuffer: 8 * 1024 * 1024,
         encoding: 'utf-8',
         env: ghEnv(),
     });
     return String(stdout ?? '');
 }
-/** Unique GitHub slugs declared on project definitions. */
 export function projectRepoSlugs(defs) {
     const slugs = new Set();
     for (const d of defs) {
@@ -62,13 +35,6 @@ export function projectRepoSlugs(defs) {
     }
     return [...slugs].sort();
 }
-/**
- * Resolve a slug to GitHub's current `nameWithOwner`. A renamed repo
- * (`phnx-labs/agents-cli` → `phnx-labs/agi-cli`) lists zero PRs under the old
- * name; the REST repo read follows the rename redirect and returns the live one.
- * REST + a 24h gh cache: a rename is rare, and every `projects prs` refresh asks.
- * On error, keep the input slug.
- */
 export async function canonicalizeRepo(slug, gh) {
     try {
         const out = (await gh([
@@ -92,10 +58,6 @@ async function fetchVerdict(repo, number, gh) {
         comments: Array.isArray(comments) ? comments : [],
     };
 }
-/**
- * Given PRs already listed for one repo, attach verdict payloads only for the
- * CI-green ones that lack a formal APPROVED reviewDecision, then select.
- */
 export async function selectListedMergeable(repo, listed, gh) {
     const candidates = [];
     for (const row of listed) {
@@ -118,13 +80,11 @@ export async function selectListedMergeable(repo, listed, gh) {
             candidates.push({ ...base, ...extra });
         }
         catch {
-            // A single PR's reviews/comments probe failed — skip it, keep the rest.
             continue;
         }
     }
     return candidates.filter((pr) => pr.reviewDecision === 'APPROVED' || hasApproveVerdict(pr.reviews, pr.comments));
 }
-/** List mergeable `owner/repo#n` refs, space-separated. Empty string if none. */
 export async function listMergeableRefs(opts) {
     const gh = opts?.gh ?? ghExec;
     const slugs = opts?.repos ?? projectRepoSlugs(opts?.defs ?? listProjectDefs());

package/dist/lib/github/pr-verdict.d.ts

@@ -1,67 +1,23 @@
-/**
- * Non-author PR approval + CI-green checks for merge-on-green.
- *
- * Verdict rules are copied from merge-guard.sh (the PreToolUse hook in
- * phnx-labs/.agents-system `rules/subrules/gh-merge-guard/merge-guard.sh`).
- * That hook accepts EITHER a formal GitHub `APPROVED` review OR an APPROVE
- * verdict comment on THIS PR, and rejects a comment that only cites another
- * PR ("carried from #N" / "APPROVE on #N") — the #2736 laundering pattern.
- *
- * Do not invent a third rule. If the hook's regexes change, change these in
- * the same delivery.
- */
-/** A GitHub pull-request review, shaped after `GET .../pulls/{n}/reviews`. */
 export interface PrReview {
     state?: string;
 }
-/** An issue comment on a PR, shaped after `GET .../issues/{n}/comments`. */
 export interface PrComment {
     body?: string;
 }
-/**
- * One status-check rollup item from `gh pr list --json statusCheckRollup`.
- * `gh` exposes conclusion/state/status under those names; empty fields are
- * pending/in-progress.
- */
 export interface StatusCheck {
     conclusion?: string;
     state?: string;
     status?: string;
 }
-/** One open PR with the fields the mergeable selector reads. */
 export interface MergeablePrInput {
     number: number;
-    /** `owner/repo`. Required so a daemon with no git cwd can still merge. */
     repo: string;
     reviewDecision?: string | null;
     statusCheckRollup?: StatusCheck[] | null;
     reviews?: PrReview[] | null;
     comments?: PrComment[] | null;
 }
-/**
- * True when a non-author verdict exists ON this PR.
- *
- * Mirrors merge-guard.sh: a GitHub review with `state == "APPROVED"`, or an
- * issue comment whose body contains `\bAPPROVE\b` and is not a carried-from
- * citation (`\bcarried\s+(?:over\s+)?from\b` or `\bAPPROVE\s+(?:on|from)\s+#\d+`).
- */
 export declare function hasApproveVerdict(reviews: readonly PrReview[] | null | undefined, comments: readonly PrComment[] | null | undefined): boolean;
-/**
- * True when every check is a terminal success-class conclusion.
- *
- * Matches the built-in monitor's original jq: SUCCESS / NEUTRAL / SKIPPED
- * (ascii-uppercased conclusion, else state, else status). An empty rollup
- * is green — jq `all([])` is true, and a PR with no checks is mergeable
- * from this filter's point of view.
- */
 export declare function isCiGreen(rollup: readonly StatusCheck[] | null | undefined): boolean;
-/**
- * Keep PRs that are CI-green AND non-author-approved.
- *
- * `reviewDecision == "APPROVED"` is sufficient (a formal review). When that
- * field is empty — the fleet convention: reviewers post an APPROVE *comment*
- * rather than a GitHub review — fall through to {@link hasApproveVerdict}.
- */
 export declare function selectMergeablePrs(prs: readonly MergeablePrInput[]): MergeablePrInput[];
-/** `owner/repo#n` — the poll observation the merge action can parse without a cwd. */
 export declare function formatMergeableRef(pr: Pick<MergeablePrInput, 'repo' | 'number'>): string;

package/dist/lib/github/pr-verdict.js

@@ -1,22 +1,3 @@
-/**
- * Non-author PR approval + CI-green checks for merge-on-green.
- *
- * Verdict rules are copied from merge-guard.sh (the PreToolUse hook in
- * phnx-labs/.agents-system `rules/subrules/gh-merge-guard/merge-guard.sh`).
- * That hook accepts EITHER a formal GitHub `APPROVED` review OR an APPROVE
- * verdict comment on THIS PR, and rejects a comment that only cites another
- * PR ("carried from #N" / "APPROVE on #N") — the #2736 laundering pattern.
- *
- * Do not invent a third rule. If the hook's regexes change, change these in
- * the same delivery.
- */
-/**
- * True when a non-author verdict exists ON this PR.
- *
- * Mirrors merge-guard.sh: a GitHub review with `state == "APPROVED"`, or an
- * issue comment whose body contains `\bAPPROVE\b` and is not a carried-from
- * citation (`\bcarried\s+(?:over\s+)?from\b` or `\bAPPROVE\s+(?:on|from)\s+#\d+`).
- */
 export function hasApproveVerdict(reviews, comments) {
     if (Array.isArray(reviews) && reviews.some((r) => r?.state === 'APPROVED')) {
         return true;
@@ -27,7 +8,6 @@ export function hasApproveVerdict(reviews, comments) {
         const body = c?.body ?? '';
         if (!/\bAPPROVE\b/.test(body))
             continue;
-        // A verdict that only points at another PR is laundering, not review.
         if (/\bcarried\s+(?:over\s+)?from\b|\bAPPROVE\s+(?:on|from)\s+#\d+/.test(body)) {
             continue;
         }
@@ -35,14 +15,6 @@ export function hasApproveVerdict(reviews, comments) {
     }
     return false;
 }
-/**
- * True when every check is a terminal success-class conclusion.
- *
- * Matches the built-in monitor's original jq: SUCCESS / NEUTRAL / SKIPPED
- * (ascii-uppercased conclusion, else state, else status). An empty rollup
- * is green — jq `all([])` is true, and a PR with no checks is mergeable
- * from this filter's point of view.
- */
 export function isCiGreen(rollup) {
     const items = rollup ?? [];
     return items.every((c) => {
@@ -50,13 +22,6 @@ export function isCiGreen(rollup) {
         return v === 'SUCCESS' || v === 'NEUTRAL' || v === 'SKIPPED';
     });
 }
-/**
- * Keep PRs that are CI-green AND non-author-approved.
- *
- * `reviewDecision == "APPROVED"` is sufficient (a formal review). When that
- * field is empty — the fleet convention: reviewers post an APPROVE *comment*
- * rather than a GitHub review — fall through to {@link hasApproveVerdict}.
- */
 export function selectMergeablePrs(prs) {
     return prs.filter((pr) => {
         if (!isCiGreen(pr.statusCheckRollup))
@@ -66,7 +31,6 @@ export function selectMergeablePrs(prs) {
         return hasApproveVerdict(pr.reviews, pr.comments);
     });
 }
-/** `owner/repo#n` — the poll observation the merge action can parse without a cwd. */
 export function formatMergeableRef(pr) {
     return `${pr.repo}#${pr.number}`;
 }