argus-reviewer-e2e 0.1.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Luke Kimball
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,80 @@
+# argus-reviewer
+
+<p align="center">
+  <img src="docs/assets/social.png" alt="Argus — vision-model E2E testing" width="640" />
+</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.
+- **Cache-first**: replay costs zero vision calls on an unchanged UI; heals re-spend only on drift and show up as reviewable cache diffs.
+- **Cost-explicit**: every call is metered from OpenRouter's per-call cost and rolled into a per-run dollar figure on the PR.
+- **Grounding specialist**: a `grounding_model` (e.g. a ui-tars-class model) can drive element location with its native coordinate output, verified against the DOM before any click executes.
+
+```bash
+npm i -D argus-reviewer-e2e        # or github:duketopceo/argus-reviewer
+npx argus-reviewer record "log in and open settings" --url https://localhost:3000
+npx argus-reviewer run             # replays + asserts, zero-cost on cache hit
+```
+
+<p align="center">
+  <img src="docs/assets/demo.gif" alt="argus-reviewer run — live vision call, PASS, $0.0005 spend" width="900" />
+</p>
+
+*Real `run` output: one vision assert, `PASS`, and the exact dollar figure on the run report.*
+
+Configuration lives in `argus-reviewer.config.ts` (a legacy `vision-e2e.config.*` is still accepted) — see `src/config.ts` for the full shape: `model`, `grounding_model`, `escalation_model`, `provider` routing rules, `budgetUsd`, `target`, `pageSetup`, `secrets`.
+
+### OpenRouter cost attribution
+
+Add an `openrouter` block to tag every request. `trace` is sent in the request body and is the right hook for cost allocation by repo/PR/run. `headers` are sent verbatim with every OpenRouter request (useful for `HTTP-Referer` or `X-Title`).
+
+```ts
+export default {
+  openrouter: {
+    trace: { repo: 'duketopceo/myapp', pr: '42', run: 'argus-reviewer' },
+    headers: { 'HTTP-Referer': 'https://github.com/duketopceo/myapp' },
+  },
+}
+```
+
+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.
+
+## File structure
+
+```text
+argus-reviewer/
+├── action/                  # GitHub Actions composite action + sticky PR comment
+│   ├── action.yml
+│   └── sticky-comment.mjs
+├── runner/                  # Self-hosted runner registration docs + script
+│   ├── README.md
+│   └── register-runner.sh
+├── src/
+│   ├── api.ts               # Test-facing `test`/`td` API + generated test file renderer
+│   ├── cli.ts               # `record`, `run`, and `cache` commands
+│   ├── config.ts            # `argus-reviewer.config.*` loader (legacy `vision-e2e.config.*` accepted)
+│   ├── driver/
+│   │   ├── browser.ts       # Playwright browser launch (chromium/firefox/webkit) + observation capture
+│   │   └── target.ts        # Optional local dev-server target process
+│   ├── engine/
+│   │   ├── 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
+│   ├── report/
+│   │   ├── comment.ts       # Markdown PR comment + commit-status rendering
+│   │   ├── junit.ts         # JUnit XML output
+│   │   └── run.ts           # JSON run report consumed by the action
+│   └── vision/
+│       ├── cost.ts          # OpenRouter cost parsing per call
+│       ├── ledger.ts        # Per-run USD budget tracking
+│       └── openrouter.ts    # OpenRouter chat-completion client + schema parsing
+└── tests/                   # Unit tests + small Playwright fixture page
+```
+
+License: MIT.

package/action/action.yml

