randomparity / randomparity/kdive
Durable reset-retry for a dead-worker gdbstub transport reset
Nobody has claimed this yet.
- Dominant language
- Python
- Stars
- 0
- Forks
- 0
- Avg merge
- 1h 26m
- Merged PRs (30d)
- 307
Description
Follow-up to #216 (PR #220, ADR-0086), which added the reconciler reset that frees a dead worker's single-client gdbstub when it detaches a stale live DebugSession.
Context
ADR-0086 made the transport reset best-effort: the detach commits first, then the reset is attempted once. A transient reset failure (QEMU host briefly partitioned, the qemu+tls monitor unreachable for that pass) is not retried — the session is already detached and will not re-surface in the next dead-session sweep, so the port can stay wedged until the next attach forces a transport_conflict.
This was an accepted, deliberate scope cut in ADR-0086:
No durable reset-retry. Retrying a failed reset would need a new
needs_transport_resetsignal swept independently of session state; deliberately out of scope for M2 (no speculative column). Revisit only if operational data shows transient reset failures are common.
And in Considered & rejected:
Durable reset-retry via a
needs_transport_resetcolumn swept independently. Rejected for M2: speculative complexity for a failure mode (transient reset failure) that is no worse than today's behavior. Revisit with operational evidence.
The current fallback is a strict no-regression (it is exactly the pre-#216 behavior), so this is an enhancement, not a defect.
Task (when justified by operational evidence)
Make a failed transport reset durably retryable, decoupled from session state:
- Add a
needs_transport_resetsignal (e.g. a column or a small work row) set when the reset is attempted and cleared when it succeeds, so the reconciler re-attempts it on a later pass instead of losing it once the row isdetached. - Bound the retries (a max-attempt / age cap) so a permanently-unreachable host does not retry forever.
- Preserve the existing live-holder guard (do not re-arm a stub a
livesession legitimately holds) and the best-effort, sweep-isolated error handling. - This re-touches the gate-protected core (
reconciler/), so it needs its own ADR amending ADR-0086 and ascripts/m2_portability_gate.pyallowlist review in the same PR.
Acceptance
- A transient reset failure is retried on a subsequent reconciler pass and eventually frees the port once the host is reachable again, without re-marking the session
live. - Retries are bounded; a permanently-unreachable host stops retrying after the cap and is observable in logs.
- The live-holder guard still prevents evicting a legitimately re-attached debugger.
Notes
- Gate this work on operational signal that transient reset failures actually occur — per ADR-0086, do not build it speculatively.
- Reference: ADR-0086 (
docs/adr/0086-dead-worker-gdbstub-reconciler-reset.md), specdocs/superpowers/specs/2026-06-09-dead-worker-gdbstub-reset-design.md(§Ordering, "Out of scope").
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
First check for operational evidence of transient reset failures, then read docs/adr/0086-dead-worker-gdbstub-reconciler-reset.md and docs/superpowers/specs/2026-06-09-dead-worker-gdbstub-reset-design.md, especially Ordering and “Out of scope.” Inspect the reconciler/ reset path and scripts/m2_portability_gate.py before proposing the ADR amendment. Done means bounded retries recover reachable hosts, preserve the live-holder guard, and log exhausted retries.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- backend, infrastructure
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100