From ae9f10e3d03b2dcd6388ceb3c0da564c99b9b978 Mon Sep 17 00:00:00 2001 From: istos Date: Thu, 30 Jul 2026 14:25:14 +0200 Subject: [PATCH] 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 --- .../27-update-offers-to-commit-itself.md | 78 +++++++++++++++++++ .../backlog/28-a-pinned-port-stays-pinned.md | 78 +++++++++++++++++++ 2 files changed, 156 insertions(+) create mode 100644 tasks/backlog/27-update-offers-to-commit-itself.md create mode 100644 tasks/backlog/28-a-pinned-port-stays-pinned.md diff --git a/tasks/backlog/27-update-offers-to-commit-itself.md b/tasks/backlog/27-update-offers-to-commit-itself.md new file mode 100644 index 0000000..3350708 --- /dev/null +++ b/tasks/backlog/27-update-offers-to-commit-itself.md @@ -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 → ()` — 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. diff --git a/tasks/backlog/28-a-pinned-port-stays-pinned.md b/tasks/backlog/28-a-pinned-port-stays-pinned.md new file mode 100644 index 0000000..5ae1221 --- /dev/null +++ b/tasks/backlog/28-a-pinned-port-stays-pinned.md @@ -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.