@futurelastic/colab-handbook 1.14.1-rc.9 → 1.15.0-rc.2

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
@@ -33,5 +33,5 @@
33
33
  "engines": {
34
34
  "node": ">=18"
35
35
  },
36
- "version": "1.14.1-rc.9"
36
+ "version": "1.15.0-rc.2"
37
37
  }
@@ -79,7 +79,7 @@ Named it something other than `ci-heavy.yml`? Say so with `heavy-workflow:` in `
79
79
  | `ci-node-heavy.yml`, `ci-python-heavy.yml`, `ci-laravel-heavy.yml` | `.github/workflows/ci-heavy.yml` | The heavy lane beside the matching `ci-<stack>.yml` (above) | `schedule` + `workflow_dispatch` + `workflow_call`, never a push. Toolchain and install steps are copied from the light lane's `build` job, so the two resolve the same versions — keep them in step. `TRUNK` is an edit point. |
80
80
  | `ci-python.yml` | `.github/workflows/ci.yml` | Python: FastAPI/Flask services, CLIs, libraries | Resolves Python from `project.yml` → `.python-version`/`requires-python` → **fails**. `requirements.txt` does not count. **Hybrid** Python+Node repo: copy this, then paste `ci-node.yml`'s `build:` job alongside — see the template header. |
81
81
  | `release-tag.yml` | `.github/workflows/release.yml` | Any repo cutting `v*.*.*` releases | Triggers on tag push. Publishes a grouped GitHub Release — a `-rc.N` tag as a pre-release, every summary since the previous *final* tag. No toolchain, no deploy; its header shows the `!v*.*.*-*` exclusion a deploy trigger needs. |
82
- | `release-auto.yml` | `.github/workflows/release-auto.yml` | A repo whose release tags land on `main` (`trunk: main`, `deploy: tag` or `none`) and whose §6 release route cuts candidates | Runs `colab release cut --auto` after CI goes green on main and `colab release finalize --auto` daily — plus an hourly run that re-tries only a refused cut, once the fetched CLI has moved within `RETRY_WINDOW_MINUTES` or a run at main's head was cancelled (#547) — from a handbook ref (`HANDBOOK_REF` — the `stable` channel by default, `next` for the fast channel, or an exact tag to freeze; #445) — the handbook's own copy runs its checkout's CLI instead, since it ships the CLI it releases with (#428). **Publishes the Release in the same run** — a tag pushed with `GITHUB_TOKEN` triggers no other workflow, so `release-tag.yml` would never fire for it. A refusal is a warning, not a red run. Reads and creates tags, and fast-forwards the release channels `next` / `stable` (branches naming the newest candidate / final, #445); never pushes a commit. The audit recognises any workflow running `release cut/finalize --auto` and warns when the route leaves candidates off, when it tags without publishing while a tag-push workflow waits, or when it commits. |
82
+ | `release-auto.yml` | `.github/workflows/release-auto.yml` | A repo whose release tags land on `main` (`trunk: main`, `deploy: tag` or `none`) and whose §6 release route cuts candidates | Runs `colab release cut --auto` after CI goes green on main — at the sha that CI run tested (`--sha`, #622), even once main has moved on — and `colab release finalize --auto` daily — plus an hourly run that re-tries only a refused cut, once the fetched CLI has moved within `RETRY_WINDOW_MINUTES` or a run at main's head was cancelled (#547) — from a handbook ref (`HANDBOOK_REF` — the `stable` channel by default, `next` for the fast channel, or an exact tag to freeze; #445) — the handbook's own copy runs its checkout's CLI instead, since it ships the CLI it releases with (#428). **Publishes the Release in the same run** — a tag pushed with `GITHUB_TOKEN` triggers no other workflow, so `release-tag.yml` would never fire for it. A refusal is a warning, not a red run. Reads and creates tags, and fast-forwards the release channels `next` / `stable` (branches naming the newest candidate / final, #445); never pushes a commit. The audit recognises any workflow running `release cut/finalize --auto` and warns when the route leaves candidates off, when it tags without publishing while a tag-push workflow waits, or when it commits. |
83
83
  | `dist-refs.yml` | `.github/workflows/dist-refs.yml` | A **private** repo shipping a **compiled** tool, installed as `npx github:<org>/<repo>#vX.Y.Z` ([CONVENTIONS §6, *Distribution*](../CONVENTIONS.md#distribution--one-install-surface-npx-442)) | `workflow_call`, called from the same run that cut the release tag (a tag pushed with `GITHUB_TOKEN` triggers nothing else). Takes one build artifact per `<os>-<arch>` and pushes each as an orphan commit at `refs/tags/dist/vX.Y.Z/<os>-<arch>` with a `SHA256SUMS`. Refuses a public or unreadable repository (a public compiled tool ships npm platform packages instead), a version that is not an existing tag, and a missing platform — before pushing any. Never moves a dist ref that exists. |
