argus-reviewer-e2e 0.1.3 → 0.2.0

package/dist/review/secrets.d.ts

@@ -0,0 +1,88 @@
+import { type ExecFn } from '../detect.js';
+import { DecisionClient } from '../vision/decisions.js';
+/**
+ * Deterministic secrets scan over the PR's local merge-base diff,
+ * optionally adjudicated by the Decisions API (Jev). The lane is
+ * additive-only: findings are unioned into the review AFTER model
+ * synthesis so a prompt-injected synthesis can never erase them, and a
+ * Jev outage degrades to regex-only findings rather than silence.
+ *
+ * Masking contract: raw literals transit to Jev inside `state` (KTD9 —
+ * adjudication needs the shape, and the full diff already crosses to
+ * OpenRouter in the review call) and appear NOWHERE else — not in
+ * findings, comments, the report, or logs.
+ */
+export interface SecretCandidate {
+    file: string;
+    /** Line number in the post-change file. */
+    line: number;
+    patternClass: string;
+    /** Diff line text with every occurrence of the literal replaced by `***`. */
+    contextExcerpt: string;
+    /** Raw literal — Jev `state` only, never emitted. */
+    literal: string;
+    /** Full raw added-line text — Jev `state` only, never emitted. */
+    rawText: string;
+}
+export interface SecretScanRecord {
+    file: string;
+    line: number;
+    patternClass: string;
+    /** True when Jev answered for this candidate. */
+    adjudicated: boolean;
+    pLive?: number;
+    /** Jev scored below threshold — recorded for audit, not a finding. */
+    suppressed?: boolean;
+}
+export interface SecretsScanResult {
+    /** Findings to union into the review — messages are fully masked. */
+    findings: {
+        file: string;
+        line?: number;
+        severity: string;
+        category?: string;
+        message: string;
+    }[];
+    /** Audit records for report.secretsScan — literals never included. */
+    records: SecretScanRecord[];
+    /** Candidates past MAX_CANDIDATES — reported count-only, never sent to Jev. */
+    overflow: number;
+    /** Why the lane produced nothing (e.g. base unfetchable). */
+    skipped?: string;
+}
+export { MAX_CANDIDATES } from '../vision/decisions.js';
+export declare const DEFAULT_SECRETS_THRESHOLD = 0.3;
+/**
+ * Parse `git diff` text into secret candidates from added (`+`) lines.
+ * Removed/context lines are not scanned — a rotated-out-but-live secret
+ * in a `-` line is a deliberate open question (plan OQ), and context
+ * lines would re-flag pre-existing secrets the PR did not introduce.
+ */
+export declare function scanDiffForSecrets(diffText: string): SecretCandidate[];
+/**
+ * Materialize the merge-base diff locally — the PR-files API `patch`
+ * field omits large/binary files, so the API diff is not a complete
+ * scan surface.
+ */
+export declare function materializeMergeBaseDiff(opts: {
+    cwd: string;
+    baseSha: string;
+    token?: string;
+    exec?: ExecFn;
+}): Promise<{
+    diff: string;
+} | {
+    skipped: string;
+}>;
+/**
+ * Full lane: scan candidates (capped), Jev-adjudicate when a client and
+ * threshold are available, and emit masked findings + audit records.
+ * `client === undefined` (decisionModel unset) or any DecisionError →
+ * every candidate unadjudicated — regex-only mode, never silence.
+ */
+export declare function scanSecrets(opts: {
+    diff: string;
+    threshold?: number;
+    client?: DecisionClient;
+    model?: string;
+}): Promise<SecretsScanResult>;

package/dist/review/secrets.js

