@futurelastic/colab-handbook 1.20.1 → 1.20.2-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.20.1"
36
+ "version": "1.20.2-rc.2"
37
37
  }
@@ -260,7 +260,29 @@ jobs:
260
260
  fetch-depth: 0
261
261
  persist-credentials: false
262
262
 
263
+ # Kept between jobs (#696) — GitHub-hosted only: a fresh VM has nothing on disk, so the
264
+ # binary comes back from here and the install step below downloads nothing.
265
+ # - Self-hosted → off. A persistent runner keeps its tool cache on disk already, and a
266
+ # remote cache on top was measured as a loss, not a saving (#512).
267
+ # - Keyed on the pin and the platform: a version bump is a miss. The post step saves
268
+ # only when the job passes, so a failed download is never what gets cached.
269
+ # A NEW step, skipped on self-hosted. "Install gitleaks (pinned release binary)" keeps
270
+ # its name: handbook-sync recognises a copy of this job by it.
271
+ # EDIT: self-hosted runners are already off; to turn it off everywhere, delete this step.
272
+ - name: Restore gitleaks cache
273
+ if: runner.environment == 'github-hosted'
274
+ uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
275
+ with:
276
+ path: ${{ runner.tool_cache }}/gitleaks/${{ env.GITLEAKS_VERSION }}
277
+ key: gitleaks-${{ env.GITLEAKS_VERSION }}-${{ runner.os }}-${{ runner.arch }}
278
+
263
279
  - name: Install gitleaks (pinned release binary)
280
+ env:
281
+ # Authenticated (#698). Under load GitHub sheds ANONYMOUS release downloads first:
282
+ # measured 2026-11-09, ~90 min of instant 504s from github.com/…/releases/download,
283
+ # while the API asset path below answered 200 with the same file. The job's own token
284
+ # is enough — reading a public release needs an identity, not a permission.
285
+ GH_TOKEN: ${{ github.token }}
264
286
  run: |
265
287
  # NOT gitleaks/gitleaks-action@v2 — it demands a paid GITLEAKS_LICENSE for
266
288
  # organization-owned repositories. The plain release binary is MIT.
@@ -276,20 +298,70 @@ jobs:
276
298
  x86_64|amd64) arch=x64 ;;
277
299
  *) echo "unsupported arch: $(uname -m)" >&2; exit 1 ;;
278
300
  esac
279
- # --fail: on an HTTP error curl otherwise saves the error page and exits 0, and tar
280
- # then fails with "not in gzip format", naming neither the download nor the host.
281
- # --retry: a re-run during the same upstream error spends the one re-run branch CI
282
- # allows, so a brief error is retried here first. A longer outage still fails, at
283
- # curl, naming the status (#690).
284
- curl -fsSL --retry 5 --retry-delay 10 --retry-all-errors --connect-timeout 10 --max-time 120 -o gitleaks.tar.gz \
285
- "https://github.com/gitleaks/gitleaks/releases/download/v${GITLEAKS_VERSION}/gitleaks_${GITLEAKS_VERSION}_${os}_${arch}.tar.gz"
286
- # Into $RUNNER_TEMP, not /usr/local/bin: no sudo, no global write — the same
287
- # step then works on BOTH GitHub-hosted and shared self-hosted runners
288
- # (a shared runner is infrastructure; jobs must not mutate it).
289
- tar -xzf gitleaks.tar.gz -C "$RUNNER_TEMP" gitleaks
290
- chmod +x "$RUNNER_TEMP/gitleaks"
291
- echo "$RUNNER_TEMP" >> "$GITHUB_PATH"
292
- rm -f gitleaks.tar.gz
301
+ # Kept between jobs (#696): a pinned version is downloaded once per runner, not on
302
+ # every run. A release download can answer 504 for hours (measured: 20 of 20 tries),
303
+ # which outlasts any retry, so the binary has to be on the runner already.
304
+ # Into the runner's tool cache, not /usr/local/bin: no sudo, no global write — the
305
+ # per-runner directory setup-node and setup-python install into. A persistent
306
+ # self-hosted runner keeps it on disk; a GitHub-hosted VM gets it back from the
307
+ # "Restore gitleaks cache" step above. The version is in the path, so a pin bump is a
308
+ # miss, never a stale binary. EDIT: an ephemeral self-hosted runner keeps neither and
309
+ # downloads on every run.
310
+ dir="${RUNNER_TOOL_CACHE:-$RUNNER_TEMP}/gitleaks/${GITLEAKS_VERSION}/${os}-${arch}"
311
+ if [ -x "$dir/gitleaks" ]; then
312
+ echo "gitleaks ${GITLEAKS_VERSION} already on this runner: $dir"
313
+ else
314
+ mkdir -p "$dir"
315
+ tmp="$(mktemp -d "$dir.XXXXXX")"
316
+ trap 'rm -rf "$tmp"' EXIT
317
+ asset="gitleaks_${GITLEAKS_VERSION}_${os}_${arch}.tar.gz"
318
+ sums="gitleaks_${GITLEAKS_VERSION}_checksums.txt"
319
+ # fetch <accept> <url> <file> — every request of this step, one curl line.
320
+ # --fail: on an HTTP error curl otherwise saves the error page and exits 0, and tar
321
+ # then fails with "not in gzip format", naming neither the download nor the host.
322
+ # --retry: a re-run during the same upstream error spends the one re-run branch CI
323
+ # allows, so a brief error is retried here first. A longer outage still fails, at
324
+ # curl, naming the status (#690).
325
+ # The token reaches api.github.com only: curl drops an -H Authorization header when
326
+ # the asset's 302 leads to another host, so the download CDN never sees it.
327
+ fetch() {
328
+ curl -fsSL --retry 5 --retry-delay 10 --retry-all-errors --connect-timeout 10 --max-time 120 \
329
+ -H "Authorization: Bearer ${GH_TOKEN}" -H "Accept: $1" -o "$3" "$2"
330
+ }
331
+ # The API serves an asset by id, not by name, so look the ids up in the release. No jq:
332
+ # a self-hosted runner need not have it. Splitting on , { [ leaves one key per line
333
+ # whether the JSON comes pretty or compact; within an asset, "url" precedes "name". Were
334
+ # that order ever to change, the wrong file would arrive and the sha256 check below
335
+ # would refuse it — a loud failure, never a wrong binary.
336
+ fetch application/vnd.github+json \
337
+ "https://api.github.com/repos/gitleaks/gitleaks/releases/tags/v${GITLEAKS_VERSION}" "$tmp/release.json"
338
+ for f in "$asset" "$sums"; do
339
+ url="$(tr ',{[' '\n\n\n' < "$tmp/release.json" | awk -F'"' -v want="$f" '
340
+ $2 == "url" && $4 ~ /\/releases\/assets\/[0-9]+$/ { u = $4 }
341
+ $2 == "name" && $4 == want && !found { print u; found = 1 }')"
342
+ if [ -z "$url" ]; then
343
+ echo "::error::gitleaks release v${GITLEAKS_VERSION} has no asset $f"; exit 1
344
+ fi
345
+ fetch application/octet-stream "$url" "$tmp/$f"
346
+ done
347
+ # Verified before tar (#698): an error page, a truncated file or a wrong archive stops
348
+ # here, naming the file, instead of reaching tar — or, for a valid archive, the PATH.
349
+ want="$(awk -v f="$asset" '$2 == f { print $1 }' "$tmp/$sums")"
350
+ if command -v sha256sum >/dev/null; then got="$(sha256sum "$tmp/$asset" | awk '{ print $1 }')"
351
+ else got="$(shasum -a 256 "$tmp/$asset" | awk '{ print $1 }')"; fi # macOS self-hosted
352
+ if [ -z "$want" ]; then
353
+ echo "::error::$sums does not list $asset, so it cannot be verified"; exit 1
354
+ fi
355
+ if [ "$got" != "$want" ]; then
356
+ echo "::error::sha256 mismatch for $asset: got $got, $sums lists $want"; exit 1
357
+ fi
358
+ tar -xzf "$tmp/$asset" -C "$tmp" gitleaks
359
+ chmod +x "$tmp/gitleaks"
360
+ # One rename on one filesystem: a job sharing this tool cache sees no binary or a
361
+ # whole one, never half of one.
362
+ mv -f "$tmp/gitleaks" "$dir/gitleaks"
363
+ fi
364
+ echo "$dir" >> "$GITHUB_PATH"
293
365
 
