Cards 27, 28: update offers to commit itself; a pinned port stays pinned

Both from the first downstream 0.2 update report: the vendored diff
left as homework in a clean-main workflow, and the TIME_WAIT port hop
that rewrote an explicit BOARD_PORT pin.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
istos
2026-07-30 14:25:14 +02:00
co-authored by Claude Fable 5
parent a5dd0ac565
commit ae9f10e3d0
2 changed files with 156 additions and 0 deletions
@@ -0,0 +1,78 @@
# 27 — update.sh offers to commit the update it just made
**Status:** Backlog
**Priority:** Medium — every update leaves doctrine-mandated homework in the host's tree; the first 0.2 field report asked for exactly this
**Type:** Feature
The doctrine says commit `.task-manager/` into the host repo, so every
update strands a large vendored diff (0.1→0.2: 18 files, +1049/−275)
in the working tree for someone to stage by hand — on a branch teams
try to keep clean. update.sh knows exactly which paths it replaced, so
it can stage exactly those and commit them cleanly — offered, never
imposed.
## Context
- Field report (first 0.2 update, cicero-pas install): update clean,
promise held (only core-owned files touched), but the tree was left
holding the vendor diff *alongside the host's own uncommitted card
move* — and the human had to know to separate them.
- The separation is mechanical: the artifact's `release-manifest`
names every path the update may write (`tree manager/core` + the
`copy` list). Stage precisely those; the host's own dirt (card
moves, local edits) stays untouched.
- Interaction with task 19's piggyback guard: on a synced board, a
non-`board:` commit on main stalls publishing with a stray-commit
note. A manifest-scoped update commit is mechanical and reproducible
from its release tag — it should count as publishable.
**Affected areas:** `update.sh`, `sync.py` (`_stray` learns the
`bench: ` prefix), `core/.env.example`, README's update section.
## What to build
- After a successful update, update.sh stages the manifest's paths
and either commits — message
`bench: core <old> → <new> (<tag>)` — or prints the exact command
it would run. Committing requires opt-in: `--commit` flag or
`BENCH_UPDATE_COMMIT=1` in local/.env; default prints.
- Nothing outside the manifest's paths is ever staged — proven
against a tree that also carries an unrelated task move and a
dirty file elsewhere in the host repo.
- `sync.py`'s publish guard accepts `bench: ` commits as pushable
alongside `board: ` ones; everything else still stalls the push.
- README/update output: one line telling users with sync on that the
update commit will publish on the next beat.
**Out of scope** — tempting neighbours left alone:
- Auto-pushing the commit from update.sh itself (sync's job where
enabled; the human's otherwise).
- Committing on the bench repo's own self-hosted layout — dev clones
update via git, and update.sh's no-release path already says so.
## Acceptance
- [ ] Given a host tree with an uncommitted card move plus the fresh
update, when `update.sh --commit` runs, then one `bench: `
commit contains exactly the manifest paths and the card move
remains uncommitted.
- [ ] Without the opt-in, nothing is committed and the printed
command, run verbatim, produces the identical commit.
- [ ] With `BOARD_SYNC=1`, the update commit publishes on the next
beat; a genuinely stray commit still stalls with the named
note.
- [ ] Edge case — update applied but commit refused (e.g. the host's
git identity unset): the update itself stays intact and the
failure names what to fix; no partial staging left behind.
## Open questions
- None.
## Notes
Requested from the field (2026-07-30) after the first 0.2 update:
"main is typically a clean branch — should we offer to commit as part
of an install update?" Yes to offering, no to imposing: the manifest
is what turns the offer from "commit -A and hope" into surgery.
@@ -0,0 +1,78 @@
# 28 — A pinned port stays pinned: fix the TIME_WAIT hop that rewrites .env
**Status:** Backlog
**Priority:** Medium — a routine stop/start silently moves a deliberately pinned port; found by the first downstream install within hours of 0.2
**Type:** Bug
Restarting the board can hop it off its own pinned port: start.sh's
free-port probe binds without `SO_REUSEADDR`, so the just-stopped
board's socket in TIME_WAIT reads as "taken by something else", the
script walks to the next port and — worse — persists the new number
over the user's explicit `BOARD_PORT` pin in `manager/local/.env`.
The user pinned 26074; one routine restart later they were on 26075
with their own setting overwritten. The probe also disagrees with the
server it probes for: `ThreadingHTTPServer` sets `allow_reuse_address`,
so the board itself could have bound the port the probe called busy.
## Context
- Field report (cicero-pas, first 0.2 restart): stop → start hopped
26074 → 26075 with nothing actually listening; the hop message also
misnames the file it rewrote ("manager/.env" — it is
`manager/local/.env`).
- `start.sh` `is_free()`: a plain `socket.bind()` probe — fails on
TIME_WAIT remnants that the actual server (reuse-address) would
bind over fine. False "busy" → unnecessary hop.
- The persist behaviour exists for the *genuinely occupied* case, so
hooks and agents follow the board (right and documented). The bug
is hopping when nothing is there, and clobbering an explicit pin
for a transient condition.
**Affected areas:** `start.sh` only (probe, retry, persist policy,
message wording).
## What to build
- Probe with `SO_REUSEADDR`, matching the server's own bind
semantics — TIME_WAIT stops reading as occupied. This alone
dissolves the reported race.
- Belt: if the pinned port still reads busy, distinguish "our own
board" (existing is_our_board check answers) from "foreign": for
foreign, briefly retry (a few seconds) before walking — restarts
race their predecessor's shutdown more often than squatters exist.
- Persist policy: walking off a port the user explicitly pinned in
local/.env still persists (hooks must follow the live board — the
alternative is events into a dead port), but say it plainly: name
the file correctly, state old → new, and print how to reclaim the
pin. The message currently misnames the file; fix that regardless.
**Out of scope** — tempting neighbours left alone:
- A separate runtime port file with config-precedence changes — more
moving parts than the bug warrants once the probe stops lying.
- Port management for drives/agents (they already read the same env).
## Acceptance
- [ ] Given a board stopped and immediately restarted on its pinned
port, then it comes back on the same port with .env untouched —
the TIME_WAIT case, tested with a real socket left in that
state.
- [ ] Given the pinned port genuinely held by a foreign process, then
start.sh retries briefly, then walks and persists, and the
message names `manager/local/.env`, the old and new ports, and
the reclaim step.
- [ ] `is_our_board` on the pinned port still short-circuits to
"reopen the browser" — no probe, no hop.
## Open questions
- None.
## Notes
Diagnosis arrived nearly complete in the downstream report (TIME_WAIT
suspicion, the clobbered pin, the misnamed file) — second field
report, second time the reporter's analysis survives into the card
nearly verbatim. The probe/server asymmetry (`allow_reuse_address` on
one side only) is the one-line root cause.