import type { GhPR, GhCheck, GhComment } from "./gh.js";
import type { MergePolicy } from "./config.js";
export type CiState = "passing" | "failing" | "pending" | "none";
/**
 * Every PR state, **in ladder order, highest first** — the same order
 * `classifyPR` decides in and `loop-mode.md` § "Reconcile playbook" documents.
 *
 * A VALUE, not only a type, so a consumer that must handle all of them (the
 * inbox's icon map) can be pinned to the list instead of quietly rendering a
 * bare dot for a state someone added in one file.
 */
export declare const PR_STATES: readonly ["reporter_corrected", "awaiting_reporter", "conflict", "ci_failing", "changes_requested", "review_comments", "ci_pending", "approved_ready", "stale", "awaiting_review"];
export type PRState = (typeof PR_STATES)[number];
/** The `reasons` token for an intent-gated PR (#402) — the same string as the
 *  label the server adds/removes, so the row names the exact thing to look for. */
export declare const REPORTER_REVIEW_REASON: "needs-reporter-review";
/** The `reasons` token that says a fresh reporter CORRECTION is sitting on a
 *  gated PR (#442). It rides beside `REPORTER_REVIEW_REASON`, never instead of
 *  it — the gate is still armed; only the dispatch changed. */
export declare const REPORTER_CORRECTION_REASON = "reporter_correction";
/** The `reasons` token on a gated PR that has a correction the loop may no
 *  longer act on: `max-fix-attempts` reworks have already been spent (#442).
 *  Visible, not silent — a correction that stops being actioned must say so, or
 *  this fix trades park-forever for rework-then-park-forever. */
export declare const REWORK_CEILING_REASON = "rework_ceiling";
/** The `reasons` token on a gated PR carrying human-shaped comments the
 *  detector REFUSED to read, because the PR has no legible loop trail
 *  (`correctionTrailUnreadable`). A visible refusal, never a silent one. */
export declare const CORRECTION_UNREADABLE_REASON = "correction_unreadable";
/** The `reasons` token on a gated PR whose gate has simply STOOD — past
 *  `stale-pr-hours`, with no reporter answer of any kind (#439).
 *
 *  The ladder ranks `awaiting_reporter` (index 1) far above `stale` (index 8)
 *  and the `intentBlocked` branch short-circuits before the `ageHours >=
 *  staleHours` test ever runs, so a gated PR could never age into `stale`. With
 *  `needsAction` excluding `awaiting_reporter`, that left an intent-gated PR
 *  with **no aging path and no exit** but a human comment the loop cannot
 *  cause — measured live on PRs #401/#418, gated + CONFLICTING and silent for
 *  days.
 *
 *  The ladder is NOT reordered to fix that, and no `awaiting_reporter_stale`
 *  state is added. Reordering re-admits dispatch on an unconfirmed
 *  interpretation, which is the whole point of #436/#402; a new state
 *  duplicates the parked/WIP/summary plumbing for no new routing. And `stale`'s
 *  own documented handler is "nudge the PR" — a bare `gh pr comment`, i.e. the
 *  unmarked author-side comment that manufactures a phantom correction (#477).
 *  So the gate ages into the mechanism that already exists and is proven:
 *  escalate ONCE, then re-park. */
export declare const REPORTER_GATE_STALE_REASON = "reporter_gate_stale";
/** The three refusals whose documented handler is `issue escalate` ONCE — the
 *  loop may not rework, and it may not silently drop the thread either
 *  (loop-mode.md § "A reporter correction", the `Ceiling`,
 *  `correction_unreadable` and gate-stale rows).
 *
 *  All land on a PARKED `awaiting_reporter` row, and Phase A iterates on
 *  `needsAttention` — so as shipped the escalation the doc requires could never
 *  be dispatched from a row, and the ceiling case ended as the exact
 *  rework-then-park-forever this issue set out to remove (PR #446 review,
 *  finding 6). The state is right and stays: what changed is that the ROW is
 *  actionable while the escalation is still owed. Once-ness is decided by the
 *  parent issue's `needs-human` label — data the inbox already fetches — so the
 *  row falls back to parked the moment the escalation exists (`inbox.ts`).
 *
 *  ⚠️ Once-ness is NO LONGER decided by the parent's `needs-human` label (issue
 *  #488): the server removes that label on any human reply, so the key it was
 *  standing in for was erased by design and the row re-escalated every tick.
 *  The key is now a per-(PR, reason) comment marker — which also sets the cap:
 *  a PR can earn AT MOST one escalation per entry in this list, ever. */
export declare const ESCALATE_ONCE_REASONS: readonly string[];
/** Does this row still OWE an escalation? True on a parked gated PR carrying
 *  one of `ESCALATE_ONCE_REASONS`. Says nothing about whether one has already
 *  been filed — that is the caller's half (it needs the parent's comments). */
export declare function owesEscalation(cl: Pick<PRClassification, "reasons">): boolean;
/** WHICH escalate-once reasons this row carries — each one the second half of
 *  its own once-key, and the value the orchestrator passes back as
 *  `issue escalate --once-reason`.
 *
 *  A LIST, not one reason (issue #488): a row can carry more than one refusal,
 *  and each earns exactly one escalation. Returning only the first would park
 *  the row for good the moment that first key was filed, swallowing the second
 *  refusal — so the caller walks this list and takes the first entry with no
 *  marker on file. Always in `ESCALATE_ONCE_REASONS` order so the same tick
 *  cannot file under a different key each time (which would make "once"
 *  unenforceable). Empty when the row owes nothing. */
