[bitlane] Sync with upstream main 2026-10-21 (13 patches kept, 1 dropped: merged upstream)

.agents/skills/pr-checklist/SKILL.md

@@ -104,6 +104,8 @@ When adding or modifying tests, consider both the coverage and the effectiveness
 
 Assess whether the included test cases are meaningful, concise, and maintainable. Testing should not be exhaustive: local validation is typically sufficient to ensure a baseline correctness of the change. Contributed tests should focus exclusively on areas that are deemed prone to errors, regressions, or complex interactions within the codebase. Recommend deletion of redundant, trivial, or otherwise unnecessary tests: this is one of the most common complaints raised during code reviews.
 
+Check added and changed tests against [`tests/AGENTS.md`](../../../tests/AGENTS.md). For reproducible bugs, the PR must show the new test failing without the fix and passing with it.
+
 Verify that testing actually exercises the new path, rather than passing through an unchanged path or fallback. Ensure added speculative decoding correctness tests assert nonzero acceptance rate, selection tests identify the desired backend, etc.
 
 Aim to write tests that are meaningful, targeted, and maintainable. Avoid redundant or trivial tests that do not contribute to the overall reliability of the test suite. Avoid using mock objects, especially when highly coupled with internal logic.
@@ -135,7 +137,7 @@ For bug fixes, there is no need to include details of the original bug and expla
 
 #### 3.2: Documentation and Examples
 