294
366
  - name: gitleaks detect
295
367
  run: gitleaks detect --source . --no-banner
@@ -246,7 +246,29 @@ jobs:
246
246
  fetch-depth: 0
247
247
  persist-credentials: false
248
248
 
249
+ # Kept between jobs (#696) — GitHub-hosted only: a fresh VM has nothing on disk, so the
250
+ # binary comes back from here and the install step below downloads nothing.
251
+ # - Self-hosted → off. A persistent runner keeps its tool cache on disk already, and a
252
+ # remote cache on top was measured as a loss, not a saving (#512).
253
+ # - Keyed on the pin and the platform: a version bump is a miss. The post step saves
254
+ # only when the job passes, so a failed download is never what gets cached.
255
+ # A NEW step, skipped on self-hosted. "Install gitleaks (pinned release binary)" keeps
256
+ # its name: handbook-sync recognises a copy of this job by it.
257
+ # EDIT: self-hosted runners are already off; to turn it off everywhere, delete this step.
258
+ - name: Restore gitleaks cache
259
+ if: runner.environment == 'github-hosted'
260
+ uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
261
+ with:
262
+ path: ${{ runner.tool_cache }}/gitleaks/${{ env.GITLEAKS_VERSION }}
263
+ key: gitleaks-${{ env.GITLEAKS_VERSION }}-${{ runner.os }}-${{ runner.arch }}
264
+
249
265
  - name: Install gitleaks (pinned release binary)
266
+ env:
267
+ # Authenticated (#698). Under load GitHub sheds ANONYMOUS release downloads first:
268
+ # measured 2026-11-09, ~90 min of instant 504s from github.com/…/releases/download,
269
+ # while the API asset path below answered 200 with the same file. The job's own token
270
+ # is enough — reading a public release needs an identity, not a permission.
271
+ GH_TOKEN: ${{ github.token }}
250
272
  run: |
251
273
  # Deliberately NOT gitleaks/gitleaks-action@v2: that action requires a paid
252
274
  # GITLEAKS_LICENSE for repositories owned by an organization (free only for
@@ -266,20 +288,70 @@ jobs:
266
288
  x86_64|amd64) arch=x64 ;;
267
289
  *) echo "unsupported arch: $(uname -m)" >&2; exit 1 ;;
268
290
  esac
269
- # --fail: on an HTTP error curl otherwise saves the error page and exits 0, and tar
270
- # then fails with "not in gzip format", naming neither the download nor the host.
271
- # --retry: a re-run during the same upstream error spends the one re-run branch CI
272
- # allows, so a brief error is retried here first. A longer outage still fails, at
273
- # curl, naming the status (#690).
274
- curl -fsSL --retry 5 --retry-delay 10 --retry-all-errors --connect-timeout 10 --max-time 120 -o gitleaks.tar.gz \
275
- "https://github.com/gitleaks/gitleaks/releases/download/v${GITLEAKS_VERSION}/gitleaks_${GITLEAKS_VERSION}_${os}_${arch}.tar.gz"
276
- # Into $RUNNER_TEMP, not /usr/local/bin: no sudo, no global write — the same
277
- # step then works on BOTH GitHub-hosted and shared self-hosted runners
278
- # (a shared runner is infrastructure; jobs must not mutate it).
279
- tar -xzf gitleaks.tar.gz -C "$RUNNER_TEMP" gitleaks
280
- chmod +x "$RUNNER_TEMP/gitleaks"
281
- echo "$RUNNER_TEMP" >> "$GITHUB_PATH"
282
- rm -f gitleaks.tar.gz
291
+ # Kept between jobs (#696): a pinned version is downloaded once per runner, not on
292
+ # every run. A release download can answer 504 for hours (measured: 20 of 20 tries),
293
+ # which outlasts any retry, so the binary has to be on the runner already.
294
+ # Into the runner's tool cache, not /usr/local/bin: no sudo, no global write — the
295
+ # per-runner directory setup-node and setup-python install into. A persistent
296
+ # self-hosted runner keeps it on disk; a GitHub-hosted VM gets it back from the
297
+ # "Restore gitleaks cache" step above. The version is in the path, so a pin bump is a
298
+ # miss, never a stale binary. EDIT: an ephemeral self-hosted runner keeps neither and
299
+ # downloads on every run.
300
+ dir="${RUNNER_TOOL_CACHE:-$RUNNER_TEMP}/gitleaks/${GITLEAKS_VERSION}/${os}-${arch}"
301
+ if [ -x "$dir/gitleaks" ]; then
302
+ echo "gitleaks ${GITLEAKS_VERSION} already on this runner: $dir"
303
+ else
304
+ mkdir -p "$dir"
305
+ tmp="$(mktemp -d "$dir.XXXXXX")"
306
+ trap 'rm -rf "$tmp"' EXIT
307
+ asset="gitleaks_${GITLEAKS_VERSION}_${os}_${arch}.tar.gz"
308
+ sums="gitleaks_${GITLEAKS_VERSION}_checksums.txt"
309
+ # fetch <accept> <url> <file> — every request of this step, one curl line.
310
+ # --fail: on an HTTP error curl otherwise saves the error page and exits 0, and tar
311
+ # then fails with "not in gzip format", naming neither the download nor the host.
312
+ # --retry: a re-run during the same upstream error spends the one re-run branch CI
313
+ # allows, so a brief error is retried here first. A longer outage still fails, at
314
+ # curl, naming the status (#690).
315
+ # The token reaches api.github.com only: curl drops an -H Authorization header when
316
+ # the asset's 302 leads to another host, so the download CDN never sees it.
317
+ fetch() {
318
+ curl -fsSL --retry 5 --retry-delay 10 --retry-all-errors --connect-timeout 10 --max-time 120 \
319
+ -H "Authorization: Bearer ${GH_TOKEN}" -H "Accept: $1" -o "$3" "$2"
320
+ }
321
+ # The API serves an asset by id, not by name, so look the ids up in the release. No jq:
322
+ # a self-hosted runner need not have it. Splitting on , { [ leaves one key per line
323
+ # whether the JSON comes pretty or compact; within an asset, "url" precedes "name". Were
324
+ # that order ever to change, the wrong file would arrive and the sha256 check below
325
+ # would refuse it — a loud failure, never a wrong binary.
326
+ fetch application/vnd.github+json \
327
+ "https://api.github.com/repos/gitleaks/gitleaks/releases/tags/v${GITLEAKS_VERSION}" "$tmp/release.json"
328
+ for f in "$asset" "$sums"; do
329
+ url="$(tr ',{[' '\n\n\n' < "$tmp/release.json" | awk -F'"' -v want="$f" '
330
+ $2 == "url" && $4 ~ /\/releases\/assets\/[0-9]+$/ { u = $4 }
331
+ $2 == "name" && $4 == want && !found { print u; found = 1 }')"
332
+ if [ -z "$url" ]; then
333
+ echo "::error::gitleaks release v${GITLEAKS_VERSION} has no asset $f"; exit 1
334
+ fi
335
+ fetch application/octet-stream "$url" "$tmp/$f"
336
+ done
337
+ # Verified before tar (#698): an error page, a truncated file or a wrong archive stops
338
+ # here, naming the file, instead of reaching tar — or, for a valid archive, the PATH.
339
+ want="$(awk -v f="$asset" '$2 == f { print $1 }' "$tmp/$sums")"
340
+ if command -v sha256sum >/dev/null; then got="$(sha256sum "$tmp/$asset" | awk '{ print $1 }')"
341
+ else got="$(shasum -a 256 "$tmp/$asset" | awk '{ print $1 }')"; fi # macOS self-hosted
342
+ if [ -z "$want" ]; then
343
+ echo "::error::$sums does not list $asset, so it cannot be verified"; exit 1
344
+ fi
345
+ if [ "$got" != "$want" ]; then
346
+ echo "::error::sha256 mismatch for $asset: got $got, $sums lists $want"; exit 1
347
+ fi
348
+ tar -xzf "$tmp/$asset" -C "$tmp" gitleaks
349
+ chmod +x "$tmp/gitleaks"
350
+ # One rename on one filesystem: a job sharing this tool cache sees no binary or a
351
+ # whole one, never half of one.
352
+ mv -f "$tmp/gitleaks" "$dir/gitleaks"
353
+ fi
354
+ echo "$dir" >> "$GITHUB_PATH"
283
355
 