84
84
  | `npx-launcher.mjs` | anywhere in-repo (e.g. `bin/launch.mjs`), named by the root `package.json`'s `bin` | Pairs with `dist-refs.yml` | Node ≥ 18, zero dependencies, needs `git`. Reads the `#vX.Y.Z` npx installed, fetches that one dist ref with the same URL and credentials npx cloned with, verifies `SHA256SUMS`, installs to a stable per-user path (`$XDG_DATA_HOME`/`%LOCALAPPDATA%`), and execs it; `--print-path` prints that path. A **channel** committish (`#stable`, `#next`, #465) is resolved to the release tag on the commit npx installed, then installed as that version; any other branch is refused. Also the library `npx-service.mjs` imports. `*.mjs`, so `colab template npx-launcher.mjs --dest <path>` copies it stamped, `--dest` required. One edit point: `BIN` (defaults to the package name without its scope). |
85
85
  | `npx-service.mjs` | the same directory as your `npx-launcher.mjs` copy (e.g. `bin/service.mjs`), named by the root `package.json`'s `bin` | A tool that runs as a **per-machine service** (a dashboard, a daemon, a JS app a launch agent serves), installed with npx ([CONVENTIONS §6, *Services over npx*](../CONVENTIONS.md#services-over-npx--init-update-rollback-465)) | `npx github:<org>/<repo>#vX.Y.Z init [--auto-update 6h \| --no-auto-update]`, then `<tool> update [--check] [--version vX.Y.Z] [--channel next\|stable]`, `<tool> rollback`, `<tool> status`, `<tool> uninstall [--purge]` (#472: unit, timer, shim and every version go; config and state stay unless `--purge`); anything else runs the current version's payload. Versions side by side under `$XDG_DATA_HOME/<tool>/` with `current`/`previous` links the unit and the `~/.local/bin` shim go through; update installs beside, switches, restarts, health-checks, and **switches back** on failure. Config/secrets under `$XDG_CONFIG_HOME/<tool>/`, state and logs under `$XDG_STATE_HOME/<tool>/` — the unit carries their locations, never a value. launchd agent on macOS, systemd user unit on Linux, Windows refused; `<TOOL>_SERVICE_MANAGER=none` skips the manager. `--auto-update` (#471) adds a timer (launchd `StartInterval` agent / systemd user `.timer`) that runs the same `update`. Node ≥ 18, zero dependencies; needs `git`, `npm` for `update`, `tar` for `dist`. **Imports `./npx-launcher.mjs`** — copy both, or edit the import. Edit points: `KIND` (`binary` = a compiled tool from dist refs, `package` = a JS app run with node, `dist` = a prebuilt JS app unpacked from one verified tarball in the `dist/vX.Y.Z/any` ref, #470), `LABEL`, `SERVICE_ARGS`, `ENTRY`, `DIST_FILE`, `HEALTH_URL`, `KEEP`, `AUTO_UPDATE`, `VERBS`. The package's `files` must include both copies (and a `package` app's built output). `colab template npx-service.mjs --dest <path>`, `--dest` required. |
@@ -15,7 +15,9 @@
15
15
  # everywhere else)
16
16
  # your CI workflow finished green on main colab release cut --auto → vX.Y.Z-rc.N
17
17
  # (on `trunk: dev`: the promotion's push), (#443: the newest candidate always names main's
18
- # and the daily schedule head; a head already carrying one is a no-op)
18
+ # and the daily schedule head; a head already carrying one is a no-op.
19
+ # #622: a CI-fired run cuts the sha that run
20
+ # tested — `--sha` — even once main moved on)
19
21
  # a daily schedule colab release finalize --auto → vX.Y.Z (or a
20
22
  # hand-off where
21
23
  # the final is a
@@ -457,16 +459,41 @@ jobs:
457
459
  # declared release.candidates-per-day window held back is tagged once the window ends, even
458
460
  # with no new merge to fire workflow_run. A head already carrying a candidate is a no-op. Not
459
461
  # right after this run promoted: that head has no CI yet — the dispatched run cuts it.
462
+ # #622: a run fired by workflow_run cuts the sha THAT CI run tested (`--sha`), not main's head —
463
+ # on a busy trunk something lands during almost every suite run, so the green sha is rarely
464
+ # still the head when its run ends, and the head itself has no green run yet. The head gets its
465
+ # own candidate when its own run is green; a run that finishes out of order (a later commit
466
+ # already carries a candidate) is a no-op, so `next` never moves backwards. The schedule and a
467
+ # dispatch still cut main's head. While the cut reads an older sha the checkout is detached there
468
+ # (a release.guard-run reads the working tree) and restored afterwards.
460
469
  - name: Cut a candidate (colab release cut --auto)
461
470
  id: cut
462
471
  if: steps.gate.outputs.cut == 'true' && (github.event_name == 'workflow_run' || github.event_name == 'workflow_dispatch' || github.event_name == 'schedule') && steps.promote.outputs.promoted != 'true' && (env.RETRY_RUN != 'true' || steps.retry.outputs.retry == 'true')
472
+ env:
473
+ EVENT: ${{ github.event_name }}
474
+ RUN_SHA: ${{ github.event.workflow_run.head_sha }}
463
475
  run: |
464
476
  set -uo pipefail
465
477
  eval "$RETRY_TRANSIENT"
466
478
  OUT="$RUNNER_TEMP/cut.json"
467
479
  rc=0
468
480
  DRY=(); [ "${DRY_RUN:-false}" = "true" ] && DRY=(--dry)
469
- retry_transient node "$COLAB" release cut --auto ${DRY[@]+"${DRY[@]}"} --json > "$OUT" || rc=$?
481
+ AT=(); RESTORE=""
482
+ if [ "${EVENT:-}" = "workflow_run" ] && [ -n "${RUN_SHA:-}" ]; then
483
+ if git rev-parse --git-dir > /dev/null 2>&1 && [ "$(git rev-parse HEAD)" != "$RUN_SHA" ]; then
484
+ RESTORE="$(git symbolic-ref --quiet --short HEAD || git rev-parse HEAD)"
485
+ git checkout --quiet --detach "$RUN_SHA" || RESTORE=""
486
+ fi
487
+ # Asked AFTER the detach, of the CLI that will run: a CLI older than #622 (a HANDBOOK_REF no
488
+ # final with --sha has reached yet, or a checkout's own CLI at an older sha) cuts the head.
489
+ if grep -q -- '--sha <sha>' <<< "$(node "$COLAB" release cut --help 2> /dev/null)"; then
490
+ AT=(--sha "$RUN_SHA")
491
+ elif [ -n "$RESTORE" ]; then
492
+ git checkout --quiet "$RESTORE"; RESTORE=""
493
+ fi
494
+ fi
495
+ retry_transient node "$COLAB" release cut --auto ${AT[@]+"${AT[@]}"} ${DRY[@]+"${DRY[@]}"} --json > "$OUT" || rc=$?
496
+ [ -z "$RESTORE" ] || git checkout --quiet "$RESTORE"
470
497
  # A verdict is JSON carrying `ok`; anything else is a run that never decided.
471
498
  if ! jq -e 'has("ok")' "$OUT" > /dev/null 2>&1; then
472
499
  echo "::error::colab release cut produced no verdict (exit $rc)"
package/tools/colab CHANGED
@@ -1252,7 +1252,7 @@ function existingWorktreeFor(repoAbs, wtName, branch) {
1252
1252
  }
1253
1253
 
1254
1254
  const HELP_RELEASE = `colab release <issue> [--repo <path>]
1255
- colab release cut [--repo <path>] [--bump patch|minor --reason "<why>"] [--dry] [--json] (see: colab release cut --help)
1255
+ colab release cut [--repo <path>] [--sha <sha>] [--bump patch|minor --reason "<why>"] [--dry] [--json] (see: colab release cut --help)
1256
1256
  colab release finalize [--repo <path>] [--tag vX.Y.Z-rc.N] [--answered-by <name>] [--dry] [--json] (see: colab release finalize --help)
1257
1257
  colab release npm [--repo <path>] [--json] (see: colab release npm --help)
1258
1258
 
@@ -1284,9 +1284,9 @@ said so. Worktree claims never held the checkout; \`colab worktree rm\` owns the
1284
1284
  // release skill's (#339) and never this command's.
1285
1285
  // ---------------------------------------------------------------------------
1286
1286
 
1287
- const HELP_RELEASE_CUT = `colab release cut [--repo <path>] [--auto | --bump patch|minor --reason "<why>"] [--dry] [--json]
1287
+ const HELP_RELEASE_CUT = `colab release cut [--repo <path>] [--sha <sha>] [--auto | --bump patch|minor --reason "<why>"] [--dry] [--json]
1288
1288
 
1289
- Cut a release CANDIDATE, vX.Y.Z-rc.N, on origin/main's head — only where CONVENTIONS.md §6's release
1289
+ Cut a release CANDIDATE, vX.Y.Z-rc.N, on origin/main's head (or the commit --sha names) — only where CONVENTIONS.md §6's release
1290
1290
  rung lets an agent, and only once every condition below holds on that exact commit. Creates an
1291
1291
  annotated tag (the bump, its reason and every checked condition are recorded in its message) and
1292
1292
  pushes it to origin. NEVER creates a final vX.Y.Z tag — finalizing is the release skill's.
@@ -1302,7 +1302,10 @@ Refuses, naming each failed condition (all are reported, not just the first):
1302
1302
  already-candidate this commit already carries a candidate of the same version
1303
1303
  ci-green every run at the commit finished and one succeeded — colab ship's whole-sha check
1304
1304
  full-suite every workflow that ran at the commit has a successful run (a cancelled-only
1305
- workflow never ran its tests)
1305
+ workflow never ran its tests). Both read only the runs that verify the code,
1306
+ by colab ship's rule: a schedule / workflow_dispatch / workflow_run run (a
1307
+ nightly still in flight) is set aside and named; project.yml
1308
+ ship-gate-workflows / ship-ignore-workflows narrow it the same way
1306
1309
  schema-additive a migration since the last final tag is destructive (Laravel database/migrations
1307
1310
  up() drops/renames/->change(), Prisma DROP/RENAME/ALTER COLUMN, and .php/.sql
1308
1311
  under a project.yml \`migrations:\` prefix) or an existing migration was
@@ -1370,6 +1373,14 @@ The bump (without --auto) is release-status's semverSuggestion since the last fi
1370
1373
  patch, feat -> minor; a breaking change is a minor pre-1.0 and a refusal from 1.0 on.
1371
1374
  --bump patch|minor override the computed bump — requires --reason, which is recorded on the tag
1372
1375
  --reason "<why>" why the override
1376
+ --sha <sha> (#622) cut at this commit instead of main's head — the qualified sha a busy trunk
1377
+ has already moved past. Every condition above is measured at it; on-trunk
1378
+ requires it on main. One more row when it is not the head:
1379
+ qualified-sha refused (a NO-OP under --auto) when a release tag already names a
1380
+ later commit (the newer candidate stands), on a final route (a
1381
+ final is tagged only on main's head), or --auto under a
1382
+ candidates-per-day cap (the cut is spent on the head)
1383
+ The release workflow passes the sha its triggering CI run tested.
1373
1384
  --dry measure and report; create and push nothing
1374
1385
  --json machine-readable: { ok, tag, created, checks: [{condition, ok, detail}], ... }
1375
1386
  --repo <path> the repo (default: the one you are in)
@@ -1432,7 +1443,7 @@ function releaseCutChanges(repoAbs, from, sha, declared) {
1432
1443
  * — by branch window for a fresh head (cut), by commit for an older candidate (finalize). Also
1433
1444
  * returns the issue list it read (null when unread or gh unusable), so a caller does not read it twice.
1434
1445
  */
1435
- function measureCandidateConditions(repoAbs, { sha, lastFinal, at, readRuns, issues: knownIssues }) {
1446
+ function measureCandidateConditions(repoAbs, { sha, lastFinal, at, readRuns, issues: knownIssues, verifying }) {
1436
1447
  let ci; let suite; let switches; let issues = null;
1437
1448
  if (!isGhUsable(repoAbs)) {
1438
1449
  const why = ghUnusableWhy(repoAbs);
@@ -1441,11 +1452,16 @@ function measureCandidateConditions(repoAbs, { sha, lastFinal, at, readRuns, iss
1441
1452
  switches = { ok: false, unread: true, detail: `gh not usable (${why}) — the colab:switch markers cannot be read` };
1442
1453
  } else {
1443
1454
  // #616: a workflow whose every run at the sha was skipped did not run — not counted either way.
1444
- const rows = releaseCut.withoutSkippedOnlyWorkflows(readRuns());
1455
+ // #624: `verifying` (release cut only) narrows the rows to the runs that verify the code — a
1456
+ // scheduled run still in flight at the sha is not part of its verdict. Finalize passes none.
1457
+ const read = verifying ? releaseCut.verifyingRunsForCut(readRuns(), verifying) : { rows: readRuns() };
1458
+ const note = releaseCut.verifyingNote(read);
1459
+ const rows = releaseCut.withoutSkippedOnlyWorkflows(read.rows);
1445
1460
  const run = git.summarizeRunsForCommit(rows, sha);
1446
1461
  if (!run) ci = { ok: false, detail: `gh run list failed — cannot confirm CI at ${at}` };
1447
- else { const v = classifyCiRun(repoAbs, run, at); ci = { ok: v.ok, detail: v.detail }; }
1462
+ else { const v = classifyCiRun(repoAbs, run, at); ci = { ok: v.ok, detail: v.detail + note }; }
1448
1463
  suite = releaseCut.fullSuiteVerdict(rows, at);
1464
+ if (note && rows) suite = { ...suite, detail: suite.detail + note };
1449
1465
  // #423: an --auto finalize judges several candidates in one run — the issue list is read once.
1450
1466
  issues = knownIssues !== undefined ? knownIssues : readAllIssuesForSwitches(repoAbs);
1451
1467
  switches = releaseCut.switchVerdict(issues);
@@ -1655,10 +1671,11 @@ function announceCarried(repoAbs, { tagNames, exclude, version, sha }) {
1655
1671
 
1656
1672
  function cmdReleaseCut(argv) {
1657
1673
  const opts = parseArgs(argv, {
1658
- values: { '--repo': 'repo', '--bump': 'bump', '--reason': 'reason' },
1674
+ values: { '--repo': 'repo', '--bump': 'bump', '--reason': 'reason', '--sha': 'sha' },
1659
1675
  flags: { '--dry': 'dry', '--json': 'json', '--auto': 'auto', '-h': 'help', '--help': 'help' },
1660
1676
  });
1661
1677
  if (opts.help) return print(HELP_RELEASE_CUT);
1678
+ if (opts.sha !== undefined && !/^[0-9a-f]{4,40}$/i.test(String(opts.sha))) throw new UserError(`--sha takes a commit sha (hex, 4–40 chars), got ${JSON.stringify(opts.sha)} — run \`git rev-parse <rev>\` and pass the sha it prints`);
1662
1679
  if (opts._.length) throw new UserError(`release cut takes no positional arguments (got: ${opts._.join(' ')})`);
