The free-port probe bound without SO_REUSEADDR while the board's own
ThreadingHTTPServer sets it, so the socket a just-stopped board left in
TIME_WAIT read as "taken by something else": a routine stop/start walked
the board to the next port and wrote that over the user's BOARD_PORT pin.
The probe now binds exactly as the server does, which is the whole race.
Behind it, a held port gets a few seconds (BOARD_PORT_WAIT, 5s) to clear
before the walk, re-asking is_our_board each beat — a restart races its
own predecessor far more often than a stranger takes the port. Walking
off a pinned port still persists, since the hooks and agents read
BOARD_PORT and must reach the live board, but it now says so in full:
the right file (manager/local/.env, not manager/.env), old → new, and
how to reclaim the pin.
Tested end to end against a scratch host with a stub board.py, over real
sockets: a genuine TIME_WAIT remnant, a listener that lets go mid-wait,
a listener that does not, and our own board answering.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
The third setup question wanted an answer about a repo the person may
have just cloned, thirty seconds in, before anything had explained why
the board needed one. The file that names a project's ecosystem usually
names its runner too, so it is read off the project: package.json → npm
test, Cargo.toml → cargo test, go.mod → go test ./..., a
pyproject/setup.py/tests/ → python3 -m unittest.
Nothing recognisable writes BOARD_AGENT_COMMANDS empty rather than the
example's Python default, which would be quietly wrong in most repos —
and a wrong prefix denies an agent exactly the way an empty one does, so
absent beats wrong here.
Two details the first attempt got wrong, both now covered:
- Detection runs *before* the questions. Placed after them, a Ctrl-D
part-way through skipped it and left the example's default.
- "Keep what the project already said" reads the existing .env, not the
example-seeded defaults dict — which already carries the example's
answer, so every first run looked like it had one and detection never
ran.
The landing page's terminal, README.md and AGENTS.md follow: two
questions now, and AGENTS.md documents the detection table.
A project could run bench for months without a manager/local/.env:
everything fell back to core/.env.example, so the two settings that
change what bench is — claim-on-move and syncing through origin/main —
were invisible to anyone who had not read that file.
install.py now writes it on a first run. It asks three questions no
default can be right about (solo or team, which agent adapter, the
project's test command) and writes core/.env.example with the answers
substituted into their lines, comments and all keys intact — so the
written file is where the project reads what else it can change.
- Runs after first_boot_clean: .env is one of the two things the
first-boot guard reads, so writing it earlier would skip the clean.
- Never asks without a terminal on stdin. install.py sits on the path
of start.sh, update.sh and every hook, so no TTY prints one line and
carries on rather than blocking a board start on an invisible prompt.
--dry-run reports the questions and writes nothing.
- An existing .env is never touched; --setup is the only way back to
the questions, pre-filling from the current file and rewriting it in
place, so start.sh's fallback BOARD_PORT line survives.
- Bare Enter takes every default (the result is the example verbatim,
i.e. today's behaviour exactly); Ctrl-D skips the rest.
start.sh needed no change — it already calls install.py before the port
dance, which is the right order. Tests drive the interactive runs over a
real pty and the non-interactive ones with /dev/null on stdin.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
The first-boot guard is now its own predicate gating both the clean and
the local/state/ stamp, so a disarmed run (pre-existing local/.env, or
self-hosted) touches nothing at all — before, it still created the stamp
directory on any vendored run. Removal unlinks symlinks instead of
following them into rmtree. Tests filter BOARD_* out of the subprocess
environment, assert the stamp stays absent when .env disarms the guard,
and cover the symlink case.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
A vendored clone of bench arrives carrying bench's own task cards, plans
and reference documents, so a new user's first board opened pre-loaded
with our backlog. install.py now detects first boot — a vendored install
(project root != manager root) whose manager/local/ has never been
populated (no .env, no state/) — and only then clears the stage
directories, tasks/archive/, plans/ and reference/, keeping
task-template.md and the .gitkeep files and printing every removal.
--dry-run lists instead of removing. After cleaning it stamps
manager/local/state/, so the guard is permanently false on every later
run even if the adapter wire fails, and a host's own cards are never
touched. Self-hosted repos (bench itself, including fresh dev clones)
are never cleaned: their tasks/ is the repo's history.
Covered end-to-end in tests/test_install_first_boot.py by running
install.py as a subprocess against scratch host layouts; README notes
the first-boot behaviour under "Install into a repo".
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