export declare function escalationReasonsOwed(cl: Pick<PRClassification, "reasons">): string[];
/** Per-check policy. `ciStateOf` rolls this up; do not add a fourth matcher. */
export declare function classifyCheck(c: GhCheck): CiState;
/** Collapse the status-check rollup into one CI verdict. */
export declare function ciStateOf(checks: GhCheck[] | undefined): CiState;
/**
 * Why an open PR may need follow-up. Empty = nothing to do. "review_comments" is
 * advisory (the comment may already be addressed); "changes_requested" and
 * "ci_failing" are definite.
 */
export declare function prAttentionReasons(pr: GhPR, me: string): string[];
/** The newest comment on an issue if it's from someone other than `me` (i.e. you
 * may owe a reply); otherwise null. */
export declare function issueNeedsReply(comments: GhComment[], me: string): GhComment | null;
/** Does this PR carry a `shipflow-approved`-style label? The label alone is
 *  not approval (issue #637) — `isApproved` also requires a matching head SHA. */
export declare function hasApprovalLabel(pr: Pick<GhPR, "labels">): boolean;
/** 40-char lowercase hex, or null. Missing / short / garbage fails closed. */
export declare function commitSha(value: unknown): string | null;
/** OPEN token `pr approve` stamps on the attestation comment (issue #637). */
export declare const APPROVED_HEAD_MARKER: "<!-- shipflow:approved-head";
/** The exact line `pr approve` writes — `sha` is the reviewed head. */
export declare function renderApprovedHeadMarker(sha: string): string;
/**
 * The reviewed head SHA stamped on this PR's comments, or null.
 *
 * Fail closed: quote-stripped, own-line (column 0 — leading spaces are a
 * markdown code block, not a stamp), 40-hex only. Latest valid marker wins
 * so a re-approve after a real re-review rebinds. A missing or unreadable
 * marker is not a SHA — `isApproved` then refuses the label.
 *
 * Authorization is OWNER / MEMBER / COLLABORATOR only. Undefined association
 * is untrusted. Not `commentAuthorCouldBeLoop`: that also accepts `[bot]` /
 * App NONE, so leftover `shipflow-approved` + a forged `sha=<new head>`
 * would re-approve unreviewed B.
 */
export declare function approvedHeadSha(comments: GhComment[] | undefined): string | null;
/** `mergeDecision` token when the label is present but the head is not the
 *  reviewed SHA (or the SHA is missing/unreadable). The loop keys on this. */
export declare const STALE_APPROVAL_BLOCKER = "stale-approval";
/**
 * Approved via a native GitHub review, or a `shipflow-approved`-style label
 * bound to the current head SHA (issue #637).
 *
 * The label path fails closed: no matching 40-hex marker, an unreadable
 * marker, or a missing current head is not approved. `headSha` overrides
 * `pr.headRefOid` when the caller has a fresher read.
 */
export declare function isApproved(pr: GhPR, headSha?: string | null): boolean;
/** Whole hours since an ISO timestamp. */
export declare function hoursSince(iso: string | undefined, nowMs?: number): number;
/** The intent-gate notice's first line — the comment `pr automerge` posts in the
 *  same breath as APPLYING `needs-reporter-review`, so its timestamp is exactly
 *  "the reporter has been asked since".
 *
 *  It lives here rather than in `commands/pr.ts` because two things now key on
 *  it and they must not drift: the renderer that emits it (and the retry probe
 *  that asks "did the notice land?"), and `gateOpenedAt` below, which reads it
 *  back as the ARMING event. `commands/pr.ts` re-exports it for its callers. */
