randomparity / randomparity/kdive

Durable reset-retry for a dead-worker gdbstub transport reset

Open
#221 2 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

area:debug effort:M priority:P3 provider:remote-libvirt risk:daytime-only status:blocked type:feature
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_reset signal 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_reset column 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_reset signal (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 is detached.
  • 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 live session 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 a scripts/m2_portability_gate.py allowlist 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), spec docs/superpowers/specs/2026-06-09-dead-worker-gdbstub-reset-design.md (§Ordering, "Out of scope").

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.