fix(kernel): release an event claim when a panic unwinds past it (#173)

[kjgbot]

Closes #173, deferred from #171 on purpose so it would get its own review rather than riding under an exactly-once fix.

The gap

claim_event tells every concurrent delivery that an event is a duplicate on the strength of a claim row, so whoever takes that claim owes the event either a registered run or the claim back.

The Err path handed it back. A panic did not — an unwind passes every match arm, and a claim leaked that way survived for the life of the boot: each later delivery answered "duplicate" by the same-boot rule, with no run to carry the event. Only a restart cleared it, because the claim then belonged to a previous boot and was repaired.

The shape of the fix

A Drop guard covers the exit that has no ? to take. The ordinary Err path still releases explicitly and propagates — a release that fails there strands the claim while later deliveries are told "deduped" with nothing behind them, and that is a runtime failure the caller must see, not one to report and swallow. Release happens before disarming, so a failing release leaves the guard armed and the unwind still attempts best-effort cleanup on the way out.

This is the crate's first Drop impl, so the trade is stated in the code: it cannot return an error or be ?-ed, so a failed release there is reported via eprintln! — the convention already used in server/liveness.rs — and swallowed, leaving the event exactly where a leak would have left it, no worse. It must not panic: panicking in Drop during an unwind aborts the process, turning a stranded event into a dead daemon.

Evidence

Four tests, and the mutation that gates them. Making Drop a no-op (if true || !self.armed) fails exactly the two that should fail — an_armed_guard_releases_the_claim_when_dropped and a_panic_between_claim_and_register_still_releases — while a_disarmed_guard_leaves_the_claim_alone and a_guard_only_releases_its_own_run keep passing. So they pin the release without also pinning its absence.

The panic case runs through catch_unwind and asserts the panic actually happened, so it cannot pass by never unwinding.

Full transcript with runnable commands and sha256 before/mutated/restored is in the commit message. Kernel workspace: 156 passed, 0 failed, no warnings.

Known boundary, stated rather than glossed

The panic test constructs ClaimGuard directly rather than injecting a panic through submit_event, so it pins the guard's contract, not its placement. Placement is pinned by reading — armed immediately after the claim, disarmed only after spawn_claimed_run returns Ok — and injecting a panic into production code would need a test-only seam in the very span this change exists to protect.

Review history

Four drafts were rejected, each fairly, and one was about the code: routing the ordinary Err path through Drop silently downgraded a propagating release to best-effort. That was a real regression the review caught, not a wording problem. The other three were evidence claims — describing output instead of showing it, abbreviating cargo's test paths while calling the block literal, and printing commands without the cd kernel they were actually run in.

🤖 Generated with Claude Code

https://claude.ai/code/session_01FtQSAcGDta5VH9xiZFT4sR

[coderabbitai]

Warning

Review limit reached

Next included review available in 12 minutes.

Check out review usage here.

View limit details

Limit details: You’ve used the included review currently available.

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

Learn how review limits work.

Review configuration:

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Free

Run ID: afeb0930-a6fc-4ca4-9a93-b6e421b7aee0

📥 Commits

Reviewing files that changed from the base of the PR and between a93a6f7 and bc41f9e.

📒 Files selected for processing (1)

• kernel/relayflowd/src/engine/wake.rs

---

Note

🎁 Summarized by CodeRabbit Free

Your organization is on the Free plan. CodeRabbit will generate a high-level summary and a walkthrough for each pull request. For a comprehensive line-by-line review, please upgrade your subscription to CodeRabbit Essentials by visiting https://app.coderabbit.ai/settings/billing.

_{Comment @coderabbitai help to get the list of available commands.}