Skip to content

v1.92.0.0 ship-queue: merge trains for any repo (train gates, every prefix gated, direct/update land, train init/doctor) (GSTA-157 PR 2) - #3692

Merged
capy-ai[bot] merged 16 commits into
mainfrom
capy/ship-queue-merge-trains
Oct 31, 2026
Merged

capy-ai[bot] merged 16 commits into
mainfrom
capy/ship-queue-merge-trains

Conversation

@garrytan

@garrytan garrytan commented Oct 31, 2026 •

Copy link
Copy Markdown
Owner
{
  "schema_version": 1,
  "pr": 3692,
  "head": "93fc5dc9e8e4ce5bf9c5b1082dda9b5b75931d3d",
  "version": "1.91.374.0",
  "base": "main",
  "gate": {
    "train": {
      "pass": 610,
      "fail": 0,
      "skip": 0
    }
  },
  "session_kind": "unattended",
  "head_tree": "68e0643f61c0ac15cdccda2dae1a37ac17c8d2cd",
  "product_patch_id": "b863307da1e02795f67f0ce9ac833cbab3f15312",
  "gstack_version": "1.91.366.0",
  "review_depth": {
    "depth": "full",
    "class": "gate",
    "runtime_lines": 1780,
    "rules": "150435b0a543019a",
    "base": "7d4e71bd940a9611ffc7020a4128403952c77af9",
    "registry": "7d4e71bd940a9611ffc7020a4128403952c77af9",
    "gate_scan": {
      "tagged": 0,
      "head": "93fc5dc9e8e4ce5bf9c5b1082dda9b5b75931d3d"
    },
    "reasons": [
      "gate-class",
      "runtime=1780>50"
    ]
  },
  "pregate": "requires-remote cleared @68e0643f61c0 (1 checks, current for 93fc5dc9e8e4)",
  "requires_remote": [
    "free-tests.yml/cso-macos-launcher: https://github.com/garrytan/gstack/actions/runs/41219850887",
    "free-tests.yml/macos-named-regressions: https://github.com/garrytan/gstack/actions/runs/41219850887",
    "windows-free-tests.yml/windows-free-shard: https://github.com/garrytan/gstack/actions/runs/41219853793",
    "pregate.json/remote_gate: remote-gate tree=68e0643f61c0 tests=24391"
  ],
  "issues": {
    "fixes": [],
    "refs": [
      3611
    ],
    "flakes": []
  },
  "docs": {
    "status": "current",
    "scope": "docs/, captain/, README.md, CLAUDE.md, AGENTS.md after the base merge (re-audit of docs-ship-pr2-a1)"
  },
  "review_loop": {
    "passes": 5,
    "blocking_found": 8,
    "deferred": 0,
    "noted": 30,
    "fixed": 16,
    "scope": "frozen",
    "fix_checks": 1,
    "dispatches": {
      "specialist": 2,
      "red-team": 2
    }
  },
  "review_targeted": {
    "classes": [
      "money"
    ],
    "rules": "baeb8f7ef7da92d0",
    "brief_sha": "7f92a0d0a8319c3c0e076fb3b1a4689c45120b2be2c14dfc7d4cb03aafa9d6a5",
    "product_patch_id": "b863307da1e02795f67f0ce9ac833cbab3f15312",
    "status": "done",
    "findings": 1,
    "raised_by": "targeted"
  }
}

What changed

Any repo can now run a merge train on its own CI workflows or a test command; captain.md gains the setup steps (train init, doctor, watch --land).

Any repo can now run a merge train on its own CI workflows or a test command; captain.md gains the setup steps (train init, doctor, watch --land)