export declare const INTENT_GATE_NOTICE_HEADLINE = "\u23F8\uFE0F **Merge blocked \u2014 awaiting the reporter's confirmation**";
/**
 * When this PR's intent gate went up **as it currently stands**, as an ISO
 * string. The anchor `gateAgeHours` measures the reporter's wait from.
 *
 * ⚠️ NOT `pr.updatedAt`, and that half is the original point (#439). `updatedAt`
 * is the timer every "PR has gone quiet" check reaches for, and on exactly the
 * PRs this matters for it never fires: the server's gate notice, the near-miss
 * nudge and every reviewer verdict are COMMENTS, and each one resets it.
 * Measured on PR #418 — opened 2026-07-25, `updatedAt` 2026-07-28, zero reporter
 * input in between. A gate-staleness timer keyed on `updatedAt` is a timer the
 * machinery rewinds for itself, forever.
 *
 * ── AND NOT THE OLDEST MACHINERY COMMENT EITHER (PR #487 review, round 2) ────
 * The first implementation took the OLDEST loop comment on the thread. That is
 * not "when the gate went up", it is "when the loop first said anything here" —
 * in practice the PR's whole lifetime — and it failed in the OPPOSITE direction
 * to `updatedAt`: not never, but far too eagerly. Two reviewers reached the same
 * root cause from opposite ends and both probes reproduced:
 *
 *   | probe | reality | old answer | harm |
 *   |---|---|---|---|
 *   | T4 | armed 1h ago, PR 100h old | 101h | escalates a gate the reporter has had ONE HOUR to answer |
 *   | T2 | armed, cleared, re-armed 38h ago | 50h | fires 10h early on a wait that restarted |
 *
 * T4 is `chatgpt-codex-connector`'s: a PR carries trusted ShipFlow comments long
 * before it is gated — the mandatory `loop-review` verdict is posted BEFORE `pr
 * automerge` arms anything — so "oldest marker" dated the verdict, not the gate.
 * T2 is `renaissshipflow`'s: after the #442 flow the PR returns to
 * `awaiting_reporter` on a NEW unconfirmed reading, and the clock never
 * restarted. Both escalations stamp `needs-human` on the parent, permanently
 * rerouting later corrections — so firing early is not a cosmetic error.
 *
 * ── THE RULE ────────────────────────────────────────────────────────────────
 * Scan BACK to the latest arming, never forward to the earliest:
 *
 *   1. the NEWEST arming (`commentArmsGate`) after the LAST clearance;
 *   2. else the last clearance itself — the gate was re-armed by a hand that
 *      posted nothing, and it certainly did not go up before it came down;
 *   3. else `pr.createdAt` — no legible arming at all (the legacy #401 shape).
 *
 * With no clearance on the thread, rule 1 degenerates to "the newest arming",
 * which is the right answer for that case for the same reason. Clearance is the
 * server's attributable audit comment (`isIntentGateAuditComment`, #411/#441) —
 * the artifact, author-checked and anchored, never a bare marker anyone can
 * type.
 *
 * ── WHERE THE CLEARANCE HAS TO COME FROM (issue #650) ───────────────────────
 * `pr.comments` is GRAPHQL, and GraphQL is BLIND TO BOTNESS — the whole of
 * issue #537, restated at this call site. `GhComment` carries no `authorIsBot`
 * field at all, so pass 1 fed `isIntentGateAuditComment` a candidate with the
 * field missing; the predicate insists on a strict `true` (ignorance is not
 * evidence), and the App's own association is `NONE`, so the fallback branch
 * fails too. Both branches false ⇒ **the App's own clearance is invisible
 * here**, exactly as it was in the #537 path. There was never anything to
 * "pass through": the bit does not exist in this payload.
 *
 * So the clearance timestamp is threaded IN, from REST, by the caller
 * (`classifyPR`'s `gateClearedAt` ⇠ `ghIntentGateLastClearedAt`). This module
 * stays I/O-free and does NOT import `gh` — same split as
 * `intentGateEverCleared`/`ghIntentGateClearance`: the read lives in `gh.ts`,
 * the decision lives here and stays pure.
 *
 * The GraphQL pass is KEPT beside it, not replaced: a PAT-backed machine user
 * posts the audit record under a TRUSTED ASSOCIATION, which GraphQL does carry
 * and REST-vs-GraphQL should not disagree about. The two are merged by taking
 * the LATER of the two — a clearance either source can see is a clearance.
 *
 * Failing to read REST leaves `gateClearedAt` undefined, i.e. the pre-#650
 * behaviour: an anchor that can only be too OLD (rule 1 falls back to an
 * earlier arming). That error is one-directional by construction — the age
 * inflates, so the gate can only escalate EARLY, never miss. Neither `state`
 * nor `needsAction` moves either way; `gateAgeHours` feeds only
 * `REPORTER_GATE_STALE_REASON`.
 *
 * Rule 3 is the one anchor that can still be EARLIER than the true arming, and
 * it is deliberately kept: a gated PR whose trail says nothing is the shape this
 * issue was filed about, and a timer that fires early there is better than one
 * that never fires at all. Every legible shape now anchors on the arming itself.
 *
 * @param restClearedAt REST-sourced timestamp of the newest genuine clearance
 *        (`ghIntentGateLastClearedAt`). Optional: absent ⇒ GraphQL-only, which
 *        can only anchor too old.
 */
export declare function gateOpenedAt(pr: GhPR, restClearedAt?: string): string | undefined;
export interface PRClassification {
    number: number;
    state: PRState;
    ciState: CiState;
    approved: boolean;
    ageHours: number;
    reasons: string[];
    needsAction: boolean;
    /** Hours the intent gate has stood unanswered (`gateOpenedAt`). Present ONLY
     *  on an intent-gated row — it is meaningless otherwise — so a consumer can
     *  render "waiting Nh" without re-deriving the anchor. Never NaN: `hoursSince`
     *  answers 0 for a missing or unparseable date. */
    gateAgeHours?: number;
}
/**
 * Reduce a PR to the single next action the loop should take. Priority: a red
 * build and explicit change requests come before advisory comments; pending CI
 * means wait; an approved+green PR is a merge candidate; otherwise it's parked
 * (or stale once it ages past the threshold).
 */
export declare function classifyPR(pr: GhPR, me: string, opts?: {
    staleHours?: number;
    nowMs?: number;
    unresolvedThreads?: number;
    intentBlocked?: boolean;
    /** Rework ceiling for `reporter_corrected` (#442) — the caller passes
     *  `resolveMaxFixAttempts()`; this module stays I/O-free. */
    maxReworks?: number;
    /** REST-sourced timestamp of the newest genuine intent-gate CLEARANCE
     *  (#650). Read by the caller (`ghIntentGateLastClearedAt`) because only
     *  REST carries `user.type`, and `pr.comments` — GraphQL — cannot see that
     *  the ShipFlow App wrote the record; see `gateOpenedAt`. Consumed ONLY
     *  inside the `intentBlocked` branch below, which is why the caller may
     *  skip the read entirely on a non-gated PR. Omitted ⇒ GraphQL-only, an
     *  anchor that can only be too OLD. */
    gateClearedAt?: string;
    /** Current head SHA (issue #637). Overrides `pr.headRefOid`. Missing /
     *  unreadable fails closed on the `shipflow-approved` label path. */
    headSha?: string | null;
}): PRClassification;
export declare const INTENT_BLOCKER = "unconfirmed interpretation \u2014 needs reporter confirmation";
export interface IntentGate {
    blocked: boolean;
    applyLabel: boolean;
}
/**
 * Decide the intent gate from three facts about a PR. Pure + idempotent so
 * `pr ready` (read-only) and `pr automerge` (which also labels) agree on ONE
 * definition:
 *   - blocked  = the needs-reporter-review label is present, OR the body carries
 *                an interpretation signal that has never been through an
 *                apply+clear cycle yet.
 *   - applyLabel = the one-shot side effect: a fresh signal with no label and no
 *                prior clear — automerge adds the label, the server pings once.
 * Once the gate is genuinely cleared, `everCleared` stays true, so the same body
 * no longer re-blocks or re-labels — confirmation is sticky. What counts as
 * "genuinely cleared" is `intentGateEverCleared` below, NOT the bare `unlabeled`
 * timeline event (issue #411).
 */
export declare function intentGate(i: {
    signal: boolean;
    hasLabel: boolean;
    everCleared: boolean;
}): IntentGate;
/** WHICH gate input is blocking — `label`, `signal`, or `both` (issue #444,
 *  second shape). The blocker text used to be identical in every case, so an
 *  operator whose PR was blocked by the BODY SIGNAL alone kept removing a label
 *  that was never there — `gh` exits 0, no `unlabeled` event is written, and the
 *  gate is untouched. Naming the input names the remedy.
 *
 *  Kept OUT of `intentGate`'s return so its truth table (and every consumer of
 *  `{ blocked, applyLabel }`) stays byte-identical. `undefined` when nothing
 *  blocks. Note the label alone can block even after a clearance (`hasLabel`
 *  with `everCleared` — the server re-applied it on a correction), which is why
 *  this derives from the same three facts, not from `blocked`. */
export type IntentBlockedBy = "label" | "signal" | "both";
export declare function intentGateBlockedBy(i: {
    signal: boolean;
    hasLabel: boolean;
    everCleared: boolean;
}): IntentBlockedBy | undefined;
/** The operator-facing detail appended to `INTENT_BLOCKER` — each names the
 *  remedy its input actually responds to. The `signal` line exists because of
 *  issue #444's second shape: "remove the label" is a no-op there. */
export declare const INTENT_BLOCKED_BY_DETAIL: Record<IntentBlockedBy, string>;
/** The audit artifact the server stamps on every `needs-reporter-review`
 *  removal (contract markers.intentGateCleared). Its PRESENCE is what makes a
 *  clearance attributable — it names who cleared the gate and quotes the line
 *  read as their confirmation. */
export declare const INTENT_GATE_AUDIT_MARKER: "<!-- shipflow:intent-gate-cleared";
/** Does this body carry the audit marker in its rendered, ANCHORED shape (the
 *  marker alone on the comment's last non-empty line)?
 *
 *  ⚠️ THE BODY HALF OF THE TEST, AND NOT EVIDENCE ON ITS OWN. Exported only so
 *  the reader in `gh.ts` can log the one diagnostic that matters — "a bot posted
 *  a byte-perfect audit line and the author check rejected it" — which is the
 *  difference between a diagnosable fail-stuck and a silent one. Never call this
 *  to decide clearance: `isIntentGateAuditComment` is that decision, and it is
 *  the author check that turns a body into a record (PR #441). */
export declare function intentGateAuditLineAnchored(body: string): boolean;
/** Trim, case-fold, strip ONE trailing `[bot]`. Exported so the slug RESOLVER
 *  in config.ts normalises identically — two normalisers would let a value
 *  resolve cleanly and then fail the comparison here. */
export declare function normalizeBotLogin(login: string | undefined): string;
/** A comment as far as the audit check is concerned: what it says, and enough
 *  about WHO said it to know whether they could have performed a clearance. */
export interface AuditCandidate {
    body: string;
    /** The author's login. REST renders the App as `renaissshipflow[bot]`;
     *  GraphQL renders the SAME account as `renaissshipflow`. Compared with the
     *  suffix normalised away, so neither shape is privileged. */
    authorLogin?: string;
    /** `authorAssociation` — the fallback for a PAT-backed machine user, whose
     *  login carries no `[bot]` suffix (a real deployment shape). A GitHub App's
     *  association is `NONE`, so this branch never fires for the App itself. */
    authorAssociation?: string;
    /** REST's `user.type === "Bot"` — the ONLY reliable botness signal available
     *  (issue #537). Optional because the type is shared with GraphQL-sourced
     *  candidates that cannot know it; `undefined` is NOT evidence and the check
     *  below insists on a strict `true`. */
    authorIsBot?: boolean;
    /** When the candidate was posted, ISO 8601 (#650). NOT read by
     *  `isIntentGateAuditComment` — the predicate's semantics are unchanged, and
     *  a timestamp can never make a comment more or less authentic. It exists so
     *  the ACCEPTED record can be dated: `gateOpenedAt` needs the moment of the
     *  last genuine clearance, and REST is the only source that can identify one.
     *  Optional for the same reason as `authorIsBot`: a GraphQL-sourced candidate
     *  has no obligation to carry it. */
    createdAt?: string;
}
/**
 * True when a comment IS the intent-gate clearance audit record.
 *
 * Two independent conditions, both required: the body must carry the marker in
 * its rendered, anchored shape, AND the author must be someone who could have
 * performed the removal — the ShipFlow App itself, or a trusted association.
 * Body text alone is a claim; only the author makes it evidence.
 *
 * WHY THE AUTHOR RULE LOOKS LIKE THIS (issue #537). It used to read
 * `login.endsWith("[bot]")`, fed from `gh issue view --json comments` — GraphQL,
 * where a Bot's login has NO `[bot]` suffix and a GitHub App's association is
 * `NONE`. Measured on PR #489: `{bodyMatches: true, endsWithBot: false,
 * assocTrusted: false}`. Both branches were false for the ONE author this check
 * exists to recognise, so the #411 clearance path was dead from the day it
 * landed and every confirmed PR re-armed forever. The reader now comes from REST
 * (`ghIntentGateAuditCandidates`), which carries `user.type`.
 *
 * Two deliberate narrowings came with that widening, because this is an
 * authorization predicate on a merge gate:
 *   - `authorIsBot === true` STRICTLY. A missing field is a candidate from a
 *     source that cannot see botness, which is ignorance, not evidence.
 *   - the login must EQUAL the trusted App slug. `type: "Bot"` is equally true
 *     of `gemini-code-assist[bot]` and `chatgpt-codex-connector[bot]`, which
 *     comment on these very PRs — "any bot" would have swapped a dead control
 *     for a forgeable one.
 * A wrong slug therefore fails STUCK (the reporter replies again, or a
 * maintainer pulls the label by hand — the standing human override), never open.
 *
 * `trustedSlug` IS PER-DEPLOYMENT (PR #542 review). The App slug is runtime
 * config — the server reads `GITHUB_APP_SLUG`, and dev / self-hosted installs run
 * a separate App — so a compile-time constant baked into the published npm
 * package would make those deployments reject their OWN server's valid audit
 * comment, with no edit available to fix it. Callers pass
 * `resolveIntentGateAuditAuthorSlug().slug` (config.ts). Omitted, blank or
 * unresolvable ⇒ the CONTRACT DEFAULT, still compared for equality: absence of a
 * configured slug is not permission, and there is no value of `trustedSlug` that
 * widens this to "any bot".
 *
 * The body rule is UNCHANGED (#411): the marker must still be the comment's last
 * non-empty line, so a quoted, fenced or mid-prose marker stays a claim no
 * matter who posted it. The author rule widened; the body rule did not.
 */
export declare function isIntentGateAuditComment(c: AuditCandidate, trustedSlug?: string): boolean;
/** What the CLI can observe about a PR's past intent-gate clearances. */
export interface ClearanceEvidence {
    /** Comments that ARE the clearance audit record (author-checked, anchored). */
    auditComments: number;
    /** Every `unlabeled` timeline event for the gate label, oldest-first.
     *  `actorKnown` is false when the timeline reported no actor at all. */
    removals: {
        actorIsBot: boolean;
        actorKnown: boolean;
    }[];
}
/**
 * Was this PR's intent gate EVER genuinely cleared?
 *
 * This replaces reading the raw `unlabeled` timeline event, which was the bug
 * behind issue #411's third layer: that event is permanent and says nothing
 * about WHY the label went away. One stray machine strip therefore pinned
 * `blocked=false` AND `applyLabel=false` forever — `pr automerge` could never
 * re-arm the gate, only a human's hand could. The two live instances (PRs #401,
 * #405) both carry exactly such an event.
 *
 * Two things count as a clearance, and a bare bot strip is neither:
 *   - an AUDIT COMMENT — the server records one on every removal it performs,
 *     naming the actor and quoting the trigger line. Counted only when the
 *     comment is genuinely the server's (`isIntentGateAuditComment`), or the
 *     artifact is forgeable by anyone who can type the marker;
 *   - a removal by a KNOWN NON-BOT actor — a maintainer removing the label in
 *     the GitHub UI is the documented human override and must keep working.
 *     Nothing in the ShipFlow CLI removes this label (pinned by a guard test in
 *     `intent-gate-invariant.test.ts`), so such an event is a person acting
 *     deliberately.
 *
 * A bot removal with no audit record is the #411 defect itself: not a
 * clearance, so the gate re-arms on the next pass. So is a removal whose actor
 * the timeline did not report (a deleted account, or GitHub omitting it): an
 * UNKNOWN actor is not evidence of a human override, and reading it as one was
 * the single fail-OPEN branch left in this path (PR #441 review).
 */
