README.md

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 #

  1. Fetches origin, then resets the dedicated worktree .claude/worktrees/integration-next onto origin/main.
  2. Merges each listed branch with git merge --no-ff. Known-trivial conflicts are resolved first: Cargo.lock takes either side and is regenerated afterwards, and additive list conflicts in Cargo.toml (members or dependencies), crates/protokill/tests/architecture.rs, AGENTS.md and scripts/check-targets.py keep 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 as merged (auto-resolved: files). After that it can retry once with -X ours or -X theirs when --x-strategy is given (default: none). Otherwise it records the conflicting files, skips that branch and its dependents, and continues.
  3. Regenerates Cargo.lock with cargo metadata if the merges changed the dependency graph, and commits it as a fix-up.
  4. Force-pushes the result to integration/next.
  5. Runs gates in order, one log each: scripts/fetch-fonts.sh, scripts/ci.sh --full (which runs scripts/wasm-test.sh too), a release build with scripts/deploy.sh, then the browser smokes present in the tree (mouse, effects, hosted) inside tools/pk/shell.nix. The smokes use port 4170 and PK_INSTANCE=2; npm ci runs once if tools/pk/node_modules is missing.
  6. With --soak MINUTES, runs protokill_server's tests/it/strategic.rs when present, or scripts/slice-soak.sh, on the named testnet instance integration-next, and brings that instance down afterwards.
  7. On the first failing gate, bisects over the merge order. It rebuilds main plus a prefix of branches in the bisect worktree, which keeps its own target dir between candidates, 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.
  8. 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.html gets ?v=<sha>, and next/BUILD.txt lists 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.
  9. Writes integration/REPORT.md (overwritten each run) and a dated copy in integration/history/. Logs live in integration/logs/<timestamp>/.

Resources and cleanup #

The wrapper runs nice -n 10 and sets TMPDIR under /data/dev/tmp/integration. Each of the two worktrees builds into its own target/: a target dir shared between worktrees is not safe, so the tool unsets CARGO_TARGET_DIR for every gate. Builds share compiled dependencies through sccache instead. A worktree's target/ is deleted when it exceeds 20 GB, and the shared /data/dev/tmp/integration/target that older runs used is removed on the next run. Each run removes the worktrees' output/ and its own scratch directory, but keeps their 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.