Before/after as text: Any repo can now run a merge train on its own CI workflows or a test command; captain.md gains the setup steps (train init, doctor, watch --land)
--- Before · docs/captain.md § Merge trains for other repos at 1b46f37 · source text (section not present before)
+++ After · docs/captain.md § Merge trains for other repos on this branch · source text
+### Merge trains for other repos
+A repository without gstack's eval workflow declares `gates` in its train block
+([ship-policy.md](ship-policy.md#train-gates)): its own CI workflows, a test
+command on a Ubicloud VM, or both. Every prefix is gated, so a red train names
+its culprit with no bisect and no rebuild. To turn one on, run `train init` in
+a checkout, commit the printed block (and the workflow snippet) on the base
+branch through a PR, then run `train doctor` until it reports no findings.
+
+The controller's loop shortens to `train build --prs <pins>`, then
+`train watch --train <nonce> --land`, which waits for every prefix run, reads
+the verdict and lands each landable slot in order. Lanes READY with
+`ready --pr <n> --no-screen`; there is no screen and no slot call. A lane whose
+/ship paused on a red base READYs with `--base-red --fixer <pr>`, its fixer with
+`--fixes-base-red <cases>`, and the train seats the fixer at slot 1. The `update` commit `train land` pushes to a PR
+branch (the gated tree on [pin, main]) is the one exception to CREW rule 14's "never merge
+the base into a PR": it is tool-made, recorded before the push, and pushed under the pin's
+lease, like a stamped train's stamp commit. A peer crew
+adopting this starts from
+[captain/templates/merge-train-peer.md](../captain/templates/merge-train-peer.md).
  • Train gates for any repo: train.gates lists workflows gates (nonce-dispatched CI workflows with workflow-qualified required_jobs) and command gates (a repo command on a Ubicloud VM, bound to the prefix tree). Every entry must be green on every prefix. A train block without gates keeps the old path.
  • Every prefix gated: T0..Tk are each pushed to train-prefix/<nonce>/t<i> and gated, so the culprit is the first red prefix after a green one, with no bisect.
  • train land generalized: it publishes the stamped S_i when the policy stamps and T_i otherwise, with the merge method from train.land.merge_method, a direct mode when the pin's required checks are all green and update otherwise. The next slot waits until the previous slot's post_merge_checks are green.
  • Base-red trains: ready --base-red/--fixer and --fixes-base-red; T0 may be red only on the fixer's declared cases, and the fixer sits in slot 1.
  • train init / train doctor read branch protection, workflows and open PRs and print the policy block and workflow snippets; train watch --land runs build, gate, verdict and land and stops at the first refusal.

Why

"Trains only worked for gstack's own paid-eval gate": other repos (Truther, gbrain, Founderstar) merged one PR at a time and got stuck whenever main was red. Now any repo can run a train on its own CI or test command, and every tree that lands on main has passed its gate first.

Blast radius

This touches the ship-queue train code, the ship policy schema and the docs for both. gstack's own trains keep their current behavior because a train block without gates takes the old code path, and a test parses the repo's .gstack/ship-policy.json unchanged (script ran: the train lane passed 610 tests at tree 68e0643).

Approvals

No approvals recorded for branch capy/ship-queue-merge-trains.

Summary

Merge trains only worked for one repo, so every other crew merged one PR at a time and stopped when main went red. This PR lets a repo declare its own gates, gates every prefix so a red train names its culprit right away, and lands each slot with the merge method and checks that repo uses. Review fixes after pass 1 and pass 2 bound workflow re-dispatch, hold a lease during builds, keep the full output tail, and make landing wait for each slot's post-merge checks. The branch carries one merge of the base branch and one of main (rule 19 grant); neither changed the product patch.

Test Coverage

New code paths are covered by the 22-file train lane (610 pass, 0 fail) and the free tier on a remote pregate (24391 tests, 0 failed). Gaps found by review are listed under Review notes (chooseMode wait branch, end-to-end stamp-at-merge without fragments). Coverage percentage was not computed in this run.

Tests ran: typecheck count unavailable
Tests ran: train 610

Pre-Landing Review

Pass 1 found 23 issues; 7 were at the blocking floor and were fixed with tests (468f4e8): unbounded workflow re-dispatch, rebase direct land, retarget before merge, post_merge_checks not gating, concurrent builds, the 1 MB tree line, and merge-only rejecting legacy policies. Pass 2 found 1 blocker, fixed in 583cc1b (train land refuses the next slot until the previous slot's post-merge checks are green). Passes 3 to 5 were clean reads after docs, curation and merge commits.

REVIEW_LOOP: passes=5 blocking_found=8 deferred=0 noted=30 fixed=16 scope=frozen fix_checks=1 dispatches=4

Gate edits: none detected (2 listed, 1 read; patterns: RH-1,RH-3,RH-4,RH-12,RH-13,RH-14,RH-15,RH-16; unlisted idioms: none)

Outside review: issues found. Its first High item (a restarted watcher skipping post-merge checks) was fixed in 583cc1b; its other two (the train lease is local to one clone, and command-only repos with no GitHub CI cannot READY or land) are below the floor and listed in Review notes. The fix-check flagged that the pending post-merge NEXT carries --timeout 0, which the CLI rejects; it was judged below the floor and is open.

Targeted review (money class, at 93fc5dc against main 1b46f37): 1 finding, INFORMATIONAL, below the floor; listed in Review notes.

Review notes

Below the blocking floor (advisory, informational, test-gap or wording items); recorded here and not fixed in this PR.

  • INFORMATIONAL lib/ship-queue-train-land.ts:119 no test reaches chooseMode wait branch or the merge-tree mismatch branch
  • INFORMATIONAL lib/ship-queue-train.ts:433 no end-to-end test of a gated train under stamp-at-merge without fragments
  • INFORMATIONAL lib/ship-queue-train-land.ts:53 rulesets-only protection reads as unprotected; direct retried forever
  • INFORMATIONAL lib/ship-queue-train-land.ts:150 post_merge_checks names with commas split by --checks; JSON.stringify is not shell quoting
  • INFORMATIONAL lib/ship-queue-train-cli.ts:186 --fixes-base-red split on commas; matrix case ids contain commas
  • INFORMATIONAL lib/ship-queue-train-gate.ts:391 all command VMs start at once; a quota refusal settles INCOMPLETE
  • INFORMATIONAL lib/ship-queue-train-gate.ts:459 record artifact not scoped to the rerun attempt
  • INFORMATIONAL lib/ship-queue-train-gate.ts:132 a failed non-required job turns a prefix RED
  • INFORMATIONAL lib/ship-queue-train-gate.ts:452 a transient read error settles INCOMPLETE
  • INFORMATIONAL lib/ship-queue-train-gate.ts:447 rerun completion keyed on run_attempt<2
  • INFORMATIONAL lib/ship-queue-train-gate.ts:291 lease takeover race, unowned release, pid reuse after sleep
  • INFORMATIONAL lib/ship-queue-train-land.ts:114 direct mode trusts local merge-tree to predict the server merge (post-merge tree check freezes)
  • INFORMATIONAL lib/ship-queue-train-gate.ts:356 command rerun skipped silently when the cap is spent
  • INFORMATIONAL lib/ship-queue-train.ts:686 refs and gw worktrees left behind for unattributed/incomplete trains
  • INFORMATIONAL lib/ship-queue-train.ts:403 a held fixer past max_size refuses the build
  • INFORMATIONAL lib/ship-queue-train-gate.ts:298 the train lease is local; two controllers on separate clones can both run command gates
  • INFORMATIONAL lib/ship-queue-train-ready.ts:228 command-only repos with no GitHub CI cannot READY or land
  • INFORMATIONAL lib/ship-queue-train-gate.ts:461 crash between rerun request and record allows a third attempt
  • INFORMATIONAL lib/ship-queue-train-gate.ts:342 a VM whose teardown is not confirmed (left=1 or unknown) keeps billing until its TTL reaper, up to about 3x the reservation the train cap counted (targeted money pass)

Exploratory QA

Not run: this is CLI and library code, and its behavior is exercised by the train lane fixtures (fake gh, fake Ubicloud API). No live repo train was run.

Design Review

No frontend files changed — design review skipped.

Eval Results

No paid evals ran; no prompt-related files changed. The remote pregate cost $0.07 at tree 68e0643 ($0.14 in total with the superseded run at 821cf3b).

Greptile Review

No Greptile comments.

Plan Completion

Built against the GSTA-157 plan approved by Garry ("Do it", 2026-10-29) and re-planned against v1.91.365.0 with GStack Minder's approval (2026-10-31). Deferred: #3603 items 3 to 5 stay with GSTA-154.

Issues

Refs #3611

Verification Results

The plan's checks ran as tests: 610 PASS in the train lane, 0 FAIL, 0 BLOCKED. Not run: a live train on a peer repo.

TODOS

No TODO items completed in this PR.

Documentation

Status: current. This re-audit after the base merge (origin/main 1b46f37 now includes #3611) found no drift in this PR's docs; no edits and no blockers.

Scope: base 1b46f37 to head 93fc5dc, 22 committed files with nothing staged, unstaged or untracked. The docs in the diff are docs/ship-policy.md, docs/troubleshooting.md, docs/captain.md, captain/templates/merge-train-peer.md and the changelog.d fragment. The merge commit changes no bytes compared with 94fa21c, and main's changes since the earlier audit's base touch only unrelated troubleshooting entries. Claims were rechecked against lib/ship-policy.ts (TRAIN_GATES_KEY_VERSION 1.92.0.0; max_size 1 to 5 for a train with gates), lib/ship-queue-train-gate.ts (at most two sends per prefix; UBI_OWNER required; $0.34 reservation at 1800 s), lib/ship-queue-train-init.ts (default cap $3 covers six prefixes and one rerun; the rebase finding), lib/ship-queue-train.ts (prune) and lib/result-codes-release.ts (all seven new codes have troubleshooting anchors). Banned-term check: none configured.

Documentation health:

  • docs/ship-policy.md: Current.
  • docs/troubleshooting.md: Current.
  • docs/captain.md: Current (CREW rule 14 citation matches captain/templates/CREW.md).
  • captain/templates/merge-train-peer.md: Current (linked from docs/captain.md).
  • README.md, AGENTS.md: Current (docs/captain.md stays linked from README).
  • CHANGELOG.md, changelog.d: Not audited for edits (owned by the parent).

Documentation coverage:

  • train.gates (workflows and command gates): reference in ship-policy.md; how-to in merge-train-peer.md and captain.md; no tutorial.
  • train init, train doctor, train watch --land, ready --base-red/--fixes-base-red: reference and how-to; no tutorial.
  • verify --post-merge --checks: reference only (common gap).
  • train prune keeping an attributed train with gates while the slots before its culprit are unmerged: covered only by the changelog fragment, not by ship-policy.md's Clean up step or the CLI help (critical gap).
  • The train lease (one build or verdict at a time): reference only, in QUEUE_TRAIN_PENDING (common gap).

Diagram drift: none (ARCHITECTURE.md has no ship-queue diagram).

Follow-up: run /document-generate for a tutorial on turning on a train with gates.

Test plan

  • bun run typecheck: exit 0
  • bun test (22 train-lane files): 610 pass, 0 fail
  • UBI_OWNER=gsta157 gstack-pregate --stage tests --remote: 24391 tests, 0 failed, tree 68e0643
  • Free Tests run 41219850887 and Windows Free Tests run 41219853793: success

🤖 Generated with Claude Code

garrytan and others added 14 commits January 1, 2000 00:00
…-red, conditional receipts) (GSTA-157 PR 1)

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>
Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>
…, readPause, wait unconfigured)

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>
…ers an invalid base policy

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>
…ify usage before fetch, unresolved-head detail)

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>
… 2026-10-31); CHANGELOG entry moved to changelog.d fragment

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>
…command), every prefix gated, generalized train land (direct/update, merge method), base-red trains, train init/doctor, watch --land (GSTA-157 PR 2)

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>
…base, post-merge checks, output tail, caps)

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>
…merge checks are green

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>
… fixes

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>
Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>
…m resolves gh.exe there)

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>
…py/ship-queue-merge-trains (rule 19 grant, GStack Minder 2026-10-31)

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>
@capy-ai
capy-ai Bot changed the base branch from gsta157-base-red-pause to main October 31, 2026 16:32
@trunk-io