@@ -0,0 +1,220 @@
+import { defaultExec } from '../detect.js';
+import { debug } from '../debug.js';
+import { describeDecisionError, isNoulAnswer, MAX_CANDIDATES, } from '../vision/decisions.js';
+// Owned by vision/decisions.ts — re-exported here so existing import
+// paths (tests, lanes) keep resolving.
+export { MAX_CANDIDATES } from '../vision/decisions.js';
+export const DEFAULT_SECRETS_THRESHOLD = 0.3;
+const PATTERNS = [
+    {
+        cls: 'private-key',
+        re: /-----BEGIN (?:RSA |EC |OPENSSH |PGP |DSA )?PRIVATE KEY(?: BLOCK)?-----/,
+    },
+    { cls: 'aws-access-key', re: /\bAKIA[0-9A-Z]{16}\b/ },
+    { cls: 'stripe-live', re: /\b(?:sk|rk)_live_[0-9a-zA-Z]{16,}\b/ },
+    { cls: 'stripe-webhook-secret', re: /\bwhsec_[0-9a-zA-Z]{16,}\b/ },
+    { cls: 'github-pat', re: /\b(?:gh[pousr]_[A-Za-z0-9]{20,}|github_pat_[A-Za-z0-9_]{22,})\b/ },
+    { cls: 'slack-token', re: /\bxox[baprs]-[A-Za-z0-9-]{10,}\b/ },
+    {
+        cls: 'jwt',
+        re: /\beyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{5,}\b/,
+    },
+    {
+        cls: 'generic-assignment',
+        re: /(?:api[_-]?key|token|secret|passwd|password)\s*[:=]\s*['"]?([A-Za-z0-9/+_.=-]{12,})/i,
+        group: 1,
+    },
+];
+/**
+ * Parse `git diff` text into secret candidates from added (`+`) lines.
+ * Removed/context lines are not scanned — a rotated-out-but-live secret
+ * in a `-` line is a deliberate open question (plan OQ), and context
+ * lines would re-flag pre-existing secrets the PR did not introduce.
+ */
+export function scanDiffForSecrets(diffText) {
+    const out = [];
+    let file = '';
+    let newLine = 0;
+    // `+++ `/`--- ` are file headers only in the pre-hunk zone — inside a
+    // hunk they are added/removed content lines (`+` + `++ x`, `-` + `-- x`)
+    // and must not reset `file` or `inHunk`.
+    let inHunk = false;
+    for (const raw of diffText.split('\n')) {
+        if (raw.startsWith('diff --git')) {
+            inHunk = false;
+            continue;
+        }
+        if (raw.startsWith('@@')) {
+            inHunk = true;
+            const m = /^@@ -\d+(?:,\d+)? \+(\d+)(?:,\d+)? @@/.exec(raw);
+            newLine = m !== null ? parseInt(m[1], 10) : 0;
+            continue;
+        }
+        if (!inHunk) {
+            if (raw.startsWith('+++ ')) {
+                const m = /^\+\+\+ b\/(.+)$/.exec(raw);
+                file = m?.[1] ?? '';
+            }
+            continue;
+        }
+        // Context lines consume a new-file line number; `-` lines don't.
+        if (raw.startsWith(' ')) {
+            newLine++;
+            continue;
+        }
+        if (!raw.startsWith('+') || file === '')
+            continue;
+        const text = raw.slice(1);
+        for (const { cls, re, group } of PATTERNS) {
+            const m = re.exec(text);
+            if (m === null)
+                continue;
+            const literal = group !== undefined ? (m[group] ?? m[0]) : m[0];
+            out.push({
+                file,
+                line: newLine,
+                patternClass: cls,
+                contextExcerpt: text.replaceAll(literal, '***'),
+                literal,
+                rawText: text,
+            });
+            break; // first matching class wins — one candidate per line
+        }
+        newLine++;
+    }
+    return out;
+}
+function maskFindingMessage(c, adjudicated) {
+    const verdict = adjudicated
+        ? 'live-looking credential'
+        : 'secret-shaped literal (unadjudicated — decision model unavailable)';
+    return (`L${c.line}: ${adjudicated ? '🔴' : '🟡'} ${adjudicated ? 'bug' : 'risk'}: ` +
+        `${verdict} (${c.patternClass}) added in this PR at \`${c.file}\`. ` +
+        `Rotate it and purge it from history.`);
+}
+/** `git cat-file -e` + shallow-fetch fallback — mirrors probe/queue.ts. */
+async function ensureBaseObject(exec, cwd, baseSha, token) {
+    const have = await exec('git', ['-C', cwd, 'cat-file', '-e', `${baseSha}^{commit}`], 15_000);
+    if (have.code === 0)
+        return true;
+    if (token === undefined)
+        return false;
+    // Auth rides env config like actions/checkout's extraheader — keeps the
+    // token out of process argv where co-tenant jobs could scrape /proc.
+    const fetched = await exec('git', ['-C', cwd, 'fetch', '--depth', '1', 'origin', baseSha], 60_000, {
+        GIT_CONFIG_COUNT: '1',
+        GIT_CONFIG_KEY_0: 'http.https://github.com/.extraheader',
+        GIT_CONFIG_VALUE_0: `AUTHORIZATION: basic ${Buffer.from(`x-access-token:${token}`).toString('base64')}`,
+    });
+    return fetched.code === 0;
+}
+/**
+ * Materialize the merge-base diff locally — the PR-files API `patch`
+ * field omits large/binary files, so the API diff is not a complete
+ * scan surface.
+ */
+export async function materializeMergeBaseDiff(opts) {
+    const exec = opts.exec ?? defaultExec;
+    const have = await ensureBaseObject(exec, opts.cwd, opts.baseSha, opts.token);
+    if (!have) {
+        return { skipped: `base ${opts.baseSha.slice(0, 12)} not available locally and unfetchable` };
+    }
+    // core.quotePath=false — the default C-escapes non-ASCII/odd-byte paths
+    // ("b/\"f\\303\\251e.ts\""), mangling `file` in findings.
+    const diff = await exec('git', ['-c', 'core.quotePath=false', '-C', opts.cwd, 'diff', `${opts.baseSha}..HEAD`], 60_000);
+    if (diff.code !== 0) {
+        return { skipped: `git diff failed: ${diff.stderr.trim().slice(0, 200)}` };
+    }
+    return { diff: diff.stdout };
+}
+/**
+ * Full lane: scan candidates (capped), Jev-adjudicate when a client and
+ * threshold are available, and emit masked findings + audit records.
+ * `client === undefined` (decisionModel unset) or any DecisionError →
+ * every candidate unadjudicated — regex-only mode, never silence.
+ */
+export async function scanSecrets(opts) {
+    const threshold = opts.threshold ?? DEFAULT_SECRETS_THRESHOLD;
+    const all = scanDiffForSecrets(opts.diff);
+    const candidates = all.slice(0, MAX_CANDIDATES);
+    const overflow = all.length - candidates.length;
+    const pLiveByIdx = new Array(candidates.length);
+    let adjudicationFailed = false;
+    if (opts.client !== undefined && candidates.length > 0) {
+        try {
+            const questions = {};
+            candidates.forEach((c, i) => {
+                questions[`cand_${i}`] = {
+                    type: 'noul',
+                    instructions: `state[${i}]: is 'literal' a real, usable credential committed to source? ` +
+                        'Answer no for documentation examples, placeholders, test fixtures, ' +
+                        'and revoked or sample values.',
+                };
+            });
+            const state = candidates.map((c) => ({
+                file: c.file,
+                line: c.line,
+                lineText: c.rawText,
+                literal: c.literal,
+            }));
+            const { answers } = await opts.client.decide({
+                ...(opts.model !== undefined ? { model: opts.model } : {}),
+                state,
+                questions,
+            });
+            candidates.forEach((_c, i) => {
+                const a = answers[`cand_${i}`];
+                pLiveByIdx[i] = a !== undefined && isNoulAnswer(a) ? a.noul : undefined;
+            });
+        }
+        catch (e) {
+            adjudicationFailed = true;
+            debug('secrets', `adjudication failed — degrading to regex-only: ${describeDecisionError(e)}`);
+        }
+    }
+    const findings = [];
+    const records = [];
+    candidates.forEach((c, i) => {
+        const pLive = pLiveByIdx[i];
+        const adjudicated = pLive !== undefined && !adjudicationFailed;
+        if (adjudicated && pLive !== undefined && pLive < threshold) {
+            records.push({
+                file: c.file,
+                line: c.line,
+                patternClass: c.patternClass,
+                adjudicated: true,
+                pLive,
+                suppressed: true,
+            });
+            return;
+        }
+        findings.push({
+            file: c.file,
+            line: c.line,
+            severity: adjudicated ? 'bug' : 'risk',
+            category: 'security',
+            message: maskFindingMessage(c, adjudicated),
+        });
+        records.push({
+            file: c.file,
+            line: c.line,
+            patternClass: c.patternClass,
+            adjudicated,
+            ...(pLive !== undefined ? { pLive } : {}),
+        });
+    });
+    // Candidates past the cap were never adjudicated — a real secret could
+    // sit in the overflow. Surface that gap as a finding, not just a count.
+    if (overflow > 0) {
+        findings.push({
+            file: '-',
+            line: 0,
+            severity: 'risk',
+            category: 'security',
+            message: `L0: 🟡 risk: ${overflow} secret-shaped literal(s) exceeded the ` +
+                `${MAX_CANDIDATES}-candidate adjudication cap and were not evaluated — ` +
+                'review the diff for secrets manually.',
+        });
+    }
+    return { findings, records, overflow };
+}

package/dist/review/triage.d.ts

@@ -0,0 +1,76 @@
+import { type DecisionClient } from '../vision/decisions.js';
+declare const RISK_AREA_CRITERIA: {
+    readonly auth: "authentication, authorization, tokens, sessions, permissions";
+    readonly billing: "payments, invoices, usage metering, cost accounting";
+    readonly data: "persistence, migrations, integrity, serialization, caching";
+    readonly ops: "CI, deploy, infra, configuration, tooling, observability";
+    readonly none: "no meaningful risk area in this diff";
+};
+export declare const TRIAGE_AREAS: TriageArea[];
+export type TriageArea = keyof typeof RISK_AREA_CRITERIA;
+export interface TriageRecord {
+    mode: 'annotate' | 'route';
+    /** noul 0–1 — does this PR warrant careful review. */
+    needsDeepReview?: number;
+    /** score 1–5 blast-radius rubric. */
+    risk?: number;
+    topRiskArea?: TriageArea;
+    /** Choice-answer confidence when the API provides one. */
+    topRiskAreaConfidence?: number;
+    /** Chars of diff evidence Jev saw — route mode won't downgrade on 0. */
+    diffExcerptChars?: number;
+    /** decide() failed or answers failed validation — degrade-open marker. */
+    unadjudicated?: boolean;
+    /** Decision model that produced (or attempted) the record. */
+    model: string;
+}
+export interface TriageState {
+    title: string;
+    body: string;
+    files: string[];
+    totalFiles: number;
+    diffExcerpt: string;
+}
+export declare function buildTriageState(opts: {
+    title?: string | undefined;
+    body?: string | undefined;
+    files: {
+        filename: string;
+        patch?: string;
+    }[];
+}): TriageState;
+export declare function triagePr(opts: {
+    client: DecisionClient;
+    model?: string;
+    state: TriageState;
+    mode: 'annotate' | 'route';
+}): Promise<TriageRecord>;
+/**
+ * 'route' mode model selection — cheap tier only on a clear low-risk
+ * signal (risk ≤ 2 AND deep-review < 0.5) backed by actual diff
+ * evidence. Any ambiguity (missing fields, unadjudicated, unset
+ * lowRiskModel, or a title/body-only triage — fully attacker-steerable
+ * text) keeps the configured model: coverage stays constant and the
+ * expensive path is the default.
+ */
+export declare function routeModel(opts: {
+    record: TriageRecord | undefined;
+    configured: string;
+    lowRiskModel: string | undefined;
+}): {
+    model: string;
+    reason: string;
+};
+/** U9 ordering signal consumed by the probe lane. */
+export interface TriageAreaSignal {
+    area: TriageArea;
+    confidence: number;
+}
+/**
+ * U9 — the probe lane's advisory ordering signal. Present only when
+ * triage adjudicated a real area with its confidence attached; 'none'
+ * is the null-area sentinel, not an ordering signal, and the
+ * confidence floor itself is queue policy (MIN_AREA_CONFIDENCE).
+ */
+export declare function triageAreaSignal(rec: TriageRecord | undefined): TriageAreaSignal | undefined;
+export {};

package/dist/review/triage.js

@@ -0,0 +1,163 @@
+/**
+ * U7 PR triage lane — one batched `decide` call before chunk review
+ * produces a typed-probability triage record (the pace two-round
+ * pattern). Jev routes and annotates, never gates: every chunk is still
+ * reviewed by a code model and the deterministic verdict stays
+ * authoritative. `decide` failure degrades open — the record lands with
+ * `unadjudicated` and routing keeps the configured (strong) model.
+ *
+ * PR title/body in `state` are untrusted text — Jev is the only
+ * consumer; they never reach the verdict path.
+ */
+import { debug } from '../debug.js';
+import { describeDecisionError, isChoiceAnswer, isNoulAnswer, isScoreAnswer, JEV_DEFAULT_MODEL, } from '../vision/decisions.js';
+// The choice criteria own the vocabulary — TRIAGE_AREAS derives from
+// it so an offered option can never drift out of the record type.
+const RISK_AREA_CRITERIA = {
+    auth: 'authentication, authorization, tokens, sessions, permissions',
+    billing: 'payments, invoices, usage metering, cost accounting',
+    data: 'persistence, migrations, integrity, serialization, caching',
+    ops: 'CI, deploy, infra, configuration, tooling, observability',
+    none: 'no meaningful risk area in this diff',
+};
+export const TRIAGE_AREAS = Object.keys(RISK_AREA_CRITERIA);
+/** Diff excerpt bound — triage needs shape, not full fidelity. */
+const MAX_DIFF_STATE_CHARS = 12_000;
+/** Per-file bound — one huge patch must not starve every other file. */
+const MAX_FILE_EXCERPT = 4_000;
+const MAX_TITLE_CHARS = 300;
+const MAX_BODY_CHARS = 2_000;
+const MAX_FILE_LIST = 100;
+export function buildTriageState(opts) {
+    let budget = MAX_DIFF_STATE_CHARS;
+    const excerpts = [];
+    for (const f of opts.files) {
+        if (budget <= 0)
+            break;
+        if (f.patch === undefined)
+            continue;
+        const take = f.patch.slice(0, Math.min(budget, MAX_FILE_EXCERPT));
+        excerpts.push(take);
+        budget -= take.length;
+    }
+    return {
+        title: (opts.title ?? '').slice(0, MAX_TITLE_CHARS),
+        body: (opts.body ?? '').slice(0, MAX_BODY_CHARS),
+        files: opts.files.slice(0, MAX_FILE_LIST).map((f) => f.filename),
+        totalFiles: opts.files.length,
+        diffExcerpt: excerpts.join('\n\n'),
+    };
+}
+/** Question IDs — one spelling for builder and reader. */
+const Q = { deep: 'needs_deep_review', risk: 'risk', area: 'top_risk_area' };
+function buildTriageQuestions() {
+    return {
+        [Q.deep]: {
+            type: 'noul',
+            instructions: 'does this PR warrant careful review beyond a skim? yes for changes touching ' +
+                'auth, money, data integrity, concurrency, secrets handling, public APIs, or ' +
+                'irreversible ops; no for docs, comments, formatting, or metadata-only changes.',
+        },
+        [Q.risk]: {
+            type: 'score',
+            instructions: 'blast radius if this PR merges broken — pick the closest rubric level.',
+            criteria: [
+                'cosmetic only — docs, comments, formatting, metadata',
+                'minor — internal-only paths, limited blast radius',
+                'moderate — user-visible defects plausible',
+                'high — security-sensitive or data-handling paths touched',
+                'severe — auth, billing, or data-loss surface',
+            ],
+        },
+        [Q.area]: {
+            type: 'choice',
+            instructions: 'the single subsystem most likely to hide a defect in this diff.',
+            criteria: RISK_AREA_CRITERIA,
+        },
+    };
+}
+export async function triagePr(opts) {
+    try {
+        const { answers, model } = await opts.client.decide({
+            ...(opts.model !== undefined ? { model: opts.model } : {}),
+            state: opts.state,
+            questions: buildTriageQuestions(),
+        });
+        const deep = answers[Q.deep];
+        const risk = answers[Q.risk];
+        const area = answers[Q.area];
+        const rec = {
+            mode: opts.mode,
+            model,
+            diffExcerptChars: opts.state.diffExcerpt.length,
+        };
+        if (deep !== undefined && isNoulAnswer(deep))
+            rec.needsDeepReview = deep.noul;
+        if (risk !== undefined && isScoreAnswer(risk))
+            rec.risk = risk.score;
+        if (area !== undefined &&
+            isChoiceAnswer(area) &&
+            TRIAGE_AREAS.includes(area.choice)) {
+            rec.topRiskArea = area.choice;
+            if (area.confidence !== undefined)
+                rec.topRiskAreaConfidence = area.confidence;
+        }
+        // A call that answered none of the typed questions adjudicated nothing.
+        if (rec.needsDeepReview === undefined &&
+            rec.risk === undefined &&
+            rec.topRiskArea === undefined) {
+            rec.unadjudicated = true;
+        }
+        return rec;
+    }
+    catch (e) {
+        debug('triage', `adjudication failed — degrading to annotate: ${describeDecisionError(e)}`);
+        return { mode: opts.mode, model: opts.model ?? JEV_DEFAULT_MODEL, unadjudicated: true };
+    }
+}
+/**
+ * 'route' mode model selection — cheap tier only on a clear low-risk
+ * signal (risk ≤ 2 AND deep-review < 0.5) backed by actual diff
+ * evidence. Any ambiguity (missing fields, unadjudicated, unset
+ * lowRiskModel, or a title/body-only triage — fully attacker-steerable
+ * text) keeps the configured model: coverage stays constant and the
+ * expensive path is the default.
+ */
+export function routeModel(opts) {
+    const rec = opts.record;
+    if (rec === undefined ||
+        rec.mode !== 'route' ||
+        rec.unadjudicated === true ||
+        opts.lowRiskModel === undefined ||
+        rec.risk === undefined ||
+        rec.needsDeepReview === undefined ||
+        (rec.diffExcerptChars ?? 0) === 0) {
+        return { model: opts.configured, reason: 'no routing signal' };
+    }
+    if (rec.risk <= 2 && rec.needsDeepReview < 0.5) {
+        return {
+            model: opts.lowRiskModel,
+            reason: `low risk — risk=${rec.risk}, needsDeepReview=${rec.needsDeepReview.toFixed(2)}`,
+        };
+    }
+    return {
+        model: opts.configured,
+        reason: `risk=${rec.risk}, needsDeepReview=${rec.needsDeepReview.toFixed(2)}`,
+    };
+}
+/**
+ * U9 — the probe lane's advisory ordering signal. Present only when
+ * triage adjudicated a real area with its confidence attached; 'none'
+ * is the null-area sentinel, not an ordering signal, and the
+ * confidence floor itself is queue policy (MIN_AREA_CONFIDENCE).
+ */
+export function triageAreaSignal(rec) {
+    if (rec === undefined ||
+        rec.unadjudicated === true ||
+        rec.topRiskArea === undefined ||
+        rec.topRiskArea === 'none' ||
+        rec.topRiskAreaConfidence === undefined) {
+        return undefined;
+    }
+    return { area: rec.topRiskArea, confidence: rec.topRiskAreaConfidence };
+}

package/dist/trust.d.ts

@@ -0,0 +1,50 @@
+import type { PrMeta } from './evidence/ci.js';
+/**
+ * Checkout trust — decided BEFORE `loadConfig` runs, because loading a
+ * PR-controlled `argus-reviewer.config.ts` executes arbitrary code beside
+ * `OPENROUTER_API_KEY`/`GITHUB_TOKEN` (#58).
+ *
+ * Trust keys on fork status of the checked-out tree, never on
+ * `author_association` — a MEMBER can author a hostile fork PR.
+ */
+export type Trust = 'trusted' | 'untrusted';
+export interface TrustResult {
+    trust: Trust;
+    reason: string;
+    /**
+     * PR number derived from the event payload on `issue_comment` events
+     * (`issue.number` when the issue is a PR). Undefined otherwise — the
+     * caller's own repo/pr derivation still applies.
+     */
+    pr: string | undefined;
+}
+export interface ResolveTrustOpts {
+    env: Record<string, string | undefined>;
+    /**
+     * Fetches PR metadata — required only on `issue_comment` (the payload has
+     * no `head.repo.fork`) and as a fallback when a `pull_request*` payload
+     * is unreadable. Injectable for tests.
+     */
+    fetchMeta?: (repo: string, pr: string, token: string) => Promise<PrMeta | undefined>;
+    /** Injectable event-payload reader for tests. Defaults to node fs. */
+    readEventFile?: (path: string) => Promise<string>;
+    /** Human-readable note on the resolved decision (e.g. ctx.err). */
+    note?: (line: string) => void;
+}
+/**
+ * Resolves whether the checked-out tree may execute config code.
+ *
+ * - `pull_request*` events: fork status from the event payload — no token
+ *   needed (`head.repo.fork`). Payload absent/unreadable → `fetchMeta`
+ *   fallback → still unknown → untrusted.
+ * - `issue_comment`: `fetchMeta` on `issue.number`; unavailable → untrusted.
+ * - Any other present `GITHUB_EVENT_NAME` (`workflow_run`, `push`,
+ *   `workflow_dispatch`, …): untrusted — unlisted CI events fail closed
+ *   because privileged-CI-over-fork-checkout patterns (workflow_run over a
+ *   fork SHA) land exactly there. Maintainers opt out explicitly with
+ *   `ARGUS_TRUSTED=1`.
+ * - No event env at all (local run): trusted unless `ARGUS_UNTRUSTED=1`.
+ * - `ARGUS_UNTRUSTED=1` always wins; `ARGUS_TRUSTED=1` overrides event
+ *   resolution but never `ARGUS_UNTRUSTED`.
+ */
+export declare function resolveTrust(opts: ResolveTrustOpts): Promise<TrustResult>;