action.yml

# OrcaCode Review — reusable composite action.
#
# Consumers reference this with `uses:` instead of copying the folder; see
# workflows/orca-code-review.yml for the ~15-line example workflow.
#
# One review pass per pull-request push. Findings post as inline PR comments and
# a severity gate can fail the check to block the merge.
#
# Model selection is NOT hardcoded here. The action emits raw facts
# (x-cr-prev-tier / x-cr-prev-p0p1) and never names a model; OCR cannot send
# custom headers, so an in-job loopback proxy (scripts/fact-proxy.mjs) stamps
# those facts onto its requests and the workspace router's DSL recipe
# (recipes/orcacode-review.dsl.yaml) turns them into a concrete model. Changing which
# model reviews your code is therefore a recipe edit in your own workspace, with
# no Action version to bump.
#
# Around the review: dashboard settings (scripts/settings.mjs, fetched
# fail-open from the gateway; `settings: "false"` skips the fetch and makes
# the workflow file authoritative) gate auto reviews (auto_review / trigger),
# retune fix-first/block-on, and switch on quiet mode (P2 muted at posting via
# scripts/quiet-filter.mjs — the gate/report still see true counts), an
# exhaustive mode (extra engine passes, deduped by
# scripts/exhaustive-merge.mjs), and a server-side rubric override; an
# oversized-diff guard (scripts/diff-guard.mjs) decides review/skip BEFORE the
# engine ever runs (a skip posts a notice and, by default, FAILS the check so
# the merge gate can't be padded around — `on-oversized-diff: "pass"` makes it
# advisory); one summary per PR (scripts/summary-comment.mjs) is written into
# a marker region of the PR description (scripts/inject-summary.mjs) so it stays
# pinned at the top, replaced in place on every push; and a best-effort per-tier run report
# (scripts/report.mjs) posts severity counts — never code — to the OrcaRouter
# control plane after the gate.

name: "OrcaCode Review"
description: "AI code review for every pull request, powered by OrcaRouter"
author: "OrcaRouter"

branding:
  icon: "eye"
  color: "blue"

inputs:
  orcarouter-api-key:
    description: "OrcaRouter API key."
    required: true
  orcarouter-url:
    description: "OrcaRouter chat-completions endpoint."
    required: false
    default: "https://api.orcarouter.ai/v1/chat/completions"
  github-token:
    description: "Token used to fetch the PR head, post review comments, and react to a /orcacode-review command."
    required: false
    default: ${{ github.token }}
  brand:
    description: "Name shown on PR comments."
    required: false
    default: "OrcaCode Review"
  router:
    description: >-
      OrcaRouter router alias (orcarouter/<name>) that owns model selection.
      The action names no models: it injects raw facts (x-cr-prev-tier /
      x-cr-prev-p0p1) as headers and this router's DSL recipe turns them into a
      concrete model. See recipes/orcacode-review.dsl.yaml.
    required: false
    default: "orcarouter/orcacode-review"
  fix-first:
    description: >-
      Severities that stop an exhaustive review early: once a pass has found
      one, no further passes are added, because that finding is what to fix
      first. NO EFFECT unless exhaustive is on. It does not change what the
      reviewer is asked to look for, and it does not block the merge — that
      is block-on.
    required: false
    default: "P0,P1"
  block-on:
    description: "Severities that fail the check (block the merge)."
    required: false
    default: "P0,P1"
  auto-review-authors:
    description: >-
      Comma-separated GitHub author-association allowlist for AUTOMATIC
      reviews (pull_request events). Empty = review everyone (default). On a
      PUBLIC repo, pull_request_target bypasses GitHub's fork-approval gate
      and the review key is wallet-metered, so an external user can trigger
      paid reviews by opening PRs — set e.g.
      "OWNER,MEMBER,COLLABORATOR,CONTRIBUTOR" to auto-review only known
      contributors (others can still be reviewed on demand via
      /orcacode-review). Also set a wallet budget + alert on the key.
      Case-insensitive; values: OWNER, MEMBER, COLLABORATOR, CONTRIBUTOR,
      FIRST_TIME_CONTRIBUTOR, FIRST_TIMER, MANNEQUIN, NONE.
    required: false
    default: ""
  max-diff-kb:
    description: >-
      Skip the review when the PR's merge-base diff is bigger than this many
      KB. A skip posts a notice without running the engine; whether the check
      then fails or passes is `on-oversized-diff` (default: fail, so the
      merge gate cannot be padded around).


      The default is a ceiling on WASTE, not on what the engine can handle.
      It used to be 512, chosen to avoid spending tokens on diffs that review
      badly — but it also meant a large PR could never be reviewed at all, and
      "never" is worse than "expensive". The engine reads the diff through its
      own tooling rather than taking it as one prompt, so size alone does not
      decide whether it can work.


      What DOES bound it is the model's context window, which the action cannot
      see. Past that point a run reports a wall-clock timeout or an aborted
      pass instead of a clean skip — louder, and no longer a silent refusal to
      look. Lower this if you would rather have the clean skip back.
    required: false
    default: "5000"
  max-diff-files:
    description: >-
      Skip the review when the diff touches more than this many files (same
      notice + on-oversized-diff outcome as max-diff-kb). Counted separately
      from size because the two describe different shapes: a mechanical rename
      across 900 files is small and shallow, one 4 MB generated file is large
      and shallow, and either can be worth reviewing.
    required: false
    default: "2000"
  on-oversized-diff:
    description: >-
      What an oversized-diff skip does to the check. "fail" (default) fails
      it — a diff padded past max-diff-kb / max-diff-files can then never
      bypass a required merge gate. "pass" restores the advisory behavior:
      the skip notice posts and the check stays green.
    required: false
    default: "fail"
  settings:
    description: >-
      Fetch per-repo review settings from the OrcaRouter dashboard at the
      start of each run. Set "false" to skip the fetch entirely and make this
      workflow file authoritative: inputs (or their documented defaults)
      apply as-is and no dashboard value can override them.
    required: false
    default: "true"
  report:
    description: >-
      Send a best-effort per-tier run summary (repo, PR number, head SHA, tier,
      P0/P1/P2 counts, gate result, engine version — never code or finding
      text) to the OrcaRouter control plane. Set "false" to disable.
    required: false
    default: "true"
  engine-version:
    description: "Pinned @alibaba-group/open-code-review version (the review engine). Bump deliberately after testing — the later steps parse its JSON output shape."
    required: false
    default: "1.3.13"
  timeout-minutes:
    description: >-
      Wall-clock ceiling (in minutes) for ONE engine review pass. If the engine
      hasn't produced a result within this window it is killed and the run
      fails closed with a distinct "wall-clock timeout" error (separate from
      "no usable result", so the log makes clear which mode failed). Accepts
      decimals (e.g. "0.5" = 30 seconds) for testing.


      PER PASS, which matters more now that the default is 60: `exhaustive`
      mode makes up to three passes, so the worst case is three times this
      number. The default rose with the diff limits — a review allowed to
      accept a much larger diff needs the time to actually read it, and 20
      minutes would have converted "too big, skipped cleanly" into "killed
      halfway", which is the same non-review with a worse message.
    required: false
    default: "60"
  precision-filter:
    description: >-
      Post-processing between the engine and the merge gate. When `"true"`
      (default), a deterministic filter (L1) verifies each finding's
      `existing_code` snippet against the reviewed commit and re-homes or
      drops findings whose snippet does not match the claimed path; then an
      LLM judge (L2) clusters findings by root cause and drops
      low-confidence ones. Set to `"false"` to post the engine's raw
      findings directly — that skips BOTH layers, and is the supported way to
      review without a judge.

      L1 is soft-fail: if it errors the engine's findings carry forward. L2 is
      NOT. L1's output is not publishable on its own, so a judge still
      unavailable after retries fails the run closed rather than posting
      unjudged findings.
    required: false
    default: "true"
  judge-model:
    description: >-
      Model used by the L2 judge stage. Should differ from the reviewer
      model so the judge acts as an independent second opinion. Ignored when
      `precision-filter` is `"false"`.
    required: false
    default: ""
  judge-threshold:
    description: >-
      Keep-threshold for the L2 judge's per-cluster confidence score (0–1).
      Findings with confidence below this are dropped. Lower to keep more;
      raise to be stricter.
    required: false
    default: "0.5"
  concurrency:
    description: >-
      Max concurrent file reviews. Raise to shorten wall clock on large diffs;
      lower it if your model has a tight per-minute request quota. Empty uses
      the engine default.
    required: false
    default: "24"
  max-tools:
    description: >-
      Max tool-call rounds per file. Lowering it reduces cost and time but can
      cost review depth. Empty uses the engine default.
    required: false
    default: ""
  meter:
    description: >-
      Record per-call token accounting for the run (prompt / completion /
      cached tokens and the model the router resolved) and print a totals table
      in the job log, so a run's real token cost is visible. Local only —
      nothing is uploaded, and the file is removed with the other run files.
      Soft-fail: metering never alters or blocks a review. Set "false" to skip
      it.
    required: false
    default: "true"