284
356
  - name: gitleaks detect
285
357
  run: gitleaks detect --source . --no-banner
@@ -257,7 +257,29 @@ jobs:
257
257
  fetch-depth: 0
258
258
  persist-credentials: false
259
259
 
260
+ # Kept between jobs (#696) — GitHub-hosted only: a fresh VM has nothing on disk, so the
261
+ # binary comes back from here and the install step below downloads nothing.
262
+ # - Self-hosted → off. A persistent runner keeps its tool cache on disk already, and a
263
+ # remote cache on top was measured as a loss, not a saving (#512).
264
+ # - Keyed on the pin and the platform: a version bump is a miss. The post step saves
265
+ # only when the job passes, so a failed download is never what gets cached.
266
+ # A NEW step, skipped on self-hosted. "Install gitleaks (pinned release binary)" keeps
267
+ # its name: handbook-sync recognises a copy of this job by it.
268
+ # EDIT: self-hosted runners are already off; to turn it off everywhere, delete this step.
269
+ - name: Restore gitleaks cache
270
+ if: runner.environment == 'github-hosted'
271
+ uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
272
+ with:
273
+ path: ${{ runner.tool_cache }}/gitleaks/${{ env.GITLEAKS_VERSION }}
274
+ key: gitleaks-${{ env.GITLEAKS_VERSION }}-${{ runner.os }}-${{ runner.arch }}
275
+
260
276
  - name: Install gitleaks (pinned release binary)
277
+ env:
278
+ # Authenticated (#698). Under load GitHub sheds ANONYMOUS release downloads first:
279
+ # measured 2026-11-09, ~90 min of instant 504s from github.com/…/releases/download,
280
+ # while the API asset path below answered 200 with the same file. The job's own token
281
+ # is enough — reading a public release needs an identity, not a permission.
282
+ GH_TOKEN: ${{ github.token }}
261
283
  run: |
262
284
  # Deliberately NOT gitleaks/gitleaks-action@v2: that action requires a paid
263
285
  # GITLEAKS_LICENSE for repositories owned by an organization (free only for
@@ -277,20 +299,70 @@ jobs:
277
299
  x86_64|amd64) arch=x64 ;;
278
300
  *) echo "unsupported arch: $(uname -m)" >&2; exit 1 ;;
279
301
  esac
