argus-reviewer-e2e 0.1.3 → 0.2.0

package/README.md

@@ -4,6 +4,13 @@
   <img src="docs/assets/social.png" alt="Argus — vision-model E2E testing" width="640" />
 </p>
 
+<p align="center">
+  <a href="https://www.npmjs.com/package/argus-reviewer-e2e"><img src="https://img.shields.io/npm/v/argus-reviewer-e2e" alt="npm version" /></a>
+  <a href="https://github.com/duketopceo/Argus/actions/workflows/ci.yml"><img src="https://github.com/duketopceo/Argus/actions/workflows/ci.yml/badge.svg" alt="CI" /></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue" alt="MIT license" /></a>
+  <a href="https://github.com/duketopceo/Argus/security/policy"><img src="https://img.shields.io/badge/security-policy-orange" alt="security policy" /></a>
+</p>
+
 Open-source, self-hosted vision-model E2E testing — the hundred-eyed watcher for your UI. Bring your own `OPENROUTER_API_KEY`: record a flow once, fingerprint-cache every step, replay near-free, heal on UI drift, and get results as a check + comment on the GitHub PR.
 
 - **Vision-first**: a model looks at a screenshot and decides where to click — no selectors to write or maintain.
@@ -41,7 +48,10 @@ export default {
 
 The GitHub Action automatically sets `ARGUS_REVIEWER_TRACE` with the repository, PR number, commit, and run id, so every PR review is attributed in OpenRouter without extra config. You can also set `ARGUS_REVIEWER_TRACE` yourself (JSON object) to add more fields.
 
-Status: early development. See `action/` for the composite GitHub Action and `runner/` for self-hosted runner registration.
+Status: early development. See `action/` for the composite GitHub Action,
+`runner/` for self-hosted runner registration, `docs/quickstart.md` for
+setup, `SECURITY.md` for the threat model, and `CONTRIBUTING.md` to hack
+on it.
 
 ## File structure
 
@@ -53,10 +63,14 @@ argus-reviewer/
 ├── runner/                  # Self-hosted runner registration docs + script
 │   ├── README.md
 │   └── register-runner.sh
+├── electron/                # Local observability dashboard (`npm run app`)
 ├── src/
 │   ├── api.ts               # Test-facing `test`/`td` API + generated test file renderer
-│   ├── cli.ts               # `record`, `run`, and `cache` commands
+│   ├── cli.ts               # record · run · code-review · delegate · cache · index · init
 │   ├── config.ts            # `argus-reviewer.config.*` loader (legacy `vision-e2e.config.*` accepted)
+│   ├── cache/
+│   │   ├── fingerprint.ts   # Per-step screenshot/a11y fingerprint + resolve
+│   │   └── store.ts         # Flow cache read/write
 │   ├── driver/
 │   │   ├── browser.ts       # Playwright browser launch (chromium/firefox/webkit) + observation capture
 │   │   └── target.ts        # Optional local dev-server target process
@@ -64,9 +78,19 @@ argus-reviewer/
 │   │   ├── actions.ts       # Low-level page actions (click, type, scroll, …)
 │   │   ├── loop.ts          # Vision model record/replay + healing loop
 │   │   └── prompts.ts       # OpenRouter action/assertion prompts + JSON schemas
-│   ├── cache/
-│   │   ├── fingerprint.ts   # Per-step screenshot/a11y fingerprint + resolve
-│   │   └── store.ts         # Flow cache read/write
+│   ├── evidence/
+│   │   ├── ci.ts            # PR metadata + CI check-run context for findings
+│   │   ├── gate.ts          # Fork-PR trust gate (argus-probe label bound to head SHA)
+│   │   └── link.ts          # Finding → evidence linkage + comment-safe sanitization
+│   ├── executor/
+│   │   ├── a0.ts            # `a0 headless -p` delegation to a user's Agent Zero instance
+│   │   └── sandbox.ts       # Hardened Docker runner for generated probes
+│   ├── index/               # Repo index, diff context, cache invalidation
+│   ├── journal/             # Per-run structured journal entries
+│   ├── probe/
+│   │   ├── author.ts        # Model-authored regression probe generation + validation
+│   │   ├── harness.ts       # vitest/jest/node:test detection + TAP classification
+│   │   └── queue.ts         # Head-vs-merge-base probe orchestration
 │   ├── report/
 │   │   ├── comment.ts       # Markdown PR comment + commit-status rendering
 │   │   ├── junit.ts         # JUnit XML output

package/action/action.yml

@@ -46,6 +46,14 @@ inputs:
     description: Enable the B.2 probe lane — authored test probes for unexercised findings run in a hardened Docker container (no network, no secrets, read-only fs). Enable-only — 'false' does not override a config-enabled lane. Requires Docker on the runner; forced off on pull_request_target.
     default: 'false'
     required: false
+  max-comments:
+    description: Cap on inline review comments posted per run; overflow is summarized in the sticky. Overrides review.maxComments when set.
+    default: ''
+    required: false
+  run:
+    description: Run the browser-flow lane (`argus-reviewer run`). Set 'false' for code-review-only consumers — repos without a per-PR web target (CLIs, libraries, infra repos). Skips the Playwright install and run steps; the sticky comment and commit status then reflect code-review alone.
+    default: 'true'
+    required: false
 outputs:
   conclusion:
     description: 'Run conclusion: success, failure, or neutral'
@@ -65,6 +73,7 @@ runs:
       run: npm ci
 
     - name: Install Playwright browser
+      if: inputs.run != 'false'
       shell: bash
       working-directory: ${{ inputs.working-directory }}
       env:
@@ -93,6 +102,10 @@ runs:
       if: inputs.index == 'true'
       shell: bash
       working-directory: ${{ inputs.working-directory }}
+      env:
+        # Token only feeds trust resolution on issue_comment events —
+        # pull_request* events read fork status from the event payload.
+        GITHUB_TOKEN: ${{ github.token }}
       run: ${{ inputs.cli }} index
 
     - name: Run argus-reviewer code review
@@ -104,6 +117,7 @@ runs:
         OPENROUTER_API_KEY: ${{ inputs.openrouter-api-key }}
         GITHUB_TOKEN: ${{ github.token }}
         ARGUS_SANDBOX: ${{ inputs.sandbox == 'true' && '1' || '' }}
+        ARGUS_MAX_COMMENTS: ${{ inputs.max-comments }}
         ARGUS_DEBUG: '1'
         ARGUS_REVIEWER_TRACE: >-
           {"repo":"${{ github.repository }}",
@@ -116,11 +130,13 @@ runs:
 
     - name: Run argus-reviewer
       id: run
+      if: inputs.run != 'false'
       shell: bash
       working-directory: ${{ inputs.working-directory }}
       continue-on-error: true
       env:
         OPENROUTER_API_KEY: ${{ inputs.openrouter-api-key }}
+        GITHUB_TOKEN: ${{ github.token }}
         ARGUS_DEBUG: '1'
         ARGUS_DIFF_BASE: ${{ inputs.diff-base }}
         ARGUS_BUDGET_USD: ${{ inputs.budget-usd }}
@@ -140,6 +156,7 @@ runs:
         OPENROUTER_API_KEY: ${{ inputs.openrouter-api-key }}
         VISION_E2E_WORKING_DIR: ${{ inputs.working-directory }}
         ARGUS_REPORT_DIR: ${{ inputs.report-dir }}
+        ARGUS_RUN_DISABLED: ${{ inputs.run == 'false' && '1' || '' }}
       with:
         github-token: ${{ github.token }}
         script: |

package/action/sticky-comment.mjs

@@ -11,7 +11,10 @@ function formatUsd(n) {
 
 /** Escape a report string for one markdown table cell. */
 function cell(s) {
-  return String(s ?? '').replace(/\|/g, '\\|').replace(/[\r\n]+/g, ' ').slice(0, 200)
+  return String(s ?? '')
+    .replace(/\|/g, '\\|')
+    .replace(/[\r\n]+/g, ' ')
+    .slice(0, 200)
 }
 
 function renderMissingKeyBody() {
@@ -20,7 +23,9 @@ function renderMissingKeyBody() {
   lines.push('')
   lines.push('## argus-reviewer ⚪ skipped')
   lines.push('')
-  lines.push('`OPENROUTER_API_KEY` is not configured. Add it as a repository or workflow secret to run argus-reviewer.')
+  lines.push(
+    '`OPENROUTER_API_KEY` is not configured. Add it as a repository or workflow secret to run argus-reviewer.',
+  )
   lines.push('')
   lines.push('This status is intentionally neutral, not a failure.')
   lines.push('')
@@ -33,14 +38,16 @@ function renderNoReportBody(reportDir, runUrl) {
   lines.push('')
   lines.push('## argus-reviewer ⚠️ no report')
   lines.push('')
-  lines.push(`The run step produced no \`run.json\` under \`${reportDir}\`. The commit status fails closed — check the action logs before merging.`)
+  lines.push(
+    `The run step produced no \`run.json\` under \`${reportDir}\`. The commit status fails closed — check the action logs before merging.`,
+  )
   lines.push('')
   lines.push(`[View run](${runUrl})`)
   lines.push('')
   return lines.join('\n')
 }
 
-function renderBody(report, codeReview, runUrl, ok) {
+function renderBody(report, codeReview, runUrl, ok, inlinePlan) {
   if (!report) return renderMissingKeyBody()
 
   const lines = []
@@ -73,7 +80,9 @@ function renderBody(report, codeReview, runUrl, ok) {
     lines.push(`- \`${path.basename(t.file)}\` — ${t.name}`)
   }
   lines.push('')
-  lines.push(`**Risk:** ${ok ? 'Low — UI regression tests and code review passed; no heals or failures.' : 'High — investigate failures before merge.'}`)
+  lines.push(
+    `**Risk:** ${ok ? 'Low — UI regression tests and code review passed; no heals or failures.' : 'High — investigate failures before merge.'}`,
+  )
   lines.push('')
   if (Object.keys(trace).length > 0) {
     lines.push('**Trace**')
@@ -92,7 +101,9 @@ function renderBody(report, codeReview, runUrl, ok) {
   lines.push('| --- | --- | ---: | ---: | ---: | ---: |')
   for (const t of report.tests) {
     const result = t.ok ? '✅ pass' : '❌ fail'
-    lines.push(`| ${t.name} | ${result} | ${t.visionCalls} | ${formatUsd(t.visionCostUsd)} | ${t.healEvents?.length ?? 0} | ${t.asserts?.length ?? 0} |`)
+    lines.push(
+      `| ${t.name} | ${result} | ${t.visionCalls} | ${formatUsd(t.visionCostUsd)} | ${t.healEvents?.length ?? 0} | ${t.asserts?.length ?? 0} |`,
+    )
   }
   lines.push('')
   lines.push('</details>')
@@ -178,14 +189,24 @@ function renderBody(report, codeReview, runUrl, ok) {
   lines.push('')
   lines.push('| Check | Status | Explanation |')
   lines.push('| --- | --- | --- |')
-  lines.push(`| Tests | ${report.ok ? '✅ Passed' : '❌ Failed'} | ${report.totals.passed}/${report.totals.tests} tests passed |`)
-  lines.push(`| Budget | ${report.totals.budgetExceeded ? '⚠️ Warning' : '✅ Passed'} | ${formatUsd(report.totals.visionCostUsd)} spent${budgetCap > 0 ? ` of ${formatUsd(budgetCap)}` : ''} |`)
-  lines.push(`| Heal events | ${healCount === 0 ? '✅ Passed' : '⚠️ Warning'} | ${healCount} heal event${healCount === 1 ? '' : 's'} |`)
-  lines.push(`| Assertions | ${assertFails === 0 ? '✅ Passed' : '❌ Failed'} | ${assertFails === 0 ? assertCount : `${assertFails} failed`} assertion${assertCount === 1 ? '' : 's'} |`)
+  lines.push(
+    `| Tests | ${report.ok ? '✅ Passed' : '❌ Failed'} | ${report.totals.passed}/${report.totals.tests} tests passed |`,
+  )
+  lines.push(
+    `| Budget | ${report.totals.budgetExceeded ? '⚠️ Warning' : '✅ Passed'} | ${formatUsd(report.totals.visionCostUsd)} spent${budgetCap > 0 ? ` of ${formatUsd(budgetCap)}` : ''} |`,
+  )
+  lines.push(
+    `| Heal events | ${healCount === 0 ? '✅ Passed' : '⚠️ Warning'} | ${healCount} heal event${healCount === 1 ? '' : 's'} |`,
+  )
+  lines.push(
+    `| Assertions | ${assertFails === 0 ? '✅ Passed' : '❌ Failed'} | ${assertFails === 0 ? assertCount : `${assertFails} failed`} assertion${assertCount === 1 ? '' : 's'} |`,
+  )
   lines.push(`| OpenRouter key | ✅ Passed | \`OPENROUTER_API_KEY\` configured |`)
   if (codeReview && !codeReview.skipped) {
     const codeStatus = codeReview.ok ? '✅ Passed' : '❌ Failed'
-    lines.push(`| Code review | ${codeStatus} | ${codeReview.findings.length} findings (${codeReview.model}) |`)
+    lines.push(
+      `| Code review | ${codeStatus} | ${codeReview.findings.length} findings (${codeReview.model}) |`,
+    )
   } else {
     lines.push(`| Code review | ⚪ Skipped | ${codeReview?.summary ?? 'no report'} |`)
   }
@@ -193,43 +214,7 @@ function renderBody(report, codeReview, runUrl, ok) {
   lines.push('</details>')
   lines.push('')
 
-  if (codeReview && !codeReview.skipped) {
-    lines.push('<details>')
-    lines.push('<summary>🧠 Code review</summary>')
-    lines.push('')
-    lines.push(`**Verdict:** ${codeReview.verdict} · ${codeReview.model} · ${codeReview.tokens}tok ${formatUsd(codeReview.visionCostUsd)}`)
-    if (Array.isArray(codeReview.probes) && codeReview.probes.length > 0) {
-      const reproduced = codeReview.probes.filter((p) => p.outcome === 'reproduced').length
-      lines.push(` · 🧪 ${codeReview.probes.length} probe${codeReview.probes.length === 1 ? '' : 's'} run, ${reproduced} reproduced`)
-    }
-    if (typeof codeReview.probeLaneSkipped === 'string') {
-      lines.push(` · 🧪 probe lane skipped — ${cell(codeReview.probeLaneSkipped)}`)
-    }
-    lines.push('')
-    lines.push(codeReview.summary)
-    lines.push('')
-    if (codeReview.findings.length > 0) {
-      const evidenceIcon = { exercised: '✅', corroborated: '🔴', not_exercised: '⚪', inconclusive: '❔', reproduced: '🧪' }
-      lines.push('| File | Severity | Evidence | Finding |')
-      lines.push('| --- | --- | --- | --- |')
-      // Findings/evidence strings are model- and probe-emitted — sanitize
-      // for the markdown table and bound the section so an oversized report
-      // can't push the body past GitHub's 65536-char comment limit.
-      const MAX_FINDING_ROWS = 25
-      for (const f of codeReview.findings.slice(0, MAX_FINDING_ROWS)) {
-        const ev = f.evidence
-          ? `${evidenceIcon[f.evidence.status] ?? '❔'} ${cell(f.evidence.detail)}`
-          : '—'
-        lines.push(`| \`${cell(f.file)}\` | ${cell(f.severity)} | ${ev} | ${cell(f.message)} |`)
-      }
-      if (codeReview.findings.length > MAX_FINDING_ROWS) {
-        lines.push(`| … | — | — | ${codeReview.findings.length - MAX_FINDING_ROWS} more findings in \`code-review.json\` |`)
-      }
-      lines.push('')
-    }
-    lines.push('</details>')
-    lines.push('')
-  }
+  pushCodeReviewDetails(lines, codeReview, inlinePlan)
 
   lines.push('<details>')
   lines.push('<summary>✨ Actions</summary>')
@@ -247,50 +232,182 @@ function renderBody(report, codeReview, runUrl, ok) {
   return lines.join('\n')
 }
 
-async function main() {
-  const pr = context.payload && context.payload.pull_request
-  const owner = context.repo.owner
-  const repo = context.repo.repo
-  const hasKey = !!process.env.OPENROUTER_API_KEY
-  const workDir = process.env.VISION_E2E_WORKING_DIR || ''
-  const reportDir = path.resolve(
-    process.env.GITHUB_WORKSPACE,
-    workDir,
-    process.env.ARGUS_REPORT_DIR || 'argus-reviewer-report',
+// The 🧠 Code review details block — shared by the full body and the
+// review-only body (run lane disabled).
+function pushCodeReviewDetails(lines, codeReview, inlinePlan) {
+  if (!codeReview || codeReview.skipped) return
+  lines.push('<details>')
+  lines.push('<summary>🧠 Code review</summary>')
+  lines.push('')
+  lines.push(
+    `**Verdict:** ${codeReview.verdict} · ${codeReview.model} · ${codeReview.tokens}tok ${formatUsd(codeReview.visionCostUsd)}`,
   )
-  const runUrl = `${process.env.GITHUB_SERVER_URL}/${owner}/${repo}/actions/runs/${process.env.GITHUB_RUN_ID}`
-
-  let report
-  let codeReview
-  if (hasKey) {
-    try {
-      const raw = fs.readFileSync(path.join(reportDir, 'run.json'), 'utf8')
-      report = JSON.parse(raw)
-    } catch {
-      report = undefined
+  // U7 triage record — Jev annotate/route signals, never the gate.
+  if (codeReview.triage) {
+    const t = codeReview.triage
+    if (t.unadjudicated === true) {
+      lines.push(` · 🧭 triage unadjudicated — Jev unavailable`)
+    } else {
+      lines.push(
+        ` · 🧭 triage: risk ${t.risk ?? '?'}/5` +
+          `${typeof t.needsDeepReview === 'number' ? ` · deep-review ${t.needsDeepReview.toFixed(2)}` : ''}` +
+          `${t.topRiskArea !== undefined ? ` · top area \`${cell(t.topRiskArea)}\`` : ''}` +
+          ` (${cell(t.mode)})`,
+      )
     }
-    try {
-      const raw = fs.readFileSync(path.join(reportDir, 'code-review.json'), 'utf8')
-      codeReview = JSON.parse(raw)
-    } catch {
-      codeReview = undefined
+  }
+  if (Array.isArray(codeReview.probes) && codeReview.probes.length > 0) {
+    const reproduced = codeReview.probes.filter((p) => p.outcome === 'reproduced').length
+    lines.push(
+      ` · 🧪 ${codeReview.probes.length} probe${codeReview.probes.length === 1 ? '' : 's'} run, ${reproduced} reproduced`,
+    )
+  }
+  if (typeof codeReview.probeLaneSkipped === 'string') {
+    lines.push(` · 🧪 probe lane skipped — ${cell(codeReview.probeLaneSkipped)}`)
+  }
+  lines.push('')
+  lines.push(codeReview.summary)
+  lines.push('')
+  if (codeReview.findings.length > 0) {
+    const evidenceIcon = {
+      exercised: '✅',
+      corroborated: '🔴',
+      not_exercised: '⚪',
+      inconclusive: '❔',
+      reproduced: '🧪',
+    }
+    lines.push('| File | Severity | p | Category | Evidence | Finding |')
+    lines.push('| --- | --- | --- | --- | --- | --- |')
+    // Findings/evidence strings are model- and probe-emitted — sanitize
+    // for the markdown table and bound the section so an oversized report
+    // can't push the body past GitHub's 65536-char comment limit.
+    const MAX_FINDING_ROWS = 25
+    for (const f of codeReview.findings.slice(0, MAX_FINDING_ROWS)) {
+      const ev = f.evidence
+        ? `${evidenceIcon[f.evidence.status] ?? '❔'} ${cell(f.evidence.detail)}`
+        : '—'
+      // U8 — Jev P(true positive); unadjudicated findings render '—'.
+      const p = typeof f.p === 'number' ? f.p.toFixed(2) : '—'
+      lines.push(
+        `| \`${cell(f.file)}\` | ${cell(f.severity)} | ${p} | ${cell(f.category ?? '—')} | ${ev} | ${cell(f.message)} |`,
+      )
+    }
+    if (codeReview.findings.length > MAX_FINDING_ROWS) {
+      lines.push(
+        `| … | — | — | — | — | ${codeReview.findings.length - MAX_FINDING_ROWS} more findings in \`code-review.json\` |`,
+      )
+    }
+    lines.push('')
+    // Inline-comment cap note — dedup'd fresh findings the
+    // review.maxComments budget didn't post (TCA max_comments).
+    if (inlinePlan !== undefined && inlinePlan.dropped > 0) {
+      lines.push(
+        `*+${inlinePlan.dropped} inline-eligible finding(s) not posted — \`review.maxComments\` cap ${inlinePlan.cap}.*`,
+      )
+      lines.push('')
+    }
+    // Secrets-lane audit line — adjudicated/suppressed counts, never literals.
+    if (codeReview.secretsScan) {
+      if (typeof codeReview.secretsScan.skipped === 'string') {
+        lines.push(`*🔐 secrets scan skipped — ${cell(codeReview.secretsScan.skipped)}*`)
+      } else if (Array.isArray(codeReview.secretsScan.records)) {
+        const suppressed = codeReview.secretsScan.records.filter((r) => r.suppressed).length
+        const unadj = codeReview.secretsScan.records.filter((r) => !r.adjudicated).length
+        lines.push(
+          `*🔐 secrets scan: ${codeReview.secretsScan.records.length} candidate(s)` +
+            `${suppressed > 0 ? `, ${suppressed} adjudicated-suppressed` : ''}` +
+            `${unadj > 0 ? `, ${unadj} unadjudicated` : ''}` +
+            `${codeReview.secretsScan.overflow > 0 ? `, +${codeReview.secretsScan.overflow} over cap` : ''}.*`,
+        )
+      }
+      lines.push('')
     }
   }
+  // U8 adjudication audit — outside the findings guard so suppressed-
+  // only reviews still show what Jev removed. p values live on the
+  // findings table and in code-review.json records.
+  if (codeReview.findingAdjudication && Array.isArray(codeReview.findingAdjudication.records)) {
+    const fa = codeReview.findingAdjudication
+    if (fa.unadjudicated === true) {
+      lines.push('*🧮 adjudication: unadjudicated — Jev unavailable, nothing suppressed.*')
+    } else {
+      const suppressed = fa.records.filter((r) => r.suppressed).length
+      const unadj = fa.records.filter((r) => !r.adjudicated).length
+      lines.push(
+        `*🧮 adjudication: ${fa.records.length} finding(s) scored` +
+          `${suppressed > 0 ? `, ${suppressed} suppressed (nit/q)` : ''}` +
+          `${unadj > 0 ? `, ${unadj} unadjudicated` : ''}` +
+          `${fa.overflow > 0 ? `, +${fa.overflow} over cap` : ''}.*`,
+      )
+    }
+    lines.push('')
+  }
+  lines.push('</details>')
+  lines.push('')
+}
 
-  // Missing code-review.json after a continue-on-error step means the review
-  // crashed, not that it skipped — an intentional skip writes ok+skipped.
-  // Fail closed rather than reporting it as a clean skip.
-  const codeReviewOk = codeReview != null && codeReview.ok === true
-  const ok = (report?.ok === true) && codeReviewOk
-  const conclusion = !hasKey ? 'neutral' : ok ? 'success' : 'failure'
-  const body = !hasKey
-    ? renderMissingKeyBody()
-    : report === undefined
-      ? renderNoReportBody(reportDir, runUrl)
-      : renderBody(report, codeReview, runUrl, ok)
+// Sticky body for `run: 'false'` consumers — no run.json exists by
+// design, so the body and conclusion reflect code-review alone.
+function renderReviewOnlyBody(codeReview, runUrl, ok, inlinePlan) {
+  const lines = []
+  lines.push(SENTINEL)
+  lines.push('')
+  lines.push(`## argus-reviewer ${ok ? '✅ PASS' : '❌ FAIL'}`)
+  lines.push('')
+  if (!codeReview) {
+    lines.push(
+      '**Summary:** code-review only (run lane disabled) — no `code-review.json` found. The review step crashed or produced no report; the commit status fails closed — check the action logs before merging.',
+    )
+  } else if (codeReview.skipped) {
+    lines.push(
+      `**Summary:** code-review only (run lane disabled) — review skipped: ${cell(codeReview.summary)}`,
+    )
+  } else {
+    lines.push(
+      `**Summary:** code review only (run lane disabled) · verdict **${codeReview.verdict}** · ` +
+        `${codeReview.findings.length} finding(s) · ${codeReview.model} · ` +
+        `${codeReview.tokens}tok ${formatUsd(codeReview.visionCostUsd)}`,
+    )
+  }
+  lines.push('')
+  lines.push('<details>')
+  lines.push('<summary>🚥 Pre-merge checks</summary>')
+  lines.push('')
+  lines.push('| Check | Status | Explanation |')
+  lines.push('| --- | --- | --- |')
+  lines.push('| OpenRouter key | ✅ Passed | `OPENROUTER_API_KEY` configured |')
+  if (codeReview && !codeReview.skipped) {
+    const codeStatus = codeReview.ok ? '✅ Passed' : '❌ Failed'
+    lines.push(
+      `| Code review | ${codeStatus} | ${codeReview.findings.length} findings (${codeReview.model}) |`,
+    )
+  } else {
+    lines.push(
+      `| Code review | ${codeReview ? '⚪ Skipped' : '❌ Failed'} | ${cell(codeReview?.summary ?? 'no report')} |`,
+    )
+  }
+  lines.push('')
+  lines.push('</details>')
+  lines.push('')
+  pushCodeReviewDetails(lines, codeReview, inlinePlan)
+  if (runUrl) lines.push(`[View run](${runUrl})`)
+  lines.push('')
+  lines.push('<details>')
+  lines.push('<summary>✨ Actions</summary>')
+  lines.push('')
+  lines.push('- [ ] Re-run argus-reviewer')
+  lines.push('')
+  lines.push('</details>')
+  lines.push('')
+  lines.push('---')
+  lines.push('')
+  lines.push('<sub>`argus-reviewer` — self-hosted, BYOK OpenRouter UI regression.</sub>')
+  lines.push('')
+  return lines.join('\n')
+}
 
-async function postInlineComments(pr, codeReview) {
-  if (!pr || !codeReview || codeReview.skipped || !codeReview.findings) return
+async function planInlineComments(pr, codeReview) {
+  if (!pr || !codeReview || codeReview.skipped || !codeReview.findings) return undefined
   // Must match the severity vocabulary emitted by the code-review schema
   // (src/cli.ts): bug/risk are inline-worthy; nit/q stay in the sticky body.
   const inlineSeverities = ['bug', 'risk']
@@ -301,6 +418,8 @@ async function postInlineComments(pr, codeReview) {
       line: f.line,
       side: 'RIGHT',
       body: `**argus-reviewer ${f.severity}:** ${f.message}${
+        f.category ? ` \`${f.category}\`` : ''
+      }${
         f.evidence && f.evidence.status === 'reproduced'
           ? '\n\n*🧪 Reproduced by an Argus probe — fails on this PR head, clean on base. See workflow artifacts.*'
           : f.evidence && f.evidence.status !== 'exercised'
@@ -308,7 +427,7 @@ async function postInlineComments(pr, codeReview) {
             : ''
       }`,
     }))
-  if (comments.length === 0) return
+  if (comments.length === 0) return { capped: [], dropped: 0, cap: 0 }
 
   // Re-runs on the same SHA must not duplicate inline comments — the sticky
   // body is upserted but review comments are not. Paginate fully (100/page)
@@ -336,8 +455,17 @@ async function postInlineComments(pr, codeReview) {
     page += 1
   }
   const fresh = comments.filter((c) => !posted.has(dedupKey(c.path, c.line, c.body)))
-  if (fresh.length === 0) return
 
+  // review.maxComments caps inline noise (TCA max_comments) — applied
+  // after dedup so already-posted comments don't eat the budget. A cap of
+  // 0 disables inline posting entirely (no empty review).
+  const cap = typeof codeReview.maxComments === 'number' ? codeReview.maxComments : 20
+  const capped = fresh.slice(0, cap)
+  return { capped, dropped: fresh.length - capped.length, cap }
+}
+
+async function postInlineComments(pr, plan) {
+  if (plan === undefined || plan.capped.length === 0) return
   // One batched review instead of N createReviewComment calls — avoids
   // secondary rate limits on large findings sets.
   try {
@@ -347,13 +475,65 @@ async function postInlineComments(pr, codeReview) {
       pull_number: pr.number,
       commit_id: pr.head.sha,
       event: 'COMMENT',
-      comments: fresh,
+      comments: plan.capped,
     })
   } catch (e) {
     core.warning(`inline review failed: ${e.message}`)
   }
 }
 
+async function main() {
+  const pr = context.payload && context.payload.pull_request
+  const owner = context.repo.owner
+  const repo = context.repo.repo
+  const hasKey = !!process.env.OPENROUTER_API_KEY
+  const workDir = process.env.VISION_E2E_WORKING_DIR || ''
+  const reportDir = path.resolve(
+    process.env.GITHUB_WORKSPACE,
+    workDir,
+    process.env.ARGUS_REPORT_DIR || 'argus-reviewer-report',
+  )
+  const runUrl = `${process.env.GITHUB_SERVER_URL}/${owner}/${repo}/actions/runs/${process.env.GITHUB_RUN_ID}`
+
+  let report
+  let codeReview
+  if (hasKey) {
+    try {
+      const raw = fs.readFileSync(path.join(reportDir, 'run.json'), 'utf8')
+      report = JSON.parse(raw)
+    } catch {
+      report = undefined
+    }
+    try {
+      const raw = fs.readFileSync(path.join(reportDir, 'code-review.json'), 'utf8')
+      codeReview = JSON.parse(raw)
+    } catch {
+      codeReview = undefined
+    }
+  }
+
+  // Missing code-review.json after a continue-on-error step means the review
+  // crashed, not that it skipped — an intentional skip writes ok+skipped.
+  // Fail closed rather than reporting it as a clean skip.
+  const codeReviewOk = codeReview != null && codeReview.ok === true
+  // run: 'false' consumers have no run.json by design — the conclusion then
+  // reflects the code-review verdict alone.
+  const runDisabled = process.env.ARGUS_RUN_DISABLED === '1'
+  const ok = (runDisabled || report?.ok === true) && codeReviewOk
+  const conclusion = !hasKey ? 'neutral' : ok ? 'success' : 'failure'
+  const inlinePlan = hasKey ? await planInlineComments(pr, codeReview) : undefined
+  const body = !hasKey
+    ? renderMissingKeyBody()
+    : runDisabled
+      ? renderReviewOnlyBody(codeReview, runUrl, ok, inlinePlan)
+      : report === undefined
+        ? renderNoReportBody(reportDir, runUrl)
+        : renderBody(report, codeReview, runUrl, ok, inlinePlan)
+
+  // Eligibility + dedup for inline comments, computed before the sticky
+  // body renders so the "+N not posted" note counts the *fresh* set — the
+  // cap is applied to fresh, not to raw findings (already-posted comments
+  // must not inflate the dropped count).
   if (pr) {
     const { data: comments } = await github.rest.issues.listComments({
       owner,
@@ -377,7 +557,7 @@ async function postInlineComments(pr, codeReview) {
         body,
       })
     }
-    await postInlineComments(pr, codeReview)
+    await postInlineComments(pr, inlinePlan)
   }
 
   const sha = pr ? pr.head.sha : context.sha

package/dist/api.d.ts

@@ -7,6 +7,7 @@ import { Config, defineConfig } from './config.js';
 import { ErrorRecord } from './journal/schema.js';
 import { Logger } from './log.js';
 export { defineConfig };
+export { DecisionClient, DecisionError, JEV_DEFAULT_MODEL, type DecisionAnswer, type DecisionClientOptions, type DecisionErrorKind, type DecisionQuestion, } from './vision/decisions.js';
 /**
  * Test-facing API (R13). Test files are plain TypeScript using a `td` object:
  *

package/dist/api.js

@@ -4,6 +4,7 @@ import { loadFlow, saveFlow } from './cache/store.js';
 import { Ledger } from './vision/ledger.js';
 import { defineConfig } from './config.js';
 export { defineConfig };
+export { DecisionClient, DecisionError, JEV_DEFAULT_MODEL, } from './vision/decisions.js';
 const KEY_ALIASES = {
     tab: 'Tab',
     enter: 'Enter',