Integration branch tool #
Builds and tests integration/next the way linux-next works: merge every
in-flight branch onto a fresh origin/main in one place, run the full gate
suite, and find the branch that broke a failing gate. The coordinator runs it
without waiting for merges into main.
integration/next is disposable. The tool force-pushes it and never opens a
pull request from it.
Usage #
tools/integration/run.sh --manifest /data/dev/protokill-notes/integration/branches.txt
tools/integration/run.sh --manifest ... --soak 30
tools/integration/run.sh --manifest ... --dry-run
tools/integration/run.sh --manifest ... --no-preview
The manifest lists branches in merge order, one per line. Blank lines and
comments are ignored. An optional after: other-branch suffix skips this
branch when other-branch is missing, conflicts, or is skipped; the
dependency must appear earlier in the file. branches.txt here is an example;
the coordinator keeps the real one in the notes directory.
--dry-run prints the plan without fetching, merging, building, pushing or
publishing. Exit codes: 0 all gates passed, 1 a gate failed or assembly
failed, 130 interrupted, 2 usage.
A lockfile (integration/.lock) prevents two runs from overlapping. A cron
entry can therefore be safe:
17 3 * * * /data/dev/protokill/tools/integration/run.sh \
--manifest /data/dev/protokill-notes/integration/branches.txt \
>> /data/dev/protokill-notes/integration/cron.log 2>&1
What it does #
- Fetches
origin, then resets the dedicated worktree.claude/worktrees/integration-nextontoorigin/main. - Merges each listed branch with
git merge --no-ff. Known-trivial conflicts are resolved first:Cargo.locktakes either side and is regenerated afterwards, and additive list conflicts inCargo.toml(members or dependencies),crates/protokill/tests/architecture.rs,AGENTS.mdandscripts/check-targets.pykeep both sides' inserted lines (ours then theirs) when every hunk is insertion-only. A hunk with a deletion or modification stays a real conflict. Resolved branches are reported asmerged (auto-resolved: files). After that it can retry once with-X oursor-X theirswhen--x-strategyis given (default: none). Otherwise it records the conflicting files, skips that branch and its dependents, and continues. - Regenerates
Cargo.lockwithcargo metadataif the merges changed the dependency graph, and commits it as a fix-up. - Force-pushes the result to
integration/next. - Runs gates in order, one log each:
scripts/fetch-fonts.sh,scripts/ci.sh,scripts/wasm-test.sh, a release build withscripts/deploy.sh, then the browser smokes present in the tree (mouse,effects,hosted) insidetools/pk/shell.nix. The smokes use port 4170 andPK_INSTANCE=2;npm ciruns once iftools/pk/node_modulesis missing. - With
--soak MINUTES, runsprotokill_server'stests/strategic.rswhen present, orscripts/slice-soak.sh, on the named testnet instanceintegration-next, and brings that instance down afterwards. - On the first failing gate, bisects over the merge order. It rebuilds
mainplus a prefix of branches, sharing one incremental target dir, and reports the first branch whose addition makes the gate fail. For a smoke gate each candidate is rebuilt and served, so this is the slow path. - When the release build and every present smoke pass, publishes the bundle
to
/data/dev/protokill-notes/preview/fullstack/next/by building a staging directory and swapping it in atomically.index.htmlgets?v=<sha>, andnext/BUILD.txtlists main and every merged branch with its sha. The maintainer's preview server on port 8710 is never touched or restarted; it serves that directory. - Writes
integration/REPORT.md(overwritten each run) and a dated copy inintegration/history/. Logs live inintegration/logs/<timestamp>/.
Resources and cleanup #
The wrapper runs nice -n 10, sets TMPDIR under
/data/dev/tmp/integration, and points every build at one shared
CARGO_TARGET_DIR (/data/dev/tmp/integration/target) so the main build and
the bisect share incremental artifacts. That target dir is deleted when it
exceeds 20 GB. Each run removes the worktrees' output/ and its own scratch
directory, but keeps the shared target.
All long-running children are started in their own process group and stopped by their recorded PID; the tool never matches processes by command line.