export declare function intentGateEverCleared(e: ClearanceEvidence): boolean;
/** The marker a rework worker stamps on the comment it posts after acting on a
 *  correction, rendered by `renderReworkFromMarker`. OPEN token (no trailing
 *  `-->` in the literal) matched with `includes`, like `precedent-applied`. */
export declare const REWORK_FROM_MARKER: "<!-- shipflow:rework-from";
/** Reworks allowed per PR before the loop stops actioning corrections. Mirrors
 *  `max-fix-attempts`' default; callers pass `resolveMaxFixAttempts()`. */
export declare const DEFAULT_MAX_REWORKS = 3;
/** The exact comment line a rework worker must post — `id` is the id of the
 *  correction it acted on. Single-sourced so the doc, the writer and the reader
 *  below cannot drift. */
export declare function renderReworkFromMarker(commentId: string): string;
/**
 * The comment ids this PR's rework markers name, oldest comment first, deduped.
 *
 * Two jobs: `length` is the rework count the ceiling is measured against, and
 * membership is the EXACT idempotency test — "the loop already answered THIS
 * comment" — instead of a timestamp comparison that a re-ordered or edited
 * comment can defeat.
 *
 * Both jobs are AUTHORITY claims, so both are author-scoped (PR #446 review,
 * finding 4). Reading the marker from ANY author let an account that can only
 * comment (`NONE` — every review bot on this repo) control both suppression
 * inputs: one such comment naming a real correction's id suppressed it, and
 * three burned the whole rework budget so the next genuine correction came back
 * `rework_ceiling`. #411 hardened `isIntentGateAuditComment` against exactly
 * this — typing the literal is a CLAIM, not evidence — and this applies the
 * same rule (`commentAuthorCouldBeLoop`). Deduped for the same reason: three
 * copies of one id in one body are one answered comment, not three reworks.
 *
 * Quote-stripped, so quoting a rework comment is not performing one — the same
 * reason the server judges `domain.StripQuotedLines(body)` at its call site.
 */
export declare function reworkAttemptsOn(pr: GhPR): string[];
/**
 * The newest comment on this PR that could be the reporter answering the intent
 * gate — or `null`. Pure, and ZERO extra API calls: `comments` is already in
 * `PR_FIELDS`, and gh returns `id`, `url` and `authorAssociation` inside each
 * comment object (verified against `gh pr list --json comments`).
 *
 * A candidate must clear four independent tests, each fail-CLOSED:
 *
 *  1. **Not machinery** — no `<!-- shipflow:` marker, no 🚧 banner. The only
 *     workable discriminator (see the note above on shared identity), and the
 *     first line of defence against the loop answering itself.
 *  2. **A trusted association** — OWNER / MEMBER / COLLABORATOR, the same set
 *     `headTrust` uses. Missing or unknown is untrusted. This is what keeps a
 *     drive-by comment from an outside account — or a review bot posting under
 *     `NONE`, which is what gemini-code-assist and codex do on every PR here —
 *     from spending a worker cycle.
 *  3. **Not already answered** — its id is not named by a `rework-from` marker,
 *     AND it is strictly newer than the ACTION HORIZON (`correctionHorizon`),
 *     which the same marker sets. The id test is exact; the horizon additionally
 *     settles everything the loop had already seen when it answered.
 *  4. **Not a whole-line confirmation** — the coarse near-miss guard above.
 *
 *  5. **A legible loop trail exists** — at least ONE machinery comment on the
 *     PR. See `scanForCorrection`; this is what makes the horizon meaningful.
 *
 * RESIDUAL RISK, stated rather than hidden: a loop comment carrying no marker,
 * posted through a bare `gh pr comment` AFTER a marked one, satisfies all five
 * and reads as a fresh correction. No content test can distinguish it and an
 * author test cannot exist here. That is why the `rework-from` marker is
 * mandatory in the protocol, why the sanctioned posting paths (`pr approve
 * --comment`, `pr post-review`) stamp a marker for you — and why the ceiling in
 * `classifyPR` is a hard stop rather than advice: it bounds the damage at
 * `max-fix-attempts` reworks instead of forever.
 */
export declare function reporterCorrectionOn(pr: GhPR): GhComment | null;
/**
 * EVERY comment on this PR that could be the reporter answering — oldest first,
 * the order the loop owes them answers in — or `[]`.
 *
 * Why a list and not the newest one (PR #446 review, finding 2). Newest-only
 * selection dropped the real correction the moment ANY chatter followed it:
 * `[gate, "No — scope this to the CLI only.", "thanks for turning this around"]`
 * put the thank-you on the row and made the decision unreachable. That is not an
 * edge case — the gate's own nudge tells reporters to "send it as a SEPARATE
 * comment", so correction-then-note is the DOCUMENTED way to use the gate — and
 * it does not self-heal: the orchestrator is told to park chatter, parking
 * stamps no `rework-from`, so the same chatter is re-offered every tick forever.
 *
 * The whole set goes on the row instead, and the orchestrator picks the decision
 * out of it — the same division of labour this module already states: the CLI
 * answers the deterministic question ("which comments has the loop not answered
 * yet?"), the judgement stays where the judgement already lives. `[0]` is only a
 * default for a caller that wants one, and it is the OLDEST — the decision comes
 * before the thank-you in the shape the nudge asks for.
 */
