@futurelastic/colab-handbook 1.12.0-rc.62 → 1.12.0-rc.64

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/audit/audit.mjs CHANGED
@@ -103,6 +103,8 @@ const shipBatch = require("../tools/lib/ship-batch.js");
103
103
  const migrationPaths = require("../tools/lib/migration-paths.js");
104
104
  // #398: the `migration-grant:` policy key — read through the same module `colab migration-grant` uses.
105
105
  const migrationGrant = require("../tools/lib/migration-grant.js");
106
+ // #504: the `ci-grant:` policy key — read through the same module `colab ci-grant` uses.
107
+ const ciGrantLib = require("../tools/lib/ci-grant.js");
106
108
  // #407: the optional `trust-humans` list — read through the same module every grant reader uses.
107
109
  const trustHumansLib = require("../tools/lib/trust-humans.js");
108
110
  // #403: the `live-env:` key — read through the same module `colab gate-hermetic` uses.
@@ -1332,6 +1334,17 @@ function auditRepo(target, ctx) {
1332
1334
  if (!pol.valid) fail(pol.reason);
1333
1335
  }
1334
1336
 
1337
+ // ---- ci-grant (#504) -------------------------------------------------------
1338
+ // Who may open the red-trunk door when the cure rule refuses: `human` (absent) or `reviewer`, the
1339
+ // coordinator agent minting `colab ci-grant --role ci-reviewer` without COLAB_HUMAN=1.
1340
+ // tools/lib/ci-grant.js parseGrantPolicy is the one reading. Always reported (info.ciGrant); an
1341
+ // invalid value fails, because the reader then falls back to `human` silently.
1342
+ {
1343
+ const pol = ciGrantLib.parseGrantPolicy(cfg);
1344
+ info.ciGrant = pol.policy;
1345
+ if (!pol.valid) fail(pol.reason);
1346
+ }
1347
+
1335
1348
  // ---- trust-humans (#407) --------------------------------------------------
1336
1349
  // Which logins count as HUMAN for a grant or a ruling. Absent = the association class, as
1337
1350
  // before. tools/lib/trust-humans.js parseTrustHumans is the one reading. A malformed value
package/package.json CHANGED
@@ -32,5 +32,5 @@
32
32
  "engines": {
33
33
  "node": ">=18"
34
34
  },
35
- "version": "1.12.0-rc.62"
35
+ "version": "1.12.0-rc.64"
36
36
  }
@@ -45,8 +45,8 @@
45
45
  # The last two bullets fire ONLY when rows exist — on an empty table every one of
46
46
  # them passes on both engines. Set ROUNDTRIP_SEEDER below, or they go unchecked.
47
47
  #
48
- # Not gated on RUN_TESTS: a bad migration is cheapest to fix on the branch that adds
49
- # it, so this runs on every push, not only on main.
48
+ # Not gated on RUN_TESTS: a bad migration is cheapest to fix on the branch that adds or
49
+ # modifies it, so this runs on every push, not only on main.
50
50
 
51
51
  name: CI
52
52
 
@@ -461,14 +461,19 @@ jobs:
461
461
  # Migration round-trip — see the header for what each engine catches.
462
462
  #
463
463
  # 1. migrate from zero (schema snapshot A)
464
- # 2. migrate:rollback the migrations THIS change adds — every down() among them
465
- # runs (all migrations when the change adds none)
464
+ # 2. migrate:rollback back to the OLDEST migration this change adds OR modifies —
465
+ # every down() it touched runs, plus the untouched ones after
466
+ # it (all migrations when the change touches none)
466
467
  # 3. seed only if ROUNDTRIP_SEEDER is set, and only when the change
467
- # adds migrations: rows land at the PRE-change schema
468
- # 4. migrate again — the new migrations land on those rows (snapshot B)
468
+ # touches migrations: rows land at the PRE-change schema
469
+ # 4. migrate again — the touched migrations land on those rows (snapshot B)
469
470
  # 5. compare B must equal A — a down() that does not exactly undo its
470
471
  # up() leaves a schema that differs on the second pass
471
472
  #
473
+ # MODIFIED counts as touched, not only added (#507): a branch that only repairs an
474
+ # existing down() must see that down() run, and a branch that adds one migration and
475
+ # repairs an older one must roll back past the older one, not just the newest step.
476
+ #
472
477
  # Steps 2-4 are the shape of a real deploy: new migrations landing on tables that
473
478
  # already hold rows written before they existed. That is why the seed sits BETWEEN
474
479
  # the rollback and the second migrate — rows seeded after the new migrations would
@@ -533,7 +538,7 @@ jobs:
533
538
  steps:
534
539
  - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
535
540
  with:
536
- # Full history: step 3 counts the migrations this change adds against trunk.
541
+ # Full history: the count step diffs the migrations this change touches against trunk.
537
542
  fetch-depth: 0
538
543
  persist-credentials: false
539
544
 
@@ -580,7 +585,7 @@ jobs:
580
585
  - name: Discover packages
581
586
  run: php artisan package:discover --ansi
582
587
 
583
- - name: Count the migrations this change adds
588
+ - name: Find the migrations this change adds or modifies
584
589
  env:
585
590
  DEFAULT_BRANCH: ${{ github.event.repository.default_branch }}
586
591
  run: |
@@ -597,15 +602,24 @@ jobs:
597
602
  base="$(git rev-parse -q --verify 'HEAD^' || true)"
598
603
  fi
599
604
  fi
600
- steps=0
605
+ # Added, Modified, and Renamed (a rename is a new name to the migrator) — not
606
+ # added only (#507): a branch that only repairs an existing down() got a green
607
+ # round-trip that never ran it.
608
+ touched=""
601
609
  if [ -n "$base" ]; then
602
- steps="$(git diff --name-only --diff-filter=A "$base" HEAD -- "$MIGRATIONS_PATH" | grep -c '\.php$' || true)"
610
+ touched="$(git diff --name-status --diff-filter=AMR "$base" HEAD -- "$MIGRATIONS_PATH" | awk -F'\t' '$NF ~ /\.php$/ { print substr($1,1,1) "\t" $NF }')"
603
611
  fi
604
- echo "ROLLBACK_STEPS=$steps" >> "$GITHUB_ENV"
605
- if [ "$steps" -gt 0 ]; then
606
- echo "This change adds $steps migration(s) (vs ${base_ref}); step 3 rolls back exactly those."
612
+ # The migrator orders by file name, so the oldest touched one is the smallest
613
+ # base name; step 2 rolls back to it and everything after it.
614
+ from="$(printf '%s\n' "$touched" | awk -F'\t' 'NF { n=$2; sub(/.*\//, "", n); sub(/\.php$/, "", n); print n }' | LC_ALL=C sort | head -1)"
615
+ echo "ROUNDTRIP_FROM=$from" >> "$GITHUB_ENV"
616
+ if [ -n "$from" ]; then
617
+ added="$(printf '%s\n' "$touched" | grep -c '^A' || true)"
618
+ modified="$(printf '%s\n' "$touched" | grep -c '^[MR]' || true)"
619
+ echo "This change touches migrations (vs ${base_ref}): $added added, $modified modified. Step 2 rolls back to the oldest, $from, so every down() listed below runs:"
620
+ printf '%s\n' "$touched" | sed 's/^A\t/ added /; s/^[MR]\t/ modified /'
607
621
  else
608
- echo "This change adds no migrations (vs ${base_ref:-nothing}); step 3 rolls back all of them."
622
+ echo "This change adds or modifies no migrations (vs ${base_ref:-nothing}); step 2 rolls back all of them."
609
623
  fi
610
624
 
611
625
  - name: Write the schema snapshot script
@@ -637,6 +651,18 @@ jobs:
637
651
  ksort($out);
638
652
  echo json_encode($out, JSON_PRETTY_PRINT | JSON_UNESCAPED_SLASHES), "\n";
639
653
  PHP
654
+ # How many migrations step 2 must roll back to reach ROUNDTRIP_FROM: the rows of
655
+ # the migrations table at or after it. Read from the table, not by counting
656
+ # files, so migrations a package registers from another path are counted too.
657
+ cat > "$RUNNER_TEMP/rollback-steps.php" <<'PHP'
658
+ <?php
659
+ require getcwd() . '/vendor/autoload.php';
660
+ $app = require getcwd() . '/bootstrap/app.php';
661
+ $app->make(Illuminate\Contracts\Console\Kernel::class)->bootstrap();
662
+ $m = config('database.migrations');
663
+ $table = is_array($m) ? ($m['table'] ?? 'migrations') : ($m ?: 'migrations');
664
+ echo Illuminate\Support\Facades\DB::table($table)->where('migration', '>=', getenv('ROUNDTRIP_FROM'))->count(), "\n";
665
+ PHP
640
666
 
641
667
  - name: 1. migrate from zero
642
668
  run: |
@@ -645,16 +671,22 @@ jobs:
645
671
 
646
672
  - name: 2. roll back
647
673
  run: |
648
- if [ "$ROLLBACK_STEPS" -gt 0 ]; then
649
- php artisan migrate:rollback --step="$ROLLBACK_STEPS" --force
674
+ set -euo pipefail
675
+ steps=0
676
+ if [ -n "$ROUNDTRIP_FROM" ]; then
677
+ steps="$(php "$RUNNER_TEMP/rollback-steps.php")"
678
+ fi
679
+ if [ "$steps" -gt 0 ]; then
680
+ echo "Rolling back $steps migration(s), down to $ROUNDTRIP_FROM."
681
+ php artisan migrate:rollback --step="$steps" --force
650
682
  else
651
683
  # Everything ran in one batch at step 1, so this rolls all of it back.
652
684
  php artisan migrate:rollback --force
653
685
  fi
654
686
 
655
687
  - name: 3. seed rows at the pre-change schema
