docs: read the log before fixing a bug whose acceptance is a count we log #121

Merged

jlxq0 merged 1 commit from read-the-log into main

2026-08-25 13:24:32 +00:00

jlxq0 commented

2026-08-25 13:06:45 +00:00

Owner

Doc-only. One Known Pitfalls entry, from #120.

#120 reported one channel event delivered three times and named stale peer accumulation as the cause, reasoning correctly about code that really does write once per live peer. It had not happened: every channel: pushed line in the pod's life read live=1 written=1, the reported event appeared exactly once, and the only peer-liveness line in the pod's history said total: 1, closed: 1. The duplication was three byte-identical copies of the same <channel> tag in the reporting session's own transcript, the first 33ms behind the single server push and the other two with no server write behind them.

The issue's own acceptance criterion was "assert notify returns 1", and the running system already answered 1 — in one kubectl logs.

The entry records the habit and the specific command, because the fields that make it answerable (live and written on every push) are not obvious from the code.

What the check was worth is not the hour saved. The recommended fix, de-duplicating on event id per mxid at the send, would have broken two sessions authenticated as one identity — a supported shape — while suppressing nothing, because there was no second notify call to suppress. A wrong cause does not produce a harmless fix; it produces a fix aimed at nothing with all of its own side effects intact. That is the part worth writing down.

No code change, no test change. AGENTS.md only.

Doc-only. One `Known Pitfalls` entry, from #120. #120 reported one channel event delivered three times and named stale peer accumulation as the cause, reasoning correctly about code that really does write once per live peer. It had not happened: every `channel: pushed` line in the pod's life read `live=1 written=1`, the reported event appeared exactly once, and the only peer-liveness line in the pod's history said `total: 1, closed: 1`. The duplication was three byte-identical copies of the same `<channel>` tag in the reporting session's own transcript, the first 33ms behind the single server push and the other two with no server write behind them. The issue's own acceptance criterion was "assert `notify` returns 1", and the running system already answered 1 — in one `kubectl logs`. The entry records the habit and the specific command, because the fields that make it answerable (`live` and `written` on every push) are not obvious from the code. **What the check was worth is not the hour saved.** The recommended fix, de-duplicating on event id per mxid at the send, would have broken two sessions authenticated as one identity — a supported shape — while suppressing nothing, because there was no second `notify` call to suppress. A wrong cause does not produce a harmless fix; it produces a fix aimed at nothing with all of its own side effects intact. That is the part worth writing down. No code change, no test change. `AGENTS.md` only.

jlxq0 added 1 commit

2026-08-25 13:06:45 +00:00

docs: read the log before fixing a bug whose acceptance is a count we log

CI / cargo (pull_request) Successful in 1m27s

Details

CI / docker (pull_request) Has been skipped

Details

6df9c6ac60

#120 reported one channel event delivered three times and named stale peer
accumulation as the cause. The reasoning was sound about the code — `notify`
does write once per live peer, and a reconnecting client does get a new
session_key. It had not happened. Every `channel: pushed` line in the pod's
life read `live=1 written=1`, the reported event appeared exactly once, and
the only peer-liveness line said `total: 1, closed: 1`.

The issue's own acceptance criterion was "assert `notify` returns 1". The
running system already answered 1, in one `kubectl logs`.

What the check was worth is not the hour saved. The recommended fix —
de-duplicate on event id per mxid at the send — would have broken two sessions
authenticated as one identity, which is a supported shape, while suppressing
nothing, because there was no second `notify` call to suppress. A wrong cause
does not produce a harmless fix; it produces a fix aimed at nothing, with all
of its own side effects intact.

The duplication was client-side: three byte-identical copies of the same
`<channel>` tag in the session's own transcript, the first 33ms behind the
single server push and the other two with no server write behind them.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0176noPigX2cwByDtRcafzyi

jlxq0 merged commit aab1b22642 into main

2026-08-25 13:24:32 +00:00

jlxq0 referenced this pull request from a commit

2026-08-25 13:24:32 +00:00

Merge pull request 'docs: read the log before fixing a bug whose acceptance is a count we log' (#121) from read-the-log into main

jlxq0 referenced this pull request

2026-08-26 09:16:34 +00:00

Relay permission prompts through the Matrix channel #109