/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

+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 };