v1.94.9.0 feat(pregate): owner-granted flaky exception for named cases in a red run (GST-1096) (#3911)

* feat(pregate): owner-granted flaky exception for named cases in a red run (GST-1096)

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>

* fix(pregate): bind flaky exceptions to the consuming PR head, quote the grant command, recheck red runs (review fixes)

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>

* docs(changelog): plain wording in the flaky exception fragment

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>

---------

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>

CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## [1.94.9.0] - 2026-11-03
+
+**A pull request can clear its remote gate obligation from a run with named flaky failures, once the owner grants it (GST-1096).** A timing flake in a test file the pull request never touched used to keep the pregate red with no way through but another paid run. `gstack-pregate clear --remote <lane> --run <id|url> --flaky-exception "<file>::<case>" --pr <n> --grant <approval id>` now accepts such a run when every failure is named from the run's own shard results and logs, at most three cases, each file outside the pull request's diff and its import closure, none paid and none a security scan test, and a gstack-approvals row in the owner's words binds the repository, PR, head, tree, lane, run attempt and cases. It covers the pregate only, and a red required CI check still needs its own green run.
+
+### Added
+- **`--flaky-exception`, `--pr` and `--grant` on `gstack-pregate clear`** (`lib/pregate/flaky-exception.ts`). Every job of the run attempt is reconciled (only test-shard jobs and their aggregate may fail), every planned shard needs a complete result, and each failed shard's log must name no failure its result leaves out. Without `--grant` the clear checks everything and prints the exact `gstack-approvals add` command, whose scope is a digest of everything the grant binds, so a grant can never be moved to another head or case list.
+- **`pass-with-exception`.** pregate.json records `exceptions`; `gstack-pregate verify` re-checks the binding offline and prints `PREGATE: pass-with-exception (<cases>; grant <id>)`; `gstack-ship-queue ready` accepts it and prints a `FLAKY_EXCEPTION:` line; the ship receipt records `flaky_exception`.
+- **docs/pregate.md#flaky-exception**, including why `base_red` is not used: it proves a failure by reproducing it on the base, and a timing flake passes there.
+
+### Tests
+- `test/pregate-flaky-exception.test.ts`: a red run with one named flake clears once the bound grant exists, and verify, ready and the receipt report it; refusals for an unnamed or extra failure, a case that did not fail, more than three cases, an unattributed failure, a failed non-shard job, a missing result or log, a timed-out shard, a log failure the result omits, a file in the diff or its import closure, a paid or security test, another head, another PR head, a newer run, a run from another repository or fork, a stale or unfinished run, a moved attempt (also after the inventory runs), and a grant with another scope, outcome or speaker; ready still refuses red CI, and refuses an exception granted for another PR or head. The printed grant command quotes case names for the shell. These tests failed before the change.
+
 ## [1.94.8.0] - 2026-11-03
 
 **`gstack-approvals render` no longer puts the owner's exact words, autoplan run ids or plan hashes into PR bodies on public repositories (GST-1160).** On a public repo, /ship pasted the full `## Approvals` table into the PR description. That table carries the owner's verbatim quote, the run id and the plan sha256, and GitHub keeps every earlier version of a description in its edit history, which no API can delete.

VERSION

@@ -1 +1 @@
-1.94.8.0
+1.94.9.0

agents-digest/gstack-AGENTS.md

@@ -1,4 +1,4 @@
-# gstack digest v1.94.8.0 — regenerate/re-copy after upgrading gstack
+# gstack digest v1.94.9.0 — regenerate/re-copy after upgrading gstack
 
 Behavioral rules from gstack (https://github.com/garrytan/gstack), compressed
 for agent hosts without a full skill install. The full skills add workflows,

bin/gstack-pregate

@@ -7,6 +7,7 @@
  *                  [--timeout <s>] [--stall-timeout <s>] [--remote --spend-cap <usd>] [--run <id>] [--from-run <id|url>] [--no-ci-carry] [--explain] [--json]
  *   gstack-pregate verify [--out <pregate.json>] [--json]      publication check: current tree, no fail/incomplete, obligations cleared
  *   gstack-pregate clear --remote <workflow.yml/job> --run-url <url> | --run <id|url> [--run …] [--allow-repo-commands] | --bundle-lane <label> | --receipt <file> [--out <pregate.json>]
+ *                  [--flaky-exception "<test file>::<case>" … --pr <n> [--grant <approval id>]]   a run with failures, under the owner's grant
  *   gstack-pregate lanes [--explain]                             the lane list and platform tiers read from .github/workflows
  *   gstack-pregate validate | init [--explain] [--force]         the working-tree .gstack/pregate.json
  *   gstack-pregate sealed [--range <a..b>] [--remote <name>] [--base <branch>] [--no-skip] [--json]
@@ -36,6 +37,7 @@ import { CHECKS, CHECK_IDS, PREGATE_OUT_REL, PREGATE_TIER2, clearDecision, clear
 import { describeLane, discoverLanes } from '../lib/pregate/workflows';
 import { REMOTE_GATE_LANE } from '../lib/pregate/checks/lanes';
 import { describeSubstitution } from '../lib/pregate/remote-receipt';
+import { approvalGrants, describeExceptions, type FlakyInput } from '../lib/pregate/flaky-exception';
 import { ensureTmpExcluded } from '../lib/restamp';
 import { RESULT_CODES, resultCodeSuffix, resultLine } from '../lib/result-codes';
 import { DEFAULT_STALL_TIMEOUT_S } from '../lib/pregate/context';
@@ -58,7 +60,10 @@ const HELP = `gstack-pregate — cheap checks before anything paid or remote (do
                   verifies GitHub Actions runs against the base branch's run_profiles instead (docs/pregate.md#run-evidence):
                   one run of the profile named after the lane, or for pregate.json/remote_gate one run per
                   remote_gate_runs profile covering the gate's inventory (needs --allow-repo-commands); where a lane has a
-                  profile, --run-url is verified the same way
+                  profile, --run-url is verified the same way. --flaky-exception "<test file>::<case>" (at most 3) --pr <n>
+                  --grant <approval id> takes such runs with failures when every failure is named from the run's shard
+                  results and logs, outside the PR's diff and import closure, and an owner's gstack-approvals row binds
+                  them; without --grant it prints the row to record (pregate only; docs/pregate.md#flaky-exception)
   lanes           print every CI lane with its platform tier (from .github/workflows/*.yml)
   validate | init the working-tree ${PREGATE_CONFIG_PATH}
   sealed [--range <a..b>] [--remote <name>] [--base <branch>] [--no-skip]
@@ -117,7 +122,7 @@ function flag(args: string[], name: string): string | undefined { const i = args
 const VERB_FLAGS: Record<string, [string[], string[]]> = {
   run: [['--stage', '--only', '--base', '--policy-from', '--out', '--timeout', '--stall-timeout', '--spend-cap', '--run', '--from-run'], ['--allow-repo-commands', '--explain', '--json', '--remote', '--no-ci-carry']],
   verify: [['--out'], ['--json']],
-  clear: [['--remote', '--run-url', '--run', '--bundle-lane', '--receipt', '--out'], ['--allow-repo-commands']],
+  clear: [['--remote', '--run-url', '--run', '--bundle-lane', '--receipt', '--out', '--flaky-exception', '--pr', '--grant'], ['--allow-repo-commands']],
   lanes: [[], ['--explain', '--json']],
   validate: [[], ['--json']],
   init: [[], ['--explain', '--force']],
@@ -223,7 +228,12 @@ function cmdVerify(root: string, rest: string[], json: boolean): number {
   if (!read.file) { for (const e of read.errors) process.stderr.write(resultLine('gstack-pregate verify', e.code, `${e.message} at ${e.path}`) + '\n'); return EXIT.fail; }
   const v = verifyPregate(root, read.file);
   if (json) { process.stdout.write(JSON.stringify({ ...v, verdict: read.file.verdict, tree: read.file.tree, head: read.file.head, out }) + '\n'); return v.ok ? EXIT.ok : EXIT.fail; }
-  if (v.ok) { process.stdout.write(`PREGATE_VERIFY: ok ${v.message}\n`); return EXIT.ok; }
+  if (v.ok) {
+    const excepted = describeExceptions(read.file);
+    if (excepted) process.stdout.write(`PREGATE: ${excepted}\n`);
+    process.stdout.write(`PREGATE_VERIFY: ok ${v.message}\n`);
+    return EXIT.ok;
+  }
   process.stderr.write(resultLine('gstack-pregate verify', v.code!, v.message) + '\n');
   for (const r of v.uncleared) process.stdout.write(`requires-remote: ${r.lane} (${r.platform}) ${r.tests.length} test(s) uncleared\n`);
   process.stdout.write(`PREGATE_VERIFY: refused ${v.code}\n`);
@@ -233,6 +243,14 @@ function cmdVerify(root: string, rest: string[], json: boolean): number {
 function cmdClear(root: string, rest: string[]): number {
   const lane = flag(rest, '--remote');
   if (!lane) { process.stderr.write(`gstack-pregate clear: --remote <workflow.yml/job> with --run-url <url>, --bundle-lane <label> or (for ${REMOTE_GATE_LANE}) --receipt <file> is required\n`); return EXIT.usage; }
+  const cases = rest.flatMap((a, i) => a === '--flaky-exception' ? [rest[i + 1]!] : []);
+  let flaky: FlakyInput | undefined;
+  if (cases.length) {
+    if (!rest.includes('--run') && !rest.includes('--run-url')) { process.stderr.write('gstack-pregate clear: --flaky-exception needs --run <id|url>: an exception reads GitHub Actions runs\n'); return EXIT.usage; }
+    const pr = Number(flag(rest, '--pr'));
+    if (!Number.isInteger(pr) || pr <= 0) { process.stderr.write('gstack-pregate clear: --flaky-exception needs --pr <n>, the pull request the grant binds\n'); return EXIT.usage; }
+    flaky = { cases, pr, grant: flag(rest, '--grant'), grantRow: approvalGrants(root) };
+  } else if (flag(rest, '--pr') !== undefined || flag(rest, '--grant') !== undefined) { process.stderr.write('gstack-pregate clear: --pr and --grant apply only with --flaky-exception\n'); return EXIT.usage; }
   const out = outPath(root, rest);
   const read = fs.existsSync(out) ? readPregateFile(out) : { file: null, errors: [] };
   if (!read.file) { process.stderr.write(resultLine('gstack-pregate clear', 'PREGATE_STALE', `${out} is missing or invalid; run gstack-pregate first`) + '\n'); return EXIT.fail; }
@@ -242,7 +260,7 @@ function cmdClear(root: string, rest: string[]): number {
   const checked = runs.length || runUrl || bundleLane ? buildRunCheck(root, lane, rest.includes('--allow-repo-commands')) : undefined;
   if (checked && 'error' in checked && (runs.length || checked.profiled)) { process.stderr.write(`gstack-pregate clear: ${checked.error}${checked.profiled ? `; ${lane} may have a run profile on the base branch, so it clears only with a verified --run` : ''}\n`); return EXIT.fail; }
   const evidence = checked && !('error' in checked) ? checked : undefined;
-  const decision = clearDecision(read.file, lane, { runUrl, runs, bundleLane, receiptPath: flag(rest, '--receipt'), evidence }, root);
+  const decision = clearDecision(read.file, lane, { runUrl, runs, bundleLane, receiptPath: flag(rest, '--receipt'), evidence, flaky }, root);
   if ('refused' in decision) {
     if (decision.refused === 'usage') { process.stderr.write(`gstack-pregate clear: ${decision.message}\n`); return EXIT.usage; }
     process.stderr.write(`gstack-pregate clear: receipt refused — ${decision.message}; fix: ${decision.fix ?? RESULT_CODES.PREGATE_RECEIPT_INVALID.fix} ${resultCodeSuffix('PREGATE_RECEIPT_INVALID')}\n`);
@@ -250,9 +268,11 @@ function cmdClear(root: string, rest: string[]): number {
   }
   const current = readPregateFile(out).file;
   if (!current || current.tree !== read.file.tree || current.generated_at !== read.file.generated_at) { process.stderr.write(resultLine('gstack-pregate clear', 'PREGATE_STALE', `${out} changed while ${lane} was being verified; rerun the clear against the new file`) + '\n'); return EXIT.fail; }
-  const file = clearObligation(current, lane, decision.receipt, `gstack-pregate clear ${new Date().toISOString()}`, decision.substitution);
+  const file = clearObligation(current, lane, decision.receipt, `gstack-pregate clear ${new Date().toISOString()}`, decision.substitution, decision.exception);
   writePregateFile(root, out, file);
-  if (/ runs=\S+ profiles=/.test(decision.receipt)) process.stdout.write(`REUSE: accepted ${lane} ${decision.receipt}\n`);
+  const e = decision.exception;
+  if (e) process.stdout.write(`FLAKY_EXCEPTION: accepted ${lane} cases=${e.cases.join(' | ')} run=${e.runs.join(',')} grant=${e.grant} by=${e.by} (pregate only; every required CI check still needs its own green run at this head)\n`);
+  else if (/ runs=\S+ profiles=/.test(decision.receipt)) process.stdout.write(`REUSE: accepted ${lane} ${decision.receipt}\n`);
   if (decision.substitution) process.stdout.write(`PREGATE_RECEIPT_SUBSTITUTED: ${describeSubstitution(decision.substitution)}\n`);
   process.stdout.write(`PREGATE_CLEARED: ${lane} receipt=${decision.receipt} verdict=${file.verdict}${decision.attested ? ` (attested, not validated: ${lane} has no machine-checkable receipt)` : ''}\n`);
   if (checked && 'error' in checked) process.stderr.write(`gstack-pregate clear: run profiles unavailable (${checked.error}); ${lane} was recorded without run verification\n`);

bin/gstack-ship-receipt

@@ -40,6 +40,7 @@ import { versionAtRef } from '../lib/restamp';
 import { branchSides, stampOnlyLine, type BranchSide } from '../lib/stamp-only';
 import { runScriptSync } from '../lib/script-invocation';
 import { readPregateFile, verifyPregate } from '../lib/pregate/index';
+import { exceptionConsumerProblem } from '../lib/pregate/flaky-exception';
 import { isUnavailable, loadPolicyFromBase, matchesAny, policyUnavailableLine, resolveBaseBranch, runningGstackVersion, stampFilesInTree, validatePolicy, type ShipPolicy } from '../lib/ship-policy';
 import { approvalForReceipt } from '../lib/approval-citations';
 import {
@@ -472,15 +473,18 @@ function gitVersionBelow(repoRoot: string, minimum: string): string | null {
   return major > minMajor || (major === minMajor && minor >= minMinor) ? null : m[0];
 }
 
-type PregateField = { pregate: string; requires_remote?: string[] };
+type PregateField = { pregate: string; requires_remote?: string[]; flaky_exception?: ShipReceipt['flaky_exception'] };
 /** A pregate result file → the receipt's pregate field, verified current for this checkout's tree (shared by write and carry). */
 function pregateFieldFor(repoRoot: string, file: string, head: string): { ok: true; field: PregateField } | { ok: false; errors: Array<{ code: string; message: string }> } {
   const read = readPregateFile(file);
   if (!read.file) return { ok: false, errors: read.errors.map(e => ({ code: e.code, message: `${e.message} at ${e.path}` })) };
   const v = verifyPregate(repoRoot, read.file);
   if (!v.ok) return { ok: false, errors: [{ code: v.code!, message: v.message ?? 'pregate is not current' }] };
+  const foreign = exceptionConsumerProblem(read.file, head);
+  if (foreign) return { ok: false, errors: [{ code: 'PREGATE_REMOTE_UNCLEARED', message: foreign }] };
   const remote = read.file.requires_remote ?? [];
-  return { ok: true, field: { pregate: `${read.file.verdict ?? 'pass'} @${read.file.tree.slice(0, 12)} (${read.file.checks.length} checks, current for ${head.slice(0, 12)})`, requires_remote: remote.length ? remote.map(r => `${r.lane}: ${r.receipt}`) : undefined } };
+  const exceptions = read.file.exceptions ?? [];
+  return { ok: true, field: { pregate: `${read.file.verdict ?? 'pass'} @${read.file.tree.slice(0, 12)} (${read.file.checks.length} checks, current for ${head.slice(0, 12)})`, requires_remote: remote.length ? remote.map(r => `${r.lane}: ${r.receipt}`) : undefined, flaky_exception: exceptions.length ? exceptions.map(e => ({ lane: e.lane, runs: e.runs, cases: e.cases, grant: e.grant, by: e.by })) : undefined } };
 }
 
 /**

docs/pregate.md

@@ -1059,6 +1059,91 @@ and without it every push falls back to the full run. Windows Free Tests now
 runs nightly and by hand only (docs/support-tiers.md), never on a push, so its
 `reuse` job is always skipped and every nightly run takes the strict path.
 
+<a id="flaky-exception"></a>
+## Owner-granted flaky exception
+
+A timing flake in a test file the pull request never touched can keep a remote
+gate obligation red: the rerun hits the same 5 s timeout on a loaded runner,
+and nothing in the diff can fix it. `clear --flaky-exception` lets the owner
+accept named cases for one head, on the run's own records:
+
+```bash
+gstack-pregate clear --remote pregate.json/remote_gate --run <id|url> \
+  --flaky-exception "test/docsync-fault-interface-legacy.test.ts::rejects legacy-third" \
+  --pr <n> --allow-repo-commands
+```
+
+The first call checks everything below and then refuses with
+`reason=grant_needed`, printing the exact `gstack-approvals add` command to run
+once the owner says yes: its `--scope` is `flaky-exception:<sha256>`, a digest of
+the repository, PR, head, tree, lane, every run with its attempt, and the sorted
+cases. Record the owner's exact words in that row, then rerun the same clear with
+`--grant <the row id>`. The obligation clears only when all of this holds:
+
+- **Every failure is named from the run's own records.** A red run uploads no
+  `tree.json`, so the clear reads the strict shard runner's artifacts instead
+  (`free-plan`, `free-result-<n>` and `free-test-shard-logs-<n>` in
+  `free-tests.yml`; the `windows-` names in `windows-free-tests.yml`; any other
+  workflow refuses with `no_shard_results`). Every job of the attempt is
+  reconciled: only the shard jobs (`free-suite (<n>)`) and the aggregate that
+  needs them may fail, every job the profile requires must pass, and any other
+  failed or cancelled job refuses (`unnamed_failure`). Every planned shard needs
+  its result; a missing result, a timed-out shard or a missing summary is
+  `shard_incomplete`. A failure the runner could not attribute to a test file,
+  an unhandled error between tests, or a `(fail)` line in a failed shard's log
+  that its result does not record refuses. A retry that passed is a recovered
+  flake; a retry that failed again keeps its own failures.
+- **The cases are exactly the failures.** At most three, written as
+  `<test file>::<test name>` the way the run printed them. A failure no
+  `--flaky-exception` names refuses (`unnamed_failure`), and so does a named
+  case that did not fail (`case_not_failed`). The refusal lists the run's
+  failures in that form.
+- **The files are not the PR's business.** A named file in the PR's diff
+  (`case_in_diff`), or one the import graph reaches from any changed path
+  (`case_in_closure`, lib/pregate/import-graph.ts with the base branch's
+  `dependencies`), refuses. The closure follows imports only: a test that reads a
+  changed doc, template or workflow through the file system is not reached, so
+  required CI stays the check on it. A paid test file (`case_paid`) and a
+  security test (`case_security`: a file name with cso, secrets, gitleaks, sealed,
+  redact or redaction, osv, security, sanitize or inject) are never excepted. Security scans themselves are pregate checks and CI jobs,
+  not test cases, so no exception can reach them.
+- **One head, one grant.** The runs must have tested pregate.json's own head and
+  tree, with no stamp-only substitution (`head_mismatch`); the PR must be open with
+  that head (`pr_mismatch`); no newer run of the workflow may exist on the head
+  (`newer_run`), and the run may not move to another attempt during the check
+  (`run_changed`). The grant row must carry this exception's scope
+  (`grant_mismatch` otherwise), record `approved` (`grant_not_approved`) and be
+  the owner's words, not an agent's (`grant_not_owner`). That last check reads
+  the row's `by` field, which `gstack-approvals add --by` takes as written, so it
+  only catches a row honestly labeled `agent:`. The record is as trustworthy as
+  whoever writes it, the same as every gstack approval. A new head needs a new
+  run and a new grant; a grant is never rebound: `ready` and the ship receipt
+  refuse an exception granted for another PR or head, even when the tree matches.
+
+pregate.json records the grant under `exceptions` (lane, repository, PR, head,
+tree, runs, cases, grant id, who said it, their words and the binding), and the
+obligation's receipt adds `exception=<grant> cases=<n>` to the usual run fields.
+The verdict becomes `pass-with-exception`. `verify` re-checks offline that each
+exception receipt has its entry, bound to this head and tree, with a binding that
+still matches its fields, and prints
+`PREGATE: pass-with-exception (<cases>; grant <id>)`. `gstack-ship-queue ready`
+accepts it and prints one `FLAKY_EXCEPTION:` line per exception in the READY
+block, and `gstack-ship-receipt write` records `flaky_exception` (lane, runs,
+cases, grant, who).
+
+**Pregate only.** The exception clears the pregate obligation and nothing else.
+It never waives a red required CI check: `ready` still needs every required check
+green at the exact head, so a red Free Tests check on the pull request needs its
+own rerun to pass. Changing that contract is a separate decision for the owner.
+
+**Why not `base_red`.** `base_red` (docs/ship-policy.md#base-red) proves a
+failure belongs to the base by reproducing it there, at the base head and at the
+PR head. A timing flake usually passes on the base (the 2026-11-02 docsync case
+passed in 3.5 s on main and failed at 5 s on the PR's tree), so `base_red`
+returns `IN_BRANCH` and refuses. The exception path asks a different question:
+not "is the base broken?" but "is every failure named, outside this PR, and
+accepted by the owner?"
+
 <a id="guards"></a>
 ## Guards and the lane-done rule
 

lib/headless-artifacts.ts

@@ -83,6 +83,8 @@ export interface PregateCheck {
 /** A remote_gate receipt accepted from a stamp-only predecessor tree (lib/pregate/remote-receipt.ts): the gated tree, the tree it was accepted for, the policy, and every differing path with its stamp rule. */
 export interface PregateReceiptSubstitution { gated_tree: string; accepted_for: string; policy: string; files: Array<{ path: string; rule: string }> }
 export interface PregateRemote { lane: string; platform: string; workflow: string; job: string; tests: string[]; receipt: string | null; cleared_by?: string; command?: string; substitution?: PregateReceiptSubstitution }
+/** An owner-granted flaky exception (lib/pregate/flaky-exception.ts): the runs, cases and grant that cleared one obligation, bound to one head and tree. */
+export interface PregateException { lane: string; repo: string; pr: number; head: string; tree: string; runs: string[]; cases: string[]; grant: string; by: string; words: string; binding: string }
 export interface PregateFile {
   schema_version: 1; tree: string; checks: PregateCheck[]; run?: string; stage1_ms?: number; stage2_ms?: number;
   // C-pregate (C8): head/base identity, the policy sources, persisted requires-remote obligations and the one-line verdict.
@@ -93,6 +95,8 @@ export interface PregateFile {
   policy_user_path?: string;
   /** This run's scratch directory under the state root (logs, scan files). */
   scratch?: string;
+  /** Obligations cleared from runs with failures under an owner's grant (`clear --flaky-exception`). */
+  exceptions?: PregateException[];
 }
 export interface ShipReceipt {
   schema_version: 1; head: string; base: string; pr?: number; version?: string; gated_tree?: string;
@@ -123,6 +127,8 @@ export interface ShipReceipt {
   review_targeted?: { classes: string[]; rules: string; brief_sha: string; product_patch_id: string; status: 'done' | 'failed' | 'not-run'; findings: number; raised_by: string };
   /** Step 5 failures gstack-base-red proved are the base's own (lib/base-red.ts): a conditional receipt the queue refuses until /ship --resume rewrites it without this block. */
   base_red?: { cases: string[]; files: string[]; base: string; lane: string; expires_at: string };
+  /** The pregate's owner-granted flaky exceptions (gstack-pregate clear --flaky-exception): pregate only, never a required CI check. */
+  flaky_exception?: Array<{ lane: string; runs: string[]; cases: string[]; grant: string; by: string }>;
   /** The base policy's review_exclude_paths at the reviewed head (lib/review-exclude.ts); absent when the base declares none. Carry and the queue compare `digest`. */
   review_exclude?: { source: string; patterns: string[]; applied: string[]; excluded: number; excluded_bytes: number; kept: number; gate_tagged: string[]; patterns_sha256: string; list_sha256: string; digest: string };
 }
@@ -234,6 +240,7 @@ export const ARTIFACT_SCHEMAS = {
       head: str, base: str, generated_at: str, policy: str, policy_digest: str, policy_user_path: str, registry: str, verdict: str, scratch: str,
       requires_remote: { type: 'array', items: { type: 'object', required: ['lane', 'platform', 'tests', 'receipt'], properties: { lane: str, platform: str, workflow: str, job: str, tests: strList, receipt: nullableStr, cleared_by: str, command: str,
         substitution: { type: 'object', required: ['gated_tree', 'accepted_for', 'policy', 'files'], properties: { gated_tree: str, accepted_for: str, policy: str, files: { type: 'array', items: { type: 'object', required: ['path', 'rule'], properties: { path: str, rule: str } } } } } } } },
+      exceptions: { type: 'array', items: { type: 'object', required: ['lane', 'repo', 'pr', 'head', 'tree', 'runs', 'cases', 'grant', 'by', 'words', 'binding'], properties: { lane: str, repo: str, pr: { type: 'integer' }, head: str, tree: str, runs: strList, cases: strList, grant: str, by: str, words: str, binding: str } } },
     },
   },
   'ship-receipt': {
@@ -250,6 +257,7 @@ export const ARTIFACT_SCHEMAS = {
       carry: { type: 'object', required: ['from', 'reason', 'product_patch_id'], properties: { from: str, reason: str, product_patch_id: str, changed_paths: strList, merge_commits: { type: 'integer', minimum: 0 }, range_diff: str, covers: strList, reruns: strList, trees: strList, ancestry: { enum: ['linear', 'rewritten'] } } },
       head_tree: str, product_patch_id: str, gstack_version: str,
       base_red: { type: 'object', required: ['cases', 'files', 'base', 'lane', 'expires_at'], properties: { cases: strList, files: strList, base: str, lane: str, expires_at: str } },
+      flaky_exception: { type: 'array', items: { type: 'object', required: ['lane', 'runs', 'cases', 'grant', 'by'], properties: { lane: str, runs: strList, cases: strList, grant: str, by: str } } },
       review_depth: { type: 'object', required: ['depth', 'class', 'runtime_lines', 'rules', 'base', 'gate_scan'], properties: { depth: { enum: ['light', 'standard', 'full'] }, class: { enum: ['docs', 'tests', 'code', 'gate'] }, runtime_lines: { type: 'integer', minimum: 0 }, rules: str, base: str, registry: nullableStr, gate_scan: { type: 'object', required: ['tagged', 'head'], properties: { tagged: { type: ['integer', 'null'], minimum: 0 }, head: str } }, reasons: strList, risk: { type: 'array', items: { enum: ['money', 'auth', 'secret', 'security', 'data'] } } } },
       review_targeted: { type: 'object', required: ['classes', 'rules', 'brief_sha', 'product_patch_id', 'status', 'findings', 'raised_by'], properties: { classes: { type: 'array', items: { enum: ['money', 'gate', 'auth', 'secret'] } }, rules: str, brief_sha: str, product_patch_id: str, status: { enum: ['done', 'failed', 'not-run'] }, findings: { type: 'integer', minimum: 0 }, raised_by: str } },
       review_exclude: { type: 'object', required: ['source', 'patterns', 'applied', 'excluded', 'excluded_bytes', 'kept', 'gate_tagged', 'patterns_sha256', 'list_sha256', 'digest'], properties: { source: str, patterns: strList, applied: strList, excluded: { type: 'integer', minimum: 0 }, excluded_bytes: { type: 'integer', minimum: 0 }, kept: { type: 'integer', minimum: 0 }, gate_tagged: strList, patterns_sha256: str, list_sha256: str, digest: str } },

lib/pregate/flaky-exception.ts

@@ -0,0 +1,403 @@
+/**
+ * pregate flaky exception (GST-1096, docs/pregate.md#flaky-exception): an owner-granted exception that lets GitHub
+ * Actions runs with failures clear one requires-remote obligation. `gstack-pregate clear --remote <lane> --run <run>
+ * --flaky-exception "<test file>::<case>" … --pr <n> --grant <approval id>` (lib/pregate/index.ts clearByRuns) takes
+ * the runs only when:
+ *
+ * - every failure is named from the run's own records: each job of the attempt reconciles (only test-shard jobs, and
+ *   the aggregate that needs them, may fail), the plan and every shard's strict result are present and complete (a
+ *   timed-out or unattributed shard is incomplete evidence), and each failed shard's log names no failure its result
+ *   omits;
+ * - the named cases are exactly the failures, at most three, none in a paid test file or a test of a security scan,
+ *   and each file is outside the PR's diff and the diff's import closure (lib/pregate/import-graph.ts);
+ * - the runs tested pregate.json's own head and tree (no stamp-only substitution), the PR's head is that head, and an
+ *   approved gstack-approvals row in the owner's words carries the scope `exceptionBinding` computes over repository,
+ *   PR, head, tree, lane, runs with their attempts and cases, so it cannot be rebound to another head or case list.
+ *
+ * It is pregate only: nothing here touches a required CI check, which still needs its own green run at the head.
+ * base_red is not used: it proves a failure by reproducing it on the base, and a timing flake passes there.
+ */
+import { createHash } from 'node:crypto';
+import { spawnSync } from 'node:child_process';
+import * as path from 'node:path';
+import { locate, readRecord } from '../approval-record';
+import type { PregateException, PregateFile } from '../headless-artifacts';
+import { parseRunRef, verifyRun, type ApiJob, type ApiRun, type RunArtifactDeps, type RunDeps, type RunEvidence, type RunProfile } from '../run-evidence';
+import { wtreeFingerprint } from '../script-invocation';
+import { resolveBaseBranch } from '../ship-policy';
+import type { FreeCiPlan, FreeCiResult, FreeShardOutcome } from '../../scripts/test-free-shards';
+import { isConfigUnavailable, loadConfigFromBase } from './config';
+import { buildGraph, testsFor } from './import-graph';
+
+export type FailureDeps = RunArtifactDeps;
+export interface GrantRow { id: string; outcome: string; scope: string; words: string; by: string }
+export interface FlakyInput { cases: string[]; pr?: number; grant?: string; grantRow?: (id: string) => GrantRow | null }
+export type FlakyRefusal = { refused: 'usage' | 'PREGATE_RECEIPT_INVALID'; message: string; fix?: string };
+/** What a flaky exception is granted for; `exceptionBinding` hashes exactly these fields. */
+export type ExceptionSubject = Pick<PregateException, 'lane' | 'repo' | 'pr' | 'head' | 'tree' | 'runs' | 'cases'>;
+export interface FlakyRuns { evidence: RunEvidence[]; red: Array<{ evidence: RunEvidence; failures: string[] }> }
+
+export const MAX_FLAKY_CASES = 3;
+export const FLAKY_SCOPE_PREFIX = 'flaky-exception:';
+/** The receipt field an exception clear adds; verify and verdictOf read it back. */
+export const EXCEPTION_RECEIPT = / exception=(\S+)/;
+
+/** The strict shard runner's artifacts and job names (scripts/test-free-shards.ts --ci-run) in the workflows that upload them. */
+interface ShardLayout { plan: string; result: string; logs: string; shardJob: string; aggregate: string }
+const SHARD_LAYOUTS: Record<string, ShardLayout> = {
+  'free-tests.yml': { plan: 'free-plan', result: 'free-result-', logs: 'free-test-shard-logs-', shardJob: 'free-suite', aggregate: 'free-tests' },
+  'windows-free-tests.yml': { plan: 'windows-plan', result: 'windows-result-', logs: 'windows-free-test-shard-logs-', shardJob: 'windows-free-shard', aggregate: 'windows-free-tests' },
+};
+/** A test of a security scanner (/cso, secrets, gitleaks, the sealed guard, redaction, OSV): never excepted. */
+const SECURITY_TEST = /(?:^|[-_.])(?:cso|secrets?|gitleaks|sealed|redact\w*|osv|security|sanitize\w*|injection|inject)(?=[-_.])/;
+const SHA = /^[0-9a-f]{40}$/;
+const LOG_FILE_HEADER = /^(\S.*\.test\.(?:[cm]?[jt]s|tsx|jsx)):$/;
+
+const sha256 = (text: string) => createHash('sha256').update(text).digest('hex');
+const short = (s: string | undefined) => (s ?? '').slice(0, 12);
+const shellQuote = (s: string) => `'${s.replace(/'/g, `'\\''`)}'`;
+
+/** The gstack-approvals scope that grants one exception: a digest of every field it binds, cases in sorted order. */
+export function exceptionBinding(e: ExceptionSubject): string {
+  const lines = [`lane=${e.lane}`, `repo=${e.repo}`, `pr=${e.pr}`, `head=${e.head}`, `tree=${e.tree}`, ...e.runs.map(r => `run=${r}`), ...[...e.cases].sort().map(c => `case=${c}`)];
+  return FLAKY_SCOPE_PREFIX + sha256(lines.join('\n'));
+}
+
+/** The approvals rows of this checkout's branch record (lib/approval-record.ts), looked up by id. */
+export function approvalGrants(repoRoot: string, env: NodeJS.ProcessEnv = process.env): (id: string) => GrantRow | null {
+  return id => {
+    const loc = locate({ cwd: repoRoot, env });
+    return 'code' in loc ? null : readRecord(loc).rows.find(r => r.id === id) ?? null;
+  };
+}
+
+/** The `--flaky-exception` values as `<file>::<case>` strings, or the usage refusal. */
+export function parseCases(cases: string[]): string[] | FlakyRefusal {
+  if (cases.length > MAX_FLAKY_CASES) return { refused: 'usage', message: `--flaky-exception names at most ${MAX_FLAKY_CASES} cases; got ${cases.length}` };
+  const bad = cases.find(c => { const i = c.indexOf('::'); return i <= 0 || i + 2 >= c.length; });
+  if (bad !== undefined) return { refused: 'usage', message: `--flaky-exception takes "<test file>::<case>", the file and the test name as the run printed them; got ${JSON.stringify(bad)}` };
+  if (new Set(cases).size !== cases.length) return { refused: 'usage', message: '--flaky-exception names each case once' };
+  return cases;
+}
+
+/** One-line summary for verify's PREGATE line: `pass-with-exception (<cases>; grant <id>)`. */
+export function describeExceptions(file: PregateFile): string | null {
+  const list = file.exceptions ?? [];
+  if (!list.length) return null;
+  return `pass-with-exception (${list.flatMap(e => e.cases).join(', ')}; grant ${list.map(e => e.grant).join(', ')})`;
+}
+
+/** READY's line for each exception: it waives the pregate obligation, never a required CI check. */
+export function flakyExceptionLines(file: PregateFile): string[] {
+  return (file.exceptions ?? []).map(e => `FLAKY_EXCEPTION: ${e.lane} cases=${e.cases.join(' | ')} run=${e.runs.join(',')} grant=${e.grant} by=${e.by} (pregate only; every required CI check still needs its own green run at this head)`);
+}
+
+/** verify's offline check: every exception receipt has its entry, bound to this head and tree, with an intact binding; null when all hold. */
+export function exceptionProblem(file: PregateFile): string | null {
+  const list = file.exceptions ?? [];
+  const remote = file.requires_remote ?? [];
+  for (const r of remote) {
+    const grant = EXCEPTION_RECEIPT.exec(r.receipt ?? '')?.[1];
+    if (!grant) continue;
+    const e = list.find(x => x.lane === r.lane && x.grant === grant);
+    if (!e) return `${r.lane}'s receipt names flaky exception grant ${grant}, but pregate.json has no exceptions entry for it; clear again`;
+    if (e.head !== file.head || e.tree !== file.tree) return `${r.lane}'s flaky exception (grant ${grant}) is bound to head ${short(e.head)} tree ${short(e.tree)}, not pregate.json's head ${short(file.head)} tree ${short(file.tree)}; a new head needs a new run and a new grant`;
+    if (exceptionBinding(e) !== e.binding) return `${r.lane}'s flaky exception (grant ${grant}): the binding does not match its recorded fields (granted scope ${e.binding}); clear again`;
+    const runs = / runs=(\S+)/.exec(r.receipt ?? '')?.[1];
+    if (runs !== e.runs.join(',')) return `${r.lane}'s receipt names runs ${runs ?? 'none'}, but its flaky exception (grant ${grant}) was granted for ${e.runs.join(',')}; clear again`;
+  }
+  const orphan = list.find(e => !remote.some(r => r.lane === e.lane && EXCEPTION_RECEIPT.exec(r.receipt ?? '')?.[1] === e.grant));
+  return orphan ? `pregate.json records a flaky exception for ${orphan.lane} (grant ${orphan.grant}) that no receipt uses; clear again` : null;
+}
+
+/** Why `file`'s exceptions cannot stand for this PR head: each binds the PR and head it was granted for, and a same-tree commit or another PR reusing the record never inherits it. */
+export function exceptionConsumerProblem(file: PregateFile, head: string, pr?: string): string | null {
+  const e = (file.exceptions ?? []).find(x => x.head !== head || (pr !== undefined && String(x.pr) !== pr));
+  return e ? `flaky exception grant ${e.grant} is bound to PR #${e.pr} at ${short(e.head)}, not ${pr ? `PR #${pr} at ` : ''}${short(head)}; a new head needs a new run and a new grant` : null;
+}
+
+/** Why red run `id` no longer stands as completed, failed attempt `attempt`; read again once the whole clear is assembled. */
+export function redRunChanged(deps: RunDeps, id: number, attempt: number): string | null {
+  const again = deps.run(id);
+  return again.run_attempt === attempt && again.status === 'completed' && again.conclusion === 'failure' ? null : `run ${id} moved to attempt ${again.run_attempt} (${again.status === 'completed' ? again.conclusion : again.status}) while it was being verified`;
+}
+
+/** verify's ok-line suffix naming each exception. */
+export function exceptionSummary(file: PregateFile): string {
+  return (file.exceptions ?? []).map(e => `flaky exception ${e.cases.join(', ')} (grant ${e.grant}, by ${e.by}, run ${e.runs.join(',')})`).join('; ');
+}
+
+const invalid = (lane: string, reason: string, detail: string, fix?: string): FlakyRefusal => ({ refused: 'PREGATE_RECEIPT_INVALID', message: `FLAKY_EXCEPTION: refused reason=${reason} — ${detail}; ${lane} stays uncleared`, ...(fix ? { fix } : {}) });
+const errText = (e: unknown) => String((e as Error)?.message ?? e).slice(0, 300);
+
+/**
+ * The runs for `names` (one per profile, matched by workflow): a green run verifies as `clear --run` verifies it, a red
+ * run through `readRunFailures`. At least one must be red, or no exception is needed.
+ */
+export function flakyRuns(lane: string, check: { repo: string; deps: RunDeps; profiles: Record<string, RunProfile>; now: Date; failures?: FailureDeps }, names: string[], refs: string[], vetoHead: string | undefined): FlakyRuns | FlakyRefusal {
+  if (!check.failures) return { refused: 'usage', message: 'the run artifacts cannot be read here (no GitHub origin), so failures cannot be named' };
+  const runs: Array<{ ref: string; id: number; run: ApiRun }> = [];
+  for (const ref of refs) {
+    const id = parseRunRef(ref, check.repo);
+    if (id === null) return invalid(lane, 'run_ref_invalid', `${JSON.stringify(ref)} is not a run id or a run URL on ${check.repo}`);
+    try { runs.push({ ref, id, run: check.deps.run(id) }); }
+    catch (e) { return invalid(lane, 'api_error', `reading run ${id} failed: ${errText(e)}`, `check gh auth status and that gh can read ${check.repo}'s Actions runs, then rerun the same clear`); }
+  }
+  if (runs.every(r => r.run.status === 'completed' && r.run.conclusion === 'success')) return invalid(lane, 'run_green', `${runs.map(r => `run ${r.id} attempt ${r.run.run_attempt}`).join(', ')} passed; clear with --run alone, no exception is needed`);
+  const out: FlakyRuns = { evidence: [], red: [] };
+  const used = new Set<number>();
+  for (const name of names) {
+    const profile = check.profiles[name]!;
+    const pick = runs.find(r => !used.has(r.id) && r.run.path === `.github/workflows/${profile.workflow}`) ?? runs.find(r => !used.has(r.id));
+    if (!pick) return { refused: 'usage', message: `${lane} needs one run per profile (${names.join(', ')})` };
+    used.add(pick.id);
+    if (pick.run.conclusion === 'success') {
+      const v = verifyRun(check.deps, { repo: check.repo, runRef: pick.ref, profileName: name, profile, vetoHeads: vetoHead ? [vetoHead] : [], now: check.now });
+      if (!v.ok) return invalid(lane, v.reason, `${name}: ${v.detail}`);
+      out.evidence.push(v.evidence);
+      continue;
+    }
+    const r = readRunFailures(check.deps, check.failures, { repo: check.repo, id: pick.id, run: pick.run, profileName: name, profile, now: check.now });
+    if (!r.ok) return invalid(lane, r.reason, r.detail);
+    out.evidence.push(r.evidence);
+    out.red.push({ evidence: r.evidence, failures: r.failures });
+  }
+  return out;
+}
+
+type Read<T> = { ok: true } & T | { ok: false; reason: string; detail: string };
+const fail = (reason: string, detail: string) => ({ ok: false as const, reason, detail });
+
+/** The one JSON file of artifact `name`, parsed; a message when it is missing, ambiguous or unreadable. */
+function jsonArtifact<T>(art: FailureDeps, id: number, name: string): T | { error: string } {
+  let files: Record<string, string>;
+  try { files = art.artifactFiles(id, name); } catch (e) { return { error: errText(e) }; }
+  const json = Object.entries(files).filter(([f]) => f.endsWith('.json'));
+  if (json.length !== 1) return { error: `${name} holds ${json.length} JSON files, not one` };
+  try { return JSON.parse(json[0]![1]) as T; } catch (e) { return { error: `${json[0]![0]} is not JSON: ${errText(e)}` }; }
+}
+
+const isError = (v: unknown): v is { error: string } => !!v && typeof v === 'object' && 'error' in v && typeof (v as { error: unknown }).error === 'string';
+const escapeRe = (s: string) => s.replace(/[.*+?^${{}()|[\]\\]/g, '\\$&');
+
+/**
+ * A red run under `profile` read from its own records (B8: a red run uploads no tree.json): every job of the attempt, the
+ * plan, every shard's strict result and each failed shard's logs. Returns the evidence (the plan's files, the tests the
+ * shards ran) and the failed cases as `<file>::<test name>`, or the refusal naming what could not be reconciled.
+ */
+function readRunFailures(deps: RunDeps, art: FailureDeps, o: { repo: string; id: number; run: ApiRun; profileName: string; profile: RunProfile; now: Date }): Read<{ evidence: RunEvidence; failures: string[] }> {
+  const { run, profile: p, id } = o;
+  const layout = SHARD_LAYOUTS[p.workflow];
+  if (!layout) return fail('no_shard_results', `${p.workflow} uploads no strict shard results gstack can read (only ${Object.keys(SHARD_LAYOUTS).join(' and ')} do), so its failures cannot be named`);
+  const at = `run ${id} attempt ${run.run_attempt}`;
+  try {
+    if ((run.repository?.full_name ?? '').toLowerCase() !== o.repo.toLowerCase()) return fail('other_repository', `${at} belongs to ${run.repository?.full_name ?? 'an unknown repository'}, not ${o.repo}`);
+    if ((run.head_repository?.full_name ?? '').toLowerCase() !== o.repo.toLowerCase()) return fail('fork_run', `${at} ran for ${run.head_repository?.full_name ?? 'an unknown repository'}, not ${o.repo}`);
+    if (run.path !== `.github/workflows/${p.workflow}`) return fail('workflow_mismatch', `${at} ran ${run.path ?? 'an unknown workflow'}, not .github/workflows/${p.workflow}`);
+    if (!p.events.includes(run.event)) return fail('event_mismatch', `${at} is a ${run.event} run; ${o.profileName} accepts ${p.events.join(', ')}`);
+    if (run.status !== 'completed') return fail('run_in_progress', `${at} is ${run.status}`);
+    if (run.conclusion !== 'failure') return fail('run_not_failure', `${at} concluded ${run.conclusion}; only a run that finished with test failures can carry an exception (a cancelled or timed-out run is incomplete evidence)`);
+    if (!SHA.test(run.head_sha)) return fail('api_error', `${at} has no head commit`);
+    const jobs = deps.jobs(id, run.run_attempt);
+    const finishedAt = jobs.map(j => j.completed_at).filter((t): t is string => !!t).sort().pop() ?? run.updated_at;
+    const finished = Date.parse(finishedAt ?? '');
+    const maxAge = p.max_age_hours ?? 24;
+    if (!Number.isFinite(finished)) return fail('api_error', `${at} has no completion time`);
+    if (o.now.getTime() - finished > maxAge * 3600_000) return fail('run_stale', `${at} finished ${finishedAt}, more than ${maxAge} h before now`);
+    const newer = deps.runsForHead(p.workflow, run.head_sha).find(r => r.id !== id && (r.run_started_at ?? r.created_at ?? '') >= (run.created_at ?? ''));
+    if (newer) return fail('newer_run', `run ${newer.id} of ${p.workflow} on ${short(run.head_sha)} started after ${at}; clear with the newest run`);
+    const shardJobs = reconcileJobs(jobs, layout, p, at);
+    if ('reason' in shardJobs) return fail(shardJobs.reason, shardJobs.detail);
+    const plan = jsonArtifact<FreeCiPlan>(art, id, layout.plan);
+    if (isError(plan)) return fail('shard_incomplete', `${at} has no readable ${layout.plan} (${plan.error})`);
+    if (plan.version !== 1 || typeof plan.id !== 'string' || typeof plan.revision !== 'string' || !Array.isArray(plan.shards) || !plan.shards.length
+      || plan.shards.some((s, i) => s.shard !== i + 1 || !Array.isArray(s.files) || s.files.some(f => typeof f !== 'string'))) return fail('result_mismatch', `${at}'s ${layout.plan} is not a strict shard plan`);
+    const headTree = deps.commitTree(run.head_sha);
+    if (!headTree) return fail('api_error', `git cannot read the tree of ${run.head_sha}`);
+    if (plan.revision !== run.head_sha && (!SHA.test(plan.revision) || deps.commitTree(plan.revision) !== headTree)) return fail('tree_mismatch', `${at} tested ${short(plan.revision)}, whose tree is not its head ${short(run.head_sha)}'s tree ${short(headTree)}`);
+    if (shardJobs.size !== plan.shards.length || plan.shards.some(s => !shardJobs.has(s.shard))) return fail('shard_mismatch', `${at} has ${layout.shardJob} job(s) for shard(s) ${[...shardJobs.keys()].sort((a, b) => a - b).join(', ') || 'none'}, but its plan has ${plan.shards.length} shard(s)`);
+    const failures: string[] = [];
+    let tests = 0;
+    for (const s of plan.shards) {
+      const res = jsonArtifact<FreeCiResult>(art, id, `${layout.result}${s.shard}`);
+      if (isError(res)) return fail('shard_incomplete', `shard ${s.shard} has no readable ${layout.result}${s.shard} (${res.error})`);
+      if (res.planId !== plan.id || res.revision !== plan.revision || res.outcome?.shard !== s.shard || JSON.stringify(res.outcome.files) !== JSON.stringify(s.files)) return fail('result_mismatch', `shard ${s.shard}'s result is not shard ${s.shard} of plan ${plan.id}`);
+      const named = shardFailures(res, s.shard);
+      if ('reason' in named) return fail(named.reason, named.detail);
+      const job = shardJobs.get(s.shard)!;
+      if ((job.conclusion === 'failure') !== (named.final.length > 0)) return fail('shard_mismatch', `shard ${s.shard}'s job concluded ${job.conclusion}, but its result names ${named.final.length} final failure(s)`);
+      if (job.conclusion === 'failure') {
+        const problem = logProblem(art, id, `${layout.logs}${s.shard}`, s.shard, s.files, named.all);
+        if (problem) return fail(problem.reason, problem.detail);
+      }
+      failures.push(...named.final);
+      tests += res.outcome.summary?.testsRan ?? 0;
+    }
+    const again = deps.run(id);
+    if (again.run_attempt !== run.run_attempt || again.status !== 'completed' || again.conclusion !== run.conclusion) return fail('run_changed', `run ${id} moved to attempt ${again.run_attempt} (${again.status === 'completed' ? again.conclusion : again.status}) while it was being verified`);
+    return { ok: true, evidence: { run_id: id, run_attempt: run.run_attempt, head_sha: run.head_sha, tree: headTree, profile: o.profileName, event: run.event, finished_at: finishedAt!, files: plan.shards.flatMap(s => s.files), tests }, failures: [...new Set(failures)] };
+  } catch (e) {
+    return fail('api_error', `reading run ${id} failed: ${errText(e)}`);
+  }
+}
+
+/** Shard number → job, once every job of the attempt is accounted for: only shard jobs and the aggregate may fail. */
+function reconcileJobs(jobs: ApiJob[], layout: ShardLayout, p: RunProfile, at: string): Map<number, ApiJob> | { reason: string; detail: string } {
+  const shardRe = new RegExp(`^${escapeRe(layout.shardJob)} \\((\\d+)\\)$`);
+  const shards = new Map<number, ApiJob>();
+  for (const j of jobs) {
+    if (j.conclusion === null) return { reason: 'shard_incomplete', detail: `${at}'s ${j.name} job has not finished` };
+    const m = shardRe.exec(j.name);
+    if (m) {
+      if (shards.has(Number(m[1]))) return { reason: 'shard_mismatch', detail: `${at} has two jobs named ${j.name}` };
+      if (j.conclusion !== 'success' && j.conclusion !== 'failure') return { reason: 'shard_incomplete', detail: `${at}'s ${j.name} job concluded ${j.conclusion}` };
+      shards.set(Number(m[1]), j);
+      continue;
+    }
+    if (j.name === layout.aggregate) continue;
+    const allowed = p.jobs.includes(j.name) ? ['success'] : ['success', 'skipped', 'neutral'];
+    if (!allowed.includes(j.conclusion)) return { reason: 'unnamed_failure', detail: `${at}'s ${j.name} job concluded ${j.conclusion}; only test-shard failures can be named` };
+  }
+  const missing = p.jobs.find(n => !jobs.some(j => j.name === n));
+  if (missing) return { reason: 'job_missing', detail: `${at} has no job named ${missing}` };
+  const aggregate = jobs.filter(j => j.name === layout.aggregate);
+  if (aggregate.length !== 1) return { reason: 'job_missing', detail: `${at} has ${aggregate.length} jobs named ${layout.aggregate}` };
+  if (![...shards.values()].some(j => j.conclusion === 'failure')) return { reason: 'unnamed_failure', detail: `${at} failed, but no ${layout.shardJob} job did, so the failure is not a test case` };
+  if (aggregate[0]!.conclusion !== 'failure') return { reason: 'shard_mismatch', detail: `${at}'s ${layout.aggregate} job concluded ${aggregate[0]!.conclusion} although a shard failed` };
+  return shards;
+}
+
+function completeSummary(o: FreeShardOutcome): boolean {
+  const s = o.summary;
+  return !!s && Number.isInteger(s.testsRan) && s.testsRan! >= 0 && s.filesRan === o.files.length && (o.files.length === 0 || s.sawTerminalSummary === true);
+}
+
+/**
+ * A shard's final failures (`<file>::<test>`) and every failure it recorded. A retry that passed recovered its files; a
+ * retry that failed replaces the first run's failures for the files it ran. Anything unattributed or incomplete refuses.
+ */
+function shardFailures(r: FreeCiResult, n: number): { final: string[]; all: Set<string> } | { reason: string; detail: string } {
+  const o = r.outcome;
+  const key = (f: { file: string | null; testName: string }) => `${f.file}::${f.testName}`;
+  if (o.status === 'timed-out') return { reason: 'shard_incomplete', detail: `shard ${n} timed out, so the tests after the hang never ran` };
+  if (!completeSummary(o)) return { reason: 'shard_incomplete', detail: `shard ${n}'s result has no complete run summary` };
+  if (o.status === 'passed') {
+    if (o.exitCode !== 0 || o.failingFiles.length || o.unattributedFailures || r.retry) return { reason: 'result_mismatch', detail: `shard ${n} passed with failures recorded` };
+    return { final: [], all: new Set() };
+  }
+  if (o.status !== 'failed') return { reason: 'result_mismatch', detail: `shard ${n} has status ${String(o.status)}` };
+  if (o.unattributedFailures) return { reason: 'unnamed_failure', detail: `shard ${n}: ${o.unattributedFailures} failure(s) the runner could not attribute to a test file` };
+  const first = o.failures ?? [];
+  const unnamed = first.filter(f => !f.file || !o.files.includes(f.file) || !f.testName);
+  if (!first.length || unnamed.length) return { reason: 'unnamed_failure', detail: `shard ${n} failed ${first.length ? `with ${unnamed.length} failure(s) not attributed to one of its files` : 'without naming a failure'}` };
+  if (JSON.stringify([...new Set(first.map(f => f.file))].sort()) !== JSON.stringify([...o.failingFiles].sort())) return { reason: 'result_mismatch', detail: `shard ${n}'s named failures and failing files disagree` };
+  const all = new Set(first.map(key));
+  const t = r.retry;
+  if (!t) return { final: [...all], all };
+  if (t.status === 'timed-out' || !completeSummary(t)) return { reason: 'shard_incomplete', detail: `shard ${n}'s retry did not complete` };
+  if (t.files.some(f => !o.failingFiles.includes(f))) return { reason: 'result_mismatch', detail: `shard ${n}'s retry ran files that had not failed` };
+  const again = t.failures ?? [];
+  if (t.unattributedFailures || (t.status === 'failed' && (!again.length || again.some(f => !f.file || !t.files.includes(f.file))))) return { reason: 'unnamed_failure', detail: `shard ${n}'s retry failed without naming each failure` };
+  if (t.status === 'passed' && (again.length || t.exitCode !== 0)) return { reason: 'result_mismatch', detail: `shard ${n}'s retry passed with failures recorded` };
+  for (const f of again) all.add(key(f));
+  const final = [...first.filter(f => !t.files.includes(f.file!)), ...again].map(key);
+  return { final: [...new Set(final)], all };
+}
+
+/** Why a failed shard's logs do not reconcile with its result: missing, an unhandled error between tests, or a failure the result omits. */
+function logProblem(art: FailureDeps, id: number, name: string, n: number, planned: string[], recorded: Set<string>): { reason: string; detail: string } | null {
+  let files: Record<string, string>;
+  try { files = art.artifactFiles(id, name); } catch (e) { return { reason: 'logs_missing', detail: `shard ${n} failed and has no readable ${name} (${errText(e)})` }; }
+  const logs = Object.entries(files).filter(([f]) => f.endsWith('.log'));
+  if (!logs.length) return { reason: 'logs_missing', detail: `shard ${n} failed and its ${name} holds no .log file` };
+  const canonical = (printed: string) => {
+    const stripped = printed.replace(/\\/g, '/').replace(/^(?:\.{1,2}\/)+/, '');
+    return planned.includes(stripped) ? stripped : planned.find(p => stripped.endsWith(`/${p}`) || p.endsWith(`/${stripped}`)) ?? stripped;
+  };
+  const { classifyBunTestOutputLine, parseBunFailureResult, stripAnsiLine } = require('../../scripts/lib/shard-engine') as typeof import('../../scripts/lib/shard-engine');
+  for (const [, text] of logs) {
+    let file: string | null = null;
+    let recap = false;
+    let unhandled = 0;
+    for (const raw of text.split('\n')) {
+      const line = stripAnsiLine(raw).replace(/^::group::/, '').replace(/\r$/, '');
+      if (/^\d+ tests? failed:$/.test(line)) { recap = true; file = null; continue; }
+      if (classifyBunTestOutputLine(line) === 'unhandled-between-tests') { unhandled++; continue; }
+      const header = LOG_FILE_HEADER.exec(line);
+      if (header) { if (!recap) file = canonical(header[1]!); continue; }
+      const failed = recap ? null : parseBunFailureResult(line);
+      if (failed !== null && !recorded.has(`${file}::${failed}`)) return { reason: 'unnamed_failure', detail: `shard ${n}'s log names ${file}::${failed}, which its result does not` };
+    }
+    if (unhandled) return { reason: 'unnamed_failure', detail: `shard ${n}'s log shows ${unhandled} unhandled error(s) between tests` };
+  }
+  return null;
+}
+
+/** The PR's changed paths against the merge base with origin/<base>, and each test the diff reaches through the import graph. */
+function prScope(repoRoot: string, file: PregateFile): { diff: Set<string>; closure: Map<string, string[]> } | { error: string } {
+  const git = (args: string[]) => { const r = spawnSync('git', args, { cwd: repoRoot, encoding: 'utf8', timeout: 60_000, maxBuffer: 64 * 1024 * 1024 }); return r.status === 0 ? r.stdout : null; };
+  const base = resolveBaseBranch(repoRoot);
+  const mb = git(['merge-base', `refs/remotes/origin/${base}`, '--end-of-options', file.head!])?.trim();
+  if (!mb) return { error: `git cannot find the merge base of origin/${base} and ${short(file.head)}` };
+  const listed = git(['diff', '--name-status', '-z', '--no-renames', '--end-of-options', mb, file.head!]);
+  if (listed === null) return { error: `git diff ${short(mb)} ${short(file.head)} failed` };
+  const parts = listed.split('\0').filter(Boolean);
+  const diff = new Set<string>();
+  const deleted: string[] = [];
+  for (let i = 0; i + 1 < parts.length; i += 2) { diff.add(parts[i + 1]!); if (parts[i] === 'D') deleted.push(parts[i + 1]!); }
+  const loaded = loadConfigFromBase(repoRoot, base);
+  if (isConfigUnavailable(loaded) || loaded.errors.length) return { error: `the base branch's .gstack/pregate.json cannot be read, so its dependency declarations are unknown` };
+  const at = () => { const fp = wtreeFingerprint({ cwd: repoRoot }); return 'tree' in fp ? fp.tree : null; };
+  if (at() !== file.tree) return { error: `the working tree is not pregate.json's tree ${short(file.tree)}; the import closure must be read from that tree` };
+  const declarations = loaded.config.dependencies;
+  const graph = buildGraph(repoRoot, { declarations, extraFiles: deleted });
+  const closure = new Map<string, string[]>();
+  for (const changed of diff) for (const t of testsFor(graph, changed, declarations).tests) closure.set(t, [...(closure.get(t) ?? []), changed]);
+  if (at() !== file.tree) return { error: 'the working tree changed while the import closure was read' };
+  return { diff, closure };
+}
+
+/**
+ * After the runs verified and covered the obligation: the named cases must be exactly the failures, in no paid or
+ * security test, outside the PR's diff and import closure, the PR's head must be pregate.json's, and the grant row must
+ * carry this exception's binding in the owner's words. Returns the exception to record.
+ */
+export function flakyDecision(file: PregateFile, lane: string, check: { repo: string; failures?: FailureDeps }, runs: FlakyRuns, input: FlakyInput & { cases: string[] }, repoRoot: string): { exception: PregateException } | FlakyRefusal {
+  const label = runs.red.map(r => `run ${r.evidence.run_id} attempt ${r.evidence.run_attempt}`).join(', ');
+  const failures = [...new Set(runs.red.flatMap(r => r.failures))];
+  const extra = failures.filter(f => !input.cases.includes(f));
+  if (extra.length) return invalid(lane, 'unnamed_failure', `${label} failed ${extra.slice(0, 5).join(', ')}${extra.length > 5 ? ` and ${extra.length - 5} more` : ''}, which no --flaky-exception names`);
+  const notFailed = input.cases.find(c => !failures.includes(c));
+  if (notFailed) return invalid(lane, 'case_not_failed', `${notFailed} did not fail in ${label}; its failures are ${failures.join(', ')}`);
+  const files = [...new Set(input.cases.map(c => c.slice(0, c.indexOf('::'))))];
+  const { isPaidTestFile } = require('../../test/helpers/paid-test-set') as typeof import('../../test/helpers/paid-test-set');
+  const paid = files.find(f => isPaidTestFile(f));
+  if (paid) return invalid(lane, 'case_paid', `${paid} is a paid test file; the paid gate covers it, never an exception`);
+  const security = files.find(f => SECURITY_TEST.test(path.posix.basename(f)));
+  if (security) return invalid(lane, 'case_security', `${security} tests a security scan, which an exception never covers`);
+  let pr: { head_sha: string; state: string; head_repo: string | null };
+  try { pr = check.failures!.pull(input.pr!); }
+  catch (e) { return invalid(lane, 'api_error', `reading PR #${input.pr} failed: ${errText(e)}`); }
+  if (pr.state !== 'open') return invalid(lane, 'pr_mismatch', `PR #${input.pr} is ${pr.state}`);
+  if ((pr.head_repo ?? '').toLowerCase() !== check.repo.toLowerCase()) return invalid(lane, 'pr_mismatch', `PR #${input.pr}'s head is on ${pr.head_repo ?? 'an unknown repository'}, not ${check.repo}`);
+  if (pr.head_sha !== file.head) return invalid(lane, 'pr_mismatch', `PR #${input.pr}'s head is ${short(pr.head_sha)}, not pregate.json's head ${short(file.head)}`);
+  const scope = prScope(repoRoot, file);
+  if ('error' in scope) return invalid(lane, 'closure_failed', scope.error);
+  const touched = files.find(f => scope.diff.has(f));
+  if (touched) return invalid(lane, 'case_in_diff', `${touched} is in the PR's diff`);
+  const reached = files.find(f => scope.closure.has(f));
+  if (reached) return invalid(lane, 'case_in_closure', `${reached} depends on a file the PR changes (${scope.closure.get(reached)!.slice(0, 5).join(', ')})`);
+  const subject: ExceptionSubject = { lane, repo: check.repo, pr: input.pr!, head: file.head!, tree: file.tree, runs: runs.evidence.map(e => `${e.run_id}/${e.run_attempt}`), cases: [...input.cases].sort() };
+  const binding = exceptionBinding(subject);
+  if (!input.grant) {
+    const ask = `Accept flaky ${subject.cases.join(', ')} in run ${subject.runs.join(',')} for PR #${subject.pr} at ${short(subject.head)}? Pregate only; required CI still needs a green run.`.slice(0, 300);
+    return invalid(lane, 'grant_needed', `every failure in ${label} is named (${subject.cases.join(', ')}) and outside the PR's diff and its import closure; the owner must grant the exception`,
+      `ask the owner, record their words with gstack-approvals add --ask ${shellQuote(ask)} --words "<the owner's exact words>" --by "<owner>" --scope "${binding}" --source pregate-flaky-exception, then rerun this clear with --grant <the row id it prints>`);
+  }
+  const row = input.grantRow?.(input.grant) ?? null;
+  if (!row) return invalid(lane, 'grant_missing', `no gstack-approvals row ${input.grant} in this branch's record`);
+  if (row.scope !== binding) return invalid(lane, 'grant_mismatch', `row ${row.id}'s scope ${JSON.stringify(row.scope.slice(0, 80))} is not this exception's binding ${binding}; a grant covers one repository, PR, head, tree, lane, run attempt and case list, so a new head needs a new grant`);
+  if (row.outcome !== 'approved') return invalid(lane, 'grant_not_approved', `row ${row.id} records outcome ${row.outcome}, not approved`);
+  if (/^agent:/i.test(row.by)) return invalid(lane, 'grant_not_owner', `row ${row.id} records an agent's words (${row.by}); only the owner grants an exception`);
+  return { exception: { ...subject, grant: row.id, by: row.by, words: row.words, binding } };
+}

lib/pregate/index.ts

@@ -14,7 +14,7 @@ import { spawnSync } from 'node:child_process';
 import { createHash } from 'node:crypto';
 import * as fs from 'node:fs';
 import * as path from 'node:path';
-import { ARTIFACT_SCHEMAS, checkSchema, type PregateFile, type PregateReceiptSubstitution, type PregateRemote, type ValidationError } from '../headless-artifacts';
+import { ARTIFACT_SCHEMAS, checkSchema, type PregateException, type PregateFile, type PregateReceiptSubstitution, type PregateRemote, type ValidationError } from '../headless-artifacts';
 import { wtreeFingerprint, type WtreeResult } from '../script-invocation';
 import { resolveStateRoot } from '../state-root';
 import { guardsCheck } from './checks/guards';
@@ -28,6 +28,7 @@ import { timingCheck } from './checks/timing';
 import { NON_DOWNGRADABLE, PREGATE_CONFIG_PATH, userPolicyAbsent } from './config';
 import { sha256, withFingerprint } from './context';
 import { baseBranchOf, baseMismatchFix, describeSubstitution, substituteStampOnlyTree } from './remote-receipt';
+import { EXCEPTION_RECEIPT, exceptionProblem, exceptionSummary, flakyDecision, flakyRuns, parseCases, redRunChanged, type FailureDeps, type FlakyInput } from './flaky-exception';
 import { buildRunCheck } from './run-check';
 import { resolveBaseBranch } from '../ship-policy';
 import { parseRunReceipt, parseRunRef, runChanged, runReceiptFields, uncoveredFiles, verifyRun, type ApiJob, type ApiRun, type RemoteGateRuns, type RunDeps, type RunEvidence, type RunProfile } from '../run-evidence';
@@ -134,6 +135,7 @@ export function verdictOf(file: PregateFile): string {
   if (statuses.has('incomplete') || statuses.has('not_installed')) return 'incomplete';
   const uncleared = (file.requires_remote ?? []).filter(r => !r.receipt);
   if (uncleared.length) return `requires-remote (${uncleared.length} uncleared)`;
+  if ((file.requires_remote ?? []).some(r => EXCEPTION_RECEIPT.test(r.receipt ?? ''))) return 'pass-with-exception';
   if (statuses.has('requires-remote')) return 'requires-remote cleared';
   if (statuses.has('warn')) return 'warn';
   return 'pass';
@@ -234,8 +236,12 @@ export function verifyPregate(repoRoot: string, file: PregateFile, treeNow: Wtre
   // A run receipt was verified online at clear for its tree; offline it must still name this tree (or carry its substitution).
   const foreignRuns = (file.requires_remote ?? []).filter(r => { const run = parseRunReceipt(r.receipt ?? ''); return run && !r.substitution && run.tree !== file.tree.slice(0, 12); });
   if (foreignRuns.length) return { ok: false, code: 'PREGATE_REMOTE_UNCLEARED', message: `${foreignRuns.length} run receipt(s) verified for another tree: ${foreignRuns.map(r => `${r.lane} (${r.receipt})`).join(', ')}; clear again with runs on tree ${file.tree.slice(0, 12)}`, current, uncleared: foreignRuns };
+  // A flaky exception was granted for one head, tree, run attempt and case list; recorded for another, or edited, it clears nothing.
+  const exception = exceptionProblem(file);
+  if (exception) return { ok: false, code: 'PREGATE_REMOTE_UNCLEARED', message: exception, current, uncleared: [] };
   const substituted = (file.requires_remote ?? []).filter(r => r.substitution).map(r => `${r.lane}: ${describeSubstitution(r.substitution!)}`);
-  return { ok: true, message: `pregate ${file.verdict} is current for tree ${file.tree.slice(0, 12)}${substituted.length ? `; ${substituted.join('; ')}` : ''}`, current, uncleared };
+  const excepted = exceptionSummary(file);
+  return { ok: true, message: `pregate ${file.verdict} is current for tree ${file.tree.slice(0, 12)}${substituted.length ? `; ${substituted.join('; ')}` : ''}${excepted ? `; ${excepted}` : ''}`, current, uncleared };
 }
 
 /**
@@ -259,10 +265,10 @@ function userPolicyChange(file: PregateFile): string | null {
   return `${absent} now holds a user-owned policy, and pregate.json was recorded under the defaults; rerun gstack-pregate`;
 }
 
-export interface ClearInput { runUrl?: string; bundleLane?: string; receiptPath?: string; runs?: string[]; evidence?: RunCheck }
+export interface ClearInput { runUrl?: string; bundleLane?: string; receiptPath?: string; runs?: string[]; evidence?: RunCheck; flaky?: FlakyInput }
 /** What a run clear needs: the base branch's run profiles, the verifier's dependencies, the clock, and the remote gate's inventory. */
-export interface RunCheck { repo: string; deps: RunDeps; profiles: Record<string, RunProfile>; gateRuns: RemoteGateRuns | null; now: Date; inventory: (command: string, tree: string, selected?: string[]) => string[] | { error: string } }
-export type ClearDecision = { receipt: string; attested: boolean; substitution?: PregateReceiptSubstitution } | { refused: 'usage' | 'PREGATE_RECEIPT_INVALID'; message: string; fix?: string };
+export interface RunCheck { repo: string; deps: RunDeps; profiles: Record<string, RunProfile>; gateRuns: RemoteGateRuns | null; now: Date; inventory: (command: string, tree: string, selected?: string[]) => string[] | { error: string }; failures?: FailureDeps }
+export type ClearDecision = { receipt: string; attested: boolean; substitution?: PregateReceiptSubstitution; exception?: PregateException } | { refused: 'usage' | 'PREGATE_RECEIPT_INVALID'; message: string; fix?: string };
 
 /**
  * What `clear` may record for one obligation. A `pregate.json/remote_gate`
@@ -284,12 +290,21 @@ export type ClearDecision = { receipt: string; attested: boolean; substitution?:
  * `--run` (and `--run-url` on a lane the base branch profiles) goes to
  * clearByRuns, which accepts only verified Actions runs; a profiled lane
  * refuses `--bundle-lane`, and the remote gate clears by runs only when the
- * base declares remote_gate_runs.
+ * base declares remote_gate_runs. `flaky` (`--flaky-exception`) takes runs with failures the same way under an owner's
+ * grant (lib/pregate/flaky-exception.ts).
  */
 export function clearDecision(file: PregateFile, lane: string, input: ClearInput, repoRoot: string): ClearDecision {
   const list = file.requires_remote ?? [];
   const target = list.find(r => r.lane === lane);
   if (!target) return { refused: 'usage', message: `no requires-remote obligation named ${lane}; obligations: ${list.map(r => r.lane).join(', ') || '(none)'}` };
+  if (input.flaky) {
+    const cases = parseCases(input.flaky.cases);
+    if (!Array.isArray(cases)) return cases;
+    const refs = [...(input.runs ?? []), ...(input.runUrl ? [input.runUrl] : [])];
+    if (!refs.length) return { refused: 'usage', message: '--flaky-exception needs --run <id|url>: an exception reads GitHub Actions runs' };
+    if (!input.flaky.pr) return { refused: 'usage', message: '--flaky-exception needs --pr <n>, the pull request the grant binds' };
+    return clearByRuns(file, lane, refs, input.evidence, repoRoot, { ...input.flaky, cases });
+  }
   const profiled = input.evidence && (lane === REMOTE_GATE_LANE ? input.evidence.gateRuns : input.evidence.profiles[lane]);
   if (input.runs?.length || (input.runUrl && profiled)) return clearByRuns(file, lane, [...(input.runs ?? []), ...(input.runUrl ? [input.runUrl] : [])], input.evidence, repoRoot);
   if (input.bundleLane && profiled && lane !== REMOTE_GATE_LANE) return { refused: 'usage', message: `${lane} has a run profile on the base branch; clear it with --run <id|url>, which verifies the run` };
@@ -372,7 +387,7 @@ function treeSubstitution(file: PregateFile, gatedTree: string, lane: string, re
  * does not run (never an inventory file); any other lane needs one verified run of the profile named after it. The run
  * tree must be pregate.json's tree or a stamp-only predecessor of it, exactly as a gate report's tree must.
  */
-function clearByRuns(file: PregateFile, lane: string, refs: string[], check: RunCheck | undefined, repoRoot: string): ClearDecision {
+function clearByRuns(file: PregateFile, lane: string, refs: string[], check: RunCheck | undefined, repoRoot: string, flaky?: FlakyInput & { cases: string[] }): ClearDecision {
   if (!check) return { refused: 'usage', message: `--run needs the base branch's run_profiles; none could be read` };
   const isGate = lane === REMOTE_GATE_LANE;
   const names = isGate ? check.gateRuns?.profiles ?? [] : check.profiles[lane] ? [lane] : [];
@@ -404,13 +419,17 @@ function clearByRuns(file: PregateFile, lane: string, refs: string[], check: Run
     }
     return null;
   };
-  const evidence = assign(0, new Set());
+  const red = flaky ? flakyRuns(lane, check, names, refs, file.head) : null;
+  if (red && 'refused' in red) return red;
+  const evidence = red ? red.evidence : assign(0, new Set());
   if (!evidence) {
     const failed = names.map(name => `${name}: ${refs.map(ref => { const v = verdict(name, ref); return v.ok ? `${ref} ok` : `${ref} reason=${v.reason} ${v.detail}`; }).join('; ')}`);
     return { refused: 'PREGATE_RECEIPT_INVALID', message: `REUSE: refused reason=no_verified_run — no run per profile verifies (${failed.join(' | ')}); ${lane} stays uncleared` };
   }
   const trees = [...new Set(evidence.map(e => e.tree))];
   if (trees.length > 1) return { refused: 'PREGATE_RECEIPT_INVALID', message: `REUSE: refused reason=tree_mismatch — the runs tested different trees (${trees.map(t => t.slice(0, 12)).join(', ')}); ${lane} stays uncleared` };
+  const off = red && evidence.find(e => e.head_sha !== file.head || e.tree !== file.tree);
+  if (off) return { refused: 'PREGATE_RECEIPT_INVALID', message: `FLAKY_EXCEPTION: refused reason=head_mismatch — run ${off.run_id} attempt ${off.run_attempt} tested head ${off.head_sha.slice(0, 12)} tree ${off.tree.slice(0, 12)}, not pregate.json's head ${(file.head ?? '').slice(0, 12)} tree ${file.tree.slice(0, 12)}; an exception binds the exact head and tree, never a stamp-only predecessor; ${lane} stays uncleared` };
   const sub = treeSubstitution(file, trees[0]!, lane, repoRoot);
   if ('refused' in sub) return { ...sub, message: `REUSE: refused reason=tree_not_stamp_only — ${sub.message}` };
   const idle = evidence.filter(e => (e.tests ?? e.files.length) === 0);
@@ -433,24 +452,29 @@ function clearByRuns(file: PregateFile, lane: string, refs: string[], check: Run
   }
   const missing = uncoveredFiles([...required], evidence);
   if (missing.length) return { refused: 'PREGATE_RECEIPT_INVALID', message: `REUSE: refused reason=${isGate ? 'inventory_uncovered' : 'tests_uncovered'} — ${missing.length} of the ${required.size} test file(s) ${lane} must cover appear in no run's tree.json (${missing.slice(0, 5).join(', ')}${missing.length > 5 ? ', …' : ''}); ${lane} stays uncleared` };
+  const granted = red ? flakyDecision(file, lane, check, red, flaky!, repoRoot) : null;
+  if (granted && 'refused' in granted) return granted;
   for (const e of evidence) {
     let changed: string | null;
-    try { changed = runChanged(check.deps, e.run_id, e.run_attempt); }
+    try { changed = red?.red.some(r => r.evidence === e) ? redRunChanged(check.deps, e.run_id, e.run_attempt) : runChanged(check.deps, e.run_id, e.run_attempt); }
     catch (err: any) { changed = `reading run ${e.run_id} again failed: ${String(err?.message ?? err).slice(0, 200)}`; }
     if (changed) return { refused: 'PREGATE_RECEIPT_INVALID', message: `REUSE: refused reason=run_changed — ${changed}; ${lane} stays uncleared` };
   }
   const tests = evidence.reduce((n, e) => n + (e.tests ?? e.files.length), 0);
   const accepted = sub.substitution ? ` accepted-for=${file.tree.slice(0, 12)} stamp-only=${sub.substitution.files.length}` : '';
-  return { receipt: `${isGate ? 'remote-gate' : 'run'} tree=${trees[0]!.slice(0, 12)} tests=${tests}${skippedCount ? ` skipped=${skippedCount}` : ''}${accepted} ${runReceiptFields(evidence, check.now)}`, attested: false, substitution: sub.substitution };
+  const exception = granted?.exception;
+  return { receipt: `${isGate ? 'remote-gate' : 'run'} tree=${trees[0]!.slice(0, 12)} tests=${tests}${skippedCount ? ` skipped=${skippedCount}` : ''}${exception ? ` exception=${exception.grant} cases=${exception.cases.length}` : ''}${accepted} ${runReceiptFields(evidence, check.now)}`, attested: false, substitution: sub.substitution, ...(exception ? { exception } : {}) };
 }
 
 /** Record the receipt that clears one obligation (a run URL, an evidence-bundle lane label, or a remote gate report, with the stamp-only substitution when one was accepted). */
-export function clearObligation(file: PregateFile, lane: string, receipt: string, by: string, substitution?: PregateReceiptSubstitution): PregateFile {
+export function clearObligation(file: PregateFile, lane: string, receipt: string, by: string, substitution?: PregateReceiptSubstitution, exception?: PregateException): PregateFile {
   const list = file.requires_remote ?? [];
   const target = list.find(r => r.lane === lane);
   if (!target) throw new Error(`no requires-remote obligation named ${lane}; obligations: ${list.map(r => r.lane).join(', ') || '(none)'}`);
   target.receipt = receipt; target.cleared_by = by;
   if (substitution) target.substitution = substitution; else delete target.substitution;
+  const exceptions = [...(file.exceptions ?? []).filter(e => e.lane !== lane), ...(exception ? [exception] : [])];
+  if (exceptions.length) file.exceptions = exceptions; else delete file.exceptions;
   file.verdict = verdictOf(file);
   return file;
 }

lib/pregate/run-check.ts

@@ -11,7 +11,7 @@ import { spawnSync } from 'node:child_process';
 import * as fs from 'node:fs';
 import * as os from 'node:os';
 import * as path from 'node:path';
-import { ghRunDeps, runInventory } from '../run-evidence';
+import { ghArtifactDeps, ghRunDeps, runInventory } from '../run-evidence';
 import { wtreeFingerprint } from '../script-invocation';
 import { resolveBaseBranch } from '../ship-policy';
 import { normalizeRemoteUrl } from '../ship-queue-train-record';
@@ -31,7 +31,7 @@ export function buildRunCheck(root: string, lane: string | null, allowRepoComman
   const repo = /^https:\/\/github\.com\/(.+)$/.exec(normalizeRemoteUrl(origin.status === 0 ? origin.stdout.trim() : ''))?.[1];
   if (!repo) return { error: 'origin is not a github.com repository; run evidence is read from GitHub Actions', profiled: lane === null ? false : lane === REMOTE_GATE_LANE ? !!loaded.config.remote_gate_runs : !!loaded.config.run_profiles[lane] };
   return {
-    repo, deps: ghRunDeps(repo, root), profiles: loaded.config.run_profiles, gateRuns: loaded.config.remote_gate_runs, now: new Date(),
+    repo, deps: ghRunDeps(repo, root), failures: ghArtifactDeps(repo), profiles: loaded.config.run_profiles, gateRuns: loaded.config.remote_gate_runs, now: new Date(),
     inventory: (command, tree, selected) => {
       if (!allowRepoCommands) return { error: 'the inventory command is a pin-file command; pass --allow-repo-commands' };
       const at = () => { const fp = wtreeFingerprint({ cwd: root }); return 'tree' in fp ? fp.tree : null; };

lib/run-evidence.ts

@@ -52,6 +52,13 @@ export interface ApiRun {
 export interface ApiJob { name: string; conclusion: string | null; completed_at?: string | null }
 export interface TreeRecord { run_id?: unknown; run_attempt?: unknown; event?: unknown; sha?: unknown; head_sha?: unknown; tree?: unknown; reused?: unknown; reuse?: unknown; os?: unknown; files?: unknown; tests?: unknown }
 
+/** What a red run's reader needs beyond RunDeps (lib/pregate/flaky-exception.ts): every file of one artifact, and a pull request's head. */
+export interface RunArtifactDeps {
+  /** Every file of the run's one unexpired artifact `name`, path → text; throws when it is missing, ambiguous or too large. */
+  artifactFiles(id: number, name: string): Record<string, string>;
+  pull(n: number): { head_sha: string; state: string; head_repo: string | null };
+}
+
 /** Everything verifyRun reads, injectable so every refusal has a fixture. */
 export interface RunDeps {
   run(id: number): ApiRun;
@@ -74,6 +81,8 @@ const WORKFLOW_FILE = /^[A-Za-z0-9_.-]+\.ya?ml$/;
 const NAME = /^[A-Za-z0-9_.\/-]{1,128}$/;
 export const DEFAULT_MAX_AGE_HOURS = 24;
 const MAX_ARTIFACT_BYTES = 8 * 1024 * 1024;
+/** Shard logs are the whole test stream, so a red run's reader allows more than a tree.json. */
+const MAX_LOG_ARTIFACT_BYTES = 64 * 1024 * 1024;
 
 /** A numeric run id, or a run URL on this repository (`…/actions/runs/<id>[/attempts/<n>][/job/<j>]`). */
 export function parseRunRef(ref: string, repo: string): number | null {
@@ -298,3 +307,37 @@ export function ghRunDeps(repo: string, repoRoot: string): RunDeps {
     },
   };
 }
+
+/** The gh-backed artifact and pull request reads for `repo` (lib/pregate/flaky-exception.ts): one unexpired artifact by name, every regular file in it under a byte cap. */
+export function ghArtifactDeps(repo: string): RunArtifactDeps {
+  const all = <T>(p: string, key: string): T[] => gh(['api', '--paginate', p, '--jq', `.${key}[]`]).split('\n').filter(Boolean).map(l => JSON.parse(l) as T);
+  return {
+    artifactFiles: (id, name) => {
+      const listed = all<{ name: string; size_in_bytes: number; expired: boolean }>(`repos/${repo}/actions/runs/${id}/artifacts?name=${encodeURIComponent(name)}&per_page=100`, 'artifacts').filter(a => a.name === name && !a.expired);
+      if (listed.length !== 1) throw new Error(`run ${id} has ${listed.length} unexpired artifacts named ${name}`);
+      if (!(listed[0]!.size_in_bytes <= MAX_LOG_ARTIFACT_BYTES)) throw new Error(`artifact ${name} is ${listed[0]!.size_in_bytes} bytes, over ${MAX_LOG_ARTIFACT_BYTES}`);
+      const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'gstack-run-evidence-'));
+      try {
+        gh(['run', 'download', String(id), '--repo', repo, '--name', name, '--dir', dir], 300_000);
+        const out: Record<string, string> = {};
+        let bytes = 0;
+        const walk = (rel: string) => {
+          for (const entry of fs.readdirSync(path.join(dir, rel), { withFileTypes: true })) {
+            const child = rel ? `${rel}/${entry.name}` : entry.name;
+            if (entry.isDirectory()) { walk(child); continue; }
+            if (!entry.isFile()) continue;
+            bytes += fs.statSync(path.join(dir, child)).size;
+            if (bytes > MAX_LOG_ARTIFACT_BYTES) throw new Error(`artifact ${name} unpacks to more than ${MAX_LOG_ARTIFACT_BYTES} bytes`);
+            out[child] = fs.readFileSync(path.join(dir, child), 'utf8');
+          }
+        };
+        walk('');
+        return out;
+      } finally { fs.rmSync(dir, { recursive: true, force: true }); }
+    },
+    pull: n => {
+      const p = JSON.parse(gh(['api', `repos/${repo}/pulls/${n}`])) as { state: string; head: { sha: string; repo: { full_name: string } | null } };
+      return { head_sha: p.head.sha, state: p.state, head_repo: p.head.repo?.full_name ?? null };
+    },
+  };
+}

lib/ship-queue.ts

@@ -29,6 +29,7 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import type { PregateFile } from './headless-artifacts';
 import { CHECKS, pregateMirrorPath, readPregateFile, verifyPregate, PREGATE_OUT_REL } from './pregate/index';
+import { exceptionConsumerProblem, flakyExceptionLines } from './pregate/flaky-exception';
 import { ensureTmpExcluded, restamp, versionAtRef } from './restamp';
 import type { ResultCodeName } from './result-codes';
 import { extractReceipt } from './ship-receipt';
@@ -232,6 +233,7 @@ export function ready(ctx: QueueContext, o: { pr: string; pregate?: string; gate
   const pregateFile = path.resolve(ctx.repoRoot, o.pregate ?? PREGATE_OUT_REL);
   let pregateLine = `PREGATE: missing (${path.relative(ctx.repoRoot, pregateFile)}; run gstack-pregate run --allow-repo-commands)`;
   let pregateOk = false;
+  let accepted: PregateFile | null = null;
   const treeNow = wtreeFingerprint({ cwd: ctx.repoRoot });
   // The mirror stands in for a record that is missing, unreadable, recorded for another tree, or current but
   // waiting on a remote receipt another checkout holds; a record whose own checks failed or stayed incomplete (the diff's doing
@@ -242,6 +244,7 @@ export function ready(ctx: QueueContext, o: { pr: string; pregate?: string; gate
     if (read.file) {
       const v = verifyPregate(ctx.repoRoot, read.file, treeNow);
       pregateOk = v.ok;
+      if (v.ok) accepted = read.file;
       useMirror = !v.ok && v.code !== 'PREGATE_LANE_FAILED' && v.code !== 'PREGATE_INCOMPLETE' && v.code !== 'PREGATE_ENVIRONMENT';
       pregateLine = `PREGATE: ${read.file.verdict} tree=${read.file.tree.slice(0, 12)} head=${(read.file.head ?? '').slice(0, 12)} checks=${read.file.checks.length}${v.ok ? '' : ` — ${v.message} (${v.code})`}`;
     } else pregateLine = `PREGATE: unreadable (${read.errors[0]?.message ?? 'invalid'})`;
@@ -253,9 +256,12 @@ export function ready(ctx: QueueContext, o: { pr: string; pregate?: string; gate
     const v = read?.file && !gap ? verifyPregate(ctx.repoRoot, read.file, treeNow) : null;
     if (read?.file && v?.ok) {
       pregateOk = true;
+      accepted = read.file;
       pregateLine = `PREGATE: ${read.file.verdict} tree=${read.file.tree.slice(0, 12)} head=${(read.file.head ?? '').slice(0, 12)} checks=${read.file.checks.length} (from the state root's pregate/by-tree/${treeNow.tree.slice(0, 12)}.json, recorded by another checkout)`;
     } else if (gap) pregateLine += `; the state root's mirror for this tree cannot stand in: ${gap}`;
   }
+  const foreign = accepted && exceptionConsumerProblem(accepted, head, o.pr);
+  if (foreign) { pregateOk = false; accepted = null; pregateLine += ` — ${foreign} (PREGATE_REMOTE_UNCLEARED)`; }
   const receipt = bindShippedReceipt(ctx.repoRoot, `origin/${ctx.base}`, info.body ?? '', o.pr, acceptedReceiptHeads(ctx, policy, head, info.body ?? ''));
   const attempt = currentAttempt(ctx.repoRoot, o.pr);
   const hint = conflictHint(info.mergeable, ci, info.headRefName, info.isCrossRepository === true, head);
@@ -268,6 +274,7 @@ export function ready(ctx: QueueContext, o: { pr: string; pregate?: string; gate
     `ci: ${ci.line}`,
     ...(hint ? [hint] : []),
     pregateLine,
+    ...(accepted ? flakyExceptionLines(accepted) : []),
     gateLine(policy, attempt),
     receipt.line,
     ...(receipt.depthLine ? [receipt.depthLine] : []),

lib/ship-receipt.ts

@@ -19,7 +19,7 @@ const KEY_ORDER: Array<keyof ShipReceipt | 'docs'> = [
   'schema_version', 'pr', 'head', 'version', 'base', 'gated_tree', 'predecessor', 'tree', 'gate_reuse', 'gate', 'ci', 'ci_carried', 'spend_usd',
   'session_kind', 'artifacts_consumed', 'run', 'thread', 'policy', 'queue_mode', 'preregistration', 'history',
   'head_tree', 'product_patch_id', 'gstack_version', 'review_depth', 'pregate', 'requires_remote', 'issues', 'approval', 'docs', 'review_loop',
-  'review_loop_exception', 'review_targeted', 'review_exclude', 'carry', 'base_red',
+  'review_loop_exception', 'review_targeted', 'review_exclude', 'carry', 'base_red', 'flaky_exception',
 ];
 
 /** Keys in the fixed order so identifiers lead; undefined values are dropped. */

package.json

@@ -1,6 +1,6 @@
 {
   "name": "gstack",
-  "version": "1.94.8",
+  "version": "1.94.9",
   "description": "Garry's Stack — Claude Code skills + fast headless browser. One repo, one install, entire AI engineering workflow.",
   "license": "MIT",
   "type": "module",

test/pregate-flaky-exception.test.ts

@@ -0,0 +1,317 @@
+/**
+ * gstack-pregate clear --flaky-exception (GST-1096): a red GitHub Actions run clears a requires-remote obligation only
+ * when every failure is named from the run's own shard results and logs, each named file is outside the PR's diff and
+ * its import closure, at most three cases, none paid or a security scan, and an owner's gstack-approvals row binds the
+ * repository, PR, head, tree, lane, run, attempt and cases. verify prints pass-with-exception, ready prints
+ * FLAKY_EXCEPTION and still needs green CI (pregate only), and the receipt records it. The run API is a fake; trees
+ * come from the fixture repository's git.
+ */
+import { afterEach, describe, expect, test } from 'bun:test';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { EXIT, type PregateFile } from '../lib/headless-artifacts';
+import { buildContext } from '../lib/pregate/context';
+import { clearDecision, clearObligation, runPregate, verifyPregate, type ClearDecision, type RunCheck } from '../lib/pregate/index';
+import { exceptionBinding, type FailureDeps, type GrantRow } from '../lib/pregate/flaky-exception';
+import type { ApiJob, ApiRun, RunDeps, RunProfile } from '../lib/run-evidence';
+import { BASE_PREGATE, cleanup, commit, makeFixtureRepo, runBin, type FixtureRepo } from './helpers/pregate-fixture';
+import { cleanup as cleanupQueue, makeFixtureRepo as makeQueueRepo, makePr, runBin as runQueueBin } from './helpers/restamp-fixture';
+import { ghQueueShim } from './helpers/ship-queue-fixture';
+import { shippedBody } from './helpers/ship-queue-train-fixture';
+
+const repos: FixtureRepo[] = [];
+const queueRepos: Array<ReturnType<typeof makeQueueRepo>> = [];
+afterEach(() => {
+  while (repos.length) cleanup(repos.pop()!);
+  while (queueRepos.length) cleanupQueue(queueRepos.pop()!);
+});
+
+const LANE = 'pregate.json/remote_gate';
+const NOW = new Date('2026-10-29T12:00:00Z');
+const PROFILE_NAME = 'ci-reuse/free-tests';
+const PROFILE: RunProfile = { workflow: 'free-tests.yml', events: ['pull_request', 'workflow_dispatch'], jobs: ['free-plan', 'typecheck', 'free-tests'], artifact: 'tested-tree' };
+const GATE_RUNS = { profiles: [PROFILE_NAME], inventory: 'true' };
+const FLAKE = 'test/retry.test.js::retries three times';
+const WORDS = 'yes, accept the retry timing flake for this head';
+
+function fixture(): FixtureRepo {
+  const repo = makeFixtureRepo({ pregate: { ...BASE_PREGATE, remote_gate: 'node scripts/remote-gate.js' } });
+  repos.push(repo);
+  commit(repo, { 'lib/util.js': 'exports.add = (a, b) => a + b + 0;\n' }, 'the real change');
+  return repo;
+}
+
+async function pregateAt(repo: FixtureRepo): Promise<PregateFile> {
+  const loaded = buildContext({ repoRoot: repo.work, base: 'main', policyFrom: 'base', allowRepoCommands: true, env: { ...process.env, ...repo.env }, progress: () => {}, cores: 4, testBackend: 'local' });
+  if (!('ctx' in loaded)) throw new Error('fixture context refused');
+  const file = await runPregate(loaded.ctx, { stage: 'tests' });
+  expect(file.requires_remote).toEqual([expect.objectContaining({ lane: LANE, receipt: null })]);
+  return file;
+}
+
+interface Shard { files: string[]; failures?: Array<[string | null, string]>; status?: 'passed' | 'failed' | 'timed-out'; unattributed?: number; retry?: { files: string[]; failures: Array<[string, string]> }; log?: string | null }
+interface RunOver { conclusion?: string; jobs?: (jobs: ApiJob[]) => ApiJob[]; missing?: string[]; pull?: { head_sha: string; state: string; head_repo: string | null }; newer?: boolean; attemptAfter?: number; api?: Partial<ApiRun> }
+
+const DEFAULT_SHARDS: Shard[] = [
+  { files: ['test/retry.test.js', 'test/a.test.ts'], failures: [['test/retry.test.js', 'retries three times']] },
+  { files: ['test/b.test.ts', 'test/util.test.js', 'test/config-read.test.js', 'test/tool-cli.test.js'] },
+];
+
+function logFor(s: Shard, names: Array<[string | null, string]>): string {
+  const lines: string[] = [];
+  for (const f of s.files) {
+    lines.push(`${f}:`);
+    for (const [file, name] of names) if (file === f) lines.push(`(fail) ${name} [5005.00ms]`);
+  }
+  lines.push(`Ran ${s.files.length * 3} tests across ${s.files.length} files. [12.00s]`);
+  return lines.join('\n') + '\n';
+}
+
+/** Run 400: a red workflow_dispatch Free Tests run on `head` whose shard artifacts and logs say what failed. */
+function redRun(repo: FixtureRepo, head: string, shards: Shard[] = DEFAULT_SHARDS, over: RunOver = {}): RunCheck & { failures: FailureDeps } {
+  const plan = { version: 1, revision: head, id: 'plan-1', shards: shards.map((s, i) => ({ shard: i + 1, files: s.files, predictedMs: 1000 })) };
+  const statusOf = (s: Shard) => s.status ?? (s.failures?.length || s.unattributed ? 'failed' : 'passed');
+  const finalFailed = (s: Shard) => statusOf(s) !== 'passed' && !(s.retry && s.retry.failures.length === 0);
+  const outcome = (s: Shard, i: number, files: string[], failures: Array<[string | null, string]>, status: string) => ({
+    shard: i + 1, files, status, exitCode: status === 'passed' ? 0 : 1, elapsedMs: 1000, groupPid: null,
+    summary: { testsRan: files.length * 3, filesRan: files.length, sawTerminalSummary: status !== 'timed-out' },
+    failingFiles: [...new Set(failures.map(([f]) => f).filter((f): f is string => !!f))], unattributedFailures: s.unattributed ?? 0,
+    failures: failures.map(([file, testName]) => ({ file, testName })),
+  });
+  const artifacts: Record<string, Record<string, string>> = { 'free-plan': { 'free-plan.json': JSON.stringify(plan) } };
+  shards.forEach((s, i) => {
+    const retry = s.retry ? outcome({ files: s.retry.files }, i, s.retry.files, s.retry.failures, s.retry.failures.length ? 'failed' : 'passed') : null;
+    artifacts[`free-result-${i + 1}`] = { [`shard-${i + 1}.json`]: JSON.stringify({ planId: 'plan-1', revision: head, outcome: outcome(s, i, s.files, s.failures ?? [], statusOf(s)), retry }) };
+    if (statusOf(s) !== 'passed' && s.log !== null) artifacts[`free-test-shard-logs-${i + 1}`] = { [`gstack-free-test-${i + 1}.log`]: s.log ?? logFor(s, [...(s.failures ?? []), ...(s.retry?.failures ?? [])]) };
+  });
+  for (const m of over.missing ?? []) delete artifacts[m];
+  const anyFailed = shards.some(finalFailed);
+  const at = '2026-10-29T10:30:00Z';
+  const baseJobs: ApiJob[] = [
+    { name: 'reuse', conclusion: 'skipped', completed_at: at },
+    { name: 'free-plan', conclusion: 'success', completed_at: at },
+    { name: 'typecheck', conclusion: 'success', completed_at: at },
+    ...shards.map((s, i) => ({ name: `free-suite (${i + 1})`, conclusion: finalFailed(s) ? 'failure' : 'success', completed_at: at })),
+    { name: 'free-tests', conclusion: anyFailed ? 'failure' : 'success', completed_at: at },
+  ];
+  const jobs = over.jobs ? over.jobs(baseJobs) : baseJobs;
+  let reads = 0;
+  const api = (): ApiRun => ({
+    id: 400, run_attempt: reads++ > 0 && over.attemptAfter ? over.attemptAfter : 1, status: 'completed', conclusion: over.conclusion ?? (anyFailed ? 'failure' : 'success'), event: 'workflow_dispatch', head_sha: head,
+    path: '.github/workflows/free-tests.yml', created_at: '2026-10-29T10:00:00Z', updated_at: at, repository: { full_name: 'fx/fx' }, head_repository: { full_name: 'fx/fx' }, ...over.api,
+  });
+  const deps: RunDeps = {
+    run: id => { if (id !== 400) throw new Error('HTTP 404'); return api(); },
+    runsForHead: () => [{ ...api(), run_attempt: 1 }, ...(over.newer ? [{ ...api(), id: 401, run_attempt: 1, created_at: '2026-10-29T11:00:00Z', run_started_at: '2026-10-29T11:00:00Z' }] : [])],
+    jobs: () => jobs,
+    artifact: () => { throw new Error('run 400 has 0 unexpired artifacts named tested-tree'); },
+    commitTree: sha => repo.git('rev-parse', `${sha}^{tree}`),
+  };
+  const failures: FailureDeps = {
+    artifactFiles: (_id, name) => { const a = artifacts[name]; if (!a) throw new Error(`run 400 has 0 unexpired artifacts named ${name}`); return a; },
+    pull: () => over.pull ?? { head_sha: head, state: 'open', head_repo: 'fx/fx' },
+  };
+  return { repo: 'fx/fx', deps, profiles: { [PROFILE_NAME]: PROFILE }, gateRuns: GATE_RUNS, now: NOW, inventory: () => ['test/a.test.ts', 'test/b.test.ts'], failures };
+}
+
+const msg = (d: ClearDecision) => ('refused' in d ? `${d.refused}: ${d.message}${d.fix ? `; fix: ${d.fix}` : ''}` : `cleared ${d.receipt}`);
+
+/** The scope the grant-needed refusal names, as an approvals row the owner granted. */
+function grantFor(d: ClearDecision, over: Partial<GrantRow> = {}): (id: string) => GrantRow | null {
+  const scope = /--scope "(flaky-exception:[0-9a-f]{64})"/.exec(msg(d))?.[1];
+  if (!scope) throw new Error(`no grant scope in: ${msg(d)}`);
+  return id => (id === 'a-1' ? { id, outcome: 'approved', scope, words: WORDS, by: 'Garry', ...over } : null);
+}
+
+describe.skipIf(process.platform === 'win32')('clear --flaky-exception: an owner-granted exception for named flaky cases', () => {
+  test('a red run whose only failure is the named case clears the gate once the bound grant exists; verify reports pass-with-exception', async () => {
+    const repo = fixture();
+    const head = repo.git('rev-parse', 'HEAD');
+    const file = await pregateAt(repo);
+    const check = redRun(repo, head);
+    const asked = clearDecision(file, LANE, { runs: ['400'], evidence: check, flaky: { cases: [FLAKE], pr: 7 } }, repo.work);
+    expect(msg(asked)).toMatch(/^PREGATE_RECEIPT_INVALID: FLAKY_EXCEPTION: refused reason=grant_needed — .*test\/retry\.test\.js::retries three times.*; fix: .*gstack-approvals add --ask '.*' --words "<the owner's exact words>" --by "<owner>" --scope "flaky-exception:[0-9a-f]{64}" --source pregate-flaky-exception/);
+    const d = clearDecision(file, LANE, { runs: ['400'], evidence: check, flaky: { cases: [FLAKE], pr: 7, grant: 'a-1', grantRow: grantFor(asked) } }, repo.work);
+    if ('refused' in d) throw new Error(d.message);
+    expect(d.receipt).toBe(`remote-gate tree=${file.tree.slice(0, 12)} tests=18 exception=a-1 cases=1 runs=400/1 profiles=${PROFILE_NAME} heads=${head.slice(0, 12)} verified=2026-10-29T12:00:00.000Z`);
+    expect(d.exception).toMatchObject({ lane: LANE, repo: 'fx/fx', pr: 7, head, tree: file.tree, runs: ['400/1'], cases: [FLAKE], grant: 'a-1', by: 'Garry', words: WORDS });
+    const cleared = clearObligation(file, LANE, d.receipt, 'test', d.substitution, d.exception);
+    expect(cleared.verdict).toBe('pass-with-exception');
+    expect(cleared.exceptions).toEqual([d.exception!]);
+    const v = verifyPregate(repo.work, cleared, { tree: file.tree } as any);
+    expect(v).toMatchObject({ ok: true });
+    expect(v.message).toContain(`flaky exception ${FLAKE} (grant a-1, by Garry, run 400/1)`);
+    const tampered = (e: Partial<NonNullable<PregateFile['exceptions']>[number]>) => verifyPregate(repo.work, { ...cleared, exceptions: [{ ...cleared.exceptions![0]!, ...e }] }, { tree: file.tree } as any);
+    expect(tampered({ head: 'f'.repeat(40) })).toMatchObject({ ok: false, code: 'PREGATE_REMOTE_UNCLEARED' });
+    expect(tampered({ cases: [FLAKE, 'test/b.test.ts::other'] }).message).toContain('binding does not match');
+    expect(verifyPregate(repo.work, { ...cleared, exceptions: [] }, { tree: file.tree } as any).message).toContain('no exceptions entry');
+    const plain = clearObligation(structuredClone(cleared), LANE, `remote-gate tree=${file.tree.slice(0, 12)} tests=18 runs=401/1 profiles=${PROFILE_NAME} heads=${head.slice(0, 12)} verified=2026-10-29T12:00:00.000Z`, 'test');
+    expect([plain.exceptions, plain.verdict]).toEqual([undefined, 'requires-remote cleared']);
+  }, 120_000);
+
+  test('the grant binds the head, PR, run and cases: another scope, an unapproved row, an agent\'s words or an unknown id refuse', async () => {
+    const repo = fixture();
+    const head = repo.git('rev-parse', 'HEAD');
+    const file = await pregateAt(repo);
+    const check = redRun(repo, head);
+    const asked = clearDecision(file, LANE, { runs: ['400'], evidence: check, flaky: { cases: [FLAKE], pr: 7 } }, repo.work);
+    const run = (grantRow: (id: string) => GrantRow | null, grant = 'a-1') => msg(clearDecision(file, LANE, { runs: ['400'], evidence: check, flaky: { cases: [FLAKE], pr: 7, grant, grantRow } }, repo.work));
+    const otherHead = exceptionBinding({ lane: LANE, repo: 'fx/fx', pr: 7, head: 'e'.repeat(40), tree: file.tree, runs: ['400/1'], cases: [FLAKE] });
+    expect(run(grantFor(asked, { scope: otherHead }))).toContain('reason=grant_mismatch');
+    expect(run(grantFor(asked, { outcome: 'pending' }))).toContain('reason=grant_not_approved');
+    expect(run(grantFor(asked, { by: 'agent:jam_123' }))).toContain('reason=grant_not_owner');
+    expect(run(grantFor(asked), 'a-2')).toContain('reason=grant_missing');
+  }, 120_000);
+
+  test('every failure must be named: an extra failure, a case that did not fail, more than three cases, an unattributed failure refuse', async () => {
+    const repo = fixture();
+    const head = repo.git('rev-parse', 'HEAD');
+    const file = await pregateAt(repo);
+    const clear = (check: RunCheck, cases = [FLAKE]) => msg(clearDecision(file, LANE, { runs: ['400'], evidence: check, flaky: { cases, pr: 7 } }, repo.work));
+    const two: Shard[] = [{ files: ['test/retry.test.js', 'test/a.test.ts'], failures: [['test/retry.test.js', 'retries three times'], ['test/a.test.ts', 'other']] }, DEFAULT_SHARDS[1]!];
+    expect(clear(redRun(repo, head, two))).toContain('reason=unnamed_failure — run 400 attempt 1 failed test/a.test.ts::other, which no --flaky-exception names');
+    expect(clear(redRun(repo, head), [FLAKE, 'test/a.test.ts::passed fine'])).toContain('reason=case_not_failed — test/a.test.ts::passed fine did not fail in run 400');
+    expect(clear(redRun(repo, head), ['a.ts::1', 'b.ts::2', 'c.ts::3', 'd.ts::4'])).toBe('usage: --flaky-exception names at most 3 cases; got 4');
+    expect(clear(redRun(repo, head), ['no-separator'])).toContain('usage: --flaky-exception takes "<test file>::<case>"');
+    expect(clear(redRun(repo, head, [{ ...DEFAULT_SHARDS[0]!, unattributed: 1 }, DEFAULT_SHARDS[1]!]))).toContain('reason=unnamed_failure — shard 1: 1 failure(s) the runner could not attribute to a test');
+    expect(clear(redRun(repo, head, [{ ...DEFAULT_SHARDS[0]!, failures: [[null, 'retries three times']] }, DEFAULT_SHARDS[1]!]))).toContain('reason=unnamed_failure');
+    expect(clear(redRun(repo, head, [{ files: DEFAULT_SHARDS[0]!.files }, DEFAULT_SHARDS[1]!]))).toContain('reason=run_green');
+  }, 120_000);
+
+  test('every job, shard and log is reconciled: a failed non-shard job, a missing result or log, a timed-out shard, a log failure the result omits refuse', async () => {
+    const repo = fixture();
+    const head = repo.git('rev-parse', 'HEAD');
+    const file = await pregateAt(repo);
+    const clear = (check: RunCheck) => msg(clearDecision(file, LANE, { runs: ['400'], evidence: check, flaky: { cases: [FLAKE], pr: 7 } }, repo.work));
+    expect(clear(redRun(repo, head, DEFAULT_SHARDS, { jobs: js => js.map(j => j.name === 'typecheck' ? { ...j, conclusion: 'failure' } : j) }))).toContain('reason=unnamed_failure — run 400 attempt 1\'s typecheck job concluded failure; only test-shard failures can be named');
+    expect(clear(redRun(repo, head, DEFAULT_SHARDS, { jobs: js => js.map(j => j.name === 'reuse' ? { ...j, conclusion: 'cancelled' } : j) }))).toContain('reason=unnamed_failure — run 400 attempt 1\'s reuse job concluded cancelled');
+    expect(clear(redRun(repo, head, DEFAULT_SHARDS, { jobs: js => js.filter(j => j.name !== 'free-suite (2)') }))).toContain('reason=shard_mismatch');
+    expect(clear(redRun(repo, head, DEFAULT_SHARDS, { missing: ['free-result-2'] }))).toContain('reason=shard_incomplete — shard 2 has no readable free-result-2');
+    expect(clear(redRun(repo, head, [{ ...DEFAULT_SHARDS[0]!, log: null }, DEFAULT_SHARDS[1]!]))).toContain('reason=logs_missing — shard 1 failed and has no readable free-test-shard-logs-1');
+    expect(clear(redRun(repo, head, [{ ...DEFAULT_SHARDS[0]!, status: 'timed-out' }, DEFAULT_SHARDS[1]!]))).toContain('reason=shard_incomplete — shard 1 timed out');
+    const extraInLog = logFor(DEFAULT_SHARDS[0]!, [['test/retry.test.js', 'retries three times'], ['test/a.test.ts', 'hidden']]);
+    expect(clear(redRun(repo, head, [{ ...DEFAULT_SHARDS[0]!, log: extraInLog }, DEFAULT_SHARDS[1]!]))).toContain('reason=unnamed_failure — shard 1\'s log names test/a.test.ts::hidden, which its result does not');
+    expect(clear(redRun(repo, head, [{ ...DEFAULT_SHARDS[0]!, log: logFor(DEFAULT_SHARDS[0]!, [['test/retry.test.js', 'retries three times']]) + '# Unhandled error between tests\n' }, DEFAULT_SHARDS[1]!]))).toContain('reason=unnamed_failure — shard 1\'s log shows 1 unhandled error(s) between tests');
+    expect(clear(redRun(repo, head, DEFAULT_SHARDS, { conclusion: 'cancelled' }))).toContain('reason=run_not_failure');
+    expect(clear(redRun(repo, head, DEFAULT_SHARDS, { newer: true }))).toContain('reason=newer_run');
+    expect(clear(redRun(repo, head, DEFAULT_SHARDS, { attemptAfter: 2 }))).toContain('reason=run_changed');
+    expect(clear(redRun(repo, head, DEFAULT_SHARDS, { api: { repository: { full_name: 'other/fx' } } }))).toContain('reason=other_repository');
+    expect(clear(redRun(repo, head, DEFAULT_SHARDS, { api: { head_repository: { full_name: 'fork/fx' } } }))).toContain('reason=fork_run');
+    expect(clear(redRun(repo, head, DEFAULT_SHARDS, { api: { path: '.github/workflows/evals.yml' } }))).toContain('reason=workflow_mismatch');
+    expect(clear(redRun(repo, head, DEFAULT_SHARDS, { api: { event: 'push' } }))).toContain('reason=event_mismatch');
+    expect(clear(redRun(repo, head, DEFAULT_SHARDS, { api: { status: 'in_progress' } }))).toContain('reason=run_in_progress');
+    expect(clear(redRun(repo, head, DEFAULT_SHARDS, { jobs: js => js.map(j => ({ ...j, completed_at: '2026-10-27T10:30:00Z' })) }))).toContain('reason=run_stale');
+  }, 120_000);
+
+  test('a red run that moves while the clear is assembled refuses, and the printed grant command quotes case names for the shell', async () => {
+    const repo = fixture();
+    const head = repo.git('rev-parse', 'HEAD');
+    const file = await pregateAt(repo);
+    const check = redRun(repo, head);
+    const asked = clearDecision(file, LANE, { runs: ['400'], evidence: check, flaky: { cases: [FLAKE], pr: 7 } }, repo.work);
+    let rerun = false;
+    const run = check.deps.run;
+    const moving: RunCheck = { ...check, deps: { ...check.deps, run: id => (rerun ? { ...run(id), run_attempt: 2, status: 'in_progress' } : run(id)) }, inventory: () => { rerun = true; return ['test/a.test.ts', 'test/b.test.ts'] } };
+    expect(msg(clearDecision(file, LANE, { runs: ['400'], evidence: moving, flaky: { cases: [FLAKE], pr: 7, grant: 'a-1', grantRow: grantFor(asked) } }, repo.work))).toContain('reason=run_changed — run 400 moved to attempt 2 (in_progress)');
+    const name = "times out $(touch pwned) `id` it's";
+    const shard: Shard[] = [{ files: ['test/retry.test.js', 'test/a.test.ts'], failures: [['test/retry.test.js', name]] }, DEFAULT_SHARDS[1]!];
+    const fix = msg(clearDecision(file, LANE, { runs: ['400'], evidence: redRun(repo, head, shard), flaky: { cases: [`test/retry.test.js::${name}`], pr: 7 } }, repo.work));
+    const ask = /--ask ('(?:[^']|'\\'')*') --words/.exec(fix)?.[1];
+    expect(ask).toBeDefined();
+    const echoed = Bun.spawnSync(['bash', '-c', `printf %s ${ask}`], { cwd: repo.work, timeout: 10_000 });
+    expect(echoed.stdout.toString()).toContain(`test/retry.test.js::${name}`);
+    expect(fs.existsSync(path.join(repo.work, 'pwned'))).toBe(false);
+  }, 120_000);
+
+  test('a retry that passed is a recovered flake; a retry that failed again keeps only its own failures', async () => {
+    const repo = fixture();
+    const head = repo.git('rev-parse', 'HEAD');
+    const file = await pregateAt(repo);
+    const shard1: Shard = { files: ['test/retry.test.js', 'test/a.test.ts'], failures: [['test/retry.test.js', 'retries three times'], ['test/a.test.ts', 'recovered']], retry: { files: ['test/retry.test.js', 'test/a.test.ts'], failures: [['test/retry.test.js', 'retries three times']] } };
+    expect(msg(clearDecision(file, LANE, { runs: ['400'], evidence: redRun(repo, head, [shard1, DEFAULT_SHARDS[1]!]), flaky: { cases: [FLAKE], pr: 7 } }, repo.work))).toContain('reason=grant_needed');
+  }, 120_000);
+
+  test('a named file inside the PR diff or its import closure, a paid file or a security scan test refuses', async () => {
+    const repo = fixture();
+    const head = repo.git('rev-parse', 'HEAD');
+    const file = await pregateAt(repo);
+    const one = (fileName: string, name: string) => {
+      const check = redRun(repo, head, [{ files: [fileName, 'test/retry.test.js', 'test/a.test.ts'].filter((f, i, a) => a.indexOf(f) === i), failures: [[fileName, name]] }, { files: DEFAULT_SHARDS[1]!.files.filter(f => f !== fileName) }]);
+      return msg(clearDecision(file, LANE, { runs: ['400'], evidence: check, flaky: { cases: [`${fileName}::${name}`], pr: 7 } }, repo.work));
+    };
+    expect(one('test/util.test.js', 'adds')).toContain('reason=case_in_closure — test/util.test.js depends on a file the PR changes (lib/util.js)');
+    expect(one('test/skill-e2e-flaky.test.ts', 'judge')).toContain('reason=case_paid — test/skill-e2e-flaky.test.ts is a paid test file');
+    expect(one('test/cso-docker-policy.test.ts', 'times out')).toContain('reason=case_security — test/cso-docker-policy.test.ts tests a security scan');
+    expect(one('test/ship-template-redaction.test.ts', 'blocks')).toContain('reason=case_security');
+    expect(one('browse/test/content-security.test.ts', 'blocks')).toContain('reason=case_security');
+
+    const touched = fixture();
+    commit(touched, { 'test/retry.test.js': "const test = require('node:test');\ntest('retries three times', () => {});\n" }, 'touch the flaky test');
+    const touchedHead = touched.git('rev-parse', 'HEAD');
+    const touchedFile = await pregateAt(touched);
+    expect(msg(clearDecision(touchedFile, LANE, { runs: ['400'], evidence: redRun(touched, touchedHead), flaky: { cases: [FLAKE], pr: 7 } }, touched.work))).toContain('reason=case_in_diff — test/retry.test.js is in the PR\'s diff');
+  }, 120_000);
+
+  test('the run must be at pregate.json\'s own head and tree, and the PR head must be that head: no rebinding', async () => {
+    const repo = fixture();
+    const older = repo.git('rev-parse', 'HEAD~1');
+    const head = repo.git('rev-parse', 'HEAD');
+    const file = await pregateAt(repo);
+    const clear = (check: RunCheck) => msg(clearDecision(file, LANE, { runs: ['400'], evidence: check, flaky: { cases: [FLAKE], pr: 7 } }, repo.work));
+    expect(clear(redRun(repo, older))).toContain('reason=head_mismatch');
+    expect(clear(redRun(repo, head, DEFAULT_SHARDS, { pull: { head_sha: older, state: 'open', head_repo: 'fx/fx' } }))).toContain('reason=pr_mismatch — PR #7\'s head is');
+    expect(clear(redRun(repo, head, DEFAULT_SHARDS, { pull: { head_sha: head, state: 'closed', head_repo: 'fx/fx' } }))).toContain('reason=pr_mismatch — PR #7 is closed');
+  }, 120_000);
+
+  test('the bins: clear refuses --flaky-exception without --run or --pr; verify prints the PREGATE pass-with-exception line; the receipt records it', async () => {
+    const repo = fixture();
+    const head = repo.git('rev-parse', 'HEAD');
+    const file = await pregateAt(repo);
+    const out = path.join(repo.work, '.gstack/tmp/pregate.json');
+    fs.mkdirSync(path.dirname(out), { recursive: true });
+    fs.writeFileSync(out, JSON.stringify(file));
+    const noRun = runBin(repo, 'gstack-pregate', ['clear', '--remote', LANE, '--flaky-exception', FLAKE, '--pr', '7', '--out', out]);
+    expect([noRun.status, noRun.err]).toEqual([EXIT.usage, expect.stringContaining('--flaky-exception needs --run <id|url>')]);
+    const noPr = runBin(repo, 'gstack-pregate', ['clear', '--remote', LANE, '--run', '400', '--flaky-exception', FLAKE, '--out', out]);
+    expect([noPr.status, noPr.err]).toEqual([EXIT.usage, expect.stringContaining('--flaky-exception needs --pr <n>')]);
+    const exception = { lane: LANE, repo: 'fx/fx', pr: 7, head, tree: file.tree, runs: ['400/1'], cases: [FLAKE] };
+    const recorded = { ...exception, grant: 'a-1', by: 'Garry', words: WORDS, binding: exceptionBinding(exception) };
+    const cleared = clearObligation(file, LANE, `remote-gate tree=${file.tree.slice(0, 12)} tests=18 exception=a-1 cases=1 runs=400/1 profiles=${PROFILE_NAME} heads=${head.slice(0, 12)} verified=2026-10-29T12:00:00.000Z`, 'test', undefined, recorded);
+    fs.writeFileSync(out, JSON.stringify(cleared));
+    const v = runBin(repo, 'gstack-pregate', ['verify', '--out', out]);
+    expect([v.status, v.err]).toEqual([EXIT.ok, '']);
+    expect(v.out).toContain(`PREGATE: pass-with-exception (${FLAKE}; grant a-1)\n`);
+    const bound = runBin(repo, 'gstack-ship-receipt', ['write', '--pr', '7', '--base', 'main', '--version', '1.0.0', '--session-kind', 'interactive', '--pregate', out, '--json']);
+    expect([bound.status, bound.err]).toEqual([EXIT.ok, expect.any(String)]);
+    expect(bound.out).toContain('"flaky_exception":[{"lane":"pregate.json/remote_gate","runs":["400/1"],"cases":["test/retry.test.js::retries three times"],"grant":"a-1","by":"Garry"}]');
+  }, 180_000);
+});
+
+describe.skipIf(process.platform === 'win32')('ready with a flaky exception', () => {
+  test('ready accepts pass-with-exception, prints FLAKY_EXCEPTION, and still refuses a red required check (pregate only)', () => {
+    const repo = makeQueueRepo();
+    queueRepos.push(repo);
+    const head = makePr(repo, 'pr-a');
+    const tree = runQueueBin(repo, 'gstack-wtree', []).out.trim();
+    const exception = { lane: LANE, repo: 'o/r', pr: 1, head, tree, runs: ['400/1'], cases: [FLAKE] };
+    const pregate = path.join(repo.root, 'pregate.json');
+    fs.writeFileSync(pregate, JSON.stringify({
+      schema_version: 1, tree, head, verdict: 'pass-with-exception', checks: [{ id: 'lanes', status: 'requires-remote' }],
+      requires_remote: [{ lane: LANE, platform: 'remote', workflow: 'pregate.json', job: 'remote_gate', tests: ['test/a.test.ts'], receipt: `remote-gate tree=${tree.slice(0, 12)} tests=18 exception=a-1 cases=1 runs=400/1 profiles=${PROFILE_NAME} heads=${head.slice(0, 12)} verified=2026-10-29T12:00:00.000Z` }],
+      exceptions: [{ ...exception, grant: 'a-1', by: 'Garry', words: WORDS, binding: exceptionBinding(exception) }],
+    }));
+    const queue = (checks: unknown) => runQueueBin(repo, 'gstack-ship-queue', ['ready', '--pr', '1', '--pregate', pregate, '--base', 'main'], ghQueueShim(repo, { prs: { '1': { headRefOid: head, url: 'https://github.com/o/r/pull/1', body: shippedBody('1', head) } }, checks: { [head]: checks } }));
+    const ok = queue({ check_runs: [{ status: 'completed', conclusion: 'success' }] });
+    expect([ok.status, ok.err]).toEqual([EXIT.ok, '']);
+    expect(ok.out).toMatch(/^PREGATE: pass-with-exception tree=[0-9a-f]{12} /m);
+    expect(ok.out).toContain(`FLAKY_EXCEPTION: ${LANE} cases=${FLAKE} run=400/1 grant=a-1 by=Garry (pregate only; every required CI check still needs its own green run at this head)\n`);
+    const red = queue({ check_runs: [{ status: 'completed', conclusion: 'failure' }] });
+    expect(red.status).toBe(EXIT.refused);
+    expect(red.err).toMatch(/CI is not green at .*\(QUEUE_NOT_READY\)/);
+    const other = { ...exception, pr: 2 };
+    fs.writeFileSync(pregate, JSON.stringify({ ...JSON.parse(fs.readFileSync(pregate, 'utf8')), exceptions: [{ ...other, grant: 'a-1', by: 'Garry', words: WORDS, binding: exceptionBinding(other) }] }));
+    const moved = queue({ check_runs: [{ status: 'completed', conclusion: 'success' }] });
+    expect(moved.status).toBe(EXIT.refused);
+    expect(moved.err).toContain('flaky exception grant a-1 is bound to PR #2');
+  }, 120_000);
+});