export declare function reporterCorrectionsOn(pr: GhPR): GhComment[];
/**
 * True when this gated PR has trusted, human-shaped comments the detector
 * REFUSED to read, because the PR carries no legible loop trail at all.
 *
 * Surfaced as a `reasons` token rather than swallowed: a refusal nobody can see
 * is the same failure mode as the park-forever this whole issue is about, one
 * level down. A human reading the row learns "there is something on this thread
 * the loop will not act on", which is exactly true.
 */
export declare function correctionTrailUnreadable(pr: GhPR): boolean;
/** How many unanswered candidates a row carries. The excerpt cap already bounds
 *  each one; this bounds a thread that ran away. Oldest-first, so what is
 *  dropped is the newest chatter on an already-long backlog — and one rework
 *  advances the horizon past all of it anyway. */
export declare const MAX_CORRECTION_CANDIDATES = 5;
/** How much of a correction the inbox row quotes. Long enough for the
 *  orchestrator to judge decision-vs-question without a second API call, short
 *  enough that a pasted stack trace can't bloat every row. */
export declare const CORRECTION_EXCERPT_CHARS = 200;
/** The correction as it rides on the inbox row (issue #442). `id` is carried
 *  because the rework worker must echo it back in its `rework-from` marker. */
export interface ReporterCorrectionRow {
    id: string;
    author: string;
    at: string;
    url: string;
    excerpt: string;
}
/** Flatten a correction onto the row. Whitespace is collapsed so a multi-line
 *  reply stays one readable line in the JSON the orchestrator reads. */
export declare function reporterCorrectionRow(c: GhComment): ReporterCorrectionRow;
/** The issue numbers a PR body links with `Part of #N`, in order, deduped. */
export declare function partOfIssueNumbers(body: string | undefined): number[];
/**
 * Every issue this PR is the work for — closing references FIRST, then any
 * `Part of #N` slice link in the body.
 *
 * `closingIssuesReferences` alone is empty BY DESIGN on a slice PR: `--partial`
 * deliberately emits `Part of #N` with no closing keyword so merging the slice
 * leaves the parent open (issue #367). Reading only the closing references
 * therefore made `parentNeedsHuman` permanently false on exactly those PRs (PR
 * #446 review, finding 5) — and the routing fork keys on it, so a correction on
 * an ESCALATED parent took the rework path instead of the needs-human ANSWER
 * path, the one case loop-mode.md says must never take both protocols. PR #401
 * is this shape, so the live instance was the one the guard missed.
 *
 * Ordered, not merged-and-sorted: a closing reference is the stronger link, so
 * a caller that wants one issue gets the same one it got before.
 */
export declare function linkedIssueNumbers(pr: {
    body?: string;
    closingIssuesReferences?: {
        number: number;
    }[];
}): number[];
export interface MergeDecision {
    policy: MergePolicy;
    wouldMerge: boolean;
    blockers: string[];
    /** True when a blocker can NEVER clear on its own — today: `require-ci` is on
     *  and `ciState` is `none` past `NO_CI_GRACE_HOURS` (issue #305 zero-checks,
     *  issue #696 all-no-verdict). The loop must ESCALATE once instead of
     *  re-polling forever; re-running the same tick can never change the answer. */
    unsatisfiable?: boolean;
}
/** How long a PR may sit with ZERO status checks before we conclude no CI is
 *  coming (issue #305). GitHub posts a pending check within seconds of any
 *  trigger, so a PR older than this with no checks has no PR-triggering CI —
 *  regardless of Actions vs external CI. Kept short so the loop escalates within
 *  a tick or two rather than spinning, but long enough to never race a check
 *  that is about to appear. */
export declare const NO_CI_GRACE_HOURS = 0.25;
/** How long automerge waits after the last head commit for an external review
 *  to land (issue #687). Bots post 1–2 minutes after a push; an immediate
 *  `unresolved: 0` is not a settled measurement. After this window, zero is
 *  accepted — never require a bot forever. No config knob (same as
 *  `FRESH_PROBE_BACKOFF_MS`). */
export declare const REVIEW_SETTLE_MS = 120000;
/** mergeDecision blocker when the head is still inside the settle window and
 *  no external review has landed since. */
export declare const REVIEW_SETTLE_BLOCKER = "external reviews still settling \u2014 last head is too recent and no external review has landed since";
/** mergeDecision blocker when the last-head clock could not be read. */
export declare const REVIEW_SETTLE_UNAVAILABLE = "last-head clock unavailable \u2014 never merge on unknown review-settle state";
/** A formal review or a thread's first comment — anything with an author and
 *  a submit time. `author` accepts both `GhReview` (`{login}`) and
 *  `GhReviewThread` (bare string). */