656
- # No new migrations = nothing lands on the rows, and the schema is empty anyway.
657
- if: env.ROUNDTRIP_SEEDER != '' && env.ROLLBACK_STEPS != '0'
688
+ # No touched migrations = nothing lands on the rows, and the schema is empty anyway.
689
+ if: env.ROUNDTRIP_SEEDER != '' && env.ROUNDTRIP_FROM != ''
658
690
  run: php artisan db:seed --class="$ROUNDTRIP_SEEDER" --force
659
691
 
660
692
  - name: 4. migrate again
package/tools/colab CHANGED
@@ -4348,6 +4348,7 @@ function cmdDecisionList(opts) {
4348
4348
  // ---------------------------------------------------------------------------
4349
4349
 
4350
4350
  const HELP_CI_GRANT = `colab ci-grant <issue> --branch <branch> [--evidence-run <sha-or-url>] [--repo <path>]
4351
+ colab ci-grant <issue> --branch <branch> --role ci-reviewer --reviewer <id> --verdict pass --cures <checks> [--repo <path>]
4351
4352
  colab ci-grant <issue> --revoke [--repo <path>]
4352
4353
  colab ci-grant --list [--json] [--repo <path>]
4353
4354
 
@@ -4386,8 +4387,9 @@ CI grant merges into a repo whose own test suite is known-failing:
4386
4387
  \`ship\` would never consult it for, reading live in \`--list\` while doing nothing.
4387
4388
 
4388
4389
  HUMAN-ONLY, ENFORCED: both grant and revoke REFUSE (exit 1) unless COLAB_HUMAN=1 is set in the
4389
- environment — the identical bar \`colab promote\`/\`colab migration-grant\` already hold. No field,
4390
- flag or project.yml value can lower it. This check runs BEFORE any network call.
4390
+ environment — the identical bar \`colab promote\`/\`colab migration-grant\` already hold. This check
4391
+ runs BEFORE any network call. The ONE exception is the reviewer role below, and only on a repo whose
4392
+ trunk opts in.
4391
4393
 
4392
4394
  The marker is TWO parts, both required for a grant to read as live:
4393
4395
  - the \`${labels.CI_GRANT_LABEL}\` label — applying it requires GitHub write/triage permission, so
@@ -4415,8 +4417,30 @@ Revoking removes the label FIRST (the gate is restored the same minute) and post
4415
4417
  There is deliberately no local-only fallback: without a usable \`gh\`, every subcommand here REFUSES
4416
4418
  rather than write (or read) something invisible to the machine \`ship\` might later run on.
4417
4419
 
4420
+ THE REVIEWER ROLE (#504). On a repo whose TRUNK declares \`ci-grant: reviewer\` in project.yml,
4421
+ --role ${ciGrant.REVIEWER_ROLE} mints a \`${ciGrant.REVIEW_GRANT_MARK}\` WITHOUT COLAB_HUMAN=1 — the coordinator
4422
+ agent's door through a red trunk the cure rule refuses (maintainer ruling 2026-10-05). It is the only
4423
+ path past the human bar above, and only that opt-in opens it; revoking stays human. Every guard is
4424
+ measured, nothing is taken from the flags:
4425
+ - local, before any network call: the opt-in on trunk as committed (a branch cannot opt itself
4426
+ in) · the record is well-formed with --verdict pass and at least one cure · the branch is
4427
+ pushed and --head (if given) is origin's tip · the branch's trailing number group carries #N;
4428
+ - #N is open and its title starts "${ciGrant.TRUNK_RED_TITLE_PREFIX}" · trunk is red in ship's sense ·
4429
+ never stacks (guard 2 above) · the branch's own CI is green at that EXACT head · every
4430
+ check in --cures is red on trunk at the red sha.
4431
+ The comment carries a fenced \`ci-review\` record (verdict, head, red sha, cures) and binds that
4432
+ HEAD and that red sha: a new commit on either voids it. \`colab ship\` re-measures all of it, reads
4433
+ the opt-in at the merge target, and reads a grant with \`not-before\` in the future as not yet usable.
4434
+
4418
4435
  Options:
4419
4436
  --branch <branch> required for a grant; never inferred from HEAD
4437
+ --role <role> human (default) | ${ciGrant.REVIEWER_ROLE}
4438
+ --reviewer <id> (reviewer) the reviewer's declared identity (letters, digits, . _ @ -)
4439
+ --verdict <v> (reviewer) pass | fail — only pass is minted
4440
+ --cures <checks> (reviewer) the red checks the branch cures, "workflow / job; …"
4441
+ --head <sha> (reviewer) optional; must equal the pushed branch tip
4442
+ --not-before <iso> (reviewer) optional; a revoke window the host imposes
4443
+ --ci-run <id-or-url> (reviewer) optional; recorded only
4420
4444
  --evidence-run <ref> recording-only note for the audit trail — never substitutes for the
4421
4445
  measured branch-head run this command itself checks
4422
4446
  --revoke revoke instead of grant
@@ -4473,7 +4497,12 @@ function computeAntiStacking(repoAbs, trunk, trunkIsRed) {
4473
4497
 
4474
4498
  function cmdCiGrant(argv) {
4475
4499
  const opts = parseArgs(argv, {
4476
- values: { '--repo': 'repo', '--branch': 'branch', '--evidence-run': 'evidenceRun' },
4500
+ values: {
4501
+ '--repo': 'repo', '--branch': 'branch', '--evidence-run': 'evidenceRun',
4502
+ // #504 reviewer-grant record flags
4503
+ '--role': 'role', '--reviewer': 'reviewer', '--verdict': 'verdict', '--cures': 'cures',
4504
+ '--head': 'head', '--not-before': 'notBefore', '--ci-run': 'ciRun',
4505
+ },
4477
4506
  flags: { '--revoke': 'revoke', '--list': 'list', '--json': 'json', '-h': 'help', '--help': 'help' },
4478
4507
  });
4479
4508
  if (opts.help) return print(HELP_CI_GRANT);
@@ -4481,11 +4510,27 @@ function cmdCiGrant(argv) {
4481
4510
  if (opts._.length === 0) return print(HELP_CI_GRANT);
4482
4511
  const num = normIssueNum(opts._[0]);
4483
4512
 
4513
+ // #504: the reviewer role is the ONE path past the human bar below, and only on a repo whose
4514
+ // TRUNK declares `ci-grant: reviewer`. Decided from local git alone, before any network call.
4515
+ const role = opts.role === undefined ? 'human' : String(opts.role);
4516
+ if (!ciGrant.GRANT_ROLES.includes(role)) {
4517
+ throw new UserError(`--role is "${role}", expected ${ciGrant.GRANT_ROLES.join(' | ')}`);
4518
+ }
4519
+ if (opts.revoke && opts.role !== undefined) {
4520
+ throw new UserError('--revoke takes no --role — a revoke cancels every live grant on the issue, whatever its role');
4521
+ }
4522
+ if (role === ciGrant.REVIEWER_ROLE && !opts.revoke) return cmdCiGrantReviewer(num, opts);
4523
+ const stray = ['reviewer', 'verdict', 'cures', 'head', 'notBefore', 'ciRun'].filter((k) => opts[k] !== undefined);
4524
+ if (stray.length) {
4525
+ throw new UserError(`review-record flags (${stray.map((k) => '--' + k.replace(/[A-Z]/g, (c) => '-' + c.toLowerCase())).join(', ')}) need --role ${ciGrant.REVIEWER_ROLE} — a human grant carries no record`);
4526
+ }
4527
+
4484
4528
  // HUMAN-ONLY, first — identical posture and identical reason to cmdMigrationGrant's check above:
4485
4529
  // assertable by a test against a fixture with no `gh` at all (tools/lib/ship-ci-grant.test.js).
4486
4530
  if (process.env.COLAB_HUMAN !== '1') {
4487
4531
  process.stderr.write(`✗ Refusing: ${opts.revoke ? 'revoking' : 'creating'} a CI grant requires a human.\n`);
4488
4532
  process.stderr.write(' Re-run with COLAB_HUMAN=1. (No field, flag or project.yml value can lower this bar.)\n');
4533
+ if (!opts.revoke) process.stderr.write(` The ${ciGrant.REVIEWER_ROLE} role is a different grant, open only where trunk declares ci-grant: reviewer — colab ci-grant --help.\n`);
4489
4534
  return 1;
4490
4535
  }
4491
4536
 
@@ -4509,6 +4554,121 @@ function cmdCiGrant(argv) {
4509
4554
  return opts.revoke ? cmdCiGrantRevoke(repoAbs, num) : cmdCiGrantCreate(repoAbs, num, opts);
4510
4555
  }
4511
4556
 
4557
+ /**
4558
+ * #504: `colab ci-grant <N> --role ci-reviewer` — the coordinator agent's door through a red trunk the
4559
+ * cure rule refuses. Needs no COLAB_HUMAN=1, and that is the whole point; what replaces the human is
4560
+ * the opt-in on trunk plus guards that are all MEASURED here, never taken from the flags:
4561
+ * local (before any network call): `ci-grant: reviewer` committed on trunk · the record is
4562
+ * well-formed with verdict pass and at least one cure · the branch is pushed and --head (if
4563
+ * given) is its remote tip · the branch name's trailing number group carries #N;
4564
+ * tracker/CI: #N is open and titled `TRUNK RED:` · trunk is red in the sense ship checks · never
4565
+ * stacks (computeAntiStacking, same as the human grant) · the branch's own CI is green at that
4566
+ * EXACT head · every claimed cure is a red check on trunk at the red sha.
4567
+ * Nothing is written until all of them pass.
4568
+ */
4569
+ function cmdCiGrantReviewer(num, opts) {
4570
+ const repoAbs = resolveRepoOrCwd(opts);
4571
+ if (!repoAbs) throw new UserError('not inside a git repo — pass --repo <path>');
4572
+ if (!opts.branch) {
4573
+ throw new UserError('--branch <branch> is required — a grant is bound to one branch, never inferred from the current checkout');
4574
+ }
4575
+ const trunk = resolveTrunk(repoAbs, projectDoc(repoAbs));
4576
+ if (!trunk) throw new UserError('Could not determine trunk branch (set project.yml trunk:)');
4577
+
4578
+ // The opt-in, read from TRUNK as committed — never this checkout or the branch, so a branch cannot
4579
+ // grant itself the policy it would then use.
4580
+ const pol = ciGrant.parseGrantPolicy(projectDocAt(repoAbs, trunk));
4581
+ if (!pol.valid) throw new UserError(`${pol.reason} — fix project.yml on ${trunk} before minting a reviewer grant`);
4582
+ if (pol.policy !== 'reviewer') {
4583
+ process.stderr.write(`✗ Refusing: ${trunk}'s project.yml says ci-grant: ${pol.policy}${pol.declared ? '' : ' (absent = human)'} — a ${ciGrant.REVIEWER_ROLE} grant is minted only where trunk declares ci-grant: reviewer.\n`);
4584
+ process.stderr.write(' Without that opt-in a CI grant is human-only: COLAB_HUMAN=1 colab ci-grant <N> --branch <b>.\n');
4585
+ return 1;
4586
+ }
4587
+
4588
+ if (!branchName.branchIssueNumbers(opts.branch).includes(num)) {
4589
+ throw new UserError(`branch "${opts.branch}" does not carry #${num} in its trailing number group — a reviewer grant needs the branch to close the TRUNK RED issue it is posted on`);
4590
+ }
4591
+ const refs = git.branchRefs(repoAbs, opts.branch);
4592
+ if (!refs.remoteSha) {
4593
+ throw new UserError(`branch "${opts.branch}" is not on origin — a reviewer grant binds the pushed HEAD, so push it first`);
4594
+ }
4595
+ const head = refs.remoteSha.toLowerCase();
4596
+ if (opts.head !== undefined && String(opts.head).toLowerCase() !== head) {
4597
+ throw new UserError(`--head ${String(opts.head).slice(0, 12)} is not origin's tip of "${opts.branch}" (${head.slice(0, 12)}) — the review covers a commit the grant would not bind; re-review the tip`);
4598
+ }
4599
+ const rec = {
4600
+ v: '1', role: ciGrant.REVIEWER_ROLE, reviewer: opts.reviewer, head, red: '0'.repeat(40),
4601
+ verdict: opts.verdict, cures: opts.cures === undefined ? undefined : ciGrant.formatCures(ciGrant.parseCures(opts.cures)),
4602
+ 'not-before': opts.notBefore, 'ci-run': opts.ciRun,
4603
+ };
4604
+ for (const k of Object.keys(rec)) if (rec[k] === undefined || rec[k] === '') delete rec[k];
4605
+ const v0 = ciGrant.validateReviewRecord(rec);
4606
+ if (!v0.valid) throw new UserError(`the review record is invalid: ${v0.problems.join('; ')}`);
4607
+ if (!v0.passing) throw new UserError(`the review says verdict ${rec.verdict} — a grant carrying a failing review is a contradiction; nothing was posted`);
4608
+
4609
+ if (!isGhUsable(repoAbs)) {
4610
+ throw new UserError(`gh not usable here (${ghUnusableWhy(repoAbs)}) — a CI grant lives on the tracker, visible from any machine to the gate that reads it, and there is deliberately no local-only fallback`);
4611
+ }
4612
+
4613
+ const info = git.ghIssueView(repoAbs, num, ['state', 'labels', 'title']);
4614
+ if (!info) throw new UserError(`could not read #${num} from the tracker — refusing to write a grant blind`);
4615
+ if (info.state !== 'OPEN') throw new UserError(`#${num} is ${info.state} — a grant expires the instant its issue closes`);
4616
+ if (!ciGrant.titleIsTrunkRed(info.title)) {
4617
+ throw new UserError(`#${num}'s title does not start "${ciGrant.TRUNK_RED_TITLE_PREFIX}" — a reviewer CI grant covers only work that is the red trunk's repair`);
4618
+ }
4619
+ const present = git.ghListLabels(repoAbs);
4620
+ if (present && !present.includes(labels.CI_GRANT_LABEL)) {
4621
+ throw new UserError(labels.ciGrantMissingLabelHint(present) || `this repo has no \`${labels.CI_GRANT_LABEL}\` label`);
4622
+ }
4623
+
4624
+ // Trunk red, in ship's sense — the identical classification cmdCiGrantCreate uses (#155).
4625
+ git.git(['fetch', git.remoteFor(repoAbs), trunk], repoAbs);
4626
+ const trunkRun = git.ghRunForSha(repoAbs, trunk);
4627
+ if (!trunkRun) throw new UserError(`could not read ${trunk}'s CI status (gh run list failed) — refusing to grant blind`);
4628
+ const trunkVerdict = classifyCiRun(repoAbs, trunkRun, `${trunk}@${shortSha(trunkRun.sha)}`);
4629
+ if (trunkVerdict.class !== HUMAN_GATED) {
4630
+ throw new UserError(`${trunk} is not red in the sense \`ship\` checks — ${trunkVerdict.detail || 'green'}. Nothing for a grant to exempt.`);
4631
+ }
4632
+ const redSha = trunkRun.sha;
4633
+ const stacking = computeAntiStacking(repoAbs, trunk, true);
4634
+ if (!stacking.ok) throw new UserError(stacking.reason);
4635
+
4636
+ // The branch's own CI, green at the EXACT head the review covers.
4637
+ const evRun = git.ghRunForSha(repoAbs, opts.branch);
4638
+ if (!evRun) throw new UserError(`could not read "${opts.branch}"'s CI status (gh run list failed) — refusing to grant blind`);
4639
+ if (String(evRun.sha || '').toLowerCase() !== head) {
4640
+ throw new UserError(`"${opts.branch}"'s newest CI run is for ${shortSha(evRun.sha)}, not the reviewed head ${shortSha(head)} — wait for CI on the head, then re-run`);
4641
+ }
4642
+ if (!(evRun.status === 'completed' && evRun.conclusion === 'success')) {
4643
+ throw new UserError(`"${opts.branch}" has no completed, successful CI run at ${shortSha(head)} (status=${evRun.status} conclusion=${evRun.conclusion || 'none'}) — a reviewer grant needs the branch green at its exact head`);
4644
+ }
4645
+
4646
+ // Every claimed cure is a red check on trunk at the red sha.
4647
+ const redRunJobs = trunkRedRunJobs(repoAbs, trunk, redSha);
4648
+ const redJobs = redRunJobs === null ? null : ciCure.redJobSet(redRunJobs);
4649
+ const cr = ciGrant.curesAreRed(ciGrant.parseCures(rec.cures), redJobs);
4650
+ if (!cr.ok) throw new UserError(`${cr.reason}; nothing was posted`);
4651
+
4652
+ rec.red = redSha.toLowerCase();
4653
+ const v = ciGrant.validateReviewRecord(rec);
4654
+ if (!v.passing) throw new UserError(`the review record is invalid: ${v.problems.join('; ')}`);
4655
+
4656
+ const editR = git.ghIssueEdit(repoAbs, num, labels.ciGrantLabelArgs({}));
4657
+ if (!editR.ok) throw new UserError(`gh edit #${num} failed (${editR.stderr.split('\n')[0] || editR.code})`);
4658
+ const commentR = git.ghIssueComment(repoAbs, num,
4659
+ ciGrant.reviewGrantCommentBody(opts.branch, trunk, commentHost(repoAbs), nowISO(), rec));
4660
+ if (!commentR.ok) {
4661
+ git.ghIssueEdit(repoAbs, num, labels.ciGrantLabelArgs({ clear: true }));
4662
+ throw new UserError(`label applied but the grant comment failed to post (${commentR.stderr.split('\n')[0] || commentR.code}) — rolled the label back so this does not read as granted. Re-run.`);
4663
+ }
4664
+
4665
+ print(`Recorded a ${ciGrant.REVIEWER_ROLE} CI grant on #${num} in ${shortRepo(repoAbs)} — reviewer "${rec.reviewer}", branch "${opts.branch}" @ ${head.slice(0, 12)}.`);
4666
+ print(` Bound to that HEAD and to red ${trunk}@${shortSha(redSha)}: a new commit on either voids it. Cures: ${rec.cures}.`);
4667
+ if (rec['not-before']) print(` Not usable before ${rec['not-before']} (revoke window).`);
4668
+ print(` Revoke any time: COLAB_HUMAN=1 colab ci-grant ${num} --revoke`);
4669
+ return 0;
4670
+ }
4671
+
4512
4672
  function cmdCiGrantCreate(repoAbs, num, opts) {
4513
4673
  if (!opts.branch) {
4514
4674
  throw new UserError('--branch <branch> is required — a grant is bound to one branch, never inferred from the current checkout');
@@ -4589,7 +4749,8 @@ function cmdCiGrantRevoke(repoAbs, num) {
4589
4749
  if (!info) throw new UserError(`could not read #${num} from the tracker`);
4590
4750
  const labelNames = (info.labels || []).map((l) => (l && typeof l === 'object' ? l.name : l));
4591
4751
  const hasLabel = labelNames.includes(labels.CI_GRANT_LABEL);
4592
- const live = ciGrant.liveGrants(info.comments);
4752
+ // Every role (#504): a revoke cancels reviewer grants too, so a reviewer-only issue is not "nothing to revoke".
4753
+ const live = ciGrant.liveGrantRecords(info.comments);
4593
4754
 
4594
4755
  if (!hasLabel && live.length === 0) {
4595
4756
  print(`No live CI grant on #${num} in ${shortRepo(repoAbs)} — nothing to revoke.`);
@@ -4635,14 +4796,15 @@ function cmdCiGrantList(opts) {
4635
4796
  const stale = [];
4636
4797
  for (const h of hits) {
4637
4798
  const info = git.ghIssueView(repoAbs, h.number, ['state', 'labels', 'comments']);
4638
- const live = info ? ciGrant.liveGrants(info.comments) : [];
4799
+ const live = info ? ciGrant.liveGrantRecords(info.comments) : [];
4639
4800
  if (live.length === 0) { stale.push(h.number); continue; }
4640
4801
  const g = live[live.length - 1];
4641
4802
  // Spent: the normal post-ship state — trunk's head has moved past the sha this grant named.
4642
4803
  // Not an error, just informative — distinguishes "still live, awaiting a ship" from "already
4643
4804
  // used (or overtaken by an unrelated trunk change) and inert" without anyone revoking it.
4644
4805
  const spent = currentTrunkSha !== null && g.redSha !== currentTrunkSha;
4645
- grants.push({ issue: h.number, title: h.title, branch: g.branch, redSha: g.redSha, evidenceSha: g.evidenceSha, by: g.login, authorAssociation: g.authorAssociation, at: g.at, spent });
4806
+ const reviewer = g.role !== 'human' ? { role: g.role, reviewer: g.reviewer, head: g.head } : {};
4807
+ grants.push({ issue: h.number, title: h.title, branch: g.branch, redSha: g.redSha, evidenceSha: g.role === 'human' ? g.evidenceSha : g.head, by: g.login, authorAssociation: g.authorAssociation, at: g.at, spent, ...reviewer });
4646
4808
  }
4647
4809
 
4648
4810
  if (opts.json) {
@@ -4654,7 +4816,7 @@ function cmdCiGrantList(opts) {
4654
4816
  return 0;
4655
4817
  }
4656
4818
  print(table(
4657
- grants.map((g) => [String(g.issue), g.branch, shortSha(g.redSha), g.spent ? 'spent' : 'live', g.by || '(unknown)', g.title]),
4819
+ grants.map((g) => [String(g.issue), g.branch, shortSha(g.redSha), g.spent ? 'spent' : 'live', (g.by || '(unknown)') + (g.role ? ` (${g.role} ${g.reviewer})` : ''), g.title]),
4658
4820
  ['ISSUE', 'BRANCH', 'RED SHA', 'STATE', 'GRANTED BY', 'TITLE'],
4659
4821
  ));
4660
4822
  if (stale.length) {
@@ -9643,7 +9805,11 @@ function ciGrantTrailerLine(grantVerdict, branch, trunk) {
9643
9805
  if (!grantVerdict || !grantVerdict.ok || !grantVerdict.granted.length) return null;
9644
9806
  const g = grantVerdict.granted[0]; // redSha/evidenceSha are identical across the whole granted set (evaluateShipSet)
9645
9807
  const issues = grantVerdict.granted.map((x) => '#' + x.issue).join(' ');
9646
- return `CI-Grant: ${issues} branch ${branch} over-red ${trunk}@${shortSha(g.redSha)} evidence ${shortSha(g.evidenceSha)}`;
9808
+ // #504: a reviewer grant appends who reviewed it; the `over-red <trunk>@<sha>` part the anti-stacking
9809
+ // scan (ci-cure.js priorRedShaFromMessage) reads is unchanged.
9810
+ const rv = grantVerdict.granted.filter((x) => x.role && x.role !== 'human');
9811
+ const via = rv.length ? ` via ${rv[0].role} ${[...new Set(rv.map((x) => x.reviewer))].join(',')}` : '';
9812
+ return `CI-Grant: ${issues} branch ${branch} over-red ${trunk}@${shortSha(g.redSha)} evidence ${shortSha(g.evidenceSha)}${via}`;
9647
9813
  }
9648
9814
 
9649
9815
  /**
@@ -10747,9 +10913,14 @@ function applyRedTrunkExemptions(raw, target, trunk, redSha, grantThunk, cureThu
10747
10913
  const grantVerdict = grantThunk ? grantThunk(redSha) : null;
10748
10914
  if (grantVerdict && grantVerdict.ok) {
10749
10915
  const by = grantVerdict.granted.map((g) => '#' + g.issue).join(' ');
10916
+ // #504: a reviewer grant says so — it must never render as a human's decision.
10917
+ const rv = grantVerdict.granted.filter((g) => g.role && g.role !== 'human');
10918
+ const who = rv.length
10919
+ ? `a ${rv[0].role} ci-grant (reviewer ${[...new Set(rv.map((g) => g.reviewer))].join(', ')}, cures ${[...new Set(rv.flatMap((g) => g.cures || []))].join('; ')})`
10920
+ : 'a human ci-grant';
10750
10921
  return {
10751
10922
  name: raw.name, ok: true, class: null,
10752
- detail: `PRECONDITION OVERRIDDEN by a human ci-grant on ${by} — trunk was red at ${shortSha(redSha)} (raw: ${raw.detail})`,
10923
+ detail: `PRECONDITION OVERRIDDEN by ${who} on ${by} — trunk was red at ${shortSha(redSha)} (raw: ${raw.detail})`,
10753
10924
  grantVerdict, cureVerdict,
10754
10925
  };
10755
10926
  }
@@ -10772,12 +10943,21 @@ function shipCiGrants(repoAbs, gh, issues, branch, trunk, redSha) {
10772
10943
  missing: [{ issue: null, reason: `gh not usable (${ghUnusableWhy(repoAbs)}) — a CI grant lives on the tracker and cannot be confirmed` }] };
10773
10944
  }
10774
10945
  const records = {};
10775
- for (const n of issues) records[n] = git.ghIssueView(repoAbs, n, ['state', 'labels', 'comments']);
10946
+ // `title` (#504): a reviewer grant requires its issue to be titled `TRUNK RED:`.
10947
+ for (const n of issues) records[n] = git.ghIssueView(repoAbs, n, ['state', 'labels', 'comments', 'title']);
10776
10948
  const evRun = git.ghRunForSha(repoAbs, branch);
10777
10949
  const evidence = !evRun ? null : { ok: evRun.status === 'completed' && evRun.conclusion === 'success', sha: evRun.sha };
10778
10950
  return ciGrant.evaluateShipSet(issues, records, branch, trunk, redSha, evidence, labels.CI_GRANT_LABEL, {
10779
10951
  trust: trustAt(repoAbs, trunk),
10780
10952
  labelActors: (n) => git.ghIssueLabelActors(repoAbs, n, labels.CI_GRANT_LABEL),
10953
+ // #504 — the reviewer role: the opt-in as committed on TRUNK (never the branch), the clock for a
10954
+ // host's revoke window, and trunk's red checks at redSha, read lazily and at most once.
10955
+ policy: ciGrant.parseGrantPolicy(projectDocAt(repoAbs, trunk)).policy,
10956
+ now: Date.now(),
10957
+ redJobs: () => {
10958
+ const jobs = trunkRedRunJobs(repoAbs, trunk, redSha);
10959
+ return jobs === null ? null : ciCure.redJobSet(jobs);
10960
+ },
10781
10961
  });
10782
10962
  }
10783
10963
 
@@ -10792,7 +10972,8 @@ function ciGrantPayload(ciResult) {
10792
10972
  const g = ciResult.grantVerdict;
10793
10973
  return {
10794
10974
  ok: g.ok,
10795
- granted: g.granted.map((x) => ({ issue: x.issue, by: x.by, at: x.at, redSha: x.redSha, evidenceSha: x.evidenceSha })),
10975
+ granted: g.granted.map((x) => ({ issue: x.issue, by: x.by, at: x.at, redSha: x.redSha, evidenceSha: x.evidenceSha,
10976
+ ...(x.role ? { role: x.role, reviewer: x.reviewer, head: x.head, cures: x.cures } : {}) })),
10796
10977
  missing: g.missing.map((m) => ({ issue: m.issue, reason: m.reason })),
10797
10978
  };
10798
10979
  }
@@ -14692,7 +14873,7 @@ Commands:
14692
14873
  migration-grant <issue> --branch B | --revoke | --list [--json] human-only ship migration exemption (#98)
14693
14874
  decision <issue> --record --ruled-by N | --reopen --ruled-by N | --list [--json]
14694
14875
  record/reopen a needs-decision answer (#121, #122)
14695
- ci-grant <issue> --branch B | --revoke | --list [--json] human-only ship trunk-CI-green exemption (#105)
14876
+ ci-grant <issue> --branch B | --revoke | --list [--json] ship trunk-CI-green exemption: human, or ci-reviewer under opt-in (#105, #504)
14696
14877
  claims [--json] [--sync] list / reconcile with GitHub
14697
14878
 
14698
14879
  port alloc [--count N] [--range A-B] [--worktree N|--claim I|--label S]
@@ -230,6 +230,11 @@ function evaluateIssue(record, branch, trunk, redTrunkSha, evidence, issueNum, l
230
230
  *
231
231
  * `records` maps issue number → the `ghIssueView` result for that issue, or `null` on a failed
232
232
  * read (the caller's job, not this function's).
233
+ *
234
+ * `opts` (#504) additionally carries `{ policy, now, redJobs }` for the reviewer role: per issue a
235
+ * live human grant wins, unchanged; otherwise an issue carrying a live reviewer grant is judged by
236
+ * evaluateReviewerIssue (records must then include `title`). `redJobs` is a thunk, called at most
237
+ * once per set. A granted reviewer entry carries `role: 'ci-reviewer'`, `reviewer`, `head`, `cures`.
233
238
  */
234
239
  function evaluateShipSet(issues, records, branch, trunk, redTrunkSha, evidence, labelName, opts) {
235
240
  const list = Array.isArray(issues) ? issues : [];
@@ -239,10 +244,35 @@ function evaluateShipSet(issues, records, branch, trunk, redTrunkSha, evidence,
239
244
  }
240
245
  const granted = [];
241
246
  const missing = [];
247
+ // #504: the red-job set is read at most once per set, and only by an issue whose reviewer grant
248
+ // has cleared every cheaper check.
249
+ let redJobsMemo;
250
+ const redJobs = () => {
251
+ if (redJobsMemo === undefined) {
252
+ try { redJobsMemo = opts && typeof opts.redJobs === 'function' ? opts.redJobs() : null; } catch (_) { redJobsMemo = null; }
253
+ }
254
+ return redJobsMemo;
255
+ };
242
256
  for (const n of list) {
243
- const v = evaluateIssue(records ? records[n] : null, branch, trunk, redTrunkSha, evidence, n, labelName, opts);
244
- if (v.ok) granted.push({ issue: n, branch: v.grant.branch, by: v.grant.login, at: v.grant.at, redSha: v.grant.redSha, evidenceSha: v.grant.evidenceSha });
245
- else missing.push({ issue: n, reason: v.reason });
257
+ const rec = records ? records[n] : null;
258
+ const v = evaluateIssue(rec, branch, trunk, redTrunkSha, evidence, n, labelName, opts);
259
+ if (v.ok) {
260
+ granted.push({ issue: n, branch: v.grant.branch, by: v.grant.login, at: v.grant.at, redSha: v.grant.redSha, evidenceSha: v.grant.evidenceSha });
261
+ continue;
262
+ }
263
+ // #504: a reviewer grant is consulted only when the human one failed AND the issue carries a
264
+ // live reviewer marker — so an issue with none keeps the human reason byte for byte.
265
+ const hasReviewer = !!rec && liveGrantRecords(rec.comments).some((g) => g.role !== 'human');
266
+ if (!hasReviewer) { missing.push({ issue: n, reason: v.reason }); continue; }
267
+ const r = evaluateReviewerIssue(rec, { branch, trunk, redTrunkSha, evidence, issueNum: n, labelName,
268
+ policy: opts && opts.policy, now: opts && opts.now, redJobs });
269
+ if (r.ok) {
270
+ granted.push({ issue: n, role: REVIEWER_ROLE, reviewer: r.grant.reviewer, head: r.grant.head,
271
+ branch: r.grant.branch, by: r.grant.login, at: r.grant.at, redSha: r.grant.redSha, evidenceSha: r.grant.head,
272
+ cures: parseCures(r.grant.record.cures) });
273
+ } else {
274
+ missing.push({ issue: n, reason: `reviewer grant: ${r.reason}` });
275
+ }
246
276
  }
247
277
  return { ok: missing.length === 0, granted, missing };
248
278
  }
@@ -297,9 +327,248 @@ function stackingVerdict({ trunkIsRed, priorGrantMerge, redContinuousSincePriorG
297
327
  return { ok: true, reason: '' };
298
328
  }
299
329
 
330
+ // ============================================================================================
331
+ // THE REVIEWER ROLE (#504) — `colab ci-grant <N> --role ci-reviewer`.
332
+ //
333
+ // Maintainer ruling 2026-10-05: the coordinator agent owns a red trunk end to end, including this
334
+ // exemption, where the cure rule (tools/lib/ci-cure.js) still refuses. Mirrors the reviewer
335
+ // migration grant (#397, #401): a declared reviewer, a review record, bound to ONE HEAD — and, like
336
+ // every CI grant, to ONE red trunk sha. Unlike the migration reviewer it is minted WITHOUT
337
+ // COLAB_HUMAN=1, and only because the repo opted in on trunk (`ci-grant: reviewer`). Everything it
338
+ // relies on is MEASURED by the reader, never taken from the record:
339
+ // - the issue is open, labelled, and titled `TRUNK RED:` (the work is the red trunk's repair);
340
+ // - trunk is still at the red sha the review names;
341
+ // - the branch's own CI is green at the exact HEAD the review names;
342
+ // - every check the record claims to cure is red on trunk at that sha;
343
+ // - a host-imposed revoke window (`not-before`) has passed.
344
+ // Never-stacks is a MINT-time guard (stackingVerdict, as for the human grant): once any exemption
345
+ // merges, trunk's head moves, and a grant bound to the old red sha is dead.
346
+ //
347
+ // THE REVIEWER IDENTITY IS DECLARED, NOT ATTESTED — same caveat as the migration reviewer. The
348
+ // anti-forgery properties are the label (write/triage permission) and TRUSTED_ASSOCIATIONS on read.
349
+ // ============================================================================================
350
+
351
+ const REVIEW_GRANT_MARK = codec.CI_REVIEW_GRANT_MARK;
352
+ const REVIEW_GRANT_RE = codec.CI_REVIEW_GRANT_RE;
353
+ const REVIEWER_ROLE = codec.CI_REVIEWER_ROLE;
354
+ const GRANT_ROLES = Object.freeze(['human', REVIEWER_ROLE]);
355
+ const REVIEW_RECORD_FIELDS = codec.CI_REVIEW_RECORD_FIELDS;
356
+ const REVIEW_RECORD_KEYS = new Set(REVIEW_RECORD_FIELDS.map((f) => f.key));
357
+ /** The issue-title prefix a reviewer grant requires: the branch's work IS the red trunk's repair. */
358
+ const TRUNK_RED_TITLE_PREFIX = 'TRUNK RED:';
359
+ /** `ci-grant:` values in project.yml (#504). Absent = human, the behaviour before #504. */
360
+ const GRANT_POLICIES = Object.freeze(['human', 'reviewer']);
361
+
362
+ /**
363
+ * `ci-grant:` from a parsed project.yml → { policy, declared, valid, reason }. Same shape and the same
364
+ * fail-safe posture as migration-grant.js's parseGrantPolicy: an invalid value reads as `human` (the
365
+ * stricter reading) with `valid: false`, so the audit fails it.
366
+ */
367
+ function parseGrantPolicy(doc) {
368
+ const has = !!doc && Object.prototype.hasOwnProperty.call(doc, 'ci-grant');
369
+ const raw = has ? doc['ci-grant'] : undefined;
370
+ if (!has || raw === null || raw === undefined) {
371
+ return { policy: 'human', declared: false, valid: true, reason: 'ci-grant absent — human grants only' };
372
+ }
373
+ const v = typeof raw === 'string' ? raw.trim() : raw;
374
+ if (typeof v === 'string' && GRANT_POLICIES.includes(v)) {
375
+ return { policy: v, declared: true, valid: true, reason: `ci-grant: ${v}` };
376
+ }
377
+ return { policy: 'human', declared: true, valid: false,
378
+ reason: `ci-grant is ${JSON.stringify(raw)}, expected ${GRANT_POLICIES.join(' | ')} (omit for human)` };
379
+ }
380
+
381
+ /** The `cures:` value → a list of check names, trimmed, empties dropped. */
382
+ function parseCures(value) {
383
+ return String(value == null ? '' : value).split(codec.CI_CURES_SEPARATOR).map((x) => x.trim()).filter(Boolean);
384
+ }
385
+
386
+ /** A list of check names → the `cures:` value. */
387
+ function formatCures(list) {
388
+ return (Array.isArray(list) ? list : []).map((x) => String(x).trim()).filter(Boolean).join(`${codec.CI_CURES_SEPARATOR} `);
389
+ }
390
+
391
+ /**
392
+ * Validate a `ci-review` record — from a parsed comment or from CLI flags, the SAME function for
393
+ * both. `marker` (optional) is the parsed first line; given, its head/reviewer/red/role must agree
394
+ * with the record. Returns { valid, passing, problems }; PASSING = valid AND `verdict: pass`.
395
+ */
396
+ function validateReviewRecord(rec, marker) {
397
+ const problems = [];
398
+ const r = rec && typeof rec === 'object' ? rec : {};
399
+ for (const k of Object.keys(r)) {
400
+ if (!REVIEW_RECORD_KEYS.has(k)) problems.push(`unknown key "${k}" — a v${codec.CI_REVIEW_RECORD_VERSION} ci-review record has no such field`);
401
+ }
402
+ for (const f of REVIEW_RECORD_FIELDS) {
403
+ const has = Object.prototype.hasOwnProperty.call(r, f.key) && r[f.key] !== undefined && r[f.key] !== null && String(r[f.key]) !== '';
404
+ if (!has) {
405
+ if (f.required) problems.push(`missing "${f.key}"`);
406
+ continue;
407
+ }
408
+ const v = String(r[f.key]);
409
+ if (f.values && !f.values.includes(v)) problems.push(`"${f.key}" is ${JSON.stringify(v)}, expected ${f.values.join(' | ')}`);
410
+ if (f.re && !f.re.test(v)) problems.push(`"${f.key}" is ${JSON.stringify(v)}, expected ${f.hint}`);
411
+ }
412
+ if (r['not-before'] && Number.isNaN(Date.parse(r['not-before']))) problems.push(`"not-before" is ${JSON.stringify(r['not-before'])}, not a parseable instant`);
413
+ if (marker) {
414
+ if (r.head && marker.head !== r.head) problems.push(`record head ${String(r.head).slice(0, 7)} differs from the marker's head ${String(marker.head).slice(0, 7)}`);
415
+ if (r.red && marker.redSha !== r.red) problems.push(`record red ${String(r.red).slice(0, 7)} differs from the marker's red ${String(marker.redSha).slice(0, 7)}`);
416
+ if (r.reviewer && marker.reviewer !== r.reviewer) problems.push(`record reviewer "${r.reviewer}" differs from the marker's reviewer "${marker.reviewer}"`);
417
+ if (marker.role !== REVIEWER_ROLE) problems.push(`marker role is "${marker.role}", expected "${REVIEWER_ROLE}"`);
418
+ }
419
+ const valid = problems.length === 0;
420
+ return { valid, passing: valid && r.verdict === 'pass', problems };
421
+ }
422
+
423
+ /** The exact reviewer-grant comment body. Only v1 fields are written. The caller validates `rec`
424
+ * (validateReviewRecord) BEFORE calling this. */
425
+ function reviewGrantCommentBody(branch, trunk, host, iso, rec) {
426
+ const record = {};
427
+ for (const f of REVIEW_RECORD_FIELDS) if (Object.prototype.hasOwnProperty.call(rec, f.key)) record[f.key] = rec[f.key];
428
+ return codec.encodeCiReviewGrant({ role: rec.role, reviewer: rec.reviewer, branch, head: rec.head,
429
+ trunk, redSha: rec.red, host, at: iso, record });
430
+ }
431
+
432
+ /** A reviewer-grant comment → { marker, record, problems } or null. Syntax from the codec, values
433
+ * from validateReviewRecord. */
434
+ function parseReviewGrant(body) {
435
+ const d = codec.decodeCiReviewGrant(body);
436
+ if (!d) return null;
437
+ const marker = { role: d.role, reviewer: d.reviewer, branch: d.branch, head: d.head, trunk: d.trunk,
438
+ redSha: d.redSha, host: d.host, at: d.at };
439
+ if (!d.record) return { marker, record: null, problems: d.problems };
440
+ const v = validateReviewRecord(d.record, marker);
441
+ return { marker, record: d.record, problems: [...d.problems, ...v.problems] };
442
+ }
443
+
444
+ /**
445
+ * Every live grant of EVERY role — human ones as liveGrants() reads them, plus reviewer grants —
446
+ * after the same revoke rule (a revoke cancels every earlier grant, whichever role, whoever posted
447
+ * it). Oldest-first. Human entries carry role 'human' and liveGrants()'s fields; reviewer entries
448
+ * carry { role, reviewer, branch, head, trunk, redSha, record, problems, valid, passing }.
449
+ */
450
+ function liveGrantRecords(comments) {
451
+ const list = Array.isArray(comments) ? comments : [];
452
+ const sorted = [...list].sort((a, b) => (a.createdAt < b.createdAt ? -1 : a.createdAt > b.createdAt ? 1 : 0));
453
+ let lastRevokeAt = null;
454
+ for (const c of sorted) {
455
+ if (REVOKE_RE.test(String(c.body || '').trim())) {
456
+ if (lastRevokeAt === null || c.createdAt > lastRevokeAt) lastRevokeAt = c.createdAt;
457
+ }
458
+ }
459
+ const out = [];
460
+ for (const c of sorted) {
461
+ const at = c.createdAt;
462
+ if (lastRevokeAt !== null && lastRevokeAt > at) continue;
463
+ const body = String(c.body || '').trim();
464
+ const base = { at, login: (c.author && c.author.login) || '', authorAssociation: c.authorAssociation || '' };
465
+ const h = body.match(GRANT_RE);
466
+ if (h) {
467
+ out.push({ role: 'human', branch: h[1], trunk: h[2], redSha: h[3], evidenceSha: h[4], host: h[5], ...base });
468
+ continue;
469
+ }
470
+ const r = parseReviewGrant(body);
471
+ if (r) {
472
+ const v = r.record ? validateReviewRecord(r.record, r.marker) : { valid: false, passing: false };
473
+ out.push({ role: r.marker.role, reviewer: r.marker.reviewer, branch: r.marker.branch, head: r.marker.head,
474
+ trunk: r.marker.trunk, redSha: r.marker.redSha, host: r.marker.host, ...base,
475
+ record: r.record, problems: r.problems,
476
+ valid: r.problems.length === 0 && v.valid, passing: r.problems.length === 0 && v.passing });
477
+ }
478
+ }
479
+ return out;
480
+ }
481
+
482
+ /** The label a check is named by in `cures:` and in reasons — `workflow / job`, or the bare job
483
+ * name when the workflow is unknown (tools/lib/ci-cure.js jobLabel). */
484
+ function checkLabel(j) {
485
+ return j && j.workflowName ? `${j.workflowName} / ${j.name}` : String((j && j.name) || '');
486
+ }
487
+
488
+ /**
489
+ * Which claimed cures are NOT red on trunk. `redJobs` is ci-cure.js redJobSet's `[{name,
490
+ * workflowName}]` at the red sha, or null when it could not be measured. A claimed name matches a red
491
+ * job by its full `workflow / job` label, or by its bare job name when exactly one red job carries
492
+ * it (an ambiguous bare name matches nothing — never a guess). Returns { ok, unmatched, reason }.
493
+ */
494
+ function curesAreRed(cures, redJobs) {
495
+ if (!Array.isArray(redJobs)) {
496
+ return { ok: false, unmatched: [], reason: 'trunk\'s red checks at that sha could not be measured — an unmeasured red set never confirms a cure' };
497
+ }
498
+ const list = Array.isArray(cures) ? cures : [];
499
+ if (list.length === 0) return { ok: false, unmatched: [], reason: 'the review names no red check it cures' };
500
+ const labelsSet = new Set(redJobs.map(checkLabel));
501
+ const byName = new Map();
502
+ for (const j of redJobs) byName.set(j.name, (byName.get(j.name) || 0) + 1);
503
+ const unmatched = list.filter((c) => !labelsSet.has(c) && byName.get(c) !== 1);
504
+ if (unmatched.length) {
505
+ const red = redJobs.length ? redJobs.map((j) => `\`${checkLabel(j)}\``).join(', ') : 'none';
506
+ return { ok: false, unmatched,
507
+ reason: `the review claims to cure ${unmatched.map((c) => `\`${c}\``).join(', ')}, which ${unmatched.length === 1 ? 'is' : 'are'} not red on trunk at that sha (red: ${red})` };
508
+ }
509
+ return { ok: true, unmatched: [], reason: '' };
510
+ }
511
+
512
+ function titleIsTrunkRed(title) {
513
+ return String(title || '').trimStart().startsWith(TRUNK_RED_TITLE_PREFIX);
514
+ }
515
+
516
+ /**
517
+ * The reviewer-grant verdict for one issue on a ship. `ctx` = { branch, trunk, redTrunkSha, evidence,
518
+ * issueNum, labelName, policy, now, redJobs } where `evidence` is `{ok, sha}` for the branch's CURRENT
519
+ * remote head (or null on a failed read), `now` is an ISO instant or ms (absent = Date.now()), and
520
+ * `redJobs` is a function returning the red-job set at `redTrunkSha` (or null) — called only once
521
+ * everything cheaper has passed. Checks, cheapest first, each with its own reason. `record` must be a
522
+ * ghIssueView result carrying `title`. Returns { ok, grant, reason }.
523
+ */
524
+ function evaluateReviewerIssue(record, ctx) {
525
+ const c = ctx || {};
526
+ const issue = c.issueNum;
527
+ const no = (reason, grant = null) => ({ issue, ok: false, grant, reason });
528
+ if (!record) return no(`#${issue} could not be read from the tracker — a failed read is never a grant`);
529
+ if (record.state !== 'OPEN') return no(`#${issue} is ${record.state || 'not open'} — a grant expires when its issue closes`);
530
+ const labelNames = (record.labels || []).map((l) => (l && typeof l === 'object' ? l.name : l));
531
+ if (!labelNames.includes(c.labelName)) return no(`#${issue} does not carry the \`${c.labelName}\` label`);
532
+ if (c.policy !== 'reviewer') return no(`this repo's ci-grant policy is "${c.policy || 'human'}" — a reviewer grant is honoured only under ci-grant: reviewer`);
533
+ if (!titleIsTrunkRed(record.title)) {
534
+ return no(`#${issue}'s title does not start "${TRUNK_RED_TITLE_PREFIX}" — a reviewer CI grant covers only a branch whose work is the red trunk's repair`);
535
+ }
536
+ const reviewer = liveGrantRecords(record.comments).filter((g) => g.role !== 'human');
537
+ if (reviewer.length === 0) return no(`#${issue} has no live reviewer grant (revoked, or never posted)`);
538
+ const g = reviewer[reviewer.length - 1];
539
+ if (g.branch !== c.branch) return no(`#${issue}'s reviewer grant is bound to branch "${g.branch}", not "${c.branch}"`, g);
540
+ if (!TRUSTED_ASSOCIATIONS.has(g.authorAssociation)) {
541
+ return no(`#${issue}'s reviewer grant was posted by ${g.login || '(unknown)'} (${g.authorAssociation || 'unknown association'}) — not a repo owner/member/collaborator`, g);
542
+ }
543
+ if (!g.valid) return no(`#${issue}'s reviewer grant has an invalid review record: ${(g.problems || []).join('; ') || 'unreadable'}`, g);
544
+ if (!g.passing) return no(`#${issue}'s review record says verdict ${g.record && g.record.verdict} — only a pass is a grant`, g);
545
+ if (g.trunk !== c.trunk || g.redSha !== c.redTrunkSha) {
546
+ return no(`#${issue}'s reviewer grant was reviewed against \`${g.trunk}\`@\`${String(g.redSha).slice(0, 7)}\`, not the current \`${c.trunk}\`@\`${String(c.redTrunkSha || '').slice(0, 7)}\` — trunk moved since the review`, g);
547
+ }
548
+ const nb = g.record['not-before'];
549
+ if (nb) {
550
+ const now = c.now === undefined ? Date.now() : (typeof c.now === 'number' ? c.now : Date.parse(c.now));
551
+ if (!(now >= Date.parse(nb))) return no(`#${issue}'s reviewer grant is not yet usable — its revoke window runs until ${nb}`, g);
552
+ }
553
+ if (!c.evidence) return no(`#${issue}'s reviewer grant could not be checked against the branch's current CI run — a failed evidence read is never a grant`, g);
554
+ if (!c.evidence.ok) return no(`#${issue}'s reviewer grant requires a completed, successful CI run on \`${c.branch}\`'s current head — none exists`, g);
555
+ if (String(c.evidence.sha || '').toLowerCase() !== String(g.head).toLowerCase()) {
556
+ return no(`#${issue}'s reviewer grant is bound to ${String(g.head).slice(0, 7)}, \`${c.branch}\` is at ${String(c.evidence.sha || '?').slice(0, 7)} — a new commit voids it`, g);
557
+ }
558
+ let redJobs = null;
559
+ try { redJobs = typeof c.redJobs === 'function' ? c.redJobs() : (c.redJobs === undefined ? null : c.redJobs); } catch (_) { redJobs = null; }
560
+ const cr = curesAreRed(parseCures(g.record.cures), redJobs);
561
+ if (!cr.ok) return no(`#${issue}: ${cr.reason}`, g);
562
+ return { issue, ok: true, grant: g, reason: '' };
563
+ }
564
+
300
565
  module.exports = {
301
566
  GRANT_MARK, REVOKE_MARK, GRANT_RE, REVOKE_RE,
302
567
  grantCommentBody, revokeCommentBody,
303
568
  liveGrants, TRUSTED_ASSOCIATIONS,
304
569
  evaluateIssue, evaluateShipSet, stackingVerdict, wentGreenSince,
570
+ // #504 — the reviewer role
571
+ REVIEW_GRANT_MARK, REVIEW_GRANT_RE, REVIEWER_ROLE, GRANT_ROLES, REVIEW_RECORD_FIELDS, TRUNK_RED_TITLE_PREFIX,
572
+ GRANT_POLICIES, parseGrantPolicy, parseCures, formatCures, validateReviewRecord, reviewGrantCommentBody,
573
+ parseReviewGrant, liveGrantRecords, checkLabel, curesAreRed, titleIsTrunkRed, evaluateReviewerIssue,
305
574
  };
@@ -52,3 +52,27 @@ export function encodeCiGrant(g?: Omit<DecodedCiGrant, 'tail'> & { tail?: string
52
52
  export function decodeCiGrant(body: string | null | undefined): DecodedCiGrant | null;
53
53
  export function encodeCiRevoke(r?: { branch: string; host: string; at: string; tail?: string | null }): string;
54
54
  export function decodeCiRevoke(body: string | null | undefined): DecodedMigrationGrant | null;
55
+
56
+ // ── reviewer red-trunk CI grant (#504) ───────────────────────────────────────────────────────
57
+
58
+ export const CI_REVIEW_GRANT_MARK: '🩹 Red-trunk CI review grant';
59
+ export const CI_REVIEW_GRANT_RE: RegExp;
60
+ export const CI_REVIEWER_ROLE: 'ci-reviewer';
61
+ export const CI_REVIEW_RECORD_FENCE: 'ci-review';
62
+ export const CI_REVIEW_RECORD_VERSION: '1';
63
+ export const CI_CURES_SEPARATOR: ';';
64
+ export const CI_REVIEW_RECORD_FIELDS: ReadonlyArray<ReviewRecordField>;
65
+
66
+ export interface DecodedCiReviewGrant {
67
+ role: string; reviewer: string; branch: string;
68
+ /** Full 40-hex sha the review covers, as written. */
69
+ head: string;
70
+ /** Trunk name and the full red trunk sha the review was made against. */
71
+ trunk: string; redSha: string;
72
+ host: string; at: string; tail: string | null;
73
+ record: Record<string, string> | null;
74
+ /** SYNTAX findings only — never whether the review passes. */
75
+ problems: string[];
76
+ }
77
+ export function encodeCiReviewGrant(g?: Partial<Omit<DecodedCiReviewGrant, 'problems' | 'record'>> & { record?: Record<string, unknown> }): string;
78
+ export function decodeCiReviewGrant(body: string | null | undefined): DecodedCiReviewGrant | null;
@@ -1,8 +1,9 @@
1
1
  'use strict';
2
2
  /**
3
3
  * CODEC (#498, epic #496): the GRANT comment wire formats as encode/decode pairs — the human
4
- * migration grant and its revoke, the reviewer migration grant with its fenced record, and the
5
- * red-trunk CI grant and its revoke. Pure and synchronous: no I/O, no clock, no requires.
4
+ * migration grant and its revoke, the reviewer migration grant with its fenced record, the
5
+ * red-trunk CI grant and its revoke, and the reviewer red-trunk CI grant with its fenced record
6
+ * (#504). Pure and synchronous: no I/O, no clock, no requires.
6
7
  *
7
8
  * What stays OUT of here is everything that JUDGES a grant: which grants are live, whose comment is
8
9
  * trusted, whether a record passes review, whether a grant still binds a HEAD. That lives in
@@ -11,7 +12,7 @@
11
12
  *
12
13
  * STABLE WIRE FORMAT. `tools/colab` and any vendored reader parse these verbatim, and an older CLI on
13
14
  * another machine reads what this one writes. Every mark has a DIFFERENT leading emoji from every
14
- * other (🛢 🚫 🔎 🚨 🧯), so no regex here can match another mark's body — a revoke that merely
15
+ * other (🛢 🚫 🔎 🚨 🧯 🩹), so no regex here can match another mark's body — a revoke that merely
15
16
  * suffixed its grant would parse as a fresh grant and reopen the door it was posted to close.
16
17
  *
17
18
  * Round-trip rule shared by every pair below: a decoded comment carries `tail`, the text after the
@@ -92,17 +93,7 @@ const REVIEW_RECORD_FIELDS = Object.freeze([
92
93
  function encodeReviewGrant({ role, reviewer, branch, head, host, at, tail, record } = {}) {
93
94
  const marker = withTail(`${REVIEW_GRANT_MARK} — role \`${role}\` · reviewer \`${reviewer}\` · branch \`${branch}\``
94
95
  + ` · head \`${head}\` · host \`${host}\` · ${at}`, tail, REVIEW_GRANT_TAIL);
95
- const rec = record || {};
96
- const known = REVIEW_RECORD_FIELDS.map((f) => f.key);
97
- const keys = [...known.filter((k) => Object.prototype.hasOwnProperty.call(rec, k)),
98
- ...Object.keys(rec).filter((k) => !known.includes(k))];
99
- const lines = [];
100
- for (const k of keys) {
101
- const v = rec[k];
102
- if (v === undefined || v === null || String(v) === '') continue;
103
- lines.push(`${k}: ${v}`);
104
- }
105
- return `${marker}\n\n\`\`\`${REVIEW_RECORD_FENCE}\n${lines.join('\n')}\n\`\`\``;
96
+ return `${marker}\n\n${fencedRecord(REVIEW_RECORD_FENCE, REVIEW_RECORD_FIELDS, record)}`;
106
97
  }
107
98
 
108
99
  /**
@@ -121,10 +112,16 @@ function decodeReviewGrant(body) {
121
112
  const t = line.slice(m[0].length);
122
113
  const out = { role: m[1], reviewer: m[2], branch: m[3], head: m[4], host: m[5], at: m[6],
123
114
  tail: t === REVIEW_GRANT_TAIL ? null : t, record: null, problems: [] };
124
- const fence = new RegExp('^```' + REVIEW_RECORD_FENCE + '[ \\t]*\\n([\\s\\S]*?)^```[ \\t]*$', 'm');
125
- const fm = text.match(fence);
115
+ return readFencedRecord(text, REVIEW_RECORD_FENCE, out);
116
+ }
117
+
118
+ /** Find the FIRST fenced block whose info string is exactly `fence` and read its `key: value`
119
+ * lines into `out.record`; syntax findings go to `out.problems`. Shared by both reviewer grants. */
120
+ function readFencedRecord(text, fence, out) {
121
+ const re = new RegExp('^```' + fence + '[ \\t]*\\n([\\s\\S]*?)^```[ \\t]*$', 'm');
122
+ const fm = text.match(re);
126
123
  if (!fm) {
127
- out.problems.push(`no \`\`\`${REVIEW_RECORD_FENCE} block — a reviewer grant without its review record is not a grant`);
124
+ out.problems.push(`no \`\`\`${fence} block — a reviewer grant without its review record is not a grant`);
128
125
  return out;
129
126
  }
130
127
  const record = {};
@@ -140,6 +137,22 @@ function decodeReviewGrant(body) {
140
137
  return out;
141
138
  }
142
139
 
140
+ /** Record object → its fenced lines: `fields` order first, then any other key in the object's own
141
+ * order; an empty/absent value is omitted. Shared by both reviewer grants. */
142
+ function fencedRecord(fence, fields, rec) {
143
+ const r = rec || {};
144
+ const known = fields.map((f) => f.key);
145
+ const keys = [...known.filter((k) => Object.prototype.hasOwnProperty.call(r, k)),
146
+ ...Object.keys(r).filter((k) => !known.includes(k))];
147
+ const lines = [];
148
+ for (const k of keys) {
149
+ const v = r[k];
150
+ if (v === undefined || v === null || String(v) === '') continue;
151
+ lines.push(`${k}: ${v}`);
152
+ }
153
+ return `\`\`\`${fence}\n${lines.join('\n')}\n\`\`\``;
154
+ }
155
+
143
156
  // ── red-trunk CI grant / revoke ───────────────────────────────────────────────────────────────
144
157
 
145
158
  const CI_GRANT_MARK = '🚨 Red-trunk CI grant';
@@ -174,6 +187,59 @@ function decodeCiRevoke(body) {
174
187
  return m ? { branch: m[1], host: m[2], at: m[3], tail: tailOf(s, m, REVOKE_TAIL) } : null;
175
188
  }
176
189
 
190
+ // ── reviewer red-trunk CI grant (#504): a marker line plus a fenced `ci-review` record ─────────
191
+ //
192
+ // The coordinator agent's door through a red trunk the cure rule refuses (maintainer ruling
193
+ // 2026-10-05). Same shape as the reviewer migration grant: a declared reviewer, a review record,
194
+ // bound to one HEAD. It additionally names the red trunk sha it reviewed against (a grant must never
195
+ // survive into a different red) and the red checks it claims to cure. Leading glyph 🩹, distinct from
196
+ // every other mark here.
197
+
198
+ const CI_REVIEW_GRANT_MARK = '🩹 Red-trunk CI review grant';
199
+ const CI_REVIEWER_ROLE = 'ci-reviewer';
200
+ const CI_REVIEW_GRANT_RE = /^🩹 Red-trunk CI review grant — role `([^`]*)` · reviewer `([^`]*)` · branch `([^`]*)` · head `([^`]*)` · red `([^`]*)`@`([^`]*)` · host `([^`]*)` · (\S+)/;
201
+ const CI_REVIEW_GRANT_TAIL = ' — bound to this HEAD and this red trunk sha: a new commit on either voids it; expires when this issue closes.';
202
+ const CI_REVIEW_RECORD_FENCE = 'ci-review';
203
+ const CI_REVIEW_RECORD_VERSION = '1';
204
+ /** `cures:` is a `; `-separated list of red check names (`workflow / job`, or a bare job name) —
205
+ * `;`, not `,`, because matrix job names carry commas (`test (ubuntu, 22)`). */
206
+ const CI_CURES_SEPARATOR = ';';
207
+
208
+ /** Every key a v1 `ci-review` record may carry. Order is the order the encoder writes them in. */
209
+ const CI_REVIEW_RECORD_FIELDS = Object.freeze([
210
+ { key: 'v', required: true, values: [CI_REVIEW_RECORD_VERSION] },
211
+ { key: 'role', required: true, values: [CI_REVIEWER_ROLE] },
212
+ { key: 'reviewer', required: true, re: REVIEWER_ID_RE, hint: 'letters, digits, . _ @ -' },
213
+ { key: 'head', required: true, re: SHA40_RE, hint: 'a full 40-hex commit sha' },
214
+ { key: 'red', required: true, re: SHA40_RE, hint: 'the full 40-hex red trunk sha reviewed against' },
215
+ { key: 'verdict', required: true, values: ['pass', 'fail'] },
216
+ { key: 'cures', required: true, re: /^[^;\s][^;]*(;\s*[^;\s][^;]*)*$/, hint: 'red check names, "; "-separated' },
217
+ { key: 'not-before', required: false, re: /^\d{4}-\d{2}-\d{2}T\S+$/, hint: 'an ISO-8601 instant' },
218
+ { key: 'ci-run', required: false, re: /^\S+$/, hint: 'a run id or URL, no spaces' },
219
+ ]);
220
+
221
+ /** `{role, reviewer, branch, head, trunk, redSha, host, at, tail?, record}` → marker line, blank
222
+ * line, fenced `ci-review` record. Validation is ci-grant.js's job; the codec writes what it gets. */
223
+ function encodeCiReviewGrant({ role, reviewer, branch, head, trunk, redSha, host, at, tail, record } = {}) {
224
+ const marker = withTail(`${CI_REVIEW_GRANT_MARK} — role \`${role}\` · reviewer \`${reviewer}\` · branch \`${branch}\``
225
+ + ` · head \`${head}\` · red \`${trunk}\`@\`${redSha}\` · host \`${host}\` · ${at}`, tail, CI_REVIEW_GRANT_TAIL);
226
+ return `${marker}\n\n${fencedRecord(CI_REVIEW_RECORD_FENCE, CI_REVIEW_RECORD_FIELDS, record)}`;
227
+ }
228
+
229
+ /** A CI review-grant comment → `{role, reviewer, branch, head, trunk, redSha, host, at, tail, record,
230
+ * problems}`, or null when the first line is not one. `problems` holds SYNTAX findings only. */
231
+ function decodeCiReviewGrant(body) {
232
+ const text = String(body == null ? '' : body).replace(/\r\n/g, '\n').trim();
233
+ const m = text.match(CI_REVIEW_GRANT_RE);
234
+ if (!m) return null;
235
+ const nl = text.indexOf('\n');
236
+ const line = nl === -1 ? text : text.slice(0, nl);
237
+ const t = line.slice(m[0].length);
238
+ const out = { role: m[1], reviewer: m[2], branch: m[3], head: m[4], trunk: m[5], redSha: m[6], host: m[7], at: m[8],
239
+ tail: t === CI_REVIEW_GRANT_TAIL ? null : t, record: null, problems: [] };
240
+ return readFencedRecord(text, CI_REVIEW_RECORD_FENCE, out);
241
+ }
242
+
177
243
  module.exports = {
178
244
  MIGRATION_GRANT_MARK, MIGRATION_REVOKE_MARK, MIGRATION_GRANT_RE, MIGRATION_REVOKE_RE,
179
245
  encodeMigrationGrant, decodeMigrationGrant, encodeMigrationRevoke, decodeMigrationRevoke,
@@ -181,4 +247,6 @@ module.exports = {
181
247
  encodeReviewGrant, decodeReviewGrant,
182
248
  CI_GRANT_MARK, CI_REVOKE_MARK, CI_GRANT_RE, CI_REVOKE_RE,
183
249
  encodeCiGrant, decodeCiGrant, encodeCiRevoke, decodeCiRevoke,
250
+ CI_REVIEW_GRANT_MARK, CI_REVIEW_GRANT_RE, CI_REVIEWER_ROLE, CI_REVIEW_RECORD_FENCE, CI_REVIEW_RECORD_VERSION,
251
+ CI_REVIEW_RECORD_FIELDS, CI_CURES_SEPARATOR, encodeCiReviewGrant, decodeCiReviewGrant,
184
252
  };
@@ -473,6 +473,60 @@
473
473
  },
474
474
  "note": "synthetic"
475
475
  }
476
+ ],
477
+ "ciReview": [
478
+ {
479
+ "wire": "🩹 Red-trunk CI review grant — role `ci-reviewer` · reviewer `reviewer-b` · branch `fix/trunk-red-audit-212` · head `4f2a9c1e7b3d5a6f8e0c2b4d6a8f0e1c3b5d7a9f` · red `main`@`9e8d7c6b5a4f3e2d1c0b9a8f7e6d5c4b3a2f1e0d` · host `h:ee4bcb5b2678` · 2026-10-05T16:20:31.507Z — bound to this HEAD and this red trunk sha: a new commit on either voids it; expires when this issue closes.\n\n```ci-review\nv: 1\nrole: ci-reviewer\nreviewer: reviewer-b\nhead: 4f2a9c1e7b3d5a6f8e0c2b4d6a8f0e1c3b5d7a9f\nred: 9e8d7c6b5a4f3e2d1c0b9a8f7e6d5c4b3a2f1e0d\nverdict: pass\ncures: CI / test (ubuntu-latest, 22); CI / self-audit\nci-run: 18290000042\n```",
480
+ "decoded": {
481
+ "role": "ci-reviewer",
482
+ "reviewer": "reviewer-b",
483
+ "branch": "fix/trunk-red-audit-212",
484
+ "head": "4f2a9c1e7b3d5a6f8e0c2b4d6a8f0e1c3b5d7a9f",
485
+ "trunk": "main",
486
+ "redSha": "9e8d7c6b5a4f3e2d1c0b9a8f7e6d5c4b3a2f1e0d",
487
+ "host": "h:ee4bcb5b2678",
488
+ "at": "2026-10-05T16:20:31.507Z",
489
+ "tail": null,
490
+ "record": {
491
+ "v": "1",
492
+ "role": "ci-reviewer",
493
+ "reviewer": "reviewer-b",
494
+ "head": "4f2a9c1e7b3d5a6f8e0c2b4d6a8f0e1c3b5d7a9f",
495
+ "red": "9e8d7c6b5a4f3e2d1c0b9a8f7e6d5c4b3a2f1e0d",
496
+ "verdict": "pass",
497
+ "cures": "CI / test (ubuntu-latest, 22); CI / self-audit",
498
+ "ci-run": "18290000042"
499
+ },
500
+ "problems": []
501
+ },
502
+ "note": "synthetic: the #504 shape, every field"
503
+ },
504
+ {
505
+ "wire": "🩹 Red-trunk CI review grant — role `ci-reviewer` · reviewer `reviewer-b` · branch `fix/trunk-red-audit-212` · head `4f2a9c1e7b3d5a6f8e0c2b4d6a8f0e1c3b5d7a9f` · red `main`@`9e8d7c6b5a4f3e2d1c0b9a8f7e6d5c4b3a2f1e0d` · host `h:ee4bcb5b2678` · 2026-10-05T16:20:31.507Z — bound to this HEAD and this red trunk sha: a new commit on either voids it; expires when this issue closes.\n\n```ci-review\nv: 1\nrole: ci-reviewer\nreviewer: reviewer-b\nhead: 4f2a9c1e7b3d5a6f8e0c2b4d6a8f0e1c3b5d7a9f\nred: 9e8d7c6b5a4f3e2d1c0b9a8f7e6d5c4b3a2f1e0d\nverdict: pass\ncures: CI / test (ubuntu-latest, 22); CI / self-audit\nnot-before: 2026-10-05T16:35:31.507Z\n```",
506
+ "decoded": {
507
+ "role": "ci-reviewer",
508
+ "reviewer": "reviewer-b",
509
+ "branch": "fix/trunk-red-audit-212",
510
+ "head": "4f2a9c1e7b3d5a6f8e0c2b4d6a8f0e1c3b5d7a9f",
511
+ "trunk": "main",
512
+ "redSha": "9e8d7c6b5a4f3e2d1c0b9a8f7e6d5c4b3a2f1e0d",
513
+ "host": "h:ee4bcb5b2678",
514
+ "at": "2026-10-05T16:20:31.507Z",
515
+ "tail": null,
516
+ "record": {
517
+ "v": "1",
518
+ "role": "ci-reviewer",
519
+ "reviewer": "reviewer-b",
520
+ "head": "4f2a9c1e7b3d5a6f8e0c2b4d6a8f0e1c3b5d7a9f",
521
+ "red": "9e8d7c6b5a4f3e2d1c0b9a8f7e6d5c4b3a2f1e0d",
522
+ "verdict": "pass",
523
+ "cures": "CI / test (ubuntu-latest, 22); CI / self-audit",
524
+ "not-before": "2026-10-05T16:35:31.507Z"
525
+ },
526
+ "problems": []
527
+ },
528
+ "note": "synthetic: a host-imposed revoke window (not-before), no ci-run"
529
+ }
476
530
  ]
477
531
  },
478
532
  "decisions": {