@futurelastic/colab-handbook 1.12.0-rc.41 → 1.12.0-rc.43

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/package.json CHANGED
@@ -27,5 +27,5 @@
27
27
  "engines": {
28
28
  "node": ">=18"
29
29
  },
30
- "version": "1.12.0-rc.41"
30
+ "version": "1.12.0-rc.43"
31
31
  }
package/tools/colab CHANGED
@@ -4400,7 +4400,10 @@ function computeAntiStacking(repoAbs, trunk, trunkIsRed) {
4400
4400
  let priorGrantMerge = null;
4401
4401
  if (priorLog.ok && priorLog.stdout.trim()) {
4402
4402
  const [sha, at] = priorLog.stdout.trim().split('\n')[0].split('\t');
4403
- priorGrantMerge = { sha, at };
4403
+ // #477: the red sha that exemption was measured against, off its own trailer — what the cure
4404
+ // rule's progress admission compares today's red set with. null when unreadable (refuses there).
4405
+ const body = git.git(['log', '-1', '--format=%B', sha], repoAbs);
4406
+ priorGrantMerge = { sha, at, redSha: body.ok ? ciCure.priorRedShaFromMessage(body.stdout) : null };
4404
4407
  }
4405
4408
  let redContinuousSincePriorGrant = false;
4406
4409
  if (priorGrantMerge) {
@@ -9443,7 +9446,7 @@ function ciGrantTrailerLine(grantVerdict, branch, trunk) {
9443
9446
  * line without touching the scan.
9444
9447
  *
9445
9448
  * A cure admitted through the #321 workflow carve-out appends ` via workflow-carve-out jobs <a,b>`.
9446
- * That suffix is not decoration: anti-stacking permits exactly ONE exemption per continuous red
9449
+ * That suffix is not decoration: anti-stacking permits ONE exemption per continuous red (more only on progress, #477)
9447
9450
  * episode, so a later reader has to be able to tell WHICH door spent it — and a cure that went
9448
9451
  * through the widened door on a branch editing the CI config is a materially different fact from an
9449
9452
  * ordinary one. The commit is the only artifact that still says so after the runs age out.
@@ -9457,7 +9460,11 @@ function ciCureTrailerLine(cureVerdict, branch, trunk) {
9457
9460
  const adm = cureVerdict.admitted || {};
9458
9461
  const manifest = [adm.scripts ? 'add-only-scripts' : null, adm.pins ? 'pin-only-requirements' : null].filter(Boolean);
9459
9462
  const admittedSuffix = manifest.length ? ` admitted ${manifest.join(',')}` : '';
9460
- return `CI-Cure: branch ${branch} over-red ${trunk}@${shortSha(cureVerdict.redSha)} evidence ${shortSha(cureVerdict.evidenceSha)}${via}${admittedSuffix}`;
9463
+ // #477: a cure that spent condition 3 by progress past a prior exemption says so, and which jobs
9464
+ // healed — the next cure on this red compares against THIS line's over-red sha.
9465
+ const progressSuffix = cureVerdict.progress
9466
+ ? ` after-progress healed ${cureVerdict.progress.healed.join(',')}` : '';
9467
+ return `CI-Cure: branch ${branch} over-red ${trunk}@${shortSha(cureVerdict.redSha)} evidence ${shortSha(cureVerdict.evidenceSha)}${via}${admittedSuffix}${progressSuffix}`;
9461
9468
  }
9462
9469
 
9463
9470
  const HELP_SHIP = `colab ship [--repo <path>] [--worktree <name> | --branch <br> | --direct] [--message "<msg>"] [--refs <N[,M]>] [--keep-worktree] [--delete-branch | --keep-branch] [--adopt] [--session <id>] [--session-name <s>] [--dry] [--json]
@@ -9588,7 +9595,9 @@ makes today); (2) the branch's own CI is green AT ITS OWN CURRENT HEAD, measured
9588
9595
  and (2b, #297) every job RED on trunk at the red sha exists in the branch's runs at that head,
9589
9596
  completed and \`success\` (a green run in which the failing check never ran proves nothing);
9590
9597
  (3) the same anti-stacking guard ci-grant uses holds (no prior grant OR cure merged while trunk has
9591
- stayed continuously red since); (4) the branch diff does not touch \`.github/workflows/**\` (a branch
9598
+ stayed continuously red since) — UNLESS trunk's red-job set now is a STRICT subset of the set at the
9599
+ red sha the prior exemption's trailer names (#477: progress, so two failures healed by two fixes need
9600
+ no human; an unchanged or grown set still refuses); (4) the branch diff does not touch \`.github/workflows/**\` (a branch
9592
9601
  may not self-certify a change to the CI configuration grading it; renames count) — UNLESS it passes
9593
9602
  the #321 CARVE-OUT below; (5, #297) the branch diff does not change the \`scripts\` block of any
9594
9603
  \`package.json\` — CI templates read that block to decide which checks run, so it is part of the
@@ -9609,7 +9618,7 @@ nothing — this is the sub-test that catches a fast exit, because GitHub report
9609
9618
  were all skipped as \`conclusion: success\`); (4c) each of those jobs cost at least the wall time its
9610
9619
  failure did on trunk. Anything unmeasurable refuses, exactly as before. A carve-out cure names the
9611
9620
  door in its \`CI-Cure:\` trailer and in \`--dry --json\`'s \`ciCure.via\`, because anti-stacking permits
9612
- only ONE exemption per continuous red and a later reader must be able to tell which door spent it.
9621
+ only ONE exemption per continuous red (more only while its red-job set shrinks, #477) and a later reader must be able to tell which door spent it.
9613
9622
  Its own honest limit: it proves the red jobs still ran the steps they ran and still cost the time —
9614
9623
  never what those steps ASSERTED. Known false refusal: a trunk job that failed by TIMEOUT ran longer
9615
9624
  than any healthy run, so (4c) refuses the genuine repair; take the ordinary ci-grant door there.
@@ -9738,7 +9747,9 @@ Options:
9738
9747
  warning). --dry prints "Machine trailer: …" saying which way it will go.
9739
9748
  --refs <N[,M]> reference these claimed issues (Refs #N) instead of closing them — for a
9740
9749
  long-lived memory/tracking issue the branch touched but did not complete.
9741
- Comma-separated; each must be a claimed issue on the branch. An issue carrying
9750
+ Comma-separated, and repeatable: --refs A --refs B is --refs A,B (#479 —
9751
+ every other value flag to ship refuses a repeat). Each must be a claimed
9752
+ issue on the branch. An issue carrying
9742
9753
  the "tracking" label is treated this way automatically, no flag needed. The
9743
9754
  claim is still released either way — only Closes→Refs changes.
9744
9755
  #385: a --refs'd issue whose body still has an unticked "- [ ]" box (under
@@ -10556,7 +10567,9 @@ function shipCiCure(repoAbs, gh, target, trunk, redSha, branch) {
10556
10567
  // #474: which workflows at the branch head offer a dry run — a static read (git show), read only
10557
10568
  // when job evidence exists, so a branch that already refuses on containment or 2a pays nothing.
10558
10569
  const capable = jobEvidence && evidence ? dryRunCapableWorkflows(repoAbs, evidence.sha) : [];
10559
- const verdict = ciCure.cureVerdict({ containsRedSha, evidence, redSha, stacking, jobEvidence,
10570
+ // #477: a stacked refusal may be lifted by progress — measure the prior red set only then.
10571
+ const priorRedJobs = jobEvidence && stacking && stacking.stacked ? priorExemptionRedJobs(repoAbs, trunk, stacking) : null;
10572
+ const verdict = ciCure.cureVerdict({ containsRedSha, evidence, redSha, stacking, jobEvidence, priorRedJobs,
10560
10573
  workflowsTouched: diff.workflowsTouched,
10561
10574
  manifestScriptsTouched: diff.manifestScriptsTouched, manifestPaths: diff.manifestPaths,
10562
10575
  manifestScriptsAddOnly: diff.manifestScriptsAddOnly,
@@ -10593,37 +10606,64 @@ function shipCiCure(repoAbs, gh, target, trunk, redSha, branch) {
10593
10606
  function shipCureJobEvidence(repoAbs, trunk, redSha, branch, evRun) {
10594
10607
  if (!evRun || !evRun.sha) return null;
10595
10608
 
10596
- // ALL runs at the red sha, not the single row `ghRunForCommit` would pick: a red job can sit in a
10609
+ const redRunJobs = trunkRedRunJobs(repoAbs, trunk, redSha);
10610
+ if (redRunJobs === null) return null;
10611
+
10612
+ const branchRuns = git.ghRunsForCommit(repoAbs, branch, evRun.sha);
10613
+ if (branchRuns === null || branchRuns.length === 0) return null;
10614
+ const branchRunJobs = [];
10615
+ for (const r of branchRuns) {
10616
+ const jobs = git.ghRunJobs(repoAbs, r.databaseId);
10617
+ if (jobs === null) return null;
10618
+ branchRunJobs.push(...jobs.map((j) => ({ ...j, workflowName: r.workflowName || '' })));
10619
+ }
10620
+
10621
+ return ciCure.shapeJobEvidence({ redRunJobs, branchRunJobs });
10622
+ }
10623
+
10624
+ /**
10625
+ * Every job of every not-green, repo-owned run on `trunk` at `sha`, each tagged with its run's
10626
+ * `workflowName` — the raw input of ci-cure.js's `shapeJobEvidence`/`redJobSet`. `null` on any failed
10627
+ * read, or when no not-green run exists there (nothing red to name). `limit` widens the run window
10628
+ * for an OLDER sha (#477's prior red sha), which a 10-row list of trunk's latest runs may not reach.
10629
+ */
10630
+ function trunkRedRunJobs(repoAbs, trunk, sha, limit) {
10631
+ // ALL runs at the sha, not the single row `ghRunForCommit` would pick: a red job can sit in a
10597
10632
  // sibling workflow the picker never returned, and admitting a carve-out while that job is still
10598
10633
  // red is exactly the failure this evidence exists to prevent.
10599
10634
  // #451: a run from a workflow the repo does not own is not part of trunk's red — same drop the
10600
10635
  // verdict itself makes (git.summarizeRunsForCommit), so cure evidence never chases its jobs.
10601
- const redRunsAll = git.ghRunsForCommit(repoAbs, trunk, redSha);
10602
- const redRuns = redRunsAll === null ? null : redRunsAll.filter(git.isRepoOwnedRun);
10603
- if (redRuns === null || redRuns.length === 0) return null;
10636
+ const runsAll = git.ghRunsForCommit(repoAbs, trunk, sha, limit);
10637
+ const runs = runsAll === null ? null : runsAll.filter(git.isRepoOwnedRun);
10638
+ if (runs === null || runs.length === 0) return null;
10604
10639
 
10605
10640
  // Same inverted allowlist git.js uses at run level (#146/#165): only `success`/`cancelled` are
10606
10641
  // not-bad, so a new not-success conclusion value is covered the day GitHub invents it.
10607
- const notGreen = redRuns.filter((r) => r.status === 'completed' && r.conclusion !== 'success' && r.conclusion !== 'cancelled');
10642
+ const notGreen = runs.filter((r) => r.status === 'completed' && r.conclusion !== 'success' && r.conclusion !== 'cancelled');
10608
10643
  if (notGreen.length === 0) return null;
10609
10644
 
10610
- const redRunJobs = [];
10645
+ const out = [];
10611
10646
  for (const r of notGreen) {
10612
10647
  const jobs = git.ghRunJobs(repoAbs, r.databaseId);
10613
10648
  if (jobs === null) return null;
10614
- redRunJobs.push(...jobs.map((j) => ({ ...j, workflowName: r.workflowName || '' })));
10615
- }
10616
-
10617
- const branchRuns = git.ghRunsForCommit(repoAbs, branch, evRun.sha);
10618
- if (branchRuns === null || branchRuns.length === 0) return null;
10619
- const branchRunJobs = [];
10620
- for (const r of branchRuns) {
10621
- const jobs = git.ghRunJobs(repoAbs, r.databaseId);
10622
- if (jobs === null) return null;
10623
- branchRunJobs.push(...jobs.map((j) => ({ ...j, workflowName: r.workflowName || '' })));
10649
+ out.push(...jobs.map((j) => ({ ...j, workflowName: r.workflowName || '' })));
10624
10650
  }
10651
+ return out;
10652
+ }
10625
10653
 
10626
- return ciCure.shapeJobEvidence({ redRunJobs, branchRunJobs });
10654
+ /**
10655
+ * The red-job set at the red sha the prior exemption on this continuous red was measured against
10656
+ * (#477) — read only when condition 3 refused as stacked AND job evidence exists (containment + 2a
10657
+ * passed), so no other ship pays for it. The trailer's sha is usually short; it is resolved to a full
10658
+ * sha first. `null` (unmeasured → no progress → the stacked refusal stands) on any failed step.
10659
+ */
10660
+ function priorExemptionRedJobs(repoAbs, trunk, stacking) {
10661
+ const short = stacking && stacking.stacked && stacking.prior ? stacking.prior.redSha : null;
10662
+ if (!short) return null;
10663
+ const full = git.git(['rev-parse', '--verify', '--quiet', `${short}^{commit}`], repoAbs);
10664
+ if (!full.ok || !full.stdout.trim()) return null;
10665
+ const raw = trunkRedRunJobs(repoAbs, trunk, full.stdout.trim(), 100);
10666
+ return raw === null ? null : ciCure.redJobSet(raw);
10627
10667
  }
10628
10668
 
10629
10669
  /**
@@ -10656,6 +10696,8 @@ function ciCurePayload(ciResult) {
10656
10696
  dryRunWanted: c.dryRunDispatch ? c.dryRunDispatch.map((d) => ({ ...d })) : null,
10657
10697
  // #475/#476: the manifest change a cure was admitted with — `{scripts?, pins?}` — or null.
10658
10698
  admitted: c.admitted || null,
10699
+ // #477: condition 3 passed by progress past a prior exemption — `{healed, still}` — or null.
10700
+ progress: c.progress ? { healed: c.progress.healed.slice(), still: c.progress.still.slice() } : null,
10659
10701
  };
10660
10702
  }
10661
10703
 
@@ -11513,6 +11555,8 @@ function cmdShipDirect(opts) {
11513
11555
  print(preOk ? '→ READY: preconditions pass. Re-run without --dry to close.' : '→ NOT READY: fix the ✗ rows above.');
11514
11556
  print(' Plan: no merge, no commit, no push · post evidence comment + CLOSE each issue · release the claims (and the checkout hold)');
11515
11557
  print(' Gate: every closing issue must already carry an evidence comment — checked at run time.');
11558
+ // #479: show BOTH halves of the split, so a wrong one is visible before the push.
11559
+ if (closeIssues.length) print(` Closes (closed by this ship): ${closeIssues.map((n) => '#' + n).join(' ')}`);
11516
11560
  if (refsIssues.length) print(` Refs (kept open, NOT closed): ${refsIssues.map((n) => '#' + n).join(' ')}`);
11517
11561
  return preOk ? 0 : 1;
11518
11562
  }
@@ -11736,7 +11780,13 @@ function shipRefFor(repoAbs, branch) {
11736
11780
 
11737
11781
  function cmdShip(argv) {
11738
11782
  const opts = parseArgs(argv, {
11739
- values: { '--repo': 'repo', '--worktree': 'worktree', '--branch': 'branch', '--message': 'message', '--refs': 'refs', '--session': 'session', '--session-name': 'sessionName', '--batch': 'batch' },
11783
+ values: { '--repo': 'repo', '--worktree': 'worktree', '--branch': 'branch', '--message': 'message', '--session': 'session', '--session-name': 'sessionName', '--batch': 'batch' },
11784
+ // #479: a repeated --refs used to keep only its LAST value, and every dropped issue then became a
11785
+ // `Closes` line on trunk — an issue meant to stay open, auto-closed by the push. --refs now
11786
+ // accumulates (a repeat is the same as one comma list); every OTHER value flag to ship refuses a
11787
+ // repeat (`once`), checked here before any git or GitHub call.
11788
+ lists: { '--refs': 'refs' },
11789
+ once: true,
11740
11790
  flags: { '--keep-worktree': 'keepWorktree', '--delete-branch': 'deleteBranch', '--keep-branch': 'keepBranch', '--dry': 'dry', '--json': 'json', '--direct': 'direct', '--adopt': 'adopt', '-h': 'help', '--help': 'help' },
11741
11791
  });
11742
11792
  if (opts.help) return print(HELP_SHIP);
@@ -12180,6 +12230,8 @@ function cmdShip(argv) {
12180
12230
  print(` ✗ "${c.keyword} #${c.num}" would close #${c.num} on merge — kept open by --refs; reword the commit before shipping.`);
12181
12231
  }
12182
12232
  }
12233
+ // #479: show BOTH halves of the split, so a wrong one is visible before the push.
12234
+ if (closeIssues.length) print(` Closes (closed by this ship): ${closeIssues.map((n) => '#' + n).join(' ')}`);
12183
12235
  if (refsIssues.length) print(` Refs (kept open, NOT closed): ${refsIssues.map((n) => '#' + n).join(' ')}`);
12184
12236
  return dryOk ? 0 : 1;
12185
12237
  }
@@ -34,6 +34,13 @@
34
34
  * trailer scan that feeds this (tools/colab's computeAntiStacking) to recognise BOTH a
35
35
  * prior `CI-Grant:` trailer and a prior `CI-Cure:` trailer as "an exemption already merged
36
36
  * against this red" — a cure and a grant are both exemptions for this guard's purposes.
37
+ * ONE NARROW ADMISSION (#477): PROGRESS. When the guard refuses because a prior exemption
38
+ * already merged on this continuous red, a further cure is still admitted iff trunk's red-job
39
+ * set at the current red sha is a STRICT subset of the red-job set at the red sha the prior
40
+ * exemption was measured against (`redSetShrank`, below). A fix that repaired one of two red
41
+ * jobs, or two independent failures healed by two successive fixes, then needs no human step;
42
+ * a cure that left the set unchanged — or grew it — still stops the chain, which is the loop
43
+ * condition 3 exists to break. Every other condition still applies to the remaining set.
37
44
  * 4. NO WORKFLOW-FILE CHANGES — the branch diff must not touch `.github/workflows/**`. A
38
45
  * branch that edits the CI configuration doing the grading is not allowed to grade itself;
39
46
  * that door stays behind a human ci-grant (condition 4 in the original proposal, #281).
@@ -583,6 +590,90 @@ function dryRunDispatchPlan(jobEvidence, dryRunCapable) {
583
590
  return [...want].sort();
584
591
  }
585
592
 
593
+ /**
594
+ * The prior exemption's red sha (#477), read off its merge commit's message: both trailers carry
595
+ * `over-red <trunk>@<sha>` — `CI-Grant:` (#105) and `CI-Cure:` (#281) — and that sha is what the
596
+ * prior exemption was measured against. Returns the hex string as written (usually short) or `null`
597
+ * when no such trailer line is present. Only a line STARTING with one of the two prefixes counts,
598
+ * the same anchoring `computeAntiStacking`'s `--grep` uses, so prose quoting a trailer cannot feed it.
599
+ */
600
+ function priorRedShaFromMessage(message) {
601
+ if (typeof message !== 'string') return null;
602
+ for (const line of message.split('\n')) {
603
+ const m = /^CI-(?:Grant|Cure):.*\bover-red \S*@([0-9a-f]{7,40})\b/.exec(line.trim());
604
+ if (m) return m[1];
605
+ }
606
+ return null;
607
+ }
608
+
609
+ /**
610
+ * The red-job SET at one trunk sha (#477), from the raw job rows of every not-green run there —
611
+ * the same selection `shapeJobEvidence` makes (an incomplete job → `null`, unmeasurable), reduced
612
+ * to `{name, workflowName}` identities.
613
+ */
614
+ function redJobSet(redRunJobs) {
615
+ const shaped = shapeJobEvidence({ redRunJobs, branchRunJobs: [] });
616
+ if (!shaped) return null;
617
+ return shaped.redJobs.map((j) => ({ name: j.name, workflowName: j.workflowName }));
618
+ }
619
+
620
+ /**
621
+ * Progress past condition 3 (#477) — PURE. `prior` is the red-job set at the red sha the most recent
622
+ * exemption on this continuous red was measured against; `current` the red-job set at trunk's red
623
+ * sha now (the `redJobs` of `shapeJobEvidence`). Jobs are compared by `jobKey` — workflow AND name,
624
+ * the same identity 2b matches on.
625
+ *
626
+ * ok only when `current` is a STRICT subset of `prior`: every job red now was already red then, and
627
+ * at least one job red then is not red now. An equal set is no progress (the prior exemption fixed
628
+ * nothing that stayed fixed); a job red now that was not red then is a NEW failure and refuses even
629
+ * if another job was repaired — admitting it would let a chain of cures trade one red for another
630
+ * forever. Either set unmeasured (`null`, non-array) or empty refuses: an empty `prior` cannot have
631
+ * been the basis of an exemption, and an empty `current` on a red trunk is unmeasurable (same
632
+ * posture as 2b).
633
+ */
634
+ function redSetShrank(prior, current) {
635
+ if (!Array.isArray(prior) || !Array.isArray(current)) {
636
+ return { ok: false, reason: 'the red-job set at the prior exemption\'s red sha could not be measured' };
637
+ }
638
+ if (!prior.length || !current.length) {
639
+ return { ok: false, reason: 'a red-job set to compare was empty — an unmeasurable red set is never progress' };
640
+ }
641
+ const before = new Map(prior.map((j) => [jobKey(j), j]));
642
+ const now = new Map(current.map((j) => [jobKey(j), j]));
643
+ const added = [...now.keys()].filter((k) => !before.has(k)).map((k) => jobLabel(now.get(k)));
644
+ const healed = [...before.keys()].filter((k) => !now.has(k)).map((k) => jobLabel(before.get(k)));
645
+ const still = [...now.values()].map(jobLabel);
646
+ if (added.length) {
647
+ return { ok: false, added, healed, still,
648
+ reason: `trunk's red set did not shrink: ${added.map((n) => `\`${n}\``).join(', ')} is red now and was not at the prior exemption's red sha — a new failure is not progress` };
649
+ }
650
+ if (!healed.length) {
651
+ return { ok: false, added, healed, still,
652
+ reason: `trunk's red set is unchanged since the prior exemption (${still.map((n) => `\`${n}\``).join(', ')}) — no progress` };
653
+ }
654
+ return { ok: true, added, healed, still,
655
+ reason: `trunk's red set shrank since the prior exemption: ${healed.map((n) => `\`${n}\``).join(', ')} healed, ` +
656
+ `${still.map((n) => `\`${n}\``).join(', ')} still red` };
657
+ }
658
+
659
+ /**
660
+ * Condition 3 as `cureVerdict` applies it (#477): the caller's `stacking` verdict, widened ONLY on
661
+ * its stacked refusal (`stacking.stacked`, set by ci-grant.js's stackingVerdict) and only by
662
+ * measured progress. Returns `{ok, reason, progress}` — `progress` is the `redSetShrank` result
663
+ * whenever it was consulted, so the success path can carry it into the trailer.
664
+ */
665
+ function stackingWithProgress(stacking, priorRedJobs, jobEvidence) {
666
+ if (stacking && stacking.ok) return { ok: true, reason: '', progress: null };
667
+ const base = (stacking && stacking.reason) || 'anti-stacking verdict unavailable';
668
+ if (!stacking || !stacking.stacked) return { ok: false, reason: base, progress: null };
669
+ const current = jobEvidence && Array.isArray(jobEvidence.redJobs) ? jobEvidence.redJobs : null;
670
+ const progress = redSetShrank(priorRedJobs, current);
671
+ if (!progress.ok) {
672
+ return { ok: false, progress, reason: `${base} The progress admission (#477) does not admit it either: ${progress.reason}` };
673
+ }
674
+ return { ok: true, reason: '', progress };
675
+ }
676
+
586
677
  /**
587
678
  * The cure verdict for one branch's attempt to ship into a red trunk.
588
679
  *
@@ -599,7 +690,11 @@ function dryRunDispatchPlan(jobEvidence, dryRunCapable) {
599
690
  * (the caller already used it to compute `containsRedSha` and `evidence`).
600
691
  *
601
692
  * `stacking` — `{ok, reason}`, the caller's `ciGrant.stackingVerdict(...)` result, reused
602
- * verbatim (condition 3) — this module never recomputes it.
693
+ * verbatim (condition 3) — this module never recomputes it. Its stacked refusal carries
694
+ * `stacked: true`; only that refusal can be lifted, by progress (#477).
695
+ *
696
+ * `priorRedJobs` (#477) — `redJobSet(...)` at the red sha the prior exemption named in its trailer,
697
+ * or `null` when unmeasured. Consulted only on a stacked refusal; compared with `jobEvidence.redJobs`.
603
698
  *
604
699
  * `workflowsTouched` — bool, whether the branch's diff against trunk touches any path under
605
700
  * `.github/workflows/` (condition 4 — tools/lib/cure-diff.js, `--no-renames`). `null` means the
@@ -637,14 +732,15 @@ function dryRunDispatchPlan(jobEvidence, dryRunCapable) {
637
732
  *
638
733
  * Returns `{ok, reason}`; on success also `provenJobs` (the red job names 2b proved, additive,
639
734
  * #297), `admitted` (#475/#476 — `{scripts: [{path, added}], pins: [{path, pins}]}`, present only
640
- * when a manifest admission was used) and — ONLY on a cure that went through the carve-out —
735
+ * when a manifest admission was used), `progress` (#477 — `{healed, still}`, present only when condition 3
736
+ * was passed by progress past a prior exemption) and — ONLY on a cure that went through the carve-out —
641
737
  * `carveOut: {jobs}`. The ordinary
642
738
  * cure's reason text is unchanged, which is what lets the caller answer "which door was this?" by
643
739
  * the presence of `carveOut` rather than by re-deriving it.
644
740
  */