@@ -0,0 +1,147 @@
+name: argus-reviewer
+description: Run the argus-reviewer harness and post a sticky PR comment with cost and evidence.
+author: duketopceo
+inputs:
+  openrouter-api-key:
+    description: OpenRouter API key (BYOK). All vision calls are billed through this key.
+    required: true
+  cli:
+    description: Command used to run argus-reviewer (defaults to `npx --no-install argus-reviewer`). For dogfooding this repo, use `node dist/cli.js` after `npm run build`.
+    default: npx --no-install argus-reviewer
+    required: false
+  config:
+    description: Path to the argus-reviewer config file
+    default: argus-reviewer.config.ts
+    required: false
+  working-directory:
+    description: Working directory for the consumer's project
+    required: false
+  budget-usd:
+    description: Optional per-run budget cap override in USD
+    required: false
+  index:
+    description: Run `argus-reviewer index` before the test run to enable diff-aware cache invalidation
+    default: 'true'
+    required: false
+  diff-base:
+    description: Base ref for diff invalidation (e.g. origin/main); empty = working tree
+    default: ''
+    required: false
+  node-version:
+    description: Node.js version for the harness (Node 20 is deprecated on GH runners)
+    default: '22'
+    required: false
+  browser:
+    description: Playwright browser engine to install and run (chromium, firefox, or webkit). Should match config.browser.
+    default: 'chromium'
+    required: false
+  cache-dependency-path:
+    description: npm lockfile path for setup-node cache (defaults to <working-directory>/package-lock.json)
+    required: false
+  report-dir:
+    description: Report output dir, passed to both run and code-review so the post step can find run.json/code-review.json regardless of config reportDir
+    default: argus-reviewer-report
+    required: false
+outputs:
+  conclusion:
+    description: 'Run conclusion: success, failure, or neutral'
+    value: ${{ steps.post.outputs.conclusion }}
+runs:
+  using: composite
+  steps:
+    - uses: actions/setup-node@v4
+      with:
+        node-version: ${{ inputs.node-version }}
+        cache: npm
+        cache-dependency-path: ${{ inputs.cache-dependency-path || format('{0}/package-lock.json', inputs.working-directory || '.') }}
+
+    - name: Install consumer dependencies
+      shell: bash
+      working-directory: ${{ inputs.working-directory }}
+      run: npm ci
+
+    - name: Install Playwright browser
+      shell: bash
+      working-directory: ${{ inputs.working-directory }}
+      env:
+        ARGUS_BROWSER: ${{ inputs.browser }}
+      run: |
+        case "$ARGUS_BROWSER" in
+          chromium|firefox|webkit) ;;
+          *) echo "invalid browser input: '$ARGUS_BROWSER' (expected chromium, firefox, or webkit)"; exit 1 ;;
+        esac
+        npx playwright install --with-deps "$ARGUS_BROWSER" || npx playwright install "$ARGUS_BROWSER"
+
+    - name: Stage config
+      shell: bash
+      working-directory: ${{ inputs.working-directory }}
+      run: |
+        if [ "${{ inputs.config }}" != "argus-reviewer.config.ts" ]; then
+          ext="${{ inputs.config }}"
+          ext="${ext##*.}"
+          case "$ext" in
+            ts|json) cp "${{ inputs.config }}" "argus-reviewer.config.$ext" ;;
+            *) echo "unsupported config extension: $ext" >&2; exit 1 ;;
+          esac
+        fi
+
+    - name: Build repo index
+      if: inputs.index == 'true'
+      shell: bash
+      working-directory: ${{ inputs.working-directory }}
+      run: ${{ inputs.cli }} index
+
+    - name: Run argus-reviewer code review
+      id: code-review
+      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_REVIEWER_TRACE: >-
+          {"repo":"${{ github.repository }}",
+          "pr":"${{ github.event.pull_request.number }}",
+          "commit":"${{ github.sha }}",
+          "run_id":"${{ github.run_id }}",
+          "run_attempt":"${{ github.run_attempt }}",
+          "workflow":"${{ github.workflow }}"}
+      run: ${{ inputs.cli }} code-review --report-dir "${{ inputs.report-dir }}"
+
+    - name: Run argus-reviewer
+      id: run
+      shell: bash
+      working-directory: ${{ inputs.working-directory }}
+      continue-on-error: true
+      env:
+        OPENROUTER_API_KEY: ${{ inputs.openrouter-api-key }}
+        ARGUS_DEBUG: '1'
+        ARGUS_DIFF_BASE: ${{ inputs.diff-base }}
+        ARGUS_BUDGET_USD: ${{ inputs.budget-usd }}
+        ARGUS_REVIEWER_TRACE: >-
+          {"repo":"${{ github.repository }}",
+          "pr":"${{ github.event.pull_request.number }}",
+          "commit":"${{ github.sha }}",
+          "run_id":"${{ github.run_id }}",
+          "run_attempt":"${{ github.run_attempt }}",
+          "workflow":"${{ github.workflow }}"}
+      run: ${{ inputs.cli }} run --report-dir "${{ inputs.report-dir }}"
+
+    - name: Post or update sticky PR comment
+      id: post
+      uses: actions/github-script@v7
+      env:
+        OPENROUTER_API_KEY: ${{ inputs.openrouter-api-key }}
+        VISION_E2E_WORKING_DIR: ${{ inputs.working-directory }}
+        ARGUS_REPORT_DIR: ${{ inputs.report-dir }}
+      with:
+        github-token: ${{ github.token }}
+        script: |
+          const fs = require('fs');
+          const path = require('path');
+          const actionPath = process.env.GITHUB_ACTION_PATH;
+          const file = path.join(actionPath, 'sticky-comment.mjs');
+          const code = fs.readFileSync(file, 'utf8');
+          const runFn = new Function('github', 'context', 'core', 'require', `return (async () => {\n${code}\n})()`);
+          return await runFn(github, context, core, require);