280
- # --fail: on an HTTP error curl otherwise saves the error page and exits 0, and tar
281
- # then fails with "not in gzip format", naming neither the download nor the host.
282
- # --retry: a re-run during the same upstream error spends the one re-run branch CI
283
- # allows, so a brief error is retried here first. A longer outage still fails, at
284
- # curl, naming the status (#690).
285
- curl -fsSL --retry 5 --retry-delay 10 --retry-all-errors --connect-timeout 10 --max-time 120 -o gitleaks.tar.gz \
286
- "https://github.com/gitleaks/gitleaks/releases/download/v${GITLEAKS_VERSION}/gitleaks_${GITLEAKS_VERSION}_${os}_${arch}.tar.gz"
287
- # Into $RUNNER_TEMP, not /usr/local/bin: no sudo, no global write — the same
288
- # step then works on BOTH GitHub-hosted and shared self-hosted runners
289
- # (a shared runner is infrastructure; jobs must not mutate it).
290
- tar -xzf gitleaks.tar.gz -C "$RUNNER_TEMP" gitleaks
291
- chmod +x "$RUNNER_TEMP/gitleaks"
292
- echo "$RUNNER_TEMP" >> "$GITHUB_PATH"
293
- rm -f gitleaks.tar.gz
302
+ # Kept between jobs (#696): a pinned version is downloaded once per runner, not on
303
+ # every run. A release download can answer 504 for hours (measured: 20 of 20 tries),
304
+ # which outlasts any retry, so the binary has to be on the runner already.
305
+ # Into the runner's tool cache, not /usr/local/bin: no sudo, no global write — the
306
+ # per-runner directory setup-node and setup-python install into. A persistent
307
+ # self-hosted runner keeps it on disk; a GitHub-hosted VM gets it back from the
308
+ # "Restore gitleaks cache" step above. The version is in the path, so a pin bump is a
309
+ # miss, never a stale binary. EDIT: an ephemeral self-hosted runner keeps neither and
310
+ # downloads on every run.
311
+ dir="${RUNNER_TOOL_CACHE:-$RUNNER_TEMP}/gitleaks/${GITLEAKS_VERSION}/${os}-${arch}"
312
+ if [ -x "$dir/gitleaks" ]; then
313
+ echo "gitleaks ${GITLEAKS_VERSION} already on this runner: $dir"
314
+ else
315
+ mkdir -p "$dir"
316
+ tmp="$(mktemp -d "$dir.XXXXXX")"
317
+ trap 'rm -rf "$tmp"' EXIT
318
+ asset="gitleaks_${GITLEAKS_VERSION}_${os}_${arch}.tar.gz"
319
+ sums="gitleaks_${GITLEAKS_VERSION}_checksums.txt"
320
+ # fetch <accept> <url> <file> — every request of this step, one curl line.
321
+ # --fail: on an HTTP error curl otherwise saves the error page and exits 0, and tar
322
+ # then fails with "not in gzip format", naming neither the download nor the host.
323
+ # --retry: a re-run during the same upstream error spends the one re-run branch CI
324
+ # allows, so a brief error is retried here first. A longer outage still fails, at
325
+ # curl, naming the status (#690).
326
+ # The token reaches api.github.com only: curl drops an -H Authorization header when
327
+ # the asset's 302 leads to another host, so the download CDN never sees it.
328
+ fetch() {
329
+ curl -fsSL --retry 5 --retry-delay 10 --retry-all-errors --connect-timeout 10 --max-time 120 \
330
+ -H "Authorization: Bearer ${GH_TOKEN}" -H "Accept: $1" -o "$3" "$2"
331
+ }
332
+ # The API serves an asset by id, not by name, so look the ids up in the release. No jq:
333
+ # a self-hosted runner need not have it. Splitting on , { [ leaves one key per line
334
+ # whether the JSON comes pretty or compact; within an asset, "url" precedes "name". Were
335
+ # that order ever to change, the wrong file would arrive and the sha256 check below
336
+ # would refuse it — a loud failure, never a wrong binary.
337
+ fetch application/vnd.github+json \
338
+ "https://api.github.com/repos/gitleaks/gitleaks/releases/tags/v${GITLEAKS_VERSION}" "$tmp/release.json"
339
+ for f in "$asset" "$sums"; do
340
+ url="$(tr ',{[' '\n\n\n' < "$tmp/release.json" | awk -F'"' -v want="$f" '
341
+ $2 == "url" && $4 ~ /\/releases\/assets\/[0-9]+$/ { u = $4 }
342
+ $2 == "name" && $4 == want && !found { print u; found = 1 }')"
343
+ if [ -z "$url" ]; then
344
+ echo "::error::gitleaks release v${GITLEAKS_VERSION} has no asset $f"; exit 1
345
+ fi
346
+ fetch application/octet-stream "$url" "$tmp/$f"
347
+ done
348
+ # Verified before tar (#698): an error page, a truncated file or a wrong archive stops
349
+ # here, naming the file, instead of reaching tar — or, for a valid archive, the PATH.
350
+ want="$(awk -v f="$asset" '$2 == f { print $1 }' "$tmp/$sums")"
351
+ if command -v sha256sum >/dev/null; then got="$(sha256sum "$tmp/$asset" | awk '{ print $1 }')"
352
+ else got="$(shasum -a 256 "$tmp/$asset" | awk '{ print $1 }')"; fi # macOS self-hosted
353
+ if [ -z "$want" ]; then
354
+ echo "::error::$sums does not list $asset, so it cannot be verified"; exit 1
355
+ fi
356
+ if [ "$got" != "$want" ]; then
357
+ echo "::error::sha256 mismatch for $asset: got $got, $sums lists $want"; exit 1
358
+ fi
359
+ tar -xzf "$tmp/$asset" -C "$tmp" gitleaks
360
+ chmod +x "$tmp/gitleaks"
361
+ # One rename on one filesystem: a job sharing this tool cache sees no binary or a
362
+ # whole one, never half of one.
363
+ mv -f "$tmp/gitleaks" "$dir/gitleaks"
364
+ fi
365
+ echo "$dir" >> "$GITHUB_PATH"
294
366
 
295
367
  - name: gitleaks detect
296
368
  run: gitleaks detect --source . --no-banner
package/tools/colab CHANGED
@@ -12409,17 +12409,27 @@ function shipStaleBaseCheck(repoAbs, gh, base, branch) {
12409
12409
  // the trunk-CI row reads (commit statuses on Forgejo) — never keyed on the gh flag, so a stale or red
12410
12410
  // branch head cannot pass here as `unread` while the CI row passes on the forge's statuses.
12411
12411
  const fc = forgeCi(repoAbs);
12412
+ let verifiedRun = null;
12412
12413
  if (headSha && fc) run = fc.ciVerdict(headSha, { branch });
12413
- else if (headSha && gh) run = git.ghRunForCommit(repoAbs, branch, headSha);
12414
+ else if (headSha && gh) {
12415
+ // #691: one read, two summaries. `run` stays exactly what the stale-base and docs-only rows have
12416
+ // always read; `verifiedRun` applies the verifying-runs policy (#503) the trunk row uses, so the
12417
+ // head row below never refuses on a run that policy sets aside (a release lane, an ignored workflow).
12418
+ const rows = git.ghRunsForCommit(repoAbs, branch, headSha);
12419
+ run = git.summarizeRunsForCommit(rows, headSha);
12420
+ verifiedRun = git.summarizeRunsForCommit(rows, headSha, { verifying: verifyingPolicy(repoAbs), finishedRed: true });
12421
+ }
12414
12422
  // #606: `run`/`headSha` are additive — the docs-only row reads whether that run finished red.
12415
12423
  // #682: on a forge, `headCi` is the branch head's own CI verdict (green / red / pending), its own
12416
- // row — the class code-ship B1a reads through `colab ci-wait` on GitHub. null on GitHub, and where
12417
- // the head has no run to judge (the stale-base row speaks for those).
12418
- const headCi = fc ? staleBase.branchHeadCiVerdict({ headSha, run, branch, engine: fc.kind }) : null;
12424
+ // row. #691: on GitHub it is emitted only for a head whose run FINISHED red — waiting on a running
12425
+ // one stays code-ship B1a's `colab ci-wait` — and is null otherwise, as it is wherever the head has
12426
+ // no run to judge (the stale-base row speaks for those).
12427
+ const headCi = fc ? staleBase.branchHeadCiVerdict({ headSha, run, branch, engine: fc.kind })
12428
+ : (gh ? staleBase.githubBranchHeadRedVerdict({ headSha, run: verifiedRun, branch }) : null);
12419
12429
  return { ...staleBase.staleBaseVerdict({ headSha, run, baseTip, contains, behind, base, ciReadable: !!(fc || gh) }), run, headSha, headCi };
12420
12430
  }
12421
12431
 
12422
- /** #682: the forge branch-head CI row's name — one spelling for the JSON and the prose table. */
12432
+ /** #682: the branch-head CI row's name (forge; on GitHub a finished-red head only, #691) — one spelling for the JSON and the prose table. */
12423
12433
  const BRANCH_HEAD_CI_ROW = 'branch CI green at its head (#682)';
12424
12434
 
12425
12435
  /**
@@ -13243,7 +13253,7 @@ function cmdShipDryJson(opts) {
13243
13253
  } else {
13244
13254
  checks.push({ name: 'branch run contains current base (#395)', ok: staleJson.ok,
13245
13255
  class: staleJson.ok ? null : SELF_CLEARING, verdict: staleJson.verdict, detail: staleJson.detail });
13246
- const hc = staleJson.headCi; // #682: forge only — a red head needs a person, a running one clears
13256
+ const hc = staleJson.headCi; // #682 forge, #691 GitHub (red only) — a red head needs a person, a running one clears
13247
13257
  if (hc) checks.push({ name: BRANCH_HEAD_CI_ROW, ok: hc.ok, class: hc.ok ? null : (hc.selfClearing ? SELF_CLEARING : HUMAN_GATED), verdict: hc.verdict, detail: hc.detail });
13248
13258
  }
13249
13259
  // #610: the same gated heavy-lane read as the prose path. A missing or running heavy run clears on
@@ -15608,7 +15618,7 @@ function shipBatchLaneCheck(repoAbs, doc, trunk, target, gh, ciResult = null) {
15608
15618
  let t = git.git(['log', '-1', '--format=%cI', x.sha], repoAbs);
15609
15619
  if (!t.ok) { git.git(['fetch', '-q', remote, `refs/heads/${x.parsed.ref}`], repoAbs); t = git.git(['log', '-1', '--format=%cI', x.sha], repoAbs); }
15610
15620
  const built = t.ok ? Date.parse(t.stdout.trim()) : NaN;
15611
- return { ref: x.parsed.ref, base7: x.parsed.base7, rooted: true, verdict: shipBatch.combinedVerdict(runs),
15621
+ return { ref: x.parsed.ref, base7: x.parsed.base7, rooted: true, verdict: shipBatch.combinedVerdict(runs, { verifying: verifyRuns.parsePolicy(doc) }),
15612
15622
  builtAtMs: Number.isFinite(built) ? built : null, settledAtMs: shipBatch.settledAt(runs) };
15613
15623
  });
15614
15624
  const r = shipBatch.laneHold({ batches, trunkNow, nowMs: Date.now() });
@@ -15713,6 +15723,8 @@ function cmdShipBatch(opts) {
15713
15723
  const repoAbs = resolveRepo(opts);
15714
15724
  if (!git.repoRoot(repoAbs)) throw new UserError(`${repoAbs} is not a git repo`);
15715
15725
  const doc = projectDoc(repoAbs);
15726
+ // #692: the combined run reads a wholly skipped workflow as #688 does, unless ship-gate-workflows names it.
15727
+ const batchRead = { verifying: verifyRuns.parsePolicy(doc) };
15716
15728
  const trunk = resolveTrunk(repoAbs, doc);
15717
15729
  if (!trunk) throw new UserError('Could not determine trunk branch (set project.yml trunk:)');
15718
15730
  // #591: a member built on another machine names its hand-off inline — `<branch>@<hand-off-url>`.
@@ -15900,7 +15912,7 @@ function cmdShipBatch(opts) {
15900
15912
  print(` ${want} is gone and ${atTip.parsed.ref} at ${trunk}'s tip carries this batch — its parent landed; resuming on ${trunk}'s tip`);
15901
15913
  } else {
15902
15914
  const pc = chains.get(want);
15903
- const verdict = shipBatch.combinedVerdict(git.ghRunsForRef(repoAbs, want, p.sha));
15915
+ const verdict = shipBatch.combinedVerdict(git.ghRunsForRef(repoAbs, want, p.sha), batchRead);
15904
15916
  const child = rooted.find((x) => x !== p && p.sha.startsWith(x.parsed.base7)) || null;
15905
15917
  if (verdict.state === 'red') {
15906
15918
  if (child) {
@@ -15934,7 +15946,7 @@ function cmdShipBatch(opts) {
15934
15946
  let foreignStep = null;
15935
15947
  if (foreign.length) {
15936
15948
  const runs = git.ghRunsForRef(repoAbs, atBase.parsed.ref, atBase.sha);
15937
- foreignStep = shipBatch.foreignBatchStep(shipBatch.combinedVerdict(runs), { settledAtMs: shipBatch.settledAt(runs), nowMs: Date.now() });
15949
+ foreignStep = shipBatch.foreignBatchStep(shipBatch.combinedVerdict(runs, batchRead), { settledAtMs: shipBatch.settledAt(runs), nowMs: Date.now() });
15938
15950
  }
15939
15951
  if (foreignStep && foreignStep.step === 'wait') {
15940
15952
  print(`⏸ ship-batch: another batch is in flight at this base — ${atBase.parsed.ref} carries ${inBatch.map((m) => m.branch).join(', ')}${foreignStep.why ? ` (${foreignStep.why})` : ''}.`);
@@ -15963,7 +15975,7 @@ function cmdShipBatch(opts) {
15963
15975
  }
15964
15976
  }
15965
15977
  }
15966
- let verdict = existing && existing.matches ? shipBatch.combinedVerdict(git.ghRunsForRef(repoAbs, existing.ref, existing.sha)) : null;
15978
+ let verdict = existing && existing.matches ? shipBatch.combinedVerdict(git.ghRunsForRef(repoAbs, existing.ref, existing.sha), batchRead) : null;
15967
15979
  // #610: integration-profile: gated — a wave lands only on a green heavy run at its head too. The
15968
15980
  // heavy verdict joins the combined one (integration-profile.js waveVerdict), so a heavy red takes
15969
15981
  // the same re-run / split path a light red does, and the split walks toward the culprit.
@@ -16965,7 +16977,7 @@ function cmdBatchStats(argv) {
16965
16977
  if (!isGhUsable(repoAbs)) {
16966
16978
  notes.push(`gh not usable (${ghUnusableWhy(repoAbs)}) — trunk commits only: no combined runs, no green times, no partner matching`);
16967
16979
  } else {
16968
- const jq = '.workflow_runs[] | [.id, .head_branch, .head_sha, .event, .status, .conclusion, .run_attempt, .created_at, .updated_at, (if ((.head_branch // "") | startswith("ship-batch/")) then .head_commit.message else null end)] | @json';
16980
+ const jq = '.workflow_runs[] | [.id, .head_branch, .head_sha, .event, .status, .conclusion, .run_attempt, .created_at, .updated_at, (if ((.head_branch // "") | startswith("ship-batch/")) then .head_commit.message else null end), .name] | @json';
16969
16981
  // One query per UTC day: GitHub answers at most 1000 rows for a filtered run list, and a busy
16970
16982
  // repo passes that inside a fortnight. A day that still hits the cap is named, never hidden.
16971
16983
  const days = [];
@@ -16980,7 +16992,9 @@ function cmdBatchStats(argv) {
16980
16992
  if (!line.trim()) continue;
16981
16993
  let a; try { a = JSON.parse(line); } catch (_) { continue; }
16982
16994
  n++;
16983
- runs.push({ id: a[0], branch: a[1], sha: a[2], event: a[3], status: a[4], conclusion: a[5], attempt: a[6], createdMs: Date.parse(a[7]), updatedMs: Date.parse(a[8]), message: a[9] });
16995
+ // #692: `.name` is the workflow's `name:` (a `run-name:` is `.display_title`) — what the
16996
+ // ship's gate list and #688's per-workflow rule key on.
16997
+ runs.push({ id: a[0], branch: a[1], sha: a[2], event: a[3], status: a[4], conclusion: a[5], attempt: a[6], createdMs: Date.parse(a[7]), updatedMs: Date.parse(a[8]), message: a[9], workflowName: a[10] || undefined });
16984
16998
  }
16985
16999
  if (n >= 1000) capped.push(day);
16986
17000
  }
@@ -17003,7 +17017,7 @@ function cmdBatchStats(argv) {
17003
17017
 
17004
17018
  const cfg = shipBatch.parseShipBatch(doc);
17005
17019
  const waitCfg = shipBatch.parseShipBatchWait(doc);
17006
- const rep = batchStats.derive({ commits, runs, builds, trunk, config: { n: cfg.n, waitSec: waitCfg.sec } });
17020
+ const rep = batchStats.derive({ commits, runs, builds, trunk, config: { n: cfg.n, waitSec: waitCfg.sec }, verifying: verifyRuns.parsePolicy(doc) });
17007
17021
  rep.repo = shortRepo(repoAbs);
17008
17022
  rep.since = sinceIso;
17009
17023
  rep.until = new Date(nowMs).toISOString();
@@ -64,11 +64,12 @@ const isBatchRef = (b) => String(b || '').startsWith(shipBatch.REF_PREFIX);
64
64
 
65
65
  /**
66
66
  * When did `branch` go green at the head it had at time `atMs`? Its runs created before `atMs` are
67
- * read; the newest sha among them is the head at that moment. Green only when every run at that sha
68
- * finished success (cancelled aside, as combinedVerdict reads it) by `atMs` → the latest finish.
67
+ * read; the newest sha among them is the head at that moment. Green only when combinedVerdict reads
68
+ * the runs at that sha green, and their successes finished by `atMs` → the latest finish.
69
69
  * Null when there is no run, or the head was not green yet — unknown, never a guess.
70
+ * `verifying` (#692): the ship's policy, so a wholly skipped workflow reads as the batch lane reads it.
70
71
  */
71
- function greenAt(runsByBranch, branch, atMs, sha = null) {
72
+ function greenAt(runsByBranch, branch, atMs, sha = null, verifying = null) {
72
73
  const rows = (runsByBranch.get(branch) || []).filter((r) => r.createdMs <= atMs);
73
74
  if (!rows.length) return null;
74
75
  const headSha = sha
@@ -76,12 +77,28 @@ function greenAt(runsByBranch, branch, atMs, sha = null) {
76
77
  : rows.reduce((a, b) => (b.createdMs > a.createdMs ? b : a)).sha;
77
78
  if (!headSha) return null;
78
79
  const at = rows.filter((r) => r.sha === headSha);
79
- const v = shipBatch.combinedVerdict(at.map((r) => ({ status: r.status, conclusion: r.conclusion, attempt: r.attempt })));
80
+ const v = shipBatch.combinedVerdict(at.map(verdictRow), verdictOpts(verifying));
80
81
  if (v.state !== 'green') return null;
81
82
  const done = Math.max(...at.filter((r) => r.conclusion === 'success').map((r) => r.updatedMs));
82
83
  return done <= atMs ? done : null;
83
84
  }
84
85
 
86
+ /**
87
+ * #692: the projection combinedVerdict reads. `workflowName` and `event` ride along so #688's rule
88
+ * (a wholly skipped workflow is not judged beside a run that can verify the code) reads these rows
89
+ * exactly as `colab ship --batch` reads its own. A side effect of the name, wanted for the same
90
+ * reason: #629 now applies here too, so a named workflow whose only run was cancelled no longer reads
91
+ * green beside another workflow's success. A row without the field stays unnamed, read as before.
92
+ */
93
+ function verdictRow(r) {
94
+ return {
95
+ status: r.status, conclusion: r.conclusion, attempt: r.attempt, databaseId: r.id,
96
+ ...(r.workflowName ? { workflowName: r.workflowName } : {}),
97
+ ...(r.event ? { event: r.event } : {}),
98
+ };
99
+ }
100
+ const verdictOpts = (verifying) => (verifying ? { verifying } : {});
101
+
85
102
  /** Which feature branch carried a serial landing that closed `issues`, as of `atMs`? Newest run wins. */
86
103
  function branchForIssues(runsByBranch, issues, atMs) {
87
104
  if (!issues.length) return null;
@@ -100,14 +117,17 @@ function branchForIssues(runsByBranch, issues, atMs) {
100
117
  /**
101
118
  * The report. Inputs:
102
119
  * commits [{ sha, dateMs, body }] — trunk first-parent, inside the window, any order
103
- * runs [{ id, branch, sha, event, status, conclusion, attempt, createdMs, updatedMs, message? }]
120
+ * runs [{ id, branch, sha, event, status, conclusion, attempt, createdMs, updatedMs, message?,
121
+ * workflowName? }]
104
122
  * `message` is the head commit's message, needed only for ship-batch/** rows
123
+ * verifying optional — the ship's verify-runs policy (`{gate, ignore}`, #692); absent, a skipped
124
+ * row reads red as before
105
125
  * builds optional { [sha]: [message, …] } — every commit message of an UNLANDED build, when the
106
126
  * caller could read them (compare API); a landed build is read from trunk instead
107
127
  * trunk trunk branch name
108
128
  * config { n, waitSec } — the repo's declared knobs, echoed so the report says what it tunes
109
129
  */
110
- function derive({ commits = [], runs = [], builds = {}, trunk = 'main', config = {} } = {}) {
130
+ function derive({ commits = [], runs = [], builds = {}, trunk = 'main', config = {}, verifying = null } = {}) {
111
131
  const notes = [];
112
132
  const runsByBranch = new Map();
113
133
  const trunkRuns = new Map(); // sha → rows
@@ -157,12 +177,12 @@ function derive({ commits = [], runs = [], builds = {}, trunk = 'main', config =
157
177
  for (const l of landings) {
158
178
  if (l.kind === 'batch') {
159
179
  for (const m of l.members) {
160
- changes.push({ landing: l, branch: m.branch, issues: branchName.branchIssueNumbers(m.branch), greenMs: greenAt(runsByBranch, m.branch, l.atMs, m.sha), atMs: l.atMs });
180
+ changes.push({ landing: l, branch: m.branch, issues: branchName.branchIssueNumbers(m.branch), greenMs: greenAt(runsByBranch, m.branch, l.atMs, m.sha, verifying), atMs: l.atMs });
161
181
  }
162
182
  } else {
163
183
  const br = branchForIssues(runsByBranch, l.issues, l.atMs);
164
184
  l.branch = br;
165
- changes.push({ landing: l, branch: br, issues: l.issues, greenMs: br ? greenAt(runsByBranch, br, l.atMs) : null, atMs: l.atMs });
185
+ changes.push({ landing: l, branch: br, issues: l.issues, greenMs: br ? greenAt(runsByBranch, br, l.atMs, null, verifying) : null, atMs: l.atMs });
166
186
  }
167
187
  }
168
188
 
@@ -171,7 +191,7 @@ function derive({ commits = [], runs = [], builds = {}, trunk = 'main', config =
171
191
  const buildRows = [];
172
192
  for (const [k, rows] of batchRuns) {
173
193
  const [ref, sha] = k.split(' ');
174
- const v = shipBatch.combinedVerdict(rows.map((r) => ({ status: r.status, conclusion: r.conclusion, attempt: r.attempt, databaseId: r.id })));
194
+ const v = shipBatch.combinedVerdict(rows.map(verdictRow), verdictOpts(verifying));
175
195
  const landed = landedHeads.has(sha);
176
196
  const messages = landed ? null : (builds[sha] || rows.map((r) => r.message).filter(Boolean).slice(0, 1));
177
197
  buildRows.push({ ref, sha, state: v.state, attempt: v.attempt, landed, createdMs: Math.min(...rows.map((r) => r.createdMs)), messages });
@@ -235,14 +255,14 @@ function derive({ commits = [], runs = [], builds = {}, trunk = 'main', config =
235
255
  const via = tagVia ? { via: c.landing.kind === 'serial' ? 'serial' : 'batch-of-one' } : {};
236
256
  for (const o of changes) {
237
257
  if (o === c || o.landing === c.landing || o.atMs <= c.atMs || !o.branch || o.branch === c.branch) continue;
238
- const gNow = greenAt(runsByBranch, o.branch, c.atMs);
258
+ const gNow = greenAt(runsByBranch, o.branch, c.atMs, null, verifying);
239
259
  if (gNow !== null) {
240
260
  missed = true;
241
261
  pairs.push({ kind: 'missed', landed: label, partner: o.branch, ...via });
242
262
  continue;
243
263
  }
244
264
  if (end === null) continue;
245
- const gEnd = greenAt(runsByBranch, o.branch, end);
265
+ const gEnd = greenAt(runsByBranch, o.branch, end, null, verifying);
246
266
  if (gEnd !== null && gEnd > c.atMs) {
247
267
  near = true;
248
268
  const from = c.greenMs !== null ? c.greenMs : c.atMs;
package/tools/lib/git.js CHANGED
@@ -1280,6 +1280,12 @@ function summarizeRunsForCommit(allForSha, sha, opts = {}) {
1280
1280
  ...(allSkipped ? { allSkipped: true } : {}),
1281
1281
  ...(setAside.length ? { setAside: excludedRunSummary(setAside) } : {}),
1282
1282
  ...(dispatchCounted.length ? { dispatchCounted: excludedRunSummary(dispatchCounted) } : {}),
1283
+ // #691: opt-in (`opts.finishedRed`), so no reader that never asked sees a new field — every
1284
+ // JUDGED run that finished red: completed, and not success, cancelled or skipped (neither of
1285
+ // those two executed anything). The summary's single `conclusion` names only the first not-green
1286
+ // row it meets, which can be a `skipped` one beside a real failure; a caller asking "did any run
1287
+ // finish red here" reads this list instead. Absent when none did.
1288
+ ...(opts && opts.finishedRed && judged.some(isFinishedRed) ? { finishedRed: excludedRunSummary(judged.filter(isFinishedRed)) } : {}),
1283
1289
  // #651: the rows came from the unfiltered listing because the forge's filter index was empty.
1284
1290
  ...(allForSha.some((x) => x && x.readVia === 'unfiltered-listing') ? { readVia: 'unfiltered-listing' } : {}),
1285
1291
  };
@@ -1287,6 +1293,11 @@ function summarizeRunsForCommit(allForSha, sha, opts = {}) {
1287
1293
  return { ...r, ...extra };
1288
1294
  }
1289
1295
 
1296
+ /** #691: a run that ran and failed — completed, and not success, cancelled or skipped. */
1297
+ function isFinishedRed(x) {
1298
+ return !!x && x.status === 'completed' && x.conclusion !== 'success' && x.conclusion !== 'cancelled' && x.conclusion !== 'skipped';
1299
+ }
1300
+
1290
1301
  /** Sort key for "which run of one workflow is newer": createdAt, then databaseId; null = unknown. */
1291
1302
  function runRecency(x) {
1292
1303
  const t = x && x.createdAt ? Date.parse(x.createdAt) : NaN;
@@ -18,6 +18,8 @@
18
18
  * semantic conflicts need no shared file. The combined run is the gate.
19
19
  */
20
20
 
21
+ const verifyRuns = require('./verify-runs');
22
+
21
23
  // The SAFETY ceiling (#557): what any repo may declare, never what it gets. 3 until a red batch had
22
24
  // a cheaper exit than N serial cycles; split-and-retry (nextStep's `split`) is that exit, so the
23
25
  // ceiling is now 8 — the size from which bisection beats a serial fallback. A repo's own
@@ -384,33 +386,71 @@ function wiring(fires) {
384
386
  * least one success. `attempt` is the highest run attempt seen — how many times it was re-run.
385
387
  * Unlike summarizeRunsForCommit it does NOT reduce to the newest run per workflow (#461): a batch
386
388
  * ref is built fresh and re-run in place (same run, higher `attempt`), so it carries no superseded
387
- * attempts of a workflow for that reduction to set aside. Nor does it set a wholly skipped workflow
388
- * aside (#688): a skip here reads red, so a workflow gated off on `ship-batch/**` costs a split or
389
- * a serial landing rather than a refusal of trunk.
389
+ * attempts of a workflow for that reduction to set aside.
390
+ *
391
+ * #692: `opts.verifying` (the verify-runs.js policy, `{gate, ignore}`) applies #688's rule here too:
392
+ * a named workflow whose every row is `skipped` executed nothing, so it is set aside beside a row
393
+ * that can verify the code, unless `ship-gate-workflows` names it. Measured shape (#688): a
394
+ * workflow with every job gated on an unset repository variable fires on the batch push, concludes
395
+ * skipped, and read every batch red. Without `opts.verifying` nothing is set aside — a skip reads
396
+ * red, as before; batchGreenCoversTrunk asks that strict reading on purpose.
390
397
  */
391
- function combinedVerdict(rows) {
398
+ function combinedVerdict(rows, opts = {}) {
392
399
  const list = Array.isArray(rows) ? rows : null;
393
400
  if (list === null) return { state: 'pending', attempt: 1, runIds: [], why: 'the run list could not be read' };
394
401
  const runIds = list.map((r) => r.databaseId).filter((x) => x !== null && x !== undefined);
395
402
  const attempt = list.reduce((m, r) => Math.max(m, Number(r.attempt) || 1), 1);
396
403
  if (list.length === 0) return { state: 'none', attempt, runIds, why: 'no run at the batch head yet' };
397
- const bad = list.find((r) => r.status === 'completed' && r.conclusion !== 'success' && r.conclusion !== 'cancelled');
398
- if (bad) return { state: 'red', attempt, runIds, why: `a run finished ${bad.conclusion}` };
399
- if (list.some((r) => r.status !== 'completed')) return { state: 'pending', attempt, runIds, why: 'a run is still in flight' };
404
+ const policy = opts && opts.verifying ? opts.verifying : null;
405
+ const { judged, skippedOnly } = policy ? setAsideSkippedWorkflows(list, policy) : { judged: list, skippedOnly: [] };
406
+ const note = verifyRuns.skippedOnlyNote(skippedOnly);
407
+ const bad = judged.find((r) => r.status === 'completed' && r.conclusion !== 'success' && r.conclusion !== 'cancelled');
408
+ if (bad) {
409
+ const gated = bad.conclusion === 'skipped' && bad.workflowName && policy && Array.isArray(policy.gate) && policy.gate.includes(bad.workflowName);
410
+ return { state: 'red', attempt, runIds, why: gated
411
+ ? `workflow "${bad.workflowName}" finished skipped — ${verifyRuns.GATE_KEY} names it, so it must run here (#692)`
412
+ : `a run finished ${bad.conclusion}` };
413
+ }
414
+ if (judged.some((r) => r.status !== 'completed')) return { state: 'pending', attempt, runIds, why: `a run is still in flight${note}` };
400
415
  // #629 (the batch-ref twin of #628): a NAMED workflow whose rows here are all cancelled verified
401
416
  // nothing, and another workflow's success must not carry the verdict for it — measured shape: the
402
417
  // test workflow hung and was cancelled, a lint workflow passed, and the batch read green. A
403
418
  // batch ref is re-run in place (same run, higher attempt), so a cancelled row is never a
404
419
  // superseded straggler beside a newer run of its workflow; a same-workflow success still clears
405
420
  // it. Unnamed rows (batch-stats.js projections, older fixtures) stay neutral, as in #628.
406
- const succeeded = new Set(list.filter((r) => r.conclusion === 'success' && r.workflowName).map((r) => r.workflowName));
407
- const cancelledOnly = list.find((r) => r.workflowName && r.conclusion === 'cancelled' && !succeeded.has(r.workflowName));
421
+ const succeeded = new Set(judged.filter((r) => r.conclusion === 'success' && r.workflowName).map((r) => r.workflowName));
422
+ const cancelledOnly = judged.find((r) => r.workflowName && r.conclusion === 'cancelled' && !succeeded.has(r.workflowName));
408
423
  if (cancelledOnly) {
409
424
  const id = cancelledOnly.databaseId !== null && cancelledOnly.databaseId !== undefined ? ` (run ${cancelledOnly.databaseId})` : '';
410
425
  return { state: 'red', attempt, runIds, why: `workflow "${cancelledOnly.workflowName}" never finished here — its only run${id} was cancelled, so it verified nothing; re-run it` };
411
426
  }
412
- if (list.some((r) => r.conclusion === 'success')) return { state: 'green', attempt, runIds, why: `${list.length} run(s): all success` };
413
- return { state: 'red', attempt, runIds, why: 'every run was cancelled' };
427
+ if (judged.some((r) => r.conclusion === 'success')) return { state: 'green', attempt, runIds, why: `${judged.length} run(s): all success${note}` };
428
+ return { state: 'red', attempt, runIds, why: skippedOnly.length ? `every run that ran was cancelled${note}` : 'every run was cancelled' };
429
+ }
430
+
431
+ /**
432
+ * #692: #688's rule (git.js setAsideWhollySkipped) for the rows at one batch head. A NAMED workflow
433
+ * whose every row is a finished `skipped` is set aside — returned as `skippedOnly` — when:
434
+ * - `ship-gate-workflows` does not name it. A named gate workflow that skipped reads red: the
435
+ * owner said exactly these must count. (git.js sets nothing aside once the list is declared,
436
+ * because its rows were already narrowed to the list; batch rows are not, so the test is per
437
+ * name.)
438
+ * - another row can verify the code (a verifying trigger, or no `event` field). All-skipped
439
+ * stays red (#514): nothing verified the batch.
440
+ * Unnamed rows are never set aside (#92). A workflow with any row that is not a finished skip is
441
+ * left whole, so its skipped row still reads red beside it, as before #692.
442
+ */
443
+ function setAsideSkippedWorkflows(list, policy) {
444
+ const gate = policy && Array.isArray(policy.gate) ? policy.gate : null;
445
+ const isSkipped = (r) => !!r && r.status === 'completed' && r.conclusion === 'skipped';
446
+ const names = new Set(list.filter((r) => r && r.workflowName).map((r) => r.workflowName));
447
+ const wholly = new Set([...names].filter((n) => (!gate || !gate.includes(n))
448
+ && list.every((r) => !r || r.workflowName !== n || isSkipped(r))));
449
+ const unchanged = { judged: list, skippedOnly: [] };
450
+ if (!wholly.size) return unchanged;
451
+ const rest = list.filter((r) => !r || !wholly.has(r.workflowName));
452
+ if (!rest.some((r) => !isSkipped(r) && verifyRuns.setAsideReason(r, null) === null)) return unchanged;
453
+ return { judged: rest, skippedOnly: list.filter((r) => r && wholly.has(r.workflowName)) };
414
454
  }
415
455
 
416
456
  /**
@@ -524,6 +564,10 @@ function givenUpRefs({ refs, members } = {}) {
524
564
  * - the workflow FILES firing on a trunk push and on a `ship-batch/**` push are the same set;
525
565
  * - there are at least as many batch rows as trunk-firing workflows.
526
566
  * Anything else → false, and trunk waits for its own run exactly as today.
567
+ *
568
+ * #692: the batch rows are read WITHOUT the skipped-workflow rule (combinedVerdict with no policy).
569
+ * A workflow gated on the trunk ref is `skipped` on every batch ref, so a skip here would vouch for
570
+ * a trunk run that will execute; the stand-in needs every batch row to have run and passed.
527
571
  */
528
572
  function batchGreenCoversTrunk({ trunkRows, batchRows, trunkFires, batchFires }) {
529
573
  const t = Array.isArray(trunkRows) ? trunkRows : [];
@@ -123,4 +123,43 @@ function branchHeadCiVerdict(a) {
123
123
  `Wait with \`colab ci-wait --sha ${a.headSha} --branch ${a.branch}\`, then run ship again` };
124
124
  }
125
125
 
126
- module.exports = { staleBaseVerdict, branchHeadCiVerdict };
126
+ /**
127
+ * #691: the GitHub half of #682's row. On GitHub the branch head's class used to be left wholly to
128
+ * code-ship B1a (`colab ci-wait`), so `colab ship --dry --json` read READY on a head whose run had
129
+ * FINISHED red — measured on a required secret-scan job that failed before scanning anything. The
130
+ * row now refuses that one state, human-gated, in dry and real ship alike; everything else stays as
131
+ * it was on GitHub (null — no row):
132
+ *
133
+ * a run at the head finished red -> red, human-gated (red:infra or red:finding is B1a's call)
134
+ * green / in flight / no run / unread -> null: B1a's ci-wait still owns the wait, the stale-base
135
+ * row still speaks for `none` and an unread run
136
+ *
137
+ * "Finished red" is #606's docs-only rule (`docsOnlyBranchRow`): completed, and not success,
138
+ * cancelled or skipped — so a code branch is never held to a weaker rule than a docs-only one.
139
+ * `run` is the head's summary read under the verifying-runs policy (#503), the same rule the trunk
140
+ * row uses, so a run that policy sets aside (a release lane, a `ship-ignore-workflows` entry) never
141
+ * refuses here. `run.finishedRed` (tools/lib/git.js) lists every judged red run; without it the
142
+ * summary's own status/conclusion decides.
143
+ *
144
+ * @param {object} a
145
+ * @param {string|null} a.headSha - the branch head on the remote
146
+ * @param {object|null} a.run - summarizeRunsForCommit's verdict at headSha, verifying policy applied
147
+ * @param {string} a.branch
148
+ * @returns {null|{ok:false, verdict:'red', selfClearing:false, detail:string}}
149
+ */
150
+ function githubBranchHeadRedVerdict(a) {
151
+ const run = a && a.run;
152
+ if (!a || !a.headSha || !run || run.status === 'none') return null;
153
+ const listed = Array.isArray(run.finishedRed) ? run.finishedRed : [];
154
+ const summaryRed = run.status === 'completed' && run.conclusion !== 'success' && run.conclusion !== 'cancelled' && run.conclusion !== 'skipped';
155
+ if (!listed.length && !summaryRed) return null;
156
+ const at = `${a.branch}@${String(a.headSha).slice(0, 7)} (GitHub Actions)`;
157
+ const failing = listed.length
158
+ ? listed.map((x) => `${x.workflowName || 'run'} (${x.conclusion || 'none'})`).join(', ')
159
+ : `conclusion=${run.conclusion || 'none'}`;
160
+ return { ok: false, verdict: 'red', selfClearing: false,
161
+ detail: `${at} finished red — failing: ${failing}. A branch lands only on its own green (C7.contract.03): ` +
162
+ 'red:infra → re-run once; red:finding → send it back (code-ship B1a)' };
163
+ }
164
+
165
+ module.exports = { staleBaseVerdict, branchHeadCiVerdict, githubBranchHeadRedVerdict };