@1aboveio/skills 0.10.0

package/skills/engineering/resolve-release/scripts/ensure-target-green.mjs

@@ -0,0 +1,659 @@
+#!/usr/bin/env node
+// ensure-target-green — mechanize the repair lane as a reusable pre-envelope phase (#807).
+//
+// Productizes the prose "repair lane" in SKILL.md + the `target-gate-colour` probe into a
+// named, scripted path:
+//
+//   1. classify failures (required gates only when --gate is set)
+//   2. if all failures ∈ allowlisted classes → open repair unit(s) via resolve-issues brief
+//      else → hand structured human brief (supervised) or block
+//   3. land → re-run target-gate-colour on the NEW tip
+//   4. only then propose/confirm envelope (or resume same attempt)
+//
+// SCOPE: tip check-runs only.
+//   - Live floor / public-host DEAD while CI green → #800 (floorReadiness / rollback-floor)
+//   - Tooling that lies about tip green (stale local main, tag push, blank percent) → #799
+// Do not conflate those with this phase.
+//
+// Modes:
+//   supervised (default)           — classify + structured brief; never auto-opens repair
+//   auto-repair-allowlist          — auto-open repair only when every failure is allowlisted
+//
+// Budget: maxRepairRounds (default 2) + wallClockMinutes (default 60) so permanent flakes
+// cannot thrash forever.
+//
+// JSON contract:
+//   { state: green|repairing|blocked|unknown, headSha, failing[{name,conclusion,class,allowlisted}],
+//     repair?, reprobe?, brief?, override?, attempts[], startedAt, finishedAt, durationMs }
+//
+// Manifest: release.ensureGreen = { startedAt, attempts[], finalHead, outcome, failingClasses[],
+//                                   repairPrs[], durationMs }
+
+import { execFileSync } from 'node:child_process'
+import { readFileSync } from 'node:fs'
+import { isMainModule } from '../../engineering-runtime/scripts/main-module.mjs'
+
+export const STATES = {
+  GREEN: 'green',
+  REPAIRING: 'repairing',
+  BLOCKED: 'blocked',
+  UNKNOWN: 'unknown',
+}
+
+export const MODES = {
+  SUPERVISED: 'supervised',
+  AUTO_REPAIR_ALLOWLIST: 'auto-repair-allowlist',
+}
+
+export const DEFAULT_MAX_REPAIR_ROUNDS = 2
+export const DEFAULT_WALL_CLOCK_MINUTES = 60
+
+/**
+ * Repo-declared allowlist / never-auto map. Callers may override via --classify-config.
+ * Order matters: first match wins. Critical / hazard patterns must outrank flake heuristics.
+ */
+export const DEFAULT_CLASSIFY_CONFIG = {
+  optionalGates: [],
+  // Never auto without human — checked first.
+  neverAuto: [
+    { class: 'critical', pattern: /auth|authz|session|oauth|token|cookie|password|credential/i },
+    { class: 'critical', pattern: /money|payment|billing|tax|pricing|invoice|ledger|refund/i },
+    { class: 'critical', pattern: /tenant|tenancy|org[-_]?scope|multi[-_]?tenant/i },
+    { class: 'critical', pattern: /migrat|schema\.prisma|prisma migrate|alembic|flyway/i },
+    { class: 'critical', pattern: /post[-_]?deploy|prod[-_]?active|smoke|production/i },
+    { class: 'critical', pattern: /release[-_]?readiness|green[-_]?gate|traffic shift|expose/i },
+  ],
+  allowlist: [
+    { class: 'flake', pattern: /flak|intermittent|order.?dependent|race.?condition|retry/i },
+    { class: 'digest-drift', pattern: /contentDigest|digest drift|workflow.?digest|distribution/i },
+    { class: 'external-fetch', pattern: /ECONNRESET|ETIMEDOUT|ENOTFOUND|registry\.npmjs|fetch failed|network/i },
+    { class: 'missing-optional', pattern: /reported no check-run|absent check/i, onlyOptionalGate: true },
+  ],
+}
+
+/** Terminal conclusions that may count as green. Anything else is not-green. */
+export const ALLOWED_TERMINAL_CONCLUSIONS = new Set(['SUCCESS', 'SKIPPED', 'NEUTRAL'])
+
+/**
+ * A check is blocking when it is not completed with an allowed terminal conclusion.
+ * GitHub stores in-progress conclusions as null (fetchTip normalizes to ""); those
+ * must not silent-green. When `status` is present and not COMPLETED, block even if
+ * a conclusion string looks terminal.
+ */
+export function isCheckBlocking(check) {
+  if (!check) return true
+  const conclusion = String(check.conclusion || '').toUpperCase()
+  const status = String(check.status || '').toUpperCase()
+  if (status && status !== 'COMPLETED') return true
+  if (!ALLOWED_TERMINAL_CONCLUSIONS.has(conclusion)) return true
+  return false
+}
+
+export function classifyFailure(check, config = DEFAULT_CLASSIFY_CONFIG) {
+  const name = String(check?.name || '')
+  const status = String(check?.status || '')
+  const rawConclusion = String(check?.conclusion || '')
+  // Present but incomplete checks often have conclusion:"" — surface status so briefs are readable.
+  const conclusion = rawConclusion
+    || (status && status.toUpperCase() !== 'COMPLETED' ? status : rawConclusion)
+    || 'PENDING'
+  const output = String(check?.output || check?.detail || '')
+  const text = `${name}\n${output}\n${conclusion}\n${status}`
+  const optionalGates = Array.isArray(config.optionalGates) ? config.optionalGates : []
+
+  for (const rule of config.neverAuto || []) {
+    if (rule.pattern.test(text)) {
+      return {
+        name,
+        conclusion,
+        status,
+        class: rule.class || 'critical',
+        allowlisted: false,
+      }
+    }
+  }
+
+  for (const rule of config.allowlist || []) {
+    if (!rule.pattern.test(text)) continue
+    if (rule.onlyOptionalGate) {
+      if (optionalGates.includes(name)) {
+        return { name, conclusion, status, class: rule.class, allowlisted: true }
+      }
+      // Missing *required* gate is critical, never allowlisted.
+      return { name, conclusion, status, class: 'critical', allowlisted: false }
+    }
+    return { name, conclusion, status, class: rule.class, allowlisted: true }
+  }
+
+  return { name, conclusion, status, class: 'unknown', allowlisted: false }
+}
+
+/**
+ * Classify every failing, incomplete, or missing-required check on the tip.
+ * A required check that is present but still in progress is blocked/not-green —
+ * never silent green on an empty conclusion.
+ */
+export function classifyFailures({ checks, gates = [], config = DEFAULT_CLASSIFY_CONFIG } = {}) {
+  if (!Array.isArray(checks)) return []
+  const relevant = gates.length > 0 ? checks.filter((c) => gates.includes(c.name)) : checks
+  const failing = relevant.filter((c) => isCheckBlocking(c))
+  // Missing required gates also count as failures.
+  if (gates.length > 0) {
+    for (const g of gates) {
+      if (!checks.some((c) => c.name === g)) {
+        failing.push({
+          name: g,
+          conclusion: 'MISSING',
+          status: '',
+          output: 'required gate(s) reported no check-run on the target head',
+        })
+      }
+    }
+  }
+  return failing.map((c) => classifyFailure(c, config))
+}
+
+/**
+ * Core ensure path. All I/O is injectable so tests never hit the network.
+ *
+ * @param {object} opts
+ * @param {string|null} opts.headSha
+ * @param {Array|null} opts.checks
+ * @param {boolean} opts.readable
+ * @param {string[]} [opts.gates]
+ * @param {object} [opts.config]
+ * @param {'supervised'|'auto-repair-allowlist'} [opts.mode]
+ * @param {number} [opts.maxRepairRounds]
+ * @param {number} [opts.wallClockMinutes]
+ * @param {{recorded:boolean,by?:string,reason?:string}|null} [opts.humanOverride]
+ * @param {(brief:object)=>Promise<object>} opts.openRepair  mockable resolve-issues handoff
+ * @param {()=>Promise<{headSha,checks,readable}>} opts.reProbe  mandatory re-probe after repair
+ * @param {()=>number} [opts.now]  ms since epoch (test clock)
+ */
+export async function ensureTargetGreen(opts = {}) {
+  const {
+    headSha = null,
+    checks = null,
+    readable = true,
+    gates = [],
+    config = DEFAULT_CLASSIFY_CONFIG,
+    mode = MODES.SUPERVISED,
+    maxRepairRounds = DEFAULT_MAX_REPAIR_ROUNDS,
+    wallClockMinutes = DEFAULT_WALL_CLOCK_MINUTES,
+    humanOverride = null,
+    openRepair,
+    reProbe,
+    now = () => Date.now(),
+  } = opts
+
+  const startedAtMs = now()
+  const startedAt = new Date(startedAtMs).toISOString()
+  const deadline = startedAtMs + wallClockMinutes * 60_000
+  const attempts = []
+
+  const finish = (partial) => {
+    const finishedAtMs = now()
+    return {
+      ...partial,
+      startedAt,
+      finishedAt: new Date(finishedAtMs).toISOString(),
+      durationMs: finishedAtMs - startedAtMs,
+      attempts,
+    }
+  }
+
+  // Explicit human override recorded on the envelope may green without tip green.
+  if (humanOverride && humanOverride.recorded) {
+    attempts.push({ round: 0, state: STATES.GREEN, via: 'human-override' })
+    return finish({
+      state: STATES.GREEN,
+      headSha,
+      failing: [],
+      override: humanOverride,
+      reprobe: { required: false, skipped: 'human-override' },
+    })
+  }
+
+  if (!readable || !Array.isArray(checks)) {
+    attempts.push({ round: 0, state: STATES.UNKNOWN })
+    return finish({
+      state: STATES.UNKNOWN,
+      headSha,
+      failing: [],
+      brief: {
+        reason: 'unread-check-runs',
+        detail: 'the target branch check-runs could not be read — unknown is not green (#807 / principle 13)',
+      },
+    })
+  }
+
+  // classifyFailures is the source of truth for green — includes present-but-incomplete
+  // required gates (empty conclusion / non-COMPLETED status), not only terminal failures.
+  let currentHead = headSha
+  let currentChecks = checks
+  let failing = classifyFailures({ checks: currentChecks, gates, config })
+
+  if (failing.length === 0) {
+    attempts.push({ round: 0, state: STATES.GREEN, headSha: currentHead })
+    return finish({
+      state: STATES.GREEN,
+      headSha: currentHead,
+      failing: [],
+    })
+  }
+
+  // Tip red.
+  attempts.push({
+    round: 0,
+    state: STATES.BLOCKED,
+    headSha: currentHead,
+    failingClasses: failing.map((f) => f.class),
+  })
+
+  const allAllowlisted = failing.every((f) => f.allowlisted)
+
+  if (mode !== MODES.AUTO_REPAIR_ALLOWLIST) {
+    return finish({
+      state: STATES.BLOCKED,
+      headSha: currentHead,
+      failing,
+      brief: {
+        reason: 'supervised-mode',
+        strategy: 'resolve-issues',
+        failing,
+        detail:
+          'tip is red; supervised mode hands a structured brief and holds the lease — do not auto-fix. ' +
+          'Re-run ensure-target-green after repair lands, or pass humanOverride on the envelope.',
+      },
+    })
+  }
+
+  if (!allAllowlisted) {
+    return finish({
+      state: STATES.BLOCKED,
+      headSha: currentHead,
+      failing,
+      brief: {
+        reason: 'non-allowlisted-failure',
+        strategy: 'human',
+        failing,
+        detail:
+          'at least one failure is critical/unknown — never auto-repair without a human ' +
+          '(auth/money/tenancy/migration, critical release gate, unknown class)',
+      },
+    })
+  }
+
+  // Allowlisted under auto-repair-allowlist: open repair, re-probe, loop under budget.
+  if (typeof openRepair !== 'function' || typeof reProbe !== 'function') {
+    return finish({
+      state: STATES.BLOCKED,
+      headSha: currentHead,
+      failing,
+      brief: {
+        reason: 'missing-handoff-seam',
+        detail: 'openRepair and reProbe seams are required for the auto-repair path',
+      },
+    })
+  }
+
+  let lastRepair = null
+  let lastReprobe = null
+  for (let round = 1; round <= maxRepairRounds; round += 1) {
+    if (now() > deadline) {
+      return finish({
+        state: STATES.BLOCKED,
+        headSha: currentHead,
+        failing,
+        repair: lastRepair,
+        reprobe: { required: true, ...(lastReprobe || {}) },
+        brief: {
+          reason: 'repair-budget-exhausted',
+          detail: `wall-clock budget of ${wallClockMinutes}m exhausted after ${round - 1} repair round(s)`,
+        },
+      })
+    }
+
+    const brief = {
+      strategy: 'resolve-issues',
+      headSha: currentHead,
+      failing,
+      lease: 'held', // same release attempt lease throughout
+      note: 'repair inside the attempt; do not open a second release behind it',
+    }
+    attempts.push({ round, state: STATES.REPAIRING, headSha: currentHead })
+    lastRepair = await openRepair(brief)
+    // Re-probe is mandatory after repair lands — never claim green on the old tip.
+    lastReprobe = await reProbe()
+    currentHead = lastReprobe?.headSha ?? currentHead
+    currentChecks = lastReprobe?.checks
+    const reReadable = lastReprobe?.readable !== false && Array.isArray(currentChecks)
+
+    if (!reReadable) {
+      attempts.push({ round, state: STATES.UNKNOWN, headSha: currentHead, phase: 'reprobe' })
+      return finish({
+        state: STATES.UNKNOWN,
+        headSha: currentHead,
+        failing,
+        repair: lastRepair,
+        reprobe: { required: true, readable: false },
+        brief: {
+          reason: 'reprobe-unread',
+          detail: 're-probe could not read check-runs on the new tip — unknown is not green',
+        },
+      })
+    }
+
+    failing = classifyFailures({ checks: currentChecks, gates, config })
+    if (failing.length === 0) {
+      attempts.push({ round, state: STATES.GREEN, headSha: currentHead, phase: 'reprobe' })
+      return finish({
+        state: STATES.GREEN,
+        headSha: currentHead,
+        failing: [],
+        repair: lastRepair,
+        reprobe: { required: true, headSha: currentHead, state: STATES.GREEN },
+      })
+    }
+
+    attempts.push({
+      round,
+      state: STATES.BLOCKED,
+      headSha: currentHead,
+      phase: 'reprobe',
+      failingClasses: failing.map((f) => f.class),
+    })
+
+    // Still red — only continue if still fully allowlisted.
+    if (!failing.every((f) => f.allowlisted)) {
+      return finish({
+        state: STATES.BLOCKED,
+        headSha: currentHead,
+        failing,
+        repair: lastRepair,
+        reprobe: { required: true, headSha: currentHead, state: STATES.BLOCKED },
+        brief: {
+          reason: 'non-allowlisted-failure',
+          failing,
+          detail: 're-probe still red with a non-allowlisted class — hand to human',
+        },
+      })
+    }
+  }
+
+  return finish({
+    state: STATES.BLOCKED,
+    headSha: currentHead,
+    failing,
+    repair: lastRepair,
+    reprobe: { required: true, ...(lastReprobe ? { headSha: lastReprobe.headSha } : {}) },
+    brief: {
+      reason: 'repair-budget-exhausted',
+      detail: `maxRepairRounds=${maxRepairRounds} exhausted; tip still red — permanent flake cannot thrash forever`,
+    },
+  })
+}
+
+/** Write release.ensureGreen onto a manifest (pure). */
+export function recordEnsureGreen(manifest, result) {
+  const m = structuredClone(manifest || {})
+  if (!m.release || typeof m.release !== 'object') m.release = {}
+  m.release.ensureGreen = {
+    startedAt: result.startedAt,
+    finishedAt: result.finishedAt,
+    durationMs: result.durationMs,
+    attempts: result.attempts || [],
+    finalHead: result.headSha || null,
+    outcome: result.state,
+    failingClasses: (result.failing || []).map((f) => f.class),
+    repairPrs: result.repair?.prs || [],
+    repairIssues: result.repair?.issues || [],
+    override: result.override || null,
+  }
+  return m
+}
+
+export function parseArgs(argv) {
+  const args = {
+    gates: [],
+    mode: MODES.SUPERVISED,
+    maxRepairRounds: DEFAULT_MAX_REPAIR_ROUNDS,
+    wallClockMinutes: DEFAULT_WALL_CLOCK_MINUTES,
+  }
+  for (let i = 0; i < argv.length; i += 1) {
+    const a = argv[i]
+    if (a === '--repo') args.repo = argv[++i]
+    else if (a === '--target-branch') args.targetBranch = argv[++i]
+    else if (a === '--gate') args.gates.push(argv[++i])
+    else if (a === '--classify-config') args.classifyConfig = argv[++i]
+    else if (a === '--mode') args.mode = argv[++i]
+    else if (a === '--max-repair-rounds') args.maxRepairRounds = Number(argv[++i])
+    else if (a === '--wall-clock-minutes') args.wallClockMinutes = Number(argv[++i])
+    else if (a === '--json') args.json = true
+    else if (a === '--help' || a === '-h') args.help = true
+    else if (a === '--dry-classify') args.dryClassify = true
+    else if (a.startsWith('-')) {
+      // Keep the first unknown flag token (not a following value) so --gat x reports --gat.
+      if (!args.unknown) args.unknown = a
+    } else if (!args.unknown) {
+      // No positionals on this CLI — bare junk is also a usage error (exit 2).
+      args.unknown = a
+    }
+  }
+  return args
+}
+
+function help() {
+  return `ensure-target-green — tip check-runs repair phase (#807)
+
+Standalone surface (Option 4). Classifies target-branch tip failures, optionally
+opens allowlisted repair work via a resolve-issues brief, re-probes the NEW tip,
+and only then reports green so the release envelope can proceed.
+
+Usage:
+  node …/ensure-target-green.mjs \\
+    --repo <owner/name> --target-branch <prod> \\
+    [--gate <check-name>…] \\
+    [--classify-config <path>] \\
+    [--mode supervised|auto-repair-allowlist] \\
+    [--max-repair-rounds <n>] \\
+    [--wall-clock-minutes <n>] \\
+    [--json] [--dry-classify]
+
+Modes:
+  supervised (default)       classify + structured brief; never auto-opens repair
+  auto-repair-allowlist      open repair only when every failure is allowlisted
+
+Exit codes:
+  0  state=green
+  1  state=blocked|repairing|unknown  (not green — do not confirm envelope)
+  2  usage error
+
+Non-overlap:
+  · tip check-runs only — live floor / public-host DEAD is #800 (floorReadiness)
+  · true remote tip / tag-push / blank-percent honesty is #799
+  · never skip/weaken required gates; never claim green on a different SHA
+  · never stuff tip repairs into the promotion PR
+
+JSON: { state, headSha, failing[{name,conclusion,class,allowlisted}], repair?, reprobe?, brief? }`
+}
+
+const safeJson = (t) => { try { return JSON.parse(t) } catch { return null } }
+
+/** owner/name only — rejects shell metacharacters before any process spawn. */
+export const REPO_NAME_RE = /^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/
+
+export function isValidRepo(repo) {
+  return REPO_NAME_RE.test(String(repo || ''))
+}
+
+/**
+ * Invoke `gh api` via argv (never /bin/sh -c). Path segments are validated/
+ * encoded so operator- or orchestrator-supplied --repo cannot inject shell.
+ */
+function ghApi({ path, jq, timeout = 60_000 } = {}) {
+  try {
+    const args = ['api', path]
+    if (jq != null) args.push('--jq', jq)
+    const stdout = execFileSync('gh', args, {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'pipe'],
+      timeout,
+    })
+    return { ok: true, stdout, stderr: '' }
+  } catch (error) {
+    return {
+      ok: false,
+      stdout: error.stdout?.toString?.() || '',
+      stderr: error.stderr?.toString?.() || error.message || '',
+    }
+  }
+}
+
+function loadConfig(path) {
+  if (!path) return DEFAULT_CLASSIFY_CONFIG
+  const raw = JSON.parse(readFileSync(path, 'utf8'))
+  // Patterns arrive as strings in JSON; compile them.
+  const compile = (rules = []) => rules.map((r) => ({
+    ...r,
+    pattern: r.pattern instanceof RegExp ? r.pattern : new RegExp(r.pattern, r.flags || 'i'),
+  }))
+  return {
+    optionalGates: raw.optionalGates || [],
+    neverAuto: compile(raw.neverAuto || DEFAULT_CLASSIFY_CONFIG.neverAuto.map((r) => ({
+      class: r.class,
+      pattern: r.pattern.source,
+      flags: r.pattern.flags,
+    }))),
+    allowlist: compile(raw.allowlist || DEFAULT_CLASSIFY_CONFIG.allowlist.map((r) => ({
+      class: r.class,
+      pattern: r.pattern.source,
+      flags: r.pattern.flags,
+      onlyOptionalGate: r.onlyOptionalGate,
+    }))),
+  }
+}
+
+/**
+ * Fetch tip SHA + check-runs without a shell. Repo must be owner/name;
+ * branch is a single path segment (URI-encoded), never interpolated into sh -c.
+ * Exported for regression tests that assert argv form / validation.
+ */
+export function fetchTip({ repo, targetBranch, api = ghApi } = {}) {
+  if (!isValidRepo(repo)) {
+    return {
+      headSha: null,
+      checks: null,
+      readable: false,
+      error: `invalid --repo ${repo}; expected owner/name`,
+    }
+  }
+  const branch = encodeURIComponent(String(targetBranch || ''))
+  const sha = api({ path: `repos/${repo}/commits/${branch}`, jq: '.sha' })
+  const checks = api({
+    path: `repos/${repo}/commits/${branch}/check-runs`,
+    jq: '[.check_runs[] | {name: .name, status: (.status // ""), conclusion: (.conclusion // ""), output: ((.output.summary // "") + " " + (.output.title // ""))}]',
+  })
+  return {
+    headSha: sha.ok ? String(sha.stdout || '').trim() : null,
+    checks: checks.ok ? safeJson(checks.stdout) : null,
+    readable: sha.ok && checks.ok,
+  }
+}
+
+/**
+ * Default openRepair: emit a structured resolve-issues brief to stdout/stderr and return
+ * a handoff record. Real spawn is the caller's job (agent / resolve-release phase); this
+ * seam is deliberately mockable and does not nest an orchestrator in v1.
+ */
+export async function defaultOpenRepair(brief) {
+  // Structured brief the agent (or resolve-issues) consumes. We do not auto-merge anything.
+  return {
+    opened: true,
+    strategy: 'resolve-issues',
+    brief,
+    issues: [],
+    prs: [],
+    note: 'structured brief ready — open/land repair via resolve-issues while the release lease is held; re-probe before resume',
+  }
+}
+
+export async function runCli(argv) {
+  const args = parseArgs(argv)
+  if (args.help) {
+    console.log(help())
+    return 0
+  }
+  // Fail closed on any unknown flag BEFORE fetchTip/classification — a mistyped
+  // --gate / --classify-config must never silently skip the required-gate check
+  // or fall back to the default allowlist (exit 2 usage contract).
+  if (args.unknown) {
+    console.error(`ensure-target-green: unknown flag ${args.unknown} (see --help)`)
+    return 2
+  }
+  if (!args.repo || !args.targetBranch) {
+    console.error(help())
+    return 2
+  }
+  if (!isValidRepo(args.repo)) {
+    console.error(`ensure-target-green: invalid --repo ${args.repo}; expected owner/name`)
+    return 2
+  }
+  if (args.mode && !Object.values(MODES).includes(args.mode)) {
+    console.error(`unknown --mode ${args.mode}; expected ${Object.values(MODES).join('|')}`)
+    return 2
+  }
+
+  const config = loadConfig(args.classifyConfig)
+  const tip = fetchTip({ repo: args.repo, targetBranch: args.targetBranch })
+
+  if (args.dryClassify) {
+    const failing = tip.readable
+      ? classifyFailures({ checks: tip.checks, gates: args.gates, config })
+      : []
+    const out = {
+      state: !tip.readable ? STATES.UNKNOWN : failing.length === 0 ? STATES.GREEN : STATES.BLOCKED,
+      headSha: tip.headSha,
+      failing,
+    }
+    console.log(JSON.stringify(out, null, 2))
+    return out.state === STATES.GREEN ? 0 : 1
+  }
+
+  // Live CLI: supervised by default — classify + brief. Auto-repair opens a structured
+  // handoff but does not itself wait for land (the release agent holds the lease and
+  // re-invokes after repair lands, or supplies injectable seams when embedding).
+  const result = await ensureTargetGreen({
+    headSha: tip.headSha,
+    checks: tip.checks,
+    readable: tip.readable,
+    gates: args.gates,
+    config,
+    mode: args.mode,
+    maxRepairRounds: args.maxRepairRounds,
+    wallClockMinutes: args.wallClockMinutes,
+    openRepair: defaultOpenRepair,
+    reProbe: async () => fetchTip({ repo: args.repo, targetBranch: args.targetBranch }),
+  })
+
+  if (args.json) console.log(JSON.stringify(result, null, 2))
+  else {
+    console.log(`state=${result.state} head=${result.headSha || '(unknown)'}`)
+    if (result.failing?.length) {
+      for (const f of result.failing) {
+        console.log(`  failing: ${f.name}=${f.conclusion} class=${f.class} allowlisted=${f.allowlisted}`)
+      }
+    }
+    if (result.brief) console.log(`  brief: ${result.brief.reason} — ${result.brief.detail || ''}`)
+    if (result.repair) console.log(`  repair: strategy=${result.repair.strategy || 'resolve-issues'}`)
+    if (result.reprobe) console.log(`  reprobe: required=${result.reprobe.required !== false}`)
+    console.log(`  durationMs=${result.durationMs}`)
+  }
+  return result.state === STATES.GREEN ? 0 : 1
+}
+
+if (isMainModule(import.meta.url)) {
+  runCli(process.argv.slice(2)).then((code) => {
+    process.exitCode = code
+  })
+}