export type SettleReview = {
    author?: {
        login?: string;
    } | string | null;
    submittedAt?: string;
};
export interface ReviewSettle {
    settled: boolean;
    /** ms until the age path would accept zero reviews. 0 when already aged
     *  or when lastHead is unreadable (do not sleep on an unknown clock). */
    remainingMs: number;
    /** Set only when unready. */
    reason?: "unavailable" | "pending";
}
/**
 * Has this head waited long enough that an immediate `unresolved: 0` can be
 * trusted (issue #687)?
 *
 * Settled iff `lastHeadAt` is ≥ `settleMs` old, OR a review/thread whose
 * author is not `me` has `submittedAt ≥ lastHeadAt`. The loop's own reviews
 * (author === me) do not settle — `shipflow-approved` is our approval label,
 * not an external review, and is not consulted here. After 120s, zero is
 * accepted.
 *
 * `lastHeadAt` null / missing / unparseable → unready. The clock is a
 * dedicated GraphQL `commits(last:1).committedDate`, never `updatedAt`.
 */
export declare function reviewSettle(input: {
    lastHeadAt: string | null | undefined;
    nowMs: number;
    reviews: SettleReview[];
    me: string;
    settleMs?: number;
}): ReviewSettle;
/**
 * Decide whether the loop may merge this PR under the active policy. A red or
 * pending build, a merge conflict, or requested changes always block. Approval
 * is required for `auto-on-green`; `auto-timeout` also accepts a green PR that
 * has aged past the stale threshold with no objection. `manual` never merges.
 */
export declare function mergeDecision(pr: GhPR, me: string, opts: {
    policy: MergePolicy;
    requireCi: boolean;
    staleHours: number;
    nowMs?: number;
    unresolvedThreads?: number;
    intentBlocked?: boolean;
    /** Which gate input blocks (issue #444): appended to INTENT_BLOCKER as a
     *  parenthetical so consumers keying on the existing string still match.
     *  Absent → the bare INTENT_BLOCKER, byte-identical to before. */
    intentBlockedBy?: IntentBlockedBy;
    /** Commits the head is BEHIND base (issue #530): >0 blocks — CI proved the
     *  branch against a base that no longer exists; rebase (pr sync) so CI
     *  re-runs on the rebased head. null = comparison failed → also blocks
     *  (never merge on unknown freshness). Absent → no freshness gate,
     *  byte-identical to before. */
    behindBy?: number | null;
    /** Only read when `behindBy` is null: the comparison can NEVER succeed by
     *  retrying — the ref pair does not resolve (deleted head branch or fork, a
     *  cross-repo head with no owner to qualify it, or a token that cannot see
     *  the head repo). It does NOT unblock anything (PR #531 review): the merge
     *  stays blocked exactly as before, this only routes the block to ONE
     *  escalation instead of an endless per-tick re-poll. */
    freshnessUnresolvable?: boolean;
    /** Last head commit time (issue #687). Absent → no settle gate,
     *  byte-identical to before. `null` = clock unreadable → fail closed. */
    lastHeadAt?: string | null;
    /** Extra reviews/threads folded into settle (thread author !== me). */
    settleReviews?: SettleReview[];
    /** Override `REVIEW_SETTLE_MS` — tests only. */
    settleMs?: number;
    /** Current head SHA (issue #637). Overrides `pr.headRefOid`. Missing /
     *  unreadable fails closed on the `shipflow-approved` label path. */
    headSha?: string | null;
}): MergeDecision;
/** Author associations whose branch the loop may check out and execute. */
export declare const TRUSTED_AUTHOR_ASSOCIATIONS: Set<string>;
/** Why a head may not be run autonomously — `null` means it may.
 *  `association-unknown` is as untrusted as `untrusted-author`; it exists only so
 *  a human can tell "GitHub says this author is a CONTRIBUTOR" apart from "the
 *  lookup failed and we could not tell" (PR #394 review). */
export type HeadDistrust = "fork-head" | "untrusted-author" | "association-unknown";
/**
 * Whether the loop may check out + run this PR's head. FAIL CLOSED: a missing
 * `isCrossRepository` or `authorAssociation` (older gh, failed GraphQL
 * enrichment) is untrusted, never trusted. Enforced BEFORE checkout — a
 * post-hoc "the push was refused" caveat fires only after the code has run.
 */
export declare function headTrust(pr: GhPR): HeadDistrust | null;
/** One foreign conflicted PR plus the verdict on whether the loop may act on it. */
export interface ForeignConflictedPR {
    pr: GhPR;
    /** Safe to check out + run: same-repo head from a trusted association. */
    trusted: boolean;
    /** Set when `trusted` is false — surfaced in the inbox so a human can act. */
    distrust?: HeadDistrust;
}
/**
 * Foreign conflicted PRs (issue #393): every OTHER author's open, non-draft PR
 * whose head conflicts with base. The inbox appends these so the conflict sweep
 * covers ALL open PRs, not only the loop's own. Drafts are the author's
 * workbench and are never rebased under them; the mine list wins on overlap
 * (deduped by number).
 *
 * Two gates, both fail-closed (PR #394 review):
 *  1. `opts.enabled` — the whole sweep is OPT-IN (`config set conflict-sweep
 *     true`). Off (the default, and what every existing install keeps on
 *     upgrade) returns `[]`.
 *  2. `headTrust` — fork heads and untrusted associations are returned with
 *     `trusted: false` so the inbox can REPORT them for a human, and are never
 *     admitted to the autonomous queue.
 */
export declare function foreignConflictedPRs(mine: GhPR[], all: GhPR[], me: string, opts?: {
    enabled?: boolean;
}): ForeignConflictedPR[];
//# sourceMappingURL=pr-state.d.ts.map