645
741
  function cureVerdict({ containsRedSha, evidence, redSha, stacking, workflowsTouched, jobEvidence,
646
742
  manifestScriptsTouched, manifestPaths, manifestScriptsAddOnly, pythonManifestTouched, pythonManifestPaths,
647
- pythonPinOnly, dryRunCapable }) {
743
+ pythonPinOnly, dryRunCapable, priorRedJobs }) {
648
744
  if (!containsRedSha) {
649
745
  return { ok: false,
650
746
  reason: `branch does not contain trunk's current red head \`${redSha}\` as an ancestor — ` +
@@ -663,6 +759,7 @@ function cureVerdict({ containsRedSha, evidence, redSha, stacking, workflowsTouc
663
759
  'a bystander\'s PR runs against a merge ref that includes the red trunk, so it waits for green instead (#353)' };
664
760
  }
665
761
  const proven = redJobsProvenOnBranch(jobEvidence);
762
+ const cond3 = stackingWithProgress(stacking, priorRedJobs, jobEvidence);
666
763
  if (!proven.ok) {
667
764
  const out = { ok: false,
668
765
  reason: `branch's run is green, but the check trunk is red on is not proven here: ${proven.reason} — ` +
@@ -676,7 +773,7 @@ function cureVerdict({ containsRedSha, evidence, redSha, stacking, workflowsTouc
676
773
  || (manifestScriptsTouched === true && Array.isArray(manifestScriptsAddOnly) && manifestScriptsAddOnly.length > 0);
677
774
  const pythonOk = pythonManifestTouched === false
678
775
  || (pythonManifestTouched === true && Array.isArray(pythonPinOnly) && pythonPinOnly.length > 0);
679
- if (wanted.length && stacking && stacking.ok && scriptsOk && pythonOk
776
+ if (wanted.length && cond3.ok && scriptsOk && pythonOk
680
777
  && typeof workflowsTouched === 'boolean') {
681
778
  out.dryRunWanted = wanted;
682
779
  }
@@ -684,9 +781,11 @@ function cureVerdict({ containsRedSha, evidence, redSha, stacking, workflowsTouc
684
781
  }
685
782
  const dry = proven.dryRunJobs && proven.dryRunJobs.length ? { jobs: proven.dryRunJobs } : null;
686
783
  const drySuffix = dry ? ` — the main-only job(s) ${dry.jobs.map((n) => `\`${n}\``).join(', ')} proven by a dry run on the branch (#474)` : '';
687
- if (!stacking || !stacking.ok) {
688
- return { ok: false, reason: (stacking && stacking.reason) || 'anti-stacking verdict unavailable' };
784
+ if (!cond3.ok) {
785
+ return { ok: false, reason: cond3.reason };
689
786
  }
787
+ const prog = cond3.progress ? { progress: { healed: cond3.progress.healed, still: cond3.progress.still } } : {};
788
+ const progSuffix = cond3.progress ? `; past a prior exemption on this red because ${cond3.progress.reason} (#477)` : '';
690
789
  if (typeof workflowsTouched !== 'boolean' || typeof manifestScriptsTouched !== 'boolean'
691
790
  || typeof pythonManifestTouched !== 'boolean') {
692
791
  return { ok: false,
@@ -728,12 +827,12 @@ function cureVerdict({ containsRedSha, evidence, redSha, stacking, workflowsTouc
728
827
  }
729
828
  const detail = carve.jobs.map((j) => `\`${j.name}\` (${j.redMs}ms red on trunk, ${j.branchMs}ms passing here)`).join(', ');
730
829
  return { ok: true, provenJobs: proven.jobs, carveOut: { jobs: carve.jobs }, ...(dry ? { dryRun: dry } : {}),
731
- ...(via ? { admitted } : {}),
830
+ ...(via ? { admitted } : {}), ...prog,
732
831
  reason: `branch contains red \`${redSha}\` as an ancestor AND is green at its own current head (\`${evidence.sha}\`) — proven cure, ` +
733
- `admitted through the #321 workflow carve-out: every job red on trunk ran to success here with every step it took on trunk — ${detail}${drySuffix}${via}` };
832
+ `admitted through the #321 workflow carve-out: every job red on trunk ran to success here with every step it took on trunk — ${detail}${drySuffix}${via}${progSuffix}` };
734
833
  }
735
- return { ok: true, provenJobs: proven.jobs, ...(dry ? { dryRun: dry } : {}), ...(via ? { admitted } : {}),
736
- reason: `branch contains red \`${redSha}\` as an ancestor AND is green at its own current head (\`${evidence.sha}\`) — proven cure${drySuffix}${via}` };
834
+ return { ok: true, provenJobs: proven.jobs, ...(dry ? { dryRun: dry } : {}), ...(via ? { admitted } : {}), ...prog,
835
+ reason: `branch contains red \`${redSha}\` as an ancestor AND is green at its own current head (\`${evidence.sha}\`) — proven cure${drySuffix}${via}${progSuffix}` };
737
836
  }
738
837
 
739
838
  /** The reason-text suffix naming which manifest admission(s) a cure used (#475/#476), or ''. */
@@ -749,4 +848,5 @@ function admittedText(admitted) {
749
848
  }
750
849
 
751
850
  module.exports = { cureVerdict, redJobsProvenOnBranch, workflowCarveOut, manifestStepProof, shapeJobEvidence, dryRunDispatchPlan,
851
+ priorRedShaFromMessage, redJobSet, redSetShrank,
752
852
  WORKFLOW_REFUSAL, MANIFEST_SCRIPTS_REFUSAL, PYTHON_MANIFEST_REFUSAL, PUBLISH_STEP_MARKER, DRY_RUN_STEP };
@@ -294,7 +294,9 @@ function stackingVerdict({ trunkIsRed, priorGrantMerge, redContinuousSincePriorG
294
294
  return { ok: false, reason: 'trunk is not currently red — nothing for a CI grant to exempt' };
295
295
  }
296
296
  if (priorGrantMerge && redContinuousSincePriorGrant) {
297
- return { ok: false, reason: `a CI grant already merged ${priorGrantMerge.sha} against this red trunk and trunk has been red ever since — a second exemption is how a permanently broken repo ships anyway. Revert the bad merge or fix trunk by hand instead of granting again.` };
297
+ // `stacked`/`prior` are additive (#477): the cure rule may lift THIS refusal — and only this
298
+ // one — on measured progress (tools/lib/ci-cure.js redSetShrank); the grant CREATE path ignores them.
299
+ return { ok: false, stacked: true, prior: priorGrantMerge, reason: `a CI grant already merged ${priorGrantMerge.sha} against this red trunk and trunk has been red ever since — a second exemption is how a permanently broken repo ships anyway. Revert the bad merge or fix trunk by hand instead of granting again.` };
298
300
  }
299
301
  return { ok: true, reason: '' };
300
302
  }
package/tools/lib/util.js CHANGED
@@ -51,12 +51,19 @@ function humanAge(iso) {
51
51
  * spec.flags : { '--json': 'json', '--force': 'force' } boolean flags
52
52
  * spec.values : { '--repo': 'repo', '--count': 'count' } flags that take a value
53
53
  * spec.aliases : { '--issue': '--issues' } map an alias to its canonical flag
54
+ * spec.lists : { '--refs': 'refs' } value flags that ACCUMULATE: a repeat is
55
+ * joined onto the earlier value(s) with ',' — the same as one comma list (#479)
56
+ * spec.once : true a repeated `values` flag is a usage error
57
+ * instead of last-one-wins (#479). Off by default: most commands keep the old
58
+ * overwrite, where a dropped value is harmless; turn it on where it is not.
54
59
  * Positionals collected into result._ .
55
60
  */
56
61
  function parseArgs(argv, spec = {}) {
57
62
  const flags = spec.flags || {};
58
63
  const values = spec.values || {};
59
64
  const aliases = spec.aliases || {};
65
+ const lists = spec.lists || {};
66
+ const seen = new Set();
60
67
  const out = { _: [] };
61
68
  for (let i = 0; i < argv.length; i++) {
62
69
  let a = argv[i];
@@ -66,9 +73,18 @@ function parseArgs(argv, spec = {}) {
66
73
  const eq = a.indexOf('=');
67
74
  if (a.startsWith('--') && eq !== -1) { inlineVal = a.slice(eq + 1); a = a.slice(0, eq); }
68
75
  if (flags[a]) { out[flags[a]] = true; }
69
- else if (values[a]) {
76
+ else if (lists[a]) {
70
77
  const v = inlineVal !== null ? inlineVal : argv[++i];
71
78
  if (v === undefined) throw new UserError(`Option ${a} needs a value`);
79
+ const k = lists[a];
80
+ out[k] = out[k] === undefined ? v : `${out[k]},${v}`;
81
+ } else if (values[a]) {
82
+ const v = inlineVal !== null ? inlineVal : argv[++i];
83
+ if (v === undefined) throw new UserError(`Option ${a} needs a value`);
84
+ if (spec.once && seen.has(values[a])) {
85
+ throw new UserError(`Option ${a} given more than once — only one value is accepted; pass it once`);
86
+ }
87
+ seen.add(values[a]);
72
88
  out[values[a]] = v;
73
89
  } else if (a.startsWith('-') && a !== '-') {
74
90
  throw new UserError(`Unknown option: ${a}`);