package/action/sticky-comment.mjs

@@ -0,0 +1,376 @@
+/* global github, context, core, require, process */
+
+const fs = require('fs')
+const path = require('path')
+
+const SENTINEL = '<!-- argus-reviewer -->'
+
+function formatUsd(n) {
+  return `$${(n || 0).toFixed(6)}`
+}
+
+function renderMissingKeyBody() {
+  const lines = []
+  lines.push(SENTINEL)
+  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('')
+  lines.push('This status is intentionally neutral, not a failure.')
+  lines.push('')
+  return lines.join('\n')
+}
+
+function renderNoReportBody(reportDir, runUrl) {
+  const lines = []
+  lines.push(SENTINEL)
+  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('')
+  lines.push(`[View run](${runUrl})`)
+  lines.push('')
+  return lines.join('\n')
+}
+
+function renderBody(report, codeReview, runUrl, ok) {
+  if (!report) return renderMissingKeyBody()
+
+  const lines = []
+  const budgetCap = report.config?.budgetUsd ?? 0
+  const healCount = report.tests.reduce((n, t) => n + (t.healEvents?.length ?? 0), 0)
+  const assertCount = report.tests.reduce((n, t) => n + (t.asserts?.length ?? 0), 0)
+  const assertFails = report.tests.reduce(
+    (n, t) => n + (t.asserts?.filter((a) => a.verdict === 'fail').length ?? 0),
+    0,
+  )
+  const trace = report.trace ?? {}
+
+  lines.push(SENTINEL)
+  lines.push('')
+  lines.push(`## argus-reviewer ${ok ? '✅ PASS' : '❌ FAIL'}`)
+  lines.push('')
+  lines.push(
+    `**Summary:** ${report.totals.passed}/${report.totals.tests} passed · ` +
+      `${report.totals.visionCalls} vision calls · ` +
+      `${formatUsd(report.totals.visionCostUsd)} spend · ` +
+      `${report.totals.sandboxSeconds.toFixed(1)}s sandbox`,
+  )
+  lines.push('')
+
+  lines.push('<details>')
+  lines.push('<summary>📝 Summary</summary>')
+  lines.push('')
+  lines.push('**What ran**')
+  for (const t of report.tests) {
+    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('')
+  if (Object.keys(trace).length > 0) {
+    lines.push('**Trace**')
+    for (const [k, v] of Object.entries(trace)) {
+      lines.push(`- ${k}: \`${v}\``)
+    }
+    lines.push('')
+  }
+  lines.push('</details>')
+  lines.push('')
+
+  lines.push('<details>')
+  lines.push(`<summary>📒 Tests (${report.totals.tests})</summary>`)
+  lines.push('')
+  lines.push('| Test | Result | Calls | Cost | Heals | Asserts |')
+  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('')
+  lines.push('</details>')
+  lines.push('')
+
+  lines.push('<details>')
+  lines.push('<summary>💰 Cost ledger</summary>')
+  lines.push('')
+  lines.push('| Line item | Value |')
+  lines.push('| --- | ---: |')
+  lines.push(`| Vision calls | ${report.totals.visionCalls} |`)
+  const perCall =
+    report.totals.visionCalls > 0
+      ? formatUsd(report.totals.visionCostUsd / report.totals.visionCalls)
+      : '$0.00'
+  lines.push(`| Per-call cost (avg) | ${perCall} |`)
+  for (const model of Object.keys(report.totals.callsByModel ?? {}).sort()) {
+    lines.push(`| Calls (${model}) | ${report.totals.callsByModel[model]} |`)
+    lines.push(`| Spend (${model}) | ${formatUsd(report.totals.costByModel?.[model] ?? 0)} |`)
+  }
+  lines.push(`| Total vision spend | ${formatUsd(report.totals.visionCostUsd)} |`)
+  lines.push(`| Sandbox seconds | ${report.totals.sandboxSeconds.toFixed(1)}s |`)
+  if (budgetCap > 0) {
+    lines.push(`| Budget cap | ${formatUsd(budgetCap)} |`)
+    lines.push(`| Budget exceeded | ${report.totals.budgetExceeded ? '⚠️ yes' : '✅ no'} |`)
+  }
+  lines.push('')
+  lines.push('</details>')
+  lines.push('')
+
+  lines.push('<details>')
+  lines.push('<summary>🔧 Heal events</summary>')
+  lines.push('')
+  const heals = report.tests.flatMap((t) => t.healEvents ?? [])
+  if (heals.length === 0) {
+    lines.push('No heals this run.')
+  } else {
+    for (const h of heals) {
+      lines.push(`- \`${h.instruction}\` healed with ${h.model || 'unknown model'}`)
+    }
+  }
+  lines.push('')
+  lines.push('</details>')
+  lines.push('')
+
+  lines.push('<details>')
+  lines.push('<summary>✅ Assertions</summary>')
+  lines.push('')
+  let any = false
+  for (const t of report.tests) {
+    if (!t.asserts || t.asserts.length === 0) continue
+    any = true
+    lines.push(`**${t.name}**`)
+    for (const a of t.asserts) {
+      const icon = a.verdict === 'pass' ? '✅' : a.verdict === 'fail' ? '❌' : '⚪'
+      lines.push(`- ${icon} *${a.question}* — ${a.reasoning}`)
+    }
+    lines.push('')
+  }
+  if (!any) {
+    lines.push('No assertions recorded.')
+    lines.push('')
+  }
+  lines.push('</details>')
+  lines.push('')
+
+  lines.push('<details>')
+  lines.push('<summary>📂 Evidence</summary>')
+  lines.push('')
+  if (report.artifacts && report.artifacts.videos.length > 0) {
+    for (const v of report.artifacts.videos) lines.push(`- video: \`${v}\``)
+  }
+  if (runUrl) lines.push(`- [workflow run / artifacts](${runUrl})`)
+  if ((!report.artifacts || report.artifacts.videos.length === 0) && !runUrl) {
+    lines.push('No artifact links available.')
+  }
+  lines.push('')
+  lines.push('</details>')
+  lines.push('')
+
+  lines.push('<details>')
+  lines.push('<summary>🚥 Pre-merge checks</summary>')
+  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(`| 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 | ⚪ Skipped | ${codeReview?.summary ?? 'no report'} |`)
+  }
+  lines.push('')
+  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)}`)
+    lines.push('')
+    lines.push(codeReview.summary)
+    lines.push('')
+    if (codeReview.findings.length > 0) {
+      const evidenceIcon = { exercised: '✅', corroborated: '🔴', not_exercised: '⚪', inconclusive: '❔' }
+      lines.push('| File | Severity | Evidence | Finding |')
+      lines.push('| --- | --- | --- | --- |')
+      for (const f of codeReview.findings) {
+        const ev = f.evidence
+          ? `${evidenceIcon[f.evidence.status] ?? '❔'} ${f.evidence.detail}`
+          : '—'
+        lines.push(`| \`${f.file}\` | ${f.severity} | ${ev} | ${f.message} |`)
+      }
+      lines.push('')
+    }
+    lines.push('</details>')
+    lines.push('')
+  }
+
+  lines.push('<details>')
+  lines.push('<summary>✨ Actions</summary>')
+  lines.push('')
+  lines.push('- [ ] Re-run argus-reviewer')
+  lines.push('- [ ] Open a heal PR')
+  lines.push('- [ ] Record a new flow')
+  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 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
+  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)
+
+async function postInlineComments(pr, codeReview) {
+  if (!pr || !codeReview || codeReview.skipped || !codeReview.findings) return
+  // 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']
+  const comments = codeReview.findings
+    .filter((f) => f.file && typeof f.line === 'number' && inlineSeverities.includes(f.severity))
+    .map((f) => ({
+      path: f.file,
+      line: f.line,
+      side: 'RIGHT',
+      body: `**argus-reviewer ${f.severity}:** ${f.message}${f.evidence && f.evidence.status !== 'exercised' ? `\n\n*CI evidence: ${f.evidence.detail}*` : ''}`,
+    }))
+  if (comments.length === 0) return
+
+  // 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)
+  // and scope dedup to the current head: comments on older commits must not
+  // suppress findings that still apply to this head.
+  const posted = new Set()
+  let page = 1
+  for (;;) {
+    const { data: existing } = await github.rest.pulls.listReviewComments({
+      owner: context.repo.owner,
+      repo: context.repo.repo,
+      pull_number: pr.number,
+      per_page: 100,
+      page,
+    })
+    for (const c of existing) {
+      if (c.body && c.body.startsWith('**argus-reviewer') && c.commit_id === pr.head.sha) {
+        posted.add(`${c.path}:${c.line}:${c.body}`)
+      }
+    }
+    if (existing.length < 100) break
+    page += 1
+  }
+  const fresh = comments.filter((c) => !posted.has(`${c.path}:${c.line}:${c.body}`))
+  if (fresh.length === 0) return
+
+  // One batched review instead of N createReviewComment calls — avoids
+  // secondary rate limits on large findings sets.
+  try {
+    await github.rest.pulls.createReview({
+      owner: context.repo.owner,
+      repo: context.repo.repo,
+      pull_number: pr.number,
+      commit_id: pr.head.sha,
+      event: 'COMMENT',
+      comments: fresh,
+    })
+  } catch (e) {
+    core.warning(`inline review failed: ${e.message}`)
+  }
+}
+
+  if (pr) {
+    const { data: comments } = await github.rest.issues.listComments({
+      owner,
+      repo,
+      issue_number: pr.number,
+      per_page: 100,
+    })
+    const existing = comments.find((c) => c.body && c.body.includes(SENTINEL))
+    if (existing) {
+      await github.rest.issues.updateComment({
+        owner,
+        repo,
+        comment_id: existing.id,
+        body,
+      })
+    } else {
+      await github.rest.issues.createComment({
+        owner,
+        repo,
+        issue_number: pr.number,
+        body,
+      })
+    }
+    await postInlineComments(pr, codeReview)
+  }
+
+  const sha = pr ? pr.head.sha : context.sha
+  // Commit statuses have no 'neutral'; a 'pending' skip would wedge a
+  // required check forever, so skip maps to success with a clear label.
+  const state = conclusion === 'failure' ? 'failure' : 'success'
+  const description =
+    conclusion === 'neutral'
+      ? 'argus-reviewer skipped (no OPENROUTER_API_KEY)'
+      : `argus-reviewer ${conclusion}`
+  await github.rest.repos.createCommitStatus({
+    owner,
+    repo,
+    sha,
+    state,
+    description,
+    context: 'argus-reviewer',
+    target_url: runUrl,
+  })
+
+  core.setOutput('conclusion', conclusion)
+}
+
+return await main()