Repository navigation
[do-not-mirror][do-not-merge] chore(fork): document the SSH stall that blocks fetches and forkctl - #25
Closed
jdsika wants to merge 7 commits into
Closed
[do-not-mirror][do-not-merge] chore(fork): document the SSH stall that blocks fetches and forkctl#25jdsika wants to merge 7 commits into
jdsika wants to merge 7 commits into
Conversation
ASCS-eV/PufferDrive is consumed as a git submodule internally while feeding
features back to Emerge-Lab/PufferDrive. This commit carries everything that
exists only in the fork, and is the single place fork-only content lives.
Branch model:
3.0 verbatim, fast-forward-only mirror of upstream/3.0
integration/3.0 default branch; this commit plus a linear stack of
single-commit features; what internal consumers pin
feature/<slug> one feature, exactly one commit
mirror/<slug> cherry-picked onto pure upstream/3.0 for upstream PRs
integration/3.0 is the default branch because GitHub reads the PR template,
the contributing guidelines, the agent instructions and scheduled workflows
only from the default branch, and none of those files may exist on 3.0
without destroying the mirror. A clone checks out the default branch, so the
copy of the instructions here is the process as far as every agent and every
submodule consumer is concerned; a rule that lives only in an open PR has no
effect.
Nothing reaches integration/3.0 until three gates pass:
1. CI green on the final commit.
2. Adversarial review by someone other than the author, with the findings
written down -- including the probes that found nothing.
3. Upstream-readiness proven rather than asserted: the commit cherry-picks
onto a branch cut from pure upstream/3.0 and produces an upstream-clean
diff. We stack only commits we could contribute today.
chore(fork): commits are exempt from gate 3, since fork-only infrastructure
can never be upstream-ready. They carry two orthogonal markers: do-not-mirror
(must never reach upstream) and do-not-merge (the merge button is never
pressed -- merging would create a second chore(fork): commit and break the
single-commit invariant that every sync asserts). Such a PR is folded into
this commit by fixup and closed unmerged.
Contents:
- .github/copilot-instructions.md: normative process for coding agents
- CONTRIBUTING.md: human orientation, same rules
- .github/pull_request_template.md: testing and stack-hygiene gates
- .github/workflows/sync-mirror.yml: fast-forward-only mirror sync that
refuses any non-fast-forward instead of rewriting the upstream base
- AGENTS.md / CLAUDE.md: fenced pointer so agents find the fork process
without colliding with upstream-owned content
- ci.yml / install.yml: run CI for PRs targeting integration/3.0, which
upstream's branch filters would otherwise skip
A standing draft PR from integration/3.0 into 3.0 gives a continuous CI
verdict on the combined stack; it must never be merged.
Everything here is fork-only and must never be cherry-picked upstream.
The Linux CI jobs fail while installing the package:
[Errno 122] Disk quota exceeded
Errno 122 is EDQUOT, hit while unpacking the CUDA torch stack that
`pip install -e .` resolves by default. torch alone is 554.6 MB and the
accompanying nvidia-* wheels add another ~2.4 GB, which no longer fits
the runner's quota. The failure occurs during "Installing build
dependencies", i.e. the isolated PEP 517 build environment is already
enough to exceed it on its own.
The trigger is a runner image change, not a code change:
* upstream 11_bernhard_dev, 2026-10-20, Image: ubuntu-24.04 -> success
* same workflows, 2026-10-23, Image: ubuntu-26.04 -> failure
Both resolve an identical wheel set (torch 2.14.1, 554.6 MB). The
`ubuntu-latest` label began migrating to Ubuntu 26 on 2026-10-19
(actions/runner-images#14748), between those two runs. Both workflows
already carry "Free up disk space" steps, so these jobs were running
close to the limit before the migration.
Fix: install CPU-only torch from download.pytorch.org, then build with
--no-build-isolation so the build reuses it instead of resolving torch
a second time. --no-build-isolation needs the build dependencies present
up front, hence the explicit setuptools/wheel/numpy install; the
`setuptools<81` bound matches the pin already in install_requires.
This loses no coverage: BUILD_CUDA_EXT keys off CUDA_HOME/ROCM_HOME,
which is unset on these runners, so the CUDA sources were never compiled
here. tests/smoke_tests/Dockerfile already installs torch this way.
macOS keeps the plain `pip install -e .` unchanged: its PyPI wheels are
already CPU-only, and leaving it alone keeps the default PEP 517
build-isolation path under test somewhere in the matrix.
The shipped puffer_drive.yaml sets policy.fused_slot_encoder=true, and DriveBackbone raises ImportError when that is set without triton. Two CI jobs build a policy straight from the shipped config, so Unit Tests and Notebook Execution have been failing on every pull request: ImportError: fused_slot_encoder=true requires triton The smoke and eval suites already pin the flag off for exactly this reason; these two call sites were simply missed. test_action_selection only exercises the discrete-to-continuous action table, which the fused kernel has no part in, so it pins the flag off outright. The inference notebook keeps the kernel whenever it has a CUDA device and drops it otherwise, which is also what a reader running the notebook on a laptop needs. Neither change touches the training path or the kernel itself: with triton and a GPU present, both call sites behave exactly as before.
The two instruction files are byte-identical except for one line, and that line is a contradiction rather than a Claude-specific tweak. AGENTS.md asked for comments that explain invariants; CLAUDE.md banned them by default with a hard one-line cap and an explicit list of banned forms. Agents load one file or the other depending on the tool, so the same codebase was being written to two different standards, and neither copy said the other existed. This adopts the stricter rule in both, because it is the one written for this codebase and the one the recent code follows.
Selecting the shipped carla_cosim benchmark crashed with UnboundLocalError: the cosim branch of load_benchmark_config appended to resolved_benchmarks, which is not assigned until after the loop it sits in. The parsed cosim entries now accumulate in their own list and are appended to the normalized replay benchmarks, so a selection may mix both kinds. The bug is the kind a linter finds for free, so the ruff hook that has been commented out since it was added is enabled, scoped to exactly that class of defect: names that do not resolve and imports that are never used. The repo has 104 other violations under ruff's full default set, most of them E402 import placement, and fixing those is neither this change nor obviously desirable; a deliberately narrow select keeps the hook green today and lets the set widen later alongside the fixes a wider set would demand. Enabling it removed eight genuinely unused imports and required noqa markers on the four import-availability probes that exist precisely to be unused. tests/unit_tests/test_terminate_on_goal.py called pytest.main without importing pytest, so its __main__ entry point had never worked.
A README or docstring change currently runs the full matrix -- unit, C, notebooks, a 30-minute Docker smoke train and the perf run -- none of which can observe a Markdown edit. On a fork whose process documentation changes often this is the single largest source of runner time, and it is pure waste. A changes job diffs the PR against the merge base and votes code=false only when every changed path is recognised documentation (*.md, docs/, .github/ISSUE_TEMPLATE/). Anything unrecognised, and every push build, votes rue, so the failure direction is always 'run the tests'. The five heavy jobs gain eeds: changes and an if:. Job-level if: rather than workflow-level paths-ignore is deliberate: a workflow skipped by path filtering leaves its required checks pending forever and blocks the merge, whereas a skipped job is reported to branch protection as passing. No third-party action is used; the detection is five lines of git.
jdsika
added
do-not-mirror
Every documented workflow opens with git fetch origin && git fetch upstream, and forkctl status, check-view and delete-mirror reach the network themselves. When the SSH path to GitHub is blocked these block indefinitely instead of failing, so the stall reads as a hung tool. It is easy to hit on Windows, where the make targets push people into WSL and WSL often cannot reach GitHub over SSH even though Windows can. Add a troubleshooting section naming the symptom, the one-line test that tells the two sides apart, and which subcommands sit on each side of the split.
jdsika
force-pushed
the
chore/wsl-network-note
branch
from
November 12, 2026 09:17
1ccb477 to
9aaccf3
Compare
jdsika
changed the title
Author
Review — Track B (independent reviewer, fresh context)Verdict: request changes — one blocking factual error; the section described behaviour Track B confirmations
Gate 1 — all required checks green on Blocking — the opening paragraph
Three inaccuracies, each checked against
What genuinely blocks on SSH is the Non-blocking
Checked and fine
Once the opening paragraph describes what |
Author
|
Blocking finding fixed in 9aaccf3, and I confirmed the reviewer's reading of the source first: The section now says that the stall comes from the mandated The tooling suggestion is a good one and deliberately not taken here: a |
Author
Re-review — Track B (independent reviewer, fresh context) —
|
jdsika
force-pushed
the
integration/3.0
branch
from
November 12, 2026 09:24
351531d to
aacc53d
Compare
Author
|
Folded into the base
|
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Adds a troubleshooting section to
CONTRIBUTING.mdfor the case where aforkctlcommand hangs with no output at all.Why
forkctl doctor,statusandmirrorcontact GitHub before they print their first line. When that call blocks, the tool looks hung rather than failed, and there is nothing on screen to diagnose from.This is easy to hit on Windows. The
maketargets need a POSIX shell, so the natural habit is to run everything inside WSL — but WSL frequently cannot reach GitHub over SSH even on a machine where Windows reaches it in a couple of seconds, andgit fetch/git ls-remotethen block indefinitely instead of timing out. Encountered exactly this while runningforkctl statusduring the last round of stack work.Notes
The section gives the symptom, a one-line test that tells the two sides apart (
git ls-remote origin -h refs/heads/integration/3.0, run from each), and the split that works: network-touching commands from Windows, offline checks (check-commit,check-stack,track) andmakefrom WSL. HTTPS inside WSL is mentioned as the single-shell alternative.No behaviour change — documentation only.
Validation
forkctl check-commit --chore— PASS (one commit, well-formedchore(fork):subject, markers intact, track B)pre-commit run --all-files— passed (all 5 hooks)The simulator suites were not run and are not applicable: the diff is one Markdown file.
Upstream readiness
Not applicable —
chore(fork):, exempt from Gate 2 and never mirrored.Disposition
Per
.github/copilot-instructions.md§3.3 this is a review vehicle, not a delivery mechanism: once it is green and reviewed it gets folded into the basechore(fork):commit and closed unmerged.