runs:
  using: "composite"
  steps:
    # FIRST, before anything can read $RUNNER_TEMP: a reused self-hosted
    # runner can carry a PREVIOUS run's files (a hard cancel can kill a job
    # before its always() cleanup step gets to run). Clear everything this
    # action writes there — above all policy-block.json, which the
    # always()-running "Surface guardrail / firewall block" step trusts and
    # would otherwise post as a false "merge is blocked" comment on a clean
    # run whose review step (and its own stale-file rm) never executed.
    - name: Clear stale run files
      shell: bash
      run: |
        # result-cheap/result-strong are the pre-single-tier names, kept here on
        # purpose: a reused self-hosted runner hard-cancelled under the older
        # action still has them, and they hold finding text and source snippets.
        # This step exists for exactly the files an earlier cleanup never
        # reached, so renaming them out of the list would strand them.
        rm -f "$RUNNER_TEMP/result.json" "$RUNNER_TEMP/review.log" \
          "$RUNNER_TEMP/result-final.json" "$RUNNER_TEMP/result-reported.json" \
          "$RUNNER_TEMP/result-cheap.json" "$RUNNER_TEMP/result-strong.json" \
          "$RUNNER_TEMP/result-posted.json" "$RUNNER_TEMP/result-extra.json" \
          "$RUNNER_TEMP/result-merged.json" \
          "$RUNNER_TEMP/cr-settings.json" "$RUNNER_TEMP/cr-rubric.md" \
          "$RUNNER_TEMP/cr-facts.json" "$RUNNER_TEMP/proxy.out" "$RUNNER_TEMP/proxy.err" \
          "$RUNNER_TEMP/policy-block.json" \
          "$RUNNER_TEMP/pr.diff" "$RUNNER_TEMP/diff-guard.json" "$RUNNER_TEMP/prev-summary.md" \
          "$RUNNER_TEMP/wallclock-timeout" "$RUNNER_TEMP/judge-unavailable" \
          "$RUNNER_TEMP/cr-usage.jsonl" \
          "$RUNNER_TEMP/cr-clean" \
          "$RUNNER_TEMP/result.l1.json" "$RUNNER_TEMP/result.l2.json" \
          "$RUNNER_TEMP/result-extra.l1.json" "$RUNNER_TEMP/result-extra.l2.json" \
          "$RUNNER_TEMP/result.l2.log" "$RUNNER_TEMP/result-extra.l2.log"

    - name: Resolve PR refs
      id: pr
      uses: actions/github-script@v7
      with:
        github-token: ${{ inputs.github-token }}
        script: |
          let base, headSha, num, isDraft, authorAssoc;
          if (context.eventName === 'pull_request_target') {
            base = context.payload.pull_request.base.ref;
            headSha = context.payload.pull_request.head.sha;
            num = context.payload.pull_request.number;
            isDraft = context.payload.pull_request.draft === true;
            authorAssoc = context.payload.pull_request.author_association || 'NONE';
          } else {
            num = context.issue.number;
            const { data: pr } = await github.rest.pulls.get({
              owner: context.repo.owner, repo: context.repo.repo, pull_number: num,
            });
            base = pr.base.ref; headSha = pr.head.sha;
            isDraft = pr.draft === true;
            authorAssoc = pr.author_association || 'NONE';
          }
          core.setOutput('base', base);
          core.setOutput('head_sha', headSha);
          core.setOutput('number', String(num));
          // The project-conventions doc is only trusted when the PR targets the
          // repository's DEFAULT branch. A PR base is author-chosen: a push-access
          // contributor could create a branch holding a malicious AGENTS.md and
          // target it, so "base" is not inherently protected — but the default
          // branch is the canonical ref they cannot rewrite without an approved
          // merge. (Full branch-protection checks need admin token scope and can
          // 403, so default-branch is the robust proxy.)
          core.setOutput('base_is_default', String(base === context.payload.repository.default_branch));
          // Draft state feeds the settings gate: trigger=ready_for_review
          // skips auto-reviews while the PR is still a draft.
          core.setOutput('is_draft', String(isDraft));
          // PR author's association gates auto-review spend on public repos:
          // pull_request_target bypasses GitHub's fork-approval gate, so the
          // `auto-review-authors` allowlist can restrict which associations
          // trigger a paid auto-review (comment commands stay maintainer-gated
          // in the workflow `if:`).
          core.setOutput('author_association', authorAssoc);


    # Lightweight 👀 acknowledgement so the requester sees the bot noticed the
    # trigger. Static one-shot (no update or removal). Fires early — before any
    # skip gate — so even a skipped run still visibly acknowledges receipt.
    # Reaction outages are non-fatal: the review must never be blocked by a
    # UI-affordance failure.
    - name: React 👀 to acknowledge review request
      shell: bash
      env:
        GH_TOKEN: ${{ inputs.github-token }}
        REPO: ${{ github.repository }}
        PR_NUMBER: ${{ steps.pr.outputs.number }}
        EVENT_NAME: ${{ github.event_name }}
        COMMENT_ID: ${{ github.event.comment.id }}
      run: |
        # THE SAME GATE AS THE CLEAR, and its absence here was a regression the
        # last round introduced: gating only the removal left a PAT-backed run
        # POSTing 👀 and never taking it off, which is worse than the state
        # before any of this. Declining is only coherent if it covers both ends.
        #
        # Checked once here rather than inside react(), so a token that cannot be
        # identified costs one API call, not two.
        # ONLY AN EXPLICIT "User" DECLINES. `gh api user` needs a user-scoped
        # token, and github-token defaults to ${{ github.token }} — an
        # installation token, for which that endpoint returns no user. The old
        # `|| echo "Bot"` fallback was meant to cover that and did not: the call
        # can exit 0 with no `.type`, so ME_TYPE came back empty, `!= "Bot"` held,
        # and the reaction was skipped for EVERY consumer on the default token —
        # the case this exists to serve. Measured on a real run: "belongs to a
        # user, not an app" while the reaction author was github-actions[bot].
        #
        # Inverted to fail towards acting: a PAT identifies itself as type User,
        # and anything else — 403, empty, Bot — reacts.
        ME_TYPE=$(gh api user --jq .type 2>/dev/null) || ME_TYPE=""
        if [ "$ME_TYPE" = "User" ]; then
          echo "github-token belongs to a user, not an app; not reacting"
          exit 0
        fi

        # JUST REACT. This used to record the id the POST returned so the clear
        # step could delete exactly it — first unconditionally, then only on a
        # 201 — and each version needed a JSON parse that node is not yet
        # available for at this point in the job. The last one was a greedy
        # expression that picked the nested author id out of a compact response,
        # so the DELETE would have targeted the wrong resource.
        #
        # The id existed to tell OUR reaction from the token owner's. That
        # question is settled once, in the settle step, by declining to manage
        # reactions at all when github-token is a user rather than an app — so
        # there is nothing here to record, and nothing to parse.
        #
        # Two concurrent runs as the same app share one reaction, so the first to
        # finish clears it while the second is still working. Accepted: a missing
        # 👀 for a few minutes is cosmetic, and every mechanism that avoided it
        # cost more correctness elsewhere than it bought.
        react() {
          if gh api -X POST "$1" -f content=eyes >/dev/null 2>&1; then
            echo "reacted 👀 -> $1"
          else
            echo "warning: failed to react at $1 (non-fatal)"
          fi
        }
        # Always react on the PR body (issue reactions endpoint — PRs are issues).
        if [ -n "${PR_NUMBER:-}" ]; then
          react "repos/$REPO/issues/$PR_NUMBER/reactions"
        fi
        # For a maintainer's /orcacode-review command, also react on that
        # trigger comment so the operator sees direct feedback on THEIR comment.
        if [ "$EVENT_NAME" = "issue_comment" ] && [ -n "${COMMENT_ID:-}" ]; then
          react "repos/$REPO/issues/comments/$COMMENT_ID/reactions"
        fi

    # setup-node runs BEFORE checkout (it never reads the workspace) so the
    # settings fetch below has node available even on a bare self-hosted runner.
    - uses: actions/setup-node@v4
      with:
        node-version: "20"

    # Dashboard-driven behavior, fetched from the gateway BEFORE anything is
    # cloned or installed: a settings-skip should cost nothing. settings.mjs
    # always exits 0 and falls back to the built-in defaults on any outage
    # (fail-open — a settings hiccup must never kill reviews); this step's own
    # parsing falls back the same way, so `decision` is always review|skip.
    - name: Fetch review settings
      id: settings
      shell: bash
      env:
        SETTINGS_SCRIPT: ${{ github.action_path }}/scripts/settings.mjs
        SETTINGS_ENABLED: ${{ inputs.settings }}
        ORCAROUTER_URL: ${{ inputs.orcarouter-url }}
        ORCAROUTER_API_KEY: ${{ inputs.orcarouter-api-key }}
        REPO: ${{ github.repository }}
        SETTINGS_JSON: ${{ runner.temp }}/cr-settings.json
        RUBRIC_FILE: ${{ runner.temp }}/cr-rubric.md
        INPUT_FIX_FIRST: ${{ inputs.fix-first }}
        INPUT_BLOCK_ON: ${{ inputs.block-on }}
        EVENT_NAME: ${{ github.event_name }}
        IS_DRAFT: ${{ steps.pr.outputs.is_draft }}
        AUTHOR_ASSOC: ${{ steps.pr.outputs.author_association }}
        AUTO_REVIEW_AUTHORS: ${{ inputs.auto-review-authors }}
      run: |
        # The auto-event gate is defined UP FRONT — before the settings-disabled
        # short-circuit — so BOTH the settings-disabled (workflow-file-
        # authoritative) and settings-enabled (dashboard) paths share the exact
        # same spend guards. The auto-review-authors allowlist in particular is a
        # WORKFLOW-FILE input, not a dashboard value, so it must gate paid auto
        # reviews on public repos REGARDLESS of whether the dashboard fetch ran.

        # Spend guard for public repos: only auto-review PRs whose author
        # association is in the allowlist. Factored into a function so it is
        # unit-tested directly (settings.test.mjs extracts and runs this exact
        # code). Both sides are space-trimmed the way the JS list parsers are,
        # so "OWNER, MEMBER" still anchors on ",MEMBER,"; the comma wrapping
        # keeps the match a whole-token one (MEMBER never matches inside
        # FIRST_TIME_CONTRIBUTOR). An empty (or all-space) allowlist allows
        # everyone (default, preserves behavior). echoes allow|deny.
        author_allowed() {
          local list assoc
          list=$(printf '%s' "$1" | tr -d ' ')
          assoc=$(printf '%s' "$2" | tr -d ' ')
          if [ -z "$list" ]; then echo allow; return; fi
          if printf '%s' ",$list," | grep -qi ",$assoc,"; then echo allow; else echo deny; fi
        }

        # Auto-event gate -> sets DECISION/REASON. Only AUTO runs are gated —
        # any pull_request* event, so a hand-written plain `pull_request`
        # workflow honors gating exactly like the documented
        # `pull_request_target` one. An explicit `/orcacode-review` comment
        # command (issue_comment) always proceeds — on-demand mode exists
        # precisely for those, and a human asking for a review of a
        # draft/disabled repo is deliberate. Shared by both settings paths so the
        # author-allowlist spend guard holds whether or not the dashboard fetch
        # ran. $1=auto_review $2=trigger $3=is_draft.
        gate_decision() {
          DECISION=review
          REASON=""
          case "$EVENT_NAME" in
            pull_request*)
              if [ "$1" = "false" ]; then
                DECISION=skip; REASON="auto-review is disabled in the OrcaRouter dashboard"
              elif [ "$2" = "on_demand" ]; then
                DECISION=skip; REASON="on-demand mode"
              elif [ "$2" = "ready_for_review" ] && [ "$3" = "true" ]; then
                DECISION=skip; REASON="draft PR"
              elif [ "$(author_allowed "$AUTO_REVIEW_AUTHORS" "$AUTHOR_ASSOC")" = deny ]; then
                # Maintainer comment commands are unaffected (gated in the workflow `if:`).
                DECISION=skip; REASON="author association $AUTHOR_ASSOC not in auto-review-authors"
              fi
              ;;
          esac
        }

        # `settings: "false"` makes the workflow FILE authoritative: skip the
        # fetch entirely, so inputs (or their documented defaults) apply as-is
        # and no dashboard value can override them. (With the fetch on, an
        # input left AT its documented default defers to the server — see the
        # precedence rule below — so e.g. a deliberate `block-on: "P0,P1"` pin
        # could still be overridden from the dashboard.) auto_review/trigger are
        # fixed on (true/every_push) in this mode, so gate_decision can only skip
        # via the author allowlist — a fork author still can't spend on a public
        # repo just because the dashboard fetch is off.
        if [ "$SETTINGS_ENABLED" = "false" ]; then
          echo "settings: disabled via the 'settings' input — the workflow file is authoritative."
          gate_decision true every_push false
          echo "settings: workflow-file-authoritative -> $DECISION ${REASON:+($REASON)}"
          {
            echo "auto_review=true"
            echo "trigger=every_push"
            echo "exhaustive=false"
            echo "quiet=false"
            echo "fix_first=$INPUT_FIX_FIRST"
            echo "block_on=$INPUT_BLOCK_ON"
            # Every severity: with the dashboard off there is no report_on to
            # honour and the workflow file has no input for it, so display must
            # not narrow on its own.
            echo "report_on=P0,P1,P2,P3"
            echo "rubric_file="
            echo "decision=$DECISION"
            echo "reason=$REASON"
          } >> "$GITHUB_OUTPUT"
          exit 0
        fi

        node "$SETTINGS_SCRIPT" --url "$ORCAROUTER_URL" \
          --repo "$REPO" --out "$SETTINGS_JSON"

        # Read one validated field from the settings file; $2 is the fallback
        # if the file itself is missing/unreadable (settings.mjs already
        # defaulted and validated every field it wrote).
        setting() {
          node -pe 'String(JSON.parse(require("fs").readFileSync(process.env.SETTINGS_JSON, "utf8"))[process.argv[1]])' \
            "$1" 2>/dev/null || printf '%s' "$2"
        }
        AUTO_REVIEW=$(setting auto_review true)
        TRIGGER=$(setting trigger every_push)
        EXHAUSTIVE=$(setting exhaustive false)
        QUIET=$(setting quiet false)
        FIX_FIRST=$(setting fix_first "P0,P1")
        BLOCK_ON=$(setting block_on "P0,P1")
        # DISPLAY ONLY, and with no `with:` override on purpose: fix_first and
        # block_on have workflow inputs because a repo may need to ENFORCE
        # differently from the workspace default, whereas which severities a
        # reader SEES is the workspace's call. Defaulting to every severity means
        # a gateway that predates the field behaves exactly as before.
        # Agrees with settings.mjs DEFAULTS on purpose. settings.mjs always writes
        # a defaulted file, so this fires only if that file is missing or
        # unreadable — and two different answers to the same question is how one
        # of them ends up wrong without anyone noticing.
        REPORT_ON=$(setting report_on "P0,P1")
        RUBRIC=$(setting rubric "")

        # PRECEDENCE (documented in the README): an explicit `with:` input that
        # DIFFERS from the action's documented default ("P0,P1") wins over the
        # server settings; an input left at the default defers to the server.
        if [ "$INPUT_FIX_FIRST" != "P0,P1" ]; then FIX_FIRST="$INPUT_FIX_FIRST"; fi
        if [ "$INPUT_BLOCK_ON" != "P0,P1" ]; then BLOCK_ON="$INPUT_BLOCK_ON"; fi

        # A non-empty server rubric REPLACES rules/severity-instruction.md as
        # the --background content; it is exposed as a file path only when set.
        RUBRIC_OUT=""
        if [ -n "$RUBRIC" ]; then
          printf '%s\n' "$RUBRIC" > "$RUBRIC_FILE"
          RUBRIC_OUT="$RUBRIC_FILE"
          echo "Using the server-side rubric ($(wc -c < "$RUBRIC_FILE") bytes) instead of the built-in one."
        fi

        # Settings gate — composable with the diff guard's `decision != 'skip'`.
        # Same gate_decision as the settings-disabled path (defined at the top of
        # this step): the dashboard-fetched auto_review/trigger feed it here,
        # while the author-allowlist spend guard inside it is identical in both
        # paths.
        gate_decision "$AUTO_REVIEW" "$TRIGGER" "$IS_DRAFT"
        echo "settings: auto_review=$AUTO_REVIEW trigger=$TRIGGER exhaustive=$EXHAUSTIVE quiet=$QUIET fix_first=$FIX_FIRST block_on=$BLOCK_ON report_on=$REPORT_ON rubric=${RUBRIC_OUT:+custom} -> $DECISION ${REASON:+($REASON)}"
        {
          echo "auto_review=$AUTO_REVIEW"
          echo "trigger=$TRIGGER"
          echo "exhaustive=$EXHAUSTIVE"
          echo "quiet=$QUIET"
          echo "fix_first=$FIX_FIRST"
          echo "block_on=$BLOCK_ON"
          echo "report_on=$REPORT_ON"
          echo "rubric_file=$RUBRIC_OUT"
          echo "decision=$DECISION"
          echo "reason=$REASON"
        } >> "$GITHUB_OUTPUT"

    # On a settings-skip: leave ONE small marker comment (created if absent,
    # edited only when the reason changes — repeated pushes must not spam the
    # timeline or its edit history), then PASS. No later step runs the engine
    # or the gate, so the job (and a required check) goes green.
    - name: Skip review (settings)
      if: steps.settings.outputs.decision == 'skip'
      uses: actions/github-script@v7
      env:
        BRAND: ${{ inputs.brand }}
        PR_NUMBER: ${{ steps.pr.outputs.number }}
        REASON: ${{ steps.settings.outputs.reason }}
      with:
        github-token: ${{ inputs.github-token }}
        script: |
          const brand = process.env.BRAND;
          const num = Number(process.env.PR_NUMBER);
          const repo = { owner: context.repo.owner, repo: context.repo.repo };
          // Own marker (distinct from the summary and oversized-skip ones).
          const MARKER = '<!-- orca-code-review-disabled -->';
          const footer =
            `\n\n<sub>[OrcaCode Review](https://www.orcarouter.ai/code-review) — ` +
            `Route Smarter. Ship Safer. Spend Less.</sub>`;
          const body =
            `${MARKER}\n## 🐳 ${brand}\n\n` +
            `⏸️ **Automatic review is off for this PR** (${process.env.REASON}).\n\n` +
            `The check **passes** — this never blocks your merge. A maintainer can still ` +
            `run a review on demand by commenting \`/orcacode-review\` ` +
            `(\`@orcacode review\` works too), or change the ` +
            `repo's review settings in the OrcaRouter dashboard.` +
            footer;

          const comments = await github.paginate(github.rest.issues.listComments, {
            ...repo, issue_number: num, per_page: 100,
          });
          const existing = comments.find((c) => c.body && c.body.includes(MARKER));
          if (!existing) {
            await github.rest.issues.createComment({ ...repo, issue_number: num, body });
          } else if (existing.body !== body) {
            // Only when the reason changed (e.g. on_demand -> draft).
            await github.rest.issues.updateComment({ ...repo, comment_id: existing.id, body });
          }

          await core.summary.addRaw(`skipped: ${process.env.REASON}`).write();
          core.notice(`${brand}: review skipped — ${process.env.REASON}`);

    - uses: actions/checkout@v4
      if: steps.settings.outputs.decision != 'skip'
      with:
        fetch-depth: 0 # full history for the merge-base diff
        ref: ${{ steps.pr.outputs.head_sha }}
        # Don't leave the job token in .git/config: on pull_request_target later
        # steps (incl. the OCR agent reading untrusted PR files) run with secrets,
        # so a prompt-injected file must not be able to read a persisted token.
        persist-credentials: false

    - name: Fetch PR head (covers fork PRs)
      if: steps.settings.outputs.decision != 'skip'
      shell: bash
      env:
        GH_TOKEN: ${{ inputs.github-token }}
        PR_NUMBER: ${{ steps.pr.outputs.number }}
      run: |
        # Authenticate this one fetch with a command-scoped header (works for
        # private repos) so the token is never written to disk for later steps.
        AUTH=$(printf 'x-access-token:%s' "$GH_TOKEN" | base64 | tr -d '\n')
        git -c "http.extraheader=Authorization: Basic $AUTH" \
          fetch origin "pull/${PR_NUMBER}/head"

    - name: Oversized-diff guard
      id: guard
      if: steps.settings.outputs.decision != 'skip'
      shell: bash
      env:
        BRAND: ${{ inputs.brand }}
        BASE: origin/${{ steps.pr.outputs.base }}
        HEAD: ${{ steps.pr.outputs.head_sha }}
        GUARD: ${{ github.action_path }}/scripts/diff-guard.mjs
        MAX_KB: ${{ inputs.max-diff-kb }}
        MAX_FILES: ${{ inputs.max-diff-files }}
        DIFF_FILE: ${{ runner.temp }}/pr.diff
        GUARD_JSON: ${{ runner.temp }}/diff-guard.json
      run: |
        # Size-check the SAME range the engine reviews (merge-base diff),
        # BEFORE anything is installed or run: an oversized PR should cost
        # nothing. `--merge-base` needs git >= 2.30; fall back to the
        # equivalent three-dot form, then fail OPEN (empty file -> "review")
        # if no diff can be produced — a guard glitch must never kill the job.
        git diff --merge-base "$BASE" "$HEAD" > "$DIFF_FILE" 2>/dev/null \
          || git diff "$BASE...$HEAD" > "$DIFF_FILE" 2>/dev/null \
          || { echo "::warning::$BRAND: diff generation failed — size guard failing open."; : > "$DIFF_FILE"; }
        node "$GUARD" --diff "$DIFF_FILE" --max-kb "$MAX_KB" --max-files "$MAX_FILES" > "$GUARD_JSON"
        cat "$GUARD_JSON"
        node -e '
          const fs = require("fs");
          const g = JSON.parse(fs.readFileSync(process.env.GUARD_JSON, "utf8"));
          fs.appendFileSync(
            process.env.GITHUB_OUTPUT,
            `decision=${g.decision}\nreason=${g.reason}\nsize_kb=${g.size_kb}\nfiles=${g.files}\n`,
          );
        '

    # On "skip": explain on the PR (upserted — one notice, edited while pushes
    # stay oversized), then apply `on-oversized-diff`. No later step runs the
    # engine or the gate either way. Default "fail": the check goes RED — an
    # unreviewed diff must not satisfy a required merge gate (padding a PR
    # past max-diff-kb would otherwise bypass the P0/P1 gate entirely).
    # "pass" restores the advisory behavior (notice + green check).
    - name: Skip review (diff too large)
      if: steps.guard.outputs.decision == 'skip'
      uses: actions/github-script@v7
      env:
        BRAND: ${{ inputs.brand }}
        PR_NUMBER: ${{ steps.pr.outputs.number }}
        SIZE_KB: ${{ steps.guard.outputs.size_kb }}
        FILES: ${{ steps.guard.outputs.files }}
        REASON: ${{ steps.guard.outputs.reason }}
        MAX_KB: ${{ inputs.max-diff-kb }}
        MAX_FILES: ${{ inputs.max-diff-files }}
        ON_OVERSIZED: ${{ inputs.on-oversized-diff }}
      with:
        github-token: ${{ inputs.github-token }}
        script: |
          const brand = process.env.BRAND;
          const num = Number(process.env.PR_NUMBER);
          const repo = { owner: context.repo.owner, repo: context.repo.repo };
          // Anything that is not an explicit "pass" fails the check (fail-safe).
          const pass = process.env.ON_OVERSIZED === 'pass';
          // Own marker (distinct from the summary comment's): once the PR
          // shrinks and reviews resume, the summary comment takes over (and
          // deletes this notice).
          const MARKER = '<!-- orca-code-review-skip -->';
          const footer =
            `\n\n<sub>[OrcaCode Review](https://www.orcarouter.ai/code-review) — ` +
            `Route Smarter. Ship Safer. Spend Less.</sub>`;
          const outcome = pass
            ? `and the check **passes** (\`on-oversized-diff: "pass"\`), so this skip does not block your merge.`
            : `and the check **fails** (\`on-oversized-diff: "fail"\`, the default), so an unreviewed ` +
              `diff cannot slip through a required merge gate.`;
          const body =
            `${MARKER}\n## 🐳 ${brand}\n\n` +
            `⏭️ **Review skipped — this PR's diff is too large** (${process.env.REASON}).\n\n` +
            `| | This PR | Limit |\n|---|---|---|\n` +
            `| Diff size | ${process.env.SIZE_KB} KB | ${process.env.MAX_KB} KB |\n` +
            `| Files touched | ${process.env.FILES} | ${process.env.MAX_FILES} |\n\n` +
            `The review engine was **not** run — reviews of very large diffs truncate and ` +
            `lose signal — ${outcome}\n\n` +
            `**What now?** Split the PR (smaller diffs get much higher-signal reviews), raise ` +
            `the limits, or make skips advisory:\n\n` +
            '```yaml\nwith:\n  max-diff-kb: "10000"       # default 5000\n  max-diff-files: "4000"     # default 2000\n  on-oversized-diff: "pass"  # default "fail"\n```' +
            footer;

          const comments = await github.paginate(github.rest.issues.listComments, {
            ...repo, issue_number: num, per_page: 100,
          });
          const existing = comments.find((c) => c.body && c.body.includes(MARKER));
          if (existing) {
            await github.rest.issues.updateComment({ ...repo, comment_id: existing.id, body });
          } else {
            await github.rest.issues.createComment({ ...repo, issue_number: num, body });
          }

          await core.summary.addRaw(`skipped: diff too large (${process.env.REASON})`).write();
          if (pass) {
            core.notice(`${brand}: review skipped — ${process.env.REASON}`);
          } else {
            core.setFailed(
              `${brand}: review skipped — ${process.env.REASON}. Failing the check so the merge ` +
              `gate cannot be bypassed by an oversized diff: raise max-diff-kb / max-diff-files, ` +
              `split the PR, or set on-oversized-diff: "pass" to make skips advisory.`,
            );
          }

    - name: Install review engine
      if: steps.settings.outputs.decision != 'skip' && steps.guard.outputs.decision != 'skip'
      shell: bash
      env:
        ENGINE_VERSION: ${{ inputs.engine-version }}
      run: npm install -g "@alibaba-group/open-code-review@${ENGINE_VERSION}"

    - name: Review
      id: review
      if: steps.settings.outputs.decision != 'skip' && steps.guard.outputs.decision != 'skip'
      shell: bash
      env:
        ROUTER: ${{ inputs.router }}
        # Wall-clock ceiling for ONE engine pass; wrapped around `ocr review`
        # via GNU `timeout` inside run_pass. Passed as-is (units are minutes;
        # decimals accepted, e.g. "0.5" = 30s). See the input docstring.
        TIMEOUT_MIN: ${{ inputs.timeout-minutes }}
        # Precision post-processing (L1 postfilter + L2 LLM judge) sits
        # between `ocr review` and check-result.mjs; toggled by the input.
        PRECISION_FILTER: ${{ inputs.precision-filter }}
        POSTFILTER: ${{ github.action_path }}/scripts/postfilter.mjs
        JUDGE: ${{ github.action_path }}/scripts/judge.mjs
        JUDGE_MODEL: ${{ inputs.judge-model }}
        JUDGE_THRESHOLD: ${{ inputs.judge-threshold }}
        # Effective value after the settings/input precedence rule.
        FIX_FIRST: ${{ steps.settings.outputs.fix_first }}
        # Non-empty only when the dashboard supplies a replacement rubric.
        RUBRIC_FILE: ${{ steps.settings.outputs.rubric_file }}
        EXHAUSTIVE: ${{ steps.settings.outputs.exhaustive }}
        MERGE: ${{ github.action_path }}/scripts/exhaustive-merge.mjs
        BASE: origin/${{ steps.pr.outputs.base }}
        HEAD: ${{ steps.pr.outputs.head_sha }}
        INSTRUCTION: ${{ github.action_path }}/rules/severity-instruction.md
        OUTPUT_SHAPE: ${{ github.action_path }}/rules/output-shape.md
        # Untrusted-data framing prepended to the project-conventions doc that
        # we extract from the BASE revision and inline into the background file
        # (see the review step): tells the engine the doc may only suppress
        # style findings, never weaken correctness/security or alter severity.
        CONVENTIONS_DIRECTIVE: ${{ github.action_path }}/rules/conventions-directive.md
        # Only load conventions when the PR targets the default branch (base is
        # then a protected ref the PR author cannot rewrite). See the pr step.
        BASE_IS_DEFAULT: ${{ steps.pr.outputs.base_is_default }}
        GATE: ${{ github.action_path }}/scripts/gate.mjs
        CHECK: ${{ github.action_path }}/scripts/check-result.mjs
        PROXY: ${{ github.action_path }}/scripts/fact-proxy.mjs
        BRAND: ${{ inputs.brand }}
        # The real OrcaRouter endpoint. OCR does NOT talk to it directly: the
        # in-job proxy stamps the routing facts as headers and forwards here.
        ORCAROUTER_URL: ${{ inputs.orcarouter-url }}
        # Drive OCR entirely through env vars — its highest-priority config source.
        # Nothing is written to the shared ~/.opencodereview, so we neither leak a
        # token to disk nor clobber a self-hosted runner's existing OCR config.
        # The model is the router alias; the router's DSL picks the real model.
        OCR_LLM_TOKEN: ${{ inputs.orcarouter-api-key }}
        OCR_LLM_AUTH_HEADER: authorization
        OCR_LLM_MODEL: ${{ inputs.router }}
        OCR_USE_ANTHROPIC: "false"
        # Pin the engine: a background auto-update would defeat engine-version and
        # could change the JSON shape the later steps parse.
        OCR_NO_UPDATE: "1"
        # Write engine output OUTSIDE the PR checkout. A fork could commit
        # `result.json`/`review.log` as symlinks pointing at e.g. ~/.ssh; a `>`
        # redirect in the working tree would follow them and clobber the target.
        # $RUNNER_TEMP is runner-controlled and reset per job.
        RESULT: ${{ runner.temp }}/result.json
        REVIEW_LOG: ${{ runner.temp }}/review.log
        # An unfiltered snapshot of $RESULT for the run report: it has to carry
        # what the review FOUND, and $RESULT itself is the input to the display
        # chain (report_on then quiet) further down.
        RESULT_FINAL: ${{ runner.temp }}/result-final.json
        # Exhaustive-mode scratch: each extra engine pass lands in
        # $RESULT_EXTRA and is deduped into $RESULT via $RESULT_MERGED.
        RESULT_EXTRA: ${{ runner.temp }}/result-extra.json
        RESULT_MERGED: ${{ runner.temp }}/result-merged.json
        FACTS_FILE: ${{ runner.temp }}/cr-facts.json
        # Per-call token accounting (see the `meter` input). Empty disables the
        # tap entirely inside the proxy.
        CONCURRENCY: ${{ inputs.concurrency }}
        MAX_TOOLS: ${{ inputs.max-tools }}
        METER: ${{ inputs.meter }}
        USAGE_FILE: ${{ runner.temp }}/cr-usage.jsonl
        # The proxy writes the guardrail/firewall reason here on a block; a later
        # always()-step posts it to the PR (the review step itself fails closed).
        POLICY_BLOCK: ${{ runner.temp }}/policy-block.json
      run: |
        set -e

        # Security: we run with secrets against the PR head on pull_request_target,
        # so never let PR-controlled config weaken the review. A fork could commit
        # `.opencodereview/rule.json` to exclude its own changed files or replace
        # the built-in checks, yielding an empty result that passes as
        # clean. Drop it so OCR uses system defaults + our --background instruction.
        rm -rf .opencodereview

        # Clear any stale block file before the proxy can write a fresh one. On a
        # self-hosted runner $RUNNER_TEMP may be reused, and the always()-step
        # below trusts whatever is here — a leftover block from an earlier run
        # would post a false "merge is blocked" comment on this clean run.
        rm -f "$POLICY_BLOCK"

        # Start the in-job fact-injecting proxy (loopback, ephemeral). OCR can't
        # send custom headers; the proxy stamps x-cr-* facts (from $FACTS_FILE,
        # re-read per request) so the router's DSL can route on them.
        # Pre-create the output files: the backgrounded node opens proxy.out
        # asynchronously, and under `set -e` a first-iteration `sed` on a
        # not-yet-created file would kill the whole step with no diagnostics.
        echo '{}' > "$FACTS_FILE"
        : > "$RUNNER_TEMP/proxy.out"
        : > "$RUNNER_TEMP/proxy.err"
        # Metering is opt-out; an empty CR_USAGE_FILE turns the tap off in the proxy.
        CR_USAGE_FILE=""
        if [ "$METER" = "true" ]; then CR_USAGE_FILE="$USAGE_FILE"; fi
        export CR_USAGE_FILE
        CR_FACTS_FILE="$FACTS_FILE" CR_POLICY_BLOCK_FILE="$POLICY_BLOCK" node "$PROXY" > "$RUNNER_TEMP/proxy.out" 2> "$RUNNER_TEMP/proxy.err" &
        PROXY_PID=$!
        trap 'kill "$PROXY_PID" 2>/dev/null || true' EXIT
        for _ in $(seq 1 50); do
          OCR_LLM_URL=$(sed -n 's/^PROXY_URL=//p' "$RUNNER_TEMP/proxy.out" 2>/dev/null || true)
          [ -n "$OCR_LLM_URL" ] && break
          sleep 0.1
        done
        if [ -z "$OCR_LLM_URL" ]; then
          echo "::error::$BRAND: fact proxy failed to start."; cat "$RUNNER_TEMP/proxy.err" || true; exit 1
        fi
        export OCR_LLM_URL

        # Set the raw facts the DSL routes on for the NEXT review pass.
        #   $1 = prev-tier fact, $2 = prev pass found a fix-first (true|false)
        set_facts() {
          printf '{"x-cr-prev-tier":"%s","x-cr-prev-p0p1":"%s"}' "$1" "$2" > "$FACTS_FILE"
        }

        # The review background is assembled into a FILE, then passed inline via
        # --background "$(cat …)" (the pinned engine 1.3.13 has no
        # --background-file flag). On Linux the arg comfortably holds our sizes
        # (severity rubric ~6 KB + a typical AGENTS.md). Two parts:
        #   1. Severity rubric + [P0]-[P3] tag mandate (rules/severity-instruction.md,
        #      or the dashboard's server-side override, which REPLACES it wholesale;
        #      the untagged->P1 fail-safe still catches slippage). This rides the
        #      background, NOT --rule: a --rule glob REPLACES OCR's built-in
        #      language/security checklist for matched files, and the rubric is
        #      explicitly ADDITIVE on top of that checklist — moving it to --rule
        #      would delete the "what to look for" the rubric depends on.
        #   2. Project conventions, read from the BASE revision — never the PR
        #      head (the engine's file tools can only read the head version, so
        #      we extract the doc ourselves) — and ONLY when the base is the
        #      repo's default branch: a PR base is author-chosen, so an untrusted
        #      base could itself be attacker-controlled. Inlined below, framed as
        #      untrusted data that may only SUPPRESS style findings, and capped so
        #      a large doc cannot push the inlined arg past the OS argv limit.
        BACKGROUND="$RUNNER_TEMP/cr-background.md"
        if [ -n "$RUBRIC_FILE" ] && [ -s "$RUBRIC_FILE" ]; then
          cp "$RUBRIC_FILE" "$BACKGROUND"
          echo "Severity rubric: using the dashboard's server-side override."
        else
          cp "$INSTRUCTION" "$BACKGROUND"
        fi
        # APPENDED IN BOTH BRANCHES, because it is not part of the rubric. The
        # rubric decides WHICH severity a finding gets and a workspace may
        # replace it wholesale; the output SHAPE is how every finding is written
        # down, and the renderer splits a title from a body on it. Living inside
        # the replaceable file, the shape contract reached only workspaces that
        # had not customised their rubric — the ones least likely to notice the
        # untitled output it exists to prevent.
        if [ -s "$OUTPUT_SHAPE" ]; then
          echo "" >> "$BACKGROUND"
          echo "" >> "$BACKGROUND"
          cat "$OUTPUT_SHAPE" >> "$BACKGROUND"
        fi

        # Append the first conventions doc found at the base revision. $BASE is
        # origin/<base ref>; when it is the default branch it is a protected ref
        # the PR author cannot rewrite, so `git show "$BASE:<path>"` is trusted.
        CONVENTIONS_MAX_BYTES=32768
        if [ "$BASE_IS_DEFAULT" = "true" ] && [ -s "$CONVENTIONS_DIRECTIVE" ]; then
          for f in AGENTS.md CLAUDE.md CONTRIBUTING.md; do
            if doc=$(git show "$BASE:$f" 2>/dev/null | head -c "$CONVENTIONS_MAX_BYTES") && [ -n "$doc" ]; then
              {
                printf '\n\n'
                cat "$CONVENTIONS_DIRECTIVE"
                printf '\n\n----- BEGIN %s (untrusted project conventions; read-only reference) -----\n' "$f"
                printf '%s\n' "$doc"
                printf -- '----- END %s -----\n' "$f"
              } >> "$BACKGROUND"
              echo "Project conventions: inlined $f from the base revision ($BASE)."
              break
            fi
          done
        fi

        # One engine pass into $1; returns nonzero on an unusable/partial
        # result. The CALLER decides what that means: a tier's FIRST pass
        # fails the job closed, an exhaustive EXTRA pass just ends the loop
        # (extra depth is best-effort — findings already in hand must survive).
        #   $1 = output file, $2 = log label, $3 = prev tier fact, $4 = prev fix-first fact
        run_pass() {
          set_facts "$3" "$4"
          echo "::group::Review — $2"
          rc=0
          # Wall-clock guard: SIGTERM at TIMEOUT_MIN; SIGKILL 10s later if the
          # engine ignored the term. Redirections apply to whatever `timeout`
          # runs — i.e. ocr's own stdout/stderr — so the JSON result and log
          # end up in the same files as before.
          # Engine tuning flags are only passed when set, so an empty input
          # leaves the engine's own default in place rather than forcing a value.
          ENGINE_FLAGS=""
          [ -n "$CONCURRENCY" ] && ENGINE_FLAGS="$ENGINE_FLAGS --concurrency $CONCURRENCY"
          [ -n "$MAX_TOOLS" ] && ENGINE_FLAGS="$ENGINE_FLAGS --max-tools $MAX_TOOLS"
          # shellcheck disable=SC2086
          timeout --kill-after=10s "${TIMEOUT_MIN}m" \
            ocr review --from "$BASE" --to "$HEAD" \
              --background "$(cat "$BACKGROUND")" --format json $ENGINE_FLAGS \
              > "$1" 2> "$REVIEW_LOG" || rc=$?
          cat "$REVIEW_LOG"
          # 124 = GNU timeout tripped (SIGTERM); 137 = 128+9, i.e. --kill-after
          # escalated to SIGKILL. Leave a marker so run_review can print a
          # wall-clock-specific error (distinct from "no usable result").
          if [ "$rc" = "124" ] || [ "$rc" = "137" ]; then
            echo "::warning::Engine wall-clock timeout after ${TIMEOUT_MIN} minute(s) (rc=$rc)."
            printf 'wall-clock timeout after %sm\n' "$TIMEOUT_MIN" > "$RUNNER_TEMP/wallclock-timeout"
          fi
          echo "::endgroup::"
          # Precision post-processing (seam ③). Only runs when the engine
          # produced a usable JSON result on this pass — a timeout or crash
          # leaves nothing to filter, so we skip straight to CHECK which
          # will fail closed on rc anyway. Both layers write to a temp file
          # first and only overwrite $1 on success, so no postprocessing error
          # can corrupt the engine output.
          #
          # L1 is fail-safe in the full sense: an error there keeps the engine's
          # findings and the review continues. L2 is not — see the judge branch
          # below for why an unavailable judge has to fail the pass.
          #
          # A PARTIAL RESULT IS ALREADY DOOMED, so do not spend the filter on
          # it. CHECK fails closed on any non-empty `warnings`, so a pass that
          # carries them cannot be published however the judge rules. Filtering
          # anyway buys a judge call for output nobody will read — and if THAT
          # call is what fails, the summary blames "the L2 judge was
          # unavailable" for a run whose actual defect was a partial engine
          # result, the exact mis-attribution the reason= tags were added to
          # end. Falling through to CHECK lets reason=partial name it, and
          # name the warnings with it.
          #
          # `warnings` IS NORMALIZED THE WAY CHECK NORMALIZES IT — Array.isArray
          # or nothing (check-result.mjs:44). The two predicates decide the fate
          # of the same field and must not disagree: a non-array `warnings`, say
          # the string "oops", has a nonzero .length, so a bare length test reads
          # it as partial and skips the filter, while CHECK reads it as absent and
          # publishes. That combination ships the engine's raw findings with no
          # L1 and no L2 under `precision-filter: true` — the exact thing this
          # pass fails closed to prevent, arriving as a green review.
          #
          # Which fixes the direction this test has to fail in: SKIPPING is the
          # branch that can publish unjudged, so it may only be taken when the
          # result is definitely partial. Anything malformed or unrecognized runs
          # the filter.
          JUDGE_FAILED=""
          if [ "$PRECISION_FILTER" = "true" ] && [ "$rc" = "0" ] && [ -s "$1" ] \
             && node -e "const r=require(process.argv[1]);const w=Array.isArray(r.warnings)?r.warnings:[];process.exit((r.comments||[]).length>0&&w.length===0?0:1)" "$1" 2>/dev/null; then
            echo "::group::Precision filter — $2"
            L1_OUT="${1%.json}.l1.json"
            if node "$POSTFILTER" "$1" "$GITHUB_WORKSPACE" "$HEAD" --out "$L1_OUT" 2>&1 \
               && [ -s "$L1_OUT" ]; then
              L1_IN_COUNT=$(node -pe "(require('$1').comments||[]).length")
              L1_OUT_COUNT=$(node -pe "(require('$L1_OUT').comments||[]).length")
              echo "L1 postfilter: $L1_IN_COUNT -> $L1_OUT_COUNT"
              mv "$L1_OUT" "$1"
            else
              echo "::warning::L1 postfilter failed — keeping engine findings"
            fi
            L2_OUT="${1%.json}.l2.json"
            # Snapshot the engine's policy-block CONTENT (not just presence)
            # before the L2 sidecar. The judge call goes through fact-proxy,
            # whose `recordPolicyBlock()` can OVERWRITE `$POLICY_BLOCK` if the
            # judge itself hits a guardrail — a presence-only flag can't tell
            # "engine block preserved" from "engine block silently replaced by
            # L2 block". After the L2 call, if we snapshotted engine content
            # we always restore it (both success and fail paths) so the
            # engine's guardrail record wins over an L2 sidecar overwrite.
            POLICY_BLOCK_SNAPSHOT="${POLICY_BLOCK}.pre-l2"
            rm -f "$POLICY_BLOCK_SNAPSHOT"
            if [ -f "$POLICY_BLOCK" ]; then cp -f "$POLICY_BLOCK" "$POLICY_BLOCK_SNAPSHOT"; fi
            # THE ROUTER DECIDES, unless judge-model overrides it. Its default is now
            # empty, which sends this router's ALIAS instead of a model name; judge.mjs
            # stamps x-cr-lens: judge, so the recipe's judge rule picks the model.
            #
            # Same model as before — the shipped recipe routes that rule to
            # a model of its own choosing, which is what judge-model used to name
            # directly. What moves is
            # where the choice lives, so a workspace can price its judge by editing its
            # own recipe rather than waiting for a release.
            #
            # A recipe with NO judge rule sends the judge to its default, i.e. the
            # reviewer's own model, which agrees with itself while still reporting
            # success. That is why the provisioned recipe carries the rule, and why
            # setting judge-model explicitly stays the way to pin a model outright.
            L2_MODEL="${JUDGE_MODEL:-$ROUTER}"
            # CAPTURED, not just streamed, so the failure branch can name WHICH
            # failure this was. The judge exits 1 for a 400, a 401, a missing
            # endpoint and a model that answered with prose, and its exit code
            # tells those apart from each other not at all — the reason only ever
            # existed in its stderr. Everything is echoed below either way, so the
            # log reads exactly as before.
            L2_LOG="${1%.json}.l2.log"
            L2_RC=0
            node "$JUDGE" "$1" --model "$L2_MODEL" --threshold "$JUDGE_THRESHOLD" --out "$L2_OUT" > "$L2_LOG" 2>&1 || L2_RC=$?
            cat "$L2_LOG"
            if [ "$L2_RC" = "0" ] && [ -s "$L2_OUT" ]; then
              L2_IN_COUNT=$(node -pe "(require('$1').comments||[]).length")
              L2_OUT_COUNT=$(node -pe "(require('$L2_OUT').comments||[]).length")
              echo "L2 judge ($L2_MODEL, thr=$JUDGE_THRESHOLD): $L2_IN_COUNT -> $L2_OUT_COUNT"
              mv "$L2_OUT" "$1"
              # L2 succeeded. Restore engine's block if we snapshotted one —
              # covers the case where L2 was warn-mode guardrail-hit and
              # overwrote engine's authoritative record mid-call.
              if [ -f "$POLICY_BLOCK_SNAPSHOT" ]; then
                mv -f "$POLICY_BLOCK_SNAPSHOT" "$POLICY_BLOCK"
              fi
            else
              # L1 AND L2 ARE ONE STAGE, NOT TWO. L1's output is not a shippable
              # review: it is the engine's raw findings with mismatched snippets
              # re-homed, still carrying the duplicate and low-value findings that
              # L2 exists to cluster and drop. Publishing it because the judge was
              # unreachable ships exactly the noise the filter was turned on to
              # remove — worse for the reader than no review, and it arrives
              # looking like a finished one.
              #
              # So an unavailable judge fails the pass. `precision-filter: "false"`
              # remains the supported way to run without a judge, and it skips L1
              # too, which is the honest version of that choice.
              # NAME THE FAILURE CLASS, because they are not the same problem and
              # do not have the same fix. A 502 is the gateway having a moment and
              # is worth re-running; a 401 is a key the workspace has to correct;
              # a model answering in prose is a routing or recipe problem. Calling
              # all three "unavailable after retries" sends the reader to wait out
              # an outage that is not happening — the same wrong-cause reading
              # this pass exists to end, one layer up.
              #
              # FIRST line, not the last: the judge prints "judge did not return
              # JSON:" followed by a dump of what the model actually said, so a
              # tail would quote a fragment of the bad completion in place of the
              # reason. On a failing exit nothing else has been printed, so the
              # first line is the message.
              if [ "$L2_RC" = "0" ]; then
                L2_REASON="it exited cleanly but wrote no output"
              else
                L2_REASON=$(head -n 1 "$L2_LOG")
                [ -n "$L2_REASON" ] || L2_REASON="it exited $L2_RC without a message"
              fi
              # STATED, NOT ADJUDICATED. Whether a failed judge ends the run is
              # the caller's call, not this function's: on the mandatory pass it
              # is fatal, on a best-effort exhaustive pass run_review warns and
              # keeps what it has. An `::error:: … failing closed` here put a red
              # annotation claiming a failure onto runs that went green — the same
              # register of wrong-claim this pass exists to remove. Both callers
              # already print the consequence, so this is a plain log line inside
              # the group the operator is already reading. Matches the wall-clock
              # marker above, which reports and lets run_review adjudicate.
              echo "L2 judge failed — $L2_REASON (L1 output is not publishable on its own, so this pass yields nothing)"
              printf '%s' "$L2_REASON" > "$RUNNER_TEMP/judge-unavailable"
              JUDGE_FAILED=1
              # Restore engine's block if we snapshotted one; else clear any
              # L2-authored block so a sidecar guardrail hit doesn't surface as
              # the engine's own block on the primary review.
              if [ -f "$POLICY_BLOCK_SNAPSHOT" ]; then
                mv -f "$POLICY_BLOCK_SNAPSHOT" "$POLICY_BLOCK"
              else
                rm -f "$POLICY_BLOCK"
              fi
            fi
            unset POLICY_BLOCK_SNAPSHOT
            echo "::endgroup::"
            [ -z "$JUDGE_FAILED" ] || return 1
          fi
          node "$CHECK" "$1" "$rc"
        }

        # The mandatory first pass, then — in exhaustive mode — up to 2 extra
        # engine passes over the same diff, because an LLM review is not
        # exhaustive in one pass. Each extra is deduped into $RESULT by
        # exhaustive-merge.mjs.
        #
        # The loop stops early on either of two conditions: a fix-first finding is
        # already in hand (the gate blocks on what we have, so more depth buys
        # nothing yet), or a pass adds nothing new. So a run makes at most 3 engine
        # passes. PASSES carries the count into the summary.
        #   $1 = log label, $2 = prev-tier fact, $3 = prev fix-first fact,
        #   $4 = extra passes allowed
        run_review() {
          if ! run_pass "$RESULT" "$1" "$2" "$3"; then
            # WHICH GATE FAILED, in the summary and not only inside a collapsed
            # log group. These all used to print the same "no usable result", so a
            # reader could not tell an engine crash from a partial run from an
            # unavailable judge, and picked whichever cause was last in the log.
            if [ -f "$RUNNER_TEMP/wallclock-timeout" ]; then
              echo "::error::$BRAND: $(cat "$RUNNER_TEMP/wallclock-timeout") — engine killed, failing closed. Bump the 'timeout-minutes' input for very large PRs or slow-per-call models."
            elif [ -f "$RUNNER_TEMP/judge-unavailable" ]; then
              echo "::error::$BRAND: the L2 judge failed — $(cat "$RUNNER_TEMP/judge-unavailable") — failing closed. Findings are not published unjudged; set 'precision-filter: false' to review without a judge."
            else
              echo "::error::$BRAND: review engine produced no usable result — failing closed. The log carries a reason= tag naming which check failed."
            fi
            exit 1
          fi
          PASSES=1
          [ "$EXHAUSTIVE" = "true" ] || return 0
          [ "$4" = "true" ] || return 0
          for extra in 2 3; do
            if node "$GATE" "$RESULT" --has "$FIX_FIRST"; then
              echo "exhaustive: $FIX_FIRST finding(s) already in hand — skipping further passes (fix those first)."
              break
            fi
            if ! run_pass "$RESULT_EXTRA" "$1 — exhaustive pass $extra" "$2" "$3"; then
              # A guardrail/firewall POLICY BLOCK on an extra pass is FATAL —
              # exactly like on the primary pass. The proxy records the block to
              # $POLICY_BLOCK (cleared at step start, and no earlier pass wrote
              # it — its presence pins the block to THIS pass) and OrcaRouter
              # stopped the request BEFORE the model, so the review is
              # incomplete. Swallowing it as a warning would let the required
              # check go green while the always() "Surface guardrail / firewall
              # block" step posts a "merge is blocked" comment — a contradiction.
              # Fail closed; that surface step then renders the reason.
              if [ -f "$POLICY_BLOCK" ]; then
                echo "::error::$BRAND: exhaustive pass $extra blocked by a guardrail/firewall policy — failing closed."
                exit 1
              fi
              # Otherwise a benign tooling failure (engine crash / partial
              # result): extra depth is best-effort, so warn and END exhaustion,
              # keeping the findings already in hand.
              # Carry the reason into the downgrade. Without this a judge failure
              # reads as "no usable result", which is what an engine crash also
              # reads as — and the reason is the only thing that tells an operator
              # whether to re-run or fix a key.
              if [ -f "$RUNNER_TEMP/judge-unavailable" ]; then
                echo "::warning::$BRAND: exhaustive pass $extra — the L2 judge failed ($(cat "$RUNNER_TEMP/judge-unavailable")) — keeping the findings so far."
              else
                echo "::warning::$BRAND: exhaustive pass $extra produced no usable result — keeping the findings so far."
              fi
              break
            fi
            # Guard the merge + parse like the run_pass failure path above: an
            # exhaustive-merge.mjs crash or unparseable output must NOT abort the
            # whole step under `set -e` (that would skip Post/Summary/Enforce and
            # turn a review with valid findings-in-hand red). On any failure,
            # warn and END exhaustion gracefully, keeping the findings so far.
            if ! MERGE_OUT=$(node "$MERGE" --base "$RESULT" --new "$RESULT_EXTRA" --out "$RESULT_MERGED"); then
              echo "::warning::$BRAND: exhaustive pass $extra merge failed — keeping the findings so far."
              break
            fi
            mv "$RESULT_MERGED" "$RESULT"
            PASSES=$extra
            if ! NEW_FINDINGS=$(MERGE_JSON="$MERGE_OUT" node -pe 'JSON.parse(process.env.MERGE_JSON).new_findings'); then
              echo "::warning::$BRAND: exhaustive pass $extra produced unparseable merge output — keeping the findings so far."
              break
            fi
            echo "exhaustive: pass $extra added $NEW_FINDINGS new finding(s)."
            [ "$NEW_FINDINGS" -gt 0 ] || break
          done
        }

        # ONE PASS, one tier, one model. The routing FACTS are still injected —
        # the recipe reads them, and a later size-based policy (decided up front,
        # still single-pass) can re-diverge on them without touching this file or
        # the Action version anyone has pinned. Which is why the facts outlived a
        # change that removed everything else about tiers.
        PASSES=1
        run_review "review" "standard" "false" true
        cp "$RESULT" "$RESULT_FINAL"
        # Engine passes behind the FINAL result (the last tier that ran) —
        # >1 only in exhaustive mode; the summary comment notes it.
        echo "passes=$PASSES" >> "$GITHUB_OUTPUT"

    # Token accounting for this run — a separate always() step rather than the
    # tail of the review shell above. That shell `exit 1`s on wall-clock timeout,
    # unusable engine output, and policy blocks, and those are precisely the runs
    # whose token spend you most want to see: the tokens were spent either way.
    # The final cleanup step deletes cr-usage.jsonl, so accounting not printed
    # here is gone for good. Soft-fail throughout — metering reports on a run's
    # verdict, it never changes it.
    - name: Token accounting
      if: always()
      shell: bash
      env:
        METER: ${{ inputs.meter }}
        USAGE_FILE: ${{ runner.temp }}/cr-usage.jsonl
        USAGE_SUMMARY: ${{ github.action_path }}/scripts/usage-summary.mjs
      run: |
        if [ "$METER" = "true" ] && [ -s "$USAGE_FILE" ]; then
          echo "::group::Token accounting"
          node "$USAGE_SUMMARY" "$USAGE_FILE" || true
          echo "::endgroup::"
        fi

    # If a dashboard guardrail/firewall blocked the request, the review step above
    # failed closed and the normal review comment never runs. Surface the reason
    # on the PR so the block is actionable, not just a red X with a log line.
    # always() so it posts despite the failed review step; no-op when no block file.
    # The guard condition also keeps a STALE block file from being posted on a
    # skipped run (the review step's own cleanup never ran on a skip).
    - name: Surface guardrail / firewall block
      if: always() && steps.settings.outputs.decision != 'skip' && steps.guard.outputs.decision != 'skip'
      uses: actions/github-script@v7
      env:
        BRAND: ${{ inputs.brand }}
        PR_NUMBER: ${{ steps.pr.outputs.number }}
        POLICY_BLOCK: ${{ runner.temp }}/policy-block.json
      with:
        github-token: ${{ inputs.github-token }}
        script: |
          const fs = require('fs');
          let block;
          try {
            block = JSON.parse(fs.readFileSync(process.env.POLICY_BLOCK, 'utf8'));
          } catch {
            return; // no guardrail/firewall block this run
          }
          const brand = process.env.BRAND;
          const num = Number(process.env.PR_NUMBER);
          const repo = { owner: context.repo.owner, repo: context.repo.repo };
          // Own marker (distinct from the summary/skip/disabled ones): the block
          // is upserted so a PR that trips a guardrail on every push gets ONE
          // edited comment, not a fresh one each time; the summary step retires
          // it once a clean review posts.
          const MARKER = '<!-- orca-code-review-block -->';
          const layer = block.kind === 'firewall' ? 'firewall' : 'guardrail';
          const policyLine = block.policyName
            ? `\n\n**Policy:** \`${String(block.policyName).slice(0, 120)}\``
            : '';
          const detail = block.detail ? String(block.detail).slice(0, 300) : '';
          const matchedLine = detail ? `\n\n**Matched:** ${detail}` : '';
          const idTag = block.requestId
            ? ` · request id \`${String(block.requestId).slice(0, 80)}\``
            : '';
          const footer =
            `\n\n<sub>[OrcaCode Review](https://www.orcarouter.ai/code-review) — ` +
            `Route Smarter. Ship Safer. Spend Less.${idTag}</sub>`;
          const body =
            `${MARKER}\n## 🐳 ${brand}\n\n` +
            `🛡️ **Review blocked by a ${layer} policy.**` +
            policyLine +
            matchedLine +
            `\n\nOrcaRouter's ${layer} matched this PR against a configured policy and ` +
            `stopped the request **before it reached the model** — the flagged content was ` +
            `never sent to the LLM provider. Because the diff wasn't reviewed, the merge is blocked.` +
            `\n\n**What to do**\n` +
            `- Remove or fix the flagged content (commonly a secret, credential, or other restricted text in the diff).\n` +
            `- Keep secrets out of the repo — use GitHub Actions secrets or a secrets manager, referenced at deploy time.\n` +
            `- If a real secret was exposed, rotate it now.\n` +
            `- Push the fix and the review will re-run automatically.` +
            footer;
          // Upsert by marker — find an existing block comment and edit it (only
          // when the reason changed), else create one, mirroring the skip-notice
          // pattern above. A guardrail that trips on every push must not spam.
          const existingComments = await github.paginate(github.rest.issues.listComments, {
            ...repo, issue_number: num, per_page: 100,
          });
          const existing = existingComments.find((c) => c.body && c.body.includes(MARKER));
          if (!existing) {
            await github.rest.issues.createComment({ ...repo, issue_number: num, body });
          } else if (existing.body !== body) {
            await github.rest.issues.updateComment({ ...repo, comment_id: existing.id, body });
          }

    # What gets POSTED is decoupled from what gets ENFORCED: this step always
    # produces $RESULT_POSTED for the posting step — a straight copy normally,
    # or with P2 comments dropped when quiet mode is on (dashboard settings).
    # The severity gate, the summary counts, and the run reports keep reading
    # the UNfiltered result: quiet mutes timeline noise, never enforcement.
    # report_on: which severities the workspace wants PUBLISHED (dashboard →
    # "Report severities"). The Action did not parse the field before, so the
    # setting was offered and then silently ignored here.
    #
    # FIRST IN THE DISPLAY CHAIN, before quiet, because quiet's question is "is
    # there anything left to say" and after a narrowed report_on there can be
    # nothing left to say while the raw result is full of findings.
    #
    # The gate and the run report keep reading $RESULT — the unfiltered file.
    # report_on changes what lands on the PR, never what is enforced or measured;
    # the union with block_on inside the script is what stops a display preference
    # from hiding a merge blocker.
    #
    # THE SUMMARY IS DISPLAY, so it reads the filtered copy — it did not, and the
    # pinned description contradicted the review three lines below it.
    - name: report_on severity filter
      if: steps.settings.outputs.decision != 'skip' && steps.guard.outputs.decision != 'skip'
      shell: bash
      env:
        REPORT_FILTER: ${{ github.action_path }}/scripts/report-filter.mjs
        REPORT_ON: ${{ steps.settings.outputs.report_on }}
        BLOCK_ON: ${{ steps.settings.outputs.block_on }}
        RESULT: ${{ runner.temp }}/result.json
        RESULT_REPORTED: ${{ runner.temp }}/result-reported.json
      run: |
        # ALWAYS --show, including when it is empty. The script reads an ABSENT
        # flag as "no setting to apply" and passes everything through, and an
        # EMPTY one as "publish only what blocks" — two different answers, and
        # only one of them can be right here. The settings step always emits a
        # value: the dashboard path forwards what was configured, and the
        # disabled path writes every severity explicitly. So an empty value
        # arriving here can only be the configured "show only what blocks",
        # and guarding on `-n` published everything instead.
        #
        # There is no path where this is empty because nothing wrote it: if the
        # settings step fails outright it fails the job, having no
        # continue-on-error.
        node "$REPORT_FILTER" "$RESULT" \
          --show "$REPORT_ON" --block-on "$BLOCK_ON" --out "$RESULT_REPORTED"

    - name: Quiet mode filter
      if: steps.settings.outputs.decision != 'skip' && steps.guard.outputs.decision != 'skip'
      shell: bash
      env:
        QUIET: ${{ steps.settings.outputs.quiet }}
        QUIET_FILTER: ${{ github.action_path }}/scripts/quiet-filter.mjs
        # The report_on-filtered copy, not the raw result — see the step above.
        RESULT: ${{ runner.temp }}/result-reported.json
        RESULT_POSTED: ${{ runner.temp }}/result-posted.json
      run: |
        if [ "$QUIET" = "true" ]; then
          node "$QUIET_FILTER" "$RESULT" --drop P2 --out "$RESULT_POSTED"
        else
          cp "$RESULT" "$RESULT_POSTED"
        fi

    - name: Post review comments
      if: steps.settings.outputs.decision != 'skip' && steps.guard.outputs.decision != 'skip'
      uses: actions/github-script@v7
      env:
        BRAND: ${{ inputs.brand }}
        PR_NUMBER: ${{ steps.pr.outputs.number }}
        HEAD_SHA: ${{ steps.pr.outputs.head_sha }}
        # The quiet-filtered copy — see the "Quiet mode filter" step above.
        RESULT: ${{ runner.temp }}/result-posted.json
        # PRE-QUIET, for the one question quiet must not answer: did this review
        # FIND anything? Quiet decides what is posted; a run whose P2s it muted
        # has still found them, and the summary says so. Reading the posted file
        # to declare a run clean put "No findings" and a 👍 on a pull request
        # whose own summary listed the findings three lines above.
        RESULT_FOUND: ${{ runner.temp }}/result-reported.json
      with:
        github-token: ${{ inputs.github-token }}
        script: |
          const fs = require('fs');
          const brand = process.env.BRAND;
          const num = Number(process.env.PR_NUMBER);
          const sha = process.env.HEAD_SHA;
          const repo = { owner: context.repo.owner, repo: context.repo.repo };

          let result = { comments: [] };
          try {
            result = JSON.parse(fs.readFileSync(process.env.RESULT, 'utf8'));
          } catch (e) {
            console.log('Could not parse result.json:', e.message);
          }
          const comments = result.comments || [];
          // OrcaRouter design: 🐳 header, colored severity dots, brand tagline.
          const SEV = { P0: '🔴', P1: '🟠', P2: '🟡', P3: '⚪' };
          // Attribution for the Apache-2.0 engine lives in NOTICE + README, not
          // in every comment — OCR is consumed as a package, not redistributed.
          const footer =
            `\n\n<sub>[OrcaCode Review](https://www.orcarouter.ai/code-review) — ` +
            `Route Smarter. Ship Safer. Spend Less.</sub>`;

          // THE THUMB IS NOT SETTLED HERE. This step is one of several ways a run
          // ends — settings skip, oversized diff, a guardrail block, an engine
          // failure, a rejected post — and a marker only this step maintains is
          // one the other endings leave stale, endorsing a head nobody reviewed.
          // It is settled in the always() step near the end of this file, which
          // sees every ending. All this step does is record what it concluded.
          const markClean = () => {
            try {
              fs.writeFileSync(process.env.RUNNER_TEMP + '/cr-clean', '1');
            } catch (e) {
              console.log('could not record the clean verdict (non-fatal):', e.message);
            }
          };

          // DID THE REVIEW FIND ANYTHING — not "is there anything left to post".
          // `comments` is the quiet-filtered list, so a quiet workspace whose
          // findings were all P2 arrives here empty while its summary reports
          // them. Declaring that clean contradicts the summary on the same PR.
          let foundCount = comments.length;
          try {
            const found = JSON.parse(fs.readFileSync(process.env.RESULT_FOUND, 'utf8'));
            foundCount = (found.comments || []).length;
          } catch (e) {
            // Unreadable: fall back to what we can see rather than guess clean.
          }

          // MUTED IS NOT CLEAN, AND IT IS NOT A REVIEW EITHER. Quiet drops every
          // reported P2, so a run can have found things and still have nothing
          // to post. Falling through built a review from an empty array —
          // "Found **0** issues in this PR: ." — beside a description summary
          // that listed the muted findings. Quiet's own promise is silence, so
          // this posts nothing AND records no clean verdict: the run is not
          // clean, it is quiet.
          if (foundCount > 0 && comments.length === 0) {
            console.log('quiet mode muted every finding; posting nothing');
            return;
          }

          if (foundCount === 0) {
            // A CLEAN RUN SAYS SO. This used to return silently and leave the
            // pinned summary to report it — but the summary sits in the PR
            // description, folded and above the fold only if you scroll, so a
            // reviewer who asked for a review got no visible answer at all. The
            // hosted reviewer posts this same sentence; two paths reviewing one
            // repository should not disagree about what "nothing to flag" looks
            // like.
            //
            // Still one timeline entry per push, which was the original worry.
            // That is what the 👍 is for: the entry states the result once, and
            // the reaction is the at-a-glance version that updates in place.
            const cleanBody =
              `## 🐳 ${brand}\n\n` +
              `✅ **No findings** — nothing to flag in this PR. Great work!`;
            try {
              await github.rest.pulls.createReview({
                ...repo, pull_number: num, commit_id: sha,
                body: cleanBody + footer, event: 'COMMENT',
              });
            } catch (e) {
              console.log('Clean review failed, posting as a comment:', e.message);
              await github.rest.issues.createComment({
                ...repo, issue_number: num, body: cleanBody + footer,
              });
            }
            // AFTER ONE OF THEM SUCCEEDED. Written first, a run whose review AND
            // its comment fallback both failed still told the always() step it
            // was clean — so the 👍 endorsed a verdict that was never published.
            // A throw from the fallback skips this and the thumb is withdrawn,
            // which is the right answer for a run that could not say anything.
            markClean();
            return;
          }

          // Severity from the LEADING [P0]/[P1]/[P2]/[P3] tag only (mirrors gate.mjs);
          // a later mention must not override the missing-tag P1 fail-safe.
          const tagRe = /^\s*\[(P[0-3])\]\s*/i;
          const sevOf = (c) => {
            const m = String(c.content || '').match(tagRe);
            return m ? m[1].toUpperCase() : 'P1';
          };
          // Display form (Codex-style): a colored severity badge, then a bold
          // subtitle + prose ONLY when we can split cleanly; otherwise the finding
          // stays whole. OCR emits a single `[Px] <prose>` string with no title
          // field, and a forced split reads worse than no split (mid-phrase breaks,
          // lowercase fragments). So we split on just two reliable signals: a
          // model-written **bold** lead, or a short first sentence (which keeps the
          // body starting on a fresh, capitalized sentence). Anything else: whole.
          const decorate = (c) => {
            const text = String(c.content || '');
            const m = text.match(tagRe);
            const sev = m ? m[1].toUpperCase() : 'P1';
            const badge = `${SEV[sev]} **${sev}**`;
            const raw = (m ? text.slice(m[0].length) : text).trim();
            const mk = (t) => t.replace(/\*\*/g, '').replace(/[.!?]+$/, '').trim();
            // 1) The model sometimes writes its own **bold** lead — use it verbatim.
            const lead = raw.match(/^\*\*(.+?)\*\*\s+([\s\S]+)$/);
            if (lead) {
              // THE BODY KEEPS ITS ASTERISKS. Stripping every `**` was tolerable
              // while only some findings took this branch; the rubric now asks
              // for a bold title on all of them, so every explanation would pass
              // through it — and `x ** 2` or `src/**/*.js` in a finding came out
              // corrupted. Only the title's own markup is removed, by mk().
              return `${badge} **${mk(lead[1])}**\n\n${lead[2].trim()}`;
            }
            // 2) Else split only when the first sentence is short enough to title.
            const rest = raw.replace(/\*\*/g, '');
            const end = rest.search(/(?<=[.!?])\s/);
            if (end > 0 && end <= 72) {
              return `${badge} **${mk(rest.slice(0, end))}**\n\n${rest.slice(end).trim()}`;
            }
            // 3) Hard to separate cleanly — keep the finding whole.
            return `${badge} ${rest}`;
          };
          const counts = {};
          for (const c of comments) counts[sevOf(c)] = (counts[sevOf(c)] || 0) + 1;
          const breakdown = ['P0', 'P1', 'P2', 'P3']
            .filter((s) => counts[s])
            .map((s) => `${SEV[s]} ${counts[s]} ${s}`)
            .join(' · ');
          const n = comments.length;
          const summary =
            `## 🐳 ${brand}\n\n` +
            `Found **${n}** issue${n === 1 ? '' : 's'} in this PR: ${breakdown}.`;

          const inline = [];
          const rest = [];
          for (const c of comments) {
            const line =
              c.end_line >= 1 ? c.end_line : c.start_line >= 1 ? c.start_line : 0;
            if (line >= 1 && c.path) {
              inline.push({ path: c.path, line, side: 'RIGHT', body: decorate(c) });
            } else {
              rest.push(c);
            }
          }
          let body = summary;
          for (const c of rest) body += `\n\n---\n\`${c.path}\`: ${decorate(c)}`;

          try {
            await github.rest.pulls.createReview({
              ...repo, pull_number: num, commit_id: sha,
              body: body + footer, event: 'COMMENT',
              comments: inline,
            });
          } catch (e) {
            console.log('Inline review failed, posting findings as a comment:', e.message);
            // The inline batch carries the actual findings; if GitHub rejects it
            // (uncommentable line, batch too large) append them as text so users
            // still see the details instead of bare counts.
            let fallback = body;
            for (const c of inline) {
              fallback += `\n\n---\n\`${c.path}\` (line ${c.line}): ${c.body}`;
            }
            await github.rest.issues.createComment({ ...repo, issue_number: num, body: fallback + footer });
          }

    # ONE summary per PR, written into the PR DESCRIPTION body (the only element
    # GitHub anchors at the very top) inside a marker-delimited region that is
    # replaced in place on every push: severity counts with Δ vs the previous
    # push (state travels in an HTML comment inside the region), the tier, and
    # the gate verdict. The author's own description text is preserved untouched.
    # Runs BEFORE the enforce step so a blocked run still updates the summary.
    - name: Summary (PR description)
      if: steps.settings.outputs.decision != 'skip' && steps.guard.outputs.decision != 'skip'
      uses: actions/github-script@v7
      env:
        PR_NUMBER: ${{ steps.pr.outputs.number }}
        # THE FILTERED COPY, the same one the inline comments come from.
        #
        # This used to be the raw result, deliberately, so the summary could show
        # "true counts". That reads as honesty and lands as a contradiction: a
        # workspace on report_on=P0,P1 saw two P1s inline and a description
        # pinned above them announcing P2s and P3s that appear nowhere in the
        # review. The reader has no way to tell which surface to believe, and
        # the one they can act on is the one they were shown.
        #
        # Two surfaces of one review must not disagree. The gate and the run
        # report still read $RESULT — those MEASURE and ENFORCE, and a display
        # preference must never move them. This one is display.
        RESULT: ${{ runner.temp }}/result-reported.json
        PREV_BODY: ${{ runner.temp }}/prev-summary.md
        SUMMARY_SCRIPT: ${{ github.action_path }}/scripts/summary-comment.mjs
        INJECT_SCRIPT: ${{ github.action_path }}/scripts/inject-summary.mjs
        GATE: ${{ github.action_path }}/scripts/gate.mjs
        BLOCK_ON: ${{ steps.settings.outputs.block_on }}
        QUIET: ${{ steps.settings.outputs.quiet }}
        PASSES: ${{ steps.review.outputs.passes }}
      with:
        github-token: ${{ inputs.github-token }}
        script: |
          const fs = require('fs');
          const { execFileSync } = require('child_process');
          const { pathToFileURL } = require('url');
          const { injectSummary, extractRegion } = await import(pathToFileURL(process.env.INJECT_SCRIPT).href);
          const num = Number(process.env.PR_NUMBER);
          const repo = { owner: context.repo.owner, repo: context.repo.repo };
          // Legacy marker: earlier versions posted the summary as an issue
          // comment. Keep in sync with scripts/summary-comment.mjs.
          const MARKER = '<!-- orca-code-review-summary -->';

          // A real review ran, so retire stale notices (best-effort): the
          // "automatic review is off", "diff too large", and guardrail/firewall
          // "review blocked" comments would otherwise outlive the condition they
          // describe once a clean review posts. Also delete a legacy summary
          // issue comment from a pre-description-body install so it doesn't
          // linger as a duplicate of the description summary.
          const comments = await github.paginate(github.rest.issues.listComments, {
            ...repo, issue_number: num, per_page: 100,
          });
          for (const stale of ['<!-- orca-code-review-disabled -->', '<!-- orca-code-review-skip -->', '<!-- orca-code-review-block -->', MARKER]) {
            const notice = comments.find((c) => c.body && c.body.includes(stale));
            if (!notice) continue;
            try {
              await github.rest.issues.deleteComment({ ...repo, comment_id: notice.id });
            } catch (e) {
              console.log(`Could not delete a stale notice (${stale}):`, e.message);
            }
          }

          // Read the current PR description; the previous summary (if any) lives
          // in its marker region. Feed that back for the Δ column and number
          // this push from its machine state (first summary = push 1).
          const { data: pr } = await github.rest.pulls.get({ ...repo, pull_number: num });
          const prevRegion = extractRegion(pr.body);
          const args = [process.env.SUMMARY_SCRIPT, process.env.RESULT];
          let push = 1;
          if (prevRegion) {
            fs.writeFileSync(process.env.PREV_BODY, prevRegion);
            args.push('--prev', process.env.PREV_BODY);
            const m = prevRegion.match(/<!-- orca-cr-state: (\{.*?\}) -->/);
            if (m) {
              try { push = (Number(JSON.parse(m[1]).push) || 0) + 1; } catch { /* keep 1 */ }
            }
          }

          // Mirror the enforce step's verdict: gate.mjs on the final result
          // (exit 0 = a BLOCK_ON severity is present).
          let blocked;
          try {
            execFileSync('node', [process.env.GATE, process.env.RESULT, '--has', process.env.BLOCK_ON], { stdio: 'pipe' });
            blocked = true;
          } catch { blocked = false; }
          // One tier, one name. This used to report `strong`, from when a cheap
          // pass could escalate to a strong one; with a single pass the label was
          // a leftover that made per-tier figures meaningless.
          args.push('--tier', 'standard', '--push', String(push), '--gate', blocked ? 'blocked' : 'pass');
          // The ❌ line counts findings against the EFFECTIVE block-on set
          // (dashboard/input precedence already applied) — an empty string is
          // a deliberate "block on nothing" and passes through as-is.
          args.push('--block-on', process.env.BLOCK_ON ?? 'P0,P1');
          // Mode notes: exhaustive pass count (renders only when > 1) and the
          // quiet-mode explainer next to the true counts.
          args.push('--passes', process.env.PASSES || '1');
          // ONLY WHEN THERE IS STILL A P2 TO EXPLAIN. The note reads "quiet mode:
          // P2 shown in summary only", which is true while the summary carries
          // P2s the inline comments do not. Now that the summary reads the
          // report_on-filtered file, a workspace excluding P2 there has a summary
          // with zero P2s — and the note would sit under a 0 explaining why it is
          // shown. The flag describes a difference; with no difference, no note.
          const summaryHasP2 = (() => {
            try {
              const r = JSON.parse(fs.readFileSync(process.env.RESULT, 'utf8'));
              return (r.comments || []).some((c) => /^\s*\[?P2\]?/i.test(String(c.content || '')));
            } catch (e) { return true; }  // unreadable: keep the old behaviour
          })();
          if (process.env.QUIET === 'true' && summaryHasP2) args.push('--quiet');

          const summaryMd = execFileSync('node', args, { encoding: 'utf8' });
          // Preserve the author's description text; only the marker region changes.
          const newBody = injectSummary(pr.body, summaryMd);
          if (newBody !== (pr.body || '')) {
            await github.rest.pulls.update({ ...repo, pull_number: num, body: newBody });
          }

    - name: Enforce severity gate
      if: steps.settings.outputs.decision != 'skip' && steps.guard.outputs.decision != 'skip'
      shell: bash
      env:
        BRAND: ${{ inputs.brand }}
        # Effective values after the settings/input precedence rule.
        BLOCK_ON: ${{ steps.settings.outputs.block_on }}
        GATE: ${{ github.action_path }}/scripts/gate.mjs
        # ALWAYS the unfiltered result — quiet mode never weakens the gate.
        RESULT: ${{ runner.temp }}/result.json
      run: |
        if node "$GATE" "$RESULT" --has "$BLOCK_ON"; then
          echo "::error::$BRAND: blocking — found $BLOCK_ON severity finding(s)."
          exit 1
        fi
        echo "$BRAND: no $BLOCK_ON findings — gate passed."

    # Best-effort run counters to the OrcaRouter control plane — severity
    # counts and the gate verdict only, never code (see README "Run
    # reporting"). One step per tier that ran, AFTER the gate: always() because
    # a blocked gate fails the job above, and blocked runs must report too.
    # report.mjs itself exits 0 on any error, so these steps can't fail the job.
    - name: Report run
      if: always() && inputs.report == 'true' && steps.settings.outputs.decision != 'skip' && steps.guard.outputs.decision != 'skip'
      shell: bash
      env:
        REPORT: ${{ github.action_path }}/scripts/report.mjs
        GATE: ${{ github.action_path }}/scripts/gate.mjs
        RESULT_FINAL: ${{ runner.temp }}/result-final.json
        BLOCK_ON: ${{ steps.settings.outputs.block_on }}
        REPO: ${{ github.repository }}
        PR_NUMBER: ${{ steps.pr.outputs.number }}
        HEAD_SHA: ${{ steps.pr.outputs.head_sha }}
        ORCAROUTER_URL: ${{ inputs.orcarouter-url }}
        ORCAROUTER_API_KEY: ${{ inputs.orcarouter-api-key }}
        ENGINE_VERSION: ${{ inputs.engine-version }}
      run: |
        # The verdict re-uses gate.mjs on the snapshot
        # (exit 0 = a BLOCK_ON severity is present = blocked).
        GATE_RESULT=pass
        if node "$GATE" "$RESULT_FINAL" --has "$BLOCK_ON"; then GATE_RESULT=blocked; fi
        node "$REPORT" "$RESULT_FINAL" \
          --repo "$REPO" --pr "$PR_NUMBER" --sha "$HEAD_SHA" \
          --tier standard --gate "$GATE_RESULT" \
          --url "$ORCAROUTER_URL" \
          --engine-version "$ENGINE_VERSION"

    # The 👀 said "I am looking at this". Once the review has been posted — or
    # has failed and said so — that is no longer true, and a reaction nobody
    # removes stops carrying information: every PR the reviewer has ever touched
    # wears one for ever, so the operator cannot tell an in-flight run from a
    # finished one. Placing it and leaving it is the same as not placing it.
    #
    # always(), because a FAILED run has to clear it too. That is the case where a
    # stale pair of eyes is worst: it promises a review that is not coming.
    #
    # Only OUR OWN reaction. The endpoint deletes by id, so this lists first and
    # removes the one whose user matches the token's identity — a maintainer who
    # also reacted 👀 keeps theirs.
    #
    # Best-effort throughout: `|| true` on the deletes and no `set -e`
    # dependency, because failing a run over a leftover emoji would trade a
    # cosmetic problem for a real one.
    - name: Settle the review reactions
      if: always()
      shell: bash
      env:
        GH_TOKEN: ${{ inputs.github-token }}
        REPO: ${{ github.repository }}
        PR_NUMBER: ${{ steps.pr.outputs.number }}
        HEAD_SHA: ${{ steps.pr.outputs.head_sha }}
        EVENT_NAME: ${{ github.event_name }}
        COMMENT_ID: ${{ github.event.comment.id }}
      run: |
        # ONE GATE FOR BOTH REACTIONS: is this token an app?
        #
        # GitHub cannot be asked "which reaction did I create" after the fact, so
        # the only handle is the author — and when github-token is a maintainer's
        # PAT, their manual 👀 or 👍 and ours have the same author. Three rounds
        # of review went into narrowing that predicate with recorded ids and
        # status codes; every version needed a parse, and the parses were where
        # the bugs were. Declining at the boundary removes the question instead
        # of answering it more precisely each time.
        #
        # The review body and the summary say everything the reactions would.
        # ONLY AN EXPLICIT "User" DECLINES. `gh api user` needs a user-scoped
        # token, and github-token defaults to ${{ github.token }} — an
        # installation token, for which that endpoint returns no user. The old
        # `|| echo "Bot"` fallback was meant to cover that and did not: the call
        # can exit 0 with no `.type`, so ME_TYPE came back empty, `!= "Bot"` held,
        # and the reaction was skipped for EVERY consumer on the default token —
        # the case this exists to serve. Measured on a real run: "belongs to a
        # user, not an app" while the reaction author was github-actions[bot].
        #
        # Inverted to fail towards acting: a PAT identifies itself as type User,
        # and anything else — 403, empty, Bot — reacts.
        ME_TYPE=$(gh api user --jq .type 2>/dev/null) || ME_TYPE=""
        if [ "$ME_TYPE" = "User" ]; then
          echo "github-token belongs to a user, not an app; leaving reactions alone"
          exit 0
        fi
        # SAME TRAP AS THE TYPE PROBE, and it survived the fix to that one: with an
        # installation token `gh api user` can exit 0 and print nothing, so
        # `|| echo` never fires and ME came back EMPTY. The delete filter then read
        # `select(.user.login=="")`, matched nothing, and the 👀 stayed on the PR
        # for ever while the step reported success. Observed on a clean run that
        # placed both 👀 and 👍 and cleared neither.
        #
        # Test the VALUE, not the exit status.
        ME=$(gh api user --jq .login 2>/dev/null) || ME=""
        [ -n "$ME" ] || ME="github-actions[bot]"

        # ------------------------------------------------------------------
        # 👀 — it said "I am looking at this", and the run has stopped looking.
        clear_eyes() {
          ids=$(gh api "$1" --paginate \
            --jq '.[] | select(.content=="eyes") | select(.user.login=="'"$ME"'") | .id' \
            2>/dev/null || true)
          for id in $ids; do
            gh api -X DELETE "$1/$id" >/dev/null 2>&1 \
              && echo "cleared 👀 -> $1/$id" || echo "warning: could not clear 👀 (non-fatal)"
          done
        }
        if [ -n "${PR_NUMBER:-}" ]; then
          clear_eyes "repos/$REPO/issues/$PR_NUMBER/reactions"
        fi
        if [ "$EVENT_NAME" = "issue_comment" ] && [ -n "${COMMENT_ID:-}" ]; then
          clear_eyes "repos/$REPO/issues/comments/$COMMENT_ID/reactions"
        fi

        # ------------------------------------------------------------------
        # THE 👍 IS PLACED AND NEVER WITHDRAWN — a product decision, and it
        # deletes more code than it adds rules.
        #
        # Withdrawing was the source of the concurrency problem this step kept
        # growing conditions for: with no serialisation between invocations, an
        # older findings run finishing after a newer clean one removed a thumb
        # that correctly described the current head, and the justification for
        # leaving the delete unguarded — "the current run re-adds it" — only held
        # when the current run finished last, which nothing guarantees. Remove
        # the withdrawal and the whole class goes with it.
        #
        # What it costs, stated plainly: a head that was clean keeps its 👍 after
        # a later push breaks something. The review comment on that later push
        # says so, and the pinned summary says so; the thumb becomes "some head
        # of this PR reviewed clean" rather than "the current one does". The
        # hosted reviewer has made the same trade since it shipped, so the two
        # paths now agree about what the mark means.
        #
        # ONLY FOR THE HEAD THIS RUN REVIEWED, and that guard matters MORE now
        # rather than less: a wrong add is permanent. An unconfirmed head counts
        # as moved — "could not tell" is not evidence that it did not.
        if [ ! -f "$RUNNER_TEMP/cr-clean" ]; then
          echo "not a clean run; leaving 👍 alone"
          exit 0
        fi
        CURRENT_SHA=$(gh api "repos/$REPO/pulls/$PR_NUMBER" --jq .head.sha 2>/dev/null || echo "")
        if [ "$CURRENT_SHA" != "$HEAD_SHA" ]; then
          echo "cannot confirm this run still describes the PR head (${HEAD_SHA} vs ${CURRENT_SHA:-unknown}); leaving 👍 alone"
          exit 0
        fi
        # POSTED UNCONDITIONALLY. Creating a reaction that already exists is a
        # no-op at the API, so there is nothing to look up first — which also
        # means the 👍 no longer depends on resolving our own login, and the
        # custom-App identity gap is confined to clearing 👀.
        gh api -X POST "repos/$REPO/issues/$PR_NUMBER/reactions" -f content=+1 >/dev/null 2>&1           && echo "👍 -> PR #$PR_NUMBER" || echo "warning: could not add 👍 (non-fatal)"

    - name: Clean up engine output
      if: always()
      shell: bash
      run: |
        # Remove only the files THIS run created in $RUNNER_TEMP so review output
        # doesn't linger across jobs on a self-hosted runner. We deliberately do
        # not touch ~/.opencodereview: we never write the shared config (all OCR
        # settings come from env vars), and deleting it would corrupt the OCR
        # state of other jobs/users on the same runner.
        rm -f "$RUNNER_TEMP/result.json" "$RUNNER_TEMP/review.log" \
          "$RUNNER_TEMP/result-final.json" "$RUNNER_TEMP/result-reported.json" \
          "$RUNNER_TEMP/result-posted.json" "$RUNNER_TEMP/result-extra.json" \
          "$RUNNER_TEMP/result-merged.json" \
          "$RUNNER_TEMP/cr-settings.json" "$RUNNER_TEMP/cr-rubric.md" \
          "$RUNNER_TEMP/cr-facts.json" "$RUNNER_TEMP/proxy.out" "$RUNNER_TEMP/proxy.err" \
          "$RUNNER_TEMP/policy-block.json" \
          "$RUNNER_TEMP/pr.diff" "$RUNNER_TEMP/diff-guard.json" "$RUNNER_TEMP/prev-summary.md" \
          "$RUNNER_TEMP/wallclock-timeout" "$RUNNER_TEMP/judge-unavailable" \
          "$RUNNER_TEMP/cr-usage.jsonl" \
          "$RUNNER_TEMP/cr-clean" \
          "$RUNNER_TEMP/result.l1.json" "$RUNNER_TEMP/result.l2.json" \
          "$RUNNER_TEMP/result-extra.l1.json" "$RUNNER_TEMP/result-extra.l2.json" \
          "$RUNNER_TEMP/result.l2.log" "$RUNNER_TEMP/result-extra.l2.log"