trunk-io Bot commented Oct 31, 2026 •

Copy link
Copy Markdown

😎 This pull request was merged.

@github-actions github-actions Bot changed the title ship-queue: merge trains for any repo (train gates, every prefix gated, direct/update land, train init/doctor) (GSTA-157 PR 2) v1.91.374.0 ship-queue: merge trains for any repo (train gates, every prefix gated, direct/update land, train init/doctor) (GSTA-157 PR 2) Oct 31, 2026
garrytan and others added 2 commits October 31, 2026 16:32
…queue-merge-trains (rule 19 grant, GStack Minder 2026-10-31)

main's tree at 1b46f37 equals the base stamp 4bc8d9c already merged in 94fa21c, so every add/add hunk resolves to the same bytes.

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>
@github-actions github-actions Bot changed the title v1.91.374.0 ship-queue: merge trains for any repo (train gates, every prefix gated, direct/update land, train init/doctor) (GSTA-157 PR 2) v1.92.0.0 ship-queue: merge trains for any repo (train gates, every prefix gated, direct/update land, train init/doctor) (GSTA-157 PR 2) Oct 31, 2026
@capy-ai
capy-ai Bot merged commit 92a9350 into main Oct 31, 2026
63 checks passed
garrytan added a commit that referenced this pull request Oct 31, 2026
…seline to 970

lib/ship-policy.ts:403 and test/ship-queue-train-generic.test.ts:234 use
startsWith instead of a caret regex (same result). Main dropped the unused
outOk import, so --write-baseline removes that entry; the baseline only shrinks.

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant