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:
@@ -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.
|
||||
Reference in New Issue
Block a user