/ship reuses CI's passing run when a base merge changed no file, and stops before long local test runs or an unknown base (GST-3019) (#4461)

/ship's preflight and its CI-run lookup now reuse a passing CI test run
when a base merge left the files unchanged, stop instead of quietly
starting an hour-long test suite on the local machine, and refuse a
`--base` that names no commit instead of reporting an empty diff.

Why: gbrain #9662 lost a green CI run to a no-op base merge, then ran a
50-minute suite on a 4-CPU box, and its audit read a commit sha as a
branch and saw zero changed files.

Nothing to do: `--run-uncarried-here` restores running an uncovered
suite locally under `--tests-only`.

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>
Review-Finding: s11/outside-voice#1 reader=outside-voice
Review-Finding: s11/outside-voice#2 reader=outside-voice
This commit is contained in:
Garry Tanandcapy-ai[bot] authored and GitHub committed 2026-11-17 20:56:07 +00:00
1 parent 76535826f5
commit da98d0a0eb
18 files changed
+354 -45

No files matched your search

+10 -5
View File
@@ -9,13 +9,15 @@
* find: the newest verified run of each profile (default: every profile the base branch's
* ship_lanes_from names) at HEAD's clean tree. With --command, the base branch's mapping for that exact lane
* command supplies the profiles and the inventory the runs must cover (a pin-file command, so it needs
* --allow-repo-commands). Prints CI_CARRY: accepted <receipt> (exit 0) or CI_CARRY: none (<reason>) (exit 1).
* --allow-repo-commands). Prints CI_CARRY: accepted <receipt> (exit 0) or CI_CARRY: none (<reason>) (exit 1). A run at
* one of HEAD's ancestors whose tree git reads as HEAD's (a base merge that changed no file) carries too, and CI_CARRY_FROM
* names that run and commit (GST-3019).
* wait: polls the newest run of the profile's workflow at HEAD (REST, at least 60 s apart) until it completes (default timeout 1800 s),
* prints CI_WAIT: green|red|running|none, and on green runs find. Exit 0 green and carried, 1 red or not
* carried, 3 still running or no run. Logic: lib/ci-carry.ts; the run checks are lib/run-evidence.ts.
*/
import { spawnSync } from 'node:child_process';
import { findCarry, laneMapping, mappingCoverage, waitForRun } from '../lib/ci-carry';
import { carriedFromLine, findCarry, laneMapping, mappingCoverage, treeTwins, waitForRun } from '../lib/ci-carry';
import { isConfigUnavailable, loadConfigFromBase, loadConfigFromHead } from '../lib/pregate/config';
import { buildRunCheck } from '../lib/pregate/run-check';
import { wtreeFingerprint } from '../lib/script-invocation';
@@ -24,11 +26,12 @@ import { resolveBaseBranch } from '../lib/ship-policy';
const HELP = `gstack-ci-carry — use a verified CI run at HEAD's exact tree instead of running the suite again (docs/pregate.md#ci-carry)
find [--base <branch>] [--profile <name>]... [--command <exact lane command> --allow-repo-commands] [--json]
CI_CARRY: accepted <receipt> (exit 0) or CI_CARRY: none (<reason>) (exit 1)
CI_CARRY: accepted <receipt> (exit 0) or CI_CARRY: none (<reason>) (exit 1); a run at an earlier commit with
HEAD's exact tree (git rev-parse <sha>^{tree}) carries too, and CI_CARRY_FROM: names that run and commit
--policy-from head --simulate: the same check under the branch's own map and profiles, every line starting
SIMULATION:; a dry run that proves a new mapping before it lands (find never writes evidence; nothing clears)
wait [--base <branch>] [--profile <name>] [--timeout <s>] [--interval <s>]
poll the newest run at HEAD (default 1800 s, every 60 s at least, plus jitter): CI_WAIT: green|red|running|none, then find on green;
poll the newest run at HEAD or an earlier commit with its tree (default 1800 s, every 60 s at least, plus jitter): CI_WAIT: green|red|running|none, then find on green;
exit 0 carried, 1 red or not carried, 3 still running or no run
Profiles and ship_lanes_from come from origin/<base>'s .gstack/pregate.json only (a simulation reads the branch's). Only a clean, committed tree
@@ -70,6 +73,8 @@ function find(): number {
const v = findCarry(check as Exclude<typeof check, { error: string }>, { profiles, head, tree, wtree, ...(mapping ? mappingCoverage(mapping, root) : {}) });
if (argv.includes('--json')) out(JSON.stringify(v));
else out(v.ok ? `CI_CARRY: accepted ${v.receipt}` : `CI_CARRY: none (${v.reason}: ${v.detail})`);
const from = v.ok && !argv.includes('--json') ? carriedFromLine(v.runs, head) : undefined;
if (from) out(from);
return v.ok ? 0 : 1;
}
@@ -79,6 +84,6 @@ const interval = Number(flag('--interval') ?? '60');
if (!(timeout >= 0 && timeout <= 21_600) || !(interval >= 1 && interval <= 600)) usage('--timeout is 0-21600 seconds and --interval 1-600');
const profile = check.profiles[profiles[0]!];
if (!profile) usage(`${profiles[0]} is not a run_profiles name on origin/${base}`);
const w = await waitForRun(check.deps, { workflow: profile!.workflow, events: profile!.events, head, timeoutMs: timeout * 1000, intervalMs: interval * 1000, sleep: ms => Bun.sleep(ms), clock: Date.now });
const w = await waitForRun(check.deps, { workflow: profile!.workflow, events: profile!.events, head, also: treeTwins(check.deps, head, tree), timeoutMs: timeout * 1000, intervalMs: interval * 1000, sleep: ms => Bun.sleep(ms), clock: Date.now });
out(`CI_WAIT: ${w.state} ${profiles[0]} ${'run' in w ? `run=${w.run.id}/${w.run.run_attempt}${w.state === 'red' ? ` failing=${w.failing.join(',') || '-'}` : ''}` : w.reason}`);
process.exit(w.state === 'green' ? find() : w.state === 'red' ? 1 : 3);
+5 -1
View File
@@ -100,7 +100,7 @@ import { resultLine } from "../lib/result-codes";
import { isUnavailable, loadPolicyFromBase, resolveBaseBranch } from "../lib/ship-policy";
import { versionAtRef } from "../lib/restamp";
import { bashCommandInvocation, runScriptSync, wtreeFingerprint } from "../lib/script-invocation";
import { findCarry, laneMapping, mappingCoverage, perFileCommand } from "../lib/ci-carry";
import { carriedFromLine, findCarry, laneMapping, mappingCoverage, perFileCommand } from "../lib/ci-carry";
import { DEFAULT_MAX_AGE_HOURS, runChanged } from "../lib/run-evidence";
import { isConfigUnavailable, loadConfigFromBase } from "../lib/pregate/config";
import { buildRunCheck } from "../lib/pregate/run-check";
@@ -806,6 +806,8 @@ async function cmdRecordCi(argv: string[]): Promise<number> {
if (prior) {
console.error(recordedCiLine(prior));
if (prior.not_owed) console.error(`gstack-evidence: not owed: ${prior.not_owed}`);
const priorFrom = carriedFromLine(v.runs, head);
if (priorFrom) console.error(priorFrom);
console.error(`CI_RECORD_REUSED: label=${label} runs=${runs.join(",")} tree=${tree.slice(0, 12)} policy=${loaded.label} (the ledger's CI row for this exact tree, run and selection; nothing ran here)`);
return 0;
}
@@ -870,6 +872,8 @@ async function cmdRecordCi(argv: string[]): Promise<number> {
appendJsonl(paths.file, rec, { mode: 0o600 });
console.error(recordedCiLine(rec));
if (v.notOwed) console.error(`gstack-evidence: not owed: ${v.notOwed}`);
const from = carriedFromLine(v.runs, head);
if (from) console.error(from);
if (exception) console.error(`TEST_LANE_EXCEPTION: ${testLaneExceptionText(exception)}`);
return 0;
}
@@ -0,0 +1 @@
- **/ship reuses CI's passing test run when merging the base changed no file, and stops instead of quietly starting hour-long test runs or reviewing an empty diff (GST-3019).** When git reads a commit's file tree as identical to an earlier commit's, a passed CI run of the earlier commit now counts for it, under the same workflow, command and freshness rules, and the output names the commit and run it used. `gstack-ship-preflight --tests-only` now stops with `SHIP_LANE_NOT_CARRIED` and the CI command to run when a mapped test suite has no passing CI run to reuse, instead of running it on this machine (`--run-uncarried-here` still runs it). `--audit --base <commit sha>` now diffs against that commit, and a base that names no commit stops with `SHIP_BASE_UNKNOWN` instead of reporting zero changed files.
+15 -1
View File
@@ -1075,6 +1075,17 @@ it accepts a run only when all of these hold:
running run on HEAD, within `max_age_hours`, and a `tree.json` naming HEAD's
tree. A `pull_request` run counts only when the pull request already
contained its base.
- <a id="same-tree-commits"></a>HEAD's runs include those of its newest
ancestors (up to 20 back) whose tree `git rev-parse <sha>^{tree}` reads as
HEAD's own, so a base merge that changed no file keeps the green run of the
commit before it (GST-3019). Git decides which commits those are; a run's
own `tree.json` never does. Every rule above still applies to that run, and
a newer red or running run on HEAD or on any of those commits vetoes it.
`gstack-ci-carry find` then prints `CI_CARRY_FROM: run <id>/<attempt> at
commit <sha>, not HEAD <sha>; git rev-parse reads the same tree <tree> for
both`, a Step 5 lane reads `LANE: <label> carried run=… from=<sha> (same
tree as HEAD)`, and the receipt's `heads=` names that commit.
`gstack-ci-carry wait` watches those commits' runs too.
- Every run executed tests, and with an inventory command, the runs'
`tree.json` files cover every file it prints, none of them a file whose every
test skipped there (`skipped_files`). A lane mapped by `jobs`
@@ -1295,7 +1306,10 @@ with every character outside `A-Za-z0-9._-` turned into `_` (`pnpm lint` is
`pnpm_lint`, `db:test` is `db_test`), and `run`, `record-ci` and `check` all
use that one spelling, so `check --label 'pnpm lint'` finds the row; `ci_carried`
and `CI_CARRIED:` name the stored spelling. A mapped lane that cannot
carry prints `CI_CARRY: none label=<label> (<reason>)` and runs here. Every
carry prints `CI_CARRY: none label=<label> (<reason>)` and runs here, except
under `gstack-ship-preflight --tests-only`, which stops before any lane runs
with [`SHIP_LANE_NOT_CARRIED`](troubleshooting.md#ship-lane-not-carried) unless
it is given `--run-uncarried-here`. Every
other lane runs through `gstack-evidence run --reuse`: the newest row for its
label, command and working tree is reused when it passed with a counted run
under the same runtime (bun and node versions, OS, architecture, runner image)
+13
View File
@@ -1291,6 +1291,19 @@ which carry the workflow consequences the skill prose would otherwise spell out:
| `ship: review_scope …` | Step 9.4 item 0 runs `gstack-review-scope classify` on each pass's findings; see [review_scope](#review-scope) |
| `ship: changelog_fragments <dir>: …` | Step 12 writes no version; Step 13 writes the entry as `<dir>/<branch-slug>.md` (entry text only, `bump:` front matter only when the change warrants more than the policy bump), never an `[Unreleased]` section, linted with `gstack-prose-lint <file> --gate`; `gstack-ship-queue land` assigns the version; see [changelog fragments](#changelog-fragments) |
<a id="preflight-result-codes"></a>
`gstack-ship-preflight` stops with a named code where a quiet fallback would cost
an hour or hide an empty diff (GST-3019):
| Code | When | Next |
|---|---|---|
| `SHIP_LANE_NOT_CARRIED` | `--tests-only` was given a lane `ship_lanes_from` maps, and no verified CI run carries it at this tree. Nothing runs, not even the other lanes. | Push, dispatch the workflow the `NEXT:` line names, `gstack-ci-carry wait`, rerun; or rerun with `--run-uncarried-here` to run it here. A full preflight still runs a lane that does not carry. [Troubleshooting](troubleshooting.md#ship-lane-not-carried) |
| `SHIP_BASE_UNKNOWN` | `--audit --base <base>` resolves to no commit: a sha-like value is tried as a commit first, then `origin/<base>`. | Fetch the base branch or the commit, then rerun. [Troubleshooting](troubleshooting.md#ship-base-unknown) |
A lane carries from a run at an earlier commit when git reads that commit's tree as HEAD's (a base merge
that changed no file); the LANE line names it as `from=<sha> (same tree as HEAD)`. See
[same-tree commits](pregate.md#same-tree-commits).
The ship receipt (`gstack-ship-receipt write … --body`) goes in the PR body's closing Agent notes
section, written by the pr-body section of `/ship` after the body is composed. A body from before that
layout keeps its receipt at the top. That receipt is still read while it opens the body, also after the
+44
View File
@@ -725,6 +725,50 @@ before the fetch instead of going on unprotected.
**Fix.** Do what the parenthesized `gstack-lease` line names (wait for the
process holding `<git dir>/gstack-leases/.lock`), then rerun.
<a id="ship-lane-not-carried"></a>
### `STOP: SHIP_LANE_NOT_CARRIED: lane <label> did not carry from a verified CI run at this tree, and --tests-only never starts a lane on its own ...`
**Meaning.** `gstack-ship-preflight --tests-only` was given a lane whose exact
command `origin/<base>`'s `.gstack/pregate.json` maps in `ship_lanes_from`,
and no verified CI run carries it at this tree: the `CI_CARRY: none
label=<label> (<reason>)` line above the STOP says why (`no_run`: CI has not
run this tree yet; `dirty_tree`: uncommitted work). A mapped lane is the full
suite, which can take most of an hour on a small machine (gbrain #9662: a
50-minute unit lane on 4 CPUs), so `--tests-only` no longer starts it on its
own (GST-3019).
**What is kept.** Nothing ran: no lane, mapped or not, started. The pregate
line above it is the pregate's own verdict.
**Fix.** Follow the `NEXT:` lines. Commit and push the tree, dispatch the
workflow they name (`gh workflow run <workflow> --ref <branch>`), wait with
`gstack-ci-carry wait --base <base>`, and once it prints `CI_WAIT: green`
rerun the same `--tests-only` command, which then carries the lane. To run the
lane on this machine instead, rerun with `--run-uncarried-here`.
**Expected result.** `LANE: <label> carried run=<id>/<attempt> …`, or with
`--run-uncarried-here`, `LANE: <label> pass …` from the run here.
<a id="ship-base-unknown"></a>
### `STOP: SHIP_BASE_UNKNOWN: --base <base> names no commit here ...`
**Meaning.** `gstack-ship-preflight --audit --base <base>` could not resolve
the base to a commit. A value that looks like a commit sha (7 to 64 hex
characters) is tried as a commit this checkout holds first, then
`origin/<base>`. Before GST-3019 a sha was read as `origin/<sha>`, which
resolved to nothing and printed `CONTEXT: … files=0`, an empty diff that
looked like a branch with no changes.
**What is kept.** Nothing ran: no diff, commit list, coverage map or plan
lookup was written.
**Fix.** Pass the base branch name after `git fetch origin
+refs/heads/<name>:refs/remotes/origin/<name>`, or a commit sha this checkout
holds (`git fetch origin <sha>` first when it does not), then rerun.
**Expected result.** `CONTEXT: diff=… files=<n> commits=<n>` for the diff
against that base.
<a id="review-fingerprint-tmpdir"></a>
### `gstack-wtree: cannot create a temp index under <dir>; set TMPDIR to a writable directory` / `gstack-review-log: cannot create a private object directory under <dir>; no working-tree fingerprint. Set TMPDIR to a writable directory.`
+40 -13
View File
@@ -4,8 +4,9 @@
* they use it instead of running the suite again.
*
* `findCarry` looks up the newest verified run of each named run profile (the
* base branch's `.gstack/pregate.json` `run_profiles`) for HEAD and accepts it
* only when every rule holds:
* base branch's `.gstack/pregate.json` `run_profiles`) for HEAD, or for one of
* HEAD's newest ancestors whose tree git reads as HEAD's own (a base merge that
* changed no file, GST-3019; treeTwins), and accepts it only when every rule holds:
*
* the working tree is HEAD's committed tree (gstack-wtree), before and after
* the lookup, so admitted dirty or untracked work never carries;
@@ -23,7 +24,7 @@
* suite as before. Security and advisory scans and the sealed guard are never
* carried: callers carry test lanes only.
*
* waitForRun polls the newest run of one workflow on HEAD (REST) until it
* waitForRun polls the newest run of one workflow on HEAD (and `also`, the commits with its tree) (REST) until it
* completes, at least 60 s apart (lib/gh-poll.ts), bounded by a timeout, and
* returns green, red with the failing jobs, still running, or none.
*/
@@ -47,17 +48,40 @@ export type CarryVerdict = { ok: true; runs: RunEvidence[]; tests: number | 'n/a
/** How many of HEAD's runs per workflow are tried, newest first. */
const CANDIDATES = 10;
/** How many of HEAD's newest ancestors are read for a commit with HEAD's exact tree. */
const TWIN_DEPTH = 20;
const no = (reason: CarryRefusal, detail: string): CarryRefused => ({ ok: false, reason, detail });
const newestFirst = (a: ApiRun, b: ApiRun) => (b.created_at ?? '').localeCompare(a.created_at ?? '') || b.id - a.id;
/** The newest run of `profile` on `head` that verifies; a refusal lists each candidate's reason, newest first. */
function newestVerified(src: RunSource, name: string, profile: RunProfile, head: string, jobs: string[]): { ok: true; evidence: RunEvidence } | CarryRefused {
/**
* The commits among HEAD's newest ancestors whose tree git reads as `tree` (a base merge that changed no file, GST-3019), newest
* first, HEAD itself left out. Each is checked with git rev-parse <sha>^{tree}; a run's own record never makes a commit one of these.
*/
export function treeTwins(deps: RunDeps, head: string, tree: string): string[] {
return (deps.ancestors?.(head, TWIN_DEPTH) ?? []).filter(sha => sha !== head && deps.commitTree(sha) === tree);
}
/** The line naming each carried run that ran at a commit other than HEAD, or undefined when every run ran at HEAD. */
export function carriedFromLine(runs: RunEvidence[], head: string): string | undefined {
const away = runs.filter(e => e.head_sha !== head);
if (!away.length) return undefined;
return `CI_CARRY_FROM: ${away.map(e => `run ${e.run_id}/${e.run_attempt} at commit ${e.head_sha.slice(0, 12)}`).join('; ')}, not HEAD ${head.slice(0, 12)}; git rev-parse reads the same tree ${away[0]!.tree.slice(0, 12)} for both`;
}
/**
* The newest run of `profile` on `heads` (HEAD, then the commits with its exact tree) that verifies; a refusal lists each
* candidate's reason, newest first. A newer red or running run on any of them vetoes. A docs-only skipped run at another
* commit is owed nothing only when HEAD itself is docs-only against the base too.
*/
function newestVerified(src: RunSource, name: string, profile: RunProfile, heads: string[], jobs: string[]): { ok: true; evidence: RunEvidence } | CarryRefused {
if (jobs.length) profile = { ...profile, jobs: [...new Set([...profile.jobs, ...jobs])] };
const listed = src.deps.runsForHead(profile.workflow, head).filter(r => profile.events.includes(r.event)).sort(newestFirst).slice(0, CANDIDATES);
if (!listed.length) return no('no_run', `no ${profile.workflow} run (${profile.events.join(', ')}) on ${head.slice(0, 12)} yet`);
const listed = heads.flatMap(h => src.deps.runsForHead(profile.workflow, h)).filter(r => profile.events.includes(r.event)).sort(newestFirst).slice(0, CANDIDATES);
const twins = heads.slice(1).map(h => h.slice(0, 12));
if (!listed.length) return no('no_run', `no ${profile.workflow} run (${profile.events.join(', ')}) on ${heads[0]!.slice(0, 12)}${twins.length ? ` or on ${twins.join(', ')}, which git reads as the same tree` : ''} yet`);
const refusals: string[] = [];
const docsOnly = src.docsOnly && ((sha: string) => src.docsOnly!(sha) && (sha === heads[0] || src.docsOnly!(heads[0]!)));
for (const run of listed) {
const v = verifyRun(src.deps, { repo: src.repo, runRef: String(run.id), profileName: name, profile, vetoHeads: [head], now: src.now, unchanged: src.unchanged, docsOnly: src.docsOnly });
const v = verifyRun(src.deps, { repo: src.repo, runRef: String(run.id), profileName: name, profile, vetoHeads: heads, now: src.now, unchanged: src.unchanged, docsOnly });
if (v.ok) return v;
refusals.push(`run ${run.id}: ${v.reason}${v.fix ? ` (the pull request's base moved after the run; fix: ${v.fix})` : ''}`);
}
@@ -84,10 +108,11 @@ export function findCarry(src: RunSource, o: { profiles: string[]; head: string;
if (!o.profiles.length) return no('no_profile', 'no run profile is named');
const runs: RunEvidence[] = [];
try {
const heads = [o.head, ...treeTwins(src.deps, o.head, o.tree)];
for (const name of o.profiles) {
const profile = src.profiles[name];
if (!profile) return no('no_profile', `${name} is not a run_profiles name on the base branch`);
const v = newestVerified(src, name, profile, o.head, jobs);
const v = newestVerified(src, name, profile, heads, jobs);
if (!v.ok) return v;
runs.push(v.evidence);
}
@@ -147,10 +172,10 @@ const PASSING = ['success', 'skipped', 'neutral'];
* Poll the newest `workflow` run on `head` (among `events`) until it completes or `timeoutMs` passes; polls are at least 60 s
* apart, so the last poll can land up to one poll interval (75 s with jitter) after `timeoutMs`.
*/
export async function waitForRun(deps: RunDeps, o: { workflow: string; events: string[]; head: string; timeoutMs: number; intervalMs: number; sleep: (ms: number) => Promise<void>; clock: () => number; random?: () => number }): Promise<WaitVerdict> {
export async function waitForRun(deps: RunDeps, o: { workflow: string; events: string[]; head: string; also?: string[]; timeoutMs: number; intervalMs: number; sleep: (ms: number) => Promise<void>; clock: () => number; random?: () => number }): Promise<WaitVerdict> {
const end = o.clock() + o.timeoutMs;
for (;;) {
const newest = deps.runsForHead(o.workflow, o.head).filter(r => o.events.includes(r.event)).sort(newestFirst)[0];
const newest = [o.head, ...(o.also ?? [])].flatMap(h => deps.runsForHead(o.workflow, h)).filter(r => o.events.includes(r.event)).sort(newestFirst)[0];
if (newest?.status === 'completed') {
if (newest.conclusion === 'success') return { state: 'green', run: newest };
const failing = deps.jobs(newest.id, newest.run_attempt).filter(j => !PASSING.includes(j.conclusion ?? '')).map(j => j.name);
@@ -212,7 +237,7 @@ export function importedTestLines(cwd: string, missing: string[], candidates: st
* not-owed reason, or the last CARRY_NONE reason. A lane the cleared remote gate stood in for (--remote-gate-stands-in, GST-1688)
* reads as its receipt, its count and why the CI carry refused.
*/
export function recordCiResult(stderr: string): { runs?: string; tests?: string; files?: boolean; notOwed?: string; here?: string; exception?: string; reused?: string; none?: string; diagnosis?: string[]; remoteGate?: string; standIn?: string } {
export function recordCiResult(stderr: string): { runs?: string; tests?: string; files?: boolean; notOwed?: string; here?: string; exception?: string; reused?: string; from?: string; none?: string; diagnosis?: string[]; remoteGate?: string; standIn?: string } {
const lines = stderr.split('\n');
const last = lines.findLast(x => x.startsWith('gstack-evidence: recorded label='));
const gateRow = last && / tests_ran=(\d+) log=- source=remote_gate receipt=(.+)$/.exec(last);
@@ -227,7 +252,9 @@ export function recordCiResult(stderr: string): { runs?: string; tests?: string;
const here = / skipped_here=(\d+) tests_ran_here=(\S+)( not_owed_here=\d+)?$/.exec(lines[at]!);
const notOwed = lines.slice(at + 1).find(x => x.startsWith('gstack-evidence: not owed: '))?.slice('gstack-evidence: not owed: '.length);
const reused = lines.slice(at + 1).map(x => /^CI_RECORD_REUSED: .* tree=([0-9a-f]+) /.exec(x)?.[1]).find(Boolean);
return { runs: got?.[3], tests: got?.[1], files: !!got?.[2], ...(notOwed ? { notOwed } : {}), ...(here ? { here: `skipped_here=${here[1]} file(s) tests_ran_here=${here[2]}${here[3] ?? ''}` } : {}), ...(exception ? { exception } : {}), ...(reused ? { reused } : {}) };
const fromLine = lines.slice(at + 1).find(x => x.startsWith('CI_CARRY_FROM: '));
const from = fromLine ? [...new Set([...fromLine.matchAll(/ at commit ([0-9a-f]{12})/g)].map(m => m[1]!))].join(',') : '';
return { runs: got?.[3], tests: got?.[1], files: !!got?.[2], ...(notOwed ? { notOwed } : {}), ...(here ? { here: `skipped_here=${here[1]} file(s) tests_ran_here=${here[2]}${here[3] ?? ''}` } : {}), ...(exception ? { exception } : {}), ...(reused ? { reused } : {}), ...(from ? { from } : {}) };
}
/** The per_file runner command for `files`: `{files}` replaced by the paths, each anchored with ./ (Bun reads a bare relative path as a substring filter) and single-quoted for bash. */
+6
View File
@@ -72,6 +72,8 @@ export interface RunDeps {
/** The tree.json of the run's unexpired artifact `name`: the only one, or with one per rerun attempt of its job, the one that records run_attempt `attempt`. */
artifact(id: number, name: string, attempt: number): TreeRecord;
commitTree(sha: string): string | null;
/** `sha` and its ancestors, newest first, at most `max` (git rev-list): where a commit with `sha`'s exact tree is looked for (GST-3019). */
ancestors?(sha: string, max: number): string[];
}
export type RunRefusal = 'run_ref_invalid' | 'other_repository' | 'fork_run' | 'workflow_mismatch' | 'event_mismatch' | 'run_in_progress'
@@ -396,6 +398,10 @@ export function ghRunDeps(repo: string, repoRoot: string): RunDeps {
const tree = (r.stdout ?? '').trim();
return r.status === 0 && /^[0-9a-f]{40,64}$/.test(tree) ? tree : null;
},
ancestors: (sha, max) => {
const r = spawnSync('git', ['rev-list', `--max-count=${max}`, sha], { cwd: repoRoot, encoding: 'utf8', timeout: 30_000 });
return r.status === 0 ? (r.stdout ?? '').split('\n').filter(s => SHA.test(s)) : [];
},
};
}
+13 -2
View File
@@ -63,13 +63,24 @@ function planCandidates(cwd: string, fork: string, branch: string): string[] {
return found;
}
/**
* The commit --base names: a commit sha this checkout holds, tried first, else origin/<base>; null when neither resolves
* (GST-3019: --base <sha> was read as origin/<sha>, which diffed as files=0).
*/
export function resolveAuditBase(cwd: string, base: string): string | null {
const commit = (rev: string) => git(cwd, ['rev-parse', '--verify', '--quiet', `${rev}^{commit}`]).stdout.trim() || null;
return (/^[0-9a-f]{7,64}$/i.test(base) ? commit(base) : null) ?? commit(`refs/remotes/origin/${base}`);
}
export function audit(cwd: string, base: string, out: string): Report {
const r = new Report();
const fork = git(cwd, ['merge-base', `origin/${base}`, 'HEAD']).stdout.trim() || `origin/${base}`;
const resolved = resolveAuditBase(cwd, base);
if (!resolved) return r.stop(`SHIP_BASE_UNKNOWN: --base ${base} names no commit here (not a commit this checkout holds, and no origin/${base}); pass the base branch fetched into origin/<name>, or a commit sha after git fetch origin <sha>, then rerun (docs/troubleshooting.md#ship-base-unknown)`);
const fork = git(cwd, ['merge-base', resolved, 'HEAD']).stdout.trim() || resolved;
fs.mkdirSync(out, { recursive: true, mode: 0o700 });
const diff = git(cwd, ['diff', fork]).stdout;
const files = git(cwd, ['diff', '--name-only', fork]).stdout.split('\n').filter(Boolean);
const commits = git(cwd, ['log', '--oneline', `origin/${base}..HEAD`]).stdout;
const commits = git(cwd, ['log', '--oneline', `${resolved}..HEAD`]).stdout;
fs.writeFileSync(path.join(out, 'diff.patch'), diff, { mode: 0o600 });
fs.writeFileSync(path.join(out, 'commits.txt'), commits, { mode: 0o600 });
r.add(`CONTEXT: diff=${path.join(out, 'diff.patch')} bytes=${Buffer.byteLength(diff)} files=${files.length} commits=${commits.split('\n').filter(Boolean).length} log=${path.join(out, 'commits.txt')}`);
+20 -9
View File
@@ -184,7 +184,7 @@ export function laneConcurrency(mode: string | undefined, cpus = os.availablePar
return cpus <= 4 ? 1 : Infinity;
}
export interface LaneResult { label: string; exit: number | null; testsRan: string; log: string; carried?: string; reused?: string; carryNone?: string; diagnosis?: string[]; notOwed?: string; here?: string; exception?: string; remoteGate?: string; standIn?: string }
export interface LaneResult { label: string; exit: number | null; testsRan: string; log: string; carried?: string; from?: string; held?: true; reused?: string; carryNone?: string; diagnosis?: string[]; notOwed?: string; here?: string; exception?: string; remoteGate?: string; standIn?: string }
/** The base branch's `ship_lanes_from` entry for each lane whose command is a key or a declared alias, byte for byte (the ledger binds its sha256). */
export function mappedLanes(cwd: string, base: string, list: { label: string; command: string }[]): Map<string, ShipLaneMapping> {
@@ -205,7 +205,7 @@ export function carryLane(cwd: string, base: string, l: { label: string; command
const rec = bin(cwd, 'gstack-evidence', ['record-ci', '--label', l.label, '--base', base, '--remote-gate-stands-in', '--', l.command], timeoutS * 1000);
const got = recordCiResult(rec.stderr);
if (rec.status === 0 && got.remoteGate) return { label: l.label, exit: 0, testsRan: got.tests!, log: '-', remoteGate: got.remoteGate, standIn: got.standIn ?? 'not carried' };
if (rec.status === 0 && got.runs) return { label: l.label, exit: 0, testsRan: got.files ? `${got.tests} (files)` : got.tests!, log: '-', carried: got.runs, ...(got.notOwed ? { notOwed: got.notOwed } : {}), ...(got.here ? { here: got.here } : {}), ...(got.exception ? { exception: got.exception } : {}), ...(got.reused ? { reused: got.reused } : {}) };
if (rec.status === 0 && got.runs) return { label: l.label, exit: 0, testsRan: got.files ? `${got.tests} (files)` : got.tests!, log: '-', carried: got.runs, ...(got.notOwed ? { notOwed: got.notOwed } : {}), ...(got.here ? { here: got.here } : {}), ...(got.exception ? { exception: got.exception } : {}), ...(got.reused ? { reused: got.reused } : {}), ...(got.from ? { from: got.from } : {}) };
return { label: l.label, exit: null, testsRan: 'unknown', log: '-', carryNone: got.none ?? `record_failed: ${firstLine(rec.stderr)}`, ...(got.diagnosis ? { diagnosis: got.diagnosis } : {}) };
}
@@ -219,20 +219,30 @@ export function recordCiTimeout(policy: Record<string, any> | null, base: string
/**
* Run each lane, at most `concurrency` at a time; results keep the lanes' order. With `base`, a lane the base branch maps in
* `ship_lanes_from` is carried from a verified CI run at this exact tree when one exists. Every other lane runs through
* gstack-evidence run --reuse (a pass at this tree, command and runtime is reused; `reuse: false` forces a run).
* `ship_lanes_from` is carried from a verified CI run at this exact tree when one exists; every mapped lane's carry is
* decided before any lane runs. With `hold`, a mapped lane that does not carry stops the call: nothing runs, and every
* lane that did not carry comes back `held` (GST-3019: --tests-only never starts a long lane on its own). Under `hold`,
* gstack-ci-carry find checks every mapped lane read-only first, so a refusal stops before any lane's record-ci runs its
* per_file remainder or exception preflight here; only the refused lanes go to record-ci, for a cleared remote gate. Every other
* lane runs through gstack-evidence run --reuse (a pass at this tree, command and runtime is reused; `reuse: false` forces a run).
*/
export async function runLanes(cwd: string, list: { label: string; command: string }[], concurrency = Infinity, opts: { base?: string; reuse?: boolean } = {}): Promise<LaneResult[]> {
export async function runLanes(cwd: string, list: { label: string; command: string }[], concurrency = Infinity, opts: { base?: string; reuse?: boolean; hold?: boolean } = {}): Promise<LaneResult[]> {
const out: LaneResult[] = [];
const mapped = opts.base ? mappedLanes(cwd, opts.base, list) : new Map<string, ShipLaneMapping>();
const refused = list.map(l => !!opts.hold && mapped.has(l.label) && bin(cwd, 'gstack-ci-carry', ['find', '--base', opts.base!, '--command', l.command, '--allow-repo-commands']).status !== 0);
const carries = list.map((l, i) => (refused[i] ? carryLane(cwd, opts.base!, l) : null));
const done = (c: LaneResult | null) => !!(c?.carried || c?.remoteGate);
const held = () => list.map((l, i) => { const c = carries[i]; return c && done(c) ? c : { ...(c ?? { label: l.label, exit: null, testsRan: 'unknown', log: '-' }), held: true as const }; });
if (opts.hold && carries.some(c => c && !done(c))) return held();
for (const [i, l] of list.entries()) if (!carries[i] && mapped.has(l.label)) carries[i] = carryLane(cwd, opts.base!, l);
if (opts.hold && carries.some(c => c && !done(c))) return held();
let next = 0;
const worker = async () => {
while (next < list.length) {
const i = next++;
const l = list[i]!;
const m = mapped.get(l.label);
const carry = m ? carryLane(cwd, opts.base!, l) : null;
if (carry?.carried || carry?.remoteGate) { out[i] = carry; continue; }
const carry = carries[i];
if (carry && done(carry)) { out[i] = carry; continue; }
const r = await binAsync(cwd, 'gstack-evidence', ['run', ...(opts.reuse === false ? [] : ['--reuse']), '--label', l.label, '--', l.command]);
const rec = /gstack-evidence: recorded label=\S+ exit=(\S+) tests_ran=(\S+) log=(\S+)/.exec(r.stderr);
const reused = /gstack-evidence: reused label=\S+ tree=\S+ from=(\S+)/.exec(r.stderr)?.[1];
@@ -246,8 +256,9 @@ export async function runLanes(cwd: string, list: { label: string; command: stri
/** Step 5's lane verdict: a lane passes on its runner count, never exit 0 alone; a carried lane names its CI runs. */
export function laneLine(l: LaneResult): { line: string; ok: boolean } {
if (l.notOwed) return { line: `LANE: ${l.label} not owed: ${l.notOwed} run=${l.carried}`, ok: true };
if (l.carried) return { line: `LANE: ${l.label} carried run=${l.carried} tests_ran=${l.testsRan}${l.here ? ` ${l.here}` : ''}${l.reused ? ` (reused the CI record at tree ${l.reused})` : ''}`, ok: true };
if (l.carried) return { line: `LANE: ${l.label} carried run=${l.carried} tests_ran=${l.testsRan}${l.here ? ` ${l.here}` : ''}${l.from ? ` from=${l.from} (same tree as HEAD)` : ''}${l.reused ? ` (reused the CI record at tree ${l.reused})` : ''}`, ok: true };
if (l.remoteGate) return { line: `LANE: ${l.label} satisfied by remote_gate receipt=${l.remoteGate}`, ok: true };
if (l.held) return { line: `LANE: ${l.label} held: not run`, ok: false };
const zero = l.exit === 0 && l.testsRan === '0';
const state = l.exit !== 0 ? 'FAIL' : zero ? 'ZERO-RUN' : l.testsRan === 'unknown' ? 'pass (count unavailable)' : 'pass';
return { line: `LANE: ${l.label} ${state} exit=${l.exit} tests_ran=${l.testsRan} log=${l.log}${l.reused ? ` reused=${l.reused}` : ''}`, ok: l.exit === 0 && !zero };
+27 -8
View File
@@ -10,13 +10,13 @@ import * as os from 'node:os';
import * as path from 'node:path';
import { findCarry, laneMapping, mappingCoverage } from './ci-carry';
import { defaultBaseBranch } from './default-base';
import { isConfigUnavailable, loadConfigFromHead } from './pregate/config';
import { isConfigUnavailable, loadConfigFromBase, loadConfigFromHead } from './pregate/config';
import { buildRunCheck } from './pregate/run-check';
import { classifyDiff } from './review-depth';
import { wtreeFingerprint } from './script-invocation';
import { audit } from './ship-audit';
import { withGateLock } from './gate-dispositions';
import { bin, carryNoneLines, firstLine, flagReader, gh, git, hostedOrigin, laneConcurrency, laneLine, lanes, Report, runLanes, shipPolicy, shipRunMarker, short } from './ship-bin-common';
import { bin, carryNoneLines, firstLine, flagReader, gh, git, hostedOrigin, laneConcurrency, laneLine, lanes, mappedLanes, Report, runLanes, shipPolicy, shipRunMarker, short } from './ship-bin-common';
export const PREFLIGHT_HELP = `gstack-ship-preflight — /ship Steps 1-3 and Step 5's pregate and lanes in one call (ship/SKILL.md)
@@ -25,6 +25,8 @@ export const PREFLIGHT_HELP = `gstack-ship-preflight — /ship Steps 1-3 and Ste
this checkout's git dir and opened on its lease, and a later full preflight stops until finish
clears it or 120 minutes pass, because its merge would move the tree the run's readers diff (GST-1204)
gstack-ship-preflight --tests-only --base <base> --lane <label>=<command>... Step 5 only (after a repair)
--run-uncarried-here run a lane origin/<base> maps in ship_lanes_from here when its CI carry refuses; without it a refused
carry stops with SHIP_LANE_NOT_CARRIED before any lane runs, naming the CI dispatch (GST-3019)
--lanes serial|parallel how Step 5 runs its lanes; unset, one at a time on 4 or fewer cores, all at once above
--policy-from head Step 5's pregate reads the branch's .gstack/pregate.json, which may only add test lanes
(a branch that adds the lane for a file it touches); anything else is PREGATE_HEAD_POLICY_LOOSENS
@@ -37,13 +39,15 @@ export const PREFLIGHT_HELP = `gstack-ship-preflight — /ship Steps 1-3 and Ste
CI run at this tree. Every line starts SIMULATION:; no lane runs, no evidence or ledger row is written and no
obligation clears (a real carry reads origin/<base>'s map only). An inventory-mapped lane runs the branch's
inventory command, so it needs --allow-repo-commands. Exit 0 when every mapped lane would carry, else 1
gstack-ship-preflight --audit --base <base> --out <dir> the single reads and Steps 7-8's deterministic audits
gstack-ship-preflight --audit --base <base|commit sha> --out <dir> the single reads and Steps 7-8's deterministic audits;
a base that names no commit stops with SHIP_BASE_UNKNOWN instead of an empty diff
(CONTEXT, TODOS, COVERAGE_MAP, Coverage, PLAN_*, READER: coverage=needed|none plan=needed|none)
Prints at most 30 lines: BRANCH, STATUS, DIFF, PR/CARRY, APPLE, SCOPE, MERGE, DISTRIBUTION, POLICY,
RUNTIME_LINES, PREGATE (with up to three PREGATE_DETAIL lines when it does not pass), LANES, one LANE line per lane
(a lane the base maps in .gstack/pregate.json ship_lanes_from is carried from a verified CI run at this exact clean tree:
LANE: <label> carried run=<id>/<attempt> tests_ran=<n>, else CI_CARRY: none (<reason>) and it runs; any other lane that
LANE: <label> carried run=<id>/<attempt> tests_ran=<n>, else CI_CARRY: none (<reason>) and it runs, under --tests-only only with
--run-uncarried-here; any other lane that
passed at this tree, command and runtime is reused: reused=<original time>), then NEXT: lines. STOP: names what the agent must
decide or repair; nothing after it ran. Exit codes: 0 ok · 2 usage · 3 STOP`;
@@ -197,7 +201,7 @@ function merge(cwd: string, base: string, r: Report): boolean {
return true;
}
async function tests(cwd: string, base: string, list: { label: string; command: string }[], policyFrom: string, timeout: string | undefined, step: { seconds: number; source: string }, run: { concurrency: number; line: string }, r: Report): Promise<void> {
async function tests(cwd: string, base: string, list: { label: string; command: string }[], policyFrom: string, timeout: string | undefined, step: { seconds: number; source: string }, run: { concurrency: number; line: string; hold: boolean }, r: Report): Promise<void> {
const pg = bin(cwd, 'gstack-pregate', ['--allow-repo-commands', '--base', base, '--policy-from', policyFrom, ...(timeout ? ['--timeout', timeout] : [])], step.seconds * 1000);
if (pg.timedOut) {
r.add(`PREGATE: time limit hit (Step 5's whole pregate ran past its ${step.seconds} s budget, ${step.source}, and was stopped with exit ${pg.status ?? 'none'}; no verdict)`);
@@ -214,9 +218,22 @@ async function tests(cwd: string, base: string, list: { label: string; command:
}
if (/uncleared/.test(verdict)) r.next('pregate requires-remote: gstack-pregate clear, or --remote --spend-cap <usd> under a user cap, before Step 18');
r.add(run.line);
const ran = await runLanes(cwd, list, run.concurrency, { base });
const ran = await runLanes(cwd, list, run.concurrency, { base, hold: run.hold });
const results = ran.map(laneLine);
for (const [i, l] of results.entries()) { for (const none of carryNoneLines(ran[i]!)) r.add(none); r.add(l.line); }
const refused = ran.filter(l => l.held && l.carryNone);
if (refused.length) {
const names = refused.map(l => l.label).join(', ');
const lane = `lane${refused.length > 1 ? 's' : ''} ${names}`;
const loaded = loadConfigFromBase(cwd, base);
const mapped = mappedLanes(cwd, base, list);
const workflows = isConfigUnavailable(loaded) ? [] : [...new Set(refused.flatMap(l => mapped.get(l.label)?.profiles ?? []).map(p => loaded.config.run_profiles?.[p]?.workflow).filter((w): w is string => !!w))];
const branch = git(cwd, ['branch', '--show-current']).stdout.trim() || '<branch>';
r.stop(`SHIP_LANE_NOT_CARRIED: ${lane} did not carry from a verified CI run at this tree, and --tests-only never starts a lane on its own: nothing ran here (docs/troubleshooting.md#ship-lane-not-carried)`);
r.next(`commit and push this tree, then ${workflows.length ? workflows.map(w => `gh workflow run ${w} --ref ${branch}`).join(' and ') : 'run its CI workflow on the branch'} and gstack-ci-carry wait --base ${base}; once it prints CI_WAIT: green, rerun this command`);
r.next(`or rerun this command with --run-uncarried-here to run ${lane} on this machine`);
return;
}
const bad = results.filter(l => !l.ok);
if (bad.length) { r.stop(`${bad.length} lane(s) failed or ran zero tests: Step 5 triage (read each log; a free-suite shard failure reruns its file list per measure.md); in-branch failures stop the ship`); return; }
r.next('Step 6: select eval suites for prompt-related changes with the project\'s selector, then Step 7');
@@ -264,7 +281,8 @@ export async function preflight(argv: readonly string[], cwd: string): Promise<{
if (has('--audit')) {
const out = flag('--out');
if (!base || !out) return { text: 'gstack-ship-preflight: --audit needs --base <base> --out <dir>\n', exit: 2 };
return { text: audit(cwd, base, out).render(), exit: 0 };
const r = audit(cwd, base, out);
return { text: r.render(), exit: r.exit };
}
const policyFrom = flag('--policy-from') ?? 'base';
if (!['base', 'head'].includes(policyFrom)) return { text: 'gstack-ship-preflight: --policy-from needs base|head\n', exit: 2 };
@@ -277,13 +295,14 @@ export async function preflight(argv: readonly string[], cwd: string): Promise<{
const run = flag('--run');
if (has('--run') && !(run && RUN_ID.test(run))) return { text: 'gstack-ship-preflight: --run needs a run id: letters, digits, dot, underscore or dash, at most 128\n', exit: 2 };
if (has('--tests-only') && !list.length) return { text: 'gstack-ship-preflight: --tests-only needs at least one --lane <label>=<command>\n', exit: 2 };
if (has('--run-uncarried-here') && !has('--tests-only')) return { text: 'gstack-ship-preflight: --run-uncarried-here goes with --tests-only (a full preflight runs a lane that does not carry here)\n', exit: 2 };
if (has('--simulate')) return has('--tests-only') && policyFrom === 'head' && list.length ? simulate(cwd, base, list, has('--allow-repo-commands')) : { text: 'gstack-ship-preflight: --simulate needs --tests-only --policy-from head and at least one --lane <label>=<command>\n', exit: 2 };
const mode = flag('--lanes');
const concurrency = has('--lanes') && mode === undefined ? '--lanes needs serial or parallel' : laneConcurrency(mode);
if (typeof concurrency === 'string') return { text: `gstack-ship-preflight: ${concurrency}\n`, exit: 2 };
const r = new Report();
if (has('--tests-only') || integrate(cwd, base, run, r)) {
if (list.length) await tests(cwd, base, list, policyFrom, timeout, step, { concurrency, line: `LANES: ${concurrency === 1 ? 'serial' : 'parallel'} (${mode ? '--lanes' : `${os.availableParallelism()} cores`})` }, r);
if (list.length) await tests(cwd, base, list, policyFrom, timeout, step, { concurrency, line: `LANES: ${concurrency === 1 ? 'serial' : 'parallel'} (${mode ? '--lanes' : `${os.availableParallelism()} cores`})`, hold: has('--tests-only') && !has('--run-uncarried-here') }, r);
else if (r.exit === 0) r.next('Step 4: confirm the test framework, then rerun with --tests-only --lane <label>=<command> per suite (Step 5)');
}
return { text: r.render(), exit: r.exit };
+2 -1
View File
@@ -234,7 +234,8 @@ merge-check code: `lib/ship-*`, `lib/pregate/*`, the ship and pregate bins,
(`gstack-post pr-create --base <base> --draft --title-file <f> --body-file <f>`), then `gstack-ci-carry wait` in
the background; once it prints `CI_WAIT: green`, rerun `--tests-only` and the mapped lane is carried. A red
run is a failed lane: triage it below. Batch review fixes into one commit and one push. `CI_CARRY: none
label=<l> (<reason>)` names why a mapped lane ran here. A docs-only change ([docs/pregate.md#docs-only](../../docs/pregate.md#docs-only)) owes no test lane: pregate runs
label=<l> (<reason>)` names why a mapped lane did not carry; under `--tests-only` that is `STOP: SHIP_LANE_NOT_CARRIED` before
any lane runs: dispatch CI and wait as its `NEXT:` lines say, or rerun with `--run-uncarried-here` to run the lane here. A docs-only change ([docs/pregate.md#docs-only](../../docs/pregate.md#docs-only)) owes no test lane: pregate runs
the docs lane, and a mapped lane prints `LANE: <label> not owed: docs-only change …` from CI's skipped run. Any other lane that already passed at this
tree, command and runtime is reused (`reused=<time>`). In Step 16, `finish` defers a mapped
lane it cannot carry (`EVIDENCE: DEFERRED`); after Step 17's push, `gstack-ship-release accept --base <base>
+2 -1
View File
@@ -30,7 +30,8 @@ merge-check code: `lib/ship-*`, `lib/pregate/*`, the ship and pregate bins,
(`gstack-post pr-create --base <base> --draft --title-file <f> --body-file <f>`), then `gstack-ci-carry wait` in
the background; once it prints `CI_WAIT: green`, rerun `--tests-only` and the mapped lane is carried. A red
run is a failed lane: triage it below. Batch review fixes into one commit and one push. `CI_CARRY: none
label=<l> (<reason>)` names why a mapped lane ran here. A docs-only change ([docs/pregate.md#docs-only](../../docs/pregate.md#docs-only)) owes no test lane: pregate runs
label=<l> (<reason>)` names why a mapped lane did not carry; under `--tests-only` that is `STOP: SHIP_LANE_NOT_CARRIED` before
any lane runs: dispatch CI and wait as its `NEXT:` lines say, or rerun with `--run-uncarried-here` to run the lane here. A docs-only change ([docs/pregate.md#docs-only](../../docs/pregate.md#docs-only)) owes no test lane: pregate runs
the docs lane, and a mapped lane prints `LANE: <label> not owed: docs-only change …` from CI's skipped run. Any other lane that already passed at this
tree, command and runtime is reused (`reused=<time>`). In Step 16, `finish` defers a mapped
lane it cannot carry (`EVIDENCE: DEFERRED`); after Step 17's push, `gstack-ship-release accept --base <base>
+47
View File
@@ -79,6 +79,53 @@ describe('findCarry', () => {
});
});
describe('GST-3019: a run at another commit whose tree git reads as HEAD\'s carries', () => {
const TWIN = 'c'.repeat(40);
const ELSE = 'e'.repeat(40);
const twins = (runs: ApiRun[], records: Record<number, TreeRecord>, trees: Record<string, string> = { [HEAD]: TREE, [TWIN]: TREE, [ELSE]: 'f'.repeat(40) }): RunSource => {
const src = source(runs, records);
return { ...src, deps: { ...src.deps, commitTree: sha => trees[sha] ?? null, ancestors: (sha, max) => [sha, TWIN, ELSE].slice(0, max) } };
};
const atTwin = (id: number, over: Partial<ApiRun> = {}) => run(id, { head_sha: TWIN, ...over });
const recTwin = (id: number, over: Partial<TreeRecord> = {}) => record(id, { sha: TWIN, ...over });
// Value: protects=a base merge that changed no file keeps the green CI run of the commit before it (gbrain #9662: 0dc0d1d had 5840295's tree 369fa767 and carried nothing);
// fails_when=only runs on HEAD's own sha are listed, or the carried run's commit is not the one git read; why_new=GST-3019; seam=RunDeps.ancestors and commitTree
test('a green run of the same workflow at an ancestor with HEAD\'s tree carries, and the evidence names that commit', () => {
const v = carry(twins([atTwin(4)], { 4: recTwin(4) }), { inventory: () => ['test/a.test.ts', 'test/b.test.ts'] });
expect(why(v)).toBe('ok');
if (!v.ok) return;
expect(v.runs.map(e => [e.run_id, e.head_sha, e.tree])).toEqual([[4, TWIN, TREE]]);
expect(v.receipt).toContain(`runs=4/1 profiles=ci-reuse/free-tests heads=${TWIN.slice(0, 12)} `);
const both = carry(twins([atTwin(4), run(5)], { 4: recTwin(4), 5: record(5) }));
expect(both.ok && both.runs.map(e => [e.run_id, e.head_sha])).toEqual([[5, HEAD]]);
});
// Value: protects=tree identity comes from git, and every other carry rule still holds at the other commit; fails_when=a different tree, a failed or cancelled run,
// another workflow, or a newer red run at HEAD carries; why_new=GST-3019 negative controls; seam=verifyRun
test('negative controls: another tree, a failed or cancelled run, another workflow and a newer red run at HEAD never carry', () => {
expect(why(carry(twins([run(4, { head_sha: ELSE })], { 4: record(4, { sha: ELSE, tree: TREE }) })))).toBe('no_run');
expect(why(carry(twins([atTwin(4)], { 4: recTwin(4) }, { [HEAD]: TREE, [TWIN]: 'd'.repeat(40) })))).toBe('no_run');
const failed = carry(twins([atTwin(4, { conclusion: 'failure' })], { 4: recTwin(4) }));
expect([why(failed), failed.ok ? '' : failed.detail]).toEqual(['no_verified_run', expect.stringContaining('run 4: run_not_success')]);
const cancelled = carry(twins([atTwin(4, { conclusion: 'cancelled' })], { 4: recTwin(4) }));
expect([why(cancelled), cancelled.ok ? '' : cancelled.detail]).toEqual(['no_verified_run', expect.stringContaining('run 4: run_not_success')]);
const other = carry(twins([atTwin(4, { path: '.github/workflows/other.yml' })], { 4: recTwin(4) }));
expect([why(other), other.ok ? '' : other.detail]).toEqual(['no_verified_run', expect.stringContaining('run 4: workflow_mismatch')]);
const vetoed = carry(twins([atTwin(4), run(6, { conclusion: 'failure' })], { 4: recTwin(4), 6: record(6) }));
expect([why(vetoed), vetoed.ok ? '' : vetoed.detail]).toEqual(['no_verified_run', expect.stringContaining('run 4: newer_run_vetoes')]);
expect(why(carry(twins([atTwin(4)], { 4: recTwin(4, { tree: 'd'.repeat(40) }) })))).toBe('no_verified_run');
});
// Value: protects=gstack-ci-carry wait sees the green run at the commit with HEAD's tree instead of waiting out its timeout; fails_when=wait reads HEAD's sha alone;
// why_new=GST-3019; seam=waitForRun
test('waitForRun reads runs at the commits with HEAD\'s tree too', async () => {
const src = twins([atTwin(4)], { 4: recTwin(4) });
const w = await waitForRun(src.deps, { workflow: 'free-tests.yml', events: ['workflow_dispatch'], head: HEAD, also: [TWIN], timeoutMs: 0, intervalMs: 60_000, sleep: async () => {}, clock: () => 0 });
expect(w.state === 'green' && w.run.id).toBe(4);
});
});
describe('waitForRun', () => {
const clockAt = () => { let t = 0; return { clock: () => t, sleep: async (ms: number) => { t += ms; } }; };
// Value: protects=the bounded wait reports green, red with failing jobs, still running and none; fails_when=it waits forever or calls a red run green
+14
View File
@@ -55,3 +55,17 @@ test('a run whose gate job failed never counts its skipped suites', () => {
const v = verifyRun(failed, { repo: REPO, runRef: '7', profileName: 'ci-reuse/free-tests', profile: PROFILE, now: NOW, unchanged: () => null, docsOnly: () => true });
expect(v.ok ? 'ok' : v.reason).toBe('job_skipped');
});
// Value: protects=a docs-only skipped run at a commit with HEAD's tree (GST-3019) carries as not owed only when HEAD itself is docs-only;
// fails_when=the ancestor's classification exempts a HEAD whose base merge changed runtime code against the new base; why_new=GST-3019 review; seam=RunDeps.ancestors
test('a docs-only run at a same-tree ancestor carries only when HEAD is docs-only too', () => {
const TWIN = 'c'.repeat(40);
const atTwin: ApiRun = { ...RUN, head_sha: TWIN };
const twinDeps: RunDeps = { ...deps, run: () => atTwin, runsForHead: (_wf, sha) => (sha === TWIN ? [atTwin] : []), commitTree: sha => (sha === HEAD || sha === TWIN ? TREE : null), ancestors: sha => [sha, TWIN] };
const at = (docsOnly: (h: string) => boolean) => carry({ ...source(docsOnly), deps: twinDeps });
const ancestorOnly = at(h => h === TWIN);
expect(ancestorOnly.ok).toBe(false);
if (!ancestorOnly.ok) expect(ancestorOnly.detail).toContain('artifact_missing');
const both = at(() => true);
expect(both.ok && both.notOwed).toContain('docs-only change');
});
+74 -4
View File
@@ -41,7 +41,9 @@ function world(f: ShipFx, over: { run?: Record<string, unknown>; tree?: Record<s
fs.writeFileSync(file, JSON.stringify(w));
f.gh(fakeGhScript(file));
}
const preflight = (f: ShipFx, lanes = [`free=${FREE}`, `unit=${UNIT}`]) => f.run(PREFLIGHT, ['--tests-only', '--base', 'main', ...lanes.flatMap(l => ['--lane', l])]);
const preflight = (f: ShipFx, lanes = [`free=${FREE}`, `unit=${UNIT}`], extra: string[] = []) => f.run(PREFLIGHT, ['--tests-only', '--base', 'main', ...extra, ...lanes.flatMap(l => ['--lane', l])]);
/** --tests-only with --run-uncarried-here: a mapped lane whose carry refuses runs here (GST-3019; without the flag it stops). */
const UNCARRIED_HERE = ['--run-uncarried-here'];
const lane = (out: string, label: string) => out.split('\n').find(l => l.startsWith(`LANE: ${label} `)) ?? '';
describe('Step 5 lanes: CI carry and the tree cache', () => {
@@ -75,7 +77,7 @@ describe('Step 5 lanes: CI carry and the tree cache', () => {
let expected = 0;
for (const [reason, setup] of cases) {
setup();
const out = preflight(f, [`free=${FREE}`]).stdout;
const out = preflight(f, [`free=${FREE}`], UNCARRIED_HERE).stdout;
expect([reason, out]).toEqual([reason, expect.stringContaining('CI_CARRY: none label=free (')]);
expect(out).toContain(reason);
expect(lane(out, 'free')).toMatch(/^LANE: free pass exit=0 tests_ran=3 /);
@@ -424,7 +426,7 @@ describe('GST-1190: a file whose every test skipped on CI is not carried', () =>
world(f, { tree: { skipped_files: ['test/b.test.ts'] } });
const rec = f.run(path.join(BIN, 'gstack-evidence'), ['record-ci', '--label', 'free', '--base', 'main', '--', FREE]);
expect([rec.status, rec.stderr]).toEqual([1, expect.stringMatching(/^CARRY_NONE: inventory_skipped: 1 of 2 inventory file\(s\) skipped every test in CI and the lane declares no per_file runner: test\/b\.test\.ts$/m)]);
const out = preflight(f, [`free=${FREE}`]);
const out = preflight(f, [`free=${FREE}`], UNCARRIED_HERE);
expect(out.stdout).toContain('CI_CARRY: none label=free (inventory_skipped');
expect(runs(f, 'free-runs')).toBe(1);
world(f, { tree: { skipped_files: [] } });
@@ -538,10 +540,21 @@ describe('GST-1190: a lane carries the covered files and runs only the skipped r
const rec = f.run(path.join(BIN, 'gstack-evidence'), ['record-ci', '--label', 'free', '--base', 'main', '--', FREE]);
expect([rec.status, rec.stderr]).toEqual([1, expect.stringMatching(/^CARRY_NONE: skipped_failed: the per_file run of test\/b\.test\.ts exited 1 \(label=free\.skipped\)$/m)]);
expect(rows(f).filter(r => r.source === 'ci')).toEqual([]);
expect(preflight(f, [`free=${FREE}`]).stdout).toContain('CI_CARRY: none label=free (skipped_failed');
expect(preflight(f, [`free=${FREE}`], UNCARRIED_HERE).stdout).toContain('CI_CARRY: none label=free (skipped_failed');
expect(runs(f, 'free-runs')).toBe(1);
});
// Value: protects=--tests-only decides its hold before any lane's record-ci runs a per_file remainder here (GST-3019 review: the hold ran
// remainders, then said nothing ran); fails_when=the carrying lane's skipped file runs while another mapped lane refuses; why_new=GST-3019; seam=fake gh, gstack-ci-carry find
test('a refused mapped lane stops --tests-only before another lane runs its skipped remainder here', () => {
const f = shipFixture({ ...BASE, '.gstack/pregate.json': JSON.stringify({ run_profiles: { 'ci/free': PROFILE }, ship_lanes_from: { [FREE]: { profiles: ['ci/free'], inventory: "printf 'test/a.test.ts\\ntest/b.test.ts\\n'", per_file: PER(0) }, [UNIT]: { profiles: ['ci/free'], jobs: ['lint'] } } }, null, 2) + '\n' }); fixtures.push(f);
world(f, { tree: { skipped_files: ['test/b.test.ts'] } });
const held = preflight(f);
expect(held.status, held.stdout + held.stderr).toBe(3);
expect(lineOf(held.stdout, 'STOP')).toMatch(/^STOP: SHIP_LANE_NOT_CARRIED: lane unit did not carry /);
expect([args(f), runs(f, 'free-runs'), runs(f, 'unit-runs')]).toEqual(['', 0, 0]);
});
test('a remainder file that registers no test here carries nothing: the lane runs whole', () => {
const zero = { ...BASE, '.gstack/pregate.json': JSON.stringify({ run_profiles: { 'ci/free': PROFILE }, ship_lanes_from: { [FREE]: { profiles: ['ci/free'], inventory: "printf 'test/a.test.ts\\ntest/b.test.ts\\n'", per_file: "printf ' 0 pass\\n 0 fail\\nRan 0 tests across 1 file. [1.00ms]\\n' >&2 # {files}" } } }, null, 2) + '\n' };
const f = shipFixture(zero); fixtures.push(f);
@@ -716,3 +729,60 @@ describe('GSTA-258 L6 review fixes: gate inputs, ledger CI rows, simulate consen
expect(yes.stdout).toContain('SIMULATION: LANE: free would carry run=7/1 tests_ran=2 unit=files');
});
});
describe('GST-3019: a commit that changes no file carries the green run of the commit with its tree', () => {
// Value: protects=a base merge that changed no file reuses the passed CI run of the identical tree, and every surface says which commit and run it came from
// (gbrain #9662: 0dc0d1d, tree 369fa767, printed no_run beside 5840295's green run); fails_when=find, wait or Step 5 reads HEAD's sha alone, or a changed tree,
// an unmapped command or a red run carries; why_new=GST-3019; seam=fake gh, git rev-list and rev-parse in the fixture
test('find, wait and Step 5 carry from the earlier commit and name it; a changed tree, another command or a red run does not', () => {
const f = fx();
world(f);
const before = f.git('rev-parse', 'HEAD').stdout.trim();
const tree = f.git('rev-parse', 'HEAD^{tree}').stdout.trim();
expect(f.git('commit', '--allow-empty', '-m', 'merge main: no file changes').status).toBe(0);
const head = f.git('rev-parse', 'HEAD').stdout.trim();
expect([head !== before, f.git('rev-parse', 'HEAD^{tree}').stdout.trim()]).toEqual([true, tree]);
const cli = (args: string[]) => f.run(path.join(BIN, 'gstack-ci-carry'), args);
const found = cli(['find', '--base', 'main', '--command', FREE, '--allow-repo-commands']);
expect([found.status, lineOf(found.stdout, 'CI_CARRY')]).toEqual([0, expect.stringMatching(new RegExp(`^CI_CARRY: accepted ci-carry tree=${tree.slice(0, 12)} files=2 runs=7/1 profiles=ci/free heads=${before.slice(0, 12)} `))]);
expect(lineOf(found.stdout, 'CI_CARRY_FROM')).toBe(`CI_CARRY_FROM: run 7/1 at commit ${before.slice(0, 12)}, not HEAD ${head.slice(0, 12)}; git rev-parse reads the same tree ${tree.slice(0, 12)} for both`);
expect(cli(['wait', '--base', 'main', '--timeout', '0']).stdout).toContain('CI_WAIT: green ci/free run=7/1');
const step5 = preflight(f, [`free=${FREE}`]);
expect([step5.status, lane(step5.stdout, 'free')]).toEqual([0, `LANE: free carried run=7/1 tests_ran=2 (files) from=${before.slice(0, 12)} (same tree as HEAD)`]);
expect(runs(f, 'free-runs')).toBe(0);
expect(cli(['find', '--base', 'main', '--command', 'bun run test', '--allow-repo-commands']).stdout).toContain('CI_CARRY: none (not_mapped');
world(f, { run: { head_sha: before, conclusion: 'failure' }, tree: { sha: before } });
expect(cli(['find', '--base', 'main', '--command', FREE, '--allow-repo-commands']).stdout).toContain('CI_CARRY: none (no_verified_run: ci/free: run 7: run_not_success');
world(f, { run: { head_sha: before, conclusion: 'cancelled' }, tree: { sha: before } });
expect(cli(['find', '--base', 'main', '--command', FREE, '--allow-repo-commands']).stdout).toContain('run 7: run_not_success');
world(f, { run: { head_sha: before }, tree: { sha: before } });
f.write({ 'src/c.ts': 'export const c = 1;\n' });
expect(f.git('add', '-A').status).toBe(0);
expect(f.git('commit', '-m', 'a real change').status).toBe(0);
expect(cli(['find', '--base', 'main', '--command', FREE, '--allow-repo-commands']).stdout).toContain('CI_CARRY: none (no_run: no free.yml run (pull_request, workflow_dispatch) on ');
});
});
describe('GST-3019: --tests-only never starts a lane on its own when its carry refuses', () => {
// Value: protects=a refused carry under --tests-only stops with SHIP_LANE_NOT_CARRIED and the next command instead of quietly running the lane here
// (gbrain #9662: a 50-minute unit lane on a 4-CPU box); fails_when=the mapped lane or any other lane runs, the stop has no code, or --run-uncarried-here
// does not run it; why_new=GST-3019; seam=fake gh, gstack-evidence ledger
test('a refused carry stops before any lane runs and names the CI dispatch; --run-uncarried-here runs it here', () => {
const f = fx();
world(f, { run: { head_sha: '0'.repeat(40) } });
const branch = f.git('branch', '--show-current').stdout.trim();
const held = preflight(f);
expect(held.status).toBe(3);
expect(held.stdout).toContain('CI_CARRY: none label=free (no_run: ');
expect(lineOf(held.stdout, 'STOP')).toBe('STOP: SHIP_LANE_NOT_CARRIED: lane free did not carry from a verified CI run at this tree, and --tests-only never starts a lane on its own: nothing ran here (docs/troubleshooting.md#ship-lane-not-carried)');
expect(held.stdout).toContain(`NEXT: commit and push this tree, then gh workflow run free.yml --ref ${branch} and gstack-ci-carry wait --base main; once it prints CI_WAIT: green, rerun this command`);
expect(held.stdout).toContain('NEXT: or rerun this command with --run-uncarried-here to run lane free on this machine');
expect([runs(f, 'free-runs'), runs(f, 'unit-runs')]).toEqual([0, 0]);
const here = preflight(f, undefined, UNCARRIED_HERE);
expect(here.status).toBe(0);
expect(here.stdout).toContain('CI_CARRY: none label=free (no_run: ');
expect(lane(here.stdout, 'free')).toMatch(/^LANE: free pass exit=0 tests_ran=3 /);
expect([runs(f, 'free-runs'), runs(f, 'unit-runs')]).toEqual([1, 1]);
expect(f.run(PREFLIGHT, ['--base', 'main', '--run-uncarried-here', '--lane', `free=${FREE}`]).status).toBe(2);
});
});
+17
View File
@@ -339,6 +339,23 @@ describe('gstack-ship-preflight --audit (GSTA-167 variant G)', () => {
expect(lineOf(r.stdout, 'READER')).toBe('READER: coverage=none plan=needed');
expect(f.run(PREFLIGHT, ['--audit', '--base', 'main']).status).toBe(2);
});
// Value: protects=--audit --base <sha> diffs against that commit, and a base that resolves to nothing stops with SHIP_BASE_UNKNOWN instead of an empty diff (gbrain #9662);
// fails_when=a commit sha is read as origin/<sha>, or an unknown base prints CONTEXT files=0; why_new=GST-3019; seam=git
test('a commit sha is a base; a base that resolves to nothing stops with SHIP_BASE_UNKNOWN, never files=0', () => {
const f = fx({}, { 'src/budget.ts': 'export const budget = 1;\n', 'src/other.ts': 'export const o = 1;\n' });
const base = f.git('rev-parse', 'origin/main').stdout.trim();
for (const sha of [base, base.slice(0, 12)]) {
const r = f.run(PREFLIGHT, ['--audit', '--base', sha, '--out', path.join(f.root, `a-${sha.length}`)], { HOME: f.root });
expect(r.status, r.stdout + r.stderr).toBe(0);
expect(lineOf(r.stdout, 'CONTEXT')).toMatch(/ files=2 commits=1 /);
}
for (const bad of ['0'.repeat(40), 'no-such-branch']) {
const u = f.run(PREFLIGHT, ['--audit', '--base', bad, '--out', path.join(f.root, 'bad')], { HOME: f.root });
expect([u.status, lineOf(u.stdout, 'STOP')]).toEqual([3, `STOP: SHIP_BASE_UNKNOWN: --base ${bad} names no commit here (not a commit this checkout holds, and no origin/${bad}); pass the base branch fetched into origin/<name>, or a commit sha after git fetch origin <sha>, then rerun (docs/troubleshooting.md#ship-base-unknown)`]);
expect(u.stdout).not.toContain('CONTEXT');
}
});
});
describe('GSTA-167 part 4a: RUNTIME_LINES and REVIEW_DEPTH share one owner', () => {
@@ -0,0 +1,4 @@
{
"bytes": 192,
"why": "GST-3019: Step 5 prose names the SHIP_LANE_NOT_CARRIED stop under --tests-only and the --run-uncarried-here flag"
}