-Ensure that any new features, changes, or public APIs are properly documented. This includes updating relevant documentation files under `docs/` and providing usage examples where applicable. Refer to `supported_models.md` for new models and `examples/` for usage examples.
+User-visible changes need docs in the same PR, placed and checked per [Documenting User-Visible Changes](../../../docs/contributing/README.md#documenting-user-visible-changes); missing or unfindable docs are blocking. Add usage examples under `examples/` where applicable.
 
 #### 3.3: Helper Functions
 

.agents/skills/transformers-upgrade/SKILL.md

@@ -23,12 +23,14 @@ A version change is one of two jobs, and they usually come as a pair:
 2. Read the release notes for config validation changes, renamed auto-mapping
    formats, and removed attributes; these are what break vLLM.
 3. Search `tests/` for `min_transformers_version` and skip markers naming the
-   new version, and un-gate them.
+   new version, and run those tests on the new pin. Keep the gates: older
+   versions in the supported range still lack the feature, so a gate goes
+   only when the floor reaches it.
 4. Run the suites in [Testing](#testing) and fix what breaks. Mark every
    shim with a `# Transformers >= X` comment so the next floor raise finds it.
 
-Done when the [Testing](#testing) suites pass on the new pin and every test
-waiting on this version is un-gated.
+Done when the [Testing](#testing) suites and every test gated on this
+version pass on the new pin.
 
 ## Raise the floor (unvendoring pass)
 

.bitlane/builder.sh

@@ -0,0 +1,18 @@
+#!/usr/bin/env bash
+# usage: .bitlane/builder.sh 'shell'   In a workflow, after the OIDC role: runs the shell as root on the bitlane
+# builder host over SSM (instance id in SSM parameter /bitlane/builder_id), waits, prints its output. Exit 1 unless
+# the command succeeded. A person starts the builder (bitlane node/launch.sh), never CI.
+# The e2e it starts reaches off-AWS dev nodes (bitlane control/hosts.yaml) over ssh from the builder.
+set -euo pipefail
+ID=$(aws ssm get-parameter --name /bitlane/builder_id --query Parameter.Value --output text)
+CID=$(aws ssm send-command --instance-ids "$ID" --document-name AWS-RunShellScript --timeout-seconds 600 \
+  --parameters "$(jq -nc --arg c "$1" '{commands: [$c], executionTimeout: ["9000"]}')" \
+  --query Command.CommandId --output text) \
+  || { echo "::error::builder $ID unreachable: is it running? (bitlane docs/operations.md, Fork workflow)"; exit 1; }
+while sleep 20; do
+  S=$(aws ssm get-command-invocation --command-id "$CID" --instance-id "$ID" --query Status --output text 2>/dev/null || echo Pending)
+  case $S in Pending|InProgress|Delayed) ;; *) break ;; esac
+done
+aws ssm get-command-invocation --command-id "$CID" --instance-id "$ID" \
+  --query '[StandardOutputContent,StandardErrorContent]' --output text
+[ "$S" = Success ] || { echo "::error::builder command $CID: $S"; exit 1; }

.bitlane/check-stack.py

@@ -0,0 +1,113 @@
+#!/usr/bin/env python3
+"""Hygiene gate for the bitlane patch stack: python3 .bitlane/check-stack.py BASE [HEAD] [--prs]
+
+BASE is the upstream main commit the stack sits on (git merge-base HEAD upstream/main). Every commit in BASE..HEAD:
+  - is not a merge commit
+  - has a subject "[bitlane] ..."
+  - has a body line "Upstream: https://github.com/vllm-project/vllm/pull/N" or "Bitlane-only: <reason>"
+  - changes only files an overlay build can carry (vllm/**.py, tests, docs, ...; .bitlane/ and our bitlane-*
+    workflows), unless it has "Binary-change: yes", which needs a full build: not supported yet, so it fails
+--prs: also the state of each Upstream PR (GitHub API; GITHUB_TOKEN if set). Merged with its merge commit already in
+BASE = the patch should have dropped at the rebase: error. Merged after BASE: drops at the next rebase. Closed
+unmerged: flagged. Prints a Markdown report (CI summary, release notes); exit 1 on any error. Stdlib only.
+"""
+import json, os, re, subprocess, sys, urllib.request
+
+PR = re.compile(r"^https://github\.com/vllm-project/vllm/pull/(\d+)$")
+OVERLAY = re.compile(r"^(vllm/.*\.py|tests/.*|docs/.*|benchmarks/.*|examples/.*|\.buildkite/.*"
+                     r"|\.bitlane/.*|\.github/workflows/bitlane-[^/]*)$")
+
+
+def git(*a):
+    return subprocess.run(["git", *a], check=True, capture_output=True, text=True).stdout
+
+
+TRAILER = re.compile(r"^(Upstream|Bitlane-only|Binary-change):[ \t]*(\S.*)$", re.M)
+
+
+def trailers(sha):  # "Key: value" lines in the body. git's own trailer parser misses them when the last paragraph
+    # also holds What:/Why: prose (the v0.32.0.x commits). The first of each key counts.
+    return {k.lower(): v.strip() for k, v in reversed(TRAILER.findall(git("log", "-1", "--format=%b", sha)))}
+
+
+def pr_state(n):  # "open" | "closed" | ("merged", merge sha)
+    req = urllib.request.Request(f"https://api.github.com/repos/vllm-project/vllm/pulls/{n}",
+                                 headers={"Accept": "application/vnd.github+json"})
+    if os.environ.get("GITHUB_TOKEN"):
+        req.add_header("Authorization", f"Bearer {os.environ['GITHUB_TOKEN']}")
+    with urllib.request.urlopen(req, timeout=30) as r:
+        d = json.load(r)
+    return ("merged", d["merge_commit_sha"]) if d.get("merged_at") else (d["state"], None)
+
+
+def in_base(sha, base):
+    if not sha:
+        return None
+    r = subprocess.run(["git", "merge-base", "--is-ancestor", sha, base], capture_output=True)
+    return {0: True, 1: False}.get(r.returncode)  # 128: commit not here: unknown
+
+
+GH_MERGE = re.compile(r"^Merge pull request #\d+ from callgideon/")
+
+
+def check(base, head, prs):
+    errors, notes, rows = [], [], []
+    for line in git("rev-list", "--reverse", "--parents", f"{base}..{head}").splitlines():
+        sha, *parents = line.split()
+        s, subject = sha[:12], git("log", "-1", "--format=%s", sha).strip()
+        t = trailers(sha)
+        if len(parents) > 1:
+            # GitHub's "Merge pull request" button: allowed, its commits are checked one by one in this same loop;
+            # bitlane-sync's daily rebase drops it. Any other merge breaks the linear stack.
+            if GH_MERGE.match(subject):
+                notes.append(f"{s}: {subject} (a PR merge: its commits are checked on their own)")
+                continue
+            errors.append(f"{s}: merge commit (the stack is linear: rebase, never merge)")
+        if not subject.startswith("[bitlane] "):
+            errors.append(f"{s}: subject must start with '[bitlane] ': {subject!r}")
+        up, only = t.get("upstream", ""), t.get("bitlane-only", "")
+        m = PR.match(up)
+        if not m and not only:
+            errors.append(f"{s}: needs a trailer 'Upstream: https://github.com/vllm-project/vllm/pull/N' or 'Bitlane-only: <reason>'")
+        if up and not m:
+            errors.append(f"{s}: Upstream must be a vllm-project/vllm PR url, not {up!r}")
+        files = git("diff-tree", "--no-commit-id", "--name-only", "-r", "--no-renames", sha).split()
+        bad = [f for f in files if not OVERLAY.match(f)]
+        if t.get("binary-change", "").lower() == "yes":
+            errors.append(f"{s}: Binary-change: yes needs a full vLLM build; the pipeline builds Python overlays only")
+        elif bad:
+            errors.append(f"{s}: changes {', '.join(bad[:5])}: not an overlay file (csrc, build, requirements, data "
+                          "under vllm/); a binary change needs 'Binary-change: yes' and a full build")
+        state = "-"
+        if m:
+            state = "not checked"
+            if prs:
+                st, merge = pr_state(m.group(1))
+                state = st
+                if st == "merged":
+                    ib = in_base(merge, base)
+                    state = f"merged {merge[:12]}" + {True: " (in base)", False: " (after base)", None: ""}[ib]
+                    if ib:
+                        errors.append(f"{s}: #{m.group(1)} is merged in the base ({merge[:12]}) and the patch did not "
+                                      "drop: drop it, or keep the difference as a Bitlane-only commit")
+                    else:
+                        notes.append(f"{s}: #{m.group(1)} merged upstream: drops at the next rebase past {merge[:12]}")
+                elif st == "closed":
+                    notes.append(f"{s}: #{m.group(1)} closed without merge: carry it as Bitlane-only or drop it")
+        link = f"[#{m.group(1)}]({up})" if m else f"Bitlane-only: {only}" if only else "?"
+        rows.append(f"| `{s}` | {subject.removeprefix('[bitlane] ')} | {link} | {state} | {len(files)} |")
+    out = [f"Stack: {len(rows)} commits on upstream `{base[:12]}`", "",
+           "| Commit | Subject | Upstream | State | Files |", "|---|---|---|---|---|", *rows, ""]
+    out += [f"- note: {n}" for n in notes] + [f"- **error**: {e}" for e in errors]
+    out.append("" if errors else "Hygiene: PASS")
+    return "\n".join(out), not errors
+
+
+if __name__ == "__main__":
+    args = [a for a in sys.argv[1:] if a != "--prs"]
+    if not 1 <= len(args) <= 2:
+        sys.exit(__doc__)
+    report, ok = check(git("rev-parse", args[0]).strip(), git("rev-parse", args[1] if len(args) > 1 else "HEAD").strip(),
+                       "--prs" in sys.argv)
+    print(report)
+    sys.exit(0 if ok else 1)

.bitlane/cpu-skip

@@ -0,0 +1,4 @@
+# pytest node ids the CPU test run deselects (bitlane control/build-engine.sh TEST=1): upstream tests in files our
+# stack touches that need a GPU. One per line, each with its reason above it.
+# upstream test, needs a CUDA stream ("current platform may not support current_stream")
+tests/v1/cudagraph/test_cudagraph_manager.py::test_full_capture_sets_graph_pool_id_before_cuda_graph

.bitlane/e2e.sh

@@ -0,0 +1,21 @@
+#!/usr/bin/env bash
+# usage: .bitlane/e2e.sh IMAGE NAME    In a workflow, after the OIDC role: bitlane control/e2e.sh on the dev environment
+# (never prod) with IMAGE and run-file suffix NAME, run on the builder (node/fork-ci.sh e2e, over SSM by builder.sh).
+# Step outputs for the report job: state (success = PASS, failure = FAIL, error = NOT RUN or no result) and desc
+# (<= 140 characters; a NOT RUN starts "NOT RUN:"). Exit 1 on FAIL or no result; NOT RUN exits 0 (the status says it).
+set -uo pipefail
+IMAGE=$1 NAME=$2
+.bitlane/builder.sh "/opt/bitlane/current/node/fork-ci.sh e2e $IMAGE $NAME" > out.txt 2>&1
+cat out.txt
+J=$(grep -E '^\{"result": ' out.txt | tail -1)
+R=$(jq -r '.result // empty' <<<"$J" 2>/dev/null) WHY=$(jq -r '.reason // empty' <<<"$J" 2>/dev/null)
+case $R in
+  PASS) S=success D="PASS $(jq -r '.run' <<<"$J")" ;;
+  FAIL) S=failure D="FAIL: $WHY" ;;
+  "NOT RUN") S=error D=$WHY ;;
+  *) S=error D="NOT RUN: no result from the builder: $(grep -m1 -E '::error::|usage:|ssm ' out.txt | cut -c1-80)" ;;
+esac
+D=${D//$'\n'/ }
+{ echo "state=$S"; echo "desc=${D:0:140}"; } >> "${GITHUB_OUTPUT:-/dev/stdout}"
+echo "bitlane/e2e on dev: $S, $D" >> "${GITHUB_STEP_SUMMARY:-/dev/null}"
+[ "$S" = success ] || [ "$R" = "NOT RUN" ]

.bitlane/test_check_stack.py

@@ -0,0 +1,80 @@
+#!/usr/bin/env python3
+"""Self-check of check-stack.py on a synthetic git repo: python3 .bitlane/test_check_stack.py (no network)."""
+import importlib.util, os, pathlib, subprocess, tempfile
+
+spec = importlib.util.spec_from_file_location("cs", pathlib.Path(__file__).with_name("check-stack.py"))
+cs = importlib.util.module_from_spec(spec)
+spec.loader.exec_module(cs)
+
+
+def sh(*a):
+    return subprocess.run(a, check=True, capture_output=True, text=True).stdout.strip()
+
+
+def commit(path, msg):
+    p = pathlib.Path(path)
+    p.parent.mkdir(parents=True, exist_ok=True)
+    p.write_text(p.read_text() + "x\n" if p.exists() else "x\n")
+    sh("git", "add", "-A")
+    sh("git", "commit", "-q", "-m", msg)
+    return sh("git", "rev-parse", "HEAD")
+
+
+def errors(base):
+    report, ok = cs.check(base, sh("git", "rev-parse", "HEAD"), prs=False)
+    return ok, report
+
+
+with tempfile.TemporaryDirectory() as d:
+    os.chdir(d)
+    sh("git", "init", "-q", "-b", "main")
+    sh("git", "config", "user.email", "t@t"), sh("git", "config", "user.name", "t")
+    base = commit("vllm/a.py", "upstream")
+    commit("vllm/b.py", "[bitlane] fix b\n\nUpstream: https://github.com/vllm-project/vllm/pull/1")
+    commit(".bitlane/x.py", "[bitlane] ci\n\nBitlane-only: our CI")
+    commit("tests/test_b.py", "[bitlane] test\n\nWhy: x\nUpstream: https://github.com/vllm-project/vllm/pull/2")
+    ok, report = errors(base)
+    assert ok and "Stack: 3 commits" in report and "Hygiene: PASS" in report, report
+
+    for path, msg, expect in [
+        ("vllm/c.py", "fix c\n\nBitlane-only: x", "subject must start"),
+        ("vllm/c.py", "[bitlane] fix c", "needs a trailer"),
+        ("vllm/c.py", "[bitlane] fix c\n\nUpstream: https://github.com/other/repo/pull/3", "must be a vllm-project"),
+        ("csrc/k.cu", "[bitlane] kernel\n\nBitlane-only: x", "not an overlay file"),
+        ("vllm/data.json", "[bitlane] data\n\nBitlane-only: x", "not an overlay file"),
+        ("csrc/k.cu", "[bitlane] kernel\n\nBitlane-only: x\nBinary-change: yes", "needs a full vLLM build"),
+        (".github/workflows/upstream.yml", "[bitlane] ci\n\nBitlane-only: x", "not an overlay file"),
+    ]:
+        top = sh("git", "rev-parse", "HEAD")
+        commit(path, msg)
+        ok, report = errors(base)
+        assert not ok and expect in report, (msg, report)
+        sh("git", "reset", "-q", "--hard", top)
+
+    top = sh("git", "rev-parse", "HEAD")  # a merge commit in the stack
+    sh("git", "checkout", "-q", "-b", "side", base)
+    commit("vllm/s.py", "[bitlane] side\n\nBitlane-only: x")
+    sh("git", "checkout", "-q", "main")
+    sh("git", "merge", "-q", "--no-ff", "-m", "[bitlane] merge\n\nBitlane-only: x", "side")
+    ok, report = errors(base)
+    assert not ok and "merge commit" in report, report
+    sh("git", "reset", "-q", "--hard", top)
+
+    # GitHub's PR merge commit: allowed, but the PR's own commits still pass or fail on their own (PR #3, 2026-10-20)
+    for side_msg, ok_want in [("[bitlane] side\n\nBitlane-only: x", True), ("side without trailer", False)]:
+        sh("git", "checkout", "-q", "-B", "side", base)
+        commit("vllm/s.py", side_msg)
+        sh("git", "checkout", "-q", "main")
+        sh("git", "merge", "-q", "--no-ff", "-m", "Merge pull request #3 from callgideon/side", "side")
+        ok, report = errors(base)
+        assert ok == ok_want, (side_msg, report)
+        sh("git", "reset", "-q", "--hard", top)
+
+    # merged upstream and already in the base: the patch should have dropped
+    cs.pr_state = lambda n: ("merged", base)
+    report, ok = cs.check(base, top, prs=True)
+    assert not ok and "is merged in the base" in report, report
+    cs.pr_state = lambda n: ("closed", None)
+    report, ok = cs.check(base, top, prs=True)
+    assert ok and "closed without merge" in report, report
+print("check-stack self-check: OK")

.bitlane/test_workflows.py

@@ -0,0 +1,83 @@
+#!/usr/bin/env python3
+"""Every bitlane workflow that sets commit statuses reports every stage, even when one fails:
+python3 .bitlane/test_workflows.py (stdlib only; run by the gate). Checked on our own files' layout:
+  - the first step of the first job posts state=pending (GitHub shows a running build, not nothing);
+  - a job named report has `if: always()` and needs every other job (a job added later cannot skip its status:
+    before 2026-10-20 a hygiene-gate failure posted no status at all);
+  - no other job writes a final state (one writer: only state=pending outside report)."""
+import pathlib, re
+
+JOB = re.compile(r"^  ([A-Za-z0-9_-]+):")
+
+
+def jobs(text):
+    """{job: [its lines]} of the top-level `jobs:` map, in order."""
+    out, cur, inside = {}, None, False
+    for line in text.splitlines():
+        if not line.startswith(" ") and line.strip():
+            inside = line.startswith("jobs:")
+            continue
+        if inside and (m := JOB.match(line)):
+            cur = out.setdefault(m[1], [])
+        elif inside and cur is not None:
+            cur.append(line)
+    return out
+
+
+def first_step(lines):
+    """The lines of a job's first step: from its first `- ` to the next `- ` at the same indent."""
+    starts = [i for i, l in enumerate(lines) if l.lstrip().startswith("- ")]
+    if not starts:
+        return ""
+    indent = len(lines[starts[0]]) - len(lines[starts[0]].lstrip())
+    end = next((i for i in starts[1:] if len(lines[i]) - len(lines[i].lstrip()) == indent), len(lines))
+    return "\n".join(lines[starts[0]:end])
+
+
+def problems(text):
+    j = jobs(text)
+    if not any("/statuses/" in l for lines in j.values() for l in lines):
+        return []  # sets no status (bitlane-sync: its build job's workflow does)
+    bad = []
+    if "state=pending" not in first_step(next(iter(j.values()))):
+        bad.append("the first step of the first job does not post state=pending")
+    rep = j.get("report")
+    if rep is None:
+        return bad + ["no report job"]
+    if not any(l.strip() == "if: always()" for l in rep):
+        bad.append("report has no `if: always()`")
+    needs = next((l for l in rep if l.strip().startswith("needs:")), "")
+    missing = [n for n in j if n != "report" and not re.search(rf"[\[\s,]{re.escape(n)}[\],\s]", needs + " ")]
+    if missing:
+        bad.append(f"report does not need {missing}")
+    for name, lines in j.items():
+        bad += [f"{name} writes a final status: {l.strip()[:60]}" for l in lines
+                if name != "report" and "/statuses/" in l and "state=pending" not in l]
+    return bad
+
+
+GOOD = """on: push
+jobs:
+  gate:
+    steps:
+      - run: gh api repos/x/statuses/$SHA -f state=pending
+      - run: true
+  build:
+    needs: gate
+  report:
+    needs: [gate, build]
+    if: always()
+    steps:
+      - run: gh api repos/x/statuses/$SHA -f state=success
+"""
+assert problems(GOOD) == [], problems(GOOD)
+assert problems(GOOD.replace("    if: always()\n", "")) == ["report has no `if: always()`"]
+assert problems(GOOD.replace("[gate, build]", "[gate]")) == ["report does not need ['build']"]
+assert problems(GOOD.replace("  build:\n    needs: gate\n", "  build:\n    steps:\n      - run: gh api repos/x/statuses/$SHA -f state=failure\n"))
+assert "the first step of the first job does not post state=pending" in problems(GOOD.replace("state=pending", "state=x"))
+
+flows = sorted(pathlib.Path(__file__).parent.parent.glob(".github/workflows/bitlane-*.yml"))
+assert flows, "no bitlane workflows found"
+for f in flows:
+    assert not (p := problems(f.read_text())), f"{f.name}: {p}"
+print(f"workflow status check: OK ({', '.join(f.name for f in flows)})")