1663
1680
  if (opts.auto && (opts.bump || opts.reason)) throw new UserError('--auto computes the bump with no human input — --bump/--reason cannot be combined with it');
1664
1681
  if (opts.reason && !opts.bump) throw new UserError('--reason records why --bump overrode the computed bump — pass --bump with it');
@@ -1678,7 +1695,15 @@ function cmdReleaseCut(argv) {
1678
1695
  const trunkFetch = offTrunk && opts.auto ? git.git(['fetch', remote, trunk], repoAbs) : null;
1679
1696
  const shaR = git.git(['rev-parse', '--verify', '--quiet', `refs/remotes/${remote}/main^{commit}`], repoAbs);
1680
1697
  if (!shaR.ok || !shaR.stdout) throw new UserError(`no ${remote}/main — candidates are cut from main (CONVENTIONS.md §6: never from dev)`);
1681
- const sha = shaR.stdout;
1698
+ const head = shaR.stdout;
1699
+ // #622: --sha names the commit to cut — a qualified sha a busy trunk has already moved past. Every
1700
+ // condition below is measured at it; on-trunk still requires it to be an ancestor of main.
1701
+ let sha = head;
1702
+ if (opts.sha) {
1703
+ const r = git.git(['rev-parse', '--verify', '--quiet', `${opts.sha}^{commit}`], repoAbs);
1704
+ if (!r.ok || !r.stdout) throw new UserError(`--sha ${opts.sha} is not a commit in this clone (after fetching ${remote}/main) — run \`git log --oneline ${remote}/main\` and pass a sha from it`);
1705
+ sha = r.stdout;
1706
+ }
1682
1707
  const at = `main@${shortSha(sha)}`;
1683
1708
 
1684
1709
  const wf = git.git(['ls-tree', '--name-only', `${sha}:.github/workflows`], repoAbs);
@@ -1695,7 +1720,7 @@ function cmdReleaseCut(argv) {
1695
1720
  const remoteTags = remoteTagSetOrThrow(repoAbs, remote);
1696
1721
  const lastFinal = releaseTag.latestReleaseTag(repoAbs, { ref: `${remote}/main`, onlyTags: remoteTags });
1697
1722
  const suggestion = lastFinal
1698
- ? semverSuggestion(ccSummary(repoAbs, `${lastFinal}..${remote}/main`))
1723
+ ? semverSuggestion(ccSummary(repoAbs, `${lastFinal}..${sha}`)) // #622: the bump reads what the tagged commit carries
1699
1724
  : { bump: null, why: 'no final tag yet' };
1700
1725
  const lines = (r) => (r.ok ? r.stdout.split('\n').map((s) => s.trim()).filter(Boolean) : []);
1701
1726
  const onRemote = (t) => remoteTags.has(t);
@@ -1704,6 +1729,7 @@ function cmdReleaseCut(argv) {
1704
1729
 
1705
1730
  const { ci, suite, schema, switches, issues, migrations: migrationPathsSince } = measureCandidateConditions(repoAbs, {
1706
1731
  sha, lastFinal, at, readRuns: () => releaseCut.withoutOwnWorkflow(git.ghRunsForCommit(repoAbs, 'main', sha)), // #425
1732
+ verifying: verifyingPolicy(repoAbs), // #624: the ship gate's rule for which runs may veto
1707
1733
  });
1708
1734
  const { manifests, ancestry } = measurePreTag(repoAbs, sha, `${remote}/main`); // #424
1709
1735
 
@@ -1741,8 +1767,21 @@ function cmdReleaseCut(argv) {
1741
1767
  if (lane.present && lane.verdict.state === 'none' && opts.auto && !opts.dry) dispatchHeavyLane(repoAbs, lane.file, 'main', sha);
1742
1768
  }
1743
1769
 
1770
+ // #622: a cut below main's head — refused (a no-op under --auto) when a release tag already names a
1771
+ // later commit, on a final route, or under a candidates-per-day cap. Null at the head: today's cut.
1772
+ let qualified = null;
1773
+ if (sha !== head) {
1774
+ const c = git.git(['tag', '--contains', sha], repoAbs);
1775
+ const atSha = new Set(tagsAtSha);
1776
+ const newer = c.ok ? lines(c).filter(onRemote).filter((t) => !atSha.has(t) && /^v[0-9]+\.[0-9]+\.[0-9]+(-rc\.[1-9][0-9]*)?$/.test(t)) : null;
1777
+ qualified = releaseCut.qualifiedShaVerdict({
1778
+ sha, head, newer, finalRoute: fast || library, auto: !!opts.auto,
1779
+ capped: policy.effective && policy.effective.candidatesPerDay !== null && policy.effective.candidatesPerDay !== undefined,
1780
+ });
1781
+ }
1782
+
1744
1783
  const verdict = releaseCut.decide({
1745
- policy, triggers, lastFinal, suggestion, tags, tagsAtSha, ci, suite, schema, switches, manifests, ancestry, auto, heavy,
1784
+ policy, triggers, lastFinal, suggestion, tags, tagsAtSha, ci, suite, schema, switches, manifests, ancestry, auto, heavy, qualified,
1746
1785
  override: opts.bump ? { bump: opts.bump, reason: opts.reason } : null,
1747
1786
  finalGrant: fastFacts.finalGrant, holds: fastFacts.holds, migrations: fastFacts.migrations, migration: libraryMigration,
1748
1787
  trackingIssue: fastFacts.tracking ? fastFacts.tracking.number : null,
@@ -1805,7 +1844,7 @@ function cmdReleaseCut(argv) {
1805
1844
 
1806
1845
  if (opts.json) {
1807
1846
  print(JSON.stringify({
1808
- repo: shortRepo(repoAbs), sha, ...(offTrunk ? { trunk } : {}), lastFinal, suggestion, dry: !!opts.dry, auto: !!opts.auto,
1847
+ repo: shortRepo(repoAbs), sha, ...(sha !== head ? { head } : {}), ...(offTrunk ? { trunk } : {}), lastFinal, suggestion, dry: !!opts.dry, auto: !!opts.auto,
1809
1848
  ok: verdict.ok, noop: !!verdict.noop, standing: verdict.standing || [], tag: verdict.tag, created, published, channel, version: verdict.version, bump: verdict.bump,
1810
1849
  overridden: verdict.overridden, signals: verdict.signals ? verdict.signals.lines : null, checks: verdict.checks,
1811
1850
  // #446: present on every route, so the workflow reads one shape — final on deploy-tag-fast and
@@ -1817,7 +1856,7 @@ function cmdReleaseCut(argv) {
1817
1856
  return verdict.ok || verdict.noop ? 0 : 1;
1818
1857
  }
1819
1858
 
1820
- print(`colab release cut${opts.auto ? ' --auto' : ''} — ${shortRepo(repoAbs)} at ${at} (last final: ${lastFinal || 'none'})`);
1859
+ print(`colab release cut${opts.auto ? ' --auto' : ''} — ${shortRepo(repoAbs)} at ${at}${sha !== head ? ` (main's head: ${shortSha(head)})` : ''} (last final: ${lastFinal || 'none'})`);
1821
1860
  if (verdict.signals) {
1822
1861
  print(' signals:');
1823
1862
  for (const l of verdict.signals.lines) print(` · ${l}`);
@@ -1830,7 +1869,7 @@ function cmdReleaseCut(argv) {
1830
1869
  ? '· no-op — nothing owed, inside release.final-spacing, or main\'s head already carries a final; nothing tagged.'
1831
1870
  : library
1832
1871
  ? '· no-op — nothing owed (the manifest still says the last final), or main\'s head already carries a final; nothing tagged.'
1833
- : '· no-op — nothing owed, inside the route\'s cadence window, or main\'s head is not a promotion of trunk; nothing cut.');
1872
+ : '· no-op — nothing owed, inside the route\'s cadence window, main\'s head is not a promotion of trunk, or a later commit already carries a candidate; nothing cut.');
1834
1873
  return 0;
1835
1874
  }
1836
1875
  if (!verdict.ok) {
@@ -17353,7 +17392,7 @@ Commands:
17353
17392
  release-notes [<range>] [--repo P] [--out F] [--headline "..."] grouped Markdown release summary
17354
17393
  release-status [<repo>...] [--repo P] [--json] merged-but-UNRELEASED lag on tag-gated repos —
17355
17394
  read-only, never tags (#81)
17356
- release cut [--repo P] [--bump patch|minor --reason R] [--dry] [--json] cut a release CANDIDATE
17395
+ release cut [--repo P] [--sha S] [--bump patch|minor --reason R] [--dry] [--json] cut a release CANDIDATE
17357
17396
  vX.Y.Z-rc.N where §6's rung allows it; never a final tag (#338)
17358
17397
  release finalize [--repo P] [--tag RC] [--answered-by N] [--dry] [--json] a candidate's next step:
17359
17398
  testing / held / new candidate owed / human handoff / final
@@ -23,6 +23,7 @@
23
23
  * already-candidate the commit does not already carry a candidate of this version
24
24
  * ci-green §6 condition 1 — every run at the sha finished, one succeeded
25
25
  * full-suite §6 condition 2 — every workflow that ran at the sha has a successful run
26
+ * (both over the code-verifying runs only, the ship gate's rule — #624)
26
27
  * schema-additive §6 condition 3 — no destructive migration since the last final tag
27
28
  * switch-dependencies §6 condition 4 — the colab:switch markers are readable, and no finished
28
29
  * switch needs one that is still unfinished
@@ -75,6 +76,7 @@
75
76
  const migrationPaths = require('./migration-paths');
76
77
  const releaseTag = require('./release-tag');
77
78
  const { stripCode } = require('./instruction-file');
79
+ const verifyRuns = require('./verify-runs');
78
80
 
79
81
  const VERSION_RE = /^v(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)$/;
80
82
  const BUMPS = Object.freeze(['patch', 'minor']);
@@ -87,7 +89,7 @@ const BUMPS = Object.freeze(['patch', 'minor']);
87
89
  const RELEASE_BRANCH = 'main';
88
90
 
89
91
  const CONDITIONS = Object.freeze([
90
- 'release-policy', 'cadence', 'spacing', 'promotion', 'prerelease-trigger', 'version', 'already-candidate', 'already-final',
92
+ 'release-policy', 'cadence', 'spacing', 'promotion', 'qualified-sha', 'prerelease-trigger', 'version', 'already-candidate', 'already-final',
91
93
  ...releaseTag.PRE_TAG_CONDITIONS,
92
94
  'ci-green', 'full-suite', 'schema-additive', 'switch-dependencies',
93
95
  'final-grant', 'release-hold', 'migration-grant',
@@ -515,6 +517,35 @@ function cadenceVerdict({ candidates, perDay, now }) {
515
517
  return { ok: false, detail: `${recent.length} candidate(s) in the last 24h (${recent.map((c) => c.name).join(', ')}) — release.candidates-per-day caps at ${perDay} a day; the first run from ${nextAt} cuts main's head, never an older commit`, nextAt };
516
518
  }
517
519
 
520
+ // ---- #622: a candidate at a named sha that is not main's head ----------------------------------
521
+
522
+ /**
523
+ * `release cut --sha <sha>` (#622): a busy trunk moves during every long qualifying suite, so the sha
524
+ * that went green is rarely still main's head when its run ends. The cut may name that sha instead —
525
+ * every other condition is already measured at the sha; this verdict answers only what is new about
526
+ * tagging a commit below the head. Null when the sha IS main's head (nothing new: today's cut).
527
+ *
528
+ * newer release tags (candidate or final) on a commit that DESCENDS from the sha — a CI run
529
+ * finishing out of order. A candidate here would move `next` backwards.
530
+ * finalRoute deploy-tag-fast / library-fast: their cut is a FINAL, and #622 is candidates-only —
531
+ * those routes keep tagging main's head.
532
+ * capped --auto under a declared release.candidates-per-day cap: a capped route spends its
533
+ * cut on the head (#443's "never an older commit").
534
+ *
535
+ * Returns { ok, detail, unread }. Not ok is a NO-OP under --auto (the head's own run cuts), a refusal
536
+ * by hand. `newer: null` = the tags could not be read — unread, never "none newer".
537
+ */
538
+ function qualifiedShaVerdict({ sha, head, newer, finalRoute = false, capped = false, auto = false }) {
539
+ const s = String(sha || '').slice(0, 7);
540
+ const h = String(head || '').slice(0, 7);
541
+ if (!sha || !head || sha === head) return null;
542
+ if (finalRoute) return { ok: false, detail: `${s} is not main's head (${h}) — this route's cut is a final, and a final is tagged only on main's head; --sha names a candidate (#622)` };
543
+ if (auto && capped) return { ok: false, detail: `${s} is not main's head (${h}) — under a release.candidates-per-day cap a cut is spent on the head, never an older commit (#443)` };
544
+ if (newer === null || newer === undefined) return { ok: false, unread: true, detail: `the release tags on commits after ${s} could not be read — an unread newer candidate is not an absent one` };
545
+ if (newer.length) return { ok: false, detail: `${newer.join(', ')} already names a commit after ${s} — a candidate here would move \`next\` backwards; the newer one stands` };
546
+ return { ok: true, detail: `${s} is below main's head (${h}) and no release tag names a later commit — the candidate is cut at ${s} (#622)` };
547
+ }
548
+
518
549
  // ---- #446: deploy-tag-fast — spacing and holds ------------------------------------------------
519
550
 
520
551
  /**
@@ -708,6 +739,34 @@ function withoutSkippedOnlyWorkflows(rows) {
708
739
  return rows.filter((r) => !drop.has((r && r.workflowName) || '(unnamed workflow)'));
709
740
  }
710
741
 
742
+ /**
743
+ * #624: the run rows `release cut` judges ci-green and full-suite over — the runs that VERIFY the code
744
+ * at the sha, by the ship gate's own rule (verify-runs.js, #503: push / pull_request / merge_group
745
+ * triggers, project.yml `ship-gate-workflows` / `ship-ignore-workflows`, the #567 dispatch rescue).
746
+ * One rule for "which workflows may veto", not a second. Measured: a qualified sha whose CI push run
747
+ * had succeeded was refused ci-green AND full-suite because a scheduled `Nightly` run at the same sha
748
+ * was still in progress — a run that comes after the verdict, not part of it. Returns `{ rows,
749
+ * setAside }`; each set-aside row carries `setAsideWhy`. null passes through as `{ rows: null }`.
750
+ */
751
+ function verifyingRunsForCut(rows, policy) {
752
+ if (!Array.isArray(rows)) return { rows, setAside: [], dispatchCounted: [] };
753
+ const split = verifyRuns.splitVerifying(rows, policy || { gate: null, ignore: [] });
754
+ return { rows: split.counted, setAside: split.setAside, dispatchCounted: split.dispatchCounted || [] };
755
+ }
756
+
757
+ /**
758
+ * #624: the detail suffix naming what `verifyingRunsForCut` set aside (and any lost-push dispatch run
759
+ * it counted, #567) — the ship gate's own wording, so one reader learns one phrase. '' when neither.
760
+ */
761
+ function verifyingNote(read) {
762
+ if (!read) return '';
763
+ const summary = (list) => (list || []).map((x) => ({
764
+ workflowName: x.workflowName || null, status: x.status || null, conclusion: x.conclusion || null,
765
+ databaseId: x.databaseId || null, ...(x.setAsideWhy ? { why: x.setAsideWhy } : {}),
766
+ }));
767
+ return verifyRuns.setAsideNote(summary(read.setAside)) + verifyRuns.dispatchCountedNote(summary(read.dispatchCounted));
768
+ }
769
+
711
770
  /**
712
771
  * The run rows minus the CALLING workflow's own runs (#425). Inside the release workflow
713
772
  * (templates/release-auto.yml) `release cut` / `release finalize` read the runs at the very commit
@@ -1032,6 +1091,14 @@ function decide(facts) {
1032
1091
  }
1033
1092
  }
1034
1093
 
1094
+ // #622: a cut at a named sha below main's head — only what is new about it; every other row is
1095
+ // already measured at the sha. Null (no row) when the sha is the head or no --sha was given.
1096
+ const q = f.qualified;
1097
+ if (q) {
1098
+ add('qualified-sha', q.ok, q.detail, isUnread(q));
1099
+ if (!q.ok && f.auto && !q.unread) noop = true;
1100
+ }
1101
+
1035
1102
  const trig = f.triggers || [];
1036
1103
  if (trig.length) add('prerelease-trigger', false, `a deploy would fire on a candidate tag: ${trig.map((t) => t.text).join('; ')}`);
1037
1104
  else add('prerelease-trigger', true, 'no deploy workflow fires on a pre-release tag');
@@ -1188,8 +1255,8 @@ module.exports = {
1188
1255
  CONDITIONS, FAST_CONDITIONS, STANDING_CONDITIONS, BUMPS, MIGRATION_FILE, RELEASE_BRANCH, HOLD_LABEL,
1189
1256
  isFastRoute, isLibraryRoute, decideManifestVersion, spacingVerdict, holdsVerdict, migrationHandoff,
1190
1257
  parseVersion, formatVersion, candidateNumbers, nextCandidateNumber, decideVersion,
1191
- parseGuardOutput, exportsDiff, switchRemovalsSince, autoSignals, parseMigrationSection, decideAutoVersion, cadenceVerdict,
1192
- fullSuiteVerdict, withoutOwnWorkflow, withoutSkippedOnlyWorkflows, isMigrationPath, schemaVerdict,
1258
+ parseGuardOutput, exportsDiff, switchRemovalsSince, autoSignals, parseMigrationSection, decideAutoVersion, cadenceVerdict, qualifiedShaVerdict,
1259
+ fullSuiteVerdict, withoutOwnWorkflow, withoutSkippedOnlyWorkflows, verifyingRunsForCut, verifyingNote, isMigrationPath, schemaVerdict,
1193
1260
  parseSwitchMarkers, switchVerdict,
1194
1261
  promotionVerdict, decide, tagMessage, versionSourceOf,
1195
1262
  DOWNSTREAM_EVENTS, headCandidateVerdict, prereleaseArgs, finalReleaseArgs, handoffTrackingBody,